@ceed/cds 1.28.1 → 1.29.1

package/dist/components/navigation/Breadcrumbs.md

@@ -67,6 +67,14 @@ function MyComponent() {
 
 ## Features
 
+### Basic Breadcrumbs
+
+A simple breadcrumb trail with a few levels of hierarchy. The last item uses `type: 'text'` to indicate the current page.
+
+```
+<Canvas of={Breadcrumbs.BasicExample} />
+```
+
 ### Sizes
 
 Breadcrumbs are available in three sizes -- `sm`, `md`, and `lg` -- allowing you to match the surrounding layout density.
@@ -83,39 +91,16 @@ Breadcrumbs are available in three sizes -- `sm`, `md`, and `lg` -- allowing you
 
 The separator character between items can be customized via the `separator` prop. Common choices include `/`, `>`, and `-`.
 
-```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
-  separator="-"
-/>
+```
+<Canvas of={Breadcrumbs.CustomSeparator} />
+```
+
+### 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`.
+
+```
+<Canvas of={Breadcrumbs.CollapsedVariants} />
 ```
 
 ### Expanded View
@@ -170,42 +155,55 @@ The component handles the edge case of a single breadcrumb item gracefully.
 />
 ```
 
+### With Icons
+
+Breadcrumb items can include icons alongside their labels.
+
+```
+<Canvas of={Breadcrumbs.WithIcons} />
+```
+
 ## Common Use Cases
 
-### Service Detail Page
+### Admin Dashboard Navigation
 
 ```tsx
-function ServiceDetailPage({ service, category }) {
+function UserDetailPage({ user }) {
   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: 'Dashboard', type: 'link', linkHref: '/admin' },
+    { label: 'Users', type: 'link', linkHref: '/admin/users' },
+    { label: user.name, type: 'text' },
   ];
 
   return (
     <Box>
       <Breadcrumbs crumbs={crumbs} />
-      <ServiceDetails service={service} />
+      <UserProfile user={user} />
     </Box>
   );
 }
 ```
 
-### Account Settings
+### E-commerce Product Page
 
 ```tsx
-function AccountSettingsPage() {
+function ProductPage({ product, category, subcategory }) {
   const crumbs = [
     { label: 'Home', type: 'link', linkHref: '/' },
-    { label: 'Account', type: 'link', linkHref: '/account' },
-    { label: 'Settings', 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} size="sm" />
-      <SettingsForm />
+      <Breadcrumbs crumbs={crumbs} collapsed={true} startCrumbCount={1} endCrumbCount={2} />
+      <ProductDetails product={product} />
     </Box>
   );
 }
@@ -231,6 +229,19 @@ function DynamicBreadcrumbs() {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop              | Type                                                             | Default                          | Description                                          |
+| ----------------- | ---------------------------------------------------------------- | -------------------------------- | ---------------------------------------------------- |
+| `crumbs`          | `{ type: 'text' \| 'link'; label: string; linkHref?: string }[]` | (required)                       | Breadcrumb items                                     |
+| `collapsed`       | `boolean`                                                        | `true`                           | Whether long crumb lists are collapsed with ellipsis |
+| `startCrumbCount` | `number`                                                         | `1`                              | Number of crumbs shown at the start when collapsed   |
+| `endCrumbCount`   | `number`                                                         | `3`                              | Number of crumbs shown at the end when collapsed     |
+| `slots`           | `{ link?: ElementType }`                                         | -                                | Custom component for link crumbs                     |
+| `slotProps`       | `{ link?: { color?: string } }`                                  | `{ link: { color: 'neutral' } }` | Props passed to slot components                      |
+
 ## 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.

package/dist/components/navigation/Drawer.md

@@ -161,6 +161,23 @@ function FormDrawer({ open, onClose, onSubmit }) {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop       | Type                                                           | Default                          | Description                                                                |                                                                                |
+| ---------- | -------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| `children` | `ReactNode`                                                    | -                                | Content rendered inside the drawer panel                                   |                                                                                |
+| `open`     | `boolean`                                                      | `false`                          | Controls whether the drawer is visible                                     |                                                                                |
+| `onClose`  | \`(event: React.SyntheticEvent                                 | Event, reason: string) => void\` | -                                                                          | Called when the drawer requests to close, such as backdrop click or Escape key |
+| `anchor`   | `'left' \| 'right' \| 'top' \| 'bottom'`                       | `'left'`                         | Edge of the screen from which the drawer slides in                         |                                                                                |
+| `size`     | `'sm' \| 'md' \| 'lg'`                                         | `'md'`                           | Preset drawer size used to control width or height depending on the anchor |                                                                                |
+| `variant`  | `'plain' \| 'soft' \| 'outlined' \| 'solid'`                   | `'plain'`                        | Visual style inherited from Joy UI Drawer                                  |                                                                                |
+| `color`    | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'`                      | Color scheme inherited from Joy UI Drawer                                  |                                                                                |
+| `sx`       | `SxProps`                                                      | -                                | Custom styles using the MUI system                                         |                                                                                |
+
+> **Note**: Drawer also accepts Joy UI `DrawerProps` and Framer Motion props because the component is a thin wrapper around Joy UI Drawer with motion support.
+
 ## 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.

package/dist/components/navigation/Dropdown.md

@@ -583,6 +583,19 @@ const [open, setOpen] = useState(false);
 </Button>
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop           | Type                             | Default | Description                          |
+| -------------- | -------------------------------- | ------- | ------------------------------------ |
+| `children`     | `ReactNode`                      | -       | Dropdown content (MenuButton + Menu) |
+| `open`         | `boolean`                        | -       | Controlled open state                |
+| `defaultOpen`  | `boolean`                        | `false` | Initial open state (uncontrolled)    |
+| `onOpenChange` | `(event, open: boolean) => void` | -       | Callback when open state changes     |
+
+> **Note**: Dropdown accepts all Joy UI Dropdown props. It is a state management wrapper — style props go on Menu and MenuButton.
+
 ## Best Practices
 
 - **Use the right abstraction level.** If you only need a simple list of text items, prefer `MenuButton` or `IconMenuButton` standalone components. Use `Dropdown` + `Menu` when you need dividers, custom headers, or mixed content inside the menu.

package/dist/components/navigation/IconMenuButton.md

@@ -225,6 +225,23 @@ function EditorToolbar({ onAction }) {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop                   | Type                                                                   | Default     | Description                                  |
+| ---------------------- | ---------------------------------------------------------------------- | ----------- | -------------------------------------------- |
+| `icon`                 | `ReactNode`                                                            | (required)  | Icon element to render in the trigger button |
+| `items`                | `{ text: string; component?: ElementType; componentProps?: object }[]` | -           | Menu items                                   |
+| `size`                 | `'sm' \| 'md' \| 'lg'`                                                 | `'md'`      | Button size                                  |
+| `color`                | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'`         | `'neutral'` | Button color                                 |
+| `variant`              | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                           | `'plain'`   | Button visual style                          |
+| `disabled`             | `boolean`                                                              | `false`     | Disables the button                          |
+| `loading`              | `boolean`                                                              | `false`     | Shows loading indicator                      |
+| `placement`            | `Placement`                                                            | `'bottom'`  | Menu position                                |
+| `buttonComponent`      | `ElementType`                                                          | -           | Custom trigger element                       |
+| `buttonComponentProps` | `object`                                                               | -           | Props passed to custom trigger               |
+
 ## Best Practices
 
 - **Always provide `aria-label`.** Since IconMenuButton has no visible text, screen readers rely entirely on the `aria-label` to announce the button's purpose. Include context when possible.