@windforge/ui 0.1.0

package/src/components/data-table.tsx

@@ -0,0 +1,194 @@
+import * as React from 'react'
+import { ChevronUp, ChevronDown, ChevronsUpDown } from 'lucide-react'
+import { cn } from '../lib/utils'
+import {
+  Table, TableHeader, TableBody, TableRow, TableHead, TableCell,
+} from './table'
+import { Checkbox } from './checkbox'
+import { Pagination } from './pagination'
+
+/**
+ * DataTable — the batteries-included table: column sorting, row selection, and
+ * optional client-side pagination, built on the Table primitives so it stays
+ * on-system. Pass `columns` + `data` + a `rowKey`; opt into `selectable` and
+ * `pageSize`. For a purely presentational table, use Table directly.
+ *
+ *   <DataTable rowKey={(r) => r.id} selectable pageSize={10}
+ *     columns={[
+ *       { header: 'Name', accessor: 'name', sortable: true },
+ *       { header: 'Amount', accessor: 'amount', align: 'right', sortable: true },
+ *     ]}
+ *     data={rows}
+ *   />
+ */
+type Align = 'left' | 'center' | 'right'
+
+export interface DataTableColumn<Row> {
+  header: React.ReactNode
+  /** A row key, or a render function returning the cell content. */
+  accessor: keyof Row | ((row: Row) => React.ReactNode)
+  align?: Align
+  sortable?: boolean
+  /** Sort value when `accessor` is a render function (or to sort by something else). */
+  sortAccessor?: (row: Row) => string | number
+}
+
+export interface DataTableProps<Row> {
+  columns: DataTableColumn<Row>[]
+  data: readonly Row[]
+  /** Stable id per row — required for selection and React keys. */
+  rowKey: (row: Row) => string
+  caption?: React.ReactNode
+  selectable?: boolean
+  /** Controlled selection (ids). Omit for uncontrolled. */
+  selected?: string[]
+  onSelectedChange?: (ids: string[]) => void
+  /** Enable client-side pagination at this page size. */
+  pageSize?: number
+  /** Empty-state content when there are no rows. */
+  emptyState?: React.ReactNode
+}
+
+type SortState = { index: number; dir: 'asc' | 'desc' } | null
+
+function sortValue<Row>(col: DataTableColumn<Row>, row: Row): string | number {
+  if (col.sortAccessor) return col.sortAccessor(row)
+  if (typeof col.accessor !== 'function') {
+    const v = row[col.accessor]
+    return typeof v === 'number' ? v : String(v ?? '')
+  }
+  return ''
+}
+
+export function DataTable<Row>({
+  columns, data, rowKey, caption, selectable, selected, onSelectedChange, pageSize, emptyState,
+}: DataTableProps<Row>) {
+  const [sort, setSort] = React.useState<SortState>(null)
+  const [page, setPage] = React.useState(1)
+  const [internalSel, setInternalSel] = React.useState<string[]>([])
+  const sel = selected ?? internalSel
+  const setSel = (ids: string[]) => {
+    onSelectedChange?.(ids)
+    if (selected === undefined) setInternalSel(ids)
+  }
+
+  const sorted = React.useMemo(() => {
+    if (!sort) return [...data]
+    const col = columns[sort.index]
+    const dir = sort.dir === 'asc' ? 1 : -1
+    return [...data].sort((a, b) => {
+      const av = sortValue(col, a)
+      const bv = sortValue(col, b)
+      if (av < bv) return -1 * dir
+      if (av > bv) return 1 * dir
+      return 0
+    })
+  }, [data, sort, columns])
+
+  const pageCount = pageSize ? Math.max(1, Math.ceil(sorted.length / pageSize)) : 1
+  const current = Math.min(page, pageCount)
+  const rows = pageSize ? sorted.slice((current - 1) * pageSize, current * pageSize) : sorted
+
+  const pageIds = rows.map(rowKey)
+  const allOnPageSelected = pageIds.length > 0 && pageIds.every((id) => sel.includes(id))
+  const toggleAll = () =>
+    setSel(allOnPageSelected ? sel.filter((id) => !pageIds.includes(id)) : [...new Set([...sel, ...pageIds])])
+  const toggleRow = (id: string) =>
+    setSel(sel.includes(id) ? sel.filter((x) => x !== id) : [...sel, id])
+
+  const toggleSort = (index: number) =>
+    setSort((s) =>
+      s?.index !== index ? { index, dir: 'asc' } : s.dir === 'asc' ? { index, dir: 'desc' } : null,
+    )
+
+  const colCount = columns.length + (selectable ? 1 : 0)
+
+  return (
+    <div className="flex flex-col gap-3">
+      <Table caption={caption}>
+        <TableHeader>
+          <TableRow>
+            {selectable && (
+              <TableHead align="center">
+                <Checkbox
+                  checked={allOnPageSelected}
+                  onCheckedChange={toggleAll}
+                  aria-label="Select all rows on this page"
+                />
+              </TableHead>
+            )}
+            {columns.map((col, i) => {
+              const active = sort?.index === i
+              const SortIcon = !active ? ChevronsUpDown : sort!.dir === 'asc' ? ChevronUp : ChevronDown
+              return (
+                <TableHead key={i} align={col.align}>
+                  {col.sortable ? (
+                    <button
+                      type="button"
+                      onClick={() => toggleSort(i)}
+                      aria-label={`Sort by ${typeof col.header === 'string' ? col.header : 'column'}`}
+                      className={cn(
+                        'inline-flex items-center gap-1 rounded-sm transition-colors hover:text-primary',
+                        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                        active ? 'text-primary' : 'text-tertiary',
+                      )}
+                    >
+                      {col.header}
+                      <SortIcon className="size-3.5 shrink-0" aria-hidden="true" />
+                    </button>
+                  ) : (
+                    col.header
+                  )}
+                </TableHead>
+              )
+            })}
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {rows.length === 0 ? (
+            <TableRow>
+              <TableCell align="center" colSpan={colCount}>
+                <div className="py-6 text-sm text-secondary">{emptyState ?? 'No results.'}</div>
+              </TableCell>
+            </TableRow>
+          ) : (
+            rows.map((row) => {
+              const id = rowKey(row)
+              const isSelected = sel.includes(id)
+              return (
+                <TableRow key={id} data-state={isSelected ? 'selected' : undefined}>
+                  {selectable && (
+                    <TableCell align="center">
+                      <Checkbox
+                        checked={isSelected}
+                        onCheckedChange={() => toggleRow(id)}
+                        aria-label="Select row"
+                      />
+                    </TableCell>
+                  )}
+                  {columns.map((col, c) => (
+                    <TableCell key={c} align={col.align}>
+                      {typeof col.accessor === 'function'
+                        ? col.accessor(row)
+                        : (row[col.accessor] as React.ReactNode)}
+                    </TableCell>
+                  ))}
+                </TableRow>
+              )
+            })
+          )}
+        </TableBody>
+      </Table>
+
+      {pageSize && pageCount > 1 && (
+        <div className="flex items-center justify-between">
+          <span className="text-sm text-secondary">
+            {selectable && sel.length > 0 ? `${sel.length} selected · ` : ''}
+            {sorted.length} {sorted.length === 1 ? 'row' : 'rows'}
+          </span>
+          <Pagination page={current} count={pageCount} onPageChange={setPage} />
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/date-picker.tsx

@@ -0,0 +1,77 @@
+import * as React from 'react'
+import * as PopoverPrimitive from '@radix-ui/react-popover'
+import { Calendar as CalendarIcon } from 'lucide-react'
+import { Popover, PopoverTrigger } from './popover'
+import { Calendar } from './calendar'
+import { cn } from '../lib/utils'
+import { focusRingField, floatingPanel } from '../lib/recipes'
+
+/**
+ * DatePicker — a single-date field: a token-styled trigger that opens the Calendar
+ * in a Popover. Controlled via `value`/`onValueChange`. For ranges or multi-select,
+ * use the Calendar directly inside a Popover.
+ *
+ *   <DatePicker value={date} onValueChange={setDate} />
+ */
+export interface DatePickerProps {
+  value?: Date
+  onValueChange?: (date?: Date) => void
+  placeholder?: string
+  disabled?: boolean
+  invalid?: boolean
+  id?: string
+  'aria-describedby'?: string
+  /** Intl format for the displayed value. Default { dateStyle: 'medium' }. */
+  formatOptions?: Intl.DateTimeFormatOptions
+}
+
+export function DatePicker({
+  value, onValueChange, placeholder = 'Pick a date', disabled, invalid, id,
+  'aria-describedby': ariaDescribedBy, formatOptions = { dateStyle: 'medium' },
+}: DatePickerProps) {
+  const [open, setOpen] = React.useState(false)
+  const label = value ? new Intl.DateTimeFormat(undefined, formatOptions).format(value) : null
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          id={id}
+          disabled={disabled}
+          aria-invalid={invalid || undefined}
+          aria-describedby={ariaDescribedBy}
+          className={cn(
+            'flex h-10 w-full items-center gap-2 rounded-lg border border-strong bg-surface px-3 text-left text-sm',
+            'transition-colors hover:bg-surface-subtle',
+            focusRingField,
+            'disabled:cursor-not-allowed disabled:opacity-50',
+            invalid && 'border-error focus-visible:border-error',
+          )}
+        >
+          <CalendarIcon className="size-4 shrink-0 text-tertiary" />
+          <span className={cn('flex-1', label ? 'text-primary' : 'text-tertiary')}>
+            {label ?? placeholder}
+          </span>
+        </button>
+      </PopoverTrigger>
+      <PopoverPrimitive.Portal>
+        <PopoverPrimitive.Content
+          align="start"
+          sideOffset={6}
+          className={cn(floatingPanel, 'w-auto rounded-xl shadow-lg animate-scale-in')}
+        >
+          <Calendar
+            mode="single"
+            selected={value}
+            onSelect={(date) => {
+              onValueChange?.(date)
+              setOpen(false)
+            }}
+            autoFocus
+          />
+        </PopoverPrimitive.Content>
+      </PopoverPrimitive.Portal>
+    </Popover>
+  )
+}

package/src/components/dialog.tsx

@@ -0,0 +1,57 @@
+import * as React from 'react'
+import * as DialogPrimitive from '@radix-ui/react-dialog'
+import { Modal, ModalTrigger, ModalContent, type ModalContentProps } from './modal'
+import { cn } from '../lib/utils'
+
+/**
+ * Dialog — the opinionated, props-based convenience built on `Modal`. Pass
+ * `title`, `description`, and `actions` (buttons) as nodes; body goes in
+ * `children`. There are no header/title/footer sub-components to assemble — for
+ * full control over structure, drop down to the `Modal` primitives directly.
+ *
+ *   <Dialog
+ *     trigger={<Button>Delete</Button>}
+ *     title="Delete project?"
+ *     description="This can't be undone."
+ *     actions={<><Button variant="secondary">Cancel</Button><Button variant="destructive">Delete</Button></>}
+ *   />
+ */
+export interface DialogProps {
+  title: React.ReactNode
+  description?: React.ReactNode
+  /** Footer content — typically buttons. */
+  actions?: React.ReactNode
+  /** The element that opens the dialog. Omit for fully controlled use. */
+  trigger?: React.ReactNode
+  children?: React.ReactNode
+  size?: ModalContentProps['size']
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+}
+
+export function Dialog({
+  title, description, actions, trigger, children, size, open, defaultOpen, onOpenChange,
+}: DialogProps) {
+  return (
+    <Modal open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
+      {trigger && <ModalTrigger asChild>{trigger}</ModalTrigger>}
+      <ModalContent size={size}>
+        <div className={cn('flex flex-col gap-1.5 text-left')}>
+          <DialogPrimitive.Title className={cn('text-lg font-semibold leading-snug tracking-tight')}>
+            {title}
+          </DialogPrimitive.Title>
+          {description && (
+            <DialogPrimitive.Description className={cn('text-sm text-primary')}>
+              {description}
+            </DialogPrimitive.Description>
+          )}
+        </div>
+        {children}
+        {actions && (
+          <div className={cn('flex flex-col-reverse gap-2 sm:flex-row sm:justify-end')}>{actions}</div>
+        )}
+      </ModalContent>
+    </Modal>
+  )
+}

package/src/components/dropdown-menu.tsx

@@ -0,0 +1,186 @@
+import * as React from 'react'
+import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu'
+import { Check, ChevronRight, Circle } from 'lucide-react'
+import { cn } from '../lib/utils'
+import type { NoStyle } from '../lib/types'
+import { floatingPanel, menuItem } from '../lib/recipes'
+
+export const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger
+export const DropdownMenuGroup = DropdownMenuPrimitive.Group
+export const DropdownMenuPortal = DropdownMenuPrimitive.Portal
+export const DropdownMenuSub = DropdownMenuPrimitive.Sub
+export const DropdownMenuRadioGroup = DropdownMenuPrimitive.RadioGroup
+
+export const DropdownMenuContent = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Content>,
+  NoStyle<React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>>
+>(({ sideOffset = 6, ...props }, ref) => (
+  <DropdownMenuPrimitive.Portal>
+    <DropdownMenuPrimitive.Content
+      ref={ref}
+      sideOffset={sideOffset}
+      className={cn(floatingPanel, 'min-w-48 overflow-hidden p-1 animate-scale-in')}
+      {...props}
+    />
+  </DropdownMenuPrimitive.Portal>
+))
+DropdownMenuContent.displayName = DropdownMenuPrimitive.Content.displayName
+
+export const DropdownMenuItem = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Item>,
+  NoStyle<React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Item>> & { inset?: boolean }
+>(({ inset, ...props }, ref) => (
+  <DropdownMenuPrimitive.Item
+    ref={ref}
+    className={cn(
+      menuItem,
+      'gap-2 px-2 py-1.5 focus:bg-surface-inset focus:text-primary [&_svg]:size-4',
+      inset && 'pl-8',
+    )}
+    {...props}
+  />
+))
+DropdownMenuItem.displayName = DropdownMenuPrimitive.Item.displayName
+
+export const DropdownMenuCheckboxItem = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.CheckboxItem>,
+  NoStyle<React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.CheckboxItem>>
+>(({ children, checked, ...props }, ref) => (
+  <DropdownMenuPrimitive.CheckboxItem
+    ref={ref}
+    checked={checked}
+    className={cn(menuItem, 'py-1.5 pl-8 pr-2 focus:bg-surface-inset focus:text-primary')}
+    {...props}
+  >
+    <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+      <DropdownMenuPrimitive.ItemIndicator>
+        <Check className="h-4 w-4" />
+      </DropdownMenuPrimitive.ItemIndicator>
+    </span>
+    {children}
+  </DropdownMenuPrimitive.CheckboxItem>
+))
+DropdownMenuCheckboxItem.displayName = DropdownMenuPrimitive.CheckboxItem.displayName
+
+export const DropdownMenuRadioItem = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.RadioItem>,
+  NoStyle<React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.RadioItem>>
+>(({ children, ...props }, ref) => (
+  <DropdownMenuPrimitive.RadioItem
+    ref={ref}
+    className={cn(menuItem, 'py-1.5 pl-8 pr-2 focus:bg-surface-inset focus:text-primary')}
+    {...props}
+  >
+    <span className="absolute left-2 flex h-3.5 w-3.5 items-center justify-center">
+      <DropdownMenuPrimitive.ItemIndicator>
+        <Circle className="h-2 w-2 fill-current" />
+      </DropdownMenuPrimitive.ItemIndicator>
+    </span>
+    {children}
+  </DropdownMenuPrimitive.RadioItem>
+))
+DropdownMenuRadioItem.displayName = DropdownMenuPrimitive.RadioItem.displayName
+
+export const DropdownMenuLabel = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Label>,
+  NoStyle<React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Label>> & { inset?: boolean }
+>(({ inset, ...props }, ref) => (
+  <DropdownMenuPrimitive.Label
+    ref={ref}
+    className={cn('px-2 py-1.5 text-sm font-semibold text-tertiary', inset && 'pl-8')}
+    {...props}
+  />
+))
+DropdownMenuLabel.displayName = DropdownMenuPrimitive.Label.displayName
+
+export const DropdownMenuSeparator = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Separator>,
+  NoStyle<React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Separator>>
+>(({ ...props }, ref) => (
+  <DropdownMenuPrimitive.Separator ref={ref} className={cn('-mx-1 my-1 h-px bg-border')} {...props} />
+))
+DropdownMenuSeparator.displayName = DropdownMenuPrimitive.Separator.displayName
+
+export function DropdownMenuShortcut({ ...props }: NoStyle<React.HTMLAttributes<HTMLSpanElement>>) {
+  return <span className={cn('ml-auto text-sm tracking-widest text-tertiary')} {...props} />
+}
+
+export const DropdownMenuSubTrigger = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.SubTrigger>,
+  NoStyle<React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.SubTrigger>> & { inset?: boolean }
+>(({ inset, children, ...props }, ref) => (
+  <DropdownMenuPrimitive.SubTrigger
+    ref={ref}
+    className={cn(menuItem, 'px-2 py-1.5 focus:bg-surface-inset focus:text-primary', inset && 'pl-8')}
+    {...props}
+  >
+    {children}
+    <ChevronRight className="ml-auto h-4 w-4" />
+  </DropdownMenuPrimitive.SubTrigger>
+))
+DropdownMenuSubTrigger.displayName = DropdownMenuPrimitive.SubTrigger.displayName
+
+export const DropdownMenuSubContent = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.SubContent>,
+  NoStyle<React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.SubContent>>
+>(({ ...props }, ref) => (
+  <DropdownMenuPrimitive.SubContent
+    ref={ref}
+    className={cn(floatingPanel, 'min-w-32 overflow-hidden p-1 animate-scale-in')}
+    {...props}
+  />
+))
+DropdownMenuSubContent.displayName = DropdownMenuPrimitive.SubContent.displayName
+
+/**
+ * DropdownMenu — pass a `trigger` and an `items` array for the common case (the
+ * component renders the content, items, labels, and separators), or compose the
+ * primitives (`DropdownMenuTrigger`/`DropdownMenuContent`/…) by hand for
+ * submenus, checkbox/radio groups, and other advanced layouts.
+ *
+ *   <DropdownMenu trigger={<Button>Open</Button>} items={[
+ *     { label: 'Profile', icon: <User />, shortcut: '⇧⌘P', onSelect: goProfile },
+ *     { type: 'separator' },
+ *     { label: 'Log out', onSelect: logout },
+ *   ]} />
+ */
+export type DropdownMenuItemData =
+  | {
+      type?: 'item'
+      label: React.ReactNode
+      icon?: React.ReactNode
+      shortcut?: string
+      onSelect?: () => void
+      disabled?: boolean
+    }
+  | { type: 'separator' }
+  | { type: 'label'; label: React.ReactNode }
+
+export interface DropdownMenuProps extends React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Root> {
+  /** The element that opens the menu (rendered via asChild). */
+  trigger?: React.ReactNode
+  /** Declarative items. Omit to compose the primitives as children instead. */
+  items?: DropdownMenuItemData[]
+}
+
+export function DropdownMenu({ trigger, items, children, ...props }: DropdownMenuProps) {
+  if (!items) return <DropdownMenuPrimitive.Root {...props}>{children}</DropdownMenuPrimitive.Root>
+  return (
+    <DropdownMenuPrimitive.Root {...props}>
+      {trigger && <DropdownMenuTrigger asChild>{trigger}</DropdownMenuTrigger>}
+      <DropdownMenuContent>
+        {items.map((item, i) => {
+          if (item.type === 'separator') return <DropdownMenuSeparator key={i} />
+          if (item.type === 'label') return <DropdownMenuLabel key={i}>{item.label}</DropdownMenuLabel>
+          return (
+            <DropdownMenuItem key={i} onSelect={item.onSelect} disabled={item.disabled}>
+              {item.icon}
+              {item.label}
+              {item.shortcut && <DropdownMenuShortcut>{item.shortcut}</DropdownMenuShortcut>}
+            </DropdownMenuItem>
+          )
+        })}
+      </DropdownMenuContent>
+    </DropdownMenuPrimitive.Root>
+  )
+}

package/src/components/form-field.tsx

@@ -0,0 +1,97 @@
+import * as React from 'react'
+import { CircleAlert } from 'lucide-react'
+import { Label } from './label'
+import { Text } from './text'
+import { Input } from './input'
+import { cn } from '../lib/utils'
+import type { NoStyle } from '../lib/types'
+
+/**
+ * FormField — the on-system way to assemble a labelled control. For the common
+ * case it renders the field for you: pass `label`, `description`, `placeholder`,
+ * and `type` and it owns an `Input`. To wrap a different control (Textarea,
+ * Select, Autocomplete) pass it as the single child instead. Either way FormField
+ * generates the ids and wires `htmlFor`, `aria-describedby`, `aria-invalid`, and
+ * the error/required state — so accessible, validated forms stay a one-liner and
+ * never drift.
+ *
+ *   <FormField label="Email" description="We'll only use this to sign you in."
+ *              type="email" placeholder="you@example.com" error={errors.email} required />
+ *
+ *   <FormField label="Notes" description="Optional.">
+ *     <Textarea rows={3} />
+ *   </FormField>
+ *
+ * Per the system's hue policy, the error MESSAGE text stays the normal foreground;
+ * only the leading icon (and the control's outline) carry the status hue — matching
+ * Alert and Toast. The state is never conveyed by color alone (icon + border + text).
+ */
+export interface FormFieldProps extends NoStyle<Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>> {
+  label?: React.ReactNode
+  /** Helper text below the label. Kept as normal foreground — meant to be read. */
+  description?: React.ReactNode
+  /** Placeholder forwarded onto the control. A prop set directly on a child wins. */
+  placeholder?: string
+  /** Input type for the default control (text, email, password, …). Forwarded onto the control. */
+  type?: React.HTMLInputTypeAttribute
+  /** Error message. Its presence puts the control into the invalid state. */
+  error?: React.ReactNode
+  required?: boolean
+  /** Escape hatch: a non-Input control to wrap. Omit to let FormField render an Input. */
+  children?: React.ReactElement
+}
+
+type FieldChildProps = {
+  id?: string
+  invalid?: boolean
+  placeholder?: string
+  type?: string
+  'aria-describedby'?: string
+}
+
+export const FormField = React.forwardRef<HTMLDivElement, FormFieldProps>(
+  ({ label, description, placeholder, type, error, required, children, ...props }, ref) => {
+    const uid = React.useId()
+    const field = children ?? <Input />
+    const childProps = field.props as FieldChildProps
+    const fieldId = childProps.id ?? `${uid}-field`
+    const descId = description ? `${uid}-desc` : undefined
+    const errId = error ? `${uid}-err` : undefined
+    const describedBy =
+      [childProps['aria-describedby'], descId, errId].filter(Boolean).join(' ') || undefined
+    const invalid = error != null || childProps.invalid
+
+    const control = React.cloneElement(field, {
+      id: fieldId,
+      invalid: invalid || undefined,
+      placeholder: childProps.placeholder ?? placeholder,
+      type: childProps.type ?? type,
+      'aria-describedby': describedBy,
+      'aria-required': required || undefined,
+    } as Partial<FieldChildProps> & Record<string, unknown>)
+
+    return (
+      <div ref={ref} className={cn('flex flex-col gap-1.5')} {...props}>
+        {label != null && (
+          <Label htmlFor={fieldId}>
+            {label}
+            {required && <span aria-hidden="true" className="text-error"> *</span>}
+          </Label>
+        )}
+        {control}
+        {description != null && error == null && (
+          <Text span size="sm" id={descId}>
+            {description}
+          </Text>
+        )}
+        {error != null && (
+          <div id={errId} className="flex items-start gap-1.5 text-sm text-primary">
+            <CircleAlert className="mt-0.5 size-3.5 shrink-0 text-error" aria-hidden="true" />
+            <span>{error}</span>
+          </div>
+        )}
+      </div>
+    )
+  },
+)
+FormField.displayName = 'FormField'

package/src/components/input.tsx

@@ -0,0 +1,29 @@
+import * as React from 'react'
+import { cn } from '../lib/utils'
+import type { NoStyle } from '../lib/types'
+import { focusRingField } from '../lib/recipes'
+
+export interface InputProps extends NoStyle<React.InputHTMLAttributes<HTMLInputElement>> {
+  /** Error state — red control outline + aria-invalid. Usually set for you by FormField. */
+  invalid?: boolean
+}
+
+export const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  ({ type, invalid, ...props }, ref) => (
+    <input
+      type={type}
+      ref={ref}
+      aria-invalid={invalid || undefined}
+      className={cn(
+        'flex h-10 w-full rounded-lg border border-strong bg-surface px-3 py-2 text-sm text-primary',
+        'transition-colors placeholder:text-tertiary',
+        focusRingField,
+        'disabled:cursor-not-allowed disabled:opacity-50',
+        'file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-primary',
+        invalid && 'border-error focus-visible:border-error',
+      )}
+      {...props}
+    />
+  ),
+)
+Input.displayName = 'Input'

package/src/components/label.tsx

@@ -0,0 +1,18 @@
+import * as React from 'react'
+import * as LabelPrimitive from '@radix-ui/react-label'
+import { cn } from '../lib/utils'
+import type { NoStyle } from '../lib/types'
+
+export const Label = React.forwardRef<
+  React.ElementRef<typeof LabelPrimitive.Root>,
+  NoStyle<React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root>>
+>(({ ...props }, ref) => (
+  <LabelPrimitive.Root
+    ref={ref}
+    className={cn(
+      'text-sm font-medium leading-none text-primary peer-disabled:cursor-not-allowed peer-disabled:opacity-70',
+    )}
+    {...props}
+  />
+))
+Label.displayName = LabelPrimitive.Root.displayName