@prolibu-suite/cobalt-core 0.10.4 → 0.11.1

package/dist/collection/components/co-select/co-select.js

@@ -2,28 +2,61 @@ import { h } from "@stencil/core";
 import { RequiredMark } from "../../utils/requiredMark";
 import { OverlayScrollbars } from "overlayscrollbars";
 import { highlightSegments, rankByMatch } from "../../utils/normalizeText";
+import { LEGACY_ROW_METRICS, resolveRowMetrics, scrollTopToReveal, virtualSlice } from "./virtualRows";
+/**
+ * Selector desplegable de una o varias opciones de una lista conocida, con
+ * búsqueda opcional del lado del cliente y lista virtualizada. Para opciones que
+ * vienen paginadas del servidor usá `co-ref-field`. Wrapper Vue: `CoSelect` de
+ * `@prolibu-suite/cobalt-vue`.
+ */
 export class CoSelect {
     constructor() {
         /** Whether the field is required (renders a required marker on the label). */
         this.required = false;
+        /** Texto del trigger sin selección. */
         this.placeholder = 'Select…';
+        /** Deshabilita el campo. */
         this.disabled = false;
+        /** Botón × para vaciar la selección cuando hay valor; emite `coClear` y `coChange`. */
         this.clearable = false;
         /** Label layout: vertical (label above) or horizontal (label beside) */
         this.layout = 'vertical';
+        /** Estado de validación: pinta el borde y el `helperText` con el color del estado. */
         this.status = 'default';
+        /** Opciones: array de `{ value, label, icon?, image?, disabled? }`, array de strings
+         *  (value = label), o ese mismo array como JSON desde HTML. */
         this.options = '[]';
+        /** Selección: el `value` de la opción en single; en `multiple`, array o JSON array.
+         *  `''` significa «sin selección» (una opción con `value: ''` no se puede marcar).
+         *  El componente lo actualiza al elegir. */
         this.value = '';
+        /** Selección múltiple: el panel queda abierto y `value`/`coChange` llevan un array. */
         this.multiple = false;
+        /** Alto del trigger: `xs` 24 · `s` 28 · `sm` 32 · `md` 40 (default) · `lg` 48. Un valor fuera de la lista cae al default. */
         this.size = 'md';
         /** Visual style. `flat` strips the trigger's border and background so it
          *  reads as plain content instead of a boxed control — padding, label,
-         *  focus ring, disabled and status states are unaffected. `default` (the
-         *  standard bordered box) renders identically to before this prop existed. */
+         *  focus ring, disabled and status states are unaffected. `soft` pinta un
+         *  fondo `gray-100` sólido con borde transparente (mismo grosor que el
+         *  default, no cambia el tamaño de la caja). `default` (the standard
+         *  bordered box) renders identically to before this prop existed. */
         this.variant = 'default';
+        /** Layout de la fila de etiqueta. `inline-help` la muestra en una sola fila
+         *  (`label` a la izquierda, `secondaryLabel` a la derecha, alineados a la
+         *  línea de base) y ajusta el borde/gap del trigger para ese contexto
+         *  (modal). `default` mantiene el layout actual (labels apiladas arriba,
+         *  centradas verticalmente entre sí). */
+        this.labelStyle = 'default';
+        /** Superficie del panel desplegable. `dark` = fondo `surface-primary` +
+         *  texto `text-inverse`, con el check de la opción seleccionada al
+         *  INICIO (hueco siempre reservado, como `co-menu-item leadingCheck`).
+         *  `light` (default) conserva el panel y el check al final tal cual hoy. */
+        this.menuSurface = 'light';
         /** Show a search box inside the dropdown to filter options client-side. */
         this.searchable = false;
+        /** Placeholder del buscador del panel (`searchable`). */
         this.searchPlaceholder = 'Search…';
+        /** Texto del panel cuando la búsqueda no encuentra opciones. */
         this.emptyText = 'No results';
         /** Footer de confirmación al pie del panel (paridad co-combobox/co-ref-field). */
         this.showFooter = false;
@@ -39,12 +72,41 @@ export class CoSelect {
          *  Patrón APG de combobox: el foco NUNCA baja a las opciones — queda en el
          *  trigger (o en el search input) y esto viaja por `aria-activedescendant`. */
         this.activeIndex = -1;
+        /** Alto y hueco de fila con los que virtualiza la lista. Se leen de los knobs
+         *  del menú (`--co-select-option-height`, `--co-select-menu-gap`) en cada
+         *  apertura; sin knobs, el paso histórico de 34 (ver `virtualRows.ts`). */
+        this.rowMetrics = LEGACY_ROW_METRICS;
         /** Scroll pendiente hacia la opción activa, resuelto en componentDidRender. */
         this.pendingActiveScroll = false;
         this.activeScrollFrames = 0;
         this.lastParsedOptions = [];
         this.lastRankSearch = '';
         this.lastRanked = [];
+        /** Valor en px de una custom property heredada por el host, o `null` si no
+         *  está seteada o no resuelve a px. El caso común (`12px`, o un token `--co-*`
+         *  en px, que ya llega sustituido) se lee directo; cualquier otra forma
+         *  (`calc()`, `rem`…) la resuelve el motor CSS sobre un nodo de prueba
+         *  `display: none` que vive solo durante la lectura. */
+        this.readCssLengthPx = (cssVar) => {
+            if (typeof getComputedStyle !== 'function')
+                return null;
+            const raw = getComputedStyle(this.el).getPropertyValue(cssVar).trim();
+            if (!raw)
+                return null;
+            const px = /^(-?\d*\.?\d+)px$/.exec(raw);
+            if (px)
+                return parseFloat(px[1]);
+            const root = this.el.shadowRoot;
+            if (!root)
+                return null;
+            const probe = document.createElement('div');
+            probe.style.display = 'none';
+            probe.style.setProperty('height', `var(${cssVar})`);
+            root.appendChild(probe);
+            const resolved = getComputedStyle(probe).height;
+            probe.remove();
+            return /px$/.test(resolved) ? parseFloat(resolved) : null;
+        };
         this.handleSearchInput = (e) => {
             this.searchText = e.target.value;
             this.scrollTop = 0;
@@ -128,6 +190,24 @@ export class CoSelect {
             e.preventDefault();
             return true;
         };
+        /** El puntero MUEVE la activa: hay un solo resaltado, el de `--active`, y el
+         *  CSS ya no pinta `:hover` en las filas. Con los dos canales se veían DOS
+         *  filas resaltadas a la vez (la activa por teclado y la de abajo del mouse).
+         *
+         *  `pointermove` y no `mouseenter`/`mouseover`: cuando el TECLADO scrollea la
+         *  lista bajo un mouse quieto, el navegador actualiza el hover y dispara esos
+         *  eventos de borde, pero no un `pointermove` — la activa del teclado no se la
+         *  roba una fila que pasó por debajo del cursor (medido en Chromium).
+         *
+         *  Sin `scrollActiveIntoView`: la fila ya está bajo el puntero, scrollear la
+         *  haría saltar. El toque no cuenta: arrastrar el dedo es scrollear. Una fila
+         *  deshabilitada no llega acá (`pointer-events: none`). */
+        this.handleOptionPointerMove = (e, index) => {
+            if (e.pointerType === 'touch')
+                return;
+            if (this.activeIndex !== index)
+                this.activeIndex = index;
+        };
         /** Alinea el scroll REAL con la ventana virtual ya renderizada.
          *
          *  Escribe `scrollTop` DIRECTO sobre el viewport de OverlayScrollbars: el
@@ -153,8 +233,9 @@ export class CoSelect {
                 if (Math.abs(viewport.scrollTop - target) <= 1) {
                     this.pendingActiveScroll = false;
                     this.activeScrollFrames = 0;
-                    // Afinado dentro del slice ya visible (las alturas reales de fila no son
-                    // exactamente ITEM_HEIGHT). jsdom no implementa scrollIntoView.
+                    // Afinado dentro del slice ya visible (sin `--co-select-option-height`
+                    // las filas miden 32 y el paso histórico es 34). jsdom no implementa
+                    // scrollIntoView.
                     (_e = (_d = (_c = this.el.shadowRoot) === null || _c === void 0 ? void 0 : _c.getElementById(this.optionId(this.activeIndex))) === null || _d === void 0 ? void 0 : _d.scrollIntoView) === null || _e === void 0 ? void 0 : _e.call(_d, { block: 'nearest' });
                     return;
                 }
@@ -325,6 +406,8 @@ export class CoSelect {
     onOpenChange(open) {
         if (open) {
             this.scrollTop = 0;
+            // ANTES de la activa: su scroll inicial se calcula con el paso de fila.
+            this.rowMetrics = resolveRowMetrics(this.readCssLengthPx);
             this.resetActiveIndex();
             if (this.searchable)
                 this.focusSearchWhenVisible();
@@ -357,7 +440,6 @@ export class CoSelect {
     /** Deja la opción activa dentro de la ventana virtual (state) y agenda el
      *  scroll real para después del próximo render. */
     scrollActiveIntoView() {
-        const { ITEM_HEIGHT, VIEWPORT_ITEMS } = CoSelect;
         const index = this.activeIndex;
         if (!(index >= 0))
             return;
@@ -365,13 +447,10 @@ export class CoSelect {
         // (apertura con la selección abajo, Home/End, wrap) no tendría nodo — y el
         // `aria-activedescendant` quedaría colgado. Se empuja la posición virtual
         // para que el próximo slice lo incluya.
-        const top = index * ITEM_HEIGHT;
-        const viewportH = ITEM_HEIGHT * VIEWPORT_ITEMS;
         const from = this.scrollTop || 0;
-        if (top < from)
-            this.scrollTop = top;
-        else if (top + ITEM_HEIGHT > from + viewportH)
-            this.scrollTop = top + ITEM_HEIGHT - viewportH;
+        const next = scrollTopToReveal(index, from, this.metrics, CoSelect.VIEWPORT_ITEMS);
+        if (next !== from)
+            this.scrollTop = next;
         // El scroll REAL se resuelve en componentDidRender, no en un rAF suelto:
         // al abrir, el @Watch('isOpen') corre ANTES de que Stencil agende el
         // re-render, así que un rAF pedido acá se ejecutaría con el slice viejo
@@ -448,17 +527,17 @@ export class CoSelect {
             return label;
         return segs.map((s) => (s.match ? h("span", { class: "co-select__match" }, s.text) : s.text));
     }
+    /** `?? LEGACY`: el harness de specs no siembra inicializadores de campo en
+     *  todos los casos; en el build real `rowMetrics` siempre existe. */
+    get metrics() {
+        var _a;
+        return (_a = this.rowMetrics) !== null && _a !== void 0 ? _a : LEGACY_ROW_METRICS;
+    }
     getVirtualSlice(items) {
-        const { ITEM_HEIGHT, VIEWPORT_ITEMS, OVERSCAN } = CoSelect;
-        const total = items.length;
-        const totalHeight = total * ITEM_HEIGHT;
-        const startIdx = Math.max(0, Math.floor(this.scrollTop / ITEM_HEIGHT) - OVERSCAN);
-        const endIdx = Math.min(total, startIdx + VIEWPORT_ITEMS + OVERSCAN * 2);
-        const offsetY = startIdx * ITEM_HEIGHT;
-        return { totalHeight, startIdx, endIdx, offsetY };
+        return virtualSlice(items.length, this.scrollTop || 0, this.metrics, CoSelect.VIEWPORT_ITEMS, CoSelect.OVERSCAN);
     }
     render() {
-        var _a;
+        var _a, _b;
         const selected = this.selectedValues;
         const options = this.filteredOptions;
         // Se calcula UNA vez sobre `options` (no en un getter): el virtualizador
@@ -468,25 +547,36 @@ export class CoSelect {
         const activeOptionId = this.isOpen && this.activeIndex >= 0 && this.activeIndex < options.length
             ? this.optionId(this.activeIndex)
             : undefined;
-        return (h("div", { key: '902da0519e9fe96401f5339a3b46a66c94efd3de', class: {
+        return (h("div", { key: '12cb506f80422c39f8f5a17b81afa6c01831f237', class: {
                 'co-select': true,
                 'co-select--open': this.isOpen,
                 'co-select--disabled': this.disabled,
                 [`co-select--${this.size}`]: true,
                 [`co-select--${this.status}`]: this.status !== 'default',
                 'co-select--flat': this.variant === 'flat',
-            } }, (this.label || this.secondaryLabel) && (h("div", { key: '3faf027e94d30728d7715ebca758eb0d9cb41bc9', class: "co-select__labels" }, this.label && h("label", { key: 'a7267986158eae66be547356482df079e3670d44', class: "co-select__label" }, this.label, h(RequiredMark, { key: '5eaca0cfade91041b33edd07e648b1e22cb875f3', required: this.required })), this.secondaryLabel && h("span", { key: '3561fb5297dde4c128e9c888cdd00546c5e1b4c3', class: "co-select__secondary-label" }, this.secondaryLabel))), h("co-popover", { key: '63fc16eefafcb8ef870aba457be9e00f5dce6f32', open: this.isOpen, placement: "bottom-start", matchWidth: true, offset: 4, onCoOpen: this.handlePopoverOpen, onCoClose: this.handlePopoverClose }, h("div", { key: '6056ec2a5d85df9d8361f4b78f12eec6e2fe7749', slot: "trigger", class: "co-select__trigger", role: "combobox", "aria-expanded": this.isOpen ? 'true' : 'false', "aria-haspopup": "listbox", "aria-label": this.label || this.ariaLabelText || undefined, "aria-disabled": this.disabled ? 'true' : undefined, "aria-controls": CoSelect.LISTBOX_ID, "aria-activedescendant": activeOptionId, tabIndex: this.disabled ? -1 : 0, ref: (el) => (this.triggerEl = el), onClick: this.handleTriggerClick, onKeyDown: this.handleTriggerKeyDown }, this.iconLeft && h("co-icon", { key: '8877e366eba45e073a3481e7b86408763e103f6c', name: this.iconLeft, size: 16, class: "co-select__icon" }), ((_a = this.selectedOption) === null || _a === void 0 ? void 0 : _a.image) && (h("img", { key: '4f964e48dafff76a9fe04ed381b1f11113e351d6', class: "co-select__flag", src: this.selectedOption.image, alt: "" })), this.multiple && this.hasValue ? (h("div", { class: "co-select__chips" }, this.selectedValues.map((v) => {
+                'co-select--soft': this.variant === 'soft',
+                'co-select--inline-help': this.labelStyle === 'inline-help',
+            } }, (this.label || this.secondaryLabel) && (h("div", { key: 'bbb454e9d0ab08fd3abf5462711654c6eb8fe253', class: "co-select__labels" }, this.label && h("label", { key: '2dbf39a9e4fca24b95777078ecb6fea060aa2e19', class: "co-select__label" }, this.label, h(RequiredMark, { key: 'f5a62c06aa12a5556fc78d93918d673982183dfa', required: this.required })), this.secondaryLabel && h("span", { key: '2082ba20405dee16a08d35ec1ff67b59294056a0', class: "co-select__secondary-label" }, this.secondaryLabel))), h("co-popover", { key: '4f7e00909286922ff2b9d05f1ee4f42f8bc7aed9', open: this.isOpen, placement: "bottom-start", matchWidth: true, offset: 4,
+            // menuSurface="dark": el panel oscuro pinta su propio chrome (fondo
+            // negro, radio xs, sin borde ni sombra — Figma 4750:23242), así que
+            // el co-popover va `bare` para no sumar el borde hairline ni la
+            // sombra del panel claro (y cualquier --co-popover-shadow heredada
+            // del contexto). En "light" (default) no cambia nada.
+            bare: this.menuSurface === 'dark', onCoOpen: this.handlePopoverOpen, onCoClose: this.handlePopoverClose }, h("div", { key: '8537fcefbd02707af785ad623bcb1f19b276d3c4', slot: "trigger", class: "co-select__trigger", role: "combobox", "aria-expanded": this.isOpen ? 'true' : 'false', "aria-haspopup": "listbox", "aria-label": this.label || this.ariaLabelText || undefined, "aria-disabled": this.disabled ? 'true' : undefined, "aria-controls": CoSelect.LISTBOX_ID, "aria-activedescendant": activeOptionId, tabIndex: this.disabled ? -1 : 0, ref: (el) => (this.triggerEl = el), onClick: this.handleTriggerClick, onKeyDown: this.handleTriggerKeyDown }, this.iconLeft && (h("co-icon", { key: '6714adb30bb2c24824cf80048b579a05825652b9', name: this.iconLeft, size: (_a = this.iconSize) !== null && _a !== void 0 ? _a : 16, class: "co-select__icon" })), ((_b = this.selectedOption) === null || _b === void 0 ? void 0 : _b.image) && (h("img", { key: '8c0c6cca536a5edba4e3caa50ecd196f9e70117c', class: "co-select__flag", src: this.selectedOption.image, alt: "" })), this.multiple && this.hasValue ? (h("div", { class: "co-select__chips" }, this.selectedValues.map((v) => {
             const opt = this.parsedOptions.find((o) => o.value === v);
             return (h("span", { class: "co-select__chip", key: v }, h("span", { class: "co-select__chip-label" }, opt ? opt.label : v), h("button", { class: "co-select__chip-remove", type: "button", tabIndex: -1, "aria-label": "Remove", onClick: (e) => {
                     e.stopPropagation();
                     this.handleOptionClick(v);
                 } }, h("co-icon", { name: "x", size: 12 }))));
-        }))) : (h("span", { class: { 'co-select__text': true, 'co-select__text--placeholder': !this.hasValue } }, this.hasValue ? this.displayText : this.placeholder)), this.clearable && this.hasValue && !this.disabled && (h("button", { key: '55a94e3d877ec0c50ae4ce544774c6e4330b5f5e', class: "co-select__clear", type: "button", tabIndex: -1, onClick: this.handleClear, "aria-label": "Clear" }, h("co-icon", { key: 'b452121827aa8b2f341396b3376e82728bee5276', name: "x-circle", size: 16, weight: "fill" }))), h("co-icon", { key: '0ebc5a451bcb3f2f95a63ab600157e27cb445a9b', name: this.isOpen ? 'caret-up' : 'caret-down', size: 16, class: "co-select__caret" })), h("div", { key: '92b18226a02de73cbd245ab6827c3f5593aa08fc', class: "co-select__dropdown" }, this.isOpen && this.searchable && (h("div", { key: '68aec7a4ced328a00a1185078edbbfe4820d6582', class: "co-select__search" }, h("co-icon", { key: '1aa322cf22d4824bf6d2012b6dfc4e856360502a', name: "magnifying-glass", size: 16, class: "co-select__search-icon" }), h("input", { key: '62ec52d3369334f83709bc5219d5b3ca040c3ccb', class: "co-select__search-input", type: "text", placeholder: this.searchPlaceholder, value: this.searchText, "aria-controls": CoSelect.LISTBOX_ID, "aria-activedescendant": activeOptionId, onInput: this.handleSearchInput, onKeyDown: this.handleNavKeyDown, ref: (el) => (this.searchInputEl = el) }))), this.isOpen && this.searchable && options.length === 0 && (h("div", { key: '86613208aa94d79b6aa503a6ed53c010cc1ba1f9', class: "co-select__empty" }, this.emptyText)), h("div", { key: 'a6b1f09abfbfb0171094079c3da7ac89764eb00f', class: "co-select__options", id: CoSelect.LISTBOX_ID, role: "listbox", "aria-multiselectable": this.multiple ? 'true' : undefined, ref: (el) => (this.optionsContainerEl = el) }, this.isOpen && (() => {
+        }))) : (h("span", { class: { 'co-select__text': true, 'co-select__text--placeholder': !this.hasValue } }, this.hasValue ? this.displayText : this.placeholder)), this.clearable && this.hasValue && !this.disabled && (h("button", { key: '65f1295511998e7ec9685ee45433e01c14ae65df', class: "co-select__clear", type: "button", tabIndex: -1, onClick: this.handleClear, "aria-label": "Clear" }, h("co-icon", { key: '23416924a88739bf6326095298bfaaeabbe980e1', name: "x-circle", size: 16, weight: "fill" }))), h("co-icon", { key: 'd4c3c23b8ceb6ef0b918348e8b0f724051380681', name: this.isOpen ? 'caret-up' : 'caret-down', size: 16, class: "co-select__caret" })), h("div", { key: 'd591730000ed4e58f6c2474b58949ae15cf65593', class: {
+                'co-select__dropdown': true,
+                'co-select__dropdown--dark': this.menuSurface === 'dark',
+            } }, this.isOpen && this.searchable && (h("div", { key: 'd663fdb315d997ed2325a5c385bbd5728bebdaa1', class: "co-select__search" }, h("co-icon", { key: '13d5e0bd54b6dfa6d926f7e9ec2057f814720e16', name: "magnifying-glass", size: 16, class: "co-select__search-icon" }), h("input", { key: 'e7edfe009febe2c681c47fa92105b62c868b53d5', class: "co-select__search-input", type: "text", placeholder: this.searchPlaceholder, value: this.searchText, "aria-controls": CoSelect.LISTBOX_ID, "aria-activedescendant": activeOptionId, onInput: this.handleSearchInput, onKeyDown: this.handleNavKeyDown, ref: (el) => (this.searchInputEl = el) }))), this.isOpen && this.searchable && options.length === 0 && (h("div", { key: 'bd0befdaba2cbead771171b609e2021c714ea247', class: "co-select__empty" }, this.emptyText)), h("div", { key: '0e395475bba6b693419986ff2cf582192a15a2e6', class: "co-select__options", id: CoSelect.LISTBOX_ID, role: "listbox", "aria-multiselectable": this.multiple ? 'true' : undefined, ref: (el) => (this.optionsContainerEl = el) }, this.isOpen && (() => {
             const { totalHeight, startIdx, endIdx, offsetY } = this.getVirtualSlice(options);
             return (
             // Los wrappers del virtualizador van `presentation` para que las
             // opciones sigan siendo hijas del listbox en el árbol de a11y.
-            h("div", { role: "presentation", class: "co-select__virtual-spacer", style: { height: `${totalHeight}px`, position: 'relative' } }, h("div", { role: "presentation", style: { position: 'absolute', top: `${offsetY}px`, left: '0', right: '0' } }, options.slice(startIdx, endIdx).map((opt, i) => {
+            h("div", { role: "presentation", class: "co-select__virtual-spacer", style: { height: `${totalHeight}px`, position: 'relative' } }, h("div", { role: "presentation", class: "co-select__virtual-window", style: { position: 'absolute', top: `${offsetY}px`, left: '0', right: '0' } }, options.slice(startIdx, endIdx).map((opt, i) => {
                 const index = startIdx + i;
                 const isSelected = selected.includes(opt.value);
                 const isDisabled = !!opt.disabled;
@@ -495,9 +585,9 @@ export class CoSelect {
                         'co-select__option--selected': isSelected,
                         'co-select__option--disabled': isDisabled,
                         'co-select__option--active': index === this.activeIndex,
-                    }, onClick: () => !isDisabled && this.handleOptionClick(opt.value) }, opt.image ? (h("img", { class: "co-select__option-flag", src: opt.image, alt: "", loading: "lazy" })) : opt.icon ? (h("co-icon", { name: opt.icon, size: 20, class: "co-select__option-icon" })) : null, h("span", { class: "co-select__option-label" }, this.renderLabel(opt.label)), isSelected && h("co-icon", { name: "check", size: 16, class: "co-select__option-check" })));
+                    }, onClick: () => !isDisabled && this.handleOptionClick(opt.value), onPointerMove: (e) => this.handleOptionPointerMove(e, index) }, this.menuSurface === 'dark' && (h("span", { class: "co-select__option-check-slot" }, isSelected && (h("co-icon", { name: "check", size: 12, class: "co-select__option-check co-select__option-check--leading" })))), opt.image ? (h("img", { class: "co-select__option-flag", src: opt.image, alt: "", loading: "lazy" })) : opt.icon ? (h("co-icon", { name: opt.icon, size: 20, class: "co-select__option-icon" })) : null, h("span", { class: "co-select__option-label" }, this.renderLabel(opt.label)), isSelected && this.menuSurface !== 'dark' && (h("co-icon", { name: "check", size: 16, class: "co-select__option-check" }))));
             }))));
-        })()), this.isOpen && this.showFooter && (h("co-list-footer", { key: '5f5d60d846092aed435e292a4652ad7016cb6aee', class: "co-select__footer", primaryLabel: this.footerPrimaryLabel, primaryIcon: "check", onCoPrimary: this.handleFooterPrimary })))), this.helperText && (h("div", { key: '72ebb3366ee45eaccce69f534611804f8f1dbc1c', class: `co-select__helper co-select__helper--${this.status}` }, this.statusIcon && h("co-icon", { key: '2f2ad274cf521c3bd9f21d66d0fa9b7c87f7ba71', name: this.statusIcon, size: 14, class: "co-select__helper-icon" }), h("span", { key: '3e1ef4abb47a61d173e1942f5798caff97c2347e', class: "co-select__helper-text" }, this.helperText)))));
+        })()), this.isOpen && this.showFooter && (h("co-list-footer", { key: 'b5991f9a23e145990ba8d1a01f67c1744165aa36', class: "co-select__footer", primaryLabel: this.footerPrimaryLabel, primaryIcon: "check", onCoPrimary: this.handleFooterPrimary })))), this.helperText && (h("div", { key: '04d08f975108f5f86dcbf4078271cbb16c47f4c6', class: `co-select__helper co-select__helper--${this.status}` }, this.statusIcon && h("co-icon", { key: '26ab3e89c81d4c64aef536f561921d5c3f08ea62', name: this.statusIcon, size: 14, class: "co-select__helper-icon" }), h("span", { key: '0743ba35903d666a3ab4598e4639e8c0f94a190b', class: "co-select__helper-text" }, this.helperText)))));
     }
     static get is() { return "co-select"; }
     static get encapsulation() { return "shadow"; }
@@ -525,7 +615,7 @@ export class CoSelect {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Etiqueta del campo (tambi\u00E9n es su nombre accesible)."
                 },
                 "getter": false,
                 "setter": false,
@@ -583,7 +673,7 @@ export class CoSelect {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Texto secundario junto a la etiqueta (p. ej. \u00ABOpcional\u00BB); con `labelStyle=\"inline-help\"` va a la derecha."
                 },
                 "getter": false,
                 "setter": false,
@@ -602,7 +692,7 @@ export class CoSelect {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Texto del trigger sin selecci\u00F3n."
                 },
                 "getter": false,
                 "setter": false,
@@ -622,7 +712,7 @@ export class CoSelect {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Deshabilita el campo."
                 },
                 "getter": false,
                 "setter": false,
@@ -642,13 +732,32 @@ export class CoSelect {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "\u00CDcono Phosphor al inicio del trigger."
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": false,
                 "attribute": "icon-left"
             },
+            "iconSize": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Tama\u00F1o (px) del `co-icon` de `iconLeft`. Sin setear, conserva el actual (16)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "icon-size"
+            },
             "clearable": {
                 "type": "boolean",
                 "mutable": false,
@@ -661,7 +770,7 @@ export class CoSelect {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Bot\u00F3n \u00D7 para vaciar la selecci\u00F3n cuando hay valor; emite `coClear` y `coChange`."
                 },
                 "getter": false,
                 "setter": false,
@@ -681,7 +790,7 @@ export class CoSelect {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Texto de ayuda o de error bajo el campo."
                 },
                 "getter": false,
                 "setter": false,
@@ -720,7 +829,7 @@ export class CoSelect {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Estado de validaci\u00F3n: pinta el borde y el `helperText` con el color del estado."
                 },
                 "getter": false,
                 "setter": false,
@@ -737,7 +846,7 @@ export class CoSelect {
                     "references": {
                         "SelectOption": {
                             "location": "local",
-                            "path": "/Users/agox/worktrees/cobalt-release-0.10.3/packages/core/src/components/co-select/co-select.tsx",
+                            "path": "/Users/agox/worktrees/cobalt-docs-2026-09-24/packages/core/src/components/co-select/co-select.tsx",
                             "id": "src/components/co-select/co-select.tsx::SelectOption"
                         }
                     }
@@ -746,7 +855,7 @@ export class CoSelect {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Opciones: array de `{ value, label, icon?, image?, disabled? }`, array de strings\n(value = label), o ese mismo array como JSON desde HTML."
                 },
                 "getter": false,
                 "setter": false,
@@ -766,7 +875,7 @@ export class CoSelect {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Selecci\u00F3n: el `value` de la opci\u00F3n en single; en `multiple`, array o JSON array.\n`''` significa \u00ABsin selecci\u00F3n\u00BB (una opci\u00F3n con `value: ''` no se puede marcar).\nEl componente lo actualiza al elegir."
                 },
                 "getter": false,
                 "setter": false,
@@ -786,7 +895,7 @@ export class CoSelect {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Selecci\u00F3n m\u00FAltiple: el panel queda abierto y `value`/`coChange` llevan un array."
                 },
                 "getter": false,
                 "setter": false,
@@ -798,15 +907,15 @@ export class CoSelect {
                 "type": "string",
                 "mutable": false,
                 "complexType": {
-                    "original": "'s' | 'sm' | 'md' | 'lg'",
-                    "resolved": "\"lg\" | \"md\" | \"s\" | \"sm\"",
+                    "original": "'xs' | 's' | 'sm' | 'md' | 'lg'",
+                    "resolved": "\"lg\" | \"md\" | \"s\" | \"sm\" | \"xs\"",
                     "references": {}
                 },
                 "required": false,
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Alto del trigger: `xs` 24 \u00B7 `s` 28 \u00B7 `sm` 32 \u00B7 `md` 40 (default) \u00B7 `lg` 48. Un valor fuera de la lista cae al default."
                 },
                 "getter": false,
                 "setter": false,
@@ -818,15 +927,15 @@ export class CoSelect {
                 "type": "string",
                 "mutable": false,
                 "complexType": {
-                    "original": "'default' | 'flat'",
-                    "resolved": "\"default\" | \"flat\"",
+                    "original": "'default' | 'flat' | 'soft'",
+                    "resolved": "\"default\" | \"flat\" | \"soft\"",
                     "references": {}
                 },
                 "required": false,
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Visual style. `flat` strips the trigger's border and background so it\nreads as plain content instead of a boxed control \u2014 padding, label,\nfocus ring, disabled and status states are unaffected. `default` (the\nstandard bordered box) renders identically to before this prop existed."
+                    "text": "Visual style. `flat` strips the trigger's border and background so it\nreads as plain content instead of a boxed control \u2014 padding, label,\nfocus ring, disabled and status states are unaffected. `soft` pinta un\nfondo `gray-100` s\u00F3lido con borde transparente (mismo grosor que el\ndefault, no cambia el tama\u00F1o de la caja). `default` (the standard\nbordered box) renders identically to before this prop existed."
                 },
                 "getter": false,
                 "setter": false,
@@ -834,6 +943,46 @@ export class CoSelect {
                 "attribute": "variant",
                 "defaultValue": "'default'"
             },
+            "labelStyle": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'default' | 'inline-help'",
+                    "resolved": "\"default\" | \"inline-help\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Layout de la fila de etiqueta. `inline-help` la muestra en una sola fila\n(`label` a la izquierda, `secondaryLabel` a la derecha, alineados a la\nl\u00EDnea de base) y ajusta el borde/gap del trigger para ese contexto\n(modal). `default` mantiene el layout actual (labels apiladas arriba,\ncentradas verticalmente entre s\u00ED)."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "label-style",
+                "defaultValue": "'default'"
+            },
+            "menuSurface": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'light' | 'dark'",
+                    "resolved": "\"dark\" | \"light\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Superficie del panel desplegable. `dark` = fondo `surface-primary` +\ntexto `text-inverse`, con el check de la opci\u00F3n seleccionada al\nINICIO (hueco siempre reservado, como `co-menu-item leadingCheck`).\n`light` (default) conserva el panel y el check al final tal cual hoy."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "menu-surface",
+                "defaultValue": "'light'"
+            },
             "searchable": {
                 "type": "boolean",
                 "mutable": false,
@@ -866,7 +1015,7 @@ export class CoSelect {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Placeholder del buscador del panel (`searchable`)."
                 },
                 "getter": false,
                 "setter": false,
@@ -886,7 +1035,7 @@ export class CoSelect {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Texto del panel cuando la b\u00FAsqueda no encuentra opciones."
                 },
                 "getter": false,
                 "setter": false,
@@ -954,7 +1103,7 @@ export class CoSelect {
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Cambi\u00F3 la selecci\u00F3n (`value` ya est\u00E1 actualizado): `detail` = value elegido, o el\narray completo en `multiple`. Al vaciar con la \u00D7: `''` (o `[]`)."
                 },
                 "complexType": {
                     "original": "string | string[]",
@@ -969,7 +1118,7 @@ export class CoSelect {
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Se vaci\u00F3 la selecci\u00F3n con la \u00D7. Sin `detail`; le sigue un `coChange`."
                 },
                 "complexType": {
                     "original": "void",
@@ -1001,7 +1150,8 @@ export class CoSelect {
             }];
     }
 }
-CoSelect.ITEM_HEIGHT = 34;
+/** Filas visibles sin scroll. Es el mismo 8 del `max-height` de
+ *  `.co-select__options` (8 altos + 7 huecos): si cambia uno, cambia el otro. */
 CoSelect.VIEWPORT_ITEMS = 8;
 CoSelect.OVERSCAN = 3;
 /** Ids del shadow root (únicos por instancia sin sufijos aleatorios).

package/dist/collection/components/co-select/virtualRows.js

@@ -0,0 +1,57 @@
+/**
+ * Geometría del virtualizador de filas de `co-select`, pura: recibe medidas y
+ * devuelve medidas, sin tocar el DOM (el componente es el que las lee del CSS).
+ *
+ * El paso de una fila es su ALTO más el HUECO hasta la siguiente. Los dos salen
+ * de los knobs del menú (`--co-select-option-height`, `--co-select-menu-gap`);
+ * sin ellos rige el paso de 0.10.x (ver `LEGACY_ROW_METRICS`).
+ */
+/**
+ * Paso histórico, el de 0.10.x: 34 px por fila, sin hueco. Las filas por defecto
+ * miden 32 (`min-height`), así que el virtualizador reserva 2 px de más por fila
+ * — la lista corta muestra ese sobrante como aire al pie del panel. Se conserva
+ * TAL CUAL para que ningún consumidor actual vea cambiar el alto de su menú; el
+ * que setea `--co-select-option-height` obtiene el paso exacto de sus filas. Es
+ * el mismo 34 del fallback del `max-height` de `.co-select__options`.
+ */
+export const LEGACY_ROW_METRICS = Object.freeze({ rowHeight: 34, gap: 0 });
+const pitch = (m) => m.rowHeight + m.gap;
+/** Alto de `count` filas apiladas: sin hueco colgando después de la última. */
+export function listHeight(count, m) {
+    return count > 0 ? count * m.rowHeight + (count - 1) * m.gap : 0;
+}
+/** Ventana de filas a renderizar para un `scrollTop`, con `overscan` a cada lado. */
+export function virtualSlice(total, scrollTop, m, viewportItems, overscan) {
+    const step = pitch(m);
+    const startIdx = Math.max(0, Math.floor(scrollTop / step) - overscan);
+    const endIdx = Math.min(total, startIdx + viewportItems + overscan * 2);
+    return { totalHeight: listHeight(total, m), startIdx, endIdx, offsetY: startIdx * step };
+}
+/**
+ * `scrollTop` que deja la fila `index` entera dentro de una ventana de
+ * `viewportItems` filas: si está arriba, la sube al borde superior; si está
+ * abajo, la pega al inferior; si ya se ve, no mueve nada.
+ */
+export function scrollTopToReveal(index, scrollTop, m, viewportItems) {
+    const top = index * pitch(m);
+    const bottom = top + m.rowHeight;
+    const viewportH = listHeight(viewportItems, m);
+    if (top < scrollTop)
+        return top;
+    if (bottom > scrollTop + viewportH)
+        return bottom - viewportH;
+    return scrollTop;
+}
+/**
+ * Medidas a partir de los knobs. `readPx` devuelve el valor en px de una custom
+ * property, o `null` si no está seteada o no se puede resolver a px. Lo que
+ * falte o sea inválido (alto ≤ 0, hueco < 0, NaN) cae al valor histórico.
+ */
+export function resolveRowMetrics(readPx) {
+    const h = readPx('--co-select-option-height');
+    const g = readPx('--co-select-menu-gap');
+    return {
+        rowHeight: h != null && h > 0 ? h : LEGACY_ROW_METRICS.rowHeight,
+        gap: g != null && g >= 0 ? g : LEGACY_ROW_METRICS.gap,
+    };
+}

package/dist/collection/components/co-separator/co-separator.js

@@ -1,4 +1,11 @@
 import { h } from "@stencil/core";
+/**
+ * Línea divisoria horizontal o vertical, con espaciado e inset opcionales y
+ * color/grosor configurables por prop. Wrapper Vue: `CoSeparator` de
+ * `@prolibu-suite/cobalt-vue`.
+ *
+ * @part separator - La línea.
+ */
 export class CoSeparator {
     constructor() {
         /** Orientation: horizontal (default) or vertical */
@@ -57,7 +64,7 @@ export class CoSeparator {
                 style['--co-separator-inset-end'] = '0px';
             }
         }
-        return (h("hr", { key: '164044b86003ca2ed8c15a2d82cc50922dfe8313', class: {
+        return (h("hr", { key: '1b15a22f07b7bf656d9b20b53d602bc7d47e3cf2', class: {
                 'co-separator': true,
                 'co-separator--vertical': this.vertical,
                 'co-separator--dark': this.dark,

package/dist/collection/components/co-sidebar/co-sidebar.js

@@ -1,5 +1,13 @@
 import { h } from "@stencil/core";
 /**
+ * Barra lateral de navegación con cabecera, cuerpo de ítems y pie. Wrapper Vue:
+ * `CoSidebar` de `@prolibu-suite/cobalt-vue`.
+ *
+ * @part sidebar - La barra completa.
+ * @part header - Área del slot `header`.
+ * @part body - Área de navegación (slot por defecto).
+ * @part footer - Área del slot `footer`.
+ *
  * @slot header - Logo / branding area
  * @slot        - Navigation items (co-list-item, etc.)
  * @slot footer - Bottom section
@@ -10,10 +18,10 @@ export class CoSidebar {
         this.mode = 'full';
     }
     render() {
-        return (h("nav", { key: '3d14a99c008dd92798182b04d7049c1a9fb4a00c', class: {
+        return (h("nav", { key: 'de782225d3dc1ef1def8af333a2a81809b50a84d', class: {
                 'co-sidebar': true,
                 [`co-sidebar--${this.mode}`]: true,
-            }, part: "sidebar" }, h("div", { key: '1bf5b8ebe9eb9836c01ac8c7b651aac8af2ebf3c', class: "co-sidebar__header", part: "header" }, h("slot", { key: 'ba0d88bf62955a61b3e2d297261b260845cbd98f', name: "header" })), h("div", { key: '793248e8020bd38e3da64e35ca8610cb85b17d4a', class: "co-sidebar__body", part: "body" }, h("slot", { key: 'a76928e89d8425846ad0859339ab35b465bf917e' })), h("div", { key: '4182d50c61913447ae78c670bba1ca1821cc763d', class: "co-sidebar__footer", part: "footer" }, h("slot", { key: 'bb20795e0acc8e1865f8b5d8568768eb5c5097ee', name: "footer" }))));
+            }, part: "sidebar" }, h("div", { key: '7c4466bf0d14cba9ca008d0a1cf9c28972726301', class: "co-sidebar__header", part: "header" }, h("slot", { key: '1389f2fa757adcd7b97586534de4144f9b08d1a7', name: "header" })), h("div", { key: '298ea9f0183bb31b0a4b6d83053029b8f181fb7d', class: "co-sidebar__body", part: "body" }, h("slot", { key: 'f1c0c4b26b4be0441048f7f961529ce5371d4c6d' })), h("div", { key: '62666b4e1b9591c70196fccb73caf683925de906', class: "co-sidebar__footer", part: "footer" }, h("slot", { key: '83566f1745b802296b7db7b90032a3ca13849126', name: "footer" }))));
     }
     static get is() { return "co-sidebar"; }
     static get encapsulation() { return "shadow"; }