@ceed/ads 1.20.0 → 1.20.1

package/dist/components/navigation/NavigationGroup.md

@@ -2,6 +2,8 @@
 
 ## Introduction
 
+NavigationGroup is an expandable container for organizing related navigation items in a sidebar. Built on Joy UI's Accordion component, it provides a collapsible section that can hold NavigationItems or nested Navigator components. NavigationGroup creates hierarchical navigation structures where users can expand and collapse sections to access nested items.
+
 ```text
 // Unable to derive source for Default
 ```
@@ -13,5 +15,403 @@
 ## Usage
 
 ```tsx
-import { NavigationGroup } from '@ceed/ads';
+import { NavigationGroup, NavigationItem } from '@ceed/ads';
+
+function Sidebar() {
+  return (
+    <NavigationGroup
+      title="User Management"
+      startDecorator={<PeopleIcon />}
+      defaultExpanded={true}
+    >
+      <NavigationItem id="users" level={1}>All Users</NavigationItem>
+      <NavigationItem id="roles" level={1}>Roles</NavigationItem>
+      <NavigationItem id="permissions" level={1}>Permissions</NavigationItem>
+    </NavigationGroup>
+  );
+}
+```
+
+## Examples
+
+### Default
+
+Basic navigation group with a title and content.
+
+```text
+// Unable to derive source for Default
+```
+
+### Nesting Levels
+
+NavigationGroup supports different indentation levels for nested hierarchies.
+
+```text
+// Unable to derive source for Level1
+```
+
+```text
+// Unable to derive source for Level2
+```
+
+### With Start Decorator
+
+Add an icon before the group title.
+
+```text
+// Unable to derive source for WithStartDecorator
+```
+
+### Levels with Icons
+
+Icons work at any nesting level.
+
+```text
+// Unable to derive source for Level1WithStartDecorator
+```
+
+```text
+// Unable to derive source for Level2WithStartDecorator
+```
+
+## When to Use
+
+### ✅ Good Use Cases
+
+- **Collapsible sidebar sections**: Organize navigation into expandable categories
+- **Deep navigation hierarchies**: Group related items under collapsible headers
+- **Admin interfaces**: Organize modules and sub-modules
+- **Settings organization**: Group related settings under categories
+- **File system navigation**: Folders containing nested items
+
+### ❌ When Not to Use
+
+- **Flat navigation**: When all items are at the same level
+- **Tab-like navigation**: Use Tabs for switching between views
+- **Simple menus**: For 5 or fewer items, consider flat NavigationItems
+- **Modal dialogs**: Use proper modal patterns instead
+- **Accordion content**: For non-navigation accordions, use Accordion directly
+
+## Common Use Cases
+
+### Admin Module Navigation
+
+```tsx
+function AdminNavigation() {
+  return (
+    <>
+      <NavigationGroup
+        title="User Management"
+        startDecorator={<PeopleIcon />}
+        defaultExpanded={true}
+      >
+        <NavigationItem id="users" level={1}>
+          All Users
+        </NavigationItem>
+        <NavigationItem id="invite" level={1}>
+          Invite User
+        </NavigationItem>
+        <NavigationItem id="roles" level={1}>
+          Roles & Permissions
+        </NavigationItem>
+      </NavigationGroup>
+
+      <NavigationGroup
+        title="Content"
+        startDecorator={<ArticleIcon />}
+      >
+        <NavigationItem id="posts" level={1}>
+          Posts
+        </NavigationItem>
+        <NavigationItem id="categories" level={1}>
+          Categories
+        </NavigationItem>
+        <NavigationItem id="media" level={1}>
+          Media Library
+        </NavigationItem>
+      </NavigationGroup>
+
+      <NavigationGroup
+        title="Settings"
+        startDecorator={<SettingsIcon />}
+      >
+        <NavigationItem id="general" level={1}>
+          General
+        </NavigationItem>
+        <NavigationItem id="security" level={1}>
+          Security
+        </NavigationItem>
+        <NavigationItem id="integrations" level={1}>
+          Integrations
+        </NavigationItem>
+      </NavigationGroup>
+    </>
+  );
+}
+```
+
+### Nested Groups
+
+```tsx
+function NestedNavigation() {
+  return (
+    <NavigationGroup
+      title="E-commerce"
+      startDecorator={<ShoppingCartIcon />}
+      defaultExpanded={true}
+    >
+      <NavigationItem id="dashboard" level={1}>
+        Dashboard
+      </NavigationItem>
+
+      <NavigationGroup
+        title="Products"
+        level={1}
+        defaultExpanded={true}
+      >
+        <NavigationItem id="all-products" level={2}>
+          All Products
+        </NavigationItem>
+        <NavigationItem id="add-product" level={2}>
+          Add Product
+        </NavigationItem>
+        <NavigationItem id="categories" level={2}>
+          Categories
+        </NavigationItem>
+      </NavigationGroup>
+
+      <NavigationGroup
+        title="Orders"
+        level={1}
+      >
+        <NavigationItem id="all-orders" level={2}>
+          All Orders
+        </NavigationItem>
+        <NavigationItem id="pending" level={2}>
+          Pending
+        </NavigationItem>
+        <NavigationItem id="completed" level={2}>
+          Completed
+        </NavigationItem>
+      </NavigationGroup>
+    </NavigationGroup>
+  );
+}
+```
+
+### Documentation Sidebar
+
+```tsx
+function DocsSidebar({ sections, currentPath }) {
+  return (
+    <nav>
+      {sections.map((section) => (
+        <NavigationGroup
+          key={section.id}
+          title={section.title}
+          startDecorator={<BookIcon />}
+          defaultExpanded={currentPath.startsWith(section.basePath)}
+        >
+          {section.pages.map((page) => (
+            <NavigationItem
+              key={page.id}
+              id={page.id}
+              level={1}
+              selected={currentPath === page.path}
+              onClick={() => navigate(page.path)}
+            >
+              {page.title}
+            </NavigationItem>
+          ))}
+        </NavigationGroup>
+      ))}
+    </nav>
+  );
+}
 ```
+
+## Props and Customization
+
+### Key Props
+
+| Prop              | Type                  | Default | Description                   |
+| ----------------- | --------------------- | ------- | ----------------------------- |
+| `title`           | `string \| ReactNode` | -       | Group header title            |
+| `children`        | `ReactNode`           | -       | Content shown when expanded   |
+| `startDecorator`  | `ReactNode`           | -       | Icon before the title         |
+| `level`           | `number`              | `0`     | Nesting level for indentation |
+| `defaultExpanded` | `boolean`             | `false` | Initial expanded state        |
+
+### Accordion Props
+
+NavigationGroup extends Joy UI's Accordion, so you can use additional Accordion props:
+
+```tsx
+<NavigationGroup
+  title="Settings"
+  expanded={isExpanded}
+  onChange={(event, expanded) => setIsExpanded(expanded)}
+>
+  {/* Content */}
+</NavigationGroup>
+```
+
+### Custom Styling
+
+```tsx
+<NavigationGroup
+  title="Custom Section"
+  sx={{
+    '& .NavigationGroup-Summary': {
+      fontWeight: 600,
+    },
+    '& .NavigationGroup-Details': {
+      backgroundColor: 'background.level2',
+    },
+  }}
+>
+  {/* Content */}
+</NavigationGroup>
+```
+
+## Accessibility
+
+NavigationGroup leverages Joy UI's Accordion accessibility features:
+
+### ARIA Attributes
+
+- `role="button"` on the expandable header
+- `aria-expanded` indicates the current state
+- `aria-controls` links header to content
+- Content region has proper `role="region"`
+
+### Keyboard Navigation
+
+- **Tab**: Focus the group header
+- **Enter/Space**: Toggle expanded state
+- **Arrow Down**: Move to first item when expanded
+- **Arrow Up**: Move to header from first item
+
+### Screen Reader Support
+
+```tsx
+// Expansion state is announced
+<NavigationGroup title="Settings" defaultExpanded={true}>
+  {/* "Settings, expanded, button" */}
+</NavigationGroup>
+```
+
+## Best Practices
+
+### ✅ Do
+
+1. **Use descriptive titles**: Group titles should clearly indicate the content category
+
+```tsx
+// ✅ Good: Descriptive title
+<NavigationGroup title="User Management">
+
+// ❌ Bad: Vague title
+<NavigationGroup title="More">
+```
+
+2. **Expand active sections**: Auto-expand groups containing the current page
+
+```tsx
+<NavigationGroup
+  title="Products"
+  defaultExpanded={currentPath.startsWith('/products')}
+>
+```
+
+3. **Limit group children**: Keep 3-7 items per group for easy scanning
+
+4. **Use consistent icons**: If using icons, apply them to all groups
+
+### ❌ Don't
+
+1. **Don't over-nest**: Maximum 2-3 levels of nesting
+
+```tsx
+// ❌ Bad: Too deep
+<NavigationGroup>
+  <NavigationGroup level={1}>
+    <NavigationGroup level={2}>
+      <NavigationGroup level={3}>  {/* Too deep */}
+```
+
+2. **Don't mix patterns**: Be consistent with structure across all groups
+
+3. **Don't put actions in groups**: Navigation only, not buttons or forms
+
+4. **Don't hide critical navigation**: Important items should be easily discoverable
+
+## Performance Considerations
+
+### Lazy Load Content
+
+For groups with heavy content, consider lazy loading:
+
+```tsx
+function LazyNavigationGroup({ title, loadContent }) {
+  const [expanded, setExpanded] = useState(false);
+  const [content, setContent] = useState(null);
+
+  const handleChange = async (event, isExpanded) => {
+    setExpanded(isExpanded);
+    if (isExpanded && !content) {
+      const loadedContent = await loadContent();
+      setContent(loadedContent);
+    }
+  };
+
+  return (
+    <NavigationGroup
+      title={title}
+      expanded={expanded}
+      onChange={handleChange}
+    >
+      {content || <Skeleton />}
+    </NavigationGroup>
+  );
+}
+```
+
+### Controlled Expansion
+
+For complex navigation, control expansion at the parent level:
+
+```tsx
+function SidebarNavigation() {
+  const [expandedGroups, setExpandedGroups] = useState(['products']);
+
+  const handleGroupChange = (groupId) => (event, isExpanded) => {
+    setExpandedGroups((prev) =>
+      isExpanded
+        ? [...prev, groupId]
+        : prev.filter((id) => id !== groupId)
+    );
+  };
+
+  return (
+    <>
+      <NavigationGroup
+        title="Products"
+        expanded={expandedGroups.includes('products')}
+        onChange={handleGroupChange('products')}
+      >
+        {/* Items */}
+      </NavigationGroup>
+      <NavigationGroup
+        title="Orders"
+        expanded={expandedGroups.includes('orders')}
+        onChange={handleGroupChange('orders')}
+      >
+        {/* Items */}
+      </NavigationGroup>
+    </>
+  );
+}
+```
+
+NavigationGroup provides the structure for organizing hierarchical sidebar navigation. Combine it with NavigationItem for individual links, or use it within Navigator for a complete navigation solution.