@moni-labs/moni-ui 0.2.0 → 0.3.0

package/src/components/moni-switch.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-switch.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,33 +12,111 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 
 /**
- * Switch styled per Material Design 3 specs.
+ * Material Design 3 Switch component.
+ *
+ * Switches toggle the state of a single setting on or off. They are the
+ * binary on/off equivalent of a checkbox, but optimized for toggling a
+ * single state rather than selecting from a list.
+ *
+ * **M3 spec reference:** `m3-docs/components/switch/specs.md`
+ *
+ * **M3 measurements:**
+ * - Track: 52dp × 32dp, 2dp border, full-radius pill shape.
+ * - Handle (thumb): 16dp unselected → 24dp selected → 28dp pressed.
+ * - State layer: 40dp circular ripple on hover/focus/pressed states.
+ * - Icon (optional): 16dp icon rendered inside the thumb when `icon` is set.
+ *
+ * **Visual architecture:**
+ * Like `<moni-checkbox>`, the native `<input type="checkbox" role="switch">`
+ * occupies real layout space but is visually hidden via `opacity: 0`. Two
+ * `<span>` pseudo-elements render the track (`::after`) and thumb (`::before`).
+ * When `icon=true`, `<i>` elements render `close` and `check` glyphs inside
+ * the thumb, with visibility toggled via CSS based on the checked state.
  *
- * M3 measurements (`m3-docs/components/switch/specs.md`):
- *  - Track: 52dp × 32dp, 2dp outline, full corner radius
- *  - Handle (thumb): 16dp unselected, 24dp selected, 28dp pressed
- *  - State layer: 40dp circular ripple on hover/focus/pressed
- *  - Icon (optional): 16dp on selected and/or unselected handle
+ * @fires change - Bubbles and is composed. Fired when the switch is toggled.
+ *                 Read `element.checked` for the new state.
  *
- * Attributes:
- *  - label:    text label (displayed to the right of the switch)
- *  - checked:  present
- *  - disabled: present
- *  - icon:     present → renders check/close icons inside the thumb
- *  - name:     forwarded to input.name
- *  - value:    forwarded to input.value
+ * @example
+ * ```html
+ * <moni-switch label="Dark mode" name="dark-mode"></moni-switch>
+ * <moni-switch icon checked label="Notifications"></moni-switch>
+ *
+ * <script>
+ *   document.querySelector('moni-switch').addEventListener('change', (e) => {
+ *     console.log('enabled:', e.target.checked);
+ *   });
+ * </script>
+ * ```
+ *
+ * @csspart switch - The outer `<label>` element containing the switch.
  */
 @customElement('moni-switch')
 export class MoniSwitch extends MoniElement {
+	/**
+	 * Text label displayed to the right of the switch.
+	 *
+	 * When non-empty, renders as a padded text span after the track.
+	 * When empty, the default slot is rendered, allowing custom HTML labels.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) label = '';
+
+	/**
+	 * Whether the switch is in the "on" (checked) state.
+	 *
+	 * When `true`:
+	 * - Track fills with `--primary` color.
+	 * - Thumb grows from 16dp to 24dp and slides to the trailing edge.
+	 * - Thumb color changes to `--on-primary`.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) checked = false;
+
+	/**
+	 * When `true`, the switch is non-interactive and renders at 50% opacity.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) disabled = false;
+
+	/**
+	 * When `true`, renders icon glyphs inside the thumb.
+	 *
+	 * Uses Material Symbols ligatures:
+	 * - Unchecked state: `close` icon.
+	 * - Checked state: `check` icon.
+	 *
+	 * The icon size (16dp) is set via the `--_thumb` CSS custom property.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) icon = false;
+
+	/**
+	 * Forwarded to the native `<input name>` attribute for form participation.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) name = '';
+
+	/**
+	 * Forwarded to the native `<input value>` attribute.
+	 * The value submitted in a form when this switch 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` imperatively to the native input after render.
+	 *
+	 * @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;
@@ -39,6 +124,14 @@ export class MoniSwitch extends MoniElement {
 		}
 	}
 
+	/**
+	 * Handles the native input `change` event.
+	 *
+	 * Updates `this.checked` and re-dispatches a composed `'change'` event
+	 * so it bubbles across shadow DOM boundaries.
+	 *
+	 * @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 }));

package/src/components/moni-tab.ts

@@ -1,17 +1,45 @@
+/**
+ * @file components/moni-tab.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';
 import './moni-icon.js';
 
 /**
- * Visual-only tab. Renders an `<a>` styled with the BeerCSS `.tabs > a`
- * helper.
+ * Material Design 3 Tab component.
+ *
+ * An individual interactive tab element designed to be placed inside a
+ * `<moni-tabs>` container. Tabs organize content across different screens,
+ * data sets, and other interactions.
+ *
+ * **M3 spec reference:** `m3-docs/components/tabs/specs.md`
+ *
+ * **Visual layout & interaction:**
+ * Internally renders as an `<a>` element to support native link behavior when
+ * an `href` is provided, but behaves visually as a tab button. It displays a
+ * text label and an optional Material icon. If the parent `<moni-tabs>` has the
+ * `vertical` attribute set, the layout automatically adjusts to stack the icon
+ * above the text.
+ *
+ * **State:**
+ * The `active` attribute highlights the tab, applying the primary color to the
+ * text and rendering the active indicator line (handled via CSS in the parent
+ * container or pseudo-elements).
+ *
+ * @example
+ * ```html
+ * <moni-tabs>
+ *   <moni-tab active icon="home" label="Home"></moni-tab>
+ *   <moni-tab icon="settings" label="Settings" href="/settings"></moni-tab>
+ * </moni-tabs>
+ * ```
  *
- * Attributes:
- *  - active: present → active style
- *  - icon:   Material Symbols name
- *  - label:  tab text
- *  - href:   link target
+ * @csspart tab - The inner `<a>` element acting as the tab button.
  */
 @customElement('moni-tab')
 export class MoniTab extends MoniElement {

package/src/components/moni-tabs.ts

@@ -1,20 +1,59 @@
+/**
+ * @file components/moni-tabs.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 tab bar. Renders a `<nav>` styled with the BeerCSS `.tabs`
- * helper.
+ * Material Design 3 Tabs container component.
+ *
+ * A navigational container that groups multiple `<moni-tab>` elements. Tabs
+ * organize content into high-level categories and allow the user to switch
+ * between them.
+ *
+ * **M3 spec reference:** `m3-docs/components/tabs/specs.md`
+ *
+ * **Modes (Primary vs Secondary):**
+ * - `primary` (default): Used for top-level navigation at the highest hierarchy,
+ *   often placed directly below a top app bar. They span the full width and
+ *   feature a prominent active indicator.
+ * - `secondary`: Used for deeper content hierarchies within a specific area
+ *   or page. They are typically more subtle.
+ *
+ * **Layout & Alignment:**
+ * - `scrollable`: If the number of tabs exceeds the container width, this
+ *   enables horizontal scrolling (`overflow-x: auto`) rather than squishing.
+ * - `align`: Controls how the tabs are distributed (`default` space-around,
+ *   `left`, `center`, or `right`).
+ * - `vertical`: Stacks the icon above the text label inside the child tabs.
+ *
+ * **Active Indicator:**
+ * The `indicator-size` attribute allows customizing the width of the active
+ * underline indicator (`default` fits the tab content, `min` is narrow, `max`
+ * fills the full tab width).
+ *
+ * @example
+ * ```html
+ * <!-- Primary, scrollable tabs -->
+ * <moni-tabs scrollable>
+ *   <moni-tab active label="Flights"></moni-tab>
+ *   <moni-tab label="Trips"></moni-tab>
+ *   <moni-tab label="Explore"></moni-tab>
+ * </moni-tabs>
  *
- * Attributes:
- *  - mode:      primary (default) | secondary
- *  - scrollable: present → overflow-x: auto
- *  - align:     default (space-around) | left | center | right
- *  - indicator: default (full) | min | max
- *  - vertical:  present → icon above label
+ * <!-- Secondary, centered tabs with vertical layout -->
+ * <moni-tabs mode="secondary" align="center" vertical>
+ *   <moni-tab active icon="video_camera_front" label="Video"></moni-tab>
+ *   <moni-tab icon="photo_camera" label="Photo"></moni-tab>
+ * </moni-tabs>
+ * ```
  *
- * Slots:
- *  - default: <moni-tab> children
+ * @slot default - `<moni-tab>` child elements.
  */
 @customElement('moni-tabs')
 export class MoniTabs extends MoniElement {

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

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-text-field.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, nothing } from 'lit';
 import { customElement, property, query } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
@@ -7,17 +14,56 @@ import './moni-icon.js';
 import './moni-progress.js';
 
 /**
- * Visual-only text field. Renders the `.field` family of BeerCSS helpers
- * with a native `<input>`.
+ * Material Design 3 Text Field component.
+ *
+ * A full-featured input field that wraps a native `<input>` inside the M3
+ * field shell (`.field` class from `fieldStyles`). Supports floating labels,
+ * filled and outlined variants, leading/trailing icons, helper text, and
+ * error states.
+ *
+ * **M3 spec reference:** `m3-docs/components/text-fields/specs.md`
+ *
+ * **Visual architecture:**
+ * Uses `fieldStyles` for the complete CSS field shell. The field container
+ * is a `<div class="field [modifiers]">` wrapping:
+ * 1. Optional leading icon.
+ * 2. Native `<input>` element.
+ * 3. Floating `<label>` (when `label` is set).
+ * 4. Optional trailing icon or loading spinner.
+ * 5. `<output>` for helper/error text.
+ *
+ * **Visual-only contract:**
+ * This component does **not** listen to `@input` events to sync the `value`
+ * attribute back from the underlying `<input>`. Consumers must either:
+ * - Submit the native form (the `<input name>` participates in form submission).
+ * - Listen to `change` or `input` events via standard DOM event handling.
+ * - Use a framework binding (e.g. `bind:value` in Svelte, `v-model` in Vue).
+ *
+ * @example
+ * ```html
+ * <moni-text-field
+ *   label="Email address"
+ *   type="email"
+ *   name="email"
+ *   icon="mail"
+ *   variant="outlined"
+ *   helper="We'll never share your email."
+ * ></moni-text-field>
  *
- * This component is **visual-only**: it does NOT listen to `@input` to
- * sync the `value` attribute back from the underlying input. Consumers
- * either use form submission or wire their own change handling.
+ * <moni-text-field
+ *   label="Amount"
+ *   type="number"
+ *   prefix="$"
+ *   error
+ *   error-text="Value must be positive"
+ * ></moni-text-field>
+ * ```
  *
- * Attributes:
- *  - name, label, value, variant, size, shape, type, icon, trailing-icon,
- *    prefix, suffix, helper, error, error-text, disabled, placeholder — see below.
- *  - loading:   present → shows indeterminate circular progress
+ * @csspart field         - The outer `.field` div container.
+ * @csspart input         - The native `<input>` element.
+ * @csspart label         - The floating `<label>` element.
+ * @csspart helper        - The helper `<output>` element.
+ * @csspart error-output  - The error `<output>` element.
  */
 @customElement('moni-text-field')
 export class MoniTextField extends MoniElement {

package/src/components/moni-textarea.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-textarea.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, nothing } from 'lit';
 import { customElement, property, query } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
@@ -7,26 +14,50 @@ import './moni-icon.js';
 import './moni-progress.js';
 
 /**
- * Visual-only textarea. Same field shell as moni-text-field but renders a
- * `<textarea>`. Visual-only: no `@input` listener.
+ * Material Design 3 Textarea component.
+ *
+ * A multi-line text input field designed for collecting longer amounts of text,
+ * such as comments, descriptions, or messages.
+ *
+ * **M3 spec reference:** `m3-docs/components/text-fields/specs.md`
+ *
+ * **Visual architecture:**
+ * It shares the exact same `.field` shell and styling engine as
+ * `<moni-text-field>`, but internally renders a native `<textarea>` instead
+ * of an `<input>`. This ensures visual consistency across all form elements
+ * regarding floating labels, helper text, error states, and icons.
+ *
+ * **Character Counter:**
+ * If the `maxlength` attribute is set, the textarea automatically displays
+ * a character counter (`{current length} / {maxlength}`) positioned at the
+ * trailing edge of the supporting text area (bottom right). This can be
+ * suppressed by setting the `no-counter` attribute.
+ *
+ * **State management:**
+ * This component is purely visual and presentational. It reflects attributes
+ * down to the native textarea, but it does NOT attach internal `@input` or
+ * `@change` listeners. Consumers should attach standard DOM listeners directly
+ * to this element to capture user input, just as they would with a native
+ * textarea.
+ *
+ * @example
+ * ```html
+ * <!-- Standard filled textarea -->
+ * <moni-textarea label="Description" rows="4"></moni-textarea>
  *
- * M3 spec (`m3-docs/components/text-fields/specs.md`): the textarea supports
- * both **filled** and **outlined** variants. When `maxlength` is set, a
- * character counter is shown next to the supporting text
- * (`{value.length} / {maxlength}`).
+ * <!-- Outlined textarea with character counter -->
+ * <moni-textarea
+ *   variant="outlined"
+ *   label="Bio"
+ *   maxlength="160"
+ * ></moni-textarea>
+ * ```
  *
- * Attributes:
- *  - name, label, value, variant, size, shape, disabled, helper, error,
- *    error-text, placeholder — see moni-text-field.
- *  - icon:           leading Material Symbols name
- *  - trailing-icon:  trailing Material Symbols name
- *  - prefix:         short text rendered before the input (e.g. "https://")
- *  - suffix:         short text rendered after the input (e.g. ".com")
- *  - loading:        present → shows indeterminate circular progress
- *  - rows:           native textarea rows attribute (default 3)
- *  - maxlength:      when set, displays a character counter
- *                    (auto-shown; can be hidden via `no-counter`)
- *  - no-counter:     suppress the character counter even when maxlength is set
+ * @csspart field     - The outer `.field` div container.
+ * @csspart input     - The native `<textarea>` element.
+ * @csspart label     - The floating `<label>` element.
+ * @csspart helper    - The helper/error text area.
+ * @csspart counter   - The character counter element.
  */
 @customElement('moni-textarea')
 export class MoniTextarea extends MoniElement {

package/src/components/moni-time-picker.ts

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-time-picker.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css, PropertyValues } from 'lit';
 import { customElement, property, state, query } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
@@ -5,18 +12,42 @@ import './moni-icon.js';
 import './moni-button.js';
 
 /**
- * Material Design 3 Time Picker Component.
- * Supports interactive clock face (dial) and manual keyboard input.
+ * Material Design 3 Time Picker component.
+ *
+ * A highly interactive control that allows users to select a specific time.
+ * It provides two distinct input modes:
+ * 1. **Dial mode:** An interactive clock face where users can drag or click
+ *    to select hours and minutes.
+ * 2. **Input mode:** Standard text inputs for precise keyboard entry.
+ *
+ * **M3 spec reference:** `m3-docs/components/time-pickers/specs.md`
+ *
+ * **Time formats & modes:**
+ * - The `value` property expects and always outputs a 24-hour formatted string
+ *   (`HH:MM`, e.g., `"14:30"`).
+ * - Setting `use-24-hour` configures the visual presentation to use a 24-hour
+ *   clock dial (inner and outer rings) and removes the AM/PM toggle. Otherwise,
+ *   it uses a standard 12-hour dial with an AM/PM toggle.
+ *
+ * **Responsive design:**
+ * The `orientation` attribute configures the layout. `vertical` stacks the
+ * time display above the clock face, `horizontal` places them side-by-side,
+ * and `auto` responds to the container/viewport width automatically.
+ *
+ * @fires change - Fired when the selected time changes interactively. The
+ *                 `detail.value` contains the new time in `HH:MM` format.
+ * @fires cancel - Fired when the 'Cancel' button is clicked.
+ * @fires ok     - Fired when the 'OK' button is clicked. The `detail.value`
+ *                 contains the final confirmed time.
  *
- * Attributes:
- *  - value: Time value in "HH:MM" 24h format (default "00:00")
- *  - use24Hour: If true, uses 24-hour mode without AM/PM toggle (default false)
- *  - mode: "dial" | "input" (default "dial")
+ * @example
+ * ```html
+ * <!-- 12-hour format (AM/PM) -->
+ * <moni-time-picker value="14:30"></moni-time-picker>
  *
- * Events:
- *  - change: Fired when value changes (detail: { value })
- *  - cancel: Fired when cancel button is clicked
- *  - ok: Fired when OK button is clicked (detail: { value })
+ * <!-- 24-hour format -->
+ * <moni-time-picker use-24-hour value="14:30"></moni-time-picker>
+ * ```
  */
 @customElement('moni-time-picker')
 export class MoniTimePicker extends MoniElement {

package/src/components/moni-toolbar.ts

@@ -1,26 +1,55 @@
+/**
+ * @file components/moni-toolbar.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 Toolbar (`m3-docs/components/top-app-bar/specs.md`).
+ * Material Design 3 Top App Bar (Toolbar) component.
+ *
+ * Top app bars display information and actions at the top of a screen.
+ * They are used for branding, screen titles, navigation, and actions.
+ *
+ * **M3 spec reference:** `m3-docs/components/top-app-bar/specs.md`
+ *
+ * **Note:** This is the standard top-level toolbar. For bottom navigation
+ * bars (often used on mobile), use `<moni-app-bar>`.
+ *
+ * **Variants:**
+ * - `standard` (default): A full-width bar (64dp height) that sits flush
+ *   against the top of the screen.
+ * - `floating`: A detached bar with a 4dp margin and rounded 8dp corners,
+ *   appearing to float above the content.
  *
- * This is the larger/top-level variant. If you need the compact
- * Navigation Bar at the bottom of the screen, use `<moni-app-bar>`.
+ * **Scroll behavior:**
+ * When the `scroll` attribute is present, the toolbar visually responds to
+ * scrolling by increasing its elevation (shadow) and dynamically shifting
+ * its surface color to indicate depth over the scrolling content.
  *
- * Supported M3 types:
- *  - **standard** (default): 64dp height, flat surface color, bottom shadow.
- *  - **floating**: 4dp margin, rounded 8dp corners, elevated.
+ * @example
+ * ```html
+ * <!-- Standard toolbar with navigation and actions -->
+ * <moni-toolbar title="Inbox">
+ *   <moni-icon-button slot="leading" icon="menu"></moni-icon-button>
+ *   <moni-icon-button slot="trailing" icon="search"></moni-icon-button>
+ *   <moni-icon-button slot="trailing" icon="more_vert"></moni-icon-button>
+ * </moni-toolbar>
  *
- * Slots:
- *  - default:       title / center content.
- *  - leading:       navigation icon/button.
- *  - trailing:      action icons/buttons.
- *  - action-button: floating action button (moni-fab) anchored right.
+ * <!-- Floating toolbar with an attached FAB -->
+ * <moni-toolbar type="floating" title="Notes">
+ *   <moni-fab slot="action-button" icon="add"></moni-fab>
+ * </moni-toolbar>
+ * ```
  *
- * Attributes:
- *  - type:   standard (default) | floating
- *  - scroll: true | false (default). When true, elevation increases on scroll.
+ * @slot default       - The title text or center content.
+ * @slot leading       - Navigation icon/button placed on the far left.
+ * @slot trailing      - Action icons/buttons placed on the far right.
+ * @slot action-button - A floating action button (FAB) anchored to the right side.
  */
 @customElement('moni-toolbar')
 export class MoniToolbar extends MoniElement {

package/src/components/moni-tooltip.ts

@@ -1,36 +1,67 @@
+/**
+ * @file components/moni-tooltip.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';
 
 /**
- * Tooltip that faithfully ports BeerCSS's `.tooltip` styles and adds M3
- * Expressive semantics.
+ * Material Design 3 Tooltip component.
+ *
+ * Tooltips provide contextual text labels or rich content that appear when
+ * users hover over, focus on, or tap an element. They surface supplementary
+ * information that helps users understand interface elements without
+ * permanently occupying screen space.
+ *
+ * **M3 spec reference:** `m3-docs/components/tooltips/specs.md`
+ *
+ * **Types:**
+ * - **Plain** (default) — Text-only label for simple descriptions (max 1 line).
+ * - **Rich** (`rich` attribute) — HTML content including formatted text,
+ *   links, and icons. Rich tooltips can contain multiple lines and action links.
+ *
+ * **Placements:**
+ * - `top` (default), `top-start`, `top-end`
+ * - `bottom`, `bottom-start`, `bottom-end`
+ *
+ * **Trigger mechanism:**
+ * The tooltip uses `position: absolute` inside the parent element. The parent
+ * must have `position: relative` (set automatically via `connectedCallback`).
+ * Hover/focus events on the parent trigger the tooltip's CSS `:hover` and
+ * `:focus-within` selectors, which drive the show/hide transition.
+ *
+ * **Accessibility:**
+ * - The tooltip has `role="tooltip"`.
+ * - For keyboard accessibility, the parent should have `aria-describedby`
+ *   pointing to the tooltip's `id` attribute. The component exposes a
+ *   `tooltipId` getter for this purpose.
+ * - The `Escape` key closes rich tooltips.
  *
- * **M3 spec** (`m3-docs/components/tooltips/specs.md`):
- *  - Two types: **plain** (text only) and **rich** (HTML content).
- *  - 6 placements: top, top-start, top-end, bottom, bottom-start, bottom-end.
- *  - Trigger: hover (mouse) or focus (keyboard) on the parent.
- *  - Auto-dismiss: tooltip hides on `mouseleave` / `focusout` / `Escape`.
+ * @example
+ * ```html
+ * <!-- Plain tooltip -->
+ * <button aria-describedby="save-tip">
+ *   Save
+ *   <moni-tooltip id="save-tip" text="Ctrl+S"></moni-tooltip>
+ * </button>
  *
- * The component delegates trigger detection to the parent element (consistent
- * with the original BeerCSS port). The tooltip element is `position: absolute`
- * inside the parent so it follows the trigger naturally.
+ * <!-- Rich tooltip -->
+ * <button>
+ *   Filter
+ *   <moni-tooltip rich position="bottom">
+ *     <strong>Filter by date</strong>
+ *     <p>Select a date range to filter results.</p>
+ *   </moni-tooltip>
+ * </button>
+ * ```
  *
- * **Accessibility**:
- *  - The tooltip has `role="tooltip"` (M3 spec).
- *  - When `rich` content is used, the parent should also have
- *    `aria-describedby="<tooltip-id>"`. The component sets a unique `id` on
- *    the tooltip element and exposes it via `tooltipId` getter.
- *  - `Escape` closes the tooltip (WAI-ARIA tooltip pattern).
+ * @slot default - Rich content for the tooltip body (only used when `rich=true`).
  *
- * Attributes:
- *  - text:      tooltip text (plain tooltip)
- *  - position:  top (default) | top-start | top-end | bottom | bottom-start | bottom-end
- *  - size:      '' (default) | small | medium | large
- *  - rich:      boolean — when true, the default slot accepts arbitrary HTML
- *               for rich content (links, icons, etc.). When false (default),
- *               the slot is rendered as text only.
- *  - id:        forwarded to the tooltip element (useful for aria-describedby)
+ * @csspart tooltip - The tooltip container element.
  */
 @customElement('moni-tooltip')
 export class MoniTooltip extends MoniElement {