@softize/opus 14.0.0 → 15.0.1

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

@@ -20,6 +20,9 @@
  */
 
 import {
+  Children,
+  Fragment,
+  isValidElement,
   useEffect,
   useLayoutEffect,
   useMemo,
@@ -74,6 +77,7 @@ import {
   PaginationPrevious,
 } from "../primitives/pagination.tsx";
 import { Button } from "../primitives/button.tsx";
+import { ButtonGroup } from "../primitives/button-group.tsx";
 import { Calendar } from "../primitives/calendar.tsx";
 import { Checkbox } from "../primitives/checkbox.tsx";
 import {
@@ -262,7 +266,9 @@ export interface ActionFilterBarProps {
   filterOptions?: Record<string, SelectOption[]>;
   onRefresh?: () => Promise<void> | void;
   refreshing?: boolean;
-  /** Ações de apresentação do consumidor, renderizadas depois do refresh. */
+  /** Controles auxiliares, agrupados com o refresh em um ButtonGroup espaçado. */
+  controls?: ReactNode;
+  /** Ações do consumidor, separadas do grupo de controles. */
   actions?: ReactNode;
 }
 
@@ -293,6 +299,8 @@ export interface ActionListProps<TInput, TItem> {
   action: ListActionLike;
   /** Input BASE (escopo fixo, ex.: { workspaceId }) — a toolbar soma por cima. */
   input: TInput;
+  /** Ações do consumidor no fim da barra de filtros, depois dos controles de exibição. */
+  toolbarActions?: ReactNode;
   /** Tabela explícita — sobrepõe as colunas do contrato. */
   columns?: ActionListColumn<TItem>[];
   /** Células custom POR CIMA das colunas do contrato (chave = column.key). */
@@ -904,6 +912,7 @@ export function ActionFilterBar({
   filterOptions,
   onRefresh,
   refreshing = false,
+  controls,
   actions,
 }: ActionFilterBarProps): React.ReactElement {
   const dicts = useDicts();
@@ -1047,7 +1056,7 @@ export function ActionFilterBar({
             <Tooltip>
               <TooltipTrigger asChild>
                 <Button
-                  variant="outline"
+                  variant="ghost"
                   size="icon"
                   className="shrink-0"
                   aria-label="Filtros"
@@ -1061,27 +1070,32 @@ export function ActionFilterBar({
           )}
           <div className="ml-auto flex min-w-0 items-center gap-2">
             {!searchFirst && searchBox}
-            {onRefresh !== undefined && (
-              <Tooltip>
-                <TooltipTrigger asChild>
-                  <Button
-                    variant="outline"
-                    size="icon"
-                    className="shrink-0"
-                    aria-label="Recarregar"
-                    onClick={() => void onRefresh()}
-                    disabled={refreshing}
-                  >
-                    <RefreshCw
-                      className={cn(
-                        "h-3.5 w-3.5",
-                        refreshing && "animate-spin",
-                      )}
-                    />
-                  </Button>
-                </TooltipTrigger>
-                <TooltipContent>Recarregar</TooltipContent>
-              </Tooltip>
+            {(onRefresh !== undefined || controls !== undefined) && (
+              <ButtonGroup mode="spaced">
+                {onRefresh !== undefined && (
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <Button
+                        variant="ghost"
+                        size="icon"
+                        className="shrink-0"
+                        aria-label="Recarregar"
+                        onClick={() => void onRefresh()}
+                        disabled={refreshing}
+                      >
+                        <RefreshCw
+                          className={cn(
+                            "h-3.5 w-3.5",
+                            refreshing && "animate-spin",
+                          )}
+                        />
+                      </Button>
+                    </TooltipTrigger>
+                    <TooltipContent>Recarregar</TooltipContent>
+                  </Tooltip>
+                )}
+                {controls}
+              </ButtonGroup>
             )}
             {actions}
           </div>
@@ -1131,9 +1145,35 @@ export function ActionFilterBar({
 // ActionList
 // =============================================================================
 
+/**
+ * Ações de uma linha da tabela. Com duas ou mais, agrupa e espaça; com uma só, não
+ * materializa o `ButtonGroup` — um `role="group"` sem nome por linha enche a árvore de
+ * acessibilidade sem informar nada, e `mode="spaced"` não teria o que espaçar.
+ */
+function RowActions({ children }: { children: ReactNode }) {
+  // O consumidor costuma devolver as ações dentro de um fragment, que conta como UM filho —
+  // e às vezes dentro de fragments aninhados. Expandir recursivamente, e contar só elementos,
+  // evita tanto tratar duas ações como uma quanto deixar um espaço em branco virar ação.
+  const expand = (node: ReactNode): ReactNode[] =>
+    Children.toArray(node).flatMap((child) =>
+      isValidElement(child) && child.type === Fragment
+        ? expand((child.props as { children?: ReactNode }).children)
+        : [child],
+    );
+  const alone = expand(children).filter(isValidElement).length < 2;
+  return alone ? (
+    <div className="flex justify-end">{children}</div>
+  ) : (
+    <ButtonGroup mode="spaced" className="ml-auto">
+      {children}
+    </ButtonGroup>
+  );
+}
+
 export function ActionList<TInput, TItem>({
   action,
   input,
+  toolbarActions,
   columns,
   cells,
   filterOptions,
@@ -1394,7 +1434,7 @@ export function ActionList<TInput, TItem>({
         filterOptions={filterOptions}
         onRefresh={() => refetch()}
         refreshing={isLoading}
-        actions={
+        controls={
           <>
             {hasSegment && (
               <ToggleGroup
@@ -1433,7 +1473,7 @@ export function ActionList<TInput, TItem>({
                 <TooltipTrigger asChild>
                   <PopoverTrigger asChild>
                     <Button
-                      variant="outline"
+                      variant="ghost"
                       size="icon"
                       className="shrink-0"
                       aria-label="Exibição"
@@ -1517,6 +1557,7 @@ export function ActionList<TInput, TItem>({
             </Popover>
           </>
         }
+        actions={toolbarActions}
       />
     </div>
   ) : null;
@@ -1621,7 +1662,7 @@ export function ActionList<TInput, TItem>({
                   className="w-px whitespace-nowrap text-right"
                   onClick={(e) => e.stopPropagation()}
                 >
-                  {rowActions(item)}
+                  <RowActions>{rowActions(item)}</RowActions>
                 </TableCell>
               )}
             </TableRow>

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

@@ -7,7 +7,12 @@
  * as superfícies são as mesmas (state-surface.tsx), aqui na escala da página.
  */
 
-import type { ReactNode } from "react";
+import {
+  createContext,
+  useContext,
+  useLayoutEffect,
+  type ReactNode,
+} from "react";
 import { cn } from "../../lib/cn.ts";
 import {
   DEFAULT_RETRY_LABEL,
@@ -18,6 +23,23 @@ import {
 
 export type PageStateStatus = "loading" | "error" | "empty" | "ready";
 
+const PageStatePresenceContext = createContext<(() => () => void) | null>(null);
+
+/** Integração interna: permite que Page reconheça um PageState mesmo dentro de outro componente. */
+export function PageStatePresenceProvider({
+  register,
+  children,
+}: {
+  register: () => () => void;
+  children: ReactNode;
+}): React.ReactElement {
+  return (
+    <PageStatePresenceContext.Provider value={register}>
+      {children}
+    </PageStatePresenceContext.Provider>
+  );
+}
+
 export interface PageStateProps {
   status: PageStateStatus;
   /** Título específico do estado. Defaults seguros existem para loading, error e empty. */
@@ -54,15 +76,31 @@ export function PageState({
   children,
   className,
 }: PageStateProps): React.ReactElement {
+  const registerPresence = useContext(PageStatePresenceContext);
+  useLayoutEffect(() => {
+    if (status === "ready" || registerPresence === null) return;
+    return registerPresence();
+  }, [registerPresence, status]);
+
   if (status === "ready") return <>{children}</>;
 
+  const stateClassName = cn(
+    "flex min-h-64 flex-1 items-center justify-center",
+    className,
+  );
+
   if (status === "loading") {
     return (
-      <div data-slot="page-state" data-status="loading" className={className}>
+      <div
+        data-slot="page-state"
+        data-status="loading"
+        className={stateClassName}
+      >
         <LoadingSurface
-          className="min-h-64"
+          className="w-full min-h-64"
           title={title ?? "Carregando…"}
           description={description}
+          titleLevel={1}
         />
       </div>
     );
@@ -73,10 +111,12 @@ export function PageState({
       <div
         data-slot="page-state"
         data-status="error"
-        className={cn("flex min-h-64 items-center justify-center", className)}
+        className={stateClassName}
       >
         <ErrorSurface
-          className="max-w-xl"
+          presentation="state"
+          className="w-full max-w-xl"
+          titleLevel={1}
           icon={icon}
           title={title ?? errorMessage}
           description={description}
@@ -90,9 +130,11 @@ export function PageState({
   }
 
   return (
-    <div data-slot="page-state" data-status="empty" className={className}>
+    <div data-slot="page-state" data-status="empty" className={stateClassName}>
       <EmptySurface
+        frame="bare"
         className="min-h-64"
+        titleLevel={1}
         icon={icon}
         title={title ?? emptyMessage}
         description={description}

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

@@ -9,17 +9,38 @@ import {
   Children,
   createContext,
   isValidElement,
+  useCallback,
   useContext,
+  useRef,
+  useState,
   type HTMLAttributes,
+  type ComponentProps,
   type ReactElement,
   type ReactNode,
 } from "react";
 import { createPortal } from "react-dom";
+import { ArrowLeft } from "lucide-react";
 import { cn } from "../../lib/cn.ts";
+import { Button } from "../primitives/button.tsx";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "../primitives/tooltip.tsx";
 import { SurfaceHeader, surfaceHeaderClasses } from "./surface-header.tsx";
+import { PageStatePresenceProvider } from "./page-state.tsx";
+
+export type PageHeaderVariant = "default" | "bar";
+
+interface PageContextValue {
+  headerVariant: PageHeaderVariant;
+  containerClassName?: string;
+}
 
-const PageContext = createContext(false);
-const PageHeaderContext = createContext(false);
+const PageContext = createContext<PageContextValue | null>(null);
+const PageHeaderContext = createContext<PageHeaderVariant | null>(null);
+const PageIntegralStateContext = createContext(false);
 const PageActionsTargetContext = createContext<HTMLElement | null>(null);
 
 export function PageActionsTarget({
@@ -54,8 +75,6 @@ interface PageBaseProps extends Omit<
 
 interface PageShorthandProps extends PageBaseProps {
   title: ReactNode;
-  /** Total de itens ao lado do título. */
-  count?: number;
   description?: ReactNode;
   actions?: ReactNode;
   children: ReactNode;
@@ -63,7 +82,6 @@ interface PageShorthandProps extends PageBaseProps {
 
 interface PageComposedProps extends PageBaseProps {
   title?: never;
-  count?: never;
   description?: never;
   actions?: never;
   children: ReactNode;
@@ -73,7 +91,6 @@ export type PageProps = PageShorthandProps | PageComposedProps;
 
 export function Page({
   title,
-  count,
   description,
   actions,
   className,
@@ -82,6 +99,25 @@ export function Page({
 }: PageProps): ReactElement {
   const shorthand = title !== undefined;
   const nodes = Children.toArray(children);
+  const headers = nodes.filter(
+    (node) => isValidElement(node) && node.type === PageHeader,
+  );
+  const bodies = nodes.filter(
+    (node) => isValidElement(node) && node.type === PageBody,
+  );
+  const activeStateCount = useRef(0);
+  const [integralState, setIntegralState] = useState(false);
+  const registerIntegralState = useCallback(() => {
+    activeStateCount.current += 1;
+    setIntegralState(true);
+    let registered = true;
+    return () => {
+      if (!registered) return;
+      registered = false;
+      activeStateCount.current = Math.max(0, activeStateCount.current - 1);
+      setIntegralState(activeStateCount.current > 0);
+    };
+  }, []);
   if (
     shorthand &&
     nodes.some((node) => isValidElement(node) && node.type === PageHeader)
@@ -91,12 +127,6 @@ export function Page({
     );
   }
   if (!shorthand) {
-    const headers = nodes.filter(
-      (node) => isValidElement(node) && node.type === PageHeader,
-    );
-    const bodies = nodes.filter(
-      (node) => isValidElement(node) && node.type === PageBody,
-    );
     if (
       headers.length !== 1 ||
       bodies.length !== 1 ||
@@ -107,49 +137,105 @@ export function Page({
       );
     }
   }
+  const headerVariant: PageHeaderVariant = shorthand
+    ? "default"
+    : ((headers[0] as ReactElement<PageHeaderProps> | undefined)?.props
+        .variant ?? "default");
+  const pageContext: PageContextValue = {
+    headerVariant,
+    containerClassName: className,
+  };
+
+  const content = shorthand ? (
+    <>
+      <PageHeader>
+        <PageTitle>{title}</PageTitle>
+        {description !== undefined && (
+          <PageDescription>{description}</PageDescription>
+        )}
+        {actions !== undefined && <PageActions>{actions}</PageActions>}
+      </PageHeader>
+      <PageBody>{children}</PageBody>
+    </>
+  ) : (
+    children
+  );
 
   return (
-    <PageContext.Provider value>
-      <main data-slot="page" className="min-w-0 flex-1" {...props}>
-        <div className={cn("mx-auto max-w-7xl space-y-6 px-8 py-8", className)}>
-          {shorthand ? (
-            <>
-              <PageHeader>
-                <PageTitle>{title}</PageTitle>
-                {count !== undefined && <PageMeta>{count}</PageMeta>}
-                {description !== undefined && (
-                  <PageDescription>{description}</PageDescription>
+    <PageContext.Provider value={pageContext}>
+      <PageIntegralStateContext.Provider value={integralState}>
+        <PageStatePresenceProvider register={registerIntegralState}>
+          <main
+            data-slot="page"
+            className={cn(
+              "min-w-0 flex-1",
+              (headerVariant === "bar" || integralState) && "flex flex-col",
+              // A barra contém a rolagem (`min-h-0`); o estado integral ocupa a altura
+              // disponível (`min-h-full`). Emitir os dois juntos deixava o resultado por
+              // conta da ordem do CSS gerado — no estado integral, quem manda é ele.
+              integralState ? "min-h-full" : headerVariant === "bar" && "min-h-0",
+            )}
+            {...props}
+          >
+            {headerVariant === "bar" ? (
+              content
+            ) : (
+              <div
+                className={cn(
+                  "mx-auto max-w-7xl space-y-6 px-8 py-8",
+                  integralState &&
+                    "flex min-h-full w-full flex-1 flex-col space-y-0",
+                  className,
                 )}
-                {actions !== undefined && <PageActions>{actions}</PageActions>}
-              </PageHeader>
-              <PageBody>{children}</PageBody>
-            </>
-          ) : (
-            children
-          )}
-        </div>
-      </main>
+              >
+                {content}
+              </div>
+            )}
+          </main>
+        </PageStatePresenceProvider>
+      </PageIntegralStateContext.Provider>
     </PageContext.Provider>
   );
 }
 
 /** A anatomia é a de `SurfaceHeader`, a mesma de `ContentHeader`; só os slots mudam de nome. */
+export interface PageHeaderProps extends HTMLAttributes<HTMLDivElement> {
+  /** `default` fica no container; `bar` cria uma faixa compacta no topo da Page. */
+  variant?: PageHeaderVariant;
+}
+
 export function PageHeader({
+  variant = "default",
+  className,
   children,
   ...props
-}: HTMLAttributes<HTMLDivElement>): ReactElement {
-  requireParent(useContext(PageContext), "PageHeader", "Page");
+}: PageHeaderProps): ReactElement {
+  const page = useContext(PageContext);
+  const integralState = useContext(PageIntegralStateContext);
+  requireParent(page !== null, "PageHeader", "Page");
+  if (integralState) return <></>;
   return (
-    <PageHeaderContext.Provider value>
+    <PageHeaderContext.Provider value={variant}>
       <SurfaceHeader
         name="PageHeader"
         slot="page"
         slots={{
+          leading: [PageBack, PageNavigation],
           title: PageTitle,
-          count: PageMeta,
           description: PageDescription,
           actions: PageActions,
         }}
+        leadingPlacement={variant === "bar" ? "inline" : "above"}
+        contentClassName={
+          variant === "bar"
+            ? cn("mx-auto w-full max-w-7xl px-8 py-2", page?.containerClassName)
+            : undefined
+        }
+        className={cn(
+          variant === "bar" &&
+            "shrink-0 border-b border-border bg-background text-foreground",
+          className,
+        )}
         {...props}
       >
         {children}
@@ -162,11 +248,17 @@ export function PageTitle({
   className,
   ...props
 }: HTMLAttributes<HTMLHeadingElement>): ReactElement {
-  requireParent(useContext(PageHeaderContext), "PageTitle", "PageHeader");
+  const variant = useContext(PageHeaderContext);
+  requireParent(variant !== null, "PageTitle", "PageHeader");
   return (
     <h1
       data-slot="page-title"
-      className={cn(surfaceHeaderClasses.page.title, className)}
+      className={cn(
+        variant === "bar"
+          ? "truncate text-sm font-semibold"
+          : surfaceHeaderClasses.page.title,
+        className,
+      )}
       {...props}
     />
   );
@@ -176,50 +268,127 @@ export function PageDescription({
   className,
   ...props
 }: HTMLAttributes<HTMLParagraphElement>): ReactElement {
-  requireParent(useContext(PageHeaderContext), "PageDescription", "PageHeader");
+  const variant = useContext(PageHeaderContext);
+  requireParent(variant !== null, "PageDescription", "PageHeader");
   return (
     <p
       data-slot="page-description"
-      className={cn(surfaceHeaderClasses.page.description, className)}
+      className={cn(
+        variant === "bar"
+          ? "mt-0.5 truncate text-xs text-muted-foreground"
+          : surfaceHeaderClasses.page.description,
+        className,
+      )}
       {...props}
     />
   );
 }
 
-export function PageMeta({
+export function PageActions({
   className,
   ...props
-}: HTMLAttributes<HTMLSpanElement>): ReactElement {
-  requireParent(useContext(PageHeaderContext), "PageMeta", "PageHeader");
-  return (
-    <span
-      data-slot="page-meta"
-      className={cn(surfaceHeaderClasses.page.count, className)}
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  const variant = useContext(PageHeaderContext);
+  requireParent(variant !== null, "PageActions", "PageHeader");
+  const target = useContext(PageActionsTargetContext);
+  const actions = (
+    <div
+      data-slot="page-actions"
+      className={cn(
+        variant === "bar"
+          ? "flex shrink-0 items-center gap-2"
+          : surfaceHeaderClasses.page.actions,
+        className,
+      )}
       {...props}
     />
   );
+  return target === null ? actions : createPortal(actions, target);
 }
 
-export function PageActions({
+export interface PageBackProps extends Omit<ComponentProps<"a">, "children" | "href"> {
+  /** Nome do destino pai. Na barra, também alimenta tooltip e nome acessível. */
+  children: ReactNode;
+  /** Destino explícito. Obrigatório: sem `href` o elemento não é tabulável, não expõe
+   *  `role="link"` e o navegador descarta o nome acessível — na barra, onde não há texto
+   *  visível, o retorno simplesmente desapareceria para tecnologia assistiva. */
+  href: string;
+}
+
+/** Região introdutória para uma trilha estrutural com mais de um ancestral relevante. */
+export function PageNavigation({
   className,
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
-  requireParent(useContext(PageHeaderContext), "PageActions", "PageHeader");
-  const target = useContext(PageActionsTargetContext);
-  const actions = (
+  requireParent(
+    useContext(PageHeaderContext) !== null,
+    "PageNavigation",
+    "PageHeader",
+  );
+  return (
     <div
-      data-slot="page-actions"
-      className={cn(surfaceHeaderClasses.page.actions, className)}
+      data-slot="page-navigation-content"
+      className={cn("min-w-0", className)}
       {...props}
     />
   );
-  return target === null ? actions : createPortal(actions, target);
+}
+
+export function PageBack({
+  children,
+  className,
+  "aria-label": ariaLabel,
+  ...props
+}: PageBackProps): ReactElement {
+  const variant = useContext(PageHeaderContext);
+  requireParent(variant !== null, "PageBack", "PageHeader");
+  const destination =
+    typeof children === "string" ? children : "a página anterior";
+  const accessibleLabel = ariaLabel ?? `Voltar para ${destination}`;
+  const link = (
+    <Button asChild variant="ghost" size={variant === "bar" ? "icon-sm" : "sm"}>
+      <a
+        data-slot="page-back"
+        aria-label={accessibleLabel}
+        className={className}
+        {...props}
+      >
+        <ArrowLeft aria-hidden="true" />
+        {variant === "default" && <span>{children}</span>}
+      </a>
+    </Button>
+  );
+
+  return variant === "bar" ? (
+    <TooltipProvider delayDuration={200}>
+      <Tooltip>
+        <TooltipTrigger asChild>{link}</TooltipTrigger>
+        <TooltipContent>{accessibleLabel}</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  ) : (
+    link
+  );
 }
 
 export function PageBody({
   className,
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
-  requireParent(useContext(PageContext), "PageBody", "Page");
-  return <div data-slot="page-body" className={className} {...props} />;
+  const page = useContext(PageContext);
+  const integralState = useContext(PageIntegralStateContext);
+  requireParent(page !== null, "PageBody", "Page");
+  return (
+    <div
+      data-slot="page-body"
+      className={cn(
+        page?.headerVariant === "bar" &&
+          "mx-auto w-full max-w-7xl flex-1 px-8 py-8",
+        page?.headerVariant === "bar" && page.containerClassName,
+        integralState && "flex min-h-0 flex-1 flex-col",
+        className,
+      )}
+      {...props}
+    />
+  );
 }