@bearmenu/ui 0.8.7 → 0.8.9

package/src/components/timeline-band.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import * as React from "react";
+import { Radio } from "lucide-react";
 import { cn } from "../lib/utils";
 import { Separator } from "./separator";
 import { Skeleton } from "./skeleton";
@@ -45,14 +46,23 @@ import { Skeleton } from "./skeleton";
  */
 
 /**
- * Ring pulse on the live puck — inherited from the deleted `TimelinePlayhead`,
+ * Ring pulse on the live puck — inherited from an earlier `TimelinePlayhead`,
  * which carried this surface's only motion. Kept at its 2.4s `ease-in-out` and
- * its reduced-motion kill switch, but BOX-SHADOW ONLY: the playhead's
- * `transform: scale` would make the hairline visibly breathe here, because
- * unlike the playhead this puck sits ON the rail.
+ * its reduced-motion kill switch, but BOX-SHADOW ONLY: a `transform: scale`
+ * would make the hairline visibly breathe here, because this puck sits ON the
+ * rail. (Today's `timeline-playhead.tsx` is static and sits between bands.)
  */
 const LIVE_PUCK_PULSE_CLASS = "bm-timeline-live-puck-pulse";
 
+/**
+ * The mobile axis gutter, shared by `HourBand` and `TimelinePlayhead` so the
+ * hour chips and the current-time label sit in one column. 58px is the width
+ * of a five-glyph 24-hour label ("20:00") in the chip's mono type plus its
+ * padding; a 12-hour locale's "09:00 AM" overflows it, which is one of the
+ * reasons the events surfaces format 24-hour everywhere.
+ */
+export const TIMELINE_MOBILE_GUTTER_CLASS = "w-[58px]";
+
 export type TimelineHourPuckProps = {
   /** The hour, already formatted and localised — or an em dash for a quiet day. */
   time: string;
@@ -60,6 +70,16 @@ export type TimelineHourPuckProps = {
   isLive?: boolean;
   /** Shown under the puck when live, e.g. "NOW ON". Required to render it. */
   liveLabel?: string;
+  /**
+   * `station` (default): the bordered puck that sits ON the hairline, for the
+   * desktop spine. `chip`: a filled, fixed-width lozenge with the hairline
+   * starting BELOW it, for the mobile gutter — an app's time label, not a
+   * station on a rail. In `chip` the live label is visually hidden: the tinted
+   * chip plus a small on-air glyph are the visible signal (the glyph so the
+   * state never rests on colour alone once the pulse is reduced away) and the
+   * label stays for screen readers only.
+   */
+  variant?: "station" | "chip";
   className?: string;
 };
 
@@ -78,7 +98,15 @@ export type TimelineHourPuckProps = {
  * centre this puck with `-translate-y-1/2`, and a two-item column would centre
  * the STACK, lifting the puck off the line it exists to sit on.
  */
-export function TimelineHourPuck({ time, isLive, liveLabel, className }: TimelineHourPuckProps) {
+export function TimelineHourPuck({
+  time,
+  isLive,
+  liveLabel,
+  variant = "station",
+  className,
+}: TimelineHourPuckProps) {
+  const isChip = variant === "chip";
+
   return (
     <span className={cn("relative flex justify-center", className)}>
       {isLive && (
@@ -97,20 +125,32 @@ export function TimelineHourPuck({ time, isLive, liveLabel, className }: Timelin
       )}
       <span
         className={cn(
-          "whitespace-nowrap rounded-[7px] border bg-background px-[7px] py-[3px]",
-          "font-mono text-[12.5px] font-medium tabular-nums",
-          isLive
-            ? cn("border-success/40 text-success", LIVE_PUCK_PULSE_CLASS)
-            : "border-border text-foreground"
+          "whitespace-nowrap font-mono tabular-nums",
+          isChip
+            ? cn(
+                "inline-flex h-6 min-w-[58px] items-center justify-center gap-1 rounded-[7px] px-1 text-[12px] font-medium",
+                isLive ? cn("bg-success/10 text-success", LIVE_PUCK_PULSE_CLASS) : "bg-muted text-foreground"
+              )
+            : cn(
+                "rounded-[7px] border bg-background px-[7px] py-[3px] text-[12.5px] font-medium",
+                isLive
+                  ? cn("border-success/40 text-success", LIVE_PUCK_PULSE_CLASS)
+                  : "border-border text-foreground"
+              )
         )}
       >
+        {isChip && isLive && <Radio className="h-2.5 w-2.5 shrink-0" aria-hidden />}
         {time}
       </span>
       {isLive && !!liveLabel && (
         <span
           className={cn(
-            "absolute top-[calc(100%+6px)] whitespace-nowrap bg-background px-1",
-            "text-[9.5px] font-extrabold tracking-[0.08em] text-success"
+            isChip
+              ? "sr-only"
+              : cn(
+                  "absolute top-[calc(100%+6px)] whitespace-nowrap bg-background px-1",
+                  "text-[9.5px] font-extrabold tracking-[0.08em] text-success"
+                )
           )}
         >
           {liveLabel}

package/src/components/timeline-playhead.stories.tsx

@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { TimelinePlayhead } from "./timeline-playhead";
+
+const meta: Meta<typeof TimelinePlayhead> = {
+  title: "Events/TimelinePlayhead",
+  component: TimelinePlayhead,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="w-[390px] bg-background px-4">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The current-time mark on the mobile timeline. Rendered between hour bands where the wall clock falls; its time label shares the gutter with `HourBand` so it aligns under the hour chips.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TimelinePlayhead>;
+
+export const Default: Story = {
+  args: { time: "21:38", label: "NOW" },
+};

package/src/components/timeline-playhead.test.tsx

@@ -0,0 +1,11 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { TimelinePlayhead } from "./timeline-playhead";
+
+describe("TimelinePlayhead", () => {
+  it("prints the time and the label, both as given", () => {
+    render(<TimelinePlayhead time="21:38" label="NOW" />);
+    expect(screen.getByText("21:38")).toBeInTheDocument();
+    expect(screen.getByText("NOW")).toBeInTheDocument();
+  });
+});

package/src/components/timeline-playhead.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import * as React from "react";
+import { cn } from "../lib/utils";
+import { TIMELINE_MOBILE_GUTTER_CLASS } from "./timeline-band";
+
+/**
+ * TimelinePlayhead — the "you are here" mark on the mobile timeline: the
+ * current time in the axis gutter, a dashed rule across the content column,
+ * and a filled NOW pill at the far edge.
+ *
+ * It sits BETWEEN hour bands, at the point where the wall clock falls, so the
+ * reader can see at a glance which hours are behind them and which are ahead.
+ * The live hour band's tinted chip says "this hour is running"; the playhead
+ * says exactly how far into it we are. Both are needed: a band spans an hour
+ * and the hour is mostly not "now".
+ *
+ * The time label shares the gutter width with `HourBand` so it lines up under
+ * the hour chips. Both strings arrive formatted — the DS holds no clock.
+ */
+export type TimelinePlayheadProps = {
+  /** The current time, already formatted — "21:38". */
+  time: string;
+  /** The pill text, e.g. "NOW". */
+  label: string;
+  className?: string;
+};
+
+export function TimelinePlayhead({ time, label, className }: TimelinePlayheadProps) {
+  return (
+    <div className={cn("flex items-center gap-2.5 pt-3", className)}>
+      <span
+        className={cn(
+          TIMELINE_MOBILE_GUTTER_CLASS,
+          "shrink-0 text-center font-mono text-[11px] font-bold tabular-nums text-success"
+        )}
+      >
+        {time}
+      </span>
+      <span aria-hidden className="h-0 flex-1 border-t-[1.5px] border-dashed border-success/50" />
+      <span className="rounded-full bg-success px-2 py-0.5 text-[9.5px] font-extrabold tracking-[0.1em] text-success-foreground">
+        {label}
+      </span>
+    </div>
+  );
+}

package/src/components/venue-busyness-strip.stories.tsx

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { mockPlaces } from "./menu-mocks";
+import { VenueBusynessStrip } from "./venue-busyness-strip";
+
+const busyness = mockPlaces[0].busyness!;
+
+const meta: Meta<typeof VenueBusynessStrip> = {
+  title: "Menu/VenueBusynessStrip",
+  component: VenueBusynessStrip,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="w-[560px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "When a venue actually fills up, as a bar per hour. The API serves one score per hour of the venue's OWN trading day, so the strip has no fixed length — a bakery closing at three and a club open until four draw different numbers of bars, and padding either to 24 would put empty columns under hours the venue is shut. The rush is derived relative to that venue's own peak, because a fixed score threshold would mark every hour at a busy venue and none at a quiet one.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof VenueBusynessStrip>;
+
+export const Default: Story = {
+  args: {
+    busyness,
+    caption: "Usually not busy until 18:00 — the rush is seven to eight.",
+  },
+};
+
+/** No caption: the bars alone, for a tight row. */
+export const BarsOnly: Story = { args: { busyness } };
+
+/** A short trading day draws a short strip rather than padding to 24. */
+export const ShortDay: Story = {
+  args: {
+    busyness: [
+      { hour: 8, score: 40 },
+      { hour: 9, score: 72 },
+      { hour: 10, score: 88 },
+      { hour: 11, score: 60 },
+      { hour: 12, score: 34 },
+    ],
+    caption: "Busiest first thing — quiet by noon.",
+  },
+};
+
+/** A flat day: `peakRatio` still finds the top of it, because it is relative. */
+export const Flat: Story = {
+  args: {
+    busyness: Array.from({ length: 10 }, (_, index) => ({ hour: 12 + index, score: 30 })),
+    caption: "Steady all day.",
+  },
+};
+
+/** All zeros — no reading. The strip renders nothing rather than a flat line. */
+export const NoReading: Story = {
+  args: { busyness: Array.from({ length: 8 }, (_, index) => ({ hour: index, score: 0 })) },
+};

package/src/components/venue-busyness-strip.tsx

@@ -0,0 +1,64 @@
+import { cn } from "../lib/utils";
+
+/**
+ * VenueBusynessStrip — when a venue actually fills up, as a bar per hour.
+ *
+ * The API serves one score per hour of the venue's own trading day, so the
+ * strip has no fixed length: a bakery closing at three and a club open until
+ * four draw different numbers of bars, and padding either to 24 would put empty
+ * columns under hours the venue is not open.
+ *
+ * The rush is derived rather than passed: bars at or above `peakRatio` of the
+ * day's own maximum take the accent. A fixed score threshold would mark every
+ * hour at a busy venue and none at a quiet one — busyness is only meaningful
+ * relative to that venue's own day.
+ *
+ * `caption` is composed by the caller ("Usually not busy until 18:00 — the rush
+ * is nine to eleven"), because the sentence needs the venue's clock, its locale
+ * and a plural rule the DS does not own.
+ *
+ * Server-safe.
+ */
+
+export type VenueBusynessStripProps = {
+  busyness: Array<{ hour: number; score: number }>;
+  /** Composed sentence beside the bars. */
+  caption?: string;
+  /** Share of the day's own peak at which an hour counts as the rush. */
+  peakRatio?: number;
+  className?: string;
+};
+
+const BAR_MAX_HEIGHT = 22;
+
+export function VenueBusynessStrip({
+  busyness,
+  caption,
+  peakRatio = 0.8,
+  className,
+}: VenueBusynessStripProps) {
+  if (busyness.length === 0) return null;
+
+  const peak = Math.max(...busyness.map((entry) => entry.score));
+  if (peak <= 0) return null;
+
+  return (
+    <div
+      className={cn("flex items-center gap-2.5 text-[12.5px] text-muted-foreground", className)}
+    >
+      <span aria-hidden className="flex h-[22px] items-end gap-[3px]">
+        {busyness.map(({ hour, score }) => (
+          <i
+            key={hour}
+            className={cn(
+              "w-[7px] rounded-t-sm bg-[oklch(0.88_0.02_45)]",
+              score >= peak * peakRatio && "bg-[var(--accent,currentColor)]"
+            )}
+            style={{ height: Math.max(2, Math.round((score / peak) * BAR_MAX_HEIGHT)) }}
+          />
+        ))}
+      </span>
+      {caption}
+    </div>
+  );
+}

package/src/components/venue-grade-dimensions.stories.tsx

@@ -0,0 +1,83 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { mockFormatters, mockPlaces } from "./menu-mocks";
+import { VenueGradeDimensions } from "./venue-grade-dimensions";
+
+const labels = {
+  food: "Food",
+  coffee_quality: "Coffee",
+  drinks_quality: "Drinks",
+  service: "Service",
+  value: "Value",
+  ambiance: "Ambiance",
+  portion: "Portion",
+  consistency: "Consistency",
+  cleanliness: "Cleanliness",
+};
+
+const meta: Meta<typeof VenueGradeDimensions> = {
+  title: "Menu/VenueGradeDimensions",
+  component: VenueGradeDimensions,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="w-[720px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Per-dimension review scores as a row of bars. A dimension the reviews never mention is ABSENT from the payload, not zero, and exactly one of food / coffee_quality / drinks_quality is scored per place — so a component drawing a fixed row of seven would invent readings for a third of the catalogue. It iterates the canonical order, skips what is missing, and lays out however many survive. Scores arrive 0–100 and display over ten.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof VenueGradeDimensions>;
+
+export const Default: Story = {
+  args: {
+    dimensions: mockPlaces[0].reviews_digest!.grade!.dimensions!,
+    labels,
+    formatScore: mockFormatters.score,
+  },
+};
+
+/**
+ * A coffee bar. It is graded on `coffee_quality` and has no food score at all —
+ * the row is four columns, not seven with a gap.
+ */
+export const CoffeeBar: Story = {
+  args: {
+    dimensions: mockPlaces[2].reviews_digest!.grade!.dimensions!,
+    labels,
+    formatScore: mockFormatters.score,
+  },
+};
+
+/** Thin evidence: only two dimensions were mentioned often enough to score. */
+export const Sparse: Story = {
+  args: {
+    dimensions: { food: 78, value: 64 },
+    labels,
+    formatScore: mockFormatters.score,
+  },
+};
+
+/** `order` narrows as well as reorders — here, quality and value only. */
+export const Narrowed: Story = {
+  args: {
+    dimensions: mockPlaces[0].reviews_digest!.grade!.dimensions!,
+    labels,
+    order: ["food", "value"],
+    formatScore: mockFormatters.score,
+  },
+};
+
+/** Nothing scored: the component renders nothing rather than an empty row. */
+export const Empty: Story = {
+  args: { dimensions: {}, labels, formatScore: mockFormatters.score },
+};

package/src/components/venue-grade-dimensions.tsx

@@ -0,0 +1,91 @@
+import { cn } from "../lib/utils";
+import type { PlaceGradeDimensions } from "./place-types";
+
+/**
+ * VenueGradeDimensions — the per-dimension review scores as a row of bars.
+ *
+ * ## Why this renders what it is given rather than a fixed row
+ *
+ * A dimension the reviews never mention is ABSENT from the payload, not zero,
+ * and exactly one of `food` / `coffee_quality` / `drinks_quality` is scored per
+ * place — a coffee bar has no food score and a restaurant has no coffee one.
+ * So a component drawing seven fixed columns would invent readings for a third
+ * of the catalogue. It iterates `order`, skips what is missing, and lays out
+ * however many survive.
+ *
+ * Scores arrive 0–100 and display on the 0–10 scale the rest of the product
+ * grades on, so the bar width is the raw value and the numeral is that value
+ * over ten. `formatScore` is injected because a decimal separator is
+ * locale-dependent.
+ *
+ * Server-safe.
+ */
+
+export type VenueGradeDimensionKey = keyof PlaceGradeDimensions;
+
+/** Canonical order. Quality leads, and the three quality keys are mutually exclusive. */
+const DEFAULT_ORDER: VenueGradeDimensionKey[] = [
+  "food",
+  "coffee_quality",
+  "drinks_quality",
+  "service",
+  "value",
+  "ambiance",
+  "portion",
+  "consistency",
+  "cleanliness",
+];
+
+export type VenueGradeDimensionsProps = {
+  dimensions: PlaceGradeDimensions;
+  /** Dimension key → translated label. Keys with no label fall back to the key. */
+  labels: Partial<Record<VenueGradeDimensionKey, string>>;
+  /** Override the canonical order, or narrow which dimensions show at all. */
+  order?: VenueGradeDimensionKey[];
+  /** 0–100 → display numeral, e.g. `(v) => (v / 10).toFixed(1)`. */
+  formatScore: (value: number) => string;
+  className?: string;
+};
+
+export function VenueGradeDimensions({
+  dimensions,
+  labels,
+  order = DEFAULT_ORDER,
+  formatScore,
+  className,
+}: VenueGradeDimensionsProps) {
+  const present = order
+    .map((key) => ({ key, value: dimensions[key] }))
+    .filter((entry): entry is { key: VenueGradeDimensionKey; value: number } =>
+      typeof entry.value === "number"
+    );
+
+  if (present.length === 0) return null;
+
+  return (
+    <dl
+      className={cn(
+        "grid grid-cols-3 gap-2.5 sm:grid-cols-4 lg:flex lg:gap-2.5",
+        className
+      )}
+    >
+      {present.map(({ key, value }) => (
+        <div key={key} className="flex flex-col gap-1.5 lg:flex-1">
+          <dd className="text-[15px] font-extrabold tracking-[-0.02em] tabular-nums">
+            {formatScore(value)}
+          </dd>
+          <div
+            aria-hidden
+            className="relative block h-[3px] overflow-hidden rounded-full bg-muted"
+          >
+            <span
+              className="absolute inset-y-0 left-0 rounded-full bg-[var(--gradient-primary,currentColor)]"
+              style={{ width: `${Math.min(100, Math.max(0, value))}%` }}
+            />
+          </div>
+          <dt className="text-[10.5px] text-muted-foreground">{labels[key] ?? key}</dt>
+        </div>
+      ))}
+    </dl>
+  );
+}

package/src/components/venue-quotes.stories.tsx

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { mockPlaces } from "./menu-mocks";
+import { VenueQuotes } from "./venue-quotes";
+
+const highlights = mockPlaces[0].reviews_digest!.highlights!;
+
+const meta: Meta<typeof VenueQuotes> = {
+  title: "Menu/VenueQuotes",
+  component: VenueQuotes,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="w-[720px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The digest's standout lines as pull-quotes — one to three short positives, already resolved into the request locale. They are the only place on a hub where a reviewer speaks in their own register, so they are set in serif italic against the sans everything else uses. `onCite` turns a quote into a button opening the reviews behind it: `review_ids` is what makes the claim checkable, and a quote nobody can trace is just copy.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof VenueQuotes>;
+
+/** Inert prose. Correct on a surface with nowhere to open. */
+export const Default: Story = { args: { quotes: highlights } };
+
+/** With `onCite` each quote becomes a button onto its own evidence. */
+export const Citable: Story = {
+  args: {
+    quotes: highlights,
+    onCite: () => {},
+    citeLabel: (count) => `Read ${count} reviews`,
+  },
+};
+
+/** A quote with no `review_ids` stays inert even when `onCite` is passed. */
+export const MixedEvidence: Story = {
+  args: {
+    quotes: [highlights[0], { text: "Worth the walk from the centre." }],
+    onCite: () => {},
+    citeLabel: (count) => `Read ${count} reviews`,
+  },
+};
+
+export const Single: Story = { args: { quotes: [highlights[0]] } };
+
+export const Limited: Story = {
+  args: {
+    quotes: [...highlights, { text: "A third line the surface has no room for." }],
+    limit: 2,
+  },
+};

package/src/components/venue-quotes.tsx

@@ -0,0 +1,64 @@
+import { cn } from "../lib/utils";
+import type { CitedText } from "./place-types";
+
+/**
+ * VenueQuotes — the digest's standout lines, as pull-quotes.
+ *
+ * These are `reviews_digest.highlights`: one to three short positives already
+ * resolved into the request locale. They are the only place on a hub where a
+ * reviewer speaks in their own register, so they are set in serif italic
+ * against the sans everything else uses.
+ *
+ * `onCite` turns a quote into a button that opens the reviews behind it —
+ * `review_ids` is what makes the claim checkable, and a quote nobody can trace
+ * is just copy. Without the handler the quote renders as inert prose, which is
+ * correct on surfaces that have nowhere to open.
+ *
+ * No directive: inert quotes render on the server; passing `onCite` needs a
+ * client caller.
+ */
+
+export type VenueQuotesProps = {
+  quotes: CitedText[];
+  /** Opens the reviews behind one quote. Omit to render inert prose. */
+  onCite?: (quote: CitedText) => void;
+  /** Accessible name for the cite action, e.g. `(n) => "Read 5 reviews"`. */
+  citeLabel?: (reviewCount: number) => string;
+  /** Cap on how many render. The digest ships at most three. */
+  limit?: number;
+  className?: string;
+};
+
+export function VenueQuotes({ quotes, onCite, citeLabel, limit, className }: VenueQuotesProps) {
+  const shown = typeof limit === "number" ? quotes.slice(0, limit) : quotes;
+  if (shown.length === 0) return null;
+
+  return (
+    <div className={cn("grid gap-3 lg:grid-cols-2", className)}>
+      {shown.map((quote, index) => {
+        const citations = quote.review_ids?.length ?? 0;
+        const canCite = !!onCite && citations > 0;
+
+        const text = (
+          <blockquote className="border-l-2 border-border pl-3 font-serif text-[13px] italic leading-[1.45] text-muted-foreground">
+            {`“${quote.text}”`}
+          </blockquote>
+        );
+
+        if (!canCite) return <div key={index}>{text}</div>;
+
+        return (
+          <button
+            key={index}
+            type="button"
+            onClick={() => onCite(quote)}
+            aria-label={citeLabel?.(citations)}
+            className="rounded-md text-left transition-colors hover:bg-muted/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            {text}
+          </button>
+        );
+      })}
+    </div>
+  );
+}