@eifi1/ui-kit 0.43.0 → 0.45.0

package/src/shell.ts

@@ -20,6 +20,10 @@ export type { AdminMenuEntryOptions, AdminMenuRowProps } from "./shell/admin-men
 // 0.43.0 (kastlan): the entry with the provider's words.
 export { useAdminMenuEntry } from "./shell/admin-menu";
 export type { UseAdminMenuEntryOptions } from "./shell/admin-menu";
+// 0.45.0 (docs/admin-harmonization.md §9.3.4): the row's waiting pill on its own, for
+// IconButton's `badge` (kastlan's platform button); its name is `adminArea.waitingLabel`.
+export { AdminWaitingBadge } from "./shell/admin-menu";
+export type { AdminWaitingBadgeProps } from "./shell/admin-menu";
 // 0.31.0: the settings and admin pages' shell (docs/settings-harmonization.md §3, §5).
 export { SettingsLayout, SETTINGS_SEARCH_THRESHOLD } from "./settings/settings-layout";
 export type { SettingsLayoutProps, SettingsLayoutWidth, SettingsDocumentTitleParts } from "./settings/settings-layout";

package/src/tour/tour-catalogue-labels.ts

@@ -54,11 +54,11 @@ export const DEFAULT_TOUR_CATALOGUE_LABELS: TourCatalogueLabels = {
   groupOption: (group, count) => `${group} (${count})`,
   stateLabel: "Filter tours",
   stateAll: (count) => `All (${count})`,
-  stateTodo: (count) => `To do (${count})`,
+  stateTodo: (count) => `Not taken (${count})`,
   stateDone: (count) => `Completed (${count})`,
   showing: (shown, total) => `Showing ${shown} of ${total} tours`,
   noMatches: "No tour matches",
-  noMatchesHint: "Try another word, or clear the filters.",
+  noMatchesHint: "Try another word, or clear the filter.",
   clearFilters: "Clear filters",
   badgeNew: "New",
   badgeUpdated: "Updated",

package/src/tour/tour-catalogue.tsx

@@ -30,7 +30,12 @@ export interface TourCatalogueCardProps {
   onLaunch: (id: string) => void;
   /** "Mark as not done". Without it, the link is not drawn. */
   onReset?: (id: string) => void;
-  /** Formats the completion and update days. Default: the kit's medium date in the provider's locale. */
+  /**
+   * Formats the completion and update days. Default: the kit's medium date in the provider's locale.
+   * It gets the completion's ISO instant and the update's bare `"YYYY-MM-DD"` (`updated.date`): read
+   * the bare day on its calendar (the kit's `formatDate`, `parseIsoDate`), never `new Date(day)`,
+   * which is UTC midnight and the day before west of UTC (round 0.45, N9).
+   */
   formatDate?: (iso: string) => string;
   labels?: LabelOverride<TourCatalogueLabels>;
   className?: string;
@@ -161,6 +166,7 @@ export interface TourCatalogueProps extends TourCatalogueFilter {
   onReset?: (id: string) => void;
   /** Above the filter bar: the app's page header with its points tile (§6.1). */
   header?: ReactNode;
+  /** Each card's `formatDate`: see {@link TourCatalogueCardProps.formatDate} (a bare day for the update). */
   formatDate?: (iso: string) => string;
   /** The search's locale (case folding). Default: the provider's. */
   locale?: string;

package/src/tour/tour-info.ts

@@ -59,8 +59,8 @@ export interface TourGroup {
 
 /**
  * Which tours are completed and when: tour id → the ISO timestamp of the completion, or
- * `null` for one recorded without a date (kastlan's old id list, §6.2). A tour that is
- * not a key is untaken.
+ * `null` for one recorded without a date (kastlan's old id list, §6.2; stored as `""`,
+ * §9.6.6). A tour that is not a key is untaken.
  */
 export type TourCompletions = Readonly<Record<string, string | null>>;
 

package/src/tour/tour.tsx

@@ -17,6 +17,8 @@ import { sameRect } from "../hooks/use-anchored-rect";
 import { dirOf, horizontalStep } from "../lib/direction";
 import type { Direction } from "../lib/direction";
 import { DEFAULT_TOUR_LABELS } from "./tour-labels";
+import type { TourInfo } from "./tour-info";
+import { completeStored, rememberAccount, rememberMigrate, type UseTourProgressOptions } from "./use-tour-progress";
 
 /**
  * `start`/`end` follow the reading direction (`end` is the right side in LTR and the
@@ -67,16 +69,34 @@ export { DEFAULT_TOUR_LABELS };
 
 interface StartOptions {
   /** Stable id of the tour, surfaced as `activeId` so the app can mirror it to
-   *  the URL (deep-link / evaluation tracking) and record completion. */
+   *  the URL (deep-link / evaluation tracking) and record completion. Defaults to
+   *  `tour.id`. */
   id?: string;
+  /** The tour being started, as the app lists it (docs/tours-harmonization.md §9.6.1).
+   *  When its last step is finished, the provider records the completion in its
+   *  `progress` and hands this to `onComplete`. */
+  tour?: TourInfo;
   /** Start at this step index instead of 0 (clamped) — for URL/deep-link resume. */
   startIndex?: number;
   /** Fires synchronously when the tour starts (e.g. enable a mock interceptor). */
   onStart?: () => void;
+  /** After the last step: runs after the provider's progress write and `onComplete`. */
   onFinish?: () => void;
   onSkip?: () => void;
 }
 
+/** What `TourProvider`'s `onComplete` learns besides the tour (§9.1, §9.6). */
+export interface TourCompletion {
+  /**
+   * `true` when the completion counts anew (the first time, or the first time after the
+   * tour's update, §8): the moment for the app's points toast. `false` for a replay, and
+   * when the stored text is in an old shape no `migrate` reads: nothing is overwritten
+   * then, and the error goes to `console.error` (keksdose B-1). `undefined` when the provider has no `progress` or the start carried no `tour`, so
+   * nothing was recorded.
+   */
+  awarded: boolean | undefined;
+}
+
 interface TourContextValue {
   active: boolean;
   /** Id of the running tour (from {@link StartOptions.id}), else null. */
@@ -129,6 +149,11 @@ export function useTourOptional(): TourContextValue | null {
   return useContext(TourContext);
 }
 
+/** The kit's dev switch (as number-input's): a development build, never under vitest. */
+function devWarnings(): boolean {
+  return Boolean(import.meta.env?.DEV) && !import.meta.env?.VITEST;
+}
+
 /**
  * Provides the guided-tour engine: a dimmed spotlight overlay + step card driven
  * by a list of {@link TourStep}s. Domain-free — the app supplies the steps (copy,
@@ -136,13 +161,32 @@ export function useTourOptional(): TourContextValue | null {
  * Mount once inside the router; start a tour from anywhere via {@link useTour},
  * which also exposes step control (`next`/`prev`/`goToStep`) and the current
  * `index`/`total` for URL mirroring, `awaitClick` and deep-link resume.
+ *
+ * **Completion in one place** (docs/tours-harmonization.md §9.6): give the provider the
+ * app's `progress` (the same `{storageKey, migrate}` as `useTourProgress`) and start each
+ * tour with `start(steps, {tour})`. When the last step is finished the provider writes the
+ * completion ONCE, through the store every `useTourProgress` reader of the key shares
+ * (never a second copy), then calls `onComplete(tour, {awarded})`, then the start's own
+ * `onFinish`. A skip or `stop()` records nothing and calls neither. The app removes its
+ * own `complete()` from `onFinish`, or that second write answers `false`.
+ *
+ * Both props are optional: without `progress` or a `tour` on the start, `onComplete`
+ * still fires, with `awarded: undefined` (and `tour` as given, possibly `undefined`). A
+ * new `storageKey` (an account switch on a shared PC) is followed on the next
+ * completion, without a remount.
  */
 export function TourProvider({
   children,
   labels,
+  progress,
+  onComplete,
 }: {
   children: ReactNode;
   labels?: LabelOverride<TourLabels>;
+  /** The app's tour progress: the same options its `useTourProgress` readers use. */
+  progress?: UseTourProgressOptions;
+  /** A tour's last step was finished; see {@link TourCompletion}. */
+  onComplete?: (tour: TourInfo | undefined, completion: TourCompletion) => void;
 }) {
   // `labels` over the provider's `tour` over English. Resolved once here and handed
   // down: the step card is portalled, but context crosses portals anyway — this is
@@ -152,6 +196,23 @@ export function TourProvider({
   const [index, setIndex] = useState(0);
   const [activeId, setActiveId] = useState<string | null>(null);
   const optsRef = useRef<StartOptions>({});
+  // The latest props, read at the finish: a new `storageKey` or callback needs no remount.
+  const progressRef = useRef(progress);
+  const onCompleteRef = useRef(onComplete);
+  useLayoutEffect(() => {
+    progressRef.current = progress;
+    onCompleteRef.current = onComplete;
+  });
+  // The provider's migrate becomes the key's, for readers that pass none (keksdose B-2).
+  const storageKey = progress?.storageKey;
+  const migrate = progress?.migrate;
+  // 0.45: and its `account` (§10.3), so a finish on an account key is sent as readers' are.
+  const account = progress?.account;
+  useLayoutEffect(() => {
+    if (storageKey !== undefined) rememberMigrate(storageKey, migrate);
+    if (storageKey !== undefined) rememberAccount(storageKey, account);
+  }, [storageKey, migrate, account]);
+  const warnedNoTourRef = useRef(false);
   // Live mirrors so the step-control callbacks can stay stable (identity-safe for
   // consumers) while still reading the current steps/index. Synced in a layout
   // effect — after the commit, before paint and before any passive effect or event
@@ -169,7 +230,7 @@ export function TourProvider({
     optsRef.current = opts ?? {};
     optsRef.current.onStart?.();
     setIndex(Math.min(Math.max(0, opts?.startIndex ?? 0), Math.max(0, s.length - 1)));
-    setActiveId(opts?.id ?? null);
+    setActiveId(opts?.id ?? opts?.tour?.id ?? null);
     setSteps(s);
   }, []);
   const stop = useCallback(() => {
@@ -177,7 +238,30 @@ export function TourProvider({
     setActiveId(null);
   }, []);
   const finish = useCallback(() => {
-    optsRef.current.onFinish?.();
+    // Once per tour: a second "Done" before the overlay unmounts records nothing more.
+    if (!stepsRef.current) return;
+    stepsRef.current = null;
+    const { tour, onFinish } = optsRef.current;
+    const store = progressRef.current;
+    // Exactly one write per completion (§9.6.2), so `awarded` is what `complete(tour)` answered.
+    let awarded: boolean | undefined;
+    if (store && tour) {
+      try {
+        awarded = completeStored(store.storageKey, store.migrate, tour);
+      } catch (error) {
+        // A stored text no migrate reads is left as it is (keksdose B-1); the tour still ends.
+        console.error(error);
+        awarded = false;
+      }
+    } else if (store && !tour && devWarnings() && !warnedNoTourRef.current) {
+      warnedNoTourRef.current = true;
+      console.warn(
+        "[ui-kit] TourProvider has `progress`, but a finished tour's start carried no `tour`: " +
+          "nothing was recorded and `awarded` is undefined. Start it with `start(steps, { tour })`.",
+      );
+    }
+    onCompleteRef.current?.(tour, { awarded });
+    onFinish?.();
     setSteps(null);
     setActiveId(null);
   }, []);