@sekiui/elements 0.0.56 → 0.0.59

package/dist/types/index.d.ts

@@ -1,2 +1,6 @@
 export { Components, JSX } from './components';
 export { SekiSwitch } from './components/switch/seki-switch';
+export * from './services';
+export * from './utils/common';
+export * from './utils/a11y';
+export * from './types';

package/dist/types/services/focus.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Focus Management Service
+ * Provides utilities for focus management, focus traps, and focus restoration
+ */
+export interface FocusTrapOptions {
+    initialFocus?: HTMLElement;
+    restoreFocus?: boolean;
+    allowOutsideClick?: boolean;
+}
+/**
+ * FocusService - Centralized focus management
+ * Provides:
+ * - Focus trap implementation
+ * - Focus restoration
+ * - Focusable element detection
+ * - Focus utilities for accessibility
+ */
+export declare class FocusService {
+    private focusTrapStack;
+    private previouslyFocusedElement;
+    /**
+     * Get all focusable elements within a container
+     * Includes buttons, links, inputs, textareas, selects, and elements with tabindex
+     */
+    getFocusableElements(container?: HTMLElement | Document): HTMLElement[];
+    /**
+     * Check if an element is focusable
+     */
+    isFocusable(element: HTMLElement): boolean;
+    /**
+     * Set focus to an element with optional callbacks
+     */
+    setFocus(element: HTMLElement | null, options?: {
+        preventScroll?: boolean;
+    }): boolean;
+    /**
+     * Trap focus within a container (keyboard navigation stays within bounds)
+     * @param container - The element to trap focus within
+     * @param options - Focus trap options
+     */
+    createFocusTrap(container: HTMLElement, options?: FocusTrapOptions): void;
+    /**
+     * Release focus trap from a container
+     */
+    releaseFocusTrap(container: HTMLElement, restoreFocus?: boolean): void;
+    /**
+     * Get the first focusable element in a container
+     */
+    getFirstFocusable(container?: HTMLElement | Document): HTMLElement | null;
+    /**
+     * Get the last focusable element in a container
+     */
+    getLastFocusable(container?: HTMLElement | Document): HTMLElement | null;
+    /**
+     * Move focus to the next focusable element
+     */
+    focusNext(container?: HTMLElement | Document): boolean;
+    /**
+     * Move focus to the previous focusable element
+     */
+    focusPrevious(container?: HTMLElement | Document): boolean;
+    /**
+     * Clear all focus traps
+     */
+    clearFocusTraps(): void;
+}
+/**
+ * Get the singleton FocusService instance
+ */
+export declare function getFocusService(): FocusService;
+/**
+ * Create a new isolated FocusService instance
+ */
+export declare function createFocusService(): FocusService;

package/dist/types/services/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Services Index
+ * Central export point for all application services
+ */
+export * from './keyboard';
+export * from './focus';
+export * from './media-query';

package/dist/types/services/keyboard.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Keyboard Service
+ * Provides normalized keyboard event handling and shortcut management
+ * Handles cross-platform shortcuts (Ctrl/Cmd combinations)
+ */
+export interface KeyboardShortcut {
+    key: string;
+    ctrlKey?: boolean;
+    shiftKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+    handler: (event: Event) => void;
+}
+export interface KeyboardShortcutOptions {
+    key: string;
+    ctrl?: boolean;
+    shift?: boolean;
+    alt?: boolean;
+    meta?: boolean;
+    handler: (event: KeyboardEvent) => void;
+    preventDefault?: boolean;
+}
+/**
+ * KeyboardService - Centralized keyboard event management
+ * Provides:
+ * - Normalized keyboard shortcuts (handles Ctrl vs Cmd on Mac)
+ * - Cross-platform shortcut registration
+ * - Event cleanup and teardown
+ */
+export declare class KeyboardService {
+    private shortcuts;
+    private listeners;
+    /**
+     * Register a keyboard shortcut
+     * @param id - Unique identifier for this shortcut
+     * @param options - Shortcut configuration
+     */
+    registerShortcut(id: string, options: KeyboardShortcutOptions): void;
+    /**
+     * Register a shortcut that works with Ctrl on Windows/Linux and Cmd on Mac
+     * @param id - Unique identifier for this shortcut
+     * @param key - The key to listen for
+     * @param handler - Callback when shortcut is triggered
+     * @param preventDefault - Whether to prevent default browser behavior
+     */
+    registerCtrlOrCmdShortcut(id: string, key: string, handler: (event: KeyboardEvent) => void, preventDefault?: boolean): void;
+    /**
+     * Unregister a keyboard shortcut
+     * @param id - The identifier of the shortcut to remove
+     */
+    unregisterShortcut(id: string): void;
+    /**
+     * Unregister all shortcuts and clean up
+     */
+    cleanup(): void;
+    /**
+     * Check if a keyboard event matches a specific key combination
+     * @param event - The keyboard event to check
+     * @param key - The key to match
+     * @param ctrl - Whether Ctrl/Cmd should be pressed
+     * @param shift - Whether Shift should be pressed
+     * @param alt - Whether Alt should be pressed
+     */
+    matchesShortcut(event: KeyboardEvent, key: string, ctrl?: boolean, shift?: boolean, alt?: boolean): boolean;
+}
+/**
+ * Get the singleton KeyboardService instance
+ */
+export declare function getKeyboardService(): KeyboardService;
+/**
+ * Create a new isolated KeyboardService instance
+ * Useful for testing or when you need independent event handling
+ */
+export declare function createKeyboardService(): KeyboardService;

package/dist/types/services/media-query.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Media Query Service
+ * Provides utilities for responsive design and media query management
+ */
+export interface MediaQueryListener {
+    query: string;
+    handler: (match: boolean) => void;
+    matcher?: MediaQueryList;
+}
+export interface BreakpointConfig {
+    sm?: string;
+    md?: string;
+    lg?: string;
+    xl?: string;
+    '2xl'?: string;
+}
+/**
+ * Default breakpoints (Tailwind-inspired)
+ */
+export declare const DEFAULT_BREAKPOINTS: BreakpointConfig;
+/**
+ * MediaQueryService - Centralized media query management
+ * Provides:
+ * - Media query listener registration
+ * - Breakpoint detection
+ * - Window resize handling
+ * - Current viewport information
+ */
+export declare class MediaQueryService {
+    private listeners;
+    private breakpoints;
+    private resizeObserver;
+    private resizeListeners;
+    constructor(breakpoints?: BreakpointConfig);
+    /**
+     * Register a media query listener
+     * @param id - Unique identifier for this listener
+     * @param query - CSS media query string
+     * @param handler - Callback when media query matches/unmatches
+     */
+    registerMediaQuery(id: string, query: string, handler: (match: boolean) => void): void;
+    /**
+     * Register a breakpoint listener (easier than raw media queries)
+     * @param id - Unique identifier
+     * @param breakpoint - Breakpoint name (sm, md, lg, xl, 2xl)
+     * @param type - Type of match: 'min' (mobile-first) or 'max' (desktop-first)
+     * @param handler - Callback when breakpoint matches
+     */
+    registerBreakpoint(id: string, breakpoint: keyof BreakpointConfig, type: "min" | "max" | undefined, handler: (match: boolean) => void): void;
+    /**
+     * Unregister a media query listener
+     */
+    unregisterMediaQuery(id: string): void;
+    /**
+     * Check if a media query currently matches
+     */
+    isMatching(query: string): boolean;
+    /**
+     * Check if a breakpoint is currently active
+     */
+    isBreakpointActive(breakpoint: keyof BreakpointConfig, type?: 'min' | 'max'): boolean;
+    /**
+     * Get the current viewport width
+     */
+    getViewportWidth(): number;
+    /**
+     * Get the current viewport height
+     */
+    getViewportHeight(): number;
+    /**
+     * Check if viewport is mobile-sized (< 768px)
+     */
+    isMobile(): boolean;
+    /**
+     * Check if viewport is tablet-sized (768px - 1024px)
+     */
+    isTablet(): boolean;
+    /**
+     * Check if viewport is desktop-sized (>= 1024px)
+     */
+    isDesktop(): boolean;
+    /**
+     * Check if prefers-reduced-motion is enabled
+     */
+    prefersReducedMotion(): boolean;
+    /**
+     * Check if dark mode is preferred
+     */
+    prefersDarkMode(): boolean;
+    /**
+     * Get the current device orientation
+     */
+    getOrientation(): 'portrait' | 'landscape';
+    /**
+     * Register a window resize listener
+     * @param id - Unique identifier
+     * @param handler - Callback with (width, height)
+     * @param debounceMs - Debounce delay in milliseconds
+     */
+    registerResizeListener(id: string, handler: (width: number, height: number) => void, debounceMs?: number): void;
+    /**
+     * Unregister a resize listener
+     */
+    unregisterResizeListener(id: string): void;
+    /**
+     * Clean up all listeners
+     */
+    cleanup(): void;
+    /**
+     * Update breakpoint configuration
+     */
+    setBreakpoints(breakpoints: BreakpointConfig): void;
+}
+/**
+ * Get the singleton MediaQueryService instance
+ */
+export declare function getMediaQueryService(breakpoints?: BreakpointConfig): MediaQueryService;
+/**
+ * Create a new isolated MediaQueryService instance
+ */
+export declare function createMediaQueryService(breakpoints?: BreakpointConfig): MediaQueryService;

package/dist/types/stencil-public-runtime.d.ts

@@ -1,5 +1,6 @@
 type CustomMethodDecorator<T> = (target: object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>) => TypedPropertyDescriptor<T> | void;
-type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type MixinInstance<F> = F extends (base: MixedInCtor) => MixedInCtor<infer I> ? I : never;
 export interface ComponentDecorator {
     (opts?: ComponentOptions): ClassDecorator;
 }
@@ -364,18 +365,27 @@ export declare function readTask(task: RafCallback): void;
  * Unhandled exception raised while rendering, during event handling, or lifecycles will trigger the custom event handler.
  */
 export declare const setErrorHandler: (handler: ErrorHandler) => void;
-export type MixinFactory = <TBase extends new (...args: any[]) => any>(base: TBase) => abstract new (...args: ConstructorParameters<TBase>) => any;
+/**
+ * @deprecated - Use `MixedInCtor` instead:
+ * ```ts
+ * import { MixedInCtor } from '@stencil/core';
+ *
+ * const AFactoryFn = <B extends MixedInCtor>(Base: B) => {class A extends Base { propA = A }; return A;}
+ * ```
+ */
+export type MixinFactory = (base: MixedInCtor) => MixedInCtor;
+export type MixedInCtor<T = {}> = new (...args: any[]) => T;
 /**
  * Compose multiple mixin classes into a single constructor.
  * The resulting class has the combined instance types of all mixed-in classes.
  *
  * Example:
- * ```
- * import { Mixin, MixinFactory } from '@stencil/core';
+ * ```ts
+ * import { Mixin, MixedInCtor } from '@stencil/core';
  *
- * const AWrap: MixinFactory = (Base) => {class A extends Base { propA = A }; return A;}
- * const BWrap: MixinFactory = (Base) => {class B extends Base { propB = B }; return B;}
- * const CWrap: MixinFactory = (Base) => {class C extends Base { propC = C }; return C;}
+ * const AWrap = <B extends MixedInCtor>(Base: B) => {class A extends Base { propA = A }; return A;}
+ * const BWrap = <B extends MixedInCtor>(Base: B) => {class B extends Base { propB = B }; return B;}
+ * const CWrap = <B extends MixedInCtor>(Base: B) => {class C extends Base { propC = C }; return C;}
  *
  * class X extends Mixin(AWrap, BWrap, CWrap) {
  *   render() { return <div>{this.propA} {this.propB} {this.propC}</div>; }
@@ -383,9 +393,9 @@ export type MixinFactory = <TBase extends new (...args: any[]) => any>(base: TBa
  * ```
  *
  * @param mixinFactories mixin factory functions that return a class which extends from the provided class.
- * @returns a class that that is composed from extending each of the provided classes in the order they were provided.
+ * @returns a class that is composed from extending each of the provided classes in the order they were provided.
  */
-export declare function Mixin<TMixins extends readonly MixinFactory[]>(...mixinFactories: TMixins): abstract new (...args: any[]) => UnionToIntersection<InstanceType<ReturnType<TMixins[number]>>>;
+export declare function Mixin<const TMixins extends readonly MixinFactory[]>(...mixinFactories: TMixins): abstract new (...args: any[]) => UnionToIntersection<MixinInstance<TMixins[number]>>;
 /**
  * This file gets copied to all distributions of stencil component collections.
  * - no imports

package/dist/types/types.d.ts

@@ -0,0 +1,105 @@
+/**
+ * SekiUI Type Definitions
+ * Central export point for all type definitions across components and services
+ */
+export interface SekiButtonProps {
+    disabled?: boolean;
+    size?: 'sm' | 'md' | 'lg' | 'icon-sm' | 'icon' | 'icon-lg';
+    type?: 'button' | 'submit' | 'reset';
+    variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'link';
+    ariaLabel?: string;
+}
+export interface SekiFieldProps {
+    invalid?: boolean;
+    orientation?: 'vertical' | 'horizontal' | 'responsive';
+}
+export interface SekiInputProps {
+    type?: 'text' | 'password' | 'email' | 'number' | 'tel' | 'url' | 'search' | 'date';
+    placeholder?: string;
+    value?: string;
+    disabled?: boolean;
+    readonly?: boolean;
+    required?: boolean;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    ariaLabel?: string;
+    ariaDescribedBy?: string;
+}
+export interface SekiSkeletonProps {
+    count?: number;
+    width?: string | number;
+    height?: string | number;
+    circle?: boolean;
+}
+export interface SekiSwitchProps {
+    checked?: boolean;
+    disabled?: boolean;
+    name?: string;
+    value?: string;
+    ariaLabel?: string;
+    ariaDescribedBy?: string;
+}
+export type TooltipSide = 'top' | 'right' | 'bottom' | 'left';
+export interface TooltipShowDetail {
+    side: TooltipSide;
+}
+export interface TooltipHideDetail {
+    side: TooltipSide;
+}
+export interface TooltipPositionedDetail {
+    x: number;
+    y: number;
+    side: TooltipSide;
+}
+export interface CustomEventDetail {
+    [key: string]: any;
+}
+export type ClassValue = string | undefined | null | false | {
+    [key: string]: boolean;
+};
+export type DataAttributeValue = string | number | boolean | null | undefined;
+/**
+ * Type guard to check if a value is a valid sidebar variant
+ */
+export declare function isSidebarVariant(value: any): value is 'sidebar' | 'floating' | 'inset';
+/**
+ * Type guard to check if a value is a valid collapse mode
+ */
+export declare function isCollapseMode(value: any): value is 'offcanvas' | 'icon' | 'none';
+/**
+ * Type guard to check if a value is a valid button size
+ */
+export declare function isButtonSize(value: any): value is 'sm' | 'md' | 'lg' | 'icon-sm' | 'icon' | 'icon-lg';
+/**
+ * Type guard to check if a value is a valid button variant
+ */
+export declare function isButtonVariant(value: any): value is 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'link';
+/**
+ * Type guard to check if a value is a valid tooltip side
+ */
+export declare function isTooltipSide(value: any): value is TooltipSide;
+/**
+ * Create a partial type (all properties optional)
+ */
+export type Partial<T> = {
+    [P in keyof T]?: T[P];
+};
+/**
+ * Create a readonly type
+ */
+export type Readonly<T> = {
+    readonly [P in keyof T]: T[P];
+};
+/**
+ * Create a required type (all properties required)
+ */
+export type Required<T> = {
+    [P in keyof T]-?: T[P];
+};
+/**
+ * Create a record type
+ */
+export type Record<K extends string | number | symbol, T> = {
+    [P in K]: T;
+};

package/dist/types/utils/a11y.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Accessibility Utilities
+ * Provides helpers for ARIA attributes, keyboard navigation, and accessibility features
+ */
+/**
+ * Generate a unique ID for ARIA relationships
+ * @param prefix - Optional prefix for the ID
+ * @param suffix - Optional suffix for the ID
+ */
+export declare function generateAriaId(prefix?: string, suffix?: string): string;
+/**
+ * Set ARIA attributes on an element
+ * @param element - The element to set attributes on
+ * @param attributes - Object with attribute names and values
+ */
+export declare function setAriaAttributes(element: HTMLElement, attributes: Record<string, string | boolean | null>): void;
+/**
+ * Add accessible label to an element
+ * @param element - The element to label
+ * @param label - The label text or element ID
+ * @param useAriaLabel - If true, uses aria-label; if false, uses aria-labelledby
+ */
+export declare function addAriaLabel(element: HTMLElement, label: string, useAriaLabel?: boolean): void;
+/**
+ * Add accessible description to an element
+ * @param element - The element to describe
+ * @param description - The description text or element ID
+ * @param useAriaDescription - If true, uses aria-description; if false, uses aria-describedby
+ */
+export declare function addAriaDescription(element: HTMLElement, description: string, useAriaDescription?: boolean): void;
+/**
+ * Set ARIA live region announcement
+ * @param element - The element to make a live region
+ * @param message - The message to announce
+ * @param politeness - 'polite' (default), 'assertive', or 'off'
+ * @param atomic - Whether to announce the entire region
+ */
+export declare function announceAriaLive(element: HTMLElement, message: string, politeness?: 'polite' | 'assertive' | 'off', atomic?: boolean): void;
+/**
+ * Mark an element as disabled with ARIA attributes
+ * @param element - The element to mark as disabled
+ * @param disabled - Whether the element is disabled
+ */
+export declare function setAriaDisabled(element: HTMLElement, disabled: boolean): void;
+/**
+ * Mark an element as expanded/collapsed (for collapsible sections)
+ * @param element - The element to mark
+ * @param expanded - Whether the element is expanded
+ * @param targetId - ID of the element being controlled (optional)
+ */
+export declare function setAriaExpanded(element: HTMLElement, expanded: boolean, targetId?: string): void;
+/**
+ * Mark an element as selected
+ * @param element - The element to mark
+ * @param selected - Whether the element is selected
+ */
+export declare function setAriaSelected(element: HTMLElement, selected: boolean): void;
+/**
+ * Mark an element as checked (for checkboxes and radio buttons)
+ * @param element - The element to mark
+ * @param checked - The checked state ('true', 'false', or 'mixed')
+ */
+export declare function setAriaChecked(element: HTMLElement, checked: 'true' | 'false' | 'mixed'): void;
+/**
+ * Set the current value of an element (for sliders, spinbuttons, etc.)
+ * @param element - The element
+ * @param current - Current value
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @param text - Optional text description of the value
+ */
+export declare function setAriaValueNow(element: HTMLElement, current: number, min?: number, max?: number, text?: string): void;
+/**
+ * Mark an element as having a popup (for menus, popovers, etc.)
+ * @param element - The element with the popup trigger
+ * @param type - Type of popup: 'menu', 'listbox', 'tree', 'grid', 'dialog'
+ * @param popupId - ID of the popup element
+ */
+export declare function setAriaPopup(element: HTMLElement, type?: 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog', popupId?: string): void;
+/**
+ * Set role for an element
+ * @param element - The element
+ * @param role - The role (button, menu, menuitem, etc.)
+ */
+export declare function setRole(element: HTMLElement, role: string): void;
+/**
+ * Get the accessible name of an element
+ * Follows ARIA naming convention: aria-labelledby > aria-label > title > textContent
+ */
+export declare function getAccessibleName(element: HTMLElement): string;
+/**
+ * Create a skip link for keyboard navigation
+ * @param text - Link text
+ * @param targetId - ID of element to skip to
+ */
+export declare function createSkipLink(text: string, targetId: string): HTMLElement;
+/**
+ * Check if element should be hidden from screen readers
+ */
+export declare function isAriaHidden(element: HTMLElement): boolean;
+/**
+ * Hide element from screen readers but keep visually visible
+ */
+export declare function setAriaHidden(element: HTMLElement, hidden: boolean): void;
+/**
+ * Announce a message to screen readers immediately (without ARIA live regions)
+ * @param message - The message to announce
+ * @param politeness - 'polite' (default) or 'assertive'
+ */
+export declare function announceToScreenReader(message: string, politeness?: 'polite' | 'assertive'): void;
+/**
+ * Set proper heading hierarchy
+ * @param element - The heading element
+ * @param level - Heading level (1-6)
+ */
+export declare function setHeadingLevel(element: HTMLElement, level: 1 | 2 | 3 | 4 | 5 | 6): void;
+/**
+ * Enable keyboard navigation for a custom component
+ * @param element - The element that should handle keyboard
+ * @param keys - Map of key to handler function
+ */
+export declare function enableKeyboardNavigation(element: HTMLElement, keys: Record<string, (event: KeyboardEvent) => void>): (() => void);
+/**
+ * Check if element has accessible focus styling
+ */
+export declare function hasAccessibleFocus(element: HTMLElement): boolean;
+/**
+ * Ensure focus visible styling (for focus-visible pseudo-class)
+ */
+export declare function ensureFocusVisible(element: HTMLElement): void;