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

package/docs/transfer.md

@@ -0,0 +1,273 @@
+<!-- index: ./index.md -->
+# transfer
+
+`data-ui="transfer"` · Moves items between two lists.
+
+## Import
+
+```ts
+import { SlTransfer, SlTransferFooter, SlTransferItem, provideTransferDefaults } from '@slotted/angular/transfer';
+```
+
+Selector: `[slTransfer], ng-template[slTransferItem], ng-template[slTransferFooter]` · exportAs: `slTransfer`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slTransfer aria-label="Project team" [items]="people" [(targetKeys)]="team"></div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element slTransfer is on | yes |
+| `switch` | div around an slSegmentedControl | yes |
+| `body` | div | yes |
+| `pane` | div | yes |
+| `pane-header` | div | yes |
+| `select-all` | span around an slCheckbox | no |
+| `title` | span | yes |
+| `count` | span | yes |
+| `search` | div around an slTextField | no |
+| `search-icon` | span | no |
+| `list` | div around an slListbox | yes |
+| `empty` | div inside the listbox’s slListboxEmpty | no |
+| `drop-indicator` | div | no |
+| `pane-footer` | div | no |
+| `actions` | div | yes |
+| `move-to-target` | button slButton | yes |
+| `move-all-to-target` | button slButton | yes |
+| `move-to-source` | button slButton | yes |
+| `move-all-to-source` | button slButton | yes |
+| `reorder` | div | no |
+| `move-up` | button slButton | no |
+| `move-down` | button slButton | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `readonly T[]` | — | [slTransfer] | The whole collection, both sides |
+| `getKey` | `(item: T) => string` | item.key | [slTransfer] | The key an item is moved and selected by |
+| `getLabel` | `(item: T) => string` | item.label | [slTransfer] | What typeahead and the search match |
+| `getDescription` | `(item: T) => string \| undefined` | item.description | [slTransfer] | A second line under the label, also searched |
+| `isItemDisabled` | `(item: T) => boolean` | item.disabled | [slTransfer] | A disabled item cannot be selected or moved |
+| `targetKeys` | `model<readonly string[] \| undefined>` | — | [slTransfer] | Two-way. Unbound, the transfer holds the keys itself from defaultTargetKeys |
+| `defaultTargetKeys` | `readonly string[]` | [] | [slTransfer] | The start while targetKeys is unbound |
+| `selectedKeys` | `model<readonly string[] \| undefined>` | — | [slTransfer] | Two-way selection across both panes |
+| `defaultSelectedKeys` | `readonly string[]` | [] | [slTransfer] | The start while selectedKeys is unbound |
+| `sourceQuery` | `model<string \| undefined>` | — | [slTransfer] | Two-way source search |
+| `defaultSourceQuery` | `string` | '' | [slTransfer] | The start while sourceQuery is unbound |
+| `targetQuery` | `model<string \| undefined>` | — | [slTransfer] | Two-way target search |
+| `defaultTargetQuery` | `string` | '' | [slTransfer] | The start while targetQuery is unbound |
+| `pane` | `model<'source' \| 'target' \| undefined>` | source | [slTransfer] | Two-way pane shown in steps |
+| `defaultPane` | `'source' \| 'target'` | source | [slTransfer] | The start while pane is unbound |
+| `filter` | `(item: T, query: string, side) => boolean` | locale contains | [slTransfer] | Whether an item answers a query |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | [slTransfer], provideTransferDefaults | The lists’ step; the search and the buttons stand one below |
+| `layout` | `'auto' \| 'columns' \| 'steps'` | auto | [slTransfer], provideTransferDefaults | auto answers the root’s own width: columns from 36rem, steps below |
+| `searchable` | `boolean` | true | [slTransfer], provideTransferDefaults | Whether each pane has a search field |
+| `selectAll` | `boolean` | true | [slTransfer], provideTransferDefaults | Whether each pane has a select-all box |
+| `reorderable` | `boolean` | false | [slTransfer], provideTransferDefaults | Whether the target keeps an order of its own |
+| `rows` | `number` | 8 | [slTransfer], provideTransferDefaults | How many options tall each list is |
+| `virtual` | `boolean` | false | [slTransfer] | Windows both lists; needs itemSize |
+| `itemSize` | `number` | — | [slTransfer] | The block size of one option, in pixels |
+| `overscan` | `number` | 4 | [slTransfer] | Options rendered either side of a windowed viewport |
+| `disabled` | `boolean` | false | [slTransfer] | Stops every control; a disabled form control sets it too |
+| `readOnly` | `boolean` | false | [slTransfer] | Keeps the lists reachable and refuses every move |
+| `required` | `boolean` | false | [slTransfer] | aria-required on both lists, and { required: true } to a form while the target is empty |
+| `invalid` | `boolean` | false | [slTransfer] | The danger edge on both panes |
+| `loading` | `boolean` | false | [slTransfer] | The source is still arriving |
+| `hasMore` | `boolean` | false | [slTransfer] | The source has another page; draws the loading row |
+| `name` | `string` | — | [slTransfer] | Submits one hidden input per target key |
+| `messages` | `Partial<TransferMessages>` | — | [slTransfer] | Words laid over the language in force, key by key; {slot}s are filled |
+| `slTransferItem` | `ng-template, let-item, side` | label and description | a child template | The content of one option inside the check the family draws |
+| `slTransferFooter` | `ng-template, let-side` | — | a child template | Content under a pane’s list |
+| `focus(side?) / scrollToKey(key)` | `methods, through #ref="slTransfer"` | — | [slTransfer] | Move focus into a list; reveal an item in whichever pane holds it |
+| `native attributes` | `HTML attributes` | — | the host | aria-*, id, class and listeners stay on the element the directive is on; a role written there wins |
+| `provideTransferDefaults` | `{ size, layout, searchable, selectAll, reorderable, rows }` | — | providers | The decisions an application takes once |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `targetKeysChangeRequest` | `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. |
+| `targetKeysChange` | `readonly string[]` | The model half of [(targetKeys)], after a request nobody cancelled. A form control is told at the same moment. |
+| `selectedKeysChangeRequest` | `ChangeRequest<readonly string[]>` | Before the selection moves: a press or a key in a list, select-all or Control+A (select), and after a move. |
+| `selectedKeysChange` | `readonly string[]` | The model half of [(selectedKeys)]. |
+| `sourceQueryChangeRequest / targetQueryChangeRequest` | `ChangeRequest<string>` | Before a pane’s search moves: typing (keyboard) or the clear control (clear). |
+| `sourceQueryChange / targetQueryChange` | `string` | The model halves of [(sourceQuery)] and [(targetQuery)]. |
+| `paneChangeRequest` | `ChangeRequest<'source' \| 'target'>` | Before the switch names the other pane (pointer, keyboard). |
+| `paneChange` | `'source' \| 'target'` | The model half of [(pane)]. |
+| `loadMore` | `void` | When the source list reaches the end of what has been loaded while hasMore is true. |
+
+## 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 slListbox 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” — and a list that a move emptied hands focus to the other list rather than to nothing.
+- The select-all box is named on its input, “Select all in Available”: the slCheckbox family takes its name from its label and offers no input for one, so the family writes aria-label on the control after each render and leaves the label empty.
+
+## 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
+
+```html
+<div slTransfer [items]="people" [(selectedKeys)]="selected"></div>
+```
+
+### 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
+
+```html
+<div slTransfer [items]="people" [filter]="byEmail"></div>
+```
+
+### 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.
+
+Excerpt — not a complete module
+
+```html
+<div slTransfer reorderable [items]="widgets" [messages]="{ target: 'On the dashboard' }"></div>
+```
+
+### 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
+
+```html
+<div slTransfer reorderable [items]="people"></div>
+```
+
+### 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
+
+```html
+<div slTransfer layout="steps" [items]="people" [(pane)]="pane"></div>
+```
+
+### 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; required reports { required: true } to a form while the target is empty.
+
+Excerpt — not a complete module
+
+```html
+<div slTransfer disabled [items]="people"></div>
+<div slTransfer readOnly [items]="people"></div>
+<div slTransfer invalid required [items]="people"></div>
+```
+
+### Two thousand items
+
+virtual with an itemSize windows both lists, so a directory of two thousand people scrolls without drawing them all.
+
+Excerpt — not a complete module
+
+```html
+<div slTransfer virtual [itemSize]="34" [items]="directory"></div>
+```
+
+### A source that arrives in pages
+
+loading marks the source busy; hasMore draws the loading row at its end and (loadMore) asks for the next page when the reader reaches it.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slTransfer
+  [items]="page().items"
+  [loading]="page().loading"
+  [hasMore]="page().hasMore"
+  (loadMore)="fetchNext()"
+></div>
+```
+
+### 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
+
+```html
+<div slTransfer [items]="permissions">
+  <ng-template slTransferItem let-permission>
+    <span slListboxLabel>{{ permission.label }}</span>
+    <span slListboxMeta>{{ permission.scope }}</span>
+  </ng-template>
+</div>
+```
+
+### In a form
+
+The transfer is a ControlValueAccessor over targetKeys and a Validator for required; a disabled control disables it. name submits one hidden input per chosen key.
+
+Excerpt — not a complete module
+
+```html
+<div slTransfer required formControlName="reviewers" [items]="people"></div>
+```
+
+### Words for another product
+
+Every word is a message: the titles, the four moves, the counts and the announcements. provideSlotted sets the language once; an instance lays its own words over it.
+
+Excerpt — not a complete module
+
+```ts
+providers: [provideSlotted({ locale: 'pt-BR', catalogs: { 'pt-BR': PT_BR } })];
+```
+
+### 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
+
+```html
+<div slTransfer reorderable [items]="people"></div>
+```
+
+### 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
+
+```html
+<div slTransfer [items]="people" [messages]="{ moved: '{count} added to {pane}' }"></div>
+```