@nextelco/common-ui 2.1.96 → 2.1.97

package/dist/types/components/molecules/DataTable/DataTable.d.ts

@@ -19,13 +19,16 @@ export interface DataTableColumn<T> {
     width?: number;
     /** Largura máxima em px (o conteúdo corta com "…" e mostra o valor completo no tooltip). Sobrepõe-se a `defaultMaxColumnWidth`. */
     maxWidth?: number;
-    /** Mostra um filtro por coluna com o distinct dos valores (multi-seleção). */
+    /**
+     * Filtro por coluna (distinct dos valores, multi-seleção; intervalo nas colunas number/date).
+     * Por omissão LIGADO em todas as colunas com dados — `false` desliga. Colunas sem dados (ex.: ações) não o mostram.
+     */
     filterable?: boolean;
     /** Desliga a ordenação nesta coluna (default: ordenável). */
     sortable?: boolean;
     /**
-     * Agrupar por esta coluna é opt-in. Evita oferecer agrupamento em colunas de valor
-     * contínuo (datas, floats, €), onde cada linha daria o seu próprio grupo.
+     * Agrupar por esta coluna. Por omissão LIGADO nas colunas de texto com dados e DESLIGADO nas de valor contínuo
+     * (`sortType` number/date, ou com `groupAggregate`), onde cada linha daria o seu próprio grupo. `true`/`false` forçam.
      */
     groupable?: boolean;
     /** Chave usada só para ORDENAR os grupos (sobrepõe-se a `value` ao agrupar por esta coluna). */
@@ -43,6 +46,11 @@ export interface DataTableColumn<T> {
     cellClassName?: string;
     /** Conteúdo extra por baixo do título da coluna (ex: somatório). Recebe as linhas já filtradas. */
     headerExtra?: (rows: T[]) => React.ReactNode;
+    /**
+     * Valor desta coluna na linha de cada grupo (ex: soma em €), alinhado com a coluna. Recebe as linhas do grupo
+     * (já filtradas). Também é usado na linha de total (`totalRow`), com todas as linhas filtradas.
+     */
+    groupAggregate?: (rows: T[]) => React.ReactNode;
     /**
      * Cores por valor para os chips de filtro ativo (valor → classes tailwind). Com isto, cada
      * valor escolhido ganha o seu chip, removível à parte.
@@ -125,6 +133,8 @@ export interface DataTableLabels {
     selectAll: string;
     /** O mesmo, com pesquisa activa — aí só abrange os valores que correspondem. */
     selectAllResults: string;
+    /** Rótulo da linha de total (`totalRow`). */
+    total: string;
 }
 interface DataTableProps<T> {
     columns: DataTableColumn<T>[];
@@ -183,16 +193,16 @@ interface DataTableProps<T> {
     /** Colunas redimensionáveis arrastando o limite do cabeçalho; duplo clique repõe (default true). */
     resizableColumns?: boolean;
     /**
-     * Acrescenta "Ordenar A→Z / Z→A" ao topo do popup de filtro. Opt-in: quem já usava a
-     * tabela não passa `labels` para isto e via aparecer dois botões em inglês.
+     * "Ordenar A→Z / Z→A" no topo do popup de filtro. Ligado por omissão (o cabeçalho é o mesmo em todos os
+     * portais); `false` desliga. Os textos vêm de `labels.sortAsc`/`sortDesc` (por omissão em inglês).
      */
     sortFromFilter?: boolean;
     /**
      * Semântica do filtro por coluna.
      *
-     * - `'simple'` (default): abre com tudo **desmarcado** e marcar um valor quer dizer "só este".
+     * - `'simple'`: abre com tudo **desmarcado** e marcar um valor quer dizer "só este".
      *   Conjunto vazio = sem filtro.
-     * - `'excel'`: abre com tudo **marcado** e desmarca-se o que se quer excluir, com uma linha
+     * - `'excel'` (default): abre com tudo **marcado** e desmarca-se o que se quer excluir, com uma linha
      *   `(Selecionar tudo)` no topo e curingas (`*`, `?`, `~`) na pesquisa. É o que a folha de
      *   cálculo faz, e o que quem vem de lá espera. Conjunto vazio = **nada seleccionado**, e a
      *   tabela fica sem linhas.
@@ -218,6 +228,10 @@ interface DataTableProps<T> {
     /** Ilustração do estado vazio. */
     emptyIcon?: React.ReactNode;
     labels?: Partial<DataTableLabels>;
+    /** Linha de total no fim (fica fixa em baixo), com o `groupAggregate` de cada coluna sobre as linhas filtradas. */
+    totalRow?: boolean;
+    /** Agrupamento inicial (chaves de colunas, por ordem de nível). A pessoa pode mudá-lo depois. */
+    defaultGroupBy?: string[];
 }
 /**
  * Timestamp de um valor de coluna de data. As apps passam a data já formatada (`value:
@@ -250,5 +264,5 @@ export declare function pesquisaCuringa(q: string): (v: string) => boolean;
  * Com paginação de servidor, passa também `allData`/`onDataNeeded`: sem o dataset completo,
  * filtrar, ordenar e agrupar só olhariam para a página à vista.
  */
-export default function DataTable<T>({ columns, data, allData, onDataNeeded, isAllDataLoading, alwaysClient, onClientModeChange, rowKey, onRowClick, onRowDoubleClick, rowClassName, isLoading, isError, maxHeight, pageSize, pageSizeOptions, selectable, onSelectionChange, clearSelectionTrigger, storageKey, defaultMaxColumnWidth, resizableColumns, sortFromFilter, filterMode, defaultSortKey, defaultSortDir, viewRef, exportFileName, onExport, extraToolbar, emptySubLabel, emptyIcon, labels, }: DataTableProps<T>): React.JSX.Element;
+export default function DataTable<T>({ columns, data, allData, onDataNeeded, isAllDataLoading, alwaysClient, onClientModeChange, rowKey, onRowClick, onRowDoubleClick, rowClassName, isLoading, isError, maxHeight, pageSize, pageSizeOptions, selectable, onSelectionChange, clearSelectionTrigger, storageKey, defaultMaxColumnWidth, resizableColumns, sortFromFilter, filterMode, defaultSortKey, defaultSortDir, viewRef, exportFileName, onExport, extraToolbar, emptySubLabel, emptyIcon, labels, totalRow, defaultGroupBy, }: DataTableProps<T>): React.JSX.Element;
 export {};

package/dist/types/components/ui/CaixaPesquisa.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+export interface CaixaPesquisaProps {
+    valor: string;
+    onMudar: (valor: string) => void;
+    placeholder?: string;
+    /** Nome acessível (leitores de ecrã). Por omissão, o placeholder. */
+    rotulo?: string;
+    /** Largura (classes tailwind). Por omissão w-56. */
+    className?: string;
+    autoFocus?: boolean;
+}
+/**
+ * Caixa de pesquisa das barras de tabela e listas: mesma altura (h-8) e cantos (rounded-lg) dos botões, do
+ * Exportar e do seletor de colunas. Lupa à esquerda; com texto, um "×" para limpar (Esc também limpa).
+ */
+export default function CaixaPesquisa({ valor, onMudar, placeholder, rotulo, className, autoFocus }: CaixaPesquisaProps): React.JSX.Element;

package/dist/types/components/ui/CaixaPesquisa.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/components/ui/Escolha.d.ts

@@ -0,0 +1,33 @@
+import React from 'react';
+export interface OpcaoEscolha {
+    valor: string;
+    rotulo: string;
+    /** Texto pequeno por baixo do rótulo, na lista. */
+    descricao?: string;
+}
+export interface EscolhaProps {
+    valor: string;
+    /** Opções: texto simples (valor = rótulo) ou { valor, rotulo, descricao }. */
+    opcoes: readonly string[] | readonly OpcaoEscolha[];
+    onMudar: (valor: string) => void;
+    /** Nome acessível (leitores de ecrã). */
+    rotulo: string;
+    /** Texto do botão sem nada escolhido. */
+    placeholder?: string;
+    /**
+     * Primeira opção "vazia" (valor ''), para desfazer a escolha (ex.: "Todas"). Sem isto não há como voltar atrás
+     * depois de escolher.
+     */
+    opcaoVazia?: string;
+    disabled?: boolean;
+    /** Caixa de pesquisa no topo da lista. Por omissão, só com mais de 10 opções. */
+    pesquisa?: boolean;
+    /** Largura (classes tailwind). Por omissão a do conteúdo, entre 10rem e 18rem. */
+    className?: string;
+}
+/**
+ * Lista suspensa para escolher um valor (substitui o `<select>` nativo, que abre com o aspeto do sistema e não
+ * segue o tema). Mesma altura e cantos dos botões e campos (h-8, rounded-lg); a lista tem o mesmo aspeto do
+ * MenuAcoes. Teclado: ↑/↓, Home/End, Enter escolhe, Esc fecha; ao escrever com a lista aberta salta para a opção.
+ */
+export default function Escolha({ valor, opcoes, onMudar, rotulo, placeholder, opcaoVazia, disabled, pesquisa, className, }: EscolhaProps): React.JSX.Element;

package/dist/types/components/ui/Escolha.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/components/ui/MenuAcoes.d.ts

@@ -0,0 +1,31 @@
+import React, { type ReactNode } from 'react';
+export interface AcaoMenu {
+    rotulo: ReactNode;
+    onClick: () => void;
+    /** Ícone à esquerda (ex.: um ícone do lucide-react com className="h-4 w-4"). */
+    icone?: ReactNode;
+    /** Ação destrutiva (eliminar, fechar…): a vermelho. */
+    perigo?: boolean;
+    desativado?: boolean;
+    /** Linha separadora antes deste item. */
+    separador?: boolean;
+}
+export interface MenuAcoesProps {
+    /** Itens; `false`/`null`/`undefined` são ignorados (para `cond && {...}`). */
+    acoes: (AcaoMenu | false | null | undefined)[];
+    /**
+     * Conteúdo do botão. Sem rótulo, o botão é o ícone "⋯" (ações de uma linha de tabela).
+     * Com rótulo, é um botão como o Btn, com uma seta.
+     */
+    rotulo?: ReactNode;
+    /** Nome acessível / tooltip do botão. */
+    titulo?: string;
+    /** Lado para onde a lista abre, a partir do botão. Por omissão, alinhada à direita do botão. */
+    alinhar?: 'esquerda' | 'direita';
+    disabled?: boolean;
+}
+/**
+ * Botão que abre uma lista de ações (ex.: "Ações do ano", o "⋯" de cada linha). Mesmo aspeto da lista da
+ * Escolha. Teclado: ↑/↓ percorrem, Enter executa, Esc fecha. Os cliques não chegam à linha da tabela.
+ */
+export default function MenuAcoes({ acoes, rotulo, titulo, alinhar, disabled }: MenuAcoesProps): React.JSX.Element | null;

package/dist/types/components/ui/painelFlutuante.d.ts

@@ -0,0 +1,20 @@
+import { type CSSProperties } from 'react';
+/**
+ * Aspeto comum das listas suspensas (Escolha e MenuAcoes): cartão arredondado com sombra, nos dois temas.
+ * Um só sítio para as duas ficarem iguais.
+ */
+export declare const CLS_PAINEL = "fixed z-[60] min-w-[10rem] max-h-72 overflow-auto rounded-xl border border-slate-200 bg-white py-1 text-sm shadow-lg dark:border-slate-700 dark:bg-slate-900";
+/** Item de uma lista suspensa; `ativo` = o que o teclado tem selecionado. */
+export declare const clsItem: (ativo: boolean, perigo?: boolean) => string;
+/**
+ * Painel flutuante preso a um botão: posição fixa (não é cortado por tabelas ou modais com scroll), abre para
+ * cima quando não cabe por baixo, fecha ao clicar fora, com Esc, ao fazer scroll fora dele ou ao redimensionar.
+ */
+export declare function usePainelFlutuante(alinhar?: 'esquerda' | 'direita'): {
+    aberto: boolean;
+    setAberto: import("react").Dispatch<import("react").SetStateAction<boolean>>;
+    fechar: () => void;
+    refBotao: import("react").RefObject<HTMLButtonElement | null>;
+    refPainel: import("react").RefObject<HTMLDivElement | null>;
+    estilo: CSSProperties;
+};

package/dist/types/exports/ui.d.ts

@@ -10,6 +10,12 @@ export { default as BarraAcoes } from '../components/ui/BarraAcoes';
 export type { BarraAcoesProps } from '../components/ui/BarraAcoes';
 export { default as FaixaAviso } from '../components/ui/FaixaAviso';
 export type { FaixaAvisoProps, TomFaixa } from '../components/ui/FaixaAviso';
+export { default as Escolha } from '../components/ui/Escolha';
+export type { EscolhaProps, OpcaoEscolha } from '../components/ui/Escolha';
+export { default as MenuAcoes } from '../components/ui/MenuAcoes';
+export type { MenuAcoesProps, AcaoMenu } from '../components/ui/MenuAcoes';
+export { default as CaixaPesquisa } from '../components/ui/CaixaPesquisa';
+export type { CaixaPesquisaProps } from '../components/ui/CaixaPesquisa';
 export { default as TextoAuto } from '../components/ui/TextoAuto';
 export type { TextoAutoProps } from '../components/ui/TextoAuto';
 export { default as Confirmacao } from '../components/ui/Confirmacao';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextelco/common-ui",
-  "version": "2.1.96",
+  "version": "2.1.97",
   "description": "",
   "main": "dist/bundle.js",
   "types": "dist/types/index.d.ts",