@repobit/dex-system-design 0.22.12 → 0.23.2

package/src/components/breadcrumb/breadcrumb.stories.js

@@ -2,272 +2,271 @@ import { html } from 'lit';
 import './breadcrumb.js';
 
 export default {
-  title        : 'Components/Breadcrumb',
-  component    : 'bd-breadcrumb',
-  subcomponents: { 'BreadcrumbItem': 'bd-breadcrumb-item' },
-  tags         : ['autodocs'],
-  argTypes     : {
+  title     : 'Components/Breadcrumb',
+  tags      : ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+**Breadcrumb** and **BreadcrumbItem** are Lit web components for rendering accessible breadcrumb navigation.
+
+Two elements are available:
+- \`<bd-breadcrumb>\` — the nav container, handles responsive orientation and resize detection
+- \`<bd-breadcrumb-item>\` — individual crumb items supporting links, current page, and dividers
+
+### Usage
+\`\`\`html
+<bd-breadcrumb>
+  <bd-breadcrumb-item href="/">Home</bd-breadcrumb-item>
+  <bd-breadcrumb-item href="/products">Products</bd-breadcrumb-item>
+  <bd-breadcrumb-item current>Total Security</bd-breadcrumb-item>
+</bd-breadcrumb>
+\`\`\`
+
+### Responsive Behavior
+| Width | Layout |
+|---|---|
+| \`> mobileBreakpoint\` (default 768px) | Horizontal |
+| \`≤ mobileBreakpoint\` | Vertical |
+
+### Item Rendering Logic
+| Condition | Rendered as |
+|---|---|
+| \`current\` | \`<span>\` with \`aria-current="page"\` |
+| \`href\` set | \`<bd-link>\` anchor |
+| Neither | Plain \`<span>\` |
+
+### Divider Logic
+- Divider \`/\` is shown after every non-current item unless \`no-trailing-slash\` is set on the container
+        `
+      }
+    }
+  },
+  argTypes: {
+    noTrailingSlash: {
+      control    : 'boolean',
+      description: 'When true, hides the `/` divider after non-current items',
+      table      : {
+        type        : { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+        category    : 'Breadcrumb'
+      }
+    },
     mobileBreakpoint: {
+      control    : { type: 'number' },
+      description: 'Pixel width at which the layout switches from horizontal to vertical',
+      table      : {
+        type        : { summary: 'number' },
+        defaultValue: { summary: '768' },
+        category    : 'Breadcrumb'
+      }
+    },
+    href: {
       control    : 'text',
-      description: 'Breakpoint for mobile responsive behavior',
+      description: 'URL for a breadcrumb item link',
       table      : {
         type        : { summary: 'string' },
-        defaultValue: { summary: '768px' }
+        defaultValue: { summary: '' },
+        category    : 'BreadcrumbItem'
+      }
+    },
+    current: {
+      control    : 'boolean',
+      description: 'Marks this item as the current page. Renders as a `<span>` with `aria-current="page"`.',
+      table      : {
+        type        : { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+        category    : 'BreadcrumbItem'
       }
     }
-  },
+  }
+};
+
+// ─── Stories ───────────────────────────────────────────────────────────────
+
+export const Default = {
+  name  : 'Default (3 items)',
+  render: () => html`
+    <bd-breadcrumb>
+      <bd-breadcrumb-item href="/">Home</bd-breadcrumb-item>
+      <bd-breadcrumb-item href="/products">Products</bd-breadcrumb-item>
+      <bd-breadcrumb-item current>Total Security</bd-breadcrumb-item>
+    </bd-breadcrumb>
+  `,
   parameters: {
     docs: {
       description: {
-        component: 'A navigation component that shows the current page location within a hierarchy. Supports responsive behavior and accessible navigation.'
+        story: 'Three-item breadcrumb: two linked items and one current page item. Dividers are shown after non-current items.'
       }
     }
   }
 };
 
-export const Default = () => html`
-  <bd-breadcrumb>
-    <bd-breadcrumb-item href="/">
-      Home
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/products">
-      Products
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/products/security">
-      Security
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item current>
-      Bitdefender Total Security
-    </bd-breadcrumb-item>
-  </bd-breadcrumb>
-`;
-Default.parameters = {
-  docs: {
-    description: {
-      story: 'Default breadcrumb navigation showing a typical product hierarchy. The current page is marked with the `current` attribute and is not clickable.'
+export const TwoItems = {
+  name  : 'Two Items',
+  render: () => html`
+    <bd-breadcrumb>
+      <bd-breadcrumb-item href="/">Home</bd-breadcrumb-item>
+      <bd-breadcrumb-item current>Products</bd-breadcrumb-item>
+    </bd-breadcrumb>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Minimal two-item breadcrumb with one link and one current item.'
+      }
     }
   }
 };
 
-export const WithNestedLinks = () => html`
-  <bd-breadcrumb>
-    <bd-breadcrumb-item href="/">
-      Home
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/products">
-      All Products
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/products/security">
-      Security Suite
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item current>
-      Internet Security 2024
-    </bd-breadcrumb-item>
-  </bd-breadcrumb>
-`;
-WithNestedLinks.parameters = {
-  docs: {
-    description: {
-      story: 'Breadcrumb with nested product categories demonstrating deep hierarchical navigation structure.'
+export const DeepNesting = {
+  name  : 'Deep Nesting (5 items)',
+  render: () => html`
+    <bd-breadcrumb>
+      <bd-breadcrumb-item href="/">Home</bd-breadcrumb-item>
+      <bd-breadcrumb-item href="/products">Products</bd-breadcrumb-item>
+      <bd-breadcrumb-item href="/products/security">Security</bd-breadcrumb-item>
+      <bd-breadcrumb-item href="/products/security/antivirus">Antivirus</bd-breadcrumb-item>
+      <bd-breadcrumb-item current>Bitdefender Total Security</bd-breadcrumb-item>
+    </bd-breadcrumb>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Five-level deep breadcrumb. Tests horizontal layout with many items and dividers.'
+      }
     }
   }
 };
 
-export const MixedItems = () => html`
-  <bd-breadcrumb>
-    <bd-breadcrumb-item href="/">
-      Home
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item>
-      Documentation
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/docs/components">
-      Components
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item current>
-      Breadcrumb
-    </bd-breadcrumb-item>
-  </bd-breadcrumb>
-`;
-MixedItems.parameters = {
-  docs: {
-    description: {
-      story: 'Breadcrumb with mixed navigation items - some are clickable links while others are non-clickable text nodes for intermediate hierarchy levels.'
+export const NoTrailingSlash = {
+  name  : 'No Trailing Slash',
+  render: () => html`
+    <bd-breadcrumb no-trailing-slash>
+      <bd-breadcrumb-item href="/">Home</bd-breadcrumb-item>
+      <bd-breadcrumb-item href="/products">Products</bd-breadcrumb-item>
+      <bd-breadcrumb-item current>Total Security</bd-breadcrumb-item>
+    </bd-breadcrumb>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: '`no-trailing-slash` applied to the container. The `/` divider is hidden after all non-current items. The prop is propagated to each child item via `updateNoTrailingSlash()`.'
+      }
     }
   }
 };
 
-export const LongPath = () => html`
-  <bd-breadcrumb>
-    <bd-breadcrumb-item href="/">
-      Home
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/categories">
-      Categories
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/categories/technology">
-      Technology
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/categories/technology/software">
-      Software
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/categories/technology/software/security">
-      Security Software
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item current>
-      Bitdefender Internet Security Complete Edition
-    </bd-breadcrumb-item>
-  </bd-breadcrumb>
-`;
-LongPath.parameters = {
-  docs: {
-    description: {
-      story: 'Breadcrumb with an extended hierarchical path showing how the component handles deep navigation structures and long product names.'
+export const AllLinked = {
+  name  : 'All Items Linked (no current)',
+  render: () => html`
+    <bd-breadcrumb>
+      <bd-breadcrumb-item href="/">Home</bd-breadcrumb-item>
+      <bd-breadcrumb-item href="/products">Products</bd-breadcrumb-item>
+      <bd-breadcrumb-item href="/products/security">Security</bd-breadcrumb-item>
+    </bd-breadcrumb>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: 'All items have `href` set and none are `current`. All render as `<bd-link>` elements with dividers.'
+      }
     }
   }
 };
 
-export const MobileView = () => html`
-  <div style="max-width: 400px; border: 1px solid #ccc; padding: 20px;">
-    <bd-breadcrumb mobile-breakpoint="1200">
-      <bd-breadcrumb-item href="/">
-        Home
-      </bd-breadcrumb-item>
-      <bd-breadcrumb-item href="/products">
-        Products
-      </bd-breadcrumb-item>
-      <bd-breadcrumb-item current>
-        Current Page
-      </bd-breadcrumb-item>
+export const NoLinks = {
+  name  : 'No Links (plain text items)',
+  render: () => html`
+    <bd-breadcrumb>
+      <bd-breadcrumb-item>Home</bd-breadcrumb-item>
+      <bd-breadcrumb-item>Products</bd-breadcrumb-item>
+      <bd-breadcrumb-item current>Total Security</bd-breadcrumb-item>
     </bd-breadcrumb>
-    <p style="margin-top: 20px; font-size: 12px; color: #666;">
-      This demo forces mobile view by setting breakpoint to 1200px.
-      Resize window to see responsive behavior.
-    </p>
-  </div>
-`;
-MobileView.parameters = {
-  docs: {
-    description: {
-      story: 'Mobile-optimized breadcrumb demonstration. The component automatically adapts to smaller screens by collapsing intermediate items when the viewport is below the specified breakpoint.'
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Items without `href` or `current` render as plain `<span>` elements. The last item uses `current` for the active page indicator.'
+      }
     }
   }
 };
 
-export const EcommerceExample = () => html`
-  <bd-breadcrumb>
-    <bd-breadcrumb-item href="/">
-      Home
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/electronics">
-      Electronics
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/electronics/computers">
-      Computers & Tablets
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/electronics/computers/laptops">
-      Laptops
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item current>
-      Gaming Laptops - High Performance
-    </bd-breadcrumb-item>
-  </bd-breadcrumb>
-`;
-EcommerceExample.parameters = {
-  docs: {
-    description: {
-      story: 'E-commerce style breadcrumb showing typical product categorization hierarchy commonly used in online shopping platforms.'
+export const SingleItem = {
+  name  : 'Single Item (edge case)',
+  render: () => html`
+    <bd-breadcrumb>
+      <bd-breadcrumb-item current>Home</bd-breadcrumb-item>
+    </bd-breadcrumb>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Edge case: only one item marked as current. No divider is shown.'
+      }
     }
   }
 };
 
-export const DocumentationExample = () => html`
-  <bd-breadcrumb>
-    <bd-breadcrumb-item href="/">
-      Home
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/help">
-      Help Center
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/help/getting-started">
-      Getting Started
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/help/getting-started/installation">
-      Installation Guide
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item current>
-      Troubleshooting
-    </bd-breadcrumb-item>
-  </bd-breadcrumb>
-`;
-DocumentationExample.parameters = {
-  docs: {
-    description: {
-      story: 'Documentation site breadcrumb demonstrating hierarchical navigation through help articles and documentation sections.'
+export const MobileVertical = {
+  name  : 'Mobile — Vertical Layout',
+  render: () => html`
+    <bd-breadcrumb>
+      <bd-breadcrumb-item href="/">Home</bd-breadcrumb-item>
+      <bd-breadcrumb-item href="/products">Products</bd-breadcrumb-item>
+      <bd-breadcrumb-item current>Total Security</bd-breadcrumb-item>
+    </bd-breadcrumb>
+  `,
+  parameters: {
+    viewport: { defaultViewport: 'mobile1' },
+    docs    : {
+      description: {
+        story: 'At 375px, the component detects mobile width (≤768px) and switches to a vertical layout via the `bd-breadcrumb--vertical` class.'
+      }
     }
   }
 };
 
-export const AccessibilityExample = () => html`
-  <bd-breadcrumb aria-label="Breadcrumb navigation">
-    <bd-breadcrumb-item href="/">
-      Home
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/accessibility">
-      Accessibility
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/accessibility/components">
-      Components
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item current>
-      Breadcrumb Best Practices
-    </bd-breadcrumb-item>
-  </bd-breadcrumb>
-  
-  <div style="margin-top: 2rem; padding: 1rem; background: #f5f5f5; border-radius: 4px;">
-    <h4 style="margin-top: 0;">Accessibility Features</h4>
-    <ul style="margin-bottom: 0;">
-      <li><strong>ARIA landmarks:</strong> Proper navigation role with aria-label</li>
-      <li><strong>Current page indication:</strong> aria-current="page" for active item</li>
-      <li><strong>Keyboard navigation:</strong> All links are keyboard accessible</li>
-      <li><strong>Semantic structure:</strong> Clear hierarchy for screen readers</li>
-    </ul>
-  </div>
-`;
-AccessibilityExample.parameters = {
-  docs: {
-    description: {
-      story: 'Accessibility-focused breadcrumb example demonstrating proper ARIA attributes and semantic HTML structure for screen reader compatibility and keyboard navigation.'
+export const CustomMobileBreakpoint = {
+  name  : 'Custom Mobile Breakpoint (480px)',
+  render: () => html`
+    <bd-breadcrumb mobile-breakpoint="480">
+      <bd-breadcrumb-item href="/">Home</bd-breadcrumb-item>
+      <bd-breadcrumb-item href="/products">Products</bd-breadcrumb-item>
+      <bd-breadcrumb-item current>Total Security</bd-breadcrumb-item>
+    </bd-breadcrumb>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: '`mobile-breakpoint` set to 480px instead of the default 768px. Layout switches to vertical only at very small widths.'
+      }
     }
   }
 };
 
-// Template for interactive controls
-const BreadcrumbTemplate = ({ mobileBreakpoint }) => html`
-  <bd-breadcrumb mobile-breakpoint="${mobileBreakpoint}">
-    <bd-breadcrumb-item href="/">
-      Home
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/products">
-      Products
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item href="/products/security">
-      Security
-    </bd-breadcrumb-item>
-    <bd-breadcrumb-item current>
-      Current Product
-    </bd-breadcrumb-item>
-  </bd-breadcrumb>
-`;
-
-export const InteractiveExample = BreadcrumbTemplate.bind({});
-InteractiveExample.args = {
-  mobileBreakpoint: '768px'
-};
-InteractiveExample.parameters = {
-  docs: {
-    description: {
-      story: 'Interactive breadcrumb example. Use the controls panel to adjust the mobile breakpoint and see how it affects the responsive behavior.'
+export const Playground = {
+  name: '🛝 Playground',
+  args: {
+    noTrailingSlash : false,
+    mobileBreakpoint: 768
+  },
+  render: (args) => html`
+    <bd-breadcrumb
+      ?no-trailing-slash="${args.noTrailingSlash}"
+      mobile-breakpoint="${args.mobileBreakpoint}"
+    >
+      <bd-breadcrumb-item href="/">Home</bd-breadcrumb-item>
+      <bd-breadcrumb-item href="/products">Products</bd-breadcrumb-item>
+      <bd-breadcrumb-item current>Total Security</bd-breadcrumb-item>
+    </bd-breadcrumb>
+  `,
+  parameters: {
+    docs: {
+      description: {
+        story: 'Interactive playground. Toggle `no-trailing-slash` and adjust `mobile-breakpoint` via Controls.'
+      }
     }
   }
 };