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

package/src/components/.chart.md

@@ -1,58 +1,56 @@
-<!-- source-hash: 4316bb882549d86dc2d68491a7d84326 -->
-A comprehensive chart component system built on Recharts that provides themed, accessible data visualization components with customizable styling and tooltips.
+<!-- source-hash: 03d762aae1fcc567d347384e10dad904 -->
+A client-side React chart component library built on top of Recharts, providing themed, accessible chart containers with customizable tooltips and legends.
 
 ## Key Components
 
-**Core Components:**
-- `ChartContainer` - Main wrapper that provides chart context and responsive container
-- `ChartTooltip` / `ChartTooltipContent` - Customizable tooltip with indicators and formatting
-- `ChartLegend` / `ChartLegendContent` - Legend component with icons and labels
-- `ChartStyle` - Dynamic CSS generator for theme-aware chart colors
-
-**Types & Context:**
-- `ChartConfig` - Configuration object defining chart data series with labels, icons, and theme colors
-- `useChart()` - React hook to access chart configuration context
-- `getPayloadConfigFromPayload()` - Helper to extract configuration from chart data payloads
-
-**Theme System:**
-- Supports light/dark themes with CSS custom properties
-- Dynamic color injection based on chart configuration
-- Comprehensive Recharts styling overrides for consistent appearance
+| Export | Description |
+|---|---|
+| `ChartContainer` | Root wrapper that provides chart context, injects CSS custom properties, and wraps content in a `ResponsiveContainer` |
+| `ChartStyle` | Internal component that generates scoped CSS variables for light/dark theme colors |
+| `ChartTooltip` | Re-export of `RechartsPrimitive.Tooltip` |
+| `ChartTooltipContent` | Styled tooltip renderer with support for `dot`, `line`, and `dashed` indicators, custom formatters, and label/icon overrides |
+| `ChartLegend` | Re-export of `RechartsPrimitive.Legend` |
+| `ChartLegendContent` | Styled legend renderer with icon support and configurable alignment |
+| `ChartConfig` | TypeScript type defining per-series labels, icons, and color/theme mappings |
+| `useChart` | Internal hook for consuming `ChartContext`; throws if used outside `ChartContainer` |
 
 ## Usage Example
 
 ```typescript
-import { ChartContainer, ChartTooltipContent, ChartTooltip } from "./chart"
-import { BarChart, Bar, XAxis, YAxis } from "recharts"
-
-const chartConfig = {
-  sales: {
-    label: "Sales",
-    color: "#8884d8",
-    theme: { light: "#8884d8", dark: "#82ca9d" }
-  },
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  ChartLegend,
+  ChartLegendContent,
+} from "./chart"
+import { LineChart, Line, CartesianGrid, XAxis } from "recharts"
+
+const config = {
   revenue: {
-    label: "Revenue", 
-    color: "#82ca9d"
-  }
+    label: "Revenue",
+    theme: { light: "#6366f1", dark: "#818cf8" },
+  },
 }
 
 const data = [
-  { month: "Jan", sales: 4000, revenue: 2400 },
-  { month: "Feb", sales: 3000, revenue: 1398 }
+  { month: "Jan", revenue: 4200 },
+  { month: "Feb", revenue: 5800 },
 ]
 
-function SalesChart() {
+export function RevenueChart() {
   return (
-    <ChartContainer config={chartConfig} className="h-[400px]">
-      <BarChart data={data}>
+    <ChartContainer config={config} className="h-64 w-full">
+      <LineChart data={data}>
+        <CartesianGrid strokeDasharray="3 3" />
         <XAxis dataKey="month" />
-        <YAxis />
-        <ChartTooltip content={<ChartTooltipContent />} />
-        <Bar dataKey="sales" fill="var(--color-sales)" />
-        <Bar dataKey="revenue" fill="var(--color-revenue)" />
-      </BarChart>
+        <ChartTooltip content={<ChartTooltipContent indicator="line" />} />
+        <ChartLegend content={<ChartLegendContent />} />
+        <Line dataKey="revenue" stroke="var(--color-revenue)" />
+      </LineChart>
     </ChartContainer>
   )
 }
-```
+```
+
+**Source:** [`chart.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chart.tsx)

package/src/components/.command.md

@@ -1,17 +1,19 @@
-<!-- source-hash: 4f4abef71f555b45571aaa27bbb5f20c -->
-A comprehensive command palette component built on top of cmdk with Radix UI integration, providing a searchable interface for commands and actions with keyboard navigation support.
+<!-- source-hash: 9b89a858035a27159cafb11e28a5b3e8 -->
+Styled wrapper components around the [cmdk](https://cmdk.dev) command palette primitive, providing a fully themed command menu with search input, grouped results, and dialog support.
 
 ## Key Components
 
-- **Command** - Root command palette container with overflow handling
-- **CommandDialog** - Modal wrapper that displays the command palette in a dialog
-- **CommandInput** - Search input with integrated search icon and styling
-- **CommandList** - Scrollable container for command results with max height constraint
-- **CommandEmpty** - Placeholder component shown when no results are found
-- **CommandGroup** - Logical grouping container for related commands
-- **CommandItem** - Individual selectable command with hover and selection states
-- **CommandSeparator** - Visual divider between command groups
-- **CommandShortcut** - Display component for keyboard shortcuts
+| Export | Description |
+|---|---|
+| `Command` | Root container wrapping `CommandPrimitive` with popover styling |
+| `CommandDialog` | Modal variant that renders the command palette inside a `Dialog` |
+| `CommandInput` | Search input with a `Search` icon prefix and border separator |
+| `CommandList` | Scrollable results container (max height 300px) |
+| `CommandEmpty` | Centered empty-state message when no results match |
+| `CommandGroup` | Labeled section for grouping related items |
+| `CommandItem` | Individual selectable result row with hover/selected/disabled states |
+| `CommandSeparator` | Horizontal rule divider between groups |
+| `CommandShortcut` | Right-aligned `<span>` for displaying keyboard shortcut hints |
 
 ## Usage Example
 
@@ -19,31 +21,53 @@ A comprehensive command palette component built on top of cmdk with Radix UI int
 import {
   Command,
   CommandDialog,
+  CommandInput,
+  CommandList,
   CommandEmpty,
   CommandGroup,
-  CommandInput,
   CommandItem,
-  CommandList,
   CommandShortcut,
+  CommandSeparator,
 } from "./command"
 
-function CommandPalette() {
-  const [open, setOpen] = React.useState(false)
-
+// Inline palette
+function InlineCommandMenu() {
   return (
-    <CommandDialog open={open} onOpenChange={setOpen}>
-      <CommandInput placeholder="Type a command or search..." />
+    <Command>
+      <CommandInput placeholder="Search actions..." />
       <CommandList>
         <CommandEmpty>No results found.</CommandEmpty>
-        <CommandGroup heading="Suggestions">
+        <CommandGroup heading="Devices">
           <CommandItem>
-            Calendar
-            <CommandShortcut>⌘K</CommandShortcut>
+            View All Devices
+            <CommandShortcut>⌘D</CommandShortcut>
+          </CommandItem>
+        </CommandGroup>
+        <CommandSeparator />
+        <CommandGroup heading="Tickets">
+          <CommandItem>Open Tickets</CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </Command>
+  )
+}
+
+// Modal palette triggered by a keyboard shortcut
+function CommandPaletteDialog({ open, onOpenChange }) {
+  return (
+    <CommandDialog open={open} onOpenChange={onOpenChange}>
+      <CommandInput placeholder="Type a command..." />
+      <CommandList>
+        <CommandEmpty>No results found.</CommandEmpty>
+        <CommandGroup heading="Navigation">
+          <CommandItem onSelect={() => router.push("/dashboard")}>
+            Dashboard
           </CommandItem>
-          <CommandItem>Search Emoji</CommandItem>
         </CommandGroup>
       </CommandList>
     </CommandDialog>
   )
 }
-```
+```
+
+**Source:** [`command.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/command.tsx)

package/src/components/.comment-card.md

@@ -1,42 +1,47 @@
-<!-- source-hash: 0b18246ba972b704769b5c9382e327c6 -->
-Renders a styled card for displaying a user comment, supporting both vendor-context (showing the commenter's identity) and profile-context (showing the associated vendor) views with optional delete functionality.
+<!-- source-hash: 2dc22952dfcc6e283cfc3b6d4d636ade -->
+Renders a styled comment card that adapts its layout based on context — showing vendor information when viewing a user profile, or user information when viewing a vendor page — with optional delete functionality based on auth state.
 
 ## Key Components
 
-### `CommentCard`
-The primary exported component accepting a `CommentCardProps` object.
+### `CommentCard` (default export)
 
-**Props:**
+A context-aware card component for displaying user-submitted vendor comments.
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `comment` | `object` | Comment data including content, metadata, and optional vendor/user info |
-| `onViewProduct` | `(vendorSlug: string) => void` | Callback when vendor button is clicked |
-| `onDeleteComment` | `(commentId: string) => void` | Callback when delete button is clicked |
-| `showVendorInfo` | `boolean` | Whether to display vendor information (default: `true`) |
-| `compact` | `boolean` | Reduces content area height (default: `false`) |
-| `context` | `'profile' \| 'vendor'` | Controls header layout — vendor button or user summary |
+**Props (`CommentCardProps`):**
 
-### Delete Authorization Logic (`canUserDeleteComment`)
-Context-aware check: in `profile` context, relies on `comment.canDelete`; in `vendor` context, compares `currentUser.id` against `comment.user.id`.
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `comment` | `object` | — | Comment data including content, author, vendor, and metadata |
+| `context` | `'profile' \| 'vendor'` | `'profile'` | Controls layout and delete permission logic |
+| `onViewProduct` | `(slug: string) => void` | — | Callback when vendor button is clicked |
+| `onDeleteComment` | `(id: string) => void` | — | Callback when delete is triggered |
+| `showVendorInfo` | `boolean` | `true` | Toggles vendor info display |
+| `compact` | `boolean` | `false` | Reduces content area height |
+
+**Internal logic:**
+
+- `canUserDeleteComment()` — Grants delete access to authenticated users; in `profile` context, respects the `canDelete` prop; in `vendor` context, compares `currentUser.id` against `comment.user.id`
+- `formatActivityTime()` — Delegates to `formatRelativeTime` utility for human-readable timestamps
 
 ## Usage Example
 
 ```typescript
 <CommentCard
+  context="vendor"
   comment={{
     id: "abc123",
-    content: "Excellent ticketing integration with our existing stack.",
-    title: "Great RMM Tool",
-    type: "pro",
-    importance: "Critical",
-    createdAt: "2024-11-01T10:00:00Z",
-    vendor: { id: 1, title: "NinjaRMM", slug: "ninjarmm", logo: "/logos/ninja.png" },
+    content: "Solid RMM tool for small MSPs.",
+    title: "Great value",
+    createdAt: "2025-06-01T12:00:00Z",
+    user: {
+      id: "user-42",
+      name: "Jane Smith",
+      profilePicture: null,
+    },
     canDelete: true,
   }}
-  context="profile"
-  onViewProduct={(slug) => router.push(`/vendors/${slug}`)}
-  onDeleteComment={(id) => handleDelete(id)}
-  compact={false}
+  onDeleteComment={(id) => console.log("Delete", id)}
 />
-```
+```
+
+**Source:** [`comment-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/comment-card.tsx)

package/src/components/.content-loading-container.md

@@ -1,40 +1,59 @@
-<!-- source-hash: 136d5eb8692fb936306eaef6f2ae6216 -->
-A React component that provides smooth loading transitions with skeleton states while preventing layout jumps during content loading.
+<!-- source-hash: b7d95eae06e3f4248319cf0584641bd9 -->
+A client-side React component and companion hook for managing content loading states with skeleton overlays, smooth transitions, and stable layout dimensions.
 
 ## Key Components
 
-- **ContentLoadingContainer** - Main component that overlays skeleton loading states over actual content
-- **useContentLoading** - Hook providing common loading state patterns and utilities for different content types
+### `ContentLoadingContainer`
 
-## Core Features
+A wrapper component that overlays a skeleton placeholder during loading, then fades in the actual content once data is ready. Prevents layout jumps by preserving container dimensions throughout the loading lifecycle.
 
-- **Layout Stability** - Maintains consistent dimensions during loading with configurable `minHeight`
-- **Smooth Transitions** - Customizable opacity transitions between loading and loaded states
-- **Accessibility** - Proper ARIA labels, live regions, and screen reader support
-- **Flexible Skeletons** - Accepts any skeleton component for different content types
-- **Visual Overlay** - Dark background overlay that smoothly fades in/out during state changes
+**Props:**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `isLoading` | `boolean` | — | Controls skeleton/content visibility |
+| `children` | `ReactNode` | — | Content rendered when not loading |
+| `skeletonComponent` | `ReactNode` | — | Skeleton UI shown during loading |
+| `className` | `string?` | — | Additional Tailwind classes |
+| `minHeight` | `string?` | `"min-h-[300px] md:min-h-[800px]"` | Prevents layout jumps |
+| `loadingOpacity` | `number?` | `1` | Skeleton overlay opacity (0–1) |
+| `transitionDuration` | `number?` | `300` | Fade transition in milliseconds |
+
+### `useContentLoading`
+
+A utility hook that returns accessibility attributes and layout helpers scoped to content type.
+
+**Returns:**
+
+| Key | Description |
+|---|---|
+| `containerProps` | `aria-busy` and `data-loading` attributes |
+| `getSkeletonCount(type)` | Returns skeleton card count (12 for `vendor`, 6 for `blog`) |
+| `getMinHeight(type)` | Returns appropriate min-height class per content type |
 
 ## Usage Example
 
 ```typescript
-import { ContentLoadingContainer, useContentLoading } from './content-loading-container'
+import {
+  ContentLoadingContainer,
+  useContentLoading
+} from "./content-loading-container"
+import { CardSkeletonGrid } from "./card-skeleton-grid"
 
-function VendorPage() {
-  const [vendors, setVendors] = useState([])
-  const [isLoading, setIsLoading] = useState(true)
+function VendorSection({ vendors, isLoading }) {
   const { getMinHeight, getSkeletonCount } = useContentLoading(isLoading)
 
   return (
     <ContentLoadingContainer
       isLoading={isLoading}
       skeletonComponent={
-        <CardSkeletonGrid 
-          variant="vendor" 
-          count={getSkeletonCount('vendor')} 
+        <CardSkeletonGrid
+          variant="vendor"
+          count={getSkeletonCount("vendor")}
         />
       }
-      minHeight={getMinHeight('vendor')}
-      transitionDuration={200}
+      minHeight={getMinHeight("vendor")}
+      transitionDuration={400}
     >
       <VendorGrid vendors={vendors} />
     </ContentLoadingContainer>
@@ -42,4 +61,10 @@ function VendorPage() {
 }
 ```
 
-The component uses absolute positioning to overlay the skeleton during loading while keeping the actual content rendered but hidden, ensuring smooth transitions without DOM manipulation delays.
+## Accessibility
+
+The component includes built-in ARIA support: `role="region"` with `aria-live="polite"` on the wrapper, `role="status"` on the skeleton overlay, and `aria-hidden` on content while loading — ensuring screen readers announce state transitions correctly.
+
+## Source
+
+[`content-loading-container.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/content-loading-container.tsx)

package/src/components/.context-menu.md

@@ -1,57 +1,71 @@
-<!-- source-hash: b87ab486ec9d61378bfc78b4a34edc52 -->
-A React context menu component library built on top of Radix UI primitives, providing styled and accessible right-click context menus with support for items, checkboxes, radio buttons, submenus, and keyboard shortcuts.
+<!-- source-hash: 6a66d13d506e134a8d9bffd6d46a99bb -->
+A styled right-click context menu component built on Radix UI's `@radix-ui/react-context-menu` primitive, providing accessible, animated menu overlays with Tailwind CSS styling.
 
 ## Key Components
 
-- **ContextMenu** - Root wrapper component for context menu functionality
-- **ContextMenuTrigger** - Element that triggers the context menu on right-click
-- **ContextMenuContent** - Container for menu items with portal rendering and animations
-- **ContextMenuItem** - Individual clickable menu item with hover states
-- **ContextMenuCheckboxItem** - Checkbox menu item with check indicator
-- **ContextMenuRadioItem** - Radio button menu item for single selections
-- **ContextMenuLabel** - Non-interactive label for grouping menu items
-- **ContextMenuSeparator** - Visual separator between menu sections
-- **ContextMenuShortcut** - Text component for displaying keyboard shortcuts
-- **ContextMenuSub** - Submenu container with chevron indicator
-- **ContextMenuGroup/RadioGroup** - Grouping components for related items
+| Export | Description |
+|---|---|
+| `ContextMenu` | Root container managing open/close state |
+| `ContextMenuTrigger` | Element that activates the menu on right-click |
+| `ContextMenuContent` | Animated popover panel rendered in a portal |
+| `ContextMenuItem` | Standard clickable menu item; supports `inset` prop |
+| `ContextMenuCheckboxItem` | Menu item with a toggleable checkbox indicator |
+| `ContextMenuRadioItem` | Menu item for use within a `ContextMenuRadioGroup` |
+| `ContextMenuLabel` | Non-interactive section label; supports `inset` prop |
+| `ContextMenuSeparator` | Horizontal divider between menu sections |
+| `ContextMenuShortcut` | Right-aligned keyboard shortcut hint span |
+| `ContextMenuSub` | Container for nested sub-menus |
+| `ContextMenuSubTrigger` | Item that opens a nested sub-menu with a chevron icon |
+| `ContextMenuSubContent` | Animated panel for nested sub-menu items |
+| `ContextMenuGroup` | Groups related items together |
+| `ContextMenuRadioGroup` | Groups radio items for single-selection behavior |
+| `ContextMenuPortal` | Renders menu content outside the DOM hierarchy |
 
 ## Usage Example
 
 ```typescript
 import {
   ContextMenu,
+  ContextMenuTrigger,
   ContextMenuContent,
   ContextMenuItem,
-  ContextMenuTrigger,
+  ContextMenuCheckboxItem,
   ContextMenuSeparator,
   ContextMenuShortcut,
-  ContextMenuCheckboxItem,
-  ContextMenuRadioGroup,
-  ContextMenuRadioItem,
+  ContextMenuSub,
+  ContextMenuSubTrigger,
+  ContextMenuSubContent,
+  ContextMenuLabel,
 } from "./context-menu"
 
-function MyComponent() {
+export function FileContextMenu() {
   return (
     <ContextMenu>
-      <ContextMenuTrigger>
-        <div className="border p-4">Right-click me</div>
+      <ContextMenuTrigger className="flex h-32 w-48 items-center justify-center border rounded-md">
+        Right-click here
       </ContextMenuTrigger>
       <ContextMenuContent>
+        <ContextMenuLabel>File Actions</ContextMenuLabel>
         <ContextMenuItem>
-          Copy
-          <ContextMenuShortcut>⌘C</ContextMenuShortcut>
+          Open <ContextMenuShortcut>⌘O</ContextMenuShortcut>
         </ContextMenuItem>
-        <ContextMenuItem>Paste</ContextMenuItem>
+        <ContextMenuCheckboxItem checked>Show Hidden Files</ContextMenuCheckboxItem>
         <ContextMenuSeparator />
-        <ContextMenuCheckboxItem checked={true}>
-          Show Grid
-        </ContextMenuCheckboxItem>
-        <ContextMenuRadioGroup value="light">
-          <ContextMenuRadioItem value="light">Light</ContextMenuRadioItem>
-          <ContextMenuRadioItem value="dark">Dark</ContextMenuRadioItem>
-        </ContextMenuRadioGroup>
+        <ContextMenuSub>
+          <ContextMenuSubTrigger>Share</ContextMenuSubTrigger>
+          <ContextMenuSubContent>
+            <ContextMenuItem>Email</ContextMenuItem>
+            <ContextMenuItem>Copy Link</ContextMenuItem>
+          </ContextMenuSubContent>
+        </ContextMenuSub>
+        <ContextMenuSeparator />
+        <ContextMenuItem>
+          Delete <ContextMenuShortcut>⌫</ContextMenuShortcut>
+        </ContextMenuItem>
       </ContextMenuContent>
     </ContextMenu>
   )
 }
-```
+```
+
+**Source:** [`context-menu.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/context-menu.tsx)

package/src/components/.date-time-picker.md

@@ -1,44 +1,50 @@
-<!-- source-hash: e4564c4f125012e83f935e01f9e227ea -->
-A reusable date and time picker component built with react-datepicker, featuring dark theme styling and consistent form integration with the design system.
+<!-- source-hash: a36437c1a2e15a6b144f93b54910e1cd -->
+A client-side React date and time picker component that wraps `react-datepicker` with OpenFrame's ODS (OpenFrame Design System) dark theme styling and consistent input patterns.
 
 ## Key Components
 
-- **DateTimePicker**: Main component that wraps react-datepicker with custom styling
-- **DateTimePickerProps**: TypeScript interface defining component configuration options
-- **inputClassName**: Shared styling constants that match the design system's Input component pattern
+### `DateTimePicker`
+The primary exported component. Renders a labeled date/time input with a fully styled dark-theme calendar popup matching the admin UI theme tokens (`ods-card`, `ods-border`, `ods-accent`, etc.).
+
+### `DateTimePickerProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `Date` | — | Controlled selected date |
+| `onChange` | `(date: Date \| null) => void` | — | Change handler |
+| `disabled` | `boolean` | `false` | Disables the input |
+| `label` | `string` | — | Optional field label |
+| `placeholder` | `string` | `"Select date and time"` | Input placeholder |
+| `className` | `string` | — | Additional wrapper classes |
+| `showTimeSelect` | `boolean` | `true` | Enables time selection panel |
+| `timeFormat` | `string` | `"HH:mm"` | Time display format |
+| `timeIntervals` | `number` | `15` | Minutes between time options |
+| `dateFormat` | `string` | `"MMMM d, yyyy h:mm aa"` | Full date/time display format |
+
+### `inputClassName`
+A shared `cn()`-composed class string that mirrors the `Input` component's styling, including mobile zoom prevention (`text-base` on small screens).
 
 ## Usage Example
 
 ```typescript
-import { DateTimePicker } from './components/date-time-picker';
-import { useState } from 'react';
+import { DateTimePicker } from "@/components/date-time-picker";
+import { useState } from "react";
 
-function EventForm() {
-  const [eventDate, setEventDate] = useState<Date | null>(null);
+export function ScheduleForm() {
+  const [scheduledAt, setScheduledAt] = useState<Date | null>(null);
 
   return (
-    <div className="space-y-4">
-      <DateTimePicker
-        label="Event Date & Time"
-        value={eventDate}
-        onChange={setEventDate}
-        placeholder="When is your event?"
-        showTimeSelect={true}
-        timeIntervals={30}
-        dateFormat="MMM dd, yyyy h:mm aa"
-      />
-      
-      {/* Date-only picker */}
-      <DateTimePicker
-        label="Deadline"
-        value={eventDate}
-        onChange={setEventDate}
-        showTimeSelect={false}
-        dateFormat="MMMM d, yyyy"
-      />
-    </div>
+    <DateTimePicker
+      label="Schedule At"
+      value={scheduledAt ?? undefined}
+      onChange={(date) => setScheduledAt(date)}
+      timeIntervals={30}
+      dateFormat="MM/dd/yyyy HH:mm"
+    />
   );
 }
 ```
 
-The component features full-width responsive design, dark theme integration, customizable date/time formats, and matches the ODS design system colors including the signature yellow (#FFC008) accent color for selections.
+> **Note:** Inline `<style>` via `dangerouslySetInnerHTML` overrides `react-datepicker`'s default light theme. The accent color (`#FFC008`) maps to `ods-accent` for selected days and time slots.
+
+**Source:** [`date-time-picker.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/date-time-picker.tsx)

package/src/components/.empty-state.md

@@ -1,52 +1,52 @@
-<!-- source-hash: 50c4ce7ece14f33f4a6cb6591ed66364 -->
-A reusable React client component that renders context-aware empty state UI for vendors, posts, search results, or generic scenarios — with smart CTA logic that adapts based on the current URL path.
+<!-- source-hash: 55c09cdcc7260b6cd2e3101f25d75b39 -->
+A reusable React client component that renders contextual empty state UI for vendors, posts, search results, and generic scenarios, with smart CTA logic that adapts based on the current route.
 
 ## Key Components
 
 ### `EmptyStateProps` Interface
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `type` | `'vendors' \| 'posts' \| 'search' \| 'generic'` | required | Determines default icon, title, and description |
-| `title` | `string` | — | Overrides default title |
-| `description` | `string` | — | Overrides default description |
-| `showBackButton` | `boolean` | `false` | Renders an optional back button |
-| `onGoBack` | `() => void` | — | Handler for the back button |
-| `backButtonText` | `string` | `"Go Back"` | Back button label |
-| `showCTA` | `boolean` | `true` | Toggles the smart CTA button |
-| `ctaText` | `string` | — | Overrides smart CTA label |
-| `onCtaClick` | `() => void` | — | Overrides smart CTA action |
-| `ctaVariant` | `'primary' \| 'secondary'` | `'primary'` | CTA button styling |
-
-### Internal Helpers
+|---|---|---|---|
+| `type` | `'vendors' \| 'posts' \| 'search' \| 'generic'` | — | Determines default icon, title, and description |
+| `title` | `string` | type-based default | Override the default heading |
+| `description` | `string` | type-based default | Override the default body text |
+| `showBackButton` | `boolean` | `false` | Renders an optional secondary back button |
+| `onGoBack` | `() => void` | — | Callback for the back button |
+| `backButtonText` | `string` | `"Go Back"` | Label for the back button |
+| `showCTA` | `boolean` | `true` | Toggles the primary CTA button |
+| `ctaText` | `string` | smart default | Custom CTA label |
+| `onCtaClick` | `() => void` | smart default | Custom CTA handler |
+| `ctaVariant` | `'primary' \| 'secondary'` | `'primary'` | CTA button style variant |
+
+### `EmptyState` Component
 
 - **`getDefaultContent()`** — Returns icon, title, and description based on `type`
-- **`getSmartCTA()`** — Derives CTA label and action from `type` + current pathname (e.g., resets filters on `/vendors` or `/blog`, navigates to `/vendors` from `/profile`)
+- **`getSmartCTA()`** — Derives CTA label and action from `type` and `window.location.pathname`; custom `ctaText`/`onCtaClick` always take precedence. Falls back to route-aware defaults (e.g. resets URL search params on vendor/blog/search pages, navigates to `/vendors` or `/blog` elsewhere)
 
 ## Usage Example
 
 ```typescript
-// Basic usage
+// Basic usage — type-driven defaults
 <EmptyState type="vendors" />
 
-// Search with custom CTA
-<EmptyState
-  type="search"
-  title="No results"
-  description="Try different keywords."
-  ctaText="Clear Search"
-  onCtaClick={() => setQuery('')}
-  ctaVariant="secondary"
-/>
+// Search results with filter reset
+<EmptyState type="search" />
 
-// With back button, no CTA
+// Custom CTA and back button
 <EmptyState
   type="posts"
-  showCTA={false}
-  showBackButton={true}
+  title="No articles yet"
+  description="Check back soon for new content."
+  showCTA
+  ctaText="Browse Vendors"
+  onCtaClick={() => router.push('/vendors')}
+  ctaVariant="secondary"
+  showBackButton
   onGoBack={() => router.back()}
-  backButtonText="Return to Feed"
+  backButtonText="Return"
 />
 ```
 
-> **Smart CTA behavior:** When no `ctaText`/`onCtaClick` is provided, the component inspects `window.location.pathname` to decide whether to reset URL filters or navigate to `/vendors` or `/blog`.
+## Source
+
+[`empty-state.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/empty-state.tsx)