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

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

@@ -1,44 +1,42 @@
-<!-- source-hash: d70b1713cdb85568acf904d7a2daa162 -->
-Renders enhanced chat messages with support for multi-segment content, inline/block entity card markers, tool executions, approval flows, and rich markdown — delegating entity resolution and navigation to host-provided callbacks.
+<!-- source-hash: e3aea36595a360e95ddef8fc94d285d3 -->
+Renders an enhanced chat message component that supports rich content including markdown, inline entity cards, mention chips, tool execution displays, approval requests, and context-aware streaming with intelligent segment splitting.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `ChatMessageEnhanced` | `forwardRef` component | Main message renderer with role-aware layout (`user`, `error`, assistant variants) |
-| `normalizeContent` | Function | Normalizes `MessageContent` (string or `MessageSegment[]`) to a uniform segment array |
-| `CARD_MARKER_REGEX` | Regex | Shared pattern matching `[card://type:id]` markers — kept in lockstep with `remarkCardLinks` |
-| `renderingPlan` | `useMemo` | Per-message plan splitting text segments at block card markers for accurate streaming position |
-| `cardComponentOverrides` | `useMemo` | Overrides `<a>` tags for `card://` URLs, resolving inline/block entity cards via host callbacks |
-
-### Supporting Displays (composed internally)
-- `ToolExecutionDisplay` — renders tool call segments
-- `ApprovalRequestMessage` / `ApprovalBatchMessage` — approval flow segments
-- `ErrorMessageDisplay` — error role messages
-- `ContextCompactionDisplay` — context compaction events
-- `ThinkingDisplay` — streaming thinking segments
+### `ChatMessageEnhanced`
+The primary `forwardRef` component that handles multi-role message rendering (`user`, `error`, assistant variants) with:
+
+- **`renderingPlan`** — Memoized plan that splits text segments at `[card://type:id]` markers so block-level entity cards render at exact marker positions during streaming, not at segment end
+- **`renderedCardNodeCache`** — `useRef`-backed cache keyed by `type:id` that preserves React element identity across stream chunks, preventing card remounts and preserving open menus/fetch state
+- **`inlineMentionIds`** — Scans text segments for `@marker:id` tokens to exclude already-inline-rendered mentions from the chip strip
+- **`stripContextItems`** — Filters `contextItems` to only show context NOT already rendered inline
+
+### Regex Constants
+- **`MENTION_MARKER_REGEX`** — Mirrors `remark-mention-chips.ts` left-boundary to avoid stripping tokens the plugin would also skip
+- **`CARD_MARKER_REGEX`** — Mirrors `remarkCardLinks` grammar; both must stay in lockstep when the marker syntax changes
+
+### Utilities
+- **`formatMessageTimestamp`** — Shows time-only for today's messages; prepends locale date for older ones
+- **`normalizeContent`** — Normalizes `MessageContent` (string or `MessageSegment[]`) to a uniform `MessageSegment[]`
 
 ## Usage Example
 
 ```typescript
+import { ChatMessageEnhanced } from "@openframe-oss/lib"
+
 <ChatMessageEnhanced
   role="assistant"
   assistantType="mingo"
-  content={[
-    { type: 'text', text: 'Here is your ticket [card://ticket:123].' },
-    { type: 'tool_execution', toolName: 'search', result: '...' },
-  ]}
-  chatRefs={{
-    'ticket:123': { type: 'ticket', id: '123', title: 'Login bug', url: '/tickets/123' },
-  }}
-  renderEntityCard={(ref) => <TicketPill ref={ref} />}
-  NavLinkAnchor={({ href, children }) => <Link href={href}>{children}</Link>}
-  showAvatar
+  content={[{ type: "text", text: "Here is your device: [card://device:abc123]" }]}
+  chatRefs={{ "device:abc123": { type: "device", id: "abc123", title: "Laptop A", url: null } }}
+  renderEntityCard={(ref) => <MyEntityCard ref={ref} />}
+  renderMention={(type, id) => <MentionChip type={type} id={id} />}
+  contextItems={contextItems}
+  timestamp={new Date()}
 />
 ```
 
-## Notes
-
-- **Data-agnostic**: the library never imports entity types or routing — the host provides `renderEntityCard` and `NavLinkAnchor`.
-- Block card markers split their text segment so block payloads render at the marker position during streaming, not appended at the end.
-- Three distinct fallbacks for unresolved `card://` hrefs prevent LLM hallucinations from appearing as real cards.
+## Related Files
+- [`remark-card-links.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/remark-card-links.ts) — Remark plugin; grammar must stay in sync with `CARD_MARKER_REGEX`
+- [`remark-mention-chips.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/remark-mention-chips.ts) — Remark plugin; left-boundary must stay in sync with `MENTION_MARKER_REGEX`
+- [`block-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/entity-cards/block-card.tsx) — Block-level card wrapper used in segment splitting logic

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

@@ -1,67 +1,57 @@
-<!-- source-hash: ddaad2500e41f9ee61eff7435b990d72 -->
-A scrollable chat message list component with stick-to-bottom behavior, prepend anchoring for load-older pagination, and streaming indicators.
+<!-- source-hash: bcd59a730239fa164668aa97e210c356 -->
+Renders a scrollable, auto-anchoring chat message list with streaming indicators, infinite scroll upward pagination, and stick-to-bottom physics for AI chat interfaces.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `ChatMessageList` | `forwardRef` Component | Main scrollable message list with auto-scroll management |
-| `STREAMING_WORDS` | `const` | Flamingo-themed cycling phrases shown during AI streaming |
-| `hasNonEmptyContent` | Helper Function | Checks if a `MessageContent` value carries visible text |
-| `disposeAnchorWatcher` | Helper Function | Idempotent teardown for `AnchorWatcher` instances |
-| `AnchorWatcher` | Interface | Tracks `ResizeObserver` + timeout for top-anchor settle window |
-
-## Key Props (`ChatMessageListProps`)
-
-| Prop | Description |
-|------|-------------|
-| `messages` | Array of chat messages to render |
-| `dialogId` | Triggers instant scroll-to-bottom on dialog change |
-| `isLoading` / `isTyping` | Controls skeleton and streaming indicator visibility |
-| `autoScroll` | Enables/disables stick-to-bottom behavior |
-| `hasNextPage` / `onLoadMore` | Infinite scroll upward (load-older pagination) |
-| `renderEntityCard` | Custom renderer for entity card messages |
+- **`ChatMessageList`** — Primary `forwardRef` component wrapping `useStickToBottom` for spring-physics scroll anchoring during token streaming
+- **`STREAMING_WORDS`** — Flamingo-themed cycling phrases displayed alongside the typing/streaming indicator
+- **`hasNonEmptyContent`** — Utility predicate that checks whether a `MessageContent` value (string or `MessageSegment[]`) contains visible text
+- **`AnchorWatcher`** / **`disposeAnchorWatcher`** — Interface and idempotent teardown helper for the prepend-anchor `ResizeObserver` settle window
+- **`ChatMessageEnhanced`** — Per-message renderer (avatars, approval variants, entity cards, context icons, mentions)
+- **`ChatMessageListSkeleton`** — Placeholder skeleton shown during initial load
+- **`CyclingPhrase`** — Animated word-cycling component used inside the streaming indicator
+- **`DotsLoaderIcon`** — Animated dots icon displayed while `isTyping` is active
+
+## Scroll Architecture
+
+| Concern | Owner |
+|---|---|
+| Streaming follow (spring) | `useStickToBottom` |
+| Dialog change / first load / new user message | Force-scroll `useEffect` |
+| Load-older prepend anchoring | `loadOlderAnchorRef` + geometry delta |
+| Top-sentinel infinite scroll | `sentinelRef` + `IntersectionObserver` |
+| Passive demo hard-pin | `pinBottom` prop path |
 
 ## Usage Example
 
 ```typescript
-import { ChatMessageList } from "@/components/chat"
+import { ChatMessageList } from "@openframe/ui"
+import type { ChatMessage } from "@openframe/ui/types"
 
-const messages = [
+const messages: ChatMessage[] = [
   { id: "1", role: "user", content: "Hello!" },
   { id: "2", role: "assistant", content: "Hi there!" },
 ]
 
-export function ChatPanel() {
-  const listRef = useRef<HTMLDivElement>(null)
-
+export function MyChatView() {
   return (
     <ChatMessageList
-      ref={listRef}
       messages={messages}
-      dialogId="conv-abc123"
+      dialogId="dialog-abc"
       isTyping={false}
-      autoScroll={true}
-      showAvatars={true}
-      hasNextPage={true}
+      autoScroll
+      showAvatars
       onLoadMore={() => fetchOlderMessages()}
+      hasNextPage={true}
+      isFetchingNextPage={false}
     />
   )
 }
 ```
 
-## Scroll Management Strategy
-
-The component uses [`use-stick-to-bottom`](https://github.com/stackblitz-labs/use-stick-to-bottom) (same library powering bolt.new) with three additional behaviors layered on top:
+## Notes
 
-```mermaid
-graph TD
-    A["Message Update"] --> B{"Trigger Type?"}
-    B -->|"Dialog changed"| C["scrollToBottom instant"]
-    B -->|"First message"| C
-    B -->|"New user message"| C
-    B -->|"Streaming assistant"| D["Library spring physics"]
-    A --> E{"Content prepended?"}
-    E -->|"Load-older"| F["Preserve viewport via scrollTop delta"]
-    E -->|"No prepend"| G["Update scrollHeight snapshot"]
-```
+- Requires `use-stick-to-bottom` (StackBlitz Labs) — the same library used by Vercel AI SDK's `<Conversation>` and bolt.new
+- `initial: false` disables mount-time auto-scroll; the dialog-change `useEffect` owns first-paint positioning
+- Image attachments trigger a `requestAnimationFrame` follow-up scroll to handle Next.js `<Image>` progressive dimensioning
+- `pinBottom` bypasses smart-follow for scripted demos (Fae/Mingo) where no human controls scroll

package/src/components/chat/.chat-message-row.md

@@ -0,0 +1,56 @@
+<!-- source-hash: 9c88cf89d89eafde809c83221cb785bc -->
+Renders a single Slack-channel-style message row used across both the OpenMSP community feed and ticket conversation surfaces, ensuring pixel-identical layout on both.
+
+## Key Components
+
+### `ChatMessageRow`
+The primary message row component with avatar, display name, relative timestamp, body text, and an optional footer slot. Handles avatar proxying via `useProxiedImageUrl` and gracefully falls back to an initials box on image load failure, keyed by URL to allow retry on src change.
+
+### `ChatMessageRowSkeleton`
+A loading placeholder with 1:1 structural parity to `ChatMessageRow` — matching wrapper, avatar box dimensions, and bar heights to prevent layout reflow on the loading-to-loaded transition.
+
+### `ChatMessageRowProps`
+```typescript
+interface ChatMessageRowProps {
+  displayName: string       // Bold name in header
+  avatarUrl?: string | null // Proxied; falls back to initials
+  timeLabel?: string | null // Pre-formatted (e.g. "2h ago"); hidden if empty
+  body: string              // whitespace-pre-wrap message text
+  footer?: ReactNode        // Surface-specific slot (reply badge / attachments)
+}
+```
+
+## Usage Example
+
+```typescript
+import { ChatMessageRow, ChatMessageRowSkeleton } from './chat-message-row'
+
+// Slack community feed
+<ChatMessageRow
+  displayName="Jane Smith"
+  avatarUrl="https://cdn.example.com/avatars/jane.jpg"
+  timeLabel="2h ago"
+  body="Hey team, deployment looks good!"
+  footer={<ReplyBadge count={3} />}
+/>
+
+// Ticket conversation feed
+<ChatMessageRow
+  displayName="Support Bot"
+  avatarUrl={null}          // Renders initials fallback "SB"
+  timeLabel={formatRelativeTime(message.createdAt)}
+  body={message.text}
+  footer={<TicketAttachmentsList attachments={message.attachments} />}
+/>
+
+// While loading
+<ChatMessageRowSkeleton />
+```
+
+## Notes
+
+- Colors use ODS theme tokens exclusively (`text-ods-text-primary`, `text-ods-text-secondary`, `bg-ods-border`) — no raw color values.
+- Avatar sizing mirrors Slack's layout: `w-8 h-8` (32px) on mobile, `md:w-10 md:h-10` (40px) on desktop, `rounded-lg`, `object-cover`.
+- The `footer` prop is the **only** intentional surface-level variation point; all other markup is shared verbatim.
+
+**Source:** [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat-message-row.tsx)

package/src/components/chat/.chat-message-skeleton.md

@@ -1,40 +1,46 @@
-<!-- source-hash: dc7cb2f1d39ceeb5b0684dbef38a8d20 -->
-Animated loading skeleton components that simulate the layout of chat messages while content is being fetched, matching the `ChatMessageEnhanced` hanging-avatar layout.
+<!-- source-hash: a6dcb9f785576018e8095625642e2ea3 -->
+Skeleton loading components for chat message rows and lists, mirroring the layout of `ChatMessageEnhanced` and `ChatMessageList` with pulsing placeholder elements.
 
 ## Key Components
 
 ### `ChatMessageSkeleton`
-Renders a single animated placeholder message with pulsing blocks for the avatar, sender name, timestamp, and multi-line message content.
+Single message-row skeleton with an inline avatar (assistant only), name/timestamp placeholders, and configurable body lines. Uses percentage-based widths so placeholders reflow correctly on panel resize.
 
+**Props:**
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `className` | `string` | — | Additional CSS classes |
-| `showAvatar` | `boolean` | `true` | Whether to render the avatar skeleton |
-| `isUser` | `boolean` | `false` | Applies user-message styling (no card background, no avatar) |
-| `assistantType` | `'mingo' \| 'fae'` | `'fae'` | Controls avatar gradient — cyan for Mingo, pink for Fae |
+|---|---|---|---|
+| `showAvatar` | `boolean` | `true` | Show circular avatar placeholder |
+| `isUser` | `boolean` | `false` | Hides avatar for user-side messages |
+| `bodyLines` | `number` | `3` | Number of body line placeholders |
+| `className` | `string` | — | Additional class names |
 
 ### `ChatMessageListSkeleton`
-Renders a scrollable list of `ChatMessageSkeleton` items, mimicking a full chat viewport during initial load.
+Renders a configurable list of `ChatMessageSkeleton` rows. Supports two layout modes:
+- **Default** — bottom-anchors rows with inner scroll, matching `ChatMessageList`
+- **Fill mode** (`fill=true`) — top-anchors rows and clips overflow so the entire panel appears to be loading regardless of container height
 
+**Props:**
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `messageCount` | `number` | `6` | Number of skeleton messages to render |
-| `showAvatars` | `boolean` | `true` | Passed through to each `ChatMessageSkeleton` |
-| `assistantType` | `'mingo' \| 'fae'` | `'fae'` | Applied to all assistant messages |
-| `contentClassName` | `string` | — | Overrides default horizontal padding on the content wrapper |
+|---|---|---|---|
+| `messageCount` | `number` | `6` | Number of skeleton rows |
+| `showAvatars` | `boolean` | `true` | Forward avatar visibility to rows |
+| `fullWidth` | `boolean` | `false` | Drops `max-w-ods-content-narrow` column |
+| `bodyLines` | `number` | `3` | Forwarded to each `ChatMessageSkeleton` |
+| `fill` | `boolean` | `false` | Enable fill/clip layout mode |
+| `contentClassName` | `string` | — | Classes on the inner content column |
 
 ## Usage Example
 
 ```typescript
-// Single message skeleton (e.g. while streaming)
-<ChatMessageSkeleton assistantType="mingo" showAvatar />
-
-// Full chat list skeleton on initial page load
-<ChatMessageListSkeleton
-  messageCount={8}
-  assistantType="fae"
-  showAvatars={true}
-/>
-```
-
-> Every third message (`index % 3 === 0`) is rendered as a user bubble; the rest render as assistant messages with the appropriate Mingo/Fae avatar gradient.
+// Default paragraph-style skeleton list
+<ChatMessageListSkeleton messageCount={5} showAvatars />
+
+// Single-line messages (e.g. hero demo turns) — prevents oversized skeleton
+<ChatMessageListSkeleton bodyLines={1} messageCount={8} />
+
+// Fill mode: whole panel reads as loading
+<ChatMessageListSkeleton fill messageCount={12} fullWidth />
+
+// Individual row with one body line
+<ChatMessageSkeleton isUser bodyLines={1} />
+```

package/src/components/chat/.chat-panel-header-mobile.md

@@ -0,0 +1,46 @@
+<!-- source-hash: b2c65cbe56eb2aa7a9827bd4892f6e34 -->
+Mobile-specific chat panel header component that renders a full-screen-aware header with back navigation, title, contextual actions menu, and a mandatory close button for drawer dismissal.
+
+## Key Components
+
+### `ChatPanelHeaderMobile`
+
+The primary export. Renders a vertically-aligned header card with:
+
+- **Back chevron** — conditionally shown via `showBack`; uses a 44px outlined `Button` with `Chevron02LeftIcon`
+- **Title** — `text-h2` truncated text, bottom-aligned under a tall header via `xl` top padding
+- **Actions menu (`⋯`)** — an `ActionsMenuDropdown` built from view-dependent items (archive, restore, rename, open archive); hidden entirely when no items apply
+- **Close button** — `XmarkIcon` button; required on mobile since the full-screen drawer has no tappable backdrop
+
+### `ChatPanelHeaderMobileProps`
+
+Extends [`ChatPanelHeaderProps`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/chat/chat-panel-header.tsx) and adds an optional `className` for layout overrides.
+
+### Menu item construction
+
+Items are conditionally assembled based on current view state:
+
+| Condition | Item |
+|---|---|
+| `!showBack && onOpenArchive` | Chat archive |
+| `isArchivedView && onRestore` | Unarchive chat |
+| `!isArchivedView && onRename` | Rename chat |
+| `!isArchivedView && onArchive` | Archive chat |
+
+## Usage Example
+
+```typescript
+import { ChatPanelHeaderMobile } from './chat-panel-header-mobile'
+
+<ChatPanelHeaderMobile
+  title="Support Session"
+  showBack={false}
+  isArchivedView={false}
+  onClose={() => setDrawerOpen(false)}
+  onRename={() => openRenameDialog()}
+  onArchive={() => archiveChat(chatId)}
+  onOpenArchive={() => navigateTo('archive')}
+/>
+```
+
+> The orchestrator renders `ChatPanelHeaderMobile` on mobile viewports and the desktop bar at `md+`. The close button (`onClose`) should always be provided since the full-screen drawer has no visible backdrop.

package/src/components/chat/.chat-panel-header.md

@@ -0,0 +1,80 @@
+<!-- source-hash: 06fbb4632d6895d92e482f4903daf830 -->
+Responsive top-navigation bar for the chat panel, rendering the correct header layout across list, active-conversation, archived-conversation, and compose views — with adaptive mobile/desktop breakpoints and inline search support.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `ChatPanelHeader` | Component | Main header bar with back navigation, title, avatar, action buttons, and close |
+| `ChatPanelHeaderProps` | Interface | Full prop surface controlling layout, actions, search, and avatar |
+
+## Usage Example
+
+```typescript
+// List view (no back, with search + archive entry)
+<ChatPanelHeader
+  title="My Chats"
+  onClose={handleClose}
+  onOpenArchive={handleOpenArchive}
+  onToggleSearch={handleToggleSearch}
+  searchActive={isSearchOpen}
+  onSearchChange={handleSearchChange}
+  searchQuery={currentQuery}
+/>
+
+// Active conversation view
+<ChatPanelHeader
+  showBack
+  title="Support Thread"
+  subtitle="Jane Smith"
+  avatar={{ name: "Jane Smith", avatarUrl: "/avatars/jane.png" }}
+  onBack={handleBack}
+  onClose={handleClose}
+  onRename={handleRename}
+  onArchive={handleArchive}
+/>
+
+// Archived conversation (read-only)
+<ChatPanelHeader
+  showBack
+  title="Old Thread"
+  isArchivedView
+  onBack={handleBack}
+  onClose={handleClose}
+  onRestore={handleRestore}
+/>
+
+// Embedded/compact mode (skips mobile full-screen layout)
+<ChatPanelHeader
+  title="Preview"
+  compact
+  onClose={handleClose}
+/>
+```
+
+## Layout Behavior
+
+```mermaid
+graph TD
+    A[ChatPanelHeader] --> B{compact?}
+    B -->|false| C[ChatPanelHeaderMobile on small screens]
+    B -->|false| D[Compact bar on md+]
+    B -->|true| E[Compact bar at ALL widths]
+    D --> F{showBack?}
+    F -->|true| G[Back chevron + title + ellipsis menu]
+    F -->|false| H[Static title + search + archive clock]
+```
+
+**Right-hand action slots (desktop bar):**
+
+| Condition | Rendered control |
+|---|---|
+| `isArchivedView && onRestore` | Refresh/unarchive button |
+| `showBack && !isArchivedView` | ⋯ dropdown (rename / archive) |
+| `!showBack && onToggleSearch` | Search toggle (hidden when inline search open) |
+| `!showBack && onOpenArchive` | Clock/archive entry button |
+| Always | × close button |
+
+## Source
+
+[`chat-panel-header.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat-panel-header.tsx)

package/src/components/chat/.chat-sidebar-skeleton.md

@@ -1,52 +1,53 @@
-<!-- source-hash: aae524b6903a622a00d4f048e78ca2ef -->
-Skeleton loading components for the chat sidebar UI, providing animated placeholder states while chat dialog data is being fetched.
+<!-- source-hash: 1a8d84383a2cc399dcbc2df528219979 -->
+Loading state skeleton components for the chat sidebar, rendering animated placeholder UI while conversation data is being fetched.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `ChatSidebarSkeleton` | `React.ForwardRefExoticComponent` | Full sidebar skeleton with optional new chat button and configurable dialog count |
-| `DialogListItemSkeleton` | `React.ForwardRefExoticComponent` | Individual chat list item skeleton with animated title, timestamp, and chevron placeholders |
+### `DialogListItemSkeleton`
+A single row skeleton mimicking a chat conversation list item. Renders animated pulse placeholders for the title, timestamp, and chevron icon using `animate-pulse` on `bg-ods-border` elements.
 
-### Props
+**Props:**
+| Prop | Type | Description |
+|------|------|-------------|
+| `className` | `string?` | Additional CSS classes |
 
-**`ChatSidebarSkeletonProps`**
+### `ChatSidebarSkeleton`
+Full sidebar skeleton wrapping multiple `DialogListItemSkeleton` rows with an optional disabled "Start New Chat" button header.
 
+**Props:**
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `className` | `string` | — | Additional CSS classes |
-| `dialogCount` | `number` | `8` | Number of skeleton dialog items to render |
-| `showNewChatButton` | `boolean` | `true` | Toggle the disabled "Start New Chat" button header |
-
-**`DialogListItemSkeletonProps`**
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `className` | `string` | — | Additional CSS classes |
+| `className` | `string?` | — | Additional CSS classes |
+| `dialogCount` | `number` | `8` | Number of skeleton rows to render |
+| `showNewChatButton` | `boolean` | `true` | Whether to render the disabled new chat button |
 
 ## Usage Example
 
 ```typescript
 import { ChatSidebarSkeleton, DialogListItemSkeleton } from "./chat-sidebar-skeleton"
 
-// Full sidebar skeleton during data load
+// Full sidebar skeleton during initial load
 function ChatLayout() {
-  const { dialogs, isLoading } = useDialogs()
+  const { data, isLoading } = useConversations()
 
   if (isLoading) {
-    return (
-      <ChatSidebarSkeleton
-        dialogCount={5}
-        showNewChatButton={true}
-      />
-    )
+    return <ChatSidebarSkeleton dialogCount={6} showNewChatButton={true} />
   }
 
-  return <ChatSidebar dialogs={dialogs} />
+  return <ChatSidebar conversations={data} />
 }
 
-// Standalone skeleton item for custom lists
-function CustomList() {
-  return <DialogListItemSkeleton className="opacity-50" />
+// Single item skeleton for partial list loading
+function ConversationList() {
+  return (
+    <div>
+      {conversations.map(c => <ConversationItem key={c.id} {...c} />)}
+      {isFetchingMore && <DialogListItemSkeleton />}
+    </div>
+  )
 }
-```
+```
+
+Both components use `React.forwardRef` for DOM ref forwarding and accept standard `HTMLDivElement` props via spread. Styles follow the ODS design token conventions (`ods-bg`, `ods-border`, `ods-card`).
+
+**Source:** [`chat-sidebar-skeleton.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/chat-sidebar-skeleton.tsx)

package/src/components/chat/.chat-sidebar.md

@@ -1,48 +1,55 @@
-<!-- source-hash: eca198ef18bcc431169bc6caeb87161d -->
-A sidebar component for chat navigation that displays a list of dialogs, supports infinite scroll pagination, and provides controls for creating new chats.
+<!-- source-hash: 60628db258030b0c522169a464accc8d -->
+Renders a collapsible chat history sidebar with a dialog list, infinite scroll pagination, skeleton loading states, and an empty state view for the OpenFrame chat interface.
 
 ## Key Components
 
-### `ChatSidebar`
-The main container component that renders the sidebar with:
-- **New Chat button** — triggers `onNewChat` callback
-- **Dialog list** — scrollable list with infinite scroll via `IntersectionObserver`
-- **Empty state** — shown when no dialogs exist and no `children` are provided
-- **Custom content slot** — renders `children` instead of the dialog list when provided
-- **Loading skeleton** — displays `ChatSidebarSkeleton` when `isLoading` is true and no dialogs are present
-
-### `DialogListItem`
-A single chat entry in the sidebar list. Displays:
-- Chat title (truncated with tooltip)
-- Formatted timestamp (`MM/DD/YYYY, HH:MM`)
-- Unread message badge (capped at `99+`) or a chevron arrow when no unread messages exist
-- Active state with accent border and background highlight
+| Export | Type | Description |
+|---|---|---|
+| `ChatSidebar` | `forwardRef` component | Main sidebar container managing dialog list, loading, and empty states |
+| `DialogListItem` | `forwardRef` component | Individual chat entry row with title, timestamp, and unread badge |
+
+### `ChatSidebar` Props
+
+| Prop | Type | Description |
+|---|---|---|
+| `dialogs` | `Dialog[]` | List of chat sessions to render |
+| `activeDialogId` | `string` | Highlights the currently selected dialog |
+| `onNewChat` | `() => void` | Callback for the "Start New Chat" button |
+| `onDialogSelect` | `(id: string) => void` | Callback when a dialog row is clicked |
+| `isLoading` | `boolean` | Shows full skeleton when `true` and list is empty |
+| `isCreatingDialog` | `boolean` | Disables the new chat button during creation |
+| `hasNextPage` | `boolean` | Enables the `IntersectionObserver`-based infinite scroll trigger |
+| `isFetchingNextPage` | `boolean` | Shows skeleton rows at the bottom while fetching |
+| `onLoadMore` | `() => void` | Fired when the sentinel element enters the viewport |
+| `children` | `ReactNode` | Replaces the default dialog list with custom content |
 
 ## Usage Example
 
 ```typescript
-import { ChatSidebar } from "./chat-sidebar"
+import { ChatSidebar } from "@openframe-oss-lib/components"
+
+const dialogs = [
+  { id: "1", title: "Network Issue", timestamp: new Date(), unreadMessagesCount: 3 },
+  { id: "2", title: "Printer Setup", timestamp: new Date() },
+]
+
+export function AppLayout() {
+  const [activeId, setActiveId] = useState("1")
 
-function App() {
   return (
     <ChatSidebar
-      dialogs={[
-        { id: "1", title: "Network Issue", timestamp: new Date(), unreadMessagesCount: 3 },
-        { id: "2", title: "Server Setup", timestamp: new Date() },
-      ]}
-      activeDialogId="1"
-      isLoading={false}
-      isCreatingDialog={false}
+      dialogs={dialogs}
+      activeDialogId={activeId}
+      onNewChat={() => console.log("new chat")}
+      onDialogSelect={(id) => setActiveId(id)}
       hasNextPage={true}
       isFetchingNextPage={false}
-      onNewChat={() => console.log("New chat")}
-      onDialogSelect={(id) => console.log("Selected:", id)}
       onLoadMore={() => fetchNextPage()}
     />
   )
 }
 ```
 
-## Infinite Scroll
+> **Infinite scroll:** A sentinel `<div>` at the bottom of the list is observed via `IntersectionObserver` with a `100px` root margin. `onLoadMore` fires automatically when it enters the scroll container's viewport, provided `hasNextPage` is `true` and a fetch isn't already in progress.
 
-Pagination is handled automatically using an `IntersectionObserver` anchored to the bottom of the scroll container. When the sentinel element enters the viewport and `hasNextPage` is `true`, `onLoadMore` is called. Skeleton items are shown while `isFetchingNextPage` is active.
+**Source:** [`chat-sidebar.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat-sidebar.tsx)