@apollion-dsi/core 3.0.0

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

@@ -0,0 +1,175 @@
+import React from 'react';
+import { Row } from '@tanstack/react-table';
+/**
+ * Códigos de cor pré-definidos para destacar linhas inteiras da tabela.
+ *
+ * Usado pelo callback {@link DataTableProps.setRowColor} para sinalizar status
+ * (sucesso, alerta, erro) sem precisar resolver paletas no call-site.
+ */
+export declare enum RowColor {
+    primary = "primary",
+    success = "success",
+    alert = "warning",
+    error = "danger"
+}
+/**
+ * Alinhamento horizontal do conteúdo de uma célula.
+ *
+ * Valores correspondem a `justify-content` do flexbox para que possam ser
+ * aplicados diretamente no estilo da célula sem mapeamento extra.
+ */
+export declare enum CellAlign {
+    left = "flex-start",
+    center = "center",
+    right = "flex-end"
+}
+/**
+ * Configuração de estilo aplicada a uma célula durante o render.
+ *
+ * Estrutura interna usada por `DataTable` para combinar dados da coluna
+ * (alinhamento, se é checkbox) com props pontuais (`cellProps`).
+ */
+export type CellStyle = {
+    align?: CellAlign;
+    header?: boolean;
+    hasCheckbox?: boolean;
+    selectable?: boolean;
+    cellProps?: React.ComponentPropsWithoutRef<'div'>;
+};
+/**
+ * Definição de uma coluna do `DataTable`.
+ *
+ * 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).
+ *
+ * @example
+ * ```tsx
+ * const columns: Column<User>[] = [
+ *   { Header: 'Nome', accessor: 'name' },
+ *   { Header: 'Idade', accessor: 'age', align: CellAlign.right },
+ * ];
+ * ```
+ */
+export type Column<T extends Record<string, unknown>> = {
+    /** Identificador único. Inferido de `accessor` quando omitido. */
+    id?: string;
+    /** Título do cabeçalho. Aceita string ou ReactNode (ex.: ícones + tooltips). */
+    Header: string | React.ReactNode;
+    /** Renderizador customizado da célula; recebe a linha e o valor extraído. */
+    Cell?: (props: {
+        row: Row<T>;
+        value: any;
+    }) => React.ReactNode;
+    /** Renderizador customizado do footer da coluna (somatórios, totalizadores). */
+    Footer?: (props: {
+        table: any;
+    }) => React.ReactNode;
+    /** Key de `T` cujo valor é exibido por padrão; `null` para colunas sem dado. */
+    accessor: keyof T | null;
+    /** Largura inicial em pixels. */
+    width?: number;
+    /** Largura mínima ao redimensionar. */
+    minWidth?: number;
+    /** Largura máxima ao redimensionar. */
+    maxWidth?: number;
+    /** Alinhamento horizontal do conteúdo. */
+    align?: CellAlign;
+    /** Quando `false`, cliques na célula não disparam seleção/onRowClick. */
+    selectable?: boolean;
+    /** Quando `true`, remove o cabeçalho clicável de ordenação. */
+    disableSortBy?: boolean;
+    /** Quando `true`, exclui a coluna do filtro global. */
+    disableFilters?: boolean;
+};
+/**
+ * Props específicas do `DataTable` (sem as props do elemento `<div>` que o
+ * envolve).
+ */
+interface ComponentProps<T extends Record<string, unknown>> {
+    /** Dataset a ser exibido. Deve ser memoizado (`useMemo`). */
+    data: T[];
+    /** Definição das colunas. Deve ser memoizada (`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).
+     */
+    selectableColumn?: string | boolean;
+    /** Largura da coluna de seleção, em pixels. */
+    selectableColumnWidth?: number;
+    /** Espaçamento vertical adicional somado à altura da linha. */
+    spacing?: number;
+    /**
+     * Altura do corpo virtualizado, em pixels.
+     *
+     * @default 400
+     */
+    height?: number;
+    /** Título exibido no header da tabela (requer `hasHeader`). */
+    title?: string;
+    /** Placeholder do input de busca global. */
+    searchPlaceholder?: string;
+    /** Callback disparado quando a seleção de linhas muda. */
+    onRowSelect?: (d: T[]) => void;
+    /** Callback disparado ao clicar em qualquer linha. */
+    onRowClick?: (row: T) => void;
+    /** Aplica fundo zebrado em linhas pares. */
+    striped?: boolean;
+    /** Adiciona bordas verticais entre células. */
+    bordered?: boolean;
+    /** Exibe o header (título + busca + slots laterais). */
+    hasHeader?: boolean;
+    /** Renderiza a linha de footer com somatórios definidos em `column.Footer`. */
+    hasFooter?: boolean;
+    /** Habilita o menu de densidade (compact/default/expansive). */
+    hasSpacingMenu?: boolean;
+    /** Slot à esquerda no header — após o título. */
+    headerLeftComponent?: React.ReactNode;
+    /** Slot à direita no header — após o input de busca. */
+    headerRightComponent?: React.ReactNode;
+    /**
+     * Substitui o `Input` de busca global por um componente custom (útil para
+     * integração com filtros server-side).
+     */
+    inputSearchComponent?: React.ReactNode;
+    /**
+     * Componente fixo ao final da lista (ex.: botão "carregar mais"). Recebe
+     * automaticamente `style` posicional do `react-window`.
+     */
+    lastRowComponent?: React.ReactNode;
+    /** Ícone exibido quando `data` está vazio. */
+    emptyIcon?: React.ReactNode;
+    /** Título do estado vazio. */
+    emptyTitle?: string;
+    /** Texto auxiliar do estado vazio. */
+    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).
+     */
+    setRowColor?: (row: Row<T>) => RowColor | undefined;
+}
+export type RegularProps = React.ComponentPropsWithoutRef<'div'>;
+/**
+ * Props do componente `DataTable`.
+ *
+ * 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.
+ */
+export type DataTableProps<T extends Record<string, unknown>> = ComponentProps<T> & RegularProps;
+/**
+ * Props do input de busca global interno do `DataTable`.
+ *
+ * Exposto para que stories e testes possam montar o filtro isoladamente, mas
+ * normalmente é controlado pelo próprio `DataTable`.
+ */
+export interface GlobalFilterProps {
+    globalFilter: string;
+    setGlobalFilter: (filterValue: string) => void;
+    placeholder?: string;
+}
+export {};

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

@@ -0,0 +1,25 @@
+/**
+ * Configuração padrão de largura aplicada a colunas que não declaram
+ * `width`/`minWidth`/`maxWidth` explícitos.
+ *
+ * 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.
+ */
+export declare const defaultColumn: {
+    minWidth: number;
+    width: number;
+    maxWidth: number;
+};
+/**
+ * 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.
+ */
+export declare enum RowHeight {
+    compact = 32,
+    default = 48,
+    expansive = 64
+}