@moni-labs/moni-ui 0.2.0 → 0.3.0

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

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-context-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);
@@ -9,31 +15,47 @@ import { customElement, property, state, query } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } 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.
  */
 let MoniContextMenu = class MoniContextMenu extends MoniElement {
     constructor() {

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

@@ -1,32 +1,124 @@
+/**
+ * @file components/moni-dialog.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Visual-only dialog. Renders a native `<dialog>` element. The consumer
- * opens/closes by calling the native `show()` / `showModal()` /
- * `close()` / `showPopover()` methods on the inner dialog via
- * `this.querySelector('dialog')` from the light DOM.
+ * Material Design 3 Dialog component.
+ *
+ * Dialogs inform users about a task and can contain critical information,
+ * require decisions, or involve multiple tasks. They interrupt the user's
+ * workflow and should be used sparingly.
+ *
+ * **M3 spec reference:** `m3-docs/components/dialogs/specs.md`
+ *
+ * **Implementation note — native `<dialog>` element:**
+ * This component wraps the native `<dialog>` HTML element. Opening and closing
+ * are controlled via the `open` attribute (and its JS property). The component
+ * syncs `open` changes to the native `<dialog>` in `updated()`:
+ * - `modal=true` → calls `dialog.showModal()` (blocks focus, adds backdrop).
+ * - `modal=false` → calls `dialog.show()` (non-blocking, no backdrop).
+ * - `open=false` → calls `dialog.close()`.
+ *
+ * **Placement (`side` attribute):**
+ * - `center` (default) — Centered in the viewport. Standard M3 dialog.
+ * - `top`, `right`, `bottom`, `left` — Edge-anchored panels (side sheet pattern).
+ * - `max` — Full-screen dialog for complex flows.
+ *
+ * @example
+ * ```html
+ * <!-- Basic modal dialog -->
+ * <moni-dialog open modal title="Delete item?" size="small">
+ *   <p>This action cannot be undone.</p>
+ *   <div slot="footer">
+ *     <moni-button variant="text">Cancel</moni-button>
+ *     <moni-button>Delete</moni-button>
+ *   </div>
+ * </moni-dialog>
+ * ```
  *
- * Attributes:
- *  - open:   present → dialog[open]
- *  - side:   center (default) | top | right | bottom | left | max
- *  - size:   small | medium (default) | large
- *  - modal:  present → adds the `modal` class (used by BeerCSS)
- *  - title:  header text
+ * @slot default - The dialog body content.
+ * @slot header  - Custom header content (overrides `title` attribute).
+ * @slot footer  - Action buttons row at the bottom of the dialog.
  *
- * Slots:
- *  - default: body
- *  - header:  title
- *  - footer:  action buttons
+ * @csspart dialog - The native `<dialog>` element.
+ * @csspart header - The header container.
+ * @csspart body   - The body content wrapper.
+ * @csspart footer - The footer actions wrapper.
  */
 export declare class MoniDialog extends MoniElement {
+    /**
+     * Controls the open/closed state of the dialog.
+     *
+     * When set to `true`, the component calls `dialog.showModal()` (if `modal`)
+     * or `dialog.show()`. When set to `false`, calls `dialog.close()`.
+     * Reflected as an HTML attribute for CSS and external state readers.
+     *
+     * @default false
+     */
     open: boolean;
+    /**
+     * When `true`, opens the dialog as a modal using `<dialog>.showModal()`.
+     *
+     * Modal dialogs:
+     * - Block keyboard focus from leaving the dialog.
+     * - Render a `::backdrop` scrim over the rest of the page.
+     * - Can be closed by pressing `Escape` (native browser behavior).
+     *
+     * When `false`, uses `<dialog>.show()` which is non-blocking (no focus trap
+     * and no backdrop).
+     *
+     * @default false
+     */
     modal: boolean;
+    /**
+     * Placement of the dialog within the viewport.
+     *
+     * - `'center'` (default) — Centered. Standard M3 dialog placement.
+     * - `'top'`    — Anchored to the top edge (drawer from top).
+     * - `'right'`  — Anchored to the right edge (side sheet pattern).
+     * - `'bottom'` — Anchored to the bottom edge (bottom sheet alternative).
+     * - `'left'`   — Anchored to the left edge (navigation drawer pattern).
+     * - `'max'`    — Full-screen (covers the entire viewport).
+     *
+     * @default 'center'
+     */
     side: 'center' | 'top' | 'right' | 'bottom' | 'left' | 'max';
+    /**
+     * Size of the dialog container.
+     *
+     * - `'small'`  — Narrow dialog; ideal for simple confirmations.
+     * - `'medium'` — Standard dialog width (default).
+     * - `'large'`  — Wide dialog; for forms or complex content.
+     *
+     * @default 'medium'
+     */
     size: 'small' | 'medium' | 'large';
+    /**
+     * Text displayed in the dialog header area.
+     *
+     * When non-empty, renders as a styled heading inside the header container.
+     * The `header` slot takes precedence over this attribute when both are present.
+     *
+     * @default ''
+     */
     title: string;
+    /** Direct reference to the native `<dialog>` element for programmatic access. */
     private _dialog;
+    /**
+     * Syncs the `open` and `modal` state to the native `<dialog>` element.
+     *
+     * Called by Lit after every render cycle where tracked properties change.
+     * Avoids calling `showModal()` or `show()` if the dialog is already open
+     * (prevents the `InvalidStateError` DOMException).
+     *
+     * @param changed - Map of changed property names to their previous values.
+     */
     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-dialog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-dialog.d.ts","sourceRoot":"","sources":["../../src/components/moni-dialog.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;GAiBG;AACH,qBACa,UAAW,SAAQ,WAAW;IACE,IAAI,UAAS;IACb,KAAK,UAAS;IAE1D,IAAI,EAAE,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAY;IAExE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IACjB,KAAK,SAAM;IAEvB,OAAO,CAAC,OAAO,CAAqB;IAE5C,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAoB9C,OAAgB,MAAM,4BAgKpB;IAEO,MAAM;CAef;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,aAAa,EAAE,UAAU,CAAC;KAC1B;CACD;AAED,eAAe,UAAU,CAAC"}
+{"version":3,"file":"moni-dialog.d.ts","sourceRoot":"","sources":["../../src/components/moni-dialog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBACa,UAAW,SAAQ,WAAW;IAC1C;;;;;;;;OAQG;IACyC,IAAI,UAAS;IAEzD;;;;;;;;;;;;OAYG;IACyC,KAAK,UAAS;IAE1D;;;;;;;;;;;OAWG;IAEH,IAAI,EAAE,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAY;IAExE;;;;;;;;OAQG;IAEH,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE9C;;;;;;;OAOG;IAC0B,KAAK,SAAM;IAExC,iFAAiF;IAChE,OAAO,CAAC,OAAO,CAAqB;IAErD;;;;;;;;OAQG;IACM,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAoB9C,OAAgB,MAAM,4BAgKpB;IAEO,MAAM;CAef;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,aAAa,EAAE,UAAU,CAAC;KAC1B;CACD;AAED,eAAe,UAAU,CAAC"}

package/dist/components/moni-dialog.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-dialog.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
     var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
     if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -8,32 +14,117 @@ import { html, css } from 'lit';
 import { customElement, property, query } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Visual-only dialog. Renders a native `<dialog>` element. The consumer
- * opens/closes by calling the native `show()` / `showModal()` /
- * `close()` / `showPopover()` methods on the inner dialog via
- * `this.querySelector('dialog')` from the light DOM.
+ * Material Design 3 Dialog component.
+ *
+ * Dialogs inform users about a task and can contain critical information,
+ * require decisions, or involve multiple tasks. They interrupt the user's
+ * workflow and should be used sparingly.
+ *
+ * **M3 spec reference:** `m3-docs/components/dialogs/specs.md`
+ *
+ * **Implementation note — native `<dialog>` element:**
+ * This component wraps the native `<dialog>` HTML element. Opening and closing
+ * are controlled via the `open` attribute (and its JS property). The component
+ * syncs `open` changes to the native `<dialog>` in `updated()`:
+ * - `modal=true` → calls `dialog.showModal()` (blocks focus, adds backdrop).
+ * - `modal=false` → calls `dialog.show()` (non-blocking, no backdrop).
+ * - `open=false` → calls `dialog.close()`.
+ *
+ * **Placement (`side` attribute):**
+ * - `center` (default) — Centered in the viewport. Standard M3 dialog.
+ * - `top`, `right`, `bottom`, `left` — Edge-anchored panels (side sheet pattern).
+ * - `max` — Full-screen dialog for complex flows.
+ *
+ * @example
+ * ```html
+ * <!-- Basic modal dialog -->
+ * <moni-dialog open modal title="Delete item?" size="small">
+ *   <p>This action cannot be undone.</p>
+ *   <div slot="footer">
+ *     <moni-button variant="text">Cancel</moni-button>
+ *     <moni-button>Delete</moni-button>
+ *   </div>
+ * </moni-dialog>
+ * ```
  *
- * Attributes:
- *  - open:   present → dialog[open]
- *  - side:   center (default) | top | right | bottom | left | max
- *  - size:   small | medium (default) | large
- *  - modal:  present → adds the `modal` class (used by BeerCSS)
- *  - title:  header text
+ * @slot default - The dialog body content.
+ * @slot header  - Custom header content (overrides `title` attribute).
+ * @slot footer  - Action buttons row at the bottom of the dialog.
  *
- * Slots:
- *  - default: body
- *  - header:  title
- *  - footer:  action buttons
+ * @csspart dialog - The native `<dialog>` element.
+ * @csspart header - The header container.
+ * @csspart body   - The body content wrapper.
+ * @csspart footer - The footer actions wrapper.
  */
 let MoniDialog = class MoniDialog extends MoniElement {
     constructor() {
         super(...arguments);
+        /**
+         * Controls the open/closed state of the dialog.
+         *
+         * When set to `true`, the component calls `dialog.showModal()` (if `modal`)
+         * or `dialog.show()`. When set to `false`, calls `dialog.close()`.
+         * Reflected as an HTML attribute for CSS and external state readers.
+         *
+         * @default false
+         */
         this.open = false;
+        /**
+         * When `true`, opens the dialog as a modal using `<dialog>.showModal()`.
+         *
+         * Modal dialogs:
+         * - Block keyboard focus from leaving the dialog.
+         * - Render a `::backdrop` scrim over the rest of the page.
+         * - Can be closed by pressing `Escape` (native browser behavior).
+         *
+         * When `false`, uses `<dialog>.show()` which is non-blocking (no focus trap
+         * and no backdrop).
+         *
+         * @default false
+         */
         this.modal = false;
+        /**
+         * Placement of the dialog within the viewport.
+         *
+         * - `'center'` (default) — Centered. Standard M3 dialog placement.
+         * - `'top'`    — Anchored to the top edge (drawer from top).
+         * - `'right'`  — Anchored to the right edge (side sheet pattern).
+         * - `'bottom'` — Anchored to the bottom edge (bottom sheet alternative).
+         * - `'left'`   — Anchored to the left edge (navigation drawer pattern).
+         * - `'max'`    — Full-screen (covers the entire viewport).
+         *
+         * @default 'center'
+         */
         this.side = 'center';
+        /**
+         * Size of the dialog container.
+         *
+         * - `'small'`  — Narrow dialog; ideal for simple confirmations.
+         * - `'medium'` — Standard dialog width (default).
+         * - `'large'`  — Wide dialog; for forms or complex content.
+         *
+         * @default 'medium'
+         */
         this.size = 'medium';
+        /**
+         * Text displayed in the dialog header area.
+         *
+         * When non-empty, renders as a styled heading inside the header container.
+         * The `header` slot takes precedence over this attribute when both are present.
+         *
+         * @default ''
+         */
         this.title = '';
     }
+    /**
+     * Syncs the `open` and `modal` state to the native `<dialog>` element.
+     *
+     * Called by Lit after every render cycle where tracked properties change.
+     * Avoids calling `showModal()` or `show()` if the dialog is already open
+     * (prevents the `InvalidStateError` DOMException).
+     *
+     * @param changed - Map of changed property names to their previous values.
+     */
     updated(changed) {
         if (changed.has('open') && this._dialog) {
             if (this.open) {

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

@@ -1,28 +1,63 @@
+/**
+ * @file components/moni-divider.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } from './_base/index.js';
 /**
- * Material 3 Divider (`m3-docs/components/divider/specs.md`).
+ * Material Design 3 Divider component.
+ *
+ * A thin horizontal (or vertical) rule used to visually separate content
+ * sections within lists, layouts, and cards.
+ *
+ * **M3 spec reference:** `m3-docs/components/divider/specs.md`
+ *
+ * **M3 measurements:**
+ * - Thickness: 1dp (`0.0625rem`).
+ * - Color: `outline-variant` — subtle on all surface backgrounds.
+ * - Inset variants align the line with list content:
+ *   - `leading` — 16dp margin from the leading edge (aligns with icon text).
+ *   - `middle`  — 16dp margin on both edges.
+ *   - `none`    — full-bleed (no margin).
  *
- * A thin line used to group content in lists, layouts, or cards. M3 spec
- * defines three inset variants:
- *  - **full** (default): spans the full width of the parent.
- *  - **inset**: indented from the leading edge (16dp) so it lines up
- *    with text content below an icon.
- *  - **middle**: indented from both edges (16dp each).
+ * **Vertical usage:**
+ * While not yet exposed as an attribute, the `[vertical]` CSS attribute selector
+ * is supported. Set `vertical` as an HTML attribute to render a 1dp-wide
+ * vertical divider that stretches to match its flex container's cross-axis.
  *
- * M3 measurements:
- *  - Thickness: 1dp (`0.0625rem`).
- *  - Color: `outline-variant` (subtle on a light background).
+ * @example
+ * ```html
+ * <!-- Full-bleed divider between sections -->
+ * <moni-divider inset="none"></moni-divider>
  *
- * Attributes:
- *  - inset:  leading (default) | middle | none
+ * <!-- Leading-inset divider in a list (aligns with list item text) -->
+ * <moni-divider></moni-divider>
  *
- * Slots:
- *  - default: optional content rendered inline with the divider line.
+ * <!-- Vertical divider inside a flex container -->
+ * <div style="display:flex; height: 3rem; align-items:center; gap: 1rem;">
+ *   <span>Section A</span>
+ *   <moni-divider vertical></moni-divider>
+ *   <span>Section B</span>
+ * </div>
+ * ```
  */
 export declare class MoniDivider extends MoniElement {
+    /**
+     * Controls the horizontal margin on the divider line.
+     *
+     * - `'leading'` (default) — 16dp margin from the leading (start) edge only.
+     *   Use in lists to align the divider with the primary text of list items.
+     * - `'middle'`  — 16dp margin on both the leading and trailing edges.
+     *   Use to separate sections where full-bleed would be too visually heavy.
+     * - `'none'`    — No margin; the line spans the full parent width.
+     *   Use as a section separator or between cards.
+     *
+     * @default 'leading'
+     */
     inset: 'leading' | 'middle' | 'none';
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-divider.d.ts","sourceRoot":"","sources":["../../src/components/moni-divider.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBACa,WAAY,SAAQ,WAAW;IAE3C,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAa;IAEjD,OAAgB,MAAM,4BAkCpB;IAEO,MAAM;CAGf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,cAAc,EAAE,WAAW,CAAC;KAC5B;CACD;AAED,eAAe,WAAW,CAAC"}
+{"version":3,"file":"moni-divider.d.ts","sourceRoot":"","sources":["../../src/components/moni-divider.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBACa,WAAY,SAAQ,WAAW;IAC3C;;;;;;;;;;;OAWG;IAEH,KAAK,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAa;IAEjD,OAAgB,MAAM,4BAkCpB;IAEO,MAAM;CAGf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,cAAc,EAAE,WAAW,CAAC;KAC5B;CACD;AAED,eAAe,WAAW,CAAC"}

package/dist/components/moni-divider.js

@@ -1,3 +1,9 @@
+/**
+ * @file components/moni-divider.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,28 +14,57 @@ import { html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Material 3 Divider (`m3-docs/components/divider/specs.md`).
+ * Material Design 3 Divider component.
+ *
+ * A thin horizontal (or vertical) rule used to visually separate content
+ * sections within lists, layouts, and cards.
+ *
+ * **M3 spec reference:** `m3-docs/components/divider/specs.md`
+ *
+ * **M3 measurements:**
+ * - Thickness: 1dp (`0.0625rem`).
+ * - Color: `outline-variant` — subtle on all surface backgrounds.
+ * - Inset variants align the line with list content:
+ *   - `leading` — 16dp margin from the leading edge (aligns with icon text).
+ *   - `middle`  — 16dp margin on both edges.
+ *   - `none`    — full-bleed (no margin).
  *
- * A thin line used to group content in lists, layouts, or cards. M3 spec
- * defines three inset variants:
- *  - **full** (default): spans the full width of the parent.
- *  - **inset**: indented from the leading edge (16dp) so it lines up
- *    with text content below an icon.
- *  - **middle**: indented from both edges (16dp each).
+ * **Vertical usage:**
+ * While not yet exposed as an attribute, the `[vertical]` CSS attribute selector
+ * is supported. Set `vertical` as an HTML attribute to render a 1dp-wide
+ * vertical divider that stretches to match its flex container's cross-axis.
  *
- * M3 measurements:
- *  - Thickness: 1dp (`0.0625rem`).
- *  - Color: `outline-variant` (subtle on a light background).
+ * @example
+ * ```html
+ * <!-- Full-bleed divider between sections -->
+ * <moni-divider inset="none"></moni-divider>
  *
- * Attributes:
- *  - inset:  leading (default) | middle | none
+ * <!-- Leading-inset divider in a list (aligns with list item text) -->
+ * <moni-divider></moni-divider>
  *
- * Slots:
- *  - default: optional content rendered inline with the divider line.
+ * <!-- Vertical divider inside a flex container -->
+ * <div style="display:flex; height: 3rem; align-items:center; gap: 1rem;">
+ *   <span>Section A</span>
+ *   <moni-divider vertical></moni-divider>
+ *   <span>Section B</span>
+ * </div>
+ * ```
  */
 let MoniDivider = class MoniDivider extends MoniElement {
     constructor() {
         super(...arguments);
+        /**
+         * Controls the horizontal margin on the divider line.
+         *
+         * - `'leading'` (default) — 16dp margin from the leading (start) edge only.
+         *   Use in lists to align the divider with the primary text of list items.
+         * - `'middle'`  — 16dp margin on both the leading and trailing edges.
+         *   Use to separate sections where full-bleed would be too visually heavy.
+         * - `'none'`    — No margin; the line spans the full parent width.
+         *   Use as a section separator or between cards.
+         *
+         * @default 'leading'
+         */
         this.inset = 'leading';
     }
     static { this.styles = [

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

@@ -1,20 +1,56 @@
+/**
+ * @file components/moni-expansion.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
 import { MoniElement } 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).
  */
 export declare class MoniExpansion extends MoniElement {
     open: boolean;
     title: string;
     static styles: import("lit").CSSResult[];
-    render(): import("lit-html").TemplateResult<1>;
+    render(): import("lit").TemplateResult<1>;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-expansion.d.ts","sourceRoot":"","sources":["../../src/components/moni-expansion.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;GAUG;AACH,qBACa,aAAc,SAAQ,WAAW;IACD,IAAI,UAAS;IAC5B,KAAK,SAAM;IAExC,OAAgB,MAAM,4BA6CpB;IAEO,MAAM;CAUf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,gBAAgB,EAAE,aAAa,CAAC;KAChC;CACD;AAED,eAAe,aAAa,CAAC"}
+{"version":3,"file":"moni-expansion.d.ts","sourceRoot":"","sources":["../../src/components/moni-expansion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBACa,aAAc,SAAQ,WAAW;IACD,IAAI,UAAS;IAC5B,KAAK,SAAM;IAExC,OAAgB,MAAM,4BA6CpB;IAEO,MAAM;CAUf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,gBAAgB,EAAE,aAAa,CAAC;KAChC;CACD;AAED,eAAe,aAAa,CAAC"}