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

package/src/components/ui/.organization-card.md

@@ -1,45 +1,64 @@
-<!-- source-hash: a5842b7f26b01448b4819804ae2a446d -->
-Reusable card component for displaying organization/client summary information in a grid or list layout, supporting optional navigation, action buttons, device counts, and customizable footer stats.
+<!-- source-hash: 3ad90c81666a2fe9bcd98d333ec8d564 -->
+A client-side React component that renders a styled card UI for displaying MSP organization details, supporting optional navigation links, action buttons, device counts, and configurable footer stats.
 
 ## Key Components
 
 ### Interfaces
-- **`Organization`** — Data model for an organization entity (id, name, imageUrl, industry, tier, devices, MRR, etc.)
-- **`OrganizationCardProps`** — Full prop interface including optional `href`, `actionButton`, `footerStats`, `customFooter`, and `deviceCount`
 
-### Component
-- **`OrganizationCard`** — Renders the card with three configurable zones:
-  - **Header** — `EntityImage` + name + subtitle (industry, tier, or website)
-  - **Body** — Optional 2-line clamped description
-  - **Footer** — `customFooter` node or auto-rendered `footerStats` array
-  - **Top-right overlay** — Either a device count badge (with `Monitor` icon) or an action button (ghost/primary variant)
+- **`Organization`** — Data model for an MSP organization, including `id`, `name`, `imageUrl`, `industry`, `tier`, `totalDevices`, `activeDevices`, `mrrUsd`, and an index signature for custom fields.
+- **`OrganizationCardProps`** — Props contract for the card, supporting:
+  - `organization` — Required organization data object
+  - `fetchedImageUrl` — Optional externally resolved image URL (overrides `organization.imageUrl`)
+  - `href` — Makes the card a navigable `Link`
+  - `actionButton` — Configurable icon button with `ghost` or `primary` variant (mutually exclusive with `deviceCount`)
+  - `footerStats` — Array of `{ icon, value, label }` stat items rendered in the card footer
+  - `customFooter` — Fully custom footer `ReactNode` override
+  - `deviceCount` — Displays a `Monitor` icon + count badge in the top-right corner
 
-When `href` is provided, the entire card is wrapped in a `Link` for navigation.
+### Exported Function
+
+- **`OrganizationCard`** — Main card component. Renders a bordered, rounded card with an `EntityImage`, name, subtitle (industry/tier/website), optional description, and footer. Wraps in a `<Link>` when `href` is provided.
 
 ## Usage Example
 
 ```typescript
+import { OrganizationCard } from "@openframe-oss-lib/ui"
+import { Trash2 } from "lucide-react"
+
+const org = {
+  id: "org_123",
+  name: "Acme Corp",
+  industry: "Healthcare",
+  description: "A leading healthcare provider.",
+  totalDevices: 42,
+}
+
+// Linkable card with device count
 <OrganizationCard
-  organization={{
-    id: "org_123",
-    name: "Acme Corp",
-    industry: "Manufacturing",
-    description: "A leading widget manufacturer.",
-    totalDevices: 42,
-  }}
+  organization={org}
   href="/organizations/org_123"
-  deviceCount={42}
-  footerStats={[
-    { icon: <DollarSign className="w-4 h-4" />, value: 1200, label: "MRR" },
-  ]}
+  deviceCount={org.totalDevices}
+/>
+
+// Card with action button and footer stats
+<OrganizationCard
+  organization={org}
+  showActionButton
   actionButton={{
-    icon: <Trash2 className="w-4 h-4" />,
-    label: "Remove",
+    icon: <Trash2 size={16} />,
+    label: "Remove organization",
     variant: "ghost",
-    onClick: (org, e) => handleRemove(org.id),
+    onClick: (org, e) => console.log("Remove", org.id),
   }}
-  showActionButton
+  footerStats={[
+    { value: 42, label: "devices" },
+    { value: "$1,200", label: "MRR" },
+  ]}
 />
 ```
 
-> **Note:** `deviceCount` takes display priority over `showActionButton` — if both are provided, only the device badge renders in the top-right corner.
+## Notes
+
+- `deviceCount` and `actionButton` are mutually exclusive — the action button only renders when `deviceCount` is `undefined`.
+- `customFooter` takes precedence over `footerStats` when both are provided.
+- Source: [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/components/organization-card.tsx)

package/src/components/ui/.page-actions.md

@@ -1,52 +1,66 @@
-<!-- source-hash: 70d0d7bf97f25795ba22d26ce08d067f -->
-Responsive page-level action bar component that renders action buttons in three layout variants (`icon-buttons`, `primary-buttons`, `menu-primary`), automatically adapting between desktop and mobile layouts with overflow menus.
+<!-- source-hash: 1ccbc3cff6ac7ff27e1641c46c70275a -->
+Responsive page-level action bar component that renders buttons, split-buttons, icon-only buttons, and dropdown submenus — adapting layout between desktop (inline buttons) and mobile (icon, "…" menu, or fixed bottom bar) based on the selected variant.
 
 ## Key Components
 
 ### Types
-- **`PageActionButton`** — Action descriptor supporting labels, icons, links (`href`), submenus, split-button icon actions, and visibility/rendering flags like `showOnlyMobile` and `iconOnlyOnDesktop`
-- **`PageActionsProps`** — Props for the main `PageActions` component
 
-### Components
-- **`PageActions`** — Root component; dispatches to the correct variant
-- **`IconButtonsVariant`** — Desktop: icon buttons + optional overflow menu. Mobile: single icon or merged `...` dropdown
-- **`PrimaryButtonsVariant`** — Desktop: labeled buttons sorted by variant. Mobile: fixed bottom bar
-- **`MenuPrimaryVariant`** — Desktop: `...` menu + accent-styled primary buttons. Mobile: all actions in a single `...` dropdown
+- **`PageActionButton`** — Configuration object for a single action. Supports labels, icons, variants, href links, tooltips, submenus (`ActionsMenuItem[]`), and split-button `iconAction`. Key flags: `showOnlyMobile`, `iconOnlyOnDesktop`, `mainDisabled`.
+- **`PageActionsProps`** — Props for the main `PageActions` export. Accepts `variant`, `actions`, `menuActions`, `selector`, and `className`.
 
-### Utilities
-- **`renderActionButton`** — Renders a `Button`, `SplitButton`, or submenu `ActionsMenuDropdown` based on action config
-- **`actionToMenuItems`** — Converts a `PageActionButton` to `ActionsMenuItem[]` for mobile dropdown merging
-- **`usePageActionsBottomPadding`** — Hook returning a Tailwind padding class to prevent content from being obscured by the mobile bottom bar
+### Exports
+
+- **`PageActions`** — Top-level component. Delegates to one of three layout variants based on the `variant` prop.
+
+### Internal Variants
+
+| Component | Desktop | Mobile |
+|---|---|---|
+| `IconButtonsVariant` (default) | Icon buttons + optional overflow menu | Single icon or "…" dropdown |
+| `PrimaryButtonsVariant` | Labeled/accent buttons | Fixed bottom bar |
+| `MenuPrimaryVariant` | "…" menu + accent buttons | "…" dropdown only |
+
+### Internal Helpers
+
+- **`renderActionButton`** — Wraps `renderRawActionButton` with an optional tooltip.
+- **`renderRawActionButton`** — Resolves the correct button type: `SplitButton`, chevron `ActionsMenuDropdown`, icon-only `Button`, or labeled `Button`.
+- **`actionToMenuItems`** — Converts a `PageActionButton` into `ActionsMenuItem[]` for mobile menus; flattens submenu children with parent label prefixes.
+- **`MobileBottomActions`** — Fixed `bottom-0` bar for the `primary-buttons` variant.
 
 ## Usage Example
 
 ```typescript
-import { PageActions, usePageActionsBottomPadding } from './page-actions'
-
-function MyPage() {
-  const bottomPad = usePageActionsBottomPadding('primary-buttons')
-
-  return (
-    <div className={bottomPad}>
-      <PageActions
-        variant="primary-buttons"
-        actions={[
-          {
-            label: 'Save',
-            variant: 'accent',
-            onClick: () => handleSave(),
-          },
-          {
-            label: 'More',
-            icon: <SettingsIcon />,
-            submenu: [
-              { id: 'export', label: 'Export', onClick: handleExport },
-              { id: 'delete', label: 'Delete', onClick: handleDelete },
-            ],
-          },
-        ]}
-      />
-    </div>
-  )
-}
+import { PageActions, type PageActionButton } from './page-actions'
+import { PlusIcon, TrashIcon } from '../icons'
+
+const actions: PageActionButton[] = [
+  {
+    label: 'New Item',
+    icon: <PlusIcon />,
+    variant: 'accent',
+    onClick: () => console.log('create'),
+    tooltip: 'Create a new item',
+  },
+  {
+    label: 'Delete',
+    icon: <TrashIcon />,
+    variant: 'outline',
+    iconOnlyOnDesktop: true,
+    onClick: () => console.log('delete'),
+  },
+]
+
+// icon-buttons (default): icon buttons on desktop, "..." menu on mobile
+<PageActions actions={actions} />
+
+// primary-buttons: full buttons on desktop, fixed bottom bar on mobile
+<PageActions variant="primary-buttons" actions={actions} />
+
+// menu-primary: overflow menu + accent buttons on desktop, "..." on mobile
+<PageActions
+  variant="menu-primary"
+  actions={actions}
+  menuActions={[{ items: [{ id: 'export', label: 'Export', onClick: () => {} }] }]}
+  selector={<TabSelector />}
+/>
 ```

package/src/components/ui/.page-loader.md

@@ -1,45 +1,62 @@
-<!-- source-hash: 1028d9cb0f96281d45d967924264b1cc -->
-A React component providing full-screen and compact loading states with customizable text and branded OpenFrame logo animation.
+<!-- source-hash: 069900935088b57e5ca42bc2d323e014 -->
+Full-page and compact loading state components that display an animated OpenFrame logo with customizable title and description text.
 
 ## Key Components
 
-- **`PageLoader`** - Full viewport loading component with centered content and animated logo
-- **`CompactPageLoader`** - Smaller version for use within containers or modals
-- **`PageLoaderProps`** - TypeScript interface defining customization options including title, description, styling, and icon visibility
+| Export | Type | Description |
+|---|---|---|
+| `PageLoader` | Component | Full viewport loading overlay with centered content |
+| `CompactPageLoader` | Component | Smaller loading indicator for inline containers |
+| `PageLoaderProps` | Interface | Shared props interface for both components |
+
+### `PageLoaderProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | `'Loading'` | Primary loading message |
+| `description` | `string` | `'Getting your data ready'` | Secondary descriptive text |
+| `className` | `string` | — | Additional CSS classes for the container |
+| `showIcon` | `boolean` | `true` | Toggles the animated OpenFrame logo |
 
 ## Usage Example
 
 ```typescript
-import { PageLoader, CompactPageLoader } from './components/ui/page-loader'
+import { PageLoader, CompactPageLoader } from '@openframe-oss-lib/ui'
 
-// Full page loading state
+// Full-screen loader during initial data fetch
 function App() {
-  const [isLoading, setIsLoading] = useState(true)
-  
   if (isLoading) {
     return (
-      <PageLoader 
-        title="Loading Dashboard"
-        description="Fetching your data..."
-        className="bg-gray-50"
+      <PageLoader
+        title="Connecting"
+        description="Fetching your workspace data"
       />
     )
   }
-  
   return <Dashboard />
 }
 
-// Compact loader for components
-function DataTable() {
+// Compact loader inside a panel or widget
+function DataPanel() {
   return (
-    <div className="border rounded-lg">
-      <CompactPageLoader 
-        title="Loading table data"
-        showIcon={false}
-      />
-    </div>
+    <CompactPageLoader
+      title="Refreshing"
+      description="Syncing latest records"
+      showIcon={true}
+    />
   )
 }
+
+// Icon-free loader with custom styling
+<PageLoader
+  title="Please wait"
+  showIcon={false}
+  className="bg-ods-surface"
+/>
 ```
 
-Both components feature the OpenFrame logo with pulse animation, customizable text content, and responsive design using Tailwind CSS classes with the design system's color tokens.
+**Key differences:** `PageLoader` uses `min-h-screen` to fill the viewport and always shows `description`; `CompactPageLoader` uses `p-12` padding and renders `description` only when provided.
+
+## Source
+
+[`page-loader.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/page-loader.tsx)

package/src/components/ui/.password-input.md

@@ -0,0 +1,30 @@
+<!-- source-hash: 81c75ceb63c114f45f4ca4dd6b9f21f4 -->
+A password input component that extends the base `Input` with a show/hide toggle button, rendering an eye icon to reveal or conceal the entered value.
+
+## Key Components
+
+- **`PasswordInput`** — A `forwardRef` component wrapping the base `Input`, managing visibility state and injecting an icon toggle as `endAdornment`.
+- **`PasswordInputProps`** — Extends `InputProps`, omitting `type` and `endAdornment` (both are controlled internally).
+
+## Usage Example
+
+```typescript
+import { PasswordInput } from "./password-input"
+
+function LoginForm() {
+  return (
+    <PasswordInput
+      placeholder="Enter your password"
+      disabled={false}
+      className="w-full"
+    />
+  )
+}
+```
+
+## Behavior Notes
+
+- Toggles between `type="password"` and `type="text"` based on internal `visible` state.
+- The toggle button uses `tabIndex={-1}` to keep it out of the tab order and `aria-label` for accessibility (`"Show password"` / `"Hide password"`).
+- Applies `text-ellipsis` via `className` to truncate long values when the field is not focused.
+- The toggle button is automatically disabled when the `disabled` prop is passed to the component.

package/src/components/ui/.phone-input.md

@@ -1,44 +1,40 @@
-<!-- source-hash: 8f44dd654f7205b5e41cde63c6ee32dd -->
-A composite phone number input component combining a country selector dropdown with a phone number text field, featuring debounced validation using `libphonenumber-js`.
+<!-- source-hash: 32581c5a8247511ad64b8ad45ce014af -->
+A composite phone input component combining a country code selector with a phone number text field, featuring debounced validation using `libphonenumber-js`.
 
 ## Key Components
 
 ### `PhoneInput` (main export)
-A controlled input component that renders a country code selector and phone number field side-by-side.
+
+A controlled input component that renders a country dial-code `Select` alongside a `tel` input. Validates the phone number against the selected country after a 300ms debounce on change, and immediately on blur.
 
 **Props (`PhoneInputProps`):**
 
 | Prop | Type | Description |
-|------|------|-------------|
-| `value` | `string` | Current phone number value |
-| `countryCode` | `CountryCode` | Selected country (ISO code) |
-| `onPhoneChange` | `(phone: string) => void` | Called on phone input change |
-| `onCountryChange` | `(country: CountryCode) => void` | Called on country selection |
-| `onValidationChange` | `(isInvalid: boolean) => void` | Optional validation state callback |
+|---|---|---|
+| `value` | `string` | Current phone number string |
+| `countryCode` | `CountryCode` | ISO country code (from `libphonenumber-js`) |
+| `onPhoneChange` | `(phone: string) => void` | Called when phone input changes |
+| `onCountryChange` | `(country: CountryCode) => void` | Called when country selection changes |
+| `onValidationChange` | `(isInvalid: boolean) => void` | Optional callback for validation state |
 | `disabled` | `boolean` | Disables both inputs |
-| `placeholder` | `string` | Input placeholder text |
-| `onKeyDown` | `React.KeyboardEvent handler` | Key event passthrough |
+| `placeholder` | `string` | Input placeholder (default: `"Phone Number (optional)"`) |
+| `onKeyDown` | `React.KeyboardEventHandler` | Key event passthrough |
 
 ### `CountryOption` (internal)
-Renders a single country row inside the dropdown showing flag, dial code, and country name.
 
-### Validation Behavior
-- Input is restricted to digits, spaces, hyphens, and parentheses
-- Validation triggers via debounce (300ms) after 4+ digits are entered
-- Immediate validation fires on input blur
-- Empty input clears any invalid state without triggering validation
+Renders a single `SelectItem` with the country's flag emoji, dial code, and name with overflow truncation.
 
 ## Usage Example
 
 ```typescript
-import { PhoneInput } from './phone-input'
+import { PhoneInput } from '@/components/ui/phone-input'
 import { useState } from 'react'
 import type { CountryCode } from 'libphonenumber-js'
 
 function ContactForm() {
   const [phone, setPhone] = useState('')
   const [country, setCountry] = useState<CountryCode>('US')
-  const [hasError, setHasError] = useState(false)
+  const [phoneInvalid, setPhoneInvalid] = useState(false)
 
   return (
     <PhoneInput
@@ -46,9 +42,11 @@ function ContactForm() {
       countryCode={country}
       onPhoneChange={setPhone}
       onCountryChange={setCountry}
-      onValidationChange={setHasError}
-      placeholder="Phone Number (optional)"
+      onValidationChange={setPhoneInvalid}
+      placeholder="Enter phone number"
     />
   )
 }
-```
+```
+
+**Validation behaviour:** Empty fields are treated as valid. Validation fires after 4+ digits are entered (debounced) or on blur, and highlights the input with `!border-ods-warning` when invalid.

package/src/components/ui/.portal-container.md

@@ -0,0 +1,43 @@
+<!-- source-hash: cd6ef482a4e9898cb3090a6c0ba0b8ae -->
+Provides a React context and hook for controlling where Radix UI overlay components (dropdowns, tooltips, etc.) are portaled, enabling stacking-context-aware positioning without z-index escalation.
+
+## Key Components
+
+- **`PortalContainerContext`** — React context holding an `HTMLElement | null` value. When `null`, Radix falls back to its default `document.body` portal target. When set to a specific DOM node, overlays portal into that node and naturally inherit its stacking context.
+- **`usePortalContainer()`** — Convenience hook that reads the current portal container from context.
+
+## Usage Example
+
+```typescript
+// Wrap a high-z surface (e.g. a chat drawer) with a provider pointing
+// at a ref inside that same surface, then consume it in overlay components.
+
+function ChatDrawer() {
+  const [container, setContainer] = React.useState<HTMLElement | null>(null)
+
+  return (
+    <div ref={setContainer} className="drawer">
+      <PortalContainerContext.Provider value={container}>
+        <DrawerContent />
+      </PortalContainerContext.Provider>
+    </div>
+  )
+}
+
+// Inside DrawerContent — pass the container to Radix portal props:
+function DropdownExample() {
+  const portalContainer = usePortalContainer()
+
+  return (
+    <DropdownMenu.Portal container={portalContainer}>
+      <DropdownMenu.Content>...</DropdownMenu.Content>
+    </DropdownMenu.Portal>
+  )
+}
+```
+
+## Notes
+
+- Radix uses `position: fixed` internally, so portaling into a nested node does **not** re-introduce `overflow: hidden` clipping — content still escapes ancestor scroll containers.
+- Providing `null` (the default) leaves Radix behavior unchanged everywhere a provider is absent.
+- Source: [`portal-container.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/portal-container.tsx)

package/src/components/ui/.progress-bar.md

@@ -1,50 +1,63 @@
-<!-- source-hash: e7dc6507dbb40dd8dffb5171634e1bd5 -->
-Segmented progress bar component that visualizes a numeric value (0–100) using dynamically calculated fill segments, with responsive sizing and threshold-based color coding.
+<!-- source-hash: f0113fcceed7014d22166d2c03afc5d5 -->
+Segmented progress bar component with responsive sizing, threshold-based color states, and support for both normal and inverted value semantics.
 
 ## Key Components
 
-### `ProgressBarProps`
+### `ProgressBar` (exported component)
+
+A responsive, segmented progress bar that dynamically calculates the number of segments based on container width using a `ResizeObserver`. Color state is driven by configurable thresholds and ODS design tokens.
+
+**Props:**
+
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `progress` | `number` | — | Value from 0–100 to display |
+|---|---|---|---|
+| `progress` | `number` | — | Current value (0–100) |
 | `warningThreshold` | `number` | `75` | Threshold for warning color |
 | `criticalThreshold` | `number` | `90` | Threshold for critical color |
-| `segmentWidth` | `number` | `3.43px` | Desktop segment width |
-| `mobileSegmentWidth` | `number` | `5px` | Mobile segment width |
-| `segmentGap` | `number` | `2px` | Gap between segments |
-| `height` | `number` | `24px` | Desktop bar height |
-| `mobileHeight` | `number` | `8px` | Mobile bar height |
-| `inverted` | `boolean` | `false` | Flips color logic (high = good) |
+| `segmentWidth` | `number` | `3.43` | Desktop segment width (px) |
+| `mobileSegmentWidth` | `number` | `5` | Mobile segment width (px) |
+| `segmentGap` | `number` | `2` | Gap between segments (px) |
+| `height` | `number` | `24` | Desktop segment height (px) |
+| `mobileHeight` | `number` | `8` | Mobile segment height (px) |
+| `inverted` | `boolean` | `false` | Reverses color semantics (high = green, low = red) |
 
-### Color Logic
-- **Normal** (e.g., disk usage): green → warning → red as value increases
-- **Inverted** (e.g., battery health): red → warning → green as value increases
-- Uses ODS design tokens: `--ods-attention-green-success`, `--color-warning`, `--ods-attention-red-error`
+**Color mapping (normal mode):**
+- `≥ criticalThreshold` → `--color-error` (red)
+- `≥ warningThreshold` → `--color-warning` (yellow)
+- Below both → `--color-success` (green)
 
-### Responsive Behavior
-Uses `useMdUp()` hook to switch between desktop and mobile segment dimensions. A `ResizeObserver` dynamically recalculates segment count based on container width, ensuring pixel-perfect fills on any layout.
+**Inverted mode** reverses this — useful for metrics like battery health where higher is better.
 
 ## Usage Example
 
 ```typescript
-// Normal mode — disk usage (high values = bad)
+// Disk usage — high values are bad (normal mode)
 <ProgressBar progress={85} warningThreshold={70} criticalThreshold={90} />
 
-// Inverted mode — battery health (high values = good)
+// Battery health — high values are good (inverted mode)
 <ProgressBar
-  progress={25}
-  warningThreshold={40}
+  progress={45}
+  warningThreshold={30}
   criticalThreshold={80}
-  inverted={true}
+  inverted
 />
 
 // Custom sizing
 <ProgressBar
   progress={60}
-  segmentWidth={5}
-  mobileSegmentWidth={8}
-  height={32}
-  mobileHeight={12}
+  segmentWidth={4}
+  mobileSegmentWidth={6}
+  height={16}
+  mobileHeight={6}
   segmentGap={3}
 />
-```
+```
+
+## Notes
+
+- Uses `useMdUp` hook to switch between desktop and mobile dimensions
+- Segment count recalculates automatically on container resize via `ResizeObserver`
+- Unfilled segments render with `--color-bg-surface-active`
+- Requires a Client Component context (`'use client'`)
+
+**Source:** [`progress-bar.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/progress-bar.tsx)

package/src/components/ui/.release-changelog-section.md

@@ -1,24 +1,23 @@
-<!-- source-hash: 7fa49d7ef85ecd5ac09ebac9a632fbac -->
-Renders a collapsible/expandable changelog section for product releases, supporting three display modes: default (always visible), collapsible (toggle open/closed), and preview-first (show first entry with fade-masked overflow).
+<!-- source-hash: 911c333ce08edfbeee406277154d07b8 -->
+Renders a collapsible/expandable changelog section for product releases, displaying a titled list of `ChangelogEntry` items with optional progressive disclosure and rich markdown support.
 
 ## Key Components
 
-### `ReleaseChangelogSection` (exported)
-Main component accepting these key props:
+**`ReleaseChangelogSection`** — Primary export. Accepts a `title`, array of `ChangelogEntry` items, and several display-mode flags:
 
 | Prop | Type | Description |
-|------|------|-------------|
-| `title` | `string` | Section heading text |
-| `entries` | `ChangelogEntry[]` | List of changelog items to render |
-| `isBreaking` | `boolean` | Applies red styling for breaking changes |
-| `collapsible` | `boolean` | Enables toggle open/close mode (wins over `previewFirst`) |
-| `defaultCollapsed` | `boolean` | Initial collapsed state when `collapsible=true` (default: `true`) |
-| `previewFirst` | `boolean` | Shows first entry fully, fades remaining with "Show N more" toggle |
-| `icon` | `React.ReactNode` | Optional Lucide icon rendered before title |
-| `SimpleMarkdownRenderer` | `ComponentType` | Injected markdown renderer for entry descriptions |
-
-### `ChangelogEntryList` (internal)
-Shared list renderer used by both default and preview-first branches. Renders each `ChangelogEntry` as a left-bordered list item with bold title and markdown-rendered description, with responsive typography tokens pinned via Tailwind `[&_p]:!` overrides.
+|---|---|---|
+| `collapsible` | `boolean` | Toggle section open/closed via title row button |
+| `defaultCollapsed` | `boolean` | Initial collapsed state (default: `true`) |
+| `previewFirst` | `boolean` | Shows first entry in full, fades remaining entries behind a "Show N more" toggle |
+| `isBreaking` | `boolean` | Renders title in error color for breaking changes |
+| `icon` | `ReactNode` | Lucide icon rendered inline before the title |
+| `MarkdownRenderer` | `ComponentType` | Defaults to `RichMarkdownRenderer`; swap for custom implementations |
+| `hideTitle` | `boolean` | Suppresses the title row entirely |
+
+> **Note:** When both `collapsible` and `previewFirst` are passed, `collapsible` takes precedence.
+
+**`ChangelogEntryList`** *(internal)* — Renders a `<ul>` of bordered entries, each with a bold markdown-rendered `title` and optional `description` body. Typography is pinned via Tailwind `[&_p]:!` overrides to ODS token scales (`text-h3`/`text-h4`) so the `MarkdownRenderer`'s default paragraph styles don't override responsive breakpoints.
 
 ## Usage Example
 
@@ -26,26 +25,33 @@ Shared list renderer used by both default and preview-first branches. Renders ea
 import { ReleaseChangelogSection } from './release-changelog-section';
 import { Sparkles } from 'lucide-react';
 
+// Default collapsible section
 <ReleaseChangelogSection
   title="New Features"
   entries={[
-    { title: "AI Ticketing", description: "Automated ticket routing via Mingo AI." },
-    { title: "Client Portal", description: "Fae self-service dashboard launched." },
+    { title: "AI-powered ticket routing", description: "Routes tickets to the right queue automatically." },
+    { title: "[Dashboard redesign](https://example.com)", description: "Faster load times and improved layout." },
   ]}
-  icon={<Sparkles className="w-5 h-5" />}
+  icon={<Sparkles className="h-4 w-4" />}
+  collapsible
+  defaultCollapsed={false}
+/>
+
+// Preview-first mode (fades entries after the first)
+<ReleaseChangelogSection
+  title="Bug Fixes"
+  entries={fixes}
   previewFirst
-  SimpleMarkdownRenderer={MyMarkdownRenderer}
 />
 
-// Collapsible breaking-changes section
+// Breaking changes section
 <ReleaseChangelogSection
   title="Breaking Changes"
-  entries={breakingEntries}
+  entries={breaking}
   isBreaking
-  collapsible
-  defaultCollapsed={false}
-  SimpleMarkdownRenderer={MyMarkdownRenderer}
 />
 ```
 
-> **Note:** When both `collapsible` and `previewFirst` are passed, `collapsible` takes precedence. The `previewFirst` fade toggle resets automatically when `entries.length` changes.
+## Source
+
+[`release-changelog-section.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/release-changelog-section.tsx)