@bearmenu/ui 0.8.9 → 0.8.10

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

@@ -0,0 +1,425 @@
+import { MapPin, MessageSquareQuote, Star } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Separator } from "./separator";
+import { Skeleton } from "./skeleton";
+import { MenuItem, type MenuItemLabels } from "./menu-item";
+import type { MenuItemPreview, MenuLinkComponent, MenuLinkProps } from "./menu-types";
+import type { TopRankEntry } from "./top-types";
+
+/**
+ * TopRankingEntry — one rank, as an article entry.
+ *
+ * ## A numbered editorial list, not a grid of cards
+ *
+ * Cards imply a grid you filter, and they force every entry into the same
+ * height — wrong when the evidence varies, because one kitchen has a three-line
+ * quote and another has a sentence. A numbered list lets each entry be as long
+ * as its argument, which is what reads as an article, which is what ranks.
+ *
+ * ## Evidence leads, because a rank is a claim
+ *
+ * The cited review is the entry's first content, not a footnote. The dish it
+ * names sits under it with its price and its mention count. The old page had
+ * this the other way round — name, grade, photo, then evidence somewhere below
+ * the fold — which asked the reader to accept the position before showing them
+ * any reason for it.
+ *
+ * ## Two targets, the same rule as everywhere
+ *
+ * The entry goes to the venue; the signature dish opens the item drawer. Not
+ * implemented as a stretched overlay here, unlike `MenuKitchenList`: this entry
+ * is a paragraph of prose with several links inside it, so a full-bleed overlay
+ * would swallow them. The name and the cover are the venue's targets.
+ */
+
+function DefaultLink({ href, ...props }: MenuLinkProps) {
+  return <a href={href} {...props} />;
+}
+
+export type TopRankingEntryLabels = {
+  /** Heading over the menu rows when the venue's own group is unknown. */
+  signature: string;
+  /** Accessible name for the dish link. */
+  openDish: (name: string) => string;
+  /** Passed through to the production `<MenuItem>`. */
+  item: MenuItemLabels;
+  /**
+   * Opens an item's drawer. The DS owns no routing, so the caller composes it.
+   *
+   * Takes the ITEM, not its slug: a menu row is a dish or a drink and the two
+   * resolve through different endpoints, so the caller has to see `kind` to
+   * build the right link. `undefined` leaves the row inert, which is the
+   * text-only must-try mention with no live menu row behind it.
+   */
+  itemHref: (item: MenuItemPreview) => string | undefined;
+};
+
+export type TopRankingEntryProps = {
+  entry: TopRankEntry;
+  labels: TopRankingEntryLabels;
+  formatPrice: (amount: number) => string;
+  formatCount?: (value: number) => string;
+  /** The category's hue, for the menu rows' colour mark. */
+  markGradient?: string;
+  linkComponent?: MenuLinkComponent;
+  className?: string;
+};
+
+/**
+ * The scrim under the rank, name, district and grade on the phone.
+ *
+ * A literal, never `var(--scrim)`: that token is defined in the consumer app's
+ * stylesheet and not in this package's, so a DS component reading it renders an
+ * invisible scrim in Storybook, admin and the post-generator — and the failure
+ * only appears in the consumers nobody is looking at. Same base colour as
+ * `MenuFamilyCard` and `MenuFamilyBlock`, so the three are one family.
+ *
+ * The stops are in PIXELS from the block's top, not percentages of the cover.
+ * The cover is an aspect ratio, so its height runs 192px to 265px across the
+ * phone range and the name wraps to one line or two; a percentage ramp would
+ * put the first glyph anywhere between alpha 0.52 and 0.79 depending on the
+ * handset and the venue. Anchored to the fixed `pt-12` runway it is 0.72 every
+ * time — which is what makes the contrast floor a guarantee rather than an
+ * average. Against a pure-white photograph that is 7.3:1 on the name.
+ *
+ * If it ever bands on a flat bright sky, lengthen the runway (`pt-14`, 0.72
+ * stop to 56px). Never lower the terminal alpha — that is the guarantee.
+ *
+ * Applied unprefixed and cleared with `lg:bg-none`, NOT written as `max-lg:`.
+ * This project's Tailwind emits no `max-width` media queries at all, so every
+ * `max-lg:` class is silently dropped — no error, no style, and on this
+ * component that meant white type on white paper in the gap under the photo.
+ */
+const ENTRY_COVER_SCRIM =
+  "bg-[linear-gradient(180deg,oklch(0.16_0.012_55_/_0)_0px,oklch(0.16_0.012_55_/_0.06)_16px,oklch(0.16_0.012_55_/_0.3)_32px,oklch(0.16_0.012_55_/_0.72)_48px,oklch(0.16_0.012_55_/_0.95)_100%)]";
+
+export function TopRankingEntry({
+  entry,
+  labels,
+  formatPrice,
+  formatCount,
+  markGradient,
+  linkComponent: LinkComponent = DefaultLink,
+  className,
+}: TopRankingEntryProps) {
+  const initial = (entry.name.match(/\p{L}/u)?.[0] ?? "").toLocaleUpperCase();
+
+  return (
+    <article
+      id={entry.slug}
+      /* A one-column GRID on the phone so the identity block can share the
+         cover's cell, and the same flex row it always was from `lg` — the
+         desktop declarations below compute to exactly today's box. */
+      className={cn("grid grid-cols-1 gap-0 py-6 lg:flex lg:flex-row lg:gap-7", className)}
+    >
+      {/*
+        The cover sits beside the entry rather than above it: the column has the
+        room, and a full-width photograph per entry turns twenty-five of them
+        into a scroll with no argument visible at any point.
+
+        ## One box, the same on every entry
+
+        It was 300×225, and entries run roughly 300–370px tall — so the short
+        cover left a hole under itself on nearly all of them. Letting it stretch
+        to the row would close that, but then no two entries share a photo size,
+        and a ranking whose thumbnails all differ reads as broken rather than as
+        responsive. Fixed 4:5 instead: it sits at the common entry height, and
+        where it overshoots, the text simply ends — a much softer failure than an
+        image floating above a void.
+
+        `object-cover` absorbs the source ratios. Restaurant photography is
+        landscape, so a 4:5 centre-crop loses the sides and keeps the subject.
+      */}
+      <LinkComponent
+        href={entry.href}
+        className="col-start-1 row-start-1 block shrink-0 overflow-hidden rounded-xl transition-opacity focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring active:opacity-90 motion-reduce:transition-none lg:sticky lg:top-4 lg:w-[300px] lg:self-start"
+      >
+        {/* 3:2 on the phone, 4:5 from `lg`.
+            4:5 is ~448px at 390 — an entry ran ~880px, so a reader met one
+            venue per two screens on a page whose unit of reading is the entry.
+            3:2 halves the cover and, with the identity line folded into it,
+            brings an entry to roughly one viewport. It is also the ratio the
+            source photography is actually shot at, so unlike 4:5 the crop
+            throws almost nothing away.
+
+            The warm ground is the phone's; desktop restores its stripes. Base
+            first and `lg:` to override, never `max-lg:` — this project's
+            Tailwind emits no `max-width` media queries at all, so a `max-lg:`
+            class is silently dropped and the style simply never exists. */}
+        <span className="relative block aspect-[3/2] w-full bg-[oklch(0.21_0.012_55)] lg:aspect-[4/5] lg:bg-[repeating-linear-gradient(135deg,oklch(0.82_0.014_55)_0_10px,oklch(0.87_0.01_58)_10px_20px)]">
+          {entry.coverUrl ? (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img
+              src={entry.coverUrl}
+              alt=""
+              loading="lazy"
+              decoding="async"
+              className="h-full w-full object-cover"
+            />
+          ) : (
+            /* Never a grey box: the warm ground with the venue's initial, the
+               rule `MenuFamilyBlock` states. Phone only — desktop keeps its
+               stripes. The stripes are a LIGHT surface in both themes, so at
+               this size they would be a pale rectangle under white type.
+               The ground stays on the parent span, so a 404 on `coverUrl`
+               degrades to the same surface for free. */
+            <span
+              aria-hidden
+              className="absolute inset-0 flex items-center justify-center lg:hidden"
+            >
+              <span className="font-serif text-[64px] font-semibold leading-none text-white/25">
+                {initial}
+              </span>
+            </span>
+          )}
+        </span>
+      </LinkComponent>
+
+      {/* `contents` on the phone so the identity block below becomes a direct
+          grid child and can be placed in the cover's cell. One DOM copy, not a
+          `hidden`/`lg:hidden` twin: this page's whole value is search, and 25
+          duplicated headings and venue links is not a thing to ship to avoid a
+          `display: contents`. */}
+      <div className="contents lg:block lg:min-w-0 lg:flex-1">
+        {/* On the phone this sits IN the photograph, bottom-anchored, and
+            carries its own scrim. Grid paints items in document order, so the
+            block covers the cover anchor with no `z-index`.
+
+            `flex-wrap` + `basis-full` on the rank is what gives the phone its
+            two-line stack — rank on its own line, then the name column and the
+            grade pill sharing the next — while desktop keeps the single
+            no-wrap row with the numeral out to the left. One DOM order, two
+            compositions, no duplicated markup. */}
+        <div
+          className={cn(
+            /* `relative z-[1]`: without it this block's background is a
+               non-positioned box's background, which paints in an earlier phase
+               than the cover's replaced `<img>` — so the scrim went UNDER the
+               photograph and the white type landed on bare image. Positioning
+               it lifts the whole block, background included, above the image.
+               Harmless at `lg`, where the two no longer overlap. */
+            "pointer-events-none relative z-[1] col-start-1 row-start-1 flex flex-wrap items-end gap-x-3 gap-y-0 self-end",
+            "rounded-b-xl px-3.5 pb-3.5 pt-12 [text-shadow:0_1px_2px_oklch(0.16_0.012_55_/_0.45)]",
+            ENTRY_COVER_SCRIM,
+            "lg:pointer-events-auto lg:flex-nowrap lg:items-start lg:gap-3 lg:rounded-none lg:bg-none lg:p-0 lg:[text-shadow:none]"
+          )}
+        >
+          <span
+            aria-hidden
+            className="basis-full text-[11px] font-bold leading-none tabular-nums text-white/70 lg:basis-auto lg:font-serif lg:text-[28px] lg:font-semibold lg:text-muted-foreground"
+          >
+            {entry.rank}
+          </span>
+
+          <div className="min-w-0 flex-1">
+            <h3 className="line-clamp-2 text-lg font-bold leading-tight tracking-[-0.015em] text-white lg:line-clamp-none lg:text-foreground">
+              <LinkComponent
+                href={entry.href}
+                /* `lg:hover:` — sticky hover on touch would leave the name
+                   terracotta on the scrim, which measures 1.28:1. The ring
+                   inverts for the same reason: `--ring` is a dark brown drawn
+                   on a dark scrim. */
+                className="pointer-events-auto focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white lg:focus-visible:ring-ring lg:hover:text-accent"
+              >
+                {entry.name}
+              </LinkComponent>
+            </h3>
+            {entry.district && (
+              <span className="mt-0.5 flex items-center gap-1 text-[12.5px] text-white/80 lg:text-muted-foreground">
+                <MapPin className="h-3 w-3 shrink-0" aria-hidden />
+                {entry.district}
+              </span>
+            )}
+          </div>
+
+          {/* The grade, with the band it falls in. A bare 8.7 is a number; "8.7
+              Excellent" is the claim the number is making. The star is the
+              third-party fallback for a venue the reviews have not graded.
+
+              Over the photograph it INVERTS rather than dissolving: a white
+              pill with dark ink, the same mode-invariant device the family
+              block's "Browse" pill uses. `bg-accent-subtle` could not stay —
+              it is near-white in one theme and near-black in the other, and
+              photography is not themed — and dropping the container instead
+              would have cost the band word, which is the half that says what
+              the number MEANS. */}
+          {entry.gradeLabel ? (
+            <span className="inline-flex shrink-0 items-center gap-1.5 rounded-full bg-white/95 px-2.5 py-1 backdrop-blur-[2px] lg:gap-2 lg:rounded-lg lg:bg-accent-subtle lg:px-2.5 lg:py-1.5 lg:backdrop-blur-none">
+              <b className="text-[15px] font-extrabold tabular-nums text-[oklch(0.21_0.012_55)] lg:text-accent">
+                {entry.gradeLabel}
+              </b>
+              {entry.tierLabel && (
+                <span className="text-[11.5px] text-[oklch(0.21_0.012_55)]/70 lg:text-muted-foreground">
+                  {entry.tierLabel}
+                </span>
+              )}
+            </span>
+          ) : (
+            entry.rating !== undefined && (
+              /* The star fallback inverts the same way as the grade — a white
+                 pill, deliberately quieter than a grade, because a third-party
+                 rating is weaker evidence and should look it. Filled, since an
+                 outlined star at this size disappears over photography. */
+              <span className="inline-flex shrink-0 items-center gap-1 rounded-full bg-white/95 px-2.5 py-1 text-[13px] font-semibold tabular-nums text-[oklch(0.21_0.012_55)] backdrop-blur-[2px] lg:bg-transparent lg:px-0 lg:py-0 lg:text-foreground lg:backdrop-blur-none">
+                <Star
+                  className="h-3.5 w-3.5 shrink-0 fill-[oklch(0.21_0.012_55)] lg:fill-none"
+                  aria-hidden
+                />
+                {entry.rating}
+              </span>
+            )
+          )}
+        </div>
+
+        {/* The place caption: large enough to be the entry's argument, quiet
+            enough not to be its headline.
+            At 17px in full foreground it was the loudest block in the entry and
+            competed with the venue name — three lines of black serif italic
+            reads as a pull-quote, not as supporting prose. The size stays,
+            because it is what fills the column beside a 4:5 cover; the COLOUR
+            drops instead. Weight is the wrong lever here: the serif italic is
+            what makes the page read as an article. */}
+        {entry.editorial && (
+          /* The article's row gap is 0 on the phone now that the identity block
+             lives inside the photograph, so the paragraph owns the space under
+             it and gives it back at `lg`. */
+          <p className="mt-4 font-serif text-[17px] italic leading-[1.65] text-muted-foreground [text-wrap:pretty] lg:mt-3">
+            {entry.editorial}
+          </p>
+        )}
+
+        {entry.menuItems && entry.menuItems.length > 0 && (
+          <div className="mt-4">
+            <span className="block pb-1.5 text-[15px] font-bold tracking-[-0.01em]">
+              {entry.menuGroupLabel ?? labels.signature}
+            </span>
+            <Separator />
+            {/* The production `<MenuItem>`, so a dish is visibly the same object
+                here as on the venue's own menu and on every hub surface. The
+                row owns its own padding and its colour mark is drawn at
+                `-ml-4`, so it is not wrapped in anything that would clip it. */}
+            {entry.menuItems.map((item) => (
+              <MenuItem
+                key={item.id}
+                item={item}
+                labels={labels.item}
+                formatPrice={formatPrice}
+                formatCount={formatCount}
+                markGradient={markGradient}
+                href={labels.itemHref(item)}
+                linkLabel={labels.openDish(item.name)}
+                linkComponent={LinkComponent}
+              />
+            ))}
+          </div>
+        )}
+
+        {entry.evidence && (
+          <figure className="mt-4 border-l-[3px] border-border pl-4">
+            {entry.evidence.quote && (
+              <blockquote className="text-[13.5px] leading-relaxed text-muted-foreground [text-wrap:pretty]">
+                {`“${entry.evidence.quote}”`}
+              </blockquote>
+            )}
+            <figcaption
+              className={cn(
+                "flex items-center gap-1.5 text-[11.5px] text-muted-foreground",
+                entry.evidence.quote && "mt-1.5"
+              )}
+            >
+              <MessageSquareQuote className="h-3 w-3 shrink-0 opacity-60" aria-hidden />
+              {entry.evidence.count && (
+                <b className="font-bold tabular-nums text-foreground">{entry.evidence.count}</b>
+              )}
+              {entry.evidence.sourceLabel}
+            </figcaption>
+
+            {/* A `<details>`, never a drawer: its contents ship in the HTML, so
+                the remaining evidence is crawlable and readable with no
+                JavaScript. On a page whose argument IS the evidence, hiding
+                most of it behind a modal gives away the argument. */}
+            {entry.evidence.extraQuotes && entry.evidence.extraQuotes.length > 0 && (
+              <details className="mt-2">
+                <summary className="cursor-pointer text-[11.5px] font-semibold text-accent hover:underline">
+                  {entry.evidence.extraLabel}
+                </summary>
+                <ul className="mt-2 flex flex-col gap-2">
+                  {entry.evidence.extraQuotes.map((quote) => (
+                    <li
+                      key={quote}
+                      className="text-[13px] leading-relaxed text-muted-foreground [text-wrap:pretty]"
+                    >
+                      {`“${quote}”`}
+                    </li>
+                  ))}
+                </ul>
+              </details>
+            )}
+          </figure>
+        )}
+
+        {/* No "see the full menu" button.
+            The entry already has three targets — the cover, the name, and every
+            dish row — and all of them lead into the venue. A fourth, sitting
+            under the rows as the heaviest element in the block, made the entry
+            read as a card with a call to action rather than as an item in an
+            article. The name is the way in. */}
+      </div>
+    </article>
+  );
+}
+
+// ─── Skeleton ───────────────────────────────────────────────────────────────
+
+/**
+ * The entry's own loading state, at the entry's footprint.
+ *
+ * The cover keeps its 3:2 on the phone and its 4:5 at 300px wide on desktop, so
+ * the article does not jump when the photographs land — the one reflow a long,
+ * scrolled page cannot afford. (This said "4:3 … 300×225" for a while after the
+ * cover changed underneath it, which is the failure mode a skeleton in the same
+ * file as its component is supposed to prevent.)
+ */
+export function TopRankingEntrySkeleton({ className }: { className?: string }) {
+  return (
+    <div
+      className={cn("flex flex-col gap-0 py-6 lg:flex-row lg:gap-7", className)}
+      aria-hidden
+    >
+      <Skeleton className="aspect-[3/2] w-full shrink-0 rounded-xl lg:aspect-[4/5] lg:w-[300px]" />
+      <div className="min-w-0 flex-1">
+        {/* Hidden on the phone: the real entry draws the rank, name, district
+            and grade INSIDE the photograph, so a placeholder row here would
+            promise a band that never arrives and reflow on hydration. */}
+        <div className="hidden items-start gap-3 lg:flex">
+          <Skeleton className="h-7 w-6" />
+          <div className="flex min-w-0 flex-1 flex-col gap-1.5">
+            <Skeleton className="h-5 w-[220px]" />
+            <Skeleton className="h-3 w-[100px]" />
+          </div>
+          <Skeleton className="h-8 w-[110px] rounded-lg" />
+        </div>
+        <div className="mt-4 flex flex-col gap-2 lg:mt-3">
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-[92%]" />
+          <Skeleton className="h-4 w-[64%]" />
+        </div>
+        <Skeleton className="mt-4 h-[62px] w-full rounded-lg" />
+      </div>
+    </div>
+  );
+}
+
+/** A run of entries — the ranking's loading state. */
+export function TopRankingListSkeleton({ rows = 6 }: { rows?: number }) {
+  return (
+    <div aria-hidden>
+      {Array.from({ length: rows }, (_, index) => (
+        <div key={index}>
+          {index > 0 && <Separator />}
+          <TopRankingEntrySkeleton />
+        </div>
+      ))}
+    </div>
+  );
+}

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

@@ -0,0 +1,76 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { ChefHat, Clock, LayoutList, MapPin } from "lucide-react";
+import { TopMethodNote, TopRankingHero } from "./top-ranking-hero";
+import { mockGradients } from "./menu-mocks";
+
+const meta: Meta<typeof TopRankingHero> = {
+  title: "Top/TopRankingHero",
+  component: TopRankingHero,
+  tags: ["autodocs"],
+  args: {
+    kicker: "RANKED · CUISINE",
+    title: "The best Italian restaurants in Cluj-Napoca",
+    lede: "Two hundred and forty-seven kitchens in the city cook Italian. These are the ones the reviews keep returning to — ranked on BearMenu grades, with the dish each is named for and what it costs today.",
+    updatedLabel: "Updated 6 September 2026",
+    metaLabel: "247 kitchens considered · 4,318 reviews read",
+    exits: [
+      { label: "Browse all 247 Italian kitchens", href: "/menu/cuisines/italian", icon: <LayoutList className="h-4 w-4" /> },
+      { label: "58 open now", href: "/menu/cuisines/italian?open=now", icon: <Clock className="h-4 w-4" /> },
+    ],
+    gradient: mockGradients.sweet,
+    icon: <ChefHat />,
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-[1000px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "It says **when** and **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, a method line — and those sit where a reader looks for them, not in fine print at the foot. The two exits into the browsing tool are stated rather than implied: the ranking is the editorial pick, the intent page is everything else.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TopRankingHero>;
+
+export const Cuisine: Story = {};
+
+/** A district takes cobblestone and a pin. Same component, different token. */
+export const District: Story = {
+  args: {
+    kicker: "RANKED · DISTRICT",
+    title: "The best restaurants in Centru, Cluj-Napoca",
+    lede: "Four hundred and eighty-one places eat and drink inside the old town. These are the ones the reviews rate highest — whatever they cook.",
+    metaLabel: "481 places considered · 9,204 reviews read",
+    icon: <MapPin />,
+    gradient: "linear-gradient(150deg, oklch(0.72 0.03 70), oklch(0.62 0.028 64))",
+  },
+};
+
+export const Mobile: Story = {
+  decorators: [
+    (Story) => (
+      <div className="w-[390px] bg-background p-3">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export const MethodNote: StoryObj<typeof TopMethodNote> = {
+  render: () => (
+    <TopMethodNote heading="How this is ranked.">
+      BearMenu grades, which weigh how many reviews a place has as well as how good they are, then
+      the review evidence for the dish each kitchen is named for. Prices are read from the venue's
+      current menu and dated. No sponsorship, no submissions.
+    </TopMethodNote>
+  ),
+};
+