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

package/docs/cascader.md

@@ -0,0 +1,379 @@
+<!-- index: ./index.md -->
+# cascader
+
+`data-ui="cascader"` · Picks a value from nested option columns.
+
+## Import
+
+```ts
+import { provideCascaderDefaults, SlCascader, SlCascaderNode, SlCascaderPanel } from '@slotted/angular/cascader';
+```
+
+Selector: `sl-cascader, sl-cascader-panel, ng-template[slCascaderNode]` · exportAs: `slCascader, slCascaderPanel`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<sl-cascader
+  aria-label="Location"
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+  [(value)]="place"
+/>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `trigger` | button | yes |
+| `value` | span | no |
+| `value-segment` | span | no |
+| `value-separator` | span | no |
+| `placeholder` | span | no |
+| `tags` | span | no |
+| `summary` | span | no |
+| `clear` | button | no |
+| `busy` | span | no |
+| `arrow` | span | no |
+| `positioner` | div | yes |
+| `content` | div | yes |
+| `search` | div | no |
+| `search-input` | input | no |
+| `breadcrumb` | nav | no |
+| `crumb` | button | no |
+| `panel` | div | yes |
+| `column` | div | yes |
+| `node` | div | yes |
+| `indicator` | span | no |
+| `icon` | span | no |
+| `label` | span | yes |
+| `match` | mark | no |
+| `description` | span | no |
+| `meta` | span | no |
+| `expander` | span | no |
+| `loader` | div | no |
+| `status` | div | no |
+| `empty` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `nodes` | `readonly T[]` | [] | sl-cascader, sl-cascader-panel | The roots, nested, or a flat list read with getParent. |
+| `getKey` | `(node) => string` | — | sl-cascader, sl-cascader-panel | A stable key, which is also the value. |
+| `getLabel` | `(node) => string` | — | sl-cascader, sl-cascader-panel | The name, which search and typeahead read. |
+| `getChildren` | `(node) => T[] \| undefined` | — | sl-cascader, sl-cascader-panel | The children of a nested node. |
+| `getParent` | `(node) => string \| null` | — | sl-cascader, sl-cascader-panel | Opts in to a flat list; an unknown parent makes a root. |
+| `hasChildren` | `(node) => boolean` | — | sl-cascader, sl-cascader-panel | A branch whose children have not arrived says so. |
+| `isNodeDisabled` | `(node) => boolean` | — | sl-cascader, sl-cascader-panel | Stays on show and reachable, never chosen. |
+| `isNodeLoading` | `(node) => boolean` | — | sl-cascader, sl-cascader-panel | The children of this branch are on their way. |
+| `isNodeFailed` | `(node) => boolean` | — | sl-cascader, sl-cascader-panel | The children of this branch could not be loaded. |
+| `loading` | `boolean` | false | sl-cascader, sl-cascader-panel | The roots are on their way: the first level waits as rows and the control shows the ring. |
+| `value` | `model<string \| null \| string[]>` | null | sl-cascader, sl-cascader-panel | A scalar for one choice, a list for many. A model, so [(value)] is both the value and the write-back. |
+| `open` | `model<boolean>` | false | sl-cascader | Whether the popup is showing. |
+| `path` | `model<readonly string[]>` | [] | sl-cascader, sl-cascader-panel | The branches whose levels are on show, root first. |
+| `activeKey` | `model<string \| null>` | null | sl-cascader, sl-cascader-panel | The node under the cursor. |
+| `expandedKeys` | `model<readonly string[]>` | [] | sl-cascader, sl-cascader-panel | The branches open in place, under layout="tree". |
+| `searchValue` | `model<string>` | '' | sl-cascader, sl-cascader-panel | The query, under search. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | sl-cascader, sl-cascader-panel | The control and the surface together. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | sl-cascader | sl-select’s three frames. |
+| `fullWidth` | `boolean` | true | sl-cascader | Whether the control fills its field. |
+| `layout` | `'auto' \| 'columns' \| 'drill' \| 'tree'` | auto | sl-cascader, sl-cascader-panel | auto shows columns while two fit and drills below that. |
+| `selectionMode` | `'single' \| 'multiple'` | single | sl-cascader, sl-cascader-panel | One place, or many. |
+| `selectable` | `'leaf' \| 'any' \| (node) => boolean` | leaf | sl-cascader, sl-cascader-panel | Which nodes a single selection may commit. |
+| `checkedStrategy` | `'all' \| 'parent' \| 'child'` | all | sl-cascader, sl-cascader-panel | Which keys a multiple selection emits. |
+| `expandOn` | `'press' \| 'hover'` | press | sl-cascader, sl-cascader-panel | Whether a rest on a branch shows its level. Hover never commits. |
+| `closeOnSelect` | `boolean` | true | sl-cascader | Whether a single commit closes the popup. |
+| `search` | `boolean` | false | sl-cascader, sl-cascader-panel | A field that finds nodes at any depth. |
+| `clearable` | `boolean` | true | sl-cascader | Whether a clear button stands in the control while it holds a value. |
+| `portal` | `boolean` | true | sl-cascader | Whether the layer is rendered at the end of the document. |
+| `disabled` | `boolean` | false | sl-cascader | Never opens and answers nothing; a disabled form control says the same. |
+| `readOnly` | `boolean` | false | sl-cascader, sl-cascader-panel | Opens and walks, and refuses every change. |
+| `required` | `boolean` | false | sl-cascader | Says aria-required, and the Validator reports required. |
+| `invalid` | `boolean` | false | sl-cascader | Says aria-invalid and paints the frame. |
+| `separator` | `string` | / | sl-cascader | Between two segments of the path. |
+| `hoverDelay` | `number` | 150 | sl-cascader, sl-cascader-panel | How long a rest on a branch waits before its level shows, under expandOn="hover". |
+| `maxColumns` | `number` | 3 | sl-cascader, sl-cascader-panel | The most columns on show at once, whatever the room. |
+| `maxCrumbs` | `number` | 4 | sl-cascader, sl-cascader-panel | The most crumbs before the middle folds. |
+| `name` | `string` | — | sl-cascader | Submits one hidden input per emitted key. |
+| `messages` | `Partial<CascaderMessages>` | — | sl-cascader, sl-cascader-panel | Words laid over the language in force, key by key: placeholder, clear, remove ({label}), summary ({count}), search, searchPlaceholder, root, back ({label}), breadcrumb, empty, noResults ({query}), results ({count}), loading, failed ({label}), retry |
+| `valueTemplate` | `TemplateRef<{ $implicit: T[] }>` | — | sl-cascader | The value’s path as the control prints it. |
+| `provideCascaderDefaults` | `provider` | — | Application | Sets every axis once, in the bootstrap or on a route; the words come from the language in force (provideSlotted). A cascader that states one itself still wins. |
+| `ng-template[slCascaderNode]` | `directive` | — | sl-cascader, sl-cascader-panel | The label of a node, with the item as $implicit and its state as view. |
+| `ControlValueAccessor` | `forms` | — | sl-cascader | formControl, formControlName and ngModel; a disabled control disables the cascader. |
+| `exportAs` | `template reference` | — | sl-cascader, sl-cascader-panel | A template reaches the instance — #places="slCascader" — for focus() and revealValue(). |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChangeRequest` | `ChangeRequest<CascaderValue>` | Before the value moves: pointer, keyboard, select, clear, remove or programmatic. cancel() refuses it. |
+| `openChangeRequest` | `ChangeRequest<boolean>` | Before the popup opens or closes, with the reason. |
+| `pathChangeRequest` | `ChangeRequest<string[]>` | Before a level is shown or left. |
+| `activeKeyChangeRequest` | `ChangeRequest<string \| null>` | Before the cursor moves. |
+| `expandedKeysChangeRequest` | `ChangeRequest<string[]>` | Before a branch opens or closes in place, under layout="tree". |
+| `searchValueChangeRequest` | `ChangeRequest<string>` | Before the query changes. |
+| `loadChildren` | `{ key, signal }` | A level that has not arrived is shown. The signal aborts when the path moves away or the popup closes. |
+| `retry` | `string` | The reader pressed retry on a level that failed. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `layout` | `auto`, `columns`, `drill`, `tree` | `auto` |
+| `selectionMode` | `single`, `multiple` | `single` |
+| `selectable` | `leaf`, `any` | `leaf` |
+| `checkedStrategy` | `all`, `parent`, `child` | `all` |
+| `expandOn` | `press`, `hover` | `press` |
+| `closeOnSelect` | `true`, `false` | `true` |
+| `search` | `true`, `false` | `false` |
+| `clearable` | `true`, `false` | `true` |
+| `portal` | `true`, `false` | `true` |
+| `disabled` | `true`, `false` | `false` |
+| `readOnly` | `true`, `false` | `false` |
+| `required` | `true`, `false` | `false` |
+| `invalid` | `true`, `false` | `false` |
+| `variant` | `outline`, `subtle`, `plain` | `outline` |
+| `fullWidth` | `true`, `false` | `true` |
+
+## Rules
+
+- The control is a combobox whose popup is a tree, in all three layouts: the tree view pattern gives a branch aria-expanded, a level aria-level and a set aria-posinset and aria-setsize, so nothing has to be folded into a name.
+- DOM focus stays on the control — or on the search field, which the combobox pattern moves it into for a dialog popup — and the cursor is aria-activedescendant. The arrows follow the tree popup section of the pattern, mirrored in right-to-left, with one written departure: in columns and drill the vertical arrows stay in the active column.
+- A multiple selection is aria-multiselectable with aria-checked on each node and mixed on a branch partly chosen. A disabled node stays reachable and is never chosen.
+- A level on its way carries aria-busy on its column; a level that failed says so in a status row with a real retry button outside the tree; a query reports its count in a polite status.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-medium`, `--slotted-border-width-thin`, `--slotted-cascader-arrow-color`, `--slotted-cascader-background`, `--slotted-cascader-border-color`, `--slotted-cascader-border-subtle`, `--slotted-cascader-column-measure`, `--slotted-cascader-content-radius`, `--slotted-cascader-content-shadow`, `--slotted-cascader-highlight`, `--slotted-cascader-highlight-active`, `--slotted-cascader-highlight-ring`, `--slotted-cascader-hover-border-color`, `--slotted-cascader-icon-size-min`, `--slotted-cascader-indent`, `--slotted-cascader-invalid-border-color`, `--slotted-cascader-invalid-edge-width`, `--slotted-cascader-mark-inset`, `--slotted-cascader-open-border-color`, `--slotted-cascader-path`, `--slotted-cascader-placeholder-color`, `--slotted-cascader-radius`, `--slotted-cascader-selected-color`, `--slotted-cascader-separator-color`, `--slotted-cascader-surface`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-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-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-shadow-focus-geometry`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-radius-lg`, `--slotted-radius-none`, `--slotted-radius-sm`, `--slotted-radius-xs`, `--slotted-selection-size-lg`, `--slotted-selection-size-md`, `--slotted-selection-size-sm`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-secondary-surface`, `--slotted-z-index-popover`
+
+## Examples
+
+### Columns
+
+One column per level of the path, side by side: the road from the first column to the value reads as one line, and each count ends on one edge.
+
+Excerpt — not a complete module
+
+```html
+<sl-cascader
+  layout="columns"
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+/>
+```
+
+### Drill
+
+One level at a time, with the levels behind it in a breadcrumb. It is what layout="auto" chooses where two columns do not fit.
+
+Excerpt — not a complete module
+
+```html
+<sl-cascader
+  layout="drill"
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+/>
+```
+
+### Tree
+
+Every level in one indented list, branches opening in place. The chevron turns down as its level opens.
+
+Excerpt — not a complete module
+
+```html
+<sl-cascader
+  layout="tree"
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+/>
+```
+
+### Layout from the room
+
+The same cascader in a narrow and a wide container. The narrow one drills; the wide one shows columns, never more than maxColumns, and slides past a level when the path is deeper.
+
+Excerpt — not a complete module
+
+```html
+<sl-cascader
+  layout="auto"
+  [maxColumns]="3"
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+/>
+```
+
+### Search
+
+A query finds a node at any depth and prints the road to it under the label. The navigation path is untouched, and clearing the query shows it again.
+
+Excerpt — not a complete module
+
+```html
+<sl-cascader search [nodes]="places" [getKey]="key" [getLabel]="label" [getChildren]="children" />
+```
+
+### Multiple
+
+A box per node. A branch’s box takes everything below it, a branch partly chosen shows the dash, and checkedStrategy decides whether the branch or its leaves are emitted.
+
+Excerpt — not a complete module
+
+```html
+<sl-cascader
+  selectionMode="multiple"
+  checkedStrategy="parent"
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+/>
+```
+
+### Any level
+
+selectable="any" lets a branch be chosen: pressing it opens its level and chooses it, so a reader can stop at a country or go on to a city.
+
+Excerpt — not a complete module
+
+```html
+<sl-cascader
+  selectable="any"
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+/>
+```
+
+### Levels on demand
+
+A branch whose children have not arrived asks for them as its level is shown, with a signal the family aborts if the reader moves on. The rows wait as the shape of what is coming.
+
+Excerpt — not a complete module
+
+```html
+<sl-cascader
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+  [hasChildren]="hasChildren"
+  [isNodeLoading]="isLoading"
+  (loadChildren)="load($event.key, $event.signal)"
+/>
+```
+
+### The path in the control
+
+A long path gives way in the middle, keeping the place itself, and a value template replaces the segments with anything the consumer draws.
+
+Excerpt — not a complete module
+
+```html
+<sl-cascader
+  separator="›"
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+/>
+```
+
+### Panel
+
+The same tree on the page, without a control or a layer. The tree takes focus itself and walks by the same keys.
+
+Excerpt — not a complete module
+
+```html
+<sl-cascader-panel
+  aria-label="Category"
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+/>
+```
+
+### States
+
+Disabled, read-only, invalid, a disabled node, a level that failed with its retry, and a query with no answer.
+
+Excerpt — not a complete module
+
+```html
+<sl-cascader
+  [disabled]="true"
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+/>
+<sl-cascader
+  [readOnly]="true"
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+/>
+<sl-cascader
+  [invalid]="true"
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+/>
+```
+
+### Keyboard
+
+Down opens; Right enters a level, Left goes back, both mirrored in right-to-left; Up and Down stay in the column; Enter chooses; a letter jumps in the level.
+
+Excerpt — not a complete module
+
+```html
+<sl-cascader
+  aria-label="Location"
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+/>
+```
+
+### In a form
+
+A form control with ControlValueAccessor and a Validator: required, and unresolved for a key the hierarchy no longer holds.
+
+Excerpt — not a complete module
+
+```html
+<sl-cascader
+  aria-label="Delivery area"
+  [required]="true"
+  [nodes]="places"
+  [getKey]="key"
+  [getLabel]="label"
+  [getChildren]="children"
+  [formControl]="area"
+/>
+```