@bearmenu/ui 0.8.8 → 0.8.10

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

@@ -0,0 +1,91 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { MenuFamilyBlock } from "./menu-family-block";
+import { mockBareFamilyBlock, mockFamilyBlock, mockFormatters, mockGradients } from "./menu-mocks";
+
+const labels = {
+  venueUnit: (count: number) => `${count} kitchens`,
+  more: (count: number) => `+${count} more`,
+  priceBand: "kitchen price band",
+  browse: "Browse Italian",
+  kitchens: {
+    openVenue: (name: string) => `Open ${name}`,
+    openDish: (name: string) => `See ${name}`,
+    openNow: "Open now",
+  },
+};
+
+const meta: Meta<typeof MenuFamilyBlock> = {
+  title: "Menu/MenuFamilyBlock",
+  component: MenuFamilyBlock,
+  tags: ["autodocs"],
+  args: {
+    family: mockFamilyBlock,
+    labels,
+    formatCount: mockFormatters.number,
+    hue: "oklch(0.56 0.15 38)",
+    gradient: mockGradients.pasta,
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-[900px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The cuisines index's family card. **The mosaic is the ground**: the grid of venue photographs is the background for the entire card, and everything floats on it through three layers — the mosaic wearing the family's hue, a masked `backdrop-filter` that is absent where the photography is the subject and full where the rows begin, and an ink gradient that buys the contrast frost alone cannot. Phone: top to bottom. Desktop: the same layers turned ninety degrees, photo column clear on the left, rows frosted on the right, mosaic 3×2 rather than 2×2. The content region is `.dark`-scoped, which is how `MenuKitchenList` and `HueChip` render on the ink without a fork. Two costs accepted: a masked backdrop-filter repeated ten times down a scroll, and thumbnails that sit on a photograph and survive only because the ink is heavy under them.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof MenuFamilyBlock>;
+
+/** A stand-in photograph with enough variance that the frost has something to soften. */
+function photo(hue: number, label: string) {
+  return (
+    "data:image/svg+xml;utf8," +
+    encodeURIComponent(
+      `<svg xmlns="http://www.w3.org/2000/svg" width="480" height="320"><defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="hsl(${hue} 30% 62%)"/><stop offset="1" stop-color="hsl(${hue} 20% 28%)"/></linearGradient></defs><rect width="480" height="320" fill="url(#g)"/><circle cx="120" cy="90" r="60" fill="hsl(${hue} 40% 80%)" opacity=".6"/><rect x="260" y="180" width="180" height="110" fill="hsl(${hue} 15% 20%)" opacity=".7"/><text x="50%" y="88%" font-family="monospace" font-size="18" fill="#fff" text-anchor="middle">${label}</text></svg>`
+    )
+  );
+}
+
+const PHOTOS = [40, 200, 90, 300, 20, 150].map((h, i) => photo(h, `venue ${i + 1}`));
+
+export const Default: Story = {
+  args: { family: { ...mockFamilyBlock, photoUrls: PHOTOS } },
+};
+
+/**
+ * No photographs: the mosaic ground with the family's initial, never a grey box.
+ * A missing photograph is not a broken image, and a placeholder makes a real
+ * city look unfinished.
+ */
+export const NoPhotos: Story = {
+  args: { family: { ...mockFamilyBlock, photoUrls: [] } },
+};
+
+/** No photographs, no venue, no price — one kitchen in the whole city. */
+export const Bare: Story = {
+  args: {
+    family: mockBareFamilyBlock,
+    labels: { ...labels, browse: "Browse Portuguese" },
+  },
+};
+
+/** Frost and ink run top to bottom: clear photography under the name, the rows on the frosted foot. */
+export const Mobile: Story = {
+  args: { family: { ...mockFamilyBlock, photoUrls: PHOTOS } },
+  decorators: [
+    (Story) => (
+      <div className="w-[390px] bg-background p-3">
+        <Story />
+      </div>
+    ),
+  ],
+};

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

@@ -0,0 +1,314 @@
+import { Wallet } from "lucide-react";
+import { cn } from "../lib/utils";
+import { HueChip } from "./hue-chip";
+import { PHOTO_GROUND, PhotoGround } from "./photo-ground";
+import { Separator } from "./separator";
+import { Skeleton } from "./skeleton";
+import { MenuKitchenList, type MenuKitchenListLabels } from "./menu-kitchen-list";
+import type {
+  MenuFamilyBlockPreview,
+  MenuLinkComponent,
+  MenuLinkProps,
+} from "./menu-types";
+
+/**
+ * MenuFamilyBlock — the cuisines index's family card. The mosaic is the ground.
+ *
+ * ## Three layers, and everything floats on them
+ *
+ * The grid of venue photographs is the background for the ENTIRE card, edge to
+ * edge, and the facts sit on it. Three layers do the work:
+ *
+ *  1. **The mosaic**, full-bleed, wearing the family's hue through a
+ *     `mix-blend-color` layer.
+ *  2. **A masked backdrop-filter** — absent where the photography is the
+ *     subject, full where the rows begin — so the pictures stay sharp where
+ *     they are looked at and go soft exactly where they are read over.
+ *  3. **An ink gradient** over that. This is what actually buys the contrast:
+ *     frost alone blurs without darkening, and blurred mid-tones will not carry
+ *     16px type.
+ *
+ * On the phone the frost and ink run top to bottom: the name and the action
+ * sit on clear photography, the chips and the rows on the frosted foot. On
+ * desktop the same three layers turn ninety degrees — the photo column on the
+ * left stays clear, the row column on the right is the frosted one. The mosaic
+ * runs 3×2 there rather than 2×2, because at 1110px a four-tile grid makes each
+ * photograph too big to read as texture.
+ *
+ * ## The dark scope
+ *
+ * The card's content region carries the `dark` class, so every token inside —
+ * `text-foreground`, `bg-muted`, `border-border` — resolves to its dark-theme
+ * value. That is how `MenuKitchenList` and `HueChip` render correctly on the
+ * ink without a fork or a "tone" prop: the mechanism the app already uses to
+ * mark a region as dark. It also means the card looks the same in both themes,
+ * which is right — it is built on photography, and photography is not themed.
+ *
+ * ## The two costs, stated
+ *
+ * A `backdrop-filter` over a mask is expensive to composite, and this card is
+ * repeated ten times down a scroll. And the thumbnails now sit on a
+ * photograph; they survive only because the ink is heavy under them, and on a
+ * busy interior shot they will fight. Both were accepted with the design.
+ *
+ * ## No "most named" item, no venue count badge
+ *
+ * The family-level "most named" was the first venue's signature relabelled —
+ * Italian, Pizza and Mediterranean all claimed "Turkish Poached Eggs" — and
+ * the count used to print three times with two values. One count, under the
+ * name; the overflow tile says only how many photographs it stands for.
+ */
+
+/** @deprecated Alias of `MenuLinkProps`; kept for symmetry with the other menu surfaces. */
+export type MenuFamilyBlockLinkProps = MenuLinkProps;
+
+function DefaultLink({ href, ...props }: MenuFamilyBlockLinkProps) {
+  return <a href={href} {...props} />;
+}
+
+export type MenuFamilyBlockLabels = {
+  /** Unit under the family name, e.g. "247 kitchens". Pluralised by the caller. */
+  venueUnit: (count: number) => string;
+  /** The overflow pill over the mosaic, e.g. "+311 more". */
+  more: (count: number) => string;
+  /**
+   * Price-band caption, e.g. "kitchen price band".
+   *
+   * Never drawn: the band reads as a wallet and a range, and a caption on a
+   * pill that short is longer than the fact. It names the pill for a screen
+   * reader, which would otherwise be read two numbers and a currency.
+   */
+  priceBand: string;
+  /** Main action, e.g. "Browse Italian". Sits on the photography — keep it short. */
+  browse: string;
+  /** Passed through to the venue rows. */
+  kitchens: MenuKitchenListLabels;
+};
+
+export type MenuFamilyBlockProps = {
+  family: MenuFamilyBlockPreview;
+  labels: MenuFamilyBlockLabels;
+  formatCount?: (value: number) => string;
+  /** Finished CSS colour for the chips. */
+  hue?: string;
+  /** Finished CSS gradient — the family's colour over the mosaic. */
+  gradient?: string;
+  linkComponent?: MenuLinkComponent;
+  className?: string;
+};
+
+/** 2×2 on the phone, 3×2 from `lg`. Tiles past the fourth are desktop-only. */
+const MOSAIC_TILES = 6;
+const PHONE_TILES = 4;
+
+/** The card's ground is `PhotoGround`'s, so the two cannot differ. */
+const GROUND = PHOTO_GROUND;
+
+/**
+ * The frost: absent at the top, full at the foot on the phone; absent on the
+ * left, full on the right from `lg`. The mask is what makes it a gradient of
+ * softness rather than a frosted pane — the subject stays sharp.
+ */
+const FROST =
+  "backdrop-blur-xl [mask-image:linear-gradient(to_bottom,transparent_0%,black_42%)] lg:[mask-image:linear-gradient(to_right,transparent_36%,black_54%)]";
+
+/**
+ * The ink. Same direction as the frost, heavier at the foot, and it is the
+ * layer the contrast rests on. Literal rather than `var(--scrim)`: that token
+ * lives in the app's stylesheet, not this package's, so a DS component reading
+ * it renders nothing in Storybook and the other three consumers.
+ */
+const INK =
+  "bg-[linear-gradient(to_bottom,oklch(0.16_0.012_55_/_0.42)_0%,oklch(0.16_0.012_55_/_0.6)_30%,oklch(0.16_0.012_55_/_0.9)_48%,oklch(0.16_0.012_55_/_0.96)_100%)] lg:bg-[linear-gradient(to_right,oklch(0.16_0.012_55_/_0.38)_0%,oklch(0.16_0.012_55_/_0.6)_30%,oklch(0.16_0.012_55_/_0.92)_46%,oklch(0.16_0.012_55_/_0.96)_100%)]";
+
+/**
+ * A second, LOCAL scrim under the name, count and action — the photo column's
+ * own, rising from its foot.
+ *
+ * The global ink is deliberately light where the photography is the subject,
+ * and on a bright, warm-tinted picture (a bakery counter under the Romanian
+ * red) 30px of white serif sat at about 2.5:1 on it. Darkening the whole ink
+ * would have dulled every photograph to fix a corner of some; this darkens
+ * only the band the type actually occupies, and leaves the top of the picture
+ * clear. Same base colour as the ink, so the two read as one shadow.
+ */
+const TEXT_SCRIM =
+  /* `isolate` + `before:-z-10`: a positioned pseudo-element paints ABOVE the
+     column's in-flow text unless the column is its own stacking context and
+     the layer is ordered beneath. Without `isolate`, `-z-10` would instead
+     drop it behind the card's mosaic — inside the article's context. */
+  "isolate before:pointer-events-none before:absolute before:inset-x-0 before:bottom-0 before:top-[30%] before:-z-10 before:bg-[linear-gradient(to_bottom,oklch(0.16_0.012_55_/_0)_0%,oklch(0.16_0.012_55_/_0.55)_45%,oklch(0.16_0.012_55_/_0.8)_100%)] before:content-['']";
+
+export function MenuFamilyBlock({
+  family,
+  labels,
+  formatCount = String,
+  hue,
+  gradient,
+  linkComponent: LinkComponent = DefaultLink,
+  className,
+}: MenuFamilyBlockProps) {
+  const photos = (family.photoUrls ?? []).slice(0, MOSAIC_TILES);
+  const overflow = Math.max(family.venueCount - photos.length, 0);
+  const initial = (family.name.match(/\p{L}/u)?.[0] ?? "").toLocaleUpperCase();
+  const venues = family.venues ?? [];
+
+  return (
+    <article
+      className={cn(
+        /* `isolate` confines the blend and the backdrop-filter to this card.
+           `dark` scopes every token inside to its dark-theme value. */
+        "dark relative isolate overflow-hidden rounded-[14px] text-foreground",
+        GROUND,
+        className
+      )}
+    >
+      {/* ── Layer 1: the photographs, wearing the family's colour ──────── */}
+      {/* A 2×2 on the phone, 3×2 from `lg`: at 1110px a four-tile grid makes
+          each photograph too big to read as texture. With no photographs at
+          all, one slot with the family's initial. */}
+      <PhotoGround
+        photos={photos.length > 0 ? photos : [undefined]}
+        initials={initial}
+        mosaicClassName={
+          photos.length > 0 ? "grid-cols-2 grid-rows-2 lg:grid-cols-3" : "grid-cols-1"
+        }
+        phoneTiles={PHONE_TILES}
+        gradient={gradient}
+      />
+
+      {/* ── Layer 2: the frost ──────────────────────────────────────────── */}
+      <span aria-hidden className={cn("absolute inset-0", FROST)} />
+
+      {/* ── Layer 3: the ink ────────────────────────────────────────────── */}
+      <span aria-hidden className={cn("absolute inset-0", INK)} />
+
+      {/* ── The content, floating ───────────────────────────────────────── */}
+      <div className="relative grid grid-cols-1 lg:grid-cols-[38%_1fr]">
+        {/* The photo column. On the phone it is the card's head; on desktop
+            the left third, with its stack anchored to the foot. */}
+        <div className={cn("relative flex flex-col p-3.5 lg:min-h-[320px] lg:justify-end lg:p-5", TEXT_SCRIM)}>
+          {overflow > 0 && (
+            <span className="mb-16 self-end rounded-full bg-[oklch(0.16_0.012_55_/_0.72)] px-2.5 py-1 text-[11px] font-semibold text-white backdrop-blur-[2px] lg:mb-3 lg:self-start">
+              {labels.more(overflow)}
+            </span>
+          )}
+
+          <h3 className="text-balance font-serif text-[26px] font-semibold leading-tight tracking-[-0.02em] text-white lg:text-[30px]">
+            {family.name}
+          </h3>
+          <span className="mt-0.5 block text-[13px] font-medium tabular-nums text-white/70">
+            {labels.venueUnit(family.venueCount)}
+          </span>
+
+          {/* The action, as a frosted pill on the photography. `bg-white/12`
+              on the ink rather than `bg-accent`: ten filled accent buttons on
+              one page is ten primary actions, and the pill reads as part of the
+              picture rather than as a control laid on top of it.
+
+              No glyph. An arrow read as "leaves the site" beside a label that
+              already says where it goes, and a chevron would have made the pill
+              one more row: every venue row to its right ends in exactly that
+              chevron. The shape and the label are the whole affordance. */}
+          <LinkComponent
+            href={family.href}
+            className="mt-3.5 inline-flex h-10 w-max items-center rounded-full border border-white/20 bg-white/[0.12] px-4 text-[13.5px] font-bold text-white backdrop-blur-md transition-colors hover:bg-white/20 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white motion-reduce:transition-none"
+          >
+            {labels.browse}
+          </LinkComponent>
+        </div>
+
+        {/* The frosted column: chips, then the rows. */}
+        <div className="flex min-w-0 flex-col px-3.5 pb-3.5 lg:p-5">
+          <ul className="flex flex-wrap items-center gap-1.5">
+            {family.priceBandLabel && (
+              /* No hue: a fact about money, not about the family. In the dark
+                 scope `HueChip`'s `--muted` fallback is the dark pill the design
+                 draws. */
+              <HueChip
+                as="li"
+                className="font-bold tabular-nums"
+                aria-label={`${labels.priceBand}: ${family.priceBandLabel}`}
+                icon={<Wallet className="h-3.5 w-3.5 shrink-0 text-muted-foreground" aria-hidden />}
+              >
+                {family.priceBandLabel}
+              </HueChip>
+            )}
+            {family.chips?.map((chip) => (
+              /* Label only. The counts are VENUES beside a dish group's name,
+                 which every reader takes for dishes. */
+              <HueChip key={chip.slug} as="li" hue={hue}>
+                {chip.label}
+              </HueChip>
+            ))}
+          </ul>
+
+          {venues.length > 0 && (
+            <>
+              <Separator className="my-3" />
+              <MenuKitchenList
+                kitchens={venues}
+                labels={labels.kitchens}
+                linkComponent={LinkComponent}
+              />
+            </>
+          )}
+        </div>
+      </div>
+    </article>
+  );
+}
+
+// ─── Skeleton ───────────────────────────────────────────────────────────────
+
+/**
+ * The block's own loading state, at the block's footprint.
+ *
+ * The ground is the card's own, so the placeholder is already the dark
+ * surface the photographs will land on — nothing flashes from paper to ink.
+ * `venues` matches the rows the caller will render, so a block showing three
+ * does not settle from a placeholder showing one.
+ */
+export function MenuFamilyBlockSkeleton({
+  venues = 3,
+  className,
+}: {
+  venues?: number;
+  className?: string;
+}) {
+  return (
+    <div
+      className={cn("dark relative overflow-hidden rounded-[14px]", GROUND, className)}
+      aria-hidden
+    >
+      <div className="grid grid-cols-1 lg:grid-cols-[38%_1fr]">
+        <div className="flex flex-col p-3.5 lg:min-h-[320px] lg:justify-end lg:p-5">
+          <Skeleton className="mb-16 h-6 w-[72px] self-end rounded-full lg:mb-3 lg:self-start" />
+          <Skeleton className="h-7 w-[60%]" />
+          <Skeleton className="mt-2 h-3.5 w-[90px]" />
+          <Skeleton className="mt-3.5 h-10 w-[160px] rounded-full" />
+        </div>
+        <div className="flex min-w-0 flex-col px-3.5 pb-3.5 lg:p-5">
+          <div className="flex gap-1.5">
+            <Skeleton className="h-7 w-[86px] rounded-full" />
+            <Skeleton className="h-7 w-[74px] rounded-full" />
+            <Skeleton className="h-7 w-[66px] rounded-full" />
+          </div>
+          <Separator className="my-3" />
+          {Array.from({ length: venues }, (_, index) => (
+            <div key={index}>
+              {index > 0 && <Separator />}
+              <div className="flex items-center gap-3 py-2.5">
+                <Skeleton className="h-[46px] w-[46px] rounded-[11px]" />
+                <div className="flex min-w-0 flex-1 flex-col gap-1.5">
+                  <Skeleton className="h-3.5 w-[46%]" />
+                  <Skeleton className="h-3 w-[58%]" />
+                </div>
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,120 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { MenuFamilyCard } from "./menu-family-card";
+import { mockDrinkFamily, mockFamily, mockGradients } from "./menu-mocks";
+
+const labels = {
+  venueUnit: "kitchens",
+  priceBand: "kitchen price band",
+  browse: "Browse Italian",
+};
+
+/** A stand-in photograph with enough variance that the frost has something to soften. */
+function photo(hue: number, label: string) {
+  return (
+    "data:image/svg+xml;utf8," +
+    encodeURIComponent(
+      `<svg xmlns="http://www.w3.org/2000/svg" width="320" height="240"><defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="hsl(${hue} 30% 62%)"/><stop offset="1" stop-color="hsl(${hue} 20% 28%)"/></linearGradient></defs><rect width="320" height="240" fill="url(#g)"/><circle cx="80" cy="70" r="44" fill="hsl(${hue} 40% 80%)" opacity=".6"/><rect x="170" y="130" width="120" height="80" fill="hsl(${hue} 15% 20%)" opacity=".7"/><text x="50%" y="88%" font-family="monospace" font-size="16" fill="#fff" text-anchor="middle">${label}</text></svg>`
+    )
+  );
+}
+
+const PHOTOS = [40, 200, 90, 300].map((h, i) => photo(h, `venue ${i + 1}`));
+
+const meta: Meta<typeof MenuFamilyCard> = {
+  title: "Menu/MenuFamilyCard",
+  component: MenuFamilyCard,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="w-[360px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The hub's doorway to a family — a cuisine on the dishes tab, a drink family on the drinks tab. The same photo language as `MenuFamilyBlock` (the mosaic is the ground, wearing the family's hue; a masked frost and an ink gradient carry the type) drawn one step earlier, in a row of three, where the reader is choosing a family and not yet a venue: one number, one name, the groups the family consists of, and the `Browse` pill. It lists no venue. The count is VENUES: cuisine exists only on places, so a card counting dishes cannot be built. The whole card is one link.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof MenuFamilyCard>;
+
+export const Default: Story = {
+  args: {
+    family: { ...mockFamily, venue_photo_urls: PHOTOS },
+    labels,
+    href: "/menu/cuisines/italian",
+    hue: "oklch(0.55 0.15 40)",
+    gradient: mockGradients.pasta,
+    priceBandLabel: "32–84 lei",
+  },
+};
+
+/** The drinks tab. Same card, different unit and vocabulary. */
+export const DrinkFamily: Story = {
+  args: {
+    family: { ...mockDrinkFamily, venue_photo_urls: PHOTOS },
+    labels: { venueUnit: "bars", priceBand: "bar price band", browse: "Browse cocktails" },
+    href: "/menu/drinks/cocktail",
+    hue: "oklch(0.5 0.13 240)",
+    gradient: mockGradients.cocktail,
+    priceBandLabel: "18–54 lei",
+  },
+};
+
+/** A one-venue cuisine: the count is honest, and the mosaic repeats one photo. */
+export const Sparse: Story = {
+  args: {
+    family: {
+      slug: "portuguese",
+      name: "Portuguese",
+      venue_count: 1,
+      chips: [{ slug: "seafood-dish", label: "seafood" }],
+      venue_photo_urls: PHOTOS.slice(0, 1),
+    },
+    labels: { ...labels, browse: "Browse Portuguese" },
+    href: "/menu/cuisines/portuguese",
+    hue: "oklch(0.52 0.13 340)",
+    gradient: mockGradients.sweet,
+    priceBandLabel: "42–88 lei",
+  },
+};
+
+/** No photography at all: the ground with the family's initial, and no tint. */
+export const NoPhotos: Story = {
+  args: {
+    ...Default.args,
+    family: { ...mockFamily, venue_photo_urls: [] },
+  },
+};
+
+/** The row of three the card is designed to be scanned in. */
+export const Row: Story = {
+  render: () => (
+    <div className="grid grid-cols-3 gap-5">
+      {[mockFamily, mockDrinkFamily, mockFamily].map((family, index) => (
+        <MenuFamilyCard
+          key={index}
+          family={{ ...family, venue_photo_urls: PHOTOS }}
+          labels={labels}
+          href={`/menu/cuisines/${family.slug}`}
+          hue="oklch(0.55 0.15 40)"
+          gradient={Object.values(mockGradients)[index]}
+          priceBandLabel="32–84 lei"
+        />
+      ))}
+    </div>
+  ),
+  decorators: [
+    (Story) => (
+      <div className="w-[1100px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+};