@bearmenu/ui 0.8.8 → 0.8.10

package/src/components/explainer-steps.stories.tsx

@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { ExplainerSteps } from "./explainer-steps";
+
+const meta: Meta<typeof ExplainerSteps> = {
+  title: "Menu/ExplainerSteps",
+  component: ExplainerSteps,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="w-[360px] bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    steps: [
+      { text: "We read 32 spellings of papanași and matched them to one dish.", figure: "32", unit: "names" },
+      { text: "Prices compare like for like: every one is a portion of the same dish.", figure: "8–44", unit: "lei" },
+      { text: "Open any dish and see what every other kitchen charges for it.", figure: "45", unit: "kitchens" },
+    ],
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "How something works, as numbered rules: a numeral in a ring, one line, and the live figure that proves it with its unit. A thread joins the numerals; the last is filled, because the rules end where the reader is asked to act. A step without a figure shows none.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ExplainerSteps>;
+
+export const Default: Story = {};
+
+/** The third rule has no number, so it shows none. */
+export const UnevenFigures: Story = {
+  args: {
+    steps: [
+      { text: "The reviews of every place in Cluj-Napoca, read in full.", figure: "791", unit: "places" },
+      { text: "A mention is one review naming the item.", figure: "68", unit: "here" },
+      { text: "The most-named lists are ranked on it, so the top is what the city keeps talking about." },
+    ],
+  },
+};

package/src/components/explainer-steps.tsx

@@ -0,0 +1,74 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * ExplainerSteps — how something works, as numbered rules a reader can scan.
+ *
+ * Each step is a numeral in a ring, one line of prose, and the live figure
+ * that proves the line, right-aligned with its unit. A thread runs from one
+ * numeral to the next so the three read as a sequence, and the last numeral
+ * is filled: the rules end where the reader is asked to do something.
+ *
+ * A step without a figure shows none — an invented number in the column is
+ * worse than an empty one. But a list where no step has a figure should be
+ * prose, not steps.
+ *
+ * Server-safe. Data in, not children: a server component composes these from
+ * translated strings and numbers, and an array is easier to number than a
+ * child list is to clone.
+ */
+
+export type ExplainerStepItem = {
+  /** One line. Two at most on a phone; a third is a paragraph and belongs elsewhere. */
+  text: ReactNode;
+  /** The live figure, pre-formatted. */
+  figure?: string;
+  /** A unit or caption beside the figure, e.g. "names". */
+  unit?: string;
+};
+
+export type ExplainerStepsProps = {
+  steps: ExplainerStepItem[];
+  className?: string;
+};
+
+export function ExplainerSteps({ steps, className }: ExplainerStepsProps) {
+  return (
+    <ol className={cn("flex flex-col", className)}>
+      {steps.map((step, index) => {
+        const isLast = index === steps.length - 1;
+        return (
+          <li key={index} className="relative flex gap-3.5 pb-5 last:pb-0">
+            {/* The thread, from this numeral to the next. */}
+            {!isLast && (
+              <span
+                aria-hidden
+                className="absolute bottom-0 left-[11px] top-7 w-px bg-border"
+              />
+            )}
+            <span
+              aria-hidden
+              className={cn(
+                "relative flex h-6 w-6 shrink-0 items-center justify-center rounded-full text-[11px] font-bold tabular-nums",
+                isLast
+                  ? "bg-primary text-primary-foreground"
+                  : "border border-border bg-background text-muted-foreground"
+              )}
+            >
+              {index + 1}
+            </span>
+            <p className="min-w-0 flex-1 pt-0.5 text-[14px] leading-[1.45] text-foreground">{step.text}</p>
+            {step.figure && (
+              <span className="shrink-0 pt-0.5 text-right text-[15px] font-bold leading-[1.45] tabular-nums text-foreground">
+                {step.figure}
+                {step.unit && (
+                  <span className="ml-1 text-[11px] font-normal text-muted-foreground">{step.unit}</span>
+                )}
+              </span>
+            )}
+          </li>
+        );
+      })}
+    </ol>
+  );
+}

package/src/components/glass-ground.tsx

@@ -0,0 +1,129 @@
+import type { CSSProperties } from "react";
+import { cn } from "../lib/utils";
+
+/**
+ * GlassGround — a frosted, inked caption rising out of one edge of a
+ * photograph.
+ *
+ * Layers over a `PhotoGround`: two masked `backdrop-blur`s (the frost) and
+ * an ink gradient (the contrast), running in one direction — absent where the
+ * photograph is the subject, solid where the type is. `MenuFamilyBlock` drew
+ * this first; this is the same idea with the stops as data, so a card can say
+ * "clear for 128px, then glass" without a sixth copy of the gradient strings.
+ *
+ * ## Why two blurs, and why the ramps are eased
+ *
+ * One blur under a linear mask has an edge: the eye reads the line where
+ * sharp becomes soft, however gently the mask fades it in. Two blurs — a
+ * light one that starts early and a heavier one that starts late — make the
+ * softening itself a gradient (the "progressive blur" of a phone's lock
+ * screen), and every ramp here is an ease-in through five stops rather than
+ * a straight line, because a straight ramp has a visible crease at each end
+ * where its slope changes.
+ *
+ * ## Why the stops are custom properties
+ *
+ * Tailwind emits only the classes it can read verbatim, so the gradients
+ * cannot be assembled from props into a class. The classes below are literal
+ * and read `--glass-*` variables; the component writes those inline, having
+ * interpolated the quarter stops in JS (`clear` and `full` must share a
+ * unit). Same mechanism as `HueChip`'s hue. The ink's colour is the
+ * package's one scrim literal, `oklch(0.16 0.012 55)`, never `var(--scrim)`.
+ *
+ * ## The ramp ends where the type begins
+ *
+ * `clear` is where the frost starts, `full` where it and the ink are solid.
+ * Set `full` to the exact seam the content starts at — a ramp that runs past
+ * the seam puts the first row of type on half-frost.
+ */
+
+export type GlassStops = {
+  /** Which way the ink runs — toward the type. */
+  direction: "to bottom" | "to right";
+  /** Where the frost begins, e.g. `"0px"` or `"24%"`. */
+  clear: string;
+  /** Where frost and ink are solid — the seam the content starts at. Same unit as `clear`. */
+  full: string;
+};
+
+export type GlassGroundProps = {
+  stops: GlassStops;
+  /** Stops from `lg`. Omit to keep the same ramp at every width. */
+  lgStops?: GlassStops;
+  /**
+   * How dark the ink gets at the far edge, 0–1. `0.96` is a caption the
+   * photograph is only a texture under; `0.4` is a photograph the caption is
+   * drawn on — the type is lifted, the room stays a room.
+   */
+  peak?: number;
+  /**
+   * How much the frost softens the photograph where it is solid. `xl` turns
+   * a room into colour; `sm` keeps it a room and only takes the edge off the
+   * detail behind the type.
+   */
+  blur?: "sm" | "md" | "lg" | "xl";
+  className?: string;
+};
+
+/* Ease-in through the ramp: the fraction of the way from `clear` to `full`
+   at which each stop sits, and the share of the peak it carries. */
+const STOPS = [0, 0.25, 0.5, 0.75, 1] as const;
+const EASE = [0, 0.06, 0.25, 0.56, 1] as const;
+
+/** The light blur starts at once and is solid halfway; the heavy one starts halfway. */
+const FROST_SOFT =
+  "[mask-image:linear-gradient(var(--glass-dir),transparent_var(--glass-s0),rgba(0,0,0,0.25)_var(--glass-s1),black_var(--glass-s2))] lg:[mask-image:linear-gradient(var(--glass-lg-dir),transparent_var(--glass-lg-s0),rgba(0,0,0,0.25)_var(--glass-lg-s1),black_var(--glass-lg-s2))]";
+const FROST_HEAVY =
+  "[mask-image:linear-gradient(var(--glass-dir),transparent_var(--glass-s1),rgba(0,0,0,0.25)_var(--glass-s2),rgba(0,0,0,0.6)_var(--glass-s3),black_var(--glass-s4))] lg:[mask-image:linear-gradient(var(--glass-lg-dir),transparent_var(--glass-lg-s1),rgba(0,0,0,0.25)_var(--glass-lg-s2),rgba(0,0,0,0.6)_var(--glass-lg-s3),black_var(--glass-lg-s4))]";
+
+const INK =
+  "bg-[linear-gradient(var(--glass-dir),oklch(0.16_0.012_55_/_0)_var(--glass-s0),oklch(0.16_0.012_55_/_var(--glass-a1))_var(--glass-s1),oklch(0.16_0.012_55_/_var(--glass-a2))_var(--glass-s2),oklch(0.16_0.012_55_/_var(--glass-a3))_var(--glass-s3),oklch(0.16_0.012_55_/_var(--glass-a4))_var(--glass-s4),oklch(0.16_0.012_55_/_var(--glass-a-peak))_100%)] lg:bg-[linear-gradient(var(--glass-lg-dir),oklch(0.16_0.012_55_/_0)_var(--glass-lg-s0),oklch(0.16_0.012_55_/_var(--glass-a1))_var(--glass-lg-s1),oklch(0.16_0.012_55_/_var(--glass-a2))_var(--glass-lg-s2),oklch(0.16_0.012_55_/_var(--glass-a3))_var(--glass-lg-s3),oklch(0.16_0.012_55_/_var(--glass-a4))_var(--glass-lg-s4),oklch(0.16_0.012_55_/_var(--glass-a-peak))_100%)]";
+
+/** Literal, for the scanner: the light and the heavy blur per strength. */
+const BLUR = {
+  sm: ["backdrop-blur-[2px]", "backdrop-blur-sm"],
+  md: ["backdrop-blur-sm", "backdrop-blur-md"],
+  lg: ["backdrop-blur-md", "backdrop-blur-lg"],
+  xl: ["backdrop-blur-lg", "backdrop-blur-xl"],
+} as const;
+
+/** "72px" → [72, "px"]; "24%" → [24, "%"]. */
+function measure(value: string): [number, string] {
+  const match = value.trim().match(/^(-?\d*\.?\d+)\s*([a-z%]*)$/i);
+  if (!match) throw new Error(`GlassGround: cannot read stop "${value}"`);
+  return [Number(match[1]), match[2] || "px"];
+}
+
+/** The five ramp positions between `clear` and `full`, as CSS lengths. */
+function positions(clear: string, full: string): string[] {
+  const [from, unit] = measure(clear);
+  const [to] = measure(full);
+  return STOPS.map((fraction) => `${from + (to - from) * fraction}${unit}`);
+}
+
+export function GlassGround({
+  stops,
+  lgStops = stops,
+  peak = 0.96,
+  blur = "xl",
+  className,
+}: GlassGroundProps) {
+  const base = positions(stops.clear, stops.full);
+  const lg = positions(lgStops.clear, lgStops.full);
+  const style = {
+    "--glass-dir": stops.direction,
+    "--glass-lg-dir": lgStops.direction,
+    ...Object.fromEntries(base.map((position, index) => [`--glass-s${index}`, position])),
+    ...Object.fromEntries(lg.map((position, index) => [`--glass-lg-s${index}`, position])),
+    ...Object.fromEntries(EASE.slice(1).map((share, index) => [`--glass-a${index + 1}`, String(peak * 0.8 * share)])),
+    "--glass-a-peak": String(peak),
+  } as CSSProperties;
+
+  return (
+    <span aria-hidden className={cn("pointer-events-none absolute inset-0 block", className)} style={style}>
+      <span className={cn("absolute inset-0", BLUR[blur][0], FROST_SOFT)} />
+      <span className={cn("absolute inset-0", BLUR[blur][1], FROST_HEAVY)} />
+      <span className={cn("absolute inset-0", INK)} />
+    </span>
+  );
+}

package/src/components/hub-surface.stories.tsx

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { HubSurface } from "./hub-surface";
+import { SectionHeader } from "./section-header";
+
+const meta: Meta<typeof HubSurface> = {
+  title: "Menu/HubSurface",
+  component: HubSurface,
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div className="w-[390px] bg-[var(--surface-2,oklch(0.97_0.004_60))] p-3">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The surface a hub section sits on below `lg`. On a phone a hub is an app screen, not a page: each section is a white card on the tinted ground, 18px radius, one shadow, no border. From `lg` up the card dissolves entirely and sections sit flat the way the desktop design draws them — one element, two looks, identical markup inside. Hairlines live inside a card, never across the page.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof HubSurface>;
+
+export const Default: Story = {
+  render: () => (
+    <HubSurface>
+      <SectionHeader title="Open right now" />
+      <p className="text-sm text-muted-foreground">
+        Section content, inset by the surface.
+      </p>
+    </HubSurface>
+  ),
+};
+
+/** `flush` drops the inset so a rail or a photograph can bleed to the edge. */
+export const Flush: Story = {
+  render: () => (
+    <HubSurface flush>
+      <div className="px-3.5 pt-4">
+        <SectionHeader title="Browse by cuisine" />
+      </div>
+      <div className="flex gap-3 overflow-x-auto px-3.5 pb-4">
+        {[0, 1, 2].map((card) => (
+          <div key={card} className="h-24 w-40 shrink-0 rounded-xl bg-muted" />
+        ))}
+      </div>
+    </HubSurface>
+  ),
+};
+
+/** Stacked, at the 12px rhythm the hub uses between sections. */
+export const Stacked: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      {["Open right now", "One kitchen worth knowing", "Most named"].map((title) => (
+        <HubSurface key={title}>
+          <SectionHeader title={title} />
+          <div className="h-12 rounded-lg bg-muted" />
+        </HubSurface>
+      ))}
+    </div>
+  ),
+};

package/src/components/hub-surface.tsx

@@ -0,0 +1,50 @@
+import { cn } from "../lib/utils";
+
+/**
+ * HubSurface — the surface a hub section sits on BELOW `lg`.
+ *
+ * On a phone a hub is an app screen, not a page: each section is a white card
+ * on the tinted ground, 18px radius, one card shadow and no border, with 14px
+ * of inset. Hairlines live inside a card, never across the page. From `lg` up
+ * the card dissolves — no fill, no radius, no inset — and the sections sit flat
+ * the way the desktop design draws them. One element, two looks; the section
+ * markup inside is identical at every width.
+ *
+ * `flush` drops the inset so a section whose content bleeds to the card edge —
+ * a snap rail, a full-width photograph — can pad its own header and let the
+ * rest run.
+ *
+ * Generalised out of the events hub's `EventsHubCard`, which had the same job
+ * and lived in the app. Nothing here is menu- or event-shaped.
+ */
+
+export type HubSurfaceProps = {
+  flush?: boolean;
+  className?: string;
+  children: React.ReactNode;
+};
+
+export function HubSurface({ flush, className, children }: HubSurfaceProps) {
+  return (
+    <section
+      className={cn(
+        "rounded-[18px] border border-border bg-card shadow-none",
+        flush ? "overflow-hidden" : "px-3.5 py-4",
+        /*
+         * `lg:border-0` is load-bearing and was missing.
+         *
+         * Above `lg` this surface stops being a card — the background, the
+         * radius, the padding and the shadow are all dropped so the section
+         * sits on the page. The border was not, so every section on every
+         * desktop page kept a 1px rectangle around content that no longer had
+         * a card behind it. A caller that genuinely wants an edge at desktop
+         * adds `lg:border` in `className`, which lands after this in `cn`.
+         */
+        "lg:overflow-visible lg:rounded-none lg:border-0 lg:bg-transparent lg:p-0 lg:shadow-none",
+        className
+      )}
+    >
+      {children}
+    </section>
+  );
+}

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

@@ -0,0 +1,76 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Wallet } from "lucide-react";
+import { HueChip } from "./hue-chip";
+
+const meta: Meta<typeof HueChip> = {
+  title: "Menu/HueChip",
+  component: HueChip,
+  tags: ["autodocs"],
+  args: { children: "Sweet Pastry", hue: "oklch(0.62 0.14 82)" },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A pill wearing a category's colour as a pale wash. It exists because the wash has one non-obvious rule — the mix must happen `in oklab`, never `in oklch` — and that rule has to live in one place. oklch is polar, so mixing a hue into an achromatic `--card` interpolates the hue ANGLE toward 0: honey 82° arrives at 16° (pink), a bar's 205° blue at 41° (orange). The hue is runtime data from ~40 cuisines, so it is an inline custom property rather than a Tailwind class — Tailwind can only emit what it sees at build time.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof HueChip>;
+
+export const Default: Story = {};
+
+/**
+ * The bug this component was extracted to prevent. Every hue survives the mix
+ * with its own identity — the cool families especially, which under `in oklch`
+ * came out orange and mustard.
+ */
+export const EveryFamily: Story = {
+  render: () => (
+    <div className="flex flex-wrap gap-1.5">
+      {[
+        ["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)"],
+        ["Bars", "oklch(0.47 0.10 205)"],
+        ["Clubs", "oklch(0.42 0.11 300)"],
+      ].map(([label, hue]) => (
+        <HueChip key={label} hue={hue}>
+          {label}
+        </HueChip>
+      ))}
+    </div>
+  ),
+};
+
+/** No hue — `--muted`, the right neutral for a facet with no family behind it. */
+export const Untinted: Story = {
+  args: { hue: undefined },
+};
+
+/** A price band: an icon, a bare figure, and an accessible name for it. */
+export const WithIcon: Story = {
+  args: {
+    hue: undefined,
+    className: "font-bold tabular-nums",
+    "aria-label": "kitchen price band: 22–86 lei",
+    icon: <Wallet className="h-3.5 w-3.5 shrink-0 text-muted-foreground" aria-hidden />,
+    children: "22–86 lei",
+  },
+};
+
+/** In a list, which is where most of these live. */
+export const InAList: Story = {
+  render: () => (
+    <ul className="flex flex-wrap items-center gap-1.5">
+      {["Sweet Pastry", "Salad", "Cake"].map((label) => (
+        <HueChip key={label} as="li" hue="oklch(0.62 0.14 82)">
+          {label}
+        </HueChip>
+      ))}
+    </ul>
+  ),
+};

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

@@ -0,0 +1,62 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { HueChip, hueTint } from "./hue-chip";
+
+/**
+ * The whole reason this component exists is one character of CSS, so that is
+ * what is pinned. `color-mix(in oklch, …)` interpolates the hue ANGLE, and the
+ * paper it mixes into is achromatic (`--card` is `oklch(1 0 0)`, hue 0), so
+ * every family colour was dragged a proportional fraction of the way to red:
+ * honey 82° arrived at 16°, pink. It is invisible in a diff and obvious on
+ * screen, which is exactly the kind of thing a test should hold.
+ */
+describe("hueTint", () => {
+  it("mixes in the rectangular space, never the polar one", () => {
+    const tint = hueTint("oklch(0.62 0.14 82)");
+    expect(tint).toContain("in oklab");
+    expect(tint).not.toContain("in oklch,");
+  });
+
+  it("mixes into the surface the chip sits on", () => {
+    expect(hueTint("oklch(0.62 0.14 82)")).toContain("var(--card)");
+    expect(hueTint("oklch(0.62 0.14 82)", "chip", "var(--background)")).toContain(
+      "var(--background)"
+    );
+  });
+
+  it("gives a subtle chip less of the hue than a plain one", () => {
+    expect(hueTint("oklch(0.62 0.14 82)", "chip")).toContain("20%");
+    expect(hueTint("oklch(0.62 0.14 82)", "subtle")).toContain("12%");
+  });
+});
+
+describe("HueChip", () => {
+  it("wears the tint when it has a hue", () => {
+    render(<HueChip hue="oklch(0.62 0.14 82)">Sweet Pastry</HueChip>);
+    const chip = screen.getByText("Sweet Pastry");
+    expect(chip.getAttribute("style")).toContain("oklab");
+    expect(chip.className).not.toContain("bg-muted");
+  });
+
+  it("falls back to the neutral rather than to a colour", () => {
+    // A facet with no family behind it must not borrow another family's colour.
+    render(<HueChip>Fast Food</HueChip>);
+    const chip = screen.getByText("Fast Food");
+    expect(chip.className).toContain("bg-muted");
+    expect(chip.getAttribute("style")).toBeNull();
+  });
+
+  it("renders as a list item when asked, for the lists it lives in", () => {
+    render(
+      <ul>
+        <HueChip as="li">Salad</HueChip>
+      </ul>
+    );
+    expect(screen.getByText("Salad").tagName).toBe("LI");
+  });
+
+  it("takes an accessible name for a chip whose text is a bare figure", () => {
+    render(<HueChip aria-label="kitchen price band: 22–86 lei">22–86 lei</HueChip>);
+    expect(screen.getByLabelText("kitchen price band: 22–86 lei")).toBeInTheDocument();
+  });
+});

package/src/components/hue-chip.tsx

@@ -0,0 +1,99 @@
+import { cn } from "../lib/utils";
+
+/**
+ * HueChip — a pill that wears a category's colour as a pale wash.
+ *
+ * Menu surfaces label things with a family's hue: a cuisine's dish groups, a
+ * going-out family's tags, a price band. Every one of them was an inline
+ * `style` with a hand-written `color-mix` next to a hand-written pill class
+ * list, which is how the two below drifted apart and how the mix space bug
+ * survived as long as it did — it had to be found and fixed in each copy.
+ *
+ * ## The mix space is the whole reason this is a component
+ *
+ * **`in oklab`, and never `in oklch`.** They describe the same colours, but
+ * oklch is POLAR, so `color-mix(in oklch, …)` interpolates the hue ANGLE — and
+ * the paper being mixed into is achromatic (`--card` is `oklch(1 0 0)`, hue 0).
+ * Mixing 20% of a family colour into that lands at a fifth of the family's hue:
+ * honey 82° came out at 16°, which is pink, so a Breakfast & Brunch card wore
+ * pink chips under an amber mosaic. Cool families were worse — a bar's 205°
+ * blue mixes to 41°, orange; a club's 300° violet to 60°, mustard.
+ *
+ * oklab is rectangular: mixing toward an achromatic base scales chroma along
+ * the SAME hue instead of rotating it, which is what "a pale version of this
+ * colour" has to mean.
+ *
+ * ## Why an inline style and not a Tailwind class
+ *
+ * The hue is DATA — one of ~40 cuisine values resolved by the app at request
+ * time — not one of a fixed set of variants. Tailwind can only emit classes it
+ * can see at build time, so a class-based version would mean either a
+ * safelisted colour per cuisine (a palette that must be edited to add a
+ * cuisine) or an arbitrary-value class built from a runtime string, which
+ * Tailwind cannot compile. A CSS custom property set inline is the honest
+ * mechanism; this component is the one place that writes it.
+ */
+
+/** Mix strengths, so callers say what a chip IS rather than picking a number. */
+const STRENGTH = {
+  /** A labelled facet: readable at 11.5px, still clearly the family's colour. */
+  chip: 20,
+  /** A quieter wash, for a chip that sits beside a stronger one. */
+  subtle: 12,
+} as const;
+
+export type HueChipTone = keyof typeof STRENGTH;
+
+/**
+ * The tint itself, exported for the surfaces that need the colour rather than
+ * the pill — a section ground, a hover state. Same rule: `in oklab`.
+ */
+export function hueTint(hue: string, tone: HueChipTone = "chip", base = "var(--card)"): string {
+  return `color-mix(in oklab, ${hue} ${STRENGTH[tone]}%, ${base})`;
+}
+
+export type HueChipProps = {
+  /**
+   * A finished CSS colour — the DS owns no category table, so the app resolves
+   * it. Without one the chip falls back to `--muted`, which is the right
+   * neutral for a facet that has no family behind it.
+   */
+  hue?: string;
+  tone?: HueChipTone;
+  /** The paper the wash is mixed into. Must be the surface the chip sits on. */
+  base?: string;
+  /** Drawn before the label, e.g. a wallet on a price band. */
+  icon?: React.ReactNode;
+  /** `li` inside a list, which is where most of these live. */
+  as?: "span" | "li" | "div";
+  children: React.ReactNode;
+  className?: string;
+  /** For a chip whose visible text is a bare figure, e.g. "22–86 lei". */
+  "aria-label"?: string;
+};
+
+export function HueChip({
+  hue,
+  tone = "chip",
+  base = "var(--card)",
+  icon,
+  as: Tag = "span",
+  children,
+  className,
+  "aria-label": ariaLabel,
+}: HueChipProps) {
+  return (
+    <Tag
+      aria-label={ariaLabel}
+      className={cn(
+        "inline-flex h-7 items-center gap-1.5 rounded-full px-2.5 text-[11.5px] text-foreground",
+        !hue && "bg-muted",
+        className
+      )}
+      style={hue ? { backgroundColor: hueTint(hue, tone, base) } : undefined}
+    >
+      {icon}
+      {children}
+    </Tag>
+  );
+}