@bearmenu/ui 0.8.8 → 0.8.10

package/src/components/snap-rail.tsx

@@ -32,6 +32,8 @@ const snapRailVariants = cva(
         sm: "[&>*]:w-[46%]",
         md: "[&>*]:w-[60%]",
         lg: "[&>*]:w-[80%]",
+        /** One card per view — pair with `dots` so the reader knows there is more. */
+        full: "[&>*]:w-full",
       },
       gap: {
         sm: "gap-2",
@@ -52,16 +54,138 @@ const snapRailVariants = cva(
 );
 
 export type SnapRailProps = React.HTMLAttributes<HTMLDivElement> &
-  VariantProps<typeof snapRailVariants>;
+  VariantProps<typeof snapRailVariants> & {
+    /**
+     * Page dots under the rail, one per child, the current one filled. For
+     * `itemWidth="full"`, where no next card peeks in to say there is more.
+     * Decorative: the rail itself is the control, and every card is reachable
+     * by scrolling, so the dots are `aria-hidden`.
+     */
+    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, ...props }, ref) => (
-    <div
-      ref={ref}
-      data-slot="snap-rail"
-      className={cn(snapRailVariants({ itemWidth, gap, bleed }), className)}
-      {...props}
-    />
-  )
+  (
+    { 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) => {
+        railRef.current = node;
+        if (typeof ref === "function") ref(node);
+        else if (ref) ref.current = node;
+      },
+      [ref]
+    );
+
+    // The child whose left edge is nearest the rail's scroll-padding edge is
+    // the current page. Read on scroll, rAF-throttled; passive so it never
+    // blocks the swipe it watches.
+    React.useEffect(() => {
+      if (!tracks) return;
+      const rail = railRef.current;
+      if (!rail) return;
+      let frame = 0;
+      let last = -1;
+      const sync = () => {
+        frame = 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) => {
+          const distance = Math.abs((child as HTMLElement).offsetLeft - origin);
+          if (distance < bestDistance) {
+            bestDistance = distance;
+            best = index;
+          }
+        });
+        setActive(best);
+        if (best !== last) {
+          last = best;
+          onActiveChangeRef.current?.(best);
+        }
+      };
+      const onScroll = () => {
+        if (!frame) frame = requestAnimationFrame(sync);
+      };
+      sync();
+      rail.addEventListener("scroll", onScroll, { passive: true });
+      return () => {
+        if (frame) cancelAnimationFrame(frame);
+        rail.removeEventListener("scroll", onScroll);
+      };
+    }, [tracks, count]);
+
+    const rail = (
+      <div
+        ref={setRefs}
+        data-slot="snap-rail"
+        className={cn(snapRailVariants({ itemWidth, gap, bleed }), className)}
+        {...props}
+      >
+        {children}
+      </div>
+    );
+
+    if (!dots) return rail;
+
+    return (
+      <div className="flex flex-col gap-3">
+        {rail}
+        <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/stat-banner.stories.tsx

@@ -0,0 +1,100 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { ArrowRight } from "lucide-react";
+import { Button } from "./button";
+import { StatBanner } from "./stat-banner";
+
+const meta: Meta<typeof StatBanner> = {
+  title: "Menu/StatBanner",
+  component: StatBanner,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="w-[520px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "One claim about the catalogue, carried by a single number. These sit between the modules that list things and give the page somewhere to STATE what it knows rather than only showing it. Two side by side is the usual arrangement, which is a caller's grid rather than a `StatBannerPair` component — pairing is layout, and a consumer wanting one, three, or a different order should not have to fight a wrapper. Pass `scale` only when all three values come from the same real measurement.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof StatBanner>;
+
+export const Dark: Story = {
+  args: {
+    tone: "dark",
+    kicker: "ONE DISH, A DOZEN NAMES",
+    headline: "“Margherita” appears on eighty-seven menus and never twice the same way.",
+    body: "We match them anyway, so the price comparison is real.",
+    watermark: "12",
+    action: (
+      <Button size="sm" variant="secondary">
+        How concepts work
+      </Button>
+    ),
+  },
+};
+
+export const Warm: Story = {
+  args: {
+    tone: "warm",
+    kicker: "THE REVIEW CENSUS",
+    figure: "100",
+    figureUnit: "%",
+    body: "Every one of the 45,140 items carries a mention count read from the reviews. The typical dish is named twelve times; the most-named, sixty-eight.",
+    scale: ["1", "12", "68"],
+    action: (
+      <Button size="sm" variant="ghost">
+        How the census works
+        <ArrowRight className="h-3.5 w-3.5" />
+      </Button>
+    ),
+  },
+};
+
+/** The pair, as the hub arranges it — a caller's grid, not a component. */
+export const AsAPair: Story = {
+  render: () => (
+    <div className="grid gap-5 lg:grid-cols-2">
+      <StatBanner
+        tone="dark"
+        kicker="ONE DISH, A DOZEN NAMES"
+        headline="Eighty-seven menus, a dozen names."
+        watermark="12"
+      />
+      <StatBanner
+        tone="warm"
+        kicker="THE REVIEW CENSUS"
+        figure="100"
+        figureUnit="%"
+        body="A mention count on every item in the catalogue."
+        scale={["1", "12", "68"]}
+      />
+    </div>
+  ),
+  decorators: [
+    (Story) => (
+      <div className="w-[1000px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+/** No scale — because nothing counted the distribution. */
+export const WithoutScale: Story = {
+  args: {
+    tone: "warm",
+    kicker: "THE WIDEST SPREAD WE FOUND",
+    figure: "4.99",
+    figureUnit: "— 30 lei",
+    body: "The same espresso, across the ninety-eight bars and cafés that pour one.",
+  },
+};

package/src/components/stat-banner.tsx

@@ -0,0 +1,117 @@
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../lib/utils";
+
+/**
+ * StatBanner — one claim about the catalogue, carried by a single number.
+ *
+ * These sit between the modules that list things and give the page somewhere to
+ * state what it knows rather than only showing it. Two side by side is the
+ * usual arrangement, which is a caller's grid rather than a `StatBannerPair`
+ * component — pairing is layout, and a consumer wanting one, or three, or a
+ * different order should not have to fight a wrapper for it.
+ *
+ * `scale` draws the distribution the figure sits in — low, the figure, high.
+ * Pass it only when all three are real numbers from the same measurement; a
+ * scale invented around a figure is worse than no scale, because it implies a
+ * spread nobody counted.
+ *
+ * Server-safe.
+ */
+
+const bannerVariants = cva(
+  "relative flex flex-col gap-2 overflow-hidden rounded-[18px] p-5",
+  {
+    variants: {
+      tone: {
+        /** Dark ground, for the claim that needs the most weight. */
+        dark: "bg-[oklch(0.21_0.012_55)] text-white",
+        /** Tinted ground, for the supporting figure beside it. */
+        warm: "bg-accent-subtle text-foreground",
+      },
+    },
+    defaultVariants: { tone: "dark" },
+  }
+);
+
+export type StatBannerProps = VariantProps<typeof bannerVariants> & {
+  /** Small caps kicker, e.g. "THE REVIEW CENSUS". */
+  kicker?: string;
+  /**
+   * The headline claim. On the dark tone this is the whole point; on the warm
+   * one it usually sits under `figure`.
+   */
+  headline?: string;
+  body?: string;
+  /** The number itself, pre-formatted, e.g. "100". */
+  figure?: string;
+  /** Unit set small beside the figure, e.g. "%" or "lei". */
+  figureUnit?: string;
+  /** Oversized watermark numeral behind the content. */
+  watermark?: string;
+  /** Low, middle and high of the distribution. All three, or none. */
+  scale?: [string, string, string];
+  /** The action — pass a rendered link or button. */
+  action?: React.ReactNode;
+  className?: string;
+};
+
+export function StatBanner({
+  tone,
+  kicker,
+  headline,
+  body,
+  figure,
+  figureUnit,
+  watermark,
+  scale,
+  action,
+  className,
+}: StatBannerProps) {
+  return (
+    <div className={cn(bannerVariants({ tone }), className)}>
+      {watermark && (
+        <span
+          aria-hidden
+          className="pointer-events-none absolute -bottom-8 right-2 select-none font-serif text-[150px] font-bold leading-none opacity-[0.08]"
+        >
+          {watermark}
+        </span>
+      )}
+
+      <div className="relative z-[1] flex flex-1 flex-col gap-2">
+        {kicker && (
+          <span className="text-[10px] font-bold tracking-[0.11em] opacity-80">{kicker}</span>
+        )}
+
+        {figure && (
+          <div className="text-[40px] font-extrabold leading-none tracking-[-0.03em] tabular-nums">
+            {figure}
+            {figureUnit && (
+              <span className="ml-1 text-lg font-extrabold">{figureUnit}</span>
+            )}
+          </div>
+        )}
+
+        {headline && (
+          <h3 className="font-serif text-xl font-semibold leading-[1.2] tracking-[-0.02em] lg:text-2xl">
+            {headline}
+          </h3>
+        )}
+
+        {body && <p className="text-[13px] leading-[1.5] opacity-85">{body}</p>}
+
+        {scale && (
+          <div className="mt-1 flex items-center gap-2 text-[11px] tabular-nums opacity-70">
+            <span>{scale[0]}</span>
+            <span aria-hidden className="h-px flex-1 bg-current opacity-30" />
+            <span>{scale[1]}</span>
+            <span aria-hidden className="h-px flex-1 bg-current opacity-30" />
+            <span>{scale[2]}</span>
+          </div>
+        )}
+
+        {action && <div className="mt-auto flex items-center pt-3">{action}</div>}
+      </div>
+    </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 })),
+  },
+};