@softize/opus 26.0.0 → 26.2.0

package/src/ui/docs/content/action-form.md

@@ -84,12 +84,21 @@ do mesmo peso visual. Nesse caso, o cancelamento muda para `outline`, salvo esco
 `cancelVariant`. Para apresentar o formulário como uma seção delimitada da página, use
 [`ActionFormCard`](/ui/action-form-card). As propriedades de cada wrapper estão na página dele.
 
-## Ajuda no rótulo
+## Hint visível ou ícone de help
 
-`FieldSpec.help` aparece como um ícone junto ao rótulo, com o texto em um tooltip. Escreva ali o
-critério, o efeito ou a limitação que o rótulo não diz; ajuda que só repete o rótulo deve ser omitida.
-Não existe texto auxiliar sob o campo: quem precisa de uma frase permanente abaixo do controle usa
-`FieldDescription` na composição própria.
+Use `FieldSpec.hint` abaixo do controle quando a pessoa precisar da informação para preencher
+corretamente ou prever o efeito da escolha. Exemplo: “Sem áreas selecionadas, a pasta aparece em
+todas as áreas.” O texto permanece visível e participa do `aria-describedby` do controle, junto
+do erro quando houver. Em uma composição própria, use `FieldDescription` com a mesma associação.
+
+Use `FieldSpec.help` no ícone junto à label para detalhes complementares, definições e exemplos
+opcionais. A pergunta é: sem abrir essa ajuda, a pessoa ainda consegue escolher corretamente?
+Se não, o trecho necessário deve ser hint. Não use o comprimento da frase como critério nem
+esconda uma condição obrigatória no tooltip. Omita texto que apenas repete a label.
+
+Hint e help podem coexistir se tiverem funções diferentes, sem duplicar a mesma frase. Um erro
+explica uma entrada inválida e sua correção; não substitui uma orientação necessária antes de
+preencher. Uma regra que afeta vários campos pertence ao corpo ou ao grupo correspondente.
 
 `LabelHelp` é esse mesmo ícone, exportado para um formulário sem contrato mostrar a ajuda no mesmo
 lugar:
@@ -185,3 +194,7 @@ ciclo de vida que o pattern não cobre; validação e execução continuam iguai
 | Propriedade | Tipo     | Descrição                                                    |
 | ----------- | -------- | ------------------------------------------------------------ |
 | `help`      | `string` | O texto do tooltip. Vazio ou ausente, o ícone não renderiza. |
+
+O `hint` aceita texto ou `I18nRef` e permanece visível; o contexto do formulário entrega o texto
+resolvido aos campos personalizados. O botão de `help` participa do Tab e abre por foco ou hover.
+Dialog e Drawer evitam que a ajuda seja o primeiro foco automático quando há outro controle.

package/src/ui/docs/content/action-list-dialog.md

@@ -96,6 +96,13 @@ const roleOptions = roles.items.map((role) => ({ value: role.id, label: role.nam
 </ActionListDialog>;
 ```
 
+## Orientação e contexto
+
+`description` apresenta a finalidade no cabeçalho, como “Escolha onde a pasta e suas subpastas
+aparecem.”. É opcional; não repita o título. `intro` apresenta no corpo informações necessárias
+à decisão que não pertencem a um campo específico. Regras, condições e consequências não ficam
+somente no subheading. Quando ambos são fornecidos, ambos participam de `aria-describedby`.
+
 ## Propriedades de ActionListDialog
 
 | Propriedade                                | Tipo                                | Padrão               | Descrição                                                                                         |
@@ -103,6 +110,7 @@ const roleOptions = roles.items.map((role) => ({ value: role.id, label: role.nam
 | `action / input`                           | `ListAction / TInput`               | `input`: `{}`        | O contrato e o escopo base da consulta. Uma mudança em `input` refaz a consulta; as invalidações declaradas por forms e triggers também. |
 | `open / onOpenChange`                      | `boolean / (open) => void`          |                      | Estado controlado do modal.                                                                       |
 | `title`                                    | `string`                            |                      | Nome da lista exibido no cabeçalho fixo.                                                          |
+| `description` | `ReactNode` | | Orientação opcional sob o título; não recebe regras de negócio. |
 | `intro`                                    | `ReactNode`                         |                      | Contexto relevante no início do corpo, como texto ou `Alert`.                                     |
 | `children`                                 | `(items, refetch) => ReactNode`     |                      | A composição dos itens. Carregamento, erro e vazio já são tratados pelo `ActionList`.            |
 | `note`                                     | `ReactNode`                         |                      | Contexto curto à esquerda da linha de ações. O total de itens já aparece no rodapé do `ActionList`. |

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

@@ -150,8 +150,21 @@ Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem)
 [`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
 quadrado `icon-sm` (1.75rem) por padrão.
 
-O cabeçalho não recebe descrição: um modal já é a superfície de uma tarefa, e o contexto que ajuda a
-decidir aparece no começo do corpo, como texto ou `Alert`.
+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
+ficam junto dos controles ou em `DialogBody`. Uma frase curta também pode ser regra: o critério é se
+pular o texto compromete a decisão, não sua extensão.
+
+```tsx
+<DialogHeader>
+  <DialogTitle>Organizar pasta</DialogTitle>
+  <DialogDescription>Escolha onde a pasta e suas subpastas aparecem.</DialogDescription>
+</DialogHeader>
+```
+
+Na composição direta, associe o `id` do texto por `aria-describedby` em `DialogContent` quando ele
+descrever a superfície para tecnologias assistivas. A regra sobre seleção vazia pertence ao
+campo de áreas e permanece fora do subheading.
 
 ## Identificar a tarefa com um ícone
 
@@ -634,3 +647,12 @@ conteúdo no primeiro bloco de `DialogBody`. `DialogIntro` exige um `DialogTitle
 
 No formato compacto, mantenha `DialogTitle` e `DialogActions` no próprio `DialogHeader`. Para
 comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions).
+
+## Propriedades de DialogDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | | Orientação opcional sob o título em `DialogHeader` ou `DialogIntro`. |
+| `id` | `string` | | Identificador para associação acessível explícita. |
+| `className` | `string` | | Ajusta a apresentação do parágrafo. |
+| `…props` | `ComponentProps<"p">` | | Atributos nativos. |

package/src/ui/docs/content/documentation-portal.md

@@ -46,6 +46,36 @@ conceitos relacionados, não para reproduzir automaticamente a árvore de arquiv
 tem `slug`, `title` e `render`; `searchText` acrescenta conteúdo à busca e `navigationTitle` permite
 um rótulo lateral curto sem mudar o título completo.
 
+Um grupo pode conter páginas próprias e subgrupos em `groups`. Por exemplo, uma documentação
+por domínio pode reunir as conexões externas em Integrações e manter um grupo por sistema:
+
+```tsx
+const sections: DocSection[] = [{
+  label: 'Domínios',
+  groups: [{
+    label: 'Integrações',
+    pages: [{ slug: 'integrations', title: 'Integrações', render: () => <p>Conexões com sistemas externos.</p> }],
+    groups: [{
+      label: 'Insider',
+      pages: [{ slug: 'integrations/insider', title: 'Insider', render: () => <p>Envio de atributos e eventos.</p> }],
+    }],
+  }],
+}]
+```
+
+As páginas próprias vêm antes dos subgrupos na sequência de leitura. Um grupo com `pages: []`
+pode reunir somente subgrupos; ramos sem páginas em nenhum nível não aparecem na lateral.
+O contexto editorial usa o grupo nomeado mais próximo. A busca revela os ancestrais dos
+resultados e, no modo `sidebarInitiallyCollapsed`, restaura os ramos abertos manualmente
+quando a consulta é limpa. No modo expandido padrão, os ancestrais da página ativa são
+reabertos para mantê-la visível. `groups` é opcional:
+as declarações existentes continuam válidas. Essa hierarquia é uma escolha de leitura do host,
+não exige mover arquivos nem muda a descoberta por pastas.
+
+Se o host também percorre as páginas para montar índices ou resolver links, esse percurso
+precisa visitar `group.groups` recursivamente. Achatar somente `section.groups[].pages`
+não inclui as páginas dos subgrupos.
+
 Com `editorial`, a leitura recebe contexto, sumário dos títulos renderizados e links de página
 anterior e seguinte. `additionalPages` preserva destinos diretos que não entram nessa sequência.
 A busca documental do topo mantém seu rótulo, valor e função ao navegar para catálogos e detalhes;
@@ -64,6 +94,19 @@ o contrato desktop a partir de `64rem`. O aplicativo organiza a moldura do porta
 
 ADRs e changelog mantêm o mapa dos guias, sem acrescentar uma árvore para cada registro. Use `sidebarLinks` para oferecer entradas
 no mesmo nível dos grupos, após os capítulos, sem incluí-las na sequência anterior/próxima.
+Destinos com URL HTTP(S) absoluta usam navegação nativa, inclusive para outro aplicativo;
+destinos relativos usam o roteamento compartilhado.
+
+Para abrir uma ferramenta sem substituir a leitura atual, declare `newTab` no destino:
+
+```tsx
+<DocBrowser sections={sections}
+  sidebarLinks={[{ label: 'Lente', href: '/lens', newTab: true }]} />
+```
+
+O link exibe um ícone de nova aba, informa a abertura no nome acessível e usa
+`rel="noopener noreferrer"`. Sem `newTab`, mantém a navegação na aba atual.
+
 `DocCatalog` recebe registros derivados dos Markdown e uma consulta local independente do cabeçalho.
 Passe o catálogo em `content` para preservar a lateral:
 
@@ -148,7 +191,7 @@ não define as rotas nem a autorização do aplicativo.
 
 | Propriedade | Tipo | Padrão | Uso |
 | --- | --- | --- | --- |
-| `sections` | `DocSection[]` | Obrigatória na entrada leve | Seções, grupos e páginas na ordem de leitura. |
+| `sections` | `DocSection[]` | Obrigatória na entrada leve | Seções, grupos, subgrupos opcionais e páginas na ordem de leitura. |
 | `basePath` | `string` | `/docs` | Prefixo das rotas. |
 | `path` | `string` | Rota compartilhada | Caminho controlado por um host externo. |
 | `redirects` | `Record<string, string>` | `{}` | Slugs anteriores e seus destinos canônicos. |
@@ -160,7 +203,7 @@ não define as rotas nem a autorização do aplicativo.
 | `navigationLabel` | `string` | `Documentação` | Nome da área no contexto editorial; por exemplo, `UI` para o catálogo de componentes. |
 | `additionalPages` | `DocEntry[]` | `[]` | Destinos diretos fora da árvore e da sequência. |
 | `content` | `ReactNode` | — | Conteúdo do host no lugar da página documental, mantendo a lateral. O host resolve rota e título; `null` deixa a leitura vazia. |
-| `sidebarLinks` | `{ label: string; href: string; active?: boolean }[]` | `[]` | Destinos globais fora dos capítulos; `active` marca o catálogo atual. |
+| `sidebarLinks` | `{ label: string; href: string; active?: boolean; newTab?: boolean }[]` | `[]` | Destinos globais fora dos capítulos; `active` marca o catálogo atual e `newTab` abre em outra aba com ícone e descrição acessível. |
 | `sidebarInitiallyCollapsed` | `boolean` | `false` | Seções e grupos nomeados começam recolhidos, inclusive em links diretos. A busca revela resultados temporariamente sem alterar os ramos abertos pela pessoa. |
 
 A entrada histórica `@softize/opus/ui/docs` inclui o catálogo e oferece suas páginas quando

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

@@ -148,8 +148,21 @@ Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem)
 [`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
 quadrado `icon-sm` (1.75rem) por padrão.
 
-O cabeçalho não recebe descrição: o painel já nomeia o recurso, e o contexto que ajuda a decidir
-aparece no começo do corpo, como texto ou `Alert`.
+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
+ficam junto dos controles ou em `DrawerBody`. Uma frase curta também pode ser regra: o critério é se
+pular o texto compromete a decisão, não sua extensão.
+
+```tsx
+<DrawerHeader>
+  <DrawerTitle>Organizar pasta</DrawerTitle>
+  <DrawerDescription>Escolha onde a pasta e suas subpastas aparecem.</DrawerDescription>
+</DrawerHeader>
+```
+
+Na composição direta, associe o `id` do texto por `aria-describedby` em `DrawerContent` quando ele
+descrever a superfície para tecnologias assistivas. A regra sobre seleção vazia pertence ao
+campo de áreas e permanece fora do subheading.
 
 ## Impedir o fechamento durante uma operação
 
@@ -301,3 +314,12 @@ Assim o título acompanha o conteúdo rolável enquanto o chrome permanece está
 
 No formato compacto, mantenha `DrawerTitle` e `DrawerActions` no próprio `DrawerHeader`. Para
 comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions).
+
+## Propriedades de DrawerDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | | Orientação opcional sob o título em `DrawerHeader` ou `DrawerIntro`. |
+| `id` | `string` | | Identificador para associação acessível explícita. |
+| `className` | `string` | | Ajusta a apresentação do parágrafo. |
+| `…props` | `ComponentProps<"p">` | | Atributos nativos. |

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

@@ -1,7 +1,7 @@
 ## Esqueleto de página
 
 Use `Page` para manter cabeçalho, estado e conteúdo na mesma anatomia. `PageHeader` é a única
-introdução estrutural: reúne navegação contextual opcional, título e ações. O container é
+introdução estrutural: reúne navegação contextual opcional, título, orientação opcional e ações. O container é
 centralizado e ocupa a largura disponível até `80rem` (`max-w-7xl`). Use `className` somente quando
 a composição pedir outro teto ou largura total.
 
@@ -41,6 +41,19 @@ render(
 );
 ```
 
+## Orientar sobre a finalidade
+
+Use `description` na forma curta ou `PageDescription` em `PageHeader` quando uma frase breve
+ajudar a reconhecer a finalidade da página. Omita texto que só repita o título. Regras de negócio,
+limites e consequências ficam nos campos, ações ou corpo em que são necessários. Pular o
+subheading não deve comprometer a decisão nem a conclusão correta da tarefa.
+
+```tsx
+<Page title="Conhecimento" description="Consulte os materiais de apoio da sua área.">
+  <KnowledgeList />
+</Page>
+```
+
 ## Retorno para a página pai
 
 Use `PageBack` em uma subpágina simples. O destino é explícito para continuar correto após refresh ou
@@ -311,6 +324,7 @@ estado na própria seção com [`DataState`](/ui/data-state), [`ActionView`](/ui
 
 | Propriedade | Tipo                       | Padrão      | Descrição                                                                                                                                                          |
 | ----------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `description` | `ReactNode` | | Orientação opcional sob o título na forma curta. |
 | `title`     | `ReactNode`                |             | O h1 da página.                                                                                                                                                    |
 | `actions`   | `ReactNode`                |             | Ações contextuais no extremo oposto do cabeçalho.                                                                                                                  |
 | `layout`    | `'flow' \| 'fill'`         | `'flow'`    | Ocupação de altura, não anatomia: `fill` limita a página ao shell para que uma região interna role e leva essa altura até uma `ActionList` composta em `PageBody`. |
@@ -414,3 +428,11 @@ ocupa a altura.
 | `retryLabel`   | `string`                                     | `'Tentar de novo'`                        | Texto do botão de recuperação.                                                                              |
 | `children`     | `ReactNode`                                  |                                           | Conteúdo renderizado somente em `ready`.                                                                    |
 | `className`    | `string`                                     |                                           | Classes da superfície de estado.                                                                            |
+
+## Propriedades de PageDescription
+
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | | Orientação breve e opcional; filho direto de `PageHeader`. |
+| `className` | `string` | | Ajusta a apresentação do parágrafo. |
+| `…props` | `HTMLAttributes<HTMLParagraphElement>` | | Atributos nativos. |

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

@@ -73,6 +73,10 @@ diretamente quando a composição precisar de controles, badges ou hierarquia pa
 Quando o host usa um roteador, forneça também `onClick`: somente o clique simples é interceptado;
 cliques com modificadores preservam o comportamento do link. Sem `href`, o item continua sendo um botão.
 
+Para manter a página atual aberta ao visitar outro destino, declare `newTab` junto de `href`.
+O link usa `target="_blank"` e `rel="noopener noreferrer"`, não chama `onClick` e informa
+“abre em nova aba” no nome acessível, inclusive no rail recolhido. Sem `href`, `newTab` não tem efeito.
+
 ## Colapso
 
 `collapsed` informa o estado compacto aos itens. Forneça labels acessíveis mesmo quando somente os
@@ -99,3 +103,22 @@ render(
 - `Sidebar` oferece a coluna de navegação.
 - `SidebarNav`, `SidebarItem` e elementos nativos organizam o conteúdo interno.
 - `Surface` oferece anatomia e tratamento visual quando a região não é uma sidebar.
+
+## Propriedades de SidebarItem
+
+| Propriedade | Tipo | Padrão | Uso |
+| --- | --- | --- | --- |
+| `label` | `string` | Obrigatória | Nome do destino, também usado no modo recolhido. |
+| `href` | `string` | — | Renderiza um link nativo quando o item está habilitado; sem ela, renderiza um botão. |
+| `newTab` | `boolean` | `false` | Com `href`, abre em outra aba, informa a abertura no nome acessível e não chama `onClick`. |
+| `onClick` | `() => void` | — | Ativa o botão ou intercepta o clique simples do link, exceto com `newTab`. |
+| `icon`, `badge` | `ReactNode` | — | Ícone e complemento visual da linha. O modo recolhido mostra somente o ícone. |
+| `active` | `boolean` | `false` | Destaca o destino atual e declara `aria-current="page"`. |
+| `disabled` | `boolean` | `false` | Desabilita o alvo principal e impede que seja um link. |
+| `actions` | `ReactNode` | — | Controles irmãos do alvo principal, no modo aberto. |
+| `onToggle` | `() => void` | — | Exibe um controle separado para expandir ou recolher descendentes no modo aberto. |
+| `expanded` | `boolean` | `false` | Estado visual e acessível do controle de expansão. |
+| `dropPosition` | `'before' \| 'inside' \| 'after'` | — | Indicação visual de posição durante arraste, no modo aberto. |
+| `dragProps` | `HTMLAttributes<HTMLDivElement>` | — | Eventos e atributos de arraste aplicados à linha. |
+| `tooltipHint` | `ReactNode` | — | Complementa o tooltip do modo recolhido. |
+| `className` | `string` | — | Classes da linha nos dois modos. |

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

@@ -131,12 +131,11 @@ render(
     as="section"
     framed
     title="Plano atual"
-    description="Renova em 12 de maio."
     level={3}
   >
     <SurfaceBody>
       <p className="text-sm text-muted-foreground">
-        Até 10 workspaces e 50 agentes.
+        Renova em 12 de maio. Até 10 workspaces e 50 agentes.
       </p>
     </SurfaceBody>
     <SurfaceFooter>
@@ -511,3 +510,10 @@ um wrapper filho declara relações locais mais compactas.
 | ----------- | ----------- | ------ | ---------------------------------------------------- |
 | `children`  | `ReactNode` |        | Ações persistentes, alinhadas no fim da linha.       |
 | `className` | `string`    |        | Ajusta o rodapé, inclusive a distribuição das ações. |
+
+## Subheading e regras de negócio
+
+`description` e `SurfaceDescription` apresentam brevemente a finalidade da região. A orientação
+é opcional e não repete o título. A mesma regra vale para uma página (`level={1}`), uma seção ou
+um card: condições, limites e consequências necessários à decisão ficam no corpo ou junto do
+controle correspondente. Pular o subheading não deve comprometer a tarefa.

package/src/ui/docs/types.ts

@@ -18,6 +18,8 @@ export interface DocGroup {
   label?: string
   icon?: React.ReactNode
   pages: DocEntry[]
+  /** Subgrupos opcionais; páginas próprias vêm antes dos grupos na sequência de leitura. */
+  groups?: DocGroup[]
 }
 
 export interface DocSection {

package/src/ui/lib/modal-layers.ts

@@ -143,6 +143,21 @@ function syncHosts(): void {
   }
 }
 
+/** A ajuda permanece no Tab, mas não toma o foco inicial do campo ao abrir um modal. */
+export function skipHelpOnAutoFocus(event: Event): void {
+  if (event.defaultPrevented || !(event.target instanceof HTMLElement)) return;
+  const candidates = tabbables(event.target).filter(
+    (element) => element.tagName !== "A",
+  );
+  if (candidates[0]?.dataset.slot !== "label-help") return;
+  const control = candidates.find(
+    (element) => element.dataset.slot !== "label-help",
+  );
+  if (control === undefined) return;
+  control.focus();
+  if (document.activeElement === control) event.preventDefault();
+}
+
 /** Elementos alcançáveis pelo Tab dentro de `root`, na ordem do documento. */
 function tabbables(root: HTMLElement): HTMLElement[] {
   const nodes: HTMLElement[] = [];
@@ -178,7 +193,10 @@ function tabbables(root: HTMLElement): HTMLElement[] {
 function focusFromKeyboard(element: HTMLElement): void {
   element.focus();
   // O Tab do navegador seleciona o texto do campo que recebe o foco; a passagem manual imita.
-  if (element instanceof HTMLInputElement && typeof element.select === "function") {
+  if (
+    element instanceof HTMLInputElement &&
+    typeof element.select === "function"
+  ) {
     element.select();
   }
 }
@@ -342,7 +360,10 @@ export function registerFloatingLayer(
   // podem tratar o Tab e marcá-lo com `preventDefault`.
   const onKeyDown = (event: KeyboardEvent): void => {
     if (!isTabKey(event) || event.defaultPrevented) return;
-    if (!layerExemptionsActive() || layerOf(document.activeElement) !== record) {
+    if (
+      !layerExemptionsActive() ||
+      layerOf(document.activeElement) !== record
+    ) {
       return;
     }
     const candidates = tabbables(host);
@@ -361,7 +382,10 @@ export function registerFloatingLayer(
     if (layerWherePersonIs() === record) escape()?.(event);
   };
   const observer = new MutationObserver(() => {
-    if (pointerAnchor !== null && pointerAnchor.parentNode !== pointerLayer?.host) {
+    if (
+      pointerAnchor !== null &&
+      pointerAnchor.parentNode !== pointerLayer?.host
+    ) {
       // O painel apertado saiu da camada, como quando é fechado por código e vira o FAB.
       pointerAnchor = null;
       pointerLayer = null;

package/src/ui/react.tsx

@@ -173,6 +173,7 @@ export {
   DialogBody,
   DialogFooter,
   DialogTitle,
+  DialogDescription,
 } from "./components/primitives/dialog.tsx";
 export type {
   DialogProps,
@@ -326,6 +327,7 @@ export {
   DrawerNavigation,
   DrawerBody,
   DrawerTitle,
+  DrawerDescription,
   DrawerTrigger,
 } from "./components/primitives/drawer.tsx";
 export {
@@ -509,6 +511,7 @@ export {
   PageNavigation,
   PageBack,
   PageTitle,
+  PageDescription,
   PageActions,
   PageActionsTarget,
   PageBody,