@bearmenu/ui 0.8.3 → 0.8.4

package/src/components/motion-icon.tsx

@@ -0,0 +1,163 @@
+"use client";
+
+/**
+ * MotionIcon — the root for character-animated icons.
+ *
+ * An animated icon performs a behaviour the object it depicts would actually
+ * perform (a roof jumps, utensils uncross, a pin drops and plants) rather than
+ * tweening a property. The rules that make container motion feel right — short
+ * durations, one or two properties, restraint — produce dead icons, so this
+ * primitive is built for the opposite:
+ *
+ *   - Gestures run 400–700ms in five or six beats (anticipation, action, apex,
+ *     impact, settle), which deliberately exceeds the usual UI ceiling. An icon
+ *     gesture is a performance the user chose to trigger, not a transition they
+ *     are waiting through.
+ *   - Amplitudes are 25–40% of the icon box. At a 22px render on a 24-unit grid
+ *     one unit is 0.92px, so anything under ~6 units is physically invisible.
+ *   - The silhouette must change. If the outline is the same shape throughout,
+ *     nothing reads at icon size.
+ *
+ * Three variants, not two:
+ *   rest    — the plain glyph.
+ *   active  — the held pose. Equal to `rest` for gestures that return
+ *             (a roof that lands again); a genuinely different pose for ones
+ *             that stay changed (uncrossed utensils, a filled pin).
+ *   play    — the performance: keyframe arrays that land on `active`.
+ *
+ * `play` is driven by `replayToken`, which callers bump on POINTER DOWN rather
+ * than on the resulting state change. Waiting for state means waiting for
+ * navigation or a network write, which disconnects the gesture from the finger
+ * and reads as dead at any amplitude.
+ */
+
+import * as React from "react";
+import { motion, useAnimationControls, type Transition, type Variants } from "framer-motion";
+
+import { cn } from "../lib/utils";
+
+export type MotionIconProps = {
+  /** The held state. Drives `active` vs `rest`, and the stroke weight. */
+  active?: boolean;
+  /**
+   * Bump on pointer down to perform the gesture. Changing this value replays
+   * `play` even when `active` has not changed, which is what makes the icon
+   * respond to the touch rather than to its consequence.
+   */
+  replayToken?: number;
+  className?: string;
+};
+
+export type MotionIconVariant = "rest" | "active" | "play";
+
+/**
+ * A gesture is a performance with beats, so it is a tween with explicit
+ * `times`. A spring interpolates two keyframes and puts its overshoot at the
+ * end, which cannot express anticipation.
+ */
+export function beats(times: number[], duration = 0.62): Transition {
+  return { duration, times, ease: "easeInOut" };
+}
+
+/** Leaving is not a performance — it returns the glyph, firmly and fast. */
+export const returnTransition: Transition = { type: "spring", stiffness: 320, damping: 26 };
+
+type PoseValues = Record<string, number>;
+
+/**
+ * Builds the three variants for a moving part.
+ * `play` values are keyframe arrays; `rest`/`active` are the two held poses.
+ */
+export function poses(
+  rest: PoseValues,
+  active: PoseValues,
+  play: Record<string, number[]>,
+  transition: Transition
+): Variants {
+  return {
+    rest: { ...rest, transition: returnTransition },
+    active: { ...active, transition: returnTransition },
+    play: { ...play, transition },
+  };
+}
+
+const rootVariants: Variants = {
+  rest: { strokeWidth: 1.75, transition: { duration: 0.18 } },
+  active: { strokeWidth: 2.25, transition: { duration: 0.18 } },
+  play: { strokeWidth: 2.25, transition: { duration: 0.12 } },
+};
+
+/**
+ * Mount poses without playing; pointer down plays; arriving plays unless the
+ * pointer already started it; leaving returns.
+ *
+ * Both effects compare against a ref rather than trusting the dependency array,
+ * so they fire once per actual change and not once per render.
+ */
+export function useIconGesture(active: boolean, replayToken: number) {
+  const controls = useAnimationControls();
+  const lastPlayAt = React.useRef(0);
+  const seenToken = React.useRef(0);
+  // `null` until mounted, so the pose effect can tell a real change from the
+  // first run and never performs the gesture on page load.
+  const seenActive = React.useRef<boolean | null>(null);
+
+  React.useEffect(() => {
+    controls.set(active ? "active" : "rest");
+    seenActive.current = active;
+    // Mount only — the two effects below own everything after that.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  React.useEffect(() => {
+    if (replayToken === seenToken.current) return;
+    seenToken.current = replayToken;
+    lastPlayAt.current = Date.now();
+    void controls.start("play");
+  }, [replayToken, controls]);
+
+  React.useEffect(() => {
+    if (seenActive.current === null || seenActive.current === active) return;
+    seenActive.current = active;
+    if (!active) {
+      void controls.start("rest");
+      return;
+    }
+    // The pointer that caused this state change already started the gesture.
+    if (Date.now() - lastPlayAt.current < 600) return;
+    void controls.start("play");
+  }, [active, controls]);
+
+  return controls;
+}
+
+export function MotionIcon({
+  active = false,
+  replayToken = 0,
+  className,
+  children,
+}: MotionIconProps & { children: React.ReactNode }) {
+  const controls = useIconGesture(active, replayToken);
+
+  return (
+    <motion.svg
+      viewBox="0 0 24 24"
+      // Parts leave the 24-unit box at the apex of a jump. Callers give the
+      // icon padding rather than clipping the gesture.
+      overflow="visible"
+      fill="none"
+      stroke="currentColor"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      variants={rootVariants}
+      // Without this the active icon replays on hydration and every other one
+      // flashes through its pose on first paint.
+      initial={false}
+      animate={controls}
+      className={cn("size-6", className)}
+      aria-hidden
+    >
+      {children}
+    </motion.svg>
+  );
+}

package/src/components/multi-select-combobox.stories.tsx

@@ -10,7 +10,7 @@ const meta = {
 } satisfies Meta<typeof MultiSelectCombobox>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof MultiSelectCombobox>;
 
 const cuisines = [
   { value: "italian", label: "Italian" },

package/src/components/phone-frame.stories.tsx

@@ -11,7 +11,7 @@ const meta = {
 } satisfies Meta<typeof PhoneFrame>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof PhoneFrame>;
 
 export const Default: Story = {
   args: { width: 220 },

package/src/components/rating.stories.tsx

@@ -1,14 +1,14 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Rating } from "./rating";
 
-const meta = {
+const meta: Meta<typeof Rating> = {
   title: "Components/Rating",
   component: Rating,
   tags: ["autodocs"],
-} satisfies Meta<typeof Rating>;
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof Rating>;
 
 export const Default: Story = {
   render: () => <Rating value={4} reviewCount={128} />,

package/src/components/searchable-select.stories.tsx

@@ -10,7 +10,7 @@ const meta = {
 } satisfies Meta<typeof SearchableSelect>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof SearchableSelect>;
 
 const frameworks = [
   { value: "next", label: "Next.js", description: "The React Framework" },

package/src/components/selection-bar.stories.tsx

@@ -9,7 +9,7 @@ const meta = {
 } satisfies Meta<typeof SelectionBar>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof SelectionBar>;
 
 export const Default: Story = {
   render: () => (

package/src/components/skeleton-card.stories.tsx

@@ -1,14 +1,14 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { SkeletonCard } from "./skeleton-card";
 
-const meta = {
+const meta: Meta<typeof SkeletonCard> = {
   title: "Components/SkeletonCard",
   component: SkeletonCard,
   tags: ["autodocs"],
-} satisfies Meta<typeof SkeletonCard>;
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof SkeletonCard>;
 
 export const Experience: Story = {
   render: () => <SkeletonCard variant="experience" className="w-[350px]" />,

package/src/components/sliding-panels.stories.tsx

@@ -10,7 +10,7 @@ const meta = {
 } satisfies Meta<typeof SlidingPanels>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof SlidingPanels>;
 
 function SlidingPanelsDemo() {
   const [currentPanel, setCurrentPanel] = useState("panel-1");

package/src/components/stepper.stories.tsx

@@ -10,7 +10,7 @@ const meta = {
 } satisfies Meta<typeof Stepper>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof Stepper>;
 
 const steps = [
   { id: "account", title: "Account" },

package/src/components/sticky-container.stories.tsx

@@ -1,14 +1,14 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { StickyContainer } from "./sticky-container";
 
-const meta = {
+const meta: Meta<typeof StickyContainer> = {
   title: "Components/StickyContainer",
   component: StickyContainer,
   tags: ["autodocs"],
-} satisfies Meta<typeof StickyContainer>;
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof StickyContainer>;
 
 export const Default: Story = {
   render: () => (

package/src/components/toggle-group.stories.tsx

@@ -9,7 +9,7 @@ const meta = {
 } satisfies Meta<typeof ToggleGroup>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof ToggleGroup>;
 
 export const Default: Story = {
   render: () => (

package/src/components/tooltip.stories.tsx

@@ -3,7 +3,7 @@ import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "./tool
 import { Button } from "./button";
 import { Plus } from "lucide-react";
 
-const meta = {
+const meta: Meta<typeof Tooltip> = {
   title: "Components/Tooltip",
   component: Tooltip,
   tags: ["autodocs"],
@@ -14,7 +14,7 @@ const meta = {
       </TooltipProvider>
     ),
   ],
-} satisfies Meta<typeof Tooltip>;
+};
 
 export default meta;
 type Story = StoryObj<typeof meta>;

package/src/lib/icon-registry.ts

@@ -0,0 +1,139 @@
+/**
+ * The purpose → glyph registry.
+ *
+ * One place recording which glyph means what. Before this existed, ~10 ad-hoc
+ * glyph maps were scattered across the app and the same purpose ended up drawn
+ * two different ways: back as both an arrow and a chevron, "open filters" as
+ * both a funnel and sliders (one surface used both, chosen by which view you
+ * were in), clear and close sharing a bare X.
+ *
+ * Only GENERIC action vocabulary lives here. Product taxonomy — cuisine
+ * shortcuts, facet dimensions, digest categories — stays in the consuming app.
+ *
+ * ## The rules this encodes
+ *
+ * 1. **Arrow leaves, chevron stays.** `ArrowRight` means "you are going to a new
+ *    destination" (see-all links, banner CTAs). `ChevronRight` means "reveal
+ *    more, in place" and is scoped to exactly two jobs: carousel paging and
+ *    row-contained drill-in. Collapsing these is what produced a glyph with
+ *    four meanings.
+ * 2. **Sliders, not a funnel.** A funnel reads as "narrow a list" and collides
+ *    with search and sort iconography at 24px; three sliders read
+ *    unambiguously as "adjust parameters" and carry a badge count cleanly.
+ * 3. **Containment separates clear from close.** A bare `X` leaves a layer. A
+ *    contained `XCircle` resets a value in place without leaving. In a dense
+ *    filter row, bare Xs beside each other cannot say which layer they close.
+ * 4. **Tappable has a container or a colour state; information is muted and
+ *    bare.** This is what disambiguates the overloaded glyphs (`MapPin`,
+ *    `Star`) rather than picking different glyphs for each sense. An
+ *    interactive instance sits in a chip or button and takes an active colour;
+ *    a decorative one is `text-muted-foreground`, `aria-hidden`, outside any
+ *    button, with no hover or active transition.
+ * 5. **Loved and want-to-try are two actions, not one.** `Heart` is
+ *    retrospective ("I have had this and I love it"), `Bookmark` is prospective
+ *    ("I want to try this"). They feed different lists and are mutually
+ *    exclusive per item.
+ */
+
+import {
+  ArrowLeft,
+  ArrowRight,
+  ArrowUpDown,
+  Bookmark,
+  Check,
+  ChevronDown,
+  ChevronLeft,
+  ChevronRight,
+  ExternalLink,
+  Flag,
+  Heart,
+  Info,
+  Navigation,
+  Phone,
+  Plus,
+  RefreshCw,
+  Search,
+  Share2,
+  SlidersHorizontal,
+  Trash2,
+  X,
+  XCircle,
+  type LucideIcon,
+} from "lucide-react";
+
+export type IconPurpose =
+  // navigation
+  | "back"
+  | "seeAll"
+  | "drillIn"
+  | "carouselPrev"
+  | "carouselNext"
+  | "directions"
+  | "externalLink"
+  // layers and values
+  | "close"
+  | "clear"
+  | "expand"
+  // list controls
+  | "filter"
+  | "sort"
+  | "search"
+  // actions
+  | "share"
+  | "favorite"
+  | "wantToTry"
+  | "confirm"
+  | "add"
+  | "remove"
+  | "refresh"
+  | "call"
+  | "report"
+  | "info";
+
+export const iconFor: Record<IconPurpose, LucideIcon> = {
+  back: ArrowLeft,
+  seeAll: ArrowRight,
+  drillIn: ChevronRight,
+  carouselPrev: ChevronLeft,
+  carouselNext: ChevronRight,
+  directions: Navigation,
+  externalLink: ExternalLink,
+
+  close: X,
+  clear: XCircle,
+  expand: ChevronDown,
+
+  filter: SlidersHorizontal,
+  sort: ArrowUpDown,
+  search: Search,
+
+  share: Share2,
+  favorite: Heart,
+  wantToTry: Bookmark,
+  confirm: Check,
+  add: Plus,
+  remove: Trash2,
+  refresh: RefreshCw,
+  call: Phone,
+  report: Flag,
+  info: Info,
+};
+
+/**
+ * Purposes whose glyph must rotate to show state, and by how much.
+ * `expand` is the disclosure chevron: pointing down at rest, up when open.
+ */
+export const iconRotation: Partial<Record<IconPurpose, number>> = {
+  expand: 180,
+};
+
+/**
+ * Retired glyphs and what replaced them. Kept so a reviewer can tell a
+ * deliberate choice from a regression, and so lint/codemods have a source.
+ */
+export const retiredIcons = {
+  Filter: "filter → SlidersHorizontal",
+  ChevronRightAsSeeAll: "seeAll → ArrowRight",
+  ChevronLeftAsBack: "back → ArrowLeft",
+  XAsClear: "clear → XCircle",
+} as const;

package/src/test/setup.ts

@@ -1,6 +1,10 @@
 import "@testing-library/jest-dom";
 
-global.ResizeObserver = class ResizeObserver {
+// `globalThis`, not `global`: the latter is a Node-only global, and this
+// project's `lib` is dom / dom.iterable / esnext with no `@types/node`, so it
+// did not typecheck. This file already reaches for `window` below — the test
+// environment is jsdom, and `globalThis` is the spelling that is typed in both.
+globalThis.ResizeObserver = class ResizeObserver {
   observe() {}
   unobserve() {}
   disconnect() {}