@sekiui/elements 0.0.55 → 0.0.57

package/dist/types/components/sidebar/types.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Sidebar Component Type Definitions
+ * @module sidebar/types
+ *
+ * Complete TypeScript interfaces and types for the sidebar component system.
+ * These types are used throughout the component implementation, tests, and exported
+ * to the npm package for consumer IDE autocomplete support.
+ */
+/**
+ * SidebarState - Core state object managed by the sidebar provider
+ * Defines the complete state of the sidebar including collapse state, layout variant,
+ * and responsive configuration.
+ */
+export interface SidebarState {
+    /** Whether sidebar is open/expanded (true) or closed/collapsed (false) */
+    isOpen: boolean;
+    /** Collapse mechanism: 'offcanvas' (slides), 'icon' (shrinks to icons), 'none' (fixed) */
+    collapseMode: 'offcanvas' | 'icon' | 'none';
+    /** Layout variant: 'sidebar' (standard), 'floating' (detached), 'inset' (integrated) */
+    variant: 'sidebar' | 'floating' | 'inset';
+    /** Whether viewport is mobile (<mobileBreakpoint) */
+    isMobile: boolean;
+    /** localStorage key for state persistence */
+    persistenceKey: string;
+}
+/**
+ * Default sidebar state values
+ */
+export declare const DEFAULT_SIDEBAR_STATE: SidebarState;
+/**
+ * SidebarProps - Properties for the main seki-sidebar component
+ */
+export interface SidebarProps {
+    /** Layout variant: standard, floating (detached), or inset */
+    variant?: 'sidebar' | 'floating' | 'inset';
+    /** Collapse mechanism: offcanvas (slides), icon (shrinks), or none (fixed) */
+    collapseMode?: 'offcanvas' | 'icon' | 'none';
+    /** Initial open/closed state */
+    defaultOpen?: boolean;
+    /** Persist state to localStorage */
+    persistent?: boolean;
+    /** Viewport width for mobile detection (px) */
+    mobileBreakpoint?: number;
+    /** Position: left or right side of viewport */
+    side?: 'left' | 'right';
+    /** Storage key for persisted state */
+    persistenceKey?: string;
+    /** Callback fired when open state changes */
+    onOpenChange?: (isOpen: boolean) => void;
+}
+/**
+ * SidebarTriggerProps - Properties for the seki-sidebar-trigger component
+ */
+export interface SidebarTriggerProps {
+    /** Accessibility label for the button */
+    ariaLabel?: string;
+    /** Icon name or SVG path (optional) */
+    icon?: string;
+}
+/**
+ * SidebarGroupProps - Properties for the seki-sidebar-group component
+ */
+export interface SidebarGroupProps {
+    /** Section header text (optional) */
+    title?: string;
+    /** Allow collapsing this group */
+    collapsible?: boolean;
+    /** Initial collapsed state */
+    defaultCollapsed?: boolean;
+    /** Optional action button configuration */
+    action?: {
+        icon: string;
+        label: string;
+        onClick: () => void;
+    };
+}
+/**
+ * SidebarMenuItemProps - Properties for the seki-sidebar-menu-item component
+ */
+export interface SidebarMenuItemProps {
+    /** Navigation URL (optional) */
+    href?: string;
+    /** Link target: _blank, _self, etc. */
+    target?: string;
+    /** Disable interaction */
+    disabled?: boolean;
+    /** Highlight as current page */
+    isActive?: boolean;
+    /** Badge indicator for the item */
+    badge?: {
+        text: string;
+        variant?: 'default' | 'secondary' | 'destructive';
+    };
+    /** Accessibility label override */
+    ariaLabel?: string;
+    /** ARIA current value for active items */
+    ariaCurrentValue?: 'page' | 'step' | 'location' | 'date' | 'time' | 'true' | 'false';
+    /** Callback fired on click */
+    onClick?: (event: MouseEvent) => void;
+}
+/**
+ * SidebarMenuSubProps - Properties for the seki-sidebar-menu-sub component
+ */
+export interface SidebarMenuSubProps {
+    /** Label for the submenu (shown when expanded) */
+    label?: string;
+    /** Initial collapsed state */
+    defaultCollapsed?: boolean;
+}
+/**
+ * MenuItem - Individual navigation item with optional nesting
+ */
+export interface MenuItem {
+    /** Unique identifier */
+    id: string;
+    /** Display text */
+    label: string;
+    /** Navigation URL (optional) */
+    href?: string;
+    /** Icon name or SVG path (optional) */
+    icon?: string;
+    /** Badge indicator (optional) */
+    badge?: {
+        text: string;
+        variant?: 'default' | 'secondary' | 'destructive';
+    };
+    /** Highlight as current page */
+    isActive?: boolean;
+    /** Prevent interaction */
+    disabled?: boolean;
+    /** Nested menu items */
+    children?: MenuItem[];
+    /** Custom click handler */
+    onClick?: (item: MenuItem) => void;
+    /** Accessibility label (optional) */
+    ariaLabel?: string;
+}
+/**
+ * MenuGroup - Container for related menu items with optional header
+ */
+export interface MenuGroup {
+    /** Unique identifier */
+    id: string;
+    /** Section header text (optional) */
+    title?: string;
+    /** List of menu items in this group */
+    items: MenuItem[];
+    /** Allow collapsing this group */
+    collapsible?: boolean;
+    /** Current collapsed state */
+    isCollapsed?: boolean;
+    /** Optional action button */
+    action?: {
+        icon: string;
+        onClick: () => void;
+        ariaLabel: string;
+    };
+}
+/**
+ * Event detail payloads for sidebar custom events
+ */
+/** Detail payload for openChange event */
+export interface OpenChangeDetail {
+    isOpen: boolean;
+}
+/** Detail payload for variantChange event */
+export interface VariantChangeDetail {
+    variant: 'sidebar' | 'floating' | 'inset';
+}
+/** Detail payload for collapseModeChange event */
+export interface CollapseModeChangeDetail {
+    collapseMode: 'offcanvas' | 'icon' | 'none';
+}
+/** Detail payload for mobileStateChange event */
+export interface MobileStateChangeDetail {
+    isMobile: boolean;
+}
+/** Detail payload for collapsedChange event (on groups) */
+export interface CollapsedChangeDetail {
+    isCollapsed: boolean;
+}
+/** Detail payload for navigate event (on menu items) */
+export interface NavigateDetail {
+    href: string;
+    target?: string;
+}
+/**
+ * Component instance types for TypeScript consumers
+ */
+export interface SidebarElement extends HTMLElement {
+    /** Current sidebar state */
+    getState(): SidebarState;
+    /** Update sidebar state */
+    setState(state: Partial<SidebarState>): Promise<void>;
+    /** Open the sidebar (set isOpen=true) */
+    open(): Promise<void>;
+    /** Close the sidebar (set isOpen=false) */
+    close(): Promise<void>;
+    /** Toggle the sidebar open/closed state */
+    toggle(): Promise<void>;
+}
+export interface SidebarTriggerElement extends HTMLElement {
+    readonly ariaExpanded: string | null;
+}
+export interface SidebarGroupElement extends HTMLElement {
+    /** Get current collapsed state */
+    isCollapsed(): boolean;
+    /** Set collapsed state */
+    setCollapsed(collapsed: boolean): Promise<void>;
+}
+export interface SidebarMenuItemElement extends HTMLElement {
+    readonly ariaCurrent: string | null;
+}
+export interface SidebarMenuSubElement extends HTMLElement {
+    readonly ariaExpanded: string | null;
+}
+/**
+ * Event handler type for media query changes
+ */
+export type MediaQueryChangeHandler = (mq: {
+    matches: boolean;
+}) => void;
+/**
+ * MediaQueryList-like interface for browser compatibility
+ */
+export interface MediaQueryListCompat {
+    matches: boolean;
+    addEventListener: (event: string, handler: MediaQueryChangeHandler) => void;
+    removeListener: (handler: MediaQueryChangeHandler) => void;
+    addListener: (handler: MediaQueryChangeHandler) => void;
+}
+/**
+ * ResizeObserver-like interface for browser compatibility
+ */
+export interface ResizeObserverCompat {
+    disconnect: () => void;
+    observe: (element: HTMLElement) => void;
+}
+/**
+ * Stencil Context type for sidebar state distribution
+ */
+export interface SidebarContextValue {
+    state: SidebarState;
+    setState: (partial: Partial<SidebarState>) => Promise<void>;
+}