@softize/opus 18.1.1 → 18.3.0

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

@@ -32,11 +32,20 @@ shell que efetivamente hospeda a rota.
 O exemplo declara a Presentation sobre um contrato de formulário e alterna a superfície. O
 `DocBrowserActionProvider` simula o cliente de actions; na aplicação, esse papel é do provider real.
 
+Quando o recurso aceita assistência contextual, declare somente o gatilho serializável em
+`assistant`. O renderer coloca esse gatilho no cabeçalho e abre o painel à direita do body da
+própria Page, Dialog ou Drawer. Cabeçalho e rodapé continuam ocupando toda a largura da superfície;
+enquanto o painel está aberto, o gatilho sai do cabeçalho e o próprio painel assume sua identidade
+visual. O dado vivo do recurso não entra na definição: a página que o carregou fornece
+`assistant.render`, captura identidade, nome e demais dados autorizados e monta o chat. Assim,
+contexto de conversa não vira autorização nem dado persistido no manifest.
+
 ```tsx live
 const workspacePresentation = definePresentation({
   schemaVersion: 1,
   id: "workspace.create",
   title: "Criar workspace",
+  assistant: { triggerLabel: "Conversar sobre este workspace" },
   body: { action: docWorkspaceCreate.name },
 });
 
@@ -81,6 +90,22 @@ function Example() {
             if (next) setInvocation(next);
             else setOpen(false);
           }}
+          assistant={{
+            render: ({ close }) => (
+              <div className="flex h-full flex-col p-3">
+                <p className="text-sm">
+                  Conversa vinculada ao workspace carregado pela página.
+                </p>
+                <Button
+                  className="mt-3 self-start"
+                  variant="ghost"
+                  onClick={close}
+                >
+                  Fechar
+                </Button>
+              </div>
+            ),
+          }}
         />
       </div>
     </DocBrowserActionProvider>
@@ -164,21 +189,22 @@ no manifest e concentre a inspeção na Lens em vez de criar um launcher flutuan
 
 ## Propriedades de Presentation
 
-| Propriedade          | Tipo                                             | Padrão | Descrição                                              |
-| -------------------- | ------------------------------------------------ | ------ | ------------------------------------------------------ |
-| `definition`         | `PresentationDefinition`                         |        | Artefato estático que descreve o recurso.              |
-| `definitions`        | `PresentationDefinition[]`                       |        | Registry alcançável por navegação, abertura e retorno. |
-| `actions`            | `PresentationActionRegistry`                     |        | Contratos compartilháveis referenciados pelo artefato. |
-| `invocation`         | `PresentationInvocation`                         |        | Surface, input e pilha da exibição atual.              |
-| `bindingContext`     | `PresentationBindingContext`                     |        | Rota, item, seleção, sessão e resultado disponíveis.   |
-| `onInvocationChange` | `(next: PresentationInvocation \| null) => void` |        | Recebe navegação, retorno e fechamento.                |
-| `onRefresh`          | `(action: string \| null) => void`               |        | Recebe invalidações declaradas após sucesso.           |
-| `listState`          | `ActionListState`                                |        | Recorte controlado da action `list` do body, quando a aplicação o sincroniza com a URL. |
+| Propriedade          | Tipo                                             | Padrão | Descrição                                                                                           |
+| -------------------- | ------------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------- |
+| `definition`         | `PresentationDefinition`                         |        | Artefato estático que descreve o recurso.                                                           |
+| `definitions`        | `PresentationDefinition[]`                       |        | Registry alcançável por navegação, abertura e retorno.                                              |
+| `actions`            | `PresentationActionRegistry`                     |        | Contratos compartilháveis referenciados pelo artefato.                                              |
+| `invocation`         | `PresentationInvocation`                         |        | Surface, input e pilha da exibição atual.                                                           |
+| `bindingContext`     | `PresentationBindingContext`                     |        | Rota, item, seleção, sessão e resultado disponíveis.                                                |
+| `assistant`          | `PresentationAssistantRuntime`                   |        | Painel contextual fornecido pela superfície hospedeira.                                             |
+| `onInvocationChange` | `(next: PresentationInvocation \| null) => void` |        | Recebe navegação, retorno e fechamento.                                                             |
+| `onRefresh`          | `(action: string \| null) => void`               |        | Recebe invalidações declaradas após sucesso.                                                        |
+| `listState`          | `ActionListState`                                |        | Recorte controlado da action `list` do body, quando a aplicação o sincroniza com a URL.             |
 | `onListStateChange`  | `(state: ActionListState) => void`               |        | Recebe cada mudança de recorte ou exibição da lista do body, como busca, filtros, período e página. |
-| `open`               | `boolean`                                        | `true` | Estado controlado de Dialog ou Drawer.                 |
-| `onOpenChange`       | `(open: boolean) => void`                        |        | Notifica abertura e fechamento da superfície modal.    |
-| `className`          | `string`                                         |        | Classes adicionais da superfície.                      |
-| `bodyClassName`      | `string`                                         |        | Classes adicionais do body, aplicadas uma única vez.   |
+| `open`               | `boolean`                                        | `true` | Estado controlado de Dialog ou Drawer.                                                              |
+| `onOpenChange`       | `(open: boolean) => void`                        |        | Notifica abertura e fechamento da superfície modal.                                                 |
+| `className`          | `string`                                         |        | Classes adicionais da superfície.                                                                   |
+| `bodyClassName`      | `string`                                         |        | Classes adicionais do body, aplicadas uma única vez.                                                |
 
 ## Propriedades de PresentationInspector
 

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

@@ -24,6 +24,10 @@ render(
 )
 ```
 
+O gatilho respeita a largura definida pelo contexto. Ao abrir, a lista usa essa largura como mínimo
+e pode crescer até `32rem` para preservar rótulos maiores sem alterar o layout do formulário ou da
+toolbar. Rótulos que ultrapassarem esse limite continuam truncados como proteção de layout.
+
 ## Lista pesquisável
 
 Use `searchable` quando a quantidade ou os rótulos dificultarem encontrar uma opção. O gatilho

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

@@ -12,11 +12,13 @@ render(
         <div className="p-4 text-sm">Navegação</div>
       </Pane>
       <Pane grow inset="lg">
-        <p className="text-sm text-muted-foreground">Conteúdo. Arraste a divisória.</p>
+        <p className="text-sm text-muted-foreground">
+          Conteúdo. Arraste a divisória.
+        </p>
       </Pane>
     </Split>
   </div>,
-)
+);
 ```
 
 ## Espaçamento interno
@@ -30,8 +32,12 @@ Quando uma área precisa continuar legível em telas largas, use uma unidade abs
 
 ```tsx
 <Split resizable>
-  <Pane grow inset="none"><Main /></Pane>
-  <Pane initialSize="28rem" minSize="20rem" inset="none"><Inspector /></Pane>
+  <Pane grow inset="none">
+    <Main />
+  </Pane>
+  <Pane initialSize="28rem" minSize="20rem" inset="none">
+    <Inspector />
+  </Pane>
 </Split>
 ```
 
@@ -75,23 +81,78 @@ const defaultLayout = readLayout('workspace-layout')
 
 Em aplicações renderizadas no servidor, leia o armazenamento somente no cliente. `onLayoutChanged` também permite usar `sessionStorage` ou uma camada própria quando o layout precisa acompanhar outro escopo.
 
+## Assistência dentro da superfície
+
+`SurfaceAssistant` especializa o split usado por uma Page, Dialog ou Drawer que abre assistência
+contextual. O conteúdo principal permanece montado e o painel aparece à direita com largura
+redimensionável. A superfície hospedeira controla o gatilho, o estado aberto e os dados passados ao
+painel; o pattern cuida apenas da relação espacial. Envolva somente o body da superfície com
+`SurfaceAssistant`: cabeçalho e rodapé devem permanecer fora do split e ocupar toda a largura.
+
+```tsx preview
+function Example() {
+  const [open, setOpen] = React.useState(true);
+
+  return (
+    <div className="h-72 overflow-hidden rounded-lg border border-border">
+      <SurfaceAssistant
+        open={open}
+        assistantLabel="Assistente do pedido"
+        assistant={
+          <div className="h-full p-3">
+            <p className="text-sm">Conversa vinculada ao pedido carregado.</p>
+            <Button
+              className="mt-3"
+              variant="ghost"
+              onClick={() => setOpen(false)}
+            >
+              Fechar
+            </Button>
+          </div>
+        }
+      >
+        <div className="h-full p-3">
+          <Button variant="outline" onClick={() => setOpen(true)}>
+            Abrir assistente
+          </Button>
+        </div>
+      </SurfaceAssistant>
+    </div>
+  );
+}
+
+render(<Example />);
+```
+
 ## Propriedades de Split
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `direction` | `'horizontal' \| 'vertical'` | `'horizontal'` | Sentido em que os panes se alinham. |
-| `resizable` | `boolean` | `false` | Cada fronteira ganha um separador acessível e arrastável. |
-| `handle` | `boolean` | `false` | Mostra a alça visual no separador. |
-| `id` | `string` | | Identidade estável do grupo redimensionável. |
-| `defaultLayout` | `Record<string, number>` | | Layout percentual restaurado, indexado pelos ids dos panes. |
-| `onLayoutChanged` | `(layout, { isUserInteraction }) => void` | | Chamado ao concluir uma mudança de layout; persista onde fizer sentido. |
+| Propriedade       | Tipo                                      | Padrão         | Descrição                                                               |
+| ----------------- | ----------------------------------------- | -------------- | ----------------------------------------------------------------------- |
+| `direction`       | `'horizontal' \| 'vertical'`              | `'horizontal'` | Sentido em que os panes se alinham.                                     |
+| `resizable`       | `boolean`                                 | `false`        | Cada fronteira ganha um separador acessível e arrastável.               |
+| `handle`          | `boolean`                                 | `false`        | Mostra a alça visual no separador.                                      |
+| `id`              | `string`                                  |                | Identidade estável do grupo redimensionável.                            |
+| `defaultLayout`   | `Record<string, number>`                  |                | Layout percentual restaurado, indexado pelos ids dos panes.             |
+| `onLayoutChanged` | `(layout, { isUserInteraction }) => void` |                | Chamado ao concluir uma mudança de layout; persista onde fizer sentido. |
 
 ## Propriedades de Pane
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `id` | `string` | | Identidade estável usada pelo layout redimensionável e persistido. |
-| `initialSize` | `number \| string` | | Tamanho inicial; número é porcentagem, string aceita `%`, `rem`, `em`, `vh`, `vw` e `px`. |
-| `minSize` / `maxSize` | `number \| string` | | Limites quando o split é redimensionável. |
-| `grow` | `boolean` | `false` | Ocupa o espaço remanescente no layout simples. |
-| `inset` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Respiro interno; `none` para chrome, navegação ou conteúdo com inset próprio. |
+| Propriedade           | Tipo                             | Padrão  | Descrição                                                                                 |
+| --------------------- | -------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
+| `id`                  | `string`                         |         | Identidade estável usada pelo layout redimensionável e persistido.                        |
+| `initialSize`         | `number \| string`               |         | Tamanho inicial; número é porcentagem, string aceita `%`, `rem`, `em`, `vh`, `vw` e `px`. |
+| `minSize` / `maxSize` | `number \| string`               |         | Limites quando o split é redimensionável.                                                 |
+| `grow`                | `boolean`                        | `false` | Ocupa o espaço remanescente no layout simples.                                            |
+| `inset`               | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'`  | Respiro interno; `none` para chrome, navegação ou conteúdo com inset próprio.             |
+
+## Propriedades de SurfaceAssistant
+
+| Propriedade      | Tipo        | Padrão  | Descrição                                               |
+| ---------------- | ----------- | ------- | ------------------------------------------------------- |
+| `open`           | `boolean`   |         | Exibe o painel complementar à direita.                  |
+| `assistantLabel` | `string`    |         | Nome acessível da região complementar.                  |
+| `children`       | `ReactNode` |         | Conteúdo principal que permanece montado.               |
+| `assistant`      | `ReactNode` |         | Painel fornecido pela superfície que conhece o recurso. |
+| `initialSize`    | `PaneSize`  | `28rem` | Largura inicial do painel.                              |
+| `minSize`        | `PaneSize`  | `20rem` | Largura mínima durante o redimensionamento.             |
+| `maxSize`        | `PaneSize`  | `40rem` | Largura máxima durante o redimensionamento.             |

package/src/ui/meta.ts

@@ -81,7 +81,7 @@ export const componentMeta = {
     name: "metric-card",
     ancestry: "opus",
     whenToUse:
-      "Medida resumida com rótulo, valor em destaque e descrição opcional. `context` realça semanticamente somente o ícone; aceita ação relacionada e estado de carregamento. O consumidor calcula e formata o valor; para conteúdo geral ou estrutura livre, use Card.",
+      "Medida resumida com rótulo, valor em destaque e descrição opcional. Use `secondaryMetric` para uma segunda leitura diretamente relacionada, exibida como lâmina posterior com explicação própria. `context` realça semanticamente somente o ícone; aceita ação relacionada e estado de carregamento. O consumidor calcula e formata os valores; para conteúdo geral ou estrutura livre, use Card.",
   },
   chat: {
     name: "chat",
@@ -321,7 +321,7 @@ export const componentMeta = {
     name: "split",
     ancestry: "opus",
     whenToUse:
-      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial/mínimo e inset. É o mecanismo espacial para sidebar, conteúdo e rail.",
+      "Divide uma área em panes em sequência horizontal ou vertical. Use `resizable` quando a pessoa deve ajustar a fronteira; o mesmo `<Split>` vira flex simples sem ele. Cada `<Pane>` declara tamanho inicial/mínimo e inset. SurfaceAssistant especializa esse layout para assistência contextual dentro de Page, Dialog ou Drawer.",
   },
   sidebar: {
     name: "sidebar",

package/src/ui/react.tsx

@@ -105,6 +105,7 @@ export { MetricCard } from "./components/primitives/metric-card.tsx";
 export type {
   MetricCardProps,
   MetricCardContext,
+  MetricCardSecondaryMetric,
   MetricCardTone,
 } from "./components/primitives/metric-card.tsx";
 
@@ -424,6 +425,7 @@ export {
   PresentationInspector,
 } from "./components/patterns/presentation.tsx";
 export type {
+  PresentationAssistantRuntime,
   PresentationProps,
   PresentationInspectorProps,
 } from "./components/patterns/presentation.tsx";
@@ -483,6 +485,10 @@ export type {
   SplitLayoutChange,
 } from "./components/patterns/split.tsx";
 
+// Assistência contextual: mantém o recurso visível e abre um painel redimensionável na superfície.
+export { SurfaceAssistant } from "./components/patterns/surface-assistant.tsx";
+export type { SurfaceAssistantProps } from "./components/patterns/surface-assistant.tsx";
+
 // A barra de ferramentas que flutua sobre uma superfície de trabalho (canvas, editor, preview).
 export {
   Dock,