@mono-lit/helper 0.0.0-stage → 0.0.2

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

@@ -0,0 +1,103 @@
+/**
+ * Colour parsing and contrast, for props that accept a raw CSS colour.
+ *
+ * `mono-sidebar`, `mono-nav` and `mono-menu` take a `color` that is either a theme token
+ * name or a literal colour (`#7c3aed`, `rgb(124 58 237)`). A token resolves entirely in
+ * CSS — the component sets a `-preset` var and the stylesheet reads `--theme-<name>` and
+ * the matching `--theme-<name>-contrast`. A literal has no such tokens, so two values
+ * have to be derived here instead: the `r, g, b` triple the `--*-rgb` half of the API
+ * expects, and the ink that stays readable on it.
+ *
+ * Everything is a pure function over the prop's own string — no `getComputedStyle`, no
+ * DOM — so it runs unchanged during SSR, where the component renders before any
+ * stylesheet has been applied.
+ *
+ * Scope note: `src/components/chart/mono-data-chart.ts` has its own private `toRgb`.
+ * It is deliberately left alone — it feeds Chart.js canvas paint, which cannot resolve
+ * `var()` and has different needs.
+ */
+export interface Rgba {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** The two inks the theme uses on a filled surface (`index.css` `--theme-*-contrast`). */
+export declare const INK_LIGHT = "#ffffff";
+export declare const INK_DARK = "rgba(0, 0, 0, 0.87)";
+/**
+ * Parse a literal CSS colour to sRGB, or null when it isn't one we can read.
+ *
+ * Handles `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb()/rgba()` and `hsl()/hsla()` in
+ * both the legacy comma syntax and the modern space syntax. Returns null for anything
+ * else — `var(…)`, `color-mix(…)`, a named keyword — which callers treat as "paint it,
+ * but fall back for the derived values", since the browser can still render it.
+ */
+export declare function parseCssColor(value: string | undefined | null): Rgba | null;
+/** WCAG relative luminance. */
+export declare function relativeLuminance({ r, g, b }: Rgba): number;
+/** WCAG contrast ratio, 1–21. Order of the arguments does not matter. */
+export declare function contrastRatio(a: Rgba, b: Rgba): number;
+/**
+ * The better of the theme's two inks for text sitting ON `value`, or null when the
+ * colour can't be parsed (the caller then leaves the ink alone and the CSS default —
+ * white, matching every `--theme-*-contrast` but warning's — applies).
+ *
+ * Compares actual contrast rather than thresholding luminance, so it stays correct for
+ * mid-tone colours where a fixed cutoff picks the worse of the two.
+ */
+export declare function readableInk(value: string | undefined | null): string | null;
+/**
+ * `"r, g, b"` for the `--*-rgb` half of the colour API, which the stylesheets wrap in
+ * `rgba(var(--…-rgb), α)`. Null when unparseable.
+ */
+export declare function toRgbTriple(value: string | undefined | null): string | null;
+/**
+ * Does this look like a literal colour rather than a token name?
+ *
+ * Only used AFTER the component's own token list has been checked, so `teal` and
+ * `purple` — which are both theme slots and CSS keywords — always mean the theme slot.
+ * Bare CSS keywords are deliberately not recognised here: a typo like `primry` should
+ * fall through to the validator's warning instead of being silently painted as nothing.
+ */
+export declare function isRawColorValue(value: string | undefined | null): boolean;
+/**
+ * The brand slots `src/data/theme/index.css` defines, in the order they appear there.
+ * Every one has a `--theme-<name>`, a `--theme-<name>-rgb` and a `--theme-<name>-contrast`,
+ * so a component only has to name the slot for the whole treatment to follow the active
+ * colour preset. `surface` is not here — it is each component's "not painted" state, not
+ * a palette entry.
+ */
+export declare const THEME_COLOR_TOKENS: readonly ["primary", "secondary", "success", "danger", "warning", "info", "teal", "purple", "neutral", "dark"];
+export type ThemeColorToken = (typeof THEME_COLOR_TOKENS)[number];
+/** The class token emitted for a `color` that is a literal rather than a slot name. */
+export declare const CUSTOM_COLOR_CLASS = "custom";
+export declare function isThemeColorToken(value: string | undefined | null): boolean;
+/**
+ * The class token for a `color` value.
+ *
+ * A literal MUST NOT reach the class list: the class string is built with `join(' ')`,
+ * so `rgb(255, 0, 0)` would split into three garbage tokens (`rgb(255,`, `0,`, `0)`),
+ * and `var(--brand)` likewise. Named slots — including `surface` — pass through; every
+ * literal collapses to one marker class that the stylesheet keys the painted treatment
+ * off, with the actual colour arriving inline (see `customColorStyle`).
+ */
+export declare function colorClassToken(value: string | undefined | null): string;
+/**
+ * The inline declarations that carry a literal colour, e.g.
+ * `customColorStyle('#7c3aed', 'sidebar')`.
+ *
+ * Written on the component's ROOT element (the one whose stylesheet block declares the
+ * resolvers) — an inline declaration beats the class-based `.mono-<c>.<token>` presets,
+ * whereas the same property set on the host would only *inherit* and would lose to them.
+ *
+ * The rgb triple and the ink are emitted only when the value parses. An unparseable but
+ * renderable value (`var(--brand)`, `color-mix(…)`) still paints: it just keeps the CSS
+ * default ink, and `--mono-<c>-on-accent` stays available to set it by hand.
+ */
+export declare function customColorStyle(value: string | undefined | null, component: string): string;
+/**
+ * Shared validator arm for a `color` prop: a named slot, `surface`, or something that
+ * reads as a CSS colour. Returns an error string, or null when the value is fine.
+ */
+export declare function validateColorProp(value: unknown): string | null;

package/dist/src/composables/css-class.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Append a per-part class override (if present) to a base class string.
+ *
+ *   cssPart({ inner: 'px-4' }, 'mono-nav-inner', 'inner') // 'mono-nav-inner px-4'
+ *   cssPart(undefined,        'mono-nav-inner', 'inner') // 'mono-nav-inner'
+ */
+export declare function cssPart<T extends object>(cssClass: T | undefined, base: string, key: keyof T): string;
+/**
+ * Apply a `css-class` value to an element's `cssClass`/`cssClassName`.
+ *
+ *  - `null`/`undefined`/empty string → reset both
+ *  - object                          → `cssClass`
+ *  - `'{ … }'` JSON string           → parsed into `cssClass`
+ *  - plain string                    → `cssClassName` (root class fallback)
+ *
+ * Mutates the element's reactive properties directly (so Lit picks up the
+ * change). Used by each component's `_setCssClass`.
+ */
+export declare function applyCssClass<T extends object>(target: {
+    cssClass: T;
+    cssClassName: string;
+}, value: unknown): void;
+/**
+ * Define `css-class` and `cssclass` instance aliases (Vue interop) that route to
+ * `set`. Lets consumers write `<el :css-class="…">` / `:cssclass` / `:cssClass`.
+ */
+export declare function defineCssClassAliases(target: object, set: (value: unknown) => void): void;

package/dist/src/composables/css-size.d.ts

@@ -0,0 +1,40 @@
+import { StyleInfo } from 'lit/directives/style-map.js';
+/** A sizing prop value: a CSS length string, or a number (interpreted as px). */
+export type CssSizeValue = string | number | undefined;
+/**
+ * Normalize a sizing prop to a CSS length string.
+ * - `number` (or numeric string) → `${n}px`
+ * - any other non-empty string → passed through verbatim (`"12rem"`, `"80%"`, …)
+ * - `null` / `undefined` / `''` → `undefined` (treated as "not set")
+ */
+export declare function toCssSize(value: CssSizeValue): string | undefined;
+/** The six sizing props shared by sizing-driven components. */
+export interface SizeProps {
+    width?: CssSizeValue;
+    height?: CssSizeValue;
+    minWidth?: CssSizeValue;
+    maxWidth?: CssSizeValue;
+    minHeight?: CssSizeValue;
+    maxHeight?: CssSizeValue;
+}
+/**
+ * The popup-PANEL sizing object shared by `mono-select`, `mono-tag-input` and
+ * `mono-dropdown-table`, bound as `:dropdown.prop="{ … }"`.
+ *
+ * The same six keys as {@link SizeProps}, applied to the panel rather than the field:
+ * `height` is an exact height and `maxHeight` the cap, on all three.
+ *
+ * Aliased rather than re-declared per component so the key set cannot drift between them —
+ * each still exports its own name (`SelectDropdownOptions`, `TagInputDropdownOptions`,
+ * `DropdownPanelOptions`) for the consumers who already import one.
+ *
+ * There is deliberately no shared style BUILDER to go with it: the three write these keys onto
+ * different elements with different fallbacks, and a helper parameterised over all of that would
+ * bury the one part that is genuinely subtle — which cap goes to a custom property, and why.
+ */
+export type PanelSizeProps = SizeProps;
+/**
+ * Build a Lit `styleMap` object from the six sizing props, normalizing each via
+ * `toCssSize` and omitting the ones that aren't set.
+ */
+export declare function buildSizeStyle(src: SizeProps): StyleInfo;

package/dist/src/composables/data-source-controller.d.ts

@@ -0,0 +1,113 @@
+import { ReactiveController, ReactiveControllerHost } from 'lit';
+import { DescribedError } from '../utils/normalize-error';
+/**
+ * Minimal structural shape of a devextreme DataSource. Declared locally so
+ * @mono-lit/helper stays dependency-free; a real devextreme DataSource satisfies it.
+ */
+export interface MonoDataSource<T = unknown> {
+    load: () => PromiseLike<T[]> | T[];
+    items: () => T[];
+    isLoading?: () => boolean;
+    on(event: string, handler: (...args: unknown[]) => void): void;
+    off(event: string, handler: (...args: unknown[]) => void): void;
+    paginate?(value?: boolean): boolean;
+    pageSize?(value?: number): number;
+    pageIndex?(value?: number): number;
+    isLastPage?: () => boolean;
+    totalCount?: () => number;
+}
+/**
+ * Incremental loading mode. Works with BOTH a paged DataSource and a plain
+ * `items` array (the array is revealed one `pageSize` chunk at a time):
+ * - 'button' → render a "Load more" button at the end of the list.
+ * - 'scroll' → load/reveal the next chunk when scrolled near the bottom.
+ */
+export type LoadMoreMode = 'button' | 'scroll';
+export interface DataSourceControllerOptions<T> {
+    /** Current bound DataSource (or null) — read live from the host property. */
+    getDataSource: () => MonoDataSource<T> | null;
+    /** The raw plain `items` array, used when no DataSource is bound. */
+    getItems: () => T[];
+    /** Auto-load the source on attach when it has no items yet. */
+    getImmediate: () => boolean;
+    /** Effective load-more mode, or undefined when disabled. */
+    getLoadMoreMode: () => LoadMoreMode | undefined;
+    /** Sanitized chunk size (>= 1) for array-mode paging. */
+    getPageSize: () => number;
+}
+/**
+ * Encapsulates the generic DataSource + incremental-loading logic shared by
+ * `mono-select`, `mono-tag-input`, etc. The host owns the rendering and any
+ * scroll/height ergonomics; this controller owns binding, event wiring, page
+ * accumulation, and array-mode chunking.
+ *
+ * Every state mutation calls `host.requestUpdate()` so the host re-renders.
+ */
+export declare class DataSourceController<T = unknown> implements ReactiveController {
+    private readonly host;
+    private readonly opts;
+    private _dsItems;
+    private _dsLoading;
+    private _loadingMore;
+    private _isLastPage;
+    private _error;
+    private _hasLoaded;
+    private _retrying;
+    private _visibleCount;
+    private _internalLoad;
+    private _bound;
+    constructor(host: ReactiveControllerHost, opts: DataSourceControllerOptions<T>);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /** Attach/detach listeners for a (possibly new) DataSource and seed state. */
+    bind(ds: MonoDataSource<T> | null): void;
+    maybeImmediateLoad(): void;
+    /** Call when the load-more mode changes; refreshes paging assumptions. */
+    onLoadMoreModeChange(): void;
+    /** Reset array-mode paging to the first chunk. */
+    resetVisible(): void;
+    /** Load/reveal the next page and append it to the accumulated list. */
+    loadMore(): Promise<void>;
+    /**
+     * Re-run the request after a failure. Reloads the source as it stands, so a
+     * failed search is retried with the same query. While it runs the field is
+     * {@link busy} again.
+     *
+     * `load` replaces the plain `ds.load()` — a host whose failed request was a
+     * search passes one that clears the query on the source and reloads.
+     */
+    retry(load?: () => unknown): Promise<void>;
+    /**
+     * Record a failure from a request the host drove itself (e.g. a server
+     * select-all drain). Cancelled loads are ignored.
+     */
+    setError(raw: unknown): void;
+    /** Raw source array: accumulated DataSource items, or the plain `items`. */
+    get sourceItems(): T[];
+    /** Rows to actually render (array-mode reveals a slice; else everything). */
+    get visibleItems(): T[];
+    get loading(): boolean;
+    get loadingMore(): boolean;
+    /**
+     * The field must be locked: the FIRST load (or a retry) is in flight. A
+     * search / filter reload after the source has answered once does not count —
+     * the person is typing into the field and it must stay usable.
+     */
+    get busy(): boolean;
+    /** The last load failure, described for a person; null once a load succeeds. */
+    get error(): DescribedError | null;
+    /** load-more is driving a plain `items` array (no DataSource bound). */
+    get isArrayLoadMore(): boolean;
+    /** Whether there's nothing left to load/reveal. */
+    get atLastPage(): boolean;
+    private readonly _onChanged;
+    private readonly _onLoadingChanged;
+    private readonly _onLoadError;
+    /** A load answered: the source is usable and any earlier failure is over. */
+    private _markLoaded;
+    private _sync;
+    /** Load the first page, replacing the accumulated list. */
+    private _loadFirstPage;
+    private _detach;
+    private _changed;
+}

package/dist/src/composables/element-props.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Whether `key` can actually be assigned on `obj` — a plain expando, or an
+ * accessor/data property that isn't read-only.
+ *
+ * This matters because a controller's `props` object legitimately carries keys
+ * that are NOT element props: `monoDataGrid`'s `th[].summary` includes `prefix`
+ * and `precision`, which the controller consumes for formatting. `prefix`
+ * collides with the read-only native `Element.prefix`, and assigning it throws —
+ * which took down the whole docs page render until this check existed.
+ */
+export declare function isSettable(obj: object, key: string): boolean;
+/** `{ onChange, onToggle, onLoadingChange, … }` typed from a component's `*Events` interface. */
+export type MonoEventProps<E> = {
+    [K in Extract<keyof E, string> as K extends `${string}-${string}` ? never : `on${Capitalize<K>}`]?: (event: E[K]) => void;
+};
+/** Whether a props key names an event handler (`onClick`, `onLoadingChange`). */
+export declare function isEventHandlerKey(key: string): boolean;
+/**
+ * `onClick` → `click`, `onLoadingChange` → `loading-change`, `onMnoChange` →
+ * `mno-change` — the same rule Vue applies to an `on*` listener prop, so a key
+ * that works in a template works here.
+ */
+export declare function eventNameFromHandlerKey(key: string): string;
+/**
+ * Remove every handler `applyProps` attached to `el`. Call it where an element
+ * leaves its controller (an unbind, a re-bind to a different one) so the old
+ * controller's handlers do not keep firing beside the new one's.
+ */
+export declare function detachEventHandlers(el: object): void;
+/**
+ * Write a controller's props onto an element.
+ *
+ * Two guards, both load-bearing:
+ * - `undefined` values are skipped, so "not declared" never clobbers a value the
+ *   template set;
+ * - each write is equality-checked, so a sync can't schedule another update and
+ *   loop.
+ *
+ * Handler keys (`onClick`, `onToggle`, …) become event listeners — see the
+ * block above — never properties.
+ *
+ * Shared by `table-controller-core` (`monoDataGrid`/`monoDataDropdown` elements)
+ * and `form-control-core` (`monoForm` controls) — the write loop is identical
+ * and its failure modes are subtle enough to be worth having in one place.
+ */
+export declare function applyProps(el: object, patch: Record<string, unknown> | undefined): boolean;

package/dist/src/composables/field-icons.d.ts

@@ -0,0 +1,15 @@
+import { TemplateResult } from 'lit';
+/** Downward caret — the "this opens a panel" affordance. */
+export declare function caretIcon(): TemplateResult;
+/** The ✕ a clear button and a chip's remove button draw, at the caret's weight. */
+export declare function closeIcon(): TemplateResult;
+/** Left (`-1`) or right (`1`) chevron, matching {@link caretIcon}'s weight. */
+export declare function chevronIcon(dir: -1 | 1): TemplateResult;
+/**
+ * Busy arc for a field whose data source is still answering. Spun by the
+ * component's own CSS (`[mono-ds-spinner] > svg`) so a reduced-motion rule can
+ * stop it.
+ */
+export declare function spinnerIcon(): TemplateResult;
+/** ↻ — the retry affordance a field shows after its data source failed. */
+export declare function refreshIcon(): TemplateResult;

package/dist/src/composables/hybird-prop.d.ts

@@ -0,0 +1,79 @@
+/** Generic constructor type for Lit mixins: `<T extends Constructor<LitElement>>`. */
+export type Constructor<T = object> = new (...args: any[]) => T;
+export declare function toKebabCase(value: string): string;
+export declare function toLowerCaseProp(value: string): string;
+export declare function defineHybridPropAliases<T extends object>(target: T, props: string[]): void;
+/**
+ * Register a cross-name alias for a controller-binding prop — e.g.
+ * `defineHybridPropAlias(el, 'controlTable', 'dataGrid')` makes `controlTable`,
+ * `control-table` and `controltable` all read/write the canonical reactive
+ * `dataGrid` property (so `.controlTable = …` still triggers Lit's update
+ * cycle). Used to rename the controller props without a breaking change: the
+ * new `control-*` spellings land here while the old `data-*` ones keep working.
+ */
+export declare function defineHybridPropAlias<T extends object>(target: T, aliasCamel: string, realProp: string): void;
+/**
+ * Lit `hasChanged` for an array prop.
+ *
+ * **Load-bearing**, for exactly the reason `rateLimitHasChanged` is (see
+ * `composables/rate-limit.ts`): `:items="[...]"` in a template allocates a NEW array
+ * on every parent re-render. Under Lit's default `!==` the element sees a change
+ * each time, so anything gated on `changed.has('items')` — resetting an
+ * infinite-scroll page, invalidating a search memo, rebuilding a cache — runs on
+ * renders where nothing about the data actually moved.
+ *
+ * Element-wise identity rather than a deep compare: rows are normally stable objects
+ * owned by a store, so this catches the re-created-wrapper case cheaply. If the
+ * consumer also rebuilds each row object the arrays are reported as different, which
+ * is the safe direction.
+ *
+ * **Why this needs no "repair" step, unlike `mono-button-dropdown`.** That element
+ * compares entries by CONTENT and deliberately ignores function fields, so it reports
+ * "same" for entries that really were rebuilt — leaving cached listener state pointing
+ * at the previous array (hence `_retargetItemParts()`). `arrayHasChanged` says "same"
+ * only when the array holds literally the same objects in the same order, so nothing
+ * item-related can have moved and there is nothing to retarget. Reach for the deeper
+ * compare only where the callbacks are resolved late, and prove it.
+ *
+ * **Do NOT add this (or any `hasChanged`) to these — they hang real work off the
+ * update cycle, so suppressing an update silently drops it:**
+ *   - `chart-core.ts` — `updated()` IS the chart pipeline; its last step `_applyData()`
+ *     is the only place chart.js is redrawn. A skipped update freezes the canvas.
+ *   - `date-core.ts` — `updated()` drives `_rebuild()` / `_applyModelValue()`, so
+ *     flatpickr would be stranded on stale config.
+ *   - every `mono-table-*` element — `table-controller-core.ts` overrides `update()` to
+ *     pull each element's slice of `monoDataGrid({ props })`.
+ *   - every `monoForm`-bound control and `filter-builder-core.ts` — same `update()` hook
+ *     (`form-control-core.ts`), used for form binding and visibility.
+ *
+ * Surveyed 2026-08-17 across all 26 component directories; the guarded props are
+ * `select`/`tag-input` `items`, `tag-input` `modelValue`/`value`, `menu` +
+ * `mono-menu-list` `items`, `tabs` `items`, both `breadcrumb` `items`, and
+ * `file-upload` `modelValue`.
+ */
+export declare function arrayHasChanged(value: unknown, old: unknown): boolean;
+export declare const booleanStringConverter: {
+    fromAttribute(value: unknown): boolean;
+    toAttribute(value: boolean): string | null;
+};
+export declare const numberStringConverter: {
+    fromAttribute(value: string | null): number;
+    toAttribute(value: number): string | null;
+};
+/**
+ * Like {@link numberStringConverter}, but an absent/blank attribute stays
+ * `undefined` instead of collapsing to `0`.
+ *
+ * Needed wherever 0 is a meaningful value AND "not set" has to mean "fall back to
+ * whatever the component computes" — e.g. `mono-modal` / `mono-drawer`'s `z-index`,
+ * where 0 is a legal stacking level and unset means "let the popup stack decide".
+ * Using the plain number converter there would pin every dialog to `z-index: 0`.
+ */
+export declare const optionalNumberConverter: {
+    fromAttribute(value: string | null): number | undefined;
+    toAttribute(value: number | undefined): string | null;
+};
+export declare const stringConverter: {
+    fromAttribute(value: string | null): string;
+    toAttribute(value: string): string | null;
+};

package/dist/src/composables/hydration-flush.d.ts

@@ -0,0 +1,34 @@
+import { ReactiveElement } from 'lit';
+export interface FlushSsrHydrationOptions {
+    /**
+     * Withhold hydration until this returns `true`; polling continues meanwhile.
+     *
+     * Needed for elements that render a LIST from a property the server also
+     * rendered (`:items.prop`): Vue assigns the property asynchronously AFTER
+     * connect, so hydrating early makes the client render fewer children than the
+     * server's `<!--lit-part-->` markers → "Unhandled shorter than expected
+     * iterable" plus a duplicate render. Gate on the client count having caught
+     * up with the server count.
+     */
+    gate?: () => boolean;
+    /** How many ticks to attempt before giving up (default 30). */
+    maxTries?: number;
+}
+/**
+ * Force an SSR'd element's first client update to flush.
+ *
+ * Under `nuxt-ssr-lit` the server-rendered element can stay `hasUpdated: false`
+ * with updates disabled even after `<LitWrapper>` removes `defer-hydration` —
+ * so `render()` never re-runs and its event handlers never bind. The element is
+ * then frozen at whatever the SERVER assumed, while its JS properties keep
+ * taking client values: a silent divergence between the rendered DOM and the
+ * live props.
+ *
+ * Poll `requestUpdate()` for a few ticks until the element reports `hasUpdated`.
+ * A no-op once the element has hydrated normally.
+ *
+ * Scheduling races `requestAnimationFrame` against a `setTimeout` backstop:
+ * rAF does NOT fire in a hidden, minimized, or fully occluded tab, and relying
+ * on it alone leaves the element frozen until the tab is next painted.
+ */
+export declare function flushSsrHydration(el: ReactiveElement, options?: FlushSsrHydrationOptions): void;

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

@@ -0,0 +1,17 @@
+import { TemplateResult } from 'lit';
+/**
+ * Detect whether an icon string is an iconify utility class — e.g.
+ * `i-mdi-close`, `i-tabler-upload`. UnoCSS's preset-icons resolves these to a
+ * background/mask, so components render them as an empty `<span class="i-...">`.
+ *
+ * Single source of truth — components re-export this from their own
+ * `*-utils.ts` so their public API stays stable.
+ */
+export declare function isIconifyClass(icon: string | undefined | null): boolean;
+/**
+ * Draw an `i-mdi-*` glyph as inline SVG — the SHADOW builds' counterpart to the
+ * light builds' UnoCSS mask. Both come from `@iconify-json/mdi`, so one `icon`
+ * value paints the same artwork in either build. Returns `undefined` when the
+ * glyph is not bundled (see `scripts/mdi-glyphs.mjs`), so a caller can fall back.
+ */
+export declare function mdiGlyph(icon: string | undefined | null): TemplateResult | undefined;

package/dist/src/composables/layout-var.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Refcounted document-level layout variables.
+ *
+ * Several components publish their own size as a custom property on
+ * `document.documentElement` so page content can offset itself —
+ * `--mono-nav-height`, `--mono-sidebar-left-width`, `--mono-sidebar-right-width`.
+ * The property is global but the writers are not: two navs, or two sidebars on the
+ * same side, all write the SAME property.
+ *
+ * Removing it outright on the first unmount blanked the offset for every writer that
+ * was still mounted — the page content jumped back underneath a nav or sidebar that
+ * is still on screen. That bug was found independently in BOTH `mono-sidebar` and
+ * `mono-nav`, which is why the fix lives here rather than being written twice.
+ *
+ * Ownership is therefore refcounted: the property is removed only when the LAST
+ * owner releases it, and until then it is handed back to a remaining owner's last
+ * known value. Note that a refcount has two failure modes — releasing too early
+ * (survivor loses the var) and never reaching zero (the var is stranded on the
+ * document forever). Both are covered by assertions in `docs/e2e/stress.mjs` (repo root).
+ */
+/**
+ * Publish `value` for `name` on behalf of `owner`.
+ *
+ * Re-claiming with the same owner just updates that owner's value, so this is safe
+ * to call on every render.
+ */
+export declare function claimLayoutVar(name: string, owner: object, value: string): void;
+/**
+ * Drop `owner`'s claim on `name`.
+ *
+ * The property is only removed once nobody holds it; while another owner remains,
+ * that owner's last published value is restored instead.
+ */
+export declare function releaseLayoutVar(name: string, owner: object): void;

package/dist/src/composables/light-slots.d.ts

@@ -0,0 +1,133 @@
+/** Captured nodes, keyed by slot name, in document order. */
+export type LightSlotBuckets = Map<string, Node[]>;
+export interface CaptureLightSlotsOptions {
+    /** Named `slot="…"` values this component lays out. */
+    names: readonly string[];
+    /** Bucket for unnamed content and framework anchors. Default `'default'`. */
+    fallback?: string;
+    /**
+     * Install the `textContent` guard on the host (default `true`). Opt out only for
+     * a component that never renders a `[data-mono-slot]` region for `fallback`.
+     */
+    guardTextContent?: boolean;
+}
+/**
+ * Take ownership of the host's current children. Run **once**, from
+ * `connectedCallback`, before the first render.
+ *
+ * Only nodes that were bucketed are detached from the host — anything left
+ * unclaimed stays exactly where the consumer put it.
+ */
+export declare function captureLightSlots(host: HTMLElement, options: CaptureLightSlotsOptions): LightSlotBuckets;
+export interface HostTextGuardOptions {
+    /** Bucket a bare text write lands in. Default `'default'`. */
+    fallback?: string;
+    /**
+     * Ran after a write that changed the captured content — normally
+     * `requestUpdate()`, because slot emptiness is read during render and is not
+     * itself reactive.
+     */
+    onWrite?: () => void;
+}
+/**
+ * Redirect `host.textContent = …` into the captured default region.
+ *
+ * A light-DOM component renders into its own host, so the host's children are the
+ * component. Vue compiles a lone interpolation to a `TEXT`-flagged vnode and
+ * patches it with `el.textContent = next` (`runtime-dom`'s `setElementText`) —
+ * on the HOST. That single assignment removes every rendered node, Lit's
+ * `<!--lit-part-->` markers included, and replaces them with one bare text node:
+ * the component visually disappears and no later render repairs it, because
+ * Lit's parts now point at detached nodes. `patchChildren` does the same when
+ * children go array→text or are cleared, and so does `v-text`.
+ *
+ * Static text never hit this (Vue skips the write when the string is unchanged),
+ * which is why it only showed up on dynamic captions. Shadow builds are immune —
+ * there the host's children really are slotted content.
+ *
+ * So the write is intercepted and applied to the text node the consumer already
+ * owns inside `[data-mono-slot="<fallback>"]`, which is what the framework meant
+ * by it anyway. Framework anchors (zero-length text nodes, comments) and element
+ * children are left alone — repurposing an anchor would break the consumer's next
+ * patch just as badly as dropping one.
+ *
+ * `innerHTML` is deliberately not guarded: only `v-html` on the host reaches it,
+ * and that is a consumer asking to own the element outright.
+ */
+export declare function guardHostTextContent(host: HTMLElement, buckets: LightSlotBuckets, options?: HostTextGuardOptions): void;
+/**
+ * Move one captured node into its region — unless the consumer has taken it back.
+ *
+ * The obvious form of this, `if (node.parentNode !== target) target.appendChild(node)`,
+ * cannot tell "not placed yet" from "the framework DELETED this". A child behind a
+ * `v-if` that flips false ends up with `parentNode === null`, looks unplaced, and the
+ * very next render puts it straight back: the element **resurrects** and no amount of
+ * consumer state removes it. That was reproduced in `mono-accordion` and `mono-input`
+ * and the same loop was copied into every light-DOM component.
+ *
+ * So: place freely until a node has been placed once. After that, only re-home it
+ * while it is still inside one of OUR regions — which is what happens when a
+ * re-render swaps the region element, the case the original guard existed for. A
+ * null parent means deleted and any other parent means the consumer moved it; both
+ * are left alone.
+ */
+export declare function placeSlotNode(target: Element, node: Node): void;
+/**
+ * Move captured nodes into their `[data-mono-slot]` regions. Run from `updated()`,
+ * after Lit has rendered them.
+ *
+ * Nodes already sitting in the right region are left untouched — that guard is
+ * what stops a re-render from re-ordering content the consumer's framework
+ * inserted after capture. See {@link placeSlotNode} for why "not in the target"
+ * is not enough on its own.
+ */
+export declare function placeLightSlots(host: HTMLElement, buckets: LightSlotBuckets): void;
+/**
+ * Park captured nodes that couldn't be placed — because their `[data-mono-slot]`
+ * target isn't rendered (a slot naming an item that doesn't exist *yet*, e.g. one
+ * bound to async-loaded data) — in a detached holder so they always keep a live
+ * parent. A captured node left with `parentNode === null` crashes the consumer
+ * framework's next patch (`Cannot read properties of null`); any parent avoids that
+ * while keeping the node invisible until its real target appears and placement moves
+ * it out. Returns the holder (created lazily on first orphan) so the caller can cache
+ * it. Pass the previously-returned holder back in on later calls.
+ */
+export declare function parkDetachedNodes(holder: HTMLElement | undefined, nodes: Iterable<Node>): HTMLElement | undefined;
+/**
+ * Whether a bucket holds anything the user can actually see — used to decide
+ * whether a region is worth rendering.
+ *
+ * Comments are explicitly excluded: an anchor like `<!--v-if-->` has a non-blank
+ * `textContent`, so a naive check would report an empty region as occupied.
+ */
+export declare function bucketHasContent(nodes: Node[] | undefined): boolean;
+/**
+ * Watches a host for a named slot child that arrives AFTER `connectedCallback`.
+ *
+ * The one-shot capture the light builds do at connect is right for the common case — a framework
+ * mounts an element's children before inserting it — but it is not the only case. A `<ClientOnly>`
+ * boundary, a hydration pass, or a `v-if` flipping later all append the child to an element that
+ * is already connected, and a capture that has already run will never see it. In the light build
+ * that leaves the node sitting in the host's own flow, visible OUTSIDE the region it was meant
+ * for; in the shadow build the flag that renders the `<slot>` never turns on, so nothing projects.
+ *
+ * Deliberately not a Lit controller: it has to work from inside a mixin whose host may be either
+ * build, and all it needs is connect/disconnect.
+ */
+export declare class LateSlotWatcher {
+    private readonly host;
+    private readonly name;
+    private readonly onFound;
+    private _observer?;
+    constructor(host: Element, name: string, onFound: () => void);
+    /**
+     * The host's own child carrying `slot="<name>"`, or `null`.
+     *
+     * Walks `children` rather than running a `:scope >` selector — only a DIRECT child is
+     * assignable to a slot, and this way the check is one cheap loop over a handful of nodes with
+     * no selector engine involved.
+     */
+    find(): Element | null;
+    start(): void;
+    stop(): void;
+}

package/dist/src/composables/mdi-glyphs.d.ts

@@ -0,0 +1,4 @@
+/** `i-mdi-<name>` → the inner SVG markup of that glyph, on a 24x24 viewBox. */
+export declare const MDI_GLYPHS: Readonly<Record<string, string>>;
+/** The artwork for an `i-mdi-*` class, or `undefined` when it is not bundled. */
+export declare function mdiGlyphBody(icon: string | undefined | null): string | undefined;