@flamingo-stack/openframe-frontend-core 0.0.201 → 0.0.202

package/src/components/chat/approval-request-message.tsx

@@ -6,11 +6,77 @@ import { Button } from "../ui/button"
 import { Tag } from "../ui/tag"
 import { CheckCircle, XCircle } from "lucide-react"
 import type { ApprovalRequestMessageProps } from "./types"
+import type { ApprovalRequestField } from "./types/message.types"
+
+/**
+ * Stacked label/value rows for the approval card's structured field
+ * list. Labels are tiny uppercase muted text; values render as primary
+ * text with `whitespace-pre-wrap` so multi-line descriptions
+ * (`content`, `resolution`, etc.) keep their structure. Mirrored across
+ * the pending + resolved branches so an approved ticket reads the same
+ * way it did at decision time.
+ */
+function ApprovalFieldList({ fields }: { fields: ApprovalRequestField[] }) {
+  return (
+    <dl className="flex flex-col gap-2.5 mt-1">
+      {fields.map((f, i) => (
+        <div key={i} className="flex flex-col gap-0.5">
+          <dt className="font-['DM_Sans'] font-semibold text-[11px] uppercase tracking-wide text-ods-text-tertiary leading-4">
+            {f.label}
+          </dt>
+          <dd className="font-['DM_Sans'] text-sm text-ods-text-primary leading-5 whitespace-pre-wrap break-words">
+            {f.value}
+          </dd>
+        </div>
+      ))}
+    </dl>
+  )
+}
+
+/**
+ * Shared body for both pending and resolved branches of
+ * `<ApprovalRequestMessage>`. The pending card adds Approve/Reject
+ * buttons below; the resolved card adds an Approved/Rejected `<Tag>`.
+ * Everything ABOVE the footer — command bar, icon, structured-fields
+ * stack, explanation paragraph — is identical, so the body lives here
+ * to prevent silent drift between the two render paths (a prior
+ * version already had a `break-words` vs `break-all` mismatch on the
+ * `<code>` element from an out-of-sync copy-paste edit).
+ */
+function ApprovalCardBody({
+  data,
+}: {
+  data: ApprovalRequestMessageProps['data']
+}) {
+  return (
+    <div className="flex flex-col gap-1">
+      <div className="bg-ods-bg border border-ods-border rounded-md p-3 flex gap-2 items-start max-h-32 overflow-y-auto">
+        <code className="font-['DM_Sans'] font-medium text-sm text-ods-text-primary flex-1 leading-5 whitespace-pre-wrap break-words">
+          {data.command}
+        </code>
+        {data.icon && (
+          <div className="w-4 h-4 shrink-0 text-ods-text-tertiary">
+            {data.icon}
+          </div>
+        )}
+      </div>
+      {data.fields && data.fields.length > 0 ? (
+        <ApprovalFieldList fields={data.fields} />
+      ) : (
+        data.explanation && (
+          <p className="font-['DM_Sans'] font-medium text-sm text-ods-text-secondary leading-5 whitespace-pre-line break-words">
+            {data.explanation}
+          </p>
+        )
+      )}
+    </div>
+  )
+}
 
 const ApprovalRequestMessage = forwardRef<HTMLDivElement, ApprovalRequestMessageProps>(
   ({ className, data, onApprove, onReject, status = 'pending', ...props }, ref) => {
     const [isProcessing, setIsProcessing] = useState(false)
-    
+
     const handleApprove = async () => {
       setIsProcessing(true)
       try {
@@ -28,49 +94,7 @@ const ApprovalRequestMessage = forwardRef<HTMLDivElement, ApprovalRequestMessage
         setIsProcessing(false)
       }
     }
-    
-    if (status !== 'pending') {
-      return (
-        <div
-          ref={ref}
-          className={cn(
-            "bg-ods-card border border-ods-border rounded-md p-4 mb-2 flex flex-col gap-4",
-            className
-          )}
-          {...props}
-        >
-          {/* Command and icon section */}
-          <div className="flex flex-col gap-1">
-            <div className="bg-ods-bg border border-ods-border rounded-md p-3 flex gap-2 items-start max-h-32 overflow-y-auto">
-              <code className="font-['DM_Sans'] font-medium text-sm text-ods-text-primary flex-1 leading-5 whitespace-pre-wrap break-words">
-                {data.command}
-              </code>
-              {data.icon && (
-                <div className="w-4 h-4 shrink-0 text-ods-text-tertiary">
-                  {data.icon}
-                </div>
-              )}
-            </div>
-            
-            {data.explanation && (
-              <p className="font-['DM_Sans'] font-medium text-sm text-ods-text-secondary leading-5 whitespace-pre-line break-words">
-                {data.explanation}
-              </p>
-            )}
-          </div>
-          
-          {/* Status indicator */}
-          <div className="flex">
-            <Tag
-              label={status === 'approved' ? 'Approved' : 'Rejected'}
-              variant={status === 'approved' ? 'success' : 'error'}
-              icon={status === 'approved' ? <CheckCircle className="w-4 h-4" /> : <XCircle className="w-4 h-4" />}
-            />
-          </div>
-        </div>
-      )
-    }
-    
+
     return (
       <div
         ref={ref}
@@ -80,55 +104,45 @@ const ApprovalRequestMessage = forwardRef<HTMLDivElement, ApprovalRequestMessage
         )}
         {...props}
       >
-        {/* Command and icon section */}
-        <div className="flex flex-col gap-1">
-          <div className="bg-ods-bg border border-ods-border rounded-md p-3 flex gap-2 items-start max-h-32 overflow-y-auto">
-            <code className="font-['DM_Sans'] font-medium text-sm text-ods-text-primary flex-1 leading-5 whitespace-pre-wrap break-all">
-              {data.command}
-            </code>
-            {data.icon && (
-              <div className="w-4 h-4 shrink-0 text-ods-text-tertiary">
-                {data.icon}
-              </div>
-            )}
+        <ApprovalCardBody data={data} />
+        {status === 'pending' ? (
+          <div className="flex gap-4 items-center">
+            <Button
+              size="small-legacy"
+              variant="accent"
+              onClick={handleApprove}
+              disabled={isProcessing}
+              className={cn(
+                "bg-ods-accent hover:bg-ods-accent/90",
+                "font-mono font-medium md:!text-sm text-ods-bg uppercase tracking-[-0.28px]",
+                "px-2 py-1 h-auto"
+              )}
+            >
+              Approve
+            </Button>
+            <Button
+              size="small-legacy"
+              variant="outline"
+              onClick={handleReject}
+              disabled={isProcessing}
+              className={cn(
+                "bg-ods-card border-ods-border",
+                "font-mono font-medium md:!text-sm text-ods-text-primary uppercase tracking-[-0.28px]",
+                "hover:bg-ods-bg px-2 py-1 h-auto"
+              )}
+            >
+              Reject
+            </Button>
           </div>
-          
-          {data.explanation && (
-            <p className="font-['DM_Sans'] font-medium text-sm text-ods-text-secondary leading-5">
-              {data.explanation}
-            </p>
-          )}
-        </div>
-        
-        {/* Approve/Reject buttons */}
-        <div className="flex gap-4 items-center">
-          <Button
-            size="small-legacy"
-            variant="accent"
-            onClick={handleApprove}
-            disabled={isProcessing}
-            className={cn(
-              "bg-ods-accent hover:bg-ods-accent/90",
-              "font-mono font-medium md:!text-sm text-ods-bg uppercase tracking-[-0.28px]",
-              "px-2 py-1 h-auto"
-            )}
-          >
-            Approve
-          </Button>
-          <Button
-            size="small-legacy"
-            variant="outline"
-            onClick={handleReject}
-            disabled={isProcessing}
-            className={cn(
-              "bg-ods-card border-ods-border",
-              "font-mono font-medium md:!text-sm text-ods-text-primary uppercase tracking-[-0.28px]",
-              "hover:bg-ods-bg px-2 py-1 h-auto"
-            )}
-          >
-            Reject
-          </Button>
-        </div>
+        ) : (
+          <div className="flex">
+            <Tag
+              label={status === 'approved' ? 'Approved' : 'Rejected'}
+              variant={status === 'approved' ? 'success' : 'error'}
+              icon={status === 'approved' ? <CheckCircle className="w-4 h-4" /> : <XCircle className="w-4 h-4" />}
+            />
+          </div>
+        )}
       </div>
     )
   }

package/src/components/chat/chat-container.tsx

@@ -11,14 +11,18 @@ import type { ConnectionIndicatorProps, ChatContainerProps, ChatHeaderProps } fr
 const ConnectionIndicator: React.FC<ConnectionIndicatorProps> = ({ status }) => {
   const getStatusStyles = () => {
     switch (status) {
+      // ODS attention tokens — same scheme used by the rest of the chat
+      // shell (StatusBadge, error toast, etc.). Hex Tailwind palette
+      // (`bg-green-500` / `bg-red-500`) would diverge from the theme and
+      // is forbidden by the host's design-token policy.
       case 'connected':
-        return 'bg-green-500'
+        return 'bg-ods-attention-green-success'
       case 'connecting':
-        return 'bg-yellow-500 animate-pulse'
+        return 'bg-ods-attention-yellow-warning animate-pulse'
       case 'disconnected':
-        return 'bg-red-500'
+        return 'bg-ods-attention-red-error'
       default:
-        return 'bg-gray-500'
+        return 'bg-ods-text-tertiary'
     }
   }
 

package/src/components/chat/chat-message-enhanced.tsx

@@ -111,8 +111,32 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
           // returns the cached node so React reuses the same instance.
           let rendered = seenRendered.get(key)
           if (!seenRendered.has(key)) {
+            // Always invoke render() — even when the metadata map has
+            // no entry for this marker. Fetch-mode card types
+            // (delivery_item, roadmap_item, internal_task, etc.) don't
+            // ship metadata in the SSE frame; they self-fetch by `id`
+            // via the host's list-API hook, so a minimal {type,id}
+            // ChatRef is all the renderer needs to mount the loader.
+            // For no-fetch types (hubspot_ticket_self, slack_message,
+            // …) without a refMatch the host's render() returns null
+            // and we fall through to the bare-cardId fallback in the
+            // `<a card://…>` override below.
+            //
+            // SYNTHETIC REF DEFAULTS: `ChatRef.title` and `ChatRef.url`
+            // are non-optional in the type; a bare `{type, id}` cast
+            // would lie to consumers that read those fields. Default
+            // `title` to the cardId (so any host renderer that prints
+            // `ref.title` shows the id rather than `undefined`) and
+            // `url` to null (matches the no-link semantics fetch-mode
+            // cards rely on — they resolve their own URL after fetch).
             const refMatch = refs[key]
-            rendered = refMatch ? render(refMatch) : undefined
+            const refForRender: ChatRef = refMatch ?? {
+              type: cardType,
+              id: cardId,
+              title: cardId,
+              url: null,
+            }
+            rendered = render(refForRender)
             seenRendered.set(key, rendered)
           }
           if (React.isValidElement(rendered) && rendered.type === BlockCard) {
@@ -171,15 +195,33 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
               const key = `${cardType}:${cardId}`
               const inline = inlineByKey?.get(key)
               if (inline != null) return inline
-              // No renderer, no ref, OR renderer returned null — fall back
-              // to plain text title-only. Use any same-type ref's title if
-              // available; otherwise the bare cardId. Never render the
-              // literal `card://` URL.
+              // Three fallback cases — keep them DISTINCT, never blur them
+              // together. Mixing them up (which the old code did by reaching
+              // for "any same-type ref's title") makes LLM hallucinations
+              // LOOK like real cards, which the user can't tell apart from
+              // genuine references.
+              //
+              //   (1) Exact ref present, renderer returned null:
+              //       The marker is legit (server confirmed the row exists)
+              //       but no compact-card type is registered for `cardType`.
+              //       Render the ref's REAL title as plain text — accurate,
+              //       just no rich UI.
+              //
+              //   (2) Exact ref absent (refs map has no `${cardType}:${cardId}`):
+              //       The LLM emitted a marker for an ID the server did NOT
+              //       surface. Either the LLM hallucinated the id, or the
+              //       refs map and the snapshot drifted (server-side bug
+              //       worth fixing — see `MAX_ROWS_PER_ENTITY_GROUP` in
+              //       `doc-chat-utils.ts:buildSourcesMeta`). Render the raw
+              //       `cardId` so the breakage is VISIBLE; never borrow a
+              //       title from an unrelated ref — that hides the bug and
+              //       deceives the reader into thinking they're looking at
+              //       a real card.
               const refMatch: ChatRef | undefined = refs[key]
-              const fallbackTitle = (refMatch?.title)
-                ?? Object.values(refs).find((r) => r.type === cardType)?.title
-                ?? cardId
-              return <span className="text-ods-text-primary">{fallbackTitle}</span>
+              if (refMatch) {
+                return <span className="text-ods-text-primary">{refMatch.title}</span>
+              }
+              return <span className="text-ods-text-secondary opacity-60">{cardId}</span>
             }
           }
           // Unified click rule — delegated to the host's `NavLinkAnchor`

package/src/components/chat/chat-message-list.tsx

@@ -441,25 +441,33 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
               <div ref={sentinelRef} className="h-px" />
             )}
             <div className="flex-1" />
-            {messages.map((message, index) => (
-              <ChatMessageEnhanced
-                key={message.id}
-                ref={getRegisterMessageEl(message.id)}
-                role={message.role}
-                name={message.name}
-                content={message.content}
-                timestamp={message.timestamp}
-                isTyping={index === messages.length - 1 && isTyping && message.role === 'assistant'}
-                avatar={showAvatars ? message.avatar : null}
-                showAvatar={showAvatars}
-                assistantType={message.assistantType || assistantType}
-                authorType={message.authorType}
-                assistantIcon={message.role !== 'user' ? assistantIcon : undefined}
-                chatRefs={message.chatRefs}
-                renderEntityCard={renderEntityCard}
-                NavLinkAnchor={NavLinkAnchor}
-              />
-            ))}
+            {messages.map((message, index) => {
+              // Hidden messages (synthetic continuation prompts the host
+              // injects after an approval card) are part of the API
+              // conversation history but never render. Skipping here
+              // keeps the visible thread coherent — see
+              // `Message.hidden` doc-comment in message.types.ts.
+              if (message.hidden) return null
+              return (
+                <ChatMessageEnhanced
+                  key={message.id}
+                  ref={getRegisterMessageEl(message.id)}
+                  role={message.role}
+                  name={message.name}
+                  content={message.content}
+                  timestamp={message.timestamp}
+                  isTyping={index === messages.length - 1 && isTyping && message.role === 'assistant'}
+                  avatar={showAvatars ? message.avatar : null}
+                  showAvatar={showAvatars}
+                  assistantType={message.assistantType || assistantType}
+                  authorType={message.authorType}
+                  assistantIcon={message.role !== 'user' ? assistantIcon : undefined}
+                  chatRefs={message.chatRefs}
+                  renderEntityCard={renderEntityCard}
+                  NavLinkAnchor={NavLinkAnchor}
+                />
+              )
+            })}
           </div>
         </div>
 

package/src/components/chat/types/message.types.ts

@@ -78,8 +78,24 @@ export interface ExecutingToolState {
 
 // ========== Approval Request Types ==========
 
+export interface ApprovalRequestField {
+  /** Short label — e.g. "Subject", "Priority". Rendered in a muted
+   *  caps style above the value. */
+  label: string
+  /** Free-text value. Wraps and line-breaks are preserved
+   *  (`whitespace-pre-wrap`). */
+  value: string
+}
+
 export interface ApprovalRequestData {
   command: string
+  /** Structured field list — preferred over `explanation`. When set,
+   *  the approval card renders a vertical label/value stack with
+   *  proper spacing. Falls back to `explanation` (a single paragraph)
+   *  when omitted. Keep BOTH when you want hosts on older lib
+   *  versions to still see the prose; new hosts should send only
+   *  `fields`. */
+  fields?: ApprovalRequestField[]
   explanation?: string
   icon?: React.ReactNode
   requestId?: string
@@ -333,4 +349,23 @@ export interface Message {
    *  whose body is a long article). The server is the sole decision-
    *  maker — set on the metadata leading frame. */
   scrollAnchor?: ScrollAnchor
+  /** When true the message is part of the API conversation history (sent
+   *  to the LLM so it has context) but is NOT rendered in the chat UI.
+   *
+   *  Used for "synthetic continuation" turns: when the user clicks Approve
+   *  on a tool proposal, the host auto-fires a follow-up `sendMessage`
+   *  with `hidden: true` carrying a directive like "the user just
+   *  approved <tool>; ask follow-up questions per protocol". The LLM's
+   *  response IS rendered (as a normal assistant message); only the
+   *  trigger prompt is suppressed so the chat reads naturally:
+   *
+   *    user: "open a ticket"
+   *    assistant: preamble + approval card
+   *    [user clicks Approve]
+   *    assistant: "Now to triage faster, can you share..."   ← auto-fires
+   *
+   *  Without this flag the trigger prompt would surface as a confusing
+   *  bubble like "(continue per protocol)" between the approval card
+   *  and the AI's follow-up. */
+  hidden?: boolean
 }

package/src/components/features/index.ts

@@ -2,6 +2,21 @@
 
 // Feature Components exports
 export { DynamicThemeProvider, useDynamicTheme } from '../providers/dynamic-theme-provider'
+// Canonical ODS theme system — thin wrapper over `next-themes`
+// (manual light/dark, default dark, no-flash handled by next-themes).
+// Headless by design: apps build their own toggle button via the lib's
+// existing <Button> + `useThemeToggle()`.
+export {
+  ThemeProvider,
+  useTheme,
+  useThemeToggle,
+  THEME_STORAGE_KEY,
+  THEME_ATTRIBUTE,
+  DEFAULT_THEME,
+  type Theme,
+  type ThemeProviderProps,
+  type UseThemeToggleResult,
+} from '../providers/theme-provider'
 export * from './array-entry-manager'
 export * from './auth-providers-list'
 export * from './changelog-manager'

package/src/components/providers/theme-provider.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import * as React from "react";
+import {
+  ThemeProvider as NextThemesProvider,
+  useTheme as useNextTheme,
+} from "next-themes";
+import type { ThemeProviderProps as NextThemesProviderProps } from "next-themes/dist/types";
+
+/**
+ * ODS theme system — thin wrapper over `next-themes`.
+ *
+ * We deliberately do NOT hand-roll a provider/no-flash script: `next-themes`
+ * is already a dependency, is battle-tested in Next.js (App & Pages router),
+ * injects its own pre-paint anti-flash script, handles SSR + localStorage +
+ * cross-tab sync, and also works in plain React (Vite/Tauri).
+ *
+ * Product model (locked): a MANUAL light/dark switch, default DARK,
+ * persisted to localStorage. No "system" mode (`enableSystem={false}`).
+ *
+ * Drives styling by setting `data-theme="light|dark"` on <html>;
+ * `src/styles/ods-colors.css` swaps the `--ods-*` primitives accordingly.
+ *
+ * Public API exposed by this module:
+ *   • `<ThemeProvider>` — preconfigured next-themes provider.
+ *   • `useTheme()`      — raw next-themes hook (advanced cases).
+ *   • `useThemeToggle()`— headless convenience hook for building toggle UI
+ *                         in consumer apps (no styled component on purpose;
+ *                         apps own their button visuals via the lib's
+ *                         existing `<Button>`).
+ */
+
+export type Theme = "light" | "dark";
+
+export const THEME_STORAGE_KEY = "ods-theme";
+export const THEME_ATTRIBUTE = "data-theme";
+export const DEFAULT_THEME: Theme = "dark";
+
+export type ThemeProviderProps = Partial<NextThemesProviderProps>;
+
+/**
+ * Pre-configured provider. Wrap the app once (Next.js: in the root layout;
+ * apps must keep `suppressHydrationWarning` on <html> — already the case).
+ * No `<ThemeScript>` needed — next-themes handles the no-flash script.
+ *
+ * All next-themes props are overridable, but the ODS defaults below encode
+ * the product decision.
+ */
+export function ThemeProvider({ children, ...overrides }: ThemeProviderProps) {
+  return (
+    <NextThemesProvider
+      attribute={THEME_ATTRIBUTE}
+      defaultTheme={DEFAULT_THEME}
+      enableSystem={false}
+      themes={["light", "dark"]}
+      storageKey={THEME_STORAGE_KEY}
+      disableTransitionOnChange={false}
+      {...overrides}
+    >
+      {children}
+    </NextThemesProvider>
+  );
+}
+
+/**
+ * Re-export of next-themes' `useTheme` (no custom logic on top).
+ * Returns `{ theme, setTheme, resolvedTheme, themes, ... }`.
+ */
+export const useTheme = useNextTheme;
+
+/* ------------------------------------------------------------------ */
+/* useThemeToggle — headless convenience for building toggle UIs      */
+/* ------------------------------------------------------------------ */
+
+export interface UseThemeToggleResult {
+  /** Becomes `true` after the client has hydrated and resolved the stored
+   *  preference. Until then, `theme`/`isDark`/`isLight` reflect the SSR
+   *  default (`DEFAULT_THEME`) — handy for rendering a stable placeholder. */
+  mounted: boolean;
+  /** Resolved active theme (`"dark"` until mounted, then real value). */
+  theme: Theme;
+  isDark: boolean;
+  isLight: boolean;
+  /** Flip dark↔light and persist. */
+  toggle: () => void;
+  /** Set explicitly to `"light"` or `"dark"` and persist. */
+  setTheme: (theme: Theme) => void;
+}
+
+/**
+ * Headless toggle helper. Build any button you like:
+ *
+ *   const { isDark, toggle, mounted } = useThemeToggle()
+ *   <Button size="icon" variant="transparent" onClick={toggle} aria-label="…">
+ *     {mounted && (isDark ? <Sun01Icon /> : <MoonIcon />)}
+ *   </Button>
+ *
+ * The mount gate avoids hydration mismatch (next-themes only knows the
+ * persisted preference on the client after mount).
+ */
+export function useThemeToggle(): UseThemeToggleResult {
+  const { resolvedTheme, theme, setTheme } = useTheme();
+  const [mounted, setMounted] = React.useState(false);
+  React.useEffect(() => setMounted(true), []);
+
+  const active: Theme = mounted
+    ? resolvedTheme === "light" || theme === "light"
+      ? "light"
+      : "dark"
+    : DEFAULT_THEME;
+
+  const setOdsTheme = React.useCallback(
+    (next: Theme) => setTheme(next),
+    [setTheme],
+  );
+
+  const toggle = React.useCallback(
+    () => setTheme(active === "dark" ? "light" : "dark"),
+    [active, setTheme],
+  );
+
+  return {
+    mounted,
+    theme: active,
+    isDark: active === "dark",
+    isLight: active === "light",
+    toggle,
+    setTheme: setOdsTheme,
+  };
+}