@eifi1/ui-kit 0.48.2 → 0.50.0

package/src/tour/use-tour-url-sync.ts

@@ -2,7 +2,8 @@ import { createContext, useContext, useEffect, useLayoutEffect, useRef, useState
 import * as ReactRouter from "react-router";
 import { useLocation, useNavigate, type Navigator } from "react-router";
 import { useSearchParamsState } from "../hooks/use-search-param-state";
-import { useTourOptional } from "./tour";
+import { useTourOptional, type TourStart } from "./tour";
+import { devWarnings } from "./tour-gates";
 
 /* ── useTourUrlSync ─────────────────────────────────────────────────────────── */
 
@@ -11,9 +12,11 @@ export interface UseTourUrlSyncOptions {
    * Start the tour `id` at `startIndex` (0-based) — the app's launcher, which builds the
    * steps, awaits its own `prepare()` and passes `onFinish` (the completion, the points
    * toast) to `useTour().start`. An unknown id should do nothing. May return a promise:
-   * the parameters are kept until it settles.
+   * the parameters are kept until it settles. Under a `TourProvider` the third argument is
+   * that provider's `start` (0.50, as `TourProvider launch` gets it), so one launcher serves
+   * both. Without a provider it is a `start` that does nothing (a development build warns).
    */
-  launch: (id: string, options: { startIndex: number }) => void | Promise<unknown>;
+  launch: (id: string, options: { startIndex: number }, start: TourStart) => void | Promise<unknown>;
   /**
    * Are the facts a tour's steps are built from loaded yet (keksdose's `ready`: the
    * caches a branching tour reads)? A deep link waits for it, keeping its parameters, so
@@ -120,9 +123,11 @@ export function useTourUrlSync({ launch, ready = true, stepAliases = [] }: UseTo
   const aliases = stepAliases.join("\n");
 
   const launchRef = useRef(launch);
+  const startRef = useRef<TourStart>(engine?.start ?? noProviderStart);
   const activeIdRef = useRef(activeId);
   useLayoutEffect(() => {
     launchRef.current = launch;
+    startRef.current = engine?.start ?? noProviderStart;
     activeIdRef.current = active ? activeId : null;
   });
   /** The `tour` value last seen in the URL: a tour starts when it CHANGES to an id. */
@@ -148,7 +153,7 @@ export function useTourUrlSync({ launch, ready = true, stepAliases = [] }: UseTo
     pendingRef.current = null;
     launchingRef.current = true;
     void Promise.resolve()
-      .then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }))
+      .then(() => launchRef.current(pending.id, { startIndex: pending.startIndex }, startRef.current))
       .catch(() => undefined)
       .finally(() => {
         launchingRef.current = false;
@@ -183,6 +188,11 @@ export function useTourUrlSync({ launch, ready = true, stepAliases = [] }: UseTo
   }, [active, activeId, index, pathname, search, hash, settled, aliases]);
 }
 
+/** `start` for a launcher run with no `TourProvider` above `useTourUrlSync`. */
+const noProviderStart: TourStart = () => {
+  if (devWarnings()) console.warn("[ui-kit] useTourUrlSync: the launcher's start needs a TourProvider above it.");
+};
+
 /* ── useTourCatalogueUrlState ───────────────────────────────────────────────── */
 
 /** The catalogue's state filter. */

package/src/tour.ts

@@ -16,3 +16,6 @@ export { signOutTourProgress } from "./tour/use-tour-progress";
 export type { TourProgressAccount, TourProgressAdopt, TourProgressBody } from "./tour/use-tour-progress";
 export { useTourUrlSync, useTourCatalogueUrlState } from "./tour/use-tour-url-sync";
 export type { UseTourUrlSyncOptions, TourCatalogueFilter, TourStateFilter } from "./tour/use-tour-url-sync";
+// 0.50.0: guided form tours (docs/tours-harmonization.md §11) — "Guide me" inside a form.
+export { TourGuideButton, DEFAULT_TOUR_GUIDE_LABELS } from "./tour/tour-guide-button";
+export type { TourGuideButtonProps, TourGuideLabels } from "./tour/tour-guide-button";

package/src/wizard/stepper-nav.tsx

@@ -10,8 +10,9 @@ import { alertFrameClass } from "../components/alert-banner";
 import { WizardContextProvider } from "./wizard-context";
 import { DEFAULT_WIZARD_LABELS } from "./types";
 import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
-import type { UseWizardReturn, WizardLabels } from "./types";
+import type { UseWizardReturn, WizardFinishResult, WizardLabels } from "./types";
 import type { CommitScope } from "../components/write-lock";
+import { useTourGateRelease } from "../tour/tour-gates";
 
 /**
  * The chrome around a wizard: the step indicator, the step content, and the
@@ -42,7 +43,7 @@ export function StepperNav<TData extends Record<string, unknown>>({
   description,
   className,
   labels,
-  finishVariant = "brand",
+  finishVariant = "accent",
   finishDisabled = false,
   finishCommit,
   finishDisabledReason,
@@ -56,7 +57,7 @@ export function StepperNav<TData extends Record<string, unknown>>({
   className?: string;
   labels?: LabelOverride<WizardLabels>;
   /** The Finish button's variant — `"danger"` for a destructive commit (an import
-   *  that replaces what is there). Default `"brand"`. Next keeps `"brand"`. */
+   *  that replaces what is there). Default `"accent"`. Next keeps `"accent"`. */
   finishVariant?: ButtonVariant;
   /** Disable Finish for a reason of the app's own, on top of the kit's gates
    *  (`canFinish`, submitting, validating). */
@@ -152,6 +153,25 @@ export function StepperNav<TData extends Record<string, unknown>>({
   // (empty data after a reload) from firing an empty submit.
   const canFinish = wizard.canFinish;
 
+  // A running tour's `awaitGate` steps (0.50, docs/tours-harmonization.md §11.9): Next
+  // releases "wizard-next" when the wizard moved and refuses it when a validator kept it
+  // in place; Finish releases "wizard-finish" once `onComplete` resolved and refuses it,
+  // with the error's message, when it threw. No-ops without a TourProvider or a tour.
+  const tourGates = useTourGateRelease();
+  // `useWizard`'s goNext/finish resolve their outcome at run time (see their types); a
+  // wizard object built some other way resolves nothing, and nothing is signalled.
+  const goNext = async () => {
+    const moved = (await wizard.goNext()) as unknown as boolean | undefined;
+    if (moved === true) tourGates.release("wizard-next");
+    else if (moved === false) tourGates.refuse("wizard-next");
+  };
+  const finish = async () => {
+    const result = (await wizard.finish()) as unknown as WizardFinishResult | undefined;
+    if (!result) return;
+    if (result.ok) tourGates.release("wizard-finish");
+    else tourGates.refuse("wizard-finish", result.error);
+  };
+
   // Pending while the step's validators run (an async server check): a spinner and
   // `aria-busy`, and disabled — the hook's own re-entry guard still refuses a second
   // press, this just stops it looking like the first one did nothing.
@@ -165,7 +185,7 @@ export function StepperNav<TData extends Record<string, unknown>>({
       <Button
         variant={finishVariant}
         data-tour="wizard-finish"
-        onClick={wizard.finish}
+        onClick={() => void finish()}
         // The kit Button's lock: a reason (its own or, with `commit`, the provider's)
         // wins over `disabled` and keeps the button reachable, saying why.
         commit={finishCommit}
@@ -183,16 +203,16 @@ export function StepperNav<TData extends Record<string, unknown>>({
     // The last step after a commit. Nothing to finish; Done only when the app gave
     // an `onDone` — otherwise the step carries its own way out.
     forwardButton = wizard.canDone ? (
-      <Button variant="brand" data-tour="wizard-done" onClick={wizard.done} disabled={doneDisabled}>
+      <Button variant="accent" data-tour="wizard-done" onClick={wizard.done} disabled={doneDisabled}>
         {stepNextLabel ?? l.done ?? DEFAULT_WIZARD_LABELS.done}
       </Button>
     ) : null;
   } else {
     forwardButton = (
       <Button
-        variant="brand"
+        variant="accent"
         data-tour="wizard-next"
-        onClick={wizard.goNext}
+        onClick={() => void goNext()}
         disabled={wizard.nextBlocked || pending}
         aria-busy={pending || undefined}
       >

package/src/wizard/types.ts

@@ -119,6 +119,13 @@ export interface UseWizardOptions<TData extends Record<string, unknown>> {
 
 export type StepStatus = "upcoming" | "active" | "completed" | "skipped";
 
+
+/** What `finish` resolves to at run time (0.50): whether the commit went through, and the
+ *  error's message when `onComplete` threw. `undefined` when there was nothing to run. */
+export interface WizardFinishResult {
+  ok: boolean;
+  error?: string;
+}
 export interface UseWizardReturn<TData extends Record<string, unknown>> {
   // Navigation
   currentStepIndex: number;
@@ -146,12 +153,17 @@ export interface UseWizardReturn<TData extends Record<string, unknown>> {
   /** Whether the indicator may jump to `index` — a completed/skipped/active step on
    *  the right side of any commit. `goToStep` refuses anything this rejects. */
   canGoToStep: (index: number) => boolean;
+  /** Validates the step and moves on. (0.50: at run time it resolves `true` when it
+   *  moved, `false` when a validator kept it in place — what StepperNav tells a running
+   *  tour, docs/tours-harmonization.md §11.9. The declared type stays `Promise<void>`.) */
   goNext: () => Promise<void>;
   /** One step back — or, on the first step, `onExit`. Refused while submitting. */
   goBack: () => void;
   goToStep: (index: number) => void;
   skip: () => void;
   cancel: () => void;
+  /** Validates and commits (`onComplete`). (0.50: at run time it resolves `{ ok, error? }`
+   *  — see {@link WizardFinishResult}; the declared type stays `Promise<void>`.) */
   finish: () => Promise<void>;
   /** Leave after the post-commit steps: drops the URL param, then calls `onDone`. */
   done: () => void;

package/src/wizard/use-wizard.ts

@@ -20,6 +20,7 @@ import { useKitLabels } from "../i18n/kit-labels";
 import { DEFAULT_WIZARD_LABELS } from "./types";
 import { toast } from "../components/toast";
 import type {
+  WizardFinishResult,
   FieldErrors,
   StepStatus,
   UseWizardOptions,
@@ -341,8 +342,8 @@ export function useWizard<TData extends Record<string, unknown>>(
    */
   const advancingRef = useRef(false);
 
-  const goNext = useCallback(async () => {
-    if (advancingRef.current) return;
+  const goNext = useCallback(async (): Promise<boolean | undefined> => {
+    if (advancingRef.current) return undefined;
     advancingRef.current = true;
     const from = state.currentStepIndex;
     // Pending state for the chrome (spinner, aria-busy). The ref above is still what
@@ -351,7 +352,9 @@ export function useWizard<TData extends Record<string, unknown>>(
     try {
       if (await runStepValidators()) {
         dispatch({ type: "GO_NEXT", from });
+        return true;
       }
+      return false;
     } finally {
       dispatch({ type: "SET_VALIDATING", value: false });
       advancingRef.current = false;
@@ -431,16 +434,16 @@ export function useWizard<TData extends Record<string, unknown>>(
     dispatch({ type: "SET_FIELD_ERRORS", errors: {} });
   }, []);
 
-  const finish = useCallback(async () => {
-    if (!onComplete || !canFinish) return;
+  const finish = useCallback(async (): Promise<WizardFinishResult | undefined> => {
+    if (!onComplete || !canFinish) return undefined;
     // A commit with steps after it happens once: those steps exist because the
     // data has been written. (A last-step commit keeps its old behaviour — the app
     // may retry Finish after `onComplete` resolved, as it always could.)
-    if (commitStepIndex < steps.length - 1 && state.committedStepIndex !== null) return;
+    if (commitStepIndex < steps.length - 1 && state.committedStepIndex !== null) return undefined;
     // The same re-entry guard as `goNext`: a double-click on Finish would otherwise
     // validate twice and call `onComplete` twice — `isSubmitting` is only set once
     // validation has passed, too late to stop the second click.
-    if (advancingRef.current) return;
+    if (advancingRef.current) return undefined;
     advancingRef.current = true;
     const from = state.currentStepIndex;
     try {
@@ -454,16 +457,18 @@ export function useWizard<TData extends Record<string, unknown>>(
       } finally {
         dispatch({ type: "SET_VALIDATING", value: false });
       }
-      if (!valid) return;
+      if (!valid) return { ok: false };
       submittingRef.current = true;
       dispatch({ type: "SET_SUBMITTING", value: true });
       dispatch({ type: "SET_ERROR", error: null });
       try {
         await onComplete(state.data);
         dispatch({ type: "COMMITTED", from });
+        return { ok: true };
       } catch (err) {
         const message = err instanceof Error && err.message ? err.message : genericError;
         dispatch({ type: "SET_ERROR", error: message });
+        return { ok: false, error: err instanceof Error && err.message ? err.message : undefined };
       } finally {
         submittingRef.current = false;
         dispatch({ type: "SET_SUBMITTING", value: false });
@@ -507,12 +512,14 @@ export function useWizard<TData extends Record<string, unknown>>(
     canCancel,
     canDone,
     canGoToStep,
-    goNext,
+    // Their outcomes are what StepperNav tells a running tour (0.50); the declared types stay
+    // `Promise<void>`, so an app's `let p: Promise<void> = wizard.goNext()` still compiles.
+    goNext: goNext as () => Promise<void>,
     goBack,
     goToStep,
     skip,
     cancel,
-    finish,
+    finish: finish as () => Promise<void>,
     done,
     registerStepValidate,
     nextBlocked,

package/tokens.css

@@ -264,15 +264,23 @@ html[data-text-size="xlarge"] {
   --status-pending: #1d4ed8;   /* blue-700   — in flight */
   --status-edited: #bf6800;    /* solved     — dirty, not yet saved */
   --status-error: #b91c1c;     /* red-700    — the save failed */
-  --chart-1: #332288;
-  --chart-2: #88ccee;
-  --chart-3: #44aa99;
-  --chart-4: #117733;
-  --chart-5: #999933;
-  --chart-6: #ddcc77;
-  --chart-7: #cc6677;
-  --chart-8: #882255;
-  --chart-9: #aa4499;
+  /* Chart ramp: anyplot's eight "Imprint" hues (0.49, https://anyplot.ai/palette), the
+     SAME in both themes — a hue under 3:1 on the ground gets a 1px ink edge
+     (`chartEdge`) rather than a different colour. `--chart-9` repeats slot 1, where
+     `paletteFor(8)` lands. Only the two inks below change with the theme:
+     `--chart-ink` for totals, baselines and edges; `--chart-muted` for an "other" /
+     rest / disabled slice and confidence bands (`CHART_ROLES`). */
+  --chart-1: #009e73;
+  --chart-2: #c475fd;
+  --chart-3: #4467a3;
+  --chart-4: #bd8233;
+  --chart-5: #ae3030;
+  --chart-6: #2abccd;
+  --chart-7: #954477;
+  --chart-8: #99b314;
+  --chart-9: #009e73;
+  --chart-ink: #1a1a17;
+  --chart-muted: #6b6a63;
 }
 
 .dark {
@@ -306,15 +314,17 @@ html[data-text-size="xlarge"] {
   --status-pending: #7dd3fc;   /* sky-300 */
   --status-edited: #fbbf24;    /* amber-400 */
   --status-error: #fca5a5;     /* red-300 */
-  --chart-1: #7e72d6;
-  --chart-2: #9fd8f2;
-  --chart-3: #5fc4b0;
-  --chart-4: #3fa45f;
-  --chart-5: #bfbf5e;
-  --chart-6: #e8dda0;
-  --chart-7: #e08c9a;
-  --chart-8: #c25a78;
-  --chart-9: #cc78be;
+  --chart-1: #009e73;
+  --chart-2: #c475fd;
+  --chart-3: #4467a3;
+  --chart-4: #bd8233;
+  --chart-5: #ae3030;
+  --chart-6: #2abccd;
+  --chart-7: #954477;
+  --chart-8: #99b314;
+  --chart-9: #009e73;
+  --chart-ink: #f0efe8;
+  --chart-muted: #a8a79f;
 }
 
 /* ── Derived surface / text roles ───────────────────────────────────────────