@softize/opus 15.0.1 → 15.2.0

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

@@ -1,8 +1,8 @@
 /**
  * <Page /> — esqueleto composto de página do back-office.
  *
- * 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.
+ * A forma curta cobre o caso comum; PageShell coordena a barra persistente quando shell e rota
+ * conhecem partes diferentes. Todas preservam o container centralizado com teto de 80rem.
  */
 
 import {
@@ -39,9 +39,114 @@ interface PageContextValue {
 }
 
 const PageContext = createContext<PageContextValue | null>(null);
-const PageHeaderContext = createContext<PageHeaderVariant | null>(null);
+type PageHeadingRegion = PageHeaderVariant | "intro";
+
+const PageHeaderContext = createContext<PageHeadingRegion | null>(null);
 const PageIntegralStateContext = createContext(false);
 const PageActionsTargetContext = 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";
+const pageBarContentClassName = "w-full py-2";
+
+function PageShellNavigationSlot({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  return (
+    <div
+      data-slot="page-shell-navigation"
+      className={cn("min-w-0 flex-1 overflow-hidden", className)}
+      {...props}
+    />
+  );
+}
+
+function PageShellActionsSlot({
+  targetRef,
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement> & {
+  targetRef: (target: HTMLDivElement | null) => void;
+}): ReactElement {
+  return (
+    <div
+      ref={targetRef}
+      data-slot="page-shell-actions"
+      className={cn("flex shrink-0 items-center gap-2", className)}
+      {...props}
+    />
+  );
+}
+
+export interface PageShellProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "children"
+> {
+  /** Navegação contextual conhecida pelo shell, normalmente um Breadcrumb. */
+  navigation?: ReactNode;
+  /** Ações do shell ou do recurso que antecedem as ações declaradas pela Page. */
+  actions?: ReactNode;
+  /** Uma Page descendente, diretamente ou através da rota ativa. */
+  children: ReactNode;
+  /** Classes do container interno da barra. */
+  headerClassName?: string;
+}
+
+/** Moldura persistente que coordena navegação do shell e ações da Page ativa. */
+export function PageShell({
+  navigation,
+  actions,
+  children,
+  className,
+  headerClassName,
+  ...props
+}: PageShellProps): ReactElement {
+  const [actionsTarget, setActionsTarget] = useState<HTMLDivElement | null>(null);
+
+  return (
+    <div
+      data-slot="page-shell"
+      className={cn(
+        "relative flex h-full min-h-0 min-w-0 flex-1 flex-col",
+        className,
+      )}
+      {...props}
+    >
+      <SurfaceHeader
+        name="PageShell"
+        slot="page"
+        slots={{
+          leading: PageShellNavigationSlot,
+          title: PageTitle,
+          description: PageDescription,
+          actions: PageShellActionsSlot,
+        }}
+        leadingPlacement="inline"
+        titleRequired={false}
+        contentClassName={cn(
+          pageBarContentClassName,
+          "px-3",
+          headerClassName,
+        )}
+        className={pageBarClassName}
+        data-variant="bar"
+      >
+        <PageShellNavigationSlot>{navigation}</PageShellNavigationSlot>
+        <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>
+      </PageShellContext.Provider>
+    </div>
+  );
+}
 
 export function PageActionsTarget({
   target,
@@ -97,6 +202,7 @@ export function Page({
   children,
   ...props
 }: PageProps): ReactElement {
+  const insideShell = useContext(PageShellContext);
   const shorthand = title !== undefined;
   const nodes = Children.toArray(children);
   const headers = nodes.filter(
@@ -105,6 +211,9 @@ export function Page({
   const bodies = nodes.filter(
     (node) => isValidElement(node) && node.type === PageBody,
   );
+  const intros = nodes.filter(
+    (node) => isValidElement(node) && node.type === PageIntro,
+  );
   const activeStateCount = useRef(0);
   const [integralState, setIntegralState] = useState(false);
   const registerIntegralState = useCallback(() => {
@@ -127,13 +236,22 @@ export function Page({
     );
   }
   if (!shorthand) {
-    if (
-      headers.length !== 1 ||
-      bodies.length !== 1 ||
-      headers.length + bodies.length !== nodes.length
-    ) {
+    const validIntroComposition =
+      intros.length === 1 &&
+      headers.length === 0 &&
+      bodies.length === 1 &&
+      intros.length + bodies.length === nodes.length;
+    const validStandaloneComposition =
+      !insideShell &&
+      headers.length === 1 &&
+      intros.length === 0 &&
+      bodies.length === 1 &&
+      headers.length + bodies.length === nodes.length;
+    if (!validIntroComposition && !validStandaloneComposition) {
       throw new Error(
-        "Page explícito exige exatamente um PageHeader e um PageBody como filhos diretos.",
+        insideShell
+          ? "Page explícito dentro de PageShell exige exatamente um PageIntro e um PageBody como filhos diretos."
+          : "Page explícito exige exatamente um PageHeader ou PageIntro e um PageBody como filhos diretos.",
       );
     }
   }
@@ -146,7 +264,18 @@ export function Page({
     containerClassName: className,
   };
 
-  const content = shorthand ? (
+  const content = shorthand && insideShell ? (
+    <>
+      <PageIntro>
+        <PageTitle>{title}</PageTitle>
+        {description !== undefined && (
+          <PageDescription>{description}</PageDescription>
+        )}
+        {actions !== undefined && <PageActions>{actions}</PageActions>}
+      </PageIntro>
+      <PageBody>{children}</PageBody>
+    </>
+  ) : shorthand ? (
     <>
       <PageHeader>
         <PageTitle>{title}</PageTitle>
@@ -169,6 +298,7 @@ export function Page({
             data-slot="page"
             className={cn(
               "min-w-0 flex-1",
+              insideShell && "min-h-full",
               (headerVariant === "bar" || integralState) && "flex flex-col",
               // A barra contém a rolagem (`min-h-0`); o estado integral ocupa a altura
               // disponível (`min-h-full`). Emitir os dois juntos deixava o resultado por
@@ -198,6 +328,47 @@ export function Page({
   );
 }
 
+/** Introdução opcional do conteúdo, separada da navegação persistente do shell. */
+export function PageIntro({
+  className,
+  children,
+  ...props
+}: HTMLAttributes<HTMLDivElement>): ReactElement {
+  const page = useContext(PageContext);
+  const insideShell = useContext(PageShellContext);
+  const integralState = useContext(PageIntegralStateContext);
+  requireParent(page !== null, "PageIntro", "Page");
+  if (integralState) {
+    if (!insideShell) return <></>;
+    const actions = Children.toArray(children).filter(
+      (node) => isValidElement(node) && node.type === PageActions,
+    );
+    return (
+      <PageHeaderContext.Provider value="intro">
+        {actions}
+      </PageHeaderContext.Provider>
+    );
+  }
+
+  return (
+    <PageHeaderContext.Provider value="intro">
+      <SurfaceHeader
+        name="PageIntro"
+        slot="page-intro"
+        slots={{
+          title: PageTitle,
+          description: PageDescription,
+          actions: PageActions,
+        }}
+        className={className}
+        {...props}
+      >
+        {children}
+      </SurfaceHeader>
+    </PageHeaderContext.Provider>
+  );
+}
+
 /** A anatomia é a de `SurfaceHeader`, a mesma de `ContentHeader`; só os slots mudam de nome. */
 export interface PageHeaderProps extends HTMLAttributes<HTMLDivElement> {
   /** `default` fica no container; `bar` cria uma faixa compacta no topo da Page. */
@@ -228,12 +399,15 @@ export function PageHeader({
         leadingPlacement={variant === "bar" ? "inline" : "above"}
         contentClassName={
           variant === "bar"
-            ? cn("mx-auto w-full max-w-7xl px-8 py-2", page?.containerClassName)
+            ? cn(
+                pageBarContentClassName,
+                "mx-auto max-w-7xl px-8",
+                page?.containerClassName,
+              )
             : undefined
         }
         className={cn(
-          variant === "bar" &&
-            "shrink-0 border-b border-border bg-background text-foreground",
+          variant === "bar" && pageBarClassName,
           className,
         )}
         {...props}
@@ -249,14 +423,16 @@ export function PageTitle({
   ...props
 }: HTMLAttributes<HTMLHeadingElement>): ReactElement {
   const variant = useContext(PageHeaderContext);
-  requireParent(variant !== null, "PageTitle", "PageHeader");
+  requireParent(variant !== null, "PageTitle", "PageHeader ou PageIntro");
   return (
     <h1
       data-slot="page-title"
       className={cn(
         variant === "bar"
           ? "truncate text-sm font-semibold"
-          : surfaceHeaderClasses.page.title,
+          : variant === "intro"
+            ? "text-3xl font-semibold tracking-tight"
+            : surfaceHeaderClasses.page.title,
         className,
       )}
       {...props}
@@ -269,7 +445,11 @@ export function PageDescription({
   ...props
 }: HTMLAttributes<HTMLParagraphElement>): ReactElement {
   const variant = useContext(PageHeaderContext);
-  requireParent(variant !== null, "PageDescription", "PageHeader");
+  requireParent(
+    variant !== null,
+    "PageDescription",
+    "PageHeader ou PageIntro",
+  );
   return (
     <p
       data-slot="page-description"
@@ -289,13 +469,14 @@ export function PageActions({
   ...props
 }: HTMLAttributes<HTMLDivElement>): ReactElement {
   const variant = useContext(PageHeaderContext);
-  requireParent(variant !== null, "PageActions", "PageHeader");
+  requireParent(variant !== null, "PageActions", "PageHeader ou PageIntro");
   const target = useContext(PageActionsTargetContext);
+  const insideShell = useContext(PageShellContext);
   const actions = (
     <div
       data-slot="page-actions"
       className={cn(
-        variant === "bar"
+        variant === "bar" || insideShell
           ? "flex shrink-0 items-center gap-2"
           : surfaceHeaderClasses.page.actions,
         className,
@@ -303,6 +484,7 @@ export function PageActions({
       {...props}
     />
   );
+  if (insideShell && target === null) return <></>;
   return target === null ? actions : createPortal(actions, target);
 }
 

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

@@ -57,6 +57,8 @@ export interface SurfaceHeaderProps extends HTMLAttributes<HTMLDivElement> {
   leadingPlacement?: "above" | "inline";
   /** Classes de um container interno quando a moldura precisa ocupar toda a largura. */
   contentClassName?: string;
+  /** Permite uma superfície composta apenas pelas regiões leading/actions. */
+  titleRequired?: boolean;
 }
 
 /** Expande fragments de primeiro nível: o shorthand monta os slots dentro de um `<>`. */
@@ -74,6 +76,7 @@ export function SurfaceHeader({
   slots,
   leadingPlacement = "above",
   contentClassName,
+  titleRequired = true,
   className,
   children,
   ...props
@@ -100,7 +103,7 @@ export function SurfaceHeader({
     actionSlots.length;
 
   if (
-    titles.length !== 1 ||
+    (titleRequired ? titles.length !== 1 : titles.length > 1) ||
     leading.length > 1 ||
     counts.length > 1 ||
     descriptions.length > 1 ||
@@ -130,11 +133,11 @@ export function SurfaceHeader({
     throw new Error(
       distinctLeading.size > 1
         ? `${name} aceita ${[...distinctLeading].map(label).join(" ou ")} na região introdutória, nunca os dois na mesma superfície.`
-        : `${name} exige um ${label(slots.title)} e aceita no máximo um de cada: ${optionalSlots}.`,
+        : `${name} ${titleRequired ? `exige um ${label(slots.title)}` : `aceita no máximo um ${label(slots.title)}`} e aceita no máximo um de cada: ${optionalSlots}.`,
     );
   }
 
-  const heading = (
+  const heading = titles.length + counts.length + descriptions.length > 0 && (
     <div
       data-slot={`${slot}-heading`}
       className={cn("min-w-0", leadingPlacement === "inline" && "flex-1")}
@@ -153,7 +156,13 @@ export function SurfaceHeader({
       {leadingPlacement === "inline" && leading.length > 0 && (
         // `min-w-0` aqui é o que deixa a trilha do PageNavigation ceder e truncar; sem ele o
         // wrapper assume o min-content do breadcrumb e a compressão toda cai sobre o título.
-        <div data-slot={`${slot}-navigation`} className="flex min-w-0 items-center">
+        <div
+          data-slot={`${slot}-navigation`}
+          className={cn(
+            "flex min-w-0 items-center",
+            !heading && "flex-1",
+          )}
+        >
           {leading}
         </div>
       )}

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

@@ -5,6 +5,10 @@ import { Composer } from './composer.tsx'
 import { Markdown } from './markdown.tsx'
 
 export interface ChatMessage {
+  /** Identidade persistida pelo app. Opcional para históricos legados. */
+  id?: string
+  /** Instante ISO-8601 persistido pelo app. Opcional para históricos legados. */
+  createdAt?: string
   role: 'user' | 'assistant'
   content: string
 }
@@ -19,8 +23,10 @@ export interface ChatArtifact {
 /** Item do transcript no modo CONTROLADO (o app é o dono do estado — ex.: sala
  *  server-autoritativa com replay, como o ChatRail do Maestro). */
 export type ChatTranscriptItem =
-  | { role: 'user' | 'assistant' | 'error'; content: string }
-  | { role: 'artifact'; artifact: ChatArtifact }
+  | { id?: string; createdAt?: string; role: 'user' | 'assistant' | 'error'; content: string }
+  | { id?: string; createdAt?: string; role: 'artifact'; artifact: ChatArtifact }
+
+export type ChatTranscriptMessage = Extract<ChatTranscriptItem, { content: string }>
 
 /** Feedback humano do tool em uso (default pt-BR; override por prop). */
 function defaultHumanizeTool(name: string): string {
@@ -85,6 +91,9 @@ export interface ChatProps {
   kickoff?: () => Promise<string> | AsyncIterable<ChatEvent>
   /** Render do evento `artifact` (card, iframe, preview…). Default: link com o título. */
   renderArtifact?: (artifact: ChatArtifact) => React.ReactNode
+  /** Ações contextuais de uma mensagem. O Chat fornece apenas a anatomia; buscar dados
+   *  detalhados, pedir reautorização e decidir o conteúdo pertencem ao app. */
+  renderMessageActions?: (message: ChatTranscriptMessage) => React.ReactNode
   /** Rótulo humano do tool em uso no indicador vivo (modo autogerenciado). */
   humanizeTool?: (name: string, detail?: string) => string
   placeholder?: string
@@ -95,6 +104,14 @@ function isAsyncIterable(value: unknown): value is AsyncIterable<ChatEvent> {
   return typeof value === 'object' && value !== null && Symbol.asyncIterator in value
 }
 
+function transcriptMeta(): { id: string; createdAt: string } {
+  const cryptoApi = globalThis.crypto
+  const id = typeof cryptoApi?.randomUUID === 'function'
+    ? cryptoApi.randomUUID()
+    : `message_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`
+  return { id, createdAt: new Date().toISOString() }
+}
+
 /** Agrupa o transcript em turnos (mensagem do usuário + o que veio em resposta). */
 function groupTurns(items: ChatTranscriptItem[]): Array<{ user: ChatTranscriptItem | null; rest: ChatTranscriptItem[] }> {
   const turns: Array<{ user: ChatTranscriptItem | null; rest: ChatTranscriptItem[] }> = []
@@ -114,6 +131,7 @@ interface ChatTranscriptProps {
   greeting: string | undefined
   empty: React.ReactNode | undefined
   renderArtifact: ChatProps['renderArtifact']
+  renderMessageActions: ChatProps['renderMessageActions']
 }
 
 /**
@@ -128,6 +146,7 @@ const ChatTranscript = React.memo(function ChatTranscript({
   greeting,
   empty,
   renderArtifact,
+  renderMessageActions,
 }: ChatTranscriptProps): React.ReactElement {
   const scrollRef = React.useRef<HTMLDivElement>(null)
   const turns = React.useMemo(() => groupTurns(items), [items])
@@ -164,16 +183,21 @@ const ChatTranscript = React.memo(function ChatTranscript({
         // (o agente narra o que vai fazendo), então andam juntas; quem separa é o gap
         // MAIOR entre turnos. Com o mesmo gap nos dois níveis, um turno de oito falas
         // curtas virava uma parede uniforme, sem começo nem fim visíveis.
-        <div key={ti} className="flex flex-col gap-1">
+        <div key={turn.user?.id ?? turn.rest[0]?.id ?? ti} className="flex flex-col gap-1">
           {turn.user !== null && turn.user.role === 'user' && (
-            <div data-slot="chat-turn-user" className="flex justify-end py-1.5">
+            <div
+              data-slot="chat-turn-user"
+              data-message-id={turn.user.id}
+              data-message-created-at={turn.user.createdAt}
+              className="flex justify-end py-1.5"
+            >
               <UserTurn content={turn.user.content} />
             </div>
           )}
           {turn.rest.map((item, i) => {
             if (item.role === 'artifact') {
               return (
-                <div key={i} data-slot="chat-artifact" className="flex justify-start">
+                <div key={item.id ?? i} data-slot="chat-artifact" data-message-id={item.id} className="flex justify-start">
                   {renderArtifact !== undefined ? (
                     renderArtifact(item.artifact)
                   ) : (
@@ -192,7 +216,9 @@ const ChatTranscript = React.memo(function ChatTranscript({
             if (item.role === 'error') {
               return (
                 <div
-                  key={i}
+                  key={item.id ?? i}
+                  data-slot="chat-error"
+                  data-message-id={item.id}
                   className="max-w-[88%] self-start rounded-xl border border-context-danger-border bg-context-danger-subtle px-3.5 py-2.5 text-sm text-context-danger-emphasis"
                 >
                   {item.content}
@@ -201,8 +227,22 @@ const ChatTranscript = React.memo(function ChatTranscript({
             }
             // O assistente responde direto no corpo, em Markdown (convenção da casa).
             return (
-              <div key={i} className="break-words px-1 text-sm leading-snug">
+              <div
+                key={item.id ?? i}
+                data-slot="chat-message"
+                data-message-id={item.id}
+                data-message-created-at={item.createdAt}
+                className="group/chat-message break-words px-1 text-sm leading-snug"
+              >
                 <Markdown content={item.content} />
+                {renderMessageActions !== undefined && (
+                  <div
+                    data-slot="chat-message-actions"
+                    className="mt-1 flex min-h-5 items-center opacity-0 transition-opacity group-hover/chat-message:opacity-100 focus-within:opacity-100"
+                  >
+                    {renderMessageActions(item)}
+                  </div>
+                )}
               </div>
             )
           })}
@@ -257,6 +297,7 @@ export function Chat({
   initialMessages,
   kickoff,
   renderArtifact,
+  renderMessageActions,
   humanizeTool = defaultHumanizeTool,
   placeholder = 'Escreva uma mensagem…',
   className,
@@ -335,7 +376,7 @@ export function Chat({
       return
     }
 
-    const next: ChatTranscriptItem[] = [...ownItems, { role: 'user', content: text }]
+    const next: ChatTranscriptItem[] = [...ownItems, { ...transcriptMeta(), role: 'user', content: text }]
     setOwnItems(next)
     const transcript = next.filter((i): i is ChatMessage => i.role === 'user' || i.role === 'assistant')
     await consume(() => send!(transcript))
@@ -349,16 +390,18 @@ export function Chat({
       const result = run()
       if (isAsyncIterable(result)) {
         let streaming = false
+        let streamingMeta: { id: string; createdAt: string } | undefined
         for await (const event of result) {
           if (event.type === 'text') {
             setOwnActivity(null)
             setOwnItems((list) => {
               const last = list[list.length - 1]
               if (streaming && last !== undefined && last.role === 'assistant') {
-                return [...list.slice(0, -1), { role: 'assistant', content: last.content + event.delta }]
+                return [...list.slice(0, -1), { ...last, content: last.content + event.delta }]
               }
               streaming = true
-              return [...list, { role: 'assistant', content: event.delta }]
+              streamingMeta = transcriptMeta()
+              return [...list, { ...streamingMeta, role: 'assistant', content: event.delta }]
             })
           } else if (event.type === 'tool') {
             streaming = false
@@ -367,20 +410,20 @@ export function Chat({
             streaming = false
             setOwnItems((list) => [
               ...list,
-              { role: 'artifact', artifact: { kind: event.kind, ref: event.ref, title: event.title } },
+              { ...transcriptMeta(), role: 'artifact', artifact: { kind: event.kind, ref: event.ref, title: event.title } },
             ])
           } else if (event.type === 'done') {
             if (!event.ok) {
-              setOwnItems((list) => [...list, { role: 'error', content: event.error ?? 'Desculpe, algo falhou.' }])
+              setOwnItems((list) => [...list, { ...transcriptMeta(), role: 'error', content: event.error ?? 'Desculpe, algo falhou.' }])
             }
           }
         }
       } else {
         const reply = await result
-        setOwnItems((list) => [...list, { role: 'assistant', content: reply }])
+        setOwnItems((list) => [...list, { ...transcriptMeta(), role: 'assistant', content: reply }])
       }
     } catch {
-      setOwnItems((list) => [...list, { role: 'error', content: 'Desculpe, algo falhou.' }])
+      setOwnItems((list) => [...list, { ...transcriptMeta(), role: 'error', content: 'Desculpe, algo falhou.' }])
     } finally {
       setOwnBusy(false)
       setOwnActivity(null)
@@ -395,6 +438,7 @@ export function Chat({
         greeting={greeting}
         empty={empty}
         renderArtifact={renderArtifact}
+        renderMessageActions={renderMessageActions}
       />
       {/* Composer da casa (pílula elevada, enviar dentro). Extraído no <Composer> — o Chat
           liga texto/envio e repassa `composerActions` pros seletores da conversa (agente,

package/src/ui/docs/content/chat.md

@@ -92,6 +92,11 @@ Reidratação: passe `initialMessages` com o histórico persistido e troque a `k
 componente ao trocar de conversa. O rótulo do indicador é customizável por
 `humanizeTool={(name) => '…'}`.
 
+Itens controlados podem carregar `id` e `createdAt`. O Chat os projeta no elemento da
+mensagem e oferece `renderMessageActions` para ações contextuais discretas. O slot não
+busca nem conhece detalhes: o app deve carregar informação complementar somente após a
+interação da pessoa e aplicar novamente sua autorização.
+
 ## Propriedades de Chat
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -109,5 +114,6 @@ componente ao trocar de conversa. O rótulo do indicador é customizável por
 | `initialMessages` | `ChatMessage[]` | | Histórico inicial do modo autogerenciado; troque a `key` ao trocar de conversa. |
 | `kickoff` | `() => Promise<string> \| AsyncIterable<ChatEvent>` | | Conversa que começa pelo assistente, uma vez, quando o transcript nasce vazio. |
 | `renderArtifact` | `(artifact: ChatArtifact) => ReactNode` | link com o título | Render do evento `artifact`. |
+| `renderMessageActions` | `(message: ChatTranscriptMessage) => ReactNode` | | Ações contextuais da mensagem; ficam visíveis em hover ou foco. |
 | `humanizeTool` | `(name: string, detail?: string) => string` | pt-BR embutido | Rótulo humano do tool em uso no indicador vivo. |
 | `placeholder` | `string` | `'Escreva uma mensagem…'` | Placeholder do composer. |