@softize/opus 18.3.0 → 18.5.0

package/src/executions/stream.ts

@@ -0,0 +1,123 @@
+import type { ExecutionChanges, ExecutionNotice } from './index.ts'
+
+export interface ExecutionStreamOptions {
+  changes: ExecutionChanges
+  /** null: sessão e direito de acompanhar; notice: também autorizar a execução exata. */
+  authorize: (notice: ExecutionNotice | null) => Promise<boolean>
+  signal?: AbortSignal
+  heartbeatMs?: number
+  /** Renova a conexão e a autorização mesmo se não houver atividade. */
+  maxDurationMs?: number
+  onError: (error: unknown) => void
+}
+
+/**
+ * SSE sem dados de negócio. Ler a fotografia por actions autorizadas após cada invalidate.
+ * Assinar antes da primeira invalidação evita a lacuna entre fotografia e assinatura.
+ */
+export async function executionStream(options: ExecutionStreamOptions): Promise<Response> {
+  const heartbeatMs = options.heartbeatMs ?? 15_000
+  const maxDurationMs = options.maxDurationMs ?? 300_000
+  if (!Number.isFinite(heartbeatMs) || heartbeatMs < 100 || !Number.isFinite(maxDurationMs) || maxDurationMs < heartbeatMs) {
+    throw new Error('Invalid execution stream timing')
+  }
+  if (options.signal?.aborted) return new Response(null, { status: 204 })
+  if (!await options.authorize(null)) return new Response(null, { status: 403 })
+  if (options.signal?.aborted) return new Response(null, { status: 204 })
+
+  const encoder = new TextEncoder()
+  let close = () => {}
+  let cancelled = false
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      let closed = false
+      let busy = false
+      let pendingReset = false
+      let pinging = false
+      let sessionCheck: Promise<boolean> | undefined
+      const pending = new Map<string, ExecutionNotice>()
+      let unsubscribe: (() => void) | undefined
+      let heartbeat: ReturnType<typeof setInterval> | undefined
+      let deadline: ReturnType<typeof setTimeout> | undefined
+      close = () => {
+        if (closed) return
+        closed = true
+        pending.clear()
+        unsubscribe?.()
+        clearInterval(heartbeat)
+        clearTimeout(deadline)
+        options.signal?.removeEventListener('abort', close)
+        if (!cancelled) controller.close()
+      }
+      const send = (message: string) => {
+        if (closed) return
+        // Uma conexão lenta reconecta e refaz a fotografia; nunca acumula progresso sem limite.
+        if ((controller.desiredSize ?? 0) <= 0) { close(); return }
+        controller.enqueue(encoder.encode(message))
+      }
+      const invalidate = () => send('event: invalidate\ndata: {}\n\n')
+      const report = (error: unknown) => { try { options.onError(error) } catch { /* não vazar erro no SSE */ } }
+
+      function sessionAllowed(): Promise<boolean> {
+        sessionCheck ??= Promise.resolve().then(() => options.authorize(null)).finally(() => { sessionCheck = undefined })
+        return sessionCheck
+      }
+
+      // A fila de autorizações por recurso não pode segurar a renovação da sessão ou o heartbeat.
+      async function ping(): Promise<void> {
+        if (pinging || closed) return
+        pinging = true
+        try {
+          if (!await sessionAllowed()) close()
+          else send(': heartbeat\n\n')
+        } catch (error) { report(error); close() }
+        finally { pinging = false }
+      }
+
+      async function flush(): Promise<void> {
+        if (busy || closed) return
+        busy = true
+        try {
+          while (!closed && (pending.size > 0 || pendingReset)) {
+            const notices = [...pending.values()]
+            pending.clear()
+            let allowed = pendingReset
+            pendingReset = false
+            if (!await sessionAllowed()) { close(); break }
+            for (const notice of notices) {
+              if (closed) break
+              if (await options.authorize(notice)) allowed = true
+            }
+            if (allowed && !closed) {
+              if (!await sessionAllowed()) { close(); break }
+              invalidate()
+            }
+          }
+        } catch (error) { report(error); close() }
+        finally { busy = false }
+      }
+
+      const dispose = options.changes.subscribe((notice) => {
+        if (closed) return
+        if (notice === null) pendingReset = true
+        else pending.set(notice.id, notice)
+        if (pending.size > 128) { close(); return }
+        void flush()
+      }, close)
+      unsubscribe = dispose
+      if (closed) { dispose(); return }
+      options.signal?.addEventListener('abort', close, { once: true })
+      if (options.signal?.aborted) { close(); return }
+      heartbeat = setInterval(() => { void ping() }, heartbeatMs)
+      deadline = setTimeout(close, maxDurationMs)
+      pendingReset = true
+      void flush()
+    },
+    cancel() { cancelled = true; close() },
+  }, { highWaterMark: 16 })
+  return new Response(stream, { headers: {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache, no-store',
+    'X-Accel-Buffering': 'no',
+  } })
+}

package/src/ui/components/patterns/content-header.tsx

@@ -4,6 +4,7 @@ import {
   isValidElement,
   useContext,
   useId,
+  type ComponentProps,
   type HTMLAttributes,
   type ReactElement,
   type ReactNode,
@@ -18,8 +19,13 @@ import {
 
 export type ContentHeaderLevel = 1 | 2 | 3 | 4 | 5 | 6;
 export type ContentHeaderVariant = SurfaceHeaderVariant;
+export type ContentElement = "section" | "fieldset";
+export type ContentFrameVariant = "default" | "legend";
 
 interface ContentContextValue {
+  element: ContentElement;
+  frameVariant: ContentFrameVariant;
+  framed: boolean;
   level: ContentHeaderLevel;
   titleId: string;
   variant: ContentHeaderVariant;
@@ -38,17 +44,37 @@ function requiredContext<T>(
   return value;
 }
 
-interface ContentBaseProps extends Omit<
-  HTMLAttributes<HTMLElement>,
-  "children" | "title"
-> {
-  /** Nível semântico do heading, independente de seu destaque visual. */
-  level?: ContentHeaderLevel;
+interface ContentSharedProps {
+  /** Aplica a moldura estrutural da região sem transferi-la ao conteúdo interno. */
+  framed?: boolean;
   /** Hierarquia visual: `section` (default) ou `page`, a mesma de PageHeader. */
   variant?: ContentHeaderVariant;
 }
 
-interface ContentShorthandProps extends ContentBaseProps {
+interface ContentSectionBaseProps
+  extends
+    ContentSharedProps,
+    Omit<ComponentProps<"section">, "children" | "title"> {
+  /** Elemento semântico da região. */
+  as?: "section";
+  frameVariant?: "default";
+  /** Nível semântico do heading, independente de seu destaque visual. */
+  level?: ContentHeaderLevel;
+}
+
+interface ContentFieldsetBaseProps
+  extends
+    ContentSharedProps,
+    Omit<ComponentProps<"fieldset">, "children" | "title"> {
+  /** Usa a semântica nativa de grupo de campos; o título vira `legend`. */
+  as: "fieldset";
+  /** Tratamento visual da moldura: contínua (default) ou recortada pela legenda. */
+  frameVariant?: ContentFrameVariant;
+  level?: never;
+  variant?: "section";
+}
+
+interface ContentSectionShorthandProps extends ContentSectionBaseProps {
   title: ReactNode;
   /** Total de itens ao lado do título da seção. A página não carrega contador (ADR 0009). */
   count?: number;
@@ -57,7 +83,15 @@ interface ContentShorthandProps extends ContentBaseProps {
   children: ReactNode;
 }
 
-interface ContentComposedProps extends ContentBaseProps {
+interface ContentFieldsetShorthandProps extends ContentFieldsetBaseProps {
+  title: ReactNode;
+  count?: never;
+  description?: never;
+  actions?: never;
+  children: ReactNode;
+}
+
+interface ContentComposedProps {
   title?: never;
   count?: never;
   description?: never;
@@ -65,22 +99,36 @@ interface ContentComposedProps extends ContentBaseProps {
   children: ReactNode;
 }
 
-export type ContentProps = ContentShorthandProps | ContentComposedProps;
+export type ContentProps =
+  | ContentSectionShorthandProps
+  | ContentFieldsetShorthandProps
+  | ((ContentSectionBaseProps | ContentFieldsetBaseProps) &
+      ContentComposedProps);
 
 /** Região de conteúdo nomeada. A forma curta e a explícita produzem a mesma anatomia. */
 export function Content({
+  as = "section",
   title,
   count,
   description,
   actions,
   level = 2,
   variant = "section",
+  framed = false,
+  frameVariant = "default",
   children,
   className,
   ...props
 }: ContentProps): ReactElement {
   const titleId = useId();
-  const context = { level, titleId, variant };
+  const context = {
+    element: as,
+    frameVariant,
+    framed,
+    level: level as ContentHeaderLevel,
+    titleId,
+    variant,
+  };
   const shorthand = title !== undefined;
   const nodes = Children.toArray(children);
 
@@ -110,34 +158,64 @@ export function Content({
     }
   }
 
+  const anatomy = shorthand ? (
+    <>
+      <ContentHeader>
+        <ContentTitle>{title}</ContentTitle>
+        {count !== undefined && <ContentMeta>{count}</ContentMeta>}
+        {description !== undefined && (
+          <ContentDescription>{description}</ContentDescription>
+        )}
+        {actions !== undefined && <ContentActions>{actions}</ContentActions>}
+      </ContentHeader>
+      <ContentBody>{children}</ContentBody>
+    </>
+  ) : (
+    children
+  );
+  const ariaLabelledBy =
+    props["aria-label"] === undefined ? titleId : undefined;
+
   return (
     <ContentContext.Provider value={context}>
-      <section
-        data-slot="content"
-        aria-labelledby={
-          props["aria-label"] === undefined ? titleId : undefined
-        }
-        className={cn("space-y-3", className)}
-        {...props}
-      >
-        {shorthand ? (
-          <>
-            <ContentHeader>
-              <ContentTitle>{title}</ContentTitle>
-              {count !== undefined && <ContentMeta>{count}</ContentMeta>}
-              {description !== undefined && (
-                <ContentDescription>{description}</ContentDescription>
-              )}
-              {actions !== undefined && (
-                <ContentActions>{actions}</ContentActions>
-              )}
-            </ContentHeader>
-            <ContentBody>{children}</ContentBody>
-          </>
-        ) : (
-          children
-        )}
-      </section>
+      {as === "fieldset" ? (
+        <fieldset
+          data-slot="content"
+          data-as="fieldset"
+          data-framed={framed}
+          data-frame-variant={frameVariant}
+          aria-labelledby={ariaLabelledBy}
+          className={cn(
+            !framed && "space-y-3",
+            framed &&
+              frameVariant === "default" &&
+              "rounded-lg border border-border p-4",
+            framed &&
+              frameVariant === "legend" &&
+              "space-y-3 rounded-lg border border-border px-4 pb-4",
+            className,
+          )}
+          {...(props as ComponentProps<"fieldset">)}
+        >
+          {anatomy}
+        </fieldset>
+      ) : (
+        <section
+          data-slot="content"
+          data-as="section"
+          data-framed={framed}
+          data-frame-variant={frameVariant}
+          aria-labelledby={ariaLabelledBy}
+          className={cn(
+            "space-y-3",
+            framed && "rounded-lg border border-border p-4",
+            className,
+          )}
+          {...(props as ComponentProps<"section">)}
+        >
+          {anatomy}
+        </section>
+      )}
     </ContentContext.Provider>
   );
 }
@@ -158,6 +236,37 @@ export function ContentHeader({
     "ContentHeader",
     "Content",
   );
+  if (content.element === "fieldset") {
+    const nodes = Children.toArray(children);
+    if (
+      nodes.length !== 1 ||
+      !isValidElement(nodes[0]) ||
+      nodes[0].type !== ContentTitle
+    ) {
+      throw new Error(
+        "ContentHeader de fieldset exige somente um ContentTitle; contador, descrição e ações ficam fora da legenda.",
+      );
+    }
+    return (
+      <ContentHeaderContext.Provider value={content}>
+        <legend
+          data-slot="content-header"
+          className={cn(
+            content.framed &&
+              content.frameVariant === "default" &&
+              "float-left w-full",
+            content.framed &&
+              content.frameVariant === "legend" &&
+              "-ml-2 w-auto px-2",
+            className,
+          )}
+          {...props}
+        >
+          {children}
+        </legend>
+      </ContentHeaderContext.Provider>
+    );
+  }
   return (
     <ContentHeaderContext.Provider value={content}>
       <SurfaceHeader
@@ -195,14 +304,15 @@ export function ContentTitle({
   className,
   id,
   ...props
-}: HTMLAttributes<HTMLHeadingElement>): ReactElement {
+}: HTMLAttributes<HTMLElement>): ReactElement {
   const context = requiredContext(
     useContext(ContentHeaderContext),
     "ContentTitle",
     "ContentHeader",
   );
-  const Heading = headingTags[context.level];
-  usePageHeadingPresence(context.level === 1);
+  const Heading =
+    context.element === "fieldset" ? "span" : headingTags[context.level];
+  usePageHeadingPresence(context.element !== "fieldset" && context.level === 1);
   return (
     <Heading
       id={id ?? context.titleId}
@@ -279,6 +389,23 @@ export function ContentBody({
   className,
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
-  requiredContext(useContext(ContentContext), "ContentBody", "Content");
-  return <div data-slot="content-body" className={className} {...props} />;
+  const content = requiredContext(
+    useContext(ContentContext),
+    "ContentBody",
+    "Content",
+  );
+  return (
+    <div
+      data-slot="content-body"
+      className={cn(
+        content.element === "fieldset" && "space-y-3",
+        content.element === "fieldset" &&
+          content.framed &&
+          content.frameVariant === "default" &&
+          "clear-left pt-3",
+        className,
+      )}
+      {...props}
+    />
+  );
 }

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

@@ -111,8 +111,13 @@ import {
   InputGroupInput,
 } from "../primitives/input-group.tsx";
 import { Separator } from "../primitives/separator.tsx";
-import { Label } from "../primitives/label.tsx";
-import { FieldGroup, FieldLegend, FieldSet } from "../primitives/field.tsx";
+import {
+  Field,
+  FieldGroup,
+  FieldLabel,
+  type FieldSetVariant,
+} from "../primitives/field.tsx";
+import { Content } from "./content-header.tsx";
 import { Search } from "lucide-react";
 import { Select, type SelectOption } from "../primitives/select.tsx";
 import {
@@ -307,6 +312,8 @@ export interface AdvancedFiltersLayout {
   columns?: 1 | 2 | 3;
   /** Ícone de cada seção, indexado pelo mesmo rótulo declarado nos filtros. */
   sectionIcons?: Record<string, ReactNode>;
+  /** Tratamento visual de cada seção. `framed` integra a legenda à moldura do conjunto. */
+  sectionVariant?: FieldSetVariant;
 }
 
 /** Uma view alternativa da MESMA listagem (board, galeria, lista, calendário…). A
@@ -1105,6 +1112,7 @@ function AdvancedFiltersDialog({
   filterDefaults,
   filterIcons,
   sectionIcons,
+  sectionVariant = "plain",
   cascade,
   columns = 1,
 }: {
@@ -1117,6 +1125,7 @@ function AdvancedFiltersDialog({
   filterDefaults?: Record<string, string> | undefined;
   filterIcons?: Record<string, ReactNode> | undefined;
   sectionIcons?: Record<string, ReactNode> | undefined;
+  sectionVariant?: FieldSetVariant | undefined;
   columns?: 1 | 2 | 3;
   /** A cascata do `depends` do pai — mudar um campo limpa os dependentes no draft. */
   cascade: (
@@ -1153,8 +1162,10 @@ function AdvancedFiltersDialog({
   }[columns];
 
   const field = ([name, spec]: [string, FilterSpec]): React.ReactElement => (
-    <div key={name} className="space-y-2">
-      <Label htmlFor={`filter-${name}`}>{text(spec.label, name)}</Label>
+    <Field key={name}>
+      <FieldLabel htmlFor={`filter-${name}`}>
+        {text(spec.label, name)}
+      </FieldLabel>
       <FilterField
         name={name}
         spec={spec}
@@ -1166,7 +1177,7 @@ function AdvancedFiltersDialog({
         defaultValue={filterDefaults?.[name]}
         icon={filterIcons?.[name]}
       />
-    </div>
+    </Field>
   );
 
   const clear = (): void => {
@@ -1194,14 +1205,32 @@ function AdvancedFiltersDialog({
         <DialogBody className="space-y-4">
           {sectioned ? (
             sections.map(([section, entries]) => (
-              <FieldSet key={section} className="gap-0">
-                <FieldLegend variant="section" icon={sectionIcons?.[section]}>
-                  {section}
-                </FieldLegend>
+              <Content
+                key={section}
+                as="fieldset"
+                framed={sectionVariant === "framed"}
+                frameVariant={
+                  sectionVariant === "framed" ? "legend" : "default"
+                }
+                title={
+                  <span className="flex items-center gap-2">
+                    {sectionIcons?.[section] !== undefined && (
+                      <span
+                        data-slot="content-title-icon"
+                        aria-hidden="true"
+                        className="inline-flex shrink-0 items-center justify-center text-muted-foreground [&_svg]:size-4"
+                      >
+                        {sectionIcons[section]}
+                      </span>
+                    )}
+                    {section}
+                  </span>
+                }
+              >
                 <FieldGroup className={cn("grid gap-4", gridColumns)}>
                   {entries.map(field)}
                 </FieldGroup>
-              </FieldSet>
+              </Content>
             ))
           ) : (
             <FieldGroup className={cn("grid gap-4", gridColumns)}>
@@ -1597,6 +1626,7 @@ export function ActionFilterBar({
             filterIcons={filterIcons}
             columns={advancedFilters?.columns}
             sectionIcons={advancedFilters?.sectionIcons}
+            sectionVariant={advancedFilters?.sectionVariant}
           />
         )}
       </div>
@@ -2111,7 +2141,7 @@ export function ActionList<TInput, TItem>({
   } else {
     content = (
       <Table
-        variant="framed"
+        variant="plain"
         className={tableStateActive ? "h-full" : undefined}
         containerClassName={
           tableFillsAvailableHeight
@@ -2122,7 +2152,7 @@ export function ActionList<TInput, TItem>({
         <TableHeader
           className={
             tableFillsAvailableHeight
-              ? "sticky top-0 z-10 bg-muted/30 dark:bg-input/30"
+              ? "sticky top-0 z-10 bg-background shadow-[inset_0_-0.0625rem_0_var(--border)] [&_tr]:border-b-0"
               : undefined
           }
         >
@@ -2270,7 +2300,7 @@ export function ActionList<TInput, TItem>({
     total !== undefined && !isError ? (
       <div
         data-slot="action-list-footer"
-        className="grid grid-cols-[1fr_auto_1fr] items-center gap-3 px-3 py-1.5 text-xs text-muted-foreground"
+        className="grid grid-cols-[1fr_auto_1fr] items-center gap-3 border-t border-border px-3 py-1.5 text-xs text-muted-foreground"
       >
         <span>
           Página {state.page} de {pages}

package/src/ui/components/primitives/detail.tsx

@@ -131,7 +131,7 @@ function DetailField({
       <dt
         data-slot="detail-field-label"
         className={cn(
-          'flex items-center gap-2.5 text-xs leading-snug font-medium text-muted-foreground group-data-[orientation=horizontal]/detail-group:text-sm',
+          'flex items-center gap-2.5 text-sm leading-snug font-medium text-muted-foreground',
           splitHorizontalField && 'bg-muted/30 p-3 dark:bg-input/30',
         )}
       >

package/src/ui/components/primitives/empty.tsx

@@ -1,6 +1,7 @@
 import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from '../../lib/cn.ts'
+import { iconTileVariants } from './icon-tile.tsx'
 
 function Empty({ className, ...props }: React.ComponentProps<"div">) {
   return (
@@ -34,7 +35,7 @@ const emptyMediaVariants = cva(
     variants: {
       variant: {
         default: "bg-transparent",
-        icon: "flex size-10 shrink-0 items-center justify-center rounded-lg bg-muted text-foreground [&_svg:not([class*='size-'])]:size-6",
+        icon: iconTileVariants({ size: "lg", variant: "subtle" }),
       },
     },
     defaultVariants: {

package/src/ui/components/primitives/field.tsx

@@ -1,21 +1,41 @@
-import { useMemo } from "react"
+import { createContext, useContext, useMemo } from "react"
 import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from '../../lib/cn.ts'
 import { Label } from './label.tsx'
 import { Separator } from './separator.tsx'
 
-function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
+export type FieldSetVariant = "plain" | "framed"
+
+export interface FieldSetProps extends React.ComponentProps<"fieldset"> {
+  /** `framed` envolve o conjunto com a moldura canônica e integra a legenda à borda. */
+  variant?: FieldSetVariant
+}
+
+const FieldSetVariantContext = createContext<FieldSetVariant>("plain")
+
+function FieldSet({
+  className,
+  children,
+  variant = "plain",
+  ...props
+}: FieldSetProps) {
   return (
-    <fieldset
-      data-slot="field-set"
-      className={cn(
-        "flex flex-col gap-6",
-        "has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3",
-        className
-      )}
-      {...props}
-    />
+    <FieldSetVariantContext.Provider value={variant}>
+      <fieldset
+        data-slot="field-set"
+        data-variant={variant}
+        className={cn(
+          "flex flex-col gap-6",
+          "has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3",
+          variant === "framed" && "rounded-lg border border-border px-4 pb-4",
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </fieldset>
+    </FieldSetVariantContext.Provider>
   )
 }
 
@@ -29,6 +49,8 @@ function FieldLegend({
   variant?: "legend" | "label" | "section"
   icon?: React.ReactNode
 }) {
+  const fieldSetVariant = useContext(FieldSetVariantContext)
+
   return (
     <legend
       data-slot="field-legend"
@@ -38,7 +60,10 @@ function FieldLegend({
         icon !== undefined && "flex items-center gap-2",
         "data-[variant=legend]:text-base",
         "data-[variant=label]:text-sm",
-        "data-[variant=section]:w-full data-[variant=section]:border-b data-[variant=section]:border-border/70 data-[variant=section]:pb-2 data-[variant=section]:text-sm data-[variant=section]:font-semibold",
+        fieldSetVariant === "plain" &&
+          "data-[variant=section]:w-full data-[variant=section]:border-b data-[variant=section]:border-border/70 data-[variant=section]:pb-2",
+        "data-[variant=section]:text-sm data-[variant=section]:font-semibold",
+        fieldSetVariant === "framed" && "-ml-2 w-auto px-2",
         className
       )}
       {...props}
@@ -47,10 +72,7 @@ function FieldLegend({
         <span
           data-slot="field-legend-icon"
           aria-hidden="true"
-          className={cn(
-            "inline-flex shrink-0 items-center justify-center text-muted-foreground [&_svg]:size-4",
-            variant === "section" && "size-7 rounded-md bg-muted",
-          )}
+          className="inline-flex shrink-0 items-center justify-center text-muted-foreground [&_svg]:size-4"
         >
           {icon}
         </span>