@softize/opus 18.5.0 → 20.0.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;
@@ -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.
@@ -2144,8 +2151,11 @@ export function ActionList<TInput, TItem>({
         variant="plain"
         className={tableStateActive ? "h-full" : undefined}
         containerClassName={
+          // Quem rola é a linha de resultados, acima: aqui o contêiner abre mão da
+          // rolagem horizontal para não virar a referência do `sticky` do cabeçalho.
+          // `h-full` só no estado sem linhas, para a moldura vazia ocupar a altura.
           tableFillsAvailableHeight
-            ? "absolute inset-0 overflow-auto"
+            ? cn("overflow-x-visible", tableStateActive && "h-full")
             : undefined
         }
       >
@@ -2290,7 +2300,14 @@ export function ActionList<TInput, TItem>({
     ) : null;
 
   // — Rodapé (o estilo da casa): Página X de Y à esquerda · pager CENTRALIZADO ·
-  //   total à direita (grid de 3 colunas com laterais 1fr = centro geométrico) —
+  //   total à direita (grid de 3 colunas com laterais 1fr = centro geométrico).
+  //   Encosta na última linha: a borda de cima é o fecho da tabela, não a de um
+  //   bloco solto, então o rodapé não entra no `gap` da pilha.
+  //   Altura: 2.5rem de piso (a mesma do `TableHead`) para a faixa não mudar de
+  //   tamanho quando o pager aparece — ele ocupa 1.75rem e cabe dentro do piso.
+  //   O padding fica em 0.25rem só para o dia em que o conteúdo passar disso:
+  //   com `py-2` o padding empurraria o pager para fora e a faixa voltaria a
+  //   crescer —
   const pages =
     total !== undefined
       ? Math.max(1, Math.ceil(total / (state.limit ?? pageSize)))
@@ -2300,7 +2317,7 @@ export function ActionList<TInput, TItem>({
     total !== undefined && !isError ? (
       <div
         data-slot="action-list-footer"
-        className="grid grid-cols-[1fr_auto_1fr] items-center gap-3 border-t border-border px-3 py-1.5 text-xs text-muted-foreground"
+        className="grid min-h-10 grid-cols-[1fr_auto_1fr] items-center gap-3 border-t border-border px-3 py-1 text-xs text-muted-foreground"
       >
         <span>
           Página {state.page} de {pages}
@@ -2357,6 +2374,7 @@ export function ActionList<TInput, TItem>({
   return (
     <TooltipProvider>
       <div
+        ref={rootRef}
         data-action={action.name}
         data-layout={layout}
         className={cn(
@@ -2365,75 +2383,87 @@ export function ActionList<TInput, TItem>({
             : "space-y-3",
         )}
       >
-        {toolbar}
-        {beforeContent}
-        {selectionBar}
-        {/* Refetch com a lista já na tela: esmaece e trava interação até chegar. */}
-        <div
-          aria-busy={busy}
-          className={cn(
-            layout === "fill" && "relative flex min-h-0 flex-1 flex-col",
-            layout === "fill" &&
-              (tableFillsAvailableHeight ? "overflow-hidden" : "overflow-auto"),
-            busy && items.length > 0 && "pointer-events-none opacity-60",
-          )}
-        >
-          {body}
-        </div>
-        {footer}
-        {confirming !== null && (
-          <Dialog
-            mode="alert"
-            open
-            onOpenChange={(o) => {
-              if (!o) setConfirming(null);
-            }}
-          >
-            <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>
+        {/* 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",
               )}
-              <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>
-        )}
+            >
+              {body}
+            </div>
+            {footer}
+          </div>
+          {confirming !== null && (
+            <Dialog
+              mode="alert"
+              open
+              onOpenChange={(o) => {
+                if (!o) setConfirming(null);
+              }}
+            >
+              <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/pane.tsx

@@ -0,0 +1,294 @@
+/**
+ * Pane — a superfície encaixável de um Split: a coluna ou faixa que hospeda navegação,
+ * lista ou conteúdo, com regiões fixas no topo e no rodapé e um corpo que rola.
+ *
+ * Até a ADR 0023 esta família vivia partida: a raiz em `split.tsx`, os slots em
+ * `sidebar.tsx`, sem validação entre eles e com padding assimétrico (header sem recuo,
+ * footer com `p-2`). Agora raiz e slots moram aqui e derivam a anatomia da mesma tabela
+ * das demais famílias.
+ *
+ *   <Pane>
+ *     <PaneHeader><PaneMedia>…</PaneMedia><PaneTitle>Conversas</PaneTitle><PaneActions>…</PaneActions></PaneHeader>
+ *     <PaneBody>…</PaneBody>
+ *     <PaneFooter>…</PaneFooter>
+ *   </Pane>
+ *
+ * `inset` continua existindo para o pane que NÃO usa slots — a caixa simples que recebe
+ * conteúdo direto. Quando há slots, o recuo é de cada região, e o inset do pane vira
+ * `none` sozinho: o divisor precisa alcançar a borda.
+ */
+import {
+  Children,
+  Fragment,
+  isValidElement,
+  type CSSProperties,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+
+import { cn } from "../../lib/cn.ts";
+import { headingTags, type HeadingLevel } from "./heading-level.ts";
+import {
+  SurfaceLayoutProvider,
+  surfaceActionsClasses,
+  surfaceDescriptionClasses,
+  surfaceHeaderRowClasses,
+  surfaceRegionClasses,
+  surfaceTitleClasses,
+  useSurfaceLayout,
+  type SurfaceLayout,
+} from "./surface-anatomy.ts";
+import { SurfaceHeader } from "./surface-header.tsx";
+import { SurfaceMedia, type SurfaceMediaProps } from "./surface-media.tsx";
+
+export type PaneSize =
+  | number
+  | `${number}%`
+  | `${number}rem`
+  | `${number}em`
+  | `${number}vh`
+  | `${number}vw`
+  | `${number}px`;
+
+// Números continuam percentuais por compatibilidade com Split/Pane. Strings preservam
+// a unidade explícita para layouts que precisam de um limite físico, como `28rem`.
+export function paneSizeToCss(value: PaneSize): string {
+  return typeof value === "number" ? `${value}%` : value;
+}
+
+export interface PaneProps {
+  /** Identidade estável do painel dentro do grupo. */
+  id?: string;
+  /** Tamanho inicial. Números representam porcentagens; strings aceitam %, rem, em, vh, vw e px. */
+  initialSize?: PaneSize;
+  /** Tamanho mínimo quando o split é redimensionável. */
+  minSize?: PaneSize;
+  /** Tamanho máximo quando o split é redimensionável. */
+  maxSize?: PaneSize;
+  /** Ocupa o espaço remanescente no layout simples. */
+  grow?: boolean;
+  /**
+   * Respiro interno do pane sem slots. Com header, body ou footer como filhos DIRETOS o
+   * default passa a `none`, porque aí o recuo é de cada região. Quando os slots vêm
+   * dentro de outro componente — a `Sidebar`, por exemplo —, o pane não os enxerga:
+   * declare `inset="none"` você mesmo.
+   */
+  inset?: "none" | "sm" | "md" | "lg";
+  /** Anatomia das regiões: `sectioned` (default) ou `continuous` — ADR 0023. */
+  layout?: SurfaceLayout;
+  className?: string;
+  children: ReactNode;
+}
+
+const insets = { none: "", sm: "p-2", md: "p-4", lg: "p-6" } as const;
+
+/** Expande fragments de primeiro nível antes de procurar os slots. */
+function flatten(children: ReactNode): ReactNode[] {
+  return Children.toArray(children).flatMap((node) =>
+    isValidElement(node) && node.type === Fragment
+      ? Children.toArray((node.props as { children?: ReactNode }).children)
+      : [node],
+  );
+}
+
+function hasStructuralSlots(children: ReactNode): boolean {
+  return flatten(children).some(
+    (node) =>
+      isValidElement(node) &&
+      (node.type === PaneHeader ||
+        node.type === PaneBody ||
+        node.type === PaneContent ||
+        node.type === PaneFooter),
+  );
+}
+
+/** Um conteúdo encaixável. Sua posição é dada pela ordem dentro de <Split>. */
+export function Pane({
+  id,
+  initialSize,
+  grow = false,
+  inset,
+  layout = "sectioned",
+  className,
+  children,
+}: PaneProps): ReactElement {
+  const style: CSSProperties | undefined =
+    initialSize === undefined
+      ? undefined
+      : { flexBasis: paneSizeToCss(initialSize) };
+  const structural = hasStructuralSlots(children);
+  const resolvedInset = inset ?? (structural ? "none" : "md");
+  return (
+    <SurfaceLayoutProvider value={layout}>
+      <div
+        id={id === undefined ? undefined : String(id)}
+        data-slot="pane"
+        data-inset={resolvedInset}
+        data-layout={layout}
+        className={cn(
+          "min-h-0 min-w-0 shrink-0",
+          grow && "flex-1",
+          // Com slots o pane é uma coluna: header fixo, corpo que rola, footer fixo.
+          structural && "flex flex-col",
+          insets[resolvedInset],
+          className,
+        )}
+        style={style}
+      >
+        {children}
+      </div>
+    </SurfaceLayoutProvider>
+  );
+}
+
+/** Faixa fixa no topo de um pane — marca, contexto ou ações locais. */
+export function PaneHeader({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<"div">): ReactElement {
+  const layout = useSurfaceLayout("pane");
+  return (
+    <SurfaceHeader
+      name="PaneHeader"
+      slot="pane"
+      slots={{
+        media: PaneMedia,
+        title: PaneTitle,
+        description: PaneDescription,
+        actions: PaneActions,
+      }}
+      leadingPlacement="inline"
+      titleRequired={false}
+      // O pane é a superfície genérica: além dos slots, o header hospeda marca, busca ou
+      // chrome que não são título nem ação (ADR 0023).
+      allowFreeContent
+      rowClassName={surfaceHeaderRowClasses("pane")}
+      className={cn(surfaceRegionClasses("pane", layout, "header"), className)}
+      {...props}
+    >
+      {children}
+    </SurfaceHeader>
+  );
+}
+
+/** Moldura de ícone ou imagem que abre a linha do header. */
+export function PaneMedia(props: SurfaceMediaProps): ReactElement {
+  return <SurfaceMedia slot="pane-media" size="xs" {...props} />;
+}
+
+export function PaneTitle({
+  className,
+  level = 2,
+  ...props
+}: React.ComponentProps<"h2"> & {
+  /** Hierarquia do documento (`h1`–`h6`). O tamanho vem do layout, nunca do nível. */
+  level?: HeadingLevel;
+}): ReactElement {
+  const layout = useSurfaceLayout("pane");
+  const Comp = headingTags[level];
+  return (
+    <Comp
+      data-slot="pane-title"
+      className={cn(
+        "min-w-0 truncate",
+        surfaceTitleClasses("pane", layout),
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function PaneDescription({
+  className,
+  ...props
+}: React.ComponentProps<"p">): ReactElement {
+  return (
+    <p
+      data-slot="pane-description"
+      className={cn("truncate", surfaceDescriptionClasses("pane"), className)}
+      {...props}
+    />
+  );
+}
+
+/** Ações do header — a família posiciona no extremo oposto ao título. */
+export function PaneActions({
+  className,
+  ...props
+}: React.ComponentProps<"div">): ReactElement {
+  return (
+    <div
+      data-slot="pane-actions"
+      className={cn(surfaceActionsClasses, className)}
+      {...props}
+    />
+  );
+}
+
+/** Região rolável que ocupa o espaço restante de um pane. */
+export function PaneBody({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<"div">): ReactElement {
+  const layout = useSurfaceLayout("pane");
+  return (
+    <div
+      data-slot="pane-body"
+      className={cn(
+        "min-h-0 flex-1 overflow-y-auto",
+        surfaceRegionClasses("pane", layout, "body"),
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** @deprecated Use PaneBody. Alias mantido para migração; sai numa próxima versão major. */
+export function PaneContent({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<"div">): ReactElement {
+  const layout = useSurfaceLayout("pane");
+  return (
+    <div
+      data-slot="pane-content"
+      className={cn(
+        "min-h-0 flex-1 overflow-y-auto",
+        surfaceRegionClasses("pane", layout, "body"),
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+/** Faixa fixa no rodapé de um pane para ações persistentes. */
+export function PaneFooter({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<"div">): ReactElement {
+  const layout = useSurfaceLayout("pane");
+  return (
+    <div
+      data-slot="pane-footer"
+      className={cn(
+        "shrink-0",
+        surfaceRegionClasses("pane", layout, "footer"),
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}