@softize/opus 18.1.1 → 18.3.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ 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.
 
+## 18.3.0 — 2026-09-17
+
+`ActionList` passa a oferecer composição previsível para barras densas: filtros inline de valor
+único abraçam o conteúdo até o limite da barra, a busca ocupa o espaço flexível restante, dropdowns
+podem ser mais largos que o controle e filtros pesquisáveis podem omitir a opção vazia. Valores de
+repouso, ícones por filtro, agrupamento de tipo de data com período e ícones nas seções avançadas
+ficam declarados pelas props do pattern. A barra deixa de transformar filtros inline em chips por
+falta de espaço; a página preserva sua largura mínima e delega o overflow à superfície correta.
+
+Listagens podem usar `layout="fill"` para ocupar a altura disponível e manter a rolagem dentro da
+tabela, com cabeçalho fixo e a mesma moldura nos estados vazio, carregando e erro. `Page` e
+`Presentation` propagam esse contrato sem criar uma segunda rolagem no frame.
+
+`MetricCard` aceita `secondaryMetric` para uma leitura complementar diretamente relacionada,
+exibida como lâmina posterior com explicação própria. `FieldLegend` aceita ícone e a variante
+`section`; o `Select` equaliza a ação de limpar com os demais campos e permite que sua lista cresça
+além do gatilho sem alterar o layout.
+
+## 18.2.0 — 2026-09-16
+
+`Presentation` passa a aceitar um body serializável baseado em componente. O contrato continua
+definindo rota, superfície, navegação e ações, enquanto a aplicação fornece o conteúdo React em
+tempo de execução. Assim, uma página pode adotar a casca dirigida por spec sem precisar migrar de
+uma vez toda a implementação interna para actions declarativas.
+
+Recursos podem declarar um gatilho de assistência contextual em `assistant`. A aplicação fornece o
+painel e os dados vivos do recurso por `assistant.render`; identidade, autorização e demais dados
+não entram no manifest. O novo `SurfaceAssistant`, também disponível pela API pública, divide
+somente o body de Page, Dialog ou Drawer. Cabeçalho e rodapé permanecem em toda a largura, e o
+gatilho sai do cabeçalho enquanto o painel aberto assume a identidade visual da assistência.
+
+O split contextual usa um único separador redimensionável, sem sobrepor uma segunda borda entre o
+conteúdo e o painel. O conteúdo principal permanece montado durante a conversa e volta a ocupar
+toda a largura quando ela é fechada.
+
 ## 18.1.1 — 2026-09-16
 
 **Correção de segurança.** Quem executa tools de IA só roda o que `aiTools()` anunciou. Até aqui, o

package/package.json

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

package/registry/skills/build-opus-ui/SKILL.md

@@ -37,8 +37,9 @@ existentes, mantendo navegação observável e componentes reutilizáveis sem la
    permanece sempre presente.
 6. Deixar ausência, paginação e largura de filtro com o pattern: célula e `DetailField` já
    representam valor ausente (`EmptyValue`, `empty` para o significado do domínio); listas
-   paginam pela primitiva `Pagination`; selects inline de filtro têm largura fixa. Não reescrever
-   esses defaults na tela.
+   paginam pela primitiva `Pagination`; selects inline de valor único abraçam o valor até o limite
+   definido pela barra, e o menu pode ser mais largo que o controle. Não reescrever esses defaults
+   na tela.
 7. Tratar página, filtro, seleção e modal importante como estado navegável por URL quando
    o produto precisa de deep link, back/forward ou refresh. Em `Presentation`, declarar `route`
    no artefato e deixar o adaptador apenas conectar a spec ao router da aplicação.

package/registry/skills/build-opus-ui/references/ui-patterns.md

@@ -122,9 +122,10 @@ ContentDescription, ContentMeta, ContentActions) + ContentBody`. `ContentHeader`
 - Paginação é a primitiva `Pagination`, inclusive dentro de `ActionList`. Número de página tem
   largura mínima e cresce com os dígitos; só as setas são quadradas. Não montar paginador com
   `Button` nem prender números a `size-*`.
-- Select inline de filtro tem largura fixa (`w-40`; lookup e múltiplo `w-52`): a label trunca, o
-  valor trunca no trigger e a opção inteira fica na lista. Não dimensionar filtro pelo conteúdo
-  nem pela label; o modal usa `w-full`.
+- Select inline de valor único abraça o valor selecionado até `max-w-80`. Acima desse limite, o
+  valor trunca no gatilho e a opção inteira permanece na lista, que pode ser mais larga.
+  Multiseleção mantém `w-52`; o modal usa `w-full`. Não recalcular essa largura na tela nem
+  dimensioná-la pela label do filtro.
 - Catálogo e API efetivos vêm dos exports da versão instalada, não de memória ou exemplo antigo.
 - Em componentes semânticos, `context` responde por que há destaque e `variant` responde como ele
   aparece. O vocabulário canônico é `neutral | primary | info | success | warning | danger`; as

package/src/core/errors.ts

@@ -93,7 +93,6 @@ class ActionErrorImpl extends Error implements ActionError {
   readonly i18nParams?: Record<string, unknown>
   readonly field?: string
   readonly issues?: ValidationIssue[]
-  override readonly cause?: unknown
   readonly meta?: Record<string, unknown>
 
   constructor(input: ErrorInput) {

package/src/core/presentation.ts

@@ -90,7 +90,7 @@ const presentationFieldSchema = z
   })
   .strict();
 
-const presentationBodySchema = z
+const presentationActionBodySchema = z
   .object({
     action: z.string().min(1),
     input: z.record(presentationBindingSchema).default({}),
@@ -108,6 +108,27 @@ const presentationBodySchema = z
   })
   .strict();
 
+const presentationComponentBodySchema = z
+  .object({
+    /** Boundary estático do conteúdo React fornecido pelo consumidor. */
+    component: identifierSchema,
+    /** Define se o heading principal nasce na casca ou no conteúdo React. */
+    heading: z.enum(["shell", "content"]).default("shell"),
+  })
+  .strict();
+
+const presentationBodySchema = z.union([
+  presentationActionBodySchema,
+  presentationComponentBodySchema,
+]);
+
+const presentationAssistantSchema = z
+  .object({
+    /** Nome acessível do botão que abre a assistência contextual. */
+    triggerLabel: z.string().min(1),
+  })
+  .strict();
+
 const presentationRouteRecordSchema = z
   .object({
     presentation: identifierSchema,
@@ -136,6 +157,7 @@ export const presentationSchema = z
     title: z.string().min(1),
     route: presentationRouteSchema.optional(),
     body: presentationBodySchema,
+    assistant: presentationAssistantSchema.optional(),
     actions: z.array(presentationCommandSchema).default([]),
   })
   .strict();
@@ -143,6 +165,12 @@ export const presentationSchema = z
 export type PresentationDefinition = z.infer<typeof presentationSchema>;
 export type PresentationDefinitionInput = z.input<typeof presentationSchema>;
 export type PresentationCommand = PresentationDefinition["actions"][number];
+export type PresentationActionBody = z.infer<
+  typeof presentationActionBodySchema
+>;
+export type PresentationComponentBody = z.infer<
+  typeof presentationComponentBodySchema
+>;
 type DefaultedProperty<
   Input,
   Key extends PropertyKey,
@@ -174,27 +202,48 @@ type DefinedPresentationEffects<
         }
       : PresentationCommand["onSuccess"]
   : PresentationCommand["onSuccess"];
-type PresentationOpen = NonNullable<PresentationDefinition["body"]["open"]>;
+type PresentationOpen = NonNullable<PresentationActionBody["open"]>;
 type DefinedPresentationOpen<Open> = Open extends object
   ? Omit<Open, "input"> &
       Omit<PresentationOpen, "input"> & {
         input: DefaultedProperty<Open, "input", PresentationOpen["input"]>;
       }
   : never;
+type DefinedPresentationActionBody<Body> =
+  Body extends z.input<typeof presentationActionBodySchema>
+    ? Omit<Body, "input" | "open" | "onSuccess"> &
+        Omit<PresentationActionBody, "input" | "open" | "onSuccess"> & {
+          input: DefaultedProperty<
+            Body,
+            "input",
+            PresentationActionBody["input"]
+          >;
+          onSuccess: DefinedPresentationEffects<Body, "onSuccess">;
+        } & ("open" extends keyof Body
+          ? undefined extends Body["open"]
+            ? {
+                open?: DefinedPresentationOpen<
+                  Exclude<Body["open"], undefined>
+                >;
+              }
+            : { open: DefinedPresentationOpen<Body["open"]> }
+          : { open?: PresentationActionBody["open"] })
+    : never;
+type DefinedPresentationComponentBody<Body> =
+  Body extends z.input<typeof presentationComponentBodySchema>
+    ? Omit<Body, "heading"> &
+        Omit<PresentationComponentBody, "heading"> & {
+          heading: DefaultedProperty<
+            Body,
+            "heading",
+            PresentationComponentBody["heading"]
+          >;
+        }
+    : never;
 type DefinedPresentationBody<Body extends PresentationDefinitionInput["body"]> =
-  Omit<Body, "input" | "open" | "onSuccess"> &
-    Omit<PresentationDefinition["body"], "input" | "open" | "onSuccess"> & {
-      input: DefaultedProperty<
-        Body,
-        "input",
-        PresentationDefinition["body"]["input"]
-      >;
-      onSuccess: DefinedPresentationEffects<Body, "onSuccess">;
-    } & ("open" extends keyof Body
-      ? undefined extends Body["open"]
-        ? { open?: DefinedPresentationOpen<Exclude<Body["open"], undefined>> }
-        : { open: DefinedPresentationOpen<Body["open"]> }
-      : { open?: PresentationDefinition["body"]["open"] });
+  Body extends { component: string }
+    ? DefinedPresentationComponentBody<Body>
+    : DefinedPresentationActionBody<Body>;
 type DefinedPresentationCommand<Command> = Command extends object
   ? Omit<Command, "input" | "blocking" | "onSuccess"> &
       Omit<PresentationCommand, "input" | "blocking" | "onSuccess"> & {
@@ -272,6 +321,18 @@ export interface PresentationActionRegistry {
   readonly [name: string]: ActionContract;
 }
 
+export function isPresentationActionBody(
+  body: PresentationDefinition["body"],
+): body is PresentationActionBody {
+  return "action" in body;
+}
+
+export function isPresentationComponentBody(
+  body: PresentationDefinition["body"],
+): body is PresentationComponentBody {
+  return "component" in body;
+}
+
 export interface PresentationRouteMatch {
   definition: PresentationDefinition;
   input: Record<string, string>;
@@ -312,8 +373,7 @@ export function matchPresentationRoute(
         const decoded = decodeRouteSegment(received);
         if (decoded === null) return [];
         input[expected.slice(1)] = decoded;
-      }
-      else if (expected !== received) return [];
+      } else if (expected !== received) return [];
     }
     return [{ definition, input }];
   });
@@ -527,46 +587,53 @@ export function validatePresentations(
       problems.push(`Presentation “${presentation.id}” duplicada.`);
     byId.set(presentation.id, presentation);
 
-    const bodyAction = actions[presentation.body.action];
-    if (bodyAction === undefined) {
-      problems.push(
-        `A action “${presentation.body.action}” não está disponível.`,
-      );
-    } else if (bodyAction.kind === "simple") {
-      problems.push(
-        `A action simple “${bodyAction.name}” não pode ocupar o body.`,
-      );
+    if (isPresentationComponentBody(presentation.body)) {
+      // O conteúdo interno permanece uma fronteira React opaca para a spec da casca.
     } else {
-      validateActionBindings(
-        presentation.body.input,
-        bodyAction,
-        `${presentation.id}.body.input`,
-        problems,
-      );
-      if (
-        bodyAction.kind === "view" &&
-        presentation.body.fields === undefined
-      ) {
+      const bodyAction = actions[presentation.body.action];
+      if (bodyAction === undefined) {
         problems.push(
-          `A Presentation “${presentation.id}” precisa declarar fields para a view.`,
+          `A action “${presentation.body.action}” não está disponível.`,
         );
-      }
-      if (
-        bodyAction.kind !== "view" &&
-        presentation.body.fields !== undefined
-      ) {
-        problems.push(`Fields só podem ser declarados para uma action view.`);
-      }
-      if (bodyAction.kind !== "list" && presentation.body.open !== undefined) {
-        problems.push(`Open só pode ser declarado para uma action list.`);
-      }
-      if (
-        bodyAction.kind !== "form" &&
-        presentation.body.submitLabel !== undefined
-      ) {
+      } else if (bodyAction.kind === "simple") {
         problems.push(
-          `SubmitLabel só pode ser declarado para uma action form.`,
+          `A action simple “${bodyAction.name}” não pode ocupar o body.`,
+        );
+      } else {
+        validateActionBindings(
+          presentation.body.input,
+          bodyAction,
+          `${presentation.id}.body.input`,
+          problems,
         );
+        if (
+          bodyAction.kind === "view" &&
+          presentation.body.fields === undefined
+        ) {
+          problems.push(
+            `A Presentation “${presentation.id}” precisa declarar fields para a view.`,
+          );
+        }
+        if (
+          bodyAction.kind !== "view" &&
+          presentation.body.fields !== undefined
+        ) {
+          problems.push(`Fields só podem ser declarados para uma action view.`);
+        }
+        if (
+          bodyAction.kind !== "list" &&
+          presentation.body.open !== undefined
+        ) {
+          problems.push(`Open só pode ser declarado para uma action list.`);
+        }
+        if (
+          bodyAction.kind !== "form" &&
+          presentation.body.submitLabel !== undefined
+        ) {
+          problems.push(
+            `SubmitLabel só pode ser declarado para uma action form.`,
+          );
+        }
       }
     }
 
@@ -615,7 +682,10 @@ export function validatePresentations(
           problems.push(
             `A route de “${presentation.id}” consulta a Presentation inexistente “${record.presentation}”.`,
           );
-        } else if (actions[source.body.action]?.kind !== "list") {
+        } else if (
+          !isPresentationActionBody(source.body) ||
+          actions[source.body.action]?.kind !== "list"
+        ) {
           problems.push(
             `A route de “${presentation.id}” exige que “${record.presentation}” tenha uma list action no body.`,
           );
@@ -633,7 +703,9 @@ export function validatePresentations(
         }
       }
     }
-    const open = presentation.body.open;
+    const open = isPresentationActionBody(presentation.body)
+      ? presentation.body.open
+      : undefined;
     if (open !== undefined && !byId.has(open.presentation)) {
       problems.push(
         `A lista “${presentation.id}” abre a Presentation inexistente “${open.presentation}”.`,
@@ -650,7 +722,9 @@ export function validatePresentations(
         );
       }
       const action =
-        target === undefined ? undefined : actions[target.body.action];
+        target !== undefined && isPresentationActionBody(target.body)
+          ? actions[target.body.action]
+          : undefined;
       if (action !== undefined) {
         validateActionBindings(
           open.input,
@@ -660,7 +734,10 @@ export function validatePresentations(
         );
       }
     }
-    for (const effect of presentation.body.onSuccess) {
+    const bodyEffects = isPresentationActionBody(presentation.body)
+      ? presentation.body.onSuccess
+      : [];
+    for (const effect of bodyEffects) {
       if (effect.effect !== "navigate") continue;
       const target = byId.get(effect.presentation);
       if (target === undefined) {
@@ -678,7 +755,9 @@ export function validatePresentations(
           `O body de “${presentation.id}” navega para “${target.id}” como ${effect.surface}, mas sua route declara ${target.route.surface}.`,
         );
       }
-      const action = actions[target.body.action];
+      const action = isPresentationActionBody(target.body)
+        ? actions[target.body.action]
+        : undefined;
       if (action !== undefined) {
         validateActionBindings(
           effect.input,
@@ -706,7 +785,9 @@ export function validatePresentations(
                 `A action “${command.action}” navega para “${target.id}” como ${effect.surface}, mas sua route declara ${target.route.surface}.`,
               );
             }
-            const action = actions[target.body.action];
+            const action = isPresentationActionBody(target.body)
+              ? actions[target.body.action]
+              : undefined;
             if (action !== undefined) {
               validateActionBindings(
                 effect.input,
@@ -724,6 +805,10 @@ export function validatePresentations(
         problems.push(
           `A action “${command.action}” abre a Presentation inexistente “${command.target.presentation}”.`,
         );
+      } else if (!isPresentationActionBody(target.body)) {
+        problems.push(
+          `A Presentation “${target.id}” usa conteúdo de componente e não pode ser aberta pela action “${command.action}”.`,
+        );
       } else if (target.body.action !== command.action) {
         problems.push(
           `A Presentation “${target.id}” usa “${target.body.action}”, mas foi aberta por “${command.action}”.`,

package/src/core/types.ts

@@ -598,6 +598,10 @@ export interface FilterSpec {
 
   type: 'text' | 'select' | 'lookup' | 'date' | 'number'
   multiple?: boolean
+  /** Habilita busca local nas opções de um `select`; `lookup` já é pesquisável por natureza. */
+  searchable?: boolean
+  /** Quando `false`, a interface omite a opção vazia. Limpar restaura o default do filtro. */
+  allowEmpty?: boolean
   mode?: 'server' | 'client'
   operators?: FilterOp[]
   path?: string

package/src/ui/components/patterns/data-state.tsx

@@ -75,7 +75,7 @@ export function DataState({
   if (colSpan !== undefined) {
     return (
       <tr data-slot="data-state" data-status={status}>
-        <td colSpan={colSpan} className="px-4 py-4 text-center text-sm">
+        <td colSpan={colSpan} className="px-4 py-4 text-center align-middle text-sm">
           {surface}
         </td>
       </tr>