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

package/src/components/features/.og-editor-preview.md

@@ -1,43 +1,47 @@
-<!-- source-hash: 08ec4f842d84b7970d3f7a6fb899875b -->
-A unified React component for editing SEO metadata and Open Graph data with live preview functionality. This component provides a consistent interface for managing meta titles, descriptions, keywords, and OG images across different content types.
+<!-- source-hash: 7e8d4cbbf42c408ee48d1318fbf9c4e3 -->
+Unified SEO & Open Graph editor component that combines meta fields (title, description, keywords), OG image upload, and a live preview into a single reusable panel. Designed for content editors across blog posts, case studies, and product releases.
 
 ## Key Components
 
-- **OGEditorPreview** - Main component that renders the complete SEO/OG editing interface
-- **OGEditorPreviewProps** - TypeScript interface defining all required props including SEO fields, auto-populate sources, change handlers, and render prop components
-- Responsive grid layout with form inputs for SEO metadata
-- Integration points for custom OG image upload and preview components
+### `OGEditorPreview`
+Main exported component that renders a card-style panel with:
+- **SEO Title + Keywords** — side-by-side `Input` fields (responsive grid)
+- **SEO Description + OG Image** — `Textarea` paired with an injected upload widget
+- **OG Preview** — rendered below a divider via the `OGPreviewComponent` slot
+
+### `OGEditorPreviewProps`
+Full interface defining:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `seoTitle` / `seoDescription` / `seoKeywords` | `string` | Controlled SEO field values |
+| `ogImageUrl` | `string` | Current OG image URL |
+| `title` / `summary` / `featuredImage` | `string` | Auto-populate sources from parent content |
+| `categories` | `Array<{name, slug}>` | Optional category metadata |
+| `OGImageUploadComponent` | `React.ReactNode` | Upload widget injected by parent |
+| `OGPreviewComponent` | `React.ReactNode` | Preview widget injected by parent |
+| `disabled` | `boolean` | Disables all inputs |
 
 ## Usage Example
 
 ```typescript
-import { OGEditorPreview } from './components/og-editor-preview';
-import { OGImageUpload } from './components/og-image-upload';
-import { OGPreviewCard } from './components/og-preview-card';
-
-function BlogEditor() {
-  const [seoData, setSeoData] = useState({
-    title: '',
-    description: '',
-    keywords: ''
-  });
-
-  return (
-    <OGEditorPreview
-      seoTitle={seoData.title}
-      seoDescription={seoData.description}
-      seoKeywords={seoData.keywords}
-      ogImageUrl=""
-      title="Blog Post Title"
-      summary="Auto-populated summary"
-      featuredImage=""
-      onSeoTitleChange={(title) => setSeoData(prev => ({ ...prev, title }))}
-      onSeoDescriptionChange={(description) => setSeoData(prev => ({ ...prev, description }))}
-      onSeoKeywordsChange={(keywords) => setSeoData(prev => ({ ...prev, keywords }))}
-      onOgImageUrlChange={(url) => console.log('OG image changed:', url)}
-      OGImageUploadComponent={<OGImageUpload />}
-      OGPreviewComponent={<OGPreviewCard />}
-    />
-  );
-}
-```
+import { OGEditorPreview } from './og-editor-preview';
+
+<OGEditorPreview
+  seoTitle={post.seoTitle}
+  seoDescription={post.seoDescription}
+  seoKeywords={post.seoKeywords}
+  ogImageUrl={post.ogImageUrl}
+  title={post.title}
+  summary={post.summary}
+  featuredImage={post.featuredImage}
+  onSeoTitleChange={(val) => updateField('seoTitle', val)}
+  onSeoDescriptionChange={(val) => updateField('seoDescription', val)}
+  onSeoKeywordsChange={(val) => updateField('seoKeywords', val)}
+  onOgImageUrlChange={(val) => updateField('ogImageUrl', val)}
+  OGImageUploadComponent={<OGImageUploader postId={post.id} />}
+  OGPreviewComponent={<OGPreview title={post.seoTitle} description={post.seoDescription} image={post.ogImageUrl} />}
+/>
+```
+
+> Upload and preview widgets are passed as render props (`React.ReactNode`), keeping this component decoupled from specific upload or preview implementations.

package/src/components/features/.parallax-image-showcase.md

@@ -1,47 +1,54 @@
-<!-- source-hash: 5ea87f0b89bc2824f1f4d66b74b70a08 -->
-An interactive React component that creates animated image showcases with parallax effects, supporting three distinct layouts with scroll and mouse-based movement animations.
+<!-- source-hash: 95c8b5bc96c688ed1c4897e169dbdcc0 -->
+A React component that renders up to three images with scroll-based and mouse-tracking parallax animations using Framer Motion, supporting three distinct layout modes.
 
 ## Key Components
 
-- **ParallaxImageShowcase**: Main component with three layout modes:
-  - `non-boxed`: Stacked images with z-index layering and complex positioning
-  - `boxed`: Clean two-row grid with logo support and image overlaps
-  - `grid`: Simple responsive three-column grid layout
-- **Animation System**: Combines scroll-based and global mouse tracking using Framer Motion
-- **Responsive Design**: Adaptive layouts with mobile-friendly breakpoints
+### `ParallaxImageShowcaseProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `images` | `array` | Up to 3 images with `src`, `alt`, and `position` (`left`, `center`, `right`) |
+| `layout` | `'non-boxed' \| 'boxed' \| 'grid'` | Visual arrangement mode (default: `'non-boxed'`) |
+| `intensity` | `number` | Animation strength multiplier (default: `1`; range: `0.1`–`10`) |
+| `shadow` | `boolean` | Applies drop shadow to images (grid layout only) |
+| `logoElement` | `ReactNode` | Custom logo rendered above images in boxed layout |
+| `className` | `string` | Additional Tailwind classes on the root element |
+
+### Layout Modes
+- **`non-boxed`** — Overlapping layered images with z-index depth, large responsive offsets
+- **`boxed`** — Two-row structure with a logo slot and two overlapping card-style images
+- **`grid`** — Responsive 3-column grid with gentler vertical-only parallax
+
+### Animation System
+- **Scroll**: `useScroll` → `useTransform` drives `x`, `y`, and `rotate` based on page scroll position
+- **Mouse**: Global `mousemove` listener computes cursor offset relative to the component's `DOMRect`, fed into spring-smoothed motion values
+- **Combined**: Scroll and mouse transforms are summed via `useTransform` with array input
 
 ## Usage Example
 
 ```typescript
 import { ParallaxImageShowcase } from './parallax-image-showcase'
 
-// Grid layout with shadows
-<ParallaxImageShowcase
-  images={[
-    { src: '/img1.jpg', alt: 'Screenshot 1', position: 'left' },
-    { src: '/img2.jpg', alt: 'Screenshot 2', position: 'center' },
-    { src: '/img3.jpg', alt: 'Screenshot 3', position: 'right' }
-  ]}
-  layout="grid"
-  intensity={2}
-  shadow={true}
-  className="h-96"
-/>
+const images = [
+  { src: '/screens/dashboard.png', alt: 'Dashboard', position: 'left' as const },
+  { src: '/screens/tickets.png',   alt: 'Tickets',   position: 'center' as const },
+  { src: '/screens/reports.png',   alt: 'Reports',   position: 'right' as const },
+]
 
-// Boxed layout with logo
+// Gentle grid layout with shadows
 <ParallaxImageShowcase
   images={images}
-  layout="boxed"
-  logoElement={<div>My Logo</div>}
+  layout="grid"
   intensity={0.5}
+  shadow
 />
 
-// Non-boxed layered layout
+// Aggressive non-boxed hero section
 <ParallaxImageShowcase
   images={images}
   layout="non-boxed"
-  intensity={1}
+  intensity={3}
+  className="h-[600px]"
 />
 ```
 
-The component features global mouse tracking, smooth spring animations, and configurable intensity levels for different visual effects. All layouts respond to both scroll position and mouse movement for immersive parallax experiences.
+> **Intensity guide:** `0.1` = nearly static · `1` = default · `5` = dramatic · `10` = extreme. Tune per layout — `grid` looks best below `1`, `non-boxed` can handle up to `3–5`.

package/src/components/features/.paths-display.md

@@ -1,51 +1,50 @@
-<!-- source-hash: 7ad75ac8ea63324a0a3900bc15151bcb -->
-A React component for displaying file system paths with copy-to-clipboard functionality, featuring ODS styling and cross-platform path support. Designed for use cases like antivirus exclusions or system configuration paths.
+<!-- source-hash: da445924e21f0d905c4ca341c95ec68c -->
+Displays a list of file/folder paths with optional copy-to-clipboard functionality, styled with ODS design tokens and monospace formatting.
 
 ## Key Components
 
-- **PathsDisplay**: Main component that renders a list of paths with optional copy buttons
-- **PathsDisplayProps**: TypeScript interface defining component props
-- **OPENFRAME_PATHS**: Pre-defined path constants for Windows, macOS, and Linux platforms
-- **getOpenFramePaths**: Utility function to retrieve platform-specific OpenFrame paths
-- **OpenFramePathsPlatform**: Type union for supported platforms
+| Export | Type | Description |
+|--------|------|-------------|
+| `PathsDisplay` | Component | Main component rendering a styled list of paths with optional copy buttons |
+| `PathsDisplayProps` | Interface | Props definition for the `PathsDisplay` component |
+| `OPENFRAME_PATHS` | Constant | Pre-defined path sets for Windows, macOS, and Linux platforms |
+| `getOpenFramePaths` | Function | Returns a mutable array of paths for a given platform key |
+| `OpenFramePathsPlatform` | Type | Union type of `'windows' \| 'darwin' \| 'linux'` |
 
 ## Usage Example
 
 ```typescript
-import { PathsDisplay, getOpenFramePaths } from './paths-display'
-
-// Basic usage with custom paths
-const systemPaths = [
-  'C:\\Program Files\\MyApp\\',
-  'C:\\Users\\%USERNAME%\\AppData\\Local\\MyApp\\'
-]
-
-function PathsList() {
-  const handleCopyPath = (path: string) => {
+import { PathsDisplay, getOpenFramePaths } from '@flamingo/ui-kit/components/features'
+
+// Basic usage with antivirus exclusion paths
+<PathsDisplay
+  paths={getOpenFramePaths('windows')}
+  title="Antivirus Exclusions"
+  description="Add these folders to your antivirus exclusions list"
+  onCopyPath={(path) => {
     navigator.clipboard.writeText(path)
-    toast({ title: 'Copied!', description: 'Path copied to clipboard' })
-  }
-
-  return (
-    <PathsDisplay
-      paths={systemPaths}
-      title="Antivirus Exclusions"
-      description="Add these paths to your antivirus whitelist"
-      onCopyPath={handleCopyPath}
-      showCopyButtons={true}
-    />
-  )
-}
-
-// Using pre-defined OpenFrame paths
-function OpenFramePaths() {
-  const windowsPaths = getOpenFramePaths('windows')
-  
-  return (
-    <PathsDisplay
-      paths={windowsPaths}
-      title="OpenFrame Installation Paths"
-    />
-  )
-}
-```
+    toast({ title: 'Copied', description: 'Path copied to clipboard' })
+  }}
+/>
+
+// Display-only, no copy buttons
+<PathsDisplay
+  paths={getOpenFramePaths('linux')}
+  title="Linux Agent Paths"
+  showCopyButtons={false}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `paths` | `string[]` | — | Array of paths to display |
+| `onCopyPath` | `(path: string) => void` | — | Callback triggered on copy button click |
+| `title` | `string` | — | Optional heading above the list |
+| `description` | `string` | — | Optional subtext below the title |
+| `showCopyButtons` | `boolean` | `true` | Toggle copy button visibility |
+| `copyIconSize` | `string` | `'w-5 h-5'` | Tailwind size classes for the copy icon |
+| `className` | `string` | — | Additional CSS classes for the container |
+
+> **Note:** The component renders `null` when `paths` is empty or undefined. Copy buttons only render when both `showCopyButtons` is `true` **and** `onCopyPath` is provided.

package/src/components/features/.platform-badge.md

@@ -1,50 +1,51 @@
-<!-- source-hash: 8fc07a96a287d7d30046a7e6b1251b68 -->
-A React component that renders platform-specific badges with branded icons, colors, and labels for Flamingo Stack platforms.
+<!-- source-hash: 8742c38ee7680d3664638dd468a8ed67 -->
+A client-side React component that renders a styled badge identifying the source platform of content, with platform-specific icons, colors, and sizing options.
 
 ## Key Components
 
-- **PlatformBadge** - Main component that displays a platform badge with icon and optional label
-- **PlatformIcon** - Internal component that renders platform-specific icons based on platform name
-- **sizeClasses** - Configuration object defining size variants (xs, sm, md) for container, icon, and text
-- **platformColors** - Color scheme mapping for each platform (background, border, text colors)
-- **PlatformBadgeProps** - TypeScript interface defining component props including platform data, size, and display options
+- **`PlatformBadge`** — Main exported component that renders a rounded pill badge with an icon and optional label
+- **`PlatformIcon`** — Internal component that resolves the correct logo/icon for a given platform ID
+- **`sizeClasses`** — Size variant map (`xs`, `sm`, `md`) controlling container padding, icon dimensions, and text size
+- **`platformColors`** — Color theme map per platform, defining background, border, and text Tailwind classes
+
+### Supported Platforms
+
+| Platform ID | Color |
+|---|---|
+| `openmsp` | Yellow `#FFC008` |
+| `flamingo` / `flamingo-teaser` | Pink `#FF006E` |
+| `openframe` | Cyan `#00D9D9` |
+| `tmcg` | Magenta `#F357BB` |
+| `company-hub` | Red `#f36666` |
+| `marketing-hub` | Magenta `#F357BB` |
+| `product-hub` | Green `#5EA62E` |
+| `revenue-hub` | Yellow `#FFC008` |
+| `people-hub` | Teal `#5EFAF0` |
+| `universal` (fallback) | Gray `#6B7280` |
 
 ## Usage Example
 
 ```typescript
-import { PlatformBadge } from './components/ui/platform-badge';
-
-// Basic usage with platform object
-<PlatformBadge 
-  platform={{
-    id: "1",
-    name: "flamingo",
-    display_name: "Flamingo"
-  }}
-/>
+import { PlatformBadge } from './platform-badge';
 
-// Different sizes and configurations
-<PlatformBadge 
-  platform={{
-    id: "2", 
-    name: "openframe",
-    display_name: "OpenFrame"
-  }}
-  size="md"
+// Basic usage with label
+<PlatformBadge
+  platform={{ id: '1', name: 'flamingo', display_name: 'Flamingo' }}
+  size="sm"
   showLabel={true}
-  className="custom-styles"
 />
 
-// Icon only (no label)
-<PlatformBadge 
-  platform={{
-    id: "3",
-    name: "openmsp", 
-    display_name: "OpenMSP"
-  }}
-  size="xs"
+// Icon-only, larger size
+<PlatformBadge
+  platform={{ id: '2', name: 'openframe', display_name: 'OpenFrame' }}
+  size="md"
   showLabel={false}
 />
-```
 
-The component supports platforms like Flamingo, OpenMSP, OpenFrame, Admin Hub, and TMCG with their respective brand colors and icons. It gracefully handles unknown platforms with a generic globe icon and gray color scheme.
+// With custom class override
+<PlatformBadge
+  platform={{ id: '3', name: 'openmsp', display_name: 'OpenMSP' }}
+  size="xs"
+  className="opacity-75"
+/>
+```

package/src/components/features/.platform-filter.md

@@ -1,38 +1,45 @@
-<!-- source-hash: 03180f80130a11561f970ec5330ba8be -->
-A React component that renders a set of filter buttons for selecting different platforms, with support for icons and customizable styling.
+<!-- source-hash: aa1e11dd3e0b9d6a8141611784c7d212 -->
+A reusable React filter component that renders a row of platform-selection buttons, including an "All Platforms" option, with optional platform icons.
 
 ## Key Components
 
-- **PlatformFilterComponentProps** - Interface defining component props including platform selection state, change handler, and styling options
-- **PlatformFilterComponent** - Main functional component that renders platform filter buttons with optional icons
-- **getSmallPlatformIcon** - Utility function import for retrieving platform-specific icons
+### `PlatformFilterComponent`
+The primary export — a client-side React component that maps a `PlatformConfig[]` array into toggle buttons, highlighting the currently selected platform using the `"accent"` variant.
+
+### `PlatformFilterComponentProps`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `selectedPlatform` | `string` | — | Currently active platform value (use `'all'` for the global option) |
+| `onPlatformChange` | `(platform: string) => void` | — | Callback fired when a platform button is clicked |
+| `platforms` | `PlatformConfig[]` | `[]` | List of platform options to render |
+| `className` | `string` | `''` | Additional CSS classes for the wrapper `div` |
+| `showIcons` | `boolean` | `true` | Whether to render small platform icons via `getSmallPlatformIcon` |
+| `size` | `'small-legacy' \| 'default'` | `'small-legacy'` | Button size variant |
 
 ## Usage Example
 
 ```typescript
 import { PlatformFilterComponent } from './platform-filter';
-import type { PlatformConfig } from '../types/platform';
+import type { PlatformConfig } from '../../types/platform';
 
 const platforms: PlatformConfig[] = [
-  { value: 'ios', label: 'iOS' },
-  { value: 'android', label: 'Android' },
-  { value: 'web', label: 'Web' }
+  { value: 'connectwise', label: 'ConnectWise' },
+  { value: 'halo',        label: 'HaloPSA'    },
 ];
 
-function AppFilters() {
-  const [selectedPlatform, setSelectedPlatform] = useState('all');
+function TicketFilters() {
+  const [platform, setPlatform] = React.useState('all');
 
   return (
     <PlatformFilterComponent
-      selectedPlatform={selectedPlatform}
-      onPlatformChange={setSelectedPlatform}
+      selectedPlatform={platform}
+      onPlatformChange={setPlatform}
       platforms={platforms}
       showIcons={true}
-      size="default"
-      className="my-4"
     />
   );
 }
 ```
 
-The component renders an "All Platforms" button followed by individual platform buttons, with the selected platform highlighted using the primary variant. Icons are displayed by default and can be toggled via the `showIcons` prop.
+> **Note:** Platform icons are resolved via the shared `getSmallPlatformIcon` utility in `platform-config`. To add a new platform, extend the `PlatformConfig` type and register its icon there rather than modifying this component.

package/src/components/features/.policy-configuration-panel.md

@@ -1,66 +1,58 @@
-<!-- source-hash: c4760001ccc6ea7295fa325e79556bf6 -->
-A comprehensive React component that renders an expandable permission policy configuration interface with hierarchical categories and granular policy controls.
+<!-- source-hash: bd515872f4cb1c49add8d17631e037c5 -->
+A React panel component for displaying and editing permission policies grouped by category, supporting both view and edit modes with animated expand/collapse behavior.
 
 ## Key Components
 
-**PolicyConfigurationPanel**: Main container component that renders a list of expandable permission categories with global and individual policy settings.
-
-**CategorySection**: Individual category component with animated expansion/collapse, global permission dropdown, and policy list management.
-
-**PolicyRow**: Individual policy item component displaying tool icon, policy details (name and command pattern), and permission level dropdown.
-
-**useAnimatedHeight**: Custom hook providing smooth height animations for expanding/collapsing category sections.
-
-**Helper Functions**:
-- `getApprovalLevelLabel()`: Maps approval level values to user-friendly labels
-- `approvalLevelOptions`: Predefined approval level configuration
+| Export / Internal | Type | Description |
+|---|---|---|
+| `PolicyConfigurationPanel` | Component (exported) | Root panel rendering all permission categories |
+| `CategorySection` | Internal component | Collapsible category with global permission dropdown |
+| `PolicyRow` | Internal component | Single policy entry with approval level selector |
+| `useAnimatedHeight` | Custom hook | Smooth height animation for expand/collapse transitions |
+| `approvalLevelOptions` | Constant | Available levels: `ALLOW`, `ASK_USER`, `ASK_TECHNICIAN`, `DENY` |
+| `getApprovalLevelLabel` | Utility fn | Resolves `ApprovalLevel` enum to display string |
 
 ## Usage Example
 
 ```typescript
 import { PolicyConfigurationPanel } from './policy-configuration-panel'
-
-function PermissionsSettings() {
-  const [categories, setCategories] = useState<PermissionCategory[]>([
-    {
-      id: 'network',
-      name: 'Network Tools',
-      icon: '🌐',
-      configurationsCount: 5,
-      isExpanded: false,
-      globalPermission: 'ASK_USER',
-      policies: [
-        {
-          id: 'ping',
-          name: 'Ping Command',
-          toolName: 'ping',
-          commandPattern: 'ping -c 4 {host}',
-          approvalLevel: 'ALLOW'
-        }
-      ]
-    }
-  ])
-
-  return (
-    <PolicyConfigurationPanel
-      categories={categories}
-      editMode={true}
-      onCategoryToggle={(categoryId) => {
-        setCategories(prev => prev.map(cat => 
-          cat.id === categoryId 
-            ? { ...cat, isExpanded: !cat.isExpanded }
-            : cat
-        ))
-      }}
-      onGlobalPermissionChange={(categoryId, level) => {
-        // Update global permission logic
-      }}
-      onPolicyPermissionChange={(categoryId, policyId, level) => {
-        // Update individual policy logic
-      }}
-    />
-  )
-}
+import { PermissionCategory, ApprovalLevel } from '../../types/permissions'
+
+const categories: PermissionCategory[] = [
+  {
+    id: 'network',
+    name: 'Network',
+    icon: <NetworkIcon />,
+    configurationsCount: 3,
+    isExpanded: false,
+    globalPermission: 'ALLOW',
+    policies: [
+      {
+        id: 'ping',
+        name: 'Ping Host',
+        commandPattern: 'ping *',
+        toolName: 'network',
+        approvalLevel: 'ALLOW',
+      },
+    ],
+  },
+]
+
+<PolicyConfigurationPanel
+  categories={categories}
+  editMode={true}
+  onCategoryToggle={(categoryId) => toggleCategory(categoryId)}
+  onGlobalPermissionChange={(categoryId, level) => setGlobal(categoryId, level)}
+  onPolicyPermissionChange={(categoryId, policyId, level) =>
+    updatePolicy(categoryId, policyId, level)
+  }
+  className="my-4"
+/>
 ```
 
-The component features smooth animations, responsive design, and comprehensive permission management with support for both category-level global permissions and individual policy-level controls.
+## Behavior Notes
+
+- In **edit mode**, dropdowns allow selecting approval levels per policy or globally per category
+- In **view mode**, current levels are rendered as static text
+- `useAnimatedHeight` uses `scrollHeight` measurement + CSS transitions for smooth accordion animation
+- Category header clicks and the chevron button both toggle expansion; dropdown clicks use `stopPropagation` to prevent conflicts

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

@@ -1,50 +1,47 @@
-<!-- source-hash: 274a22be0c31fdc49ccdc0daf827abd4 -->
-A React component that renders authentication provider buttons with integrated loading states and consistent styling for OAuth sign-in flows.
+<!-- source-hash: 18cb2f4cc768f6f9efb9b720bfbd1714 -->
+A reusable OAuth provider sign-in button component that handles loading states, click propagation, and renders the appropriate provider icon and label.
 
 ## Key Components
 
-**ProviderButton Component**
-- `ProviderButtonProps` - Interface defining provider type, click handler, and optional disabled/loading states
-- `PROVIDER_CONFIG` - Configuration object mapping provider names to display text and icons
-- Supports Microsoft, Google, Slack, and GitHub authentication providers
+### `ProviderButtonProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `provider` | `'microsoft' \| 'google' \| 'slack' \| 'github'` | OAuth provider to render |
+| `onClick` | `() => Promise<void> \| void` | Sign-in handler (sync or async) |
+| `disabled` | `boolean` | Disables the button (default: `false`) |
+| `loading` | `boolean` | External loading state override (default: `false`) |
 
-**Key Features**
-- Dual loading state management (internal and external)
-- Event bubbling prevention for modal contexts
-- Consistent styling with hover states and accessibility labels
-- Error handling with console logging
+### `PROVIDER_CONFIG`
+Static map linking each provider key to its display name and icon component.
+
+### `ProviderButton`
+Main exported component. Manages an internal loading state that activates during async `onClick` execution, falling back gracefully when an external `loading` prop is passed. Stops click propagation to prevent accidental modal/backdrop dismissals.
 
 ## Usage Example
 
 ```typescript
 import { ProviderButton } from './provider-button';
 
-function SignInModal() {
-  const [loading, setLoading] = useState(false);
+async function handleMicrosoftSignIn() {
+  await signIn('microsoft');
+}
+
+// Basic usage
+<ProviderButton provider="microsoft" onClick={handleMicrosoftSignIn} />
 
-  const handleGoogleSignIn = async () => {
+// With external loading control
+const [loading, setLoading] = useState(false);
+
+<ProviderButton
+  provider="google"
+  onClick={async () => {
     setLoading(true);
-    try {
-      await signInWithGoogle();
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return (
-    <div className="space-y-3">
-      <ProviderButton 
-        provider="google" 
-        onClick={handleGoogleSignIn}
-        loading={loading}
-      />
-      <ProviderButton 
-        provider="github" 
-        onClick={() => signInWithGitHub()}
-      />
-    </div>
-  );
-}
+    await signIn('google');
+    setLoading(false);
+  }}
+  loading={loading}
+  disabled={loading}
+/>
 ```
 
-The component automatically handles loading states, displays appropriate icons, and provides consistent UX patterns for authentication flows across different OAuth providers.
+> **Note:** When `loading` is provided externally, internal loading state management is skipped to avoid state conflicts.