@smilodon/core 1.4.11 → 1.4.12

package/dist/index.umd.js

@@ -1407,6 +1407,18 @@
             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...',
@@ -1883,6 +1895,10 @@
         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();
@@ -1898,6 +1914,7 @@
         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();
@@ -1916,6 +1933,7 @@
             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();
@@ -2000,6 +2018,7 @@
                 return;
             }
             this._mirrorGlobalStylesForCustomOptions = enabled;
+            this._track('style', 'globalStylesMirroringChanged', { enabled });
             if (enabled) {
                 this._setupGlobalStylesMirroring();
             }
@@ -3680,6 +3699,162 @@
         }
         _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());
@@ -3697,6 +3872,7 @@
         set optionRenderer(renderer) {
             this._optionRenderer = renderer;
             this._setGlobalStylesMirroring(Boolean(renderer || this._classMap));
+            this._track('style', 'optionRendererChanged', { enabled: Boolean(renderer) });
             this._renderOptions();
         }
         /**
@@ -3861,7 +4037,22 @@
          * 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;
@@ -3889,6 +4080,22 @@
             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;