@softize/opus 13.1.0 → 14.0.0

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

@@ -1,9 +1,12 @@
 ## Carregamento sem progresso conhecido
 
-Use `Spinner` quando a duração ou o progresso da espera não forem conhecidos. `sm` atende ações
-compactas; `lg`, estados mais amplos. O componente já possui o nome acessível “Carregando”.
+Use `Spinner` quando a duração ou o progresso da espera não forem conhecidos. `size` usa os nomes da
+escala dos controles e mede o glifo do controle homônimo: `sm` é o ícone de um `Button` `sm`, `lg` o
+de um `lg`. O ícone é decorativo; quem nomeia a espera é o contêiner (`role="status"`, como fazem
+`DataState` e `PageState`) ou o texto ao lado.
 
 ```tsx preview
+<Spinner size="xs" />
 <Spinner size="sm" />
 <Spinner />
 <Spinner size="lg" />
@@ -20,11 +23,11 @@ andamento.
 
 ## Em carga de conteúdo
 
-Espera curta sem forma definida. Quando o conteúdo tem forma conhecida (lista, card), prefira
-Skeleton.
+Espera curta sem forma definida; o contêiner nomeia o estado. Para uma consulta inteira, `DataState`
+já monta esse contêiner. Quando o conteúdo tem forma conhecida (lista, card), prefira Skeleton.
 
 ```tsx preview
-<div className="flex items-center gap-2 text-sm text-muted-foreground">
+<div role="status" className="flex items-center gap-2 text-sm text-muted-foreground">
   <Spinner />
   <span>Carregando sessões…</span>
 </div>
@@ -34,4 +37,4 @@ Skeleton.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | O tamanho — sm para dentro de botão, lg para estados de página. |
+| `size` | `'xs' \| 'sm' \| 'default' \| 'lg'` | `'default'` | O glifo do controle homônimo na escala única (0.875 · 0.875 · 1 · 1.25rem). |

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

@@ -66,5 +66,5 @@ disabled esmaece e bloqueia a chave — ligada ou desligada — e o rótulo em p
 | `checked` | `boolean` | | O estado, no modo controlado — parear com onCheckedChange. |
 | `onCheckedChange` | `(checked: boolean) => void` | | Chamado a cada alternância, com o novo estado. |
 | `defaultChecked` | `boolean` | `false` | Estado inicial no modo não controlado. |
-| `size` | `'sm' \| 'default'` | `'default'` | Tamanho da chave — sm para densidade em linha de lista. |
+| `size` | `'sm' \| 'default'` | `'default'` | Tamanho da chave, com os nomes da escala única — sm para densidade em linha de lista. |
 | `disabled` | `boolean` | `false` | Esmaece e bloqueia — o Label em par esmaece junto (peer-disabled). |

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

@@ -92,7 +92,7 @@ lateral do gatilho.
 | `defaultValue` | `string` | | Aba inicial no modo não controlado. |
 | `value` | `string` | | Aba ativa no modo controlado. Use com `onValueChange`. |
 | `onValueChange` | `(value: string) => void` | | Chamado quando a pessoa seleciona outra aba. |
-| `size` | `'default' \| 'sm'` | `'default'` | Escala de altura compartilhada com `TabsList`. |
+| `size` | `'default' \| 'sm'` | `'default'` | Altura da lista na escala única dos controles (2.25 e 2rem), aplicada em `TabsList`. |
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção da lista de abas. |
 
 ## Propriedades de TabsList

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

@@ -70,7 +70,7 @@ disabled esmaece e bloqueia o clique — o estado pressed permanece visível.
 | `onPressedChange` | `(pressed: boolean) => void` | | Chamado a cada alternância, com o novo estado. |
 | `defaultPressed` | `boolean` | `false` | Estado inicial no modo não controlado. |
 | `variant` | `'default' \| 'outline'` | `'default'` | default não tem borda (fundo só quando ativo); outline carrega a borda. |
-| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Altura do botão — sm para toolbar densa, lg para alvo mais confortável. |
+| `size` | `'sm' \| 'default' \| 'lg'` | `'default'` | Altura na escala única dos controles (2 · 2.25 · 2.5rem) — sm para toolbar densa, lg para alvo mais confortável. |
 | `disabled` | `boolean` | `false` | Esmaece e bloqueia o clique, preservando o estado visual. |
 
 ## ToggleGroup

package/src/ui/drivers/react.tsx

@@ -2,7 +2,7 @@
  * @softize/opus/ui/react — React driver
  *
  * Hooks + Provider pra invocar actions client-side.
- *   - `OpusProvider` — injeta ClientAdapter no contexto (`TbdlibProvider` é alias em retirada)
+ *   - `OpusProvider` — injeta ClientAdapter no contexto
  *   - `useAction(action)` — invoca actions simple/form/view
  *   - `useLookupAction(action)` — variante pra search (output Paginated)
  *
@@ -83,11 +83,6 @@ export function OpusProvider({
   return <OpusContext.Provider value={value}>{children}</OpusContext.Provider>
 }
 
-/** @deprecated Renomeado para `OpusProvider`; o alias segue até a próxima série. */
-export const TbdlibProvider = OpusProvider
-/** @deprecated Use `OpusProviderProps`. */
-export type TbdlibProviderProps = OpusProviderProps
-
 function useClient(): ClientAdapter {
   const ctx = useContext(OpusContext)
   if (ctx === null) {

package/src/ui/meta.ts

@@ -69,7 +69,7 @@ export const componentMeta = {
     name: "button",
     ancestry: "shadcn",
     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; `busy` comunica o andamento e impede um novo acionamento. Para ações relacionadas, use ButtonGroup.",
+      "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.",
   },
   card: {
     name: "card",
@@ -117,7 +117,7 @@ export const componentMeta = {
     name: "content-header",
     ancestry: "opus",
     whenToUse:
-      "Estruture o cabeçalho de um Content com título, descrição, metadados e ações. No caso comum, declare esses valores diretamente em Content; componha ContentHeader apenas quando precisar controlar a anatomia.",
+      "Estruture o cabeçalho de um Content com título, contador, descrição e ações — a mesma anatomia de PageHeader. No caso comum, declare esses valores diretamente em Content; componha ContentHeader apenas quando precisar controlar a anatomia.",
   },
   copyable: {
     name: "copyable",
@@ -183,7 +183,7 @@ export const componentMeta = {
     name: "spinner",
     ancestry: "shadcn",
     whenToUse:
-      "Indique uma espera sem progresso determinado, como uma ação ou consulta em andamento. Para reservar a forma do conteúdo, use Skeleton.",
+      "Indique uma espera sem progresso determinado, como uma ação ou consulta em andamento. O ícone é decorativo: o contêiner (`role=\"status\"`) ou o texto ao lado nomeia a espera. Para reservar a forma do conteúdo, use Skeleton.",
   },
   table: {
     name: "table",
@@ -327,7 +327,7 @@ export const componentMeta = {
     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, enquanto PaneHeader, PaneBody e PaneFooter estruturam as regiões fixa e rolável. Use SidebarNav para grupos planos, componha árvores com SidebarItem e SidebarTreeGroup e use ShellNav quando a navegação precisar de cabeçalho e rodapé próprios.",
+      "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, enquanto PaneHeader, PaneBody e PaneFooter estruturam as regiões fixa e rolável. Use SidebarNav para grupos planos e componha árvores com SidebarItem e SidebarTreeGroup; cabeçalho e rodapé próprios ficam em PaneHeader e PaneFooter.",
   },
   "scroll-area": {
     name: "scroll-area",
@@ -412,7 +412,7 @@ export const componentMeta = {
     name: "data-state",
     ancestry: "opus",
     whenToUse:
-      "Coordene carregamento, erro, vazio e conteúdo de uma consulta assíncrona. Use DataState dentro da estrutura que receberá os dados; para uma região disponível à criação, use Empty. Ações em andamento pertencem ao estado `busy` do controle que as iniciou.",
+      "Coordene carregamento, erro, vazio e conteúdo de uma consulta assíncrona com as mesmas superfícies de PageState: `emptyMessage` compõe Empty com moldura sólida, o erro é um Alert com `onRetry` e `retryLabel`. Use DataState dentro da estrutura que receberá os dados; para uma região disponível à criação, use Empty. Ações em andamento pertencem ao estado `busy` do controle que as iniciou.",
   },
   "action-list-dialog": {
     name: "action-list-dialog",

package/src/ui/react.tsx

@@ -18,7 +18,12 @@ export type {
   ButtonVariant,
   ButtonSize,
 } from "./components/primitives/button.tsx";
-export type { ControlShape } from "./components/primitives/control.ts";
+export type {
+  ControlShape,
+  ControlSize,
+  ControlIconSize,
+  ControlScale,
+} from "./components/primitives/control.ts";
 
 export { Input } from "./components/primitives/input.tsx";
 
@@ -358,6 +363,7 @@ export { useOverflowing } from "./lib/overflow.ts";
 export {
   ActionForm,
   ActionFormField,
+  LabelHelp,
   useActionFormContext,
 } from "./components/patterns/form.tsx";
 export type {
@@ -395,12 +401,7 @@ export { ActionView } from "./components/patterns/view.tsx";
 export type { ActionViewProps } from "./components/patterns/view.tsx";
 
 export { ActionTrigger } from "./components/patterns/trigger.tsx";
-export {
-  dialog,
-  DialogHost,
-  confirm,
-  ConfirmHost,
-} from "./components/patterns/confirm.tsx";
+export { dialog, DialogHost } from "./components/patterns/confirm.tsx";
 export type {
   AlertOptions,
   ChooseOptions,
@@ -499,15 +500,6 @@ export type {
   SidebarNavItem,
 } from "./components/patterns/sidebar.tsx";
 
-// O menu como primitivo pivotável: recolhe quando composto dentro de Sidebar.
-export { ShellNav, ShellNavHeading } from "./components/patterns/shell-nav.tsx";
-export type {
-  ShellNavProps,
-  ShellNavGroup,
-  ShellNavItem,
-  ShellNavHeadingProps,
-} from "./components/patterns/shell-nav.tsx";
-
 // Roteamento history-based (o pathname É o estado). Escopo pequeno de propósito: leitura
 // reativa da URL + navigate — sem tabela de rotas. Ver src/ui/router.ts.
 export {

package/src/ui/components/patterns/shell-nav.tsx

@@ -1,154 +0,0 @@
-/**
- * <ShellNav /> — o menu como primitivo PIVOTÁVEL. Um nav (grupos → itens, com heading e
- * âncora inferior) que serve os DOIS lares do chrome sem flag:
- *
- *   - dentro de <Sidebar> → recolhe pra ícone-só (com tooltip) junto com a coluna;
- *   - fora de <Sidebar> → permanece expandido.
- *
- * "Tanto faz onde": o componente se adapta ao lugar, sem "modo" configurado.
- *
- * Presentacional e CONTROLADO — o app é dono do `activeId`, do clique e do roteamento.
- * v1 PLANA (grupos → itens); aninhamento (accordion/pasta) e DnD COMPOSTO entram quando o
- * primeiro consumidor de árvore migrar — ver `docs/shellnav.md`.
- */
-
-import type { ReactNode } from 'react'
-import { cn } from '../../lib/cn.ts'
-import { focusRing } from '../primitives/control.ts'
-import { useSidebarCollapsed } from './sidebar.tsx'
-import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../primitives/tooltip.tsx'
-
-/** @deprecated Use `SidebarNav` (ver sidebar.md); mantido por compatibilidade. */
-export interface ShellNavItem {
-  /** Coordenada estável — volta em `onSelect` e casa com `activeId`. Único em toda a nav. */
-  id: string
-  label: string
-  /** Ícone à esquerda (é o que sobra no modo recolhido — vira o alvo, com o label no tooltip). */
-  icon?: ReactNode
-  /** Selo à direita (contagem, `beta`). Some no recolhido. */
-  badge?: ReactNode
-  /** Visível mas inerte. */
-  disabled?: boolean
-}
-
-/** @deprecated Use `SidebarNav` (ver sidebar.md); mantido por compatibilidade. */
-export interface ShellNavGroup {
-  /** Cabeçalho do grupo. Ausente/vazio = itens soltos, sem rótulo. Some no recolhido. */
-  label?: string
-  items: ShellNavItem[]
-}
-
-/** @deprecated Use `SidebarNav` (ver sidebar.md); mantido por compatibilidade. */
-export interface ShellNavProps {
-  groups: ShellNavGroup[]
-  /** `id` do item ativo. Ausente = nenhum destacado. */
-  activeId?: string
-  onSelect: (id: string) => void
-  /** Topo do nav — título, busca, botão (ex.: o "+" do Relatórios). Some no recolhido. Ver <ShellNavHeading>. */
-  heading?: ReactNode
-  /** Grupos ANCORADOS embaixo (ex.: Configurações no app), mesmo renderer, separados por filete. */
-  footer?: ShellNavGroup[]
-  /** Rótulo da landmark `<nav>`. */
-  navLabel?: string
-  /** Classes da raiz (a coluna). A largura vem do pane/sidebar que a contém. */
-  className?: string
-}
-
-/** Rótulo só existe se tiver texto — vazio não vira cabeçalho fantasma. */
-const titled = (label?: string): boolean => (label ?? '').trim() !== ''
-
-/** Selo vazio não vira pílula sem texto. `0` conta (contagem legítima). */
-const shown = (badge: ReactNode): boolean => {
-  if (badge === undefined || badge === null || badge === false || badge === '') return false
-  if (typeof badge === 'number' && Number.isNaN(badge)) return false
-  return !(Array.isArray(badge) && badge.length === 0)
-}
-
-/** Grupo sem item não abre buraco no `space-y` nem deixa rótulo pairando sobre nada. */
-const filled = (group: ShellNavGroup): boolean => group.items.length > 0
-
-function renderItem(item: ShellNavItem, activeId: string | undefined, onSelect: (id: string) => void, railed: boolean): React.ReactElement {
-  const active = item.id === activeId
-  const button = (
-    <button
-      type="button"
-      disabled={item.disabled}
-      aria-current={active ? 'page' : undefined}
-      onClick={() => onSelect(item.id)}
-      className={cn(
-        'flex w-full items-center gap-2.5 rounded-md py-1.5 text-left text-sm transition-colors',
-        'disabled:pointer-events-none disabled:opacity-40',
-        'outline-none',
-        focusRing,
-        railed ? 'justify-center px-0' : 'px-2.5',
-        active ? 'bg-muted font-medium text-foreground' : 'text-foreground/80 hover:bg-muted/60',
-      )}
-    >
-      {item.icon !== undefined && <span className="flex shrink-0">{item.icon}</span>}
-      {!railed && <span className="min-w-0 flex-1 truncate">{item.label}</span>}
-      {!railed && shown(item.badge) && <span className="shrink-0">{item.badge}</span>}
-    </button>
-  )
-  if (!railed) return <div key={item.id}>{button}</div>
-  // Recolhido: o label migra pro tooltip (à direita) — sem ele, a coluna vira ícones adivinháveis.
-  return (
-    <Tooltip key={item.id}>
-      <TooltipTrigger asChild>{button}</TooltipTrigger>
-      <TooltipContent side="right">{item.label}</TooltipContent>
-    </Tooltip>
-  )
-}
-
-function renderGroup(group: ShellNavGroup, gi: number, activeId: string | undefined, onSelect: (id: string) => void, railed: boolean): React.ReactElement | null {
-  if (!filled(group)) return null
-  return (
-    <div key={gi} className="space-y-0.5">
-      {!railed && titled(group.label) && (
-        <div className="px-2.5 pb-1 text-xs font-medium text-muted-foreground/70">{group.label}</div>
-      )}
-      {group.items.map((item) => renderItem(item, activeId, onSelect, railed))}
-    </div>
-  )
-}
-
-/** @deprecated Use `SidebarNav`: mesma navegação, integrada à `Sidebar`. Mantido por compatibilidade. */
-export function ShellNav({ groups, activeId, onSelect, heading, footer, navLabel = 'Navegação', className }: ShellNavProps): React.ReactElement {
-  const railed = useSidebarCollapsed()
-
-  const body = (
-    <div data-slot="shell-nav" className={cn('flex h-full min-h-0 flex-col', className)}>
-      {!railed && heading}
-      <nav aria-label={navLabel} className={cn('min-h-0 flex-1 space-y-4 overflow-y-auto p-2', railed && 'px-1.5')}>
-        {groups.map((group, gi) => renderGroup(group, gi, activeId, onSelect, railed))}
-      </nav>
-      {footer !== undefined && footer.some(filled) && (
-        <div className={cn('space-y-4 border-t border-border p-2', railed && 'px-1.5')}>
-          {footer.map((group, gi) => renderGroup(group, gi, activeId, onSelect, railed))}
-        </div>
-      )}
-    </div>
-  )
-
-  // Recolhido usa tooltips — garante um provider (nested é ok se o app já tem um).
-  return railed ? <TooltipProvider delayDuration={200}>{body}</TooltipProvider> : body
-}
-
-/** @deprecated Use `SidebarNav` (ver sidebar.md); mantido por compatibilidade. */
-export interface ShellNavHeadingProps {
-  /** Título da seção. */
-  title: ReactNode
-  /** Ação à direita — em geral um botão (o "+" de criar). */
-  action?: ReactNode
-  className?: string
-}
-
-/** @deprecated Use `SidebarHeader` com `SidebarNav`. Cabeçalho do ShellNav: título + espaço
- *  pra um botão. Mantido por compatibilidade. */
-export function ShellNavHeading({ title, action, className }: ShellNavHeadingProps): React.ReactElement {
-  return (
-    <div className={cn('flex h-12 shrink-0 items-center gap-1.5 border-b border-border px-4', className)}>
-      <span className="min-w-0 flex-1 truncate text-sm font-semibold">{title}</span>
-      {action !== undefined && <span className="shrink-0">{action}</span>}
-    </div>
-  )
-}