@softize/opus 16.0.0 → 17.0.0

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

@@ -1,20 +1,41 @@
-import { useState, type ReactElement, type ReactNode } from "react";
-import { Braces, X } from "lucide-react";
+import {
+  useCallback,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+import { ArrowLeft, Braces } from "lucide-react";
 import type {
+  PresentationActionRegistry,
+  PresentationBindingContext,
+  PresentationCommand,
   PresentationDiagnostic,
   PresentationDefinition,
   PresentationInvocation,
+  PresentationJsonValue,
   PresentationSurface,
 } from "../../../core/presentation.ts";
-import { createPresentationInspectionSnapshot } from "../../../core/presentation.ts";
+import {
+  applyPresentationEffects,
+  createPresentationInspectionSnapshot,
+  openPresentation,
+  resolvePresentationBindings,
+} from "../../../core/presentation.ts";
+import type {
+  FormContract,
+  ListContract,
+  SimpleContract,
+  ViewContract,
+} from "../../../core/contracts.ts";
 import { cn } from "../../lib/cn.ts";
 import { Button, buttonVariants } from "../primitives/button.tsx";
 import { ButtonGroup } from "../primitives/button-group.tsx";
 import { Copyable } from "../primitives/copyable.tsx";
+import { DetailField, DetailGroup } from "../primitives/detail.tsx";
 import {
   Dialog,
   DialogBody,
-  DialogClose,
   DialogContent,
   DialogFooter,
   DialogHeader,
@@ -23,7 +44,6 @@ import {
 import {
   Drawer,
   DrawerBody,
-  DrawerClose,
   DrawerContent,
   DrawerFooter,
   DrawerHeader,
@@ -35,29 +55,30 @@ import {
   PageBody,
   PageFooter,
   PageHeader,
-  PageIntro,
   PageNavigation,
   PageTitle,
   useInsidePageShell,
 } from "./page.tsx";
+import { ActionForm } from "./form.tsx";
+import { ActionList, type ActionListState } from "./list.tsx";
+import { ActionTrigger } from "./trigger.tsx";
+import { ActionView } from "./view.tsx";
 
-interface PresentationBaseProps {
+interface PresentationFrameProps {
   surface: PresentationSurface;
   title: ReactNode;
   navigation?: ReactNode;
   headerActions?: ReactNode;
   footerActions?: ReactNode;
-  children: ReactNode;
+  children: ReactNode | ((footerTarget: HTMLElement | null) => ReactNode);
+  hasBodyFooter?: boolean;
+  blocked?: boolean;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
   className?: string;
   bodyClassName?: string;
 }
 
-export type PresentationProps = PresentationBaseProps &
-  (
-    | { open?: undefined; onOpenChange?: (open: boolean) => void }
-    | { open: boolean; onOpenChange: (open: boolean) => void }
-  );
-
 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";
 
@@ -75,49 +96,46 @@ function PresentationActions({
   );
 }
 
-function CloseAction({
-  surface,
-}: {
-  surface: "dialog" | "drawer";
-}): ReactElement {
-  const button = (
-    <Button size="icon-sm" variant="ghost" aria-label="Fechar">
-      <X aria-hidden />
-    </Button>
-  );
-  return surface === "dialog" ? (
-    <DialogClose asChild>{button}</DialogClose>
-  ) : (
-    <DrawerClose asChild>{button}</DrawerClose>
-  );
-}
-
 /** A mesma Presentation em Page, Dialog ou Drawer; a superfície não redefine o recurso. */
-export function Presentation({
+function PresentationFrame({
   surface,
   title,
   navigation,
   headerActions,
   footerActions,
   children,
-  open,
+  hasBodyFooter = false,
+  blocked = false,
+  open = true,
   onOpenChange,
   className,
   bodyClassName: bodyClassNameProp,
-}: PresentationProps): ReactElement {
+}: PresentationFrameProps): ReactElement {
   const insidePageShell = useInsidePageShell();
-  const [internalOpen, setInternalOpen] = useState(true);
-  const modalOpen = open ?? internalOpen;
-  function handleOpenChange(nextOpen: boolean): void {
-    if (open === undefined) setInternalOpen(nextOpen);
-    onOpenChange?.(nextOpen);
-  }
+  const [footerTarget, setFooterTarget] = useState<HTMLElement | null>(null);
+  const setFooterNode = useCallback((node: HTMLSpanElement | null) => {
+    setFooterTarget(node);
+  }, []);
+  const hasFooter = hasBodyFooter || footerActions !== undefined;
+  const renderFooterActions = (
+    equal = false,
+  ): ReactElement => (
+    <PresentationActions equal={equal}>
+      {hasBodyFooter ? (
+        <span
+          ref={setFooterNode}
+          className="contents [&>*]:min-w-0 [&>*]:w-full [&>*]:flex-1"
+        />
+      ) : null}
+      {footerActions}
+    </PresentationActions>
+  );
   const body = (
     <div
       data-slot="presentation-body"
       className={cn(bodyClassName, bodyClassNameProp)}
     >
-      {children}
+      {typeof children === "function" ? children(footerTarget) : children}
     </div>
   );
 
@@ -125,7 +143,7 @@ export function Presentation({
     if (insidePageShell) {
       return (
         <Page className={cn("flex min-h-full flex-col", className)}>
-          <PageIntro>
+          <PageHeader>
             {navigation === undefined ? null : (
               <PageNavigation>{navigation}</PageNavigation>
             )}
@@ -135,13 +153,9 @@ export function Presentation({
                 <PresentationActions>{headerActions}</PresentationActions>
               </PageActions>
             )}
-          </PageIntro>
+          </PageHeader>
           <PageBody className="min-h-0 flex-1 overflow-y-auto">{body}</PageBody>
-          {footerActions === undefined ? null : (
-            <PageFooter>
-              <PresentationActions>{footerActions}</PresentationActions>
-            </PageFooter>
-          )}
+          {hasFooter ? <PageFooter>{renderFooterActions()}</PageFooter> : null}
         </Page>
       );
     }
@@ -166,76 +180,408 @@ export function Presentation({
         <PageBody className="min-h-0 flex-1 overflow-y-auto px-8 py-8">
           {body}
         </PageBody>
-        {footerActions === undefined ? null : (
-          <PageFooter>
-            <PresentationActions>{footerActions}</PresentationActions>
-          </PageFooter>
-        )}
+        {hasFooter ? <PageFooter>{renderFooterActions()}</PageFooter> : null}
       </Page>
     );
   }
 
   if (surface === "dialog") {
     return (
-      <Dialog open={modalOpen} onOpenChange={handleOpenChange}>
+      <Dialog
+        open={open}
+        onOpenChange={(nextOpen) => {
+          if (!nextOpen && blocked) return;
+          onOpenChange?.(nextOpen);
+        }}
+      >
         <DialogContent
           className={className}
-          showCloseButton={false}
           aria-describedby={undefined}
+          closeDisabled={blocked}
+          onEscapeKeyDown={(event) => {
+            if (blocked) event.preventDefault();
+          }}
+          onPointerDownOutside={(event) => {
+            if (blocked) event.preventDefault();
+          }}
         >
           <DialogHeader>
-            <div className="flex items-center justify-between gap-4">
-              {navigation}
-              <DialogTitle className="min-w-0 flex-1 truncate">
-                {title}
-              </DialogTitle>
-              <PresentationActions>
-                {headerActions}
-                <CloseAction surface="dialog" />
-              </PresentationActions>
-            </div>
+            {navigation}
+            <DialogTitle className="truncate">{title}</DialogTitle>
+            {headerActions === undefined ? null : (
+              <PresentationActions>{headerActions}</PresentationActions>
+            )}
           </DialogHeader>
-          <DialogBody className={bodyClassNameProp}>{body}</DialogBody>
-          {footerActions === undefined ? null : (
-            <DialogFooter>
-              <PresentationActions equal>{footerActions}</PresentationActions>
-            </DialogFooter>
-          )}
+          <DialogBody>{body}</DialogBody>
+          {hasFooter ? <DialogFooter>{renderFooterActions(true)}</DialogFooter> : null}
         </DialogContent>
       </Dialog>
     );
   }
 
   return (
-    <Drawer open={modalOpen} onOpenChange={handleOpenChange}>
+    <Drawer
+      open={open}
+      onOpenChange={(nextOpen) => {
+        if (!nextOpen && blocked) return;
+        onOpenChange?.(nextOpen);
+      }}
+    >
       <DrawerContent
         className={className}
-        showCloseButton={false}
         aria-describedby={undefined}
+        closeDisabled={blocked}
+        onEscapeKeyDown={(event) => {
+          if (blocked) event.preventDefault();
+        }}
+        onPointerDownOutside={(event) => {
+          if (blocked) event.preventDefault();
+        }}
       >
         <DrawerHeader>
-          <div className="flex items-center justify-between gap-4">
-            {navigation}
-            <DrawerTitle className="min-w-0 flex-1 truncate">
-              {title}
-            </DrawerTitle>
-            <PresentationActions>
-              {headerActions}
-              <CloseAction surface="drawer" />
-            </PresentationActions>
-          </div>
+          {navigation}
+          <DrawerTitle className="truncate">{title}</DrawerTitle>
+          {headerActions === undefined ? null : (
+            <PresentationActions>{headerActions}</PresentationActions>
+          )}
         </DrawerHeader>
-        <DrawerBody className={bodyClassNameProp}>{body}</DrawerBody>
-        {footerActions === undefined ? null : (
-          <DrawerFooter>
-            <PresentationActions equal>{footerActions}</PresentationActions>
-          </DrawerFooter>
-        )}
+        <DrawerBody>{body}</DrawerBody>
+        {hasFooter ? <DrawerFooter>{renderFooterActions(true)}</DrawerFooter> : null}
       </DrawerContent>
     </Drawer>
   );
 }
 
+export interface PresentationProps {
+  /** Definição estática registrada e publicada no manifest. */
+  definition: PresentationDefinition;
+  /** Definições alcançáveis por open, navigate ou back. */
+  definitions: readonly PresentationDefinition[];
+  /** Contratos compartilháveis das actions referenciadas pela definição. */
+  actions: PresentationActionRegistry;
+  /** Estado serializável da exibição atual. */
+  invocation: PresentationInvocation;
+  /** Dados disponíveis para resolver bindings além do input da invocação. */
+  bindingContext?: PresentationBindingContext;
+  /** Recebe navegação, retorno e fechamento produzidos pelo artefato. */
+  onInvocationChange?: (invocation: PresentationInvocation | null) => void;
+  /** Recebe cada invalidação declarada por um efeito refresh. */
+  onRefresh?: (action: string | null) => void;
+  /** Estado de recorte da action list quando a aplicação o sincroniza com a URL. */
+  listState?: ActionListState;
+  onListStateChange?: (state: ActionListState) => void;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  className?: string;
+  bodyClassName?: string;
+}
+
+function actionLabel(action: { name: string; label?: unknown }): string {
+  if (typeof action.label === "string") return action.label;
+  if (
+    action.label !== null &&
+    typeof action.label === "object" &&
+    "default" in action.label &&
+    typeof (action.label as { default?: unknown }).default === "string"
+  ) {
+    return (action.label as { default: string }).default;
+  }
+  return action.name;
+}
+
+function readField(record: unknown, key: string): unknown {
+  if (record === null || typeof record !== "object") return undefined;
+  return (record as Record<string, unknown>)[key];
+}
+
+function PresentationCommandTrigger({
+  command,
+  action,
+  input,
+  disabled,
+  onLoadingChange,
+  onSuccess,
+}: {
+  command: PresentationCommand;
+  action: SimpleContract<Record<string, unknown>, unknown>;
+  input: Record<string, unknown>;
+  disabled: boolean;
+  onLoadingChange: (command: PresentationCommand, loading: boolean) => void;
+  onSuccess: (data: unknown) => void;
+}): ReactElement {
+  const reportLoading = useCallback(
+    (loading: boolean) => onLoadingChange(command, loading),
+    [command, onLoadingChange],
+  );
+  return (
+    <ActionTrigger
+      action={action}
+      input={input}
+      variant="ghost"
+      disabled={disabled}
+      onLoadingChange={reportLoading}
+      onSuccess={onSuccess}
+    />
+  );
+}
+
+/** Renderiza uma definição declarativa delegando cada kind ao pattern Opus correspondente. */
+export function Presentation({
+  definition,
+  definitions,
+  actions,
+  invocation,
+  bindingContext,
+  onInvocationChange,
+  onRefresh,
+  listState,
+  onListStateChange,
+  open = true,
+  onOpenChange,
+  className,
+  bodyClassName: bodyClassNameProp,
+}: PresentationProps): ReactElement {
+  if (definition.id !== invocation.presentationId) {
+    throw new Error(
+      `A invocação “${invocation.presentationId}” não corresponde à Presentation “${definition.id}”.`,
+    );
+  }
+  const [loadingCommands, setLoadingCommands] = useState<
+    ReadonlySet<PresentationCommand>
+  >(() => new Set());
+  const [bodyLoading, setBodyLoading] = useState(false);
+  const context: PresentationBindingContext = {
+    ...bindingContext,
+    route: bindingContext?.route ?? invocation.input,
+  };
+
+  const applyEffects = useCallback(
+    (
+      effects: PresentationDefinition["body"]["onSuccess"],
+      result?: unknown,
+    ): void => {
+      const next = applyPresentationEffects(invocation, effects, {
+        ...context,
+        ...(result !== undefined && result !== null && typeof result === "object"
+          ? { result: result as Record<string, unknown> }
+          : {}),
+      });
+      for (const action of next.refresh) onRefresh?.(action);
+      if (next.invocation !== invocation || next.exit !== undefined) {
+        onInvocationChange?.(next.invocation);
+      }
+    },
+    [context, invocation, onInvocationChange, onRefresh],
+  );
+
+  const reportLoading = useCallback(
+    (command: PresentationCommand, loading: boolean): void => {
+      setLoadingCommands((current) => {
+        const next = new Set(current);
+        if (loading) next.add(command);
+        else next.delete(command);
+        return next;
+      });
+    },
+    [],
+  );
+
+  const hasSurfaceBlock = [...loadingCommands].some(
+    (active) => active.blocking === "surface",
+  );
+  const surfaceBlocked = bodyLoading || hasSurfaceBlock;
+  const isBlocked = (command: PresentationCommand): boolean =>
+    bodyLoading ||
+    [...loadingCommands].some(
+      (active) =>
+        active.blocking === "surface" ||
+        (active.blocking === "group" && active.placement === command.placement),
+    );
+
+  const openTarget = (
+    presentationId: string,
+    surface: PresentationSurface | undefined,
+    bindings: PresentationCommand["input"],
+    targetContext: PresentationBindingContext = context,
+  ): void => {
+    const target = definitions.find((candidate) => candidate.id === presentationId);
+    if (target === undefined) {
+      throw new Error(`Presentation “${presentationId}” não registrada.`);
+    }
+    onInvocationChange?.(
+      openPresentation(invocation, {
+        presentationId: target.id,
+        surface: surface ?? invocation.surface,
+        input: resolvePresentationBindings(bindings, targetContext) as Record<
+          string,
+          PresentationJsonValue
+        >,
+      }),
+    );
+  };
+
+  const renderCommand = (command: PresentationCommand): ReactElement => {
+    const action = actions[command.action];
+    if (action === undefined) {
+      throw new Error(`Action “${command.action}” não registrada.`);
+    }
+    const input = resolvePresentationBindings(command.input, context) as Record<
+      string,
+      unknown
+    >;
+    if (action.kind === "simple") {
+      return (
+        <PresentationCommandTrigger
+          key={`${command.placement}:${command.action}`}
+          command={command}
+          action={action as SimpleContract<Record<string, unknown>, unknown>}
+          input={input}
+          disabled={isBlocked(command)}
+          onLoadingChange={reportLoading}
+          onSuccess={(data) => applyEffects(command.onSuccess, data)}
+        />
+      );
+    }
+    if (command.target === undefined) {
+      throw new Error(
+        `A action “${command.action}” precisa declarar uma Presentation de destino.`,
+      );
+    }
+    return (
+      <Button
+        key={`${command.placement}:${command.action}`}
+        variant="ghost"
+        disabled={isBlocked(command)}
+        onClick={() =>
+          openTarget(
+            command.target!.presentation,
+            command.target!.surface,
+            command.input,
+          )
+        }
+      >
+        {actionLabel(action)}
+      </Button>
+    );
+  };
+
+  const bodyAction = actions[definition.body.action];
+  if (bodyAction === undefined) {
+    throw new Error(`Action “${definition.body.action}” não registrada.`);
+  }
+  const bodyInput = resolvePresentationBindings(
+    definition.body.input,
+    context,
+  ) as Record<string, unknown>;
+  const renderBody = (footerTarget: HTMLElement | null): ReactNode => {
+    if (bodyAction.kind === "form") {
+      return (
+        <ActionForm
+          action={bodyAction as FormContract<Record<string, unknown>, unknown>}
+          defaultValues={bodyInput}
+          submitLabel={definition.body.submitLabel}
+          onSuccess={(data) => applyEffects(definition.body.onSuccess, data)}
+          disabled={hasSurfaceBlock}
+          onLoadingChange={setBodyLoading}
+          footer={(actions) =>
+            footerTarget === null ? null : createPortal(actions, footerTarget)
+          }
+        />
+      );
+    }
+    if (bodyAction.kind === "list") {
+      return (
+      <ActionList<Record<string, unknown>, Record<string, unknown>>
+        action={bodyAction as ListContract<
+          Record<string, unknown>,
+          Record<string, unknown>
+        >}
+        input={bodyInput}
+        state={listState}
+        onStateChange={onListStateChange}
+        {...(definition.body.open === undefined
+          ? {}
+          : {
+              onRowClick: (item: Record<string, unknown>) =>
+                openTarget(
+                  definition.body.open!.presentation,
+                  definition.body.open!.surface,
+                  definition.body.open!.input,
+                  { ...context, item },
+                ),
+            })}
+      />
+      );
+    }
+    if (bodyAction.kind === "view") {
+      const fields = definition.body.fields ?? [];
+      return (
+      <ActionView
+        action={bodyAction as ViewContract<Record<string, unknown>, unknown>}
+        input={bodyInput}
+      >
+        {(data) => (
+          <DetailGroup>
+            {fields.map((field) => (
+              <DetailField
+                key={field.key}
+                label={field.label}
+                value={readField(data, field.key) as ReactNode}
+                empty={field.empty}
+              />
+            ))}
+          </DetailGroup>
+        )}
+      </ActionView>
+      );
+    }
+    throw new Error(`A action simple “${bodyAction.name}” não pode ocupar o body.`);
+  };
+
+  const headerActions = definition.actions
+    .filter((command) => command.placement === "header")
+    .map(renderCommand);
+  const footerActions = definition.actions
+    .filter((command) => command.placement === "footer")
+    .map(renderCommand);
+  const navigation =
+    invocation.stack.length === 0 ? undefined : (
+      <Button
+        size="icon-sm"
+        variant="ghost"
+        disabled={surfaceBlocked}
+        aria-label="Voltar"
+        title="Voltar"
+        onClick={() => applyEffects([{ effect: "back" }])}
+      >
+        <ArrowLeft aria-hidden />
+      </Button>
+    );
+
+  return (
+    <PresentationFrame
+      surface={invocation.surface}
+      title={definition.title}
+      navigation={navigation}
+      headerActions={headerActions.length === 0 ? undefined : headerActions}
+      footerActions={footerActions.length === 0 ? undefined : footerActions}
+      open={open}
+      onOpenChange={(nextOpen) => {
+        onOpenChange?.(nextOpen);
+        if (!nextOpen && invocation.surface !== "page") {
+          applyEffects([{ effect: "close" }]);
+        }
+      }}
+      className={className}
+      bodyClassName={bodyClassNameProp}
+      hasBodyFooter={bodyAction.kind === "form"}
+      blocked={surfaceBlocked}
+    >
+      {renderBody}
+    </PresentationFrame>
+  );
+}
+
 export interface PresentationInspectorProps {
   definition: PresentationDefinition | unknown;
   invocation?: PresentationInvocation | unknown;
@@ -243,11 +589,50 @@ export interface PresentationInspectorProps {
   diagnostics?: readonly PresentationDiagnostic[];
   triggerLabel?: string;
   title?: string;
-  /** Apresenta o gatilho como FAB; o consumidor continua responsável por posicioná-lo. */
-  floating?: boolean;
   className?: string;
 }
 
+function PresentationInspectionDialog({
+  registration,
+  open,
+  onOpenChange,
+  title = "JSON da Presentation",
+}: {
+  registration: Pick<
+    PresentationInspectorProps,
+    "definition" | "invocation" | "resolved" | "diagnostics"
+  >;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  title?: string;
+}): ReactElement {
+  const snapshot = createPresentationInspectionSnapshot(registration);
+  const json = JSON.stringify(snapshot, null, 2) ?? "null";
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="sm:max-w-3xl" aria-describedby={undefined}>
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+        </DialogHeader>
+        <DialogBody>
+          <pre className="max-h-[65vh] overflow-auto rounded-lg bg-muted p-4 text-xs leading-relaxed">
+            {json}
+          </pre>
+        </DialogBody>
+        <DialogFooter>
+          <Copyable
+            value={json}
+            className={buttonVariants({ variant: "outline" })}
+          >
+            Copiar JSON
+          </Copyable>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
 /** Ferramenta de desenvolvimento para conferir e copiar o artefato consumido pelo renderer. */
 export function PresentationInspector({
   definition,
@@ -256,61 +641,29 @@ export function PresentationInspector({
   diagnostics,
   triggerLabel = "Ver JSON da Presentation",
   title = "JSON da Presentation",
-  floating = false,
   className,
 }: PresentationInspectorProps): ReactElement {
   const [open, setOpen] = useState(false);
-  const [json, setJson] = useState<string | null>(null);
-
-  function inspect(): void {
-    const snapshot = createPresentationInspectionSnapshot({
-      definition,
-      invocation,
-      resolved,
-      diagnostics,
-    });
-    setJson(JSON.stringify(snapshot, null, 2) ?? "null");
-    setOpen(true);
-  }
-
-  function handleOpenChange(nextOpen: boolean): void {
-    setOpen(nextOpen);
-    if (!nextOpen) setJson(null);
-  }
 
   return (
     <>
       <Button
-        size={floating ? "icon" : "icon-sm"}
-        variant={floating ? "outline" : "ghost"}
-        data-appearance={floating ? "fab" : "inline"}
-        className={cn(floating && "rounded-full shadow-md", className)}
+        size="icon-sm"
+        variant="ghost"
+        data-appearance="inline"
+        className={className}
         aria-label={triggerLabel}
         title={triggerLabel}
-        onClick={inspect}
+        onClick={() => setOpen(true)}
       >
         <Braces aria-hidden />
       </Button>
-      <Dialog open={open} onOpenChange={handleOpenChange}>
-        <DialogContent className="sm:max-w-3xl" aria-describedby={undefined}>
-          <DialogHeader>
-            <DialogTitle>{title}</DialogTitle>
-          </DialogHeader>
-          <DialogBody>
-            <pre className="max-h-[65vh] overflow-auto rounded-lg bg-muted p-4 text-xs leading-relaxed">
-              {json ?? ""}
-            </pre>
-          </DialogBody>
-          <DialogFooter>
-            <Copyable
-              value={json ?? ""}
-              className={buttonVariants({ variant: "outline" })}
-            >
-              Copiar JSON
-            </Copyable>
-          </DialogFooter>
-        </DialogContent>
-      </Dialog>
+      <PresentationInspectionDialog
+        registration={{ definition, invocation, resolved, diagnostics }}
+        open={open}
+        onOpenChange={setOpen}
+        title={title}
+      />
     </>
   );
 }