@softize/opus 27.1.0 → 28.0.0

package/src/ui/docs/content/compositions.md

@@ -24,8 +24,8 @@ Cada família dá um nome próprio a cada região. A tabela mostra a correspond
 | Navegação            | `PageNavigation` ou `PageBack`              | `DialogNavigation`            | `DrawerNavigation`            | Não existe                    |
 | Título no cabeçalho  | `PageTitle`                                 | `DialogTitle`                 | `DrawerTitle`                 | `SurfaceTitle`                |
 | Ações do cabeçalho   | `PageActions`                               | `DialogActions`               | `DrawerActions`               | `SurfaceActions`              |
-| Intro                | `Surface level={1}` no início do `PageBody` | `DialogIntro`                 | `DrawerIntro`                 | Não existe                    |
-| Ações da intro       | Ações da `Surface level={1}`                | `DialogIntroActions`          | `DrawerIntroActions`          | Não existe                    |
+| Intro                | `PageIntro` no início do `PageBody` | `DialogIntro`                 | `DrawerIntro`                 | Não existe                    |
+| Ações da intro       | `PageIntroActions`                | `DialogIntroActions`          | `DrawerIntroActions`          | Não existe                    |
 | Corpo                | `PageBody`                                  | `DialogBody`                  | `DrawerBody`                  | `SurfaceBody`                 |
 | Rodapé               | `PageFooter`                                | `DialogFooter`                | `DrawerFooter`                | `SurfaceFooter`               |
 | Divisores            | Antes do `PageFooter`                       | `sectioned` (padrão)          | `sectioned` (padrão)          | `sectioned`                   |
@@ -97,7 +97,7 @@ function DialogWithIntro({ layout, label }) {
       <DialogContent layout={layout}>
         <DialogHeader>
           <DialogActions>
-            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
               <MessageCircle />
             </Button>
           </DialogActions>
@@ -142,7 +142,7 @@ function CompactDialog({ layout, label }) {
             <Button variant="outline" size="sm">
               Ver histórico
             </Button>
-            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
               <MessageCircle />
             </Button>
           </DialogActions>
@@ -197,7 +197,7 @@ function OrderField() {
 function CollapseButton() {
   return (
     <DrawerClose asChild>
-      <Button variant="ghost" size="icon" aria-label="Recolher painel">
+      <Button variant="ghost" size="icon-sm" aria-label="Recolher painel">
         <ChevronsRight />
       </Button>
     </DrawerClose>
@@ -216,7 +216,7 @@ function DrawerWithIntro({ layout, label }) {
             <CollapseButton />
           </DrawerNavigation>
           <DrawerActions>
-            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
               <MessageCircle />
             </Button>
           </DrawerActions>
@@ -261,7 +261,7 @@ function CompactDrawer({ layout, label }) {
             <Button variant="outline" size="sm">
               Ver histórico
             </Button>
-            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
               <MessageCircle />
             </Button>
           </DrawerActions>
@@ -300,8 +300,8 @@ painel.
 
 ## Page
 
-A `Page` não tem um slot de intro. Com intro, o `PageHeader` guarda a navegação e as ações da
-página, e uma `Surface level={1}` abre o `PageBody` com o título e as ações do conteúdo. A página
+Na composição com intro, o `PageHeader` guarda a navegação e as ações da
+página, e uma `PageIntro` abre o `PageBody` com o título e as ações do conteúdo. A página
 precisa de exatamente um heading principal, por isso o `PageHeader` dessa composição não leva
 `PageTitle`.
 
@@ -322,27 +322,20 @@ render(
           </Breadcrumb>
         </PageNavigation>
         <PageActions>
-          <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+          <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
             <MessageCircle />
           </Button>
         </PageActions>
       </PageHeader>
       <PageBody>
-        <Surface
-          as="section"
-          level={1}
-          title="Editar ordem de serviço"
-          actions={
-            <Button variant="outline" size="sm">
-              Ver histórico
-            </Button>
-          }
-        >
+        <PageIntro>
+          <PageTitle>Editar ordem de serviço</PageTitle>
+          <PageIntroActions><Button variant="outline" size="sm">Ver histórico</Button></PageIntroActions>
+        </PageIntro>
           <div className="space-y-2">
             <Label htmlFor="page-intro-owner">Responsável</Label>
             <Input id="page-intro-owner" defaultValue="Marina Alves" />
           </div>
-        </Surface>
       </PageBody>
       <PageFooter>
         <ButtonGroup mode="spaced">
@@ -380,7 +373,7 @@ render(
           <Button variant="outline" size="sm">
             Ver histórico
           </Button>
-          <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+          <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
             <MessageCircle />
           </Button>
         </PageActions>
@@ -449,7 +442,7 @@ render(
               <Button variant="outline" size="sm">
                 Ver histórico
               </Button>
-              <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+              <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
                 <MessageCircle />
               </Button>
             </SurfaceActions>
@@ -477,3 +470,22 @@ Os dois panes recebem conteúdos diferentes sem mudar de componente: o primeiro
 [`Sidebar`](/ui/sidebar), que já tem anatomia própria, e o segundo, uma `Surface` completa. A
 rolagem também pertence ao conteúdo: a `Surface` ocupa a altura do pane com `flex h-full flex-col`,
 e o `SurfaceBody` declara `min-h-0 flex-1 overflow-y-auto` para rolar entre o cabeçalho e o rodapé.
+
+## Ritmo entre regiões e blocos
+
+Surface (incluindo cards e seções), Page, Dialog, Drawer e Tabs organizam o conteúdo
+com intervalos de `1rem`. Os bodies separam seus blocos diretos; grupos internos podem
+ter densidade própria. DetailGroup e Separator não criam margens externas.
+
+Sem delimitação, Surface e Tabs não adicionam padding inferior. Uma Surface com moldura
+ou elevação, assim como Dialog e Drawer, reserva `1rem` até a borda. No layout contínuo,
+o intervalo vem da região anterior. No seccionado, há `1rem` entre cada divisória e o
+conteúdo adjacente. Não some padding e gap para expressar o mesmo intervalo.
+
+Page conserva os recuos laterais e a largura de leitura. Seu body não acrescenta padding
+inferior quando termina a página; antes de um footer seccionado, reserva `1rem` até a linha.
+O modo `flush` remove recuos do body para uma lista ou tabela controlar sua própria borda,
+mas mantém o intervalo entre blocos.
+
+Ao migrar, remova `space-y`, `gap`, `pt` e `pb` locais que apenas reconstruíam esses defaults
+nos slots. Preserve classes de layout internas, como uma grade ou um grupo de campos compacto.

package/src/ui/docs/content/dialog.md

@@ -48,7 +48,7 @@ distinta da página.
 ```
 
 O corpo cresce até o limite da janela e passa a rolar; cabeçalho e rodapé permanecem visíveis.
-Seus filhos diretos recebem o ritmo estrutural de `1.5rem`. Um grupo compacto, uma grade ou uma
+Seus filhos diretos recebem o ritmo estrutural de `1rem`. Um grupo compacto, uma grade ou uma
 linha declara a própria relação em um wrapper filho; `flush` fica reservado ao conteúdo que
 controla todo o inset.
 O backdrop escurece a página sem aplicar desfoque.
@@ -126,13 +126,13 @@ fluxo modal encadeado, em que a superfície permanece aberta e troca de etapa.
   <DialogContent>
     <DialogHeader>
       <DialogNavigation>
-        <Button variant="ghost" size="icon" aria-label="Voltar para a lista">
+        <Button variant="ghost" size="icon-sm" aria-label="Voltar para a lista">
           <ArrowLeft />
         </Button>
       </DialogNavigation>
       <DialogTitle>Evento 4821</DialogTitle>
       <DialogActions>
-        <Button variant="ghost" size="icon" aria-label="Mais ações">
+        <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
           <Ellipsis />
         </Button>
       </DialogActions>
@@ -146,9 +146,10 @@ fluxo modal encadeado, em que a superfície permanece aberta e troca de etapa.
 </Dialog>
 ```
 
-Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem), o mesmo que a
-[`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
-quadrado `icon-sm` (1.75rem) por padrão.
+O header compartilha a geometria de Page e Surface delimitada: padding de `1rem` e
+linha mínima de `2rem`, nos dois layouts. Declare `size="sm"` nos botões textuais e
+`size="icon-sm"` nos de ícone (`2rem`), incluindo o retorno. `CloseButton` já usa
+`icon-sm` por padrão. Conteúdo maior pode expandir a linha; rodapés preservam sua escala.
 
 O cabeçalho aceita `DialogDescription` como subheading opcional para orientar sobre a finalidade.
 Omita quando repetir o título. Condições, regras de negócio e consequências necessárias à decisão
@@ -656,3 +657,14 @@ comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions)
 | `id` | `string` | | Identificador para associação acessível explícita. |
 | `className` | `string` | | Ajusta a apresentação do parágrafo. |
 | `…props` | `ComponentProps<"p">` | | Atributos nativos. |
+
+## Espaçamento do corpo
+
+O body separa os blocos diretos por `1rem`. Dialog e Drawer são superfícies delimitadas:
+o conteúdo mantém `1rem` até a borda inferior, mesmo sem uma propriedade `framed`.
+Em `sectioned`, o corpo tem `1rem` entre o conteúdo e cada divisória. Em `continuous`,
+o cabeçalho fornece o intervalo superior; sem cabeçalho, o próprio corpo abre esse recuo.
+Use `flush` quando o conteúdo controlar seus próprios recuos.
+
+Na intro, `DialogTitle` usa a mesma escala de `PageTitle` (`1.875rem`). No header
+compacto, o título conserva a escala de `1.125rem`. O nível semântico não altera essas medidas.

package/src/ui/docs/content/drawer.md

@@ -119,7 +119,7 @@ retorno de um fluxo encadeado, em que o painel permanece aberto e troca de etapa
   <DrawerContent side="right">
     <DrawerHeader>
       <DrawerNavigation>
-        <Button variant="ghost" size="icon" aria-label="Voltar para a lista">
+        <Button variant="ghost" size="icon-sm" aria-label="Voltar para a lista">
           <ArrowLeft />
         </Button>
       </DrawerNavigation>
@@ -130,7 +130,7 @@ retorno de um fluxo encadeado, em que o painel permanece aberto e troca de etapa
       </DrawerMedia>
       <DrawerTitle>ABC-1D23</DrawerTitle>
       <DrawerActions>
-        <Button variant="ghost" size="icon" aria-label="Mais ações">
+        <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
           <Ellipsis />
         </Button>
       </DrawerActions>
@@ -144,9 +144,10 @@ retorno de um fluxo encadeado, em que o painel permanece aberto e troca de etapa
 </Drawer>
 ```
 
-Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem), o mesmo que a
-[`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
-quadrado `icon-sm` (1.75rem) por padrão.
+O header compartilha a geometria de Page e Surface delimitada: padding de `1rem` e
+linha mínima de `2rem`, nos dois layouts. Declare `size="sm"` nos botões textuais e
+`size="icon-sm"` nos de ícone (`2rem`), incluindo o retorno. `CloseButton` já usa
+`icon-sm` por padrão. Conteúdo maior pode expandir a linha; rodapés preservam sua escala.
 
 O cabeçalho aceita `DrawerDescription` como subheading opcional para orientar sobre a finalidade.
 Omita quando repetir o título. Condições, regras de negócio e consequências necessárias à decisão
@@ -323,3 +324,14 @@ comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions)
 | `id` | `string` | | Identificador para associação acessível explícita. |
 | `className` | `string` | | Ajusta a apresentação do parágrafo. |
 | `…props` | `ComponentProps<"p">` | | Atributos nativos. |
+
+## Espaçamento do corpo
+
+O body separa os blocos diretos por `1rem`. Dialog e Drawer são superfícies delimitadas:
+o conteúdo mantém `1rem` até a borda inferior, mesmo sem uma propriedade `framed`.
+Em `sectioned`, o corpo tem `1rem` entre o conteúdo e cada divisória. Em `continuous`,
+o cabeçalho fornece o intervalo superior; sem cabeçalho, o próprio corpo abre esse recuo.
+Use `flush` quando o conteúdo controlar seus próprios recuos.
+
+Na intro, `DrawerTitle` usa a mesma escala de `PageTitle` (`1.875rem`). No header
+compacto, o título conserva a escala de `1.125rem`. O nível semântico não altera essas medidas.

package/src/ui/docs/content/icon-picker.md

@@ -1,18 +1,18 @@
 ## Escolher na paleta padrão
 
 Use `IconPicker` quando a pessoa puder escolher o ícone que identifica um registro, como um
-relatório ou um painel. A lista abre em um popover com busca, e o valor guardado é o nome do ícone em
-kebab-case, como `chart-line`. Selecionar novamente o ícone atual limpa o valor.
+relatório ou um painel. A grade de ícones abre em um popover com busca em português, e o valor guardado é o nome do ícone em
+kebab-case, como `chart-line`. Selecionar novamente o ícone atual limpa o valor. A grade exibe somente ícones; os nomes ficam disponíveis para leitores de tela e busca. A busca aceita o identificador técnico, o nome em português e sinônimos. `searchTerms` permite definir rótulos e termos de busca para uma paleta própria, sem alterar o valor salvo.
 
 ```tsx preview col md
-const [icon, setIcon] = useState('chart-line')
+const [icon, setIcon] = useState("chart-line");
 
 render(
   <div className="grid gap-2">
     <Label htmlFor="report-icon">Ícone do relatório</Label>
     <IconPicker id="report-icon" value={icon} onChange={setIcon} />
   </div>,
-)
+);
 ```
 
 ## Apresentar o ícone escolhido
@@ -22,8 +22,8 @@ padrão é exportada como `iconPickerIcons`; use-a em listas, cards e árvores,
 para nomes que não existam mais, como em `iconPickerIcons[name] ?? FileText`.
 
 ```tsx preview col md
-const [icon, setIcon] = useState('store')
-const SelectedIcon = iconPickerIcons[icon] ?? FileText
+const [icon, setIcon] = useState("store");
+const SelectedIcon = iconPickerIcons[icon] ?? FileText;
 
 render(
   <div className="flex items-center gap-3">
@@ -37,7 +37,7 @@ render(
       </ItemHeader>
     </Item>
   </div>,
-)
+);
 ```
 
 ## Paleta própria
@@ -46,27 +46,45 @@ render(
 domínio, pois cada importação participa do bundle.
 
 ```tsx preview col md
-const [icon, setIcon] = useState('')
+const [icon, setIcon] = useState("");
 
 render(
   <IconPicker
     value={icon}
     onChange={setIcon}
-    icons={{ 'zap': Zap, 'star': Star, 'flag': Flag, 'heart': Heart }}
+    icons={{ zap: Zap, star: Star, flag: Flag, heart: Heart }}
     placeholder="Selecione um ícone…"
     className="w-56"
   />,
-)
+);
 ```
 
 ## Propriedades de IconPicker
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `value` | `string` | | Nome do ícone selecionado (chave da paleta); `''` é nenhum. |
-| `onChange` | `(name: string) => void` | | Recebe o nome escolhido. |
-| `icons` | `Record<string, LucideIcon>` | `iconPickerIcons` | Paleta nome → componente. |
-| `placeholder` | `string` | `'Selecione um ícone…'` | Texto do gatilho sem seleção. |
-| `disabled` | `boolean` | `false` | Desabilita o gatilho. |
-| `className` | `string` | | Classes do gatilho, em geral para ajustar a largura. Sem elas, o gatilho ocupa toda a largura disponível. |
-| `id`, `aria-invalid`, `aria-describedby` | `string`, `boolean`, `string` | | Integração com `Field` e `ActionForm`: o gatilho recebe a identidade do campo, o estado inválido e a mensagem associada. Com `aria-invalid`, a moldura assume o contexto de erro, como no `Input`. |
+| Propriedade                              | Tipo                                                    | Padrão                    | Descrição                                                                                                                                                                                          |
+| ---------------------------------------- | ------------------------------------------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`                                  | `string`                                                |                           | Nome do ícone selecionado (chave da paleta); `''` é nenhum.                                                                                                                                        |
+| `onChange`                               | `(name: string) => void`                                |                           | Recebe o nome escolhido.                                                                                                                                                                           |
+| `icons`                                  | `Record<string, LucideIcon>`                            | `iconPickerIcons`         | Paleta nome → componente.                                                                                                                                                                          |
+| `searchTerms`                            | `Record<string, { label: string; keywords: string[] }>` | Mapa interno em português | Rótulos acessíveis e sinônimos de busca.                                                                                                                                                           |
+| `placeholder`                            | `string`                                                | `'Selecione um ícone…'`   | Texto do gatilho sem seleção.                                                                                                                                                                      |
+| `disabled`                               | `boolean`                                               | `false`                   | Desabilita o gatilho.                                                                                                                                                                              |
+| `className`                              | `string`                                                |                           | Classes do gatilho, em geral para ajustar a largura. Sem elas, o gatilho ocupa toda a largura disponível.                                                                                          |
+| `id`, `aria-invalid`, `aria-describedby` | `string`, `boolean`, `string`                           |                           | Integração com `Field` e `ActionForm`: o gatilho recebe a identidade do campo, o estado inválido e a mensagem associada. Com `aria-invalid`, a moldura assume o contexto de erro, como no `Input`. |
+
+## Catálogo sob demanda
+
+`IconCatalogProvider` recebe um objeto `catalog` com `load` e `render`. Declare esse objeto
+como constante de módulo ou com `useMemo`, preservando sua identidade entre renders. `load` retorna uma promessa com
+`{ name, label, keywords }[]` e só é chamado ao abrir o picker. O consumidor pode reutilizar a
+promessa para cache, mas deve descartá-la em caso de falha para permitir tentar novamente.
+`render(name, className)` apresenta o ícone salvo sem precisar carregar o índice.
+
+O picker começa com 64 resultados e carrega mais automaticamente ao se aproximar do fim do scroll.
+A grade tem oito colunas; a busca sempre percorre o índice inteiro. Erros no carregamento oferecem nova tentativa.
+O consumidor deve carregar imagens conforme entram na região visível e fornecer fallback.
+Uma paleta explícita por `icons` prevalece sobre o provider, preservando seletores especializados.
+Sem provider, o catálogo curado continua funcionando sem requisições externas.
+
+Antes da primeira abertura, um ícone externo salvo é anunciado como “Ícone selecionado”;
+após carregar o índice, o gatilho usa o rótulo do catálogo. O desenho não depende desse carregamento.

package/src/ui/docs/content/input.md

@@ -200,7 +200,7 @@ controle ativo, declare `data-disabled="true"` no `InputGroup`.
 
 | Propriedade | Tipo                                                    | Padrão      | Descrição                                                                                                                     |
 | ----------- | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `size`      | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'`                | `'xs'`      | O subconjunto da escala única que cabe em um campo (1.5 · 2 · 1.5 · 1.75rem); os `icon-*` são quadrados.                      |
+| `size`      | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'`                | `'xs'`      | O subconjunto da escala única que cabe em um campo (1.5 · 2 · 1.5 · 2rem); os `icon-*` são quadrados.                      |
 | `context`   | `'neutral' \| 'primary' \| 'warning' \| 'danger'`       | `'neutral'` | Contexto semântico herdado de Button. Com `variant` `solid` ou `subtle` sem contexto declarado, o padrão passa a `'primary'`. |
 | `variant`   | `'solid' \| 'subtle' \| 'outline' \| 'ghost' \| 'link'` | `'ghost'`   | Tratamento visual; use `solid` quando a ação precisar de ênfase.                                                              |