@tribepad/themis 1.0.0

package/src/elements/Tooltip/Tooltip.stories.tsx

@@ -0,0 +1,748 @@
+/**
+ * Tooltip Component Stories
+ * Storybook stories for Tooltip component demonstrating all variants, placements, and states
+ *
+ * @see tooltip-prd.md (Component Requirements)
+ * @see plan.md Phase 4 (Documentation)
+ */
+
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { Tooltip, TooltipTrigger, TooltipContent, TooltipArrow } from './Tooltip';
+import { Button } from '../Button';
+import { Info, HelpCircle, Settings, AlertCircle } from 'lucide-react';
+
+const meta = {
+  title: 'Elements/Tooltip',
+  component: Tooltip,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'Accessible tooltip component with React Aria primitives, CVA variant styling, and WCAG 2.2 AAA compliance (7:1 contrast ratio). Supports configurable placement, delays, arrow indicator, and keyboard accessibility.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    delay: {
+      control: { type: 'number', min: 0, max: 2000 },
+      description: 'Delay before showing tooltip on hover (ms)',
+      table: {
+        defaultValue: { summary: '700' },
+      },
+    },
+    closeDelay: {
+      control: { type: 'number', min: 0, max: 1000 },
+      description: 'Delay before hiding tooltip after mouse leave (ms)',
+      table: {
+        defaultValue: { summary: '300' },
+      },
+    },
+    trigger: {
+      control: 'select',
+      options: ['hover', 'focus'],
+      description: 'Trigger mode',
+      table: {
+        defaultValue: { summary: 'hover' },
+      },
+    },
+    isDisabled: {
+      control: 'boolean',
+      description: 'Disable tooltip without affecting trigger element',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    defaultOpen: {
+      control: 'boolean',
+      description: 'Default open state for uncontrolled mode',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+  },
+} satisfies Meta<typeof Tooltip>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Default story
+export const Default: Story = {
+  render: (args) => (
+    <Tooltip {...args}>
+      <TooltipTrigger>
+        <Button variant="outline">Hover me</Button>
+      </TooltipTrigger>
+      <TooltipContent>
+        This is a tooltip
+      </TooltipContent>
+    </Tooltip>
+  ),
+  args: {
+    delay: 300,
+  },
+};
+
+// Placement stories
+export const PlacementTop: Story = {
+  render: () => (
+    <Tooltip delay={0}>
+      <TooltipTrigger>
+        <Button variant="outline">Top</Button>
+      </TooltipTrigger>
+      <TooltipContent side="top">
+        Tooltip on top
+      </TooltipContent>
+    </Tooltip>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tooltip appears above the trigger element.',
+      },
+    },
+  },
+};
+
+export const PlacementBottom: Story = {
+  render: () => (
+    <Tooltip delay={0}>
+      <TooltipTrigger>
+        <Button variant="outline">Bottom</Button>
+      </TooltipTrigger>
+      <TooltipContent side="bottom">
+        Tooltip on bottom
+      </TooltipContent>
+    </Tooltip>
+  ),
+};
+
+export const PlacementLeft: Story = {
+  render: () => (
+    <Tooltip delay={0}>
+      <TooltipTrigger>
+        <Button variant="outline">Left</Button>
+      </TooltipTrigger>
+      <TooltipContent side="left">
+        Tooltip on left
+      </TooltipContent>
+    </Tooltip>
+  ),
+};
+
+export const PlacementRight: Story = {
+  render: () => (
+    <Tooltip delay={0}>
+      <TooltipTrigger>
+        <Button variant="outline">Right</Button>
+      </TooltipTrigger>
+      <TooltipContent side="right">
+        Tooltip on right
+      </TooltipContent>
+    </Tooltip>
+  ),
+};
+
+export const AllPlacements: Story = {
+  render: () => (
+    <div className="grid grid-cols-3 gap-8 p-16">
+      <div />
+      <Tooltip delay={0} defaultOpen>
+        <TooltipTrigger>
+          <Button variant="outline">Top</Button>
+        </TooltipTrigger>
+        <TooltipContent side="top">Top tooltip</TooltipContent>
+      </Tooltip>
+      <div />
+
+      <Tooltip delay={0} defaultOpen>
+        <TooltipTrigger>
+          <Button variant="outline">Left</Button>
+        </TooltipTrigger>
+        <TooltipContent side="left">Left tooltip</TooltipContent>
+      </Tooltip>
+      <div />
+      <Tooltip delay={0} defaultOpen>
+        <TooltipTrigger>
+          <Button variant="outline">Right</Button>
+        </TooltipTrigger>
+        <TooltipContent side="right">Right tooltip</TooltipContent>
+      </Tooltip>
+
+      <div />
+      <Tooltip delay={0} defaultOpen>
+        <TooltipTrigger>
+          <Button variant="outline">Bottom</Button>
+        </TooltipTrigger>
+        <TooltipContent side="bottom">Bottom tooltip</TooltipContent>
+      </Tooltip>
+      <div />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All four placement options displayed together.',
+      },
+    },
+  },
+};
+
+// Arrow stories
+export const WithArrow: Story = {
+  render: () => (
+    <Tooltip delay={0}>
+      <TooltipTrigger>
+        <Button variant="outline">With Arrow</Button>
+      </TooltipTrigger>
+      <TooltipContent showArrow>
+        Tooltip with arrow indicator
+      </TooltipContent>
+    </Tooltip>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tooltip with arrow pointing to trigger element.',
+      },
+    },
+  },
+};
+
+export const WithoutArrow: Story = {
+  render: () => (
+    <Tooltip delay={0}>
+      <TooltipTrigger>
+        <Button variant="outline">Without Arrow</Button>
+      </TooltipTrigger>
+      <TooltipContent showArrow={false}>
+        Tooltip without arrow (default)
+      </TooltipContent>
+    </Tooltip>
+  ),
+};
+
+export const ArrowPlacements: Story = {
+  render: () => (
+    <div className="grid grid-cols-3 gap-8 p-16">
+      <div />
+      <Tooltip delay={0} defaultOpen>
+        <TooltipTrigger>
+          <Button variant="outline">Top</Button>
+        </TooltipTrigger>
+        <TooltipContent side="top" showArrow>Arrow top</TooltipContent>
+      </Tooltip>
+      <div />
+
+      <Tooltip delay={0} defaultOpen>
+        <TooltipTrigger>
+          <Button variant="outline">Left</Button>
+        </TooltipTrigger>
+        <TooltipContent side="left" showArrow>Arrow left</TooltipContent>
+      </Tooltip>
+      <div />
+      <Tooltip delay={0} defaultOpen>
+        <TooltipTrigger>
+          <Button variant="outline">Right</Button>
+        </TooltipTrigger>
+        <TooltipContent side="right" showArrow>Arrow right</TooltipContent>
+      </Tooltip>
+
+      <div />
+      <Tooltip delay={0} defaultOpen>
+        <TooltipTrigger>
+          <Button variant="outline">Bottom</Button>
+        </TooltipTrigger>
+        <TooltipContent side="bottom" showArrow>Arrow bottom</TooltipContent>
+      </Tooltip>
+      <div />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Arrows automatically rotate based on placement.',
+      },
+    },
+  },
+};
+
+export const CustomArrowSize: Story = {
+  render: () => (
+    <div className="flex gap-8">
+      <Tooltip delay={0}>
+        <TooltipTrigger>
+          <Button variant="outline">Small Arrow (4px)</Button>
+        </TooltipTrigger>
+        <TooltipContent showArrow arrowSize={4}>Small arrow</TooltipContent>
+      </Tooltip>
+      <Tooltip delay={0}>
+        <TooltipTrigger>
+          <Button variant="outline">Default (8px)</Button>
+        </TooltipTrigger>
+        <TooltipContent showArrow arrowSize={8}>Default arrow</TooltipContent>
+      </Tooltip>
+      <Tooltip delay={0}>
+        <TooltipTrigger>
+          <Button variant="outline">Large Arrow (12px)</Button>
+        </TooltipTrigger>
+        <TooltipContent showArrow arrowSize={12}>Large arrow</TooltipContent>
+      </Tooltip>
+    </div>
+  ),
+};
+
+// Delay stories
+export const CustomDelay: Story = {
+  render: () => (
+    <div className="flex gap-4">
+      <Tooltip delay={0}>
+        <TooltipTrigger>
+          <Button variant="outline">Instant (0ms)</Button>
+        </TooltipTrigger>
+        <TooltipContent>No delay</TooltipContent>
+      </Tooltip>
+      <Tooltip delay={700}>
+        <TooltipTrigger>
+          <Button variant="outline">Default (700ms)</Button>
+        </TooltipTrigger>
+        <TooltipContent>Default delay</TooltipContent>
+      </Tooltip>
+      <Tooltip delay={1500}>
+        <TooltipTrigger>
+          <Button variant="outline">Long (1500ms)</Button>
+        </TooltipTrigger>
+        <TooltipContent>Long delay</TooltipContent>
+      </Tooltip>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Different delay values for showing tooltip.',
+      },
+    },
+  },
+};
+
+// Trigger mode stories
+export const FocusTrigger: Story = {
+  render: () => (
+    <Tooltip trigger="focus">
+      <TooltipTrigger>
+        <Button variant="outline">Tab to focus me</Button>
+      </TooltipTrigger>
+      <TooltipContent>
+        Shown only on keyboard focus
+      </TooltipContent>
+    </Tooltip>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Focus-only trigger mode. Tooltip shows on keyboard focus but not hover. Ideal for keyboard-only users.',
+      },
+    },
+  },
+};
+
+// Non-button trigger stories
+export const IconTrigger: Story = {
+  render: () => (
+    <div className="flex items-center gap-2">
+      <span>More information</span>
+      <Tooltip delay={0}>
+        <TooltipTrigger>
+          <span tabIndex={0} className="inline-flex cursor-help" data-testid="icon-trigger">
+            <Info className="h-4 w-4 text-[var(--muted-foreground)]" />
+          </span>
+        </TooltipTrigger>
+        <TooltipContent>
+          This is additional context about the feature.
+        </TooltipContent>
+      </Tooltip>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tooltip triggered by an info icon. Non-button triggers must be focusable (tabIndex=0).',
+      },
+    },
+  },
+};
+
+export const TextTrigger: Story = {
+  render: () => (
+    <p className="max-w-md">
+      The candidate has excellent{' '}
+      <Tooltip delay={0}>
+        <TooltipTrigger>
+          <span tabIndex={0} className="underline decoration-dotted cursor-help" data-testid="text-trigger">
+            technical skills
+          </span>
+        </TooltipTrigger>
+        <TooltipContent>
+          Includes proficiency in React, TypeScript, and Node.js
+        </TooltipContent>
+      </Tooltip>
+      {' '}and strong communication abilities.
+    </p>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tooltip on inline text. Useful for providing definitions or additional context.',
+      },
+    },
+  },
+};
+
+export const ButtonTrigger: Story = {
+  render: () => (
+    <Tooltip delay={0}>
+      <TooltipTrigger>
+        <Button variant="outline" size="icon" aria-label="Settings">
+          <Settings className="h-4 w-4" />
+        </Button>
+      </TooltipTrigger>
+      <TooltipContent>
+        Open settings
+      </TooltipContent>
+    </Tooltip>
+  ),
+};
+
+// Content variants
+export const ShortContent: Story = {
+  render: () => (
+    <Tooltip delay={0}>
+      <TooltipTrigger>
+        <Button variant="outline">Short</Button>
+      </TooltipTrigger>
+      <TooltipContent>Hi!</TooltipContent>
+    </Tooltip>
+  ),
+};
+
+export const LongContent: Story = {
+  render: () => (
+    <Tooltip delay={0}>
+      <TooltipTrigger>
+        <Button variant="outline">Long content</Button>
+      </TooltipTrigger>
+      <TooltipContent className="max-w-xs">
+        This is a longer tooltip with more detailed information that wraps to multiple lines.
+        It provides additional context about the feature or action.
+      </TooltipContent>
+    </Tooltip>
+  ),
+};
+
+export const Multiline: Story = {
+  render: () => (
+    <Tooltip delay={0}>
+      <TooltipTrigger>
+        <Button variant="outline">Multiline</Button>
+      </TooltipTrigger>
+      <TooltipContent className="max-w-xs">
+        <strong>Keyboard Shortcut</strong>
+        <br />
+        Press ⌘S to save
+        <br />
+        Press ⌘Z to undo
+      </TooltipContent>
+    </Tooltip>
+  ),
+};
+
+// Disabled state
+export const Disabled: Story = {
+  render: () => (
+    <Tooltip isDisabled delay={0}>
+      <TooltipTrigger>
+        <Button variant="outline">Tooltip disabled</Button>
+      </TooltipTrigger>
+      <TooltipContent>
+        You won&apos;t see this
+      </TooltipContent>
+    </Tooltip>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tooltip can be disabled while keeping the trigger element interactive.',
+      },
+    },
+  },
+};
+
+// Controlled state
+export const Controlled: Story = {
+  render: function ControlledStory() {
+    const [isOpen, setIsOpen] = React.useState(false);
+    return (
+      <div className="flex flex-col items-center gap-4">
+        <Button onPress={() => setIsOpen(!isOpen)}>
+          Toggle Tooltip: {isOpen ? 'Open' : 'Closed'}
+        </Button>
+        <Tooltip isOpen={isOpen} onOpenChange={setIsOpen}>
+          <TooltipTrigger>
+            <Button variant="outline">Controlled trigger</Button>
+          </TooltipTrigger>
+          <TooltipContent>
+            Controlled tooltip
+          </TooltipContent>
+        </Tooltip>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tooltip state can be controlled externally using isOpen and onOpenChange props.',
+      },
+    },
+  },
+};
+
+// Import React for controlled story
+import * as React from 'react';
+
+// Offset stories
+export const CustomOffset: Story = {
+  render: () => (
+    <div className="flex gap-8">
+      <Tooltip delay={0}>
+        <TooltipTrigger>
+          <Button variant="outline">Default offset (4px)</Button>
+        </TooltipTrigger>
+        <TooltipContent sideOffset={4}>Default offset</TooltipContent>
+      </Tooltip>
+      <Tooltip delay={0}>
+        <TooltipTrigger>
+          <Button variant="outline">Large offset (16px)</Button>
+        </TooltipTrigger>
+        <TooltipContent sideOffset={16}>Large offset</TooltipContent>
+      </Tooltip>
+    </div>
+  ),
+};
+
+// Theme stories
+export const AllThemes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div className="p-4 bg-[var(--background)] text-[var(--foreground)]">
+        <h4 className="mb-2 text-sm font-medium">Current Theme</h4>
+        <Tooltip delay={0} defaultOpen>
+          <TooltipTrigger>
+            <Button variant="outline">Themed tooltip</Button>
+          </TooltipTrigger>
+          <TooltipContent showArrow>
+            Inverted colors for high contrast
+          </TooltipContent>
+        </Tooltip>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tooltip uses inverted foreground/background colors to achieve WCAG 2.2 AAA 7:1 contrast ratio in all themes.',
+      },
+    },
+  },
+};
+
+// Accessibility stories
+export const FocusState: Story = {
+  render: () => (
+    <Tooltip delay={0}>
+      <TooltipTrigger>
+        <Button variant="outline">Tab to me</Button>
+      </TooltipTrigger>
+      <TooltipContent>
+        Appears on focus
+      </TooltipContent>
+    </Tooltip>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Press Tab to focus the button. Tooltip appears on keyboard focus for accessibility.',
+      },
+    },
+  },
+};
+
+export const EscapeToClose: Story = {
+  render: () => (
+    <Tooltip delay={0}>
+      <TooltipTrigger>
+        <Button variant="outline">Hover, then press Escape</Button>
+      </TooltipTrigger>
+      <TooltipContent>
+        Press Escape to dismiss
+      </TooltipContent>
+    </Tooltip>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Hover to show tooltip, then press Escape to dismiss it.',
+      },
+    },
+  },
+};
+
+// Animation story
+export const Animation: Story = {
+  render: () => (
+    <Tooltip delay={0}>
+      <TooltipTrigger>
+        <Button variant="outline">Hover for animation</Button>
+      </TooltipTrigger>
+      <TooltipContent>
+        Smooth fade and slide animation
+      </TooltipContent>
+    </Tooltip>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tooltip has smooth entry/exit animations. Uses motion-safe for users who prefer reduced motion.',
+      },
+    },
+  },
+};
+
+// Edge positioning
+export const EdgePositioning: Story = {
+  render: () => (
+    <div className="flex justify-between w-full p-4">
+      <Tooltip delay={0}>
+        <TooltipTrigger>
+          <Button variant="outline">Left edge</Button>
+        </TooltipTrigger>
+        <TooltipContent side="right">
+          Auto-flips to stay in viewport
+        </TooltipContent>
+      </Tooltip>
+      <Tooltip delay={0}>
+        <TooltipTrigger>
+          <Button variant="outline">Right edge</Button>
+        </TooltipTrigger>
+        <TooltipContent side="left">
+          Auto-flips to stay in viewport
+        </TooltipContent>
+      </Tooltip>
+    </div>
+  ),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        story: 'Tooltip automatically flips placement when constrained by viewport edges.',
+      },
+    },
+  },
+};
+
+// Real-world examples
+export const IconButton: Story = {
+  render: () => (
+    <div className="flex gap-2">
+      <Tooltip delay={300}>
+        <TooltipTrigger>
+          <Button variant="ghost" size="icon" aria-label="Help">
+            <HelpCircle className="h-4 w-4" />
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent>Get help</TooltipContent>
+      </Tooltip>
+      <Tooltip delay={300}>
+        <TooltipTrigger>
+          <Button variant="ghost" size="icon" aria-label="Settings">
+            <Settings className="h-4 w-4" />
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent>Open settings</TooltipContent>
+      </Tooltip>
+      <Tooltip delay={300}>
+        <TooltipTrigger>
+          <Button variant="ghost" size="icon" aria-label="Warnings">
+            <AlertCircle className="h-4 w-4" />
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent>View warnings</TooltipContent>
+      </Tooltip>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tooltips on icon buttons provide essential context for unlabeled buttons.',
+      },
+    },
+  },
+};
+
+export const FormFieldHelp: Story = {
+  render: () => (
+    <div className="w-80">
+      <label className="flex items-center gap-2 text-sm font-medium mb-2">
+        Email Address
+        <Tooltip delay={0}>
+          <TooltipTrigger>
+            <span tabIndex={0} className="inline-flex cursor-help">
+              <Info className="h-4 w-4 text-[var(--muted-foreground)]" />
+            </span>
+          </TooltipTrigger>
+          <TooltipContent className="max-w-xs">
+            We&apos;ll use this email for account notifications and password recovery.
+            Your email will never be shared.
+          </TooltipContent>
+        </Tooltip>
+      </label>
+      <input
+        type="email"
+        placeholder="you@example.com"
+        className="w-full rounded-md border border-[var(--border)] bg-[var(--background)] px-3 py-2"
+      />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Tooltip providing help text for a form field.',
+      },
+    },
+  },
+};
+
+export const ContrastCheck: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <Tooltip delay={0} defaultOpen>
+        <TooltipTrigger>
+          <Button variant="outline">WCAG AAA Contrast</Button>
+        </TooltipTrigger>
+        <TooltipContent>
+          7:1 contrast ratio achieved via inverted colors
+        </TooltipContent>
+      </Tooltip>
+      <p className="text-xs text-[var(--muted-foreground)] max-w-sm">
+        Tooltip uses bg-[var(--foreground)] and text-[var(--background)] to achieve
+        WCAG 2.2 AAA 7:1 contrast ratio in all themes.
+      </p>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Demonstrates the high contrast colors used for WCAG AAA compliance.',
+      },
+    },
+  },
+};