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

package/docs/stepper.md

@@ -0,0 +1,250 @@
+<!-- index: ./index.md -->
+# stepper
+
+`data-ui="stepper"` · Shows progress through ordered steps.
+
+## Import
+
+```ts
+import {
+  SlStepper,
+  SlStepperList,
+  SlStepperNext,
+  SlStepperPanel,
+  SlStepperPrevious,
+  SlStepperStep,
+  provideStepperDefaults,
+} from '@slotted/angular/stepper';
+```
+
+Selector: `[slStepper], ol[slStepperList], li[slStepperStep], [slStepperPanel], button[slStepperNext], button[slStepperPrevious]` · exportAs: `slStepper, slStepperList, slStepperStep, slStepperPanel, slStepperNext, slStepperPrevious`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slStepper [defaultStep]="1" label="Checkout">
+  <ol slStepperList>
+    <li slStepperStep label="Cart" [complete]="true"></li>
+    <li slStepperStep label="Address"></li>
+    <li slStepperStep label="Payment"></li>
+    <li slStepperStep label="Review"></li>
+  </ol>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div | yes |
+| `list` | ol | yes |
+| `item` | li | yes |
+| `trigger` | button, a or span | yes |
+| `marker` | span | yes |
+| `label` | span | yes |
+| `description` | span | no |
+| `status` | span | yes |
+| `separator` | span | no |
+| `panel` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `step` | `number` | — | slStepper | Present means controlled, for the life of the component. The family then only asks to move. |
+| `defaultStep` | `number` | 0 | slStepper | What an uncontrolled stepper starts from, read once, and where reset() returns to |
+| `orientation` | `'horizontal' \| 'vertical'` | horizontal | slStepper | Which way the flow runs. A horizontal one still becomes a column below its own breakpoint. |
+| `labelPlacement` | `'end' \| 'bottom'` | end | slStepper | The name beside the marker, or under it |
+| `navigation` | `'button' \| 'link' \| 'none'` | button | slStepper | What a header is. none renders a span, which is a read-only progress indicator. |
+| `linear` | `boolean` | false | slStepper | Requires every earlier step to be complete before a later one can be reached |
+| `autoComplete` | `boolean` | false | slStepper | Treats every step before the current one as complete. Off, because walking past a step is not finishing it. |
+| `messages` | `PartialMessages<StepperMessages>` | — | slStepper | Words laid over the language in force, key by key: the name of the sequence announced on the list (label), the position, and the five statuses a step announces |
+| `complete` | `boolean` | — | li[slStepperStep] | Whether the consumer says the work on this step is done. Unstated defers to autoComplete. |
+| `disabled` | `boolean` | false | li[slStepperStep] | Takes the header out of reach, in a linear flow or outside one. It keeps its tab stop. |
+| `loading` | `boolean` | false | li[slStepperStep] | The step is waiting on something: the header stops answering and the status says so |
+| `invalid` | `boolean` | false | li[slStepperStep] | The work on this step failed. It outranks complete in the marker and in the announcement. |
+| `description` | `string` | — | li[slStepperStep] | The second line under the step’s name |
+| `href` | `string` | — | li[slStepperStep] | The destination, used only when navigation is link |
+| `provideStepperDefaults` | `labelPlacement \| linear \| navigation \| orientation` | — | Application | Sets those six once for the whole injector; an input on the stepper still wins |
+| `exportAs="slStepper"` | `template reference` | — | Template | Reaches the instance: step(), count(), percent(), canGoNext(), goToStep(), next(), previous() and reset() |
+| `slStepperNext, slStepperPrevious` | `directive` | — | The consumer’s button | Moving one step is a handler on a button you styled, the shape matStepperNext already taught Angular consumers. The directive disables the button at each bound and never paints it. |
+| `ng-content` | `projection` | — | li[slStepperStep] | Whatever a step should carry beyond its header — a panel, a form, a summary — projected after the trigger and before the connector |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `stepChange` | `ChangeRequest<number>` | Before the step moves. The request carries the value it replaces, the reason — pointer, keyboard or programmatic — and the originating event. Calling request.cancel() commits nothing, which is how a consumer refuses a move and the reason this family ships no isStepValid and no onStepInvalid. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `orientation` | `horizontal`, `vertical` | `horizontal` |
+| `labelPlacement` | `end`, `bottom` | `end` |
+| `navigation` | `button`, `link`, `none` | `button` |
+
+## Rules
+
+- The family refuses role="tablist". Angular Material gives a horizontal stepper that role and section 7 of docs/component-features.md forbids it in the Tabs entry itself: tabs are for peer views in one context, not for the steps of a process. What replaces it is ol and li for the sequence and the set size, a name on the list, and a status inside every header — the cost is that a screen reader will not announce "tab 2 of 5" or offer tab-specific navigation.
+- The current step carries aria-current="step" on its trigger, which is the value the ARIA specification names for a link inside a step indicator. The item mirrors it as data-current, because the marker, the label and the connector are styled from the item and none of them is the trigger.
+- A step a linear flow has not opened carries aria-disabled rather than disabled, so it keeps its tab stop: a reader can find out the step exists and that it is not yet available, instead of finding nothing at all.
+- Every header carries a visually hidden status, so what a reader hears is "Cart, Step 2 of 4, current" rather than "2". The marker itself is aria-hidden, because it would otherwise announce the number twice, and the status is prefixed with a comma because nothing separates two elements’ text when a name is computed.
+- A panel is a group labelled by its own trigger and given tabindex="-1", so a consumer who moves focus after a step change has somewhere to put it. It is not a tabpanel, for the same reason the root is not a tablist.
+- The arrows reach every header, exactly where Tab reaches — they were added on top of the tab sequence rather than replacing it with a roving tab stop, and they follow the reading direction, so ArrowRight moves to the previous step in a right-to-left document. Home and End go to the ends, and the block arrows answer only a vertical flow.
+- No status depends on colour alone: a complete step fills its disc and shows a check, a failed one fills and shows a cross, the current one is a ring and a pending one an outline. Section 7 of the feature guide asks for exactly that.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-control-border-color`, `--slotted-control-font-size-md`, `--slotted-control-gap-md`, `--slotted-control-height-md`, `--slotted-control-icon-size-md`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-focus-ring-color`, `--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-sm`, `--slotted-radius-full`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-8`, `--slotted-stepper-color`, `--slotted-stepper-color-muted`, `--slotted-stepper-column-inset`, `--slotted-stepper-connector-color`, `--slotted-stepper-connector-color-complete`, `--slotted-stepper-connector-gap`, `--slotted-stepper-connector-thickness`, `--slotted-stepper-description-font-size`, `--slotted-stepper-description-gap`, `--slotted-stepper-font-family`, `--slotted-stepper-font-size`, `--slotted-stepper-gap`, `--slotted-stepper-glyph-size`, `--slotted-stepper-label-color-invalid`, `--slotted-stepper-label-gap`, `--slotted-stepper-label-weight`, `--slotted-stepper-line-height`, `--slotted-stepper-marker-border`, `--slotted-stepper-marker-border-current`, `--slotted-stepper-marker-color-complete`, `--slotted-stepper-marker-color-current`, `--slotted-stepper-marker-color-invalid`, `--slotted-stepper-marker-press-strength`, `--slotted-stepper-marker-size`, `--slotted-stepper-marker-surface`, `--slotted-stepper-marker-surface-complete`, `--slotted-stepper-marker-surface-invalid`, `--slotted-stepper-marker-weight`, `--slotted-stepper-panel-gap`, `--slotted-stepper-radius`, `--slotted-stepper-step-gap`, `--slotted-stepper-track-gap`, `--slotted-stepper-track-min`, `--slotted-stepper-underline-offset`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-text`, `--slotted-tone-danger-on-solid`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-text`
+
+## Examples
+
+### Which way the flow runs
+
+Horizontal divides the width into equal columns so five markers line up however long their labels are; vertical runs the connector down the marker’s own centre line.
+
+Excerpt — not a complete module
+
+```html
+<div slStepper orientation="horizontal">
+  <ol slStepperList>
+    …
+  </ol>
+</div>
+
+<div slStepper orientation="vertical">
+  <ol slStepperList>
+    …
+  </ol>
+</div>
+```
+
+### The four statuses, and the fifth that is not one
+
+Each is a fill and an edge rather than a colour alone: an outline for pending, a ring for current, a filled disc with a check for complete, a filled disc with a cross for a failure.
+
+Excerpt — not a complete module
+
+```html
+<li slStepperStep label="Complete" [complete]="true"></li>
+<li slStepperStep label="Failed" invalid></li>
+<li slStepperStep label="Current"></li>
+<li slStepperStep label="Pending"></li>
+<li slStepperStep label="Closed" [disabled]="true"></li>
+```
+
+### A flow that has to be taken in order
+
+linear reaches backwards freely and forwards only as far as the first step whose predecessors are complete. Everything further carries aria-disabled and stays reachable by Tab.
+
+Excerpt — not a complete module
+
+```html
+<div slStepper linear (stepChange)="onStepChange($event)">
+  <ol slStepperList>
+    …
+  </ol>
+</div>
+```
+
+### What a header is
+
+A button moves the step, a link carries a destination of its own, and none is a read-only progress indicator — one family covering what the field ships as two components.
+
+Excerpt — not a complete module
+
+```html
+<div slStepper navigation="button">…</div>
+<div slStepper navigation="link">
+  <ol slStepperList>
+    <li slStepperStep label="Cart" href="/cart"></li>
+  </ol>
+</div>
+<div slStepper navigation="none">…</div>
+```
+
+### Where the label sits
+
+end puts the name beside the marker and gives the connector whatever the label leaves; bottom centres the marker over its own label, which is what a row of five names needs.
+
+Excerpt — not a complete module
+
+```html
+<div slStepper labelPlacement="end">…</div>
+<div slStepper labelPlacement="bottom">…</div>
+```
+
+### The content of the step you are on
+
+A panel is a group labelled by its own header, shown only while that step is current, and the two buttons that move it are the consumer’s own with a directive on them.
+
+Excerpt — not a complete module
+
+```html
+<li slStepperStep label="Recipient">
+  <div slStepperPanel>The account number is being checked.</div>
+</li>
+
+<button slStepperPrevious type="button">Back</button>
+<button slStepperNext type="button">Continue</button>
+```
+
+### A row that runs out of width
+
+Below thirty rems of its own inline size a horizontal flow becomes a column, because five labels at 320 pixels are five columns two characters wide. Drag the stage edge to cross it.
+
+Excerpt — not a complete module
+
+```css
+/* The family declares its own container, so a stepper in a narrow panel
+   reflows while the same stepper on a full page does not. */
+[data-ui='stepper'] {
+  container-name: slotted-stepper;
+  container-type: inline-size;
+}
+```
+
+### Names the flow did not choose
+
+Six steps, a forty-character German compound and a second line under each name. The label wraps inside its own column and the markers stay on one line.
+
+Excerpt — not a complete module
+
+```html
+<li
+  slStepperStep
+  label="Zahlungsabwicklungseinstellungen"
+  description="Zuletzt geprüft am 14. August"
+></li>
+```
+
+### Composition
+
+provideStepperDefaults decides for a whole injector, exportAs reaches the instance from a template, and the two advance directives sit on buttons the consumer styled themselves.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideStepperDefaults({ labelPlacement: 'bottom', linear: true })],
+});
+```
+
+### Keyboard and announcement
+
+Tab reaches every header, the arrows reach exactly the same ones, Home and End go to the ends, and Enter or Space moves to the focused step when the flow allows it.
+
+Excerpt — not a complete module
+
+```html
+<!-- "Cart, Step 1 of 4, completed" — the marker is hidden and the
+     status part says the position and the state in words. -->
+<div slStepper [messages]="{ label: 'Checkout' }" [defaultStep]="1">
+  <ol slStepperList>
+    …
+  </ol>
+</div>
+```