@jovertical/mise-design-system 1.0.0 → 1.1.0

package/skills/mise/components/forms.md

@@ -0,0 +1,712 @@
+<!-- Generated by pnpm build:skill. Do not edit by hand. -->
+
+# Forms
+
+## ButtonGroup
+
+`import { ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants } from '@jovertical/mise-design-system'`
+
+Adjacent controls that share one edge instead of each carrying its own radius and gap: a segmented set of buttons, or two buttons and the input they act on, read as one control.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |  |
+
+Also takes: every `<div>` attribute.
+
+### `ButtonGroupSeparator`
+
+A rule between two parts of a group. Vertical by default, for a row.
+
+Also takes: everything `Separator` takes.
+
+### `ButtonGroupText`
+
+A fixed label inside a group: a unit, a prefix, a caption ahead of an action.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `child` | `Snippet<[{ props: Record<string, unknown> }]>` |  |  |
+
+Also takes: every `<div>` attribute.
+
+Also exports: `buttonGroupVariants`.
+
+Types: `ButtonGroupOrientation` (`'horizontal' | 'vertical'`).
+
+## Calendar
+
+`import { Calendar, RangeCalendar } from '@jovertical/mise-design-system'`
+
+A month grid to pick a day from. The one a `DatePicker` renders inside its popover, and the one most call sites want; `type="multiple"` picks several separate days, and `RangeCalendar` a contiguous span.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `captionLayout` | `'label' \| 'dropdown' \| 'dropdown-months' \| 'dropdown-years'` | `'label'` | `label` names the month; the dropdown layouts swap the month, the year or both for a native select, for a date far from today (a birth date, an expiry). |
+
+Also takes: bits-ui `Calendar.Root` props except `children`, `child`.
+
+### `RangeCalendar`
+
+A contiguous span of days, for reporting windows and stay lengths. The first click sets `start`; the second sets `end` and closes the span.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `captionLayout` | `'label' \| 'dropdown' \| 'dropdown-months' \| 'dropdown-years'` | `'label'` | `label` names the month; the dropdown layouts swap the month, the year or both for a native select, for a date far from today (a birth date, an expiry). |
+
+Also takes: bits-ui `RangeCalendar.Root` props except `children`, `child`.
+
+Types: `CalendarCaptionLayout` (`'label' | 'dropdown' | 'dropdown-months' | 'dropdown-years'`).
+
+## Checkbox
+
+`import { Checkbox } from '@jovertical/mise-design-system'`
+
+Also takes: bits-ui `Checkbox.Root` props except `children`, `child`.
+
+## ChoiceRow
+
+`import { ChoiceRow, ChoiceRowReadonly } from '@jovertical/mise-design-system'`
+
+A bordered row that is entirely clickable and highlights when its control is checked.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `for` (required) | `string` |  | Must match the control's own `id`, or the row will not forward its click. |
+| `control` (required) | `Snippet` |  | A `RadioGroupItem`, a `Checkbox`: anything bits-ui drives with `data-state`. |
+| `media` | `Snippet` |  | Sits between the control and the label: an avatar, a logo, a product thumbnail. For identifying *who or what* the row is about, where the control says whether it is chosen. Not an icon chip: a row of glyphs beside a row of radios reads as two controls. |
+| `label` (required) | `string` |  |  |
+| `description` | `string` |  |  |
+| `badge` | `string` |  | A short qualifier beside the label: "Coming soon", "Recommended". |
+| `disabled` | `boolean` | `false` |  |
+| `children` | `Snippet` |  | Revealed under the row, outside the label, inside the same border. |
+
+Also takes: every `<div>` attribute except `children`.
+
+### `ChoiceRowReadonly`
+
+A settled choice, in the shape of the choice it was.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` (required) | `string` |  |  |
+| `description` | `string` |  |  |
+| `selected` (required) | `boolean` |  |  |
+
+Also takes: every `<div>` attribute except `children`.
+
+## Combobox
+
+`import { Combobox, ComboboxChip, ComboboxChips, ComboboxChipsInput, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxInput, ComboboxItem, ComboboxLabel, ComboboxList, ComboboxSeparator, ComboboxTrigger } from '@jovertical/mise-design-system'`
+
+A searchable select: typing into the field narrows the list. Reach for it where the list is long enough that scanning it is slower than typing (a category picker over hundreds of rows), not a five-option status field, which stays a `Select`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | `'single'` | `'single'` |  |
+
+Also takes: bits-ui `Combobox.Root` props except `type`; bits-ui `Combobox.Root` props.
+
+### `ComboboxChip`
+
+One chosen value in `ComboboxChips`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `showRemove` | `boolean` | `true` |  |
+| `onRemove` | `() => void` |  | Called by the remove button; take the value out of the combobox's. |
+| `removeLabel` | `string` | `'Remove'` | Names the remove button: "Remove Valves". |
+| `disabled` | `boolean` | `false` |  |
+
+Also takes: every `<span>` attribute.
+
+### `ComboboxChips`
+
+The field for a multiple combobox: the chosen values as chips, then a `ComboboxChipsInput` to type into, wrapped as one Input-like box.
+
+Also takes: every `<div>` attribute.
+
+### `ComboboxChipsInput`
+
+The text a multiple combobox is typed into, inside `ComboboxChips`.
+
+Also takes: bits-ui `Combobox.Input` props.
+
+### `ComboboxContent`
+
+The floating panel. Put a `ComboboxList` inside, and a `ComboboxEmpty` for when nothing matches.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `portalProps` | `ComboboxPrimitive.PortalProps` |  |  |
+
+Also takes: bits-ui `Combobox.Content` props.
+
+### `ComboboxEmpty`
+
+Also takes: every `<div>` attribute.
+
+### `ComboboxGroup`
+
+Also takes: bits-ui `Combobox.Group` props.
+
+### `ComboboxInput`
+
+The field: an `InputGroup` with the typed text, the chevron that opens the list, and optionally a clear button that takes the chevron's place while there is a value. `children` render inside the group, after the addon.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `showTrigger` | `boolean` | `true` |  |
+| `showClear` | `boolean` | `false` |  |
+| `children` | `Snippet` |  |  |
+
+Also takes: bits-ui `Combobox.Input` props except `child` except `children`.
+
+### `ComboboxItem`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `Snippet` |  |  |
+
+Also takes: bits-ui `Combobox.Item` props except `child` except `children`.
+
+### `ComboboxLabel`
+
+Also takes: bits-ui `Combobox.GroupHeading` props.
+
+### `ComboboxList`
+
+Also takes: bits-ui `Combobox.Viewport` props.
+
+### `ComboboxSeparator`
+
+Also takes: bits-ui `Separator.Root` props.
+
+### `ComboboxTrigger`
+
+The chevron that opens the list without typing. ComboboxInput draws its own.
+
+Also takes: bits-ui `Combobox.Trigger` props.
+
+## DatePicker
+
+`import { DatePicker } from '@jovertical/mise-design-system'`
+
+A `Calendar` behind a trigger, for the case where the calendar itself would otherwise sit permanently on the page.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `mode` (required) | `'single' \| 'range'` |  |  |
+| `value` | `DateValue \| DateRange` |  |  |
+| `onValueChange` | `((value: DateValue \| undefined) => void) \| ((value: DateRange \| undefined) => void)` |  |  |
+| `placeholder` | `string` |  |  |
+| `disabled` | `boolean` | `false` | Disables the whole control: the trigger cannot be opened. |
+| `'aria-invalid'` | `boolean` |  | Marks the trigger invalid; `Button` draws the destructive border `Input` does. |
+| `isDateDisabled` | `(date: DateValue) => boolean` |  | Days the operator may not pick, inside an open calendar. Distinct from `disabled`, which closes the control. The rule is the caller's, not a `disablePast` flag: what counts as "past" is a decision the screen owns. |
+| `minValue` | `DateValue` |  |  |
+| `maxValue` | `DateValue` |  |  |
+| `locale` | `string` | `'en-US'` | For the trigger's label and the calendar. `en-US` when absent. |
+| `class` | `string` |  |  |
+
+## Field
+
+`import { Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle, fieldVariants } from '@jovertical/mise-design-system'`
+
+One control with its label, description and error. `horizontal` puts the label beside the control; `responsive` does so from the field group's `md` container width.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `orientation` | `'vertical' \| 'horizontal' \| 'responsive'` | `'vertical'` |  |
+
+Also takes: every `<div>` attribute.
+
+### `FieldContent`
+
+Also takes: every `<div>` attribute.
+
+### `FieldDescription`
+
+Also takes: every `<p>` attribute.
+
+### `FieldError`
+
+The field's error, announced as an alert. Children win; otherwise `errors` is de-duplicated by message, one shown as text and several as a list. Nothing renders when there is nothing to say.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `errors` | `Array<{ message?: string } \| undefined>` |  |  |
+
+Also takes: every `<div>` attribute.
+
+### `FieldGroup`
+
+Also takes: every `<div>` attribute.
+
+### `FieldLabel`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `required` | `boolean` | `false` | Marks the field as required: an `aria-hidden` asterisk beside a real sr-only "(required)", because a screen reader announcing "asterisk" tells you nothing. |
+
+Also takes: everything `Label` takes.
+
+### `FieldLegend`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'legend' \| 'label'` | `'legend'` |  |
+
+Also takes: every `<legend>` attribute.
+
+### `FieldSeparator`
+
+Also takes: every `<div>` attribute.
+
+### `FieldSet`
+
+Also takes: every `<fieldset>` attribute.
+
+### `FieldTitle`
+
+Also takes: every `<div>` attribute.
+
+Also exports: `fieldVariants`.
+
+Types: `FieldOrientation` (`'vertical' | 'horizontal' | 'responsive'`).
+
+## Form
+
+`import { Form, FormButton, FormDescription, FormElementField, FormField, FormFieldErrors, FormFieldset, FormLabel, FormLegend, FormControl } from '@jovertical/mise-design-system/form'`
+
+The `<form>` around a superforms form: `method="POST"` and superforms' `enhance`, so submitting validates on the client and posts to the page's action, or stays in the browser in SPA mode.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `form` (required) | `SuperForm<T>` |  |  |
+
+Also takes: every `<form>` attribute.
+
+### `FormButton`
+
+The form's submit button: a `Button` with `type="submit"`.
+
+Also takes: everything `Button` takes.
+
+### `FormDescription`
+
+The line under a field, which formsnap links to the control with `aria-describedby`.
+
+Also takes: bits-ui `Form.Description` props except `child`.
+
+### `FormElementField`
+
+One element of an array field (`tags[0]`), drawn as `FormField` is.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `form` (required) | `FsSuperForm<T>` |  |  |
+| `name` (required) | `U` |  |  |
+| `children` | `Snippet<[FormFieldState<T[U]>]>` |  |  |
+
+Also takes: every `<div>` attribute except `children`.
+
+### `FormField`
+
+One field of a superforms form: label, control, description and errors, wired to `name`, so the control is labelled, described and marked invalid from the form's validation. Reach for `Field` directly for a form with no superforms behind it; reach for this where one already is.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `form` (required) | `FsSuperForm<T>` |  |  |
+| `name` (required) | `U` |  |  |
+| `children` | `Snippet<[FormFieldState<T[U]>]>` |  |  |
+
+Also takes: every `<div>` attribute except `children`.
+
+### `FormFieldErrors`
+
+The field's validation errors, linked to the control, nothing while it is valid.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `errorClasses` | `string \| null` |  |  |
+
+Also takes: bits-ui `Form.FieldErrors` props except `child`.
+
+### `FormFieldset`
+
+A group of controls under one name, captioned by `FormLegend`.
+
+Also takes: bits-ui `Form.Fieldset` props except `child`.
+
+### `FormLabel`
+
+The field's label, pointed at its control and red while the field is invalid.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `required` | `boolean` | `false` | Adds the asterisk that marks a mandatory field. |
+
+Also takes: bits-ui `Form.Label` props except `child`.
+
+### `FormLegend`
+
+text-destructive:The caption of a `FormFieldset`, red while the group is invalid.
+
+Also takes: bits-ui `Form.Legend` props except `child`.
+
+Also exports: `FormControl`.
+
+Types: `FormFieldState`.
+
+## Input
+
+`import { Input } from '@jovertical/mise-design-system'`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` (required) | `'file' \| InputType` |  |  |
+| `files` | `FileList \| undefined` |  |  |
+
+Also takes: every `<input>` attribute except `type`.
+
+## InputGroup
+
+`import { InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, inputGroupAddonVariants, inputGroupButtonVariants } from '@jovertical/mise-design-system'`
+
+The surface matches `Input` exactly: filled, a transparent border, rounded-2xl. Stock shadcn draws a bordered white box at rounded-md, which put every grouped field out of step with the plain inputs beside it.
+
+Also takes: every `<div>` attribute.
+
+### `InputGroupAddon`
+
+A click on the addon focuses the group's input or textarea, unless it landed on a button.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `align` | `'inline-start' \| 'inline-end' \| 'block-start' \| 'block-end'` | `'inline-start'` |  |
+
+Also takes: every `<div>` attribute.
+
+### `InputGroupButton`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'` | `'xs'` |  |
+
+Also takes: everything `Button` takes except `size`.
+
+### `InputGroupInput`
+
+Also takes: everything `Input` takes.
+
+### `InputGroupText`
+
+A fixed unit or symbol rather than an interactive addon.
+
+Also takes: every `<span>` attribute.
+
+### `InputGroupTextarea`
+
+A bare `textarea`, not this package's `Textarea`. That one wraps itself in a `div` with a counter once `maxlength` is set, which breaks the group's `>textarea` selectors. A group that wants a count shows it in an addon.
+
+Also takes: every `<textarea>` attribute.
+
+Also exports: `inputGroupAddonVariants`, `inputGroupButtonVariants`.
+
+Types: `InputGroupAddonAlign` (`'inline-start' | 'inline-end' | 'block-start' | 'block-end'`), `InputGroupButtonSize` (`'xs' | 'sm' | 'icon-xs' | 'icon-sm'`).
+
+## InputOTP
+
+`import { InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot } from '@jovertical/mise-design-system'`
+
+A one-time code or a PIN, typed into one hidden input and drawn as cells. Lay out `InputOTPGroup`s and `InputOTPSlot`s in the children snippet, one slot per cell it receives.
+
+Also takes: bits-ui `InputOTP.Root` props.
+
+### `InputOTPGroup`
+
+The field: one rounded box around its slots, drawn as `Input` is (rounded-2xl, `bg-input/50`, the same focus ring around the whole of it), so a code sits in a form of inputs as one of them. Pass `aria-invalid` here, not on the slots: the field is what turns red.
+
+Also takes: every `<div>` attribute.
+
+### `InputOTPSeparator`
+
+Also takes: every `<div>` attribute.
+
+### `InputOTPSlot`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `masked` | `boolean` | `false` | A dot for each character typed, never the character: a PIN being set. |
+
+Also takes: bits-ui `InputOTP.Cell` props.
+
+## Label
+
+`import { Label } from '@jovertical/mise-design-system'`
+
+Also takes: bits-ui `Label.Root` props.
+
+## MediaDropzone
+
+`import { MediaDropzone } from '@jovertical/mise-design-system'`
+
+One image, on a zone that stays put: a logo, an avatar, a cover.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `MediaAsset \| null` | `null` |  |
+| `onValueChange` | `(value: MediaAsset \| null) => void` |  |  |
+| `adapter` (required) | `MediaUploaderAdapter` |  | The consumer's media service: the package makes no request of its own. |
+| `linkMode` | `'immediate' \| 'deferred'` | `'deferred'` |  |
+| `accept` | `string` | `DEFAULT_ACCEPT` | What a native `<input accept>` takes. Images when absent. |
+| `maxSize` | `number` | `DEFAULT_MAX_SIZE` | Bytes. 2MB when absent. |
+| `disabled` | `boolean` | `false` |  |
+| `class` | `string` |  |  |
+| `icon` | `Snippet` |  |  |
+| `placeholder` | `string` | `'Drag and drop your image here'` |  |
+| `hint` | `string` |  |  |
+| `recommendation` | `string` |  |  |
+| `actionLabel` | `string` | `'Choose file'` |  |
+| `previewLabel` | `string` |  | Heads the preview panel. Without it there is no panel. |
+| `previewCaption` | `string` |  |  |
+| `emptyLabel` | `string` | `'Nothing uploaded yet'` |  |
+| `onError` | `(error: Error) => void` |  | Failures the zone recovers from on its own: an unlink that did not take, an adapter that was not ready. A failed upload keeps its message and a Retry instead. |
+
+Types: `MediaAsset`, `MediaLinkMode` (`'immediate' | 'deferred'`), `MediaUploaderAdapter`, `MediaUploadOptions`.
+
+## NumberInput
+
+`import { NumberInput, NumberInputField } from '@jovertical/mise-design-system'`
+
+A number typed into a text field, never `type="number"`: the native one has 8px spinners drawn differently in every engine, a scroll wheel that changes a quantity under a passing pointer, "1e" accepted as a number in progress, and a selection API that throws.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `format` | `'integer' \| 'decimal' \| 'currency'` | `'decimal'` | `integer` takes whole numbers; `decimal` takes up to `precision` places; `currency` speaks minor units: `value` is an integer count of cents, shown with two places, and only two can be typed, because a third has no cent to land in. Everything crossing the boundary is then an integer, the units an API uses, and no price arrives as 19.99 and leaves as 1998.9999999999998. |
+| `min` | `number` | `0` | The floor, in `value`'s units. A negative one lets a minus sign be typed. |
+| `max` | `number` |  | No ceiling when absent. |
+| `step` | `number` | `1` | How far ↑, ↓ and the buttons move it, in `value`'s units. |
+| `precision` | `number` |  | The most decimal places `decimal` takes. No limit when absent. |
+| `clearable` | `boolean` | `true` | An emptied field commits `null`. Off, it commits `min`: for a count where zero is a real answer and the field should never be blank. |
+| `controls` | `boolean` | `false` | − and + either side, inside the field's own fill, so it reads as one control beside the plain inputs around it. Each disables at its end of the range. |
+| `prefix` | `string \| Snippet` |  | Ahead of the number: a currency symbol, a unit. |
+
+Also takes: everything `NumberInputField` takes.
+
+### `NumberInputField`
+
+The field alone: a number typed into a text field, inside an `InputGroup` the caller draws. `NumberInput` is this with its own group, buttons and prefix; reach for the field only when composing another control.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `format` | `'integer' \| 'decimal' \| 'currency'` | `'decimal'` |  |
+| `value` | `number \| null` | `null` |  |
+| `onValueChange` | `(value: number \| null) => void` |  |  |
+| `min` | `number` | `0` |  |
+| `max` | `number` |  |  |
+| `step` | `number` | `1` |  |
+| `precision` | `number` |  |  |
+| `clearable` | `boolean` | `true` |  |
+| `ref` | `HTMLInputElement \| null` | `null` |  |
+
+Also takes: every `<input>` attribute except `type`, `value`, `min`, `max`, `step`, `prefix`, `children`, `files`.
+
+Types: `NumberInputFormat` (`'integer' | 'decimal' | 'currency'`).
+
+## QuantityInput
+
+`import { QuantityInput } from '@jovertical/mise-design-system'`
+
+An amount and the unit it is measured in, as one control.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `units` (required) | `readonly QuantityUnit[]` |  | The units on offer. A prop rather than a constant: a measurement enum is domain, and a package that shipped one would ship an application's contract. |
+| `layout` | `'unit-first' \| 'quantity-first'` | `'unit-first'` |  |
+| `unit` | `string` | `''` |  |
+| `quantity` | `number \| null` | `null` |  |
+| `onUnitChange` | `(unit: string) => void` |  |  |
+| `onQuantityChange` | `(quantity: number \| null) => void` |  |  |
+| `onQuantityBlur` | `() => void` |  | When the amount loses focus, for a caller that writes on commit rather than on keystroke: "2" on the way to "25" is not an amount anybody meant. |
+| `groupHints` | `Readonly<Record<string, string>>` |  | A muted note beside a group's heading, keyed by the group's name: "needs density" beside volume units for an item weighed by the gram. The units stay pickable. |
+| `menuFooter` | `Snippet<[() => void]>` |  | Something below the units in the open menu: a fact and an action, such as "Density 0.92 g per ml · Edit". Handed `closeMenu`, because an action there usually opens something else, and the menu has to go first. |
+| `unitPlaceholder` | `string` | `'Unit'` |  |
+| `quantityPlaceholder` | `string` | `'1'` |  |
+| `quantityStep` | `number` | `0.01` | How far ↑ and ↓ move the amount. |
+| `quantityMin` | `number` | `0` |  |
+| `quantityPrecision` | `number` |  | The most decimal places the amount takes: `0` for a counted unit. No limit when absent. |
+| `size` | `'sm' \| 'md'` | `'md'` | Matches `Input`'s own scale. `sm` for a control inside a list row. |
+| `disabled` | `boolean` | `false` |  |
+
+Also takes: every `<div>` attribute except `children`.
+
+Types: `QuantityInputLayout` (`'unit-first' | 'quantity-first'`), `QuantityUnit`.
+
+## RadioGroup
+
+`import { RadioGroup, RadioGroupItem } from '@jovertical/mise-design-system'`
+
+Also takes: bits-ui `RadioGroup.Root` props.
+
+### `RadioGroupItem`
+
+Also takes: bits-ui `RadioGroup.Item` props except `children`, `child`.
+
+## Select
+
+`import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue } from '@jovertical/mise-design-system'`
+
+Pass `items` (`{ value, label }[]`) so the trigger can show the selected label while the list is closed. bits-ui learns an item's label only when the item renders, and the list renders only when open. Radix kept hidden items mounted for the same purpose.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | `'single'` | `'single'` |  |
+
+Also takes: bits-ui `Select.Root` props except `type`; bits-ui `Select.Root` props.
+
+### `SelectContent`
+
+A ring rather than a border, matching every other floating surface.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `portalProps` | `SelectPrimitive.PortalProps` |  |  |
+
+Also takes: bits-ui `Select.Content` props except `child`.
+
+### `SelectGroup`
+
+Also takes: bits-ui `Select.Group` props.
+
+### `SelectItem`
+
+`focus:bg-muted` rather than `--accent`, which is a nav tint and never a hover.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `Snippet` |  |  |
+
+Also takes: bits-ui `Select.Item` props except `child` except `children`.
+
+### `SelectLabel`
+
+Also takes: bits-ui `Select.GroupHeading` props.
+
+### `SelectScrollDownButton`
+
+Also takes: bits-ui `Select.ScrollDownButton` props except `children`, `child`.
+
+### `SelectScrollUpButton`
+
+Also takes: bits-ui `Select.ScrollUpButton` props except `children`, `child`.
+
+### `SelectSeparator`
+
+Also takes: every `<div>` attribute.
+
+### `SelectTrigger`
+
+`w-full` by default: a select sits in a form field beside inputs that are already full width, and `w-fit` made it the one control in the row not to be. Set `class="w-fit"` back for the rarer case. `size="sm"` for a dense row, such as a table cell or a toolbar.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | `'sm' \| 'md'` | `'md'` |  |
+
+Also takes: bits-ui `Select.Trigger` props except `child`.
+
+### `SelectValue`
+
+Also takes: bits-ui `Select.Value` props.
+
+## Switch
+
+`import { Switch } from '@jovertical/mise-design-system'`
+
+Bare: pair it with a Label, or a field, when it needs words beside it.
+
+Also takes: bits-ui `Switch.Root` props except `children`, `child`.
+
+## SwitchField
+
+`import { SwitchField } from '@jovertical/mise-design-system'`
+
+A bordered on/off row: what it does on the left, the switch on the right.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` (required) | `string` |  | The switch's id, which the label points at. |
+| `label` (required) | `string` |  |  |
+| `description` | `string` |  |  |
+| `checked` | `boolean` | `false` |  |
+| `onCheckedChange` | `(checked: boolean) => void` |  |  |
+| `disabled` | `boolean` | `false` |  |
+| `variant` | `'default' \| 'flush'` | `'default'` | `default` draws its own bordered surface, for a switch that stands alone in a form. |
+| `children` | `Snippet` |  | Revealed below the row while the switch is on. |
+
+Also takes: every `<div>` attribute except `children`.
+
+Types: `SwitchFieldVariant` (`'default' | 'flush'`).
+
+## Textarea
+
+`import { Textarea } from '@jovertical/mise-design-system'`
+
+A counter appears only when `maxlength` is set: a bare number counts up towards nothing. `maxlength` stops typing at the ceiling, so falling under `minlength` is the only reachable invalid state, and only once something has been typed. An untouched optional field is not wrong.
+
+Also takes: every `<textarea>` attribute.
+
+## TimePicker
+
+`import { TimePicker } from '@jovertical/mise-design-system'`
+
+Three selects standing in for a clock: hour, minute, and AM/PM.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Time` |  |  |
+| `onValueChange` | `(value: Time) => void` |  |  |
+| `disabled` | `boolean` | `false` |  |
+
+Also takes: every `<div>` attribute except `children`.
+
+## Toggle
+
+`import { Toggle, toggleVariants } from '@jovertical/mise-design-system'`
+
+One on/off control, not a group: reach for `ToggleGroup` the moment a second option joins it. `variant="segmented"` only makes sense inside that group's track; a lone `Toggle` wants `default`, `outline` or `solid`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'default' \| 'outline' \| 'segmented' \| 'solid'` |  |  |
+| `size` | `'default' \| 'sm' \| 'lg'` |  |  |
+| `iconOnly` | `boolean` |  | One glyph and no label: a circle the size of the toggle's height. Needs an `aria-label`. |
+
+Also takes: bits-ui `Toggle.Root` props.
+
+Also exports: `toggleVariants`.
+
+Types: `ToggleSize` (`'default' | 'sm' | 'lg'`), `ToggleVariant` (`'default' | 'outline' | 'segmented' | 'solid'`).
+
+## ToggleGroup
+
+`import { ToggleGroup, ToggleGroupItem } from '@jovertical/mise-design-system'`
+
+A segmented group is a track, not a row of joined buttons: no gap between options, no shared border to collapse, and the wash is the point. `size` sizes the track, because a segmented item measures itself against it.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'default' \| 'outline' \| 'segmented' \| 'solid'` |  |  |
+| `size` | `'default' \| 'sm' \| 'lg'` |  |  |
+| `spacing` | `number` | `0` |  |
+
+Also takes: bits-ui `ToggleGroup.Root` props.
+
+### `ToggleGroupItem`
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'default' \| 'outline' \| 'segmented' \| 'solid'` |  |  |
+| `size` | `'default' \| 'sm' \| 'lg'` |  |  |
+
+Also takes: bits-ui `ToggleGroup.Item` props.