@moni-labs/moni-ui 0.2.0 → 0.3.0

package/src/components/moni-button.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-button.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 { ifDefined } from 'lit/directives/if-defined.js';
@@ -6,41 +13,54 @@ import './moni-icon.js';
 import './moni-progress.js';
 
 /**
- * Visual-only button. Renders a native `<button>` styled per Material 3 Expressive.
+ * Material Design 3 Button component.
+ *
+ * Buttons allow users to take actions and make choices with a single tap.
+ * This component provides all M3 button variants, sizes, and shape morphing
+ * capabilities (e.g. morphing to a pill shape on press or toggle).
+ *
+ * **M3 spec reference:** `m3-docs/components/buttons/specs.md`
+ *
+ * **Variants:**
+ * - `filled` (default) — High emphasis. Use for primary actions.
+ * - `tonal` — Medium emphasis. Secondary actions that still need to stand out.
+ * - `elevated` — Medium emphasis with shadow. Used when sitting on patterned backgrounds.
+ * - `outlined` — Medium emphasis, no fill. Secondary or tertiary actions.
+ * - `text` — Low emphasis. Tertiary actions (e.g. dialog cancel button).
+ *
+ * **Shape morphing (M3 Expressive feature):**
+ * - On press (active state): Round and square buttons morph to a slightly squarer
+ *   "pressed" shape with specific M3 corner radii (e.g. XS/S 8dp, M 12dp).
+ * - On toggle (`active` attribute): The resting shape flips (e.g. round ↔ square).
+ *
+ * **Rendering as a link:**
+ * When the `href` attribute is provided, the component internally renders as
+ * an `<a>` element instead of a `<button>`, allowing native routing and
+ * middle-click (open in new tab) behaviors while maintaining button visuals.
+ *
+ * @example
+ * ```html
+ * <!-- Primary filled button -->
+ * <moni-button icon="add">Create new</moni-button>
+ *
+ * <!-- Outlined button -->
+ * <moni-button variant="outlined">Cancel</moni-button>
  *
- * **Shape morph on press** (`m3-docs/components/buttons/specs.md` § Shape morph):
- * round and square buttons both morph to the same pressed shape, with per-size
- * corner radii: XS 8dp, S 8dp, M 12dp, L 16dp, XL 16dp. The per-size rules
- * `.button.{xsmall,small,large,xlarge,extra}:active` override the default
- * `:active` rule by specificity (0,4,0 vs 0,3,0).
+ * <!-- Toggle button (toggles active state on click) -->
+ * <moni-button icon="favorite" active>Like</moni-button>
  *
- * **Shape morph on selected** (toggle): when `active` is true, the resting
- * shape flips (round ↔ square). See `render()`.
+ * <!-- Link button -->
+ * <moni-button href="/settings" icon="settings">Settings</moni-button>
+ * ```
  *
- * Attributes:
- *  - variant:   filled (default) | tonal | elevated | outlined | text | fill
- *  - size:      xsmall | small | medium (default) | large | xlarge
- *               (legacy `extra` alias for `xlarge`, deprecated in v0.3.0)
- *  - shape:     round (default) | square | circle | no-round
- *               | left-round | right-round | top-round | bottom-round
- *               | left-round-flat | right-round-flat | top-round-flat
- *               | bottom-round-flat | inner-round
- *               (the `-flat` and `inner-round` shapes are Moni brand
- *                extensions; not part of M3 — see WEB_COMPONENT_GUIDELINES.md)
- *  - disabled:  present → native disabled
- *  - loading:   present → shows an indeterminate circular progress
- *  - active:    present → toggle (selection) state; applies shape morph
- *               (round↔square) and variant-specific color swap
- *  - icon:      Material Symbols name to prepend
- *  - icon-trailing: Material Symbols name to append
- *  - type:      button (default) | submit | reset
- *  - href:      present → renders as `<a>` instead of `<button>`
- *  - target:    for `<a>` rendering
+ * @slot default       - The button label text.
+ * @slot icon          - Optional override for the leading icon.
+ * @slot icon-trailing - Optional override for the trailing icon.
  *
- * Slots:
- *  - default:   button label
- *  - icon:      optional override for the leading icon
- *  - icon-trailing: optional override for the trailing icon
+ * @csspart button     - The inner `<button>` or `<a>` element.
+ * @csspart icon       - The leading icon container.
+ * @csspart label      - The label container.
+ * @csspart trailing-icon - The trailing icon container.
  */
 @customElement('moni-button')
 export class MoniButton extends MoniElement {

package/src/components/moni-card.ts

@@ -1,45 +1,109 @@
+/**
+ * @file components/moni-card.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';
 
 /**
- * Material 3 Card (`m3-docs/components/cards/specs.md`).
+ * Material Design 3 Card component.
+ *
+ * Cards display content and actions about a single subject. They are
+ * container surfaces that group related information together, making it
+ * easy for users to scan and interact with collections of related data.
+ *
+ * **M3 spec reference:** `m3-docs/components/cards/specs.md`
  *
- * Cards display content and actions on a single subject. Three variants:
- *  - **elevated**: surface-container-low background + elevation 1 shadow.
- *    Default for collections where the card needs separation from a
- *    patterned background.
- *  - **filled**: surface-container-highest background, no shadow.
- *    Lowest emphasis; use when cards sit directly on the background.
- *  - **outlined**: surface background + outline-variant 1dp stroke.
- *    Highest emphasis without shadow; good on solid color backgrounds.
+ * **Variants:**
+ * - `elevated` (default) — `surface-container-low` background + `--elevate1` shadow.
+ *   Best for collections where the card needs visual separation from a
+ *   patterned or colored background. Gains shadow on hover/drag.
+ * - `filled` — `surface-container-highest` background, no shadow.
+ *   Lowest emphasis; use when cards sit directly on the main background surface.
+ * - `outlined` — `surface` background + 1dp `outline-variant` stroke.
+ *   Highest structural emphasis without casting a shadow. Best on solid backgrounds.
  *
- * M3 measurements:
- *  - Container corner radius: **12dp**.
- *  - Left/right padding: **16dp**.
- *  - Padding between cards in a collection: max **8dp**.
- *  - Headline text alignment: **start**.
+ * **M3 measurements:**
+ * - Container corner radius: 12dp.
+ * - Horizontal content padding: 16dp.
+ * - Gap between cards in a collection: max 8dp.
+ * - Headline text alignment: start.
  *
- * Slots:
- *  - media:        image or video at the top of the card.
- *  - default:      primary content (headline, subhead, supporting text).
- *  - headline:     shortcut for the H3-equivalent title (semantic).
- *  - subhead:      secondary title slot.
- *  - supporting:   supporting text slot.
- *  - actions:      action buttons row at the bottom of the card.
+ * **Interactive cards:**
+ * When `clickable=true`, the card renders M3 state layer overlays on hover,
+ * focus, and press via the `::before` pseudo-element. The consumer must handle
+ * the `click` event to implement navigation or selection logic.
  *
- * Attributes:
- *  - variant: elevated (default) | filled | outlined
- *  - clickable: present → apply hover/focus/pressed state layers
- *  - draggable:  present → apply dragged state elevation (3)
- *  - disabled:   present → reduced opacity + cursor not-allowed
+ * @example
+ * ```html
+ * <moni-card variant="outlined" clickable>
+ *   <img slot="media" src="photo.jpg" alt="Card image" />
+ *   <h3 slot="headline">Card Title</h3>
+ *   <p slot="supporting">Supporting text that describes the card topic.</p>
+ *   <div slot="actions">
+ *     <moni-button variant="text">Cancel</moni-button>
+ *     <moni-button>Confirm</moni-button>
+ *   </div>
+ * </moni-card>
+ * ```
+ *
+ * @slot media      - An image, video, or icon at the top of the card.
+ * @slot default    - Primary body content (replaces all named slots if used).
+ * @slot headline   - H3-equivalent title text.
+ * @slot subhead    - Secondary title below the headline.
+ * @slot supporting - Descriptive supporting body text.
+ * @slot actions    - Action buttons row at the bottom of the card.
+ *
+ * @csspart card    - The outer card container.
+ * @csspart media   - The media area wrapper.
+ * @csspart content - The content wrapper.
+ * @csspart actions - The actions row wrapper.
  */
 @customElement('moni-card')
 export class MoniCard extends MoniElement {
+	/**
+	 * Visual variant of the card.
+	 *
+	 * - `'elevated'` (default) — Surface-low background + elevation shadow.
+	 * - `'filled'` — Surface-highest background, no shadow.
+	 * - `'outlined'` — Surface background + outline-variant stroke.
+	 *
+	 * @default 'elevated'
+	 */
 	@property({ reflect: true })
 	variant: 'elevated' | 'filled' | 'outlined' = 'elevated';
+
+	/**
+	 * When `true`, applies M3 state layer overlays (hover, focus, pressed)
+	 * to communicate interactivity. The card background shifts slightly on hover.
+	 *
+	 * Use when the card itself is a clickable navigation or selection target.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) clickable = false;
+
+	/**
+	 * When `true`, applies `--elevate3` box-shadow to simulate the M3 "dragged"
+	 * state as specified in the M3 card interaction spec.
+	 *
+	 * Consumers should toggle this attribute based on the drag state of the card
+	 * (e.g. via a drag-and-drop library callback).
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) draggable = false;
+
+	/**
+	 * When `true`, the card renders at 50% opacity with `cursor: not-allowed`,
+	 * signaling that the card and its actions are unavailable.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) disabled = false;
 
 	static override styles = [

package/src/components/moni-carousel.ts

@@ -1,34 +1,85 @@
+/**
+ * @file components/moni-carousel.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 import { customElement, property, query, state, queryAll } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import { gsap } from 'gsap';
 
+/**
+ * Data model for a single item in a `<moni-carousel>`.
+ */
 export interface CarouselItem {
+	/** Display title overlaid on the item. */
 	title: string;
+	/** URL or path to the background image. */
 	img: string;
+	/** Optional link target. If provided, the item renders as an `<a>` element. */
 	href?: string;
+	/** Link target attribute (e.g. `'_blank'`). Only applies if `href` is set. */
 	target?: string;
 }
 
 /**
  * Material Design 3 Expressive Carousel component.
- * Supports three layouts:
- *  - `multi-browse`: Shows a collection of items (large, medium, and small items).
- *  - `hero`: Focuses on one large item with a smaller item peeking.
- *  - `uncontained`: Standard same-sized layout bleeding off the edges.
  *
- * Attributes:
- *  - layout: 'multi-browse' | 'hero' | 'uncontained'
- *  - auto: if true, dynamically calculates items sizes to fit the container without gaps.
- *  - large-width: width of large items (used in non-auto mode or as a guideline).
- *  - medium-width: width of medium items (multi-browse layout).
- *  - small-width: width of small/peeking items.
- *  - gap: spacing between elements (default 8px).
- *  - padding: leading/trailing padding (default 16px).
- *  - border-radius: radius of cards (default 28px).
- *  - header-text: header title of the carousel.
- *  - show-all: renders a "Show all" action button/link.
- *  - show-all-text: customize the text for the "Show all" action.
+ * Carousels display a collection of related items in a scrollable, horizontal list.
+ * They allow users to quickly browse through items like images, cards, or products.
+ *
+ * **M3 spec reference:** `m3-docs/components/carousel/specs.md`
+ *
+ * **Layout variants:**
+ * - `multi-browse` (default) — Shows a mix of large, medium, and small (peeking)
+ *   items. Best for exploring a large number of items.
+ * - `hero` — Focuses on one large primary item while showing a sliver of the
+ *   next item. Best for featuring important content.
+ * - `uncontained` — Standard layout where all items have the same width and
+ *   bleed off the edges of the container.
+ *
+ * **Animation & Gestures:**
+ * This component uses GSAP for smooth drag, flick, and snap animations,
+ * mirroring the high-fidelity M3 Expressive motion specs. It handles touch
+ * gestures for mobile and mouse-drag for desktop.
+ *
+ * **Auto-sizing (`auto` mode):**
+ * When `auto=true` (default), the carousel measures its own width and
+ * dynamically calculates the optimal sizes for large, medium, and small items
+ * based on the active `layout` to ensure they fit perfectly without awkward gaps
+ * or clipping at the edges.
+ *
+ * @example
+ * ```html
+ * <!-- Declarative usage via DOM properties (recommended) -->
+ * <moni-carousel layout="hero"></moni-carousel>
+ * <script>
+ *   const carousel = document.querySelector('moni-carousel');
+ *   carousel.items = [
+ *     { title: 'Item 1', img: '/img1.jpg', href: '/link1' },
+ *     { title: 'Item 2', img: '/img2.jpg' }
+ *   ];
+ * </script>
+ *
+ * <!-- Slot-based usage (for SSR or simple static content) -->
+ * <moni-carousel layout="uncontained">
+ *   <div slot="item">
+ *     <img src="/img1.jpg" />
+ *     <h3>Static Item</h3>
+ *   </div>
+ * </moni-carousel>
+ * ```
+ *
+ * @slot item - Alternative to the `items` property. Slot individual HTML elements
+ *              instead of passing data objects.
+ *
+ * @csspart carousel - The outer wrapper.
+ * @csspart track    - The scrolling track element.
+ * @csspart item     - Individual carousel item containers.
+ * @csspart img      - The image elements inside the items.
+ * @csspart title    - The title text elements inside the items.
  */
 @customElement('moni-carousel')
 export class MoniCarousel extends MoniElement {

package/src/components/moni-checkbox.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-checkbox.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,35 +12,122 @@ import { live } from 'lit/directives/live.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Checkbox that faithfully ports BeerCSS's `.checkbox` styles.
+ * Material Design 3 Checkbox component.
+ *
+ * Checkboxes allow users to select one or more items from a set, or toggle
+ * a single binary option. They are visual-only shells — the consumer is
+ * responsible for wiring up form submission and validation logic.
+ *
+ * **Visual architecture (BeerCSS pattern):**
+ * The native `<input type="checkbox">` occupies real layout space (16×16 minimum)
+ * but is visually hidden via `opacity: 0`. A `<span>` sibling rendered after
+ * the input holds two pseudo-elements:
+ * - `::before` — the visible checkbox icon (Material Symbols ligature).
+ * - `::after`  — the hover/focus state layer ripple ring.
+ *
+ * The `::before` content switches between:
+ * - `'check_box_outline_blank'` (unchecked)
+ * - `'check_box'` (checked)
+ * - `'indeterminate_check_box'` (native indeterminate state)
+ *
+ * **Form integration:**
+ * Setting `name` and `value` passes them to the native `<input>` element,
+ * enabling participation in HTML form submissions.
  *
- * BeerCSS architecture:
- *  - `.checkbox` is inline-flex, aligns items center
- *  - `input` has width/height = --_size, opacity: 0  (occupies real space, no absolute!)
- *  - `span::before` is the visible checkbox box (position: absolute, inset from the input)
- *  - `span::after` is the ripple hover effect
- *  - Content is set via CSS: "check_box_outline_blank" / "check_box" (Material Symbols font)
+ * @fires change - Bubbles and is composed. Fired when the checkbox is toggled.
+ *                 The consumer can read `element.checked` for the new state.
  *
- * Attributes:
- *  - label:    text label
- *  - checked:  present → input is checked
- *  - disabled: present → input is disabled
- *  - size:     small | medium (default) | large | extra
- *  - name:     forwarded to input.name
- *  - value:    forwarded to input.value
+ * @example
+ * ```html
+ * <moni-checkbox label="Accept terms" name="terms" value="yes"></moni-checkbox>
+ *
+ * <script>
+ *   document.querySelector('moni-checkbox').addEventListener('change', (e) => {
+ *     console.log('checked:', e.target.checked);
+ *   });
+ * </script>
+ * ```
+ *
+ * @csspart checkbox - The outer `<label>` element.
  */
 @customElement('moni-checkbox')
 export class MoniCheckbox extends MoniElement {
+	/**
+	 * Text label displayed to the right of the checkbox icon.
+	 *
+	 * When non-empty, the label is rendered as a text node inside the `<span>`.
+	 * When empty, the default slot is rendered instead, allowing slotted HTML.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) label = '';
+
+	/**
+	 * Whether the checkbox is currently checked.
+	 *
+	 * Reflected as an attribute so CSS attribute selectors and external state
+	 * readers can observe the checked state without accessing the JS property.
+	 * Synced to the native input via `updated()`.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) checked = false;
+
+	/**
+	 * When `true`, the native input is disabled: the checkbox is not interactive
+	 * and renders at 50% opacity.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) disabled = false;
+
+	/**
+	 * Visual size of the checkbox icon.
+	 *
+	 * Maps to the `--_size` custom property which controls both the invisible
+	 * input's hit area and the visible `::before` icon size.
+	 *
+	 * | Value      | `--_size` |
+	 * |------------|-----------|
+	 * | `'small'`  | 1rem      |
+	 * | `'medium'` | 1.5rem    |
+	 * | `'large'`  | 2rem      |
+	 * | `'extra'`  | 2.5rem    |
+	 *
+	 * @default 'medium'
+	 */
 	@property({ reflect: true })
 	size: 'small' | 'medium' | 'large' | 'extra' = 'medium';
+
+	/**
+	 * Forwarded to the native `<input name>` attribute.
+	 * Required for grouping checkboxes within a form.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) name = '';
+
+	/**
+	 * Forwarded to the native `<input value>` attribute.
+	 * The value submitted in a form when this checkbox is checked.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) value = '';
 
+	/** Direct reference to the native input element for programmatic access. */
 	@query('input') private _input!: HTMLInputElement;
 
+	/**
+	 * Syncs `checked` and `disabled` back to the native input element after
+	 * Lit's render cycle, ensuring the DOM stays in sync with component state.
+	 *
+	 * This is necessary because Lit's `.property=${value}` binding updates the
+	 * DOM property, but the `live()` directive and direct property assignment
+	 * are more reliable for boolean inputs across browser implementations.
+	 *
+	 * @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;
@@ -159,11 +253,28 @@ export class MoniCheckbox extends MoniElement {
 		`
 	];
 
+	/**
+	 * Handles the native input's `change` event.
+	 *
+	 * Reads the new checked state from the input and re-dispatches a composed
+	 * `'change'` event so the signal crosses shadow DOM boundaries and can be
+	 * heard by 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;
 		this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
 	}
 
+	/**
+	 * Renders the accessible checkbox label structure.
+	 *
+	 * The `<label>` wraps the hidden `<input>` and a `<span>` so that clicking
+	 * anywhere on the label area (including the text) toggles the checkbox.
+	 * The `has-label` class on the span adds left padding to separate the icon
+	 * from the label text.
+	 */
 	override render() {
 		return html`<label part="checkbox">
 			<input

package/src/components/moni-chip.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-chip.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 { MoniElement, sharedStyles } from './_base/index.js';
@@ -5,35 +12,55 @@ import './moni-icon.js';
 import './moni-progress.js';
 
 /**
- * Visual-only chip. Renders a native `<button>` styled per Material 3 Expressive.
+ * Material Design 3 Chip component.
+ *
+ * Chips are compact, interactive elements that represent actions, filters,
+ * attributes, or user inputs. They are visual-only shells — the consumer
+ * owns all state management (selection, removal, active filter state).
+ *
+ * **M3 spec reference:** `m3-docs/components/chips/specs.md`
+ *
+ * **Variants:**
+ * - `assist` (default) — Smart or suggested actions. Uses `var(--outline)` border
+ *   to ensure 3:1 contrast per the M3 accessibility spec. Alias: `outlined`.
+ * - `filter` — Filters for a content collection. Shows a leading checkmark when
+ *   `selected`. Alias: `fill`.
+ * - `input` — Represents discrete user input (tags, tokens). Adds a trailing
+ *   remove icon when `removable`.
+ * - `suggestion` — Product-generated suggestions. Outlined, no icons.
+ *
+ * **M3 measurements:**
+ * - Default height: 32dp (`small` size = M3 spec baseline).
+ * - Corner radius: 8dp.
+ * - Icon size: 18dp.
+ * - `medium` and `large` sizes are Moni extensions with larger touch targets.
+ *
+ * **Accessibility:**
+ * `assist` and `suggestion` chips use `var(--outline)` for their stroke to
+ * guarantee 3:1 contrast against the surface background at rest.
+ * `filter` and `input` use `outline-variant` at rest but achieve contrast
+ * through the `secondary-container` fill when selected.
+ *
+ * @fires remove - Bubbles and is composed. Fired when the trailing remove
+ *                 icon is clicked on an `input` chip with `removable`.
+ *
+ * @example
+ * ```html
+ * <!-- Filter chip with selected state -->
+ * <moni-chip variant="filter" selected>Technology</moni-chip>
  *
- * M3 spec (`m3-docs/components/chips/specs.md`) defines **4 variants**:
- *  - **assist**     — smart/automated actions; outlined; `outline` 1dp stroke.
- *  - **filter**     — filters for a collection; outlined; leading check when selected.
- *  - **input**      — discrete user input; outlined; trailing remove icon.
- *  - **suggestion** — product-generated suggestions; outlined; no icons.
+ * <!-- Input chip (tag/token) -->
+ * <moni-chip variant="input" removable icon="label">TypeScript</moni-chip>
  *
- * All variants share M3 measurements: 32dp height, 8dp corner, 18dp icon.
- * Container height scales with `size` (`small` = 32dp = M3 default,
- * `medium`/`large` are Moni extensions with larger touch targets).
+ * <!-- Assist chip with icon -->
+ * <moni-chip icon="directions_car">Get directions</moni-chip>
+ * ```
  *
- * **A11y** — `assist` and `suggestion` use `var(--outline)` for the
- * stroke to ensure 3:1 contrast (per `m3-docs/components/chips/accessibility.md`
- * § *Showing chip interactivity*). `filter` and `input` use `outline-variant`
- * for the resting state but show a clear `secondary-container` background
- * when selected, passing contrast.
+ * @slot default   - The chip label text.
+ * @slot icon      - Override for the leading icon (alternative to the `icon` attribute).
  *
- * Attributes:
- *  - variant:   assist (default) | filter | input | suggestion
- *               | outlined (alias for assist) | fill (alias for filter)
- *  - size:      small (default, 32dp = M3) | medium | large
- *  - shape:     round (default) | square | circle | no-round
- *               | left-round | right-round | top-round | bottom-round
- *  - selected:  present → background uses secondary-container (M3 filter/input)
- *  - removable: present → adds a trailing ✕ icon (M3 input chip, visual only)
- *  - disabled:  present → native disabled
- *  - loading:   present → shows indeterminate circular progress
- *  - icon:      Material Symbols name (leading icon)
+ * @csspart chip   - The inner `<button>` element.
+ * @csspart label  - The label `<span>` element.
  */
 @customElement('moni-chip')
 export class MoniChip extends MoniElement {

package/src/components/moni-color-field.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-color-field.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css, nothing } from 'lit';
 import { customElement, property, query } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
@@ -5,12 +12,44 @@ import { classMap } from 'lit/directives/class-map.js';
 import { MoniElement, sharedStyles, fieldStyles } from './_base/index.js';
 
 /**
- * Visual-only color field. Renders a hidden `<input type="color">` plus a
- * preview swatch and a read-only text display of the current value.
+ * Material Design 3 Color Field component.
+ *
+ * A specialized text field for color input that combines a native
+ * `<input type="color">` with a read-only text display of the selected
+ * hex value, wrapped in the standard M3 field shell.
+ *
+ * **Visual architecture:**
+ * Extends the field styling pattern used by `<moni-text-field>`. The
+ * leading icon slot is replaced by a circular color swatch (`.swatch`)
+ * which is absolutely positioned over an invisible native color input.
+ * Clicking the swatch opens the system color picker. The text input portion
+ * displays the selected hex code and is strictly `readOnly`.
+ *
+ * **State syncing:**
+ * The component listens to the native `change` event on the color input,
+ * updates the `value` property, and re-dispatches a composed `'change'` event.
+ * It does not listen to `input` (continuous drag in the color picker) to avoid
+ * excessive event firing, but consumers can attach their own `input` listeners
+ * directly to the element if live preview is needed.
+ *
+ * @fires change - Bubbles and is composed. Fired when the color picker closes
+ *                 and the value is committed. Read `element.value`.
+ *
+ * @example
+ * ```html
+ * <moni-color-field
+ *   label="Theme Color"
+ *   name="primaryColor"
+ *   value="#6750a4"
+ *   variant="outlined"
+ * ></moni-color-field>
+ * ```
  *
- * Attributes:
- *  - name, label, value, variant, size, shape, disabled, helper, error,
- *    error-text, placeholder — see moni-text-field.
+ * @csspart field       - The outer `.field` div container.
+ * @csspart swatch      - The circular color preview element.
+ * @csspart input-color - The native, visually hidden `<input type="color">`.
+ * @csspart input-text  - The native `<input type="text">` displaying the hex code.
+ * @csspart label       - The floating `<label>` element.
  */
 @customElement('moni-color-field')
 export class MoniColorField extends MoniElement {