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

package/src/components/.faq-accordion.md

@@ -1,48 +1,38 @@
-<!-- source-hash: 287c2bd98ac7a3ef2c0c3e9abfc07ed3 -->
-Accessible, animated FAQ accordion component that renders a list of question/answer pairs with smooth height transitions and keyboard navigation support.
+<!-- source-hash: ca93087dff304ae780464b5f1cefad86 -->
+An accessible, animated accordion component for rendering FAQ items with smooth expand/collapse transitions and deep-link anchor support.
 
 ## Key Components
 
 ### Interfaces
-- **`FaqItem`** — Data shape for each FAQ entry (`id`, `question`, `answer`)
-- **`FaqAccordionProps`** — Component props accepting `items` array and optional `defaultOpenIds` for pre-expanded panels
 
-### Hooks
-- **`useMeasuredHeight(isOpen)`** — Internal hook that measures `scrollHeight` outside the render cycle to drive CSS `max-height` animations; returns `ref` and `maxHeight` string
+- **`FaqItem`** — Data shape for a single FAQ entry with `id`, `question`, and `answer` fields
+- **`FaqAccordionProps`** — Props accepting an array of `FaqItem` and optional `defaultOpenIds` for pre-expanded items
+
+### Hook
+
+- **`useMeasuredHeight(isOpen)`** — Internal hook that reads `scrollHeight` outside the render cycle to drive CSS `max-height` animations without layout thrashing. Returns `ref` and `maxHeight` string.
 
 ### Component
-- **`FaqAccordion`** — Main export; manages a `Set`-based open/close state, renders each item with animated expansion, `aria-expanded` attribute, and keyboard (`Enter`/`Space`) support
+
+- **`FaqAccordion`** — Stateful accordion managing open/close state via a `Set`, rendering each item with a clickable header, animated content panel, and per-item anchor ID for hash-based deep linking (e.g. `/faqs#faq-item-<id>`).
 
 ## Usage Example
 
 ```typescript
 import { FaqAccordion, FaqItem } from './faq-accordion'
 
-const faqs: FaqItem[] = [
-  {
-    id: 1,
-    question: 'What is Flamingo?',
-    answer: 'Flamingo is an AI-powered MSP platform that replaces expensive proprietary software.',
-  },
-  {
-    id: 2,
-    question: 'What is OpenFrame?',
-    answer: 'OpenFrame is a unified platform integrating multiple MSP tools into a single AI-driven interface.',
-  },
+const items: FaqItem[] = [
+  { id: 1, question: 'What is OpenFrame?', answer: 'A unified MSP platform...' },
+  { id: 2, question: 'How does Mingo AI work?', answer: 'It automates triage...' },
 ]
 
-export default function FaqPage() {
-  return (
-    <FaqAccordion
-      items={faqs}
-      defaultOpenIds={[1]} // First item open by default
-    />
-  )
-}
+// Render with the second item open by default
+<FaqAccordion items={items} defaultOpenIds={[2]} />
 ```
 
-## Notes
+## Behavior Notes
 
-- Multiple panels can be open simultaneously
-- Height animation uses a measured `scrollHeight` approach rather than fixed values, so dynamic content is handled correctly
-- Fully keyboard accessible via `role="button"`, `tabIndex`, and `onKeyDown` handlers
+- **Keyboard accessible** — `Enter` and `Space` toggle items; `aria-expanded` reflects open state
+- **Scroll margin** — Each row has `scroll-mt-24` so sticky nav (96px) doesn't obscure the header on hash navigation
+- **Animation** — `max-height` + `opacity` transition at 350ms `ease-in-out`; height is measured lazily on open to support dynamic content
+- **Mobile safety** — `break-words` prevents long URLs or tokens from clipping inside the `overflow-hidden` panel

package/src/components/.filter-chip.md

@@ -1,56 +1,59 @@
-<!-- source-hash: fe89e2561aca7887d4e55361b739f66e -->
-Reusable pill-shaped filter chip component for displaying and managing active filters, category tags, and selection states across the UI.
+<!-- source-hash: 60260aec5918ec31a661ffb15daaa6aa -->
+A reusable, accessible filter chip UI component for displaying and interacting with filter tags, supporting multiple visual variants, optional removal, and responsive sizing.
 
 ## Key Components
 
-### `FilterChip`
-The sole export — a styled, accessible chip element built with Tailwind CSS classes via `cn`.
-
 ### `FilterChipProps`
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `id` | `string` | — | Unique identifier |
-| `label` | `string` | — | Display text (truncated with tooltip) |
+| `id` | `string` | — | Unique identifier for the chip |
+| `label` | `string` | — | Display text, truncated with tooltip on overflow |
 | `variant` | `'selected' \| 'unselected' \| 'category' \| 'subcategory' \| 'tag' \| 'info'` | `'unselected'` | Visual style preset |
-| `size` | `'sm' \| 'md'` | `'md'` | Controls padding and text sizing |
-| `removable` | `boolean` | `false` | Shows an `×` remove button when `true` |
-| `onRemove` | `() => void` | — | Callback fired when remove button is clicked |
-| `onClick` | `() => void` | — | Makes the chip interactive as a toggle button |
-| `disabled` | `boolean` | `false` | Dims chip and disables all interactions |
-| `className` | `string` | — | Additional Tailwind classes |
-
-**Variants summary:**
-- `selected` / `category` / `subcategory` / `tag` — yellow (`#FFC008`) border at varying opacities for hierarchy
-- `unselected` — neutral dark border
-- `info` — static display only, hover/scale effects disabled
+| `size` | `'sm' \| 'md'` | `'md'` | Controls padding and text size |
+| `removable` | `boolean` | `false` | Shows an `X` button when `true` |
+| `onRemove` | `() => void` | — | Callback fired when the remove button is clicked |
+| `onClick` | `() => void` | — | Callback fired when the chip itself is clicked |
+| `disabled` | `boolean` | `false` | Disables all interactions and reduces opacity |
+| `className` | `string` | — | Additional Tailwind classes for overrides |
+
+### `FilterChip`
+
+The exported component renders a styled pill-shaped chip. Variant classes use ODS (OpenFrame Design System) tokens for consistent theming. The `category`, `subcategory`, and `tag` variants use accent color borders at varying opacity levels to signal hierarchy subtly.
 
 ## Usage Example
 
 ```typescript
-// Basic selectable filter
+import { FilterChip } from "@/components/filter-chip"
+
+// Basic interactive chip
 <FilterChip
-  id="status-active"
-  label="Active"
+  id="filter-os"
+  label="Windows"
   variant="selected"
-  onClick={() => toggleFilter('active')}
+  onClick={() => toggleFilter("windows")}
 />
 
-// Removable tag chip
+// Removable category chip
 <FilterChip
-  id="tag-windows"
-  label="Windows"
-  variant="tag"
+  id="filter-category-network"
+  label="Networking"
+  variant="category"
   removable
-  onRemove={() => removeTag('windows')}
+  onRemove={() => removeCategory("network")}
 />
 
-// Small category chip (disabled)
+// Small info chip (non-interactive)
 <FilterChip
-  id="cat-networking"
-  label="Networking"
-  variant="category"
+  id="chip-count"
+  label="42 results"
+  variant="info"
   size="sm"
-  disabled
 />
-```
+```
+
+## Notes
+
+- Keyboard accessible: chips with `onClick` receive `tabIndex={0}` and `role="button"`; the remove button includes `aria-label` for screen readers.
+- Click events call `stopPropagation` to prevent conflicts when chips are nested inside other interactive elements.
+- Label text truncates at `120px` (`md`) or `100px` (`sm`) with a native `title` tooltip for full text on hover.

package/src/components/.footer-waitlist-button.md

@@ -1,18 +1,17 @@
-<!-- source-hash: 8e25a68fa3e51dd5cde8b484877f10f2 -->
-A footer button component that navigates users to the OpenFrame waitlist page, routing through the unified navigation system when available.
+<!-- source-hash: 4d908f9cf7af91751965e17795b7dff2 -->
+A footer UI component that renders a "Join Waitlist" button, routing navigation through the unified `ChatRuntimeContext` navigation hook when available, with a fallback to the embed-shim router.
 
 ## Key Components
 
 ### `FooterWaitlistButtonProps`
-- `className?: string` — Optional CSS class for styling overrides.
+Interface with a single optional `className` prop for styling overrides.
 
 ### `FooterWaitlistButton`
-A `Button` wrapper that handles navigation to `/waitlist#top` via a two-tier fallback strategy:
-
-1. **Primary:** `runtime.navigation.navigate` — the host's unified-nav hook (provided by `HubRuntimeProvider`), which handles cross-platform new-tab decisions, same-URL re-scroll, and embed-mode short-circuiting.
-2. **Fallback:** `router.push` via the embed-shim's `useRouter` — used when no `ChatRuntimeContext` is mounted (e.g., third-party embedders).
-
-Renders with the `OpenFrameLogo` icon as a left icon inside the button.
+Client-side React component that:
+- Resolves the active navigation strategy at runtime via `executeNavigationImperative`
+- Uses `runtime.navigation.navigate` when a `ChatRuntimeContext` is mounted (inherits cross-platform new-tab decisions, embed-mode handling, same-URL re-scroll, and future host nav rules)
+- Falls back to the embed-shim's `router.push` when no runtime context is present, keeping the library usable without requiring full chat-runtime setup
+- Navigates to `/waitlist#top`, where `#top` anchors to an explicit `<div id="top">` at the top of `<main>` for reliable cross-browser scroll behavior
 
 ## Usage Example
 
@@ -20,26 +19,33 @@ Renders with the `OpenFrameLogo` icon as a left icon inside the button.
 import { FooterWaitlistButton } from './footer-waitlist-button';
 
 // Basic usage inside a footer layout
-export function AppFooter() {
+export function SiteFooter() {
   return (
     <footer>
       <FooterWaitlistButton className="mt-4 w-full" />
     </footer>
   );
 }
-```
 
-> **Navigation note:** The `#top` anchor targets an explicit `<div id="top">` at the top of the waitlist page's `<main>` element, ensuring consistent scroll behavior across all browsers regardless of HTML5 magic-anchor handling.
+// Without ChatRuntimeContext — falls back to embed-shim router.push
+export function StandaloneEmbed() {
+  return (
+    <div>
+      <FooterWaitlistButton />
+    </div>
+  );
+}
+```
 
-## Navigation Flow
+## Navigation Resolution
 
 ```mermaid
 graph TD
-    A["FooterWaitlistButton clicked"] --> B{"runtime.navigation.navigate available?"}
-    B -->|Yes| C["Call runtime.navigation.navigate"]
-    C --> D{"Handled?"}
-    D -->|Yes| E["Done - unified nav handled"]
-    D -->|No| F["Fallback: router.push"]
-    B -->|No| F
-    F --> G["Navigate to /waitlist#top"]
-```
+    A[Button Click] --> B{ChatRuntimeContext mounted?}
+    B -->|Yes| C[runtime.navigation.navigate]
+    B -->|No| D[embed-shim router.push]
+    C --> E[/waitlist#top]
+    D --> E
+```
+
+> **Source:** [`footer-waitlist-button.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/footer-waitlist-button.tsx)

package/src/components/.footer.md

@@ -1,53 +1,68 @@
-<!-- source-hash: 71df967a1bb27327de1d15d5c696e36b -->
-A configurable, platform-aware footer component for Next.js (client-side) that renders navigation sections, social icons, branding, and custom content slots based on a `FooterConfig` object.
+<!-- source-hash: dc228d826a1ea8db2b14ac844ec17eeb -->
+A configuration-driven, client-side footer component that renders a responsive multi-column layout based on a `FooterConfig` object, with no hardcoded content.
 
 ## Key Components
 
-**`Footer`** — Public entry point. Validates config presence and delegates to `UniversalFooter`. Returns `null` with a console warning if no config is provided.
+### Interfaces
 
-**`UniversalFooter`** — Core rendering logic. Builds a responsive 4-column grid layout with:
-- **Column 1:** Logo, platform name, description, social icons (`SocialIconRow`)
-- **Dynamic sections:** Rendered from `config.sections[]`
-- **Custom component slot:** `config.customComponent`
-- **Right column slot:** `config.rightColumnContent` or relocated description via `config.moveDescriptionToRight`
+- **`FooterConfig`** — Primary configuration shape controlling logo, sections, social links, layout flags, and styling
+- **`FooterSection`** / **`FooterLink`** — Define the link columns rendered in the footer grid
+- **`FooterProps`** — Props for the public `Footer` export; accepts `config` and an optional custom `renderLink` renderer
 
-**`FooterConfig`** — Interface driving all layout behavior. Key flags:
+### Exported Components
+
+- **`Footer`** — Public entry point; guards against missing config and delegates to `UniversalFooter`
+
+### Internal Components
+
+- **`UniversalFooter`** — Renders the full footer grid: logo column, dynamic link sections, optional custom component slot, right column, and copyright
+- **`NavLinkSkeleton`** — Suspense fallback for individual nav links
+
+### Layout Flags (`FooterConfig`)
 
 | Flag | Effect |
-|------|--------|
-| `moveDescriptionToRight` | Moves description to the right column |
-| `keepBelowDescriptionLeft` | Keeps `belowDescriptionContent` in column 1 when description is moved |
+|---|---|
+| `moveDescriptionToRight` | Moves description text to the right column |
+| `keepBelowDescriptionLeft` | Retains `belowDescriptionContent` on the left when description is moved |
 | `hideSocialRow` | Suppresses the `SocialIconRow` |
-| `backgroundColor` | ODS utility class override (default: `bg-ods-card`) |
-
-**`renderLink`** — Optional prop to override the default anchor renderer per link.
+| `backgroundColor` | Overrides the default `bg-ods-card` Tailwind class |
 
 ## Usage Example
 
 ```typescript
 import { Footer } from "@/components/footer"
 
-const config: FooterConfig = {
-  name: "Flamingo",
-  legalName: "Flamingo Technologies Inc.",
+const config = {
+  name: "OpenFrame",
+  legalName: "Flamingo Stack Inc.",
   description: "AI-powered MSP platform.",
   sections: [
     {
       title: "Product",
       links: [
-        { href: "/openframe", label: "OpenFrame" },
+        { href: "/features", label: "Features" },
         { href: "/pricing", label: "Pricing" },
       ],
     },
   ],
   social: {
-    github: "https://github.com/flamingo",
-    twitter: "https://twitter.com/flamingo",
+    github: "https://github.com/flamingo-stack/openframe-oss-lib",
+    discord: "https://www.openmsp.ai/",
   },
-  backgroundColor: "bg-ods-bg",
 }
 
 export default function Layout() {
-  return <Footer config={config} />
+  return (
+    <Footer
+      config={config}
+      renderLink={(link) => (
+        <a href={link.href} className="custom-link">
+          {link.label}
+        </a>
+      )}
+    />
+  )
 }
-```
+```
+
+> **Note:** `config` is required. If omitted, the component returns `null` and logs a warning — there are no hardcoded fallback values.

package/src/components/.form.md

@@ -1,49 +1,61 @@
-<!-- source-hash: 5c621a80fa78cd0b2d7325f392c2df01 -->
-A comprehensive form component system built on top of react-hook-form and Radix UI primitives, providing accessible form elements with automatic error handling and validation state management.
+<!-- source-hash: 4c16af16fe805c06acff7fd15a83fe05 -->
+Accessible form primitives built on top of `react-hook-form` and Radix UI, providing context-aware field wrappers with built-in ARIA attributes, error styling, and label association.
 
 ## Key Components
 
-- **Form**: Alias for react-hook-form's `FormProvider` to wrap form contexts
-- **FormField**: Wrapper around react-hook-form's `Controller` with context integration
-- **FormItem**: Container component that provides unique IDs for form field associations
-- **FormLabel**: Accessible label component with automatic error styling
-- **FormControl**: Control wrapper with ARIA attributes for accessibility
-- **FormDescription**: Helper text component linked via `aria-describedby`
-- **FormMessage**: Error message component that displays validation errors
-- **useFormField**: Custom hook providing form field state and accessibility IDs
+| Export | Description |
+|---|---|
+| `Form` | Re-export of `react-hook-form`'s `FormProvider` — wraps the entire form |
+| `FormField` | Wraps `Controller` and injects field name into context |
+| `FormItem` | Container div that generates a unique `id` for ARIA linkage |
+| `FormLabel` | Label that auto-links to the field input and applies `text-destructive` on error |
+| `FormControl` | Radix `Slot` with pre-wired `id`, `aria-describedby`, and `aria-invalid` |
+| `FormDescription` | Helper text paragraph linked via `aria-describedby` |
+| `FormMessage` | Displays validation error messages (or custom children) with destructive styling |
+| `useFormField` | Hook exposing field state, IDs, and error info — must be used inside `<FormField>` |
 
 ## Usage Example
 
 ```typescript
 import { useForm } from "react-hook-form"
-import { Form, FormField, FormItem, FormLabel, FormControl, FormMessage } from "./form"
+import {
+  Form,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormControl,
+  FormDescription,
+  FormMessage,
+} from "./form"
 import { Input } from "./ui/input"
 
-function MyForm() {
-  const form = useForm({
-    defaultValues: { email: "" }
-  })
+function ProfileForm() {
+  const form = useForm<{ username: string }>()
 
   return (
     <Form {...form}>
-      <form onSubmit={form.handleSubmit(onSubmit)}>
+      <form onSubmit={form.handleSubmit(console.log)}>
         <FormField
           control={form.control}
-          name="email"
+          name="username"
           render={({ field }) => (
             <FormItem>
-              <FormLabel>Email</FormLabel>
+              <FormLabel>Username</FormLabel>
               <FormControl>
-                <Input placeholder="Enter email" {...field} />
+                <Input placeholder="flamingo-user" {...field} />
               </FormControl>
+              <FormDescription>Your public display name.</FormDescription>
               <FormMessage />
             </FormItem>
           )}
         />
+        <button type="submit">Submit</button>
       </form>
     </Form>
   )
 }
 ```
 
-The system automatically handles ARIA attributes, error states, and accessibility concerns while maintaining type safety with TypeScript generics for field values and names.
+> **Note:** `useFormField` must only be called within a `<FormField>` tree; it throws if `FormFieldContext` is missing.
+
+**Source:** [`form.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/form.tsx)

package/src/components/.hero-image-uploader.md

@@ -1,54 +1,58 @@
-<!-- source-hash: 61d27934627ce1b9a3b2c8e253f66d56 -->
-A React component for uploading hero/cover images with drag-and-drop functionality, file validation, and customizable upload handling. Provides both authenticated and deferred upload modes.
+<!-- source-hash: b371bcdc8a33778b126fd82289475ae3 -->
+Reusable React component for hero-style image uploading with client-side validation, preview, and flexible upload strategies including deferred (base64 preview) and custom authenticated upload handlers.
 
 ## Key Components
 
-- **HeroImageUploader** - Main component with file validation (JPEG/PNG/WebP/GIF, 5MB max)
-- **HeroImageUploaderProps** - Interface defining component configuration options
-- **File validation** - Client-side type and size checking with toast notifications
-- **Upload modes** - Standard upload, deferred upload (base64 preview), or custom handlers
-- **Image preview** - Shows uploaded image with hover overlay for replace/remove actions
+### `HeroImageUploaderProps`
+
+| Prop | Type | Description |
+|---|---|---|
+| `imageUrl` | `string?` | Existing image URL to display |
+| `onChange` | `(url: string \| undefined) => void` | Fires with new URL or `undefined` on removal |
+| `uploadEndpoint` | `string` | POST endpoint for default upload flow |
+| `height` | `number \| string` | Drop-zone height; numbers treated as `px` |
+| `objectFit` | `string` | CSS `object-fit` for preview image (default: `'cover'`) |
+| `deferUpload` | `boolean` | Return base64 data URL instead of uploading (unauthenticated flows) |
+| `onUpload` | `(file: File) => Promise<string>` | Custom authenticated upload handler |
+| `onDelete` | `() => Promise<void>` | Custom delete handler |
+
+### Internal Logic
+
+- **`handleFile`** — validates MIME type (JPEG/PNG/WebP/GIF) and file size (≤ 5 MB), then routes to deferred preview, custom `onUpload`, or default `fetch` POST
+- **`handleRemove`** — calls optional `onDelete` before clearing state via `onChange(undefined)`
+- **`openDialog`** — programmatically triggers the hidden `<input type="file">`
 
 ## Usage Example
 
 ```typescript
-import { HeroImageUploader } from './hero-image-uploader';
-
-// Basic usage with standard upload
+// Default upload flow
 <HeroImageUploader
-  imageUrl={currentImage}
-  onChange={(url) => setCurrentImage(url)}
   uploadEndpoint="/api/upload"
-  height={400}
-  objectFit="cover"
+  onChange={(url) => setHeroImage(url)}
 />
 
-// Deferred upload mode (returns base64 preview)
+// Deferred upload (unauthenticated preview)
 <HeroImageUploader
-  imageUrl={previewImage}
-  onChange={(url) => setPreviewImage(url)}
   uploadEndpoint="/api/upload"
   deferUpload={true}
+  onChange={(dataUrl) => setLocalPreview(dataUrl)}
 />
 
-// Custom upload handler for authenticated uploads
+// Custom authenticated upload
 <HeroImageUploader
-  imageUrl={heroImage}
-  onChange={setHeroImage}
   uploadEndpoint="/api/upload"
+  imageUrl={currentImage}
   onUpload={async (file) => {
-    const formData = new FormData();
-    formData.append('file', file);
-    const response = await authenticatedFetch('/api/upload', {
-      method: 'POST',
-      body: formData
-    });
-    return response.url;
+    const { url } = await myAuthenticatedUpload(file);
+    return url;
   }}
   onDelete={async () => {
-    await authenticatedFetch(`/api/images/${imageId}`, {
-      method: 'DELETE'
-    });
+    await myAuthenticatedDelete(currentImageId);
   }}
+  onChange={(url) => setHeroImage(url)}
+  height={400}
+  objectFit="contain"
 />
-```
+```
+
+**Source:** [`hero-image-uploader.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/hero-image-uploader.tsx)

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

@@ -0,0 +1,53 @@
+<!-- source-hash: fe7a0a95673575f637ece7b20bebd5c4 -->
+Renders a unified icon across all app surfaces (announcement bar, chat quick actions, AI-agent identity) using a consistent three-step resolution strategy.
+
+## Key Components
+
+### `EntityIconValue` (interface)
+Shared icon descriptor used throughout the app. Accepts one of:
+- `name` — library glyph name resolved via `resolveIcon`
+- `url` — uploaded image URL (takes priority over `name`)
+- `props` — additional props spread onto the resolved glyph (e.g. `{ color }`)
+
+### `EntityIcon` (component)
+The single icon-rendering path for the whole app. Resolution order:
+1. `url` → renders an `<img>` tag with `objectFit: contain`
+2. `name` ∈ `{fae, mingo}` → renders the packaged `AgentMark` brand component
+3. `name` → resolves a library glyph via `resolveIcon` and spreads `props`
+
+Falls back to an empty glyph when no `icon` is provided.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `icon` | `EntityIconValue \| null` | — | Icon descriptor |
+| `size` | `number` | `20` | Pixel size (width/height) |
+| `className` | `string` | — | Tailwind/CSS classes; enables responsive sizing |
+
+> **Sizing note:** When `className` is provided, sizing is controlled entirely by CSS (e.g. `w-6 md:w-8`). The `size` prop is only applied as an inline style when no `className` is given, preventing class overrides.
+
+## Usage Example
+
+```typescript
+import { EntityIcon, type EntityIconValue } from './icon-display'
+
+// Uploaded image
+const imageIcon: EntityIconValue = { url: 'https://cdn.example.com/logo.png' }
+
+// Brand agent mark
+const agentIcon: EntityIconValue = { name: 'mingo' }
+
+// Library glyph with custom color
+const glyphIcon: EntityIconValue = { name: 'shield', props: { color: '#FF5733' } }
+
+// Fixed size
+<EntityIcon icon={glyphIcon} size={24} />
+
+// Responsive via Tailwind
+<EntityIcon icon={agentIcon} className="w-6 md:w-8" />
+```
+
+## Source
+
+[`icon-display.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/icon-display.tsx)