@bearmenu/ui 0.8.9 → 0.8.10

package/src/components/top-cross-link.stories.tsx

@@ -0,0 +1,84 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { TopCrossLink } from "./top-cross-link";
+import { mockGradients } from "./menu-mocks";
+
+const meta: Meta<typeof TopCrossLink> = {
+  title: "Top/TopCrossLink",
+  component: TopCrossLink,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The link between the two answers to “where should I eat”. `row` is the way out of the ranking, full width under the list; `panel` is the way in, for the narrow column of a browse page. One component in both directions so the pair cannot drift — and never a sticky bar, because a sticky CTA on an article is an advert.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TopCrossLink>;
+
+/** Under the ranking: the editorial pick is done, the directory is over here. */
+export const Row: Story = {
+  args: {
+    title: "This is the editorial pick — the rest is browsable",
+    description:
+      "Two hundred and forty-seven Italian kitchens, filterable by open now, price, district and what they have on.",
+    cta: "Browse all 247",
+    href: "/menu/cuisines/italian",
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-[900px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+/**
+ * The long CTA that `h-11` used to clip. The categories registry hands this
+ * component whole headlines, which is the point — the reader lands on a page
+ * whose `h1` is the string they tapped.
+ */
+export const RowLongCta: Story = {
+  args: {
+    ...Row.args,
+    cta: "Vezi toate localurile cu shaorma din Cluj-Napoca",
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-[375px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+/** Beside a browse list, in a 380px column. */
+export const Panel: Story = {
+  args: {
+    variant: "panel",
+    kicker: "RANKED",
+    title: "299 kitchens. One answer.",
+    description:
+      "Every one graded and put in order, with the reviews that decided the ranking quoted. Updated September 2026.",
+    cta: "The best Romanian restaurants in Cluj-Napoca",
+    href: "/top/romanesc",
+    gradient: mockGradients.pasta,
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-[380px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+/** No ground — the panel still reads as a card. */
+export const PanelPlain: Story = {
+  args: { ...Panel.args, gradient: undefined },
+  decorators: Panel.decorators,
+};

package/src/components/top-cross-link.tsx

@@ -0,0 +1,171 @@
+import { ArrowRight, LayoutList, Trophy } from "lucide-react";
+import { cn } from "../lib/utils";
+import type { MenuLinkComponent, MenuLinkProps } from "./menu-types";
+
+/**
+ * TopCrossLink — the link between the ranking and the browsing tool.
+ *
+ * The product has two answers to "where should I eat", and they are different
+ * questions: the intent page answers *which venues, right now*, and `/top`
+ * answers *which are the best*. A reader who wants the other one should be told
+ * it exists rather than left to bounce, and told in the same object in both
+ * directions — so this is one component with two proportions, not two
+ * components that will drift.
+ *
+ * It was `TopExitRow`, which named only the outbound half. A menu page
+ * importing "exit row" to point INTO the ranking is a lie in the import list,
+ * and four projects read these names.
+ *
+ * ## `row` under a list, `panel` beside one
+ *
+ * `row` is the way out, full width under the ranking: icon, title, prose, and a
+ * button on the right at `lg`. `panel` is the way in, stacked for the ~380px
+ * column of a browse page, and it is the one that carries a ground — a card
+ * competing for attention with the list next to it needs to be a place, not a
+ * paragraph.
+ *
+ * ## Never a sticky bar
+ *
+ * Stated once, where the reader has finished reading. A sticky call to action
+ * on an article is an advert, and both of these pages exist to be read to the
+ * end.
+ */
+
+function DefaultLink({ href, ...props }: MenuLinkProps) {
+  return <a href={href} {...props} />;
+}
+
+export type TopCrossLinkProps = {
+  /**
+   * `row` (default) — the way OUT of the ranking, full width under the list.
+   * `panel` — the way IN, stacked, for a narrow column beside a browse list.
+   */
+  variant?: "row" | "panel";
+  /** e.g. "RANKED". `panel` only; drawn over the title with `icon` inline. */
+  kicker?: string;
+  title: string;
+  description: string;
+  /**
+   * The link's text. Prefer the destination's own headline over a generic
+   * "see more": the reader lands on a page whose `<h1>` is the string they
+   * tapped, and it is the anchor text the destination actually wants.
+   */
+  cta: string;
+  href: string;
+  /** Finished CSS gradient for the ground. `panel` only. */
+  gradient?: string;
+  /** Names the DESTINATION. Defaults to `LayoutList` on `row`, `Trophy` on `panel`. */
+  icon?: React.ReactNode;
+  /** The title's element. `b` by default on `row`, `h2` on `panel`. */
+  as?: "h2" | "h3" | "b";
+  linkComponent?: MenuLinkComponent;
+  className?: string;
+};
+
+/**
+ * `min-h-11`, never `h-11`.
+ *
+ * A fixed 44px box silently clips: the categories registry hands this component
+ * strings like "Vezi toate localurile cu shaorma din Cluj-Napoca" (48 characters
+ * against ~271px of inner width at 375px), which wraps to two lines and
+ * overflows a fixed height. The floor plus real padding is the same 44px target
+ * when the label is short and grows when it is not.
+ */
+const CTA = cn(
+  "rounded-xl bg-accent font-bold text-accent-foreground",
+  "transition-opacity duration-150 hover:opacity-90",
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+  "motion-reduce:transition-none"
+);
+
+export function TopCrossLink({
+  variant = "row",
+  kicker,
+  title,
+  description,
+  cta,
+  href,
+  gradient,
+  icon,
+  as,
+  linkComponent: LinkComponent = DefaultLink,
+  className,
+}: TopCrossLinkProps) {
+  const isPanel = variant === "panel";
+  const Heading = as ?? (isPanel ? "h2" : "b");
+  const glyph = icon ?? (isPanel ? <Trophy /> : <LayoutList />);
+
+  if (!isPanel) {
+    return (
+      <div
+        className={cn(
+          "flex flex-col gap-3 rounded-[18px] border border-border bg-card p-4",
+          "lg:flex-row lg:items-center lg:gap-5 lg:p-5",
+          className
+        )}
+      >
+        <span aria-hidden className="shrink-0 text-muted-foreground [&>svg]:h-5 [&>svg]:w-5">
+          {glyph}
+        </span>
+        <div className="min-w-0 flex-1">
+          <Heading className="block text-[15px] font-bold tracking-[-0.01em]">{title}</Heading>
+          <p className="mt-1 text-[13px] leading-relaxed text-muted-foreground">{description}</p>
+        </div>
+        <LinkComponent
+          href={href}
+          className={cn(
+            CTA,
+            "inline-flex min-h-11 shrink-0 items-center justify-center gap-2 px-5 py-2.5 text-sm"
+          )}
+        >
+          {cta}
+          <ArrowRight className="h-4 w-4 shrink-0" aria-hidden />
+        </LinkComponent>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={cn(
+        "relative overflow-hidden rounded-[18px] border border-border bg-card shadow-[var(--shadow-card)]",
+        className
+      )}
+    >
+      {/* An inset span rather than a background on the card, so the ground can
+          be a finished gradient string without fighting `bg-card` for the
+          shorthand — the same construction `TopRankingHero` uses. */}
+      {gradient && (
+        <span aria-hidden className="absolute inset-0" style={{ backgroundImage: gradient }} />
+      )}
+
+      <div className="relative z-[1] p-4 lg:p-5">
+        {kicker && (
+          <span className="flex items-center gap-1.5 text-[10.5px] font-extrabold uppercase tracking-[0.13em] text-muted-foreground">
+            <span aria-hidden className="[&>svg]:h-3 [&>svg]:w-3 [&>svg]:shrink-0">{glyph}</span>
+            {kicker}
+          </span>
+        )}
+
+        {/* Serif, and a tier under the page's own h1. The card is a window onto
+            the ranking, so it speaks in the destination's voice. */}
+        <Heading className="mt-2 block font-serif text-[20px] font-bold leading-[1.12] tracking-[-0.02em] text-foreground lg:text-[21px]">
+          {title}
+        </Heading>
+
+        <p className="mt-1.5 text-[13px] leading-relaxed text-muted-foreground">{description}</p>
+
+        <LinkComponent
+          href={href}
+          className={cn(
+            CTA,
+            "mt-4 flex min-h-11 w-full items-center justify-between gap-3 px-4 py-3 text-left text-[13.5px] leading-snug"
+          )}
+        >
+          <span>{cta}</span>
+          <ArrowRight className="h-4 w-4 shrink-0" aria-hidden />
+        </LinkComponent>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,171 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { TopRankingEntry } from "./top-ranking-entry";
+import type { TopRankEntry } from "./top-types";
+import type { MenuItemPreview } from "./menu-types";
+
+const labels = {
+  signature: "Signature",
+  openDish: (name: string) => `See ${name}`,
+  itemHref: (item: MenuItemPreview) =>
+    item.slug ? `/menu/${item.kind === "drink" ? "drinks" : "dishes"}/${item.slug}` : undefined,
+  item: {
+    currency: "RON",
+    mentions: (count: number) => `${count} mentions`,
+    signature: "SIGNATURE",
+    mentioned: "MENTIONED",
+  },
+};
+
+const entry: TopRankEntry = {
+  rank: 1,
+  slug: "salt-and-stone",
+  name: "Salt & Stone",
+  href: "/places/salt-and-stone",
+  district: "Centru",
+  gradeLabel: "9.4",
+  tierLabel: "Exceptional",
+  editorial:
+    "The tagliatelle is the reason to book a week ahead — the truffle is shaved at the table and the pasta is made that morning.",
+  menuGroupLabel: "Pasta",
+  menuItems: [
+    {
+      id: "m1",
+      slug: "truffle-tagliatelle",
+      name: "Truffle Tagliatelle",
+      kind: "dish" as const,
+      description: "Fresh pasta, black truffle, parmesan.",
+      mentions: 17,
+      sizes_and_prices: [{ size: 320, price: 62 }],
+    },
+    {
+      id: "m2",
+      slug: "classic-tiramisu",
+      name: "Classic Tiramisù",
+      kind: "dish" as const,
+      mentions: 9,
+      sizes_and_prices: [{ size: 180, price: 32 }],
+    },
+  ],
+  evidence: {
+    quote: "Best carbonara in the city and they will tell you off, politely, if you ask for cream.",
+    sourceLabel: "17 from reviews",
+  },
+};
+
+const meta: Meta<typeof TopRankingEntry> = {
+  title: "Top/TopRankingEntry",
+  component: TopRankingEntry,
+  tags: ["autodocs"],
+  args: {
+    entry,
+    labels,
+    formatPrice: (amount: number) => `${amount} RON`,
+    markGradient: "linear-gradient(150deg, oklch(0.56 0.15 38), oklch(0.46 0.14 34))",
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-[1000px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A numbered editorial entry, not a card. Cards imply a grid you filter and force every entry into the same height — wrong when one kitchen has a three-line quote and another has a sentence. **Evidence leads**: the cited review is the entry's first content, because a rank is a claim and the page has to show why before it asks you to accept the position. The entry goes to the venue; the signature dish opens the drawer.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TopRankingEntry>;
+
+export const Default: Story = {};
+
+/** No grade yet — the third-party star is the fallback, never a blank. */
+export const Ungraded: Story = {
+  args: {
+    entry: { ...entry, gradeLabel: undefined, tierLabel: undefined, rating: 4.6 },
+  },
+};
+
+/** A must-try with no live menu row: `MenuItem` renders it inert, not linked. */
+export const InertDish: Story = {
+  args: {
+    entry: {
+      ...entry,
+      menuItems: [{ ...entry.menuItems![0], slug: "", sizes_and_prices: undefined }],
+    },
+  },
+};
+
+/** No evidence, no editorial, no menu — the entry is still a legible rank. */
+export const Bare: Story = {
+  args: {
+    entry: { ...entry, editorial: undefined, evidence: undefined, menuItems: undefined },
+  },
+};
+
+/**
+ * On the phone the rank, name, district and grade sit INSIDE a 3:2 cover under
+ * a scrim, and the cover halves. It is one DOM copy placed in the same grid
+ * cell, not a `hidden`/`lg:hidden` twin — 25 duplicated headings and venue
+ * links is not something to ship on the page whose value is search.
+ */
+export const Mobile: Story = {
+  decorators: [
+    (Story) => (
+      <div className="w-[390px] bg-background p-3">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+/**
+ * The contrast worst case: a blown-out cover. The scrim's ramp is anchored in
+ * PIXELS to the block's `pt-12` runway, so the first glyph always lands at
+ * alpha 0.72 — 7.3:1 on the name against pure white — whatever the handset
+ * width or how the name wraps.
+ */
+export const MobileBrightCover: Story = {
+  ...Mobile,
+  args: {
+    entry: {
+      ...entry,
+      coverUrl:
+        "data:image/svg+xml;utf8," +
+        encodeURIComponent('<svg xmlns="http://www.w3.org/2000/svg" width="8" height="8"><rect width="8" height="8" fill="#ffffff"/></svg>'),
+    },
+  },
+};
+
+/** A name that wraps. It clamps at two lines and the row stays baseline-aligned. */
+export const MobileLongName: Story = {
+  ...Mobile,
+  args: {
+    entry: { ...entry, name: "PASQUALE | brunch & dinner, Piața Unirii" },
+  },
+};
+
+/**
+ * No photograph and no grade at once: the warm ground with the venue's initial
+ * — never a grey box — and the filled star fallback. The desktop keeps its
+ * diagonal stripes, which are a LIGHT surface and would put white type on a
+ * pale rectangle at this size.
+ */
+export const MobileNoPhotoNoGrade: Story = {
+  ...Mobile,
+  args: {
+    entry: {
+      ...entry,
+      coverUrl: undefined,
+      gradeLabel: undefined,
+      tierLabel: undefined,
+      rating: 4.6,
+    },
+  },
+};
+

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

@@ -0,0 +1,105 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { TopRankingEntry } from "./top-ranking-entry";
+import type { TopRankEntry } from "./top-types";
+
+const labels = {
+  signature: "Signature",
+  openDish: (name: string) => `See ${name}`,
+  itemHref: () => undefined,
+  item: {
+    currency: "RON",
+    mentions: (count: number) => `${count} mentions`,
+    signature: "SIGNATURE",
+    mentioned: "MENTIONED",
+  },
+};
+
+const entry: TopRankEntry = {
+  rank: 1,
+  slug: "pasquale",
+  name: "PASQUALE | brunch & dinner",
+  href: "/places/pasquale",
+  district: "Centru",
+  gradeLabel: "9.4",
+  tierLabel: "Exceptional",
+  coverUrl: "https://example.test/cover.jpg",
+  editorial: "Locals keep coming back.",
+};
+
+function renderEntry(override: Partial<TopRankEntry> = {}) {
+  return render(
+    <TopRankingEntry
+      entry={{ ...entry, ...override }}
+      labels={labels}
+      formatPrice={(amount) => `${amount} RON`}
+    />
+  );
+}
+
+/**
+ * The phone overlay puts white type over a photograph, so its legibility rests
+ * entirely on the scrim behind it. That scrim is a long arbitrary-value class
+ * passed through `cn()` — i.e. through `tailwind-merge`, which is allowed to
+ * DROP a class it believes a later one supersedes. If it ever does, nothing
+ * errors: the type just goes white-on-white, which is precisely how this
+ * shipped twice.
+ */
+describe("the phone overlay", () => {
+  it("keeps the scrim on the identity block after class merging", () => {
+    renderEntry();
+    const block = screen.getByRole("heading", { level: 3 }).closest("div")?.parentElement;
+    expect(block?.className).toContain("linear-gradient(180deg,oklch(0.16_0.012_55_/_0)");
+    // …and clears it again at desktop, where the block is on paper.
+    expect(block?.className).toContain("lg:bg-none");
+  });
+
+  it("places the identity block in the cover's grid cell", () => {
+    renderEntry();
+    const block = screen.getByRole("heading", { level: 3 }).closest("div")?.parentElement;
+    expect(block?.className).toContain("col-start-1");
+    expect(block?.className).toContain("row-start-1");
+    expect(block?.className).toContain("self-end");
+  });
+
+  /*
+   * A non-positioned box's background paints in an earlier phase than replaced
+   * inline content, so an unpositioned overlay puts its scrim UNDER the
+   * photograph — the scrim vanishes, the white type lands on bare image, and
+   * nothing anywhere reports an error.
+   */
+  it("positions the identity block so its scrim paints above the photograph", () => {
+    renderEntry();
+    const block = screen.getByRole("heading", { level: 3 }).closest("div")?.parentElement;
+    expect(block?.className).toContain("relative");
+    expect(block?.className).toContain("z-[1]");
+  });
+
+  /*
+   * Every mobile-only style here is written base-first and undone with `lg:`.
+   * `max-lg:` is unusable in this project — the consuming app's Tailwind emits
+   * no `max-width` media queries at all, so those classes are dropped silently
+   * and the style simply never exists.
+   */
+  it("uses no max-lg variants, which this project cannot compile", () => {
+    const { container } = renderEntry();
+    expect(container.innerHTML).not.toContain("max-lg:");
+  });
+
+  it("renders one heading and one venue link per entry, not a mobile twin", () => {
+    renderEntry();
+    expect(screen.getAllByRole("heading", { level: 3 })).toHaveLength(1);
+    expect(screen.getAllByRole("link", { name: entry.name })).toHaveLength(1);
+  });
+
+  it("keeps the band word beside the grade rather than hiding it", () => {
+    renderEntry();
+    expect(screen.getByText("Exceptional")).toBeInTheDocument();
+    expect(screen.getByText("9.4")).toBeInTheDocument();
+  });
+
+  it("falls back to the venue's initial when there is no photograph", () => {
+    renderEntry({ coverUrl: undefined });
+    expect(screen.getByText("P")).toBeInTheDocument();
+  });
+});