@softize/opus 30.0.0 → 31.1.0

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

@@ -16,7 +16,11 @@ render(
     title="Dispositivos conectados"
     count={3}
     description="Sessões com acesso à sua conta."
-    actions={<Button variant="outline" size="sm">Encerrar outras sessões</Button>}
+    actions={
+      <Button variant="outline" size="sm">
+        Encerrar outras sessões
+      </Button>
+    }
   >
     <p className="text-sm text-muted-foreground">MacBook Pro · ativo agora</p>
   </Surface>,
@@ -43,17 +47,16 @@ Quando `aria-label` é informado, ele substitui a ligação com o título. Para
 
 ## Moldura, fundo e anatomia
 
-Três propriedades independentes definem a aparência:
+Moldura e fundo têm funções independentes:
 
 - `framed` acrescenta borda e raio.
 - `elevation="raised"` dá à superfície o fundo de um elemento elevado sobre a página.
-- `layout` escolhe entre o ritmo contínuo e as faixas com divisores.
 
 Uma superfície com moldura ou com fundo passa a aplicar o recuo de `1rem` nas suas regiões; você não
 escreve classes de padding no header, no corpo ou no rodapé. O header delimitado usa
-`1rem` em todos os lados e linha mínima de `2rem`, como Page, Dialog e Drawer.
-Declare `sm` para botões textuais e `icon-sm` para ícones; Pane usa a mesma geometria
-quando hospeda Surface. Seções sem moldura e legendas recortadas não ganham padding de barra.
+`1rem` em todos os lados e linha mínima de `2,25rem`, como Page, Dialog e Drawer.
+Declare `default` para botões textuais e `icon` para ícones; Pane usa a mesma geometria
+quando hospeda Surface. Seções sem moldura permanecem alinhadas ao hospedeiro.
 
 ```tsx preview col
 render(
@@ -130,12 +133,7 @@ ainda ter rodapé:
 
 ```tsx preview col
 render(
-  <Surface
-    as="section"
-    framed
-    title="Plano atual"
-    level={3}
-  >
+  <Surface as="section" framed title="Plano atual" level={3}>
     <SurfaceBody>
       <p className="text-sm text-muted-foreground">
         Renova em 12 de maio. Até 10 workspaces e 50 agentes.
@@ -163,56 +161,13 @@ A `Surface` reprova as composições que deixariam a estrutura ambígua:
 
 O `opus check` aponta os mesmos problemas antes da execução.
 
-## Contínuo ou seccionado
-
-`layout` declara a anatomia da superfície inteira. No padrão, `continuous`, o espaço separa as
-regiões. Em `sectioned`, header e rodapé viram faixas e uma linha separa as regiões vizinhas.
-
-```tsx preview col
-render(
-  <div className="grid grid-cols-2 gap-4">
-    <Surface as="section" framed elevation="raised" title="Contínuo" level={3}>
-      <SurfaceBody>
-        <p className="text-sm text-muted-foreground">
-          Um assunto, lido de cima a baixo.
-        </p>
-      </SurfaceBody>
-      <SurfaceFooter>
-        <Button size="sm" variant="outline">
-          Abrir
-        </Button>
-      </SurfaceFooter>
-    </Surface>
-    <Surface
-      as="section"
-      framed
-      elevation="raised"
-      layout="sectioned"
-      title="Seccionado"
-      level={3}
-    >
-      <SurfaceBody>
-        <p className="text-sm text-muted-foreground">
-          Regiões com pesos diferentes.
-        </p>
-      </SurfaceBody>
-      <SurfaceFooter>
-        <Button size="sm" variant="outline">
-          Abrir
-        </Button>
-      </SurfaceFooter>
-    </Surface>
-  </div>,
-);
-```
-
-Use `continuous` para um bloco de leitura e `sectioned` para uma superfície de operação, com lista
-ou tabela no corpo e ações persistentes no rodapé. `sectioned` exige `framed` ou
-`elevation="raised"`: os divisores precisam de um limite para alcançar.
+## Divisores automáticos
 
-Os divisores são derivados das regiões presentes. Um header sozinho não desenha linha, e um header
-seguido direto de um rodapé produz uma linha só. Por isso, não escreva `border-b` nem `border-t`
-nas regiões, e use `layout="continuous"` para uma superfície sem divisores.
+Em superfícies delimitadas, as regiões presentes determinam os divisores. Um header isolado não desenha linha; seguido
+pelo rodapé, produz uma linha só. O recuo de uma superfície delimitada é `1rem` em cada região.
+Sem moldura ou elevação, as regiões permanecem alinhadas ao hospedeiro e separadas por `1rem`,
+sem padding nem divisor de região. Abas no Header conservam a linha de seleção própria.
+Não há prop para alternar essa anatomia.
 
 ### Corpo de ponta a ponta
 
@@ -225,7 +180,6 @@ render(
   <Surface
     as="section"
     framed
-    layout="sectioned"
     title="Veículo"
     media={
       <IconTile size="xs">
@@ -328,9 +282,8 @@ render(
 );
 ```
 
-Com `framed`, a legenda ocupa a borda do grupo, como em um `fieldset` nativo. Com
-`layout="sectioned"`, ela passa a ser a faixa do header, dentro da moldura. Sem moldura, o grupo
-flui alinhado ao formulário.
+Em uma superfície delimitada, a legenda nativa ocupa a faixa do header. Sem moldura ou
+elevação, o grupo flui alinhado ao formulário.
 
 ## Superfície clicável
 
@@ -387,33 +340,16 @@ declaram, sem recuo nem espaçamento. O conteúdo e o recuo são seus.
 documento: uma superfície dentro de uma seção que já tem `h2` usa `level={3}`. Os níveis de 2 a 6
 têm a mesma aparência.
 
-O nível 1 é diferente: identifica o conteúdo principal da página e usa a escala do título de
-[`Page`](/ui/page). É o caso da página centrada em uma coleção.
+O nível 1 usa a escala do título de [`Page`](/ui/page), mas fica restrito a superfícies
+fora de Page, como o acesso à aplicação. Dentro da Page, o título principal pertence ao
+PageHeader e as Surfaces são seções subordinadas.
 
 ## Coleção nomeada
 
-Quando a região principal da página é uma coleção, a `Surface` nomeia essa coleção e a
-[`ActionList`](/ui/action-list) executa a consulta. Coloque criar, importar e outras ações sobre o
-conjunto completo nas ações da superfície. Busca, filtros, atualização e operações que dependem do
-recorte atual permanecem na toolbar da lista.
-
-```tsx preview col
-render(
-  <Surface
-    as="section"
-    level={1}
-    title="Clientes"
-    actions={<Button size="sm">Criar cliente</Button>}
-  >
-    <p className="text-sm text-muted-foreground">
-      A lista de clientes ocupa o corpo.
-    </p>
-  </Surface>,
-);
-```
-
-A criação usa um `Button` textual na variante padrão e no tamanho `sm`, sem ícone, nomeado
-`Criar {recurso}`; o diálogo aberto por ele repete esse título, e a edição usa `Editar {recurso}`.
+Uma coleção principal usa [`Page`](/ui/page) com [`ActionList`](/ui/action-list).
+Use Surface para nomear uma coleção subordinada. Criação, importação e exportação ficam em
+`ActionList.toolbarActions`, junto de busca e filtros. Ações gerais da superfície permanecem
+no header. O botão de criação mostra **Criar**, com nome acessível e título de formulário específicos.
 
 Em uma [`Page`](/ui/page) com `layout="fill"`, a coleção ocupa a altura da página e rola só os
 resultados. `Surface` e `SurfaceBody` repassam a altura até a `ActionList` sem classes adicionais;
@@ -440,9 +376,18 @@ reservado à orientação textual breve. Os itens quebram em várias linhas quan
 
 ```tsx preview col
 render(
-<Surface as="article" title="Manual de atendimento" meta={<><Badge>Publicado</Badge><span>Por Ana</span></>}>
-  <p>Conteúdo do manual.</p>
-</Surface>
+  <Surface
+    as="article"
+    title="Manual de atendimento"
+    meta={
+      <>
+        <Badge>Publicado</Badge>
+        <span>Por Ana</span>
+      </>
+    }
+  >
+    <p>Conteúdo do manual.</p>
+  </Surface>,
 );
 ```
 
@@ -452,31 +397,31 @@ O total da coleção continua ao lado do título: use `count` na forma curta ou
 
 ## Propriedades de Surface
 
-| Propriedade   | Tipo                                            | Padrão         | Descrição                                                                                              |
-| ------------- | ----------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------ |
-| `as`          | `'div' \| 'section' \| 'article' \| 'fieldset'` | `'div'`        | Elemento da superfície. Não combina com `asChild`.                                                     |
-| `asChild`     | `boolean`                                       | `false`        | Entrega a superfície ao único filho, como um `button` ou um link.                                      |
-| `framed`      | `boolean`                                       | `false`        | Acrescenta borda e raio, e recorta o conteúdo seccionado ou sem recuo.                                 |
-| `elevation`   | `'none' \| 'raised'`                            | `'none'`       | `raised` pinta o fundo de superfície elevada e mantém a altura do próprio conteúdo.                    |
-| `layout`      | `'continuous' \| 'sectioned'`                   | `'continuous'` | Anatomia das regiões. `sectioned` exige `framed` ou `elevation="raised"`.                              |
-| `level`       | `1 \| 2 \| 3 \| 4 \| 5 \| 6`                    | `2`            | Nível do heading do título. `1` identifica o conteúdo principal da página. Não se aplica a `fieldset`. |
-| `title`       | `ReactNode`                                     |                | Forma curta: título da superfície.                                                                     |
-| `media`       | `ReactNode`                                     |                | Forma curta: conteúdo do slot de mídia, antes do título. Exige `title`.                                |
-| `count`       | `number`                                        |                | Forma curta: total de itens ao lado do título. Exige `title`; indisponível em `fieldset`.              |
-| `description` | `ReactNode`                                     |                | Forma curta: frase de apoio sob o título. Exige `title`; indisponível em `fieldset`.                   |
-| `meta` | `ReactNode` | | Forma curta: metadados sob o título e a orientação. Exige `title`; indisponível em `fieldset`. |
-| `actions`     | `ReactNode`                                     |                | Forma curta: ações sobre a superfície inteira. Exige `title`; indisponível em `fieldset`.              |
-| `className`   | `string`                                        |                | Compõe sobre a superfície. Na caixa simples, é onde entra o recuo.                                     |
-| `children`    | `ReactNode`                                     |                | Filhos livres, que formam o corpo, ou os slots `SurfaceHeader`, `SurfaceBody` e `SurfaceFooter`.       |
+| Propriedade   | Tipo                                            | Padrão   | Descrição                                                                                              |
+| ------------- | ----------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
+| `as`          | `'div' \| 'section' \| 'article' \| 'fieldset'` | `'div'`  | Elemento da superfície. Não combina com `asChild`.                                                     |
+| `asChild`     | `boolean`                                       | `false`  | Entrega a superfície ao único filho, como um `button` ou um link.                                      |
+| `framed`      | `boolean`                                       | `false`  | Acrescenta borda e raio, e recorta o conteúdo seccionado ou sem recuo.                                 |
+| `elevation`   | `'none' \| 'raised'`                            | `'none'` | `raised` pinta o fundo de superfície elevada e mantém a altura do próprio conteúdo.                    |
+| `level`       | `1 \| 2 \| 3 \| 4 \| 5 \| 6`                    | `2`      | Nível do heading do título. `1` identifica o conteúdo principal da página. Não se aplica a `fieldset`. |
+| `title`       | `ReactNode`                                     |          | Forma curta: título da superfície.                                                                     |
+| `media`       | `ReactNode`                                     |          | Forma curta: conteúdo do slot de mídia, antes do título. Exige `title`.                                |
+| `count`       | `number`                                        |          | Forma curta: total de itens ao lado do título. Exige `title`; indisponível em `fieldset`.              |
+| `description` | `ReactNode`                                     |          | Forma curta: frase de apoio sob o título. Exige `title`; indisponível em `fieldset`.                   |
+| `meta`        | `ReactNode`                                     |          | Forma curta: metadados sob o título e a orientação. Exige `title`; indisponível em `fieldset`.         |
+| `actions`     | `ReactNode`                                     |          | Forma curta: ações sobre a superfície inteira. Exige `title`; indisponível em `fieldset`.              |
+| `className`   | `string`                                        |          | Compõe sobre a superfície. Na caixa simples, é onde entra o recuo.                                     |
+| `children`    | `ReactNode`                                     |          | Filhos livres, que formam o corpo, ou os slots `SurfaceHeader`, `SurfaceBody` e `SurfaceFooter`.       |
 
 As demais propriedades são as nativas do elemento escolhido em `as`.
 
 ## Propriedades de SurfaceHeader
 
-| Propriedade | Tipo        | Padrão | Descrição                                                                                                                                                                                               |
-| ----------- | ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Propriedade | Tipo        | Padrão | Descrição                                                                                                                                                                                                               |
+| ----------- | ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tabs`      | `ReactNode` |        | `TabsList` sob o título, controlado por um `Tabs` ancestral. Não disponível em fieldset.                                                                                                                                |
 | `children`  | `ReactNode` |        | No máximo um de cada: `SurfaceMedia`, `SurfaceTitle`, `SurfaceCount`, `SurfaceMeta`, `SurfaceDescription` e `SurfaceActions`. Em `fieldset`, o `SurfaceTitle` é obrigatório e somente ele e `SurfaceMedia` são aceitos. |
-| `className` | `string`    |        | Ajusta a região do header.                                                                                                                                                                              |
+| `className` | `string`    |        | Ajusta a região do header.                                                                                                                                                                                              |
 
 `SurfaceHeader` só existe como filho direto de `Surface`.
 
@@ -529,25 +474,25 @@ um wrapper filho declara relações locais mais compactas.
 ## 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
+é opcional e não repete o título. A mesma regra vale para uma página, 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.
 
 ## Propriedades de SurfaceCount
 
-| Propriedade | Tipo | Descrição |
-| --- | --- | --- |
-| `children` | `ReactNode` | Contador ao lado do título. |
-| `className` | `string` | Ajusta a apresentação do contador. |
+| Propriedade | Tipo        | Descrição                          |
+| ----------- | ----------- | ---------------------------------- |
+| `children`  | `ReactNode` | Contador ao lado do título.        |
+| `className` | `string`    | Ajusta a apresentação do contador. |
 
 Aceita atributos nativos de `span`. Deve estar em `SurfaceHeader`, fora de `fieldset`.
 
 ## Propriedades de SurfaceMeta
 
-| Propriedade | Tipo | Descrição |
-| --- | --- | --- |
-| `children` | `ReactNode` | Badges, datas, autoria ou outros metadados do registro. |
-| `className` | `string` | Ajusta a faixa de metadados. |
+| Propriedade | Tipo        | Descrição                                               |
+| ----------- | ----------- | ------------------------------------------------------- |
+| `children`  | `ReactNode` | Badges, datas, autoria ou outros metadados do registro. |
+| `className` | `string`    | Ajusta a faixa de metadados.                            |
 
 Aceita atributos nativos de `div`. O intervalo superior é de 0,75rem; os itens têm
 0,75rem entre colunas e 0,5rem entre linhas. O componente não insere separadores nem

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

@@ -64,6 +64,10 @@ tom ao sair do canvas e entrar num card, porque `control` representa o resultado
 cor translúcida a ser misturada com o ancestral. Da mesma forma, hover, seleção e pressão usam
 papéis diferentes e preservam a mesma ordem comportamental nos dois temas.
 
+O fundo discreto (`muted`) também se distingue do hover nos dois temas. A calibração de base
+mantém essa diferença mesmo com Contraste em zero; aumentar esse ajuste amplia os degraus da
+escala. Use os tokens de interação para hover, seleção e pressão, sem criar opacidades por componente.
+
 ```tsx preview
 const NEUTRAL_STATES = [
   ["control", "Controle em repouso."],
@@ -87,6 +91,16 @@ render(
 );
 ```
 
+A navegação interna usa `bg-sidebar text-foreground`. No claro, ela é quase branca sobre
+conteúdo branco; no escuro, acompanha a camada elevada (`card`). A sidebar geral pode usar
+`bg-sidebar-global text-foreground` para acompanhar o canvas nos dois temas, mantendo continuidade visual sem transparência.
+Os tokens são opacos, e hover, seleção e
+pressão mantêm os papéis de interação compartilhados. O fundo da navegação global continua
+sendo escolhido pelo hospedeiro.
+
+No dark, a calibração aplica uma redução final de 5% à luminosidade HSL das superfícies,
+linhas e estados neutros. Textos e contextos semânticos mantêm seus valores para preservar a leitura.
+
 ### Ajuste de aparência
 
 Os tokens neutros desta seção não são valores fixos: o tema os calcula a partir de quatro eixos,
@@ -298,8 +312,8 @@ render(
 
 1. Formato HSL nos tokens (o upstream migrou para oklch), escolhido pela legibilidade.
 2. Hierarquia opaca de superfícies e estados nos dois temas: canvas, card/popover, controle, hover,
-   seleção e pressão têm papéis próprios. No light, o canvas quase branco sustenta superfícies
-   brancas; no dark, cards e popovers permanecem acima do canvas. A ADR 0043 registra os valores e
+   seleção e pressão têm papéis próprios. No preset light, canvas, controles, cards e popovers são brancos; bordas e elevação
+   distinguem as regiões; no dark, cards e popovers permanecem acima do canvas. A ADR 0043 registra os valores e
    as restrições de composição. A escala neutra é derivada dos eixos de aparência (ADR 0044); no
    preset, os valores são os calibrados.
 3. Radius mapeado (`xs` a `2xl`) preservando o sentido pré-v4 dos utilitários `rounded-*`. Esse
@@ -307,8 +321,8 @@ render(
    precisam revisar a transição para esse degrau nativo ao customizar `--radius`.
 4. Escala `shadow-*` recomposta em duas camadas claras e difusas — preserva os degraus do
    Tailwind e troca somente o peso visual. Componentes e consumidores usam diretamente a escala.
-5. Bordas mais leves no tema claro: `--border`/`--input` em `92.5%` (upstream `89.8%`) — par do canvas
-   quase-branco do body; superfícies elevadas usam essa mesma borda real.
+5. Bordas mais leves no tema claro: `--border`/`--input` em `92%` (upstream `89.8%`) — par do canvas
+   branco do body; superfícies elevadas usam essa mesma borda real.
 6. Radius base em `0.75rem` — superfícies principais ganham cantos mais presentes sem aproximar
    controles compactos de modais. A decisão detalhada acompanha o pacote em
    `docs/radius-scale.md`, com os defaults, o comportamento de superfícies aninhadas e as

package/src/ui/docs/registry.tsx

@@ -67,6 +67,8 @@ import dockMd from "./content/dock.md?raw";
 import breadcrumbMd from "./content/breadcrumb.md?raw";
 import buttonMd from "./content/button.md?raw";
 import calendarMd from "./content/calendar.md?raw";
+import dateInputMd from "./content/date-input.md?raw";
+import calendarMonthViewMd from "./content/calendar-month-view.md?raw";
 import metricCardMd from "./content/metric-card.md?raw";
 import carouselMd from "./content/carousel.md?raw";
 import askMd from "./content/ask.md?raw";
@@ -152,9 +154,15 @@ export const iconScope: Record<string, unknown> = Object.fromEntries(
 );
 
 /** Página conceitual (Começar/Framework/Design/Intro): markdown direto (o H1/lead moram no md). */
-const doc = (content: string, codeCollapsible = true) => (): React.ReactElement => (
-  <DocMarkdown content={content} scope={iconScope} codeCollapsible={codeCollapsible} />
-);
+const doc =
+  (content: string, codeCollapsible = true) =>
+  (): React.ReactElement => (
+    <DocMarkdown
+      content={content}
+      scope={iconScope}
+      codeCollapsible={codeCollapsible}
+    />
+  );
 
 /**
  * Página de componente: o cabeçalho (título + badge de origem + whenToUse) vem do `meta` central
@@ -305,7 +313,11 @@ export const PROTOCOL_SECTIONS: DocSection[] = [
             searchText: mcpMd,
             render: doc(mcpMd),
           },
-          { slug: "ui", title: "Interface com Opus ↗", render: () => <UiRedirect /> },
+          {
+            slug: "ui",
+            title: "Interface com Opus ↗",
+            render: () => <UiRedirect />,
+          },
           {
             slug: "documentation-portal",
             title: "Publicação de documentação",
@@ -585,6 +597,11 @@ export const UI_SECTIONS: DocSection[] = [
               actionFormDialogMd,
             ),
           },
+          {
+            slug: "calendar-month-view",
+            title: "CalendarMonthView",
+            render: comp("CalendarMonthView", "calendar-month-view", calendarMonthViewMd),
+          },
           {
             slug: "action-list",
             title: "Action List",
@@ -637,6 +654,11 @@ export const UI_SECTIONS: DocSection[] = [
             title: "Calendar",
             render: comp("Calendar", "calendar", calendarMd),
           },
+          {
+            slug: "date-input",
+            title: "DateInput",
+            render: comp("DateInput", "date-input", dateInputMd),
+          },
           {
             slug: "checkbox",
             title: "Checkbox",
@@ -890,8 +912,9 @@ export const DOC_SECTIONS: DocSection[] = [
       {
         pages: [
           ...["getting-started", "cycle", "upgrading"].map((slug) =>
-            PROTOCOL_SECTIONS.flatMap((section) => section.groups.flatMap((group) => group.pages))
-              .find((page) => page.slug === slug)!,
+            PROTOCOL_SECTIONS.flatMap((section) =>
+              section.groups.flatMap((group) => group.pages),
+            ).find((page) => page.slug === slug)!,
           ),
           {
             slug: "changelog",
@@ -902,7 +925,9 @@ export const DOC_SECTIONS: DocSection[] = [
       },
       {
         label: "Introdução ao SDK",
-        pages: PROTOCOL_SECTIONS[0]!.groups[0]!.pages.filter((page) => page.slug !== "getting-started"),
+        pages: PROTOCOL_SECTIONS[0]!.groups[0]!.pages.filter(
+          (page) => page.slug !== "getting-started",
+        ),
       },
     ],
   },
@@ -913,8 +938,12 @@ export const DOC_SECTIONS: DocSection[] = [
     label: s.label === "Testes e evolução" ? "Testes" : s.label,
     groups: s.groups.map((g) => ({
       ...g,
-      pages: g.pages.filter((p) => !["ui", "cycle", "upgrading"].includes(p.slug)),
+      pages: g.pages.filter(
+        (p) => !["ui", "cycle", "upgrading"].includes(p.slug),
+      ),
     })),
   })),
-  ...UI_SECTIONS.map((section, index) => index === 0 ? { ...section, label: "Introdução à UI" } : section),
+  ...UI_SECTIONS.map((section, index) =>
+    index === 0 ? { ...section, label: "Introdução à UI" } : section,
+  ),
 ];

package/src/ui/drivers/context.tsx

@@ -29,9 +29,12 @@ export function OpusProvider({ client, dicts, children }: OpusProviderProps): Re
 }
 
 /** Acesso interno ao adapter; não é reexportado por `@softize/opus/ui/react`. */
-export function useClient(hook: string): ClientAdapter {
-  const ctx = useContext(OpusContext)
-  if (ctx === null) {
+export function useOptionalClient(): ClientAdapter | null {
+  return useContext(OpusContext)?.client ?? null
+}
+
+export function requireClient(client: ClientAdapter | null, hook: string): ClientAdapter {
+  if (client === null) {
     throw new Error(
       `${hook} foi chamado fora de um <OpusProvider> e não tem como executar a action. ` +
         'Os hooks de action e os componentes que os usam, como ActionForm, ActionList e ActionView, ' +
@@ -39,7 +42,11 @@ export function useClient(hook: string): ClientAdapter {
         'em testes e previews, envolva o componente renderizado.',
     )
   }
-  return ctx.client
+  return client
+}
+
+export function useClient(hook: string): ClientAdapter {
+  return requireClient(useOptionalClient(), hook)
 }
 
 const NO_DICTS: Record<string, DictLike> = {}

package/src/ui/drivers/react.tsx

@@ -39,7 +39,7 @@ import {
   idleAction,
   idleLookup,
 } from '../index.ts'
-import { useClient } from './context.tsx'
+import { useClient, useOptionalClient, requireClient } from './context.tsx'
 export {
   OpusProvider,
   useDicts,
@@ -213,18 +213,37 @@ export function useListAction<TItem = unknown, TInput extends Record<string, unk
   input?: TInput,
   options?: { enabled?: boolean },
 ): UseListActionResult<TItem> {
-  const client = useClient('useListAction')
+  return useListResource<TItem, TInput>(action, input, options)
+}
+
+/** Fonte já governada por outro serviço; a chave inclui o escopo de acesso. */
+export interface ListDataSource<TItem> {
+  key: readonly string[]
+  load: (input: Record<string, unknown>, context: { signal: AbortSignal }) => Promise<Paginated<TItem>>
+}
+
+/** Consulta comum ao ActionList e ao hook público, sem duplicar estados de busca. */
+export function useListResource<TItem = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(
+  resource: { name: string; kind: 'list' } | ListDataSource<TItem>,
+  input?: TInput,
+  options?: { enabled?: boolean },
+): UseListActionResult<TItem> {
+  const providedClient = useOptionalClient()
+  const external = 'load' in resource
+  const client = external ? null : requireClient(providedClient, 'useListAction')
 
   const query = useQuery<Paginated<TItem>, ActionError>({
-    queryKey: [action.name, input ?? {}],
-    queryFn: async () => {
-      const result = await client.run<Paginated<TItem>>(action as unknown as ActionDef, input ?? {})
+    queryKey: external ? ['opus:list-source', ...resource.key, input ?? {}] : [resource.name, input ?? {}],
+    ...(external ? { gcTime: 0, retry: false } : {}),
+    queryFn: async (context) => {
+      if (external) return resource.load(input ?? {}, { signal: context.signal })
+      const result = await client!.run<Paginated<TItem>>(resource as unknown as ActionDef, input ?? {})
       if (!result.ok) throw result.error
       return result.data
     },
     // Input mudou (filtro/página) → mantém os itens na tela enquanto busca: o
     // ActionList esmaece em vez de piscar skeleton. isPending = só o 1º load.
-    placeholderData: keepPreviousData,
+    placeholderData: external ? undefined : keepPreviousData,
     enabled: options?.enabled ?? true,
   })
 
@@ -259,7 +278,8 @@ export function useGroupedListAction<
   pages: Record<string, number>,
   pageSize: number,
 ): ListActionGroup<TItem>[] {
-  const client = useClient('ActionList grouping')
+  const providedClient = useOptionalClient()
+  const client = field === null ? providedClient : requireClient(providedClient, 'ActionList grouping')
   return useGroupedListQueries<TItem, TInput>(
     client,
     action,

package/src/ui/meta.ts

@@ -15,7 +15,7 @@ export const componentMeta = {
     name: "surface",
     ancestry: "opus",
     whenToUse:
-      'Delimite e nomeie um trecho da tela: uma região da página, um grupo de campos, um registro, um item de grade ou um bloco clicável. `as` escolhe o elemento (`div`, `section`, `article` ou `fieldset`) e `asChild` entrega a superfície a um botão ou link. `framed` acrescenta a moldura, `elevation="raised"` dá fundo próprio e `layout` escolhe entre ritmo contínuo e faixas com divisores. No caso comum, declare `title`, `description`, `count`, `actions` e `media` na própria Surface; componha SurfaceHeader, SurfaceBody e SurfaceFooter quando precisar controlar a estrutura. Numa página centrada em uma coleção, `level={1}` faz da Surface o heading principal; nas demais, ele vem de PageTitle. Para um modal use Dialog, para um painel lateral use Drawer e para uma coluna de layout use Pane.',
+      'Delimite e nomeie um trecho da tela: uma região da página, um grupo de campos, um registro, um item de grade ou um bloco clicável. `as` escolhe o elemento (`div`, `section`, `article` ou `fieldset`) e `asChild` entrega a superfície a um botão ou link. `framed` acrescenta a moldura, `elevation="raised"` dá fundo próprio. Superfícies delimitadas derivam os divisores das regiões presentes; sem moldura, conservam o alinhamento e ritmo do hospedeiro. No caso comum, declare `title`, `description`, `count`, `actions` e `media` na própria Surface; componha SurfaceHeader, SurfaceBody e SurfaceFooter quando precisar controlar a estrutura. O título principal de Page vem de PageTitle; Surfaces internas usam níveis subordinados. `level={1}` fica restrito a superfícies fora de Page. Para um modal use Dialog, para um painel lateral use Drawer e para uma coluna de layout use Pane.',
   },
   ask: {
     name: "ask",
@@ -131,6 +131,12 @@ export const componentMeta = {
     whenToUse:
       "Receba texto em uma única linha com os atributos nativos de `input`. Use `icon` para identidade e `trailing` para uma ação no fim do campo; associe uma Label. Quando precisar combinar múltiplos adornos ou controles na mesma moldura, use InputGroup.",
   },
+  "date-input": {
+    name: "date-input",
+    ancestry: "opus",
+    whenToUse:
+      "Receba uma data por digitação em DD/MM/AAAA ou escolha no calendário. O valor válido permanece uma string civil AAAA-MM-DD, sem conversão de fuso horário. Associe uma Label; no ActionForm, declare widget: 'date'.",
+  },
   label: {
     name: "label",
     ancestry: "shadcn",
@@ -165,7 +171,7 @@ export const componentMeta = {
     name: "separator",
     ancestry: "shadcn",
     whenToUse:
-      'Marque a fronteira entre blocos de conteúdo que não pertencem a uma superfície com regiões. A linha horizontal fica entre blocos empilhados; com `orientation="vertical"`, ela separa itens lado a lado e herda a altura do contêiner. A linha é decorativa por padrão e fica fora da árvore de acessibilidade; use `decorative={false}` quando a divisão tiver significado. Não use Separator entre cabeçalho, corpo e rodapé de Surface, Dialog ou Drawer: nessas superfícies, os divisores são derivados das regiões com `layout="sectioned"`.',
+      'Marque a fronteira entre blocos de conteúdo que não pertencem a uma superfície com regiões. A linha horizontal fica entre blocos empilhados; com `orientation="vertical"`, ela separa itens lado a lado e herda a altura do contêiner. A linha é decorativa por padrão e fica fora da árvore de acessibilidade; use `decorative={false}` quando a divisão tiver significado. Não use Separator entre cabeçalho, corpo e rodapé de Surface, Dialog ou Drawer: nessas superfícies, os divisores são derivados das regiões automaticamente.',
   },
   skeleton: {
     name: "skeleton",
@@ -239,11 +245,16 @@ export const componentMeta = {
     whenToUse:
       "Mostre onde a pessoa está quando a página fica vários níveis abaixo da entrada da seção e permita voltar a um nível intermediário. Use BreadcrumbLink nos níveis navegáveis, BreadcrumbPage no nível atual, que não é clicável, BreadcrumbSeparator entre eles e BreadcrumbEllipsis para colapsar trilhas longas. Quando basta voltar ao nível imediatamente acima, use PageBack; para alternar painéis no mesmo nível, Tabs.",
   },
+  "calendar-month-view": {
+    name: "calendar-month-view",
+    ancestry: "opus",
+    whenToUse: "Consulte registros distribuídos pelos dias de um mês, como expediente e agenda. Use como visualização de ActionList para preservar consulta, filtros e estados da coleção.",
+  },
   calendar: {
     name: "calendar",
     ancestry: "shadcn",
     whenToUse:
-      'Permita escolher datas vendo o mês inteiro, como a data de uma entrega ou o período de um relatório. `mode` define a seleção — `single`, `multiple` ou `range` — e o formato de `selected` e `onSelect` (Date, Date[] ou { from, to }). `captionLayout="dropdown"` troca o título do mês por seletores de mês e ano, útil para chegar a um período distante; `numberOfMonths` mostra meses lado a lado e `disabled` impede a escolha de datas específicas. Os textos usam pt-BR por padrão. Para abrir o calendário a partir de um campo, ancore-o em um Popover.',
+      'Permita escolher datas vendo o mês inteiro, como a data de uma entrega ou o período de um relatório. `mode` define a seleção — `single`, `multiple` ou `range` — e o formato de `selected` e `onSelect` (Date, Date[] ou { from, to }). `captionLayout="dropdown"` troca o título do mês por seletores de mês e ano, útil para chegar a um período distante; `numberOfMonths` mostra meses lado a lado e `disabled` impede a escolha de datas específicas. Os textos usam pt-BR por padrão. Para preencher uma data em um campo com digitação e calendário, use DateInput. Use Popover para composições próprias.',
   },
   carousel: {
     name: "carousel",
@@ -261,7 +272,7 @@ export const componentMeta = {
     name: "floating-layer",
     ancestry: "opus",
     whenToUse:
-      "Mantenha utilizável, por cima de qualquer Dialog ou Drawer aberto, uma região que acompanha a aplicação inteira, como o botão e o painel de um assistente. O modal continua aberto e intacto atrás; a camada recebe clique, foco, digitação, rolagem e Esc. Diálogos que exigem resposta, como `Dialog mode=\"alert\"` e `dialog.confirm`, continuam cobrindo a camada até a resposta. Cada filho se posiciona contra a janela, e o hospedeiro publica em `data-modal` e `data-modal-side` o Dialog ou Drawer aberto. Para ferramentas sobre uma única superfície, use Dock; para conteúdo preso a um gatilho, Popover.",
+      'Mantenha utilizável, por cima de qualquer Dialog ou Drawer aberto, uma região que acompanha a aplicação inteira, como o botão e o painel de um assistente. O modal continua aberto e intacto atrás; a camada recebe clique, foco, digitação, rolagem e Esc. Diálogos que exigem resposta, como `Dialog mode="alert"` e `dialog.confirm`, continuam cobrindo a camada até a resposta. Cada filho se posiciona contra a janela, e o hospedeiro publica em `data-modal` e `data-modal-side` o Dialog ou Drawer aberto. Para ferramentas sobre uma única superfície, use Dock; para conteúdo preso a um gatilho, Popover.',
   },
   drawer: {
     name: "drawer",
@@ -388,7 +399,7 @@ export const componentMeta = {
     name: "action-list",
     ancestry: "opus",
     whenToUse:
-      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período, busca e dimensões fechadas de agrupamento; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. A tabela derivada não cria moldura própria. Em uma página, envolva a lista com Surface para manter título e criação junto da coleção. Para um único recurso, use ActionView.",
+      "Apresente uma coleção pesquisável a partir de uma ListAction. O contrato declara colunas, filtros, período, busca e dimensões fechadas de agrupamento; ActionList coordena visualizações, paginação, seleção em lote e sincronização com a URL. A tabela derivada não cria moldura própria. Use item com os campos title e description para uma lista de itens conectados; title da coleção reúne suas toolbarActions. Fontes externas já governadas por outro serviço usam source com chave de escopo e loader, preservando o transporte existente. Para um único recurso, use ActionView.",
   },
   "action-trigger": {
     name: "action-trigger",
@@ -406,7 +417,7 @@ export const componentMeta = {
     name: "page",
     ancestry: "opus",
     whenToUse:
-      "Estruture uma página com cabeçalho, estado e conteúdo na mesma anatomia. Page renderiza o `<main>` com header e viewport em largura total e conteúdo centralizado de até 80rem; surfaceLayout escolhe sectioned (padrão) ou continuous, independente de layout flow/fill; PageHeader reúne navegação e ações da superfície; PageIntro abre PageBody com título e orientação. A composição compacta mantém o título no header, sem intro. PageShell pode fornecer navegação e ações conhecidas pela aplicação sem criar uma barra visual. Uma região interna pode fornecer o heading principal com `Surface level={1}`. PageActionsTarget fica restrito a workspaces imersivos. PageState substitui o header e o conteúdo durante carregamento, falha ou ausência, por isso informações indispensáveis entram no corpo, como Alert ou texto. Para uma falha parcial, mantenha o estado na seção com DataState; para uma região disponível para criação ou vínculo, use Empty.",
+      "Estruture uma página aberta com título e ações no header, metadados abaixo e conteúdo na mesma coluna. Page usa padding de 2,5rem, título de 1,875rem, intervalo de 1,5rem após o cabeçalho e de 1rem entre as demais regiões, sem divisores. width escolhe narrow, default ou wide; sem opção, ocupa a largura disponível. Ações dos headers de Page, Drawer, Dialog e Surface usam default/icon e linha mínima de 2,25rem. PageHeader.tabs recebe TabsList; TabsPanel fica no body. PageBack é o primeiro ícone das ações, com destino explícito e tooltip. PageShell fornece ações sem criar outra barra. layout flow rola a página inteira; fill mantém o header visível e entrega a altura a listas ou à rolagem do body. Drawer e Dialog mantêm suas superfícies delimitadas e recuo de 1rem. PageState substitui o header e o conteúdo durante carregamento, falha ou ausência. Use DataState para falha parcial. Título e metadados pertencem ao PageHeader.",
   },
   presentation: {
     name: "presentation",