@bearmenu/ui 0.8.9 → 0.8.10

package/src/components/menu-types.ts

@@ -157,10 +157,8 @@ export type MenuFamilyPreview = {
   price_low?: number
   price_high?: number
   price_median?: number
-  /** Pre-resolved venue photos for the fanned deck. Venue photography only. */
+  /** Pre-resolved venue photos for the mosaic. Venue photography only. */
   venue_photo_urls?: string[]
-  /** The item this family is most named for. */
-  signature?: MenuFamilySignature
 }
 
 export type MenuFamilyChip = {
@@ -170,9 +168,6 @@ export type MenuFamilyChip = {
   count?: number
 }
 
-/** A family card's featured item. Same shape as a venue's, for the same reason. */
-export type MenuFamilySignature = MenuVenueSignature
-
 /**
  * A venue as the hub's venue-scoped surfaces consume it: the place itself plus
  * the pre-resolved bits a hub row needs and `PlacePreview` does not carry —
@@ -235,6 +230,194 @@ export type MenuIntentTile = {
   icon?: ReactNode
 }
 
+/**
+ * One figure in the intent hero — a number the reader can tap to filter by.
+ *
+ * The value arrives pre-formatted because the figures are not all the same
+ * quantity: "247" is a count and "58" is a count of a subset, but a caller may
+ * also want "4 past midnight", and a component that formatted numbers itself
+ * would need the locale it is forbidden to own.
+ */
+export type MenuIntentFigure = {
+  key: string
+  /** Pre-formatted, e.g. "247". */
+  value: string
+  /** The unit, e.g. "kitchens" or "make a pizza". */
+  label: string
+  /**
+   * The state this figure applies, as a URL.
+   *
+   * An `href` rather than only a callback because the filter state lives in the
+   * query string: a link is server-rendered, crawlable, middle-clickable and
+   * survives with no JavaScript, and `?open=now` is an indexable state we
+   * actively want followed. `onSelect` remains for consumers holding the state
+   * in memory; `href` wins when both are set.
+   */
+  href?: string
+  /**
+   * Applies this figure as a filter without navigating. A figure with neither
+   * `href` nor `onSelect` renders as a static fact rather than as a control
+   * that does nothing — the total is usually one, since filtering to "all of
+   * them" is not a state.
+   */
+  onSelect?: () => void
+  /** The filter this figure applies is already on. */
+  active?: boolean
+}
+
+/**
+ * A filter chip on the intent page.
+ *
+ * Every chip counts KITCHENS, whatever facet backs it — a dietary chip reads
+ * "has a vegetarian dish" and counts venues, not dishes. Mixing venue counts
+ * and item counts in one row is what made the earlier version unreadable, so
+ * the type carries no unit: there is only ever one.
+ */
+export type MenuFilterChip = {
+  key: string
+  label: string
+  /** Kitchens this chip would leave. Absent where no facet backs it. */
+  count?: number
+  active?: boolean
+  /**
+   * Zero kitchens under the current filters — dimmed, but STILL TAPPABLE.
+   *
+   * Tapping swaps it in and drops whichever active filter conflicts, with a
+   * line saying which. A disabled chip would leave the reader guessing why the
+   * thing they want is unavailable; this one answers it by being pressed.
+   */
+  empty?: boolean
+  /** Icon node, resolved by the caller. */
+  icon?: ReactNode
+}
+
+/**
+ * A venue row on the intent page — the page's spine.
+ *
+ * Distinct from `MenuVenuePreview` (the hub's ranked row) in one structural
+ * way that is the whole point of the surface: the dish carries its own `href`,
+ * so the row has TWO targets. The row goes to the venue; the dish name opens
+ * the item drawer. `RankedVenueList` wraps its entire row in one link and
+ * therefore cannot express this, which is why this is a separate shape rather
+ * than a flag on that one.
+ */
+export type MenuKitchenPreview = {
+  place: PlacePreview
+  /** The venue page. The row's primary target. */
+  href: string
+  /** Venue type and district, composed and localised by the caller, e.g. "pizzeria · Centru". */
+  metaLabel?: string
+  /**
+   * "kitchen until 23:00", or "closed · opens 12:00". Composed by the caller
+   * because the wording differs by scope — a bar is not a kitchen.
+   */
+  hoursLabel?: string
+  dish?: MenuKitchenDish
+  /** Pre-formatted, e.g. "62 lei". */
+  priceLabel?: string
+}
+
+/** The dish a kitchen row leads with. The row's second target. */
+export type MenuKitchenDish = {
+  name: string
+  /**
+   * Opens the item drawer. Omit for an inert dish line — a must-try the
+   * reviews named that has no live menu row behind it.
+   */
+  href?: string
+  /** Kicker over the name: "MOST NAMED HERE", or "WHY IT MATCHES" when filtered. */
+  kicker: string
+  /** Under the name: "17 reviews name it", or "mid-range · 300g" when matched. */
+  meta?: string
+  /**
+   * This row is answering a filter rather than volunteering its most-named
+   * dish. Draws the match mark and tints the block, so a reader scanning a
+   * filtered list can see that every row changed its reason for being there.
+   */
+  matched?: boolean
+  /** The filter it matched, e.g. "vegetarian". */
+  matchLabel?: string
+}
+
+/**
+ * One row in a browse index — the complete set, at a glance.
+ *
+ * The index is the page's whole SEO job: it carries a crawlable link to every
+ * destination the city has, which is what frees the richer blocks below it to
+ * be progressive. So it holds nothing but what a reader needs to choose — a
+ * name, a count and a colour.
+ */
+export type MenuIndexEntry = {
+  slug: string
+  name: string
+  count: number
+  href: string
+  /** Finished CSS gradient for the mark. Falls back to the border colour. */
+  gradient?: string
+}
+
+/**
+ * A family on the cuisines index — the hub's card, opened out sideways.
+ *
+ * Deliberately thin. The reader here is choosing a cuisine, not a venue, and
+ * every field the block does NOT carry is a decision the next page owns.
+ */
+export type MenuFamilyBlockPreview = {
+  slug: string
+  name: string
+  venueCount: number
+  /** Facet chips. Labels only — the block never prints their counts. */
+  chips?: MenuFamilyChip[]
+  /** Composed price band, e.g. "22–86 lei". */
+  priceBandLabel?: string
+  /** Venue photography only — item photography is AI-generated and never shown. */
+  photoUrls?: string[]
+  /**
+   * Venues, as kitchen rows. The block draws every one it is given — the caller
+   * decides how many, because how much of a claim the block makes is the page's
+   * decision, not the component's.
+   *
+   * The same `MenuKitchenPreview` the intent page's list takes, rendered by the
+   * same component — a family block that grew its own venue row would be the
+   * fourth near-identical row in the package, and they drift the moment one of
+   * them gets a fix.
+   */
+  venues?: MenuKitchenPreview[]
+  /** The family's own page. */
+  href: string
+}
+
+/**
+ * One "loosen this" row on a dead end — a filter, and what dropping it returns.
+ *
+ * The count is the point: "drop Open now" is a guess, "+8 kitchens" is an
+ * answer, and a dead end that cannot say which filter costs the most is just
+ * an empty state with extra steps.
+ */
+export type MenuLoosenOption = {
+  key: string
+  /** e.g. 'Drop "Open now"'. */
+  label: string
+  /** e.g. "+8 kitchens". Pre-formatted. */
+  gainLabel: string
+  /**
+   * The state without this filter, as a URL.
+   *
+   * An `href` because dropping a filter IS a navigation wherever the filter set
+   * lives in the query string — which makes it server-renderable, shareable and
+   * undoable with the back button. `onSelect` remains for consumers holding the
+   * state in memory; `href` wins when both are set.
+   */
+  href?: string
+  onSelect?: () => void
+}
+
+/** One question and its answer. Static prose — never an accordion; see `<QaBlock>`. */
+export type QaItem = {
+  question: string
+  answer: string
+}
+
 /** Formatters injected into every menu surface. The DS owns no `Intl` locale. */
 export type MenuFormatters = {
   /** 24 → "24 lei". */

package/src/components/motion-icon-controls.tsx

@@ -14,7 +14,7 @@
 import * as React from "react";
 import { motion, type Variants } from "framer-motion";
 
-import { MotionIcon, beats, returnTransition, type MotionIconProps } from "./motion-icon";
+import { MotionIcon, beats, pivot, returnTransition, type MotionIconProps } from "./motion-icon";
 
 // ─── Heart — favorite. Squash, then inflate (deform) ──────────────────────────
 
@@ -41,7 +41,7 @@ export function MotionHeart(props: MotionIconProps) {
     <MotionIcon {...props}>
       <motion.path
         variants={heartBody}
-        style={{ originX: "12px", originY: "13px" }}
+        style={pivot(12, 13)}
         fill="currentColor"
         fillOpacity={0}
         d="M2 9.5a5.5 5.5 0 0 1 9.591-3.676.56.56 0 0 0 .818 0A5.49 5.49 0 0 1 22 9.5c0 2.29-1.5 4-3 5.5l-5.492 5.313a2 2 0 0 1-3 .019L5 15c-1.5-1.5-3-3.2-3-5.5"
@@ -71,7 +71,7 @@ export function MotionBookmark(props: MotionIconProps) {
     <MotionIcon {...props}>
       <motion.path
         variants={bookmarkBody}
-        style={{ originX: "12px", originY: "21px" }}
+        style={pivot(12, 21)}
         fill="currentColor"
         fillOpacity={0}
         d="M17 3a2 2 0 0 1 2 2v15a1 1 0 0 1-1.496.868l-4.512-2.578a2 2 0 0 0-1.984 0l-4.512 2.578A1 1 0 0 1 5 20V5a2 2 0 0 1 2-2z"
@@ -144,14 +144,14 @@ const found: Variants = {
 export function MotionSearch(props: MotionIconProps) {
   return (
     <MotionIcon {...props}>
-      <motion.g variants={lens} style={{ originX: "21px", originY: "21px" }}>
+      <motion.g variants={lens} style={pivot(21, 21)}>
         <circle cx="11" cy="11" r="8" />
         <path d="m21 21-4.34-4.34" />
         {/* Something turns up in the glass on the return stroke. */}
         <motion.circle
           variants={found}
           opacity={0}
-          style={{ originX: "11px", originY: "11px" }}
+          style={pivot(11, 11)}
           fill="currentColor"
           cx="11"
           cy="11"
@@ -309,7 +309,7 @@ const crescent: Variants = {
  * cross-dissolve into visual mush at 20px.
  */
 export function MotionTheme(props: MotionIconProps) {
-  const origin = { originX: "12px", originY: "12px" } as const;
+  const origin = pivot(12, 12);
   return (
     <MotionIcon {...props}>
       <motion.g variants={rays} style={origin}>
@@ -348,7 +348,7 @@ const chevron: Variants = {
 export function MotionChevron(props: MotionIconProps) {
   return (
     <MotionIcon {...props}>
-      <motion.path variants={chevron} style={{ originX: "12px", originY: "12px" }} d="m6 9 6 6 6-6" />
+      <motion.path variants={chevron} style={pivot(12, 12)} d="m6 9 6 6 6-6" />
     </MotionIcon>
   );
 }
@@ -386,7 +386,7 @@ const barLeft = pauseBar(5);
 const barRight = pauseBar(-5);
 
 export function MotionPlayPause(props: MotionIconProps) {
-  const origin = { originX: "12px", originY: "12px" } as const;
+  const origin = pivot(12, 12);
   return (
     <MotionIcon {...props}>
       <motion.path
@@ -433,7 +433,7 @@ const slash: Variants = {
 };
 
 export function MotionEye(props: MotionIconProps) {
-  const origin = { originX: "12px", originY: "12px" } as const;
+  const origin = pivot(12, 12);
   return (
     <MotionIcon {...props}>
       <motion.path
@@ -471,7 +471,7 @@ export function MotionStar(props: MotionIconProps) {
     <MotionIcon {...props}>
       <motion.path
         variants={starBody}
-        style={{ originX: "12px", originY: "12px" }}
+        style={pivot(12, 12)}
         fill="currentColor"
         fillOpacity={0}
         d="M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z"
@@ -541,7 +541,7 @@ const refreshRing: Variants = {
 export function MotionRefresh(props: MotionIconProps) {
   return (
     <MotionIcon {...props}>
-      <motion.g variants={refreshRing} style={{ originX: "12px", originY: "12px" }}>
+      <motion.g variants={refreshRing} style={pivot(12, 12)}>
         <path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8" />
         <path d="M21 3v5h-5" />
         <path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16" />

package/src/components/motion-icon-set.tsx

@@ -18,6 +18,7 @@ import { motion, type Variants } from "framer-motion";
 import {
   MotionIcon,
   beats,
+  pivot,
   returnTransition,
   type MotionIconProps,
 } from "./motion-icon";
@@ -54,10 +55,10 @@ export function MotionHouse(props: MotionIconProps) {
     <MotionIcon {...props}>
       <motion.path
         variants={houseRoof}
-        style={{ originX: "12px", originY: "10px" }}
+        style={pivot(12, 10)}
         d="M3 10a2 2 0 0 1 .709-1.528l7-6a2 2 0 0 1 2.582 0l7 6A2 2 0 0 1 21 10"
       />
-      <motion.g variants={houseWalls} style={{ originX: "12px", originY: "21px" }}>
+      <motion.g variants={houseWalls} style={pivot(12, 21)}>
         <path d="M21 10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V10" />
         <path d="M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8" />
       </motion.g>
@@ -104,7 +105,7 @@ const knife: Variants = {
   },
 };
 
-const CROSSING = { originX: "12px", originY: "12px" } as const;
+const CROSSING = pivot(12, 12);
 
 /**
  * The fork's handle. Lucide leaves a gap between the handle and the neck where
@@ -180,11 +181,11 @@ const pinDot: Variants = {
 export function MotionMapPin(props: MotionIconProps) {
   return (
     <MotionIcon {...props}>
-      <motion.g variants={pinBody} style={{ originX: "12px", originY: "22px" }}>
+      <motion.g variants={pinBody} style={pivot(12, 22)}>
         <path d="M20 10c0 4.993-5.539 10.193-7.399 11.799a1 1 0 0 1-1.202 0C9.539 20.193 4 14.993 4 10a8 8 0 0 1 16 0" />
         <motion.circle
           variants={pinDot}
-          style={{ originX: "12px", originY: "10px" }}
+          style={pivot(12, 10)}
           fill="currentColor"
           fillOpacity={0}
           cx="12"

package/src/components/motion-icon.test.tsx

@@ -2,7 +2,7 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 import { render } from "@testing-library/react";
 import * as React from "react";
 
-import { MotionIcon } from "./motion-icon";
+import { MotionIcon, pivot } from "./motion-icon";
 
 /**
  * The primitive drives its gesture through animation controls rather than a
@@ -157,3 +157,25 @@ describe("MotionIcon", () => {
     expect(variantsStarted).toEqual(["play"]);
   });
 });
+
+/**
+ * Framer Motion puts `transform-box: fill-box` on every SVG element it
+ * transforms, so a pixel origin is read against that element's OWN bounding
+ * box, not the icon's viewBox. The chevron's box starts at (6, 9); "12px 12px"
+ * therefore meant (18, 21) and the arrow slid sideways as it flipped. The
+ * helper's whole job is the one property that makes viewBox pixels mean what
+ * they say — and nothing errors if it goes missing, so it is pinned here.
+ */
+describe("pivot", () => {
+  it("anchors the origin to the viewBox, not the part's own box", () => {
+    expect(pivot(12, 12)).toEqual({
+      originX: "12px",
+      originY: "12px",
+      transformBox: "view-box",
+    });
+  });
+
+  it("carries a pivot that is deliberately off the part, like a pin's tip", () => {
+    expect(pivot(12, 22)).toMatchObject({ originY: "22px", transformBox: "view-box" });
+  });
+});

package/src/components/motion-icon.tsx

@@ -62,6 +62,26 @@ export function beats(times: number[], duration = 0.62): Transition {
 /** Leaving is not a performance — it returns the glyph, firmly and fast. */
 export const returnTransition: Transition = { type: "spring", stiffness: 320, damping: 26 };
 
+/**
+ * A moving part's pivot, in the icon's 24-unit VIEWBOX coordinates.
+ *
+ * Every part in this family wrote `style={{ originX: "12px", originY: "12px" }}`
+ * meaning "the centre of the icon" — and every one of them was pivoting
+ * somewhere else. Framer Motion sets `transform-box: fill-box` on any SVG
+ * element it transforms, which makes `transform-origin` relative to that
+ * element's OWN bounding box, not the viewBox. The chevron `m6 9 6 6 6-6` has
+ * its box at (6, 9), so "12px 12px" resolved to user-space (18, 21): a 180°
+ * flip around a point outside the arrow, which is why it visibly slid as it
+ * turned. A house's walls pivoting at its floor, a pin at its tip, a lens at
+ * its centre — all of them missed by the same offset for the same reason.
+ *
+ * `transform-box: view-box` is the single switch that makes px origins mean
+ * what they say. Declared once here so the next icon cannot get it wrong.
+ */
+export function pivot(x: number, y: number) {
+  return { originX: `${x}px`, originY: `${y}px`, transformBox: "view-box" } as const;
+}
+
 type PoseValues = Record<string, number>;
 
 /**

package/src/components/photo-ground.tsx

@@ -0,0 +1,147 @@
+import { cn } from "../lib/utils";
+
+/**
+ * PhotoGround — venue photography as the ground of a card.
+ *
+ * Three cards are built on photographs rather than on panels: the hub's family
+ * card, the cuisines index's family block and the concept card. Each had grown
+ * its own copy of the same stack — a dark ground, a grid of `<img>`s with an
+ * initial for the missing ones, a hue layer, an overlay — and the one rule that
+ * matters for all of them (the tint has to be `mix-blend-color`, the ground
+ * has to be a fixed literal) was written three times. This is the stack, once.
+ *
+ * ## What it owns and what it leaves to the card
+ *
+ * It owns the photographs and their colour: the ground, the tiles, the fallback
+ * initial, the family's hue and an optional uniform dark overlay. It does NOT
+ * own the glass — the scrims and frosted bands that carry a card's type run in
+ * a different direction on every card (down the family block's phone, across
+ * its desktop, in from both ends of the concept card) and are the card's own.
+ *
+ * ## Two layouts
+ *
+ * `mosaic` tiles every photograph into a grid the caller shapes; `stack` shows
+ * ONE of them, `active`, and cross-fades to the next — a card whose ground
+ * follows a swipe. Same slots, same fallback, same tint either way.
+ *
+ * ## Why the ground is a literal, and why the tint is `color`
+ *
+ * The ground is the backdrop a blend or blur samples before a lazy image lands
+ * and the tile an empty slot shows, so it must not change with the theme —
+ * photography is not themed, and a card that flashed paper-white behind its
+ * photographs in light mode was wrong in exactly the mode most people use.
+ * `mix-blend-mode: color` takes hue and chroma from the tint layer and
+ * luminance from the photograph, so the room keeps its structure and the
+ * family keeps its colour; a plain overlay would have muddied both.
+ */
+
+/** The ground under the photography. Fixed, and deliberately not a token. */
+export const PHOTO_GROUND = "bg-[oklch(0.21_0.012_55)]";
+
+/** The uniform dark overlay a card may put over every photograph. */
+const OVERLAY = "absolute inset-0 bg-[oklch(0.16_0.012_55_/_0.5)]";
+
+export type PhotoGroundProps = {
+  /** One per slot. An absent one draws the slot's initial on the ground. */
+  photos: (string | undefined)[];
+  /** The fallback glyph per slot — a venue's first letter. One is reused for all. */
+  initials: string | string[];
+  /** `mosaic` tiles every slot; `stack` shows `active` and cross-fades. */
+  mode?: "mosaic" | "stack";
+  /** `stack` only: which slot is showing. */
+  active?: number;
+  /** `mosaic` only: the grid template, e.g. `"grid-cols-2 grid-rows-2 lg:grid-cols-3"`. */
+  mosaicClassName?: string;
+  /** `mosaic` only: slots from this index on are desktop-only tiles. */
+  phoneTiles?: number;
+  /** Finished CSS gradient — the family's colour, laid over the photographs. */
+  gradient?: string;
+  /** A uniform dark overlay on every photograph. */
+  overlay?: boolean;
+  /** Extra classes on the overlay, e.g. a hover that lifts it. */
+  overlayClassName?: string;
+  /** How eagerly the first photograph loads. `stack` grounds are above the fold. */
+  loading?: "lazy" | "eager";
+  className?: string;
+};
+
+export function PhotoGround({
+  photos,
+  initials,
+  mode = "mosaic",
+  active = 0,
+  mosaicClassName,
+  phoneTiles,
+  gradient,
+  overlay,
+  overlayClassName,
+  loading = "lazy",
+  className,
+}: PhotoGroundProps) {
+  const initialOf = (index: number) =>
+    typeof initials === "string" ? initials : (initials[index] ?? initials[0] ?? "");
+  const hasAnyPhoto = photos.some(Boolean);
+
+  const slot = (index: number, extra?: string) => {
+    const src = photos[index];
+    return (
+      <span key={index} className={cn("relative block overflow-hidden", extra)}>
+        {src ? (
+          // eslint-disable-next-line @next/next/no-img-element
+          <img
+            src={src}
+            alt=""
+            loading={index === 0 ? loading : "lazy"}
+            decoding="async"
+            className="absolute inset-0 h-full w-full object-cover"
+          />
+        ) : (
+          /* Never a grey box: the ground with the venue's initial. A missing
+             photograph is not a broken image, and drawing one as a placeholder
+             makes a real city look unfinished. */
+          <span className="absolute inset-0 flex items-center justify-center">
+            <span className="font-serif text-[64px] font-semibold leading-none text-white/15">
+              {initialOf(index)}
+            </span>
+          </span>
+        )}
+      </span>
+    );
+  };
+
+  return (
+    <span aria-hidden className={cn("absolute inset-0 block", PHOTO_GROUND, className)}>
+      {mode === "mosaic" ? (
+        <span className={cn("absolute inset-0 grid gap-px", mosaicClassName)}>
+          {photos.map((_, index) =>
+            slot(index, phoneTiles !== undefined && index >= phoneTiles ? "hidden lg:block" : undefined)
+          )}
+        </span>
+      ) : (
+        /* Stacked, not swapped, so the change is a cross-fade and not a flash
+           of ground between two images. */
+        photos.map((_, index) =>
+          slot(
+            index,
+            cn(
+              "absolute inset-0 transition-opacity duration-500 motion-reduce:transition-none",
+              index === active ? "opacity-100" : "opacity-0"
+            )
+          )
+        )
+      )}
+
+      {/* The family's colour, one layer over the whole ground. Skipped when
+          there is nothing to colour — a flat tint over the bare ground reads as
+          a mistake rather than as a family. */}
+      {gradient && hasAnyPhoto && (
+        <span
+          className="absolute inset-0 opacity-[0.85] mix-blend-color"
+          style={{ backgroundImage: gradient }}
+        />
+      )}
+
+      {overlay && <span className={cn(OVERLAY, overlayClassName)} />}
+    </span>
+  );
+}

package/src/components/place-types.ts

@@ -33,7 +33,7 @@ export type PlacePreview = {
   busyness?: Array<{ hour: number; score: number }>
   /**
    * The review distillation. Drives every menu-hub surface that speaks for a
-   * venue — `<VenueSpotlight>`, `<RankedVenueList>`, `<SignatureLineList>` —
+   * venue — `<KitchenDossier>`, `<MenuKitchenList>`, `<OpenNowList>` —
    * because the signature dish, the pull-quotes and the graded dimensions all
    * live here rather than on the menu itself.
    */
@@ -158,7 +158,7 @@ export type PlaceReviewsDigest = {
   tagline?: CitedText
   verdict?: CitedText
   caveat?: CitedText
-  /** 1–3 standout positives. The pull-quotes on `<VenueSpotlight>`. */
+  /** 1–3 standout positives. The pull-quotes on `<KitchenDossier>`. */
   highlights?: CitedText[]
   must_try?: PlaceMustTry[]
   /** Vibe codes (cozy, quiet, family_friendly, …). Localised by the caller. */

package/src/components/qa-block.stories.tsx

@@ -0,0 +1,43 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { QaBlock } from "./qa-block";
+import { mockQa } from "./menu-mocks";
+
+const meta: Meta<typeof QaBlock> = {
+  title: "Menu/QaBlock",
+  component: QaBlock,
+  tags: ["autodocs"],
+  args: { items: mockQa, heading: "Questions people ask" },
+  decorators: [
+    (Story) => (
+      <div className="w-[1100px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Questions answered from the numbers, as static prose — **never an accordion**. This block is the visible half of the page's `FAQPage` markup, and structured data must mirror content the reader can actually see; collapsing it hides every answer from the crawler's first paint and buys nothing, since 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.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof QaBlock>;
+
+export const Default: Story = {};
+
+/** Under a page that already supplies its own section heading. */
+export const NoHeading: Story = { args: { heading: undefined } };
+
+export const Mobile: Story = {
+  decorators: [
+    (Story) => (
+      <div className="w-[390px] bg-background p-3">
+        <Story />
+      </div>
+    ),
+  ],
+};