aural-ui 4.0.1 → 4.1.0

package/dist/components/dot-loader/DotLoader.stories.tsx

@@ -1,6 +1,8 @@
 import React from "react"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import DotLoader from "."
 
 const meta: Meta<typeof DotLoader> = {
@@ -10,77 +12,44 @@ const meta: Meta<typeof DotLoader> = {
     layout: "centered",
     docs: {
       description: {
-        component: `
-# DotLoader
-
-A customizable animated dot loader component with three dots that pulse in sequence, built with accessibility in mind.
-
-## Features
-- Smooth pulsing animation with CSS custom properties
-- Customizable colors for normal and active states
-- Optional text label with flexible content support
-- Comprehensive accessibility features (ARIA attributes, screen reader support)
-- Flexible styling with custom classes
-- Dark theme optimized
-- Screen reader announcements with configurable messages
-
-## Accessibility Features
-- \`role="status"\` for proper semantic meaning
-- \`aria-live="polite"\` for non-intrusive screen reader announcements
-- \`aria-busy="true"\` to indicate loading state
-- Hidden descriptive text for screen readers
-- Configurable ARIA labels and loading messages
-- Decorative elements properly hidden from assistive technology
-
-## Usage
-\`\`\`tsx
-import DotLoader from '@/ui/components/dot-loader'
-
-// Basic usage
-<DotLoader />
-
-// With text
-<DotLoader text="Loading..." />
-
-// Custom colors and accessibility
-<DotLoader 
-  color="var(--color-blue-500)" 
-  activeDotColor="var(--color-blue-300)" 
-  text="Processing..." 
-  ariaLabel="Processing user data"
-  loadingMessage="User data is being processed, please wait"
-/>
-
-// Silent loading (no screen reader announcements)
-<DotLoader 
-  text="Background sync" 
-  announceToScreenReader={false}
-/>
-\`\`\`
-        `,
+        component:
+          "An animated three-dot loading indicator that pulses in sequence. Supports optional visible text, custom dot colors via design tokens, and comprehensive ARIA attributes for screen reader compatibility.",
       },
-    },
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#1a1a1a" },
-        { name: "light", value: "#ffffff" },
-      ],
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Pulsing Animation",
+              description: "Sequenced dot animation",
+            },
+            {
+              title: "Token Colors",
+              description: "Active & inactive dots",
+            },
+            {
+              title: "ARIA Support",
+              description: "aria-live and role built in",
+            },
+          ]}
+        />
+      ),
     },
   },
+  tags: ["autodocs"],
   argTypes: {
     text: {
       control: "text",
-      description:
-        "Optional text to display below the loader (supports React nodes)",
+      description: "Optional visible text displayed below the dots",
     },
     color: {
-      control: "color",
-      description: "Color of the inactive dots",
+      control: "text",
+      description:
+        "CSS value for the inactive dot color (use design token var() references)",
     },
     activeDotColor: {
-      control: "color",
-      description: "Color of the active/pulsing dot",
+      control: "text",
+      description:
+        "CSS value for the active/pulsing dot color (use design token var() references)",
     },
     className: {
       control: "text",
@@ -93,143 +62,187 @@ import DotLoader from '@/ui/components/dot-loader'
     },
     ariaLabel: {
       control: "text",
-      description: "Accessible label for screen readers",
+      description: "Accessible label announced by screen readers",
     },
     announceToScreenReader: {
       control: "boolean",
-      description: "Whether to announce loading state to screen readers",
+      description:
+        "Whether to add aria-live='polite' for screen reader announcements",
     },
     loadingMessage: {
       control: "text",
-      description: "Custom loading message for screen readers",
+      description: "Hidden descriptive message read by screen readers",
     },
   },
-  tags: ["autodocs"],
 }
 
 export default meta
 type Story = StoryObj<typeof meta>
 
-// Default story
-export const Default: Story = {
-  args: {},
-}
+// ─── 1. Playground ────────────────────────────────────────────────────────────
 
-// With text
-export const WithText: Story = {
+export const Playground: Story = {
   args: {
     text: "Loading...",
-  },
-}
-
-// Custom colors
-export const CustomColors: Story = {
-  args: {
-    text: "Processing...",
-    color: "#64748b",
-    activeDotColor: "#3b82f6",
-  },
-}
-
-// Brand colors
-export const BrandColors: Story = {
-  args: {
-    text: "Please wait",
     color: "var(--color-fm-secondary-800)",
     activeDotColor: "var(--color-fm-secondary-500)",
-  },
-}
-
-// Accessibility focused story
-export const AccessibilityFeatures: Story = {
-  args: {
-    text: "Loading user profile",
-    ariaLabel: "Loading user profile data",
-    loadingMessage: "User profile data is being loaded, please wait",
+    ariaLabel: "Loading",
     announceToScreenReader: true,
+    loadingMessage: "Content is loading, please wait",
   },
+  render: (args) => (
+    <div className="w-full max-w-sm space-y-4">
+      <div className="flex justify-center py-4">
+        <DotLoader {...args} />
+      </div>
+      <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+        <code className="text-fm-secondary text-fm-md leading-fm-md font-(--font-fm-mono)">
+          {`<DotLoader${args.text ? ` text="${args.text}"` : ""}${args.ariaLabel ? ` ariaLabel="${args.ariaLabel}"` : ""} />`}
+        </code>
+      </div>
+    </div>
+  ),
   parameters: {
     docs: {
       description: {
         story:
-          "Demonstrates accessibility features with custom ARIA labels and screen reader messages.",
+          "Adjust text, dot colors, and accessibility props using the controls panel in the sidebar.",
       },
     },
   },
 }
 
-// Silent loading (no screen reader announcements)
-export const SilentLoading: Story = {
-  args: {
-    text: "Background sync",
-    announceToScreenReader: false,
-    ariaLabel: "Background synchronization",
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Example of a loader that doesn't announce to screen readers, useful for background processes.",
-      },
-    },
-  },
-}
+// ─── 2. Configurations ────────────────────────────────────────────────────────
 
-// Large with custom styling
-export const CustomStyling: Story = {
-  args: {
-    text: "Loading your content...",
-    className: "p-8",
-    classes: {
-      root: "bg-slate-800 rounded-lg p-6",
-      dot: "scale-150",
-      text: "text-slate-300 text-lg font-semibold",
-    },
-    ariaLabel: "Loading content",
-    loadingMessage: "Content is being loaded with custom styling",
-  },
-}
-
-// Different color variations
-export const ColorVariations: Story = {
+export const Configurations: Story = {
   render: () => (
-    <div className="flex flex-col gap-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-4 text-lg">Default Theme</h3>
-        <DotLoader text="Loading..." ariaLabel="Loading default content" />
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Text Options
+        </h4>
+        <div className="grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+          <div className="space-y-3 text-center">
+            <div className="flex min-h-24 items-center justify-center">
+              <DotLoader ariaLabel="Loading" />
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              No Text
+            </p>
+          </div>
+          <div className="space-y-3 text-center">
+            <div className="flex min-h-24 items-center justify-center">
+              <DotLoader text="Loading..." ariaLabel="Loading content" />
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              With Text
+            </p>
+          </div>
+          <div className="space-y-3 text-center">
+            <div className="flex min-h-24 items-center justify-center">
+              <DotLoader
+                text="Uploading your files..."
+                ariaLabel="Uploading files"
+              />
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Longer Text
+            </p>
+          </div>
+        </div>
       </div>
 
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-4 text-lg">Blue Theme</h3>
-        <DotLoader
-          text="Processing..."
-          color="#1e293b"
-          activeDotColor="#3b82f6"
-          ariaLabel="Processing data"
-          loadingMessage="Data processing in progress"
-        />
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Custom Colors (Design Tokens)
+        </h4>
+        <div className="grid gap-6 sm:grid-cols-2 xl:grid-cols-4">
+          <div className="space-y-3 text-center">
+            <div className="flex min-h-24 items-center justify-center">
+              <DotLoader
+                text="Default"
+                color="var(--color-fm-secondary-800)"
+                activeDotColor="var(--color-fm-secondary-500)"
+                ariaLabel="Loading with brand colors"
+              />
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Brand (Secondary)
+            </p>
+          </div>
+          <div className="space-y-3 text-center">
+            <div className="flex min-h-24 items-center justify-center">
+              <DotLoader
+                text="Positive"
+                color="var(--color-fm-green-900)"
+                activeDotColor="var(--color-fm-green-500)"
+                ariaLabel="Loading with positive indicator"
+              />
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Positive
+            </p>
+          </div>
+          <div className="space-y-3 text-center">
+            <div className="flex min-h-24 items-center justify-center">
+              <DotLoader
+                text="Info"
+                color="var(--color-fm-blue-900)"
+                activeDotColor="var(--color-fm-blue-500)"
+                ariaLabel="Loading with info indicator"
+              />
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Info
+            </p>
+          </div>
+          <div className="space-y-3 text-center">
+            <div className="flex min-h-24 items-center justify-center">
+              <DotLoader
+                text="Warning"
+                color="var(--color-fm-yellow-800)"
+                activeDotColor="var(--color-fm-yellow-500)"
+                ariaLabel="Loading with warning indicator"
+              />
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Warning
+            </p>
+          </div>
+        </div>
       </div>
 
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-4 text-lg">Green Theme</h3>
-        <DotLoader
-          text="Uploading..."
-          color="#1f2937"
-          activeDotColor="#10b981"
-          ariaLabel="Uploading files"
-          loadingMessage="Files are being uploaded"
-        />
-      </div>
-
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-4 text-lg">Red Theme</h3>
-        <DotLoader
-          text="Deleting..."
-          color="#1f2937"
-          activeDotColor="#ef4444"
-          ariaLabel="Deleting items"
-          loadingMessage="Items are being deleted"
-        />
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Screen Reader Announcement Mode
+        </h4>
+        <div className="grid gap-6 sm:grid-cols-2">
+          <div className="space-y-3 text-center">
+            <div className="flex min-h-24 items-center justify-center">
+              <DotLoader
+                text="Syncing..."
+                announceToScreenReader={true}
+                ariaLabel="Syncing data"
+                loadingMessage="Data is being synced with the server, please wait"
+              />
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Announced (aria-live)
+            </p>
+          </div>
+          <div className="space-y-3 text-center">
+            <div className="flex min-h-24 items-center justify-center">
+              <DotLoader
+                text="Background sync"
+                announceToScreenReader={false}
+                ariaLabel="Background synchronization"
+              />
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Silent (no aria-live)
+            </p>
+          </div>
+        </div>
       </div>
     </div>
   ),
@@ -237,58 +250,93 @@ export const ColorVariations: Story = {
     docs: {
       description: {
         story:
-          "Examples of different color combinations for various use cases, each with appropriate accessibility labels.",
+          "Configuration options: text presence, custom dot colors using design token CSS variables, and screen reader announcement mode.",
       },
     },
   },
 }
 
-// Loading states simulation
-export const LoadingStates: Story = {
-  render: () => (
-    <div className="grid grid-cols-2 gap-8">
-      <div className="bg-fm-surface-secondary rounded-lg p-6 text-center">
-        <h4 className="text-fm-primary mb-4 text-sm">File Upload</h4>
-        <DotLoader
-          text="Uploading files..."
-          color="#374151"
-          activeDotColor="#06b6d4"
-          ariaLabel="File upload in progress"
-          loadingMessage="Files are being uploaded to the server"
-        />
-      </div>
+// ─── 3. Accessibility ─────────────────────────────────────────────────────────
 
-      <div className="bg-fm-surface-secondary rounded-lg p-6 text-center">
-        <h4 className="text-fm-primary mb-4 text-sm">Data Processing</h4>
-        <DotLoader
-          text="Processing data..."
-          color="#374151"
-          activeDotColor="#8b5cf6"
-          ariaLabel="Data processing"
-          loadingMessage="Your data is being processed"
-        />
-      </div>
-
-      <div className="bg-fm-surface-secondary rounded-lg p-6 text-center">
-        <h4 className="text-fm-primary mb-4 text-sm">Authentication</h4>
-        <DotLoader
-          text="Signing in..."
-          color="#374151"
-          activeDotColor="#f59e0b"
-          ariaLabel="Authentication in progress"
-          loadingMessage="Please wait while we sign you in"
-        />
+export const Accessibility: Story = {
+  render: () => (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          ARIA Attribute Examples
+        </h4>
+        <div className="flex flex-wrap items-start gap-8">
+          <div className="space-y-2 text-center">
+            <DotLoader
+              text="Loading user profile"
+              ariaLabel="Loading user profile data"
+              loadingMessage="User profile data is being loaded, please wait"
+              announceToScreenReader={true}
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Visual + SR message
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <DotLoader
+              ariaLabel="Authenticating your account"
+              loadingMessage="Authentication is in progress, please wait"
+              announceToScreenReader={true}
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              SR label only (no text)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <DotLoader
+              text="Saving changes"
+              announceToScreenReader={false}
+              ariaLabel="Saving document changes silently"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Silent background task
+            </p>
+          </div>
+        </div>
       </div>
 
-      <div className="bg-fm-surface-secondary rounded-lg p-6 text-center">
-        <h4 className="text-fm-primary mb-4 text-sm">Content Loading</h4>
-        <DotLoader
-          text="Loading content..."
-          color="#374151"
-          activeDotColor="#10b981"
-          ariaLabel="Content loading"
-          loadingMessage="Page content is being loaded"
-        />
+      <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+        <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+          <strong className="text-fm-primary">Best practices:</strong>
+        </p>
+        <ul className="mt-2 space-y-1">
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              • Always provide <code>ariaLabel</code> or <code>text</code> so
+              screen readers have context about what is loading.
+            </p>
+          </li>
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              • Use <code>loadingMessage</code> to supply a more detailed
+              description than the visible text, if they differ.
+            </p>
+          </li>
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              • Set <code>announceToScreenReader=false</code> for silent
+              background tasks that should not interrupt the user.
+            </p>
+          </li>
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              • The component uses <code>role="status"</code> and{" "}
+              <code>aria-busy="true"</code> automatically — no extra markup
+              needed.
+            </p>
+          </li>
+          <li>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              • Decorative dot elements are hidden from assistive technology via{" "}
+              <code>aria-hidden="true"</code>.
+            </p>
+          </li>
+        </ul>
       </div>
     </div>
   ),
@@ -296,56 +344,7 @@ export const LoadingStates: Story = {
     docs: {
       description: {
         story:
-          "Real-world examples of how the loader might be used in different contexts with appropriate accessibility descriptions.",
-      },
-    },
-  },
-}
-
-// Complex content example
-export const ComplexContent: Story = {
-  args: {
-    text: (
-      <div className="flex items-center gap-2">
-        <span>Loading</span>
-        <span className="font-bold text-blue-400">premium</span>
-        <span>content...</span>
-      </div>
-    ),
-    ariaLabel: "Loading premium content",
-    loadingMessage: "Premium content is being loaded for your account",
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Example with complex React node content while maintaining accessibility.",
-      },
-    },
-  },
-}
-
-// Playground story for interactive testing
-export const Playground: Story = {
-  args: {
-    text: "Loading...",
-    color: "#64748b",
-    activeDotColor: "#3b82f6",
-    className: "",
-    classes: {
-      root: "",
-      dot: "",
-      text: "",
-    },
-    ariaLabel: "Loading",
-    announceToScreenReader: true,
-    loadingMessage: "Content is loading, please wait",
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Interactive playground to test all component props including accessibility features.",
+          "Proper ARIA attribute usage patterns for DotLoader — covering visible-text loaders, screen-reader-only labels, and silent background tasks, with a best-practices reference at the bottom.",
       },
     },
   },