@bearmenu/ui 0.8.15 → 0.8.17

package/src/components/coach-marks.tsx

@@ -0,0 +1,252 @@
+"use client";
+
+import { useCallback, useEffect, useLayoutEffect, useState } from "react";
+import { createPortal } from "react-dom";
+import { ArrowRight, Lightbulb } from "lucide-react";
+import { cn } from "../lib/utils";
+import { Button } from "./button";
+
+/**
+ * CoachMarks — a guided tour drawn OVER the real page.
+ *
+ * Four things, one at a time: the page dims, the current stop's target is cut
+ * out of the dimming in a spotlight, its step number sits on the spotlight's
+ * corner, and one callout beside the spotlight says what the target is. Only
+ * the current stop is marked — a map of every stop's number over the page
+ * competes with the page's own numerals and with the callout's "Step N of
+ * M"; the way through is Next, Back and the arrow keys. The reader learns
+ * the surface by looking at the surface, not at a picture of it; nothing on
+ * the page moves or re-renders to be taught.
+ *
+ * Targets are found by `data-coach-mark="<stop id>"` on the page's own
+ * elements, so the page keeps its markup and the tour attaches from outside.
+ * The tour is built from the stops whose target is ON THE PAGE when it opens
+ * (or when the itinerary changes): a stop with nothing to point at is not
+ * counted, so "Step 3 of 5" is always a step the reader will reach. Where
+ * the same id is on two elements — a desktop and a phone rendering of one
+ * control — the visible one is taken.
+ *
+ * The consumer owns the words (`labels`, `stops`) and the open state; the
+ * tour owns its position, the geometry (8px breathing room, the callout's
+ * side, re-measure on scroll and resize) and the keys (Escape closes, the
+ * arrows step). `onProgress` reports the current stop for a toolbar label.
+ *
+ * Rendered into `document.body`: a page wrapper with an opacity or transform
+ * transition is a stacking context, and the tour must sit above everything
+ * the page and its chrome draw, whatever wraps the consumer.
+ */
+
+export type CoachMarkStop = {
+  /** Matches the target's `data-coach-mark` attribute. */
+  id: string;
+  title: string;
+  body: string;
+};
+
+export type CoachMarksLabels = {
+  /** "Step 2 of 4". */
+  progress: (step: number, total: number) => string;
+  back: string;
+  next: string;
+  /** The last stop's forward action, e.g. "Done". */
+  done: string;
+  skip: string;
+};
+
+export type CoachMarksProps = {
+  open: boolean;
+  stops: CoachMarkStop[];
+  /** Skip, Done, Escape and a tap on the dimmed page all end here. */
+  onClose: () => void;
+  /**
+   * 1-based position, the count of stops the page actually has, and the
+   * stop being shown — its id is what a consumer remembers, since the
+   * position shifts when a stop's target is missing.
+   */
+  onProgress?: (step: number, total: number, stop: CoachMarkStop) => void;
+  labels: CoachMarksLabels;
+  className?: string;
+};
+
+type Rect = { top: number; left: number; width: number; height: number };
+
+const PAD = 8;
+const CALLOUT_WIDTH = 320;
+const CALLOUT_GAP = 14;
+/** The room a side needs before the callout goes there. */
+const CALLOUT_ROOM = 280;
+const EDGE = 12;
+
+/** The step number, an inverted disc on the spotlight's corner: dark on the gold ring. */
+const PIN =
+  "pointer-events-none absolute z-[1] flex h-8 w-8 -translate-x-1/2 -translate-y-1/2 items-center justify-center rounded-full bg-[oklch(0.26_0.03_60)] text-[13px] font-extrabold text-[oklch(0.82_0.15_85)] ring-2 ring-[oklch(0.82_0.15_85)] shadow-[0_2px_8px_oklch(0.16_0.012_55_/_0.45)] transition-[top,left] duration-300 motion-reduce:transition-none";
+
+/** The visible element carrying the id — a `display: none` twin has no boxes. */
+function findTarget(id: string): HTMLElement | null {
+  if (typeof document === "undefined") return null;
+  const candidates = document.querySelectorAll<HTMLElement>(`[data-coach-mark="${id}"]`);
+  for (const candidate of candidates) {
+    if (candidate.getClientRects().length > 0) return candidate;
+  }
+  return null;
+}
+
+function measure(element: HTMLElement): Rect {
+  const box = element.getBoundingClientRect();
+  return { top: box.top, left: box.left, width: box.width, height: box.height };
+}
+
+export function CoachMarks({ open, stops, onClose, onProgress, labels, className }: CoachMarksProps) {
+  // The stops the page can show, fixed when the tour opens or the itinerary
+  // changes — by its ids, so a consumer rebuilding the array each render does
+  // not send the tour back to the first stop.
+  const [available, setAvailable] = useState<CoachMarkStop[]>([]);
+  const [index, setIndex] = useState(0);
+  const [rect, setRect] = useState<Rect | null>(null);
+  const [viewport, setViewport] = useState({ width: 0, height: 0 });
+  const itinerary = stops.map((stop) => stop.id).join("|");
+
+  useLayoutEffect(() => {
+    if (!open) return;
+    const present = stops.filter((stop) => findTarget(stop.id));
+    setAvailable(present);
+    setIndex(0);
+    if (present.length === 0) onClose();
+    // `stops` is read whenever its ids change; the words alone do not restart the tour.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open, itinerary]);
+
+  const current = available[index];
+  const currentId = current?.id;
+
+  const remeasure = useCallback(() => {
+    const element = currentId ? findTarget(currentId) : null;
+    setRect(element ? measure(element) : null);
+    setViewport({ width: window.innerWidth, height: window.innerHeight });
+  }, [currentId]);
+
+  // Bring the current target into view, then measure it — again once the
+  // smooth scroll has settled.
+  useLayoutEffect(() => {
+    if (!open || !current) return;
+    const element = findTarget(current.id);
+    if (!element) {
+      // The page changed under the tour: move on, or end when nothing is left.
+      const forward = available.findIndex((stop, at) => at > index && findTarget(stop.id));
+      if (forward !== -1) setIndex(forward);
+      else onClose();
+      return;
+    }
+    element.scrollIntoView({ block: "center", behavior: "smooth", inline: "nearest" });
+    remeasure();
+    const settle = setTimeout(remeasure, 400);
+    return () => clearTimeout(settle);
+  }, [open, current, index, available, remeasure, onClose]);
+
+  useEffect(() => {
+    if (!open || !current) return;
+    onProgress?.(index + 1, available.length, current);
+  }, [open, current, index, available.length, onProgress]);
+
+  useEffect(() => {
+    if (!open) return;
+    window.addEventListener("resize", remeasure);
+    window.addEventListener("scroll", remeasure, true);
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") onClose();
+      if (event.key === "ArrowRight") setIndex((at) => Math.min(at + 1, available.length - 1));
+      if (event.key === "ArrowLeft") setIndex((at) => Math.max(at - 1, 0));
+    };
+    window.addEventListener("keydown", onKey);
+    return () => {
+      window.removeEventListener("resize", remeasure);
+      window.removeEventListener("scroll", remeasure, true);
+      window.removeEventListener("keydown", onKey);
+    };
+  }, [open, remeasure, onClose, available.length]);
+
+  if (!open || !current || !rect) return null;
+
+  const last = index === available.length - 1;
+  const spot = {
+    top: rect.top - PAD,
+    left: rect.left - PAD,
+    width: rect.width + PAD * 2,
+    height: rect.height + PAD * 2,
+  };
+  // Below the target when there is room for the callout, else above it; a
+  // target taller than the viewport leaves room on neither side, and the
+  // callout then sits at the bottom edge, over the target's lower part.
+  const roomBelow = viewport.height - (spot.top + spot.height);
+  const calloutLeft = Math.min(
+    Math.max(spot.left, EDGE),
+    Math.max(EDGE, viewport.width - CALLOUT_WIDTH - EDGE)
+  );
+  const calloutPlace =
+    roomBelow > CALLOUT_ROOM
+      ? { top: spot.top + spot.height + CALLOUT_GAP, left: calloutLeft }
+      : spot.top > CALLOUT_ROOM
+        ? { bottom: viewport.height - spot.top + CALLOUT_GAP, left: calloutLeft }
+        : { bottom: EDGE, left: calloutLeft };
+
+  return createPortal(
+    <div
+      className={cn("fixed inset-0 z-[80]", className)}
+      role="dialog"
+      aria-modal
+      aria-label={current.title}
+    >
+      {/* The dimming is the spotlight's shadow: one element, cut out where
+          the target is, so the target stays fully visible and the rest of the
+          page falls back. A tap on the dim closes the tour. */}
+      <button
+        type="button"
+        aria-label={labels.skip}
+        onClick={onClose}
+        className="absolute inset-0 cursor-default"
+      />
+      <div
+        aria-hidden
+        className="pointer-events-none absolute rounded-[18px] shadow-[0_0_0_9999px_oklch(0.16_0.012_55_/_0.55)] ring-2 ring-[oklch(0.82_0.15_85)] transition-[top,left,width,height] duration-300 motion-reduce:transition-none"
+        style={spot}
+      />
+
+      {/* The step number on the spotlight's corner; the callout says the rest. */}
+      <span aria-hidden className={PIN} style={{ top: rect.top - 2, left: rect.left - 2 }}>
+        {index + 1}
+      </span>
+
+      {/* The callout. */}
+      <div
+        className="absolute z-[2] w-[min(320px,calc(100vw-24px))] rounded-2xl border border-border bg-card p-4 text-card-foreground shadow-xl"
+        style={calloutPlace}
+      >
+        <span className="inline-flex items-center gap-1.5 rounded-full bg-[oklch(0.82_0.15_85)] px-2.5 py-1 text-[10.5px] font-extrabold uppercase tracking-[0.08em] text-[oklch(0.26_0.03_60)]">
+          <Lightbulb className="h-3 w-3" aria-hidden />
+          {labels.progress(index + 1, available.length)}
+        </span>
+        <p className="mt-3 text-[15px] font-bold leading-snug">{current.title}</p>
+        <p className="mt-1.5 text-sm leading-relaxed text-muted-foreground">{current.body}</p>
+        <div className="mt-4 flex items-center gap-2">
+          {index > 0 && (
+            <Button type="button" variant="ghost" size="sm" onClick={() => setIndex(index - 1)}>
+              {labels.back}
+            </Button>
+          )}
+          <Button
+            type="button"
+            size="sm"
+            onClick={() => (last ? onClose() : setIndex(index + 1))}
+          >
+            {last ? labels.done : labels.next}
+            {!last && <ArrowRight aria-hidden />}
+          </Button>
+          <Button type="button" variant="link" size="sm" className="ml-auto" onClick={onClose}>
+            {labels.skip}
+          </Button>
+        </div>
+      </div>
+    </div>,
+    document.body
+  );
+}

package/src/components/doorway-tiles.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react";
+import { TextSearch } from "lucide-react";
 import { DoorwayTiles } from "./doorway-tiles";
 import {
   mockFamilyTiles,
@@ -58,6 +59,25 @@ export const PolaroidPartial: Story = {
   args: { treatment: "polaroid", tiles: mockFamilyTiles.slice(0, 5) },
 };
 
+/**
+ * The closing tile as a door to an ACTION — the menu's search page. No
+ * photograph, no initial: the print holds a glyph on the photo ground, and
+ * the tile keeps its siblings' silhouette.
+ */
+export const PolaroidWithSearchDoor: Story = {
+  args: {
+    treatment: "polaroid",
+    tiles: mockFamilyTiles,
+    all: {
+      ...mockFamilyTilesAll,
+      label: "Search the menu",
+      countLabel: "535 dishes · 210 drinks",
+      photoUrl: undefined,
+      icon: <TextSearch strokeWidth={1.75} aria-hidden />,
+    },
+  },
+};
+
 /** The occasions: the mood's hue multiplied over a room. */
 export const Ground: Story = {
   args: { treatment: "ground", tiles: mockOccasionTiles, all: mockOccasionTilesAll },
@@ -81,3 +101,17 @@ export const GroundWithoutPhotos: Story = {
     tiles: mockOccasionTiles.map(({ photoUrl: _photoUrl, ...tile }) => tile),
   },
 };
+
+/** The closing tile as a door to an action on the ground treatment: the glyph where the initial was. */
+export const GroundWithActionDoor: Story = {
+  args: {
+    treatment: "ground",
+    tiles: mockOccasionTiles,
+    all: {
+      ...mockOccasionTilesAll,
+      label: "Search the menu",
+      photoUrl: undefined,
+      icon: <TextSearch strokeWidth={1.75} aria-hidden />,
+    },
+  },
+};

package/src/components/doorway-tiles.test.tsx

@@ -30,6 +30,33 @@ describe("DoorwayTiles", () => {
     expect(screen.getByText(withoutPhoto.label.charAt(0))).toBeInTheDocument();
   });
 
+  // A door about an action carries a glyph in the print: no photograph, and
+  // not the initial either — that would read as a family starting with "S".
+  it("draws the glyph, not the initial or the photo, where a tile has an icon", () => {
+    const search = {
+      ...mockFamilyTilesAll,
+      label: "Search the menu",
+      icon: <svg data-testid="glyph" />,
+    };
+    render(<DoorwayTiles treatment="polaroid" tiles={mockFamilyTiles.slice(0, 1)} all={search} />);
+    expect(screen.getByTestId("glyph")).toBeInTheDocument();
+    expect(screen.queryByText("S")).not.toBeInTheDocument();
+    expect(document.querySelectorAll("img")).toHaveLength(1);
+  });
+
+  it("ground: the glyph takes the initial's place and no photograph is drawn for it", () => {
+    const door = {
+      ...mockOccasionTilesAll,
+      label: "Search the menu",
+      icon: <svg data-testid="glyph" />,
+    };
+    render(<DoorwayTiles treatment="ground" tiles={mockOccasionTiles.slice(0, 1)} all={door} />);
+    expect(screen.getByTestId("glyph")).toBeInTheDocument();
+    expect(screen.queryByText("S")).not.toBeInTheDocument();
+    const withPhoto = mockOccasionTiles.slice(0, 1).filter((t) => t.photoUrl).length;
+    expect(document.querySelectorAll("img")).toHaveLength(withPhoto);
+  });
+
   it("omits the index tile when no index is given", () => {
     render(<DoorwayTiles treatment="polaroid" tiles={mockFamilyTiles.slice(0, 3)} />);
     expect(screen.getAllByRole("link")).toHaveLength(3);

package/src/components/doorway-tiles.tsx

@@ -1,6 +1,6 @@
 import { cn } from "../lib/utils";
 import type { MenuLinkComponent, MenuLinkProps } from "./menu-types";
-import { PhotoGround } from "./photo-ground";
+import { PHOTO_GLYPH_SHADOW, PHOTO_GROUND, PhotoGround } from "./photo-ground";
 
 /**
  * DoorwayTiles — a grid of doors: every class the reader browses by, as
@@ -89,6 +89,17 @@ export type DoorwayTile = {
   gradient?: string;
   /** Pre-resolved photograph of the CLASS, from the consumer's own origin. */
   photoUrl?: string;
+  /**
+   * A glyph in the photograph's place — for a tile about an ACTION, not a
+   * thing. A search door has no class to photograph, and any subject put on
+   * it (a table, a lens, a book) reads as one more family; the initial the
+   * fallback draws is a family's initial too. So the print holds the glyph
+   * instead, on the photo ground with the photo fallback's drop shadow, and
+   * the tile keeps its siblings' silhouette. Wins over `photoUrl`.
+   *
+   * A node rather than a name: the app owns its iconography.
+   */
+  icon?: React.ReactNode;
 };
 
 export type DoorwayTilesTreatment = "polaroid" | "ground";
@@ -144,6 +155,17 @@ 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";
 
+/**
+ * The action glyph. In the polaroid it fills the print at 44% on the photo
+ * ground, white with the fallback family's drop shadow; on the ground
+ * treatment it takes the initial's place at the initial's weight.
+ */
+const PRINT_ICON =
+  `absolute inset-0 flex items-center justify-center ${PHOTO_GROUND} text-white/90 ` +
+  `[&_svg]:h-[44%] [&_svg]:w-[44%] [&_svg]:${PHOTO_GLYPH_SHADOW}`;
+const GROUND_ICON =
+  "absolute inset-0 z-0 flex items-center justify-center text-white/15 [&_svg]:h-[40%] [&_svg]:w-[40%]";
+
 export function DoorwayTiles({
   tiles,
   all,
@@ -167,7 +189,9 @@ export function DoorwayTiles({
           >
             {isPolaroid ? (
               <span aria-hidden className={POLAROID}>
-                {tile.photoUrl ? (
+                {tile.icon ? (
+                  <span className={PRINT_ICON}>{tile.icon}</span>
+                ) : 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
@@ -186,6 +210,10 @@ export function DoorwayTiles({
                   />
                 )}
               </span>
+            ) : tile.icon ? (
+              <span aria-hidden className={GROUND_ICON}>
+                {tile.icon}
+              </span>
             ) : tile.photoUrl ? (
               <>
                 {/* eslint-disable-next-line @next/next/no-img-element */}

package/src/components/facet-group.tsx

@@ -118,6 +118,13 @@ export type FacetGroupProps = Omit<
   /** e.g. "Show all". Omit to hide the trailing action. */
   moreLabel?: string;
   onMore?: () => void;
+  /**
+   * Whether the trailing action has already expanded the options it controls
+   * — set it when `onMore` reveals more rows in place (and `moreLabel` reads
+   * "Show fewer"), so the button carries `aria-expanded`. Leave it unset when
+   * the action opens another surface.
+   */
+  moreExpanded?: boolean;
   className?: string;
 };
 
@@ -133,6 +140,7 @@ export function FacetGroup({
   onToggle,
   moreLabel,
   onMore,
+  moreExpanded,
   className,
   ...rest
 }: FacetGroupProps) {
@@ -304,6 +312,7 @@ export function FacetGroup({
         <button
           type="button"
           onClick={onMore}
+          aria-expanded={moreExpanded}
           className="cursor-pointer pt-[11px] text-[12.5px] font-bold text-primary transition-colors duration-150 hover:text-primary/80 motion-reduce:transition-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:rounded-sm"
         >
           {moreLabel}

package/src/components/haptic-switch.test.tsx

@@ -0,0 +1,134 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { HapticSwitch, isHapticSwitchTarget } from "./haptic-switch";
+import { Button } from "./button";
+import { Switch } from "./switch";
+
+const IOS_UA =
+  "Mozilla/5.0 (iPhone; CPU iPhone OS 26_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.5 Mobile/15E148 Safari/604.1";
+
+function pretendIos() {
+  vi.spyOn(navigator, "userAgent", "get").mockReturnValue(IOS_UA);
+}
+
+const overlay = () => document.querySelector<HTMLInputElement>('input[data-slot="haptic-switch"]');
+
+describe("HapticSwitch", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("renders nothing off iOS", () => {
+    render(<HapticSwitch />);
+    expect(overlay()).toBeNull();
+  });
+
+  it("renders an invisible native switch on iOS, out of the tab order and the a11y tree", () => {
+    pretendIos();
+    render(<HapticSwitch />);
+    const input = overlay();
+    expect(input).not.toBeNull();
+    expect(input?.type).toBe("checkbox");
+    expect(input?.hasAttribute("switch")).toBe(true);
+    expect(input?.getAttribute("aria-hidden")).toBe("true");
+    expect(input?.tabIndex).toBe(-1);
+    expect(input?.className).toContain("opacity-0");
+  });
+
+  it("mirrors the host's disabled state", () => {
+    pretendIos();
+    render(<HapticSwitch disabled />);
+    expect(overlay()?.disabled).toBe(true);
+  });
+
+  it("identifies its own click target", () => {
+    pretendIos();
+    render(<HapticSwitch />);
+    expect(isHapticSwitchTarget(overlay())).toBe(true);
+    expect(isHapticSwitchTarget(document.body)).toBe(false);
+    expect(isHapticSwitchTarget(null)).toBe(false);
+  });
+});
+
+describe("Button haptic on iOS", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("lays the switch over the button and still runs onClick when the switch is tapped", async () => {
+    pretendIos();
+    const onClick = vi.fn();
+    render(
+      <Button haptic onClick={onClick}>
+        Save
+      </Button>
+    );
+    const button = screen.getByRole("button", { name: "Save" });
+    expect(button.className).toContain("relative");
+    const input = overlay();
+    expect(input?.parentElement).toBe(button);
+
+    await userEvent.click(input!);
+    expect(onClick).toHaveBeenCalledTimes(1);
+    expect(input?.checked).toBe(true);
+  });
+
+  it("does not render the switch without haptic, or with asChild", () => {
+    pretendIos();
+    const { rerender } = render(<Button>Plain</Button>);
+    expect(overlay()).toBeNull();
+    rerender(
+      <Button haptic asChild>
+        <a href="/x">Link</a>
+      </Button>
+    );
+    expect(overlay()).toBeNull();
+  });
+
+  it("forwards a submit tapped through the switch to the form", async () => {
+    pretendIos();
+    const onSubmit = vi.fn((e: React.FormEvent) => e.preventDefault());
+    render(
+      <form onSubmit={onSubmit}>
+        <Button type="submit" haptic>
+          Send
+        </Button>
+      </form>
+    );
+    await userEvent.click(overlay()!);
+    expect(onSubmit).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not forward the submit when the click handler cancelled it", async () => {
+    pretendIos();
+    const onSubmit = vi.fn((e: React.FormEvent) => e.preventDefault());
+    render(
+      <form onSubmit={onSubmit}>
+        <Button type="submit" haptic onClick={(e) => e.preventDefault()}>
+          Send
+        </Button>
+      </form>
+    );
+    await userEvent.click(overlay()!);
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+});
+
+describe("Switch haptic on iOS", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("toggles through a tap on the overlay", async () => {
+    pretendIos();
+    const onCheckedChange = vi.fn();
+    render(<Switch haptic aria-label="Precise" onCheckedChange={onCheckedChange} />);
+    const root = screen.getByRole("switch", { name: "Precise" });
+    expect(root.className).toContain("relative");
+    expect(overlay()?.parentElement).toBe(root);
+
+    await userEvent.click(overlay()!);
+    expect(onCheckedChange).toHaveBeenCalledWith(true);
+  });
+});

package/src/components/haptic-switch.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import * as React from "react";
+import { isIos } from "../hooks/use-haptic";
+
+export const HAPTIC_SWITCH_SLOT = "haptic-switch";
+
+/** True when a click's target is the overlay switch rather than the host. */
+export function isHapticSwitchTarget(target: EventTarget | null): boolean {
+  return target instanceof HTMLElement && target.dataset.slot === HAPTIC_SWITCH_SLOT;
+}
+
+type HapticSwitchProps = {
+  /** Mirror the host's disabled state; a disabled switch neither flips nor ticks. */
+  disabled?: boolean;
+};
+
+/**
+ * The only haptic iOS Safari has left.
+ *
+ * WebKit plays the system toggle haptic when an `<input type="checkbox" switch>`
+ * flips under the user's finger, and since iOS 26.5 under the finger is the
+ * only way — a programmatic click on the input or its label no longer counts
+ * (WebKit #65327). So the switch goes INSIDE the control, stretched over it and
+ * invisible, and the tap that lands on the control lands on the switch first.
+ * The click then bubbles to the host's own handler as usual.
+ *
+ * What the host must do:
+ * - be positioned (`relative` at least) so `inset-0` fills it;
+ * - not call `preventDefault()` on the click — that cancels the toggle, and
+ *   the toggle is the haptic;
+ * - if it is `type="submit"`, submit explicitly: the click target is the
+ *   switch, so the button's implicit submission never runs. `Button` does
+ *   this through `form.requestSubmit()`.
+ *
+ * Renders nothing on the server and on non-iOS clients (so the first client
+ * render matches SSR). Keyboard and assistive-tech activation land on the host,
+ * not the switch, and stay silent. `opacity: 0`, never `display: none` — a
+ * switch that is not rendered does not tick.
+ */
+export function HapticSwitch({ disabled = false }: HapticSwitchProps) {
+  const [enabled, setEnabled] = React.useState(false);
+
+  React.useEffect(() => {
+    setEnabled(isIos());
+  }, []);
+
+  if (!enabled) return null;
+
+  return (
+    <input
+      type="checkbox"
+      // WebKit's non-standard attribute; React's input types do not know it.
+      ref={(el) => el?.setAttribute("switch", "")}
+      data-slot={HAPTIC_SWITCH_SLOT}
+      aria-hidden="true"
+      tabIndex={-1}
+      disabled={disabled}
+      className="absolute inset-0 m-0 h-full w-full cursor-[inherit] rounded-[inherit] opacity-0 touch-manipulation [-webkit-tap-highlight-color:transparent]"
+    />
+  );
+}

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

@@ -31,9 +31,12 @@ describe("hueTint", () => {
 });
 
 describe("HueChip", () => {
+  // The label sits in an inner span that ellipsises; the chip is its parent.
+  const chipOf = (text: string) => screen.getByText(text).parentElement!;
+
   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");
+    const chip = chipOf("Sweet Pastry");
     expect(chip.getAttribute("style")).toContain("oklab");
     expect(chip.className).not.toContain("bg-muted");
   });
@@ -41,7 +44,7 @@ describe("HueChip", () => {
   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");
+    const chip = chipOf("Fast Food");
     expect(chip.className).toContain("bg-muted");
     expect(chip.getAttribute("style")).toBeNull();
   });
@@ -52,7 +55,7 @@ describe("HueChip", () => {
         <HueChip as="li">Salad</HueChip>
       </ul>
     );
-    expect(screen.getByText("Salad").tagName).toBe("LI");
+    expect(chipOf("Salad").tagName).toBe("LI");
   });
 
   it("takes an accessible name for a chip whose text is a bare figure", () => {

package/src/components/hue-chip.tsx

@@ -86,14 +86,17 @@ export function HueChip({
     <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",
+        // One line, and never wider than its row: a chip that wraps grows past
+        // its 28px and paints over its neighbours; a chip that overflows pushes
+        // the row. The label ellipsises instead.
+        "inline-flex h-7 min-w-0 max-w-full items-center gap-1.5 whitespace-nowrap rounded-full px-2.5 text-[11.5px] text-foreground",
         !hue && "bg-muted",
         className
       )}
       style={hue ? { backgroundColor: hueTint(hue, tone, base) } : undefined}
     >
       {icon}
-      {children}
+      <span className="min-w-0 truncate">{children}</span>
     </Tag>
   );
 }