@prolibu-suite/cobalt-core 0.9.3 → 0.9.5

package/dist/types/components/co-audio-player/co-audio-player.utils.d.ts

@@ -1,5 +1,22 @@
-/** Seconds → "m:ss" (floors; 0 for NaN/negative). */
+/** Rendered in place of `m:ss` while a time is not known.
+ *
+ *  Not an error state: `<audio>.duration` is `Infinity` for any container whose
+ *  header carries no duration — every blob `MediaRecorder` produces, i.e. every
+ *  freshly recorded voice note — and Chrome keeps it that way until the clip has
+ *  been played end to end. `0:00` there would read as a zero-length recording;
+ *  `--:--` reads as "not known yet", which is the truth. */
+export declare const UNKNOWN_TIME = "--:--";
+/** Seconds → "m:ss" (floors). Anything that is not a finite, non-negative number
+ *  (`Infinity`, `NaN`, negatives) → `UNKNOWN_TIME` — never `"Infinity:NaN"`. */
 export declare function formatTime(seconds: number): string;
+/** Picks the duration to trust (seconds), or `NaN` when neither source knows it.
+ *
+ *  `<audio>.duration` is authoritative *when it is a real number*. It is not for
+ *  a duration-less container (see `UNKNOWN_TIME`), where it reports `Infinity`.
+ *  The WebAudio decode the player already runs to draw the waveform does know the
+ *  real length (`AudioBuffer.duration`), so it is the fallback. `0` from either
+ *  source means "empty/unknown" too, so it never wins. */
+export declare function resolveDuration(fromAudio: number, fromDecode: number): number;
 /** Downsample raw PCM to `bars` peak heights, each normalized to a 0..1 fraction. */
 export declare function resamplePeaks(channelData: Float32Array | number[], bars: number): number[];
 /** Deterministic pseudo-waveform (stable render + testable — no Math.random). */

package/dist/types/components/co-button/co-button.d.ts

@@ -19,7 +19,9 @@ export declare class CoButton {
      * `variant="danger" surface="dark"`.
      */
     surface: 'light' | 'dark';
-    /** Disabled state */
+    /** Disabled state. Reflected so :host([disabled]) can kill pointer-events —
+     *  the inner button's own pointer-events:none re-targets clicks to the host,
+     *  where consumers' click listeners live. */
     disabled: boolean;
     /** Text label (alternative to default slot) */
     label?: string;

package/dist/types/components/co-calendar-month/co-calendar-month.d.ts

@@ -76,10 +76,14 @@ export declare class CoCalendarMonth {
         rect?: DOMRect;
     }>;
     private onPointerUp;
+    private onPointerMove;
     private nowTimer?;
     /** Root ref para el classList imperativo del FIX D (sin @State: no debe
      * disparar un render por celda cruzada durante el drag). */
     private rootEl?;
+    private dragArmedId;
+    private dragStartPointer;
+    private suppressNextClick;
     /** Memo de layoutMonth/matrix/segByWeek/byId por identidad de inputs. Durante
      * el drag-over de celdas (pointerenter → dragOverDate @State) ninguno de estos
      * inputs cambia → hit puro, sin recomputar layoutMonth/getMonthMatrix/segByWeek. */
@@ -108,6 +112,9 @@ export declare class CoCalendarMonth {
      * celda cruzada). No es @State a propósito: no debe disparar un render. */
     private setInteracting;
     private startDrag;
+    /** Arma → activa el drag al cruzar el umbral (ver DRAG_THRESHOLD_PX). Antes de
+     * eso no toca dragId/interacting, así el click nativo del chip sigue vivo. */
+    private trackDrag;
     private finishDrag;
     private getLayouts;
     private renderChip;

package/dist/types/components/co-checkbox/co-checkbox.d.ts

@@ -23,5 +23,6 @@ export declare class CoCheckbox {
     /** Fired when the value changes */
     coChange: EventEmitter<boolean>;
     private handleClick;
+    private handleKeyDown;
     render(): any;
 }

package/dist/types/components/co-color-picker/co-color-picker.d.ts

@@ -11,6 +11,16 @@ import { type ColorPreset } from './presets';
  */
 export declare class CoColorPicker {
     el: HTMLElement;
+    /**
+     * Id del panel de presets, target de `aria-controls` del trigger. Constante
+     * (no aleatoria): vive en el shadow root de ESTA instancia, donde los ids no
+     * colisionan con los de otras.
+     *
+     * El trigger solo emite `aria-controls` mientras `isOpen`: el panel se monta
+     * on-demand, así que cerrado el IDREF quedaría colgante.
+     */
+    private static readonly PANEL_ID;
+    private triggerEl?;
     /** Current color value as hex string (e.g. "#0066FF"). */
     value: string;
     /** Field label. */
@@ -43,6 +53,11 @@ export declare class CoColorPicker {
     private get parsedPresets();
     private handlePopoverOpen;
     private handlePopoverClose;
+    private handleTriggerKeyDown;
+    /** Devuelve el foco al trigger al cerrar el panel (Escape, selección),
+     *  salvo que el cierre venga de un click-outside que ya movió el foco a
+     *  otro elemento — en ese caso no robarlo. */
+    private restoreTriggerFocus;
     private handleSwatchClick;
     private get statusIcon();
     private handleCopy;

package/dist/types/components/co-combobox/co-combobox.d.ts

@@ -50,6 +50,18 @@ export declare class CoCombobox {
     searchQuery: string;
     overflowCount: number;
     el: HTMLElement;
+    /**
+     * Id del <co-option-list> del dropdown, target de `aria-controls` del
+     * trigger. Constante (no aleatoria): vive en el shadow root de ESTA
+     * instancia, donde los ids no colisionan con los de otras. Se referencia el
+     * HOST de la primitiva — su listbox interno queda tras su propio shadow
+     * boundary y no es direccionable desde acá (limitación conocida y aceptada).
+     *
+     * El trigger solo emite `aria-controls` mientras `isOpen`: la lista se monta
+     * on-demand, así que cerrado el IDREF quedaría colgante.
+     */
+    private static readonly LIST_ID;
+    private triggerEl?;
     private chipContainerEl?;
     private optionListEl?;
     private resizeObserver?;
@@ -92,6 +104,11 @@ export declare class CoCombobox {
     componentDidRender(): void;
     private calcOverflow;
     private handleTriggerClick;
+    private handleTriggerKeyDown;
+    /** Devuelve el foco al trigger al cerrar el panel (Escape, selección),
+     *  salvo que el cierre venga de un click-outside que ya movió el foco a
+     *  otro elemento — en ese caso no robarlo. */
+    private restoreTriggerFocus;
     private handlePopoverOpen;
     private handlePopoverClose;
     private handleClear;

package/dist/types/components/co-icon-button/co-icon-button.d.ts

@@ -29,6 +29,9 @@ export declare class CoIconButton {
      */
     iconSize?: number;
     /** Disabled state */
+    /** Reflected so :host([disabled]) can kill pointer-events — the inner
+     *  button's pointer-events:none re-targets clicks to the host, where
+     *  consumers' click listeners live. */
     disabled: boolean;
     /** Accessible label */
     label: string;

package/dist/types/components/co-input/co-input.d.ts

@@ -18,6 +18,15 @@ export declare class CoInput {
     placeholder: string;
     /** Current value */
     value: string;
+    /**
+     * Refleja en el <input> los cambios de `value` que vienen de AFUERA (host que
+     * setea la prop programáticamente: cálculos, refresh, seed diferido). El
+     * <input> controlado de Stencil no repinta ante esos cambios bajo el lazy
+     * loader; escribir `inputEl.value` a mano lo sincroniza. Guard `hasFocus`:
+     * mientras el usuario tipea NO lo pisamos (movería el caret). Mismo patrón que
+     * co-number-field.onValueChange.
+     */
+    onValueChange(next: string): void;
     /** Helper text displayed below the input */
     helperText?: string;
     /** Disabled state */

package/dist/types/components/co-number-field/co-number-field.d.ts

@@ -9,6 +9,15 @@ export declare class CoNumberField {
     layout: 'vertical' | 'horizontal';
     status: 'default' | 'error' | 'success' | 'warning' | 'info';
     value: number | null;
+    /**
+     * Refleja en el <input> los cambios de `value` que vienen de AFUERA (host que
+     * setea la prop: refresh de tasas, seed al abrir un form, cálculos). El render
+     * de Stencil no repinta el input controlado ante esos cambios bajo el lazy
+     * loader (verificado en vivo 2026-08-20: prop=0.000326 y el input seguía en
+     * "0"). Escribir `inputEl.value` a mano lo sincroniza. Guard `focused`: mientras
+     * el usuario tipea, su propio input manda — no lo pisamos (movería el caret).
+     */
+    onValueChange(): void;
     min?: number;
     max?: number;
     step: number;

package/dist/types/components/co-option-list/co-option-list.d.ts

@@ -27,6 +27,13 @@ export declare class CoOptionList {
     removableItems: boolean;
     /** Habilita reorder por drag del bloque de seleccionados (selected-first). */
     reorderable: boolean;
+    /** Botón push-pin por fila (siempre visible). Emite coPinToggle; el estado
+     *  pinned viene en item.pinned — el componente NO lo muta (controlado). */
+    pinnable: boolean;
+    /** Drag-reorder de la LISTA completa (no del bloque seleccionado): handle en
+     *  filas no-pineadas, emite coListReorder con el orden visible completo.
+     *  Independiente de multiple/selectedFirst. No soportado con `virtual`. */
+    listReorderable: boolean;
     searchable: boolean;
     searchPlaceholder: string;
     searchDebounce: number;
@@ -64,6 +71,15 @@ export declare class CoOptionList {
         value: string[];
         item: OptionListItem;
     }>;
+    /** Toggle de pin de una fila (pinnable). */
+    coPinToggle: EventEmitter<{
+        item: OptionListItem;
+    }>;
+    /** Drag-reorder de lista completa (listReorderable): orden visible + ítem movido. */
+    coListReorder: EventEmitter<{
+        value: string[];
+        item: OptionListItem;
+    }>;
     term: string;
     activeIndex: number;
     scrollTop: number;
@@ -78,10 +94,20 @@ export declare class CoOptionList {
     private searchInputEl?;
     private optionsEl?;
     private osInstance?;
+    /** Longitud de lista para la que ya se pidió un fill (ver fillViewport). */
+    private lastFillLen;
     private debounceTimer?;
     /** Snapshot selected-first (ver snapshotOrder). */
     private sortSnapshot;
     private displaySnapshot;
+    /** FLIP del settle post-drop: tops por id capturados ANTES de mutar el orden.
+     *  `spring` = momento expresivo (solo el settle del revert), no los swaps. */
+    private pendingFlip?;
+    /** Orden del live-preview en curso (drag por puntero del bloque seleccionado). */
+    private previewOrder;
+    /** Drag por puntero (estilo motion.dev: la fila sigue al cursor, sin ghost
+     *  nativo). Solo bloque seleccionado; listReorderable sigue en HTML5 DnD. */
+    private ptrDrag?;
     private get parsedItems();
     private get selectedIds();
     private get orderedItems();
@@ -99,6 +125,16 @@ export declare class CoOptionList {
      * sobre subtree oculto es no-op silencioso. Reintenta ~20 frames.
      */
     focusSearch(): Promise<void>;
+    /**
+     * Ancla la sesión del panel en la selección: highlight sobre la primera fila
+     * seleccionada y scroll hasta dejarla visible (paridad resetActiveIndex de
+     * co-select). El host la llama al ABRIR su panel — la lista queda montada
+     * entre aperturas y no sabe cuándo se abre (mismo contrato que
+     * focusSearch/snapshotOrder). Espera layout real igual que focusSearch: el
+     * panel se hace visible frames después y un scroll sobre subtree oculto se
+     * clampea a 0 en silencio.
+     */
+    scrollToSelected(): Promise<void>;
     /** Navegación para hosts con input externo. true = tecla consumida (host hace preventDefault). */
     handleKey(e: KeyboardEvent): Promise<boolean>;
     private takeSnapshot;
@@ -114,18 +150,61 @@ export declare class CoOptionList {
      *  consumidor jamás se enteraba y la X parecía muerta (bug del workspace). */
     private deselectItem;
     private pick;
+    /** true = drag de lista completa; el modo selected-block (chips multiple) tiene prioridad
+     *  si ambos están activos (no coexisten en la práctica). */
+    private get listDragActive();
+    /** Universo del drag de LISTA COMPLETA (listReorderable). El bloque
+     *  seleccionado usa `previewOrder` (live-preview, ver handleRowDragStart). */
+    private dragOrderIds;
     private handleRowDragStart;
     private handleRowDragOver;
+    /** Aplica un orden de preview al bloque seleccionado con FLIP (todo ease-out;
+     *  la fila lifted queda fuera del FLIP — su posición la dicta el puntero). */
+    private applyPreview;
+    private startPointerDrag;
+    private onPtrMove;
+    /** Posiciona la fila lifted bajo el puntero (transform sobre su slot de layout). */
+    private positionLifted;
+    private onPtrUp;
+    private onPtrKey;
+    /** Settle de la fila lifted: de su posición visual actual a su slot, con spring. */
+    private settleLifted;
+    private removePtrListeners;
     private handleRowDrop;
+    private captureRowTops;
+    /**
+     * FLIP de cada reacomodo (swap del live-preview y revert): las filas arrancan
+     * desplazadas a su posición visual anterior (transform) y transicionan a la
+     * nueva. Solo transform, con tokens de motion (reduced-motion se resuelve
+     * global vía zeroing). Swaps mid-drag: todo ease-out (fluido, sin rebote);
+     * spring solo para la fila movida en el settle del revert.
+     * Batcheado (writes → reads → writes, un solo flush) y robusto a interrupciones:
+     * neutraliza transforms de un FLIP anterior ANTES de medir el layout nuevo.
+     */
+    private runFlip;
     private handleRowDragEnd;
     private handleRowDragLeave;
     private disarmDrag;
     private resetDragState;
     private maybeLoadMore;
+    /** El infinite scroll asume que cada página desborda el contenedor. Con
+     *  paneles altos (--co-option-list-max-height) una página puede caber entera
+     *  → sin overflow no hay evento de scroll y la paginación queda muerta. Tras
+     *  cada render, si el contenido no deja distancia scrolleable (mismo slack
+     *  de 40px que maybeLoadMore) y hay más resultados, pide otra página. Se
+     *  emite UNA vez por longitud de lista: si el host no responde no re-emite,
+     *  y el append de la página siguiente re-habilita el check. */
+    private fillViewport;
     private onNativeScroll;
     private scrollActiveIntoView;
     private renderLeading;
     private renderLabelText;
+    /** Pill junto al label. Con `tooltip` va envuelto en un `co-tooltip` — el
+     *  label del badge se abrevia (3 letras en el de workspace) y sin el texto
+     *  completo al hover no hay forma de saber a qué se refiere. Sin `tooltip`
+     *  renderiza el span pelado, igual que antes (mismo patrón que la prop
+     *  `name` de co-avatar). */
+    private renderBadge;
     private renderRow;
     private renderVirtual;
     render(): any;

package/dist/types/components/co-option-list/optionListLogic.d.ts

@@ -7,10 +7,15 @@ export interface OptionListItem {
     description?: string;
     /** Texto secundario junto al label, renderizado como "- suffix". */
     suffix?: string;
-    /** Pill junto al label (generaliza el workspace badge de suite-v2). */
+    /** Pill junto al label (generaliza el workspace badge de suite-v2).
+     *  `tooltip` (opcional): texto completo al hover — el pill se abrevia (3
+     *  letras en el badge de workspace) y sin esto no hay forma de saber qué
+     *  dice. Con `tooltip` el pill se envuelve en un `co-tooltip`; sin él
+     *  renderiza exactamente igual que antes. */
     badge?: {
         label: string;
         color?: string;
+        tooltip?: string;
     };
     /** Phosphor icon como leading visual (si no hay avatar/color). */
     icon?: string;
@@ -23,6 +28,8 @@ export interface OptionListItem {
     /** Header de sección: se inserta uno al CAMBIAR de group (patrón ⌘K). */
     group?: string;
     disabled?: boolean;
+    /** Fila pineada por el usuario: pinta el push-pin fill y queda excluida del drag de lista. */
+    pinned?: boolean;
 }
 export type OptionListRow = {
     kind: 'header';
@@ -53,9 +60,24 @@ export declare function orderItems(items: OptionListItem[], snapshotIds: Set<str
 export declare function buildRows(items: OptionListItem[]): OptionListRow[];
 /** Mueve `fromId` a la posición de `toId` en `order`. No muta el input;
  *  devuelve el mismo array (referencia) si es no-op. */
+/**
+ * Universo del drag del bloque seleccionado: los ids seleccionados VIVOS en su
+ * orden visible. A diferencia del snapshot (congelado al abrir), incluye lo
+ * seleccionado durante la sesión del panel — sin esto, esos ítems renderizan
+ * handle pero el drop los rechaza, y un reorder del snapshot emitiría un value
+ * truncado (pierde las selecciones frescas).
+ */
+export declare function liveSelectedOrder(items: OptionListItem[], selectedIds: string[]): string[];
 export declare function reorderIds(order: string[], fromId: string, toId: string): string[];
+/** Reorder de lista completa: los extremos pineados son inválidos (ni origen ni
+ *  destino) — devuelve la misma referencia, señal de no-op para el caller. */
+export declare function listReorderIds(order: string[], fromId: string, toId: string, isPinned: (id: string) => boolean): string[];
 /** Siguiente highlight: wrap, salta disabled. -1 = sin items navegables. */
 export declare function nextActiveIndex(current: number, delta: 1 | -1, items: OptionListItem[]): number;
+/** Highlight inicial de la sesión del panel: primera fila seleccionada
+ *  NAVEGABLE en orden visible (contrato de scrollToSelected, paridad
+ *  resetActiveIndex de co-select). -1 = nada que anclar. */
+export declare function selectedActiveIndex(items: OptionListItem[], selectedIds: string[]): number;
 /** `total > 0` tiene precedencia (deriva remaining); si no, vale `hasMoreProp`. */
 export declare function deriveMore(count: number, total: number, hasMoreProp: boolean): {
     hasMore: boolean;

package/dist/types/components/co-ref-field/co-ref-field.d.ts

@@ -29,6 +29,12 @@ export declare class CoRefField {
     placeholder: string;
     disabled: boolean;
     clearable: boolean;
+    /** Shows a pencil button on the single-value trigger that emits
+     *  `coEditSelected` with the selected record id. The host owns policy
+     *  (permissions, what opens) — the component only paints and emits. */
+    editable: boolean;
+    /** Accessible name / tooltip for the edit button. */
+    editLabel: string;
     multiple: boolean;
     status: 'default' | 'error' | 'success' | 'warning';
     helperText?: string;
@@ -78,6 +84,13 @@ export declare class CoRefField {
     maxChips: number;
     /** Panel color theme. 'auto' follows trigger, 'dark' forces dark panel, 'light' forces light. */
     panelTheme: 'auto' | 'dark' | 'light';
+    /**
+     * How `item.color` paints the selected chips (multiple mode).
+     * 'dot' (default) = neutral chip with a leading 8px color dot.
+     * 'fill' = the color becomes the chip BACKGROUND (label/remove switch to
+     * WCAG-contrast text) — the tag look. Avatar/image items keep the avatar.
+     */
+    colorMode: 'dot' | 'fill';
     /**
      * Phosphor icon rendered as a small status badge after the selected label in
      * the trigger (e.g. 'funnel' = strict workspace filter active). Only shows
@@ -101,6 +114,10 @@ export declare class CoRefField {
      * a smooth squircle. The avatar border can be themed via --co-avatar-border-color.
      */
     avatarShape: 'circle' | 'square';
+    /** Push-pin por fila en el panel (forward a co-option-list). */
+    pinnable: boolean;
+    /** Drag-reorder de la lista del panel (forward a co-option-list). */
+    listReorderable: boolean;
     coChange: EventEmitter<{
         value: string | string[];
         item: RefFieldOption;
@@ -113,7 +130,30 @@ export declare class CoRefField {
     coRemove: EventEmitter<string>;
     coFooterPrimary: EventEmitter<void>;
     coFooterSecondary: EventEmitter<void>;
+    /** Re-emisión del toggle de pin de una fila del panel (pinnable). */
+    coPinToggle: EventEmitter<{
+        item: RefFieldOption;
+    }>;
+    /** Re-emisión del drag-reorder de la lista del panel (listReorderable). */
+    coListReorder: EventEmitter<{
+        value: string[];
+        item: RefFieldOption;
+    }>;
+    /** Pencil click on the single-value trigger. Detail = selected record `_id`. */
+    coEditSelected: EventEmitter<string>;
     el: HTMLElement;
+    private triggerEl?;
+    /**
+     * Id del <co-option-list> del panel, target de `aria-controls` del trigger.
+     * Constante (no aleatoria): vive en el shadow root de ESTA instancia, donde
+     * los ids no colisionan con los de otras. Se referencia el HOST de la
+     * primitiva — su listbox interno queda tras su propio shadow boundary y no
+     * es direccionable desde acá (limitación conocida y aceptada).
+     *
+     * El trigger solo emite `aria-controls` mientras `isOpen`: el panel se monta
+     * on-demand, así que cerrado el IDREF quedaría colgante.
+     */
+    private static readonly LIST_ID;
     isOpen: boolean;
     /** How many trailing chips don't fit the trigger width (responsive mode). */
     overflowCount: number;
@@ -146,6 +186,11 @@ export declare class CoRefField {
     private handlePopoverOpen;
     private handlePopoverClose;
     private handleTriggerClick;
+    private handleTriggerKeyDown;
+    /** Devuelve el foco al trigger al cerrar el panel (Escape, selección),
+     *  salvo que el cierre venga de un click-outside que ya movió el foco a
+     *  otro elemento — en ese caso no robarlo. */
+    private restoreTriggerFocus;
     /** Change de la co-option-list: `value: null` = deselección explícita (la X
      *  de la fila) → mismo camino que la X del trigger (clear + coClear). El
      *  resto sigue por handleOptionClick con el ítem. */
@@ -153,6 +198,7 @@ export declare class CoRefField {
     private handleOptionClick;
     private handleReorder;
     private handleClear;
+    private handleEditClick;
     private handleRemoveChip;
     private handleFooterPrimary;
     private handleFooterSecondary;

package/dist/types/components/co-select/co-select.d.ts

@@ -41,13 +41,34 @@ export declare class CoSelect {
     scrollTop: number;
     searchText: string;
     private sortSnapshot;
+    /** Índice (sobre `filteredOptions`) de la opción resaltada por teclado.
+     *  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`. */
+    activeIndex: number;
     el: HTMLElement;
+    private triggerEl?;
     private optionsContainerEl?;
     private osInstance?;
     private searchInputEl?;
+    /** Scroll pendiente hacia la opción activa, resuelto en componentDidRender. */
+    private pendingActiveScroll;
+    private activeScrollFrames;
     private static readonly ITEM_HEIGHT;
     private static readonly VIEWPORT_ITEMS;
     private static readonly OVERSCAN;
+    /** Ids del shadow root (únicos por instancia sin sufijos aleatorios).
+     *  Acá `aria-controls` se emite SIEMPRE (no solo abierto) porque este nodo
+     *  listbox es permanente en el shadow root — el IDREF nunca cuelga. En
+     *  co-ref-field/co-combobox/co-color-picker el panel se monta on-demand, así
+     *  que ahí `aria-controls` va solo con el panel abierto: no unificar en la
+     *  dirección equivocada. */
+    private static readonly LISTBOX_ID;
+    /** Frames que esperamos a que el panel tenga layout para escribir el scroll.
+     *  Holgado a propósito (~0.8s a 60Hz): dentro de un co-modal/drawer animado el
+     *  layout llega tarde y con 12 frames el flush se rendía a mitad de camino —
+     *  el scroll quedaba clampeado en cualquier parte de la lista en vez de en la
+     *  opción seleccionada. El loop corta solo al verificar el write o al cerrar. */
+    private static readonly ACTIVE_SCROLL_MAX_FRAMES;
     coChange: EventEmitter<string | string[]>;
     coClear: EventEmitter<void>;
     /** Click en el botón primario del footer (el panel se cierra solo). */
@@ -67,9 +88,54 @@ export declare class CoSelect {
     private get selectedOption();
     private get displayText();
     private get statusIcon();
+    private optionId;
+    /** Al abrir, la activa arranca en la opción seleccionada (la primera de ellas
+     *  en multiple) para que las flechas continúen desde donde el usuario está. */
+    private resetActiveIndex;
     onOpenChange(open: boolean): void;
     private handleSearchInput;
     private handleTriggerClick;
+    private handleTriggerKeyDown;
+    /** Apertura por TECLADO. Congela el orden selected-first ANTES de mover
+     *  `isOpen` para que el @Watch calcule la opción activa sobre la lista
+     *  definitiva; por mouse eso ya lo garantiza handlePopoverOpen, que corre
+     *  antes del cambio de estado. */
+    private openPanel;
+    /** Navegación del panel abierto, compartida por el trigger (caso
+     *  no-searchable, donde el foco se queda ahí) y el search input (caso
+     *  searchable, donde las flechas no deben mover el caret). Devuelve `true`
+     *  si consumió la tecla — con el panel cerrado no consume nada, así el
+     *  comportamiento del trigger (Enter/Space togglean, ArrowDown abre) queda
+     *  intacto. */
+    private handleNavKeyDown;
+    private setActiveIndex;
+    /** Enter/Space sobre una opción deshabilitada no hace nada — igual que el
+     *  click (la tecla igual se consume: el panel abierto no togglea). */
+    private activateActiveOption;
+    /** Deja la opción activa dentro de la ventana virtual (state) y agenda el
+     *  scroll real para después del próximo render. */
+    private scrollActiveIntoView;
+    /** Alinea el scroll REAL con la ventana virtual ya renderizada.
+     *
+     *  Escribe `scrollTop` DIRECTO sobre el viewport de OverlayScrollbars: el
+     *  `[role="listbox"]` queda en `overflow:hidden` y OS monta su propio
+     *  elemento scrolleable, así que `scrollIntoView` desde el nodo de la opción
+     *  no siempre encuentra un ancestro que scrollee. Y reintenta unos frames
+     *  porque en la APERTURA el panel del popover todavía no tiene layout (su
+     *  ciclo de posicionamiento son 2 rAF): sin layout el `scrollTop` se clampea
+     *  a 0 en silencio y el usuario ve el panel EN BLANCO con la fila activa
+     *  renderizada fuera del área visible. */
+    private flushActiveScroll;
+    /** Enfoca el search esperando visibilidad real (paridad focusSearch de
+     *  co-option-list): el panel se posiciona 2+ rAF después de abrir — y más
+     *  tarde dentro de un modal/drawer animado — y focus() sobre un subtree sin
+     *  layout es no-op silencioso. Un solo rAF dejaba el buscador sin foco en
+     *  esos hosts. Reintenta ~20 frames; aborta si el panel se cerró. */
+    private focusSearchWhenVisible;
+    /** Devuelve el foco al trigger al cerrar el panel (Escape, selección),
+     *  salvo que el cierre venga de un click-outside que ya movió el foco a
+     *  otro elemento — en ese caso no robarlo. */
+    private restoreTriggerFocus;
     private handlePopoverOpen;
     private handlePopoverClose;
     private handleClear;
@@ -77,6 +143,7 @@ export declare class CoSelect {
     private handleOptionClick;
     private syncOverlayScrollbars;
     componentDidRender(): void;
+    componentWillLoad(): void;
     disconnectedCallback(): void;
     /** Option label with the matched substring wrapped for highlighting. */
     private renderLabel;