@moni-labs/moni-ui 0.2.0 → 0.3.1

package/src/components/moni-ripple.ts

@@ -1,33 +1,135 @@
+/**
+ * @file components/moni-ripple.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 ripple decoration.
+ * Visual-only ripple decoration component.
+ *
+ * Provides a pointer-origin ripple animation — the expanding circle starts
+ * at the exact pointer-down coordinates rather than the element's center.
+ * This is the full-fidelity M3 ripple; for a simpler CSS-only center-ripple,
+ * use the `interactionStyles` `.interactive::after` pseudo-element instead.
+ *
+ * **Usage:**
+ * Drop `<moni-ripple>` as a **child** of any interactive element. The component
+ * automatically attaches a `pointerdown` listener to its `parentElement` and
+ * calculates the ripple origin in percentage coordinates relative to the parent.
+ *
+ * The parent element must NOT have `position: static` (the ripple applies
+ * `position: relative` automatically in `connectedCallback`).
+ *
+ * **Timing model:**
+ * On `pointerdown`:
+ * 1. `active = false` is set (cancels any in-progress ripple).
+ * 2. A `requestAnimationFrame` tick ensures the browser has processed the reset.
+ * 3. `active = true` triggers the CSS scale animation.
+ * 4. A `setTimeout` of `duration` ms (based on `speed`) resets `active = false`.
  *
- * To trigger a ripple at a specific point, set the `x` and `y` attributes
- * and toggle the `active` attribute. The visual scale-in animation will
- * run for `duration` ms and then the element becomes hidden.
+ * The duration matches the CSS transition duration so the opacity fade-out
+ * completes before `active` is cleared.
  *
- * Attributes:
- *  - x, y:        origin in px (0..100, %)
- *  - active:      present → visible
- *  - speed:       fast | normal (default) | slow
- *  - color:       primary (default) | secondary | surface
+ * **Cleanup:**
+ * `disconnectedCallback` removes the `pointerdown` listener and clears any
+ * pending timeout. Always call `super.disconnectedCallback()` if subclassing.
+ *
+ * @example
+ * ```html
+ * <!-- Ripple on a custom element -->
+ * <div class="my-button" style="position: relative; overflow: hidden;">
+ *   Click me
+ *   <moni-ripple color="primary"></moni-ripple>
+ * </div>
+ * ```
+ *
+ * @csspart ripple - The inner `<span>` that performs the scale animation.
  */
 @customElement('moni-ripple')
 export class MoniRipple extends MoniElement {
+	/**
+	 * Horizontal origin of the ripple as a percentage of the parent's width.
+	 *
+	 * Set automatically by `_onPointerDown` based on the pointer coordinates.
+	 * Can be set manually to trigger a ripple at a specific location.
+	 *
+	 * @default 50
+	 */
 	@property({ type: Number, reflect: true }) x = 50;
+
+	/**
+	 * Vertical origin of the ripple as a percentage of the parent's height.
+	 *
+	 * Set automatically by `_onPointerDown` based on the pointer coordinates.
+	 *
+	 * @default 50
+	 */
 	@property({ type: Number, reflect: true }) y = 50;
+
+	/**
+	 * When `true`, the ripple is visible and animating.
+	 *
+	 * Toggled automatically by `_onPointerDown`. Can be set manually for
+	 * programmatically-triggered ripple effects.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) active = false;
+
+	/**
+	 * Animation speed of the ripple expand-and-fade sequence.
+	 *
+	 * Maps to the `--_dur` CSS custom property:
+	 * - `'fast'`   — 300ms
+	 * - `'normal'` — 600ms (default)
+	 * - `'slow'`   — 1200ms
+	 *
+	 * @default 'normal'
+	 */
 	@property({ reflect: true })
 	speed: 'fast' | 'normal' | 'slow' = 'normal';
+
+	/**
+	 * Color token for the ripple overlay.
+	 *
+	 * Sets the `color` CSS property on `:host`, which the `.ripple` span
+	 * inherits via `background-color: currentColor`.
+	 *
+	 * - `'primary'`   — `--primary` (default)
+	 * - `'secondary'` — `--secondary`
+	 * - `'surface'`   — `--surface-variant` (subtle, for surface containers)
+	 *
+	 * @default 'primary'
+	 */
 	@property({ reflect: true })
 	color: 'primary' | 'secondary' | 'surface' = 'primary';
 
+	/**
+	 * Reference to the parent element that the ripple is anchored to.
+	 * Populated in `connectedCallback`, cleared in `disconnectedCallback`.
+	 */
 	private _target: HTMLElement | null = null;
+
+	/**
+	 * ID of the pending `setTimeout` that clears `active` after the animation.
+	 * Stored so it can be cancelled if a second pointer event fires before the
+	 * first ripple finishes (rapid double-tap prevention).
+	 */
 	private _timeoutId: any = null;
 
+	/**
+	 * Attaches the ripple to its parent element.
+	 *
+	 * - Stores a reference to `parentElement` for pointer event listening.
+	 * - Ensures the parent has `position: relative` so the ripple's `position: absolute`
+	 *   stays within bounds.
+	 * - Registers the `_onPointerDown` event listener.
+	 */
 	override connectedCallback() {
 		super.connectedCallback();
 		this._target = this.parentElement;
@@ -40,6 +142,12 @@ export class MoniRipple extends MoniElement {
 		}
 	}
 
+	/**
+	 * Detaches the ripple from its parent element.
+	 *
+	 * Removes the `pointerdown` listener and clears any pending timeout to
+	 * prevent the `active` flag from being set after the element is removed.
+	 */
 	override disconnectedCallback() {
 		if (this._target) {
 			this._target.removeEventListener('pointerdown', this._onPointerDown);
@@ -50,6 +158,15 @@ export class MoniRipple extends MoniElement {
 		super.disconnectedCallback();
 	}
 
+	/**
+	 * Handles pointer-down events on the parent element.
+	 *
+	 * Computes the ripple origin as a percentage of the parent's bounding rect,
+	 * cancels any in-progress ripple, then triggers a new one after one
+	 * animation frame to guarantee the CSS transition fires from the new position.
+	 *
+	 * @param e - The `PointerEvent` from the parent's `pointerdown` listener.
+	 */
 	private _onPointerDown = (e: PointerEvent) => {
 		if (!this._target) return;
 		const rect = this._target.getBoundingClientRect();

package/src/components/moni-segmented-button.ts

@@ -1,26 +1,47 @@
+/**
+ * @file components/moni-segmented-button.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 import { customElement, property, queryAssignedElements } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import { MoniButtonSegment } from './moni-button-segment.js';
 
 /**
+ * Material Design 3 Segmented Button component (Legacy).
+ *
  * A form-associated group of selectable segmented buttons.
  *
- * @deprecated since v0.3.0 — `moni-segmented-button` is **no longer
- * recommended** by Material Design 3 Expressive. Use
- * `moni-button-group[variant="connected"]` instead, which has the same
- * functionality with an updated visual design. See
- * `m3-docs/components/segmented-buttons/overview.md` § M3 Expressive update.
+ * **Deprecation Notice:** The M3 spec (`m3-docs/components/segmented-buttons/overview.md`)
+ * has updated the segmented button pattern. The bespoke segments have been
+ * replaced with standard `<moni-button>` elements grouped inside a
+ * `<moni-button-group variant="connected">`.
  *
  * This component continues to work for backward compatibility but will be
  * removed in v1.0. A deprecation warning is logged to the console when the
  * element is connected to the DOM.
  *
- * Attributes:
- *  - name:       Name of the control in forms
- *  - multi:      Whether multiple options can be selected
- *  - hide-check: Hides checkmarks on all child segments
- *  - gap:        Custom gap space (e.g. "8px" or "1rem")
+ * @deprecated Use `<moni-button-group variant="connected">` instead.
+ *
+ * @example
+ * ```html
+ * <!-- Legacy usage (not recommended) -->
+ * <moni-segmented-button name="view" multi>
+ *   <moni-button-segment value="day">Day</moni-button-segment>
+ *   <moni-button-segment value="week">Week</moni-button-segment>
+ * </moni-segmented-button>
+ *
+ * <!-- Modern M3 equivalent -->
+ * <moni-button-group variant="connected">
+ *   <moni-button>Day</moni-button>
+ *   <moni-button>Week</moni-button>
+ * </moni-button-group>
+ * ```
+ *
+ * @slot default - `<moni-button-segment>` elements.
  */
 @customElement('moni-segmented-button')
 export class MoniSegmentedButton extends MoniElement {

package/src/components/moni-select-option.ts

@@ -1,16 +1,51 @@
+/**
+ * @file components/moni-select-option.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';
 
 /**
- * Option item for custom moni-select dropdown.
+ * Material Design 3 Select Option component.
+ *
+ * An individual selectable item designed to be placed inside a
+ * `<moni-select>` dropdown.
+ *
+ * **Interaction and layout:**
+ * Options are rendered as accessible `<li>` elements styled identically to
+ * `<moni-menu-item>`. When slotted into a `<moni-select>`, the parent
+ * component extracts their `value`, `label`, and `group` attributes to build
+ * its internal data model and handles the actual selection logic, keyboard
+ * navigation, and rendering within the dropdown popup.
+ *
+ * **Grouping:**
+ * Options can be categorized into subcategories by providing a `group`
+ * attribute. The parent `<moni-select>` uses this to automatically generate
+ * group headers (`<moni-select-group>`) in the dropdown list.
+ *
+ * @example
+ * ```html
+ * <moni-select label="Favorite framework">
+ *   <!-- Standard option -->
+ *   <moni-select-option value="lit">Lit Element</moni-select-option>
+ *
+ *   <!-- Disabled option -->
+ *   <moni-select-option value="react" disabled>React (not allowed)</moni-select-option>
+ *
+ *   <!-- Grouped option -->
+ *   <moni-select-option value="vue" group="Other">Vue.js</moni-select-option>
+ * </moni-select>
+ * ```
+ *
+ * @slot default - The text label for the option. If the `label` attribute is
+ *                omitted, the parent `<moni-select>` will read this slot's
+ *                `textContent`.
  *
- * Attributes:
- *  - value:    string value of the option
- *  - label:    text label (uses textContent or slot if empty)
- *  - group:    subcategory group/category name
- *  - selected: present -> active highlight state
- *  - disabled: present -> disabled
+ * @csspart item - The outer `<li>` element.
  */
 @customElement('moni-select-option')
 export class MoniSelectOption extends MoniElement {

package/src/components/moni-select.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-select.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css, nothing } from 'lit';
 import { customElement, property, state, query } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
@@ -7,25 +14,96 @@ import './moni-icon.js';
 import './moni-progress.js';
 import './moni-select-option.js';
 
+/**
+ * Internal representation of a single option within the select dropdown.
+ *
+ * @internal
+ */
 interface OptionNode {
+	/** Discriminant property that identifies this node as an option. */
 	type: 'option';
+	/** The value submitted when this option is selected. */
 	value: string;
+	/** The display label shown in the dropdown list. */
 	label: string;
+	/** When `true`, the option is non-interactive and grayed out. */
 	disabled?: boolean;
+	/** Reference to the original slotted `<moni-select-option>` element, if any. */
 	element?: HTMLElement;
+	/** Optional group name for organizing options under a `<moni-select-group>`. */
 	group?: string;
 }
 
+/**
+ * Internal representation of an option group within the select dropdown.
+ *
+ * @internal
+ */
 interface GroupNode {
+	/** Discriminant property that identifies this node as a group. */
 	type: 'group';
+	/** The group header label displayed above the group's options. */
 	label: string;
+	/** The options nested within this group. */
 	children: DropdownNode[];
 }
 
+/** Union type for any node in the dropdown tree. @internal */
 type DropdownNode = OptionNode | GroupNode;
 
 /**
- * Custom Searchable Select Component with Subcategories, Animations, and Drawer/Sheet option.
+ * Material Design 3 Select (Dropdown) component.
+ *
+ * A fully-featured custom select dropdown with searchability, option groups,
+ * keyboard navigation, animation, and optional mobile drawer/sheet mode.
+ * Replaces the native `<select>` element with a fully styled, accessible
+ * M3-compliant alternative.
+ *
+ * **M3 spec reference:** `m3-docs/components/menus/specs.md` (dropdown menus)
+ *
+ * **Feature summary:**
+ * - Filled and outlined variants matching the M3 text field styles.
+ * - Floating label with the standard field-styles floating label animation.
+ * - Searchable mode: `searchable` attribute adds an inline filter input.
+ * - Option groups: slot `<moni-select-group>` elements for hierarchical options.
+ * - Mobile drawer: `drawer` attribute opens options in a `<moni-bottom-sheet>`
+ *   instead of a dropdown popup, ideal for touch UIs.
+ * - Keyboard navigation: Arrow keys, Enter, Escape, and Tab per ARIA combobox.
+ * - Loading state: `loading` shows an indeterminate circular progress.
+ * - Multi-value support: `multiple` enables multiple selection.
+ *
+ * **Option sources:**
+ * Options can be provided in two ways:
+ * 1. **Slotted `<moni-select-option>` elements** (default, recommended for SSR).
+ * 2. **`options` property** — a `DropdownNode[]` array for fully programmatic control.
+ *
+ * **Value binding:**
+ * The `value` property holds the currently selected option's value string.
+ * For multiple selection, `values` holds `string[]`. On change, a composed
+ * `'change'` event is fired.
+ *
+ * @fires change - Bubbles and is composed. Fired when the selected value changes.
+ *                 Read `element.value` (or `element.values` for `multiple`).
+ *
+ * @example
+ * ```html
+ * <moni-select label="Country" name="country" variant="outlined">
+ *   <moni-select-option value="us">United States</moni-select-option>
+ *   <moni-select-option value="gb">United Kingdom</moni-select-option>
+ *   <moni-select-option value="de">Germany</moni-select-option>
+ * </moni-select>
+ *
+ * <!-- Searchable select -->
+ * <moni-select label="Language" searchable>
+ *   <moni-select-option value="ts">TypeScript</moni-select-option>
+ *   <moni-select-option value="py">Python</moni-select-option>
+ * </moni-select>
+ * ```
+ *
+ * @slot default - `<moni-select-option>` or `<moni-select-group>` children.
+ *
+ * @csspart field    - The outer `.field` div container.
+ * @csspart dropdown - The floating option list container.
  */
 @customElement('moni-select')
 export class MoniSelect extends MoniElement {

package/src/components/moni-side-sheet.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-side-sheet.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css, PropertyValues } from 'lit';
 import { customElement, property, query } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
@@ -5,24 +12,55 @@ import './moni-icon.js';
 import './moni-button.js';
 
 /**
- * Material Design 3 Side Sheet Component.
- * Can act as a standard (non-modal) side sheet or a modal side sheet.
+ * Material Design 3 Side Sheet component.
+ *
+ * Side sheets show supplementary content that is anchored to the left or right
+ * edge of the screen. They can be standard (inline with content) or modal
+ * (overlaying content with a scrim).
+ *
+ * **M3 spec reference:** `m3-docs/components/side-sheets/specs.md`
+ *
+ * **Dialog behavior:**
+ * Internally, this component uses the native HTML `<dialog>` element for robust
+ * accessibility, focus trapping, and top-layer rendering.
+ * - When `modal=true`, the sheet uses `dialog.showModal()`, rendering a scrim
+ *   backdrop and trapping focus. Pressing `Escape` closes it.
+ * - When `modal=false`, the sheet uses `dialog.show()` and remains interactive
+ *   alongside the main page content.
+ *
+ * **Drag & Resize (Moni feature):**
+ * Setting the `with-handle` attribute adds a draggable grab handle to the inner
+ * edge of the sheet. Users can click and drag this handle to resize the sheet's
+ * width up to the `max-width` limit. If the user drags the sheet towards the
+ * screen edge quickly or beyond a certain threshold, it automatically closes.
+ *
+ * **Animations:**
+ * Side sheets slide in from the specified `side` (`left` or `right`). The open
+ * and close animations are handled via CSS transitions tied to the `open` property.
+ *
+ * @fires close - Fired when the side sheet is completely closed (after animations
+ *                finish), either via the close button, scrim click, drag-to-close,
+ *                or `Escape` key.
+ *
+ * @example
+ * ```html
+ * <!-- Modal side sheet on the right -->
+ * <moni-side-sheet id="details-sheet" modal title="Item Details">
+ *   <p>Here is more information about the selected item.</p>
+ *   <div slot="footer">
+ *     <moni-button>Save</moni-button>
+ *   </div>
+ * </moni-side-sheet>
  *
- * Attributes:
- *  - open:            boolean (reflect: true)
- *  - modal:           boolean (reflect: true)
- *  - side:            'right' | 'left' (default: 'right')
- *  - title:           Header text (default: '')
- *  - detached:        boolean (adds 16px/16dp margins/rounded corners all around)
- *  - showClose:       boolean (shows standard close button)
- *  - showBack:        boolean (shows standard back button)
- *  - noBorder:        boolean (removes borders, default: false)
- *  - withHandle:      boolean (shows grab handle and enables dragging to close/resize, default: false)
- *  - expanded-width:  string (width when expanded, default: '600px')
- *  - max-width:       string (maximum width restriction, default: '100%')
+ * <!-- Resizable, detached side sheet on the left -->
+ * <moni-side-sheet side="left" detached with-handle max-width="50vw">
+ *   <p>Navigation options</p>
+ * </moni-side-sheet>
+ * ```
  *
- * Events:
- *  - close:       Fired when the sheet is closed/dismissed
+ * @slot default - Main body content.
+ * @slot header  - Custom header content (overrides `title`, close/back buttons remain).
+ * @slot footer  - Bottom-anchored action area.
  */
 @customElement('moni-side-sheet')
 export class MoniSideSheet extends MoniElement {

package/src/components/moni-slider.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-slider.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css, nothing } from 'lit';
 import { customElement, property, state } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
@@ -5,33 +12,58 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 
 /**
- * Slider that faithfully ports BeerCSS's `.slider` styles.
+ * Material Design 3 Slider component.
+ *
+ * Sliders allow users to select a single value or a range of values from a
+ * continuous or discrete scale.
+ *
+ * **M3 spec reference:** `m3-docs/components/sliders/specs.md`
+ *
+ * **Slider modes:**
+ * - **Continuous** (default) — Smooth drag between `min` and `max`. Use when
+ *   the exact value does not need to be defined by the user (e.g. volume).
+ * - **Discrete** — Set `step` to snap to discrete intervals. Tick marks
+ *   appear via the native `<datalist>` element in Chrome/Edge. Firefox does
+ *   not render datalist ticks for range inputs.
+ * - **Range** (`range` attribute) — Two thumbs that define a minimum and
+ *   maximum value within the slider's extent.
+ * - **Vertical** (`vertical` attribute) — 90° rotated slider.
+ *
+ * **Value label tooltip:**
+ * When `indicator` is set, the current value is displayed in a tooltip above
+ * (or below, via `indicator-placement`) the active thumb during focus/drag.
+ *
+ * **Tick marks:**
+ * - `ticks` attribute: adds datalist with marks at `min` and `max` only.
+ * - `tick-interval` attribute: generates datalist options at every N units
+ *   between `min` and `max`, creating visible tick marks at those positions.
+ *
+ * **Internal state management:**
+ * Uses `@state()` for `_value` and `_valueHigh` so the fill track width and
+ * tooltip position update reactively on every drag `input` event without
+ * waiting for the `change` event.
+ *
+ * @fires change - Bubbles and is composed. Fired when dragging ends and the
+ *                 value is committed. Read `element.value` for the new value.
+ * @fires input  - Fired on every drag step. Read `element.value` for the
+ *                 live value during drag.
+ *
+ * @example
+ * ```html
+ * <!-- Continuous slider -->
+ * <moni-slider name="volume" min="0" max="100" value="60"></moni-slider>
  *
- * Fixes:
- *  - Uses @state() for internal reactive values so CSS vars update on every input
- *  - Track visual (span) and tooltip positions update immediately on drag
+ * <!-- Discrete slider with ticks every 10 units -->
+ * <moni-slider step="10" tick-interval="10" indicator></moni-slider>
  *
- * M3 spec (`m3-docs/components/sliders/specs.md`):
- *  - Continuous slider: smooth drag between min/max.
- *  - Discrete slider: snap to `step` intervals; tick marks visible.
- *  - Tick marks: in Chrome/Edge, native `<datalist>` ticks render at every
- *    option value. In Firefox, the datalist ticks are not rendered for
- *    range inputs; consumers can use `tick-interval` to manually generate
- *    a visual fallback if needed (P3.4 — outside the scope of this release).
- *  - State layer: hover/focus state uses CSS `::before` overlay at 0.08/0.12
- *    opacity per M3 (handled by `interaction-styles.ts`).
+ * <!-- Range slider -->
+ * <moni-slider range min="0" max="100" value="20" value-high="80"></moni-slider>
+ * ```
  *
- * Attributes:
- *  - name, min, max, step, value, disabled
- *  - size:       tiny | small | medium (default) | large | extra
- *  - vertical:   present → rotated
- *  - range:      present → two thumbs
- *  - ticks:      present → datalist with min/max marks
- *  - tick-interval: number — when set, generates datalist options every
- *                    N units between min and max. Overrides `ticks`.
- *  - indicator:  present → show value tooltip on focus
- *  - indicator-placement: top (default) | bottom
- *  - inset-icon: Material Symbols name inside the colored track
+ * @csspart slider    - The outer slider container.
+ * @csspart track     - The track background.
+ * @csspart fill      - The filled portion of the track.
+ * @csspart indicator - The value label tooltip.
  */
 @customElement('moni-slider')
 export class MoniSlider extends MoniElement {