@bearmenu/ui 0.8.8 → 0.8.10

package/src/components/menu-types.ts

@@ -0,0 +1,442 @@
+/**
+ * Structural mirror of the openapi `Dish` / `Drink` schemas, decoupled from any
+ * one app's generated types. FE, admin and post-generator map their domain
+ * shapes into these before passing data to the menu-hub surfaces.
+ *
+ * Same contract as `place-types.ts` and `event-types.ts`: no app schemas, no
+ * app hooks, no i18n. Every user-facing string arrives through a `*Labels`
+ * object, every destination through an `href`, and every locale-sensitive
+ * format through an injected formatter — the DS never owns a translation key
+ * or an `Intl` locale.
+ *
+ * ## One set of components, two tabs
+ *
+ * Dishes and drinks are the same shape. `MenuItemPreview.kind` is the only
+ * discriminator, and nothing in this file branches on it — a drinks hub is a
+ * different view model and a different `*Labels` object, never a second set of
+ * components. Anything that would need a `if (kind === 'drink')` inside a
+ * component belongs in the caller's mapper instead.
+ */
+
+import type { ComponentType, CSSProperties, ReactNode } from 'react'
+
+import type { MenuSizeAndPrice, PlacePreview } from './place-types'
+
+export type { MenuSizeAndPrice } from './place-types'
+
+/**
+ * The shape every menu surface's `linkComponent` must accept.
+ *
+ * One type rather than a clone per component: these surfaces nest each other —
+ * a family card renders a `<MenuItem>`, a spotlight renders a signature block —
+ * and a caller passes ONE `next/link` down through all of them. Subtly
+ * different clones made those hand-offs fail to typecheck for no design reason.
+ */
+export type MenuLinkProps = {
+  href: string
+  className?: string
+  'aria-label'?: string
+  'aria-current'?: 'page'
+  /** Intent tiles paint their hue on the link element itself. */
+  style?: CSSProperties
+  children?: ReactNode
+}
+
+export type MenuLinkComponent = ComponentType<MenuLinkProps>
+
+/**
+ * A dish or a drink as every hub surface consumes it.
+ *
+ * `mentions` is the census count of review mentions and is populated on every
+ * item in the catalogue — it is the ranking signal the hub is built on. Do not
+ * confuse it with `review_count`, which counts full review objects and is zero
+ * for most items; a surface that ranks on `review_count` renders an empty page.
+ */
+export type MenuItemPreview = {
+  id: string
+  slug: string
+  name: string
+  kind: 'dish' | 'drink'
+  description?: string
+  /** API category code (pizza, pasta, cocktail, non-alcoholic, …). Localised by the caller. */
+  category_slug?: string
+  sizes_and_prices?: MenuSizeAndPrice[]
+  /** Censused review mentions. The hub's ranking signal. */
+  mentions?: number
+  /** Full review objects citing this item. Sparse — not a ranking signal. */
+  review_count?: number
+  /** 0–100 recommendation score. */
+  score?: number
+  /** The venue serving it. Menu items are always venue-scoped. */
+  place?: MenuItemPlaceRef
+  /**
+   * Pre-resolved photo URL. Menu-item photography is AI-generated and hidden in
+   * production, so hub surfaces draw a typographic `<MenuFieldTile>` instead
+   * and leave this unset. It exists for the surfaces that legitimately show one
+   * (concept detail) and for consumers outside the consumer app.
+   */
+  photo_url?: string
+}
+
+/** The venue attribution carried on a menu item. */
+export type MenuItemPlaceRef = {
+  slug: string
+  name: string
+  /** Pre-resolved venue thumbnail. Venue photography is real; item photography is not. */
+  thumbnail_url?: string
+}
+
+/**
+ * A dish or drink concept — one item across every kitchen that makes it, under
+ * whatever name each of them uses. The page's keystone, and the one thing the
+ * catalogue can say that a single menu cannot.
+ */
+export type MenuConceptPreview = {
+  slug: string
+  /** Canonical concept name, e.g. "Margherita". */
+  title: string
+  kind: 'dish' | 'drink'
+  /** Venues serving it. */
+  venue_count?: number
+  price_low?: number
+  price_high?: number
+  /** Distinct names it appears under across those menus. */
+  alias_count?: number
+  /** Summed censused mentions across every venue's version. */
+  mentions?: number
+  rows?: MenuConceptRow[]
+}
+
+/** One venue's version of a concept, as drawn by `<ConceptCompare>`. */
+export type MenuConceptRow = {
+  place_slug: string
+  place_name: string
+  /** What this kitchen calls it on its own menu. */
+  alias: string
+  price: number
+  mentions?: number
+  rating?: number
+  /** Venue type line, e.g. "pub". Localised by the caller. */
+  place_type?: string
+  /** Neighbourhood, e.g. "Centru". */
+  place_area?: string
+  /**
+   * Pre-resolved VENUE photograph.
+   *
+   * The row is place-led: five restaurants that disagree about a name, not five
+   * bars of similar length. A price bar was drawn here first and it measured
+   * the one thing already written beside it in words, while the venue — the
+   * thing you are actually choosing between — had no image at all.
+   */
+  place_thumbnail_url?: string
+  open_now?: boolean
+  /** Marks the row the surface should lead with (cheapest, or most named). */
+  featured?: boolean
+  /** Portion, already formatted with its unit, e.g. "260g". */
+  portion_label?: string
+}
+
+/**
+ * A browsable grouping of venues — a cuisine on the dishes tab, a drink family
+ * on the drinks tab. Both are sets of VENUES, never sets of items: cuisine
+ * exists only on places, so a card counting dishes cannot be built.
+ */
+export type MenuFamilyPreview = {
+  slug: string
+  /** Display name, already localised by the caller. */
+  name: string
+  /** Venues in this family. */
+  venue_count: number
+  /**
+   * Facet chips. Counts are VENUES, not items — they come from the places
+   * facet narrowed by this family. The drinks tab has no equivalent facet, so
+   * its chips ship without counts; `count` is optional for that reason.
+   */
+  chips?: MenuFamilyChip[]
+  /** Price band across the family's venues. */
+  price_low?: number
+  price_high?: number
+  price_median?: number
+  /** Pre-resolved venue photos for the mosaic. Venue photography only. */
+  venue_photo_urls?: string[]
+}
+
+export type MenuFamilyChip = {
+  slug: string
+  label: string
+  /** Venue count. Absent where no facet backs the chip. */
+  count?: number
+}
+
+/**
+ * A venue as the hub's venue-scoped surfaces consume it: the place itself plus
+ * the pre-resolved bits a hub row needs and `PlacePreview` does not carry —
+ * which signature to lead with, and where the row points.
+ */
+export type MenuVenuePreview = {
+  place: PlacePreview
+  href: string
+  /**
+   * The signature to draw. Callers pick it from `reviews_digest.must_try`
+   * rather than the surface re-deriving the rule on every row.
+   */
+  signature?: MenuVenueSignature
+  /** Closing time as an already-formatted wall clock, e.g. "23:00". */
+  closes_at_label?: string
+}
+
+/**
+ * The resolved signature on a venue row.
+ *
+ * It carries a whole `MenuItemPreview` rather than a flattened name and price,
+ * because every surface that draws one renders `<MenuItem>` — the same row a
+ * venue's own menu uses — and that component takes an item. Flattening it here
+ * was what let the hub's version drift into a different-looking row.
+ */
+export type MenuVenueSignature = {
+  item: MenuItemPreview
+  /** The reviewers' reason, from the digest. Rendered in place of the description. */
+  why?: string
+  href?: string
+  /** The digest called this the venue's signature rather than merely frequent. */
+  isSignature?: boolean
+}
+
+/**
+ * An intent tile — a family plus a constraint, resolving to a category page.
+ *
+ * Only about thirty-two of the thirty-eight cuisines have a page, so `href` is
+ * required: a tile that cannot resolve to a real destination is not rendered
+ * rather than linking nowhere.
+ */
+export type MenuIntentTile = {
+  slug: string
+  label: string
+  /** Supporting line, e.g. "247 kitchens". Already formatted by the caller. */
+  caption?: string
+  href: string
+  /**
+   * Finished CSS gradient for the tile's ground, e.g.
+   * `linear-gradient(150deg, …)`.
+   *
+   * A gradient rather than a token name, for the same reason `<MenuField>`
+   * takes one: the hue tables are app-owned, and a component referencing
+   * `var(--h-pizza)` renders an invisible tile in any consumer that does not
+   * happen to define that variable. A missing gradient falls back to `bg-muted`
+   * — visible and obviously unstyled, rather than white text on white.
+   */
+  gradient?: string
+  /** Icon node, resolved by the caller — the DS does not pick icons for it. */
+  icon?: ReactNode
+}
+
+/**
+ * One figure in the intent hero — a number the reader can tap to filter by.
+ *
+ * The value arrives pre-formatted because the figures are not all the same
+ * quantity: "247" is a count and "58" is a count of a subset, but a caller may
+ * also want "4 past midnight", and a component that formatted numbers itself
+ * would need the locale it is forbidden to own.
+ */
+export type MenuIntentFigure = {
+  key: string
+  /** Pre-formatted, e.g. "247". */
+  value: string
+  /** The unit, e.g. "kitchens" or "make a pizza". */
+  label: string
+  /**
+   * The state this figure applies, as a URL.
+   *
+   * An `href` rather than only a callback because the filter state lives in the
+   * query string: a link is server-rendered, crawlable, middle-clickable and
+   * survives with no JavaScript, and `?open=now` is an indexable state we
+   * actively want followed. `onSelect` remains for consumers holding the state
+   * in memory; `href` wins when both are set.
+   */
+  href?: string
+  /**
+   * Applies this figure as a filter without navigating. A figure with neither
+   * `href` nor `onSelect` renders as a static fact rather than as a control
+   * that does nothing — the total is usually one, since filtering to "all of
+   * them" is not a state.
+   */
+  onSelect?: () => void
+  /** The filter this figure applies is already on. */
+  active?: boolean
+}
+
+/**
+ * A filter chip on the intent page.
+ *
+ * Every chip counts KITCHENS, whatever facet backs it — a dietary chip reads
+ * "has a vegetarian dish" and counts venues, not dishes. Mixing venue counts
+ * and item counts in one row is what made the earlier version unreadable, so
+ * the type carries no unit: there is only ever one.
+ */
+export type MenuFilterChip = {
+  key: string
+  label: string
+  /** Kitchens this chip would leave. Absent where no facet backs it. */
+  count?: number
+  active?: boolean
+  /**
+   * Zero kitchens under the current filters — dimmed, but STILL TAPPABLE.
+   *
+   * Tapping swaps it in and drops whichever active filter conflicts, with a
+   * line saying which. A disabled chip would leave the reader guessing why the
+   * thing they want is unavailable; this one answers it by being pressed.
+   */
+  empty?: boolean
+  /** Icon node, resolved by the caller. */
+  icon?: ReactNode
+}
+
+/**
+ * A venue row on the intent page — the page's spine.
+ *
+ * Distinct from `MenuVenuePreview` (the hub's ranked row) in one structural
+ * way that is the whole point of the surface: the dish carries its own `href`,
+ * so the row has TWO targets. The row goes to the venue; the dish name opens
+ * the item drawer. `RankedVenueList` wraps its entire row in one link and
+ * therefore cannot express this, which is why this is a separate shape rather
+ * than a flag on that one.
+ */
+export type MenuKitchenPreview = {
+  place: PlacePreview
+  /** The venue page. The row's primary target. */
+  href: string
+  /** Venue type and district, composed and localised by the caller, e.g. "pizzeria · Centru". */
+  metaLabel?: string
+  /**
+   * "kitchen until 23:00", or "closed · opens 12:00". Composed by the caller
+   * because the wording differs by scope — a bar is not a kitchen.
+   */
+  hoursLabel?: string
+  dish?: MenuKitchenDish
+  /** Pre-formatted, e.g. "62 lei". */
+  priceLabel?: string
+}
+
+/** The dish a kitchen row leads with. The row's second target. */
+export type MenuKitchenDish = {
+  name: string
+  /**
+   * Opens the item drawer. Omit for an inert dish line — a must-try the
+   * reviews named that has no live menu row behind it.
+   */
+  href?: string
+  /** Kicker over the name: "MOST NAMED HERE", or "WHY IT MATCHES" when filtered. */
+  kicker: string
+  /** Under the name: "17 reviews name it", or "mid-range · 300g" when matched. */
+  meta?: string
+  /**
+   * This row is answering a filter rather than volunteering its most-named
+   * dish. Draws the match mark and tints the block, so a reader scanning a
+   * filtered list can see that every row changed its reason for being there.
+   */
+  matched?: boolean
+  /** The filter it matched, e.g. "vegetarian". */
+  matchLabel?: string
+}
+
+/**
+ * One row in a browse index — the complete set, at a glance.
+ *
+ * The index is the page's whole SEO job: it carries a crawlable link to every
+ * destination the city has, which is what frees the richer blocks below it to
+ * be progressive. So it holds nothing but what a reader needs to choose — a
+ * name, a count and a colour.
+ */
+export type MenuIndexEntry = {
+  slug: string
+  name: string
+  count: number
+  href: string
+  /** Finished CSS gradient for the mark. Falls back to the border colour. */
+  gradient?: string
+}
+
+/**
+ * A family on the cuisines index — the hub's card, opened out sideways.
+ *
+ * Deliberately thin. The reader here is choosing a cuisine, not a venue, and
+ * every field the block does NOT carry is a decision the next page owns.
+ */
+export type MenuFamilyBlockPreview = {
+  slug: string
+  name: string
+  venueCount: number
+  /** Facet chips. Labels only — the block never prints their counts. */
+  chips?: MenuFamilyChip[]
+  /** Composed price band, e.g. "22–86 lei". */
+  priceBandLabel?: string
+  /** Venue photography only — item photography is AI-generated and never shown. */
+  photoUrls?: string[]
+  /**
+   * Venues, as kitchen rows. The block draws every one it is given — the caller
+   * decides how many, because how much of a claim the block makes is the page's
+   * decision, not the component's.
+   *
+   * The same `MenuKitchenPreview` the intent page's list takes, rendered by the
+   * same component — a family block that grew its own venue row would be the
+   * fourth near-identical row in the package, and they drift the moment one of
+   * them gets a fix.
+   */
+  venues?: MenuKitchenPreview[]
+  /** The family's own page. */
+  href: string
+}
+
+/**
+ * One "loosen this" row on a dead end — a filter, and what dropping it returns.
+ *
+ * The count is the point: "drop Open now" is a guess, "+8 kitchens" is an
+ * answer, and a dead end that cannot say which filter costs the most is just
+ * an empty state with extra steps.
+ */
+export type MenuLoosenOption = {
+  key: string
+  /** e.g. 'Drop "Open now"'. */
+  label: string
+  /** e.g. "+8 kitchens". Pre-formatted. */
+  gainLabel: string
+  /**
+   * The state without this filter, as a URL.
+   *
+   * An `href` because dropping a filter IS a navigation wherever the filter set
+   * lives in the query string — which makes it server-renderable, shareable and
+   * undoable with the back button. `onSelect` remains for consumers holding the
+   * state in memory; `href` wins when both are set.
+   */
+  href?: string
+  onSelect?: () => void
+}
+
+/** One question and its answer. Static prose — never an accordion; see `<QaBlock>`. */
+export type QaItem = {
+  question: string
+  answer: string
+}
+
+/** Formatters injected into every menu surface. The DS owns no `Intl` locale. */
+export type MenuFormatters = {
+  /** 24 → "24 lei". */
+  price: (value: number) => string
+  /** 1717 → "1,717". */
+  number: (value: number) => string
+}
+
+/** Strings shared by every menu-hub surface. */
+export type MenuHubLabels = {
+  /** Mention-count badge. Pass a translator that handles ICU pluralization. */
+  mentions: (count: number) => string
+  /** Venue-count line. Pass a translator that handles ICU pluralization. */
+  venues: (count: number) => string
+  /** "See all" affordance on a section header. */
+  seeAll: string
+  /** Badge on a must-try row the digest called `signature`. */
+  signature: string
+  openNow: string
+  /** Prefixes a closing time, e.g. "until". */
+  until: string
+}

package/src/components/motion-icon-controls.tsx

@@ -14,7 +14,7 @@
 import * as React from "react";
 import { motion, type Variants } from "framer-motion";
 
-import { MotionIcon, beats, returnTransition, type MotionIconProps } from "./motion-icon";
+import { MotionIcon, beats, pivot, returnTransition, type MotionIconProps } from "./motion-icon";
 
 // ─── Heart — favorite. Squash, then inflate (deform) ──────────────────────────
 
@@ -41,7 +41,7 @@ export function MotionHeart(props: MotionIconProps) {
     <MotionIcon {...props}>
       <motion.path
         variants={heartBody}
-        style={{ originX: "12px", originY: "13px" }}
+        style={pivot(12, 13)}
         fill="currentColor"
         fillOpacity={0}
         d="M2 9.5a5.5 5.5 0 0 1 9.591-3.676.56.56 0 0 0 .818 0A5.49 5.49 0 0 1 22 9.5c0 2.29-1.5 4-3 5.5l-5.492 5.313a2 2 0 0 1-3 .019L5 15c-1.5-1.5-3-3.2-3-5.5"
@@ -71,7 +71,7 @@ export function MotionBookmark(props: MotionIconProps) {
     <MotionIcon {...props}>
       <motion.path
         variants={bookmarkBody}
-        style={{ originX: "12px", originY: "21px" }}
+        style={pivot(12, 21)}
         fill="currentColor"
         fillOpacity={0}
         d="M17 3a2 2 0 0 1 2 2v15a1 1 0 0 1-1.496.868l-4.512-2.578a2 2 0 0 0-1.984 0l-4.512 2.578A1 1 0 0 1 5 20V5a2 2 0 0 1 2-2z"
@@ -144,14 +144,14 @@ const found: Variants = {
 export function MotionSearch(props: MotionIconProps) {
   return (
     <MotionIcon {...props}>
-      <motion.g variants={lens} style={{ originX: "21px", originY: "21px" }}>
+      <motion.g variants={lens} style={pivot(21, 21)}>
         <circle cx="11" cy="11" r="8" />
         <path d="m21 21-4.34-4.34" />
         {/* Something turns up in the glass on the return stroke. */}
         <motion.circle
           variants={found}
           opacity={0}
-          style={{ originX: "11px", originY: "11px" }}
+          style={pivot(11, 11)}
           fill="currentColor"
           cx="11"
           cy="11"
@@ -309,7 +309,7 @@ const crescent: Variants = {
  * cross-dissolve into visual mush at 20px.
  */
 export function MotionTheme(props: MotionIconProps) {
-  const origin = { originX: "12px", originY: "12px" } as const;
+  const origin = pivot(12, 12);
   return (
     <MotionIcon {...props}>
       <motion.g variants={rays} style={origin}>
@@ -348,7 +348,7 @@ const chevron: Variants = {
 export function MotionChevron(props: MotionIconProps) {
   return (
     <MotionIcon {...props}>
-      <motion.path variants={chevron} style={{ originX: "12px", originY: "12px" }} d="m6 9 6 6 6-6" />
+      <motion.path variants={chevron} style={pivot(12, 12)} d="m6 9 6 6 6-6" />
     </MotionIcon>
   );
 }
@@ -386,7 +386,7 @@ const barLeft = pauseBar(5);
 const barRight = pauseBar(-5);
 
 export function MotionPlayPause(props: MotionIconProps) {
-  const origin = { originX: "12px", originY: "12px" } as const;
+  const origin = pivot(12, 12);
   return (
     <MotionIcon {...props}>
       <motion.path
@@ -433,7 +433,7 @@ const slash: Variants = {
 };
 
 export function MotionEye(props: MotionIconProps) {
-  const origin = { originX: "12px", originY: "12px" } as const;
+  const origin = pivot(12, 12);
   return (
     <MotionIcon {...props}>
       <motion.path
@@ -471,7 +471,7 @@ export function MotionStar(props: MotionIconProps) {
     <MotionIcon {...props}>
       <motion.path
         variants={starBody}
-        style={{ originX: "12px", originY: "12px" }}
+        style={pivot(12, 12)}
         fill="currentColor"
         fillOpacity={0}
         d="M11.525 2.295a.53.53 0 0 1 .95 0l2.31 4.679a2.123 2.123 0 0 0 1.595 1.16l5.166.756a.53.53 0 0 1 .294.904l-3.736 3.638a2.123 2.123 0 0 0-.611 1.878l.882 5.14a.53.53 0 0 1-.771.56l-4.618-2.428a2.122 2.122 0 0 0-1.973 0L6.396 21.01a.53.53 0 0 1-.77-.56l.881-5.139a2.122 2.122 0 0 0-.611-1.879L2.16 9.795a.53.53 0 0 1 .294-.906l5.165-.755a2.122 2.122 0 0 0 1.597-1.16z"
@@ -541,7 +541,7 @@ const refreshRing: Variants = {
 export function MotionRefresh(props: MotionIconProps) {
   return (
     <MotionIcon {...props}>
-      <motion.g variants={refreshRing} style={{ originX: "12px", originY: "12px" }}>
+      <motion.g variants={refreshRing} style={pivot(12, 12)}>
         <path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8" />
         <path d="M21 3v5h-5" />
         <path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16" />

package/src/components/motion-icon-set.tsx

@@ -18,6 +18,7 @@ import { motion, type Variants } from "framer-motion";
 import {
   MotionIcon,
   beats,
+  pivot,
   returnTransition,
   type MotionIconProps,
 } from "./motion-icon";
@@ -54,10 +55,10 @@ export function MotionHouse(props: MotionIconProps) {
     <MotionIcon {...props}>
       <motion.path
         variants={houseRoof}
-        style={{ originX: "12px", originY: "10px" }}
+        style={pivot(12, 10)}
         d="M3 10a2 2 0 0 1 .709-1.528l7-6a2 2 0 0 1 2.582 0l7 6A2 2 0 0 1 21 10"
       />
-      <motion.g variants={houseWalls} style={{ originX: "12px", originY: "21px" }}>
+      <motion.g variants={houseWalls} style={pivot(12, 21)}>
         <path d="M21 10v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V10" />
         <path d="M15 21v-8a1 1 0 0 0-1-1h-4a1 1 0 0 0-1 1v8" />
       </motion.g>
@@ -76,12 +77,20 @@ const UTENSILS_TIMES = [0, 0.18, 0.72, 1];
  */
 const SEPARATION = 5;
 
+/**
+ * The fork is not centred on the crossing: its handle reaches ~13.9 units
+ * below (12,12) and its tines ~10.8 above, so upright it hung ~1.5 units lower
+ * than the knife. `FORK_LIFT` centres it in the uncrossed pose.
+ */
+const FORK_LIFT = -1.5;
+
 const fork: Variants = {
-  rest: { rotate: 0, x: 0, transition: returnTransition },
-  active: { rotate: -44, x: -SEPARATION, transition: returnTransition },
+  rest: { rotate: 0, x: 0, y: 0, transition: returnTransition },
+  active: { rotate: -44, x: -SEPARATION, y: FORK_LIFT, transition: returnTransition },
   play: {
     rotate: [0, 6, -50, -44],
     x: [0, 0.8, -6, -SEPARATION],
+    y: [0, 0, FORK_LIFT - 0.3, FORK_LIFT],
     transition: beats(UTENSILS_TIMES, 0.6),
   },
 };
@@ -96,7 +105,26 @@ const knife: Variants = {
   },
 };
 
-const CROSSING = { originX: "12px", originY: "12px" } as const;
+const CROSSING = pivot(12, 12);
+
+/**
+ * The fork's handle. Lucide leaves a gap between the handle and the neck where
+ * the knife crosses, so the two strokes never form a blob at the crossing. Once
+ * the fork swings clear the gap is just a broken fork, so the handle lengthens
+ * to meet the neck at (12,12) as it uncrosses and shortens again on the way
+ * back. Same command shape both ways, so the `d` tweens.
+ */
+const HANDLE_CROSSED = "M2.1 21.8 8.5 15.4";
+const HANDLE_CLEAR = "M2.1 21.8 12 12";
+
+const forkHandle: Variants = {
+  rest: { d: HANDLE_CROSSED, transition: returnTransition },
+  active: { d: HANDLE_CLEAR, transition: returnTransition },
+  play: {
+    d: [HANDLE_CROSSED, HANDLE_CROSSED, HANDLE_CLEAR, HANDLE_CLEAR],
+    transition: beats(UTENSILS_TIMES, 0.6),
+  },
+};
 
 /**
  * The one gesture that HOLDS: uncrossed is the active pose. ~89° of relative
@@ -113,7 +141,7 @@ export function MotionUtensils(props: MotionIconProps) {
       />
       <motion.g variants={fork} style={CROSSING}>
         <path d="m16 2-2.3 2.3a3 3 0 0 0 0 4.2l1.8 1.8a3 3 0 0 0 4.2 0L22 8" />
-        <path d="m2.1 21.8 6.4-6.3" />
+        <motion.path variants={forkHandle} d={HANDLE_CROSSED} />
         <path d="m19 5-7 7" />
       </motion.g>
     </MotionIcon>
@@ -153,11 +181,11 @@ const pinDot: Variants = {
 export function MotionMapPin(props: MotionIconProps) {
   return (
     <MotionIcon {...props}>
-      <motion.g variants={pinBody} style={{ originX: "12px", originY: "22px" }}>
+      <motion.g variants={pinBody} style={pivot(12, 22)}>
         <path d="M20 10c0 4.993-5.539 10.193-7.399 11.799a1 1 0 0 1-1.202 0C9.539 20.193 4 14.993 4 10a8 8 0 0 1 16 0" />
         <motion.circle
           variants={pinDot}
-          style={{ originX: "12px", originY: "10px" }}
+          style={pivot(12, 10)}
           fill="currentColor"
           fillOpacity={0}
           cx="12"

package/src/components/motion-icon.test.tsx

@@ -2,7 +2,7 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 import { render } from "@testing-library/react";
 import * as React from "react";
 
-import { MotionIcon } from "./motion-icon";
+import { MotionIcon, pivot } from "./motion-icon";
 
 /**
  * The primitive drives its gesture through animation controls rather than a
@@ -157,3 +157,25 @@ describe("MotionIcon", () => {
     expect(variantsStarted).toEqual(["play"]);
   });
 });
+
+/**
+ * Framer Motion puts `transform-box: fill-box` on every SVG element it
+ * transforms, so a pixel origin is read against that element's OWN bounding
+ * box, not the icon's viewBox. The chevron's box starts at (6, 9); "12px 12px"
+ * therefore meant (18, 21) and the arrow slid sideways as it flipped. The
+ * helper's whole job is the one property that makes viewBox pixels mean what
+ * they say — and nothing errors if it goes missing, so it is pinned here.
+ */
+describe("pivot", () => {
+  it("anchors the origin to the viewBox, not the part's own box", () => {
+    expect(pivot(12, 12)).toEqual({
+      originX: "12px",
+      originY: "12px",
+      transformBox: "view-box",
+    });
+  });
+
+  it("carries a pivot that is deliberately off the part, like a pin's tip", () => {
+    expect(pivot(12, 22)).toMatchObject({ originY: "22px", transformBox: "view-box" });
+  });
+});

package/src/components/motion-icon.tsx

@@ -62,6 +62,26 @@ export function beats(times: number[], duration = 0.62): Transition {
 /** Leaving is not a performance — it returns the glyph, firmly and fast. */
 export const returnTransition: Transition = { type: "spring", stiffness: 320, damping: 26 };
 
+/**
+ * A moving part's pivot, in the icon's 24-unit VIEWBOX coordinates.
+ *
+ * Every part in this family wrote `style={{ originX: "12px", originY: "12px" }}`
+ * meaning "the centre of the icon" — and every one of them was pivoting
+ * somewhere else. Framer Motion sets `transform-box: fill-box` on any SVG
+ * element it transforms, which makes `transform-origin` relative to that
+ * element's OWN bounding box, not the viewBox. The chevron `m6 9 6 6 6-6` has
+ * its box at (6, 9), so "12px 12px" resolved to user-space (18, 21): a 180°
+ * flip around a point outside the arrow, which is why it visibly slid as it
+ * turned. A house's walls pivoting at its floor, a pin at its tip, a lens at
+ * its centre — all of them missed by the same offset for the same reason.
+ *
+ * `transform-box: view-box` is the single switch that makes px origins mean
+ * what they say. Declared once here so the next icon cannot get it wrong.
+ */
+export function pivot(x: number, y: number) {
+  return { originX: `${x}px`, originY: `${y}px`, transformBox: "view-box" } as const;
+}
+
 type PoseValues = Record<string, number>;
 
 /**