@ishtar-sink/vega 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+# Vega
 
-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.
+Biblioteca de componentes React e temas do ecossistema [Ishtar Sink](https://github.com/Ishtar-Sink). Todo produto da organização monta a interface com as mesmas peças (botões, campos, diálogos, avisos, abas, cartões) e recebe daqui o tema. O tema do Ishtar Sink é o padrão: quando ele muda aqui, todos os produtos que o usam acompanham na próxima atualização. Quem precisar pode trocar a paleta pela sua.
+
+Código aberto (AGPL-3.0) e aberto a qualquer projeto, dentro ou fora do ecossistema.
+
+A Vega nasce da extração do `@atria/ui` e do `@atria/theme`, a biblioteca e o tema que o [Atria](https://github.com/Ishtar-Sink/Atria) construiu para a própria interface, e é publicada como `@ishtar-sink/vega`. As mudanças de cada versão estão no [CHANGELOG](CHANGELOG.md).
+
+## Temas
+
+- **Tema Ishtar Sink, padrão.** É a paleta das [diretrizes do ecossistema](https://github.com/Ishtar-Sink/.github/blob/main/docs/identidade-ecossistema.md), nos temas claro e escuro, junto com a tipografia (Outfit e Inter), os raios, o espaço e o movimento.
+- **Paleta própria.** Uma aplicação cria o próprio tema com a API de tema da Vega, preenchendo os mesmos tokens (`bg`, `surface`, `primary`, `success`, os `*Soft`…) nos dois temas, e passa esse tema para os componentes. Nenhum componente tem cor fixa.
+- **Contraste verificado.** A Vega traz as verificações de contraste que o tema padrão usa (AA para texto), para que um tema próprio passe pelas mesmas regras nos testes da aplicação.
+- **Troca em tempo de execução.** A camada de marca pode ser sobrescrita sem rebuild, o que permite o white label por instância nos produtos que o oferecem.
+
+## Componentes
+
+| Grupo | Componentes e funções |
+|---|---|
+| Ações | `Button` (com `size` e `block` desde a 0.2.0), `IconButton`, `MenuButton` |
+| Campos | `TextField`, `SelectField`, `Checkbox`, `SegmentedField`, `Autocomplete`, `TagField`, `ColorField`, `ColorPicker`, `DEFAULT_COLOR_FIELD_LABELS`, `hexToRgb`, `rgbToHex`, `hslToRgb`, `rgbToHsl`; na 0.2.0, `Switch`, `RadioGroup`, `TextAreaField` |
+| Data e hora | `Calendar`, `DateField`, `TimeField`, `DateTimeField`, `PeriodField`, `parseTime`, `maskTime`, `resolvePeriod` |
+| Dinheiro | `MoneyField`, `maskMoneyInput`, `parseMoneyInput`, `formatCents` |
+| Estrutura | `Card`, `PageHeader`, `Toolbar`, `Tabs`, `ViewSwitcher`, `FormGrid`, `FormActions`; na 0.2.0, `CardLink`, `CardButton`, `FocusHeader`, `Disclosure`, `Accordion` |
+| Diálogos e avisos | `Dialog`, `ConfirmDialog`, `Toast`, `ToastRegion`; na 0.2.0, `BottomSheet`, `Callout` |
+| Estados | `EmptyState`, `LoadingState`, `Skeleton`, `ErrorState`, `ProgressBar` (com `valueText` e `indeterminate` desde a 0.2.0) |
+| Marca e itens | `BrandLogo`, `Badge`, `ItemSwatch`, `ListIcon`, `GridIcon`, `ShelfIcon`, `TableIcon`, `DayIcon`, `TimelineIcon` |
+| Ícones de interface | Os 36 da seção [Ícones](#ícones), na 0.2.0 |
+| Navegação | `AppShell`, `Sidebar`, `BottomNav`, `Topbar`, na 0.2.0 |
+| Conteúdo | `Prose`, na 0.2.0, pela entrada `@ishtar-sink/vega/prose` |
+
+Os grupos Ações, Campos, Data e hora, Dinheiro, Estrutura, Diálogos e avisos, Estados e Marca e itens entraram na 0.1.0; o que a tabela marca com 0.2.0, e os grupos Ícones de interface, Navegação e Conteúdo, entraram na 0.2.0.
+
+## Princípios
+
+- **Uma fonte para a identidade.** Os componentes leem os tokens do tema e não declaram cor, raio, espaço nem fonte próprios.
+- **Acessível por padrão.** Cada componente é testado com axe e com navegação por teclado, e o contraste dos tokens é verificado em AA.
+- **Tema claro e escuro.** Os dois funcionam sem configuração, com o claro como padrão.
+- **Sem dependência de serviço externo.** Fontes e ícones vêm junto com o pacote, nunca de um CDN em tempo de execução.
+- **Nenhum produto do ecossistema recria um componente que já existe aqui.** Se faltar algo, o componente entra na Vega, não no produto.
+
+## Instalação
+
+```bash
+pnpm add @ishtar-sink/vega react react-dom
+```
+
+`react` e `react-dom` `^19.3.1` são peer dependencies.
+
+## Estilos
+
+```ts
+import '@ishtar-sink/vega/tokens.css';
+import '@ishtar-sink/vega/styles.css';
+```
+
+O `tokens.css` traz as variáveis dos dois temas e as fontes; o `styles.css`, o CSS dos componentes. Importe os dois uma vez, na entrada da aplicação, nessa ordem.
+
+O tema claro é o padrão. Para o escuro, use `data-theme="dark"` num elemento ancestral, como o `<html>`. A marca pode ser sobrescrita por variáveis como `--primary` num contêiner, sem rebuild.
+
+## Uso
+
+```tsx
+import { Button, Card } from '@ishtar-sink/vega';
+
+export function Exemplo() {
+  return (
+    <Card>
+      <Button variant="primary">Salvar</Button>
+    </Card>
+  );
+}
+```
+
+## Ícones
+
+Os 36 ícones de interface vêm do [Lucide](https://lucide.dev), pelo pacote `lucide-react` (licença ISC), com os nomes da Vega: `HomeIcon`, `BookOpenIcon`, `LayersIcon`, `TimerIcon`, `UsersIcon`, `MenuIcon`, `ChevronLeftIcon`, `ChevronRightIcon`, `ChevronDownIcon`, `ArrowLeftIcon`, `CloseIcon`, `PlusIcon`, `MinusIcon`, `DownloadIcon`, `UploadIcon`, `FlagIcon`, `RefreshIcon`, `EyeIcon`, `CheckIcon`, `CircleCheckIcon`, `InfoIcon`, `AlertTriangleIcon`, `CircleAlertIcon`, `WifiOffIcon`, `CloudCheckIcon`, `UserIcon`, `SettingsIcon`, `LogOutIcon`, `SunIcon`, `MoonIcon`, `LightbulbIcon`, `ClockIcon`, `CalendarIcon`, `PencilIcon`, `SearchIcon` e `TrashIcon`.
+
+Os ícones são sempre decorativos (`aria-hidden`), usam a cor do texto (`currentColor`) e têm tamanho 16, 20 ou 24, com 20 por padrão. O nome acessível fica no elemento que contém o ícone.
+
+```tsx
+import { Button, HomeIcon } from '@ishtar-sink/vega';
+
+export function Inicio() {
+  return (
+    <Button variant="primary">
+      <HomeIcon size={16} />
+      Início
+    </Button>
+  );
+}
+```
+
+## Texto formatado (Prose)
+
+O `Prose` sai numa entrada própria, `@ishtar-sink/vega/prose`, para que quem não usa Markdown não carregue o parser. O HTML cru do texto é ignorado, e links com `javascript:`, `data:` ou `vbscript:` são bloqueados.
+
+```tsx
+import { Prose } from '@ishtar-sink/vega/prose';
+
+export function Licao({ texto }: { texto: string }) {
+  return <Prose markdown={texto} size="reading" />;
+}
+```
+
+Extensões do produto, como fórmulas de matemática, entram por `remarkPlugins` (sintaxe nova) e `components` (como cada elemento é renderizado), sem mudar a Vega.
+
+## Tema próprio
+
+```ts
+import { dark, defineTheme, light } from '@ishtar-sink/vega';
+
+export const meuTema = defineTheme({
+  light: { ...light, primary: '#115e59' },
+  dark: { ...dark, primary: '#5eead4' },
+});
+```
+
+Um teste da aplicação confere que o tema passa nas mesmas regras de contraste do tema padrão:
+
+```ts
+import { checkThemeContrast } from '@ishtar-sink/vega';
+import { meuTema } from './tema';
+
+it('o tema próprio passa no contraste AA', () => {
+  expect(checkThemeContrast(meuTema)).toEqual([]);
+});
+```
+
+## Sobre o nome
+
+Vega, a estrela mais brilhante da Lira, é a referência de brilho da astronomia: por séculos, o brilho de todas as outras estrelas foi medido em relação a ela, que é o ponto zero da escala de magnitude. A biblioteca é a referência visual contra a qual todos os produtos do Ishtar Sink se medem, mesmo os que escolhem uma cor própria.
+
+## Licença
+
+[AGPL-3.0](LICENSE).

package/dist/app-shell/app-shell.constants.d.ts

@@ -0,0 +1,13 @@
+/** Textos padrão da `Sidebar` e da `BottomNav`. */
+export declare const DEFAULT_NAV_LABELS: {
+    readonly navigation: "Principal";
+};
+/** Textos padrão do `AppShell`. */
+export declare const DEFAULT_APP_SHELL_LABELS: {
+    readonly skipToContent: "Pular para o conteúdo";
+    readonly openMenu: "Abrir menu";
+};
+/** Abaixo de 720 px a navegação vira gaveta ou barra inferior, como o `@media` dos estilos. */
+export declare const COMPACT_QUERY: string;
+/** Elementos que recebem foco dentro da gaveta. */
+export declare const FOCUSABLE = "a[href], button:not([disabled]), [tabindex]:not([tabindex=\"-1\"])";

package/dist/app-shell/app-shell.d.ts

@@ -0,0 +1,6 @@
+import { AppShellProps } from './app-shell.types';
+/**
+ * Estrutura da aplicação: link de pular, `Sidebar`, `Topbar` e `<main>`. Abaixo de 720 px, a
+ * navegação vira gaveta com botão de menu ou `BottomNav`, conforme `mobileNav`.
+ */
+export declare function AppShell({ sidebar, topbar, mobileNav, hideNavigation, children, labels, className, ...rest }: AppShellProps): import('react').JSX.Element;

package/dist/app-shell/app-shell.types.d.ts

@@ -0,0 +1,20 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+import { SidebarProps } from './sidebar.types';
+import { TopbarProps } from './topbar.types';
+export interface AppShellProps extends ComponentPropsWithRef<'div'> {
+    /** Props da `Sidebar`; a gaveta é controlada pelo próprio `AppShell`. */
+    sidebar: Omit<SidebarProps, 'drawer' | 'open' | 'onClose'>;
+    /** Props da `Topbar`; sem ela, a barra só aparece no modo gaveta, com o botão de menu. */
+    topbar?: TopbarProps;
+    /** Navegação abaixo de 720 px: gaveta com botão de menu ou barra inferior. Padrão: `drawer`. */
+    mobileNav?: 'drawer' | 'bottom';
+    /** Esconde toda a navegação (barra lateral, gaveta, barra inferior e link de pular). */
+    hideNavigation?: boolean;
+    /** Conteúdo da página, dentro do `<main>`. */
+    children: ReactNode;
+    /** Textos visíveis e nomes acessíveis. Padrão: `Pular para o conteúdo` e `Abrir menu`. */
+    labels?: Partial<{
+        skipToContent: string;
+        openMenu: string;
+    }>;
+}

package/dist/app-shell/bottom-nav.d.ts

@@ -0,0 +1,3 @@
+import { BottomNavProps } from './bottom-nav.types';
+/** Barra inferior fixa com 3 a 5 destinos, sempre com ícone e rótulo. */
+export declare function BottomNav({ items, renderLink, labels, className, ...rest }: BottomNavProps): import('react').JSX.Element;

package/dist/app-shell/bottom-nav.types.d.ts

@@ -0,0 +1,12 @@
+import { ComponentPropsWithRef } from 'react';
+import { NavItem, RenderNavLink } from './nav.types';
+export interface BottomNavProps extends ComponentPropsWithRef<'nav'> {
+    /** De 3 a 5 destinos; fora disso, um aviso no console em desenvolvimento. */
+    items: readonly NavItem[];
+    /** Desenha cada link com o roteador do produto; sem ele, um `<a href>` simples. */
+    renderLink?: RenderNavLink;
+    /** Textos visíveis e nomes acessíveis. Padrão: `{ navigation: 'Principal' }`. */
+    labels?: Partial<{
+        navigation: string;
+    }>;
+}

package/dist/app-shell/nav-link.d.ts

@@ -0,0 +1,11 @@
+import { NavItem, RenderNavLink } from './nav.types';
+interface NavLinkProps {
+    item: NavItem;
+    className: string | undefined;
+    iconClassName?: string | undefined;
+    badgeClassName?: string | undefined;
+    renderLink?: RenderNavLink;
+}
+/** Link de um destino: usa o `renderLink` do produto ou, sem ele, um `<a href>` simples. */
+export declare function NavLink({ item, className, iconClassName, badgeClassName, renderLink, }: NavLinkProps): string | number | bigint | boolean | Iterable<import('react').ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<import('react').ReactNode> | null | undefined> | import('react').JSX.Element | null | undefined;
+export {};

package/dist/app-shell/nav.types.d.ts

@@ -0,0 +1,22 @@
+import { ReactNode } from 'react';
+/** Destino da navegação, usado pela `Sidebar`, pela `BottomNav` e pelo `AppShell`. */
+export interface NavItem {
+    /** Identificador estável do destino, usado como chave. */
+    id: string;
+    /** Rótulo visível do destino. */
+    label: string;
+    /** Ícone em SVG inline; fica dentro de um `<span aria-hidden="true">`. */
+    icon: ReactNode;
+    /** Endereço do destino, usado pelo `<a>` simples ou pelo `renderLink`. */
+    href: string;
+    /** Marca o destino atual com `aria-current="page"`. */
+    current?: boolean;
+    /** Selo opcional ao lado do rótulo (ex.: a contagem de pendências). */
+    badge?: ReactNode;
+}
+/** Desenha o link com o componente do roteador do produto, repassando as props recebidas. */
+export type RenderNavLink = (item: NavItem, props: {
+    className: string;
+    'aria-current'?: 'page';
+    children: ReactNode;
+}) => ReactNode;

package/dist/app-shell/sidebar.d.ts

@@ -0,0 +1,3 @@
+import { SidebarProps } from './sidebar.types';
+/** Barra lateral com a marca, a navegação principal e o rodapé; vira gaveta com `drawer`. */
+export declare function Sidebar({ brand, items, renderLink, footer, drawer, open, onClose, labels, className, onKeyDown, ref, ...rest }: SidebarProps): import('react').JSX.Element;

package/dist/app-shell/sidebar.types.d.ts

@@ -0,0 +1,22 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+import { NavItem, RenderNavLink } from './nav.types';
+export interface SidebarProps extends ComponentPropsWithRef<'aside'> {
+    /** Marca do produto, no topo da barra. */
+    brand: ReactNode;
+    /** Destinos da navegação principal. */
+    items: readonly NavItem[];
+    /** Desenha cada link com o roteador do produto; sem ele, um `<a href>` simples. */
+    renderLink?: RenderNavLink;
+    /** Conteúdo do rodapé (ex.: conta, tema, ajustes). */
+    footer?: ReactNode;
+    /** Modo gaveta: barra fixa sobre o conteúdo, com foco preso enquanto aberta. Padrão: `false`. */
+    drawer?: boolean;
+    /** Gaveta aberta; fechada, ela fica `inert`. Só vale com `drawer`. */
+    open?: boolean;
+    /** Chamado no Escape e ao escolher um link com a gaveta aberta. */
+    onClose?: () => void;
+    /** Textos visíveis e nomes acessíveis. Padrão: `{ navigation: 'Principal' }`. */
+    labels?: Partial<{
+        navigation: string;
+    }>;
+}

package/dist/app-shell/topbar.d.ts

@@ -0,0 +1,3 @@
+import { TopbarProps } from './topbar.types';
+/** Barra superior com os slots de início, meio e fim. */
+export declare function Topbar({ start, center, end, className, ...rest }: TopbarProps): import('react').JSX.Element;

package/dist/app-shell/topbar.types.d.ts

@@ -0,0 +1,9 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+export interface TopbarProps extends ComponentPropsWithRef<'header'> {
+    /** Slot do início da barra (ex.: o botão de menu ou o voltar). */
+    start?: ReactNode;
+    /** Slot do meio da barra (ex.: o título da tela). */
+    center?: ReactNode;
+    /** Slot do fim da barra (ex.: ações e busca). */
+    end?: ReactNode;
+}

package/dist/app-shell/use-focus-trap.d.ts

@@ -0,0 +1,6 @@
+import { KeyboardEvent, RefObject } from 'react';
+/**
+ * Prende o foco dentro de `ref` enquanto `active`: foca o primeiro item ao ativar, faz o Tab dar a
+ * volta e entrega o Escape a `onEscape`. Devolve o `onKeyDown` a ligar no elemento.
+ */
+export declare function useFocusTrap(ref: RefObject<HTMLElement | null>, active: boolean, onEscape?: () => void): (event: KeyboardEvent<HTMLElement>) => void;

package/dist/app-shell/use-media-query.d.ts

@@ -0,0 +1,2 @@
+/** Diz se a media query casa agora e acompanha as mudanças de largura da janela. */
+export declare function useMediaQuery(query: string): boolean;

package/dist/autocomplete/autocomplete.d.ts

@@ -0,0 +1,37 @@
+import { ComponentPropsWithRef } from 'react';
+export interface AutocompleteOption<T extends string | number> {
+    value: T;
+    label: string;
+}
+interface AutocompleteBaseProps<T extends string | number> extends Omit<ComponentPropsWithRef<'input'>, 'value' | 'defaultValue' | 'onChange' | 'onBlur' | 'multiple' | 'type' | 'role' | 'children'> {
+    /** Rótulo visível do campo. */
+    label: string;
+    /** Opções da lista. */
+    options: readonly AutocompleteOption<T>[];
+    /** Texto de ajuda abaixo do campo. */
+    help?: string;
+    /** Mensagem de erro; aparece com `role="alert"` e marca o campo como inválido. */
+    error?: string;
+    /** Chamada quando o campo perde o foco com a lista fechada. */
+    onBlur?: () => void;
+    /** Texto mostrado quando nenhuma opção combina com o que foi digitado; padrão `Nenhuma opção encontrada`. */
+    emptyText?: string;
+    /** Nome da lista de pílulas, só no modo múltiplo; padrão `{label} escolhidas`. */
+    listLabel?: string;
+    /** Nome do "×" de cada pílula, só no modo múltiplo; padrão `Remover {opção}`. */
+    removeLabel?: (label: string) => string;
+}
+export interface AutocompleteSingleProps<T extends string | number> extends AutocompleteBaseProps<T> {
+    multiple?: false;
+    value: T | null;
+    onChange: (value: T | null) => void;
+}
+export interface AutocompleteMultipleProps<T extends string | number> extends AutocompleteBaseProps<T> {
+    multiple: true;
+    value: readonly T[];
+    onChange: (value: T[]) => void;
+}
+export type AutocompleteProps<T extends string | number> = AutocompleteSingleProps<T> | AutocompleteMultipleProps<T>;
+export declare function Autocomplete<T extends string | number>(props: AutocompleteSingleProps<T>): React.JSX.Element;
+export declare function Autocomplete<T extends string | number>(props: AutocompleteMultipleProps<T>): React.JSX.Element;
+export {};

package/dist/badge/badge.d.ts

@@ -0,0 +1,8 @@
+import { ComponentPropsWithRef } from 'react';
+export type BadgeTone = 'neutral' | 'primary' | 'accent' | 'success' | 'warning' | 'danger' | 'info';
+export interface BadgeProps extends ComponentPropsWithRef<'span'> {
+    /** Tom do selo; o fundo é sempre o *Soft do tom e o texto diz o estado, sem depender só da cor. Padrão: primary. */
+    tone?: BadgeTone;
+}
+/** Selo curto de estado ou categoria. */
+export declare function Badge({ tone, className, ...rest }: BadgeProps): import('react').JSX.Element;

package/dist/bottom-sheet/bottom-sheet.constants.d.ts

@@ -0,0 +1,3 @@
+import { BottomSheetLabels } from './bottom-sheet.types';
+export declare const DEFAULT_LABELS: BottomSheetLabels;
+export declare const FOCUSABLE = "button, [href], input, select, textarea, [tabindex]:not([tabindex=\"-1\"])";

package/dist/bottom-sheet/bottom-sheet.d.ts

@@ -0,0 +1,3 @@
+import { BottomSheetProps } from './bottom-sheet.types';
+/** Folha modal sobre o `<dialog>` nativo: embaixo em telas estreitas e na lateral a partir de 720 px. */
+export declare function BottomSheet({ open, onClose, title, description, footer, placement, labels, children, className, ref, ...rest }: BottomSheetProps): import('react').JSX.Element | null;

package/dist/bottom-sheet/bottom-sheet.types.d.ts

@@ -0,0 +1,26 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+/** Posição da folha: `auto` fica embaixo abaixo de 720 px e na lateral a partir daí. */
+export type BottomSheetPlacement = 'auto' | 'bottom' | 'side';
+/** Textos visíveis do `BottomSheet`. */
+export interface BottomSheetLabels {
+    /** Nome acessível do botão de fechar. Padrão: `Fechar`. */
+    close: string;
+}
+export interface BottomSheetProps extends Omit<ComponentPropsWithRef<'dialog'>, 'title' | 'open'> {
+    /** Abre a folha como modal (`showModal()`); ao ficar `false`, fecha e devolve o foco. */
+    open: boolean;
+    /** Chamado no Esc, no clique no fundo e no botão de fechar. */
+    onClose: () => void;
+    /** Título, lido como nome acessível. */
+    title: ReactNode;
+    /** Descrição curta, ligada ao diálogo por `aria-describedby`. */
+    description?: ReactNode;
+    /** Rodapé fixo, fora da rolagem do conteúdo. */
+    footer?: ReactNode;
+    /** Posição da folha. Padrão: `auto`. */
+    placement?: BottomSheetPlacement;
+    /** Sobrescreve os textos padrão. */
+    labels?: Partial<BottomSheetLabels>;
+    /** Conteúdo rolável. */
+    children: ReactNode;
+}

package/dist/bottom-sheet/use-bottom-sheet.d.ts

@@ -0,0 +1,14 @@
+import { KeyboardEvent, MouseEvent, Ref, SyntheticEvent } from 'react';
+interface UseBottomSheetArgs {
+    open: boolean;
+    onClose: () => void;
+    ref?: Ref<HTMLDialogElement>;
+}
+/** Abre o `<dialog>` como modal, prende o Tab e devolve o foco a quem abriu. */
+export declare function useBottomSheet({ open, onClose, ref }: UseBottomSheetArgs): {
+    dialogRef: import('react').RefObject<HTMLDialogElement | null>;
+    onKeyDown: (event: KeyboardEvent<HTMLDialogElement>) => void;
+    onCancel: (event: SyntheticEvent<HTMLDialogElement>) => void;
+    onClick: (event: MouseEvent<HTMLDialogElement>) => void;
+};
+export {};

package/dist/brand-logo/brand-logo.d.ts

@@ -0,0 +1,9 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+export interface BrandLogoProps extends ComponentPropsWithRef<'div'> {
+    /** Nome do produto ao lado da marca, já traduzido por quem usa. */
+    name: string;
+    /** Desenho da marca (SVG ou imagem), mostrado no quadrado em gradiente; é decorativo, o nome é o texto acessível. */
+    mark: ReactNode;
+}
+/** Marca de um produto: quadrado em gradiente com o desenho recebido e o nome em texto com gradiente. */
+export declare function BrandLogo({ name, mark, className, ...rest }: BrandLogoProps): import('react').JSX.Element;

package/dist/button/button.d.ts

@@ -0,0 +1,15 @@
+import { ComponentPropsWithRef } from 'react';
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'muted' | 'success';
+export interface ButtonProps extends ComponentPropsWithRef<'button'> {
+    /** Variação visual. Padrão: `secondary`. */
+    variant?: ButtonVariant;
+    /** Mostra o indicador, anuncia `aria-busy` e bloqueia o clique. */
+    loading?: boolean;
+    /** Cor CSS usada pela variação `muted` (ex.: a cor de uma categoria). */
+    tint?: string;
+    /** `lg`: altura mínima de 48 px. Padrão: `md`. */
+    size?: 'md' | 'lg';
+    /** Ocupa a largura toda do contêiner. */
+    block?: boolean;
+}
+export declare function Button({ variant, loading, tint, size, block, type, disabled, className, style, children, ...rest }: ButtonProps): import('react').JSX.Element;

package/dist/calendar/calendar.d.ts

@@ -0,0 +1,28 @@
+import { ComponentPropsWithRef } from 'react';
+export interface CalendarValue {
+    /** `YYYY-MM-DD` ou `''`. */
+    from: string;
+    to?: string;
+}
+export interface CalendarLabels {
+    previous: string;
+    next: string;
+    /** Sufixo do dia atual no nome acessível ("hoje"). */
+    today: string;
+}
+export interface CalendarProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'defaultValue'> {
+    /** `single` escolhe um dia; `range` escolhe um intervalo com dois cliques. */
+    mode: 'single' | 'range';
+    /** Mês exibido, `YYYY-MM`. */
+    month: string;
+    onMonthChange: (month: string) => void;
+    value: CalendarValue;
+    onChange: (value: CalendarValue) => void;
+    /** Dia atual, `YYYY-MM-DD`. */
+    today: string;
+    /** Locale das datas e dos nomes de mês e dia. Padrão: `pt-BR`. */
+    locale?: string;
+    /** Textos do calendário; o que faltar usa o padrão em pt-br, qualquer que seja o `locale`. */
+    labels?: Partial<CalendarLabels>;
+}
+export declare function Calendar({ mode, month, onMonthChange, value, onChange, today, locale, labels, className, ref, ...rest }: CalendarProps): import('react').JSX.Element;

package/dist/callout/callout.constants.d.ts

@@ -0,0 +1,4 @@
+import { InfoIcon } from '../icons/interface-icons';
+import { CalloutTone } from './callout.types';
+/** Ícone padrão de cada tom. */
+export declare const TONE_ICONS: Record<CalloutTone, typeof InfoIcon>;

package/dist/callout/callout.d.ts

@@ -0,0 +1,3 @@
+import { CalloutProps } from './callout.types';
+/** Aviso fixo na página, com tom, ícone, ação e região viva opcional. */
+export declare function Callout({ tone, title, icon, action, live, className, role, children, ...rest }: CalloutProps): import('react').JSX.Element;

package/dist/callout/callout.types.d.ts

@@ -0,0 +1,14 @@
+import { ComponentPropsWithRef, ReactNode } from 'react';
+export type CalloutTone = 'neutral' | 'accent' | 'info' | 'success' | 'warning' | 'danger';
+export interface CalloutProps extends Omit<ComponentPropsWithRef<'aside'>, 'title'> {
+    /** Tom do aviso, que define o fundo, a cor e o ícone. Padrão: `neutral`. */
+    tone?: CalloutTone;
+    /** Título do aviso; também dá o nome acessível ao `<aside>`. */
+    title?: ReactNode;
+    /** Ícone no lugar do padrão do tom; `false` remove o ícone. */
+    icon?: ReactNode | false;
+    /** Ação no fim do aviso, como um botão ou um link. */
+    action?: ReactNode;
+    /** `polite` anuncia o aviso como região viva (`role="status"`). Padrão: `off`. */
+    live?: 'off' | 'polite';
+}

package/dist/card/card.d.ts

@@ -0,0 +1,9 @@
+import { ComponentPropsWithRef } from 'react';
+export type CardTone = 'default' | 'primary' | 'accent' | 'success' | 'warning' | 'danger' | 'info';
+export interface CardProps extends ComponentPropsWithRef<'div'> {
+    /** Elemento HTML da raiz. Padrão: `div`. */
+    as?: 'div' | 'section' | 'article';
+    /** Tom do fundo e da borda. Padrão: `default`. */
+    tone?: CardTone;
+}
+export declare function Card({ as: Tag, tone, className, ...rest }: CardProps): import('react').JSX.Element;

package/dist/card-link/card-button.d.ts

@@ -0,0 +1,3 @@
+import { CardButtonProps } from './card-link.types';
+export type { CardButtonProps } from './card-link.types';
+export declare function CardButton({ tone, type, className, ...rest }: CardButtonProps): import('react').JSX.Element;

package/dist/card-link/card-link.d.ts

@@ -0,0 +1,3 @@
+import { CardLinkProps } from './card-link.types';
+export type { CardLinkProps } from './card-link.types';
+export declare function CardLink({ tone, className, children, ...rest }: CardLinkProps): import('react').JSX.Element;

package/dist/card-link/card-link.types.d.ts

@@ -0,0 +1,10 @@
+import { ComponentPropsWithRef } from 'react';
+import { CardTone } from '../card/card';
+export interface CardLinkProps extends ComponentPropsWithRef<'a'> {
+    /** Tom do fundo e da borda, o mesmo do `Card`. Padrão: `default`. */
+    tone?: CardTone;
+}
+export interface CardButtonProps extends ComponentPropsWithRef<'button'> {
+    /** Tom do fundo e da borda, o mesmo do `Card`. Padrão: `default`. */
+    tone?: CardTone;
+}

package/dist/checkbox/checkbox.d.ts

@@ -0,0 +1,6 @@
+import { ComponentPropsWithRef } from 'react';
+export interface CheckboxProps extends Omit<ComponentPropsWithRef<'input'>, 'type'> {
+    /** Rótulo visível ao lado da caixa. */
+    label: string;
+}
+export declare function Checkbox({ label, id, className, style, ...rest }: CheckboxProps): import('react').JSX.Element;

package/dist/color-field/color-field.d.ts

@@ -0,0 +1,20 @@
+import { ComponentPropsWithRef } from 'react';
+import { ColorFieldLabels } from './color-picker';
+export type { ColorFieldLabels } from './color-picker';
+export interface ColorFieldProps extends Omit<ComponentPropsWithRef<'button'>, 'value' | 'defaultValue' | 'onChange' | 'onBlur' | 'children' | 'type'> {
+    /** Rótulo visível do campo. */
+    label: string;
+    /** HEX atual. */
+    value: string;
+    /** Chamado com o HEX `#RRGGBB` ao aplicar. */
+    onChange: (hex: string) => void;
+    /** Chamado quando o diálogo fecha. */
+    onBlur?: () => void;
+    /** Textos do campo e do seletor; os que faltarem usam o padrão em pt-br. */
+    labels?: Partial<ColorFieldLabels>;
+    /** Mensagem de erro, anunciada com `role="alert"`. */
+    error?: string;
+    /** Texto de ajuda sob o campo. */
+    help?: string;
+}
+export declare function ColorField({ label, value, onChange, onBlur, labels, error, help, id, className, style, ref, 'aria-describedby': ariaDescribedBy, 'aria-invalid': ariaInvalid, ...rest }: ColorFieldProps): import('react').JSX.Element;

package/dist/color-field/color-picker.d.ts

@@ -0,0 +1,42 @@
+import { ComponentPropsWithRef } from 'react';
+/** Textos do campo de cor e do seletor. */
+export interface ColorFieldLabels {
+    /** Título do diálogo. */
+    title: string;
+    /** Rótulo do controle de luminosidade. */
+    lightness: string;
+    /** Rótulo do campo HEX. */
+    hex: string;
+    /** Legenda do grupo RGB. */
+    rgb: string;
+    /** Rótulo do canal vermelho. */
+    red: string;
+    /** Rótulo do canal verde. */
+    green: string;
+    /** Rótulo do canal azul. */
+    blue: string;
+    /** Legenda do grupo HSL. */
+    hsl: string;
+    /** Rótulo do matiz. */
+    hue: string;
+    /** Rótulo da saturação. */
+    saturation: string;
+    /** Texto do botão que cancela. */
+    cancel: string;
+    /** Texto do botão que aplica. */
+    apply: string;
+    /** Nome da roda de matiz e saturação. */
+    wheel: string;
+    /** Texto do valor da roda para leitores de tela. */
+    wheelValue: (hue: number, saturation: number) => string;
+}
+export declare const DEFAULT_COLOR_FIELD_LABELS: ColorFieldLabels;
+export interface ColorPickerProps extends Omit<ComponentPropsWithRef<'div'>, 'onChange' | 'children' | 'defaultValue'> {
+    /** Cor inicial (HEX); o seletor guarda o próprio estado depois disso. */
+    value: string;
+    /** Chamado com o HEX `#RRGGBB` a cada mudança. */
+    onChange: (hex: string) => void;
+    /** Textos do seletor; os que faltarem usam o padrão em pt-br. */
+    labels?: Partial<ColorFieldLabels>;
+}
+export declare function ColorPicker({ value, onChange, labels, className, style, ...rest }: ColorPickerProps): import('react').JSX.Element;

package/dist/color-field/color.d.ts

@@ -0,0 +1,11 @@
+export type Rgb = [number, number, number];
+/** Limita `value` ao intervalo de `min` a `max`. */
+export declare function clamp(value: number, min: number, max: number): number;
+/** Converte HSL (matiz, saturação e luminosidade) em RGB (0 a 255 por canal). */
+export declare function hslToRgb(h: number, s: number, l: number): Rgb;
+/** Converte RGB (0 a 255 por canal) em HSL (matiz, saturação e luminosidade). */
+export declare function rgbToHsl(r: number, g: number, b: number): Rgb;
+/** Converte os canais RGB em `#RRGGBB` maiúsculo. */
+export declare function rgbToHex(rgb: readonly number[]): string;
+/** Aceita 3 ou 6 dígitos, com ou sem `#`; `null` se inválido. */
+export declare function hexToRgb(hex: string): Rgb | null;

package/dist/confirm-dialog/confirm-dialog.d.ts

@@ -0,0 +1,15 @@
+import { DialogProps } from '../dialog/dialog';
+export interface ConfirmDialogProps extends Omit<DialogProps, 'children' | 'actions' | 'role' | 'onClose'> {
+    /** Texto explicativo do corpo, lido como descrição do diálogo. */
+    description: string;
+    /** Rótulo do botão de confirmar. Padrão: `Confirmar`. */
+    confirmLabel?: string;
+    /** Rótulo do botão de cancelar. Padrão: `Cancelar`. */
+    cancelLabel?: string;
+    /** Chamado ao confirmar. */
+    onConfirm: () => void;
+    /** Chamado ao cancelar ou ao apertar Esc. */
+    onCancel: () => void;
+}
+/** Confirmação simples, montada sobre o `Dialog`. */
+export declare function ConfirmDialog({ description, confirmLabel, cancelLabel, onConfirm, onCancel, ...rest }: ConfirmDialogProps): import('react').JSX.Element;