@tribepad/themis 1.0.0

package/src/elements/Carousel/Carousel.stories.tsx

@@ -0,0 +1,597 @@
+/**
+ * Carousel Component Stories
+ * Storybook stories for Carousel component demonstrating all features
+ */
+
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { Carousel } from './Carousel';
+import { useState } from 'react';
+
+const meta = {
+  title: 'Elements/Carousel',
+  component: Carousel,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Accessible carousel component for rotating content with auto-rotation, manual navigation, and full React Node support. Compliant with WCAG 2.2 AA standards.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    items: {
+      control: false,
+      description: 'Array of React nodes to display as carousel items',
+    },
+    autoRotateInterval: {
+      control: 'number',
+      description: 'Auto-rotation interval in milliseconds (0 to disable)',
+      table: {
+        defaultValue: { summary: '5000' },
+      },
+    },
+    defaultIndex: {
+      control: 'number',
+      description: 'Initial slide index (uncontrolled mode)',
+      table: {
+        defaultValue: { summary: '0' },
+      },
+    },
+    showNavigation: {
+      control: 'boolean',
+      description: 'Show navigation dots',
+      table: {
+        defaultValue: { summary: 'true' },
+      },
+    },
+    showPlayPause: {
+      control: 'boolean',
+      description: 'Show play/pause button',
+      table: {
+        defaultValue: { summary: 'true' },
+      },
+    },
+    respectReducedMotion: {
+      control: 'boolean',
+      description: 'Respect prefers-reduced-motion setting',
+      table: {
+        defaultValue: { summary: 'true' },
+      },
+    },
+    label: {
+      control: 'text',
+      description: 'Accessible label for the carousel',
+      table: {
+        defaultValue: { summary: 'Carousel' },
+      },
+    },
+    collapsible: {
+      control: 'boolean',
+      description: 'Enable minimize/maximize feature',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    defaultMinimized: {
+      control: 'boolean',
+      description: 'Start in minimized state (uncontrolled mode)',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    isMinimized: {
+      control: 'boolean',
+      description: 'Controlled minimized state',
+    },
+    minimizedLabel: {
+      control: 'text',
+      description: 'Label shown when carousel is minimized',
+      table: {
+        defaultValue: { summary: 'Carousel (minimized)' },
+      },
+    },
+  },
+} satisfies Meta<typeof Carousel>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Simple text items
+const textItems = [
+  <div key="1">Welcome to our platform</div>,
+  <div key="2">Discover amazing features</div>,
+  <div key="3">Get started today</div>,
+];
+
+// Rich content items
+const richItems = [
+  <div key="1" className="space-y-2">
+    <h3 className="text-lg font-semibold">Welcome</h3>
+    <p className="text-sm">Start your journey with us today</p>
+  </div>,
+  <div key="2" className="space-y-2">
+    <h3 className="text-lg font-semibold">Explore</h3>
+    <p className="text-sm">Discover powerful features and tools</p>
+  </div>,
+  <div key="3" className="space-y-2">
+    <h3 className="text-lg font-semibold">Achieve</h3>
+    <p className="text-sm">Reach your goals with our platform</p>
+  </div>,
+];
+
+// Complex component items
+const complexItems = [
+  <div key="1" className="flex items-center gap-4">
+    <div className="w-12 h-12 rounded-full bg-[var(--primary)] flex items-center justify-center text-[var(--primary-foreground)] font-bold">
+      1
+    </div>
+    <div>
+      <h4 className="font-semibold">Step One</h4>
+      <p className="text-sm">Create your account</p>
+    </div>
+  </div>,
+  <div key="2" className="flex items-center gap-4">
+    <div className="w-12 h-12 rounded-full bg-[var(--primary)] flex items-center justify-center text-[var(--primary-foreground)] font-bold">
+      2
+    </div>
+    <div>
+      <h4 className="font-semibold">Step Two</h4>
+      <p className="text-sm">Set up your profile</p>
+    </div>
+  </div>,
+  <div key="3" className="flex items-center gap-4">
+    <div className="w-12 h-12 rounded-full bg-[var(--primary)] flex items-center justify-center text-[var(--primary-foreground)] font-bold">
+      3
+    </div>
+    <div>
+      <h4 className="font-semibold">Step Three</h4>
+      <p className="text-sm">Start exploring</p>
+    </div>
+  </div>,
+];
+
+export const Default: Story = {
+  args: {
+    items: textItems,
+    autoRotateInterval: 5000,
+    showNavigation: true,
+    showPlayPause: true,
+  },
+};
+
+export const RichContent: Story = {
+  args: {
+    items: richItems,
+    autoRotateInterval: 5000,
+    label: 'Feature highlights',
+  },
+};
+
+export const ComplexComponents: Story = {
+  args: {
+    items: complexItems,
+    autoRotateInterval: 5000,
+    label: 'Onboarding steps',
+  },
+};
+
+export const FastRotation: Story = {
+  args: {
+    items: textItems,
+    autoRotateInterval: 2000,
+    label: 'Fast rotating carousel',
+  },
+};
+
+export const NoAutoRotation: Story = {
+  args: {
+    items: textItems,
+    autoRotateInterval: 0,
+    label: 'Manual navigation only',
+  },
+};
+
+export const NoNavigation: Story = {
+  args: {
+    items: textItems,
+    showNavigation: false,
+    autoRotateInterval: 5000,
+  },
+};
+
+export const NoPlayPause: Story = {
+  args: {
+    items: textItems,
+    showPlayPause: false,
+    autoRotateInterval: 5000,
+  },
+};
+
+export const SingleItem: Story = {
+  args: {
+    items: [<div key="1">Only one item</div>],
+    autoRotateInterval: 5000,
+  },
+};
+
+export const StartAtSecondSlide: Story = {
+  args: {
+    items: textItems,
+    defaultIndex: 1,
+    autoRotateInterval: 5000,
+  },
+};
+
+export const CustomSlideLabels: Story = {
+  args: {
+    items: textItems,
+    slideLabel: (index: number, total: number) => `Item ${index + 1} of ${total}`,
+    autoRotateInterval: 5000,
+  },
+};
+
+// Controlled example
+export const Controlled: Story = {
+  render: function ControlledCarousel() {
+    const [currentIndex, setCurrentIndex] = useState(0);
+    const [isPaused, setIsPaused] = useState(false);
+
+    return (
+      <div className="space-y-4">
+        <Carousel
+          items={textItems}
+          currentIndex={currentIndex}
+          onIndexChange={setCurrentIndex}
+          isPaused={isPaused}
+          onPauseChange={setIsPaused}
+          autoRotateInterval={5000}
+        />
+        <div className="text-sm text-[var(--muted-foreground)] text-center">
+          Current slide: {currentIndex + 1} | Paused: {isPaused ? 'Yes' : 'No'}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const CustomStyling: Story = {
+  args: {
+    items: richItems,
+    autoRotateInterval: 5000,
+    className: 'max-w-md',
+    slideClassName: 'bg-[var(--primary)]/20 border-2 border-[var(--primary)]',
+    navigationClassName: 'justify-center',
+  },
+};
+
+// Accessibility demonstration
+export const ReducedMotion: Story = {
+  args: {
+    items: textItems,
+    autoRotateInterval: 5000,
+    respectReducedMotion: true,
+    label: 'Respects prefers-reduced-motion',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'This carousel respects the user\'s prefers-reduced-motion setting. If enabled, auto-rotation will be disabled automatically.',
+      },
+    },
+  },
+};
+
+// Collapsible feature demonstrations
+export const Collapsible: Story = {
+  args: {
+    items: richItems,
+    collapsible: true,
+    autoRotateInterval: 5000,
+    label: 'Tips carousel',
+    minimizedLabel: 'Tips',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Carousel with collapsible feature. Click the minimize button to collapse it, revealing content below. Click expand to show the full carousel again.',
+      },
+    },
+  },
+};
+
+export const CollapsibleMinimizedByDefault: Story = {
+  args: {
+    items: richItems,
+    collapsible: true,
+    defaultMinimized: true,
+    autoRotateInterval: 5000,
+    label: 'Tips carousel',
+    minimizedLabel: 'Tips',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Carousel that starts in minimized state. Click the expand button to show the full carousel.',
+      },
+    },
+  },
+};
+
+// Controlled collapsible example
+export const ControlledCollapsible: Story = {
+  render: function ControlledCollapsibleCarousel() {
+    const [currentIndex, setCurrentIndex] = useState(0);
+    const [isPaused, setIsPaused] = useState(false);
+    const [isMinimized, setIsMinimized] = useState(false);
+
+    return (
+      <div className="space-y-4">
+        <Carousel
+          items={richItems}
+          currentIndex={currentIndex}
+          onIndexChange={setCurrentIndex}
+          isPaused={isPaused}
+          onPauseChange={setIsPaused}
+          collapsible={true}
+          isMinimized={isMinimized}
+          onMinimizeChange={setIsMinimized}
+          autoRotateInterval={5000}
+          label="Controlled tips carousel"
+          minimizedLabel="Tips"
+        />
+        <div className="text-sm text-[var(--muted-foreground)] text-center space-y-1">
+          <div>Current slide: {currentIndex + 1} | Paused: {isPaused ? 'Yes' : 'No'}</div>
+          <div>Minimized: {isMinimized ? 'Yes' : 'No'}</div>
+        </div>
+        <div className="flex gap-2 justify-center">
+          <button
+            onClick={() => setIsMinimized(!isMinimized)}
+            className="px-3 py-1 text-sm bg-[var(--primary)] text-[var(--primary-foreground)] rounded"
+          >
+            Toggle Minimize
+          </button>
+        </div>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Fully controlled collapsible carousel. The parent component manages the minimized state and can toggle it programmatically.',
+      },
+    },
+  },
+};
+
+// Demo with content behind carousel
+export const CollapsibleWithContentBehind: Story = {
+  render: function CollapsibleWithContent() {
+    return (
+      <div className="space-y-4 w-[400px]">
+        <Carousel
+          items={richItems}
+          collapsible={true}
+          autoRotateInterval={0}
+          label="Tips"
+          minimizedLabel="Tips"
+        />
+        <div className="p-4 bg-[var(--card)] border border-[var(--border)] rounded-lg">
+          <h3 className="font-semibold mb-2">Content Below Carousel</h3>
+          <p className="text-sm text-[var(--muted-foreground)]">
+            This content is visible below the carousel. When the carousel overlaps or takes too much
+            space, you can minimize it to focus on this content. Click the minimize button (chevron
+            up icon) to collapse the carousel.
+          </p>
+        </div>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Demonstrates the collapsible feature use case: minimize the carousel to reveal content below it.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Per-Item Timing Stories
+// =============================================================================
+
+// Items with different content complexity
+const perItemTimingItems = [
+  <div key="1" className="space-y-1">
+    <h3 className="text-lg font-semibold">Quick Tip</h3>
+    <p className="text-sm">Short announcement (3 seconds)</p>
+  </div>,
+  <div key="2" className="space-y-2">
+    <h3 className="text-lg font-semibold">Detailed Feature</h3>
+    <p className="text-sm">
+      This slide has more content and requires more time to read. It showcases
+      a new feature with multiple bullet points:
+    </p>
+    <ul className="text-sm list-disc list-inside ml-2">
+      <li>Feature point one</li>
+      <li>Feature point two</li>
+      <li>Feature point three</li>
+    </ul>
+    <p className="text-xs text-[var(--muted-foreground)]">(10 seconds)</p>
+  </div>,
+  <div key="3" className="space-y-1">
+    <h3 className="text-lg font-semibold">Call to Action</h3>
+    <p className="text-sm">Ready to get started? (5 seconds)</p>
+  </div>,
+];
+
+export const PerItemTiming: Story = {
+  args: {
+    items: perItemTimingItems,
+    itemDurations: [3000, 10000, 5000], // 3s, 10s, 5s
+    label: 'Per-item timing carousel',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Carousel with per-item viewing durations. Each slide displays for its specified duration: Quick Tip (3s), Detailed Feature (10s), Call to Action (5s).',
+      },
+    },
+  },
+};
+
+export const PerItemTimingWithProgress: Story = {
+  render: function PerItemTimingWithProgressIndicator() {
+    const [elapsed, setElapsed] = useState(0);
+    const durations = [3000, 10000, 5000];
+    const total = durations.reduce((a, b) => a + b, 0);
+
+    return (
+      <div className="space-y-4 w-[400px]">
+        <Carousel
+          items={perItemTimingItems}
+          itemDurations={durations}
+          onElapsedTimeChange={setElapsed}
+          label="Per-item timing with progress"
+        />
+        <div className="space-y-2">
+          <div className="flex justify-between text-xs text-[var(--muted-foreground)]">
+            <span>Elapsed: {(elapsed / 1000).toFixed(0)}s</span>
+            <span>Total: {total / 1000}s</span>
+          </div>
+          <div className="h-2 bg-[var(--muted)] rounded-full overflow-hidden">
+            <div
+              className="h-full bg-[var(--primary)] transition-all duration-1000"
+              style={{ width: `${(elapsed / total) * 100}%` }}
+            />
+          </div>
+        </div>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Per-item timing carousel with an external progress indicator using the onElapsedTimeChange callback.',
+      },
+    },
+  },
+};
+
+export const PerItemTimingControlled: Story = {
+  render: function PerItemTimingControlledCarousel() {
+    const [elapsed, setElapsed] = useState(0);
+    const [isPaused, setIsPaused] = useState(false);
+    const durations = [3000, 10000, 5000];
+    const total = durations.reduce((a, b) => a + b, 0);
+
+    const jumpToSlide = (slideIndex: number) => {
+      // Calculate the start time for the selected slide
+      let startTime = 0;
+      for (let i = 0; i < slideIndex; i++) {
+        startTime += durations[i];
+      }
+      setElapsed(startTime);
+    };
+
+    return (
+      <div className="space-y-4 w-[400px]">
+        <Carousel
+          items={perItemTimingItems}
+          itemDurations={durations}
+          elapsedTime={elapsed}
+          onElapsedTimeChange={setElapsed}
+          isPaused={isPaused}
+          onPauseChange={setIsPaused}
+          label="Controlled per-item timing"
+        />
+        <div className="space-y-2">
+          <div className="flex justify-between text-xs text-[var(--muted-foreground)]">
+            <span>Elapsed: {(elapsed / 1000).toFixed(0)}s</span>
+            <span>Paused: {isPaused ? 'Yes' : 'No'}</span>
+          </div>
+          <div className="h-2 bg-[var(--muted)] rounded-full overflow-hidden">
+            <div
+              className="h-full bg-[var(--primary)] transition-all duration-100"
+              style={{ width: `${(elapsed / total) * 100}%` }}
+            />
+          </div>
+          <div className="flex gap-2 justify-center flex-wrap">
+            <button
+              onClick={() => jumpToSlide(0)}
+              className="px-3 py-1 text-xs bg-[var(--secondary)] text-[var(--secondary-foreground)] rounded"
+            >
+              Jump to Slide 1
+            </button>
+            <button
+              onClick={() => jumpToSlide(1)}
+              className="px-3 py-1 text-xs bg-[var(--secondary)] text-[var(--secondary-foreground)] rounded"
+            >
+              Jump to Slide 2
+            </button>
+            <button
+              onClick={() => jumpToSlide(2)}
+              className="px-3 py-1 text-xs bg-[var(--secondary)] text-[var(--secondary-foreground)] rounded"
+            >
+              Jump to Slide 3
+            </button>
+          </div>
+        </div>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Fully controlled per-item timing carousel. Use the buttons to jump to specific slides, which updates the elapsed time to match.',
+      },
+    },
+  },
+};
+
+export const MixedDurations: Story = {
+  args: {
+    items: [
+      <div key="1">Very quick tip (1 second minimum)</div>,
+      <div key="2">Standard announcement (5 seconds)</div>,
+      <div key="3">Extended content with lots of detail to read (15 seconds)</div>,
+      <div key="4">Final reminder (3 seconds)</div>,
+    ],
+    itemDurations: [1000, 5000, 15000, 3000], // 1s, 5s, 15s, 3s = 24s total
+    label: 'Mixed duration carousel',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Carousel with widely varying durations from 1 second to 15 seconds, demonstrating flexibility for different content types.',
+      },
+    },
+  },
+};
+
+export const PerItemTimingFallback: Story = {
+  args: {
+    items: textItems,
+    itemDurations: [3000, 5000], // Intentionally mismatched length
+    autoRotateInterval: 2000, // Falls back to this
+    label: 'Fallback to autoRotateInterval',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'When itemDurations length does not match items length, the carousel falls back to using autoRotateInterval (2 seconds). Check the console for a warning message.',
+      },
+    },
+  },
+};