@smilodon/core 1.4.11 → 1.4.12

package/dist/index.cjs

@@ -1403,6 +1403,18 @@ const defaultConfig = {
         icon: '×',
     },
     callbacks: {},
+    tracking: {
+        enabled: false,
+        events: true,
+        styling: true,
+        limitations: true,
+        emitDiagnostics: false,
+        maxEntries: 200,
+    },
+    limitations: {
+        policies: {},
+        autoMitigateRuntimeModeSwitch: true,
+    },
     enabled: true,
     searchable: false,
     placeholder: 'Select an option...',
@@ -1879,6 +1891,10 @@ class EnhancedSelect extends HTMLElement {
     set classMap(map) {
         this._classMap = map;
         this._setGlobalStylesMirroring(Boolean(this._optionRenderer || map || this._groupHeaderRenderer));
+        this._track('style', 'classMapChanged', {
+            hasClassMap: Boolean(map),
+            keys: map ? Object.keys(map) : [],
+        });
         if (!this.isConnected)
             return;
         this._renderOptions();
@@ -1894,6 +1910,7 @@ class EnhancedSelect extends HTMLElement {
     set groupHeaderRenderer(renderer) {
         this._groupHeaderRenderer = renderer;
         this._setGlobalStylesMirroring(Boolean(this._optionRenderer || this._classMap || renderer));
+        this._track('style', 'groupHeaderRendererChanged', { enabled: Boolean(renderer) });
         if (!this.isConnected)
             return;
         this._renderOptions();
@@ -1912,6 +1929,7 @@ class EnhancedSelect extends HTMLElement {
         this._mirrorGlobalStylesForCustomOptions = false;
         this._globalStylesObserver = null;
         this._globalStylesContainer = null;
+        this._tracking = { events: [], styles: [], limitations: [] };
         this._shadow = this.attachShadow({ mode: 'open' });
         this._uniqueId = `enhanced-select-${Math.random().toString(36).substr(2, 9)}`;
         this._rendererHelpers = this._buildRendererHelpers();
@@ -1996,6 +2014,7 @@ class EnhancedSelect extends HTMLElement {
             return;
         }
         this._mirrorGlobalStylesForCustomOptions = enabled;
+        this._track('style', 'globalStylesMirroringChanged', { enabled });
         if (enabled) {
             this._setupGlobalStylesMirroring();
         }
@@ -3676,6 +3695,162 @@ class EnhancedSelect extends HTMLElement {
     }
     _emit(name, detail) {
         this.dispatchEvent(new CustomEvent(name, { detail, bubbles: true, composed: true }));
+        if (name !== 'diagnostic') {
+            this._track('event', String(name), detail);
+        }
+    }
+    _track(source, name, detail) {
+        const cfg = this._config.tracking;
+        if (!cfg?.enabled)
+            return;
+        if (source === 'event' && !cfg.events)
+            return;
+        if (source === 'style' && !cfg.styling)
+            return;
+        if (source === 'limitation' && !cfg.limitations)
+            return;
+        const entry = {
+            timestamp: Date.now(),
+            source,
+            name,
+            detail,
+        };
+        const bucket = source === 'event'
+            ? this._tracking.events
+            : source === 'style'
+                ? this._tracking.styles
+                : this._tracking.limitations;
+        bucket.push(entry);
+        const maxEntries = Math.max(10, cfg.maxEntries || 200);
+        if (bucket.length > maxEntries) {
+            bucket.splice(0, bucket.length - maxEntries);
+        }
+        if (cfg.emitDiagnostics) {
+            this.dispatchEvent(new CustomEvent('diagnostic', {
+                detail: entry,
+                bubbles: true,
+                composed: true,
+            }));
+        }
+    }
+    _getKnownLimitationDefinitions() {
+        return [
+            {
+                id: 'variableItemHeight',
+                title: 'Variable item height',
+                description: 'Virtualization assumes fixed or estimated item heights; fully dynamic heights are not yet supported.',
+                workaround: 'Use consistent item heights or set estimatedItemHeight to your dominant row size.',
+            },
+            {
+                id: 'builtInFetchPaginationApi',
+                title: 'Built-in fetch/pagination API',
+                description: 'Core does not include a built-in fetchUrl/searchUrl pagination transport.',
+                workaround: 'Use onSearch/onLoadMore callbacks and update data via setItems().',
+            },
+            {
+                id: 'virtualizationOverheadSmallLists',
+                title: 'Virtualization overhead for small lists',
+                description: 'Virtualization can add slight overhead on very small lists.',
+                workaround: 'Disable virtualization for tiny datasets when micro-latency is critical.',
+            },
+            {
+                id: 'runtimeModeSwitching',
+                title: 'Runtime single/multi mode switching',
+                description: 'Switching between single and multi mode can require state reset for consistency.',
+                workaround: 'Enable autoMitigateRuntimeModeSwitch or recreate/reset component state when toggling modes.',
+            },
+            {
+                id: 'legacyBrowserSupport',
+                title: 'Legacy browser support',
+                description: 'Official support targets modern evergreen browsers.',
+            },
+            {
+                id: 'webkitArchLinux',
+                title: 'Playwright WebKit on Arch-based Linux',
+                description: 'Native WebKit Playwright bundle depends on unavailable legacy system libraries on Arch-based distros.',
+                workaround: 'Run WebKit E2E tests via Playwright Docker image.',
+            },
+        ];
+    }
+    _evaluateLimitationStatus(id) {
+        const policyMode = this._config.limitations?.policies?.[id]?.mode ?? 'default';
+        if (policyMode === 'suppress')
+            return 'suppressed';
+        if (id === 'runtimeModeSwitching' && this._config.limitations?.autoMitigateRuntimeModeSwitch) {
+            return 'mitigated';
+        }
+        return 'active';
+    }
+    getKnownLimitations() {
+        return this._getKnownLimitationDefinitions().map((limitation) => {
+            const mode = this._config.limitations?.policies?.[limitation.id]?.mode ?? 'default';
+            return {
+                ...limitation,
+                mode,
+                status: this._evaluateLimitationStatus(limitation.id),
+            };
+        });
+    }
+    setLimitationPolicies(policies) {
+        const next = {
+            ...(this._config.limitations?.policies || {}),
+            ...policies,
+        };
+        this.updateConfig({
+            limitations: {
+                ...(this._config.limitations || { autoMitigateRuntimeModeSwitch: true, policies: {} }),
+                policies: next,
+            },
+        });
+        this._track('limitation', 'policiesUpdated', { policies: next });
+    }
+    getTrackingSnapshot() {
+        return {
+            events: [...this._tracking.events],
+            styles: [...this._tracking.styles],
+            limitations: [...this._tracking.limitations],
+        };
+    }
+    clearTracking(source) {
+        if (!source || source === 'all') {
+            this._tracking.events = [];
+            this._tracking.styles = [];
+            this._tracking.limitations = [];
+            return;
+        }
+        if (source === 'event')
+            this._tracking.events = [];
+        if (source === 'style')
+            this._tracking.styles = [];
+        if (source === 'limitation')
+            this._tracking.limitations = [];
+    }
+    getCapabilities() {
+        return {
+            styling: {
+                classMap: true,
+                optionRenderer: true,
+                groupHeaderRenderer: true,
+                cssCustomProperties: true,
+                shadowParts: true,
+                globalStyleMirroring: true,
+            },
+            events: {
+                emitted: ['select', 'open', 'close', 'search', 'change', 'loadMore', 'remove', 'clear', 'error', 'diagnostic'],
+                diagnosticEvent: true,
+            },
+            functionality: {
+                multiSelect: true,
+                searchable: true,
+                infiniteScroll: true,
+                loadMore: true,
+                clearControl: true,
+                groupedItems: true,
+                serverSideSelection: true,
+                runtimeModeSwitchMitigation: Boolean(this._config.limitations?.autoMitigateRuntimeModeSwitch),
+            },
+            limitations: this.getKnownLimitations(),
+        };
     }
     _emitChange() {
         const selectedItems = Array.from(this._state.selectedItems.values());
@@ -3693,6 +3868,7 @@ class EnhancedSelect extends HTMLElement {
     set optionRenderer(renderer) {
         this._optionRenderer = renderer;
         this._setGlobalStylesMirroring(Boolean(renderer || this._classMap));
+        this._track('style', 'optionRendererChanged', { enabled: Boolean(renderer) });
         this._renderOptions();
     }
     /**
@@ -3857,7 +4033,22 @@ class EnhancedSelect extends HTMLElement {
      * Update component configuration
      */
     updateConfig(config) {
-        this._config = selectConfig.mergeWithComponentConfig(config);
+        const previousMode = this._config.selection.mode;
+        this._config = this._mergeConfig(this._config, config);
+        if (previousMode !== this._config.selection.mode &&
+            this._config.limitations?.autoMitigateRuntimeModeSwitch) {
+            this.clear();
+            this._track('limitation', 'runtimeModeSwitchMitigated', {
+                from: previousMode,
+                to: this._config.selection.mode,
+            });
+        }
+        else if (previousMode !== this._config.selection.mode) {
+            this._track('limitation', 'runtimeModeSwitchDetected', {
+                from: previousMode,
+                to: this._config.selection.mode,
+            });
+        }
         // Update input state based on new config
         if (this._input) {
             this._input.readOnly = !this._config.searchable;
@@ -3885,6 +4076,22 @@ class EnhancedSelect extends HTMLElement {
         this._syncClearControlState();
         this._renderOptions();
     }
+    _mergeConfig(target, source) {
+        const result = { ...target };
+        for (const key in source) {
+            if (!Object.prototype.hasOwnProperty.call(source, key))
+                continue;
+            const sourceValue = source[key];
+            const targetValue = result[key];
+            if (sourceValue && typeof sourceValue === 'object' && !Array.isArray(sourceValue)) {
+                result[key] = this._mergeConfig(targetValue && typeof targetValue === 'object' ? targetValue : {}, sourceValue);
+            }
+            else {
+                result[key] = sourceValue;
+            }
+        }
+        return result;
+    }
     _handleClearControlClick() {
         const shouldClearSelection = this._config.clearControl.clearSelection !== false;
         const shouldClearSearch = this._config.clearControl.clearSearch !== false;