@bearmenu/ui 0.8.9 → 0.8.10

package/src/components/qa-block.tsx

@@ -0,0 +1,60 @@
+import { cn } from "../lib/utils";
+import type { QaItem } from "./menu-types";
+
+/**
+ * QaBlock — questions answered from the numbers, as static prose.
+ *
+ * ## Never an accordion
+ *
+ * This block exists to be crawled as much as read: it is the visible half of
+ * the page's `FAQPage` markup, and the rule is that structured data must mirror
+ * content the reader can actually see. Collapsing it hides every answer from
+ * the crawler's first paint and buys nothing — three short answers are cheaper
+ * to scroll past than to expand.
+ *
+ * The caller renders the JSON-LD from the SAME array it passes here, so the
+ * markup and the visible answers cannot drift.
+ *
+ * ## Three across, then one
+ *
+ * Answers are two or three lines each, so a single column wastes the desktop
+ * measure and a two-column grid leaves an orphan. On the phone it is one
+ * column, in order.
+ */
+
+export type QaBlockProps = {
+  items: QaItem[];
+  /** Section heading, e.g. "Questions people ask". Omit where the page supplies one. */
+  heading?: string;
+  /** Heading level for the questions. Defaults to `h3`, under a page's `h2`. */
+  questionAs?: "h3" | "h4";
+  className?: string;
+};
+
+export function QaBlock({ items, heading, questionAs: Question = "h3", className }: QaBlockProps) {
+  return (
+    <section className={cn(className)}>
+      {heading && (
+        <h2 className="text-[15px] font-bold leading-tight tracking-[-0.01em]">{heading}</h2>
+      )}
+
+      <div
+        className={cn(
+          "grid grid-cols-1 gap-[18px] lg:grid-cols-3 lg:gap-[26px]",
+          heading && "mt-3.5"
+        )}
+      >
+        {items.map((item) => (
+          <div key={item.question}>
+            <Question className="text-sm font-bold leading-[1.35] tracking-[-0.01em] lg:text-[15px]">
+              {item.question}
+            </Question>
+            <p className="mt-[7px] text-[13px] leading-[1.65] text-muted-foreground [text-wrap:pretty] lg:text-[13.5px]">
+              {item.answer}
+            </p>
+          </div>
+        ))}
+      </div>
+    </section>
+  );
+}

package/src/components/snap-rail.tsx

@@ -64,13 +64,27 @@ export type SnapRailProps = React.HTMLAttributes<HTMLDivElement> &
     dots?: boolean;
     /** Classes for the dots row, e.g. `lg:hidden` where the rail becomes a grid. */
     dotsClassName?: string;
+    /**
+     * Reports the current page whenever it changes — for a caller that wants
+     * to react to the swipe beyond the dots, e.g. a backdrop that follows the
+     * active card. Tracking runs whenever this or `dots` is set.
+     */
+    onActiveChange?: (index: number) => void;
   };
 
 export const SnapRail = React.forwardRef<HTMLDivElement, SnapRailProps>(
-  ({ className, itemWidth, gap, bleed, dots, dotsClassName, children, ...props }, ref) => {
+  (
+    { className, itemWidth, gap, bleed, dots, dotsClassName, onActiveChange, children, ...props },
+    ref
+  ) => {
     const railRef = React.useRef<HTMLDivElement | null>(null);
     const [active, setActive] = React.useState(0);
     const count = React.Children.count(children);
+    const tracks = Boolean(dots || onActiveChange);
+    // A ref, so a caller passing a fresh arrow each render does not re-bind
+    // the scroll listener each render.
+    const onActiveChangeRef = React.useRef(onActiveChange);
+    onActiveChangeRef.current = onActiveChange;
 
     const setRefs = React.useCallback(
       (node: HTMLDivElement | null) => {
@@ -85,13 +99,19 @@ export const SnapRail = React.forwardRef<HTMLDivElement, SnapRailProps>(
     // the current page. Read on scroll, rAF-throttled; passive so it never
     // blocks the swipe it watches.
     React.useEffect(() => {
-      if (!dots) return;
+      if (!tracks) return;
       const rail = railRef.current;
       if (!rail) return;
       let frame = 0;
+      let last = -1;
       const sync = () => {
         frame = 0;
-        const origin = rail.scrollLeft + parseFloat(getComputedStyle(rail).scrollPaddingLeft || "0");
+        // `|| 0`, not `|| "0"` on the input: with no `scroll-px-*` the computed
+        // value is the string "auto", which parses to NaN, and every distance
+        // below became NaN — so the nearest child was never found and the page
+        // stayed at 0 forever. Only the `bleed` variants set a scroll padding,
+        // which is why every rail that used one appeared to work.
+        const origin = rail.scrollLeft + (parseFloat(getComputedStyle(rail).scrollPaddingLeft) || 0);
         let best = 0;
         let bestDistance = Number.POSITIVE_INFINITY;
         Array.from(rail.children).forEach((child, index) => {
@@ -102,6 +122,10 @@ export const SnapRail = React.forwardRef<HTMLDivElement, SnapRailProps>(
           }
         });
         setActive(best);
+        if (best !== last) {
+          last = best;
+          onActiveChangeRef.current?.(best);
+        }
       };
       const onScroll = () => {
         if (!frame) frame = requestAnimationFrame(sync);
@@ -112,7 +136,7 @@ export const SnapRail = React.forwardRef<HTMLDivElement, SnapRailProps>(
         if (frame) cancelAnimationFrame(frame);
         rail.removeEventListener("scroll", onScroll);
       };
-    }, [dots, count]);
+    }, [tracks, count]);
 
     const rail = (
       <div
@@ -130,19 +154,38 @@ export const SnapRail = React.forwardRef<HTMLDivElement, SnapRailProps>(
     return (
       <div className="flex flex-col gap-3">
         {rail}
-        <div aria-hidden className={cn("flex justify-center gap-1.5", dotsClassName)}>
-          {Array.from({ length: count }, (_, index) => (
-            <span
-              key={index}
-              className={cn(
-                "h-1.5 rounded-full transition-[width,background-color] duration-200 motion-reduce:transition-none",
-                index === active ? "w-4 bg-foreground" : "w-1.5 bg-foreground/25"
-              )}
-            />
-          ))}
-        </div>
+        <SnapRailDots count={count} active={active} className={dotsClassName} />
       </div>
     );
   }
 );
 SnapRail.displayName = "SnapRail";
+
+/**
+ * The page dots on their own, for a caller that tracks the rail through
+ * `onActiveChange` and wants the dots somewhere other than directly under it —
+ * inside a foot band, say. Decorative, as on the rail: the rail is the control.
+ */
+export function SnapRailDots({
+  count,
+  active,
+  className,
+}: {
+  count: number;
+  active: number;
+  className?: string;
+}) {
+  return (
+    <div aria-hidden className={cn("flex justify-center gap-1.5", className)}>
+      {Array.from({ length: count }, (_, index) => (
+        <span
+          key={index}
+          className={cn(
+            "h-1.5 rounded-full transition-[width,background-color] duration-200 motion-reduce:transition-none",
+            index === active ? "w-4 bg-foreground" : "w-1.5 bg-foreground/25"
+          )}
+        />
+      ))}
+    </div>
+  );
+}

package/src/components/story.tsx

@@ -0,0 +1,225 @@
+"use client";
+
+import * as React from "react";
+import { useInView } from "framer-motion";
+import { cn } from "../lib/utils";
+
+/**
+ * Story — a few things said one at a time in the same space, on a timer.
+ *
+ * The kitchen dossier has three or four things worth saying about a place —
+ * the dish it is known for, what people say, its grade — and a story says
+ * them in one panel, part after part, instead of asking for a swipe per fact.
+ * Segments at the top show how many parts there are and which one is up;
+ * the panel cross-fades between them; a tap advances, a segment jumps.
+ *
+ * ## Autoplay only while looked at
+ *
+ * The timer runs only while the story is mostly in view (`useInView`, 60%)
+ * and not pressed, so a rail of six kitchens is not six timers and
+ * a card half-scrolled away does not burn through its story unseen.
+ *
+ * It runs under `prefers-reduced-motion` too. The setting is about motion —
+ * things sliding and fading — and the cross-fade honours it through
+ * `motion-reduce:transition-none`; but a story whose segments never fill
+ * reads as a broken story, not a calmer one, and the parts still change on
+ * their own schedule as they would in a slideshow. Pressing holds it.
+ *
+ * ## Three pieces, one state
+ *
+ * The segments sit at the card's top edge and the panel in its foot, with the
+ * card's own identity between them, so the state lives in a provider and the
+ * two pieces read it. The card stays a server component: it renders the
+ * parts and hands them to `StoryPanel` as nodes.
+ *
+ * ## The panel keeps its height
+ *
+ * Every part is rendered into the same grid cell and the inactive ones are
+ * hidden in place, so the panel is as tall as its tallest part at every
+ * moment and the card does not jump as the story runs.
+ */
+
+type StoryContextValue = {
+  count: number;
+  active: number;
+  /** Progress of the active part, 0–1, for the segment fill. */
+  progress: number;
+  playing: boolean;
+  go: (index: number) => void;
+  next: () => void;
+};
+
+const StoryContext = React.createContext<StoryContextValue | null>(null);
+
+function useStory(): StoryContextValue {
+  const value = React.useContext(StoryContext);
+  if (!value) throw new Error("Story pieces must render inside StoryProvider");
+  return value;
+}
+
+export type StoryProviderProps = {
+  /** How many parts the story has. */
+  count: number;
+  /** How long each part shows. */
+  durationMs?: number;
+  /** Accessible name of the tap-to-advance, e.g. "Next". */
+  nextLabel: string;
+  className?: string;
+  children: React.ReactNode;
+};
+
+/** How often the segment fill is redrawn while playing. */
+const TICK_MS = 100;
+
+export function StoryProvider({
+  count,
+  durationMs = 5000,
+  nextLabel,
+  className,
+  children,
+}: StoryProviderProps) {
+  const ref = React.useRef<HTMLDivElement>(null);
+  const inView = useInView(ref, { amount: 0.6 });
+  const [active, setActive] = React.useState(0);
+  const [elapsed, setElapsed] = React.useState(0);
+  const [held, setHeld] = React.useState(false);
+
+  const playing = Boolean(inView && !held && count > 1);
+
+  const go = React.useCallback(
+    (index: number) => {
+      setActive(((index % count) + count) % count);
+      setElapsed(0);
+    },
+    [count]
+  );
+  const next = React.useCallback(() => go(active + 1), [go, active]);
+
+  /* Two effects, not one updater that also advances: a state updater must be
+     pure — React runs it twice in development — and an advance inside it
+     skipped every other part. The tick only counts; the roll-over is its own
+     effect. */
+  React.useEffect(() => {
+    if (!playing) return;
+    const timer = window.setInterval(() => setElapsed((previous) => previous + TICK_MS), TICK_MS);
+    return () => window.clearInterval(timer);
+  }, [playing]);
+
+  React.useEffect(() => {
+    if (elapsed < durationMs) return;
+    setActive((current) => (current + 1) % count);
+    setElapsed(0);
+  }, [elapsed, durationMs, count]);
+
+  const value = React.useMemo<StoryContextValue>(
+    () => ({ count, active, progress: Math.min(elapsed / durationMs, 1), playing, go, next }),
+    [count, active, elapsed, durationMs, playing, go, next]
+  );
+
+  /* A tap anywhere on the story that is not a link or a button advances —
+     the card's own targets (the name, the dish, the action, the segments)
+     keep theirs, and the rest of the card is "next". Keyboard readers move
+     through the segments, which are tabs. */
+  const advance = (event: React.MouseEvent<HTMLDivElement>) => {
+    if (count < 2) return;
+    if ((event.target as Element).closest("a, button")) return;
+    next();
+  };
+
+  return (
+    <StoryContext.Provider value={value}>
+      <div
+        ref={ref}
+        className={cn(count > 1 && "cursor-pointer", className)}
+        title={count > 1 ? nextLabel : undefined}
+        onClick={advance}
+        /* Held = pressed, not hovered. A cursor resting on a card is not a
+           reader holding a story still, and a hover-pause made the segments
+           look broken to anyone whose mouse happened to be over the rail. */
+        onPointerDown={() => setHeld(true)}
+        onPointerUp={() => setHeld(false)}
+        onPointerLeave={() => setHeld(false)}
+        onPointerCancel={() => setHeld(false)}
+      >
+        {children}
+      </div>
+    </StoryContext.Provider>
+  );
+}
+
+export type StorySegmentsProps = {
+  /**
+   * Accessible name per segment, one per part, e.g. `["Part 1 of 3", …]`.
+   * Strings rather than a function: a server component renders this and a
+   * function cannot cross into a client one.
+   */
+  labels: string[];
+  className?: string;
+};
+
+/** The segments: one per part, the active one filling on the timer. */
+export function StorySegments({ labels, className }: StorySegmentsProps) {
+  const { count, active, progress, go } = useStory();
+  if (count < 2) return null;
+
+  return (
+    <div className={cn("flex gap-1", className)} role="tablist">
+      {Array.from({ length: count }, (_, index) => {
+        const fill = index < active ? 1 : index === active ? progress : 0;
+        return (
+          <button
+            key={index}
+            type="button"
+            role="tab"
+            aria-selected={index === active}
+            aria-label={labels[index]}
+            onClick={() => go(index)}
+            /* A 24px tall target around a 2px bar — the bar is the visual,
+               the button is the thumb's. */
+            className="group/segment flex h-6 flex-1 items-center focus-visible:outline-none"
+          >
+            <span className="relative block h-[3px] w-full overflow-hidden rounded-full bg-white/25 group-focus-visible/segment:ring-2 group-focus-visible/segment:ring-white/70">
+              <span
+                className="absolute inset-y-0 left-0 rounded-full bg-white"
+                style={{ width: `${fill * 100}%` }}
+              />
+            </span>
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+export type StoryPanelProps = {
+  /** The parts, in order. Rendered by the caller; shown one at a time. */
+  parts: React.ReactNode[];
+  className?: string;
+};
+
+/** The panel: every part in one cell, the active one visible. */
+export function StoryPanel({ parts, className }: StoryPanelProps) {
+  const { active } = useStory();
+
+  return (
+    <div className={cn("relative", className)}>
+      <div className="grid [&>*]:col-start-1 [&>*]:row-start-1">
+        {parts.map((part, index) => {
+          const isActive = index === active;
+          return (
+            <div
+              key={index}
+              aria-hidden={!isActive}
+              className={cn(
+                "transition-[opacity,transform] duration-200 ease-out motion-reduce:transition-none",
+                isActive ? "opacity-100" : "pointer-events-none invisible translate-y-1.5 opacity-0"
+              )}
+            >
+              {part}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/src/components/top-comparison.stories.tsx

@@ -0,0 +1,78 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { TopComparison } from "./top-comparison";
+import type { TopComparisonRow } from "./top-types";
+
+const rows: TopComparisonRow[] = [
+  ["Salt & Stone", "9.4", "Truffle Tagliatelle", "62 lei", true, true],
+  ["The Copper Yard", "9.1", "Carbonara", "48 lei", false, true],
+  ["Osteria Mica", "8.9", "Pizza Margherita", "38 lei", false, false],
+  ["Il Forno", "8.7", "Pizza Diavola", "44 lei", true, true],
+  ["Vecchio Mulino", "8.6", "Cacio e pepe", "46 lei", false, true],
+  ["La Nonna", "8.4", "Lasagne al forno", "54 lei", false, false],
+  ["Pasta Fresca", "8.1", "Gnocchi al pesto", "24 lei", false, false],
+].map(([name, gradeLabel, signature, priceLabel, late, terrace], index) => ({
+  rank: index + 1,
+  name: String(name),
+  href: `/places/${String(name).toLowerCase().replace(/[^a-z]+/g, "-")}`,
+  gradeLabel: String(gradeLabel),
+  signature: String(signature),
+  priceLabel: String(priceLabel),
+  late: Boolean(late),
+  terrace: Boolean(terrace),
+}));
+
+const labels = {
+  venue: "Kitchen",
+  grade: "Grade",
+  signature: "Signature",
+  price: "Price",
+  late: "Past midnight",
+  terrace: "Terrace",
+  yes: "yes",
+  no: "no",
+};
+
+const meta: Meta<typeof TopComparison> = {
+  title: "Top/TopComparison",
+  component: TopComparison,
+  tags: ["autodocs"],
+  args: { rows, labels, caption: "The ranking side by side" },
+  decorators: [
+    (Story) => (
+      <div className="w-[1000px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The only place in the product where you can compare the whole shortlist on the same axes, and it is static so it costs nothing. **A table on desktop, a ranked strip on the phone**: seven columns at 358px is unreadable, and a horizontally scrolling table hides the column you are comparing — which is the one thing the control exists to do. Two renderings of one dataset, so they cannot disagree. A *no* cell carries screen-reader text rather than being an empty dash.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TopComparison>;
+
+export const Default: Story = {};
+
+/** The strip, which is what the table becomes under `lg`. */
+export const Mobile: Story = {
+  decorators: [
+    (Story) => (
+      <div className="w-[390px] bg-background p-3">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+/** Missing facts render as dashes, never as blanks that read as "no". */
+export const Sparse: Story = {
+  args: {
+    rows: rows.slice(0, 3).map((row) => ({ ...row, signature: undefined, priceLabel: undefined })),
+  },
+};

package/src/components/top-comparison.tsx

@@ -0,0 +1,151 @@
+import { Moon, Sun } from "lucide-react";
+import { cn } from "../lib/utils";
+import type { MenuLinkComponent, MenuLinkProps } from "./menu-types";
+import type { TopComparisonRow } from "./top-types";
+
+/**
+ * TopComparison — the ranking side by side.
+ *
+ * The only place in the product where you can compare the whole shortlist at
+ * once on the same axes, and it costs nothing because it is static. It is not
+ * a filter: narrowing links out to the browsing tool.
+ *
+ * ## A table on desktop, a ranked strip on the phone
+ *
+ * Seven columns at 358px is unreadable, and a horizontally scrolling table
+ * hides the column you are comparing — which is the one thing the control
+ * exists to do. The strip keeps the side-by-side scan, which is the table's
+ * actual job, by dropping to the four facts that fit: rank, name, signature
+ * with its price, and the grade, with late and terrace as glyphs.
+ *
+ * Two renderings of one dataset, so they cannot disagree.
+ */
+
+function DefaultLink({ href, ...props }: MenuLinkProps) {
+  return <a href={href} {...props} />;
+}
+
+export type TopComparisonLabels = {
+  venue: string;
+  grade: string;
+  signature: string;
+  price: string;
+  late: string;
+  terrace: string;
+  /** Screen-reader text for a "no" cell — never an empty cell. */
+  no: string;
+  yes: string;
+};
+
+export type TopComparisonProps = {
+  rows: TopComparisonRow[];
+  labels: TopComparisonLabels;
+  /** Accessible name for the table. */
+  caption: string;
+  linkComponent?: MenuLinkComponent;
+  className?: string;
+};
+
+export function TopComparison({
+  rows,
+  labels,
+  caption,
+  linkComponent: LinkComponent = DefaultLink,
+  className,
+}: TopComparisonProps) {
+  return (
+    <div className={className}>
+      {/* Desktop: the full table. `overflow-x-auto` on the wrapper so a narrow
+          desktop window scrolls the table rather than the page. */}
+      <div className="hidden overflow-x-auto lg:block">
+        <table className="w-full border-collapse text-[13px]">
+          <caption className="sr-only">{caption}</caption>
+          <thead>
+            <tr className="border-b border-border text-left text-[11px] font-bold uppercase tracking-[0.07em] text-muted-foreground">
+              <th scope="col" className="w-10 py-2 font-bold">
+                <span className="sr-only">#</span>
+              </th>
+              <th scope="col" className="py-2 font-bold">{labels.venue}</th>
+              <th scope="col" className="py-2 font-bold">{labels.grade}</th>
+              <th scope="col" className="py-2 font-bold">{labels.signature}</th>
+              <th scope="col" className="py-2 font-bold">{labels.price}</th>
+              <th scope="col" className="py-2 font-bold">{labels.late}</th>
+              <th scope="col" className="py-2 font-bold">{labels.terrace}</th>
+            </tr>
+          </thead>
+          <tbody>
+            {rows.map((row) => (
+              <tr key={row.name} className="border-b border-border/60">
+                <td className="py-2.5 tabular-nums text-muted-foreground">
+                  {String(row.rank).padStart(2, "0")}
+                </td>
+                <td className="py-2.5 font-semibold">
+                  <LinkComponent
+                    href={row.href}
+                    className="hover:text-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                  >
+                    {row.name}
+                  </LinkComponent>
+                </td>
+                <td className="py-2.5 font-bold tabular-nums text-accent">{row.gradeLabel ?? "—"}</td>
+                <td className="py-2.5 text-muted-foreground">{row.signature ?? "—"}</td>
+                <td className="py-2.5 tabular-nums">{row.priceLabel ?? "—"}</td>
+                <td className="py-2.5">
+                  <Mark on={row.late} yes={labels.yes} no={labels.no} />
+                </td>
+                <td className="py-2.5">
+                  <Mark on={row.terrace} yes={labels.yes} no={labels.no} />
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+
+      {/* Phone: one row per venue. */}
+      <ul className="lg:hidden">
+        {rows.map((row) => (
+          <li key={row.name} className="border-t border-border first:border-t-0">
+            <LinkComponent
+              href={row.href}
+              className="flex items-center gap-3 py-2.5 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring"
+            >
+              <span className="w-6 shrink-0 text-[13px] font-bold tabular-nums text-muted-foreground">
+                {String(row.rank).padStart(2, "0")}
+              </span>
+              <span className="min-w-0 flex-1">
+                <span className="block truncate text-[13.5px] font-bold">{row.name}</span>
+                {(row.signature || row.priceLabel) && (
+                  <span className="block truncate text-[11.5px] text-muted-foreground">
+                    {[row.signature, row.priceLabel].filter(Boolean).join(" · ")}
+                  </span>
+                )}
+              </span>
+              <span className="flex shrink-0 items-center gap-1 text-muted-foreground">
+                {row.late && <Moon className="h-3.5 w-3.5" aria-label={labels.late} />}
+                {row.terrace && <Sun className="h-3.5 w-3.5" aria-label={labels.terrace} />}
+              </span>
+              {row.gradeLabel && (
+                <span className="shrink-0 text-[13px] font-extrabold tabular-nums text-accent">
+                  {row.gradeLabel}
+                </span>
+              )}
+            </LinkComponent>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+/** A yes/no cell that a screen reader can read — never a bare dash. */
+function Mark({ on, yes, no }: { on?: boolean; yes: string; no: string }) {
+  return on ? (
+    <span className="font-semibold text-[color:var(--free,oklch(0.45_0.13_155))]">{yes}</span>
+  ) : (
+    <span className="text-muted-foreground">
+      <span aria-hidden>—</span>
+      <span className="sr-only">{no}</span>
+    </span>
+  );
+}