@moni-labs/moni-ui 0.2.0 → 0.3.0

package/src/components/moni-icon.ts

@@ -1,27 +1,97 @@
+/**
+ * @file components/moni-icon.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 icon.
+ * Visual-only icon component using Material Symbols variable font.
+ *
+ * Renders a Material Symbols glyph by its ligature name. The icon font
+ * must be loaded globally by the host document — it is not bundled with
+ * the component. Add the font via the `@moni-labs/moni-ui/styles` stylesheet
+ * or by including the Google Fonts CDN link.
+ *
+ * **Font rendering:**
+ * The icon uses `font-family: var(--font-icon)` which defaults to
+ * `'Material Symbols Rounded'`. Override `--font-icon-override` in the
+ * host document's `:root` to switch to a different icon set variant
+ * (e.g. `'Material Symbols Outlined'` or `'Material Symbols Sharp'`).
+ *
+ * **Variable font settings:**
+ * The default `font-variation-settings` is `'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 24`.
+ * Setting the `filled` attribute switches to `'FILL' 1` for the solid icon variant.
  *
- * Renders a Material Symbols glyph by name. The font must be loaded
- * globally in the host document (see `@moni-labs/moni-ui/styles`).
+ * **Color inheritance:**
+ * The icon always inherits color from its parent via `color: inherit`, making it
+ * automatically adapt to button variants, chip selected states, list item active
+ * states, and other color-context containers.
  *
- * Attributes:
- *  - name:   icon name from https://fonts.google.com/icons
- *  - size:   tiny | small | medium (default) | large | extra
- *  - filled: present → switches to the filled variant (font-variation-settings)
+ * @example
+ * ```html
+ * <!-- Basic icon -->
+ * <moni-icon name="home"></moni-icon>
  *
- * Slots:
- *  - default: fallback text if no name is given
- *  - (also accepts slotted <svg> or <img> as override)
+ * <!-- Filled large icon -->
+ * <moni-icon name="favorite" size="large" filled></moni-icon>
+ *
+ * <!-- Custom SVG override via slot -->
+ * <moni-icon>
+ *   <svg slot="default" viewBox="0 0 24 24">...</svg>
+ * </moni-icon>
+ * ```
+ *
+ * @slot default - Fallback content when `name` is empty. Accepts `<svg>` or `<img>`
+ *                 elements which are sized to 100% of the icon box.
+ *
+ * @cssproperty --font-icon-override - Overrides the icon font family at the
+ *                                     document level. Set on `:root`.
  */
 @customElement('moni-icon')
 export class MoniIcon extends MoniElement {
+	/**
+	 * Material Symbols ligature name for the icon to render.
+	 *
+	 * Use the name exactly as shown on https://fonts.google.com/icons
+	 * (e.g. `'home'`, `'settings'`, `'arrow_forward'`).
+	 * When empty, the default slot is rendered instead.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) name = '';
+
+	/**
+	 * Size of the icon bounding box.
+	 *
+	 * Maps to the `--_size` custom property:
+	 * | Value      | Size     |
+	 * |------------|----------|
+	 * | `'tiny'`   | 1rem     |
+	 * | `'small'`  | 1.25rem  |
+	 * | `'medium'` | 1.5rem   |
+	 * | `'large'`  | 1.75rem  |
+	 * | `'extra'`  | 2rem     |
+	 *
+	 * @default 'medium'
+	 */
 	@property({ reflect: true })
 	size: 'tiny' | 'small' | 'medium' | 'large' | 'extra' = 'medium';
+
+	/**
+	 * When `true`, switches to the filled variant of the icon by setting
+	 * `font-variation-settings: 'FILL' 1`.
+	 *
+	 * This works only with variable icon fonts that include the `FILL` axis
+	 * (all Material Symbols variants do). It has no effect if a different
+	 * icon font is loaded that does not support `FILL`.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) filled = false;
 
 	static override styles = [

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

@@ -1,38 +1,70 @@
+/**
+ * @file components/moni-list-item.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css, nothing } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 
 /**
- * Material 3 List Item (`m3-docs/components/lists/specs.md`).
+ * Material Design 3 List Item component.
+ *
+ * A single row within a `<moni-list>`. List items display a headline and
+ * optional supporting text, metadata, icons, or avatars.
+ *
+ * **M3 spec reference:** `m3-docs/components/lists/specs.md`
+ *
+ * **Line configurations:**
+ * The `lines` attribute configures the layout and minimum height of the item:
+ * - `lines="1"` (default) — 56dp min height. Only the headline slot is shown.
+ * - `lines="2"` — 72dp min height. Shows headline and supporting text.
+ * - `lines="3"` — 88dp min height. Shows headline, supporting text, and meta text.
+ *
+ * **Interactive behavior:**
+ * By default, items render as `<button>` elements, gaining the M3 state layer
+ * (hover, focus, and press ripple effects).
+ * If the `href` attribute is provided, the item internally renders as an `<a>`
+ * element, allowing native link routing and interactions while preserving the
+ * list item styling.
+ *
+ * **Visual elements:**
+ * - `icon` (attribute) — Material Symbol name for the leading icon (24dp).
+ * - `avatar` (attribute) — URL for a leading circular image (40dp).
+ * - `trailing-icon` (attribute) — Material Symbol name for the trailing icon.
  *
- * One row in a `<moni-list>`. Supports up to 3 lines of text:
- *  - line 1: headline (required).
- *  - line 2: supporting text (optional).
- *  - line 3: trailing meta text (optional).
+ * @example
+ * ```html
+ * <!-- 1-line item with icon -->
+ * <moni-list-item icon="inbox">
+ *   Inbox
+ * </moni-list-item>
  *
- * Plus optional leading/trailing icons or avatars.
+ * <!-- 2-line item with avatar and trailing meta -->
+ * <moni-list-item lines="2" avatar="/user.jpg">
+ *   Ali Connors
+ *   <span slot="supporting">Brunch this weekend?</span>
+ *   <span slot="trailing-meta">10 min</span>
+ * </moni-list-item>
  *
- * M3 measurements:
- *  - Min height: 56dp (1-line), 72dp (2-line), 88dp (3-line).
- *  - Horizontal padding: 16dp.
- *  - Vertical padding: 8dp top/bottom (so 1-line is 56dp tall).
- *  - Leading icon/avatar size: 24dp.
+ * <!-- Link item -->
+ * <moni-list-item href="/settings" icon="settings">
+ *   Settings
+ * </moni-list-item>
+ * ```
  *
- * Attributes:
- *  - lines: 1 (default) | 2 | 3
- *  - icon:   Material Symbols name (leading icon)
- *  - avatar: URL for a leading image
- *  - trailing-icon: Material Symbols name (trailing icon)
- *  - active:   present → background uses secondary-container
- *  - disabled: present → opacity 38%, cursor not-allowed
- *  - href:     present → renders as <a>; otherwise <button>
+ * @slot default       - Headline text (Line 1).
+ * @slot supporting    - Supporting text (Line 2, requires `lines>=2`).
+ * @slot meta          - Additional meta text (Line 3, requires `lines=3`).
+ * @slot trailing-meta - Small text displayed on the far right edge.
  *
- * Slots:
- *  - default:   headline (line 1)
- *  - supporting:line 2 text
- *  - meta:      line 3 text
- *  - trailing-meta: trailing small text (right side)
+ * @csspart item          - The outer `<button>` or `<a>` container.
+ * @csspart leading-icon  - Container for the leading icon/avatar.
+ * @csspart text          - Container for the multi-line text block.
+ * @csspart trailing-icon - Container for the trailing icon.
  */
 @customElement('moni-list-item')
 export class MoniListItem extends MoniElement {

package/src/components/moni-list.ts

@@ -1,24 +1,49 @@
+/**
+ * @file components/moni-list.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 List (`m3-docs/components/lists/specs.md`).
+ * Material Design 3 List component.
+ *
+ * Lists are continuous, vertical indexes of text or images. They are
+ * container elements that provide structural grouping and optional
+ * divider lines for `<moni-list-item>` children.
+ *
+ * **M3 spec reference:** `m3-docs/components/lists/specs.md`
+ *
+ * **Container role:**
+ * The list itself does not apply padding or margins to its children. Spacing
+ * and internal padding are controlled entirely by the `<moni-list-item>`
+ * elements themselves to ensure proper hit targets and alignment.
  *
- * A list is a continuous vertical index of text and images. The
- * container itself is purely structural (no padding); spacing and
- * dividers are controlled by `<moni-list-item>` children.
+ * **Variants:**
+ * - `default` (empty string) — A clean, borderless list container.
+ * - `border` — Adds a bottom border to the list and displays horizontal
+ *   dividers (`outline-variant` color) between list items.
  *
- * Two visual variants:
- *  - **default**: 8dp top/bottom padding between items (handled by items).
- *  - **border**:  dividers drawn between items.
+ * @example
+ * ```html
+ * <!-- Standard list -->
+ * <moni-list>
+ *   <moni-list-item headline="Item 1"></moni-list-item>
+ *   <moni-list-item headline="Item 2"></moni-list-item>
+ * </moni-list>
  *
- * Attributes:
- *  - variant: '' (default) | border
- *  - rounded: when set, items use a 4dp corner radius.
+ * <!-- List with dividers and rounded items -->
+ * <moni-list variant="border" rounded>
+ *   <moni-list-item icon="inbox" headline="Inbox"></moni-list-item>
+ *   <moni-list-item icon="send" headline="Sent"></moni-list-item>
+ * </moni-list>
+ * ```
  *
- * Slots:
- *  - default: <moni-list-item> children.
+ * @slot default - `<moni-list-item>` elements.
  */
 @customElement('moni-list')
 export class MoniList extends MoniElement {

package/src/components/moni-loading-indicator.ts

@@ -1,21 +1,49 @@
+/**
+ * @file components/moni-loading-indicator.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css, unsafeCSS } from 'lit';
 import { customElement, property, query } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import { loadingIndicatorPolygons } from './loading-shapes.js';
 
 /**
- * Shape-shifting indeterminate loading indicator based on Material 3 Expressive spec.
+ * Material Design 3 Loading Indicator component.
+ *
+ * An indeterminate loading indicator that visually represents an unspecified
+ * wait time. Unlike standard circular spinners, this component uses a morphing
+ * polygon animation that shifts between shapes (circle, rounded square, etc.)
+ * in accordance with the high-fidelity M3 Expressive motion specifications.
+ *
+ * **Variants:**
+ * - `uncontained` (default) — A standalone morphing shape that inherits color
+ *   from its text context (or defaults to `primary`).
+ * - `contained` — The morphing shape is placed inside a circular container
+ *   with a distinct background color, useful for high-contrast loading states
+ *   or overlaying imagery.
+ *
+ * **Animation & Accessibility:**
+ * The component manages its own SVG `<animate>` tags. The animation is
+ * automatically started/stopped via `connectedCallback`/`disconnectedCallback`
+ * to save CPU cycles when the element is off-screen. It applies standard ARIA
+ * roles (`role="progressbar"`) and value attributes to ensure screen readers
+ * identify it correctly as an indeterminate loading state.
+ *
+ * @example
+ * ```html
+ * <!-- Uncontained indicator -->
+ * <moni-loading-indicator></moni-loading-indicator>
  *
- * Attributes:
- *  - variant: 'uncontained' (default) | 'contained'
+ * <!-- Contained indicator (default container is secondary-container) -->
+ * <moni-loading-indicator variant="contained"></moni-loading-indicator>
+ * ```
  *
- * CSS custom properties for customization:
- *  - --moni-loading-indicator-size: Size of the active indicator (default: 2.375rem)
- *  - --moni-loading-indicator-active-color: Active indicator color in uncontained mode (default: var(--primary))
- *  - --moni-loading-indicator-contained-active-color: Active indicator color in contained mode (default: var(--on-primary-container))
- *  - --moni-loading-indicator-contained-container-color: Background color of container in contained mode (default: var(--secondary-container))
- *  - --moni-loading-indicator-container-shape: Border radius of container in contained mode (default: 9999px)
- *  - --moni-loading-indicator-container-size: Container size (default: 3rem)
+ * @csspart container - The outer `.container` wrapper.
+ * @csspart svg       - The inner `<svg>` element.
+ * @csspart shape     - The `<path>` element that morphs.
  */
 @customElement('moni-loading-indicator')
 export class MoniLoadingIndicator extends MoniElement {

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

@@ -1,17 +1,41 @@
+/**
+ * @file components/moni-menu-item.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 menu item. Renders an `<li>` styled with the BeerCSS
- * `menu > li` rule.
+ * Material Design 3 Menu Item component.
+ *
+ * A single interactive item within a `<moni-menu>` or `<moni-context-menu>`.
+ * It provides standard M3 menu item styling, hover states, and optional
+ * leading icons.
+ *
+ * **M3 spec reference:** `m3-docs/components/menus/specs.md`
+ *
+ * **Interaction states:**
+ * - Hover: applies an opacity layer.
+ * - Active (`active=true`): applies a `tertiary-container` background highlight,
+ *   useful for indicating the currently selected option in a list.
+ * - Disabled (`disabled=true`): reduces opacity and disables pointer events.
+ *
+ * @example
+ * ```html
+ * <moni-menu-item icon="edit">Edit text</moni-menu-item>
+ * <moni-menu-item icon="content_copy" disabled>Copy</moni-menu-item>
+ * <moni-menu-item active>Currently selected</moni-menu-item>
+ * ```
+ *
+ * @slot default - The text label for the menu item.
  *
- * Attributes:
- *  - active:    present → tertiary-container highlight
- *  - disabled:  present
- *  - icon:      Material Symbols name
- *  - label:     item text
+ * @csspart item - The outer `<li>` element.
+ * @csspart icon - The container for the leading icon.
  */
 @customElement('moni-menu-item')
 export class MoniMenuItem extends MoniElement {

package/src/components/moni-menu.ts

@@ -1,40 +1,66 @@
+/**
+ * @file components/moni-menu.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';
 
 /**
- * Menu that faithfully ports BeerCSS's `menu` styles.
+ * Material Design 3 Menu component.
+ *
+ * Menus display a list of choices on a temporary surface. They appear when
+ * users interact with a button, action, or other control.
+ *
+ * **M3 spec reference:** `m3-docs/components/menus/guidelines.md`
+ *
+ * **Positioning architecture:**
+ * The menu uses `position: absolute` relative to its nearest positioned
+ * ancestor. The component's `:host` uses `display: contents`, meaning the
+ * inner `<menu>` element directly participates in the consumer's layout context.
+ * **Crucial:** The consumer must apply `position: relative` to the wrapper
+ * element that contains both the trigger and the `<moni-menu>`.
+ *
+ * **Auto-flip positioning:**
+ * Per M3 guidelines, menus should flip to the opposite side of the anchor
+ * if they overflow the viewport.
+ * - **Modern browsers (Chrome/Edge 125+, Safari 18+):** Uses CSS anchor
+ *   positioning and `@position-try-fallback` natively when `flip=true`.
+ * - **Fallback:** A JavaScript polyfill measures the menu after it opens. If
+ *   it overflows the requested `placement`, it sets an internal state to flip
+ *   the placement classes.
  *
- * BeerCSS uses a plain `<menu>` with class `.active` toggled by JS —
- * NO Popover API. The menu positions itself as `position: absolute`
- * relative to the nearest positioned ancestor.
+ * **State management:**
+ * The `active` attribute controls visibility. Consumers must listen to trigger
+ * events (like `click`) and toggle the `active` property.
  *
- * Shadow DOM note: we keep :host as `display: contents` so the inner
- * `<menu>` can position relative to the consumer's layout context.
- * The consumer must have `position: relative` on the trigger's wrapper.
+ * @example
+ * ```html
+ * <!-- Wrapper must have position: relative -->
+ * <div style="position: relative; display: inline-block;">
+ *   <moni-button id="menu-trigger">Open Menu</moni-button>
  *
- * **M3 spec** (`m3-docs/components/menus/guidelines.md`): menus should
- * auto-flip to the opposite side when there isn't enough viewport space
- * in the requested placement.
+ *   <moni-menu placement="bottom" flip id="my-menu">
+ *     <moni-menu-item icon="edit">Edit</moni-menu-item>
+ *     <moni-menu-item icon="content_copy">Copy</moni-menu-item>
+ *     <moni-divider></moni-divider>
+ *     <moni-menu-item icon="delete">Delete</moni-menu-item>
+ *   </moni-menu>
+ * </div>
  *
- * **Flip implementation** (P4.3):
- *  - Modern browsers (Chrome 125+, Edge 125+, Safari 18+): uses CSS
- *    `@position-try-fallback` (Baseline 2024) when `flip` is set.
- *  - Older browsers (Firefox, Safari < 18): JS polyfill. After the menu
- *    becomes active, we measure the inner `<menu>` rect; if it overflows
- *    the viewport on the requested side, we set `_resolvedPlacement`
- *    to the opposite side and the CSS picks up the change.
+ * <script>
+ *   const btn = document.getElementById('menu-trigger');
+ *   const menu = document.getElementById('my-menu');
+ *   btn.addEventListener('click', () => menu.active = !menu.active);
+ * </script>
+ * ```
  *
- * Attributes:
- *  - placement:  bottom (default) | top | left | right | min | max
- *  - no-wrap:    present
- *  - space:      no-space | space | small-space | medium-space | large-space | extra-space
- *  - active:     present → menu is visible
- *  - flip:       present → enable auto-flip when there is no viewport space
- *                (works on all browsers; CSS-native when supported)
+ * @slot default - `<moni-menu-item>`, `<moni-divider>`, or raw `<li>` elements.
  *
- * Slots:
- *  - default: menu items (moni-menu-item or li elements)
+ * @csspart menu - The inner `<menu>` container.
  */
 @customElement('moni-menu')
 export class MoniMenu extends MoniElement {

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 {