export declare const dispatchAtlasLayoutUpdateEvent: () => void; export declare function initLayout(): void; /** * Persists `layout-*` class state per `storageKey`. Instance is live on return. * * A subscriber fires when its watched class enters the requested state; if the * class is already in that state, the callback is queued for an initial replay * once `deferCallbacksUntil` resolves. * * `data-layout-restored="true"` is always set after the initial flush — even on * setup or callback failure — so CSS gated on it cannot leave content hidden. * Setup errors are re-thrown. * * View transitions coalesce same-microtask callbacks and skip while another is * animating, avoiding `InvalidStateError` aborts. * * ### SPA integration * * Create the instance once at boot. Pair `suspend()` with `resume()` around * navigations that mutate ``'s class list: * * ```ts * const layoutState = createLayoutState({ * storageKey: () => currentRoute.layoutKey, // getter, re-read on resume * excludesKey: () => currentRoute.excludesKey, * excludes: () => currentRoute.excludes * }); * * router.on('beforeNavigate', () => layoutState.suspend()); * router.on('afterNavigate', () => layoutState.resume()); * ``` * * Subscribers registered once at boot stay live across every navigation — no * re-registration required. `resume()` re-fires matching subscribers against * the freshly-restored state, so callbacks **must be idempotent** and should * look up the DOM each time (don't capture stale element references). * * **Order matters.** Call `suspend()` BEFORE any DOM mutation that touches * ``'s class list, and `resume()` AFTER. `suspend()` disconnects the * observer synchronously, so mutations during the navigation window cannot * leak into the persisted state. */ export type LayoutClassWhen = 'added' | 'removed' | 'always'; export interface LayoutCallbackEvent { className: string; isApplied: boolean; storageKey: string; } export type LayoutCallback = (event: LayoutCallbackEvent) => void; export interface LayoutStateView { [className: string]: boolean; } export interface LayoutStatePersisted { [storageKey: string]: LayoutStateView; } export interface LayoutStateOptions { /** Observed element. Defaults to ``. */ root?: HTMLElement; /** Storage backend. Defaults to `localStorage`. */ storage?: Pick; /** * Bucket key under `atlas-layout-preferences` and the value surfaced as * `LayoutCallbackEvent.storageKey`. Same key shares state. Getter is * re-read per operation. Defaults to `'default'`. */ storageKey?: string | (() => string); /** * Key into `atlas-layout-exclusions`. Classes listed under this key are * skipped during restore, persist, subscriber dispatch (including initial * replay), and the inline pre-paint restore. Getter is re-read per * operation. Omit to disable exclusion lookup. */ excludesKey?: string | (() => string); /** * Classes to store under the current `excludesKey` in * `atlas-layout-exclusions`, written on construction and on every * `resume()`. Requires `excludesKey`. An empty array clears the list; * omission leaves any persisted entry untouched. The getter is re-read * per write, so SPA route changes can supply different exclusions. */ excludes?: string[] | (() => string[]); /** Delays initial subscriber callbacks. Defaults to next microtask. */ deferCallbacksUntil?: Promise; /** Wrap initial restoration in `document.startViewTransition` if available. */ useViewTransitionOnRestore?: boolean; } export interface LayoutSubscribeOptions { /** Wrap in a coalesced view transition; runs sync if one is already active. */ useViewTransition?: boolean; } export interface LayoutStateInstance { /** * Subscribe to `className` transitions. Replays once if the current state * matches (queued behind `deferCallbacksUntil`). Returns an unsubscribe fn * which is always safe to call (including after `dispose()`). Throws if * the instance has been disposed. */ subscribe(className: string, when: LayoutClassWhen, callback: LayoutCallback, options?: LayoutSubscribeOptions): () => void; /** State stored under the current `storageKey`. Safe to call after `dispose()`. */ getViewState(): LayoutStateView; /** State for all `storageKey` buckets. Safe to call after `dispose()`. */ getState(): LayoutStatePersisted; /** * Pause observation and clear `data-layout-restored` so CSS that waits for * layout restoration re-engages. Subscriptions are preserved. The * `MutationObserver` is disconnected synchronously, so this is safe to call * immediately before a DOM swap that overwrites ``'s class list. * Idempotent. Throws if disposed. */ suspend(): void; /** * Resume observation. Re-reads `storageKey`, `excludesKey`, and * `excludes` getters, re-writes any configured exclusions, re-restores * persisted state, replays matching subscribers against the new state, * and re-sets `data-layout-restored`. No-op when not currently * suspended. Throws if disposed. */ resume(): void; /** * Permanently tear down: disconnect the observer, clear all * subscriptions and pending queues, and remove `data-layout-restored`. * After dispose, `subscribe()`, `suspend()`, and `resume()` throw; * `getViewState()` and `getState()` still work (they read from * `storage`); previously-returned unsubscribe functions remain safe * no-ops. Idempotent. */ dispose(): void; } export interface LayoutSubscription { className: string; when: LayoutClassWhen; callback: LayoutCallback; useViewTransition: boolean; } /** `atlas-layout-exclusions` shape: key → set of excluded `layout-*` class names. */ export interface LayoutExclusionsPersisted { [key: string]: { [className: string]: true; }; } export declare function createLayoutState(options?: LayoutStateOptions): LayoutStateInstance; //# sourceMappingURL=layout.d.ts.map