@prolibu-suite/cobalt-core 0.11.0 → 0.11.2

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,9 +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;
@@ -19,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;
@@ -35,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;
@@ -54,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). */
@@ -62,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<{
@@ -134,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
@@ -142,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-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 */
@@ -8,6 +18,11 @@ export declare class CoOverlay {
      * previously-focused element, moves focus into the overlay, cycles Tab /
      * Shift+Tab within the slotted content, and restores focus on close.
      * Default false → existing consumers are unchanged.
+     *
+     * The walk is COMPOSED (shadow roots + assigned slots): it reaches the
+     * consumer's content projected through a host's slots and the inner control
+     * of every co-* (a co-button's `<button>`). With several traps open, only the
+     * most recent one handles Tab.
      */
     trapFocus: boolean;
     /**
@@ -27,9 +42,28 @@ export declare class CoOverlay {
     private overlayEl?;
     /** Element focused before the trap engaged, restored on close. */
     private returnFocusEl?;
+    /** Identidad de esta instancia en `trapStack`. */
+    private readonly trapId;
+    /** Whether THIS instance is currently in `trapStack` (prevents double push). */
+    private trapping;
     onOpenChange(isOpen: boolean): void;
+    onTrapFocusChange(): void;
     componentDidLoad(): void;
     disconnectedCallback(): void;
+    /**
+     * Re-promueve el scrim al TOPE del top layer (QA 2026-09-24, «Generar
+     * contrato»): un drawer abierto DESPUÉS de un modal pintaba encima, porque en
+     * el top layer gana el último promovido y no hay z-index que lo corrija.
+     * `hidePopover()` + `showPopover()` lo vuelven a meter último.
+     *
+     * No es un cierre: no emite `coClose` / `coAfterClose` / `coAfterOpen`, no
+     * toca `open` ni el scroll lock, y no re-anima la entrada (la clase
+     * `co-overlay--refront` anula la transición durante el re-show y se retira en
+     * el frame siguiente). Tampoco mueve el foco: si el re-show dispara los
+     * «popover focusing steps» (un `[autofocus]` adentro), se devuelve a donde
+     * estaba. No-op cerrado, sin Popover API o fuera del top layer.
+     */
+    bringToFront(): Promise<void>;
     private acquireLock;
     private releaseLock;
     /**
@@ -42,7 +76,11 @@ export declare class CoOverlay {
      * reconciliation are untouched. No-ops gracefully where unsupported.
      */
     private syncPopover;
-    /** Record the current focus and move it into the overlay (guarded by trapFocus). */
+    /** La trampa está activa exactamente mientras el overlay está abierto con `trapFocus`. */
+    private syncTrap;
+    private engageTrap;
+    private releaseTrap;
+    /** Record the current focus and move it into the overlay (only while trapping). */
     private captureAndFocus;
     /** Restore focus to the element that had it before the trap engaged. */
     private restoreFocus;

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

@@ -13,8 +13,29 @@ export declare const FOCUSABLE_SELECTOR: string;
  */
 export declare function resolveTabIndex(count: number, activeIndex: number, shiftKey: boolean): number;
 /**
- * Collect the tabbable elements slotted into the overlay's light DOM, skipping
- * hidden / aria-hidden ones. (Focusables nested inside further shadow roots are
- * out of scope — the common dialog/modal content lives in the slotted subtree.)
+ * Collect the tabbable elements in the overlay's light DOM, skipping hidden /
+ * aria-hidden ones.
+ *
+ * Kept for compatibility only — co-overlay no longer uses it: it cannot see past
+ * a shadow root, and co-overlay lives INSIDE co-modal's shadow, so its light DOM
+ * is the modal frame (the ✕) and never the consumer's slotted content nor the
+ * inner `<button>` of a co-button. Use `getComposedFocusables`.
  */
 export declare function getFocusableElements(root: ParentNode): HTMLElement[];
+/**
+ * Paradas de Tab dentro de `root` en el árbol COMPUESTO (shadowRoots + slots
+ * asignados), con las mismas exclusiones que `getFocusableElements`.
+ */
+export declare function getComposedFocusables(root: Element): HTMLElement[];
+/**
+ * Dónde cae el foco al abrir la trampa: el primer `[autofocus]` del recorrido
+ * compuesto —si es un host con shadow (`<co-input autofocus>`), su primer
+ * enfocable compuesto—; si no hay, la primera parada de Tab. `null` = nada
+ * enfocable (el llamador cae al contenedor).
+ */
+export declare function resolveInitialFocus(root: Element): HTMLElement | null;
+/**
+ * Con dos trampas abiertas (un confirm sobre un modal, un modal anidado) las dos
+ * escuchan el keydown de document: solo la capa MÁS RECIENTE maneja Tab.
+ */
+export declare function isTopTrap(stack: readonly string[], id: string): boolean;

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;
@@ -24,7 +35,7 @@ export declare class CoPopover {
     /** Flip placement when the panel would overflow the viewport. */
     flip: boolean;
     /**
-     * El panel no pinta fondo/borde/sombra propios (Task C10, Fase 2 Cobalt):
+     * 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` /
@@ -33,14 +44,13 @@ export declare class CoPopover {
     bare: boolean;
     /**
      * Elemento (o selector resuelto contra `document`) al que se alinea el
-     * panel EN VEZ del trigger (Task C10, Fase 2 Cobalt) — p.ej. la píldora
+     * 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` (Task C10, Fase
-     * 2 Cobalt): con un placement vertical (`top*`/`bottom*`) mueve `left`; con
+     * 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
@@ -49,7 +59,9 @@ export declare class CoPopover {
      * 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
@@ -82,8 +94,11 @@ 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;
@@ -91,7 +106,7 @@ export declare class CoPopover {
     private handleDocumentKeydownManual;
     private updatePosition;
     /**
-     * Resuelve la prop `anchor` a un elemento (Task C10, Fase 2 Cobalt):
+     * 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).

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;

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

@@ -19,15 +19,39 @@ export interface RefFieldDisplayItem {
     avatar?: string;
     image?: string;
 }
+/**
+ * Campo para elegir uno o varios registros relacionados (contactos, empresas,
+ * workspaces…) con búsqueda y paginación del lado del host: el componente pinta
+ * el trigger y el panel (`co-option-list`) y emite `coSearch`/`coLoadMore`; el
+ * host responde con `options`, `total` y `loading`. Wrapper Vue: `CoRefField` de
+ * `@prolibu-suite/cobalt-vue`.
+ *
+ * @slot panel - Reemplaza la lista del panel por contenido propio del host (su búsqueda, opciones y accesibilidad); se conservan el chrome del panel y el footer. Selecciona con `selectOption()`.
+ * @slot panel-footer - Contenido libre al pie de la lista del panel (p. ej. un switch), encima de los botones de `showFooter`.
+ *
+ * @part trigger-text - Texto del valor seleccionado en el trigger (modo single).
+ * @part trigger-placeholder - Placeholder del trigger sin valor.
+ * @part trigger-inherited - Texto del valor heredado (`inheritedLabel`) cuando no hay valor.
+ * @part trigger-inherited-badge - Chip junto al valor heredado (`inheritedBadgeLabel`).
+ * @part trigger-badge - Insignia de estado tras el valor (`triggerBadgeIcon`).
+ * @part trigger-edit - Botón lápiz del trigger (`editable`).
+ * @part trigger-clear - Botón × que vacía la selección (`clearable`).
+ * @part trigger-chevron - Ícono de apertura del panel.
+ */
 export declare class CoRefField {
+    /** 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 (p. ej. «Opcional»). */
     secondaryLabel?: string;
     /** Phosphor icon name rendered before the label text. */
     labelIcon?: string;
+    /** Texto del trigger sin valor (salvo que haya `inheritedLabel`). */
     placeholder: string;
+    /** Deshabilita el campo: no abre el panel ni muestra × ni lápiz. */
     disabled: boolean;
+    /** Muestra la × que vacía la selección cuando hay valor (default `true`); emite `coClear`. */
     clearable: boolean;
     /** Shows a pencil button on the single-value trigger that emits
      *  `coEditSelected` with the selected record id. The host owns policy
@@ -35,9 +59,13 @@ export declare class CoRefField {
     editable: boolean;
     /** Accessible name / tooltip for the edit button. */
     editLabel: string;
+    /** Selección múltiple: la selección se pinta como chips y `value` es un JSON array de ids. */
     multiple: boolean;
+    /** Estado de validación: pinta el borde y el `helperText` con el color del estado. */
     status: 'default' | 'error' | 'success' | 'warning';
+    /** Texto de ayuda o de error bajo el campo. */
     helperText?: string;
+    /** Ícono Phosphor al inicio del trigger. */
     iconLeft?: string;
     /** Label layout: vertical (label above) or horizontal (label beside) */
     layout: 'vertical' | 'horizontal';
@@ -65,9 +93,13 @@ export declare class CoRefField {
     loading: boolean;
     /** Total count of matching records from the API. */
     total: number;
+    /** Buscador en el panel (default `true`); el filtrado lo hace el host al recibir `coSearch`. */
     searchable: boolean;
+    /** Placeholder del buscador del panel. */
     searchPlaceholder: string;
+    /** Espera en ms entre la última tecla y el `coSearch` (default 350). */
     searchDebounce: number;
+    /** Texto del panel cuando no hay opciones. */
     emptyMessage: string;
     /** Show footer buttons (same pattern as co-combobox). */
     showFooter: boolean;
@@ -127,17 +159,27 @@ export declare class CoRefField {
     pinnable: boolean;
     /** Drag-reorder de la lista del panel (forward a co-option-list). */
     listReorderable: boolean;
+    /** Cambió la selección (el componente ya actualizó `value`). `detail.value`: el id
+     *  elegido, o el array completo en `multiple`; `detail.item`: la opción elegida o quitada. */
     coChange: EventEmitter<{
         value: string | string[];
         item: RefFieldOption;
     }>;
+    /** Se vació la selección (× del trigger o deselección de la fila en single). Sin `detail`. */
     coClear: EventEmitter<void>;
+    /** Término del buscador del panel, con debounce. El host filtra y responde con `options`. */
     coSearch: EventEmitter<string>;
+    /** Pide la página siguiente de opciones (scroll al final del panel). Sin `detail`. */
     coLoadMore: EventEmitter<void>;
+    /** Se abrió el panel. No burbujea. */
     coOpen: EventEmitter<void>;
+    /** Se cerró el panel. No burbujea. */
     coClose: EventEmitter<void>;
+    /** Se quitó un chip en `multiple`; `detail` = id quitado. También sale `coChange` con la selección nueva. */
     coRemove: EventEmitter<string>;
+    /** Click en el botón primario del footer (`showFooter`); cierra el panel. Sin `detail`. */
     coFooterPrimary: EventEmitter<void>;
+    /** Click en el botón secundario del footer (p. ej. «Nuevo»); el panel queda abierto. Sin `detail`. */
     coFooterSecondary: EventEmitter<void>;
     /** Re-emisión del toggle de pin de una fila del panel (pinnable). */
     coPinToggle: EventEmitter<{

package/dist/types/components/co-rich-text-editor/co-rich-text-editor.d.ts

@@ -7,11 +7,19 @@ import type { Editor, RichTextOutput, RichTextPreset, ToolbarVariant } from '@pr
  * ProseMirror builds its editable DOM imperatively — Stencil's scoped CSS would
  * never reach it. All styles live in light DOM via BEM + `--co-*` tokens.
  *
+ * Editor de texto enriquecido configurado por `preset` (tarea, comentario,
+ * notas, email, documento, impresión). Wrapper Vue: `CoRichTextEditor` de
+ * `@prolibu-suite/cobalt-vue`.
+ *
+ * @slot content-end - Zona entre el contenido y la barra inferior (adjuntos pendientes, vistas previas). Siempre montar el hijo y ocultarlo con CSS.
+ * @slot toolbar-end - Al final de la fila de la barra cuando `toolbarPosition="bottom"` (p. ej. el botón «Enviar»). Siempre montar el hijo.
+ *
  * @part wrapper - Outer container
  * @part toolbar - Formatting toolbar
  * @part content - Editable ProseMirror surface
  * @part label - Field label
  * @part helper - Helper text row
+ * @part toolbar-row - Fila de la barra inferior (`toolbarPosition="bottom"`) con el slot `toolbar-end`.
  */
 export declare class CoRichTextEditor {
     el: HTMLElement;
@@ -19,10 +27,15 @@ export declare class CoRichTextEditor {
     value: string | null;
     /** Preset controlling allowed nodes/marks, toolbar and sanitization. */
     preset: RichTextPreset;
+    /** Texto de ayuda del editor vacío. */
     placeholder: string;
+    /** Etiqueta del campo. */
     label?: string;
+    /** Texto secundario junto a la etiqueta. */
     secondaryLabel?: string;
+    /** Texto de ayuda o de error bajo el editor. */
     helperText?: string;
+    /** Estado de validación: pinta el borde y el `helperText` con el color del estado. */
     status: 'default' | 'error' | 'success' | 'warning' | 'info';
     /** Visual style. `flat` strips the frame's border and background so it
      *  reads as plain content instead of a boxed control — padding, label,
@@ -32,11 +45,17 @@ export declare class CoRichTextEditor {
      *  outer box is gone. `default` (the standard bordered box) renders
      *  identically to before this prop existed. */
     variant: 'default' | 'flat';
+    /** Deshabilita el editor. */
     disabled: boolean;
+    /** Solo lectura: sin barra ni edición; `coChange` sale en el acto (p. ej. al marcar una casilla de task-list). */
     readonly: boolean;
+    /** Campo obligatorio (marca de requerido en la etiqueta). */
     required: boolean;
+    /** Límite de caracteres (sobrescribe el del preset); muestra el contador «n / max». */
     maxLength?: number;
+    /** Muestra el contador de caracteres aunque no haya `maxLength`. */
     showCharacterCount: boolean;
+    /** Enfoca el editor al montarse. */
     autofocus: boolean;
     /** Toolbar layout. `auto` uses the preset default. */
     toolbar: ToolbarVariant;
@@ -100,8 +119,11 @@ export declare class CoRichTextEditor {
     coInput: EventEmitter<RichTextOutput>;
     /** Emitted on blur (committed value). */
     coChange: EventEmitter<RichTextOutput>;
+    /** El editor ganó el foco. */
     coFocus: EventEmitter<void>;
+    /** El editor perdió el foco (lo sigue `coChange`). */
     coBlur: EventEmitter<void>;
+    /** Se vació el contenido con `clear()`. */
     coClear: EventEmitter<void>;
     /** Emitted once the editor is mounted and ready. */
     coReady: EventEmitter<void>;
@@ -160,12 +182,19 @@ export declare class CoRichTextEditor {
     onAccountFontsChange(): void;
     onValueChange(next: string | null): void;
     onEditableChange(): void;
+    /** Documento como JSON de ProseMirror, o `null` si está vacío. */
     getJSON(): Promise<object | null>;
+    /** HTML sanitizado según el preset (`getHtml`, no `getHTML`, para no chocar con `HTMLElement`). */
     getHtml(): Promise<string>;
+    /** Texto plano del documento. */
     getText(): Promise<string>;
+    /** Vacía el contenido y emite `coClear`. */
     clear(): Promise<void>;
+    /** Enfoca el editor (`focusEditor`, no `focus`, para no chocar con `HTMLElement`). */
     focusEditor(): Promise<void>;
+    /** Reemplaza el contenido: HTML (string) o JSON de ProseMirror. */
     setContent(content: string | object): Promise<void>;
+    /** Instancia Tiptap subyacente (escape hatch para control avanzado), o `null` antes de montar. */
     getEditorInstance(): Promise<Editor | null>;
     /** Whether the image node is enabled (mirrors presets.ts `wantImage` logic). */
     private get imagesEnabled();

package/dist/types/components/co-rich-text-toolbar/co-rich-text-toolbar.d.ts

@@ -8,6 +8,8 @@ import type { Editor, ToolbarEntry, ToolbarExtraItem } from '@prolibu-suite/coba
  *
  * @part toolbar - The toolbar container
  * @part button - A toolbar button
+ *
+ * Wrapper Vue: `CoRichTextToolbar` de `@prolibu-suite/cobalt-vue`.
  */
 export declare class CoRichTextToolbar {
     el: HTMLElement;
@@ -18,6 +20,7 @@ export declare class CoRichTextToolbar {
     /** Placement inside co-rich-text-editor. `bottom` drops the toolbar's own bottom
      * border/background/rounding: the editor's toolbar row paints the separator. */
     position: 'top' | 'bottom';
+    /** Deshabilita la barra: sus botones no ejecutan acciones sobre el editor. */
     disabled: boolean;
     /** BCP-47 locale for UI strings (e.g. 'en', 'es-CO', 'pt-BR'). Default English. */
     locale: string;

package/dist/types/components/co-rich-text-viewer/co-rich-text-viewer.d.ts

@@ -1,4 +1,12 @@
 import type { RichTextPreset } from '@prolibu-suite/cobalt-rich-text';
+/**
+ * Visor de solo lectura de contenido rich text (HTML o JSON de ProseMirror),
+ * sanitizado según el `preset`. En `format="html"` no carga Tiptap: solo
+ * DOMPurify. Wrapper Vue: `CoRichTextViewer` de `@prolibu-suite/cobalt-vue`.
+ *
+ * @part content - El contenido renderizado.
+ * @part empty - El texto de vacío (`emptyText`) cuando no hay contenido.
+ */
 export declare class CoRichTextViewer {
     /** HTML string (default) or ProseMirror JSON string. */
     value: string | null;

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

@@ -3,6 +3,9 @@
  * @slot prefix  - Leading content (icon, checkbox)
  * @slot         - Main content
  * @slot suffix  - Trailing content (switch, badge, action)
+ *
+ * Wrapper Vue: `CoRow` de `@prolibu-suite/cobalt-vue`.
+ * @part row - La fila.
  */
 export declare class CoRow {
     /** Position in a group — affects border radius */