@prolibu-suite/cobalt-core 0.11.0 → 0.11.2

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

@@ -669,6 +669,44 @@ html[data-overlayscrollbars-viewport~=scrollbarHidden] > body::-webkit-scrollbar
   overflow: auto;
 }
 
+/**
+ * @prop --co-option-list-max-height: Alto máximo del área de filas antes de scrollear (default 280px).
+ * @prop --co-option-list-options-padding: Padding del área de filas.
+ * @prop --co-option-list-gap: Separación vertical entre filas.
+ * @prop --co-option-list-item-gap: Separación entre los elementos de una fila (ícono, textos, acciones).
+ * @prop --co-option-list-item-min-height: Alto mínimo de fila (default 32px); no cambia el paso fijo de la lista virtual.
+ * @prop --co-option-list-item-padding-y: Padding vertical de la fila.
+ * @prop --co-option-list-item-radius: Radio de la fila.
+ * @prop --co-option-list-item-bg: Fondo de la fila en reposo.
+ * @prop --co-option-list-item-ring: Sombra/anillo de la fila en reposo.
+ * @prop --co-option-list-item-font-size: Tamaño del texto de la fila (default 14px).
+ * @prop --co-option-list-active-bg: Fondo de la fila activa (hover o teclado).
+ * @prop --co-option-list-active-ring: Sombra/anillo de la fila activa.
+ * @prop --co-option-list-label-weight: Peso del label de la fila.
+ * @prop --co-option-list-text-gap: Separación entre el título y la descripción de la fila.
+ * @prop --co-option-list-icon-tile-size: Lado del recuadro del ícono (default 22px).
+ * @prop --co-option-list-icon-tile-radius: Radio del recuadro del ícono.
+ * @prop --co-option-list-icon-tile-mix: Porcentaje del tinte del ícono en el fondo del recuadro (default 12%).
+ * @prop --co-option-list-icon-tile-ring-mix: Porcentaje del tinte en el borde del recuadro (default 0%, sin borde).
+ * @prop --co-option-list-search-height: Alto del buscador (default 32px).
+ * @prop --co-option-list-search-margin: Margen del buscador.
+ * @prop --co-option-list-search-padding: Padding del buscador.
+ * @prop --co-option-list-search-border: Borde del buscador (shorthand).
+ * @prop --co-option-list-search-radius: Radio del buscador.
+ * @prop --co-option-list-search-bg: Fondo del buscador.
+ * @prop --co-option-list-search-border-focus: Color del borde del buscador con foco.
+ * @prop --co-option-list-search-bg-focus: Fondo del buscador con foco.
+ * @prop --co-option-list-search-caret: Color del cursor de texto del buscador.
+ * @prop --co-option-list-group-padding-top: Padding superior del encabezado de grupo.
+ * @prop --co-option-list-group-padding-bottom: Padding inferior del encabezado de grupo.
+ * @prop --co-option-list-group-font-family: Familia tipográfica del encabezado de grupo (default mono).
+ * @prop --co-option-list-group-font-size: Tamaño del encabezado de grupo.
+ * @prop --co-option-list-group-font-weight: Peso del encabezado de grupo.
+ * @prop --co-option-list-group-text-transform: Transformación del encabezado de grupo (default uppercase).
+ * @prop --co-option-list-group-letter-spacing: Espaciado de letras del encabezado de grupo.
+ * @prop --co-option-list-group-color: Color del encabezado de grupo.
+ */
+
 :host {
   display: block;
   font-family: var(--co-font-family-primary, 'Geist', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif);

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

@@ -9,9 +9,16 @@ import { buildRows, deriveMore, listReorderIds, liveSelectedOrder, nextActiveInd
  *
  * 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 class CoOptionList {
     constructor() {
@@ -22,6 +29,8 @@ export class CoOptionList {
         this.value = '';
         /** Display-items de la selección (para selected-first con ids fuera de página). */
         this.selectedItems = '[]';
+        /** 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. */
         this.multiple = false;
         /** Partición selected-first (snapshot al llamar snapshotOrder()). */
         this.selectedFirst = false;
@@ -39,17 +48,24 @@ export class CoOptionList {
          *  Independiente de multiple/selectedFirst. No soportado con `virtual`. */
         this.listReorderable = false;
         // ── Search integrado (opcional) ────────────────────────────
+        /** Muestra el buscador integrado arriba de la lista (reflejado como atributo).
+         *  El filtrado lo hace el host al recibir `coSearch`. */
         this.searchable = false;
+        /** Placeholder del buscador integrado. */
         this.searchPlaceholder = 'Search…';
+        /** Espera en ms entre la última tecla y el `coSearch` (default 350). */
         this.searchDebounce = 350;
         /** Pre-seed del término (modo convert de las celdas). */
         this.initialTerm = '';
         // ── Estados ────────────────────────────────────────────────
+        /** Cargando: sin filas muestra un loader en lugar de la lista; con filas,
+         *  un loader al pie. Mientras está activo no se emite `coLoadMore`. */
         this.loading = false;
         /** Total del server: deriva hasMore + hint "N more results". */
         this.total = 0;
         /** Fallback cuando el host no conoce totales (⌘K). total>0 manda. */
         this.hasMore = false;
+        /** Texto cuando no hay filas y no se está cargando. */
         this.emptyMessage = 'No results found';
         /** Si se setea y hay selección, fila "quitar selección" al tope. */
         this.clearOptionLabel = '';
@@ -60,6 +76,7 @@ export class CoOptionList {
         this.highlightMatches = false;
         /** Término externo para highlight (input en el host, p.ej. ⌘K). */
         this.highlightTerm = '';
+        /** Forma del `co-avatar` de las filas que traen avatar: `circle` (default) o `square`. */
         this.avatarShape = 'circle';
         /** `end` pinta el suffix como columna a la derecha de la fila (precio/meta),
          *  sin el guion; `inline` = junto al label (default). */
@@ -308,7 +325,6 @@ export class CoOptionList {
         this.activeIndex = activeId ? this.orderedItems.findIndex((i) => i._id === activeId) : -1;
     }
     // ── Métodos públicos ───────────────────────────────────────
-    /** 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
@@ -328,6 +344,7 @@ export class CoOptionList {
             this.takeSnapshot();
         this.coSearch.emit('');
     }
+    /** Re-toma el snapshot selected-first. El host la llama al abrir su panel. */
     async snapshotOrder() {
         this.takeSnapshot();
     }
@@ -764,11 +781,11 @@ export class CoOptionList {
         const selectedIds = this.selectedIds;
         const { hasMore, remaining } = deriveMore(this.parsedItems.length, this.total, this.hasMore);
         const showClear = !!this.clearOptionLabel && selectedIds.length > 0;
-        return (h("div", { key: 'af6891bdf933b74b6e680b81387764c3c2a0f2b9', class: "co-option-list", onKeyDown: this.onRootKeyDown }, this.searchable && (h("div", { key: '68cfffc9df1d3061d38063f6b0502afc58c668c4', class: "co-option-list__search", part: "search" }, h("co-icon", { key: 'abfc569cce22f30146cc714f4157ce12819a729a', name: "magnifying-glass", size: 16 }), h("input", { key: '5150055db79ef22253e0103998fde0c79d3b5eda', class: "co-option-list__search-input", type: "text", placeholder: this.searchPlaceholder, value: this.term, onInput: this.onSearchInput, ref: (el) => (this.searchInputEl = el), role: "combobox", "aria-expanded": "true", "aria-autocomplete": "list" }))), h("slot", { key: '1d858e33c3a6971b4abf6dd614603c4e01cba1c6', name: "header" }), h("div", { key: '28fd86f22a7f8e95fdfee4f33f1af0b441ca4c38', class: "co-option-list__options", part: "options", role: "listbox", "aria-multiselectable": this.multiple ? 'true' : 'false', ref: (el) => (this.optionsEl = el), onScroll: this.onNativeScroll }, h("div", { key: '3002c5216cac79d5d39aab2b349f6853e6517535', class: "co-option-list__inner" }, showClear && (h("button", { key: 'f6e15aeb7ea9422daf38d65611df3ca4dbb243e2', class: "co-option-list__clear-row", type: "button", onClick: () => this.coClearSelection.emit() }, h("co-icon", { key: '2f22f2b31291145b36721e923c3a422fadcabb50', name: "x-circle", size: 14 }), h("span", { key: 'd4c6b7ad4dd8df4725b763929f34da6793b29649' }, this.clearOptionLabel))), this.loading && items.length === 0 && (h("div", { key: 'c9cb5cf8095ed45d71a143878bd9ed524c6dbf25', class: "co-option-list__loading" }, h("co-loader", { key: '550b8014bec75fb16c9c7b29dd5589355abee9be', size: "sm" }))), !this.loading && items.length === 0 && (h("div", { key: '40ffc1f2945a0acd0a9c7ee4e83a1f23a93ebbd2', class: "co-option-list__empty" }, h("co-icon", { key: '639e88bb241fd79fca5481505d5cab36e89b89df', name: "magnifying-glass", size: 20 }), h("span", { key: '8f01fb62e21ad0fd6c2e367bd14d88cb09fa425e' }, this.emptyMessage))), items.length > 0 && this.virtual
+        return (h("div", { key: 'ca480a23b7127ff745ee57002a71dea707e32e95', class: "co-option-list", onKeyDown: this.onRootKeyDown }, this.searchable && (h("div", { key: 'de6a96f09450c05c9194933f3e5f732e158437c7', class: "co-option-list__search", part: "search" }, h("co-icon", { key: 'f99a19e0a194d6a0bcce6d40a736197593af8fdf', name: "magnifying-glass", size: 16 }), h("input", { key: '26fabd78b4660523e25b40bc8e92740df2677244', class: "co-option-list__search-input", type: "text", placeholder: this.searchPlaceholder, value: this.term, onInput: this.onSearchInput, ref: (el) => (this.searchInputEl = el), role: "combobox", "aria-expanded": "true", "aria-autocomplete": "list" }))), h("slot", { key: '05dc7fb2d632ba58b3b960e9355b1e48a71df32c', name: "header" }), h("div", { key: 'b3edc8acf06c7f433da9584249be73d25c5f1fee', class: "co-option-list__options", part: "options", role: "listbox", "aria-multiselectable": this.multiple ? 'true' : 'false', ref: (el) => (this.optionsEl = el), onScroll: this.onNativeScroll }, h("div", { key: '8abe9a20998f35332ee320512a433d8fb8196875', class: "co-option-list__inner" }, showClear && (h("button", { key: '9b420f4a08d94c7588657ec73102253dc3aace29', class: "co-option-list__clear-row", type: "button", onClick: () => this.coClearSelection.emit() }, h("co-icon", { key: '5e0d86b76f5b85ee41a4534284c4e05fec4f2df1', name: "x-circle", size: 14 }), h("span", { key: 'ff554cd331978bbe2e6aaef44b590a9de66c67d5' }, this.clearOptionLabel))), this.loading && items.length === 0 && (h("div", { key: '1db10de6bf8b6cda7b7ca13f5969400ab420a3e7', class: "co-option-list__loading" }, h("co-loader", { key: 'd724879c38f755067e544503c233c740f932f46e', size: "sm" }))), !this.loading && items.length === 0 && (h("div", { key: '95f42f0028e6f7a1641bc45f6a294fe2ded5a29f', class: "co-option-list__empty" }, h("co-icon", { key: '1bed6dbd8c0c4e0722f6c28c2867331bba4e3879', name: "magnifying-glass", size: 20 }), h("span", { key: '7f2d01d6eed6e91ab14ace418f52167713963976' }, this.emptyMessage))), items.length > 0 && this.virtual
             ? this.renderVirtual(items, selectedIds)
             : buildRows(items).map((row) => row.kind === 'header'
                 ? h("div", { class: "co-option-list__group", role: "presentation" }, row.label)
-                : this.renderRow(row.item, row.index, selectedIds)), this.loading && items.length > 0 && (h("div", { key: 'e0146742e08a49e0c297ab795e3eb283daedf281', class: "co-option-list__loading-more" }, h("co-loader", { key: '1bdd97a2c79d4fab0ea75be2bc4c7c4254de7638', size: "sm" }))), !this.loading && hasMore && remaining > 0 && (h("div", { key: 'cd336459aded62f27957888595c53475ba2d7664', class: "co-option-list__more" }, remaining, " more results")))), h("slot", { key: '767d9b82e7afbea41f196e110d7a6fd720637df9', name: "footer" })));
+                : this.renderRow(row.item, row.index, selectedIds)), this.loading && items.length > 0 && (h("div", { key: '9fb95c0193357bf50eabc21dae3f8ca0bb2b3a9f', class: "co-option-list__loading-more" }, h("co-loader", { key: 'dddf472d61b1c14f281212b02538bd576dce09d1', size: "sm" }))), !this.loading && hasMore && remaining > 0 && (h("div", { key: '6d4f16d14d67b137fe37b67fe1590d209b51b800', class: "co-option-list__more" }, remaining, " more results")))), h("slot", { key: '9091482eaf2228e93b3eeb893e804d5fcd8c3d44', name: "footer" })));
     }
     static get is() { return "co-option-list"; }
     static get encapsulation() { return "shadow"; }
@@ -870,7 +887,7 @@ export class CoOptionList {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Selecci\u00F3n m\u00FAltiple: `value` es un JSON array de ids y `coChange` emite el\narray completo; con `false` (default) la selecci\u00F3n es un solo id."
                 },
                 "getter": false,
                 "setter": false,
@@ -1010,7 +1027,7 @@ export class CoOptionList {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Muestra el buscador integrado arriba de la lista (reflejado como atributo).\nEl filtrado lo hace el host al recibir `coSearch`."
                 },
                 "getter": false,
                 "setter": false,
@@ -1030,7 +1047,7 @@ export class CoOptionList {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Placeholder del buscador integrado."
                 },
                 "getter": false,
                 "setter": false,
@@ -1050,7 +1067,7 @@ export class CoOptionList {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Espera en ms entre la \u00FAltima tecla y el `coSearch` (default 350)."
                 },
                 "getter": false,
                 "setter": false,
@@ -1090,7 +1107,7 @@ export class CoOptionList {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Cargando: sin filas muestra un loader en lugar de la lista; con filas,\nun loader al pie. Mientras est\u00E1 activo no se emite `coLoadMore`."
                 },
                 "getter": false,
                 "setter": false,
@@ -1150,7 +1167,7 @@ export class CoOptionList {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Texto cuando no hay filas y no se est\u00E1 cargando."
                 },
                 "getter": false,
                 "setter": false,
@@ -1250,7 +1267,7 @@ export class CoOptionList {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Forma del `co-avatar` de las filas que traen avatar: `circle` (default) o `square`."
                 },
                 "getter": false,
                 "setter": false,
@@ -1321,7 +1338,7 @@ export class CoOptionList {
                 "composed": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "T\u00E9rmino del buscador integrado, con debounce (`searchDebounce`); `''` al vaciarlo\no tras `clearSearch()`. No burbujea."
                 },
                 "complexType": {
                     "original": "string",
@@ -1336,7 +1353,7 @@ export class CoOptionList {
                 "composed": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Selecci\u00F3n pedida (el componente no muta `value`). `detail.value`: el id elegido,\nel array completo en `multiple`, o `null` al deseleccionar en single;\n`detail.item`: la fila involucrada. No burbujea."
                 },
                 "complexType": {
                     "original": "{ value: string | string[] | null; item: OptionListItem }",
@@ -1358,7 +1375,7 @@ export class CoOptionList {
                 "composed": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Pide la p\u00E1gina siguiente: al acercarse el scroll al final, o si las filas\ncargadas no llenan el panel. Solo con m\u00E1s resultados (`total`/`hasMore`) y\nsin `loading`. Sin `detail`. No burbujea."
                 },
                 "complexType": {
                     "original": "void",
@@ -1373,7 +1390,7 @@ export class CoOptionList {
                 "composed": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Click en la fila \u00ABquitar selecci\u00F3n\u00BB (`clearOptionLabel`). Sin `detail`. No burbujea."
                 },
                 "complexType": {
                     "original": "void",
@@ -1388,7 +1405,7 @@ export class CoOptionList {
                 "composed": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Click en la X de una fila seleccionada (`removableItems`); `detail` = id de la fila. No burbujea."
                 },
                 "complexType": {
                     "original": "string",
@@ -1495,7 +1512,7 @@ export class CoOptionList {
                     "return": "Promise<void>"
                 },
                 "docs": {
-                    "text": "",
+                    "text": "Re-toma el snapshot selected-first. El host la llama al abrir su panel.",
                     "tags": []
                 }
             },

package/dist/collection/components/co-overlay/co-overlay.css

@@ -1,3 +1,7 @@
+/**
+ * @prop --co-overlay-bg: Color del fondo (default negro al 40%).
+ * @prop --co-overlay-blur: Desenfoque del fondo (default 2px); queda fuera del interruptor `--co-glass-filter`.
+ */
 :host {
   display: contents;
 }
@@ -33,3 +37,10 @@
   pointer-events: auto;
   transition: opacity var(--co-motion-duration-base) var(--co-motion-ease-out);
 }
+
+/* bringToFront(): el hide + show que re-apila el scrim en el top layer no es una
+   apertura — nada transiciona durante el re-show (la clase se retira en el frame
+   siguiente). */
+.co-overlay--refront {
+  transition: none !important;
+}

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

@@ -1,7 +1,7 @@
 import { h } from "@stencil/core";
 import { afterEventFor } from "./overlayAfterClose";
 import { isBackdropDismiss } from "./backdropDismiss";
-import { getFocusableElements, resolveTabIndex } from "./focusTrap";
+import { getComposedFocusables, isTopTrap, resolveInitialFocus, resolveTabIndex } from "./focusTrap";
 /**
  * Module-level body-scroll lock shared by every overlay instance.
  * Ref-counted so stacked/nested overlays (e.g. a modal opened from a drawer)
@@ -28,12 +28,32 @@ function unlockBodyScroll() {
         document.body.style.overflow = savedOverflow;
     }
 }
+/**
+ * Pila de trampas de foco ABIERTAS, compartida por todas las instancias (como el
+ * scroll lock). Todas escuchan el keydown de document: con un confirm encima de
+ * un modal, las dos movían el foco en el mismo Tab. Solo la capa más reciente
+ * (`isTopTrap`) maneja Tab y el foco inicial.
+ */
+const trapStack = [];
+let trapSeq = 0;
+/** Clase del div mientras dura el re-apilado de `bringToFront()` (ver co-overlay.css). */
+const REFRONT_CLASS = 'co-overlay--refront';
 function nextFrame(cb) {
     if (typeof requestAnimationFrame === 'function')
         requestAnimationFrame(cb);
     else
         cb();
 }
+/**
+ * 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 class CoOverlay {
     constructor() {
         /** Whether the overlay is visible */
@@ -43,6 +63,11 @@ export 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.
          */
         this.trapFocus = false;
         /**
@@ -52,6 +77,10 @@ export class CoOverlay {
         this.closeOnEscape = false;
         /** Whether THIS instance currently holds a scroll lock (prevents double-count). */
         this.hasLock = false;
+        /** Identidad de esta instancia en `trapStack`. */
+        this.trapId = `co-overlay-trap-${++trapSeq}`;
+        /** Whether THIS instance is currently in `trapStack` (prevents double push). */
+        this.trapping = false;
         // Origen de la pulsación en curso (ver isBackdropDismiss): un drag que
         // empieza dentro del contenido y suelta en el fondo NO es un cierre —el
         // navegador despacha ese `click` al ancestro común, el propio scrim—, ni
@@ -93,27 +122,55 @@ export class CoOverlay {
         else
             this.releaseLock();
         this.syncPopover();
-        if (this.trapFocus) {
-            if (isOpen)
-                this.captureAndFocus();
-            else
-                this.restoreFocus();
-        }
+        this.syncTrap();
+    }
+    onTrapFocusChange() {
+        this.syncTrap();
     }
     componentDidLoad() {
         // Handle the case where the overlay mounts already open.
         if (this.open)
             this.acquireLock();
         this.syncPopover();
-        if (this.open && this.trapFocus)
-            this.captureAndFocus();
+        this.syncTrap();
     }
     disconnectedCallback() {
         // Safety: never leave the body locked if removed while open.
         this.releaseLock();
-        // Safety: return focus if we were removed while trapping.
-        if (this.trapFocus)
-            this.restoreFocus();
+        // Safety: leave the trap stack and return focus if removed while trapping.
+        this.releaseTrap();
+    }
+    /**
+     * 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.
+     */
+    async bringToFront() {
+        const el = this.overlayEl;
+        if (!this.open || !el || typeof el.showPopover !== 'function')
+            return;
+        if (!el.matches(':popover-open'))
+            return;
+        const active = this.deepActiveElement();
+        el.classList.add(REFRONT_CLASS);
+        try {
+            el.hidePopover();
+            el.showPopover();
+        }
+        catch (_a) {
+            /* desconectado entre medio: no hay nada que re-apilar */
+        }
+        if (active && active.isConnected && this.deepActiveElement() !== active)
+            active.focus({ preventScroll: true });
+        nextFrame(() => el.classList.remove(REFRONT_CLASS));
     }
     acquireLock() {
         if (this.hasLock)
@@ -151,19 +208,43 @@ export class CoOverlay {
             /* not connected yet, or already in the desired state */
         }
     }
-    /** 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`. */
+    syncTrap() {
+        if (this.open && this.trapFocus)
+            this.engageTrap();
+        else
+            this.releaseTrap();
+    }
+    engageTrap() {
+        if (this.trapping)
+            return;
+        this.trapping = true;
+        trapStack.push(this.trapId);
+        this.captureAndFocus();
+    }
+    releaseTrap() {
+        if (!this.trapping)
+            return;
+        this.trapping = false;
+        const i = trapStack.indexOf(this.trapId);
+        if (i >= 0)
+            trapStack.splice(i, 1);
+        this.restoreFocus();
+    }
+    /** Record the current focus and move it into the overlay (only while trapping). */
     captureAndFocus() {
-        if (typeof document !== 'undefined') {
-            this.returnFocusEl = document.activeElement;
-        }
+        // El activo PROFUNDO: `document.activeElement` se queda en el host de un
+        // co-* (co-button), cuyo focus() no llega al <button> interno.
+        this.returnFocusEl = this.deepActiveElement();
         // Defer so slotted content / the open transition is ready to take focus.
         nextFrame(() => {
             var _a;
-            if (!this.open)
+            // Una trampa abierta en el mismo frame por ENCIMA (confirm) se queda el foco.
+            if (!this.open || !this.trapping || !isTopTrap(trapStack, this.trapId))
                 return;
-            const focusables = getFocusableElements(this.el);
-            if (focusables.length > 0)
-                focusables[0].focus();
+            const target = resolveInitialFocus(this.el);
+            if (target)
+                target.focus();
             else
                 (_a = this.overlayEl) === null || _a === void 0 ? void 0 : _a.focus();
         });
@@ -172,8 +253,9 @@ export class CoOverlay {
     restoreFocus() {
         const target = this.returnFocusEl;
         this.returnFocusEl = null;
-        if (target && typeof target.focus === 'function')
-            target.focus();
+        // Desmontado mientras el overlay estaba abierto (el paso de un wizard): no hay adónde volver.
+        if (target && target.isConnected && typeof target.focus === 'function')
+            target.focus({ preventScroll: true });
     }
     /** Deepest active element, descending through nested shadow roots. */
     deepActiveElement() {
@@ -192,12 +274,16 @@ export class CoOverlay {
             this.coClose.emit();
             return;
         }
-        if (this.trapFocus && e.key === 'Tab')
+        if (this.trapping && e.key === 'Tab' && isTopTrap(trapStack, this.trapId))
             this.trapTab(e);
     }
     trapTab(e) {
         var _a;
-        const focusables = getFocusableElements(this.el);
+        // Tab ya manejado por un control de adentro (co-tags-field agrega el tag, las listas de co-rich-text y
+        // CodeMirror indentan): el listener de document corre DESPUÉS y no le roba el foco.
+        if (e.defaultPrevented)
+            return;
+        const focusables = getComposedFocusables(this.el);
         if (focusables.length === 0) {
             // Nothing to move to — keep focus pinned to the overlay container.
             e.preventDefault();
@@ -212,7 +298,7 @@ export class CoOverlay {
         focusables[nextIndex].focus();
     }
     render() {
-        return (h("div", { key: '842f23e0829dcb9138f3fd35c86471035949517c', class: { 'co-overlay': true, 'co-overlay--open': this.open }, part: "overlay", popover: "manual", tabindex: this.trapFocus ? -1 : undefined, ref: (el) => (this.overlayEl = el), onPointerDown: this.handlePointerDown, onPointerUp: this.handlePointerUp, onClick: this.handleClick, onTransitionEnd: this.handleTransitionEnd }, h("slot", { key: '645b336ce50938672fc09a27a15ef314250beaf2' })));
+        return (h("div", { key: 'e18d7b0e3ebd4933a78a9f2d39af6058ce429105', class: { 'co-overlay': true, 'co-overlay--open': this.open }, part: "overlay", popover: "manual", tabindex: this.trapFocus ? -1 : undefined, ref: (el) => (this.overlayEl = el), onPointerDown: this.handlePointerDown, onPointerUp: this.handlePointerUp, onClick: this.handleClick, onTransitionEnd: this.handleTransitionEnd }, h("slot", { key: '2f29233d44de8a0cc3100cfa08233cdc10ebf352' })));
     }
     static get is() { return "co-overlay"; }
     static get encapsulation() { return "shadow"; }
@@ -260,7 +346,7 @@ export class CoOverlay {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "Opt-in accessible focus trap. When true, opening the overlay records the\npreviously-focused element, moves focus into the overlay, cycles Tab /\nShift+Tab within the slotted content, and restores focus on close.\nDefault false \u2192 existing consumers are unchanged."
+                    "text": "Opt-in accessible focus trap. When true, opening the overlay records the\npreviously-focused element, moves focus into the overlay, cycles Tab /\nShift+Tab within the slotted content, and restores focus on close.\nDefault false \u2192 existing consumers are unchanged.\n\nThe walk is COMPOSED (shadow roots + assigned slots): it reaches the\nconsumer's content projected through a host's slots and the inner control\nof every co-* (a co-button's `<button>`). With several traps open, only the\nmost recent one handles Tab."
                 },
                 "getter": false,
                 "setter": false,
@@ -338,11 +424,39 @@ export class CoOverlay {
                 }
             }];
     }
+    static get methods() {
+        return {
+            "bringToFront": {
+                "complexType": {
+                    "signature": "() => Promise<void>",
+                    "parameters": [],
+                    "references": {
+                        "Promise": {
+                            "location": "global",
+                            "id": "global::Promise"
+                        },
+                        "HTMLElement": {
+                            "location": "global",
+                            "id": "global::HTMLElement"
+                        }
+                    },
+                    "return": "Promise<void>"
+                },
+                "docs": {
+                    "text": "Re-promueve el scrim al TOPE del top layer (QA 2026-09-24, \u00ABGenerar\ncontrato\u00BB): un drawer abierto DESPU\u00C9S de un modal pintaba encima, porque en\nel top layer gana el \u00FAltimo promovido y no hay z-index que lo corrija.\n`hidePopover()` + `showPopover()` lo vuelven a meter \u00FAltimo.\n\nNo es un cierre: no emite `coClose` / `coAfterClose` / `coAfterOpen`, no\ntoca `open` ni el scroll lock, y no re-anima la entrada (la clase\n`co-overlay--refront` anula la transici\u00F3n durante el re-show y se retira en\nel frame siguiente). Tampoco mueve el foco: si el re-show dispara los\n\u00ABpopover focusing steps\u00BB (un `[autofocus]` adentro), se devuelve a donde\nestaba. No-op cerrado, sin Popover API o fuera del top layer.",
+                    "tags": []
+                }
+            }
+        };
+    }
     static get elementRef() { return "el"; }
     static get watchers() {
         return [{
                 "propName": "open",
                 "methodName": "onOpenChange"
+            }, {
+                "propName": "trapFocus",
+                "methodName": "onTrapFocusChange"
             }];
     }
     static get listeners() {