@moni-labs/moni-ui 0.2.0 → 0.3.1

package/src/components/moni-morph-modal.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-morph-modal.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 import { customElement, property, query, state } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
@@ -36,6 +43,11 @@ type Placement =
 	| 'viewport-bottom-left'
 	| 'viewport-bottom-right';
 
+/**
+ * Internal coordinate and styling state of the morph target before animation.
+ *
+ * @internal
+ */
 interface TargetState {
 	rect: DOMRect;
 	backgroundColor: string;
@@ -43,40 +55,62 @@ interface TargetState {
 	borderRadius: string;
 }
 
+/**
+ * References to the internal icon and text elements animated during the morph.
+ *
+ * @internal
+ */
 interface MorphElements {
 	text: HTMLElement | null;
 	icon: HTMLElement | null;
 }
 
 /**
- * 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.
  *
- * 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.
+ * **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).
  *
- * 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.
+ * @example
+ * ```html
+ * <moni-morph-modal id="myModal" title="Details">
+ *   <p>This modal morphed from the button you just clicked.</p>
+ * </moni-morph-modal>
  *
- * Slots:
- *  - default: cuerpo del panel.
- *  - header:  encabezado.
- *  - footer:  acciones al pie.
- *  - trigger-label: contenido explícito a animar desde el target.
+ * <moni-button id="openBtn">Open Details</moni-button>
+ *
+ * <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>
+ * ```
+ *
+ * @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: string | null) => value !== 'false' && value !== null,
 	toAttribute: (value: boolean) => (value ? '' : null)

package/src/components/moni-nav-item.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-nav-item.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 import { customElement, property, state } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
@@ -5,15 +12,49 @@ 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.
  */
 @customElement('moni-nav-item')
 export class MoniNavItem extends MoniElement {

package/src/components/moni-nav.ts

@@ -1,29 +1,65 @@
+/**
+ * @file components/moni-nav.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Visual-only navigation. Renders a `<nav>` styled with BeerCSS helpers.
+ * Material Design 3 Navigation container component.
+ *
+ * `<moni-nav>` is the container that wraps `<moni-nav-item>` elements and
+ * controls the M3 navigation pattern: navigation bar, navigation rail, or
+ * navigation drawer.
+ *
+ * **M3 spec references:**
+ * - Navigation bar: `m3-docs/components/navigation-bar/specs.md`
+ * - Navigation rail: `m3-docs/components/navigation-rail/specs.md`
+ * - Navigation drawer: `m3-docs/components/navigation-drawer/specs.md`
+ *
+ * **Navigation patterns:**
+ * - **Navigation bar** (`placement="bottom"`) — Horizontal bar of icon+label
+ *   items at the bottom of the screen. Best for 3–5 top-level destinations.
+ * - **Navigation rail** (`variant="rail"`) — Vertical rail of icon+label items
+ *   on the side of the screen. Best for medium/expanded breakpoints.
+ * - **Standard drawer** (`variant="drawer"`) — Always-visible vertical panel
+ *   with full text labels. No scrim. Best for large screens.
+ * - **Modal drawer** (`variant="drawer" modal`) — Overlay drawer with scrim.
+ *   Opened/closed via the `open` property. Traps keyboard focus while open.
+ *   Closes on `Escape` key press.
+ *
+ * **Keyboard handling:**
+ * When `modal=true`, the component adds a global `keydown` listener in
+ * `connectedCallback` that closes the drawer on `Escape`. The listener is
+ * removed in `disconnectedCallback`.
+ *
+ * @example
+ * ```html
+ * <!-- Bottom navigation bar -->
+ * <moni-nav placement="bottom">
+ *   <moni-nav-item icon="home" label="Home" active></moni-nav-item>
+ *   <moni-nav-item icon="search" label="Search"></moni-nav-item>
+ *   <moni-nav-item icon="person" label="Profile"></moni-nav-item>
+ * </moni-nav>
  *
- * M3 navigation patterns (`m3-docs/components/navigation-*`):
- *  - Navigation bar: placement="bottom"
- *  - Navigation rail: placement="left|right" variant="rail"
- *  - Navigation drawer: placement="left|right" variant="drawer"
- *    * Standard drawer: always visible, no scrim (default)
- *    * Modal drawer: `modal` toggles open/closed, renders a scrim and
- *      traps focus while open. See `m3-docs/components/navigation-drawer/specs.md`.
+ * <!-- Modal navigation drawer -->
+ * <moni-nav variant="drawer" modal open placement="left">
+ *   <h3 slot="header">My App</h3>
+ *   <moni-nav-item icon="home" label="Home" active></moni-nav-item>
+ *   <moni-nav-item icon="settings" label="Settings"></moni-nav-item>
+ * </moni-nav>
+ * ```
  *
- * Attributes:
- *  - placement: top (default) | bottom | left | right
- *  - variant:   rail | drawer
- *  - modal:     present → drawer is modal (requires variant="drawer")
- *  - open:      present → modal drawer is open (default true)
- *  - layout:    vertical | horizontal | auto (default)
+ * @slot default - `<moni-nav-item>` children.
+ * @slot header  - Content above the nav items (drawer variant only).
+ * @slot footer  - Content below the nav items (drawer variant only).
  *
- * Slots:
- *  - default: <moni-nav-item> children
- *  - header:  content above nav items (drawer only)
- *  - footer:  content below nav items (drawer only)
+ * @csspart nav     - The inner `<nav>` element.
+ * @csspart scrim   - The backdrop scrim (modal drawer only).
  */
 @customElement('moni-nav')
 export class MoniNav extends MoniElement {

package/src/components/moni-progress.ts

@@ -1,40 +1,133 @@
+/**
+ * @file components/moni-progress.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css, svg, nothing } from 'lit';
 import { customElement, property, state } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Progress indicator that faithfully ports BeerCSS's progress styles.
+ * Material Design 3 Progress Indicator component.
+ *
+ * Progress indicators express an unspecified wait time or display the length
+ * of a process. They inform users about the status of ongoing processes such
+ * as loading an app, submitting a form, or saving updates.
+ *
+ * **M3 spec reference:** `m3-docs/components/progress-indicators/specs.md`
+ *
+ * **Variants:**
+ * - `linear` (default) — A horizontal bar that fills left-to-right.
+ * - `circular` — A circular SVG stroke indicator.
+ * - `wavy` — An animated wave bar (Moni extension; not in M3 spec).
+ * - `circular-wavy` — Circular + wave combo (Moni extension).
  *
- * BeerCSS uses the native <progress> element with `::after`, `::before` and
- * `mask-image` pseudo-elements. Those don't work inside Shadow DOM because:
- *  - `<progress>` native pseudo-elements (::webkit-progress-value, ::after)
- *    are blocked by the UA shadow root in Chrome/Firefox within a custom shadow.
- *  - `mask-image` on those pseudo-elements doesn't apply at all in shadows.
+ * **Shadow DOM compatibility note:**
+ * BeerCSS's progress uses native `<progress>` pseudo-elements (`::before`,
+ * `::after`, `::webkit-progress-value`) and `mask-image`, which are blocked
+ * by the UA shadow root in Chrome/Firefox. This component uses a plain `<div>`
+ * wrapper that replicates the visual rules exactly, and an `<svg>` element
+ * for the circular variant using SVG stroke-dashoffset animation for superior
+ * cross-browser support compared to `conic-gradient`.
  *
- * Solution: use a plain <div> wrapper that replicates BeerCSS's visual rules
- * exactly, and an SVG for the circular variant (matching BeerCSS's conic-gradient
- * approach but with SVG stroke for better cross-browser support).
+ * **Percentage computation:**
+ * `_pct` is computed in `willUpdate()` as `(value / max) * 100`, clamped to
+ * `[0, 100]`. When `indeterminate` is set, `_pct` is fixed at `50` to drive
+ * the infinite loop animation.
  *
- * Attributes:
- *  - value:         0..max (omit for indeterminate)
- *  - max:           upper bound (default 100)
- *  - variant:       linear (default) | circular | wavy | circular-wavy
- *  - size:          small | medium (default) | large
- *  - indeterminate: present → infinite animation
+ * @example
+ * ```html
+ * <!-- Determinate linear progress -->
+ * <moni-progress value="65" max="100"></moni-progress>
+ *
+ * <!-- Indeterminate circular progress (loading spinner) -->
+ * <moni-progress variant="circular" indeterminate></moni-progress>
+ * ```
+ *
+ * @csspart bar      - The outer container div.
+ * @csspart fill     - The inner fill element (linear variant).
+ * @csspart svg      - The SVG element (circular variant).
  */
 @customElement('moni-progress')
 export class MoniProgress extends MoniElement {
+	/**
+	 * Current progress value.
+	 *
+	 * Must be in the range `[0, max]`. Values outside this range are clamped
+	 * during percentage computation in `willUpdate()`. Ignored when
+	 * `indeterminate` is set.
+	 *
+	 * @default 0
+	 */
 	@property({ type: Number, reflect: true }) value = 0;
+
+	/**
+	 * Maximum value of the progress range.
+	 *
+	 * Defaults to `100` so `value` can be set as a percentage directly.
+	 * For non-percentage ranges (e.g. steps), set `max` to the total step count
+	 * and `value` to the current step.
+	 *
+	 * @default 100
+	 */
 	@property({ type: Number, reflect: true }) max = 100;
+
+	/**
+	 * Visual variant of the progress indicator.
+	 *
+	 * - `'linear'` (default) — Horizontal fill bar.
+	 * - `'circular'` — SVG circle with stroke-dashoffset animation.
+	 * - `'wavy'` — Animated wave bar.
+	 * - `'circular-wavy'` — Combination of circular and wave.
+	 *
+	 * @default 'linear'
+	 */
 	@property({ reflect: true })
 	variant: 'linear' | 'circular' | 'wavy' | 'circular-wavy' = 'linear';
+
+	/**
+	 * Visual size of the progress indicator.
+	 *
+	 * - `'small'`  — Compact; suitable for inline or tight layouts.
+	 * - `'medium'` — Standard M3 size (default).
+	 * - `'large'`  — Prominent; for full-page loading states.
+	 *
+	 * @default 'medium'
+	 */
 	@property({ reflect: true })
 	size: 'small' | 'medium' | 'large' = 'medium';
+
+	/**
+	 * When `true`, the indicator animates in an infinite loop regardless of `value`.
+	 *
+	 * Use for operations where the completion percentage is unknown
+	 * (e.g. network requests, file processing). When `indeterminate` is set,
+	 * `_pct` is fixed at `50` to drive a continuous sweep animation.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) indeterminate = false;
 
-	/** Computed fill percentage (0-100) used in styles/SVG */
+	/**
+	 * Computed fill percentage in the range `[0, 100]`.
+	 *
+	 * Updated in `willUpdate()` whenever `value`, `max`, or `indeterminate` changes.
+	 * Used directly in CSS custom property bindings and SVG stroke attributes.
+	 *
+	 * @internal
+	 */
 	@state() private _pct = 0;
 
+	/**
+	 * Computes the fill percentage before each render.
+	 *
+	 * Recalculates `_pct` whenever `value`, `max`, or `indeterminate` changes.
+	 * The `Math.max(1, max)` guard prevents division-by-zero when `max` is 0.
+	 *
+	 * @param changed - Map of property names to their previous values.
+	 */
 	override willUpdate(changed: Map<string, unknown>) {
 		if (changed.has('value') || changed.has('max') || changed.has('indeterminate')) {
 			this._pct = this.indeterminate

package/src/components/moni-radio.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-radio.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 import { customElement, property, query } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
@@ -5,34 +12,112 @@ import { live } from 'lit/directives/live.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Radio that faithfully ports BeerCSS's `.radio` styles.
+ * Material Design 3 Radio Button component.
+ *
+ * Radio buttons allow users to select exactly one item from a set of mutually
+ * exclusive options. They share the same visual architecture as
+ * `<moni-checkbox>` but use `type="radio"` and implement group deselection.
+ *
+ * **M3 spec reference:** `m3-docs/components/radio/specs.md`
+ *
+ * **Visual architecture (BeerCSS pattern):**
+ * Identical to the checkbox pattern: the native `<input type="radio">` occupies
+ * real layout space at `--_size` × `--_size` but is hidden via `opacity: 0`.
+ * A sibling `<span>` renders:
+ * - `::before` — the radio icon (`radio_button_unchecked` / `radio_button_checked`).
+ * - `::after`  — the hover/focus ripple ring.
+ *
+ * **Group deselection:**
+ * When a radio is checked, `_onChange` queries the component's `getRootNode()`
+ * for all `moni-radio` elements sharing the same `name` attribute and sets
+ * their `checked` property to `false`. This mirrors native browser behavior
+ * for radio groups across shadow DOM boundaries where `name` grouping does
+ * not work natively.
  *
- * BeerCSS architecture:
- *  - `.radio` is inline-flex, aligns items center
- *  - `input` has width/height = --_size, opacity: 0  (real layout space, not absolute)
- *  - `span::before` shows "radio_button_unchecked" / "radio_button_checked" via Material Symbols font
- *  - `span::after` is the ripple hover effect
+ * @fires change - Bubbles and is composed. Fired when this radio is selected.
+ *                 Read `element.checked` for the new state.
  *
- * Attributes:
- *  - label:    text label
- *  - checked:  present
- *  - disabled: present
- *  - size:     small | medium (default) | large | extra
- *  - name:     forwarded to input.name (group radios by name)
- *  - value:    forwarded to input.value
+ * @example
+ * ```html
+ * <moni-radio name="color" value="red"   label="Red"></moni-radio>
+ * <moni-radio name="color" value="green" label="Green"></moni-radio>
+ * <moni-radio name="color" value="blue"  label="Blue" checked></moni-radio>
+ * ```
+ *
+ * @csspart radio - The outer `<label>` element.
  */
 @customElement('moni-radio')
 export class MoniRadio extends MoniElement {
+	/**
+	 * Text label displayed to the right of the radio icon.
+	 *
+	 * When non-empty, renders as a text node. When empty, the default slot
+	 * is rendered, allowing slotted HTML content as the label.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) label = '';
+
+	/**
+	 * Whether this radio button is currently selected.
+	 *
+	 * Reflected as an attribute so CSS selectors can target it. Synced to
+	 * the native input via `updated()`.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) checked = false;
+
+	/**
+	 * When `true`, the radio is non-interactive and renders at 50% opacity.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) disabled = false;
+
+	/**
+	 * Visual size of the radio icon and its invisible hit area.
+	 *
+	 * | Value      | `--_size` |
+	 * |------------|-----------|
+	 * | `'small'`  | 1rem      |
+	 * | `'medium'` | 1.5rem    |
+	 * | `'large'`  | 2rem      |
+	 * | `'extra'`  | 2.5rem    |
+	 *
+	 * @default 'medium'
+	 */
 	@property({ reflect: true })
 	size: 'small' | 'medium' | 'large' | 'extra' = 'medium';
+
+	/**
+	 * Radio group name. Radios with the same `name` in the same root node
+	 * are treated as a mutual-exclusion group by `_onChange`.
+	 *
+	 * Note: Native `<input type="radio">` groups only work within the same
+	 * document root. Since `moni-radio` uses shadow DOM, the deselection
+	 * of siblings is handled imperatively in `_onChange`.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) name = '';
+
+	/**
+	 * Forwarded to the native `<input value>` attribute.
+	 * The value submitted in a form when this radio is selected.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) value = '';
 
+	/** Direct reference to the native input element for programmatic access. */
 	@query('input') private _input!: HTMLInputElement;
 
+	/**
+	 * Syncs `checked` and `disabled` to the native input after each render cycle.
+	 *
+	 * @param changed - Map of changed property names to their previous values.
+	 */
 	override updated(changed: Map<string, unknown>) {
 		if (this._input) {
 			if (changed.has('checked')) this._input.checked = this.checked;
@@ -152,6 +237,19 @@ export class MoniRadio extends MoniElement {
 		`
 	];
 
+	/**
+	 * Handles the native input `change` event.
+	 *
+	 * On selection, deselects all sibling `moni-radio` elements with the same
+	 * `name` in the same root node (document or shadow root). This is necessary
+	 * because native radio group exclusion only works within the same document
+	 * root and does not cross shadow DOM boundaries.
+	 *
+	 * After deselection, dispatches a composed `'change'` event so it is
+	 * audible to parent elements in the light DOM.
+	 *
+	 * @param e - The native `change` event from the hidden `<input>`.
+	 */
 	private _onChange(e: Event) {
 		this.checked = (e.target as HTMLInputElement).checked;
 		if (this.checked && this.name) {