@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/shared/product-release/.release-detail-page.md

@@ -1,26 +1,30 @@
-<!-- source-hash: bce89d098aaae5a0045e31b754508d2a -->
-A client-side React page component that renders a detailed view of a product release, including metadata, changelog sections, linked roadmap/delivery tasks, media, and video content. It supports injectable components for app-specific rendering and pre-fetched data for admin preview.
+<!-- source-hash: 2d7b47eeea450e199010485ffef88bdb -->
+Renders a full product release detail page with support for injectable components, linked task fetching, and flexible layout modes.
 
 ## Key Components
 
-### Exported Types
-- **`ReleaseDetailPageProps`** — Main props interface; accepts `slug`, optional `initialData`, a `useRelease` hook, and injectable section components
-- **`UseReleaseResult`** — Shape returned by the injected `useRelease` hook
-- **`MarkdownRendererProps`**, **`RoadmapSectionProps`**, **`DeliverySectionProps`**, **`VideoSectionProps`**, **`VideoDisplaySectionProps`** — Props interfaces for each injectable section component
-- **`RoadmapItem`**, **`DeliveryResponse`** — Re-exported canonical types for source compatibility
+### `ReleaseDetailPage`
+Primary export. Renders a complete release detail view including metadata, changelog, media gallery, roadmap/delivery sections, and related content.
 
-### Main Export
-- **`ReleaseDetailPage`** — Primary page component; orchestrates data fetching, linked task loading, gallery state, and layout rendering
+### Exported Types
 
-### Internal Helpers
-- **`DefaultMarkdownRenderer`** — Fallback renderer using `whitespace-pre-wrap` when no `MarkdownRenderer` is injected
+| Type | Purpose |
+|---|---|
+| `ReleaseDetailPageProps` | Full prop interface for the page component |
+| `UseReleaseResult` | Shape returned by the required `useRelease` hook |
+| `VideoDisplaySectionProps` | Props for the injectable video section with bites/tabs support |
+| `RoadmapSectionProps` | Props for the injectable roadmap task section |
+| `DeliverySectionProps` | Props for the injectable delivery task section |
+| `MarkdownRendererProps` | Props for the injectable markdown renderer |
+| `RoadmapItem` | Re-exported from `../../chat/types/entities/roadmap-item` |
+| `DeliveryResponse` | Re-exported from `../../../types/delivery` |
 
 ## Usage Example
 
 ```typescript
-import { ReleaseDetailPage } from './release-detail-page';
+import { ReleaseDetailPage } from '@openframe/ui';
 import { useRelease } from '@/hooks/use-release';
-import { MarkdownRenderer } from '@/components/markdown-renderer';
+import { AppMarkdownRenderer } from '@/components/markdown-renderer';
 import { RoadmapSection } from '@/components/roadmap-section';
 
 export default function ReleasePage({ params }: { params: { slug: string } }) {
@@ -28,14 +32,25 @@ export default function ReleasePage({ params }: { params: { slug: string } }) {
     <ReleaseDetailPage
       slug={params.slug}
       useRelease={useRelease}
-      MarkdownRenderer={MarkdownRenderer}
+      MarkdownRenderer={AppMarkdownRenderer}
       RoadmapSection={RoadmapSection}
       roadmapApiEndpoint="/api/roadmap"
       deliveryApiEndpoint="/api/delivery"
       backButton={{ label: 'Back to releases', href: '/releases' }}
+      relatedContent={<RelatedReleases />}
+      shell={true}
     />
   );
 }
 ```
 
-> **Note:** The `useRelease` hook must be provided at the app level to ensure it uses the correct `QueryClient`. When `initialData` is supplied, the hook is bypassed entirely — enabling admin preview without a network fetch.
+## Key Behaviors
+
+- **Injectable architecture**: `MarkdownRenderer`, `RoadmapSection`, `DeliverySection`, and `VideoDisplaySection` are all optional overrides; defaults fall back to lib-provided components
+- **Dual data modes**: Accepts `initialData` for admin preview (skips fetch); otherwise uses the required `useRelease` hook
+- **Linked task fetching**: Automatically fetches ClickUp roadmap/delivery tasks via `contentFetch` when task IDs are present on the release record
+- **Shell toggle**: `shell={false}` suppresses the outer `<PageShell>` for host layouts that already provide a page container
+
+## Source
+
+[`release-detail-page.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/release-detail-page.tsx)

package/src/components/shared/roadmap/.index.md

@@ -1,37 +1,42 @@
-<!-- source-hash: 499214f4840bb2650161d384a662b71b -->
-Barrel export file for the shared roadmap surface, exposing grid components and voting hook while intentionally omitting `RoadmapItem` and `VoteType` to prevent TypeScript TS2308 ambiguous re-export errors.
+<!-- source-hash: 84846be8d32682355ecb5cfae1b2e793 -->
+Barrel export file for the shared roadmap surface, exposing grid, skeleton, voting logic, and the self-fetching list view while intentionally omitting `RoadmapItem` and `VoteType` to avoid TypeScript TS2308 ambiguous re-export errors.
 
 ## Key Components
 
 | Export | Type | Description |
-|--------|------|-------------|
-| `RoadmapGrid` | Component | Main grid layout for displaying roadmap items |
-| `RoadmapGridProps` | Type | Props interface for `RoadmapGrid` |
-| `RoadmapGridSkeleton` | Component | Loading skeleton for the roadmap grid |
-| `RoadmapGridSkeletonProps` | Type | Props interface for `RoadmapGridSkeleton` |
-| `useRoadmapVoting` | Hook | Hook encapsulating roadmap voting logic |
-| `VoteState` | Type | State shape for a vote interaction |
-| `UseRoadmapVotingOptions` | Type | Options interface for `useRoadmapVoting` |
-
-## Intentionally Omitted Exports
-
-| Omitted | Reason | Canonical Import Path |
-|---------|--------|-----------------------|
-| `RoadmapItem` | Already exported via two paths; a third triggers TS2308 | `@flamingo-stack/openframe-frontend-core/components/chat` |
-| `VoteType` | Duplicate of the same type re-exported from `./chat` | `@flamingo-stack/openframe-frontend-core/components/chat` |
+|---|---|---|
+| `RoadmapGrid` / `RoadmapGridProps` | Component | Renders a grid of roadmap cards |
+| `RoadmapGridSkeleton` / `RoadmapGridSkeletonProps` | Component | Loading skeleton for the roadmap grid |
+| `useRoadmapVoting` / `VoteState` / `UseRoadmapVotingOptions` | Hook + Types | Manages voting state and interactions on roadmap items |
+| `RoadmapView` / `RoadmapViewProps` | Component | Self-fetching roadmap list surface; host only configures API routes |
 
 ## Usage Example
 
 ```typescript
-// ✅ Import roadmap surface components from this barrel
 import {
   RoadmapGrid,
   RoadmapGridSkeleton,
+  RoadmapView,
   useRoadmapVoting,
-  type VoteState,
-  type UseRoadmapVotingOptions,
-} from '@flamingo-stack/openframe-frontend-core/components/shared/roadmap';
+} from '@flamingo-stack/openframe-frontend-core/components/roadmap';
 
-// ✅ Import omitted types from their canonical paths
-import type { RoadmapItem, VoteType } from '@flamingo-stack/openframe-frontend-core/components/chat';
-```
+// Self-fetching view — host provides API route config only
+<RoadmapView apiRoute="/api/roadmap" />
+
+// Manual grid with voting hook
+const { vote, voteState } = useRoadmapVoting({ itemId: 'item-123' });
+<RoadmapGrid items={roadmapItems} onVote={vote} />
+```
+
+## Intentional Omissions
+
+- **`RoadmapItem`** — canonical type is available via:
+  - `@flamingo-stack/openframe-frontend-core/components/chat`
+  - `@flamingo-stack/openframe-frontend-core/components` (via `./shared/product-release`)
+- **`VoteType`** — canonical import path is `@flamingo-stack/openframe-frontend-core/components/chat`
+
+Both are excluded to prevent [TS2308](https://www.typescriptlang.org/tsconfig#isolatedModules) ambiguous re-export errors at the top-level barrel.
+
+## Source
+
+[`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)

package/src/components/shared/roadmap/.roadmap-grid.md

@@ -1,66 +1,55 @@
-<!-- source-hash: afe909dc035ab417a954948a391b890a -->
-Full-page roadmap surface that renders a responsive 2-column grid of `RoadmapCard` components with integrated voting state and live count refresh.
+<!-- source-hash: 20b142caf72c6c8479a957bacef62151 -->
+Shared roadmap list surface component that renders roadmap items either as a flat two-column grid or grouped into collapsible per-quarter accordions, with centralized voting state management.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `RoadmapGrid` | Component | Main grid component rendering all roadmap items |
-| `RoadmapGridProps` | Interface | Component prop contract |
-| `DEFAULT_BUILD_REFRESH_URL` | Constant | Default URL builder: `(taskId) => /api/roadmap/${taskId}` |
-
-## Props
+### `RoadmapGrid` (main export)
+The top-level component that orchestrates both rendering modes and shared voting state.
 
+**Props:**
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `items` | `RoadmapItem[]` | — | Roadmap entries to display |
-| `onItemUpdate` | `(item: RoadmapItem) => void` | — | Callback fired after a successful vote refresh |
-| `showLeftMargin` | `boolean` | `true` | Applies `md:ml-[120px]` for hero alignment; pass `false` for rails |
-| `buildRefreshUrl` | `(taskId: string) => string` | `DEFAULT_BUILD_REFRESH_URL` | Path-based URL builder for per-task refresh after vote |
-| `votingOptions` | `UseRoadmapVotingOptions` | — | Vote endpoint + storage key forwarded to `useRoadmapVoting` |
-
-## Voting Flow
-
-```mermaid
-graph TD
-    A["User Clicks Vote"] --> B{"Task Already Voting?"}
-    B -->|Yes| C["Ignore / No-op"]
-    B -->|No| D["Lock Task ID in votingTasks"]
-    D --> E["toggleVote()"]
-    E --> F{"result.success?"}
-    F -->|No| G["Unlock Task ID"]
-    F -->|Yes| H["GET buildRefreshUrl(taskId)"]
-    H --> I{"response.ok?"}
-    I -->|Yes| J["onItemUpdate(data.item)"]
-    I -->|No| G
-    J --> G
-```
+|---|---|---|---|
+| `items` | `RoadmapItem[]` | — | Roadmap items to display |
+| `groupByQuarter` | `boolean` | `false` | Enables accordion quarter grouping |
+| `hasActiveFilters` | `boolean` | `false` | Expands all quarters when filters are active |
+| `quartersToKeepClosed` | `number` | `2` | Past quarter collapse window |
+| `showLeftMargin` | `boolean` | `true` | Desktop alignment margin (~120px) |
+| `buildRefreshUrl` | `(taskId: string) => string` | `/api/roadmap/:id` | URL builder for post-vote refresh |
+| `votingOptions` | `UseRoadmapVotingOptions` | — | Vote endpoint + storage key config |
+| `onItemUpdate` | `(item: RoadmapItem) => void` | — | Callback after successful vote refresh |
+
+### `RoadmapGridSingle` (internal)
+Flat 2-column grid for a single set of items. Receives voting handlers from the parent to avoid split state across quarters.
+
+### Quarter Helpers (pure functions)
+- `parseQuarterString(q)` — parses `"Q<n> <year>"` labels
+- `compareQuarters(a, b)` — chronological sort comparator
+- `computeDefaultExpandedQuarters(quarters, quartersToKeepClosed)` — determines which quarters open by default
+- `getStatusPriority(status)` — sorts items within a quarter by status (Complete → Working → Review → To-Do)
 
 ## Usage Example
 
 ```typescript
-import { RoadmapGrid } from './roadmap-grid';
-import type { RoadmapItem } from '../../chat/types/entities/roadmap-item';
-
-function RoadmapPage({ items }: { items: RoadmapItem[] }) {
-  const [roadmapItems, setRoadmapItems] = useState(items);
+// Grouped by quarter (full roadmap page)
+<RoadmapGrid
+  items={roadmapItems}
+  groupByQuarter={true}
+  hasActiveFilters={searchQuery.length > 0}
+  quartersToKeepClosed={2}
+  onItemUpdate={(updated) => patchItem(updated)}
+  votingOptions={{ endpoint: '/api/vote', storageKey: 'roadmap-votes' }}
+/>
+
+// Flat mode (related-content rail)
+<RoadmapGrid
+  items={filteredItems}
+  showLeftMargin={false}
+  votingOptions={{ endpoint: '/api/vote', storageKey: 'roadmap-votes' }}
+/>
+```
 
-  const handleItemUpdate = (updated: RoadmapItem) => {
-    setRoadmapItems(prev =>
-      prev.map(i => (i.id === updated.id ? updated : i))
-    );
-  };
+## Hydration Strategy
 
-  return (
-    <RoadmapGrid
-      items={roadmapItems}
-      onItemUpdate={handleItemUpdate}
-      showLeftMargin={true}
-      buildRefreshUrl={(taskId) => `/api/roadmap/${taskId}`}
-      votingOptions={{ endpoint: '/api/votes', storageKey: 'roadmap-votes' }}
-    />
-  );
-}
-```
+`expandedQuarters` initializes to `[]` on the server and is populated in a client-only `useEffect`, ensuring SSR markup matches the first client paint before accordion state is applied.
 
-> **Note on `buildRefreshUrl`:** This prop is intentionally a function rather than a string template to safely support embedders whose by-id route shape differs (e.g. `/api/roadmap?id=…`). String concatenation would silently break non-standard routes.
+**Source:** [`roadmap-grid.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/roadmap-grid.tsx)

package/src/components/shared/roadmap/.roadmap-view.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 84574f4998ed905b3d23591c61799aab -->
+Self-contained roadmap list surface that fetches roadmap data via `useSelfFetch`, applies URL-driven search/status filters, and renders the controlled `<RoadmapGrid>` with SSR hydration support.
+
+## Key Components
+
+- **`RoadmapView`** — Primary export. Orchestrates data fetching, URL parameter reading, scroll-to-hash deep linking, and delegates rendering to `<RoadmapGrid>`.
+- **`RoadmapViewProps`** — Configuration interface for API routes, SSR hydration, voting, and URL parameter key overrides.
+- **`useSelfFetch`** — Shared hook providing `data`, `setData`, `isLoading`, `error`, and `reload`. The fetch URL acts as the cache key, so filter changes automatically trigger refetches.
+- **`useScrollToHash`** — Handles deep-link hash dispatch (e.g. `?search=<id>#roadmap-<id>` from chat cards), polling until the target item mounts.
+- **`RoadmapGridSkeleton`** — Shown only during the first in-flight fetch when no data exists yet.
+- **`LoadError`** — Rendered on fetch failure with a retry callback.
+
+## Usage Example
+
+```typescript
+import { RoadmapView } from './roadmap-view'
+
+// Minimal — uses all defaults (/api/roadmap, 'search', 'status' params)
+<RoadmapView />
+
+// With SSR hydration, custom endpoint, and voting
+<RoadmapView
+  endpoint="/api/v2/roadmap"
+  initialItems={serverSideItems}
+  showLeftMargin
+  buildRefreshUrl={(taskId) => `/api/v2/roadmap/${taskId}`}
+  votingOptions={{
+    voteEndpoint: '/api/roadmap/vote',
+    storageKey: 'roadmap-votes',
+  }}
+  searchParamKey="q"
+  statusParamKey="status"
+/>
+```
+
+## Notes
+
+- Filter params are folded into the fetch URL (`?search=&status=`), keeping the URL as the single cache key. This mirrors the `ProductReleasesView` pattern.
+- The `initialData` wrapper is memoized to maintain stable identity and prevent optimistic vote patches from being clobbered by re-sync effects.
+- After a vote, `onItemUpdate` patches the refreshed task directly into local state via `setData`, keeping vote counts live without a full list refetch.
+- `searchParamKey` and `statusParamKey` default to values from `DEV_SECTION_PARAM_KEYS` — the same registry used by the section chrome — preventing silent key divergence.

package/src/components/shared/roadmap/.use-roadmap-voting.md

@@ -1,5 +1,5 @@
-<!-- source-hash: f066f48b7e750fe429b96a6f9a50da79 -->
-A `localStorage`-backed React hook providing optimistic up/down voting for roadmap cards, with one vote per task per user, automatic vote toggling/switching, and server sync via a configurable API endpoint.
+<!-- source-hash: 97838d0f1dd2839bee9f826d368aa0df -->
+Custom React hook that manages optimistic up/down voting for roadmap cards, persisting vote state to `localStorage` with one vote per task per user and syncing changes to a configurable API endpoint.
 
 ## Key Components
 
@@ -9,7 +9,14 @@ A `localStorage`-backed React hook providing optimistic up/down voting for roadm
 |------|-------------|
 | `VoteType` | `'up' \| 'down' \| null` — current vote state for a task |
 | `VoteState` | Record mapping `taskId → VoteType` |
-| `UseRoadmapVotingOptions` | Configuration interface for endpoint and storage key |
+| `UseRoadmapVotingOptions` | Hook configuration options |
+
+### `UseRoadmapVotingOptions`
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `voteApiEndpoint` | `/api/roadmap/vote` | Vote POST endpoint; override for reverse-proxy embedders |
+| `storageKey` | `roadmap_votes_v1` | `localStorage` key; scope per surface to avoid cross-contamination |
 
 ### Hook Return Values
 
@@ -17,16 +24,15 @@ A `localStorage`-backed React hook providing optimistic up/down voting for roadm
 |-------|------|-------------|
 | `votes` | `VoteState` | All current votes keyed by `taskId` |
 | `isLoading` | `boolean` | `true` while hydrating from `localStorage` |
-| `getVote` | `(taskId) => VoteType` | Returns current vote for a task |
-| `toggleVote` | `async (taskId, voteType) => result` | Casts or removes a vote with optimistic update |
+| `getVote` | `(taskId: string) => VoteType` | Returns current vote for a task |
+| `toggleVote` | `(taskId, voteType) => Promise<{success, newVote, action}>` | Casts or retracts a vote |
 | `clearVotes` | `() => void` | Clears all votes from state and `localStorage` |
 
-### Core Behavior
+### `toggleVote` Logic
 
-- **Optimistic updates** — UI reflects vote immediately; reverts on API failure
-- **Toggle semantics** — clicking the active vote removes it; switching direction sends a remove + add pair to keep server totals consistent
-- **Namespace isolation** — `storageKey` option allows multiple roadmap surfaces on the same origin without vote cross-contamination
-- **Key change safety** — state resets and re-hydrates whenever `storageKey` changes mid-lifecycle
+- **Same direction** → removes the existing vote (`action: 'remove'`)
+- **Opposite direction** → fires a remove for the old vote first, then adds the new one (keeps server totals consistent)
+- **Optimistic update** → state updates immediately; reverts on API failure
 
 ## Usage Example
 
@@ -35,34 +41,38 @@ import { useRoadmapVoting } from './use-roadmap-voting';
 
 function RoadmapCard({ taskId }: { taskId: string }) {
   const { getVote, toggleVote, isLoading } = useRoadmapVoting({
-    voteApiEndpoint: '/api/roadmap/vote',
+    voteApiEndpoint: '/proxy/roadmap/vote',
     storageKey: 'roadmap_votes_v1_main',
   });
 
   const currentVote = getVote(taskId);
 
-  const handleVote = async (type: 'up' | 'down') => {
-    const { success, newVote } = await toggleVote(taskId, type);
+  const handleVote = async (direction: 'up' | 'down') => {
+    const { success, newVote } = await toggleVote(taskId, direction);
     if (!success) console.warn('Vote failed, reverted to:', newVote);
   };
 
-  if (isLoading) return <span>Loading...</span>;
+  if (isLoading) return null;
 
   return (
     <div>
       <button
         onClick={() => handleVote('up')}
-        style={{ fontWeight: currentVote === 'up' ? 'bold' : 'normal' }}
+        aria-pressed={currentVote === 'up'}
       >
         👍
       </button>
       <button
         onClick={() => handleVote('down')}
-        style={{ fontWeight: currentVote === 'down' ? 'bold' : 'normal' }}
+        aria-pressed={currentVote === 'down'}
       >
         👎
       </button>
     </div>
   );
 }
-```
+```
+
+> **Storage key scoping:** When mounting multiple roadmap surfaces on the same origin, use distinct `storageKey` values (e.g. `roadmap_votes_v1_main` vs `roadmap_votes_v1_admin`) to prevent votes from bleeding across surfaces.
+
+**Source:** [`use-roadmap-voting.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-roadmap-voting.ts)

package/src/components/switch.tsx

@@ -11,7 +11,7 @@ const Switch = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <SwitchPrimitives.Root
     className={cn(
-      "peer inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input",
+      "peer inline-flex h-6 w-11 shrink-0 items-center rounded-full border-2 border-transparent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input",
       className,
     )}
     {...props}

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

@@ -1,39 +1,38 @@
-<!-- source-hash: a4fe8194703f767fe2216ee1b9351f99 -->
-A client-side React component that renders a single support ticket row in the Help Center list, featuring a toggleable expanded drawer for full ticket interaction.
+<!-- source-hash: e00a581ebb9cca5570476237e530ae85 -->
+Renders a single ticket row in the Help Center list, combining a toggleable summary button with an expandable detail drawer (`TicketDetailDrawer`) that provides full ticket interaction (compose, close, reopen).
 
 ## Key Components
 
 ### `HelpCenterCard` (default export)
-The primary component rendering a ticket summary row as a clickable `<button>` that toggles a `<TicketDetailDrawer>` below it. Key behaviors:
+The primary component. Renders a `<button>` summary row using `DevCardRowContent` (shared with the delivery list for visual consistency). When expanded, mounts a sibling `TicketDetailDrawer` beneath the row. Optimistic (locally-created, not yet server-confirmed) tickets render as non-expandable, dimmed rows.
 
-- **Optimistic rows** are rendered as non-expandable (dimmed, `opacity-60`) until the server confirms the ticket ID
-- **Scroll-on-expand** uses `scrollElementIntoView` with a cross-row layout-shift correction — compensates when a sibling drawer above collapses simultaneously, shifting the page Y position
-- **Sticky header offset** (`STICKY_HEADER_OFFSET_PX = 96`) is applied both as `scrollMarginTop` inline style (for browser/anchor scrolls) and as `headerOffset` (for programmatic scroll), keeping them in sync from a single constant
+**Notable behaviors:**
+- Smooth-scroll via `scrollElementIntoView` (rAF-driven, immune to browser scroll-anchor cancellation) on expand — runs in a `useEffect`, not the click handler, so the drawer height is committed before measurement
+- Deep-link support: accepts an `id` prop (`ticket-<external_id>`) for `useScrollToHash` hash navigation from chat cards
+- Drawer is a DOM sibling of the toggle button — click events inside the drawer do not bubble to the row's toggle handler
 
-### `HelpCenterCardProps`
-```typescript
-interface HelpCenterCardProps {
-  ticket: AnyTicket
-  expanded: boolean
-  onToggle: (id: string) => void
-  busy: boolean
-  supportSystemDown: boolean
-  onSendMessage: TicketDetailDrawerProps['onSendMessage']
-  onClose: TicketDetailDrawerProps['onClose']
-  onReopen: TicketDetailDrawerProps['onReopen']
-  onActionCollapsed: () => void
-}
-```
+### `mapPriorityScheme` (local helper)
+Maps ticket priority strings to `StatusBadge` color schemes:
 
-### `mapPriorityScheme` (internal)
-Maps ticket priority strings to `StatusBadge` color schemes. Kept separate from the shared `getStatusColorScheme` to avoid conflating workflow status with severity.
-
-| Priority | Color Scheme |
-|----------|-------------|
+| Priority | Scheme |
+|---|---|
 | `HIGH` / `URGENT` | `error` (red) |
 | `MEDIUM` | `warning` (yellow) |
 | `LOW` / unknown | `default` |
 
+Kept local to avoid conflating workflow status colors (from `getStatusColorScheme`) with severity colors.
+
+## Key Props (`HelpCenterCardProps`)
+
+| Prop | Type | Description |
+|---|---|---|
+| `ticket` | `AnyTicket` | Ticket data (real or optimistic) |
+| `expanded` | `boolean` | Controlled open/closed state |
+| `onToggle` | `(id: string) => void` | Called on row click |
+| `busy` | `boolean` | Forwarded to drawer for loading state |
+| `replyError` | `TicketDetailDrawerProps['replyError']` | Persisted reply-failure banner |
+| `id` | `string?` | DOM `id` for hash-based deep linking |
+
 ## Usage Example
 
 ```typescript
@@ -44,8 +43,13 @@ Maps ticket priority strings to `StatusBadge` color schemes. Kept separate from
   busy={isBusy}
   supportSystemDown={false}
   onSendMessage={handleSendMessage}
-  onClose={handleCloseTicket}
-  onReopen={handleReopenTicket}
+  onClose={handleClose}
+  onReopen={handleReopen}
   onActionCollapsed={() => setExpandedId(null)}
+  replyError={replyErrors[ticket.external_id]}
+  onClearReplyError={() => clearReplyError(ticket.external_id)}
+  id={`ticket-${ticket.external_id}`}
 />
-```
+```
+
+**Source:** [`help-center-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/help-center-card.tsx)

package/src/components/tickets/.help-center-create-form.md

@@ -1,38 +1,50 @@
-<!-- source-hash: a34cdabdcffe2227fd25cb927e40e785 -->
-Thin wrapper around `<ContactForm />` that preconfigures it for Help Center ticket creation, plus a pixel-accurate loading skeleton.
+<!-- source-hash: c50de1033f2620ae73492d4bf1b8bd20 -->
+Thin wrapper around `<ContactForm />` that preconfigures it for Help Center ticket creation, managing local Subject field state and wiring submission to `useTicketActions.submitTicket`.
 
 ## Key Components
 
 ### `HelpCenterCreateForm`
-The primary export. Wraps `<ContactForm />` with ticket-specific configuration:
-- Hides irrelevant contact fields (`name`, `email`, `companySize`, `referralSource`, `helpCategory`)
+Main form component that composes `<ContactForm />` with ticket-specific behavior:
+- Hides contact-only fields (`name`, `email`, `companySize`, `referralSource`, `helpCategory`)
 - Injects a locally-managed `Subject` input via `extraTopField`
-- Pre-fills hidden fields from session identity to satisfy Zod validators
-- Wires `onCustomSubmit` to `actions.submitTicket(...)` with subject validation before delegating
+- Pre-fills hidden fields from `sessionName`/`sessionEmail` so Zod validators pass silently
+- Routes submission through `actions.submitTicket()` into the optimistic-placeholder flow
 
 ### `HelpCenterCreateFormSkeleton`
-A loading placeholder that mirrors the real form's dimensions pixel-for-pixel (verified at `lg` breakpoint: 556px wrapper height). Includes 4 hidden `<input type="hidden">` elements to replicate Tailwind's `space-y-*` sibling spacing behavior — omitting them shifts the visible stack up by 24px on page load.
+Pixel-accurate loading placeholder that mirrors the real form's layout to prevent layout shift (CLS) while session identity resolves. Includes four hidden `<input>` elements to replicate `space-y-*` sibling counting behavior from `<ContactForm />`.
 
 ### `HelpCenterCreateFormProps`
 | Prop | Type | Description |
-|------|------|-------------|
-| `actions` | `UseTicketActionsReturn` | Full actions bag; `submitTicket` is consumed |
-| `sessionName` | `string` | Pre-resolved identity name from parent |
-| `sessionEmail` | `string` | Pre-resolved identity email from parent |
-| `supportSystemDown` | `boolean` | Disables all inputs when HubSpot is unavailable |
+|---|---|---|
+| `actions` | `UseTicketActionsReturn` | Full actions bag from `useTicketActions` |
+| `sessionName` | `string` | Resolved session display name |
+| `sessionEmail` | `string` | Resolved session email |
+| `supportSystemDown` | `boolean?` | Disables all inputs when HubSpot is unavailable |
 
 ## Usage Example
 
 ```typescript
-<HelpCenterCreateForm
-  actions={ticketActions}
-  sessionName={identity.name}
-  sessionEmail={identity.email}
-  supportSystemDown={ticketActions.onSupportSystemDown}
-/>
-
-// While identity.isLoading:
-<HelpCenterCreateFormSkeleton />
+import { HelpCenterCreateForm, HelpCenterCreateFormSkeleton } from './help-center-create-form'
+import { useTicketActions } from './hooks/use-ticket-actions'
+import { useChatIdentity } from '../hooks/use-chat-identity'
+
+function HelpCenterList() {
+  const actions = useTicketActions()
+  const identity = useChatIdentity()
+
+  if (identity.isLoading) {
+    return <HelpCenterCreateFormSkeleton />
+  }
+
+  return (
+    <HelpCenterCreateForm
+      actions={actions}
+      sessionName={identity.user?.name ?? ''}
+      sessionEmail={identity.sessionEmail}
+      supportSystemDown={actions.onSupportSystemDown}
+    />
+  )
+}
 ```
 
-> **Note:** `sessionName`/`sessionEmail` must be passed from the parent rather than re-calling `useChatIdentity` inside this component — a second hook call mounts with `user = null`, causing react-hook-form to lock `defaultValues.email` to an empty string for the form's lifetime, silently failing Zod validation on submit.
+> **Note:** Pass `sessionName`/`sessionEmail` from the parent rather than calling `useChatIdentity` again inside this component — a second hook call mounts with stale defaults, causing Zod to silently reject submission with an empty email.