origam 2.15.0 → 2.16.0

package/dist/src/interfaces/Bracket/bracket-surface.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Bracket/bracket-surface.interface.d.ts

@@ -0,0 +1,56 @@
+import type { TBracketBorder, TBracketColor, TBracketElevation, TBracketRounded } from '../../types';
+/**
+ * Prop bag consumed by `bracketSurfaceVars` to paint one match card.
+ *
+ * Mirrors the `IBgColorProps` / `IRoundedProps` / `IElevationProps` /
+ * `IBorderProps` surfaces that `IBracketProps` and
+ * `IBracketMatchProps` already extend — but it is a SEPARATE shape on
+ * purpose, and does not `extends` them.
+ *
+ * The reason is the target element. `IBorderProps.border` accepts a
+ * `TDirectionBoth[]` edge selector, which `useBorder` resolves onto the
+ * component ROOT. The bracket resolves its surface props onto the match
+ * CARD instead (each card is what the user sees shaped and bordered),
+ * through `--origam-bracket-match---*` custom properties, and a custom
+ * property cannot express "these edges only" the way `useBorder`'s
+ * class output can. Extending `IBorderProps` here would therefore
+ * declare a prop form this layer silently drops — the exact
+ * typed-but-inert failure the surrounding audit exists to remove.
+ *
+ * Every property type is nonetheless DERIVED from the matching Commons
+ * vocabulary (see the `TBracket*` aliases in
+ * `types/Bracket/bracket.type.ts`), so the two
+ * cannot drift on the value grammar they share.
+ */
+export interface IBracketSurfaceInput {
+    bgColor?: TBracketColor;
+    rounded?: TBracketRounded;
+    elevation?: TBracketElevation;
+    border?: TBracketBorder;
+    borderColor?: TBracketColor;
+    borderStyle?: string | null;
+    /**
+     * Per-corner radius and per-side border overrides.
+     *
+     * The bracket resolves `rounded` / `border` onto the MATCH CARD rather
+     * than its own root (each card is what the user sees shaped and
+     * bordered), so the directional rungs of `IRoundedProps` /
+     * `IBorderProps` have to follow the same target — otherwise
+     * `roundedTopLeft` is typed, editable in Histoire, and inert, which is
+     * exactly the class of bug this surface is being audited for.
+     */
+    roundedTopLeft?: TBracketRounded;
+    roundedTopRight?: TBracketRounded;
+    roundedBottomLeft?: TBracketRounded;
+    roundedBottomRight?: TBracketRounded;
+    borderTop?: TBracketBorder;
+    borderRight?: TBracketBorder;
+    borderBottom?: TBracketBorder;
+    borderLeft?: TBracketBorder;
+    borderBlock?: TBracketBorder;
+    borderInline?: TBracketBorder;
+    borderTopColor?: TBracketColor;
+    borderRightColor?: TBracketColor;
+    borderBottomColor?: TBracketColor;
+    borderLeftColor?: TBracketColor;
+}

package/dist/src/interfaces/Calendar/calendar.interface.d.ts

@@ -162,3 +162,28 @@ export interface IUseCalendarOptions {
     maxDate?: () => Date | null;
     locale?: () => string;
 }
+/**
+ * Time-slot descriptor returned by `buildDayGrid` / `buildWeekGrid`.
+ *
+ * The grid is **not** event-aware — events are positioned absolutely
+ * on top of the timeline using `diffMinutes(dayStart, event.start)`.
+ * Decoupling the grid from the events lets us re-use the grid output
+ * for the drag-select overlay without re-computing.
+ */
+export interface ICalendarTimeSlot {
+    /** Top-of-slot Date (e.g. 09:30). */
+    date: Date;
+    /** Slot duration in minutes (mirror of `options.slotDuration`). */
+    durationMin: number;
+    /** True when the slot's hour mark falls on the hour. */
+    isHourMark: boolean;
+}
+/**
+ * Agenda entry — one per day that has at least one event in the
+ * visible window. Agenda view skips empty days; the `#empty` slot
+ * fires when *no* event is in range.
+ */
+export interface ICalendarAgendaEntry {
+    date: Date;
+    events: Array<IEvent>;
+}

package/dist/src/interfaces/Calendar/rrule.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/Calendar/rrule.interface.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Normalized form of the RRULE subset understood by
+ * `src/utils/Calendar/rrule.util.ts`.
+ *
+ * Only the directives the parser actually honours are modelled here —
+ * `FREQ`, `INTERVAL`, `COUNT`, `UNTIL` and `BYDAY`. Everything else in
+ * RFC 5545 is dropped at parse time, so a value of this shape is a
+ * complete description of what the expander will do.
+ *
+ * The name is `ICalendarParsedRule` rather than a bare `IParsedRule`
+ * because `src/interfaces/index.ts` is a flat `export *` barrel — an
+ * unqualified name there reads as a repo-wide concept and is a
+ * collision waiting to happen.
+ */
+export interface ICalendarParsedRule {
+    /** Recurrence frequency. The parser rejects any other `FREQ` value. */
+    freq: 'DAILY' | 'WEEKLY' | 'MONTHLY';
+    /** `INTERVAL=N`, defaulted to 1 when absent. */
+    interval: number;
+    /** `COUNT=N` occurrence cap, or `null` when unbounded. */
+    count: number | null;
+    /** `UNTIL=` cut-off date, or `null` when unbounded. */
+    until: Date | null;
+    /** `BYDAY=` as JS day indices (0 = Sunday). `WEEKLY` only; else `null`. */
+    byDay: Array<number> | null;
+}

package/dist/src/interfaces/Chart/chart-sunburst.interface.d.ts

@@ -1,5 +1,6 @@
 import type { IChartBaseEmits, IChartBaseProps, IChartBaseSlots, IChartPoint, IChartSeries } from '../../interfaces';
-import type { TIntent } from '../../types';
+import type { TChartSunburstLabelMode, TIntent } from '../../types';
+export type { TChartSunburstLabelMode } from '../../types/Chart/chart-sunburst.type';
 /**
  * A single datum node in the sunburst tree.
  * Internal nodes may omit `value` — it will be computed from children.
@@ -17,13 +18,6 @@ export interface IChartSunburstDatum {
     /** Child nodes — forms the next ring outward. */
     children?: Array<IChartSunburstDatum>;
 }
-/**
- * How the label for a node is rendered.
- * - `'inline'`  — centred horizontally inside the arc (wide arcs).
- * - `'rotated'` — rotated tangentially along the arc midpoint (narrow arcs).
- * - `'leader'`  — placed outside the chart with a leader line (very narrow arcs).
- */
-export type TChartSunburstLabelMode = 'inline' | 'rotated' | 'leader';
 /**
  * Fully-resolved node produced by the geometry engine. Every field is
  * definite — defaults / inherited values have been applied.

package/dist/src/interfaces/CommandPalette/command-palette-rendered-group.interface.d.ts

@@ -1,5 +1,4 @@
-import type { ICommand } from './command.interface';
-import type { IFuzzyMatchResult } from '../../utils/CommandPalette/fuzzy-match.util';
+import type { ICommand, IFuzzyMatchResult } from './command.interface';
 /**
  * Internal implementation detail of `<OrigamCommandPalette>`'s grouping
  * computation — NOT part of the component's public props/emits/slots

package/dist/src/interfaces/CommandPalette/command.interface.d.ts

@@ -1,3 +1,4 @@
+import type { ComputedRef, Ref } from 'vue';
 import type { TIcon } from '../../types';
 /**
  * A single command/action exposed by `OrigamCommandPalette`.
@@ -49,3 +50,49 @@ export interface ICommand {
     /** Disabled commands stay visible but cannot be selected. */
     disabled?: boolean;
 }
+/**
+ * Backing store of `useCommand`'s process-wide singleton registry.
+ *
+ * Module-scoped rather than provide/inject on purpose: commands are
+ * spawned from anywhere — feature code, plugins, background services —
+ * without coupling to a Vue tree.
+ */
+export interface ICommandRegistry {
+    /** Live array of registered commands. Dedup by id is enforced at write time. */
+    items: Ref<Array<ICommand>>;
+    /** Whether the global palette singleton is currently open. */
+    isOpen: Ref<boolean>;
+}
+/** Public API returned by `useCommand`. */
+export interface IUseCommandReturn {
+    /**
+     * Register a command. Returns an `unregister()` closure so callers
+     * can drop the entry imperatively. When called from inside a Vue
+     * effect scope, the entry is auto-unregistered on scope dispose
+     * (component unmount, route leave, …) via `tryOnScopeDispose`.
+     */
+    register: (cmd: ICommand) => () => void;
+    /** Drop the entry with the matching `id`. No-op if unknown. */
+    unregister: (id: string) => void;
+    /**
+     * Reactive read-only view of every registered command, deduplicated
+     * by id.
+     */
+    commands: ComputedRef<ReadonlyArray<ICommand>>;
+    /** Open the global palette singleton. */
+    open: () => void;
+    /** Close the global palette singleton. */
+    close: () => void;
+    /** Reactive open/close state of the global palette singleton. */
+    isOpen: Ref<boolean>;
+}
+/**
+ * Output of `fuzzyMatch` — the matched item carries its score so callers
+ * can short-circuit a re-sort on cached input.
+ */
+export interface IFuzzyMatchResult<T> {
+    /** Original item passed in. */
+    item: T;
+    /** Higher = better fit. `0` is the floor for a successful match. */
+    score: number;
+}

package/dist/src/interfaces/Commons/loader.interface.d.ts

@@ -1,5 +1,5 @@
 import type { IColorProps, ICommonsComponentProps, ITagProps } from '../../interfaces';
-import type { TLoadingValue } from '../../types';
+import type { TLoaderConfig, TLoaderKind, TLoadingValue } from '../../types';
 export interface ILoaderProps extends ICommonsComponentProps, ITagProps, IColorProps {
     loading?: TLoadingValue;
     loadingText?: string;
@@ -9,3 +9,25 @@ export interface ILoaderSlots {
     loader?: () => any;
     default?: () => any;
 }
+/**
+ * Resolved loader state — what each consumer component reads to decide
+ * which renderer to mount and with which props.
+ *
+ * @remarks
+ * `overrides` is intentionally typed as `Omit<TLoaderConfig, 'type'>`. After
+ * the discriminant `type` is destructured at runtime, TypeScript can no
+ * longer narrow the union. Consumer components must access optional fields
+ * defensively (e.g. `(overrides as { modelValue?: number }).modelValue`).
+ */
+export interface IResolvedLoader {
+    /** Whether ANY loading state is active. */
+    isActive: boolean;
+    /** Which renderer to use ('line' / 'circular' / 'skeleton'). */
+    kind: TLoaderKind;
+    /** Determinate progress value (0..100) when the user passed a number; else undefined. */
+    modelValue: number | undefined;
+    /** Indeterminate when `true`, determinate when a number was passed. */
+    indeterminate: boolean;
+    /** Per-kind override props the consumer should v-bind on the renderer. */
+    overrides: Omit<TLoaderConfig, 'type'>;
+}

package/dist/src/interfaces/Commons/margin.interface.d.ts

@@ -1,9 +1,39 @@
+/**
+ * Outer-spacing surface.
+ *
+ * Precedence — SPECIFIC beats GLOBAL, same grammar as `IPaddingProps` /
+ * `IBorderProps` / `IRoundedProps`:
+ *
+ *   1. `margin`                       — global shorthand
+ *   2. `marginBlock` / `marginInline` — logical axis
+ *   3. `marginTop` / `marginRight` / `marginBottom` / `marginLeft`
+ *
+ * Each rung only overrides the edge(s) it targets. See
+ * `resolveSpacingValue` for the accepted value forms (the directionals
+ * also take the `auto` keyword), and
+ * `packages/docs/guide/spacing-and-corners.md` for the full reference.
+ *
+ * ⚠️ The 4-value `margin` shorthand distributes as
+ * **Haut/Gauche/Bas/Droite**, NOT the CSS clockwise order (issue #216).
+ * The per-side props exist so you never have to know that.
+ */
 export interface IMarginProps {
+    /**
+     * Global shorthand. `16` → `16px`; `"4"` → the `--origam-space---4`
+     * design rung; `"8px 16px"` → block / inline; `true` → the legacy
+     * `--marged` class.
+     */
     margin?: boolean | number | string;
+    /** Overrides `margin` and `marginBlock` for the top edge. */
     marginTop?: boolean | number | string;
+    /** Overrides `margin` and `marginInline` for the left edge. */
     marginLeft?: boolean | number | string;
+    /** Overrides `margin` and `marginBlock` for the bottom edge. */
     marginBottom?: boolean | number | string;
+    /** Overrides `margin` and `marginInline` for the right edge. */
     marginRight?: boolean | number | string;
+    /** Top + bottom. Overrides `margin`; beaten by `marginTop` / `marginBottom`. */
     marginBlock?: boolean | number | string;
+    /** Left + right. Overrides `margin`; beaten by `marginLeft` / `marginRight`. */
     marginInline?: boolean | number | string;
 }

package/dist/src/interfaces/Commons/padding.interface.d.ts

@@ -1,9 +1,38 @@
+/**
+ * Inner-spacing surface.
+ *
+ * Precedence — SPECIFIC beats GLOBAL, same grammar as `IMarginProps` /
+ * `IBorderProps` / `IRoundedProps`:
+ *
+ *   1. `padding`                        — global shorthand
+ *   2. `paddingBlock` / `paddingInline` — logical axis
+ *   3. `paddingTop` / `paddingRight` / `paddingBottom` / `paddingLeft`
+ *
+ * Each rung only overrides the edge(s) it targets. See
+ * `resolveSpacingValue` for the accepted value forms, and
+ * `packages/docs/guide/spacing-and-corners.md` for the full reference.
+ *
+ * ⚠️ The 4-value `padding` shorthand distributes as
+ * **Haut/Gauche/Bas/Droite**, NOT the CSS clockwise order (issue #216).
+ * The per-side props exist so you never have to know that.
+ */
 export interface IPaddingProps {
+    /**
+     * Global shorthand. `16` → `16px`; `"4"` → the `--origam-space---4`
+     * design rung; `"8px 16px"` → block / inline; `true` → the legacy
+     * `--padded` class.
+     */
     padding?: boolean | number | string;
+    /** Overrides `padding` and `paddingBlock` for the top edge. */
     paddingTop?: boolean | number | string;
+    /** Overrides `padding` and `paddingInline` for the left edge. */
     paddingLeft?: boolean | number | string;
+    /** Overrides `padding` and `paddingBlock` for the bottom edge. */
     paddingBottom?: boolean | number | string;
+    /** Overrides `padding` and `paddingInline` for the right edge. */
     paddingRight?: boolean | number | string;
+    /** Top + bottom. Overrides `padding`; beaten by `paddingTop` / `paddingBottom`. */
     paddingBlock?: boolean | number | string;
+    /** Left + right. Overrides `padding`; beaten by `paddingLeft` / `paddingRight`. */
     paddingInline?: boolean | number | string;
 }

package/dist/src/interfaces/Commons/rounded.interface.d.ts

@@ -1,4 +1,20 @@
 import type { TRounded } from '../../types';
+/**
+ * Corner-radius surface.
+ *
+ * Precedence — SPECIFIC beats GLOBAL, same grammar as `IPaddingProps` /
+ * `IMarginProps` / `IBorderProps`, with two rungs instead of three (there
+ * is no logical-axis form for corners):
+ *
+ *   1. `rounded`                   — global shorthand
+ *   2. `roundedTopLeft` / `roundedTopRight` /
+ *      `roundedBottomLeft` / `roundedBottomRight`
+ *
+ * A corner prop only overrides the corner it targets — `rounded="lg"` plus
+ * `roundedTopLeft="0px"` flattens one corner and leaves the other three at
+ * `lg`. See `resolveRoundedCornerValue` for the accepted value forms and
+ * `packages/docs/guide/spacing-and-corners.md` for the full reference.
+ */
 export interface IRoundedProps {
     /**
      * Corner-radius selector. Three modes:
@@ -12,8 +28,16 @@ export interface IRoundedProps {
      *    `border-radius` declarations via `useRounded.roundedStyles`.
      */
     rounded?: boolean | number | string | TRounded | null | undefined;
+    /**
+     * Top-right corner only. Takes the same vocabulary as `rounded`
+     * (`8`, `'8px'`, `'md'`, `'large'`, `'var(…)'`), minus `shaped` /
+     * `shaped-invert` which are asymmetric by definition.
+     */
     roundedTopRight?: boolean | number | string;
+    /** Top-left corner only. Same vocabulary as `roundedTopRight`. */
     roundedTopLeft?: boolean | number | string;
+    /** Bottom-left corner only. Same vocabulary as `roundedTopRight`. */
     roundedBottomLeft?: boolean | number | string;
+    /** Bottom-right corner only. Same vocabulary as `roundedTopRight`. */
     roundedBottomRight?: boolean | number | string;
 }

package/dist/src/interfaces/CssSupport/css-support.interface.cjs

@@ -0,0 +1 @@
+"use strict";

package/dist/src/interfaces/CssSupport/css-support.interface.d.ts

@@ -0,0 +1,43 @@
+import type { ComputedRef, Ref } from 'vue';
+import type { TCssFeatureName, TCssSupportMap } from '../../types';
+/** Public API returned by `useCssSupport`. */
+export interface IUseCssSupport {
+    /**
+     * Reactive map of feature → `boolean`. Computed once on first browser-
+     * side call; subsequent calls share the same frozen snapshot.
+     */
+    css: Readonly<Ref<TCssSupportMap>>;
+    /**
+     * Free-form query support. Pass any string accepted by `CSS.supports()`.
+     * Result is cached per-query.
+     *
+     * @example
+     *   supports('display: grid')                  // true on modern browsers
+     *   supports('selector(:has(*))')              // selector query
+     *   supports('width: clamp(1px, 50%, 100px)')  // math function
+     */
+    supports: (query: string) => boolean;
+    /**
+     * `true` if at least ONE of the queries is supported.
+     */
+    supportsAny: (...queries: string[]) => boolean;
+    /**
+     * `true` if EVERY query is supported.
+     */
+    supportsAll: (...queries: string[]) => boolean;
+    /**
+     * Reactive `ComputedRef<boolean>` for a single named feature. Useful in
+     * templates: `<div v-if="hasGrid">…`.
+     */
+    has: (feature: TCssFeatureName) => ComputedRef<boolean>;
+}
+/** Options accepted by `useCssSupportClient`. */
+export interface IUseCssSupportClientOptions {
+    /**
+     * Value returned during SSR and on the first client render (before
+     * `onMounted` fires). Pick the side of the branch that produces the
+     * smaller / safer markup — typically `false` (= JS fallback) so the
+     * server output stays universally compatible.
+     */
+    defaultValue?: boolean;
+}

package/dist/src/interfaces/DataList/data-list.interface.d.ts

@@ -1,19 +1,6 @@
 import type { IAdjacentProps, IBorderProps, IBgColorProps, IColorProps, ICommonsComponentProps, IDataListKVItem, IDataTextProps, IDataTitleProps, IDensityProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps, ITypographyProps } from "../../interfaces";
-/**
- * Layout mode of `<OrigamDataList>`.
- *
- * - `"avatar"` (default, back-compat) — the historical `<dl>` layout
- *   where each item stacks a `<dt>` (title) above one or more `<dd>`
- *   rows (text). Items conform to {@link IDataItem}. The naming reflects
- *   the most common usage: a `prependAvatar` per title, with a stack of
- *   labels below — the Vuetify `v-list`-flavoured shape.
- *
- * - `"kv"` — the PDF-aligned key/value table where each row renders a
- *   key on the left (muted) and a value on the right (primary text or
- *   an inline component such as `<origam-chip>` / `<origam-avatar>`).
- *   Items conform to {@link IDataListKVItem}.
- */
-export type TDataListMode = 'avatar' | 'kv';
+import type { TDataListMode } from "../../types";
+export type { TDataListMode } from "../../types/DataList/data-list.type";
 export interface IDataListProps extends ICommonsComponentProps, IAdjacentProps, IColorProps, IBgColorProps, IMarginProps, IPaddingProps, IDensityProps, IBorderProps, IRoundedProps, IElevationProps, ITypographyProps {
     /**
      * Selects the layout. Defaults to `"avatar"` so existing call sites

package/dist/src/interfaces/Dialog/dialog-confirmation.interface.d.ts

@@ -1,9 +1,9 @@
-import type { IDialogProps, IDialogSlots } from '../../interfaces';
+import type { ICommonsComponentEmits, IDialogProps, IDialogSlots } from '../../interfaces';
 export interface IDialogConfirmationProps extends IDialogProps {
     cancellable?: boolean;
 }
 /** Emits fired by `<OrigamDialogConfirmation>` — confirm/cancel buttons. */
-export interface IDialogConfirmationEmits {
+export interface IDialogConfirmationEmits extends ICommonsComponentEmits {
     (e: 'validate', event?: MouseEvent): void;
     (e: 'cancel', event?: MouseEvent): void;
 }

package/dist/src/interfaces/Form/form.interface.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentInternalInstance, ComputedRef, Raw, Ref } from 'vue';
-import type { ICommonsComponentProps, ICommonsComponentSlots, ITypographyProps } from '../../interfaces';
+import type { ICommonsComponentEmits, ICommonsComponentProps, ICommonsComponentSlots, ITypographyProps } from '../../interfaces';
 import type { TValidateOn } from '../../types';
 export interface IFormProvide {
     register: (item: {
@@ -38,7 +38,14 @@ export interface IFormSlots extends ICommonsComponentSlots {
         reset: () => void;
     }) => any;
 }
-export interface IFormEmits {
+/**
+ * `useForm` ÉCRIT la validité calculée dans `modelValue`
+ * (form.composable.ts:77) — c'est un canal sortant, pas seulement une valeur
+ * entrante. L'émission correspondante doit donc être déclarée, sans quoi Vue
+ * avertit à chaque montage et le handler `onUpdate:modelValue` reste dans
+ * `$attrs`, où `inheritAttrs` le pose sur l'élément `<form>` racine.
+ */
+export interface IFormEmits extends ICommonsComponentEmits {
     (e: 'submit', value: any): void;
     (e: 'reset', value: any): void;
 }

package/dist/src/interfaces/Icon/icon.interface.d.ts

@@ -3,8 +3,18 @@ import type { TIcon, TIconComponent } from '../../types';
 export interface IIconProps {
     icon?: TIcon;
 }
+/**
+ * Surface de props partagée par `<OrigamIcon>` et ses quatre feuilles de
+ * rendu (`ClassIcon`, `ComponentIcon`, `LigatureIcon`, `SvgIcon`).
+ *
+ * ⚠️ PAS de prop `disabled` ici, et c'est délibéré. Elle y a été déclarée
+ * puis retirée : aucun des cinq composants ne la lisait, et une icône est
+ * un élément de rendu, pas un élément interactif — il n'y a rien à
+ * désactiver. Un état désactivé se peint sur le contrôle qui PORTE l'icône
+ * (bouton, champ, item de liste), pas sur l'icône elle-même, qui hérite
+ * alors naturellement de son opacité et de son curseur.
+ */
 export interface IIconComponentProps extends IIconProps, IColorProps, IBgColorProps, ICommonsComponentProps, ITagProps, ISizeProps, IPaddingProps, IMarginProps, IBorderProps, IDimensionProps, IRoundedProps {
-    disabled?: boolean;
 }
 /** Slot signatures shared by `<OrigamIcon>` and `<OrigamComponentIcon>` —
  *  a single unscoped `default` slot holding the icon glyph / fallback. */

package/dist/src/interfaces/Mask/mask-options.interface.d.ts

@@ -1,4 +1,5 @@
-import type { TPatternValidator } from '../../types';
+import type { Ref } from 'vue';
+import type { TMaskTokenKind, TPatternValidator } from '../../types';
 /**
  * Configuration object accepted by `useMask` / the
  * `OrigamTextField.mask` prop in its long form.
@@ -42,7 +43,27 @@ export interface IMaskApplyResult {
  * (`#`, `A`, `*`) or is a literal kept verbatim.
  */
 export interface IMaskToken {
-    kind: 'digit' | 'letter' | 'any' | 'literal';
+    kind: TMaskTokenKind;
     char: string;
     consumer: boolean;
 }
+/**
+ * Public return shape of `useMask`.
+ */
+export interface IUseMaskReturn {
+    masked: Ref<string>;
+    unmasked: Ref<string>;
+    isValid: Ref<boolean>;
+    complete: Ref<boolean>;
+    /**
+     * Imperatively re-run the formatter on a raw value
+     * (used by paste / external sync). Returns the new
+     * `unmasked` so callers can keep their model in sync.
+     */
+    setRaw: (raw: string) => string;
+    /**
+     * Currently resolved config (pattern + validator +
+     * required). `null` when no mask is active.
+     */
+    config: Ref<IResolvedMaskConfig | null>;
+}

package/dist/src/interfaces/Masonry/masonry.interface.d.ts

@@ -1,5 +1,6 @@
 import type { IBgColorProps, IBorderProps, IColorProps, ICommonsComponentProps, IDimensionProps, IElevationProps, IMarginProps, IPaddingProps, IRoundedProps, ITagProps } from '../../interfaces';
 import type { TGridGapSize, TMasonryAlign } from '../../types';
+import type { Ref } from 'vue';
 /**
  * Map of `min-width` (px) → number of columns to apply when the
  * container is at least that wide. Container-query based (NOT viewport),
@@ -78,3 +79,57 @@ export interface IMasonryProps extends ICommonsComponentProps, ITagProps, IDimen
      */
     align?: TMasonryAlign;
 }
+/**
+ * Internal layout descriptor produced by the bucket-fill algorithm.
+ * One entry per measured item. Coordinates are expressed in CSS px,
+ * relative to the masonry container's content box.
+ */
+export interface IMasonryItemRect {
+    /** Index of the item in the original DOM order. */
+    index: number;
+    /** `left` (px) of the item inside the container's content box. */
+    left: number;
+    /** `top` (px) of the item inside the container's content box. */
+    top: number;
+    /** Computed width (px) — same for every item in a given pass. */
+    width: number;
+    /** Measured height (px) — preserved from the natural item flow. */
+    height: number;
+    /** Zero-based column index the item was placed into. */
+    column: number;
+}
+/**
+ * Public layout result. The caller uses `containerHeight` to size the
+ * container (absolute-positioned children would otherwise collapse it),
+ * and `items` to read per-item coordinates for inline-style assignment.
+ */
+export interface IMasonryLayoutResult {
+    /** Final container height (px) — `max(column heights)`. */
+    containerHeight: number;
+    /** Per-item position record. Index matches the original DOM order. */
+    items: IMasonryItemRect[];
+    /** Effective column count used for this layout (post-breakpoint). */
+    columns: number;
+}
+/**
+ * Options consumed by `useMasonry`. All inputs are refs so the
+ * composable can react to prop changes from its consumer.
+ */
+export interface IUseMasonryOptions {
+    /** Default column count. Used when no breakpoint matches. */
+    columnsRef: Ref<number>;
+    /**
+     * Gap in **px** between items, both axes. The composable expects an
+     * already-resolved pixel value — string-token resolution happens in
+     * the component wrapper.
+     */
+    gapRef: Ref<number>;
+    /** Optional container-query breakpoints. */
+    breakpointsRef?: Ref<TMasonryColumnBreakpoints | undefined>;
+    /**
+     * Vertical alignment of items inside a column. `'top'` packs to the
+     * top; `'center'` shifts each column's content down by half the
+     * unused space.
+     */
+    alignRef?: Ref<TMasonryAlign>;
+}

package/dist/src/interfaces/Media/media-scrubber.interface.d.ts

@@ -30,6 +30,12 @@ export interface IMediaScrubberProps extends ICommonsComponentProps, IColorProps
      * Upper bound of the value range. Required to compute the thumb
      * position. Passing `0` (or any value `<= min`) freezes the
      * scrubber at the start.
+     *
+     * A frozen range is the NORMAL mount state for a media scrubber, not
+     * an error: `OrigamMediaController` feeds `scrubberMax`, which stays
+     * `0` until `state.duration` becomes finite. `aria-valuemax` reports
+     * that empty range honestly (`0`), never the internal epsilon the
+     * component uses to keep the percentage division finite.
      */
     max: number;
     /**
@@ -100,9 +106,25 @@ export interface IMediaScrubberProps extends ICommonsComponentProps, IColorProps
      */
     ariaValueText?: string;
     /**
-     * Optional `data-cy` test selector forwarded by the parent
-     * (`OrigamMediaController`, `OrigamMediaVolumeControl`) as a
-     * camelCase Vue prop. Passed through `$attrs` to the host element.
+     * `data-cy` test selector for the host element.
+     *
+     * Declaring it as a prop REMOVES it from `$attrs`, so it is rendered
+     * explicitly by the template — it does not fall through. When a parent
+     * forwards one it WINS over the component's own literal; the literal
+     * `'origam-media-scrubber'` is only the fallback for a standalone
+     * instance nobody named.
+     *
+     * Both in-house parents forward one, so inside `<OrigamVideo>` /
+     * `<OrigamAudio>` the fallback is never what renders:
+     *   - `OrigamMediaController` → `origam-media-controller-scrubber`
+     *     (the timeline, on the `#waveform` fallback)
+     *   - `OrigamMediaVolumeControl` → its own `dataCy` verbatim, i.e.
+     *     `origam-media-controller-volume` in the default toolbar
+     *
+     * Target the composed name in tests. Asserting on the bare literal is
+     * what made `video.spec.ts` red on all three engines.
+     *
+     * @default 'origam-media-scrubber'
      */
     dataCy?: string;
 }

package/dist/src/interfaces/Menu/menu.interface.d.ts

@@ -7,11 +7,19 @@ export interface IMenuProvide {
 export interface IMenuProps extends IOverlayProps, IListProps, IListItemProps {
     id?: string;
 }
-/** Emits fired by `<OrigamMenu>` — v-model on the open state plus the
+/** Emits fired by `<OrigamMenu>` — v-model on the open state, the
  *  native `contextmenu` bubble forwarded for parents that want to
- *  show their own context menu instead. */
+ *  show their own context menu instead, and `select` when the user
+ *  picks a leaf row of the `items` tree.
+ *
+ *  `select` matters because `<origam-menu :items="…">` renders its own
+ *  rows: the consumer never gets a handle on the `<origam-list-item>`
+ *  that receives the click. Without it, the only way to learn which row
+ *  was picked is to hang an `onClick` on every item object. Rows that
+ *  open a submenu do NOT emit — they are navigation, not a choice. */
 export interface IMenuEmits extends ICommonsComponentEmits {
     (e: 'contextmenu', event: MouseEvent): void;
+    (e: 'select', item: IListItemProps): void;
 }
 /** Slot signatures for `<OrigamMenu>`. `activator` only forwards the
  *  merged `props` bag (not the inner overlay's `isActive`) — matches