microui-wc 0.1.0

package/src/core/form-state.js

@@ -0,0 +1,252 @@
+/**
+ * @fileoverview Form State Management Utilities
+ * Agent-friendly form validation and state tracking
+ * 
+ * @example
+ * import { createFormState } from 'microui';
+ * 
+ * const form = document.querySelector('mu-form');
+ * const state = createFormState(form, {
+ *     email: { required: true, type: 'email' },
+ *     password: { required: true, minLength: 8 }
+ * });
+ * 
+ * state.isValid;    // true if all fields valid
+ * state.isDirty;    // true if any field changed
+ * state.fields.email.value;
+ * state.fields.email.error;
+ * state.fields.email.touched;
+ */
+
+import { signal, computed, effect } from '../core/signals.js';
+
+/**
+ * @typedef {Object} FieldRule
+ * @property {boolean} [required]
+ * @property {number} [minLength]
+ * @property {number} [maxLength]
+ * @property {RegExp} [pattern]
+ * @property {string} [type] - 'email', 'url', 'number'
+ * @property {(value: string) => string|null} [validate] - Custom validator
+ */
+
+/**
+ * @typedef {Object} FieldState
+ * @property {string} value
+ * @property {string|null} error
+ * @property {boolean} touched
+ * @property {boolean} dirty
+ */
+
+/**
+ * @typedef {Object} FormState
+ * @property {Object<string, FieldState>} fields
+ * @property {boolean} isValid
+ * @property {boolean} isDirty
+ * @property {boolean} isSubmitting
+ * @property {() => Object<string, string>} getValues
+ * @property {() => Object<string, string|null>} getErrors
+ * @property {() => void} reset
+ * @property {() => boolean} validate
+ */
+
+/**
+ * Validate a single field value against rules
+ * @param {string} value 
+ * @param {FieldRule} rules 
+ * @returns {string|null} Error message or null if valid
+ */
+function validateField(value, rules) {
+    if (rules.required && !value?.trim()) {
+        return 'This field is required';
+    }
+
+    if (value && rules.minLength && value.length < rules.minLength) {
+        return `Minimum ${rules.minLength} characters required`;
+    }
+
+    if (value && rules.maxLength && value.length > rules.maxLength) {
+        return `Maximum ${rules.maxLength} characters allowed`;
+    }
+
+    if (value && rules.pattern && !rules.pattern.test(value)) {
+        return 'Invalid format';
+    }
+
+    if (value && rules.type === 'email') {
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        if (!emailRegex.test(value)) {
+            return 'Invalid email address';
+        }
+    }
+
+    if (value && rules.type === 'url') {
+        try {
+            new URL(value);
+        } catch {
+            return 'Invalid URL';
+        }
+    }
+
+    if (rules.validate) {
+        return rules.validate(value);
+    }
+
+    return null;
+}
+
+/**
+ * Create reactive form state from a form element
+ * @param {HTMLElement} formElement - mu-form or form element
+ * @param {Object<string, FieldRule>} schema - Validation rules per field
+ * @returns {FormState}
+ */
+export function createFormState(formElement, schema = {}) {
+    const fieldNames = Object.keys(schema);
+
+    /** @type {Object<string, ReturnType<typeof signal>>} */
+    const fieldSignals = {};
+
+    /** @type {Object<string, {value: string, error: string|null, touched: boolean, dirty: boolean}}>} */
+    const initialState = {};
+
+    // Initialize signals for each field
+    for (const name of fieldNames) {
+        const input = formElement.querySelector(`[name="${name}"]`);
+        const initialValue = input?.value || input?.getAttribute('value') || '';
+
+        fieldSignals[name] = signal({
+            value: initialValue,
+            error: null,
+            touched: false,
+            dirty: false
+        }, `form-${name}`);
+
+        initialState[name] = { value: initialValue, error: null, touched: false, dirty: false };
+    }
+
+    // Computed: isValid
+    const isValid = computed(() => {
+        for (const name of fieldNames) {
+            const field = fieldSignals[name]();
+            const error = validateField(field.value, schema[name] || {});
+            if (error) return false;
+        }
+        return true;
+    });
+
+    // Computed: isDirty
+    const isDirty = computed(() => {
+        for (const name of fieldNames) {
+            if (fieldSignals[name]().dirty) return true;
+        }
+        return false;
+    });
+
+    const isSubmitting = signal(false, 'form-submitting');
+
+    // Setup input listeners
+    for (const name of fieldNames) {
+        const input = formElement.querySelector(`[name="${name}"]`);
+        if (!input) continue;
+
+        input.addEventListener('input', (e) => {
+            const value = /** @type {HTMLInputElement} */ (e.target).value;
+            const current = fieldSignals[name]();
+            const error = validateField(value, schema[name] || {});
+
+            fieldSignals[name].set({
+                ...current,
+                value,
+                dirty: value !== initialState[name].value,
+                error: current.touched ? error : null
+            });
+        });
+
+        input.addEventListener('blur', () => {
+            const current = fieldSignals[name]();
+            const error = validateField(current.value, schema[name] || {});
+
+            fieldSignals[name].set({
+                ...current,
+                touched: true,
+                error
+            });
+        });
+    }
+
+    // Create fields proxy for easy access
+    const fields = new Proxy({}, {
+        get(_, name) {
+            if (typeof name === 'string' && fieldSignals[name]) {
+                return fieldSignals[name]();
+            }
+            return undefined;
+        }
+    });
+
+    return {
+        get fields() { return fields; },
+        get isValid() { return isValid(); },
+        get isDirty() { return isDirty(); },
+        get isSubmitting() { return isSubmitting(); },
+        set isSubmitting(v) { isSubmitting.set(v); },
+
+        getValues() {
+            const values = {};
+            for (const name of fieldNames) {
+                values[name] = fieldSignals[name]().value;
+            }
+            return values;
+        },
+
+        getErrors() {
+            const errors = {};
+            for (const name of fieldNames) {
+                errors[name] = fieldSignals[name]().error;
+            }
+            return errors;
+        },
+
+        reset() {
+            for (const name of fieldNames) {
+                fieldSignals[name].set({ ...initialState[name] });
+                const input = formElement.querySelector(`[name="${name}"]`);
+                if (input) input.value = initialState[name].value;
+            }
+        },
+
+        validate() {
+            let valid = true;
+            for (const name of fieldNames) {
+                const current = fieldSignals[name]();
+                const error = validateField(current.value, schema[name] || {});
+                if (error) valid = false;
+
+                fieldSignals[name].set({
+                    ...current,
+                    touched: true,
+                    error
+                });
+            }
+            return valid;
+        }
+    };
+}
+
+/**
+ * Helper to get form values without state management
+ * @param {HTMLElement} formElement 
+ * @returns {Object<string, string>}
+ */
+export function getFormValues(formElement) {
+    const values = {};
+    const inputs = formElement.querySelectorAll('[name]');
+    for (const input of inputs) {
+        const name = input.getAttribute('name');
+        if (name) {
+            values[name] = /** @type {HTMLInputElement} */ (input).value || '';
+        }
+    }
+    return values;
+}

package/src/core/http.js

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview HTTP Utilities for microUI
+ * 
+ * Simple fetch wrapper with common patterns.
+ * 
+ * Usage:
+ * const data = await http.get('/api/users');
+ * await http.post('/api/users', { name: 'John' });
+ */
+
+export const http = {
+    baseURL: '',
+    headers: {
+        'Content-Type': 'application/json'
+    },
+
+    /**
+     * Set base URL for all requests
+     */
+    setBaseURL(url) {
+        this.baseURL = url;
+    },
+
+    /**
+     * Set default header
+     */
+    setHeader(key, value) {
+        this.headers[key] = value;
+    },
+
+    /**
+     * GET request
+     */
+    async get(url, options = {}) {
+        return this.request(url, { ...options, method: 'GET' });
+    },
+
+    /**
+     * POST request
+     */
+    async post(url, body, options = {}) {
+        return this.request(url, { ...options, method: 'POST', body });
+    },
+
+    /**
+     * PUT request
+     */
+    async put(url, body, options = {}) {
+        return this.request(url, { ...options, method: 'PUT', body });
+    },
+
+    /**
+     * DELETE request
+     */
+    async delete(url, options = {}) {
+        return this.request(url, { ...options, method: 'DELETE' });
+    },
+
+    /**
+     * Core request method
+     */
+    async request(url, options = {}) {
+        const fullURL = this.baseURL + url;
+
+        const config = {
+            method: options.method || 'GET',
+            headers: { ...this.headers, ...options.headers }
+        };
+
+        if (options.body) {
+            config.body = JSON.stringify(options.body);
+        }
+
+        try {
+            const response = await fetch(fullURL, config);
+
+            if (!response.ok) {
+                throw new HttpError(response.status, response.statusText, await response.text());
+            }
+
+            const contentType = response.headers.get('content-type');
+            if (contentType?.includes('application/json')) {
+                return response.json();
+            }
+
+            return response.text();
+        } catch (error) {
+            if (error instanceof HttpError) throw error;
+            throw new HttpError(0, 'Network Error', error.message);
+        }
+    }
+};
+
+/**
+ * HTTP Error class
+ */
+export class HttpError extends Error {
+    constructor(status, statusText, body) {
+        super(`HTTP ${status}: ${statusText}`);
+        this.status = status;
+        this.statusText = statusText;
+        this.body = body;
+    }
+}

package/src/core/keyboard.js

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Centralized Keyboard Manager for microUI
+ * 
+ * Provides a stack-based ESC key handler for modal-like components.
+ * Components register handlers when opened and unregister when closed.
+ * ESC key closes the topmost component (LIFO stack).
+ * 
+ * @example
+ * import { keyboard } from '../core/keyboard.js';
+ * 
+ * connectedCallback() {
+ *     this._unsubEsc = keyboard.pushEscapeHandler(this, () => this.close());
+ * }
+ * 
+ * disconnectedCallback() {
+ *     this._unsubEsc?.();
+ * }
+ */
+
+/**
+ * @typedef {Object} EscapeEntry
+ * @property {HTMLElement} element - The element that registered the handler
+ * @property {() => void} callback - Function to call on ESC
+ */
+
+class KeyboardManager {
+    /** @type {EscapeEntry[]} */
+    #escapeStack = [];
+
+    /** @type {boolean} */
+    #initialized = false;
+
+    constructor() {
+        this.#init();
+    }
+
+    /**
+     * Initialize the global keyboard listener
+     * @private
+     */
+    #init() {
+        if (this.#initialized || typeof window === 'undefined') return;
+
+        document.addEventListener('keydown', (e) => {
+            if (e.key === 'Escape' && this.#escapeStack.length > 0) {
+                e.preventDefault();
+                e.stopPropagation();
+
+                // Get the topmost handler
+                const top = this.#escapeStack[this.#escapeStack.length - 1];
+                top.callback();
+            }
+        });
+
+        this.#initialized = true;
+    }
+
+    /**
+     * Register an ESC key handler for a component.
+     * Handlers are called in LIFO order (last registered = first to receive ESC).
+     * 
+     * @param {HTMLElement} element - The element registering the handler
+     * @param {() => void} callback - Function to call when ESC is pressed
+     * @returns {() => void} Unsubscribe function - call when closing/disconnecting
+     */
+    pushEscapeHandler(element, callback) {
+        const entry = { element, callback };
+        this.#escapeStack.push(entry);
+
+        // Return unsubscribe function
+        return () => {
+            const index = this.#escapeStack.indexOf(entry);
+            if (index > -1) {
+                this.#escapeStack.splice(index, 1);
+            }
+        };
+    }
+
+    /**
+     * Check if an element is currently at the top of the ESC stack
+     * @param {HTMLElement} element
+     * @returns {boolean}
+     */
+    isTopmost(element) {
+        if (this.#escapeStack.length === 0) return false;
+        return this.#escapeStack[this.#escapeStack.length - 1].element === element;
+    }
+
+    /**
+     * Get the current stack depth (for debugging)
+     * @returns {number}
+     */
+    get stackDepth() {
+        return this.#escapeStack.length;
+    }
+}
+
+/**
+ * Global keyboard manager singleton
+ * @type {KeyboardManager}
+ */
+export const keyboard = new KeyboardManager();
+
+// Also export class for testing
+export { KeyboardManager };

package/src/core/layers.js

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Centralized Z-Index Layer System for microUI
+ * 
+ * Provides consistent layering across all components.
+ * Uses named constants to eliminate magic numbers.
+ * 
+ * Layer Stack (lowest to highest):
+ * - base: 1 (default content)
+ * - sticky: 100 (sticky headers, FABs)
+ * - dropdown: 1000 (dropdowns, menus)
+ * - drawer: 1100 (navigation drawers)
+ * - modal: 1200 (modal dialogs)
+ * - toast: 1300 (toast notifications)
+ * - tooltip: 1400 (tooltips)
+ * - overlay: 9999 (full-screen overlays)
+ * - devtools: 999999 (agent dev tools - always on top)
+ * 
+ * @example
+ * import { Z_INDEX } from '../core/layers.js';
+ * this.style.zIndex = Z_INDEX.modal;
+ */
+
+/**
+ * Z-Index layer constants
+ * @type {Object<string, number>}
+ */
+export const Z_INDEX = Object.freeze({
+    /** Default content layer */
+    base: 1,
+    /** Sticky headers, FABs */
+    sticky: 100,
+    /** Dropdowns, menus, popovers */
+    dropdown: 1000,
+    /** Navigation drawers */
+    drawer: 1100,
+    /** Modal dialogs */
+    modal: 1200,
+    /** Toast notifications */
+    toast: 1300,
+    /** Tooltips */
+    tooltip: 1400,
+    /** Full-screen overlays */
+    overlay: 9999,
+    /** Agent dev tools - always on top */
+    devtools: 999999
+});
+
+/**
+ * Inject CSS custom properties for z-index layers.
+ * Call this once on app init to use in CSS.
+ * 
+ * @example
+ * // In CSS:
+ * .my-modal { z-index: var(--z-modal); }
+ */
+export function injectLayerTokens() {
+    // Check if already injected
+    if (document.getElementById('mu-layer-tokens')) return;
+
+    const style = document.createElement('style');
+    style.id = 'mu-layer-tokens';
+    style.textContent = `:root {
+${Object.entries(Z_INDEX).map(([k, v]) => `    --z-${k}: ${v};`).join('\n')}
+}`;
+    document.head.appendChild(style);
+}
+
+// Auto-inject on load
+if (typeof window !== 'undefined') {
+    injectLayerTokens();
+}