@tribepad/themis 1.0.6 → 1.0.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribepad/themis",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Accessible React component library built on React Aria primitives",
   "author": "Tribepad <mbasford@tribepad.com>",
   "license": "MIT",
@@ -50,10 +50,31 @@
       }
     },
     "./styles/defaults.css": "./dist/styles/defaults.css",
+    "./styles/animations.css": "./dist/styles/animations.css",
     "./tailwind-source.css": {
       "style": "./dist/tailwind-source.css",
       "default": "./dist/tailwind-source.css"
     },
+    "./hooks": {
+      "import": {
+        "types": "./dist/hooks/index.d.ts",
+        "default": "./dist/hooks/index.mjs"
+      },
+      "require": {
+        "types": "./dist/hooks/index.d.ts",
+        "default": "./dist/hooks/index.js"
+      }
+    },
+    "./types": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/types/index.mjs"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/types/index.js"
+      }
+    },
     "./utils": {
       "import": {
         "types": "./dist/utils/index.d.ts",
@@ -110,7 +131,8 @@
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "tailwindcss": "^3.4.0 || ^4.0.0",
-    "zod": "^3.0.0 || ^4.0.0"
+    "zod": "^3.0.0 || ^4.0.0",
+    "motion": ">=11.0.0"
   },
   "peerDependenciesMeta": {
     "tailwindcss": {
@@ -121,6 +143,9 @@
     },
     "zod": {
       "optional": true
+    },
+    "motion": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -130,38 +155,39 @@
     "react-aria": "^3.35.0",
     "react-aria-components": "^1.5.0",
     "react-stately": "^3.33.0",
-    "tailwind-merge": "^3.4.0"
+    "tailwind-merge": "^3.5.0"
   },
   "devDependencies": {
-    "@eslint/js": "^9.0.0",
+    "@eslint/js": "^9.39.3",
     "@size-limit/preset-small-lib": "^11.0.0",
-    "@storybook/addon-a11y": "^10.2.8",
-    "@storybook/react-vite": "^10.2.8",
-    "@tailwindcss/vite": "^4.1.18",
+    "@storybook/addon-a11y": "^10.2.10",
+    "@storybook/react-vite": "^10.2.10",
+    "@tailwindcss/vite": "^4.2.0",
     "@testing-library/jest-dom": "^6.0.0",
     "@testing-library/react": "^16.0.0",
     "@testing-library/user-event": "^14.0.0",
-    "@types/node": "^25.2.2",
-    "@types/react": "^19.0.0",
+    "@types/node": "^25.3.5",
+    "@types/react": "^19.2.14",
     "@types/react-dom": "^19.0.0",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
-    "@vitejs/plugin-react": "^5.1.3",
+    "@typescript-eslint/eslint-plugin": "^8.56.1",
+    "@typescript-eslint/parser": "^8.56.1",
+    "@vitejs/plugin-react": "^5.1.4",
     "@vitest/coverage-v8": "^4.0.0",
     "eslint": "^9.0.0",
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "globals": "^17.3.0",
-    "happy-dom": "^20.5.3",
+    "happy-dom": "^20.7.0",
     "jest-axe": "^10.0.0",
-    "jsdom": "^28.0.0",
+    "jsdom": "^28.1.0",
     "lucide-react": ">=0.400.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "size-limit": "^11.0.0",
-    "storybook": "^10.2.8",
+    "storybook": "^10.2.10",
     "tsup": "^8.0.0",
     "tsx": "^4.0.0",
-    "typescript": "^5.6.0",
+    "typescript": "^5.9.3",
+    "motion": "^12.35.0",
     "vitest": "^4.0.18",
     "zod": "^4.3.6"
   },
@@ -187,6 +213,12 @@
       "styles": [
         "dist/styles/index.d.ts"
       ],
+      "hooks": [
+        "dist/hooks/index.d.ts"
+      ],
+      "types": [
+        "dist/types/index.d.ts"
+      ],
       "utils": [
         "dist/utils/index.d.ts"
       ],

package/src/elements/NumberField/NumberField.stories.tsx

@@ -676,3 +676,103 @@ export const Playground: Story = {
     },
   },
 };
+
+// =============================================================================
+// Animation Stories (ADR 020)
+// =============================================================================
+
+/**
+ * Spring animation on stepper press (default behavior when motion.dev is installed).
+ * Click increment/decrement to see the value spring to its target.
+ */
+export const AnimatedStepper: Story = {
+  args: {
+    label: 'Quantity',
+    defaultValue: 5,
+    step: 1,
+    minValue: 0,
+    maxValue: 99,
+    animated: true,
+    description: 'Click stepper buttons to see the spring animation',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Default animated NumberField with spring physics on stepper press. The displayed value springs from the old value to the new one. Direct keyboard input updates instantly.',
+      },
+    },
+  },
+};
+
+/**
+ * Animation disabled — value updates instantly on stepper press.
+ */
+export const NoStepperAnimation: Story = {
+  args: {
+    label: 'Quantity',
+    defaultValue: 5,
+    step: 1,
+    minValue: 0,
+    maxValue: 99,
+    animated: false,
+    description: 'Stepper updates value instantly (no spring)',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'NumberField with `animated={false}`. Stepper press updates the value instantly without spring animation.',
+      },
+    },
+  },
+};
+
+/**
+ * Currency formatting with spring animation.
+ * The animated overlay displays locale-formatted intermediate values.
+ */
+export const AnimatedCurrency: Story = {
+  args: {
+    label: 'Price',
+    defaultValue: 9.99,
+    step: 0.5,
+    minValue: 0,
+    maxValue: 999.99,
+    animated: true,
+    formatOptions: { style: 'currency', currency: 'USD' },
+    description: 'Spring animation with currency formatting',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Currency-formatted NumberField with spring animation. The overlay formats intermediate values with the same Intl.NumberFormat options as the input.',
+      },
+    },
+  },
+};
+
+/**
+ * Custom spring configuration — softer, bouncier animation.
+ */
+export const CustomSpringConfig: Story = {
+  args: {
+    label: 'Score',
+    defaultValue: 50,
+    step: 10,
+    minValue: 0,
+    maxValue: 100,
+    animated: true,
+    springConfig: { stiffness: 150, damping: 10 },
+    description: 'Low stiffness, low damping = more bounce',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Custom `springConfig` with lower stiffness and damping for a more pronounced bounce effect on stepper press.',
+      },
+    },
+  },
+};

package/src/elements/Switch/Switch.stories.tsx

@@ -437,5 +437,65 @@ export const WithAriaLabel: Story = {
   },
 };
 
+// =============================================================================
+// Animation Stories (ADR 020)
+// =============================================================================
+
+/**
+ * Spring bounce animation on toggle (default behavior when motion.dev is installed).
+ * The thumb overshoots slightly before settling, giving a natural feel.
+ */
+export const Animated: Story = {
+  args: {
+    label: 'Spring animation',
+    description: 'Toggle to see the bounce effect',
+    animated: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Default animated switch with spring physics via motion.dev. The thumb bounces when toggled.',
+      },
+    },
+  },
+};
+
+/**
+ * Animation explicitly disabled — thumb slides instantly via CSS.
+ */
+export const NoAnimation: Story = {
+  args: {
+    label: 'No animation',
+    description: 'Instant toggle with no spring',
+    animated: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Switch with `animated={false}`. The thumb translates instantly using CSS, with no spring bounce.',
+      },
+    },
+  },
+};
+
+/**
+ * Custom spring configuration for a slower, bouncier feel.
+ */
+export const CustomSpring: Story = {
+  args: {
+    label: 'Custom spring',
+    description: 'Low stiffness, low damping = more bounce',
+    animated: true,
+    springConfig: { stiffness: 200, damping: 12 },
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Custom `springConfig` with lower stiffness and damping for a softer, bouncier toggle.',
+      },
+    },
+  },
+};
+
 // Import React for controlled example
 import { useState } from 'react';

package/src/elements/Tabs/Tabs.stories.tsx

@@ -26,8 +26,8 @@ const meta = {
   argTypes: {
     variant: {
       control: 'select',
-      options: ['default', 'block'],
-      description: 'Visual variant: underline (default) or block/pill',
+      options: ['default', 'block', 'stepper'],
+      description: 'Visual variant: underline (default), block/pill, or stepper (numbered steps)',
     },
     orientation: {
       control: 'select',
@@ -131,6 +131,235 @@ export const Block: Story = {
   ),
 };
 
+// ============================================================================
+// Stepper Variant Stories
+// ============================================================================
+
+/**
+ * Stepper: Numbered step circles with connecting lines.
+ * Completed steps show a checkmark, the active step is highlighted.
+ */
+export const Stepper: Story = {
+  render: () => (
+    <Tabs variant="stepper" defaultSelectedKey="form" className="w-[600px]">
+      <TabList aria-label="Blueprint setup steps">
+        <Tab id="details">Job Details</Tab>
+        <Tab id="form">Application Form</Tab>
+        <Tab id="statuses">Statuses</Tab>
+        <Tab id="journeys">Journeys</Tab>
+      </TabList>
+      <TabPanel id="details">
+        <div className="p-4">
+          <h3 className="text-lg font-semibold mb-2">Job Details</h3>
+          <p className="text-sm text-[var(--muted-foreground)]">
+            Configure the basic job information and requirements.
+          </p>
+        </div>
+      </TabPanel>
+      <TabPanel id="form">
+        <div className="p-4">
+          <h3 className="text-lg font-semibold mb-2">Application Form</h3>
+          <p className="text-sm text-[var(--muted-foreground)]">
+            Build the candidate application form with fields and sections.
+          </p>
+        </div>
+      </TabPanel>
+      <TabPanel id="statuses">
+        <div className="p-4">
+          <h3 className="text-lg font-semibold mb-2">Statuses</h3>
+          <p className="text-sm text-[var(--muted-foreground)]">
+            Define the status workflow for applications.
+          </p>
+        </div>
+      </TabPanel>
+      <TabPanel id="journeys">
+        <div className="p-4">
+          <h3 className="text-lg font-semibold mb-2">Journeys</h3>
+          <p className="text-sm text-[var(--muted-foreground)]">
+            Configure candidate journeys for each status.
+          </p>
+        </div>
+      </TabPanel>
+    </Tabs>
+  ),
+};
+
+/**
+ * StepperFirstStep: Stepper with the first step active (no completed steps).
+ */
+export const StepperFirstStep: Story = {
+  render: () => (
+    <Tabs variant="stepper" defaultSelectedKey="details" className="w-[600px]">
+      <TabList aria-label="Setup wizard">
+        <Tab id="details">Details</Tab>
+        <Tab id="form">Form</Tab>
+        <Tab id="statuses">Statuses</Tab>
+        <Tab id="journeys">Journeys</Tab>
+      </TabList>
+      <TabPanel id="details">
+        <div className="p-4">
+          <h3 className="text-lg font-semibold mb-2">Step 1: Details</h3>
+          <p className="text-sm text-[var(--muted-foreground)]">
+            First step is active. No completed steps yet.
+          </p>
+        </div>
+      </TabPanel>
+      <TabPanel id="form">
+        <div className="p-4">Step 2 content</div>
+      </TabPanel>
+      <TabPanel id="statuses">
+        <div className="p-4">Step 3 content</div>
+      </TabPanel>
+      <TabPanel id="journeys">
+        <div className="p-4">Step 4 content</div>
+      </TabPanel>
+    </Tabs>
+  ),
+};
+
+/**
+ * StepperLastStep: Stepper with the last step active (all previous completed).
+ */
+export const StepperLastStep: Story = {
+  render: () => (
+    <Tabs variant="stepper" defaultSelectedKey="journeys" className="w-[600px]">
+      <TabList aria-label="Setup wizard">
+        <Tab id="details">Details</Tab>
+        <Tab id="form">Form</Tab>
+        <Tab id="statuses">Statuses</Tab>
+        <Tab id="journeys">Journeys</Tab>
+      </TabList>
+      <TabPanel id="details">
+        <div className="p-4">Step 1 content</div>
+      </TabPanel>
+      <TabPanel id="form">
+        <div className="p-4">Step 2 content</div>
+      </TabPanel>
+      <TabPanel id="statuses">
+        <div className="p-4">Step 3 content</div>
+      </TabPanel>
+      <TabPanel id="journeys">
+        <div className="p-4">
+          <h3 className="text-lg font-semibold mb-2">Step 4: Journeys</h3>
+          <p className="text-sm text-[var(--muted-foreground)]">
+            All previous steps show checkmarks as completed.
+          </p>
+        </div>
+      </TabPanel>
+    </Tabs>
+  ),
+};
+
+/**
+ * StepperControlled: Stepper with external step navigation controls.
+ */
+export const StepperControlled: Story = {
+  render: function StepperControlledDemo() {
+    const steps = ['details', 'form', 'statuses', 'journeys'] as const;
+    const [selected, setSelected] = useState<Key>('details');
+    const currentIndex = steps.indexOf(selected as typeof steps[number]);
+
+    return (
+      <div className="w-[600px]">
+        <Tabs variant="stepper" selectedKey={selected} onSelectionChange={setSelected}>
+          <TabList aria-label="Controlled stepper">
+            <Tab id="details">Details</Tab>
+            <Tab id="form">Form</Tab>
+            <Tab id="statuses">Statuses</Tab>
+            <Tab id="journeys">Journeys</Tab>
+          </TabList>
+          <TabPanel id="details">
+            <div className="p-4">Step 1: Configure details</div>
+          </TabPanel>
+          <TabPanel id="form">
+            <div className="p-4">Step 2: Build the form</div>
+          </TabPanel>
+          <TabPanel id="statuses">
+            <div className="p-4">Step 3: Define statuses</div>
+          </TabPanel>
+          <TabPanel id="journeys">
+            <div className="p-4">Step 4: Set up journeys</div>
+          </TabPanel>
+        </Tabs>
+        <div className="flex justify-between mt-4 px-4">
+          <button
+            onClick={() => currentIndex > 0 && setSelected(steps[currentIndex - 1])}
+            disabled={currentIndex === 0}
+            className="px-4 py-2 text-sm rounded-md bg-[var(--secondary)] text-[var(--secondary-foreground)] disabled:opacity-50"
+          >
+            Previous
+          </button>
+          <button
+            onClick={() => currentIndex < steps.length - 1 && setSelected(steps[currentIndex + 1])}
+            disabled={currentIndex === steps.length - 1}
+            className="px-4 py-2 text-sm rounded-md bg-[var(--primary)] text-[var(--primary-foreground)] disabled:opacity-50"
+          >
+            Next
+          </button>
+        </div>
+      </div>
+    );
+  },
+};
+
+/**
+ * StepperWithDisabledTabs: Stepper with some tabs disabled.
+ */
+export const StepperWithDisabledTabs: Story = {
+  render: () => (
+    <Tabs variant="stepper" defaultSelectedKey="form" disabledKeys={['journeys']} className="w-[600px]">
+      <TabList aria-label="Steps with disabled">
+        <Tab id="details">Details</Tab>
+        <Tab id="form">Form</Tab>
+        <Tab id="statuses">Statuses</Tab>
+        <Tab id="journeys">Journeys</Tab>
+      </TabList>
+      <TabPanel id="details">
+        <div className="p-4">Step 1 content</div>
+      </TabPanel>
+      <TabPanel id="form">
+        <div className="p-4">
+          <h3 className="text-lg font-semibold mb-2">Step 2: Form</h3>
+          <p className="text-sm text-[var(--muted-foreground)]">
+            The &quot;Journeys&quot; step is disabled and cannot be selected.
+          </p>
+        </div>
+      </TabPanel>
+      <TabPanel id="statuses">
+        <div className="p-4">Step 3 content</div>
+      </TabPanel>
+      <TabPanel id="journeys">
+        <div className="p-4">Step 4 content (disabled)</div>
+      </TabPanel>
+    </Tabs>
+  ),
+};
+
+/**
+ * StepperTwoSteps: Minimal stepper with only 2 steps.
+ */
+export const StepperTwoSteps: Story = {
+  render: () => (
+    <Tabs variant="stepper" defaultSelectedKey="review" className="w-[400px]">
+      <TabList aria-label="Two-step process">
+        <Tab id="configure">Configure</Tab>
+        <Tab id="review">Review</Tab>
+      </TabList>
+      <TabPanel id="configure">
+        <div className="p-4">Configuration step content</div>
+      </TabPanel>
+      <TabPanel id="review">
+        <div className="p-4">
+          <h3 className="text-lg font-semibold mb-2">Review</h3>
+          <p className="text-sm text-[var(--muted-foreground)]">
+            The first step shows a checkmark. This is the active step.
+          </p>
+        </div>
+      </TabPanel>
+    </Tabs>
+  ),
+};
+
 // ============================================================================
 // Orientation Stories
 // ============================================================================
@@ -703,3 +932,104 @@ export const Controlled: Story = {
     );
   },
 };
+
+// =============================================================================
+// Animation Stories (ADR 020)
+// =============================================================================
+
+/**
+ * Animated sliding indicator (default behavior when motion.dev is installed).
+ * Click between tabs to see the underline smoothly slide to the selected tab.
+ */
+export const AnimatedIndicator: Story = {
+  render: () => (
+    <Tabs defaultSelectedKey="tab1" animated>
+      <TabList aria-label="Animated indicator demo">
+        <Tab id="tab1">Account</Tab>
+        <Tab id="tab2">Notifications</Tab>
+        <Tab id="tab3">Security</Tab>
+      </TabList>
+      <TabPanel id="tab1">
+        <div className="p-4">Click other tabs to see the indicator slide.</div>
+      </TabPanel>
+      <TabPanel id="tab2">
+        <div className="p-4">Notification preferences.</div>
+      </TabPanel>
+      <TabPanel id="tab3">
+        <div className="p-4">Security settings.</div>
+      </TabPanel>
+    </Tabs>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Default animated tabs with a sliding underline indicator via motion.dev `layoutId`. The indicator smoothly transitions between tabs on selection.',
+      },
+    },
+  },
+};
+
+/**
+ * Animation disabled — indicator jumps instantly between tabs.
+ */
+export const NoIndicatorAnimation: Story = {
+  render: () => (
+    <Tabs defaultSelectedKey="tab1" animated={false}>
+      <TabList aria-label="No animation demo">
+        <Tab id="tab1">Account</Tab>
+        <Tab id="tab2">Notifications</Tab>
+        <Tab id="tab3">Security</Tab>
+      </TabList>
+      <TabPanel id="tab1">
+        <div className="p-4">Indicator jumps instantly (no slide).</div>
+      </TabPanel>
+      <TabPanel id="tab2">
+        <div className="p-4">Notification preferences.</div>
+      </TabPanel>
+      <TabPanel id="tab3">
+        <div className="p-4">Security settings.</div>
+      </TabPanel>
+    </Tabs>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Tabs with `animated={false}`. The indicator appears instantly on the selected tab without sliding.',
+      },
+    },
+  },
+};
+
+/**
+ * Vertical orientation with animated indicator sliding up and down.
+ */
+export const VerticalAnimated: Story = {
+  render: () => (
+    <Tabs defaultSelectedKey="tab1" orientation="vertical" animated>
+      <TabList aria-label="Vertical animated demo">
+        <Tab id="tab1">Profile</Tab>
+        <Tab id="tab2">Settings</Tab>
+        <Tab id="tab3">Billing</Tab>
+      </TabList>
+      <TabPanel id="tab1">
+        <div className="p-4">Vertical tabs with sliding indicator.</div>
+      </TabPanel>
+      <TabPanel id="tab2">
+        <div className="p-4">Settings panel.</div>
+      </TabPanel>
+      <TabPanel id="tab3">
+        <div className="p-4">Billing information.</div>
+      </TabPanel>
+    </Tabs>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Vertical orientation with animated indicator. The indicator slides vertically between tabs using the same `layoutId` approach.',
+      },
+    },
+  },
+};