ezfw-core 1.0.0

package/core/EzComponentTypes.ts

@@ -0,0 +1,693 @@
+/**
+ * Component-specific type definitions for IDE autocomplete
+ * These interfaces enable discriminated unions for eztype-specific props
+ */
+
+import type { ItemConfig, BindConfig } from './EzTypes.js';
+
+// =============================================================================
+// Base Config (shared by all components)
+// =============================================================================
+
+interface BaseComponentConfig {
+    /** CSS class(es) */
+    cls?: string | string[];
+    /** Inline styles */
+    style?: Record<string, string | number>;
+    /** Flex grow value */
+    flex?: number;
+    /** Reference name for ez._refs */
+    ref?: string;
+    /** Data bindings */
+    bind?: BindConfig;
+}
+
+// =============================================================================
+// EzButton
+// =============================================================================
+
+/**
+ * Button component with variants, sizes, and loading state
+ * @example
+ * { eztype: 'EzButton', text: 'Submit', variant: 'primary', onClick: 'handleSubmit' }
+ */
+export interface EzButtonItemConfig extends BaseComponentConfig {
+    eztype: 'EzButton';
+    /** Button text */
+    text?: string;
+    /** Icon class (FontAwesome) - e.g., 'download', 'fa-solid fa-check' */
+    icon?: string;
+    /** Icon position relative to text */
+    iconPosition?: 'left' | 'right';
+    /** Button style variant */
+    variant?: 'primary' | 'danger' | 'success' | 'warning' | 'ghost' | 'text' | 'outline' | 'outline-primary' | 'outline-danger' | 'outline-success' | 'outline-warning';
+    /** Button size */
+    size?: 'sm' | 'lg';
+    /** Full width button */
+    block?: boolean;
+    /** Show loading spinner */
+    loading?: boolean;
+    /** Disable button */
+    disabled?: boolean;
+    /** HTML button type */
+    htmlType?: 'button' | 'submit' | 'reset';
+    /** Tooltip text */
+    tooltip?: string;
+    /** Click handler - method name or function */
+    onClick?: string | ((e: MouseEvent) => void);
+}
+
+// =============================================================================
+// EzInput
+// =============================================================================
+
+/**
+ * Text input with icons and variants
+ * @example
+ * { eztype: 'EzInput', name: 'email', placeholder: 'Enter email', formData: 'form' }
+ */
+export interface EzInputItemConfig extends BaseComponentConfig {
+    eztype: 'EzInput';
+    /** Field name for form binding */
+    name?: string;
+    /** Form data path in controller state */
+    formData?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Initial value */
+    value?: string | number;
+    /** Input type */
+    inputType?: 'text' | 'password' | 'email' | 'number' | 'tel' | 'url';
+    /** Input size */
+    size?: 'sm' | 'lg';
+    /** Input variant */
+    variant?: 'filled' | 'underline';
+    /** Icon class (left side) */
+    icon?: string;
+    /** Full width */
+    block?: boolean;
+    /** Disable input */
+    disabled?: boolean;
+    /** Read-only input */
+    readonly?: boolean;
+}
+
+// =============================================================================
+// EzTextarea
+// =============================================================================
+
+/**
+ * Multi-line text input with auto-resize
+ * @example
+ * { eztype: 'EzTextarea', name: 'description', rows: 4, formData: 'form' }
+ */
+export interface EzTextareaItemConfig extends BaseComponentConfig {
+    eztype: 'EzTextarea';
+    /** Field name for form binding */
+    name?: string;
+    /** Form data path in controller state */
+    formData?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Initial value */
+    value?: string;
+    /** Number of visible rows */
+    rows?: number;
+    /** Minimum rows for auto-resize */
+    minRows?: number;
+    /** Maximum rows for auto-resize */
+    maxRows?: number;
+    /** Disable textarea */
+    disabled?: boolean;
+    /** Read-only textarea */
+    readonly?: boolean;
+}
+
+// =============================================================================
+// EzSelect
+// =============================================================================
+
+/**
+ * Dropdown select component
+ * @example
+ * { eztype: 'EzSelect', options: [{value: 1, label: 'One'}], placeholder: 'Select...' }
+ */
+export interface EzSelectItemConfig extends BaseComponentConfig {
+    eztype: 'EzSelect';
+    /** Select options - array of {value, label} or primitives */
+    options?: ({ value: string | number; label: string } | string | number)[];
+    /** Selected value */
+    value?: string | number | null;
+    /** Placeholder when no selection */
+    placeholder?: string;
+    /** Selection change handler */
+    onSelect?: string | ((value: string | number) => void);
+}
+
+// =============================================================================
+// EzCheckbox
+// =============================================================================
+
+/**
+ * Checkbox input with label
+ * @example
+ * { eztype: 'EzCheckbox', name: 'agree', label: 'I agree', formData: 'form' }
+ */
+export interface EzCheckboxItemConfig extends BaseComponentConfig {
+    eztype: 'EzCheckbox';
+    /** Field name for form binding */
+    name?: string;
+    /** Form data path */
+    formData?: string;
+    /** Checkbox label text */
+    label?: string;
+    /** Checked state */
+    value?: boolean;
+    /** Checkbox size */
+    size?: 'sm' | 'lg';
+    /** Disable checkbox */
+    disabled?: boolean;
+}
+
+// =============================================================================
+// EzSwitch
+// =============================================================================
+
+/**
+ * Toggle switch component
+ * @example
+ * { eztype: 'EzSwitch', name: 'enabled', label: 'Enable feature', formData: 'settings' }
+ */
+export interface EzSwitchItemConfig extends BaseComponentConfig {
+    eztype: 'EzSwitch';
+    /** Field name for form binding */
+    name?: string;
+    /** Form data path */
+    formData?: string;
+    /** Switch label */
+    label?: string;
+    /** On/off state */
+    value?: boolean;
+    /** Switch size */
+    size?: 'sm' | 'lg';
+    /** Disable switch */
+    disabled?: boolean;
+}
+
+// =============================================================================
+// EzRadio
+// =============================================================================
+
+/**
+ * Radio button group
+ * @example
+ * { eztype: 'EzRadio', name: 'size', options: ['S', 'M', 'L'], formData: 'form' }
+ */
+export interface EzRadioItemConfig extends BaseComponentConfig {
+    eztype: 'EzRadio';
+    /** Field name for form binding */
+    name?: string;
+    /** Form data path */
+    formData?: string;
+    /** Radio options */
+    options?: ({ value: string | number; label: string } | string | number)[];
+    /** Selected value */
+    value?: string | number;
+    /** Radio size */
+    size?: 'sm' | 'lg';
+    /** Disable all options */
+    disabled?: boolean;
+    /** Layout direction */
+    direction?: 'horizontal' | 'vertical';
+}
+
+// =============================================================================
+// EzCard
+// =============================================================================
+
+/**
+ * Card container with header and actions
+ * @example
+ * { eztype: 'EzCard', title: 'My Card', items: [...] }
+ */
+export interface EzCardItemConfig extends BaseComponentConfig {
+    eztype: 'EzCard';
+    /** Card title */
+    title?: string;
+    /** Card subtitle */
+    subtitle?: string;
+    /** Action buttons in header */
+    headerActions?: ItemConfig[];
+    /** Card variant */
+    variant?: 'default' | 'bordered' | 'elevated';
+    /** Remove body padding */
+    noPadding?: boolean;
+    /** Card content */
+    items?: ItemConfig[];
+}
+
+// =============================================================================
+// EzBadge
+// =============================================================================
+
+/**
+ * Badge for status, labels, and notifications
+ * @example
+ * { eztype: 'EzBadge', text: 'New', variant: 'success', pill: true }
+ */
+export interface EzBadgeItemConfig extends BaseComponentConfig {
+    eztype: 'EzBadge';
+    /** Badge text */
+    text?: string | number;
+    /** Badge variant */
+    variant?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info';
+    /** Badge size */
+    size?: 'sm' | 'lg';
+    /** Pill shape (rounded) */
+    pill?: boolean;
+    /** Outline style */
+    outline?: boolean;
+    /** Dot indicator (no text) */
+    dot?: boolean;
+    /** Icon class */
+    icon?: string;
+    /** Show close button */
+    closable?: boolean;
+    /** Close button handler */
+    onClose?: (e: MouseEvent) => void;
+    /** Click handler */
+    onClick?: (e: MouseEvent) => void;
+}
+
+// =============================================================================
+// EzLabel
+// =============================================================================
+
+/**
+ * Text label with binding support
+ * @example
+ * { eztype: 'EzLabel', text: 'Hello', bind: { text: 'userName' } }
+ */
+export interface EzLabelItemConfig extends BaseComponentConfig {
+    eztype: 'EzLabel';
+    /** Label text */
+    text?: string;
+}
+
+// =============================================================================
+// EzForm
+// =============================================================================
+
+/**
+ * Form container with validation
+ * @example
+ * { eztype: 'EzForm', formData: 'userData', onSubmit: 'handleSubmit', items: [...] }
+ */
+export interface EzFormItemConfig extends BaseComponentConfig {
+    eztype: 'EzForm';
+    /** State path for form data */
+    formData?: string;
+    /** Gap between form items */
+    gap?: string;
+    /** Row layout - items per row e.g., [2, 3] */
+    layout?: number[];
+    /** Default props for form items */
+    defaults?: { eztype?: string; [key: string]: unknown };
+    /** Submit handler - method name or function */
+    onSubmit?: string | ((dirtyData: object, formData: object, form: unknown) => void);
+    /** Form items */
+    items?: ItemConfig[];
+}
+
+// =============================================================================
+// EzGrid
+// =============================================================================
+
+interface GridColumnConfig {
+    /** Field index in row data */
+    index?: string;
+    /** Column type */
+    type?: 'selection' | 'actions' | string;
+    /** Column header text */
+    text?: string;
+    /** Flex grow */
+    flex?: number;
+    /** Fixed width in pixels */
+    width?: number;
+    /** Custom cell render function */
+    render?: (value: unknown, row: Record<string, unknown>, cell: HTMLElement) => unknown;
+    /** Enable sorting */
+    sort?: boolean;
+    /** Enable filtering */
+    filter?: boolean | string | object;
+    /** Action buttons for actions column */
+    actions?: { icon?: string; tooltip?: string; danger?: boolean; onClick?: (row: Record<string, unknown>) => void }[];
+    /** Text wrapping */
+    wrap?: boolean | number;
+    /** Enable column resize */
+    resizable?: boolean;
+    /** Enable column reorder */
+    reorderable?: boolean;
+}
+
+/**
+ * Data grid with sorting, filtering, and pagination
+ * @example
+ * { eztype: 'EzGrid', columns: [...], data: users, rowKey: 'id' }
+ */
+export interface EzGridItemConfig extends BaseComponentConfig {
+    eztype: 'EzGrid';
+    /** Grid columns configuration */
+    columns?: GridColumnConfig[];
+    /** Local data array */
+    data?: Record<string, unknown>[];
+    /** Row identifier field */
+    rowKey?: string | ((row: Record<string, unknown>) => string | number);
+    /** Data model name */
+    model?: string;
+    /** Grid controller name */
+    gridController?: string;
+    /** Selection mode */
+    selectionMode?: 'single' | 'multi';
+    /** Data mode */
+    dataMode?: 'local' | 'remote';
+    /** Remote data configuration */
+    remote?: {
+        api?: string;
+        source?: { dataPath?: string; countPath?: string };
+        autoLoad?: boolean;
+    };
+    /** Page size */
+    pageSize?: number;
+    /** Show pagination */
+    showPagination?: boolean;
+    /** Show title bar */
+    showTitle?: boolean;
+    /** Show filters */
+    showFilters?: boolean;
+    /** Persist state to localStorage */
+    stateful?: boolean;
+    statefulPersist?: boolean;
+    /** Row click handler */
+    onRowClick?: string | ((row: Record<string, unknown>, ctx: object) => void);
+    /** Selection change handler */
+    onSelectionChange?: string | ((rows: Record<string, unknown>[]) => void);
+}
+
+// =============================================================================
+// EzTabPanel
+// =============================================================================
+
+interface TabConfig {
+    /** Tab identifier */
+    id?: string | number;
+    /** Tab title */
+    title?: string;
+    /** Tab icon */
+    icon?: string;
+    /** Allow closing tab */
+    closable?: boolean;
+    /** Tab content */
+    items?: ItemConfig[];
+}
+
+/**
+ * Tabbed content panel with variants
+ * @example
+ * { eztype: 'EzTabPanel', tabs: [{ id: 'tab1', title: 'Tab 1', items: [...] }] }
+ */
+export interface EzTabPanelItemConfig extends BaseComponentConfig {
+    eztype: 'EzTabPanel';
+    /** Tab panel id for state persistence */
+    id?: string;
+    /** Tab configurations */
+    tabs?: TabConfig[];
+    /** Initially active tab */
+    activeTab?: string | number;
+    /** Tab style variant */
+    variant?: string;
+    /** Persist state */
+    stateful?: boolean;
+    statefulPersist?: boolean;
+    /** Tab change handler */
+    onTabChange?: (tabId: string | number) => void;
+    /** Tab add handler */
+    onTabAdd?: (tabId: string | number, config: TabConfig) => void;
+    /** Tab close handler */
+    onTabClose?: (tabId: string | number) => void;
+}
+
+// =============================================================================
+// EzDialog
+// =============================================================================
+
+/**
+ * Modal dialog with sizes and async loading
+ * @example
+ * ez.dialog.show({ title: 'Confirm', message: 'Are you sure?' })
+ */
+export interface EzDialogItemConfig extends BaseComponentConfig {
+    eztype: 'EzDialog';
+    /** Dialog title */
+    title?: string;
+    /** Dialog size */
+    size?: 'sm' | 'md' | 'lg' | 'xl' | 'fullscreen';
+    /** Show close button */
+    closable?: boolean;
+    /** Dialog content */
+    items?: ItemConfig[];
+    /** Footer buttons */
+    buttons?: ItemConfig[];
+}
+
+// =============================================================================
+// EzDropdown
+// =============================================================================
+
+interface DropdownItem {
+    /** Item text */
+    text?: string;
+    /** Item icon */
+    icon?: string;
+    /** Keyboard shortcut display */
+    shortcut?: string;
+    /** Divider line */
+    divider?: boolean;
+    /** Disable item */
+    disabled?: boolean;
+    /** Danger style */
+    danger?: boolean;
+    /** Click handler */
+    onClick?: () => void;
+}
+
+/**
+ * Dropdown menu with icons and shortcuts
+ * @example
+ * { eztype: 'EzDropdown', trigger: { eztype: 'EzButton', text: 'Menu' }, items: [...] }
+ */
+export interface EzDropdownItemConfig extends BaseComponentConfig {
+    eztype: 'EzDropdown';
+    /** Trigger element */
+    trigger?: ItemConfig;
+    /** Dropdown items */
+    items?: DropdownItem[];
+    /** Dropdown position */
+    position?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+}
+
+// =============================================================================
+// EzComponent
+// =============================================================================
+
+/**
+ * Base layout component with flex support
+ * @example
+ * { eztype: 'EzComponent', layout: 'hbox', items: [...] }
+ */
+export interface EzComponentItemConfig extends BaseComponentConfig {
+    eztype: 'EzComponent';
+    /** Layout direction */
+    layout?: 'hbox' | 'vbox';
+    /** Child items */
+    items?: ItemConfig[];
+}
+
+// =============================================================================
+// EzPanel
+// =============================================================================
+
+/**
+ * Panel with header, title, tools and content
+ * @example
+ * { eztype: 'EzPanel', title: 'Settings', collapsible: true, items: [...] }
+ */
+export interface EzPanelItemConfig extends BaseComponentConfig {
+    eztype: 'EzPanel';
+    /** Panel title */
+    title?: string;
+    /** Title icon */
+    icon?: string;
+    /** Header tool buttons */
+    tools?: ItemConfig[];
+    /** Allow collapsing */
+    collapsible?: boolean;
+    /** Initial collapsed state */
+    collapsed?: boolean;
+    /** Panel content */
+    items?: ItemConfig[];
+}
+
+// =============================================================================
+// EzSkeleton
+// =============================================================================
+
+/**
+ * Loading placeholder for content
+ * @example
+ * { eztype: 'EzSkeleton', variant: 'card', count: 3 }
+ */
+export interface EzSkeletonItemConfig extends BaseComponentConfig {
+    eztype: 'EzSkeleton';
+    /** Skeleton variant */
+    variant?: 'text' | 'circle' | 'rect' | 'card';
+    /** Width */
+    width?: string | number;
+    /** Height */
+    height?: string | number;
+    /** Number of skeleton items */
+    count?: number;
+}
+
+// =============================================================================
+// EzAvatar
+// =============================================================================
+
+/**
+ * User avatar component
+ * @example
+ * { eztype: 'EzAvatar', name: 'John Doe', src: '/avatar.jpg', size: 'lg' }
+ */
+export interface EzAvatarItemConfig extends BaseComponentConfig {
+    eztype: 'EzAvatar';
+    /** User name (for initials fallback) */
+    name?: string;
+    /** Image source URL */
+    src?: string;
+    /** Avatar size */
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    /** Shape */
+    shape?: 'circle' | 'square';
+    /** Status indicator */
+    status?: 'online' | 'offline' | 'busy' | 'away';
+}
+
+// =============================================================================
+// Chart Components
+// =============================================================================
+
+/**
+ * Line chart with simplified API
+ * @example
+ * { eztype: 'EzLineChart', labels: ['Mon','Tue'], datasets: [{data: [1,2]}] }
+ */
+export interface EzLineChartItemConfig extends BaseComponentConfig {
+    eztype: 'EzLineChart';
+    /** Chart height */
+    height?: number;
+    /** X-axis labels */
+    labels?: string[];
+    /** Chart datasets */
+    datasets?: { label?: string; data: number[]; borderColor?: string; backgroundColor?: string }[];
+}
+
+/**
+ * Bar chart with simplified API
+ * @example
+ * { eztype: 'EzBarChart', labels: ['A','B'], datasets: [{data: [10,20]}] }
+ */
+export interface EzBarChartItemConfig extends BaseComponentConfig {
+    eztype: 'EzBarChart';
+    /** Chart height */
+    height?: number;
+    /** X-axis labels */
+    labels?: string[];
+    /** Chart datasets */
+    datasets?: { label?: string; data: number[]; backgroundColor?: string }[];
+}
+
+/**
+ * Doughnut chart with simplified API
+ * @example
+ * { eztype: 'EzDoughnutChart', labels: ['A','B'], values: [30, 70] }
+ */
+export interface EzDoughnutChartItemConfig extends BaseComponentConfig {
+    eztype: 'EzDoughnutChart';
+    /** Chart height */
+    height?: number;
+    /** Segment labels */
+    labels?: string[];
+    /** Segment values */
+    values?: number[];
+}
+
+// =============================================================================
+// EzActivityFeed
+// =============================================================================
+
+interface ActivityItem {
+    /** Icon class */
+    icon?: string;
+    /** Icon variant */
+    variant?: 'primary' | 'success' | 'warning' | 'danger' | 'info';
+    /** Activity description */
+    description?: string;
+    /** Timestamp display */
+    timestamp?: string;
+}
+
+/**
+ * Activity feed with icons and timestamps
+ * @example
+ * { eztype: 'EzActivityFeed', items: [{ icon: 'fa-user', description: 'User joined' }] }
+ */
+export interface EzActivityFeedItemConfig extends BaseComponentConfig {
+    eztype: 'EzActivityFeed';
+    /** Maximum height with scroll */
+    maxHeight?: number | string;
+    /** Activity items */
+    items?: ActivityItem[];
+}
+
+// =============================================================================
+// Union Type for All Components
+// =============================================================================
+
+/**
+ * Union of all Ez component configurations
+ * Provides autocomplete for component-specific props based on eztype
+ */
+export type EzItemConfig =
+    | EzButtonItemConfig
+    | EzInputItemConfig
+    | EzTextareaItemConfig
+    | EzSelectItemConfig
+    | EzCheckboxItemConfig
+    | EzSwitchItemConfig
+    | EzRadioItemConfig
+    | EzCardItemConfig
+    | EzBadgeItemConfig
+    | EzLabelItemConfig
+    | EzFormItemConfig
+    | EzGridItemConfig
+    | EzTabPanelItemConfig
+    | EzDialogItemConfig
+    | EzDropdownItemConfig
+    | EzComponentItemConfig
+    | EzPanelItemConfig
+    | EzSkeletonItemConfig
+    | EzAvatarItemConfig
+    | EzLineChartItemConfig
+    | EzBarChartItemConfig
+    | EzDoughnutChartItemConfig
+    | EzActivityFeedItemConfig;