@moni-labs/moni-ui 0.2.0 → 0.3.0

package/dist/components/moni-text-field.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-text-field.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,17 +18,56 @@ import { MoniElement, sharedStyles, fieldStyles } from './_base/index.js';
 import './moni-icon.js';
 import './moni-progress.js';
 /**
- * Visual-only text field. Renders the `.field` family of BeerCSS helpers
- * with a native `<input>`.
+ * Material Design 3 Text Field component.
+ *
+ * A full-featured input field that wraps a native `<input>` inside the M3
+ * field shell (`.field` class from `fieldStyles`). Supports floating labels,
+ * filled and outlined variants, leading/trailing icons, helper text, and
+ * error states.
+ *
+ * **M3 spec reference:** `m3-docs/components/text-fields/specs.md`
+ *
+ * **Visual architecture:**
+ * Uses `fieldStyles` for the complete CSS field shell. The field container
+ * is a `<div class="field [modifiers]">` wrapping:
+ * 1. Optional leading icon.
+ * 2. Native `<input>` element.
+ * 3. Floating `<label>` (when `label` is set).
+ * 4. Optional trailing icon or loading spinner.
+ * 5. `<output>` for helper/error text.
+ *
+ * **Visual-only contract:**
+ * This component does **not** listen to `@input` events to sync the `value`
+ * attribute back from the underlying `<input>`. Consumers must either:
+ * - Submit the native form (the `<input name>` participates in form submission).
+ * - Listen to `change` or `input` events via standard DOM event handling.
+ * - Use a framework binding (e.g. `bind:value` in Svelte, `v-model` in Vue).
+ *
+ * @example
+ * ```html
+ * <moni-text-field
+ *   label="Email address"
+ *   type="email"
+ *   name="email"
+ *   icon="mail"
+ *   variant="outlined"
+ *   helper="We'll never share your email."
+ * ></moni-text-field>
  *
- * This component is **visual-only**: it does NOT listen to `@input` to
- * sync the `value` attribute back from the underlying input. Consumers
- * either use form submission or wire their own change handling.
+ * <moni-text-field
+ *   label="Amount"
+ *   type="number"
+ *   prefix="$"
+ *   error
+ *   error-text="Value must be positive"
+ * ></moni-text-field>
+ * ```
  *
- * Attributes:
- *  - name, label, value, variant, size, shape, type, icon, trailing-icon,
- *    prefix, suffix, helper, error, error-text, disabled, placeholder — see below.
- *  - loading:   present → shows indeterminate circular progress
+ * @csspart field         - The outer `.field` div container.
+ * @csspart input         - The native `<input>` element.
+ * @csspart label         - The floating `<label>` element.
+ * @csspart helper        - The helper `<output>` element.
+ * @csspart error-output  - The error `<output>` element.
  */
 let MoniTextField = class MoniTextField extends MoniElement {
     constructor() {

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

@@ -1,27 +1,57 @@
+/**
+ * @file components/moni-textarea.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 textarea. Same field shell as moni-text-field but renders a
- * `<textarea>`. Visual-only: no `@input` listener.
- *
- * M3 spec (`m3-docs/components/text-fields/specs.md`): the textarea supports
- * both **filled** and **outlined** variants. When `maxlength` is set, a
- * character counter is shown next to the supporting text
- * (`{value.length} / {maxlength}`).
- *
- * Attributes:
- *  - name, label, value, variant, size, shape, disabled, helper, error,
- *    error-text, placeholder — see moni-text-field.
- *  - icon:           leading Material Symbols name
- *  - trailing-icon:  trailing Material Symbols name
- *  - prefix:         short text rendered before the input (e.g. "https://")
- *  - suffix:         short text rendered after the input (e.g. ".com")
- *  - loading:        present → shows indeterminate circular progress
- *  - rows:           native textarea rows attribute (default 3)
- *  - maxlength:      when set, displays a character counter
- *                    (auto-shown; can be hidden via `no-counter`)
- *  - no-counter:     suppress the character counter even when maxlength is set
+ * Material Design 3 Textarea component.
+ *
+ * A multi-line text input field designed for collecting longer amounts of text,
+ * such as comments, descriptions, or messages.
+ *
+ * **M3 spec reference:** `m3-docs/components/text-fields/specs.md`
+ *
+ * **Visual architecture:**
+ * It shares the exact same `.field` shell and styling engine as
+ * `<moni-text-field>`, but internally renders a native `<textarea>` instead
+ * of an `<input>`. This ensures visual consistency across all form elements
+ * regarding floating labels, helper text, error states, and icons.
+ *
+ * **Character Counter:**
+ * If the `maxlength` attribute is set, the textarea automatically displays
+ * a character counter (`{current length} / {maxlength}`) positioned at the
+ * trailing edge of the supporting text area (bottom right). This can be
+ * suppressed by setting the `no-counter` attribute.
+ *
+ * **State management:**
+ * This component is purely visual and presentational. It reflects attributes
+ * down to the native textarea, but it does NOT attach internal `@input` or
+ * `@change` listeners. Consumers should attach standard DOM listeners directly
+ * to this element to capture user input, just as they would with a native
+ * textarea.
+ *
+ * @example
+ * ```html
+ * <!-- Standard filled textarea -->
+ * <moni-textarea label="Description" rows="4"></moni-textarea>
+ *
+ * <!-- Outlined textarea with character counter -->
+ * <moni-textarea
+ *   variant="outlined"
+ *   label="Bio"
+ *   maxlength="160"
+ * ></moni-textarea>
+ * ```
+ *
+ * @csspart field     - The outer `.field` div container.
+ * @csspart input     - The native `<textarea>` element.
+ * @csspart label     - The floating `<label>` element.
+ * @csspart helper    - The helper/error text area.
+ * @csspart counter   - The character counter element.
  */
 export declare class MoniTextarea extends MoniElement {
     name: string;
@@ -46,7 +76,7 @@ export declare class MoniTextarea extends MoniElement {
     private _input;
     updated(changed: Map<string, unknown>): void;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-textarea.d.ts","sourceRoot":"","sources":["../../src/components/moni-textarea.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAA6B,MAAM,kBAAkB,CAAC;AAC1E,OAAO,gBAAgB,CAAC;AACxB,OAAO,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBACa,YAAa,SAAQ,WAAW;IACf,IAAI,SAAM;IACV,KAAK,SAAM;IACX,OAAO,EAAE,QAAQ,GAAG,UAAU,CAAY;IAEvE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAExD,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAc;IACvB,IAAI,SAAM;IACkB,YAAY,SAAM;IAC9C,MAAM,SAAM;IACZ,MAAM,SAAM;IACE,IAAI,SAAK;IACT,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE3E,SAAS,UAAS;IAC0B,OAAO,UAAS;IAChB,QAAQ,UAAS;IAChC,MAAM,SAAM;IACa,SAAS,SAAM;IACzB,KAAK,UAAS;IAC7B,KAAK,SAAM;IACX,WAAW,SAAM;IAE3B,OAAO,CAAC,MAAM,CAAuB;IAE/C,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAU9C,OAAgB,MAAM,4BAA+B;IAE5C,MAAM;CAkGf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,YAAY,CAAC;KAC9B;CACD;AAED,eAAe,YAAY,CAAC"}
+{"version":3,"file":"moni-textarea.d.ts","sourceRoot":"","sources":["../../src/components/moni-textarea.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,WAAW,EAA6B,MAAM,kBAAkB,CAAC;AAC1E,OAAO,gBAAgB,CAAC;AACxB,OAAO,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBACa,YAAa,SAAQ,WAAW;IACf,IAAI,SAAM;IACV,KAAK,SAAM;IACX,OAAO,EAAE,QAAQ,GAAG,UAAU,CAAY;IAEvE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAExD,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAc;IACvB,IAAI,SAAM;IACkB,YAAY,SAAM;IAC9C,MAAM,SAAM;IACZ,MAAM,SAAM;IACE,IAAI,SAAK;IACT,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE3E,SAAS,UAAS;IAC0B,OAAO,UAAS;IAChB,QAAQ,UAAS;IAChC,MAAM,SAAM;IACa,SAAS,SAAM;IACzB,KAAK,UAAS;IAC7B,KAAK,SAAM;IACX,WAAW,SAAM;IAE3B,OAAO,CAAC,MAAM,CAAuB;IAE/C,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAU9C,OAAgB,MAAM,4BAA+B;IAE5C,MAAM;CAkGf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,YAAY,CAAC;KAC9B;CACD;AAED,eAAe,YAAY,CAAC"}

package/dist/components/moni-textarea.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-textarea.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,26 +18,50 @@ import { MoniElement, sharedStyles, fieldStyles } from './_base/index.js';
 import './moni-icon.js';
 import './moni-progress.js';
 /**
- * Visual-only textarea. Same field shell as moni-text-field but renders a
- * `<textarea>`. Visual-only: no `@input` listener.
+ * Material Design 3 Textarea component.
+ *
+ * A multi-line text input field designed for collecting longer amounts of text,
+ * such as comments, descriptions, or messages.
+ *
+ * **M3 spec reference:** `m3-docs/components/text-fields/specs.md`
+ *
+ * **Visual architecture:**
+ * It shares the exact same `.field` shell and styling engine as
+ * `<moni-text-field>`, but internally renders a native `<textarea>` instead
+ * of an `<input>`. This ensures visual consistency across all form elements
+ * regarding floating labels, helper text, error states, and icons.
+ *
+ * **Character Counter:**
+ * If the `maxlength` attribute is set, the textarea automatically displays
+ * a character counter (`{current length} / {maxlength}`) positioned at the
+ * trailing edge of the supporting text area (bottom right). This can be
+ * suppressed by setting the `no-counter` attribute.
+ *
+ * **State management:**
+ * This component is purely visual and presentational. It reflects attributes
+ * down to the native textarea, but it does NOT attach internal `@input` or
+ * `@change` listeners. Consumers should attach standard DOM listeners directly
+ * to this element to capture user input, just as they would with a native
+ * textarea.
+ *
+ * @example
+ * ```html
+ * <!-- Standard filled textarea -->
+ * <moni-textarea label="Description" rows="4"></moni-textarea>
  *
- * M3 spec (`m3-docs/components/text-fields/specs.md`): the textarea supports
- * both **filled** and **outlined** variants. When `maxlength` is set, a
- * character counter is shown next to the supporting text
- * (`{value.length} / {maxlength}`).
+ * <!-- Outlined textarea with character counter -->
+ * <moni-textarea
+ *   variant="outlined"
+ *   label="Bio"
+ *   maxlength="160"
+ * ></moni-textarea>
+ * ```
  *
- * Attributes:
- *  - name, label, value, variant, size, shape, disabled, helper, error,
- *    error-text, placeholder — see moni-text-field.
- *  - icon:           leading Material Symbols name
- *  - trailing-icon:  trailing Material Symbols name
- *  - prefix:         short text rendered before the input (e.g. "https://")
- *  - suffix:         short text rendered after the input (e.g. ".com")
- *  - loading:        present → shows indeterminate circular progress
- *  - rows:           native textarea rows attribute (default 3)
- *  - maxlength:      when set, displays a character counter
- *                    (auto-shown; can be hidden via `no-counter`)
- *  - no-counter:     suppress the character counter even when maxlength is set
+ * @csspart field     - The outer `.field` div container.
+ * @csspart input     - The native `<textarea>` element.
+ * @csspart label     - The floating `<label>` element.
+ * @csspart helper    - The helper/error text area.
+ * @csspart counter   - The character counter element.
  */
 let MoniTextarea = class MoniTextarea extends MoniElement {
     constructor() {

package/dist/components/moni-time-picker.d.ts

@@ -1,20 +1,50 @@
+/**
+ * @file components/moni-time-picker.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { PropertyValues } from 'lit';
 import { MoniElement } from './_base/index.js';
 import './moni-icon.js';
 import './moni-button.js';
 /**
- * Material Design 3 Time Picker Component.
- * Supports interactive clock face (dial) and manual keyboard input.
+ * Material Design 3 Time Picker component.
+ *
+ * A highly interactive control that allows users to select a specific time.
+ * It provides two distinct input modes:
+ * 1. **Dial mode:** An interactive clock face where users can drag or click
+ *    to select hours and minutes.
+ * 2. **Input mode:** Standard text inputs for precise keyboard entry.
+ *
+ * **M3 spec reference:** `m3-docs/components/time-pickers/specs.md`
+ *
+ * **Time formats & modes:**
+ * - The `value` property expects and always outputs a 24-hour formatted string
+ *   (`HH:MM`, e.g., `"14:30"`).
+ * - Setting `use-24-hour` configures the visual presentation to use a 24-hour
+ *   clock dial (inner and outer rings) and removes the AM/PM toggle. Otherwise,
+ *   it uses a standard 12-hour dial with an AM/PM toggle.
+ *
+ * **Responsive design:**
+ * The `orientation` attribute configures the layout. `vertical` stacks the
+ * time display above the clock face, `horizontal` places them side-by-side,
+ * and `auto` responds to the container/viewport width automatically.
+ *
+ * @fires change - Fired when the selected time changes interactively. The
+ *                 `detail.value` contains the new time in `HH:MM` format.
+ * @fires cancel - Fired when the 'Cancel' button is clicked.
+ * @fires ok     - Fired when the 'OK' button is clicked. The `detail.value`
+ *                 contains the final confirmed time.
  *
- * Attributes:
- *  - value: Time value in "HH:MM" 24h format (default "00:00")
- *  - use24Hour: If true, uses 24-hour mode without AM/PM toggle (default false)
- *  - mode: "dial" | "input" (default "dial")
+ * @example
+ * ```html
+ * <!-- 12-hour format (AM/PM) -->
+ * <moni-time-picker value="14:30"></moni-time-picker>
  *
- * Events:
- *  - change: Fired when value changes (detail: { value })
- *  - cancel: Fired when cancel button is clicked
- *  - ok: Fired when OK button is clicked (detail: { value })
+ * <!-- 24-hour format -->
+ * <moni-time-picker use-24-hour value="14:30"></moni-time-picker>
+ * ```
  */
 export declare class MoniTimePicker extends MoniElement {
     value: string;
@@ -40,7 +70,7 @@ export declare class MoniTimePicker extends MoniElement {
     private handleMinuteInputChange;
     static styles: import("lit").CSSResult[];
     private renderDialClockFace;
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/components/moni-time-picker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-time-picker.d.ts","sourceRoot":"","sources":["../../src/components/moni-time-picker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,cAAc,EAAE,MAAM,KAAK,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AACxB,OAAO,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;GAaG;AACH,qBACa,cAAe,SAAQ,WAAW;IACjB,KAAK,SAAW;IACyB,SAAS,UAAS;IAC3D,IAAI,EAAE,MAAM,GAAG,OAAO,CAAU;IAChC,WAAW,EAAE,UAAU,GAAG,YAAY,GAAG,MAAM,CAAU;IAE7E,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,MAAM,CAAqB;IAEnC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,aAAa,CAAK;IAEb,OAAO,CAAC,WAAW,CAAC,CAAiB;IAE3D,OAAO,CAAC,UAAU,CAAS;cAER,UAAU,CAAC,iBAAiB,EAAE,cAAc;IAM/D,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,WAAW;IAwBnB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,sBAAsB;IA2C9B,OAAO,CAAC,oBAAoB;IAa5B,OAAO,CAAC,qBAAqB;IAiB7B,OAAO,CAAC,uBAAuB;IAY/B,OAAgB,MAAM,4BAqXpB;IAEF,OAAO,CAAC,mBAAmB;IAwIlB,MAAM;CAsFf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,kBAAkB,EAAE,cAAc,CAAC;KACnC;CACD;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"moni-time-picker.d.ts","sourceRoot":"","sources":["../../src/components/moni-time-picker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAa,cAAc,EAAE,MAAM,KAAK,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AACxB,OAAO,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBACa,cAAe,SAAQ,WAAW;IACjB,KAAK,SAAW;IACyB,SAAS,UAAS;IAC3D,IAAI,EAAE,MAAM,GAAG,OAAO,CAAU;IAChC,WAAW,EAAE,UAAU,GAAG,YAAY,GAAG,MAAM,CAAU;IAE7E,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,MAAM,CAAqB;IAEnC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,aAAa,CAAK;IAEb,OAAO,CAAC,WAAW,CAAC,CAAiB;IAE3D,OAAO,CAAC,UAAU,CAAS;cAER,UAAU,CAAC,iBAAiB,EAAE,cAAc;IAM/D,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,WAAW;IAwBnB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,sBAAsB;IA2C9B,OAAO,CAAC,oBAAoB;IAa5B,OAAO,CAAC,qBAAqB;IAiB7B,OAAO,CAAC,uBAAuB;IAY/B,OAAgB,MAAM,4BAqXpB;IAEF,OAAO,CAAC,mBAAmB;IAwIlB,MAAM;CAsFf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,kBAAkB,EAAE,cAAc,CAAC;KACnC;CACD;AAED,eAAe,cAAc,CAAC"}

package/dist/components/moni-time-picker.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-time-picker.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);
@@ -10,18 +16,42 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 import './moni-button.js';
 /**
- * Material Design 3 Time Picker Component.
- * Supports interactive clock face (dial) and manual keyboard input.
+ * Material Design 3 Time Picker component.
+ *
+ * A highly interactive control that allows users to select a specific time.
+ * It provides two distinct input modes:
+ * 1. **Dial mode:** An interactive clock face where users can drag or click
+ *    to select hours and minutes.
+ * 2. **Input mode:** Standard text inputs for precise keyboard entry.
+ *
+ * **M3 spec reference:** `m3-docs/components/time-pickers/specs.md`
+ *
+ * **Time formats & modes:**
+ * - The `value` property expects and always outputs a 24-hour formatted string
+ *   (`HH:MM`, e.g., `"14:30"`).
+ * - Setting `use-24-hour` configures the visual presentation to use a 24-hour
+ *   clock dial (inner and outer rings) and removes the AM/PM toggle. Otherwise,
+ *   it uses a standard 12-hour dial with an AM/PM toggle.
+ *
+ * **Responsive design:**
+ * The `orientation` attribute configures the layout. `vertical` stacks the
+ * time display above the clock face, `horizontal` places them side-by-side,
+ * and `auto` responds to the container/viewport width automatically.
+ *
+ * @fires change - Fired when the selected time changes interactively. The
+ *                 `detail.value` contains the new time in `HH:MM` format.
+ * @fires cancel - Fired when the 'Cancel' button is clicked.
+ * @fires ok     - Fired when the 'OK' button is clicked. The `detail.value`
+ *                 contains the final confirmed time.
  *
- * Attributes:
- *  - value: Time value in "HH:MM" 24h format (default "00:00")
- *  - use24Hour: If true, uses 24-hour mode without AM/PM toggle (default false)
- *  - mode: "dial" | "input" (default "dial")
+ * @example
+ * ```html
+ * <!-- 12-hour format (AM/PM) -->
+ * <moni-time-picker value="14:30"></moni-time-picker>
  *
- * Events:
- *  - change: Fired when value changes (detail: { value })
- *  - cancel: Fired when cancel button is clicked
- *  - ok: Fired when OK button is clicked (detail: { value })
+ * <!-- 24-hour format -->
+ * <moni-time-picker use-24-hour value="14:30"></moni-time-picker>
+ * ```
  */
 let MoniTimePicker = class MoniTimePicker extends MoniElement {
     constructor() {

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

@@ -1,30 +1,58 @@
+/**
+ * @file components/moni-toolbar.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Material 3 Toolbar (`m3-docs/components/top-app-bar/specs.md`).
+ * Material Design 3 Top App Bar (Toolbar) component.
+ *
+ * Top app bars display information and actions at the top of a screen.
+ * They are used for branding, screen titles, navigation, and actions.
+ *
+ * **M3 spec reference:** `m3-docs/components/top-app-bar/specs.md`
+ *
+ * **Note:** This is the standard top-level toolbar. For bottom navigation
+ * bars (often used on mobile), use `<moni-app-bar>`.
+ *
+ * **Variants:**
+ * - `standard` (default): A full-width bar (64dp height) that sits flush
+ *   against the top of the screen.
+ * - `floating`: A detached bar with a 4dp margin and rounded 8dp corners,
+ *   appearing to float above the content.
  *
- * This is the larger/top-level variant. If you need the compact
- * Navigation Bar at the bottom of the screen, use `<moni-app-bar>`.
+ * **Scroll behavior:**
+ * When the `scroll` attribute is present, the toolbar visually responds to
+ * scrolling by increasing its elevation (shadow) and dynamically shifting
+ * its surface color to indicate depth over the scrolling content.
  *
- * Supported M3 types:
- *  - **standard** (default): 64dp height, flat surface color, bottom shadow.
- *  - **floating**: 4dp margin, rounded 8dp corners, elevated.
+ * @example
+ * ```html
+ * <!-- Standard toolbar with navigation and actions -->
+ * <moni-toolbar title="Inbox">
+ *   <moni-icon-button slot="leading" icon="menu"></moni-icon-button>
+ *   <moni-icon-button slot="trailing" icon="search"></moni-icon-button>
+ *   <moni-icon-button slot="trailing" icon="more_vert"></moni-icon-button>
+ * </moni-toolbar>
  *
- * Slots:
- *  - default:       title / center content.
- *  - leading:       navigation icon/button.
- *  - trailing:      action icons/buttons.
- *  - action-button: floating action button (moni-fab) anchored right.
+ * <!-- Floating toolbar with an attached FAB -->
+ * <moni-toolbar type="floating" title="Notes">
+ *   <moni-fab slot="action-button" icon="add"></moni-fab>
+ * </moni-toolbar>
+ * ```
  *
- * Attributes:
- *  - type:   standard (default) | floating
- *  - scroll: true | false (default). When true, elevation increases on scroll.
+ * @slot default       - The title text or center content.
+ * @slot leading       - Navigation icon/button placed on the far left.
+ * @slot trailing      - Action icons/buttons placed on the far right.
+ * @slot action-button - A floating action button (FAB) anchored to the right side.
  */
 export declare class MoniToolbar extends MoniElement {
     type: 'standard' | 'floating';
     scrolled: boolean;
     title: string;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-toolbar.d.ts","sourceRoot":"","sources":["../../src/components/moni-toolbar.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBACa,WAAY,SAAQ,WAAW;IAE3C,IAAI,EAAE,UAAU,GAAG,UAAU,CAAc;IAE3C,QAAQ,UAAS;IACY,KAAK,SAAM;IAExC,OAAgB,MAAM,4BA8DpB;IAEO,MAAM;CAcf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,cAAc,EAAE,WAAW,CAAC;KAC5B;CACD;AAED,eAAe,WAAW,CAAC"}
+{"version":3,"file":"moni-toolbar.d.ts","sourceRoot":"","sources":["../../src/components/moni-toolbar.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,qBACa,WAAY,SAAQ,WAAW;IAE3C,IAAI,EAAE,UAAU,GAAG,UAAU,CAAc;IAE3C,QAAQ,UAAS;IACY,KAAK,SAAM;IAExC,OAAgB,MAAM,4BA8DpB;IAEO,MAAM;CAcf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,cAAc,EAAE,WAAW,CAAC;KAC5B;CACD;AAED,eAAe,WAAW,CAAC"}

package/dist/components/moni-toolbar.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-toolbar.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,24 +14,46 @@ import { html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Material 3 Toolbar (`m3-docs/components/top-app-bar/specs.md`).
+ * Material Design 3 Top App Bar (Toolbar) component.
+ *
+ * Top app bars display information and actions at the top of a screen.
+ * They are used for branding, screen titles, navigation, and actions.
+ *
+ * **M3 spec reference:** `m3-docs/components/top-app-bar/specs.md`
+ *
+ * **Note:** This is the standard top-level toolbar. For bottom navigation
+ * bars (often used on mobile), use `<moni-app-bar>`.
+ *
+ * **Variants:**
+ * - `standard` (default): A full-width bar (64dp height) that sits flush
+ *   against the top of the screen.
+ * - `floating`: A detached bar with a 4dp margin and rounded 8dp corners,
+ *   appearing to float above the content.
  *
- * This is the larger/top-level variant. If you need the compact
- * Navigation Bar at the bottom of the screen, use `<moni-app-bar>`.
+ * **Scroll behavior:**
+ * When the `scroll` attribute is present, the toolbar visually responds to
+ * scrolling by increasing its elevation (shadow) and dynamically shifting
+ * its surface color to indicate depth over the scrolling content.
  *
- * Supported M3 types:
- *  - **standard** (default): 64dp height, flat surface color, bottom shadow.
- *  - **floating**: 4dp margin, rounded 8dp corners, elevated.
+ * @example
+ * ```html
+ * <!-- Standard toolbar with navigation and actions -->
+ * <moni-toolbar title="Inbox">
+ *   <moni-icon-button slot="leading" icon="menu"></moni-icon-button>
+ *   <moni-icon-button slot="trailing" icon="search"></moni-icon-button>
+ *   <moni-icon-button slot="trailing" icon="more_vert"></moni-icon-button>
+ * </moni-toolbar>
  *
- * Slots:
- *  - default:       title / center content.
- *  - leading:       navigation icon/button.
- *  - trailing:      action icons/buttons.
- *  - action-button: floating action button (moni-fab) anchored right.
+ * <!-- Floating toolbar with an attached FAB -->
+ * <moni-toolbar type="floating" title="Notes">
+ *   <moni-fab slot="action-button" icon="add"></moni-fab>
+ * </moni-toolbar>
+ * ```
  *
- * Attributes:
- *  - type:   standard (default) | floating
- *  - scroll: true | false (default). When true, elevation increases on scroll.
+ * @slot default       - The title text or center content.
+ * @slot leading       - Navigation icon/button placed on the far left.
+ * @slot trailing      - Action icons/buttons placed on the far right.
+ * @slot action-button - A floating action button (FAB) anchored to the right side.
  */
 let MoniToolbar = class MoniToolbar extends MoniElement {
     constructor() {

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

@@ -1,33 +1,63 @@
+/**
+ * @file components/moni-tooltip.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Tooltip that faithfully ports BeerCSS's `.tooltip` styles and adds M3
- * Expressive semantics.
+ * Material Design 3 Tooltip component.
+ *
+ * Tooltips provide contextual text labels or rich content that appear when
+ * users hover over, focus on, or tap an element. They surface supplementary
+ * information that helps users understand interface elements without
+ * permanently occupying screen space.
+ *
+ * **M3 spec reference:** `m3-docs/components/tooltips/specs.md`
+ *
+ * **Types:**
+ * - **Plain** (default) — Text-only label for simple descriptions (max 1 line).
+ * - **Rich** (`rich` attribute) — HTML content including formatted text,
+ *   links, and icons. Rich tooltips can contain multiple lines and action links.
+ *
+ * **Placements:**
+ * - `top` (default), `top-start`, `top-end`
+ * - `bottom`, `bottom-start`, `bottom-end`
+ *
+ * **Trigger mechanism:**
+ * The tooltip uses `position: absolute` inside the parent element. The parent
+ * must have `position: relative` (set automatically via `connectedCallback`).
+ * Hover/focus events on the parent trigger the tooltip's CSS `:hover` and
+ * `:focus-within` selectors, which drive the show/hide transition.
+ *
+ * **Accessibility:**
+ * - The tooltip has `role="tooltip"`.
+ * - For keyboard accessibility, the parent should have `aria-describedby`
+ *   pointing to the tooltip's `id` attribute. The component exposes a
+ *   `tooltipId` getter for this purpose.
+ * - The `Escape` key closes rich tooltips.
  *
- * **M3 spec** (`m3-docs/components/tooltips/specs.md`):
- *  - Two types: **plain** (text only) and **rich** (HTML content).
- *  - 6 placements: top, top-start, top-end, bottom, bottom-start, bottom-end.
- *  - Trigger: hover (mouse) or focus (keyboard) on the parent.
- *  - Auto-dismiss: tooltip hides on `mouseleave` / `focusout` / `Escape`.
+ * @example
+ * ```html
+ * <!-- Plain tooltip -->
+ * <button aria-describedby="save-tip">
+ *   Save
+ *   <moni-tooltip id="save-tip" text="Ctrl+S"></moni-tooltip>
+ * </button>
  *
- * The component delegates trigger detection to the parent element (consistent
- * with the original BeerCSS port). The tooltip element is `position: absolute`
- * inside the parent so it follows the trigger naturally.
+ * <!-- Rich tooltip -->
+ * <button>
+ *   Filter
+ *   <moni-tooltip rich position="bottom">
+ *     <strong>Filter by date</strong>
+ *     <p>Select a date range to filter results.</p>
+ *   </moni-tooltip>
+ * </button>
+ * ```
  *
- * **Accessibility**:
- *  - The tooltip has `role="tooltip"` (M3 spec).
- *  - When `rich` content is used, the parent should also have
- *    `aria-describedby="<tooltip-id>"`. The component sets a unique `id` on
- *    the tooltip element and exposes it via `tooltipId` getter.
- *  - `Escape` closes the tooltip (WAI-ARIA tooltip pattern).
+ * @slot default - Rich content for the tooltip body (only used when `rich=true`).
  *
- * Attributes:
- *  - text:      tooltip text (plain tooltip)
- *  - position:  top (default) | top-start | top-end | bottom | bottom-start | bottom-end
- *  - size:      '' (default) | small | medium | large
- *  - rich:      boolean — when true, the default slot accepts arbitrary HTML
- *               for rich content (links, icons, etc.). When false (default),
- *               the slot is rendered as text only.
- *  - id:        forwarded to the tooltip element (useful for aria-describedby)
+ * @csspart tooltip - The tooltip container element.
  */
 export declare class MoniTooltip extends MoniElement {
     text: string;
@@ -54,7 +84,7 @@ export declare class MoniTooltip extends MoniElement {
      */
     get tooltipId(): string;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {