@mono-lit/helper 0.0.0-stage → 0.0.1

package/dist/src/composables/mono-skeleton.d.ts

@@ -0,0 +1,193 @@
+/** phantom-ui's options, camelCase (applied to the wrapper as kebab-case attributes). */
+export interface MonoPhantomProps {
+    /** `shimmer` (default) | `pulse` | `breathe` | `solid`. */
+    animation?: 'shimmer' | 'pulse' | 'breathe' | 'solid' | (string & {});
+    /** `skeleton` (default, hides the content) | `overlay` (dims it and sweeps). */
+    mode?: 'skeleton' | 'overlay' | (string & {});
+    shimmerDirection?: 'ltr' | 'rtl' | 'ttb' | 'btt' | (string & {});
+    /** Sweep colour. Unset = the mono theme's (`--mono-skeleton-color`). */
+    shimmerColor?: string;
+    /** Block colour. Unset = the mono theme's (`--mono-skeleton-bg`). */
+    backgroundColor?: string;
+    /** Animation cycle, seconds (default 1.5). */
+    duration?: number;
+    /** Delay between blocks, seconds. */
+    stagger?: number;
+    /** Fade-out when loading ends, seconds. */
+    reveal?: number;
+    /** Repeat the measured row set N times (table placeholders). */
+    count?: number;
+    /** Gap between repeated rows, px. */
+    countGap?: number;
+    /** Radius for flat elements, px (default 4). */
+    fallbackRadius?: number;
+    /** Screen-reader announcement (default "Loading"). */
+    loadingLabel?: string;
+    /** Measure inside open shadow roots of slotted components. */
+    pierceShadow?: boolean;
+    /** Outline the measured blocks. */
+    debug?: boolean;
+}
+/** The object form of `pending`: `active` plays the boolean's part (omitted = auto). */
+export type MonoPendingOptions = {
+    active?: boolean;
+} & Partial<MonoPhantomProps>;
+/** `pending` — `true` / `false`, or an object with phantom-ui options. `undefined` = auto. */
+export type MonoPending = boolean | MonoPendingOptions;
+/** `createMonoUI({ skeleton: {...} })` — global phantom defaults + the SSR flag. */
+export interface MonoSkeletonDefaults extends Partial<MonoPhantomProps> {
+    /**
+     * Whether the app renders on the server. Decides the AUTO default of light elements:
+     * `true` → pending on first connect, `false` → never pending unless asked. The Nuxt
+     * module sets it from `nuxt.options.ssr`; unset, a Nuxt payload marker is sniffed.
+     */
+    ssr?: boolean;
+    /**
+     * Safety net for an automatic pending that never gets its "loaded" signal: released
+     * after this many ms (default 15000; `0` disables).
+     */
+    maxWait?: number;
+}
+export interface MonoSkeletonStatus {
+    /** `phantom-ui` is defined in this realm (and the skeleton is not disabled). */
+    active: boolean;
+    /** The configured SSR flag (`null` = not set, the sniffed value is used). */
+    ssr: boolean | null;
+    /** Elements whose first render happened BEFORE activation (no skeleton on that first paint). */
+    createdBeforeActive: number;
+    createdBeforeActiveTags: string[];
+}
+/** Which "loaded" signal an element's AUTO pending waits for. */
+export type MonoPendingAuto = 'render' | 'data' | 'never';
+/** Statics a Core may declare to tune the automatic behaviour. */
+export interface MonoPendingStatics {
+    /**
+     * `'render'` (default) — released in the element's first update, before first paint.
+     * `'data'` — released when `_monoPendingReady()` first returns true (re-checked on
+     * every update; the Cores request one on each controller / source notify).
+     * `'never'` — never automatic (overlays like modal / drawer); manual still works.
+     */
+    monoPendingAuto?: MonoPendingAuto;
+    /**
+     * `'wrap'` (default) — the mixin wraps `render()` in `<phantom-ui>`.
+     * `'custom'` — the element draws its own placeholder from `monoPendingActive(this)`
+     * (e.g. `mono-table-loading`); the mixin only resolves the state.
+     */
+    monoPendingMode?: 'wrap' | 'custom';
+    /**
+     * How the element's own pending is drawn. `'phantom'` (default) — phantom-ui measures the
+     * content (a wrapper, one re-render per flip). `'css'` — only the `mono-pending` host
+     * attribute, i.e. the CSS-only block: no wrapper, no re-render, right for small elements
+     * whose measured skeleton would be one bar anyway (the table helpers). Render-driven
+     * elements held by a loading page draw through phantom like everything else; the CSS lane
+     * is their fallback while phantom-ui is not (yet) defined.
+     */
+    monoPendingDraw?: 'phantom' | 'css';
+}
+/** A render-driven element held by the page (internal). */
+export interface MonoHeldElement {
+    _monoReleaseHeld(): void;
+}
+interface MonoSkeletonState {
+    active: boolean;
+    disabled: boolean;
+    ssr: boolean | null;
+    ssrSniffed: boolean | null;
+    defaults: MonoSkeletonDefaults;
+    watching: boolean;
+    createdBeforeActive: number;
+    createdBeforeActiveTags: string[];
+    warnedLate: boolean;
+    /** Data-driven elements still waiting for their first load (the page is "loading"). */
+    waiting: Set<object>;
+    /** Render-driven elements held pending until `waiting` empties. */
+    holders: Set<MonoHeldElement>;
+}
+/** Per-element slots the Cores can read without depending on the mixin's class shape. */
+declare const TAG_DEFAULT: unique symbol;
+declare const PENDING_ACTIVE: unique symbol;
+declare const PENDING_GRACE: unique symbol;
+declare const PENDING_PHANTOM: unique symbol;
+/** Where `applyMonoUIDefaults` parks a tag's `pending` default (not assigned to the prop). */
+export declare const MONO_PENDING_TAG_DEFAULT: unique symbol;
+declare function isActive(): boolean;
+/**
+ * Start following the registry. Idempotent; a no-op on the server. Called by the mono
+ * `customElement` decorator, so the watcher exists before any element constructs.
+ */
+export declare function watchSkeletonActivation(): void;
+/**
+ * Is this an SSR app? The explicit flag (`createMonoUI({ skeleton: { ssr } })`, which the
+ * Nuxt module sets from `nuxt.options.ssr`) wins; otherwise the Nuxt payload marker is
+ * sniffed once (`<script id="__NUXT_DATA__" data-ssr="true">`).
+ */
+export declare function isMonoSsrApp(): boolean;
+/** Set the global defaults (`createMonoUI`'s `skeleton` key routes here). `false` disables the skeleton. */
+export declare function setMonoSkeletonDefaults(defaults: MonoSkeletonDefaults | false | undefined): void;
+export declare function getMonoSkeletonStatus(): MonoSkeletonStatus;
+/** Drop defaults / flag / counters (tests). `active` stays — an element cannot be undefined. */
+export declare function resetMonoSkeleton(): void;
+/** The boolean a `pending` value carries (`undefined` = auto). */
+declare function activeOf(value: MonoPending | undefined): boolean | undefined;
+/** Only the phantom options of a value (an object), as a plain record. */
+declare function phantomOf(value: unknown): Record<string, unknown>;
+/** `hasChanged` for the property: booleans by value, objects shallowly. */
+export declare function pendingChanged(next: unknown, prev: unknown): boolean;
+/**
+ * The attribute converter. The attribute form is boolean-only: `pending`,
+ * `pending="true"` → true; `pending="false"` → false; absent or `pending="auto"` → auto.
+ * A real boolean is accepted too (what a server renderer hands over).
+ */
+export declare const pendingConverter: {
+    fromAttribute(value: unknown): MonoPending | undefined;
+    toAttribute(): null;
+};
+/**
+ * Register the `pending` property on a registered element class. Called by the mono
+ * `customElement` decorator BEFORE `customElements.define`, so the attribute lands in
+ * Lit's attribute map when `observedAttributes` is read.
+ */
+export declare function registerPendingProperty(cls: unknown): void;
+/** Whether `pending` currently resolves to true for `el` (set before each render). */
+export declare function monoPendingActive(el: object): boolean;
+/**
+ * True once one macrotask has passed since the element first resolved pending — lets a
+ * `'data'` Core say "no controller / source after one tick → nothing to wait for" without
+ * releasing before a binding made in the consumer's `onMounted`.
+ */
+export declare function monoPendingGrace(el: object): boolean;
+/**
+ * The phantom options resolved for `el` while pending (element object over tag default
+ * over global default), camelCase keys. Empty while not pending. For `'custom'` Cores
+ * that render their own `<phantom-ui>` and want a value in the template (e.g. `count`).
+ */
+export declare function monoPhantomOptions(el: object): Readonly<Record<string, unknown>>;
+/**
+ * Apply the resolved phantom options to a `<phantom-ui>` element as attributes (used by
+ * the mixin for its wrapper, and by `'custom'` Cores for the phantom they render).
+ * Diffed against what was last applied to that element, so unchanged values cost nothing.
+ */
+export declare function monoApplyPhantomOptions(el: object, target: Element | null | undefined): void;
+/** @internal */
+export declare const monoSkeletonInternals: {
+    readonly hasDom: boolean;
+    readonly isActive: typeof isActive;
+    readonly state: MonoSkeletonState;
+    readonly slots: {
+        readonly TAG_DEFAULT: typeof TAG_DEFAULT;
+        readonly PENDING_ACTIVE: typeof PENDING_ACTIVE;
+        readonly PENDING_GRACE: typeof PENDING_GRACE;
+        readonly PENDING_PHANTOM: typeof PENDING_PHANTOM;
+    };
+    readonly activeOf: typeof activeOf;
+    readonly phantomOf: typeof phantomOf;
+    readonly PHANTOM_TAG: "phantom-ui";
+    readonly DEFAULT_MAX_WAIT: 15000;
+};
+/** The `<phantom-ui>` wrapper the skeleton mixin renders around an element's content. */
+export declare function isMonoSkeletonWrapper(node: Node | null | undefined): boolean;
+/** `Array.from(host.childNodes)` minus the skeleton wrapper. */
+export declare function monoHostChildNodes(host: Node): Node[];
+/** `Array.from(host.children)` minus the skeleton wrapper. */
+export declare function monoHostChildren(host: Element): Element[];
+export {};

package/dist/src/composables/mono-ui.d.ts

@@ -0,0 +1,58 @@
+import { MonoSkeletonDefaults } from './mono-skeleton';
+/**
+ * Tag → props map for typed configs. `scripts/gen-vue-types.mjs` augments it in
+ * the published types (`'mono-button': ButtonProps`, …); it is empty in source.
+ */
+export interface MonoUIComponents {
+}
+type KnownConfig = {
+    [K in keyof MonoUIComponents]?: Partial<MonoUIComponents[K]>;
+};
+/**
+ * Per-component default props. Keys are tags (`mono-button`); props are camelCase or kebab-case.
+ * The reserved `skeleton` key holds the global defaults of the automatic skeleton
+ * (`pending`, see ./mono-skeleton.ts) and its `ssr` flag; `false` disables it.
+ */
+export type MonoUIConfig = KnownConfig & {
+    skeleton?: MonoSkeletonDefaults | false;
+} & {
+    [tag: `mono-${string}`]: Record<string, unknown> | undefined;
+};
+export interface MonoUI {
+    readonly config: Readonly<MonoUIConfig>;
+    /** Vue plugin hook — a no-op; the call already applied the config. */
+    install(app?: unknown): void;
+}
+export interface MonoUIStatus {
+    /** `createMonoUI` has been called (and not reset). */
+    configured: boolean;
+    /** Mono elements constructed BEFORE the current config was set — they kept built-in defaults. */
+    createdBefore: number;
+    /** Their tags, first occurrence order. */
+    createdBeforeTags: string[];
+}
+/**
+ * Set the app-wide default props. Call once, first — usually in `main.ts`:
+ *
+ * ```ts
+ * app.use(createMonoUI({ 'mono-button': { size: 'xs' } }))
+ * // or simply
+ * createMonoUI({ 'mono-button': { size: 'xs' } })
+ * ```
+ *
+ * A later call replaces the previous config for elements created afterwards.
+ */
+export declare function createMonoUI(config?: MonoUIConfig): MonoUI;
+/** The current config, or `null` when `createMonoUI` has not been called. */
+export declare function getMonoUI(): Readonly<MonoUIConfig> | null;
+/** Whether the config is set, and how many elements were created before it was. */
+export declare function getMonoUIStatus(): MonoUIStatus;
+/** Drop the config (tests, or reconfiguring before mount). Elements created afterwards get built-in defaults. */
+export declare function resetMonoUI(): void;
+/**
+ * Apply the configured defaults to a freshly constructed element. Called by the
+ * mono `customElement` decorator at the end of construction — not public API.
+ * @internal
+ */
+export declare function applyMonoUIDefaults(el: HTMLElement, tag: string): void;
+export {};

package/dist/src/composables/notifier.d.ts

@@ -0,0 +1,46 @@
+/** A subscriber callback. */
+export type MonoNotifyFn = () => void;
+export interface MonoNotifier {
+    /** Register a subscriber; returns its unsubscribe handle. */
+    subscribe(cb: MonoNotifyFn): () => void;
+    /** Schedule a coalesced notification. */
+    notify(): void;
+    /** Drop every subscriber (controller `dispose`). */
+    clear(): void;
+    /** How many subscribers are attached — handy for tests / diagnostics. */
+    readonly size: number;
+}
+export interface MonoNotifierOptions {
+    /**
+     * Runs immediately before the subscribers, inside the same flush. Use it to
+     * recompute derived state that subscribers are about to read (e.g. the grid
+     * refreshes its merged element props and writes its `state` snapshot here).
+     */
+    onFlush?: () => void;
+    /** Names the controller in the runaway-loop error (`'form'`, `'grid'` …). */
+    name?: string;
+    /** Extra context for that error — e.g. the form keys that notified last. Called only on a trip. */
+    detail?: () => string;
+}
+/**
+ * Flushes allowed back-to-back without the event loop getting a turn. Real work never comes close:
+ * notifies in one tick coalesce into ONE flush, and a chain of awaited watchers adds a handful. A
+ * count in the hundreds is a feedback loop — a subscriber (a Vue `watch` on the `state` ref, a
+ * `subscribe` callback) writing back into the controller on every flush — and as microtasks it
+ * starves rendering, input and timers: the tab freezes with no error at all.
+ */
+export declare const MONO_NOTIFY_RUNAWAY_LIMIT = 200;
+/**
+ * The coalesced notifier every mono controller uses.
+ *
+ * Notifications are queued on a microtask and de-duplicated, so several state
+ * changes in one tick produce a single callback. That coalescing is not a
+ * nicety: a synchronous subscriber that re-renders the consumer's Vue tree would
+ * reenter an in-flight patch and corrupt the DOM. When `queueMicrotask` is
+ * unavailable (older SSR runtimes) it degrades to a synchronous flush.
+ *
+ * This was copy-pasted into `monoDataGrid`, `monoDataDropdown`, `monoForm` and
+ * `monoChart` — identical logic and, in two of them, identical comments. One
+ * implementation means one place to fix if the scheduling ever needs to change.
+ */
+export declare function createNotifier(options?: MonoNotifierOptions): MonoNotifier;

package/dist/src/composables/popup-portal.d.ts

@@ -0,0 +1,226 @@
+import { ReactiveController, ReactiveControllerHost } from 'lit';
+import { PopupLayer } from './popup-stack';
+type PopupHost = ReactiveControllerHost & HTMLElement & {
+    readonly renderRoot: HTMLElement | DocumentFragment;
+};
+export type PopupSide = 'top' | 'bottom' | 'left' | 'right';
+export type PopupAlign = 'start' | 'center' | 'end';
+export interface PopupPortalOptions {
+    /** Locate the panel element (searched in the host's render root). */
+    getPanel: () => HTMLElement | null;
+    /** Element the panel is anchored to (the trigger / field). */
+    getAnchor: () => HTMLElement | null;
+    /**
+     * Element whose class list AND `mono-*` attributes are mirrored onto the portal
+     * so the relocated panel keeps its theme CSS variables and state-dependent
+     * styles — the legacy `.mono-select.open .mono-select-dropdown` rule and the
+     * Basecoat-ported `[mono-select][mono-open] > [mono-dropdown]` one alike, with
+     * the `--_mono-<c>-*` resolvers declared on `[mono-<c>]` re-resolving on the
+     * portal. Usually the host or its inner wrapper `<div>`.
+     */
+    getStyleScope: () => HTMLElement | null;
+    /**
+     * The component's PUBLIC custom-property names, so a relocated panel keeps
+     * overrides an ancestor of the host set.
+     *
+     * Class and attribute mirroring is not enough for these: a custom property is
+     * inherited, and a portaled panel is a child of `<body>`, so
+     * `--mono-dropdown-radius` set on a wrapper around the host simply is not in
+     * its inheritance chain any more. `getComputedStyle` cannot enumerate custom
+     * properties (Chromium lists none of them), so the component has to name the
+     * ones it reads; each is resolved on the scope and copied onto the portal when
+     * it differs from what the portal already resolves.
+     */
+    styleVars?: () => readonly string[];
+    /** Whether the popup is currently open. */
+    isOpen: () => boolean;
+    side?: () => PopupSide;
+    align?: () => PopupAlign;
+    offset?: () => number;
+    flip?: () => boolean;
+    shift?: () => boolean;
+    /** Panel width tracks the anchor's width (select / tag-input full-width drop). */
+    /**
+     * Stretch the panel to the anchor's width on every reposition.
+     *
+     * A GETTER as well as a plain boolean, because a component may want it to follow a prop: a
+     * consumer that sets an explicit panel width needs this off, or the write below overwrites it
+     * on the next open / scroll / resize.
+     */
+    matchWidth?: boolean | (() => boolean);
+    /**
+     * Publish the room available on the resolved side as `--mono-popup-avail-h`
+     * (main axis) / `--mono-popup-avail-w` (cross axis) on the panel, so its CSS
+     * can shrink instead of spilling off-screen. See {@link applyPopupPlacement}.
+     */
+    constrainSize?: () => boolean;
+    /** Notified when the resolved side changes after flipping. */
+    onSideResolved?: (side: PopupSide) => void;
+}
+export interface PopupPlacementOptions {
+    side?: PopupSide;
+    align?: PopupAlign;
+    offset?: number;
+    flip?: boolean;
+    shift?: boolean;
+    /** Gap kept between the panel and the viewport edge. */
+    margin?: number;
+    /**
+     * The caller will clamp the panel to `availableMain` (see `constrainSize`), so
+     * anchor a flipped/`top`-side panel to the CLAMPED extent rather than its
+     * natural one. Off by default: an unconstrained panel keeps its natural size,
+     * and pretending otherwise would slide it over its own trigger.
+     */
+    constrain?: boolean;
+}
+export interface PopupPlacement {
+    top: number;
+    left: number;
+    /** The side actually used (may differ from the preferred one after flipping). */
+    side: PopupSide;
+    /**
+     * Room between the anchor and the viewport edge along the panel's main axis
+     * on the resolved side — height for top/bottom, width for left/right.
+     */
+    availableMain: number;
+}
+/**
+ * True when an event's composed path passes through any of `roots` — directly,
+ * or through a body-level popup portal whose OWNER lives inside one of them (at
+ * any depth: a select inside a header filter inside a dropdown-table resolves
+ * all the way up).
+ *
+ * The one "is this click inside me?" test the library uses. Popups ask it
+ * through `PopupPortalController.containsInPath`; `mono-modal` / `mono-drawer`
+ * — which portal themselves, not through this controller — ask it directly with
+ * their host + render root, so a click in a select's option list opened from
+ * inside a no-overlay dialog counts as inside the dialog.
+ */
+export declare function pathOwnedBy(path: EventTarget[], roots: readonly Element[]): boolean;
+/**
+ * Nearest ancestor of the panel that establishes a containing block for
+ * `position: fixed` descendants. A body-portaled panel has none (the portal is
+ * a direct child of `<body>`), but a shadow-root panel usually sits under app
+ * chrome that does.
+ */
+export declare function findFixedContainingBlock(panel: HTMLElement): HTMLElement | null;
+/**
+ * Resolve where `panel` should sit relative to `anchor`, in viewport
+ * coordinates (i.e. what `position: fixed` wants, before any containing-block
+ * compensation — that's {@link applyPopupPlacement}'s job).
+ *
+ * IMPORTANT — the panel is measured at its NATURAL size: any previously
+ * published `--mono-popup-avail-*` constraint is cleared first. A constrained
+ * panel is exactly as tall as the room we gave it, so measuring it that way
+ * would make the flip test (`spaceBelow < panelH`) always report "it fits" and
+ * the panel would oscillate between sides on every scroll tick.
+ */
+export declare function computePopupPlacement(anchor: HTMLElement, panel: HTMLElement, o?: PopupPlacementOptions): PopupPlacement;
+/**
+ * Commit a {@link computePopupPlacement} result to the panel. Compensates for a
+ * transformed / contained ancestor that has become the fixed panel's containing
+ * block (a no-op for a body-portaled panel), and — when `constrain` is set —
+ * publishes the available room so the panel's own CSS can clamp itself.
+ */
+export declare function applyPopupPlacement(panel: HTMLElement, placement: PopupPlacement, constrain?: boolean): void;
+export declare class PopupPortalController implements ReactiveController, PopupLayer {
+    private readonly host;
+    private readonly opts;
+    private _portal;
+    /** Cached panel reference (it leaves the render root once adopted). */
+    private _panel;
+    private _adopted;
+    private _registered;
+    private _resolvedSide;
+    /** Keeps the portal's mirrored class current even when the host applies its
+     *  state classes imperatively in `updated()` (which runs *after* the
+     *  controller's `hostUpdated`). */
+    private _classObserver;
+    /** Whether the viewport listeners are currently attached (open-only, see
+     *  `_bindViewport`). Keeps the add/remove pair balanced across the several
+     *  paths that can open or close a popup. */
+    private _viewportBound;
+    /** Pending reposition frame, so a scroll burst costs one layout, not one per event. */
+    private _viewportFrame;
+    constructor(host: PopupHost, opts: PopupPortalOptions);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    hostUpdated(): void;
+    /**
+     * Only relocate to `<body>` when the host renders into light DOM
+     * (`renderRoot === host`). Shadow hosts keep the panel in their shadow root.
+     */
+    private get _canPortal();
+    private _ensurePortal;
+    /** Move the panel into the body portal on first open; keep it there after. */
+    private _adopt;
+    /** Mirror the style-scope element's classes and `mono-*` attributes onto the portal. */
+    private _syncPortalClass;
+    /**
+     * Carry the component's public custom properties across the portal (see
+     * `styleVars`). Only values that DIFFER from the portal's own resolution are
+     * written, so a theme-level token stays inherited and only a real override
+     * (an ancestor of the host, or an inline style on it) is copied.
+     */
+    private _syncPortalVars;
+    /**
+     * Watch the style-scope's `class` attribute so the portal stays in sync even
+     * when the host toggles state classes (e.g. `open`) imperatively in
+     * `updated()`, which runs after the controller's `hostUpdated`.
+     */
+    private _observeStyleScope;
+    private _enterStack;
+    private _leaveStack;
+    /** PopupLayer hook — write the chained z onto the portal (root context). */
+    setStackZ(z: number): void;
+    /** Where panel-internal elements live now (portal while adopted, else host). */
+    get panelRoot(): ParentNode;
+    /**
+     * True when an event's composed path passes through this popup — its own
+     * portaled panel, OR any popup that was opened from inside it.
+     *
+     * The second half is what keeps a nested popup from dismissing its parent:
+     * a header filter opened from a `<mono-table-th>` in a dropdown-table's
+     * panel, a select's option list inside a modal — each lives in a portal of
+     * its own on `<body>`, so a click in it is nowhere near the parent in the
+     * DOM. It IS inside by ownership, and that is what every outside-click test
+     * in the library asks this method.
+     */
+    containsInPath(path: EventTarget[]): boolean;
+    /**
+     * True when the path passes through a popup opened from INSIDE this one
+     * (at any depth) — not this popup's own panel.
+     *
+     * Walks each portal in the path back to its owner and asks whether that
+     * owner lives in this host or this panel; an owner that is itself inside
+     * another popup climbs to that popup's owner, so a select inside a filter
+     * inside a dropdown-table resolves all the way up. Composed-tree
+     * containment throughout: the owner may sit behind a slot or a shadow root.
+     */
+    ownsNestedInPath(path: EventTarget[]): boolean;
+    /**
+     * Listen for viewport movement — but ONLY while this popup is open.
+     *
+     * These used to be bound in `hostConnected`, which meant one capture-phase
+     * `scroll` listener on `window` per popup-capable element on the page, open or
+     * not: every select, every table header filter, every search box — and one per
+     * ROW on a grid that puts a `mono-button-dropdown` in each. `_onViewport` bails
+     * when closed, so the handler was free; the *dispatch* was not, and a
+     * non-passive capture listener on `window` also disqualifies the whole page's
+     * scrolling from running off the compositor thread.
+     *
+     * `passive` because nothing here calls `preventDefault`.
+     */
+    private _bindViewport;
+    private _unbindViewport;
+    /**
+     * Coalesced to one frame: `reposition()` writes then reads
+     * (`getBoundingClientRect` on anchor and panel) and walks the ancestors with
+     * `getComputedStyle`, i.e. it forces a synchronous layout. Running that once per
+     * scroll event rather than once per frame is what made scrolling a modal body
+     * with an open dropdown stutter.
+     */
+    private _onViewport;
+    reposition(): void;
+}
+export {};

package/dist/src/composables/popup-stack.d.ts

@@ -0,0 +1,70 @@
+/** First layer's z-index. Each subsequent open layer sits one STEP higher. */
+export declare const POPUP_Z_BASE = 1000;
+/** Gap between adjacent layers — leaves room for overlay(z) + panel(z+1) pairs. */
+export declare const POPUP_Z_STEP = 10;
+export interface PopupLayer {
+    /**
+     * Apply the z-index for this layer's current slot in the stack.
+     * `isTopBackdrop` is true when no other *backdrop-bearing* layer (modal /
+     * drawer) sits above this one. Backdrop layers use it to dim their own
+     * overlay only when another overlay already covers them; lightweight popups
+     * (which render no backdrop) ignore it.
+     */
+    setStackZ(z: number, isTopBackdrop: boolean): void;
+    /** True while this layer wants the document body scroll locked (modal/drawer). */
+    readonly lockBodyScroll?: boolean;
+    /**
+     * True when this layer renders its own dim backdrop / overlay (modal, drawer).
+     * Only these layers participate in the `isTopBackdrop` computation, so opening
+     * a backdrop-less popup (dropdown/select/…) above a modal never hides the
+     * modal's backdrop.
+     */
+    readonly hasBackdrop?: boolean;
+    /**
+     * Called when Escape is pressed and this layer is the topmost one. Layers that
+     * own their own Escape handling (dropdown/select/…) simply don't implement it,
+     * in which case Escape is a no-op at the stack level.
+     */
+    onStackEscape?(event: KeyboardEvent): void;
+    /**
+     * The level this layer actually paints at when it refuses the slot it is
+     * handed — modal / drawer's `z-index` prop. `undefined` (the default) means
+     * "use the slot", which is every other layer.
+     *
+     * The chain RESUMES from this value rather than from the slot index, because
+     * layers opened above a pinned one have to clear it. Without that, a dialog
+     * pinned to 10_000_000 leaves the select opened inside it at 1010 — painted
+     * underneath the very dialog it belongs to.
+     */
+    readonly pinnedZ?: number;
+}
+/** Add a layer to the top of the stack (call on open). */
+export declare function registerPopupLayer(layer: PopupLayer): void;
+/** Remove a layer from the stack (call on close / disconnect). */
+export declare function unregisterPopupLayer(layer: PopupLayer): void;
+/**
+ * Recompute every open layer's level without touching the membership.
+ *
+ * For a layer whose `pinnedZ` changed while it was open — a bound `:z-index` on a
+ * modal that is already showing. The dialog's own level is republished by its
+ * `updated()` either way; this is what moves the layers stacked ABOVE it.
+ *
+ * Re-runs the scroll lock as well, because `lockScroll` can flip on an overlay that is
+ * ALREADY open: membership has not changed, so neither register nor unregister fires,
+ * and without this the page stays locked until the overlay closes.
+ */
+export declare function refreshPopupStack(): void;
+/**
+ * Take or release a share of the page-scroll lock from OUTSIDE the stack.
+ *
+ * For an overlay that manages its own z-index and Escape handling and so does not belong
+ * in the stack, but must still share the one lock — `mono-sidebar`. Idempotent per owner;
+ * the lock lifts only when the last owner (stack layer or otherwise) lets go.
+ */
+export declare function setExternalScrollLock(owner: object, wanted: boolean): void;
+/**
+ * Currently-open layers in open order (topmost last). Used by exclusive
+ * (non-stackable) modal/drawer logic that must close *other* instances of its
+ * own type — filter the returned list by `instanceof`.
+ */
+export declare function getOpenPopupLayers(): readonly PopupLayer[];