@flamingo-stack/openframe-frontend-core 0.0.216 → 0.0.217

package/src/components/shared/dev-section/dev-card-row.tsx

@@ -18,15 +18,14 @@
  * Pair with `DevCardRowSkeletonList` for the loading state — the
  * skeleton mirrors the same min-heights so the in-flight UI doesn't
  * shift the layout when real data lands.
+ *
+ * NOTE: the ticket conversation row is NOT here — it renders the shared
+ * `<ChatMessageRow>` (`components/chat/chat-message-row.tsx`), the SAME
+ * component the OpenMSP Slack-community feed uses, so the two surfaces stay
+ * pixel-identical by construction.
  */
 
 import type { ReactNode } from 'react';
-import { SquareAvatar } from '../../ui/square-avatar';
-import {
-  TicketAttachmentsList,
-  type TicketAttachment,
-} from '../../ui/ticket-attachments-list';
-import { formatRelativeTime } from '../../../utils/date-utils';
 
 export interface DevCardRowContentProps {
   title: string;
@@ -74,183 +73,6 @@ export function DevCardRowContent({
   );
 }
 
-// ────────────────────────────────────────────────────────────────────────────
-// ConversationCardRow — sibling row variant for thread-style conversation
-// surfaces (ticket detail drawer, future inbox replies, etc.). Shares the
-// outer chrome (`border-b last:border-b-0 p-[12px] md:p-[16px]`) with
-// `DevCardRowContent` so a list mixing both variants stays visually
-// coherent. Internal layout differs because the data shape is different:
-// instead of title/subtitle/description + right-stacked badges, a
-// conversation message has an author (avatar + name + role + timestamp)
-// and a free-form body that should NOT be line-clamped, plus optional
-// attachments rendered via the shared `<TicketAttachmentsList>` so
-// download UX is identical to any other attachments surface in the lib.
-//
-// 2026 conversation-UI best practices applied (UXPin / Salesforce UX /
-// Coveo support-ticket research):
-//   - Author identity visible on every turn (avatar + name + role chip)
-//   - Threaded single-side layout — best for async business support,
-//     not alternating bubbles
-//   - Relative timestamp right-aligned, absolute on hover (`title` attr)
-//   - Body uses `whitespace-pre-wrap break-words` so multi-line replies
-//     and long URLs render without clipping
-//   - WCAG 2.2 contrast + 44×44 touch targets enforced by the shared
-//     `<TicketAttachmentsList>` download button
-// ────────────────────────────────────────────────────────────────────────────
-
-export interface ConversationCardRowProps {
-  /** Display name of the message author. "You" for the current customer,
-   *  "Support team" for any non-customer engagement. */
-  author: string;
-  /** Optional short role label rendered as an inline chip beside the
-   *  author name — e.g. "You", "Original message", "Resolution". Keeps
-   *  the header line scannable on long threads. */
-  role?: string;
-  /** Avatar image URL. Falls back to `author` initials when missing
-   *  (initials derived by `<SquareAvatar>` via `getFirstLastInitials`). */
-  avatarSrc?: string;
-  /** ISO timestamp. Renders via `formatRelativeTime` with the absolute
-   *  string in the `title` for hover-precision. `null`/`undefined`
-   *  hides the timestamp entirely (e.g. the original ticket body which
-   *  shares the ticket's `created_at`). */
-  timestamp?: string | null;
-  /** Free-form message body. Empty string + zero attachments renders
-   *  nothing (the row is skipped at the caller level). */
-  body: string;
-  /** Files attached to this message. Rendered through the lib's
-   *  `<TicketAttachmentsList>` so the chip styling, file-icon picker
-   *  and download button match every other attachments surface. */
-  attachments?: TicketAttachment[];
-  /** Author bucket — kept for semantic markup + future styling needs.
-   *  Does NOT drive avatar color anymore: the avatar always renders
-   *  with the canonical `<SquareAvatar>` defaults (ODS palette,
-   *  derived by the component itself). Adding bespoke bg-color
-   *  overrides per role drifted from the ODS theme and was reverted. */
-  variant?: 'current-user' | 'support';
-}
-
-export function ConversationCardRow({
-  author,
-  role,
-  avatarSrc,
-  timestamp,
-  body,
-  attachments,
-  variant = 'support',
-}: ConversationCardRowProps) {
-  const hasBody = body.trim().length > 0;
-  const hasAttachments = !!attachments && attachments.length > 0;
-  if (!hasBody && !hasAttachments) return null;
-
-  const relativeTime = timestamp ? formatRelativeTime(timestamp) : null;
-
-  return (
-    <article
-      className="border-b border-ods-border last:border-b-0 p-[12px] md:p-[16px] flex gap-[12px] md:gap-[16px] w-full"
-      aria-label={`${author}${relativeTime ? ` · ${relativeTime}` : ''}`}
-    >
-      {/* Avatar — canonical `<SquareAvatar>` with NO className override.
-          Color, border, and fallback styling all come from the ODS
-          theme defaults (`bg-ods-bg` + `border-ods-border` +
-          `text-ods-text-primary`). Per-role bespoke colors
-          (bg-ods-flamingo-pink for customer / bg-ods-flamingo-cyan
-          for support) were tried + reverted — they drifted from the
-          standard theme and broke parity with other surfaces that
-          use SquareAvatar without overrides (assignee-dropdown,
-          ticket-info-section). */}
-      <SquareAvatar
-        src={avatarSrc}
-        alt={author}
-        fallback={author}
-        size="sm"
-        variant="round"
-      />
-
-      <div className="flex-1 min-w-0 flex flex-col gap-[8px] md:gap-[12px]">
-        {/* Header row — author + optional role chip on the left,
-            relative time on the right. The header collapses cleanly on
-            narrow viewports by wrapping. */}
-        <div className="flex items-baseline justify-between gap-[8px] flex-wrap">
-          <div className="flex items-baseline gap-[8px] min-w-0">
-            <h3 className="text-h4 text-ods-text-primary truncate">{author}</h3>
-            {role && (
-              <span className="text-h6 text-ods-text-secondary uppercase tracking-[-0.28px] shrink-0">
-                {role}
-              </span>
-            )}
-          </div>
-          {relativeTime && (
-            <time
-              className="text-h6 text-ods-text-secondary uppercase tracking-[-0.28px] shrink-0"
-              dateTime={timestamp ?? undefined}
-              title={timestamp ?? undefined}
-            >
-              {relativeTime}
-            </time>
-          )}
-        </div>
-
-        {/* Body — full message, no line-clamp. `pre-wrap` preserves
-            authored line breaks; `break-words` handles long URLs. */}
-        {hasBody && (
-          <p className="text-h4 text-ods-text-primary whitespace-pre-wrap break-words">
-            {body}
-          </p>
-        )}
-
-        {/* Attachments — delegated to the canonical lib component so
-            every file-attachment surface (chat, drawer, future inbox)
-            shares the same chip styling + download UX. */}
-        {hasAttachments && <TicketAttachmentsList attachments={attachments!} />}
-      </div>
-    </article>
-  );
-}
-
-/**
- * Skeleton variant matching `ConversationCardRow`'s layout. Used by
- * the ticket-detail-drawer's timeline panel while engagements load —
- * mirrors avatar + header + body so the loading→loaded swap doesn't
- * reshape the row vertically.
- */
-export function ConversationCardRowSkeleton() {
-  return (
-    <div className="border-b border-ods-border last:border-b-0 p-[12px] md:p-[16px] flex gap-[12px] md:gap-[16px] w-full">
-      {/* Avatar — matches SquareAvatar size="sm" (32px) used by the
-          real row. Round to match `variant="round"`. */}
-      <div className="h-8 w-8 shrink-0 rounded-full bg-ods-border animate-pulse" />
-      <div className="flex-1 min-w-0 flex flex-col gap-[8px] md:gap-[12px]">
-        {/* Header row — author + role chip + timestamp placeholders. */}
-        <div className="flex items-baseline justify-between gap-[8px]">
-          <div className="flex items-baseline gap-[8px] flex-1">
-            <div className="h-[24px] w-32 bg-ods-border rounded animate-pulse" />
-            <div className="h-[20px] w-16 bg-ods-border rounded animate-pulse" />
-          </div>
-          <div className="h-[20px] w-20 bg-ods-border rounded animate-pulse shrink-0" />
-        </div>
-        {/* Body — two-line placeholder. */}
-        <div className="space-y-2">
-          <div className="h-[20px] w-full bg-ods-border rounded animate-pulse" />
-          <div className="h-[20px] w-3/4 bg-ods-border rounded animate-pulse" />
-        </div>
-      </div>
-    </div>
-  );
-}
-
-/** Multi-row skeleton list — drop-in for the conversation timeline's
- *  loading state. Defaults to 2 rows so the placeholder fits in a
- *  reasonable vertical footprint without dominating the drawer. */
-export function ConversationCardRowSkeletonList({ rows = 2 }: { rows?: number }) {
-  return (
-    <div className="bg-ods-card border border-ods-border rounded-[6px] overflow-hidden w-full">
-      {Array.from({ length: rows }, (_, i) => (
-        <ConversationCardRowSkeleton key={i} />
-      ))}
-    </div>
-  );
-}
-
 /**
  * Skeleton rendering for a single row — the bars mirror the same
  * min-heights as `DevCardRowContent` so the loading→loaded swap

package/src/components/shared/legal-document/use-legal-docs.ts

@@ -86,7 +86,11 @@ export function useLegalDocs(
       setData(result);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : 'Unknown error occurred';
-      console.error(`Error fetching ${docType} document:`, err);
+      // `docType` is externally controlled (URL path segment in embedders), so it must NOT sit in
+      // console.error's FIRST (format-string) argument — Node interprets %s/%j/%o there
+      // (CodeQL js/tainted-format-string). Keep the format string constant; pass docType + err as
+      // plain trailing args.
+      console.error('Error fetching legal document:', docType, err);
       setError(errorMessage);
     } finally {
       setIsLoading(false);

package/src/components/tickets/help-center-card.tsx

@@ -15,7 +15,7 @@
  * is a SIBLING of the toggle button, not nested inside it.
  */
 
-import { useCallback, useRef } from 'react'
+import { useCallback, useEffect, useRef } from 'react'
 import { StatusBadge, type StatusBadgeProps } from '../ui'
 import { formatRelativeTime } from '../../utils/date-utils'
 import { scrollElementIntoView } from '../../utils/scroll-into-view'
@@ -97,39 +97,36 @@ export function HelpCenterCard({
   const isExpandable = !optimistic
   const isExpanded = expanded && isExpandable
 
-  // Scroll-on-click — delegates to the canonical `scrollElementIntoView`
-  // helper with a cross-row layout-shift `adjustTargetY` callback. The
-  // helper owns the smooth-scroll mechanics + sticky-chrome offset; we
-  // pass the consumer-specific knowledge ("a sibling drawer above me
-  // is about to collapse — subtract its height from the target Y").
-  //
-  // Cross-row gotcha: if ANOTHER row above this one is currently
-  // expanded, its drawer collapses simultaneously with our toggle.
-  // The collapse shrinks the page above our row → our final Y is
-  // HIGHER than the current `rect.top`. By pre-subtracting the
-  // collapsing drawer's height we land at the post-shift position
-  // cleanly, without scrollIntoView's mid-animation drift.
   const rowRef = useRef<HTMLDivElement | null>(null)
+  // Click only toggles — the scroll-to-top is deferred to the effect below.
   const handleClick = useCallback(() => {
     onToggle(ticket.id)
-    scrollElementIntoView(rowRef.current, {
-      headerOffset: STICKY_HEADER_OFFSET_PX,
-      adjustTargetY: (raw) => {
-        if (!rowRef.current) return raw
-        const expandedDrawer = document.querySelector(
-          'div[id^="help-center-drawer-"]',
-        )
-        if (!(expandedDrawer instanceof HTMLElement)) return raw
-        const drawerRect = expandedDrawer.getBoundingClientRect()
-        const myRect = rowRef.current.getBoundingClientRect()
-        // Only adjust when the drawer is ABOVE us. Drawers below us
-        // don't shift our position when they collapse.
-        if (drawerRect.bottom > myRect.top) return raw
-        return raw - drawerRect.height
-      },
-    })
   }, [onToggle, ticket.id])
 
+  // Smooth-scroll the row to the top once the drawer has expanded — in an
+  // effect keyed on `isExpanded` (NOT the click handler, which runs before
+  // React commits the drawer, when the page isn't yet tall enough to scroll).
+  //
+  // The cancellation-proof motion lives in the shared `scrollElementIntoView`
+  // helper (self-driven rAF tween, instant per-frame writes, target recomputed
+  // each frame). It is immune to the browser SCROLL ANCHORING that cancelled the
+  // old native `window.scrollTo({behavior:'smooth'})` on every open after the
+  // first — the bug where smooth "only worked once" because anchoring is
+  // suppressed at scrollY=0 (first open) but aborts the native smooth scroll
+  // from any non-zero offset (every later open). See that util for the full
+  // mechanics. One leading rAF so the expanded drawer has committed its height
+  // before the first measurement; the tween then tracks the row to its resting
+  // position as the page finishes growing. Cleanup cancels on collapse/unmount.
+  useEffect(() => {
+    if (!isExpanded) return
+    const raf = requestAnimationFrame(() => {
+      scrollElementIntoView(rowRef.current, {
+        headerOffset: STICKY_HEADER_OFFSET_PX,
+      })
+    })
+    return () => cancelAnimationFrame(raf)
+  }, [isExpanded])
+
   const rightBadges = (
     <>
       <StatusBadge

package/src/components/tickets/help-center-list.tsx

@@ -41,7 +41,7 @@ import { useTicketActions } from './hooks/use-ticket-actions'
 import { HelpCenterCard } from './help-center-card'
 import { HelpCenterCreateForm, HelpCenterCreateFormSkeleton } from './help-center-create-form'
 import type { AnyTicket, OptimisticTicket, TicketsCacheSlot } from './types'
-import { isOptimistic } from './types'
+import { isOptimistic, TICKET_LIVE_POLL_MS } from './types'
 
 export interface HelpCenterListProps {
   /** Toast override (test-friendly). Defaults to the lib's shared
@@ -57,6 +57,10 @@ export function HelpCenterList({ toast = defaultToast }: HelpCenterListProps = {
 
   const search = searchParams.get('search') || ''
   const status = searchParams.get('status') || 'all'
+  // Deep-link: `?ticket=<external_id>` auto-opens that ticket's drawer on load.
+  // Same GET-param plumbing as `?search=` — read here, drilled to the authed
+  // child which expands the matching row once it's in the fetched list.
+  const ticketParam = searchParams.get('ticket') || ''
   // 1-based page from the URL. `<UnifiedPagination>` writes `?page=N`
   // on navigation; we read it here and re-fetch on change. Invalid
   // values fall back to page 1.
@@ -108,6 +112,7 @@ export function HelpCenterList({ toast = defaultToast }: HelpCenterListProps = {
       search={search}
       status={status}
       page={page}
+      ticketParam={ticketParam}
       searchParams={searchParams}
       router={router}
       pathname={pathname}
@@ -122,6 +127,8 @@ interface AuthedProps {
   search: string
   status: string
   page: number
+  /** `?ticket=<external_id>` deep-link target — auto-opens that drawer. */
+  ticketParam: string
   searchParams: ReturnType<typeof useSearchParams>
   router: ReturnType<typeof useRouter>
   pathname: string
@@ -134,6 +141,7 @@ function HelpCenterListAuthed({
   search,
   status,
   page,
+  ticketParam,
   searchParams,
   router,
   pathname,
@@ -142,6 +150,26 @@ function HelpCenterListAuthed({
   sessionEmail,
 }: AuthedProps) {
   const queryClient = useQueryClient()
+  const [optimisticTickets, setOptimisticTickets] = useState<OptimisticTicket[]>([])
+  const [supportSystemDown, setSupportSystemDown] = useState(false)
+
+  // SINGLE source of truth for "which ticket is open" = the `?ticket=<external_id>`
+  // URL param (same model as `?search=` / `?status=`). Click-to-open and the
+  // deep-link path are now ONE code path: a click writes the param, the drawer's
+  // open state is DERIVED from the param. No separate `expandedTicketId` state,
+  // no auto-open effect, no re-open guard — opening, closing, deep-linking, and
+  // sharing a URL all flow through the same param.
+  const setOpenTicket = useCallback(
+    (externalId: string | null) => {
+      const params = new URLSearchParams(searchParams.toString())
+      if (externalId) params.set('ticket', externalId)
+      else params.delete('ticket')
+      const qs = params.toString()
+      router.replace(qs ? `${pathname}?${qs}` : pathname, { scroll: false })
+    },
+    [searchParams, router, pathname],
+  )
+
   const { tickets, isLoading, isFetching, error, refetch, totalPages } = useTicketsList({
     // `sessionEmail` is drilled in from the parent — see the same
     // pattern + race-cause rationale documented in
@@ -153,11 +181,19 @@ function HelpCenterListAuthed({
     search,
     status,
     page,
+    // Live status: while a drawer is open, poll so an out-of-band HubSpot
+    // status change (e.g. agent closes the ticket) flips the badge +
+    // open/reopen affordance within one interval. Idle (no drawer) → no poll.
+    // `ticketParam` (the open ticket's external_id) is the open signal.
+    refetchInterval: ticketParam ? TICKET_LIVE_POLL_MS : false,
   })
 
-  const [optimisticTickets, setOptimisticTickets] = useState<OptimisticTicket[]>([])
-  const [expandedTicketId, setExpandedTicketId] = useState<string | null>(null)
-  const [supportSystemDown, setSupportSystemDown] = useState(false)
+  // Open state DERIVED from the URL param. `?ticket=` carries the user-facing
+  // `external_id`; map it to the internal row id the card matches on. Resolves
+  // to null until the ticket lands in the fetched list (deep-link cold load) and
+  // auto-collapses if the open ticket disappears (e.g. TICKET_NOT_FOUND removal).
+  const expandedTicketId =
+    (ticketParam && tickets.find((t) => t.external_id === ticketParam)?.id) || null
 
   // Optimistic cache management. Kept LOCAL (not in the query cache) so
   // a refetch (e.g. URL-filter change) doesn't blow away pending
@@ -168,7 +204,8 @@ function HelpCenterListAuthed({
   }, [])
   const removeOptimistic = useCallback((placeholderId: string) => {
     setOptimisticTickets((prev) => prev.filter((t) => t.id !== placeholderId))
-    setExpandedTicketId((prev) => (prev === placeholderId ? null : prev))
+    // No drawer-collapse needed: optimistic placeholders have no `external_id`,
+    // so they can never be the URL-derived open ticket.
   }, [])
   const removeTicketFromCache = useCallback(
     (ticketId: string) => {
@@ -191,7 +228,8 @@ function HelpCenterListAuthed({
           return { ...prev, tickets: nextTickets }
         },
       )
-      setExpandedTicketId((prev) => (prev === ticketId ? null : prev))
+      // The drawer auto-collapses on its own: once the ticket leaves the list,
+      // the URL-derived `expandedTicketId` finds no match → null. No state to clear.
     },
     [queryClient],
   )
@@ -204,9 +242,18 @@ function HelpCenterListAuthed({
     onSupportSystemDown: () => setSupportSystemDown(true),
   })
 
-  const toggleRow = useCallback((id: string) => {
-    setExpandedTicketId((prev) => (prev === id ? null : id))
-  }, [])
+  // Toggle = write the URL param (open) or clear it (close). The clicked card's
+  // internal id maps to its `external_id` for the param; optimistic rows (no
+  // external_id) aren't expandable so they short-circuit. This is the ONE open
+  // path — a click, a deep link, and a shared URL are indistinguishable.
+  const toggleRow = useCallback(
+    (id: string) => {
+      const t = tickets.find((x) => x.id === id)
+      if (!t?.external_id) return
+      setOpenTicket(t.external_id === ticketParam ? null : t.external_id)
+    },
+    [tickets, ticketParam, setOpenTicket],
+  )
 
   const merged: AnyTicket[] = [...optimisticTickets, ...tickets]
   const hasActiveFilters = search !== '' || (status !== '' && status !== 'all')
@@ -296,7 +343,7 @@ function HelpCenterListAuthed({
                   onSendMessage={actions.sendMessage}
                   onClose={actions.closeTicket}
                   onReopen={actions.reopenTicket}
-                  onActionCollapsed={() => setExpandedTicketId(null)}
+                  onActionCollapsed={() => setOpenTicket(null)}
                   replyError={actions.replyErrorFor(ticket.external_id)}
                   onClearReplyError={() => actions.clearReplyError(ticket.external_id)}
                 />

package/src/components/tickets/hooks/use-ticket-engagements.ts

@@ -73,7 +73,18 @@ export interface UseTicketEngagementsReturn {
   refetch: () => void
 }
 
-export function useTicketEngagements(externalTicketId: string | null | undefined, enabled = true): UseTicketEngagementsReturn {
+export function useTicketEngagements(
+  externalTicketId: string | null | undefined,
+  enabled = true,
+  /** Poll cadence (ms) for live conversation refresh while the drawer is
+   *  open. The drawer only mounts this hook when expanded, so a constant
+   *  here is already gated to "drawer open" — closing the drawer unmounts
+   *  the panel and the polling stops. `false`/undefined disables it (the
+   *  default, preserving prior fetch-once-per-open behavior for any other
+   *  caller). Mirrors `useTicketsList.refetchInterval`; see
+   *  `TICKET_LIVE_POLL_MS`. */
+  refetchInterval: number | false = false,
+): UseTicketEngagementsReturn {
   const identity = useChatIdentity()
   const identityKey = identity.user?.email ?? 'anon'
 
@@ -94,6 +105,11 @@ export function useTicketEngagements(externalTicketId: string | null | undefined
     gcTime: 0,
     refetchOnMount: 'always',
     refetchOnWindowFocus: true,
+    // Live conversation: poll while the caller opts in (drawer open). New
+    // agent replies + attachments appear within one interval without a
+    // manual refresh. `refetchIntervalInBackground` stays false (default)
+    // so polling pauses on a hidden tab.
+    refetchInterval,
     queryFn: async (): Promise<TicketEngagement[]> => {
       const response = await embedAuthedFetch(LIST_ENGAGEMENTS_ENDPOINT, {
         method: 'POST',

package/src/components/tickets/hooks/use-tickets-list.ts

@@ -58,6 +58,13 @@ export interface UseTicketsListFilters {
   page?: number
   /** Items per page (server caps at 100). Defaults to 20. */
   pageSize?: number
+  /** Poll interval (ms) for live updates — e.g. so a ticket CLOSED out-of-band
+   *  on HubSpot flips the status badge + open/reopen affordance without a manual
+   *  refresh. `false`/0/undefined disables polling. The hub passes a value only
+   *  while a drawer is open (mirror webhooks keep the server fresh; this surfaces
+   *  it client-side). TanStack pauses interval polling while the tab is hidden,
+   *  so there are no wasted background requests. */
+  refetchInterval?: number | false
 }
 
 export interface UseTicketsListReturn {
@@ -103,6 +110,8 @@ export function useTicketsList(filters: UseTicketsListFilters): UseTicketsListRe
   // previous identity's data.
   const identityKey = customerEmail || 'anon'
 
+  const refetchInterval = filters.refetchInterval ?? false
+
   const query = useQuery({
     queryKey: ['tickets', 'self', identityKey, search, statusFilter, page, pageSize],
     enabled,
@@ -115,6 +124,10 @@ export function useTicketsList(filters: UseTicketsListFilters): UseTicketsListRe
     gcTime: 0,
     refetchOnMount: 'always',
     refetchOnWindowFocus: true,
+    // Live status: poll while the caller opts in (drawer open). Defaults to
+    // false. `refetchIntervalInBackground` stays false (the default) so polling
+    // pauses on a hidden tab — no wasted requests when the user tabs away.
+    refetchInterval,
     queryFn: async (): Promise<FindTicketResponse> => {
       const body: Record<string, string | number> = {
         query: search,

package/src/components/tickets/index.ts

@@ -10,6 +10,10 @@ export {
   TicketLinkedDeliveryCard,
   type TicketLinkedDeliveryCardProps,
 } from './ticket-linked-delivery-card'
+export {
+  TicketReplyComposer,
+  type TicketReplyComposerProps,
+} from './ticket-reply-composer'
 // Help Center — full-page customer-facing surface used by
 // openframe's `/tickets` route. Composes `DevSectionPage` chrome
 // (hero + search + filter) + a creation form above the controls +