@sekiui/elements 0.0.56 → 0.0.59

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

@@ -0,0 +1,185 @@
+/**
+ * SekiSidebar Component
+ * @description Main sidebar container component managing collapse state, layout variant,
+ * and responsive configuration. Provides context to child components.
+ * @component
+ * @example
+ * <seki-sidebar variant="sidebar" collapse-mode="icon" persistent>
+ *   <seki-sidebar-header>Header Content</seki-sidebar-header>
+ *   <seki-sidebar-content>Menu content</seki-sidebar-content>
+ *   <seki-sidebar-footer>Footer content</seki-sidebar-footer>
+ * </seki-sidebar>
+ */
+import { EventEmitter } from '../../stencil-public-runtime';
+import { SidebarProps, SidebarState, OpenChangeDetail, VariantChangeDetail, CollapseModeChangeDetail, MobileStateChangeDetail } from './types';
+export declare class SekiSidebar {
+    /**
+     * Layout variant: standard, floating (detached), or inset
+     * @type {'sidebar' | 'floating' | 'inset'}
+     * @default 'sidebar'
+     */
+    variant: SidebarProps['variant'];
+    /**
+     * Collapse mechanism: offcanvas (slides), icon (shrinks), or none (fixed)
+     * @type {'offcanvas' | 'icon' | 'none'}
+     * @default 'offcanvas'
+     */
+    collapseMode: SidebarProps['collapseMode'];
+    /**
+     * Initial open/closed state
+     * @type {boolean}
+     * @default true
+     */
+    defaultOpen: boolean;
+    /**
+     * Persist state to localStorage
+     * @type {boolean}
+     * @default false
+     */
+    persistent: boolean;
+    /**
+     * Viewport width for mobile detection (px)
+     * @type {number}
+     * @default 768
+     */
+    mobileBreakpoint: number;
+    /**
+     * Position: left or right side of viewport
+     * @type {'left' | 'right'}
+     * @default 'left'
+     */
+    side: SidebarProps['side'];
+    /**
+     * Storage key for persisted state
+     * @type {string}
+     * @default 'seki-sidebar-state'
+     */
+    persistenceKey: string;
+    /**
+     * Callback fired when open state changes
+     */
+    onOpenChange?: (isOpen: boolean) => void;
+    el: HTMLElement;
+    /**
+     * Internal state: whether sidebar is open/expanded
+     */
+    isOpen: boolean;
+    /**
+     * Internal state: whether viewport is mobile
+     */
+    isMobile: boolean;
+    /**
+     * Event fired when sidebar opens/closes
+     */
+    openChange: EventEmitter<OpenChangeDetail>;
+    /**
+     * Event fired when variant changes
+     */
+    variantChange: EventEmitter<VariantChangeDetail>;
+    /**
+     * Event fired when collapse mode changes
+     */
+    collapseModeChange: EventEmitter<CollapseModeChangeDetail>;
+    /**
+     * Event fired when mobile state changes
+     */
+    mobileStateChange: EventEmitter<MobileStateChangeDetail>;
+    /**
+     * Note: Context distribution to child components via parent-child DOM hierarchy
+     * Child components use closest('seki-sidebar') to access parent methods
+     */
+    private resizeObserver;
+    private mediaQueryList;
+    private keyboardShortcutId;
+    /**
+     * Component lifecycle: initialize state
+     */
+    componentWillLoad(): void;
+    /**
+     * Watch for variant changes
+     */
+    watchVariant(newValue: SidebarProps['variant'] | undefined): void;
+    /**
+     * Watch for collapse mode changes
+     */
+    watchCollapseMode(newValue: SidebarProps['collapseMode'] | undefined): void;
+    /**
+     * Component lifecycle: after render
+     */
+    componentDidLoad(): void;
+    /**
+     * Component lifecycle: on prop changes
+     */
+    componentWillUpdate(): void;
+    /**
+     * Component lifecycle: cleanup
+     */
+    disconnectedCallback(): void;
+    /**
+     * Listen for variant prop changes
+     */
+    onVariantChange(newVariant: string): void;
+    /**
+     * Listen for collapseMode prop changes
+     */
+    onCollapseModeChange(newMode: string): void;
+    /**
+     * Handle media query changes for mobile detection
+     */
+    private handleMediaQueryChange;
+    /**
+     * Detect if viewport is mobile
+     */
+    private detectMobileState;
+    /**
+     * Setup resize detection using ResizeObserver
+     */
+    private setupResizeDetection;
+    /**
+     * Setup keyboard shortcut for toggling sidebar (Ctrl+B or Cmd+B)
+     * Uses the KeyboardService for centralized event handling
+     */
+    private setupKeyboardShortcut;
+    /**
+     * Note: Context updates handled via event emissions and state changes
+     */
+    private updateContext;
+    /**
+     * Get current state synchronously
+     */
+    private getStateSync;
+    /**
+     * Open the sidebar (set isOpen=true)
+     * @returns {Promise<void>}
+     */
+    open(): Promise<void>;
+    /**
+     * Close the sidebar (set isOpen=false)
+     * @returns {Promise<void>}
+     */
+    close(): Promise<void>;
+    /**
+     * Toggle the sidebar open/closed state
+     * @returns {Promise<void>}
+     */
+    toggle(): Promise<void>;
+    /**
+     * Get current sidebar state
+     * @returns {Promise<SidebarState>}
+     */
+    getState(): Promise<SidebarState>;
+    /**
+     * Update sidebar state
+     * @param {Partial<SidebarState>} state - Partial state object
+     * @returns {Promise<void>}
+     */
+    setState(state: Partial<SidebarState>): Promise<void>;
+    /**
+     * Persist state to localStorage if persistent=true
+     */
+    private persistState;
+    /**
+     * Render the component
+     */
+    render(): any;
+}

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>;
+}