@moni-labs/moni-ui 0.2.0 → 0.3.0

package/dist/components/moni-snackbar.d.ts

@@ -1,35 +1,104 @@
+/**
+ * @file components/moni-snackbar.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Snackbar that faithfully ports BeerCSS's `.snackbar` styles.
+ * Material Design 3 Snackbar component.
+ *
+ * Snackbars provide brief messages about app processes at the bottom of the
+ * screen. They disappear automatically and do not require user action,
+ * but may contain a single optional action.
+ *
+ * **M3 spec reference:** `m3-docs/components/snackbar/specs.md`
+ *
+ * **Positioning model:**
+ * The snackbar uses `position: fixed` so it renders in the viewport
+ * regardless of which element it is placed in the DOM. The host element
+ * displays as `block` rather than `contents` to ensure `position: fixed`
+ * inside the shadow root anchors to the viewport (not to a stacking context
+ * created by a transformed ancestor).
+ *
+ * **Show/hide mechanism:**
+ * Visibility is controlled by `:host([active]) .snackbar` via CSS
+ * `opacity`, `visibility`, and `transform`. This mirrors BeerCSS's
+ * `.snackbar.active` pattern and allows CSS transition animations.
+ *
+ * **M3 text truncation:**
+ * The message text is clamped to `maxLines` lines with `-webkit-line-clamp`.
+ * The M3 spec requires a maximum of 2 lines; consumers can override this
+ * via the `max-lines` attribute.
  *
- * BeerCSS uses `.snackbar` with `position: fixed; inset: auto auto 6rem 50%;`
- * and `.snackbar.active` / `.snackbar:popover-open` to show it.
+ * @example
+ * ```ts
+ * const snackbar = document.querySelector('moni-snackbar') as MoniSnackbar;
  *
- * We use :host([active]) .snackbar with visibility/opacity/transform — same as BeerCSS.
- * The host is display:block so the fixed snackbar inside is part of the stacking context
- * of the document body (not clipped by any shadow root overflow).
+ * // Show for 3 seconds
+ * snackbar.text = 'Item deleted';
+ * snackbar.action = 'Undo';
+ * snackbar.active = true;
+ * setTimeout(() => { snackbar.active = false; }, 3000);
+ * ```
  *
- * Material 3 spec (`m3-docs/components/snackbar/specs.md`): the message text
- * must truncate at **2 lines** with ellipsis when too long. The container
- * width adapts to the screen size (full width on compact, 40% on expanded).
+ * @slot default - Additional content placed inside the snackbar container.
  *
- * Attributes:
- *  - text:      message
- *  - action:    action label (visual only)
- *  - placement: bottom (default) | top
- *  - active:    present → visible
- *  - max-lines: 2 (default) | number — clamp text to N lines with ellipsis
+ * @csspart snackbar - The inner snackbar container element.
+ * @csspart text     - The message text element.
+ * @csspart action   - The action button element.
  */
 export declare class MoniSnackbar extends MoniElement {
+    /**
+     * The main message text displayed in the snackbar.
+     *
+     * Clamped to `maxLines` lines. Long messages are truncated with `…`.
+     * Per M3 spec, keep messages short and informative (under 60 characters).
+     *
+     * @default ''
+     */
     text: string;
+    /**
+     * Label for the optional action button.
+     *
+     * When non-empty, renders a text button on the trailing edge of the snackbar.
+     * The component dispatches a `'action'` event when the action is clicked.
+     * This is a visual-only label — the consumer handles the action logic.
+     *
+     * @default ''
+     */
     action: string;
+    /**
+     * Vertical placement of the snackbar on the screen.
+     *
+     * - `'bottom'` (default) — Fixed 6rem from the bottom, centered horizontally.
+     * - `'top'` — Fixed 6rem from the top, centered horizontally.
+     *
+     * @default 'bottom'
+     */
     placement: 'bottom' | 'top';
+    /**
+     * When `true`, the snackbar is visible.
+     *
+     * Toggle this attribute to show/hide the snackbar. The CSS transition
+     * handles the fade-in/slide-up animation automatically.
+     * Consumers are responsible for implementing the auto-dismiss timer.
+     *
+     * @default false
+     */
     active: boolean;
-    /** M3 spec: clamp the message text to N lines (default 2). */
+    /**
+     * Maximum number of lines of message text before it is clamped.
+     *
+     * Uses `-webkit-line-clamp` with `display: -webkit-box` for cross-browser
+     * multi-line truncation. The M3 spec recommends a maximum of 2 lines.
+     *
+     * @default 2
+     */
     maxLines: number;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/components/moni-snackbar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-snackbar.d.ts","sourceRoot":"","sources":["../../src/components/moni-snackbar.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBACa,YAAa,SAAQ,WAAW;IACf,IAAI,SAAM;IACV,MAAM,SAAM;IAEzC,SAAS,EAAE,QAAQ,GAAG,KAAK,CAAY;IACK,MAAM,UAAS;IAC3D,8DAA8D;IAE9D,QAAQ,SAAK;IAEb,OAAgB,MAAM,4BAmFpB;IAEO,MAAM;CAef;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,YAAY,CAAC;KAC9B;CACD;AAED,eAAe,YAAY,CAAC"}
+{"version":3,"file":"moni-snackbar.d.ts","sourceRoot":"","sources":["../../src/components/moni-snackbar.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBACa,YAAa,SAAQ,WAAW;IAC5C;;;;;;;OAOG;IAC0B,IAAI,SAAM;IAEvC;;;;;;;;OAQG;IAC0B,MAAM,SAAM;IAEzC;;;;;;;OAOG;IAEH,SAAS,EAAE,QAAQ,GAAG,KAAK,CAAY;IAEvC;;;;;;;;OAQG;IACyC,MAAM,UAAS;IAE3D;;;;;;;OAOG;IAEH,QAAQ,SAAK;IAEb,OAAgB,MAAM,4BAmFpB;IAEO,MAAM;CAef;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,YAAY,CAAC;KAC9B;CACD;AAED,eAAe,YAAY,CAAC"}

package/dist/components/moni-snackbar.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-snackbar.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -9,34 +15,97 @@ import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Snackbar that faithfully ports BeerCSS's `.snackbar` styles.
+ * Material Design 3 Snackbar component.
+ *
+ * Snackbars provide brief messages about app processes at the bottom of the
+ * screen. They disappear automatically and do not require user action,
+ * but may contain a single optional action.
+ *
+ * **M3 spec reference:** `m3-docs/components/snackbar/specs.md`
+ *
+ * **Positioning model:**
+ * The snackbar uses `position: fixed` so it renders in the viewport
+ * regardless of which element it is placed in the DOM. The host element
+ * displays as `block` rather than `contents` to ensure `position: fixed`
+ * inside the shadow root anchors to the viewport (not to a stacking context
+ * created by a transformed ancestor).
+ *
+ * **Show/hide mechanism:**
+ * Visibility is controlled by `:host([active]) .snackbar` via CSS
+ * `opacity`, `visibility`, and `transform`. This mirrors BeerCSS's
+ * `.snackbar.active` pattern and allows CSS transition animations.
+ *
+ * **M3 text truncation:**
+ * The message text is clamped to `maxLines` lines with `-webkit-line-clamp`.
+ * The M3 spec requires a maximum of 2 lines; consumers can override this
+ * via the `max-lines` attribute.
  *
- * BeerCSS uses `.snackbar` with `position: fixed; inset: auto auto 6rem 50%;`
- * and `.snackbar.active` / `.snackbar:popover-open` to show it.
+ * @example
+ * ```ts
+ * const snackbar = document.querySelector('moni-snackbar') as MoniSnackbar;
  *
- * We use :host([active]) .snackbar with visibility/opacity/transform — same as BeerCSS.
- * The host is display:block so the fixed snackbar inside is part of the stacking context
- * of the document body (not clipped by any shadow root overflow).
+ * // Show for 3 seconds
+ * snackbar.text = 'Item deleted';
+ * snackbar.action = 'Undo';
+ * snackbar.active = true;
+ * setTimeout(() => { snackbar.active = false; }, 3000);
+ * ```
  *
- * Material 3 spec (`m3-docs/components/snackbar/specs.md`): the message text
- * must truncate at **2 lines** with ellipsis when too long. The container
- * width adapts to the screen size (full width on compact, 40% on expanded).
+ * @slot default - Additional content placed inside the snackbar container.
  *
- * Attributes:
- *  - text:      message
- *  - action:    action label (visual only)
- *  - placement: bottom (default) | top
- *  - active:    present → visible
- *  - max-lines: 2 (default) | number — clamp text to N lines with ellipsis
+ * @csspart snackbar - The inner snackbar container element.
+ * @csspart text     - The message text element.
+ * @csspart action   - The action button element.
  */
 let MoniSnackbar = class MoniSnackbar extends MoniElement {
     constructor() {
         super(...arguments);
+        /**
+         * The main message text displayed in the snackbar.
+         *
+         * Clamped to `maxLines` lines. Long messages are truncated with `…`.
+         * Per M3 spec, keep messages short and informative (under 60 characters).
+         *
+         * @default ''
+         */
         this.text = '';
+        /**
+         * Label for the optional action button.
+         *
+         * When non-empty, renders a text button on the trailing edge of the snackbar.
+         * The component dispatches a `'action'` event when the action is clicked.
+         * This is a visual-only label — the consumer handles the action logic.
+         *
+         * @default ''
+         */
         this.action = '';
+        /**
+         * Vertical placement of the snackbar on the screen.
+         *
+         * - `'bottom'` (default) — Fixed 6rem from the bottom, centered horizontally.
+         * - `'top'` — Fixed 6rem from the top, centered horizontally.
+         *
+         * @default 'bottom'
+         */
         this.placement = 'bottom';
+        /**
+         * When `true`, the snackbar is visible.
+         *
+         * Toggle this attribute to show/hide the snackbar. The CSS transition
+         * handles the fade-in/slide-up animation automatically.
+         * Consumers are responsible for implementing the auto-dismiss timer.
+         *
+         * @default false
+         */
         this.active = false;
-        /** M3 spec: clamp the message text to N lines (default 2). */
+        /**
+         * Maximum number of lines of message text before it is clamped.
+         *
+         * Uses `-webkit-line-clamp` with `display: -webkit-box` for cross-browser
+         * multi-line truncation. The M3 spec recommends a maximum of 2 lines.
+         *
+         * @default 2
+         */
         this.maxLines = 2;
     }
     static { this.styles = [

package/dist/components/moni-split-button.d.ts

@@ -1,15 +1,44 @@
+/**
+ * @file components/moni-split-button.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Visual-only split button. Combines a primary action button and a dropdown menu trigger.
+ * Material Design 3 Split Button component.
+ *
+ * A split button combines a primary action button with a secondary dropdown
+ * button. The two buttons sit flush against each other, typically sharing
+ * a background color and elevation, but separated by a distinct border.
+ *
+ * **Visual architecture:**
+ * The component acts as a layout container (`display: inline-flex`) that
+ * groups two standard buttons. It overrides the margins of the trailing
+ * button to create the "connected" look (similar to connected button groups).
+ *
+ * **Usage:**
+ * Consumers must provide exactly two buttons via the named slots:
+ * - `slot="leading-button"` — The primary action (usually text or text+icon).
+ * - `slot="trailing-button"` — The secondary action (usually just a dropdown icon).
+ *
+ * Both buttons should be standard `<moni-button>` or `<moni-icon-button>`
+ * elements configured with matching variants for a cohesive appearance.
+ *
+ * @example
+ * ```html
+ * <moni-split-button variant="filled">
+ *   <moni-button slot="leading-button" icon="send">Send</moni-button>
+ *   <moni-button slot="trailing-button" icon="arrow_drop_down" id="schedule-trigger"></moni-button>
+ * </moni-split-button>
  *
- * Attributes:
- *  - variant: filled (default) | tonal | outlined | elevated
- *  - size:    small | medium (default) | large | extra
- *  - gap:     custom gap space (e.g. "8px" or "1rem")
+ * <moni-menu id="schedule-menu" placement="bottom">
+ *   <moni-menu-item>Schedule send...</moni-menu-item>
+ * </moni-menu>
+ * ```
  *
- * Slots:
- *  - leading-button:  The main action button
- *  - trailing-button: The menu dropdown button
+ * @slot leading-button  - The primary action button on the left.
+ * @slot trailing-button - The secondary action (dropdown trigger) on the right.
  */
 export declare class MoniSplitButton extends MoniElement {
     variant: 'filled' | 'tonal' | 'outlined' | 'elevated';
@@ -22,7 +51,7 @@ export declare class MoniSplitButton extends MoniElement {
     private handleSlotChange;
     private getGapValue;
     private updateChildren;
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/components/moni-split-button.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-split-button.d.ts","sourceRoot":"","sources":["../../src/components/moni-split-button.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,qBACa,eAAgB,SAAQ,WAAW;IAE/C,OAAO,EAAE,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAY;IAGjE,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAG9E,GAAG,SAAM;IAGT,OAAO,CAAC,eAAe,CAAiB;IAGxC,OAAO,CAAC,gBAAgB,CAAiB;IAEzC,OAAgB,MAAM,4BAoBpB;cAEiB,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC;IAOpF,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,cAAc;IAuBb,MAAM;CAYf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,mBAAmB,EAAE,eAAe,CAAC;KACrC;CACD;AAED,eAAe,eAAe,CAAC"}
+{"version":3,"file":"moni-split-button.d.ts","sourceRoot":"","sources":["../../src/components/moni-split-button.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBACa,eAAgB,SAAQ,WAAW;IAE/C,OAAO,EAAE,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,UAAU,CAAY;IAGjE,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAG9E,GAAG,SAAM;IAGT,OAAO,CAAC,eAAe,CAAiB;IAGxC,OAAO,CAAC,gBAAgB,CAAiB;IAEzC,OAAgB,MAAM,4BAoBpB;cAEiB,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC;IAOpF,OAAO,CAAC,gBAAgB;IAIxB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,cAAc;IAuBb,MAAM;CAYf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,mBAAmB,EAAE,eAAe,CAAC;KACrC;CACD;AAED,eAAe,eAAe,CAAC"}

package/dist/components/moni-split-button.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-split-button.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -8,16 +14,39 @@ import { html, css } from 'lit';
 import { customElement, property, queryAssignedElements } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Visual-only split button. Combines a primary action button and a dropdown menu trigger.
+ * Material Design 3 Split Button component.
+ *
+ * A split button combines a primary action button with a secondary dropdown
+ * button. The two buttons sit flush against each other, typically sharing
+ * a background color and elevation, but separated by a distinct border.
+ *
+ * **Visual architecture:**
+ * The component acts as a layout container (`display: inline-flex`) that
+ * groups two standard buttons. It overrides the margins of the trailing
+ * button to create the "connected" look (similar to connected button groups).
+ *
+ * **Usage:**
+ * Consumers must provide exactly two buttons via the named slots:
+ * - `slot="leading-button"` — The primary action (usually text or text+icon).
+ * - `slot="trailing-button"` — The secondary action (usually just a dropdown icon).
+ *
+ * Both buttons should be standard `<moni-button>` or `<moni-icon-button>`
+ * elements configured with matching variants for a cohesive appearance.
+ *
+ * @example
+ * ```html
+ * <moni-split-button variant="filled">
+ *   <moni-button slot="leading-button" icon="send">Send</moni-button>
+ *   <moni-button slot="trailing-button" icon="arrow_drop_down" id="schedule-trigger"></moni-button>
+ * </moni-split-button>
  *
- * Attributes:
- *  - variant: filled (default) | tonal | outlined | elevated
- *  - size:    small | medium (default) | large | extra
- *  - gap:     custom gap space (e.g. "8px" or "1rem")
+ * <moni-menu id="schedule-menu" placement="bottom">
+ *   <moni-menu-item>Schedule send...</moni-menu-item>
+ * </moni-menu>
+ * ```
  *
- * Slots:
- *  - leading-button:  The main action button
- *  - trailing-button: The menu dropdown button
+ * @slot leading-button  - The primary action button on the left.
+ * @slot trailing-button - The secondary action (dropdown trigger) on the right.
  */
 let MoniSplitButton = class MoniSplitButton extends MoniElement {
     constructor() {

package/dist/components/moni-step.d.ts

@@ -1,15 +1,48 @@
+/**
+ * @file components/moni-step.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Visual-only step. Renders an icon/number, a title, and a description.
+ * Material Design 3 Step component.
+ *
+ * An individual step within a `<moni-stepper>`. Steps display progress through
+ * a sequence of logical and numbered operations.
+ *
+ * **M3 spec reference:** `m3-docs/components/progress-indicators/specs.md` (Stepper pattern)
+ *
+ * **Anatomy & Visuals:**
+ * A step renders a circular indicator containing either its sequence number
+ * (automatically injected by the parent stepper) or a custom icon. Below or
+ * beside the indicator (depending on the parent's `orientation`), it renders
+ * the `title` and an optional `description`.
+ *
+ * **State management:**
+ * The parent `<moni-stepper>` automatically calculates and injects the `index`,
+ * `active`, and `completed` properties based on its current state.
+ * - **Active:** Highlighted with the primary color, indicating the current step.
+ * - **Completed:** Displayed with a solid primary background and a checkmark
+ *   icon (`completed` state overrides the numeric index).
+ *
+ * @example
+ * ```html
+ * <!-- Typically used inside a stepper -->
+ * <moni-stepper current="1">
+ *   <moni-step title="Shipping" description="Enter address"></moni-step>
+ *   <moni-step title="Payment" description="Credit card details"></moni-step>
+ *   <moni-step title="Review" description="Confirm order"></moni-step>
+ * </moni-stepper>
+ *
+ * <!-- Overriding the icon -->
+ * <moni-step title="Done" icon="celebration"></moni-step>
+ * ```
  *
- * Attributes:
- *  - title:       step heading
- *  - description: step secondary text
- *  - active:      present → primary color highlight
- *  - completed:   present → filled circle with check
- *  - icon:        Material Symbols name (overrides the number)
- *  - index:       numeric label (auto-set by parent stepper, optional)
+ * @csspart step-indicator - The circular badge containing the number/icon.
+ * @csspart title          - The main title text.
+ * @csspart description    - The secondary description text.
  */
 export declare class MoniStep extends MoniElement {
     title: string;
@@ -19,7 +52,7 @@ export declare class MoniStep extends MoniElement {
     icon: string;
     index: number;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/components/moni-step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-step.d.ts","sourceRoot":"","sources":["../../src/components/moni-step.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;GAUG;AACH,qBACa,QAAS,SAAQ,WAAW;IACX,KAAK,SAAM;IACX,WAAW,SAAM;IACF,MAAM,UAAS;IACf,SAAS,UAAS;IACjC,IAAI,SAAM;IACI,KAAK,SAAK;IAErD,OAAgB,MAAM,4BAqGpB;IAEO,MAAM;CAkBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,WAAW,EAAE,QAAQ,CAAC;KACtB;CACD;AAED,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"moni-step.d.ts","sourceRoot":"","sources":["../../src/components/moni-step.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBACa,QAAS,SAAQ,WAAW;IACX,KAAK,SAAM;IACX,WAAW,SAAM;IACF,MAAM,UAAS;IACf,SAAS,UAAS;IACjC,IAAI,SAAM;IACI,KAAK,SAAK;IAErD,OAAgB,MAAM,4BAqGpB;IAEO,MAAM;CAkBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,WAAW,EAAE,QAAQ,CAAC;KACtB;CACD;AAED,eAAe,QAAQ,CAAC"}

package/dist/components/moni-step.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-step.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -9,15 +15,42 @@ import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Visual-only step. Renders an icon/number, a title, and a description.
+ * Material Design 3 Step component.
+ *
+ * An individual step within a `<moni-stepper>`. Steps display progress through
+ * a sequence of logical and numbered operations.
+ *
+ * **M3 spec reference:** `m3-docs/components/progress-indicators/specs.md` (Stepper pattern)
+ *
+ * **Anatomy & Visuals:**
+ * A step renders a circular indicator containing either its sequence number
+ * (automatically injected by the parent stepper) or a custom icon. Below or
+ * beside the indicator (depending on the parent's `orientation`), it renders
+ * the `title` and an optional `description`.
+ *
+ * **State management:**
+ * The parent `<moni-stepper>` automatically calculates and injects the `index`,
+ * `active`, and `completed` properties based on its current state.
+ * - **Active:** Highlighted with the primary color, indicating the current step.
+ * - **Completed:** Displayed with a solid primary background and a checkmark
+ *   icon (`completed` state overrides the numeric index).
+ *
+ * @example
+ * ```html
+ * <!-- Typically used inside a stepper -->
+ * <moni-stepper current="1">
+ *   <moni-step title="Shipping" description="Enter address"></moni-step>
+ *   <moni-step title="Payment" description="Credit card details"></moni-step>
+ *   <moni-step title="Review" description="Confirm order"></moni-step>
+ * </moni-stepper>
+ *
+ * <!-- Overriding the icon -->
+ * <moni-step title="Done" icon="celebration"></moni-step>
+ * ```
  *
- * Attributes:
- *  - title:       step heading
- *  - description: step secondary text
- *  - active:      present → primary color highlight
- *  - completed:   present → filled circle with check
- *  - icon:        Material Symbols name (overrides the number)
- *  - index:       numeric label (auto-set by parent stepper, optional)
+ * @csspart step-indicator - The circular badge containing the number/icon.
+ * @csspart title          - The main title text.
+ * @csspart description    - The secondary description text.
  */
 let MoniStep = class MoniStep extends MoniElement {
     constructor() {

package/dist/components/moni-stepper.d.ts

@@ -1,11 +1,48 @@
+/**
+ * @file components/moni-stepper.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Visual-only stepper. Wraps a list of <moni-step> children, propagates the
- * `current` index to each child, and styles the connectors between them.
+ * Material Design 3 Stepper component.
+ *
+ * A container for a linear progression of `<moni-step>` elements. Steppers
+ * convey progress through numbered steps and indicate the user's current
+ * position within a flow.
+ *
+ * **M3 spec reference:** `m3-docs/components/progress-indicators/specs.md`
+ *
+ * **Orchestration:**
+ * This component acts as the orchestrator for its slotted `<moni-step>` children.
+ * Whenever the `current` property changes, or children are added/removed, the
+ * stepper iterates over all child steps and injects their state:
+ * - Assigns the sequential `index` (0-based) to each step.
+ * - Sets `active=true` on the step matching the `current` index.
+ * - Sets `completed=true` on all steps prior to the `current` index.
+ *
+ * **Visual layout:**
+ * The stepper manages the layout (flex row or column based on `orientation`)
+ * and ensures the connector lines between steps are rendered correctly via
+ * CSS pseudo-elements defined in the child `<moni-step>` styling.
+ *
+ * @example
+ * ```html
+ * <moni-stepper current="1" orientation="horizontal">
+ *   <moni-step title="Step 1"></moni-step>
+ *   <moni-step title="Step 2"></moni-step>
+ *   <moni-step title="Step 3"></moni-step>
+ * </moni-stepper>
+ *
+ * <script>
+ *   const stepper = document.querySelector('moni-stepper');
+ *   // Move to next step
+ *   stepper.current = 2;
+ * </script>
+ * ```
  *
- * Attributes:
- *  - orientation: horizontal (default) | vertical
- *  - current:     zero-based index of the active step
+ * @slot default - `<moni-step>` elements.
  */
 export declare class MoniStepper extends MoniElement {
     orientation: 'horizontal' | 'vertical';
@@ -23,7 +60,7 @@ export declare class MoniStepper extends MoniElement {
      */
     private _syncSteps;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
     private _onSlotChange;
 }
 declare global {

package/dist/components/moni-stepper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-stepper.d.ts","sourceRoot":"","sources":["../../src/components/moni-stepper.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAG7D;;;;;;;GAOG;AACH,qBACa,WAAY,SAAQ,WAAW;IAE3C,WAAW,EAAE,YAAY,GAAG,UAAU,CAAgB;IACX,OAAO,SAAK;IAGvD,OAAO,CAAC,MAAM,CAAc;IAEnB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAU9C;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;IAclB,OAAgB,MAAM,4BAwBpB;IAEO,MAAM;IAMf,OAAO,CAAC,aAAa,CAGnB;CACF;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,cAAc,EAAE,WAAW,CAAC;KAC5B;CACD;AAED,eAAe,WAAW,CAAC"}
+{"version":3,"file":"moni-stepper.d.ts","sourceRoot":"","sources":["../../src/components/moni-stepper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBACa,WAAY,SAAQ,WAAW;IAE3C,WAAW,EAAE,YAAY,GAAG,UAAU,CAAgB;IACX,OAAO,SAAK;IAGvD,OAAO,CAAC,MAAM,CAAc;IAEnB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAU9C;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;IAclB,OAAgB,MAAM,4BAwBpB;IAEO,MAAM;IAMf,OAAO,CAAC,aAAa,CAGnB;CACF;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,cAAc,EAAE,WAAW,CAAC;KAC5B;CACD;AAED,eAAe,WAAW,CAAC"}

package/dist/components/moni-stepper.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-stepper.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -8,12 +14,43 @@ import { html, css } from 'lit';
 import { customElement, property, queryAssignedElements } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Visual-only stepper. Wraps a list of <moni-step> children, propagates the
- * `current` index to each child, and styles the connectors between them.
+ * Material Design 3 Stepper component.
+ *
+ * A container for a linear progression of `<moni-step>` elements. Steppers
+ * convey progress through numbered steps and indicate the user's current
+ * position within a flow.
+ *
+ * **M3 spec reference:** `m3-docs/components/progress-indicators/specs.md`
+ *
+ * **Orchestration:**
+ * This component acts as the orchestrator for its slotted `<moni-step>` children.
+ * Whenever the `current` property changes, or children are added/removed, the
+ * stepper iterates over all child steps and injects their state:
+ * - Assigns the sequential `index` (0-based) to each step.
+ * - Sets `active=true` on the step matching the `current` index.
+ * - Sets `completed=true` on all steps prior to the `current` index.
+ *
+ * **Visual layout:**
+ * The stepper manages the layout (flex row or column based on `orientation`)
+ * and ensures the connector lines between steps are rendered correctly via
+ * CSS pseudo-elements defined in the child `<moni-step>` styling.
+ *
+ * @example
+ * ```html
+ * <moni-stepper current="1" orientation="horizontal">
+ *   <moni-step title="Step 1"></moni-step>
+ *   <moni-step title="Step 2"></moni-step>
+ *   <moni-step title="Step 3"></moni-step>
+ * </moni-stepper>
+ *
+ * <script>
+ *   const stepper = document.querySelector('moni-stepper');
+ *   // Move to next step
+ *   stepper.current = 2;
+ * </script>
+ * ```
  *
- * Attributes:
- *  - orientation: horizontal (default) | vertical
- *  - current:     zero-based index of the active step
+ * @slot default - `<moni-step>` elements.
  */
 let MoniStepper = class MoniStepper extends MoniElement {
     constructor() {