@apollion-dsi/core 5.3.0 → 5.5.0

package/lib/dataDisplay/DataTable/DataTable.interface.d.ts

@@ -1,10 +1,10 @@
 import React from 'react';
 import type { ColumnFiltersState, ExpandedState, FilterFn, OnChangeFn, PaginationState, Row } from '../../vendors/TanstackReactTable';
 /**
- * Códigos de cor pré-definidos para destacar linhas inteiras da tabela.
+ * Predefined color codes to highlight entire table rows.
  *
- * Usado pelo callback {@link DataTableProps.setRowColor} para sinalizar status
- * (sucesso, alerta, erro) sem precisar resolver paletas no call-site.
+ * Used by the {@link DataTableProps.setRowColor} callback to signal status
+ * (success, alert, error) without resolving palettes at the call-site.
  */
 export declare enum RowColor {
     primary = "primary",
@@ -13,10 +13,10 @@ export declare enum RowColor {
     error = "danger"
 }
 /**
- * Alinhamento horizontal do conteúdo de uma célula.
+ * Horizontal alignment of a cell's content.
  *
- * Valores correspondem a `justify-content` do flexbox para que possam ser
- * aplicados diretamente no estilo da célula sem mapeamento extra.
+ * Values correspond to flexbox `justify-content` so they can be
+ * applied directly to the cell style without extra mapping.
  */
 export declare enum CellAlign {
     left = "flex-start",
@@ -24,10 +24,10 @@ export declare enum CellAlign {
     right = "flex-end"
 }
 /**
- * Configuração de estilo aplicada a uma célula durante o render.
+ * Style configuration applied to a cell during render.
  *
- * Estrutura interna usada por `DataTable` para combinar dados da coluna
- * (alinhamento, se é checkbox) com props pontuais (`cellProps`).
+ * Internal structure used by `DataTable` to combine column data
+ * (alignment, whether it is a checkbox) with one-off props (`cellProps`).
  */
 export type CellStyle = {
     align?: CellAlign;
@@ -37,86 +37,86 @@ export type CellStyle = {
     cellProps?: React.ComponentPropsWithoutRef<'div'>;
 };
 /**
- * Definição de uma coluna do `DataTable`.
+ * Definition of a `DataTable` column.
  *
- * Cada coluna pode declarar um `accessor` (key do registro), conteúdo
- * customizado via `Cell`/`Footer` e regras de alinhamento, largura e
- * comportamento de ordenação. Use `accessor: null` para colunas puramente
- * decorativas (ex.: coluna de ações).
+ * Each column can declare an `accessor` (record key), custom content
+ * via `Cell`/`Footer`, and rules for alignment, width, and
+ * sorting behavior. Use `accessor: null` for purely decorative
+ * columns (e.g. an actions column).
  *
  * @example
  * ```tsx
  * const columns: Column<User>[] = [
- *   { Header: 'Nome', accessor: 'name' },
- *   { Header: 'Idade', accessor: 'age', align: CellAlign.right },
+ *   { Header: 'Name', accessor: 'name' },
+ *   { Header: 'Age', accessor: 'age', align: CellAlign.right },
  * ];
  * ```
  */
 export type Column<T extends Record<string, unknown>> = {
-    /** Identificador único. Inferido de `accessor` quando omitido. */
+    /** Unique identifier. Inferred from `accessor` when omitted. */
     id?: string;
-    /** Título do cabeçalho. Aceita string ou ReactNode (ex.: ícones + tooltips). */
+    /** Header title. Accepts a string or ReactNode (e.g. icons + tooltips). */
     Header: string | React.ReactNode;
-    /** Renderizador customizado da célula; recebe a linha e o valor extraído. */
+    /** Custom cell renderer; receives the row and the extracted value. */
     Cell?: (props: {
         row: Row<T>;
         value: any;
     }) => React.ReactNode;
-    /** Renderizador customizado do footer da coluna (somatórios, totalizadores). */
+    /** Custom column footer renderer (sums, totals). */
     Footer?: (props: {
         table: any;
     }) => React.ReactNode;
-    /** Key de `T` cujo valor é exibido por padrão; `null` para colunas sem dado. */
+    /** Key of `T` whose value is displayed by default; `null` for data-less columns. */
     accessor: keyof T | null;
-    /** Largura inicial em pixels. */
+    /** Initial width in pixels. */
     width?: number;
-    /** Largura mínima ao redimensionar. */
+    /** Minimum width when resizing. */
     minWidth?: number;
-    /** Largura máxima ao redimensionar. */
+    /** Maximum width when resizing. */
     maxWidth?: number;
-    /** Alinhamento horizontal do conteúdo. */
+    /** Horizontal alignment of the content. */
     align?: CellAlign;
-    /** Quando `false`, cliques na célula não disparam seleção/onRowClick. */
+    /** When `false`, clicks on the cell do not trigger selection/onRowClick. */
     selectable?: boolean;
-    /** Quando `true`, remove o cabeçalho clicável de ordenação. */
+    /** When `true`, removes the clickable sorting header. */
     disableSortBy?: boolean;
     /**
-     * Quando `true`, desliga o filtro por coluna desta coluna:
+     * When `true`, turns off per-column filtering for this column:
      *
-     * - Esconde o ícone de filter no header (mesmo com `filterVariant` setado).
-     * - Marca `enableColumnFilter: false` na `ColumnDef` do tanstack-react-table,
-     *   tirando a coluna do pipeline de `getFilteredRowModel` para filtros
-     *   por-coluna (`globalFilter` continua olhando para a coluna conforme
-     *   `getColumnCanGlobalFilter`).
+     * - Hides the filter icon in the header (even with `filterVariant` set).
+     * - Marks `enableColumnFilter: false` on the tanstack-react-table `ColumnDef`,
+     *   removing the column from the `getFilteredRowModel` pipeline for
+     *   per-column filters (`globalFilter` still looks at the column according
+     *   to `getColumnCanGlobalFilter`).
      *
-     * Ativado a partir do ROADMAP §🟡 "DataTable absorption gaps · Faceted
-     * filters" — em ciclos anteriores essa prop era no-op declarada.
+     * Activated from ROADMAP §🟡 "DataTable absorption gaps · Faceted
+     * filters" — in earlier cycles this prop was a declared no-op.
      *
      * @default false
      */
     disableFilters?: boolean;
     /**
-     * Habilita filtro por coluna. Quando setado, DataTable renderiza um ícone
-     * de filter no header da coluna; click no ícone abre um popover com o UI
-     * apropriado:
+     * Enables per-column filtering. When set, DataTable renders a filter
+     * icon in the column header; clicking the icon opens a popover with the
+     * appropriate UI:
      *
-     * - `'select'`: multi-select de valores únicos (categorical) — usa
-     *   `getFacetedUniqueValues()` para listar opções com contagem.
-     * - `'range'`: dois inputs min/max (numeric) — usa
-     *   `getFacetedMinMaxValues()` para defaults dos bounds.
-     * - `'text'`: input de busca contains (case-insensitive) — debounce 200ms.
+     * - `'select'`: multi-select of unique values (categorical) — uses
+     *   `getFacetedUniqueValues()` to list options with counts.
+     * - `'range'`: two min/max inputs (numeric) — uses
+     *   `getFacetedMinMaxValues()` for the bounds defaults.
+     * - `'text'`: contains search input (case-insensitive) — 200ms debounce.
      *
-     * O filterFn aplicado é resolvido a partir do variant (mapping em
-     * `DataTable.filters.tsx`); use {@link Column.filterFn} para override
-     * custom mantendo a UI da variant.
+     * The applied filterFn is resolved from the variant (mapping in
+     * `DataTable.filters.tsx`); use {@link Column.filterFn} for a custom
+     * override while keeping the variant's UI.
      *
-     * @default undefined (sem filter UI)
+     * @default undefined (no filter UI)
      */
     filterVariant?: 'select' | 'range' | 'text';
     /**
-     * Override do filterFn padrão da variant. Aceita um nome de builtin do
-     * tanstack-react-table (`'includesString'`, `'inNumberRange'`,
-     * `'arrIncludesSome'`, `'equals'`, etc.) ou uma função custom
+     * Override of the variant's default filterFn. Accepts a
+     * tanstack-react-table builtin name (`'includesString'`, `'inNumberRange'`,
+     * `'arrIncludesSome'`, `'equals'`, etc.) or a custom function
      * `(row, columnId, filterValue, addMeta?) => boolean`.
      *
      * @example
@@ -130,175 +130,223 @@ export type Column<T extends Record<string, unknown>> = {
     filterFn?: FilterFn<Record<string, unknown>> | string;
 };
 /**
- * Props específicas do `DataTable` (sem as props do elemento `<div>` que o
- * envolve).
+ * Consumer-overridable UI strings rendered by the `DataTable` chrome
+ * (pagination row and per-column filter popovers).
+ *
+ * Every field is optional — omitted fields keep the current pt-BR
+ * defaults, so passing a partial object is safe. Flipping the defaults to
+ * English is reserved for v6.
+ *
+ * @example
+ * ```tsx
+ * <DataTable
+ *   data={data}
+ *   columns={columns}
+ *   paginated
+ *   labels={{
+ *     showingRange: (start, end, total) => `Showing ${start}-${end} of ${total}`,
+ *     previous: 'Previous',
+ *     next: 'Next',
+ *   }}
+ * />
+ * ```
+ */
+export interface DataTableLabels {
+    /** Range line under the body. Default: `Mostrando ${start}-${end} de ${total}` */
+    showingRange?: (start: number, end: number, total: number) => string;
+    /** Page-size option title in the selector menu. Default: `${size} por página` */
+    perPageOption?: (size: number) => string;
+    /** Page-size trigger button text. Default: `${size} / página` */
+    perPageTrigger?: (size: number) => string;
+    /**
+     * Previous-page button text.
+     *
+     * @default 'Anterior'
+     */
+    previous?: string;
+    /**
+     * Next-page button text.
+     *
+     * @default 'Próximo'
+     */
+    next?: string;
+    /**
+     * Select-filter empty state.
+     *
+     * @default 'Sem valores'
+     */
+    filterNoValues?: string;
+    /**
+     * Text-filter input placeholder.
+     *
+     * @default 'Filtrar...'
+     */
+    filterPlaceholder?: string;
+}
+/**
+ * `DataTable`-specific props (without the props of the wrapping `<div>`
+ * element).
  */
 interface ComponentProps<T extends Record<string, unknown>> {
-    /** Dataset a ser exibido. Deve ser memoizado (`useMemo`). */
+    /** Dataset to display. Must be memoized (`useMemo`). */
     data: T[];
-    /** Definição das colunas. Deve ser memoizada (`useMemo`). */
+    /** Column definitions. Must be memoized (`useMemo`). */
     columns: Array<Column<T>>;
     /**
-     * Quando informado, exibe uma coluna de checkboxes para seleção de linhas.
-     * Aceita string (título da coluna) ou `true` (sem título).
+     * When provided, shows a checkbox column for row selection.
+     * Accepts a string (column title) or `true` (no title).
      */
     selectableColumn?: string | boolean;
-    /** Largura da coluna de seleção, em pixels. */
+    /** Width of the selection column, in pixels. */
     selectableColumnWidth?: number;
-    /** Espaçamento vertical adicional somado à altura da linha. */
+    /** Additional vertical spacing added to the row height. */
     spacing?: number;
     /**
-     * Altura do corpo virtualizado, em pixels.
+     * Height of the virtualized body, in pixels.
      *
      * @default 400
      */
     height?: number;
-    /** Título exibido no header da tabela (requer `hasHeader`). */
+    /** Title displayed in the table header (requires `hasHeader`). */
     title?: string;
-    /** Placeholder do input de busca global. */
+    /** Placeholder of the global search input. */
     searchPlaceholder?: string;
-    /** Callback disparado quando a seleção de linhas muda. */
+    /** Callback fired when the row selection changes. */
     onRowSelect?: (d: T[]) => void;
-    /** Callback disparado ao clicar em qualquer linha. */
+    /** Callback fired when any row is clicked. */
     onRowClick?: (row: T) => void;
-    /** Aplica fundo zebrado em linhas pares. */
+    /** Applies a zebra-striped background to even rows. */
     striped?: boolean;
-    /** Adiciona bordas verticais entre células. */
+    /** Adds vertical borders between cells. */
     bordered?: boolean;
-    /** Exibe o header (título + busca + slots laterais). */
+    /** Shows the header (title + search + side slots). */
     hasHeader?: boolean;
-    /** Renderiza a linha de footer com somatórios definidos em `column.Footer`. */
+    /** Renders the footer row with sums defined in `column.Footer`. */
     hasFooter?: boolean;
-    /** Habilita o menu de densidade (compact/default/expansive). */
+    /** Enables the density menu (compact/default/expansive). */
     hasSpacingMenu?: boolean;
-    /** Slot à esquerda no header — após o título. */
+    /** Left slot in the header — after the title. */
     headerLeftComponent?: React.ReactNode;
-    /** Slot à direita no header — após o input de busca. */
+    /** Right slot in the header — after the search input. */
     headerRightComponent?: React.ReactNode;
     /**
-     * Substitui o `Input` de busca global por um componente custom (útil para
-     * integração com filtros server-side).
+     * Replaces the global search `Input` with a custom component (useful for
+     * integration with server-side filters).
      */
     inputSearchComponent?: React.ReactNode;
     /**
-     * Componente fixo ao final da lista (ex.: botão "carregar mais").
-     * Renderizado pelo `DataTable` na última posição virtual; o
-     * posicionamento absoluto é injetado pelo wrapper interno (não pelo
-     * próprio `lastRowComponent`).
+     * Component pinned to the end of the list (e.g. a "load more" button).
+     * Rendered by `DataTable` at the last virtual position; the
+     * absolute positioning is injected by the internal wrapper (not by
+     * `lastRowComponent` itself).
      */
     lastRowComponent?: React.ReactNode;
-    /** Ícone exibido quando `data` está vazio. */
+    /** Icon shown when `data` is empty. */
     emptyIcon?: React.ReactNode;
-    /** Título do estado vazio. */
+    /** Title of the empty state. */
     emptyTitle?: string;
-    /** Texto auxiliar do estado vazio. */
+    /** Helper text of the empty state. */
     emptyDescription?: string;
     /**
-     * Resolve a cor de fundo de cada linha. Retorne um valor de {@link RowColor}
-     * para destacar status (sucesso, alerta, erro) ou `undefined` para usar o
-     * padrão (incluindo zebrado).
+     * Resolves the background color of each row. Return a {@link RowColor}
+     * value to highlight status (success, alert, error) or `undefined` to use
+     * the default (including zebra striping).
      */
     setRowColor?: (row: Row<T>) => RowColor | undefined;
     /**
-     * Habilita pagination client-side. Quando `true`, o DataTable wireia
-     * `getPaginationRowModel()` no tanstack-react-table e renderiza uma
-     * linha de navegação (Anterior / Próximo + indicador + seletor de
-     * page size) entre o body e o footer.
+     * Enables client-side pagination. When `true`, DataTable wires
+     * `getPaginationRowModel()` into tanstack-react-table and renders a
+     * navigation row ("Anterior" / "Próximo" + indicator + page size
+     * selector) between the body and the footer.
      *
-     * Default `false` — comportamento de scroll virtualizado infinito
-     * preservado.
+     * Default `false` — infinite virtualized scroll behavior
+     * preserved.
      *
      * @default false
      */
     paginated?: boolean;
     /**
-     * Estado inicial da paginação (uncontrolled). Default `{ pageIndex: 0,
+     * Initial pagination state (uncontrolled). Default `{ pageIndex: 0,
      * pageSize: pageSizeOptions[0] ?? 10 }`.
      *
-     * Mutuamente exclusivo com `pagination` (controlled). Se ambos forem
-     * informados, o estado controlado tem precedência.
+     * Mutually exclusive with `pagination` (controlled). If both are
+     * provided, the controlled state takes precedence.
      */
     initialPagination?: Partial<PaginationState>;
     /**
-     * Estado controlado da paginação. Quando informado, `onPaginationChange`
-     * deve atualizar este valor no callsite.
+     * Controlled pagination state. When provided, `onPaginationChange`
+     * must update this value at the callsite.
      */
     pagination?: PaginationState;
-    /** Callback disparado quando a paginação muda. Aceita o updater pattern do tanstack. */
+    /** Callback fired when pagination changes. Accepts the tanstack updater pattern. */
     onPaginationChange?: OnChangeFn<PaginationState>;
     /**
-     * Opções de page size disponíveis no seletor. Default `[10, 25, 50, 100]`.
+     * Page size options available in the selector. Default `[10, 25, 50, 100]`.
      *
-     * Quando o array tem ≤ 1 entradas, o seletor de page size é escondido
-     * (consumer trava o page size).
+     * When the array has ≤ 1 entries, the page size selector is hidden
+     * (the consumer locks the page size).
      */
     pageSizeOptions?: number[];
     /**
-     * Callback que retorna as sub-rows de um row pai (tree expansion). Quando
-     * informado, o DataTable wireia `getExpandedRowModel()` no
-     * tanstack-react-table e injeta uma coluna de toggle (chevron) como
-     * primeira coluna. Linhas com sub-rows ganham botão de expand/collapse.
-     *
-     * Retorna `undefined` para linhas-folha (sem children).
+     * Returns a row's sub-rows, enabling tree expansion (a chevron toggle
+     * column is injected). Return `undefined` for leaf rows.
      *
      * @example
      * ```tsx
-     * <DataTable<TreeNode>
-     *   data={tree}
-     *   columns={cols}
-     *   getSubRows={(row) => row.children}
-     * />
+     * <DataTable<TreeNode> data={tree} columns={cols} getSubRows={(row) => row.children} />
      * ```
-     *
-     * Modo apenas tree (sub-rows da mesma shape T). Detail panels custom
-     * sob row são gap separado — ver `vendors/TanstackReactTable/README.md`
-     * §"Candidatos ROADMAP".
      */
     getSubRows?: (row: T, index: number) => T[] | undefined;
     /**
-     * Largura da coluna de toggle de expand, em pixels. Default igual à
-     * `selectableColumnWidth` quando ambos coexistem; senão `48`.
+     * Width of the expand toggle column, in pixels. Defaults to
+     * `selectableColumnWidth` when both coexist; otherwise `48`.
      */
     expandedColumnWidth?: number;
     /**
-     * Estado inicial do expanded (uncontrolled). Default `{}` (todas as
-     * linhas colapsadas). Use `true` para expandir todas inicialmente.
+     * Initial expanded state (uncontrolled). Default `{}` (all rows
+     * collapsed). Use `true` to expand all initially.
      *
-     * Mutuamente exclusivo com `expanded` (controlled). Se ambos forem
-     * informados, controlado tem precedência.
+     * Mutually exclusive with `expanded` (controlled). If both are
+     * provided, controlled takes precedence.
      */
     initialExpanded?: ExpandedState;
-    /** Estado controlado do expanded. Requer `onExpandedChange`. */
+    /** Controlled expanded state. Requires `onExpandedChange`. */
     expanded?: ExpandedState;
-    /** Callback disparado quando o expand muda. Aceita o updater pattern do tanstack. */
+    /** Callback fired when the expansion changes. Accepts the tanstack updater pattern. */
     onExpandedChange?: OnChangeFn<ExpandedState>;
     /**
-     * Estado inicial dos filtros por coluna (uncontrolled). Default `[]`.
-     * Cada entry tem `{ id: <column id>, value: <filter value> }`.
+     * Initial per-column filters state (uncontrolled). Default `[]`.
+     * Each entry has `{ id: <column id>, value: <filter value> }`.
      *
-     * Mutuamente exclusivo com `columnFilters` (controlled). Se ambos
-     * forem informados, controlado tem precedência.
+     * Mutually exclusive with `columnFilters` (controlled). If both
+     * are provided, controlled takes precedence.
      */
     initialColumnFilters?: ColumnFiltersState;
-    /** Estado controlado dos filtros por coluna. Requer `onColumnFiltersChange`. */
+    /** Controlled per-column filters state. Requires `onColumnFiltersChange`. */
     columnFilters?: ColumnFiltersState;
-    /** Callback disparado quando algum filtro por coluna muda. */
+    /** Callback fired when any per-column filter changes. */
     onColumnFiltersChange?: OnChangeFn<ColumnFiltersState>;
+    /**
+     * Overrides for the UI strings of the pagination row and the filter
+     * popovers. Partial — omitted fields keep the pt-BR defaults. See
+     * {@link DataTableLabels}.
+     */
+    labels?: DataTableLabels;
 }
 export type RegularProps = React.ComponentPropsWithoutRef<'div'>;
 /**
- * Props do componente `DataTable`.
+ * Props of the `DataTable` component.
  *
- * Combina os campos específicos da tabela com as props nativas de um `<div>`
- * — então é possível passar `style`, `className`, `data-*`, etc., direto no
- * componente.
+ * Combines the table-specific fields with the native props of a `<div>`
+ * — so `style`, `className`, `data-*`, etc. can be passed straight to the
+ * component.
  */
 export type DataTableProps<T extends Record<string, unknown>> = ComponentProps<T> & RegularProps;
 /**
- * Props do input de busca global interno do `DataTable`.
+ * Props of the `DataTable`'s internal global search input.
  *
- * Exposto para que stories e testes possam montar o filtro isoladamente, mas
- * normalmente é controlado pelo próprio `DataTable`.
+ * Exposed so stories and tests can mount the filter in isolation, but
+ * it is normally controlled by `DataTable` itself.
  */
 export interface GlobalFilterProps {
     globalFilter: string;

package/lib/dataDisplay/DataTable/DataTable.props.d.ts

@@ -1,10 +1,10 @@
 /**
- * Configuração padrão de largura aplicada a colunas que não declaram
- * `width`/`minWidth`/`maxWidth` explícitos.
+ * Default width configuration applied to columns that declare no explicit
+ * `width`/`minWidth`/`maxWidth`.
  *
- * Exportada porque o adapter para `@tanstack/react-table` precisa repassar os
- * mesmos valores ao `defaultColumn` da biblioteca para manter consistência
- * entre o cabeçalho e o corpo virtualizado.
+ * Exported because the `@tanstack/react-table` adapter needs to forward the
+ * same values to the library's `defaultColumn` to keep the header and the
+ * virtualized body consistent.
  */
 export declare const defaultColumn: {
     minWidth: number;
@@ -12,13 +12,13 @@ export declare const defaultColumn: {
     maxWidth: number;
 };
 /**
- * Alturas de linha (em pixels) para os três modos de densidade suportados
- * pelo menu de espaçamento.
+ * Row heights (in pixels) for the three density modes supported by the
+ * spacing menu.
  *
- * O `useVirtualizer` de `@tanstack/react-virtual` recebe esse valor via
- * `estimateSize: () => rowHeight` — fixed-size hoje, variable-size opt-in
- * via `measureElement` quando o DataTable expor essa opção. Mudanças de
- * densidade redefinem este valor diretamente.
+ * The `@tanstack/react-virtual` `useVirtualizer` receives this value via
+ * `estimateSize: () => rowHeight` — fixed-size today, variable-size opt-in
+ * via `measureElement` once the DataTable exposes that option. Density
+ * changes redefine this value directly.
  */
 export declare enum RowHeight {
     compact = 32,