@mono-lit/helper 0.0.0-stage → 0.0.1

package/dist/src/components/breadcrumb/breadcrumb-list-core.d.ts

@@ -0,0 +1,49 @@
+import { LitElement } from 'lit';
+import { BreadcrumbItem, BreadcrumbBadgeColor, BreadcrumbVariant, BreadcrumbSize, BreadcrumbColor } from './breadcrumb-types.js';
+import { Constructor } from '../../composables/hybird-prop';
+import { BreadcrumbRenderContext } from './breadcrumb-render.js';
+/** Public + shared-protected surface added by the list core mixin. */
+export declare class MonoBreadcrumbListCoreInterface {
+    items: BreadcrumbItem[];
+    item?: BreadcrumbItem;
+    title: string;
+    href: string;
+    icon: string;
+    badge?: string | number;
+    badgeColor?: BreadcrumbBadgeColor;
+    current: boolean;
+    disabled: boolean;
+    variant: BreadcrumbVariant;
+    size: BreadcrumbSize;
+    color: BreadcrumbColor;
+    separator: string;
+    truncate: boolean;
+    getBreadcrumbItems(): BreadcrumbItem[];
+    protected readonly _autoId: string;
+    protected _hasDirectItemProps(): boolean;
+    protected _normalizeItem(item: Partial<BreadcrumbItem>): BreadcrumbItem;
+    protected _buildDirectItem(): BreadcrumbItem;
+    protected _getEffectiveItems(): BreadcrumbItem[];
+    protected _itemsForRender(): BreadcrumbItem[];
+    protected _useIconSlots(): boolean;
+    protected _standaloneContext(): BreadcrumbRenderContext;
+    protected _buildContext(): BreadcrumbRenderContext;
+    protected _standaloneRootClasses(): string;
+}
+/**
+ * `MonoBreadcrumbListCore` — render-mode-agnostic logic for the STANDALONE
+ * `mono-breadcrumb-list`: reactive props (incl. the SSR `items` string→array
+ * coercion), item resolution (`items` array / single `item` / direct single-row
+ * props), the self-contained `<nav><ol>` render, and the `_useIconSlots()` /
+ * `_itemsForRender()` hooks.
+ *
+ * The light build (`mono-breadcrumb-list.ts`) extends this and layers the
+ * light-only CHILD composition (registering with a parent `<mono-breadcrumb>`
+ * via `closest()` and rendering bare items). The shadow build
+ * (`mono-breadcrumb-list.shadow.ts`) extends this for `@lit-labs/ssr`, rendering
+ * standalone in one shadow root and overriding `_useIconSlots()`. Child mode is
+ * a light-only feature (cross-element `closest()` can't work under SSR).
+ *
+ * SSR-safe: no `document`/`window` access.
+ */
+export declare const MonoBreadcrumbListCore: <T extends Constructor<LitElement>>(superClass: T) => Constructor<MonoBreadcrumbListCoreInterface> & T;

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

@@ -0,0 +1,31 @@
+import { nothing, TemplateResult } from 'lit';
+import { BreadcrumbCssClass, BreadcrumbItem } from './breadcrumb-types.js';
+export interface BreadcrumbRenderContext {
+    cssClass: BreadcrumbCssClass;
+    separator: string;
+    hasSeparatorSlot: boolean;
+    disabled: boolean;
+    /**
+     * Shadow build: render per-item icons through a native `<slot name="icon-<id>">`
+     * (the element creates matching light-DOM `<span slot>` children styled by the
+     * page's global UnoCSS — `i-…` classes can't paint inside a shadow root). The
+     * light build leaves this falsy and uses `data-mono-slot` + inline `i-…` spans.
+     */
+    iconSlot?: boolean;
+    isCurrent(id: string): boolean;
+    getSlotIconNodes(id: string): Node[] | undefined;
+    onItemClick(item: BreadcrumbItem, index: number, event: Event): void;
+}
+export declare function renderBreadcrumbIcon(item: BreadcrumbItem, ctx: BreadcrumbRenderContext): TemplateResult | typeof nothing;
+export declare function renderBreadcrumbBadge(item: BreadcrumbItem, ctx: BreadcrumbRenderContext): TemplateResult | typeof nothing;
+export declare function renderBreadcrumbItemRow(item: BreadcrumbItem, index: number, ctx: BreadcrumbRenderContext): TemplateResult;
+export declare function renderBreadcrumbSeparator(ctx: BreadcrumbRenderContext, index: number): TemplateResult;
+export declare function renderBreadcrumbList(items: BreadcrumbItem[], ctx: BreadcrumbRenderContext): TemplateResult[];
+/**
+ * Render items with a leading separator BEFORE each item — used when the child
+ * `<mono-breadcrumb-list>` is composed inside a parent `<mono-breadcrumb>` and
+ * we don't know whether this child is the first sibling. The very first
+ * separator is hidden via CSS:
+ *   `.mono-breadcrumb-list > mono-breadcrumb-list:first-child > .mono-breadcrumb-sep:first-child { display: none; }`
+ */
+export declare function renderBreadcrumbItemsLeadingSep(items: BreadcrumbItem[], ctx: BreadcrumbRenderContext, startIndex?: number): TemplateResult[];

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

@@ -0,0 +1,117 @@
+/**
+ * Breadcrumb Component Type Definitions
+ */
+export type BreadcrumbVariant = 'default' | 'contained' | 'underlined';
+export type BreadcrumbSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+export type BreadcrumbColor = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'teal' | 'purple' | 'neutral' | 'dark' | 'surface';
+export type BreadcrumbBadgeColor = 'default' | 'primary' | 'success' | 'danger' | 'warning' | 'info';
+export interface BreadcrumbItem {
+    id: string;
+    title?: string;
+    href?: string;
+    icon?: string;
+    badge?: string | number;
+    badgeColor?: BreadcrumbBadgeColor;
+    /** Marks this item as the current/last segment. If unset, the final array entry is treated as current. */
+    current?: boolean;
+    disabled?: boolean;
+}
+export interface BreadcrumbCssClass {
+    root?: string;
+    list?: string;
+    item?: string;
+    itemCurrent?: string;
+    itemDisabled?: string;
+    action?: string;
+    icon?: string;
+    content?: string;
+    title?: string;
+    badge?: string;
+    separator?: string;
+}
+export type BreadcrumbClickEventDetail = {
+    value: string;
+    item: BreadcrumbItem;
+    index: number;
+    sourceEvent?: Event;
+};
+export type BreadcrumbClickEvent = CustomEvent<BreadcrumbClickEventDetail>;
+export type BreadcrumbChangeEventDetail = {
+    modelValue: BreadcrumbItem | null;
+    currentValue: BreadcrumbItem | null;
+    oldValue: BreadcrumbItem | null;
+    sourceEvent?: Event;
+};
+export type BreadcrumbChangeEvent = CustomEvent<BreadcrumbChangeEventDetail>;
+export interface BreadcrumbProps {
+    /** List of breadcrumb segments to render. */
+    items?: BreadcrumbItem[];
+    /** Two-way bound currently selected breadcrumb item. */
+    modelValue?: BreadcrumbItem | null;
+    'model-value'?: BreadcrumbItem | null;
+    modelvalue?: BreadcrumbItem | null;
+    /** Visual style of the breadcrumb. */
+    variant?: BreadcrumbVariant;
+    /** Size of the breadcrumb. */
+    size?: BreadcrumbSize;
+    /** Color theme of the breadcrumb. */
+    color?: BreadcrumbColor;
+    /** Separator character shown between segments. */
+    separator?: string;
+    /** Truncates long segment titles with an ellipsis. */
+    truncate?: boolean;
+    /** Disables interaction with all segments. */
+    disabled?: boolean;
+    /** Per-part class overrides for styling internal elements. */
+    cssClass?: BreadcrumbCssClass;
+    cssclass?: BreadcrumbCssClass;
+    'css-class'?: BreadcrumbCssClass | string;
+    /** Extra class applied to the root element. */
+    cssClassName?: string;
+}
+export interface BreadcrumbEvents {
+    change: BreadcrumbChangeEvent;
+    click: BreadcrumbClickEvent;
+    'mno-change': BreadcrumbChangeEvent;
+    mnoChange: BreadcrumbChangeEvent;
+    'mno-click': BreadcrumbClickEvent;
+    mnoClick: BreadcrumbClickEvent;
+}
+/**
+ * `<mono-breadcrumb-list>` mirrors `<mono-menu-list>`'s dual mode:
+ *   - List mode: `<mono-breadcrumb-list :items.prop="items" />`.
+ *   - Single-row mode (for `v-for`): pass row-level props directly
+ *     (`title`, `href`, `icon`, `current`, …) and the component normalises them
+ *     into a one-entry list.
+ */
+export interface BreadcrumbListProps {
+    /** List of breadcrumb segments to render. */
+    items?: BreadcrumbItem[];
+    /** A single breadcrumb item to render. */
+    item?: BreadcrumbItem;
+    /** Direct single-row props. */
+    title?: string;
+    /** Link target for this segment. */
+    href?: string;
+    /** Icon name shown before the segment title. */
+    icon?: string;
+    /** Badge text or count shown on the segment. */
+    badge?: string | number;
+    /** Color theme of the segment badge. */
+    badgeColor?: BreadcrumbBadgeColor;
+    'badge-color'?: BreadcrumbBadgeColor;
+    /** Marks this segment as the current one. */
+    current?: boolean;
+    /** Disables interaction with this segment. */
+    disabled?: boolean;
+    /** Standalone styling — only used when there is no parent `<mono-breadcrumb>`. */
+    variant?: BreadcrumbVariant;
+    /** Size of the breadcrumb when standalone. */
+    size?: BreadcrumbSize;
+    /** Color theme of the breadcrumb when standalone. */
+    color?: BreadcrumbColor;
+    /** Separator character shown between segments when standalone. */
+    separator?: string;
+    /** Truncates long segment titles when standalone. */
+    truncate?: boolean;
+}

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

@@ -0,0 +1,43 @@
+import { BreadcrumbItem, BreadcrumbProps } from './breadcrumb-types.js';
+export { isIconifyClass } from '../../composables/icon.js';
+/**
+ * Coerce any `items` input to a `BreadcrumbItem[]`. Accepts an array (pass-through),
+ * a JSON string (`items='[...]'` attribute, or a string assigned to the PROPERTY —
+ * which is what nuxt-ssr-lit does when forwarding a Vue `:items="<json>"` binding
+ * to the SSR renderer), or anything else (→ `[]`).
+ */
+export declare function coerceItems(value: unknown): BreadcrumbItem[];
+export declare function findItem(items: BreadcrumbItem[], id: string): BreadcrumbItem | null;
+export declare function findItemIndex(items: BreadcrumbItem[], id: string): number;
+/**
+ * Resolve which breadcrumb item is the "current" segment.
+ * Priority: explicit `modelValue` → first item with `current: true` → last item.
+ */
+export declare function resolveCurrentId(items: BreadcrumbItem[], modelValue: BreadcrumbItem | null): string;
+export declare function generateBreadcrumbRootClasses(props: {
+    variant: string;
+    size: string;
+    color: string;
+    truncate: boolean;
+    disabled: boolean;
+    cssClassName?: string;
+    rootExtra?: string;
+}): string;
+export declare function validateBreadcrumbProps(props: BreadcrumbProps): string[];
+/**
+ * The Basecoat styling attributes for the breadcrumb ROOT, mirroring the props
+ * one for one. A prop at its DEFAULT emits nothing — `:not([mono-size])` is md,
+ * `:not([mono-color])` is primary, `:not([mono-variant])` is default — so the
+ * rendered DOM is also the shortest hand-written markup that paints the same
+ * (see breadcrumb.css). Shared so `<mono-breadcrumb>` and a standalone
+ * `<mono-breadcrumb-list>` cannot drift apart.
+ */
+export declare function breadcrumbRootAttrs(props: {
+    variant: string;
+    size: string;
+    color: string;
+}): {
+    size: string | null;
+    color: string | null;
+    variant: string | null;
+};

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

@@ -0,0 +1,6 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoBreadcrumb } from './mono-breadcrumb.js';
+export { MonoBreadcrumbList } from './mono-breadcrumb-list.js';
+export type { BreadcrumbVariant, BreadcrumbSize, BreadcrumbColor, BreadcrumbBadgeColor, BreadcrumbItem, BreadcrumbCssClass, BreadcrumbClickEventDetail, BreadcrumbClickEvent, BreadcrumbChangeEventDetail, BreadcrumbChangeEvent, BreadcrumbProps, BreadcrumbEvents, BreadcrumbListProps, } from './breadcrumb-types.js';
+export { findItemIndex, resolveCurrentId, generateBreadcrumbRootClasses, validateBreadcrumbProps, } from './breadcrumb-utils.js';
+export { renderBreadcrumbList, renderBreadcrumbItemsLeadingSep, renderBreadcrumbItemRow, renderBreadcrumbSeparator, renderBreadcrumbIcon, renderBreadcrumbBadge, type BreadcrumbRenderContext, } from './breadcrumb-render.js';

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

@@ -0,0 +1,8 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoBreadcrumbShadow } from './mono-breadcrumb.shadow.js';
+export { MonoBreadcrumbListShadow } from './mono-breadcrumb-list.shadow.js';
+export { MonoBreadcrumbCore } from './breadcrumb-core.js';
+export type { MonoBreadcrumbCoreInterface, MonoBreadcrumbListLike, } from './breadcrumb-core.js';
+export type { BreadcrumbVariant, BreadcrumbSize, BreadcrumbColor, BreadcrumbBadgeColor, BreadcrumbItem, BreadcrumbCssClass, BreadcrumbClickEventDetail, BreadcrumbClickEvent, BreadcrumbChangeEventDetail, BreadcrumbChangeEvent, BreadcrumbProps, BreadcrumbEvents, BreadcrumbListProps, } from './breadcrumb-types.js';
+export { coerceItems, findItemIndex, resolveCurrentId, generateBreadcrumbRootClasses, validateBreadcrumbProps, } from './breadcrumb-utils.js';
+export { renderBreadcrumbList, renderBreadcrumbItemsLeadingSep, renderBreadcrumbItemRow, renderBreadcrumbSeparator, renderBreadcrumbIcon, renderBreadcrumbBadge, type BreadcrumbRenderContext, } from './breadcrumb-render.js';

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

@@ -0,0 +1,29 @@
+import { LitElement, TemplateResult } from 'lit';
+import { BreadcrumbRenderContext } from './breadcrumb-render.js';
+declare const MonoBreadcrumbList_base: import('../../composables/hybird-prop').Constructor<import('./breadcrumb-list-core.js').MonoBreadcrumbListCoreInterface> & typeof LitElement;
+/**
+ * Light-DOM `mono-breadcrumb-list` (default build, `@mono-lit/helper/ui/breadcrumb`).
+ *
+ * Two modes:
+ *   - Standalone (no parent) — a self-contained breadcrumb nav. All of that logic
+ *     lives in `MonoBreadcrumbListCore`.
+ *   - Child (inside `<mono-breadcrumb>`) — registers with the parent via
+ *     `closest()` and renders BARE items + leading separators (the parent owns
+ *     the `<ol>`/`<nav>` chrome). This composition is light-only; the shadow build
+ *     (`@mono-lit/helper/ui/shadow/breadcrumb`) supports standalone only.
+ */
+export declare class MonoBreadcrumbList extends MonoBreadcrumbList_base {
+    static styles: import('lit').CSSResult[];
+    protected createRenderRoot(): HTMLElement;
+    private _parent;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected _buildContext(): BreadcrumbRenderContext;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'mono-breadcrumb-list': MonoBreadcrumbList;
+    }
+}
+export {};

package/dist/src/components/breadcrumb/mono-breadcrumb-list.shadow.d.ts

@@ -0,0 +1,48 @@
+import { LitElement } from 'lit';
+import { BreadcrumbItem } from './breadcrumb-types.js';
+declare const MonoBreadcrumbListShadow_base: import('../../composables/hybird-prop').Constructor<import('./breadcrumb-list-core.js').MonoBreadcrumbListCoreInterface> & typeof LitElement;
+/**
+ * Shadow-DOM `mono-breadcrumb-list` (SSR build, `@mono-lit/helper/ui/shadow/breadcrumb`).
+ *
+ * Real shadow root + `static styles`, so `@lit-labs/ssr` serializes it to
+ * Declarative Shadow DOM. Renders the STANDALONE breadcrumb nav (from `items`,
+ * a single `item`, or direct single-row props) inside one shadow root. The
+ * child-of-`<mono-breadcrumb>` composition is a light-only feature (cross-element
+ * `closest()` can't work under SSR), so this build is standalone only.
+ *
+ * Icons: `i-…` utility classes can't resolve inside a shadow root, so each item's
+ * icon renders as a native `<slot name="icon-<id>">` (see `iconSlot`), and this
+ * element creates the matching LIGHT-DOM `<span slot="icon-<id>" class="i-…">`
+ * children itself (client-only; empty on the server → the empty `<slot>` matches).
+ *
+ * Shares all standalone logic with the light build via `MonoBreadcrumbListCore`.
+ * Both register `mono-breadcrumb-list`, so a document loads only one build.
+ */
+export declare class MonoBreadcrumbListShadow extends MonoBreadcrumbListShadow_base {
+    static styles: import('lit').CSSResult[];
+    /**
+     * Number of crumbs the SERVER rendered into the SSR'd shadow root, captured at
+     * `connectedCallback` before hydration. `null` when there's no SSR'd shadow
+     * root (pure client render). See `mono-breadcrumb.shadow.ts` for the full
+     * rationale — `:items.prop` is forwarded to the server but Vue sets the client
+     * property late, so we must gate hydration on the EFFECTIVE item count.
+     */
+    private _ssrItemCount;
+    protected _useIconSlots(): boolean;
+    /**
+     * Cap the HYDRATION render at exactly the server-rendered crumb count so the
+     * client's first render reproduces the SSR'd DOM structure; full list after.
+     */
+    protected _itemsForRender(): BreadcrumbItem[];
+    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
+     * effective items. Each becomes a `<span slot="icon-<id>" class="i-…">` that
+     * projects into the shadow `<slot name="icon-<id>">`, styled by the page's
+     * global UnoCSS. Client-only; icons paint at hydration.
+     */
+    private _syncLightIcons;
+}
+export {};

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

@@ -0,0 +1,38 @@
+import { LitElement, TemplateResult } from 'lit';
+declare const MonoBreadcrumb_base: import('../../composables/hybird-prop').Constructor<import('./breadcrumb-core.js').MonoBreadcrumbCoreInterface> & typeof LitElement;
+/**
+ * Light-DOM `mono-breadcrumb` (default build, `@mono-lit/helper/ui/breadcrumb`).
+ *
+ * Renders into the host (`createRenderRoot`→`this`, styled by the global
+ * `dist/ui/index.css`). Supports declarative composition with
+ * `<mono-breadcrumb-list>` children and the light-DOM slot strategy: `slot="body"`
+ * / `slot="separator"` / `slot="icon-<id>"` children are captured in
+ * `connectedCallback`, the template renders empty `[data-mono-slot]` targets, and
+ * the captured nodes are re-placed in `updated()`. All render-mode-agnostic logic
+ * lives in `MonoBreadcrumbCore`. The shadow build
+ * (`@mono-lit/helper/ui/shadow/breadcrumb`) shares the mixin but renders the whole list
+ * from the `items` prop in a single shadow root. Both register `mono-breadcrumb`,
+ * so a document loads only one.
+ */
+export declare class MonoBreadcrumb extends MonoBreadcrumb_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;
+    protected updated(changed: Map<string, unknown>): void;
+    protected _renderBody(): TemplateResult;
+    private _captureSlots;
+    private _placeIconSlots;
+    private _placeBodySlot;
+    private _placeSeparatorSlots;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'mono-breadcrumb': MonoBreadcrumb;
+    }
+}
+export {};

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

@@ -0,0 +1,73 @@
+import { LitElement } from 'lit';
+import { BreadcrumbItem } from './breadcrumb-types.js';
+declare const MonoBreadcrumbShadow_base: import('../../composables/hybird-prop').Constructor<import('./breadcrumb-core.js').MonoBreadcrumbCoreInterface> & typeof LitElement;
+/**
+ * Shadow-DOM `mono-breadcrumb` (SSR build, `@mono-lit/helper/ui/shadow/breadcrumb`).
+ *
+ * Real shadow root + `static styles`, so `@lit-labs/ssr` serializes it to
+ * Declarative Shadow DOM. Renders the WHOLE breadcrumb list from the `items`
+ * prop inside this single shadow root — so every breadcrumb CSS rule applies and
+ * the current crumb is server-rendered. The declarative `<mono-breadcrumb-list>`
+ * composition is a light-only feature (SSR consumers drive it via `items`).
+ *
+ * Icons: `i-…` utility classes can't resolve inside a shadow root, so each item's
+ * icon is rendered as a native `<slot name="icon-<id>">` (see `renderBreadcrumbIcon`
+ * + `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, so real glyphs paint client-side
+ * after hydration (empty on the server → the empty `<slot>` matches → no mismatch).
+ * A user-provided `<… slot="icon-<id>">` light child projects through the same slot.
+ *
+ * Shares all logic with the light build via `MonoBreadcrumbCore`. Both register
+ * `mono-breadcrumb`, so a document loads only one build.
+ */
+export declare class MonoBreadcrumbShadow extends MonoBreadcrumbShadow_base {
+    static styles: import('lit').CSSResult[];
+    /**
+     * Number of crumbs the SERVER actually rendered into the SSR'd shadow root,
+     * captured at `connectedCallback` before hydration replaces the DOM. `null`
+     * when there's no SSR'd shadow root (pure client render).
+     *
+     * @lit-labs/ssr does NOT forward `.prop` array bindings to the server, so for
+     * `:items.prop="arr"` the server renders 0 crumbs while the client `items` has
+     * N. Gating the first (hydration) render on this count makes the client's
+     * first render match the server exactly → no "shorter than expected iterable"
+     * and no double render. `:items="JSON.stringify(arr)"` forwards the string, so
+     * the server renders N and this is N → unchanged.
+     */
+    private _ssrItemCount;
+    protected _useIconSlots(): boolean;
+    /**
+     * Cap the HYDRATION render at exactly the server-rendered crumb count so the
+     * client's first render reproduces the SSR'd DOM structure. After hydration
+     * (`hasUpdated`) render the full list. Safety net for the rare case where the
+     * client `items` ends up longer than what the server emitted. On the server,
+     * always render the real `items`.
+     */
+    protected _itemsForRender(): BreadcrumbItem[];
+    connectedCallback(): void;
+    protected firstUpdated(changed: Map<string, unknown>): void;
+    protected updated(changed: Map<string, unknown>): void;
+    /**
+     * Register the consumer's own `slot="icon-<id>"` light children.
+     *
+     * `renderBreadcrumbIcon` only emits the wrapper (and therefore the `<slot>`) when
+     * the item has an `icon` OR `getSlotIconNodes(id)` reports something. That map is
+     * filled by the LIGHT build's capture pass, which never runs here — so a
+     * user-slotted `<svg slot="icon-home">` produced no wrapper, no slot, and no icon
+     * at all. Register them before render so the slot exists for them to project into.
+     *
+     * Must run in `willUpdate`, not `updated`: by `updated` the render that needed the
+     * information has already happened.
+     */
+    protected willUpdate(changed: Map<string, unknown>): void;
+    private _captureUserIconSlots;
+    /**
+     * Reconcile LIGHT-DOM icon spans (this element's own children) with `items`.
+     * Each becomes a `<span slot="icon-<id>" class="mono-breadcrumb-iconify i-…">`
+     * that projects into the shadow `<slot name="icon-<id>">` and is styled by the
+     * page's global UnoCSS. Client-only; icons paint at hydration.
+     */
+    private _syncLightIcons;
+}
+export {};

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

@@ -0,0 +1,90 @@
+import { LitElement, TemplateResult } from 'lit';
+import { ButtonSize, ButtonColor, ButtonVariant, ButtonRounded, ButtonIconPosition, ButtonBadgeColor, ButtonCssClass, ButtonAffixProps, ButtonHandler } from './button-types.js';
+import { Constructor } from '../../composables/hybird-prop';
+import { buildSizeStyle, CssSizeValue } from '../../composables/css-size';
+import { DebounceConfig, RateLimitOption, ThrottleConfig } from '../../composables/rate-limit';
+type ButtonLikeElement = HTMLButtonElement | HTMLAnchorElement;
+/** Public + shared-protected surface added by the core mixin. */
+export declare class MonoButtonCoreInterface {
+    size: ButtonSize;
+    color: ButtonColor;
+    variant: ButtonVariant;
+    rounded?: ButtonRounded;
+    disabled: boolean;
+    loading: boolean;
+    width?: CssSizeValue;
+    height?: CssSizeValue;
+    minWidth?: CssSizeValue;
+    maxWidth?: CssSizeValue;
+    minHeight?: CssSizeValue;
+    maxHeight?: CssSizeValue;
+    href?: string;
+    target?: string;
+    type: 'button' | 'submit' | 'reset';
+    iconPosition: ButtonIconPosition;
+    prepend: ButtonAffixProps;
+    append: ButtonAffixProps;
+    badge?: string;
+    badgeColor: ButtonBadgeColor;
+    iconOnly: boolean;
+    glass: boolean;
+    tooltip?: string;
+    ariaLabelText?: string;
+    cssClass: ButtonCssClass;
+    throttle?: RateLimitOption<ThrottleConfig>;
+    debounce?: RateLimitOption<DebounceConfig>;
+    handler?: ButtonHandler;
+    noAutoLoading: boolean;
+    focus(): void;
+    blur(): void;
+    click(): void;
+    cancelPending(): void;
+    protected _hasIcon: boolean;
+    protected _hasPrepend: boolean;
+    protected _hasAppend: boolean;
+    /** The affix config for one side, always an object. */
+    protected _affix(name: 'prepend' | 'append'): ButtonAffixProps;
+    /** Whether that affix is inert — follows `disabled`, never `loading`. */
+    protected _affixDisabled(name: 'prepend' | 'append'): boolean;
+    protected _isActive: boolean;
+    protected _buttonElement?: ButtonLikeElement;
+    protected _cls(base: string, key: keyof ButtonCssClass): string;
+    protected _toBoolean(value: unknown): boolean;
+    protected _sizeStyle(): ReturnType<typeof buildSizeStyle>;
+    protected get _hasSize(): boolean;
+    protected _defaultIsEmpty(): boolean;
+    protected get _isIconOnlyLike(): boolean;
+    protected get _buttonClasses(): string;
+    protected _renderWrapper(inner: TemplateResult, style?: unknown): TemplateResult;
+    protected get _badgeClass(): string;
+    protected get _badgeColor(): string;
+    protected get _ariaLabel(): string | undefined;
+    /** Spinner visibility: the `loading` prop OR either self-driven phase. */
+    protected get _effectiveLoading(): boolean;
+    /** Where the spinner is drawn: in the icon position, whatever triggered loading. */
+    protected get _showsSpinner(): boolean;
+    /** A click does nothing observable (covers the wait as well as the work). */
+    protected get _isBlocked(): boolean;
+    /** The native `disabled` attribute — `_isBlocked` minus the wait. */
+    protected get _isInert(): boolean;
+    protected _handleClick(event: MouseEvent): void;
+    protected _handleKeyDown(event: KeyboardEvent): void;
+    protected _handleFocus(): void;
+    protected _handleBlur(): void;
+}
+/**
+ * `MonoButtonCore` — all render-mode-agnostic logic for `mono-button`: reactive
+ * props, hybrid aliases, the camelCase attribute fallbacks, the slot-presence
+ * `@state` (`_hasIcon`), class/getter computation, sizing, click/keyboard
+ * interactivity, and the imperative `focus/blur/click`. No `render()` — the light
+ * build keeps its `[data-mono-slot]` capture strategy and the shadow build uses
+ * native `<slot>` (each ships its own `render()`, mirroring `mono-card`).
+ *
+ * The `rounded="full"` auto-"icon-only when empty" refinement depends on light-DOM slot
+ * introspection, so it lives behind the `_defaultIsEmpty()` hook (defaults to
+ * `false` here; the light build overrides it). SSR-safe: no `document`/`window`
+ * access; `_buttonElement` (`@query`) is lazy and `focus/blur/click` only run
+ * client-side.
+ */
+export declare const MonoButtonCore: <T extends Constructor<LitElement>>(superClass: T) => Constructor<MonoButtonCoreInterface> & T;
+export {};

package/dist/src/components/button/button-dropdown-core.d.ts

@@ -0,0 +1,57 @@
+import { LitElement, nothing, TemplateResult } from 'lit';
+import { ButtonDropdownCssClass, ButtonDropdownItem } from './button-dropdown-types.js';
+import { ButtonProps } from './button-types.js';
+import { DropdownPlacement, DropdownSource } from '../dropdown/dropdown-types.js';
+import { Constructor } from '../../composables/hybird-prop';
+/** Public surface added by the core mixin (for typing the wrappers + tag map). */
+export declare class MonoButtonDropdownCoreInterface {
+    buttons: ButtonDropdownItem[];
+    min: number;
+    placement: DropdownPlacement;
+    offset: number;
+    color?: ButtonProps['color'];
+    variant?: ButtonProps['variant'];
+    size?: ButtonProps['size'];
+    trigger?: ButtonProps & {
+        label?: string;
+        icon?: string;
+    };
+    modelValue: boolean;
+    disabled: boolean;
+    closeOnSelect: boolean;
+    closeOnOutsideClick: boolean;
+    closeOnEscape: boolean;
+    cssClass: ButtonDropdownCssClass;
+    show(source?: DropdownSource): void;
+    hide(source?: DropdownSource): void;
+    toggle(source?: DropdownSource): void;
+    /** Whether the entries are currently behind the trigger rather than inline. */
+    readonly collapsed: boolean;
+    /** Tag of the button element to render — differs per build. */
+    protected _buttonTag(): string;
+    /** Whether entry content may be a Lit template (shadow only — see the impl). */
+    protected _declarativeItems(): boolean;
+    protected _cls(base: string, key: keyof ButtonDropdownCssClass): string;
+    protected renderRow(): TemplateResult;
+    /** The `⋮` trigger, or `nothing` while the entries are inline. */
+    protected renderTrigger(): TemplateResult | typeof nothing;
+    /** The menu rows — rendered INSIDE the panel each build writes itself. */
+    protected renderMenuList(): TemplateResult;
+    /**
+     * The panel is deliberately NOT built here. `PopupPortalController` physically
+     * moves it into a `<body>` portal, and a node inside a `${}` expression carries
+     * a `ChildPart` range that breaks when its nodes are ejected ("this `ChildPart`
+     * has no `parentNode`"). Each build writes the panel as a STATIC element in its
+     * own template — the same arrangement `mono-dropdown` uses — and reads these.
+     */
+    protected readonly panelClass: string;
+    protected readonly panelHidden: boolean;
+    protected bindPanel: (el: Element | undefined) => void;
+    /** Ref for the inner root each build renders — where the styling attributes go. */
+    protected bindRoot: (el: Element | undefined) => void;
+    protected _computeRootAttrs(): Record<string, string | null>;
+    protected _applyRootAttrs(root: HTMLElement | null | undefined): void;
+    /** The `mono-item-color` an entry gets inside the menu (null = the panel's ink). */
+    protected _itemColorAttr(item: ButtonDropdownItem): string | null;
+}
+export declare const MonoButtonDropdownCore: <T extends Constructor<LitElement>>(superClass: T) => Constructor<MonoButtonDropdownCoreInterface> & T;