@proef/common-ui 0.0.0-stage → 2.2.1

package/dist/types/v1/primitives/display/FilterChips/FilterChips.d.ts

@@ -0,0 +1,33 @@
+import React from 'react';
+export interface FilterChipItem {
+    /** Identificador único da etiqueta. */
+    key: string;
+    /** Texto (ex: "Estado: Cancelado"). */
+    label: React.ReactNode;
+    /** Tira este filtro. */
+    onRemove: () => void;
+    /** Ícone antes do texto (ex: o de agrupar). */
+    icon?: React.ReactNode;
+    /** `filter` (turquesa): um filtro. `group` (violeta): um agrupamento. */
+    tone?: 'filter' | 'group';
+    /** Cores próprias (classes), em vez das do `tone` — ex: a cor do estado. */
+    colorClassName?: string;
+}
+export interface FilterChipsProps {
+    items: FilterChipItem[];
+    /** Tira todos. Sem isto não aparece o "Limpar tudo". */
+    onClearAll?: () => void;
+    clearAllLabel?: string;
+    /** Nome do botão × para leitores de ecrã (recebe o texto da etiqueta, quando é texto). */
+    removeLabel?: string;
+    className?: string;
+}
+/**
+ * Etiquetas dos filtros ativos, cada uma com × para o tirar, e "Limpar tudo".
+ *
+ * É o mesmo que a `DataTable` mostra por cima da tabela: usar este sempre que
+ * um ecrã mostra os filtros escolhidos (ex: ao clicar num gráfico), para se
+ * reconhecerem como a mesma coisa em todo o lado. Sem itens não desenha nada.
+ */
+export default function FilterChips({ items, onClearAll, clearAllLabel, removeLabel, className }: FilterChipsProps): React.JSX.Element | null;
+export { FilterChips };

package/dist/types/v1/primitives/display/Kpi/Kpi.d.ts

@@ -0,0 +1,68 @@
+import React from 'react';
+/**
+ * Estados com significado: `ok` (verde), `risco` (âmbar), `incumprido` (vermelho).
+ * Sem estado: `default` (texto normal) e `brand` (azul da marca).
+ * A cor é a do número — não usar cores só para enfeitar: um indicador sem
+ * significado bom/mau fica em `default`.
+ */
+export type KpiTone = 'default' | 'brand' | 'ok' | 'risco' | 'incumprido';
+export interface KpiProps {
+    label: React.ReactNode;
+    value: React.ReactNode;
+    tone?: KpiTone;
+    /** Linha por baixo do valor (ex: "de 120", "+12% do compromisso"). */
+    detail?: React.ReactNode;
+    /** Ícone antes do rótulo (ex: `<Inbox size={14} />`). */
+    icon?: React.ReactNode;
+    /** Ponto colorido antes do rótulo — liga o indicador à cor que ele tem no mapa ou na legenda. */
+    dot?: string;
+    /**
+     * Barra por baixo do valor. Um número é uma percentagem; uma lista é uma
+     * barra repartida, com cada troço proporcional ao seu peso.
+     *
+     * Serve para o indicador dizer a PROPORÇÃO e não só o valor: "253 concluídas"
+     * não diz nada sem saber de quantas.
+     */
+    bar?: number | {
+        weight: number;
+        color: string;
+    }[];
+    /** Linha pequena no fim, para um dado que acompanha mas não é o indicador. */
+    footer?: React.ReactNode;
+    /**
+     * Faixa fina em vez de cartão: alinha à esquerda e corta a altura para metade.
+     * Para muitos indicadores que empurrariam o conteúdo para fora do ecrã.
+     */
+    dense?: boolean;
+    /** Fundo no tom claro da cor, em vez de só o número colorido. */
+    tinted?: boolean;
+    /** Clicável (ex: filtra a tabela). Mostra o funil no canto (ou a seta, com `clickAction="open"`). */
+    onClick?: () => void;
+    /** O que o clique faz: `filter` (funil, por omissão) ou `open` (seta: abre uma lista ou um detalhe, não filtra). */
+    clickAction?: 'filter' | 'open';
+    /** Filtro ativo (Kpi clicável selecionado): contorno azul. */
+    active?: boolean;
+    /** Explicação no tooltip (camada `data-tip`), ex: "Filtrar a tabela" ou como o valor é calculado. */
+    hint?: string;
+    className?: string;
+    /** @deprecated Nome antigo (Legacy) de `detail`. */
+    delta?: React.ReactNode;
+    /** @deprecated Nome antigo (Legacy) de `tinted`. */
+    bgTint?: boolean;
+    /** @deprecated Nome antigo (Legacy) de `bar`. */
+    barra?: number | {
+        peso: number;
+        cor: string;
+    }[];
+    /** @deprecated Nome antigo (Legacy) de `footer`. */
+    rodape?: React.ReactNode;
+    /** @deprecated Nome antigo (Legacy) de `dense`. */
+    denso?: boolean;
+}
+/**
+ * Indicador: um número com o seu rótulo (ex: "Em progresso 13"). Quando é
+ * clicável filtra a vista e mostra-o com o funil; `active` marca o filtro
+ * aplicado. Dispor vários numa grelha (`grid gap-3`).
+ */
+export default function Kpi({ label, value, tone, detail: detailProp, icon, dot, bar: barProp, footer: footerProp, dense: denseProp, tinted: tintedProp, onClick, clickAction, active, hint, className, delta, bgTint, barra, rodape, denso, }: KpiProps): React.JSX.Element;
+export { Kpi };

package/dist/types/v1/primitives/display/Notice/Notice.d.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+export type NoticeTone = 'info' | 'warning' | 'error' | 'success';
+export interface NoticeProps {
+    /** `info` (azul), `warning` (âmbar), `error` (vermelho), `success` (verde). */
+    tone?: NoticeTone;
+    /** Título curto em cima (ex: "Automação — saída de colaborador"). */
+    title?: React.ReactNode;
+    children?: React.ReactNode;
+    /** Ícone à esquerda; por omissão, o do tom. `null` sem ícone. */
+    icon?: React.ReactNode | null;
+    /** Ação à direita (ex: "Voltar ao meu perfil"). */
+    action?: {
+        label: React.ReactNode;
+        onClick: () => void;
+    };
+    /**
+     * `box` (por omissão): caixa no meio do conteúdo, para explicar uma regra ou avisar de algo nesse sítio.
+     * `banner`: faixa a toda a largura no topo, para um estado que afeta a página inteira (ex: "Ver como").
+     */
+    variant?: 'box' | 'banner';
+    className?: string;
+}
+/**
+ * Aviso ou explicação: uma caixa com ícone, título e texto (ex: a regra de uma
+ * automação, dados possivelmente incompletos), ou uma faixa no topo da página.
+ * Não é para o resultado de uma ação — esse é um toast (`useToast`).
+ */
+export default function Notice({ tone, title, children, icon, action, variant, className }: NoticeProps): React.JSX.Element;
+export { Notice };

package/dist/types/v1/primitives/display/Person/Person.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import { type AvatarProps } from '../Avatar/Avatar';
+export interface PersonProps extends AvatarProps {
+    /** Só o avatar (o nome fica no cartão e no tooltip), ex: em colunas estreitas. */
+    hideName?: boolean;
+    /** O que mostrar sem nome nem email. */
+    empty?: React.ReactNode;
+}
+/**
+ * Uma pessoa, igual em todo o lado: o avatar (fotografia ou iniciais, com o cartão
+ * de detalhes ao passar o rato) e o nome ao lado, numa linha. Usar sempre que se
+ * mostra o nome de alguém (ex: solicitante, responsável, quem aprovou).
+ */
+export default function Person({ hideName, empty, className, ...avatar }: PersonProps): React.JSX.Element;
+export { Person };

package/dist/types/v1/primitives/display/RichText/RichText.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+export interface RichTextProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children' | 'dangerouslySetInnerHTML'> {
+    /** O texto: HTML do RichTextEditor ou texto simples (antigo, sem formatação). */
+    value: string | null | undefined;
+}
+/**
+ * Mostra um texto com formatação (negrito, listas, citações, ligações, imagens) escrito no
+ * [RichTextEditor](?path=/docs/v1-primitives-forms-richtexteditor--docs).
+ *
+ * O HTML é sempre limpo antes de entrar na página: só ficam as marcas de formatação (sem
+ * scripts, estilos nem eventos) e as ligações abrem noutro separador. Texto sem marcas
+ * (guardado antes do editor) aparece com as mudanças de linha.
+ *
+ * Não tem cor própria: herda a de quem o põe (ex: branco numa bolha navy de uma conversa).
+ */
+export declare function RichText({ value, className, ...props }: RichTextProps): React.JSX.Element;
+export default RichText;

package/dist/types/v1/primitives/display/RichText/utils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Texto com formatação (HTML do [RichTextEditor](?path=/docs/v1-primitives-forms-richtexteditor--docs)):
+ * as classes do conteúdo e as funções para o guardar, ler e mostrar em segurança.
+ */
+/**
+ * Aspeto do conteúdo (listas, citações, ligações, imagens). Sem cor de texto: herda a de quem o põe
+ * (ex: branco numa bolha navy de conversa).
+ */
+export declare const richTextContentClasses: string;
+/** Parece HTML (tem pelo menos uma marca)? Textos antigos, guardados sem formatação, não. */
+export declare function isRichText(value: string | null | undefined): boolean;
+/** Texto simples → HTML: um parágrafo por linha (as linhas em branco ficam). */
+export declare function textToRichText(text: string): string;
+/**
+ * HTML seguro para pôr na página: só as marcas de formatação, sem scripts nem atributos de eventos.
+ * Texto sem marcas é convertido (uma linha, um parágrafo). Usar sempre antes de `dangerouslySetInnerHTML`.
+ */
+export declare function sanitizeRichText(value: string | null | undefined): string;
+/** Só o texto (ex: pré-visualização numa lista, notificação, pesquisa). Parágrafos e itens viram linhas. */
+export declare function richTextToPlain(value: string | null | undefined): string;
+/** Sem texto nem imagens (ex: `<p></p>` de um editor vazio)? Para validar "obrigatório". */
+export declare function richTextIsEmpty(value: string | null | undefined): boolean;

package/dist/types/v1/primitives/documents/PdfPreview/PdfPreview.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+export interface PdfPreviewProps {
+    file: File;
+    /** Texto alternativo das páginas e mensagem quando o PDF não abre. */
+    label: string;
+    /** Imagem da 1.ª página já renderizada pela app, para aparecer de imediato. */
+    initialFirstPage?: string;
+    className?: string;
+}
+/**
+ * Pré-visualização de PDF com pdf.js: as páginas em coluna, com scroll vertical
+ * e sem a barra de ferramentas do visualizador nativo (que transborda em caixas
+ * estreitas). Cada página só é renderizada quando se aproxima da área visível.
+ *
+ * **Usado por:** [DocumentDropzone](?path=/docs/v1-components-documents-documentdropzone--docs) (quando o ficheiro é um PDF).
+ */
+export default function PdfPreview({ file, label, initialFirstPage, className }: PdfPreviewProps): React.JSX.Element;

package/dist/types/v1/primitives/documents/PdfPreview/pdfjs.d.ts

@@ -0,0 +1,11 @@
+import type * as PdfJs from 'pdfjs-dist';
+type PdfJsModule = typeof PdfJs;
+/**
+ * Indica ao pdf.js onde está o worker (`pdf.worker.min.mjs`) servido pela app.
+ * Chamar uma vez no arranque. Se a app já define `GlobalWorkerOptions.workerSrc`
+ * pela sua própria cópia do pdf.js (a mesma, quando deduplicada), não é preciso.
+ */
+export declare function configurePdfWorker(src: string): void;
+/** Carrega o pdf.js só quando há um PDF para mostrar; depois fica em cache. */
+export declare function loadPdfjs(): Promise<PdfJsModule>;
+export {};

package/dist/types/v1/primitives/forms/Checkbox/Checkbox.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+export interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type'> {
+    /** Marca a caixa a vermelho (ex: aceitar os termos, por marcar ao submeter). */
+    invalid?: boolean;
+    /**
+     * Meio marcada: um traço em vez do visto (ex: "selecionar todos" com só
+     * algumas marcadas). Só o aspeto: ao clicar, o browser tira-o e a caixa passa
+     * a marcada ou desmarcada pelo `onChange`, como sempre. Para leitores de ecrã é
+     * "parcialmente marcada".
+     */
+    indeterminate?: boolean;
+}
+/**
+ * Caixa de marcar.
+ *
+ * Dentro de um [FormField](?path=/docs/v1-components-forms-formfield--docs) fica
+ * ligada à etiqueta automaticamente. Fora dele, dar-lhe um `aria-label` ou
+ * envolvê-la num `<label>`: sozinha não tem nome para os leitores de ecrã.
+ *
+ * **Aceita os atributos HTML do [&lt;input type="checkbox"&gt;](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/checkbox)**, com o mesmo comportamento: `checked`/`defaultChecked`, `onChange`, `required`, `disabled`, `name`, `value`, `ref`, ...
+ * Só os próprios do V1 aparecem na tabela abaixo.
+ * Diferenças: o `className` aplica-se à caixa à volta; o `type` é sempre `checkbox`.
+ */
+declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLInputElement>>;
+export default Checkbox;

package/dist/types/v1/primitives/forms/DateInput/DateInput.d.ts

@@ -0,0 +1,43 @@
+import React from 'react';
+export interface DateInputProps {
+    /** Data em ISO (`aaaa-mm-dd`) ou `''` (vazio). Controlado. */
+    value?: string;
+    /** Valor inicial, sem controlar (ISO). */
+    defaultValue?: string;
+    /** Recebe só datas completas e válidas, em ISO; `''` quando se apaga. Enquanto se escreve, não é chamado. */
+    onChange?: (value: string) => void;
+    /** Ao terminar a edição: sair do campo ou escolher no calendário. */
+    onBlur?: () => void;
+    onKeyDown?: (e: React.KeyboardEvent<HTMLInputElement>) => void;
+    /** Limites, em ISO (só no calendário). */
+    min?: string;
+    max?: string;
+    disabled?: boolean;
+    readOnly?: boolean;
+    required?: boolean;
+    autoFocus?: boolean;
+    id?: string;
+    /** Marca o campo a vermelho (ex: obrigatório por preencher ao submeter). */
+    invalid?: boolean;
+    placeholder?: string;
+    /** Nome do campo para leitores de ecrã, quando não há etiqueta. */
+    'aria-label'?: string;
+    /** Texto do botão do calendário. */
+    calendarLabel?: string;
+    /** Classes da caixa à volta (ex: largura). */
+    className?: string;
+}
+/**
+ * Campo de data, sempre em **dd/mm/aaaa**.
+ *
+ * O `<input type="date">` do browser mostra a data no idioma do BROWSER, não no
+ * da página (num Chrome em inglês aparece mm/dd/aaaa), e não há atributo que o
+ * force. Aqui o texto é escrito pela biblioteca, com máscara; o calendário
+ * continua a ser o nativo (acessível e traduzido), aberto pelo ícone.
+ *
+ * O valor entra e sai em ISO (`aaaa-mm-dd`). Dentro de um
+ * [FormField](?path=/docs/v1-components-forms-formfield--docs) fica ligado à
+ * etiqueta automaticamente.
+ */
+export default function DateInput({ value, defaultValue, onChange, onBlur, onKeyDown, min, max, disabled, readOnly, required, autoFocus, id, invalid, placeholder, 'aria-label': ariaLabel, calendarLabel, className, }: DateInputProps): React.JSX.Element;
+export { DateInput };

package/dist/types/v1/primitives/forms/LookupInput/LookupInput.d.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+export interface LookupInputProps {
+    /** O que foi escolhido, como a app o quer mostrar (ex: "PRJ-0001 - Projeto de exemplo"). Vazio se nada. */
+    value: string;
+    /** Chamado ao carregar na lupa: a app abre a sua pesquisa e, quando se escolhe algo, atualiza o `value`. */
+    onLookup: () => void;
+    /** O que a lupa faz (ex: "Pesquisar projeto"). Lido pelos leitores de ecrã e mostrado ao passar o rato. */
+    lookupLabel: string;
+    /** Texto quando não há nada escolhido (ex: "Nenhum projeto"). */
+    placeholder?: string;
+    /** Marca o campo a vermelho (ex: obrigatório por escolher ao submeter). */
+    invalid?: boolean;
+    disabled?: boolean;
+    id?: string;
+    /** Aplica-se à caixa à volta (para a largura, por exemplo). */
+    className?: string;
+}
+/**
+ * Campo que **não se escreve**: o valor escolhe-se numa pesquisa, aberta pela
+ * lupa ao lado (ex: escolher um projeto). A pesquisa é da app; este campo só
+ * mostra o que foi escolhido.
+ *
+ * Dentro de um [FormField](?path=/docs/v1-components-forms-formfield--docs) fica
+ * ligado à etiqueta automaticamente.
+ *
+ * Não é como um `<input>` HTML: só aceita as props da tabela abaixo.
+ */
+export default function LookupInput({ value, onLookup, lookupLabel, placeholder, invalid, disabled, id, className }: LookupInputProps): React.JSX.Element;

package/dist/types/v1/primitives/forms/RichTextEditor/RichTextEditor.d.ts

@@ -0,0 +1,64 @@
+import React from 'react';
+export interface RichTextEditorLabels {
+    bold: string;
+    italic: string;
+    underline: string;
+    strike: string;
+    bulletList: string;
+    orderedList: string;
+    quote: string;
+    image: string;
+    maximize: string;
+    restore: string;
+}
+export interface RichTextEditorProps {
+    /** O texto, em HTML. Texto simples (antigo, sem formatação) também serve: cada linha vira um parágrafo. */
+    value: string;
+    /** Recebe o HTML a cada alteração; `''` quando fica vazio (para validar "obrigatório" sem olhar para `<p></p>`). */
+    onChange: (html: string) => void;
+    placeholder?: string;
+    /** Marca o campo a vermelho (ex: obrigatório por preencher ao submeter). */
+    invalid?: boolean;
+    disabled?: boolean;
+    /** Altura mínima da área de escrita, em px. Por omissão 80. */
+    minHeight?: number;
+    /** Altura máxima (px ou CSS, ex: `'50vh'`): cresce com o texto até aqui e depois faz scroll por dentro. Sem isto, cresce sempre. */
+    maxHeight?: number | string;
+    /**
+     * Onde guardar uma imagem (escolhida na barra, colada ou largada); devolve o `src` a pôr no texto.
+     * Sem isto, o editor não aceita imagens.
+     */
+    onUploadImage?: (file: File) => Promise<string>;
+    /** Mostra na barra o botão para escrever com o editor em ecrã quase inteiro (Esc volta). */
+    maximizable?: boolean;
+    /**
+     * Enviar com o teclado (ex: uma conversa): Ctrl+Enter chama-o sempre. Com `submitOnEnter`,
+     * também o Enter — exceto dentro de uma lista, onde o Enter cria o item seguinte. Shift+Enter muda de linha.
+     */
+    onSubmit?: () => void;
+    submitOnEnter?: boolean;
+    autoFocus?: boolean;
+    /** Nome acessível, quando não há etiqueta à volta (ex: "Escrever comentário"). */
+    'aria-label'?: string;
+    id?: string;
+    /** Aplica-se à caixa à volta. */
+    className?: string;
+    /** Textos da barra (para outra língua). */
+    labels?: Partial<RichTextEditorLabels>;
+}
+/**
+ * Texto com formatação, que se vê enquanto se escreve: negrito, itálico, sublinhado, riscado,
+ * listas, citações e (com `onUploadImage`) imagens. Atalhos habituais: Ctrl+B, Ctrl+I, Ctrl+U;
+ * "- " ou "1. " no início da linha começam uma lista.
+ *
+ * Guarda HTML. Para o mostrar, usar sempre o [RichText](?path=/docs/v1-primitives-display-richtext--docs),
+ * que o limpa antes de entrar na página. Para validar "obrigatório", o `onChange` dá `''` quando está vazio
+ * (ou `richTextIsEmpty`).
+ *
+ * Para uma conversa: `onSubmit` + `submitOnEnter` (Enter envia, Shift+Enter muda de linha) e `maxHeight`
+ * para crescer com o texto até um limite.
+ *
+ * Dentro de um [FormField](?path=/docs/v1-components-forms-formfield--docs) fica com o `id` do campo.
+ */
+export declare function RichTextEditor({ value, onChange, placeholder, invalid, disabled, minHeight, maxHeight, onUploadImage, maximizable, onSubmit, submitOnEnter, autoFocus, 'aria-label': ariaLabel, id, className, labels: labelsProp, }: RichTextEditorProps): React.JSX.Element | null;
+export default RichTextEditor;

package/dist/types/v1/primitives/forms/SearchInput/SearchInput.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+export interface SearchInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'type' | 'className'> {
+    value: string;
+    /** O texto novo, a cada tecla (e `''` ao limpar). */
+    onChange: (value: string) => void;
+    /** Nome do campo para leitores de ecrã. Por omissão, o placeholder. */
+    label?: string;
+    /** Nome do botão ×, para leitores de ecrã. Por omissão: "Limpar pesquisa". */
+    clearLabel?: string;
+    /** Largura e posição (classes do invólucro). Por omissão `w-56`. */
+    className?: string;
+    /** Ícone à esquerda, no lugar da lupa, quando o filtro é de algo concreto (ex: empresa, colaborador). Tamanho 14. */
+    icon?: React.ReactNode;
+}
+/**
+ * Caixa de pesquisa das barras de páginas, tabelas e listas: a mesma altura
+ * dos botões ao lado. Lupa à esquerda; com texto, um × para limpar (Esc também
+ * limpa).
+ *
+ * Aceita os outros atributos do `<input>` (`autoFocus`, `name`, `onKeyDown`, …).
+ */
+declare const SearchInput: React.ForwardRefExoticComponent<SearchInputProps & React.RefAttributes<HTMLInputElement>>;
+export default SearchInput;

package/dist/types/v1/primitives/forms/SelectInput/SelectInput.d.ts

@@ -0,0 +1,70 @@
+import React from 'react';
+export interface SelectOption {
+    value: string;
+    label: string;
+    /** Texto pequeno por baixo do rótulo, na lista. */
+    description?: string;
+    disabled?: boolean;
+}
+export interface SelectInputLabels {
+    /** Texto da caixa de pesquisa. */
+    search: string;
+    /** Nome da caixa de pesquisa para leitores de ecrã; "{label}" é o nome do campo. */
+    searchIn: string;
+    noResults: string;
+}
+export declare const DEFAULT_SELECT_LABELS: SelectInputLabels;
+export interface SelectInputProps {
+    /** A opção escolhida (controlado). `''` = nenhuma. */
+    value?: string;
+    defaultValue?: string;
+    /** As opções: texto simples (valor = rótulo) ou `{ value, label, description }`. */
+    options?: readonly (string | SelectOption)[];
+    /** Em alternativa a `options`: `<option>` como num `<select>` (compatível com o uso antigo). */
+    children?: React.ReactNode;
+    /** Recebe o valor escolhido. */
+    onValueChange?: (value: string) => void;
+    /** Como no `<select>`: `e.target.value` é o valor escolhido. */
+    onChange?: (e: React.ChangeEvent<HTMLSelectElement>) => void;
+    /** Texto do botão sem nada escolhido; com `placeholderOption`, também a primeira opção (vazia). */
+    placeholder?: string;
+    /** O `placeholder` é também uma opção (vazia) na lista. Por omissão sim, como no `<select>`. */
+    placeholderOption?: boolean;
+    /** Primeira opção vazia para desfazer a escolha (ex: "Todas"). */
+    emptyOption?: string;
+    /** Caixa de pesquisa no topo da lista. Por omissão, só com mais de 10 opções. */
+    searchable?: boolean;
+    disabled?: boolean;
+    required?: boolean;
+    /** Marca o campo a vermelho (ex: obrigatório por escolher ao submeter). */
+    invalid?: boolean;
+    id?: string;
+    /** Nome no formulário (vai num campo escondido). */
+    name?: string;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    /** `field` (por omissão): campo. `pill`: etiqueta arredondada (ex: o estado numa linha de tabela). A lista é a mesma. */
+    variant?: 'field' | 'pill';
+    /** Cores da etiqueta (`pill`), normalmente conforme o valor escolhido; pode trazer contorno (ex: `border border-dashed`). */
+    pillClassName?: string;
+    /** 38px em vez da altura dos controlos (para alinhar com campos de formulários mais altos). */
+    tall?: boolean;
+    labels?: Partial<SelectInputLabels>;
+    /** Classes da caixa à volta (ex: a largura). */
+    className?: string;
+}
+/**
+ * Lista de escolha: um campo que abre uma lista desenhada pela biblioteca (não a do sistema, que não segue o
+ * tema nem o aspeto dos portais). A opção escolhida tem ✓; com muitas opções há pesquisa.
+ *
+ * Teclado: ↑/↓, Home/End, Enter escolhe, Esc fecha; sem pesquisa, uma letra salta para a opção.
+ *
+ * Dentro de um [FormField](?path=/docs/v1-components-forms-formfield--docs) fica ligado à etiqueta
+ * automaticamente. Clicar não chega a uma linha clicável por baixo (ex: numa tabela).
+ *
+ * Usa-se como um `<select>`: `<option>` como filhos e `onChange` com `e.target.value`; `placeholder`
+ * acrescenta uma primeira opção vazia.
+ */
+declare const SelectInput: React.ForwardRefExoticComponent<SelectInputProps & React.RefAttributes<HTMLButtonElement>>;
+export default SelectInput;
+export { SelectInput };

package/dist/types/v1/primitives/forms/TextArea/TextArea.d.ts

@@ -0,0 +1,40 @@
+import React from 'react';
+export interface TextAreaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
+    /** Marca o campo a vermelho (ex: obrigatório por preencher ao submeter). */
+    invalid?: boolean;
+    /** Mostra no canto quantos caracteres tem. Com `maxLength`, "usados/máximo", e fica âmbar perto do limite. */
+    counter?: boolean;
+    /**
+     * Deixar o texto passar o `maxLength`, e como o mostrar:
+     * - sem `overflow` (por omissão): não passa. Tentar escrever ou colar a mais
+     *   avisa (`limitReachedLabel`, `truncatedLabel`).
+     * - `warning`: passa, com aviso a âmbar. O campo continua válido.
+     * - `error`: passa, com aviso a vermelho, e o campo fica inválido.
+     *
+     * Com `overflow`, o texto não é cortado: a app tem de verificar o tamanho
+     * antes de guardar.
+     */
+    overflow?: 'warning' | 'error';
+    /** Sem `overflow`: aviso ao tentar escrever com o campo cheio. Por omissão: "Chegou ao limite de {maxLength} caracteres." */
+    limitReachedLabel?: string;
+    /** Sem `overflow`: aviso quando um texto colado é cortado. Por omissão: "Texto cortado: só cabem {maxLength} caracteres." */
+    truncatedLabel?: string;
+    /** Com `overflow`: aviso enquanto o texto passa o limite. Por omissão: "{a mais} caracteres a mais (máximo {maxLength})." */
+    overflowLabel?: (excess: number, max: number) => string;
+}
+/**
+ * Texto em várias linhas. Pode ser esticado na vertical.
+ *
+ * Com `counter`, mostra quantos caracteres tem (e o máximo, se houver `maxLength`).
+ * Com `maxLength`, o texto não passa do limite e o campo avisa quando se tenta
+ * escrever ou colar a mais. Com `overflow`, pode passar, como aviso ou erro.
+ *
+ * Dentro de um [FormField](?path=/docs/v1-components-forms-formfield--docs) fica
+ * ligado à etiqueta automaticamente.
+ *
+ * **Aceita os atributos HTML do [&lt;textarea&gt;](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/textarea)**, com o mesmo comportamento: `value`/`onChange`, `required`, `disabled`, `readOnly`, `name`, `placeholder`, `maxLength`, `minLength`, `ref`, ...
+ * Só os próprios do V1 aparecem na tabela abaixo.
+ * Diferenças: o `className` aplica-se à caixa à volta; com `overflow`, o `maxLength` deixa de ser imposto.
+ */
+declare const TextArea: React.ForwardRefExoticComponent<TextAreaProps & React.RefAttributes<HTMLTextAreaElement>>;
+export default TextArea;

package/dist/types/v1/primitives/forms/TextInput/TextInput.d.ts

@@ -0,0 +1,16 @@
+import React from 'react';
+export interface TextInputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+    /** Marca o campo a vermelho (ex: obrigatório por preencher ao submeter). */
+    invalid?: boolean;
+}
+/**
+ * Campo de texto de uma linha (também data, número, etc. pelo `type`).
+ *
+ * Dentro de um [FormField](?path=/docs/v1-components-forms-formfield--docs) fica
+ * ligado à etiqueta automaticamente.
+ *
+ * **Aceita os atributos HTML do [&lt;input&gt;](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input)**, com o mesmo comportamento: `value`/`onChange`, `required`, `disabled`, `readOnly`, `name`, `placeholder`, `type`, `min`/`max`, `maxLength`, `pattern`, `ref`, ...
+ * Só os próprios do V1 aparecem na tabela abaixo.
+ */
+declare const TextInput: React.ForwardRefExoticComponent<TextInputProps & React.RefAttributes<HTMLInputElement>>;
+export default TextInput;

package/dist/types/v1/primitives/forms/field.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Aspeto comum dos campos (TextInput, SelectInput, TextArea): altura `--spacing-control`, borda
+ * clara, anel suave no foco, vermelho quando inválido (`aria-invalid`) e cinzento
+ * quando desativado.
+ */
+/** O aspeto do campo sem o `display`/largura (para quem é flex, ex: o botão do SelectInput). */
+export declare const fieldBoxClasses: string;
+export declare const fieldClasses: string;
+/** Só para campos de texto: um `<select>` também conta como `:read-only` no browser. */
+export declare const readOnlyClasses = "read-only:cursor-default read-only:bg-muted";
+/**
+ * Dado pelo FormField ao campo lá dentro: o `id` que liga a etiqueta ao campo e
+ * se é obrigatório. Fora de um FormField, os campos funcionam sozinhos.
+ */
+export declare const FieldContext: import("react").Context<{
+    id?: string;
+    required?: boolean;
+}>;
+export declare const useField: () => {
+    id?: string;
+    required?: boolean;
+};

package/dist/types/v1/primitives/lists/ListItem/ListItem.d.ts

@@ -0,0 +1,67 @@
+import React from 'react';
+/** O que se mostra num ListItem: o resto (ativo, marcado) é estado. */
+export interface ListItemContent {
+    /** Por baixo do código: o que a linha é (ex: a descrição). Até duas linhas, cortada com "…" se não couber. */
+    title: React.ReactNode;
+    /** O texto mais forte da linha, em letra de máquina (ex: o número ou código). */
+    code?: React.ReactNode;
+    /** Na linha do código, logo a seguir a ele: indicadores e avisos curtos. */
+    badges?: React.ReactNode;
+    /** Por baixo do título, pequeno e numa linha só (cortada com "…"): o resto do que se quer ver de relance, separado por " · " (ex: local · data). */
+    meta?: React.ReactNode;
+    /**
+     * Opcional, e só com caixa de marcar (`onCheckedChange`): uma etiqueta curta
+     * (ex: a categoria) no espaço que a caixa abre por baixo dela. Sem caixa não
+     * se mostra — não há coluna para ela.
+     */
+    tag?: React.ReactNode;
+    /** À direita, ao nível do código: marcas que se querem ver mesmo a correr a lista. */
+    aside?: React.ReactNode;
+}
+export interface ListItemProps extends ListItemContent {
+    /** O que está aberto ao lado (fica realçado). */
+    active?: boolean;
+    /** Ao clicar (ou Enter/Espaço com o foco nele): normalmente, abri-lo. */
+    onClick?: () => void;
+    /** Marcado. Só há caixa de marcar se vier com `onCheckedChange`. */
+    checked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    /** O nome da caixa de marcar, para leitores de ecrã (ex: "Marcar P-020000"). */
+    checkboxLabel?: string;
+    /**
+     * O que se procurou: realça-se no código e no título quando são texto (sem
+     * acentos nem maiúsculas). O [ListFinder](?path=/docs/v1-components-lists-listfinder--docs) passa-o sozinho.
+     */
+    highlight?: string[];
+    className?: string;
+}
+/**
+ * A linha entre linhas, esbatida nas pontas: uma risca de ponta a ponta
+ * fechava cada linha numa caixa. Desenhada como fundo (e não com um ::after,
+ * que o botão da linha já usa); a última linha não a leva.
+ */
+export declare const LINHA_ESBATIDA = "bg-[linear-gradient(to_right,transparent,var(--color-slate-200)_15%,var(--color-slate-200)_85%,transparent)] bg-[length:100%_1px] bg-bottom bg-no-repeat last:bg-none";
+/**
+ * Texto com os pedaços que batem com a pesquisa realçados: numa descrição
+ * comprida, ou num número de dez dígitos, não se via onde é que o que se
+ * escreveu bateu.
+ */
+export declare function HighlightText({ text, terms }: {
+    text: string;
+    terms?: string[];
+}): React.JSX.Element;
+/**
+ * Uma linha de uma lista para escolher: o cartão das listas do
+ * [ListFinder](?path=/docs/v1-components-lists-listfinder--docs).
+ *
+ * Não sabe o que mostra: a app dá as partes e o ListItem arruma-as sempre da
+ * mesma forma. O código é o texto mais forte da linha, com os indicadores ao
+ * lado; o título vem por baixo, mais pequeno, e o resto por baixo dele. Com
+ * `onCheckedChange` leva uma caixa à esquerda, para marcar vários (um
+ * [Checkbox](?path=/docs/v1-primitives-forms-checkbox--docs)), numa coluna de
+ * largura fixa — senão os títulos começavam em sítios diferentes de linha para
+ * linha — e, se se quiser, a `tag` por baixo dela.
+ *
+ * É um `<li>`: vai dentro de um `<ul>`.
+ */
+export default function ListItem({ title, code, badges, meta, tag, aside, active, onClick, checked, onCheckedChange, checkboxLabel, highlight, className, }: ListItemProps): React.JSX.Element;