@ceed/ads 1.29.1 → 1.30.0-next.1

package/dist/components/navigation/Breadcrumbs.md

@@ -2,9 +2,7 @@
 
 ## Introduction
 
-The Breadcrumbs component displays a navigation trail that helps users understand their current location within a hierarchical structure and navigate back to previous levels. Each level in the path is represented as a clickable link except for the current page, which is displayed as plain text.
-
-Breadcrumbs are essential for sites with deep navigation hierarchies -- they provide context at a glance, reduce the number of steps needed to return to higher-level pages, and improve overall wayfinding within an application.
+The Breadcrumbs component displays a navigation trail that helps users understand their current location within a website's hierarchy and navigate back to previous levels. It shows the path from the homepage to the current page, with each level represented as a clickable link (except for the current page). Breadcrumbs improve user experience by providing context and enabling quick navigation.
 
 ```tsx
 <Breadcrumbs
@@ -58,18 +56,18 @@ function MyComponent() {
     { label: 'Home', type: 'link', linkHref: '/' },
     { label: 'Products', type: 'link', linkHref: '/products' },
     { label: 'Electronics', type: 'link', linkHref: '/products/electronics' },
-    { label: 'Laptops', type: 'text' },
+    { label: 'Laptops', type: 'text' }, // Current page (not a link)
   ];
 
   return <Breadcrumbs crumbs={crumbs} />;
 }
 ```
 
-## Features
+## Examples
 
 ### Basic Breadcrumbs
 
-A simple breadcrumb trail with a few levels of hierarchy. The last item uses `type: 'text'` to indicate the current page.
+A simple breadcrumb navigation with three levels.
 
 ```tsx
 <Breadcrumbs
@@ -91,7 +89,7 @@ A simple breadcrumb trail with a few levels of hierarchy. The last item uses `ty
 
 ### Sizes
 
-Breadcrumbs are available in three sizes -- `sm`, `md`, and `lg` -- allowing you to match the surrounding layout density.
+Breadcrumbs support different sizes.
 
 ```tsx
 <div>
@@ -101,9 +99,9 @@ Breadcrumbs are available in three sizes -- `sm`, `md`, and `lg` -- allowing you
 </div>
 ```
 
-### Custom Separator
+### With Custom Separator
 
-The separator character between items can be customized via the `separator` prop. Common choices include `/`, `>`, and `-`.
+Customize the separator between breadcrumb items.
 
 ```tsx
 <div style={{
@@ -152,7 +150,45 @@ The separator character between items can be customized via the `separator` prop
 
 ### Collapsed Breadcrumbs
 
-When paths are deep, the component automatically collapses middle items behind an ellipsis. You can control how many items appear at the start and end using `startCrumbCount` and `endCrumbCount`.
+For deep hierarchies, breadcrumbs can be collapsed with an ellipsis.
+
+```tsx
+<Breadcrumbs
+  crumbs={[{
+  label: 'Home',
+  type: 'link',
+  linkHref: '/'
+}, {
+  label: 'Catalog',
+  type: 'link',
+  linkHref: '/'
+}, {
+  label: 'Category',
+  type: 'link',
+  linkHref: '/'
+}, {
+  label: 'Subcategory',
+  type: 'link',
+  linkHref: '/'
+}, {
+  label: 'Product',
+  type: 'link',
+  linkHref: '/'
+}, {
+  label: 'Product Detail',
+  type: 'link',
+  linkHref: '/'
+}, {
+  label: 'Owner',
+  type: 'text'
+}]}
+  collapsed
+/>
+```
+
+### Collapsed Variants
+
+Configure how many items show at the start and end when collapsed.
 
 ```tsx
 <div style={{
@@ -215,9 +251,23 @@ When paths are deep, the component automatically collapses middle items behind a
 </div>
 ```
 
+### Single Crumb
+
+When there's only one item in the path.
+
+```tsx
+<Breadcrumbs
+  crumbs={[{
+  label: 'Home',
+  type: 'text'
+}]}
+  collapsed
+/>
+```
+
 ### Expanded View
 
-Setting `collapsed={false}` renders every item in the path without collapsing.
+Show all breadcrumb items without collapsing.
 
 ```tsx
 <Breadcrumbs
@@ -253,80 +303,105 @@ Setting `collapsed={false}` renders every item in the path without collapsing.
 />
 ```
 
-### Single Crumb
+## When to Use
 
-The component handles the edge case of a single breadcrumb item gracefully.
+### ✅ Good Use Cases
 
-```tsx
-<Breadcrumbs
-  crumbs={[{
-  label: 'Home',
-  type: 'text'
-}]}
-  collapsed
-/>
-```
+- **Deep hierarchies**: Sites with 3+ levels of navigation depth
+- **E-commerce sites**: Product category → subcategory → product navigation
+- **Documentation sites**: Section → topic → article navigation
+- **File management**: Folder → subfolder → file navigation
+- **Admin dashboards**: Module → submodule → detail view
+- **Content management**: Categories and nested content structures
 
-### With Icons
+### ❌ When Not to Use
 
-Breadcrumb items can include icons alongside their labels.
+- **Flat sites**: Single-level navigation doesn't need breadcrumbs
+- **Linear flows**: For sequential processes, use Stepper instead
+- **Primary navigation**: Breadcrumbs supplement, not replace, main navigation
+- **Mobile-first**: Consider if space allows; may need alternative patterns
+- **Dynamic content**: When paths frequently change or are user-specific
+
+## Common Use Cases
+
+### E-commerce Product Page
 
 ```tsx
-<Breadcrumbs {...args} crumbs={[{
-  label: 'Home',
-  type: 'link',
-  linkHref: '/'
-}, {
-  label: 'Settings',
-  type: 'link',
-  linkHref: '/settings'
-}, {
-  label: 'Profile',
-  type: 'text'
-}]} collapsed={false} />
+function ProductPage({ product, category, subcategory }) {
+  const crumbs = [
+    { label: 'Home', type: 'link', linkHref: '/' },
+    { label: 'Shop', type: 'link', linkHref: '/shop' },
+    { label: category.name, type: 'link', linkHref: `/shop/${category.slug}` },
+    { label: subcategory.name, type: 'link', linkHref: `/shop/${category.slug}/${subcategory.slug}` },
+    { label: product.name, type: 'text' },
+  ];
+
+  return (
+    <Box>
+      <Breadcrumbs crumbs={crumbs} />
+      <ProductDetails product={product} />
+    </Box>
+  );
+}
 ```
 
-## Common Use Cases
+### Documentation Page
+
+```tsx
+function DocPage({ section, topic, article }) {
+  const crumbs = [
+    { label: 'Docs', type: 'link', linkHref: '/docs' },
+    { label: section.title, type: 'link', linkHref: `/docs/${section.slug}` },
+    { label: topic.title, type: 'link', linkHref: `/docs/${section.slug}/${topic.slug}` },
+    { label: article.title, type: 'text' },
+  ];
+
+  return (
+    <Stack spacing={2}>
+      <Breadcrumbs crumbs={crumbs} size="sm" />
+      <Typography level="h1">{article.title}</Typography>
+      <ArticleContent content={article.content} />
+    </Stack>
+  );
+}
+```
 
-### Admin Dashboard Navigation
+### File Browser
 
 ```tsx
-function UserDetailPage({ user }) {
+function FileBrowser({ path }) {
   const crumbs = [
-    { label: 'Dashboard', type: 'link', linkHref: '/admin' },
-    { label: 'Users', type: 'link', linkHref: '/admin/users' },
-    { label: user.name, type: 'text' },
+    { label: 'Root', type: 'link', linkHref: '/files' },
+    ...path.map((folder, index) => ({
+      label: folder.name,
+      type: index === path.length - 1 ? 'text' : 'link',
+      linkHref: `/files/${path.slice(0, index + 1).map(f => f.id).join('/')}`,
+    })),
   ];
 
   return (
     <Box>
-      <Breadcrumbs crumbs={crumbs} />
-      <UserProfile user={user} />
+      <Breadcrumbs crumbs={crumbs} collapsed={path.length > 4} />
+      <FileList folderId={path[path.length - 1].id} />
     </Box>
   );
 }
 ```
 
-### E-commerce Product Page
+### Admin Dashboard
 
 ```tsx
-function ProductPage({ product, category, subcategory }) {
+function UserDetailPage({ user }) {
   const crumbs = [
-    { label: 'Home', type: 'link', linkHref: '/' },
-    { label: 'Shop', type: 'link', linkHref: '/shop' },
-    { label: category.name, type: 'link', linkHref: `/shop/${category.slug}` },
-    {
-      label: subcategory.name,
-      type: 'link',
-      linkHref: `/shop/${category.slug}/${subcategory.slug}`,
-    },
-    { label: product.name, type: 'text' },
+    { label: 'Dashboard', type: 'link', linkHref: '/admin' },
+    { label: 'Users', type: 'link', linkHref: '/admin/users' },
+    { label: user.name, type: 'text' },
   ];
 
   return (
     <Box>
-      <Breadcrumbs crumbs={crumbs} collapsed={true} startCrumbCount={1} endCrumbCount={2} />
-      <ProductDetails product={product} />
+      <Breadcrumbs crumbs={crumbs} />
+      <UserProfile user={user} />
     </Box>
   );
 }
@@ -337,55 +412,222 @@ function ProductPage({ product, category, subcategory }) {
 ```tsx
 function DynamicBreadcrumbs() {
   const location = useLocation();
-  const pathnames = location.pathname.split('/').filter(Boolean);
+  const pathnames = location.pathname.split('/').filter((x) => x);
 
   const crumbs = [
     { label: 'Home', type: 'link', linkHref: '/' },
-    ...pathnames.map((value, index) => ({
-      label: formatLabel(value),
-      type: index === pathnames.length - 1 ? 'text' : 'link',
-      linkHref: `/${pathnames.slice(0, index + 1).join('/')}`,
-    })),
+    ...pathnames.map((value, index) => {
+      const href = `/${pathnames.slice(0, index + 1).join('/')}`;
+      const isLast = index === pathnames.length - 1;
+
+      return {
+        label: formatLabel(value),
+        type: isLast ? 'text' : 'link',
+        linkHref: href,
+      };
+    }),
   ];
 
   return <Breadcrumbs crumbs={crumbs} />;
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop              | Type                   | Default | Description                                     |
+| ----------------- | ---------------------- | ------- | ----------------------------------------------- |
+| `crumbs`          | `Crumb[]`              | `[]`    | Array of breadcrumb items                       |
+| `collapsed`       | `boolean`              | `true`  | Collapse middle items with ellipsis             |
+| `startCrumbCount` | `number`               | `1`     | Number of items to show at start when collapsed |
+| `endCrumbCount`   | `number`               | `3`     | Number of items to show at end when collapsed   |
+| `separator`       | `string`               | `'/'`   | Separator between items                         |
+| `size`            | `'sm' \| 'md' \| 'lg'` | `'md'`  | Size of the breadcrumbs                         |
+
+### Crumb Type
+
+```tsx
+interface Crumb {
+  label: string;            // Display text
+  type: 'link' | 'text';    // Link or static text
+  linkHref?: string;        // URL for link type
+}
+```
+
+### Collapsed Behavior
+
+When `collapsed` is true and there are more items than `startCrumbCount + endCrumbCount`, middle items are replaced with an ellipsis:
+
+```tsx
+// With startCrumbCount=1, endCrumbCount=2, and 6 crumbs:
+// Home / ... / Category / Product
+
+<Breadcrumbs
+  crumbs={crumbs}
+  collapsed={true}
+  startCrumbCount={1}
+  endCrumbCount={2}
+/>
+```
+
+### Custom Styling
+
+```tsx
+<Breadcrumbs
+  crumbs={crumbs}
+  sx={{
+    '& .MuiBreadcrumbs-separator': {
+      mx: 1,
+      color: 'neutral.400',
+    },
+    '& a': {
+      color: 'primary.500',
+      textDecoration: 'none',
+      '&:hover': {
+        textDecoration: 'underline',
+      },
+    },
+  }}
+/>
+```
+
+## Accessibility
+
+Breadcrumbs include important accessibility features:
+
+### Semantic HTML
+
+- Uses `<nav>` element with `aria-label="breadcrumb"`
+- Structured as an ordered list (`<ol>`) to indicate sequence
+- Current page marked with `aria-current="page"`
+
+### ARIA Attributes
+
+```tsx
+// Generated HTML structure
+<nav aria-label="breadcrumb">
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li><a href="/products">Products</a></li>
+    <li aria-current="page">Current Page</li>
+  </ol>
+</nav>
+```
+
+### Keyboard Navigation
+
+- **Tab**: Navigate through breadcrumb links
+- **Enter**: Activate the focused link
+
+### Screen Reader Support
+
+- Screen readers announce "breadcrumb navigation"
+- Each link is announced with its position in the sequence
+- Current page is identified as the current location
+
+### SEO Benefits
+
+Breadcrumbs provide:
+
+- Clear site structure for search engines
+- Enhanced search result display (rich snippets)
+- Improved internal linking
+
 ## Best Practices
 
-- **Always start with a root item.** Begin the trail with "Home" or an equivalent top-level link so users can always navigate back to the starting point.
+### ✅ Do
+
+1. **Start with Home**: Always begin with a link to the homepage
 
 ```tsx
-// Good
+// ✅ Good: Starts with Home
 const crumbs = [
   { label: 'Home', type: 'link', linkHref: '/' },
-  { label: 'Settings', type: 'text' },
+  { label: 'Products', type: 'link', linkHref: '/products' },
+  { label: 'Laptops', type: 'text' },
 ];
-
-// Bad -- missing root item
-const crumbs = [{ label: 'Settings', type: 'text' }];
 ```
 
-- **Make the current page non-clickable.** The last item in the trail should use `type: 'text'` since clicking the current page serves no purpose.
+2. **Make current page non-clickable**: The last item should be text, not a link
 
 ```tsx
-// Good
+// ✅ Good: Current page is text
 { label: 'Current Page', type: 'text' }
 
-// Bad
+// ❌ Bad: Current page is a link
 { label: 'Current Page', type: 'link', linkHref: '/current' }
 ```
 
-- **Use collapsing for deep hierarchies.** When paths exceed four or five levels, enable `collapsed` to keep the UI clean and avoid horizontal overflow.
+3. **Use clear, concise labels**: Keep labels short but descriptive
 
-- **Keep labels concise.** Breadcrumb labels should be short but descriptive. Match them to the corresponding page titles for consistency.
+4. **Maintain consistency**: Use the same labels as page titles or navigation
 
-- **Do not use breadcrumbs as primary navigation.** They are a supplementary wayfinding aid, not a replacement for the main navigation menu.
+5. **Position at top**: Place breadcrumbs near the top of the page, below the header
 
-## Accessibility
+### ❌ Don't
+
+1. **Don't use as primary navigation**: Breadcrumbs supplement main navigation
+
+2. **Don't duplicate with page title**: If the current page title is visible, breadcrumbs can end with the parent
+
+```tsx
+// Consider ending at parent if title is displayed
+const crumbs = [
+  { label: 'Home', type: 'link', linkHref: '/' },
+  { label: 'Products', type: 'link', linkHref: '/products' },
+  // Omit if "Laptops" is shown as page title
+];
+```
+
+3. **Don't use for flat navigation**: Sites with only one or two levels don't need breadcrumbs
+
+4. **Don't hide on mobile carelessly**: Either show a simplified version or omit entirely
+
+## Performance Considerations
+
+### Memoize Crumbs
+
+When breadcrumbs are computed from props or state, memoize them:
+
+```tsx
+const crumbs = useMemo(() => [
+  { label: 'Home', type: 'link', linkHref: '/' },
+  { label: category.name, type: 'link', linkHref: `/category/${category.id}` },
+  { label: product.name, type: 'text' },
+], [category, product]);
+
+<Breadcrumbs crumbs={crumbs} />
+```
+
+### Use Collapsed for Deep Hierarchies
+
+For paths with many levels, use collapsing to reduce DOM elements:
+
+```tsx
+<Breadcrumbs
+  crumbs={deepHierarchy}
+  collapsed={true}
+  startCrumbCount={1}
+  endCrumbCount={2}
+/>
+```
+
+### Lazy Load for Dynamic Breadcrumbs
+
+If breadcrumb data requires fetching, ensure it doesn't block page render:
+
+```tsx
+function Page() {
+  const { data: breadcrumbData, isLoading } = useBreadcrumbPath();
+
+  return (
+    <Box>
+      {!isLoading && <Breadcrumbs crumbs={breadcrumbData} />}
+      <PageContent />
+    </Box>
+  );
+}
+```
 
-- **Semantic HTML**: The component renders a `<nav>` element with `aria-label="breadcrumb"` and an ordered list (`<ol>`) to convey the sequential nature of the trail.
-- **Current page indicator**: The last item is automatically marked with `aria-current="page"` so screen readers announce the user's current location.
-- **Keyboard navigation**: All link items are focusable with `Tab` and activated with `Enter`, following standard keyboard interaction patterns.
-- **Screen readers**: The navigation landmark is announced as "breadcrumb navigation" and each link communicates its position within the path hierarchy.
+Breadcrumbs are a simple but powerful navigation aid that helps users understand where they are and navigate efficiently. Use them consistently across your site to improve user experience and SEO.