@proef/common-ui 0.0.0-stage → 2.2.0

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/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/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,36 @@
+import React from 'react';
+/** O que se mostra num ListItem: o resto (ativo, marcado) é estado. */
+export interface ListItemContent {
+    /** A linha principal (ex: a descrição). Numa linha só, cortada com "…" se não couber. */
+    title: React.ReactNode;
+    /** Por cima do título, pequeno e em letra de máquina (ex: o número ou código). */
+    code?: React.ReactNode;
+    /** A primeira linha: etiquetas e avisos (ex: a categoria). */
+    badges?: React.ReactNode;
+    /** Por baixo do título: o resto do que se quer ver de relance (local, data, indicadores). */
+    meta?: 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;
+    className?: string;
+}
+/**
+ * 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 (etiquetas, código, título,
+ * detalhes) e o ListItem arruma-as sempre da mesma forma. Com
+ * `onCheckedChange` leva uma caixa à esquerda, para marcar vários (um
+ * [Checkbox](?path=/docs/v1-primitives-forms-checkbox--docs)).
+ *
+ * É um `<li>`: vai dentro de um `<ul>`.
+ */
+export default function ListItem({ title, code, badges, meta, active, onClick, checked, onCheckedChange, checkboxLabel, className, }: ListItemProps): React.JSX.Element;

package/dist/types/v1/primitives/navigation/Tabs/Tabs.d.ts

@@ -0,0 +1,58 @@
+import React from 'react';
+export interface TabItem<K extends string = string> {
+    id: K;
+    /** Normalmente texto; aceita JSX. Com `iconOnly`, tem de ser texto (vai para o nome do botão e para o tooltip). */
+    label: React.ReactNode;
+    /** Ícone antes do texto (ex: um ícone do lucide com `size={14}`). */
+    icon?: React.ReactNode;
+    /** Número ao lado do texto (ex: pendentes). Não aparece se for `undefined`. */
+    count?: number;
+    /** Explicação no tooltip (`data-tip`, com o `TooltipLayer`), com o `label` como título. */
+    tip?: string;
+    disabled?: boolean;
+}
+interface TabsBase<K extends string> {
+    items: TabItem<K>[];
+    /** Nome do conjunto, para leitores de ecrã (ex: "Estado das faturas"). */
+    label?: string;
+    /**
+     * `underline` (por omissão): separadores da página, com a linha por baixo.
+     * `segmented`: botões juntos numa caixa, para trocar de vista dentro de uma
+     * secção (ex: Lista · Quadro).
+     */
+    variant?: 'underline' | 'segmented';
+    /** Só os ícones; o `label` fica no tooltip e no nome do botão. */
+    iconOnly?: boolean;
+    className?: string;
+}
+export interface TabsSingleProps<K extends string = string> extends TabsBase<K> {
+    multiple?: false;
+    /** O separador escolhido. A app guarda este estado. */
+    value: K;
+    onChange: (id: K) => void;
+}
+export interface TabsMultipleProps<K extends string = string> extends TabsBase<K> {
+    /**
+     * Vários escolhidos ao mesmo tempo: um clique escolhe só esse separador;
+     * Ctrl/⌘/Shift + clique junta-o ou tira-o dos escolhidos.
+     */
+    multiple: true;
+    value: K[];
+    /** Os escolhidos depois do clique, e o separador clicado. */
+    onChange: (ids: K[], clicked: K) => void;
+    /** O separador "Todos": escolhê-lo limpa a escolha, e fica ativo quando não há nenhum escolhido. */
+    allId?: K;
+}
+export type TabsProps<K extends string = string> = TabsSingleProps<K> | TabsMultipleProps<K>;
+/**
+ * Separadores: escolher uma de várias vistas do mesmo ecrã.
+ *
+ * Só desenha os botões; o conteúdo de cada vista fica na app, que mostra o
+ * que corresponde a `value`. Setas ← → (e Home/End) mudam de separador,
+ * saltando os desativados. O escolhido fica a navy (não turquesa: turquesa
+ * sobre branco não tem contraste para texto).
+ *
+ * Com `multiple`, vários podem estar escolhidos (ex: estados de uma lista).
+ */
+export default function Tabs<K extends string = string>(props: TabsProps<K>): React.JSX.Element;
+export {};

package/package.json

@@ -1,6 +1,120 @@
-{
-  "name": "@proef/common-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@proef/common-ui",
+  "version": "2.2.0",
+  "description": "",
+  "main": "dist/esm/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/esm/index.js"
+    },
+    "./tailwind.css": "./dist/tailwind.css",
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "*.css",
+    "*.scss"
+  ],
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prebuild": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "vite build --config vite.lib.config.ts && tsc -p tsconfig.build.json && tailwindcss -i src/styles/tailwind.css -o dist/style.css --minify && tailwindcss -i src/styles/tailwind.layered.css -o dist/style.layered.css --minify && node scripts/css-components-layer.mjs && node scripts/extrair-imagens-css.mjs && node scripts/gerar-tema.mjs && node -e \"const fs=require('fs');fs.copyFileSync('src/styles/tailwind.app.css','dist/tailwind.css');fs.copyFileSync('src/styles/tokens.css','dist/tokens.css')\" && node -e \"import('./dist/esm/v1/capabilities/theme/useTheme.js').then(m=>require('fs').writeFileSync('dist/theme-boot.js',m.themeBootScript))\"",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "pub": "git add . && git commit -m \"update\" && git push && npm test && npm version patch && npm run build && npm publish",
+    "pubOnly": "npm test && npm version patch && npm run build && npm publish",
+    "pubOnlySameVersion": "npm run build && npm publish",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ci": "vitest run --coverage",
+    "release": "node scripts/release.mjs"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "peerDependencies": {
+    "@azure/msal-browser": ">=3",
+    "@azure/msal-react": ">=2",
+    "react": ">=18",
+    "react-dom": ">=18",
+    "react-router-dom": ">=6"
+  },
+  "peerDependenciesMeta": {
+    "@azure/msal-react": {
+      "optional": true
+    },
+    "@azure/msal-browser": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@azure/msal-browser": "^5.17.3",
+    "@azure/msal-react": "^5.5.4",
+    "@chromatic-com/storybook": "^5.5.1",
+    "@storybook/addon-docs": "^10.6.2",
+    "@storybook/addon-links": "^10.6.2",
+    "@storybook/addon-onboarding": "^10.6.2",
+    "@storybook/react-vite": "^10.6.2",
+    "@tailwindcss/cli": "^4.3.3",
+    "@tailwindcss/postcss": "^4.3.3",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.8",
+    "@types/js-cookie": "^3.0.6",
+    "@types/leaflet": "^1.9.22",
+    "@types/leaflet.markercluster": "^1.5.6",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@types/socket.io-client": "^3.0.0",
+    "@types/storybook__react": "^5.2.1",
+    "@vitejs/plugin-react": "^4.7.0",
+    "@vitest/coverage-v8": "^3.2.7",
+    "jsdom": "^26.1.0",
+    "msw": "^2.7.3",
+    "qrcode": "^1.5.4",
+    "react-router-dom": "^6.30.4",
+    "sass": "^1.84.0",
+    "storybook": "^10.6.2",
+    "tailwindcss": "^4.3.3",
+    "typescript": "^5.7.3",
+    "vite": "^7.3.7",
+    "vite-plugin-lib-inject-css": "^2.2.2",
+    "vitest": "^3.2.7"
+  },
+  "dependencies": {
+    "@fortawesome/fontawesome-svg-core": "^6.7.2",
+    "@fortawesome/free-brands-svg-icons": "^6.7.2",
+    "@fortawesome/free-regular-svg-icons": "^6.7.2",
+    "@fortawesome/free-solid-svg-icons": "^6.7.2",
+    "@fortawesome/react-fontawesome": "^0.2.2",
+    "@zxing/library": "^0.23.0",
+    "axios": "^1.8.1",
+    "chart.js": "^4.5.1",
+    "chartjs-plugin-datalabels": "^2.2.0",
+    "iconoir-react": "^7.11.0",
+    "js-cookie": "^3.0.5",
+    "keycloak-js": "^25.0.0",
+    "leaflet": "^1.9.4",
+    "leaflet.heat": "^0.2.0",
+    "leaflet.markercluster": "^1.5.3",
+    "pdfjs-dist": "^4.10.38",
+    "qr-scanner": "^1.4.2",
+    "react-chartjs-2": "^5.3.1",
+    "react-focus-lock": "^2.13.6",
+    "react-infinite-scroll-component": "^6.1.0",
+    "react-remove-scroll": "^2.6.3",
+    "react-switch": "^7.1.0",
+    "socket.io-client": "^4.8.1",
+    "tough-cookie": "^5.1.2",
+    "zxing-wasm": "^3.1.5"
+  },
+  "overrides": {
+    "storybook": "$storybook"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.