@ceed/cds 1.28.1 → 1.29.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,26 @@ 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 navigation with three levels.
+
+```
+<Canvas of={Breadcrumbs.BasicExample} />
+```
 
 ### 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>
@@ -79,9 +85,17 @@ Breadcrumbs are available in three sizes -- `sm`, `md`, and `lg` -- allowing you
 </div>
 ```
 
-### Custom Separator
+### With Custom Separator
+
+Customize the separator between breadcrumb items.
+
+```
+<Canvas of={Breadcrumbs.CustomSeparator} />
+```
 
-The separator character between items can be customized via the `separator` prop. Common choices include `/`, `>`, and `-`.
+### Collapsed Breadcrumbs
+
+For deep hierarchies, breadcrumbs can be collapsed with an ellipsis.
 
 ```tsx
 <Breadcrumbs
@@ -114,13 +128,34 @@ The separator character between items can be customized via the `separator` prop
   type: 'text'
 }]}
   collapsed
-  separator="-"
+/>
+```
+
+### Collapsed Variants
+
+Configure how many items show at the start and end when collapsed.
+
+```
+<Canvas of={Breadcrumbs.CollapsedVariants} />
+```
+
+### 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
@@ -156,56 +191,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
+
+### ❌ 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
 
 ## Common Use Cases
 
-### Service Detail Page
+### E-commerce Product Page
 
 ```tsx
-function ServiceDetailPage({ service, category }) {
+function ProductPage({ product, category, subcategory }) {
   const crumbs = [
     { label: 'Home', type: 'link', linkHref: '/' },
-    { label: 'Services', type: 'link', linkHref: '/services' },
-    { label: category.name, type: 'link', linkHref: `/services/${category.slug}` },
-    { label: service.name, type: 'text' },
+    { 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} />
-      <ServiceDetails service={service} />
+      <ProductDetails product={product} />
     </Box>
   );
 }
 ```
 
-### Account Settings
+### Documentation Page
 
 ```tsx
-function AccountSettingsPage() {
+function DocPage({ section, topic, article }) {
   const crumbs = [
-    { label: 'Home', type: 'link', linkHref: '/' },
-    { label: 'Account', type: 'link', linkHref: '/account' },
-    { label: 'Settings', type: 'text' },
+    { 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 (
-    <Box>
+    <Stack spacing={2}>
       <Breadcrumbs crumbs={crumbs} size="sm" />
-      <SettingsForm />
+      <Typography level="h1">{article.title}</Typography>
+      <ArticleContent content={article.content} />
+    </Stack>
+  );
+}
+```
+
+### File Browser
+
+```tsx
+function FileBrowser({ path }) {
+  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('/')}`,
+    })),
+  ];
+
+  return (
+    <Box>
+      <Breadcrumbs crumbs={crumbs} collapsed={path.length > 4} />
+      <FileList folderId={path[path.length - 1].id} />
+    </Box>
+  );
+}
+```
+
+### Admin Dashboard
+
+```tsx
+function UserDetailPage({ user }) {
+  const crumbs = [
+    { label: 'Dashboard', type: 'link', linkHref: '/admin' },
+    { label: 'Users', type: 'link', linkHref: '/admin/users' },
+    { label: user.name, type: 'text' },
+  ];
+
+  return (
+    <Box>
+      <Breadcrumbs crumbs={crumbs} />
+      <UserProfile user={user} />
     </Box>
   );
 }
@@ -216,55 +300,222 @@ function AccountSettingsPage() {
 ```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.

package/dist/components/navigation/Drawer.md

@@ -2,10 +2,6 @@
 
 ## Introduction
 
-The Drawer component is a panel that slides in from the edge of the screen, overlaying the main content to present secondary information, navigation, or actions. Built on top of Joy UI's Drawer with Framer Motion animation, it provides smooth entrance and exit transitions out of the box.
-
-Drawer supports three size presets (`sm`, `md`, `lg`) which control the panel width on horizontal anchors and height on vertical anchors. On smaller viewports (below `md` breakpoint), the drawer automatically expands to full width for an optimized mobile experience.
-
 ```tsx
 <Drawer
   open
@@ -28,180 +24,4 @@ Drawer supports three size presets (`sm`, `md`, `lg`) which control the panel wi
 
 ```tsx
 import { Drawer } from '@ceed/cds';
-
-function MyComponent() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <>
-      <Button onClick={() => setOpen(true)}>Open Drawer</Button>
-      <Drawer open={open} onClose={() => setOpen(false)}>
-        <Box sx={{ p: 2, backgroundColor: 'white', height: '100%' }}>
-          <Typography level="title-lg">Drawer Content</Typography>
-          <Typography level="body-md">
-            Place your navigation, detail view, or form content here.
-          </Typography>
-        </Box>
-      </Drawer>
-    </>
-  );
-}
-```
-
-## Default
-
-The default Drawer displays a panel sliding in from the left with the `md` size preset.
-
-```tsx
-<Drawer
-  open
-  children={<Box sx={{
-  width: '100%',
-  height: '100%',
-  backgroundColor: 'white',
-  boxShadow: 'var(--ceed-shadowRing, 0 0 #000),0px 2px 8px -2px rgba(var(--ceed-shadowChannel, 21 21 21) / var(--ceed-shadowOpacity, 0.08)),0px 6px 12px -2px rgba(var(--ceed-shadowChannel, 21 21 21) / var(--ceed-shadowOpacity, 0.08))'
-}}>
-        asdas
-      </Box>}
-/>
-```
-
-## Common Use Cases
-
-### Navigation Drawer
-
-```tsx
-function NavigationDrawer({ open, onClose }) {
-  const navItems = [
-    { label: 'Home', icon: <HomeIcon />, path: '/' },
-    { label: 'Orders', icon: <ListIcon />, path: '/orders' },
-    { label: 'Account', icon: <PersonIcon />, path: '/account' },
-  ];
-
-  return (
-    <Drawer open={open} onClose={onClose} size="sm">
-      <Box sx={{ p: 2, backgroundColor: 'white', height: '100%' }}>
-        <Typography level="title-lg" sx={{ mb: 2 }}>Menu</Typography>
-        <List>
-          {navItems.map((item) => (
-            <ListItem key={item.path}>
-              <ListItemButton onClick={() => { navigate(item.path); onClose(); }}>
-                <ListItemDecorator>{item.icon}</ListItemDecorator>
-                {item.label}
-              </ListItemButton>
-            </ListItem>
-          ))}
-        </List>
-      </Box>
-    </Drawer>
-  );
-}
 ```
-
-### Detail View
-
-```tsx
-function DetailDrawer({ open, onClose, selectedItem }) {
-  return (
-    <Drawer open={open} onClose={onClose} anchor="right" size="lg">
-      <Box
-        sx={{
-          p: 3,
-          backgroundColor: 'white',
-          height: '100%',
-          display: 'flex',
-          flexDirection: 'column',
-        }}
-      >
-        <Box sx={{ display: 'flex', justifyContent: 'space-between', mb: 2 }}>
-          <Typography level="title-lg">{selectedItem?.name}</Typography>
-          <IconButton onClick={onClose}><CloseIcon /></IconButton>
-        </Box>
-        <Divider />
-        <Box sx={{ flex: 1, overflow: 'auto', mt: 2 }}>
-          {/* Detail content */}
-        </Box>
-      </Box>
-    </Drawer>
-  );
-}
-```
-
-### Form Drawer
-
-```tsx
-function FormDrawer({ open, onClose, onSubmit }) {
-  return (
-    <Drawer open={open} onClose={onClose} anchor="right" size="md">
-      <Box
-        sx={{
-          p: 3,
-          backgroundColor: 'white',
-          height: '100%',
-          display: 'flex',
-          flexDirection: 'column',
-        }}
-      >
-        <Typography level="title-lg" sx={{ mb: 2 }}>Create New Item</Typography>
-        <Divider />
-        <Box sx={{ flex: 1, overflow: 'auto', my: 2 }}>
-          <Stack gap={2}>
-            <Input label="Name" placeholder="Enter name" />
-            <Textarea label="Description" placeholder="Enter description" minRows={3} />
-          </Stack>
-        </Box>
-        <Divider />
-        <Stack direction="row" gap={1} sx={{ mt: 2, justifyContent: 'flex-end' }}>
-          <Button variant="outlined" color="neutral" onClick={onClose}>Cancel</Button>
-          <Button onClick={onSubmit}>Save</Button>
-        </Stack>
-      </Box>
-    </Drawer>
-  );
-}
-```
-
-## Best Practices
-
-1. **Choose the right size**: Use `sm` (360px) for simple navigation, `md` (600px) for moderate content, and `lg` (900px) for complex detail views or forms.
-
-```tsx
-// ✅ Good: Size matches content complexity
-<Drawer size="sm">  {/* Simple nav list */}
-<Drawer size="md">  {/* Filter panel or form */}
-<Drawer size="lg">  {/* Detailed information view */}
-```
-
-2. **Provide visible close affordances**: Always include a close button or cancel action inside the Drawer content, in addition to the backdrop click.
-
-```tsx
-// ✅ Good: Close button inside the drawer
-<Drawer open={open} onClose={onClose}>
-  <Box>
-    <IconButton onClick={onClose}><CloseIcon /></IconButton>
-    {/* Content */}
-  </Box>
-</Drawer>
-```
-
-3. **Apply proper background and shadow styling**: The Drawer renders children directly, so you should apply background color and shadow to your content container for visual clarity.
-
-```tsx
-// ✅ Good: Styled content container
-<Drawer open={open}>
-  <Box sx={{ backgroundColor: 'white', height: '100%', boxShadow: 'md', p: 2 }}>
-    {/* Content */}
-  </Box>
-</Drawer>
-```
-
-4. **Do not use Drawer for confirmations**: For simple yes/no prompts, use Dialog instead. Drawer is designed for richer, scrollable content.
-
-5. **Structure content with header, body, and footer**: Use a flex column layout to keep the header and footer fixed while allowing the body to scroll.
-
-## Accessibility
-
-- The Drawer overlay traps focus within the panel when open, preventing keyboard users from interacting with background content.
-- Pressing **Escape** closes the Drawer. **Tab** and **Shift+Tab** cycle through focusable elements within the Drawer content.
-- On mobile viewports, the Drawer automatically expands to full width, ensuring touch targets remain accessible and content is not clipped.
-- Provide an `aria-label` or visible heading within the Drawer content to describe the panel's purpose for screen reader users.