@moni-labs/moni-ui 0.2.0 → 0.3.0

package/dist/components/moni-checkbox.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-checkbox.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,33 +16,114 @@ import { ifDefined } from 'lit/directives/if-defined.js';
 import { live } from 'lit/directives/live.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Checkbox that faithfully ports BeerCSS's `.checkbox` styles.
+ * Material Design 3 Checkbox component.
+ *
+ * Checkboxes allow users to select one or more items from a set, or toggle
+ * a single binary option. They are visual-only shells — the consumer is
+ * responsible for wiring up form submission and validation logic.
+ *
+ * **Visual architecture (BeerCSS pattern):**
+ * The native `<input type="checkbox">` occupies real layout space (16×16 minimum)
+ * but is visually hidden via `opacity: 0`. A `<span>` sibling rendered after
+ * the input holds two pseudo-elements:
+ * - `::before` — the visible checkbox icon (Material Symbols ligature).
+ * - `::after`  — the hover/focus state layer ripple ring.
+ *
+ * The `::before` content switches between:
+ * - `'check_box_outline_blank'` (unchecked)
+ * - `'check_box'` (checked)
+ * - `'indeterminate_check_box'` (native indeterminate state)
+ *
+ * **Form integration:**
+ * Setting `name` and `value` passes them to the native `<input>` element,
+ * enabling participation in HTML form submissions.
+ *
+ * @fires change - Bubbles and is composed. Fired when the checkbox is toggled.
+ *                 The consumer can read `element.checked` for the new state.
+ *
+ * @example
+ * ```html
+ * <moni-checkbox label="Accept terms" name="terms" value="yes"></moni-checkbox>
  *
- * BeerCSS architecture:
- *  - `.checkbox` is inline-flex, aligns items center
- *  - `input` has width/height = --_size, opacity: 0  (occupies real space, no absolute!)
- *  - `span::before` is the visible checkbox box (position: absolute, inset from the input)
- *  - `span::after` is the ripple hover effect
- *  - Content is set via CSS: "check_box_outline_blank" / "check_box" (Material Symbols font)
+ * <script>
+ *   document.querySelector('moni-checkbox').addEventListener('change', (e) => {
+ *     console.log('checked:', e.target.checked);
+ *   });
+ * </script>
+ * ```
  *
- * Attributes:
- *  - label:    text label
- *  - checked:  present → input is checked
- *  - disabled: present → input is disabled
- *  - size:     small | medium (default) | large | extra
- *  - name:     forwarded to input.name
- *  - value:    forwarded to input.value
+ * @csspart checkbox - The outer `<label>` element.
  */
 let MoniCheckbox = class MoniCheckbox extends MoniElement {
     constructor() {
         super(...arguments);
+        /**
+         * Text label displayed to the right of the checkbox icon.
+         *
+         * When non-empty, the label is rendered as a text node inside the `<span>`.
+         * When empty, the default slot is rendered instead, allowing slotted HTML.
+         *
+         * @default ''
+         */
         this.label = '';
+        /**
+         * Whether the checkbox is currently checked.
+         *
+         * Reflected as an attribute so CSS attribute selectors and external state
+         * readers can observe the checked state without accessing the JS property.
+         * Synced to the native input via `updated()`.
+         *
+         * @default false
+         */
         this.checked = false;
+        /**
+         * When `true`, the native input is disabled: the checkbox is not interactive
+         * and renders at 50% opacity.
+         *
+         * @default false
+         */
         this.disabled = false;
+        /**
+         * Visual size of the checkbox icon.
+         *
+         * Maps to the `--_size` custom property which controls both the invisible
+         * input's hit area and the visible `::before` icon size.
+         *
+         * | Value      | `--_size` |
+         * |------------|-----------|
+         * | `'small'`  | 1rem      |
+         * | `'medium'` | 1.5rem    |
+         * | `'large'`  | 2rem      |
+         * | `'extra'`  | 2.5rem    |
+         *
+         * @default 'medium'
+         */
         this.size = 'medium';
+        /**
+         * Forwarded to the native `<input name>` attribute.
+         * Required for grouping checkboxes within a form.
+         *
+         * @default ''
+         */
         this.name = '';
+        /**
+         * Forwarded to the native `<input value>` attribute.
+         * The value submitted in a form when this checkbox is checked.
+         *
+         * @default ''
+         */
         this.value = '';
     }
+    /**
+     * Syncs `checked` and `disabled` back to the native input element after
+     * Lit's render cycle, ensuring the DOM stays in sync with component state.
+     *
+     * This is necessary because Lit's `.property=${value}` binding updates the
+     * DOM property, but the `live()` directive and direct property assignment
+     * are more reliable for boolean inputs across browser implementations.
+     *
+     * @param changed - Map of changed property names to their previous values.
+     */
     updated(changed) {
         if (this._input) {
             if (changed.has('checked'))
@@ -162,10 +249,27 @@ let MoniCheckbox = class MoniCheckbox extends MoniElement {
 			}
 		`
     ]; }
+    /**
+     * Handles the native input's `change` event.
+     *
+     * Reads the new checked state from the input and re-dispatches a composed
+     * `'change'` event so the signal crosses shadow DOM boundaries and can be
+     * heard by parent elements in the light DOM.
+     *
+     * @param e - The native `change` event from the hidden `<input>`.
+     */
     _onChange(e) {
         this.checked = e.target.checked;
         this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
     }
+    /**
+     * Renders the accessible checkbox label structure.
+     *
+     * The `<label>` wraps the hidden `<input>` and a `<span>` so that clicking
+     * anywhere on the label area (including the text) toggles the checkbox.
+     * The `has-label` class on the span adds left padding to separate the icon
+     * from the label text.
+     */
     render() {
         return html `<label part="checkbox">
 			<input

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

@@ -1,36 +1,62 @@
+/**
+ * @file components/moni-chip.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 chip. Renders a native `<button>` styled per Material 3 Expressive.
- *
- * M3 spec (`m3-docs/components/chips/specs.md`) defines **4 variants**:
- *  - **assist**     — smart/automated actions; outlined; `outline` 1dp stroke.
- *  - **filter**     — filters for a collection; outlined; leading check when selected.
- *  - **input**      — discrete user input; outlined; trailing remove icon.
- *  - **suggestion** — product-generated suggestions; outlined; no icons.
- *
- * All variants share M3 measurements: 32dp height, 8dp corner, 18dp icon.
- * Container height scales with `size` (`small` = 32dp = M3 default,
- * `medium`/`large` are Moni extensions with larger touch targets).
- *
- * **A11y** — `assist` and `suggestion` use `var(--outline)` for the
- * stroke to ensure 3:1 contrast (per `m3-docs/components/chips/accessibility.md`
- * § *Showing chip interactivity*). `filter` and `input` use `outline-variant`
- * for the resting state but show a clear `secondary-container` background
- * when selected, passing contrast.
- *
- * Attributes:
- *  - variant:   assist (default) | filter | input | suggestion
- *               | outlined (alias for assist) | fill (alias for filter)
- *  - size:      small (default, 32dp = M3) | medium | large
- *  - shape:     round (default) | square | circle | no-round
- *               | left-round | right-round | top-round | bottom-round
- *  - selected:  present → background uses secondary-container (M3 filter/input)
- *  - removable: present → adds a trailing ✕ icon (M3 input chip, visual only)
- *  - disabled:  present → native disabled
- *  - loading:   present → shows indeterminate circular progress
- *  - icon:      Material Symbols name (leading icon)
+ * Material Design 3 Chip component.
+ *
+ * Chips are compact, interactive elements that represent actions, filters,
+ * attributes, or user inputs. They are visual-only shells — the consumer
+ * owns all state management (selection, removal, active filter state).
+ *
+ * **M3 spec reference:** `m3-docs/components/chips/specs.md`
+ *
+ * **Variants:**
+ * - `assist` (default) — Smart or suggested actions. Uses `var(--outline)` border
+ *   to ensure 3:1 contrast per the M3 accessibility spec. Alias: `outlined`.
+ * - `filter` — Filters for a content collection. Shows a leading checkmark when
+ *   `selected`. Alias: `fill`.
+ * - `input` — Represents discrete user input (tags, tokens). Adds a trailing
+ *   remove icon when `removable`.
+ * - `suggestion` — Product-generated suggestions. Outlined, no icons.
+ *
+ * **M3 measurements:**
+ * - Default height: 32dp (`small` size = M3 spec baseline).
+ * - Corner radius: 8dp.
+ * - Icon size: 18dp.
+ * - `medium` and `large` sizes are Moni extensions with larger touch targets.
+ *
+ * **Accessibility:**
+ * `assist` and `suggestion` chips use `var(--outline)` for their stroke to
+ * guarantee 3:1 contrast against the surface background at rest.
+ * `filter` and `input` use `outline-variant` at rest but achieve contrast
+ * through the `secondary-container` fill when selected.
+ *
+ * @fires remove - Bubbles and is composed. Fired when the trailing remove
+ *                 icon is clicked on an `input` chip with `removable`.
+ *
+ * @example
+ * ```html
+ * <!-- Filter chip with selected state -->
+ * <moni-chip variant="filter" selected>Technology</moni-chip>
+ *
+ * <!-- Input chip (tag/token) -->
+ * <moni-chip variant="input" removable icon="label">TypeScript</moni-chip>
+ *
+ * <!-- Assist chip with icon -->
+ * <moni-chip icon="directions_car">Get directions</moni-chip>
+ * ```
+ *
+ * @slot default   - The chip label text.
+ * @slot icon      - Override for the leading icon (alternative to the `icon` attribute).
+ *
+ * @csspart chip   - The inner `<button>` element.
+ * @csspart label  - The label `<span>` element.
  */
 export declare class MoniChip extends MoniElement {
     variant: 'assist' | 'filter' | 'input' | 'suggestion' | 'outlined' | 'fill';
@@ -46,7 +72,7 @@ export declare class MoniChip extends MoniElement {
     /** Normalize legacy variant names to M3 spec. */
     private get _variant();
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-chip.d.ts","sourceRoot":"","sources":["../../src/components/moni-chip.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AACxB,OAAO,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBACa,QAAS,SAAQ,WAAW;IAExC,OAAO,EACJ,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,YAAY,GACZ,UAAU,GACV,MAAM,CAAY;IAErB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAW;IAE7C,KAAK,EACF,OAAO,GACP,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,YAAY,GACZ,aAAa,GACb,WAAW,GACX,cAAc,CAAW;IACgB,QAAQ,UAAS;IACjB,SAAS,UAAS;IAClB,QAAQ,UAAS;IACjB,OAAO,UAAS;IAC/B,IAAI,SAAM;IAGvC,OAAO,CAAC,eAAe,CAAS;IAEhC,OAAO,CAAC,iBAAiB;IAKzB,iDAAiD;IACjD,OAAO,KAAK,QAAQ,GAInB;IAED,OAAgB,MAAM,4BAqLpB;IAEO,MAAM;CA+Df;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,WAAW,EAAE,QAAQ,CAAC;KACtB;CACD;AAED,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"moni-chip.d.ts","sourceRoot":"","sources":["../../src/components/moni-chip.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AACxB,OAAO,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,qBACa,QAAS,SAAQ,WAAW;IAExC,OAAO,EACJ,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,YAAY,GACZ,UAAU,GACV,MAAM,CAAY;IAErB,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAW;IAE7C,KAAK,EACF,OAAO,GACP,UAAU,GACV,QAAQ,GACR,QAAQ,GACR,YAAY,GACZ,aAAa,GACb,WAAW,GACX,cAAc,CAAW;IACgB,QAAQ,UAAS;IACjB,SAAS,UAAS;IAClB,QAAQ,UAAS;IACjB,OAAO,UAAS;IAC/B,IAAI,SAAM;IAGvC,OAAO,CAAC,eAAe,CAAS;IAEhC,OAAO,CAAC,iBAAiB;IAKzB,iDAAiD;IACjD,OAAO,KAAK,QAAQ,GAInB;IAED,OAAgB,MAAM,4BAqLpB;IAEO,MAAM;CA+Df;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,WAAW,EAAE,QAAQ,CAAC;KACtB;CACD;AAED,eAAe,QAAQ,CAAC"}

package/dist/components/moni-chip.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-chip.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,35 +16,55 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 import './moni-progress.js';
 /**
- * Visual-only chip. Renders a native `<button>` styled per Material 3 Expressive.
+ * Material Design 3 Chip component.
+ *
+ * Chips are compact, interactive elements that represent actions, filters,
+ * attributes, or user inputs. They are visual-only shells — the consumer
+ * owns all state management (selection, removal, active filter state).
+ *
+ * **M3 spec reference:** `m3-docs/components/chips/specs.md`
+ *
+ * **Variants:**
+ * - `assist` (default) — Smart or suggested actions. Uses `var(--outline)` border
+ *   to ensure 3:1 contrast per the M3 accessibility spec. Alias: `outlined`.
+ * - `filter` — Filters for a content collection. Shows a leading checkmark when
+ *   `selected`. Alias: `fill`.
+ * - `input` — Represents discrete user input (tags, tokens). Adds a trailing
+ *   remove icon when `removable`.
+ * - `suggestion` — Product-generated suggestions. Outlined, no icons.
+ *
+ * **M3 measurements:**
+ * - Default height: 32dp (`small` size = M3 spec baseline).
+ * - Corner radius: 8dp.
+ * - Icon size: 18dp.
+ * - `medium` and `large` sizes are Moni extensions with larger touch targets.
+ *
+ * **Accessibility:**
+ * `assist` and `suggestion` chips use `var(--outline)` for their stroke to
+ * guarantee 3:1 contrast against the surface background at rest.
+ * `filter` and `input` use `outline-variant` at rest but achieve contrast
+ * through the `secondary-container` fill when selected.
+ *
+ * @fires remove - Bubbles and is composed. Fired when the trailing remove
+ *                 icon is clicked on an `input` chip with `removable`.
+ *
+ * @example
+ * ```html
+ * <!-- Filter chip with selected state -->
+ * <moni-chip variant="filter" selected>Technology</moni-chip>
  *
- * M3 spec (`m3-docs/components/chips/specs.md`) defines **4 variants**:
- *  - **assist**     — smart/automated actions; outlined; `outline` 1dp stroke.
- *  - **filter**     — filters for a collection; outlined; leading check when selected.
- *  - **input**      — discrete user input; outlined; trailing remove icon.
- *  - **suggestion** — product-generated suggestions; outlined; no icons.
+ * <!-- Input chip (tag/token) -->
+ * <moni-chip variant="input" removable icon="label">TypeScript</moni-chip>
  *
- * All variants share M3 measurements: 32dp height, 8dp corner, 18dp icon.
- * Container height scales with `size` (`small` = 32dp = M3 default,
- * `medium`/`large` are Moni extensions with larger touch targets).
+ * <!-- Assist chip with icon -->
+ * <moni-chip icon="directions_car">Get directions</moni-chip>
+ * ```
  *
- * **A11y** — `assist` and `suggestion` use `var(--outline)` for the
- * stroke to ensure 3:1 contrast (per `m3-docs/components/chips/accessibility.md`
- * § *Showing chip interactivity*). `filter` and `input` use `outline-variant`
- * for the resting state but show a clear `secondary-container` background
- * when selected, passing contrast.
+ * @slot default   - The chip label text.
+ * @slot icon      - Override for the leading icon (alternative to the `icon` attribute).
  *
- * Attributes:
- *  - variant:   assist (default) | filter | input | suggestion
- *               | outlined (alias for assist) | fill (alias for filter)
- *  - size:      small (default, 32dp = M3) | medium | large
- *  - shape:     round (default) | square | circle | no-round
- *               | left-round | right-round | top-round | bottom-round
- *  - selected:  present → background uses secondary-container (M3 filter/input)
- *  - removable: present → adds a trailing ✕ icon (M3 input chip, visual only)
- *  - disabled:  present → native disabled
- *  - loading:   present → shows indeterminate circular progress
- *  - icon:      Material Symbols name (leading icon)
+ * @csspart chip   - The inner `<button>` element.
+ * @csspart label  - The label `<span>` element.
  */
 let MoniChip = class MoniChip extends MoniElement {
     constructor() {

package/dist/components/moni-color-field.d.ts

@@ -1,11 +1,49 @@
+/**
+ * @file components/moni-color-field.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Visual-only color field. Renders a hidden `<input type="color">` plus a
- * preview swatch and a read-only text display of the current value.
+ * Material Design 3 Color Field component.
+ *
+ * A specialized text field for color input that combines a native
+ * `<input type="color">` with a read-only text display of the selected
+ * hex value, wrapped in the standard M3 field shell.
+ *
+ * **Visual architecture:**
+ * Extends the field styling pattern used by `<moni-text-field>`. The
+ * leading icon slot is replaced by a circular color swatch (`.swatch`)
+ * which is absolutely positioned over an invisible native color input.
+ * Clicking the swatch opens the system color picker. The text input portion
+ * displays the selected hex code and is strictly `readOnly`.
+ *
+ * **State syncing:**
+ * The component listens to the native `change` event on the color input,
+ * updates the `value` property, and re-dispatches a composed `'change'` event.
+ * It does not listen to `input` (continuous drag in the color picker) to avoid
+ * excessive event firing, but consumers can attach their own `input` listeners
+ * directly to the element if live preview is needed.
+ *
+ * @fires change - Bubbles and is composed. Fired when the color picker closes
+ *                 and the value is committed. Read `element.value`.
+ *
+ * @example
+ * ```html
+ * <moni-color-field
+ *   label="Theme Color"
+ *   name="primaryColor"
+ *   value="#6750a4"
+ *   variant="outlined"
+ * ></moni-color-field>
+ * ```
  *
- * Attributes:
- *  - name, label, value, variant, size, shape, disabled, helper, error,
- *    error-text, placeholder — see moni-text-field.
+ * @csspart field       - The outer `.field` div container.
+ * @csspart swatch      - The circular color preview element.
+ * @csspart input-color - The native, visually hidden `<input type="color">`.
+ * @csspart input-text  - The native `<input type="text">` displaying the hex code.
+ * @csspart label       - The floating `<label>` element.
  */
 export declare class MoniColorField extends MoniElement {
     name: string;
@@ -22,7 +60,7 @@ export declare class MoniColorField extends MoniElement {
     private _textInput;
     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-color-field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-color-field.d.ts","sourceRoot":"","sources":["../../src/components/moni-color-field.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAA6B,MAAM,kBAAkB,CAAC;AAE1E;;;;;;;GAOG;AACH,qBACa,cAAe,SAAQ,WAAW;IACjB,IAAI,SAAM;IACV,KAAK,SAAM;IACX,OAAO,EAAE,QAAQ,GAAG,UAAU,CAAc;IAEzE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAExD,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAc;IACR,QAAQ,UAAS;IAChC,MAAM,SAAM;IACa,SAAS,SAAM;IACzB,KAAK,UAAS;IAC7B,KAAK,SAAa;IAEjB,OAAO,CAAC,WAAW,CAAoB;IACxC,OAAO,CAAC,UAAU,CAAoB;IAE1D,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAW9C,OAAgB,MAAM,4BA0BpB;IAEO,MAAM;CAuDf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,kBAAkB,EAAE,cAAc,CAAC;KACnC;CACD;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"moni-color-field.d.ts","sourceRoot":"","sources":["../../src/components/moni-color-field.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,WAAW,EAA6B,MAAM,kBAAkB,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBACa,cAAe,SAAQ,WAAW;IACjB,IAAI,SAAM;IACV,KAAK,SAAM;IACX,OAAO,EAAE,QAAQ,GAAG,UAAU,CAAc;IAEzE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAExD,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAc;IACR,QAAQ,UAAS;IAChC,MAAM,SAAM;IACa,SAAS,SAAM;IACzB,KAAK,UAAS;IAC7B,KAAK,SAAa;IAEjB,OAAO,CAAC,WAAW,CAAoB;IACxC,OAAO,CAAC,UAAU,CAAoB;IAE1D,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAW9C,OAAgB,MAAM,4BA0BpB;IAEO,MAAM;CAuDf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,kBAAkB,EAAE,cAAc,CAAC;KACnC;CACD;AAED,eAAe,cAAc,CAAC"}

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

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-color-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);
@@ -10,12 +16,44 @@ import { ifDefined } from 'lit/directives/if-defined.js';
 import { classMap } from 'lit/directives/class-map.js';
 import { MoniElement, sharedStyles, fieldStyles } from './_base/index.js';
 /**
- * Visual-only color field. Renders a hidden `<input type="color">` plus a
- * preview swatch and a read-only text display of the current value.
+ * Material Design 3 Color Field component.
+ *
+ * A specialized text field for color input that combines a native
+ * `<input type="color">` with a read-only text display of the selected
+ * hex value, wrapped in the standard M3 field shell.
+ *
+ * **Visual architecture:**
+ * Extends the field styling pattern used by `<moni-text-field>`. The
+ * leading icon slot is replaced by a circular color swatch (`.swatch`)
+ * which is absolutely positioned over an invisible native color input.
+ * Clicking the swatch opens the system color picker. The text input portion
+ * displays the selected hex code and is strictly `readOnly`.
+ *
+ * **State syncing:**
+ * The component listens to the native `change` event on the color input,
+ * updates the `value` property, and re-dispatches a composed `'change'` event.
+ * It does not listen to `input` (continuous drag in the color picker) to avoid
+ * excessive event firing, but consumers can attach their own `input` listeners
+ * directly to the element if live preview is needed.
+ *
+ * @fires change - Bubbles and is composed. Fired when the color picker closes
+ *                 and the value is committed. Read `element.value`.
+ *
+ * @example
+ * ```html
+ * <moni-color-field
+ *   label="Theme Color"
+ *   name="primaryColor"
+ *   value="#6750a4"
+ *   variant="outlined"
+ * ></moni-color-field>
+ * ```
  *
- * Attributes:
- *  - name, label, value, variant, size, shape, disabled, helper, error,
- *    error-text, placeholder — see moni-text-field.
+ * @csspart field       - The outer `.field` div container.
+ * @csspart swatch      - The circular color preview element.
+ * @csspart input-color - The native, visually hidden `<input type="color">`.
+ * @csspart input-text  - The native `<input type="text">` displaying the hex code.
+ * @csspart label       - The floating `<label>` element.
  */
 let MoniColorField = class MoniColorField extends MoniElement {
     constructor() {

package/dist/components/moni-context-menu.d.ts

@@ -1,31 +1,53 @@
+/**
+ * @file components/moni-context-menu.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 import './moni-menu.js';
 /**
- * Context menu triggered by right-click on the parent element.
+ * Material Design 3 Context Menu component.
+ *
+ * A specialized menu that opens at the exact coordinates of a pointer event,
+ * typically triggered by a right-click (`contextmenu` event). It provides
+ * contextual actions related to the specific item clicked.
+ *
+ * **M3 spec reference:** `m3-docs/components/menus/specs.md` (Contextual menus)
+ *
+ * **Triggering mechanism:**
+ * The component does not require programmatic triggering via an `open` property.
+ * Instead, it attaches a `contextmenu` event listener to its parent element
+ * during `connectedCallback`. When the parent is right-clicked, the menu
+ * captures the `clientX`/`clientY` coordinates, prevents the default browser
+ * context menu, and opens itself at the cursor position using `position: fixed`.
  *
- * **Usage** (`m3-docs/components/menus/guidelines.md`): the menu opens at
- * the cursor's coordinates and flips to the opposite side if there isn't
- * enough space in the viewport.
+ * **Auto-flip behavior (`flip` attribute):**
+ * Per the M3 guidelines, menus should flip to the opposite side of the cursor
+ * if opening in the requested `placement` would cause them to overflow the
+ * viewport. When `flip=true`, the component dynamically calculates viewport
+ * bounds before opening and overrides `placement` if necessary (e.g., flipping
+ * from `bottom` to `top` if clicked near the bottom of the screen).
  *
- * **Wiring example**:
- *   ```html
- *   <div style="position: relative;">
- *     <moni-context-menu flip>
- *       <moni-menu-item>Cut</moni-menu-item>
- *       <moni-menu-item>Copy</moni-menu-item>
- *       <moni-menu-item>Paste</moni-menu-item>
- *     </moni-context-menu>
- *     Right-click anywhere in this div
- *   </div>
- *   ```
+ * **Auto-dismiss:**
+ * Closes automatically when clicking anywhere outside the menu, or when
+ * pressing the `Escape` key.
  *
- * Attributes:
- *  - placement: bottom (default) | top | left | right
- *  - flip:      present → auto-flip to opposite side if menu would overflow
- *               the viewport (M3 spec)
+ * @example
+ * ```html
+ * <!-- Wrap the trigger area and the menu in a container -->
+ * <div>
+ *   <p>Right-click me for options</p>
+ *   <moni-context-menu flip>
+ *     <moni-menu-item>Copy</moni-menu-item>
+ *     <moni-menu-item>Paste</moni-menu-item>
+ *     <moni-divider></moni-divider>
+ *     <moni-menu-item>Delete</moni-menu-item>
+ *   </moni-context-menu>
+ * </div>
+ * ```
  *
- * Slots:
- *  - default: menu items
+ * @slot default - The `<moni-menu-item>` elements that make up the menu.
  */
 export declare class MoniContextMenu extends MoniElement {
     placement: 'bottom' | 'top' | 'left' | 'right';
@@ -44,7 +66,7 @@ export declare class MoniContextMenu extends MoniElement {
     private _onDocumentClick;
     private _onDocKeydown;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/components/moni-context-menu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-context-menu.d.ts","sourceRoot":"","sources":["../../src/components/moni-context-menu.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBACa,eAAgB,SAAQ,WAAW;IAE/C,SAAS,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAY;IACd,IAAI,UAAS;IAEhD,OAAO,CAAC,EAAE,CAAK;IACf,OAAO,CAAC,EAAE,CAAK;IACf,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,kBAAkB,CAAiD;IAEhE,OAAO,CAAC,OAAO,CAAC,CAAc;IAElD,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,WAAW,CAA+C;IAEzD,iBAAiB;IAejB,oBAAoB;IAS7B,OAAO,CAAC,cAAc,CAcpB;IAEF,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,gBAAgB,CAItB;IAEF,OAAO,CAAC,aAAa,CAInB;IAEF,OAAgB,MAAM,4BAgBpB;IAEO,MAAM;CAmBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,mBAAmB,EAAE,eAAe,CAAC;KACrC;CACD;AAED,eAAe,eAAe,CAAC"}
+{"version":3,"file":"moni-context-menu.d.ts","sourceRoot":"","sources":["../../src/components/moni-context-menu.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBACa,eAAgB,SAAQ,WAAW;IAE/C,SAAS,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAY;IACd,IAAI,UAAS;IAEhD,OAAO,CAAC,EAAE,CAAK;IACf,OAAO,CAAC,EAAE,CAAK;IACf,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,kBAAkB,CAAiD;IAEhE,OAAO,CAAC,OAAO,CAAC,CAAc;IAElD,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,WAAW,CAA+C;IAEzD,iBAAiB;IAejB,oBAAoB;IAS7B,OAAO,CAAC,cAAc,CAcpB;IAEF,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,gBAAgB,CAItB;IAEF,OAAO,CAAC,aAAa,CAInB;IAEF,OAAgB,MAAM,4BAgBpB;IAEO,MAAM;CAmBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,mBAAmB,EAAE,eAAe,CAAC;KACrC;CACD;AAED,eAAe,eAAe,CAAC"}