@prolibu-suite/cobalt-core 0.3.0 → 0.5.0

package/dist/collection/components/co-option-list/co-option-list.js

@@ -0,0 +1,899 @@
+import { h } from "@stencil/core";
+import { highlightMatch } from "../../utils/normalizeText";
+import { initOverlayScroll } from "../../utils/overlayScroll";
+import { buildRows, deriveMore, nextActiveIndex, orderItems, parseItems, parseValue, virtualSlice, VIRTUAL_ITEM_HEIGHT, VIRTUAL_VIEWPORT_ITEMS, } from "./optionListLogic";
+/**
+ * Núcleo de lista de opciones — la única fuente del look & behavior de los
+ * dropdowns Cobalt (co-ref-field, co-combobox, co-autocomplete,
+ * co-command-search) y de los pickers de celda de suite-v2.
+ *
+ * NO renderiza trigger ni chrome de panel (popover/dialog/ancho): eso es del
+ * host. Es 100% controlada: no muta `value`; emite y el host decide.
+ *
+ * @slot footer - Footer del panel (normalmente <co-list-footer>).
+ */
+export class CoOptionList {
+    constructor() {
+        // ── Data (controlada) ──────────────────────────────────────
+        /** JSON string o array de OptionListItem. */
+        this.items = '[]';
+        /** Selección actual: id single o JSON array de ids. */
+        this.value = '';
+        /** Display-items de la selección (para selected-first con ids fuera de página). */
+        this.selectedItems = '[]';
+        this.multiple = false;
+        /** Partición selected-first (snapshot al llamar snapshotOrder()). */
+        this.selectedFirst = false;
+        /** Afford. del seleccionado: check (combobox/autocomplete) o X deselect (ref-field). */
+        this.selectedAffordance = 'check';
+        /** Botón remove por fila seleccionada en multiple (tags de combobox). */
+        this.removableItems = false;
+        // ── Search integrado (opcional) ────────────────────────────
+        this.searchable = false;
+        this.searchPlaceholder = 'Search…';
+        this.searchDebounce = 350;
+        /** Pre-seed del término (modo convert de las celdas). */
+        this.initialTerm = '';
+        // ── Estados ────────────────────────────────────────────────
+        this.loading = false;
+        /** Total del server: deriva hasMore + hint "N more results". */
+        this.total = 0;
+        /** Fallback cuando el host no conoce totales (⌘K). total>0 manda. */
+        this.hasMore = false;
+        this.emptyMessage = 'No results found';
+        /** Si se setea y hay selección, fila "quitar selección" al tope. */
+        this.clearOptionLabel = '';
+        // ── Presentación ───────────────────────────────────────────
+        /** Lista virtualizada (autocomplete/combobox). Ignora `group`. */
+        this.virtual = false;
+        /** Resalta el match del término en los labels. */
+        this.highlightMatches = false;
+        /** Término externo para highlight (input en el host, p.ej. ⌘K). */
+        this.highlightTerm = '';
+        this.avatarShape = 'circle';
+        // ── Navegación ─────────────────────────────────────────────
+        /** Auto-resalta la primera fila navegable al montar y en cada cambio de
+         *  items (paridad command-palette: tipear + Enter = primer resultado).
+         *  Salta filas disabled vía nextActiveIndex. */
+        this.autoHighlight = false;
+        this.term = '';
+        this.activeIndex = -1;
+        this.scrollTop = 0;
+        /** Snapshot selected-first (ver snapshotOrder). */
+        this.sortSnapshot = new Set();
+        this.displaySnapshot = [];
+        /**
+         * Enter sobre un control real (footer, fila clear) activa ese control
+         * nativamente — nunca el highlight (regla heredada de CellRefPicker).
+         */
+        this.onRootKeyDown = (e) => {
+            var _a, _b;
+            if (e.key === 'Enter') {
+                const origin = (((_a = e.composedPath) === null || _a === void 0 ? void 0 : _a.call(e)[0]) || e.target);
+                // `instanceof HTMLElement`, NO `Element`: el decorador `@Element` importado
+                // de `@stencil/core` arriba shadowea el nombre global `Element` en este
+                // módulo, así que `origin instanceof Element` referenciaría el decorador
+                // (siempre false / rompe el narrowing de TS) en vez del DOM Element.
+                if (origin instanceof HTMLElement && ((_b = origin.closest) === null || _b === void 0 ? void 0 : _b.call(origin, 'button:not(.co-option-list__option), co-list-footer')))
+                    return;
+            }
+            if (this.processKey(e.key))
+                e.preventDefault();
+        };
+        this.onSearchInput = (e) => {
+            const v = e.target.value;
+            this.term = v;
+            this.activeIndex = -1;
+            if (this.debounceTimer)
+                clearTimeout(this.debounceTimer);
+            this.debounceTimer = setTimeout(() => this.coSearch.emit(v), this.searchDebounce);
+        };
+        this.onNativeScroll = (e) => {
+            // Fallback pre-OverlayScrollbars (primer frame) — misma lógica.
+            const el = e.target;
+            this.scrollTop = el.scrollTop;
+            this.maybeLoadMore(el.scrollTop, el.clientHeight, el.scrollHeight);
+        };
+    }
+    // ── Parsed ─────────────────────────────────────────────────
+    get parsedItems() { return parseItems(this.items); }
+    get selectedIds() { return parseValue(this.value); }
+    get orderedItems() {
+        if (!this.selectedFirst)
+            return this.parsedItems;
+        return orderItems(this.parsedItems, this.sortSnapshot, this.displaySnapshot, !!this.term);
+    }
+    get effectiveHighlightTerm() {
+        if (!this.highlightMatches)
+            return '';
+        return this.searchable ? this.term : this.highlightTerm;
+    }
+    // ── Lifecycle ──────────────────────────────────────────────
+    componentWillLoad() {
+        this.term = this.initialTerm || '';
+        this.takeSnapshot();
+        if (this.autoHighlight)
+            this.activeIndex = nextActiveIndex(-1, 1, this.orderedItems);
+    }
+    componentDidRender() {
+        // OverlayScrollbars sobre el contenedor; wrapper interno estable para que
+        // Stencil pueda seguir agregando filas (infinite scroll) sin pelear con
+        // la reestructuración de DOM de OS (patrón co-ref-field).
+        if (this.optionsEl && !this.osInstance) {
+            this.osInstance = initOverlayScroll(this.optionsEl, (vp) => {
+                this.scrollTop = vp.scrollTop;
+                this.maybeLoadMore(vp.scrollTop, vp.clientHeight, vp.scrollHeight);
+            });
+        }
+    }
+    disconnectedCallback() {
+        var _a;
+        if (this.debounceTimer)
+            clearTimeout(this.debounceTimer);
+        (_a = this.osInstance) === null || _a === void 0 ? void 0 : _a.destroy();
+        this.osInstance = undefined;
+    }
+    onItemsChange() {
+        // Nueva página / nuevos resultados: si autoHighlight, re-resalta la primera fila
+        // navegable (paridad command-palette); si no, solo resetea cuando el highlight
+        // quedó fuera de rango.
+        if (this.autoHighlight) {
+            this.activeIndex = nextActiveIndex(-1, 1, this.orderedItems);
+        }
+        else if (this.activeIndex >= this.orderedItems.length) {
+            this.activeIndex = -1;
+        }
+        // Clamp defensivo del scroll virtual: si la nueva lista es más corta que el
+        // scrollTop actual (p.ej. búsqueda que redujo drásticamente el resultset),
+        // reencuadra dentro de rango. NO resetear a 0 incondicionalmente — eso
+        // rompería el infinite scroll por append (la lista crece hacia abajo y el
+        // usuario sigue viendo su posición de scroll).
+        const maxScrollTop = Math.max(0, this.orderedItems.length * VIRTUAL_ITEM_HEIGHT - VIRTUAL_VIEWPORT_ITEMS * VIRTUAL_ITEM_HEIGHT);
+        if (this.scrollTop > this.orderedItems.length * VIRTUAL_ITEM_HEIGHT) {
+            this.scrollTop = maxScrollTop;
+        }
+    }
+    // ── Métodos públicos ───────────────────────────────────────
+    /** Re-toma el snapshot selected-first. El host la llama al abrir su panel. */
+    async snapshotOrder() {
+        this.takeSnapshot();
+    }
+    /**
+     * Enfoca el input de búsqueda esperando visibilidad real: el panel del host
+     * se vuelve visible frames después (showPopover/position en rAF) y focus()
+     * sobre subtree oculto es no-op silencioso. Reintenta ~20 frames.
+     */
+    async focusSearch() {
+        var _a, _b;
+        for (let i = 0; i < 20; i++) {
+            (_a = this.searchInputEl) === null || _a === void 0 ? void 0 : _a.focus();
+            if (this.searchInputEl && ((_b = this.el.shadowRoot) === null || _b === void 0 ? void 0 : _b.activeElement) === this.searchInputEl)
+                return;
+            await new Promise((resolve) => requestAnimationFrame(() => resolve()));
+        }
+    }
+    /** Navegación para hosts con input externo. true = tecla consumida (host hace preventDefault). */
+    async handleKey(e) {
+        return this.processKey(e.key);
+    }
+    // ── Internos ───────────────────────────────────────────────
+    takeSnapshot() {
+        this.sortSnapshot = new Set(this.selectedIds);
+        const byId = new Map();
+        for (const it of parseItems(this.selectedItems))
+            byId.set(it._id, it);
+        for (const it of this.parsedItems)
+            if (!byId.has(it._id))
+                byId.set(it._id, it);
+        this.displaySnapshot = this.selectedIds
+            .map((id) => byId.get(id))
+            .filter(Boolean);
+    }
+    processKey(key) {
+        const items = this.orderedItems;
+        switch (key) {
+            case 'ArrowDown':
+                this.activeIndex = nextActiveIndex(this.activeIndex, 1, items);
+                this.scrollActiveIntoView();
+                return true;
+            case 'ArrowUp':
+                this.activeIndex = nextActiveIndex(this.activeIndex, -1, items);
+                this.scrollActiveIntoView();
+                return true;
+            case 'Enter': {
+                // Enter con un fetch in-flight pickearía de la lista STALE (race
+                // detectada en smoke: el usuario teclea y confirma antes de que
+                // lleguen los resultados). Se consume sin actuar; el siguiente
+                // Enter opera sobre la lista fresca.
+                if (this.loading)
+                    return true;
+                const item = items[this.activeIndex];
+                if (item && !item.disabled) {
+                    this.pick(item);
+                    return true;
+                }
+                return false;
+            }
+            default:
+                return false;
+        }
+    }
+    pick(item) {
+        if (this.multiple) {
+            const current = this.selectedIds;
+            const idx = current.indexOf(item._id);
+            const next = idx >= 0 ? current.filter((id) => id !== item._id) : [...current, item._id];
+            this.coChange.emit({ value: next, item });
+        }
+        else {
+            this.coChange.emit({ value: item._id, item });
+        }
+    }
+    maybeLoadMore(scrollTop, clientHeight, scrollHeight) {
+        if (this.loading)
+            return;
+        const { hasMore } = deriveMore(this.parsedItems.length, this.total, this.hasMore);
+        if (hasMore && scrollTop + clientHeight >= scrollHeight - 40)
+            this.coLoadMore.emit();
+    }
+    scrollActiveIntoView() {
+        requestAnimationFrame(() => {
+            var _a, _b;
+            (_b = (_a = this.el.shadowRoot) === null || _a === void 0 ? void 0 : _a.getElementById(`co-optlist-${this.activeIndex}`)) === null || _b === void 0 ? void 0 : _b.scrollIntoView({ block: 'nearest' });
+        });
+    }
+    // ── Render helpers ─────────────────────────────────────────
+    renderLeading(item) {
+        if (item.image || item.avatar) {
+            return (h("co-avatar", { class: "co-option-list__avatar", type: item.image ? 'image' : 'text', src: item.image, text: item.avatar, color: item.color, size: "xxs", shape: this.avatarShape }));
+        }
+        if (item.color)
+            return h("span", { class: "co-option-list__dot", style: { backgroundColor: item.color } });
+        if (item.icon)
+            return h("co-icon", { name: item.icon, size: 16, class: "co-option-list__icon" });
+        return null;
+    }
+    renderLabelText(label) {
+        const term = this.effectiveHighlightTerm;
+        const seg = term ? highlightMatch(label, term) : null;
+        if (!seg)
+            return label;
+        return [seg.pre, h("span", { class: "co-option-list__match" }, seg.match), seg.post];
+    }
+    renderRow(item, index, selectedIds) {
+        const isSelected = selectedIds.includes(item._id);
+        return (h("div", { class: {
+                'co-option-list__option': true,
+                'co-option-list__option--selected': isSelected,
+                'co-option-list__option--active': index === this.activeIndex,
+                'co-option-list__option--disabled': !!item.disabled,
+            }, key: item._id, id: `co-optlist-${index}`, role: "option", "aria-selected": isSelected ? 'true' : 'false', "aria-disabled": item.disabled ? 'true' : 'false', onClick: () => !item.disabled && this.pick(item), onMouseEnter: () => { this.activeIndex = index; } }, this.renderLeading(item), h("div", { class: "co-option-list__text" }, h("span", { class: "co-option-list__title" }, h("span", { class: "co-option-list__label", style: item.labelColor ? { color: item.labelColor, fontWeight: '600' } : undefined }, this.renderLabelText(item.label)), item.suffix && h("span", { class: "co-option-list__suffix" }, "- ", item.suffix), item.badge && (h("span", { class: "co-option-list__badge", style: item.badge.color ? { backgroundColor: item.badge.color, color: 'var(--co-color-base-blanco, #fff)' } : undefined }, item.badge.label))), item.description && h("span", { class: "co-option-list__desc" }, item.description)), isSelected && this.removableItems && this.multiple && (h("button", { class: "co-option-list__row-action", type: "button", tabIndex: -1, "aria-label": `Remove ${item.label}`, onClick: (e) => { e.stopPropagation(); this.coRemoveItem.emit(item._id); } }, h("co-icon", { name: "x-circle", size: 16, weight: "fill" }))), isSelected && !this.removableItems && this.selectedAffordance === 'deselect' && (h("button", { class: "co-option-list__row-action", type: "button", tabIndex: -1, "aria-label": `Deselect ${item.label}`, onClick: (e) => { e.stopPropagation(); this.pick(item); } }, h("co-icon", { name: "x-circle", size: 16, weight: "fill" }))), isSelected && !this.removableItems && this.selectedAffordance === 'check' && (h("co-icon", { name: "check", size: 16, class: "co-option-list__check" }))));
+    }
+    renderVirtual(items, selectedIds) {
+        const { totalHeight, startIdx, endIdx, offsetY } = virtualSlice(this.scrollTop, items.length);
+        return (h("div", { class: "co-option-list__spacer", style: { height: `${totalHeight}px`, position: 'relative' } }, h("div", { style: { position: 'absolute', top: `${offsetY}px`, left: '0', right: '0' } }, items.slice(startIdx, endIdx).map((item, i) => this.renderRow(item, startIdx + i, selectedIds)))));
+    }
+    render() {
+        const items = this.orderedItems;
+        const selectedIds = this.selectedIds;
+        const { hasMore, remaining } = deriveMore(this.parsedItems.length, this.total, this.hasMore);
+        const showClear = !!this.clearOptionLabel && selectedIds.length > 0;
+        return (h("div", { key: 'f6262519bd90bb9a419daeb9a1386147396a79ff', class: "co-option-list", onKeyDown: this.onRootKeyDown }, this.searchable && (h("div", { key: '081a2cfee9a8a903c6bd2a2f0bd06cbac635c021', class: "co-option-list__search", part: "search" }, h("co-icon", { key: 'a001c71f5de00288907cde1e123f8d393e052a9e', name: "magnifying-glass", size: 16 }), h("input", { key: '355520b7d77077e02666fcd5012f36c648eaeacf', class: "co-option-list__search-input", type: "text", placeholder: this.searchPlaceholder, value: this.term, onInput: this.onSearchInput, ref: (el) => (this.searchInputEl = el), role: "combobox", "aria-expanded": "true", "aria-autocomplete": "list" }))), h("div", { key: '833708f614d3f561ba45bf1656f4bcfa6701b8ce', class: "co-option-list__options", part: "options", role: "listbox", "aria-multiselectable": this.multiple ? 'true' : 'false', ref: (el) => (this.optionsEl = el), onScroll: this.onNativeScroll }, h("div", { key: '10da99a56133af0748f43c20af62e03e975aebcd', class: "co-option-list__inner" }, showClear && (h("button", { key: '208bc13eb8e89c88657022fbc174bb22ffe9e1c4', class: "co-option-list__clear-row", type: "button", onClick: () => this.coClearSelection.emit() }, h("co-icon", { key: '8c6d29e405a12e53bd3ab9f1662c7237bcae0617', name: "x-circle", size: 14 }), h("span", { key: 'd7e11cc7753c8dd63ae6a556bf5368c01ea1fc2a' }, this.clearOptionLabel))), this.loading && items.length === 0 && (h("div", { key: 'dec374969fe6b401a95d60d101cc625c181f3e72', class: "co-option-list__loading" }, h("co-loader", { key: 'c1547fc0f49911f2f8ab8b85063bf15af6500314', size: "sm" }))), !this.loading && items.length === 0 && (h("div", { key: '1e0692572f89d4f9507f1e4b8c4ef90f9f8d307c', class: "co-option-list__empty" }, h("co-icon", { key: 'ff979119305afdd7b2180336c203ff33adc3c463', name: "magnifying-glass", size: 20 }), h("span", { key: '9d460743d6edf7734012d75cabb0f488b67d20cf' }, this.emptyMessage))), items.length > 0 && this.virtual
+            ? this.renderVirtual(items, selectedIds)
+            : buildRows(items).map((row) => row.kind === 'header'
+                ? h("div", { class: "co-option-list__group", role: "presentation" }, row.label)
+                : this.renderRow(row.item, row.index, selectedIds)), this.loading && items.length > 0 && (h("div", { key: 'f9c506fddfba9d360a7dd4b2d4ed4142aaa179c5', class: "co-option-list__loading-more" }, h("co-loader", { key: '587d93ebd03eb3764e5637c748975c925d1bd59f', size: "sm" }))), !this.loading && hasMore && remaining > 0 && (h("div", { key: 'cef0c72b2aa1f246404001bae6c8ee4ea560ee07', class: "co-option-list__more" }, remaining, " more results")))), h("slot", { key: '646b6421fb03008d55e5361e14f12d05db08e299', name: "footer" })));
+    }
+    static get is() { return "co-option-list"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["co-option-list.css"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["co-option-list.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "items": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | OptionListItem[]",
+                    "resolved": "OptionListItem[] | string",
+                    "references": {
+                        "OptionListItem": {
+                            "location": "import",
+                            "path": "./optionListLogic",
+                            "id": "src/components/co-option-list/optionListLogic.ts::OptionListItem",
+                            "referenceLocation": "OptionListItem"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "JSON string o array de OptionListItem."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "items",
+                "defaultValue": "'[]'"
+            },
+            "value": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Selecci\u00F3n actual: id single o JSON array de ids."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "value",
+                "defaultValue": "''"
+            },
+            "selectedItems": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | OptionListItem[]",
+                    "resolved": "OptionListItem[] | string",
+                    "references": {
+                        "OptionListItem": {
+                            "location": "import",
+                            "path": "./optionListLogic",
+                            "id": "src/components/co-option-list/optionListLogic.ts::OptionListItem",
+                            "referenceLocation": "OptionListItem"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Display-items de la selecci\u00F3n (para selected-first con ids fuera de p\u00E1gina)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "selected-items",
+                "defaultValue": "'[]'"
+            },
+            "multiple": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "multiple",
+                "defaultValue": "false"
+            },
+            "selectedFirst": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Partici\u00F3n selected-first (snapshot al llamar snapshotOrder())."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "selected-first",
+                "defaultValue": "false"
+            },
+            "selectedAffordance": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'check' | 'deselect'",
+                    "resolved": "\"check\" | \"deselect\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Afford. del seleccionado: check (combobox/autocomplete) o X deselect (ref-field)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "selected-affordance",
+                "defaultValue": "'check'"
+            },
+            "removableItems": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Bot\u00F3n remove por fila seleccionada en multiple (tags de combobox)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "removable-items",
+                "defaultValue": "false"
+            },
+            "searchable": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "searchable",
+                "defaultValue": "false"
+            },
+            "searchPlaceholder": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "search-placeholder",
+                "defaultValue": "'Search\u2026'"
+            },
+            "searchDebounce": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "search-debounce",
+                "defaultValue": "350"
+            },
+            "initialTerm": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Pre-seed del t\u00E9rmino (modo convert de las celdas)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "initial-term",
+                "defaultValue": "''"
+            },
+            "loading": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "loading",
+                "defaultValue": "false"
+            },
+            "total": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Total del server: deriva hasMore + hint \"N more results\"."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "total",
+                "defaultValue": "0"
+            },
+            "hasMore": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Fallback cuando el host no conoce totales (\u2318K). total>0 manda."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "has-more",
+                "defaultValue": "false"
+            },
+            "emptyMessage": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "empty-message",
+                "defaultValue": "'No results found'"
+            },
+            "clearOptionLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Si se setea y hay selecci\u00F3n, fila \"quitar selecci\u00F3n\" al tope."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "clear-option-label",
+                "defaultValue": "''"
+            },
+            "virtual": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Lista virtualizada (autocomplete/combobox). Ignora `group`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "virtual",
+                "defaultValue": "false"
+            },
+            "highlightMatches": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Resalta el match del t\u00E9rmino en los labels."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "highlight-matches",
+                "defaultValue": "false"
+            },
+            "highlightTerm": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "T\u00E9rmino externo para highlight (input en el host, p.ej. \u2318K)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "highlight-term",
+                "defaultValue": "''"
+            },
+            "avatarShape": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'circle' | 'square'",
+                    "resolved": "\"circle\" | \"square\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "avatar-shape",
+                "defaultValue": "'circle'"
+            },
+            "autoHighlight": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Auto-resalta la primera fila navegable al montar y en cada cambio de\nitems (paridad command-palette: tipear + Enter = primer resultado).\nSalta filas disabled v\u00EDa nextActiveIndex."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "auto-highlight",
+                "defaultValue": "false"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "term": {},
+            "activeIndex": {},
+            "scrollTop": {}
+        };
+    }
+    static get events() {
+        return [{
+                "method": "coSearch",
+                "name": "coSearch",
+                "bubbles": false,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                }
+            }, {
+                "method": "coChange",
+                "name": "coChange",
+                "bubbles": false,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "{ value: string | string[]; item: OptionListItem }",
+                    "resolved": "{ value: string | string[]; item: OptionListItem; }",
+                    "references": {
+                        "OptionListItem": {
+                            "location": "import",
+                            "path": "./optionListLogic",
+                            "id": "src/components/co-option-list/optionListLogic.ts::OptionListItem",
+                            "referenceLocation": "OptionListItem"
+                        }
+                    }
+                }
+            }, {
+                "method": "coLoadMore",
+                "name": "coLoadMore",
+                "bubbles": false,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "coClearSelection",
+                "name": "coClearSelection",
+                "bubbles": false,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "void",
+                    "resolved": "void",
+                    "references": {}
+                }
+            }, {
+                "method": "coRemoveItem",
+                "name": "coRemoveItem",
+                "bubbles": false,
+                "cancelable": true,
+                "composed": true,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                }
+            }];
+    }
+    static get methods() {
+        return {
+            "snapshotOrder": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Re-toma el snapshot selected-first. El host la llama al abrir su panel.",
+                    "tags": []
+                }
+            },
+            "focusSearch": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Enfoca el input de b\u00FAsqueda esperando visibilidad real: el panel del host\nse vuelve visible frames despu\u00E9s (showPopover/position en rAF) y focus()\nsobre subtree oculto es no-op silencioso. Reintenta ~20 frames.",
+                    "tags": []
+                }
+            },
+            "handleKey": {
+                "complexType": {
+                    "signature": "(e: KeyboardEvent) => Promise<boolean>",
+                    "parameters": [{
+                            "name": "e",
+                            "type": "KeyboardEvent",
+                            "docs": ""
+                        }],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        },
+                        "KeyboardEvent": {
+                            "location": "global",
+                            "id": "global::KeyboardEvent"
+                        }
+                    },
+                    "return": "Promise<boolean>"
+                },
+                "docs": {
+                    "text": "Navegaci\u00F3n para hosts con input externo. true = tecla consumida (host hace preventDefault).",
+                    "tags": []
+                }
+            }
+        };
+    }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "items",
+                "methodName": "onItemsChange"
+            }];
+    }
+}