@softize/opus 13.1.0 → 14.0.0

package/CHANGELOG.md

@@ -7,6 +7,40 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 14.0.0 — 2026-09-09
+
+Estados vazio, carregando e erro passam a uma composição só. `DataState` compõe `Empty` (moldura
+sólida, `bare` dentro de tabela) e o mesmo `Alert` de contexto `danger` com botão de recuperação
+que `PageState` já usava; o `Spinner` vira decorativo e o contêiner carrega o único `role="status"`.
+As props de estado têm um nome só em `DataState`, `PageState`, `ActionList` e `ActionListDialog`:
+`emptyMessage`, `errorMessage`, `retryLabel`; `PageState` ganha `onRetry` e `ActionView` ganha
+`emptyMessage` como atalho. `ContentHeader` e `PageHeader` renderizam a mesma anatomia
+(`surface-header.tsx`), e `Content` passa a usar `count`, como `Page`.
+
+A escala de `size` é uma só (`primitives/control.ts`): `xs`, `sm`, `default`, `lg` (1.5, 2, 2.25
+e 2.5rem) e `icon-xs`, `icon-sm`, `icon`, `icon-lg` (1.5, 1.75, 2.25 e 2.5rem), consumida por
+Button, InputGroupButton, Toggle, Select, Tabs, Switch, Item, Avatar, Spinner, Pagination e
+ActionTrigger. O degrau de 1.75rem que os consumidores forçavam por classe agora é `icon-sm`.
+`Button.icon` recebe um nó (`icon={<Plus />}`), como todos os outros componentes. `LabelHelp` é
+exportado pelo barrel e documentado em `form.md`.
+
+O extrator de copy alcança o que antes escapava do inventário: chamadas imperativas de diálogo
+(`dialog.confirm`, `alert`, `prompt`, `choose` — título, descrição e rótulos das ações),
+`TooltipContent`, rótulos em arrays literais locais percorridos por `map`, o `help` de
+`LabelHelp` e elementos JSX com genérico (`<ActionList<A, B>>`). Os campos de estado seguem os
+nomes novos (`emptyMessage`, `errorMessage`, `retryLabel`).
+
+**Breaking:** renomeie `emptyText`, `errorText` e `retryText` para `emptyMessage`,
+`errorMessage` e `retryLabel` em `DataState`, `PageState` e `ActionListDialog`
+(`Select.emptyText` não muda). Troque `Content.meta` por `count`; `ContentHeader` só existe
+dentro de `Content`. `icon-sm` passa a medir 1.75rem e `Avatar` segue a escala (`sm` antigo é
+`xs`; `default` cresce para 2.25rem); classes `size-7` forçadas viram `size="icon-sm"`.
+`Button.icon` deixa de aceitar componente: `icon={Trash}` vira `icon={<Trash />}`. Removidos:
+`TbdlibProvider` (use `OpusProvider`), `ShellNav*` (use `SidebarNav`), `confirm()` e `ConfirmHost`
+(use `dialog.confirm` e `DialogHost`), `FieldSpec.hint` (use `help`) e as variantes semânticas
+legadas de Button, Badge, Alert, Dot e MenuItem — declare `context` e `variant`. Testes que
+liam o markup do vazio de `DataState` passam a olhar `[data-slot=empty]`.
+
 ## 13.1.0 — 2026-09-08
 
 Erros deixam de falar inglês e de vazar detalhe interno. `normalizeError` devolve a microcopy fixa

package/bin/lib/copy.mjs

@@ -107,8 +107,16 @@ const JSX_CHILD_ROLES = new Map([
   ['TableCaption', 'description'],
   ['TableHead', 'heading'],
   ['TabsTrigger', 'tab'],
+  // A Base não tem papel `tooltip`. O tooltip nomeia um controle icon-only, logo é um
+  // fragmento (sem ponto final), não uma frase; `label` é o papel que reflete isso.
+  ['TooltipContent', 'label'],
 ])
 
+// Componentes cuja copy entra pelas próprias props e que, como filhos, não acrescentam
+// texto ao pai: `<FieldLabel>Nome<LabelHelp help="…" /></FieldLabel>` inventaria `Nome`
+// como label e a ajuda como helper-text, sem tornar o filho opaco.
+const SELF_CONTAINED_CHILD_COMPONENTS = new Set(['LabelHelp'])
+
 const OPTIONAL_CHILD_COMPONENTS = new Set(['ActionForm', 'ActionFormCard', 'ActionFormDialog'])
 const JSX_ACTION_CONSUMERS = new Set([
   'ActionForm', 'ActionFormCard', 'ActionFormDialog', 'ActionList', 'ActionListDialog', 'ActionTrigger', 'ActionView',
@@ -125,6 +133,14 @@ const JSX_PROP_ROLES = new Map([
   ['ActionForm', new Map([['submitLabel', 'button'], ['cancelLabel', 'button']])],
   ['ActionFormCard', new Map([['title', 'title'], ['description', 'description'], ['submitLabel', 'button'], ['cancelLabel', 'button']])],
   ['ActionFormDialog', new Map([['title', 'title'], ['description', 'dialog-body'], ['submitLabel', 'button'], ['cancelLabel', 'button']])],
+  // Estados unificados (14.0): a mesma tríade de mensagens em ActionList, ActionListDialog,
+  // DataState e PageState; ActionView só tem o vazio.
+  ['ActionList', new Map([['emptyMessage', 'empty-state'], ['errorMessage', 'error'], ['retryLabel', 'button']])],
+  ['ActionListDialog', new Map([
+    ['title', 'title'], ['description', 'dialog-body'],
+    ['emptyMessage', 'empty-state'], ['errorMessage', 'error'], ['retryLabel', 'button'],
+  ])],
+  ['ActionView', new Map([['emptyMessage', 'empty-state']])],
   // `itemLabel` identifica o dado alvo (por exemplo, `customer.name`); não é
   // microcopy estável e, por isso, não pertence ao inventário editorial.
   ['ActionTrigger', new Map([['label', 'button']])],
@@ -132,7 +148,7 @@ const JSX_PROP_ROLES = new Map([
   ['CommandInput', new Map([['placeholder', 'placeholder']])],
   ['Content', new Map([['title', 'title'], ['description', 'description']])],
   ['ContentHeader', new Map([['title', 'title'], ['description', 'description']])],
-  ['DataState', new Map([['emptyText', 'empty-state'], ['errorText', 'error']])],
+  ['DataState', new Map([['emptyMessage', 'empty-state'], ['errorMessage', 'error'], ['retryLabel', 'button']])],
   // A Dock nomeia a barra e cada ação por prop. Sem estas linhas, a copy sairia do inventário
   // exatamente quando uma superfície migra de <Button aria-label> para <DockAction label>.
   ['Dock', new Map([['label', 'label']])],
@@ -140,8 +156,14 @@ const JSX_PROP_ROLES = new Map([
   ['Input', new Map([['placeholder', 'placeholder']])],
   ['InputGroupInput', new Map([['placeholder', 'placeholder']])],
   ['InputGroupTextarea', new Map([['placeholder', 'placeholder']])],
+  // A ajuda vive num tooltip (portal): não herda transformação nem classe do label.
+  ['LabelHelp', new Map([['help', 'helper-text']])],
   ['MetricCard', new Map([['label', 'label'], ['description', 'description']])],
   ['Page', new Map([['title', 'title'], ['description', 'description']])],
+  ['PageState', new Map([
+    ['title', 'title'], ['description', 'description'],
+    ['emptyMessage', 'empty-state'], ['errorMessage', 'error'], ['retryLabel', 'button'],
+  ])],
   ['Select', new Map([
     ['placeholder', 'placeholder'],
     ['searchPlaceholder', 'placeholder'],
@@ -215,6 +237,36 @@ const JSX_PORTAL_BOUNDARIES = new Set([
   'PopoverContent', 'TooltipContent',
 ])
 
+// Respostas imperativas `dialog.*` da UI Opus. O DialogHost renderiza em portal com classes
+// próprias; nenhuma transformação do chamador alcança o texto.
+const DIALOG_METHOD_ROLES = new Map([
+  ['alert', new Map([['title', 'title'], ['description', 'dialog-body'], ['body', 'dialog-body'], ['action', 'button']])],
+  ['confirm', new Map([
+    ['title', 'title'], ['description', 'dialog-body'], ['body', 'dialog-body'],
+    ['action', 'button'], ['cancel', 'button'],
+  ])],
+  ['prompt', new Map([
+    ['title', 'title'], ['description', 'dialog-body'], ['body', 'dialog-body'],
+    ['action', 'button'], ['cancel', 'button'], ['placeholder', 'placeholder'],
+  ])],
+  ['choose', new Map([['title', 'title'], ['description', 'dialog-body'], ['body', 'dialog-body']])],
+])
+
+// Métodos de array que não mutam o receptor. Os que devolvem os próprios elementos (num
+// array novo ou avulsos) exigem que o resultado também seja usado de forma estável; os
+// demais só produzem primitivos, novos objetos ou nada.
+const ARRAY_RETURNING_ARRAY_METHODS = new Set(['concat', 'filter', 'flat', 'slice', 'toReversed', 'toSorted'])
+const ELEMENT_PICKING_ARRAY_METHODS = new Set(['at', 'find', 'findLast'])
+const ELEMENT_ITERATING_ARRAY_METHODS = new Set([
+  'every', 'filter', 'find', 'findIndex', 'findLast', 'findLastIndex', 'flatMap', 'forEach', 'map', 'some',
+])
+const READ_ONLY_ARRAY_METHODS = new Set([
+  ...ARRAY_RETURNING_ARRAY_METHODS, ...ELEMENT_PICKING_ARRAY_METHODS, ...ELEMENT_ITERATING_ARRAY_METHODS,
+  'includes', 'indexOf', 'join', 'lastIndexOf',
+])
+// Cadeia que preserva os elementos entre o array literal e a iteração que os lê.
+const ELEMENT_PRESERVING_ARRAY_METHODS = new Set(['filter', 'slice', 'toReversed', 'toSorted'])
+
 const digest = (content) => createHash('sha256').update(content).digest('hex')
 const portable = (value) => value.split(path.sep).join('/')
 
@@ -421,6 +473,17 @@ function knownBindAction(call, checker) {
   return importedMemberName(call.expression, checker, (module) => CONTRACT_MODULES.has(module)) === 'bindAction'
 }
 
+/** Reconhece `dialog.confirm({...})` e `Opus.dialog.alert({...})` importados da UI Opus. */
+function knownDialogCall(call, checker) {
+  const callee = unwrap(call.expression)
+  if (
+    ts.isPropertyAccessExpression(callee) &&
+    DIALOG_METHOD_ROLES.has(callee.name.text) &&
+    importedMemberName(callee.expression, checker, uiModule) === 'dialog'
+  ) return { method: callee.name.text, field: `dialog.${callee.name.text}()` }
+  return null
+}
+
 function safeBindActionBinding(call, checker) {
   if (call.arguments.length < 2) return false
   const binding = unwrap(call.arguments[1])
@@ -521,6 +584,16 @@ function stableExpressionUse(node, checker, mode, stack) {
   const parent = carrier.parent
 
   if (assignmentTarget(carrier)) return false
+  if (consumerMode === 'aggregate' && ts.isCallExpression(parent) && parent.expression === carrier) {
+    const access = unwrap(carrier)
+    return (
+      ts.isPropertyAccessExpression(access) && arrayValued(access.expression, checker) &&
+      readOnlyArrayMethodUse(access.name.text, parent, checker, stack)
+    )
+  }
+  if (ts.isForOfStatement(parent) && parent.expression === carrier) {
+    return consumerMode === 'aggregate' && arrayValued(carrier, checker) && readOnlyForOfBinding(parent, checker)
+  }
   if (ts.isVariableDeclaration(parent) && parent.initializer === carrier) {
     if (!ts.isVariableDeclarationList(parent.parent) || (parent.parent.flags & ts.NodeFlags.Const) === 0) return false
     const aliases = bindingNames(parent.name, checker)
@@ -534,6 +607,8 @@ function stableExpressionUse(node, checker, mode, stack) {
   if (ts.isCallExpression(parent) && parent.arguments.some((argument) => argument === carrier)) {
     if (consumerMode === 'aggregate') {
       if (knownDictionaryFactory(parent, checker)) return true
+      // O DialogHost copia as opções (`{ ...options }`) e só as lê; nada muta o literal.
+      if (parent.arguments[0] === carrier && knownDialogCall(parent, checker) !== null) return true
       return knownContractFactory(parent, checker) && stableFactoryResult(parent, checker, stack)
     }
     if (
@@ -573,6 +648,166 @@ function stableReferences(binding, checker, mode, stack) {
   return stable
 }
 
+/**
+ * Um parâmetro de callback (ou variável de `for…of`) é somente leitura quando cada uso é
+ * `elemento.chave` fora de posição de atribuição. Strings são imutáveis, então uma leitura de
+ * propriedade nunca altera o rótulo literal; qualquer outro uso (spread, argumento, retorno,
+ * atribuição) poderia mutar ou fazer o objeto escapar e é rejeitado. Destructuring copia os
+ * valores de primeiro nível e, por isso, também não alcança o literal.
+ */
+function readOnlyElementBinding(name, checker) {
+  if (ts.isObjectBindingPattern(name)) return true
+  if (!ts.isIdentifier(name)) return false
+  const symbol = bindingSymbol(name, checker)
+  if (symbol === undefined) return false
+  let readOnly = true
+  const visit = (node) => {
+    if (!readOnly) return
+    if (ts.isIdentifier(node) && sameBinding(node, symbol, checker) && !declarationIdentifier(node, symbol)) {
+      const carrier = transparentCarrier(node)
+      const access = carrier.parent
+      readOnly =
+        (ts.isPropertyAccessExpression(access) || ts.isElementAccessExpression(access)) &&
+        access.expression === carrier && !assignmentTarget(access)
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(name.getSourceFile())
+  return readOnly
+}
+
+function readOnlyCallback(callback, checker) {
+  const value = callback === undefined ? null : unwrap(callback)
+  if (value === null || (!ts.isArrowFunction(value) && !ts.isFunctionExpression(value))) return false
+  // O terceiro parâmetro expõe o próprio array ao callback; índice e `thisArg` não.
+  if (value.parameters.length > 2) return false
+  const element = value.parameters[0]
+  if (element === undefined) return true
+  if (element.dotDotDotToken !== undefined || element.initializer !== undefined) return false
+  return readOnlyElementBinding(element.name, checker)
+}
+
+function readOnlyArrayMethodUse(method, call, checker, stack) {
+  if (!READ_ONLY_ARRAY_METHODS.has(method)) return false
+  if (ELEMENT_ITERATING_ARRAY_METHODS.has(method) && !readOnlyCallback(call.arguments[0], checker)) return false
+  if (ARRAY_RETURNING_ARRAY_METHODS.has(method) || ELEMENT_PICKING_ARRAY_METHODS.has(method)) {
+    return stableExpressionUse(call, checker, 'aggregate', stack)
+  }
+  return true
+}
+
+/**
+ * A semântica somente leitura de `map`, `filter`… vale para arrays. Um objeto literal pode
+ * declarar um método com o mesmo nome e mutar o que quiser; por isso o receptor precisa ser
+ * um `const` com array literal ou o resultado de um método que devolve array sobre ele.
+ */
+function arrayValued(node, checker) {
+  const value = unwrap(node)
+  if (ts.isIdentifier(value)) {
+    const binding = constInitializer(value, checker)
+    return binding !== null && ts.isArrayLiteralExpression(unwrap(binding.initializer))
+  }
+  if (ts.isCallExpression(value)) {
+    const callee = unwrap(value.expression)
+    return ts.isPropertyAccessExpression(callee) && ARRAY_RETURNING_ARRAY_METHODS.has(callee.name.text) &&
+      arrayValued(callee.expression, checker)
+  }
+  return ts.isArrayLiteralExpression(value)
+}
+
+function readOnlyForOfBinding(statement, checker) {
+  const initializer = statement.initializer
+  if (!ts.isVariableDeclarationList(initializer) || initializer.declarations.length !== 1) return false
+  return readOnlyElementBinding(initializer.declarations[0].name, checker)
+}
+
+/**
+ * Localiza o array literal do qual um identificador é elemento: parâmetro de callback de
+ * `map`/`forEach`/`filter`… ou variável de `for…of`, possivelmente atrás de `filter`,
+ * `slice`, `toSorted` e `toReversed`, que preservam os elementos. Só arrays literais no
+ * mesmo arquivo entram; qualquer outra origem devolve null.
+ */
+function elementSource(identifier, checker) {
+  const symbol = bindingSymbol(identifier, checker)
+  const declaration = symbol?.declarations?.find(
+    (item) => ts.isParameter(item) || ts.isBindingElement(item) || ts.isVariableDeclaration(item),
+  )
+  if (declaration === undefined) return null
+
+  let key = null
+  let binding = declaration
+  if (ts.isBindingElement(declaration)) {
+    if (declaration.dotDotDotToken !== undefined || declaration.initializer !== undefined) return null
+    const pattern = declaration.parent
+    if (!ts.isObjectBindingPattern(pattern) || (!ts.isParameter(pattern.parent) && !ts.isVariableDeclaration(pattern.parent))) return null
+    const keyNode = declaration.propertyName ?? declaration.name
+    if (!ts.isIdentifier(keyNode) && !ts.isStringLiteral(keyNode)) return null
+    key = keyNode.text
+    binding = pattern.parent
+  }
+
+  let receiver
+  if (ts.isParameter(binding)) {
+    if (binding.dotDotDotToken !== undefined || binding.initializer !== undefined) return null
+    const callback = binding.parent
+    if ((!ts.isArrowFunction(callback) && !ts.isFunctionExpression(callback)) || callback.parameters[0] !== binding) return null
+    const call = transparentCarrier(callback).parent
+    if (!ts.isCallExpression(call) || call.arguments[0] !== transparentCarrier(callback)) return null
+    const callee = unwrap(call.expression)
+    if (!ts.isPropertyAccessExpression(callee) || !ELEMENT_ITERATING_ARRAY_METHODS.has(callee.name.text)) return null
+    receiver = callee.expression
+  } else if (ts.isVariableDeclaration(binding)) {
+    const list = binding.parent
+    if (!ts.isVariableDeclarationList(list) || !ts.isForOfStatement(list.parent) || list.parent.initializer !== list) return null
+    receiver = list.parent.expression
+  } else return null
+
+  let source = unwrap(receiver)
+  while (
+    ts.isCallExpression(source) && ts.isPropertyAccessExpression(unwrap(source.expression)) &&
+    ELEMENT_PRESERVING_ARRAY_METHODS.has(unwrap(source.expression).name.text)
+  ) source = unwrap(unwrap(source.expression).expression)
+  const array = resolveBinding(source, checker)
+  return ts.isArrayLiteralExpression(array) ? { array, key } : null
+}
+
+/**
+ * Resolve `elemento.chave` (ou a chave destruturada) para o texto literal de cada elemento
+ * do array de origem. Um único elemento opaco ou sem texto estático torna o conjunto todo
+ * inextraível: o inventário não pode listar só parte do que a superfície renderiza.
+ */
+function elementTexts(node, checker) {
+  const value = unwrap(node)
+  let identifier
+  let key = null
+  if (ts.isPropertyAccessExpression(value) && ts.isIdentifier(unwrap(value.expression))) {
+    identifier = unwrap(value.expression)
+    key = value.name.text
+  } else if (ts.isElementAccessExpression(value) && ts.isIdentifier(unwrap(value.expression))) {
+    identifier = unwrap(value.expression)
+    key = value.argumentExpression === undefined ? null : staticText(value.argumentExpression, checker)?.text ?? null
+  } else if (ts.isIdentifier(value)) {
+    identifier = value
+  } else return null
+  const source = elementSource(identifier, checker)
+  if (source === null) return null
+  if (ts.isIdentifier(value)) key = source.key
+  else if (source.key !== null) return null
+  if (key === null) return null
+
+  const listed = objects(source.array, checker)
+  if (listed.opaque.length > 0 || listed.values.length === 0) return null
+  const texts = []
+  for (const element of listed.values) {
+    const resolved = property(element, key, element.getSourceFile(), checker)
+    if (resolved.opaque !== undefined || resolved.candidate === undefined) return null
+    const text = staticText(propertyValue(resolved.candidate), checker)
+    if (text === null) return null
+    texts.push(text)
+  }
+  return texts
+}
+
 /**
  * Objetos e arrays `const` continuam mutáveis. A extração só faz fold quando cada uso
  * está numa allowlist observável: composição `const` igualmente estável, factory Opus
@@ -982,7 +1217,6 @@ export function extractCopyFromSource(file, sourceText) {
   const field = (object, prefix) => {
     addProperty(object, 'label', 'label', prefix)
     addProperty(object, 'placeholder', 'placeholder', prefix)
-    addProperty(object, 'hint', 'helper-text', prefix)
     addProperty(object, 'help', 'helper-text', prefix)
     nestedObject(object, 'options', optionItems, prefix)
   }
@@ -1384,6 +1618,11 @@ export function extractCopyFromSource(file, sourceText) {
         ? { kind: 'decorative' }
         : { kind: 'text', ...text, uppercase: inheritedUppercase }
     }
+    const listed = elementTexts(value, checker)
+    if (listed !== null) {
+      const values = listed.map((item) => ({ kind: 'text', ...item, uppercase: inheritedUppercase }))
+      return values.length === 1 ? values[0] : { kind: 'alternatives', values, node: values[0].node }
+    }
     if (ts.isJsxElement(value) || ts.isJsxSelfClosingElement(value) || ts.isJsxFragment(value)) {
       return childNode(value, inheritedUppercase, hiddenAncestor)
     }
@@ -1439,6 +1678,9 @@ export function extractCopyFromSource(file, sourceText) {
     if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child)) {
       const opening = ts.isJsxElement(child) ? child.openingElement : child
       const component = opusComponent(opening.tagName)
+      if (component !== null && SELF_CONTAINED_CHILD_COMPONENTS.has(component) && ts.isJsxSelfClosingElement(child)) {
+        return { kind: 'decorative' }
+      }
       const provenElement = transformableElement(opening, component)
       const hidden = attribute(opening.attributes, 'aria-hidden')
       if (hidden.opaque !== undefined) return { kind: 'opaque', node: hidden.opaque }
@@ -1593,7 +1835,10 @@ export function extractCopyFromSource(file, sourceText) {
     if (component === null) return
     let inherited
     const inheritedFor = (className, styleName, portal = false) => {
-      if (portal || localTransformOverridesInheritance(opening.attributes, className, styleName)) return false
+      // Um componente que renderiza em portal (TooltipContent) não é descendente visual
+      // dos ancestrais no JSX; a transformação deles não alcança o texto.
+      if (portal || JSX_PORTAL_BOUNDARIES.has(component)) return false
+      if (localTransformOverridesInheritance(opening.attributes, className, styleName)) return false
       inherited ??= ancestorTransform(element)
       return inherited.opaque ? false : inherited.uppercase
     }
@@ -1676,7 +1921,11 @@ export function extractCopyFromSource(file, sourceText) {
           }
         } else {
           const value = raw === null ? null : attributeText(item)
-          if (value === null) {
+          // `title={group.label}` dentro de `GROUPS.map(...)`: cada literal do array local
+          // vira um texto na própria linha, em vez de um diagnóstico sobre a prop.
+          const listed = value === null && raw !== null ? elementTexts(raw, checker) : null
+          const texts = value !== null ? [value] : listed ?? []
+          if (texts.length === 0) {
             diagnostics.push(diagnostic(
               file,
               sourceFile,
@@ -1685,8 +1934,8 @@ export function extractCopyFromSource(file, sourceText) {
               raw === null ? 'missing-content' : 'content',
             ))
           }
-          else {
-            const entry = { source: file, line: lineOf(sourceFile, value.node), role, text: value.text }
+          for (const text of texts) {
+            const entry = { source: file, line: lineOf(sourceFile, text.node), role, text: text.text }
             if (transformed.uppercase) entry.transform = 'uppercase'
             entries.push(entry)
           }
@@ -1838,7 +2087,28 @@ export function extractCopyFromSource(file, sourceText) {
     }
   }
 
+  /**
+   * `dialog.confirm({ title, description, action })` é copy tão editorial quanto a de um
+   * `<ActionFormDialog>`; a chamada só é imperativa. Um template com interpolação
+   * (`description: describe(name)`) cai no diagnóstico `content` normal, declarável em
+   * `copy.dynamic` como `message-template`.
+   */
+  function extractDialog(call, { method, field }) {
+    const raw = call.arguments[0]
+    const options = raw === undefined ? null : resolveBinding(raw, checker)
+    if (options === null || !ts.isObjectLiteralExpression(options)) {
+      diagnostics.push(diagnostic(file, sourceFile, raw ?? call, `${field} options`, 'structure'))
+      return
+    }
+    for (const [name, role] of DIALOG_METHOD_ROLES.get(method)) addVisualObjectProperty(options, name, role, `${field}.`)
+    if (method === 'choose') {
+      nestedObject(options, 'actions', (action, prefix) => addVisualObjectProperty(action, 'label', 'button', prefix), `${field}.`)
+    }
+  }
+
   function visit(node) {
+    const dialogCall = ts.isCallExpression(node) ? knownDialogCall(node, checker) : null
+    if (dialogCall !== null) extractDialog(node, dialogCall)
     const factory = ts.isCallExpression(node) ? contractFactory(node.expression) : null
     if (ts.isCallExpression(node) && factory !== null && node.arguments.length > 0) {
       hasContract = true

package/docs/code-style.md

@@ -86,13 +86,16 @@ Base instalada é dona do catálogo, dos kinds aceitos e do fundamento de cada r
 | `messages.success`, `messages.error`, `messages.confirmation` | `success`, `error`, `message` |
 | `confirm.message` | `dialog-body` |
 | `fields.*.label`, `filters.*.label` | `label` |
-| `placeholder`, `hint`, `help` | `placeholder`, `helper-text` |
+| `placeholder`, `help` | `placeholder`, `helper-text` |
 | opções estáticas | `menu-item` |
 | `columns[].label`, `periods[].label` | `heading`, `tab` |
 | `Select.emptyText`, `Select.searchPlaceholder` | `empty-state`, `placeholder` |
 | `Select.options[].hint/triggerLabel/group` | `label`, `label`, `heading` |
 | `ActionTrigger.confirm.*` | papel correspondente do diálogo |
 | `t.dict` — `label`, `description`, `doc` das entradas e `doc` do dicionário | `label`, `description` |
+| `DataState`/`PageState`/`ActionList`/`ActionListDialog` — `emptyMessage`, `errorMessage`, `retryLabel`; `PageState`/`ActionListDialog` — `title`, `description`; `ActionView.emptyMessage` | `empty-state`, `error`, `button`, `title`, `description` |
+| `dialog.alert/confirm/prompt/choose()` — `title`, `description`, `body`, `action`, `cancel`, `placeholder`, `actions[].label` | papel correspondente do diálogo |
+| `TooltipContent` (children), `LabelHelp.help` | `label`, `helper-text` |
 
 ## Cobertura e significado do gate verde
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "13.1.0",
+  "version": "14.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/registry/instructions/opus.md

@@ -17,9 +17,9 @@ artefatos de agentes fica em `base.json`; cada app Opus mantém seu marcador `op
 - Não duplicar schemas, tipos de transporte, validação ou fetch que o contrato já fornece.
 - Em UI semântica, declarar primeiro `context` (`neutral`, `primary`, `info`, `success`, `warning`
   ou `danger`) e usar `variant` somente para o tratamento visual (`solid`, `subtle`, `outline`,
-  `ghost` ou `link`). Dicionários de status e estágio declaram `context`; `tone` e variantes
-  semânticas antigas são apenas compatibilidade de migração. `destructive` permanece uma
-  propriedade comportamental de actions e se projeta visualmente como `danger`.
+  `ghost` ou `link`). Dicionários de status e estágio declaram `context`; `tone` é apenas
+  compatibilidade de migração e as variantes semânticas antigas não existem mais. `destructive`
+  permanece uma propriedade comportamental de actions e se projeta visualmente como `danger`.
 - Declarar datasets persistentes com `defineSeed` + `bindSeed`, registrá-los em `opus.config.ts`
   e operá-los por `opus seed`; não criar comandos de seed paralelos nem reset implícito.
 - Regenerar o inventário com `opus copy` quando mudar copy em contrato ou componente Opus

package/registry/templates/app/src/App.tsx

@@ -1,5 +1,5 @@
 import type { z } from 'zod'
-import { Badge, Card, useListAction } from '@softize/opus/ui/react'
+import { Badge, Card, DataState, useListAction } from '@softize/opus/ui/react'
 import { Task, taskList } from './domains/tasks/actions/list.ts'
 
 type TaskItem = z.infer<typeof Task>
@@ -10,7 +10,7 @@ export function App(): React.ReactElement {
   // O front consome o CONTRATO via /api — o plugin opusDesign (vite.config.ts)
   // serve o backend no próprio dev server: dev normal executa o handler real;
   // `pnpm dev:design` responde com o mockHandler, isolado de qualquer backend.
-  const { items, isLoading } = useListAction<TaskItem>(taskList)
+  const { items, isLoading, error, refetch } = useListAction<TaskItem>(taskList)
 
   return (
     <main className="flex min-h-full items-center justify-center bg-background p-6">
@@ -19,9 +19,14 @@ export function App(): React.ReactElement {
         <p className="mb-4 text-sm text-muted-foreground">
           Esqueleto criado pelo opus create. A spec vive nas declarações do domínio.
         </p>
-        {isLoading ? (
-          <p className="text-sm text-muted-foreground">Carregando…</p>
-        ) : (
+        {/* Carregando, erro e vazio saem do DataState; a lista só cuida dos itens. */}
+        <DataState
+          loading={isLoading}
+          error={error ?? null}
+          empty={items.length === 0}
+          emptyMessage="Nenhuma tarefa ainda."
+          onRetry={() => refetch()}
+        >
           <ul className="space-y-2">
             {items.map((t) => (
               <li key={t.id} className="flex items-center justify-between gap-2 text-sm">
@@ -30,7 +35,7 @@ export function App(): React.ReactElement {
               </li>
             ))}
           </ul>
-        )}
+        </DataState>
       </Card>
     </main>
   )

package/src/core/types.ts

@@ -551,9 +551,8 @@ export type FieldWidget = BuiltInFieldWidget | (string & { readonly __opusCustom
 export interface FieldSpec {
   label: I18nRef
   placeholder?: I18nRef
-  hint?: I18nRef
-  /** Ajuda no hover/foco da label (ícone ⓘ + tooltip). `hint` = texto auxiliar SOB o campo;
-   *  `help` = explicação mais longa, escondida atrás do ícone na label. */
+  /** Ajuda junto à label (ícone ⓘ + tooltip): critério, efeito ou limitação que a label não
+   *  diz. Ajuda que só repete a label deve ser omitida. */
   help?: I18nRef
 
   default?: unknown
@@ -629,7 +628,7 @@ export interface ListColumnSpec {
    *  'badge' (chip `outline` com o valor — legado; coluna de dicionário com `presentation`
    *  declarado usa `DictionaryValue` e dispensa este tipo). */
   type?: 'text' | 'number' | 'date' | 'badge'
-  /** Referência do dicionário registrado em `TbdlibProvider dicts` que esta coluna mostra,
+  /** Referência do dicionário registrado em `OpusProvider dicts` que esta coluna mostra,
    *  quando o schema de saída não carrega a meta de `t.dict` (ex.: campo `z.string()`).
    *  Coluna cujo campo de saída É um `t.dict().zod()` resolve sozinha, sem esta chave. */
   dictionary?: string

package/src/ui/components/patterns/action-list-dialog.tsx

@@ -37,7 +37,10 @@ export interface ActionListDialogProps<TItem, TInput extends Record<string, unkn
   note?: ReactNode
   /** Ação à direita da linha — em geral o botão de criar. */
   actions?: ReactNode
-  emptyText?: string
+  /** Textos dos estados, repassados ao ActionList (e dele ao DataState). */
+  emptyMessage?: string
+  errorMessage?: string
+  retryLabel?: string
   /** Sobrepõe o vazio derivado (items.length === 0) — ex.: form inline aberto. */
   empty?: (items: TItem[]) => boolean
   /** Carga EXTRA agregada à do fetch (ex.: a query irmã que os children precisam). */
@@ -57,7 +60,9 @@ export function ActionListDialog<TItem, TInput extends Record<string, unknown> =
   description,
   note,
   actions,
-  emptyText,
+  emptyMessage,
+  errorMessage,
+  retryLabel,
   empty,
   loading,
   className,
@@ -80,7 +85,9 @@ export function ActionListDialog<TItem, TInput extends Record<string, unknown> =
           <ActionList<TInput, TItem>
             action={action as unknown as ListAction<TInput, TItem>}
             input={(input ?? {}) as TInput}
-            {...(emptyText !== undefined ? { emptyMessage: emptyText } : {})}
+            {...(emptyMessage !== undefined ? { emptyMessage } : {})}
+            {...(errorMessage !== undefined ? { errorMessage } : {})}
+            {...(retryLabel !== undefined ? { retryLabel } : {})}
             {...(empty !== undefined ? { empty } : {})}
             {...(loading !== undefined ? { loading } : {})}
           >