@flamingo-stack/openframe-frontend-core 0.0.212 → 0.0.213-snapshot.20260528174436

package/src/components/.open-source-features.md

@@ -1,31 +1,48 @@
-<!-- source-hash: ec539582b686670df288033e71575765 -->
-A React component that showcases OpenFrame's open-source philosophy through a grid of feature cards with icons and descriptions, emphasizing transparency and community-driven development.
+<!-- source-hash: 86b90e3350490d5e683b6b4b06497f43 -->
+A Next.js client component that renders a responsive marketing section showcasing OpenFrame's open-source value propositions as a 4-column feature card grid.
 
 ## Key Components
 
-- **`FeatureCard`** - Individual card component displaying an icon, title, and description with hover effects
-- **`OpenSourceFeatures`** - Main section component rendering a bold headline and 4-column grid of features
-- **`FeatureCardProps`** - TypeScript interface defining the structure for feature card properties
+- **`FeatureCard`** — Reusable card component accepting an icon, title, and description; renders with hover transition styling using ODS design tokens
+- **`OpenSourceFeatures`** — Main section component that composes the feature grid with a headline and four predefined feature entries
+- **`features` array** — Static data defining the four pillars: *Built on FOSS*, *Own Your Stack*, *Modular by Design*, and *Community-Powered*
+
+## Props
+
+### `FeatureCardProps`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `icon` | `React.ReactNode` | Lucide icon element rendered in the card header |
+| `title` | `string` | Feature headline text |
+| `description` | `string` | Supporting body copy |
 
 ## Usage Example
 
 ```typescript
-import OpenSourceFeatures from './components/open-source-features';
+import OpenSourceFeatures from '@/components/open-source-features';
 
-// Use in a landing page or marketing section
-function HomePage() {
+// Drop into any page layout — no props required
+export default function LandingPage() {
   return (
-    <div>
+    <main>
       <OpenSourceFeatures />
-    </div>
+    </main>
   );
 }
 ```
 
-The component features a responsive grid layout (1 column on mobile, 2 on tablet, 4 on desktop) with cards highlighting:
-- **Built on FOSS** - Transparency and community-driven development
-- **Own Your Stack** - Control over tools and customization
-- **Modular by Design** - Flexible architecture
-- **Community-Powered** - User participation in roadmap
+To add a custom feature card standalone:
+
+```typescript
+import { FeatureCard } from '@/components/open-source-features';
+import { Shield } from 'lucide-react';
+
+<FeatureCard
+  icon={<Shield className="w-6 h-6" />}
+  title="Secure by Default"
+  description="Auditable code with no vendor lock-in."
+/>
+```
 
-Each card includes hover animations and uses Lucide React icons (Terminal, DollarSign, Network, Users) with consistent ODS (OpenFrame Design System) styling and typography.
+> **Note:** `FeatureCard` is not a named export by default — export it explicitly if reuse outside this component is needed. The section uses ODS design tokens (`ods-card`, `ods-border`, `ods-accent`) from the OpenFrame design system.

package/src/components/.pagination.md

@@ -1,60 +1,61 @@
-<!-- source-hash: 5b97dde4a783cfa59eae13fa66e6315f -->
-A React pagination component that provides smart page number display with ellipsis handling and accessibility features. The component automatically manages visible page numbers based on total pages and current position.
+<!-- source-hash: c4bd5081b24a42378ae712967abb83c2 -->
+Accessible pagination component with smart page number windowing, ellipsis truncation, and both a high-level `Pagination` component and low-level composable primitives.
 
 ## Key Components
 
-- **Pagination** - Main pagination component with intelligent page number generation
-- **PaginationContent** - Container component for pagination items
-- **PaginationItem** - Individual list item wrapper for pagination elements
-- **PaginationLink** - Clickable button component for page numbers
-- **PaginationEllipsis** - Visual indicator for hidden pages (...)
-- **PaginationPrevious** - Previous page navigation button
-- **PaginationNext** - Next page navigation button
+| Export | Type | Description |
+|--------|------|-------------|
+| `Pagination` | Component | All-in-one pagination with built-in windowing logic |
+| `PaginationContent` | Primitive | `<ul>` wrapper for custom pagination layouts |
+| `PaginationItem` | Primitive | `<li>` wrapper for individual page entries |
+| `PaginationLink` | Primitive | Styled `<button>` for page number links |
+| `PaginationEllipsis` | Primitive | `MoreHorizontal` icon span for truncated ranges |
+| `PaginationPrevious` | Primitive | Previous page `<button>` with chevron icon |
+| `PaginationNext` | Primitive | Next page `<button>` with chevron icon |
+
+### `PaginationProps`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `currentPage` | `number` | Active page (1-based) |
+| `totalPages` | `number` | Total number of pages |
+| `onPageChange` | `(page: number) => void` | Callback fired on page selection |
+| `className` | `string?` | Optional extra classes on the `<nav>` |
+
+**Windowing logic:** shows up to 5 page buttons — always including first and last — with ellipsis (`-1`/`-2` sentinels) filling gaps in between.
 
 ## Usage Example
 
 ```typescript
-import { Pagination } from "./pagination"
-
-export function DataTable() {
-  const [currentPage, setCurrentPage] = useState(1)
-  const totalPages = Math.ceil(totalItems / itemsPerPage)
-
-  return (
-    <div>
-      {/* Table content */}
-      
-      <Pagination
-        currentPage={currentPage}
-        totalPages={totalPages}
-        onPageChange={(page) => setCurrentPage(page)}
-        className="mt-4"
-      />
-    </div>
-  )
-}
-
-// Using individual components for custom layouts
-export function CustomPagination() {
-  return (
-    <nav>
-      <PaginationContent>
-        <PaginationItem>
-          <PaginationPrevious onClick={() => goToPrevious()} />
-        </PaginationItem>
-        <PaginationItem>
-          <PaginationLink onClick={() => goToPage(1)}>1</PaginationLink>
-        </PaginationItem>
-        <PaginationItem>
-          <PaginationEllipsis />
-        </PaginationItem>
-        <PaginationItem>
-          <PaginationNext onClick={() => goToNext()} />
-        </PaginationItem>
-      </PaginationContent>
-    </nav>
-  )
-}
+// High-level component
+import { Pagination } from "@/components/pagination"
+
+<Pagination
+  currentPage={3}
+  totalPages={20}
+  onPageChange={(page) => setCurrentPage(page)}
+/>
+```
+
+```typescript
+// Composable primitives for custom layouts
+import {
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+  PaginationEllipsis,
+} from "@/components/pagination"
+
+<nav>
+  <PaginationContent>
+    <PaginationItem><PaginationPrevious onClick={() => setPage(p => p - 1)} /></PaginationItem>
+    <PaginationItem><PaginationLink onClick={() => setPage(1)}>1</PaginationLink></PaginationItem>
+    <PaginationItem><PaginationEllipsis /></PaginationItem>
+    <PaginationItem><PaginationNext onClick={() => setPage(p => p + 1)} /></PaginationItem>
+  </PaginationContent>
+</nav>
 ```
 
-The component includes ARIA labels for screen readers, smart ellipsis placement, and responsive button sizing. It shows up to 5 pages with ellipsis when dealing with large page counts.
+> All interactive elements include `aria-label` and `aria-current="page"` attributes, and screen-reader-only text via `sr-only` spans for full accessibility compliance.

package/src/components/.provider-button.md

@@ -1,42 +1,40 @@
-<!-- source-hash: 8ea01942c03230213fd637a121e47ff3 -->
-A reusable React component that creates standardized authentication provider buttons with built-in styling and provider-specific labeling.
+<!-- source-hash: 0ff05b6970e5b50646e6f4906b4e794e -->
+A reusable OAuth/SSO button component that renders a styled sign-in button for supported identity providers.
 
 ## Key Components
 
-- **ProviderButton**: Forwardable React component that extends Button with provider-specific functionality
-- **ProviderButtonProps**: Interface extending button HTML attributes with provider selection and styling options
-- **providerNames**: Internal mapping of provider keys to display names
+- **`ProviderButtonProps`** — Extends native `HTMLButtonElement` attributes with:
+  - `provider` — Required. One of `'google' | 'microsoft' | 'slack' | 'github'`
+  - `variant` — `'accent' | 'outline'` (default: `'outline'`)
+  - `size` — `'default' | 'small-legacy'` (default: `'default'`)
+  - `loading` — Optional boolean for loading state
+
+- **`ProviderButton`** — `forwardRef` component wrapping the base `Button` UI primitive. Renders a full-width button with a default label of `"Sign in with {ProviderName}"` if no `children` are provided.
 
 ## Usage Example
 
 ```typescript
-import { ProviderButton } from "./provider-button"
+import { ProviderButton } from "@/components/provider-button"
 
-// Basic provider button with default styling
+// Default usage — label auto-generated
 <ProviderButton provider="google" />
 
-// Custom variant and size
-<ProviderButton 
-  provider="github" 
-  variant="primary" 
-  size="lg" 
-/>
-
-// With custom content and styling
-<ProviderButton 
+// With accent variant and custom label
+<ProviderButton
   provider="microsoft"
-  className="mb-4"
-  onClick={handleMicrosoftAuth}
+  variant="accent"
+  onClick={handleMicrosoftLogin}
 >
   Continue with Microsoft
 </ProviderButton>
 
-// Loading state
-<ProviderButton 
-  provider="slack" 
-  loading={true}
+// Compact size with loading state
+<ProviderButton
+  provider="github"
+  size="small-legacy"
+  loading={isAuthenticating}
   disabled={isAuthenticating}
 />
 ```
 
-The component automatically generates appropriate labels (e.g., "Sign in with Google") when no children are provided, supports all standard button attributes, and maintains consistent styling across different authentication providers.
+> **Note:** The `loading` prop is accepted via `ProviderButtonProps` and forwarded to the underlying `Button` primitive. Ensure the base `Button` component handles the `loading` state for visual feedback.

package/src/components/.select.md

@@ -1,17 +1,20 @@
-<!-- source-hash: eb641bd94ff499508fe8fb4c2fbad14a -->
-A React component library providing styled select dropdown components built on top of Radix UI primitives with Tailwind CSS styling and accessibility features.
+<!-- source-hash: edcc0618a769c715daef264fcd0292ee -->
+Accessible, styled select/dropdown component built on Radix UI primitives with Flamingo ODS design tokens and smooth open/close animations.
 
 ## Key Components
 
-- **Select** - Root select component wrapper (re-export of `SelectPrimitive.Root`)
-- **SelectTrigger** - Clickable trigger button with chevron icon and focus states
-- **SelectContent** - Dropdown content container with portal rendering and animations
-- **SelectItem** - Individual selectable options with check indicator
-- **SelectValue** - Displays the selected value (re-export of `SelectPrimitive.Value`)
-- **SelectLabel** - Section labels within the dropdown
-- **SelectGroup** - Groups related select items (re-export of `SelectPrimitive.Group`)
-- **SelectSeparator** - Visual divider between select items
-- **SelectScrollUpButton/SelectScrollDownButton** - Scroll controls for long lists
+| Export | Description |
+|--------|-------------|
+| `Select` | Root component managing open/value state |
+| `SelectTrigger` | Styled button that opens the dropdown, includes `ChevronDown` icon |
+| `SelectContent` | Animated portal-rendered dropdown container with scroll support |
+| `SelectItem` | Individual option with a `Check` indicator when selected |
+| `SelectGroup` | Groups related items together |
+| `SelectLabel` | Section label within a group |
+| `SelectValue` | Displays the currently selected value in the trigger |
+| `SelectSeparator` | Horizontal divider between items or groups |
+| `SelectScrollUpButton` | Scroll control shown when content overflows upward |
+| `SelectScrollDownButton` | Scroll control shown when content overflows downward |
 
 ## Usage Example
 
@@ -19,25 +22,33 @@ A React component library providing styled select dropdown components built on t
 import {
   Select,
   SelectContent,
+  SelectGroup,
   SelectItem,
+  SelectLabel,
+  SelectSeparator,
   SelectTrigger,
   SelectValue,
-} from "./select"
+} from "@/components/ui/select"
 
-function MySelect() {
+export function PrioritySelect() {
   return (
-    <Select>
-      <SelectTrigger className="w-[180px]">
-        <SelectValue placeholder="Select a fruit" />
+    <Select onValueChange={(value) => console.log(value)}>
+      <SelectTrigger className="w-[200px]">
+        <SelectValue placeholder="Select priority..." />
       </SelectTrigger>
       <SelectContent>
-        <SelectItem value="apple">Apple</SelectItem>
-        <SelectItem value="banana">Banana</SelectItem>
-        <SelectItem value="orange">Orange</SelectItem>
+        <SelectGroup>
+          <SelectLabel>Ticket Priority</SelectLabel>
+          <SelectItem value="critical">Critical</SelectItem>
+          <SelectItem value="high">High</SelectItem>
+          <SelectSeparator />
+          <SelectItem value="medium">Medium</SelectItem>
+          <SelectItem value="low">Low</SelectItem>
+        </SelectGroup>
       </SelectContent>
     </Select>
   )
 }
 ```
 
-The components include comprehensive styling for hover, focus, and disabled states, with smooth animations and proper ARIA accessibility support through Radix UI primitives.
+> All sub-components forward refs and accept native Radix UI props, allowing full customization via `className` alongside ODS defaults.

package/src/components/.sidebar.md

@@ -1,48 +1,58 @@
-<!-- source-hash: 8d8cb17e5763b4a44bbe6fa59037fe9a -->
-This React component provides a comprehensive sidebar navigation system with responsive behavior, keyboard shortcuts, and flexible theming options.
+<!-- source-hash: b66af7d5956b3733b491a303d043d297 -->
+A comprehensive sidebar UI component system providing collapsible, responsive navigation panels with mobile drawer support, keyboard shortcuts, and multiple layout variants.
 
 ## Key Components
 
-- **SidebarProvider** - Context provider managing sidebar state, mobile responsiveness, and keyboard shortcuts (Cmd/Ctrl+B)
-- **Sidebar** - Main sidebar container with variants (`sidebar`, `floating`, `inset`) and collapsible modes (`offcanvas`, `icon`, `none`)  
-- **SidebarTrigger** - Button component to toggle sidebar visibility
-- **SidebarRail** - Invisible resize handle for desktop sidebar interaction
-- **SidebarInset** - Main content area that adapts to sidebar state
-- **SidebarHeader/Footer** - Standard layout containers for sidebar top/bottom sections
-- **SidebarInput** - Styled input component for sidebar search/filters
-- **SidebarSeparator** - Visual divider component
-- **useSidebar** - Hook for accessing sidebar context and state
+| Component | Description |
+|-----------|-------------|
+| `SidebarProvider` | Context provider managing open/collapsed state, mobile detection, and cookie persistence |
+| `useSidebar` | Hook to access sidebar context (state, toggle, mobile status) |
+| `Sidebar` | Core sidebar container supporting `left`/`right` sides, `sidebar`/`floating`/`inset` variants, and `offcanvas`/`icon`/`none` collapsible modes |
+| `SidebarTrigger` | Button component that toggles the sidebar (with `PanelLeft` icon) |
+| `SidebarRail` | Thin interactive strip for resize/toggle on desktop |
+| `SidebarInset` | Main content area companion that adjusts layout based on sidebar state |
+| `SidebarInput` | Styled input field scoped to sidebar context |
+| `SidebarHeader` | Top section container for branding/navigation |
+| `SidebarFooter` | Bottom section container for user/settings actions |
+| `SidebarSeparator` | Styled divider using sidebar border token |
+| `SidebarContent` | Scrollable middle section for navigation items |
 
 ## Usage Example
 
 ```typescript
-import { 
-  SidebarProvider, 
-  Sidebar, 
-  SidebarContent, 
-  SidebarTrigger,
+import {
+  SidebarProvider,
+  Sidebar,
   SidebarHeader,
-  SidebarInset 
-} from './sidebar'
+  SidebarContent,
+  SidebarFooter,
+  SidebarTrigger,
+  SidebarInset,
+  useSidebar,
+} from "./sidebar"
 
-function AppLayout() {
+export function AppLayout() {
   return (
     <SidebarProvider defaultOpen={true}>
-      <Sidebar variant="floating" side="left">
+      <Sidebar side="left" variant="sidebar" collapsible="icon">
         <SidebarHeader>
-          <SidebarTrigger />
-          <h2>Navigation</h2>
+          <span>My App</span>
         </SidebarHeader>
         <SidebarContent>
           {/* Navigation items */}
         </SidebarContent>
+        <SidebarFooter>
+          {/* User profile */}
+        </SidebarFooter>
       </Sidebar>
+
       <SidebarInset>
-        {/* Main content */}
+        <SidebarTrigger />
+        {/* Page content */}
       </SidebarInset>
     </SidebarProvider>
   )
 }
 ```
 
-The component automatically handles mobile sheet overlays, desktop positioning, state persistence via cookies, and smooth animations between expanded/collapsed states.
+> **Keyboard shortcut:** `Ctrl+B` / `Cmd+B` toggles the sidebar globally. State is persisted via a 7-day cookie (`sidebar:state`). On mobile, the sidebar renders as a `Sheet` drawer automatically.

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

@@ -1,43 +1,41 @@
-<!-- source-hash: cd5b035679eaea29bc8651dbc5880a4f -->
-A smooth-animating accordion component built on top of Radix UI primitives that provides ultra-smooth height transitions using ResizeObserver for dynamic content measurement.
+<!-- source-hash: 8e2d34f99735f6301a4abd6dd93c8c3e -->
+A custom accordion component built on Radix UI primitives that provides ultra-smooth open/close animations using dynamic height measurement via `ResizeObserver`, replacing CSS variable-based transitions with pixel-precise `max-height` animation.
 
 ## Key Components
 
-- **`SmoothAccordion`** - Root wrapper component (re-exports Radix AccordionPrimitive.Root)
-- **`SmoothAccordionItem`** - Individual accordion item container with borderless styling
-- **`SmoothAccordionTrigger`** - Clickable header with label and animated chevron icon
-- **`SmoothAccordionContent`** - Content container with smooth height animations using ResizeObserver
+| Export | Type | Description |
+|--------|------|-------------|
+| `SmoothAccordion` | Component | Re-export of `AccordionPrimitive.Root` — the accordion container |
+| `SmoothAccordionItem` | `forwardRef` Component | Accordion item wrapper with border removed (`border-0`) |
+| `SmoothAccordionTrigger` | `forwardRef` Component | Clickable header with label text and an animated `ChevronButton` |
+| `SmoothAccordionContent` | `forwardRef` Component | Animated content panel using `ResizeObserver` for height tracking |
 
 ## Usage Example
 
 ```typescript
-import { 
-  SmoothAccordion, 
-  SmoothAccordionItem, 
-  SmoothAccordionTrigger, 
-  SmoothAccordionContent 
+import {
+  SmoothAccordion,
+  SmoothAccordionItem,
+  SmoothAccordionTrigger,
+  SmoothAccordionContent,
 } from './smooth-accordion';
 
-function FAQ() {
+export function FAQ() {
   return (
     <SmoothAccordion type="single" collapsible>
       <SmoothAccordionItem value="item-1">
-        <SmoothAccordionTrigger label="What is this component?" />
+        <SmoothAccordionTrigger label="What is Flamingo?" />
         <SmoothAccordionContent>
-          <div className="px-6 md:px-8">
-            This is a smooth accordion that automatically adjusts its height
-            based on content changes using ResizeObserver.
-          </div>
+          Flamingo is an AI-powered MSP platform that replaces expensive
+          proprietary software with open-source alternatives.
         </SmoothAccordionContent>
       </SmoothAccordionItem>
-      
+
       <SmoothAccordionItem value="item-2">
-        <SmoothAccordionTrigger label="How does the animation work?" />
+        <SmoothAccordionTrigger label="What is OpenFrame?" />
         <SmoothAccordionContent>
-          <div className="px-6 md:px-8">
-            Uses CSS transitions on max-height with dynamic measurement
-            for ultra-smooth expand/collapse animations.
-          </div>
+          OpenFrame is the unified platform integrating multiple MSP tools
+          into a single AI-driven interface.
         </SmoothAccordionContent>
       </SmoothAccordionItem>
     </SmoothAccordion>
@@ -45,4 +43,11 @@ function FAQ() {
 }
 ```
 
-The component features 0.35s ease-in-out transitions, automatic content height detection, and a rotating chevron indicator that responds to the accordion's open/closed state.
+## Animation Details
+
+`SmoothAccordionContent` avoids Radix's default CSS variable approach by:
+
+1. **Measuring** actual content height via `scrollHeight` on mount and child changes
+2. **Observing** dynamic content resize with a `ResizeObserver`
+3. **Animating** `max-height` and `opacity` over `0.35s ease-in-out`
+4. **Resetting** `maxHeight` to `0` after the close transition ends to prevent residual spacing

package/src/components/.social-icon-row.md

@@ -1,39 +1,43 @@
-<!-- source-hash: f7eff68f1ef3a2cc1a34d4c978b218c5 -->
-A React component that renders a responsive row of social media icons as clickable buttons, supporting multiple platforms with customizable styling and default Flamingo company links.
+<!-- source-hash: 5ee2a1885dc45a65b8396aea3f9f9f10 -->
+A client-side React component that renders a horizontal row of social media icon buttons with configurable links and styling variants.
 
 ## Key Components
 
-- **`SocialIconRow`** - Main component that renders social media icons in a horizontal row
-- **`SocialLink`** - Interface defining the structure for social media links (platform, href, label)
-- **`renderSocialIcon`** - Helper function that maps platform names to their corresponding icon components
-- **`defaultLinks`** - Pre-configured array of Flamingo's official social media profiles
+### Interfaces
+- **`SocialLink`** — Defines a social link entry with `platform` (string key), `href` (URL), and optional `label` (for accessibility)
+- **`SocialIconRowProps`** — Component props accepting `className`, `links` array, and a `variant` for button styling
+
+### Functions
+- **`renderSocialIcon(platform)`** — Maps a platform string to its corresponding icon component. Supports: `github`, `twitter`/`x`, `reddit`, `linkedin`, `luma`, `whatsapp`, `website`/`web`/`url`, `slack`, `discord`, `telegram`, `youtube`/`yt`, `instagram`/`ig`, `facebook`/`fb`. Falls back to `GlobeIcon` for unknown platforms.
+- **`SocialIconRow`** — Main exported component rendering a flex row of icon buttons, each wrapped in an accessible anchor tag.
+
+### Defaults
+- `defaultLinks` — Pre-configured links for GitHub, LinkedIn, and Facebook (Flamingo's primary social channels)
+- `variant` defaults to `'outline'`
 
 ## Usage Example
 
 ```typescript
-import { SocialIconRow } from './social-icon-row';
-
-// Using default Flamingo social links
-function Footer() {
-  return <SocialIconRow variant="ghost" className="max-w-sm mx-auto" />;
-}
-
-// Using custom social links
-function CustomSocials() {
-  const customLinks = [
-    { platform: 'github', href: 'https://github.com/myorg', label: 'GitHub' },
-    { platform: 'twitter', href: 'https://x.com/myhandle', label: 'Twitter' },
-    { platform: 'discord', href: 'https://discord.gg/myserver', label: 'Discord' }
-  ];
-
-  return (
-    <SocialIconRow 
-      links={customLinks} 
-      variant="flamingo-primary"
-      className="justify-center"
-    />
-  );
-}
-```
-
-The component automatically handles platform name normalization (e.g., 'twitter' and 'x' both render the X logo) and includes proper accessibility attributes. Each icon opens in a new tab with security attributes for external links.
+// Default Flamingo social links
+<SocialIconRow />
+
+// Custom links with accent variant
+<SocialIconRow
+  variant="accent"
+  links={[
+    { platform: 'github', href: 'https://github.com/your-org', label: 'GitHub' },
+    { platform: 'slack', href: 'https://join.slack.com/...', label: 'Slack' },
+    { platform: 'youtube', href: 'https://youtube.com/@flamingo', label: 'YouTube' },
+  ]}
+  className="mt-4"
+/>
+
+// Transparent variant for dark backgrounds
+<SocialIconRow
+  variant="transparent"
+  links={[
+    { platform: 'linkedin', href: 'https://linkedin.com/company/flamingo.run' },
+    { platform: 'twitter', href: 'https://x.com/flamingo' },
+  ]}
+/>
+```