@moni-labs/moni-ui 0.2.0 → 0.3.0

package/src/components/moni-select-option.ts

@@ -1,16 +1,51 @@
+/**
+ * @file components/moni-select-option.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Option item for custom moni-select dropdown.
+ * Material Design 3 Select Option component.
+ *
+ * An individual selectable item designed to be placed inside a
+ * `<moni-select>` dropdown.
+ *
+ * **Interaction and layout:**
+ * Options are rendered as accessible `<li>` elements styled identically to
+ * `<moni-menu-item>`. When slotted into a `<moni-select>`, the parent
+ * component extracts their `value`, `label`, and `group` attributes to build
+ * its internal data model and handles the actual selection logic, keyboard
+ * navigation, and rendering within the dropdown popup.
+ *
+ * **Grouping:**
+ * Options can be categorized into subcategories by providing a `group`
+ * attribute. The parent `<moni-select>` uses this to automatically generate
+ * group headers (`<moni-select-group>`) in the dropdown list.
+ *
+ * @example
+ * ```html
+ * <moni-select label="Favorite framework">
+ *   <!-- Standard option -->
+ *   <moni-select-option value="lit">Lit Element</moni-select-option>
+ *
+ *   <!-- Disabled option -->
+ *   <moni-select-option value="react" disabled>React (not allowed)</moni-select-option>
+ *
+ *   <!-- Grouped option -->
+ *   <moni-select-option value="vue" group="Other">Vue.js</moni-select-option>
+ * </moni-select>
+ * ```
+ *
+ * @slot default - The text label for the option. If the `label` attribute is
+ *                omitted, the parent `<moni-select>` will read this slot's
+ *                `textContent`.
  *
- * Attributes:
- *  - value:    string value of the option
- *  - label:    text label (uses textContent or slot if empty)
- *  - group:    subcategory group/category name
- *  - selected: present -> active highlight state
- *  - disabled: present -> disabled
+ * @csspart item - The outer `<li>` element.
  */
 @customElement('moni-select-option')
 export class MoniSelectOption extends MoniElement {

package/src/components/moni-select.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-select.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css, nothing } from 'lit';
 import { customElement, property, state, query } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
@@ -7,25 +14,96 @@ import './moni-icon.js';
 import './moni-progress.js';
 import './moni-select-option.js';
 
+/**
+ * Internal representation of a single option within the select dropdown.
+ *
+ * @internal
+ */
 interface OptionNode {
+	/** Discriminant property that identifies this node as an option. */
 	type: 'option';
+	/** The value submitted when this option is selected. */
 	value: string;
+	/** The display label shown in the dropdown list. */
 	label: string;
+	/** When `true`, the option is non-interactive and grayed out. */
 	disabled?: boolean;
+	/** Reference to the original slotted `<moni-select-option>` element, if any. */
 	element?: HTMLElement;
+	/** Optional group name for organizing options under a `<moni-select-group>`. */
 	group?: string;
 }
 
+/**
+ * Internal representation of an option group within the select dropdown.
+ *
+ * @internal
+ */
 interface GroupNode {
+	/** Discriminant property that identifies this node as a group. */
 	type: 'group';
+	/** The group header label displayed above the group's options. */
 	label: string;
+	/** The options nested within this group. */
 	children: DropdownNode[];
 }
 
+/** Union type for any node in the dropdown tree. @internal */
 type DropdownNode = OptionNode | GroupNode;
 
 /**
- * Custom Searchable Select Component with Subcategories, Animations, and Drawer/Sheet option.
+ * Material Design 3 Select (Dropdown) component.
+ *
+ * A fully-featured custom select dropdown with searchability, option groups,
+ * keyboard navigation, animation, and optional mobile drawer/sheet mode.
+ * Replaces the native `<select>` element with a fully styled, accessible
+ * M3-compliant alternative.
+ *
+ * **M3 spec reference:** `m3-docs/components/menus/specs.md` (dropdown menus)
+ *
+ * **Feature summary:**
+ * - Filled and outlined variants matching the M3 text field styles.
+ * - Floating label with the standard field-styles floating label animation.
+ * - Searchable mode: `searchable` attribute adds an inline filter input.
+ * - Option groups: slot `<moni-select-group>` elements for hierarchical options.
+ * - Mobile drawer: `drawer` attribute opens options in a `<moni-bottom-sheet>`
+ *   instead of a dropdown popup, ideal for touch UIs.
+ * - Keyboard navigation: Arrow keys, Enter, Escape, and Tab per ARIA combobox.
+ * - Loading state: `loading` shows an indeterminate circular progress.
+ * - Multi-value support: `multiple` enables multiple selection.
+ *
+ * **Option sources:**
+ * Options can be provided in two ways:
+ * 1. **Slotted `<moni-select-option>` elements** (default, recommended for SSR).
+ * 2. **`options` property** — a `DropdownNode[]` array for fully programmatic control.
+ *
+ * **Value binding:**
+ * The `value` property holds the currently selected option's value string.
+ * For multiple selection, `values` holds `string[]`. On change, a composed
+ * `'change'` event is fired.
+ *
+ * @fires change - Bubbles and is composed. Fired when the selected value changes.
+ *                 Read `element.value` (or `element.values` for `multiple`).
+ *
+ * @example
+ * ```html
+ * <moni-select label="Country" name="country" variant="outlined">
+ *   <moni-select-option value="us">United States</moni-select-option>
+ *   <moni-select-option value="gb">United Kingdom</moni-select-option>
+ *   <moni-select-option value="de">Germany</moni-select-option>
+ * </moni-select>
+ *
+ * <!-- Searchable select -->
+ * <moni-select label="Language" searchable>
+ *   <moni-select-option value="ts">TypeScript</moni-select-option>
+ *   <moni-select-option value="py">Python</moni-select-option>
+ * </moni-select>
+ * ```
+ *
+ * @slot default - `<moni-select-option>` or `<moni-select-group>` children.
+ *
+ * @csspart field    - The outer `.field` div container.
+ * @csspart dropdown - The floating option list container.
  */
 @customElement('moni-select')
 export class MoniSelect extends MoniElement {

package/src/components/moni-side-sheet.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-side-sheet.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css, PropertyValues } from 'lit';
 import { customElement, property, query } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
@@ -5,24 +12,55 @@ import './moni-icon.js';
 import './moni-button.js';
 
 /**
- * Material Design 3 Side Sheet Component.
- * Can act as a standard (non-modal) side sheet or a modal side sheet.
+ * Material Design 3 Side Sheet component.
+ *
+ * Side sheets show supplementary content that is anchored to the left or right
+ * edge of the screen. They can be standard (inline with content) or modal
+ * (overlaying content with a scrim).
+ *
+ * **M3 spec reference:** `m3-docs/components/side-sheets/specs.md`
+ *
+ * **Dialog behavior:**
+ * Internally, this component uses the native HTML `<dialog>` element for robust
+ * accessibility, focus trapping, and top-layer rendering.
+ * - When `modal=true`, the sheet uses `dialog.showModal()`, rendering a scrim
+ *   backdrop and trapping focus. Pressing `Escape` closes it.
+ * - When `modal=false`, the sheet uses `dialog.show()` and remains interactive
+ *   alongside the main page content.
+ *
+ * **Drag & Resize (Moni feature):**
+ * Setting the `with-handle` attribute adds a draggable grab handle to the inner
+ * edge of the sheet. Users can click and drag this handle to resize the sheet's
+ * width up to the `max-width` limit. If the user drags the sheet towards the
+ * screen edge quickly or beyond a certain threshold, it automatically closes.
+ *
+ * **Animations:**
+ * Side sheets slide in from the specified `side` (`left` or `right`). The open
+ * and close animations are handled via CSS transitions tied to the `open` property.
+ *
+ * @fires close - Fired when the side sheet is completely closed (after animations
+ *                finish), either via the close button, scrim click, drag-to-close,
+ *                or `Escape` key.
+ *
+ * @example
+ * ```html
+ * <!-- Modal side sheet on the right -->
+ * <moni-side-sheet id="details-sheet" modal title="Item Details">
+ *   <p>Here is more information about the selected item.</p>
+ *   <div slot="footer">
+ *     <moni-button>Save</moni-button>
+ *   </div>
+ * </moni-side-sheet>
  *
- * Attributes:
- *  - open:            boolean (reflect: true)
- *  - modal:           boolean (reflect: true)
- *  - side:            'right' | 'left' (default: 'right')
- *  - title:           Header text (default: '')
- *  - detached:        boolean (adds 16px/16dp margins/rounded corners all around)
- *  - showClose:       boolean (shows standard close button)
- *  - showBack:        boolean (shows standard back button)
- *  - noBorder:        boolean (removes borders, default: false)
- *  - withHandle:      boolean (shows grab handle and enables dragging to close/resize, default: false)
- *  - expanded-width:  string (width when expanded, default: '600px')
- *  - max-width:       string (maximum width restriction, default: '100%')
+ * <!-- Resizable, detached side sheet on the left -->
+ * <moni-side-sheet side="left" detached with-handle max-width="50vw">
+ *   <p>Navigation options</p>
+ * </moni-side-sheet>
+ * ```
  *
- * Events:
- *  - close:       Fired when the sheet is closed/dismissed
+ * @slot default - Main body content.
+ * @slot header  - Custom header content (overrides `title`, close/back buttons remain).
+ * @slot footer  - Bottom-anchored action area.
  */
 @customElement('moni-side-sheet')
 export class MoniSideSheet extends MoniElement {

package/src/components/moni-slider.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-slider.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css, nothing } from 'lit';
 import { customElement, property, state } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
@@ -5,33 +12,58 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 
 /**
- * Slider that faithfully ports BeerCSS's `.slider` styles.
+ * Material Design 3 Slider component.
+ *
+ * Sliders allow users to select a single value or a range of values from a
+ * continuous or discrete scale.
+ *
+ * **M3 spec reference:** `m3-docs/components/sliders/specs.md`
+ *
+ * **Slider modes:**
+ * - **Continuous** (default) — Smooth drag between `min` and `max`. Use when
+ *   the exact value does not need to be defined by the user (e.g. volume).
+ * - **Discrete** — Set `step` to snap to discrete intervals. Tick marks
+ *   appear via the native `<datalist>` element in Chrome/Edge. Firefox does
+ *   not render datalist ticks for range inputs.
+ * - **Range** (`range` attribute) — Two thumbs that define a minimum and
+ *   maximum value within the slider's extent.
+ * - **Vertical** (`vertical` attribute) — 90° rotated slider.
+ *
+ * **Value label tooltip:**
+ * When `indicator` is set, the current value is displayed in a tooltip above
+ * (or below, via `indicator-placement`) the active thumb during focus/drag.
+ *
+ * **Tick marks:**
+ * - `ticks` attribute: adds datalist with marks at `min` and `max` only.
+ * - `tick-interval` attribute: generates datalist options at every N units
+ *   between `min` and `max`, creating visible tick marks at those positions.
+ *
+ * **Internal state management:**
+ * Uses `@state()` for `_value` and `_valueHigh` so the fill track width and
+ * tooltip position update reactively on every drag `input` event without
+ * waiting for the `change` event.
+ *
+ * @fires change - Bubbles and is composed. Fired when dragging ends and the
+ *                 value is committed. Read `element.value` for the new value.
+ * @fires input  - Fired on every drag step. Read `element.value` for the
+ *                 live value during drag.
+ *
+ * @example
+ * ```html
+ * <!-- Continuous slider -->
+ * <moni-slider name="volume" min="0" max="100" value="60"></moni-slider>
  *
- * Fixes:
- *  - Uses @state() for internal reactive values so CSS vars update on every input
- *  - Track visual (span) and tooltip positions update immediately on drag
+ * <!-- Discrete slider with ticks every 10 units -->
+ * <moni-slider step="10" tick-interval="10" indicator></moni-slider>
  *
- * M3 spec (`m3-docs/components/sliders/specs.md`):
- *  - Continuous slider: smooth drag between min/max.
- *  - Discrete slider: snap to `step` intervals; tick marks visible.
- *  - Tick marks: in Chrome/Edge, native `<datalist>` ticks render at every
- *    option value. In Firefox, the datalist ticks are not rendered for
- *    range inputs; consumers can use `tick-interval` to manually generate
- *    a visual fallback if needed (P3.4 — outside the scope of this release).
- *  - State layer: hover/focus state uses CSS `::before` overlay at 0.08/0.12
- *    opacity per M3 (handled by `interaction-styles.ts`).
+ * <!-- Range slider -->
+ * <moni-slider range min="0" max="100" value="20" value-high="80"></moni-slider>
+ * ```
  *
- * Attributes:
- *  - name, min, max, step, value, disabled
- *  - size:       tiny | small | medium (default) | large | extra
- *  - vertical:   present → rotated
- *  - range:      present → two thumbs
- *  - ticks:      present → datalist with min/max marks
- *  - tick-interval: number — when set, generates datalist options every
- *                    N units between min and max. Overrides `ticks`.
- *  - indicator:  present → show value tooltip on focus
- *  - indicator-placement: top (default) | bottom
- *  - inset-icon: Material Symbols name inside the colored track
+ * @csspart slider    - The outer slider container.
+ * @csspart track     - The track background.
+ * @csspart fill      - The filled portion of the track.
+ * @csspart indicator - The value label tooltip.
  */
 @customElement('moni-slider')
 export class MoniSlider extends MoniElement {

package/src/components/moni-snackbar.ts

@@ -1,37 +1,111 @@
+/**
+ * @file components/moni-snackbar.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 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).
  *
- * BeerCSS uses `.snackbar` with `position: fixed; inset: auto auto 6rem 50%;`
- * and `.snackbar.active` / `.snackbar:popover-open` to show it.
+ * **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.
  *
- * 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).
+ * **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.
  *
- * 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).
+ * @example
+ * ```ts
+ * const snackbar = document.querySelector('moni-snackbar') as MoniSnackbar;
  *
- * 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
+ * // Show for 3 seconds
+ * snackbar.text = 'Item deleted';
+ * snackbar.action = 'Undo';
+ * snackbar.active = true;
+ * setTimeout(() => { snackbar.active = false; }, 3000);
+ * ```
+ *
+ * @slot default - Additional content placed inside the snackbar container.
+ *
+ * @csspart snackbar - The inner snackbar container element.
+ * @csspart text     - The message text element.
+ * @csspart action   - The action button element.
  */
 @customElement('moni-snackbar')
 export 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 ''
+	 */
 	@property({ reflect: true }) 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 ''
+	 */
 	@property({ reflect: true }) 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'
+	 */
 	@property({ reflect: true })
 	placement: 'bottom' | 'top' = '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
+	 */
 	@property({ type: Boolean, reflect: true }) 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
+	 */
 	@property({ type: Number, reflect: true, attribute: 'max-lines' })
 	maxLines = 2;
 

package/src/components/moni-split-button.ts

@@ -1,18 +1,48 @@
+/**
+ * @file components/moni-split-button.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 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.
  */
 @customElement('moni-split-button')
 export class MoniSplitButton extends MoniElement {

package/src/components/moni-step.ts

@@ -1,18 +1,52 @@
+/**
+ * @file components/moni-step.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 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.
  */
 @customElement('moni-step')
 export class MoniStep extends MoniElement {

package/src/components/moni-stepper.ts

@@ -1,15 +1,53 @@
+/**
+ * @file components/moni-stepper.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 import { customElement, property, queryAssignedElements } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import type { MoniStep } from './moni-step.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.
  */
 @customElement('moni-stepper')
 export class MoniStepper extends MoniElement {