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

package/src/components/.steps.md

@@ -1,44 +1,58 @@
-<!-- source-hash: 18962d8a10f85127f723da06d9d49622 -->
-A React component for creating visual step-by-step progress indicators with automatic state management and connecting lines between steps.
+<!-- source-hash: 061e3bda4b366c5ccd3858bef10b0bc5 -->
+A client-side React component pair for rendering a vertical step-by-step progress indicator, automatically tracking active, completed, and pending states.
 
 ## Key Components
 
-- **`Steps`**: Main container component that manages step numbering and state distribution
-  - Props: `currentStep` (number), standard HTML div attributes
-  - Automatically counts children and passes state to each step
-- **`Step`**: Individual step component with indicator, title, and optional description
-  - Props: `title` (string), `description?` (string), plus auto-injected state props
-  - Renders step number or checkmark based on completion state
+- **`Steps`** — Container component that manages step state. Accepts `currentStep` (1-based index) and automatically injects `stepNumber`, `isActive`, `isCompleted`, and `isLast` props into child `Step` components.
+- **`Step`** — Individual step item displaying a numbered circle indicator, title, optional description, and a connecting vertical line. Renders a checkmark SVG when completed.
+
+### Props
+
+**`Steps`**
+
+| Prop | Type | Description |
+|---|---|---|
+| `currentStep` | `number` | 1-based index of the currently active step |
+| `className` | `string` | Optional additional CSS classes |
+
+**`Step`**
+
+| Prop | Type | Description |
+|---|---|---|
+| `title` | `string` | Step label (required) |
+| `description` | `string` | Optional subtitle text |
+| `stepNumber` | `number` | Auto-injected by `Steps` |
+| `isActive` | `boolean` | Auto-injected by `Steps` |
+| `isCompleted` | `boolean` | Auto-injected by `Steps` |
+| `isLast` | `boolean` | Auto-injected by `Steps`; suppresses connecting line |
 
 ## Usage Example
 
 ```typescript
-import { Steps, Step } from "./components/ui/steps"
+import { Steps, Step } from "@/components/steps"
 
-function RegistrationWizard() {
-  const [currentStep, setCurrentStep] = useState(2)
+export function OnboardingFlow() {
+  const [currentStep, setCurrentStep] = React.useState(2)
 
   return (
     <Steps currentStep={currentStep}>
-      <Step 
-        title="Account Setup" 
-        description="Create your account credentials" 
-      />
-      <Step 
-        title="Profile Information" 
-        description="Add your personal details" 
+      <Step
+        title="Create Account"
+        description="Enter your email and password"
       />
-      <Step 
-        title="Verification" 
-        description="Verify your email address" 
+      <Step
+        title="Verify Email"
+        description="Check your inbox for a confirmation link"
       />
-      <Step 
-        title="Complete" 
-        description="Your account is ready" 
+      <Step
+        title="Set Up Profile"
+        description="Add your name and preferences"
       />
     </Steps>
   )
 }
 ```
 
-The component automatically handles visual states (active, completed, pending) and renders connecting lines between steps. Each step displays a numbered indicator that becomes a checkmark when completed.
+> **Note:** Only direct `Step` children are enhanced with state props — other elements pass through unchanged. `stepNumber`, `isActive`, `isCompleted`, and `isLast` are injected automatically; do not pass them manually.
+
+**Source:** [`steps.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/steps.tsx)

package/src/components/.tool-icon.md

@@ -1,20 +1,37 @@
-<!-- source-hash: 2db0b6673e5d8f02f2a3713fb6528d5d -->
-Renders the appropriate logo icon for a given MSP tool type (Fleet MDM, MeshCentral, Authentik, Osquery, or OpenFrame variants).
+<!-- source-hash: 4b8b44919fa215934fa2f582b48d9c94 -->
+Renders the appropriate logo icon for a given MSP tool type, mapping each `ToolType` to its corresponding icon component.
 
 ## Key Components
 
+### `ToolIcon` (`React.FC<ToolIconProps>`)
+The primary exported component. Looks up the correct icon renderer from `toolIconMap` using the provided `toolType` and delegates rendering with `size` and `className`.
+
 ### `toolIconMap`
-Internal mapping from each `ToolType` value to its corresponding icon renderer function. OpenFrame variants (`OPENFRAME`, `OPENFRAME_CHAT`, `OPENFRAME_CLIENT`) all share `renderOpenFrameLogo`, while `SYSTEM` renders nothing (`null`).
+Internal mapping of every `ToolType` value to a render function returning a `React.ReactNode`. All OpenFrame variants share `renderOpenFrameLogo`; `SYSTEM` renders `null`.
+
+### `renderOpenFrameLogo`
+Private helper that renders the `OpenFrameLogo` with themed CSS variable colors (`--color-accent-primary`, `--color-text-primary`).
+
+## Supported Tool Types
 
-### `ToolIconProps`
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `toolType` | `ToolType` | required | The tool whose icon should be rendered |
-| `size` | `number` | `16` | Width/height passed to the icon component |
-| `className` | `string` | — | Optional CSS class override |
+| Tool Type | Icon Component |
+|---|---|
+| `FLEET_MDM` | `FleetMdmLogoGreyIcon` |
+| `MESHCENTRAL` | `MeshcentralLogoGreyIcon` |
+| `OPENFRAME` / `OPENFRAME_CHAT` / `OPENFRAME_CLIENT` / `OPENFRAME_RMM` | `OpenFrameLogo` |
+| `AUTHENTIK` | `AuthentikLogoGreyIcon` |
+| `OSQUERY` | `OsqueryLogoGreyIcon` |
+| `SYSTEM` | *(none — renders `null`)* |
 
-### `ToolIcon`
-A functional React component that looks up the icon renderer from `toolIconMap` and invokes it with `size` and `className`. Returns `null` for unknown or `SYSTEM` tool types.
+## Props
+
+```typescript
+interface ToolIconProps {
+  toolType: ToolType;   // Required — determines which icon to render
+  size?: number;        // Icon size in px (default: 16)
+  className?: string;   // Optional CSS class override
+}
+```
 
 ## Usage Example
 
@@ -22,16 +39,12 @@ A functional React component that looks up the icon renderer from `toolIconMap`
 import { ToolIcon } from "./tool-icon";
 import { ToolTypeValues } from "../types/tool.types";
 
-// Render a Fleet MDM icon at default size (16px)
-<ToolIcon toolType={ToolTypeValues.FLEET_MDM} />
+// Render a Fleet MDM icon at 24px
+<ToolIcon toolType={ToolTypeValues.FLEET_MDM} size={24} />
 
-// Render a MeshCentral icon at 24px with a custom class
-<ToolIcon
-  toolType={ToolTypeValues.MESHCENTRAL}
-  size={24}
-  className="h-6 w-6 text-accent"
-/>
+// Render an OpenFrame icon with a custom class
+<ToolIcon toolType={ToolTypeValues.OPENFRAME} className="h-6 w-auto" />
 
-// Renders nothing — SYSTEM has no visual icon
-<ToolIcon toolType={ToolTypeValues.SYSTEM} />
+// SYSTEM type renders nothing
+<ToolIcon toolType={ToolTypeValues.SYSTEM} /> // → null
 ```

package/src/components/.unified-filter-logic.md

@@ -1,27 +1,33 @@
-<!-- source-hash: 1d107abaa66df6045feade13e2cfcdf0 -->
-Provides a unified, URL-driven AND-based filtering system for Next.js pages, exposing a React hook and pre-built filter configurations for managing multi-dimensional filter state via search parameters.
+<!-- source-hash: 1f118a5b523ee85acc9c21e5793f2dea -->
+Provides unified AND-based filter logic for URL-driven filtering across different content types (vendors, blog, etc.), managing filter state via search parameters.
 
 ## Key Components
 
 ### Interfaces
-- **`FilterState`** — Represents the current filter state: `search`, `categories`, `subcategories`, `tags`, `filters`, `pricing`, and `page`
-- **`FilterConfig`** — Configures a filter instance with a `basePath` and a feature flag map (`supportedFilters`) to enable/disable filter dimensions
+
+- **`FilterState`** — Shape of the active filter state: `search`, `categories`, `subcategories`, `tags`, `filters`, `pricing`, `page`
+- **`FilterConfig`** — Per-route configuration declaring `basePath` and which filter types are supported
 
 ### Hook
-- **`useUnifiedFiltering(config)`** — Core hook that reads/writes filter state from URL search params using AND logic. Returns:
-  - `getCurrentFilterState()` — Parses current URL params into a `FilterState` object
-  - `updateFilters(newFilters, preserveScroll?)` — Rebuilds the URL with merged filter state
-  - `addFilter(type, value, preserveScroll?)` — Appends a value to a filter dimension
-  - `removeFilter(type, value?, preserveScroll?)` — Removes a specific or all values from a filter dimension
-  - `toggleFilter(type, value, preserveScroll?)` — Adds or removes a value depending on current state
-  - `clearAllFilters()` — Navigates to the base path, removing all params
-  - `getFilterChips(categories?, tags?)` — Generates display chip descriptors from active filters
-  - `handleFilterChipRemove(chipId)` — Removes a filter based on a chip's `id` string
-  - `isPending` — React transition pending state for UI feedback
+
+**`useUnifiedFiltering(config: FilterConfig)`** — Core hook that reads/writes filter state from URL search params. Returns:
+
+| Method | Description |
+|---|---|
+| `getCurrentFilterState()` | Parses current URL params into a `FilterState` object |
+| `updateFilters(partial, preserveScroll?)` | Merges new filters into state and pushes updated URL |
+| `addFilter(type, value, preserveScroll?)` | Appends a value to a multi-select filter |
+| `removeFilter(type, value?, preserveScroll?)` | Removes a specific value or clears a filter type |
+| `toggleFilter(type, value, preserveScroll?)` | Adds if absent, removes if present |
+| `clearAllFilters()` | Navigates to `basePath` with no params |
+| `getFilterChips(categories?, tags?)` | Returns display-ready chip objects for active filters |
+| `handleFilterChipRemove(chipId)` | Parses chip ID and dispatches the correct `removeFilter` call |
+| `isPending` | React transition pending state |
 
 ### Pre-built Configs
-- **`vendorFilterConfig`** — Config for `/vendors` with categories, subcategories, filters, pricing, and search enabled
-- **`blogFilterConfig`** — Config for `/blog` with categories, tags, and search enabled
+
+- **`vendorFilterConfig`** — `/vendors` route; enables categories, subcategories, filters, pricing, and search
+- **`blogFilterConfig`** — `/blog` route; enables categories, tags, and search
 
 ## Usage Example
 
@@ -29,35 +35,25 @@ Provides a unified, URL-driven AND-based filtering system for Next.js pages, exp
 import { useUnifiedFiltering, vendorFilterConfig } from './unified-filter-logic'
 
 function VendorFilters() {
-  const {
-    getCurrentFilterState,
-    toggleFilter,
-    clearAllFilters,
-    getFilterChips,
-    handleFilterChipRemove,
-    isPending
-  } = useUnifiedFiltering(vendorFilterConfig)
+  const { getCurrentFilterState, toggleFilter, clearAllFilters, isPending } =
+    useUnifiedFiltering(vendorFilterConfig)
 
   const state = getCurrentFilterState()
 
   return (
     <div>
       <button onClick={() => toggleFilter('categories', 'security')}>
-        Toggle Security
+        Security
       </button>
       <button onClick={() => toggleFilter('pricing', 'free')}>
-        Toggle Free
+        Free
+      </button>
+      <button onClick={clearAllFilters} disabled={isPending}>
+        Clear All
       </button>
-      <button onClick={clearAllFilters}>Clear All</button>
-
-      {getFilterChips().map(chip => (
-        <span key={chip.id} onClick={() => handleFilterChipRemove(chip.id)}>
-          {chip.label} ✕
-        </span>
-      ))}
-
-      {isPending && <span>Loading...</span>}
     </div>
   )
 }
-```
+```
+
+> **AND semantics:** All active filters must match simultaneously. Selecting two categories returns only items that belong to both.

package/src/components/.user-display.md

@@ -1,43 +1,48 @@
-<!-- source-hash: 5607b9ca5e1826a2e00e830debb04c5d -->
-A reusable React component that displays a user's avatar, name, and optional subtitle in a horizontal layout, following the visual pattern used in comment headers and user cards.
+<!-- source-hash: f339cfe147ff6ce0d04d2438b39e4c5e -->
+Reusable horizontal layout component that renders a user's avatar alongside their name and an optional subtitle, following the visual pattern established by `CommentCard` headers.
 
 ## Key Components
 
-- **`UserDisplay`** - Main component that renders a horizontal user information row
-- **`UserDisplayProps`** - TypeScript interface defining component props including name, avatar URL, subtitle, size, and styling options
-- **`SquareAvatar`** - Imported avatar component for displaying user profile images
-- **`cn`** - Utility function for conditional class name merging
+### `UserDisplay` (exported function component)
 
-## Usage Example
+Composes a `SquareAvatar` with a text column for user identity display.
 
-```typescript
-import { UserDisplay } from './user-display';
+**Props (`UserDisplayProps`):**
 
-// Basic user display
-<UserDisplay name="John Doe" />
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` | — | Display name; also used as avatar fallback initials |
+| `avatarUrl` | `string \| null` | — | Optional avatar image URL; routed through the image proxy |
+| `subtitle` | `string \| null` | — | Secondary text (e.g., relative timestamp) |
+| `size` | `number` | `32` | Avatar size in pixels |
+| `shape` | `'square' \| 'round'` | `'square'` | Corner treatment forwarded to `SquareAvatar` |
+| `compact` | `boolean` | `false` | Switches to smaller typography (`text-h6`) for dense overlays |
+| `className` | `string` | — | Additional CSS classes on the root element |
+
+## Usage Example
 
-// With avatar and subtitle
-<UserDisplay 
+```typescript
+// Standard header row
+<UserDisplay
   name="Jane Smith"
-  avatarUrl="/avatars/jane.jpg"
+  avatarUrl="https://example.com/jane.jpg"
   subtitle="2 hours ago"
 />
 
-// Custom size and styling
-<UserDisplay 
-  name="Bob Wilson"
-  avatarUrl="/avatars/bob.jpg"
-  subtitle="Online now"
-  size={48}
-  className="bg-gray-50 p-2 rounded"
+// Compact rounded avatar for video-bite overlays
+<UserDisplay
+  name="Alex Rivera"
+  avatarUrl={user.avatarUrl}
+  subtitle="Just now"
+  size={24}
+  shape="round"
+  compact
 />
 
-// Handling null/undefined values
-<UserDisplay 
-  name="Anonymous User"
-  avatarUrl={null}
-  subtitle={undefined}
-/>
+// Name-only, no avatar URL (falls back to initials)
+<UserDisplay name="Bob Chen" />
 ```
 
-The component uses DM Sans font styling and includes truncation for long names/subtitles to prevent layout overflow. It's designed to be flexible with optional props while maintaining consistent visual patterns across the application.
+> **Image proxying:** `avatarUrl` is automatically passed through `getProxiedImageUrl`; the original URL is used as a fallback if the proxy returns `null`.
+
+**Source:** [`user-display.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/user-display.tsx)

package/src/components/.user-summary-stub.md

@@ -1,57 +1,64 @@
-<!-- source-hash: e8fdad9190b0ce783dc9a5712636e90d -->
-A client-side React component that renders a user profile summary card with avatar, name, email/subtitle, auth provider icons, and optional MSP organization preview data.
+<!-- source-hash: a3840a17be72a89053bcafc4a27bfd01 -->
+A client-side React component that renders a user profile summary card with avatar, name, email/subtitle, auth provider icons, and optional MSP organization preview — supporting both full and compact display modes.
 
 ## Key Components
 
-### `UserSummary` (exported component)
-The primary export. Accepts a `Props` interface and renders in two layout modes:
-- **Compact mode** (`compact=true`): Horizontal row with small avatar, name, and subtitle — intended for comment headers or inline contexts.
-- **Full mode** (default): Vertical card with large avatar, name, email, MSP info row, and auth provider badges. Responsive with a separate mobile row for auth/edit controls.
-
-### `getAuthProviderIcon(provider)`
-Internal helper that maps provider strings (`"google"`, `"microsoft"`, `"azure"`, `"slack"`) to icon elements.
-
-### `formatNumber(n)`
-Internal utility that abbreviates large numbers (e.g., `1200 → 1.2K`, `2000000 → 2M`, `1500000000 → 1.5B`).
-
-## Key Props
+### `UserSummary` (default export)
+The primary component accepting the following props:
 
 | Prop | Type | Description |
 |---|---|---|
-| `name` / `email` | `string` | Required user identity fields |
-| `avatarUrl` | `string \| null` | Optional avatar, proxied via `getProxiedImageUrl` |
-| `mspPreview` | object | Optional MSP org info (name, seats, revenue, logo badge) |
-| `compact` | `boolean` | Switches to minimal horizontal layout |
-| `authProviders` | `string[]` | Displays provider icons (Google, Microsoft, Slack) |
-| `showEditButton` | `boolean` | Shows an edit profile affordance |
+| `name` | `string` | User's display name |
+| `email` | `string` | User's email address |
+| `avatarUrl` | `string \| null` | Optional avatar image URL (proxied) |
+| `subtitle` | `string \| null` | Replaces the email line when provided |
+| `authProviders` | `string[]` | Provider names (e.g. `"google"`, `"microsoft"`) |
+| `mspPreview` | `object \| null` | MSP org info: name, logo, seat/technician count, revenue |
+| `compact` | `boolean` | Horizontal mini-row mode for comment headers |
+| `avatarSize` | `number` | Avatar px size in compact mode (default `40`) |
+| `showEditButton` | `boolean` | Renders an Edit Profile placeholder |
+| `editablePhoto` | `boolean` | Swaps static avatar for an upload widget |
+| `onPhotoChange` | `(url) => void` | Callback when photo is updated |
+
+### Internal Helpers
+
+- **`getAuthProviderIcon(provider)`** — returns an `<Image>` or fallback `<div>` for Google, Microsoft/Azure, and Slack providers.
+- **`formatNumber(n)`** — abbreviates large numbers to `K`, `M`, or `B` suffixes (e.g. `15000 → 15K`).
 
 ## Usage Example
 
 ```typescript
 import { UserSummary } from "./user-summary-stub";
 
-// Full card with MSP info
+// Full card
 <UserSummary
-  name="Jane Smith"
+  name="Jane Doe"
   email="jane@example.com"
-  avatarUrl="https://cdn.example.com/jane.jpg"
+  avatarUrl="https://cdn.example.com/avatar.png"
   authProviders={["google"]}
-  showEditButton
   mspPreview={{
-    name: "Acme MSP",
-    seatCount: 1500,
-    technicianCount: 12,
-    annualRevenue: 2000000,
-    logoUrl: "https://cdn.example.com/acme-logo.png",
+    name: "Acme IT",
+    seatCount: 1200,
+    technicianCount: 8,
+    annualRevenue: 2500000,
+    logoUrl: "https://cdn.example.com/msp-logo.png",
   }}
+  showEditButton
 />
 
-// Compact mode for comment headers
+// Compact mode (e.g. comment header)
 <UserSummary
-  name="Jane Smith"
+  name="Jane Doe"
   email="jane@example.com"
+  subtitle="2 hours ago"
   compact
   avatarSize={32}
-  subtitle="2 hours ago"
 />
-```
+```
+
+## Notes
+
+- Avatar images are routed through `getProxiedImageUrl` to avoid CORS/hotlinking issues.
+- Falls back to initials (up to 2 characters in compact, 1 character in full mode) when no `avatarUrl` is provided.
+- Auth provider icons and the Edit button are rendered in a responsive layout — stacked on mobile, inline on `md+` screens.
+- Source: [`user-summary-stub.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/user-summary-stub.tsx)

package/src/components/.vendor-display-button.md

@@ -1,38 +1,40 @@
-<!-- source-hash: 6fb4d3c3dedfd71f1af226c49bd112fd -->
-A client-side React button component that renders a vendor with its logo and title, supporting two visual variants and navigation to vendor profile pages.
+<!-- source-hash: e35b5566a5ac5d477a67495f201ffd48 -->
+A React client component that renders a clickable vendor button with logo and title, supporting two visual variants (`default` and `compact`) and two navigation modes (external URL or callback).
 
 ## Key Components
 
 ### `VendorDisplayButtonProps`
+
 | Prop | Type | Description |
 |------|------|-------------|
 | `vendor` | `VendorWithMedia` | Vendor data including slug, title, and media |
-| `onClick` | `(vendorSlug: string) => void` | Optional internal click handler |
-| `variant` | `'default' \| 'compact'` | Display style (defaults to `'default'`) |
-| `externalUrl` | `string` | Fallback base URL for external navigation |
+| `onClick` | `(vendorSlug: string) => void` | Callback invoked with the vendor slug (used when no `externalUrl`) |
+| `variant` | `'default' \| 'compact'` | Visual size variant; defaults to `'default'` |
+| `externalUrl` | `string` | Caller-resolved platform base URL; opens `{externalUrl}/vendor/{slug}` in a new tab |
 
 ### `VendorDisplayButton`
-Main export. Renders one of two button variants:
-- **`default`** — Card-style button with an 8×8 logo container, used in standard listings
-- **`compact`** — Pill-shaped button with a smaller 5×5 logo, designed for teaser/inline contexts (e.g. `flamingo-teaser`)
 
-Logo display gracefully falls back to the vendor's initial character when no logo URL is available. External navigation uses `NEXT_PUBLIC_OPENMSP_URL` env variable with `externalUrl` as fallback, opening in a new tab.
+Exported named component. Renders either:
+- **`compact`** — pill-shaped button (`rounded-full`) with a 20×20px logo, suited for inline teaser contexts.
+- **`default`** — card-style button (`rounded-lg`) with a 24×24px logo in an 8×8 container, suited for list or grid layouts.
+
+Both variants fall back to an uppercase initial letter when no logo is available, and route clicks through a shared `handleClick` that prefers `externalUrl` over the `onClick` callback.
 
 ## Usage Example
 
 ```typescript
-import { VendorDisplayButton } from "./vendor-display-button"
-
-// Default variant — navigates externally
+// External URL navigation (opens OpenMSP vendor page in new tab)
 <VendorDisplayButton
   vendor={vendorWithMedia}
-  externalUrl="https://www.openmsp.ai"
+  externalUrl="https://openmsp.ai"
 />
 
-// Compact variant — triggers internal handler
+// Compact variant with local callback
 <VendorDisplayButton
   vendor={vendorWithMedia}
   variant="compact"
   onClick={(slug) => router.push(`/vendors/${slug}`)}
 />
-```
+```
+
+> **Note:** `externalUrl` should be a fully-qualified, scheme-normalized URL (e.g. `https://openmsp.ai`) — not a scheme-less string — to avoid the relative `window.open()` bug that existed with the removed `NEXT_PUBLIC_OPENMSP_URL` environment variable.

package/src/components/.vendor-icon.md

@@ -1,5 +1,5 @@
-<!-- source-hash: f84ca33f36e32d62304615a416d5acac -->
-Renders a vendor logo icon with configurable size, background style, and fallback initials when no logo is available.
+<!-- source-hash: 0675587ecef66c442db7c41fb0de799a -->
+Renders a vendor logo image with configurable size, background style, and fallback initials display for use across comparison tables, dropdowns, and other UI contexts.
 
 ## Key Components
 
@@ -7,46 +7,38 @@ Renders a vendor logo icon with configurable size, background style, and fallbac
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `vendor` | `VendorWithMedia & { id?, title, slug?, logo? }` | — | Vendor data including logo URL |
-| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'l' \| 'xl'` | `'md'` | Icon container size |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'l' \| 'xl'` | `'md'` | Controls container and image dimensions |
 | `className` | `string` | `''` | Additional CSS classes |
-| `showBackground` | `boolean` | `true` | Toggles container background/border |
-| `backgroundStyle` | `'dark' \| 'light' \| 'white'` | `'dark'` | Container background variant |
+| `showBackground` | `boolean` | `true` | Toggles rounded background container |
+| `backgroundStyle` | `'dark' \| 'light' \| 'white'` | `'dark'` | Background and border color theme |
 
-### Size Map
-| Size | Container | Image (px) |
-|------|-----------|------------|
-| `xs` | 24×24 | 16×16 |
-| `sm` | 32×32 | 20×20 |
-| `md` | 40×40 | 32×32 |
-| `lg` | 48×48 | 40×40 |
-| `xl` | 64×64 | 40×40 |
-
-### `VendorIcon` (named export)
-The primary export. Resolves the logo via `getVendorLogo`, proxies the URL via `getProxiedImageUrl`, and falls back to a two-character uppercase initials placeholder when no logo is found.
+### `VendorIcon` (exported component)
+Resolves the logo URL via `getVendorLogo`, proxies it through `getProxiedImageUrl`, and renders an `Image` element. Falls back to a two-character uppercase initials placeholder when no logo is available.
 
 ## Usage Example
 
 ```typescript
 import { VendorIcon } from './vendor-icon'
 
-// Default dark background, medium size
-<VendorIcon vendor={vendor} />
+// Basic usage with defaults
+<VendorIcon vendor={{ title: 'Acme Corp', logo: 'https://cdn.example.com/acme.png' }} />
 
-// White background, large, no border
+// Large icon with white background, no border
 <VendorIcon
-  vendor={vendor}
-  size="lg"
+  vendor={{ title: 'Acme Corp', logo: 'https://cdn.example.com/acme.png' }}
+  size="xl"
   backgroundStyle="white"
-  showBackground={true}
 />
 
-// Logo only, no background (e.g. inside a styled card)
+// No background — fills parent container directly
 <VendorIcon
-  vendor={vendor}
+  vendor={{ title: 'Unknown Vendor' }}
   size="sm"
   showBackground={false}
   className="rounded-full"
 />
 ```
 
-> When `logoUrl` resolves to `null` or `undefined`, the component renders a dark/light pill with the first two characters of `vendor.title` (e.g. `"MI"` for *Microsoft*).
+When `logo` is absent or resolves to falsy, the component renders the first two characters of `vendor.title` (e.g. `"AC"`) as a text placeholder, respecting the active `backgroundStyle` for text color.
+
+**Source:** [`vendor-icon.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/vendor-icon.tsx)