@tachui/core 0.7.0-alpha1

package/dist/components/Grid.d.ts

@@ -0,0 +1,698 @@
+/**
+ * Grid Layout Components (Phase 1)
+ *
+ * SwiftUI-inspired Grid components with CSS Grid integration.
+ * Provides Grid, GridRow, LazyVGrid, and LazyHGrid components
+ * that mirror SwiftUI's grid system while leveraging modern CSS Grid capabilities.
+ */
+import type { ModifiableComponent, ModifierBuilder } from '../modifiers/types';
+import type { ComponentInstance, ComponentProps } from '../runtime/types';
+import { type ElementOverrideProps } from '../runtime/element-override';
+import { ComponentWithCSSClasses, type CSSClassesProps } from '../css-classes';
+import type { ResponsiveValue } from '../modifiers/responsive/types';
+import { GridDebugger, GridPerformanceMonitor, type EnhancedResponsiveGridConfig } from './GridResponsive';
+/**
+ * GridItem sizing configuration (SwiftUI-equivalent)
+ */
+export interface GridItemConfig {
+    type: 'fixed' | 'flexible' | 'adaptive';
+    size?: number;
+    minimum?: number;
+    maximum?: number;
+    spacing?: number;
+}
+/**
+ * Grid item spanning configuration (Phase 3)
+ */
+export interface GridSpanConfig {
+    columnSpan?: number;
+    rowSpan?: number;
+    columnStart?: number;
+    rowStart?: number;
+    area?: string;
+    alignment?: 'start' | 'center' | 'end' | 'stretch';
+}
+/**
+ * Enhanced grid item with spanning support (Phase 3)
+ */
+export interface EnhancedGridItemConfig extends GridItemConfig {
+    span?: GridSpanConfig;
+}
+/**
+ * GridItem factory class - matches SwiftUI GridItem exactly
+ */
+export declare class GridItem {
+    /**
+     * Fixed-size grid column/row
+     */
+    static fixed(size: number, spacing?: number): GridItemConfig;
+    /**
+     * Flexible grid column/row with optional constraints
+     */
+    static flexible(minimum?: number, maximum?: number): GridItemConfig;
+    /**
+     * Adaptive grid column/row with minimum size
+     */
+    static adaptive(minimum: number, maximum?: number): GridItemConfig;
+    /**
+     * Create spanning configuration for grid items (Phase 3)
+     */
+    static spanning(config: GridSpanConfig): GridSpanConfig;
+    /**
+     * Create enhanced grid item with spanning support (Phase 3)
+     */
+    static withSpan(baseConfig: GridItemConfig, spanConfig: GridSpanConfig): EnhancedGridItemConfig;
+}
+/**
+ * Responsive grid configuration for breakpoint-aware layouts
+ */
+export type ResponsiveGridItemConfig = {
+    base?: GridItemConfig[];
+    sm?: GridItemConfig[];
+    md?: GridItemConfig[];
+    lg?: GridItemConfig[];
+    xl?: GridItemConfig[];
+    xxl?: GridItemConfig[];
+};
+/**
+ * Grid alignment options (SwiftUI-equivalent)
+ */
+export type GridAlignment = 'topLeading' | 'top' | 'topTrailing' | 'leading' | 'center' | 'trailing' | 'bottomLeading' | 'bottom' | 'bottomTrailing';
+/**
+ * Base Grid component properties
+ */
+export interface BaseGridProps extends ComponentProps, ElementOverrideProps, CSSClassesProps {
+    children?: ComponentInstance[];
+    alignment?: GridAlignment;
+    spacing?: number | {
+        horizontal?: number;
+        vertical?: number;
+    };
+    debugLabel?: string;
+    /** Animation configuration for grid layout changes (Phase 3) */
+    animations?: GridAnimationConfig;
+    /** Accessibility configuration for grid components (Phase 3) */
+    accessibility?: GridAccessibilityConfig;
+    /** Advanced styling configuration for grid components (Phase 3) */
+    styling?: GridStylingConfig;
+}
+/**
+ * Grid component properties (explicit row/column control)
+ */
+export interface GridProps extends BaseGridProps {
+}
+/**
+ * LazyVGrid component properties (vertical scrolling with flexible columns)
+ */
+export interface LazyVGridProps extends BaseGridProps {
+    columns: GridItemConfig[] | ResponsiveGridItemConfig | ResponsiveValue<GridItemConfig[]>;
+    pinnedViews?: ('sectionHeaders' | 'sectionFooters')[];
+    /** Enhanced responsive configuration (Phase 2) */
+    responsive?: EnhancedResponsiveGridConfig;
+    /** Sectioned data with headers/footers (Phase 3) */
+    sections?: GridSection[];
+}
+/**
+ * LazyHGrid component properties (horizontal scrolling with flexible rows)
+ */
+export interface LazyHGridProps extends BaseGridProps {
+    rows: GridItemConfig[] | ResponsiveGridItemConfig | ResponsiveValue<GridItemConfig[]>;
+    pinnedViews?: ('sectionHeaders' | 'sectionFooters')[];
+    /** Enhanced responsive configuration (Phase 2) */
+    responsive?: EnhancedResponsiveGridConfig;
+    /** Sectioned data with headers/footers (Phase 3) */
+    sections?: GridSection[];
+}
+/**
+ * Grid animation configuration (Phase 3)
+ */
+export interface GridAnimationConfig {
+    /** Enable layout animations when grid structure changes */
+    layoutChanges?: boolean | {
+        duration?: number;
+        easing?: string;
+        delay?: number;
+    };
+    /** Enable animations when items are added/removed */
+    itemChanges?: boolean | {
+        enter?: {
+            duration?: number;
+            easing?: string;
+            delay?: number;
+            from?: 'fade' | 'scale' | 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right';
+        };
+        exit?: {
+            duration?: number;
+            easing?: string;
+            delay?: number;
+            to?: 'fade' | 'scale' | 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right';
+        };
+    };
+    /** Enable animations for responsive breakpoint changes */
+    responsive?: boolean | {
+        duration?: number;
+        easing?: string;
+        delay?: number;
+    };
+    /** Enable animations for section header/footer changes */
+    sections?: boolean | {
+        duration?: number;
+        easing?: string;
+        delay?: number;
+    };
+}
+/**
+ * Grid accessibility configuration (Phase 3)
+ */
+export interface GridAccessibilityConfig {
+    /** Main accessibility label for the grid */
+    label?: string;
+    /** Description of the grid's purpose */
+    description?: string;
+    /** ARIA role override (defaults to 'grid' for data grids, 'group' for layout grids) */
+    role?: 'grid' | 'group' | 'list' | 'region';
+    /** Enable keyboard navigation between grid items */
+    keyboardNavigation?: boolean | {
+        enabled?: boolean;
+        /** Arrow key behavior: 'grid' for 2D navigation, 'list' for linear navigation */
+        mode?: 'grid' | 'list';
+        /** Enable page up/down navigation */
+        pageNavigation?: boolean;
+        /** Enable home/end navigation */
+        homeEndNavigation?: boolean;
+    };
+    /** Enable focus management */
+    focusManagement?: boolean | {
+        enabled?: boolean;
+        /** Focus trap within grid */
+        trapFocus?: boolean;
+        /** Restore focus when grid is unmounted */
+        restoreFocus?: boolean;
+        /** Skip links for screen readers */
+        skipLinks?: boolean;
+    };
+    /** Screen reader optimizations */
+    screenReader?: boolean | {
+        enabled?: boolean;
+        /** Announce grid structure changes */
+        announceChanges?: boolean;
+        /** Provide row/column count information */
+        announceStructure?: boolean;
+        /** Announce item positions */
+        announcePositions?: boolean;
+    };
+    /** Reduced motion support */
+    reducedMotion?: boolean | {
+        respectPreference?: boolean;
+        fallbackBehavior?: 'disable' | 'reduce' | 'instant';
+    };
+}
+/**
+ * Advanced grid styling configuration (Phase 3)
+ */
+export interface GridStylingConfig {
+    /** Custom grid template areas for named grid positioning */
+    templateAreas?: string[];
+    /** Advanced gap configuration with different spacing for different breakpoints */
+    advancedGap?: {
+        row?: number | string | {
+            [breakpoint: string]: number | string;
+        };
+        column?: number | string | {
+            [breakpoint: string]: number | string;
+        };
+    };
+    /** Grid debugging and overlay styles */
+    debug?: boolean | {
+        enabled?: boolean;
+        /** Show grid lines */
+        showLines?: boolean;
+        /** Show grid areas */
+        showAreas?: boolean;
+        /** Grid line color */
+        lineColor?: string;
+        /** Grid line style */
+        lineStyle?: 'solid' | 'dashed' | 'dotted';
+        /** Show item numbers */
+        showItemNumbers?: boolean;
+    };
+    /** Theme integration */
+    theme?: {
+        /** Use theme-based grid colors */
+        useThemeColors?: boolean;
+        /** Custom theme variant */
+        variant?: string;
+        /** Grid-specific theme overrides */
+        overrides?: Record<string, string | number>;
+    };
+    /** Advanced hover and focus states */
+    itemStates?: {
+        /** Grid item hover effects */
+        hover?: {
+            enabled?: boolean;
+            transform?: 'scale' | 'lift' | 'glow' | 'highlight';
+            transition?: string;
+            customCSS?: Record<string, string>;
+        };
+        /** Grid item focus effects */
+        focus?: {
+            enabled?: boolean;
+            style?: 'ring' | 'outline' | 'background' | 'border';
+            color?: string;
+            customCSS?: Record<string, string>;
+        };
+        /** Grid item active/pressed effects */
+        active?: {
+            enabled?: boolean;
+            transform?: 'scale' | 'inset' | 'darken';
+            customCSS?: Record<string, string>;
+        };
+    };
+    /** Grid container styling */
+    container?: {
+        /** Background patterns or overlays */
+        background?: string | {
+            pattern?: 'dots' | 'lines' | 'grid' | 'none';
+            color?: string;
+            opacity?: number;
+        };
+        /** Container border and shadow */
+        border?: string;
+        borderRadius?: number | string;
+        boxShadow?: string;
+        /** Container padding */
+        padding?: number | string | {
+            top?: number | string;
+            right?: number | string;
+            bottom?: number | string;
+            left?: number | string;
+        };
+    };
+}
+/**
+ * Grid section configuration (Phase 3)
+ */
+export interface GridSection {
+    id: string;
+    header?: ComponentInstance | string;
+    footer?: ComponentInstance | string;
+    items: ComponentInstance[];
+    headerStyle?: 'automatic' | 'grouped' | 'plain' | 'sticky';
+    footerStyle?: 'automatic' | 'grouped' | 'plain' | 'sticky';
+}
+/**
+ * Grid section header/footer properties (Phase 3)
+ */
+export interface GridSectionHeaderProps extends ComponentProps, ElementOverrideProps, CSSClassesProps {
+    content: ComponentInstance | string;
+    sectionId: string;
+    type: 'header' | 'footer';
+    style: 'automatic' | 'grouped' | 'plain' | 'sticky';
+    debugLabel?: string;
+}
+/**
+ * GridRow component properties
+ */
+export interface GridRowProps extends ComponentProps, ElementOverrideProps, CSSClassesProps {
+    children?: ComponentInstance[];
+    alignment?: 'leading' | 'center' | 'trailing';
+    debugLabel?: string;
+}
+/**
+ * CSS Grid generation utilities
+ */
+declare class GridCSSGenerator {
+    /**
+     * Generate CSS grid-template-columns from GridItem configurations
+     */
+    static generateColumns(items: GridItemConfig[]): string;
+    /**
+     * Generate CSS grid-template-rows from GridItem configurations
+     */
+    static generateRows(items: GridItemConfig[]): string;
+    /**
+     * Generate responsive CSS for grid layouts
+     */
+    static generateResponsiveGridCSS(config: ResponsiveGridItemConfig, property: 'grid-template-columns' | 'grid-template-rows'): Record<string, string | Record<string, string>>;
+    /**
+     * Convert spacing configuration to CSS gap values
+     */
+    static generateSpacing(spacing?: number | {
+        horizontal?: number;
+        vertical?: number;
+    }): string;
+    /**
+     * Convert GridAlignment to CSS grid alignment properties
+     */
+    static generateAlignment(alignment: GridAlignment): {
+        justifyItems?: string;
+        alignItems?: string;
+    };
+    /**
+     * Generate CSS for section header/footer styling (Phase 3)
+     */
+    static generateSectionHeaderCSS(style: 'automatic' | 'grouped' | 'plain' | 'sticky', type: 'header' | 'footer', columnSpan: number): Record<string, string>;
+    /**
+     * Generate CSS animations for grid layout changes (Phase 3)
+     */
+    static generateGridAnimationCSS(animations: GridAnimationConfig): Record<string, string>;
+    /**
+     * Generate item entrance/exit animation keyframes (Phase 3)
+     */
+    static generateItemAnimationKeyframes(type: 'enter' | 'exit', animation: 'fade' | 'scale' | 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right'): Record<string, string>;
+    /**
+     * Generate accessibility attributes for grid elements (Phase 3)
+     */
+    static generateAccessibilityAttributes(accessibility: GridAccessibilityConfig, gridType: 'grid' | 'lazy-vgrid' | 'lazy-hgrid', columnCount?: number, rowCount?: number): Record<string, string | number | boolean>;
+    /**
+     * Generate reduced motion CSS based on user preferences (Phase 3)
+     */
+    static generateReducedMotionCSS(accessibility?: GridAccessibilityConfig): Record<string, string>;
+    /**
+     * Generate advanced styling CSS for grid components (Phase 3)
+     */
+    static generateAdvancedStylingCSS(styling: GridStylingConfig): Record<string, string>;
+    /**
+     * Generate item state CSS (hover, focus, active) (Phase 3)
+     */
+    static generateItemStateCSS(itemStates: NonNullable<GridStylingConfig['itemStates']>): Record<string, string>;
+    /**
+     * Get media query for breakpoint (helper function)
+     */
+    private static getMediaQueryForBreakpoint;
+}
+/**
+ * Grid Section Header/Footer component (Phase 3)
+ */
+declare class GridSectionHeaderComponent extends ComponentWithCSSClasses implements ComponentInstance<GridSectionHeaderProps> {
+    props: GridSectionHeaderProps;
+    readonly type: "component";
+    readonly id: string;
+    mounted: boolean;
+    cleanup: (() => void)[];
+    private effectiveTag;
+    private validationResult;
+    constructor(props: GridSectionHeaderProps);
+    render(): {
+        type: "element";
+        tag: string;
+        props: any;
+        children: any;
+        componentMetadata: {
+            originalType: string;
+            overriddenTo: string | undefined;
+            validationResult: any;
+        };
+    }[];
+}
+/**
+ * Base Grid component class with CSS Grid layout
+ */
+declare class BaseGridComponent extends ComponentWithCSSClasses implements ComponentInstance<BaseGridProps> {
+    props: BaseGridProps;
+    protected gridType: 'grid' | 'lazy-vgrid' | 'lazy-hgrid';
+    children: ComponentInstance[];
+    readonly type: "component";
+    readonly id: string;
+    mounted: boolean;
+    cleanup: (() => void)[];
+    protected effectiveTag: string;
+    protected validationResult: any;
+    constructor(props: BaseGridProps, gridType: 'grid' | 'lazy-vgrid' | 'lazy-hgrid', children?: ComponentInstance[]);
+    /**
+     * Generate animation styles for grid layout (Phase 3)
+     */
+    protected generateAnimationStyles(animations?: GridAnimationConfig): Record<string, string>;
+    /**
+     * Apply item animations to child elements (Phase 3)
+     */
+    protected applyItemAnimations(children: ComponentInstance[], animations?: GridAnimationConfig): ComponentInstance[];
+    /**
+     * Generate accessibility attributes for grid (Phase 3)
+     */
+    protected generateAccessibilityAttributes(accessibility?: GridAccessibilityConfig, columnCount?: number, rowCount?: number): Record<string, any>;
+    /**
+     * Generate advanced styling CSS for grid (Phase 3)
+     */
+    protected generateStylingCSS(styling?: GridStylingConfig): Record<string, string>;
+    /**
+     * Handle keyboard navigation events (Phase 3)
+     */
+    protected setupKeyboardNavigation(element: HTMLElement, accessibility?: GridAccessibilityConfig): void;
+    /**
+     * Navigate within grid structure (Phase 3)
+     */
+    private navigateGrid;
+    /**
+     * Navigate in list mode (Phase 3)
+     */
+    private navigateList;
+    /**
+     * Navigate to first/last elements (Phase 3)
+     */
+    private navigateToFirst;
+    private navigateToLast;
+    /**
+     * Navigate by page (Phase 3)
+     */
+    private navigatePage;
+    private setupLifecycleHooks;
+    /**
+     * Find DOM elements for child components (reusing pattern from LayoutComponent)
+     */
+    private findChildDOMElements;
+    render(): any[];
+}
+/**
+ * Grid component class (explicit row/column control)
+ */
+declare class GridComponent extends BaseGridComponent {
+    props: GridProps;
+    constructor(props: GridProps, children?: ComponentInstance[]);
+    render(): {
+        type: "element";
+        tag: string;
+        props: any;
+        children: import("../runtime/types").DOMNode[];
+        componentMetadata: {
+            originalType: string;
+            overriddenTo: string | undefined;
+            validationResult: any;
+        };
+    }[];
+}
+/**
+ * GridRow component class
+ */
+declare class GridRowComponent extends ComponentWithCSSClasses implements ComponentInstance<GridRowProps> {
+    props: GridRowProps;
+    children: ComponentInstance[];
+    readonly type: "component";
+    readonly id: string;
+    mounted: boolean;
+    cleanup: (() => void)[];
+    private effectiveTag;
+    private validationResult;
+    constructor(props: GridRowProps, children?: ComponentInstance[]);
+    render(): {
+        type: "element";
+        tag: string;
+        props: any;
+        children: import("../runtime/types").DOMNode[];
+        componentMetadata: {
+            originalType: string;
+            overriddenTo: string | undefined;
+            validationResult: any;
+        };
+    }[];
+}
+/**
+ * LazyVGrid component class (vertical scrolling with flexible columns)
+ */
+declare class LazyVGridComponent extends BaseGridComponent {
+    props: LazyVGridProps;
+    constructor(props: LazyVGridProps, children?: ComponentInstance[]);
+    render(): {
+        type: "element";
+        tag: string;
+        props: any;
+        children: any[];
+        componentMetadata: any;
+    }[];
+    /**
+     * Render sectioned data with headers and footers (Phase 3)
+     */
+    private renderSections;
+    /**
+     * Get the number of columns in the grid (Phase 3 helper)
+     */
+    private getColumnCount;
+    /**
+     * Generate columns from GridItemConfig array (Phase 2 helper)
+     */
+    private generateColumnsFromConfig;
+}
+/**
+ * LazyHGrid component class (horizontal scrolling with flexible rows)
+ */
+declare class LazyHGridComponent extends BaseGridComponent {
+    props: LazyHGridProps;
+    constructor(props: LazyHGridProps, children?: ComponentInstance[]);
+    render(): {
+        type: "element";
+        tag: string;
+        props: any;
+        children: any[];
+        componentMetadata: any;
+    }[];
+    /**
+     * Render sectioned data with headers and footers (Phase 3)
+     */
+    private renderSections;
+    /**
+     * Get the number of rows in the grid (Phase 3 helper)
+     */
+    private getRowCount;
+    /**
+     * Generate rows from GridItemConfig array (Phase 2 helper)
+     */
+    private generateRowsFromConfig;
+}
+/**
+ * Grid component factory function with modifier support
+ */
+export declare function Grid(props?: GridProps): ModifiableComponent<GridProps> & {
+    modifier: ModifierBuilder<ModifiableComponent<GridProps>>;
+};
+/**
+ * GridRow component factory function with modifier support
+ */
+export declare function GridRow(children?: ComponentInstance[], props?: Omit<GridRowProps, 'children'>): ModifiableComponent<GridRowProps> & {
+    modifier: ModifierBuilder<ModifiableComponent<GridRowProps>>;
+};
+/**
+ * LazyVGrid component factory function with modifier support
+ */
+export declare function LazyVGrid(props: LazyVGridProps): ModifiableComponent<LazyVGridProps> & {
+    modifier: ModifierBuilder<ModifiableComponent<LazyVGridProps>>;
+};
+/**
+ * LazyHGrid component factory function with modifier support
+ */
+export declare function LazyHGrid(props: LazyHGridProps): ModifiableComponent<LazyHGridProps> & {
+    modifier: ModifierBuilder<ModifiableComponent<LazyHGridProps>>;
+};
+/**
+ * Create a grid section with header, footer, and items (Phase 3)
+ */
+export declare function createGridSection(config: {
+    id: string;
+    header?: ComponentInstance | string;
+    footer?: ComponentInstance | string;
+    items: ComponentInstance[];
+    headerStyle?: 'automatic' | 'grouped' | 'plain' | 'sticky';
+    footerStyle?: 'automatic' | 'grouped' | 'plain' | 'sticky';
+}): GridSection;
+/**
+ * Grid section header factory (Phase 3)
+ */
+export declare function GridSectionHeader(props: GridSectionHeaderProps): ModifiableComponent<GridSectionHeaderProps> & {
+    modifier: ModifierBuilder<ModifiableComponent<GridSectionHeaderProps>>;
+};
+/**
+ * Grid animation preset functions (Phase 3)
+ */
+export declare const GridAnimations: {
+    /**
+     * Basic fade-in animation for new items
+     */
+    fadeIn(duration?: number, delay?: number): GridAnimationConfig;
+    /**
+     * Scale animation for new items
+     */
+    scaleIn(duration?: number, delay?: number): GridAnimationConfig;
+    /**
+     * Slide animation for new items
+     */
+    slideIn(direction?: "up" | "down" | "left" | "right", duration?: number): GridAnimationConfig;
+    /**
+     * Smooth layout changes when grid structure changes
+     */
+    smoothLayout(duration?: number): GridAnimationConfig;
+    /**
+     * Responsive breakpoint animations
+     */
+    smoothResponsive(duration?: number): GridAnimationConfig;
+    /**
+     * Comprehensive animation configuration
+     */
+    comprehensive(itemDuration?: number, layoutDuration?: number): GridAnimationConfig;
+    /**
+     * Staggered entrance animation for multiple items
+     */
+    staggered(itemDuration?: number): GridAnimationConfig;
+};
+/**
+ * Grid accessibility preset functions (Phase 3)
+ */
+export declare const GridAccessibility: {
+    /**
+     * Full accessibility support with keyboard navigation and screen reader optimizations
+     */
+    full(label: string, description?: string): GridAccessibilityConfig;
+    /**
+     * Basic accessibility support for simple grids
+     */
+    basic(label: string): GridAccessibilityConfig;
+    /**
+     * Screen reader focused accessibility
+     */
+    screenReader(label: string, description?: string): GridAccessibilityConfig;
+    /**
+     * Keyboard navigation focused accessibility
+     */
+    keyboardOnly(label: string): GridAccessibilityConfig;
+};
+/**
+ * Grid styling preset functions (Phase 3)
+ */
+export declare const GridStyling: {
+    /**
+     * Debug grid with visible lines and areas
+     */
+    debug(options?: {
+        lineColor?: string;
+        showAreas?: boolean;
+    }): GridStylingConfig;
+    /**
+     * Interactive grid with hover and focus effects
+     */
+    interactive(hoverTransform?: "scale" | "lift" | "glow" | "highlight"): GridStylingConfig;
+    /**
+     * Card-style grid with background and borders
+     */
+    card(options?: {
+        shadow?: string;
+        borderRadius?: number;
+        padding?: number;
+    }): GridStylingConfig;
+    /**
+     * Custom template areas grid
+     */
+    templateAreas(areas: string[]): GridStylingConfig;
+    /**
+     * Grid with background pattern
+     */
+    backgroundPattern(pattern: "dots" | "lines" | "grid", color?: string, opacity?: number): GridStylingConfig;
+    /**
+     * Comprehensive styling with multiple features
+     */
+    comprehensive(options?: {
+        debug?: boolean;
+        interactive?: boolean;
+        card?: boolean;
+        pattern?: "dots" | "lines" | "grid";
+    }): GridStylingConfig;
+};
+export { BaseGridComponent, GridComponent as EnhancedGrid, GridRowComponent as EnhancedGridRow, LazyVGridComponent as EnhancedLazyVGrid, LazyHGridComponent as EnhancedLazyHGrid, GridCSSGenerator, GridSectionHeaderComponent, GridDebugger, GridPerformanceMonitor };
+//# sourceMappingURL=Grid.d.ts.map