@moni-labs/moni-ui 0.2.0 → 0.3.0

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

@@ -1,34 +1,57 @@
+/**
+ * @file components/moni-context-menu.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css } from 'lit';
 import { customElement, property, state, query } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-menu.js';
 
 /**
- * Context menu triggered by right-click on the parent element.
+ * Material Design 3 Context Menu component.
+ *
+ * A specialized menu that opens at the exact coordinates of a pointer event,
+ * typically triggered by a right-click (`contextmenu` event). It provides
+ * contextual actions related to the specific item clicked.
+ *
+ * **M3 spec reference:** `m3-docs/components/menus/specs.md` (Contextual menus)
+ *
+ * **Triggering mechanism:**
+ * The component does not require programmatic triggering via an `open` property.
+ * Instead, it attaches a `contextmenu` event listener to its parent element
+ * during `connectedCallback`. When the parent is right-clicked, the menu
+ * captures the `clientX`/`clientY` coordinates, prevents the default browser
+ * context menu, and opens itself at the cursor position using `position: fixed`.
  *
- * **Usage** (`m3-docs/components/menus/guidelines.md`): the menu opens at
- * the cursor's coordinates and flips to the opposite side if there isn't
- * enough space in the viewport.
+ * **Auto-flip behavior (`flip` attribute):**
+ * Per the M3 guidelines, menus should flip to the opposite side of the cursor
+ * if opening in the requested `placement` would cause them to overflow the
+ * viewport. When `flip=true`, the component dynamically calculates viewport
+ * bounds before opening and overrides `placement` if necessary (e.g., flipping
+ * from `bottom` to `top` if clicked near the bottom of the screen).
  *
- * **Wiring example**:
- *   ```html
- *   <div style="position: relative;">
- *     <moni-context-menu flip>
- *       <moni-menu-item>Cut</moni-menu-item>
- *       <moni-menu-item>Copy</moni-menu-item>
- *       <moni-menu-item>Paste</moni-menu-item>
- *     </moni-context-menu>
- *     Right-click anywhere in this div
- *   </div>
- *   ```
+ * **Auto-dismiss:**
+ * Closes automatically when clicking anywhere outside the menu, or when
+ * pressing the `Escape` key.
  *
- * Attributes:
- *  - placement: bottom (default) | top | left | right
- *  - flip:      present → auto-flip to opposite side if menu would overflow
- *               the viewport (M3 spec)
+ * @example
+ * ```html
+ * <!-- Wrap the trigger area and the menu in a container -->
+ * <div>
+ *   <p>Right-click me for options</p>
+ *   <moni-context-menu flip>
+ *     <moni-menu-item>Copy</moni-menu-item>
+ *     <moni-menu-item>Paste</moni-menu-item>
+ *     <moni-divider></moni-divider>
+ *     <moni-menu-item>Delete</moni-menu-item>
+ *   </moni-context-menu>
+ * </div>
+ * ```
  *
- * Slots:
- *  - default: menu items
+ * @slot default - The `<moni-menu-item>` elements that make up the menu.
  */
 @customElement('moni-context-menu')
 export class MoniContextMenu extends MoniElement {

package/src/components/moni-dialog.ts

@@ -1,37 +1,134 @@
+/**
+ * @file components/moni-dialog.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 { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Visual-only dialog. Renders a native `<dialog>` element. The consumer
- * opens/closes by calling the native `show()` / `showModal()` /
- * `close()` / `showPopover()` methods on the inner dialog via
- * `this.querySelector('dialog')` from the light DOM.
+ * Material Design 3 Dialog component.
+ *
+ * Dialogs inform users about a task and can contain critical information,
+ * require decisions, or involve multiple tasks. They interrupt the user's
+ * workflow and should be used sparingly.
+ *
+ * **M3 spec reference:** `m3-docs/components/dialogs/specs.md`
+ *
+ * **Implementation note — native `<dialog>` element:**
+ * This component wraps the native `<dialog>` HTML element. Opening and closing
+ * are controlled via the `open` attribute (and its JS property). The component
+ * syncs `open` changes to the native `<dialog>` in `updated()`:
+ * - `modal=true` → calls `dialog.showModal()` (blocks focus, adds backdrop).
+ * - `modal=false` → calls `dialog.show()` (non-blocking, no backdrop).
+ * - `open=false` → calls `dialog.close()`.
  *
- * Attributes:
- *  - open:   present → dialog[open]
- *  - side:   center (default) | top | right | bottom | left | max
- *  - size:   small | medium (default) | large
- *  - modal:  present → adds the `modal` class (used by BeerCSS)
- *  - title:  header text
+ * **Placement (`side` attribute):**
+ * - `center` (default) — Centered in the viewport. Standard M3 dialog.
+ * - `top`, `right`, `bottom`, `left` — Edge-anchored panels (side sheet pattern).
+ * - `max` — Full-screen dialog for complex flows.
  *
- * Slots:
- *  - default: body
- *  - header:  title
- *  - footer:  action buttons
+ * @example
+ * ```html
+ * <!-- Basic modal dialog -->
+ * <moni-dialog open modal title="Delete item?" size="small">
+ *   <p>This action cannot be undone.</p>
+ *   <div slot="footer">
+ *     <moni-button variant="text">Cancel</moni-button>
+ *     <moni-button>Delete</moni-button>
+ *   </div>
+ * </moni-dialog>
+ * ```
+ *
+ * @slot default - The dialog body content.
+ * @slot header  - Custom header content (overrides `title` attribute).
+ * @slot footer  - Action buttons row at the bottom of the dialog.
+ *
+ * @csspart dialog - The native `<dialog>` element.
+ * @csspart header - The header container.
+ * @csspart body   - The body content wrapper.
+ * @csspart footer - The footer actions wrapper.
  */
 @customElement('moni-dialog')
 export class MoniDialog extends MoniElement {
+	/**
+	 * Controls the open/closed state of the dialog.
+	 *
+	 * When set to `true`, the component calls `dialog.showModal()` (if `modal`)
+	 * or `dialog.show()`. When set to `false`, calls `dialog.close()`.
+	 * Reflected as an HTML attribute for CSS and external state readers.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) open = false;
+
+	/**
+	 * When `true`, opens the dialog as a modal using `<dialog>.showModal()`.
+	 *
+	 * Modal dialogs:
+	 * - Block keyboard focus from leaving the dialog.
+	 * - Render a `::backdrop` scrim over the rest of the page.
+	 * - Can be closed by pressing `Escape` (native browser behavior).
+	 *
+	 * When `false`, uses `<dialog>.show()` which is non-blocking (no focus trap
+	 * and no backdrop).
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) modal = false;
+
+	/**
+	 * Placement of the dialog within the viewport.
+	 *
+	 * - `'center'` (default) — Centered. Standard M3 dialog placement.
+	 * - `'top'`    — Anchored to the top edge (drawer from top).
+	 * - `'right'`  — Anchored to the right edge (side sheet pattern).
+	 * - `'bottom'` — Anchored to the bottom edge (bottom sheet alternative).
+	 * - `'left'`   — Anchored to the left edge (navigation drawer pattern).
+	 * - `'max'`    — Full-screen (covers the entire viewport).
+	 *
+	 * @default 'center'
+	 */
 	@property({ reflect: true })
 	side: 'center' | 'top' | 'right' | 'bottom' | 'left' | 'max' = 'center';
+
+	/**
+	 * Size of the dialog container.
+	 *
+	 * - `'small'`  — Narrow dialog; ideal for simple confirmations.
+	 * - `'medium'` — Standard dialog width (default).
+	 * - `'large'`  — Wide dialog; for forms or complex content.
+	 *
+	 * @default 'medium'
+	 */
 	@property({ reflect: true })
 	size: 'small' | 'medium' | 'large' = 'medium';
+
+	/**
+	 * Text displayed in the dialog header area.
+	 *
+	 * When non-empty, renders as a styled heading inside the header container.
+	 * The `header` slot takes precedence over this attribute when both are present.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) title = '';
 
+	/** Direct reference to the native `<dialog>` element for programmatic access. */
 	@query('dialog') private _dialog!: HTMLDialogElement;
 
+	/**
+	 * Syncs the `open` and `modal` state to the native `<dialog>` element.
+	 *
+	 * Called by Lit after every render cycle where tracked properties change.
+	 * Avoids calling `showModal()` or `show()` if the dialog is already open
+	 * (prevents the `InvalidStateError` DOMException).
+	 *
+	 * @param changed - Map of changed property names to their previous values.
+	 */
 	override updated(changed: Map<string, unknown>) {
 		if (changed.has('open') && this._dialog) {
 			if (this.open) {

package/src/components/moni-divider.ts

@@ -1,29 +1,65 @@
+/**
+ * @file components/moni-divider.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 Divider (`m3-docs/components/divider/specs.md`).
+ * Material Design 3 Divider component.
+ *
+ * A thin horizontal (or vertical) rule used to visually separate content
+ * sections within lists, layouts, and cards.
+ *
+ * **M3 spec reference:** `m3-docs/components/divider/specs.md`
+ *
+ * **M3 measurements:**
+ * - Thickness: 1dp (`0.0625rem`).
+ * - Color: `outline-variant` — subtle on all surface backgrounds.
+ * - Inset variants align the line with list content:
+ *   - `leading` — 16dp margin from the leading edge (aligns with icon text).
+ *   - `middle`  — 16dp margin on both edges.
+ *   - `none`    — full-bleed (no margin).
  *
- * A thin line used to group content in lists, layouts, or cards. M3 spec
- * defines three inset variants:
- *  - **full** (default): spans the full width of the parent.
- *  - **inset**: indented from the leading edge (16dp) so it lines up
- *    with text content below an icon.
- *  - **middle**: indented from both edges (16dp each).
+ * **Vertical usage:**
+ * While not yet exposed as an attribute, the `[vertical]` CSS attribute selector
+ * is supported. Set `vertical` as an HTML attribute to render a 1dp-wide
+ * vertical divider that stretches to match its flex container's cross-axis.
  *
- * M3 measurements:
- *  - Thickness: 1dp (`0.0625rem`).
- *  - Color: `outline-variant` (subtle on a light background).
+ * @example
+ * ```html
+ * <!-- Full-bleed divider between sections -->
+ * <moni-divider inset="none"></moni-divider>
  *
- * Attributes:
- *  - inset:  leading (default) | middle | none
+ * <!-- Leading-inset divider in a list (aligns with list item text) -->
+ * <moni-divider></moni-divider>
  *
- * Slots:
- *  - default: optional content rendered inline with the divider line.
+ * <!-- Vertical divider inside a flex container -->
+ * <div style="display:flex; height: 3rem; align-items:center; gap: 1rem;">
+ *   <span>Section A</span>
+ *   <moni-divider vertical></moni-divider>
+ *   <span>Section B</span>
+ * </div>
+ * ```
  */
 @customElement('moni-divider')
 export class MoniDivider extends MoniElement {
+	/**
+	 * Controls the horizontal margin on the divider line.
+	 *
+	 * - `'leading'` (default) — 16dp margin from the leading (start) edge only.
+	 *   Use in lists to align the divider with the primary text of list items.
+	 * - `'middle'`  — 16dp margin on both the leading and trailing edges.
+	 *   Use to separate sections where full-bleed would be too visually heavy.
+	 * - `'none'`    — No margin; the line spans the full parent width.
+	 *   Use as a section separator or between cards.
+	 *
+	 * @default 'leading'
+	 */
 	@property({ reflect: true })
 	inset: 'leading' | 'middle' | 'none' = 'leading';
 

package/src/components/moni-expansion.ts

@@ -1,17 +1,54 @@
+/**
+ * @file components/moni-expansion.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 expansion panel. Renders a `<details>` element.
+ * Material Design 3 Expansion panel component.
+ *
+ * A lightweight wrapper around the native HTML `<details>` and `<summary>`
+ * elements, styled according to M3 surface and elevation guidelines.
+ * Expansion panels contain creation flows and allow lightweight editing of an element.
+ *
+ * **Visual architecture:**
+ * The component renders a `<details>` element with a `<summary>` that acts
+ * as the expandable header. The default slot content is placed inside the
+ * `<details>` tag (but outside the `<summary>`), naturally hiding and showing
+ * based on the native behavior. An M3 `expand_more` icon is added via a CSS
+ * `::after` pseudo-element and rotates when the panel is open.
+ *
+ * **Usage:**
+ * Set the `title` attribute for a simple text header, or use the `summary`
+ * slot to project custom rich content (like icons or secondary text) into the
+ * header area.
+ *
+ * @example
+ * ```html
+ * <!-- Simple text title -->
+ * <moni-expansion title="Advanced Settings">
+ *   <p>Enable developer mode features here.</p>
+ * </moni-expansion>
  *
- * Attributes:
- *  - open: present → panel expanded
- *  - title: heading text for the summary
+ * <!-- Rich summary content via slot -->
+ * <moni-expansion open>
+ *   <div slot="summary" style="display: flex; gap: 8px;">
+ *     <moni-icon>person</moni-icon>
+ *     <span>Personal Information</span>
+ *   </div>
+ *   <form>
+ *     <moni-text-field label="Name"></moni-text-field>
+ *   </form>
+ * </moni-expansion>
+ * ```
  *
- * Slots:
- *  - default:  panel body
- *  - summary:  custom summary content (overrides title)
+ * @slot default - The content of the expansion panel body.
+ * @slot summary - Custom header content (overrides the `title` attribute).
  */
 @customElement('moni-expansion')
 export class MoniExpansion extends MoniElement {

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

@@ -1,3 +1,10 @@
+/**
+ * @file components/moni-fab-menu.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 { MoniElement, sharedStyles } from './_base/index.js';
@@ -6,28 +13,41 @@ import './moni-icon.js';
 import type { MoniFab } from './moni-fab.js';
 
 /**
- * Visual-only FAB menu. Combines a main `<moni-fab>` trigger with a `<menu>`
- * of secondary FABs (slotted via default slot).
+ * Material Design 3 FAB Menu component.
+ *
+ * A specialized container that combines a main `<moni-fab>` trigger with a
+ * `<menu>` of secondary FABs. It allows multiple actions to be tucked away
+ * behind a single primary Floating Action Button, reducing screen clutter.
+ *
+ * **M3 spec reference:** `m3-docs/components/floating-action-buttons/specs.md` (FAB menus)
+ *
+ * **Trigger and animation:**
+ * The component wires the primary trigger FAB's `click` event to toggle its
+ * internal `open` state. When `open=true`, the nested secondary FABs scale up
+ * and fade in via CSS transitions. Consumers can also control the `open` state
+ * programmatically by setting the attribute.
+ *
+ * **Focus management (Accessibility):**
+ * - When the menu opens, focus automatically moves to the first focusable
+ *   secondary item (or remains on the trigger if empty).
+ * - While open, the `Tab` key cycles focus strictly within the menu items to
+ *   prevent keyboard focus from escaping (focus trap).
+ * - Pressing `Escape` or clicking anywhere outside the menu closes it and
+ *   returns focus to the primary trigger FAB.
  *
- * The component wires the trigger's `click` to toggle the `open` attribute.
- * Consumers can also set/unset the attribute externally for programmatic
- * control. The menu scales and fades via CSS transitions.
+ * @example
+ * ```html
+ * <!-- Bottom-trailing FAB menu opening upwards -->
+ * <moni-fab-menu icon="add" color="tertiary" direction="up">
+ *   <moni-fab size="small" icon="edit" label="Draft"></moni-fab>
+ *   <moni-fab size="small" icon="photo_camera" label="Camera"></moni-fab>
+ * </moni-fab-menu>
+ * ```
  *
- * **Focus management** (M3 spec § FAB menu):
- *  - When `open` becomes true, focus moves to the first focusable item in
- *    the menu (or stays on the trigger if the menu is empty).
- *  - When `open` becomes false, focus returns to the trigger.
- *  - `Tab` cycles within the menu while open; `Escape` closes the menu.
- *  - Click outside the menu closes it.
+ * @slot default - The secondary `<moni-fab>` elements that appear when open.
  *
- * Attributes:
- *  - open:      present → menu is shown
- *  - icon:      Material Symbols name for the trigger
- *  - size:      small | medium (default) | large
- *  - color:     primary (default) | secondary | tertiary | surface
- *  - shape:     rounded (default) | circle
- *  - direction: up (default) | down | left | right
- *  - position:  same as moni-fab
+ * @csspart trigger - The primary `<moni-fab>` trigger element.
+ * @csspart menu    - The `<menu>` container holding the secondary items.
  */
 @customElement('moni-fab-menu')
 export class MoniFabMenu extends MoniElement {

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 {