@bearmenu/ui 0.8.2 → 0.8.4

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

@@ -0,0 +1,185 @@
+import * as React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import { MotionHouse, MotionUtensils, MotionMapPin, MotionCalendar } from "./motion-icon-set";
+import {
+  MotionHeart,
+  MotionBookmark,
+  MotionSliders,
+  MotionSearch,
+  MotionShare,
+  MotionSort,
+  MotionCheck,
+  MotionTheme,
+  MotionChevron,
+  MotionPlayPause,
+  MotionEye,
+  MotionStar,
+  MotionCopy,
+  MotionRefresh,
+} from "./motion-icon-controls";
+import type { MotionIconProps } from "./motion-icon";
+
+/**
+ * The gallery is the point of keeping these in the design system.
+ *
+ * A character-animated set has to hold one duration budget and one spring
+ * across every glyph, and that is only checkable with them side by side,
+ * playing together, at the size they actually render. It cannot be judged by
+ * tapping through an app minutes apart.
+ */
+
+type Glyph = { name: string; Icon: React.ComponentType<MotionIconProps>; gesture: string };
+
+const OBJECTS: Glyph[] = [
+  { name: "House", Icon: MotionHouse, gesture: "roof jumps, walls take the impact" },
+  { name: "Utensils", Icon: MotionUtensils, gesture: "uncrosses into a place setting · holds" },
+  { name: "MapPin", Icon: MotionMapPin, gesture: "jumps, fills on the descent · holds" },
+  { name: "Calendar", Icon: MotionCalendar, gesture: "rolls four pages" },
+];
+
+const CONTROLS: Glyph[] = [
+  { name: "Heart", Icon: MotionHeart, gesture: "squashes, then inflates · holds" },
+  { name: "Bookmark", Icon: MotionBookmark, gesture: "lifts, drops, tucks · holds" },
+  { name: "Sliders", Icon: MotionSliders, gesture: "handles travel their tracks · holds" },
+  { name: "Search", Icon: MotionSearch, gesture: "lens sweeps, finds something" },
+  { name: "Share", Icon: MotionShare, gesture: "outer nodes depart and return" },
+  { name: "Sort", Icon: MotionSort, gesture: "arrows trade ends" },
+  { name: "Check", Icon: MotionCheck, gesture: "draws itself on · holds" },
+  { name: "Theme", Icon: MotionTheme, gesture: "rays retract, crescent swings in · holds" },
+  { name: "Chevron", Icon: MotionChevron, gesture: "turns over, tips past, settles · holds" },
+  { name: "PlayPause", Icon: MotionPlayPause, gesture: "triangle folds into two bars · holds" },
+  { name: "Eye", Icon: MotionEye, gesture: "lid narrows, slash draws across · holds" },
+  { name: "Star", Icon: MotionStar, gesture: "pulls in, springs its points out · holds" },
+  { name: "Copy", Icon: MotionCopy, gesture: "sheet peels off, check lands · holds" },
+  { name: "Refresh", Icon: MotionRefresh, gesture: "one full turn, overshoots, settles" },
+];
+
+const ALL = [...OBJECTS, ...CONTROLS];
+
+const meta = {
+  title: "Motion/Animated icons",
+  component: MotionHouse,
+  parameters: { layout: "centered" },
+} satisfies Meta<typeof MotionHouse>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+function Cell({
+  glyph,
+  size,
+  token,
+  active,
+  onPlay,
+}: {
+  glyph: Glyph;
+  size: number;
+  token: number;
+  active: boolean;
+  onPlay: () => void;
+}) {
+  const { name, Icon, gesture } = glyph;
+  return (
+    <button
+      type="button"
+      onPointerDown={onPlay}
+      className="flex w-32 cursor-pointer flex-col items-center gap-2 rounded-xl p-3 text-center hover:bg-muted/60"
+    >
+      <span
+        className={active ? "text-accent" : "text-muted-foreground"}
+        style={{ display: "block", width: size, height: size }}
+      >
+        <Icon active={active} replayToken={token} className="size-full" />
+      </span>
+      <span className="text-xs font-medium text-foreground">{name}</span>
+      <span className="text-[10px] leading-tight text-muted-foreground">{gesture}</span>
+    </button>
+  );
+}
+
+function Gallery({
+  glyphs,
+  size,
+  startAllActive = false,
+}: {
+  glyphs: Glyph[];
+  size: number;
+  startAllActive?: boolean;
+}) {
+  const [tokens, setTokens] = React.useState<number[]>(() => glyphs.map(() => 0));
+  const [activeIdx, setActiveIdx] = React.useState<number | null>(null);
+
+  const play = (i: number) => {
+    setTokens((t) => t.map((v, j) => (j === i ? v + 1 : v)));
+    setActiveIdx((cur) => (cur === i ? null : i));
+  };
+
+  return (
+    <div className="flex flex-col items-center gap-5 p-4">
+      <div className="flex flex-wrap items-start justify-center gap-1">
+        {glyphs.map((g, i) => (
+          <Cell
+            key={g.name}
+            glyph={g}
+            size={size}
+            token={tokens[i]}
+            active={startAllActive || activeIdx === i}
+            onPlay={() => play(i)}
+          />
+        ))}
+      </div>
+      <button
+        type="button"
+        onClick={() => setTokens((t) => t.map((v) => v + 1))}
+        className="rounded-lg border border-border px-4 py-2 text-sm font-medium hover:bg-muted"
+      >
+        Play all together
+      </button>
+    </div>
+  );
+}
+
+/**
+ * Every glyph at once, at the size the mobile tab bar renders. This is the
+ * consistency check: play them together and the set should read as one family.
+ */
+export const Family: Story = {
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <Gallery glyphs={ALL} size={22} />
+      <p className="max-w-xl px-4 text-center text-xs text-muted-foreground">
+        Tap a glyph to select and perform it; tap again to deselect and watch it return.
+        &ldquo;Play all&rdquo; replays every gesture at once — use it to check the set shares one
+        duration budget. Glyphs marked &ldquo;holds&rdquo; keep a changed pose while selected; the
+        rest return to where they started.
+      </p>
+    </div>
+  ),
+};
+
+/** The objects and the controls separately, when tuning one group at a time. */
+export const Objects: Story = { render: () => <Gallery glyphs={OBJECTS} size={28} /> };
+export const Controls: Story = { render: () => <Gallery glyphs={CONTROLS} size={28} /> };
+
+/**
+ * The legibility check. A gesture that reads at 48px and vanishes at 16px has
+ * an amplitude problem, not a timing problem.
+ */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6 p-4">
+      {[16, 22, 32, 48].map((size) => (
+        <div key={size} className="flex flex-col gap-1">
+          <span className="px-4 text-xs font-semibold text-muted-foreground">{size}px</span>
+          <Gallery glyphs={ALL} size={size} />
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+/** Every held pose at once, so the "holds" group can be compared side by side. */
+export const HeldPoses: Story = {
+  render: () => <Gallery glyphs={ALL} size={32} startAllActive />,
+};

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

@@ -0,0 +1,219 @@
+"use client";
+
+/**
+ * The character-animated glyph set.
+ *
+ * Geometry is vendored from lucide (ISC) and kept on its 24-unit grid with the
+ * same 2px round-cap stroke, so these sit beside stock lucide icons without a
+ * visible seam. Vendoring is what lets a path be split (a roof off its walls)
+ * or driven independently, which the packaged components cannot do.
+ *
+ * Each glyph names the object, not the role — a product decides that a house
+ * means "home". See `motion-icon.tsx` for the three-variant model.
+ */
+
+import * as React from "react";
+import { motion, type Variants } from "framer-motion";
+
+import {
+  MotionIcon,
+  beats,
+  returnTransition,
+  type MotionIconProps,
+} from "./motion-icon";
+
+// ─── House — the roof jumps (detach and return) ───────────────────────────────
+
+const HOUSE_TIMES = [0, 0.16, 0.44, 0.72, 1];
+
+const houseRoof: Variants = {
+  rest: { y: 0, scaleY: 1, transition: returnTransition },
+  active: { y: 0, scaleY: 1, transition: returnTransition },
+  play: {
+    // Dips into the walls, launches 9 units clear and stretches, falls, lands
+    // 0.9 low onto walls that compress under it, settles.
+    y: [0, 1.5, -9, 0.9, 0],
+    scaleY: [1, 0.92, 1.06, 0.86, 1],
+    transition: beats(HOUSE_TIMES),
+  },
+};
+
+const houseWalls: Variants = {
+  rest: { scaleY: 1, transition: returnTransition },
+  active: { scaleY: 1, transition: returnTransition },
+  play: { scaleY: [1, 1, 1, 0.9, 1], transition: beats(HOUSE_TIMES) },
+};
+
+/**
+ * Lucide draws roof and walls as one closed path; it is cut at the eaves
+ * (y=10) so the roof can leave. At rest the round caps of the two open paths
+ * overlap and the seam is invisible.
+ */
+export function MotionHouse(props: MotionIconProps) {
+  return (
+    <MotionIcon {...props}>
+      <motion.path
+        variants={houseRoof}
+        style={{ originX: "12px", originY: "10px" }}
+        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" }}>
+        <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>
+    </MotionIcon>
+  );
+}
+
+// ─── Utensils — the X uncrosses into a place setting (articulate) ─────────────
+
+const UTENSILS_TIMES = [0, 0.18, 0.72, 1];
+
+/**
+ * 5 units of separation each way. The fork head is ~6 units across and the
+ * knife blade ~5, so their half-widths alone eat 5.5 units of the gap; at ±3.5
+ * the two silhouettes nearly touch and read as one cluttered shape.
+ */
+const SEPARATION = 5;
+
+const fork: Variants = {
+  rest: { rotate: 0, x: 0, transition: returnTransition },
+  active: { rotate: -44, x: -SEPARATION, transition: returnTransition },
+  play: {
+    rotate: [0, 6, -50, -44],
+    x: [0, 0.8, -6, -SEPARATION],
+    transition: beats(UTENSILS_TIMES, 0.6),
+  },
+};
+
+const knife: Variants = {
+  rest: { rotate: 0, x: 0, transition: returnTransition },
+  active: { rotate: 45, x: SEPARATION, transition: returnTransition },
+  play: {
+    rotate: [0, -6, 51, 45],
+    x: [0, -0.8, 6, SEPARATION],
+    transition: beats(UTENSILS_TIMES, 0.6),
+  },
+};
+
+const CROSSING = { originX: "12px", originY: "12px" } as const;
+
+/**
+ * The one gesture that HOLDS: uncrossed is the active pose. ~89° of relative
+ * separation, so the outline changes completely and the state is readable from
+ * the silhouette alone.
+ */
+export function MotionUtensils(props: MotionIconProps) {
+  return (
+    <MotionIcon {...props}>
+      <motion.path
+        variants={knife}
+        style={CROSSING}
+        d="M15 15 3.3 3.3a4.2 4.2 0 0 0 0 6l7.3 7.3c.7.7 2 .7 2.8 0L15 15Zm0 0 7 7"
+      />
+      <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" />
+        <path d="m19 5-7 7" />
+      </motion.g>
+    </MotionIcon>
+  );
+}
+
+// ─── Map pin — jumps, and fills on the way down (fall and land) ───────────────
+
+const PIN_TIMES = [0, 0.16, 0.44, 0.72, 1];
+
+/** Origin at the tip (12,22) — the pin flexes on its point, it does not slide. */
+const pinBody: Variants = {
+  rest: { y: 0, scaleY: 1, transition: returnTransition },
+  active: { y: 0, scaleY: 1, transition: returnTransition },
+  play: {
+    y: [0, 1.2, -9, 0, 0],
+    scaleY: [1, 0.86, 1.08, 0.84, 1],
+    transition: beats(PIN_TIMES),
+  },
+};
+
+/**
+ * fillOpacity runs 0 → 1 between the apex (0.44) and the landing (0.72), so it
+ * is filling for the whole descent and full at the moment of impact. The fill
+ * is the payoff of the landing, not a decoration beside it.
+ */
+const pinDot: Variants = {
+  rest: { fillOpacity: 0, scale: 1, transition: { duration: 0.18 } },
+  active: { fillOpacity: 1, scale: 1, transition: { duration: 0.18 } },
+  play: {
+    fillOpacity: [0, 0, 0, 1, 1],
+    scale: [1, 1, 1, 1.35, 1],
+    transition: beats(PIN_TIMES),
+  },
+};
+
+export function MotionMapPin(props: MotionIconProps) {
+  return (
+    <MotionIcon {...props}>
+      <motion.g variants={pinBody} style={{ originX: "12px", originY: "22px" }}>
+        <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" }}
+          fill="currentColor"
+          fillOpacity={0}
+          cx="12"
+          cy="10"
+          r="3"
+        />
+      </motion.g>
+    </MotionIcon>
+  );
+}
+
+// ─── Calendar — rolls its pages (cycle content) ───────────────────────────────
+
+/** 4-unit pitch. Rows 1–2 are the visible pose; 3–6 roll in from below. */
+const ROWS = [14, 18, 22, 26, 30, 34];
+const COLS = [8, 12, 16];
+
+const reel: Variants = {
+  rest: { y: 0, transition: returnTransition },
+  active: { y: 0, transition: returnTransition },
+  play: {
+    // Exactly four rows (16 units, ~15px), so arriving rows land where the
+    // departing ones began and the end pose is identical to the rest pose.
+    y: [0, -4, -8, -12, -17, -16],
+    transition: beats([0, 0.18, 0.34, 0.5, 0.85, 1], 0.65),
+  },
+};
+
+/**
+ * Lucide's calendar has no pages — it is a box, a rule and six dots, and
+ * nothing in that geometry can roll. So the day dots become the page content,
+ * clipped to the body interior. The frame and binder rings hold perfectly
+ * still, which is what sells the contents moving.
+ */
+export function MotionCalendar(props: MotionIconProps) {
+  // React's useId contains colons, which are not safe in an SVG id / url(#…).
+  const clipId = `cal-body-${React.useId().replace(/:/g, "")}`;
+
+  return (
+    <MotionIcon {...props}>
+      <defs>
+        <clipPath id={clipId}>
+          <rect x="3.5" y="10.5" width="17" height="11" rx="1.5" />
+        </clipPath>
+      </defs>
+
+      <path d="M8 2v4" />
+      <path d="M16 2v4" />
+      <rect width="18" height="18" x="3" y="4" rx="2" />
+      <path d="M3 10h18" />
+
+      <g clipPath={`url(#${clipId})`}>
+        <motion.g variants={reel}>
+          {ROWS.map((y) => COLS.map((x) => <path key={`${x}-${y}`} d={`M${x} ${y}h.01`} />))}
+        </motion.g>
+      </g>
+    </MotionIcon>
+  );
+}

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

@@ -0,0 +1,159 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render } from "@testing-library/react";
+import * as React from "react";
+
+import { MotionIcon } from "./motion-icon";
+
+/**
+ * The primitive drives its gesture through animation controls rather than a
+ * declarative `animate` value, so the mock records every variant set or
+ * started. These assertions are the contract that keeps the icon from
+ * replaying on every page load or every unrelated re-render — both of which
+ * were real bugs during development.
+ */
+const variantsSet: string[] = [];
+const variantsStarted: string[] = [];
+
+vi.mock("framer-motion", () => ({
+  useAnimationControls: () => ({
+    set: (v: string) => variantsSet.push(v),
+    start: (v: string) => {
+      variantsStarted.push(v);
+      return Promise.resolve();
+    },
+  }),
+  motion: {
+    svg: ({ children }: { children?: React.ReactNode }) => <svg>{children}</svg>,
+    g: ({ children }: { children?: React.ReactNode }) => <g>{children}</g>,
+    path: () => <path />,
+    circle: () => <circle />,
+  },
+}));
+
+beforeEach(() => {
+  variantsSet.length = 0;
+  variantsStarted.length = 0;
+});
+
+describe("MotionIcon", () => {
+  it("poses on mount without performing the gesture", () => {
+    render(
+      <MotionIcon active>
+        <path />
+      </MotionIcon>
+    );
+
+    // Replaying on mount would animate the selected icon on every page load.
+    expect(variantsSet).toEqual(["active"]);
+    expect(variantsStarted).toEqual([]);
+  });
+
+  it("rests on mount when inactive", () => {
+    render(
+      <MotionIcon active={false}>
+        <path />
+      </MotionIcon>
+    );
+
+    expect(variantsSet).toEqual(["rest"]);
+    expect(variantsStarted).toEqual([]);
+  });
+
+  it("performs the gesture when the replay token changes, with `active` untouched", () => {
+    const { rerender } = render(
+      <MotionIcon active={false} replayToken={0}>
+        <path />
+      </MotionIcon>
+    );
+    variantsStarted.length = 0;
+
+    rerender(
+      <MotionIcon active={false} replayToken={1}>
+        <path />
+      </MotionIcon>
+    );
+
+    // This is the whole point of the token: the gesture answers the pointer,
+    // not the state change that the pointer eventually causes.
+    expect(variantsStarted).toEqual(["play"]);
+  });
+
+  it("does not re-fire on a re-render that changes nothing", () => {
+    const { rerender } = render(
+      <MotionIcon active={false} replayToken={1}>
+        <path />
+      </MotionIcon>
+    );
+    variantsStarted.length = 0;
+
+    rerender(
+      <MotionIcon active={false} replayToken={1}>
+        <path />
+      </MotionIcon>
+    );
+    rerender(
+      <MotionIcon active={false} replayToken={1}>
+        <path />
+      </MotionIcon>
+    );
+
+    expect(variantsStarted).toEqual([]);
+  });
+
+  it("returns to rest when it stops being active", () => {
+    const { rerender } = render(
+      <MotionIcon active>
+        <path />
+      </MotionIcon>
+    );
+    variantsStarted.length = 0;
+
+    rerender(
+      <MotionIcon active={false}>
+        <path />
+      </MotionIcon>
+    );
+
+    expect(variantsStarted).toEqual(["rest"]);
+  });
+
+  it("plays when it becomes active without a preceding pointer", () => {
+    const { rerender } = render(
+      <MotionIcon active={false}>
+        <path />
+      </MotionIcon>
+    );
+    variantsStarted.length = 0;
+
+    rerender(
+      <MotionIcon active>
+        <path />
+      </MotionIcon>
+    );
+
+    // Arriving by some route other than tapping this icon still performs it.
+    expect(variantsStarted).toEqual(["play"]);
+  });
+
+  it("does not double-play when the pointer already started the gesture", () => {
+    const { rerender } = render(
+      <MotionIcon active={false} replayToken={0}>
+        <path />
+      </MotionIcon>
+    );
+
+    // Pointer down, then the resulting navigation flips `active` a moment later.
+    rerender(
+      <MotionIcon active={false} replayToken={1}>
+        <path />
+      </MotionIcon>
+    );
+    rerender(
+      <MotionIcon active replayToken={1}>
+        <path />
+      </MotionIcon>
+    );
+
+    expect(variantsStarted).toEqual(["play"]);
+  });
+});