@tribepad/themis 1.0.19 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribepad/themis",
-  "version": "1.0.19",
+  "version": "1.1.0",
   "description": "Accessible React component library built on React Aria primitives",
   "author": "Tribepad <mbasford@tribepad.com>",
   "license": "MIT",
@@ -245,6 +245,11 @@
       "name": "TextField only",
       "path": "dist/elements/TextField/index.mjs",
       "limit": "30 KB"
+    },
+    {
+      "name": "Sidebar only",
+      "path": "dist/elements/Sidebar/index.mjs",
+      "limit": "35 KB"
     }
   ],
   "keywords": [

package/src/elements/Sidebar/Sidebar.stories.tsx

@@ -0,0 +1,514 @@
+import { useState, type ReactElement } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Home,
+  Inbox,
+  Calendar,
+  Users,
+  FileText,
+  Settings,
+  BarChart3,
+  MessageSquare,
+  Star,
+  HelpCircle,
+  Menu,
+} from 'lucide-react';
+import { Sidebar } from './SidebarCompound';
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '../Accordion';
+import type { SidebarRailVariant } from './Sidebar.types';
+
+const meta = {
+  title: 'Elements/Sidebar',
+  component: Sidebar,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'WCAG 2.2 AAA compliant sidebar navigation with slim icon rail, optional collapsible context panel, and hover/focus popovers. Built on React Aria Toolbar for keyboard navigation.',
+      },
+    },
+  },
+} satisfies Meta<typeof Sidebar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function PanelContentForItem({ id }: { id: string }): ReactElement {
+  const title = id.charAt(0).toUpperCase() + id.slice(1);
+  return (
+    <>
+      <Sidebar.PanelHeader title={title} />
+      <div className="p-3 text-sm text-[var(--content-foreground)]">
+        <p>Content for {id}.</p>
+        <p className="mt-2 text-[var(--muted-foreground)]">
+          This panel shows contextual information for the selected navigation item.
+        </p>
+      </div>
+    </>
+  );
+}
+
+const NAV_ITEMS = [
+  { id: 'home', icon: <Home />, label: 'Home' },
+  { id: 'inbox', icon: <Inbox />, label: 'Inbox' },
+  { id: 'calendar', icon: <Calendar />, label: 'Planner' },
+  { id: 'teams', icon: <Users />, label: 'Teams' },
+  { id: 'docs', icon: <FileText />, label: 'Docs' },
+  { id: 'analytics', icon: <BarChart3 />, label: 'Analytics' },
+] as const;
+
+const BADGE_COUNTS: Record<string, number> = {
+  home: 3,
+  inbox: 14,
+  analytics: 150,
+};
+
+function SidebarDemo({
+  defaultCollapsed = false,
+  showPanel = true,
+  showPopovers = false,
+  showBadges = false,
+  railVariant = 'default' as SidebarRailVariant,
+}: {
+  defaultCollapsed?: boolean;
+  showPanel?: boolean;
+  showPopovers?: boolean;
+  showBadges?: boolean;
+  railVariant?: SidebarRailVariant;
+}): ReactElement {
+  const [activeId, setActiveId] = useState('home');
+
+  return (
+    <div className="flex h-screen bg-[var(--page-background)]">
+      <Sidebar defaultCollapsed={defaultCollapsed}>
+        <Sidebar.Rail aria-label="Main navigation" variant={railVariant}>
+          {showPanel && <Sidebar.CollapseButton />}
+          {NAV_ITEMS.map((item) => (
+            <Sidebar.RailItem
+              key={item.id}
+              id={item.id}
+              icon={item.icon}
+              label={item.label}
+              isActive={activeId === item.id}
+              onPress={() => setActiveId(item.id)}
+              badgeCount={showBadges ? BADGE_COUNTS[item.id] : undefined}
+            >
+              {showPopovers && (
+                <Sidebar.Popover>
+                  <PanelContentForItem id={item.id} />
+                </Sidebar.Popover>
+              )}
+            </Sidebar.RailItem>
+          ))}
+        </Sidebar.Rail>
+        {showPanel && (
+          <Sidebar.Panel width="md" aria-label={`${activeId} details`}>
+            <PanelContentForItem id={activeId} />
+          </Sidebar.Panel>
+        )}
+      </Sidebar>
+      <main className="flex-1 p-6">
+        <h1 className="text-2xl font-bold text-[var(--page-foreground)]">
+          {activeId.charAt(0).toUpperCase() + activeId.slice(1)}
+        </h1>
+        <p className="mt-2 text-[var(--muted-foreground)]">Main content area</p>
+      </main>
+    </div>
+  );
+}
+
+// =============================================================================
+// Stories
+// =============================================================================
+
+/** Default sidebar with rail and context panel */
+export const Default: Story = {
+  render: () => <SidebarDemo />,
+};
+
+/** Rail without a context panel */
+export const RailOnly: Story = {
+  render: () => <SidebarDemo showPanel={false} />,
+};
+
+/** Panel starts in collapsed state */
+export const CollapsedPanel: Story = {
+  render: () => <SidebarDemo defaultCollapsed />,
+};
+
+/** Rail items with hover popover content — hover a non-active item to preview its panel content */
+export const WithPopovers: Story = {
+  render: () => <SidebarDemo showPopovers />,
+};
+
+/** Badge counts on rail items (including 99+ cap) */
+export const WithBadges: Story = {
+  render: () => <SidebarDemo showBadges />,
+};
+
+/** Rail items that navigate via href */
+export const LinkItems: Story = {
+  render: () => (
+    <div className="flex h-screen bg-[var(--page-background)]">
+      <Sidebar>
+        <Sidebar.Rail aria-label="Main navigation">
+          <Sidebar.RailItem id="home" icon={<Home />} label="Home" href="/" isActive />
+          <Sidebar.RailItem id="docs" icon={<FileText />} label="Docs" href="/docs" />
+          <Sidebar.RailItem id="help" icon={<HelpCircle />} label="Help" href="/help" />
+        </Sidebar.Rail>
+      </Sidebar>
+      <main className="flex-1 p-6">
+        <p className="text-[var(--page-foreground)]">These rail items render as links with href attributes.</p>
+      </main>
+    </div>
+  ),
+};
+
+/** Default rail variant */
+export const DefaultRail: Story = {
+  render: () => <SidebarDemo showPopovers railVariant="default" />,
+};
+
+/** Primary rail variant — uses primary action brand colour as background */
+export const PrimaryRail: Story = {
+  render: () => <SidebarDemo showPopovers railVariant="primary" />,
+};
+
+/** Both variants side by side for comparison */
+export const RailVariantComparison: Story = {
+  render: () => {
+    const [variant, setVariant] = useState<SidebarRailVariant>('default');
+
+    return (
+      <div className="flex flex-col h-screen bg-[var(--page-background)]">
+        <div className="p-2 border-b border-[var(--border)] flex gap-2">
+          <button
+            type="button"
+            onClick={() => setVariant('default')}
+            className={`px-3 py-1 text-sm rounded ${
+              variant === 'default'
+                ? 'bg-[var(--primary-action)] text-[var(--primary-action-foreground)]'
+                : 'bg-[var(--secondary)] text-[var(--secondary-foreground)]'
+            }`}
+          >
+            Default
+          </button>
+          <button
+            type="button"
+            onClick={() => setVariant('primary')}
+            className={`px-3 py-1 text-sm rounded ${
+              variant === 'primary'
+                ? 'bg-[var(--primary-action)] text-[var(--primary-action-foreground)]'
+                : 'bg-[var(--secondary)] text-[var(--secondary-foreground)]'
+            }`}
+          >
+            Primary
+          </button>
+        </div>
+        <div className="flex-1 overflow-hidden">
+          <SidebarDemo showPopovers railVariant={variant} />
+        </div>
+      </div>
+    );
+  },
+};
+
+/**
+ * Mobile drawer — uses a high mobileBreakpoint to force mobile mode.
+ * Click the hamburger button to open the drawer.
+ */
+export const MobileDrawer: Story = {
+  render: () => {
+    const [mobileOpen, setMobileOpen] = useState(false);
+    const [activeId, setActiveId] = useState('home');
+
+    return (
+      <div className="flex flex-col h-screen bg-[var(--page-background)]">
+        {/* Top bar with hamburger */}
+        <header className="flex items-center gap-3 px-4 py-2 border-b border-[var(--border)] bg-[var(--content-background)]">
+          <button
+            type="button"
+            onClick={() => setMobileOpen(true)}
+            className="inline-flex items-center justify-center min-h-[44px] min-w-[44px] rounded-[var(--radius-md)] hover:bg-[var(--accent)] text-[var(--content-foreground)]"
+            aria-label="Open navigation"
+          >
+            <Menu className="size-5" />
+          </button>
+          <h1 className="text-lg font-semibold text-[var(--content-foreground)]">My App</h1>
+        </header>
+
+        {/* Sidebar with forced mobile mode (breakpoint set very high) */}
+        <Sidebar
+          mobileBreakpoint={99999}
+          isMobileOpen={mobileOpen}
+          onMobileOpenChange={setMobileOpen}
+        >
+          <Sidebar.Rail aria-label="Main navigation">
+            {NAV_ITEMS.map((item) => (
+              <Sidebar.RailItem
+                key={item.id}
+                id={item.id}
+                icon={item.icon}
+                label={item.label}
+                isActive={activeId === item.id}
+                badgeCount={BADGE_COUNTS[item.id]}
+                onPress={() => {
+                  setActiveId(item.id);
+                }}
+              />
+            ))}
+          </Sidebar.Rail>
+          <Sidebar.Panel width="md" aria-label={`${activeId} details`}>
+            <PanelContentForItem id={activeId} />
+          </Sidebar.Panel>
+        </Sidebar>
+
+        {/* Main content */}
+        <main className="flex-1 p-6">
+          <h2 className="text-2xl font-bold text-[var(--page-foreground)]">
+            {activeId.charAt(0).toUpperCase() + activeId.slice(1)}
+          </h2>
+          <p className="mt-2 text-[var(--muted-foreground)]">
+            This story forces mobile mode by setting mobileBreakpoint to 99999px.
+            Click the hamburger menu to open the navigation drawer.
+          </p>
+        </main>
+      </div>
+    );
+  },
+};
+
+/** Mobile drawer with primary rail variant */
+export const MobileDrawerPrimary: Story = {
+  render: () => {
+    const [mobileOpen, setMobileOpen] = useState(false);
+    const [activeId, setActiveId] = useState('home');
+
+    return (
+      <div className="flex flex-col h-screen bg-[var(--page-background)]">
+        <header className="flex items-center gap-3 px-4 py-2 border-b border-[var(--border)] bg-[var(--content-background)]">
+          <button
+            type="button"
+            onClick={() => setMobileOpen(true)}
+            className="inline-flex items-center justify-center min-h-[44px] min-w-[44px] rounded-[var(--radius-md)] hover:bg-[var(--accent)] text-[var(--content-foreground)]"
+            aria-label="Open navigation"
+          >
+            <Menu className="size-5" />
+          </button>
+          <h1 className="text-lg font-semibold text-[var(--content-foreground)]">My App (Primary)</h1>
+        </header>
+
+        <Sidebar
+          mobileBreakpoint={99999}
+          isMobileOpen={mobileOpen}
+          onMobileOpenChange={setMobileOpen}
+        >
+          <Sidebar.Rail aria-label="Main navigation" variant="primary">
+            {NAV_ITEMS.map((item) => (
+              <Sidebar.RailItem
+                key={item.id}
+                id={item.id}
+                icon={item.icon}
+                label={item.label}
+                isActive={activeId === item.id}
+                badgeCount={BADGE_COUNTS[item.id]}
+                onPress={() => {
+                  setActiveId(item.id);
+                }}
+              />
+            ))}
+          </Sidebar.Rail>
+          <Sidebar.Panel width="md" aria-label={`${activeId} details`}>
+            <PanelContentForItem id={activeId} />
+          </Sidebar.Panel>
+        </Sidebar>
+
+        <main className="flex-1 p-6">
+          <h2 className="text-2xl font-bold text-[var(--page-foreground)]">
+            {activeId.charAt(0).toUpperCase() + activeId.slice(1)}
+          </h2>
+          <p className="mt-2 text-[var(--muted-foreground)]">
+            Mobile drawer with primary rail variant.
+          </p>
+        </main>
+      </div>
+    );
+  },
+};
+
+/** Panel using Accordion for collapsible sections */
+export const WithAccordionPanel: Story = {
+  render: () => {
+    const [activeId, setActiveId] = useState('inbox');
+
+    return (
+      <div className="flex h-screen bg-[var(--page-background)]">
+        <Sidebar>
+          <Sidebar.Rail aria-label="Main navigation">
+            <Sidebar.CollapseButton />
+            <Sidebar.RailItem
+              id="inbox"
+              icon={<Inbox />}
+              label="Inbox"
+              isActive={activeId === 'inbox'}
+              onPress={() => setActiveId('inbox')}
+            />
+            <Sidebar.RailItem
+              id="teams"
+              icon={<Users />}
+              label="Teams"
+              isActive={activeId === 'teams'}
+              onPress={() => setActiveId('teams')}
+            />
+          </Sidebar.Rail>
+          <Sidebar.Panel width="lg" aria-label="Inbox sections">
+            <Sidebar.PanelHeader title="Inbox" />
+            <div className="overflow-y-auto flex-1 p-3">
+              <Accordion type="multiple" defaultExpandedKeys={['favorites']}>
+                <AccordionItem id="favorites">
+                  <AccordionTrigger>Favorites</AccordionTrigger>
+                  <AccordionContent>
+                    <ul className="space-y-1 px-3 py-2 text-sm">
+                      <li className="flex items-center gap-2"><Star className="size-4" /> Project Alpha</li>
+                      <li className="flex items-center gap-2"><Star className="size-4" /> Project Beta</li>
+                    </ul>
+                  </AccordionContent>
+                </AccordionItem>
+                <AccordionItem id="channels">
+                  <AccordionTrigger>Channels</AccordionTrigger>
+                  <AccordionContent>
+                    <ul className="space-y-1 px-3 py-2 text-sm">
+                      <li className="flex items-center gap-2"><MessageSquare className="size-4" /> General</li>
+                      <li className="flex items-center gap-2"><MessageSquare className="size-4" /> Engineering</li>
+                    </ul>
+                  </AccordionContent>
+                </AccordionItem>
+                <AccordionItem id="dms">
+                  <AccordionTrigger>Direct Messages</AccordionTrigger>
+                  <AccordionContent>
+                    <ul className="space-y-1 px-3 py-2 text-sm">
+                      <li className="flex items-center gap-2"><Users className="size-4" /> Alice</li>
+                      <li className="flex items-center gap-2"><Users className="size-4" /> Bob</li>
+                    </ul>
+                  </AccordionContent>
+                </AccordionItem>
+              </Accordion>
+            </div>
+          </Sidebar.Panel>
+        </Sidebar>
+        <main className="flex-1 p-6">
+          <h1 className="text-2xl font-bold text-[var(--page-foreground)]">Inbox</h1>
+        </main>
+      </div>
+    );
+  },
+};
+
+/** Controlled collapse and mobile state with external buttons */
+export const Controlled: Story = {
+  render: () => {
+    const [collapsed, setCollapsed] = useState(false);
+
+    return (
+      <div className="flex flex-col h-screen bg-[var(--page-background)]">
+        <div className="p-2 border-b border-[var(--border)] flex gap-2">
+          <button
+            type="button"
+            onClick={() => setCollapsed(!collapsed)}
+            className="px-3 py-1 text-sm rounded bg-[var(--primary-action)] text-[var(--primary-action-foreground)]"
+          >
+            {collapsed ? 'Expand Panel' : 'Collapse Panel'}
+          </button>
+        </div>
+        <div className="flex flex-1 overflow-hidden">
+          <Sidebar isCollapsed={collapsed} onCollapsedChange={setCollapsed}>
+            <Sidebar.Rail aria-label="Main navigation">
+              <Sidebar.CollapseButton />
+              <Sidebar.RailItem id="home" icon={<Home />} label="Home" isActive onPress={() => {}} />
+              <Sidebar.RailItem id="settings" icon={<Settings />} label="Settings" onPress={() => {}} />
+            </Sidebar.Rail>
+            <Sidebar.Panel width="md" aria-label="Details">
+              <Sidebar.PanelHeader title="Home" />
+              <div className="p-3 text-sm">Panel content here</div>
+            </Sidebar.Panel>
+          </Sidebar>
+          <main className="flex-1 p-6">
+            <p className="text-[var(--page-foreground)]">
+              Panel is {collapsed ? 'collapsed' : 'expanded'}
+            </p>
+          </main>
+        </div>
+      </div>
+    );
+  },
+};
+
+/** All panel width variants */
+export const AllWidths: Story = {
+  render: () => {
+    const [width, setWidth] = useState<'sm' | 'md' | 'lg' | 'xl'>('md');
+
+    return (
+      <div className="flex flex-col h-screen bg-[var(--page-background)]">
+        <div className="p-2 border-b border-[var(--border)] flex gap-2">
+          {(['sm', 'md', 'lg', 'xl'] as const).map((w) => (
+            <button
+              key={w}
+              type="button"
+              onClick={() => setWidth(w)}
+              className={`px-3 py-1 text-sm rounded ${
+                width === w
+                  ? 'bg-[var(--primary-action)] text-[var(--primary-action-foreground)]'
+                  : 'bg-[var(--secondary)] text-[var(--secondary-foreground)]'
+              }`}
+            >
+              {w}
+            </button>
+          ))}
+        </div>
+        <div className="flex flex-1 overflow-hidden">
+          <Sidebar>
+            <Sidebar.Rail aria-label="Main navigation">
+              <Sidebar.CollapseButton />
+              <Sidebar.RailItem id="home" icon={<Home />} label="Home" isActive onPress={() => {}} />
+            </Sidebar.Rail>
+            <Sidebar.Panel width={width} aria-label="Details">
+              <Sidebar.PanelHeader title={`Width: ${width}`} />
+              <div className="p-3 text-sm">
+                Panel width: {width === 'sm' ? '220px' : width === 'md' ? '280px' : width === 'lg' ? '340px' : '420px'}
+              </div>
+            </Sidebar.Panel>
+          </Sidebar>
+          <main className="flex-1 p-6">
+            <p className="text-[var(--page-foreground)]">Main content</p>
+          </main>
+        </div>
+      </div>
+    );
+  },
+};
+
+/** Keyboard navigation demo */
+export const KeyboardNavigation: Story = {
+  render: () => (
+    <div className="flex h-screen bg-[var(--page-background)]">
+      <SidebarDemo showPopovers />
+      <div className="fixed bottom-4 right-4 bg-[var(--content-background)] border border-[var(--border)] rounded-lg p-4 shadow-lg text-sm max-w-xs">
+        <h3 className="font-semibold mb-2 text-[var(--content-foreground)]">Keyboard Shortcuts</h3>
+        <ul className="space-y-1 text-[var(--muted-foreground)]">
+          <li><kbd className="font-mono bg-[var(--muted)] px-1 rounded">Tab</kbd> Enter/exit rail</li>
+          <li><kbd className="font-mono bg-[var(--muted)] px-1 rounded">&uarr;&darr;</kbd> Navigate items</li>
+          <li><kbd className="font-mono bg-[var(--muted)] px-1 rounded">Home/End</kbd> First/last</li>
+          <li><kbd className="font-mono bg-[var(--muted)] px-1 rounded">Enter</kbd> Activate item</li>
+          <li><kbd className="font-mono bg-[var(--muted)] px-1 rounded">Esc</kbd> Close popover</li>
+        </ul>
+      </div>
+    </div>
+  ),
+};