@moldable-ai/ui 0.2.19 → 0.2.21

package/src/components/ui/empty.md

@@ -0,0 +1,87 @@
+# Empty
+
+## Purpose
+
+`Empty` describes a normal absence of content or a blocked first-run state. It gives the user a quiet explanation and, when needed, one clear next action.
+
+Use `Alert` when an operation failed. Use `Skeleton` or `Spinner` while data is still loading. Do not render an empty state before the initial query has resolved.
+
+## Usage patterns
+
+```tsx
+import { Database } from 'lucide-react'
+import {
+  Button,
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from '@moldable-ai/ui'
+
+;<Empty variant="pane" safeBottom>
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <Database />
+    </EmptyMedia>
+    <EmptyTitle>Choose a connection</EmptyTitle>
+    <EmptyDescription>
+      Select a saved connection to browse its tables.
+    </EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <Button type="button" size="sm" className="cursor-pointer">
+      Add connection
+    </Button>
+  </EmptyContent>
+</Empty>
+```
+
+For a successful zero state, omit the action when there is nothing useful to do:
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyTitle>Inbox clear</EmptyTitle>
+    <EmptyDescription>No messages need your attention.</EmptyDescription>
+  </EmptyHeader>
+</Empty>
+```
+
+## API summary
+
+- `Empty`: centered flex container for the complete state.
+- `Empty variant`: `compact`, `pane`, or `full`; defaults to `pane`.
+- `Empty safeBottom`: adds host-provided chat clearance. Do not enable it when
+  an owning `AppFrameContent` or parent scroll region already applies clearance.
+- `EmptyHeader`: groups media, title, and description.
+- `EmptyMedia`: `variant="default"` or `variant="icon"`.
+- `EmptyTitle`: primary label.
+- `EmptyDescription`: supporting text with styled inline links.
+- `EmptyContent`: optional actions or secondary controls.
+- All parts accept native props for their rendered element and a `className`.
+
+## Do
+
+- Use a one-to-four-word title and at most one sentence of description.
+- Show one primary setup action when the state is blocked.
+- Distinguish first-run, filtered-zero, permission, and successful-zero states.
+- Keep the app’s normal shell or pane structure visible.
+- Use `safeBottom` when the empty state itself owns a pane that reaches the bottom.
+
+## Don't
+
+- Do not use welcome-page copy, feature grids, or marketing language.
+- Do not explain obvious controls.
+- Do not add an illustration only to fill space.
+- Do not show a creation action when silence or completion is the correct state.
+- Do not make the empty state a giant nested card.
+
+## Moldable considerations
+
+An empty state should feel like part of a local instrument, not a landing page. Keep it visually small even when centered. If the desktop chat can resolve the state, provide specific app context or an explicit “Ask Moldable about this” affordance that prefills desktop chat; do not add another chat box.
+
+For scrollable panes, prefer `safeBottom` on the owning `ScrollArea`. Apply it
+to `Empty` only when the empty state is the owner, so nested states do not add
+the same safe area twice.

package/src/components/ui/field.md

@@ -0,0 +1,77 @@
+# Field
+
+## Purpose
+
+The field primitives compose accessible, consistent form rows. Use them to connect labels, controls, descriptions, validation messages, and related groups without wrapping every input in a card.
+
+## Usage patterns
+
+```tsx
+import {
+  Field,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLabel,
+  Input,
+} from '@moldable-ai/ui'
+
+;<FieldGroup>
+  <Field data-invalid={Boolean(error)}>
+    <FieldLabel htmlFor="connection-name">Connection name</FieldLabel>
+    <Input
+      id="connection-name"
+      aria-invalid={Boolean(error)}
+      aria-describedby={
+        error ? 'connection-name-error' : 'connection-name-help'
+      }
+    />
+    <FieldDescription id="connection-name-help">
+      Used only to identify this connection.
+    </FieldDescription>
+    <FieldError
+      id="connection-name-error"
+      errors={error ? [{ message: error }] : []}
+    />
+  </Field>
+</FieldGroup>
+```
+
+Use `orientation="horizontal"` for compact checkbox/radio rows and `orientation="responsive"` when the label and control should align horizontally only when the field-group container is wide enough.
+
+## API summary
+
+- `FieldSet`: semantic `fieldset` for related controls.
+- `FieldLegend`: `variant="legend"` or `"label"` for fieldset headings.
+- `FieldGroup`: container-query-aware vertical group.
+- `Field`: `role="group"` with `orientation="vertical"`, `"horizontal"`, or `"responsive"`.
+- `FieldLabel`: wraps `Label`; supports `htmlFor`.
+- `FieldTitle`: non-label heading for composite controls.
+- `FieldContent`: groups a control with its description and error.
+- `FieldDescription`: supporting text with styled inline links.
+- `FieldError`: accepts `children` or `errors?: Array<{ message?: string } | undefined>`; duplicate messages are removed and multiple messages render as a list.
+- `FieldSeparator`: divider with optional centered text.
+- Each part accepts its native element props and `className`.
+
+## Do
+
+- Give every control a visible label or an accessible name.
+- Connect labels and descriptions with `htmlFor`, `id`, and `aria-describedby`.
+- Set both `data-invalid` on `Field` and `aria-invalid` on the control.
+- Use real `disabled` state and reflect it on the field group when styling needs it.
+- Place validation directly after the affected control.
+- Group related checkbox or radio controls in `FieldSet` with `FieldLegend`.
+
+## Don't
+
+- Do not use placeholder text as the only label.
+- Do not show validation only by changing border color.
+- Do not wait until submission to reveal formatting requirements the user needs beforehand.
+- Do not use horizontal fields when labels or values will be cramped.
+- Do not store secrets in ordinary app state when they belong in aivault.
+
+## Moldable considerations
+
+Forms should be compact and bounded. Use dialogs for small setup or edit workflows, with their body scrolling internally above `--chat-safe-padding`. Put advanced options behind a secondary disclosure.
+
+Use plain `Input` or `Textarea` for short values only. Use `MarkdownEditor` for structured prose and Monaco for code, SQL, JSON, or configuration. Async validation and save states should stay local to the field or submit button and must prevent duplicate actions.

package/src/components/ui/grid.md

@@ -0,0 +1,109 @@
+# Grid
+
+## Purpose
+
+`Grid` is a keyboard-aware, selectable tile collection for artifacts, projects, media, templates, and other visual libraries. It provides two-dimensional arrow navigation, selection, activation, disabled-item behavior, and ARIA grid structure.
+
+Use `List` when rows are primarily textual or the container is narrow. Use CSS Grid directly for non-interactive page layout.
+
+## Basic usage
+
+```tsx
+import {
+  Grid,
+  GridItem,
+  GridItemContent,
+  GridItemDescription,
+  GridItemMedia,
+  GridItemTitle,
+} from '@moldable-ai/ui'
+
+;<Grid
+  aria-label="Artifacts"
+  columns={3}
+  selectionMode="single"
+  onAction={(value) => openArtifact(value)}
+>
+  {artifacts.map((artifact) => (
+    <GridItem key={artifact.id} value={artifact.id}>
+      <GridItemMedia>
+        <img src={artifact.previewUrl} alt="" />
+      </GridItemMedia>
+      <GridItemContent>
+        <GridItemTitle>{artifact.title}</GridItemTitle>
+        <GridItemDescription>{artifact.summary}</GridItemDescription>
+      </GridItemContent>
+    </GridItem>
+  ))}
+</Grid>
+```
+
+`GridItem` elements must be direct children. `Grid` groups them into semantic rows according to `columns`.
+
+## Responsive columns
+
+Keep the `columns` value aligned with the rendered column count because it drives both layout and keyboard movement:
+
+```tsx
+const columns = useCompactWindow() ? 1 : 3
+
+<Grid columns={columns} aria-label="Projects">
+  {/* direct GridItem children */}
+</Grid>
+```
+
+Prefer changing this value at deliberate window breakpoints. A smaller window should normally reduce the number of columns before shrinking card content below its useful size.
+
+## Interaction contract
+
+- Arrow Left/Right moves within the current row and stops at its edge.
+- Arrow Up/Down moves within the current column and stops at its edge.
+- Home and End move to the first and last available tile in the current row.
+- Control/Command + Home and End move to the first and last available tile in
+  the entire grid.
+- Space changes selection.
+- Enter changes selection and invokes `onAction`.
+- A single pointer click changes selection. A double click invokes `onAction`.
+- Disabled tiles are skipped.
+- Buttons and links inside a tile preserve their own pointer behavior.
+- When the grid first mounts, the first selected, enabled tile receives the
+  roving tab stop. If nothing is selected, the first enabled tile receives it.
+
+## API summary
+
+### `Grid`
+
+- `columns`: positive integer used for layout, row semantics, and vertical navigation. Defaults to `1`.
+- `selectionMode`: `none`, `single`, or `multiple`. Defaults to `none`.
+- `selectedValues` / `defaultSelectedValues`: controlled or initial selected keys.
+- `onSelectionChange(values)`: receives a new read-only `Set`.
+- `onAction(value)`: invoked by Enter or a double click.
+- `loop`: wraps directional navigation. Defaults to `false`.
+- `disabled`: disables the entire collection.
+
+### `GridItem`
+
+- `value`: stable application key.
+- `disabled`: removes the tile from focus, selection, and activation.
+
+`GridItemMedia`, `GridItemContent`, `GridItemTitle`, and `GridItemDescription` provide a consistent preview-card anatomy.
+
+## Do
+
+- Provide a collection label.
+- Keep every preview at a consistent aspect ratio within one grid.
+- Preserve titles and essential state at narrow widths; remove decorative metadata first.
+- Use an empty state outside the grid when there are no items.
+- Lazy-load large preview images and provide useful image alternative text when the image conveys information not already in the title.
+
+## Don't
+
+- Do not use `Grid` as a general page-layout primitive.
+- Do not hide essential actions behind hover alone.
+- Do not make every tile independently tabbable.
+- Do not let visual CSS columns disagree with the `columns` prop.
+- Do not nest interactive tiles.
+
+## Window and canvas guidance
+
+Give visual grids room to breathe in a primary canvas, but keep their controls in a compact toolbar. Prefer one to three columns in narrow app windows and denser layouts only when previews remain legible. A standalone app window should own its loading, empty, selection, and error states; do not assume a surrounding desktop shell supplies them.

package/src/components/ui/icon-button.md

@@ -0,0 +1,36 @@
+# Icon Button
+
+## Purpose
+
+`IconButton` is the shared recipe for a compact action represented by one icon. It builds on `Button`, requires an accessible `label`, and standardizes icon sizing, busy state, shape, and density.
+
+## Usage
+
+```tsx
+import { RefreshCw } from 'lucide-react'
+import { IconButton } from '@moldable-ai/ui'
+
+;<IconButton
+  label="Refresh events"
+  tooltip
+  size="sm"
+  variant="ghost"
+  loading={refreshing}
+  onClick={refresh}
+>
+  <RefreshCw />
+</IconButton>
+```
+
+`size` is `xs`, `sm`, `default`, or `lg`. `shape` is `rounded` or `circle`. `loading` disables the control, exposes `aria-busy`, and replaces the icon with a progress indicator. `tooltip` may be `true` to reuse the label as a native hint or a specific string.
+
+## Quality bar
+
+- Use an explicit verb-led label, even when the icon seems obvious.
+- Prefer `xs` or `sm` in compact toolbars and inspectors.
+- Use the same icon for the same action throughout an app.
+- Pair unfamiliar actions with the shared `Tooltip`; a native title is only a lightweight fallback.
+- Keep destructive actions visually and textually clear.
+- Do not place text inside `IconButton`, suppress its accessible name, or make an unavailable action appear enabled.
+
+The component represents an app action only. Window close, minimize, zoom, sharing, and host menus remain host-owned capabilities.

package/src/components/ui/inspector.md

@@ -0,0 +1,11 @@
+# Inspector
+
+Secondary property controls for the current selection.
+
+Compose `Inspector`, `InspectorHeader`, `InspectorContent`,
+`InspectorSection`, and aligned `InspectorRow` pairs. Controls should usually
+use compact sizes.
+
+The inspector must remain subordinate to the primary pane. Collapse it when
+width is constrained, group related properties, and avoid placing primary
+workflow actions inside it.

package/src/components/ui/item.md

@@ -0,0 +1,87 @@
+# Item
+
+## Purpose
+
+The item primitives compose dense, scannable object rows with optional media, metadata, actions, and secondary regions. Use them for messages, files, meetings, tasks, records, and settings rows.
+
+Use `Table` for strongly tabular data and `Card` only when each object genuinely needs independent framing.
+
+## Usage patterns
+
+```tsx
+import { FileText, MoreHorizontal } from 'lucide-react'
+import {
+  Button,
+  Item,
+  ItemActions,
+  ItemContent,
+  ItemDescription,
+  ItemGroup,
+  ItemMedia,
+  ItemSeparator,
+  ItemTitle,
+} from '@moldable-ai/ui'
+
+;<ItemGroup>
+  <Item size="sm">
+    <ItemMedia variant="icon">
+      <FileText />
+    </ItemMedia>
+    <ItemContent className="min-w-0">
+      <ItemTitle className="max-w-full truncate">Project notes.md</ItemTitle>
+      <ItemDescription className="truncate">
+        Edited 8 minutes ago
+      </ItemDescription>
+    </ItemContent>
+    <ItemActions>
+      <Button
+        type="button"
+        variant="ghost"
+        size="icon-xs"
+        className="cursor-pointer"
+        aria-label="More actions"
+      >
+        <MoreHorizontal />
+      </Button>
+    </ItemActions>
+  </Item>
+  <ItemSeparator />
+</ItemGroup>
+```
+
+Use `asChild` when the whole item is a link or another interactive primitive. Avoid putting nested interactive controls inside an item whose entire surface is already a link.
+
+## API summary
+
+- `ItemGroup`: `role="list"` container.
+- `Item`: `variant="default"`, `"outline"`, or `"muted"`; `size="default"` or `"sm"`; optional `asChild`.
+- `ItemMedia`: `variant="default"`, `"icon"`, or `"image"`.
+- `ItemContent`: flexible title/description column.
+- `ItemTitle`, `ItemDescription`: primary and secondary text.
+- `ItemActions`: trailing controls.
+- `ItemHeader`, `ItemFooter`: full-width secondary rows.
+- `ItemSeparator`: horizontal `Separator`.
+- All components accept native props for their rendered element and `className`.
+
+## Do
+
+- Keep a stable left-middle-right scan order.
+- Add `min-w-0` to flexible content and truncate or line-clamp unpredictable text.
+- Keep times, counts, and status controls `shrink-0`.
+- Make selected state visible with more than color when practical.
+- Expose hover actions on focus and through a menu or app command.
+- Use separators or a shared group surface for rhythm instead of one floating card per row.
+
+## Don't
+
+- Do not nest links or buttons inside a whole-row link.
+- Do not let badges and actions push the primary label out of view.
+- Do not make every row tall enough to look like a marketing card.
+- Do not hide the only route to an action behind hover.
+- Do not place unbounded text in a fixed-height row.
+
+## Moldable considerations
+
+For repeated object browsers, `size="sm"` is the useful baseline; tune row height toward the app archetype rather than adding padding for decoration. A scrolling item group should clear chat with `pb-[calc(var(--chat-safe-padding,0px)+1rem)]`, or more when a bottom dock is present.
+
+Use the selected item to update desktop chat instructions with specific object context. Important row actions should be available through Cmd+K or a contextual menu, especially when the visual action is compact or hover-revealed.

package/src/components/ui/list.md

@@ -0,0 +1,140 @@
+# List
+
+## Purpose
+
+`List` is a keyboard-aware collection for compact rows such as files, sessions, workspaces, commands, and inspector results. It owns roving focus, optional selection, disabled-item behavior, and activation without forcing an app-specific data model.
+
+Use `ItemGroup` for a static group that does not need collection interaction. Use `Command` for filtering and executing a command palette.
+
+## Basic usage
+
+```tsx
+import {
+  List,
+  ListItem,
+  ListItemContent,
+  ListItemDescription,
+  ListItemTitle,
+} from '@moldable-ai/ui'
+
+;<List
+  aria-label="Documents"
+  selectionMode="single"
+  defaultSelectedValues={['brief']}
+  onAction={(value) => openDocument(value)}
+>
+  <ListItem value="brief">
+    <ListItemContent>
+      <ListItemTitle>Project brief</ListItemTitle>
+      <ListItemDescription>Edited 8 minutes ago</ListItemDescription>
+    </ListItemContent>
+  </ListItem>
+  <ListItem value="archive" disabled>
+    <ListItemContent>
+      <ListItemTitle>Archive</ListItemTitle>
+      <ListItemDescription>Unavailable offline</ListItemDescription>
+    </ListItemContent>
+  </ListItem>
+</List>
+```
+
+## Sections
+
+Group related options with `ListSection` and give every section an accessible
+name. `ListSectionHeader` automatically labels its containing section:
+
+```tsx
+<List aria-label="Documents" selectionMode="single">
+  <ListSection>
+    <ListSectionHeader>Recent</ListSectionHeader>
+    <ListItem value="brief">Project brief</ListItem>
+    <ListItem value="notes">Research notes</ListItem>
+  </ListSection>
+  <ListSection aria-label="Archived documents">
+    <ListItem value="archive">Archive</ListItem>
+  </ListSection>
+</List>
+```
+
+Use either `ListSectionHeader`, `aria-label`, or an explicit
+`aria-labelledby` value for each section. Keyboard movement follows the
+rendered DOM order across section boundaries.
+
+For controlled selection, pass an iterable to `selectedValues` and replace it when `onSelectionChange` fires:
+
+```tsx
+const [selected, setSelected] = useState<ReadonlySet<string>>(
+  () => new Set(['inbox']),
+)
+
+<List
+  aria-label="Mailboxes"
+  selectionMode="multiple"
+  selectedValues={selected}
+  onSelectionChange={setSelected}
+>
+  {/* ListItem children */}
+</List>
+```
+
+## Interaction contract
+
+- Arrow Up/Down moves through a vertical list; Arrow Left/Right moves through a horizontal list.
+- Home and End move to the first and last available item.
+- Space changes selection.
+- Enter changes selection and invokes `onAction`.
+- A single pointer click changes selection. A double click invokes `onAction`.
+- Disabled items are skipped during keyboard navigation and cannot be selected or activated.
+- Interactive descendants such as buttons and links keep their own pointer behavior. They do not select or activate the containing item.
+- Focus uses a roving `tabIndex`, so the collection contributes one stop to the tab order.
+- When the list first mounts, the first selected, enabled item receives the roving tab stop. If nothing is selected, the first enabled item receives it.
+
+## API summary
+
+### `List`
+
+- `selectionMode`: `none`, `single`, or `multiple`. Defaults to `none`.
+- `selectedValues` / `defaultSelectedValues`: controlled or initial selected keys.
+- `onSelectionChange(values)`: receives a new read-only `Set`.
+- `onAction(value)`: invoked by Enter or a double click.
+- `orientation`: `vertical` or `horizontal`. Defaults to `vertical`.
+- `loop`: wraps arrow navigation at collection boundaries. Defaults to `false`.
+- `disabled`: disables the entire collection.
+
+### `ListItem`
+
+- `value`: stable application key; required and independent of React's `key`.
+- `disabled`: removes the row from focus, selection, and activation.
+- Native `div` props and event handlers are composed before collection behavior. Call `event.preventDefault()` to cancel the built-in response.
+
+`ListItemContent`, `ListItemTitle`, `ListItemDescription`, and `ListItemActions` provide compact row layout without changing semantics.
+
+### `ListSection`
+
+- Groups related items with `role="group"`.
+- Use `ListSectionHeader` for an automatically connected visible label.
+- Alternatively, provide `aria-label` or `aria-labelledby`.
+
+## Do
+
+- Give every collection a visible label or `aria-label`.
+- Give every section an accessible label.
+- Keep values stable when filtering or reordering.
+- Put the primary row identity in `ListItemTitle` and secondary metadata in `ListItemDescription`.
+- Use selection to represent durable collection state and action to open or execute.
+- Keep row actions keyboard reachable; label icon-only controls.
+
+## Don't
+
+- Do not put a `List` inside another list item.
+- Do not use array indexes as values when rows can reorder.
+- Do not put buttons, links, or other interactive controls inside selectable
+  listbox items. Put independent actions outside the listbox or use a pattern
+  whose child-interaction model supports them.
+- Do not rely on double click as the only way to perform an important action.
+- Do not add a second manual arrow-key handler to the same collection.
+- Do not visually mark focus and selection as if they were the same state.
+
+## Window and pane guidance
+
+Lists should stay compact in sidebars and inspectors. Let the surrounding pane own its border and material; add a list background only when the list is itself a distinct surface. In narrow windows, preserve the row title and move secondary actions into a menu before truncating the primary label.

package/src/components/ui/material.md

@@ -0,0 +1,51 @@
+# Material
+
+Adaptive material for navigation and control chrome.
+
+```tsx
+<Material asChild variant="regular" elevation="none">
+  <Toolbar>{/* context and actions */}</Toolbar>
+</Material>
+
+<MaterialGroup variant="regular" shape="capsule" spacing="compact">
+  <IconButton label="Previous" variant="ghost">
+    <ChevronLeft />
+  </IconButton>
+  <IconButton label="Next" variant="ghost">
+    <ChevronRight />
+  </IconButton>
+</MaterialGroup>
+```
+
+## Variants
+
+- `regular` provides a frosted, legible control or navigation layer.
+- `clear` is less frosted and is only for compact controls floating over
+  photos, maps, video, or another richly colored canvas.
+
+Both variants start with an opaque fallback. Backdrop sampling is enabled only
+when the renderer supports it. Reduced transparency and forced colors keep the
+fallback opaque.
+
+## Grouping
+
+`MaterialGroup` creates one sampled layer for a related cluster. Put ordinary
+ghost or transparent controls inside it. Do not wrap each child in another
+`Material`; nested sampling creates muddy, inconsistent results.
+
+Use separate `Material` instances only when controls are spatially detached and
+do not read as one group.
+
+## Rules
+
+- Use material for toolbars, compact floating controls, menus, and other
+  temporary control layers.
+- Keep documents, calendars, tables, forms, cards, sheets, and primary content
+  canvases opaque.
+- Prefer `regular`. A `clear` surface needs stable contrast across every part
+  of the media behind it.
+- Use `interactive` only when the material surface itself is the control.
+- Do not animate blur or saturation. Shared motion tokens provide restrained
+  press feedback and remove it when reduced motion is requested.
+- CSS material samples content inside the renderer. Native behind-window
+  material remains owned by the host.

package/src/components/ui/navigation-button-group.md

@@ -0,0 +1,46 @@
+# NavigationButtonGroup
+
+`NavigationButtonGroup` presents paired back and forward actions with one
+consistent compact treatment.
+
+```tsx
+<NavigationButtonGroup
+  canGoBack={historyIndex > 0}
+  canGoForward={historyIndex < history.length - 1}
+  onBack={goBack}
+  onForward={goForward}
+/>
+```
+
+## API
+
+- `canGoBack` and `canGoForward` disable unavailable directions.
+- `onBack` and `onForward` perform caller-owned navigation.
+- `backLabel` and `forwardLabel` customize accessible names.
+- `size` accepts the `IconButton` size scale.
+- `variant` is `ghost` or `outline`.
+- Native `ButtonGroup` props apply to the group.
+
+## Keyboard and accessibility
+
+The root has `role="group"` and the default accessible name “Navigation”.
+Each icon button has a stable accessible name and participates in normal Tab
+order. The component does not install global keyboard shortcuts.
+
+## Platform behavior
+
+This component is portable. It does not own browser history, Moldable
+navigation state, or native window history. Connect it to the navigation owner
+for the current surface.
+
+## Do
+
+- Put it in a leading toolbar group.
+- Disable unavailable directions.
+- Keep back and forward behavior scoped to the visible pane or app.
+
+## Don't
+
+- Do not render a fake forward action when no forward history exists.
+- Do not use it for undo and redo.
+- Do not add a second tooltip around its buttons.

package/src/components/ui/notification-dot.md

@@ -0,0 +1,7 @@
+# NotificationDot
+
+A tiny, decorative unread or changed-state marker.
+
+Pair the dot with adjacent accessible text or an accessible label on its
+container. The dot is intentionally hidden from assistive technology.
+Use `Status` when the state needs a spoken label or semantic tone.

package/src/components/ui/number-input.md

@@ -0,0 +1,19 @@
+# NumberInput
+
+Compact numeric entry with optional unit and stepper actions.
+
+```tsx
+<NumberInput
+  aria-label="Opacity"
+  min={0}
+  max={100}
+  unit="%"
+  value={opacity}
+  onValueChange={setOpacity}
+/>
+```
+
+Use in inspectors and settings where the numeric value matters. Use `Slider`
+when relative adjustment matters more than exact entry. Always supply a visible
+label or `aria-label`. Treat `null` as empty input and validate domain-specific
+constraints outside the component.