@softize/opus 19.0.0 → 20.0.0

package/src/ui/components/patterns/fill-region.ts

@@ -0,0 +1,150 @@
+/**
+ * Propagação da ocupação de altura (interno) — ADR 0024.
+ *
+ * `Page layout="fill"` limita a página à altura do shell; a `Presentation` em página herda
+ * esse limite pela `Page` que ela monta. Para uma região interna ocupar a folga e rolar
+ * sozinha, cada elemento entre a raiz limitada e essa região precisa repassar a altura como
+ * coluna flexível. Este módulo faz essa cadeia se formar sem classes no consumidor:
+ *
+ * - a raiz (`FillRoot`) publica o contexto;
+ * - os elos canônicos (`PageBody`, `Content`, `ContentBody`, o corpo da `Presentation`)
+ *   leem o contexto com `useFillRegion` e o republicam para os filhos;
+ * - a folha (`ActionList`) usa `useFillLeaf`: assume `fill` por padrão quando o elemento
+ *   pai é um elo e se registra na cadeia;
+ * - um elo só vira coluna flexível quando uma folha se registrou abaixo dele. Irmãos sem
+ *   folha mantêm a altura do próprio conteúdo, e uma página `fill` sem lista não muda;
+ * - superfícies com anatomia própria (Card, Dialog, Drawer, Pane) cortam a cadeia com
+ *   `FillBoundary`: a altura delas é decisão delas, inclusive quando um portal as renderiza
+ *   dentro de uma página `fill`.
+ *
+ * O registro acontece em `useLayoutEffect`, então as classes chegam antes da primeira pintura.
+ */
+
+import {
+  createContext,
+  createElement,
+  useContext,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactElement,
+  type ReactNode,
+  type RefObject,
+} from "react";
+
+export type FillLayout = "flow" | "fill";
+
+interface FillChain {
+  /** Anuncia uma folha abaixo deste elo; devolve a retirada do anúncio. */
+  register(): () => void;
+}
+
+const FillChainContext = createContext<FillChain | null>(null);
+
+/** A raiz já tem altura limitada: não há o que propagar acima dela. */
+const rootChain: FillChain = { register: () => () => {} };
+
+/** Classes de um elo que repassa a altura à folha registrada abaixo dele. */
+export const fillRegionClassName = "flex min-h-0 flex-1 flex-col";
+
+/**
+ * Atributo que marca um elo da cadeia no DOM: `"true"` quando repassa a altura, `"false"`
+ * quando está na cadeia sem folha abaixo. A folha só assume `fill` implícito quando o
+ * elemento pai o carrega — um contêiner próprio no meio não repassa a altura.
+ */
+export const fillRegionAttribute = "data-fill";
+
+/** Publica a cadeia quando `active`; caso contrário a interrompe. */
+export function FillRoot({
+  active,
+  children,
+}: {
+  active: boolean;
+  children?: ReactNode;
+}): ReactElement {
+  return createElement(
+    FillChainContext.Provider,
+    { value: active ? rootChain : null },
+    children,
+  );
+}
+
+/** Interrompe a cadeia: o conteúdo abaixo decide a própria altura. */
+export function FillBoundary({
+  children,
+}: {
+  children?: ReactNode;
+}): ReactElement {
+  return createElement(FillChainContext.Provider, { value: null }, children);
+}
+
+export interface FillRegion {
+  /** O elo está em uma cadeia `fill`, com ou sem folha abaixo. */
+  inChain: boolean;
+  /** Uma folha se registrou abaixo: o elo deve repassar a altura. */
+  filling: boolean;
+  /** Atributos do elemento do elo. */
+  attributes: { "data-fill"?: "true" | "false" };
+  /** Republica a cadeia para os filhos do elo. */
+  provide(children: ReactNode): ReactElement;
+}
+
+/** Elo da cadeia: lê o contexto, conta as folhas abaixo e o republica. */
+export function useFillRegion(): FillRegion {
+  const parent = useContext(FillChainContext);
+  const [leaves, setLeaves] = useState(0);
+  const chain = useMemo<FillChain | null>(
+    () =>
+      parent === null
+        ? null
+        : {
+            register() {
+              setLeaves((count) => count + 1);
+              const releaseParent = parent.register();
+              let registered = true;
+              return () => {
+                if (!registered) return;
+                registered = false;
+                setLeaves((count) => Math.max(0, count - 1));
+                releaseParent();
+              };
+            },
+          },
+    [parent],
+  );
+  const inChain = parent !== null;
+  const filling = inChain && leaves > 0;
+  return {
+    inChain,
+    filling,
+    attributes: inChain ? { "data-fill": filling ? "true" : "false" } : {},
+    provide: (children) =>
+      createElement(FillChainContext.Provider, { value: chain }, children),
+  };
+}
+
+/**
+ * Folha da cadeia. Sem `layout` explícito, assume `fill` quando o elemento pai é um elo;
+ * com `layout="fill"` explícito, registra-se mesmo sob um contêiner próprio, que passa a
+ * ser responsabilidade de quem o escreveu. `layout="flow"` nunca se registra.
+ */
+export function useFillLeaf<TElement extends HTMLElement>(
+  layout: FillLayout | undefined,
+): { layout: FillLayout; ref: RefObject<TElement | null> } {
+  const chain = useContext(FillChainContext);
+  const ref = useRef<TElement | null>(null);
+  const [linked, setLinked] = useState(false);
+  useLayoutEffect(() => {
+    setLinked(
+      chain !== null &&
+        ref.current?.parentElement?.hasAttribute(fillRegionAttribute) === true,
+    );
+  }, [chain]);
+  const resolved = layout ?? (linked ? "fill" : "flow");
+  useLayoutEffect(() => {
+    if (chain === null || resolved !== "fill") return undefined;
+    return chain.register();
+  }, [chain, resolved]);
+  return { layout: resolved, ref };
+}

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;
@@ -1666,7 +1672,7 @@ function RowActions({ children }: { children: ReactNode }) {
 export function ActionList<TInput, TItem>({
   action,
   input,
-  layout = "flow",
+  layout: layoutProp,
   toolbarActions,
   columns,
   cells,
@@ -1693,6 +1699,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 +2374,7 @@ export function ActionList<TInput, TItem>({
   return (
     <TooltipProvider>
       <div
+        ref={rootRef}
         data-action={action.name}
         data-layout={layout}
         className={cn(
@@ -2375,84 +2383,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