@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482-snapshot.20260725230219

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

@@ -1,50 +1,67 @@
-<!-- source-hash: da445924e21f0d905c4ca341c95ec68c -->
-Displays a list of file/folder paths with optional copy-to-clipboard functionality, styled with ODS design tokens and monospace formatting.
+<!-- source-hash: 96a81588a478ba85d3b042d42c4563c6 -->
+Renders a styled, copy-enabled list of file/folder paths, and exports pre-defined OpenFrame installation paths and doctor commands for Windows, macOS, and Linux.
 
 ## Key Components
 
-| 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'` |
+### `PathsDisplay` (Component)
+The primary export. Renders paths in a bordered, monospace list with optional title, description, leading icon per row, and per-path copy buttons.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `paths` | `string[]` | — | Paths to display |
+| `onCopyPath` | `(path: string) => void` | — | Copy button callback |
+| `title` | `string` | — | Heading above the list |
+| `description` | `string` | — | Subheading below title |
+| `showCopyButtons` | `boolean` | `true` | Show/hide copy buttons |
+| `copyIconSize` | `string` | `'w-6 h-6'` | Tailwind size classes for the copy icon |
+| `leadingIcon` | `React.ReactNode` | — | Icon prepended to each row (e.g. platform logo) |
+| `className` | `string` | — | Extra classes on the container |
+
+Returns `null` when `paths` is empty.
+
+### `OPENFRAME_PATHS`
+Constant record of platform-specific OpenFrame installation paths.
+
+```typescript
+OPENFRAME_PATHS.windows  // C:\Program Files\OpenFrame, etc.
+OPENFRAME_PATHS.darwin   // /Library/LaunchDaemons/..., etc.
+OPENFRAME_PATHS.linux    // /opt/openframe/
+```
+
+### `OPENFRAME_DOCTOR_COMMANDS`
+Per-platform shell commands for diagnosing and repairing the OpenFrame agent.
+
+### Helper Functions
+- **`getOpenFramePaths(platform)`** — returns a mutable copy of `OPENFRAME_PATHS[platform]`
+- **`getOpenFrameDoctorCommand(platform)`** — returns the doctor command string for a platform
+
+### `OpenFramePathsPlatform` (Type)
+`'windows' | 'darwin' | 'linux'`
 
 ## Usage Example
 
 ```typescript
 import { PathsDisplay, getOpenFramePaths } from '@flamingo/ui-kit/components/features'
 
-// Basic usage with antivirus exclusion paths
+// Basic antivirus exclusion list
 <PathsDisplay
   paths={getOpenFramePaths('windows')}
   title="Antivirus Exclusions"
-  description="Add these folders to your antivirus exclusions list"
+  description="Add these folders to your antivirus exclusion list."
   onCopyPath={(path) => {
     navigator.clipboard.writeText(path)
     toast({ title: 'Copied', description: 'Path copied to clipboard' })
   }}
 />
 
-// Display-only, no copy buttons
+// With a platform logo as a leading icon
 <PathsDisplay
   paths={getOpenFramePaths('linux')}
-  title="Linux Agent Paths"
+  leadingIcon={<LinuxIcon className="w-5 h-5" />}
   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-6 h-6'` | Tailwind size classes for the copy icon |
-| `className` | `string` | — | Additional CSS classes for the container |
+## Source
 
-> **Note:** The component renders `null` when `paths` is empty or undefined. Copy buttons only render when both `showCopyButtons` is `true` **and** `onCopyPath` is provided.
+[`paths-display.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/paths-display.tsx)

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

@@ -1,43 +1,48 @@
-<!-- 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.
+<!-- source-hash: 85b7f197fe9ccebbccd12db007ae658a -->
+A client-side React component that renders a styled badge for various Flamingo platform identifiers, combining a platform-specific icon with optional display label and color-coded styling.
 
 ## Key Components
 
-- **`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
+### `PlatformBadge` (exported)
+Main component accepting a `platform` object, `size`, `showLabel`, and `className` props. Returns `null` if no platform is provided.
 
-### Supported Platforms
+### `PlatformIcon` (internal)
+Maps platform IDs to their corresponding logo components (`FlamingoLogo`, `OpenmspLogo`, `OpenFrameLogo`, `MiamiCyberGangLogoFaceOnly`) or falls back to a `Globe` icon from Lucide.
+
+### `platformColors` (internal)
+Color map keyed by platform name, providing Tailwind-compatible `bg`, `border`, and `text` classes for each platform's brand color.
+
+### `sizeClasses` (internal)
+Three-tier size configuration (`xs`, `sm`, `md`) defining container padding, icon dimensions, and text sizing.
+
+## Supported Platforms
 
 | Platform ID | Color |
 |---|---|
-| `openmsp` | Yellow `#FFC008` |
 | `flamingo` / `flamingo-teaser` | Pink `#FF006E` |
 | `openframe` | Cyan `#00D9D9` |
-| `tmcg` | Magenta `#F357BB` |
+| `openmsp` | Amber `#FFC008` |
+| `tmcg` | Pink `#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` |
+| `universal` | Gray (fallback) |
 
 ## Usage Example
 
 ```typescript
 import { PlatformBadge } from './platform-badge';
 
-// Basic usage with label
+// Basic usage
 <PlatformBadge
-  platform={{ id: '1', name: 'flamingo', display_name: 'Flamingo' }}
+  platform={{ id: '1', name: 'openframe', display_name: 'OpenFrame' }}
   size="sm"
   showLabel={true}
 />
 
-// Icon-only, larger size
+// Icon-only, large
 <PlatformBadge
-  platform={{ id: '2', name: 'openframe', display_name: 'OpenFrame' }}
+  platform={{ id: '2', name: 'flamingo', display_name: 'Flamingo' }}
   size="md"
   showLabel={false}
 />
@@ -48,4 +53,8 @@ import { PlatformBadge } from './platform-badge';
   size="xs"
   className="opacity-75"
 />
-```
+```
+
+## Source
+
+[`platform-badge.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/platform-badge.tsx)

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

@@ -1,16 +1,13 @@
-<!-- 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.
+<!-- source-hash: 07366ff5d32cd4e46e8c63c7d6ad677c -->
+A React panel component for managing permission policies grouped by category, supporting per-policy and bulk approval level configuration with expand/collapse animations and responsive layout.
 
 ## Key Components
 
-| 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 |
+- **`PolicyConfigurationPanel`** — Main exported component. Renders grouped permission categories with collapsible policy lists. Manages expand/collapse state and bulk approval levels internally.
+- **`CategorySection`** — Collapsible category header with an optional bulk approval dropdown and a list of `PolicyRow` items. Uses `useCollapsible` for animated expand/collapse.
+- **`PolicyRow`** — Renders a single permission policy with its tool icon, name, command pattern, and an approval level selector.
+- **`ApprovalLevelDropdown`** — Reusable dropdown for selecting an `ApprovalLevel` (`ALLOW`, `ASK_USER`, `ASK_TECHNICIAN`, `DENY`). Supports an optional "Clear Global Permission" option for category-level bulk selectors.
+- **`approvalLevelLabels`** — Display label map for each `ApprovalLevel` value.
 
 ## Usage Example
 
@@ -21,38 +18,43 @@ import { PermissionCategory, ApprovalLevel } from '../../types/permissions'
 const categories: PermissionCategory[] = [
   {
     id: 'network',
-    name: 'Network',
-    icon: <NetworkIcon />,
-    configurationsCount: 3,
-    isExpanded: false,
-    globalPermission: 'ALLOW',
+    name: 'Network Tools',
     policies: [
       {
         id: 'ping',
-        name: 'Ping Host',
+        name: 'Ping',
+        toolName: 'ping',
         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)
+function SettingsPage() {
+  const handlePolicyChange = (
+    categoryId: string,
+    policyId: string,
+    level: ApprovalLevel
+  ) => {
+    console.log('Policy changed:', { categoryId, policyId, level })
   }
-  className="my-4"
-/>
+
+  const handleCategoryChange = (categoryId: string, level: ApprovalLevel) => {
+    console.log('Bulk category change:', { categoryId, level })
+  }
+
+  return (
+    <PolicyConfigurationPanel
+      categories={categories}
+      editMode={true}
+      onPolicyPermissionChange={handlePolicyChange}
+      onCategoryPermissionChange={handleCategoryChange}
+    />
+  )
+}
 ```
 
-## Behavior Notes
+> **Note:** Bulk approval selections reset automatically when `editMode` toggles. Expand/collapse state is preserved across data refreshes since it lives inside the panel.
 
-- 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
+**Source:** [`policy-configuration-panel.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/policy-configuration-panel.tsx)

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

@@ -1,47 +1,56 @@
-<!-- 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.
+<!-- source-hash: 64d6da94944d72c433e84a70e186394d -->
+Reusable OAuth provider sign-in button component that handles loading state, click propagation, and provider-specific branding for Microsoft, Google, Slack, and GitHub authentication flows.
 
 ## Key Components
 
 ### `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`) |
+| `provider` | `'microsoft' \| 'google' \| 'slack' \| 'github'` | Determines icon and display label |
+| `onClick` | `() => Promise<void> \| void` | Auth handler; supports async |
+| `disabled` | `boolean` | Disables interaction (default: `false`) |
 | `loading` | `boolean` | External loading state override (default: `false`) |
 
 ### `PROVIDER_CONFIG`
-Static map linking each provider key to its display name and icon component.
+Static map linking each provider key to its display name and icon component. Extend this object to add new providers.
 
 ### `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.
+Client component that manages an internal loading state, falling back to it only when no external `loading` prop is provided. Prevents click bubbling to avoid triggering modal backdrops or parent handlers.
 
 ## Usage Example
 
 ```typescript
-import { ProviderButton } from './provider-button';
-
-async function handleMicrosoftSignIn() {
-  await signIn('microsoft');
+import { ProviderButton } from '@/components/auth/provider-button';
+
+export function LoginForm() {
+  const handleMicrosoftLogin = async () => {
+    await signIn('microsoft');
+  };
+
+  return (
+    <ProviderButton
+      provider="microsoft"
+      onClick={handleMicrosoftLogin}
+    />
+  );
 }
+```
 
-// Basic usage
-<ProviderButton provider="microsoft" onClick={handleMicrosoftSignIn} />
+With external loading control:
 
-// With external loading control
-const [loading, setLoading] = useState(false);
+```typescript
+const [isLoading, setIsLoading] = useState(false);
 
 <ProviderButton
   provider="google"
   onClick={async () => {
-    setLoading(true);
+    setIsLoading(true);
     await signIn('google');
-    setLoading(false);
+    setIsLoading(false);
   }}
-  loading={loading}
-  disabled={loading}
+  loading={isLoading}
+  disabled={isLoading}
 />
 ```
 
-> **Note:** When `loading` is provided externally, internal loading state management is skipped to avoid state conflicts.
+> **Note:** When `loading` is passed externally, the component skips internal state management to avoid double-toggling.

package/src/components/features/.push-button-selector.md

@@ -1,29 +1,35 @@
-<!-- source-hash: 07ba5865678ee01e8867762d1e641327 -->
-A reusable React selector component that renders options as push-button cards with checkbox indicators, supporting single/multi-select, grouped sections, loading skeletons, and error states.
+<!-- source-hash: 1b470f4e084b6cb0c7cd286c460838ca -->
+A client-side React component that renders a list of toggleable push-button options with support for single/multi-select, section grouping, disabled states with tooltips, loading skeletons, and error handling.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `PushButtonSelector` | Component | Main selector rendered as interactive card list |
-| `SelectableOption` | Interface | Shape of each selectable item (id, name, icon, section, etc.) |
-| `SectionDefinition` | Interface | Defines a named group to bucket options under |
-| `PushButtonSelectorSkeleton` | Internal | Animated skeleton shown during `isLoading` |
-| `PushButtonSelectorError` | Internal | Error panel using ODS error tokens |
+### Exported Interfaces
 
-## Key Props
+| Interface | Purpose |
+|---|---|
+| `SelectableOption` | Defines an individual selectable item with `id`, `name`, optional `displayName`, `icon`, `color`, `disabled`, `disabledReason`, and `section` fields |
+| `SectionDefinition` | Defines a labeled group for organizing options with `id`, `label`, optional `icon`, and `description` |
+
+### Exported Component
+
+**`PushButtonSelector`** — Main component accepting `PushButtonSelectorProps`:
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `options` | `SelectableOption[]` | — | All available options |
-| `selectedIds` | `string[]` | — | Controlled selected IDs |
-| `onSelectionChange` | `(ids: string[]) => void` | — | Fires on toggle |
+|---|---|---|---|
+| `options` | `SelectableOption[]` | — | Items to display |
+| `selectedIds` | `string[]` | — | Currently selected IDs |
+| `onSelectionChange` | `(ids: string[]) => void` | — | Callback on toggle |
 | `multiSelect` | `boolean` | `true` | Allow multiple selections |
-| `sections` | `SectionDefinition[]` | — | Groups options under labeled headers |
-| `selectionSummary` | `boolean` | `false` | Shows badge summary of selected items |
-| `optional` | `boolean` | `false` | Suppresses empty-state warning |
-| `isLoading` | `boolean` | `false` | Renders skeleton UI |
-| `error` | `string \| null` | `null` | Renders error panel |
+| `sections` | `SectionDefinition[]` | — | Optional grouping definitions |
+| `selectionSummary` | `boolean` | `false` | Show badge summary of selections |
+| `optional` | `boolean` | `false` | Suppress empty-selection warning |
+| `isLoading` | `boolean` | `false` | Show skeleton placeholders |
+| `error` | `string \| null` | `null` | Show error state |
+
+### Internal Components
+
+- **`PushButtonSelectorSkeleton`** — Animated placeholder cards during loading
+- **`PushButtonSelectorError`** — Error banner using ODS error tokens
 
 ## Usage Example
 
@@ -31,32 +37,24 @@ A reusable React selector component that renders options as push-button cards wi
 import { PushButtonSelector, SelectableOption, SectionDefinition } from './push-button-selector';
 
 const platforms: SelectableOption[] = [
-  { id: 'uuid-1', name: 'connectwise', displayName: 'ConnectWise', description: 'PSA platform', section: 'psa' },
-  { id: 'uuid-2', name: 'halo',        displayName: 'HaloPSA',     description: 'PSA platform', section: 'psa' },
-  { id: 'uuid-3', name: 'ninja',       displayName: 'NinjaRMM',    description: 'RMM platform', section: 'rmm' },
+  { id: 'connectwise', name: 'ConnectWise', displayName: 'ConnectWise Manage', description: 'PSA platform' },
+  { id: 'halo', name: 'HaloPSA', disabled: true, disabledReason: 'License required' },
 ];
 
 const sections: SectionDefinition[] = [
-  { id: 'psa', label: 'PSA Tools' },
-  { id: 'rmm', label: 'RMM Tools' },
+  { id: 'psa', label: 'PSA Platforms', description: 'Choose your ticketing system' },
 ];
 
-function IntegrationPicker() {
-  const [selected, setSelected] = React.useState<string[]>([]);
-
-  return (
-    <PushButtonSelector
-      options={platforms}
-      selectedIds={selected}
-      onSelectionChange={setSelected}
-      sections={sections}
-      title="Select Integrations"
-      helpText="Choose the platforms to connect."
-      selectionSummary
-      multiSelect
-    />
-  );
-}
+<PushButtonSelector
+  options={platforms}
+  selectedIds={selected}
+  onSelectionChange={setSelected}
+  multiSelect={false}
+  title="Select Platform"
+  sections={sections}
+  selectionSummary
+  helpText="Only one PSA platform can be active at a time."
+/>
 ```
 
-> **Note:** Invalid `selectedIds` (IDs not present in `options`) are silently filtered once `options` has loaded. A `console.warn` is emitted in `development` mode to aid debugging.
+> **Note:** Disabled options that are already selected remain deselectable. A `disabledReason` surfaces via tooltip on hover using the shared `Tooltip` primitive.

package/src/components/features/.release-media-manager.md

@@ -1,58 +1,65 @@
-<!-- source-hash: 567153c4bee0ea823c8dcb3ad142df21 -->
-A React client component for managing media attachments (images, videos, screenshots, demos) on release entries, supporting file upload, drag-to-reorder, and inline editing.
+<!-- source-hash: c12f9380c042cace30222c9c17600a89 -->
+Manages upload, preview, reordering, and metadata editing of media items (images and videos) associated with a software release.
 
 ## Key Components
 
 ### `ReleaseMediaItem` (interface)
-Represents a single media entry with the following fields:
+Describes a single media entry with the following fields:
 
 | Field | Type | Description |
-|-------|------|-------------|
-| `media_type` | `'image' \| 'video' \| 'screenshot' \| 'demo'` | Category of media |
-| `media_url` | `string` | Public URL after upload |
+|---|---|---|
+| `media_type` | `'image' \| 'video' \| 'screenshot' \| 'demo'` | Category of the media |
+| `media_url` | `string` | Resolved URL after upload |
 | `title` | `string?` | Optional display title |
 | `description` | `string?` | Optional description |
-| `display_order` | `number?` | Sort position in gallery |
-| `_file` | `File?` | Temporary pre-upload file reference |
+| `display_order` | `number?` | Sort position in the gallery |
+| `_file` | `File?` | Temporary local file before upload |
 | `_uploading` | `boolean?` | Upload in-progress flag |
 
 ### `ReleaseMediaManager` (component)
+The primary exported component. Renders:
+- **Upload zone** — dashed drop area with a file picker (images and videos, max 50 MB)
+- **Media grid** — 2-column responsive gallery with drag-and-drop reordering
+- **Per-item controls** — inline type selector (`Select`), title input, delete button, and media preview via `Image` (photos) or `Video` (MuxPlayer/HLS)
 
-**Props:**
+### `ReleaseMediaManagerProps`
 
 | Prop | Type | Description |
-|------|------|-------------|
-| `media` | `ReleaseMediaItem[]` | Controlled media list |
-| `onChange` | `(media: ReleaseMediaItem[]) => void` | Called on any list mutation |
-| `onUpload` | `(file, mediaType) => Promise<string>` | Handles actual file upload, returns URL |
-| `className` | `string?` | Optional wrapper class |
-
-**Internal behaviors:**
-- `handleFileSelect` — detects file MIME type, auto-assigns `media_type`, triggers `onUpload`, rolls back on failure
-- `removeMedia` — removes item by index
-- `updateMedia` — updates a single field on an existing item
-- `handleDragStart` / `handleDragOver` / `handleDrop` — native HTML5 drag-and-drop reordering, updates `display_order` on drop
+|---|---|---|
+| `media` | `ReleaseMediaItem[]` | Controlled list of media items |
+| `onChange` | `(media: ReleaseMediaItem[]) => void` | Called on any mutation |
+| `onUpload` | `(file, mediaType) => Promise<string>` | Async upload handler; returns the hosted URL |
+| `className` | `string?` | Additional wrapper class |
 
 ## Usage Example
 
 ```typescript
 import { ReleaseMediaManager, ReleaseMediaItem } from './release-media-manager';
+import { useState } from 'react';
 
-const [media, setMedia] = useState<ReleaseMediaItem[]>([]);
+export function ReleaseForm() {
+  const [media, setMedia] = useState<ReleaseMediaItem[]>([]);
 
-async function uploadToStorage(file: File, mediaType: string): Promise<string> {
-  const formData = new FormData();
-  formData.append('file', file);
-  const res = await fetch('/api/upload', { method: 'POST', body: formData });
-  const { url } = await res.json();
-  return url;
-}
+  const handleUpload = async (
+    file: File,
+    mediaType: 'image' | 'video' | 'screenshot' | 'demo'
+  ): Promise<string> => {
+    const formData = new FormData();
+    formData.append('file', file);
+    formData.append('type', mediaType);
+    const res = await fetch('/api/upload', { method: 'POST', body: formData });
+    const { url } = await res.json();
+    return url;
+  };
 
-<ReleaseMediaManager
-  media={media}
-  onChange={setMedia}
-  onUpload={uploadToStorage}
-/>
+  return (
+    <ReleaseMediaManager
+      media={media}
+      onChange={setMedia}
+      onUpload={handleUpload}
+    />
+  );
+}
 ```
 
-> **Note:** The component is fully controlled — the parent owns the `media` array. Failed uploads automatically roll back to the previous state without manual intervention.
+> **Source:** [`release-media-manager.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/release-media-manager.tsx)

package/src/components/features/.section-selector.md

@@ -1,42 +1,51 @@
-<!-- source-hash: 760f28bd91ca25a2a1341b709f1c96c4 -->
-A client-side navigation component that renders a list of selectable section buttons with support for vertical and wrap layouts, optional badges, icons, descriptions, and active state highlighting.
+<!-- source-hash: b566b7b57ff314adad0d7bab07a8d548 -->
+A client-side React component that renders a group of selectable section buttons, supporting vertical and wrap layouts with optional icons, badges, numbers, and descriptions.
 
 ## Key Components
 
 ### Interfaces
 
 - **`SectionItem`** — Defines a single section entry with `id`, `title`, optional `subtitle`, `description`, `number`, `leftIcon`, `badge`, `screenshots`, and `disabled` flag.
-- **`SectionSelectorProps`** — Configuration for the selector including `sections`, `activeSection`, `onSectionChange` callback, `layout`, `buttonWidth`, `minHeight`, and display toggles.
+- **`SectionSelectorProps`** — Configuration for the `SectionSelector` component, including layout, width, active state, and callback.
 
 ### Components
 
-- **`SectionButton`** *(internal)* — Renders an individual section button. Supports two layout modes:
-  - `vertical` — Displays number prefix, left icon, title, badge, and description stacked.
-  - `wrap` — Displays left icon, title, badge, and subtitle in a compact horizontal card.
-- **`SectionSelector`** *(exported)* — Orchestrates the full selector by mapping `sections` to `SectionButton` instances inside a flex container.
+- **`SectionButton`** *(internal)* — Renders an individual section button using the `Button` and `StatusBadge` primitives. Adapts its internal layout based on the `layout` prop (`vertical` vs `wrap`).
+- **`SectionSelector`** *(exported)* — Orchestrates a list of `SectionButton` components. Manages container layout, button width classes, and delegates click handling via `onSectionChange`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `sections` | `SectionItem[]` | — | List of section items to render |
+| `activeSection` | `string` | — | ID of the currently active section |
+| `onSectionChange` | `(id: string) => void` | — | Callback fired on section click |
+| `layout` | `'vertical' \| 'wrap'` | `'vertical'` | Button arrangement direction |
+| `buttonWidth` | `'auto' \| 'full' \| 'responsive'` | `'auto'` | Width behavior of each button |
+| `showDescription` | `boolean` | `true` | Toggle description text visibility |
 
 ## Usage Example
 
 ```typescript
-import SectionSelector, { SectionItem } from './section-selector'
+import { SectionSelector, SectionItem } from './section-selector'
 
 const sections: SectionItem[] = [
   {
     id: 'overview',
     title: 'Overview',
-    subtitle: 'General information',
-    badge: { text: 'New', colorScheme: 'green' },
+    description: 'High-level summary',
+    number: '01',
+    badge: { text: 'New', colorScheme: 'cyan' },
   },
   {
-    id: 'settings',
-    title: 'Settings',
-    description: 'Configure your preferences',
-    number: '02',
+    id: 'details',
+    title: 'Details',
+    subtitle: 'In-depth configuration',
     disabled: false,
   },
 ]
 
-export default function Page() {
+export function MyPage() {
   const [active, setActive] = React.useState('overview')
 
   return (
@@ -50,4 +59,6 @@ export default function Page() {
     />
   )
 }
-```
+```
+
+**Source:** [`section-selector.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/section-selector.tsx)