@moni-labs/moni-ui 0.2.0 → 0.3.0

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

@@ -1,26 +1,61 @@
+/**
+ * @file components/moni-nav.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Visual-only navigation. Renders a `<nav>` styled with BeerCSS helpers.
- *
- * M3 navigation patterns (`m3-docs/components/navigation-*`):
- *  - Navigation bar: placement="bottom"
- *  - Navigation rail: placement="left|right" variant="rail"
- *  - Navigation drawer: placement="left|right" variant="drawer"
- *    * Standard drawer: always visible, no scrim (default)
- *    * Modal drawer: `modal` toggles open/closed, renders a scrim and
- *      traps focus while open. See `m3-docs/components/navigation-drawer/specs.md`.
- *
- * Attributes:
- *  - placement: top (default) | bottom | left | right
- *  - variant:   rail | drawer
- *  - modal:     present → drawer is modal (requires variant="drawer")
- *  - open:      present → modal drawer is open (default true)
- *  - layout:    vertical | horizontal | auto (default)
- *
- * Slots:
- *  - default: <moni-nav-item> children
- *  - header:  content above nav items (drawer only)
- *  - footer:  content below nav items (drawer only)
+ * Material Design 3 Navigation container component.
+ *
+ * `<moni-nav>` is the container that wraps `<moni-nav-item>` elements and
+ * controls the M3 navigation pattern: navigation bar, navigation rail, or
+ * navigation drawer.
+ *
+ * **M3 spec references:**
+ * - Navigation bar: `m3-docs/components/navigation-bar/specs.md`
+ * - Navigation rail: `m3-docs/components/navigation-rail/specs.md`
+ * - Navigation drawer: `m3-docs/components/navigation-drawer/specs.md`
+ *
+ * **Navigation patterns:**
+ * - **Navigation bar** (`placement="bottom"`) — Horizontal bar of icon+label
+ *   items at the bottom of the screen. Best for 3–5 top-level destinations.
+ * - **Navigation rail** (`variant="rail"`) — Vertical rail of icon+label items
+ *   on the side of the screen. Best for medium/expanded breakpoints.
+ * - **Standard drawer** (`variant="drawer"`) — Always-visible vertical panel
+ *   with full text labels. No scrim. Best for large screens.
+ * - **Modal drawer** (`variant="drawer" modal`) — Overlay drawer with scrim.
+ *   Opened/closed via the `open` property. Traps keyboard focus while open.
+ *   Closes on `Escape` key press.
+ *
+ * **Keyboard handling:**
+ * When `modal=true`, the component adds a global `keydown` listener in
+ * `connectedCallback` that closes the drawer on `Escape`. The listener is
+ * removed in `disconnectedCallback`.
+ *
+ * @example
+ * ```html
+ * <!-- Bottom navigation bar -->
+ * <moni-nav placement="bottom">
+ *   <moni-nav-item icon="home" label="Home" active></moni-nav-item>
+ *   <moni-nav-item icon="search" label="Search"></moni-nav-item>
+ *   <moni-nav-item icon="person" label="Profile"></moni-nav-item>
+ * </moni-nav>
+ *
+ * <!-- Modal navigation drawer -->
+ * <moni-nav variant="drawer" modal open placement="left">
+ *   <h3 slot="header">My App</h3>
+ *   <moni-nav-item icon="home" label="Home" active></moni-nav-item>
+ *   <moni-nav-item icon="settings" label="Settings"></moni-nav-item>
+ * </moni-nav>
+ * ```
+ *
+ * @slot default - `<moni-nav-item>` children.
+ * @slot header  - Content above the nav items (drawer variant only).
+ * @slot footer  - Content below the nav items (drawer variant only).
+ *
+ * @csspart nav     - The inner `<nav>` element.
+ * @csspart scrim   - The backdrop scrim (modal drawer only).
  */
 export declare class MoniNav extends MoniElement {
     placement: 'top' | 'bottom' | 'left' | 'right';
@@ -35,7 +70,7 @@ export declare class MoniNav extends MoniElement {
     updated(changed: Map<string, unknown>): void;
     private _propagateToItems;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-nav.d.ts","sourceRoot":"","sources":["../../src/components/moni-nav.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBACa,OAAQ,SAAQ,WAAW;IAEvC,SAAS,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAS;IAEvD,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAU;IACQ,KAAK,UAAS;IACd,IAAI,UAAQ;IAExD,MAAM,EAAE,UAAU,GAAG,YAAY,GAAG,MAAM,CAAU;IAE3C,iBAAiB;IAMjB,oBAAoB;IAK7B,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,WAAW;IAMV,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAY9C,OAAO,CAAC,iBAAiB,CAOvB;IAEF,OAAgB,MAAM,4BAoJpB;IAEO,MAAM;CAyBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,UAAU,EAAE,OAAO,CAAC;KACpB;CACD;AAED,eAAe,OAAO,CAAC"}
+{"version":3,"file":"moni-nav.d.ts","sourceRoot":"","sources":["../../src/components/moni-nav.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBACa,OAAQ,SAAQ,WAAW;IAEvC,SAAS,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAS;IAEvD,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAU;IACQ,KAAK,UAAS;IACd,IAAI,UAAQ;IAExD,MAAM,EAAE,UAAU,GAAG,YAAY,GAAG,MAAM,CAAU;IAE3C,iBAAiB;IAMjB,oBAAoB;IAK7B,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,WAAW;IAMV,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAY9C,OAAO,CAAC,iBAAiB,CAOvB;IAEF,OAAgB,MAAM,4BAoJpB;IAEO,MAAM;CAyBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,UAAU,EAAE,OAAO,CAAC;KACpB;CACD;AAED,eAAe,OAAO,CAAC"}

package/dist/components/moni-nav.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-nav.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,27 +14,56 @@ import { html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Visual-only navigation. Renders a `<nav>` styled with BeerCSS helpers.
+ * Material Design 3 Navigation container component.
+ *
+ * `<moni-nav>` is the container that wraps `<moni-nav-item>` elements and
+ * controls the M3 navigation pattern: navigation bar, navigation rail, or
+ * navigation drawer.
+ *
+ * **M3 spec references:**
+ * - Navigation bar: `m3-docs/components/navigation-bar/specs.md`
+ * - Navigation rail: `m3-docs/components/navigation-rail/specs.md`
+ * - Navigation drawer: `m3-docs/components/navigation-drawer/specs.md`
+ *
+ * **Navigation patterns:**
+ * - **Navigation bar** (`placement="bottom"`) — Horizontal bar of icon+label
+ *   items at the bottom of the screen. Best for 3–5 top-level destinations.
+ * - **Navigation rail** (`variant="rail"`) — Vertical rail of icon+label items
+ *   on the side of the screen. Best for medium/expanded breakpoints.
+ * - **Standard drawer** (`variant="drawer"`) — Always-visible vertical panel
+ *   with full text labels. No scrim. Best for large screens.
+ * - **Modal drawer** (`variant="drawer" modal`) — Overlay drawer with scrim.
+ *   Opened/closed via the `open` property. Traps keyboard focus while open.
+ *   Closes on `Escape` key press.
+ *
+ * **Keyboard handling:**
+ * When `modal=true`, the component adds a global `keydown` listener in
+ * `connectedCallback` that closes the drawer on `Escape`. The listener is
+ * removed in `disconnectedCallback`.
+ *
+ * @example
+ * ```html
+ * <!-- Bottom navigation bar -->
+ * <moni-nav placement="bottom">
+ *   <moni-nav-item icon="home" label="Home" active></moni-nav-item>
+ *   <moni-nav-item icon="search" label="Search"></moni-nav-item>
+ *   <moni-nav-item icon="person" label="Profile"></moni-nav-item>
+ * </moni-nav>
  *
- * M3 navigation patterns (`m3-docs/components/navigation-*`):
- *  - Navigation bar: placement="bottom"
- *  - Navigation rail: placement="left|right" variant="rail"
- *  - Navigation drawer: placement="left|right" variant="drawer"
- *    * Standard drawer: always visible, no scrim (default)
- *    * Modal drawer: `modal` toggles open/closed, renders a scrim and
- *      traps focus while open. See `m3-docs/components/navigation-drawer/specs.md`.
+ * <!-- Modal navigation drawer -->
+ * <moni-nav variant="drawer" modal open placement="left">
+ *   <h3 slot="header">My App</h3>
+ *   <moni-nav-item icon="home" label="Home" active></moni-nav-item>
+ *   <moni-nav-item icon="settings" label="Settings"></moni-nav-item>
+ * </moni-nav>
+ * ```
  *
- * Attributes:
- *  - placement: top (default) | bottom | left | right
- *  - variant:   rail | drawer
- *  - modal:     present → drawer is modal (requires variant="drawer")
- *  - open:      present → modal drawer is open (default true)
- *  - layout:    vertical | horizontal | auto (default)
+ * @slot default - `<moni-nav-item>` children.
+ * @slot header  - Content above the nav items (drawer variant only).
+ * @slot footer  - Content below the nav items (drawer variant only).
  *
- * Slots:
- *  - default: <moni-nav-item> children
- *  - header:  content above nav items (drawer only)
- *  - footer:  content below nav items (drawer only)
+ * @csspart nav     - The inner `<nav>` element.
+ * @csspart scrim   - The backdrop scrim (modal drawer only).
  */
 let MoniNav = class MoniNav extends MoniElement {
     constructor() {

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

@@ -1,32 +1,120 @@
+/**
+ * @file components/moni-progress.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Progress indicator that faithfully ports BeerCSS's progress styles.
- *
- * BeerCSS uses the native <progress> element with `::after`, `::before` and
- * `mask-image` pseudo-elements. Those don't work inside Shadow DOM because:
- *  - `<progress>` native pseudo-elements (::webkit-progress-value, ::after)
- *    are blocked by the UA shadow root in Chrome/Firefox within a custom shadow.
- *  - `mask-image` on those pseudo-elements doesn't apply at all in shadows.
- *
- * Solution: use a plain <div> wrapper that replicates BeerCSS's visual rules
- * exactly, and an SVG for the circular variant (matching BeerCSS's conic-gradient
- * approach but with SVG stroke for better cross-browser support).
- *
- * Attributes:
- *  - value:         0..max (omit for indeterminate)
- *  - max:           upper bound (default 100)
- *  - variant:       linear (default) | circular | wavy | circular-wavy
- *  - size:          small | medium (default) | large
- *  - indeterminate: present → infinite animation
+ * Material Design 3 Progress Indicator component.
+ *
+ * Progress indicators express an unspecified wait time or display the length
+ * of a process. They inform users about the status of ongoing processes such
+ * as loading an app, submitting a form, or saving updates.
+ *
+ * **M3 spec reference:** `m3-docs/components/progress-indicators/specs.md`
+ *
+ * **Variants:**
+ * - `linear` (default) — A horizontal bar that fills left-to-right.
+ * - `circular` — A circular SVG stroke indicator.
+ * - `wavy` — An animated wave bar (Moni extension; not in M3 spec).
+ * - `circular-wavy` — Circular + wave combo (Moni extension).
+ *
+ * **Shadow DOM compatibility note:**
+ * BeerCSS's progress uses native `<progress>` pseudo-elements (`::before`,
+ * `::after`, `::webkit-progress-value`) and `mask-image`, which are blocked
+ * by the UA shadow root in Chrome/Firefox. This component uses a plain `<div>`
+ * wrapper that replicates the visual rules exactly, and an `<svg>` element
+ * for the circular variant using SVG stroke-dashoffset animation for superior
+ * cross-browser support compared to `conic-gradient`.
+ *
+ * **Percentage computation:**
+ * `_pct` is computed in `willUpdate()` as `(value / max) * 100`, clamped to
+ * `[0, 100]`. When `indeterminate` is set, `_pct` is fixed at `50` to drive
+ * the infinite loop animation.
+ *
+ * @example
+ * ```html
+ * <!-- Determinate linear progress -->
+ * <moni-progress value="65" max="100"></moni-progress>
+ *
+ * <!-- Indeterminate circular progress (loading spinner) -->
+ * <moni-progress variant="circular" indeterminate></moni-progress>
+ * ```
+ *
+ * @csspart bar      - The outer container div.
+ * @csspart fill     - The inner fill element (linear variant).
+ * @csspart svg      - The SVG element (circular variant).
  */
 export declare class MoniProgress extends MoniElement {
+    /**
+     * Current progress value.
+     *
+     * Must be in the range `[0, max]`. Values outside this range are clamped
+     * during percentage computation in `willUpdate()`. Ignored when
+     * `indeterminate` is set.
+     *
+     * @default 0
+     */
     value: number;
+    /**
+     * Maximum value of the progress range.
+     *
+     * Defaults to `100` so `value` can be set as a percentage directly.
+     * For non-percentage ranges (e.g. steps), set `max` to the total step count
+     * and `value` to the current step.
+     *
+     * @default 100
+     */
     max: number;
+    /**
+     * Visual variant of the progress indicator.
+     *
+     * - `'linear'` (default) — Horizontal fill bar.
+     * - `'circular'` — SVG circle with stroke-dashoffset animation.
+     * - `'wavy'` — Animated wave bar.
+     * - `'circular-wavy'` — Combination of circular and wave.
+     *
+     * @default 'linear'
+     */
     variant: 'linear' | 'circular' | 'wavy' | 'circular-wavy';
+    /**
+     * Visual size of the progress indicator.
+     *
+     * - `'small'`  — Compact; suitable for inline or tight layouts.
+     * - `'medium'` — Standard M3 size (default).
+     * - `'large'`  — Prominent; for full-page loading states.
+     *
+     * @default 'medium'
+     */
     size: 'small' | 'medium' | 'large';
+    /**
+     * When `true`, the indicator animates in an infinite loop regardless of `value`.
+     *
+     * Use for operations where the completion percentage is unknown
+     * (e.g. network requests, file processing). When `indeterminate` is set,
+     * `_pct` is fixed at `50` to drive a continuous sweep animation.
+     *
+     * @default false
+     */
     indeterminate: boolean;
-    /** Computed fill percentage (0-100) used in styles/SVG */
+    /**
+     * Computed fill percentage in the range `[0, 100]`.
+     *
+     * Updated in `willUpdate()` whenever `value`, `max`, or `indeterminate` changes.
+     * Used directly in CSS custom property bindings and SVG stroke attributes.
+     *
+     * @internal
+     */
     private _pct;
+    /**
+     * Computes the fill percentage before each render.
+     *
+     * Recalculates `_pct` whenever `value`, `max`, or `indeterminate` changes.
+     * The `Math.max(1, max)` guard prevents division-by-zero when `max` is 0.
+     *
+     * @param changed - Map of property names to their previous values.
+     */
     willUpdate(changed: Map<string, unknown>): void;
     static styles: import("lit").CSSResult[];
     private _renderLinear;
@@ -34,7 +122,7 @@ export declare class MoniProgress extends MoniElement {
     private _renderCircular;
     /** Unique ID per instance for SVG clipPath IDs */
     private readonly _instanceId;
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-progress.d.ts","sourceRoot":"","sources":["../../src/components/moni-progress.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBACa,YAAa,SAAQ,WAAW;IACD,KAAK,SAAK;IACV,GAAG,SAAO;IAErD,OAAO,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,eAAe,CAAY;IAErE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IACF,aAAa,UAAS;IAElE,0DAA0D;IACjD,OAAO,CAAC,IAAI,CAAK;IAEjB,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAQjD,OAAgB,MAAM,4BA6HpB;IAEF,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,WAAW;IAyDnB,OAAO,CAAC,eAAe;IAoDvB,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0C;IAE7D,MAAM;CAYf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,YAAY,CAAC;KAC9B;CACD;AAED,eAAe,YAAY,CAAC"}
+{"version":3,"file":"moni-progress.d.ts","sourceRoot":"","sources":["../../src/components/moni-progress.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBACa,YAAa,SAAQ,WAAW;IAC5C;;;;;;;;OAQG;IACwC,KAAK,SAAK;IAErD;;;;;;;;OAQG;IACwC,GAAG,SAAO;IAErD;;;;;;;;;OASG;IAEH,OAAO,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,eAAe,CAAY;IAErE;;;;;;;;OAQG;IAEH,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE9C;;;;;;;;OAQG;IACyC,aAAa,UAAS;IAElE;;;;;;;OAOG;IACM,OAAO,CAAC,IAAI,CAAK;IAE1B;;;;;;;OAOG;IACM,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAQjD,OAAgB,MAAM,4BA6HpB;IAEF,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,WAAW;IAyDnB,OAAO,CAAC,eAAe;IAoDvB,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA0C;IAE7D,MAAM;CAYf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,YAAY,CAAC;KAC9B;CACD;AAED,eAAe,YAAY,CAAC"}

package/dist/components/moni-progress.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-progress.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,38 +14,120 @@ import { html, css, svg, nothing } from 'lit';
 import { customElement, property, state } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Progress indicator that faithfully ports BeerCSS's progress styles.
+ * Material Design 3 Progress Indicator component.
+ *
+ * Progress indicators express an unspecified wait time or display the length
+ * of a process. They inform users about the status of ongoing processes such
+ * as loading an app, submitting a form, or saving updates.
+ *
+ * **M3 spec reference:** `m3-docs/components/progress-indicators/specs.md`
+ *
+ * **Variants:**
+ * - `linear` (default) — A horizontal bar that fills left-to-right.
+ * - `circular` — A circular SVG stroke indicator.
+ * - `wavy` — An animated wave bar (Moni extension; not in M3 spec).
+ * - `circular-wavy` — Circular + wave combo (Moni extension).
+ *
+ * **Shadow DOM compatibility note:**
+ * BeerCSS's progress uses native `<progress>` pseudo-elements (`::before`,
+ * `::after`, `::webkit-progress-value`) and `mask-image`, which are blocked
+ * by the UA shadow root in Chrome/Firefox. This component uses a plain `<div>`
+ * wrapper that replicates the visual rules exactly, and an `<svg>` element
+ * for the circular variant using SVG stroke-dashoffset animation for superior
+ * cross-browser support compared to `conic-gradient`.
+ *
+ * **Percentage computation:**
+ * `_pct` is computed in `willUpdate()` as `(value / max) * 100`, clamped to
+ * `[0, 100]`. When `indeterminate` is set, `_pct` is fixed at `50` to drive
+ * the infinite loop animation.
  *
- * BeerCSS uses the native <progress> element with `::after`, `::before` and
- * `mask-image` pseudo-elements. Those don't work inside Shadow DOM because:
- *  - `<progress>` native pseudo-elements (::webkit-progress-value, ::after)
- *    are blocked by the UA shadow root in Chrome/Firefox within a custom shadow.
- *  - `mask-image` on those pseudo-elements doesn't apply at all in shadows.
+ * @example
+ * ```html
+ * <!-- Determinate linear progress -->
+ * <moni-progress value="65" max="100"></moni-progress>
  *
- * Solution: use a plain <div> wrapper that replicates BeerCSS's visual rules
- * exactly, and an SVG for the circular variant (matching BeerCSS's conic-gradient
- * approach but with SVG stroke for better cross-browser support).
+ * <!-- Indeterminate circular progress (loading spinner) -->
+ * <moni-progress variant="circular" indeterminate></moni-progress>
+ * ```
  *
- * Attributes:
- *  - value:         0..max (omit for indeterminate)
- *  - max:           upper bound (default 100)
- *  - variant:       linear (default) | circular | wavy | circular-wavy
- *  - size:          small | medium (default) | large
- *  - indeterminate: present → infinite animation
+ * @csspart bar      - The outer container div.
+ * @csspart fill     - The inner fill element (linear variant).
+ * @csspart svg      - The SVG element (circular variant).
  */
 let MoniProgress = class MoniProgress extends MoniElement {
     constructor() {
         super(...arguments);
+        /**
+         * Current progress value.
+         *
+         * Must be in the range `[0, max]`. Values outside this range are clamped
+         * during percentage computation in `willUpdate()`. Ignored when
+         * `indeterminate` is set.
+         *
+         * @default 0
+         */
         this.value = 0;
+        /**
+         * Maximum value of the progress range.
+         *
+         * Defaults to `100` so `value` can be set as a percentage directly.
+         * For non-percentage ranges (e.g. steps), set `max` to the total step count
+         * and `value` to the current step.
+         *
+         * @default 100
+         */
         this.max = 100;
+        /**
+         * Visual variant of the progress indicator.
+         *
+         * - `'linear'` (default) — Horizontal fill bar.
+         * - `'circular'` — SVG circle with stroke-dashoffset animation.
+         * - `'wavy'` — Animated wave bar.
+         * - `'circular-wavy'` — Combination of circular and wave.
+         *
+         * @default 'linear'
+         */
         this.variant = 'linear';
+        /**
+         * Visual size of the progress indicator.
+         *
+         * - `'small'`  — Compact; suitable for inline or tight layouts.
+         * - `'medium'` — Standard M3 size (default).
+         * - `'large'`  — Prominent; for full-page loading states.
+         *
+         * @default 'medium'
+         */
         this.size = 'medium';
+        /**
+         * When `true`, the indicator animates in an infinite loop regardless of `value`.
+         *
+         * Use for operations where the completion percentage is unknown
+         * (e.g. network requests, file processing). When `indeterminate` is set,
+         * `_pct` is fixed at `50` to drive a continuous sweep animation.
+         *
+         * @default false
+         */
         this.indeterminate = false;
-        /** Computed fill percentage (0-100) used in styles/SVG */
+        /**
+         * Computed fill percentage in the range `[0, 100]`.
+         *
+         * Updated in `willUpdate()` whenever `value`, `max`, or `indeterminate` changes.
+         * Used directly in CSS custom property bindings and SVG stroke attributes.
+         *
+         * @internal
+         */
         this._pct = 0;
         /** Unique ID per instance for SVG clipPath IDs */
         this._instanceId = Math.random().toString(36).slice(2, 8);
     }
+    /**
+     * Computes the fill percentage before each render.
+     *
+     * Recalculates `_pct` whenever `value`, `max`, or `indeterminate` changes.
+     * The `Math.max(1, max)` guard prevents division-by-zero when `max` is 0.
+     *
+     * @param changed - Map of property names to their previous values.
+     */
     willUpdate(changed) {
         if (changed.has('value') || changed.has('max') || changed.has('indeterminate')) {
             this._pct = this.indeterminate

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

@@ -1,33 +1,125 @@
+/**
+ * @file components/moni-radio.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } 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.
  */
 export declare class MoniRadio extends MoniElement {
+    /**
+     * 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 ''
+     */
     label: string;
+    /**
+     * 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
+     */
     checked: boolean;
+    /**
+     * When `true`, the radio is non-interactive and renders at 50% opacity.
+     *
+     * @default false
+     */
     disabled: boolean;
+    /**
+     * 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'
+     */
     size: 'small' | 'medium' | 'large' | 'extra';
+    /**
+     * 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 ''
+     */
     name: string;
+    /**
+     * Forwarded to the native `<input value>` attribute.
+     * The value submitted in a form when this radio is selected.
+     *
+     * @default ''
+     */
     value: string;
+    /** Direct reference to the native input element for programmatic access. */
     private _input;
+    /**
+     * 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: Map<string, unknown>): void;
     static styles: import("lit").CSSResult[];
+    /**
+     * 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>`.
+     */
     private _onChange;
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-radio.d.ts","sourceRoot":"","sources":["../../src/components/moni-radio.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;GAgBG;AACH,qBACa,SAAU,SAAQ,WAAW;IACZ,KAAK,SAAM;IACI,OAAO,UAAS;IAChB,QAAQ,UAAS;IAE7D,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAC3B,IAAI,SAAM;IACV,KAAK,SAAM;IAExB,OAAO,CAAC,MAAM,CAAoB;IAEzC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAO9C,OAAgB,MAAM,4BA8GpB;IAEF,OAAO,CAAC,SAAS;IAgBR,MAAM;CAiBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,YAAY,EAAE,SAAS,CAAC;KACxB;CACD;AAED,eAAe,SAAS,CAAC"}
+{"version":3,"file":"moni-radio.d.ts","sourceRoot":"","sources":["../../src/components/moni-radio.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBACa,SAAU,SAAQ,WAAW;IACzC;;;;;;;OAOG;IAC0B,KAAK,SAAM;IAExC;;;;;;;OAOG;IACyC,OAAO,UAAS;IAE5D;;;;OAIG;IACyC,QAAQ,UAAS;IAE7D;;;;;;;;;;;OAWG;IAEH,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAExD;;;;;;;;;OASG;IAC0B,IAAI,SAAM;IAEvC;;;;;OAKG;IAC0B,KAAK,SAAM;IAExC,4EAA4E;IAC5D,OAAO,CAAC,MAAM,CAAoB;IAElD;;;;OAIG;IACM,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAO9C,OAAgB,MAAM,4BA8GpB;IAEF;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS;IAgBR,MAAM;CAiBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,YAAY,EAAE,SAAS,CAAC;KACxB;CACD;AAED,eAAe,SAAS,CAAC"}