@tribepad/themis 1.6.12 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribepad/themis",
-  "version": "1.6.12",
+  "version": "1.8.0",
   "description": "Accessible React component library built on React Aria primitives",
   "author": "Tribepad <mbasford@tribepad.com>",
   "license": "MIT",

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

@@ -423,6 +423,69 @@ export const StepperVerticalNonLinear: Story = {
   ),
 };
 
+/**
+ * StepperWithError: a step flagged with `errorDescription` (here, a failed
+ * validation on the Shipping step). The errored circle turns destructive and
+ * swaps its number for an alert icon — taking visual precedence over the
+ * active/completed treatment — and the description appears as a tooltip on
+ * hover or keyboard focus of the tab. The tooltip is WCAG 2.2 AAA-compliant
+ * (React Aria: Escape-dismissible, hoverable, persistent) and the error state
+ * is also announced to screen readers via the tab's `aria-describedby`, so the
+ * information never relies on hover or colour alone.
+ */
+export const StepperWithError: Story = {
+  render: () => (
+    <Tabs variant="stepper" defaultSelectedKey="shipping">
+      <TabList aria-label="Checkout steps">
+        <Tab id="cart">Cart</Tab>
+        <Tab id="shipping" errorDescription="Postcode is invalid">Shipping</Tab>
+        <Tab id="payment">Payment</Tab>
+      </TabList>
+      <TabPanel id="cart">
+        <div className="p-4">Cart — completed.</div>
+      </TabPanel>
+      <TabPanel id="shipping">
+        <div className="p-4">Shipping — fix the highlighted error to continue.</div>
+      </TabPanel>
+      <TabPanel id="payment">
+        <div className="p-4">Payment — upcoming.</div>
+      </TabPanel>
+    </Tabs>
+  ),
+};
+
+/**
+ * StepperVerticalWithError: the same error treatment in the vertical (Wizard)
+ * stepper — destructive circle, alert icon, and a tooltip above the step.
+ */
+export const StepperVerticalWithError: Story = {
+  render: () => (
+    <Tabs
+      variant="stepper"
+      orientation="vertical"
+      defaultSelectedKey="workflow"
+      className="w-[240px]"
+    >
+      <TabList aria-label="Edit blueprint steps">
+        <Tab id="details">Position Details</Tab>
+        <Tab id="workflow" errorDescription="At least one stage is required">
+          Candidate Workflow
+        </Tab>
+        <Tab id="pipeline">Pipeline &amp; Journeys</Tab>
+      </TabList>
+      <TabPanel id="details">
+        <div className="p-4">Position Details — completed.</div>
+      </TabPanel>
+      <TabPanel id="workflow">
+        <div className="p-4">Candidate Workflow — has an error.</div>
+      </TabPanel>
+      <TabPanel id="pipeline">
+        <div className="p-4">Pipeline &amp; Journeys — upcoming.</div>
+      </TabPanel>
+    </Tabs>
+  ),
+};
+
 /**
  * StepperFirstStep: Stepper with the first step active (no completed steps).
  */

package/src/elements/Timeline/Timeline.stories.tsx

@@ -0,0 +1,244 @@
+/**
+ * Timeline Component Storybook Stories
+ *
+ * Covers the six core variants (orientation × marker), the mobile collapse, server-fed
+ * "Show more" pagination, empty/loading states, an activity-log composition, and a
+ * filter-responsiveness pattern.
+ */
+
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useDeferredValue, useState } from 'react';
+import { FileText, MessageSquare, UserCheck, CheckCircle2 } from 'lucide-react';
+import { Timeline } from './Timeline';
+import { Avatar } from '../Avatar';
+import { Badge } from '../Badge';
+
+const meta = {
+  title: 'Elements/Timeline',
+  component: Timeline,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Accessible, chronological feed of events (WCAG 2.2 AAA). Rendered as a semantic ' +
+          '`<ol>`; vertical or horizontal; dot / basic / icon markers. Horizontal collapses to ' +
+          'vertical on narrow containers. Data enters via `<Timeline.Item>` children.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    orientation: {
+      control: 'select',
+      options: ['vertical', 'horizontal'],
+      description: 'Layout direction. Horizontal collapses to vertical on narrow containers.',
+    },
+    marker: {
+      control: 'select',
+      options: ['dot', 'basic', 'icon'],
+      description: 'Marker style for each event.',
+    },
+    titleHeadingLevel: {
+      control: 'select',
+      options: ['p', 'h2', 'h3', 'h4', 'h5', 'h6'],
+      description: 'Heading level for item titles (default `p`).',
+    },
+  },
+} satisfies Meta<typeof Timeline>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const SUBTEXT = 'Timeline subtext — usually a longer piece of text for contextualising the timeline event.';
+
+/** A small set of representative events. */
+function basicItems() {
+  return (
+    <>
+      <Timeline.Item date="2025-02-01" title="Application received" description={SUBTEXT} />
+      <Timeline.Item date="2025-03-01" title="Screening" description={SUBTEXT} />
+      <Timeline.Item date="2025-04-01" title="Interview" description={SUBTEXT} />
+      <Timeline.Item date="2025-05-01" title="Offer" description={SUBTEXT} />
+    </>
+  );
+}
+
+export const VerticalDot: Story = {
+  args: { orientation: 'vertical', marker: 'dot', 'aria-label': 'Application history' },
+  render: (args) => <Timeline {...args}>{basicItems()}</Timeline>,
+};
+
+export const VerticalBasic: Story = {
+  args: { orientation: 'vertical', marker: 'basic', 'aria-label': 'Application history' },
+  render: (args) => <Timeline {...args}>{basicItems()}</Timeline>,
+};
+
+export const VerticalIcon: Story = {
+  args: { orientation: 'vertical', marker: 'icon', 'aria-label': 'Application history' },
+  render: (args) => (
+    <Timeline {...args}>
+      <Timeline.Item date="2025-02-01" title="Document uploaded" description={SUBTEXT} icon={<FileText />} />
+      <Timeline.Item date="2025-03-01" title="Message sent" description={SUBTEXT} icon={<MessageSquare />} />
+      <Timeline.Item date="2025-04-01" title="Approved" description={SUBTEXT} icon={<CheckCircle2 />} />
+    </Timeline>
+  ),
+};
+
+export const HorizontalDot: Story = {
+  args: { orientation: 'horizontal', marker: 'dot', 'aria-label': 'Process', collapseBelow: false },
+  render: (args) => <Timeline {...args}>{basicItems()}</Timeline>,
+};
+
+export const HorizontalBasic: Story = {
+  args: { orientation: 'horizontal', marker: 'basic', 'aria-label': 'Process', collapseBelow: false },
+  render: (args) => <Timeline {...args}>{basicItems()}</Timeline>,
+};
+
+export const HorizontalIcon: Story = {
+  args: { orientation: 'horizontal', marker: 'icon', 'aria-label': 'Process', collapseBelow: false },
+  render: (args) => (
+    <Timeline {...args}>
+      <Timeline.Item date="2025-02-01" title="Uploaded" description={SUBTEXT} icon={<FileText />} />
+      <Timeline.Item date="2025-03-01" title="Reviewed" description={SUBTEXT} icon={<UserCheck />} />
+      <Timeline.Item date="2025-04-01" title="Approved" description={SUBTEXT} icon={<CheckCircle2 />} />
+    </Timeline>
+  ),
+};
+
+/** Horizontal timelines collapse to vertical below `collapseBelow` (default 640px). Resize the frame. */
+export const MobileCollapse: Story = {
+  args: { orientation: 'horizontal', marker: 'dot', 'aria-label': 'Process', collapseBelow: 640 },
+  render: (args) => (
+    <div style={{ maxWidth: 420, border: '1px dashed var(--border)', padding: 16 }}>
+      <Timeline {...args}>{basicItems()}</Timeline>
+    </div>
+  ),
+};
+
+/** Date granularity is controlled with `dateFormatOptions` (Intl.DateTimeFormatOptions). */
+export const DateGranularity: Story = {
+  render: () => (
+    <div style={{ display: 'grid', gap: 32 }}>
+      <Timeline aria-label="Month + year" dateFormatOptions={{ year: 'numeric', month: 'long' }}>
+        <Timeline.Item date="2025-04-02T09:30:00" title="Month + year" description="{ year, month: 'long' }" />
+      </Timeline>
+      <Timeline aria-label="Full date" dateFormatOptions={{ dateStyle: 'full' }}>
+        <Timeline.Item date="2025-04-02T09:30:00" title="Full date" description="{ dateStyle: 'full' }" />
+      </Timeline>
+      <Timeline aria-label="Date + time" dateFormatOptions={{ dateStyle: 'medium', timeStyle: 'short' }}>
+        <Timeline.Item date="2025-04-02T09:30:00" title="Date + time" description="{ dateStyle, timeStyle }" />
+      </Timeline>
+    </div>
+  ),
+};
+
+/** Interactive items become links with a 44px target and a visible focus ring. */
+export const InteractiveItems: Story = {
+  render: () => (
+    <Timeline aria-label="Recent activity">
+      <Timeline.Item href="#1" date="2025-04-01" title="Candidate applied" description={SUBTEXT} aria-label="View application" />
+      <Timeline.Item href="#2" date="2025-04-05" title="Recruiter responded" description={SUBTEXT} aria-label="View response" />
+    </Timeline>
+  ),
+};
+
+/** Server-fed pagination via `onLoadMore`/`hasMore`. Focus moves to the first new item on the final load. */
+export const LoadMore: Story = {
+  render: () => {
+    const Demo = () => {
+      const [count, setCount] = useState(3);
+      const [loading, setLoading] = useState(false);
+      const max = 9;
+      const load = () => {
+        setLoading(true);
+        setTimeout(() => {
+          setCount((c) => Math.min(c + 3, max));
+          setLoading(false);
+        }, 600);
+      };
+      return (
+        <Timeline aria-label="Activity" hasMore={count < max} isLoadingMore={loading} onLoadMore={load}>
+          {Array.from({ length: count }, (_, i) => (
+            <Timeline.Item key={i} date={`2025-0${(i % 9) + 1}-01`} title={`Event ${i + 1}`} description={SUBTEXT} />
+          ))}
+        </Timeline>
+      );
+    };
+    return <Demo />;
+  },
+};
+
+/** Zero items render the `emptyState` slot — no orphaned connector rail. */
+export const Empty: Story = {
+  render: () => (
+    <Timeline
+      aria-label="Activity"
+      emptyState={<p style={{ color: 'var(--muted-foreground)' }}>No activity yet.</p>}
+    />
+  ),
+};
+
+/**
+ * Activity-log composition — Timeline ships the 6 core variants; richer item content is
+ * composed via the `icon`/avatar marker and the `children` body slot (no special variant).
+ */
+export const ActivityLogComposition: Story = {
+  render: () => (
+    <Timeline aria-label="Activity log" marker="icon">
+      <Timeline.Item date="2025-04-01T10:00:00" icon={<UserCheck />}>
+        <span className="text-sm">
+          <strong>Jordan Lee</strong> moved the candidate to <Badge>Interview</Badge>
+        </span>
+      </Timeline.Item>
+      <Timeline.Item date="2025-04-01T11:30:00" icon={<MessageSquare />}>
+        <div className="flex items-start gap-2">
+          <Avatar name="Sam Patel" size="sm" />
+          <div className="rounded-md bg-[var(--muted)] p-3 text-sm">
+            “Thanks — looking forward to the interview next week.”
+          </div>
+        </div>
+      </Timeline.Item>
+    </Timeline>
+  ),
+};
+
+/**
+ * Filtering large feeds: keep input responsive by deferring the filtered value
+ * (`useDeferredValue`) so typing isn't blocked by the re-render. Stable item ids keep
+ * reconciliation cheap.
+ */
+export const FilterResponsiveness: Story = {
+  render: () => {
+    const Demo = () => {
+      const ALL = Array.from({ length: 40 }, (_, i) => ({
+        id: `e${i}`,
+        date: `2025-${String((i % 12) + 1).padStart(2, '0')}-01`,
+        title: `Event ${i + 1}`,
+      }));
+      const [query, setQuery] = useState('');
+      const deferred = useDeferredValue(query);
+      const filtered = ALL.filter((e) => e.title.toLowerCase().includes(deferred.toLowerCase()));
+      const isStale = query !== deferred;
+      return (
+        <div style={{ display: 'grid', gap: 12 }}>
+          <input
+            type="search"
+            placeholder="Filter events…"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            style={{ padding: 8, border: '1px solid var(--input-border)', borderRadius: 6 }}
+          />
+          <div style={{ opacity: isStale ? 0.6 : 1, transition: 'opacity 150ms' }}>
+            <Timeline aria-label="Filtered events" marker="dot">
+              {filtered.map((e) => (
+                <Timeline.Item key={e.id} id={e.id} date={e.date} title={e.title} />
+              ))}
+            </Timeline>
+          </div>
+        </div>
+      );
+    };
+    return <Demo />;
+  },
+};