@cere/cere-design-system 0.0.13 → 0.0.17

package/README.md

@@ -335,25 +335,6 @@ When AI agents work on your application specs:
 3. They get TypeScript types and usage examples from the reference
 
 See `.specify/memory/package-usage-guide.md` (included in the npm package) for detailed integration instructions.
-
-## Documentation
-
-- [Full Components Reference](./COMPONENTS.md) - Complete API documentation
-- [Integration Guide](./INTEGRATION.md) - Step-by-step integration instructions
-- **[AI Agent Context](./.agent/README.md)** - Component reference optimized for AI agents (Claude, GPT-4, Cursor, etc.)
-
-## AI-Assisted Development
-
-This design system includes comprehensive AI agent context to accelerate development with AI coding assistants.
-
-### For AI Agents (Cursor, Claude, GPT-4, etc.)
-
-The package includes a complete component reference optimized for AI agents at `.agent/rules/COMPONENTS.md`.
-
-**Quick Start:**
-```bash
-# After installing the package
-cat node_modules/@cere/cere-design-system/.agent/rules/COMPONENTS.md
 ```
 
 Paste the output into your AI conversation to give the agent complete knowledge of:

package/dist/index.d.mts

@@ -12,6 +12,7 @@ import { TextFieldProps as TextFieldProps$1 } from '@mui/material/TextField';
 import { SwitchProps as SwitchProps$1 } from '@mui/material/Switch';
 import { CheckboxProps as CheckboxProps$1 } from '@mui/material/Checkbox';
 import { RadioProps as RadioProps$1 } from '@mui/material/Radio';
+import { ListItemButtonProps } from '@mui/material/ListItemButton';
 import { BadgeProps as BadgeProps$1 } from '@mui/material/Badge';
 import { ChipProps as ChipProps$1 } from '@mui/material/Chip';
 import { TooltipProps as TooltipProps$1 } from '@mui/material/Tooltip';
@@ -433,6 +434,456 @@ type StepButtonProps = StepButtonProps$1;
  */
 declare const StepButton: React__default.FC<StepButtonProps>;
 
+/**
+ * Type definitions for SideNav components
+ * Side Navigation Bar Component - V1 (Expanded State) & V2 (Collapsed State)
+ */
+
+/**
+ * Navigation Item Properties
+ * Individual navigation menu item with icon, label, and interactive states
+ */
+interface NavigationItemProps extends Omit<ListItemButtonProps, 'selected' | 'onClick'> {
+    /**
+     * Unique identifier for the navigation item
+     * Used for selection tracking and key prop
+     */
+    id: string;
+    /**
+     * Display text for the navigation item
+     */
+    label: string;
+    /**
+     * Icon element to display (typically a Material UI icon component)
+     */
+    icon?: ReactNode;
+    /**
+     * Position of the icon relative to the label
+     * @default 'left'
+     */
+    iconPosition?: 'left' | 'right';
+    /**
+     * Whether this item is currently selected/active
+     * @default false
+     */
+    selected?: boolean;
+    /**
+     * Whether this item is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Click handler for the navigation item
+     * @param id - The id of the clicked item
+     */
+    onClick?: (id: string) => void;
+    /**
+     * Additional content to display on the right side
+     * Can be a button, dropdown, badge, etc.
+     */
+    endContent?: ReactNode;
+    /**
+     * Optional URL for link-based navigation
+     * If provided, component renders as a link
+     */
+    href?: string;
+    /**
+     * Accessibility label for screen readers
+     * @default Uses 'label' prop value
+     */
+    ariaLabel?: string;
+    /**
+     * Size variant for the navigation item
+     * @default 'medium'
+     */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Whether sidebar is collapsed (icon-only mode) - V2
+     * When true:
+     * - Label is hidden
+     * - Tooltip shows on hover/focus
+     * - EndContent is hidden
+     * - Icon is centered
+     * @default false
+     */
+    collapsed?: boolean;
+    /**
+     * Whether to show tooltip in collapsed mode - V2
+     * @default true
+     */
+    showTooltip?: boolean;
+    /**
+     * Tooltip placement - V2
+     * @default 'right'
+     */
+    tooltipPlacement?: 'left' | 'right' | 'top' | 'bottom';
+}
+/**
+ * Navigation List Properties
+ * Container for multiple navigation items with scroll support
+ */
+interface NavigationListProps {
+    /**
+     * Array of navigation items to display
+     */
+    items: NavigationItemProps[];
+    /**
+     * ID of currently selected item (controlled mode)
+     */
+    selectedId?: string;
+    /**
+     * Callback when selection changes
+     * @param id - The id of the newly selected item
+     */
+    onSelectionChange?: (id: string) => void;
+    /**
+     * Maximum height before scrolling kicks in
+     * @default 'auto'
+     */
+    maxHeight?: string | number;
+    /**
+     * Accessibility label for the list
+     * @default 'Navigation menu'
+     */
+    ariaLabel?: string;
+    /**
+     * Whether sidebar is collapsed - V2
+     * Passed down to all NavigationItem children
+     * @default false
+     */
+    collapsed?: boolean;
+    /**
+     * Whether to show tooltips on items when collapsed - V2
+     * Passed down to each NavigationItem's showTooltip prop
+     * @default true
+     */
+    showTooltips?: boolean;
+}
+/**
+ * User Information
+ * Used in AccountSection component
+ */
+interface UserInfo {
+    /**
+     * User's display name
+     */
+    name: string;
+    /**
+     * User's email address (optional)
+     */
+    email?: string;
+    /**
+     * User's initials for avatar fallback
+     * If not provided, will be derived from name
+     */
+    initials?: string;
+    /**
+     * URL for user avatar image
+     */
+    avatarUrl?: string;
+}
+/**
+ * Connection Status Properties
+ * Displays connection status with pill-style indicator
+ */
+interface ConnectionStatusProps {
+    /**
+     * Status text to display (e.g., "Connected to Dragon 1")
+     */
+    status: string;
+    /**
+     * Visual variant of the status
+     * @default 'info'
+     */
+    variant?: 'success' | 'warning' | 'error' | 'info';
+    /**
+     * Optional custom icon to replace the default power icon
+     */
+    icon?: ReactNode;
+    /**
+     * Optional click handler (makes status interactive)
+     */
+    onClick?: () => void;
+    /**
+     * Compact mode for collapsed sidebar - V2
+     * When true:
+     * - Shows pill with icon + compactText (or falls back to icon-only)
+     * - Tooltip shows full status text on hover/focus
+     * @default false
+     */
+    compact?: boolean;
+    /**
+     * Short label to display in compact mode (e.g. "D1") - V2
+     * If not provided, compact mode shows icon-only
+     */
+    compactText?: string;
+}
+/**
+ * Account Section Properties
+ * Displays user account information with avatar, name, and logout
+ */
+interface AccountSectionProps {
+    /**
+     * User information object
+     */
+    user: UserInfo;
+    /**
+     * Logout button click handler
+     */
+    onLogout: () => void;
+    /**
+     * Whether to show email below name
+     * @default false
+     */
+    showEmail?: boolean;
+    /**
+     * Layout variant
+     * @default 'horizontal'
+     */
+    layout?: 'horizontal' | 'vertical';
+    /**
+     * Compact mode (avatar-only for collapsed sidebar) - V2
+     * When true:
+     * - Name and email are hidden
+     * - Only avatar is shown (40px)
+     * - Tooltip shows name + email on hover/focus
+     * - Logout button becomes icon-only
+     * @default false
+     */
+    compact?: boolean;
+}
+/**
+ * SideNav Properties
+ * Main container component that composes all navigation sections
+ */
+interface SideNavProps {
+    /**
+     * Width of the sidebar when expanded (pixels) - V1
+     * @default 280
+     */
+    width?: number;
+    /**
+     * Width of the sidebar when collapsed (pixels) - V2
+     * @default 68
+     */
+    collapsedWidth?: number;
+    /**
+     * Whether the sidebar is collapsed (controlled mode) - V2
+     * When provided: Component is controlled (parent manages state)
+     * When undefined: Component is uncontrolled (internal state)
+     * @default undefined
+     */
+    collapsed?: boolean;
+    /**
+     * Default collapsed state (uncontrolled mode only) - V2
+     * Ignored if `collapsed` prop is provided
+     * @default false
+     */
+    defaultCollapsed?: boolean;
+    /**
+     * Callback fired when collapsed state changes - V2
+     * Called after toggle button click or programmatic state change
+     * @param collapsed - New collapsed state value
+     */
+    onCollapseChange?: (collapsed: boolean) => void;
+    /**
+     * Duration of the collapse/expand width transition in ms - V2
+     * @default 300
+     */
+    transitionDuration?: number;
+    /**
+     * Whether to show tooltips on child items when collapsed - V2
+     * Passed down via context to NavigationList and NavigationItem
+     * @default true
+     */
+    showTooltips?: boolean;
+    /**
+     * Position of the sidebar
+     * @default 'left'
+     */
+    position?: 'left' | 'right';
+    /**
+     * Whether to show border on the edge
+     * @default true
+     */
+    showBorder?: boolean;
+    /**
+     * Custom background color
+     * @default theme.palette.background.paper
+     */
+    backgroundColor?: string;
+    /**
+     * Child components (NavigationList, ConnectionStatus, AccountSection)
+     */
+    children: ReactNode;
+    /**
+     * Additional CSS class name
+     */
+    className?: string;
+    /**
+     * Accessibility label for the navigation
+     * @default 'Main navigation'
+     */
+    ariaLabel?: string;
+}
+/**
+ * SideNav Header Properties
+ * Displays app branding (logo + title) and an optional collapse toggle button
+ */
+interface SideNavHeaderProps {
+    /**
+     * App logo or icon element (e.g. an <img>, SVG, or MUI Icon)
+     */
+    logo?: ReactNode;
+    /**
+     * App or brand title text displayed next to the logo
+     */
+    title: string;
+    /**
+     * Whether to show the collapse toggle button
+     * @default true
+     */
+    showCollapseButton?: boolean;
+    /**
+     * Callback fired when the collapse button is clicked.
+     * Wire this up to toggle sidebar expanded/collapsed state (V2).
+     */
+    onCollapse?: () => void;
+    /**
+     * Callback fired when the logo/title branding area is clicked.
+     * Use this for "go to home" navigation. Only the logo + title region
+     * is clickable — the collapse button and surrounding padding are excluded.
+     */
+    onLogoClick?: () => void;
+    /**
+     * Accessibility label for the header region
+     * @default '{title} navigation header'
+     */
+    ariaLabel?: string;
+    /**
+     * Whether sidebar is collapsed - V2
+     * When true:
+     * - Title text is hidden
+     * - Logo remains visible (compact)
+     * - Toggle button shows expand icon (→)
+     * @default false
+     */
+    collapsed?: boolean;
+}
+/**
+ * Compound component slots for SideNav
+ */
+interface SideNavHeaderSlotProps {
+    children: ReactNode;
+    className?: string;
+}
+interface SideNavNavigationProps {
+    children: ReactNode;
+    className?: string;
+}
+interface SideNavFooterProps {
+    children: ReactNode;
+    className?: string;
+}
+
+/**
+ * SideNav Component
+ * Main container for side navigation with compound components
+ * V2: Added collapsed state support with animated transitions
+ */
+
+/**
+ * SideNav.Header compound component
+ * Passes collapsed state and toggle handler to children
+ */
+declare const Header: React__default.NamedExoticComponent<SideNavHeaderSlotProps>;
+/**
+ * SideNav.Navigation compound component
+ * Passes collapsed state to children
+ */
+declare const Navigation: React__default.NamedExoticComponent<SideNavNavigationProps>;
+/**
+ * SideNav.Footer compound component
+ * Passes collapsed state to children
+ */
+declare const Footer: React__default.NamedExoticComponent<SideNavFooterProps>;
+/**
+ * Main SideNav component with compound components
+ * V2: Supports controlled/uncontrolled collapsed state
+ */
+interface SideNavComponent extends React__default.FC<SideNavProps> {
+    Header: typeof Header;
+    Navigation: typeof Navigation;
+    Footer: typeof Footer;
+}
+declare const SideNav: SideNavComponent;
+
+/**
+ * SideNavHeader Component
+ * Displays app branding (logo + title) and an optional collapse toggle button
+ * V2: Supports collapsed state with compact logo-only view
+ */
+
+/**
+ * SideNavHeader Component
+ *
+ * Renders the app branding area at the top of the side navigation.
+ * Includes an optional logo, a title, and an optional collapse toggle button.
+ * V2: In collapsed state, shows logo stacked vertically above toggle button.
+ *
+ * If `onLogoClick` is provided, only the logo+title area is clickable
+ * (e.g. to navigate back to the home page). The rest of the header
+ * (collapse button, surrounding padding) does NOT trigger that callback.
+ */
+declare const SideNavHeader: React__default.NamedExoticComponent<SideNavHeaderProps>;
+
+/**
+ * NavigationList Component
+ * Container for multiple navigation items with scroll support
+ * V2: Passes collapsed state to navigation items
+ */
+
+/**
+ * NavigationList Component
+ */
+declare const NavigationList: React__default.NamedExoticComponent<NavigationListProps>;
+
+/**
+ * NavigationItem Component
+ * Individual navigation menu item with icon, label, and interactive states
+ * V2: Added collapsed state support with tooltips
+ */
+
+/**
+ * NavigationItem Component
+ * V2: Supports collapsed state with tooltip
+ */
+declare const NavigationItem: React__default.NamedExoticComponent<NavigationItemProps>;
+
+/**
+ * ConnectionStatus Component
+ * Displays connection status with pill-style indicator
+ * V2: Supports compact mode for collapsed sidebar
+ */
+
+/**
+ * ConnectionStatus Component
+ * V2: Supports compact mode
+ */
+declare const ConnectionStatus: React__default.NamedExoticComponent<ConnectionStatusProps>;
+
+/**
+ * AccountSection Component
+ * Displays user account information with avatar, name, and logout
+ * V2: Supports compact mode for collapsed sidebar
+ */
+
+/**
+ * AccountSection Component
+ * V2: Supports compact mode
+ */
+declare const AccountSection: React__default.NamedExoticComponent<AccountSectionProps>;
+
 type BadgeVariant = 'default' | 'primary' | 'success' | 'error';
 interface BadgeProps extends Omit<BadgeProps$1, 'color' | 'variant'> {
     variant?: BadgeVariant;
@@ -1107,4 +1558,4 @@ interface CodeEditorProps {
  */
 declare const CodeEditor: React__default.FC<CodeEditorProps>;
 
-export { Accordion, type AccordionProps, ActivityAppIcon, Alert, type AlertProps, type AlertSeverity, AppBar, type AppBarProps, AppLoading, type AppLoadingProps, Avatar, AvatarIcon, type AvatarProps, Badge, type BadgeProps, BarTrackingIcon, type BreadcrumbItem, Breadcrumbs, type BreadcrumbsProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, BytesSize, type BytesSizeProps, Card, CardActions, CardContent, CardHeader, type CardProps, CereIcon, ChartWidget, type ChartWidgetProps, CheckMarkAnimation, Checkbox, type CheckboxProps, Chip, type ChipProps, CircularProgress, type CircularProgressProps, ClockIcon, CloudFlashIcon, CodeEditor, type CodeEditorLanguage, type CodeEditorProps, Collapse, type CollapseProps, DecentralizedServerIcon, Dialog, type DialogProps, DiscordIcon, Divider, type DividerProps, DownloadIcon, Drawer, type DrawerProps, Dropdown, DropdownAnchor, type DropdownAnchorProps, type DropdownProps, EmptyState, type EmptyStateProps, FilledFolderIcon, FlowEditor, type FlowEditorProps, FolderIcon, GithubLogoIcon, IconButton, type IconButtonProps, LeftArrowIcon, Link, type LinkProps, List, ListItem, type ListItemProps, type ListProps, Loading, LoadingAnimation, type LoadingAnimationProps, LoadingButton, type LoadingButtonProps, type LoadingProps, Logo, type LogoProps, Markdown, type MarkdownProps, Menu, MenuItem, type MenuItemProps, type MenuProps, type MessageOptions, MessagesProvider, MetricsChart, type MetricsChartProps, type MetricsPeriod, OnboardingProvider, Pagination, type PaginationProps, Paper, type PaperProps, PeriodSelect, Progress, type ProgressProps, QRCode, type QRCodeProps, Radio, type RadioProps, RightArrowIcon, SearchField, type SearchFieldProps, Selector, type SelectorOption, type SelectorProps, type Service, ServiceSelectorButton, type ServiceSelectorButtonProps, ShareIcon, Sidebar, SidebarItem, type SidebarItemProps, type SidebarProps, Snackbar, type SnackbarProps, Step, StepButton, type StepButtonProps, StepContent, type StepContentProps, StepLabel, type StepLabelProps, type StepProps, Stepper, type StepperProps, StorageAppIcon, Switch, type SwitchProps, Tab, type TabProps, Table, TableHeader, type TableHeaderProps, type TableProps, TextField, type TextFieldProps, ToggleButton, ToggleButtonGroup, type ToggleButtonGroupProps, type ToggleButtonProps, Tooltip, type TooltipProps, Truncate, type TruncateProps, UploadFileIcon, UploadFolderIcon, type Workspace, WorkspaceSelectorButton, type WorkspaceSelectorButtonProps, colors, theme, useIsDesktop, useIsMobile, useIsTablet, useMessages, useOnboarding };
+export { Accordion, type AccordionProps, AccountSection, type AccountSectionProps, ActivityAppIcon, Alert, type AlertProps, type AlertSeverity, AppBar, type AppBarProps, AppLoading, type AppLoadingProps, Avatar, AvatarIcon, type AvatarProps, Badge, type BadgeProps, BarTrackingIcon, type BreadcrumbItem, Breadcrumbs, type BreadcrumbsProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, BytesSize, type BytesSizeProps, Card, CardActions, CardContent, CardHeader, type CardProps, CereIcon, ChartWidget, type ChartWidgetProps, CheckMarkAnimation, Checkbox, type CheckboxProps, Chip, type ChipProps, CircularProgress, type CircularProgressProps, ClockIcon, CloudFlashIcon, CodeEditor, type CodeEditorLanguage, type CodeEditorProps, Collapse, type CollapseProps, ConnectionStatus, type ConnectionStatusProps, DecentralizedServerIcon, Dialog, type DialogProps, DiscordIcon, Divider, type DividerProps, DownloadIcon, Drawer, type DrawerProps, Dropdown, DropdownAnchor, type DropdownAnchorProps, type DropdownProps, EmptyState, type EmptyStateProps, FilledFolderIcon, FlowEditor, type FlowEditorProps, FolderIcon, GithubLogoIcon, IconButton, type IconButtonProps, LeftArrowIcon, Link, type LinkProps, List, ListItem, type ListItemProps, type ListProps, Loading, LoadingAnimation, type LoadingAnimationProps, LoadingButton, type LoadingButtonProps, type LoadingProps, Logo, type LogoProps, Markdown, type MarkdownProps, Menu, MenuItem, type MenuItemProps, type MenuProps, type MessageOptions, MessagesProvider, MetricsChart, type MetricsChartProps, type MetricsPeriod, NavigationItem, type NavigationItemProps, NavigationList, type NavigationListProps, OnboardingProvider, Pagination, type PaginationProps, Paper, type PaperProps, PeriodSelect, Progress, type ProgressProps, QRCode, type QRCodeProps, Radio, type RadioProps, RightArrowIcon, SearchField, type SearchFieldProps, Selector, type SelectorOption, type SelectorProps, type Service, ServiceSelectorButton, type ServiceSelectorButtonProps, ShareIcon, SideNav, SideNavHeader, type SideNavHeaderProps, type SideNavProps, Sidebar, SidebarItem, type SidebarItemProps, type SidebarProps, Snackbar, type SnackbarProps, Step, StepButton, type StepButtonProps, StepContent, type StepContentProps, StepLabel, type StepLabelProps, type StepProps, Stepper, type StepperProps, StorageAppIcon, Switch, type SwitchProps, Tab, type TabProps, Table, TableHeader, type TableHeaderProps, type TableProps, TextField, type TextFieldProps, ToggleButton, ToggleButtonGroup, type ToggleButtonGroupProps, type ToggleButtonProps, Tooltip, type TooltipProps, Truncate, type TruncateProps, UploadFileIcon, UploadFolderIcon, type UserInfo, type Workspace, WorkspaceSelectorButton, type WorkspaceSelectorButtonProps, colors, theme, useIsDesktop, useIsMobile, useIsTablet, useMessages, useOnboarding };