tyrell-components 1.0.0-RC13 → 1.0.0-RC14

package/lib/utils/property-capture.js

@@ -1,50 +1,3 @@
-/**
- * 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) {
@@ -54,29 +7,12 @@ export function capturePreSetProperties(element, propertyNames, options = { clea
             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;
 }
-/**
- * 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 = {};
@@ -87,58 +23,15 @@ export function getCapturedValues(element, propertyNames, options) {
     }
     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;
         }
     }
 }
-/**
- * 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)) {
@@ -149,4 +42,3 @@ export function captureAndApplyProperties(element, propertyNames, transformer, o
         }
     }
 }
-//# 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,21 +1,9 @@
-/**
- * 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) {
@@ -23,38 +11,25 @@ export class PropertyManager {
             }
         }
     }
-    /**
-     * 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,
@@ -63,35 +38,23 @@ export class PropertyManager {
         };
         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);
@@ -114,29 +77,19 @@ export class PropertyManager {
                 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);
         }
@@ -144,47 +97,25 @@ export class PropertyManager {
             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];
@@ -194,4 +125,3 @@ export class PropertyManager {
         return null;
     }
 }
-//# sourceMappingURL=property-manager.js.map

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,41 +1,16 @@
-/**
- * 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);
 }
-/**
- * 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) {
@@ -43,29 +18,18 @@ export function onResize(id, callback) {
         }
     };
 }
-/**
- * Get all registered sizes (for debugging/window API)
- */
 export function getAllSizes() {
     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));
     }
 }
-/**
- * Internal: Remove size from registry and cleanup callbacks
- */
 export function removeSize(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

package/lib/utils/scroll-lock.js

@@ -1,62 +1,20 @@
-/**
- * CSS-based scroll prevention using position: fixed.
- *
- * 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
- */
-// ============================================================================
-// Global State Management
-// ============================================================================
 const lockState = {
     locked: false,
     scrollY: 0,
     activeLocks: new Set(),
 };
-// ============================================================================
-// DOM Helper Functions
-// ============================================================================
-/**
- * Get the document body element
- */
 function getBodyEl() {
     return document.body;
 }
-/**
- * Get the document element (html)
- */
 function getDocEl() {
     return document.documentElement;
 }
-/**
- * Get current vertical scroll position
- */
 function getScrollY() {
     return window.scrollY || getDocEl().scrollTop || 0;
 }
-/**
- * Calculate the width of the browser's scrollbar
- */
 function getScrollbarWidth() {
-    // window.innerWidth - documentElement.clientWidth
     return window.innerWidth - getDocEl().clientWidth;
 }
-// ============================================================================
-// Core Lock/Unlock Functions
-// ============================================================================
-/**
- * Lock body scrolling using overflow: hidden on <html>.
- *
- * Avoids position: fixed on <body> which breaks centered/max-width body layouts
- * by snapping the body to the left edge. Using <html> instead leaves body layout
- * untouched while still preventing scroll.
- */
 function lockBodyFixed() {
     if (lockState.locked)
         return;
@@ -68,15 +26,11 @@ function lockBodyFixed() {
     lockState.scrollY = getScrollY();
     lockState.locked = true;
     docEl.style.overflow = 'hidden';
-    // Compensate for scrollbar disappearing to prevent layout shift
     if (scrollbarWidth > 0) {
         docEl.style.paddingRight = `${scrollbarWidth}px`;
     }
     docEl.classList.add('ty-scroll-locked');
 }
-/**
- * Unlock body scrolling
- */
 function unlockBodyFixed() {
     if (!lockState.locked)
         return;
@@ -89,103 +43,43 @@ function unlockBodyFixed() {
     docEl.style.paddingRight = '';
     lockState.locked = false;
 }
-// ============================================================================
-// Public API
-// ============================================================================
-/**
- * Lock scrolling for a specific component.
- *
- * Multiple components can lock scrolling simultaneously.
- * Scroll remains locked until ALL components unlock.
- *
- * @param componentId - Unique identifier for the component
- */
 export function lockScroll(componentId) {
     if (lockState.activeLocks.has(componentId))
         return;
-    // Add this component to active locks
     lockState.activeLocks.add(componentId);
-    // Lock body if this is the first lock
     if (lockState.activeLocks.size === 1) {
         lockBodyFixed();
     }
 }
-/**
- * Unlock scrolling for a specific component.
- *
- * Scroll remains locked if other components still have locks active.
- *
- * @param componentId - Unique identifier for the component
- */
 export function unlockScroll(componentId) {
     if (!lockState.activeLocks.has(componentId))
         return;
-    // Remove this component from active locks
     lockState.activeLocks.delete(componentId);
-    // Unlock body if this was the last lock
     if (lockState.activeLocks.size === 0) {
         unlockBodyFixed();
     }
 }
-/**
- * Emergency unlock - removes all scroll locks immediately.
- *
- * Use this for cleanup or error recovery scenarios.
- */
 export function forceUnlockAll() {
     lockState.activeLocks.clear();
     unlockBodyFixed();
 }
-// ============================================================================
-// Debug API
-// ============================================================================
-/**
- * Enable scroll lock debugging - useful for testing and development
- */
 export function enableDebug() {
     console.log('🔍 CSS Scroll lock debugging enabled');
     window.tyScrollDebug = true;
 }
-/**
- * Disable scroll lock debugging
- */
 export function disableDebug() {
     console.log('🔍 CSS Scroll lock debugging disabled');
     window.tyScrollDebug = false;
 }
-// ============================================================================
-// State Inspection
-// ============================================================================
-/**
- * Get the set of currently active component locks.
- *
- * @returns Set of component IDs that currently have scroll locked
- */
 export function getActiveLocks() {
     return new Set(lockState.activeLocks);
 }
-/**
- * Check if scrolling is currently locked.
- *
- * @returns true if any component has scroll locked
- */
 export function isLocked() {
     return lockState.locked;
 }
-/**
- * Check if scrolling is locked by a specific component.
- *
- * @param componentId - Component identifier to check
- * @returns true if this specific component has scroll locked
- */
 export function isLockedBy(componentId) {
     return lockState.activeLocks.has(componentId);
 }
-/**
- * Get the complete lock state for debugging.
- *
- * @returns Current state including scroll position and active locks
- */
 export function getLockState() {
     return {
         locked: lockState.locked,
@@ -193,4 +87,3 @@ export function getLockState() {
         activeLocks: Array.from(lockState.activeLocks),
     };
 }
-//# sourceMappingURL=scroll-lock.js.map

package/lib/utils/styles.d.ts

@@ -19,4 +19,3 @@ export declare function ensureStyles(shadowRoot: ShadowRoot, styleContent: Style
  * @returns Space-separated class string
  */
 export declare function buildClassList(...classes: (string | false | null | undefined)[]): string;
-//# sourceMappingURL=styles.d.ts.map

package/lib/utils/styles.js

@@ -1,46 +1,22 @@
-/**
- * CSS Utilities for Ty Components
- * Handles dynamic CSS loading into Shadow DOM
- */
-/** Cache of loaded CSSStyleSheet objects */
 const styleCache = new Map();
-/**
- * Ensure CSS is loaded into a shadow root
- * Uses CSSStyleSheet API for efficient style sharing
- *
- * @param shadowRoot - The shadow root to attach styles to
- * @param styleContent - Style content with CSS text and optional ID
- */
 export function ensureStyles(shadowRoot, styleContent) {
     const { css, id } = styleContent;
-    // Check cache first
     let sheet;
     if (id && styleCache.has(id)) {
         sheet = styleCache.get(id);
     }
     else {
-        // Create new stylesheet
         sheet = new CSSStyleSheet();
         sheet.replaceSync(css);
-        // Cache it if ID provided
         if (id) {
             styleCache.set(id, sheet);
         }
     }
-    // Append only if not already adopted
     const existing = shadowRoot.adoptedStyleSheets || [];
     if (!existing.includes(sheet)) {
         shadowRoot.adoptedStyleSheets = [...existing, sheet];
     }
 }
-/**
- * Build CSS class list from properties
- * Filters out falsy values
- *
- * @param classes - Array of class names or falsy values
- * @returns Space-separated class string
- */
 export function buildClassList(...classes) {
     return classes.filter(Boolean).join(' ');
 }
-//# sourceMappingURL=styles.js.map

package/lib/version.d.ts

@@ -4,5 +4,4 @@
  * This is automatically synced with package.json during build.
  * Use `npm version` to bump versions.
  */
-export declare const VERSION = "1.0.0-RC13";
-//# sourceMappingURL=version.d.ts.map
+export declare const VERSION = "1.0.0-RC14";

package/lib/version.js

@@ -1,11 +1 @@
-// AUTO-GENERATED FILE - DO NOT EDIT
-// This file is generated from package.json by scripts/generate-version.js
-// Run 'npm run generate:version' to regenerate
-/**
- * Current version of tyrell-components
- *
- * This is automatically synced with package.json during build.
- * Use `npm version` to bump versions.
- */
-export const VERSION = '1.0.0-RC13';
-//# sourceMappingURL=version.js.map
+export const VERSION = '1.0.0-RC14';