@mono-lit/helper 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,179 @@
+import { VisibilityProps } from '../../composables/visibility';
+import { InputFormat, InputFormatCtx, InputFormatOn } from './input-format.js';
+export type { InputFormat, InputFormatCtx, InputFormatOn };
+export type InputType = 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'date' | 'time' | 'month' | 'week' | 'search';
+export type InputSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+export type InputVariant = 'outlined' | 'filled' | 'underlined';
+export type InputColor = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'teal' | 'purple' | 'neutral' | 'dark';
+export type InputValidationState = 'default' | 'valid' | 'invalid' | 'warning';
+export type InputModelEventDetail = {
+    modelValue: string;
+    currentValue: string;
+    oldValue: string;
+    value: string;
+    name?: string;
+    sourceEvent?: Event;
+    /** What the field is SHOWING — differs from `value` once a `format-display` is set. */
+    displayValue?: string;
+};
+export interface InputCssClass {
+    root?: string;
+    label?: string;
+    required?: string;
+    field?: string;
+    prefix?: string;
+    native?: string;
+    clear?: string;
+    suffix?: string;
+    messageWrap?: string;
+    message?: string;
+}
+export type InputModelEvent = CustomEvent<InputModelEventDetail>;
+export interface InputProps extends VisibilityProps {
+    /** Native input type controlling the field's behavior and keyboard. */
+    type?: InputType;
+    /** Visual size of the input field. */
+    size?: InputSize;
+    /** Theme color applied to focus, borders, and accents. */
+    color?: InputColor;
+    /** Visual style of the field (outlined, filled, or underlined). */
+    variant?: InputVariant;
+    /** Placeholder text shown when the field is empty. */
+    placeholder?: string;
+    /** Current input value. */
+    value?: string | number;
+    /** Form field name submitted with the input. */
+    name?: string;
+    /** Two-way bound value for v-model-style usage. */
+    modelValue?: string;
+    'model-value'?: string;
+    modelvalue?: string;
+    /**
+     * How the field is DISPLAYED — a pattern (`#,##0.##`, `{}@gmail.com`) or a function.
+     * Never changes the value. A numeric pattern requires `type="text"`.
+     */
+    formatDisplay?: InputFormat;
+    'format-display'?: InputFormat;
+    formatdisplay?: InputFormat;
+    /**
+     * How the VALUE is shaped. A numeric pattern normalises to a plain numeric string
+     * (`"10000000.25"`); a template assembles the full string.
+     */
+    formatValue?: InputFormat;
+    'format-value'?: InputFormat;
+    formatvalue?: InputFormat;
+    /** When the display reformats: `'input'` (default) or `'blur'`. */
+    formatOn?: InputFormatOn;
+    'format-on'?: InputFormatOn;
+    formaton?: InputFormatOn;
+    /** Locale a numeric pattern is drawn with — the pattern is a shape, the locale the characters. */
+    formatLocale?: string;
+    'format-locale'?: string;
+    formatlocale?: string;
+    /** Disables interaction and dims the field. */
+    disabled?: boolean;
+    /** Makes the field read-only while still focusable. */
+    readonly?: boolean;
+    /** Shows a clear button when the field has a value. */
+    clearable?: boolean;
+    /** Marks the field as required and shows a required indicator. */
+    required?: boolean;
+    /** Focuses the field automatically on first render. */
+    autofocus?: boolean;
+    /** Label text displayed above the field. */
+    label?: string;
+    /** Helper text shown below the field. */
+    helperText?: string;
+    'helper-text'?: string;
+    helpertext?: string;
+    /** Explicit validation state for styling and messaging. */
+    validationState?: InputValidationState;
+    'validation-state'?: InputValidationState;
+    validationstate?: InputValidationState;
+    /** Validation message shown below the field. */
+    validationMessage?: string;
+    'validation-message'?: string;
+    validationmessage?: string;
+    /** Marks the field in an error state. */
+    error?: boolean;
+    /** Error message shown below the field. */
+    errorMessage?: string;
+    'error-message'?: string;
+    errormessage?: string;
+    /** Marks the field in a success state. */
+    success?: boolean;
+    /** Success message shown below the field. */
+    successMessage?: string;
+    'success-message'?: string;
+    successmessage?: string;
+    /** Accessible label for the input element. */
+    ariaLabelText?: string;
+    /** Shorter alias for the accessible label. */
+    ariaLabel?: string;
+    'aria-label'?: string;
+    'aria-label-text'?: string;
+    arialabel?: string;
+    arialabeltext?: string;
+    /** Minimum allowed input length. */
+    minLength?: number;
+    'min-length'?: number;
+    minlength?: number;
+    /** Maximum allowed input length. */
+    maxLength?: number;
+    'max-length'?: number;
+    maxlength?: number;
+    /**
+     * Minimum value. On a field with a NUMBER `format` this clamps the typed value on commit
+     * (never while typing — a lower bound is crossed on the way to most legal values). On every
+     * other type it is the native attribute.
+     */
+    min?: number | string;
+    /**
+     * Maximum value. On a field with a NUMBER `format` this clamps the typed value AS YOU TYPE, so
+     * the field cannot be pushed past it. On every other type it is the native attribute — note the
+     * platform ignores it on `type="text"`, which a numeric format requires.
+     */
+    max?: number | string;
+    /** Step increment for numeric or date inputs. */
+    step?: number | string;
+    /** Validation pattern the value must match. */
+    pattern?: string;
+    /** Native autocomplete hint for the field. */
+    autocomplete?: string;
+    /** Native inputmode hint for the on-screen keyboard. */
+    inputmode?: string;
+    /**
+     * Explicit sizing. Each accepts a CSS length string (`"320px"`, `"80%"`) or a
+     * number (interpreted as px). Use `width="100%"` for a full-width field.
+     */
+    width?: string | number;
+    height?: string | number;
+    minWidth?: string | number;
+    'min-width'?: string | number;
+    maxWidth?: string | number;
+    'max-width'?: string | number;
+    minHeight?: string | number;
+    'min-height'?: string | number;
+    maxHeight?: string | number;
+    'max-height'?: string | number;
+    /** Per-part class overrides for internal elements. */
+    cssClass?: InputCssClass;
+    /**
+     * Simple HTML root class only.
+     *
+     * Example:
+     * <mono-input css-class="premium-input"></mono-input>
+     */
+    'css-class'?: string;
+}
+export interface InputEvents {
+    input: InputModelEvent;
+    change: InputModelEvent;
+    clear: InputModelEvent;
+    'mno-input': InputModelEvent;
+    mnoInput: InputModelEvent;
+    'mno-change': InputModelEvent;
+    mnoChange: InputModelEvent;
+    'mno-clear': InputModelEvent;
+    mnoClear: InputModelEvent;
+}

package/dist/src/components/input/input-utils.d.ts

@@ -0,0 +1,10 @@
+import { InputType, InputSize, InputColor, InputVariant } from './input-types.js';
+export declare function validateInputProps(props: {
+    type?: InputType;
+    size?: InputSize;
+    color?: InputColor;
+    variant?: InputVariant;
+}): boolean;
+export declare function generateInputAttributes(type: InputType, disabled: boolean, readonly: boolean, required: boolean, pattern?: string, min?: number | string, max?: number | string, step?: number | string, placeholder?: string): Record<string, string | number | boolean | undefined>;
+export declare function generateInputAriaAttributes(disabled: boolean, readonly: boolean, required: boolean, hasError: boolean, label?: string, errorMessage?: string): Record<string, string | undefined>;
+export declare function getInputIcon(type: InputType): string;

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

@@ -0,0 +1,46 @@
+import { LitElement, TemplateResult } from 'lit';
+declare const MonoInput_base: import('../../composables/hybird-prop').Constructor<import('./input-core.js').MonoInputCoreInterface> & typeof LitElement;
+/**
+ * Light-DOM `mono-input` (default build, `@mono-lit/helper/ui/input`).
+ *
+ * Renders into the host (`createRenderRoot`→`this`, styled by the global
+ * `dist/ui/index.css`) and uses the light-DOM slot strategy: `slot="prefix|…"`
+ * children are captured in `connectedCallback`, the template renders empty
+ * `[data-mono-slot]` targets, and the captured nodes are appended back in
+ * `updated()`. All render-mode-agnostic logic lives in `MonoInputCore`. The
+ * shadow build (`@mono-lit/helper/ui/shadow/input`) shares the mixin but uses native
+ * `<slot>`. Both register `mono-input`, so a document loads only one.
+ */
+export declare class MonoInput extends MonoInput_base {
+    static styles: import('lit').CSSResult[];
+    protected createRenderRoot(): HTMLElement;
+    private _slotPrefix;
+    private _slotSuffix;
+    private _slotLabel;
+    private _slotHelper;
+    private _slotObserver?;
+    /**
+     * Capture `slot="…"` light-DOM children into the per-region arrays. Safe to run
+     * MORE THAN ONCE: captured nodes have their `slot` attribute removed and are
+     * detached from the host, so a re-scan never re-captures them. Re-running lets
+     * us pick up children Vue appends AFTER `connectedCallback` (e.g. a client-only
+     * `<mono-input>` slotted into the SSR `<mono-nav>`'s shadow `<slot>`, where the
+     * `<span slot="prefix">` can arrive late) — the original one-shot capture missed
+     * those, so the prefix wrapper was never rendered and the icon never showed.
+     */
+    private _captureSlots;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: Map<string, unknown>): void;
+    private _placeSlot;
+    protected renderIcon(_name: 'close'): TemplateResult;
+    private _renderLabel;
+    private _renderHelper;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'mono-input': MonoInput;
+    }
+}
+export {};

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

@@ -0,0 +1,34 @@
+import { LitElement, TemplateResult } from 'lit';
+declare const MonoInputShadow_base: import('../../composables/hybird-prop').Constructor<import('./input-core.js').MonoInputCoreInterface> & typeof LitElement;
+/**
+ * Shadow-DOM `mono-input` (SSR build, `@mono-lit/helper/ui/shadow/input`).
+ *
+ * Real shadow root + `static styles`, so `@lit-labs/ssr` serializes it to
+ * Declarative Shadow DOM and styles are scoped. Slotting uses native `<slot>`.
+ *
+ * Slot-presence note: during SSR the element has no light children, so it can't
+ * know which slots are filled. Both server and client therefore DEFAULT every
+ * `_has…SlotState` to `false` (so hydration matches), render the slot wrappers
+ * with `mono-empty` (hidden by input.css), then correct presence
+ * after hydration in `firstUpdated()` (Declarative Shadow DOM assigns slotted
+ * content at parse time, so `slotchange` does NOT fire after upgrade — we scan
+ * `assignedNodes()` directly; `slotchange` is kept for later dynamic changes).
+ * `<slot name="label|helper">` carries the prop text (`label`/`helperText`) as
+ * native fallback so it shows with no JS.
+ *
+ * Shares all logic with the light build via `MonoInputCore`. Both register
+ * `mono-input`, so a document loads only one build.
+ */
+export declare class MonoInputShadow extends MonoInputShadow_base {
+    static styles: import('lit').CSSResult[];
+    firstUpdated(changed: Map<string, unknown>): void;
+    private _slotHasContent;
+    private _setSlotState;
+    private _onSlotChange;
+    protected renderIcon(_name: 'close'): TemplateResult;
+    private _renderLabel;
+    private _renderHelper;
+    protected render(): TemplateResult;
+    connectedCallback(): void;
+}
+export {};

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

@@ -0,0 +1,6 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoMenu } from './mono-menu.js';
+export { MonoMenuList } from './mono-menu-list.js';
+export type { MenuDensity, MenuColor, MenuBadgeColor, MenuItem, MenuItemBase, MenuCssClass, MenuChangeEventDetail, MenuChangeEvent, MenuClickEventDetail, MenuClickEvent, MenuToggleGroupEventDetail, MenuToggleGroupEvent, MenuProps, MenuEvents, MonoMenuListType, MenuListProps, } from './menu-types.js';
+export { isItem, isGroup, isDivider, isSubheader, isIconifyClass, findActivePath, findItem, collectDefaultOpenGroups, generateMenuRootClasses, getMenuAlias, validateMenuProps, } from './menu-utils.js';
+export { renderMenuList, renderMenuGroupsOnly, renderMenuItemRow, renderMenuGroup, renderMenuDivider, renderMenuSubheader, renderMenuIcon, renderMenuBadge, renderMenuAppend, type MenuRenderContext, } from './menu-render.js';

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

@@ -0,0 +1,7 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoMenuShadow } from './mono-menu.shadow.js';
+export { MonoMenuCore } from './menu-core.js';
+export type { MonoMenuCoreInterface, MonoMenuListLike } from './menu-core.js';
+export type { MenuDensity, MenuColor, MenuBadgeColor, MenuItem, MenuItemBase, MenuCssClass, MenuChangeEventDetail, MenuChangeEvent, MenuClickEventDetail, MenuClickEvent, MenuToggleGroupEventDetail, MenuToggleGroupEvent, MenuProps, MenuEvents, MonoMenuListType, MenuListProps, } from './menu-types.js';
+export { isItem, isGroup, isDivider, isSubheader, isIconifyClass, findActivePath, findItem, collectDefaultOpenGroups, generateMenuRootClasses, getMenuAlias, validateMenuProps, } from './menu-utils.js';
+export { renderMenuList, renderMenuGroupsOnly, renderMenuItemRow, renderMenuGroup, renderMenuDivider, renderMenuSubheader, renderMenuIcon, renderMenuBadge, renderMenuAppend, type MenuRenderContext, } from './menu-render.js';

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

@@ -0,0 +1,65 @@
+import { LitElement, TemplateResult } from 'lit';
+import { MenuItem, MenuDensity, MenuColor, MenuCssClass } from './menu-types.js';
+import { Constructor } from '../../composables/hybird-prop';
+import { MenuRenderContext } from './menu-render.js';
+/**
+ * Minimal interface for descendant `<mono-menu-list>` instances. Avoids a
+ * circular import — the real class is in `mono-menu-list.ts`.
+ */
+export interface MonoMenuListLike extends HTMLElement {
+    requestUpdate(): void;
+    getMenuItems?(): MenuItem[];
+}
+/** Public + shared-protected surface added by the core mixin. */
+export declare class MonoMenuCoreInterface {
+    items: MenuItem[];
+    modelValue: string | string[];
+    multiple: boolean;
+    density: MenuDensity;
+    color: MenuColor;
+    nav: boolean;
+    selectable: boolean;
+    disabled: boolean;
+    controlled: boolean;
+    cssClass: MenuCssClass;
+    cssClassName: string;
+    select(id: string): void;
+    deselect(id: string): void;
+    toggleGroup(id: string): void;
+    expandGroup(id: string): void;
+    collapseGroup(id: string): void;
+    getActivePath(): MenuItem[];
+    requestItemActivation(item: MenuItem, event?: Event): void;
+    requestGroupToggle(group: MenuItem, event?: Event): void;
+    isItemSelected(id: string): boolean;
+    isGroupOpenPublic(id: string): boolean;
+    getSlotIconNodes(id: string): Node[] | undefined;
+    _registerListChild(child: MonoMenuListLike): void;
+    _unregisterListChild(child: MonoMenuListLike): void;
+    protected _openGroups: Set<string>;
+    protected _slotIcons: Map<string, Node[]>;
+    protected _listChildren: Set<MonoMenuListLike>;
+    protected _seedDefaultOpenGroups(): void;
+    protected _setCssClass(value: unknown): void;
+    protected _cls(base: string, key: keyof MenuCssClass): string;
+    protected _rootClasses: string;
+    protected _isSelected(id: string): boolean;
+    protected _isGroupOpen(id: string): boolean;
+    protected _renderContext(): MenuRenderContext;
+    protected _renderBody(): TemplateResult;
+    protected _useIconSlots(): boolean;
+    protected _chevronSvg(): TemplateResult | undefined;
+    protected _handleItemActivation(item: MenuItem, event?: Event): void;
+    protected _handleGroupToggle(group: MenuItem, event?: Event): void;
+}
+/**
+ * `MonoMenuCore` — all render-mode-agnostic logic for `mono-menu`: reactive
+ * props, hybrid aliases, css-class interop, selection + open-group state,
+ * default-open seeding, the click/toggle/change events, the full public API, and
+ * the chrome `render()` (which delegates the body to a `_renderBody()` hook).
+ *
+ * Leaves to each build: `createRenderRoot()`, the body strategy (light: slot
+ * capture / declarative `slot="body"`; shadow: items-driven only), and
+ * `_chevronSvg()` (light: undefined → UnoCSS icon span; shadow: inline SVG).
+ */
+export declare const MonoMenuCore: <T extends Constructor<LitElement>>(superClass: T) => Constructor<MonoMenuCoreInterface> & T;

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

@@ -0,0 +1,55 @@
+import { nothing, TemplateResult } from 'lit';
+import { MenuCssClass, MenuItem } from './menu-types.js';
+export interface MenuRenderContext {
+    multiple: boolean;
+    selectable: boolean;
+    disabled: boolean;
+    cssClass: MenuCssClass;
+    isSelected(id: string): boolean;
+    isGroupOpen(id: string): boolean;
+    getSlotIconNodes(id: string): Node[] | undefined;
+    onItemClick(item: MenuItem, event: Event): void;
+    onGroupToggle(group: MenuItem, event: Event): void;
+    /**
+     * When `true`, group/item bodies are rendered as an empty
+     * `<ul class="mono-menu-list" data-mono-slot="body">` placeholder instead of
+     * recursing into `item.items`. The host element re-attaches captured DOM
+     * children into that slot in `updated()`, allowing arbitrary declarative
+     * nesting. Defaults to `false` (the existing items-array behaviour).
+     */
+    bodySlot?: boolean;
+    /**
+     * Inline chevron markup for the group expand/collapse affordance. The light
+     * build leaves this undefined → the UnoCSS `.mono-icon i-mdi-chevron-right`
+     * span is rendered (resolved by global CSS). The shadow build passes an inline
+     * SVG here, because that utility class can't resolve inside a shadow root.
+     */
+    chevronSvg?: TemplateResult;
+    /**
+     * Mark a group as the ancestor of the currently-selected item, so it gets the
+     * `active` accent on its header (`.mono-menu-group.active`). Optional — when
+     * absent, groups never get the ancestor-active class (legacy behaviour).
+     */
+    isGroupActive?(group: MenuItem): boolean;
+    /**
+     * Render iconify-class icons (`i-mdi-…`) as a native `<slot name="icon-<id>">`
+     * instead of a `<span class="i-…">`. The shadow build sets this and supplies
+     * matching LIGHT-DOM `<span slot="icon-<id>">` children, so the page's global
+     * UnoCSS styles them (utility classes can't resolve inside a shadow root).
+     * Default (light build) keeps the inline class span.
+     */
+    iconSlot?: boolean;
+}
+export declare function renderMenuIcon(item: MenuItem, ctx: MenuRenderContext): TemplateResult | typeof nothing;
+export declare function renderMenuBadge(item: MenuItem, ctx: MenuRenderContext): TemplateResult | typeof nothing;
+export declare function renderMenuAppend(item: MenuItem, ctx: MenuRenderContext): TemplateResult | typeof nothing;
+export declare function renderMenuItemRow(item: MenuItem, ctx: MenuRenderContext): TemplateResult;
+export declare function renderMenuGroup(group: MenuItem, ctx: MenuRenderContext): TemplateResult;
+export declare function renderMenuDivider(item: MenuItem, ctx: MenuRenderContext): TemplateResult;
+export declare function renderMenuSubheader(item: MenuItem, ctx: MenuRenderContext): TemplateResult;
+export declare function renderMenuList(list: MenuItem[], ctx: MenuRenderContext): TemplateResult[];
+/**
+ * Render only the group rows from `list` — non-group items are skipped.
+ * Used by `<mono-menu-list type="group">`.
+ */
+export declare function renderMenuGroupsOnly(list: MenuItem[], ctx: MenuRenderContext): TemplateResult[];

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

@@ -0,0 +1,195 @@
+/**
+ * Menu (recursive nav list) Component Type Definitions
+ */
+export type MenuDensity = 'compact' | 'comfortable' | 'default';
+/**
+ * A theme palette slot, `surface` for the unpainted default, or any CSS color —
+ * `#7c3aed`, `rgb(124 58 237)`, `hsl(258 90% 66%)`.
+ *
+ * A slot name follows the active `.theme-color-*` preset automatically; a literal is
+ * carried inline and its ink is derived from its own luminance. Note `teal` and
+ * `purple` are CSS keywords too — the slot list is matched first, so they always mean
+ * the theme colour.
+ *
+ * The `(string & {})` arm keeps the slot names in editor autocomplete.
+ */
+export type MenuColorToken = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'teal' | 'purple' | 'neutral' | 'dark' | 'surface';
+export type MenuColor = MenuColorToken | (string & {}) | 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'teal' | 'purple' | 'neutral' | 'dark' | 'surface';
+export type MenuBadgeColor = 'default' | 'primary' | 'success' | 'danger' | 'warning' | 'info';
+/**
+ * Menu items are a discriminated union by `type`.
+ * - `type` omitted or `'item'` — clickable nav row, may have `children` (auto-nested with indent).
+ * - `'group'` — collapsible header + children list.
+ * - `'divider'` — thin horizontal rule.
+ * - `'subheader'` — small label heading for the section beneath.
+ */
+export interface MenuItemBase {
+    id: string;
+    type?: 'item' | 'group' | 'divider' | 'subheader';
+    title?: string;
+    subtitle?: string;
+    icon?: string;
+    appendIcon?: string;
+    badge?: string | number;
+    badgeColor?: MenuBadgeColor;
+    href?: string;
+    disabled?: boolean;
+    /**
+     * Nested menu rows.
+     * Used by both normal items and group items.
+     */
+    items?: MenuItem[];
+    /** Group items only — initial expansion state. */
+    defaultOpen?: boolean;
+}
+export type MenuItem = MenuItemBase;
+export interface MenuCssClass {
+    root?: string;
+    list?: string;
+    item?: string;
+    itemActive?: string;
+    itemDisabled?: string;
+    action?: string;
+    icon?: string;
+    appendIcon?: string;
+    content?: string;
+    title?: string;
+    subtitle?: string;
+    badge?: string;
+    group?: string;
+    groupHeader?: string;
+    groupBody?: string;
+    groupChevron?: string;
+    divider?: string;
+    subheader?: string;
+}
+export type MenuChangeEventDetail = {
+    modelValue: string | string[];
+    oldValue: string | string[];
+    value: string;
+    item: MenuItem;
+    selected: boolean;
+    sourceEvent?: Event;
+};
+export type MenuChangeEvent = CustomEvent<MenuChangeEventDetail>;
+export type MenuClickEventDetail = {
+    value: string;
+    item: MenuItem;
+    sourceEvent?: Event;
+};
+export type MenuClickEvent = CustomEvent<MenuClickEventDetail>;
+export type MenuToggleGroupEventDetail = {
+    groupId: string;
+    open: boolean;
+    oldOpen: boolean;
+    group: MenuItem;
+    sourceEvent?: Event;
+};
+export type MenuToggleGroupEvent = CustomEvent<MenuToggleGroupEventDetail>;
+export interface MenuProps {
+    /** Menu items rendered as a recursive list. */
+    items?: MenuItem[];
+    /** Selected item id, or array of ids when multiple. */
+    modelValue?: string | string[];
+    'model-value'?: string | string[];
+    modelvalue?: string | string[];
+    /** Allows selecting multiple items at once. */
+    multiple?: boolean;
+    /** Vertical spacing density of menu rows. */
+    density?: MenuDensity;
+    /** Theme color applied to active and accent states. */
+    color?: MenuColor;
+    /** Renders rows as navigation links. */
+    nav?: boolean;
+    /** Enables item selection and listbox semantics. */
+    selectable?: boolean;
+    /** Disables interaction across the whole menu. */
+    disabled?: boolean;
+    /**
+     * Controlled mode — the parent owns `modelValue` (e.g. bound to the current
+     * route). Clicks emit `click` but the highlight doesn't move until
+     * `modelValue` updates. Use with Vue Router so the active item can't jump
+     * ahead of an async navigation.
+     */
+    controlled?: boolean;
+    /** Per-part class overrides for internal elements. */
+    cssClass?: MenuCssClass;
+    cssclass?: MenuCssClass;
+    'css-class'?: MenuCssClass | string;
+    /** Plain root class string applied to the menu. */
+    cssClassName?: string;
+}
+export interface MenuEvents {
+    change: MenuChangeEvent;
+    click: MenuClickEvent;
+    'toggle-group': MenuToggleGroupEvent;
+    toggleGroup: MenuToggleGroupEvent;
+    'mno-change': MenuChangeEvent;
+    mnoChange: MenuChangeEvent;
+    'mno-click': MenuClickEvent;
+    mnoClick: MenuClickEvent;
+    'mno-toggle-group': MenuToggleGroupEvent;
+    mnoToggleGroup: MenuToggleGroupEvent;
+}
+/**
+ * `<mono-menu-list>` `type` semantics:
+ *
+ * 1. **Items-array mode** (`type` interpreted as renderer mode):
+ *    - `"children"` — full recursive renderer (items, dividers, subheaders, nested groups).
+ *    - `"group"` — render every top-level entry as a collapsible group; non-group items are
+ *      skipped silently.
+ *
+ * 2. **Direct/declarative mode** (`type` interpreted as the synthesised `MenuItem.type`):
+ *    Used when the element has direct attribute props (`title`, `icon`, `href`, …) **or**
+ *    declarative `<mono-menu-list>` children.
+ *    - `"children"` (default) / `"item"` — regular menu row; child elements compose its
+ *      sub-list (auto-indent + guide rail).
+ *    - `"group"` — collapsible group; child elements compose the group body.
+ *    - `"divider"` / `"subheader"` — leaf rows; children are ignored.
+ *
+ * Disambiguation: if the element has **only** an `items` array (no direct props, no child
+ * elements), the renderer-mode meaning applies. Otherwise the `MenuItem.type` meaning applies.
+ */
+export type MonoMenuListType = 'children' | 'item' | 'group' | 'divider' | 'subheader';
+export interface MenuListProps {
+    /**
+     * In list mode:
+     *   <mono-menu-list :items.prop="items" />
+     *
+     * In direct single-row mode:
+     *   <mono-menu-list type="group" title="Sales" :items.prop="children" />
+     * Here, `items` becomes the built item's `children`.
+     *
+     * In declarative mode, child `<mono-menu-list>` elements (or any other HTML)
+     * compose the row's body — arbitrary depth supported.
+     */
+    items?: MenuItem[];
+    /** Render one full item object, useful with Vue `v-for`. */
+    item?: MenuItem;
+    /** Render mode, or the synthesised item's type in direct mode. */
+    type?: MonoMenuListType;
+    /** Direct single-row props. `item-type` is a legacy alias for `type` in declarative mode. */
+    itemType?: MenuItem['type'];
+    'item-type'?: MenuItem['type'];
+    /** Row title text. */
+    title?: string;
+    /** Secondary text shown beneath the title. */
+    subtitle?: string;
+    /** Leading icon shown before the title. */
+    icon?: string;
+    /** Trailing icon shown after the title. */
+    appendIcon?: string;
+    'append-icon'?: string;
+    /** Badge content shown on the row. */
+    badge?: string | number;
+    /** Color theme of the badge. */
+    badgeColor?: MenuBadgeColor;
+    'badge-color'?: MenuBadgeColor;
+    /** Link target for navigation rows. */
+    href?: string;
+    /** Disables interaction with the row. */
+    disabled?: boolean;
+    /** Initial expansion state for group rows. */
+    defaultOpen?: boolean;
+    'default-open'?: boolean;
+}

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

@@ -0,0 +1,53 @@
+import { MenuItem, MenuProps } from './menu-types.js';
+export { isIconifyClass } from '../../composables/icon.js';
+export declare function isItem(node: MenuItem): boolean;
+export declare function isGroup(node: MenuItem): boolean;
+export declare function isDivider(node: MenuItem): boolean;
+export declare function isSubheader(node: MenuItem): boolean;
+/**
+ * Walk the tree and collect the chain (root → leaf) leading to the item with
+ * the given id. Returns an empty array if not found.
+ */
+export declare function findActivePath(items: MenuItem[], id: string): MenuItem[];
+export declare function findItem(items: MenuItem[], id: string): MenuItem | null;
+/**
+ * Generate a 1–2 character alias from a menu item's title for the icon
+ * fallback (used by `renderMenuIcon` when no `item.icon` and no slot icon are
+ * provided). Each space-delimited word contributes its first character; output
+ * is uppercased and capped at `max` characters.
+ *
+ * Examples:
+ *   getMenuAlias('Dashboard')           → 'D'
+ *   getMenuAlias('Post Budget')         → 'PB'
+ *   getMenuAlias('Sales Order Report')  → 'SO'
+ *   getMenuAlias('logbook')             → 'L'
+ *   getMenuAlias('')                    → ''
+ */
+export declare function getMenuAlias(input: string | undefined | null, max?: number): string;
+export declare function collectDefaultOpenGroups(items: MenuItem[]): string[];
+export declare function generateMenuRootClasses(props: {
+    density: string;
+    color: string;
+    nav: boolean;
+    selectable: boolean;
+    disabled: boolean;
+    cssClassName?: string;
+    rootExtra?: string;
+}): string;
+export declare function validateMenuProps(props: MenuProps): string[];
+/**
+ * The Basecoat styling attributes for the menu ROOT, mirroring the props one
+ * for one. A prop at its DEFAULT emits nothing — `:not([mono-density])` is
+ * comfortable and `:not([mono-color])` is primary — so the rendered DOM is
+ * also the shortest hand-written markup that paints the same (see menu.css).
+ * `nav` defaults to TRUE, so `mono-plain` is the attribute that says
+ * something. Shared so `<mono-menu>` and a standalone `<mono-menu-list>`
+ * cannot drift apart.
+ */
+export declare function menuRootAttrs(props: {
+    density: string;
+    color: string;
+}): {
+    density: string | null;
+    color: string | null;
+};