@softize/opus 19.0.0 → 20.1.0

package/src/ui/components/patterns/list.tsx

@@ -66,6 +66,7 @@ import {
   type DictLike,
 } from "../../drivers/react.tsx";
 import { cn } from "../../lib/cn.ts";
+import { FillBoundary, useFillLeaf } from "./fill-region.ts";
 import { objectSchemaShape } from "../../lib/object-schema.ts";
 import { Badge } from "../primitives/badge.tsx";
 import { DictionaryValue } from "../primitives/dictionary-value.tsx";
@@ -343,7 +344,12 @@ export interface ActionListProps<TInput, TItem> {
   action: ListActionLike;
   /** Input BASE (escopo fixo, ex.: { workspaceId }) — a toolbar soma por cima. */
   input: TInput;
-  /** `fill` ocupa a altura disponível e mantém a rolagem dentro da região de resultados. */
+  /**
+   * `fill` ocupa a altura disponível e mantém a rolagem dentro da região de resultados.
+   * Sem valor, vale `fill` quando o elemento pai repassa a altura de uma `Page` ou
+   * `Presentation` em `fill` — `PageBody`, `ContentBody` ou o corpo da Presentation — e
+   * `flow` nos demais casos (ADR 0024).
+   */
   layout?: "flow" | "fill";
   /** Ações do consumidor no fim da barra de filtros, depois dos controles de exibição. */
   toolbarActions?: ReactNode;
@@ -1212,20 +1218,8 @@ function AdvancedFiltersDialog({
                 frameVariant={
                   sectionVariant === "framed" ? "legend" : "default"
                 }
-                title={
-                  <span className="flex items-center gap-2">
-                    {sectionIcons?.[section] !== undefined && (
-                      <span
-                        data-slot="content-title-icon"
-                        aria-hidden="true"
-                        className="inline-flex shrink-0 items-center justify-center text-muted-foreground [&_svg]:size-4"
-                      >
-                        {sectionIcons[section]}
-                      </span>
-                    )}
-                    {section}
-                  </span>
-                }
+                title={section}
+                media={sectionIcons?.[section]}
               >
                 <FieldGroup className={cn("grid gap-4", gridColumns)}>
                   {entries.map(field)}
@@ -1666,7 +1660,7 @@ function RowActions({ children }: { children: ReactNode }) {
 export function ActionList<TInput, TItem>({
   action,
   input,
-  layout = "flow",
+  layout: layoutProp,
   toolbarActions,
   columns,
   cells,
@@ -1693,6 +1687,7 @@ export function ActionList<TInput, TItem>({
   onStateChange,
 }: ActionListProps<TInput, TItem>) {
   const confirmBodyId = useId();
+  const { layout, ref: rootRef } = useFillLeaf<HTMLDivElement>(layoutProp);
   // Query-backed (useListAction): busca declarativa por [name, input] E refetch
   // automático quando um form/trigger invalida a action (`invalidates: ['x.list']`).
   // O input efetivo é computado abaixo; o hook re-busca quando ele muda.
@@ -2367,6 +2362,7 @@ export function ActionList<TInput, TItem>({
   return (
     <TooltipProvider>
       <div
+        ref={rootRef}
         data-action={action.name}
         data-layout={layout}
         className={cn(
@@ -2375,84 +2371,87 @@ export function ActionList<TInput, TItem>({
             : "space-y-3",
         )}
       >
-        {toolbar}
-        {beforeContent}
-        {selectionBar}
-        {/* Tabela e rodapé formam um bloco só: o `gap` da pilha separa a barra de
-            ferramentas do conteúdo, nunca o conteúdo do seu próprio rodapé. Duas
-            linhas: a dos resultados absorve a altura que sobra, a do rodapé se mede
-            pelo conteúdo. Em `flow` a primeira linha também é `1fr`, mas o bloco não
-            tem altura própria e ela vira a altura do conteúdo. */}
-        <div className={cn("grid min-h-0 grid-rows-[1fr_auto]", layout === "fill" && "flex-1")}>
-          {/* A rolagem mora aqui, nos dois eixos: é este elemento que o `sticky` do
-              cabeçalho enxerga. Um contêiner de rolagem entre ele e a tabela roubaria
-              essa referência e o cabeçalho voltaria a subir junto com as linhas.
-              Refetch com a lista já na tela: esmaece e trava interação até chegar. */}
-          <div
-            aria-busy={busy}
-            className={cn(
-              "min-h-0",
-              layout === "fill" && "overflow-auto",
-              busy && items.length > 0 && "pointer-events-none opacity-60",
-            )}
-          >
-            {body}
+        {/* A lista é a folha da cadeia de altura: o que ela hospeda decide a própria. */}
+        <FillBoundary>
+          {toolbar}
+          {beforeContent}
+          {selectionBar}
+          {/* Tabela e rodapé formam um bloco só: o `gap` da pilha separa a barra de
+              ferramentas do conteúdo, nunca o conteúdo do seu próprio rodapé. Duas
+              linhas: a dos resultados absorve a altura que sobra, a do rodapé se mede
+              pelo conteúdo. Em `flow` a primeira linha também é `1fr`, mas o bloco não
+              tem altura própria e ela vira a altura do conteúdo. */}
+          <div className={cn("grid min-h-0 grid-rows-[1fr_auto]", layout === "fill" && "flex-1")}>
+            {/* A rolagem mora aqui, nos dois eixos: é este elemento que o `sticky` do
+                cabeçalho enxerga. Um contêiner de rolagem entre ele e a tabela roubaria
+                essa referência e o cabeçalho voltaria a subir junto com as linhas.
+                Refetch com a lista já na tela: esmaece e trava interação até chegar. */}
+            <div
+              aria-busy={busy}
+              className={cn(
+                "min-h-0",
+                layout === "fill" && "overflow-auto",
+                busy && items.length > 0 && "pointer-events-none opacity-60",
+              )}
+            >
+              {body}
+            </div>
+            {footer}
           </div>
-          {footer}
-        </div>
-        {confirming !== null && (
-          <Dialog
-            mode="alert"
-            open
-            onOpenChange={(o) => {
-              if (!o) setConfirming(null);
-            }}
-          >
-            <DialogContent
-              aria-describedby={
-                confirming.confirm?.message === undefined
-                  ? undefined
-                  : confirmBodyId
-              }
+          {confirming !== null && (
+            <Dialog
+              mode="alert"
+              open
+              onOpenChange={(o) => {
+                if (!o) setConfirming(null);
+              }}
             >
-              <DialogHeader>
-                <DialogTitle>
-                  {confirming.confirm?.title ?? confirming.label}
-                </DialogTitle>
-              </DialogHeader>
-              {confirming.confirm?.message !== undefined && (
-                <DialogBody
-                  id={confirmBodyId}
-                  className="text-sm text-muted-foreground"
-                >
-                  {confirming.confirm.message}
-                </DialogBody>
-              )}
-              <DialogFooter>
-                <ButtonGroup mode="spaced" distribution="equal">
-                  <DialogClose initialFocus asChild>
-                    <Button variant="outline">Cancelar</Button>
-                  </DialogClose>
-                  <DialogClose asChild>
-                    <Button
-                      context={
-                        confirming.destructive === true ? "danger" : "primary"
-                      }
-                      variant="solid"
-                      onClick={() => {
-                        const a = confirming;
-                        setConfirming(null);
-                        void runBatch(a);
-                      }}
-                    >
-                      {confirming.label}
-                    </Button>
-                  </DialogClose>
-                </ButtonGroup>
-              </DialogFooter>
-            </DialogContent>
-          </Dialog>
-        )}
+              <DialogContent
+                aria-describedby={
+                  confirming.confirm?.message === undefined
+                    ? undefined
+                    : confirmBodyId
+                }
+              >
+                <DialogHeader>
+                  <DialogTitle>
+                    {confirming.confirm?.title ?? confirming.label}
+                  </DialogTitle>
+                </DialogHeader>
+                {confirming.confirm?.message !== undefined && (
+                  <DialogBody
+                    id={confirmBodyId}
+                    className="text-sm text-muted-foreground"
+                  >
+                    {confirming.confirm.message}
+                  </DialogBody>
+                )}
+                <DialogFooter>
+                  <ButtonGroup mode="spaced" distribution="equal">
+                    <DialogClose initialFocus asChild>
+                      <Button variant="outline">Cancelar</Button>
+                    </DialogClose>
+                    <DialogClose asChild>
+                      <Button
+                        context={
+                          confirming.destructive === true ? "danger" : "primary"
+                        }
+                        variant="solid"
+                        onClick={() => {
+                          const a = confirming;
+                          setConfirming(null);
+                          void runBatch(a);
+                        }}
+                      >
+                        {confirming.label}
+                      </Button>
+                    </DialogClose>
+                  </ButtonGroup>
+                </DialogFooter>
+              </DialogContent>
+            </Dialog>
+          )}
+        </FillBoundary>
       </div>
     </TooltipProvider>
   );

package/src/ui/components/patterns/page.tsx

@@ -30,6 +30,11 @@ import {
 } from "./page-heading-context.tsx";
 import { SurfaceHeader, surfaceHeaderClasses } from "./surface-header.tsx";
 import { PageState, PageStatePresenceProvider } from "./page-state.tsx";
+import {
+  FillRoot,
+  fillRegionClassName,
+  useFillRegion,
+} from "./fill-region.ts";
 
 interface PageContextValue {}
 
@@ -205,7 +210,10 @@ interface PageBaseProps extends Omit<
 > {
   /** Classes do container. Default: centralizado com `max-w-7xl` (80rem). */
   className?: string;
-  /** `fill` limita a página à altura do shell para que regiões internas assumam a rolagem. */
+  /**
+   * `fill` limita a página à altura do shell para que regiões internas assumam a rolagem.
+   * A altura chega sozinha a uma `ActionList` composta por `PageBody` e `Content` (ADR 0024).
+   */
   layout?: "flow" | "fill";
 }
 
@@ -455,7 +463,7 @@ export function Page({
                   className,
                 )}
               >
-                {content}
+                <FillRoot active={layout === "fill"}>{content}</FillRoot>
               </div>
             </main>
           </PageHeadingPresenceProvider>
@@ -671,17 +679,25 @@ export function PageBack({
 
 export function PageBody({
   className,
+  children,
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
   const page = useContext(PageContext);
   const integralState = useContext(PageIntegralStateContext);
+  const fill = useFillRegion();
   requireParent(page !== null, "PageBody", "Page");
   return (
     <div
       data-slot="page-body"
-      className={cn(integralState && "flex min-h-0 flex-1 flex-col", className)}
+      {...fill.attributes}
+      className={cn(
+        (integralState || fill.filling) && fillRegionClassName,
+        className,
+      )}
       {...props}
-    />
+    >
+      {fill.provide(children)}
+    </div>
   );
 }
 

package/src/ui/components/patterns/presentation.tsx

@@ -83,6 +83,7 @@ import {
   ContentTitle,
 } from "./content-header.tsx";
 import { SurfaceAssistant } from "./surface-assistant.tsx";
+import { fillRegionClassName, useFillRegion } from "./fill-region.ts";
 
 interface PresentationFrameProps {
   surface: PresentationSurface;
@@ -109,6 +110,35 @@ interface PresentationFrameProps {
 const bodyClassName =
   "h-full min-h-full [&>[data-slot=data-state]]:flex [&>[data-slot=data-state]]:min-h-full [&>[data-slot=data-state]]:items-center [&>[data-slot=data-state]]:justify-center";
 
+/**
+ * Corpo da Presentation. Em página `fill`, é o último elo da cadeia de altura (ADR 0024):
+ * a lista do body é filha direta dele e assume `fill` sem classe no consumidor.
+ */
+function PresentationBody({
+  layout,
+  className,
+  children,
+}: {
+  layout: "flow" | "fill";
+  className?: string;
+  children: ReactNode;
+}): ReactElement {
+  const fill = useFillRegion();
+  return (
+    <div
+      data-slot="presentation-body"
+      {...fill.attributes}
+      className={cn(
+        bodyClassName,
+        (layout === "fill" || fill.filling) && fillRegionClassName,
+        className,
+      )}
+    >
+      {fill.provide(children)}
+    </div>
+  );
+}
+
 function PresentationActions({
   children,
   equal = false,
@@ -166,17 +196,14 @@ function PresentationFrame({
     </PresentationActions>
   );
   const body = (
-    <div
-      data-slot="presentation-body"
-      className={cn(
-        bodyClassName,
-        layout === "fill" && "flex min-h-0 flex-1 flex-col",
-        bodyClassNameProp,
-      )}
-    >
+    <PresentationBody layout={layout} className={bodyClassNameProp}>
       {typeof children === "function" ? children(footerTarget) : children}
-    </div>
+    </PresentationBody>
   );
+  // Viewport entre o PageBody e o conteúdo. Em `fill`, é coluna flexível para a altura
+  // chegar ao conteúdo; a rolagem continua disponível como recurso de última instância.
+  const viewportFillClassName =
+    layout === "fill" ? fillRegionClassName : undefined;
   const withAssistant = (content: ReactElement): ReactElement =>
     assistantLabel === undefined || assistantPanel === undefined ? (
       content
@@ -224,7 +251,12 @@ function PresentationFrame({
           )}
           <PageBody className="min-h-0 flex-1 overflow-hidden">
             {withAssistant(
-              <div className="h-full overflow-x-hidden overflow-y-auto">
+              <div
+                className={cn(
+                  "h-full overflow-x-hidden overflow-y-auto",
+                  viewportFillClassName,
+                )}
+              >
                 {content}
               </div>,
             )}
@@ -268,6 +300,7 @@ function PresentationFrame({
                 className={cn(
                   "flex h-full min-h-0 flex-col overflow-x-hidden",
                   layout === "fill" ? "overflow-y-hidden" : "overflow-y-auto",
+                  viewportFillClassName,
                 )}
               >
                 {body}
@@ -303,7 +336,12 @@ function PresentationFrame({
         </PageHeader>
         <PageBody className="min-h-0 flex-1 overflow-hidden">
           {withAssistant(
-            <div className="h-full overflow-x-hidden overflow-y-auto px-8 py-8">
+            <div
+              className={cn(
+                "h-full overflow-x-hidden overflow-y-auto px-8 py-8",
+                viewportFillClassName,
+              )}
+            >
               {body}
             </div>,
           )}
@@ -315,26 +353,15 @@ function PresentationFrame({
 
   if (surface === "dialog") {
     return (
-      <Dialog
-        open={open}
-        onOpenChange={(nextOpen) => {
-          if (!nextOpen && blocked) return;
-          onOpenChange?.(nextOpen);
-        }}
-      >
+      <Dialog open={open} onOpenChange={onOpenChange}>
         <DialogContent
           className={cn(
             assistantOpen ? "h-[min(48rem,85vh)] max-w-5xl" : undefined,
             className,
           )}
           aria-describedby={undefined}
+          // `closeDisabled` bloqueia o botão de fechar, o Esc e o clique fora da superfície.
           closeDisabled={blocked}
-          onEscapeKeyDown={(event) => {
-            if (blocked) event.preventDefault();
-          }}
-          onPointerDownOutside={(event) => {
-            if (blocked) event.preventDefault();
-          }}
         >
           <div className="flex h-full min-h-0 flex-col">
             <DialogHeader>
@@ -363,13 +390,7 @@ function PresentationFrame({
   }
 
   return (
-    <Drawer
-      open={open}
-      onOpenChange={(nextOpen) => {
-        if (!nextOpen && blocked) return;
-        onOpenChange?.(nextOpen);
-      }}
-    >
+    <Drawer open={open} onOpenChange={onOpenChange}>
       <DrawerContent
         className={cn(
           assistantOpen
@@ -379,12 +400,6 @@ function PresentationFrame({
         )}
         aria-describedby={undefined}
         closeDisabled={blocked}
-        onEscapeKeyDown={(event) => {
-          if (blocked) event.preventDefault();
-        }}
-        onPointerDownOutside={(event) => {
-          if (blocked) event.preventDefault();
-        }}
       >
         <div className="flex h-full min-h-0 flex-col">
           <DrawerHeader>

package/src/ui/components/patterns/split.tsx

@@ -1,4 +1,4 @@
-import { Children, isValidElement, type ReactElement, type ReactNode } from 'react'
+import { Children, cloneElement, Fragment, isValidElement, type ReactElement, type ReactNode } from 'react'
 import { cn } from '../../lib/cn.ts'
 import { ResizableHandle, ResizablePanel, ResizablePanelGroup } from '../primitives/resizable.tsx'
 import { Pane, paneSizeToCss, type PaneProps, type PaneSize } from './pane.tsx'
@@ -30,10 +30,50 @@ export interface SplitProps {
   children: ReactNode
 }
 
+/**
+ * Expande fragments em qualquer profundidade, como quem escreve `<>{a}{b}</>` espera.
+ * `Children.toArray` numera as chaves por nível, então o filho de um fragment herda a
+ * chave do fragment como prefixo — sem isso, `.0` de dentro colidiria com `.0` de fora.
+ */
+function flattenFragments(children: ReactNode, prefix = ''): ReactNode[] {
+  return Children.toArray(children).flatMap((node): ReactNode[] => {
+    if (isValidElement(node) && node.type === Fragment)
+      return flattenFragments((node.props as { children?: ReactNode }).children, `${prefix}${String(node.key)}/`)
+    if (prefix !== '' && isValidElement(node)) return [cloneElement(node, { key: `${prefix}${String(node.key)}` })]
+    return [node]
+  })
+}
+
+/** Nome legível do filho recusado, para a mensagem apontar o nó certo. */
+function describeChild(node: ReactNode): string {
+  if (typeof node === 'string' || typeof node === 'number' || typeof node === 'bigint') {
+    const text = String(node).trim()
+    return `o texto "${text.length > 40 ? `${text.slice(0, 40)}…` : text}"`
+  }
+  if (isValidElement(node)) {
+    const type = node.type as string | { displayName?: string; name?: string }
+    const name = typeof type === 'string' ? type : (type.displayName ?? type.name ?? '')
+    return name === '' ? 'um componente sem nome' : `<${name}>`
+  }
+  return 'um nó que não é elemento React'
+}
+
+/**
+ * O Split lê `initialSize`, `minSize`, `grow` e `id` de cada Pane ANTES de renderizá-lo,
+ * então só enxerga um `<Pane>` escrito diretamente (ou dentro de fragment). Qualquer outro
+ * filho seria descartado sem aviso — a tela perderia uma região e ninguém saberia por quê.
+ */
 function panesOf(children: ReactNode): ReactElement<PaneProps>[] {
-  return Children.toArray(children).filter(
-    (child): child is ReactElement<PaneProps> => isValidElement<PaneProps>(child) && child.type === Pane,
-  )
+  return flattenFragments(children).flatMap((child) => {
+    if (isValidElement<PaneProps>(child) && child.type === Pane) return [child]
+    // Espaço em branco (um `{' '}` da formatação) não é conteúdo: nunca ocupou lugar.
+    if (typeof child === 'string' && child.trim() === '') return []
+    throw new Error(
+      `Split recebeu ${describeChild(child)} como filho, mas só distribui <Pane>: esse conteúdo ficaria fora do layout. ` +
+        'Envolva-o em um <Pane>. Se ele vem de um componente que devolve um <Pane>, escreva o <Pane> dentro do Split e ' +
+        'passe o componente como filho dele: o Split lê o tamanho de cada pane antes de renderizá-lo.',
+    )
+  })
 }
 
 // Números continuam percentuais por compatibilidade com Split/Pane. Strings preservam

package/src/ui/components/patterns/surface-anatomy.ts

@@ -9,7 +9,8 @@
  * Dois layouts, e cada um é um pacote indivisível:
  *
  * - `continuous` — sem divisores. O ritmo separa: o header se aproxima do corpo e a
- *   última região fecha o espaço de baixo. É o card de leitura.
+ *   última região — seja ela o header, o body ou o footer — fecha o espaço de baixo com
+ *   o mesmo respiro do topo. É o card de leitura.
  * - `sectioned` — regiões simétricas, com divisor entre as que forem adjacentes. É o
  *   modal, o drawer e o painel.
  *
@@ -18,7 +19,14 @@
  * é mais folgado que um painel de operação.
  */
 
-import { createContext, useContext } from "react";
+import {
+  createContext,
+  createElement,
+  useContext,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { FillBoundary } from "./fill-region.ts";
 
 export type SurfaceFamily = "card" | "dialog" | "drawer" | "pane";
 export type SurfaceLayout = "continuous" | "sectioned";
@@ -76,9 +84,11 @@ export const surfaceAnatomy: Record<SurfaceFamily, FamilyAnatomy> = {
   card: {
     regions: {
       // O `pb-3` do header e do body encurtam a distância até a região seguinte; quando
-      // o body é a última região, ele reassume o respiro de baixo (`[&:last-child]:pb-5`).
+      // a região é a última, ela reassume o respiro de baixo (`[&:last-child]:pb-5`) —
+      // inclusive o header sozinho, que sem isso fecharia o card mais apertado embaixo
+      // do que em cima.
       continuous: {
-        header: "px-5 pt-5 pb-3",
+        header: "px-5 pt-5 pb-3 [&:last-child]:pb-5",
         body: "px-5 py-3 [&:last-child]:pb-5 [&:first-child]:pt-5",
         footer: "px-5 pt-3 pb-5",
       },
@@ -95,7 +105,7 @@ export const surfaceAnatomy: Record<SurfaceFamily, FamilyAnatomy> = {
   dialog: {
     regions: {
       continuous: {
-        header: "p-4 pb-2",
+        header: "p-4 pb-2 [&:last-child]:pb-4",
         body: "p-4 py-2 [&:last-child]:pb-4 [&:first-child]:pt-4",
         footer: "p-4 pt-2",
       },
@@ -112,7 +122,7 @@ export const surfaceAnatomy: Record<SurfaceFamily, FamilyAnatomy> = {
   drawer: {
     regions: {
       continuous: {
-        header: "p-4 pb-2",
+        header: "p-4 pb-2 [&:last-child]:pb-4",
         body: "p-4 py-2 [&:last-child]:pb-4 [&:first-child]:pt-4",
         footer: "p-4 pt-2",
       },
@@ -129,7 +139,7 @@ export const surfaceAnatomy: Record<SurfaceFamily, FamilyAnatomy> = {
   pane: {
     regions: {
       continuous: {
-        header: "flex shrink-0 items-center px-3 pt-3 pb-2",
+        header: "flex shrink-0 items-center px-3 pt-3 pb-2 [&:last-child]:pb-3",
         body: "p-3 [&:first-child]:pt-3",
         footer: "px-3 pt-2 pb-3",
       },
@@ -200,7 +210,24 @@ export const surfaceActionsClasses = "flex shrink-0 items-center gap-2";
  */
 const SurfaceLayoutContext = createContext<SurfaceLayout | null>(null);
 
-export const SurfaceLayoutProvider = SurfaceLayoutContext.Provider;
+/**
+ * Publica o layout da superfície para os slots. A superfície também interrompe a
+ * propagação de `layout="fill"` da página (ADR 0024): a altura do seu corpo é decisão dela,
+ * inclusive quando um portal a renderiza dentro de uma página `fill`.
+ */
+export function SurfaceLayoutProvider({
+  value,
+  children,
+}: {
+  value: SurfaceLayout;
+  children?: ReactNode;
+}): ReactElement {
+  return createElement(
+    SurfaceLayoutContext.Provider,
+    { value },
+    createElement(FillBoundary, null, children),
+  );
+}
 
 const familyDefaultLayout: Record<SurfaceFamily, SurfaceLayout> = {
   card: "continuous",