@ahrowe/ui 0.43.0 → 0.45.0

package/docs/Stepper.md

@@ -4,17 +4,19 @@
 
 **Keywords:** wizard steps, progress steps
 
-**Import:** `import { Stepper } from '@ahrowe/ui'`
-**Types:** `import type { StepperStep, StepperProps } from '@ahrowe/ui'`
+**Import:** `import { Stepper, StepperOrientation, StepperStyleType, StepperCollapse, StepperLabelPlacement, ThemeColor } from '@ahrowe/ui'`
+**Types:** `import type { StepperStep, StepperProps, StepperLabels } from '@ahrowe/ui'`
 
 **Enums:**
-- `StepperAlignment`: `Horizontal` (default) | `Vertical`
-- `StepperStyleType`: `Default` (filled numbered markers) | `Outlined` (numbered markers that stay ringed when completed) | `Dots` (minimal dots, no numbers)
+- `StepperOrientation`: `Horizontal` (default) | `Vertical`
+- `StepperStyleType`: `Filled` (default: completed markers filled solid) | `Outlined` (completed markers stay ringed, with a check in the colour) | `Dots` (minimal dots, no numbers)
 - `StepperCollapse`: `None` (default) | `ActiveOnly` | `Completed`
 - `StepperLabelPlacement`: `Top` | `Bottom` | `Left` | `Right`
 
+**Colours:** any `color`: a `ThemeColor` (default `Primary`) or any CSS colour, see [ThemeColor.md](ThemeColor.md). It paints the current and completed markers and the connectors between them. Upcoming steps are drawn in the theme's `--border-color` and `--text-dark`, and a step with `error` in its `--error-color`.
+
 ```tsx
-import { Stepper, StepperAlignment, StepperStyleType, StepperCollapse } from '@ahrowe/ui';
+import { Stepper, StepperOrientation, StepperStyleType, StepperCollapse, ThemeColor } from '@ahrowe/ui';
 import { faUser, faCreditCard } from '@fortawesome/free-solid-svg-icons';
 
 const steps = [
@@ -26,15 +28,16 @@ const steps = [
 // Horizontal (default)
 <Stepper steps={steps} currentStep={1} />
 
-// Style presets
+// Style presets and colour
 <Stepper steps={steps} currentStep={1} styleType={StepperStyleType.Outlined} />
 <Stepper steps={steps} currentStep={1} styleType={StepperStyleType.Dots} hideLabels />
+<Stepper steps={steps} currentStep={1} color={ThemeColor.Success} />
 
 // Vertical, clickable
 <Stepper
   steps={steps}
   currentStep={currentStep}
-  alignment={StepperAlignment.Vertical}
+  orientation={StepperOrientation.Vertical}
   onStepClicked={(stepIndex) => setCurrentStep(stepIndex)}
 />
 
@@ -50,7 +53,7 @@ const steps = [
 
 // Vertical wizard with collapsible bodies (only the active step's body is open)
 <Stepper
-  alignment={StepperAlignment.Vertical}
+  orientation={StepperOrientation.Vertical}
   collapse={StepperCollapse.ActiveOnly}
   currentStep={step}
   onStepClicked={setStep}
@@ -70,8 +73,8 @@ const steps = [
 | `description` | `ReactNode` | Secondary line under the label |
 | `content` | `ReactNode` | Collapsible body under the label (vertical only) |
 | `icon` | `IconDefinition \| ReactElement` | Icon in the marker, replacing the number — FontAwesome icon or any React element |
-| `error` | `boolean` | Recolours the marker with `--stepper-error-color`; suppresses the checkmark |
-| `optional` | `boolean \| ReactNode` | `true` → an "Optional" hint; a node → custom hint text |
+| `error` | `boolean` | Draws the marker in `--error-color`, suppresses the checkmark, and tells screen readers |
+| `optional` | `boolean \| ReactNode` | `true` → the `optional` label as a hint; a node → custom hint text |
 | `disabled` | `boolean` | Never clickable, dimmed |
 
 **Key props:**
@@ -79,16 +82,23 @@ const steps = [
 | Prop | Type | Description |
 |------|------|-------------|
 | `steps` | `StepperStep[]` | The steps to render |
-| `currentStep` | `number` | Zero-based active step index |
-| `alignment` | `StepperAlignment \| 'horizontal' \| 'vertical'` | Layout direction (default `Horizontal`) |
-| `styleType` | `StepperStyleType` | Marker/connector preset (default `Default`) |
+| `currentStep` | `number` | Zero-based index of the current step. `steps.length` marks every step completed |
+| `orientation` | `StepperOrientation` | Direction the steps run in (default `Horizontal`) |
+| `styleType` | `StepperStyleType` | How the markers are drawn (default `Filled`) |
+| `color` | `ColorValue` | A `ThemeColor` (default `Primary`) or any CSS colour |
 | `collapse` | `StepperCollapse` | Which `content` bodies are expanded. Vertical only (default `None`) |
 | `labelPlacement` | `StepperLabelPlacement` | Label position; default `Bottom` (horizontal) / `Right` (vertical). An out-of-orientation value falls back to that default |
-| `onStepClicked` | `(stepIndex: number) => void` | Navigate on step click. Linear: only completed steps are clickable; with `nonLinear`, any enabled step except the current one |
+| `onStepClicked` | `(stepIndex: number) => void` | Navigate on step click. Linear: only completed steps are clickable; with `nonLinear`, any enabled step except the current one. A clickable step is a `<button>`, and so is the current one, `aria-disabled`, so focus stays on a step after activating it |
 | `nonLinear` | `boolean` | Allow clicking any step, not just completed ones |
-| `hideLabels` | `boolean` | Hide labels, descriptions, and (vertical) content |
+| `hideLabels` | `boolean` | Hide each step's label, description and hint visually. Screen readers still read them, and vertical `content` still shows |
+
+**Layout:** a horizontal stepper gives every step an equal share of its width, with the marker centred in it and the label wrapping within it, so a long label never reaches past the stepper or into its neighbour. The connectors run from marker to marker.
+
+**Collapse (vertical `content`):** `None` keeps every body open; `ActiveOnly` opens just the current step's body (classic vertical wizard); `Completed` collapses completed bodies while keeping the current and upcoming ones open. A collapsed body is `inert`, so nothing in it can be focused. Bodies animate their height and respect `prefers-reduced-motion`. Horizontal steppers don't render inline `content` and ignore `collapse`.
+
+**Accessibility:** the stepper is an ordered list, the current step carries `aria-current="step"`, and every other step's status is read out from the `completed`, `notCompleted` and `error` labels. The marker is hidden from screen readers: the list gives the position.
 
-**Collapse (vertical `content`):** `None` keeps every body open; `ActiveOnly` opens just the current step's body (classic vertical wizard); `Completed` collapses completed bodies while keeping the current and upcoming ones open. Bodies animate their height and respect `prefers-reduced-motion`. Horizontal steppers don't render inline `content` and ignore `collapse`.
+**Labels:** `optional` `completed` `notCompleted` `error` — the text this component renders of its own; the last three are for screen readers only. Pass `labels` to override any of them, on the component or app-wide through `ConfigProvider`; they merge per key. Type: `StepperLabels`.
 
 **Theming:** these are theme variables (typed on `ThemeVariables`). Set them theme-wide via `ThemeProvider`'s `variables`, or per instance via `style`, without fighting specificity. Each falls back to a built-in default when unset:
 
@@ -96,23 +106,16 @@ const steps = [
 |----------|---------------|
 | `--stepper-marker-size` | `40px` |
 | `--stepper-marker-radius` | `var(--default-border-radius)` |
-| `--stepper-idle-color` | `var(--primary-lighter)` |
-| `--stepper-active-color` | `var(--primary-color)` |
-| `--stepper-done-color` | `var(--primary-color)` |
-| `--stepper-error-color` | `var(--error-color)` |
-| `--stepper-connector-color` | `var(--primary-color)` |
 | `--stepper-connector-thickness` (completed connectors) | `3px` |
 | `--stepper-connector-idle-thickness` (not-yet-reached connectors) | `1px` |
 | `--stepper-gap` | `12px` |
-| `--stepper-text-on-marker` | `var(--text-on-primary)` |
 
 ```tsx
-// Theme-wide, via ThemeProvider: circular pink markers, thicker connectors
+// Theme-wide, via ThemeProvider: circular markers, thicker connectors
 const theme: Theme = {
   id: 'brand',
   variables: {
     '--stepper-marker-radius': '50%',
-    '--stepper-active-color': '#e91e63',
     '--stepper-connector-thickness': '4px',
   },
 };
@@ -121,12 +124,37 @@ const theme: Theme = {
 <Stepper
   steps={steps}
   currentStep={1}
-  style={{
-    '--stepper-marker-radius': '50%',
-    '--stepper-active-color': '#e91e63',
-    '--stepper-connector-thickness': '4px',
-  } as React.CSSProperties}
+  style={{ '--stepper-marker-radius': '50%' } as React.CSSProperties}
 />
 ```
 
 **Slots:** `root` `entry` `entryNumber` `entryLabel` `connector` `description` `content` `optional` `icon`
+
+## Migration from `alignment`, `StepperStyleType.Default` and the colour variables
+
+Before 0.45, a Stepper's direction was `alignment`, its default look `StepperStyleType.Default`, and
+its colours six theme variables. TypeScript points at the first two:
+
+| Before | After |
+|--------|-------|
+| `alignment={StepperAlignment.Vertical}` or `alignment='vertical'` | `orientation={StepperOrientation.Vertical}` |
+| `alignment={StepperAlignment.Horizontal}` | nothing: `Horizontal` is the default |
+| `styleType={StepperStyleType.Default}` | nothing: `Filled` is the default |
+
+**The colour variables compile unchanged and do nothing**, since a theme accepts any variable:
+
+| Theme set | Instead |
+|-----------|---------|
+| `--stepper-active-color`, `--stepper-done-color`, `--stepper-connector-color` | `color`, on the instance or app-wide with `defaultProps={{ Stepper: { color: 'var(--your-colour)' } }}` |
+| `--stepper-text-on-marker` | nothing: it is picked for contrast with `color` (`--text-on-primary` for `Primary`) |
+| `--stepper-error-color` | `--error-color` |
+| `--stepper-idle-color` | `--border-color` and `--text-dark` theme-wide, or `classNames.entryNumber` for the Stepper alone |
+
+Three more changes compile unchanged and need a look of their own:
+
+- **Horizontal steps take equal columns**, so the first and last markers no longer sit at the
+  stepper's edges. A `styles.connector` or `classNames.connector` that sized the connector (such as
+  `{ flex: 1, width: 'auto' }`) is no longer needed: the connector is positioned between the markers.
+- **`hideLabels` no longer hides vertical `content`**, and keeps the labels for screen readers.
+- **A clickable step is a `<button>`**, not a `div` with `role="button"`. CSS that selected
+  `[role="button"]` inside a Stepper should select `button`.

package/docs/ThemeColor.md

@@ -38,7 +38,7 @@ showToast('Saved', { color: ThemeColor.Success });
 
 **Where it applies:** Button, ActionIcon, CopyButton, SplitButton, ActionButtons (`submitButtonColor`,
 `cancelButtonColor`), Card and its actions, Badge, Chip, Accordion, Alert, Toast, Timeline items, Calendar
-events, ProgressBar segments and AnimatedLogo.
+events, ProgressBar segments, Loader and AnimatedLogo.
 
 **Styles share their names:** where two components offer the same look, it has the same name in
 each one's own `styleType` enum. Each component offers only the ones it can draw.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "A React UI component library with theming, CSS Modules, and TypeScript support",
   "keywords": [
     "agent",

package/dist/cjs-types/common/loading/index.d.ts

@@ -1 +0,0 @@
-export { default as SpinnerLoading } from './spinnerLoading/index.js';

package/dist/cjs-types/common/loading/spinnerLoading/index.d.ts

@@ -1,2 +0,0 @@
-import { default as SpinnerLoading } from './spinnerLoading.js';
-export default SpinnerLoading;

package/dist/cjs-types/common/loading/spinnerLoading/spinnerLoading.d.ts

@@ -1,6 +0,0 @@
-import { ReactElement } from 'react';
-interface Properties {
-    className?: string | undefined;
-}
-declare function SpinnerLoading({ className }: Properties): ReactElement;
-export default SpinnerLoading;

package/dist/esm/common/loading/spinnerLoading/index.mjs

@@ -1,2 +0,0 @@
-"use client";import e from"./spinnerLoading.mjs";var t=e;export{t as default};
-//# sourceMappingURL=index.mjs.map

package/dist/esm/common/loading/spinnerLoading/index.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../../../../package/common/loading/spinnerLoading/index.ts"],"sourcesContent":["import SpinnerLoading from './spinnerLoading';\n\nexport default SpinnerLoading;\n"],"mappings":"iDAEA,IAAA,EAAe"}

package/dist/esm/common/loading/spinnerLoading/spinnerLoading.mjs

@@ -1,2 +0,0 @@
-"use client";import e from"./spinnerLoading.module.mjs";import t from"classnames";import{jsx as n}from"react/jsx-runtime";function r({className:r}){return n(`svg`,{"data-testid":`spinner`,className:t(e.spinnerLoading,r),xmlns:`http://www.w3.org/2000/svg`,viewBox:`0 0 100 100`,fill:`none`,stroke:`var(--primary-color)`,children:n(`circle`,{cx:`50`,cy:`50`,r:`45`,strokeWidth:`10`})})}export{r as default};
-//# sourceMappingURL=spinnerLoading.mjs.map

package/dist/esm/common/loading/spinnerLoading/spinnerLoading.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"spinnerLoading.mjs","names":[],"sources":["../../../../../package/common/loading/spinnerLoading/spinnerLoading.tsx"],"sourcesContent":["import type { ReactElement } from 'react';\nimport cx from 'classnames';\n\nimport styles from './spinnerLoading.module.pcss';\n\ninterface Properties {\n  className?: string | undefined;\n}\n\nfunction SpinnerLoading({ className }: Properties): ReactElement {\n  return (\n    <svg\n      data-testid='spinner'\n      className={cx(styles.spinnerLoading, className)}\n      xmlns='http://www.w3.org/2000/svg'\n      viewBox='0 0 100 100'\n      fill='none'\n      stroke='var(--primary-color)'\n    >\n      <circle cx='50' cy='50' r='45' strokeWidth='10' />\n    </svg>\n  );\n}\n\nexport default SpinnerLoading;\n"],"mappings":"0HASA,SAAS,EAAe,CAAE,aAAuC,CAC/D,OACE,EAAC,MAAD,CACE,cAAY,UACZ,UAAW,EAAG,EAAO,eAAgB,CAAS,EAC9C,MAAM,6BACN,QAAQ,cACR,KAAK,OACL,OAAO,uBAEP,SAAA,EAAC,SAAD,CAAQ,GAAG,KAAK,GAAG,KAAK,EAAE,KAAK,YAAY,IAAM,CAAA,CAC9C,CAAA,CAET"}

package/dist/esm/common/loading/spinnerLoading/spinnerLoading.module.mjs

@@ -1,2 +0,0 @@
-"use client";var e=`spinner-loading_qbxX-`,t=`animate-spinner_6HoVF`,n=`spin_axdh6`,r={"spinner-loading":`spinner-loading_qbxX-`,spinnerLoading:e,"animate-spinner":`animate-spinner_6HoVF`,animateSpinner:t,spin:n};export{t as animateSpinner,r as default,n as spin,e as spinnerLoading};
-//# sourceMappingURL=spinnerLoading.module.mjs.map

package/dist/esm/common/loading/spinnerLoading/spinnerLoading.module.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"spinnerLoading.module.mjs","names":[],"sources":["../../../../../package/common/loading/spinnerLoading/spinnerLoading.module.pcss"],"sourcesContent":[".spinner-loading {\n  width: 70px;\n  height: 70px;\n\n  circle {\n    stroke-dasharray: 283;\n    stroke-dashoffset: 281;\n    stroke-linecap: round;\n    animation:\n      animate-spinner 2s cubic-bezier(0.89, 0.01, 0.12, 1) infinite,\n      spin 3s linear infinite;\n    transform-origin: center;\n  }\n\n  @keyframes animate-spinner {\n    0% {\n      stroke-dashoffset: 281;\n    }\n\n    50% {\n      stroke-dashoffset: 0;\n    }\n\n    100% {\n      stroke-dashoffset: -281;\n    }\n  }\n\n  @keyframes spin {\n    0% {\n      transform: rotate(0deg);\n    }\n\n    100% {\n      transform: rotate(360deg);\n    }\n  }\n}\n"],"mappings":""}

package/dist/types/common/loading/index.d.ts

@@ -1 +0,0 @@
-export { default as SpinnerLoading } from './spinnerLoading/index.js';

package/dist/types/common/loading/spinnerLoading/index.d.ts

@@ -1,2 +0,0 @@
-import { default as SpinnerLoading } from './spinnerLoading.js';
-export default SpinnerLoading;

package/dist/types/common/loading/spinnerLoading/spinnerLoading.d.ts

@@ -1,6 +0,0 @@
-import { ReactElement } from 'react';
-interface Properties {
-    className?: string | undefined;
-}
-declare function SpinnerLoading({ className }: Properties): ReactElement;
-export default SpinnerLoading;

package/docs/Loading.md

@@ -1,68 +0,0 @@
-# Loading (SpinnerLoading)
-
-**When to use:** A loading indicator for async operations: page loads, data fetching, or covering a region while it refreshes. For a button use `Button`'s built-in `isLoading`, and for placeholder content that mirrors the shape of what is coming use [Skeleton.md](Skeleton.md).
-
-**Keywords:** busy, waiting, activity indicator, throbber, progress, async, fetching, overlay
-
-**Import:** `import { SpinnerLoading } from '@ahrowe/ui'`
-
-```tsx
-import { SpinnerLoading } from '@ahrowe/ui';
-
-// Default: a 70x70 circular spinner stroked in var(--primary-color)
-{isLoading && <SpinnerLoading />}
-
-// Sized through className
-<SpinnerLoading className="my-spinner" />
-```
-
-```css
-.my-spinner {
-  width: 24px;
-  height: 24px;
-}
-```
-
-**Key props:**
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `className` | `string` | Root `svg` element. This is also how you size it |
-
-## Covering a region while it loads
-
-`SpinnerLoading` is the indicator only. To overlay it on content, centre it in a positioned parent:
-
-```tsx
-<div className="panel">
-  <YourContent />
-  {isLoading && (
-    <div className="panel-overlay">
-      <SpinnerLoading className="my-spinner" />
-    </div>
-  )}
-</div>
-```
-
-```css
-.panel {
-  position: relative;
-}
-
-.panel-overlay {
-  position: absolute;
-  inset: 0;
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  pointer-events: none;
-}
-```
-
-Drop the `pointer-events: none` if the overlay should also block interaction with what is underneath, and add a translucent `background` if it should dim it.
-
-For a branded loading screen rather than a generic spinner, [AnimatedLogo.md](AnimatedLogo.md) draws an SVG mark and sits in the same overlay.
-
-**Note:** the spinner animates continuously even under `prefers-reduced-motion`. A frozen spinner would say the app has hung, which is the opposite of what it is there to communicate.
-
-**Slots:** none. The root `svg` takes `className`.