@moni-labs/moni-ui 0.2.0 → 0.3.0

package/src/components/moni-app-bar.ts

@@ -1,51 +1,140 @@
+/**
+ * @file components/moni-app-bar.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';
 
 /**
- * Material 3 App Bar (`m3-docs/components/app-bars/specs.md`).
+ * Material Design 3 App Bar component.
+ *
+ * App bars provide navigation and action controls at the top (or bottom) of a
+ * screen. They are positioned sticky by default so they remain visible as the
+ * user scrolls through content.
+ *
+ * **M3 spec reference:** `m3-docs/components/app-bars/specs.md`
+ *
+ * **Placement:**
+ * - `top` (default) — 64dp header fixed above page content. Uses `position: sticky`
+ *   with `inset-block-start: 0` so it stays at the top of the scroll container.
+ * - `bottom` — Mobile navigation footer anchored to the bottom of the viewport.
+ *   Ideal for housing primary navigation icons and an optional FAB.
  *
- * App bars are placed at the top of a screen to help users navigate.
- * Two main placements:
- *  - **top** (default): header above content. Standard height **64dp**.
- *  - **bottom**: footer below content (mobile pattern). Houses navigation
- *    icons and an optional FAB anchor.
+ * **Variants:**
+ * - `standard` — Flat surface (no shadow) when content is at the top. Best for most UIs.
+ * - `floating` — Always elevated with `--elevate2` shadow. Use when the bar visually
+ *   floats above the content regardless of scroll position.
  *
- * Two variants:
- *  - **standard** (default): flat surface with no shadow at rest.
- *  - **floating**: gains an elevation 2 shadow when content scrolls under it.
+ * **Sizes:**
+ * - `default` — 64dp (4rem) tall. Standard for most use cases.
+ * - `prominent` — 152dp (9.5rem) tall. Use when a subtitle or expanded area is needed.
+ *   The `subtitle` attribute is only rendered in this size.
  *
- * Two size modes:
- *  - **default**: 64dp tall.
- *  - **prominent**: 152dp tall, used when a subtitle is shown.
+ * @example
+ * ```html
+ * <!-- Top app bar with navigation icon and action buttons -->
+ * <moni-app-bar title="Settings">
+ *   <moni-button slot="leading" shape="circle" variant="text" icon="menu"></moni-button>
+ *   <moni-button slot="trailing" shape="circle" variant="text" icon="search"></moni-button>
+ *   <moni-button slot="trailing" shape="circle" variant="text" icon="more_vert"></moni-button>
+ * </moni-app-bar>
+ * ```
  *
- * Center-aligned title (M3 spec): title is centered horizontally.
- * Navigation icons go to the leading edge; actions to the trailing edge.
+ * @example
+ * ```html
+ * <!-- Prominent app bar with subtitle -->
+ * <moni-app-bar size="prominent" title="Inbox" subtitle="12 unread messages" elevated>
+ * </moni-app-bar>
+ * ```
  *
- * Attributes:
- *  - placement:  top (default) | bottom
- *  - variant:   standard (default) | floating
- *  - size:      default (default, 64dp) | prominent (152dp)
- *  - title:     text content of the title (centered)
- *  - subtitle:  optional subtitle shown below the title (prominent only)
- *  - elevated:  present → adds elevation 2 shadow (e.g. when scrolled)
+ * @slot leading   - Navigation icon(s) placed on the leading (start) edge.
+ * @slot trailing  - Action icon(s) placed on the trailing (end) edge.
+ * @slot fab       - FAB anchored to the trailing edge (bottom placement only).
+ * @slot default   - Additional content (e.g. a tab bar below the title row).
  *
- * Slots:
- *  - leading:  navigation icon(s) on the leading edge
- *  - trailing: action icon(s) on the trailing edge
- *  - fab:      (bottom only) FAB anchored to the trailing edge
- *  - default:  any extra content (e.g. tabs)
+ * @csspart bar      - The inner grid container.
+ * @csspart leading  - The leading slot wrapper.
+ * @csspart trailing - The trailing slot wrapper.
+ * @csspart title    - The title text element.
+ * @csspart subtitle - The subtitle text element (prominent size only).
+ * @csspart actions  - The actions slot wrapper (prominent size only).
  */
 @customElement('moni-app-bar')
 export class MoniAppBar extends MoniElement {
+	/**
+	 * Determines whether the bar is placed at the top or bottom of the viewport.
+	 *
+	 * - `'top'` (default) — Sticky header at the top of the scroll container.
+	 * - `'bottom'` — Fixed footer; primarily used for mobile bottom navigation patterns.
+	 *
+	 * @default 'top'
+	 */
 	@property({ reflect: true })
 	placement: 'top' | 'bottom' = 'top';
+
+	/**
+	 * Visual variant of the app bar.
+	 *
+	 * - `'standard'` (default) — Flat surface. No shadow at rest; gains shadow
+	 *   programmatically via the `elevated` attribute when content scrolls beneath it.
+	 * - `'floating'` — Permanently elevated with `--elevate2` box-shadow.
+	 *
+	 * @default 'standard'
+	 */
 	@property({ reflect: true })
 	variant: 'standard' | 'floating' = 'standard';
+
+	/**
+	 * Height variant of the app bar.
+	 *
+	 * - `'default'` — 64dp (4rem). Standard M3 top app bar height.
+	 * - `'prominent'` — 152dp (9.5rem). Use when showing a subtitle or when
+	 *   extra vertical space is needed for a contextual action row.
+	 *
+	 * @default 'default'
+	 */
 	@property({ reflect: true })
 	size: 'default' | 'prominent' = 'default';
+
+	/**
+	 * Title text displayed in the center of the app bar.
+	 *
+	 * The title is center-aligned per M3 spec. Long titles are truncated with
+	 * an ellipsis. For semantic HTML, the consumer should also provide an `<h1>`
+	 * in the page content that matches this title.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) title = '';
+
+	/**
+	 * Optional subtitle displayed below the title.
+	 *
+	 * Only rendered when `size="prominent"`. Provides secondary context
+	 * (e.g. folder name, item count, description).
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) subtitle = '';
+
+	/**
+	 * When present, applies `--elevate2` box-shadow to signal that content has
+	 * scrolled beneath the bar.
+	 *
+	 * Consumers are responsible for toggling this attribute reactively based on
+	 * the scroll position of the main content area:
+	 * ```ts
+	 * container.addEventListener('scroll', () => {
+	 *   appBar.elevated = container.scrollTop > 0;
+	 * });
+	 * ```
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) elevated = false;
 
 	static override styles = [
@@ -155,6 +244,18 @@ export class MoniAppBar extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renders the app bar grid layout.
+	 *
+	 * The inner `.bar` element uses a 3-column CSS grid:
+	 * - Column 1: leading slot (navigation icon).
+	 * - Column 2: title (center-aligned, fills remaining space).
+	 * - Column 3: trailing slot (action icons).
+	 *
+	 * In `prominent` size, a subtitle row and an actions row are appended
+	 * conditionally. The subtitle only renders when the `subtitle` attribute
+	 * is non-empty; the actions slot always renders for prominent bars.
+	 */
 	override render() {
 		const hasSubtitle = this.size === 'prominent' && Boolean(this.subtitle);
 		const hasActions = Boolean(this.size === 'prominent');

package/src/components/moni-badge.ts

@@ -1,40 +1,142 @@
+/**
+ * @file components/moni-badge.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';
 
 /**
- * Badge that faithfully ports BeerCSS's `.badge` styles.
+ * Material Design 3 Badge component.
+ *
+ * Badges are small status descriptors anchored to a parent element, used to
+ * convey supplementary information such as a notification count, online
+ * status, or selection indicator.
+ *
+ * **Positioning contract:**
+ * The badge uses `position: absolute` and anchors to the parent element.
+ * On `connectedCallback`, if the parent's computed `position` is `'static'`,
+ * the badge automatically sets `parent.style.position = 'relative'`.
+ * Consumers do not need to manually add `position: relative` to the parent.
+ *
+ * **Rendering model:**
+ * The `:host` displays as `contents`, making it transparent to layout.
+ * Only the inner `.badge` span is visually rendered. This allows the badge
+ * to be dropped inside any element without affecting its layout flow.
  *
- * BeerCSS `.badge` uses:
- *  - `position: absolute; inset: 50% auto auto 50%; transform: translate(var(--_x), var(--_y))`
- *  - Default: --_x: 0, --_y: -100% → top-right corner
+ * @example
+ * ```html
+ * <!-- Notification badge on a button -->
+ * <div style="position: relative; display: inline-flex;">
+ *   <moni-button icon="notifications" variant="text"></moni-button>
+ *   <moni-badge value="5"></moni-badge>
+ * </div>
+ * ```
  *
- * The parent element MUST have `position: relative` for the badge to anchor correctly.
- * We ensure this in connectedCallback.
+ * @example
+ * ```html
+ * <!-- Inline dot badge for status -->
+ * <moni-badge shape="min" color="primary" inline></moni-badge>
+ * Online
+ * ```
  *
- * Attributes:
- *  - value:    text content (also accepts slotted content)
- *  - position: '' (top-right default) | top | bottom | left | right | none
- *  - shape:    '' (round) | circle | square | min
- *  - color:    error (default) | primary | secondary | tertiary
- *  - border:   present → outlined badge (BeerCSS .badge.border)
- *  - inline:   present → badge becomes inline (BeerCSS .badge.none)
+ * @csspart badge - The badge `<span>` element. Override `background-color`,
+ *                  `color`, or `border-radius` to customize appearance.
  */
 @customElement('moni-badge')
 export class MoniBadge extends MoniElement {
+	/**
+	 * Text content of the badge label.
+	 *
+	 * Also accepts slotted content — the default slot inside the badge span
+	 * falls back to this value when no children are slotted.
+	 * Use an empty string with `shape="min"` to render a dot-only badge.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) value = '';
+
+	/**
+	 * Anchor position relative to the parent element's edges.
+	 *
+	 * Uses `inset: 50% auto auto 50%` as the base and adjusts translation:
+	 * - `''` (default) — top-right corner (translate: 0, -100%).
+	 * - `'top'`    — same as default, explicit alias.
+	 * - `'bottom'` — bottom-right corner (translate: 0, 0).
+	 * - `'left'`   — top-left corner (translate: -100%, -100%).
+	 * - `'right'`  — top-right corner (translate: 0, -100%).
+	 * - `'none'`   — disables absolute positioning; see also the `inline` attribute.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true })
 	position: 'top' | 'bottom' | 'left' | 'right' | 'none' | '' = '';
+
+	/**
+	 * Shape of the badge container.
+	 *
+	 * - `''` (default) — Rounded pill shape (border-radius: 1rem).
+	 * - `'circle'`     — Alias for pill; the badge is always circular when the
+	 *                    content is a single character or absent.
+	 * - `'square'`     — No border-radius (angular badge).
+	 * - `'min'`        — Dot only; content is hidden via `display: none` and the
+	 *                    shape is clipped to a small circle via `clip-path`.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true })
 	shape: 'circle' | 'square' | 'min' | '' = '';
+
+	/**
+	 * Semantic color role of the badge.
+	 *
+	 * Maps to the M3 color palette roles:
+	 * - `'error'` (default) — Red; standard for notification counts and alerts.
+	 * - `'primary'`         — Brand primary color; for selection or active states.
+	 * - `'secondary'`       — Secondary accent; for supplementary indicators.
+	 * - `'tertiary'`        — Tertiary accent; for decorative or informational badges.
+	 *
+	 * @default 'error'
+	 */
 	@property({ reflect: true })
 	color: 'primary' | 'secondary' | 'tertiary' | 'error' = 'error';
+
+	/**
+	 * When `true`, the badge renders inline (resets `position: absolute` to
+	 * `position: relative`) rather than anchoring to the parent.
+	 *
+	 * Equivalent to BeerCSS's `.badge.none` class. Use for inline status
+	 * indicators that flow within text or flex containers.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) inline = false;
+
+	/**
+	 * When present, renders the badge with an outlined style:
+	 * - Background becomes `--surface` (same as the page background).
+	 * - Border and text color use the palette color token (e.g. `--error`).
+	 *
+	 * Equivalent to BeerCSS's `.badge.border` class.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) border = false;
 
+	/**
+	 * Ensures the parent element can contain the absolutely-positioned badge.
+	 *
+	 * Reads the parent's computed `position` via `getComputedStyle`. If it is
+	 * `'static'` (the browser default), sets `parent.style.position = 'relative'`
+	 * so the badge anchors correctly. This is a convenience that avoids requiring
+	 * consumers to remember to add `position: relative` to the parent themselves.
+	 */
 	override connectedCallback() {
 		super.connectedCallback();
-		// BeerCSS requirement: parent must be position:relative for badge to anchor
+		// Ensure the badge's absolutely-positioned anchor point is correct.
 		const parent = this.parentElement;
 		if (parent) {
 			const computed = getComputedStyle(parent);
@@ -115,6 +217,18 @@ export class MoniBadge extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renders the badge span with the computed class list.
+	 *
+	 * Class composition:
+	 * - `'badge'`       — always present (base styles).
+	 * - `this.position` — position variant class (e.g. `'bottom'`, `'left'`).
+	 * - `this.shape`    — shape variant class (e.g. `'min'`, `'square'`).
+	 * - `'none'`        — added when `inline=true` to reset absolute positioning.
+	 *
+	 * Falsy values are filtered out so no extra spaces appear in the class string.
+	 * The default slot falls back to the `value` attribute text node.
+	 */
 	override render() {
 		const classes = [
 			'badge',

package/src/components/moni-bottom-sheet.ts

@@ -1,42 +1,154 @@
+/**
+ * @file components/moni-bottom-sheet.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 bottom sheet. Renders a `<dialog>` that the consumer opens
- * by calling `dialog.showModal()` from the light DOM. The `open` attribute
- * mirrors that state.
+ * Material Design 3 Bottom Sheet component.
+ *
+ * Bottom sheets are surfaces anchored to the bottom of the screen that
+ * supplement the main view. They display supplementary content, contextual
+ * actions, or task flows without fully obscuring the primary content.
+ *
+ * **M3 spec reference:** `m3-docs/components/sheets-bottom/specs.md`
+ *
+ * **Implementation note — native `<dialog>` element:**
+ * Like `<moni-dialog>`, this component wraps the native `<dialog>` element.
+ * The `open` property drives `dialog.showModal()` / `dialog.close()`. When
+ * `modal=true` (default), a `::backdrop` scrim is rendered automatically.
+ *
+ * **Teleportation (body-level mounting):**
+ * When `positioning="body"` (default), the component moves itself to
+ * `document.body` on `connectedCallback` so the fixed-bottom dialog renders
+ * above all stacking contexts. On `disconnectedCallback`, it is moved back
+ * to its original DOM position. This avoids clipping by `overflow: hidden`
+ * or `transform` ancestors.
+ *
+ * **Sizes:**
+ * - `small`  — Compact sheet; suitable for simple action menus.
+ * - `medium` — Standard height (default).
+ * - `large`  — Expanded height (`expandedHeight` controls the max block-size).
+ * - `auto`   — Content-driven height.
+ *
+ * @example
+ * ```html
+ * <moni-bottom-sheet title="Share">
+ *   <moni-list-item icon="share">Copy link</moni-list-item>
+ *   <moni-list-item icon="mail">Send via email</moni-list-item>
+ * </moni-bottom-sheet>
  *
- * Attributes:
- *  - open:  present → visibility on
- *  - size:  small | medium (default) | large | auto
- *  - modal: present → backdrop rendered
- *  - title: heading text
+ * <script>
+ *   document.querySelector('moni-bottom-sheet').open = true;
+ * </script>
+ * ```
  *
- * Slots:
- *  - handle:  grab handle
- *  - default: body
- *  - footer:  action buttons
+ * @slot default - The body content of the bottom sheet.
+ * @slot handle  - The drag handle area at the top of the sheet.
+ * @slot footer  - Action buttons at the bottom of the sheet.
+ *
+ * @csspart dialog - The native `<dialog>` element.
+ * @csspart header - The header container with title and close button.
+ * @csspart body   - The scrollable body content area.
+ * @csspart footer - The footer action buttons area.
  */
 @customElement('moni-bottom-sheet')
 export class MoniBottomSheet extends MoniElement {
+	/**
+	 * Controls the open/closed state of the bottom sheet.
+	 *
+	 * When set to `true`, calls `dialog.showModal()` or `dialog.show()`
+	 * depending on the `modal` property. When set to `false`, calls `dialog.close()`.
+	 *
+	 * @default false
+	 */
 	@property({ type: Boolean, reflect: true }) open = false;
+
+	/**
+	 * Height variant of the sheet container.
+	 *
+	 * - `'small'`  — Compact; suitable for quick confirmations.
+	 * - `'medium'` — Standard height (default).
+	 * - `'large'`  — Fills `expandedHeight` of the viewport.
+	 * - `'auto'`   — Content-driven; height adapts to the slotted content.
+	 *
+	 * @default 'medium'
+	 */
 	@property({ reflect: true })
 	size: 'small' | 'medium' | 'large' | 'auto' = 'medium';
+
+	/**
+	 * When `true` (default), the sheet opens as a modal dialog with a backdrop
+	 * scrim. When `false`, it opens as a non-modal overlay with no scrim.
+	 *
+	 * @default true
+	 */
 	@property({ type: Boolean, reflect: true }) modal = true;
+
+	/**
+	 * Heading text displayed in the sheet's header area.
+	 *
+	 * @default ''
+	 */
 	@property({ reflect: true }) title = '';
+
+	/**
+	 * Controls how the sheet is positioned in the document.
+	 *
+	 * - `'body'` (default) — Teleports the element to `document.body` so
+	 *   the fixed overlay renders above all stacking contexts.
+	 * - `'fixed'` — Fixed positioning within its current DOM subtree.
+	 * - `'absolute'` — Absolute within the nearest positioned ancestor.
+	 * - `'static'` — Static flow (rarely needed; for testing only).
+	 *
+	 * @default 'fixed'
+	 */
 	@property({ reflect: true })
 	positioning: 'body' | 'fixed' | 'absolute' | 'static' = 'fixed';
+
+	/**
+	 * Maximum block-size (height) of the sheet when `size="large"`.
+	 *
+	 * Accepts any valid CSS `max-block-size` value (e.g. `'85%'`, `'600px'`).
+	 * Defaults to `'85%'` which is the M3-recommended maximum for bottom sheets
+	 * on compact screens.
+	 *
+	 * @default '85%'
+	 */
 	@property({ reflect: true, attribute: 'expanded-height' })
 	expandedHeight = '85%';
+
+	/**
+	 * Optional maximum inline-size (width) constraint for the sheet.
+	 *
+	 * When set (e.g. `'640px'`), the sheet will not exceed this width even on
+	 * wide displays. Useful for tablet/desktop breakpoints where a centered
+	 * modal is preferred over a full-width sheet.
+	 *
+	 * @default '' (no constraint)
+	 */
 	@property({ reflect: true, attribute: 'max-width' })
 	maxWidth = '';
 
+	/**
+	 * Original parent node before teleportation to `document.body`.
+	 * Used to restore the element's DOM position in `disconnectedCallback`.
+	 */
 	private _originalParent: Node | null = null;
+
+	/**
+	 * Original next sibling before teleportation to `document.body`.
+	 * Used alongside `_originalParent` to restore the exact DOM position.
+	 */
 	private _originalSibling: Node | null = null;
 
+	/** Direct reference to the native `<dialog>` element. */
 	@query('dialog') private _dialog!: HTMLDialogElement;
-
 	private _isDragging = false;
 	private _startY = 0;
 	private _currentTranslationY = 0;

package/src/components/moni-button-group.ts

@@ -1,34 +1,61 @@
+/**
+ * @file components/moni-button-group.ts
+ * @package @moni-labs/moni-ui
+ * @license MIT
+ * @contributors Moni Labs & Contributors
+ */
+
 import { html, css, nothing } from 'lit';
 import { customElement, property, queryAssignedElements } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Visual-only button group. Organizes `moni-button` or `moni-icon-button`
- * components in a row.
+ * Material Design 3 Button Group component.
+ *
+ * Organizes multiple `<moni-button>` or `<moni-icon-button>` components
+ * into a single row.
+ *
+ * **Variants:**
+ * - `standard` (default) — A simple flex row with a gap between buttons.
+ * - `connected` — The M3 Expressive replacement for segmented buttons. In this
+ *   mode, buttons share borders and form a single continuous pill shape. The
+ *   group manages the single/multi-select toggle state of its children.
+ *
+ * **`connected` variant details:**
+ * - **Shape propagation:** The group automatically propagates M3 shape classes
+ *   (`left-round-flat`, `no-round`, `right-round-flat`) to its children so
+ *   they interlock seamlessly.
+ * - **Toggle management:** The group listens to child clicks and toggles their
+ *   `active` attributes. When `multi=false` (default), only one button can be
+ *   active at a time (radio button behavior). When `multi=true`, multiple buttons
+ *   can be active (checkbox behavior).
+ * - **Event propagation:** Fires a `'change'` event when the selection changes.
+ *
+ * **Accessibility:**
+ * - Renders with `role="group"` (can be overridden to `toolbar` or `radiogroup`).
+ * - Consumers should provide an `aria-label` or `aria-labelledby` attribute
+ *   to identify the group's purpose to assistive technologies.
+ *
+ * @fires change - Fired when a button is clicked in `connected` mode and the
+ *                 selection state updates.
  *
- * **`variant="connected"`** is the Material Design 3 Expressive replacement
- * for the deprecated `moni-segmented-button` (see
- * `m3-docs/components/segmented-buttons/overview.md` § M3 Expressive update).
- * In connected mode, segments share borders via propagated `shape` values
- * (`left-round-flat`, `no-round`, `right-round-flat` for a gap-less row), and
- * the group manages single/multi-select toggle state. This is the
- * **only Moni component that intentionally uses `@click` listeners** —
- * toggle behavior is essential to the M3 connected button group semantics.
+ * @example
+ * ```html
+ * <!-- Connected single-select group -->
+ * <moni-button-group variant="connected" label="Alignment">
+ *   <moni-button icon="format_align_left" active></moni-button>
+ *   <moni-button icon="format_align_center"></moni-button>
+ *   <moni-button icon="format_align_right"></moni-button>
+ * </moni-button-group>
  *
- * Accessibility:
- *  - The host renders `role="group"` (configurable via `role` attribute).
- *  - `aria-label` / `aria-labelledby` should be set by the consumer to
- *    identify the group to assistive technology.
+ * <!-- Standard button row -->
+ * <moni-button-group gap="1rem">
+ *   <moni-button variant="text">Cancel</moni-button>
+ *   <moni-button>Save</moni-button>
+ * </moni-button-group>
+ * ```
  *
- * Attributes:
- *  - variant:    standard (default) | connected
- *  - size:       small | medium (default) | large | extra
- *  - multi:      boolean (default false) — multiple toggles allowed
- *  - gap:        custom gap space (e.g. "8px" or "1rem"); in `connected`
- *                variant the default is 0.125rem (2dp) per M3 spec
- *  - role:       ARIA role override (default "group")
- *  - label:      aria-label for the group
- *  - labelled-by: aria-labelledby reference
+ * @slot default - The `<moni-button>` elements that make up the group.
  */
 @customElement('moni-button-group')
 export class MoniButtonGroup extends MoniElement {

package/src/components/moni-button-segment.ts

@@ -1,17 +1,38 @@
+/**
+ * @file components/moni-button-segment.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';
 
 /**
- * A selectable segment button designed to be grouped inside a `moni-segmented-button`.
+ * Material Design 3 Segmented Button component (Legacy).
+ *
+ * **Deprecation Notice:** The M3 spec (`m3-docs/components/segmented-buttons/overview.md`)
+ * has replaced the bespoke segmented button component with standard buttons arranged
+ * in a "connected" group. Please use `<moni-button-group variant="connected">`
+ * containing standard `<moni-button>` elements instead of this component.
+ *
+ * This component remains for backwards compatibility but will be removed in a
+ * future major release. It renders a single segment within a `<moni-segmented-button>`.
+ *
+ * @deprecated Use `<moni-button-group variant="connected">` instead.
+ *
+ * @example
+ * ```html
+ * <!-- Legacy usage (not recommended) -->
+ * <moni-segmented-button>
+ *   <moni-button-segment value="day" checked>Day</moni-button-segment>
+ *   <moni-button-segment value="week">Week</moni-button-segment>
+ * </moni-segmented-button>
+ * ```
  *
- * Attributes:
- *  - value:      The value of the segment (default "on")
- *  - checked:    Whether the segment is checked/selected
- *  - disabled:   Whether the segment is disabled
- *  - position:   Automatically set by the parent (first | middle | last | solo)
- *  - hide-check: Hides the checkmark when selected
+ * @slot default - The segment label text.
  */
 @customElement('moni-button-segment')
 export class MoniButtonSegment extends MoniElement {