@cere/cere-design-system 0.0.45 → 0.2.0

package/dist/navigation.d.mts

@@ -0,0 +1,611 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { PopoverProps } from '@mui/material/Popover';
+import * as React from 'react';
+import React__default, { ReactNode, Ref } from 'react';
+import { StepperProps as StepperProps$1 } from '@mui/material/Stepper';
+import { StepProps as StepProps$1 } from '@mui/material/Step';
+import { StepLabelProps as StepLabelProps$1 } from '@mui/material/StepLabel';
+import { StepContentProps as StepContentProps$1 } from '@mui/material/StepContent';
+import { StepButtonProps as StepButtonProps$1 } from '@mui/material/StepButton';
+import { ListItemButtonProps } from '@mui/material/ListItemButton';
+import { TabProps as TabProps$1 } from '@mui/material/Tab';
+import { MenuProps as MenuProps$1 } from '@mui/material/Menu';
+import { PaginationProps as PaginationProps$1 } from '@mui/material/Pagination';
+
+type DropdownAnchorProps = {
+    open?: boolean;
+    label?: ReactNode;
+    leftElement?: ReactNode;
+    onOpen?: () => void;
+    variant?: 'header' | 'button';
+};
+declare const DropdownAnchor: React.ForwardRefExoticComponent<DropdownAnchorProps & React.RefAttributes<HTMLButtonElement>>;
+
+type RenderAnchorOptions = {
+    ref: Ref<any>;
+    open: boolean;
+    onOpen: () => void;
+};
+type DropdownProps = Pick<PopoverProps, 'open' | 'children'> & Omit<DropdownAnchorProps, 'open'> & {
+    direction?: 'right' | 'left';
+    dense?: boolean;
+    disableGutters?: boolean;
+    disablePaddings?: boolean;
+    onToggle?: (open: boolean) => void;
+    renderAnchor?: (options: RenderAnchorOptions) => ReactNode;
+    variant: 'header' | 'button';
+};
+declare const Dropdown: ({ open, label, leftElement, direction, children, onToggle, dense, disableGutters, disablePaddings, variant, renderAnchor, }: DropdownProps) => react_jsx_runtime.JSX.Element;
+
+interface SidebarItemProps {
+    label: string;
+    icon?: React__default.ReactNode;
+    selected?: boolean;
+    onClick?: () => void;
+    size?: 'small' | 'medium' | 'large';
+    endIcon?: React__default.ReactNode;
+    children?: React__default.ReactNode;
+}
+declare const SidebarItem: React__default.FC<SidebarItemProps>;
+
+interface SidebarProps {
+    open?: boolean;
+    width?: number;
+    items: SidebarItemProps[];
+    onClose?: () => void;
+    variant?: 'permanent' | 'persistent' | 'temporary';
+}
+declare const Sidebar: React__default.FC<SidebarProps>;
+
+type StepperProps = StepperProps$1;
+/**
+ * Stepper component - displays progress through a sequence of steps
+ *
+ * @example
+ * ```tsx
+ * <Stepper activeStep={activeStep}>
+ *   <Step>
+ *     <StepLabel>Step 1</StepLabel>
+ *   </Step>
+ *   <Step>
+ *     <StepLabel>Step 2</StepLabel>
+ *   </Step>
+ * </Stepper>
+ * ```
+ */
+declare const Stepper: React__default.FC<StepperProps>;
+type StepProps = StepProps$1;
+/**
+ * Step component - represents a single step in a Stepper
+ */
+declare const Step: React__default.FC<StepProps>;
+type StepLabelProps = StepLabelProps$1;
+/**
+ * StepLabel component - label for a Step
+ */
+declare const StepLabel: React__default.FC<StepLabelProps>;
+type StepContentProps = StepContentProps$1;
+/**
+ * StepContent component - optional content that appears below a StepLabel
+ */
+declare const StepContent: React__default.FC<StepContentProps>;
+type StepButtonProps = StepButtonProps$1;
+/**
+ * StepButton component - makes a Step clickable
+ */
+declare const StepButton: React__default.FC<StepButtonProps>;
+
+interface NumberedStepperStep {
+    key: string;
+    label: string;
+}
+interface NumberedStepperProps {
+    steps: NumberedStepperStep[];
+    /** Index of the active step. -1 = none active. */
+    current: number;
+    className?: string;
+}
+/**
+ * Vertical numbered stepper used by Try-this-out and similar guided flows.
+ * Brand-styled: active rows take the violet palette; completed rows show ✓.
+ */
+declare const NumberedStepper: React__default.ForwardRefExoticComponent<NumberedStepperProps & React__default.RefAttributes<HTMLOListElement>>;
+
+/**
+ * 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.MemoExoticComponent<React__default.ForwardRefExoticComponent<Omit<NavigationItemProps, "ref"> & React__default.RefAttributes<HTMLElement>>>;
+
+/**
+ * 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>;
+
+interface TabProps extends Omit<TabProps$1, 'icon'> {
+    badge?: number | string;
+    badgeVariant?: 'default' | 'primary' | 'success' | 'error';
+}
+declare const Tab: React__default.FC<TabProps>;
+
+interface MenuProps extends Omit<MenuProps$1, 'open'> {
+    anchorEl?: HTMLElement | null;
+    onClose: () => void;
+}
+declare const Menu: React__default.ForwardRefExoticComponent<Omit<MenuProps, "ref"> & React__default.RefAttributes<HTMLDivElement>>;
+interface MenuItemProps {
+    icon?: React__default.ReactNode;
+    label: string;
+    onClick?: () => void;
+    disabled?: boolean;
+    divider?: boolean;
+}
+declare const MenuItem: React__default.ForwardRefExoticComponent<MenuItemProps & React__default.RefAttributes<HTMLLIElement>>;
+
+interface PaginationProps extends Omit<PaginationProps$1, 'color'> {
+    color?: 'primary' | 'secondary' | 'standard';
+}
+declare const Pagination: React__default.FC<PaginationProps>;
+
+interface SelectorOption {
+    id: string;
+    name: string;
+    description?: string;
+    avatar?: string;
+    icon?: React__default.ReactNode;
+    disabled?: boolean;
+}
+interface SelectorProps {
+    options: SelectorOption[];
+    selectedId: string | null;
+    onSelect: (id: string) => void;
+    onCreate?: () => void;
+    loading?: boolean;
+    placeholder?: string;
+    emptyMessage?: string;
+    compact?: boolean;
+    renderSelected?: (option: SelectorOption) => React__default.ReactNode;
+    width?: number;
+}
+declare const Selector: React__default.FC<SelectorProps>;
+
+export { AccountSection, type AccountSectionProps, ConnectionStatus, type ConnectionStatusProps, Dropdown, DropdownAnchor, type DropdownAnchorProps, type DropdownProps, Menu, MenuItem, type MenuItemProps, type MenuProps, NavigationItem, type NavigationItemProps, NavigationList, type NavigationListProps, NumberedStepper, type NumberedStepperProps, type NumberedStepperStep, Pagination, type PaginationProps, Selector, type SelectorOption, type SelectorProps, SideNav, SideNavHeader, type SideNavHeaderProps, type SideNavProps, Sidebar, SidebarItem, type SidebarItemProps, type SidebarProps, Step, StepButton, type StepButtonProps, StepContent, type StepContentProps, StepLabel, type StepLabelProps, type StepProps, Stepper, type StepperProps, Tab, type TabProps, type UserInfo };