@moni-labs/moni-ui 0.2.0 → 0.3.1

package/src/components/moni-fab.ts

@@ -1,31 +1,58 @@
+/**
+ * @file components/moni-fab.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';
 
 /**
- * Visual-only Floating Action Button.
+ * Material Design 3 Floating Action Button (FAB) component.
+ *
+ * FABs represent the primary, or most common, action on a screen. They appear
+ * in front of all screen content, typically as a circular shape with an icon in
+ * its center.
+ *
+ * **M3 spec reference:** `m3-docs/components/floating-action-buttons/specs.md`
+ *
+ * **M3 Expressive Updates & Deprecations (May 2025):**
+ * - `size="small"` is **no longer recommended** by M3. Use `medium` (40dp or 56dp)
+ *   or `large` (96dp). Deprecated in v0.3.1; will be removed in v1.0.
+ * - `shape="circle"` is **not part of M3**. M3 FABs use a `rounded` shape with a
+ *   16dp corner radius (which morphs to a `full` radius on hover/focus).
+ *   Deprecated in v0.3.1; will be removed in v1.0.
+ * - `color="surface"` is **no longer recommended**. Use `primary`, `secondary`,
+ *   or `tertiary` to ensure proper color mapping to the M3 theme.
+ *
+ * **Extended FABs:**
+ * When `extended` is true, the FAB displays a text label next to the icon.
+ * Extended FABs are wider and are typically used when the action needs explicit
+ * text to be clear. The `expanded` attribute forces the FAB to its full extended
+ * width, useful for animating between standard and extended states on scroll.
+ *
+ * **Positioning:**
+ * The `position` attribute applies predefined absolute/fixed positioning
+ * (e.g. `bottom-trailing`), snapping the FAB to standard screen corners.
+ *
+ * @example
+ * ```html
+ * <!-- Standard primary FAB -->
+ * <moni-fab icon="edit"></moni-fab>
+ *
+ * <!-- Extended tertiary FAB -->
+ * <moni-fab color="tertiary" extended icon="add" label="New task"></moni-fab>
  *
- * Material 3 Expressive update (May 2025):
- *  - `size="small"` is **no longer recommended** by M3. Use `medium` (40dp/56dp
- *    on M3 spec) or `large`. Deprecated in v0.3.1; will be removed in v1.0.
- *  - `shape="circle"` is **not part of M3**; M3 FABs are `rounded` with a 16dp
- *    corner radius (or `full` when on hover/focus). The M3 spec does not
- *    define a perfect-circle FAB. Deprecated in v0.3.1; will be removed in v1.0.
- *  - `color="surface"` is **no longer recommended** by M3. Use `primary`,
- *    `secondary`, or `tertiary` (and their container variants).
+ * <!-- Positioned FAB -->
+ * <moni-fab position="bottom-trailing" icon="navigation"></moni-fab>
+ * ```
  *
- * Attributes:
- *  - size:      medium (default) | large  (small: deprecated)
- *  - color:     primary (default) | secondary | tertiary  (surface: deprecated)
- *  - shape:     rounded (default)  (circle: deprecated)
- *  - extended:  present → wider with label always visible
- *  - expanded:  present → force expanded
- *  - disabled:  present
- *  - icon:      Material Symbols name
- *  - label:     text when extended
- *  - position:  bottom-trailing (default) | bottom-leading
- *               | top-trailing | top-leading
+ * @csspart button - The internal `<button>` element.
+ * @csspart icon   - The container for the icon.
+ * @csspart label  - The text label (only visible when extended).
  */
 @customElement('moni-fab')
 export class MoniFab extends MoniElement {

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

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-file-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';
@@ -6,21 +13,55 @@ import { MoniElement, sharedStyles, fieldStyles } from './_base/index.js';
 import './moni-icon.js';
 
 /**
- * Visual-only file field. Renders a hidden `<input type="file">` over a
- * read-only text input that shows the chosen file names.
+ * Material Design 3 File Field component.
+ *
+ * A specialized field component that provides a styled, accessible alternative
+ * to the native `<input type="file">`. It wraps a native file input inside
+ * the M3 `.field` shell and presents a read-only text input showing the
+ * selected file name(s) alongside a stylized "Choose file" action button.
+ *
+ * **Visual architecture:**
+ * The component leverages the `fieldStyles` CSS patterns. The internal DOM
+ * structure is specifically ordered as:
+ * `[text input] -> [label] -> [file input] -> [output]`
+ * This specific ordering ensures that the CSS adjacent sibling selector
+ * (`input + label`) can correctly float the label when the field is populated,
+ * even though the visible field is actually the read-only text input.
+ *
+ * **State management:**
+ * When the user selects files via the hidden file input, the component listens
+ * for the native `change` event, reads `input.files`, and updates the read-only
+ * text input with a comma-separated list of file names. The `value` property
+ * is kept in sync, and a composed `'change'` event is re-dispatched.
+ *
+ * @fires change - Bubbles and is composed. Fired when files are selected or
+ *                 cleared. The consumer can read the internal input's `files`
+ *                 list by querying the component.
+ *
+ * @example
+ * ```html
+ * <!-- Single file upload -->
+ * <moni-file-field
+ *   label="Profile picture"
+ *   name="avatar"
+ *   accept="image/png, image/jpeg"
+ *   button-label="Browse..."
+ * ></moni-file-field>
  *
- * The DOM order is `input[type=text], label, input[type=file], output` so
- * that the floating label CSS selector `input + label` lifts correctly even
- * though the visible field is the read-only text input.
+ * <!-- Multiple file upload with error state -->
+ * <moni-file-field
+ *   label="Documents"
+ *   multiple
+ *   error
+ *   error-text="Files exceed maximum size limit"
+ * ></moni-file-field>
+ * ```
  *
- * Attributes:
- *  - name, label, value, variant, size, shape, disabled, helper, error,
- *    error-text, placeholder — see moni-text-field.
- *  - accept:  forwarded to input.accept
- *  - multiple: present → input.multiple
- *  - button-label: text on the picker button (visual only, default: "Choose file")
- *  - icon:           leading Material Symbols name
- *  - trailing-icon:  trailing Material Symbols name
+ * @csspart field       - The outer `.field` div container.
+ * @csspart input-text  - The visible read-only `<input type="text">`.
+ * @csspart label       - The floating `<label>` element.
+ * @csspart input-file  - The hidden native `<input type="file">`.
+ * @csspart button      - The button element (styled via CSS `::file-selector-button`).
  */
 @customElement('moni-file-field')
 export class MoniFileField extends MoniElement {

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 {