@moldable-ai/ui 0.2.26 → 0.2.31

package/src/components/ui/card.md

@@ -0,0 +1,43 @@
+# Card
+
+`Card` groups related content on one bounded surface. Its optional anatomy
+keeps a title, description, trailing action, content, and footer aligned.
+
+```tsx
+import {
+  Card,
+  CardAction,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from '@moldable-ai/ui'
+
+;<Card surface="raised">
+  <CardHeader>
+    <CardTitle>Project brief</CardTitle>
+    <CardDescription>Updated five minutes ago</CardDescription>
+    <CardAction>{/* compact action */}</CardAction>
+  </CardHeader>
+  <CardContent>{/* related content */}</CardContent>
+</Card>
+```
+
+## API
+
+- `Card` accepts native `div` props and `surface`: `default`, `raised`,
+  `recessed`, or `plain`. The default is `default`.
+- `default` uses the card fill, border, and shadow; `raised` uses the raised
+  surface; `recessed` uses the inset surface; `plain` provides structure
+  without chrome.
+- `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`,
+  and `CardFooter` accept native `div` props.
+- `CardProps` and `CardSurface` are exported.
+- Adding `border-b` to the header or `border-t` to the footer also enables
+  their matching separator spacing.
+
+Cards do not add region, heading, or button semantics. Use a real heading
+inside `CardTitle` when the title participates in the document outline, and
+keep actions as separate buttons or links. Do not make a whole card clickable
+by attaching button behavior to its `div`; use an explicit interactive element
+with a visible focus state.

package/src/components/ui/carousel.md

@@ -0,0 +1,47 @@
+# Carousel
+
+An Embla-backed sequence of peer slides with optional previous and next
+controls.
+
+```tsx
+import {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselNext,
+  CarouselPrevious,
+} from '@moldable-ai/ui'
+
+;<Carousel aria-label="Recent projects" className="mx-auto w-full max-w-lg">
+  <CarouselContent>
+    {projects.map((project) => (
+      <CarouselItem key={project.id}>{project.name}</CarouselItem>
+    ))}
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+```
+
+## API
+
+- `Carousel` accepts native `div` props plus `orientation`, `opts`, `plugins`,
+  and `setApi`. `orientation` defaults to `horizontal` and determines Embla's
+  axis, overriding `opts.axis`.
+- `setApi` receives the initialized `CarouselApi`, which is also exported.
+- `CarouselContent` owns the clipped viewport and flex track.
+- `CarouselItem` is one full-basis slide by default. Override its basis through
+  `className` to show multiple slides.
+- `CarouselPrevious` and `CarouselNext` accept shared `Button` props. They
+  default to `variant="outline"` and `size="icon"` and disable themselves at
+  their respective scroll boundary.
+
+The root exposes carousel region semantics and each item exposes slide group
+semantics; provide the root with `aria-label` or `aria-labelledby`. Left and
+Right Arrow scroll from anywhere inside the root in both orientations. Up and
+Down Arrow handling is not implemented, so prefer a horizontal carousel when
+keyboard direction must match its visual axis.
+
+Keep slide order stable, make important content available without hover, and
+avoid placing text-editing controls inside the carousel because captured
+Left/Right Arrow keys scroll the sequence.

package/src/components/ui/chart.md

@@ -0,0 +1,52 @@
+# Chart
+
+Theme-aware wrappers for Recharts. `ChartContainer` supplies responsive sizing,
+semantic chart styling, and config-driven labels, icons, and CSS color
+variables.
+
+```tsx
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  type ChartConfig,
+} from '@moldable-ai/ui'
+import { Bar, BarChart, XAxis } from 'recharts'
+
+const config = {
+  completed: { label: 'Completed', color: 'var(--chart-1)' },
+} satisfies ChartConfig
+
+<ChartContainer config={config} className="h-64 w-full">
+  <BarChart accessibilityLayer data={data}>
+    <XAxis dataKey="day" />
+    <ChartTooltip content={<ChartTooltipContent />} />
+    <Bar dataKey="completed" fill="var(--color-completed)" />
+  </BarChart>
+</ChartContainer>
+```
+
+## API
+
+- `ChartConfig` maps each series key to an optional `label` and `icon`, plus
+  either one `color` or both `theme.light` and `theme.dark` colors.
+- `ChartContainer` accepts native `div` props, required `config`, one Recharts
+  chart child, and an optional chart-scoping `id`. That `id` seeds the
+  generated `data-chart` value; it is not forwarded as the element's HTML
+  `id`. The container wraps its child in `ResponsiveContainer`, so give it a
+  definite width and height.
+- Configured colors become `--color-{series}` variables scoped to that chart.
+- `ChartTooltip` and `ChartLegend` are the Recharts primitives.
+- `ChartTooltipContent` supports `indicator="dot" | "line" | "dashed"`,
+  `hideLabel`, `hideIndicator`, `nameKey`, and `labelKey`. It consumes the
+  Recharts `active`, `payload`, `label`, `labelFormatter`, `formatter`, and
+  `color` inputs supplied by `ChartTooltip`.
+- `ChartLegendContent` supports `hideIcon`, `nameKey`, `payload`, and
+  `verticalAlign`.
+- `ChartStyle` is exported for advanced composition; `ChartContainer` already
+  renders it.
+
+Enable Recharts' `accessibilityLayer` on the chart primitive. Use literal
+series labels, semantic color variables, and another cue when color carries
+meaning. For charts whose exact values matter, provide a nearby textual
+summary or table rather than relying on a pointer tooltip.

package/src/components/ui/checkbox.md

@@ -0,0 +1,36 @@
+# Checkbox
+
+A binary or mixed-state form control built on Radix Checkbox.
+
+```tsx
+import { Checkbox } from '@moldable-ai/ui'
+
+;<label className="flex items-center gap-2">
+  <Checkbox
+    checked={enabled}
+    onCheckedChange={(checked) => setEnabled(checked === true)}
+  />
+  Enable notifications
+</label>
+```
+
+## API and behavior
+
+- Accepts Radix Checkbox root props, including controlled `checked` and
+  `onCheckedChange`, uncontrolled `defaultChecked`, `disabled`, `required`,
+  `name`, `value`, and `form`.
+- `checked` and `defaultChecked` support `true`, `false`, or
+  `'indeterminate'`. Activating an indeterminate checkbox moves it to checked.
+- `controlSize` is optional and accepts `mini`, `small`, `medium`, `large`, or
+  `xl`; when omitted, theme defaults determine its dimensions.
+- The check and indeterminate dash indicators are included.
+
+Associate every checkbox with visible label text through a wrapping `label` or
+matching `htmlFor` and `id`. Space toggles the focused control; Enter is
+intentionally prevented. Radix exposes the mixed value as
+`aria-checked="mixed"` and preserves native form participation.
+
+Use a checkbox for an independently selectable choice. Use `RadioGroup` for
+one choice from a set and `Switch` for a settings-style state that takes effect
+immediately. Do not rely on the checkmark or accent color as the only
+explanation of the choice.

package/src/components/ui/collapsible.md

@@ -41,9 +41,8 @@ Radix. Space and Enter toggle it. The chevron is decorative.
 
 ## Motion
 
-Motion is brief and uses the shared reduced-motion behavior. Set
-`motion="none"` for content where movement would distract or when a parent owns
-the transition.
+The section content animates by default. Set `motion="none"` when movement
+would distract or when a parent owns the transition.
 
 ## Don't
 

package/src/components/ui/color-well.md

@@ -1,11 +1,21 @@
 # ColorWell
 
-Compact color selection or read-only swatch.
+Compact native color selection or a read-only swatch.
 
 ```tsx
 <ColorWell aria-label="Project color" value={color} onValueChange={setColor} />
 ```
 
-Use the browser color input as the renderer fallback. `readOnly` presents the
-value without implying interactivity. Never make color the only representation
-of a status or category.
+## API
+
+- `value` accepts a native color-input value (normally `#rrggbb`) or `null`; an
+  empty value displays a checkerboard swatch.
+- `onValueChange` receives the native color input value.
+- `size` is `sm`, `default`, or `lg` and defaults to `default`.
+- `readOnly` defaults to `false`. When true, the component renders a
+  non-interactive image role instead of an input.
+- The accessible label defaults to “Choose color”; provide a specific label in
+  app UI.
+
+The interactive form uses the browser's native color input. Never make color
+the only representation of a status or category.

package/src/components/ui/combobox.md

@@ -4,9 +4,9 @@ Searchable single- or multi-value selection for longer option sets.
 
 ## When to use
 
-Use `Combobox` when users need to filter options, create values, or manage
-multiple selections. Use `Select` for a short fixed list, `Command` for actions,
-and `Input` for unconstrained text.
+Use `Combobox` when users need to filter a longer option set or manage multiple
+selections. Use `Select` for a short fixed list, `Command` for actions, and
+`Input` for unconstrained text.
 
 ## Anatomy
 

package/src/components/ui/confirm-dialog.md

@@ -71,10 +71,11 @@ colors or custom dialog elevation.
 ## Keyboard and accessibility
 
 The component inherits alert-dialog semantics and focus containment. The
-dialog content receives initial focus; Enter activates the marked primary
-action when appropriate, and pending state prevents dismissal. Write a
-specific title and describe the consequence, not merely “Are you sure?”.
-Error copy is announced with `role="alert"`.
+dialog content receives initial focus. Command+Enter activates the confirm
+action on macOS and iOS-family runtimes; Control+Enter does so elsewhere.
+Plain Enter keeps the focused control's native behavior, and pending state
+prevents dismissal. Write a specific title and describe the consequence, not
+merely “Are you sure?”. Error copy is announced with `role="alert"`.
 
 ## Do
 

package/src/components/ui/context-menu.md

@@ -119,10 +119,11 @@ command palette as well as the context menu.
 
 ## Platform behavior
 
-With `items`, a user-initiated context-menu gesture automatically opens the
+With `items`, a `contextmenu` event such as a secondary click opens the
 host-native menu when `nativeMenu` is advertised. The pointer position is its
 anchor, `selectedId` is delivered to `onSelectItem`, and dismissal is a no-op.
-No portable menu is rendered while that native request is open.
+No portable menu is rendered while that native request is open. Radix's
+touch/pen long press opens the portable menu directly.
 
 When the service is not advertised, including web and iOS, the same items
 automatically render through the existing Radix anatomy. If advertised

package/src/components/ui/date-field.md

@@ -29,4 +29,9 @@ Values use the native timezone-free `YYYY-MM-DD` form. Use `value`/`onValueChang
 - Use a calendar popover only for workflows that require richer range, availability, or event selection.
 - Do not replace the native picker to imitate a desktop control.
 
-A host may later provide a native date capability. Keep that behind an explicit cross-client contract and preserve this web implementation as the portable fallback.
+`DateField` itself is renderer-owned and does not call the host. A call site
+that deliberately prefers the host picker can use `useHostDateTimePicker()` or
+`pickDateTimeWithHost('date', ...)`, then keep `DateField` as its portable
+fallback. A `status: 'fallback'` result does not open renderer UI for the
+caller. See
+[`host-date-time-picker.md`](../../lib/host-date-time-picker.md).

package/src/components/ui/date-picker.md

@@ -44,9 +44,12 @@ focus returns to the trigger.
 
 ## Platform behavior
 
-This component is portable and uses no host API. A future native date or time
-control must be introduced through a shared host capability with this
-renderer-owned control as its fallback.
+This component is renderer-owned and does not call the host. A call site that
+deliberately prefers the host picker can use `useHostDateTimePicker()` or
+`pickDateTimeWithHost('date', ...)`, then keep `DatePicker` as its portable
+fallback. A `status: 'fallback'` result does not open renderer UI for the
+caller. See
+[`host-date-time-picker.md`](../../lib/host-date-time-picker.md).
 
 ## Don't
 

package/src/components/ui/dialog.md

@@ -41,19 +41,21 @@ temporary control overlays where seeing the underlying context is useful.
 Use `DialogAction` for footer commands that need the standard async and keyboard
 contracts. Its `loading` prop forwards to `Button`, preventing duplicate
 activation while retaining the label width and accessible name. Keep the dialog
-controlled, show inline field errors, and close only after success. Disable the
-whole form only when edits during submission would be unsafe. Use
-`ConfirmDialog` when confirmation is the entire workflow.
+controlled when an async result must own closure, show inline field errors, and
+close only after success. Disable the whole form only when edits during
+submission would be unsafe. Use `ConfirmDialog` when confirmation is the entire
+workflow.
 
 Set `primary` on at most one `DialogAction` to opt into the default-action
-shortcut. Command+Enter activates it on macOS; Control+Enter does so on other
-platforms. The shortcut works from anywhere in the dialog unless a focused
-control consumes the key event with `preventDefault()`, or the primary action is
-loading or disabled. Plain Enter keeps the focused control's native behavior.
-Use `Kbd` to show the shortcut when it improves discovery; render the
-platform-appropriate modifier in app code.
+shortcut. Command+Enter activates it on macOS and iOS-family runtimes;
+Control+Enter does so elsewhere. The shortcut works from anywhere in the dialog
+unless a focused control consumes the key event with `preventDefault()`, or the
+primary action is loading or disabled. Plain Enter keeps the focused control's
+native behavior. Use `Kbd` to show the shortcut when it improves discovery;
+render the platform-appropriate modifier in app code.
 
 Every dialog needs a `DialogTitle`. Add `DialogDescription` when the outcome or
-scope is not obvious. Escape, outside dismissal, initial focus, and focus return
-come from the Radix primitive; do not replace them with manual document event
-handlers.
+scope is not obvious. `DialogContent` focuses its own container on open by
+default; pass `onOpenAutoFocus` for a deliberate alternative. Escape, outside
+dismissal, and focus return come from the Radix primitive; do not replace them
+with manual document event handlers.

package/src/components/ui/drawer.md

@@ -0,0 +1,58 @@
+# Drawer
+
+## Purpose
+
+`Drawer` presents a modal surface that enters from a screen edge and can be
+dismissed by dragging, pressing Escape, or using a close action. It wraps Vaul
+and defaults to the bottom edge.
+
+## Usage
+
+```tsx
+import {
+  Button,
+  Drawer,
+  DrawerClose,
+  DrawerContent,
+  DrawerDescription,
+  DrawerFooter,
+  DrawerHeader,
+  DrawerTitle,
+  DrawerTrigger,
+} from '@moldable-ai/ui'
+
+;<Drawer>
+  <DrawerTrigger asChild>
+    <Button>Open upload queue</Button>
+  </DrawerTrigger>
+  <DrawerContent>
+    <DrawerHeader>
+      <DrawerTitle>Upload queue</DrawerTitle>
+      <DrawerDescription>Two files are ready to sync.</DrawerDescription>
+    </DrawerHeader>
+    <DrawerFooter>
+      <Button>Upload all</Button>
+      <DrawerClose asChild>
+        <Button variant="outline">Cancel</Button>
+      </DrawerClose>
+    </DrawerFooter>
+  </DrawerContent>
+</Drawer>
+```
+
+`Drawer` accepts the Vaul root props, including controlled `open` and
+`onOpenChange`, `direction="top" | "bottom" | "left" | "right"`, snap points,
+and dismissal options. `DrawerContent` supplies the portal and overlay. Bottom
+drawers also show the built-in drag indicator.
+
+## Quality bar
+
+- Always include `DrawerTitle`; add `DrawerDescription` when the title does not
+  fully explain the task.
+- Keep the primary action and an explicit close action in `DrawerFooter`.
+- Use `asChild` when a shared button should be the trigger or close control.
+- Keep long drawer bodies independently scrollable and preserve focus
+  management from the primitive.
+- Use `Dialog` for a centered decision and `Sheet` for a persistent side panel.
+- Do not disable outside-click or Escape dismissal without another obvious way
+  to close the drawer.

package/src/components/ui/error-boundary-view.md

@@ -25,7 +25,7 @@ nested cards.
 ## Usage
 
 ```tsx
-import { ErrorBoundaryView } from '@moldable-ai/ui'
+import { Button, ErrorBoundaryView } from '@moldable-ai/ui'
 
 function PaneError() {
   return (

package/src/components/ui/field.md

@@ -58,7 +58,8 @@ Use `orientation="horizontal"` for compact checkbox/radio rows and `orientation=
 - 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.
+- Use real `disabled` state and set `data-disabled="true"` on `Field` when its
+  label or title should also appear disabled.
 - Place validation directly after the affected control.
 - Group related checkbox or radio controls in `FieldSet` with `FieldLegend`.
 

package/src/components/ui/form.md

@@ -0,0 +1,71 @@
+# Form
+
+## Purpose
+
+The form adapter connects React Hook Form state to labels, controls,
+descriptions, and validation messages. `Form` is `FormProvider`; the native
+`form` element remains part of the composition.
+
+## Usage
+
+```tsx
+import { useForm } from 'react-hook-form'
+import {
+  Button,
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+  Input,
+} from '@moldable-ai/ui'
+
+type Values = { project: string }
+
+function ProjectForm() {
+  const form = useForm<Values>({ defaultValues: { project: '' } })
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(saveProject)}>
+        <FormField
+          control={form.control}
+          name="project"
+          rules={{ required: 'Enter a project name.' }}
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Project name</FormLabel>
+              <FormControl>
+                <Input {...field} />
+              </FormControl>
+              <FormDescription>Shown in the app titlebar.</FormDescription>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit">Save</Button>
+      </form>
+    </Form>
+  )
+}
+```
+
+`FormField` forwards React Hook Form `Controller` props. Within its
+`FormItem`, `FormLabel` targets the slotted `FormControl`; the control receives
+`id`, `aria-invalid`, and description/message references. `FormMessage` shows
+the current field error message, falls back to its children, and renders
+nothing when both are absent. `useFormField` exposes the generated IDs and
+field state to custom parts.
+
+## Quality bar
+
+- Put `FormControl`, `FormLabel`, `FormDescription`, and `FormMessage` inside
+  the same `FormField` and `FormItem`.
+- Give `FormControl` one interactive child that can accept the injected
+  accessibility props.
+- Keep validation messages specific and place them beside the affected field.
+- Use a native `form` with `onSubmit`; `Form` alone does not submit anything.
+- Prefer the simpler `Field` primitives when React Hook Form state is not
+  needed.

package/src/components/ui/grid.md

@@ -61,9 +61,10 @@ Prefer changing this value at deliberate window breakpoints. A smaller window sh
 - 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`.
+- Space changes selection when selection is enabled.
+- Enter changes selection when enabled and invokes `onAction`.
+- A single pointer click changes selection when selection is enabled. 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

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

@@ -22,7 +22,10 @@ import { IconButton } from '@moldable-ai/ui'
 </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.
+`size` is `xs`, `sm`, `default`, `lg`, or `xl`. `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
 

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

@@ -0,0 +1,49 @@
+# Input Group
+
+## Purpose
+
+`InputGroup` combines one text control with inline or stacked context and
+actions inside a single bordered surface.
+
+## Usage
+
+```tsx
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+  InputGroupText,
+} from '@moldable-ai/ui'
+
+;<InputGroup>
+  <InputGroupAddon>
+    <InputGroupText>https://</InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput aria-label="Workspace address" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton aria-label="Copy address">Copy</InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+Use `InputGroupInput` for a native input or `InputGroupTextarea` for multiline
+text. `InputGroupAddon` defaults to `inline-start` and also supports
+`inline-end`, `block-start`, and `block-end`. Clicking a non-button inline
+addon focuses the contained input. `InputGroupButton` defaults to
+`type="button"`, `variant="ghost"`, and `size="xs"`; its sizes are `xs`, `sm`,
+`icon-xs`, and `icon-sm`.
+
+## Quality bar
+
+- Label the actual input or textarea; the group and its adornments do not
+  provide its accessible name.
+- Mark decorative icons `aria-hidden` and give icon-only buttons an
+  `aria-label`.
+- Put interactive controls in `InputGroupButton`, not in a clickable addon.
+- Set `aria-invalid` on the input or textarea so the group shows its error
+  state.
+- When disabling the control, add `data-disabled="true"` to `InputGroup` if
+  its addons should also appear disabled.
+- Keep addons short. Use `block-start` or `block-end` for context that cannot
+  fit inline.

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

@@ -0,0 +1,56 @@
+# Input OTP
+
+## Purpose
+
+`InputOTP` presents a one-time code as visual slots while retaining one
+keyboard- and paste-friendly input through the `input-otp` primitive.
+
+## Usage
+
+```tsx
+import {
+  InputOTP,
+  InputOTPGroup,
+  InputOTPSeparator,
+  InputOTPSlot,
+} from '@moldable-ai/ui'
+
+;<InputOTP
+  aria-label="Verification code"
+  maxLength={6}
+  value={code}
+  onChange={setCode}
+>
+  <InputOTPGroup>
+    {[0, 1, 2].map((index) => (
+      <InputOTPSlot key={index} index={index} />
+    ))}
+  </InputOTPGroup>
+  <InputOTPSeparator />
+  <InputOTPGroup>
+    {[3, 4, 5].map((index) => (
+      <InputOTPSlot key={index} index={index} />
+    ))}
+  </InputOTPGroup>
+</InputOTP>
+```
+
+`maxLength` defines the code length and the rendered slot indexes must match
+it. Native input props and `input-otp` options such as `pattern`,
+`pasteTransformer`, `onComplete`, and `pushPasswordManagerStrategy` pass
+through. `containerClassName` styles the visible slot container; `className`
+targets the underlying input. `InputOTPSeparator` renders a separator role
+with the shared minus icon.
+
+## Quality bar
+
+- Give the root a visible label or an accessible name.
+- Match every `InputOTPSlot` index to a valid position below `maxLength`.
+- Use `pattern` when the code format is restricted; do not reject valid pasted
+  codes silently.
+- Let users paste and use password managers or system code autofill; add an
+  appropriate `autoComplete` value for the workflow.
+- Report expiration, resend status, and server errors outside the slots in
+  text, not by color alone.
+- Do not submit solely because the last character was entered unless the
+  result is safe, reversible, and clearly communicated.

package/src/components/ui/input.md

@@ -0,0 +1,40 @@
+# Input
+
+## Purpose
+
+`Input` is the shared styled native input. It preserves native input types,
+editing behavior, constraints, and form participation while applying semantic
+control tokens.
+
+## Usage
+
+```tsx
+import { Input, Label } from '@moldable-ai/ui'
+
+;<div className="grid gap-2">
+  <Label htmlFor="workspace-name">Workspace name</Label>
+  <Input
+    id="workspace-name"
+    name="workspaceName"
+    autoComplete="organization"
+    required
+  />
+</div>
+```
+
+All native input props pass through. `controlSize` accepts `mini`, `small`,
+`medium`, `large`, or `xl`; when omitted, the input inherits the active theme
+size. File inputs receive matching typography and file-button treatment.
+
+## Quality bar
+
+- Associate every input with a visible label or an accessible name.
+- Choose the correct native `type`, `name`, `autoComplete`, `inputMode`, and
+  constraints for the data.
+- Set `aria-invalid` when invalid and connect supporting or error text with
+  `aria-describedby`.
+- Use `disabled` only for unavailable controls; use `readOnly` for values that
+  should remain selectable.
+- Keep placeholder text as a short hint, never as the only label.
+- Use `Textarea`, `SearchField`, `DateField`, or `InputGroup` when their
+  behavior matches the task more closely.