@moni-labs/moni-ui 0.2.0 → 0.3.0

package/dist/components/moni-expansion.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-expansion.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,15 +14,45 @@ import { html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Visual-only expansion panel. Renders a `<details>` element.
+ * Material Design 3 Expansion panel component.
+ *
+ * A lightweight wrapper around the native HTML `<details>` and `<summary>`
+ * elements, styled according to M3 surface and elevation guidelines.
+ * Expansion panels contain creation flows and allow lightweight editing of an element.
+ *
+ * **Visual architecture:**
+ * The component renders a `<details>` element with a `<summary>` that acts
+ * as the expandable header. The default slot content is placed inside the
+ * `<details>` tag (but outside the `<summary>`), naturally hiding and showing
+ * based on the native behavior. An M3 `expand_more` icon is added via a CSS
+ * `::after` pseudo-element and rotates when the panel is open.
+ *
+ * **Usage:**
+ * Set the `title` attribute for a simple text header, or use the `summary`
+ * slot to project custom rich content (like icons or secondary text) into the
+ * header area.
+ *
+ * @example
+ * ```html
+ * <!-- Simple text title -->
+ * <moni-expansion title="Advanced Settings">
+ *   <p>Enable developer mode features here.</p>
+ * </moni-expansion>
  *
- * Attributes:
- *  - open: present → panel expanded
- *  - title: heading text for the summary
+ * <!-- Rich summary content via slot -->
+ * <moni-expansion open>
+ *   <div slot="summary" style="display: flex; gap: 8px;">
+ *     <moni-icon>person</moni-icon>
+ *     <span>Personal Information</span>
+ *   </div>
+ *   <form>
+ *     <moni-text-field label="Name"></moni-text-field>
+ *   </form>
+ * </moni-expansion>
+ * ```
  *
- * Slots:
- *  - default:  panel body
- *  - summary:  custom summary content (overrides title)
+ * @slot default - The content of the expansion panel body.
+ * @slot summary - Custom header content (overrides the `title` attribute).
  */
 let MoniExpansion = class MoniExpansion extends MoniElement {
     constructor() {

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

@@ -1,29 +1,48 @@
+/**
+ * @file components/moni-fab-menu.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 import './moni-fab.js';
 import './moni-icon.js';
 /**
- * Visual-only FAB menu. Combines a main `<moni-fab>` trigger with a `<menu>`
- * of secondary FABs (slotted via default slot).
+ * Material Design 3 FAB Menu component.
+ *
+ * A specialized container that combines a main `<moni-fab>` trigger with a
+ * `<menu>` of secondary FABs. It allows multiple actions to be tucked away
+ * behind a single primary Floating Action Button, reducing screen clutter.
+ *
+ * **M3 spec reference:** `m3-docs/components/floating-action-buttons/specs.md` (FAB menus)
+ *
+ * **Trigger and animation:**
+ * The component wires the primary trigger FAB's `click` event to toggle its
+ * internal `open` state. When `open=true`, the nested secondary FABs scale up
+ * and fade in via CSS transitions. Consumers can also control the `open` state
+ * programmatically by setting the attribute.
+ *
+ * **Focus management (Accessibility):**
+ * - When the menu opens, focus automatically moves to the first focusable
+ *   secondary item (or remains on the trigger if empty).
+ * - While open, the `Tab` key cycles focus strictly within the menu items to
+ *   prevent keyboard focus from escaping (focus trap).
+ * - Pressing `Escape` or clicking anywhere outside the menu closes it and
+ *   returns focus to the primary trigger FAB.
  *
- * The component wires the trigger's `click` to toggle the `open` attribute.
- * Consumers can also set/unset the attribute externally for programmatic
- * control. The menu scales and fades via CSS transitions.
+ * @example
+ * ```html
+ * <!-- Bottom-trailing FAB menu opening upwards -->
+ * <moni-fab-menu icon="add" color="tertiary" direction="up">
+ *   <moni-fab size="small" icon="edit" label="Draft"></moni-fab>
+ *   <moni-fab size="small" icon="photo_camera" label="Camera"></moni-fab>
+ * </moni-fab-menu>
+ * ```
  *
- * **Focus management** (M3 spec § FAB menu):
- *  - When `open` becomes true, focus moves to the first focusable item in
- *    the menu (or stays on the trigger if the menu is empty).
- *  - When `open` becomes false, focus returns to the trigger.
- *  - `Tab` cycles within the menu while open; `Escape` closes the menu.
- *  - Click outside the menu closes it.
+ * @slot default - The secondary `<moni-fab>` elements that appear when open.
  *
- * Attributes:
- *  - open:      present → menu is shown
- *  - icon:      Material Symbols name for the trigger
- *  - size:      small | medium (default) | large
- *  - color:     primary (default) | secondary | tertiary | surface
- *  - shape:     rounded (default) | circle
- *  - direction: up (default) | down | left | right
- *  - position:  same as moni-fab
+ * @csspart trigger - The primary `<moni-fab>` trigger element.
+ * @csspart menu    - The `<menu>` container holding the secondary items.
  */
 export declare class MoniFabMenu extends MoniElement {
     open: boolean;
@@ -47,7 +66,7 @@ export declare class MoniFabMenu extends MoniElement {
     private _handleDocKeydown;
     private _firstFocusableMenuItem;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-fab-menu.d.ts","sourceRoot":"","sources":["../../src/components/moni-fab-menu.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,eAAe,CAAC;AACvB,OAAO,gBAAgB,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBACa,WAAY,SAAQ,WAAW;IACC,IAAI,UAAS;IAC5B,IAAI,SAAS;IAE1C,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE9C,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAa;IAEpE,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAa;IAExC,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAQ;IAEnD,QAAQ,EACL,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,aAAa,CAAqB;IAElB,OAAO,CAAC,QAAQ,CAAW;IAC1B,OAAO,CAAC,KAAK,CAAe;IAEhD,OAAO,CAAC,kBAAkB,CAA4B;IACtD,OAAO,CAAC,WAAW,CAA8C;IACjE,OAAO,CAAC,aAAa,CAAmD;IAEzD,YAAY;IAQlB,oBAAoB;IAOpB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAOrD,OAAO,CAAC,eAAe,CAErB;IAEF,OAAO,CAAC,cAAc;IA0BtB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,uBAAuB;IAQ/B,OAAgB,MAAM,4BA8EpB;IAEO,MAAM;CAef;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,WAAW,CAAC;KAC7B;CACD;AAED,eAAe,WAAW,CAAC"}
+{"version":3,"file":"moni-fab-menu.d.ts","sourceRoot":"","sources":["../../src/components/moni-fab-menu.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,eAAe,CAAC;AACvB,OAAO,gBAAgB,CAAC;AAGxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBACa,WAAY,SAAQ,WAAW;IACC,IAAI,UAAS;IAC5B,IAAI,SAAS;IAE1C,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE9C,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAa;IAEpE,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAa;IAExC,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAQ;IAEnD,QAAQ,EACL,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,aAAa,CAAqB;IAElB,OAAO,CAAC,QAAQ,CAAW;IAC1B,OAAO,CAAC,KAAK,CAAe;IAEhD,OAAO,CAAC,kBAAkB,CAA4B;IACtD,OAAO,CAAC,WAAW,CAA8C;IACjE,OAAO,CAAC,aAAa,CAAmD;IAEzD,YAAY;IAQlB,oBAAoB;IAOpB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAOrD,OAAO,CAAC,eAAe,CAErB;IAEF,OAAO,CAAC,cAAc;IA0BtB,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,iBAAiB;IAQzB,OAAO,CAAC,uBAAuB;IAQ/B,OAAgB,MAAM,4BA8EpB;IAEO,MAAM;CAef;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,WAAW,CAAC;KAC7B;CACD;AAED,eAAe,WAAW,CAAC"}

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

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-fab-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);
@@ -10,28 +16,41 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-fab.js';
 import './moni-icon.js';
 /**
- * Visual-only FAB menu. Combines a main `<moni-fab>` trigger with a `<menu>`
- * of secondary FABs (slotted via default slot).
+ * Material Design 3 FAB Menu component.
+ *
+ * A specialized container that combines a main `<moni-fab>` trigger with a
+ * `<menu>` of secondary FABs. It allows multiple actions to be tucked away
+ * behind a single primary Floating Action Button, reducing screen clutter.
+ *
+ * **M3 spec reference:** `m3-docs/components/floating-action-buttons/specs.md` (FAB menus)
+ *
+ * **Trigger and animation:**
+ * The component wires the primary trigger FAB's `click` event to toggle its
+ * internal `open` state. When `open=true`, the nested secondary FABs scale up
+ * and fade in via CSS transitions. Consumers can also control the `open` state
+ * programmatically by setting the attribute.
+ *
+ * **Focus management (Accessibility):**
+ * - When the menu opens, focus automatically moves to the first focusable
+ *   secondary item (or remains on the trigger if empty).
+ * - While open, the `Tab` key cycles focus strictly within the menu items to
+ *   prevent keyboard focus from escaping (focus trap).
+ * - Pressing `Escape` or clicking anywhere outside the menu closes it and
+ *   returns focus to the primary trigger FAB.
  *
- * The component wires the trigger's `click` to toggle the `open` attribute.
- * Consumers can also set/unset the attribute externally for programmatic
- * control. The menu scales and fades via CSS transitions.
+ * @example
+ * ```html
+ * <!-- Bottom-trailing FAB menu opening upwards -->
+ * <moni-fab-menu icon="add" color="tertiary" direction="up">
+ *   <moni-fab size="small" icon="edit" label="Draft"></moni-fab>
+ *   <moni-fab size="small" icon="photo_camera" label="Camera"></moni-fab>
+ * </moni-fab-menu>
+ * ```
  *
- * **Focus management** (M3 spec § FAB menu):
- *  - When `open` becomes true, focus moves to the first focusable item in
- *    the menu (or stays on the trigger if the menu is empty).
- *  - When `open` becomes false, focus returns to the trigger.
- *  - `Tab` cycles within the menu while open; `Escape` closes the menu.
- *  - Click outside the menu closes it.
+ * @slot default - The secondary `<moni-fab>` elements that appear when open.
  *
- * Attributes:
- *  - open:      present → menu is shown
- *  - icon:      Material Symbols name for the trigger
- *  - size:      small | medium (default) | large
- *  - color:     primary (default) | secondary | tertiary | surface
- *  - shape:     rounded (default) | circle
- *  - direction: up (default) | down | left | right
- *  - position:  same as moni-fab
+ * @csspart trigger - The primary `<moni-fab>` trigger element.
+ * @csspart menu    - The `<menu>` container holding the secondary items.
  */
 let MoniFabMenu = class MoniFabMenu extends MoniElement {
     constructor() {

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

@@ -1,28 +1,54 @@
+/**
+ * @file components/moni-fab.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Visual-only Floating Action Button.
- *
- * Material 3 Expressive update (May 2025):
- *  - `size="small"` is **no longer recommended** by M3. Use `medium` (40dp/56dp
- *    on M3 spec) or `large`. Deprecated in v0.3.1; will be removed in v1.0.
- *  - `shape="circle"` is **not part of M3**; M3 FABs are `rounded` with a 16dp
- *    corner radius (or `full` when on hover/focus). The M3 spec does not
- *    define a perfect-circle FAB. Deprecated in v0.3.1; will be removed in v1.0.
- *  - `color="surface"` is **no longer recommended** by M3. Use `primary`,
- *    `secondary`, or `tertiary` (and their container variants).
- *
- * Attributes:
- *  - size:      medium (default) | large  (small: deprecated)
- *  - color:     primary (default) | secondary | tertiary  (surface: deprecated)
- *  - shape:     rounded (default)  (circle: deprecated)
- *  - extended:  present → wider with label always visible
- *  - expanded:  present → force expanded
- *  - disabled:  present
- *  - icon:      Material Symbols name
- *  - label:     text when extended
- *  - position:  bottom-trailing (default) | bottom-leading
- *               | top-trailing | top-leading
+ * Material Design 3 Floating Action Button (FAB) component.
+ *
+ * FABs represent the primary, or most common, action on a screen. They appear
+ * in front of all screen content, typically as a circular shape with an icon in
+ * its center.
+ *
+ * **M3 spec reference:** `m3-docs/components/floating-action-buttons/specs.md`
+ *
+ * **M3 Expressive Updates & Deprecations (May 2025):**
+ * - `size="small"` is **no longer recommended** by M3. Use `medium` (40dp or 56dp)
+ *   or `large` (96dp). Deprecated in v0.3.1; will be removed in v1.0.
+ * - `shape="circle"` is **not part of M3**. M3 FABs use a `rounded` shape with a
+ *   16dp corner radius (which morphs to a `full` radius on hover/focus).
+ *   Deprecated in v0.3.1; will be removed in v1.0.
+ * - `color="surface"` is **no longer recommended**. Use `primary`, `secondary`,
+ *   or `tertiary` to ensure proper color mapping to the M3 theme.
+ *
+ * **Extended FABs:**
+ * When `extended` is true, the FAB displays a text label next to the icon.
+ * Extended FABs are wider and are typically used when the action needs explicit
+ * text to be clear. The `expanded` attribute forces the FAB to its full extended
+ * width, useful for animating between standard and extended states on scroll.
+ *
+ * **Positioning:**
+ * The `position` attribute applies predefined absolute/fixed positioning
+ * (e.g. `bottom-trailing`), snapping the FAB to standard screen corners.
+ *
+ * @example
+ * ```html
+ * <!-- Standard primary FAB -->
+ * <moni-fab icon="edit"></moni-fab>
+ *
+ * <!-- Extended tertiary FAB -->
+ * <moni-fab color="tertiary" extended icon="add" label="New task"></moni-fab>
+ *
+ * <!-- Positioned FAB -->
+ * <moni-fab position="bottom-trailing" icon="navigation"></moni-fab>
+ * ```
+ *
+ * @csspart button - The internal `<button>` element.
+ * @csspart icon   - The container for the icon.
+ * @csspart label  - The text label (only visible when extended).
  */
 export declare class MoniFab extends MoniElement {
     private static _deprecationWarned;
@@ -37,7 +63,7 @@ export declare class MoniFab extends MoniElement {
     position: 'bottom-trailing' | 'bottom-leading' | 'top-trailing' | 'top-leading';
     connectedCallback(): 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-fab.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-fab.d.ts","sourceRoot":"","sources":["../../src/components/moni-fab.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBACa,OAAQ,SAAQ,WAAW;IACvC,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAS;IAG1C,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE9C,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAa;IAEpE,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAa;IACI,QAAQ,UAAS;IACjB,QAAQ,UAAS;IACjB,QAAQ,UAAS;IAChC,IAAI,SAAS;IACb,KAAK,SAAM;IAExC,QAAQ,EACL,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,aAAa,CAAqB;IAE5B,iBAAiB,IAAI,IAAI;IAkBlC,OAAgB,MAAM,4BA6JpB;IAEO,MAAM;CAyBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,UAAU,EAAE,OAAO,CAAC;KACpB;CACD;AAED,eAAe,OAAO,CAAC"}
+{"version":3,"file":"moni-fab.d.ts","sourceRoot":"","sources":["../../src/components/moni-fab.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBACa,OAAQ,SAAQ,WAAW;IACvC,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAS;IAG1C,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE9C,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,CAAa;IAEpE,KAAK,EAAE,SAAS,GAAG,QAAQ,CAAa;IACI,QAAQ,UAAS;IACjB,QAAQ,UAAS;IACjB,QAAQ,UAAS;IAChC,IAAI,SAAS;IACb,KAAK,SAAM;IAExC,QAAQ,EACL,iBAAiB,GACjB,gBAAgB,GAChB,cAAc,GACd,aAAa,CAAqB;IAE5B,iBAAiB,IAAI,IAAI;IAkBlC,OAAgB,MAAM,4BA6JpB;IAEO,MAAM;CAyBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,UAAU,EAAE,OAAO,CAAC;KACpB;CACD;AAED,eAAe,OAAO,CAAC"}

package/dist/components/moni-fab.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-fab.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,28 +16,48 @@ import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Visual-only Floating Action Button.
+ * Material Design 3 Floating Action Button (FAB) component.
+ *
+ * FABs represent the primary, or most common, action on a screen. They appear
+ * in front of all screen content, typically as a circular shape with an icon in
+ * its center.
+ *
+ * **M3 spec reference:** `m3-docs/components/floating-action-buttons/specs.md`
+ *
+ * **M3 Expressive Updates & Deprecations (May 2025):**
+ * - `size="small"` is **no longer recommended** by M3. Use `medium` (40dp or 56dp)
+ *   or `large` (96dp). Deprecated in v0.3.1; will be removed in v1.0.
+ * - `shape="circle"` is **not part of M3**. M3 FABs use a `rounded` shape with a
+ *   16dp corner radius (which morphs to a `full` radius on hover/focus).
+ *   Deprecated in v0.3.1; will be removed in v1.0.
+ * - `color="surface"` is **no longer recommended**. Use `primary`, `secondary`,
+ *   or `tertiary` to ensure proper color mapping to the M3 theme.
+ *
+ * **Extended FABs:**
+ * When `extended` is true, the FAB displays a text label next to the icon.
+ * Extended FABs are wider and are typically used when the action needs explicit
+ * text to be clear. The `expanded` attribute forces the FAB to its full extended
+ * width, useful for animating between standard and extended states on scroll.
+ *
+ * **Positioning:**
+ * The `position` attribute applies predefined absolute/fixed positioning
+ * (e.g. `bottom-trailing`), snapping the FAB to standard screen corners.
+ *
+ * @example
+ * ```html
+ * <!-- Standard primary FAB -->
+ * <moni-fab icon="edit"></moni-fab>
+ *
+ * <!-- Extended tertiary FAB -->
+ * <moni-fab color="tertiary" extended icon="add" label="New task"></moni-fab>
  *
- * Material 3 Expressive update (May 2025):
- *  - `size="small"` is **no longer recommended** by M3. Use `medium` (40dp/56dp
- *    on M3 spec) or `large`. Deprecated in v0.3.1; will be removed in v1.0.
- *  - `shape="circle"` is **not part of M3**; M3 FABs are `rounded` with a 16dp
- *    corner radius (or `full` when on hover/focus). The M3 spec does not
- *    define a perfect-circle FAB. Deprecated in v0.3.1; will be removed in v1.0.
- *  - `color="surface"` is **no longer recommended** by M3. Use `primary`,
- *    `secondary`, or `tertiary` (and their container variants).
+ * <!-- Positioned FAB -->
+ * <moni-fab position="bottom-trailing" icon="navigation"></moni-fab>
+ * ```
  *
- * Attributes:
- *  - size:      medium (default) | large  (small: deprecated)
- *  - color:     primary (default) | secondary | tertiary  (surface: deprecated)
- *  - shape:     rounded (default)  (circle: deprecated)
- *  - extended:  present → wider with label always visible
- *  - expanded:  present → force expanded
- *  - disabled:  present
- *  - icon:      Material Symbols name
- *  - label:     text when extended
- *  - position:  bottom-trailing (default) | bottom-leading
- *               | top-trailing | top-leading
+ * @csspart button - The internal `<button>` element.
+ * @csspart icon   - The container for the icon.
+ * @csspart label  - The text label (only visible when extended).
  */
 let MoniFab = class MoniFab extends MoniElement {
     constructor() {

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

@@ -1,21 +1,61 @@
+/**
+ * @file components/moni-file-field.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Visual-only file field. Renders a hidden `<input type="file">` over a
- * read-only text input that shows the chosen file names.
+ * Material Design 3 File Field component.
+ *
+ * A specialized field component that provides a styled, accessible alternative
+ * to the native `<input type="file">`. It wraps a native file input inside
+ * the M3 `.field` shell and presents a read-only text input showing the
+ * selected file name(s) alongside a stylized "Choose file" action button.
+ *
+ * **Visual architecture:**
+ * The component leverages the `fieldStyles` CSS patterns. The internal DOM
+ * structure is specifically ordered as:
+ * `[text input] -> [label] -> [file input] -> [output]`
+ * This specific ordering ensures that the CSS adjacent sibling selector
+ * (`input + label`) can correctly float the label when the field is populated,
+ * even though the visible field is actually the read-only text input.
+ *
+ * **State management:**
+ * When the user selects files via the hidden file input, the component listens
+ * for the native `change` event, reads `input.files`, and updates the read-only
+ * text input with a comma-separated list of file names. The `value` property
+ * is kept in sync, and a composed `'change'` event is re-dispatched.
+ *
+ * @fires change - Bubbles and is composed. Fired when files are selected or
+ *                 cleared. The consumer can read the internal input's `files`
+ *                 list by querying the component.
+ *
+ * @example
+ * ```html
+ * <!-- Single file upload -->
+ * <moni-file-field
+ *   label="Profile picture"
+ *   name="avatar"
+ *   accept="image/png, image/jpeg"
+ *   button-label="Browse..."
+ * ></moni-file-field>
  *
- * The DOM order is `input[type=text], label, input[type=file], output` so
- * that the floating label CSS selector `input + label` lifts correctly even
- * though the visible field is the read-only text input.
+ * <!-- Multiple file upload with error state -->
+ * <moni-file-field
+ *   label="Documents"
+ *   multiple
+ *   error
+ *   error-text="Files exceed maximum size limit"
+ * ></moni-file-field>
+ * ```
  *
- * Attributes:
- *  - name, label, value, variant, size, shape, disabled, helper, error,
- *    error-text, placeholder — see moni-text-field.
- *  - accept:  forwarded to input.accept
- *  - multiple: present → input.multiple
- *  - button-label: text on the picker button (visual only, default: "Choose file")
- *  - icon:           leading Material Symbols name
- *  - trailing-icon:  trailing Material Symbols name
+ * @csspart field       - The outer `.field` div container.
+ * @csspart input-text  - The visible read-only `<input type="text">`.
+ * @csspart label       - The floating `<label>` element.
+ * @csspart input-file  - The hidden native `<input type="file">`.
+ * @csspart button      - The button element (styled via CSS `::file-selector-button`).
  */
 export declare class MoniFileField extends MoniElement {
     name: string;
@@ -36,7 +76,7 @@ export declare class MoniFileField extends MoniElement {
     private _fileInput;
     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-file-field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-file-field.d.ts","sourceRoot":"","sources":["../../src/components/moni-file-field.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAA6B,MAAM,kBAAkB,CAAC;AAC1E,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;GAgBG;AACH,qBACa,aAAc,SAAQ,WAAW;IAChB,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;IACvB,MAAM,SAAM;IACG,QAAQ,UAAS;IAE7D,WAAW,SAAiB;IACgB,QAAQ,UAAS;IAChC,MAAM,SAAM;IACa,SAAS,SAAM;IACzB,KAAK,UAAS;IAC7B,KAAK,SAAM;IACX,IAAI,SAAM;IACkB,YAAY,SACtD;IAEc,OAAO,CAAC,UAAU,CAAoB;IAE1D,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAO9C,OAAgB,MAAM,4BAepB;IAEO,MAAM;CAoEf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,iBAAiB,EAAE,aAAa,CAAC;KACjC;CACD;AAED,eAAe,aAAa,CAAC"}
+{"version":3,"file":"moni-file-field.d.ts","sourceRoot":"","sources":["../../src/components/moni-file-field.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,WAAW,EAA6B,MAAM,kBAAkB,CAAC;AAC1E,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,qBACa,aAAc,SAAQ,WAAW;IAChB,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;IACvB,MAAM,SAAM;IACG,QAAQ,UAAS;IAE7D,WAAW,SAAiB;IACgB,QAAQ,UAAS;IAChC,MAAM,SAAM;IACa,SAAS,SAAM;IACzB,KAAK,UAAS;IAC7B,KAAK,SAAM;IACX,IAAI,SAAM;IACkB,YAAY,SACtD;IAEc,OAAO,CAAC,UAAU,CAAoB;IAE1D,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAO9C,OAAgB,MAAM,4BAepB;IAEO,MAAM;CAoEf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,iBAAiB,EAAE,aAAa,CAAC;KACjC;CACD;AAED,eAAe,aAAa,CAAC"}

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

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-file-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);
@@ -11,21 +17,55 @@ import { classMap } from 'lit/directives/class-map.js';
 import { MoniElement, sharedStyles, fieldStyles } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Visual-only file field. Renders a hidden `<input type="file">` over a
- * read-only text input that shows the chosen file names.
+ * Material Design 3 File Field component.
+ *
+ * A specialized field component that provides a styled, accessible alternative
+ * to the native `<input type="file">`. It wraps a native file input inside
+ * the M3 `.field` shell and presents a read-only text input showing the
+ * selected file name(s) alongside a stylized "Choose file" action button.
+ *
+ * **Visual architecture:**
+ * The component leverages the `fieldStyles` CSS patterns. The internal DOM
+ * structure is specifically ordered as:
+ * `[text input] -> [label] -> [file input] -> [output]`
+ * This specific ordering ensures that the CSS adjacent sibling selector
+ * (`input + label`) can correctly float the label when the field is populated,
+ * even though the visible field is actually the read-only text input.
+ *
+ * **State management:**
+ * When the user selects files via the hidden file input, the component listens
+ * for the native `change` event, reads `input.files`, and updates the read-only
+ * text input with a comma-separated list of file names. The `value` property
+ * is kept in sync, and a composed `'change'` event is re-dispatched.
+ *
+ * @fires change - Bubbles and is composed. Fired when files are selected or
+ *                 cleared. The consumer can read the internal input's `files`
+ *                 list by querying the component.
+ *
+ * @example
+ * ```html
+ * <!-- Single file upload -->
+ * <moni-file-field
+ *   label="Profile picture"
+ *   name="avatar"
+ *   accept="image/png, image/jpeg"
+ *   button-label="Browse..."
+ * ></moni-file-field>
  *
- * The DOM order is `input[type=text], label, input[type=file], output` so
- * that the floating label CSS selector `input + label` lifts correctly even
- * though the visible field is the read-only text input.
+ * <!-- Multiple file upload with error state -->
+ * <moni-file-field
+ *   label="Documents"
+ *   multiple
+ *   error
+ *   error-text="Files exceed maximum size limit"
+ * ></moni-file-field>
+ * ```
  *
- * Attributes:
- *  - name, label, value, variant, size, shape, disabled, helper, error,
- *    error-text, placeholder — see moni-text-field.
- *  - accept:  forwarded to input.accept
- *  - multiple: present → input.multiple
- *  - button-label: text on the picker button (visual only, default: "Choose file")
- *  - icon:           leading Material Symbols name
- *  - trailing-icon:  trailing Material Symbols name
+ * @csspart field       - The outer `.field` div container.
+ * @csspart input-text  - The visible read-only `<input type="text">`.
+ * @csspart label       - The floating `<label>` element.
+ * @csspart input-file  - The hidden native `<input type="file">`.
+ * @csspart button      - The button element (styled via CSS `::file-selector-button`).
  */
 let MoniFileField = class MoniFileField extends MoniElement {
     constructor() {