@slotted/react 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/transfer.md

@@ -0,0 +1,291 @@
+<!-- index: ./index.md -->
+# transfer
+
+`data-ui="transfer"` · Moves items between two lists.
+
+## Import
+
+```tsx
+import { Transfer, TransferDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+const [team, setTeam] = useState<readonly string[]>(['ana', 'kenji', 'marta']);
+
+<Transfer
+  aria-label="Project team"
+  items={people}
+  onTargetKeysChange={(keys) => setTeam(keys)}
+  targetKeys={team}
+/>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `switch` | div around a SegmentedControl | yes |
+| `body` | div | yes |
+| `pane` | div | yes |
+| `pane-header` | div | yes |
+| `select-all` | span around a Checkbox | no |
+| `title` | span | yes |
+| `count` | span | yes |
+| `search` | div around a TextField | no |
+| `search-icon` | span | no |
+| `list` | div around a Listbox | yes |
+| `empty` | div inside the Listbox’s own empty part | no |
+| `drop-indicator` | div | no |
+| `pane-footer` | div | no |
+| `actions` | div | yes |
+| `move-to-target` | button, a Button | yes |
+| `move-all-to-target` | button, a Button | yes |
+| `move-to-source` | button, a Button | yes |
+| `move-all-to-source` | button, a Button | yes |
+| `reorder` | div | no |
+| `move-up` | button, a Button | no |
+| `move-down` | button, a Button | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `readonly T[]` | — | Transfer | The whole collection, both sides |
+| `getKey` | `(item: T) => string` | item.key | Transfer | The key an item is moved and selected by |
+| `getLabel` | `(item: T) => string` | item.label | Transfer | What typeahead and the search match, and what a reader hears |
+| `getDescription` | `(item: T) => string \| undefined` | item.description | Transfer | A second line under the label, also searched |
+| `isItemDisabled` | `(item: T) => boolean` | item.disabled | Transfer | A disabled item cannot be selected or moved and stays where it is |
+| `renderItem` | `(item: T, { side, resolved }) => ReactNode` | label and description | Transfer | The content of one option inside the check the family draws; write it with ListboxLabel, ListboxDescription and ListboxMeta |
+| `targetKeys` | `readonly string[]` | — | Transfer | Present means the consumer owns the target, for the life of the component |
+| `defaultTargetKeys` | `readonly string[]` | [] | Transfer | The uncontrolled start, read once |
+| `selectedKeys` | `readonly string[]` | — | Transfer | The selection across both panes. Present means controlled |
+| `defaultSelectedKeys` | `readonly string[]` | [] | Transfer | The uncontrolled selection, read once |
+| `sourceQuery` | `string` | — | Transfer | The source’s search. Present means controlled |
+| `defaultSourceQuery` | `string` | '' | Transfer | The uncontrolled source search, read once |
+| `targetQuery` | `string` | — | Transfer | The target’s search. Present means controlled |
+| `defaultTargetQuery` | `string` | '' | Transfer | The uncontrolled target search, read once |
+| `pane` | `'source' \| 'target'` | source | Transfer | The pane shown in steps. Present means controlled |
+| `defaultPane` | `'source' \| 'target'` | source | Transfer | The uncontrolled pane, read once |
+| `filter` | `(item: T, query: string, side) => boolean` | locale contains | Transfer | Whether an item answers a query |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | Transfer, TransferDefaultsProvider | The lists’ step; the search and the buttons stand one below |
+| `layout` | `'auto' \| 'columns' \| 'steps'` | auto | Transfer, TransferDefaultsProvider | auto answers the root’s own width: columns from 36rem, steps below |
+| `searchable` | `boolean` | true | Transfer, TransferDefaultsProvider | Whether each pane has a search field |
+| `selectAll` | `boolean` | true | Transfer, TransferDefaultsProvider | Whether each pane has a select-all box |
+| `reorderable` | `boolean` | false | Transfer, TransferDefaultsProvider | Whether the target keeps an order of its own |
+| `rows` | `number` | 8 | Transfer, TransferDefaultsProvider | How many options tall each list is |
+| `virtual` | `boolean` | false | Transfer | Windows both lists; needs itemSize |
+| `itemSize` | `number` | — | Transfer | The block size of one option, in pixels, for virtual |
+| `overscan` | `number` | 4 | Transfer | Options rendered either side of a windowed viewport |
+| `disabled` | `boolean` | false | Transfer | Stops every control; defaults to the field’s |
+| `readOnly` | `boolean` | false | Transfer | Keeps the lists reachable and refuses every move |
+| `required` | `boolean` | false | Transfer | Carried to both lists as aria-required; defaults to the field’s |
+| `invalid` | `boolean` | false | Transfer | The danger edge on both panes; defaults to the field’s |
+| `loading` | `boolean` | false | Transfer | The source is still arriving: aria-busy on its list |
+| `hasMore` | `boolean` | false | Transfer | The source has another page; draws the loading row |
+| `name` | `string` | — | Transfer | Submits one hidden input per target key |
+| `messages` | `Partial<TransferMessages>` | — | Transfer | Words laid over the language in force, key by key: source, target, search, selectAll, count, countSelected, countFiltered, paneCount, panes, empty, noResults, loading, actions, moveToTarget, moveAllToTarget, moveToSource, moveAllToSource, reorder, moveUp, moveDown, moved, movedOne, reordered; {slot}s are filled |
+| `renderFooter` | `(side) => ReactNode` | — | Transfer | Content under a pane’s list |
+| `handleRef` | `Ref<TransferHandle>` | — | Transfer | focus(side?) and scrollToKey(key); element, the root |
+| `render` | `(props: TransferRootProps) => ReactNode` | a div | Transfer | Substitutes the root element; attach props.ref beside your own, the drag measures against it |
+| `native props` | `ComponentPropsWithRef<"div">` | — | Transfer | aria-*, data-*, className, style and handlers reach the root |
+| `TransferDefaultsProvider` | `{ size, layout, searchable, selectAll, reorderable, rows }` | — | a subtree | The decisions an application takes once; an instance that states any of them wins |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onTargetKeysChange` | `(targetKeys: readonly string[], request: ChangeRequest<readonly string[]> & { direction: 'target' \| 'source' \| 'reorder'; keys: readonly string[] })` | Before the target moves: a move button or Up/Down (pointer, keyboard), Enter, Delete, Control+Arrow or Alt+Arrow in a list (keyboard), a drop (pointer). cancel() refuses it and nothing else follows. |
+| `onSelectedKeysChange` | `(selectedKeys: readonly string[], request: ChangeRequest<readonly string[]>)` | Before the selection moves: a press or a key in a list (pointer, keyboard), select-all or Control+A (select), and after a move, which takes the moved keys out with the move’s reason. |
+| `onSourceQueryChange / onTargetQueryChange` | `(query: string, request: ChangeRequest<string>)` | Before a pane’s search moves: typing (keyboard) or the clear control (clear). |
+| `onPaneChange` | `(pane: 'source' \| 'target', request: ChangeRequest<'source' \| 'target'>)` | Before the switch names the other pane (pointer, keyboard). |
+| `onLoadMore` | `()` | When the source list reaches the end of what has been loaded while hasMore is true. |
+| `onKeyDown and the other native handlers` | `the element’s own event` | Reach the root. The family’s own keys are taken in the capture phase of each list, so a handler that calls preventDefault() there first keeps the key. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `layout` | `auto`, `columns`, `steps` | `auto` |
+| `searchable` | `true`, `false` | `true` |
+| `selectAll` | `true`, `false` | `true` |
+| `reorderable` | `true`, `false` | `false` |
+| `virtual` | `true`, `false` | `false` |
+| `disabled` | `true`, `false` | `false` |
+
+## Rules
+
+- No WAI-ARIA pattern names a dual list; the APG’s Listboxes with Rearrangeable Options example is the closest, and the family follows its second example: each side is a multi-select listbox named by its title, Enter adds from the available list, Delete removes from the chosen one, and Alt+ArrowUp/Down moves an option with focus kept on it.
+- Each list is the Listbox family, so its own keyboard stands inside the pane: arrows, Home, End, PageUp, PageDown, Space, Shift ranges, Control+A and typeahead. Enter is the one key taken from it — the listbox selects with it, and here it moves — and Space still selects.
+- The move buttons say their shortcut through aria-keyshortcuts and keep their focus stop with aria-disabled when there is nothing to move, so the button that just emptied its own selection does not drop focus on the page.
+- Every move is announced through the shared polite live region — “Ana Souza moved to Chosen”, “3 moved to Available”, “Revenue moved to position 2” — and a list that a move emptied hands focus to the other list rather than to nothing.
+- A disabled item keeps its place and aria-disabled, and is skipped by the arrows, by select-all and by Add all; a key the collection does not hold is still announced by its key.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-shadow`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-font-family-mono`, `--slotted-font-family-sans`, `--slotted-font-size-xs`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-line-height-xs`, `--slotted-listbox-padding-block`, `--slotted-radius-full`, `--slotted-radius-md`, `--slotted-selection-size-lg`, `--slotted-selection-size-md`, `--slotted-selection-size-sm`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-solid`, `--slotted-tone-danger-border`, `--slotted-transfer-pane-min-inline-size`, `--slotted-transfer-rows`
+
+## Examples
+
+### Selecting, then moving
+
+Click, Shift+click and Control+A select inside a pane; the box in the header selects every visible enabled item and goes half-filled when some are. Add moves the selection and clears it.
+
+Excerpt — not a complete module
+
+```tsx
+<Transfer
+  items={people}
+  onSelectedKeysChange={(keys, request) => setSelected(keys)}
+  selectedKeys={selected}
+/>;
+```
+
+### Searching a pane
+
+Type fabio or design: the label and the description are searched in the locale, accents apart. The count says 1 of 12 shown, Add all moves only what is shown, and nothing matching says so over a search mark.
+
+Excerpt — not a complete module
+
+```tsx
+<Transfer filter={(person, query) => person.email.startsWith(query)} items={people} />;
+```
+
+### An order the reader decides
+
+Under reorderable the target keeps the order of targetKeys: a move joins the end, Up and Down move the selection one place, and Alt+ArrowUp/Down does the same from the list. Without it the target follows the collection.
+
+Excerpt — not a complete module
+
+```tsx
+<Transfer items={widgets} messages={{ target: 'On the dashboard' }} reorderable />;
+```
+
+### Dragging between the panes
+
+Drag a person across: a selected person carries the pane’s selection with them. In a reorderable target a line shows where the drop lands; a drop inside the source is refused, and Escape cancels.
+
+Excerpt — not a complete module
+
+```tsx
+<Transfer items={people} reorderable />;
+```
+
+### One pane at a time
+
+Below 36rem of its own width the transfer becomes two steps: the switch names the pane, Add and Add all stand under the source and Remove over the target. layout="steps" fixes it at any width.
+
+Excerpt — not a complete module
+
+```tsx
+<Transfer items={people} layout="steps" onPaneChange={(pane) => setPane(pane)} pane={pane} />;
+```
+
+### Disabled, read-only, invalid and required
+
+Disabled greys both panes and stops every control. Read-only keeps the lists reachable and selectable and refuses every move. Invalid draws the danger edge on both panes; required is carried to both lists.
+
+Excerpt — not a complete module
+
+```tsx
+<Transfer disabled items={people} />;
+<Transfer items={people} readOnly />;
+<Transfer invalid items={people} required />;
+```
+
+### Two thousand items
+
+virtual with an itemSize windows both lists, so a directory of two thousand people scrolls without drawing them all. Typeahead, Shift+click and the moves work across the whole set.
+
+Excerpt — not a complete module
+
+```tsx
+<Transfer itemSize={34} items={directory} virtual />;
+```
+
+### A source that arrives in pages
+
+loading marks the source busy; hasMore draws the loading row at its end and onLoadMore asks for the next page when the reader reaches it.
+
+Excerpt — not a complete module
+
+```tsx
+<Transfer
+  hasMore={page.hasMore}
+  items={page.items}
+  loading={page.loading}
+  onLoadMore={() => fetchNext()}
+/>;
+```
+
+### Content the family did not choose
+
+A description under the name, an unbroken permission key, a translated title that wraps, and a chosen key the collection does not hold — drawn with the key itself, in the muted mono ink, never dropped.
+
+Excerpt — not a complete module
+
+```tsx
+<Transfer
+  items={permissions}
+  renderItem={(permission) => (
+    <>
+      <ListboxLabel>{permission.name}</ListboxLabel>
+      <ListboxMeta>{permission.scope}</ListboxMeta>
+    </>
+  )}
+/>;
+```
+
+### In a form
+
+Inside a Field the transfer takes the label, the description and the disabled state; name submits one hidden input per chosen key, so a bare form posts the set.
+
+Excerpt — not a complete module
+
+```tsx
+<Field required>
+  <FieldLabel>Reviewers</FieldLabel>
+  <Transfer items={people} name="reviewers" />
+  <FieldDescription>At least one reviewer signs the release.</FieldDescription>
+</Field>;
+```
+
+### Words for another product
+
+Every word is a message: the titles, the four moves, the counts and the announcements. The language in force sets them once; an instance lays its own over them.
+
+Excerpt — not a complete module
+
+```tsx
+<SlottedProvider locale="pt-BR" catalogs={{ 'pt-BR': PT_BR }}>
+  <Transfer
+    items={permissions}
+    messages={{ target: 'Concedidas', moveToTarget: 'Conceder', moveToSource: 'Revogar' }}
+  />
+</SlottedProvider>;
+```
+
+### Keyboard
+
+In either list Enter moves the selection — or the option you are on — to the other side; Delete sends it back from the target; Control+ArrowRight and Control+ArrowLeft move toward that side, mirrored in right-to-left; Alt+ArrowUp/Down reorders. Space selects.
+
+Excerpt — not a complete module
+
+```tsx
+<Transfer items={people} reorderable />;
+```
+
+### Names, shortcuts and announcements
+
+Each pane is a group named by its title and each list a listbox named the same. The moves carry aria-keyshortcuts, and every move is announced politely: “2 moved to Chosen”.
+
+Excerpt — not a complete module
+
+```tsx
+<Transfer items={people} messages={{ moved: '{count} added to {pane}' }} />;
+```