ng-hub-ui-stepper 22.8.2 → 22.10.0

package/README.md

@@ -8,7 +8,7 @@
 A flexible, customizable, and accessible stepper component for Angular 21+. Perfect for multi-step forms, wizards, and guided user experiences with a focus on developer experience and modern standards.
 
 > [!IMPORTANT]
-> Version `22.8.2` targets **Angular 21** and uses the **Signals** architecture shared across `ng-hub-ui`.
+> Version `22.10.0` targets **Angular 21** and uses the **Signals** architecture shared across `ng-hub-ui`.
 
 ## Documentation and Live Examples
 
@@ -59,6 +59,7 @@ This library is part of the **ng-hub-ui** ecosystem:
 	- [Directives](#directives)
 	- [Host classes](#host-classes)
 	- [Services](#services)
+	- [Providers](#providers)
 	- [Interfaces](#interfaces)
 - [Internationalization](#internationalization)
 - [Styling](#styling)
@@ -107,9 +108,20 @@ The rest of the surface — `StepTriggerDirective`, `StepperNavDirective`, `Prev
 `NextButtonDirective` and `SubmitButtonDirective` — is imported the same way, one by one, as each
 template needs it.
 
+Then register the library once, so the built-in Back / Continue / Submit controls have text:
+
+```typescript
+import { provideHubStepper } from 'ng-hub-ui-stepper';
+
+bootstrapApplication(AppComponent, {
+  providers: [provideHubStepper({ language: 'en' })]
+});
+```
+
 > **`StepperModule` is deprecated and will be removed in 23.0.0.** It only re-exports the seven
-> building blocks above, so importing them directly is the whole migration. `StepperModule.forRoot()`
-> goes with it — see [Internationalization](#internationalization).
+> building blocks above, so importing them directly is the whole migration, and
+> `StepperModule.forRoot()` becomes `provideHubStepper()` — same providers, no module. See
+> [Providers](#providers) and [Internationalization](#internationalization).
 
 In your template:
 
@@ -199,13 +211,14 @@ button disabled while the move is unavailable.
 
 ### Step transitions
 
-Transitions are plain CSS and opt-in: add `stepper--animated` to the host, then pick the flavour with
-`stepper--anim-slide` (the default when neither is set) or `stepper--anim-fade`. Duration comes from
-`--hub-stepper-animation-duration`.
+Transitions are plain CSS and opt-in: add `hub-stepper--animated` to the host, then pick the flavour
+with `hub-stepper--anim-slide` (the default when neither is set) or `hub-stepper--anim-fade`. Duration
+comes from `--hub-stepper-animation-duration`. The unprefixed `stepper--animated`,
+`stepper--anim-slide` and `stepper--anim-fade` are still read, and go in 23.0.0.
 
 ```html
 <hub-stepper
-  class="stepper--animated stepper--anim-fade"
+  class="hub-stepper--animated hub-stepper--anim-fade"
   [style.--hub-stepper-animation-duration.ms]="240"
 >
   <hub-step title="Profile">...</hub-step>
@@ -213,6 +226,39 @@ Transitions are plain CSS and opt-in: add `stepper--animated` to the host, then
 </hub-stepper>
 ```
 
+### Custom rail triggers
+
+`hubStepperNav` replaces the whole rail. When all you want is a different control inside each rail
+item — a numbered circle, an icon, a check on the steps already done — `hubStepTrigger` is one level
+down: the rail keeps its list, its `role="tablist"`, its orientation and its label, and only the
+button inside each item is yours.
+
+```html
+<hub-stepper #wizard>
+  <ng-template hubStepTrigger let-title="title" let-index="index" let-isCurrent="isCurrent" let-disabled="disabled">
+    <button
+      type="button"
+      role="tab"
+      [attr.aria-selected]="isCurrent"
+      [disabled]="disabled"
+      (click)="wizard.goTo(index)"
+    >
+      <span class="badge">{{ index + 1 }}</span> {{ title }}
+    </button>
+  </ng-template>
+
+  <hub-step title="Account">...</hub-step>
+  <hub-step title="Payment">...</hub-step>
+</hub-stepper>
+```
+
+The context carries the step as `$implicit` and as `step`, plus `title`, `index`, `isCurrent`,
+`isCompleted` and `disabled`. Activating a step stays with you, through a template reference on the
+host — which is why the example names the stepper `#wizard`. Give the trigger `role="tab"` if you
+want the rail's arrow-key navigation to keep finding it.
+
+A stepper that declares both templates uses `hubStepperNav` and ignores this one.
+
 ## API Reference
 
 ### StepperComponent (`hub-stepper`)
@@ -262,7 +308,7 @@ Public members you can reach through a template reference (`<hub-stepper #steppe
 | `PreviousButtonDirective` | `button[previousButton]`, `button[backButton]` | `<button>` | Calls `goToPrevious()` and disables the button when there is no enabled previous step. |
 | `SubmitButtonDirective` | `button[submitButton]` | `<button>` | Calls `complete()` and disables the button while the current step is `disabled`. |
 | `StepperNavDirective` | `[hubStepperNav]`, `[stepperNav]` | `<ng-template>` | Replaces the built-in rail. Context: `steps`, `currentIndex`. |
-| `StepTriggerDirective` | `[hubStepTrigger]`, `[stepTrigger]` | `<ng-template>` | Captures a per-step trigger template. **Exported but not yet rendered** — the stepper draws its own triggers; this is groundwork, and applying it changes nothing today. |
+| `StepTriggerDirective` | `[hubStepTrigger]`, `[stepTrigger]` | `<ng-template>` | Replaces the rail trigger the default rail draws, once per step. Context: `$implicit` / `step`, `title`, `index`, `isCurrent`, `isCompleted`, `disabled`. Ignored when a `hubStepperNav` template is present, since a custom rail draws its own triggers. |
 
 ### Host classes
 
@@ -270,9 +316,16 @@ Set these on `<hub-stepper>` itself; they are read by the stylesheet, not by inp
 
 | Class | Effect |
 |---|---|
-| `stepper--animated` | Enables the CSS transition between step panels. Without it, panels swap instantly. |
-| `stepper--anim-slide` | Slide transition (also the default when only `stepper--animated` is set). |
-| `stepper--anim-fade` | Fade transition instead of the slide. |
+| `hub-stepper--animated` | Enables the CSS transition between step panels. Without it, panels swap instantly. |
+| `hub-stepper--anim-slide` | Slide transition (also the default when only `hub-stepper--animated` is set). |
+| `hub-stepper--anim-fade` | Fade transition instead of the slide. |
+
+> **Renamed in 22.10.0.** These were `stepper--animated`, `stepper--anim-slide` and
+> `stepper--anim-fade`, and the component itself wore a bare `stepper` class. `stepper` is a word in
+> the application's namespace, not the library's, so a host application with a `.stepper` rule of its
+> own restyled the component from the outside. The whole block is now `hub-stepper`, in line with
+> every other library of the family. **The old spellings still work and are still written to the
+> DOM**; both go in **23.0.0**. See [`BREAKING_CHANGES.md`](./BREAKING_CHANGES.md).
 
 ### Services
 
@@ -293,6 +346,46 @@ inject(StepperThemeService).setTheme({
 For a theme known at build time, prefer the [`hub-stepper-theme()` mixin](#sass-mixin): it scopes to a
 selector instead of the document root.
 
+### Providers
+
+#### `provideHubStepper(config?: StepperConfig)`
+
+The standalone entry point. Registers the ten bundled dictionaries and the `HubTranslationService`
+that `TranslatePipe` injects to resolve the built-in control labels — the service is not
+`providedIn: 'root'`, so without this (or another provider of it) the first render throws
+`NullInjectorError`.
+
+```typescript
+bootstrapApplication(AppComponent, {
+  providers: [provideHubStepper({ language: 'en', fallbackLanguage: 'en' })]
+});
+```
+
+It can also be scoped to the route that owns the wizard, which is what an application already
+configuring `provideHubTranslation()` at the root should do — see
+[Internationalization](#internationalization) for why.
+
+#### `STEPPER_DICTIONARIES`
+
+The bundled dictionaries as a plain record, keyed by language code, so you can register only the
+languages you ship or merge the labels into a dictionary of your own:
+
+```typescript
+import { STEPPER_DICTIONARIES } from 'ng-hub-ui-stepper';
+
+provideHubTranslation({
+  language: 'ca',
+  fallbackLanguage: 'en',
+  dictionaries: {
+    ca: { ...STEPPER_DICTIONARIES['ca'], ...myCatalanStrings },
+    en: { ...STEPPER_DICTIONARIES['en'], ...myEnglishStrings }
+  }
+});
+```
+
+The keys are flat — `BACK`, `CONTINUE`, `SUBMIT` — which is what the component resolves once its
+`HUBUI.STEPPER` namespace misses.
+
 ### Interfaces
 
 #### `StepperOptions`
@@ -305,7 +398,7 @@ interface StepperOptions {
 
 #### `StepperConfig`
 
-Accepted by the deprecated `StepperModule.forRoot()`, which registers the bundled dictionaries:
+Accepted by `provideHubStepper()` and by the deprecated `StepperModule.forRoot()`:
 
 ```typescript
 interface StepperConfig {
@@ -319,19 +412,22 @@ interface StepperConfig {
 The built-in back, continue and submit labels go through `TranslatePipe` from `ng-hub-ui-utils`. There are
 two ways to feed them, and they can be combined.
 
-**The bundled dictionaries — deprecated.** `StepperModule.forRoot()` registers translations for `en`,
-`es`, `ca`, `eu`, `gl`, `ast`, `an`, `de`, `zh` and `ar`:
+**The bundled dictionaries.** `provideHubStepper()` registers translations for `en`, `es`, `ca`, `eu`,
+`gl`, `ast`, `an`, `de`, `zh` and `ar`, and the `HubTranslationService` that `TranslatePipe` injects:
 
 ```typescript
-imports: [StepperModule.forRoot({ language: 'en', fallbackLanguage: 'en' })];
+providers: [provideHubStepper({ language: 'en', fallbackLanguage: 'en' })];
 ```
 
-It is the only way to reach those dictionaries, and it is **removed in 23.0.0** along with the module.
-The dictionaries themselves are not exported, so they cannot be handed to a provider function: use the
-application dictionary below, or name the three controls through the `backLabel` / `continueLabel` /
-`submitLabel` inputs. Note that `forRoot()` is also what provides `HubTranslationService`, which
-`TranslatePipe` injects — an application that drops it must provide the service another way, which
-both `provideHubTranslation()` and `provideHubTranslationAdapter()` do.
+`StepperModule.forRoot({ language: 'en', fallbackLanguage: 'en' })` does the same and is **removed in
+23.0.0** along with the module; it now delegates to `provideHubStepper()`, so the swap changes nothing
+at runtime.
+
+One caveat: `provideHubStepper()` writes `HUB_TRANSLATION_CONFIG`, and that is a single
+application-wide token. If your application already calls `provideHubTranslation()` at the root, do
+not register both — whichever comes last wins and the other loses its dictionaries. Merge the stepper
+labels into your own call with [`STEPPER_DICTIONARIES`](#stepper_dictionaries), or scope
+`provideHubStepper()` to the route that owns the wizard.
 
 **Your application dictionary.** Configure `provideHubTranslationAdapter()` once in `app.config.ts`; its
 reactive dictionary updates the rendered navigation automatically. The component provides