@flamingo-stack/openframe-frontend-core 0.0.204 → 0.0.205

package/src/components/chat/hooks/use-proxied-image-url.ts

@@ -0,0 +1,31 @@
+'use client'
+
+import { useRequiredChatRuntime } from '../../../contexts/chat-runtime-context'
+import { getProxiedImageUrl } from '../../../utils/image-proxy'
+
+/**
+ * Hook-version of `getProxiedImageUrl` that reads `proxyPrefix` and
+ * `skipDomains` from the ambient `ChatRuntime`. Use anywhere inside
+ * a `<ChatRuntimeContext.Provider>`.
+ *
+ * Returns the input URL (or `''` for null/undefined) when no
+ * `imageProxyUrlPrefix` is configured. Always passes `directHttps: true`
+ * — callers that need proxied https (e.g. raster-only) must use the pure
+ * `getProxiedImageUrl` from `@flamingo-stack/openframe-frontend-core/utils`
+ * directly.
+ *
+ * Rules of hooks: call at the TOP of a component, NOT inside loops/maps.
+ * For `.map(item => proxy(item.url))` patterns, use the pure
+ * `getProxiedImageUrl` and hardcode the proxy config — the rare
+ * non-React-tree caller pattern.
+ */
+export function useProxiedImageUrl(url: string | null | undefined): string {
+  const r = useRequiredChatRuntime()
+  return (
+    getProxiedImageUrl(url ?? '', {
+      proxyPrefix: r.endpoints.imageProxyUrlPrefix,
+      skipDomains: r.endpoints.imageProxySkipDomains,
+      directHttps: true,
+    }) ?? ''
+  )
+}

package/src/components/chat/hooks/use-slash-commands.ts

@@ -0,0 +1,106 @@
+"use client";
+
+/**
+ * Client-side hook + helper for the slash-command autocomplete.
+ *
+ * `fetchSlashCommands` is a stateless wrapper around the host's
+ * commands endpoint. The caller threads the URL — the lib never
+ * depends on hub-internal route paths.
+ *
+ * `useSlashCommands` is the React-state version (debounced, cancellable).
+ *
+ * Types live in `../types/component.types` so the autocomplete
+ * dropdown and the chat-side runtime share one source of truth.
+ */
+
+import { useEffect, useState } from "react";
+import type {
+  SlashCommandActionId,
+  SlashCommandSummaryAction,
+  SlashCommandSummary,
+} from "../types/component.types";
+
+// Re-export so callers can `import { SlashCommandSummary } from
+// '@flamingo-stack/openframe-frontend-core/components/chat/hooks'`
+// without reaching into types. The component.types module is the
+// canonical declaration.
+export type {
+  SlashCommandActionId,
+  SlashCommandSummaryAction,
+  SlashCommandSummary,
+};
+
+/**
+ * Fetch slash-command suggestions for the CURRENT deployment platform,
+ * matching id-prefix `prefix`. The chat source is server-resolved — the
+ * client sends NO `source` param on the URL.
+ *
+ * `commandsUrl` is required — supplied by `useChatRuntime().endpoints.commandsUrl`
+ * at the call site. NO default value.
+ *
+ * URL handling: `new URL(commandsUrl, window.location.origin)` works
+ * for both relative (e.g. `/api/mingo-guide/commands` → resolved against
+ * the embedder origin, proxy handles it) and absolute
+ * (e.g. `https://hub.openframe.ai/api/commands` → the base arg is
+ * ignored).
+ *
+ * Returns the parsed `commands` array; on any non-2xx (auth,
+ * rate-limit, chat-disabled) returns an empty array — the autocomplete
+ * UI silently shows no suggestions rather than surfacing 401/403/429
+ * toasts.
+ */
+export async function fetchSlashCommands(
+  prefix: string,
+  signal: AbortSignal | undefined,
+  commandsUrl: string,
+): Promise<SlashCommandSummary[]> {
+  const url = new URL(commandsUrl, window.location.origin);
+  if (prefix) url.searchParams.set("q", prefix);
+  const res = await fetch(url.toString(), { signal });
+  if (!res.ok) return [];
+  const data = (await res.json()) as { commands?: SlashCommandSummary[] };
+  return data.commands ?? [];
+}
+
+/**
+ * Debounced, cancellable React hook. Returns `{ commands, loading }`.
+ *
+ * `commandsUrl` is required — pass `useChatRuntime().endpoints.commandsUrl`.
+ */
+export function useSlashCommands(
+  prefix: string | null,
+  commandsUrl: string,
+): { commands: SlashCommandSummary[]; loading: boolean } {
+  const [commands, setCommands] = useState<SlashCommandSummary[]>([]);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    if (prefix == null) {
+      setCommands([]);
+      return;
+    }
+    let cancelled = false;
+    const ctrl = new AbortController();
+    setLoading(true);
+    const handle = setTimeout(async () => {
+      try {
+        const next = await fetchSlashCommands(prefix, ctrl.signal, commandsUrl);
+        if (!cancelled) setCommands(next);
+      } catch (err) {
+        // AbortError on dep-change / unmount is expected; log others.
+        if (!cancelled && (err as Error)?.name !== "AbortError") {
+          console.warn("[use-slash-commands] fetch failed:", err);
+        }
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    }, 150);
+    return () => {
+      cancelled = true;
+      ctrl.abort();
+      clearTimeout(handle);
+    };
+  }, [prefix, commandsUrl]);
+
+  return { commands, loading };
+}

package/src/components/chat/hooks/use-sse.ts

@@ -0,0 +1,143 @@
+'use client'
+
+import { useState, useCallback, useRef } from 'react'
+import type { MessageSegment } from '../types/message.types'
+import type { WireCommandOverride } from '../utils/slash-dispatch-utils'
+import type { ChatAttachment } from '../utils/chat-attachment-markdown'
+
+/**
+ * Stream function signature. The optional `signal` is created fresh per
+ * `streamMessage` call so the underlying fetch can be aborted cleanly when
+ * the user clicks Stop. Without the signal, abort would only stop yielding
+ * chunks at the iterator boundary while the upstream Anthropic request
+ * continued running (and billing).
+ *
+ * `extraOptions` carries per-call extras (currently `commandOverride` for
+ * the inline-card "Discuss" affordance per v6.1 §B.2.8). Kept generic so
+ * future per-call wire fields don't bloat the signature.
+ */
+export interface StreamFnExtraOptions {
+  commandOverride?: WireCommandOverride
+  /** Out-of-band signal for the post-approval / post-reject
+   *  server-driven turn. When set, the streamFn routes to
+   *  `/api/chat/agent/confirm-tool` instead of `/api/docs/chat` and
+   *  encodes the action on the request body. The server emits a
+   *  `decision_resolved` leading frame that the chat-shell uses to
+   *  flip the SOURCE approval card (different assistant message than
+   *  the one being streamed into), then — on approve + write tool —
+   *  pipes the auto-continuation Sonnet response as standard chat SSE
+   *  frames into a NEW assistant turn. The CLIENT does not orchestrate
+   *  the auto-continuation; it just renders frames. */
+  approvalAction?: {
+    proposalId: string
+    action: 'approve' | 'reject'
+  }
+  /** Chat-attachment payload riding alongside the user's text — the
+   *  staged attachments produced by `useChatAttachments`. Server-side,
+   *  `runDocsChat` strips the embedded `/api/storage/view/chat-attachments/...`
+   *  markdown lines from the user's text and replaces them with
+   *  Anthropic image content blocks (raw signed URLs).
+   *
+   *  Wire format: `storagePath` + `viewToken` only — NEVER a `url`
+   *  field. Server validates against `ChatAttachmentSchema` and rejects
+   *  malformed shapes. */
+  pendingAttachments?: ChatAttachment[]
+}
+export type StreamFn = (
+  message: string,
+  signal?: AbortSignal,
+  extra?: StreamFnExtraOptions,
+) => AsyncGenerator<MessageSegment>
+
+interface UseSSEOptions {
+  useMock?: boolean
+  debugMode?: boolean
+  /** Custom stream function — when provided, bypasses the mock fallback */
+  streamFn?: StreamFn
+}
+
+export function useSSE({ useMock = true, debugMode = false, streamFn }: UseSSEOptions = {}) {
+  const [isStreaming, setIsStreaming] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const abortControllerRef = useRef<AbortController | null>(null)
+
+  // Lib-side mock fallback — useDocChat ALWAYS sets `useMock: false`,
+  // so this path is unreachable in production usage. Kept as a clear
+  // error so any future caller that flips `useMock: true` without
+  // providing a `streamFn` gets a loud signal instead of a silent
+  // misroute. Hub-side wrappers that need the mock can supply their
+  // own streamFn from a MockChatService.
+  const fallbackStream = useCallback(async function* (): AsyncGenerator<MessageSegment> {
+    throw new Error(
+      '[useSSE] No streamFn provided and `useMock: true` is no longer wired into the lib. ' +
+        'Supply a `streamFn` (see `createDocStreamFn` in use-embedded-chat) or migrate the ' +
+        'mock to your host code.',
+    )
+  }, [])
+
+  const streamMessage = useCallback(
+    async function* (
+      message: string,
+      extra?: StreamFnExtraOptions,
+    ): AsyncGenerator<MessageSegment> {
+      setIsStreaming(true)
+      setError(null)
+
+      // Create a fresh AbortController for this stream. abort() targets it via
+      // the ref; the signal is passed THROUGH to streamFn so the underlying
+      // fetch (and Anthropic upstream) terminates on Stop.
+      const ctrl = new AbortController()
+      abortControllerRef.current = ctrl
+
+      try {
+        const generator = streamFn
+          ? streamFn(message, ctrl.signal, extra)
+          : fallbackStream()
+
+        for await (const chunk of generator) {
+          // Check if aborted
+          if (ctrl.signal.aborted) {
+            break
+          }
+          yield chunk
+        }
+      } catch (err) {
+        // AbortError on user-initiated stop is expected — surface as a no-error
+        // path so the consumer's catch doesn't render a red error message.
+        if ((err as any)?.name === 'AbortError' || ctrl.signal.aborted) {
+          return
+        }
+        const errorMessage = err instanceof Error ? err.message : 'An error occurred'
+        setError(errorMessage)
+        throw err
+      } finally {
+        setIsStreaming(false)
+        // Only clear the ref if it still points at this controller (defensive
+        // — a rapid send-stop-send sequence might have already replaced it).
+        if (abortControllerRef.current === ctrl) {
+          abortControllerRef.current = null
+        }
+      }
+    },
+    [streamFn, fallbackStream],
+  )
+
+  const abort = useCallback(() => {
+    if (abortControllerRef.current) {
+      abortControllerRef.current.abort()
+    }
+    setIsStreaming(false)
+  }, [])
+
+  const reset = useCallback(() => {
+    // Reset state if needed
+  }, [])
+
+  return {
+    streamMessage,
+    isStreaming,
+    error,
+    abort,
+    reset,
+  }
+}

package/src/components/chat/index.ts

@@ -12,10 +12,8 @@ export * from './chat-input'
 export * from './slash-command-suggestions'
 export * from './chat-message-enhanced'
 export * from './chat-message-list'
-export * from './chat-video-entity-card'
-export * from './block-card'
+
 export * from './chat-quick-action'
-export * from './chat-ticket-item'
 export * from './chat-ticket-list'
 export * from './chat-typing-indicator'
 export * from './tool-execution-display'
@@ -25,6 +23,29 @@ export * from './chat-sidebar'
 export type { ChatRef } from './chat-ref.types'
 export { remarkCardLinks } from './remark-card-links'
 
+// Card-supporting UI migrated from hub `components/shared/*` + `components/blog/*`
+export {
+  NavLinkAnchorViaRuntime,
+  type NavLinkAnchorViaRuntimeProps,
+} from './nav-link-anchor-via-runtime'
+export {
+  SourceActionButton,
+  type SourceActionButtonProps,
+  type SourceActionDensity,
+} from './source-action-button'
+export {
+  ChatAttachmentAddButton,
+  ChatAttachmentChipStrip,
+  type ChatAttachmentAddButtonProps,
+  type ChatAttachmentChipStripProps,
+  type StagedAttachment,
+  CHAT_ATTACHMENT_MIME_TYPES,
+  CHAT_ATTACHMENT_CONCURRENT_UPLOADS_PER_USER,
+} from './chat-attachment-bar'
+
+// Entity-cards (12 refactored + 4 moved + supporting primitives)
+export * from './entity-cards'
+
 // Chat types and constants
 export * from './types'
 
@@ -32,4 +53,9 @@ export * from './types'
 export * from './hooks'
 
 // Chat utilities
-export * from './utils'
+export * from './utils'
+
+// EmbeddableChat — full chat orchestrator (lib-portable port of hub's
+// `<GlobalAskAI>`). Hosts mount it once at the root after providing a
+// <ChatRuntimeContext.Provider>.
+export { EmbeddableChat, type EmbeddableChatProps } from './embeddable-chat'

package/src/components/chat/nav-link-anchor-via-runtime.tsx

@@ -0,0 +1,72 @@
+'use client'
+
+/**
+ * Lib-side `<a>` wrapper for chat-rendered links (markdown bodies,
+ * source-chip drill-ins, inline references).
+ *
+ * Reads the active `ChatRuntime` and routes clicks through
+ * `handleChatNavClick`. Same single-source rules as source chips and
+ * inline cards:
+ *   - new-tab decision via `computeIsNewTab` (embed-mode short-circuit
+ *     + `runtime.navigation.decideNewTab` + lib fallback)
+ *   - `target` / `rel` via `newTabAnchorAttrs`
+ *   - same-tab click → close the chat panel (via `ChatPanelContext`);
+ *     new-tab click → leave panel open while the new tab loads
+ *
+ * Chat-only contract: uses `useRequiredChatRuntime`, which THROWS when
+ * mounted outside a `<ChatRuntimeContext.Provider>`. That's by design —
+ * the lib should never silently fall back when the runtime is missing
+ * (the chat tree always provides one in both host + embed modes).
+ *
+ * For surfaces OUTSIDE the chat tree (header chrome, marketing pages, …)
+ * the hub keeps its own `useNavLink`-based anchor.
+ */
+
+import type { ReactNode, MouseEvent } from 'react'
+import { useRequiredChatRuntime } from '../../contexts/chat-runtime-context'
+import { handleChatNavClick } from './utils/nav-click-handler'
+import { resolveHrefForRuntime } from './utils/chat-nav-resolution'
+import { computeIsNewTab, newTabAnchorAttrs } from './utils/nav-anchor-props'
+import { useChatPanel } from './chat-panel-context'
+
+export interface NavLinkAnchorViaRuntimeProps {
+  href: string
+  path?: string | null
+  targetPlatform?: string | null
+  className?: string
+  /** Optional — matches `NavLinkAnchorComponent`'s contract so the
+   *  markdown-anchor slot can render an empty anchor (rare but legal). */
+  children?: ReactNode
+}
+
+export function NavLinkAnchorViaRuntime({
+  href,
+  path,
+  targetPlatform,
+  className,
+  children,
+}: NavLinkAnchorViaRuntimeProps) {
+  const runtime = useRequiredChatRuntime()
+  const panel = useChatPanel()
+  const resolvedHref = resolveHrefForRuntime(href, runtime)
+  const isNewTab = computeIsNewTab(runtime, resolvedHref, targetPlatform ?? null)
+
+  const onClick = (e: MouseEvent<HTMLAnchorElement>) => {
+    const handled = handleChatNavClick(e, runtime, {
+      href: resolvedHref,
+      path,
+      targetPlatform,
+    })
+    if (handled && !isNewTab && panel?.closeChat) panel.closeChat()
+  }
+  return (
+    <a
+      href={resolvedHref}
+      {...newTabAnchorAttrs(isNewTab)}
+      onClick={onClick}
+      className={className}
+    >
+      {children}
+    </a>
+  )
+}

package/src/components/chat/source-action-button.tsx

@@ -0,0 +1,120 @@
+'use client'
+
+/**
+ * One-component-fits-all "Ask" affordance shared across the three
+ * chat-adjacent surfaces (source chips, inline cards, search results).
+ *
+ * Before this primitive, the same semantic action was implemented three
+ * different ways:
+ *   - Source chip: inline `<button>` next to the chip
+ *   - Source chip dropdown row: secondaryAction icon-button
+ *   - Inline card: UI-Kit `<Button variant="transparent">Ask</Button>`
+ *   - Search results: nothing (asymmetric — no Ask)
+ *
+ * Three icon sizes, three different opacity rules, three different DOM
+ * shapes for the same action. Centralized here as a single `Button`-
+ * backed wrapper so the DOM + a11y + hover behavior live in one place.
+ * The `density` prop picks the visual variant; the icon/label/click
+ * semantics are identical across all three.
+ */
+
+import React from 'react'
+import { MessageSquare, FileText } from 'lucide-react'
+import { Button } from '../ui/button'
+import type { ChatRef } from './chat-ref.types'
+
+export type SourceActionDensity = 'inline' | 'card' | 'list-row'
+
+export interface SourceActionButtonProps {
+  /** The row to drill into when clicked. The button is HIDDEN when this
+   *  is null (e.g. row has no primary key — Ask can't fire). */
+  chatRef: ChatRef | null
+  /** Click handler. Receives the chatRef. When undefined the button is
+   *  hidden — same as null chatRef. */
+  onDiscuss?: (ref: ChatRef) => void
+  /** Visual density / layout. Defaults to `'inline'`. */
+  density?: SourceActionDensity
+  /** Optional className appended to the outer element. */
+  className?: string
+  /** Button text label override. Defaults to `'Ask'`. The Display variant
+   *  on inline cards passes `'Display'` here. Density `'inline'` shows
+   *  the icon only — the label is used for aria-label / title even when
+   *  it doesn't render visibly. */
+  label?: string
+}
+
+// Per-density styling lives in one map so the three call sites share the
+// SAME hover/opacity/transition rules. Adding a fourth density means
+// adding one entry here, not touching the render path.
+const DENSITY_STYLES: Record<
+  SourceActionDensity,
+  {
+    size: 'small' | 'icon'
+    showLabel: boolean
+    iconSize: string
+    className: string
+  }
+> = {
+  inline: {
+    size: 'icon',
+    showLabel: false,
+    iconSize: '!h-3 !w-3',
+    className:
+      '!h-5 !w-5 !p-0 text-ods-text-secondary opacity-60 hover:opacity-100 hover:text-ods-text-primary hover:bg-ods-accent/15',
+  },
+  card: {
+    size: 'small',
+    showLabel: true,
+    iconSize: '!h-3 !w-3',
+    className:
+      '!h-auto !p-0 text-xs font-normal text-ods-text-secondary opacity-60 hover:bg-transparent hover:opacity-100 hover:text-ods-text-primary',
+  },
+  'list-row': {
+    size: 'small',
+    showLabel: true,
+    iconSize: '!h-3 !w-3',
+    className:
+      '!h-auto !px-1.5 !py-0.5 text-[11px] font-normal text-ods-text-secondary opacity-60 hover:opacity-100 hover:text-ods-text-primary hover:bg-ods-accent/10',
+  },
+}
+
+export function SourceActionButton({
+  chatRef,
+  onDiscuss,
+  density = 'inline',
+  className,
+  label = 'Ask',
+}: SourceActionButtonProps): React.ReactElement | null {
+  if (!chatRef || !onDiscuss) return null
+
+  // Label-driven icon. "Display" reads as a verbatim-content action so a
+  // FileText icon reinforces "show me the body" semantics; the default
+  // "Ask" stays MessageSquare for the conversational connotation. Any
+  // future label adds an entry to this map.
+  const isDisplay = label === 'Display'
+  const verbLabel = isDisplay
+    ? `Display ${chatRef.title || 'this item'}`
+    : `Ask about ${chatRef.title || 'this item'}`
+  const handle = (e: React.MouseEvent) => {
+    e.preventDefault()
+    e.stopPropagation()
+    onDiscuss(chatRef)
+  }
+  const styles = DENSITY_STYLES[density]
+  const IconComponent = isDisplay ? FileText : MessageSquare
+  const icon = <IconComponent className={styles.iconSize} />
+
+  return (
+    <Button
+      variant="transparent"
+      size={styles.size}
+      leftIcon={styles.showLabel ? icon : undefined}
+      onClick={handle}
+      aria-label={verbLabel}
+      title={verbLabel}
+      className={`${styles.className}${className ? ` ${className}` : ''}`}
+    >
+      {styles.showLabel ? label : icon}
+    </Button>
+  )
+}

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

@@ -89,3 +89,64 @@ export interface MessageOwner {
     lastName?: string
   }
 }
+
+// ========== ChatRef-key construction ==========
+
+/**
+ * Canonical key shape for the `chatRefs` map carried on every Message —
+ * `${docType}:${externalId}`. The chat-message renderer looks up inline
+ * `[card://<type>:<id>]` markers via this same key shape, so keeping the
+ * construction in one place avoids divergence between the writer
+ * (server-driven attach in decision_resolved handler) and the readers
+ * (renderingPlan in chat-message-enhanced).
+ *
+ * Pure function — no runtime cost vs. inline template literal — but the
+ * call-site reads as "the chat-ref key for this ref" rather than as a
+ * generic string-concat, which is what the eye is hunting for when
+ * scanning the file for ref-keyed logic.
+ */
+export function buildChatRefKey(docType: string, externalId: string): string {
+  return `${docType}:${externalId}`
+}
+
+// ========== Content-shape helpers ==========
+
+import type { MessageContent, MessageSegment } from './message.types'
+
+/** Helper function to check if content is structured (segment array). */
+export function isStructuredContent(content: MessageContent): content is MessageSegment[] {
+  return Array.isArray(content)
+}
+
+/** Normalize either a string or segment array into a uniform segment array. */
+export function normalizeContent(content: MessageContent): MessageSegment[] {
+  if (typeof content === 'string') {
+    return content ? [{ type: 'text', text: content }] : []
+  }
+  return content
+}
+
+// ========== SSE event data shapes (wire shapes) ==========
+
+export interface TextEventData {
+  type: 'TEXT'
+  text: string
+}
+
+export interface ToolExecutionEventData {
+  type: 'EXECUTING_TOOL' | 'EXECUTED_TOOL'
+  integratedToolType: string
+  toolFunction: string
+  parameters?: Record<string, any>
+  result?: string
+  success?: boolean
+}
+
+export type SSEEventData = TextEventData | ToolExecutionEventData
+
+// ========== Quick-action chip shape ==========
+
+export interface QuickAction {
+  id: string
+  text: string
+}