@softize/opus 12.10.0 → 12.11.0

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

@@ -0,0 +1,115 @@
+/**
+ * <PageState /> — estado integral da área de conteúdo de uma Page.
+ *
+ * Page continua responsável somente pelo esqueleto. Na forma curta, PageState pode ser escrito
+ * como filho direto porque Page cria PageBody; na composição explícita, ele fica dentro de
+ * PageBody. Estados de uma seção ou coleção continuam em DataState, ActionView e ActionList.
+ */
+
+import type { ReactNode } from "react";
+import { TriangleAlert } from "lucide-react";
+import { cn } from "../../lib/cn.ts";
+import { Alert } from "../primitives/alert.tsx";
+import {
+  Empty,
+  EmptyContent,
+  EmptyDescription,
+  EmptyHeader,
+  EmptyMedia,
+  EmptyTitle,
+} from "../primitives/empty.tsx";
+import { Spinner } from "../primitives/spinner.tsx";
+
+export type PageStateStatus = "loading" | "error" | "empty" | "ready";
+
+export interface PageStateProps {
+  status: PageStateStatus;
+  /** Título específico do estado. Defaults seguros existem para loading, error e empty. */
+  title?: ReactNode;
+  /** Contexto e próximo passo, quando acrescentarem informação ao título. */
+  description?: ReactNode;
+  /** Ícone decorativo. Error usa TriangleAlert por default; empty não inventa um ícone. */
+  icon?: ReactNode;
+  /** Ação aplicável ao estado, como tentar novamente, escolher ou criar. */
+  action?: ReactNode;
+  /** Conteúdo normal da página, renderizado somente em ready. */
+  children?: ReactNode;
+  className?: string;
+}
+
+export function PageState({
+  status,
+  title,
+  description,
+  icon,
+  action,
+  children,
+  className,
+}: PageStateProps): React.ReactElement {
+  if (status === "ready") return <>{children}</>;
+
+  if (status === "loading") {
+    return (
+      <div
+        data-slot="page-state"
+        data-status="loading"
+        role="status"
+        aria-live="polite"
+        className={cn(
+          "flex min-h-64 flex-col items-center justify-center gap-3 text-center",
+          className,
+        )}
+      >
+        <Spinner aria-hidden="true" aria-label={undefined} role="presentation" />
+        <div className="max-w-md space-y-1">
+          <p data-slot="page-state-title" className="text-sm font-medium">
+            {title ?? "Carregando…"}
+          </p>
+          {description !== undefined && (
+            <p
+              data-slot="page-state-description"
+              className="text-sm text-muted-foreground"
+            >
+              {description}
+            </p>
+          )}
+        </div>
+      </div>
+    );
+  }
+
+  if (status === "error") {
+    return (
+      <div
+        data-slot="page-state"
+        data-status="error"
+        className={cn("flex min-h-64 items-center justify-center", className)}
+      >
+        <Alert
+          className="max-w-xl"
+          context="danger"
+          icon={icon ?? <TriangleAlert />}
+          title={title ?? "Não foi possível carregar esta página"}
+          description={description}
+        >
+          {action}
+        </Alert>
+      </div>
+    );
+  }
+
+  return (
+    <div data-slot="page-state" data-status="empty" className={className}>
+      <Empty className="min-h-64">
+        <EmptyHeader>
+          {icon !== undefined && <EmptyMedia variant="icon">{icon}</EmptyMedia>}
+          <EmptyTitle>{title ?? "Nada por aqui"}</EmptyTitle>
+          {description !== undefined && (
+            <EmptyDescription>{description}</EmptyDescription>
+          )}
+        </EmptyHeader>
+        {action !== undefined && <EmptyContent>{action}</EmptyContent>}
+      </Empty>
+    </div>
+  );
+}

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

@@ -1,52 +1,242 @@
 /**
- * <Page /> — o esqueleto de página do back-office.
+ * <Page /> — esqueleto composto de página do back-office.
  *
- * Padroniza o que toda página repete: <main> + container centralizado com teto de 72rem
- * (`max-w-6xl`; quem precisar de outra largura sobrescreve por `className`) + header
- * (título, descrição e ações à direita, alinhadas ao fim desse bloco — em geral o botão
- * de criar). O conteúdo é
- * children, sem nada imposto. Presentacional (sem contrato) de propósito: uma página
- * agrega N fontes; o que é action-driven mora dentro (ActionList, listas query-backed).
+ * A forma curta cobre o caso comum; a forma explícita expõe a mesma anatomia para composições
+ * especiais. Ambas preservam o container centralizado com teto de 80rem.
  */
 
-import type { ReactNode } from 'react'
-import { cn } from '../../lib/cn.ts'
-import { ContentHeaderFrame } from './content-header.tsx'
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useContext,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { cn } from "../../lib/cn.ts";
 
-export interface PageProps {
-  title: string
-  /** Total de itens ao lado do título (o estilo do Maestro: mono, esmaecido). */
-  count?: number
-  /** Linha de contexto sob o título. */
-  description?: ReactNode
-  /** Ações à direita do header, alinhadas ao fim do bloco de contexto. */
-  actions?: ReactNode
-  /** Classes do container. Default: centralizado com `max-w-6xl` (72rem). */
-  className?: string
-  children: ReactNode
+const PageContext = createContext(false);
+const PageHeaderContext = createContext(false);
+
+function requireParent(
+  inside: boolean,
+  component: string,
+  parent: string,
+): void {
+  if (!inside) throw new Error(`${component} deve estar dentro de ${parent}.`);
+}
+
+interface PageBaseProps extends Omit<
+  HTMLAttributes<HTMLElement>,
+  "children" | "title"
+> {
+  /** Classes do container. Default: centralizado com `max-w-7xl` (80rem). */
+  className?: string;
+}
+
+interface PageShorthandProps extends PageBaseProps {
+  title: ReactNode;
+  /** Total de itens ao lado do título. */
+  count?: number;
+  description?: ReactNode;
+  actions?: ReactNode;
+  children: ReactNode;
+}
+
+interface PageComposedProps extends PageBaseProps {
+  title?: never;
+  count?: never;
+  description?: never;
+  actions?: never;
+  children: ReactNode;
 }
 
-export function Page({ title, count, description, actions, className, children }: PageProps): React.ReactElement {
+export type PageProps = PageShorthandProps | PageComposedProps;
+
+export function Page({
+  title,
+  count,
+  description,
+  actions,
+  className,
+  children,
+  ...props
+}: PageProps): ReactElement {
+  const shorthand = title !== undefined;
+  const nodes = Children.toArray(children);
+  if (
+    shorthand &&
+    nodes.some((node) => isValidElement(node) && node.type === PageHeader)
+  ) {
+    throw new Error(
+      "Page não permite misturar propriedades de shorthand com PageHeader explícito.",
+    );
+  }
+  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 ||
+      headers.length + bodies.length !== nodes.length
+    ) {
+      throw new Error(
+        "Page explícito exige exatamente um PageHeader e um PageBody como filhos diretos.",
+      );
+    }
+  }
+
+  return (
+    <PageContext.Provider value>
+      <main data-slot="page" className="min-w-0 flex-1" {...props}>
+        <div className={cn("mx-auto max-w-7xl px-8 py-8", className)}>
+          {shorthand ? (
+            <>
+              <PageHeader>
+                <PageTitle>{title}</PageTitle>
+                {count !== undefined && <PageMeta>{count}</PageMeta>}
+                {description !== undefined && (
+                  <PageDescription>{description}</PageDescription>
+                )}
+                {actions !== undefined && <PageActions>{actions}</PageActions>}
+              </PageHeader>
+              <PageBody>{children}</PageBody>
+            </>
+          ) : (
+            children
+          )}
+        </div>
+      </main>
+    </PageContext.Provider>
+  );
+}
+
+export function PageHeader({
+  className,
+  children,
+  ...props
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  requireParent(useContext(PageContext), "PageHeader", "Page");
+  const nodes = Children.toArray(children);
+  const titles = nodes.filter(
+    (node) => isValidElement(node) && node.type === PageTitle,
+  );
+  const metas = nodes.filter(
+    (node) => isValidElement(node) && node.type === PageMeta,
+  );
+  const descriptions = nodes.filter(
+    (node) => isValidElement(node) && node.type === PageDescription,
+  );
+  const actionSlots = nodes.filter(
+    (node) => isValidElement(node) && node.type === PageActions,
+  );
+  const recognized =
+    titles.length + metas.length + descriptions.length + actionSlots.length;
+  if (
+    titles.length !== 1 ||
+    metas.length > 1 ||
+    descriptions.length > 1 ||
+    actionSlots.length > 1 ||
+    recognized !== nodes.length
+  ) {
+    throw new Error(
+      "PageHeader exige um PageTitle e aceita no máximo um PageDescription, PageMeta e PageActions como filhos diretos.",
+    );
+  }
+
   return (
-    <main data-slot="page" className="min-w-0 flex-1">
-      <div className={cn('mx-auto max-w-6xl px-8 py-8', className)}>
-        <div data-slot="page-header" className="mb-6">
-          <ContentHeaderFrame
-            title={title}
-            meta={
-              count === undefined ? undefined : (
-                <span className="font-mono text-base text-muted-foreground/60">{count}</span>
-              )
-            }
-            description={description}
-            actions={actions}
-            level={1}
-            variant="page"
-            slots={{ heading: 'page-heading', actions: 'page-actions' }}
-          />
+    <PageHeaderContext.Provider value>
+      <div
+        data-slot="page-header"
+        className={cn(
+          "mb-6",
+          actionSlots.length > 0 &&
+            "flex flex-col items-start gap-4 sm:flex-row sm:items-end sm:justify-between",
+          className,
+        )}
+        {...props}
+      >
+        <div data-slot="page-heading" className="min-w-0">
+          <div className="flex items-baseline gap-2">
+            {titles}
+            {metas}
+          </div>
+          {descriptions}
         </div>
-        {children}
+        {actionSlots}
       </div>
-    </main>
-  )
+    </PageHeaderContext.Provider>
+  );
+}
+
+export function PageTitle({
+  className,
+  ...props
+}: HTMLAttributes<HTMLHeadingElement>): ReactElement {
+  requireParent(useContext(PageHeaderContext), "PageTitle", "PageHeader");
+  return (
+    <h1
+      data-slot="page-title"
+      className={cn("text-2xl font-semibold tracking-tight", className)}
+      {...props}
+    />
+  );
+}
+
+export function PageDescription({
+  className,
+  ...props
+}: HTMLAttributes<HTMLParagraphElement>): ReactElement {
+  requireParent(useContext(PageHeaderContext), "PageDescription", "PageHeader");
+  return (
+    <p
+      data-slot="page-description"
+      className={cn("mt-1 truncate text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+export function PageMeta({
+  className,
+  ...props
+}: HTMLAttributes<HTMLSpanElement>): ReactElement {
+  requireParent(useContext(PageHeaderContext), "PageMeta", "PageHeader");
+  return (
+    <span
+      data-slot="page-meta"
+      className={cn("font-mono text-base text-muted-foreground/60", className)}
+      {...props}
+    />
+  );
+}
+
+export function PageActions({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  requireParent(useContext(PageHeaderContext), "PageActions", "PageHeader");
+  return (
+    <div
+      data-slot="page-actions"
+      className={cn(
+        "flex w-full shrink-0 items-center gap-4 sm:w-auto",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export function PageBody({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  requireParent(useContext(PageContext), "PageBody", "Page");
+  return <div data-slot="page-body" className={className} {...props} />;
 }