@ceed/cds 1.28.1 → 1.29.1

package/dist/components/navigation/InsetDrawer.md

@@ -6,124 +6,8 @@ InsetDrawer is a slide-out panel that appears from any edge of the screen, provi
 
 It is commonly used for mobile navigation menus, filter panels, configuration sidebars, and detail views. The component supports four anchor positions (left, right, top, bottom) and three size presets, making it adaptable to a wide range of layout requirements.
 
-```tsx
-<InsetDrawer {...args}>
-  <Sheet sx={{
-    borderRadius: 'md',
-    p: 2,
-    display: 'flex',
-    flexDirection: 'column',
-    gap: 2,
-    height: '100%',
-    overflow: 'auto'
-  }}>
-  <DialogTitle>Filters</DialogTitle>
-  <ModalClose />
-  <Divider sx={{
-    mt: 'auto'
-  }} />
-  <DialogContent>
-    <FormControl>
-      <FormLabel sx={{
-        typography: 'title-md',
-        fontWeight: 'bold'
-      }}>Property type</FormLabel>
-      <RadioGroup>
-        <Box sx={{
-          display: 'grid',
-          gridTemplateColumns: 'repeat(auto-fill, minmax(140px, 1fr))',
-          gap: 1.5
-        }}>
-        {[{
-          name: 'House',
-          icon: <HomeRoundedIcon />
-        }, {
-          name: 'Apartment',
-          icon: <ApartmentRoundedIcon />
-        }, {
-          name: 'Guesthouse',
-          icon: <MeetingRoomRoundedIcon />
-        }, {
-          name: 'Hotel',
-          icon: <HotelRoundedIcon />
-        }].map(item => <Card key={item.name} sx={{
-          boxShadow: 'none',
-          '&:hover': {
-            bgcolor: 'background.level1'
-          }
-        }}>
-        <CardContent>
-          {item.icon}
-          <Typography level="title-md">{item.name}</Typography>
-        </CardContent>
-        <Radio disableIcon overlay variant="outlined" color="neutral" value={item.name} sx={{
-          mt: -2
-        }} slotProps={{
-          action: {
-            sx: {
-              '&:hover': {
-                bgcolor: 'transparent'
-              }
-            }
-          }
-        }} />
-      </Card>)}
-    </Box>
-  </RadioGroup>
-</FormControl>
-
-<Typography level="title-md" fontWeight="bold" sx={{
-  mt: 2
-}}>
-Booking options
-</Typography>
-<FormControl orientation="horizontal">
-  <Box sx={{
-    flex: 1,
-    pr: 1
-  }}>
-  <FormLabel sx={{
-    typography: 'title-sm'
-  }}>Instant booking</FormLabel>
-  <FormHelperText sx={{
-    typography: 'body-sm'
-  }}>
-  Listings that you can book without waiting for host approval.
-</FormHelperText>
-</Box>
-<Switch />
-</FormControl>
-
-<FormControl orientation="horizontal">
-  <Box sx={{
-    flex: 1,
-    mt: 1,
-    mr: 1
-  }}>
-  <FormLabel sx={{
-    typography: 'title-sm'
-  }}>Self check-in</FormLabel>
-  <FormHelperText sx={{
-    typography: 'body-sm'
-  }}>
-  Easy access to the property when you arrive.
-</FormHelperText>
-</Box>
-<Switch />
-</FormControl>
-</DialogContent>
-
-<Divider sx={{
-  mt: 'auto'
-}} />
-<Stack direction="row" justifyContent="space-between" useFlexGap spacing={1}>
-  <Button variant="outlined" color="neutral">
-    Clear
-  </Button>
-  <Button>Show 165 properties</Button>
-</Stack>
-</Sheet>
-</InsetDrawer>
+```
+<Canvas of={InsetDrawer.Playground} />
 ```
 
 | Field                        | Description | Default |
@@ -155,220 +39,145 @@ function FilterDrawer() {
 }
 ```
 
-## Default
+## Anchor Positions
 
-The default InsetDrawer with a filter panel layout, demonstrating the component's structure with `DialogTitle`, `ModalClose`, `DialogContent`, and action buttons.
+InsetDrawer supports four anchor positions. Use `left` for navigation, `right` for details or filters, `top` for search bars, and `bottom` for mobile action sheets.
 
-```tsx
-<InsetDrawer {...args}>
-  <Sheet sx={{
-    borderRadius: 'md',
-    p: 2,
-    display: 'flex',
-    flexDirection: 'column',
-    gap: 2,
-    height: '100%',
-    overflow: 'auto'
-  }}>
-  <DialogTitle>Filters</DialogTitle>
-  <ModalClose />
-  <Divider sx={{
-    mt: 'auto'
-  }} />
-  <DialogContent>
-    <FormControl>
-      <FormLabel sx={{
-        typography: 'title-md',
-        fontWeight: 'bold'
-      }}>Property type</FormLabel>
-      <RadioGroup>
-        <Box sx={{
-          display: 'grid',
-          gridTemplateColumns: 'repeat(auto-fill, minmax(140px, 1fr))',
-          gap: 1.5
-        }}>
-        {[{
-          name: 'House',
-          icon: <HomeRoundedIcon />
-        }, {
-          name: 'Apartment',
-          icon: <ApartmentRoundedIcon />
-        }, {
-          name: 'Guesthouse',
-          icon: <MeetingRoomRoundedIcon />
-        }, {
-          name: 'Hotel',
-          icon: <HotelRoundedIcon />
-        }].map(item => <Card key={item.name} sx={{
-          boxShadow: 'none',
-          '&:hover': {
-            bgcolor: 'background.level1'
-          }
-        }}>
-        <CardContent>
-          {item.icon}
-          <Typography level="title-md">{item.name}</Typography>
-        </CardContent>
-        <Radio disableIcon overlay variant="outlined" color="neutral" value={item.name} sx={{
-          mt: -2
-        }} slotProps={{
-          action: {
-            sx: {
-              '&:hover': {
-                bgcolor: 'transparent'
-              }
-            }
-          }
-        }} />
-      </Card>)}
-    </Box>
-  </RadioGroup>
-</FormControl>
-
-<Typography level="title-md" fontWeight="bold" sx={{
-  mt: 2
-}}>
-Booking options
-</Typography>
-<FormControl orientation="horizontal">
-  <Box sx={{
-    flex: 1,
-    pr: 1
-  }}>
-  <FormLabel sx={{
-    typography: 'title-sm'
-  }}>Instant booking</FormLabel>
-  <FormHelperText sx={{
-    typography: 'body-sm'
-  }}>
-  Listings that you can book without waiting for host approval.
-</FormHelperText>
-</Box>
-<Switch />
-</FormControl>
-
-<FormControl orientation="horizontal">
-  <Box sx={{
-    flex: 1,
-    mt: 1,
-    mr: 1
-  }}>
-  <FormLabel sx={{
-    typography: 'title-sm'
-  }}>Self check-in</FormLabel>
-  <FormHelperText sx={{
-    typography: 'body-sm'
-  }}>
-  Easy access to the property when you arrive.
-</FormHelperText>
-</Box>
-<Switch />
-</FormControl>
-</DialogContent>
-
-<Divider sx={{
-  mt: 'auto'
-}} />
-<Stack direction="row" justifyContent="space-between" useFlexGap spacing={1}>
-  <Button variant="outlined" color="neutral">
-    Clear
-  </Button>
-  <Button>Show 165 properties</Button>
-</Stack>
-</Sheet>
-</InsetDrawer>
+```
+<Canvas of={InsetDrawer.Anchors} />
+```
+
+## Sizes
+
+Three size presets are available: `sm`, `md`, and `lg`. The size controls width for left/right anchors and height for top/bottom anchors.
+
+```
+<Canvas of={InsetDrawer.Sizes} />
+```
+
+## Navigation Menu
+
+A typical mobile navigation menu pattern using InsetDrawer anchored to the left with a compact size.
+
+```
+<Canvas of={InsetDrawer.NavigationMenu} />
+```
+
+## Filter Panel
+
+A filter panel that slides in from the right, containing form controls for refining search results.
+
+```
+<Canvas of={InsetDrawer.FilterPanel} />
 ```
 
 ## Common Use Cases
 
-### Navigation Drawer
+### Settings Drawer
 
 ```tsx
-function NavigationDrawer({ open, onClose, currentPath }) {
-  const navItems = [
-    { label: 'Dashboard', path: '/dashboard', icon: <DashboardIcon /> },
-    { label: 'Users', path: '/users', icon: <PeopleIcon /> },
-    { label: 'Settings', path: '/settings', icon: <SettingsIcon /> },
-  ];
+function SettingsDrawer({ open, onClose }) {
+  const [settings, setSettings] = useState({
+    notifications: true,
+    darkMode: false,
+    language: 'en',
+  });
 
   return (
-    <InsetDrawer open={open} onClose={onClose} anchor="left">
-      <Sheet sx={{ width: 280, height: '100%', p: 2 }}>
-        <Stack gap={1}>
-          <Typography level="title-lg">My App</Typography>
-          <Divider />
-          <List>
-            {navItems.map((item) => (
-              <ListItem key={item.path}>
-                <ListItemButton
-                  selected={currentPath === item.path}
-                  onClick={() => { navigate(item.path); onClose(); }}
-                >
-                  <ListItemDecorator>{item.icon}</ListItemDecorator>
-                  {item.label}
-                </ListItemButton>
-              </ListItem>
-            ))}
-          </List>
-        </Stack>
+    <InsetDrawer open={open} onClose={onClose} anchor="right" size="sm">
+      <Sheet sx={{ height: '100%', p: 2 }}>
+        <DialogTitle>Settings</DialogTitle>
+        <ModalClose />
+        <Divider sx={{ my: 2 }} />
+        <DialogContent>
+          <Stack gap={3}>
+            <FormControl orientation="horizontal">
+              <Box sx={{ flex: 1 }}>
+                <FormLabel>Notifications</FormLabel>
+                <FormHelperText>Receive push notifications</FormHelperText>
+              </Box>
+              <Switch
+                checked={settings.notifications}
+                onChange={(e) =>
+                  setSettings({ ...settings, notifications: e.target.checked })
+                }
+              />
+            </FormControl>
+            <FormControl orientation="horizontal">
+              <Box sx={{ flex: 1 }}>
+                <FormLabel>Dark Mode</FormLabel>
+                <FormHelperText>Use dark color theme</FormHelperText>
+              </Box>
+              <Switch
+                checked={settings.darkMode}
+                onChange={(e) =>
+                  setSettings({ ...settings, darkMode: e.target.checked })
+                }
+              />
+            </FormControl>
+          </Stack>
+        </DialogContent>
       </Sheet>
     </InsetDrawer>
   );
 }
 ```
 
-### Filter Panel
+### Detail View Drawer
 
 ```tsx
-function ProductFilters({ open, onClose, onApply }) {
-  const [localFilters, setLocalFilters] = useState({});
+function DetailDrawer({ open, onClose, itemId }) {
+  const [data, setData] = useState(null);
+
+  useEffect(() => {
+    if (open && itemId) {
+      fetchItemDetails(itemId).then(setData);
+    }
+  }, [open, itemId]);
 
   return (
-    <InsetDrawer open={open} onClose={onClose} anchor="right" size="md">
+    <InsetDrawer open={open} onClose={onClose} anchor="right" size="lg">
       <Sheet sx={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
         <Box sx={{ p: 2, borderBottom: '1px solid', borderColor: 'divider' }}>
-          <DialogTitle>Filters</DialogTitle>
+          <DialogTitle>Item Details</DialogTitle>
           <ModalClose />
         </Box>
         <DialogContent sx={{ flex: 1, overflow: 'auto', p: 2 }}>
-          {/* Filter form controls */}
+          {data ? <ItemDetails data={data} /> : <Skeleton variant="text" />}
         </DialogContent>
-        <Box sx={{ p: 2, borderTop: '1px solid', borderColor: 'divider' }}>
-          <Stack direction="row" gap={1} justifyContent="space-between">
-            <Button variant="outlined" color="neutral" onClick={() => setLocalFilters({})}>
-              Clear All
-            </Button>
-            <Button onClick={() => { onApply(localFilters); onClose(); }}>
-              Apply Filters
-            </Button>
-          </Stack>
-        </Box>
       </Sheet>
     </InsetDrawer>
   );
 }
 ```
 
-### Bottom Sheet for Mobile
+### Bottom Sheet for Mobile Actions
 
 ```tsx
 function ActionSheet({ open, onClose, onAction }) {
+  const actions = [
+    { id: 'edit', label: 'Edit', icon: <EditIcon /> },
+    { id: 'share', label: 'Share', icon: <ShareIcon /> },
+    { id: 'delete', label: 'Delete', icon: <DeleteIcon />, color: 'danger' },
+  ];
+
   return (
     <InsetDrawer open={open} onClose={onClose} anchor="bottom">
       <Sheet sx={{ borderRadius: 'lg lg 0 0', p: 2 }}>
         <List>
-          <ListItem>
-            <ListItemButton onClick={() => { onAction('edit'); onClose(); }}>
-              Edit
-            </ListItemButton>
-          </ListItem>
-          <ListItem>
-            <ListItemButton onClick={() => { onAction('delete'); onClose(); }}>
-              Delete
-            </ListItemButton>
-          </ListItem>
+          {actions.map((action) => (
+            <ListItem key={action.id}>
+              <ListItemButton
+                color={action.color}
+                onClick={() => { onAction(action.id); onClose(); }}
+              >
+                <ListItemDecorator>{action.icon}</ListItemDecorator>
+                {action.label}
+              </ListItemButton>
+            </ListItem>
+          ))}
         </List>
-        <Button variant="soft" color="neutral" fullWidth onClick={onClose}>
+        <Button variant="soft" color="neutral" fullWidth sx={{ mt: 1 }} onClick={onClose}>
           Cancel
         </Button>
       </Sheet>
@@ -377,6 +186,19 @@ function ActionSheet({ open, onClose, onAction }) {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop       | Type                                                           | Default     | Description    |
+| ---------- | -------------------------------------------------------------- | ----------- | -------------- |
+| `children` | `ReactNode`                                                    | -           | Drawer content |
+| `variant`  | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'plain'`   | Visual style   |
+| `color`    | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'` | Color scheme   |
+| `sx`       | `SxProps`                                                      | -           | Custom styles  |
+
+> **Note**: InsetDrawer is a styled Sheet component designed for sidebar layouts. It accepts all Joy UI Sheet props.
+
 ## Best Practices
 
 1. **Use appropriate anchor positions**: Match the drawer position to the content type for intuitive UX.
@@ -402,6 +224,22 @@ function ActionSheet({ open, onClose, onAction }) {
 
 3. **Structure content consistently**: Use a header/body/footer layout with clear dividers so users can quickly scan the drawer's content.
 
+```tsx
+// ✅ Good: Clear header/body/footer structure
+<Sheet sx={{ height: '100%', display: 'flex', flexDirection: 'column' }}>
+  <Box sx={{ p: 2, borderBottom: '1px solid', borderColor: 'divider' }}>
+    <DialogTitle>Title</DialogTitle>
+    <ModalClose />
+  </Box>
+  <DialogContent sx={{ flex: 1, overflow: 'auto', p: 2 }}>
+    {/* Scrollable content */}
+  </DialogContent>
+  <Box sx={{ p: 2, borderTop: '1px solid', borderColor: 'divider' }}>
+    <Button>Save</Button>
+  </Box>
+</Sheet>
+```
+
 4. **Do not nest drawers**: Opening a drawer inside another drawer creates a confusing experience.
 
 ```tsx

package/dist/components/navigation/Link.md

@@ -43,6 +43,64 @@ function MyComponent() {
 }
 ```
 
+## Features
+
+### Variants
+
+Links support four visual styles through the `variant` prop: `plain`, `outlined`, `soft`, and `solid`.
+
+```
+<Canvas of={Link.Variants} />
+```
+
+### Colors
+
+Apply semantic colors to communicate different purposes -- `primary`, `neutral`, `success`, `warning`, and `danger`.
+
+```
+<Canvas of={Link.Colors} />
+```
+
+### Underline Styles
+
+Control the underline behavior with three options: `none` (never shown), `hover` (shown on hover), and `always` (permanently visible).
+
+```
+<Canvas of={Link.Underline} />
+```
+
+### Typography Levels
+
+Links can adopt any typography level from the design system, enabling consistent text hierarchies when links appear alongside headings or body text.
+
+```
+<Canvas of={Link.Levels} />
+```
+
+### Disabled State
+
+Links can be disabled to prevent interaction while remaining visible in the layout.
+
+```
+<Canvas of={Link.Disabled} />
+```
+
+### External Links
+
+For links that navigate away from your application, include `target="_blank"` and `rel="noopener noreferrer"` for security.
+
+```
+<Canvas of={Link.ExternalLink} />
+```
+
+### Inline with Text
+
+Links integrate seamlessly within paragraph text, inheriting the surrounding font styles.
+
+```
+<Canvas of={Link.InlineWithText} />
+```
+
 ## Common Use Cases
 
 ### Inline Text Links
@@ -93,6 +151,26 @@ function AppNavigation() {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop             | Type                                                           | Default     | Description                            |
+| ---------------- | -------------------------------------------------------------- | ----------- | -------------------------------------- |
+| `children`       | `ReactNode`                                                    | -           | Link content                           |
+| `href`           | `string`                                                       | -           | Link URL                               |
+| `level`          | Typography level                                               | `'body-md'` | Text size (inherits Typography levels) |
+| `color`          | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'primary'` | Link color                             |
+| `variant`        | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | -           | Visual style                           |
+| `underline`      | `'none' \| 'hover' \| 'always'`                                | `'hover'`   | Underline behavior                     |
+| `disabled`       | `boolean`                                                      | `false`     | Disables the link                      |
+| `startDecorator` | `ReactNode`                                                    | -           | Content before link text               |
+| `endDecorator`   | `ReactNode`                                                    | -           | Content after link text                |
+| `component`      | `ElementType`                                                  | `'a'`       | Root element type (polymorphic)        |
+| `sx`             | `SxProps`                                                      | -           | Custom styles                          |
+
+> **Note**: Link also accepts all Joy UI Link props.
+
 ## Best Practices
 
 - **Use descriptive link text.** The text should clearly communicate the destination. Avoid generic labels such as "click here" or "read more".

package/dist/components/navigation/Menu.md

@@ -719,6 +719,23 @@ Menu can contain non-MenuItem elements like Box, Typography, and progress indica
 </Dropdown>
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop        | Type                                                           | Default          | Description                              |
+| ----------- | -------------------------------------------------------------- | ---------------- | ---------------------------------------- |
+| `children`  | `ReactNode`                                                    | -                | Menu items (MenuItem, ListDivider, etc.) |
+| `open`      | `boolean`                                                      | -                | Controlled open state                    |
+| `onClose`   | `() => void`                                                   | -                | Callback when the menu closes            |
+| `placement` | `Placement`                                                    | `'bottom-start'` | Menu position relative to trigger        |
+| `size`      | `'sm' \| 'md' \| 'lg'`                                         | `'md'`           | Menu size                                |
+| `variant`   | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'outlined'`     | Visual style                             |
+| `color`     | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'`      | Color scheme                             |
+| `sx`        | `SxProps`                                                      | -                | Custom styles                            |
+
+> **Note**: Menu also accepts all Joy UI Menu props and Framer Motion props.
+
 ## Best Practices
 
 - **Use ListDivider to group related items.** Logical grouping helps users scan the menu faster. Place destructive actions (like Delete) in their own group at the bottom.

package/dist/components/navigation/MenuButton.md

@@ -233,6 +233,24 @@ function ToolbarActions({ selectedItems, onAction }) {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop              | Type                                                           | Default          | Description                          |
+| ----------------- | -------------------------------------------------------------- | ---------------- | ------------------------------------ |
+| `buttonText`      | `string`                                                       | (required)       | Text displayed in the trigger button |
+| `items`           | `{ text: string; onClick?: () => void }[]`                     | (required)       | Menu item list                       |
+| `variant`         | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'outlined'`     | Button visual style                  |
+| `size`            | `'sm' \| 'md' \| 'lg'`                                         | `'md'`           | Button size                          |
+| `color`           | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'`      | Button color                         |
+| `disabled`        | `boolean`                                                      | `false`          | Disables the button                  |
+| `startDecorator`  | `ReactNode`                                                    | -                | Content before button text           |
+| `endDecorator`    | `ReactNode`                                                    | -                | Content after button text            |
+| `showIcon`        | `boolean`                                                      | `true`           | Show dropdown arrow icon             |
+| `placement`       | `Placement`                                                    | `'bottom-start'` | Menu position                        |
+| `buttonComponent` | `ElementType`                                                  | -                | Custom trigger element               |
+
 ## Best Practices
 
 - **Use descriptive button text.** The button label should clearly indicate what kind of options the menu contains. Avoid vague labels like "More" or "Options" -- prefer specific labels like "Export Options" or "User Actions".

package/dist/components/navigation/Pagination.md

@@ -214,6 +214,19 @@ function URLPaginatedList() {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop                     | Type                                 | Default                     | Description                |
+| ------------------------ | ------------------------------------ | --------------------------- | -------------------------- |
+| `paginationModel`        | `{ page: number; pageSize: number }` | (required)                  | Current page and page size |
+| `defaultPaginationModel` | `{ page: number; pageSize: number }` | `{ page: 1, pageSize: 25 }` | Initial pagination state   |
+| `rowCount`               | `number`                             | (required)                  | Total number of rows       |
+| `onPageChange`           | `(newPage: number) => void`          | (required)                  | Callback when page changes |
+| `size`                   | `'sm' \| 'md' \| 'lg'`               | `'md'`                      | Pagination control size    |
+| `variant`                | `'standard' \| 'compact'`            | `'standard'`                | Pagination display mode    |
+
 ## Best Practices
 
 - **Always show context.** Display the total item count and current range (for example "Showing 1--25 of 250") alongside the pagination controls so users understand the scope of the data.

package/dist/components/navigation/Stepper.md

@@ -204,6 +204,21 @@ function CompactProgress({ currentStep, totalSteps }) {
 }
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop                | Type                                                                              | Default         | Description                                  |
+| ------------------- | --------------------------------------------------------------------------------- | --------------- | -------------------------------------------- |
+| `steps`             | `{ indicatorContent?: ReactNode; label?: ReactNode; extraContent?: ReactNode }[]` | (required)      | Step definitions                             |
+| `activeStep`        | `number`                                                                          | (required)      | Currently active step index (0-based)        |
+| `orientation`       | `'horizontal' \| 'vertical'`                                                      | `'horizontal'`  | Stepper layout direction                     |
+| `stepOrientation`   | `'horizontal' \| 'vertical'`                                                      | `'horizontal'`  | Individual step content orientation          |
+| `activeColor`       | `string`                                                                          | `'primary.500'` | Color for active/completed step indicators   |
+| `inactiveColor`     | `string`                                                                          | `'neutral.400'` | Color for inactive step indicators           |
+| `activeLineColor`   | `string`                                                                          | `'primary.500'` | Color for connector lines of completed steps |
+| `inactiveLineColor` | `string`                                                                          | `'neutral.300'` | Color for connector lines of future steps    |
+
 ## Best Practices
 
 1. **Keep step count manageable**: Limit the number of steps to 3-7 for optimal user comprehension. If more steps are needed, consider grouping them.