aural-ui 4.0.1 → 4.1.0

package/dist/components/breadcrumb/Breadcrumb.stories.tsx

@@ -1,8 +1,9 @@
 import React from "react"
-import { ArrowRightIcon } from "@icons/arrow-right-icon"
 import { ChevronDoubleRightIcon } from "@icons/chevron-double-right-icon"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import { Breadcrumb } from "."
 
 const meta: Meta<typeof Breadcrumb> = {
@@ -10,73 +11,29 @@ const meta: Meta<typeof Breadcrumb> = {
   component: Breadcrumb,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-# Breadcrumb Component
-
-A navigation component that shows the current page's location within a site hierarchy. Users can navigate back to previous levels by clicking on breadcrumb items.
-
-## Features
-
-- **Multiple Separators**: Support for chevron, slash, arrow, and custom separators
-- **Custom Separator**: Use any React component or icon as a separator
-- **Clickable Navigation**: Items can be clickable links or static text
-- **Responsive Design**: Adapts spacing for mobile and desktop
-- **Accessibility**: Proper ARIA labels and semantic HTML structure
-- **Customizable**: Size variants and custom styling options
-- **Truncation**: Optional max items with ellipsis for long breadcrumbs
-- **Home Integration**: Optional home item at the beginning
-
-## Usage Examples
-
-### Basic Breadcrumb
-\`\`\`tsx
-<Breadcrumb
-  items={[
-    { title: "Home", url: "/" },
-    { title: "Products", url: "/products" },
-    { title: "Electronics" }
-  ]}
-  onItemClick={(title, url) => console.log(title, url)}
-/>
-\`\`\`
-
-### With Different Separators
-\`\`\`tsx
-<Breadcrumb
-  items={items}
-  separator="slash"
-  onItemClick={handleClick}
-/>
-\`\`\`
-
-### With Size Variants
-\`\`\`tsx
-<Breadcrumb
-  items={items}
-  size="lg"
-  onItemClick={handleClick}
-/>
-\`\`\`
-
-### With Custom Separator
-\`\`\`tsx
-<Breadcrumb
-  items={items}
-  customSeparator={<ArrowRightIcon width={16} height={16} />}
-  onItemClick={handleClick}
-/>
-\`\`\`
-        `,
+        component:
+          "A navigation component that shows the current page's location within a site hierarchy. Supports chevron, slash, arrow, and custom separators; optional home prepend; maxItems truncation; and clickable or static items.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Multiple Separators",
+              description: "Chevron, slash, arrow",
+            },
+            {
+              title: "Home Prefix",
+              description: "Optional home item",
+            },
+            {
+              title: "Auto Truncation",
+              description: "maxItems collapses path",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -104,199 +61,496 @@ A navigation component that shows the current page's location within a site hier
 export default meta
 type Story = StoryObj<typeof Breadcrumb>
 
-const sampleItems = [
-  { title: "Home", url: "/", isClickable: true },
-  { title: "Products", url: "/products", isClickable: true },
-  { title: "Electronics", url: "/products/electronics", isClickable: true },
+const subsectionHeaderClass =
+  "text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium"
+const itemLabelClass = "text-fm-secondary font-fm-text text-fm-sm leading-fm-sm"
+const cardClass =
+  "border-fm-divider-secondary rounded-xl border bg-transparent p-4"
+const codeBlockClass =
+  "border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3"
+const codeClass =
+  "text-fm-secondary font-[var(--font-fm-mono)] text-fm-md leading-fm-md"
+
+const musicItems = [
+  { title: "Discover", url: "/discover", isClickable: true },
+  { title: "Artists", url: "/discover/artists", isClickable: true },
+  {
+    title: "Electronic",
+    url: "/discover/artists/electronic",
+    isClickable: true,
+  },
   {
-    title: "Smartphones",
-    url: "/products/electronics/smartphones",
+    title: "Bicep",
+    url: "/discover/artists/electronic/bicep",
     isClickable: true,
   },
-  { title: "iPhone 15 Pro" },
+  { title: "Isles" },
 ]
 
-const longItems = [
-  { title: "Home", url: "/", isClickable: true },
-  { title: "Products", url: "/products", isClickable: true },
-  { title: "Electronics", url: "/products/electronics", isClickable: true },
+const longMusicItems = [
+  { title: "Discover", url: "/discover", isClickable: true },
+  { title: "Artists", url: "/discover/artists", isClickable: true },
   {
-    title: "Smartphones",
-    url: "/products/electronics/smartphones",
+    title: "Electronic",
+    url: "/discover/artists/electronic",
     isClickable: true,
   },
   {
-    title: "Apple",
-    url: "/products/electronics/smartphones/apple",
+    title: "United Kingdom",
+    url: "/discover/artists/electronic/uk",
     isClickable: true,
   },
   {
-    title: "iPhone",
-    url: "/products/electronics/smartphones/apple/iphone",
+    title: "Bicep",
+    url: "/discover/artists/electronic/uk/bicep",
     isClickable: true,
   },
-  { title: "iPhone 15 Pro" },
-]
-
-export const Default: Story = {
-  args: {
-    items: sampleItems,
-    size: "md",
-    separator: "chevron",
+  {
+    title: "Studio Albums",
+    url: "/discover/artists/electronic/uk/bicep/albums",
+    isClickable: true,
   },
-}
+  { title: "Isles" },
+]
 
-export const WithSlashSeparator: Story = {
-  args: {
-    items: sampleItems,
-    separator: "slash",
-  },
+function StoryLabel({ children }: React.PropsWithChildren) {
+  return <p className={itemLabelClass}>{children}</p>
 }
 
-export const WithArrowSeparator: Story = {
-  args: {
-    items: sampleItems,
-    separator: "arrow",
-  },
+function BreadcrumbCard({
+  children,
+  align = "center",
+}: React.PropsWithChildren<{ align?: "center" | "start" }>) {
+  return (
+    <div className={cardClass}>
+      <div className="overflow-x-auto pb-1">
+        <div
+          className={
+            align === "start"
+              ? "flex min-w-max items-center"
+              : "flex min-w-max items-center justify-center"
+          }
+        >
+          {children}
+        </div>
+      </div>
+    </div>
+  )
 }
 
-export const WithCustomSeparator: Story = {
-  args: {
-    items: sampleItems,
-    customSeparator: <ChevronDoubleRightIcon width={16} height={16} />,
-  },
+function BreadcrumbItemCard({
+  label,
+  children,
+}: React.PropsWithChildren<{ label: string }>) {
+  return (
+    <div className="space-y-2 text-center">
+      <BreadcrumbCard>{children}</BreadcrumbCard>
+      <StoryLabel>{label}</StoryLabel>
+    </div>
+  )
 }
 
-export const SmallSize: Story = {
+export const Playground: Story = {
   args: {
-    items: sampleItems,
-    size: "sm",
+    items: musicItems,
+    size: "md",
+    separator: "chevron",
+    showHome: false,
   },
-}
-
-export const LargeSize: Story = {
-  args: {
-    items: sampleItems,
-    size: "lg",
+  render: (args) => (
+    <div className="w-full max-w-2xl space-y-4">
+      <BreadcrumbCard>
+        <Breadcrumb {...args} />
+      </BreadcrumbCard>
+      <div className={codeBlockClass}>
+        <code className={codeClass}>
+          {`<Breadcrumb size="${args.size}" separator="${args.separator}" showHome={${args.showHome}} />`}
+        </code>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Controls-driven playground. Use the Storybook sidebar to change size, separator, showHome, and maxItems and see live results alongside the generated code snippet.",
+      },
+    },
   },
 }
 
-export const WithHome: Story = {
-  args: {
-    items: [
-      { title: "Products", url: "/products", isClickable: true },
-      { title: "Electronics", url: "/products/electronics", isClickable: true },
-      { title: "Smartphones" },
-    ],
-    showHome: true,
-    homeTitle: "Home",
-    homeUrl: "/",
-  },
-}
+export const Configurations: Story = {
+  render: () => (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className={subsectionHeaderClass}>Separator Types</h4>
+        <div className="grid gap-4 md:grid-cols-2">
+          <BreadcrumbItemCard label="Chevron (default)">
+            <Breadcrumb items={musicItems} separator="chevron" />
+          </BreadcrumbItemCard>
+          <BreadcrumbItemCard label="Slash">
+            <Breadcrumb items={musicItems} separator="slash" />
+          </BreadcrumbItemCard>
+          <BreadcrumbItemCard label="Arrow">
+            <Breadcrumb items={musicItems} separator="arrow" />
+          </BreadcrumbItemCard>
+          <BreadcrumbItemCard label="Custom icon">
+            <Breadcrumb
+              items={musicItems}
+              customSeparator={
+                <ChevronDoubleRightIcon width={14} height={14} />
+              }
+            />
+          </BreadcrumbItemCard>
+          <BreadcrumbItemCard label="Custom text">
+            <Breadcrumb items={musicItems} customSeparator="·" />
+          </BreadcrumbItemCard>
+        </div>
+      </div>
 
-export const WithMaxItems: Story = {
-  args: {
-    items: longItems,
-    maxItems: 4,
-  },
-}
+      <div className="space-y-4">
+        <h4 className={subsectionHeaderClass}>Show Home Prefix</h4>
+        <div className="grid gap-4 md:grid-cols-2">
+          <BreadcrumbItemCard label="showHome: false">
+            <Breadcrumb
+              items={[
+                { title: "Artists", url: "/artists", isClickable: true },
+                { title: "Bicep" },
+              ]}
+            />
+          </BreadcrumbItemCard>
+          <BreadcrumbItemCard label="showHome: true">
+            <Breadcrumb
+              items={[
+                { title: "Artists", url: "/artists", isClickable: true },
+                { title: "Bicep" },
+              ]}
+              showHome
+              homeTitle="Home"
+              homeUrl="/"
+            />
+          </BreadcrumbItemCard>
+        </div>
+      </div>
 
-export const NonClickable: Story = {
-  args: {
-    items: [
-      { title: "Home", isClickable: false },
-      { title: "Products", isClickable: false },
-      { title: "Electronics", isClickable: false },
-      { title: "Smartphones" },
-    ],
-  },
-}
+      <div className="space-y-4">
+        <h4 className={subsectionHeaderClass}>maxItems Truncation</h4>
+        <div className="grid gap-4">
+          <BreadcrumbItemCard label="All items (no limit)">
+            <Breadcrumb items={longMusicItems} />
+          </BreadcrumbItemCard>
+          <BreadcrumbItemCard label="maxItems: 4 (ellipsis middle)">
+            <Breadcrumb items={longMusicItems} maxItems={4} />
+          </BreadcrumbItemCard>
+          <BreadcrumbItemCard label="maxItems: 2 (first + last only)">
+            <Breadcrumb items={longMusicItems} maxItems={2} />
+          </BreadcrumbItemCard>
+        </div>
+      </div>
 
-export const MixedClickable: Story = {
-  args: {
-    items: [
-      { title: "Home", url: "/", isClickable: true },
-      { title: "Products", isClickable: false },
-      { title: "Electronics", url: "/products/electronics", isClickable: true },
-      { title: "Smartphones" },
-    ],
+      <div className="space-y-4">
+        <h4 className={subsectionHeaderClass}>
+          Clickable vs Non-Clickable Items
+        </h4>
+        <div className="grid gap-4 md:grid-cols-2">
+          <BreadcrumbItemCard label="Clickable ancestors, static current page">
+            <Breadcrumb
+              items={[
+                { title: "Discover", url: "/discover", isClickable: true },
+                { title: "Artists", url: "/artists", isClickable: true },
+                { title: "Bicep" },
+              ]}
+            />
+          </BreadcrumbItemCard>
+          <BreadcrumbItemCard label="All non-clickable">
+            <Breadcrumb
+              items={[
+                { title: "Discover", isClickable: false },
+                { title: "Artists", isClickable: false },
+                { title: "Bicep" },
+              ]}
+            />
+          </BreadcrumbItemCard>
+        </div>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Comparison of all configuration axes: separator types (chevron, slash, arrow, custom), showHome toggle, maxItems truncation levels, and clickable versus static items.",
+      },
+    },
   },
 }
 
-export const AllVariants: Story = {
+export const Sizes: Story = {
   render: () => (
-    <div className="flex flex-col gap-8 p-8">
+    <div className="space-y-8">
+      <div className="flex flex-wrap items-end justify-center gap-6">
+        <BreadcrumbItemCard label="Small (sm)">
+          <Breadcrumb
+            items={[
+              { title: "Discover", url: "/discover", isClickable: true },
+              { title: "Artists", url: "/artists", isClickable: true },
+              { title: "Bicep" },
+            ]}
+            size="sm"
+          />
+        </BreadcrumbItemCard>
+        <BreadcrumbItemCard label="Medium (md · default)">
+          <Breadcrumb
+            items={[
+              { title: "Discover", url: "/discover", isClickable: true },
+              { title: "Artists", url: "/artists", isClickable: true },
+              { title: "Bicep" },
+            ]}
+            size="md"
+          />
+        </BreadcrumbItemCard>
+        <BreadcrumbItemCard label="Large (lg)">
+          <Breadcrumb
+            items={[
+              { title: "Discover", url: "/discover", isClickable: true },
+              { title: "Artists", url: "/artists", isClickable: true },
+              { title: "Bicep" },
+            ]}
+            size="lg"
+          />
+        </BreadcrumbItemCard>
+      </div>
+
       <div className="space-y-4">
-        <h3 className="text-fm-lg font-fm-brand text-neutral-400">
-          Size Variants
-        </h3>
-        <div className="space-y-2">
-          <Breadcrumb items={sampleItems} size="sm" />
-          <Breadcrumb items={sampleItems} size="md" />
-          <Breadcrumb items={sampleItems} size="lg" />
+        <h4 className={subsectionHeaderClass}>Size × Separator</h4>
+        <div className="grid gap-4">
+          {(["sm", "md", "lg"] as const).map((size) => (
+            <BreadcrumbItemCard key={size} label={`${size} · slash`}>
+              <Breadcrumb items={musicItems} size={size} separator="slash" />
+            </BreadcrumbItemCard>
+          ))}
         </div>
       </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Three size variants (sm, md, lg) shown side by side with a size × separator cross-axis comparison.",
+      },
+    },
+  },
+}
 
+export const UseCases: Story = {
+  render: () => (
+    <div className="mx-auto max-w-3xl space-y-8 p-8">
       <div className="space-y-4">
-        <h3 className="text-fm-lg font-fm-brand text-neutral-400">
-          Separator Variants
-        </h3>
-        <div className="space-y-2">
-          <Breadcrumb items={sampleItems} separator="chevron" />
-          <Breadcrumb items={sampleItems} separator="slash" />
-          <Breadcrumb items={sampleItems} separator="arrow" />
-          <Breadcrumb
-            items={sampleItems}
-            customSeparator={<ArrowRightIcon width={16} height={16} />}
-          />
-          <Breadcrumb
-            items={sampleItems}
-            customSeparator={<ChevronDoubleRightIcon width={16} height={16} />}
-          />
-          <Breadcrumb items={sampleItems} customSeparator="•" />
+        <h4 className={subsectionHeaderClass}>Music Library Navigation</h4>
+        <div className="border-fm-divider-secondary mx-auto max-w-2xl space-y-4 rounded-xl border bg-transparent p-5">
+          <div className="overflow-x-auto pb-1">
+            <div className="min-w-max">
+              <Breadcrumb
+                items={[
+                  { title: "Library", url: "/library", isClickable: true },
+                  {
+                    title: "Albums",
+                    url: "/library/albums",
+                    isClickable: true,
+                  },
+                  {
+                    title: "Electronic",
+                    url: "/library/albums/electronic",
+                    isClickable: true,
+                  },
+                  { title: "Isles" },
+                ]}
+                showHome
+                homeTitle="Home"
+                homeUrl="/"
+                separator="chevron"
+                size="sm"
+              />
+            </div>
+          </div>
+          <div className="bg-fm-surface-tertiary h-32 rounded-lg" />
+          <p className="text-fm-primary font-fm-brand text-fm-lg leading-fm-lg font-semibold">
+            Isles
+          </p>
+          <p className={itemLabelClass}>Bicep · 2021 · 12 tracks</p>
         </div>
       </div>
 
       <div className="space-y-4">
-        <h3 className="text-fm-lg font-fm-brand text-neutral-400">With Home</h3>
-        <Breadcrumb
-          items={[
-            { title: "Products", url: "/products", isClickable: true },
-            { title: "Electronics" },
-          ]}
-          showHome={true}
-        />
+        <h4 className={subsectionHeaderClass}>Settings Page Context</h4>
+        <div className="border-fm-divider-secondary mx-auto max-w-2xl rounded-xl border bg-transparent">
+          <div className="border-fm-divider-secondary overflow-x-auto border-b px-5 py-3">
+            <div className="min-w-max">
+              <Breadcrumb
+                items={[
+                  { title: "Account", url: "/account", isClickable: true },
+                  {
+                    title: "Preferences",
+                    url: "/account/preferences",
+                    isClickable: true,
+                  },
+                  { title: "Audio Quality" },
+                ]}
+                separator="slash"
+                size="sm"
+              />
+            </div>
+          </div>
+          <div className="space-y-3 p-5">
+            <p className="text-fm-primary font-fm-brand text-fm-md leading-fm-md font-semibold">
+              Audio Quality Settings
+            </p>
+            <p className={itemLabelClass}>
+              Choose your preferred streaming and download quality.
+            </p>
+          </div>
+        </div>
       </div>
 
       <div className="space-y-4">
-        <h3 className="text-fm-lg font-fm-brand text-neutral-400">
-          With Max Items (4)
-        </h3>
-        <Breadcrumb items={longItems} maxItems={4} />
+        <h4 className={subsectionHeaderClass}>Deep Path with Truncation</h4>
+        <div className="border-fm-divider-secondary mx-auto max-w-2xl space-y-3 rounded-xl border bg-transparent p-5">
+          <div className="overflow-x-auto pb-1">
+            <div className="min-w-max">
+              <Breadcrumb
+                items={longMusicItems}
+                maxItems={4}
+                separator="arrow"
+                size="md"
+              />
+            </div>
+          </div>
+          <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+            Deep paths collapse automatically so the current location stays easy
+            to scan.
+          </p>
+        </div>
       </div>
     </div>
   ),
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        story:
+          "Real product-shaped examples: music library album navigation with home prefix, a settings page context bar, and a deep path using maxItems truncation.",
+      },
+    },
+  },
 }
 
 export const Interactive: Story = {
   render: () => {
-    const [currentPath, setCurrentPath] = React.useState("iPhone 15 Pro")
+    const pathTree = [
+      { title: "Discover", url: "/discover" },
+      { title: "Artists", url: "/discover/artists" },
+      { title: "Electronic", url: "/discover/artists/electronic" },
+      { title: "Bicep", url: "/discover/artists/electronic/bicep" },
+      { title: "Isles", url: "/discover/artists/electronic/bicep/isles" },
+    ]
 
-    const handleItemClick = (title: string, url?: string) => {
-      console.log(`Clicked: ${title}`, url)
-      setCurrentPath(title)
+    const [activePath, setActivePath] = React.useState<string[]>([
+      "Discover",
+      "Artists",
+      "Electronic",
+      "Bicep",
+      "Isles",
+    ])
+
+    const handleItemClick = (title: string) => {
+      const nextIndex = pathTree.findIndex((node) => node.title === title)
+
+      if (nextIndex >= 0) {
+        setActivePath(
+          pathTree.slice(0, nextIndex + 1).map((node) => node.title)
+        )
+      }
     }
 
+    const breadcrumbItems = activePath.map((title, index) => ({
+      title,
+      url: pathTree.find((node) => node.title === title)?.url,
+      isClickable: index < activePath.length - 1,
+    }))
+
     return (
-      <div className="space-y-4 p-8">
-        <h3 className="text-fm-lg font-fm-brand text-neutral-400">
-          Current Path: {currentPath}
-        </h3>
-        <Breadcrumb items={sampleItems} onItemClick={handleItemClick} />
-        <div className="text-fm-secondary text-fm-sm">
-          Click on any breadcrumb item to see the interaction
+      <div className="w-full p-8">
+        <div className="mx-auto max-w-4xl space-y-6">
+          <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
+            <div className="border-fm-divider-secondary space-y-5 rounded-xl border bg-transparent p-5">
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Navigate To
+              </p>
+              <div className="space-y-2">
+                {pathTree.map((node) => {
+                  const isCurrent =
+                    activePath[activePath.length - 1] === node.title
+                  const isVisited = activePath.includes(node.title)
+
+                  return (
+                    <button
+                      key={node.title}
+                      onClick={() => handleItemClick(node.title)}
+                      className={[
+                        "border-fm-divider-secondary w-full rounded-lg border px-3 py-2 text-left transition-colors",
+                        "text-fm-sm leading-fm-sm",
+                        isCurrent
+                          ? "bg-fm-surface-tertiary text-fm-primary font-medium"
+                          : isVisited
+                            ? "bg-fm-surface-secondary text-fm-primary"
+                            : "bg-fm-surface-primary text-fm-secondary hover:bg-fm-surface-tertiary",
+                      ].join(" ")}
+                    >
+                      {node.title}
+                    </button>
+                  )
+                })}
+              </div>
+            </div>
+
+            <div className="flex flex-col gap-3 lg:col-span-2">
+              <div className="border-fm-divider-secondary rounded-xl border bg-transparent p-6">
+                <div className="overflow-x-auto pb-1">
+                  <div className="min-w-max">
+                    <Breadcrumb
+                      items={breadcrumbItems}
+                      onItemClick={handleItemClick}
+                      size="md"
+                      separator="chevron"
+                    />
+                  </div>
+                </div>
+              </div>
+              <div className={codeBlockClass}>
+                <code className={`${codeClass} break-all`}>
+                  {`Current: ${activePath.join(" › ")}`}
+                </code>
+              </div>
+              <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">
+                  Click any breadcrumb item or jump directly from the left panel
+                  to simulate moving back through the hierarchy.
+                </p>
+              </div>
+            </div>
+          </div>
         </div>
       </div>
     )
   },
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        story:
+          "Live navigation simulation using useState. Click any breadcrumb item or a node in the panel to travel to that depth; the trail updates immediately to show the new active path.",
+      },
+    },
+  },
 }