@1doc/1ds-react 2.8.0 → 2.9.0

package/dist/components/ColorPicker/ColorPicker.css

@@ -0,0 +1,133 @@
+/* ─────────────────────────────────────────────
+   COLOR PICKER
+   Grade de amostras da paleta do 1DS (primitivos de cor). Valor = nome do token.
+
+   Na paleta do DS a grade tem 7 colunas (os cinzas são 7) e a PRIMEIRA amostra
+   de cada família abre linha nova: uma linha por família, sem aninhar nada no
+   DOM — a ordem de Tab e das setas continua a da lista.
+
+   A amostra escolhida tem dois sinais além da cor: anel duplo e ícone de
+   marcação. O ícone usa primitivos (branco ou cinza escuro), porque a cor da
+   amostra é primitiva e não muda com o tema: o contraste fica o mesmo no escuro.
+
+   Cores: semânticos (e primitivos, na marcação) · Medidas: primitivos
+───────────────────────────────────────────── */
+
+.umds-color-picker {
+  display: inline-flex;
+  flex-direction: column;
+  gap: var(--umds-primitive-spacing-nano); /* 8px */
+  font-family: var(--umds-semantic-font-family-base);
+}
+
+.umds-color-picker__label {
+  font-size: var(--umds-semantic-field-label-size);
+  font-weight: var(--umds-semantic-field-label-weight);
+  color: var(--umds-semantic-field-label-color);
+}
+
+/* ── Grade ── */
+.umds-color-picker__swatches {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--umds-primitive-spacing-nano); /* 8px */
+  /* Folga para o anel de seleção (4px) não ser cortado por um overflow do pai. */
+  padding: var(--umds-primitive-spacing-quarck);
+}
+
+.umds-color-picker--sm .umds-color-picker__swatches {
+  gap: var(--umds-primitive-spacing-quarck); /* 4px */
+}
+
+.umds-color-picker__swatches--familias {
+  display: grid;
+  grid-template-columns: repeat(7, max-content);
+}
+
+.umds-color-picker__swatch--nova-linha {
+  grid-column-start: 1;
+}
+
+/* ── Amostra ── */
+.umds-color-picker__swatch {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+  cursor: pointer;
+  /* Anel de 1px: amostra clara não some no fundo branco. */
+  border: var(--umds-primitive-border-width-hairline) solid var(--umds-semantic-color-neutral-light-down);
+  border-radius: var(--umds-primitive-border-radius-sm);
+  /* A cor da amostra vem do `style` (background-color); o ícone herda o branco. */
+  /* stylelint-disable-next-line 1ds/cor-por-token -- a amostra é primitivo (não muda com o tema); a marcação precisa do par fixo, senão o semântico inverte no escuro e perde o contraste */
+  color: var(--umds-primitive-white);
+  transition: box-shadow var(--umds-semantic-motion-duration-fast) var(--umds-semantic-motion-easing-standard);
+}
+
+.umds-color-picker--md .umds-color-picker__swatch {
+  width: var(--umds-primitive-spacing-xs); /* 32px */
+  height: var(--umds-primitive-spacing-xs);
+}
+
+.umds-color-picker--sm .umds-color-picker__swatch {
+  width: var(--umds-primitive-spacing-xxs); /* 24px */
+  height: var(--umds-primitive-spacing-xxs);
+}
+
+.umds-color-picker__swatch--on-light {
+  /* stylelint-disable-next-line 1ds/cor-por-token -- par fixo da marcação sobre amostra clara (ver acima) */
+  color: var(--umds-primitive-gray-darkest);
+}
+
+.umds-color-picker__swatch:hover:not(:disabled) {
+  box-shadow: 0 0 0 var(--umds-primitive-border-width-thin) var(--umds-semantic-color-neutral-light-down);
+}
+
+.umds-color-picker__swatch--selected,
+.umds-color-picker__swatch--selected:hover:not(:disabled) {
+  /* Anel duplo: a cor do fundo da página por dentro e o primário por fora. */
+  box-shadow:
+    0 0 0 var(--umds-primitive-border-width-thin) var(--umds-semantic-color-background-white),
+    0 0 0 calc(var(--umds-primitive-border-width-thin) * 2) var(--umds-semantic-color-primary-pure);
+}
+
+.umds-color-picker__swatch:focus-visible {
+  outline: var(--umds-primitive-border-width-thin) solid var(--umds-semantic-color-primary-pure);
+  outline-offset: var(--umds-primitive-spacing-quarck);
+}
+
+.umds-color-picker__swatch:disabled {
+  cursor: not-allowed;
+  opacity: var(--umds-semantic-field-disabled-opacity);
+}
+
+/* ── Cor livre ── */
+.umds-color-picker__custom {
+  display: flex;
+  align-items: flex-end;
+  gap: var(--umds-primitive-spacing-nano); /* 8px */
+}
+
+.umds-color-picker__custom-preview {
+  flex: none;
+  box-sizing: border-box;
+  width: var(--umds-primitive-spacing-xs); /* 32px, a altura do Input sm */
+  height: var(--umds-primitive-spacing-xs);
+  border: var(--umds-primitive-border-width-hairline) solid var(--umds-semantic-color-neutral-light-down);
+  border-radius: var(--umds-primitive-border-radius-sm);
+}
+
+/* ── Alto contraste: a marcação e a borda ficam, a cor é do usuário ── */
+@media (forced-colors: active) {
+  .umds-color-picker__swatch {
+    forced-color-adjust: none;
+    border-color: CanvasText;
+  }
+
+  .umds-color-picker__swatch--selected {
+    outline: var(--umds-primitive-border-width-thin) solid Highlight;
+    outline-offset: var(--umds-primitive-border-width-thin);
+  }
+}

package/dist/components/ColorPicker/ColorPicker.d.ts

@@ -0,0 +1,73 @@
+import './ColorPicker.css';
+/**
+ * Amostra do ColorPicker.
+ * @property {string} value - Nome da variável CSS (`--umds-primitive-blue-pure`) ou uma cor hexadecimal (`#0058DB`).
+ * @property {string} label - Nome da cor, para leitor de tela e tooltip.
+ * @property {boolean} onLight - Cor clara: o ícone de marcação sai escuro.
+ * @property {boolean} disabled - Desabilita só esta amostra.
+ */
+export interface ColorPickerSwatch {
+    value: string;
+    label: string;
+    onLight?: boolean;
+    disabled?: boolean;
+    [key: string]: any;
+}
+/**
+ * ColorPicker — escolha de UMA cor numa grade de amostras da paleta do 1DS.
+ *
+ * O valor é o NOME DO TOKEN (`--umds-primitive-blue-pure`), não o hexadecimal:
+ * guarde o nome e escreva `var(${valor})` onde pintar, e a cor acompanha a
+ * paleta do DS. As amostras são os primitivos de cor (6 famílias de 4 tons e
+ * os 7 cinzas), por isso a cor escolhida é a mesma no tema claro e no escuro,
+ * o que é o certo para cor de dado (marcador, tipo de documento, setor).
+ *
+ * É um `radiogroup`: um Tab entra na grade (na amostra escolhida, ou na
+ * primeira) e as setas movem a escolha, com Home e End nas pontas. Cada amostra
+ * tem nome acessível ("Azul escuro") e a escolhida ganha um ícone de marcação,
+ * então a seleção nunca depende só da cor.
+ *
+ * `allowCustom` liga o campo de cor livre (hexadecimal `#RRGGBB`). Vem
+ * DESLIGADO: cor fora da paleta foge do DS, e quem liga assume o desvio. O
+ * valor livre sai em maiúsculas (`#0058DB`) e se distingue do token por começar
+ * com `#`.
+ *
+ * Para um recorte da paleta (só azul e cinza) ou para traduzir os nomes, passe
+ * `swatches`; `COLOR_PALETTE` é a lista padrão, exportada para filtrar.
+ * @property {string} value - Valor escolhido (controlado): nome do token ou `#RRGGBB`
+ * @property {string} defaultValue - Valor inicial (não controlado)
+ * @property {string} label - Rótulo visível do grupo
+ * @property {string} ariaLabel - Nome acessível quando não há `label` visível
+ * @property {string} ariaLabelledby - Id do texto que nomeia o grupo
+ * @property {ColorPickerSwatch[]} swatches - Amostras no lugar da paleta do DS (ex.: nomes traduzidos)
+ * @property {string[]} families - Mostra só estas famílias da paleta do DS: 'blue' | 'red' | 'green' | 'orange' | 'yellow' | 'purple' | 'gray'
+ * @property {boolean} allowCustom - Liga o campo de cor livre (hexadecimal)
+ * @property {string} customLabel - Rótulo do campo de cor livre (padrão: "Cor livre (hexadecimal)")
+ * @property {string} customErrorMessage - Mensagem do hexadecimal inválido (padrão: "Use o formato #RRGGBB")
+ * @property {string} size - Tamanho da amostra: 'sm' (24px) | 'md' (32px)
+ * @property {boolean} disabled - Desabilita o grupo inteiro
+ * @property {string} id - Base dos ids internos; passe em SSR para os ids já saírem no HTML do servidor
+ * @property {string} className - Classes CSS adicionais
+ * @property {function} onChange - Callback com o valor escolhido (nome do token ou `#RRGGBB`)
+ * @quandoUsar Escolher a cor de um marcador, de um tipo de documento, de um setor ou de uma série de dados, sempre dentro da paleta do DS.
+ * @quandoNaoUsar Para cor com PAPEL na interface (primária, erro, sucesso), use os tokens semânticos direto: não é escolha do usuário. Para escolher entre poucas opções que não são cor, use `SegmentedControl` ou `RadioGroup`. Para uma cor qualquer da web, ligue `allowCustom` sabendo que ela sai do DS.
+ */
+export interface ColorPickerProps {
+    value?: string;
+    defaultValue?: string;
+    label?: string;
+    ariaLabel?: string;
+    ariaLabelledby?: string;
+    swatches?: ColorPickerSwatch[];
+    families?: string[];
+    allowCustom?: boolean;
+    customLabel?: string;
+    customErrorMessage?: string;
+    size?: "sm" | "md";
+    disabled?: boolean;
+    id?: string;
+    className?: string;
+    onChange?: (value: string) => void;
+}
+declare function ColorPicker(props: ColorPickerProps): import("react/jsx-runtime").JSX.Element;
+export default ColorPicker;

package/dist/components/ColorPicker/ColorPicker.js

@@ -0,0 +1,219 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import './ColorPicker.css';
+import { useState, useRef, useEffect } from "react";
+import { faCheck } from "@fortawesome/free-solid-svg-icons";
+import Icon from "../Icon/Icon";
+import Input from "../Input/Input";
+import { gerarId } from "../../utils/id";
+import { COLOR_PALETTE, isHexColor } from "../../utils/paleta-de-cores";
+function ColorPicker(props) {
+    const groupRef = useRef(null);
+    const [internalValue, setInternalValue] = useState(() => props.defaultValue !== undefined ? props.defaultValue : "");
+    const [uid, setUid] = useState(() => "");
+    const [hexDraft, setHexDraft] = useState(() => "");
+    const [hexEditing, setHexEditing] = useState(() => false);
+    const [hexTouched, setHexTouched] = useState(() => false);
+    function baseId() {
+        return props.id || uid;
+    }
+    function labelId() {
+        return baseId() && props.label ? baseId() + "-label" : undefined;
+    }
+    function currentValue() {
+        return props.value !== undefined ? props.value : internalValue;
+    }
+    function swatchList() {
+        if (props.swatches && props.swatches.length)
+            return props.swatches;
+        const familias = props.families;
+        if (!familias || !familias.length)
+            return COLOR_PALETTE;
+        return COLOR_PALETTE.filter((cor) => familias.indexOf(cor.family) !== -1);
+    }
+    function usaPaletaDoDs() {
+        return !(props.swatches && props.swatches.length);
+    }
+    function groupClasses() {
+        return [
+            "umds-color-picker",
+            `umds-color-picker--${props.size || "md"}`,
+            props.disabled ? "umds-color-picker--disabled" : "",
+            props.className,
+        ]
+            .filter(Boolean)
+            .join(" ");
+    }
+    function swatchesClasses() {
+        return [
+            "umds-color-picker__swatches",
+            usaPaletaDoDs() ? "umds-color-picker__swatches--familias" : "",
+        ]
+            .filter(Boolean)
+            .join(" ");
+    }
+    function groupAriaLabel() {
+        if (props.ariaLabel)
+            return props.ariaLabel;
+        // Antes do onMount o label ainda não tem id para o aria-labelledby apontar.
+        return props.label && !labelId() ? props.label : undefined;
+    }
+    function groupLabelledBy() {
+        return props.ariaLabelledby || labelId();
+    }
+    function corCss(valor) {
+        if (!valor)
+            return "";
+        return valor.indexOf("--") === 0 ? "var(" + valor + ")" : valor;
+    }
+    function swatchStyle(swatch) {
+        return {
+            backgroundColor: corCss(swatch.value),
+        };
+    }
+    function swatchClasses(swatch) {
+        return [
+            "umds-color-picker__swatch",
+            swatch.onLight ? "umds-color-picker__swatch--on-light" : "",
+            estaEscolhida(swatch) ? "umds-color-picker__swatch--selected" : "",
+        ]
+            .filter(Boolean)
+            .join(" ");
+    }
+    function novaLinha(swatch, index) {
+        if (!usaPaletaDoDs())
+            return false;
+        if (index === 0)
+            return true;
+        const anterior = swatchList()[index - 1];
+        return !!anterior && !!swatch.family && anterior.family !== swatch.family;
+    }
+    function swatchItemClasses(swatch, index) {
+        return [
+            swatchClasses(swatch),
+            novaLinha(swatch, index) ? "umds-color-picker__swatch--nova-linha" : "",
+        ]
+            .filter(Boolean)
+            .join(" ");
+    }
+    function estaEscolhida(swatch) {
+        return (!!currentValue() &&
+            swatch.value.toLowerCase() === currentValue().toLowerCase());
+    }
+    function estaDesabilitada(swatch) {
+        return !!props.disabled || !!swatch.disabled;
+    }
+    function indiceDoTab() {
+        const lista = swatchList();
+        for (let i = 0; i < lista.length; i++) {
+            if (estaEscolhida(lista[i]) && !estaDesabilitada(lista[i]))
+                return i;
+        }
+        for (let i = 0; i < lista.length; i++) {
+            if (!estaDesabilitada(lista[i]))
+                return i;
+        }
+        return 0;
+    }
+    function tabIndexDa(index) {
+        return index === indiceDoTab() ? 0 : -1;
+    }
+    function emitir(valor) {
+        setInternalValue(valor);
+        if (props.onChange)
+            props.onChange(valor);
+    }
+    function escolher(swatch) {
+        if (estaDesabilitada(swatch))
+            return;
+        setHexEditing(false);
+        setHexDraft("");
+        setHexTouched(false);
+        emitir(swatch.value);
+    }
+    function handleKeyDown(event, index) {
+        if (!event || event.altKey || event.ctrlKey || event.metaKey)
+            return;
+        const lista = swatchList();
+        const total = lista.length;
+        if (!total)
+            return;
+        let passo = 0;
+        let alvo = index;
+        if (event.key === "ArrowRight" || event.key === "ArrowDown")
+            passo = 1;
+        else if (event.key === "ArrowLeft" || event.key === "ArrowUp")
+            passo = -1;
+        else if (event.key === "Home") {
+            passo = 1;
+            alvo = -1;
+        }
+        else if (event.key === "End") {
+            passo = -1;
+            alvo = total;
+        }
+        else
+            return;
+        event.preventDefault();
+        for (let tentativa = 0; tentativa < total; tentativa++) {
+            alvo = (alvo + passo + total) % total;
+            if (!estaDesabilitada(lista[alvo]))
+                break;
+        }
+        if (estaDesabilitada(lista[alvo]))
+            return;
+        escolher(lista[alvo]);
+        if (groupRef.current) {
+            const botoes = groupRef.current.querySelectorAll('[role="radio"]');
+            const botao = botoes[alvo];
+            if (botao)
+                botao.focus();
+        }
+    }
+    function hexText() {
+        if (hexEditing)
+            return hexDraft;
+        const atual = currentValue();
+        return atual && atual.indexOf("#") === 0 ? atual : "";
+    }
+    function hexInvalid() {
+        return hexTouched && !!hexText() && !isHexColor(hexText());
+    }
+    function customPreview() {
+        const texto = hexText();
+        return isHexColor(texto) ? corCss(normalizarHex(texto)) : "";
+    }
+    function customLabelText() {
+        return props.customLabel || "Cor livre (hexadecimal)";
+    }
+    function customErrorText() {
+        return hexInvalid()
+            ? props.customErrorMessage || "Use o formato #RRGGBB"
+            : undefined;
+    }
+    function normalizarHex(texto) {
+        const limpo = texto.trim();
+        return (limpo.indexOf("#") === 0 ? limpo : "#" + limpo).toUpperCase();
+    }
+    function handleHexInput(texto) {
+        setHexEditing(true);
+        setHexDraft(texto);
+        if (isHexColor(texto))
+            emitir(normalizarHex(texto));
+    }
+    function handleHexBlur() {
+        setHexTouched(true);
+        if (isHexColor(hexDraft)) {
+            setHexEditing(false);
+            setHexDraft("");
+        }
+    }
+    useEffect(() => {
+        if (!props.id)
+            setUid(gerarId("umds-color-picker"));
+    }, []);
+    return (_jsxs("div", { className: groupClasses(), children: [props.label ? (_jsx("span", { className: "umds-color-picker__label", id: labelId(), children: props.label })) : null, _jsx("div", { role: "radiogroup", ref: groupRef, "aria-label": groupAriaLabel(), "aria-labelledby": groupLabelledBy(), className: swatchesClasses(), children: swatchList()?.map((swatch, index) => (_jsx("button", { type: "button", role: "radio", style: swatchStyle(swatch), "aria-checked": estaEscolhida(swatch) ? "true" : "false", "aria-label": swatch.label, title: swatch.label, disabled: estaDesabilitada(swatch), tabIndex: tabIndexDa(index), onClick: (event) => escolher(swatch), onKeyDown: (event) => handleKeyDown(event, index), className: swatchItemClasses(swatch, index), children: estaEscolhida(swatch) ? (_jsx(Icon, { size: "sm", variant: "inherit", icon: faCheck })) : null }, swatch.value))) }), props.allowCustom ? (_jsxs("div", { className: "umds-color-picker__custom", children: [_jsx("span", { "aria-hidden": "true", className: "umds-color-picker__custom-preview", style: {
+                            backgroundColor: customPreview(),
+                        } }), _jsx(Input, { size: "sm", placeholder: "#0058DB", label: customLabelText(), value: hexText(), disabled: props.disabled, errorMessage: customErrorText(), onChange: (texto) => handleHexInput(texto), onBlur: (event) => handleHexBlur() })] })) : null] }));
+}
+export default ColorPicker;

package/dist/components/Combobox/Combobox.css

@@ -214,6 +214,14 @@
   cursor: default;
 }
 
+/* Somente leitura não é desabilitado: o texto segue lido e a WCAG 1.4.3 vale
+   sem isenção. O placeholder padrão foi calibrado para fundo branco e cai para
+   ~4,2:1 sobre o fundo de somente leitura; neutral-dark-down passa 4,5:1 em
+   todos os temas (1doc 6,78:1 · 1doc-dark 10,83:1 · alto contraste 16,48:1). */
+.umds-combobox--readonly .umds-combobox__control::placeholder {
+  color: var(--umds-semantic-color-neutral-dark-down);
+}
+
 /* ── Dropdown (espelha .umds-select__dropdown) ── */
 .umds-combobox__dropdown {
   position: absolute;

package/dist/components/DataTable/DataTable.css

@@ -154,6 +154,26 @@
   outline-offset: -2px;
 }
 
+/* ── Linha de grupo (prop rowGroup) ──
+   Um <th scope="rowgroup"> que atravessa a tabela. Não é clicável nem
+   selecionável, então o hover da linha comum não se aplica. */
+.umds-datatable__row--group,
+.umds-datatable__row--group:hover {
+  background: var(--umds-semantic-color-background-light); /* #F4F6F9 */
+}
+
+.umds-datatable__group {
+  padding: var(--umds-primitive-spacing-nano) var(--umds-primitive-spacing-xxxs); /* 8px 16px */
+  font-size: var(--umds-primitive-font-size-xxxs); /* 12px */
+  font-weight: 700;
+  text-align: left;
+  color: var(--umds-semantic-color-neutral-dark-down); /* #565656 */
+}
+
+.umds-datatable--compact .umds-datatable__group {
+  padding: var(--umds-primitive-spacing-quarck) var(--umds-primitive-spacing-nano); /* 4px 8px */
+}
+
 /* ── Células ── */
 .umds-datatable__td {
   padding: var(--umds-primitive-spacing-mini) var(--umds-primitive-spacing-xxxs); /* protótipo --space-3 (12px): candidato a novo token; 16px */
@@ -237,3 +257,63 @@
   0%   { background-position: 200% 0; }
   100% { background-position: -200% 0; }
 }
+
+/* ── Variante document (variant="document") ──
+   Tabela de CONTEÚDO de documento (itens de nota, cotações): lê-se e imprime-se,
+   não se opera. Sem hover, sem cursor, sem cabeçalho grudado; grade de bordas
+   finas em todas as células, como no papel. Na impressão o cabeçalho se repete
+   a cada página e uma linha nunca é cortada ao meio. */
+.umds-datatable--document {
+  border: none;
+  border-radius: var(--umds-primitive-border-radius-none);
+  background: transparent;
+}
+
+.umds-datatable--document .umds-datatable__table {
+  border: var(--umds-primitive-border-width-hairline) solid var(--umds-semantic-color-neutral-light-medium);
+}
+
+.umds-datatable--document .umds-datatable__thead {
+  position: static;
+  border-bottom: none;
+}
+
+.umds-datatable--document .umds-datatable__th,
+.umds-datatable--document .umds-datatable__td {
+  border: var(--umds-primitive-border-width-hairline) solid var(--umds-semantic-color-neutral-light-medium);
+  vertical-align: top;
+  user-select: auto;
+}
+
+.umds-datatable--document .umds-datatable__th {
+  font-size: var(--umds-primitive-font-size-xxs); /* 14px: no papel o cabeçalho é lido, não escaneado */
+  white-space: normal;
+  color: var(--umds-semantic-color-neutral-dark-pure);
+}
+
+.umds-datatable--document .umds-datatable__row,
+.umds-datatable--document .umds-datatable__row:hover {
+  background: transparent;
+  border-bottom: none;
+}
+
+.umds-datatable--document .umds-datatable__td {
+  overflow-wrap: anywhere;
+}
+
+@media print {
+  .umds-datatable--document {
+    overflow-x: visible;
+    -webkit-print-color-adjust: exact;
+    print-color-adjust: exact;
+  }
+
+  .umds-datatable--document .umds-datatable__thead {
+    display: table-header-group;
+  }
+
+  .umds-datatable--document .umds-datatable__row {
+    break-inside: avoid;
+    page-break-inside: avoid;
+  }
+}

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

@@ -7,8 +7,10 @@ import './DataTable.css';
  * @property {string} width - Largura fixa da coluna (ex.: "120px")
  * @property {string} align - Alinhamento do conteúdo: 'left' | 'center' | 'right'
  * @property {function} render - Renderização customizada da célula: recebe a linha e o
- *   índice e retorna o conteúdo (ReactNode no React; no Vue, prefira retornar string).
- *   Sem `render`, a célula exibe `row[key]` — que também aceita ReactNode diretamente.
+ *   índice e retorna o conteúdo. No React devolve qualquer nó (badge, avatar, botão).
+ *   No Vue o retorno é tratado como TEXTO: para célula com markup use o slot
+ *   `#cell-<key>` (recebe `{ row, value, rowIndex }`), que vale sobre o `render`.
+ *   Sem `render` nem slot, a célula exibe `row[key]`.
  */
 export interface DataTableColumn {
     key: string;
@@ -32,6 +34,7 @@ export interface DataTableColumn {
  *   (selectedKeys/onSelectKeys) em vez de índice — sobrevive a paginação e ordenação.
  * @property {Array<string|number>} selectedKeys - Chaves das linhas selecionadas (controlado;
  *   requer rowKey)
+ * @property {string} variant - 'default' (tabela de interface) | 'document' (tabela de CONTEÚDO de documento: sem ordenação, seleção nem clique de linha, bordas finas, cabeçalho repetido e linha inteira por página na impressão)
  * @property {string} density - Densidade das células: 'default' | 'compact'
  * @property {string} sortKey - Chave da coluna atualmente ordenada
  * @property {string} sortDirection - Direção da ordenação: 'asc' | 'desc'
@@ -42,8 +45,16 @@ export interface DataTableColumn {
  * @property {function} onSelectKeys - Callback ao alterar a seleção por chave (requer rowKey)
  * @property {function} onRowClick - Callback ao clicar numa linha (recebe índice e a linha);
  *   cliques no checkbox de seleção não disparam
- * @quandoUsar Dados TABULARES que se comparam coluna a coluna, com ordenação, seleção e paginação. Semântica de tabela para leitor de tela.
- * @quandoNaoUsar Para hierarquia pai-filho — use `Tree`. Para cards em grade sem comparação coluna a coluna, use `Grid` com `Card`.
+ * @property {string|function} rowGroup - Agrupa linhas consecutivas: nome do campo ou função
+ *   (row, rowIndex) => rótulo. Antes da primeira linha de cada grupo entra uma linha de
+ *   grupo (`<th scope="rowgroup">` ocupando a largura toda). Linha sem rótulo não abre grupo.
+ *   A tabela não reordena: ordene `data` por grupo antes de passar.
+ * @property {function} renderRowGroup - Conteúdo da linha de grupo: (label, row, rowIndex) => nó.
+ *   Só no React. No Vue use o slot `#row-group` (recebe `{ label, row, rowIndex }`).
+ * @slot cell-<key> - Só no Vue. Célula livre da coluna `<key>`: `<template #cell-nome="{ row, value, rowIndex }">`.
+ * @slot row-group - Só no Vue. Conteúdo da linha de grupo: `{ label, row, rowIndex }`.
+ * @quandoUsar Dados TABULARES que se comparam coluna a coluna, com ordenação, seleção e paginação. Semântica de tabela para leitor de tela. Com `variant="document"`, a tabela que faz parte do TEXTO de um documento que se imprime (itens de nota, cotações): sem interação, com bordas finas e quebra de página que não corta linha.
+ * @quandoNaoUsar Para hierarquia pai-filho — use `Tree`. Para cards em grade sem comparação coluna a coluna, use `Grid` com `Card`. Para pares rótulo/valor de um documento (sem cabeçalho de coluna), use `DescriptionList`.
  */
 export interface DataTableProps {
     columns: DataTableColumn[];
@@ -53,7 +64,11 @@ export interface DataTableProps {
     selectable?: boolean;
     selectedRows?: number[];
     rowKey?: string | ((row: Record<string, any>) => string | number);
+    rowGroup?: string | ((row: Record<string, any>, rowIndex: number) => string | undefined);
+    renderRowGroup?: (label: string, row: Record<string, any>, rowIndex: number) => any;
     selectedKeys?: Array<string | number>;
+    /** `document`: tabela de conteúdo de documento, imprimível e sem interação. @default 'default' */
+    variant?: "default" | "document";
     density?: "default" | "compact";
     sortKey?: string;
     sortDirection?: "asc" | "desc";