@moni-labs/moni-ui 0.2.0 → 0.3.0

package/dist/components/moni-radio.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-radio.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);
@@ -11,33 +17,105 @@ import { ifDefined } from 'lit/directives/if-defined.js';
 import { live } from 'lit/directives/live.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Radio that faithfully ports BeerCSS's `.radio` styles.
+ * Material Design 3 Radio Button component.
+ *
+ * Radio buttons allow users to select exactly one item from a set of mutually
+ * exclusive options. They share the same visual architecture as
+ * `<moni-checkbox>` but use `type="radio"` and implement group deselection.
+ *
+ * **M3 spec reference:** `m3-docs/components/radio/specs.md`
+ *
+ * **Visual architecture (BeerCSS pattern):**
+ * Identical to the checkbox pattern: the native `<input type="radio">` occupies
+ * real layout space at `--_size` × `--_size` but is hidden via `opacity: 0`.
+ * A sibling `<span>` renders:
+ * - `::before` — the radio icon (`radio_button_unchecked` / `radio_button_checked`).
+ * - `::after`  — the hover/focus ripple ring.
+ *
+ * **Group deselection:**
+ * When a radio is checked, `_onChange` queries the component's `getRootNode()`
+ * for all `moni-radio` elements sharing the same `name` attribute and sets
+ * their `checked` property to `false`. This mirrors native browser behavior
+ * for radio groups across shadow DOM boundaries where `name` grouping does
+ * not work natively.
+ *
+ * @fires change - Bubbles and is composed. Fired when this radio is selected.
+ *                 Read `element.checked` for the new state.
  *
- * BeerCSS architecture:
- *  - `.radio` is inline-flex, aligns items center
- *  - `input` has width/height = --_size, opacity: 0  (real layout space, not absolute)
- *  - `span::before` shows "radio_button_unchecked" / "radio_button_checked" via Material Symbols font
- *  - `span::after` is the ripple hover effect
+ * @example
+ * ```html
+ * <moni-radio name="color" value="red"   label="Red"></moni-radio>
+ * <moni-radio name="color" value="green" label="Green"></moni-radio>
+ * <moni-radio name="color" value="blue"  label="Blue" checked></moni-radio>
+ * ```
  *
- * Attributes:
- *  - label:    text label
- *  - checked:  present
- *  - disabled: present
- *  - size:     small | medium (default) | large | extra
- *  - name:     forwarded to input.name (group radios by name)
- *  - value:    forwarded to input.value
+ * @csspart radio - The outer `<label>` element.
  */
 let MoniRadio = class MoniRadio extends MoniElement {
     constructor() {
         super(...arguments);
+        /**
+         * Text label displayed to the right of the radio icon.
+         *
+         * When non-empty, renders as a text node. When empty, the default slot
+         * is rendered, allowing slotted HTML content as the label.
+         *
+         * @default ''
+         */
         this.label = '';
+        /**
+         * Whether this radio button is currently selected.
+         *
+         * Reflected as an attribute so CSS selectors can target it. Synced to
+         * the native input via `updated()`.
+         *
+         * @default false
+         */
         this.checked = false;
+        /**
+         * When `true`, the radio is non-interactive and renders at 50% opacity.
+         *
+         * @default false
+         */
         this.disabled = false;
+        /**
+         * Visual size of the radio icon and its invisible hit area.
+         *
+         * | Value      | `--_size` |
+         * |------------|-----------|
+         * | `'small'`  | 1rem      |
+         * | `'medium'` | 1.5rem    |
+         * | `'large'`  | 2rem      |
+         * | `'extra'`  | 2.5rem    |
+         *
+         * @default 'medium'
+         */
         this.size = 'medium';
+        /**
+         * Radio group name. Radios with the same `name` in the same root node
+         * are treated as a mutual-exclusion group by `_onChange`.
+         *
+         * Note: Native `<input type="radio">` groups only work within the same
+         * document root. Since `moni-radio` uses shadow DOM, the deselection
+         * of siblings is handled imperatively in `_onChange`.
+         *
+         * @default ''
+         */
         this.name = '';
+        /**
+         * Forwarded to the native `<input value>` attribute.
+         * The value submitted in a form when this radio is selected.
+         *
+         * @default ''
+         */
         this.value = '';
     }
     static { MoniRadio_1 = this; }
+    /**
+     * Syncs `checked` and `disabled` to the native input after each render cycle.
+     *
+     * @param changed - Map of changed property names to their previous values.
+     */
     updated(changed) {
         if (this._input) {
             if (changed.has('checked'))
@@ -157,6 +235,19 @@ let MoniRadio = class MoniRadio extends MoniElement {
 			}
 		`
     ]; }
+    /**
+     * Handles the native input `change` event.
+     *
+     * On selection, deselects all sibling `moni-radio` elements with the same
+     * `name` in the same root node (document or shadow root). This is necessary
+     * because native radio group exclusion only works within the same document
+     * root and does not cross shadow DOM boundaries.
+     *
+     * After deselection, dispatches a composed `'change'` event so it is
+     * audible to parent elements in the light DOM.
+     *
+     * @param e - The native `change` event from the hidden `<input>`.
+     */
     _onChange(e) {
         this.checked = e.target.checked;
         if (this.checked && this.name) {

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

@@ -1,30 +1,141 @@
+/**
+ * @file components/moni-ripple.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Visual-only ripple decoration.
+ * Visual-only ripple decoration component.
+ *
+ * Provides a pointer-origin ripple animation — the expanding circle starts
+ * at the exact pointer-down coordinates rather than the element's center.
+ * This is the full-fidelity M3 ripple; for a simpler CSS-only center-ripple,
+ * use the `interactionStyles` `.interactive::after` pseudo-element instead.
+ *
+ * **Usage:**
+ * Drop `<moni-ripple>` as a **child** of any interactive element. The component
+ * automatically attaches a `pointerdown` listener to its `parentElement` and
+ * calculates the ripple origin in percentage coordinates relative to the parent.
+ *
+ * The parent element must NOT have `position: static` (the ripple applies
+ * `position: relative` automatically in `connectedCallback`).
+ *
+ * **Timing model:**
+ * On `pointerdown`:
+ * 1. `active = false` is set (cancels any in-progress ripple).
+ * 2. A `requestAnimationFrame` tick ensures the browser has processed the reset.
+ * 3. `active = true` triggers the CSS scale animation.
+ * 4. A `setTimeout` of `duration` ms (based on `speed`) resets `active = false`.
+ *
+ * The duration matches the CSS transition duration so the opacity fade-out
+ * completes before `active` is cleared.
+ *
+ * **Cleanup:**
+ * `disconnectedCallback` removes the `pointerdown` listener and clears any
+ * pending timeout. Always call `super.disconnectedCallback()` if subclassing.
  *
- * To trigger a ripple at a specific point, set the `x` and `y` attributes
- * and toggle the `active` attribute. The visual scale-in animation will
- * run for `duration` ms and then the element becomes hidden.
+ * @example
+ * ```html
+ * <!-- Ripple on a custom element -->
+ * <div class="my-button" style="position: relative; overflow: hidden;">
+ *   Click me
+ *   <moni-ripple color="primary"></moni-ripple>
+ * </div>
+ * ```
  *
- * Attributes:
- *  - x, y:        origin in px (0..100, %)
- *  - active:      present → visible
- *  - speed:       fast | normal (default) | slow
- *  - color:       primary (default) | secondary | surface
+ * @csspart ripple - The inner `<span>` that performs the scale animation.
  */
 export declare class MoniRipple extends MoniElement {
+    /**
+     * Horizontal origin of the ripple as a percentage of the parent's width.
+     *
+     * Set automatically by `_onPointerDown` based on the pointer coordinates.
+     * Can be set manually to trigger a ripple at a specific location.
+     *
+     * @default 50
+     */
     x: number;
+    /**
+     * Vertical origin of the ripple as a percentage of the parent's height.
+     *
+     * Set automatically by `_onPointerDown` based on the pointer coordinates.
+     *
+     * @default 50
+     */
     y: number;
+    /**
+     * When `true`, the ripple is visible and animating.
+     *
+     * Toggled automatically by `_onPointerDown`. Can be set manually for
+     * programmatically-triggered ripple effects.
+     *
+     * @default false
+     */
     active: boolean;
+    /**
+     * Animation speed of the ripple expand-and-fade sequence.
+     *
+     * Maps to the `--_dur` CSS custom property:
+     * - `'fast'`   — 300ms
+     * - `'normal'` — 600ms (default)
+     * - `'slow'`   — 1200ms
+     *
+     * @default 'normal'
+     */
     speed: 'fast' | 'normal' | 'slow';
+    /**
+     * Color token for the ripple overlay.
+     *
+     * Sets the `color` CSS property on `:host`, which the `.ripple` span
+     * inherits via `background-color: currentColor`.
+     *
+     * - `'primary'`   — `--primary` (default)
+     * - `'secondary'` — `--secondary`
+     * - `'surface'`   — `--surface-variant` (subtle, for surface containers)
+     *
+     * @default 'primary'
+     */
     color: 'primary' | 'secondary' | 'surface';
+    /**
+     * Reference to the parent element that the ripple is anchored to.
+     * Populated in `connectedCallback`, cleared in `disconnectedCallback`.
+     */
     private _target;
+    /**
+     * ID of the pending `setTimeout` that clears `active` after the animation.
+     * Stored so it can be cancelled if a second pointer event fires before the
+     * first ripple finishes (rapid double-tap prevention).
+     */
     private _timeoutId;
+    /**
+     * Attaches the ripple to its parent element.
+     *
+     * - Stores a reference to `parentElement` for pointer event listening.
+     * - Ensures the parent has `position: relative` so the ripple's `position: absolute`
+     *   stays within bounds.
+     * - Registers the `_onPointerDown` event listener.
+     */
     connectedCallback(): void;
+    /**
+     * Detaches the ripple from its parent element.
+     *
+     * Removes the `pointerdown` listener and clears any pending timeout to
+     * prevent the `active` flag from being set after the element is removed.
+     */
     disconnectedCallback(): void;
+    /**
+     * Handles pointer-down events on the parent element.
+     *
+     * Computes the ripple origin as a percentage of the parent's bounding rect,
+     * cancels any in-progress ripple, then triggers a new one after one
+     * animation frame to guarantee the CSS transition fires from the new position.
+     *
+     * @param e - The `PointerEvent` from the parent's `pointerdown` listener.
+     */
     private _onPointerDown;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-ripple.d.ts","sourceRoot":"","sources":["../../src/components/moni-ripple.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,qBACa,UAAW,SAAQ,WAAW;IACC,CAAC,SAAM;IACP,CAAC,SAAM;IACN,MAAM,UAAS;IAE3D,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAY;IAE7C,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAa;IAEvD,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,UAAU,CAAa;IAEtB,iBAAiB;IAYjB,oBAAoB;IAU7B,OAAO,CAAC,cAAc,CAqBpB;IAEF,OAAgB,MAAM,4BAqDpB;IAEO,MAAM;CAOf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,aAAa,EAAE,UAAU,CAAC;KAC1B;CACD;AAED,eAAe,UAAU,CAAC"}
+{"version":3,"file":"moni-ripple.d.ts","sourceRoot":"","sources":["../../src/components/moni-ripple.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBACa,UAAW,SAAQ,WAAW;IAC1C;;;;;;;OAOG;IACwC,CAAC,SAAM;IAElD;;;;;;OAMG;IACwC,CAAC,SAAM;IAElD;;;;;;;OAOG;IACyC,MAAM,UAAS;IAE3D;;;;;;;;;OASG;IAEH,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAY;IAE7C;;;;;;;;;;;OAWG;IAEH,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAa;IAEvD;;;OAGG;IACH,OAAO,CAAC,OAAO,CAA4B;IAE3C;;;;OAIG;IACH,OAAO,CAAC,UAAU,CAAa;IAE/B;;;;;;;OAOG;IACM,iBAAiB;IAY1B;;;;;OAKG;IACM,oBAAoB;IAU7B;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc,CAqBpB;IAEF,OAAgB,MAAM,4BAqDpB;IAEO,MAAM;CAOf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,aAAa,EAAE,UAAU,CAAC;KAC1B;CACD;AAED,eAAe,UAAU,CAAC"}

package/dist/components/moni-ripple.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-ripple.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,28 +14,119 @@ import { html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Visual-only ripple decoration.
+ * Visual-only ripple decoration component.
+ *
+ * Provides a pointer-origin ripple animation — the expanding circle starts
+ * at the exact pointer-down coordinates rather than the element's center.
+ * This is the full-fidelity M3 ripple; for a simpler CSS-only center-ripple,
+ * use the `interactionStyles` `.interactive::after` pseudo-element instead.
+ *
+ * **Usage:**
+ * Drop `<moni-ripple>` as a **child** of any interactive element. The component
+ * automatically attaches a `pointerdown` listener to its `parentElement` and
+ * calculates the ripple origin in percentage coordinates relative to the parent.
+ *
+ * The parent element must NOT have `position: static` (the ripple applies
+ * `position: relative` automatically in `connectedCallback`).
+ *
+ * **Timing model:**
+ * On `pointerdown`:
+ * 1. `active = false` is set (cancels any in-progress ripple).
+ * 2. A `requestAnimationFrame` tick ensures the browser has processed the reset.
+ * 3. `active = true` triggers the CSS scale animation.
+ * 4. A `setTimeout` of `duration` ms (based on `speed`) resets `active = false`.
+ *
+ * The duration matches the CSS transition duration so the opacity fade-out
+ * completes before `active` is cleared.
+ *
+ * **Cleanup:**
+ * `disconnectedCallback` removes the `pointerdown` listener and clears any
+ * pending timeout. Always call `super.disconnectedCallback()` if subclassing.
  *
- * To trigger a ripple at a specific point, set the `x` and `y` attributes
- * and toggle the `active` attribute. The visual scale-in animation will
- * run for `duration` ms and then the element becomes hidden.
+ * @example
+ * ```html
+ * <!-- Ripple on a custom element -->
+ * <div class="my-button" style="position: relative; overflow: hidden;">
+ *   Click me
+ *   <moni-ripple color="primary"></moni-ripple>
+ * </div>
+ * ```
  *
- * Attributes:
- *  - x, y:        origin in px (0..100, %)
- *  - active:      present → visible
- *  - speed:       fast | normal (default) | slow
- *  - color:       primary (default) | secondary | surface
+ * @csspart ripple - The inner `<span>` that performs the scale animation.
  */
 let MoniRipple = class MoniRipple extends MoniElement {
     constructor() {
         super(...arguments);
+        /**
+         * Horizontal origin of the ripple as a percentage of the parent's width.
+         *
+         * Set automatically by `_onPointerDown` based on the pointer coordinates.
+         * Can be set manually to trigger a ripple at a specific location.
+         *
+         * @default 50
+         */
         this.x = 50;
+        /**
+         * Vertical origin of the ripple as a percentage of the parent's height.
+         *
+         * Set automatically by `_onPointerDown` based on the pointer coordinates.
+         *
+         * @default 50
+         */
         this.y = 50;
+        /**
+         * When `true`, the ripple is visible and animating.
+         *
+         * Toggled automatically by `_onPointerDown`. Can be set manually for
+         * programmatically-triggered ripple effects.
+         *
+         * @default false
+         */
         this.active = false;
+        /**
+         * Animation speed of the ripple expand-and-fade sequence.
+         *
+         * Maps to the `--_dur` CSS custom property:
+         * - `'fast'`   — 300ms
+         * - `'normal'` — 600ms (default)
+         * - `'slow'`   — 1200ms
+         *
+         * @default 'normal'
+         */
         this.speed = 'normal';
+        /**
+         * Color token for the ripple overlay.
+         *
+         * Sets the `color` CSS property on `:host`, which the `.ripple` span
+         * inherits via `background-color: currentColor`.
+         *
+         * - `'primary'`   — `--primary` (default)
+         * - `'secondary'` — `--secondary`
+         * - `'surface'`   — `--surface-variant` (subtle, for surface containers)
+         *
+         * @default 'primary'
+         */
         this.color = 'primary';
+        /**
+         * Reference to the parent element that the ripple is anchored to.
+         * Populated in `connectedCallback`, cleared in `disconnectedCallback`.
+         */
         this._target = null;
+        /**
+         * ID of the pending `setTimeout` that clears `active` after the animation.
+         * Stored so it can be cancelled if a second pointer event fires before the
+         * first ripple finishes (rapid double-tap prevention).
+         */
         this._timeoutId = null;
+        /**
+         * Handles pointer-down events on the parent element.
+         *
+         * Computes the ripple origin as a percentage of the parent's bounding rect,
+         * cancels any in-progress ripple, then triggers a new one after one
+         * animation frame to guarantee the CSS transition fires from the new position.
+         *
+         * @param e - The `PointerEvent` from the parent's `pointerdown` listener.
+         */
         this._onPointerDown = (e) => {
             if (!this._target)
                 return;
@@ -52,6 +149,14 @@ let MoniRipple = class MoniRipple extends MoniElement {
             });
         };
     }
+    /**
+     * Attaches the ripple to its parent element.
+     *
+     * - Stores a reference to `parentElement` for pointer event listening.
+     * - Ensures the parent has `position: relative` so the ripple's `position: absolute`
+     *   stays within bounds.
+     * - Registers the `_onPointerDown` event listener.
+     */
     connectedCallback() {
         super.connectedCallback();
         this._target = this.parentElement;
@@ -63,6 +168,12 @@ let MoniRipple = class MoniRipple extends MoniElement {
             this._target.addEventListener('pointerdown', this._onPointerDown);
         }
     }
+    /**
+     * Detaches the ripple from its parent element.
+     *
+     * Removes the `pointerdown` listener and clears any pending timeout to
+     * prevent the `active` flag from being set after the element is removed.
+     */
     disconnectedCallback() {
         if (this._target) {
             this._target.removeEventListener('pointerdown', this._onPointerDown);

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

@@ -1,22 +1,42 @@
+/**
+ * @file components/moni-segmented-button.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
+ * Material Design 3 Segmented Button component (Legacy).
+ *
  * A form-associated group of selectable segmented buttons.
  *
- * @deprecated since v0.3.0 — `moni-segmented-button` is **no longer
- * recommended** by Material Design 3 Expressive. Use
- * `moni-button-group[variant="connected"]` instead, which has the same
- * functionality with an updated visual design. See
- * `m3-docs/components/segmented-buttons/overview.md` § M3 Expressive update.
+ * **Deprecation Notice:** The M3 spec (`m3-docs/components/segmented-buttons/overview.md`)
+ * has updated the segmented button pattern. The bespoke segments have been
+ * replaced with standard `<moni-button>` elements grouped inside a
+ * `<moni-button-group variant="connected">`.
  *
  * This component continues to work for backward compatibility but will be
  * removed in v1.0. A deprecation warning is logged to the console when the
  * element is connected to the DOM.
  *
- * Attributes:
- *  - name:       Name of the control in forms
- *  - multi:      Whether multiple options can be selected
- *  - hide-check: Hides checkmarks on all child segments
- *  - gap:        Custom gap space (e.g. "8px" or "1rem")
+ * @deprecated Use `<moni-button-group variant="connected">` instead.
+ *
+ * @example
+ * ```html
+ * <!-- Legacy usage (not recommended) -->
+ * <moni-segmented-button name="view" multi>
+ *   <moni-button-segment value="day">Day</moni-button-segment>
+ *   <moni-button-segment value="week">Week</moni-button-segment>
+ * </moni-segmented-button>
+ *
+ * <!-- Modern M3 equivalent -->
+ * <moni-button-group variant="connected">
+ *   <moni-button>Day</moni-button>
+ *   <moni-button>Week</moni-button>
+ * </moni-button-group>
+ * ```
+ *
+ * @slot default - `<moni-button-segment>` elements.
  */
 export declare class MoniSegmentedButton extends MoniElement {
     static formAssociated: boolean;
@@ -41,7 +61,7 @@ export declare class MoniSegmentedButton extends MoniElement {
     private updateChildren;
     private updateFormValue;
     private handleClick;
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-segmented-button.d.ts","sourceRoot":"","sources":["../../src/components/moni-segmented-button.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAG7D;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBACa,mBAAoB,SAAQ,WAAW;IACnD,MAAM,CAAC,cAAc,UAAQ;IAE7B,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAS;IAG1C,IAAI,SAAM;IAGV,KAAK,UAAS;IAGd,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAG9E,SAAS,UAAS;IAGlB,GAAG,SAAM;IAGT,OAAO,CAAC,eAAe,CAAiB;IAExC,OAAO,CAAC,SAAS,CAAmB;;IAO3B,iBAAiB,IAAI,IAAI;IAelC,IAAI,IAAI,2BAEP;IAED,IAAI,IAAI,WAEP;IAED,IAAI,KAAK,IAAI,MAAM,CAKlB;IAED,OAAO,KAAK,QAAQ,GAInB;IAED,OAAgB,MAAM,4BAoBpB;cAEiB,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC;IAQpF,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,cAAc;IAoBtB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,WAAW;IAqCV,MAAM;CAWf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,uBAAuB,EAAE,mBAAmB,CAAC;KAC7C;CACD;AAED,eAAe,mBAAmB,CAAC"}
+{"version":3,"file":"moni-segmented-button.d.ts","sourceRoot":"","sources":["../../src/components/moni-segmented-button.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBACa,mBAAoB,SAAQ,WAAW;IACnD,MAAM,CAAC,cAAc,UAAQ;IAE7B,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAS;IAG1C,IAAI,SAAM;IAGV,KAAK,UAAS;IAGd,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAG9E,SAAS,UAAS;IAGlB,GAAG,SAAM;IAGT,OAAO,CAAC,eAAe,CAAiB;IAExC,OAAO,CAAC,SAAS,CAAmB;;IAO3B,iBAAiB,IAAI,IAAI;IAelC,IAAI,IAAI,2BAEP;IAED,IAAI,IAAI,WAEP;IAED,IAAI,KAAK,IAAI,MAAM,CAKlB;IAED,OAAO,KAAK,QAAQ,GAInB;IAED,OAAgB,MAAM,4BAoBpB;cAEiB,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC;IAQpF,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,cAAc;IAoBtB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,WAAW;IAqCV,MAAM;CAWf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,uBAAuB,EAAE,mBAAmB,CAAC;KAC7C;CACD;AAED,eAAe,mBAAmB,CAAC"}

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

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-segmented-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);
@@ -9,23 +15,37 @@ import { html, css } from 'lit';
 import { customElement, property, queryAssignedElements } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
+ * Material Design 3 Segmented Button component (Legacy).
+ *
  * A form-associated group of selectable segmented buttons.
  *
- * @deprecated since v0.3.0 — `moni-segmented-button` is **no longer
- * recommended** by Material Design 3 Expressive. Use
- * `moni-button-group[variant="connected"]` instead, which has the same
- * functionality with an updated visual design. See
- * `m3-docs/components/segmented-buttons/overview.md` § M3 Expressive update.
+ * **Deprecation Notice:** The M3 spec (`m3-docs/components/segmented-buttons/overview.md`)
+ * has updated the segmented button pattern. The bespoke segments have been
+ * replaced with standard `<moni-button>` elements grouped inside a
+ * `<moni-button-group variant="connected">`.
  *
  * This component continues to work for backward compatibility but will be
  * removed in v1.0. A deprecation warning is logged to the console when the
  * element is connected to the DOM.
  *
- * Attributes:
- *  - name:       Name of the control in forms
- *  - multi:      Whether multiple options can be selected
- *  - hide-check: Hides checkmarks on all child segments
- *  - gap:        Custom gap space (e.g. "8px" or "1rem")
+ * @deprecated Use `<moni-button-group variant="connected">` instead.
+ *
+ * @example
+ * ```html
+ * <!-- Legacy usage (not recommended) -->
+ * <moni-segmented-button name="view" multi>
+ *   <moni-button-segment value="day">Day</moni-button-segment>
+ *   <moni-button-segment value="week">Week</moni-button-segment>
+ * </moni-segmented-button>
+ *
+ * <!-- Modern M3 equivalent -->
+ * <moni-button-group variant="connected">
+ *   <moni-button>Day</moni-button>
+ *   <moni-button>Week</moni-button>
+ * </moni-button-group>
+ * ```
+ *
+ * @slot default - `<moni-button-segment>` elements.
  */
 let MoniSegmentedButton = class MoniSegmentedButton extends MoniElement {
     static { MoniSegmentedButton_1 = this; }

package/dist/components/moni-select-option.d.ts

@@ -1,13 +1,47 @@
+/**
+ * @file components/moni-select-option.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Option item for custom moni-select dropdown.
- *
- * 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
+ * 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`.
+ *
+ * @csspart item - The outer `<li>` element.
  */
 export declare class MoniSelectOption extends MoniElement {
     value: string;
@@ -16,7 +50,7 @@ export declare class MoniSelectOption extends MoniElement {
     selected: boolean;
     disabled: boolean;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/components/moni-select-option.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-select-option.d.ts","sourceRoot":"","sources":["../../src/components/moni-select-option.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;GASG;AACH,qBACa,gBAAiB,SAAQ,WAAW;IACnB,KAAK,SAAM;IACX,KAAK,SAAM;IACX,KAAK,SAAM;IACI,QAAQ,UAAS;IACjB,QAAQ,UAAS;IAE7D,OAAgB,MAAM,4BA4CpB;IAEO,MAAM;CAQf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,oBAAoB,EAAE,gBAAgB,CAAC;KACvC;CACD;AAED,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"moni-select-option.d.ts","sourceRoot":"","sources":["../../src/components/moni-select-option.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBACa,gBAAiB,SAAQ,WAAW;IACnB,KAAK,SAAM;IACX,KAAK,SAAM;IACX,KAAK,SAAM;IACI,QAAQ,UAAS;IACjB,QAAQ,UAAS;IAE7D,OAAgB,MAAM,4BA4CpB;IAEO,MAAM;CAQf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,oBAAoB,EAAE,gBAAgB,CAAC;KACvC;CACD;AAED,eAAe,gBAAgB,CAAC"}