ezfw-core 1.0.0

package/core/EzError.ts

@@ -0,0 +1,63 @@
+export interface EzErrorConfig {
+    code: string;
+    message: string;
+    source?: string;
+    route?: string | null;
+    view?: string | null;
+    details?: unknown;
+    cause?: Error | null;
+}
+
+export class EzError extends Error {
+    name: string = 'EzError';
+    code: string;
+    source: string;
+    route: string | null;
+    view: string | null;
+    details: unknown;
+    cause: Error | null;
+
+    constructor({
+        code,
+        message,
+        source = 'framework',
+        route = null,
+        view = null,
+        details = null,
+        cause = null
+    }: EzErrorConfig) {
+        super(message);
+
+        this.code = code;
+        this.source = source;
+        this.route = route;
+        this.view = view;
+        this.details = details;
+        this.cause = cause;
+
+        this.handleFrameworkError(this);
+    }
+
+    handleFrameworkError(error: EzError): void {
+        console.group(`🧱 EZ Framework Error — ${error.code}`);
+        console.error(error.message);
+
+        console.info('Source:', error.source);
+        if (error.route) console.info('Route:', error.route);
+        if (error.view) console.info('View:', error.view);
+
+        if (error.details) {
+            console.group('Details');
+            console.dir(error.details);
+            console.groupEnd();
+        }
+
+        if (error.cause) {
+            console.group('Cause');
+            console.error(error.cause);
+            console.groupEnd();
+        }
+
+        console.groupEnd();
+    }
+}

package/core/EzModel.ts

@@ -0,0 +1,268 @@
+import { EzError } from './EzError.js';
+
+type TypeCoercer = (value: unknown) => unknown;
+
+export interface FieldDefinition {
+    name: string;
+    type?: string;
+    default?: unknown | (() => unknown);
+    primaryKey?: boolean;
+    compute?: (record: Record<string, unknown>) => unknown;
+    nullable?: boolean;
+}
+
+export interface ModelDefinition {
+    fields: FieldDefinition[];
+}
+
+export interface NormalizedField {
+    name: string;
+    type: string;
+    default: unknown | (() => unknown) | undefined;
+    primaryKey: boolean;
+    compute: ((record: Record<string, unknown>) => unknown) | null;
+    nullable: boolean;
+}
+
+export interface ValidationError {
+    field: string;
+    error: string;
+    message: string;
+    received?: string;
+}
+
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+
+export interface Model {
+    name: string;
+    fields: NormalizedField[];
+    fieldMap: Record<string, NormalizedField>;
+    primaryKey: string | null;
+    coerce: (record: Record<string, unknown>) => Record<string, unknown>;
+    validate: (record: Record<string, unknown>) => ValidationResult;
+    applyDefaults: (record: Record<string, unknown>) => Record<string, unknown>;
+    applyComputed: (record: Record<string, unknown>) => Record<string, unknown>;
+    process: (record: Record<string, unknown>) => Record<string, unknown>;
+    processAll: (records: Record<string, unknown>[]) => Record<string, unknown>[];
+}
+
+interface EzInstance {
+    _models: Record<string, Model>;
+}
+
+export class EzModel {
+    private ez: EzInstance;
+
+    static TYPES: Record<string, TypeCoercer> = {
+        int: (v) => v == null ? null : parseInt(String(v), 10),
+        float: (v) => v == null ? null : parseFloat(String(v)),
+        string: (v) => v == null ? null : String(v),
+        bool: (v) => {
+            if (v == null) return null;
+            if (typeof v === 'string') {
+                return v.toLowerCase() === 'true' || v === '1';
+            }
+            return Boolean(v);
+        },
+        date: (v) => {
+            if (v == null) return null;
+            if (v instanceof Date) return v;
+            const d = new Date(v as string | number);
+            return isNaN(d.getTime()) ? null : d;
+        },
+        array: (v) => {
+            if (v == null) return [];
+            return Array.isArray(v) ? v : [v];
+        },
+        object: (v) => v == null ? {} : (typeof v === 'object' ? v : {}),
+        any: (v) => v
+    };
+
+    constructor(ez: EzInstance) {
+        this.ez = ez;
+    }
+
+    defineModel(name: string, definition: ModelDefinition): void {
+        if (this.ez._models[name]) {
+            throw new EzError({
+                code: 'EZ_MODEL_DUPLICATE',
+                source: 'model',
+                message: `Model "${name}" is already defined`
+            });
+        }
+
+        const fields = (definition.fields || []).map(f => this._normalizeField(f));
+
+        const model: Model = {
+            name,
+            fields,
+            fieldMap: Object.fromEntries(fields.map(f => [f.name, f])),
+            primaryKey: fields.find(f => f.primaryKey)?.name || null,
+
+            coerce: (record) => this._coerceRecord(fields, record),
+            validate: (record) => this._validateRecord(fields, record),
+            applyDefaults: (record) => this._applyDefaults(fields, record),
+            applyComputed: (record) => this._applyComputed(fields, record),
+            process: (record) => this._processRecord(fields, record),
+            processAll: (records) => this._processAll(fields, records)
+        };
+
+        this.ez._models[name] = model;
+    }
+
+    private _normalizeField(field: FieldDefinition): NormalizedField {
+        return {
+            name: field.name,
+            type: field.type || 'any',
+            default: field.default,
+            primaryKey: field.primaryKey || false,
+            compute: field.compute || null,
+            nullable: field.nullable !== false
+        };
+    }
+
+    getModel(name: string): Model | null {
+        return this.ez._models[name] || null;
+    }
+
+    getModelSync(name: string): Model {
+        const model = this.ez._models[name];
+        if (!model) {
+            throw new EzError({
+                code: 'EZ_MODEL_001',
+                source: 'model',
+                message: `Model "${name}" not found`,
+                details: {
+                    available: Object.keys(this.ez._models)
+                }
+            });
+        }
+        return model;
+    }
+
+    private _processRecord(fields: NormalizedField[], record: Record<string, unknown>): Record<string, unknown> {
+        if (!record || typeof record !== 'object') {
+            return record;
+        }
+
+        let result = { ...record };
+        result = this._applyDefaults(fields, result);
+        result = this._coerceRecord(fields, result);
+        result = this._applyComputed(fields, result);
+        return result;
+    }
+
+    private _processAll(fields: NormalizedField[], records: Record<string, unknown>[]): Record<string, unknown>[] {
+        if (!Array.isArray(records)) {
+            return [];
+        }
+        return records.map(r => this._processRecord(fields, r));
+    }
+
+    private _applyDefaults(fields: NormalizedField[], record: Record<string, unknown>): Record<string, unknown> {
+        const result = { ...record };
+
+        for (const field of fields) {
+            if (result[field.name] === undefined && field.default !== undefined) {
+                result[field.name] = typeof field.default === 'function'
+                    ? field.default()
+                    : field.default;
+            }
+        }
+
+        return result;
+    }
+
+    private _coerceRecord(fields: NormalizedField[], record: Record<string, unknown>): Record<string, unknown> {
+        const result = { ...record };
+
+        for (const field of fields) {
+            if (field.compute) continue;
+
+            if (result[field.name] !== undefined) {
+                const coercer = EzModel.TYPES[field.type] || EzModel.TYPES.any;
+                result[field.name] = coercer(result[field.name]);
+            }
+        }
+
+        return result;
+    }
+
+    private _applyComputed(fields: NormalizedField[], record: Record<string, unknown>): Record<string, unknown> {
+        const result = { ...record };
+
+        for (const field of fields) {
+            if (field.compute && typeof field.compute === 'function') {
+                try {
+                    result[field.name] = field.compute(result);
+                } catch (err) {
+                    console.warn(`[EzModel] Error computing field "${field.name}":`, err);
+                    result[field.name] = null;
+                }
+            }
+        }
+
+        return result;
+    }
+
+    private _validateRecord(fields: NormalizedField[], record: Record<string, unknown>): ValidationResult {
+        const errors: ValidationError[] = [];
+
+        for (const field of fields) {
+            const value = record[field.name];
+
+            if (field.compute) continue;
+
+            if (value == null && !field.nullable) {
+                errors.push({
+                    field: field.name,
+                    error: 'required',
+                    message: `Field "${field.name}" is required`
+                });
+                continue;
+            }
+
+            if (value != null) {
+                const isValid = this._validateType(field.type, value);
+                if (!isValid) {
+                    errors.push({
+                        field: field.name,
+                        error: 'type',
+                        message: `Field "${field.name}" must be of type ${field.type}`,
+                        received: typeof value
+                    });
+                }
+            }
+        }
+
+        return {
+            valid: errors.length === 0,
+            errors
+        };
+    }
+
+    private _validateType(type: string, value: unknown): boolean {
+        switch (type) {
+            case 'int':
+                return Number.isInteger(value) || (typeof value === 'string' && /^-?\d+$/.test(value));
+            case 'float':
+                return typeof value === 'number' || (typeof value === 'string' && !isNaN(parseFloat(value)));
+            case 'string':
+                return typeof value === 'string';
+            case 'bool':
+                return typeof value === 'boolean' || value === 'true' || value === 'false' || value === 0 || value === 1;
+            case 'date':
+                return value instanceof Date || (typeof value === 'string' && !isNaN(Date.parse(value)));
+            case 'array':
+                return Array.isArray(value);
+            case 'object':
+                return typeof value === 'object' && !Array.isArray(value);
+            case 'any':
+            default:
+                return true;
+        }
+    }
+}

package/core/EzTypes.ts

@@ -0,0 +1,328 @@
+import type { EzItemConfig } from './EzComponentTypes.js';
+
+/**
+ * Configuration for component items (children)
+ * For component-specific autocomplete, use EzItemConfig instead
+ */
+export interface ItemConfig {
+    /**
+     * Component type to render
+     * @example eztype: 'EzButton'
+     * @example eztype: 'div' // native HTML element
+     */
+    eztype?: string;
+
+    /**
+     * CSS class(es) to apply to the element
+     * @example cls: 'header'
+     * @example cls: ['card', 'primary', 'shadow']
+     */
+    cls?: string | string[];
+
+    /**
+     * CSS module name - framework auto-loads {css}.module.scss
+     * @example css: 'UserCard' // loads UserCard.module.scss
+     */
+    css?: string;
+
+    /**
+     * Text content for the element
+     * @example text: 'Hello World'
+     * @example text: user.name
+     */
+    text?: string;
+
+    /**
+     * Raw HTML content (use with caution - XSS risk)
+     * @example html: '<strong>Bold</strong>'
+     */
+    html?: string;
+
+    /**
+     * Child items to render inside this element
+     * @example items: [{ eztype: 'span', text: 'Child 1' }]
+     */
+    items?: ItemConfig[];
+
+    /**
+     * Flex grow value for flexbox layouts
+     * @example flex: 1 // takes remaining space
+     * @example flex: 2 // takes 2x space relative to flex: 1
+     */
+    flex?: number;
+
+    /**
+     * Inline CSS styles
+     * @example style: { padding: '16px', gap: '8px' }
+     */
+    style?: Record<string, string | number>;
+
+    /**
+     * Props passed to template-based components
+     * @example props: { user: userData, showAvatar: true }
+     */
+    props?: Record<string, unknown>;
+
+    /**
+     * Data bindings for reactive updates
+     * @example bind: { text: 'userName', visible: 'isLoggedIn' }
+     */
+    bind?: BindConfig;
+
+    /**
+     * Reference name for accessing via ez._refs
+     * @example ref: 'submitBtn' // access as ez._refs.submitBtn
+     */
+    ref?: string;
+
+    /**
+     * Click event handler - method name (string) or function
+     * @example onClick: 'handleClick' // calls controller.handleClick()
+     * @example onClick: (e) => console.log('clicked')
+     */
+    onClick?: string | ((e: Event) => void);
+
+    /**
+     * Change event handler (for inputs)
+     * @example onChange: 'onSelectChange'
+     */
+    onChange?: string | ((e: Event) => void);
+
+    /**
+     * Input event handler (fires on every keystroke)
+     * @example onInput: 'onSearchInput'
+     */
+    onInput?: string | ((e: Event) => void);
+
+    /** Any additional properties */
+    [key: string]: unknown;
+}
+
+/**
+ * Data binding configuration for reactive updates
+ */
+export interface BindConfig {
+    /**
+     * Bind to array data for list rendering with itemRender
+     * @example
+     * bind: { data: 'users' },
+     * itemRender: (user) => ({ eztype: 'UserCard', props: { user } })
+     */
+    data?: string;
+
+    /**
+     * Bind text content to a state property
+     * @example bind: { text: 'userName' } // displays state.userName
+     */
+    text?: string;
+
+    /**
+     * Conditionally show/hide element based on state
+     * @example bind: { visible: 'isLoading' }
+     * @example bind: { visible: () => ctrl.state.items.length > 0 }
+     */
+    visible?: string | (() => boolean);
+
+    /**
+     * Dynamically set CSS classes based on state
+     * @example bind: { cls: 'activeClass' } // uses state.activeClass
+     * @example bind: { cls: () => ctrl.state.isActive ? 'active' : 'inactive' }
+     */
+    cls?: string | (() => string | string[]);
+
+    /**
+     * Bind input value to state (two-way binding)
+     * @example bind: { value: 'formData.email' }
+     */
+    value?: string;
+
+    /**
+     * Bind disabled state
+     * @example bind: { disabled: 'isSubmitting' }
+     */
+    disabled?: string | (() => boolean);
+
+    /** Any additional attribute bindings */
+    [key: string]: unknown;
+}
+
+/**
+ * Component definition for ez.define()
+ */
+export interface ComponentDefinition {
+    /**
+     * Base component type to extend
+     * @example eztype: 'EzComponent'
+     * @example eztype: 'EzForm'
+     */
+    eztype?: string;
+
+    /**
+     * CSS module name for automatic style loading
+     * The framework will load `{css}.module.scss` automatically
+     * @example css: 'StatCard' // loads StatCard.module.scss
+     */
+    css?: string;
+
+    /**
+     * Controller name for state management
+     * @example controller: 'UserDetail'
+     */
+    controller?: string;
+
+    /**
+     * CSS class(es) to apply to the root element
+     * @example cls: 'myComponent'
+     * @example cls: ['card', 'primary']
+     */
+    cls?: string | string[];
+
+    /**
+     * Layout direction for child items
+     * @example layout: 'hbox' // horizontal
+     * @example layout: 'vbox' // vertical
+     */
+    layout?: 'hbox' | 'vbox';
+
+    /**
+     * Inline styles for the root element
+     */
+    style?: Record<string, string | number>;
+
+    /**
+     * Static child items
+     * @example items: [{ eztype: 'EzButton', text: 'Click' }]
+     */
+    items?: ItemConfig[];
+
+    /**
+     * Template function for dynamic rendering
+     * Receives props and returns component configuration
+     * @example
+     * template({ name, age }) {
+     *     return {
+     *         eztype: 'div',
+     *         items: [
+     *             { eztype: 'span', text: name },
+     *             { eztype: 'span', text: `Age: ${age}` }
+     *         ]
+     *     };
+     * }
+     */
+    template?: (props: Record<string, unknown>) => ItemConfig;
+
+    /**
+     * Data bindings for reactive updates
+     * @example bind: { data: 'users', visible: 'hasUsers' }
+     */
+    bind?: BindConfig;
+
+    /**
+     * Render function for each item when using bind.data
+     * @example
+     * itemRender: (user) => ({
+     *     eztype: 'UserCard',
+     *     props: { user }
+     * })
+     */
+    itemRender?: (item: unknown, index?: number) => ItemConfig;
+
+    /**
+     * Method name to call before rendering (async data loading)
+     * The method must exist on the controller
+     * @example onLoad: 'loadUserData'
+     */
+    onLoad?: string;
+
+    /**
+     * Component to show while onLoad is executing
+     * @example
+     * fallback: {
+     *     eztype: 'EzSkeleton',
+     *     variant: 'card'
+     * }
+     */
+    fallback?: ItemConfig;
+
+    /**
+     * Reference name for accessing this component via ez._refs
+     * @example ref: 'myGrid' // access as ez._refs.myGrid
+     */
+    ref?: string;
+
+    /**
+     * Flex grow value for the component
+     */
+    flex?: number;
+
+    /**
+     * Route parameters passed by the router
+     */
+    routeParams?: Record<string, string>;
+
+    /** Any additional properties */
+    [key: string]: unknown;
+}
+
+/**
+ * Controller definition for ez.defineController()
+ */
+export interface ControllerDef {
+    /**
+     * Reactive state object - automatically wrapped with deepSignal
+     * Access in methods via this.state
+     * @example
+     * state: {
+     *   users: [],
+     *   loading: false,
+     *   filters: { search: '', status: 'all' }
+     * }
+     */
+    state?: Record<string, unknown>;
+
+    /**
+     * Called once when controller is first initialized
+     * Use for initial data loading
+     * @example
+     * async onInit() {
+     *   this.state.loading = true;
+     *   this.state.users = await api.getUsers();
+     *   this.state.loading = false;
+     * }
+     */
+    onInit?: () => void | Promise<void>;
+
+    /**
+     * Called when route changes (for view controllers)
+     * @param params.fullPath - Current route path
+     * @param params.chain - Remaining route chain for nested views
+     * @example
+     * async onRouteChange({ fullPath, chain }) {
+     *   const userId = chain[0]?.params?.id;
+     *   if (userId) await this.loadUser(userId);
+     * }
+     */
+    onRouteChange?: (params: { fullPath: string; chain: unknown[] }) => void | Promise<void>;
+
+    /**
+     * Called when controller is being destroyed
+     * Use for cleanup (event listeners, timers, etc.)
+     * @example
+     * onDestroy() {
+     *   clearInterval(this.refreshTimer);
+     * }
+     */
+    onDestroy?: () => void;
+
+    /**
+     * Custom methods - access state via this.state
+     * @example
+     * async loadUsers() {
+     *   this.state.users = await api.get('/users');
+     * },
+     * addUser(user) {
+     *   this.state.users.push(user);
+     * }
+     */
+    [key: string]: unknown;
+}