npm - @softize/opus - Versions diffs - 16.1.0 → 17.1.0 - Mend

@softize/opus 16.1.0 → 17.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/CHANGELOG.md +41 -0
package/bin/lib/check.mjs +9 -13
package/bin/lib/copy.mjs +29 -4
package/docs/adr/0005-structural-surfaces-share-an-explicit-anatomy.md +6 -3
package/docs/adr/0009-page-title-does-not-carry-a-counter.md +5 -2
package/docs/adr/0011-page-shell-coordinates-persistent-page-chrome.md +12 -14
package/docs/adr/0012-modal-header-only-names-the-surface.md +8 -4
package/docs/adr/0013-presentation-is-a-portable-action-oriented-artifact.md +20 -11
package/docs/adr/0014-structural-headers-do-not-carry-description.md +35 -0
package/docs/adr/0015-action-size-follows-interaction-density.md +64 -0
package/package.json +2 -2
package/registry/skills/build-opus-ui/references/evaluations.md +1 -1
package/registry/skills/build-opus-ui/references/ui-patterns.md +19 -18
package/registry/templates/app/package.json +1 -1
package/src/core/presentation.ts +142 -13
package/src/ui/components/patterns/form.tsx +35 -10
package/src/ui/components/patterns/page.tsx +93 -48
package/src/ui/components/patterns/presentation.tsx +489 -329
package/src/ui/components/patterns/surface-header.tsx +4 -3
package/src/ui/components/patterns/trigger.tsx +8 -1
package/src/ui/components/patterns/view.tsx +2 -2
package/src/ui/components/primitives/command.tsx +82 -42
package/src/ui/components/primitives/dialog.tsx +180 -97
package/src/ui/components/primitives/drawer.tsx +63 -22
package/src/ui/docs/content/button.md +8 -2
package/src/ui/docs/content/command.md +3 -1
package/src/ui/docs/content/content.md +1 -1
package/src/ui/docs/content/dialog.md +9 -9
package/src/ui/docs/content/drawer.md +4 -4
package/src/ui/docs/content/page.md +16 -31
package/src/ui/docs/content/presentation.md +73 -80
package/src/ui/meta.ts +2 -2
package/src/ui/react.tsx +1 -8

package/src/core/presentation.ts CHANGED Viewed

@@ -94,6 +94,8 @@ const presentationBodySchema = z
   .object({
     action: z.string().min(1),
     input: z.record(presentationBindingSchema).default({}),
+    onSuccess: z.array(presentationEffectSchema).default([]),
+    submitLabel: z.string().min(1).optional(),
     fields: z.array(presentationFieldSchema).min(1).optional(),
     open: z
       .object({
@@ -153,13 +155,14 @@ type DefinedPresentationOpen<Open> = Open extends object
       }
   : never;
 type DefinedPresentationBody<Body extends PresentationDefinitionInput["body"]> =
-  Omit<Body, "input" | "open"> &
-    Omit<PresentationDefinition["body"], "input" | "open"> & {
+  Omit<Body, "input" | "open" | "onSuccess"> &
+    Omit<PresentationDefinition["body"], "input" | "open" | "onSuccess"> & {
       input: DefaultedProperty<
         Body,
         "input",
         PresentationDefinition["body"]["input"]
       >;
+      onSuccess: DefinedPresentationEffects<Body, "onSuccess">;
     } & ("open" extends keyof Body
       ? undefined extends Body["open"]
         ? { open?: DefinedPresentationOpen<Exclude<Body["open"], undefined>> }
@@ -417,6 +420,12 @@ export function validatePresentations(
         `A action simple “${bodyAction.name}” não pode ocupar o body.`,
       );
     } else {
+      validateActionBindings(
+        presentation.body.input,
+        bodyAction,
+        `${presentation.id}.body.input`,
+        problems,
+      );
       if (
         bodyAction.kind === "view" &&
         presentation.body.fields === undefined
@@ -434,20 +443,34 @@ export function validatePresentations(
       if (bodyAction.kind !== "list" && presentation.body.open !== undefined) {
         problems.push(`Open só pode ser declarado para uma action list.`);
       }
+      if (
+        bodyAction.kind !== "form" &&
+        presentation.body.submitLabel !== undefined
+      ) {
+        problems.push(`SubmitLabel só pode ser declarado para uma action form.`);
+      }
     }
     for (const command of presentation.actions) {
       const action = actions[command.action];
       if (action === undefined) {
         problems.push(`A action “${command.action}” não está disponível.`);
-      } else if (action.kind === "simple" && command.target !== undefined) {
-        problems.push(
-          `A action simple “${command.action}” executa diretamente e não aceita target.`,
-        );
-      } else if (action.kind !== "simple" && command.target === undefined) {
-        problems.push(
-          `A action ${action.kind} “${command.action}” precisa abrir outra Presentation.`,
+      } else {
+        validateActionBindings(
+          command.input,
+          action,
+          `${presentation.id}.actions.${command.action}.input`,
+          problems,
         );
+        if (action.kind === "simple" && command.target !== undefined) {
+          problems.push(
+            `A action simple “${command.action}” executa diretamente e não aceita target.`,
+          );
+        } else if (action.kind !== "simple" && command.target === undefined) {
+          problems.push(
+            `A action ${action.kind} “${command.action}” precisa abrir outra Presentation.`,
+          );
+        }
       }
     }
   }
@@ -458,13 +481,57 @@ export function validatePresentations(
       problems.push(
         `A lista “${presentation.id}” abre a Presentation inexistente “${open.presentation}”.`,
       );
+    } else if (open !== undefined) {
+      const target = byId.get(open.presentation);
+      const action =
+        target === undefined ? undefined : actions[target.body.action];
+      if (action !== undefined) {
+        validateActionBindings(
+          open.input,
+          action,
+          `${presentation.id}.body.open.input`,
+          problems,
+        );
+      }
+    }
+    for (const effect of presentation.body.onSuccess) {
+      if (effect.effect !== "navigate") continue;
+      const target = byId.get(effect.presentation);
+      if (target === undefined) {
+        problems.push(
+          `O body de “${presentation.id}” navega para a Presentation inexistente “${effect.presentation}”.`,
+        );
+        continue;
+      }
+      const action = actions[target.body.action];
+      if (action !== undefined) {
+        validateActionBindings(
+          effect.input,
+          action,
+          `${presentation.id}.body.onSuccess.navigate.input`,
+          problems,
+        );
+      }
     }
     for (const command of presentation.actions) {
       for (const effect of command.onSuccess) {
-        if (effect.effect === "navigate" && !byId.has(effect.presentation)) {
-          problems.push(
-            `A action “${command.action}” navega para a Presentation inexistente “${effect.presentation}”.`,
-          );
+        if (effect.effect === "navigate") {
+          const target = byId.get(effect.presentation);
+          if (target === undefined) {
+            problems.push(
+              `A action “${command.action}” navega para a Presentation inexistente “${effect.presentation}”.`,
+            );
+          } else {
+            const action = actions[target.body.action];
+            if (action !== undefined) {
+              validateActionBindings(
+                effect.input,
+                action,
+                `${presentation.id}.actions.${command.action}.onSuccess.navigate.input`,
+                problems,
+              );
+            }
+          }
         }
       }
       if (command.target === undefined) continue;
@@ -485,6 +552,68 @@ export function validatePresentations(
   return parsed;
 }
+function unwrapObjectSchema(schema: unknown): z.ZodObject<any> | null {
+  let current = schema;
+  const visited = new Set<unknown>();
+  while (current !== null && typeof current === "object" && !visited.has(current)) {
+    visited.add(current);
+    if (current instanceof z.ZodObject) return current;
+    const definition = (current as { _def?: Record<string, unknown> })._def;
+    current = definition?.innerType ?? definition?.schema ?? null;
+  }
+  return null;
+}
+function validateActionBindings(
+  bindings: Readonly<Record<string, PresentationBinding>>,
+  action: ActionContract,
+  path: string,
+  problems: string[],
+): void {
+  const schema = unwrapObjectSchema(action.input);
+  if (schema === null) return;
+  const shape = schema.shape as Record<string, z.ZodTypeAny>;
+  for (const key of Object.keys(bindings)) {
+    const field = shape[key];
+    if (field === undefined) {
+      problems.push(
+        `O binding “${path}.${key}” não existe no input da action “${action.name}”.`,
+      );
+      continue;
+    }
+    const binding = bindings[key];
+    if (binding?.source === "fixed" && !field.safeParse(binding.value).success) {
+      problems.push(
+        `O valor fixo de “${path}.${key}” é incompatível com o input da action “${action.name}”.`,
+      );
+    }
+    if (
+      binding?.source === "now" &&
+      !field.safeParse(new Date(0).toISOString()).success
+    ) {
+      problems.push(
+        `O binding temporal “${path}.${key}” é incompatível com o input da action “${action.name}”.`,
+      );
+    }
+  }
+  for (const [key, field] of Object.entries(shape)) {
+    const suppliedByForm =
+      action.kind === "form" &&
+      key in ((action.fields ?? {}) as Record<string, unknown>);
+    if (
+      bindings[key] === undefined &&
+      !suppliedByForm &&
+      !field.safeParse(undefined).success
+    ) {
+      problems.push(
+        `O input obrigatório “${key}” da action “${action.name}” não possui binding em “${path}”.`,
+      );
+    }
+  }
+}
 export function resolvePresentationBinding(
   binding: PresentationBinding,
   context: PresentationBindingContext,

package/src/ui/components/patterns/form.tsx CHANGED Viewed

@@ -17,7 +17,7 @@
  * inline; toast em sucesso/erro. Emite `data-action="<action.name>"` na raiz (selector E2E).
  */
-import { createContext, useContext, useEffect } from 'react'
+import { createContext, useContext, useEffect, useId } from 'react'
 import type { UseFormReturn } from 'react-hook-form'
 import {
   getLogicalType,
@@ -616,6 +616,10 @@ export interface ActionFormProps<TInput extends Record<string, unknown>, TData>
   submitLabel?: string
   cancelLabel?: string
   onCancel?: () => void
+  /** Bloqueia campos e ações sem desmontar o formulário. */
+  disabled?: boolean
+  /** Informa carregamento para superfícies que coordenam ações como um grupo. */
+  onLoadingChange?: (loading: boolean) => void
   /** Opções por campo pra select/multiselect carregados em runtime (ex.: papéis/skills
    *  por id). Sobrepõe as opções estáticas inferidas do z.enum. Chave = nome do campo. */
   fieldOptions?: Record<string, SelectOption[]>
@@ -640,12 +644,15 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
   submitLabel = 'Salvar',
   cancelLabel = 'Cancelar',
   onCancel,
+  disabled = false,
+  onLoadingChange,
   fieldOptions,
   className,
   body,
   footer,
   children,
 }: ActionFormProps<TInput, TData>) {
+  const formId = useId()
   const { form, submit, isLoading, error, isSuccess } = useFormAction<TInput, TData>(action, {
     ...(defaultValues !== undefined ? { defaultValues: defaultValues as never } : {}),
     onSuccess: (data) => {
@@ -657,6 +664,11 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
     },
   })
+  useEffect(() => {
+    onLoadingChange?.(isLoading)
+    return () => onLoadingChange?.(false)
+  }, [isLoading, onLoadingChange])
   const shape = (objectSchemaShape(action.input) ?? {}) as Record<string, ZodTypeAny | undefined>
   const fields = action.fields as Record<string, FieldSpec>
@@ -692,26 +704,39 @@ export function ActionForm<TInput extends Record<string, unknown>, TData>({
         fieldOptions,
       }}
     >
-      <form onSubmit={submit} className={cn('flex flex-col', className)} data-action={action.name}>
+      <form id={formId} onSubmit={submit} className={cn('flex flex-col', className)} data-action={action.name}>
         {wrapBody(
-          <FieldGroup>
-            {children !== undefined
-              ? children
-              : Object.keys(fields).map((name) => <ActionFormField key={name} name={name} />)}
-            {errorBanner}
-          </FieldGroup>,
+          <fieldset disabled={disabled || isLoading} className="contents">
+            <FieldGroup>
+              {children !== undefined
+                ? children
+                : Object.keys(fields).map((name) => <ActionFormField key={name} name={name} />)}
+              {errorBanner}
+            </FieldGroup>
+          </fieldset>,
         )}
         {wrapFooter(
           <>
             {onCancel !== undefined && (
-              <Button type="button" variant="ghost" onClick={onCancel}>
+              <Button
+                type="button"
+                form={formId}
+                variant="ghost"
+                disabled={disabled || isLoading}
+                onClick={onCancel}
+              >
                 {cancelLabel}
               </Button>
             )}
             {/* Gated por dirty: só habilita com mudança real (igual aos forms antigos).
                 busy = a submissão em andamento (spinner + disable vêm do Button). */}
-            <Button type="submit" busy={isLoading} disabled={!form.formState.isDirty}>
+            <Button
+              type="submit"
+              form={formId}
+              busy={isLoading}
+              disabled={disabled || !form.formState.isDirty}
+            >
               {submitLabel}
             </Button>
           </>,

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

@@ -33,6 +33,8 @@ type PageHeadingRegion = "header" | "intro";
 const PageHeaderContext = createContext<PageHeadingRegion | null>(null);
 const PageIntegralStateContext = createContext(false);
 const PageActionsTargetContext = createContext<HTMLElement | null>(null);
+const PageNavigationTargetContext = createContext<HTMLElement | null>(null);
+const PageTitleTargetContext = createContext<HTMLElement | null>(null);
 const PageShellContext = createContext(false);
 const pageBarClassName =
   "flex h-12 shrink-0 items-center border-b border-border bg-background text-foreground";
@@ -44,13 +46,34 @@ export function useInsidePageShell(): boolean {
 }
 function PageShellNavigationSlot({
+  targetRef,
   className,
   ...props
-}: HTMLAttributes<HTMLDivElement>): ReactElement {
+}: HTMLAttributes<HTMLDivElement> & {
+  targetRef?: (target: HTMLDivElement | null) => void;
+}): ReactElement {
   return (
     <div
+      ref={targetRef}
       data-slot="page-shell-navigation"
-      className={cn("min-w-0 flex-1 overflow-hidden", className)}
+      className={cn("min-w-0 shrink-0 overflow-hidden", className)}
+      {...props}
+    />
+  );
+}
+function PageShellTitleSlot({
+  targetRef,
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement> & {
+  targetRef?: (target: HTMLDivElement | null) => void;
+}): ReactElement {
+  return (
+    <div
+      ref={targetRef}
+      data-slot="page-shell-title"
+      className={cn("min-w-0 flex-1", className)}
       {...props}
     />
   );
@@ -99,6 +122,9 @@ export function PageShell({
   const [actionsTarget, setActionsTarget] = useState<HTMLDivElement | null>(
     null,
   );
+  const [navigationTarget, setNavigationTarget] =
+    useState<HTMLDivElement | null>(null);
+  const [titleTarget, setTitleTarget] = useState<HTMLDivElement | null>(null);
   return (
     <div
@@ -114,8 +140,7 @@ export function PageShell({
         slot="page"
         slots={{
           leading: PageShellNavigationSlot,
-          title: PageTitle,
-          description: PageDescription,
+          title: PageShellTitleSlot,
           actions: PageShellActionsSlot,
         }}
         leadingPlacement="inline"
@@ -124,17 +149,24 @@ export function PageShell({
         className={pageBarClassName}
         data-variant="bar"
       >
-        <PageShellNavigationSlot>{navigation}</PageShellNavigationSlot>
+        <PageShellNavigationSlot targetRef={setNavigationTarget}>
+          {navigation}
+        </PageShellNavigationSlot>
+        <PageShellTitleSlot targetRef={setTitleTarget} />
         <PageShellActionsSlot targetRef={setActionsTarget}>
           {actions}
         </PageShellActionsSlot>
       </SurfaceHeader>
       <PageShellContext.Provider value>
-        <PageActionsTarget target={actionsTarget}>
-          <div data-slot="page-shell-content" className="min-h-0 flex-1">
-            {children}
-          </div>
-        </PageActionsTarget>
+        <PageNavigationTargetContext.Provider value={navigationTarget}>
+          <PageTitleTargetContext.Provider value={titleTarget}>
+            <PageActionsTarget target={actionsTarget}>
+              <div data-slot="page-shell-content" className="min-h-0 flex-1">
+                {children}
+              </div>
+            </PageActionsTarget>
+          </PageTitleTargetContext.Provider>
+        </PageNavigationTargetContext.Provider>
       </PageShellContext.Provider>
     </div>
   );
@@ -172,7 +204,6 @@ interface PageBaseProps extends Omit<
 interface PageShorthandProps extends PageBaseProps {
   title: ReactNode;
-  description?: ReactNode;
   actions?: ReactNode;
   children: ReactNode;
 }
@@ -188,7 +219,6 @@ export type PageProps = PageShorthandProps | PageComposedProps;
 export function Page({
   title,
-  description,
   actions,
   className,
   children,
@@ -232,6 +262,7 @@ export function Page({
   }
   if (!shorthand) {
     const validIntroComposition =
+      !insideShell &&
       intros.length === 1 &&
       headers.length === 0 &&
       bodies.length === 1 &&
@@ -244,10 +275,22 @@ export function Page({
       bodies.length === 1 &&
       footers.length <= 1 &&
       headers.length + bodies.length + footers.length === nodes.length;
-    if (!validIntroComposition && !validStandaloneComposition) {
+    const validShellComposition =
+      insideShell &&
+      headers.length === 1 &&
+      bodies.length === 1 &&
+      intros.length <= 1 &&
+      footers.length <= 1 &&
+      headers.length + intros.length + bodies.length + footers.length ===
+        nodes.length;
+    if (
+      !validIntroComposition &&
+      !validStandaloneComposition &&
+      !validShellComposition
+    ) {
       throw new Error(
         insideShell
-          ? "Page explícito dentro de PageShell exige um PageIntro, um PageBody e no máximo um PageFooter como filhos diretos."
+          ? "Page explícito dentro de PageShell exige um PageHeader, um PageBody e aceita no máximo um PageIntro e um PageFooter como filhos diretos."
           : "Page explícito exige um PageHeader ou PageIntro, um PageBody e no máximo um PageFooter como filhos diretos.",
       );
     }
@@ -255,22 +298,16 @@ export function Page({
   const content =
     shorthand && insideShell ? (
       <>
-        <PageIntro>
+        <PageHeader>
           <PageTitle>{title}</PageTitle>
-          {description !== undefined && (
-            <PageDescription>{description}</PageDescription>
-          )}
           {actions !== undefined && <PageActions>{actions}</PageActions>}
-        </PageIntro>
+        </PageHeader>
         <PageBody>{children}</PageBody>
       </>
     ) : shorthand ? (
       <>
         <PageHeader>
           <PageTitle>{title}</PageTitle>
-          {description !== undefined && (
-            <PageDescription>{description}</PageDescription>
-          )}
           {actions !== undefined && <PageActions>{actions}</PageActions>}
         </PageHeader>
         <PageBody>{children}</PageBody>
@@ -337,12 +374,9 @@ export function PageIntro({
         name="PageIntro"
         slot="page-intro"
         slots={{
-          leading: [PageBack, PageNavigation],
           title: PageTitle,
-          description: PageDescription,
           actions: PageActions,
         }}
-        leadingPlacement="above"
         className={className}
         {...props}
       >
@@ -361,9 +395,17 @@ export function PageHeader({
   ...props
 }: PageHeaderProps): ReactElement {
   const page = useContext(PageContext);
+  const insideShell = useContext(PageShellContext);
   const integralState = useContext(PageIntegralStateContext);
   requireParent(page !== null, "PageHeader", "Page");
-  if (integralState) return <></>;
+  if (integralState && !insideShell) return <></>;
+  if (insideShell) {
+    return (
+      <PageHeaderContext.Provider value="header">
+        {children}
+      </PageHeaderContext.Provider>
+    );
+  }
   return (
     <PageHeaderContext.Provider value="header">
       <SurfaceHeader
@@ -372,7 +414,6 @@ export function PageHeader({
         slots={{
           leading: [PageBack, PageNavigation],
           title: PageTitle,
-          description: PageDescription,
           actions: PageActions,
         }}
         leadingPlacement="inline"
@@ -390,8 +431,10 @@ export function PageTitle({
   ...props
 }: HTMLAttributes<HTMLHeadingElement>): ReactElement {
   const variant = useContext(PageHeaderContext);
+  const insideShell = useContext(PageShellContext);
+  const target = useContext(PageTitleTargetContext);
   requireParent(variant !== null, "PageTitle", "PageHeader ou PageIntro");
-  return (
+  const title = (
     <h1
       data-slot="page-title"
       className={cn(
@@ -403,21 +446,10 @@ export function PageTitle({
       {...props}
     />
   );
-}
-export function PageDescription({
-  className,
-  ...props
-}: HTMLAttributes<HTMLParagraphElement>): ReactElement {
-  const variant = useContext(PageHeaderContext);
-  requireParent(variant !== null, "PageDescription", "PageHeader ou PageIntro");
-  return (
-    <p
-      data-slot="page-description"
-      className={cn(surfaceHeaderClasses.page.description, className)}
-      {...props}
-    />
-  );
+  if (insideShell && variant === "header") {
+    return target === null ? <></> : createPortal(title, target);
+  }
+  return title;
 }
 export function PageActions({
@@ -460,18 +492,25 @@ export function PageNavigation({
   className,
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
+  const variant = useContext(PageHeaderContext);
+  const insideShell = useContext(PageShellContext);
+  const target = useContext(PageNavigationTargetContext);
   requireParent(
-    useContext(PageHeaderContext) !== null,
+    variant !== null,
     "PageNavigation",
-    "PageHeader ou PageIntro",
+    "PageHeader",
   );
-  return (
+  const navigation = (
     <div
       data-slot="page-navigation-content"
       className={cn("min-w-0", className)}
       {...props}
     />
   );
+  if (insideShell && variant === "header") {
+    return target === null ? <></> : createPortal(navigation, target);
+  }
+  return navigation;
 }
 export function PageBack({
@@ -481,11 +520,13 @@ export function PageBack({
   ...props
 }: PageBackProps): ReactElement {
   const variant = useContext(PageHeaderContext);
-  requireParent(variant !== null, "PageBack", "PageHeader ou PageIntro");
+  const insideShell = useContext(PageShellContext);
+  const target = useContext(PageNavigationTargetContext);
+  requireParent(variant !== null, "PageBack", "PageHeader");
   const destination =
     typeof children === "string" ? children : "a página anterior";
   const accessibleLabel = ariaLabel ?? `Voltar para ${destination}`;
-  return (
+  const back = (
     <Button asChild variant="ghost" size="icon-sm">
       <a
         data-slot="page-back"
@@ -499,6 +540,10 @@ export function PageBack({
       </a>
     </Button>
   );
+  if (insideShell && variant === "header") {
+    return target === null ? <></> : createPortal(back, target);
+  }
+  return back;
 }
 export function PageBody({