tyrell-components 1.0.0-RC13 → 1.0.0-RC15

package/lib/utils/property-capture.js

@@ -1,152 +1,44 @@
-/**
- * Property Capture Utility
- *
- * Solves the problem of frameworks (React, Reagent, etc.) setting properties
- * on custom elements BEFORE connectedCallback runs.
- *
- * PROBLEM:
- * 1. Framework creates element: document.createElement('ty-dropdown')
- * 2. Framework sets properties: element.value = "foo"
- * 3. Constructor runs and defines getters/setters
- * 4. BUT properties were already set, creating instance properties
- * 5. Instance properties shadow the class getters/setters
- * 6. connectedCallback runs - too late!
- *
- * SOLUTION:
- * In connectedCallback, capture any pre-set properties and apply them properly.
- *
- * @example
- * ```typescript
- * connectedCallback(): void {
- *   const preSetProps = capturePreSetProperties(this, [
- *     'value', 'clearable', 'disabled'
- *   ])
- *
- *   if (preSetProps.value !== undefined) {
- *     this._value = preSetProps.value
- *   }
- * }
- * ```
- */
-/**
- * Capture properties that were set before connectedCallback
- *
- * @param element - The custom element instance
- * @param propertyNames - Array of property names to check
- * @param options - Capture options
- * @returns Record of captured properties with metadata
- *
- * @example
- * ```typescript
- * const captured = capturePreSetProperties(this, ['value', 'disabled'])
- * // {
- * //   value: { name: 'value', value: 'foo', hadProperty: true },
- * //   disabled: { name: 'disabled', value: undefined, hadProperty: false }
- * // }
- * ```
- */
 export function capturePreSetProperties(element, propertyNames, options = { cleanup: true }) {
-    const captured = {};
-    for (const name of propertyNames) {
-        const descriptor = Object.getOwnPropertyDescriptor(element, name);
-        captured[name] = {
-            name,
-            value: descriptor?.value,
-            hadProperty: descriptor !== undefined && descriptor.value !== undefined
-        };
-        // Clean up instance property so class getter/setter works
-        if (options.cleanup && captured[name].hadProperty) {
-            delete element[name];
-        }
-    }
-    return captured;
+const captured = {};
+for (const name of propertyNames) {
+const descriptor = Object.getOwnPropertyDescriptor(element, name);
+captured[name] = {
+name,
+value: descriptor?.value,
+hadProperty: descriptor !== undefined && descriptor.value !== undefined
+};
+if (options.cleanup && captured[name].hadProperty) {
+delete element[name];
+}
+}
+return captured;
 }
-/**
- * Simpler API - just get the values that were pre-set
- *
- * @param element - The custom element instance
- * @param propertyNames - Array of property names to check
- * @param options - Capture options
- * @returns Record of property names to values (only includes properties that were set)
- *
- * @example
- * ```typescript
- * const values = getCapturedValues(this, ['value', 'disabled'])
- * if (values.value !== undefined) {
- *   this._value = values.value
- * }
- * ```
- */
 export function getCapturedValues(element, propertyNames, options) {
-    const captured = capturePreSetProperties(element, propertyNames, options);
-    const values = {};
-    for (const [name, data] of Object.entries(captured)) {
-        if (data.hadProperty) {
-            values[name] = data.value;
-        }
-    }
-    return values;
+const captured = capturePreSetProperties(element, propertyNames, options);
+const values = {};
+for (const [name, data] of Object.entries(captured)) {
+if (data.hadProperty) {
+values[name] = data.value;
+}
+}
+return values;
 }
-/**
- * Automatically apply pre-set properties to private fields
- *
- * @param element - The custom element instance
- * @param propertyNames - Array of property names to check
- * @param propertyMap - Optional mapping of public names to private field names
- *                      Default: adds underscore prefix (e.g., 'value' -> '_value')
- * @param options - Capture options
- *
- * @example
- * ```typescript
- * // Simple usage (uses _propertyName convention)
- * applyPreSetProperties(this, ['value', 'disabled'])
- * // Sets this._value and this._disabled
- *
- * // Custom mapping
- * applyPreSetProperties(this, ['value'], { value: 'internalValue' })
- * // Sets this.internalValue
- * ```
- */
 export function applyPreSetProperties(element, propertyNames, propertyMap, options) {
-    const captured = capturePreSetProperties(element, propertyNames, options);
-    for (const [name, data] of Object.entries(captured)) {
-        if (data.hadProperty) {
-            // Determine the private field name
-            const privateName = propertyMap?.[name] || `_${name}`;
-            element[privateName] = data.value;
-        }
-    }
+const captured = capturePreSetProperties(element, propertyNames, options);
+for (const [name, data] of Object.entries(captured)) {
+if (data.hadProperty) {
+const privateName = propertyMap?.[name] || `_${name}`;
+element[privateName] = data.value;
+}
+}
 }
-/**
- * Helper for components with standard _propertyName pattern
- *
- * @param element - The custom element instance
- * @param propertyNames - Array of property names to check
- * @param transformer - Optional function to transform values before setting
- * @param options - Capture options
- *
- * @example
- * ```typescript
- * connectedCallback(): void {
- *   // Basic usage
- *   captureAndApplyProperties(this, ['value', 'disabled', 'required'])
- *
- *   // With transformation
- *   captureAndApplyProperties(this, ['value'], (name, value) => {
- *     if (name === 'value') return this.parseValue(value)
- *     return value
- *   })
- * }
- * ```
- */
 export function captureAndApplyProperties(element, propertyNames, transformer, options) {
-    const captured = capturePreSetProperties(element, propertyNames, options);
-    for (const [name, data] of Object.entries(captured)) {
-        if (data.hadProperty) {
-            const privateName = `_${name}`;
-            const value = transformer ? transformer(name, data.value) : data.value;
-            element[privateName] = value;
-        }
-    }
+const captured = capturePreSetProperties(element, propertyNames, options);
+for (const [name, data] of Object.entries(captured)) {
+if (data.hadProperty) {
+const privateName = `_${name}`;
+const value = transformer ? transformer(name, data.value) : data.value;
+element[privateName] = value;
+}
+}
 }
-//# sourceMappingURL=property-capture.js.map

package/lib/utils/property-manager.d.ts

@@ -87,4 +87,3 @@ export declare class PropertyManager<T = any> {
      */
     handleAlias(aliasName: string, value: any): PropertyChange | null;
 }
-//# sourceMappingURL=property-manager.d.ts.map

package/lib/utils/property-manager.js

@@ -1,197 +1,127 @@
-/**
- * Property Manager - Unified property lifecycle for web components
- *
- * Handles property/attribute synchronization, validation, coercion, and change tracking.
- * All property updates flow through a single code path for consistency.
- */
-/**
- * Manages component properties with unified lifecycle
- */
 export class PropertyManager {
-    constructor(config) {
-        this._props = new Map();
-        this._config = config;
-        this._initializeDefaults();
-    }
-    /**
-     * Initialize properties with default values
-     */
-    _initializeDefaults() {
-        for (const [name, config] of Object.entries(this._config)) {
-            if (config.default !== undefined) {
-                this._props.set(name, config.default);
-            }
-        }
-    }
-    /**
-     * Check if a property name exists in the configuration
-     */
-    hasConfig(name) {
-        return name in this._config;
-    }
-    /**
-     * Update a property value
-     * Returns PropertyChange if value changed, null otherwise
-     */
-    updateProperty(name, value, source = 'property') {
-        const config = this._config[name];
-        if (!config) {
-            console.warn(`[PropertyManager] Unknown property: ${name}`);
-            return null;
-        }
-        // Get old value
-        const oldValue = this._props.get(name);
-        // Coerce value to correct type
-        const coercedValue = this._coerceValue(name, value, config);
-        // Validate value
-        if (!this._validateValue(name, coercedValue, config)) {
-            console.warn(`[PropertyManager] Invalid value for ${name}:`, coercedValue);
-            return null;
-        }
-        // Check if value actually changed
-        if (this._valuesEqual(oldValue, coercedValue)) {
-            return null;
-        }
-        // Update internal map
-        this._props.set(name, coercedValue);
-        // Create change object
-        const change = {
-            name,
-            oldValue,
-            newValue: coercedValue,
-            source
-        };
-        return change;
-    }
-    /**
-     * Coerce value to the correct type
-     */
-    _coerceValue(name, value, config) {
-        // Custom coercion
-        if (config.coerce) {
-            return config.coerce(value);
-        }
-        // Null/undefined handling
-        if (value === null || value === undefined) {
-            return config.default ?? null;
-        }
-        // Type coercion
-        switch (config.type) {
-            case 'boolean':
-                // HTML Standard: attribute present (even empty) = true, absent = false
-                // String handling:
-                if (typeof value === 'string') {
-                    // Empty string = true (HTML boolean attribute: <input checked>)
-                    if (value === '')
-                        return true;
-                    // Explicit false values
-                    const normalized = value.toLowerCase().trim();
-                    if (normalized === 'false' || normalized === '0')
-                        return false;
-                    // Everything else is truthy
-                    return true;
-                }
-                // Non-string: standard truthy/falsy
-                return Boolean(value);
-            case 'number':
-                const num = Number(value);
-                return isNaN(num) ? (config.default ?? 0) : num;
-            case 'string':
-                return String(value);
-            case 'object':
-            case 'array':
-                if (typeof value === 'string') {
-                    try {
-                        return JSON.parse(value);
-                    }
-                    catch {
-                        console.warn(`[PropertyManager] Failed to parse ${name}:`, value);
-                        return config.default ?? (config.type === 'array' ? [] : {});
-                    }
-                }
-                return value;
-            default:
-                return value;
-        }
-    }
-    /**
-     * Validate a property value
-     */
-    _validateValue(name, value, config) {
-        if (config.validate) {
-            return config.validate(value);
-        }
-        return true;
-    }
-    /**
-     * Check if two values are equal
-     */
-    _valuesEqual(a, b) {
-        // Simple equality for primitives
-        if (typeof a !== 'object' || typeof b !== 'object') {
-            return a === b;
-        }
-        // Null checks
-        if (a === null || b === null) {
-            return a === b;
-        }
-        // Deep equality for objects/arrays (simple implementation)
-        // For production, consider using a proper deep equality library
-        try {
-            return JSON.stringify(a) === JSON.stringify(b);
-        }
-        catch {
-            return false;
-        }
-    }
-    /**
-     * Get a property value
-     */
-    get(name) {
-        return this._props.get(name);
-    }
-    /**
-     * Get all properties as an object
-     */
-    getAll() {
-        return Object.fromEntries(this._props);
-    }
-    /**
-     * Get property configuration
-     */
-    getConfig(name) {
-        return this._config[name];
-    }
-    /**
-     * Check if a property is visual (requires render)
-     */
-    isVisual(name) {
-        return this._config[name]?.visual ?? false;
-    }
-    /**
-     * Check if a property affects form value
-     */
-    isFormValue(name) {
-        return this._config[name]?.formValue ?? false;
-    }
-    /**
-     * Check if a property should emit change events
-     */
-    shouldEmitChange(name) {
-        return this._config[name]?.emitChange ?? false;
-    }
-    /**
-     * Handle property aliases (e.g., not-clearable → clearable: false)
-     */
-    handleAlias(aliasName, value) {
-        // Find property with this alias
-        for (const [propName, config] of Object.entries(this._config)) {
-            if (config.aliases && aliasName in config.aliases) {
-                const aliasedValue = config.aliases[aliasName];
-                return this.updateProperty(propName, aliasedValue, 'attribute');
-            }
-        }
-        return null;
-    }
-}
-//# sourceMappingURL=property-manager.js.map
+constructor(config) {
+this._props = new Map();
+this._config = config;
+this._initializeDefaults();
+}
+_initializeDefaults() {
+for (const [name, config] of Object.entries(this._config)) {
+if (config.default !== undefined) {
+this._props.set(name, config.default);
+}
+}
+}
+hasConfig(name) {
+return name in this._config;
+}
+updateProperty(name, value, source = 'property') {
+const config = this._config[name];
+if (!config) {
+console.warn(`[PropertyManager] Unknown property: ${name}`);
+return null;
+}
+const oldValue = this._props.get(name);
+const coercedValue = this._coerceValue(name, value, config);
+if (!this._validateValue(name, coercedValue, config)) {
+console.warn(`[PropertyManager] Invalid value for ${name}:`, coercedValue);
+return null;
+}
+if (this._valuesEqual(oldValue, coercedValue)) {
+return null;
+}
+this._props.set(name, coercedValue);
+const change = {
+name,
+oldValue,
+newValue: coercedValue,
+source
+};
+return change;
+}
+_coerceValue(name, value, config) {
+if (config.coerce) {
+return config.coerce(value);
+}
+if (value === null || value === undefined) {
+return config.default ?? null;
+}
+switch (config.type) {
+case 'boolean':
+if (typeof value === 'string') {
+if (value === '')
+return true;
+const normalized = value.toLowerCase().trim();
+if (normalized === 'false' || normalized === '0')
+return false;
+return true;
+}
+return Boolean(value);
+case 'number':
+const num = Number(value);
+return isNaN(num) ? (config.default ?? 0) : num;
+case 'string':
+return String(value);
+case 'object':
+case 'array':
+if (typeof value === 'string') {
+try {
+return JSON.parse(value);
+}
+catch {
+console.warn(`[PropertyManager] Failed to parse ${name}:`, value);
+return config.default ?? (config.type === 'array' ? [] : {});
+}
+}
+return value;
+default:
+return value;
+}
+}
+_validateValue(name, value, config) {
+if (config.validate) {
+return config.validate(value);
+}
+return true;
+}
+_valuesEqual(a, b) {
+if (typeof a !== 'object' || typeof b !== 'object') {
+return a === b;
+}
+if (a === null || b === null) {
+return a === b;
+}
+try {
+return JSON.stringify(a) === JSON.stringify(b);
+}
+catch {
+return false;
+}
+}
+get(name) {
+return this._props.get(name);
+}
+getAll() {
+return Object.fromEntries(this._props);
+}
+getConfig(name) {
+return this._config[name];
+}
+isVisual(name) {
+return this._config[name]?.visual ?? false;
+}
+isFormValue(name) {
+return this._config[name]?.formValue ?? false;
+}
+shouldEmitChange(name) {
+return this._config[name]?.emitChange ?? false;
+}
+handleAlias(aliasName, value) {
+for (const [propName, config] of Object.entries(this._config)) {
+if (config.aliases && aliasName in config.aliases) {
+const aliasedValue = config.aliases[aliasName];
+return this.updateProperty(propName, aliasedValue, 'attribute');
+}
+}
+return null;
+}
+}

package/lib/utils/resize-observer.d.ts

@@ -39,4 +39,3 @@ export declare function updateSize(id: string, width: number, height: number): v
  * Internal: Remove size from registry and cleanup callbacks
  */
 export declare function removeSize(id: string): void;
-//# sourceMappingURL=resize-observer.d.ts.map

package/lib/utils/resize-observer.js

@@ -1,71 +1,35 @@
-/**
- * Resize Observer Registry & Callbacks
- *
- * Provides global registry for element sizes and optional callback subscriptions.
- */
-// Global registry (Map-based storage)
 const sizes = new Map();
 const callbacks = new Map();
-/**
- * Get current size for element by ID (sync query)
- *
- * @example
- * const size = getSize('parent-container')
- * if (size) console.log(`Width: ${size.width}px`)
- */
 export function getSize(id) {
-    return sizes.get(id);
+return sizes.get(id);
 }
-/**
- * Subscribe to size changes for element by ID
- * Returns unsubscribe function
- *
- * @example
- * const unsubscribe = onResize('parent', ({ width, height }) => {
- *   console.log(`Resized to ${width}x${height}`)
- * })
- * // Later: unsubscribe()
- */
 export function onResize(id, callback) {
-    if (!callbacks.has(id)) {
-        callbacks.set(id, new Set());
-    }
-    callbacks.get(id).add(callback);
-    // Call immediately with current size if available
-    const current = sizes.get(id);
-    if (current)
-        callback(current);
-    // Return unsubscribe function
-    return () => {
-        callbacks.get(id)?.delete(callback);
-        if (callbacks.get(id)?.size === 0) {
-            callbacks.delete(id);
-        }
-    };
+if (!callbacks.has(id)) {
+callbacks.set(id, new Set());
+}
+callbacks.get(id).add(callback);
+const current = sizes.get(id);
+if (current)
+callback(current);
+return () => {
+callbacks.get(id)?.delete(callback);
+if (callbacks.get(id)?.size === 0) {
+callbacks.delete(id);
+}
+};
 }
-/**
- * Get all registered sizes (for debugging/window API)
- */
 export function getAllSizes() {
-    return Object.fromEntries(sizes);
+return Object.fromEntries(sizes);
 }
-/**
- * Internal: Update size in registry and notify callbacks
- */
 export function updateSize(id, width, height) {
-    sizes.set(id, { width, height });
-    // Notify all subscribers
-    const cbs = callbacks.get(id);
-    if (cbs) {
-        const size = { width, height };
-        cbs.forEach(cb => cb(size));
-    }
+sizes.set(id, { width, height });
+const cbs = callbacks.get(id);
+if (cbs) {
+const size = { width, height };
+cbs.forEach(cb => cb(size));
+}
 }
-/**
- * Internal: Remove size from registry and cleanup callbacks
- */
 export function removeSize(id) {
-    sizes.delete(id);
-    callbacks.delete(id);
+sizes.delete(id);
+callbacks.delete(id);
 }
-//# sourceMappingURL=resize-observer.js.map

package/lib/utils/scroll-lock.d.ts

@@ -1,15 +1,9 @@
 /**
- * CSS-based scroll prevention using position: fixed.
+ * CSS-based scroll prevention.
  *
- * Prevents body/page scrolling by temporarily fixing the body position
- * while preserving scroll position. Much more reliable than event prevention.
- *
- * Key benefits:
- * - No event manipulation complexity
- * - No interference with component keyboard navigation
- * - Preserves scroll position perfectly
- * - Standard industry technique
- * - Multiple component support with proper cleanup
+ * Prevents page scrolling via CSS rather than event cancellation — no event
+ * manipulation, no interference with component keyboard navigation, scroll
+ * position preserved. Reference-counted so multiple components can lock at once.
  */
 declare global {
     interface Window {
@@ -76,4 +70,3 @@ export declare function getLockState(): Readonly<{
     scrollY: number;
     activeLocks: string[];
 }>;
-//# sourceMappingURL=scroll-lock.d.ts.map