@fabio.caffarello/react-design-system 1.7.0 → 1.9.0

package/dist/ui/organisms/Sidebar/SidebarGroup/SidebarGroup.d.ts

@@ -0,0 +1,27 @@
+import type { HTMLAttributes, ReactNode } from "react";
+export interface SidebarGroupProps extends HTMLAttributes<HTMLDivElement> {
+    title?: string;
+    titleIcon?: ReactNode;
+    children: ReactNode;
+    collapsible?: boolean;
+    defaultCollapsed?: boolean;
+    collapsed?: boolean;
+    onCollapseChange?: (collapsed: boolean) => void;
+    storageKey?: string;
+    showChevron?: boolean;
+}
+/**
+ * SidebarGroup Component
+ *
+ * A group container for sidebar items with optional title.
+ * Follows Atomic Design principles as a Molecule component.
+ *
+ * @example
+ * ```tsx
+ * <SidebarGroup title="Agile">
+ *   <SidebarItem href="/epics">Epics</SidebarItem>
+ *   <SidebarItem href="/stories">Stories</SidebarItem>
+ * </SidebarGroup>
+ * ```
+ */
+export default function SidebarGroup({ title, titleIcon, children, collapsible, defaultCollapsed, collapsed, onCollapseChange, storageKey, showChevron, className, ...props }: SidebarGroupProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/organisms/Sidebar/SidebarGroup/SidebarGroup.stories.d.ts

@@ -0,0 +1,11 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import SidebarGroup from "./SidebarGroup";
+declare const meta: Meta<typeof SidebarGroup>;
+export declare const Default: StoryObj<typeof SidebarGroup>;
+export declare const WithoutTitle: StoryObj<typeof SidebarGroup>;
+export declare const Collapsible: StoryObj<typeof SidebarGroup>;
+export declare const CollapsibleDefaultCollapsed: StoryObj<typeof SidebarGroup>;
+export declare const ControlledCollapsible: StoryObj<typeof SidebarGroup>;
+export declare const WithNestedItems: StoryObj<typeof SidebarGroup>;
+export declare const MultipleGroups: StoryObj<typeof SidebarGroup>;
+export default meta;

package/dist/ui/organisms/Sidebar/SidebarGroup/SidebarGroup.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ui/organisms/Sidebar/SidebarHeader/SidebarHeader.d.ts

@@ -0,0 +1,50 @@
+import type { HTMLAttributes, ReactNode } from "react";
+export interface SidebarHeaderProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Title text
+     */
+    title: string;
+    /**
+     * Optional subtitle or description
+     */
+    subtitle?: string;
+    /**
+     * Optional icon to display before the title
+     */
+    icon?: ReactNode;
+    /**
+     * Callback when close button is clicked
+     */
+    onClose?: () => void;
+    /**
+     * Whether to show the close button
+     * @default false
+     */
+    showCloseButton?: boolean;
+    /**
+     * Variant of the header
+     * - 'default': Standard header with padding
+     * - 'compact': Reduced padding
+     * - 'minimal': Minimal styling, no border
+     * @default 'default'
+     */
+    variant?: 'default' | 'compact' | 'minimal';
+    /**
+     * Additional actions/content to display in the header
+     */
+    children?: ReactNode;
+}
+/**
+ * SidebarHeader Component
+ *
+ * Header section of a sidebar with title and optional close button.
+ * Enhanced with variants, icons, and better token integration.
+ * Follows Atomic Design principles as a Molecule component.
+ *
+ * @example
+ * ```tsx
+ * <SidebarHeader title="Navigation" onClose={handleClose} />
+ * <SidebarHeader title="Settings" variant="compact" subtitle="Configure your preferences" />
+ * ```
+ */
+export default function SidebarHeader({ title, subtitle, icon, onClose, showCloseButton, variant, children, className, ...props }: SidebarHeaderProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/organisms/Sidebar/SidebarHeader/SidebarHeader.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ui/organisms/Sidebar/SidebarItem/SidebarItem.d.ts

@@ -0,0 +1,23 @@
+import type { AnchorHTMLAttributes, ReactNode } from "react";
+export interface SidebarItemProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+    href: string;
+    isActive?: boolean;
+    icon?: ReactNode;
+    nested?: boolean | number;
+    iconSize?: 'sm' | 'md' | 'lg';
+    children: ReactNode;
+}
+/**
+ * SidebarItem Component
+ *
+ * An individual navigation item within a sidebar.
+ * Follows Atomic Design principles as an Atom component.
+ *
+ * @example
+ * ```tsx
+ * <SidebarItem href="/epics" isActive={true} icon={<EpicIcon />}>
+ *   Epics
+ * </SidebarItem>
+ * ```
+ */
+export default function SidebarItem({ href, isActive, icon, nested, iconSize, children, className, ...props }: SidebarItemProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/organisms/Sidebar/SidebarItem/SidebarItem.stories.d.ts

@@ -0,0 +1,10 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import SidebarItem from "./SidebarItem";
+declare const meta: Meta<typeof SidebarItem>;
+export declare const Default: StoryObj<typeof SidebarItem>;
+export declare const Active: StoryObj<typeof SidebarItem>;
+export declare const WithIcon: StoryObj<typeof SidebarItem>;
+export declare const Nested: StoryObj<typeof SidebarItem>;
+export declare const NestedLevel2: StoryObj<typeof SidebarItem>;
+export declare const DifferentIconSizes: StoryObj<typeof SidebarItem>;
+export default meta;

package/dist/ui/organisms/Sidebar/SidebarItem/SidebarItem.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ui/organisms/Sidebar/index.d.ts

@@ -0,0 +1,8 @@
+export { default as Sidebar } from './Sidebar';
+export type { SidebarProps } from './Sidebar';
+export { default as SidebarItem } from './SidebarItem/SidebarItem';
+export type { SidebarItemProps } from './SidebarItem/SidebarItem';
+export { default as SidebarGroup } from './SidebarGroup/SidebarGroup';
+export type { SidebarGroupProps } from './SidebarGroup/SidebarGroup';
+export { default as SidebarHeader } from './SidebarHeader/SidebarHeader';
+export type { SidebarHeaderProps } from './SidebarHeader/SidebarHeader';

package/dist/ui/organisms/SplitSidebar/SplitSidebar.d.ts

@@ -0,0 +1,197 @@
+import React, { type ReactNode, type HTMLAttributes } from 'react';
+import { SplitSidebarToggle, SplitSidebarResizeHandle, SplitSidebarLazyContent } from './components';
+export interface SplitSidebarContextValue {
+    collapsed: boolean;
+    toggle: () => void;
+    setCollapsed: (collapsed: boolean) => void;
+    width?: number;
+    isMobile?: boolean;
+    isResizing?: boolean;
+}
+export declare const SplitSidebarContext: React.Context<SplitSidebarContextValue | null>;
+export interface SplitSidebarProps extends HTMLAttributes<HTMLAsideElement> {
+    /**
+     * Initial collapsed state (uncontrolled mode)
+     * @default false
+     */
+    defaultCollapsed?: boolean;
+    /**
+     * Controlled collapsed state
+     */
+    collapsed?: boolean;
+    /**
+     * Callback when collapse state changes
+     */
+    onCollapseChange?: (collapsed: boolean) => void;
+    /**
+     * Whether the sidebar can be collapsed
+     * @default true
+     */
+    collapsible?: boolean;
+    /**
+     * Total width of the sidebar
+     * @default '320px'
+     */
+    width?: number | string;
+    /**
+     * Width of the navigation column
+     * @default '56px'
+     */
+    navigationWidth?: number | string;
+    /**
+     * Variant of the sidebar
+     * @default 'default'
+     */
+    variant?: 'default' | 'compact' | 'minimal' | 'elevated' | 'bordered';
+    /**
+     * Whether responsive behavior is enabled
+     * @default false
+     */
+    responsive?: boolean;
+    /**
+     * Breakpoint in pixels for mobile detection
+     * @default 768
+     */
+    mobileBreakpoint?: number;
+    /**
+     * Mobile variant behavior
+     * @default 'overlay'
+     */
+    mobileVariant?: 'overlay' | 'push' | 'collapse';
+    /**
+     * Whether to show backdrop in mobile overlay mode
+     * @default true
+     */
+    overlayBackdrop?: boolean;
+    /**
+     * Callback when mobile state changes
+     */
+    onMobileChange?: (isMobile: boolean) => void;
+    /**
+     * Storage key for persistence (localStorage)
+     */
+    storageKey?: string;
+    /**
+     * Persistence type
+     * @default 'localStorage'
+     */
+    persistState?: 'localStorage' | 'sessionStorage' | false;
+    /**
+     * Whether to persist width
+     * @default false
+     */
+    persistWidth?: boolean;
+    /**
+     * Whether sidebar is resizable
+     * @default false
+     */
+    resizable?: boolean;
+    /**
+     * Minimum width constraint
+     */
+    minWidth?: number | string;
+    /**
+     * Maximum width constraint
+     */
+    maxWidth?: number | string;
+    /**
+     * Snap points (widths to snap to when dragging)
+     */
+    snapPoints?: number[];
+    /**
+     * Callback when width changes
+     */
+    onWidthChange?: (width: number) => void;
+    /**
+     * Animation duration in milliseconds
+     * @default 300
+     */
+    animationDuration?: number;
+    /**
+     * Animation easing function
+     * @default 'ease-in-out'
+     */
+    animationEasing?: string;
+    /**
+     * Whether animations are enabled
+     * @default true
+     */
+    enableAnimations?: boolean;
+    /**
+     * Children (should include SplitSidebar.Navigation and SplitSidebar.Content)
+     */
+    children: ReactNode;
+}
+interface SplitSidebarNavigationProps {
+    children: ReactNode;
+}
+interface SplitSidebarContentProps {
+    title?: string;
+    showHeader?: boolean;
+    scrollable?: boolean;
+    padding?: 'none' | 'sm' | 'md' | 'lg';
+    /**
+     * Loading state
+     */
+    loading?: boolean;
+    /**
+     * Empty state
+     */
+    empty?: boolean;
+    /**
+     * Empty state message
+     */
+    emptyMessage?: string;
+    /**
+     * Error state
+     */
+    error?: Error | null;
+    /**
+     * Retry callback for error state
+     */
+    onRetry?: () => void;
+    children: ReactNode;
+}
+/**
+ * SplitSidebar Root Component
+ *
+ * Main component that combines narrow navigation + content area.
+ * Supports collapsible navigation with smooth transitions, responsiveness,
+ * persistence, resize, and advanced accessibility.
+ *
+ * @example
+ * ```tsx
+ * <SplitSidebar width="320px" navigationWidth="56px">
+ *   <SplitSidebar.Navigation>
+ *     <Tabs>...</Tabs>
+ *   </SplitSidebar.Navigation>
+ *   <SplitSidebar.Content title="Settings">
+ *     <div>Content here</div>
+ *   </SplitSidebar.Content>
+ * </SplitSidebar>
+ * ```
+ */
+declare function SplitSidebarRoot({ defaultCollapsed, collapsed: controlledCollapsed, onCollapseChange, collapsible, width, navigationWidth, variant, responsive, mobileBreakpoint, mobileVariant, overlayBackdrop, onMobileChange, storageKey, persistState, persistWidth, resizable, minWidth, maxWidth, snapPoints, onWidthChange, animationDuration, animationEasing, enableAnimations, children, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...props }: SplitSidebarProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * SplitSidebar Navigation Component
+ *
+ * Renders the narrow navigation column on the left side.
+ */
+declare const SplitSidebarNavigation: React.NamedExoticComponent<SplitSidebarNavigationProps>;
+/**
+ * SplitSidebar Content Component
+ *
+ * Renders the main content area on the right side.
+ * Supports loading, empty, and error states.
+ */
+declare const SplitSidebarContent: React.NamedExoticComponent<SplitSidebarContentProps>;
+declare const SplitSidebar: typeof SplitSidebarRoot & {
+    Navigation: typeof SplitSidebarNavigation;
+    Content: typeof SplitSidebarContent;
+    Toggle: typeof SplitSidebarToggle;
+    ResizeHandle: typeof SplitSidebarResizeHandle;
+    LazyContent: typeof SplitSidebarLazyContent;
+};
+export default SplitSidebar;
+export { SplitSidebar };
+export type { SplitSidebarProps, SplitSidebarContextValue };

package/dist/ui/organisms/SplitSidebar/SplitSidebar.stories.d.ts

@@ -0,0 +1,15 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import SplitSidebar from './SplitSidebar';
+declare const meta: Meta<typeof SplitSidebar>;
+export default meta;
+type Story = StoryObj<typeof SplitSidebar>;
+export declare const Default: Story;
+export declare const Collapsible: Story;
+export declare const LongContent: Story;
+export declare const WithoutHeader: Story;
+export declare const WithToggle: Story;
+export declare const Resizable: Story;
+export declare const Responsive: Story;
+export declare const WithStates: Story;
+export declare const Variants: Story;
+export declare const WithPersistence: Story;

package/dist/ui/organisms/SplitSidebar/components/SplitSidebarLazyContent.d.ts

@@ -0,0 +1,41 @@
+import React, { type ReactNode } from 'react';
+export interface SplitSidebarLazyContentProps {
+    /**
+     * Lazy load function that returns a component
+     */
+    lazyLoad: () => Promise<{
+        default: React.ComponentType<any>;
+    }>;
+    /**
+     * Props to pass to SplitSidebar.Content
+     */
+    contentProps?: {
+        title?: string;
+        showHeader?: boolean;
+        scrollable?: boolean;
+        padding?: 'none' | 'sm' | 'md' | 'lg';
+    };
+    /**
+     * Fallback component while loading
+     */
+    fallback?: ReactNode;
+    /**
+     * Props to pass to the lazy-loaded component
+     */
+    componentProps?: Record<string, any>;
+}
+/**
+ * SplitSidebar Lazy Content Component
+ *
+ * Wrapper for lazy loading SplitSidebar.Content.
+ * Useful for code splitting and performance optimization.
+ *
+ * @example
+ * ```tsx
+ * <SplitSidebar.LazyContent
+ *   lazyLoad={() => import('./HeavyContent')}
+ *   contentProps={{ title: 'Settings' }}
+ * />
+ * ```
+ */
+export default function SplitSidebarLazyContent({ lazyLoad, contentProps, fallback, componentProps, }: SplitSidebarLazyContentProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/organisms/SplitSidebar/components/SplitSidebarResizeHandle.d.ts

@@ -0,0 +1,49 @@
+export interface SplitSidebarResizeHandleProps {
+    /**
+     * Initial width
+     */
+    initialWidth: number;
+    /**
+     * Minimum width constraint
+     */
+    minWidth?: number;
+    /**
+     * Maximum width constraint
+     */
+    maxWidth?: number;
+    /**
+     * Snap points (widths to snap to when dragging)
+     */
+    snapPoints?: number[];
+    /**
+     * Callback when width changes
+     */
+    onWidthChange?: (width: number) => void;
+    /**
+     * Whether resize is enabled
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Custom className
+     */
+    className?: string;
+}
+/**
+ * SplitSidebar Resize Handle Component
+ *
+ * Drag handle for resizing the sidebar width.
+ * Supports snap points and min/max constraints.
+ *
+ * @example
+ * ```tsx
+ * <SplitSidebar.ResizeHandle
+ *   initialWidth={320}
+ *   minWidth={200}
+ *   maxWidth={600}
+ *   snapPoints={[200, 320, 480]}
+ *   onWidthChange={(width) => setWidth(width)}
+ * />
+ * ```
+ */
+export default function SplitSidebarResizeHandle({ initialWidth, minWidth, maxWidth, snapPoints, onWidthChange, enabled, className, }: SplitSidebarResizeHandleProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/ui/organisms/SplitSidebar/components/SplitSidebarToggle.d.ts

@@ -0,0 +1,42 @@
+export interface SplitSidebarToggleProps {
+    /**
+     * Position of the toggle button
+     * @default 'top'
+     */
+    position?: 'top' | 'bottom' | 'inside';
+    /**
+     * Whether to show tooltip
+     * @default true
+     */
+    showTooltip?: boolean;
+    /**
+     * Keyboard shortcut (e.g., 'Ctrl+B')
+     * @default 'Ctrl+B'
+     */
+    keyboardShortcut?: string;
+    /**
+     * Whether keyboard shortcut is enabled
+     * @default true
+     */
+    enableKeyboardShortcut?: boolean;
+    /**
+     * Custom className
+     */
+    className?: string;
+    /**
+     * Custom aria-label
+     */
+    'aria-label'?: string;
+}
+/**
+ * SplitSidebar Toggle Component
+ *
+ * Button to toggle sidebar collapse/expand state.
+ * Supports keyboard shortcuts and tooltips.
+ *
+ * @example
+ * ```tsx
+ * <SplitSidebar.Toggle position="top" showTooltip={true} />
+ * ```
+ */
+export default function SplitSidebarToggle({ position, showTooltip, keyboardShortcut, enableKeyboardShortcut, className, 'aria-label': ariaLabel, }: SplitSidebarToggleProps): import("react/jsx-runtime").JSX.Element;

package/dist/ui/organisms/SplitSidebar/components/index.d.ts

@@ -0,0 +1,6 @@
+export { default as SplitSidebarToggle } from './SplitSidebarToggle';
+export type { SplitSidebarToggleProps } from './SplitSidebarToggle';
+export { default as SplitSidebarResizeHandle } from './SplitSidebarResizeHandle';
+export type { SplitSidebarResizeHandleProps } from './SplitSidebarResizeHandle';
+export { default as SplitSidebarLazyContent } from './SplitSidebarLazyContent';
+export type { SplitSidebarLazyContentProps } from './SplitSidebarLazyContent';

package/dist/ui/organisms/SplitSidebar/hooks/index.d.ts

@@ -0,0 +1,9 @@
+export { useResponsiveSidebar } from './useResponsiveSidebar';
+export type { UseResponsiveSidebarOptions, UseResponsiveSidebarReturn } from './useResponsiveSidebar';
+export { useKeyboardShortcut } from './useKeyboardShortcut';
+export type { UseKeyboardShortcutOptions } from './useKeyboardShortcut';
+export { useResize } from './useResize';
+export type { UseResizeOptions, UseResizeReturn } from './useResize';
+export { useFocusManagement } from './useFocusManagement';
+export type { UseFocusManagementOptions } from './useFocusManagement';
+export { useSplitSidebar } from './useSplitSidebar';

package/dist/ui/organisms/SplitSidebar/hooks/useFocusManagement.d.ts

@@ -0,0 +1,36 @@
+export interface UseFocusManagementOptions {
+    /**
+     * Whether focus trap is active
+     */
+    isActive: boolean;
+    /**
+     * Container element to trap focus within
+     */
+    containerRef: React.RefObject<HTMLElement>;
+    /**
+     * Whether to restore focus to previous element when deactivated
+     * @default true
+     */
+    restoreFocus?: boolean;
+    /**
+     * Initial element to focus when activated
+     */
+    initialFocusRef?: React.RefObject<HTMLElement>;
+}
+/**
+ * Hook for managing focus within a container (focus trap)
+ *
+ * Traps focus within a container element, useful for modals and overlays.
+ * Supports restoring focus when deactivated.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * useFocusManagement({
+ *   isActive: isOpen,
+ *   containerRef,
+ *   restoreFocus: true
+ * });
+ * ```
+ */
+export declare function useFocusManagement({ isActive, containerRef, restoreFocus, initialFocusRef, }: UseFocusManagementOptions): void;

package/dist/ui/organisms/SplitSidebar/hooks/useKeyboardShortcut.d.ts

@@ -0,0 +1,56 @@
+export interface UseKeyboardShortcutOptions {
+    /**
+     * Key to listen for (e.g., 'b', 'Escape', 'Enter')
+     */
+    key: string;
+    /**
+     * Whether Ctrl/Cmd key should be pressed
+     * @default false
+     */
+    ctrl?: boolean;
+    /**
+     * Whether Shift key should be pressed
+     * @default false
+     */
+    shift?: boolean;
+    /**
+     * Whether Alt key should be pressed
+     * @default false
+     */
+    alt?: boolean;
+    /**
+     * Whether Meta key should be pressed (Cmd on Mac)
+     * @default false
+     */
+    meta?: boolean;
+    /**
+     * Callback when shortcut is triggered
+     */
+    onTrigger: () => void;
+    /**
+     * Whether the shortcut is enabled
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Whether to prevent default behavior
+     * @default true
+     */
+    preventDefault?: boolean;
+}
+/**
+ * Hook for keyboard shortcuts
+ *
+ * Listens for keyboard combinations and triggers callbacks.
+ * Automatically ignores input fields unless explicitly allowed.
+ *
+ * @example
+ * ```tsx
+ * useKeyboardShortcut({
+ *   key: 'b',
+ *   ctrl: true,
+ *   onTrigger: () => toggleSidebar(),
+ * });
+ * ```
+ */
+export declare function useKeyboardShortcut({ key: targetKey, ctrl, shift, alt, meta, onTrigger, enabled, preventDefault, }: UseKeyboardShortcutOptions): void;

package/dist/ui/organisms/SplitSidebar/hooks/useResize.d.ts

@@ -0,0 +1,68 @@
+export interface UseResizeOptions {
+    /**
+     * Initial width
+     */
+    initialWidth: number;
+    /**
+     * Minimum width constraint
+     */
+    minWidth?: number;
+    /**
+     * Maximum width constraint
+     */
+    maxWidth?: number;
+    /**
+     * Snap points (widths to snap to when dragging)
+     */
+    snapPoints?: number[];
+    /**
+     * Snap threshold in pixels
+     * @default 20
+     */
+    snapThreshold?: number;
+    /**
+     * Callback when width changes
+     */
+    onWidthChange?: (width: number) => void;
+    /**
+     * Whether resize is enabled
+     * @default true
+     */
+    enabled?: boolean;
+}
+export interface UseResizeReturn {
+    /**
+     * Current width
+     */
+    width: number;
+    /**
+     * Whether currently resizing
+     */
+    isResizing: boolean;
+    /**
+     * Start resize handler (attach to mousedown)
+     */
+    startResize: (event: React.MouseEvent) => void;
+    /**
+     * Set width programmatically
+     */
+    setWidth: (width: number) => void;
+}
+/**
+ * Hook for drag-to-resize functionality
+ *
+ * Provides resize state and handlers for drag-to-resize interactions.
+ * Supports snap points and min/max constraints.
+ *
+ * @example
+ * ```tsx
+ * const { width, isResizing, startResize } = useResize({
+ *   initialWidth: 320,
+ *   minWidth: 200,
+ *   maxWidth: 600,
+ *   snapPoints: [200, 320, 480],
+ *   onWidthChange: (width) => console.log('Width:', width)
+ * });
+ * ```
+ */
+export declare function useResize({ initialWidth, minWidth, maxWidth, snapPoints, snapThreshold, onWidthChange, enabled, }: UseResizeOptions): UseResizeReturn;