@softize/opus 29.0.0 → 31.0.0

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

@@ -0,0 +1,494 @@
+import type { ActionContract } from "../../../core/contracts.ts";
+import { EmptyValue } from "../primitives/empty-value.tsx";
+import {
+  matchesPresentationConditions,
+  meetsPresentationRequirement,
+} from "../../../core/presentation.ts";
+import type { SelectOption } from "../primitives/select.tsx";
+import type { FormContract, ListContract } from "../../../core/contracts.ts";
+import { Fragment, type ReactNode } from "react";
+import type {
+  PresentationBindingContext,
+  PresentationListSection,
+  PresentationSectionsBody,
+} from "../../../core/presentation.ts";
+import type { ListDataSource } from "../../drivers/react.tsx";
+import {
+  Item,
+  ItemActions,
+  ItemBody,
+  ItemDescription,
+  ItemGroup,
+  ItemHeader,
+  ItemSeparator,
+  ItemTitle,
+} from "../primitives/item.tsx";
+import { Surface, SurfaceBody } from "./surface.tsx";
+import { FillBoundary, useFillLeaf } from "./fill-region.ts";
+import {
+  ActionList,
+  type ActionListProps,
+  type ListActionLike,
+} from "./list.tsx";
+
+export interface PresentationListAdapter {
+  requires?: ActionContract<unknown, unknown>["requires"];
+  render: (section: PresentationListSection) => ReactNode;
+}
+
+export interface PresentationCellsAdapter {
+  action: string;
+  cells: Record<string, (item: Record<string, unknown>) => ReactNode>;
+}
+
+/** Vincula células ao contrato que fornece os itens, sem serializar funções. */
+export function bindPresentationCells<TInput, TItem>(
+  action: ListContract<TInput, TItem>,
+  cells: NonNullable<ActionListProps<TInput, TItem>["cells"]>,
+): PresentationCellsAdapter {
+  return {
+    action: action.name,
+    cells: Object.fromEntries(
+      Object.entries(cells).map(([key, render]) => [
+        key,
+        (item: Record<string, unknown>) => render(item as TItem),
+      ]),
+    ),
+  };
+}
+
+export interface PresentationRowContentAdapter {
+  action: string;
+  render: (item: Record<string, unknown>) => ReactNode;
+}
+
+/** Conteúdo específico de uma linha; comandos comuns continuam na declaração. */
+export function bindPresentationRowContent<TInput, TItem>(
+  action: ListContract<TInput, TItem>,
+  render: (item: TItem) => ReactNode,
+): PresentationRowContentAdapter {
+  return { action: action.name, render: (item) => render(item as TItem) };
+}
+
+export interface PresentationCollectionControls<TItem> {
+  onOpen: (item: TItem) => void;
+  canOpen: (item: TItem) => boolean;
+  actions: (item: TItem) => ReactNode;
+  refetch: () => Promise<void>;
+}
+
+export interface PresentationCollectionAdapter {
+  action: string;
+  render: (
+    items: Record<string, unknown>[],
+    controls: PresentationCollectionControls<Record<string, unknown>>,
+  ) => ReactNode;
+}
+
+/** Apresenta os resultados sem substituir consulta, comandos ou navegação da lista. */
+export function bindPresentationCollection<TInput, TItem>(
+  action: ListContract<TInput, TItem>,
+  render: (
+    items: TItem[],
+    controls: PresentationCollectionControls<TItem>,
+  ) => ReactNode,
+): PresentationCollectionAdapter {
+  return {
+    action: action.name,
+    render: (items, controls) =>
+      render(
+        items as TItem[],
+        controls as unknown as PresentationCollectionControls<TItem>,
+      ),
+  };
+}
+
+export interface PresentationDetailAdapter {
+  action: string;
+  render: (item: Record<string, unknown>, onClose: () => void) => ReactNode;
+}
+
+/** Vincula um detalhe especializado aos itens da lista; a seleção pertence ao renderer. */
+export function bindPresentationDetail<TInput, TItem>(
+  action: ListContract<TInput, TItem>,
+  render: (item: TItem, onClose: () => void) => ReactNode,
+): PresentationDetailAdapter {
+  return {
+    action: action.name,
+    render: (item, onClose) => render(item as TItem, onClose),
+  };
+}
+
+export interface PresentationOptionsAdapter {
+  action: string;
+  format: (item: Record<string, unknown>) => SelectOption;
+}
+
+/** Formata uma opção com dados do contrato, sem alterar a consulta nem o formulário. */
+export function bindPresentationOptions<TInput, TItem>(
+  action: ListContract<TInput, TItem>,
+  format: (item: TItem) => SelectOption,
+): PresentationOptionsAdapter {
+  return { action: action.name, format: (item) => format(item as TItem) };
+}
+
+export interface PresentationFieldProps {
+  name: string;
+  context: PresentationBindingContext;
+}
+
+export interface PresentationFieldAdapter {
+  action: string;
+  field: string;
+  render: (props: PresentationFieldProps) => ReactNode;
+}
+
+/** Vincula um controle ao campo do contrato; ActionForm preserva validação e envio. */
+export function bindPresentationField<
+  TInput extends Record<string, unknown>,
+  TOutput,
+>(
+  action: FormContract<TInput, TOutput>,
+  field: keyof TInput & string,
+  render: (props: PresentationFieldProps) => ReactNode,
+): PresentationFieldAdapter {
+  return { action: action.name, field, render };
+}
+
+export interface PresentationListContentAdapter {
+  action: string;
+  render: (input: Record<string, unknown>) => ReactNode;
+}
+
+/** Conteúdo especializado recebe o mesmo recorte materializado pela lista. */
+export function bindPresentationListContent<TInput, TItem>(
+  action: ListContract<TInput, TItem>,
+  render: (input: Partial<TInput>) => ReactNode,
+): PresentationListContentAdapter {
+  return {
+    action: action.name,
+    render: (input) => render(input as Partial<TInput>),
+  };
+}
+
+export interface PresentationComponentProps<TInput = Record<string, unknown>> {
+  input: TInput;
+  context: PresentationBindingContext;
+  onClose: () => void;
+  footerTarget?: HTMLElement | null;
+  onBusyChange?: (busy: boolean) => void;
+  asideOpen?: boolean;
+  onAsideOpenChange?: (open: boolean) => void;
+}
+export interface PresentationComponentAdapter {
+  action?: string;
+  render: (props: PresentationComponentProps) => ReactNode;
+}
+/** Conteúdo específico vinculado ao contrato; estrutura e navegação pertencem à declaração. */
+export function bindPresentationComponent<TInput, TOutput>(
+  action: ActionContract<TInput, TOutput>,
+  render: (props: PresentationComponentProps<TInput>) => ReactNode,
+): PresentationComponentAdapter {
+  return {
+    action: action.name,
+    render: (props) => render({ ...props, input: props.input as TInput }),
+  };
+}
+
+/** Integração registrada pelo host, sem simular um contrato Opus para serviços externos. */
+export function bindPresentationContent(
+  render: (props: PresentationComponentProps) => ReactNode,
+): PresentationComponentAdapter {
+  return { render };
+}
+export interface PresentationRecordSource {
+  load: (
+    input: Record<string, unknown>,
+    options: { signal: AbortSignal },
+  ) => Promise<Record<string, unknown>>;
+}
+
+export interface PresentationCompositionRuntime {
+  recordSources?: Readonly<Record<string, PresentationRecordSource>>;
+  components?: Readonly<Record<string, PresentationComponentAdapter>>;
+  /** Estado integral temporário; mantém a identidade e a geometria declaradas. */
+  state?: ReactNode;
+  asideOpen?: boolean;
+  presentations?: Readonly<Record<string, ReactNode>>;
+  tabs?: { value: string; onValueChange: (value: string) => void };
+  cells?: Readonly<Record<string, PresentationCellsAdapter>>;
+  details?: Readonly<Record<string, PresentationDetailAdapter>>;
+  listContent?: Readonly<Record<string, PresentationListContentAdapter>>;
+  rowContent?: Readonly<Record<string, PresentationRowContentAdapter>>;
+  collections?: Readonly<Record<string, PresentationCollectionAdapter>>;
+  fields?: Readonly<Record<string, PresentationFieldAdapter>>;
+  options?: Readonly<Record<string, PresentationOptionsAdapter>>;
+  icons?: Readonly<Record<string, ReactNode>>;
+  slots?: Readonly<Record<string, ReactNode>>;
+  lists?: Readonly<Record<string, PresentationListAdapter>>;
+}
+
+/** Mantém a tipagem dos itens no adaptador; a definição só transporta nomes de campos. */
+export function bindPresentationList<TItem>(
+  source: ListDataSource<TItem>,
+  actions: Pick<
+    ActionListProps<Record<string, never>, TItem>,
+    "toolbarActions" | "rowActions"
+  > = {},
+): PresentationListAdapter {
+  return {
+    render: (section) => (
+      <ActionList<Record<string, never>, TItem>
+        source={source}
+        input={{}}
+        layout="flow"
+        title={section.title}
+        item={section.item}
+        emptyMessage={section.emptyMessage}
+        errorMessage={section.errorMessage}
+        toolbarActions={actions.toolbarActions}
+        rowActions={actions.rowActions}
+      />
+    ),
+  };
+}
+
+/** Liga uma coleção de action à seção, preservando tipos e comportamento do contrato. */
+export function bindPresentationActionList<TInput, TItem>(
+  action: ListActionLike,
+  props: Omit<ActionListProps<TInput, TItem>, "action" | "source">,
+): PresentationListAdapter {
+  return {
+    requires: (
+      action as ListActionLike &
+        Pick<ActionContract<unknown, unknown>, "requires">
+    ).requires,
+    render: (section) => (
+      <ActionList<TInput, TItem>
+        {...props}
+        action={action}
+        title={section.title ?? props.title}
+        item={section.item ?? props.item}
+        emptyMessage={section.emptyMessage ?? props.emptyMessage}
+        errorMessage={section.errorMessage ?? props.errorMessage}
+      />
+    ),
+  };
+}
+
+function PresentationContentRegion({ children }: { children: ReactNode }) {
+  const fill = useFillLeaf<HTMLDivElement>("fill");
+  return (
+    <div
+      ref={fill.ref}
+      data-slot="presentation-content-region"
+      className="flex min-h-0 flex-1 flex-col"
+    >
+      <FillBoundary>{children}</FillBoundary>
+    </div>
+  );
+}
+
+export function PresentationSections({
+  body,
+  runtime,
+  context,
+  can,
+}: {
+  can?: (permission: string) => boolean;
+  context?: PresentationBindingContext;
+  body: PresentationSectionsBody;
+  runtime?: PresentationCompositionRuntime;
+}): ReactNode {
+  const fill = useFillLeaf<HTMLDivElement>(body.aside ? "fill" : "flow");
+  function slot(id: string | undefined): ReactNode {
+    if (id === undefined) return null;
+    if (!Object.hasOwn(runtime?.slots ?? {}, id)) {
+      throw new Error(`Slot “${id}” da Presentation não registrado.`);
+    }
+    return runtime!.slots![id];
+  }
+  // Conferir todas as referências antes de iniciar consultas de qualquer seção.
+  for (const section of body.sections) {
+    slot(section.feedback);
+    if (section.kind === "content") {
+      slot(section.actions);
+      slot(section.content);
+    } else if (section.kind === "items") {
+      slot(section.intro);
+      slot(section.actions);
+      for (const item of section.items) slot(item.content);
+    } else if (
+      !Object.hasOwn(runtime?.lists ?? {}, section.source) ||
+      !runtime?.lists?.[section.source]
+    ) {
+      throw new Error(
+        `Fonte “${section.source}” da Presentation não registrada.`,
+      );
+    }
+  }
+  for (const id of body.overlays ?? []) slot(id);
+  slot(body.aside?.content);
+
+  const notices = (section: PresentationSectionsBody["sections"][number]) =>
+    section.notices
+      ?.filter((notice) =>
+        matchesPresentationConditions(notice.when, context?.record ?? {}),
+      )
+      .map((notice, index) => (
+        <p key={index} className="text-sm">
+          {notice.text}
+        </p>
+      ));
+  const itemContent = (
+    item: Extract<
+      PresentationSectionsBody["sections"][number],
+      { kind: "items" }
+    >["items"][number],
+  ) => {
+    if (!item.value) return slot(item.content);
+    const value = context?.record?.[item.value.field];
+    return (
+      <p className="whitespace-pre-wrap break-words text-sm">
+        {value == null || value === ""
+          ? (item.value.empty ?? <EmptyValue />)
+          : `${String(value)}${item.value.suffix ?? ""}`}
+      </p>
+    );
+  };
+  const main = (
+    <Surface>
+      <SurfaceBody>
+        {body.sections.map((section) =>
+          section.kind === "content" ? (
+            section.title === undefined && section.actions === undefined ? (
+              <Fragment key={section.id}>
+                {section.layout === "fill" ? (
+                  <PresentationContentRegion>
+                    {slot(section.content)}
+                  </PresentationContentRegion>
+                ) : (
+                  slot(section.content)
+                )}
+                {slot(section.feedback)}
+                {notices(section)}
+              </Fragment>
+            ) : (
+              <Surface
+                key={section.id}
+                as="section"
+                title={section.title}
+                level={2}
+                actions={
+                  section.actions === undefined
+                    ? undefined
+                    : slot(section.actions)
+                }
+              >
+                {section.layout === "fill" ? (
+                  <PresentationContentRegion>
+                    {slot(section.content)}
+                  </PresentationContentRegion>
+                ) : (
+                  slot(section.content)
+                )}
+                {slot(section.feedback)}
+                {notices(section)}
+              </Surface>
+            )
+          ) : section.kind === "items" ? (
+            <Surface
+              key={section.id}
+              as="section"
+              title={section.title}
+              level={2}
+              actions={
+                section.actions === undefined
+                  ? undefined
+                  : slot(section.actions)
+              }
+            >
+              {slot(section.intro)}
+              <ItemGroup variant="framed">
+                {section.items.map((item, index) => (
+                  <Fragment key={item.id}>
+                    {index > 0 && <ItemSeparator />}
+                    <Item>
+                      <ItemHeader>
+                        <ItemTitle id={item.labelId}>{item.title}</ItemTitle>
+                        {item.description && (
+                          <ItemDescription>{item.description}</ItemDescription>
+                        )}
+                      </ItemHeader>
+                      {(item.content !== undefined ||
+                        item.value !== undefined) &&
+                        (item.placement === "actions" ? (
+                          <ItemActions>{itemContent(item)}</ItemActions>
+                        ) : (
+                          <ItemBody
+                            className={
+                              item.placement === "below" ? "w-full" : "w-2/3"
+                            }
+                          >
+                            {itemContent(item)}
+                          </ItemBody>
+                        ))}
+                    </Item>
+                  </Fragment>
+                ))}
+              </ItemGroup>
+              {slot(section.feedback)}
+              {notices(section)}
+            </Surface>
+          ) : !meetsPresentationRequirement(
+              runtime!.lists![section.source]!.requires,
+              can,
+            ) ? null : (
+            <Fragment key={section.id}>
+              {runtime!.lists![section.source]!.render(section)}
+              {slot(section.feedback)}
+              {notices(section)}
+            </Fragment>
+          ),
+        )}
+      </SurfaceBody>
+    </Surface>
+  );
+  return (
+    <>
+      {body.aside ? (
+        <div
+          ref={fill.ref}
+          data-slot="presentation-columns"
+          className="grid min-h-0 flex-1 gap-4"
+          style={{
+            gridTemplateColumns:
+              runtime?.asideOpen === false
+                ? "minmax(0, 1fr)"
+                : `minmax(0, 1fr) ${{ narrow: "20rem", default: "24rem", wide: "28rem" }[body.aside.width ?? "default"]}`,
+          }}
+        >
+          <div
+            data-slot="presentation-primary"
+            className="min-h-0 min-w-0 overflow-y-auto overscroll-contain"
+          >
+            <FillBoundary>{main}</FillBoundary>
+          </div>
+          <aside
+            aria-label={body.aside.label}
+            hidden={runtime?.asideOpen === false}
+            data-slot="presentation-aside"
+            className="min-h-0 min-w-0 overflow-hidden"
+          >
+            {slot(body.aside.content)}
+          </aside>
+        </div>
+      ) : (
+        main
+      )}
+      {(body.overlays ?? []).map((id) => (
+        <Fragment key={id}>{slot(id)}</Fragment>
+      ))}
+    </>
+  );
+}