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

package/src/components/profile/.ProfileLoadingSkeleton.md

@@ -1,43 +1,44 @@
-<!-- source-hash: 1652a2fc27882d2f080c7367aefb18e6 -->
-A React loading skeleton component that displays animated placeholder elements while profile data is being fetched, providing visual feedback during loading states.
+<!-- source-hash: 562bc3a2494ee1c2637528e67f5924fc -->
+A React skeleton loading component that renders an animated placeholder UI for profile content while data is being fetched.
 
 ## Key Components
 
-**ProfileLoadingSkeleton**
-- Main component that renders skeleton placeholders
-- Takes optional `className` prop for styling customization
-- Creates animated placeholder elements mimicking profile layout
+- **`ProfileLoadingSkeleton`** — Named export functional component that renders a two-section animated skeleton:
+  - **Header skeleton** — Circular avatar placeholder (`h-16 w-16`) alongside two text line placeholders
+  - **Content skeleton** — Three progressively narrower text line placeholders (`full`, `3/4`, `1/2` widths)
 
-**Props Interface**
-- `ProfileLoadingSkeletonProps` - Defines optional className string prop
+- **`ProfileLoadingSkeletonProps`** — Interface accepting an optional `className` string for layout customization
+
+- **`cn`** utility — Merges Tailwind class names, allowing consumers to extend or override base styles
 
 ## Usage Example
 
 ```typescript
 import { ProfileLoadingSkeleton } from './components/ProfileLoadingSkeleton'
 
+// Basic usage
 function ProfilePage() {
-  const { data: profile, isLoading } = useProfile()
-  
+  const { data, isLoading } = useProfile()
+
   if (isLoading) {
-    return (
-      <div className="container mx-auto p-4">
-        <ProfileLoadingSkeleton className="max-w-md" />
-      </div>
-    )
+    return <ProfileLoadingSkeleton />
   }
-  
-  return <ProfileDisplay profile={profile} />
+
+  return <ProfileCard data={data} />
 }
 
-// Custom styling example
-function CustomProfileSkeleton() {
+// With custom className for layout overrides
+function SidebarProfile() {
   return (
-    <ProfileLoadingSkeleton 
-      className="bg-white rounded-lg p-6 shadow-sm" 
-    />
+    <ProfileLoadingSkeleton className="max-w-sm px-4" />
   )
 }
 ```
 
-The component features a header section with circular avatar placeholder and text lines, followed by content area with varying width placeholder lines. All elements use `animate-pulse` for smooth loading animations and `bg-gray-200` for consistent skeleton styling.
+## Notes
+
+- Uses the `ods-skeleton` design token (via `bg-ods-skeleton`) for consistent skeleton coloring across the OpenFrame Design System
+- Animation is handled entirely via Tailwind's `animate-pulse` — no additional animation dependencies required
+- The `className` prop is merged at the root `div`, making it straightforward to control width, padding, or margin from the parent
+
+**Source:** [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ProfileLoadingSkeleton.tsx)

package/src/components/related-content/.index.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 0d5d4e7429863e3d1ee5b0efa2bea571 -->
+Barrel export file for the `related-content` component subpath, re-exporting all public API surface from the `related-content-section` module.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `RelatedContentSection` | Component | Main component for rendering a section of related content cards |
+| `GROUP_PAGE_SIZE` | Constant | Pagination size constant for grouped content display |
+| `RelatedContentSectionProps` | Type | Props interface for `RelatedContentSection` |
+| `CardLinkProvider` | Type | Provider component type for card link rendering |
+| `CardLinkProviderProps` | Type | Props interface for `CardLinkProvider` |
+| `CardLinkAnchorProps` | Type | Props interface for anchor elements within card links |
+| `AdminCampaignCardSlot` | Type | Slot type for admin campaign card customization |
+
+## Usage Example
+
+```typescript
+import {
+  RelatedContentSection,
+  GROUP_PAGE_SIZE,
+  type RelatedContentSectionProps,
+  type CardLinkProvider,
+} from '@flamingo-stack/openframe-frontend-core/components/related-content'
+
+const linkProvider: CardLinkProvider = ({ href, children }) => (
+  <a href={href}>{children}</a>
+)
+
+const props: RelatedContentSectionProps = {
+  items: contentItems,
+  pageSize: GROUP_PAGE_SIZE,
+  cardLinkProvider: linkProvider,
+}
+
+<RelatedContentSection {...props} />
+```
+
+## Source
+
+[`index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)

package/src/components/related-content/.related-content-section.md

@@ -0,0 +1,62 @@
+<!-- source-hash: fd0a68c39b09e2977a51c082ec62bbc0 -->
+Renders grouped content references using canonical card components, supporting three data modes: controlled (explicit refs), suggestion (self-fetched via API), and SSR-hydrated suggestion (server-prefetched with client hydration).
+
+## Key Components
+
+### Exported Types & Interfaces
+
+- **`CardLinkAnchorProps`** — Anchor prop bundle (`href`, `target`, `rel`, `onClick`) passed to per-card link surfaces
+- **`CardLinkProviderProps` / `CardLinkProvider`** — Render-prop component type for host-injected navigation logic (keeps hook calls inside the injected component)
+- **`AdminCampaignCardSlot`** — Optional host-injected `{ Card, Skeleton }` pair for the admin-only `marketing_campaign` type
+
+### Internal Functions
+
+- **`DefaultLinkPropsProvider`** — Standalone embed default: same-tab for relative URLs, new tab for cross-origin (via `decideNewTab`, no router dependency)
+- **`defaultResolveHref`** — Returns the ref's stored `url` and `targetPlatform` as-is; hubs override this with domain-aware recomposition
+- **`renderSkeletonForType`** — Per-type skeleton dispatch matching each card's exact size to eliminate layout shift on data resolve
+- **`CardForType`** — Pure function component (zero hook calls) dispatching the correct sized card per content type
+
+## Usage Example
+
+```typescript
+// Controlled mode — render explicit refs
+<RelatedContentSection
+  contentRefs={myRefs}
+  apiBaseUrl="https://api.example.com"
+/>
+
+// Suggestion mode — self-fetch from the 5-tier engine
+<RelatedContentSection
+  entityType="blog_post_existing"
+  entityId="post-123"
+  apiBaseUrl="https://api.example.com"
+  minResults={5}
+/>
+
+// SSR-hydrated — skip first client fetch
+<RelatedContentSection
+  entityType="blog_post_existing"
+  entityId="post-123"
+  apiBaseUrl="https://api.example.com"
+  initialItems={serverFetchedRefs}
+/>
+
+// Hub embed with custom link provider and campaign card
+<RelatedContentSection
+  entityType="investor_update"
+  entityId="update-42"
+  apiBaseUrl="https://api.example.com"
+  LinkProvider={HubNavLinkProvider}
+  resolveHref={buildContentURL}
+  adminCampaignCard={{ Card: CampaignCard, Skeleton: CampaignCardSkeleton }}
+/>
+```
+
+## Data Flow & Architecture Notes
+
+- **No `react-query` dependency** — uses `useSelfFetch` (plain `fetch`) so embedders need no `QueryClientProvider`
+- **Deep card imports** (not the chat barrel) keep this component's source graph react-query-free at the import level
+- **Group layout/card sizing** delegated entirely to `CONTENT_REF_GROUPS` — no per-type layout logic lives here
+- **Lockstep sibling**: `CardForType` (sized cards) mirrors `CHAT_CARD_REGISTRY` in `../chat/entity-cards/dispatch.tsx` (compact `size='sm'`); register new fetch-mode types in **both** dispatchers
+
+**Source:** [`related-content-section.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/related-content-section.tsx)

package/src/components/shared/.article-author-byline.md

@@ -0,0 +1,56 @@
+<!-- source-hash: dcbaab437550f57b36728f8f0999a86c -->
+Shared author byline card for article-shaped detail pages (blog posts, product releases, onboarding guides, investor updates). Designed for embed-readiness across multiple host apps without requiring Next.js or a `ChatRuntime` provider.
+
+## Key Components
+
+### `ArticleAuthorBylineProps`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `author` | `string \| null` | Required display name; returns `null` when empty |
+| `avatar` | `string \| null` | Avatar URL; falls back to a `User` icon placeholder |
+| `bio` | `string \| null` | Bio paragraph rendered below the name |
+| `jobTitle` | `string \| null` | Job title rendered under the author name |
+| `publishedAt` | `string \| Date \| null` | ISO string or Date; formatted as "Month D, YYYY" (UTC-stable) |
+| `href` | `string \| null` | Optional link wrapping the author name |
+| `fallbackBio` | `string \| null` | Italic fallback text when `bio` is absent; hosts inject platform-specific copy |
+| `size` | `'md' \| 'lg'` | Avatar size — `md` = 56px (default), `lg` = 64px |
+| `proxyImageUrl` | `(url: string) => string` | Host-injected image URL mapper; takes precedence over ambient runtime proxy |
+
+### `ArticleAuthorByline`
+
+Main exported component. Renders an avatar, name, optional date/job title, and bio. Avatar URLs are proxied through the optional ambient `ChatRuntime` (`imageProxyUrlPrefix`) or a host-injected `proxyImageUrl` — falls back to the raw URL when neither is available.
+
+### `formatDate` (internal)
+
+Formats a `string | Date` to `"Month D, YYYY"` using `timeZone: 'UTC'` to prevent SSR/client hydration mismatches (React error #418) near midnight boundaries.
+
+## Usage Example
+
+```typescript
+import { ArticleAuthorByline } from 'openframe-oss-lib/components/article-author-byline'
+
+// Basic usage
+<ArticleAuthorByline
+  author="Jane Smith"
+  avatar="https://cdn.example.com/avatars/jane.jpg"
+  jobTitle="Senior Engineer"
+  publishedAt="2024-06-15"
+  href="/authors/jane-smith"
+  bio="Jane writes about distributed systems and developer tooling."
+  size="lg"
+/>
+
+// With host-injected fallback bio (e.g. from hub app-config)
+<ArticleAuthorByline
+  author="Jane Smith"
+  publishedAt={new Date()}
+  fallbackBio="Contributing author on the Flamingo platform."
+  proxyImageUrl={(url) => `https://img-proxy.example.com/?url=${url}`}
+/>
+
+// Returns null — no card rendered
+<ArticleAuthorByline author={null} />
+```
+
+**Source:** [`article-author-byline.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/article-author-byline.tsx)

package/src/components/shared/.detail-page-skeleton.md

@@ -1,51 +1,40 @@
-<!-- source-hash: d3a9248386a37f94266fe130168f8cb2 -->
-A client-side React component that provides a skeleton loading state for detail pages, simulating the layout of content-heavy pages like product details, case studies, or articles.
+<!-- source-hash: 0f15139d09909f034ccba359c69226cf -->
+Animated loading skeleton for detail/article pages, providing placeholder UI while content is being fetched.
 
 ## Key Components
 
-- **DetailPageSkeleton** - Main skeleton component with configurable metadata columns and image gallery
-- **DetailPageSkeletonProps** - Interface defining optional configuration props
-  - `metadataColumns` - Number of metadata grid columns (default: 4)
-  - `showImageGallery` - Toggle for horizontal image gallery vs featured image (default: true)
+### `DetailPageSkeletonProps`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `metadataColumns` | `number` | `4` | Number of metadata grid columns |
+| `showImageGallery` | `boolean` | `true` | Toggles horizontal image gallery vs. featured image skeleton |
+| `bare` | `boolean` | `false` | Renders skeleton blocks only, without the built-in `PageLayout` wrapper |
 
-The component renders animated placeholder blocks for:
-- Title section
-- Category tags
-- Configurable metadata grid
-- Image gallery or featured image
-- Multiple content sections with headings and paragraphs
+### `DetailPageSkeleton`
+The main export. Renders a pulsing skeleton layout composed of:
+- **Title block** — full-width heading placeholder
+- **Category tags** — row of tag-shaped placeholders
+- **Metadata grid** — dynamic column count via `metadataColumns`
+- **Image gallery or featured image** — toggled by `showImageGallery`
+- **Content sections** — three repeating section/paragraph blocks
+
+When `bare = false` (default), the skeleton is wrapped in a self-contained `PageLayout` at the hub article width (`max-w-[1280px]`). Set `bare = true` when the caller already provides a page shell, ensuring the loading state inherits the same width, padding, and `min-height` as the loaded page.
 
 ## Usage Example
 
 ```typescript
-import { DetailPageSkeleton } from './detail-page-skeleton';
-
-// Default configuration (4 columns, with image gallery)
-function ProductPage() {
-  return (
-    <div>
-      {loading ? (
-        <DetailPageSkeleton />
-      ) : (
-        <ProductDetails data={product} />
-      )}
-    </div>
-  );
-}
-
-// Custom configuration for case study pages
-function CaseStudyPage() {
-  return (
-    <div>
-      {loading ? (
-        <DetailPageSkeleton 
-          metadataColumns={3}
-          showImageGallery={false} // Shows featured image instead
-        />
-      ) : (
-        <CaseStudyContent data={caseStudy} />
-      )}
-    </div>
-  );
-}
-```
+// Default — self-contained with PageLayout wrapper
+<DetailPageSkeleton />
+
+// Match a gallery-less case study page
+<DetailPageSkeleton showImageGallery={false} metadataColumns={3} />
+
+// Inside a caller-supplied shell (e.g. during streaming SSR)
+<PageShell>
+  <DetailPageSkeleton bare />
+</PageShell>
+```
+
+## Source
+
+[`detail-page-skeleton.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/detail-page-skeleton.tsx)

package/src/components/shared/.media-gallery-strip.md

@@ -0,0 +1,43 @@
+<!-- source-hash: fb39f9743352e03b32dfac5b92ed2410 -->
+Horizontal-scroll media strip that renders mixed still-image and video tiles, opening a lightbox modal for images and playing clips inline.
+
+## Key Components
+
+### Interfaces
+
+- **`MediaGalleryStripItem`** — Shape of each media item: `media_type`, `media_url`, optional `title`, and optional stable `id`
+- **`MediaGalleryStripProps`** — Props for the strip: an `items` array and an optional `className`
+
+### Exports
+
+- **`MediaGalleryStrip`** — Primary component; renders a horizontally-scrollable row of 240×200 tiles
+- **`isGalleryImage`** *(internal)* — Returns `true` for any `media_type` that is not `"video"` or `"demo"`
+
+### Behavior
+
+- **Image tiles** render as accessible `<button>` elements (keyboard focusable, `aria-label` included) that open `ImageGalleryModal` at the correct lightbox index, computed against image-only items (skipping video tiles to avoid off-by-one bugs)
+- **Video tiles** render `<Video url={...} layout="native" />` inline with its own native controls
+- Returns `null` when `items` is empty or undefined
+
+## Usage Example
+
+```typescript
+import { MediaGalleryStrip, MediaGalleryStripItem } from './media-gallery-strip';
+
+const media: MediaGalleryStripItem[] = [
+  { id: 'img-1', media_type: 'screenshot', media_url: '/shots/dashboard.png', title: 'Dashboard' },
+  { id: 'vid-1', media_type: 'video',      media_url: '/clips/demo.mp4',      title: 'Demo' },
+  { id: 'img-2', media_type: 'screenshot', media_url: '/shots/settings.png',  title: 'Settings' },
+];
+
+export default function ReleasePage() {
+  return (
+    <MediaGalleryStrip
+      items={media}
+      className="py-4"
+    />
+  );
+}
+```
+
+> **Note:** The lightbox index tracks only image-type items — clicking the third tile (an image) correctly opens the modal at index `1`, not index `2`, regardless of how many video tiles precede it.

package/src/components/shared/delivery/.delivery-lists.md

@@ -1,39 +1,40 @@
-<!-- source-hash: a856dcd91dfe86722b63f8f7f40c9eea -->
-Renders the delivery section body with two filterable data tables — "Recently Completed" and "Active Tasks" — fetched from configurable API endpoints and driven by URL search parameters.
+<!-- source-hash: ad9149ea5e08cab5bb6c603f98a042bd -->
+Renders the delivery section body with two filtered tables — "Recently Completed" and "Active Tasks" — fetched from separate API endpoints and driven by URL search params.
 
 ## Key Components
 
-### `DeliveryLists` (default export)
-Main component that orchestrates dual parallel fetches and renders both `DeliveryTable` instances.
+**`DeliveryLists` (default export)**
+Main component that orchestrates data fetching and rendering for both delivery buckets.
+
+**`DeliveryListsProps`**
 
-### `DeliveryListsProps`
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
+|---|---|---|---|
 | `completedApiEndpoint` | `string` | `/api/delivery/completed` | GET endpoint for completed tasks |
 | `inProgressApiEndpoint` | `string` | `/api/delivery/in-progress` | GET endpoint for active tasks |
-| `searchParamKey` | `string` | `'search'` | URL + API query param key for search input |
-| `taskTypeParamKey` | `string` | `'task_type'` | URL + API query param key for task-type filter |
+| `searchParamKey` | `string` | `DEV_SECTION_PARAM_KEYS.search` | URL param key for search input |
+| `taskTypeParamKey` | `string` | `DEV_SECTION_PARAM_KEYS.deliveryTaskType` | URL param key for task-type filter |
+
+**Internal behaviors**
+- Reads `search` and `task_type` from URL params via `useSearchParams()` and passes them as query params on both outbound fetches (parallel via `Promise.all`)
+- `useScrollToHash` — deep-link support for `?search=<id>#delivery-<id>` patterns using `STICKY_HEADER_OFFSET_PX`
+- Renders `LoadError` on fetch failure (with reload retry), `EmptyState` (search or generic variant) when no results, or both `DeliveryTable` instances when data is present
 
-> **Coupling constraint:** `searchParamKey` and `taskTypeParamKey` must match the consuming chrome's `section.search.paramKey` / `section.filter.paramKey`. These keys are used for both URL reads and outbound API query params — override both ends consistently.
+> ⚠️ **Coupling constraint:** `searchParamKey` / `taskTypeParamKey` must match the consuming chrome's `section.search.paramKey` / `section.filter.paramKey` on both the URL-read side and the outbound API query string. Mismatches require proxy-level rewriting.
 
 ## Usage Example
 
 ```typescript
-// Zero-config (OpenFrame defaults)
+// Zero-config — defaults match hub API routes and OpenFrame chrome param keys
 <DeliveryLists />
 
-// Custom endpoints with matching chrome param keys
+// Custom endpoints and param keys (must match your chrome config)
 <DeliveryLists
-  completedApiEndpoint="/api/v2/tasks/done"
-  inProgressApiEndpoint="/api/v2/tasks/active"
+  completedApiEndpoint="/api/v2/delivery/done"
+  inProgressApiEndpoint="/api/v2/delivery/active"
   searchParamKey="q"
   taskTypeParamKey="type"
 />
 ```
 
-## Behavior
-
-- **Parallel fetches** via `Promise.all` on both endpoints, re-triggered when URL params or endpoint props change
-- **Empty states**: shows a "Reset Filters" CTA when active filters return no results; shows a generic message when no tasks exist
-- **Error state**: renders `<LoadError>` with a page-reload retry on fetch failure
-- **Loading**: passes `isLoading` to each `<DeliveryTable>` for skeleton rendering
+**Source:** [`delivery-lists.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/delivery-lists.tsx)

package/src/components/shared/delivery/.delivery-row.md

@@ -1,41 +1,45 @@
-<!-- source-hash: 48827d34bfec0bd0e5c771a4967c8775 -->
-Single-row presentational component for a ClickUp delivery item, serving as the shared rendering primitive for both the public delivery list table and the HubSpot ticket linked-delivery card.
+<!-- source-hash: 54319e5c90a08528d4927fa4cb24f409 -->
+Canonical single-row presentation component for a ClickUp delivery item, serving as the shared visual primitive across the `/bug-fixes-and-enhancements` delivery table and HubSpot ticket linked-delivery cards.
 
 ## Key Components
 
 ### `DeliveryRow` (exported component)
-Renders a responsive row layout with title, subtitle, description, and status/type badges. Conditionally wraps content in a navigable `<Link>` (via env-aware Next.js shim) or a plain `<div>` depending on whether `href` is provided.
+
+Renders a delivery item's title, subtitle, description, status badge, and task-type badge in a responsive two-column layout. Conditionally renders as a clickable `<Link>` (env-aware embed shim) or a plain `<div>` based on the `href` prop.
 
 ### `DeliveryRowProps` (exported interface)
+
 | Prop | Type | Description |
-|------|------|-------------|
-| `item` | `DeliveryItem` | ClickUp task data (title, status, type, dates, etc.) |
-| `href` | `string?` | When set, makes the entire row a clickable deep-link anchor |
-| `caption` | `string?` | Small uppercase label above the title (e.g. `"LINKED DELIVERY"`) |
-| `className` | `string?` | Additional Tailwind classes for the outer element |
+|---|---|---|
+| `item` | `DeliveryItem` | The delivery data to render |
+| `href` | `string?` | When set, wraps the row in a `<Link>` for deep-linking |
+| `caption` | `string?` | Uppercase label above the title (e.g., `"LINKED DELIVERY"`) |
+| `id` | `string?` | DOM id for `scrollIntoView` targeting (e.g., `delivery-<external_id>`) |
+| `className` | `string?` | Additional Tailwind classes merged via `cn()` |
 
-### `getRelativeTime` (internal helper)
-Converts a Unix timestamp to human-readable relative time (`"yesterday"`, `"3 weeks ago"`, etc.). Inlined so the component owns its full rendering contract independently of `DeliveryTable`.
+### `getRelativeTime` (internal)
+
+Converts a Unix timestamp to a human-readable relative string (`"today"`, `"yesterday"`, `"3 days ago"`, etc.).
 
 ## Usage Example
 
 ```typescript
-// Standard list row (no interactivity)
-<DeliveryRow item={deliveryItem} />
-
-// Clickable deep-link variant (ticket card surface)
+// Standard list rendering (DeliveryTable)
 <DeliveryRow
   item={deliveryItem}
-  href={buildDevSectionUrl('delivery', deliveryItem.id)}
-  caption="LINKED DELIVERY"
+  id={`delivery-${deliveryItem.externalId}`}
 />
 
-// With focus highlight (after ?focus=<id> scroll)
+// Ticket-side linked-delivery card with deep-link and caption
 <DeliveryRow
   item={deliveryItem}
-  id={deliveryItem.id}
-  className="animate-flash-focus"
+  href={buildDevSectionUrl('delivery', deliveryItem.id)}
+  caption="LINKED DELIVERY"
+  id={`delivery-${deliveryItem.externalId}`}
 />
 ```
 
-The `href` prop uses the embed-aware `next/link` shim — preserving TanStack Query state on back-navigation in Next.js hosts while gracefully degrading to a plain `<a>` elsewhere.
+**Key behaviors:**
+- `href` present → outer element becomes a `<Link>` (soft Next.js navigation, preserves TanStack Query state on back)
+- `id` present → enables `useScrollToHash` targeting; `scroll-mt-24` offset is always applied
+- Highlighted state (flash-focus pulse) is applied by the consuming component via `className`

package/src/components/shared/delivery/.delivery-table.md

@@ -1,21 +1,20 @@
-<!-- source-hash: d5d3a5d0e430ad78e58c1dc249ed1e27 -->
-A bordered card component that renders a list of `DeliveryItem` entries, one `DeliveryRow` per item, with loading skeleton and empty-state handling.
+<!-- source-hash: 93ccac2f20e75b0f16b4483fd2b33560 -->
+Renders a bordered card containing one `DeliveryRow` per delivery item, with skeleton loading states, empty states, and deep-link anchor support via URL `?focus=<id>` params.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `DeliveryTable` | Named export | Main table container rendering delivery items |
-| `SkeletonRow` | Internal | Animated placeholder row shown during loading |
-| `DeliveryTableProps` | Interface | `items: DeliveryItem[]`, `isLoading?: boolean` |
+- **`DeliveryTable`** *(exported)* — Main component accepting a list of `DeliveryItem` objects. Handles three render states: skeleton loading, empty, and populated. Each row receives a DOM `id` built via `devSectionAnchorId('delivery', item.id)` (e.g. `#delivery-<external_id>`) to support scroll-to-hash deep-linking from ticket linked-cards.
+- **`SkeletonRow`** *(internal)* — Animated pulse placeholder matching the responsive layout of a real row (title, subtitle, description, and two badge slots).
+- **`DeliveryItem`** — Type imported from `../../../types/delivery`; the flat item shape consumed by this table and its sibling `DeliveryRow`.
 
-## Rendering States
+## Props
 
-| State | Trigger | Output |
-|-------|---------|--------|
-| Loading | `isLoading={true}` | 5 animated `SkeletonRow` placeholders |
-| Empty | `items.length === 0` | "No tasks available" message |
-| Default | Items present | One `<DeliveryRow>` per item, separated by borders |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `DeliveryItem[]` | required | Flat list of delivery items to render |
+| `isLoading` | `boolean` | `false` | Renders 5 skeleton rows when `true` |
+
+> **Note:** `focusId` (the `?focus=<id>` URL param) is resolved by the parent `DeliveryLists` component; this table only applies the anchor id to each row via `devSectionAnchorId`.
 
 ## Usage Example
 
@@ -23,19 +22,18 @@ A bordered card component that renders a list of `DeliveryItem` entries, one `De
 import { DeliveryTable } from './delivery-table';
 import type { DeliveryItem } from '../../../types/delivery';
 
-// Normal render with data
-<DeliveryTable items={deliveryItems} />
+const inProgressItems: DeliveryItem[] = [...];
 
-// Loading state (e.g. while fetching)
+// Loading state
 <DeliveryTable items={[]} isLoading={true} />
 
-// Typically consumed by DeliveryLists — split into two tables:
-<DeliveryTable items={completedItems} />
+// Populated — parent renders two separate tables per bucket
 <DeliveryTable items={inProgressItems} />
+
+// Empty state (renders "No tasks available" message)
+<DeliveryTable items={[]} />
 ```
 
-## Notes
+## Source
 
-- Each item row is wrapped in a `div` with `border-b` and `last:border-b-0` to avoid a trailing border on the final row.
-- `DeliveryRow` handles all visual logic per row — `DeliveryTable` is purely a layout/state shell.
-- Designed to be instantiated twice by the parent `DeliveryLists` component: once for completed items and once for in-progress items.
+[`delivery-table.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/delivery-table.tsx)