alinea 2.0.0-preview.13 → 2.0.0-preview.14

package/docs/components/combo-box.md

@@ -18,40 +18,129 @@ export function ComboBoxExample() {
 }
 ```
 
+## Groups and descriptions
+
+Group items under a label with ComboBoxGroup. Like SelectItem, a ComboBoxItem can show an `icon` and a `description` below its label. Values are strings or numbers: `onValueChange` receives the `value` of the picked item, typed like the `value` you pass.
+
+Example: ComboBox: groups
+```tsx
+import {ComboBox, ComboBoxGroup, ComboBoxItem} from 'alinea/components'
+import {
+  IcRoundDescription,
+  IcRoundFeed,
+  IcRoundImage
+} from 'alinea/dashboard/icons'
+
+export function ComboBoxGroupsExample() {
+  return (
+    <ComboBox label="Link to" style={{width: 280}}>
+      <ComboBoxGroup label="Pages">
+        <ComboBoxItem value="about" icon={IcRoundDescription}>
+          About us
+        </ComboBoxItem>
+        <ComboBoxItem
+          value="collection"
+          icon={IcRoundImage}
+          description="Products of the summer collection"
+        >
+          Summer collection
+        </ComboBoxItem>
+      </ComboBoxGroup>
+      <ComboBoxGroup label="Blog">
+        <ComboBoxItem
+          value="care"
+          icon={IcRoundFeed}
+          description="Published last week"
+        >
+          Caring for linen
+        </ComboBoxItem>
+      </ComboBoxGroup>
+    </ComboBox>
+  )
+}
+```
+
+## Load items as you type
+
+To search on a server, pass `filter={false}` so every item you render is shown, and `loading` while a request runs: it shows a spinner in the input, and in the list while it is empty. `useAsyncList` loads the items for the text in the input and cancels a request when a newer one replaces it. A function as `filter` replaces the default matching instead: `(textValue, inputValue) => boolean`.
+
+Example: ComboBox: async
+```tsx
+import {ComboBox, ComboBoxItem, useAsyncList} from 'alinea/components'
+
+const products = [
+  {id: 'shirt', title: 'Linen shirt'},
+  {id: 'chair', title: 'Oak dining chair'},
+  {id: 'throw', title: 'Wool throw'},
+  {id: 'table', title: 'Walnut side table'},
+  {id: 'lamp', title: 'Ceramic table lamp'}
+]
+
+// Stands in for a search request to your own API
+async function searchProducts(text: string) {
+  await new Promise(resolve => setTimeout(resolve, 400))
+  const query = text.toLowerCase()
+  return products.filter(product => product.title.toLowerCase().includes(query))
+}
+
+export function ComboBoxAsyncExample() {
+  const list = useAsyncList({
+    async load({filterText}) {
+      return {items: await searchProducts(filterText)}
+    }
+  })
+  return (
+    <ComboBox
+      label="Related product"
+      inputValue={list.filterText}
+      onInputValueChange={list.setFilterText}
+      filter={false}
+      loading={list.loading}
+      emptyMessage="No products found"
+      style={{width: 280}}
+    >
+      {list.items.map(product => (
+        <ComboBoxItem key={product.id} value={product.id}>
+          {product.title}
+        </ComboBoxItem>
+      ))}
+    </ComboBox>
+  )
+}
+```
+
 ## Props
 
 `ComboBox`
 A labelled text input that filters a list of options to pick from
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| value | `string \| null` |  |  |
-| defaultValue | `string \| null` |  |  |
-| onValueChange | `(value: string \| null) => void` |  | Called with the selected value, or null when the selection is cleared |
+| value | `V \| null` |  | The value of the selected ComboBoxItem |
+| defaultValue | `V \| null` |  |  |
+| onValueChange | `(value: V \| null) => void` |  | Called with the selected value, or null when the selection is cleared |
 | inputValue | `string` |  |  |
 | defaultInputValue | `string` |  |  |
 | onInputValueChange | `(value: string) => void` |  |  |
 | placeholder | `string` |  |  |
 | allowsCustomValue | `boolean` |  | Keep text that does not match an item instead of reverting it on blur |
 | emptyMessage | `ReactNode` |  | Shown in the list when no item matches, the list stays closed if unset |
+| filter | `false \| ((textValue: string, inputValue: string) => boolean)` |  | Whether an item is shown for the typed text, defaults to a case and accent insensitive match anywhere in its text. Pass false to show every item, eg. when the server already filtered them. |
+| loading | `boolean` |  | Shows a spinner, eg. while the items for the typed text load |
 | name | `string` |  | Name of the hidden form input carrying the value |
 | autoFocus | `boolean` |  |  |
-| label | `ReactNode` |  |  |
-| description | `ReactNode` |  |  |
-| error | `ReactNode` |  |  |
-| required | `boolean` |  |  |
-| disabled | `boolean` |  |  |
-| readOnly | `boolean` |  |  |
-| icon | `IconType \| ReactElement` |  |  |
-| shared | `boolean` |  | Marks the field as shared between translations |
-| open | `boolean` |  |  |
-| defaultOpen | `boolean` |  |  |
-| onOpenChange | `(open: boolean) => void` |  |  |
-Also accepts `className` and `style`, `id` and `aria-*` labelling attributes, `data-*` attributes.
 
 `ComboBoxItem`
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| value (required) | `string` |  |  |
+| value (required) | `Key` |  |  |
 | textValue | `string` |  | Text used for filtering and the input, defaults to string children |
 | disabled | `boolean` |  |  |
+| icon | `IconType \| ReactElement` |  | Icon shown before the label in the list |
+| description | `ReactNode` |  | Secondary text shown below the label in the list |
 Also accepts `className` and `style`.
+
+`ComboBoxGroup`
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| label | `ReactNode` |  |  |
+Also accepts `id` and `aria-*` labelling attributes.

package/docs/components/date-field.md

@@ -22,7 +22,7 @@ export function DateFieldExample() {
 `DateField`
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| locale | `string; /** The date, `YYYY-MM-DD` */ value?: string \| null; defaultValue?: string \| null; onValueChange?: (value: string \| null) => void; /** The earliest valid date, `YYYY-MM-DD` */ min?: string; /** The latest valid date, `YYYY-MM-DD` */ max?: string; name?: string; autoFocus?: boolean;` |  | BCP 47 locale used to format dates, eg. `en-GB`, defaults to the user's locale |
+| locale | `string; /** The date, `YYYY-MM-DD` */ value?: string \| null; defaultValue?: string \| null; onValueChange?: (value: string \| null) => void; /** The earliest valid date, `YYYY-MM-DD` */ min?: string; /** The latest valid date, `YYYY-MM-DD` */ max?: string; /** * Name of the hidden form input, which submits the date like a native * date input: `YYYY-MM-DD`, or an empty string when no date is set */ name?: string; autoFocus?: boolean;` |  | BCP 47 locale used to format dates, eg. `en-GB`, defaults to the user's locale |
 | label | `ReactNode` |  |  |
 | description | `ReactNode` |  |  |
 | error | `ReactNode` |  |  |

package/docs/components/dialog.md

@@ -134,11 +134,60 @@ export function DialogFormExample() {
 }
 ```
 
+## Submit a form
+
+Pass `onSubmit` to DialogContent to render its content as a [Form](form.md): a Button with `type="submit"` submits it with the values of the named fields. The dialog closes once `onSubmit` resolves without errors. Errors it returns, keyed by field name, show on the fields and keep the dialog open. `onClose` on Dialog runs whenever the dialog closes, after `onOpenChange(false)`, for example to reset state. The form takes no room of its own (`display: contents`): put spacing such as a `gap` on DialogContent.
+
+Example: Dialog: submit
+```tsx
+import {
+  Button,
+  Dialog,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+  TextField
+} from 'alinea/components'
+
+// Stands in for a request to your own API, which returns errors by field name
+async function movePage(data: FormData) {
+  await new Promise(resolve => setTimeout(resolve, 300))
+  if (data.get('path') === 'about') return {path: 'This path is taken'}
+  return undefined
+}
+
+export function DialogSubmitExample() {
+  return (
+    <Dialog>
+      <DialogTrigger variant="outline">Change path</DialogTrigger>
+      <DialogContent onSubmit={movePage}>
+        <DialogHeader>
+          <DialogTitle>Change path</DialogTitle>
+          <DialogDescription>Try “about” to see an error.</DialogDescription>
+        </DialogHeader>
+        <TextField label="Path" name="path" defaultValue="about" autoFocus />
+        <DialogFooter>
+          <DialogClose variant="ghost">Cancel</DialogClose>
+          <Button type="submit" color="primary">
+            Save
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+```
+
 ## Props
 
 `Dialog`
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
+| onClose | `() => void` |  | Called when the dialog closes, after `onOpenChange(false)` |
 | open | `boolean` |  |  |
 | defaultOpen | `boolean` |  |  |
 | onOpenChange | `(open: boolean) => void` |  |  |
@@ -153,6 +202,8 @@ Accepts every prop of `Button`.
 | size | `'default' \| 'lg' \| 'full'` | `'default'` | `default` fits its content up to a narrow width, `lg` is a fixed wide dialog and `full` fills the viewport (minus a margin), defaults to `default` |
 | dismissable | `boolean` | `true` | Close the dialog when clicking outside of it, defaults to true |
 | showCloseButton | `boolean` | `true` | Defaults to true |
+| onSubmit | `FormProps['onSubmit']` |  | Renders the content as a Form, submitted by a `type="submit"` Button. The dialog closes once this resolves without returning errors, which are shown on the fields otherwise. |
+| validationErrors | `ValidationErrors` |  | Errors keyed by field name, when the content is a form |
 Also accepts `className` and `style`, `id` and `aria-*` labelling attributes, `data-*` attributes.
 
 `DialogHeader`

package/docs/components/form.md

@@ -0,0 +1,67 @@
+# Form
+
+A form whose fields show their validation errors. `onSubmit` receives the `FormData` of the named fields instead of the browser submitting the form. It can return errors keyed by field name, also from a promise, which show on those fields until they are edited.
+
+Example: Form
+```tsx
+import {
+  Button,
+  Form,
+  Select,
+  SelectItem,
+  Stack,
+  Text,
+  TextField
+} from 'alinea/components'
+import {useState} from 'react'
+
+// Stands in for a request to your own API, which returns errors by field name
+async function createPage(data: FormData) {
+  await new Promise(resolve => setTimeout(resolve, 300))
+  if (data.get('path') === 'about') return {path: 'This path is taken'}
+  return undefined
+}
+
+export function FormExample() {
+  const [created, setCreated] = useState<string>()
+  return (
+    <Form
+      style={{width: 300}}
+      onSubmit={async data => {
+        const errors = await createPage(data)
+        if (!errors) setCreated(String(data.get('title')))
+        return errors
+      }}
+    >
+      <Stack gap={16}>
+        <TextField label="Title" name="title" required />
+        <TextField label="Path" name="path" defaultValue="about" />
+        <Select label="Type" name="type" defaultValue="page">
+          <SelectItem value="page">Page</SelectItem>
+          <SelectItem value="post">Blog post</SelectItem>
+        </Select>
+        <Button type="submit" color="primary">
+          Create page
+        </Button>
+        {created && <Text size="sm">Created “{created}”</Text>}
+      </Stack>
+    </Form>
+  )
+}
+```
+
+## Validation
+
+Native constraints are checked when the form is submitted: `required`, and `pattern`, `minLength` and `maxLength` on a TextField. `validationErrors` shows errors you already have, for example from a server, keyed by field name like the ones `onSubmit` returns. An `error` set on a field itself takes precedence.
+
+The form controls of `alinea/components` take a `name` to be submitted under: text, number and select controls submit their value as a string, dates and times as ISO strings (`2026-09-23`, `14:30`) and MultipleSelect one entry per picked value. To submit a form from a dialog, pass `onSubmit` to [DialogContent](dialog.md#submit-a-form): the dialog closes once it succeeds.
+
+## Props
+
+`Form`
+A form whose fields show validation errors: native constraints such as `required` once the form is submitted, and `validationErrors` or the errors returned by `onSubmit` by field name. An `error` set on a field itself takes precedence.
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| validationErrors | `ValidationErrors` |  | Errors keyed by field name, eg. from the server. A field shows its error until it is edited. |
+| onSubmit | `(data: FormData) => FormSubmitResult \| Promise<FormSubmitResult>` |  | Called with the form data instead of submitting the form natively. Errors it returns are shown on the fields, next to `validationErrors`. |
+Also accepts `className` and `style`, `id` and `aria-*` labelling attributes, `data-*` attributes.

package/docs/components/link.md

@@ -19,6 +19,10 @@ export function LinkExample() {
 }
 ```
 
+## Attributes
+
+Besides `href`, the link passes `target`, `rel`, `download`, `title`, `tabIndex`, `lang`, `hrefLang`, `referrerPolicy` and `aria-current` to its `<a>`. Mark the link to the page that is shown with `aria-current="page"`.
+
 ## Props
 
 `Link`
@@ -28,6 +32,12 @@ export function LinkExample() {
 | target | `string` |  |  |
 | rel | `string` |  |  |
 | download | `boolean \| string` |  |  |
+| title | `string` |  | Tooltip text |
+| tabIndex | `number` |  |  |
+| lang | `string` |  |  |
+| hrefLang | `string` |  |  |
+| referrerPolicy | `HTMLAttributeReferrerPolicy` |  |  |
+| aria-current | `boolean \| 'page' \| 'step' \| 'location' \| 'date' \| 'time'` |  |  |
 | variant | `'plain' \| 'underline'` | `'plain'` | `plain` underlines on hover, `underline` is always underlined |
 | disabled | `boolean` |  |  |
 | onClick | `(event: MouseEvent<HTMLAnchorElement>) => void` |  |  |

package/docs/components/multiple-select.md

@@ -22,35 +22,27 @@ export function MultipleSelectExample() {
 }
 ```
 
+## Values
+
+The value is an array of the `value`s of the picked items, strings or numbers. With a `name` the field submits one form entry per value, like a native multiple select: read them with `formData.getAll(name)`.
+
 ## Props
 
 `MultipleSelect`
 A labelled field to pick several values from a searchable list, the selected values are shown as removable tags.
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| value | `Array<string>` |  |  |
-| defaultValue | `Array<string>` |  |  |
-| onValueChange | `(value: Array<string>) => void` |  |  |
+| value | `Array<V>` |  | The values of the selected MultipleSelectItems |
+| defaultValue | `Array<V>` |  |  |
+| onValueChange | `(value: Array<V>) => void` |  |  |
 | placeholder | `string` |  |  |
 | emptyMessage | `ReactNode` | `'No options'` | Shown in the list when no item matches the search, defaults to "No options" |
-| name | `string` |  | Name of the hidden form input carrying the values |
-| label | `ReactNode` |  |  |
-| description | `ReactNode` |  |  |
-| error | `ReactNode` |  |  |
-| required | `boolean` |  |  |
-| disabled | `boolean` |  |  |
-| readOnly | `boolean` |  |  |
-| icon | `IconType \| ReactElement` |  |  |
-| shared | `boolean` |  | Marks the field as shared between translations |
-| open | `boolean` |  |  |
-| defaultOpen | `boolean` |  |  |
-| onOpenChange | `(open: boolean) => void` |  |  |
-Also accepts `className` and `style`, `id` and `aria-*` labelling attributes, `data-*` attributes.
+| name | `string` |  | Name of the hidden form input carrying the values, it submits one entry per selected value like a native multiple select: read them with `formData.getAll(name)` |
 
 `MultipleSelectItem`
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| value (required) | `string` |  |  |
+| value (required) | `Key` |  |  |
 | textValue | `string` |  | Text used for searching and the tag, defaults to string children |
 | disabled | `boolean` |  |  |
 Also accepts `className` and `style`.

package/docs/components/number-field.md

@@ -19,6 +19,10 @@ export function NumberFieldExample() {
 }
 ```
 
+## Formatting
+
+`formatOptions` takes the options of `Intl.NumberFormat`, such as a currency or a unit, and the number is shown and parsed in the locale of the dashboard. Digits are not grouped by default, since number fields often hold years or ids: pass `formatOptions={{useGrouping: true}}` to show `1,250` rather than `1250`. The value is a number, or `null` when the field is empty.
+
 ## Props
 
 `NumberField`
@@ -30,7 +34,7 @@ export function NumberFieldExample() {
 | min | `number` |  |  |
 | max | `number` |  |  |
 | step | `number` |  |  |
-| formatOptions | `Intl.NumberFormatOptions` |  |  |
+| formatOptions | `Intl.NumberFormatOptions` |  | How the number is shown and parsed. Digits are not grouped unless `useGrouping` is set: number fields often hold years and ids |
 | placeholder | `string` |  |  |
 | steppers | `boolean` | `true` | Show increment and decrement buttons, defaults to true |
 | name | `string` |  |  |

package/docs/components/select.md

@@ -1,6 +1,6 @@
 # Select
 
-Picks a single value from a list of options. The value is the `value` of the chosen SelectItem, and editors can clear it unless the field is required.
+Picks a single value from a list of options. The value is the `value` of the chosen SelectItem, and `onValueChange` receives it, typed like the `value` you pass: values are strings or numbers. Set `clearable` to show a button that clears the value again, `onValueChange` then receives `null`.
 
 Example: Select
 ```tsx
@@ -63,7 +63,7 @@ export function SelectGroupsExample() {
 
 ## States
 
-A placeholder shows while nothing is selected. Like the other form controls, a select takes `description`, `error`, `required`, `disabled` and `readOnly`.
+A placeholder shows while nothing is selected, and `clearable` adds a button to clear the selection. Like the other form controls, a select takes `description`, `error`, `required`, `disabled` and `readOnly`.
 
 Example: Select: states
 ```tsx
@@ -72,7 +72,7 @@ import {Select, SelectItem} from 'alinea/components'
 export function SelectStatesExample() {
   return (
     <div style={{display: 'grid', gap: 16, width: 280}}>
-      <Select label="Category" placeholder="Choose a category">
+      <Select label="Category" placeholder="Choose a category" clearable>
         <SelectItem value="bedroom">Bedroom</SelectItem>
         <SelectItem value="dining">Dining</SelectItem>
       </Select>
@@ -92,33 +92,22 @@ export function SelectStatesExample() {
 ## Props
 
 `Select`
-A labelled field to pick a single value from a list. The value can be cleared unless the field is required.
+A labelled field to pick a single value from a list. Set `clearable` to let the value be cleared again.
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| value | `string \| null` |  |  |
-| defaultValue | `string \| null` |  |  |
-| onValueChange | `(value: string \| null) => void` |  | Called with the selected value, or null when the value is cleared |
+| value | `V \| null` |  | The value of the selected SelectItem |
+| defaultValue | `V \| null` |  |  |
+| onValueChange | `(value: V \| null) => void` |  | Called with the selected value, or null when the value is cleared |
 | placeholder | `string` |  |  |
+| clearable | `boolean` |  | Show a button that clears the value |
 | name | `string` |  | Name of the hidden form input carrying the value |
 | autoFocus | `boolean` |  |  |
 | size | `'default' \| 'sm'` | `'default'` | `sm` is as tall as a default Button, defaults to `default` |
-| label | `ReactNode` |  |  |
-| description | `ReactNode` |  |  |
-| error | `ReactNode` |  |  |
-| required | `boolean` |  |  |
-| disabled | `boolean` |  |  |
-| readOnly | `boolean` |  |  |
-| icon | `IconType \| ReactElement` |  |  |
-| shared | `boolean` |  | Marks the field as shared between translations |
-| open | `boolean` |  |  |
-| defaultOpen | `boolean` |  |  |
-| onOpenChange | `(open: boolean) => void` |  |  |
-Also accepts `className` and `style`, `id` and `aria-*` labelling attributes, `data-*` attributes.
 
 `SelectItem`
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| value (required) | `string` |  |  |
+| value (required) | `Key` |  |  |
 | disabled | `boolean` |  |  |
 | icon | `IconType \| ReactElement` |  |  |
 | textValue | `string` |  | Text used for typeahead and the value, defaults to string children |

package/docs/components/stack.md

@@ -0,0 +1,42 @@
+# Stack
+
+Lays out its children in a column, or a row with `direction="row"`, with a `gap` between them: a number is in pixels, a string any CSS length. `align` positions the items across the stack (they stretch by default), `justify` along it, and `wrap` lets a row continue on the next line.
+
+Example: Stack
+```tsx
+import {Badge, Button, Stack, TextField} from 'alinea/components'
+
+export function StackExample() {
+  return (
+    <Stack gap={16} style={{width: 320}}>
+      <Stack direction="row" align="center" justify="between">
+        <strong>About us</strong>
+        <Badge status="draft">Draft</Badge>
+      </Stack>
+      <TextField label="Title" defaultValue="About us" />
+      <TextField label="Path" defaultValue="about" />
+      <Stack direction="row" gap={8} justify="end" wrap>
+        <Button variant="outline">Cancel</Button>
+        <Button color="primary">Save</Button>
+      </Stack>
+    </Stack>
+  )
+}
+```
+
+With `asChild` the stack lays out its single child element instead of rendering a div. `Stack` replaces the deprecated `HStack` and `VStack` of `alinea/ui`: `<Stack direction="row">` is an HStack.
+
+## Props
+
+`Stack`
+Lays out its children in a row or column with a gap between them
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| direction | `'row' \| 'column'` | `'column'` | Defaults to `column` |
+| gap | `number \| string` |  | Space between the items, a number is in pixels |
+| align | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` |  | Cross axis alignment of the items, they stretch by default |
+| justify | `'start' \| 'center' \| 'end' \| 'between'` |  | Main axis distribution of the items |
+| wrap | `boolean` |  | Wrap items onto multiple lines |
+| asChild | `boolean` |  | Lay out the single child element instead of rendering a div |
+| ref | `Ref<HTMLDivElement>` |  |  |
+Also accepts `className` and `style`, `id` and `aria-*` labelling attributes, `data-*` attributes.

package/docs/components/table.md

@@ -112,6 +112,84 @@ export function TableSelectionExample() {
 }
 ```
 
+## Load more rows
+
+`onLoadMore` is called when the rows are scrolled close to the end, to fetch the next page. While `loading` is set, a spinner shows below the rows, or in place of them while there are none. `useAsyncList` keeps the loaded pages: its `load` function receives the `cursor` the previous page returned, and `loadMore` does nothing once a page returns no cursor. Its `items`, `loading`, `loadMore`, `sortDescriptor` and `sort`, and `selectedKeys` and `setSelectedKeys` plug into the props of the table. `update(key, item)`, `remove(...keys)`, `prepend(...items)` and `append(...items)` change the loaded items without loading them again, for example after a dialog saves a row.
+
+Example: Table: async
+```tsx
+import {
+  Table,
+  TableCell,
+  TableRow,
+  TableTitle,
+  useAsyncList
+} from 'alinea/components'
+
+interface Product {
+  id: string
+  title: string
+  price: number
+}
+
+const materials = ['Linen', 'Oak', 'Wool', 'Walnut', 'Ceramic']
+const kinds = ['shirt', 'chair', 'throw', 'stool', 'lamp', 'table']
+
+// Stands in for a paged API: 20 products per page, 100 in total
+async function fetchProducts(page: number) {
+  await new Promise(resolve => setTimeout(resolve, 500))
+  const items: Array<Product> = Array.from({length: 20}, (_, i) => {
+    const n = page * 20 + i
+    const title = `${materials[n % 5]} ${kinds[n % 6]} ${n + 1}`
+    return {id: `product-${n}`, title, price: 40 + ((n * 37) % 300)}
+  })
+  return {items, cursor: page < 4 ? page + 1 : undefined}
+}
+
+export function TableAsyncExample() {
+  const list = useAsyncList<Product, number>({
+    load: ({cursor = 0}) => fetchProducts(cursor)
+  })
+  return (
+    <div style={{width: 420, height: 260}}>
+      <Table
+        aria-label="Products"
+        items={list.items}
+        columns={[
+          {id: 'title', header: 'Title', width: '1fr'},
+          {id: 'price', header: 'Price', width: 100, align: 'end'}
+        ]}
+        loading={list.loading}
+        onLoadMore={list.loadMore}
+      >
+        {product => (
+          <TableRow id={product.id} textValue={product.title}>
+            <TableTitle title={product.title} />
+            <TableCell align="end">€{product.price}</TableCell>
+          </TableRow>
+        )}
+      </Table>
+    </div>
+  )
+}
+```
+
+```tsx
+import {useAsyncList} from 'alinea/components'
+
+const list = useAsyncList({
+  async load({cursor, filterText, sort, signal}) {
+    const res = await fetch(`/api/products?page=${cursor ?? 1}`, {signal})
+    const {items, next} = await res.json()
+    // Leave out the cursor, or return null, on the last page
+    return {items, cursor: next}
+  }
+})
+// list.items, list.loading, list.hasMore, list.error,
+// list.loadMore(), list.reload(), list.setFilterText(text), list.sort(sort),
+// list.update(id, item), list.remove(id), list.prepend(item)
+```
+
 ## Props
 
 `Table`
@@ -132,6 +210,8 @@ export function TableSelectionExample() {
 | onSortChange | `(descriptor: SortDescriptor) => void` |  |  |
 | onRowAction | `(key: Key) => void` |  | Called when a row is activated (see `selectionBehavior`), rows can override it with their own `onAction` |
 | renderEmptyState | `() => ReactNode` |  |  |
+| loading | `boolean` |  | Shows a spinner in place of the rows while there are none, below the rows otherwise |
+| onLoadMore | `() => void` |  | Called when the rows are scrolled close to the end, to load the next page (see useAsyncList) |
 | dependencies | `ReadonlyArray<unknown>` |  | Rows are cached per item, list the values `children` reads besides the item to render them again when those change |
 | children (required) | `(item: T) => ReactElement` |  |  |
 
@@ -174,6 +254,9 @@ Also accepts `className` and `style`.
 | suffix | `ReactNode` |  | Shown right after the title, eg. a status icon |
 Also accepts `className` and `style`.
 
+`useAsyncList`
+Loads a list of items, with sorting, filtering and paging
+
 ## Accessibility
 
 Built on the React Aria grid: the arrow keys move between rows, Space selects a row and Enter runs its action. Sortable column headers announce their sort direction.

package/docs/components/text-field.md

@@ -43,7 +43,7 @@ export function TextFieldStatesExample() {
 
 ## Multiline
 
-A multiline field starts at `rows` lines and grows as editors type.
+A multiline field starts at `rows` lines and grows as editors type, up to `maxRows` lines when you set it, then it scrolls.
 
 Example: TextField: multiline
 ```tsx
@@ -55,6 +55,7 @@ export function TextFieldMultilineExample() {
       label="Description"
       multiline
       rows={4}
+      maxRows={8}
       defaultValue="A relaxed shirt in washed linen that softens with every wear."
       style={{width: 300}}
     />
@@ -95,6 +96,10 @@ export function TextFieldIconsExample() {
 }
 ```
 
+## Native input attributes
+
+`type`, `name`, `autoComplete`, `inputMode`, `pattern`, `minLength` and `maxLength` are passed to the input. `inputMode` picks the virtual keyboard on touch devices, eg. `numeric` for a code, and `pattern` is a regular expression the value must match, checked when the field is in a [Form](form.md).
+
 ## Props
 
 `TextField`
@@ -107,6 +112,7 @@ export function TextFieldIconsExample() {
 | type | `'text' \| 'email' \| 'url' \| 'password' \| 'tel' \| 'search'` | `'text'` |  |
 | multiline | `boolean` |  | Render a textarea that grows with its content |
 | rows | `number` | `1` | Minimum number of rows of a multiline field |
+| maxRows | `number` |  | Maximum number of rows a multiline field grows to before it scrolls |
 | startIcon | `IconType \| ReactElement` |  | Icon displayed inside the input, before the text |
 | endIcon | `IconType \| ReactElement` |  | Icon displayed inside the input, after the text |
 | name | `string` |  |  |
@@ -114,6 +120,8 @@ export function TextFieldIconsExample() {
 | autoComplete | `string` |  |  |
 | maxLength | `number` |  |  |
 | minLength | `number` |  |  |
+| inputMode | `'none' \| 'text' \| 'tel' \| 'url' \| 'email' \| 'numeric' \| 'decimal' \| 'search'` |  | Which virtual keyboard to show, eg. `numeric` for a code |
+| pattern | `string` |  | A regular expression the value must match to be valid |
 | onBlur | `(event: FocusEvent<TextFieldElement>) => void` |  |  |
 | onFocus | `(event: FocusEvent<TextFieldElement>) => void` |  |  |
 | onKeyDown | `(event: KeyboardEvent<TextFieldElement>) => void` |  |  |

package/docs/components/time-field.md

@@ -18,13 +18,17 @@ export function TimeFieldExample() {
 }
 ```
 
+## Value
+
+The value is an ISO time string: `14:30`, or `14:30:15` with `granularity="second"`. With a `name` the field submits the same string in a form, like a native time input, and an empty string when no time is set. `hourCycle` only changes how the time is shown.
+
 ## Props
 
 `TimeField`
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | locale | `string; /** The time, `HH:mm` or `HH:mm:ss` */ value?: string \| null; defaultValue?: string \| null; /** Receives `HH:mm`, or `HH:mm:ss` when granularity is `second` */ onValueChange?: (value: string \| null) => void; /** The earliest valid time, `HH:mm` or `HH:mm:ss` */ min?: string; /** The latest valid time, `HH:mm` or `HH:mm:ss` */ max?: string; /** The smallest unit that can be edited, defaults to `minute` */ granularity?: 'minute' \| 'second'; /** Defaults to the locale's hour cycle */ hourCycle?: 12 \| 24` |  | BCP 47 locale used to format dates, eg. `en-GB`, defaults to the user's locale |
-| name | `string` |  |  |
+| name | `string` |  | Name of the hidden form input, which submits the time like a native time input: `HH:mm`, or `HH:mm:ss` when granularity is `second`, and an empty string when no time is set |
 | autoFocus | `boolean` |  |  |
 | label | `ReactNode` |  |  |
 | description | `ReactNode` |  |  |