@ceed/ads 1.23.3 → 1.23.5

package/dist/components/navigation/Breadcrumbs.md

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-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.
+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.
 
 ```tsx
 <Breadcrumbs
@@ -56,18 +58,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' }, // Current page (not a link)
+    { label: 'Laptops', type: 'text' },
   ];
 
   return <Breadcrumbs crumbs={crumbs} />;
 }
 ```
 
-## Examples
+## Features
 
 ### Basic Breadcrumbs
 
-A simple breadcrumb navigation with three levels.
+A simple breadcrumb trail with a few levels of hierarchy. The last item uses `type: 'text'` to indicate the current page.
 
 ```tsx
 <Breadcrumbs
@@ -89,7 +91,7 @@ A simple breadcrumb navigation with three levels.
 
 ### Sizes
 
-Breadcrumbs support different sizes.
+Breadcrumbs are available in three sizes -- `sm`, `md`, and `lg` -- allowing you to match the surrounding layout density.
 
 ```tsx
 <div>
@@ -99,9 +101,9 @@ Breadcrumbs support different sizes.
 </div>
 ```
 
-### With Custom Separator
+### Custom Separator
 
-Customize the separator between breadcrumb items.
+The separator character between items can be customized via the `separator` prop. Common choices include `/`, `>`, and `-`.
 
 ```tsx
 <div style={{
@@ -150,45 +152,7 @@ Customize the separator between breadcrumb items.
 
 ### Collapsed Breadcrumbs
 
-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.
+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`.
 
 ```tsx
 <div style={{
@@ -251,23 +215,9 @@ Configure how many items show at the start and end when collapsed.
 </div>
 ```
 
-### Single Crumb
-
-When there's only one item in the path.
-
-```tsx
-<Breadcrumbs
-  crumbs={[{
-  label: 'Home',
-  type: 'text'
-}]}
-  collapsed
-/>
-```
-
 ### Expanded View
 
-Show all breadcrumb items without collapsing.
+Setting `collapsed={false}` renders every item in the path without collapsing.
 
 ```tsx
 <Breadcrumbs
@@ -303,105 +253,80 @@ Show all breadcrumb items without collapsing.
 />
 ```
 
-## When to Use
-
-### ✅ Good Use Cases
-
-- **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
-
-### ❌ When Not to Use
-
-- **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
+### Single Crumb
 
-## Common Use Cases
-
-### E-commerce Product Page
+The component handles the edge case of a single breadcrumb item gracefully.
 
 ```tsx
-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>
-  );
-}
+<Breadcrumbs
+  crumbs={[{
+  label: 'Home',
+  type: 'text'
+}]}
+  collapsed
+/>
 ```
 
-### Documentation Page
+### With Icons
 
-```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' },
-  ];
+Breadcrumb items can include icons alongside their labels.
 
-  return (
-    <Stack spacing={2}>
-      <Breadcrumbs crumbs={crumbs} size="sm" />
-      <Typography level="h1">{article.title}</Typography>
-      <ArticleContent content={article.content} />
-    </Stack>
-  );
-}
+```tsx
+<Breadcrumbs {...args} crumbs={[{
+  label: 'Home',
+  type: 'link',
+  linkHref: '/'
+}, {
+  label: 'Settings',
+  type: 'link',
+  linkHref: '/settings'
+}, {
+  label: 'Profile',
+  type: 'text'
+}]} collapsed={false} />
 ```
 
-### File Browser
+## Common Use Cases
+
+### Admin Dashboard Navigation
 
 ```tsx
-function FileBrowser({ path }) {
+function UserDetailPage({ user }) {
   const crumbs = [
-    { 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('/')}`,
-    })),
+    { label: 'Dashboard', type: 'link', linkHref: '/admin' },
+    { label: 'Users', type: 'link', linkHref: '/admin/users' },
+    { label: user.name, type: 'text' },
   ];
 
   return (
     <Box>
-      <Breadcrumbs crumbs={crumbs} collapsed={path.length > 4} />
-      <FileList folderId={path[path.length - 1].id} />
+      <Breadcrumbs crumbs={crumbs} />
+      <UserProfile user={user} />
     </Box>
   );
 }
 ```
 
-### Admin Dashboard
+### E-commerce Product Page
 
 ```tsx
-function UserDetailPage({ user }) {
+function ProductPage({ product, category, subcategory }) {
   const crumbs = [
-    { label: 'Dashboard', type: 'link', linkHref: '/admin' },
-    { label: 'Users', type: 'link', linkHref: '/admin/users' },
-    { label: user.name, type: 'text' },
+    { 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} />
-      <UserProfile user={user} />
+      <Breadcrumbs crumbs={crumbs} collapsed={true} startCrumbCount={1} endCrumbCount={2} />
+      <ProductDetails product={product} />
     </Box>
   );
 }
@@ -412,222 +337,55 @@ function UserDetailPage({ user }) {
 ```tsx
 function DynamicBreadcrumbs() {
   const location = useLocation();
-  const pathnames = location.pathname.split('/').filter((x) => x);
+  const pathnames = location.pathname.split('/').filter(Boolean);
 
   const crumbs = [
     { label: 'Home', type: 'link', linkHref: '/' },
-    ...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,
-      };
-    }),
+    ...pathnames.map((value, index) => ({
+      label: formatLabel(value),
+      type: index === pathnames.length - 1 ? 'text' : 'link',
+      linkHref: `/${pathnames.slice(0, index + 1).join('/')}`,
+    })),
   ];
 
   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
 
-### ✅ Do
-
-1. **Start with Home**: Always begin with a link to the homepage
+- **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.
 
 ```tsx
-// ✅ Good: Starts with Home
+// Good
 const crumbs = [
   { label: 'Home', type: 'link', linkHref: '/' },
-  { label: 'Products', type: 'link', linkHref: '/products' },
-  { label: 'Laptops', type: 'text' },
+  { label: 'Settings', type: 'text' },
 ];
+
+// Bad -- missing root item
+const crumbs = [{ label: 'Settings', type: 'text' }];
 ```
 
-2. **Make current page non-clickable**: The last item should be text, not a link
+- **Make the current page non-clickable.** The last item in the trail should use `type: 'text'` since clicking the current page serves no purpose.
 
 ```tsx
-// ✅ Good: Current page is text
+// Good
 { label: 'Current Page', type: 'text' }
 
-// ❌ Bad: Current page is a link
+// Bad
 { label: 'Current Page', type: 'link', linkHref: '/current' }
 ```
 
-3. **Use clear, concise labels**: Keep labels short but descriptive
-
-4. **Maintain consistency**: Use the same labels as page titles or navigation
-
-5. **Position at top**: Place breadcrumbs near the top of the page, below the header
-
-### ❌ 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
+- **Use collapsing for deep hierarchies.** When paths exceed four or five levels, enable `collapsed` to keep the UI clean and avoid horizontal overflow.
 
-## Performance Considerations
+- **Keep labels concise.** Breadcrumb labels should be short but descriptive. Match them to the corresponding page titles for consistency.
 
-### Memoize Crumbs
+- **Do not use breadcrumbs as primary navigation.** They are a supplementary wayfinding aid, not a replacement for the main navigation menu.
 
-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>
-  );
-}
-```
+## Accessibility
 
-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.
+- **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.