@bearmenu/ui 0.8.16 → 0.8.17

package/src/components/coach-marks.tsx

@@ -0,0 +1,252 @@
+"use client";
+
+import { useCallback, useEffect, useLayoutEffect, useState } from "react";
+import { createPortal } from "react-dom";
+import { ArrowRight, Lightbulb } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Button } from "./button";
+
+/**
+ * CoachMarks — a guided tour drawn OVER the real page.
+ *
+ * Four things, one at a time: the page dims, the current stop's target is cut
+ * out of the dimming in a spotlight, its step number sits on the spotlight's
+ * corner, and one callout beside the spotlight says what the target is. Only
+ * the current stop is marked — a map of every stop's number over the page
+ * competes with the page's own numerals and with the callout's "Step N of
+ * M"; the way through is Next, Back and the arrow keys. The reader learns
+ * the surface by looking at the surface, not at a picture of it; nothing on
+ * the page moves or re-renders to be taught.
+ *
+ * Targets are found by `data-coach-mark="<stop id>"` on the page's own
+ * elements, so the page keeps its markup and the tour attaches from outside.
+ * The tour is built from the stops whose target is ON THE PAGE when it opens
+ * (or when the itinerary changes): a stop with nothing to point at is not
+ * counted, so "Step 3 of 5" is always a step the reader will reach. Where
+ * the same id is on two elements — a desktop and a phone rendering of one
+ * control — the visible one is taken.
+ *
+ * The consumer owns the words (`labels`, `stops`) and the open state; the
+ * tour owns its position, the geometry (8px breathing room, the callout's
+ * side, re-measure on scroll and resize) and the keys (Escape closes, the
+ * arrows step). `onProgress` reports the current stop for a toolbar label.
+ *
+ * Rendered into `document.body`: a page wrapper with an opacity or transform
+ * transition is a stacking context, and the tour must sit above everything
+ * the page and its chrome draw, whatever wraps the consumer.
+ */
+
+export type CoachMarkStop = {
+  /** Matches the target's `data-coach-mark` attribute. */
+  id: string;
+  title: string;
+  body: string;
+};
+
+export type CoachMarksLabels = {
+  /** "Step 2 of 4". */
+  progress: (step: number, total: number) => string;
+  back: string;
+  next: string;
+  /** The last stop's forward action, e.g. "Done". */
+  done: string;
+  skip: string;
+};
+
+export type CoachMarksProps = {
+  open: boolean;
+  stops: CoachMarkStop[];
+  /** Skip, Done, Escape and a tap on the dimmed page all end here. */
+  onClose: () => void;
+  /**
+   * 1-based position, the count of stops the page actually has, and the
+   * stop being shown — its id is what a consumer remembers, since the
+   * position shifts when a stop's target is missing.
+   */
+  onProgress?: (step: number, total: number, stop: CoachMarkStop) => void;
+  labels: CoachMarksLabels;
+  className?: string;
+};
+
+type Rect = { top: number; left: number; width: number; height: number };
+
+const PAD = 8;
+const CALLOUT_WIDTH = 320;
+const CALLOUT_GAP = 14;
+/** The room a side needs before the callout goes there. */
+const CALLOUT_ROOM = 280;
+const EDGE = 12;
+
+/** The step number, an inverted disc on the spotlight's corner: dark on the gold ring. */
+const PIN =
+  "pointer-events-none absolute z-[1] flex h-8 w-8 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-full bg-[oklch(0.26_0.03_60)] text-[13px] font-extrabold text-[oklch(0.82_0.15_85)] ring-2 ring-[oklch(0.82_0.15_85)] shadow-[0_2px_8px_oklch(0.16_0.012_55_/_0.45)] transition-[top,left] duration-300 motion-reduce:transition-none";
+
+/** The visible element carrying the id — a `display: none` twin has no boxes. */
+function findTarget(id: string): HTMLElement | null {
+  if (typeof document === "undefined") return null;
+  const candidates = document.querySelectorAll<HTMLElement>(`[data-coach-mark="${id}"]`);
+  for (const candidate of candidates) {
+    if (candidate.getClientRects().length > 0) return candidate;
+  }
+  return null;
+}
+
+function measure(element: HTMLElement): Rect {
+  const box = element.getBoundingClientRect();
+  return { top: box.top, left: box.left, width: box.width, height: box.height };
+}
+
+export function CoachMarks({ open, stops, onClose, onProgress, labels, className }: CoachMarksProps) {
+  // The stops the page can show, fixed when the tour opens or the itinerary
+  // changes — by its ids, so a consumer rebuilding the array each render does
+  // not send the tour back to the first stop.
+  const [available, setAvailable] = useState<CoachMarkStop[]>([]);
+  const [index, setIndex] = useState(0);
+  const [rect, setRect] = useState<Rect | null>(null);
+  const [viewport, setViewport] = useState({ width: 0, height: 0 });
+  const itinerary = stops.map((stop) => stop.id).join("|");
+
+  useLayoutEffect(() => {
+    if (!open) return;
+    const present = stops.filter((stop) => findTarget(stop.id));
+    setAvailable(present);
+    setIndex(0);
+    if (present.length === 0) onClose();
+    // `stops` is read whenever its ids change; the words alone do not restart the tour.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open, itinerary]);
+
+  const current = available[index];
+  const currentId = current?.id;
+
+  const remeasure = useCallback(() => {
+    const element = currentId ? findTarget(currentId) : null;
+    setRect(element ? measure(element) : null);
+    setViewport({ width: window.innerWidth, height: window.innerHeight });
+  }, [currentId]);
+
+  // Bring the current target into view, then measure it — again once the
+  // smooth scroll has settled.
+  useLayoutEffect(() => {
+    if (!open || !current) return;
+    const element = findTarget(current.id);
+    if (!element) {
+      // The page changed under the tour: move on, or end when nothing is left.
+      const forward = available.findIndex((stop, at) => at > index && findTarget(stop.id));
+      if (forward !== -1) setIndex(forward);
+      else onClose();
+      return;
+    }
+    element.scrollIntoView({ block: "center", behavior: "smooth", inline: "nearest" });
+    remeasure();
+    const settle = setTimeout(remeasure, 400);
+    return () => clearTimeout(settle);
+  }, [open, current, index, available, remeasure, onClose]);
+
+  useEffect(() => {
+    if (!open || !current) return;
+    onProgress?.(index + 1, available.length, current);
+  }, [open, current, index, available.length, onProgress]);
+
+  useEffect(() => {
+    if (!open) return;
+    window.addEventListener("resize", remeasure);
+    window.addEventListener("scroll", remeasure, true);
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") onClose();
+      if (event.key === "ArrowRight") setIndex((at) => Math.min(at + 1, available.length - 1));
+      if (event.key === "ArrowLeft") setIndex((at) => Math.max(at - 1, 0));
+    };
+    window.addEventListener("keydown", onKey);
+    return () => {
+      window.removeEventListener("resize", remeasure);
+      window.removeEventListener("scroll", remeasure, true);
+      window.removeEventListener("keydown", onKey);
+    };
+  }, [open, remeasure, onClose, available.length]);
+
+  if (!open || !current || !rect) return null;
+
+  const last = index === available.length - 1;
+  const spot = {
+    top: rect.top - PAD,
+    left: rect.left - PAD,
+    width: rect.width + PAD * 2,
+    height: rect.height + PAD * 2,
+  };
+  // Below the target when there is room for the callout, else above it; a
+  // target taller than the viewport leaves room on neither side, and the
+  // callout then sits at the bottom edge, over the target's lower part.
+  const roomBelow = viewport.height - (spot.top + spot.height);
+  const calloutLeft = Math.min(
+    Math.max(spot.left, EDGE),
+    Math.max(EDGE, viewport.width - CALLOUT_WIDTH - EDGE)
+  );
+  const calloutPlace =
+    roomBelow > CALLOUT_ROOM
+      ? { top: spot.top + spot.height + CALLOUT_GAP, left: calloutLeft }
+      : spot.top > CALLOUT_ROOM
+        ? { bottom: viewport.height - spot.top + CALLOUT_GAP, left: calloutLeft }
+        : { bottom: EDGE, left: calloutLeft };
+
+  return createPortal(
+    <div
+      className={cn("fixed inset-0 z-[80]", className)}
+      role="dialog"
+      aria-modal
+      aria-label={current.title}
+    >
+      {/* The dimming is the spotlight's shadow: one element, cut out where
+          the target is, so the target stays fully visible and the rest of the
+          page falls back. A tap on the dim closes the tour. */}
+      <button
+        type="button"
+        aria-label={labels.skip}
+        onClick={onClose}
+        className="absolute inset-0 cursor-default"
+      />
+      <div
+        aria-hidden
+        className="pointer-events-none absolute rounded-[18px] shadow-[0_0_0_9999px_oklch(0.16_0.012_55_/_0.55)] ring-2 ring-[oklch(0.82_0.15_85)] transition-[top,left,width,height] duration-300 motion-reduce:transition-none"
+        style={spot}
+      />
+
+      {/* The step number on the spotlight's corner; the callout says the rest. */}
+      <span aria-hidden className={PIN} style={{ top: rect.top - 2, left: rect.left - 2 }}>
+        {index + 1}
+      </span>
+
+      {/* The callout. */}
+      <div
+        className="absolute z-[2] w-[min(320px,calc(100vw-24px))] rounded-2xl border border-border bg-card p-4 text-card-foreground shadow-xl"
+        style={calloutPlace}
+      >
+        <span className="inline-flex items-center gap-1.5 rounded-full bg-[oklch(0.82_0.15_85)] px-2.5 py-1 text-[10.5px] font-extrabold uppercase tracking-[0.08em] text-[oklch(0.26_0.03_60)]">
+          <Lightbulb className="h-3 w-3" aria-hidden />
+          {labels.progress(index + 1, available.length)}
+        </span>
+        <p className="mt-3 text-[15px] font-bold leading-snug">{current.title}</p>
+        <p className="mt-1.5 text-sm leading-relaxed text-muted-foreground">{current.body}</p>
+        <div className="mt-4 flex items-center gap-2">
+          {index > 0 && (
+            <Button type="button" variant="ghost" size="sm" onClick={() => setIndex(index - 1)}>
+              {labels.back}
+            </Button>
+          )}
+          <Button
+            type="button"
+            size="sm"
+            onClick={() => (last ? onClose() : setIndex(index + 1))}
+          >
+            {last ? labels.done : labels.next}
+            {!last && <ArrowRight aria-hidden />}
+          </Button>
+          <Button type="button" variant="link" size="sm" className="ml-auto" onClick={onClose}>
+            {labels.skip}
+          </Button>
+        </div>
+      </div>
+    </div>,
+    document.body
+  );
+}

package/src/components/doorway-tiles.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react";
+import { TextSearch } from "lucide-react";
 import { DoorwayTiles } from "./doorway-tiles";
 import {
   mockFamilyTiles,
@@ -58,6 +59,25 @@ export const PolaroidPartial: Story = {
   args: { treatment: "polaroid", tiles: mockFamilyTiles.slice(0, 5) },
 };
 
+/**
+ * The closing tile as a door to an ACTION — the menu's search page. No
+ * photograph, no initial: the print holds a glyph on the photo ground, and
+ * the tile keeps its siblings' silhouette.
+ */
+export const PolaroidWithSearchDoor: Story = {
+  args: {
+    treatment: "polaroid",
+    tiles: mockFamilyTiles,
+    all: {
+      ...mockFamilyTilesAll,
+      label: "Search the menu",
+      countLabel: "535 dishes · 210 drinks",
+      photoUrl: undefined,
+      icon: <TextSearch strokeWidth={1.75} aria-hidden />,
+    },
+  },
+};
+
 /** The occasions: the mood's hue multiplied over a room. */
 export const Ground: Story = {
   args: { treatment: "ground", tiles: mockOccasionTiles, all: mockOccasionTilesAll },
@@ -81,3 +101,17 @@ export const GroundWithoutPhotos: Story = {
     tiles: mockOccasionTiles.map(({ photoUrl: _photoUrl, ...tile }) => tile),
   },
 };
+
+/** The closing tile as a door to an action on the ground treatment: the glyph where the initial was. */
+export const GroundWithActionDoor: Story = {
+  args: {
+    treatment: "ground",
+    tiles: mockOccasionTiles,
+    all: {
+      ...mockOccasionTilesAll,
+      label: "Search the menu",
+      photoUrl: undefined,
+      icon: <TextSearch strokeWidth={1.75} aria-hidden />,
+    },
+  },
+};

package/src/components/doorway-tiles.test.tsx

@@ -30,6 +30,33 @@ describe("DoorwayTiles", () => {
     expect(screen.getByText(withoutPhoto.label.charAt(0))).toBeInTheDocument();
   });
 
+  // A door about an action carries a glyph in the print: no photograph, and
+  // not the initial either — that would read as a family starting with "S".
+  it("draws the glyph, not the initial or the photo, where a tile has an icon", () => {
+    const search = {
+      ...mockFamilyTilesAll,
+      label: "Search the menu",
+      icon: <svg data-testid="glyph" />,
+    };
+    render(<DoorwayTiles treatment="polaroid" tiles={mockFamilyTiles.slice(0, 1)} all={search} />);
+    expect(screen.getByTestId("glyph")).toBeInTheDocument();
+    expect(screen.queryByText("S")).not.toBeInTheDocument();
+    expect(document.querySelectorAll("img")).toHaveLength(1);
+  });
+
+  it("ground: the glyph takes the initial's place and no photograph is drawn for it", () => {
+    const door = {
+      ...mockOccasionTilesAll,
+      label: "Search the menu",
+      icon: <svg data-testid="glyph" />,
+    };
+    render(<DoorwayTiles treatment="ground" tiles={mockOccasionTiles.slice(0, 1)} all={door} />);
+    expect(screen.getByTestId("glyph")).toBeInTheDocument();
+    expect(screen.queryByText("S")).not.toBeInTheDocument();
+    const withPhoto = mockOccasionTiles.slice(0, 1).filter((t) => t.photoUrl).length;
+    expect(document.querySelectorAll("img")).toHaveLength(withPhoto);
+  });
+
   it("omits the index tile when no index is given", () => {
     render(<DoorwayTiles treatment="polaroid" tiles={mockFamilyTiles.slice(0, 3)} />);
     expect(screen.getAllByRole("link")).toHaveLength(3);

package/src/components/doorway-tiles.tsx

@@ -1,6 +1,6 @@
 import { cn } from "../lib/utils";
 import type { MenuLinkComponent, MenuLinkProps } from "./menu-types";
-import { PhotoGround } from "./photo-ground";
+import { PHOTO_GLYPH_SHADOW, PHOTO_GROUND, PhotoGround } from "./photo-ground";
 
 /**
  * DoorwayTiles — a grid of doors: every class the reader browses by, as
@@ -89,6 +89,17 @@ export type DoorwayTile = {
   gradient?: string;
   /** Pre-resolved photograph of the CLASS, from the consumer's own origin. */
   photoUrl?: string;
+  /**
+   * A glyph in the photograph's place — for a tile about an ACTION, not a
+   * thing. A search door has no class to photograph, and any subject put on
+   * it (a table, a lens, a book) reads as one more family; the initial the
+   * fallback draws is a family's initial too. So the print holds the glyph
+   * instead, on the photo ground with the photo fallback's drop shadow, and
+   * the tile keeps its siblings' silhouette. Wins over `photoUrl`.
+   *
+   * A node rather than a name: the app owns its iconography.
+   */
+  icon?: React.ReactNode;
 };
 
 export type DoorwayTilesTreatment = "polaroid" | "ground";
@@ -144,6 +155,17 @@ const GROUND_LIFT = "absolute inset-0 z-0 opacity-[0.22]";
 const GROUND_GLYPH =
   "absolute inset-0 z-0 flex items-center justify-center font-serif text-[64px] font-semibold leading-none text-white/15";
 
+/**
+ * The action glyph. In the polaroid it fills the print at 44% on the photo
+ * ground, white with the fallback family's drop shadow; on the ground
+ * treatment it takes the initial's place at the initial's weight.
+ */
+const PRINT_ICON =
+  `absolute inset-0 flex items-center justify-center ${PHOTO_GROUND} text-white/90 ` +
+  `[&_svg]:h-[44%] [&_svg]:w-[44%] [&_svg]:${PHOTO_GLYPH_SHADOW}`;
+const GROUND_ICON =
+  "absolute inset-0 z-0 flex items-center justify-center text-white/15 [&_svg]:h-[40%] [&_svg]:w-[40%]";
+
 export function DoorwayTiles({
   tiles,
   all,
@@ -167,7 +189,9 @@ export function DoorwayTiles({
           >
             {isPolaroid ? (
               <span aria-hidden className={POLAROID}>
-                {tile.photoUrl ? (
+                {tile.icon ? (
+                  <span className={PRINT_ICON}>{tile.icon}</span>
+                ) : tile.photoUrl ? (
                   /* Not lazy: the grid sits directly under the hero, and these
                      photographs are the first thing the reader looks at. */
                   // eslint-disable-next-line @next/next/no-img-element
@@ -186,6 +210,10 @@ export function DoorwayTiles({
                   />
                 )}
               </span>
+            ) : tile.icon ? (
+              <span aria-hidden className={GROUND_ICON}>
+                {tile.icon}
+              </span>
             ) : tile.photoUrl ? (
               <>
                 {/* eslint-disable-next-line @next/next/no-img-element */}

package/src/components/facet-group.tsx

@@ -118,6 +118,13 @@ export type FacetGroupProps = Omit<
   /** e.g. "Show all". Omit to hide the trailing action. */
   moreLabel?: string;
   onMore?: () => void;
+  /**
+   * Whether the trailing action has already expanded the options it controls
+   * — set it when `onMore` reveals more rows in place (and `moreLabel` reads
+   * "Show fewer"), so the button carries `aria-expanded`. Leave it unset when
+   * the action opens another surface.
+   */
+  moreExpanded?: boolean;
   className?: string;
 };
 
@@ -133,6 +140,7 @@ export function FacetGroup({
   onToggle,
   moreLabel,
   onMore,
+  moreExpanded,
   className,
   ...rest
 }: FacetGroupProps) {
@@ -304,6 +312,7 @@ export function FacetGroup({
         <button
           type="button"
           onClick={onMore}
+          aria-expanded={moreExpanded}
           className="cursor-pointer pt-[11px] text-[12.5px] font-bold text-primary transition-colors duration-150 hover:text-primary/80 motion-reduce:transition-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:rounded-sm"
         >
           {moreLabel}

package/src/components/hue-chip.test.tsx

@@ -31,9 +31,12 @@ describe("hueTint", () => {
 });
 
 describe("HueChip", () => {
+  // The label sits in an inner span that ellipsises; the chip is its parent.
+  const chipOf = (text: string) => screen.getByText(text).parentElement!;
+
   it("wears the tint when it has a hue", () => {
     render(<HueChip hue="oklch(0.62 0.14 82)">Sweet Pastry</HueChip>);
-    const chip = screen.getByText("Sweet Pastry");
+    const chip = chipOf("Sweet Pastry");
     expect(chip.getAttribute("style")).toContain("oklab");
     expect(chip.className).not.toContain("bg-muted");
   });
@@ -41,7 +44,7 @@ describe("HueChip", () => {
   it("falls back to the neutral rather than to a colour", () => {
     // A facet with no family behind it must not borrow another family's colour.
     render(<HueChip>Fast Food</HueChip>);
-    const chip = screen.getByText("Fast Food");
+    const chip = chipOf("Fast Food");
     expect(chip.className).toContain("bg-muted");
     expect(chip.getAttribute("style")).toBeNull();
   });
@@ -52,7 +55,7 @@ describe("HueChip", () => {
         <HueChip as="li">Salad</HueChip>
       </ul>
     );
-    expect(screen.getByText("Salad").tagName).toBe("LI");
+    expect(chipOf("Salad").tagName).toBe("LI");
   });
 
   it("takes an accessible name for a chip whose text is a bare figure", () => {

package/src/components/hue-chip.tsx

@@ -86,14 +86,17 @@ export function HueChip({
     <Tag
       aria-label={ariaLabel}
       className={cn(
-        "inline-flex h-7 items-center gap-1.5 rounded-full px-2.5 text-[11.5px] text-foreground",
+        // One line, and never wider than its row: a chip that wraps grows past
+        // its 28px and paints over its neighbours; a chip that overflows pushes
+        // the row. The label ellipsises instead.
+        "inline-flex h-7 min-w-0 max-w-full items-center gap-1.5 whitespace-nowrap rounded-full px-2.5 text-[11.5px] text-foreground",
         !hue && "bg-muted",
         className
       )}
       style={hue ? { backgroundColor: hueTint(hue, tone, base) } : undefined}
     >
       {icon}
-      {children}
+      <span className="min-w-0 truncate">{children}</span>
     </Tag>
   );
 }

package/src/components/item.tsx

@@ -20,7 +20,10 @@ const itemVariants = cva(
         lg: "px-5 py-4",
       },
       interactive: {
-        true: "cursor-pointer hover:bg-accent hover:text-accent-foreground active:scale-[0.99]",
+        // The surface tint a hover is, not the brand fill: `bg-accent` here is
+        // the brown, and a row that inverts under the cursor loses its muted
+        // description. Same step the buttons take (`--accent-subtle`).
+        true: "cursor-pointer hover:bg-accent-subtle hover:border-accent/40 active:bg-muted active:scale-[0.99]",
         false: "",
       },
     },

package/src/components/menu-family-block.stories.tsx

@@ -61,6 +61,18 @@ export const Default: Story = {
   args: { family: { ...mockFamilyBlock, photoUrls: PHOTOS } },
 };
 
+/** The phone card at every width — for a desktop rail where the two-column card is too wide to scan. */
+export const Compact: Story = {
+  args: { family: { ...mockFamilyBlock, photoUrls: PHOTOS }, variant: "compact" },
+  decorators: [
+    (Story) => (
+      <div className="w-[360px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
 /**
  * No photographs: the mosaic ground with the family's initial, never a grey box.
  * A missing photograph is not a broken image, and a placeholder makes a real

package/src/components/menu-family-block.tsx

@@ -99,6 +99,13 @@ export type MenuFamilyBlockProps = {
   hue?: string;
   /** Finished CSS gradient — the family's colour over the mosaic. */
   gradient?: string;
+  /**
+   * `wide` (default): the phone card below `lg`, the two-column card — photo
+   * third, rows beside it — from `lg`. `compact`: the phone card at every
+   * width, for a rail on a desktop page where the two-column card is too much
+   * to scan across (the browse page's concept rail).
+   */
+  variant?: "wide" | "compact";
   linkComponent?: MenuLinkComponent;
   className?: string;
 };
@@ -108,17 +115,20 @@ const GROUND = PHOTO_GROUND;
 
 /**
  * The ink. Nearly absent at the top, heavier at the foot on the phone — the
- * top 40% is the photograph, the rows sit on 0.92+; a to-right ramp from
- * `lg`, where the row column brings its own opaque paper anyway. It is the
- * layer the contrast rests on. Literal rather than `var(--scrim)`: that token
- * lives in the app's stylesheet, not this package's, so a DS component reading
- * it renders nothing in Storybook and the other three consumers.
+ * top 40% is the photograph, the rows sit on 0.92+. It is the layer the
+ * contrast rests on. Literal rather than `var(--scrim)`: that token lives in
+ * the app's stylesheet, not this package's, so a DS component reading it
+ * renders nothing in Storybook and the other three consumers.
  */
-const INK =
-  "bg-[linear-gradient(to_bottom,oklch(0.16_0.012_55_/_0.12)_0%,oklch(0.16_0.012_55_/_0.55)_38%,oklch(0.16_0.012_55_/_0.92)_62%,oklch(0.16_0.012_55_/_0.96)_100%)] lg:bg-[linear-gradient(to_right,oklch(0.16_0.012_55_/_0.38)_0%,oklch(0.16_0.012_55_/_0.6)_30%,oklch(0.16_0.012_55_/_0.92)_46%,oklch(0.16_0.012_55_/_0.96)_100%)]";
-
-/** The row column's paper from `lg`: the card's dark, opaque. */
-const PAPER = "lg:bg-[oklch(0.21_0.012_55)]";
+const INK_PHONE =
+  "bg-[linear-gradient(to_bottom,oklch(0.16_0.012_55_/_0.12)_0%,oklch(0.16_0.012_55_/_0.55)_38%,oklch(0.16_0.012_55_/_0.92)_62%,oklch(0.16_0.012_55_/_0.96)_100%)]";
+/**
+ * From `lg` the ramp runs to the right: clear over the photo third, dark
+ * under the rows — the rows sit on the ink itself, no opaque paper, so the
+ * photograph still reads through the ramp's shoulder.
+ */
+const INK_WIDE =
+  "lg:bg-[linear-gradient(to_right,oklch(0.16_0.012_55_/_0.32)_0%,oklch(0.16_0.012_55_/_0.62)_34%,oklch(0.16_0.012_55_/_0.9)_52%,oklch(0.16_0.012_55_/_0.96)_100%)]";
 
 /**
  * A second, LOCAL scrim under the name, count and action — the photo column's
@@ -144,9 +154,11 @@ export function MenuFamilyBlock({
   formatCount = String,
   hue,
   gradient,
+  variant = "wide",
   linkComponent: LinkComponent = DefaultLink,
   className,
 }: MenuFamilyBlockProps) {
+  const wide = variant === "wide";
   const [photo] = family.photoUrls ?? [];
   // "+N more" counts past the rows shown, which are the venues the reader can
   // see — the photograph is one of them, not a venue on its own.
@@ -161,7 +173,9 @@ export function MenuFamilyBlock({
       className={cn(
         /* `isolate` confines the blend and the backdrop-filter to this card.
            `dark` scopes every token inside to its dark-theme value. */
-        "dark relative isolate overflow-hidden rounded-[14px] text-foreground",
+        /* A flex column, so a `h-full` card in a rail fills its row: siblings
+           with two rows and with three end on the same baseline. */
+        "dark relative isolate flex flex-col overflow-hidden rounded-[14px] text-foreground",
         GROUND,
         className
       )}
@@ -171,21 +185,32 @@ export function MenuFamilyBlock({
       <PhotoGround photos={[photo]} initials={initial} mode="stack" gradient={gradient} />
 
       {/* ── Layer 2: the ink ────────────────────────────────────────────── */}
-      <span aria-hidden className={cn("absolute inset-0", INK)} />
+      <span aria-hidden className={cn("absolute inset-0", INK_PHONE, wide && INK_WIDE)} />
 
       {/* ── The content, floating ───────────────────────────────────────── */}
-      <div className="relative grid grid-cols-1 lg:grid-cols-[34%_1fr]">
+      <div
+        className={cn(
+          "relative grid flex-1 grid-cols-1 grid-rows-[auto_1fr]",
+          wide && "lg:grid-cols-[34%_1fr] lg:grid-rows-1"
+        )}
+      >
         {/* The photo column. On the phone it is the card's head, with the
             overflow pill pinned to the corner and the photograph clear above
             the name; on desktop the left third, its stack anchored to the foot. */}
         <div
           className={cn(
-            "relative flex min-h-[220px] flex-col justify-end p-3.5 lg:min-h-[320px] lg:p-5",
+            "relative flex min-h-[220px] flex-col justify-end p-3.5",
+            wide && "lg:min-h-[320px] lg:p-5",
             TEXT_SCRIM
           )}
         >
           {pill && (
-            <span className="absolute right-3.5 top-3.5 rounded-full bg-[oklch(0.16_0.012_55_/_0.78)] px-2.5 py-1 text-[11px] font-semibold text-white lg:static lg:mb-3 lg:self-start">
+            <span
+              className={cn(
+                "absolute right-3.5 top-3.5 rounded-full bg-[oklch(0.16_0.012_55_/_0.78)] px-2.5 py-1 text-[11px] font-semibold text-white",
+                wide && "lg:static lg:mb-3 lg:self-start"
+              )}
+            >
               {pill}
             </span>
           )}
@@ -195,7 +220,12 @@ export function MenuFamilyBlock({
               {family.kicker}
             </span>
           )}
-          <h3 className="text-balance font-serif text-[26px] font-semibold leading-tight tracking-[-0.02em] text-white lg:text-[30px]">
+          <h3
+            className={cn(
+              "text-balance font-serif text-[26px] font-semibold leading-tight tracking-[-0.02em] text-white",
+              wide && "lg:text-[30px]"
+            )}
+          >
             {family.name}
           </h3>
           {/* The count, the facts and the band on one line: a few facts about
@@ -230,7 +260,7 @@ export function MenuFamilyBlock({
             aria-label={labels.browse}
             className={cn(buttonVariants({ variant: "ink", size: "pill" }), "mt-3.5 w-max max-w-full")}
           >
-            {labels.browseShort ? (
+            {labels.browseShort && wide ? (
               <>
                 <span className="lg:hidden">{labels.browse}</span>
                 <span className="hidden lg:inline">{labels.browseShort}</span>
@@ -241,10 +271,10 @@ export function MenuFamilyBlock({
           </LinkComponent>
         </div>
 
-        {/* The row column: chips, then the rows, on paper from `lg`. */}
-        <div className={cn("flex min-w-0 flex-col px-3.5 pb-3.5 lg:p-5", PAPER)}>
+        {/* The row column: chips, then the rows, on the ink's dark shoulder. */}
+        <div className={cn("flex min-w-0 flex-col px-3.5 pb-3.5", wide && "lg:p-5")}>
           {family.chips && family.chips.length > 0 && (
-            <ul className="flex flex-wrap items-center gap-1.5 lg:justify-end">
+            <ul className={cn("flex flex-wrap items-center gap-1.5", wide && "lg:justify-end")}>
               {family.chips.map((chip) => (
                 /* Label only. The counts are VENUES beside a dish group's name,
                    which every reader takes for dishes. */
@@ -261,6 +291,9 @@ export function MenuFamilyBlock({
               <MenuKitchenList
                 kitchens={venues}
                 labels={labels.kitchens}
+                /* A half-width column: the dish goes under the venue, not
+                   beside it. The compact card is the phone row throughout. */
+                layout={wide ? "stacked" : "phone"}
                 linkComponent={LinkComponent}
               />
             </>