@bearmenu/ui 0.8.12 → 0.8.14

package/src/components/doorway-tiles.tsx

@@ -0,0 +1,225 @@
+import { cn } from "../lib/utils";
+import type { MenuLinkComponent, MenuLinkProps } from "./menu-types";
+import { PhotoGround } from "./photo-ground";
+
+/**
+ * DoorwayTiles — a grid of doors: every class the reader browses by, as
+ * coloured tiles two to a row (four from `lg`), closed by one tile that opens
+ * the whole index. The menu hub's cuisine and going-out families are one
+ * caller; the homepage's occasions are another.
+ *
+ * ## A tile, not a card
+ *
+ * The tile is the class's NAME, its venue count and one photograph on the
+ * class's hue, so seven doors and the index fit on one phone screen. The
+ * reader is choosing a door here, not learning about one; the summary lives
+ * on the page the tile opens.
+ *
+ * ## Two treatments, one rule: object → polaroid, atmosphere → ground
+ *
+ * `polaroid` — one square photograph, tilted, running off the tile's top and
+ * right edges, with the name and the count under its lower edge. For a tile
+ * about a THING: a plate, a glass, a loaf. The print reads as "this is the
+ * thing"; the hue is what tells seven tiles apart at a glance.
+ *
+ * `ground` — the photograph IS the tile, multiplied by the hue. For a tile
+ * about a MOOD: a room, a table, a night. There is no specimen to print, so
+ * the room becomes the ground. Under `mix-blend-multiply` the photograph can
+ * never be lighter than the hue — the brightest pixel is the bare hue and
+ * everything else a darker shade of it — so seven tinted rooms stay seven
+ * distinguishable hues, and the label never lands on a highlight. A second
+ * layer of the hue at 22% lies over the image so shadows stay the hue's own
+ * dark and never black: black under wine or plum reads as a broken image.
+ *
+ * The treatment is per grid, never per tile. Sibling tiles share one shape.
+ *
+ * The photograph is the CLASS's — a plate, a room, a glass — served from the
+ * consumer's own origin, never a venue's (a venue on a tile about every venue
+ * reads as an endorsement). A class with no photograph gets the same tilted
+ * square holding `PhotoGround`'s serif initial (polaroid) or the initial on
+ * the bare hue (ground), so the silhouette never changes.
+ *
+ * Every measure on the polaroid is a percentage of the tile, so the tile and
+ * the design stay in proportion from a 170px phone cell to a 260px desktop
+ * one: 82% of the height, 8% above the top, 4% past the right, 8° over.
+ *
+ * ## The scrim is shared, and it is measured
+ *
+ * The honey and terrace hues sit around `oklch(0.6…)`, where white at 14.5px
+ * is about 3.7:1 bare — under the 4.5:1 the label needs. The scrim runs
+ * three quarters of the tile, 0.64 at the foot and 0.46 at 40% of its own
+ * height, so white passes 4.5:1 on every hue in the dictionary up to a
+ * two-line label's FIRST line (honey, the brightest, is 4.69:1 there in the
+ * worst case of a pure-white photo highlight). An earlier three-fifths scrim
+ * ran out exactly where a wrapped "Breakfast & brunch" starts.
+ *
+ * Server-safe.
+ */
+
+function DefaultLink({ href, ...props }: MenuLinkProps) {
+  return <a href={href} {...props} />;
+}
+
+/**
+ * A door — a cuisine, a going-out family, an occasion — as the doorway grid
+ * draws it: a hue, a name, a venue count and one photograph.
+ *
+ * `href` is required: a tile that cannot resolve to a real destination is not
+ * rendered rather than linking nowhere.
+ */
+export type DoorwayTile = {
+  slug: string;
+  label: string;
+  /**
+   * The venue count, already formatted by the caller — "64", "1,204" — because
+   * thousands separators are locale-dependent and the DS owns no locale.
+   */
+  countLabel?: string;
+  href: string;
+  /**
+   * Finished CSS gradient for the tile's ground, e.g.
+   * `linear-gradient(150deg, …)`.
+   *
+   * A gradient rather than a token name, for the same reason `<MenuField>`
+   * takes one: the hue tables are app-owned, and a component referencing
+   * `var(--h-pizza)` renders an invisible tile in any consumer that does not
+   * happen to define that variable. A missing gradient falls back to `bg-muted`
+   * — visible and obviously unstyled, rather than white text on white.
+   */
+  gradient?: string;
+  /** Pre-resolved photograph of the CLASS, from the consumer's own origin. */
+  photoUrl?: string;
+};
+
+export type DoorwayTilesTreatment = "polaroid" | "ground";
+
+export type DoorwayTilesProps = {
+  tiles: DoorwayTile[];
+  /**
+   * The closing tile: the index behind the doors, drawn exactly like them —
+   * its own hue and photograph, `countLabel` as the caption. Only its place in
+   * the grid says it is the index. Omit when there is none.
+   */
+  all?: DoorwayTile;
+  /**
+   * `polaroid`: hue ground, one tilted print — a tile about a thing.
+   * `ground`: the photograph is the ground, multiplied by the hue — a tile
+   * about a mood. Required, per grid: two callers, two words, no hidden default.
+   */
+  treatment: DoorwayTilesTreatment;
+  linkComponent?: MenuLinkComponent;
+  className?: string;
+};
+
+/**
+ * The tile: 16:10 on the phone (the design's 170×110 cell), 2:1 from `lg`,
+ * never shorter than two lines of name plus the count need.
+ */
+const TILE =
+  "group relative isolate flex aspect-[16/10] min-h-[108px] flex-col justify-end overflow-hidden rounded-2xl bg-muted p-3.5 text-white lg:aspect-[2/1] lg:p-4 " +
+  "transition-[transform,box-shadow] duration-200 hover:-translate-y-0.5 hover:shadow-[var(--shadow-card-hover)] active:translate-y-0 active:scale-[0.99] motion-reduce:transition-none " +
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background";
+
+/**
+ * The polaroid. Same literal family as `PHOTO_GROUND` for the shadow, never a
+ * black `rgba` — the shadow is the ground the card family already stands on.
+ */
+const POLAROID =
+  "absolute -right-[4%] -top-[8%] z-0 block aspect-square h-[82%] overflow-hidden rounded-[10%] rotate-[8deg] " +
+  "shadow-[0_10px_22px_-6px_oklch(0.16_0.012_55_/_0.65)] transition-transform duration-300 group-hover:rotate-[5deg] motion-reduce:transition-none";
+
+/** One scrim for both treatments — see the docblock for the measure. */
+const SCRIM =
+  "after:pointer-events-none after:absolute after:inset-x-0 after:bottom-0 after:z-0 after:h-3/4 after:content-[''] " +
+  "after:bg-[linear-gradient(to_top,oklch(0.16_0.012_55_/_0.64)_0%,oklch(0.16_0.012_55_/_0.46)_40%,transparent_100%)]";
+
+/** The ground photograph, multiplied by the hue the tile already paints. */
+const GROUND_PHOTO =
+  "absolute inset-0 z-0 h-full w-full object-cover mix-blend-multiply " +
+  "transition-transform duration-500 ease-out group-hover:scale-[1.04] motion-reduce:transition-none motion-reduce:group-hover:scale-100";
+
+/** 22% of the hue back over the photograph: shadows stay the hue's dark, never black. */
+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";
+
+export function DoorwayTiles({
+  tiles,
+  all,
+  treatment,
+  linkComponent: LinkComponent = DefaultLink,
+  className,
+}: DoorwayTilesProps) {
+  const cells = all ? [...tiles, all] : tiles;
+  const isPolaroid = treatment === "polaroid";
+
+  return (
+    <div className={cn("grid grid-cols-2 gap-3 lg:grid-cols-4 lg:gap-3.5", className)}>
+      {cells.map((tile) => {
+        const ground = tile.gradient ? { backgroundImage: tile.gradient } : undefined;
+        return (
+          <LinkComponent
+            key={tile.slug}
+            href={tile.href}
+            className={cn(TILE, SCRIM)}
+            style={ground}
+          >
+            {isPolaroid ? (
+              <span aria-hidden className={POLAROID}>
+                {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
+                  <img
+                    src={tile.photoUrl}
+                    alt=""
+                    decoding="async"
+                    className="absolute inset-0 h-full w-full object-cover"
+                  />
+                ) : (
+                  <PhotoGround
+                    photos={[undefined]}
+                    initials={tile.label.charAt(0)}
+                    mode="stack"
+                    glyphClassName="text-[44px]"
+                  />
+                )}
+              </span>
+            ) : tile.photoUrl ? (
+              <>
+                {/* eslint-disable-next-line @next/next/no-img-element */}
+                <img src={tile.photoUrl} alt="" decoding="async" className={GROUND_PHOTO} />
+                <span aria-hidden className={GROUND_LIFT} style={ground} />
+              </>
+            ) : (
+              <span aria-hidden className={GROUND_GLYPH}>
+                {tile.label.charAt(0)}
+              </span>
+            )}
+
+            {/* On the polaroid both lines keep to the left 55%: the print owns the right. */}
+            <span
+              className={cn(
+                "relative z-[1] line-clamp-2 text-[14.5px] font-extrabold leading-[1.2] tracking-[-0.015em] lg:text-[16px]",
+                isPolaroid && "max-w-[55%]"
+              )}
+            >
+              {tile.label}
+            </span>
+            {tile.countLabel && (
+              <span
+                className={cn(
+                  "relative z-[1] mt-0.5 truncate text-[12px] font-medium leading-[1.35] tabular-nums text-white/80 lg:text-[13px]",
+                  isPolaroid && "max-w-[55%]"
+                )}
+              >
+                {tile.countLabel}
+              </span>
+            )}
+          </LinkComponent>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/grade-atom.stories.tsx

@@ -0,0 +1,81 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { GradeAtom, type GradeAtomLabels } from "./grade-atom";
+
+const labels: GradeAtomLabels = {
+  soft: "Worth exploring",
+  bands: {
+    exceptional: "Exceptional",
+    great: "Great",
+    good: "Good",
+    decent: "Decent",
+    weak: "Weak",
+  },
+  aria: (value) => `Grade ${value} out of 10`,
+  capped: "Capped for low confidence",
+};
+
+const meta = {
+  title: "Components/GradeAtom",
+  component: GradeAtom,
+  tags: ["autodocs"],
+  args: { labels, grade: { overall: 8.4 }, size: "md" },
+} satisfies Meta<typeof GradeAtom>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+/** One hue family per band, none shared by neighbours. */
+export const Bands: Story = {
+  render: (args) => (
+    <div className="flex flex-wrap items-center gap-3">
+      {[9.4, 8.1, 6.7, 5.3, 4.2].map((overall) => (
+        <GradeAtom key={overall} {...args} grade={{ overall }} />
+      ))}
+    </div>
+  ),
+};
+
+export const Sizes: Story = {
+  render: (args) => (
+    <div className="flex flex-wrap items-end gap-3">
+      <GradeAtom {...args} size="xs" />
+      <GradeAtom {...args} size="sm" />
+      <GradeAtom {...args} size="md" />
+      <GradeAtom {...args} size="lg" />
+    </div>
+  ),
+};
+
+/** `show_number=false` — the backend recommends against a number; nothing at `xs`. */
+export const Soft: Story = {
+  args: { grade: { overall: 5.1, show_number: false } },
+};
+
+export const Capped: Story = {
+  args: { grade: { overall: 7.9, capped: true } },
+};
+
+export const OnPhoto: Story = {
+  args: { onPhoto: true, size: "lg" },
+  decorators: [
+    (Story) => (
+      <div
+        className="flex h-40 w-72 items-end rounded-xl p-4"
+        style={{
+          backgroundImage:
+            "url(https://images.unsplash.com/photo-1517248135467-4c7edcad34c4?w=800&q=80)",
+          backgroundSize: "cover",
+        }}
+      >
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+/** The disclosure-trigger form used by the place hero. */
+export const WithInfo: Story = {
+  args: { showInfo: true, size: "lg" },
+};

package/src/components/grade-atom.tsx

@@ -0,0 +1,256 @@
+"use client";
+
+/**
+ * GradeAtom — the single, scalable visual for the ReviewsDigest `grade`
+ * (1–10 Romanian school scale, food-anchored). It is the hero metric that
+ * replaces the Google star across place surfaces; the star is demoted into the
+ * meta line by each caller, not here.
+ *
+ * One shape, four sizes (xs card → lg page hero). The number is always the
+ * hero; the descriptor, capped shield and (future) confidence scale in at
+ * larger sizes. Colour band comes from `grade.overall`; the label text is
+ * always the caller's — the backend `descriptor` is null in practice and the
+ * apps own this vocabulary, so it arrives translated in `labels`.
+ *
+ * States:
+ *   - normal       → coloured pill: number (+ descriptor at sm+) (+ capped shield)
+ *   - `show_number=false` → neutral pill with a positive, honest soft label
+ *                           ("Worth exploring" / "Merită explorat"), no number
+ *   - no `overall` → renders nothing, so callers fall back to the Google star
+ */
+
+import { Info, ShieldAlert } from "lucide-react";
+import { cn } from "../lib/utils";
+import {
+  formatGrade,
+  resolveGradeBand,
+  shouldShowGradeNumber,
+  type GradeBand,
+} from "../lib/grade";
+import type { PlaceGrade } from "./place-types";
+
+export type GradeAtomSize = "xs" | "sm" | "md" | "lg";
+
+/** Labels passed to `<GradeAtom>`. All translation happens in the caller. */
+export type GradeAtomLabels = {
+  /** The `show_number=false` state, e.g. "Worth exploring". */
+  soft: string;
+  /** Band → descriptor shown beside the number from `sm` up, e.g. "Great". */
+  bands: Record<GradeBand, string>;
+  /** Accessible name for the pill, e.g. "Grade 8.2 out of 10". */
+  aria: (value: string) => string;
+  /** Title + aria suffix when `grade.capped`, e.g. "Capped for low confidence". */
+  capped: string;
+};
+
+export type GradeAtomProps = {
+  grade: PlaceGrade;
+  labels: GradeAtomLabels;
+  /** xs = card chip · sm = chat/compact · md = drawer · lg = page hero. */
+  size?: GradeAtomSize;
+  /** Force-hide the descriptor even at sizes that would show it (tight rows). */
+  hideDescriptor?: boolean;
+  /** Rendered over a photo (e.g. the page hero). Switches to a frosted-dark
+   *  shell with the band hue on the number + ring, so it stays legible and
+   *  band-recognizable on any image. */
+  onPhoto?: boolean;
+  /**
+   * Adds a trailing `Info` glyph, for the one caller where the chip IS the
+   * disclosure trigger (the place hero, wrapped in a grade explainer).
+   *
+   * Off by default and it must stay that way: on cards this atom is a readout,
+   * and an affordance marker on something that doesn't open would be a lie. The
+   * glyph goes INSIDE the pill rather than beside it — outside, it would be a
+   * bare icon on unpredictable photo luminance, and it would read as a second
+   * control next to the chip instead of part of it.
+   */
+  showInfo?: boolean;
+  className?: string;
+};
+
+// Background + text + inset ring per band, with dark-mode tints. Same shape
+// everywhere — only the fill changes — so the bands read as one family.
+// Fill-led bands: the colour lives in the FILL so each chip reads as a distinct
+// hue at a glance — even at xs before the number is read. Five separate hue
+// families (gold / green / blue / orange / rose); no two adjacent bands share
+// one. `-800` text on `-100` fill clears WCAG AA.
+const BAND_CLASSES: Record<GradeBand, string> = {
+  exceptional:
+    "bg-amber-100 text-amber-800 ring-amber-400 dark:bg-amber-500/20 dark:text-amber-300 dark:ring-amber-500/60",
+  great:
+    "bg-emerald-100 text-emerald-800 ring-emerald-400 dark:bg-emerald-500/20 dark:text-emerald-300 dark:ring-emerald-500/60",
+  good: "bg-sky-100 text-sky-800 ring-sky-400 dark:bg-sky-500/20 dark:text-sky-300 dark:ring-sky-500/60",
+  decent:
+    "bg-orange-100 text-orange-800 ring-orange-400 dark:bg-orange-500/20 dark:text-orange-300 dark:ring-orange-500/60",
+  weak: "bg-rose-100 text-rose-800 ring-rose-400 dark:bg-rose-500/20 dark:text-rose-200 dark:ring-rose-500/60",
+};
+
+const SOFT_CLASSES = "bg-muted text-muted-foreground ring-border";
+
+// On-photo variant: a frosted-dark shell — established by the hero's other
+// on-photo chips — with the band hue moved onto the NUMBER text + the ring
+// (the two elements the eye hits first), descriptor in white. A drop-shadow
+// lifts the pill off bright photo regions. Keeps a guaranteed contrast floor
+// that a light fill can't promise on an unpredictable image.
+const PHOTO_SHELL =
+  "bg-black/45 text-white backdrop-blur-sm ring-white/10 drop-shadow-[0_2px_6px_rgba(0,0,0,0.55)]";
+
+const BAND_CLASSES_PHOTO: Record<GradeBand, { ring: string; num: string }> = {
+  exceptional: { ring: "ring-amber-400/70", num: "text-amber-300" },
+  great: { ring: "ring-emerald-400/70", num: "text-emerald-300" },
+  good: { ring: "ring-sky-400/70", num: "text-sky-300" },
+  // Brighter/more saturated than the warm-canvas orange so it doesn't bleed into
+  // warm (restaurant) photos or compress toward the sky band on the dark shell.
+  decent: { ring: "ring-orange-300/90", num: "text-orange-200" },
+  weak: { ring: "ring-rose-400/70", num: "text-rose-200" },
+};
+
+// `minW` is what keeps a rail of chips rectangular. `formatGrade` strips a
+// trailing `.0`, so the value is 1–3 glyphs ("9", "10", "8.2") and a
+// content-sized pill made every card's chip a different width — the number is
+// the one element users compare ACROSS cards, and a ragged right edge reads as
+// noise in the comparison. Fixed on the box rather than by padding the number
+// to "9.0": that decimal is real precision the grade doesn't carry, and it
+// would follow `formatGrade` onto the detail hero at `text-3xl`.
+//
+// Each value clears the widest number the pill can hold at that size (three
+// glyphs of `tabular-nums` plus the horizontal padding) with a little room
+// spare. It never binds when a descriptor or the capped shield is present —
+// that content is already wider — so only the bare-number chips are affected.
+const SIZE: Record<
+  GradeAtomSize,
+  {
+    box: string;
+    minW: string;
+    num: string;
+    desc: string;
+    gap: string;
+    shield: string;
+    showDesc: boolean;
+  }
+> = {
+  xs: {
+    box: "h-6 px-1.5 rounded-md",
+    minW: "min-w-9",
+    num: "text-[13px]",
+    desc: "text-2xs",
+    gap: "gap-1",
+    shield: "h-3 w-3",
+    showDesc: false,
+  },
+  sm: {
+    box: "h-7 px-2 rounded-md",
+    minW: "min-w-11",
+    num: "text-sm",
+    desc: "text-2xs",
+    gap: "gap-1.5",
+    shield: "h-3 w-3",
+    showDesc: true,
+  },
+  md: {
+    box: "h-9 px-2.5 rounded-lg",
+    minW: "min-w-14",
+    num: "text-lg",
+    desc: "text-xs",
+    gap: "gap-1.5",
+    shield: "h-3.5 w-3.5",
+    showDesc: true,
+  },
+  lg: {
+    box: "h-12 px-3.5 rounded-xl",
+    minW: "min-w-20",
+    num: "text-3xl",
+    desc: "text-sm",
+    gap: "gap-2",
+    shield: "h-4 w-4",
+    showDesc: true,
+  },
+};
+
+export function GradeAtom({
+  grade,
+  labels,
+  size = "md",
+  hideDescriptor,
+  onPhoto,
+  showInfo,
+  className,
+}: GradeAtomProps) {
+  const overall = grade.overall;
+
+  // No grade yet → render nothing; the surface keeps its Google star fallback.
+  if (overall == null) return null;
+
+  const sz = SIZE[size];
+
+  // Same footprint as the capped shield, so the two trailing glyphs line up when
+  // a capped grade shows both. `opacity-70` rather than a colour: it has to sit
+  // one step behind the descriptor on the frosted shell AND on the five light
+  // band fills, and inheriting each shell's own text colour is the only rule
+  // that holds in both.
+  const infoGlyph = showInfo ? (
+    <Info className={cn("shrink-0 opacity-70", sz.shield)} aria-hidden />
+  ) : null;
+
+  // Soft state: the backend recommends against showing a number (thin/divided
+  // signal). Positive, honest framing instead of a bare low score.
+  //
+  // Suppressed at `xs`: the card title-row slot is sized for a 2–3 glyph
+  // number, and this label is a sentence — it wrapped inside its own
+  // fixed-height pill and forced the place name into a hard truncation. The
+  // caller falls back to its Google star instead (gate on `showsGradeAtom`, and
+  // see its note for why callers can't test `overall != null` any more).
+  if (!shouldShowGradeNumber(grade)) {
+    if (size === "xs") return null;
+    return (
+      <span
+        className={cn(
+          "inline-flex items-center justify-center font-medium ring-1 ring-inset",
+          onPhoto ? PHOTO_SHELL : SOFT_CLASSES,
+          sz.box,
+          sz.minW,
+          sz.desc,
+          sz.gap,
+          className
+        )}
+      >
+        {labels.soft}
+        {infoGlyph}
+      </span>
+    );
+  }
+
+  const band = resolveGradeBand(overall);
+  const value = formatGrade(overall);
+  const descriptor = labels.bands[band];
+  const showDesc = sz.showDesc && !hideDescriptor;
+  const photo = onPhoto ? BAND_CLASSES_PHOTO[band] : null;
+
+  return (
+    <span
+      className={cn(
+        // `justify-center` so a 1-glyph "9" sits centred in the reserved width
+        // instead of hugging the left edge of a pill sized for "8.2".
+        "inline-flex items-center justify-center font-semibold ring-1 ring-inset",
+        photo ? cn(PHOTO_SHELL, photo.ring) : BAND_CLASSES[band],
+        sz.box,
+        sz.minW,
+        sz.gap,
+        className
+      )}
+      aria-label={grade.capped ? `${labels.aria(value)} — ${labels.capped}` : labels.aria(value)}
+      title={grade.capped ? labels.capped : undefined}
+    >
+      <span className={cn("font-extrabold tabular-nums leading-none", sz.num, photo?.num)}>
+        {value}
+      </span>
+      {showDesc && (
+        <span className={cn("font-medium leading-none", sz.desc, onPhoto && "text-white/80")}>
+          {descriptor}
+        </span>
+      )}
+      {grade.capped && <ShieldAlert className={cn("shrink-0", sz.shield)} aria-hidden />}
+      {infoGlyph}
+    </span>
+  );
+}

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

@@ -34,9 +34,9 @@ export const EveryFamily: Story = {
         ["Breakfast & Brunch", "oklch(0.62 0.14 82)"],
         ["Romanian", "oklch(0.48 0.16 25)"],
         ["Italian", "oklch(0.56 0.15 38)"],
-        ["Vegetarian", "oklch(0.52 0.14 148)"],
+        ["Vegetarian", "oklch(0.48 0.13 150)"],
         ["Bars", "oklch(0.47 0.10 205)"],
-        ["Clubs", "oklch(0.42 0.11 300)"],
+        ["Clubs", "oklch(0.34 0.06 210)"],
       ].map(([label, hue]) => (
         <HueChip key={label} hue={hue}>
           {label}

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

@@ -78,6 +78,35 @@ export const Bare: Story = {
   },
 };
 
+/**
+ * The dishes index's concept card — the same block with the unit swapped:
+ * a kicker over the name, the names count beside the kitchens, the mentions
+ * in the corner pill, name chips instead of dish-group chips, and no hue.
+ */
+export const Concept: Story = {
+  args: {
+    family: {
+      ...mockFamilyBlock,
+      slug: "papanasi",
+      name: "Papanași",
+      kicker: "Dessert concept",
+      venueCount: 70,
+      facts: ["50 names"],
+      badge: "168 mentions",
+      priceBandLabel: "8–44 lei",
+      chips: [
+        { slug: "a", label: "Papanași cu smântână", count: 0 },
+        { slug: "b", label: "Papanași ropogoși", count: 0 },
+        { slug: "c", label: "+48", count: 0 },
+      ],
+      photoUrls: PHOTOS,
+    },
+    labels: { ...labels, browse: "See all 70 kitchens", browseShort: "See all 70" },
+    hue: undefined,
+    gradient: undefined,
+  },
+};
+
 /** The ink runs top to bottom: clear photography under the name, the rows on the inked foot. */
 export const Mobile: Story = {
   args: { family: { ...mockFamilyBlock, photoUrls: PHOTOS } },

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

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { MenuFamilyBlock, type MenuFamilyBlockLabels } from "./menu-family-block";
+import type { MenuFamilyBlockPreview } from "./menu-types";
+
+const labels: MenuFamilyBlockLabels = {
+  venueUnit: (count) => `${count} kitchens`,
+  more: (count) => `+${count} more`,
+  priceBand: "kitchen price band",
+  browse: "Browse",
+  kitchens: {
+    openVenue: (name) => `Open ${name}`,
+    openDish: (name) => `See ${name}`,
+    openNow: "Open now",
+  },
+};
+
+const family: MenuFamilyBlockPreview = {
+  slug: "italian",
+  name: "Italian",
+  venueCount: 96,
+  href: "/menu/cuisines/italian",
+};
+
+describe("MenuFamilyBlock", () => {
+  it("draws the overflow pill from the venues it cannot show", () => {
+    render(<MenuFamilyBlock family={family} labels={labels} />);
+    expect(screen.getByText("+96 more")).toBeInTheDocument();
+  });
+
+  it("as a concept card: the badge replaces the overflow pill, the kicker and facts join the count line", () => {
+    render(
+      <MenuFamilyBlock
+        family={{
+          ...family,
+          kicker: "Dessert concept",
+          facts: ["50 names"],
+          badge: "168 mentions",
+          priceBandLabel: "8–44 lei",
+        }}
+        labels={labels}
+      />
+    );
+    expect(screen.getByText("168 mentions")).toBeInTheDocument();
+    expect(screen.queryByText("+96 more")).not.toBeInTheDocument();
+    expect(screen.getByText("Dessert concept")).toBeInTheDocument();
+    expect(screen.getByText("96 kitchens")).toBeInTheDocument();
+    expect(screen.getByText("50 names")).toBeInTheDocument();
+    expect(screen.getByText("8–44 lei")).toBeInTheDocument();
+  });
+});