@prolibu-suite/cobalt-core 0.10.4 → 0.11.1

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

@@ -1,38 +1,97 @@
 import { h } from "@stencil/core";
+/**
+ * Control deslizante para elegir un número dentro de un rango, horizontal o
+ * vertical (volumen: el máximo arriba). `coInput` es la vista previa mientras se
+ * arrastra y `coChange` confirma una vez al terminar el gesto. Wrapper Vue:
+ * `CoSlider` de `@prolibu-suite/cobalt-vue`.
+ */
 export class CoSlider {
     constructor() {
+        /** Estado de validación: colorea el `helperText`. */
         this.status = 'default';
+        /** Valor actual; el componente lo actualiza al arrastrar o con el teclado. */
         this.value = 0;
+        /** Mínimo del rango (default 0). */
         this.min = 0;
+        /** Máximo del rango (default 100). */
         this.max = 100;
+        /** Paso entre valores (default 1); también el paso de las flechas. */
         this.step = 1;
+        /** Deshabilita el control. */
         this.disabled = false;
         /** Show current value label */
         this.showValue = true;
         /** Show min/max marks */
         this.showMarks = false;
+        /**
+         * Eje del control. `horizontal` (default) es el slider de siempre: mismo
+         * markup, mismo CSS, mismos eventos — la variante es ADITIVA y ningún
+         * consumidor actual (prolibu-front-v2) cambia de comportamiento.
+         *
+         * `vertical` INVIERTE el eje como manda la convención de un control de
+         * volumen: arriba es MÁS. El relleno crece desde abajo, el thumb se posiciona
+         * por `bottom`, y el largo del riel se ajusta con la variable
+         * `--co-slider-vertical-length` (default 120px).
+         *
+         * NO lleva `reflect`: reflejar una prop de string con default escribiría
+         * `orientation="horizontal"` en el host de TODOS los consumidores actuales, y
+         * eso ya sería cambiarles el markup. El estilo cuelga de la clase interna
+         * `.co-slider--vertical`, que es nuestra.
+         */
+        this.orientation = 'horizontal';
         this.dragging = false;
+        /** ¿Algún `coInput` real durante el gesto? Sin cambio no hay `coChange` de cierre. */
+        this.changedInGesture = false;
         this.handlePointerDown = (e) => {
-            if (this.disabled)
+            // Solo el botón primario; un segundo puntero (multitouch) no roba el gesto
+            // en curso. Sin el guard del botón, un clic DERECHO sobre el riel arrancaba
+            // un gesto que en macOS nunca veía su `pointerup` (se lo come el menú
+            // contextual): el slider seguía arrastrándose con cada movimiento del mouse
+            // hasta el clic siguiente, que remataba con un `coChange` espurio.
+            if (this.disabled || e.button !== 0 || this.dragging)
                 return;
             e.preventDefault();
             this.dragging = true;
-            const v = this.valueFromEvent(e.clientX);
-            this.value = v;
-            this.coInput.emit(v);
-            const onMove = (ev) => {
-                const val = this.valueFromEvent(ev.clientX);
-                this.value = val;
-                this.coInput.emit(val);
-            };
-            const onUp = () => {
-                this.dragging = false;
+            this.dragPointerId = e.pointerId;
+            this.changedInGesture = false;
+            this.bindGesture();
+            this.commitInput(this.valueFromPointer(e.clientX, e.clientY));
+        };
+        this.handleGesturePointerMove = (e) => {
+            if (!this.isGesturePointer(e))
+                return;
+            this.commitInput(this.valueFromPointer(e.clientX, e.clientY));
+        };
+        /**
+         * Fin del gesto — `pointerup` y también `pointercancel`, igual que el
+         * `handlePointerEnd` de co-color-slider / co-color-area: cancelar TERMINA el
+         * gesto y CONFIRMA lo alcanzado, no revierte.
+         *
+         * (Una versión anterior de esta rama revertía al valor previo con un `coInput`
+         * de rollback, copiando el arrastre de `co-modal movable`. Se descartó: el
+         * modal mueve una posición cosmética que no tiene canal de commit, mientras
+         * que acá el valor ES estado del host. Los dos sliders del propio design
+         * system confirman al cancelar, un `input type="range"` nativo también
+         * conserva el valor en `pointercancel`, y revertir obligaba al host a saber
+         * absorber un `coInput` de vuelta atrás — contrato de más, distinto al de los
+         * hermanos.)
+         */
+        this.handleGestureEnd = (e) => {
+            if (!this.isGesturePointer(e))
+                return;
+            // Un clic sobre el valor actual (o en un extremo ya alcanzado) no cambia
+            // nada: sin `coChange`, igual que el teclado en el borde.
+            if (this.endGesture())
+                this.coChange.emit(this.value);
+        };
+        /** Perder el foco de la ventana (alt-tab, un iframe que se lo lleva) cierra
+         *  el gesto igual que un `pointercancel`: sin esto, un puntero que nunca
+         *  suelta su `pointerup` deja el arrastre vivo. */
+        this.handleWindowBlur = () => {
+            if (!this.dragging)
+                return;
+            if (this.endGesture())
                 this.coChange.emit(this.value);
-                document.removeEventListener('pointermove', onMove);
-                document.removeEventListener('pointerup', onUp);
-            };
-            document.addEventListener('pointermove', onMove);
-            document.addEventListener('pointerup', onUp);
         };
         this.handleInputChange = (e) => {
             const raw = parseFloat(e.target.value);
@@ -42,6 +101,47 @@ export class CoSlider {
                 this.coChange.emit(v);
             }
         };
+        /**
+         * Flechas de la variante VERTICAL: las resuelve el componente en vez de
+         * delegarlas al range nativo, y solo ahí — en horizontal este handler NO se
+         * engancha (ver `render`), así que el camino de siempre no cambia en nada.
+         *
+         * Por qué: la orientación vertical del input se consigue con
+         * `writing-mode: vertical-rl` + `direction: rtl` (ver co-slider.css). Un motor
+         * que ignore `writing-mode` en form controls pero sí honre `direction`
+         * (Safari 17.0–17.3, Firefox < 129) deja ←/→ INVERTIDOS. Manejadas acá, las
+         * cuatro flechas siguen el eje en cualquier motor — arriba/derecha suben,
+         * abajo/izquierda bajan, de a `step` — y el contrato queda testeable (jsdom no
+         * implementa el teclado del range nativo).
+         *
+         * PageUp/PageDown/Home/End siguen siendo del nativo. Emite `coChange` y no
+         * `coInput`, exactamente como el paso de teclado del horizontal
+         * (`handleInputChange`): un paso discreto es un commit, no un preview.
+         */
+        this.handleVerticalKeyDown = (e) => {
+            if (this.disabled)
+                return;
+            const dir = e.key === 'ArrowUp' || e.key === 'ArrowRight' ? 1
+                : e.key === 'ArrowDown' || e.key === 'ArrowLeft' ? -1
+                    : 0;
+            if (dir === 0)
+                return;
+            e.preventDefault();
+            const next = this.snap(this.value + dir * this.step);
+            // En el borde no hay cambio → sin eventos, igual que el gesto.
+            if (next === this.value)
+                return;
+            this.value = next;
+            this.coChange.emit(next);
+        };
+    }
+    /**
+     * `=== 'vertical'` y no `!== 'horizontal'`: con `@stencil/vitest` las `@Prop`
+     * omitidas en `h()` llegan `undefined` (no se siembra el default), y un valor
+     * ausente tiene que caer del lado de SIEMPRE, que es el horizontal.
+     */
+    get isVertical() {
+        return this.orientation === 'vertical';
     }
     get percentage() {
         const range = this.max - this.min;
@@ -62,22 +162,114 @@ export class CoSlider {
         const steps = Math.round((v - this.min) / this.step);
         return this.clamp(this.min + steps * this.step);
     }
-    valueFromEvent(clientX) {
+    /**
+     * Valor bajo el puntero. En horizontal el eje va de `left` a `right`; en
+     * vertical va de ABAJO hacia arriba (`bottom - clientY`), así que acercarse
+     * al borde superior sube el valor.
+     *
+     * El guard de tamaño evita el `NaN` que salía de dividir por un riel de 0px
+     * (track sin medir todavía, o dentro de un contenedor colapsado).
+     */
+    valueFromPointer(clientX, clientY) {
         if (!this.trackEl)
             return this.value;
         const rect = this.trackEl.getBoundingClientRect();
-        const ratio = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
-        const raw = this.min + ratio * (this.max - this.min);
+        const ratio = this.isVertical
+            ? rect.height > 0 ? (rect.bottom - clientY) / rect.height : 0
+            : rect.width > 0 ? (clientX - rect.left) / rect.width : 0;
+        const raw = this.min + Math.max(0, Math.min(1, ratio)) * (this.max - this.min);
         return this.snap(raw);
     }
+    /**
+     * Aplica el valor y emite `coInput` SOLO si cambió — el contrato de la casa
+     * (gemelo de `commitInput` en co-color-slider / co-color-area).
+     *
+     * Que `coInput` sea condicional es lo que cierra el ciclo de vida del
+     * consumidor: en el editor `coInput` ABRE una foto de "antes" y `coChange` la
+     * LIBERA (`fill/gestureHistory.ts`). Con las dos condiciones atadas al mismo
+     * `changedInGesture`, vale la invariante **"todo gesto que emitió `coInput`
+     * termina con exactamente un `coChange`"**: si el valor nunca se movió no se
+     * abre ninguna foto, y si se movió —aunque vuelva al de partida— hay cierre.
+     * Emitir `coInput` en cada paso (como antes) y `coChange` solo si el valor
+     * FINAL difería dejaba fotos colgadas en la ida y vuelta 50→80→50.
+     */
+    commitInput(next) {
+        if (next === this.value)
+            return false;
+        this.value = next;
+        this.changedInGesture = true;
+        this.coInput.emit(next);
+        return true;
+    }
+    /** `==`: en jsdom un MouseEvent sintético trae `pointerId` undefined y debe seguir pasando. */
+    isGesturePointer(e) {
+        // eslint-disable-next-line eqeqeq
+        return this.dragging && e.pointerId == this.dragPointerId;
+    }
+    bindGesture() {
+        document.addEventListener('pointermove', this.handleGesturePointerMove);
+        document.addEventListener('pointerup', this.handleGestureEnd);
+        document.addEventListener('pointercancel', this.handleGestureEnd);
+        window.addEventListener('blur', this.handleWindowBlur);
+    }
+    unbindGesture() {
+        document.removeEventListener('pointermove', this.handleGesturePointerMove);
+        document.removeEventListener('pointerup', this.handleGestureEnd);
+        document.removeEventListener('pointercancel', this.handleGestureEnd);
+        window.removeEventListener('blur', this.handleWindowBlur);
+    }
+    /**
+     * Cierra el gesto y devuelve si hubo algún `coInput` — el ÚNICO lugar donde
+     * se apaga `changedInGesture`, para que todos los finales (pointerup,
+     * pointercancel, blur, desconexión) compartan la misma contabilidad.
+     *
+     * Que la bandera se desarme acá es lo que impide un `coChange` de más: antes
+     * solo se ponía en `false` al ARRANCAR el gesto siguiente, así que una vez
+     * movido el valor quedaba armada para siempre y `disconnectedCallback`
+     * —que cierra el gesto con su `coChange`— reemitía un commit con el valor ya
+     * escrito CADA vez que el elemento se desmontaba. En el editor eso marcaba el
+     * documento como "modificado" al cerrar el popover sin que hubiera edición;
+     * el evento de más le llega a cualquier consumidor.
+     */
+    endGesture() {
+        this.unbindGesture();
+        this.dragging = false;
+        this.dragPointerId = undefined;
+        const huboCambio = this.changedInGesture;
+        this.changedInGesture = false;
+        return huboCambio;
+    }
+    /**
+     * Desmontarse en pleno gesto tiene que dejar el componente como si nunca
+     * hubiera empezado: `endGesture()` y no solo `unbindGesture()`. Con `dragging`
+     * en `true`, una instancia que se desconecta y se vuelve a conectar (reorden
+     * de una lista keyed, un `Teleport`) quedaba sin listeners Y rechazando todo
+     * `pointerdown` por el guard de arriba: slider muerto al puntero para siempre.
+     *
+     * Y CIERRA el gesto con su `coChange`, como cualquier otro final: era el único
+     * camino donde la invariante ("todo gesto que emitió `coInput` termina con
+     * exactamente un `coChange`") no valía. Sin el cierre, un host que se recrea
+     * el subárbol con el thumb agarrado deja abierta la foto de "antes" del
+     * historial y la edición siguiente del mismo nodo se registra contra ella.
+     *
+     * El `dispatchEvent` sobre un nodo ya desconectado llega igual a los listeners
+     * puestos sobre el propio elemento, que es como enganchan `@lit/react` y el
+     * `defineContainer` de Vue.
+     */
+    disconnectedCallback() {
+        if (this.endGesture())
+            this.coChange.emit(this.value);
+    }
     render() {
         const pct = this.percentage;
-        return (h("div", { key: 'd6e0584e8c2f04f1b9a393f200a853a6acc0399c', class: {
+        const vertical = this.isVertical;
+        return (h("div", { key: '4993b9d6827cdda362ce482151bffaf84c916442', class: {
                 'co-slider': true,
                 'co-slider--disabled': this.disabled,
                 'co-slider--dragging': this.dragging,
+                'co-slider--vertical': vertical,
                 [`co-slider--${this.status}`]: this.status !== 'default',
-            } }, (this.label || this.secondaryLabel || this.showValue) && (h("div", { key: 'a0eae621e367f1145bdd9bdde53fb024489d0812', class: "co-slider__labels" }, h("div", { key: '19e102fe586ccff3ad37bc7cd6b4dd4de5172be7', class: "co-slider__labels-left" }, this.label && h("label", { key: 'ad31ddd76acb9bf7bf25f07a7fad5206ab6eb689', class: "co-slider__label" }, this.label), this.secondaryLabel && h("span", { key: 'ccb7be2022de9d8d8ed1c7eeeac38b6d4711bd60', class: "co-slider__secondary-label" }, this.secondaryLabel)), this.showValue && h("span", { key: 'c38e8a050941184056441c94f6bcbfcc62522e62', class: "co-slider__value" }, this.value))), h("div", { key: 'c6cc971ea5dc3b4d30f8224ec359ae97a8ffa24a', class: "co-slider__track-wrapper", ref: el => (this.trackEl = el), onPointerDown: this.handlePointerDown }, h("div", { key: 'de241b0017db6f5934b2332b08b6709038379b2c', class: "co-slider__track" }, h("div", { key: '9b590f27f16839a6dba5f0e2eea7467a485f79c1', class: "co-slider__fill", style: { width: `${pct}%` } })), h("div", { key: 'c8820089a72ec566210550317233832ba84a9e0a', class: "co-slider__thumb", style: { left: `${pct}%` } })), this.showMarks && (h("div", { key: '2a40f01b836d29e453b691bc1f5f378166322e1e', class: "co-slider__marks" }, h("span", { key: '1f9dc67ca0e9c327766154a1a07a67c7e53efc68', class: "co-slider__mark" }, this.min), h("span", { key: '073c37ad99a45c05d7a0341e62ea9ed4e68d7acb', class: "co-slider__mark" }, this.max))), h("input", { key: 'fa18beabbcb2e26e86436bedc57de95f40c849f2', class: "co-slider__native", type: "range", min: this.min, max: this.max, step: this.step, value: this.value, disabled: this.disabled, onInput: this.handleInputChange, "aria-label": this.label || 'Slider' }), this.helperText && (h("div", { key: 'e8e46da2806b049d29c34620acd5cadf3abb03c8', class: `co-slider__helper co-slider__helper--${this.status}` }, this.statusIcon && h("co-icon", { key: '1802da1ab54a283d46eca9cbb0fe0bf4a381956c', name: this.statusIcon, size: 14, weight: "fill", class: "co-slider__helper-icon" }), h("span", { key: 'ab294efdeee8c4546a83b16b55e3600f8706b2d7', class: "co-slider__helper-text" }, this.helperText)))));
+            } }, (this.label || this.secondaryLabel || this.showValue) && (h("div", { key: '707c5bda972f1c1c3a45d6716f1a7b1debc2e9ee', class: "co-slider__labels" }, h("div", { key: '2ea2bd4c5e9eafcc8e87214134ad3ee4881b990f', class: "co-slider__labels-left" }, this.label && h("label", { key: '8a509cbaaae01919f3e29627492762021bc6b001', class: "co-slider__label" }, this.label), this.secondaryLabel && h("span", { key: '9ac5b791724b1f106c0d50bea0eef55367187dcb', class: "co-slider__secondary-label" }, this.secondaryLabel)), this.showValue && h("span", { key: '77fd3b3c5db03128a19fc37797832e334a31a9cd', class: "co-slider__value" }, this.value))), h("div", { key: '8d16d1b89ea5c4f0226787482f4cf307cefb5f99', class: "co-slider__track-wrapper", ref: el => (this.trackEl = el), onPointerDown: this.handlePointerDown }, h("div", { key: '2d74659caca41e9255fe792e3b172e3cd6e4f3d9', class: "co-slider__track" }, h("div", { key: '169501854773b01341072f8024d89e665ed5527e', class: "co-slider__fill", style: vertical ? { height: `${pct}%` } : { width: `${pct}%` } })), h("div", { key: 'a1ea0b12371df5f0df4204a6be870fcf70141c43', class: "co-slider__thumb", style: vertical ? { bottom: `${pct}%` } : { left: `${pct}%` } })), this.showMarks && (h("div", { key: '8e8d55e60e058b1336c9819c11100c3e82f56097', class: "co-slider__marks" }, h("span", { key: '0e6b74aed9a56f40147a8e96290834c3e51d82c4', class: "co-slider__mark" }, this.min), h("span", { key: '4b735e6e20f5d49f5ab6047129b43e05210c5726', class: "co-slider__mark" }, this.max))), h("input", { key: 'ddbb917734f98c92564477b502f29f51f2c492ca', class: "co-slider__native", type: "range", min: this.min, max: this.max, step: this.step, value: this.value, disabled: this.disabled, onInput: this.handleInputChange, onKeyDown: vertical ? this.handleVerticalKeyDown : undefined, "aria-label": this.ariaLabelText || this.label || 'Slider', "aria-orientation": vertical ? 'vertical' : undefined }), this.helperText && (h("div", { key: '68ba7ef8a27b006011ad0d1beba1cd9557103f8a', class: `co-slider__helper co-slider__helper--${this.status}` }, this.statusIcon && h("co-icon", { key: '99f8b511f7de45809967a8a7588d8d736365247e', name: this.statusIcon, size: 14, weight: "fill", class: "co-slider__helper-icon" }), h("span", { key: '22f3ecf666b54d2bf5c97816c1b8253a7c6b233b', class: "co-slider__helper-text" }, this.helperText)))));
     }
     static get is() { return "co-slider"; }
     static get encapsulation() { return "shadow"; }
@@ -105,13 +297,32 @@ export class CoSlider {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Etiqueta visible; tambi\u00E9n da el nombre accesible si no hay `ariaLabelText`."
                 },
                 "getter": false,
                 "setter": false,
                 "reflect": false,
                 "attribute": "label"
             },
+            "ariaLabelText": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string | undefined",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [],
+                    "text": "Nombre accesible del control, SIN dibujar etiqueta. `label` hace las dos\ncosas a la vez (rotula y nombra), as\u00ED que un slider sin etiqueta visible\n\u2014los dos del panel de Multimedia del editor, y cualquier control con el\nr\u00F3tulo afuera\u2014 se quedaba llam\u00E1ndose `\"Slider\"`: literal, en ingl\u00E9s y para\ntodos los idiomas.\n\nMismo nombre de prop que `co-fab`, `co-button` y `co-action-bar`, y la\nmisma precedencia que `co-fab` y `co-action-bar` (`ariaLabelText || label`;\n`co-button` no tiene `label` que nombre: cae al texto de su contenido).\nEl fallback final es propio de cada componente; ac\u00E1, `\"Slider\"`. Aditiva \u2014\nsin ella el markup y el `aria-label` son byte-id\u00E9nticos a los de siempre.\n\nLa resoluci\u00F3n es por `||` sobre el valor RECIBIDO y no por un default de\nclase: un wrapper (`@lit/react`, el `defineContainer` de Vue) que pasa la\nprop sin valor manda `undefined` y pisa cualquier default sembrado por\nStencil, as\u00ED que `undefined` y `''` tienen que caer del lado de SIEMPRE \u2014\nel mismo criterio que el `=== 'vertical'` de `isVertical`."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "aria-label-text"
+            },
             "secondaryLabel": {
                 "type": "string",
                 "mutable": false,
@@ -124,7 +335,7 @@ export class CoSlider {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Texto secundario junto a la etiqueta (p. ej. la unidad)."
                 },
                 "getter": false,
                 "setter": false,
@@ -143,7 +354,7 @@ export class CoSlider {
                 "optional": true,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Texto de ayuda o de error bajo el control."
                 },
                 "getter": false,
                 "setter": false,
@@ -162,7 +373,7 @@ export class CoSlider {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Estado de validaci\u00F3n: colorea el `helperText`."
                 },
                 "getter": false,
                 "setter": false,
@@ -182,7 +393,7 @@ export class CoSlider {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Valor actual; el componente lo actualiza al arrastrar o con el teclado."
                 },
                 "getter": false,
                 "setter": false,
@@ -202,7 +413,7 @@ export class CoSlider {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "M\u00EDnimo del rango (default 0)."
                 },
                 "getter": false,
                 "setter": false,
@@ -222,7 +433,7 @@ export class CoSlider {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "M\u00E1ximo del rango (default 100)."
                 },
                 "getter": false,
                 "setter": false,
@@ -242,7 +453,7 @@ export class CoSlider {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Paso entre valores (default 1); tambi\u00E9n el paso de las flechas."
                 },
                 "getter": false,
                 "setter": false,
@@ -262,7 +473,7 @@ export class CoSlider {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Deshabilita el control."
                 },
                 "getter": false,
                 "setter": false,
@@ -309,6 +520,26 @@ export class CoSlider {
                 "reflect": false,
                 "attribute": "show-marks",
                 "defaultValue": "false"
+            },
+            "orientation": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'horizontal' | 'vertical'",
+                    "resolved": "\"horizontal\" | \"vertical\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": "Eje del control. `horizontal` (default) es el slider de siempre: mismo\nmarkup, mismo CSS, mismos eventos \u2014 la variante es ADITIVA y ning\u00FAn\nconsumidor actual (prolibu-front-v2) cambia de comportamiento.\n\n`vertical` INVIERTE el eje como manda la convenci\u00F3n de un control de\nvolumen: arriba es M\u00C1S. El relleno crece desde abajo, el thumb se posiciona\npor `bottom`, y el largo del riel se ajusta con la variable\n`--co-slider-vertical-length` (default 120px).\n\nNO lleva `reflect`: reflejar una prop de string con default escribir\u00EDa\n`orientation=\"horizontal\"` en el host de TODOS los consumidores actuales, y\neso ya ser\u00EDa cambiarles el markup. El estilo cuelga de la clase interna\n`.co-slider--vertical`, que es nuestra."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "orientation",
+                "defaultValue": "'horizontal'"
             }
         };
     }
@@ -326,7 +557,7 @@ export class CoSlider {
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Confirma el valor: una vez al terminar el gesto (si hubo alg\u00FAn `coInput`) y en cada paso de teclado. `detail` = n\u00FAmero."
                 },
                 "complexType": {
                     "original": "number",
@@ -341,7 +572,7 @@ export class CoSlider {
                 "composed": true,
                 "docs": {
                     "tags": [],
-                    "text": ""
+                    "text": "Vista previa mientras se arrastra, solo cuando el valor cambia. `detail` = n\u00FAmero."
                 },
                 "complexType": {
                     "original": "number",

package/dist/collection/components/co-swatch-grid/co-swatch-grid.css

@@ -0,0 +1,56 @@
+/* co-swatch-grid — grilla de muestras de color ("Colores recientes") */
+
+:host {
+  display: block;
+}
+
+:host([hidden]) {
+  display: none;
+}
+
+/* grid-template-columns y gap van inline (repeat(columns, swatchSize)). */
+.co-swatch-grid {
+  display: grid;
+  justify-content: start;
+}
+
+.co-swatch-grid__swatch {
+  /* width / height / border-radius van inline (swatchSize, radius). */
+  box-sizing: border-box;
+  padding: 0;
+  margin: 0;
+  border: 1px solid transparent;
+  /* El color va como capa superior sobre un damero, así un rgba() se ve
+     translúcido en vez de fundirse con el fondo del panel. */
+  background:
+    linear-gradient(var(--co-swatch-grid-color), var(--co-swatch-grid-color)),
+    conic-gradient(var(--co-color-gray-200) 25%, #ffffff 0 50%, var(--co-color-gray-200) 0 75%, #ffffff 0) 0 0 / 8px 8px;
+  cursor: pointer;
+  outline: none;
+  transition: box-shadow var(--co-motion-duration-fast) var(--co-motion-ease-out);
+}
+
+/* Borde automático para los claros (luminancia > 0,85): sin él, un blanco
+   sobre el panel blanco no tiene silueta. */
+.co-swatch-grid__swatch--light {
+  border-color: var(--co-color-opacity-negro-8);
+}
+
+.co-swatch-grid__swatch:hover {
+  box-shadow: 0 0 0 1px var(--co-color-opacity-negro-16);
+}
+
+/* Anillo de 2px accent en el seleccionado, separado del swatch por 1px de fondo. */
+.co-swatch-grid__swatch--selected,
+.co-swatch-grid__swatch--selected:hover {
+  box-shadow:
+    0 0 0 1px var(--co-semantic-surface-page, #ffffff),
+    0 0 0 3px var(--co-semantic-accent);
+}
+
+/* Anillo de foco por teclado — solo :focus-visible (misma regla que co-icon-button). */
+.co-swatch-grid__swatch:focus-visible {
+  box-shadow:
+    0 0 0 1px var(--co-semantic-surface-page, #ffffff),
+    0 0 0 3px var(--co-semantic-border-focus);
+}