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

package/dist/docs/stepper.json

@@ -0,0 +1,456 @@
+{
+  "family": "stepper",
+  "ui": "stepper",
+  "binding": "react",
+  "catalog": {
+    "group": "Navigation",
+    "summary": "Shows progress through ordered steps."
+  },
+  "axes": {
+    "orientation": [
+      "horizontal",
+      "vertical"
+    ],
+    "labelPlacement": [
+      "end",
+      "bottom"
+    ],
+    "navigation": [
+      "button",
+      "link",
+      "none"
+    ]
+  },
+  "members": {
+    "stepper": {
+      "nativeElement": "div",
+      "defaults": {
+        "defaultStep": 0,
+        "orientation": "horizontal",
+        "labelPlacement": "end",
+        "navigation": "button",
+        "linear": false,
+        "autoComplete": false,
+        "disabled": false,
+        "loading": false,
+        "invalid": false
+      },
+      "capabilities": [
+        "current",
+        "orientation",
+        "placement",
+        "disabled",
+        "loading",
+        "invalid",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "loading",
+        "invalid",
+        "current",
+        "complete"
+      ],
+      "parts": [
+        "root",
+        "list",
+        "item",
+        "trigger",
+        "marker",
+        "label",
+        "description",
+        "status",
+        "separator",
+        "panel"
+      ]
+    }
+  },
+  "docs": {
+    "stepper": {
+      "imports": {
+        "source": "import {\n  Stepper,\n  StepperDefaultsProvider,\n  StepperList,\n  StepperPanel,\n  StepperStep,\n  useStepper,\n} from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div",
+          "required": true,
+          "purpose": "Owns the step, the orientation, the navigation mode and the container query that reflows the row. Carries data-ui=\"stepper\" and the three axes as data attributes. It is not a landmark: a stepper inside a page whose navigation is elsewhere would be a second one."
+        },
+        {
+          "part": "list",
+          "element": "ol",
+          "required": true,
+          "purpose": "The ordered list, which is what carries the sequence and the set size without a single ARIA attribute. It holds the name of the flow, and it is where the arrow keys are handled — only the list knows every header."
+        },
+        {
+          "part": "item",
+          "element": "li",
+          "required": true,
+          "purpose": "One step, and the element every state is written on: data-current, data-complete, data-invalid, data-disabled and data-loading. It renders the connector after itself, and never after the last step."
+        },
+        {
+          "part": "trigger",
+          "element": "button, a or span",
+          "required": true,
+          "purpose": "The step header, in whichever element navigation decided. It carries aria-current=\"step\" when it is the step the reader is on, and aria-disabled when a linear flow has not opened it."
+        },
+        {
+          "part": "marker",
+          "element": "span",
+          "required": true,
+          "purpose": "The circle. It holds the step number, gives way to a check when the step is complete and to a cross when it failed, and is hidden from assistive technology because the status part says the same thing in words."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": true,
+          "purpose": "The step's name. The description renders inside it rather than beside it, so the marker sits against the whole text block and not against its first line."
+        },
+        {
+          "part": "description",
+          "element": "span",
+          "required": false,
+          "purpose": "The second line, nested inside label. Absent unless the step states one, and it wraps with the name rather than pushing the marker."
+        },
+        {
+          "part": "status",
+          "element": "span",
+          "required": true,
+          "purpose": "The visually hidden run that makes a header announce \"Cart, Step 2 of 4, current\" instead of \"2\". It carries the position, the status and, where they apply, the words for loading and unavailable."
+        },
+        {
+          "part": "separator",
+          "element": "span",
+          "required": false,
+          "purpose": "The connector to the next step, aria-hidden and never drawn after the last. It carries data-complete for a step the reader has walked past, which is distance travelled rather than work completed."
+        },
+        {
+          "part": "panel",
+          "element": "div",
+          "required": false,
+          "purpose": "The content of the step it is written inside, rendered only while that step is current. A group labelled by its own header rather than a tabpanel, and focusable so a consumer moving focus after a change has somewhere to put it."
+        }
+      ],
+      "api": [
+        {
+          "name": "step",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "Stepper",
+          "description": "Present means controlled, for the life of the component. Zero-based."
+        },
+        {
+          "name": "defaultStep",
+          "type": "number",
+          "defaultValue": "0",
+          "appliesTo": "Stepper",
+          "description": "What an uncontrolled stepper starts from, read once, and where reset() returns to"
+        },
+        {
+          "name": "orientation",
+          "type": "'horizontal' | 'vertical'",
+          "defaultValue": "horizontal",
+          "appliesTo": "Stepper",
+          "description": "A row of equal columns, or a column. A horizontal flow turns vertical below thirty rems of its own inline size."
+        },
+        {
+          "name": "labelPlacement",
+          "type": "'end' | 'bottom'",
+          "defaultValue": "end",
+          "appliesTo": "Stepper",
+          "description": "The name beside the marker, or under it"
+        },
+        {
+          "name": "navigation",
+          "type": "'button' | 'link' | 'none'",
+          "defaultValue": "button",
+          "appliesTo": "Stepper",
+          "description": "What a header is. none renders a span and is a read-only progress indicator."
+        },
+        {
+          "name": "linear",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Stepper",
+          "description": "Requires every earlier step to be complete before a later one is reachable"
+        },
+        {
+          "name": "autoComplete",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Stepper",
+          "description": "Whether reaching a later step means the earlier ones are finished. Off, because walking past a step is not completing it."
+        },
+        {
+          "name": "messages",
+          "type": "PartialMessages<StepperMessages>",
+          "defaultValue": "—",
+          "appliesTo": "Stepper",
+          "description": "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"
+        },
+        {
+          "name": "complete",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "Stepper.Step",
+          "description": "The consumer says the work on this step is done. Only the consumer knows."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Stepper.Step",
+          "description": "The work on this step failed. Outranks complete, and the marker draws a cross."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Stepper.Step",
+          "description": "Takes the header out of reach, in a linear flow or outside one"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Stepper.Step",
+          "description": "The step is waiting on something; the header stops answering and announces it"
+        },
+        {
+          "name": "description",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Stepper.Step",
+          "description": "The second line, rendered inside label"
+        },
+        {
+          "name": "href",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "Stepper.Step",
+          "description": "The destination, when navigation is link"
+        },
+        {
+          "name": "marker",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Stepper.Step",
+          "description": "What the circle shows in place of the step number"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Substitutes the rendered element. Every data attribute is handed to it, so a router link keeps them."
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "defaultValue": "—",
+          "appliesTo": "every part",
+          "description": "Reaches the element, and focus() with it"
+        },
+        {
+          "name": "useStepper()",
+          "type": "() => StepperContextValue",
+          "defaultValue": "—",
+          "appliesTo": "inside a Stepper",
+          "description": "step, count, percent, canGoNext, canGoPrevious, next, previous, goToStep and reset — the move a consumer cannot express as a prop, for a button of their own"
+        },
+        {
+          "name": "StepperDefaultsProvider",
+          "type": "labelPlacement | linear | navigation | orientation",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets those four once for everything below it; a prop on the stepper still wins"
+        }
+      ],
+      "events": [
+        {
+          "name": "onStepChange",
+          "payload": "(step: number, request: ChangeRequest<number>)",
+          "when": "Before the step moves. The request carries the step it replaces, the reason — pointer, keyboard or programmatic — and the originating event. Cancelling it commits nothing, and that is how a consumer refuses a move: this family ships no isStepValid, because the request already says the same thing at the same moment."
+        }
+      ],
+      "accessibility": [
+        "The family refuses role=\"tablist\" and role=\"tab\", which Angular Material gives a horizontal stepper. Section 7 of the feature guide forbids it in the Tabs entry itself: tabs are for peer views in one context, not for the steps of a process, and a tab list would tell a reader the panels may be taken in any order. What replaces it is an ol and li for the sequence and the set size, a name on the list, and a status in words inside every header.",
+        "The current header carries aria-current=\"step\", which is the value the ARIA specification names for a link inside a step indicator for a step-based process. The item beside it also carries data-current, because the marker, the label and the connector are all 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 place in the tab sequence. A reader can find out the step exists and that it is not yet available, which a removed tab stop would not tell them.",
+        "Each header holds a visually hidden status, so what a reader hears is \"Cart, Step 2 of 4, current\" rather than \"2\". The marker is aria-hidden for the same reason: the number is the picture, and the words are the announcement.",
+        "A panel is a group labelled by its own header, related through aria-controls and aria-labelledby without either claiming to be a tab, and it takes tabindex=\"-1\" so a consumer moving focus after a step change has somewhere to put it.",
+        "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 — that is the model a tablist has — so a step a linear flow has not opened is still one a reader is allowed to find.",
+        "No status depends on colour: a complete step fills and draws a check, a failed one fills and draws a cross, the current one is a ring, and a pending one is an outline whose ring holds the 3:1 a non-text element needs."
+      ]
+    }
+  },
+  "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": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "Every axis on one flow, driven by the controls below the canvas. Switch navigation to none and the same markup becomes a read-only progress indicator.",
+      "language": "tsx",
+      "source": "<Stepper defaultStep={1}>\n  <StepperList>\n    <StepperStep label=\"Cart\" complete />\n    <StepperStep label=\"Address\" />\n    <StepperStep label=\"Payment\" />\n  </StepperList>\n</Stepper>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "orientation",
+      "title": "Which way the flow runs",
+      "note": "Horizontal is a row of equal columns, so five steps divide the width evenly however long their names are. Vertical runs the connector down the marker centre and leaves room for a panel under each step.",
+      "language": "tsx",
+      "source": "<Stepper orientation=\"vertical\">\n  <StepperList>{steps}</StepperList>\n</Stepper>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "statuses",
+      "title": "The five things a step can be",
+      "note": "Each status is a fill and a shape, never a colour alone: an outline for pending, a ring for current, a filled disc with a check for complete, a red disc with a cross for a failure, and a grey outline for a step the flow closed.",
+      "language": "tsx",
+      "source": "<StepperStep label=\"Cart\" complete />;\n<StepperStep label=\"Address\" invalid />;\n<StepperStep label=\"Review\" disabled />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "linear",
+      "title": "A flow that must be taken in order",
+      "note": "With linear, a header is reachable only once every step before it is complete. The rest keep their place in the tab sequence and say aria-disabled, so a reader can find the step and learn it is not yet open.",
+      "language": "tsx",
+      "source": "<Stepper linear onStepChange={(step, request) => valid || request.cancel()}>\n  <StepperList>{steps}</StepperList>\n</Stepper>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "navigation",
+      "title": "What a header is",
+      "note": "button is a control the reader presses, link is a destination with its own URL, and none is a span nothing can press — one family covering both an interactive stepper and a read-only progress indicator.",
+      "language": "tsx",
+      "source": "<Stepper navigation=\"link\">\n  <StepperList>\n    <StepperStep href=\"/checkout/cart\" label=\"Cart\" />\n  </StepperList>\n</Stepper>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "placement",
+      "title": "Where the label sits",
+      "note": "end puts the name beside the marker and leaves the connector whatever the name does not take; bottom centres the marker over its own column, which is what a row of five long names needs.",
+      "language": "tsx",
+      "source": "<Stepper labelPlacement=\"bottom\">\n  <StepperList>{steps}</StepperList>\n</Stepper>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "panels",
+      "title": "The content of a step",
+      "note": "A panel renders only while its own step is current, so the flow shows one at a time. It is a group labelled by its header, and the button that advances is yours — this family ships none.",
+      "language": "tsx",
+      "source": "<StepperStep label=\"Address\">\n  <StepperPanel>\n    <AddressForm />\n  </StepperPanel>\n</StepperStep>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "compact",
+      "title": "A row with no room to be one",
+      "note": "Below thirty rems of its own inline size a horizontal stepper becomes a column. Drag the stage narrower and watch the connectors turn with it, rather than five names shrinking to two characters each.",
+      "language": "tsx",
+      "source": "// The reflow is a container query on the family itself, so a stepper in a\n// narrow panel becomes a column while the same one on a full page does not.\n<Stepper orientation=\"horizontal\">\n  <StepperList>{steps}</StepperList>\n</Stepper>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Names the flow did not choose",
+      "note": "Six steps, a German compound and a phrase of four words. The label wraps inside its own column, the marker never does, and the connector takes whatever is left.",
+      "language": "tsx",
+      "source": "<StepperStep description=\"Compiled in 42 seconds\" label=\"Zahlungsabwicklungseinstellungen\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition",
+      "note": "useStepper() hands you the move and whether it is available, so the button that advances is your own — and StepperDefaultsProvider decides the orientation, the placement and the mode for a whole application.",
+      "language": "tsx",
+      "source": "const stepper = useStepper();\n\n<Button disabled={!stepper.canGoNext} onClick={() => stepper.next()}>\n  Continue\n</Button>;\n\n<StepperDefaultsProvider labelPlacement=\"bottom\" orientation=\"vertical\">\n  <App />\n</StepperDefaultsProvider>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "Keyboard and announcement",
+      "note": "Tab reaches every header; the arrows reach exactly the same ones, following the reading direction and wrapping; Home and End go to the ends; Enter and Space move to a step the flow has opened.",
+      "language": "tsx",
+      "source": "// \"Cart, Step 1 of 4, completed\" — the position and the status in words,\n// because the number in the circle is hidden from assistive technology.\n<Stepper defaultStep={1} messages={{ label: 'Checkout' }}>\n  <StepperList>{steps}</StepperList>\n</Stepper>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}