@smilodon/core 1.4.10 → 1.4.12

package/README.md

@@ -610,6 +610,11 @@ Dark mode is **opt-in only** and can be enabled by adding a class or data attrib
 
 <!-- Using data attribute -->
 <enhanced-select data-theme="dark"></enhanced-select>
+
+<!-- Also supported (attribute aliases) -->
+<enhanced-select dark-mode></enhanced-select>
+<enhanced-select darkmode></enhanced-select>
+<enhanced-select theme="dark"></enhanced-select>
 ```
 
 ```css
@@ -631,6 +636,8 @@ enhanced-select.dark-mode {
 **Light Mode (Default)**
 ```css
 --select-options-bg           /* Options container background (white) */
+--select-width                /* Host width (100% default) */
+--select-height               /* Host height (auto default) */
 --select-option-color          /* Option text color (#1f2937) */
 --select-option-bg             /* Option background (white) */
 --select-option-padding        /* Option padding (8px 12px) */
@@ -643,6 +650,8 @@ enhanced-select.dark-mode {
 --select-option-selected-hover-border /* Selected+hover border (inherits selected border by default) */
 --select-option-active-bg      /* Active background (#f3f4f6) */
 --select-option-active-color   /* Active text color (#1f2937) */
+--select-input-width           /* Input field width */
+--select-input-height          /* Input container height */
 --select-dropdown-bg           /* Dropdown background (white) */
 --select-dropdown-border       /* Dropdown border color (#ccc) */
 --select-dropdown-shadow       /* Dropdown shadow */
@@ -665,9 +674,17 @@ enhanced-select.dark-mode {
 --select-group-header-color    /* Text color (#6b7280) */
 --select-group-header-bg       /* Background (#f3f4f6) */
 --select-group-header-font-size
+--select-group-header-text-align /* Header text alignment (left default) */
 --select-group-header-text-transform
 --select-group-header-letter-spacing
 --select-group-header-border-bottom
+
+/* Option content and checkmark hooks */
+--select-option-content-overflow
+--select-option-content-text-overflow
+--select-option-content-white-space
+--select-checkmark-margin-left
+--select-checkmark-color
 ```
 
 **Dark Mode (Opt-in)**
@@ -717,8 +734,19 @@ enhanced-select {
     transparent 100%
   );
 }
+
+/* Typo-compatible aliases are also accepted */
+enhanced-select {
+  --select-seperator-width: 2px;
+  --select-seperator-height: 80%;
+  --select-seperator-position: 40px;
+  --select-seperator-gradient: linear-gradient(to bottom, transparent 0%, #3b82f6 20%, #3b82f6 80%, transparent 100%);
+}
 ```
 
+**Gradient Dropdown + Hover/Selected States**
+If your dropdown uses a gradient background (for example via `--select-dropdown-bg`), option hover/selected colors still work as expected. The component intentionally uses the `background` shorthand for hover/selected option states so any inherited `background-image` layers are cleared correctly.
+
 **Badge Remove/Delete Button (Multi-Select)**
 The × button that removes selected items in multi-select mode is fully customizable:
 

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...',
@@ -1534,6 +1546,8 @@ class SelectOption extends HTMLElement {
         padding: var(--select-option-padding, 8px 12px);
         cursor: pointer;
         user-select: none;
+        color: var(--select-option-color, var(--select-text-color, #1f2937));
+        background: var(--select-option-bg, var(--select-dropdown-bg, var(--select-bg, white)));
         transition: var(--select-option-transition, background-color 0.2s ease);
         border: var(--select-option-border, none);
         border-bottom: var(--select-option-border-bottom, none);
@@ -1578,9 +1592,20 @@ class SelectOption extends HTMLElement {
       
       .option-content {
         flex: 1;
-        overflow: hidden;
-        text-overflow: ellipsis;
-        white-space: nowrap;
+        overflow: var(--select-option-content-overflow, hidden);
+        text-overflow: var(--select-option-content-text-overflow, ellipsis);
+        white-space: var(--select-option-content-white-space, nowrap);
+      }
+
+      .checkmark-icon {
+        display: none;
+        margin-left: var(--select-checkmark-margin-left, 8px);
+        color: var(--select-checkmark-color, currentColor);
+      }
+
+      :host([aria-selected="true"]) .checkmark-icon,
+      .option-container.selected .checkmark-icon {
+        display: inline-flex;
       }
       
       .remove-button {
@@ -1708,16 +1733,6 @@ class SelectOption extends HTMLElement {
             <path d="M4 8.5L6.5 11L12 5.5" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>
           </svg>
         `;
-            // Visibility control via CSS or inline style
-            // We set it to display: none unless selected.
-            // User can override this behavior via part styling if they want transitions
-            if (!selected) {
-                checkmark.style.display = 'none';
-            }
-            else {
-                checkmark.style.marginLeft = '8px';
-                checkmark.style.color = 'currentColor';
-            }
             this._container.appendChild(checkmark);
         }
         // Data Attributes Contract on Host
@@ -1876,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();
@@ -1891,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();
@@ -1909,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();
@@ -1955,7 +1976,6 @@ class EnhancedSelect extends HTMLElement {
         // Angular's rendering seems to not apply :host styles correctly in some cases
         // Must be done in connectedCallback when element is attached to DOM
         this.style.display = 'block';
-        this.style.width = '100%';
         if (this._optionRenderer) {
             this._setGlobalStylesMirroring(true);
         }
@@ -1994,6 +2014,7 @@ class EnhancedSelect extends HTMLElement {
             return;
         }
         this._mirrorGlobalStylesForCustomOptions = enabled;
+        this._track('style', 'globalStylesMirroringChanged', { enabled });
         if (enabled) {
             this._setupGlobalStylesMirroring();
         }
@@ -2198,7 +2219,8 @@ class EnhancedSelect extends HTMLElement {
       :host {
         display: block;
         position: relative;
-        width: 100%;
+        width: var(--select-width, 100%);
+        height: var(--select-height, auto);
       }
       
       .select-container {
@@ -2214,6 +2236,7 @@ class EnhancedSelect extends HTMLElement {
         flex-wrap: wrap;
         gap: var(--select-input-gap, 6px);
         padding: var(--select-input-padding, 6px 52px 6px 8px);
+        height: var(--select-input-height, auto);
         min-height: var(--select-input-min-height, 44px);
         max-height: var(--select-input-max-height, 160px);
         overflow-y: var(--select-input-overflow-y, auto);
@@ -2235,17 +2258,17 @@ class EnhancedSelect extends HTMLElement {
         content: '';
         position: absolute;
         top: 50%;
-        right: var(--select-separator-position, 40px);
+        right: var(--select-separator-position, var(--select-seperator-position, 40px));
         transform: translateY(-50%);
-        width: var(--select-separator-width, 1px);
-        height: var(--select-separator-height, 60%);
-        background: var(--select-separator-bg, var(--select-separator-gradient, linear-gradient(
+        width: var(--select-separator-width, var(--select-seperator-width, 1px));
+        height: var(--select-separator-height, var(--select-seperator-height, 60%));
+        background: var(--select-separator-bg, var(--select-seperator-bg, var(--select-separator-gradient, var(--select-seperator-gradient, linear-gradient(
           to bottom,
           transparent 0%,
           rgba(0, 0, 0, 0.1) 20%,
           rgba(0, 0, 0, 0.1) 80%,
           transparent 100%
-        )));
+        ))));
         pointer-events: none;
         z-index: 1;
       }
@@ -2272,7 +2295,7 @@ class EnhancedSelect extends HTMLElement {
       }
 
       .input-container.has-clear-control::after {
-        right: var(--select-separator-position-with-clear, 72px);
+        right: var(--select-separator-position-with-clear, var(--select-seperator-position-with-clear, 72px));
       }
 
       .dropdown-arrow-container.with-clear-control {
@@ -2350,6 +2373,7 @@ class EnhancedSelect extends HTMLElement {
       
       .select-input {
         flex: 1;
+        width: var(--select-input-width, auto);
         min-width: var(--select-input-min-width, 120px);
         padding: var(--select-input-field-padding, 4px);
         border: none;
@@ -2444,6 +2468,7 @@ class EnhancedSelect extends HTMLElement {
         font-weight: var(--select-group-header-weight, 600);
         color: var(--select-group-header-color, #6b7280);
         background-color: var(--select-group-header-bg, #f3f4f6);
+        text-align: var(--select-group-header-text-align, left);
         font-size: var(--select-group-header-font-size, 12px);
         text-transform: var(--select-group-header-text-transform, uppercase);
         letter-spacing: var(--select-group-header-letter-spacing, 0.05em);
@@ -2628,10 +2653,25 @@ class EnhancedSelect extends HTMLElement {
       
       /* Dark mode - Opt-in via class, data attribute, or ancestor context */
       :host(.dark-mode),
+      :host([dark-mode]),
+      :host([darkmode]),
       :host([data-theme="dark"]),
+      :host([theme="dark"]),
       :host-context(.dark-mode),
       :host-context(.dark),
-      :host-context([data-theme="dark"]) {
+      :host-context([dark-mode]),
+      :host-context([darkmode]),
+      :host-context([data-theme="dark"]),
+      :host-context([theme="dark"]) {
+        /* map dark tokens to base option tokens so nested <select-option>
+           components also pick up dark mode via inherited CSS variables */
+        --select-option-bg: var(--select-dark-option-bg, #1f2937);
+        --select-option-color: var(--select-dark-option-color, #f9fafb);
+        --select-option-hover-bg: var(--select-dark-option-hover-bg, #374151);
+        --select-option-hover-color: var(--select-dark-option-hover-color, #f9fafb);
+        --select-option-selected-bg: var(--select-dark-option-selected-bg, #3730a3);
+        --select-option-selected-color: var(--select-dark-option-selected-text, #e0e7ff);
+
         .input-container {
           background: var(--select-dark-bg, #1f2937);
           border-color: var(--select-dark-border, #4b5563);
@@ -2684,6 +2724,8 @@ class EnhancedSelect extends HTMLElement {
         
         .option.active:not(.selected) {
           background-color: var(--select-dark-option-active-bg, #374151);
+          color: var(--select-dark-option-active-color, #f9fafb);
+          outline: var(--select-dark-option-active-outline, 2px solid rgba(129, 140, 248, 0.55));
         }
 
         /* Group header in dark mode */
@@ -2691,9 +2733,6 @@ class EnhancedSelect extends HTMLElement {
           color: var(--select-dark-group-header-color, var(--select-group-header-color, #6b7280));
           background-color: var(--select-dark-group-header-bg, var(--select-group-header-bg, #374151));
         }
-          color: var(--select-dark-option-active-color, #f9fafb);
-          outline: var(--select-dark-option-active-outline, 2px solid rgba(129, 140, 248, 0.55));
-        }
 
         .option.selected.active {
           background-color: var(--select-dark-option-selected-active-bg, var(--select-dark-option-selected-bg, #3730a3));
@@ -2815,7 +2854,13 @@ class EnhancedSelect extends HTMLElement {
                 this._handleOpen();
             }
             else {
-                // clicking the input while open should close the dropdown too
+                // Keep open while interacting directly with the input so users can
+                // place cursor/type without accidental collapse.
+                if (target === this._input) {
+                    this._input.focus();
+                    return;
+                }
+                // clicking other parts of the input container while open toggles close
                 this._handleClose();
             }
             // Focus the input (do not prevent default behavior)
@@ -3650,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());
@@ -3667,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();
     }
     /**
@@ -3831,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;
@@ -3859,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;