@softize/opus 23.0.0 → 24.0.1

package/src/ui/index.ts

@@ -5,7 +5,10 @@
  * Aqui ficam apenas types/contratos compartilhados.
  */
 
-import type { ActionError, Paginated } from '../core/index.ts'
+import type { ActionError, Paginated } from "../core/index.ts";
+
+// Personalização de aparência (ADR 0044): sem React, também disponível em `./ui/appearance`.
+export * from "./appearance.ts";
 
 /**
  * Metadado de descoberta de um componente — cada componente co-localiza um `meta`
@@ -13,18 +16,18 @@ import type { ActionError, Paginated } from '../core/index.ts'
  */
 export interface ComponentMeta {
   /** Nome canônico (kebab), ex.: 'button', 'dropdown-menu'. */
-  name: string
+  name: string;
   /** Origem: descendente do shadcn (forkado) ou nativo do Opus. */
-  ancestry: 'shadcn' | 'opus'
+  ancestry: "shadcn" | "opus";
   /** Quando usar / quando não — guia o agente de design a escolher certo. */
-  whenToUse: string
+  whenToUse: string;
   /** Aviso de retirada no catálogo, com o caminho de migração. */
   deprecated?: {
     /** Alternativa recomendada; aceita `código` inline como `whenToUse`. */
-    alternative: string
+    alternative: string;
     /** Versão em que a retirada começou, quando houver. */
-    since?: string
-  }
+    since?: string;
+  };
 }
 
 /**
@@ -32,23 +35,23 @@ export interface ComponentMeta {
  * shape derivado disto.
  */
 export interface ActionState<TData> {
-  data: TData | undefined
-  error: ActionError | undefined
-  isIdle: boolean
-  isLoading: boolean
-  isSuccess: boolean
-  isError: boolean
+  data: TData | undefined;
+  error: ActionError | undefined;
+  isIdle: boolean;
+  isLoading: boolean;
+  isSuccess: boolean;
+  isError: boolean;
 }
 
 export interface ListState<TItem> {
-  items: TItem[]
-  cursor: { next: string | null; prev?: string | null }
-  total: number | undefined
-  error: ActionError | undefined
-  isIdle: boolean
-  isLoading: boolean
-  isSuccess: boolean
-  isError: boolean
+  items: TItem[];
+  cursor: { next: string | null; prev?: string | null };
+  total: number | undefined;
+  error: ActionError | undefined;
+  isIdle: boolean;
+  isLoading: boolean;
+  isSuccess: boolean;
+  isError: boolean;
 }
 
 /**
@@ -62,7 +65,7 @@ export function idleAction<T>(): ActionState<T> {
     isLoading: false,
     isSuccess: false,
     isError: false,
-  }
+  };
 }
 
 export function idleLookup<T>(): ListState<T> {
@@ -75,7 +78,7 @@ export function idleLookup<T>(): ListState<T> {
     isLoading: false,
     isSuccess: false,
     isError: false,
-  }
+  };
 }
 
 /**
@@ -83,10 +86,10 @@ export function idleLookup<T>(): ListState<T> {
  */
 export function isPaginated(value: unknown): value is Paginated<unknown> {
   return (
-    typeof value === 'object' &&
+    typeof value === "object" &&
     value !== null &&
-    'items' in value &&
+    "items" in value &&
     Array.isArray((value as { items: unknown }).items) &&
-    'cursor' in value
-  )
+    "cursor" in value
+  );
 }

package/src/ui/meta.ts

@@ -11,11 +11,11 @@ import type { ComponentMeta } from "./index.ts";
 
 /** Todos os metas, chaveados pelo nome canônico (kebab). Fonte única — zero duplicação. */
 export const componentMeta = {
-  content: {
-    name: "content",
+  surface: {
+    name: "surface",
     ancestry: "opus",
     whenToUse:
-      "Organize uma região nomeada dentro de uma página ou de outra superfície. Use as propriedades de Content no caso comum e componha seus slots quando precisar controlar a estrutura. Numa página centrada em uma coleção, `level={1}` faz do Content o heading principal; nas demais, ele vem de PageTitle.",
+      'Delimite e nomeie um trecho da tela: uma região da página, um grupo de campos, um registro, um item de grade ou um bloco clicável. `as` escolhe o elemento (`div`, `section`, `article` ou `fieldset`) e `asChild` entrega a superfície a um botão ou link. `framed` acrescenta a moldura, `elevation="raised"` dá fundo próprio e `layout` escolhe entre ritmo contínuo e faixas com divisores. No caso comum, declare `title`, `description`, `count`, `actions` e `media` na própria Surface; componha SurfaceHeader, SurfaceBody e SurfaceFooter quando precisar controlar a estrutura. Numa página centrada em uma coleção, `level={1}` faz da Surface o heading principal; nas demais, ele vem de PageTitle. Para um modal use Dialog, para um painel lateral use Drawer e para uma coluna de layout use Pane.',
   },
   ask: {
     name: "ask",
@@ -77,17 +77,11 @@ export const componentMeta = {
     whenToUse:
       "Inicie uma ação com um controle clicável. Use `context` para o significado, `variant` para o tratamento visual e `size` para a escala compartilhada (`xs`…`lg` e os quadrados `icon-*`); `icon` recebe um nó e `busy` comunica o andamento e impede um novo acionamento. Para ações relacionadas, use ButtonGroup conectado, espaçado ou dividido.",
   },
-  card: {
-    name: "card",
-    ancestry: "shadcn",
-    whenToUse:
-      "Agrupe conteúdo relacionado em uma superfície delimitada. Use Card diretamente para um bloco simples ou componha cabeçalho, corpo e rodapé quando houver hierarquia e ações. CardContent permanece apenas como alias temporário de compatibilidade.",
-  },
   "metric-card": {
     name: "metric-card",
     ancestry: "opus",
     whenToUse:
-      "Apresente uma medida resumida, como um total ou uma contagem, com rótulo, valor em destaque e descrição opcional. O consumidor calcula e formata os valores. Use `secondaryMetric` para uma segunda leitura da mesma dimensão, exibida como lâmina posterior com rótulo próprio; `context` realça somente o ícone, `action` acrescenta uma ação diretamente relacionada e `loading` substitui rótulo e valor durante a carga. Com `onActivate`, `active` e `activationLabel`, informados juntos, o card vira um controle que aplica o recorte que a medida resume e expõe o estado por `aria-pressed`. Para conteúdo geral ou estrutura livre, use Card.",
+      "Apresente uma medida resumida, como um total ou uma contagem, com rótulo, valor em destaque e descrição opcional. O consumidor calcula e formata os valores. Use `secondaryMetric` para uma segunda leitura da mesma dimensão, exibida como lâmina posterior com rótulo próprio; `context` realça somente o ícone, `action` acrescenta uma ação diretamente relacionada e `loading` substitui rótulo e valor durante a carga. Com `onActivate`, `active` e `activationLabel`, informados juntos, o card vira um controle que aplica o recorte que a medida resume e expõe o estado por `aria-pressed`. Para conteúdo geral ou estrutura livre, use Surface.",
   },
   chat: {
     name: "chat",
@@ -119,12 +113,6 @@ export const componentMeta = {
     whenToUse:
       "Receba texto para envio sem montar uma conversa completa. Enter envia, Shift+Enter quebra a linha e `actions` acrescenta uma faixa para seletores relacionados. O componente é controlado; use Chat quando também precisar de mensagens e estado da conversa.",
   },
-  "content-header": {
-    name: "content-header",
-    ancestry: "opus",
-    whenToUse:
-      'Estruture uma região com título e corpo. No caso comum, declare título, mídia, descrição, contador e ações diretamente em Content; use `framed` quando a região precisar de limite próprio, `layout="sectioned"` quando o filho controlar o recuo do body, `frameVariant="legend"` para integrar visualmente o header à borda e `as="fieldset"` somente para agrupar campos sob uma legenda nativa. Componha ContentHeader apenas quando precisar controlar a anatomia.',
-  },
   copyable: {
     name: "copyable",
     ancestry: "opus",
@@ -177,7 +165,7 @@ export const componentMeta = {
     name: "separator",
     ancestry: "shadcn",
     whenToUse:
-      'Marque a fronteira entre blocos de conteúdo que não pertencem a uma superfície com regiões. A linha horizontal fica entre blocos empilhados; com `orientation="vertical"`, ela separa itens lado a lado e herda a altura do contêiner. A linha é decorativa por padrão e fica fora da árvore de acessibilidade; use `decorative={false}` quando a divisão tiver significado. Não use Separator entre cabeçalho, corpo e rodapé de Card, Dialog ou Drawer: nessas superfícies, os divisores são derivados das regiões com `layout="sectioned"`.',
+      'Marque a fronteira entre blocos de conteúdo que não pertencem a uma superfície com regiões. A linha horizontal fica entre blocos empilhados; com `orientation="vertical"`, ela separa itens lado a lado e herda a altura do contêiner. A linha é decorativa por padrão e fica fora da árvore de acessibilidade; use `decorative={false}` quando a divisão tiver significado. Não use Separator entre cabeçalho, corpo e rodapé de Surface, Dialog ou Drawer: nessas superfícies, os divisores são derivados das regiões com `layout="sectioned"`.',
   },
   skeleton: {
     name: "skeleton",
@@ -201,7 +189,7 @@ export const componentMeta = {
     name: "tabs",
     ancestry: "shadcn",
     whenToUse:
-      'Navegue entre painéis relacionados no mesmo nível. Cada TabsListItem aponta para um TabsPanel pelo mesmo `value`; TabsList usa uma linha para indicar a aba ativa, enquanto Tabs define orientação, escala, distribuição e moldura. Use ToggleGroup para escolher valores sem navegar entre painéis.',
+      "Navegue entre painéis relacionados no mesmo nível. Cada TabsListItem aponta para um TabsPanel pelo mesmo `value`; TabsList usa uma linha para indicar a aba ativa, enquanto Tabs define orientação, escala, distribuição e moldura. Use ToggleGroup para escolher valores sem navegar entre painéis.",
   },
   textarea: {
     name: "textarea",
@@ -285,7 +273,7 @@ export const componentMeta = {
     name: "field",
     ancestry: "shadcn",
     whenToUse:
-      'Componha rótulo, controle, ajuda e erro com espaçamento consistente. Use a orientação vertical no caso comum e a horizontal quando controle e texto precisarem ficar lado a lado. FieldGroup organiza vários campos; quando o conjunto precisar de título, componha-o dentro de Content com `as="fieldset"`.',
+      'Componha rótulo, controle, ajuda e erro com espaçamento consistente. Use a orientação vertical no caso comum e a horizontal quando controle e texto precisarem ficar lado a lado. FieldGroup organiza vários campos; quando o conjunto precisar de título, componha-o dentro de Surface com `as="fieldset"`.',
   },
   "input-otp": {
     name: "input-otp",
@@ -327,19 +315,19 @@ export const componentMeta = {
     name: "split",
     ancestry: "opus",
     whenToUse:
-      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial e mínimo; a anatomia do pane tem página própria. SurfaceAssistant especializa esse layout para assistência contextual dentro de Page, Dialog ou Drawer.",
+      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara apenas dimensão e crescimento; o filho compõe apresentação e rolagem. SurfaceAssistant especializa esse layout para assistência contextual dentro de Page, Dialog ou Drawer.",
   },
   sidebar: {
     name: "sidebar",
     ancestry: "opus",
     whenToUse:
-      "Organize navegação global ou contextual em uma coluna lateral. Split e Pane definem posição e largura; Sidebar fornece a superfície e o colapso. Use SidebarNav para grupos planos e componha árvores com SidebarItem e SidebarTreeGroup; cabeçalho e rodapé próprios são do Pane que a hospeda.",
+      "Organize navegação global ou contextual em uma coluna lateral. Split e Pane definem posição e largura; Sidebar fornece a coluna e o colapso. Use SidebarNav para grupos planos e componha árvores com SidebarItem e SidebarTreeGroup; quando precisar de header, body ou footer visuais, envolva a Sidebar com Surface.",
   },
   pane: {
     name: "pane",
     ancestry: "opus",
     whenToUse:
-      "Estruture a coluna ou faixa encaixada em um Split. PaneHeader nomeia a região e acomoda mídia e ações; ao lado desses slots, também aceita conteúdo livre, como uma busca ou a marca de uma barra lateral. PaneBody rola e PaneFooter mantém à vista o que não pode sair da tela. `layout` escolhe entre regiões seccionadas, com divisores derivados da vizinhança, e o fluxo contínuo. `inset` vale para o pane sem slots; com eles, o recuo pertence a cada região.",
+      "Declare o tamanho de uma região dentro de Split. Pane cuida somente de dimensão, limites e crescimento; o filho decide superfície, organização e rolagem. Use Surface quando a região precisar de header, body, footer, borda ou elevação, e Sidebar quando ela for uma navegação lateral.",
   },
   "scroll-area": {
     name: "scroll-area",
@@ -363,7 +351,7 @@ export const componentMeta = {
     name: "toggle",
     ancestry: "shadcn",
     whenToUse:
-      'Alterne um estado diretamente no contexto atual. ToggleGroup reúne escolhas únicas ou múltiplas e compartilha aparência e escala entre os itens. Use `variant="outline"` com `spacing={0}` para formar um grupo conectado com borda. Para navegar entre painéis, use Tabs.',
+      'Alterne um estado diretamente no contexto atual. ToggleGroup reúne escolhas únicas ou múltiplas com a mesma gramática estrutural de ButtonGroup; `mode="segmented"` mantém alternativas curtas visíveis numa superfície compartilhada, enquanto `variant` trata cada Toggle. Para navegar entre painéis, use Tabs.',
   },
 
   confirm: {
@@ -388,13 +376,13 @@ export const componentMeta = {
     name: "action-form-card",
     ancestry: "opus",
     whenToUse:
-      "Apresente uma FormAction como seção delimitada da página. ActionFormCard combina a estrutura do Card com o comportamento de ActionForm. Para um modal, use ActionFormDialog; sem superfície adicional, use ActionForm.",
+      "Apresente uma FormAction como seção delimitada da página. ActionFormCard combina a estrutura de uma Surface elevada com o comportamento de ActionForm. Para um modal, use ActionFormDialog; sem superfície adicional, use ActionForm.",
   },
   "action-list": {
     name: "action-list",
     ancestry: "opus",
     whenToUse:
-      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período e busca; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. A tabela derivada não cria moldura própria. Em uma página, envolva a lista com Content para manter título e criação junto da coleção. Para um único recurso, use ActionView.",
+      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período e busca; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. A tabela derivada não cria moldura própria. Em uma página, envolva a lista com Surface para manter título e criação junto da coleção. Para um único recurso, use ActionView.",
   },
   "action-trigger": {
     name: "action-trigger",
@@ -412,13 +400,13 @@ export const componentMeta = {
     name: "page",
     ancestry: "opus",
     whenToUse:
-      "Estruture uma página com cabeçalho, estado e conteúdo na mesma anatomia. Page renderiza o `<main>` com um container centralizado de até 80rem (`max-w-7xl`); PageHeader reúne navegação contextual opcional, título e ações, enquanto PageBody recebe o conteúdo. PageShell pode fornecer navegação e ações conhecidas pela aplicação sem criar uma barra visual. Uma região interna pode fornecer o heading principal com Content. PageActionsTarget fica restrito a workspaces imersivos. PageState substitui o header e o conteúdo durante carregamento, falha ou ausência, por isso informações indispensáveis entram no corpo, como Alert ou texto. Para uma falha parcial, mantenha o estado na seção com DataState; para uma região disponível para criação ou vínculo, use Empty.",
+      "Estruture uma página com cabeçalho, estado e conteúdo na mesma anatomia. Page renderiza o `<main>` com um container centralizado de até 80rem (`max-w-7xl`); PageHeader reúne navegação contextual opcional, título e ações, enquanto PageBody recebe o conteúdo. PageShell pode fornecer navegação e ações conhecidas pela aplicação sem criar uma barra visual. Uma região interna pode fornecer o heading principal com `Surface level={1}`. PageActionsTarget fica restrito a workspaces imersivos. PageState substitui o header e o conteúdo durante carregamento, falha ou ausência, por isso informações indispensáveis entram no corpo, como Alert ou texto. Para uma falha parcial, mantenha o estado na seção com DataState; para uma região disponível para criação ou vínculo, use Empty.",
   },
   presentation: {
     name: "presentation",
     ancestry: "opus",
     whenToUse:
-      "Descreva um recurso que precisa manter a mesma anatomia ao aparecer como Page, Dialog ou Drawer. Presentation organiza navegação, título, ações de cabeçalho, body e ações de rodapé sem redefinir o conteúdo para cada superfície. Em Page de listagem, Content mantém título e ações junto do ActionList; modais usam o header da superfície. Route pode declarar URL, surface e origem do registro para deep links. A definição persistente liga esses slots a actions Opus; a invocação carrega o estado JSON da execução. PresentationInspector abre um snapshot isolado, enquanto a Lens apresenta o inventário estático projetado no manifest.",
+      "Descreva um recurso que precisa manter a mesma anatomia ao aparecer como Page, Dialog ou Drawer. Presentation organiza navegação, título, ações de cabeçalho, body e ações de rodapé sem redefinir o conteúdo para cada superfície. Em Page de listagem, Surface mantém título e ações junto do ActionList; modais usam o header da superfície. Route pode declarar URL, surface e origem do registro para deep links. A definição persistente liga esses slots a actions Opus; a invocação carrega o estado JSON da execução. PresentationInspector abre um snapshot isolado, enquanto a Lens apresenta o inventário estático projetado no manifest.",
   },
   router: {
     name: "router",

package/src/ui/react.tsx

@@ -10,6 +10,9 @@ export * from "./drivers/react.tsx";
 // Utilitário
 export { cn } from "./lib/cn.ts";
 
+// Personalização de aparência (ADR 0044): o mesmo módulo sem React de `./ui/appearance`.
+export * from "./appearance.ts";
+
 // Primitivos
 export { Button, buttonVariants } from "./components/primitives/button.tsx";
 export type {
@@ -90,18 +93,6 @@ export type {
   DetailGroupVariant,
 } from "./components/primitives/detail.tsx";
 
-export {
-  Card,
-  CardHeader,
-  CardMedia,
-  CardTitle,
-  CardDescription,
-  CardAction,
-  CardBody,
-  CardContent,
-  CardFooter,
-} from "./components/primitives/card.tsx";
-
 export { MetricCard } from "./components/primitives/metric-card.tsx";
 export type {
   MetricCardProps,
@@ -136,6 +127,8 @@ export {
   DialogNavigation,
   DialogMedia,
   DialogActions,
+  DialogIntro,
+  DialogIntroActions,
   DialogBody,
   DialogFooter,
   DialogTitle,
@@ -146,7 +139,7 @@ export type {
   DialogMode,
 } from "./components/primitives/dialog.tsx";
 
-// O pacote de anatomia que Card, Dialog, Drawer e Pane declaram no root (ADR 0023). As
+// O pacote de anatomia que Surface, Dialog, Drawer e Pane declaram no root (ADR 0023). As
 // tabelas e o contexto continuam internos; o consumidor escolhe entre os dois nomes.
 export type { SurfaceLayout } from "./components/patterns/surface-anatomy.ts";
 
@@ -278,6 +271,8 @@ export {
 export {
   Drawer,
   DrawerActions,
+  DrawerIntro,
+  DrawerIntroActions,
   DrawerClose,
   DrawerContent,
   DrawerFooter,
@@ -372,10 +367,16 @@ export {
 export { ScrollArea, ScrollBar } from "./components/primitives/scroll-area.tsx";
 export { Slider } from "./components/primitives/slider.tsx";
 export { Switch } from "./components/primitives/switch.tsx";
-export { Toggle, toggleVariants } from "./components/primitives/toggle.tsx";
+export {
+  Toggle,
+  type ToggleProps,
+  toggleVariants,
+} from "./components/primitives/toggle.tsx";
 export {
   ToggleGroup,
-  ToggleGroupItem,
+  type ToggleGroupDistribution,
+  type ToggleGroupMode,
+  type ToggleGroupProps,
 } from "./components/primitives/toggle-group.tsx";
 export { Truncate } from "./components/primitives/truncate.tsx";
 export type { TruncateProps } from "./components/primitives/truncate.tsx";
@@ -482,26 +483,30 @@ export type {
   PageStateStatus,
 } from "./components/patterns/page-state.tsx";
 
-// Região de conteúdo composta; shorthand e slots explícitos compartilham a mesma anatomia.
-export {
-  Content,
-  ContentHeader,
-  ContentMedia,
-  ContentTitle,
-  ContentDescription,
-  ContentMeta,
-  ContentActions,
-  ContentBody,
-} from "./components/patterns/content-header.tsx";
+// Superfície: região de página, grupo de campos, entidade, item ou bloco clicável. A
+// semântica vem de `as`/`asChild`; forma curta e slots compartilham a anatomia (ADR 0045).
+export {
+  Surface,
+  SurfaceHeader,
+  SurfaceMedia,
+  SurfaceTitle,
+  SurfaceDescription,
+  SurfaceMeta,
+  SurfaceActions,
+  SurfaceBody,
+  SurfaceFooter,
+} from "./components/patterns/surface.tsx";
 export type {
-  ContentProps,
-  ContentHeaderProps,
-  ContentElement,
-  ContentFrameVariant,
-  ContentHeaderLevel,
-} from "./components/patterns/content-header.tsx";
-
-// Layout composicional: Split decide a relação espacial; Pane carrega conteúdo com inset.
+  SurfaceProps,
+  SurfaceHeaderProps,
+  SurfaceMediaProps,
+  SurfaceBodyProps,
+  SurfaceElement,
+  SurfaceElevation,
+} from "./components/patterns/surface.tsx";
+export type { HeadingLevel } from "./components/patterns/heading-level.ts";
+
+// Layout composicional: Split decide a relação espacial; Pane declara somente dimensão.
 export { Split, Pane } from "./components/patterns/split.tsx";
 export type {
   SplitProps,
@@ -529,16 +534,8 @@ export type {
   SurfaceStatusContext,
 } from "./components/patterns/dock.tsx";
 
-// Barra lateral composicional: header/conteúdo/footer e navegação, sem possuir o layout.
+// Barra lateral composicional e navegação, sem possuir o layout.
 export {
-  PaneActions,
-  PaneDescription,
-  PaneHeader,
-  PaneMedia,
-  PaneTitle,
-  PaneBody,
-  PaneContent,
-  PaneFooter,
   Sidebar,
   SidebarItem,
   SidebarGroupLabel,