@apollion-dsi/core 3.0.0 → 4.0.0

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

@@ -1,11 +1,11 @@
 import React from 'react';
 import { DataTableProps, GlobalFilterProps } from './DataTable.interface';
 import { icons } from '../../icons';
+import type { OnChangeFn } from '../../vendors/TanstackReactTable';
 /**
- * Wrapper de scroll customizado usado como `outerElementType` do
- * `FixedSizeList`. Remove a largura fixa para deixar o conteúdo cuidar do
- * tamanho horizontal — a virtualização do `react-window` injeta esse valor
- * que conflitaria com o cabeçalho da tabela.
+ * Wrapper de scroll customizado usado como container do
+ * `useVirtualizer` (via `parentRef`). Remove a largura inline para que o
+ * cabeçalho da tabela controle a largura horizontal sem conflito.
  */
 export declare const VitualScrollbar: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
 /**
@@ -21,6 +21,33 @@ export declare const ResizeHandle: React.ForwardRefExoticComponent<Omit<React.De
  * quando a coluna não está ordenada.
  */
 export declare const getSortIcon: (sortState: "asc" | "desc" | false) => keyof typeof icons;
+/**
+ * Constrói a definição da coluna de toggle de expand (tree mode) para o
+ * `@tanstack/react-table`.
+ *
+ * Mirror do `buildSelectableColumnDef` pattern. Cell renderiza chevron-down
+ * quando expandida, chevron-right quando colapsada, ou `null` quando
+ * `row.getCanExpand()` é falso (linha-folha, sem sub-rows).
+ *
+ * O `marginLeft: row.depth * 16` indenta o chevron conforme profundidade
+ * — sub-rows ficam visualmente alinhadas ao parent sem mexer no alinhamento
+ * das colunas de dados (que mantêm posição fixa).
+ *
+ * Retorna `null` quando `enabled` é falso, permitindo spread condicional
+ * no `tanstackColumns` memo do DataTable.
+ */
+export declare function buildExpandColumnDef<T extends Record<string, unknown>>(enabled: boolean, width?: number): {
+    id: string;
+    size: number;
+    enableSorting: boolean;
+    enableResizing: boolean;
+    header: () => null;
+    cell: ({ row }: any) => React.JSX.Element;
+    meta: {
+        selectable: false;
+        align: undefined;
+    };
+};
 /**
  * Constrói a definição de coluna do checkbox de seleção para o
  * `@tanstack/react-table`.
@@ -55,3 +82,54 @@ export declare const GlobalFilter: ({ globalFilter, setGlobalFilter, placeholder
  * defaults atendem ao caso geral de "nada foi encontrado".
  */
 export declare const EmptyTable: ({ height, emptyIcon, emptyTitle, emptyDescription, }: Partial<DataTableProps<any>>) => React.JSX.Element;
+/**
+ * Unifica controlled e uncontrolled state em uma única abstração — `[value,
+ * setValue]` no callsite, sem branching.
+ *
+ * - **Controlled mode:** `controlled !== undefined`. `value` é `controlled`,
+ *   updates disparam `onControlledChange` (não tocam o state interno).
+ * - **Uncontrolled mode:** `controlled === undefined`. `value` vem do useState
+ *   interno, updates chamam `setUncontrolled`. `onControlledChange` (se
+ *   fornecido em modo uncontrolled) ainda é chamado para observação.
+ *
+ * Decisão controlled/uncontrolled é fixada na primeira render — alternar em
+ * renders subsequentes é anti-pattern e o helper não cobre esse caso (mesma
+ * restrição que React impõe sobre inputs controlados/não-controlados).
+ *
+ * @param controlled         Estado controlado (ou `undefined` para uncontrolled).
+ * @param onControlledChange Callback do estado controlado.
+ * @param initial            Valor inicial ou factory.
+ * @returns `[value, setValue]` análogo a `useState`, mas com setValue aceitando
+ *          updater function (compat com tanstack `OnChangeFn`).
+ */
+export declare function useHybridState<T>(controlled: T | undefined, onControlledChange: OnChangeFn<T> | undefined, initial: T | (() => T)): [T, (updater: T | ((prev: T) => T)) => void];
+type PaginationControlsProps = {
+    pageIndex: number;
+    pageSize: number;
+    pageCount: number;
+    rowCount: number;
+    canPreviousPage: boolean;
+    canNextPage: boolean;
+    pageSizeOptions: number[];
+    onPrevious: () => void;
+    onNext: () => void;
+    onPageSizeChange: (size: number) => void;
+};
+/**
+ * Linha de navegação de paginação do `DataTable`.
+ *
+ * Renderiza, da esquerda pra direita:
+ * - Texto "Mostrando X-Y de Z" (range visível na página atual).
+ * - Seletor de page size (`Dropdown`) — só aparece quando
+ *   `pageSizeOptions.length > 1`.
+ * - Botão `Anterior` (linked) + indicador `pageIndex+1 / pageCount` + botão
+ *   `Próximo` (linked).
+ *
+ * Estado é totalmente derivado das props — o componente é puro. O wiring
+ * do tanstack-react-table vive em `DataTable.tsx`.
+ *
+ * Strings hardcoded em PT-BR — Apollion não tem i18n layer hoje (consistente
+ * com `EmptyTable` que usa `"Nada foi encontrado"` default).
+ */
+export declare const PaginationControls: ({ pageIndex, pageSize, pageCount, rowCount, canPreviousPage, canNextPage, pageSizeOptions, onPrevious, onNext, onPageSizeChange, }: PaginationControlsProps) => React.JSX.Element;
+export {};

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

@@ -1,5 +1,5 @@
 import React from 'react';
-import { Row } from '@tanstack/react-table';
+import type { ColumnFiltersState, ExpandedState, FilterFn, OnChangeFn, PaginationState, Row } from '../../vendors/TanstackReactTable';
 /**
  * Códigos de cor pré-definidos para destacar linhas inteiras da tabela.
  *
@@ -80,8 +80,54 @@ export type Column<T extends Record<string, unknown>> = {
     selectable?: boolean;
     /** Quando `true`, remove o cabeçalho clicável de ordenação. */
     disableSortBy?: boolean;
-    /** Quando `true`, exclui a coluna do filtro global. */
+    /**
+     * Quando `true`, desliga o filtro por coluna desta coluna:
+     *
+     * - 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`).
+     *
+     * Ativado a partir do ROADMAP §🟡 "DataTable absorption gaps · Faceted
+     * filters" — em ciclos anteriores essa prop era no-op declarada.
+     *
+     * @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:
+     *
+     * - `'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.
+     *
+     * 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.
+     *
+     * @default undefined (sem 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
+     * `(row, columnId, filterValue, addMeta?) => boolean`.
+     *
+     * @example
+     * ```ts
+     * { Header: 'Tags', accessor: 'tags', filterVariant: 'select',
+     *   filterFn: (row, colId, vals: string[]) =>
+     *     (row.getValue(colId) as string[]).some(t => vals.includes(t))
+     * }
+     * ```
+     */
+    filterFn?: FilterFn<Record<string, unknown>> | string;
 };
 /**
  * Props específicas do `DataTable` (sem as props do elemento `<div>` que o
@@ -135,8 +181,10 @@ interface ComponentProps<T extends Record<string, unknown>> {
      */
     inputSearchComponent?: React.ReactNode;
     /**
-     * Componente fixo ao final da lista (ex.: botão "carregar mais"). Recebe
-     * automaticamente `style` posicional do `react-window`.
+     * 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`).
      */
     lastRowComponent?: React.ReactNode;
     /** Ícone exibido quando `data` está vazio. */
@@ -151,6 +199,91 @@ interface ComponentProps<T extends Record<string, unknown>> {
      * padrão (incluindo zebrado).
      */
     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.
+     *
+     * Default `false` — comportamento de scroll virtualizado infinito
+     * preservado.
+     *
+     * @default false
+     */
+    paginated?: boolean;
+    /**
+     * Estado inicial da paginação (uncontrolled). Default `{ pageIndex: 0,
+     * pageSize: pageSizeOptions[0] ?? 10 }`.
+     *
+     * Mutuamente exclusivo com `pagination` (controlled). Se ambos forem
+     * informados, o estado controlado tem precedência.
+     */
+    initialPagination?: Partial<PaginationState>;
+    /**
+     * Estado controlado da paginação. Quando informado, `onPaginationChange`
+     * deve atualizar este valor no callsite.
+     */
+    pagination?: PaginationState;
+    /** Callback disparado quando a paginação muda. Aceita o updater pattern do tanstack. */
+    onPaginationChange?: OnChangeFn<PaginationState>;
+    /**
+     * Opções de page size disponíveis no seletor. Default `[10, 25, 50, 100]`.
+     *
+     * Quando o array tem ≤ 1 entradas, o seletor de page size é escondido
+     * (consumer trava o 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).
+     *
+     * @example
+     * ```tsx
+     * <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`.
+     */
+    expandedColumnWidth?: number;
+    /**
+     * Estado inicial do expanded (uncontrolled). Default `{}` (todas as
+     * linhas colapsadas). Use `true` para expandir todas inicialmente.
+     *
+     * Mutuamente exclusivo com `expanded` (controlled). Se ambos forem
+     * informados, controlado tem precedência.
+     */
+    initialExpanded?: ExpandedState;
+    /** Estado controlado do expanded. Requer `onExpandedChange`. */
+    expanded?: ExpandedState;
+    /** Callback disparado quando o expand muda. Aceita o updater pattern do tanstack. */
+    onExpandedChange?: OnChangeFn<ExpandedState>;
+    /**
+     * Estado inicial dos filtros por coluna (uncontrolled). Default `[]`.
+     * Cada entry tem `{ id: <column id>, value: <filter value> }`.
+     *
+     * Mutuamente exclusivo com `columnFilters` (controlled). Se ambos
+     * forem informados, controlado tem precedência.
+     */
+    initialColumnFilters?: ColumnFiltersState;
+    /** Estado controlado dos filtros por coluna. Requer `onColumnFiltersChange`. */
+    columnFilters?: ColumnFiltersState;
+    /** Callback disparado quando algum filtro por coluna muda. */
+    onColumnFiltersChange?: OnChangeFn<ColumnFiltersState>;
 }
 export type RegularProps = React.ComponentPropsWithoutRef<'div'>;
 /**

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

@@ -15,8 +15,10 @@ export declare const defaultColumn: {
  * Alturas de linha (em pixels) para os três modos de densidade suportados
  * pelo menu de espaçamento.
  *
- * Como o `react-window` exige altura fixa por linha, mudanças de densidade
- * redefinem este valor diretamente — não há padding flexível.
+ * 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.
  */
 export declare enum RowHeight {
     compact = 32,