@tribepad/themis 1.0.0

package/src/elements/Card/Card.stories.tsx

@@ -0,0 +1,570 @@
+/**
+ * Card Component - Storybook Stories
+ *
+ * Interactive examples and documentation for the Card component
+ *
+ * @see card-prd.md (Product Requirements)
+ * @see plan.md (Implementation Plan)
+ * @see Storybook (when running)
+ */
+
+import { useState, type ReactElement } from 'react';
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { HelpCircle, Info, X, ArrowLeft } from 'lucide-react';
+import {
+  Card,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardContent,
+  CardFooter,
+  CardAction,
+} from './Card';
+import { Button } from '../Button';
+
+const meta = {
+  title: 'Elements/Card',
+  component: Card,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'A flexible container for grouping related content with composable sub-components. Supports an optional flip animation to reveal additional content on the back side.\n\n**Key Features:**\n- Composable sub-components (Header, Title, Description, Content, Footer, Action)\n- Optional flip animation with CSS 3D transforms\n- Controlled and uncontrolled flip state\n- WCAG 2.2 AAA compliant (all content always accessible)',
+      },
+    },
+  },
+  argTypes: {
+    flippable: {
+      control: 'boolean',
+      description: 'Enable flip animation feature',
+    },
+    flipButtonPosition: {
+      control: 'select',
+      options: ['top-right', 'top-left', 'bottom-right', 'bottom-left'],
+      description: 'Position of the flip button',
+    },
+    flipDuration: {
+      control: 'number',
+      description: 'Duration of flip animation in milliseconds',
+    },
+    defaultFlipped: {
+      control: 'boolean',
+      description: 'Initial flip state (uncontrolled mode)',
+    },
+  },
+} satisfies Meta<typeof Card>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ============================================================================
+// Default Story
+// ============================================================================
+
+/**
+ * Default Card
+ * Basic card with header, content, and footer.
+ */
+export const Default: Story = {
+  render: (): ReactElement => (
+    <Card className="w-[350px]">
+      <CardHeader>
+        <CardTitle>Card Title</CardTitle>
+        <CardDescription>Card description goes here.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p>Card content with any elements you need.</p>
+      </CardContent>
+      <CardFooter>
+        <Button variant="outline">Cancel</Button>
+        <Button className="ml-2">Save</Button>
+      </CardFooter>
+    </Card>
+  ),
+};
+
+// ============================================================================
+// With Header and Footer
+// ============================================================================
+
+/**
+ * Full Card Layout
+ * Card with all sub-components: header, title, description, content, footer, and action.
+ */
+export const FullLayout: Story = {
+  render: (): ReactElement => (
+    <Card className="w-[400px]">
+      <CardHeader>
+        <div className="flex items-start justify-between">
+          <div>
+            <CardTitle>Project Settings</CardTitle>
+            <CardDescription>Manage your project configuration.</CardDescription>
+          </div>
+          <CardAction>
+            <Button variant="ghost" size="sm">Edit</Button>
+          </CardAction>
+        </div>
+      </CardHeader>
+      <CardContent>
+        <div className="space-y-2">
+          <div className="flex justify-between">
+            <span className="text-sm">Project Name</span>
+            <span className="text-sm font-medium">My Project</span>
+          </div>
+          <div className="flex justify-between">
+            <span className="text-sm">Status</span>
+            <span className="text-sm font-medium text-green-600">Active</span>
+          </div>
+          <div className="flex justify-between">
+            <span className="text-sm">Created</span>
+            <span className="text-sm font-medium">Dec 31, 2025</span>
+          </div>
+        </div>
+      </CardContent>
+      <CardFooter className="justify-end gap-2">
+        <Button variant="outline">Cancel</Button>
+        <Button>Save Changes</Button>
+      </CardFooter>
+    </Card>
+  ),
+};
+
+// ============================================================================
+// Flippable Card
+// ============================================================================
+
+/**
+ * Flippable Card
+ * Card with flip animation to reveal back content.
+ */
+export const Flippable: Story = {
+  render: (): ReactElement => (
+    <Card
+      className="w-[350px]"
+      flippable
+      backContent={
+        <div className="p-6">
+          <h3 className="text-lg font-semibold mb-2">Additional Details</h3>
+          <p className="text-sm text-[var(--content-foreground-muted)]">
+            This is the back side of the card. It can contain any content you need,
+            such as detailed information, settings, or related data.
+          </p>
+          <ul className="mt-4 space-y-2 text-sm">
+            <li>Feature 1: Accessible to screen readers</li>
+            <li>Feature 2: Smooth CSS 3D animation</li>
+            <li>Feature 3: Respects reduced motion</li>
+          </ul>
+        </div>
+      }
+    >
+      <CardHeader>
+        <CardTitle>Flippable Card</CardTitle>
+        <CardDescription>Click the flip button to see more.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p>This card has additional content on the back side.</p>
+        <p className="mt-2 text-sm text-[var(--content-foreground-muted)]">
+          The flip button is in the top-right corner.
+        </p>
+      </CardContent>
+    </Card>
+  ),
+};
+
+// ============================================================================
+// Controlled Flippable Card
+// ============================================================================
+
+/**
+ * Controlled Flip State
+ * Card with externally controlled flip state.
+ */
+export const ControlledFlip: Story = {
+  render: function ControlledFlipCard(): ReactElement {
+    const [isFlipped, setIsFlipped] = useState(false);
+
+    return (
+      <div className="space-y-4">
+        <div className="flex gap-2">
+          <Button onClick={() => setIsFlipped(false)} variant={!isFlipped ? 'default' : 'outline'}>
+            Front
+          </Button>
+          <Button onClick={() => setIsFlipped(true)} variant={isFlipped ? 'default' : 'outline'}>
+            Back
+          </Button>
+        </div>
+        <Card
+          className="w-[350px]"
+          flippable
+          isFlipped={isFlipped}
+          onFlipChange={setIsFlipped}
+          backContent={
+            <div className="p-6">
+              <h3 className="text-lg font-semibold">Back Side</h3>
+              <p className="mt-2 text-sm">
+                This flip state is controlled by external buttons.
+              </p>
+            </div>
+          }
+        >
+          <CardHeader>
+            <CardTitle>Controlled Card</CardTitle>
+            <CardDescription>State controlled externally.</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <p>Use the buttons above to flip this card.</p>
+          </CardContent>
+        </Card>
+      </div>
+    );
+  },
+};
+
+// ============================================================================
+// Flip Button Positions
+// ============================================================================
+
+/**
+ * Flip Button Positions
+ * All four flip button positions demonstrated.
+ */
+export const FlipButtonPositions: Story = {
+  render: (): ReactElement => (
+    <div className="grid grid-cols-2 gap-4">
+      {(['top-right', 'top-left', 'bottom-right', 'bottom-left'] as const).map((position) => (
+        <Card
+          key={position}
+          className="w-[200px]"
+          flippable
+          flipButtonPosition={position}
+          backContent={
+            <div className="p-4">
+              <p className="text-sm">Back: {position}</p>
+            </div>
+          }
+        >
+          <CardHeader className="pb-2">
+            <CardTitle className="text-base">{position}</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <p className="text-sm">Flip button position</p>
+          </CardContent>
+        </Card>
+      ))}
+    </div>
+  ),
+};
+
+// ============================================================================
+// Custom Flip Labels
+// ============================================================================
+
+/**
+ * Custom Flip Labels
+ * Card with custom flip button labels.
+ */
+export const CustomFlipLabels: Story = {
+  render: (): ReactElement => (
+    <Card
+      className="w-[350px]"
+      flippable
+      flipButtonLabel={{
+        show: 'View specifications',
+        hide: 'Back to overview',
+      }}
+      backContent={
+        <div className="p-6">
+          <h3 className="text-lg font-semibold mb-2">Specifications</h3>
+          <dl className="space-y-2 text-sm">
+            <div className="flex justify-between">
+              <dt>Dimensions</dt>
+              <dd>10 x 5 x 2 cm</dd>
+            </div>
+            <div className="flex justify-between">
+              <dt>Weight</dt>
+              <dd>150g</dd>
+            </div>
+            <div className="flex justify-between">
+              <dt>Material</dt>
+              <dd>Aluminum</dd>
+            </div>
+          </dl>
+        </div>
+      }
+    >
+      <CardHeader>
+        <CardTitle>Product Card</CardTitle>
+        <CardDescription>Hover over flip button to see custom label.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p>Premium wireless earbuds with active noise cancellation.</p>
+        <p className="mt-2 text-2xl font-bold">$299.00</p>
+      </CardContent>
+      <CardFooter>
+        <Button className="w-full">Add to Cart</Button>
+      </CardFooter>
+    </Card>
+  ),
+};
+
+// ============================================================================
+// Custom Flip Icons
+// ============================================================================
+
+/**
+ * Custom Flip Icons
+ * Card with custom icons for the flip button.
+ */
+export const CustomFlipIcons: Story = {
+  render: (): ReactElement => (
+    <div className="grid grid-cols-2 gap-4">
+      {/* Help/Question Mark Icon */}
+      <Card
+        className="w-[200px]"
+        flippable
+        flipButtonIcon={{
+          front: <HelpCircle className="h-5 w-5" aria-hidden="true" />,
+          back: <X className="h-5 w-5" aria-hidden="true" />,
+        }}
+        flipButtonLabel={{
+          show: 'Show help',
+          hide: 'Close help',
+        }}
+        backContent={
+          <div className="p-4">
+            <h3 className="font-semibold mb-2">Help</h3>
+            <p className="text-sm">This is helpful information about the feature.</p>
+          </div>
+        }
+      >
+        <CardHeader className="pb-2">
+          <CardTitle className="text-base">Help Icon</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <p className="text-sm">Click ? for help</p>
+        </CardContent>
+      </Card>
+
+      {/* Info Icon */}
+      <Card
+        className="w-[200px]"
+        flippable
+        flipButtonIcon={{
+          front: <Info className="h-5 w-5" aria-hidden="true" />,
+          back: <ArrowLeft className="h-5 w-5" aria-hidden="true" />,
+        }}
+        flipButtonLabel={{
+          show: 'More info',
+          hide: 'Go back',
+        }}
+        backContent={
+          <div className="p-4">
+            <h3 className="font-semibold mb-2">Details</h3>
+            <p className="text-sm">Additional details about this item.</p>
+          </div>
+        }
+      >
+        <CardHeader className="pb-2">
+          <CardTitle className="text-base">Info Icon</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <p className="text-sm">Click i for info</p>
+        </CardContent>
+      </Card>
+    </div>
+  ),
+};
+
+// ============================================================================
+// Login Card (ShadCN Example)
+// ============================================================================
+
+/**
+ * Login Card
+ * Classic login form card following ShadCN patterns.
+ */
+export const LoginCard: Story = {
+  render: (): ReactElement => (
+    <Card className="w-[350px]">
+      <CardHeader>
+        <CardTitle>Login</CardTitle>
+        <CardDescription>Enter your credentials to access your account.</CardDescription>
+      </CardHeader>
+      <CardContent className="space-y-4">
+        <div className="space-y-2">
+          <label htmlFor="email" className="text-sm font-medium">Email</label>
+          <input
+            id="email"
+            type="email"
+            placeholder="name@example.com"
+            className="w-full px-3 py-2 border border-[var(--border)] rounded-md bg-[var(--content-background)]"
+          />
+        </div>
+        <div className="space-y-2">
+          <label htmlFor="password" className="text-sm font-medium">Password</label>
+          <input
+            id="password"
+            type="password"
+            placeholder="Enter your password"
+            className="w-full px-3 py-2 border border-[var(--border)] rounded-md bg-[var(--content-background)]"
+          />
+        </div>
+      </CardContent>
+      <CardFooter>
+        <Button className="w-full">Sign In</Button>
+      </CardFooter>
+    </Card>
+  ),
+};
+
+// ============================================================================
+// Product Card with Flip
+// ============================================================================
+
+/**
+ * Product Card with Details
+ * E-commerce style product card with flip to show details.
+ */
+export const ProductCard: Story = {
+  render: (): ReactElement => (
+    <Card
+      className="w-[300px]"
+      flippable
+      flipButtonPosition="bottom-right"
+      backContent={
+        <div className="p-6 h-full flex flex-col">
+          <h3 className="text-lg font-semibold mb-3">Product Details</h3>
+          <ul className="space-y-2 text-sm flex-1">
+            <li className="flex items-center gap-2">
+              <span className="text-green-500">✓</span>
+              Free shipping over $50
+            </li>
+            <li className="flex items-center gap-2">
+              <span className="text-green-500">✓</span>
+              30-day return policy
+            </li>
+            <li className="flex items-center gap-2">
+              <span className="text-green-500">✓</span>
+              2-year warranty
+            </li>
+            <li className="flex items-center gap-2">
+              <span className="text-green-500">✓</span>
+              24/7 customer support
+            </li>
+          </ul>
+          <Button variant="outline" className="w-full mt-4">
+            Contact Support
+          </Button>
+        </div>
+      }
+    >
+      <div className="aspect-square bg-[var(--accent-background)] rounded-t-lg flex items-center justify-center">
+        <span className="text-6xl">📦</span>
+      </div>
+      <CardHeader className="pb-2">
+        <CardTitle className="text-lg">Premium Widget</CardTitle>
+        <CardDescription>The best widget money can buy</CardDescription>
+      </CardHeader>
+      <CardContent className="pt-0">
+        <div className="flex items-baseline gap-2">
+          <span className="text-2xl font-bold">$49.99</span>
+          <span className="text-sm line-through text-[var(--content-foreground-muted)]">$79.99</span>
+        </div>
+      </CardContent>
+      <CardFooter>
+        <Button className="w-full">Add to Cart</Button>
+      </CardFooter>
+    </Card>
+  ),
+};
+
+// ============================================================================
+// Custom Flip Duration
+// ============================================================================
+
+/**
+ * Custom Animation Duration
+ * Card with slower flip animation (1 second).
+ */
+export const SlowFlip: Story = {
+  render: (): ReactElement => (
+    <Card
+      className="w-[350px]"
+      flippable
+      flipDuration={1000}
+      backContent={
+        <div className="p-6">
+          <h3 className="text-lg font-semibold">Slow Flip</h3>
+          <p className="mt-2 text-sm">
+            This card has a 1 second flip animation duration.
+          </p>
+        </div>
+      }
+    >
+      <CardHeader>
+        <CardTitle>Slow Animation</CardTitle>
+        <CardDescription>1000ms flip duration</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p>Click to see the slower flip animation.</p>
+      </CardContent>
+    </Card>
+  ),
+};
+
+// ============================================================================
+// Started Flipped
+// ============================================================================
+
+/**
+ * Default Flipped State
+ * Card that starts in the flipped state.
+ */
+export const StartedFlipped: Story = {
+  render: (): ReactElement => (
+    <Card
+      className="w-[350px]"
+      flippable
+      defaultFlipped
+      backContent={
+        <div className="p-6">
+          <h3 className="text-lg font-semibold">Started Flipped</h3>
+          <p className="mt-2 text-sm">
+            This card was rendered with defaultFlipped=true, so it shows the back side initially.
+          </p>
+        </div>
+      }
+    >
+      <CardHeader>
+        <CardTitle>Front Side</CardTitle>
+        <CardDescription>This is the front side.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <p>Click the flip button to see this side.</p>
+      </CardContent>
+    </Card>
+  ),
+};
+
+// ============================================================================
+// Simple Card (No Header/Footer)
+// ============================================================================
+
+/**
+ * Simple Content Card
+ * Minimal card with just content.
+ */
+export const SimpleCard: Story = {
+  render: (): ReactElement => (
+    <Card className="w-[300px]">
+      <CardContent className="pt-6">
+        <p>A simple card with just content, no header or footer.</p>
+        <p className="mt-2 text-sm text-[var(--content-foreground-muted)]">
+          Perfect for notifications or simple messages.
+        </p>
+      </CardContent>
+    </Card>
+  ),
+};