@bearmenu/ui 0.8.21 → 0.8.23

package/src/components/coach-marks.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useEffect, useLayoutEffect, useState } from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import { ArrowRight, Lightbulb } from "lucide-react";
 import { cn } from "../lib/utils";
@@ -31,9 +31,26 @@ import { Button } from "./button";
  * side, re-measure on scroll and resize) and the keys (Escape closes, the
  * arrows step). `onProgress` reports the current stop for a toolbar label.
  *
- * Rendered into `document.body`: a page wrapper with an opacity or transform
- * transition is a stacking context, and the tour must sit above everything
- * the page and its chrome draw, whatever wraps the consumer.
+ * The spotlight is a hole in the dimming, in hit-testing as well as in
+ * paint: a tap on the ringed control reaches it. A gold ring around a real,
+ * un-dimmed control is an invitation, and a tour that swallowed the tap
+ * would be lying. Acting ends the tour — the thing the reader opened is the
+ * lesson, and whatever it opened would otherwise sit under or over an
+ * `aria-modal` dialog that promises the page beneath is inert. The consumer
+ * has already heard the stop through `onProgress`, so a "N new" door can
+ * pick the tour up later. The dimmed page itself does not close the tour: a
+ * thumb resting on it while reading is not a decision.
+ *
+ * A target is scrolled into view only when it is not already in it. The
+ * page's fixed chrome (`inset`) narrows what "in view" means, and a stop can
+ * opt out of scrolling altogether (`scroll: false`): `scrollIntoView` on a
+ * pinned rail scrolls the document to the rail's in-flow position, which is
+ * the top of whatever it pins over, and a reader mid-feed loses their place.
+ *
+ * Rendered into `document.body` above every drawer, sheet and dialog: a page
+ * wrapper with an opacity or transform transition is a stacking context, and
+ * the tour must sit above everything the page and its chrome draw, whatever
+ * wraps the consumer.
  */
 
 export type CoachMarkStop = {
@@ -41,6 +58,25 @@ export type CoachMarkStop = {
   id: string;
   title: string;
   body: string;
+  /**
+   * A `control` (a button, a field, a toggle) wears the gold ring; a `region`
+   * (a list, a rail, a block) is defined by the cut-out's edge alone. Stated,
+   * not inferred: a toggle group is a div of buttons and a results region a
+   * list of links. Defaults to `control`.
+   */
+  kind?: "control" | "region";
+  /**
+   * Never scroll to this target — for a control pinned to the viewport, whose
+   * box says where it is but whose in-flow position is somewhere else.
+   * Defaults to scrolling when the target is out of view.
+   */
+  scroll?: boolean;
+};
+
+/** The viewport's fixed chrome: what a target must clear to count as in view. */
+export type CoachMarksInset = {
+  top?: number;
+  bottom?: number;
 };
 
 export type CoachMarksLabels = {
@@ -56,7 +92,7 @@ export type CoachMarksLabels = {
 export type CoachMarksProps = {
   open: boolean;
   stops: CoachMarkStop[];
-  /** Skip, Done, Escape and a tap on the dimmed page all end here. */
+  /** Skip, Done, Escape and a tap on the spotlit target all end here. */
   onClose: () => void;
   /**
    * 1-based position, the count of stops the page actually has, and the
@@ -65,6 +101,8 @@ export type CoachMarksProps = {
    */
   onProgress?: (step: number, total: number, stop: CoachMarkStop) => void;
   labels: CoachMarksLabels;
+  /** The page's fixed header and bottom bar, in px; the callout keeps clear of them too. */
+  inset?: CoachMarksInset;
   className?: string;
 };
 
@@ -76,11 +114,28 @@ const CALLOUT_GAP = 14;
 /** The room a side needs before the callout goes there. */
 const CALLOUT_ROOM = 280;
 const EDGE = 12;
+/** The pin's disc. */
+const PIN_SIZE = 32;
+/** A target this small has its pin on the spotlight's corner, not over its own. */
+const PIN_SNAP = 56;
+/** The caret's inset from the callout's ends. */
+const CARET_MARGIN = 16;
 
 /** The step number, an inverted disc on the spotlight's corner: dark on the gold ring. */
 const PIN =
   "pointer-events-none absolute z-[1] flex h-8 w-8 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-full bg-[oklch(0.26_0.03_60)] text-[13px] font-extrabold text-[oklch(0.82_0.15_85)] ring-2 ring-[oklch(0.82_0.15_85)] shadow-[0_2px_8px_oklch(0.16_0.012_55_/_0.45)] transition-[top,left] duration-300 motion-reduce:transition-none";
 
+/**
+ * The dimming with the spotlight cut out of it: one polygon drawn around the
+ * viewport and again around the spot, even-odd, so the spot is a hole in
+ * hit-testing as much as in paint.
+ */
+function dimClip(spot: Rect, viewport: { width: number; height: number }): string {
+  const right = spot.left + spot.width;
+  const bottom = spot.top + spot.height;
+  return `polygon(evenodd, 0 0, ${viewport.width}px 0, ${viewport.width}px ${viewport.height}px, 0 ${viewport.height}px, 0 0, ${spot.left}px ${spot.top}px, ${spot.left}px ${bottom}px, ${right}px ${bottom}px, ${right}px ${spot.top}px, ${spot.left}px ${spot.top}px)`;
+}
+
 /** The visible element carrying the id — a `display: none` twin has no boxes. */
 function findTarget(id: string): HTMLElement | null {
   if (typeof document === "undefined") return null;
@@ -96,11 +151,31 @@ function measure(element: HTMLElement): Rect {
   return { top: box.top, left: box.left, width: box.width, height: box.height };
 }
 
-export function CoachMarks({ open, stops, onClose, onProgress, labels, className }: CoachMarksProps) {
+/** Whole target inside the band the chrome leaves, with its breathing room. */
+function inView(element: HTMLElement, inset: CoachMarksInset): boolean {
+  const box = element.getBoundingClientRect();
+  return (
+    box.top - PAD >= (inset.top ?? 0) &&
+    box.bottom + PAD <= window.innerHeight - (inset.bottom ?? 0)
+  );
+}
+
+const NO_INSET: CoachMarksInset = {};
+
+export function CoachMarks({
+  open,
+  stops,
+  onClose,
+  onProgress,
+  labels,
+  inset = NO_INSET,
+  className,
+}: CoachMarksProps) {
   // The stops the page can show, fixed when the tour opens or the itinerary
   // changes — by its ids, so a consumer rebuilding the array each render does
-  // not send the tour back to the first stop.
-  const [available, setAvailable] = useState<CoachMarkStop[]>([]);
+  // not send the tour back to the first stop. The words are read live from
+  // `stops`, so a consumer may reword a stop without restarting the tour.
+  const [available, setAvailable] = useState<string[]>([]);
   const [index, setIndex] = useState(0);
   const [rect, setRect] = useState<Rect | null>(null);
   const [viewport, setViewport] = useState({ width: 0, height: 0 });
@@ -108,7 +183,7 @@ export function CoachMarks({ open, stops, onClose, onProgress, labels, className
 
   useLayoutEffect(() => {
     if (!open) return;
-    const present = stops.filter((stop) => findTarget(stop.id));
+    const present = stops.filter((stop) => findTarget(stop.id)).map((stop) => stop.id);
     setAvailable(present);
     setIndex(0);
     if (present.length === 0) onClose();
@@ -116,8 +191,13 @@ export function CoachMarks({ open, stops, onClose, onProgress, labels, className
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [open, itinerary]);
 
-  const current = available[index];
-  const currentId = current?.id;
+  const currentId = available[index];
+  const current = currentId ? stops.find((stop) => stop.id === currentId) : undefined;
+  const scrolls = current?.scroll !== false;
+  // Primitives, so a consumer passing `inset={{ top: 68 }}` inline — or
+  // rebuilding `stops` each render — does not re-run the effects below.
+  const insetTop = inset.top ?? 0;
+  const insetBottom = inset.bottom ?? 0;
 
   const remeasure = useCallback(() => {
     const element = currentId ? findTarget(currentId) : null;
@@ -125,28 +205,54 @@ export function CoachMarks({ open, stops, onClose, onProgress, labels, className
     setViewport({ width: window.innerWidth, height: window.innerHeight });
   }, [currentId]);
 
-  // Bring the current target into view, then measure it — again once the
-  // smooth scroll has settled.
+  // Bring the current target into view when it is not, then measure it —
+  // again once the smooth scroll has settled.
   useLayoutEffect(() => {
-    if (!open || !current) return;
-    const element = findTarget(current.id);
+    if (!open || !currentId) return;
+    const element = findTarget(currentId);
     if (!element) {
       // The page changed under the tour: move on, or end when nothing is left.
-      const forward = available.findIndex((stop, at) => at > index && findTarget(stop.id));
+      const forward = available.findIndex((id, at) => at > index && findTarget(id));
       if (forward !== -1) setIndex(forward);
       else onClose();
       return;
     }
-    element.scrollIntoView({ block: "center", behavior: "smooth", inline: "nearest" });
+    if (scrolls) {
+      // Always a scroll request, even for a target already in view: a new
+      // request aborts the previous stop's smooth scroll, which would
+      // otherwise carry on under this one and leave it off screen. A target
+      // taller than the band aligns to the band's top — centring a
+      // three-screen region scrolls into its middle — with `scroll-margin`
+      // standing in for the chrome, which `scrollIntoView` cannot see.
+      const band = window.innerHeight - insetTop - insetBottom;
+      const tall = element.getBoundingClientRect().height + PAD * 2 > band;
+      const visible = inView(element, { top: insetTop, bottom: insetBottom });
+      element.style.scrollMarginTop = `${insetTop + PAD}px`;
+      element.scrollIntoView({
+        block: visible ? "nearest" : tall ? "start" : "center",
+        behavior: "smooth",
+        inline: "nearest",
+      });
+    }
     remeasure();
     const settle = setTimeout(remeasure, 400);
-    return () => clearTimeout(settle);
-  }, [open, current, index, available, remeasure, onClose]);
+    return () => {
+      clearTimeout(settle);
+      element.style.scrollMarginTop = "";
+    };
+  }, [open, currentId, scrolls, index, available, insetTop, insetBottom, remeasure, onClose]);
 
+  // Reported once per stop — not once per rewording of it, nor once per
+  // consumer render when the callback is written inline.
+  const progressRef = useRef(onProgress);
+  useLayoutEffect(() => {
+    progressRef.current = onProgress;
+  });
   useEffect(() => {
     if (!open || !current) return;
-    onProgress?.(index + 1, available.length, current);
-  }, [open, current, index, available.length, onProgress]);
+    progressRef.current?.(index + 1, available.length, current);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open, currentId, index, available.length]);
 
   useEffect(() => {
     if (!open) return;
@@ -157,91 +263,144 @@ export function CoachMarks({ open, stops, onClose, onProgress, labels, className
       if (event.key === "ArrowRight") setIndex((at) => Math.min(at + 1, available.length - 1));
       if (event.key === "ArrowLeft") setIndex((at) => Math.max(at - 1, 0));
     };
+    // The reader acted, and the tour steps out of the way. Capture phase: a
+    // control that stops propagation (a button nested in a larger tap
+    // target) would otherwise never be heard. The target's own handler still
+    // runs — closing the tour changes nothing under it.
+    const onClick = (event: MouseEvent) => {
+      const target = currentId ? findTarget(currentId) : null;
+      if (target && event.target instanceof Node && target.contains(event.target)) onClose();
+    };
     window.addEventListener("keydown", onKey);
+    window.addEventListener("click", onClick, true);
     return () => {
       window.removeEventListener("resize", remeasure);
       window.removeEventListener("scroll", remeasure, true);
       window.removeEventListener("keydown", onKey);
+      window.removeEventListener("click", onClick, true);
     };
-  }, [open, remeasure, onClose, available.length]);
+  }, [open, currentId, remeasure, onClose, available.length]);
 
   if (!open || !current || !rect) return null;
 
   const last = index === available.length - 1;
+  const region = current.kind === "region";
   const spot = {
     top: rect.top - PAD,
     left: rect.left - PAD,
     width: rect.width + PAD * 2,
     height: rect.height + PAD * 2,
   };
+  // The pin sits on the spotlight's corner for a small target — over its own
+  // corner it would cover a quarter of a 44px disc — and drops to the bottom
+  // corner when the top one would sit under the page's chrome.
+  const small = rect.width <= PIN_SNAP || rect.height <= PIN_SNAP;
+  const pinLeft = small ? spot.left : rect.left - 2;
+  const pinTop =
+    spot.top - PIN_SIZE / 2 < insetTop + EDGE
+      ? spot.top + spot.height
+      : small
+        ? spot.top
+        : rect.top - 2;
   // Below the target when there is room for the callout, else above it; a
-  // target taller than the viewport leaves room on neither side, and the
-  // callout then sits at the bottom edge, over the target's lower part.
-  const roomBelow = viewport.height - (spot.top + spot.height);
+  // target taller than the band leaves room on neither side, and the callout
+  // then sits at the band's bottom edge, over the target's lower part. The
+  // band is the viewport less the page's fixed chrome.
+  const bandTop = insetTop;
+  const bandBottom = viewport.height - insetBottom;
+  const roomBelow = bandBottom - (spot.top + spot.height);
+  const roomAbove = spot.top - bandTop;
   const calloutLeft = Math.min(
     Math.max(spot.left, EDGE),
     Math.max(EDGE, viewport.width - CALLOUT_WIDTH - EDGE)
   );
+  const side: "below" | "above" | "edge" =
+    roomBelow > CALLOUT_ROOM ? "below" : roomAbove > CALLOUT_ROOM ? "above" : "edge";
   const calloutPlace =
-    roomBelow > CALLOUT_ROOM
+    side === "below"
       ? { top: spot.top + spot.height + CALLOUT_GAP, left: calloutLeft }
-      : spot.top > CALLOUT_ROOM
+      : side === "above"
         ? { bottom: viewport.height - spot.top + CALLOUT_GAP, left: calloutLeft }
-        : { bottom: EDGE, left: calloutLeft };
+        : { bottom: viewport.height - bandBottom + EDGE, left: calloutLeft };
+  // The caret points at the spot's centre: a disc at the right edge leaves
+  // the callout 260px from its target with nothing between them otherwise.
+  const calloutWidth = Math.min(CALLOUT_WIDTH, viewport.width - EDGE * 2);
+  const caretLeft = Math.min(
+    Math.max(spot.left + spot.width / 2 - calloutLeft, CARET_MARGIN),
+    calloutWidth - CARET_MARGIN
+  );
 
   return createPortal(
     <div
-      className={cn("fixed inset-0 z-[80]", className)}
+      className={cn("pointer-events-none fixed inset-0 z-[1100]", className)}
       role="dialog"
       aria-modal
       aria-label={current.title}
     >
-      {/* The dimming is the spotlight's shadow: one element, cut out where
-          the target is, so the target stays fully visible and the rest of the
-          page falls back. A tap on the dim closes the tour. */}
-      <button
-        type="button"
-        aria-label={labels.skip}
-        onClick={onClose}
-        className="absolute inset-0 cursor-default"
+      {/* The dimming: one layer blocking the page, with the spotlight cut out
+          of it, so the target stays fully visible AND tappable. The scrim is
+          drawn by the spotlight's shadow beneath. */}
+      <div
+        aria-hidden
+        className="pointer-events-auto absolute inset-0"
+        style={{ clipPath: dimClip(spot, viewport) }}
       />
       <div
         aria-hidden
-        className="pointer-events-none absolute rounded-[18px] shadow-[0_0_0_9999px_oklch(0.16_0.012_55_/_0.55)] ring-2 ring-[oklch(0.82_0.15_85)] transition-[top,left,width,height] duration-300 motion-reduce:transition-none"
+        className={cn(
+          "pointer-events-none absolute shadow-[0_0_0_9999px_oklch(0.16_0.012_55_/_0.55)] transition-[top,left,width,height] duration-300 motion-reduce:transition-none",
+          region ? "rounded-2xl" : "rounded-[18px] ring-2 ring-[oklch(0.82_0.15_85)]"
+        )}
         style={spot}
       />
 
       {/* The step number on the spotlight's corner; the callout says the rest. */}
-      <span aria-hidden className={PIN} style={{ top: rect.top - 2, left: rect.left - 2 }}>
+      <span aria-hidden className={PIN} style={{ top: pinTop, left: pinLeft }}>
         {index + 1}
       </span>
 
       {/* The callout. */}
       <div
-        className="absolute z-[2] w-[min(320px,calc(100vw-24px))] rounded-2xl border border-border bg-card p-4 text-card-foreground shadow-xl"
+        className="pointer-events-auto absolute z-[2] w-[min(320px,calc(100vw-24px))] rounded-2xl border border-border bg-card p-4 text-card-foreground shadow-[var(--shadow-overlay)]"
         style={calloutPlace}
       >
-        <span className="inline-flex items-center gap-1.5 rounded-full bg-[oklch(0.82_0.15_85)] px-2.5 py-1 text-[10.5px] font-extrabold uppercase tracking-[0.08em] text-[oklch(0.26_0.03_60)]">
+        {side !== "edge" && (
+          <span
+            aria-hidden
+            className={cn(
+              "absolute h-3 w-3 -translate-x-1/2 rotate-45 border-border bg-card",
+              side === "below" ? "-top-[7px] border-l border-t" : "-bottom-[7px] border-b border-r"
+            )}
+            style={{ left: caretLeft }}
+          />
+        )}
+        <span className="inline-flex items-center gap-1.5 rounded-full bg-[oklch(0.82_0.15_85)] px-2.5 py-1 text-xs font-extrabold uppercase tracking-[0.08em] text-[oklch(0.26_0.03_60)]">
           <Lightbulb className="h-3 w-3" aria-hidden />
           {labels.progress(index + 1, available.length)}
         </span>
-        <p className="mt-3 text-[15px] font-bold leading-snug">{current.title}</p>
+        <p className="mt-3 text-base font-semibold leading-snug">{current.title}</p>
         <p className="mt-1.5 text-sm leading-relaxed text-muted-foreground">{current.body}</p>
         <div className="mt-4 flex items-center gap-2">
           {index > 0 && (
-            <Button type="button" variant="ghost" size="sm" onClick={() => setIndex(index - 1)}>
+            <Button type="button" variant="ghost" size="pill" onClick={() => setIndex(index - 1)}>
               {labels.back}
             </Button>
           )}
           <Button
             type="button"
-            size="sm"
+            size="pill"
             onClick={() => (last ? onClose() : setIndex(index + 1))}
           >
             {last ? labels.done : labels.next}
             {!last && <ArrowRight aria-hidden />}
           </Button>
-          <Button type="button" variant="link" size="sm" className="ml-auto" onClick={onClose}>
+          <Button
+            type="button"
+            variant="link"
+            size="sm"
+            className="ml-auto min-h-11"
+            onClick={onClose}
+          >
             {labels.skip}
           </Button>
         </div>

package/src/components/grade-atom.test.tsx

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { GradeAtom, type GradeAtomLabels } from "./grade-atom";
+
+const labels: GradeAtomLabels = {
+  soft: "Worth exploring",
+  bands: { exceptional: "Exceptional", great: "Great", good: "Good", decent: "Decent", weak: "Weak" },
+  aria: (value) => `Grade ${value} out of 10`,
+  capped: "Capped for low confidence",
+};
+
+describe("GradeAtom", () => {
+  it("prints the grade with a dot and no trailing .0 by default", () => {
+    render(<GradeAtom grade={{ overall: 8.74 }} labels={labels} size="md" />);
+    expect(screen.getByLabelText("Grade 8.7 out of 10")).toHaveTextContent("8.7");
+    render(<GradeAtom grade={{ overall: 9 }} labels={labels} size="md" />);
+    expect(screen.getByLabelText("Grade 9 out of 10")).toHaveTextContent("9");
+  });
+
+  it("lets the labels write the number their locale's way, in the pill and in the aria name", () => {
+    const ro: GradeAtomLabels = { ...labels, value: (n) => n.toFixed(1).replace(".", ","), aria: (v) => `Nota ${v} din 10` };
+    render(<GradeAtom grade={{ overall: 8.74 }} labels={ro} size="md" />);
+    expect(screen.getByLabelText("Nota 8,7 din 10")).toHaveTextContent("8,7");
+  });
+
+  it("hands the formatter the rounded, clamped grade", () => {
+    const seen: number[] = [];
+    const spy: GradeAtomLabels = { ...labels, value: (n) => (seen.push(n), String(n)) };
+    render(<GradeAtom grade={{ overall: 12.26 }} labels={spy} size="md" />);
+    expect(seen).toEqual([10]);
+  });
+});

package/src/components/grade-atom.tsx

@@ -41,6 +41,13 @@ export type GradeAtomLabels = {
   aria: (value: string) => string;
   /** Title + aria suffix when `grade.capped`, e.g. "Capped for low confidence". */
   capped: string;
+  /**
+   * The number as the locale writes it, e.g. `8,7` in Romanian. Receives the
+   * grade already rounded to one decimal; return the glyphs to print. Defaults
+   * to `formatGrade` (`8.7`, a trailing `.0` dropped). It is a label because the
+   * decimal mark is translation, not styling — and `aria` gets the same string.
+   */
+  value?: (overall: number) => string;
 };
 
 export type GradeAtomProps = {
@@ -221,7 +228,7 @@ export function GradeAtom({
   }
 
   const band = resolveGradeBand(overall);
-  const value = formatGrade(overall);
+  const value = labels.value ? labels.value(Math.round(Math.min(10, Math.max(1, overall)) * 10) / 10) : formatGrade(overall);
   const descriptor = labels.bands[band];
   const showDesc = sz.showDesc && !hideDescriptor;
   const photo = onPhoto ? BAND_CLASSES_PHOTO[band] : null;