@caribeng/ui 22.1.0 → 22.2.0

package/types/caribeng-ui.d.ts

@@ -1,6 +1,436 @@
-import * as _angular_core from '@angular/core';
+import * as i0 from '@angular/core';
 import { InjectionToken, EnvironmentProviders, Signal } from '@angular/core';
 
+/**
+ * Textos de interfaz de CaribeNG (etiquetas accesibles, botones, placeholders y
+ * mensajes por defecto). Claves planas al estilo de PrimeNG; las partes
+ * variables se escriben como `{0}`, `{1}`… y se rellenan con `cbFormat()`.
+ *
+ * Para traducir o personalizar: `provideCaribeNG({ locale: 'en', translation: { … } })`
+ * o, en caliente, `inject(CbLocaleService).use('en')`.
+ */
+interface CbTranslation {
+    close: string;
+    clear: string;
+    remove: string;
+    /** `{0}`: elemento. */
+    removeItem: string;
+    search: string;
+    filterOptions: string;
+    noResults: string;
+    noData: string;
+    select: string;
+    /** `{0}`: elemento. */
+    selectItem: string;
+    /** `{0}`: cantidad. */
+    selectedCount: string;
+    selectAll: string;
+    options: string;
+    moreActions: string;
+    add: string;
+    onThisPage: string;
+    trendUp: string;
+    trendDown: string;
+    /** `{0}`: nombre del elemento (p. ej. "Beneficiario 2"). */
+    itemAdded: string;
+    /** `{0}`: nombre del elemento. */
+    itemRemoved: string;
+    minimum: string;
+    maximum: string;
+    switchToDark: string;
+    switchToLight: string;
+    loading: string;
+    loadingMessage: string;
+    previous: string;
+    next: string;
+    back: string;
+    finish: string;
+    skip: string;
+    start: string;
+    continue: string;
+    /** `{0}`: paso actual, `{1}`: total. */
+    stepOf: string;
+    expand: string;
+    collapse: string;
+    /** `{0}`: elemento. */
+    expandItem: string;
+    /** `{0}`: elemento. */
+    collapseItem: string;
+    togglePanel: string;
+    progress: string;
+    stepsProgress: string;
+    /** `{0}`: número de página. */
+    page: string;
+    pageIndicator: string;
+    download: string;
+    details: string;
+    viewDetails: string;
+    share: string;
+    receipt: string;
+    action: string;
+    actionGroup: string;
+    accept: string;
+    cancel: string;
+    confirm: string;
+    confirmMessage: string;
+    yes: string;
+    no: string;
+    dialog: string;
+    panel: string;
+    sidePanel: string;
+    /** Aviso para enlaces que se abren en otra pestaña. */
+    opensInNewTab: string;
+    showInfo: string;
+    closeEditing: string;
+    menu: string;
+    mainNavigation: string;
+    contextMenu: string;
+    categories: string;
+    appDock: string;
+    panelMenu: string;
+    steps: string;
+    sectionNavigation: string;
+    breadcrumb: string;
+    toolbar: string;
+    quickActions: string;
+    floatingMenu: string;
+    openActions: string;
+    closeActions: string;
+    required: string;
+    optional: string;
+    showSuggestions: string;
+    clearSearch: string;
+    showPassword: string;
+    hidePassword: string;
+    passwordWeak: string;
+    passwordMedium: string;
+    passwordStrong: string;
+    increment: string;
+    decrement: string;
+    verificationCode: string;
+    /** `{0}`: posición. */
+    digit: string;
+    color: string;
+    colorPicker: string;
+    hexColor: string;
+    switch: string;
+    /** `{0}`: valor, `{1}`: máximo. */
+    ratingOf: string;
+    openCalendar: string;
+    hours: string;
+    minutes: string;
+    /** AM / PM en formato de 12 horas. */
+    period: string;
+    /** Aviso tras elegir la fecha inicial de un rango. */
+    chooseEndDate: string;
+    previousMonth: string;
+    nextMonth: string;
+    previousYear: string;
+    nextYear: string;
+    previousDecade: string;
+    nextDecade: string;
+    /** Botón del título del calendario que abre la vista de meses / de años. */
+    chooseMonth: string;
+    chooseYear: string;
+    /** Horas del rango (inicio y fin). */
+    startTime: string;
+    endTime: string;
+    /** Campo escrito con una fecha que no se reconoce. `{0}`: formato esperado. */
+    invalidDate: string;
+    /** Atajos de fecha del DatePicker (`presets`). */
+    datePresets: string;
+    presetYesterday: string;
+    presetLast7Days: string;
+    presetLast30Days: string;
+    presetThisMonth: string;
+    presetLastMonth: string;
+    presetThisYear: string;
+    presetLastYear: string;
+    today: string;
+    /** Iniciales de los días de la semana, de lunes a domingo, separadas por comas. */
+    weekdaysMin: string;
+    chooseFile: string;
+    upload: string;
+    /** `{0}`: texto del botón de elegir. */
+    dropFiles: string;
+    /** `{0}`: nombre del archivo; `{1}`: tamaño máximo. */
+    fileTooLarge: string;
+    /** `{0}`: nombre del archivo. */
+    fileTypeNotAllowed: string;
+    selectDocument: string;
+    /** `{0}`: tipos aceptados. */
+    formats: string;
+    /** `{0}`: cantidad. */
+    filesSelected: string;
+    files: string;
+    pagination: string;
+    firstPage: string;
+    previousPage: string;
+    nextPage: string;
+    lastPage: string;
+    rowsPerPage: string;
+    /** `{0}`: número de fila. */
+    selectRow: string;
+    selectAllRows: string;
+    /** `{0}`: encabezado de la columna. */
+    sortBy: string;
+    /** `{0}`: encabezado de la columna. */
+    filterBy: string;
+    /** `{0}`: encabezado de la columna. */
+    resizeColumn: string;
+    /** `{0}`: número de fila. */
+    expandRow: string;
+    /** `{0}`: cantidad de filas tras filtrar. */
+    resultsCount: string;
+    noRecords: string;
+    moveUp: string;
+    moveDown: string;
+    moveTop: string;
+    moveBottom: string;
+    moveToTarget: string;
+    moveAllToTarget: string;
+    moveToSource: string;
+    moveAllToSource: string;
+    available: string;
+    selected: string;
+    sortableList: string;
+    orgChart: string;
+    changeLayout: string;
+    listView: string;
+    gridView: string;
+    timeline: string;
+    chart: string;
+    chartLegend: string;
+    /** `{0}`: posición. */
+    chartItem: string;
+    /** Cómo recorrer un gráfico con el teclado. */
+    chartInstructions: string;
+    /** Total acumulado (cascada). */
+    chartTotal: string;
+    /** Variación de un paso (cascada). */
+    chartChange: string;
+    /** Precio de apertura, máximo, mínimo y cierre (velas). */
+    chartOpen: string;
+    chartHigh: string;
+    chartLow: string;
+    chartClose: string;
+    /** Botón que vuelve a mostrar todos los datos tras hacer zoom. */
+    chartResetZoom: string;
+    /** Cómo hacer zoom con el teclado y el ratón. */
+    chartZoomInstructions: string;
+    carousel: string;
+    /** `{0}`: posición. */
+    slide: string;
+    /** `{0}`: posición; `{1}`: total. Nombre de cada diapositiva. */
+    slideOf: string;
+    previousImage: string;
+    nextImage: string;
+    /** `{0}`: posición. */
+    thumbnail: string;
+    /** `{0}`: descripción de la imagen. */
+    enlargeImage: string;
+    image: string;
+    imagePreview: string;
+    rotateLeft: string;
+    rotateRight: string;
+    flipHorizontal: string;
+    flipVertical: string;
+    zoomIn: string;
+    zoomOut: string;
+    reset: string;
+    fullscreen: string;
+    pdfViewer: string;
+    pdfDocument: string;
+    pageOf: string;
+    pageNumber: string;
+    ofTotal: string;
+    zoomLevel: string;
+    fitWidth: string;
+    fitPage: string;
+    print: string;
+    preparingPrint: string;
+    thumbnails: string;
+    searchInDocument: string;
+    previousMatch: string;
+    nextMatch: string;
+    matchOf: string;
+    searching: string;
+    loadingDocument: string;
+    documentError: string;
+    protectedDocument: string;
+    incorrectPassword: string;
+    password: string;
+    open: string;
+    scrollableArea: string;
+    scrollTop: string;
+    resizePanels: string;
+    command: string;
+    guidedHelp: string;
+    onboarding: string;
+    animation: string;
+    illustration: string;
+    pictogram: string;
+    decorativeStroke: string;
+    preparingSession: string;
+    monthly: string;
+    yearly: string;
+    choose: string;
+    /** `{0}`: nombre del plan. */
+    chooseItem: string;
+    perMonth: string;
+    perYear: string;
+    textFormatting: string;
+    paragraphStyle: string;
+    normal: string;
+    heading1: string;
+    heading2: string;
+    heading3: string;
+    bold: string;
+    italic: string;
+    underline: string;
+    strikethrough: string;
+    bulletList: string;
+    numberedList: string;
+    quote: string;
+    alignLeft: string;
+    alignCenter: string;
+    alignRight: string;
+    insertLink: string;
+    insertImage: string;
+    clearFormat: string;
+    undo: string;
+    redo: string;
+    editorPlaceholder: string;
+    textEditor: string;
+    linkUrl: string;
+    inlineCode: string;
+    horizontalLine: string;
+    /** Botón que alterna entre el editor y el código HTML. */
+    sourceCode: string;
+    removeLink: string;
+    openInNewTab: string;
+    /** Enlace con un protocolo no permitido (solo http, https, mailto y tel). */
+    invalidUrl: string;
+    /** `{0}`: caracteres usados; `{1}`: máximo. */
+    characterCount: string;
+    /** `{0}`: tamaño máximo (p. ej. "1 MB"). */
+    imageTooLarge: string;
+    imageUploadError: string;
+    codeBlock: string;
+    insertTable: string;
+    tableRows: string;
+    tableColumns: string;
+    tableHeaderRow: string;
+    insert: string;
+    tableTools: string;
+    insertRowAbove: string;
+    insertRowBelow: string;
+    insertColumnLeft: string;
+    insertColumnRight: string;
+    deleteRow: string;
+    deleteColumn: string;
+    deleteTable: string;
+    imageTools: string;
+    imageInline: string;
+    imageAlignLeft: string;
+    imageAlignCenter: string;
+    imageAlignRight: string;
+    imageWidth: string;
+    imageOriginalSize: string;
+    imageResize: string;
+    altText: string;
+    deleteImage: string;
+    tableSize: string;
+    tableRow: string;
+    tableColumn: string;
+    above: string;
+    below: string;
+    toLeft: string;
+    toRight: string;
+    tableDelete: string;
+    tableBorders: string;
+    bordersAll: string;
+    bordersHorizontal: string;
+    bordersNone: string;
+    borderColor: string;
+    colorGray: string;
+    colorDark: string;
+    colorGreen: string;
+    colorBlue: string;
+    cropImage: string;
+    cropArea: string;
+    cropFree: string;
+    cropInstructions: string;
+    cropError: string;
+    exitFullscreen: string;
+    heading4: string;
+    fontSize: string;
+    fontNormal: string;
+    textColor: string;
+    highlight: string;
+    automaticColor: string;
+    noHighlight: string;
+    colorBlack: string;
+    colorRed: string;
+    colorOrange: string;
+    colorYellow: string;
+    colorTeal: string;
+    colorPurple: string;
+    colorPink: string;
+    subscript: string;
+    superscript: string;
+    taskList: string;
+    indent: string;
+    outdent: string;
+    alignJustify: string;
+    alignment: string;
+    wordCount: string;
+    /** Singular de `wordCount`. */
+    wordCountOne: string;
+    charCount: string;
+    fontFamily: string;
+    fontDefault: string;
+    fontGroupRecommended: string;
+    fontGroupOffice: string;
+    fontGroupSans: string;
+    fontGroupSerif: string;
+    fontGroupMono: string;
+    fontGroupAccessible: string;
+    fontGroupFun: string;
+    specialCharacters: string;
+    charsCurrency: string;
+    charsMath: string;
+    charsPunctuation: string;
+    charsArrows: string;
+    charsEmoji: string;
+    findReplace: string;
+    findText: string;
+    replaceWith: string;
+    matchCase: string;
+    wholeWords: string;
+    findPrevious: string;
+    findNext: string;
+    replaceOne: string;
+    replaceAll: string;
+    findCount: string;
+    replacedCount: string;
+    quickFormat: string;
+    insertBlock: string;
+    paragraph: string;
+}
+/** Español (idioma por defecto). */
+declare const CB_LOCALE_ES: CbTranslation;
+/** Inglés. */
+declare const CB_LOCALE_EN: CbTranslation;
+/** Idiomas incluidos. */
+declare const CB_LOCALES: {
+    readonly es: CbTranslation;
+    readonly en: CbTranslation;
+};
+type CbLocaleCode = keyof typeof CB_LOCALES;
+/** Rellena `{0}`, `{1}`… con los argumentos. */
+declare function cbFormat(template: string, ...args: unknown[]): string;
+
 /** Tema inicial de la aplicación. `system` sigue a `prefers-color-scheme`. */
 type CbTheme = 'light' | 'dark';
 type CbThemePreference = CbTheme | 'system';
@@ -33,10 +463,17 @@ interface CaribeNgConfig {
      * input `requiredIndicator`.
      */
     requiredIndicator: CbRequiredIndicator;
-    /** Texto del modo `'text'`. Por defecto `'requerido'` → "(requerido)". */
-    requiredText: string;
-    /** Texto del modo `'optional'`. Por defecto `'opcional'` → "(opcional)". */
-    optionalText: string;
+    /** Texto del modo `'text'`. Si se omite, usa `required` del idioma ("requerido" / "required"). */
+    requiredText?: string;
+    /** Texto del modo `'optional'`. Si se omite, usa `optional` del idioma ("opcional" / "optional"). */
+    optionalText?: string;
+    /**
+     * Idioma de los textos de interfaz (etiquetas accesibles, botones, mensajes
+     * por defecto): `'es'` (por defecto), `'en'` o un objeto `CbTranslation` propio.
+     */
+    locale?: CbLocaleCode | CbTranslation;
+    /** Textos sueltos que sobrescriben los del idioma, p. ej. `{ close: 'Salir' }`. */
+    translation?: Partial<CbTranslation>;
 }
 /**
  * Indicador visual de obligatoriedad en la etiqueta de los campos:
@@ -66,13 +503,13 @@ declare class CbThemeService {
     /** Preferencia elegida por el usuario: 'light' | 'dark' | 'system'. */
     private readonly preference;
     /** Preset de paleta primaria activo. */
-    readonly preset: _angular_core.WritableSignal<CbColorPreset>;
+    readonly preset: i0.WritableSignal<CbColorPreset>;
     /** Resultado de `prefers-color-scheme` (solo relevante con 'system'). */
     private readonly systemDark;
     /** Tema efectivo aplicado al DOM. */
-    readonly theme: _angular_core.Signal<CbTheme>;
+    readonly theme: i0.Signal<CbTheme>;
     /** `true` cuando el tema efectivo es oscuro. */
-    readonly isDark: _angular_core.Signal<boolean>;
+    readonly isDark: i0.Signal<boolean>;
     constructor();
     /** Fija el tema de forma explícita. */
     setTheme(theme: CbThemePreference): void;
@@ -86,8 +523,8 @@ declare class CbThemeService {
     private readSystemDark;
     private restorePersisted;
     private listenSystemPreference;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CbThemeService, never>;
-    static ɵprov: _angular_core.ɵɵInjectableDeclaration<CbThemeService>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CbThemeService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CbThemeService>;
 }
 
 /**
@@ -154,6 +591,58 @@ declare function cbFieldState(manual: {
     requiredIndicator?: () => CbRequiredIndicator | undefined;
 }): CbFieldState;
 
-export { CB_COLOR_PRESETS, CB_CONFIG, CB_DEFAULT_CONFIG, CbThemeService, cbFieldState, provideCaribeNG };
-export type { CaribeNgConfig, CbColorPreset, CbFieldIndicator, CbFieldState, CbPrimaryScale, CbRequiredIndicator, CbSeverity, CbSize, CbTheme, CbThemePreference };
+/** Opciones de {@link cbOverlayFocus}. */
+interface CbOverlayFocusOptions {
+    /** Si el overlay está abierto (se lee como señal). */
+    open: () => boolean;
+    /** Elemento que recibe el foco al abrir (p. ej. el botón de cerrar). */
+    initialFocus: () => HTMLElement | null | undefined;
+}
+/**
+ * Gestión de foco de overlays (diálogos, paneles, popovers), según WAI-ARIA:
+ * al abrirse, recuerda el elemento enfocado y mueve el foco a `initialFocus`;
+ * al cerrarse, devuelve el foco al elemento que lo tenía.
+ *
+ * Debe llamarse en un contexto de inyección (constructor o inicializador de campo).
+ *
+ * @example
+ * ```ts
+ * readonly visible = model(false);
+ * private readonly closeBtn = viewChild<ElementRef<HTMLButtonElement>>('closeBtn');
+ * constructor() {
+ *   cbOverlayFocus({ open: this.visible, initialFocus: () => this.closeBtn()?.nativeElement });
+ * }
+ * ```
+ */
+declare function cbOverlayFocus(options: CbOverlayFocusOptions): void;
+
+/**
+ * Idioma de los textos de interfaz de CaribeNG. Se configura con
+ * `provideCaribeNG({ locale, translation })` y puede cambiarse en caliente:
+ * todos los componentes leen las traducciones como signal.
+ *
+ * ```ts
+ * const locale = inject(CbLocaleService);
+ * locale.use('en');                          // idioma incluido
+ * locale.setTranslation({ close: 'Salir' }); // sobrescribe textos sueltos
+ * ```
+ */
+declare class CbLocaleService {
+    private readonly config;
+    private readonly base;
+    private readonly overrides;
+    /** Traducciones activas (idioma base + textos sobrescritos). */
+    readonly translation: Signal<CbTranslation>;
+    /** Cambia el idioma base (`'es'`, `'en'` o un objeto de traducciones completo). */
+    use(locale: CbLocaleCode | CbTranslation): void;
+    /** Sobrescribe textos sueltos sobre el idioma activo (se acumulan). */
+    setTranslation(translation: Partial<CbTranslation>): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CbLocaleService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CbLocaleService>;
+}
+/** Traducciones activas de CaribeNG como signal (para usar en componentes). */
+declare function injectCbTranslation(): Signal<CbTranslation>;
+
+export { CB_COLOR_PRESETS, CB_CONFIG, CB_DEFAULT_CONFIG, CB_LOCALES, CB_LOCALE_EN, CB_LOCALE_ES, CbLocaleService, CbThemeService, cbFieldState, cbFormat, cbOverlayFocus, injectCbTranslation, provideCaribeNG };
+export type { CaribeNgConfig, CbColorPreset, CbFieldIndicator, CbFieldState, CbLocaleCode, CbOverlayFocusOptions, CbPrimaryScale, CbRequiredIndicator, CbSeverity, CbSize, CbTheme, CbThemePreference, CbTranslation };
 //# sourceMappingURL=caribeng-ui.d.ts.map