@prolibu-suite/cobalt-core 0.10.4 → 0.11.1

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

@@ -38,23 +38,64 @@ export declare class CoMenu {
      *  keeps its intrinsic auto width (min-width 200px). Also tune padding with the
      *  `--co-menu-padding` CSS var (default 4px; design uses 6px). */
     width?: string;
+    /** Superficie sobre la que se apoya el panel (regla transversal `surface="dark"`).
+     *  `dark` = fondo `--co-semantic-surface-primary`, texto `--co-semantic-text-inverse`,
+     *  sin anillo ni sombra, radio `--co-border-radius-xs`, `min-width: auto`. Para los
+     *  menús negros de herramienta (formas, plantillas de página, Lineal/Radial).
+     *  Reflejado a atributo para que el CSS lo lea vía `:host([surface="dark"])`.
+     *
+     *  Los `co-menu-item` (y `co-menu-divider`) hijos heredan el tema oscuro SOLOS,
+     *  sin ningún prop propio: `co-menu.css` publica variables CSS en el elemento
+     *  slotted (`::slotted(co-menu-item) { --co-menu-item-color: ...; }`) y esas
+     *  variables — al ser custom properties heredadas — atraviesan el shadow
+     *  boundary del hijo hasta su propio `:host` y de ahí a su árbol interno.
+     *  `co-menu-item`/`co-menu-divider` las consumen con fallback al valor claro
+     *  de siempre, así que sin `surface="dark"` no cambia nada. */
+    surface: 'light' | 'dark';
+    /** Elemento (o selector resuelto contra `document`) al que se alinea el
+     *  panel EN VEZ del trigger.
+     *  Reenviada tal cual al `co-popover` interno; sin `anchor`, cae al
+     *  trigger (comportamiento de siempre). Útil para alinear el menú contra
+     *  un contenedor más grande que el botón que lo abre (p.ej. la píldora del
+     *  zoom del toolbar). */
+    anchor?: HTMLElement | string;
+    /** Desplazamiento en px sobre el eje CRUZADO del `placement`. Reenviada tal
+     *  cual al `co-popover` interno. Default `0` = sin cambio. */
+    shift: number;
+    /** Se abrió el menú (toma el foco y el teclado). No burbujea. */
     coOpen: EventEmitter<void>;
+    /** Se cerró el menú (Escape, click afuera o selección con `autoClose`). No burbujea. */
     coClose: EventEmitter<void>;
     el: HTMLElement;
     /** Auto-close on leaf-item selection. Bubbled by `co-menu-item` when it has
      *  no nested submenu — submenu triggers do not emit `coMenuSelect`. */
     handleMenuSelect(): void;
     onOpenChange(isOpen: boolean): void;
+    componentDidLoad(): void;
     disconnectedCallback(): void;
+    /** Enfoca la primera fila del panel raíz (lo hace solo al abrir). */
     focusFirstItem(): Promise<void>;
     /** Walk the LIGHT DOM children for `<co-menu-item>` rows in document order.
      *  Returns the focusable inner buttons via `.focus()`-able interface — we
      *  use the host element here and rely on focus delegating to the inner
-     *  `<button>` via Stencil's `delegatesFocus`-like behavior. */
+     *  `<button>` via Stencil's `delegatesFocus`-like behavior.
+     *
+     *  Las filas son las del panel ACTIVO: el submenú abierto más profundo, o la
+     *  raíz si no hay ninguno (lo que el docstring del componente ya prometía).
+     *  Antes era un `querySelectorAll` plano, que también devolvía las filas de
+     *  los submenús CERRADOS — sus `co-menu-item` viven en el light DOM aunque su
+     *  panel no esté renderizado, así que ↓ mandaba el foco a filas invisibles.
+     *  Sin submenús el resultado es idéntico al de siempre. */
     private getMenuItems;
+    /** El submenú abierto más profundo (por el atributo `data-submenu-open` que
+     *  publica `co-menu-item`), o el propio menú si no hay ninguno abierto. */
+    private activePanel;
     private handleKeydown;
     private moveFocus;
     private handlePopoverOpen;
+    /** Publica hacia los ítems (light DOM) si el panel abrió hacia arriba, ya
+     *  resuelto el flip: sus submenús crecen en la misma dirección (utils/submenu). */
+    private handlePlacement;
     private handlePopoverClose;
     render(): any;
 }

package/dist/types/components/co-menu-divider/co-menu-divider.d.ts

@@ -1,6 +1,7 @@
 /**
  * Thin horizontal separator between groups of `co-menu-item` rows. Renders an
  * accessible `<hr>` with `role="separator"`.
+ * Wrapper Vue: `CoMenuDivider` de `@prolibu-suite/cobalt-vue`.
  */
 export declare class CoMenuDivider {
     render(): any;

package/dist/types/components/co-menu-item/co-menu-item.d.ts

@@ -13,6 +13,8 @@ import type { Placement } from '../../utils/positioning';
  *      `coSelect` — only the leaf items inside do.
  *
  * Submenu nesting is unbounded — submenu items can themselves have submenus.
+ *
+ * Wrapper Vue: `CoMenuItem` de `@prolibu-suite/cobalt-vue`.
  */
 export declare class CoMenuItem {
     /** Icon name (Phosphor) rendered before the label. Optional — rows may be
@@ -33,6 +35,14 @@ export declare class CoMenuItem {
     /** Renders a trailing check (size 15) after the label. Pair with `selected`
      *  to mark the chosen option in a single-select menu. */
     trailingCheck: boolean;
+    /** Reserva un check de 12px AL INICIO de la fila (antes del ícono/label).
+     *  A diferencia de `trailingCheck` (que solo se monta si el prop está en
+     *  true), acá el HUECO (12px + el gap de la fila) se reserva SIEMPRE que
+     *  `leadingCheck` esté activo — el `co-icon` de adentro solo se monta si
+     *  además `selected` es true, así todas las filas de un menú de selección
+     *  única (formas, plantillas de página) quedan alineadas aunque solo una
+     *  esté marcada. Pensado para menús con `co-menu surface="dark"`. */
+    leadingCheck: boolean;
     /** Visually disabled — pointer events ignored, opacity reduced. */
     disabled: boolean;
     /** `danger` shifts text + icon to the destructive color. Use for Delete, etc. */
@@ -52,6 +62,15 @@ export declare class CoMenuItem {
     submenuPlacementValue: Placement;
     private closeTimer?;
     private rowEl?;
+    /** Publica el submenú abierto como atributo del HOST (`data-submenu-open`).
+     *  Prefijo `data-`: es un atributo que el componente escribe solo, no una
+     *  API que se setea desde afuera, y sin prefijo ensuciaba el espacio de
+     *  nombres de atributos estándar (review final 2).
+     *  `submenuOpen` es `@State` y vive en el shadow: sin esto, el `co-menu`
+     *  ancestro no tiene forma de saber qué panel está activo para dirigir las
+     *  flechas (ver `getMenuItems` en co-menu.tsx). Aditivo: un atributo de solo
+     *  lectura que nadie más consume; el resto del componente no cambia. */
+    onSubmenuOpenChange(isOpen: boolean): void;
     /** Programmatic focus — used by `co-menu`'s keyboard navigation. Named
      *  `focusItem` (not `focus`) because Stencil reserves the latter (it shadows
      *  HTMLElement.prototype.focus). */

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

@@ -1,14 +1,26 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 /**
+ * Ventana modal con header (título, descripción, ✕), cuerpo y footer de
+ * acciones, sobre un scrim que bloquea la página (`co-overlay`). Es
+ * controlada: la ✕, el scrim y Escape solo emiten `coClose`; quien la usa pone
+ * `open` en `false`. Wrapper Vue: `CoModal` de `@prolibu-suite/cobalt-vue`.
+ *
  * @slot        - Modal body content
  * @slot header-leading - Control before the heading (e.g. a back arrow on a
  *                        second screen of the same modal)
  * @slot header-actions - Controls at the right end of the header (e.g. a settings
  *                        icon-button), before the close button
  * @slot footer - Footer with action buttons
- * @part modal | header | header-text | heading | description | body | footer -
- *       layout/typography hooks for a consumer that must match a specific spec
- *       (paddings, heading weight); colors stay on semantic tokens
+ *
+ * Los parts son ganchos de layout y tipografía (paddings, peso del título) para
+ * ajustar a una spec puntual; los colores siguen en tokens semánticos.
+ * @part modal - Panel del modal (superficie, radio y sombra).
+ * @part header - Header completo; con `movable` es la zona de arrastre.
+ * @part header-text - Contenedor del título y la descripción.
+ * @part heading - Título (`heading`).
+ * @part description - Descripción bajo el título.
+ * @part body - Cuerpo (slot por defecto).
+ * @part footer - Footer de acciones (slot `footer`).
  */
 export declare class CoModal {
     /** Whether the modal is visible */
@@ -32,19 +44,77 @@ export declare class CoModal {
      */
     closeOnEscape: boolean;
     /**
-     * Modal width: sm (400px), md (540px), lg (680px),
+     * Modal width: xs (369px, vía `--co-modal-width` — paneles anclados como
+     * "Tipografía y color"), sm (400px), md (540px), lg (680px),
      * full (min(1400px, 95vw) × 92vh — media/document viewers).
      *
      * `full` also drops the body padding and lets the body grow, so a slotted
      * <video>/<iframe> fills the panel edge-to-edge instead of sitting in a
      * content-height box.
      */
-    size: 'sm' | 'md' | 'lg' | 'full';
+    size: 'xs' | 'sm' | 'md' | 'lg' | 'full';
     /** Hide body section and all border dividers (compact confirm dialogs) */
     noDividers: boolean;
     /** Hairline between header and body. `false` lets the body run straight
      *  under the heading (Figma modals whose first row is a segmented control). */
     headerDivider: boolean;
+    /**
+     * Visual treatment. `default` = superficie squircle actual
+     * (radio `--co-modal-r`, sombra que sigue la silueta). `panel` = superficie
+     * plana (radio 12, borde `--co-semantic-border-subtle`, `--co-shadow-lg`),
+     * SIN máscara squircle — look de panel anclado, no de diálogo centrado.
+     *
+     * `dialog` = la anatomía del componente "Modal" del design system
+     * (Figma Prolibu UI Suite, nodo `1179:37247`): superficie plana radio 16
+     * (`--co-border-radius-lg`) sin borde ni sombra propios, título 22/500 y
+     * cuerpo 16/1.5 `text-secondary` sin divisor entre ambos, padding 32
+     * (`--co-spacing-3xl`), footer 16/24 con hairline `border-subtle` y botones
+     * cuadrados de radio 12. Sin máscara squircle. El ✕ (si `closable`) es el
+     * redondo de 32 del modo `panel`.
+     */
+    appearance: 'default' | 'panel' | 'dialog';
+    /**
+     * Control del scrim. `none` = sin fondo oscuro y sin cierre por
+     * clic afuera — independiente de `closeOnOverlay` (que solo aplica cuando
+     * SÍ hay scrim). `co-overlay` es quien posee el único `<div>` de scrim del
+     * árbol, así que `none` implica no montar `<co-overlay>` (ver `inline`).
+     */
+    backdrop: 'default' | 'none';
+    /**
+     * Renderiza en `position: fixed` con su propio `--co-modal-z-index` en vez
+     * de promoverse al TOP LAYER del browser. `co-overlay` promueve
+     * su scrim al top layer vía Popover API (`showPopover()`); el top layer
+     * SIEMPRE pinta por encima de cualquier `z-index` normal, así que un
+     * portal propio del consumidor (selector de fuente/color del editor) con
+     * z-index alto quedaría igual TAPADO detrás del modal. `inline` evita eso.
+     *
+     * `co-overlay` es también quien posee la promoción a top layer — no hay
+     * forma de pedirle "no te promuevas" sin tocar ese componente, así que,
+     * igual que `backdrop="none"`, `inline`
+     * implica no montar `<co-overlay>`: el panel pasa a posicionarse y apilarse
+     * solo (`.co-modal__frame--standalone`, ver co-modal.css).
+     */
+    inline: boolean;
+    /**
+     * Opt-in: el modal se MUEVE arrastrando su header. Default false →
+     * los consumidores actuales quedan byte-idénticos (ni DOM ni CSS cambian).
+     *
+     * Con `movable`, el `part="header"` entero es la zona de agarre (`cursor:
+     * grab`), salvo los controles que contenga (el ✕, y cualquier botón, enlace
+     * o campo: ver `isInteractiveDragTarget`). Soltar confirma la posición;
+     * `pointercancel` o perder el foco de la ventana la CANCELAN y dejan la
+     * anterior. La posición no se persiste: cerrar y reabrir devuelve el panel a
+     * su lugar por defecto.
+     *
+     * Se llama `movable` y no `draggable` a propósito: `draggable` es un atributo
+     * global de HTML (arrastre nativo HTML5) y una prop de React, y una prop del
+     * mismo nombre taparía `HTMLElement.draggable` con dos semánticas encimadas.
+     */
+    movable: boolean;
+    /** Verdadero cuando NO corresponde montar `<co-overlay>` — ver doc de
+     *  `backdrop` e `inline` arriba: ambas comparten el mismo mecanismo porque
+     *  co-overlay es la única superficie dueña del scrim Y del top layer. */
+    private get usesOverlay();
     /** Emitted when the modal requests to close */
     coClose: EventEmitter<void>;
     /** Close animation finished. */
@@ -56,8 +126,59 @@ export declare class CoModal {
     private handleFooterSlotChange;
     private handleOverlayClick;
     private handleCloseClick;
+    /** Freno del clic del panel: existe SOLO para que un clic adentro no llegue
+     *  al `<co-overlay>`, que cierra con cualquier clic sobre su div. Sin
+     *  overlay (`inline` / `backdrop="none"`) no hay nada que proteger, y el
+     *  freno se tragaba los `onClick` de React del contenido proyectado (React
+     *  delega en la raíz; el camino compuesto del evento cruza este div). Por
+     *  eso se monta condicionado a `usesOverlay` — ver `render()`. */
     private stopPropagation;
     handleKeydown(e: KeyboardEvent): void;
     private handleTransitionEnd;
+    /** Gesto en curso: pinta el cursor `grabbing` (única razón para re-render). */
+    dragging: boolean;
+    /** Desplazamiento YA confirmado. El gesto siguiente arranca desde acá. */
+    private committedOffset;
+    /** Desplazamiento en vivo (= el confirmado mientras no hay gesto). */
+    private liveOffset;
+    private dragPointerId?;
+    private dragStart?;
+    /** Caja del panel y viewport medidos UNA vez al empezar: nada de rects por `pointermove`. */
+    private dragRect?;
+    private dragViewport?;
+    private headerEl?;
+    /**
+     * La posición no se persiste: cada APERTURA arranca desde la posición por
+     * defecto. El reset va al abrir y no al cerrar a propósito — reseteando al
+     * cerrar, el panel se teletransportaba al centro mientras corría su
+     * animación de salida (un consumidor que lo deja montado y solo apaga
+     * `open` lo veía saltar).
+     */
+    resetPositionOnOpen(open: boolean): void;
+    private handleDragDown;
+    private handleDragMove;
+    /** Soltar CONFIRMA la posición alcanzada. */
+    private handleDragUp;
+    /** `pointercancel` CANCELA: el panel vuelve a la última posición confirmada. */
+    private handleDragCancel;
+    /** Perder el foco de la ventana (alt-tab, un iframe que se lo lleva) cancela igual que `pointercancel`. */
+    private handleWindowBlur;
+    disconnectedCallback(): void;
+    private endDrag;
+    /** `==`: en jsdom los MouseEvent traen `pointerId` undefined y deben seguir pasando. */
+    private isActiveDragPointer;
+    /** `setPointerCapture` sigue el gesto fuera del header (y garantiza el `pointercancel`). */
+    private capturePointer;
+    private releasePointer;
+    /**
+     * Escribe el desplazamiento como custom property en el panel; la regla que la
+     * consume vive en `.co-modal--movable` (co-modal.css).
+     *
+     * Va por el DOM y no por el `style` del vdom a propósito: el `transform` del
+     * panel es la animación de apertura (`scale`), así que el desplazamiento usa
+     * la propiedad independiente `translate` — se compone con ese transform, no
+     * dispara layout, y al no declararla el vdom ningún re-render la pisa.
+     */
+    private writeOffset;
     render(): any;
 }

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

@@ -1,7 +1,9 @@
 /**
  * Horizontal toolbar container. Place any content inside the default slot.
  * Works like Quasar's q-toolbar — a styled flex row.
+ * Wrapper Vue: `CoNavbar` de `@prolibu-suite/cobalt-vue`.
  * @slot - Content (buttons, titles, icons, etc.)
+ * @part navbar - La barra.
  */
 export declare class CoNavbar {
     /** Visual variant */

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

@@ -1,13 +1,26 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * Campo numérico con botones −/+, flechas del teclado para escalonar, límites
+ * `min`/`max` y formatos de tasa, porcentaje o monto. Wrapper Vue:
+ * `CoNumberField` de `@prolibu-suite/cobalt-vue`.
+ *
+ * @part row - Fila del campo: input y botones −/+.
+ * @part input - El `<input>` nativo.
+ */
 export declare class CoNumberField {
+    /** Etiqueta del campo. */
     label?: string;
     /** Whether the field is required (renders a required marker on the label). */
     required: boolean;
+    /** Texto secundario junto a la etiqueta. */
     secondaryLabel?: string;
+    /** Texto de ayuda o de error bajo el campo. */
     helperText?: string;
     /** Label layout: vertical (label above) or horizontal (label beside) */
     layout: 'vertical' | 'horizontal';
+    /** Estado de validación: pinta el borde y el `helperText` con el color del estado. */
     status: 'default' | 'error' | 'success' | 'warning' | 'info';
+    /** Valor numérico (reflejado); `null` = vacío (solo alcanzable con `clearable`). El componente lo actualiza. */
     value: number | null;
     /**
      * Refleja en el <input> los cambios de `value` que vienen de AFUERA (host que
@@ -18,11 +31,17 @@ export declare class CoNumberField {
      * el usuario tipea, su propio input manda — no lo pisamos (movería el caret).
      */
     onValueChange(): void;
+    /** Mínimo: los valores se recortan a este límite. */
     min?: number;
+    /** Máximo: los valores se recortan a este límite. */
     max?: number;
+    /** Paso de los botones −/+ y de las flechas (default 1). */
     step: number;
+    /** Deshabilita el campo y los botones. */
     disabled: boolean;
+    /** Placeholder del campo vacío (default `'0'`). */
     placeholder: string;
+    /** Alto del campo: `s` 28 · `sm` 32 · `md` 40 (default) · `lg` 48. */
     size: 's' | 'sm' | 'md' | 'lg';
     /** Show clear button when the field has a value */
     clearable: boolean;
@@ -57,6 +76,7 @@ export declare class CoNumberField {
      */
     private emptiedByUser;
     el: HTMLElement;
+    /** Cambió el valor (ya recortado a `min`/`max`; `value` ya está actualizado): `detail` = número, o `null` al vaciar con `clearable`. */
     coChange: EventEmitter<number | null>;
     /** Emitted when the clear button is clicked */
     coClear: EventEmitter<void>;

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

@@ -7,8 +7,16 @@ import type { OptionListItem } from './optionListLogic';
  *
  * 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.
+ * Wrapper Vue: `CoOptionList` de `@prolibu-suite/cobalt-vue`. Sus eventos NO
+ * burbujean ni cruzan el shadow DOM: se escuchan sobre el propio elemento.
  *
+ * @slot header - Entre el buscador y la lista (filtros por categoría de una paleta). UN elemento siempre montado.
  * @slot footer - Footer del panel (normalmente <co-list-footer>).
+ *
+ * @part search - Contenedor del buscador integrado (solo con `searchable`).
+ * @part options - Contenedor scrolleable de las filas.
+ * @part icon-tile - Recuadro tintado del ícono de una fila (`item.icon` + `item.iconTint`).
+ * @part drag-handle - Tirador de arrastre de una fila (con `reorderable` o `listReorderable`).
  */
 export declare class CoOptionList {
     el: HTMLElement;
@@ -18,6 +26,8 @@ export declare class CoOptionList {
     value: string;
     /** Display-items de la selección (para selected-first con ids fuera de página). */
     selectedItems: string | OptionListItem[];
+    /** Selección múltiple: `value` es un JSON array de ids y `coChange` emite el
+     *  array completo; con `false` (default) la selección es un solo id. */
     multiple: boolean;
     /** Partición selected-first (snapshot al llamar snapshotOrder()). */
     selectedFirst: boolean;
@@ -34,16 +44,23 @@ export declare class CoOptionList {
      *  filas no-pineadas, emite coListReorder con el orden visible completo.
      *  Independiente de multiple/selectedFirst. No soportado con `virtual`. */
     listReorderable: boolean;
+    /** Muestra el buscador integrado arriba de la lista (reflejado como atributo).
+     *  El filtrado lo hace el host al recibir `coSearch`. */
     searchable: boolean;
+    /** Placeholder del buscador integrado. */
     searchPlaceholder: string;
+    /** Espera en ms entre la última tecla y el `coSearch` (default 350). */
     searchDebounce: number;
     /** Pre-seed del término (modo convert de las celdas). */
     initialTerm: string;
+    /** Cargando: sin filas muestra un loader en lugar de la lista; con filas,
+     *  un loader al pie. Mientras está activo no se emite `coLoadMore`. */
     loading: boolean;
     /** Total del server: deriva hasMore + hint "N more results". */
     total: number;
     /** Fallback cuando el host no conoce totales (⌘K). total>0 manda. */
     hasMore: boolean;
+    /** Texto cuando no hay filas y no se está cargando. */
     emptyMessage: string;
     /** Si se setea y hay selección, fila "quitar selección" al tope. */
     clearOptionLabel: string;
@@ -53,6 +70,7 @@ export declare class CoOptionList {
     highlightMatches: boolean;
     /** Término externo para highlight (input en el host, p.ej. ⌘K). */
     highlightTerm: string;
+    /** Forma del `co-avatar` de las filas que traen avatar: `circle` (default) o `square`. */
     avatarShape: 'circle' | 'square';
     /** `end` pinta el suffix como columna a la derecha de la fila (precio/meta),
      *  sin el guion; `inline` = junto al label (default). */
@@ -61,13 +79,23 @@ export declare class CoOptionList {
      *  items (paridad command-palette: tipear + Enter = primer resultado).
      *  Salta filas disabled vía nextActiveIndex. */
     autoHighlight: boolean;
+    /** Término del buscador integrado, con debounce (`searchDebounce`); `''` al vaciarlo
+     *  o tras `clearSearch()`. No burbujea. */
     coSearch: EventEmitter<string>;
+    /** Selección pedida (el componente no muta `value`). `detail.value`: el id elegido,
+     *  el array completo en `multiple`, o `null` al deseleccionar en single;
+     *  `detail.item`: la fila involucrada. No burbujea. */
     coChange: EventEmitter<{
         value: string | string[] | null;
         item: OptionListItem;
     }>;
+    /** Pide la página siguiente: al acercarse el scroll al final, o si las filas
+     *  cargadas no llenan el panel. Solo con más resultados (`total`/`hasMore`) y
+     *  sin `loading`. Sin `detail`. No burbujea. */
     coLoadMore: EventEmitter<void>;
+    /** Click en la fila «quitar selección» (`clearOptionLabel`). Sin `detail`. No burbujea. */
     coClearSelection: EventEmitter<void>;
+    /** Click en la X de una fila seleccionada (`removableItems`); `detail` = id de la fila. No burbujea. */
     coRemoveItem: EventEmitter<string>;
     /** Emitido tras un drag-reorder: nuevo orden de ids seleccionados + ítem movido. */
     coReorder: EventEmitter<{
@@ -133,7 +161,6 @@ export declare class CoOptionList {
      * mismo orden → deltas 0 → no-op visual.
      */
     onValueChange(): void;
-    /** Re-toma el snapshot selected-first. El host la llama al abrir su panel. */
     /**
      * Vacía el buscador (texto, término y cualquier coSearch en vuelo) y emite
      * `coSearch('')`. Para hosts que reabren el panel (co-popover): el término
@@ -141,6 +168,7 @@ export declare class CoOptionList {
      * host ya sin filtrar.
      */
     clearSearch(): Promise<void>;
+    /** Re-toma el snapshot selected-first. El host la llama al abrir su panel. */
     snapshotOrder(): Promise<void>;
     /**
      * Enfoca el input de búsqueda esperando visibilidad real: el panel del host

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

@@ -19,6 +19,9 @@ export interface OptionListItem {
     };
     /** Phosphor icon como leading visual (si no hay avatar/color). */
     icon?: string;
+    /** Tinte del icono (CSS color, p.ej. `var(--co-color-primary-azul)`): pinta el icono en un tile de 22px con el
+     *  tinte al 12 % de fondo (paletas por categoría). Sin él, el icono va pelado como siempre. */
+    iconTint?: string;
     /** Color del dot / ring del avatar. */
     color?: string;
     /** Iniciales del avatar. */

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

@@ -1,4 +1,14 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * Capa de fondo (scrim) para contenido modal: bloquea el scroll de la página
+ * (compartido entre overlays apilados), sube al top layer y puede atrapar el
+ * foco. Es controlado: un click en el fondo o Escape (`closeOnEscape`) solo
+ * emiten `coClose`. Base de `co-modal`, `co-drawer` y `co-command-search`.
+ * Wrapper Vue: `CoOverlay` de `@prolibu-suite/cobalt-vue`.
+ *
+ * @slot - Contenido centrado sobre el fondo.
+ * @part overlay - El fondo oscuro.
+ */
 export declare class CoOverlay {
     el: HTMLElement;
     /** Whether the overlay is visible */

package/dist/types/components/co-page-header/co-page-header.d.ts

@@ -2,6 +2,9 @@
  * Page-level header bar with icon, title, and right actions.
  * @slot        - Title area (default slot)
  * @slot actions - Right-side actions (switches, buttons)
+ *
+ * Wrapper Vue: `CoPageHeader` de `@prolibu-suite/cobalt-vue`.
+ * @part page-header - La fila del encabezado.
  */
 export declare class CoPageHeader {
     /** Title text */

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

@@ -1,6 +1,17 @@
 import { EventEmitter } from '../../stencil-public-runtime';
 import { Placement } from '../../utils/positioning';
 export type PopoverPlacement = Placement;
+/**
+ * Panel flotante anclado a un disparador (slot `trigger`) con posicionamiento,
+ * volteo si no cabe y cierre por click afuera o Escape. Base de menús, selects y
+ * pickers. Sus eventos no burbujean. Wrapper Vue: `CoPopover` de
+ * `@prolibu-suite/cobalt-vue`.
+ *
+ * @slot trigger - Elemento que abre y cierra el panel al hacer click.
+ * @slot - Contenido del panel.
+ *
+ * @part panel - El panel flotante (fondo, borde, sombra).
+ */
 export declare class CoPopover {
     /** Whether the popover panel is visible. */
     open: boolean;
@@ -23,7 +34,34 @@ export declare class CoPopover {
     closeOnEscape: boolean;
     /** Flip placement when the panel would overflow the viewport. */
     flip: boolean;
+    /**
+     * El panel no pinta fondo/borde/sombra propios:
+     * para alojar un `co-menu` (u otro contenido con su propio chrome) sin
+     * "doble chrome". Reflejado como atributo `bare`. Default `false` = panel
+     * con el fondo/borde/sombra de siempre (`--co-popover-border-color` /
+     * `--co-popover-shadow`), sin cambio.
+     */
+    bare: boolean;
+    /**
+     * Elemento (o selector resuelto contra `document`) al que se alinea el
+     * panel EN VEZ del trigger — p.ej. la píldora
+     * completa del zoom, no solo el botón "▾" que abre el menú. Un selector sin
+     * match cae al trigger (comportamiento actual). Sin `anchor`, cero cambio.
+     */
+    anchor?: HTMLElement | string;
+    /**
+     * Desplazamiento en px sobre el eje CRUZADO del `placement`: con un placement vertical (`top*`/`bottom*`) mueve `left`; con
+     * uno horizontal (`left*`/`right*`) mueve `top`. Default 0 = sin cambio.
+     *
+     * ⚠️ Se aplica ANTES del clamp de 4px a los bordes del viewport (ver
+     * `computePosition` en `utils/positioning.ts`) — un `shift` grande cerca de
+     * un borde puede quedar clampeado igual que hoy, no lo evita. No hay forma
+     * de pedir un `shift` que se salga de pantalla a propósito.
+     */
+    shift: number;
+    /** Se abrió el panel. No burbujea. */
     coOpen: EventEmitter<void>;
+    /** Se cerró el panel (click afuera, Escape, método o el ancla salió de la vista). No burbujea. */
     coClose: EventEmitter<void>;
     /** El placement REAL con el que quedó el panel, ya pasado por el flip — que
      *  puede no ser el de la prop `placement`. Lo consume `co-menu-item` para que
@@ -43,6 +81,8 @@ export declare class CoPopover {
     private triggerEl?;
     private panelEl?;
     private rafId?;
+    /** El trigger se vio al menos una vez desde que abrió (ver `updatePosition`). */
+    private anchorSeenVisible;
     private scrollParents;
     private cachedOffsetAncestor;
     private offsetAncestorComputed;
@@ -54,14 +94,25 @@ export declare class CoPopover {
     private handlePanelTransitionEnd;
     private bindDocListeners;
     private unbindDocListeners;
+    /** Abre o cierra el panel. */
     toggle(): Promise<void>;
+    /** Abre el panel. */
     show(): Promise<void>;
+    /** Cierra el panel. */
     hide(): Promise<void>;
     private pressStartedInside;
     private handleDocumentPointerDownManual;
     private handleDocumentClickManual;
     private handleDocumentKeydownManual;
     private updatePosition;
+    /**
+     * Resuelve la prop `anchor` a un elemento:
+     *   - `HTMLElement` → se usa tal cual.
+     *   - `string` → selector resuelto contra `document`; sin match, `null`
+     *     (el llamador cae a `triggerRect`, el comportamiento de siempre).
+     *   - sin `anchor` → `null` (mismo fallback).
+     */
+    private resolveAnchor;
     /**
      * Promote the panel to the browser top layer (Popover API) so an ancestor's
      * filter / mask / overflow / transform can't clip it. Mirrors co-overlay.

package/dist/types/components/co-progress-bar/co-progress-bar.d.ts

@@ -1,5 +1,8 @@
 /**
  * A horizontal progress bar with status colors.
+ * Wrapper Vue: `CoProgressBar` de `@prolibu-suite/cobalt-vue`.
+ *
+ * @part bar - Contenedor de la barra (pista y relleno).
  */
 export declare class CoProgressBar {
     /** Progress value 0-100 */

package/dist/types/components/co-progress-circle/co-progress-circle.d.ts

@@ -1,5 +1,8 @@
 /**
  * A circular progress indicator with status colors and optional label.
+ * Wrapper Vue: `CoProgressCircle` de `@prolibu-suite/cobalt-vue`.
+ *
+ * @part circle - Contenedor del círculo (SVG y etiqueta).
  */
 export declare class CoProgressCircle {
     /** Progress value 0-100 */

package/dist/types/components/co-provider-logo/co-provider-logo.d.ts

@@ -5,6 +5,9 @@
  * `plated` lo monta sobre un disco blanco: es lo que hace legible una marca a
  * color cuando va encima de una superficie teñida (el badge de un evento de
  * calendario externo, que hereda el color del calendario).
+ * Wrapper Vue: `CoProviderLogo` de `@prolibu-suite/cobalt-vue`.
+ *
+ * @part root - Contenedor del logo (el disco blanco con `plated`).
  */
 export declare class CoProviderLogo {
     /** Proveedor: `google` | `microsoft`. Uno desconocido no pinta nada. */

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

@@ -1,4 +1,12 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * Botón de opción individual con etiqueta; normalmente se agrupa en un
+ * `co-radio-group`, que coordina la selección única. Wrapper Vue: `CoRadio` de
+ * `@prolibu-suite/cobalt-vue`.
+ *
+ * @part circle - El círculo del radio.
+ * @part label - La etiqueta.
+ */
 export declare class CoRadio {
     /** Whether the radio is selected */
     checked: boolean;

package/dist/types/components/co-radio-group/co-radio-group.d.ts

@@ -7,6 +7,11 @@ export interface RadioOption {
     /** Disable this specific option */
     disabled?: boolean;
 }
+/**
+ * Grupo de opciones de selección única con etiqueta, ayuda y estado de
+ * validación: `options` define los radios y `value` el elegido. Wrapper Vue:
+ * `CoRadioGroup` de `@prolibu-suite/cobalt-vue`.
+ */
 export declare class CoRadioGroup {
     /** Group label displayed above the options */
     label?: string;

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

@@ -1,15 +1,30 @@
 import { EventEmitter } from '../../stencil-public-runtime';
+/**
+ * Calificación con estrellas (u otro ícono): el usuario elige de 1 a `max` y
+ * volver a elegir el valor actual lo pone en 0. Wrapper Vue: `CoRating` de
+ * `@prolibu-suite/cobalt-vue`.
+ */
 export declare class CoRating {
+    /** Etiqueta del campo. */
     label?: string;
+    /** Calificación actual, 0 a `max` (reflejado; el componente lo actualiza al elegir). */
     value: number;
+    /** Cantidad de íconos (default 5). */
     max: number;
+    /** Tamaño de los íconos: `small` (default) o `large`. */
     size: 'small' | 'large';
+    /** Deshabilita la interacción y atenúa el control. */
     disabled: boolean;
+    /** Solo muestra el valor, sin interacción ni hover (atributo `read-only`). */
     readOnly: boolean;
+    /** Ícono Phosphor de cada paso (default `star`). */
     icon: string;
+    /** Texto de ayuda o de error bajo el control. */
     helperText?: string;
+    /** Estado de validación: colorea el `helperText`. */
     status: 'default' | 'error' | 'success' | 'warning' | 'info';
     hoverValue: number;
+    /** Cambió la calificación (`value` ya está actualizado); `detail` = nuevo valor (0 si se desmarcó). */
     coChange: EventEmitter<number>;
     private get statusIcon();
     private handleClick;