@flamingo-stack/openframe-frontend-core 0.0.429 → 0.0.430

package/src/components/chat/hooks/use-scripted-stream.ts

@@ -0,0 +1,69 @@
+'use client'
+
+/**
+ * Playback clock for {@link buildStreamFrames}: advance through pre-built
+ * scripted frames like a live chat stream — each frame holds for its own
+ * `delayMs`, then the next reveals, parking on the last. Surface-agnostic: the
+ * caller maps `frame.messages` to its own chat shape and reads `frame.phase` /
+ * `frame.typing`.
+ *
+ * `resetKey` restarts playback from the top when a NEW conversation is selected
+ * (identity change) — NOT when the SAME conversation grows (e.g. an Approve
+ * appends its continuation), which must resume from where it paused. Because the
+ * frame list's shared prefix is deterministic, keeping the index across a grow
+ * resumes seamlessly into the appended frames.
+ *
+ * `prefers-reduced-motion` (or `enabled === false`) jumps straight to the final
+ * frame (everything revealed, idle).
+ */
+
+import { useEffect, useState } from 'react'
+import type { StreamFrame } from '../utils/scripted-stream'
+
+const EMPTY_FRAME: StreamFrame = { messages: [], phase: 'idle', typing: false, delayMs: 0 }
+
+function prefersReducedMotion(): boolean {
+  return typeof window !== 'undefined' && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches === true
+}
+
+export function useScriptedStream(frames: StreamFrame[], resetKey: unknown, enabled = true): StreamFrame {
+  const [index, setIndex] = useState(0)
+  const [reducedMotion, setReducedMotion] = useState(false)
+
+  // Restart from the top on a new conversation, synchronously during render
+  // (React's "adjust state on prop change" pattern) so the previous stream's
+  // last frame never flashes before the reset effect runs.
+  const [prevKey, setPrevKey] = useState(resetKey)
+  if (resetKey !== prevKey) {
+    setPrevKey(resetKey)
+    setIndex(0)
+  }
+
+  useEffect(() => {
+    setReducedMotion(prefersReducedMotion())
+    const mq = window.matchMedia?.('(prefers-reduced-motion: reduce)')
+    if (!mq) return
+    const onChange = () => setReducedMotion(mq.matches)
+    mq.addEventListener('change', onChange)
+    return () => mq.removeEventListener('change', onChange)
+  }, [])
+
+  const playing = enabled && !reducedMotion && frames.length > 0
+  const lastIndex = Math.max(0, frames.length - 1)
+
+  // Advance one frame after the current frame's hold. When `frames` grows (an
+  // Approve appends more), this effect re-runs and, if we were parked on the old
+  // last frame, schedules the next — resuming the stream. `frames[index]` is
+  // clamped because a shrink (a shorter new conversation before the reset lands)
+  // could momentarily leave `index` past the end.
+  useEffect(() => {
+    if (!playing || index >= lastIndex) return
+    const current = frames[Math.min(index, lastIndex)] ?? EMPTY_FRAME
+    const t = setTimeout(() => setIndex((i) => Math.min(i + 1, lastIndex)), current.delayMs)
+    return () => clearTimeout(t)
+  }, [index, frames, playing, lastIndex])
+
+  if (frames.length === 0) return EMPTY_FRAME
+  if (!playing) return frames[lastIndex]
+  return frames[Math.min(index, lastIndex)] ?? EMPTY_FRAME
+}

package/src/components/chat/utils/index.ts

@@ -198,3 +198,5 @@ export {
   resolveSourceRowCTA,
   resolveSourceIcon,
 } from './source-row-cta'
+
+export * from './scripted-stream'

package/src/components/chat/utils/scripted-stream.ts

@@ -0,0 +1,111 @@
+/**
+ * Scripted-conversation replay — turn a stored `HistoricalMessage[]` into ordered
+ * "mock SSE" playback frames that animate a chat surface exactly like the live
+ * NATS/SSE stream (a `thinking` pause → assistant text token-by-token → tool /
+ * approval segments popping in → `idle`), just replayed from a script instead of
+ * a network stream.
+ *
+ * Lives in the lib (not a host) so any consumer — marketing hero demos, docs,
+ * onboarding tours — can drive a `previewMode` `EmbeddableChat` or a
+ * `ChatMessageList` from a canned conversation without re-implementing the
+ * streaming cadence. Pair with {@link useScriptedStream} (the playback clock).
+ */
+
+import type { HistoricalMessage, MessageData, StreamingPhase } from '../types'
+
+/** Normalize the single-or-array `messageData` to an array (empty when absent). */
+export function normalizeHistoricalMessageData(md: HistoricalMessage['messageData']): MessageData[] {
+  return Array.isArray(md) ? md : md ? [md] : []
+}
+
+/** A message the user authored carries an `owner`; assistant turns have none —
+ *  drives whether a turn streams (assistant) or lands at once (user). */
+export function isHistoricalUserTurn(m: HistoricalMessage): boolean {
+  return !!m.owner
+}
+
+const isTextSegment = (d: MessageData): d is MessageData & { type: 'TEXT'; text: string } =>
+  (d as { type?: string })?.type === 'TEXT' && typeof (d as { text?: unknown }).text === 'string'
+
+/** One rendered step of the mocked stream. */
+export interface StreamFrame {
+  /** The partial message list to show at this step. */
+  messages: HistoricalMessage[]
+  phase: StreamingPhase
+  /** The chat "typing" indicator (up during the `thinking` pause). */
+  typing: boolean
+  /** Hold time (ms) before advancing to the next frame. */
+  delayMs: number
+}
+
+// Playback cadence. Assistant turns "think" then stream token-by-token; user
+// turns land at once. Tuned to read like a real chat without dragging.
+const THINK_MS = 550
+const TOKEN_MS = 55 // per word revealed while streaming text
+const USER_MS = 480 // dwell on a user turn before the reply starts thinking
+const SEGMENT_MS = 340 // a tool / approval card pops in
+const POST_MS = 240 // dwell after a completed assistant turn
+
+/** Split text into tokens that KEEP surrounding whitespace, so re-joining a
+ *  prefix reproduces the original spacing exactly (`"a b"` → `["a ", "b"]`). */
+function tokenize(text: string): string[] {
+  return text.match(/\s*\S+\s*/g) ?? (text ? [text] : [])
+}
+
+/**
+ * Expand a message list into ordered playback frames reproducing the live
+ * stream: each user turn lands whole; each assistant turn first shows a
+ * `thinking` indicator, then streams its text token-by-token, then pops any
+ * tool / approval segments. Frame COUNT for a given prefix is deterministic, so
+ * a host that appends a continuation (e.g. after an Approve) resumes seamlessly
+ * from where it paused — the shared prefix's frames are unchanged.
+ */
+export function buildStreamFrames(messages: HistoricalMessage[]): StreamFrame[] {
+  const frames: StreamFrame[] = []
+  const revealed: HistoricalMessage[] = []
+  const push = (msgs: HistoricalMessage[], phase: StreamingPhase, typing: boolean, delayMs: number) =>
+    frames.push({ messages: msgs.slice(), phase, typing, delayMs })
+
+  messages.forEach((msg) => {
+    if (isHistoricalUserTurn(msg)) {
+      revealed.push(msg)
+      push(revealed, 'idle', false, USER_MS)
+      return
+    }
+
+    // Assistant turn: a `thinking` pause, then stream this turn's segments in
+    // order. The pause is emitted ONLY when there is already content to show
+    // (`revealed.length > 0`) — an empty first frame would hand the surface a
+    // zero-message list, flashing its empty state before the opening line.
+    if (revealed.length > 0) push(revealed, 'thinking', true, THINK_MS)
+
+    const segs = normalizeHistoricalMessageData(msg.messageData)
+    const built: MessageData[] = []
+    const emit = () => push([...revealed, { ...msg, messageData: [...built] }], 'streaming', false, 0)
+
+    segs.forEach((seg) => {
+      if (isTextSegment(seg)) {
+        const tokens = tokenize(seg.text)
+        let acc = ''
+        built.push({ ...seg, text: '' })
+        tokens.forEach((tok) => {
+          acc += tok
+          built[built.length - 1] = { ...seg, text: acc }
+          push([...revealed, { ...msg, messageData: [...built] }], 'streaming', false, TOKEN_MS)
+        })
+        built[built.length - 1] = { ...seg }
+      } else {
+        // Tool / approval segment: pops in fully.
+        built.push(seg)
+        emit()
+        frames[frames.length - 1].delayMs = SEGMENT_MS
+      }
+    })
+
+    revealed.push(msg)
+    push(revealed, 'idle', false, POST_MS)
+  })
+
+  if (frames.length === 0) push(revealed, 'idle', false, 0)
+  return frames
+}

package/src/components/features/board/index.ts

@@ -6,8 +6,8 @@ export { BoardColumn } from './board-column'
 export type { BoardColumnProps } from './board-column'
 export { BoardColumnHeader } from './board-column-header'
 export type { BoardColumnHeaderProps } from './board-column-header'
-export { TicketCard } from './ticket-card'
-export type { TicketCardProps } from './ticket-card'
+export { TicketCard, TicketCardView, TicketCardBody } from './ticket-card'
+export type { TicketCardProps, TicketCardViewProps, TicketCardBodyProps } from './ticket-card'
 export { BoardTicketApproval } from './board-ticket-approval'
 export type { BoardTicketApprovalProps } from './board-ticket-approval'
 export { TicketCardSkeleton } from './ticket-card-skeleton'

package/src/components/features/board/ticket-card.tsx

@@ -4,7 +4,7 @@ import { useSortable } from '@dnd-kit/sortable'
 import { CSS } from '@dnd-kit/utilities'
 import Link from '../../../embed-shims/next-link'
 import * as React from 'react'
-import { LaptopIcon, Flag02Icon, MessagesIcon, CheckCircleIcon } from '../../icons-v2-generated'
+import { LaptopIcon, Flag02Icon, MessagesIcon } from '../../icons-v2-generated'
 import { SquareAvatar } from '../../ui/square-avatar'
 import { Tag } from '../../ui/tag'
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../../ui/tooltip'
@@ -24,64 +24,36 @@ const PRIORITY_COLOR_CLASS: Record<BoardPriority, string> = {
 const MAX_VISIBLE_TAGS = 2
 const MAX_VISIBLE_ASSIGNEES = 3
 
-export interface TicketCardProps {
+/** Shared card shell (border / padding / bg). Same footprint for the draggable
+ *  board card and the static {@link TicketCardView}. */
+const TICKET_CARD_SHELL =
+  'relative flex flex-col gap-[var(--spacing-system-sf)] rounded-md border border-ods-border bg-ods-bg p-[var(--spacing-system-sf)] select-none text-left'
+
+// =============================================================================
+// Presentational body — the ONE ticket-card design, no drag/link/board context.
+// Reused by the draggable `TicketCard` AND the static `TicketCardView`.
+// =============================================================================
+
+export interface TicketCardBodyProps {
   ticket: BoardTicket
-  columnId: string
   columnColor?: string
-  href?: string
-  isOverlay?: boolean
-  dragDisabled?: boolean
-  approved?: boolean
   renderAssignSlot?: (ticket: BoardTicket) => React.ReactNode
-  onApprove?: (ticketId: string, requestId?: string) => void | Promise<void>
-  onReject?: (ticketId: string, requestId?: string) => void | Promise<void>
+  /** Approval callbacks receive the request id directly (the draggable
+   *  `TicketCard` adapts its own `(ticketId, requestId)` signature onto these). */
+  onApprove?: (requestId?: string) => void | Promise<void>
+  onReject?: (requestId?: string) => void | Promise<void>
 }
 
-export function TicketCard({
-  ticket,
-  columnId,
-  columnColor,
-  href,
-  isOverlay = false,
-  dragDisabled,
-  approved = false,
-  renderAssignSlot,
-  onApprove,
-  onReject,
-}: TicketCardProps) {
-  const sortableData = React.useMemo(
-    () => ({ columnId, type: 'ticket' as const }),
-    [columnId],
-  )
-  const sortable = useSortable({
-    id: ticket.id,
-    data: sortableData,
-    disabled: dragDisabled,
-  })
-
+/** The card's inner content: title + device/org, priority + assignees, tags,
+ *  timestamp, "New Message", and the approval row. Pure — driven only by props. */
+export function TicketCardBody({ ticket, columnColor, renderAssignSlot, onApprove, onReject }: TicketCardBodyProps) {
   const showNewMessage = !!ticket.hasNewMessage && !!columnColor
   const newMessageTextColor = columnColor ? getReadableTextColor(columnColor) : undefined
 
-  const style: React.CSSProperties = isOverlay
-    ? {}
-    : {
-        transform: CSS.Transform.toString(sortable.transform),
-        transition: sortable.transition,
-      }
-  if (showNewMessage) style.borderColor = columnColor
-
   const showDeviceRow = !!(ticket.deviceHostnames?.length || ticket.organizationName)
-  const deviceText = [
-    ticket.deviceHostnames?.join(', '),
-    ticket.organizationName,
-  ].filter(Boolean).join(', ')
-
-  const handleClick = (e: React.MouseEvent) => {
-    if (sortable.isDragging) e.preventDefault()
-  }
-
-  const hasRightSection = !!(approved || ticket.priority || ticket.assignees?.length || renderAssignSlot)
+  const deviceText = [ticket.deviceHostnames?.join(', '), ticket.organizationName].filter(Boolean).join(', ')
 
+  const hasRightSection = !!(ticket.priority || ticket.assignees?.length || renderAssignSlot)
   const rightSection = hasRightSection ? (
     <div className="pointer-events-auto flex shrink-0 items-center gap-[var(--spacing-system-xsf)]">
       {ticket.priority && (
@@ -90,14 +62,6 @@ export function TicketCard({
           aria-label={`Priority: ${ticket.priority}`}
         />
       )}
-      {approved && (
-        <CheckCircleIcon
-          size={20}
-          color="var(--ods-attention-green-success)"
-          className="shrink-0"
-          aria-label="Approved"
-        />
-      )}
       {renderAssignSlot ? (
         renderAssignSlot(ticket)
       ) : ticket.assignees?.length ? (
@@ -125,7 +89,7 @@ export function TicketCard({
   const timestampLabel = ticket.createdAt ? formatTicketRelativeTime(ticket.createdAt) : null
   const tooltipLabel = ticket.createdAt ? formatTicketFullTimestamp(ticket.createdAt) : null
 
-  const body = (
+  return (
     <>
       <div className="flex items-start gap-[var(--spacing-system-sf)]">
         <div className="flex min-w-0 flex-1 flex-col gap-[var(--spacing-system-zero)]" title={ticket.title}>
@@ -159,17 +123,97 @@ export function TicketCard({
         />
       )}
       {ticket.pendingApproval && (
-        <BoardTicketApproval
-          pendingApproval={ticket.pendingApproval}
-          onApprove={onApprove ? requestId => onApprove(ticket.id, requestId) : undefined}
-          onReject={onReject ? requestId => onReject(ticket.id, requestId) : undefined}
-        />
+        <BoardTicketApproval pendingApproval={ticket.pendingApproval} onApprove={onApprove} onReject={onReject} />
       )}
     </>
   )
+}
+
+// =============================================================================
+// Static card — the real board card design, rendered from props with NO
+// drag-and-drop / board context (for embeds, marketing heroes, previews).
+// =============================================================================
+
+export interface TicketCardViewProps extends TicketCardBodyProps {
+  className?: string
+}
+
+/**
+ * The exact board `TicketCard` visual, standalone — same shell + `TicketCardBody`
+ * as the draggable card, but without the `useSortable` dnd-kit dependency, so it
+ * renders anywhere from static props. Use this outside a `<Board>`.
+ */
+export function TicketCardView({ className, ...bodyProps }: TicketCardViewProps) {
+  const { ticket, columnColor } = bodyProps
+  const showNewMessage = !!ticket.hasNewMessage && !!columnColor
+  return (
+    <div
+      className={cn(TICKET_CARD_SHELL, className)}
+      style={showNewMessage ? { borderColor: columnColor } : undefined}
+    >
+      <div className="relative z-10 flex flex-col gap-[var(--spacing-system-sf)]">
+        <TicketCardBody {...bodyProps} />
+      </div>
+    </div>
+  )
+}
+
+// =============================================================================
+// Draggable board card
+// =============================================================================
+
+export interface TicketCardProps {
+  ticket: BoardTicket
+  columnId: string
+  columnColor?: string
+  href?: string
+  isOverlay?: boolean
+  dragDisabled?: boolean
+  renderAssignSlot?: (ticket: BoardTicket) => React.ReactNode
+  onApprove?: (ticketId: string, requestId?: string) => void | Promise<void>
+  onReject?: (ticketId: string, requestId?: string) => void | Promise<void>
+}
+
+export function TicketCard({
+  ticket,
+  columnId,
+  columnColor,
+  href,
+  isOverlay = false,
+  dragDisabled,
+  renderAssignSlot,
+  onApprove,
+  onReject,
+}: TicketCardProps) {
+  const sortableData = React.useMemo(() => ({ columnId, type: 'ticket' as const }), [columnId])
+  const sortable = useSortable({ id: ticket.id, data: sortableData, disabled: dragDisabled })
+
+  const showNewMessage = !!ticket.hasNewMessage && !!columnColor
+
+  const style: React.CSSProperties = isOverlay
+    ? {}
+    : {
+        transform: CSS.Transform.toString(sortable.transform),
+        transition: sortable.transition,
+      }
+  if (showNewMessage) style.borderColor = columnColor
+
+  const handleClick = (e: React.MouseEvent) => {
+    if (sortable.isDragging) e.preventDefault()
+  }
+
+  const body = (
+    <TicketCardBody
+      ticket={ticket}
+      columnColor={columnColor}
+      renderAssignSlot={renderAssignSlot}
+      onApprove={onApprove ? requestId => onApprove(ticket.id, requestId) : undefined}
+      onReject={onReject ? requestId => onReject(ticket.id, requestId) : undefined}
+    />
+  )
 
   const cardClasses = cn(
-    'relative flex flex-col gap-[var(--spacing-system-sf)] rounded-md border border-ods-border bg-ods-bg p-[var(--spacing-system-sf)] select-none text-left',
+    TICKET_CARD_SHELL,
     !dragDisabled && 'cursor-pointer',
     sortable.isDragging && !isOverlay && 'opacity-40',
     isOverlay && 'rotate-1 shadow-card-hover',