@moni-labs/moni-ui 0.2.0 → 0.3.0

package/dist/components/moni-loading-indicator.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-loading-indicator.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,18 +15,39 @@ import { customElement, property, query } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import { loadingIndicatorPolygons } from './loading-shapes.js';
 /**
- * Shape-shifting indeterminate loading indicator based on Material 3 Expressive spec.
+ * Material Design 3 Loading Indicator component.
+ *
+ * An indeterminate loading indicator that visually represents an unspecified
+ * wait time. Unlike standard circular spinners, this component uses a morphing
+ * polygon animation that shifts between shapes (circle, rounded square, etc.)
+ * in accordance with the high-fidelity M3 Expressive motion specifications.
+ *
+ * **Variants:**
+ * - `uncontained` (default) — A standalone morphing shape that inherits color
+ *   from its text context (or defaults to `primary`).
+ * - `contained` — The morphing shape is placed inside a circular container
+ *   with a distinct background color, useful for high-contrast loading states
+ *   or overlaying imagery.
+ *
+ * **Animation & Accessibility:**
+ * The component manages its own SVG `<animate>` tags. The animation is
+ * automatically started/stopped via `connectedCallback`/`disconnectedCallback`
+ * to save CPU cycles when the element is off-screen. It applies standard ARIA
+ * roles (`role="progressbar"`) and value attributes to ensure screen readers
+ * identify it correctly as an indeterminate loading state.
+ *
+ * @example
+ * ```html
+ * <!-- Uncontained indicator -->
+ * <moni-loading-indicator></moni-loading-indicator>
  *
- * Attributes:
- *  - variant: 'uncontained' (default) | 'contained'
+ * <!-- Contained indicator (default container is secondary-container) -->
+ * <moni-loading-indicator variant="contained"></moni-loading-indicator>
+ * ```
  *
- * CSS custom properties for customization:
- *  - --moni-loading-indicator-size: Size of the active indicator (default: 2.375rem)
- *  - --moni-loading-indicator-active-color: Active indicator color in uncontained mode (default: var(--primary))
- *  - --moni-loading-indicator-contained-active-color: Active indicator color in contained mode (default: var(--on-primary-container))
- *  - --moni-loading-indicator-contained-container-color: Background color of container in contained mode (default: var(--secondary-container))
- *  - --moni-loading-indicator-container-shape: Border radius of container in contained mode (default: 9999px)
- *  - --moni-loading-indicator-container-size: Container size (default: 3rem)
+ * @csspart container - The outer `.container` wrapper.
+ * @csspart svg       - The inner `<svg>` element.
+ * @csspart shape     - The `<path>` element that morphs.
  */
 let MoniLoadingIndicator = class MoniLoadingIndicator extends MoniElement {
     constructor() {

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

@@ -1,14 +1,37 @@
+/**
+ * @file components/moni-menu-item.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Visual-only menu item. Renders an `<li>` styled with the BeerCSS
- * `menu > li` rule.
+ * Material Design 3 Menu Item component.
+ *
+ * A single interactive item within a `<moni-menu>` or `<moni-context-menu>`.
+ * It provides standard M3 menu item styling, hover states, and optional
+ * leading icons.
+ *
+ * **M3 spec reference:** `m3-docs/components/menus/specs.md`
+ *
+ * **Interaction states:**
+ * - Hover: applies an opacity layer.
+ * - Active (`active=true`): applies a `tertiary-container` background highlight,
+ *   useful for indicating the currently selected option in a list.
+ * - Disabled (`disabled=true`): reduces opacity and disables pointer events.
+ *
+ * @example
+ * ```html
+ * <moni-menu-item icon="edit">Edit text</moni-menu-item>
+ * <moni-menu-item icon="content_copy" disabled>Copy</moni-menu-item>
+ * <moni-menu-item active>Currently selected</moni-menu-item>
+ * ```
+ *
+ * @slot default - The text label for the menu item.
  *
- * Attributes:
- *  - active:    present → tertiary-container highlight
- *  - disabled:  present
- *  - icon:      Material Symbols name
- *  - label:     item text
+ * @csspart item - The outer `<li>` element.
+ * @csspart icon - The container for the leading icon.
  */
 export declare class MoniMenuItem extends MoniElement {
     active: boolean;
@@ -16,7 +39,7 @@ export declare class MoniMenuItem extends MoniElement {
     icon: string;
     label: 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-menu-item.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-menu-item.d.ts","sourceRoot":"","sources":["../../src/components/moni-menu-item.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;GASG;AACH,qBACa,YAAa,SAAQ,WAAW;IACA,MAAM,UAAS;IACf,QAAQ,UAAS;IAChC,IAAI,SAAM;IACV,KAAK,SAAM;IAExC,OAAgB,MAAM,4BA4CpB;IAEO,MAAM;CAQf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,gBAAgB,EAAE,YAAY,CAAC;KAC/B;CACD;AAED,eAAe,YAAY,CAAC"}
+{"version":3,"file":"moni-menu-item.d.ts","sourceRoot":"","sources":["../../src/components/moni-menu-item.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBACa,YAAa,SAAQ,WAAW;IACA,MAAM,UAAS;IACf,QAAQ,UAAS;IAChC,IAAI,SAAM;IACV,KAAK,SAAM;IAExC,OAAgB,MAAM,4BA4CpB;IAEO,MAAM;CAQf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,gBAAgB,EAAE,YAAY,CAAC;KAC/B;CACD;AAED,eAAe,YAAY,CAAC"}

package/dist/components/moni-menu-item.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-menu-item.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,31 @@ import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Visual-only menu item. Renders an `<li>` styled with the BeerCSS
- * `menu > li` rule.
+ * Material Design 3 Menu Item component.
+ *
+ * A single interactive item within a `<moni-menu>` or `<moni-context-menu>`.
+ * It provides standard M3 menu item styling, hover states, and optional
+ * leading icons.
+ *
+ * **M3 spec reference:** `m3-docs/components/menus/specs.md`
+ *
+ * **Interaction states:**
+ * - Hover: applies an opacity layer.
+ * - Active (`active=true`): applies a `tertiary-container` background highlight,
+ *   useful for indicating the currently selected option in a list.
+ * - Disabled (`disabled=true`): reduces opacity and disables pointer events.
+ *
+ * @example
+ * ```html
+ * <moni-menu-item icon="edit">Edit text</moni-menu-item>
+ * <moni-menu-item icon="content_copy" disabled>Copy</moni-menu-item>
+ * <moni-menu-item active>Currently selected</moni-menu-item>
+ * ```
+ *
+ * @slot default - The text label for the menu item.
  *
- * Attributes:
- *  - active:    present → tertiary-container highlight
- *  - disabled:  present
- *  - icon:      Material Symbols name
- *  - label:     item text
+ * @csspart item - The outer `<li>` element.
+ * @csspart icon - The container for the leading icon.
  */
 let MoniMenuItem = class MoniMenuItem extends MoniElement {
     constructor() {

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

@@ -1,37 +1,62 @@
+/**
+ * @file components/moni-menu.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Menu that faithfully ports BeerCSS's `menu` styles.
- *
- * BeerCSS uses a plain `<menu>` with class `.active` toggled by JS —
- * NO Popover API. The menu positions itself as `position: absolute`
- * relative to the nearest positioned ancestor.
- *
- * Shadow DOM note: we keep :host as `display: contents` so the inner
- * `<menu>` can position relative to the consumer's layout context.
- * The consumer must have `position: relative` on the trigger's wrapper.
- *
- * **M3 spec** (`m3-docs/components/menus/guidelines.md`): menus should
- * auto-flip to the opposite side when there isn't enough viewport space
- * in the requested placement.
- *
- * **Flip implementation** (P4.3):
- *  - Modern browsers (Chrome 125+, Edge 125+, Safari 18+): uses CSS
- *    `@position-try-fallback` (Baseline 2024) when `flip` is set.
- *  - Older browsers (Firefox, Safari < 18): JS polyfill. After the menu
- *    becomes active, we measure the inner `<menu>` rect; if it overflows
- *    the viewport on the requested side, we set `_resolvedPlacement`
- *    to the opposite side and the CSS picks up the change.
- *
- * Attributes:
- *  - placement:  bottom (default) | top | left | right | min | max
- *  - no-wrap:    present
- *  - space:      no-space | space | small-space | medium-space | large-space | extra-space
- *  - active:     present → menu is visible
- *  - flip:       present → enable auto-flip when there is no viewport space
- *                (works on all browsers; CSS-native when supported)
- *
- * Slots:
- *  - default: menu items (moni-menu-item or li elements)
+ * Material Design 3 Menu component.
+ *
+ * Menus display a list of choices on a temporary surface. They appear when
+ * users interact with a button, action, or other control.
+ *
+ * **M3 spec reference:** `m3-docs/components/menus/guidelines.md`
+ *
+ * **Positioning architecture:**
+ * The menu uses `position: absolute` relative to its nearest positioned
+ * ancestor. The component's `:host` uses `display: contents`, meaning the
+ * inner `<menu>` element directly participates in the consumer's layout context.
+ * **Crucial:** The consumer must apply `position: relative` to the wrapper
+ * element that contains both the trigger and the `<moni-menu>`.
+ *
+ * **Auto-flip positioning:**
+ * Per M3 guidelines, menus should flip to the opposite side of the anchor
+ * if they overflow the viewport.
+ * - **Modern browsers (Chrome/Edge 125+, Safari 18+):** Uses CSS anchor
+ *   positioning and `@position-try-fallback` natively when `flip=true`.
+ * - **Fallback:** A JavaScript polyfill measures the menu after it opens. If
+ *   it overflows the requested `placement`, it sets an internal state to flip
+ *   the placement classes.
+ *
+ * **State management:**
+ * The `active` attribute controls visibility. Consumers must listen to trigger
+ * events (like `click`) and toggle the `active` property.
+ *
+ * @example
+ * ```html
+ * <!-- Wrapper must have position: relative -->
+ * <div style="position: relative; display: inline-block;">
+ *   <moni-button id="menu-trigger">Open Menu</moni-button>
+ *
+ *   <moni-menu placement="bottom" flip id="my-menu">
+ *     <moni-menu-item icon="edit">Edit</moni-menu-item>
+ *     <moni-menu-item icon="content_copy">Copy</moni-menu-item>
+ *     <moni-divider></moni-divider>
+ *     <moni-menu-item icon="delete">Delete</moni-menu-item>
+ *   </moni-menu>
+ * </div>
+ *
+ * <script>
+ *   const btn = document.getElementById('menu-trigger');
+ *   const menu = document.getElementById('my-menu');
+ *   btn.addEventListener('click', () => menu.active = !menu.active);
+ * </script>
+ * ```
+ *
+ * @slot default - `<moni-menu-item>`, `<moni-divider>`, or raw `<li>` elements.
+ *
+ * @csspart menu - The inner `<menu>` container.
  */
 export declare class MoniMenu extends MoniElement {
     placement: 'bottom' | 'top' | 'left' | 'right' | 'min' | 'max';
@@ -44,7 +69,7 @@ export declare class MoniMenu extends MoniElement {
     updated(changed: Map<string, unknown>): void;
     private _maybeFlip;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-menu.d.ts","sourceRoot":"","sources":["../../src/components/moni-menu.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBACa,QAAS,SAAQ,WAAW;IAExC,SAAS,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,KAAK,CAAY;IACR,MAAM,UAAS;IACrC,MAAM,UAAS;IAE3D,KAAK,EACF,UAAU,GACV,OAAO,GACP,aAAa,GACb,cAAc,GACd,aAAa,GACb,aAAa,CAAc;IACc,IAAI,UAAS;IAEhD,OAAO,CAAC,kBAAkB,CAMf;IAEL,OAAO,CAAC,OAAO,CAAC,CAAc;IAEpC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAS9C,OAAO,CAAC,UAAU;IAuBlB,OAAgB,MAAM,4BAkKpB;IAEO,MAAM;CAkBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,WAAW,EAAE,QAAQ,CAAC;KACtB;CACD;AAED,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"moni-menu.d.ts","sourceRoot":"","sources":["../../src/components/moni-menu.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,qBACa,QAAS,SAAQ,WAAW;IAExC,SAAS,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,KAAK,CAAY;IACR,MAAM,UAAS;IACrC,MAAM,UAAS;IAE3D,KAAK,EACF,UAAU,GACV,OAAO,GACP,aAAa,GACb,cAAc,GACd,aAAa,GACb,aAAa,CAAc;IACc,IAAI,UAAS;IAEhD,OAAO,CAAC,kBAAkB,CAMf;IAEL,OAAO,CAAC,OAAO,CAAC,CAAc;IAEpC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAS9C,OAAO,CAAC,UAAU;IAuBlB,OAAgB,MAAM,4BAkKpB;IAEO,MAAM;CAkBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,WAAW,EAAE,QAAQ,CAAC;KACtB;CACD;AAED,eAAe,QAAQ,CAAC"}

package/dist/components/moni-menu.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-menu.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -8,38 +14,57 @@ import { html, css } from 'lit';
 import { customElement, property, query, state } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Menu that faithfully ports BeerCSS's `menu` styles.
+ * Material Design 3 Menu component.
+ *
+ * Menus display a list of choices on a temporary surface. They appear when
+ * users interact with a button, action, or other control.
+ *
+ * **M3 spec reference:** `m3-docs/components/menus/guidelines.md`
+ *
+ * **Positioning architecture:**
+ * The menu uses `position: absolute` relative to its nearest positioned
+ * ancestor. The component's `:host` uses `display: contents`, meaning the
+ * inner `<menu>` element directly participates in the consumer's layout context.
+ * **Crucial:** The consumer must apply `position: relative` to the wrapper
+ * element that contains both the trigger and the `<moni-menu>`.
+ *
+ * **Auto-flip positioning:**
+ * Per M3 guidelines, menus should flip to the opposite side of the anchor
+ * if they overflow the viewport.
+ * - **Modern browsers (Chrome/Edge 125+, Safari 18+):** Uses CSS anchor
+ *   positioning and `@position-try-fallback` natively when `flip=true`.
+ * - **Fallback:** A JavaScript polyfill measures the menu after it opens. If
+ *   it overflows the requested `placement`, it sets an internal state to flip
+ *   the placement classes.
  *
- * BeerCSS uses a plain `<menu>` with class `.active` toggled by JS —
- * NO Popover API. The menu positions itself as `position: absolute`
- * relative to the nearest positioned ancestor.
+ * **State management:**
+ * The `active` attribute controls visibility. Consumers must listen to trigger
+ * events (like `click`) and toggle the `active` property.
  *
- * Shadow DOM note: we keep :host as `display: contents` so the inner
- * `<menu>` can position relative to the consumer's layout context.
- * The consumer must have `position: relative` on the trigger's wrapper.
+ * @example
+ * ```html
+ * <!-- Wrapper must have position: relative -->
+ * <div style="position: relative; display: inline-block;">
+ *   <moni-button id="menu-trigger">Open Menu</moni-button>
  *
- * **M3 spec** (`m3-docs/components/menus/guidelines.md`): menus should
- * auto-flip to the opposite side when there isn't enough viewport space
- * in the requested placement.
+ *   <moni-menu placement="bottom" flip id="my-menu">
+ *     <moni-menu-item icon="edit">Edit</moni-menu-item>
+ *     <moni-menu-item icon="content_copy">Copy</moni-menu-item>
+ *     <moni-divider></moni-divider>
+ *     <moni-menu-item icon="delete">Delete</moni-menu-item>
+ *   </moni-menu>
+ * </div>
  *
- * **Flip implementation** (P4.3):
- *  - Modern browsers (Chrome 125+, Edge 125+, Safari 18+): uses CSS
- *    `@position-try-fallback` (Baseline 2024) when `flip` is set.
- *  - Older browsers (Firefox, Safari < 18): JS polyfill. After the menu
- *    becomes active, we measure the inner `<menu>` rect; if it overflows
- *    the viewport on the requested side, we set `_resolvedPlacement`
- *    to the opposite side and the CSS picks up the change.
+ * <script>
+ *   const btn = document.getElementById('menu-trigger');
+ *   const menu = document.getElementById('my-menu');
+ *   btn.addEventListener('click', () => menu.active = !menu.active);
+ * </script>
+ * ```
  *
- * Attributes:
- *  - placement:  bottom (default) | top | left | right | min | max
- *  - no-wrap:    present
- *  - space:      no-space | space | small-space | medium-space | large-space | extra-space
- *  - active:     present → menu is visible
- *  - flip:       present → enable auto-flip when there is no viewport space
- *                (works on all browsers; CSS-native when supported)
+ * @slot default - `<moni-menu-item>`, `<moni-divider>`, or raw `<li>` elements.
  *
- * Slots:
- *  - default: menu items (moni-menu-item or li elements)
+ * @csspart menu - The inner `<menu>` container.
  */
 let MoniMenu = class MoniMenu extends MoniElement {
     constructor() {

package/dist/components/moni-morph-modal.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-morph-modal.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 import './moni-icon.js';
 type Placement = 'center' | 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end' | 'viewport-center' | 'viewport-top' | 'viewport-bottom' | 'viewport-left' | 'viewport-right' | 'viewport-top-left' | 'viewport-top-right' | 'viewport-bottom-left' | 'viewport-bottom-right';
@@ -67,7 +73,7 @@ export declare class MoniMorphModal extends MoniElement {
     private _computeFinalRect;
     private _parseSize;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/components/moni-morph-modal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-morph-modal.d.ts","sourceRoot":"","sources":["../../src/components/moni-morph-modal.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAI7D,OAAO,gBAAgB,CAAC;AAQxB,KAAK,SAAS,GACX,QAAQ,GACR,KAAK,GACL,WAAW,GACX,SAAS,GACT,QAAQ,GACR,cAAc,GACd,YAAY,GACZ,MAAM,GACN,YAAY,GACZ,UAAU,GACV,OAAO,GACP,aAAa,GACb,WAAW,GACX,iBAAiB,GACjB,cAAc,GACd,iBAAiB,GACjB,eAAe,GACf,gBAAgB,GAChB,mBAAmB,GACnB,oBAAoB,GACpB,sBAAsB,GACtB,uBAAuB,CAAC;AAgD3B,qBACa,cAAe,SAAQ,WAAW;IACjB,MAAM,SAAM;IACuB,IAAI,UAAS;IACb,KAAK,UAAQ;IAChD,SAAS,EAAE,SAAS,CAAY;IACH,aAAa,SAC9D;IACkD,cAAc,SAChE;IAET,mBAAmB,UAAQ;IAE3B,UAAU,UAAQ;IAElB,eAAe,UAAS;IAExB,UAAU,UAAS;IAEnB,kBAAkB,SAAM;IAExB,WAAW,UAAQ;IAEnB,UAAU,UAAS;IAEnB,WAAW,UAAS;IAEH,OAAO,CAAC,MAAM,CAAkB;IAC1B,OAAO,CAAC,MAAM,CAAkB;IACnC,OAAO,CAAC,SAAS,CAAkB;IACtC,OAAO,CAAC,OAAO,CAAe;IAEtC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,gBAAgB,CAAS;IAE1C,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,SAAS,CAA6C;IAC9D,OAAO,CAAC,MAAM,CAAC,UAAU,CAAwB;IACjD,OAAO,CAAC,kBAAkB,CAA8D;IAExF,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,aAAa,CAAmD;IACxE,OAAO,CAAC,WAAW,CAKjB;IAEO,iBAAiB,IAAI,IAAI;IAOzB,oBAAoB,IAAI,IAAI;IAiB5B,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAW9C,OAAO,CAAC,cAAc;IAgBtB,IAAI,IAAI,IAAI;IAkKZ,OAAO,CAAC,2BAA2B;IAgBnC,IAAI,IAAI,IAAI;IA0JZ,MAAM,IAAI,IAAI;IAKd,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,kBAAkB;IA4B1B,OAAO,CAAC,qBAAqB;IA6B7B,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,yBAAyB;IAKjC,OAAO,CAAC,qBAAqB;IAO7B,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,gBAAgB;IA2BxB,OAAO,CAAC,gBAAgB;IAqDxB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,mBAAmB;IAoF3B,OAAO,CAAC,sBAAsB;IA2C9B,OAAO,CAAC,sBAAsB;IAmC9B,OAAO,CAAC,oBAAoB;IAqB5B,OAAO,CAAC,eAAe;IAiDvB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,iBAAiB;IAuIzB,OAAO,CAAC,UAAU;IAYlB,OAAgB,MAAM,4BAqHpB;IAEO,MAAM;CA4Cf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,kBAAkB,EAAE,cAAc,CAAC;KACnC;CACD;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"moni-morph-modal.d.ts","sourceRoot":"","sources":["../../src/components/moni-morph-modal.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAI7D,OAAO,gBAAgB,CAAC;AAQxB,KAAK,SAAS,GACX,QAAQ,GACR,KAAK,GACL,WAAW,GACX,SAAS,GACT,QAAQ,GACR,cAAc,GACd,YAAY,GACZ,MAAM,GACN,YAAY,GACZ,UAAU,GACV,OAAO,GACP,aAAa,GACb,WAAW,GACX,iBAAiB,GACjB,cAAc,GACd,iBAAiB,GACjB,eAAe,GACf,gBAAgB,GAChB,mBAAmB,GACnB,oBAAoB,GACpB,sBAAsB,GACtB,uBAAuB,CAAC;AA2E3B,qBACa,cAAe,SAAQ,WAAW;IACjB,MAAM,SAAM;IACuB,IAAI,UAAS;IACb,KAAK,UAAQ;IAChD,SAAS,EAAE,SAAS,CAAY;IACH,aAAa,SAC9D;IACkD,cAAc,SAChE;IAET,mBAAmB,UAAQ;IAE3B,UAAU,UAAQ;IAElB,eAAe,UAAS;IAExB,UAAU,UAAS;IAEnB,kBAAkB,SAAM;IAExB,WAAW,UAAQ;IAEnB,UAAU,UAAS;IAEnB,WAAW,UAAS;IAEH,OAAO,CAAC,MAAM,CAAkB;IAC1B,OAAO,CAAC,MAAM,CAAkB;IACnC,OAAO,CAAC,SAAS,CAAkB;IACtC,OAAO,CAAC,OAAO,CAAe;IAEtC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,gBAAgB,CAAS;IAE1C,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,mBAAmB,CAAS;IACpC,OAAO,CAAC,OAAO,CAAO;IACtB,OAAO,CAAC,SAAS,CAA6C;IAC9D,OAAO,CAAC,MAAM,CAAC,UAAU,CAAwB;IACjD,OAAO,CAAC,kBAAkB,CAA8D;IAExF,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,aAAa,CAAmD;IACxE,OAAO,CAAC,WAAW,CAKjB;IAEO,iBAAiB,IAAI,IAAI;IAOzB,oBAAoB,IAAI,IAAI;IAiB5B,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAW9C,OAAO,CAAC,cAAc;IAgBtB,IAAI,IAAI,IAAI;IAkKZ,OAAO,CAAC,2BAA2B;IAgBnC,IAAI,IAAI,IAAI;IA0JZ,MAAM,IAAI,IAAI;IAKd,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,kBAAkB;IA4B1B,OAAO,CAAC,qBAAqB;IA6B7B,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,mBAAmB;IAK3B,OAAO,CAAC,yBAAyB;IAKjC,OAAO,CAAC,qBAAqB;IAO7B,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,qBAAqB;IAW7B,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,gBAAgB;IA2BxB,OAAO,CAAC,gBAAgB;IAqDxB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,mBAAmB;IAoF3B,OAAO,CAAC,sBAAsB;IA2C9B,OAAO,CAAC,sBAAsB;IAmC9B,OAAO,CAAC,oBAAoB;IAqB5B,OAAO,CAAC,eAAe;IAiDvB,OAAO,CAAC,mBAAmB;IAY3B,OAAO,CAAC,UAAU;IAOlB,OAAO,CAAC,iBAAiB;IAuIzB,OAAO,CAAC,UAAU;IAYlB,OAAgB,MAAM,4BAqHpB;IAEO,MAAM;CA4Cf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,kBAAkB,EAAE,cAAc,CAAC;KACnC;CACD;AAED,eAAe,cAAc,CAAC"}

package/dist/components/moni-morph-modal.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-morph-modal.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);
@@ -16,33 +22,49 @@ gsap.registerPlugin(Flip, CustomEase);
 CustomEase.create('morph-open', '0.15, 0.85, 0.2, 1');
 CustomEase.create('morph-close', '0.4, 0, 0.2, 1');
 /**
- * Morph-modal: abre un panel Material Design 3 a partir de cualquier elemento
- * del DOM usando una animación FLIP (First / Last / Invert / Play) con GSAP.
+ * Material Design 3 Morph Modal component.
+ *
+ * A highly interactive dialog that uses GSAP FLIP (First, Last, Invert, Play)
+ * animations to seamlessly "morph" any clicked element on the page into a full
+ * modal surface, and morph it back when closed.
+ *
+ * **Motion choreography:**
+ * This component implements the complex M3 container transform pattern. When
+ * triggered, the source element visually expands into the modal. The modal's
+ * background color, border radius, and typography fade and cross-dissolve
+ * perfectly with the origin element.
+ *
+ * **Triggering mechanism:**
+ * Consumers must provide the `triggerEvent` property containing the original
+ * pointer/click `Event` that initiated the open action. The component extracts
+ * the `event.target` (or uses `clientX/Y` as a fallback) to determine the exact
+ * origin coordinates for the GSAP FLIP animation.
+ *
+ * **Dialog behavior:**
+ * Internally, it uses the native `<dialog>` element. It traps focus, supports
+ * `Escape` to close, and handles scrim/backdrop clicks (which trigger the
+ * reverse morph animation before actually closing the native dialog).
+ *
+ * @example
+ * ```html
+ * <moni-morph-modal id="myModal" title="Details">
+ *   <p>This modal morphed from the button you just clicked.</p>
+ * </moni-morph-modal>
  *
- * El elemento disparador (`target`) no se modifica estructuralmente; solo se
- * lee su rectángulo y estilos computados para hacer coincidir el punto inicial
- * de la morph-animation. El contenido del panel se declara dentro del propio
- * componente, de forma recursiva: dentro de un `<moni-morph-modal>` abierto se
- * puede declarar otro `<moni-morph-modal>` apuntando a un botón interior.
+ * <moni-button id="openBtn">Open Details</moni-button>
  *
- * Attributes:
- *  - target:               selector CSS del elemento disparador.
- *  - open:                 estado abierto/cerrado (reflejado).
- *  - modal:                si se muestra fondo oscuro (scrim).
- *  - placement:            posición final del panel expandido.
- *  - expanded-width:       ancho del panel (px, rem, %, vw).
- *  - expanded-height:      alto del panel (px, rem, %, vh).
- *  - close-on-click-outside: cierra al clicar fuera.
- *  - close-on-esc:         cierra con Escape.
- *  - show-close-button:    muestra una “X” en el header.
- *  - morph-label:          anima el label/icono del target hacia el header.
- *  - morph-label-selector: selector dentro del target para targets arbitrarios.
+ * <script>
+ *   const modal = document.getElementById('myModal');
+ *   document.getElementById('openBtn').addEventListener('click', (e) => {
+ *     modal.triggerEvent = e; // Pass the event so it knows where to morph from
+ *     modal.open = true;
+ *   });
+ * </script>
+ * ```
  *
- * Slots:
- *  - default: cuerpo del panel.
- *  - header:  encabezado.
- *  - footer:  acciones al pie.
- *  - trigger-label: contenido explícito a animar desde el target.
+ * @slot default - The main body content of the modal.
+ * @slot header  - Custom header content (overrides `title` attribute).
+ * @slot actions - Action buttons displayed at the bottom right.
  */
 const litBool = {
     fromAttribute: (value) => value !== 'false' && value !== null,

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

@@ -1,15 +1,55 @@
+/**
+ * @file components/moni-nav-item.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Visual-only navigation item. Renders an `<a>` styled with the BeerCSS
- * nav link helper.
- *
- * Attributes:
- *  - href:     link target
- *  - target:   link target
- *  - icon:     Material Symbols name
- *  - label:    link text
- *  - active:   present → active style
+ * Material Design 3 Navigation Item component.
+ *
+ * A single destination item within a `<moni-nav>` container. Renders as an
+ * accessible `<a>` element with an icon, label, and M3 state layer.
+ *
+ * **M3 spec references:**
+ * - Navigation bar item: `m3-docs/components/navigation-bar/specs.md`
+ * - Navigation rail item: `m3-docs/components/navigation-rail/specs.md`
+ * - Navigation drawer item: `m3-docs/components/navigation-drawer/specs.md`
+ *
+ * **Layout adaptation:**
+ * The `placement`, `variant`, and `layout` properties are forwarded from
+ * the parent `<moni-nav>` (typically via attribute binding in the parent's
+ * render method). The nav item uses these to conditionally render:
+ * - Icon + label below (navigation bar).
+ * - Icon only + horizontal label (rail).
+ * - Icon + full label (drawer).
+ *
+ * **Responsive behavior:**
+ * Uses `window.matchMedia('(min-width: 601px)')` to detect medium screens
+ * and stores the result in `_isMediumScreen`. This drives automatic layout
+ * switching between bar and rail styles.
+ *
+ * **Active state:**
+ * The `active` attribute applies the M3 active indicator: a pill-shaped
+ * `secondary-container` background behind the icon and a darker label color.
+ *
+ * @example
+ * ```html
+ * <moni-nav placement="bottom">
+ *   <moni-nav-item href="/" icon="home" label="Home" active></moni-nav-item>
+ *   <moni-nav-item href="/search" icon="search" label="Search"></moni-nav-item>
+ *   <moni-nav-item href="/profile" icon="person" label="Profile">
+ *     <moni-badge value="3"></moni-badge>  <!-- notification badge -->
+ *   </moni-nav-item>
+ * </moni-nav>
+ * ```
+ *
+ * @slot default - Additional content slotted after the icon (e.g. `<moni-badge>`).
+ *
+ * @csspart item   - The outer `<a>` element.
+ * @csspart icon   - The icon container.
+ * @csspart label  - The label text element.
  */
 export declare class MoniNavItem extends MoniElement {
     href: string;
@@ -27,7 +67,7 @@ export declare class MoniNavItem extends MoniElement {
     private _handleQueryChange;
     get computedLayout(): 'vertical' | 'horizontal';
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-nav-item.d.ts","sourceRoot":"","sources":["../../src/components/moni-nav-item.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;GAUG;AACH,qBACa,WAAY,SAAQ,WAAW;IACd,IAAI,SAAO;IACX,MAAM,SAAM;IACZ,IAAI,SAAM;IACV,KAAK,SAAM;IACI,MAAM,UAAS;IAC9B,SAAS,SAAS;IAClB,OAAO,SAAU;IACjB,MAAM,SAAU;IAG7C,OAAO,CAAC,eAAe,CAAS;IAEhC,OAAO,CAAC,MAAM,CAEN;IAEC,iBAAiB;IAQjB,oBAAoB;IAO7B,OAAO,CAAC,kBAAkB,CAExB;IAEF,IAAI,cAAc,IAAI,UAAU,GAAG,YAAY,CAQ9C;IAED,OAAgB,MAAM,4BAmIpB;IAEO,MAAM;CAqCf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,WAAW,CAAC;KAC7B;CACD;AAED,eAAe,WAAW,CAAC"}
+{"version":3,"file":"moni-nav-item.d.ts","sourceRoot":"","sources":["../../src/components/moni-nav-item.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBACa,WAAY,SAAQ,WAAW;IACd,IAAI,SAAO;IACX,MAAM,SAAM;IACZ,IAAI,SAAM;IACV,KAAK,SAAM;IACI,MAAM,UAAS;IAC9B,SAAS,SAAS;IAClB,OAAO,SAAU;IACjB,MAAM,SAAU;IAG7C,OAAO,CAAC,eAAe,CAAS;IAEhC,OAAO,CAAC,MAAM,CAEN;IAEC,iBAAiB;IAQjB,oBAAoB;IAO7B,OAAO,CAAC,kBAAkB,CAExB;IAEF,IAAI,cAAc,IAAI,UAAU,GAAG,YAAY,CAQ9C;IAED,OAAgB,MAAM,4BAmIpB;IAEO,MAAM;CAqCf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,WAAW,CAAC;KAC7B;CACD;AAED,eAAe,WAAW,CAAC"}

package/dist/components/moni-nav-item.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-nav-item.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,15 +16,49 @@ import { ifDefined } from 'lit/directives/if-defined.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Visual-only navigation item. Renders an `<a>` styled with the BeerCSS
- * nav link helper.
+ * Material Design 3 Navigation Item component.
+ *
+ * A single destination item within a `<moni-nav>` container. Renders as an
+ * accessible `<a>` element with an icon, label, and M3 state layer.
+ *
+ * **M3 spec references:**
+ * - Navigation bar item: `m3-docs/components/navigation-bar/specs.md`
+ * - Navigation rail item: `m3-docs/components/navigation-rail/specs.md`
+ * - Navigation drawer item: `m3-docs/components/navigation-drawer/specs.md`
+ *
+ * **Layout adaptation:**
+ * The `placement`, `variant`, and `layout` properties are forwarded from
+ * the parent `<moni-nav>` (typically via attribute binding in the parent's
+ * render method). The nav item uses these to conditionally render:
+ * - Icon + label below (navigation bar).
+ * - Icon only + horizontal label (rail).
+ * - Icon + full label (drawer).
+ *
+ * **Responsive behavior:**
+ * Uses `window.matchMedia('(min-width: 601px)')` to detect medium screens
+ * and stores the result in `_isMediumScreen`. This drives automatic layout
+ * switching between bar and rail styles.
+ *
+ * **Active state:**
+ * The `active` attribute applies the M3 active indicator: a pill-shaped
+ * `secondary-container` background behind the icon and a darker label color.
+ *
+ * @example
+ * ```html
+ * <moni-nav placement="bottom">
+ *   <moni-nav-item href="/" icon="home" label="Home" active></moni-nav-item>
+ *   <moni-nav-item href="/search" icon="search" label="Search"></moni-nav-item>
+ *   <moni-nav-item href="/profile" icon="person" label="Profile">
+ *     <moni-badge value="3"></moni-badge>  <!-- notification badge -->
+ *   </moni-nav-item>
+ * </moni-nav>
+ * ```
+ *
+ * @slot default - Additional content slotted after the icon (e.g. `<moni-badge>`).
  *
- * Attributes:
- *  - href:     link target
- *  - target:   link target
- *  - icon:     Material Symbols name
- *  - label:    link text
- *  - active:   present → active style
+ * @csspart item   - The outer `<a>` element.
+ * @csspart icon   - The icon container.
+ * @csspart label  - The label text element.
  */
 let MoniNavItem = class MoniNavItem extends MoniElement {
     constructor() {