@moni-labs/moni-ui 0.2.0 → 0.3.0

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

@@ -1,31 +1,57 @@
+/**
+ * @file components/moni-button-group.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Visual-only button group. Organizes `moni-button` or `moni-icon-button`
- * components in a row.
- *
- * **`variant="connected"`** is the Material Design 3 Expressive replacement
- * for the deprecated `moni-segmented-button` (see
- * `m3-docs/components/segmented-buttons/overview.md` § M3 Expressive update).
- * In connected mode, segments share borders via propagated `shape` values
- * (`left-round-flat`, `no-round`, `right-round-flat` for a gap-less row), and
- * the group manages single/multi-select toggle state. This is the
- * **only Moni component that intentionally uses `@click` listeners** —
- * toggle behavior is essential to the M3 connected button group semantics.
- *
- * Accessibility:
- *  - The host renders `role="group"` (configurable via `role` attribute).
- *  - `aria-label` / `aria-labelledby` should be set by the consumer to
- *    identify the group to assistive technology.
- *
- * Attributes:
- *  - variant:    standard (default) | connected
- *  - size:       small | medium (default) | large | extra
- *  - multi:      boolean (default false) — multiple toggles allowed
- *  - gap:        custom gap space (e.g. "8px" or "1rem"); in `connected`
- *                variant the default is 0.125rem (2dp) per M3 spec
- *  - role:       ARIA role override (default "group")
- *  - label:      aria-label for the group
- *  - labelled-by: aria-labelledby reference
+ * Material Design 3 Button Group component.
+ *
+ * Organizes multiple `<moni-button>` or `<moni-icon-button>` components
+ * into a single row.
+ *
+ * **Variants:**
+ * - `standard` (default) — A simple flex row with a gap between buttons.
+ * - `connected` — The M3 Expressive replacement for segmented buttons. In this
+ *   mode, buttons share borders and form a single continuous pill shape. The
+ *   group manages the single/multi-select toggle state of its children.
+ *
+ * **`connected` variant details:**
+ * - **Shape propagation:** The group automatically propagates M3 shape classes
+ *   (`left-round-flat`, `no-round`, `right-round-flat`) to its children so
+ *   they interlock seamlessly.
+ * - **Toggle management:** The group listens to child clicks and toggles their
+ *   `active` attributes. When `multi=false` (default), only one button can be
+ *   active at a time (radio button behavior). When `multi=true`, multiple buttons
+ *   can be active (checkbox behavior).
+ * - **Event propagation:** Fires a `'change'` event when the selection changes.
+ *
+ * **Accessibility:**
+ * - Renders with `role="group"` (can be overridden to `toolbar` or `radiogroup`).
+ * - Consumers should provide an `aria-label` or `aria-labelledby` attribute
+ *   to identify the group's purpose to assistive technologies.
+ *
+ * @fires change - Fired when a button is clicked in `connected` mode and the
+ *                 selection state updates.
+ *
+ * @example
+ * ```html
+ * <!-- Connected single-select group -->
+ * <moni-button-group variant="connected" label="Alignment">
+ *   <moni-button icon="format_align_left" active></moni-button>
+ *   <moni-button icon="format_align_center"></moni-button>
+ *   <moni-button icon="format_align_right"></moni-button>
+ * </moni-button-group>
+ *
+ * <!-- Standard button row -->
+ * <moni-button-group gap="1rem">
+ *   <moni-button variant="text">Cancel</moni-button>
+ *   <moni-button>Save</moni-button>
+ * </moni-button-group>
+ * ```
+ *
+ * @slot default - The `<moni-button>` elements that make up the group.
  */
 export declare class MoniButtonGroup extends MoniElement {
     variant: 'standard' | 'connected';
@@ -44,7 +70,7 @@ export declare class MoniButtonGroup extends MoniElement {
     private handlePointerDown;
     private handlePointerUp;
     private handleClick;
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-button-group.d.ts","sourceRoot":"","sources":["../../src/components/moni-button-group.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBACa,eAAgB,SAAQ,WAAW;IAE/C,OAAO,EAAE,UAAU,GAAG,WAAW,CAAc;IAG/C,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAG9E,KAAK,UAAS;IAGd,GAAG,SAAM;IAGT,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,YAAY,CAAW;IAGnD,KAAK,SAAM;IAGX,UAAU,SAAM;IAGhB,OAAO,CAAC,cAAc,CAAiB;IAEvC,OAAgB,MAAM,4BAuCpB;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;IA0CtB,OAAO,CAAC,iBAAiB;IA2BzB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,WAAW;IA2CV,MAAM;CAyBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,mBAAmB,EAAE,eAAe,CAAC;KACrC;CACD;AAED,eAAe,eAAe,CAAC"}
+{"version":3,"file":"moni-button-group.d.ts","sourceRoot":"","sources":["../../src/components/moni-button-group.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBACa,eAAgB,SAAQ,WAAW;IAE/C,OAAO,EAAE,UAAU,GAAG,WAAW,CAAc;IAG/C,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAG9E,KAAK,UAAS;IAGd,GAAG,SAAM;IAGT,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,YAAY,CAAW;IAGnD,KAAK,SAAM;IAGX,UAAU,SAAM;IAGhB,OAAO,CAAC,cAAc,CAAiB;IAEvC,OAAgB,MAAM,4BAuCpB;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;IA0CtB,OAAO,CAAC,iBAAiB;IA2BzB,OAAO,CAAC,eAAe;IAUvB,OAAO,CAAC,WAAW;IA2CV,MAAM;CAyBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,mBAAmB,EAAE,eAAe,CAAC;KACrC;CACD;AAED,eAAe,eAAe,CAAC"}

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

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-button-group.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,32 +14,52 @@ import { html, css, nothing } from 'lit';
 import { customElement, property, queryAssignedElements } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Visual-only button group. Organizes `moni-button` or `moni-icon-button`
- * components in a row.
+ * Material Design 3 Button Group component.
+ *
+ * Organizes multiple `<moni-button>` or `<moni-icon-button>` components
+ * into a single row.
+ *
+ * **Variants:**
+ * - `standard` (default) — A simple flex row with a gap between buttons.
+ * - `connected` — The M3 Expressive replacement for segmented buttons. In this
+ *   mode, buttons share borders and form a single continuous pill shape. The
+ *   group manages the single/multi-select toggle state of its children.
+ *
+ * **`connected` variant details:**
+ * - **Shape propagation:** The group automatically propagates M3 shape classes
+ *   (`left-round-flat`, `no-round`, `right-round-flat`) to its children so
+ *   they interlock seamlessly.
+ * - **Toggle management:** The group listens to child clicks and toggles their
+ *   `active` attributes. When `multi=false` (default), only one button can be
+ *   active at a time (radio button behavior). When `multi=true`, multiple buttons
+ *   can be active (checkbox behavior).
+ * - **Event propagation:** Fires a `'change'` event when the selection changes.
+ *
+ * **Accessibility:**
+ * - Renders with `role="group"` (can be overridden to `toolbar` or `radiogroup`).
+ * - Consumers should provide an `aria-label` or `aria-labelledby` attribute
+ *   to identify the group's purpose to assistive technologies.
+ *
+ * @fires change - Fired when a button is clicked in `connected` mode and the
+ *                 selection state updates.
  *
- * **`variant="connected"`** is the Material Design 3 Expressive replacement
- * for the deprecated `moni-segmented-button` (see
- * `m3-docs/components/segmented-buttons/overview.md` § M3 Expressive update).
- * In connected mode, segments share borders via propagated `shape` values
- * (`left-round-flat`, `no-round`, `right-round-flat` for a gap-less row), and
- * the group manages single/multi-select toggle state. This is the
- * **only Moni component that intentionally uses `@click` listeners** —
- * toggle behavior is essential to the M3 connected button group semantics.
+ * @example
+ * ```html
+ * <!-- Connected single-select group -->
+ * <moni-button-group variant="connected" label="Alignment">
+ *   <moni-button icon="format_align_left" active></moni-button>
+ *   <moni-button icon="format_align_center"></moni-button>
+ *   <moni-button icon="format_align_right"></moni-button>
+ * </moni-button-group>
  *
- * Accessibility:
- *  - The host renders `role="group"` (configurable via `role` attribute).
- *  - `aria-label` / `aria-labelledby` should be set by the consumer to
- *    identify the group to assistive technology.
+ * <!-- Standard button row -->
+ * <moni-button-group gap="1rem">
+ *   <moni-button variant="text">Cancel</moni-button>
+ *   <moni-button>Save</moni-button>
+ * </moni-button-group>
+ * ```
  *
- * Attributes:
- *  - variant:    standard (default) | connected
- *  - size:       small | medium (default) | large | extra
- *  - multi:      boolean (default false) — multiple toggles allowed
- *  - gap:        custom gap space (e.g. "8px" or "1rem"); in `connected`
- *                variant the default is 0.125rem (2dp) per M3 spec
- *  - role:       ARIA role override (default "group")
- *  - label:      aria-label for the group
- *  - labelled-by: aria-labelledby reference
+ * @slot default - The `<moni-button>` elements that make up the group.
  */
 let MoniButtonGroup = class MoniButtonGroup extends MoniElement {
     constructor() {

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

@@ -1,14 +1,34 @@
+/**
+ * @file components/moni-button-segment.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 import './moni-icon.js';
 /**
- * A selectable segment button designed to be grouped inside a `moni-segmented-button`.
+ * Material Design 3 Segmented Button component (Legacy).
+ *
+ * **Deprecation Notice:** The M3 spec (`m3-docs/components/segmented-buttons/overview.md`)
+ * has replaced the bespoke segmented button component with standard buttons arranged
+ * in a "connected" group. Please use `<moni-button-group variant="connected">`
+ * containing standard `<moni-button>` elements instead of this component.
+ *
+ * This component remains for backwards compatibility but will be removed in a
+ * future major release. It renders a single segment within a `<moni-segmented-button>`.
+ *
+ * @deprecated Use `<moni-button-group variant="connected">` instead.
+ *
+ * @example
+ * ```html
+ * <!-- Legacy usage (not recommended) -->
+ * <moni-segmented-button>
+ *   <moni-button-segment value="day" checked>Day</moni-button-segment>
+ *   <moni-button-segment value="week">Week</moni-button-segment>
+ * </moni-segmented-button>
+ * ```
  *
- * Attributes:
- *  - value:      The value of the segment (default "on")
- *  - checked:    Whether the segment is checked/selected
- *  - disabled:   Whether the segment is disabled
- *  - position:   Automatically set by the parent (first | middle | last | solo)
- *  - hide-check: Hides the checkmark when selected
+ * @slot default - The segment label text.
  */
 export declare class MoniButtonSegment extends MoniElement {
     value: string;
@@ -18,7 +38,7 @@ export declare class MoniButtonSegment extends MoniElement {
     position: 'first' | 'middle' | 'last' | 'solo';
     hideCheck: 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-button-segment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-button-segment.d.ts","sourceRoot":"","sources":["../../src/components/moni-button-segment.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;GASG;AACH,qBACa,iBAAkB,SAAQ,WAAW;IAEjD,KAAK,SAAQ;IAGb,OAAO,UAAS;IAGhB,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAG9E,QAAQ,UAAS;IAGjB,QAAQ,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAU;IAGxD,SAAS,UAAS;IAElB,OAAgB,MAAM,4BA0OpB;IAEO,MAAM;CAWf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,qBAAqB,EAAE,iBAAiB,CAAC;KACzC;CACD;AAED,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"moni-button-segment.d.ts","sourceRoot":"","sources":["../../src/components/moni-button-segment.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBACa,iBAAkB,SAAQ,WAAW;IAEjD,KAAK,SAAQ;IAGb,OAAO,UAAS;IAGhB,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAG9E,QAAQ,UAAS;IAGjB,QAAQ,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAU;IAGxD,SAAS,UAAS;IAElB,OAAgB,MAAM,4BA0OpB;IAEO,MAAM;CAWf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,qBAAqB,EAAE,iBAAiB,CAAC;KACzC;CACD;AAED,eAAe,iBAAiB,CAAC"}

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

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-button-segment.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,14 +15,28 @@ import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 /**
- * A selectable segment button designed to be grouped inside a `moni-segmented-button`.
+ * Material Design 3 Segmented Button component (Legacy).
+ *
+ * **Deprecation Notice:** The M3 spec (`m3-docs/components/segmented-buttons/overview.md`)
+ * has replaced the bespoke segmented button component with standard buttons arranged
+ * in a "connected" group. Please use `<moni-button-group variant="connected">`
+ * containing standard `<moni-button>` elements instead of this component.
+ *
+ * This component remains for backwards compatibility but will be removed in a
+ * future major release. It renders a single segment within a `<moni-segmented-button>`.
+ *
+ * @deprecated Use `<moni-button-group variant="connected">` instead.
+ *
+ * @example
+ * ```html
+ * <!-- Legacy usage (not recommended) -->
+ * <moni-segmented-button>
+ *   <moni-button-segment value="day" checked>Day</moni-button-segment>
+ *   <moni-button-segment value="week">Week</moni-button-segment>
+ * </moni-segmented-button>
+ * ```
  *
- * Attributes:
- *  - value:      The value of the segment (default "on")
- *  - checked:    Whether the segment is checked/selected
- *  - disabled:   Whether the segment is disabled
- *  - position:   Automatically set by the parent (first | middle | last | solo)
- *  - hide-check: Hides the checkmark when selected
+ * @slot default - The segment label text.
  */
 let MoniButtonSegment = class MoniButtonSegment extends MoniElement {
     constructor() {

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

@@ -1,42 +1,61 @@
+/**
+ * @file components/moni-button.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 import './moni-icon.js';
 import './moni-progress.js';
 /**
- * Visual-only button. Renders a native `<button>` styled per Material 3 Expressive.
+ * Material Design 3 Button component.
+ *
+ * Buttons allow users to take actions and make choices with a single tap.
+ * This component provides all M3 button variants, sizes, and shape morphing
+ * capabilities (e.g. morphing to a pill shape on press or toggle).
+ *
+ * **M3 spec reference:** `m3-docs/components/buttons/specs.md`
+ *
+ * **Variants:**
+ * - `filled` (default) — High emphasis. Use for primary actions.
+ * - `tonal` — Medium emphasis. Secondary actions that still need to stand out.
+ * - `elevated` — Medium emphasis with shadow. Used when sitting on patterned backgrounds.
+ * - `outlined` — Medium emphasis, no fill. Secondary or tertiary actions.
+ * - `text` — Low emphasis. Tertiary actions (e.g. dialog cancel button).
+ *
+ * **Shape morphing (M3 Expressive feature):**
+ * - On press (active state): Round and square buttons morph to a slightly squarer
+ *   "pressed" shape with specific M3 corner radii (e.g. XS/S 8dp, M 12dp).
+ * - On toggle (`active` attribute): The resting shape flips (e.g. round ↔ square).
+ *
+ * **Rendering as a link:**
+ * When the `href` attribute is provided, the component internally renders as
+ * an `<a>` element instead of a `<button>`, allowing native routing and
+ * middle-click (open in new tab) behaviors while maintaining button visuals.
+ *
+ * @example
+ * ```html
+ * <!-- Primary filled button -->
+ * <moni-button icon="add">Create new</moni-button>
+ *
+ * <!-- Outlined button -->
+ * <moni-button variant="outlined">Cancel</moni-button>
  *
- * **Shape morph on press** (`m3-docs/components/buttons/specs.md` § Shape morph):
- * round and square buttons both morph to the same pressed shape, with per-size
- * corner radii: XS 8dp, S 8dp, M 12dp, L 16dp, XL 16dp. The per-size rules
- * `.button.{xsmall,small,large,xlarge,extra}:active` override the default
- * `:active` rule by specificity (0,4,0 vs 0,3,0).
+ * <!-- Toggle button (toggles active state on click) -->
+ * <moni-button icon="favorite" active>Like</moni-button>
  *
- * **Shape morph on selected** (toggle): when `active` is true, the resting
- * shape flips (round ↔ square). See `render()`.
+ * <!-- Link button -->
+ * <moni-button href="/settings" icon="settings">Settings</moni-button>
+ * ```
  *
- * Attributes:
- *  - variant:   filled (default) | tonal | elevated | outlined | text | fill
- *  - size:      xsmall | small | medium (default) | large | xlarge
- *               (legacy `extra` alias for `xlarge`, deprecated in v0.3.0)
- *  - shape:     round (default) | square | circle | no-round
- *               | left-round | right-round | top-round | bottom-round
- *               | left-round-flat | right-round-flat | top-round-flat
- *               | bottom-round-flat | inner-round
- *               (the `-flat` and `inner-round` shapes are Moni brand
- *                extensions; not part of M3 — see WEB_COMPONENT_GUIDELINES.md)
- *  - disabled:  present → native disabled
- *  - loading:   present → shows an indeterminate circular progress
- *  - active:    present → toggle (selection) state; applies shape morph
- *               (round↔square) and variant-specific color swap
- *  - icon:      Material Symbols name to prepend
- *  - icon-trailing: Material Symbols name to append
- *  - type:      button (default) | submit | reset
- *  - href:      present → renders as `<a>` instead of `<button>`
- *  - target:    for `<a>` rendering
+ * @slot default       - The button label text.
+ * @slot icon          - Optional override for the leading icon.
+ * @slot icon-trailing - Optional override for the trailing icon.
  *
- * Slots:
- *  - default:   button label
- *  - icon:      optional override for the leading icon
- *  - icon-trailing: optional override for the trailing icon
+ * @csspart button     - The inner `<button>` or `<a>` element.
+ * @csspart icon       - The leading icon container.
+ * @csspart label      - The label container.
+ * @csspart trailing-icon - The trailing icon container.
  */
 export declare class MoniButton extends MoniElement {
     private static _deprecationWarned;
@@ -59,7 +78,7 @@ export declare class MoniButton extends MoniElement {
     connectedCallback(): void;
     static styles: import("lit").CSSResult[];
     private handleLinkClick;
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-button.d.ts","sourceRoot":"","sources":["../../src/components/moni-button.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AACxB,OAAO,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBACa,UAAW,SAAQ,WAAW;IAC1C,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAS;IAG1C,OAAO,EACJ,QAAQ,GACR,OAAO,GACP,UAAU,GACV,MAAM,GACN,MAAM,GACN,UAAU,CAAY;IACzB;;;;OAIG;IAEH,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE9E,KAAK,EACF,OAAO,GACP,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,YAAY,GACZ,aAAa,GACb,WAAW,GACX,cAAc,GACd,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,mBAAmB,GACnB,aAAa,CAAW;IACiB,QAAQ,UAAS;IACjB,OAAO,UAAS;IAChB,MAAM,UAAS;IAC9B,IAAI,SAAM;IACkB,YAAY,SAAM;IAE3E,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAY;IAClB,IAAI,SAAM;IACV,MAAM,SAAM;IAEhC,iBAAiB,IAAI,IAAI;IAalC,OAAgB,MAAM,4BA6fpB;IAEF,OAAO,CAAC,eAAe;IAOd,MAAM;CAiFf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,aAAa,EAAE,UAAU,CAAC;KAC1B;CACD;AAED,eAAe,UAAU,CAAC"}
+{"version":3,"file":"moni-button.d.ts","sourceRoot":"","sources":["../../src/components/moni-button.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AACxB,OAAO,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,qBACa,UAAW,SAAQ,WAAW;IAC1C,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAS;IAG1C,OAAO,EACJ,QAAQ,GACR,OAAO,GACP,UAAU,GACV,MAAM,GACN,MAAM,GACN,UAAU,CAAY;IACzB;;;;OAIG;IAEH,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE9E,KAAK,EACF,OAAO,GACP,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,YAAY,GACZ,aAAa,GACb,WAAW,GACX,cAAc,GACd,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,mBAAmB,GACnB,aAAa,CAAW;IACiB,QAAQ,UAAS;IACjB,OAAO,UAAS;IAChB,MAAM,UAAS;IAC9B,IAAI,SAAM;IACkB,YAAY,SAAM;IAE3E,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAY;IAClB,IAAI,SAAM;IACV,MAAM,SAAM;IAEhC,iBAAiB,IAAI,IAAI;IAalC,OAAgB,MAAM,4BA6fpB;IAEF,OAAO,CAAC,eAAe;IAOd,MAAM;CAiFf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,aAAa,EAAE,UAAU,CAAC;KAC1B;CACD;AAED,eAAe,UAAU,CAAC"}

package/dist/components/moni-button.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-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);
@@ -12,41 +18,54 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 import './moni-progress.js';
 /**
- * Visual-only button. Renders a native `<button>` styled per Material 3 Expressive.
+ * Material Design 3 Button component.
+ *
+ * Buttons allow users to take actions and make choices with a single tap.
+ * This component provides all M3 button variants, sizes, and shape morphing
+ * capabilities (e.g. morphing to a pill shape on press or toggle).
+ *
+ * **M3 spec reference:** `m3-docs/components/buttons/specs.md`
+ *
+ * **Variants:**
+ * - `filled` (default) — High emphasis. Use for primary actions.
+ * - `tonal` — Medium emphasis. Secondary actions that still need to stand out.
+ * - `elevated` — Medium emphasis with shadow. Used when sitting on patterned backgrounds.
+ * - `outlined` — Medium emphasis, no fill. Secondary or tertiary actions.
+ * - `text` — Low emphasis. Tertiary actions (e.g. dialog cancel button).
+ *
+ * **Shape morphing (M3 Expressive feature):**
+ * - On press (active state): Round and square buttons morph to a slightly squarer
+ *   "pressed" shape with specific M3 corner radii (e.g. XS/S 8dp, M 12dp).
+ * - On toggle (`active` attribute): The resting shape flips (e.g. round ↔ square).
+ *
+ * **Rendering as a link:**
+ * When the `href` attribute is provided, the component internally renders as
+ * an `<a>` element instead of a `<button>`, allowing native routing and
+ * middle-click (open in new tab) behaviors while maintaining button visuals.
+ *
+ * @example
+ * ```html
+ * <!-- Primary filled button -->
+ * <moni-button icon="add">Create new</moni-button>
+ *
+ * <!-- Outlined button -->
+ * <moni-button variant="outlined">Cancel</moni-button>
  *
- * **Shape morph on press** (`m3-docs/components/buttons/specs.md` § Shape morph):
- * round and square buttons both morph to the same pressed shape, with per-size
- * corner radii: XS 8dp, S 8dp, M 12dp, L 16dp, XL 16dp. The per-size rules
- * `.button.{xsmall,small,large,xlarge,extra}:active` override the default
- * `:active` rule by specificity (0,4,0 vs 0,3,0).
+ * <!-- Toggle button (toggles active state on click) -->
+ * <moni-button icon="favorite" active>Like</moni-button>
  *
- * **Shape morph on selected** (toggle): when `active` is true, the resting
- * shape flips (round ↔ square). See `render()`.
+ * <!-- Link button -->
+ * <moni-button href="/settings" icon="settings">Settings</moni-button>
+ * ```
  *
- * Attributes:
- *  - variant:   filled (default) | tonal | elevated | outlined | text | fill
- *  - size:      xsmall | small | medium (default) | large | xlarge
- *               (legacy `extra` alias for `xlarge`, deprecated in v0.3.0)
- *  - shape:     round (default) | square | circle | no-round
- *               | left-round | right-round | top-round | bottom-round
- *               | left-round-flat | right-round-flat | top-round-flat
- *               | bottom-round-flat | inner-round
- *               (the `-flat` and `inner-round` shapes are Moni brand
- *                extensions; not part of M3 — see WEB_COMPONENT_GUIDELINES.md)
- *  - disabled:  present → native disabled
- *  - loading:   present → shows an indeterminate circular progress
- *  - active:    present → toggle (selection) state; applies shape morph
- *               (round↔square) and variant-specific color swap
- *  - icon:      Material Symbols name to prepend
- *  - icon-trailing: Material Symbols name to append
- *  - type:      button (default) | submit | reset
- *  - href:      present → renders as `<a>` instead of `<button>`
- *  - target:    for `<a>` rendering
+ * @slot default       - The button label text.
+ * @slot icon          - Optional override for the leading icon.
+ * @slot icon-trailing - Optional override for the trailing icon.
  *
- * Slots:
- *  - default:   button label
- *  - icon:      optional override for the leading icon
- *  - icon-trailing: optional override for the trailing icon
+ * @csspart button     - The inner `<button>` or `<a>` element.
+ * @csspart icon       - The leading icon container.
+ * @csspart label      - The label container.
+ * @csspart trailing-icon - The trailing icon container.
  */
 let MoniButton = class MoniButton extends MoniElement {
     constructor() {

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

@@ -1,43 +1,103 @@
+/**
+ * @file components/moni-card.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Material 3 Card (`m3-docs/components/cards/specs.md`).
- *
- * Cards display content and actions on a single subject. Three variants:
- *  - **elevated**: surface-container-low background + elevation 1 shadow.
- *    Default for collections where the card needs separation from a
- *    patterned background.
- *  - **filled**: surface-container-highest background, no shadow.
- *    Lowest emphasis; use when cards sit directly on the background.
- *  - **outlined**: surface background + outline-variant 1dp stroke.
- *    Highest emphasis without shadow; good on solid color backgrounds.
- *
- * M3 measurements:
- *  - Container corner radius: **12dp**.
- *  - Left/right padding: **16dp**.
- *  - Padding between cards in a collection: max **8dp**.
- *  - Headline text alignment: **start**.
- *
- * Slots:
- *  - media:        image or video at the top of the card.
- *  - default:      primary content (headline, subhead, supporting text).
- *  - headline:     shortcut for the H3-equivalent title (semantic).
- *  - subhead:      secondary title slot.
- *  - supporting:   supporting text slot.
- *  - actions:      action buttons row at the bottom of the card.
- *
- * Attributes:
- *  - variant: elevated (default) | filled | outlined
- *  - clickable: present → apply hover/focus/pressed state layers
- *  - draggable:  present → apply dragged state elevation (3)
- *  - disabled:   present → reduced opacity + cursor not-allowed
+ * Material Design 3 Card component.
+ *
+ * Cards display content and actions about a single subject. They are
+ * container surfaces that group related information together, making it
+ * easy for users to scan and interact with collections of related data.
+ *
+ * **M3 spec reference:** `m3-docs/components/cards/specs.md`
+ *
+ * **Variants:**
+ * - `elevated` (default) — `surface-container-low` background + `--elevate1` shadow.
+ *   Best for collections where the card needs visual separation from a
+ *   patterned or colored background. Gains shadow on hover/drag.
+ * - `filled` — `surface-container-highest` background, no shadow.
+ *   Lowest emphasis; use when cards sit directly on the main background surface.
+ * - `outlined` — `surface` background + 1dp `outline-variant` stroke.
+ *   Highest structural emphasis without casting a shadow. Best on solid backgrounds.
+ *
+ * **M3 measurements:**
+ * - Container corner radius: 12dp.
+ * - Horizontal content padding: 16dp.
+ * - Gap between cards in a collection: max 8dp.
+ * - Headline text alignment: start.
+ *
+ * **Interactive cards:**
+ * When `clickable=true`, the card renders M3 state layer overlays on hover,
+ * focus, and press via the `::before` pseudo-element. The consumer must handle
+ * the `click` event to implement navigation or selection logic.
+ *
+ * @example
+ * ```html
+ * <moni-card variant="outlined" clickable>
+ *   <img slot="media" src="photo.jpg" alt="Card image" />
+ *   <h3 slot="headline">Card Title</h3>
+ *   <p slot="supporting">Supporting text that describes the card topic.</p>
+ *   <div slot="actions">
+ *     <moni-button variant="text">Cancel</moni-button>
+ *     <moni-button>Confirm</moni-button>
+ *   </div>
+ * </moni-card>
+ * ```
+ *
+ * @slot media      - An image, video, or icon at the top of the card.
+ * @slot default    - Primary body content (replaces all named slots if used).
+ * @slot headline   - H3-equivalent title text.
+ * @slot subhead    - Secondary title below the headline.
+ * @slot supporting - Descriptive supporting body text.
+ * @slot actions    - Action buttons row at the bottom of the card.
+ *
+ * @csspart card    - The outer card container.
+ * @csspart media   - The media area wrapper.
+ * @csspart content - The content wrapper.
+ * @csspart actions - The actions row wrapper.
  */
 export declare class MoniCard extends MoniElement {
+    /**
+     * Visual variant of the card.
+     *
+     * - `'elevated'` (default) — Surface-low background + elevation shadow.
+     * - `'filled'` — Surface-highest background, no shadow.
+     * - `'outlined'` — Surface background + outline-variant stroke.
+     *
+     * @default 'elevated'
+     */
     variant: 'elevated' | 'filled' | 'outlined';
+    /**
+     * When `true`, applies M3 state layer overlays (hover, focus, pressed)
+     * to communicate interactivity. The card background shifts slightly on hover.
+     *
+     * Use when the card itself is a clickable navigation or selection target.
+     *
+     * @default false
+     */
     clickable: boolean;
+    /**
+     * When `true`, applies `--elevate3` box-shadow to simulate the M3 "dragged"
+     * state as specified in the M3 card interaction spec.
+     *
+     * Consumers should toggle this attribute based on the drag state of the card
+     * (e.g. via a drag-and-drop library callback).
+     *
+     * @default false
+     */
     draggable: boolean;
+    /**
+     * When `true`, the card renders at 50% opacity with `cursor: not-allowed`,
+     * signaling that the card and its actions are unavailable.
+     *
+     * @default false
+     */
     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-card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-card.d.ts","sourceRoot":"","sources":["../../src/components/moni-card.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBACa,QAAS,SAAQ,WAAW;IAExC,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,UAAU,CAAc;IACb,SAAS,UAAS;IAClB,SAAS,UAAS;IAClB,QAAQ,UAAS;IAE7D,OAAgB,MAAM,4BAmIpB;IAEO,MAAM;CAiBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,WAAW,EAAE,QAAQ,CAAC;KACtB;CACD;AAED,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"moni-card.d.ts","sourceRoot":"","sources":["../../src/components/moni-card.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,qBACa,QAAS,SAAQ,WAAW;IACxC;;;;;;;;OAQG;IAEH,OAAO,EAAE,UAAU,GAAG,QAAQ,GAAG,UAAU,CAAc;IAEzD;;;;;;;OAOG;IACyC,SAAS,UAAS;IAE9D;;;;;;;;OAQG;IACyC,SAAS,UAAS;IAE9D;;;;;OAKG;IACyC,QAAQ,UAAS;IAE7D,OAAgB,MAAM,4BAmIpB;IAEO,MAAM;CAiBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,WAAW,EAAE,QAAQ,CAAC;KACtB;CACD;AAED,eAAe,QAAQ,CAAC"}