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

package/docs/toolbar.md

@@ -0,0 +1,240 @@
+<!-- index: ./index.md -->
+# toolbar
+
+`data-ui="toolbar"` · Group of controls with arrow-key navigation.
+
+## Import
+
+```ts
+import { SlToolbar, SlToolbarGroup, SlToolbarItem, SlToolbarOverflow, SlToolbarSeparator, SlToolbarSpacer } from '@slotted/angular/toolbar';
+```
+
+Selector: `[slToolbar], [slToolbarGroup], [slToolbarItem], sl-toolbar-overflow, [slToolbarSeparator], [slToolbarSpacer]` · exportAs: `slToolbar, slToolbarGroup, slToolbarItem, slToolbarOverflow, slToolbarSeparator, slToolbarSpacer`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slToolbar aria-label="Formatação">
+  <button slButton variant="ghost">Negrito</button>
+  <button slButton variant="ghost">Itálico</button>
+  <div slToolbarSeparator></div>
+  <button slButton variant="ghost">Link</button>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div[role="toolbar"] carrying slToolbar | yes |
+| `group` | div[role="group"] | no |
+| `separator` | div[role="separator"] | no |
+| `spacer` | div | no |
+| `item` | div carrying slToolbarItem | no |
+| `overflow` | button inside sl-toolbar-overflow, carrying the Menu family’s own trigger | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | slToolbar, provideToolbarDefaults | Which way the bar runs, and therefore which arrow pair moves between the controls. A vertical bar also writes aria-orientation, which the role’s own default makes unnecessary for a horizontal one |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slToolbar, provideToolbarDefaults | The bar’s own inset, gap and separator inset, from the control scales. It never touches the controls inside it: a bar that resized another family’s control would own state it cannot see |
+| `variant` | `'plain' \| 'outline'` | plain | slToolbar, provideToolbarDefaults | Whether the bar paints a ground and a frame. An outline bar pads itself by at least the reach of a focus ring, so a focused control never sits on the bar’s own edge |
+| `overflow` | `'wrap' \| 'scroll' \| 'menu'` | wrap | slToolbar, provideToolbarDefaults | What a bar does with more controls than it has room for. wrap keeps every control on a second row, scroll is one line the arrows reveal, and menu is one line whose units give way from the end into a surface. A menu bar with no sl-toolbar-overflow in it has nothing to give way to, so it scrolls |
+| `overflowChange` | `output<number>` | — | slToolbar | How many units gave way, once per change. There is no two-way binding over the collapsed set: it is a measurement, and a consumer who owned it could assert that a bar fits when the layout says it does not |
+| `slToolbarItemCounterpart, slToolbarGroupCounterpart` | `TemplateRef` | — | slToolbarItem, slToolbarGroup | What the unit becomes in the surface when the bar has no room for it, rendered through NgTemplateOutlet only while it is collapsed. A unit that declares none is pinned — pinning is the absence of a counterpart rather than a second input, so the two can never disagree. It is not called overflow, because that word is the bar’s own axis |
+| `label` | `string \| ((hidden: number) => string)` | counted | sl-toolbar-overflow | The accessible name of the control that holds what did not fit. The default counts — "3 more actions" — because three dots say nothing about how much is behind them; a bar in another language replaces the sentence rather than translating the mark, and an aria-label written on the host wins over both |
+| `align, side, size` | `MenuAlign \| MenuSide \| MenuSize` | from provideMenuDefaults | sl-toolbar-overflow | Where the surface sits against the trigger, and its own measure. Everything else about the layer an application sets once with provideMenuDefaults(): a second configuration surface over the same layer would be two answers to one question |
+| `loop` | `boolean` | true | slToolbar, provideToolbarDefaults | Whether the arrows wrap past the ends of the bar |
+| `aria-label` | `string` | — | slToolbar, slToolbarGroup | The name of the bar, and of each group. The family writes neither: only the page knows what the set of controls is for. aria-labelledby works the same way |
+| `data-toolbar-keys` | `'none' \| 'inline' \| 'block' \| 'all'` | inferred | any item | Which keys an item keeps for itself. A text entry, a select, a slider, a spin button and a contenteditable keep the flow axis without stating anything; this is how a control the kind cannot describe says so |
+| `exportAs` | `slToolbar \| slToolbarGroup \| slToolbarItem \| slToolbarOverflow \| slToolbarSeparator \| slToolbarSpacer` | — | every directive | A template reaches the instance by name: #bar="slToolbar" hands a page the resolved axes, which is what a bar that answers a route needs |
+| `the element you write it on` | `any element` | — | every directive | Five of the six parts are directives on the consumer’s own element, so a bar can be a nav and a rule an hr. The overflow is the exception: it is a component, because it renders both the trigger and the surface, and its host is display: contents so the button it draws is still a child of the bar |
+| `items` | `any focusable descendant` | — | inside slToolbar | Anything focusable is an item, found in the DOM: this library’s slButton, slLink, slCheckbox, slSwitch and slTextField, a menu trigger, or a consumer’s own control. An element that cannot hold focus is not reachable by the arrows |
+| `provideToolbarDefaults()` | `{ orientation, size, variant, overflow, loop }` | — | an injector | The five decisions an application takes once, in the bootstrap file or on a route. A bar that states any of them itself still wins |
+| `collapsedUnits(), counterpart(id)` | `signal<ToolbarCollapsedUnit[]>, TemplateRef \| null` | — | slToolbar | What the parts read: the units that gave way, in the order the bar held them, and what each one becomes. A consumer’s own trigger reads the same signals through #bar="slToolbar" |
+| `fieldset` | `the platform’s own element` | — | around a slToolbar | How a bar is taken out of action. A container cannot disable controls it does not own, and a bar that refused interaction while its controls still looked operable is the defect the state precedence exists to prevent |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `orientation` | `horizontal`, `vertical` | `horizontal` |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `plain`, `outline` | `plain` |
+| `overflow` | `wrap`, `scroll`, `menu` | `wrap` |
+
+## Rules
+
+- The pattern is the WAI-ARIA APG’s Toolbar (w3.org/WAI/ARIA/apg/patterns/toolbar/): the bar is one tab stop, entry lands on the control that last had focus or on the first that is not disabled, the arrows of the flow axis move between the controls and wrap — from row to row when the bar wrapped — and Home and End reach the ends. The cross axis duplicates the pair, which the pattern permits.
+- The APG asks an author to avoid controls whose operation needs the navigation arrows and, failing that, to place one such control last. The bar enforces it instead: a text entry, a select, a slider, a spin button and a contenteditable keep the keys of the flow axis, and focus leaves them on the cross axis or with Tab.
+- A control that announces aria-disabled keeps its place in the ring, which the pattern allows where discoverability of a function is crucial and which is what Button’s focusableWhenDisabled renders. A control carrying the native attribute is skipped, because the platform will not focus it either — including every control inside a disabled fieldset.
+- The bar names itself with the consumer’s aria-label or aria-labelledby, and each group names itself the same way. The pattern uses the role for three or more controls; that is documented rather than enforced, because a role that disappeared when a permission filter removed a button would be a semantic changing behind the author.
+- Under overflow="menu" the control that holds what did not fit is a control of the bar like any other: the arrows, Home and End reach it, and it leaves the ring the moment the bar has room for everything, because a hidden control cannot hold focus. Its name carries the count rather than the mark, and focus is moved onto it before the control under focus is hidden — so a reader who was on the fifth button lands on the control that now holds it rather than on the document body.
+- Nothing in the bar is painted over: every control keeps its own states, its own focus ring and its own contrast. What the bar adds is the boundary between runs — a group, a rule, a spacer — and under forced colours the rule keeps its own paint, because a background flattens to Canvas and would take the boundary with it.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--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-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-radius-md`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-surface-raised`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-toolbar-background`, `--slotted-toolbar-border-color`, `--slotted-toolbar-gap`, `--slotted-toolbar-inset`, `--slotted-toolbar-overflow-active-background`, `--slotted-toolbar-overflow-color`, `--slotted-toolbar-overflow-hover-background`, `--slotted-toolbar-overflow-hover-color`, `--slotted-toolbar-overflow-open-background`, `--slotted-toolbar-separator-color`
+
+## Examples
+
+### Which way the bar runs
+
+A horizontal bar centres its controls and a vertical one stretches them, because a column at each control’s natural width is a ragged edge; the separator and the group boundary turn with it.
+
+Excerpt — not a complete module
+
+```html
+<div slToolbar aria-label="Ferramentas" orientation="vertical">
+  <button slButton variant="ghost">Lápis</button>
+  <button slButton variant="ghost">Pincel</button>
+  <div slToolbarSeparator></div>
+  <button slButton variant="ghost">Borracha</button>
+</div>
+```
+
+### Whether the bar paints a ground
+
+plain is the default and paints nothing: a bar inside a card header is already standing on a surface. outline frames it, and pads itself by at least the reach of a focus ring so the two never meet.
+
+Excerpt — not a complete module
+
+```html
+<div slToolbar aria-label="Sem moldura" variant="plain"></div>
+<div slToolbar aria-label="Com moldura" variant="outline"></div>
+```
+
+### The step the bar sits at
+
+The size moves the bar’s own inset, gap and separator inset and never the controls inside it, which is what lets one bar hold a small icon button beside a medium select.
+
+Excerpt — not a complete module
+
+```html
+<div slToolbar aria-label="Compacta" size="sm">
+  <button slButton size="sm" variant="ghost">Recortar</button>
+</div>
+```
+
+### Runs that belong together
+
+A group carries a name a screen reader announces and a boundary the eye reads, and a rule draws the same boundary the other way — which is what keeps a destructive action off a frequent one.
+
+Excerpt — not a complete module
+
+```html
+<div slToolbar aria-label="Seleção" variant="outline">
+  <div slToolbarGroup aria-label="Alinhamento">
+    <button slButton variant="outline">Início</button>
+    <button slButton variant="outline" pressed>Centro</button>
+  </div>
+  <div slToolbarSeparator></div>
+  <div slToolbarSpacer></div>
+  <button slButton tone="danger">Excluir</button>
+</div>
+```
+
+### The APG table, and where focus lands
+
+Tab enters the bar once and returns to the control that last had focus; the arrows of the flow axis move and wrap, the cross axis duplicates them, and Home and End reach the ends.
+
+Excerpt — not a complete module
+
+```html
+<!-- Every focusable control inside the bar is an item, found in the DOM rather
+     than wrapped in a component of its own — so this library's own families,
+     and a consumer's own control, drop in unwrapped. -->
+<div slToolbar aria-label="Formatação">
+  <button slButton variant="ghost">Negrito</button>
+  <span slCheckbox><input slCheckboxControl type="checkbox" /></span>
+  <a slLink href="/ajuda">Ajuda</a>
+</div>
+```
+
+### An item that keeps the arrows
+
+A text field needs the inline arrows for its caret, so the bar leaves them to it and focus moves out on the cross axis instead — the APG’s advice for the author, written as behaviour.
+
+Excerpt — not a complete module
+
+```html
+<div slToolbar aria-label="Filtro">
+  <button slButton variant="outline">Todos</button>
+  <div slToolbarSpacer></div>
+  <!-- Inferred from the kind of control; data-toolbar-keys states it where the
+       kind cannot say — "none", "inline", "block" or "all". -->
+  <span slTextField><input slTextFieldControl type="search" aria-label="Buscar" /></span>
+</div>
+```
+
+### A bar out of action
+
+A fieldset around the bar disables every control inside it natively, and because a natively disabled control cannot be focused, the arrows skip exactly those — the platform answers it in two lines.
+
+Excerpt — not a complete module
+
+```html
+<fieldset [disabled]="readOnly()">
+  <div slToolbar aria-label="Somente leitura">
+    <button slButton variant="outline">Editar</button>
+    <div slToolbarSeparator></div>
+    <button slButton tone="danger">Excluir</button>
+  </div>
+</fieldset>
+```
+
+### More controls than room
+
+wrap keeps every control visible on a second row, and the arrows wrap from row to row because the item list is linear; scroll keeps the bar to one line and scrolls past its controls rather than squeezing them.
+
+Excerpt — not a complete module
+
+```html
+<div slToolbar aria-label="Muitas ações" overflow="wrap"></div>
+<div slToolbar aria-label="Muitas ações, rolando" overflow="scroll"></div>
+```
+
+### What is left over, behind one control
+
+The bar measures its own width and gives way from the end, so what holds it gives it a width that does not come from the bar’s content: a bar as wide as what it shows is the trigger alone after a fold, and never sees the room come back. What stays visible is what has nowhere to go: an item that declares no counterpart cannot be hidden, which is how the primary action survives without a priority ranking it above the others. The counterpart is an ng-template, so a menu item that is never reached builds nothing.
+
+Excerpt — not a complete module
+
+```html
+<div slToolbar aria-label="Documento" overflow="menu">
+  <!-- No counterpart, so it is pinned: the primary action stays visible. -->
+  <div slToolbarItem>
+    <button slButton tone="accent">Publicar</button>
+  </div>
+  <div slToolbarSeparator></div>
+  <div slToolbarItem [slToolbarItemCounterpart]="duplicate">
+    <button slButton variant="ghost">Duplicar</button>
+  </div>
+  <div slToolbarItem [slToolbarItemCounterpart]="archive">
+    <button slButton variant="ghost">Arquivar</button>
+  </div>
+  <sl-toolbar-overflow />
+</div>
+
+<ng-template #duplicate><button slMenuItem>Duplicar</button></ng-template>
+<ng-template #archive><button slMenuItem>Arquivar</button></ng-template>
+```
+
+### Setting it once, and standing beside other families
+
+The provider carries the five decisions an application takes once, and the bar is what belongs in a tab list’s actions slot — one tab stop for however many actions the page puts there.
+
+Excerpt — not a complete module
+
+```ts
+// One decision for every bar in the application, in the bootstrap file.
+bootstrapApplication(App, {
+  providers: [provideToolbarDefaults({ size: 'sm', variant: 'outline' })],
+});
+
+// And in a template, the actions slot of a tab list is where a bar goes:
+// <div slTabActions><div slToolbar aria-label="Ações">…</div></div>
+```