@bearmenu/ui 0.8.9 → 0.8.11

package/src/components/top-ranking-hero.tsx

@@ -0,0 +1,218 @@
+import { ArrowRight, CalendarCheck, Info, LayoutList, Trophy } from "lucide-react";
+import { cn } from "../lib/utils";
+import type { MenuLinkComponent, MenuLinkProps } from "./menu-types";
+import type { TopExit } from "./top-types";
+
+/**
+ * TopRankingHero — the head of an editorial ranking.
+ *
+ * ## It says when, and it says how, before it says what
+ *
+ * The trust contract is the point of `/top`: a visible "Updated" date, the size
+ * of the pool it chose from, and a method line. Those are not fine print here —
+ * they are the reason a reader believes the ten, and they sit where a reader
+ * looks for them rather than at the foot of the page.
+ *
+ * ## The exits are stated, not implied
+ *
+ * Two links out to the browsing tool — "Browse all 247 Italian kitchens" and
+ * "58 open now". The ranking is the editorial pick; the intent page is
+ * everything else, and the page says so rather than leaving a reader who wants
+ * the directory to bounce. Placed here, in the list, and in the Q&A: three, and
+ * never a sticky bar. A sticky CTA on an article is an advert, and this page's
+ * job is to be read to the end.
+ */
+
+function DefaultLink({ href, ...props }: MenuLinkProps) {
+  return <a href={href} {...props} />;
+}
+
+export type TopRankingHeroProps = {
+  /** e.g. "RANKED · CUISINE". */
+  kicker?: string;
+  title: string;
+  /** One paragraph: the size of the pool, and what the order means. */
+  lede?: string;
+  /** e.g. "Updated 6 September 2026". */
+  updatedLabel?: string;
+  /** e.g. "247 kitchens considered · 4,318 reviews read". */
+  metaLabel?: string;
+  exits?: TopExit[];
+  /** Finished CSS gradient for the ground. */
+  gradient?: string;
+  /** Watermark behind the text — the category's icon, resolved by the caller. */
+  icon?: React.ReactNode;
+  linkComponent?: MenuLinkComponent;
+  className?: string;
+};
+
+export function TopRankingHero({
+  kicker,
+  title,
+  lede,
+  updatedLabel,
+  metaLabel,
+  exits,
+  gradient,
+  icon,
+  linkComponent: LinkComponent = DefaultLink,
+  className,
+}: TopRankingHeroProps) {
+  return (
+    <header
+      className={cn(
+        "relative overflow-hidden rounded-[18px] px-5 py-6 lg:px-8 lg:py-8",
+        !gradient && "bg-muted",
+        className
+      )}
+    >
+      {gradient && (
+        <span aria-hidden className="absolute inset-0" style={{ backgroundImage: gradient }} />
+      )}
+
+      {icon && (
+        <span
+          aria-hidden
+          className="pointer-events-none absolute -right-6 -top-6 opacity-[0.14] [&>svg]:h-[150px] [&>svg]:w-[150px] lg:[&>svg]:h-[190px] lg:[&>svg]:w-[190px]"
+        >
+          {icon}
+        </span>
+      )}
+
+      <div className="relative z-[1]">
+        {kicker && (
+          <span className="inline-flex items-center gap-1.5 rounded-full bg-background/70 px-3 py-1 text-[11px] font-extrabold uppercase tracking-[0.09em] backdrop-blur-[2px]">
+            <Trophy className="h-3 w-3 shrink-0" aria-hidden />
+            {kicker}
+          </span>
+        )}
+
+        <h1 className="mt-3 max-w-[22ch] font-serif text-[30px] font-bold leading-[1.08] tracking-[-0.025em] lg:text-[44px]">
+          {title}
+        </h1>
+
+        {lede && (
+          <p className="mt-3 max-w-[62ch] text-[14.5px] leading-relaxed opacity-85">{lede}</p>
+        )}
+
+        {(updatedLabel || metaLabel) && (
+          <div className="mt-4 flex flex-wrap items-center gap-x-3 gap-y-1.5 text-[12.5px]">
+            {updatedLabel && (
+              <span className="inline-flex items-center gap-1.5 font-semibold">
+                <CalendarCheck className="h-3.5 w-3.5 shrink-0" aria-hidden />
+                {updatedLabel}
+              </span>
+            )}
+            {updatedLabel && metaLabel && (
+              <span aria-hidden className="h-1 w-1 rounded-full bg-current opacity-40" />
+            )}
+            {metaLabel && <span className="opacity-75">{metaLabel}</span>}
+          </div>
+        )}
+
+        {/*
+          Desktop only, and not for want of room.
+
+          On a phone the hero already fills the first screen with the kicker,
+          a three-line serif headline, the date and the pool size — everything
+          that says what this page is. Two full-width buttons under that put a
+          call to action above the first entry, so the reader meets an advert
+          before they meet the ranking, and the page's whole argument is that it
+          is worth reading. The exits are stated again under the list, where a
+          reader who has read the argument is actually deciding what to do next.
+
+          Beside a 44px headline on a wide hero they are a row of two, cost one
+          line, and read as orientation rather than as a pitch.
+        */}
+        {exits && exits.length > 0 && (
+          <div className="mt-5 hidden flex-col gap-2 sm:flex-row lg:flex">
+            {exits.map((exit, index) => (
+              <LinkComponent
+                key={exit.href}
+                href={exit.href}
+                className={cn(
+                  "inline-flex h-11 items-center justify-center gap-2 rounded-xl px-4 text-sm font-bold transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 motion-reduce:transition-none",
+                  index === 0
+                    ? "bg-background text-foreground hover:bg-background/90"
+                    : "border border-current/25 hover:bg-background/25"
+                )}
+              >
+                {exit.icon ?? <LayoutList className="h-4 w-4 shrink-0" aria-hidden />}
+                {exit.label}
+                <ArrowRight className="h-3.5 w-3.5 shrink-0" aria-hidden />
+              </LinkComponent>
+            ))}
+          </div>
+        )}
+      </div>
+    </header>
+  );
+}
+
+/**
+ * TopMethodNote — how the ranking was computed, in one block.
+ *
+ * Under the hero rather than at the foot: a reader deciding whether to trust a
+ * list decides it before reading the list, not after.
+ */
+/**
+ * The note's surface, exported so a caller can put the same look on a TRIGGER.
+ *
+ * On `/top` the banner opens the grade explainer, and that explainer owns its
+ * own `<button>` (Radix clones it, so it cannot be handed a ready-made
+ * element). The caller therefore needs the surface without the element — hence
+ * a class string rather than a second component. `cn` at the call site lets the
+ * button's own `inline-flex` lose to the `flex` here.
+ */
+export const topMethodNoteSurface =
+  "flex w-full items-start gap-3 rounded-[14px] bg-muted p-4 text-left";
+
+export type TopMethodNoteProps = {
+  /** The heading fragment, e.g. "How this is ranked." Rendered bold, inline. */
+  heading: string;
+  children: React.ReactNode;
+  /** Rendered after the prose — a chevron where the note is a disclosure trigger. */
+  affordance?: React.ReactNode;
+  className?: string;
+};
+
+/**
+ * The note's CONTENT, with no element of its own.
+ *
+ * Every tag here is phrasing content — spans, not paragraphs — because this
+ * renders inside a `<button>` when the note is a trigger, and a `<p>` inside a
+ * button is invalid. Keeping one definition of the content means the static
+ * note and the interactive one cannot drift apart.
+ */
+export function TopMethodNoteBody({
+  heading,
+  children,
+  affordance,
+}: Omit<TopMethodNoteProps, "className">) {
+  return (
+    <>
+      <Info className="mt-0.5 h-4 w-4 shrink-0 text-muted-foreground" aria-hidden />
+      <span className="block text-[13px] leading-relaxed text-muted-foreground">
+        <b className="font-bold text-foreground">{heading}</b> {children}
+      </span>
+      {affordance}
+    </>
+  );
+}
+
+export function TopMethodNote({ heading, children, affordance, className }: TopMethodNoteProps) {
+  return (
+    <aside className={cn(topMethodNoteSurface, className)}>
+      <TopMethodNoteBody heading={heading} affordance={affordance}>
+        {children}
+      </TopMethodNoteBody>
+    </aside>
+  );
+}
+
+/*
+ * `TopExitRow` used to live here. It is now `TopCrossLink` in
+ * `top-cross-link.tsx`, with a `panel` variant — the same object is needed in
+ * both directions (ranking → browse, and browse → ranking), and its old name
+ * described only the outbound half.
+ */

package/src/components/top-ranking-legend.stories.tsx

@@ -0,0 +1,78 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { TopRankingLegend } from "./top-ranking-legend";
+
+const groups = [
+  {
+    key: "exceptional",
+    label: "Exceptional",
+    entries: [
+      { rank: 1, slug: "a", name: "PASQUALE | brunch & dinner" },
+      { rank: 2, slug: "b", name: "Alle Bollicine Vino & Pasta" },
+      { rank: 3, slug: "c", name: "Mare Nera Seafood Restaurant" },
+      { rank: 4, slug: "d", name: "La 502" },
+    ],
+  },
+  {
+    key: "excellent",
+    label: "Excellent",
+    entries: [
+      { rank: 5, slug: "e", name: "Tortelli Pasta Bar" },
+      { rank: 6, slug: "f", name: "Il forno - vera pizza napoletana" },
+      { rank: 7, slug: "g", name: "Perfetto Cucina Italiana" },
+      { rank: 8, slug: "h", name: "CUCINA TUREA BACANIE cu de toate" },
+    ],
+  },
+  {
+    key: "very-good",
+    label: "Very good",
+    entries: [
+      { rank: 9, slug: "i", name: "GARLIC - bites&tales" },
+      { rank: 10, slug: "j", name: "Pizzeria Dino" },
+      { rank: 11, slug: "k", name: "Motor Rock Bistro" },
+    ],
+  },
+];
+
+const meta: Meta<typeof TopRankingLegend> = {
+  title: "Top/TopRankingLegend",
+  component: TopRankingLegend,
+  tags: ["autodocs"],
+  args: { groups, heading: "The ranking", meta: "25 places · updated September 2026" },
+  decorators: [
+    (Story) => (
+      <div className="w-[280px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The ranking as a place you are inside of, not a table. It was rank / name / grade with a rule under every row: the **grade column** was the loudest thing in it and the least useful for navigating — twenty-five near-identical numbers duplicating a grade shown at full size beside them, eating the width that truncated the names. The **dividers** ran full-bleed to the column edge so nothing ever ended the aside. And there was **no active row at all**, in a component whose whole job is orientation. Now: no grade, no rules, grouped by grade band, and the current entry tracked by an `IntersectionObserver` over a narrow band near the top of the viewport. The **rank numeral is the rail** — a status ring would promise completion state we do not track and would never fill. Below `lg` it is the flat chip row, unchanged.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TopRankingLegend>;
+
+/** No entry is active without a scrolling article behind it — that is correct here. */
+export const Default: Story = {};
+
+/** Long names wrap rather than truncate: the label you navigate by is never cut. */
+export const LongNames: Story = {
+  args: { groups: [groups[1]] },
+};
+
+/** The phone keeps the flat chip row. */
+export const Mobile: Story = {
+  decorators: [
+    (Story) => (
+      <div className="w-[390px] bg-background p-3">
+        <Story />
+      </div>
+    ),
+  ],
+};

package/src/components/top-ranking-legend.tsx

@@ -0,0 +1,239 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * TopRankingLegend — the ranking as a place you are inside of, not a table.
+ *
+ * ## What it stopped being
+ *
+ * It was a two-column table: rank, name, grade, with a rule under every row.
+ * Three things were wrong with that, and they compounded.
+ *
+ * The **grade column** was the loudest thing in it and the least useful thing
+ * for navigating — twenty-five near-identical numbers in accent colour,
+ * duplicating a grade shown at full size two inches to the right, and eating
+ * the width that was truncating the names. The one field you navigate by was
+ * the one being cut. It is gone.
+ *
+ * The **dividers** ran full-bleed to the column's right edge, so every rule was
+ * a small arrow pointing at the article and nothing ever visually ended the
+ * aside. Space separates now; contrast is spent on state instead.
+ *
+ * And there was **no active row at all** — twenty-five identical entries in a
+ * component whose entire job is orientation. That is what the observer below
+ * is for.
+ *
+ * ## The rank numeral is the rail
+ *
+ * The reference this is drawn from uses a status ring down the left edge. A
+ * ring is wrong here: it promises completion state we do not track and would
+ * never fill. The rank numeral is already present, already tabular, and is
+ * itself the thing being ranked — a better rail, for free.
+ *
+ * ## Grouped, because twenty-five is not a list you can hold
+ *
+ * By grade band, which is the one honest grouping available: the tiers are
+ * already printed on the entries, so the aside is not inventing a taxonomy. It
+ * also says something true — that the top few are a different class.
+ *
+ * The column will still exceed the viewport at twenty-five, and that is
+ * accepted rather than solved: an internally-scrolling sidebar is a second page,
+ * and grouping plus a live active row makes the overflow navigable.
+ *
+ * ## The phone keeps its chips
+ *
+ * Below `lg` this is a horizontal scroller of the flat list, unchanged. None of
+ * the above applies to a chip row — there is nothing to group, no column to
+ * inset, and the active state is a press away rather than a scroll away.
+ */
+
+export type TopRankingLegendEntry = {
+  rank: number;
+  slug: string;
+  name: string;
+};
+
+export type TopRankingLegendGroup = {
+  key: string;
+  /** Grade band, e.g. "Exceptional". Letterspaced caps — structure, not content. */
+  label: string;
+  entries: TopRankingLegendEntry[];
+};
+
+export type TopRankingLegendProps = {
+  groups: TopRankingLegendGroup[];
+  /** e.g. "The ranking". */
+  heading: string;
+  /** The size and freshness of the thing, e.g. "25 places · updated September 2026". */
+  meta?: string;
+  className?: string;
+};
+
+/**
+ * Only entries crossing the upper fifth of the viewport count as current.
+ *
+ * A plain `isIntersecting` marks every entry on screen — three or four at
+ * desktop height — and the legend flickers between them. Narrowing the band to
+ * a strip near the top means "current" is the entry you are reading rather than
+ * the entries you can see.
+ */
+const ACTIVE_BAND = "-20% 0px -75% 0px";
+
+export function TopRankingLegend({ groups, heading, meta, className }: TopRankingLegendProps) {
+  const entries = groups.flatMap((group) => group.entries);
+  const [activeSlug, setActiveSlug] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (typeof IntersectionObserver === "undefined") return undefined;
+
+    const nodes = entries
+      .map((entry) => document.getElementById(entry.slug))
+      .filter((node): node is HTMLElement => Boolean(node));
+    if (nodes.length === 0) return undefined;
+
+    const observer = new IntersectionObserver(
+      (observed) => {
+        const inBand = observed.filter((record) => record.isIntersecting);
+        // Nothing in the band means the reader is BETWEEN entries — mid-way
+        // through a long one. Holding the last value is right; clearing it
+        // would blink the active row off on every gap.
+        if (inBand.length === 0) return;
+        const topmost = inBand.reduce((best, record) =>
+          record.boundingClientRect.top < best.boundingClientRect.top ? record : best
+        );
+        setActiveSlug(topmost.target.id);
+      },
+      { rootMargin: ACTIVE_BAND }
+    );
+
+    nodes.forEach((node) => observer.observe(node));
+    return () => observer.disconnect();
+    // Re-observes when the ranking itself changes, not on every render.
+  }, [entries.map((entry) => entry.slug).join("|")]);
+
+  return (
+    /*
+     * The height cap is a safety net, not the navigation model.
+     *
+     * `position: sticky` on an element TALLER than the viewport leaves its
+     * bottom permanently unreachable — at twenty-five rows on a 900px laptop
+     * you could never see ranks 20–25, however you scrolled. That is broken
+     * rather than merely tight, so the column scrolls internally once it
+     * exceeds the space available.
+     *
+     * It only ever engages on a viewport too short to fit the list: `max-height`
+     * with `overflow-y-auto` is inert when the content already fits, so nothing
+     * changes on a tall screen. `overscroll-contain` stops a flick inside the
+     * column from carrying on into the article behind it.
+     */
+    <nav
+      aria-label={heading}
+      className={cn(
+        /*
+         * Sticky at BOTH widths now, with a different offset and a different
+         * shape at each.
+         *
+         * On desktop it is the grouped column, pinned beside the article. On a
+         * phone it is the flat chip rail, pinned for the same reason the column
+         * is: this page is twenty-five long entries, so a reader at rank 14 is
+         * several screens from any means of jumping, and the rail scrolled away
+         * inside the first entry.
+         *
+         * The phone offset comes from `--legend-sticky-top`, which the CALLER
+         * sets, because it is that app's chrome — the consumer app pins under a
+         * fixed header at `calc(var(--header-offset) + env(safe-area-inset-top))`,
+         * exactly as its events day rail does. Reading the app's own
+         * `--header-offset` here would resolve to nothing in Storybook and in
+         * the other three consumers, and an invalid `calc` silently kills
+         * `top`, which turns the rail from mispositioned into not-sticky.
+         */
+        "sticky top-[var(--legend-sticky-top,0px)] z-20 lg:top-4 lg:z-auto",
+        "lg:max-h-[calc(100vh-2rem)] lg:self-start lg:overflow-y-auto lg:overscroll-contain",
+        "lg:[scrollbar-width:thin]",
+        className
+      )}
+    >
+      {/* Header block. The reference opens with the size of the thing before a
+          single row — ours is the count and the date, which were previously
+          buried in a footnote under twenty-five rows nobody scrolls past. */}
+      <div className="hidden lg:block">
+        <h2 className="text-[15px] font-bold tracking-[-0.01em]">{heading}</h2>
+        {meta && <p className="mt-1 text-[11.5px] text-muted-foreground">{meta}</p>}
+      </div>
+
+      {/* Phone: the flat chip rail.
+
+          The negative margin bleeds the band to both edges, so once the `<nav>`
+          is pinned it covers the article passing underneath — untinted, the
+          entries would scroll straight through the chips.
+
+          OPAQUE, not the events day rail's translucent-plus-blur. That rail
+          passes over body text, where a blur reads as depth; this one passes
+          over 25 photographs, and at 85% a cover's dark edge showed straight
+          through the chips — the strip stopped being a surface and started
+          looking like a rendering fault. `pb-3` is the rail's own breathing
+          room: at `py-0` the chips sat hard against the section heading below
+          and read as part of it. */}
+      <ul className="scrollbar-hide -mx-[var(--page-gutter)] flex gap-2 overflow-x-auto bg-background px-[var(--page-gutter)] pb-3 pt-1 lg:hidden">
+        {entries.map((entry) => (
+          <li key={entry.slug} className="shrink-0">
+            <a
+              href={`#${entry.slug}`}
+              className="inline-flex h-9 items-center gap-2 whitespace-nowrap rounded-full border border-border bg-card px-3.5 text-[13px] transition-colors hover:border-accent/40 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring motion-reduce:transition-none"
+            >
+              <span className="font-bold tabular-nums text-muted-foreground">{entry.rank}</span>
+              {entry.name}
+            </a>
+          </li>
+        ))}
+      </ul>
+
+      {/* Desktop: grouped column. `-mx-3` so the active pill reaches the column
+          edge while the text stays inset — the separation lives inside the
+          column, which is most of why the reference breathes. */}
+      <div className="hidden lg:mt-5 lg:-mx-3 lg:block">
+        {groups.map((group) => (
+          <div key={group.key} className="mb-4 last:mb-0">
+            <p className="px-3 pb-1.5 text-[10.5px] font-bold uppercase tracking-[0.11em] text-muted-foreground">
+              {group.label}
+            </p>
+            <ul>
+              {group.entries.map((entry) => {
+                const isActive = entry.slug === activeSlug;
+                return (
+                  <li key={entry.slug}>
+                    <a
+                      href={`#${entry.slug}`}
+                      aria-current={isActive ? "location" : undefined}
+                      className={cn(
+                        "flex gap-2.5 rounded-lg px-3 py-2 text-[13px] leading-snug transition-colors motion-reduce:transition-none",
+                        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+                        isActive
+                          ? "bg-accent-subtle font-semibold text-foreground"
+                          : "text-muted-foreground hover:bg-muted/50 hover:text-foreground"
+                      )}
+                    >
+                      <span
+                        className={cn(
+                          "w-5 shrink-0 text-right font-bold tabular-nums",
+                          isActive ? "text-accent" : "text-muted-foreground/70"
+                        )}
+                      >
+                        {entry.rank}
+                      </span>
+                      {/* Wraps rather than truncates: the label you navigate by
+                          is the one thing that must never be cut. */}
+                      <span className="min-w-0 flex-1">{entry.name}</span>
+                    </a>
+                  </li>
+                );
+              })}
+            </ul>
+          </div>
+        ))}
+      </div>
+    </nav>
+  );
+}

package/src/components/top-types.ts

@@ -0,0 +1,110 @@
+/**
+ * The editorial ranking's view model — `/top/[category]`.
+ *
+ * Separate from `menu-types.ts` on purpose. The menu surfaces describe what a
+ * city HAS; these describe an argument the product is making about it, and the
+ * shapes reflect that: an entry carries a cited quote and a dated price because
+ * a rank is a claim and the page has to show why.
+ *
+ * Same contract as everywhere else: no app schemas, no hooks, no i18n. Strings
+ * arrive through labels, destinations through `href`, numbers through injected
+ * formatters.
+ */
+
+import type { ReactNode } from 'react'
+
+import type { MenuItemPreview } from './menu-types'
+
+/** One entry in the ranking. */
+export type TopRankEntry = {
+  rank: number
+  slug: string
+  name: string
+  /** The venue page. */
+  href: string
+  /** Neighbourhood, e.g. "Centru". */
+  district?: string
+  /** Pre-resolved venue photograph. */
+  coverUrl?: string
+  /** The app's grade, already formatted — "9.4". Absent where none exists. */
+  gradeLabel?: string
+  /** The band that grade falls in, e.g. "Exceptional". Composed by the caller. */
+  tierLabel?: string
+  /** Third-party star rating, shown only where there is no grade. */
+  rating?: number
+  /**
+   * The editorial line — why this one is here, in the product's own voice.
+   *
+   * Distinct from `evidence`, which is a reviewer's words. Conflating them was
+   * the old page's problem: a quote presented as editorial reads as invented,
+   * and editorial presented as a quote reads as dishonest.
+   */
+  editorial?: string
+  /**
+   * The dishes this venue is named for, as PRODUCTION MENU ROWS.
+   *
+   * `MenuItemPreview`, so the entry renders the same `<MenuItem>` a venue's own
+   * menu and every hub surface renders. The first pass here hand-rolled a row —
+   * a bold name, a muted description, a price — which drifted from the real one
+   * immediately and meant a dish looked like a different object on this page
+   * than on every other.
+   *
+   * More than one, because a rank is a claim about a kitchen and one dish
+   * rarely carries it: the live page shows the group and two or three of its
+   * most-named plates.
+   */
+  menuItems?: MenuItemPreview[]
+  /** The group those items sit in, e.g. "Pizza". From the venue's own menu. */
+  menuGroupLabel?: string
+  /** A reviewer's own words, and how many said it. */
+  evidence?: TopEvidence
+}
+
+export type TopEvidence = {
+  /**
+   * A reviewer's own words. OPTIONAL: a venue can carry a mention count with no
+   * quotable snippet behind it, and the count is evidence in its own right —
+   * dropping the whole block for want of a quote loses the number that
+   * justifies the rank.
+   */
+  quote?: string
+  /**
+   * How many reviews back it — the figure alone, e.g. "37". Rendered as its own
+   * element beside `sourceLabel` so the number reads as a figure rather than as
+   * the first word of a sentence.
+   */
+  count?: string
+  /** What the count is evidence OF, e.g. "reviews praise the shawarma here". */
+  sourceLabel: string
+  /**
+   * The rest of the cited reviews, behind a disclosure.
+   *
+   * A `<details>`, not a drawer, and that is the whole point: its contents stay
+   * in the HTML, so the evidence is crawlable and readable with no JavaScript.
+   * A page whose entire argument is "here is why" cannot ship most of the why
+   * in a modal.
+   */
+  extraQuotes?: string[]
+  /** Summary text for the disclosure, e.g. "2 more reviews". Pluralised by the caller. */
+  extraLabel?: string
+}
+
+/** One row of the side-by-side comparison. */
+export type TopComparisonRow = {
+  rank: number
+  name: string
+  href: string
+  gradeLabel?: string
+  signature?: string
+  priceLabel?: string
+  /** Kitchen serving past midnight. */
+  late?: boolean
+  terrace?: boolean
+}
+
+/** A way out of the article and into the browsing tool. */
+export type TopExit = {
+  label: string
+  href: string
+  icon?: ReactNode
+}

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

@@ -24,7 +24,7 @@ import type { PlaceGradeDimensions } from "./place-types";
 export type VenueGradeDimensionKey = keyof PlaceGradeDimensions;
 
 /** Canonical order. Quality leads, and the three quality keys are mutually exclusive. */
-const DEFAULT_ORDER: VenueGradeDimensionKey[] = [
+export const DIMENSION_ORDER: VenueGradeDimensionKey[] = [
   "food",
   "coffee_quality",
   "drinks_quality",
@@ -50,7 +50,7 @@ export type VenueGradeDimensionsProps = {
 export function VenueGradeDimensions({
   dimensions,
   labels,
-  order = DEFAULT_ORDER,
+  order = DIMENSION_ORDER,
   formatScore,
   className,
 }: VenueGradeDimensionsProps) {

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

@@ -19,7 +19,7 @@ const meta: Meta<typeof VenueQuotes> = {
     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.",
+          "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 quoted serif 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.",
       },
     },
   },