@prolibu-suite/cobalt-core 0.10.3 → 0.11.0

package/dist/types/components/co-document-editor/co-document-editor.d.ts

@@ -0,0 +1,276 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+import type { Editor, FieldInfo, ImageUploadHandler, MergeFieldAttributes, PrintImageMode, ToolbarExtraItem } from '@prolibu-suite/cobalt-rich-text';
+import { type RichTextStrings } from '../../utils/richTextI18n';
+export interface DocumentFeatures {
+    /** Campos `[[nombre]]` (default true). */
+    fields?: boolean;
+    /** Marcadores de firma `⟦sig:N⟧` (default true). */
+    signatureSlots?: boolean;
+}
+/** Igual al detalle que emite co-rich-text-toolbar para un botón del host (`extraItems`). */
+export interface DocumentActionDetail {
+    action: string;
+    payload: {
+        extra: true;
+    };
+}
+export interface DocumentHeaderDetail {
+    html: string;
+    showPageNumber: boolean;
+}
+export type DocumentPageSize = 'letter' | 'a4' | 'legal' | {
+    width: number;
+    height: number;
+};
+export interface DocumentMargins {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Editor de documentos paginado: hoja fija, encabezado en banda, campos y
+ * firmas (spec contracts-v2-contract-editor §4.2). Recibe y devuelve SOLO el
+ * cuerpo (HTML de impresión) y el HTML del encabezado; no sabe de contratos.
+ * Nunca serializa por tecla: `coChange` solo avisa y el host pide
+ * `getPrintHtml()` cuando lo necesita.
+ *
+ * `shadow: false` (como co-rich-text-editor): ProseMirror arma su DOM de forma
+ * imperativa y el CSS de impresión del host tiene que alcanzarlo.
+ *
+ * @slot aside - Panel lateral del host (ancho fijo del componente: `--co-doc-aside-width`, 320px por defecto). Mantener el hijo siempre montado (v-show).
+ * @part wrapper - Contenedor externo
+ * @part bar - Fila de la barra
+ * @part toolbar - Barra de formato
+ * @part canvas - Superficie donde se centran las hojas
+ * @part sheet - El papel
+ * @part header-band - Banda del encabezado de la primera hoja
+ */
+export declare class CoDocumentEditor {
+    el: HTMLElement;
+    /** Cuerpo: HTML de impresión (tolera el que guardó V1) o JSON de ProseMirror como string. */
+    value: string | null;
+    /** HTML del encabezado (banda superior de cada hoja). Vacío = sin encabezado. */
+    headerHtml: string;
+    /** Número de página en la banda. Se lee como intención: `true` o `'true'`. */
+    showPageNumber: boolean | string;
+    /** `letter` | `a4` | `legal` o `{width, height}` en px a 96 dpi (objeto o JSON). */
+    pageSize: string | DocumentPageSize;
+    /** Márgenes en px (objeto o JSON). Default 38 px por lado (10 mm). */
+    margins?: string | DocumentMargins;
+    /** Alto de la banda del encabezado en px (cuando hay encabezado). */
+    headerHeight: number;
+    /** CSS de impresión del host; se acota a la hoja. */
+    pageStyles: string;
+    /** `{fields, signatureSlots}` (objeto o JSON). */
+    features?: string | DocumentFeatures;
+    /** `(file) => Promise<{src, fileId?}>` (propiedad JS). */
+    imageUpload?: ImageUploadHandler;
+    readonly: boolean;
+    /** BCP-47 para los textos de la UI ('es', 'en', 'pt-BR'…). */
+    locale: string;
+    /** Botones del host al final de la barra (objeto o JSON): `[{id, label, icon?}]`. */
+    extraItems?: string | ToolbarExtraItem[];
+    /** Nombre accesible del área de edición. */
+    label?: string;
+    /** Hubo un cambio del usuario en el cuerpo (sin HTML; como mucho cada 250 ms). */
+    coChange: EventEmitter<void>;
+    /** Lista de campos (cuerpo + encabezado) cuando cambia. */
+    coFieldsChange: EventEmitter<FieldInfo[]>;
+    /** Encabezado confirmado. */
+    coHeaderChange: EventEmitter<DocumentHeaderDetail>;
+    /** Cantidad de páginas. */
+    coPagesChange: EventEmitter<number>;
+    /** Clic en un botón del host (`extraItems`): `{ action: <id>, payload: { extra: true } }`. */
+    coAction: EventEmitter<DocumentActionDetail>;
+    coReady: EventEmitter<void>;
+    ready: boolean;
+    pageCount: number;
+    /** `custom` = zoom libre por gesto (pinza del trackpad / ctrl+rueda); la escala queda donde la dejó el usuario. */
+    zoomMode: 'fit' | 'actual' | 'custom';
+    scale: number;
+    stageHeight: number;
+    /** La banda del encabezado está en edición (editor `print-header` montado). */
+    headerEditing: boolean;
+    /** Interruptor de número de página mientras se edita (se confirma con el encabezado). */
+    draftShowPageNumber: boolean;
+    /** Barra de diseño de la imagen seleccionada en el cuerpo (null = no hay). Posición en px del papel. */
+    imageBar: {
+        mode: PrintImageMode;
+        top: number;
+        left: number;
+    } | null;
+    private editor?;
+    private contentEl?;
+    private canvasEl?;
+    private stageEl?;
+    private styleEl?;
+    private resizeObserver?;
+    /** Encabezado vigente (confirmado). La Task 16 lo cambia al confirmar la banda. */
+    protected currentHeaderHtml: string;
+    protected currentShowPageNumber: boolean;
+    private headerEditor?;
+    private headerMountEl?;
+    private headerBandEl?;
+    /** JSON del encabezado confirmado (lista de campos sin montar un editor). */
+    private headerDoc;
+    private toolbarEl?;
+    private readonly instanceId;
+    private applyingExternal;
+    private lastAppliedValue;
+    private userDirty;
+    private lastFieldsKey;
+    /** src de imágenes insertadas por el usuario sin `width`: al cargar reciben uno (nota T8). */
+    private pendingImageSrcs;
+    private changeThrottle;
+    protected get s(): RichTextStrings;
+    private get resolvedFeatures();
+    private get parsedExtraItems();
+    private get pageSizePx();
+    private get marginsPx();
+    /** Con la banda en edición hay banda aunque el encabezado confirmado esté vacío. */
+    private get hasHeader();
+    private get sanitizedHeaderHtml();
+    private get pageScope();
+    /** Editor que maneja la barra: el del encabezado mientras la banda está en edición. */
+    private get activeEditor();
+    /** «Encabezado» en la barra: apagado en solo lectura y con la banda ya abierta. */
+    private get documentHeaderEnabled();
+    /** Paginación del cuerpo: tamaño, márgenes y banda del encabezado. */
+    private buildCustomExtensions;
+    /** Campos del cuerpo y, detrás, los del encabezado (el que se edita o el confirmado). */
+    private collectAllFields;
+    connectedCallback(): void;
+    componentWillLoad(): void;
+    componentDidLoad(): void;
+    componentDidRender(): void;
+    disconnectedCallback(): void;
+    onValueChange(next: string | null): void;
+    onReadonlyChange(): void;
+    onPageGeometryChange(): void;
+    onHeaderPropsChange(): void;
+    onPageStylesChange(): void;
+    onLabelChange(): void;
+    /** «Página N / M» de las bandas de salto sale del idioma: redibujarlas. */
+    onLocaleChange(): void;
+    /** Cuerpo en la forma canónica de impresión (spec §3.4). */
+    getPrintHtml(): Promise<string>;
+    /**
+     * HTML del encabezado confirmado: el de la prop tal cual, o la forma canónica
+     * si pasó por la banda o por `setFieldValues`. Lo que se está editando en la
+     * banda sin confirmar NO cuenta.
+     */
+    getHeaderHtml(): Promise<string>;
+    getJSON(): Promise<object | null>;
+    /**
+     * Emite YA el `coChange` pendiente (no-op si no hay). El host lo llama antes de
+     * decidir «cambios sin aplicar» (cerrar, navegar): `coChange` sale al final de
+     * la ventana de 250 ms y una edición recién tipeada todavía no avisó.
+     * El blur del editor y un Escape dentro del componente lo hacen solos.
+     */
+    flushChange(): Promise<void>;
+    /**
+     * ¿Cuerpo vacío? En print un documento vacío NO serializa a `''`
+     * (`<p><br class="ProseMirror-trailingBreak"></p>`): el host pregunta acá.
+     */
+    isEmpty(): Promise<boolean>;
+    /** Reemplaza el cuerpo (HTML de impresión, V1 incluido). A diferencia del RTE, NO emite coChange. */
+    setContent(html: string): Promise<void>;
+    /**
+     * Valores de los campos (cuerpo y encabezado) en UNA transacción por editor; no
+     * cuenta como edición del usuario ni emite coHeaderChange. Con la banda abierta
+     * se aplican también al confirmado, así cancelar no los pierde.
+     */
+    setFieldValues(values: Record<string, string>): Promise<void>;
+    insertField(name: string, opts?: Partial<Omit<MergeFieldAttributes, 'name'>>): Promise<void>;
+    insertSignatureSlot(): Promise<void>;
+    focusEditor(): Promise<void>;
+    getEditorInstance(): Promise<Editor | null>;
+    /** Listeners y atributos del editor del cuerpo. */
+    private wireEditor;
+    private imageModeLabel;
+    /**
+     * Barra bajo la imagen seleccionada (corre en cada transacción del cuerpo). Solo
+     * cambia el estado si cambió algo: sin re-render por tecla ni bucles.
+     */
+    private updateImageBar;
+    /**
+     * Sin `.focus()`: con el mouse el mousedown de la barra ya no le quita el foco al
+     * editor, y con el teclado el foco se queda en el botón (se puede seguir en la barra).
+     * H7: el comando re-selecciona el nodo, así la barra sigue tras el cambio.
+     */
+    private setImageMode;
+    /** Imágenes que entran por una transacción del usuario sin `width` (barra, pegar, soltar, subida). */
+    private trackInsertedImages;
+    /** Una imagen insertada sin ancho nace acotada a la columna (V1 la abriría a 800 px). */
+    private onBodyImageLoad;
+    /** Al salir del editor (p. ej. mousedown en «Cerrar») el aviso no espera la ventana. */
+    private onEditorBlur;
+    private onHostKeydown;
+    /** JSON de ProseMirror como string, o HTML de impresión (V1 incluido) por el lector tolerante. */
+    private parseBody;
+    private applyBody;
+    private onTransaction;
+    private emitPendingChange;
+    private emitFieldsIfChanged;
+    private syncToolbar;
+    /** La barra emite coAction burbujeante: se corta acá y solo salen los botones del host. */
+    private handleToolbarAction;
+    protected syncHeaderFromProps(): void;
+    private startHeaderEdit;
+    private mountHeaderEditor;
+    /** `resync`: devolverle la barra al cuerpo (no al desconectar: la barra ya se soltó). */
+    private teardownHeaderEditor;
+    /** Cambios en la banda: solo la lista de campos (decisión 16: el encabezado no emite coChange). */
+    private onHeaderTransaction;
+    /** Como fitHeaderImage de V1: una imagen sin ancho se ajusta a la banda (40×400) al cargar. */
+    private onHeaderImageLoad;
+    /** Clic afuera de la banda (y de la barra, que la edita) confirma. */
+    private onDocumentPointer;
+    /**
+     * Esc cancela y NO sigue hasta el editor ni burbujea al host (no cierra el overlay
+     * de abajo). Convive con `onHostKeydown`: el host captura antes (es ancestro) y
+     * solo adelanta el coChange pendiente del cuerpo.
+     */
+    private onHeaderKeydown;
+    /** ¿El foco está en la banda (editor, interruptor, ✓) o se perdió al `<body>`? */
+    private focusIsInBandOrLost;
+    /**
+     * `restoreFocus`: confirmar con el ✓ (teclado o clic) desmonta el botón enfocado →
+     * el foco vuelve al cuerpo. El clic afuera NO lo toca: el foco ya se fue adonde se hizo clic.
+     */
+    private commitHeader;
+    /** `restoreFocus` solo para la cancelación del usuario (Esc); un cambio de prop no roba el foco. */
+    private cancelHeader;
+    /** Tamaño, márgenes o banda cambiaron: la extensión redibuja bandas y vuelve a medir. */
+    protected refreshPagination(): void;
+    private applyPageStyles;
+    /** Cabecera de la hoja `page` dentro de una banda de salto (DOM imperativo: la pinta un widget). */
+    protected buildHeaderClone(page: number, count: number): HTMLElement | null;
+    private updateScale;
+    /** Escala que refleja el DOM (se actualiza en componentDidRender). */
+    private renderedScale;
+    /** Punto del papel a mantener bajo el cursor hasta el próximo render. */
+    private pendingAnchor?;
+    /**
+     * Zoom libre anclado al cursor: guarda el punto del PAPEL bajo el puntero (con la escala que el
+     * DOM muestra ahora) y, tras el render, corrige el scroll midiendo dónde quedó. Varios eventos
+     * antes de un render reusan el mismo punto: la hoja todavía no se movió.
+     */
+    private zoomTo;
+    private applyPendingAnchor;
+    private onCanvasWheel;
+    /** Safari no manda la pinza como ctrl+wheel sino como GestureEvent (escala acumulada desde el inicio). */
+    private gestureBase;
+    private onGestureStart;
+    private onGestureChange;
+    private setZoom;
+    /**
+     * Banda de la primera hoja. Siempre montada (oculta con `hidden`); doble clic la
+     * vuelve un editor `print-header` con el interruptor de número de página.
+     */
+    protected renderHeaderBand(): any;
+    /** Controles flotantes sobre la hoja: la barra de diseño de la imagen seleccionada. */
+    protected renderOverlays(): any;
+    render(): any;
+}

package/dist/types/components/co-document-editor/document-props.d.ts

@@ -0,0 +1,6 @@
+import type { DocumentMargins, DocumentPageSize } from './co-document-editor';
+export declare const DEFAULT_MARGINS: DocumentMargins;
+/** `true` o `'true'`. Un `'false'` que dejó el multipart de V1 cuenta como falso (spec §3.6). */
+export declare function toBoolIntent(v: unknown): boolean;
+export declare function parsePageSize(v: unknown): DocumentPageSize;
+export declare function parseMargins(v: unknown): DocumentMargins;

package/dist/types/components/co-document-editor/header-tools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Herramientas de la banda del encabezado en edición (interruptor de número de
+ * página + ✓). La fila cuelga ENCIMA de la banda, dentro del margen superior de la
+ * hoja, y el papel tiene `overflow: clip`: tiene que entrar en el margen mínimo
+ * (10 mm = 38 px) o se recorta. `co-icon-button size="sm"` mide 48 px: el tamaño va
+ * por `box-size`. Fila = max(✓, switch de 24) + padding + borde (ver la prueba).
+ */
+export declare const HEADER_TOOL_BOX_PX = 28;
+export declare const HEADER_TOOL_ICON_PX = 16;
+/** Margen superior más chico que se admite (10 mm a 96 dpi, el default del componente). */
+export declare const MIN_TOP_MARGIN_PX = 38;

package/dist/types/components/co-document-editor/image-bar.d.ts

@@ -0,0 +1,50 @@
+import type { PrintImageMode } from '@prolibu-suite/cobalt-rich-text';
+/**
+ * Barra de diseño de imagen (4 modos de V1). Vive DENTRO del papel, que tiene
+ * `overflow: clip`: su posición se decide acá para que nunca quede recortada.
+ * Las medidas son las del CSS (`.co-doc-editor__image-bar` / `__image-mode`,
+ * ver la prueba): se calculan sin medir el DOM porque la barra todavía no existe
+ * cuando se decide dónde va.
+ */
+export declare const IMAGE_MODE_ICONS: Record<PrintImageMode, string>;
+/** Botón de modo (ancho = alto). */
+export declare const IMAGE_MODE_BUTTON_PX = 28;
+export declare const IMAGE_MODE_ICON_PX = 16;
+/** 4 botones × 28 + 3 separaciones de 2 + relleno 2 × 2 + borde 1 × 2. */
+export declare const IMAGE_BAR_SIZE: {
+    width: number;
+    height: number;
+};
+/** Aire entre la imagen y la barra. */
+export declare const IMAGE_BAR_GAP_PX = 4;
+export interface Box {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+export type ImageBarPlacement = 'below' | 'above' | 'inside';
+/**
+ * Debajo de la imagen (por defecto: una imagen pegada al margen superior no la
+ * saca por arriba); si no entra debajo (final del papel), encima; si tampoco,
+ * dentro de la imagen, sobre su borde inferior. En horizontal se acota al papel.
+ * Un papel sin medidas (0) no acota.
+ */
+export declare function imageBarPosition(img: Box, sheet: {
+    width: number;
+    height: number;
+}, bar?: {
+    width: number;
+    height: number;
+}, gap?: number): {
+    top: number;
+    left: number;
+    placement: ImageBarPlacement;
+};
+/** `offsetLeft` acumulado hasta `root` (par de `layoutBox`, que da el top). */
+export declare function layoutLeft(el: HTMLElement, root: HTMLElement): number;
+/**
+ * Ancho con el que nace una imagen insertada (nota T8 / plan B §6.4): sin `width`,
+ * V1 la abre a 800 px, más que la columna (≈740 en carta). Nunca pasa de la columna.
+ */
+export declare function defaultImageWidth(naturalWidth: number, columnWidth: number): number | null;

package/dist/types/components/co-document-editor/page-styles.d.ts

@@ -0,0 +1 @@
+export declare function scopePageStyles(css: string, scope: string): string;

package/dist/types/components/co-document-editor/zoom.d.ts

@@ -0,0 +1,26 @@
+/** Aire lateral que se descuenta del lienzo al ajustar al ancho (2 × --co-spacing-lg). */
+export declare const ZOOM_GUTTER_PX = 32;
+/** Escala para que la hoja entre en el ancho disponible: nunca agranda, nunca baja de 25 %. */
+export declare function fitScale(available: number, pageWidth: number): number;
+/** Tope del zoom libre (pinza / ctrl+rueda). El piso es el mismo de «Ajustar al ancho». */
+export declare const ZOOM_MIN = 0.25;
+export declare const ZOOM_MAX = 3;
+/** Acota la escala a [ZOOM_MIN, ZOOM_MAX] y la redondea a milésimas (NaN → 1). */
+export declare function clampScale(scale: number): number;
+/**
+ * Nueva escala para un evento `wheel` con ctrlKey (la pinza del trackpad llega así en Chrome,
+ * Edge y Firefox; también ctrl+rueda del mouse). Exponencial: acercar y alejar el mismo delta
+ * vuelve al punto de partida, y la velocidad se siente igual a cualquier escala.
+ */
+export declare function pinchScale(current: number, deltaY: number): number;
+/**
+ * Punto del papel (px de layout, sin escala) bajo el cursor: `stageStart` es el borde de la hoja
+ * escalada en pantalla (getBoundingClientRect), `scale` la escala que el DOM refleja HOY.
+ */
+export declare function paperPoint(client: number, stageStart: number, scale: number): number;
+/**
+ * Cuánto hay que correr el scroll para que el punto `paper` vuelva a quedar bajo el cursor,
+ * medido DESPUÉS del render con la escala nueva (la hoja está centrada y el lienzo tiene
+ * relleno fijo: predecir la posición falla, medirla no).
+ */
+export declare function anchorCorrection(stageStart: number, paper: number, scale: number, client: number): number;

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

@@ -0,0 +1,72 @@
+import { EventEmitter } from '../../stencil-public-runtime';
+import { type GradientStop, type GradientStopAddDetail, type GradientStopMoveDetail } from '../../utils/gradientStops';
+/**
+ * Barra de paradas de un degradado (popover de relleno del editor): arrastrar
+ * una parada, agregar una con click sobre la barra y seleccionar.
+ *
+ * Contrato de eventos (pensado para el historial de deshacer del host):
+ * - `coStopMove` — continuo, en cada movimiento del arrastre (preview en vivo).
+ * - `coStopsChange` — UNA vez al terminar el gesto (siempre que hubo al menos
+ *   un `coStopMove`, aunque el stop vuelva a su posición inicial: el host cierra
+ *   ahí su transacción) y una vez por cada paso de teclado.
+ * - `coStopSelect` — al hacer pointerdown sobre un handle.
+ * - `coStopAdd` — al hacer click sobre el track fuera de un handle; `color` es
+ *   el interpolado en esa posición.
+ * Con `disabled` no se emite nada.
+ *
+ * El componente es controlado: `stops` los pinta el host. Durante el arrastre
+ * el handle se pinta en la posición viva aunque el host no aplique cada
+ * `coStopMove`.
+ */
+export declare class CoGradientBar {
+    el: HTMLElement;
+    /** Paradas del degradado: `position` 0–100, `color` hex/rgba. */
+    stops: GradientStop[];
+    /** Índice de la parada seleccionada (anillo `accent`). Se actualiza al hacer pointerdown en un handle. */
+    selected?: number;
+    /** Deshabilita toda interacción; no se emite ningún evento. */
+    disabled: boolean;
+    /** aria-label del grupo. Vacío = el del `locale`. */
+    label?: string;
+    /** Locale de los strings integrados (es/en/pt). */
+    locale?: string;
+    /** Índice de la parada en arrastre; -1 sin gesto. */
+    dragIndex: number;
+    /** Posición viva de la parada en arrastre. */
+    dragPosition: number;
+    /** `{ index, position }` en cada movimiento del arrastre. */
+    coStopMove: EventEmitter<GradientStopMoveDetail>;
+    /**
+     * Paradas resultantes al soltar (una vez por gesto) o tras cada paso de
+     * teclado. Conserva el ORDEN e ÍNDICES del `stops` del host (solo cambia
+     * `position` de la parada movida): un host que ordene por posición al
+     * confirmar debe remapear `selected` al índice nuevo.
+     */
+    coStopsChange: EventEmitter<GradientStop[]>;
+    /** Índice de la parada al hacer pointerdown sobre su handle. */
+    coStopSelect: EventEmitter<number>;
+    /** `{ position, color }` al hacer click sobre el track fuera de un handle. */
+    coStopAdd: EventEmitter<GradientStopAddDetail>;
+    private trackEl?;
+    private pointerId;
+    /** Desplazamiento entre el puntero y el centro del handle al agarrarlo, para que no salte. */
+    private grabOffset;
+    /** Hubo al menos un `coStopMove` en el gesto → al soltar se emite `coStopsChange`. */
+    private dragMoved;
+    disconnectedCallback(): void;
+    private positionAt;
+    /** `stops` del host; un `undefined` explícito (wrappers React/Vue) cuenta como vacío. */
+    private get stopList();
+    private withPosition;
+    /** Paradas a pintar: las del host, con la que se arrastra en su posición viva. */
+    private liveStops;
+    private handleTrackClick;
+    private handleHandlePointerDown;
+    private handleWindowPointerMove;
+    private handleWindowPointerUp;
+    private endDrag;
+    private bindWindow;
+    private unbindWindow;
+    private handleHandleKeyDown;
+    render(): any;
+}

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

@@ -1,10 +1,21 @@
+/**
+ * @slot - Glifo propio (p.ej. un `<svg>` inline de 16px) que ocupa el lugar del
+ *         `co-icon` cuando NO se pasa `icon`. Va dentro del `<button>`, así que
+ *         hereda `color`/`currentColor`, la opacidad de hover/disabled, el
+ *         `:active` y el color de `selected` sin trabajo extra; mide lo mismo
+ *         que mediría el `co-icon` de esa talla (o `iconSize`) vía
+ *         `--co-icon-button-glyph-size`. Con `icon` el slot no se monta (DOM
+ *         idéntico al de siempre). El glifo proyectado no aporta nombre
+ *         accesible: pasar `label` siempre.
+ */
 export declare class CoIconButton {
     /**
      * filled = dark background (negro), outlined = light background (blanco + border),
-     * ghost = transparent background, no border, tinted hover (negro-8 on light / blanco-16 on dark).
+     * ghost = transparent background, no border, tinted hover (negro-8 on light / blanco-16 on dark),
+     * soft = fondo gris sólido (--co-color-gray-100), sin borde visible, sin frost.
      * Matches Figma: Secundario → filled, Primario → outlined
      */
-    variant: 'filled' | 'outlined' | 'ghost';
+    variant: 'filled' | 'outlined' | 'ghost' | 'soft';
     /**
      * Surface the button sits on. `dark` → white icon + blanco-16 hover (on-dark theming).
      * Defaults to `light` (no extra class → identical to previous behavior).
@@ -48,5 +59,26 @@ export declare class CoIconButton {
     toggled: boolean;
     /** Icon weight */
     iconWeight: 'regular' | 'thin' | 'light' | 'bold' | 'fill' | 'duotone';
+    /**
+     * Estado de selección (transversal, gana sobre cualquier `variant`): fondo/color
+     * de acento. Reflejado para que `:host([selected])` sea estilable desde afuera y
+     * marca `aria-pressed="true"` en el `<button>` (ausente cuando no está selected,
+     * en vez de "false", para no alterar el árbol de accesibilidad por defecto).
+     */
+    selected: boolean;
+    /**
+     * Ocupa el espacio disponible del contenedor flex (`flex: 1 1 0; min-width: 0`) en
+     * vez del ancho fijo por `size` — para filas de N botones repartidos en el 100%.
+     */
+    fluid: boolean;
+    /**
+     * Agrega un `caret-down` de 8px a la derecha del icono principal (botones-disclosure).
+     * Ensancha la caja +8px (el alto no cambia) para que el caret no le robe espacio
+     * al icono — fix round 1: la primera versión usaba `padding-right`, que con
+     * `box-sizing: border-box` y ancho fijo por talla ENCOGE el área de contenido en
+     * vez de agrandar la caja (overflow real en xs/xxs). Sin `caret`, el DOM/CSS
+     * quedan idénticos al comportamiento anterior.
+     */
+    caret: boolean;
     render(): any;
 }

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

@@ -4,6 +4,7 @@ import { EventEmitter } from '../../stencil-public-runtime';
  * Supports vertical and horizontal label layouts, action button, and chips.
  *
  * @slot - Default slot for custom content inside the field
+ * @slot prefix - Slot for prefix content (e.g. "$", "https://") rendered right before the native input, inside the input wrapper
  * @slot suffix - Slot for suffix content (e.g. toggle password icon) rendered after the input
  * @slot action - Slot for action button, rendered flush-right inside the field (Botón variant)
  * @slot chips - Slot for chip/tag elements rendered before the input (Chips variant)
@@ -57,15 +58,23 @@ export declare class CoInput {
     autocomplete?: string;
     /** Validation status */
     status: 'default' | 'error' | 'success' | 'warning' | 'info';
-    /** Size variant: s (28px), sm (32px), md (40px, default), lg (48px).
+    /** Size variant: xs (24px), s (28px), sm (32px), md (40px, default), lg (48px).
      *  In the filled search-pill variant (`fill`) this drives the pill height
      *  instead (s ≈ 38px). */
-    size: 's' | 'sm' | 'md' | 'lg';
+    size: 'xs' | 's' | 'sm' | 'md' | 'lg';
     /** Visual style. `flat` strips the field's border and background so it
      *  reads as plain content instead of a boxed input — padding, label, focus
-     *  ring, disabled and status states are unaffected. `default` (the
-     *  standard bordered box) renders identically to before this prop existed. */
-    variant: 'default' | 'flat';
+     *  ring, disabled and status states are unaffected. `soft` renders a solid
+     *  gray-100 background with a transparent 1px border (same width as
+     *  default, so nothing shifts) and no backdrop-filter — the disabled state
+     *  keeps that gray-100 background and dims the field's content instead.
+     *  `default` (the standard bordered box) renders identically to before
+     *  this prop existed. */
+    variant: 'default' | 'flat' | 'soft';
+    /** Tamaño en px de los íconos `iconLeft`/`iconRight` (pasado al `co-icon`
+     *  interno). Sin este prop, el campo sigue con el tamaño fijo que ya tenía
+     *  (16px) — comportamiento idéntico a antes de esta prop. */
+    iconSize?: number;
     /** Filled search-pill variant. When true the field renders as a minimal gray
      *  pill (background gray-100, no border/box-shadow, 10px radius) with a search
      *  glyph on the left and a plain-`x` clear — the floating label, helper text and

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

@@ -0,0 +1,43 @@
+/**
+ * co-kbd — grupo de teclas de un atajo (p.ej. "shift+1", "mod+0", "v").
+ * Modificadores como ícono Phosphor en mac, como etiqueta i18n en win;
+ * teclas sueltas como texto en mayúscula. Con `chord`, toda la combinación
+ * va en UN solo chip (sin separadores).
+ *
+ * Usage:
+ *   <co-kbd keys="mod+0" />
+ *   <co-kbd keys="v" surface="dark" size="xs" />
+ *   <co-kbd keys="mod+0" chord />
+ */
+export declare class CoKbd {
+    /** Combinación de teclas separadas por "+", p.ej. "shift+1", "mod+0", "v". */
+    keys: string;
+    /**
+     * Plataforma para resolver el render de los modificadores:
+     * `mac` → íconos Phosphor (⌘⇧⌥⌃); `win` → etiquetas de texto (`kbdI18n`).
+     * `auto` detecta por `navigator.platform`/`userAgent`; sin señal de Mac
+     * (p.ej. jsdom en tests) cae a `win`.
+     */
+    platform: 'auto' | 'mac' | 'win';
+    /** Superficie donde se apoya: `light` → fondo gray-100 (texto oscuro);
+     *  `dark` → blanco-16 (texto blanco) — pensado para pills oscuras, p.ej.
+     *  `co-tooltip` variant="label". */
+    surface: 'light' | 'dark';
+    /** Tamaño de cada tecla: `sm` 30×18 (con ícono 12px) · `xs` 16×16 (solo texto/1 char). */
+    size: 'sm' | 'xs';
+    /** Locale BCP-47 (p.ej. "es-CO") para las etiquetas de texto en `win`. Sin
+     *  locale explícito, `kbdI18n` resuelve a 'en'. */
+    locale?: string;
+    /**
+     * Modo acorde: toda la combinación en UN solo chip (`part="key"`; 30×18 en
+     * `sm`, 16 de alto en `xs`), sin separadores "+" — cada token va en una
+     * celda (`part="cell"`) de 12 de alto: ícono Phosphor de 12px en una celda
+     * de 12×12 fija (modificadores en mac); texto en una celda que crece con su
+     * contenido, mínimo 12 (modificadores en win, teclas sueltas). El chip
+     * ensancha con las celdas. `role="group"` y `aria-label` no cambian. Sin
+     * `chord`, el modo de siempre: un chip por tecla + separadores.
+     */
+    chord: boolean;
+    private resolvePlatform;
+    render(): any;
+}

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

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