@eifi1/ui-kit 0.6.0 → 0.7.0

package/src/tour/tour.tsx

@@ -13,8 +13,15 @@ import { cn } from "../lib/cn";
 import { useKitLabels } from "../i18n/kit-labels";
 import { Button } from "../components/ui";
 import { useFocusTrap } from "../hooks/use-focus-trap";
+import { dirOf, horizontalStep } from "../lib/direction";
+import type { Direction } from "../lib/direction";
 
-export type TourPlacement = "top" | "right" | "bottom" | "left" | "center";
+/**
+ * `start`/`end` follow the reading direction (`end` is the right side in LTR and the
+ * left side in RTL) and are what a translated app wants. `left`/`right` stay physical
+ * for the steps that genuinely mean a screen side.
+ */
+export type TourPlacement = "top" | "right" | "bottom" | "left" | "start" | "end" | "center";
 
 export interface TourStep {
   /** CSS selector for the element to spotlight. Omit for a centered step
@@ -28,13 +35,14 @@ export interface TourStep {
   padding?: number;
   /** Where the card sits relative to the target. Omit for auto placement
    *  (below → above → centered). "center" ignores the target and centers on
-   *  screen. An explicit side flips to the opposite side if it would overflow,
-   *  then clamps into the viewport. */
+   *  screen. "start"/"end" are the logical sides and flip in RTL; "left"/"right"
+   *  are physical. An explicit side flips to the opposite side if it would
+   *  overflow, then clamps into the viewport. */
   placement?: TourPlacement;
   /** Advance only when the user clicks the spotlighted target itself (not the
    *  card's Next button). Requires `target`: the real control's own handler runs
-   *  first, then the tour steps forward on a microtask. The overlay stays
-   *  click-through to the target. */
+   *  first, then the tour steps forward on a microtask. The spotlight hole stays
+   *  click-through to the target; the rest of the page does not. */
   awaitClick?: boolean;
   /** Runs before the step is shown — e.g. navigate to a route, open a panel.
    *  May be async; the step waits for it, then locates the target. */
@@ -269,6 +277,11 @@ function TourOverlay({
   const isLast = index === steps.length - 1;
   const [rect, setRect] = useState<Rect | null>(null);
   const [ready, setReady] = useState(false);
+  // The overlay is portalled to <body>, out of whatever `dir` subtree the app set, so it
+  // takes the direction of the element it spotlights (the document's for a centered
+  // step). Arrow keys and start/end placement read it.
+  const [dir, setDir] = useState<Direction>(() => dirOf(null));
+  const rootRef = useRef<HTMLDivElement>(null);
 
   // Run beforeStep, then locate the target (retrying across route/render lag).
   useEffect(() => {
@@ -280,6 +293,7 @@ function TourOverlay({
       await step.beforeStep?.();
       if (cancelled) return;
       if (!step.target) {
+        setDir(dirOf(null));
         setReady(true);
         return;
       }
@@ -291,11 +305,15 @@ function TourOverlay({
           el.scrollIntoView({ block: "center", behavior: "smooth" });
           const r = el.getBoundingClientRect();
           setRect({ top: r.top, left: r.left, width: r.width, height: r.height });
+          setDir(dirOf(el));
           setReady(true);
           return;
         }
         if (tries++ < 45) raf = requestAnimationFrame(find);
-        else setReady(true); // give up → render centered
+        else {
+          setDir(dirOf(null));
+          setReady(true); // give up → render centered
+        }
       };
       find();
     })();
@@ -326,8 +344,8 @@ function TourOverlay({
     };
   }, [index, step]);
 
-  // awaitClick: advance when the *real* target is clicked. The overlay is
-  // click-through (pointer-events-none except the card) so the element's own
+  // awaitClick: advance when the *real* target is clicked. The spotlight hole is
+  // click-through (see the shields in the render below) so the element's own
   // handler runs first; we step forward on the next macrotask.
   useEffect(() => {
     if (!ready || !step.awaitClick || !step.target) return;
@@ -338,21 +356,34 @@ function TourOverlay({
     return () => el.removeEventListener("click", onClick);
   }, [ready, index, step, onNext]);
 
-  // Keyboard: Esc skips, →/Enter advance, ← goes back. On awaitClick steps Enter
-  // is ignored (it would fire the target's click AND advance) — → stays as an
-  // escape hatch.
+  // Keyboard: Esc skips, Enter and the reading-direction arrow advance (→ in LTR,
+  // ← in RTL), the other arrow goes back. On awaitClick steps Enter is ignored (it
+  // would fire the target's click AND advance) — the forward arrow stays as an escape
+  // hatch.
+  //
+  // Enter on a focused control belongs to that control. This used to advance from
+  // anywhere, so Enter on a focused Skip or Back ran the button's own click AND stepped
+  // forward: Back moved nowhere, Skip skipped and then called `next` on a dead tour.
+  // The same goes for arrows in a text field a step's `action` might contain.
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
       if (e.key === "Escape") {
         onSkip();
-      } else if (e.key === "ArrowRight") {
+        return;
+      }
+      if (e.key === "Enter") {
+        if (step.awaitClick || ownsKey(e.target, "Enter")) return;
         e.preventDefault();
         onNext();
-      } else if (e.key === "Enter") {
-        if (step.awaitClick) return;
+        return;
+      }
+      if (ownsKey(e.target, e.key)) return;
+      // The overlay root carries `dir`; before it paints, the document's answers.
+      const delta = horizontalStep(e.key, rootRef.current);
+      if (delta === 1) {
         e.preventDefault();
         onNext();
-      } else if (e.key === "ArrowLeft") {
+      } else if (delta === -1) {
         if (!isFirst) onPrev();
       }
     };
@@ -367,8 +398,24 @@ function TourOverlay({
     ? { top: rect.top - pad, left: rect.left - pad, width: rect.width + pad * 2, height: rect.height + pad * 2 }
     : null;
 
+  // `aria-modal` promises the page behind is out of reach, and the card's focus trap
+  // keeps that promise for the keyboard. The pointer used to get no such treatment: the
+  // root is `pointer-events-none` so that the spotlight hole can stay live for
+  // `awaitClick`, and the scrim is a box-shadow, which takes no clicks — so every
+  // control on the dimmed page stayed clickable. Four shields now tile the viewport
+  // around the hole: the page is blocked, the card and the spotlighted target are not.
+  // Keeping `aria-modal` (rather than dropping it) is the coherent half: the tour
+  // really is modal — focus is trapped and Esc/Skip is the way out.
   return createPortal(
-    <div className="pointer-events-none fixed inset-0 z-[60]" role="dialog" aria-modal="true" aria-label={step.title}>
+    <div
+      ref={rootRef}
+      className="pointer-events-none fixed inset-0 z-[60]"
+      role="dialog"
+      aria-modal="true"
+      aria-label={step.title}
+      dir={dir}
+    >
+      {spot && <SpotlightShields spot={spot} />}
       {spot ? (
         <div
           className="pointer-events-none fixed rounded-lg transition-all duration-200 ease-out"
@@ -410,6 +457,7 @@ function TourOverlay({
         isFirst={isFirst}
         isLast={isLast}
         rect={spot}
+        dir={dir}
         onBack={onPrev}
         onNext={onNext}
         onSkip={onSkip}
@@ -419,6 +467,53 @@ function TourOverlay({
   );
 }
 
+/** Does the focused element handle `key` itself? Enter on a button or link, and any
+ *  editing key in a text field or select, is the control's — not the tour's. */
+function ownsKey(target: EventTarget | null, key: string): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  const tag = target.tagName;
+  if (tag === "TEXTAREA" || tag === "SELECT") return true;
+  if (tag === "INPUT") {
+    const type = (target as HTMLInputElement).type;
+    // Enter on a checkbox does nothing natively, but ←/→ on a radio moves it.
+    return key !== "Enter" || type !== "checkbox";
+  }
+  if (key !== "Enter") return false;
+  return (
+    tag === "BUTTON" ||
+    (tag === "A" && target.hasAttribute("href")) ||
+    target.getAttribute("role") === "button" ||
+    target.getAttribute("role") === "link"
+  );
+}
+
+/**
+ * Transparent pointer blockers tiling the viewport around the spotlight hole: one
+ * full-width band above and below, one on each side at the hole's own height. The hole
+ * itself stays uncovered, so the target keeps its clicks.
+ */
+function SpotlightShields({ spot }: { spot: Rect }) {
+  const shield = "pointer-events-auto fixed";
+  const bottom = spot.top + spot.height;
+  return (
+    <>
+      <div data-tour-shield="" className={shield} style={{ top: 0, left: 0, right: 0, height: Math.max(0, spot.top) }} />
+      <div data-tour-shield="" className={shield} style={{ top: bottom, left: 0, right: 0, bottom: 0 }} />
+      <div
+        data-tour-shield=""
+        className={shield}
+        style={{ top: spot.top, left: 0, width: Math.max(0, spot.left), height: spot.height }}
+      />
+      <div
+        data-tour-shield=""
+        className={shield}
+        style={{ top: spot.top, left: spot.left + spot.width, right: 0, height: spot.height }}
+      />
+    </>
+  );
+}
+
 /**
  * Card position (viewport px) for the given placement relative to the padded
  * spotlight `rect`. Omitted placement keeps the original auto behavior
@@ -434,7 +529,11 @@ function placeCard(
   vh: number,
   m: number,
   placement?: TourPlacement,
+  dir: Direction = "ltr",
 ): { top: number; left: number } {
+  // The logical sides resolve to a physical one here, and only here.
+  if (placement === "start") placement = dir === "rtl" ? "right" : "left";
+  else if (placement === "end") placement = dir === "rtl" ? "left" : "right";
   if (!rect || placement === "center") {
     return { top: Math.max(m, (vh - ch) / 2), left: Math.max(m, (vw - cw) / 2) };
   }
@@ -475,6 +574,7 @@ function TourCard({
   isFirst,
   isLast,
   rect,
+  dir,
   onBack,
   onNext,
   onSkip,
@@ -486,6 +586,7 @@ function TourCard({
   isFirst: boolean;
   isLast: boolean;
   rect: Rect | null;
+  dir: Direction;
   onBack: () => void;
   onNext: () => void;
   onSkip: () => void;
@@ -524,9 +625,9 @@ function TourCard({
     const card = ref.current;
     if (!card) return;
     setStyle(
-      placeCard(rect, card.offsetWidth, card.offsetHeight, window.innerWidth, window.innerHeight, 12, step.placement),
+      placeCard(rect, card.offsetWidth, card.offsetHeight, window.innerWidth, window.innerHeight, 12, step.placement, dir),
     );
-  }, [rect, index, step.placement]);
+  }, [rect, index, step.placement, dir]);
 
   return (
     <div

package/src/wizard/use-wizard.ts

@@ -33,10 +33,13 @@ interface WizardState<TData> {
 }
 
 type WizardAction<TData> =
-  | { type: "GO_NEXT" }
+  // `from` is the step the move was decided ON. A move whose step is no longer the
+  // current one is stale — see `goNext` — and is dropped rather than applied relative
+  // to wherever the wizard has got to since.
+  | { type: "GO_NEXT"; from: number }
   | { type: "GO_BACK" }
   | { type: "GO_TO_STEP"; index: number }
-  | { type: "SKIP" }
+  | { type: "SKIP"; from: number }
   | { type: "UPDATE_DATA"; partial: Partial<TData> }
   | { type: "SET_SUBMITTING"; value: boolean }
   | { type: "SET_ERROR"; error: string | null }
@@ -50,6 +53,7 @@ function createReducer<TData>(stepCount: number) {
   ): WizardState<TData> {
     switch (action.type) {
       case "GO_NEXT": {
+        if (action.from !== state.currentStepIndex) return state;
         const completed = new Set(state.completedSteps);
         completed.add(state.currentStepIndex);
         const nextIndex = Math.min(state.currentStepIndex + 1, stepCount - 1);
@@ -67,6 +71,7 @@ function createReducer<TData>(stepCount: number) {
         return { ...state, currentStepIndex: action.index };
       }
       case "SKIP": {
+        if (action.from !== state.currentStepIndex) return state;
         const skipped = new Set(state.skippedSteps);
         skipped.add(state.currentStepIndex);
         const nextIndex = Math.min(state.currentStepIndex + 1, stepCount - 1);
@@ -243,11 +248,32 @@ export function useWizard<TData extends Record<string, unknown>>(
     return true;
   }, [state.currentStepIndex, missingRequired, onValidationFailed]);
 
+  /**
+   * One forward move at a time. A double-click on Next used to validate the CURRENT
+   * step twice and then advance twice — the second GO_NEXT landing on a step whose
+   * own validators never ran, so a required field two steps in could be walked past.
+   * Two layers, because either alone leaves a gap:
+   *
+   *  - this ref refuses a second `goNext`/`skip`/`finish` while one is in flight,
+   *    which covers an async validator (a server check) of any length;
+   *  - the `from` on each action drops a move decided on a step that is no longer
+   *    current, which covers the click that arrives after the first move resolved
+   *    but before React re-rendered — its closure still holds the old step index.
+   */
+  const advancingRef = useRef(false);
+
   const goNext = useCallback(async () => {
-    if (await runStepValidators()) {
-      dispatch({ type: "GO_NEXT" });
+    if (advancingRef.current) return;
+    advancingRef.current = true;
+    const from = state.currentStepIndex;
+    try {
+      if (await runStepValidators()) {
+        dispatch({ type: "GO_NEXT", from });
+      }
+    } finally {
+      advancingRef.current = false;
     }
-  }, [runStepValidators]);
+  }, [runStepValidators, state.currentStepIndex]);
 
   const goBack = useCallback(() => {
     dispatch({ type: "GO_BACK" });
@@ -258,8 +284,11 @@ export function useWizard<TData extends Record<string, unknown>>(
   }, []);
 
   const skip = useCallback(() => {
-    dispatch({ type: "SKIP" });
-  }, []);
+    // Not while Next is validating: the skip would land first and the pending GO_NEXT
+    // would then be stale anyway — but the user asked for one move, not a race.
+    if (advancingRef.current) return;
+    dispatch({ type: "SKIP", from: state.currentStepIndex });
+  }, [state.currentStepIndex]);
 
   const cancel = useCallback(() => {
     dispatch({ type: "SHOW_CANCEL_DIALOG", show: true });
@@ -288,18 +317,27 @@ export function useWizard<TData extends Record<string, unknown>>(
 
   const finish = useCallback(async () => {
     if (!onComplete || !canFinish) return;
-    // Validate the (possibly form-bearing) last step before submitting, matching
-    // the Next gate — review-only steps register no validators and pass through.
-    if (!(await runStepValidators())) return;
-    dispatch({ type: "SET_SUBMITTING", value: true });
-    dispatch({ type: "SET_ERROR", error: null });
+    // 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;
+    advancingRef.current = true;
     try {
-      await onComplete(state.data);
-    } catch (err) {
-      const message = err instanceof Error && err.message ? err.message : genericError;
-      dispatch({ type: "SET_ERROR", error: message });
+      // Validate the (possibly form-bearing) last step before submitting, matching
+      // the Next gate — review-only steps register no validators and pass through.
+      if (!(await runStepValidators())) return;
+      dispatch({ type: "SET_SUBMITTING", value: true });
+      dispatch({ type: "SET_ERROR", error: null });
+      try {
+        await onComplete(state.data);
+      } catch (err) {
+        const message = err instanceof Error && err.message ? err.message : genericError;
+        dispatch({ type: "SET_ERROR", error: message });
+      } finally {
+        dispatch({ type: "SET_SUBMITTING", value: false });
+      }
     } finally {
-      dispatch({ type: "SET_SUBMITTING", value: false });
+      advancingRef.current = false;
     }
   }, [onComplete, canFinish, state.data, runStepValidators, genericError]);
 

package/src/wizard/wizard-summary.tsx

@@ -54,7 +54,7 @@ export function WizardSummary({
                   )}
                   <div className="flex items-start justify-between gap-4">
                     <dt className="text-[var(--text-muted)]">{item.label}</dt>
-                    <dd className="text-right font-medium text-[var(--text-primary)]">
+                    <dd className="text-end font-medium text-[var(--text-primary)]">
                       {item.value}
                     </dd>
                   </div>