@mono-lit/helper 0.0.0-stage → 0.0.1

package/dist/src/components/menu/mono-menu-list.d.ts

@@ -0,0 +1,118 @@
+import { LitElement, TemplateResult } from 'lit';
+import { MenuItem, MenuBadgeColor, MonoMenuListType } from './menu-types.js';
+export declare class MonoMenuList extends LitElement {
+    protected createRenderRoot(): HTMLElement;
+    /**
+     * For normal list mode:
+     *   <mono-menu-list :items.prop="items" />
+     *
+     * For direct single-row mode (one row built from element props):
+     *   <mono-menu-list type="group" title="Sales" :items.prop="children" />
+     *
+     * For declarative composition (any depth, any HTML inside):
+     *   <mono-menu-list type="group" title="Group">
+     *     <mono-menu-list type="children" title="Item A"></mono-menu-list>
+     *     <mono-menu-list type="group" title="Subgroup">…</mono-menu-list>
+     *   </mono-menu-list>
+     *
+     * In single-row mode, this `items` array becomes the built item's `children`.
+     */
+    items: MenuItem[];
+    /** New behavior: render exactly one menu row from a full object. */
+    item?: MenuItem;
+    /** Render mode / declarative MenuItem.type — see header doc. */
+    type: MonoMenuListType;
+    /** Direct single-row props. Legacy alias for `type` in declarative mode. */
+    itemType?: MenuItem['type'];
+    title: string;
+    subtitle: string;
+    icon: string;
+    appendIcon: string;
+    badge?: string | number;
+    badgeColor?: MenuBadgeColor;
+    href: string;
+    disabled: boolean;
+    defaultOpen: boolean;
+    private _parent;
+    private _parentList;
+    private _rootList;
+    private _nestedChildren;
+    /** Captured DOM children, re-placed into [data-mono-slot="body"] after render. */
+    private _capturedChildren;
+    /** Idempotency guard — initial capture must run once per element lifetime,
+     *  not again on reconnect (otherwise Lit's marker comments get hijacked). */
+    private _childrenCaptured;
+    /** Standalone group-open state — only honored on the root-most list. */
+    private _standaloneOpen;
+    private _childObserver;
+    private readonly _autoId;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    willUpdate(changed: Map<PropertyKey, unknown>): void;
+    protected updated(_changed: Map<PropertyKey, unknown>): void;
+    getMenuItems(): MenuItem[];
+    /** @internal called by a nested `<mono-menu-list>` from its connectedCallback. */
+    _registerNestedChild(child: MonoMenuList): void;
+    /** @internal */
+    _unregisterNestedChild(child: MonoMenuList): void;
+    /** Standalone (no `<mono-menu>`) group-open queries — root-most list owns the set. */
+    isGroupOpenStandalone(id: string): boolean;
+    /** Seed a default-open id into the standalone state set. */
+    seedStandaloneOpen(id: string): void;
+    toggleGroupStandalone(id: string): void;
+    private _findRootList;
+    private _captureInitialChildren;
+    /**
+     * Capture external Element children that landed on the host AFTER Lit's
+     * most recent render — typically because a framework (Vue/React) inserted
+     * nodes via `v-for`, `v-if`, etc. We deliberately skip non-Element nodes
+     * (text / comment) because Lit places its own marker comments around the
+     * rendered region and stealing those breaks the part graph.
+     */
+    private _captureExternalSiblings;
+    private _setupChildObserver;
+    private _placeBodySlot;
+    private _hasCapturedChildren;
+    private _hasDirectItemProps;
+    /**
+     * Declarative mode: `type` describes MenuItem.type and the body is composed
+     * from captured DOM children instead of `items`.
+     *
+     * The order of the checks is the contract. Captured children win outright —
+     * they ARE the body. An explicit `items` array comes next, and specifically
+     * BEATS direct props: the previous order returned `true` as soon as any direct
+     * prop was set, so `<mono-menu-list type="group" title="Sales" :items.prop="kids">`
+     * — the single-row form documented in the class header and in `MenuListProps` —
+     * landed in declarative mode. `_buildDeclarativeItem()` drops `items` on
+     * purpose, so that row rendered an empty `[data-mono-slot="body"]` nothing was
+     * ever placed into, and `_buildDirectItem()` (the one branch that does carry
+     * `items`) was unreachable.
+     *
+     * It doubles as a safety net for the element form: a group whose DOM children
+     * never made it into `_capturedChildren` now falls back to its `items` array
+     * rather than rendering a chevron over an empty body.
+     */
+    private _isDeclarativeMode;
+    private _typeAsMenuItemType;
+    private _normalizeItem;
+    private _buildDirectItem;
+    private _buildDeclarativeItem;
+    private _getEffectiveItems;
+    private _seedDefaultOpenIntoParent;
+    /**
+     * A group is "active" while any descendant row is the selected one.
+     * `renderMenuGroup` puts `.mono-menu-group.active` on such a header and
+     * menu.css already styles it — the class simply never appeared, because
+     * nothing supplied this callback.
+     */
+    private _hasSelectedDescendant;
+    private _buildContext;
+    private _renderSingleRow;
+    private _seedDefaultOpenIntoStandalone;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'mono-menu-list': MonoMenuList;
+    }
+}

package/dist/src/components/menu/mono-menu.d.ts

@@ -0,0 +1,39 @@
+import { LitElement, TemplateResult } from 'lit';
+declare const MonoMenu_base: import('../../composables/hybird-prop').Constructor<import('./menu-core.js').MonoMenuCoreInterface> & typeof LitElement;
+/**
+ * Light-DOM `mono-menu` (`@mono-lit/helper/ui/menu`).
+ *
+ * Renders into `this` (`createRenderRoot()=>this`) and keeps the full light-DOM
+ * feature set: declarative `slot="body"` composition with `<mono-menu-list>`
+ * children, per-item `slot="icon-${id}"` slots, and the child registry. All
+ * render-mode-agnostic logic (props, selection/open state, events, public API)
+ * lives in `MonoMenuCore`.
+ */
+export declare class MonoMenu extends MonoMenu_base {
+    static styles: import('lit').CSSResult[];
+    protected createRenderRoot(): HTMLElement;
+    private _slotsCaptured;
+    private _hasBodySlot;
+    /** Captured nodes for the whole-body slot — `slot="body"`. */
+    private _slotBody;
+    private _orphanHolder?;
+    connectedCallback(): void;
+    private _captureSlots;
+    protected updated(changed: Map<string, unknown>): void;
+    private _placeIconSlots;
+    private _placeBodySlot;
+    /**
+     * When any prop that influences the rendered content of descendant
+     * `<mono-menu-list>` instances changes, ask each registered child to
+     * re-render so they stay in lockstep with the parent.
+     */
+    private _notifyListChildren;
+    /** Light body — declarative `slot="body"` placeholder, else items-driven. */
+    protected _renderBody(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'mono-menu': MonoMenu;
+    }
+}
+export {};

package/dist/src/components/menu/mono-menu.shadow.d.ts

@@ -0,0 +1,40 @@
+import { LitElement, TemplateResult } from 'lit';
+declare const MonoMenuShadow_base: import('../../composables/hybird-prop').Constructor<import('./menu-core.js').MonoMenuCoreInterface> & typeof LitElement;
+/**
+ * Shadow-DOM `mono-menu` (SSR build, `@mono-lit/helper/ui/shadow/menu`).
+ *
+ * Real shadow root + `static styles`, so `@lit-labs/ssr` serializes it to
+ * Declarative Shadow DOM. Renders the WHOLE tree (items + nested groups) from
+ * the `items` prop inside this single shadow root — so every menu CSS rule
+ * applies, and the active item is server-rendered from the reflected
+ * `model-value`.
+ *
+ * Icons: `i-mdi-…` utility classes can't resolve inside a shadow root, so each
+ * item's icon is rendered as a native `<slot name="icon-<id>">` (see
+ * `renderMenuIcon` + `iconSlot`), and this element creates the matching
+ * LIGHT-DOM `<span slot="icon-<id>" class="i-…">` children itself in `updated()`.
+ * Those light spans are styled by the page's GLOBAL UnoCSS (exactly like
+ * `mono-input`'s slotted prefix icon), so the real glyphs paint — client-side,
+ * after hydration (empty on the server). The group chevron is inline SVG.
+ *
+ * Shares all logic with the light build via `MonoMenuCore`. Both register
+ * `mono-menu`, so a document loads only one build.
+ */
+export declare class MonoMenuShadow extends MonoMenuShadow_base {
+    static styles: import('lit').CSSResult[];
+    protected _useIconSlots(): boolean;
+    /** Inline mdi-chevron-right — the UnoCSS icon class can't resolve in shadow. */
+    protected _chevronSvg(): TemplateResult;
+    connectedCallback(): void;
+    protected firstUpdated(changed: Map<string, unknown>): void;
+    protected updated(changed: Map<string, unknown>): void;
+    /**
+     * Reconcile LIGHT-DOM icon spans (this element's own children) with the items
+     * tree. Each becomes a `<span slot="icon-<id>" class="mono-menu-iconify i-…">`
+     * that projects into the shadow `<slot name="icon-<id>">` and is styled by the
+     * page's global UnoCSS. Client-only — the server has no DOM, so icons paint at
+     * hydration (the empty `<slot>` matches the server render → no mismatch).
+     */
+    private _syncLightIcons;
+}
+export {};

package/dist/src/components/modal/index.d.ts

@@ -0,0 +1,4 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoModal } from './mono-modal.js';
+export { monoModal, controlMonoModal } from './mono-modal-controller.js';
+export type { ModalSize, ModalDimensionPreset, ModalDimension, ModalColor, ModalSource, ModalCssClass, ModalCloseEventDetail, ModalCloseEvent, ModalProps, ModalEvents, MonoDialogButton, MonoDialogButtonCtx, MonoDialogOptions, MonoDialogController, MonoModalOptions, MonoModalController, MonoModalElementLike, } from './modal-types.js';

package/dist/src/components/modal/index.shadow.d.ts

@@ -0,0 +1,5 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoModalShadow } from './mono-modal.shadow.js';
+export { MonoModalCore, type ModalSlotName } from './modal-core.js';
+export { monoModal, controlMonoModal } from './mono-modal-controller.js';
+export type { ModalSize, ModalDimensionPreset, ModalDimension, ModalColor, ModalSource, ModalCssClass, ModalCloseEventDetail, ModalCloseEvent, ModalProps, ModalEvents, MonoDialogButton, MonoDialogButtonCtx, MonoDialogOptions, MonoDialogController, MonoModalOptions, MonoModalController, MonoModalElementLike, } from './modal-types.js';

package/dist/src/components/modal/modal-core.d.ts

@@ -0,0 +1,110 @@
+import { LitElement, TemplateResult } from 'lit';
+import { StyleInfo } from 'lit/directives/style-map.js';
+import { ModalSize, ModalColor, ModalSource, ModalCssClass } from './modal-types.js';
+import { Constructor } from '../../composables/hybird-prop';
+import { PopupLayer } from '../../composables/popup-stack';
+import { MonoAutoFullscreen } from '../../composables/breakpoints';
+/**
+ * Named slots projected by `mono-modal` (light: captured; shadow: native).
+ *
+ * These are the INTERNAL region names. Consumers may also write `slot="header"`
+ * and `slot="footer"` — the drawer's vocabulary — which alias `head` and `foot`.
+ * When both spellings are supplied for the same region **the alias wins**; the
+ * losing nodes are parked and never rendered.
+ *
+ * `head` (`header`) replaces the heading COLUMN — title + subtitle — and beats
+ * the `title` / `subtitle` slots and props. The close ✕ always stays.
+ */
+export type ModalSlotName = 'head' | 'title' | 'subtitle' | 'body' | 'foot';
+type ModalSizeValue = string | number | undefined;
+/**
+ * `MonoModalCore` — render-mode-agnostic logic for `mono-modal`: props/hybrid
+ * aliases, the open/close model (`show`/`hide`/`toggle` + `mno-*` events), the
+ * `PopupLayer` surface (shared z-stack / scroll-lock / topmost-Escape via the
+ * SSR-safe `popup-stack`), draggable-header logic, sizing, and the shared modal
+ * markup (`_renderModalBody`). SSR-safe: `popup-stack` no-ops server-side and the
+ * `window`/drag access is `isServer`-guarded.
+ *
+ * Each build supplies the render root + slot/icon strategy:
+ *  - light (`mono-modal.ts`): renders into a `<body>` portal that IS the
+ *    `.mono-modal` root, `data-mono-slot` placeholders, UnoCSS `.i-mdi-close`.
+ *  - shadow (`mono-modal.shadow.ts`): a real shadow root with an inner
+ *    `.mono-modal` root, native `<slot>`s, inline-SVG ✕ (mirrors dropdown).
+ */
+export declare const MonoModalCore: <T extends Constructor<LitElement>>(superClass: T) => Constructor<MonoModalCoreInterface> & T;
+/** Public + shared-protected surface added by the core mixin. */
+export declare class MonoModalCoreInterface implements PopupLayer {
+    size: ModalSize;
+    color: ModalColor;
+    title: string;
+    subtitle: string;
+    modelValue: boolean;
+    dismissible: boolean;
+    persistent: boolean;
+    overlay: boolean;
+    closeOnEscape: boolean;
+    closeOnOverlay: boolean;
+    lockScroll: boolean;
+    draggable: boolean;
+    stackable: boolean;
+    autoFullscreen: MonoAutoFullscreen;
+    cssClass: ModalCssClass;
+    cssClassName: string;
+    width?: ModalSizeValue;
+    height?: ModalSizeValue;
+    minWidth?: ModalSizeValue;
+    maxWidth?: ModalSizeValue;
+    minHeight?: ModalSizeValue;
+    maxHeight?: ModalSizeValue;
+    zIndex?: number;
+    show(source?: ModalSource, sourceEvent?: Event): void;
+    hide(source?: ModalSource, sourceEvent?: Event): void;
+    toggle(source?: ModalSource, sourceEvent?: Event): void;
+    get lockBodyScroll(): boolean;
+    get hasBackdrop(): boolean;
+    get pinnedZ(): number | undefined;
+    onStackEscape(event: KeyboardEvent): void;
+    setStackZ(z: number, isTopBackdrop: boolean): void;
+    protected _slotsCaptured: boolean;
+    protected _hasHeadSlotState: boolean;
+    protected _hasTitleSlotState: boolean;
+    protected _hasSubtitleSlotState: boolean;
+    protected get _headingState(): {
+        title: boolean;
+        subtitle: boolean;
+        heading: boolean;
+    };
+    protected get _headingIdBase(): string;
+    protected _headingAria(): {
+        labelledby?: string;
+        describedby?: string;
+    };
+    protected _hasBodySlotState: boolean;
+    protected _hasFootSlotState: boolean;
+    protected _modalZ: number;
+    protected get _effectiveZ(): number;
+    protected _panelEl?: HTMLElement;
+    protected get _isMonoModal(): boolean;
+    protected get _isFullscreen(): boolean;
+    protected _panelSizeStyle(): StyleInfo;
+    protected _computeModalClasses(): string[];
+    protected _setCssClass(value: unknown): void;
+    protected _cls(base: string, key: keyof ModalCssClass): string;
+    protected _computeRootAttrs(): Record<string, string | null>;
+    protected _applyRootAttrs(root: HTMLElement | null | undefined): void;
+    protected bindRoot: (el: Element | undefined) => void;
+    /** The shadow build's inner root, bound by `bindRoot` — it re-applies the
+     *  state attributes from its own `updated()`. */
+    protected _rootEl: HTMLElement | null;
+    protected _toBoolean(value: unknown): boolean;
+    protected _applyOpenSideEffects(): void;
+    protected _releaseSideEffects(): void;
+    protected _onHeaderPointerDown: (event: PointerEvent) => void;
+    protected _renderModalBody(): TemplateResult;
+    protected get _slotsAlwaysRender(): boolean;
+    protected _hasSlot(name: ModalSlotName): boolean;
+    protected _setSlotState(name: ModalSlotName, has: boolean): void;
+    protected _slotOutlet(name: ModalSlotName, fallback?: unknown): TemplateResult;
+    protected renderIcon(name: 'close'): TemplateResult;
+}
+export {};

package/dist/src/components/modal/modal-types.d.ts

@@ -0,0 +1,304 @@
+import { MonoBreakpoint } from '../../composables/breakpoints';
+import { ButtonProps } from '../button/button-types.js';
+import { MonoEventProps } from '../../composables/element-props.js';
+/**
+ * Content scale of the modal — header/title font, body font, paddings, close button
+ * and corner radius. The same 6-step scale accordion and the form controls use.
+ *
+ * It does **not** set the panel's width. That is what `width` / `min-width` /
+ * `max-width` (and `--mono-modal-width`) are for, so a compact `size="sm"` dialog can
+ * still be wide and a roomy `size="xl"` one can still be narrow. Before 2026-08-17
+ * `size` was a width preset and did nothing to the type scale.
+ */
+export type ModalSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+/**
+ * Named dimension presets accepted by `width`, `height` and the four `min-*` /
+ * `max-*` props.
+ *
+ * The same six tokens as {@link ModalSize}, on a different axis — `size` scales the
+ * CONTENT, these name a MEASURE. Widths are `min(90vw, 300px)` … `min(95vw, 1080px)`
+ * (`md` = the modal's default `min(90vw, 520px)`); heights are `22vh` … `95vh`
+ * (`md` = `50vh`), matching the drawer's ladder.
+ */
+export type ModalDimensionPreset = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+/**
+ * A sizing-prop value: a {@link ModalDimensionPreset} token, any CSS length string,
+ * or a number / numeric string read as px.
+ *
+ * The `string & {}` arm keeps the token list in editor autocomplete without
+ * narrowing the type — `"32rem"` is still perfectly valid.
+ */
+export type ModalDimension = ModalDimensionPreset | (string & {}) | number;
+export type ModalColor = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'teal' | 'purple' | 'neutral' | 'dark';
+export type ModalSource = 'overlay' | 'close' | 'escape' | 'manual';
+export interface ModalCssClass {
+    root?: string;
+    overlay?: string;
+    panel?: string;
+    head?: string;
+    /** The heading column inside the head (title + subtitle, or `slot="header"`). */
+    heading?: string;
+    title?: string;
+    subtitle?: string;
+    close?: string;
+    body?: string;
+    foot?: string;
+}
+/** Shared detail for modal `toggle` / `open` / `close` events. */
+export type ModalCloseEventDetail = {
+    modelValue: boolean;
+    currentValue: boolean;
+    oldValue: boolean;
+    value: boolean;
+    source: ModalSource;
+    sourceEvent?: Event;
+};
+/** Alias — the same detail is carried by every modal state-change event. */
+export type ModalChangeEventDetail = ModalCloseEventDetail;
+/** Fired on every state change. */
+export type ModalClickEvent = CustomEvent<ModalChangeEventDetail>;
+/** Fired on the false → true transition only. */
+export type ModalOpenEvent = CustomEvent<ModalChangeEventDetail>;
+/** Fired on the true → false transition only. */
+export type ModalCloseEvent = CustomEvent<ModalCloseEventDetail>;
+export interface ModalProps {
+    /** Open state, two-way bound for v-model-style usage. */
+    modelValue?: boolean;
+    'model-value'?: boolean;
+    modelvalue?: boolean;
+    /** Width preset of the modal panel. */
+    size?: ModalSize;
+    /** Theme color applied to accents. */
+    color?: ModalColor;
+    /** Heading text shown in the modal header. `slot="title"` replaces it. */
+    title?: string;
+    /**
+     * Secondary line under the title — muted and smaller, hidden when empty.
+     * `slot="subtitle"` replaces it; `slot="header"` replaces title + subtitle
+     * together (the close ✕ stays).
+     */
+    subtitle?: string;
+    /** Shows the close button and allows dismissal. */
+    dismissible?: boolean;
+    /** Prevents closing via overlay click or escape. */
+    persistent?: boolean;
+    /** Renders a backdrop overlay behind the panel. */
+    overlay?: boolean;
+    /** Closes the modal when the Escape key is pressed. */
+    closeOnEscape?: boolean;
+    'close-on-escape'?: boolean;
+    closeonescape?: boolean;
+    /** Closes the modal on a click outside the panel: the overlay, or — with `overlay: false` — the page itself (the click still reaches the page). */
+    closeOnOverlay?: boolean;
+    'close-on-overlay'?: boolean;
+    closeonoverlay?: boolean;
+    /** Locks body scroll while the modal is open. */
+    lockScroll?: boolean;
+    'lock-scroll'?: boolean;
+    lockscroll?: boolean;
+    /** Allow dragging the modal by its header; it snaps back inside the viewport on drop. */
+    draggable?: boolean;
+    /**
+     * Fill the screen at a breakpoint and below (default `false`). `auto-fullscreen`
+     * on its own means Tailwind's `sm` (< 640px); a token moves the boundary, so
+     * `auto-fullscreen="lg"` covers everything `lg:` does not match (< 1024px).
+     */
+    autoFullscreen?: boolean | MonoBreakpoint;
+    'auto-fullscreen'?: boolean | MonoBreakpoint;
+    autofullscreen?: boolean | MonoBreakpoint;
+    /**
+     * Allow this modal to stack on top of others. When false (default) it is
+     * exclusive — opening it closes any other open modals.
+     */
+    stackable?: boolean;
+    /**
+     * Explicit panel sizing. Each accepts a preset token (`"xs"`…`"xxl"` — see
+     * {@link ModalDimensionPreset}), a CSS length string (`"12px"`, `"12rem"`,
+     * `"80%"`), or a number / numeric string (interpreted as px).
+     * Set both `width` and `height` to `"100%"` for true full-screen.
+     */
+    width?: ModalDimension;
+    height?: ModalDimension;
+    minWidth?: ModalDimension;
+    'min-width'?: ModalDimension;
+    minwidth?: ModalDimension;
+    maxWidth?: ModalDimension;
+    'max-width'?: ModalDimension;
+    maxwidth?: ModalDimension;
+    minHeight?: ModalDimension;
+    'min-height'?: ModalDimension;
+    minheight?: ModalDimension;
+    maxHeight?: ModalDimension;
+    'max-height'?: ModalDimension;
+    maxheight?: ModalDimension;
+    /**
+     * Pin the modal to an explicit stacking level. Unset (the default) lets the
+     * shared popup stack assign one so the newest layer is always on top. The value
+     * is the overlay's `z-index`; the panel sits one above it.
+     */
+    zIndex?: number | string;
+    'z-index'?: number | string;
+    zindex?: number | string;
+    /** Per-part class overrides for internal elements. */
+    cssClass?: ModalCssClass;
+    cssclass?: ModalCssClass;
+    'css-class'?: ModalCssClass | string;
+    /** Plain root class string applied to the modal. */
+    cssClassName?: string;
+    /**
+     * The controller (`monoModal()` / `controlMonoModal()`) driving this modal. Bind
+     * with `.prop`: `:control-modal.prop="modal"`. `dataModal` is the same field.
+     */
+    controlModal?: MonoModalController;
+    'control-modal'?: MonoModalController;
+    controlmodal?: MonoModalController;
+    dataModal?: MonoModalController;
+    'data-modal'?: MonoModalController;
+    datamodal?: MonoModalController;
+}
+export interface ModalEvents {
+    toggle: ModalClickEvent;
+    open: ModalOpenEvent;
+    close: ModalCloseEvent;
+    'mno-click': ModalClickEvent;
+    mnoClick: ModalClickEvent;
+    'mno-open': ModalOpenEvent;
+    mnoOpen: ModalOpenEvent;
+    'mno-close': ModalCloseEvent;
+    mnoClose: ModalCloseEvent;
+}
+/**
+ * One action of a programmatic dialog: every `<mono-button>` prop plus the
+ * dialog wiring. `handler` is deliberately NOT accepted — `onClick` is the one
+ * hook, and it already owns the spinner (see below).
+ */
+export interface MonoDialogButton extends Omit<ButtonProps, 'handler'> {
+    /** Button text (the button's default slot). */
+    label?: string;
+    /** Iconify class for the leading icon, e.g. `i-mdi-check`. */
+    icon?: string;
+    /** Extra class on the button element. */
+    className?: string;
+    /**
+     * The answer this button gives: once `onClick` settles, the dialog closes and
+     * `show()` resolves with this value — for when the code AFTER `await show()`
+     * decides what happens. Without it the button leaves the dialog open unless
+     * `onClick` closes it itself (a "see details" link, say).
+     */
+    value?: unknown;
+    /**
+     * The button's work, run on the click. `ctx.dialog` is the dialog controller;
+     * a button that does its own work ends with a bare `dialog.close()` — it
+     * already knows it was pressed, so there is nothing to report. Returning a
+     * promise keeps the button's spinner on (and defers the `value` close) until
+     * it settles; a rejection keeps the dialog open.
+     */
+    onClick?: (event: MouseEvent, ctx: MonoDialogButtonCtx) => unknown | Promise<unknown>;
+}
+/** Handed to a dialog button's `onClick`, after the click event. */
+export interface MonoDialogButtonCtx {
+    /**
+     * The dialog — `close(value?)`, `isOpen`, `element`, `setProps`. The same
+     * object as `modal.dialog`.
+     */
+    dialog: MonoDialogController;
+    /** The `<mono-button>` that was pressed. */
+    button: HTMLElement;
+}
+/**
+ * The programmatic dialog: a compact `<mono-modal>` the controller builds by code
+ * on every `show()`. It is a QUESTION — the user must answer it — so it cannot be
+ * dismissed: no ✕, no overlay click, no Escape. The only way out is a button
+ * that answers — through its `value`, or `dialog.close()` from its `onClick` —
+ * or `dialog.close()` from code.
+ */
+export interface MonoDialogOptions {
+    /** Header text. No header at all when omitted (together with `subtitle`). */
+    title?: string;
+    /** Secondary line under the title, muted and smaller. */
+    subtitle?: string;
+    /** The question. A string is rendered as HTML; a Node is appended as-is. */
+    body?: string | Node;
+    /** The actions, centred under the body. */
+    buttons?: MonoDialogButton[];
+    /** Which button gets focus once open (index), or `'none'`. Default `0`. */
+    focus?: number | 'none';
+    /**
+     * Overrides for the dialog's own `<mono-modal>` — `color`, `size`, `width`,
+     * `zIndex`, `cssClass`… — merged over the compact defaults. The dismissal
+     * locks (`persistent`, `dismissible: false`, `closeOnEscape: false`) are applied
+     * AFTER this and cannot be overridden. Takes the modal's events as `on<Event>`
+     * keys too (`onOpen`, `onClose`, …).
+     */
+    props?: Partial<ModalProps> & MonoEventProps<ModalEvents>;
+}
+export interface MonoDialogController {
+    /**
+     * Build, open and await the dialog. `override` is merged over the options the
+     * controller was created with, for this show only. Resolves with the value the
+     * answering button supplied — its `value`, or what its `onClick` passed to
+     * `dialog.close(value)` — `false` when `close()` is called bare, and `false`
+     * when a second `show()` pre-empts it.
+     */
+    show<T = boolean>(override?: Partial<MonoDialogOptions>): Promise<T>;
+    /** Close the open dialog, resolving its `show()` with `value` (default `false`). */
+    close(value?: unknown): void;
+    /** Whether a dialog is currently open. */
+    readonly isOpen: boolean;
+    /** The open dialog's `<mono-modal>` element, or `null`. */
+    readonly element: HTMLElement | null;
+    /** Merge new defaults for future `show()`s. */
+    setProps(patch: Partial<MonoDialogOptions>): void;
+}
+export interface MonoModalOptions {
+    /**
+     * Props pushed onto every `<mono-modal>` bound with `:control-modal.prop`. They
+     * WIN over the same attribute written on the element (matching `monoForm`'s
+     * `setProp`). The modal's events are accepted as `on<Event>` keys — `onOpen`,
+     * `onClose`, `onToggle`, … — and attached to every bound element as listeners.
+     */
+    props?: Partial<ModalProps> & MonoEventProps<ModalEvents>;
+    /** Defaults for the programmatic dialog — see {@link MonoDialogOptions}. */
+    dialog?: MonoDialogOptions;
+}
+/**
+ * What `monoModal()` / `controlMonoModal()` returns.
+ *
+ * Two independent halves: the bound-modal half (`open` / `close` / `setProps`)
+ * drives the `<mono-modal>` elements bound to it and never touches the dialog;
+ * the `dialog` half builds its own element per `show()` and never touches the
+ * bound ones.
+ */
+export interface MonoModalController {
+    /** The stable props object every bound element pulls on notify. */
+    props(): Partial<ModalProps>;
+    /** Merge into `props()` and notify the bound elements. */
+    setProps(patch: Partial<ModalProps>): void;
+    /** Open the bound modal(s) — `show('manual')`, so `open` fires. */
+    open(): void;
+    /** Close the bound modal(s) — `hide('manual')`, so `close` fires. */
+    close(): void;
+    toggle(): void;
+    /** Open state of the bound modal; follows user-driven closes (✕, overlay, Escape) too. */
+    readonly isOpen: boolean;
+    /** The first bound `<mono-modal>`, or `null`. */
+    readonly element: HTMLElement | null;
+    /** The programmatic dialog. */
+    readonly dialog: MonoDialogController;
+    /** Called after every state or props change. Returns an unsubscribe. */
+    subscribe(cb: () => void): () => void;
+    /** Closes an open dialog (resolving `false`), drops subscribers and bindings. */
+    dispose(): void;
+    /** @internal element plumbing */
+    _register(el: MonoModalElementLike): void;
+    /** @internal */
+    _unregister(el: MonoModalElementLike): void;
+    /** @internal the element reports its own open/close transitions */
+    _report(open: boolean, source: ModalSource): void;
+}
+/** The slice of a `<mono-modal>` the controller drives. */
+export interface MonoModalElementLike {
+    modelValue: boolean;
+    show(source?: ModalSource, sourceEvent?: Event): void;
+    hide(source?: ModalSource, sourceEvent?: Event): void;
+}

package/dist/src/components/modal/mono-modal-controller.d.ts

@@ -0,0 +1,4 @@
+import { MonoModalController, MonoModalOptions } from './modal-types.js';
+/** Renamed "control" alias of {@link monoModal} (no breaking change — both work). */
+export { monoModal as controlMonoModal };
+export declare function monoModal(options?: MonoModalOptions): MonoModalController;