@mono-lit/helper 0.0.0-stage → 0.0.1

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

@@ -0,0 +1,129 @@
+import { DropdownPlacement, DropdownSource } from '../dropdown/dropdown-types.js';
+import { ButtonEvents, ButtonProps } from './button-types.js';
+import { MonoEventProps } from '../../composables/element-props.js';
+export type { DropdownPlacement as ButtonDropdownPlacement };
+/**
+ * One entry in `buttons`.
+ *
+ * Extends the full `<mono-button>` prop surface, because that is exactly what
+ * each entry renders — `loading`, `disabled`, `throttle`, `badge`, `variant` and
+ * everything else behave as they would on a standalone button.
+ */
+export interface ButtonDropdownItem extends ButtonProps, Omit<MonoEventProps<ButtonEvents>, 'onClick'> {
+    /** Text of the button (and of its row in the menu). */
+    label?: string;
+    /**
+     * Icon class placed in the button's icon slot, e.g. `'i-mdi-pencil'`.
+     * `iconPosition` (inherited from `ButtonProps`) decides which side it sits on.
+     */
+    icon?: string;
+    /**
+     * Runs when this entry is clicked, before the element's own `click`.
+     * Bind the array with `.prop` — a function can't survive an attribute.
+     */
+    onClick?: (event: MouseEvent) => void;
+    /** Extra class on this entry's button. */
+    className?: string;
+}
+/** Detail shared by `click` / `open` / `close`. */
+export interface ButtonDropdownClickEventDetail {
+    /** The entry that was activated (absent for open/close). */
+    item?: ButtonDropdownItem;
+    /** Its index in `buttons` (absent for open/close). */
+    index?: number;
+    /** Whether the menu is open after this event. */
+    modelValue: boolean;
+    /** Whether the entries are currently collapsed behind the trigger. */
+    collapsed: boolean;
+    source: DropdownSource;
+    sourceEvent?: Event;
+}
+export type ButtonDropdownClickEvent = CustomEvent<ButtonDropdownClickEventDetail>;
+export type ButtonDropdownOpenEvent = CustomEvent<ButtonDropdownClickEventDetail>;
+export type ButtonDropdownCloseEvent = CustomEvent<ButtonDropdownClickEventDetail>;
+/**
+ * Events emitted by `<mono-button-dropdown>`. Each name is listed twice — kebab
+ * and camel — because `dispatchMonoEvent` emits both spellings.
+ */
+export interface ButtonDropdownEvents {
+    click: ButtonDropdownClickEvent;
+    open: ButtonDropdownOpenEvent;
+    close: ButtonDropdownCloseEvent;
+    'mno-click': ButtonDropdownClickEvent;
+    mnoClick: ButtonDropdownClickEvent;
+    'mno-open': ButtonDropdownOpenEvent;
+    mnoOpen: ButtonDropdownOpenEvent;
+    'mno-close': ButtonDropdownCloseEvent;
+    mnoClose: ButtonDropdownCloseEvent;
+}
+/** Per-part class overrides. */
+export interface ButtonDropdownCssClass {
+    root?: string;
+    /** The inline row rendered when the entries are NOT collapsed. */
+    row?: string;
+    /** The `⋮` trigger button. */
+    trigger?: string;
+    /** The floating panel. */
+    panel?: string;
+    /** The `<ul>` inside the panel. */
+    list?: string;
+    /** Each `<li>`. */
+    item?: string;
+}
+/**
+ * Props for `<mono-button-dropdown>`.
+ *
+ * `buttons`, `trigger` and `cssClass` are objects/arrays, so bind them with the
+ * `.prop` modifier (`:buttons.prop="actions"`); a plain attribute would only ever
+ * carry a stringified value.
+ */
+export interface ButtonDropdownProps {
+    /** The actions. Each entry takes every `<mono-button>` prop. */
+    buttons?: ButtonDropdownItem[];
+    /**
+     * How many entries may render inline. While `buttons.length <= min` they are
+     * all shown as plain buttons; past that, ALL of them move into the dropdown and
+     * only the trigger remains. Default `1`.
+     */
+    min?: number;
+    /**
+     * Colors the `⋮` trigger. Entries are deliberately NOT colored inside the menu
+     * — an entry's own `color` tints its ICON there instead, since a list of
+     * differently-coloured buttons reads as noise. Outside the menu (inline, when
+     * the list is short enough) entries keep their real button styling.
+     */
+    color?: ButtonProps['color'];
+    /** Visual style of the `⋮` trigger — same values `<mono-button>` takes. */
+    variant?: ButtonProps['variant'];
+    /** Size of the `⋮` trigger. */
+    size?: ButtonProps['size'];
+    /** Corner radius of the `⋮` trigger — the same scale `<mono-button>` takes. */
+    rounded?: ButtonProps['rounded'];
+    /** Where the panel opens relative to the trigger. Default `'bottom-end'`. */
+    placement?: DropdownPlacement;
+    /** Gap in px between trigger and panel. Default `4`. */
+    offset?: number;
+    /**
+     * Props for the `⋮` trigger button — same shape as an entry, minus the click.
+     * The button's events are accepted as `on<Event>` keys (`onLoadingChange`, …).
+     */
+    trigger?: ButtonProps & MonoEventProps<ButtonEvents> & {
+        label?: string;
+        icon?: string;
+    };
+    /** Open state. Two-way is opt-in: listen for `open` / `close`. */
+    modelValue?: boolean;
+    'model-value'?: boolean;
+    /** Disables the trigger and every entry. */
+    disabled?: boolean;
+    /** Close when a menu entry is clicked. Default `true`. */
+    closeOnSelect?: boolean;
+    'close-on-select'?: boolean;
+    closeOnOutsideClick?: boolean;
+    'close-on-outside-click'?: boolean;
+    closeOnEscape?: boolean;
+    'close-on-escape'?: boolean;
+    cssClass?: ButtonDropdownCssClass;
+    'css-class'?: ButtonDropdownCssClass | string;
+    cssClassName?: string;
+}

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

@@ -0,0 +1,219 @@
+import { DebounceConfig, RateLimitOption, RateLimitPhase, ThrottleConfig } from '../../composables/rate-limit';
+export type { DebounceConfig, RateLimitPhase, ThrottleConfig };
+export type ButtonSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+export type ButtonColor = 'primary' | 'secondary' | 'success' | 'danger' | 'warning' | 'info' | 'teal' | 'purple' | 'neutral' | 'dark' | 'light';
+/**
+ * `solid` fills with the colour, `outline` borders in it, `tonal` lays a
+ * translucent tint under coloured text, `text` is bare at rest. Each maps onto
+ * a Basecoat `.btn[data-variant]` (primary / outline / destructive / ghost).
+ * The old `gradient` variant is gone — Basecoat paints flat token colours.
+ */
+export type ButtonVariant = 'solid' | 'outline' | 'tonal' | 'text';
+/**
+ * Corner radius steps.
+ *
+ * A FIXED radius per step, not one scaled by the button's size: naming a step is
+ * an instruction, so `rounded="md"` is the same corner on an `xs` button as on an
+ * `xxl` one. Leave it unset to keep the per-size radius the theme defines.
+ *
+ * `none` is a real `0` that beats that per-size radius — the one thing the old
+ * `shape="square"` could never do, since it emitted a class with no rule behind
+ * it. `full` is a pill on a wide button and a circle on a square one, which is
+ * what replaced the old `circle` / `round` / `fab` trio.
+ */
+export type ButtonRounded = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl' | 'full';
+export type ButtonIconPosition = 'left' | 'right';
+export type ButtonBadgeColor = 'red' | 'green' | 'orange' | 'cobalt';
+/**
+ * Per-element class overrides. Each key maps to one of the rendered internal
+ * elements; the supplied class string is appended to the element's base class.
+ */
+export interface ButtonCssClass {
+    root?: string;
+    /** The leading affix zone (`slot="prepend"`). */
+    prepend?: string;
+    main?: string;
+    content?: string;
+    text?: string;
+    icon?: string;
+    badge?: string;
+    /** The trailing affix zone (`slot="append"`). */
+    append?: string;
+}
+/**
+ * Configuration for one affix zone — the `slot="prepend"` / `slot="append"`
+ * regions that sit BESIDE the button rather than inside it.
+ *
+ * They are siblings of the native control on purpose. A `<button>` may not
+ * contain interactive content: the HTML parser closes an open `<button>` at a
+ * nested one (so DSD/SSR and `innerHTML` would silently restructure), clicks from
+ * inside bubble into the button's own handler, and `disabled` plus
+ * `pointer-events: none` would kill the affix exactly when the button is busy.
+ * Sitting outside is what lets an affix hold a real control and be clicked
+ * without firing the button.
+ *
+ * Bind as a property (`:append.prop="{ divider: true }"`); a JSON attribute
+ * (`append='{"divider":true}'`) also works for static HTML.
+ */
+export interface ButtonAffixProps {
+    /**
+     * Draw a divider between this affix and the button body. Per side, so a
+     * leading icon can sit flush while a trailing caret is fenced off.
+     */
+    divider?: boolean;
+    /**
+     * Disable just this affix. Defaults to the button's own `disabled`.
+     *
+     * Deliberately NOT tied to `loading`: a busy main action with a still-live
+     * trailing menu is the useful case, and it is the one thing slotted content
+     * cannot express for itself.
+     */
+    disabled?: boolean;
+}
+export interface ButtonProps {
+    /** Visual size of the button. */
+    size?: ButtonSize;
+    /** Color theme of the button. */
+    color?: ButtonColor;
+    /**
+     * Visual style variant (solid, outline, tonal, text).
+     *
+     * `text` has no background and no border at rest — just the coloured label —
+     * and takes the tonal look on hover or keyboard focus.
+     */
+    variant?: ButtonVariant;
+    /**
+     * Corner radius — `none`, the `xs`…`xxl` scale, or `full`. Unset follows the
+     * theme's per-size radius.
+     */
+    rounded?: ButtonRounded;
+    /** Disables interaction and dims the button. */
+    disabled?: boolean;
+    /** Shows a loading state and blocks clicks. */
+    loading?: boolean;
+    /**
+     * Explicit sizing. Each accepts a CSS length string (`"220px"`, `"80%"`) or a
+     * number (interpreted as px). Use `width="100%"` for a full-width button.
+     */
+    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;
+    /** Renders the button as an anchor with this URL. */
+    href?: string;
+    /** Anchor target window when href is set. */
+    target?: string;
+    /** Native button type attribute. */
+    type?: 'button' | 'submit' | 'reset';
+    /** Placement of the icon relative to the text. */
+    iconPosition?: ButtonIconPosition;
+    'icon-position'?: ButtonIconPosition;
+    iconposition?: ButtonIconPosition;
+    /**
+     * Config for the leading affix (`<span slot="prepend">`). The slot supplies the
+     * content; this only says how the zone behaves. Bind with `.prop`.
+     *
+     * NOTE: this name deliberately SHADOWS `ParentNode.prepend()` on the element.
+     * `monoButtonEl.prepend(node)` therefore stops being callable — reading it
+     * returns this config object instead of the DOM method. Nothing inside the
+     * library calls it (slot placement uses `appendChild`), but consumer code and
+     * third-party helpers that do will break on a `<mono-button>`.
+     */
+    prepend?: ButtonAffixProps | string;
+    /**
+     * Config for the trailing affix (`<span slot="append">`). Bind with `.prop`.
+     * Shadows `ParentNode.append()` — see the note on `prepend`.
+     */
+    append?: ButtonAffixProps | string;
+    /** Badge text shown on the button. */
+    badge?: string;
+    /** Color of the badge. */
+    badgeColor?: ButtonBadgeColor;
+    'badge-color'?: ButtonBadgeColor;
+    badgecolor?: ButtonBadgeColor;
+    /** Renders an icon-only button without text. */
+    iconOnly?: boolean;
+    'icon-only'?: boolean;
+    icononly?: boolean;
+    /** Applies a translucent glass effect. */
+    glass?: boolean;
+    /** Tooltip text shown on hover. */
+    tooltip?: string;
+    /** Accessible label text for screen readers. */
+    ariaLabelText?: string;
+    'aria-label-text'?: string;
+    arialabeltext?: string;
+    /** Per-element class overrides. */
+    cssClass?: ButtonCssClass;
+    'css-class'?: ButtonCssClass;
+    /**
+     * Rate-limit clicks: at most `limit` executions per `interval` ms, the rest
+     * queued and replayed rather than dropped. A bare number is the interval.
+     * Emits `throttle` per execution.
+     */
+    throttle?: RateLimitOption<ThrottleConfig>;
+    /**
+     * Collapse a burst of clicks into one execution, `wait` ms after the last.
+     * A bare number is the wait. Emits `debounce` per execution.
+     */
+    debounce?: RateLimitOption<DebounceConfig>;
+    /**
+     * The work a click performs. Bind as a property (`:handler.prop="save"`) —
+     * it's what gets throttled/debounced, and its promise drives the spinner.
+     */
+    handler?: ButtonHandler;
+    /** Opt out of the self-driven spinner; `loading` stays fully consumer-controlled. */
+    noAutoLoading?: boolean;
+    'no-auto-loading'?: boolean;
+    noautoloading?: boolean;
+}
+/** A click's work. Its promise defines how long the button shows as loading. */
+export type ButtonHandler = (event: MouseEvent) => unknown | Promise<unknown>;
+export interface ButtonClickEventDetail {
+    originalEvent: MouseEvent;
+    /** The handler's resolved value; `undefined` on `click` (it fires first). */
+    result?: unknown;
+    /**
+     * Extend the button's loading window over your own async work — the
+     * listener-side equivalent of binding `handler`:
+     *
+     *   `@click="e => e.detail.waitUntil(save())"`
+     */
+    waitUntil(promise: Promise<unknown>): void;
+}
+/** Detail of `throttle` / `debounce`. Same shape, `result` populated. */
+export type ButtonRateLimitEventDetail = ButtonClickEventDetail;
+export interface ButtonLoadingChangeEventDetail {
+    /** Whether the button is currently self-driving a loading state. */
+    loading: boolean;
+    /** `pending` = waiting out the debounce/throttle, `running` = work in flight. */
+    phase: RateLimitPhase;
+}
+export type ButtonClickEvent = CustomEvent<ButtonClickEventDetail>;
+export type ButtonRateLimitEvent = CustomEvent<ButtonRateLimitEventDetail>;
+export type ButtonLoadingChangeEvent = CustomEvent<ButtonLoadingChangeEventDetail>;
+export interface ButtonEvents {
+    click: ButtonClickEvent;
+    throttle: ButtonRateLimitEvent;
+    debounce: ButtonRateLimitEvent;
+    'loading-change': ButtonLoadingChangeEvent;
+    loadingChange: ButtonLoadingChangeEvent;
+    'mno-click': ButtonClickEvent;
+    mnoClick: ButtonClickEvent;
+    'mno-throttle': ButtonRateLimitEvent;
+    mnoThrottle: ButtonRateLimitEvent;
+    'mno-debounce': ButtonRateLimitEvent;
+    mnoDebounce: ButtonRateLimitEvent;
+    'mno-loading-change': ButtonLoadingChangeEvent;
+    mnoLoadingChange: ButtonLoadingChangeEvent;
+}
+export interface IconProps {
+    size?: number;
+    class?: string;
+}

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

@@ -0,0 +1,18 @@
+import { ButtonSize, ButtonColor, ButtonVariant, ButtonRounded, ButtonBadgeColor } from './button-types.js';
+/**
+ * Generate badge CSS classes
+ */
+export declare function generateBadgeClasses(badgeColor?: ButtonBadgeColor): string;
+/**
+ * Process SVG icon content
+ */
+export declare function processIconContent(icon: string): string;
+/**
+ * Validate button props
+ */
+export declare function validateButtonProps(props: {
+    size?: ButtonSize;
+    color?: ButtonColor;
+    variant?: ButtonVariant;
+    rounded?: ButtonRounded;
+}): boolean;

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

@@ -0,0 +1,4 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoButtonDropdown } from './mono-button-dropdown.js';
+export { MonoButtonDropdownCore } from './button-dropdown-core.js';
+export type { ButtonDropdownItem, ButtonDropdownProps, ButtonDropdownEvents, ButtonDropdownCssClass, ButtonDropdownPlacement, ButtonDropdownClickEventDetail, ButtonDropdownClickEvent, ButtonDropdownOpenEvent, ButtonDropdownCloseEvent, } from './button-dropdown-types.js';

package/dist/src/components/button/index.button-dropdown.shadow.d.ts

@@ -0,0 +1,4 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoButtonDropdownShadow } from './mono-button-dropdown.shadow.js';
+export { MonoButtonDropdownCore } from './button-dropdown-core.js';
+export type { ButtonDropdownItem, ButtonDropdownProps, ButtonDropdownEvents, ButtonDropdownCssClass, ButtonDropdownPlacement, ButtonDropdownClickEventDetail, ButtonDropdownClickEvent, ButtonDropdownOpenEvent, ButtonDropdownCloseEvent, } from './button-dropdown-types.js';

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

@@ -0,0 +1,8 @@
+/// <reference path="../../../vue.d.ts" />
+/**
+ * Button Component Exports
+ * Exports all button components, types, and utilities
+ */
+export { MonoButton } from './mono-button.js';
+export type { ButtonSize, ButtonColor, ButtonVariant, ButtonRounded, ButtonIconPosition, ButtonBadgeColor, ButtonProps, ButtonAffixProps, ButtonEvents, IconProps, } from './button-types.js';
+export { generateBadgeClasses, processIconContent, validateButtonProps, } from './button-utils.js';

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

@@ -0,0 +1,5 @@
+/// <reference path="../../../vue.d.ts" />
+export { MonoButtonShadow } from './mono-button.shadow.js';
+export { MonoButtonCore } from './button-core.js';
+export type { ButtonSize, ButtonColor, ButtonVariant, ButtonRounded, ButtonIconPosition, ButtonBadgeColor, ButtonProps, ButtonAffixProps, ButtonEvents, IconProps, } from './button-types.js';
+export { generateBadgeClasses, processIconContent, validateButtonProps, } from './button-utils.js';

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

@@ -0,0 +1,35 @@
+import { LitElement, TemplateResult } from 'lit';
+declare const MonoButtonDropdown_base: import('../../composables/hybird-prop').Constructor<import('./button-dropdown-core.js').MonoButtonDropdownCoreInterface> & typeof LitElement;
+/**
+ * Light-DOM `mono-button-dropdown` (default build,
+ * `@mono-lit/helper/ui/button-dropdown`).
+ *
+ * Renders into the host (`createRenderRoot`→`this`, styled by the global
+ * `dist/ui/index.css`). Unlike most components here it takes no slots: the whole
+ * surface is the `buttons` array, so there is nothing to capture and none of the
+ * light-DOM slot machinery is needed.
+ *
+ * All render-mode-agnostic logic lives in `MonoButtonDropdownCore`; the shadow
+ * build shares it and only swaps the embedded button's tag.
+ */
+export declare class MonoButtonDropdown extends MonoButtonDropdown_base {
+    static styles: import('lit').CSSResult[];
+    protected createRenderRoot(): HTMLElement;
+    /**
+     * The panel is a STATIC element here, not something a helper returns.
+     *
+     * `PopupPortalController` moves it into a `<body>` portal on open and never
+     * moves it back. A node produced inside a `${}` expression sits in a
+     * `ChildPart` range, and ejecting it from that range breaks Lit on the next
+     * render ("this `ChildPart` has no `parentNode`"). As a fixed template node it
+     * has no range to leave — which is exactly why `mono-dropdown` is shaped this
+     * way too.
+     */
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'mono-button-dropdown': MonoButtonDropdown;
+    }
+}
+export {};

package/dist/src/components/button/mono-button-dropdown.shadow.d.ts

@@ -0,0 +1,45 @@
+import { LitElement, TemplateResult } from 'lit';
+declare const MonoButtonDropdownShadow_base: import('../../composables/hybird-prop').Constructor<import('./button-dropdown-core.js').MonoButtonDropdownCoreInterface> & typeof LitElement;
+/**
+ * Shadow-DOM `mono-button-dropdown` — `@mono-lit/helper/ui/shadow/button-dropdown`,
+ * registered as the DISTINCT tag `mono-shadow-button-dropdown` so it can coexist
+ * with the light build in one document.
+ *
+ * Shares every behaviour with the light build through `MonoButtonDropdownCore`;
+ * the only difference is `_buttonTag()`, which points the entries at
+ * `mono-shadow-button` instead of `mono-button`.
+ *
+ * The panel is NOT portaled out of the shadow root — `PopupPortalController`
+ * positions it in place for shadow builds — so it inherits these styles normally.
+ */
+export declare class MonoButtonDropdownShadow extends MonoButtonDropdownShadow_base {
+    static styles: import('lit').CSSResult[];
+    protected _buttonTag(): string;
+    /**
+     * Shadow buttons project through a native `<slot>` — they never relocate their
+     * children — so entry content can stay a Lit template here, which also keeps
+     * this build SSR-safe (no `document.createElement` at render time).
+     */
+    protected _declarativeItems(): boolean;
+    /**
+     * `buttons[].icon` is DATA-driven, so the icon element is created inside this
+     * shadow root — where the page's `i-mdi-*` utilities don't reach, leaving the
+     * entries icon-less. `withShadowUtilityStyles` can't cover it: that path
+     * deliberately excludes icon selectors so the two strategies don't collide.
+     *
+     * `adoptIconStyles` is the matching mechanism — one shared, LIVE constructable
+     * sheet that keeps repopulating until it has captured real `.i-…` glyph rules,
+     * so adopting early (before UnoCSS has loaded) still paints once it does.
+     * Called from both hooks for exactly that reason.
+     */
+    protected firstUpdated(changed: Map<string, unknown>): void;
+    protected updated(changed: Map<string, unknown>): void;
+    /** Panel written statically for the same reason as the light build. */
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'mono-shadow-button-dropdown': MonoButtonDropdownShadow;
+    }
+}
+export {};

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

@@ -0,0 +1,123 @@
+import { LitElement, TemplateResult } from 'lit';
+declare const MonoButton_base: import('../../composables/hybird-prop').Constructor<import('./button-core.js').MonoButtonCoreInterface> & typeof LitElement;
+/**
+ * Light-DOM `mono-button` (default build, `@mono-lit/helper/ui/button`).
+ *
+ * Renders into the host (`createRenderRoot`→`this`, styled by the global
+ * `dist/ui/index.css`) with the light-DOM slot strategy: `slot="icon"` + default
+ * text children are captured in `connectedCallback`, the template renders empty
+ * `[data-mono-slot]` targets, and the captured nodes are re-placed in `updated()`.
+ * Capture goes through `composables/light-slots`, which carries the consumer
+ * framework's positional anchors (Vue's `<!--v-if-->` comments and zero-length
+ * Fragment text nodes) instead of deleting them, and the first render is forced
+ * **synchronously** from `connectedCallback` so capture→placement is one
+ * uninterrupted step — together that's what lets buttons nest freely without
+ * crashing the consumer's next patch on a null anchor.
+ * Host sizing is applied imperatively in `updated()`. All render-mode-agnostic
+ * logic lives in `MonoButtonCore`. The shadow build (`@mono-lit/helper/ui/shadow/button`)
+ * shares the mixin but uses native `<slot>`. Both register `mono-button`, so a
+ * document loads only one.
+ */
+export declare class MonoButton extends MonoButton_base {
+    static styles: import('lit').CSSResult[];
+    protected createRenderRoot(): HTMLElement;
+    private _buckets;
+    private _slotsCaptured;
+    private _guardedAffixes;
+    /**
+     * Capture is one-shot, so a `slot="prepend"` child the consumer appends AFTER
+     * connect would never be seen. These re-run it when one turns up — the icon
+     * slot never needed it because an icon is written inline with the button, but
+     * an affix is exactly the kind of thing a `v-if` reveals later.
+     */
+    private _lateAffix;
+    /**
+     * Light-DOM refinement: `rounded="full"` auto-icon-only only when the default slot is
+     * empty. `bucketHasContent` (not a length check) so a bucket holding nothing but
+     * framework anchors still counts as empty.
+     */
+    protected _defaultIsEmpty(): boolean;
+    private _renderBadge;
+    /**
+     * The `[data-mono-slot]` targets must be **structurally stable** across every
+     * re-render.
+     *
+     * These are light-DOM elements holding nodes the *consumer's* framework
+     * created and still tracks. Toggling `loading` used to swap between two
+     * template branches, so Lit destroyed the target `<span>` — taking the
+     * consumer's nodes with it — and `updated()` re-appended them into a brand-new
+     * one. Vue's vnodes then referenced detached nodes, and the next patch died
+     * with `TypeError: can't access property "__vnode", el is null`.
+     *
+     * So visibility is expressed with the existing `.button-icon.hidden` class
+     * (`display: none !important`), never by adding or removing the target. With
+     * the span stable, `_placeSlot` finds its nodes already in place and mutates
+     * nothing at all on a loading toggle.
+     */
+    private _renderIconOnlyContent;
+    /**
+     * Icon slot class, hidden in place while loading rather than unmounted — but
+     * only in overlay mode. Inline loading keeps the icon, so the button doesn't
+     * reshuffle its contents just to show progress.
+     */
+    /**
+     * The icon box, which is also where the spinner is drawn.
+     *
+     * `spinning` paints the ring and hides whatever is slotted inside; `empty` collapses the box
+     * when there is neither. The span itself is ALWAYS rendered — see `_renderNormalContent`.
+     */
+    private _iconClass;
+    private _renderNormalContent;
+    private _renderContent;
+    protected render(): TemplateResult;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Claim a `slot="prepend"` / `slot="append"` child that arrived after connect.
+     *
+     * Deliberately NOT `captureLightSlots` a second time. This build renders into
+     * the host (`createRenderRoot` → `this`), so by now the host's children include
+     * Lit's own `<div class="mono-button">` — a re-capture would bucket that as
+     * default content and detach it, wiping the rendered button. `LateSlotWatcher`
+     * hands back only the direct child carrying the slot name, which is all that is
+     * wanted here.
+     */
+    private _recaptureAffix;
+    /**
+     * Stop a nested control's click at the affix boundary — the plain `click`
+     * and the `mno-click` / `mnoClick` aliases alike.
+     *
+     * An affix can hold a whole `<mono-button>` or a dropdown caret. Sibling
+     * placement keeps its clicks out of `_handleClick`, but they would still
+     * bubble to the HOST, where a consumer's `@click` is this button's action —
+     * a split button's caret would run the button's handler. So an affix's click
+     * ends here: its own handlers (deeper) and any document-level CAPTURE
+     * listener have already run. Same guard `mono-button-dropdown` puts on its
+     * embedded buttons.
+     */
+    private _guardAffixEvents;
+    private _captureSlots;
+    /**
+     * An affix zone renders only when its slot has content, so an affix-free button
+     * keeps byte-identical markup. That conditional is safe here — unlike the icon
+     * span, whose target must never unmount — because capture runs BEFORE the
+     * synchronous first render in `connectedCallback`, and because the flags only
+     * ever go false→true: captured nodes stay captured, so a target that exists
+     * once is never taken away from under the consumer's nodes.
+     */
+    private _renderAffix;
+    /**
+     * Apply sizing to the HOST (`mono-button` is inline-block). The `.sized` class
+     * makes the wrapper + inner control fill the host, so width/height set here
+     * cascade down. Props that aren't set are removed so they don't linger.
+     */
+    private _applyHostSize;
+    protected updated(changed: Map<string, unknown>): void;
+    private _placeSlot;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'mono-button': MonoButton;
+    }
+}
+export {};

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

@@ -0,0 +1,56 @@
+import { LitElement, TemplateResult } from 'lit';
+declare const MonoButtonShadow_base: import('../../composables/hybird-prop').Constructor<import('./button-core.js').MonoButtonCoreInterface> & typeof LitElement;
+/**
+ * Shadow-DOM `mono-button` (the opt-in SSR build, `@mono-lit/helper/ui/shadow/button`).
+ *
+ * Real shadow root + `static styles`, so `@lit-labs/ssr` serializes it to
+ * Declarative Shadow DOM and styles are scoped (`mono-button`→`:host`). Slotting
+ * uses native `<slot>`: the default text slot is always visible (DSD projects the
+ * label at parse time), and `<slot name="icon">` defaults `data-empty` (hidden)
+ * so the server and the first client render match; real icon presence is detected
+ * in `firstUpdated()` via `assignedNodes()` (+ `@slotchange` for later changes).
+ * The icon side keys off the `iconPosition` prop (not slot presence) so the DOM
+ * structure is hydration-stable. Interactivity needs the first client update to
+ * flush (so `@click` binds) — hence the defer-hydration poll. Host sizing is
+ * applied client-side in `updated()` (progressive; most buttons set none). Shares
+ * all logic with the light build via `MonoButtonCore`; both register
+ * `mono-button`, so a document loads only one.
+ */
+export declare class MonoButtonShadow extends MonoButtonShadow_base {
+    static styles: import('lit').CSSResult[];
+    connectedCallback(): void;
+    firstUpdated(changed: Map<string, unknown>): void;
+    protected updated(changed: Map<string, unknown>): void;
+    private _iconSlot;
+    private _slotHasContent;
+    /**
+     * An affix zone. Unlike the light build's conditional target, the wrapper is
+     * ALWAYS rendered here: the native `<slot>` has to exist for DSD to project
+     * into it and for the scan to see it, so emptiness is a `?data-empty`
+     * attribute the shadow-only CSS hides — the same shape the icon region uses.
+     *
+     * `stopPropagation` on `click` / `mno-click` keeps a nested control's own
+     * click from surfacing as this button's action (a split button's caret must
+     * not run the button's `@click`); see the light build's `_guardAffixEvents`.
+     */
+    private _renderAffix;
+    private _affixSlot;
+    private _onAffixSlotChange;
+    private _onIconSlotChange;
+    /** Host sizing (client-only; mirrors the light build's `_applyHostSize`). */
+    private _applyHostSize;
+    private _renderBadge;
+    /**
+     * The icon box, which is also where the spinner is drawn.
+     *
+     * `spinning` paints the ring and hides the slotted icon; `data-empty` collapses the box when
+     * there is neither. Matches the light build exactly — the two used to differ here, with light
+     * keeping the span and shadow unmounting it.
+     */
+    private _iconSpan;
+    private _renderIconOnlyContent;
+    private _renderNormalContent;
+    private _renderContent;
+    protected render(): TemplateResult;
+}
+export {};