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

package/src/components/ui/.dropdown-button.md

@@ -1,45 +1,53 @@
-<!-- source-hash: 755936e5a23162889a0f4b377887a066 -->
-A styled dropdown trigger button that combines a labeled action area with a rotating chevron indicator, opening a `MoreActionsMenu` on click.
+<!-- source-hash: f200d2146a81060f8cc6dc2a88c6bc69 -->
+A button component that renders a labeled trigger with a trailing chevron, opening an `ActionsMenuDropdown` on click. The chevron rotates 180° when the menu is open, and the entire button surface lightens on hover/open state.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `DropdownButton` | Component | Main trigger button that wraps `MoreActionsMenu` |
-| `DropdownButtonProps` | Interface | Props definition for the component |
+### `DropdownButton`
+The primary export. A composite trigger + dropdown built on top of `ActionsMenuDropdown`. Key behaviors:
+- Manages open/closed state internally via `React.useState`
+- Prevents interaction when `disabled` (blocks `onPointerDown` and ignores open-change calls)
+- Chevron animates via `rotate-180` when `open === true`
+- Renders an optional leading `icon` before the label text
+- Supports positioning via `align` (`start | center | end`) and `side` (`top | right | bottom | left`)
 
-### Props
+### `DropdownButtonProps`
+TypeScript interface defining the public API:
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `label` | `string` | — | Button label text |
+|---|---|---|---|
+| `label` | `string` | — | Button text and fallback aria-label |
 | `icon` | `ReactNode` | — | Optional leading icon |
-| `items` | `MoreActionsItem[]` | — | Dropdown menu items |
-| `align` | `'start' \| 'center' \| 'end'` | `'end'` | Menu alignment |
-| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Menu opening side |
-| `disabled` | `boolean` | — | Disables interaction |
-
-## Key Behaviors
-
-- **Single click target** — label and chevron areas are visually separated by a border seam but share one `<button>` element
-- **Open state styles** — background lightens (`ods-bg-hover`) when the menu is open or hovered
-- **Chevron rotation** — animates 180° when the dropdown is open
-- **Disabled guard** — blocks `onOpenChange` and prevents pointer events when `disabled` is set
+| `items` | `ActionsMenuItem[]` | — | Dropdown menu items |
+| `disabled` | `boolean` | — | Disables interaction and dims the button |
+| `align` | `'start' \| 'center' \| 'end'` | `'end'` | Dropdown horizontal alignment |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Dropdown preferred side |
+| `ariaLabel` | `string` | `label` | Overrides the accessible label |
+| `className` | `string` | — | Additional classes on the button root |
 
 ## Usage Example
 
 ```typescript
 import { DropdownButton } from './dropdown-button'
-import { SettingsIcon } from '../icons-v2-generated'
-
-<DropdownButton
-  label="Actions"
-  icon={<SettingsIcon />}
-  align="end"
-  side="bottom"
-  items={[
-    { label: 'Edit', onClick: () => console.log('edit') },
-    { label: 'Delete', onClick: () => console.log('delete'), destructive: true },
-  ]}
-/>
-```
+import { PlusIcon } from '../icons-v2-generated'
+
+const actions = [
+  { label: 'Export CSV', onSelect: () => handleExport('csv') },
+  { label: 'Export PDF', onSelect: () => handleExport('pdf') },
+  { label: 'Delete', onSelect: handleDelete, destructive: true },
+]
+
+export function ToolbarActions() {
+  return (
+    <DropdownButton
+      label="Export"
+      icon={<PlusIcon />}
+      items={actions}
+      align="end"
+      side="bottom"
+    />
+  )
+}
+```
+
+> **Source:** [`dropdown-button.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/dropdown-button.tsx)

package/src/components/ui/.dropdown-menu.md

@@ -1,47 +1,64 @@
-<!-- source-hash: 34ce5c6ddfeca8bdfa20a5f6665b19da -->
-A comprehensive dropdown menu component built on top of Radix UI's dropdown menu primitives, providing a full suite of styled menu components with consistent theming using the OpenFrame Design System (ODS).
+<!-- source-hash: 616939ebe1c1aac14b882a4c493b1f39 -->
+A styled dropdown menu component built on Radix UI primitives, providing accessible, animated dropdown menus with support for nested submenus, checkbox/radio items, and portal-aware rendering that inherits the correct stacking context (e.g. inside drawers).
 
 ## Key Components
 
-- **DropdownMenu** - Root container component
-- **DropdownMenuTrigger** - Button that opens the dropdown
-- **DropdownMenuContent** - Main content container with portal rendering
-- **DropdownMenuItem** - Interactive menu items with hover states
-- **DropdownMenuCheckboxItem** - Checkable menu items with check indicators
-- **DropdownMenuRadioItem** - Radio button menu items for single selection
-- **DropdownMenuLabel** - Non-interactive section labels
-- **DropdownMenuSeparator** - Visual dividers between menu sections
-- **DropdownMenuShortcut** - Keyboard shortcut display component
-- **DropdownMenuSub/SubTrigger/SubContent** - Nested submenu components
-- **DropdownMenuGroup/RadioGroup** - Grouping containers
+| Export | Description |
+|---|---|
+| `DropdownMenu` | Root component wrapping the entire menu |
+| `DropdownMenuTrigger` | Element that toggles the menu open/closed |
+| `DropdownMenuContent` | Menu panel, portalled into the active container via `usePortalContainer` |
+| `DropdownMenuItem` | Standard clickable menu item with optional `inset` indent |
+| `DropdownMenuCheckboxItem` | Item with a checkmark indicator and controlled `checked` state |
+| `DropdownMenuRadioItem` | Item within a radio group, shows a filled circle when selected |
+| `DropdownMenuRadioGroup` | Groups `DropdownMenuRadioItem` components for single-selection |
+| `DropdownMenuSub` | Container for a nested submenu |
+| `DropdownMenuSubTrigger` | Item that opens a nested submenu, with a `ChevronRight` icon |
+| `DropdownMenuSubContent` | Panel for the nested submenu |
+| `DropdownMenuLabel` | Non-interactive section header with optional `inset` |
+| `DropdownMenuSeparator` | Horizontal divider between menu sections |
+| `DropdownMenuShortcut` | Right-aligned keyboard shortcut hint text |
+| `DropdownMenuGroup` | Logical grouping of related items |
+| `DropdownMenuPortal` | Direct access to Radix's portal primitive |
 
 ## Usage Example
 
 ```typescript
 import {
   DropdownMenu,
+  DropdownMenuTrigger,
   DropdownMenuContent,
   DropdownMenuItem,
-  DropdownMenuLabel,
+  DropdownMenuCheckboxItem,
   DropdownMenuSeparator,
-  DropdownMenuTrigger,
+  DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
 } from "./dropdown-menu"
 
-function UserMenu() {
+export function ActionsMenu() {
   return (
     <DropdownMenu>
-      <DropdownMenuTrigger>Open Menu</DropdownMenuTrigger>
+      <DropdownMenuTrigger>Open</DropdownMenuTrigger>
       <DropdownMenuContent>
-        <DropdownMenuLabel>My Account</DropdownMenuLabel>
-        <DropdownMenuSeparator />
-        <DropdownMenuItem>Profile</DropdownMenuItem>
-        <DropdownMenuItem>Settings</DropdownMenuItem>
+        <DropdownMenuItem>
+          Profile <DropdownMenuShortcut>⌘P</DropdownMenuShortcut>
+        </DropdownMenuItem>
+        <DropdownMenuCheckboxItem checked={true}>
+          Show Notifications
+        </DropdownMenuCheckboxItem>
         <DropdownMenuSeparator />
-        <DropdownMenuItem>Logout</DropdownMenuItem>
+        <DropdownMenuSub>
+          <DropdownMenuSubTrigger>More Options</DropdownMenuSubTrigger>
+          <DropdownMenuSubContent>
+            <DropdownMenuItem>Settings</DropdownMenuItem>
+          </DropdownMenuSubContent>
+        </DropdownMenuSub>
       </DropdownMenuContent>
     </DropdownMenu>
   )
 }
 ```
 
-All components use ODS tokens for consistent theming and include smooth animations, focus management, and accessibility features from Radix UI.
+> **Portal context:** `DropdownMenuContent` uses `usePortalContainer` to render into the nearest active container (e.g. a drawer), preventing z-index stacking issues. It falls back to `document.body` when no container is provided.

package/src/components/ui/.duration-input.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 874180cd50bd3a257869df027cbe8b99 -->
+Segmented `HH:MM:SS` duration input component where each time unit (hours, minutes, seconds) is an independently focusable field with keyboard navigation and auto-advance behavior.
+
+## Key Components
+
+- **`DurationInput`** — Main component export. Renders three linked `<input>` fields separated by colon delimiters.
+- **`DurationInputProps`** — Interface accepting `value` (`HH:MM:SS` string), `onChange` callback, optional `invalid` flag, and `className`.
+- **`SEGMENT_META`** — Tuple defining per-segment constraints: label, placeholder, and max value (99 for hours, 59 for minutes/seconds).
+- **`commit`** — Internal helper that syncs segment state, fires `onChange`, and optionally advances focus to the next segment.
+- **`split` / `compose`** — Converts between the `HH:MM:SS` string format and the internal `[HH, MM, SS]` tuple.
+
+## Usage Example
+
+```typescript
+import { useState } from "react";
+import { DurationInput } from "@openframe/ui";
+
+export function TimerForm() {
+  const [duration, setDuration] = useState("01:30:00");
+
+  return (
+    <DurationInput
+      value={duration}
+      onChange={setDuration}
+      invalid={duration === "00:00:00"}
+    />
+  );
+}
+```
+
+## Keyboard Behavior
+
+| Key | Action |
+|---|---|
+| `0–9` | Fill current segment; auto-advance when 2 digits entered or unambiguous (e.g., `6–9` in MM/SS) |
+| `ArrowUp` / `ArrowDown` | Increment/decrement current segment with wrap-around |
+| `ArrowLeft` / `ArrowRight` | Move between segments at boundary |
+| `Backspace` | Clear and move to previous segment when empty |
+| `:` | Advance to next segment |
+
+Values are clamped to segment maximums (MM/SS ≤ 59, HH ≤ 99), making it impossible to produce an invalid duration. External value changes (e.g., form resets) are adopted without interrupting in-progress edits.

package/src/components/ui/.entity-image.md

@@ -1,46 +1,50 @@
-<!-- source-hash: 3405ab77a3bbd5f68b76564b38e7a642 -->
-A client-side React component that renders an entity's avatar image with an automatic initials-based fallback when the image source is unavailable or fails to load.
+<!-- source-hash: e7e9a04ae63cfe62a3216f3d6d05a1e7 -->
+Renders an entity avatar that displays either an authenticated image or an initials-based fallback when the image is unavailable or fails to load.
 
 ## Key Components
 
-### `EntityImageProps`
+### `EntityImage`
+A client-side React component that handles image loading with graceful degradation.
+
+**Props (`EntityImageProps`):**
+
 | Prop | Type | Description |
-|------|------|-------------|
-| `src` | `string \| null` | Image URL to display |
-| `alt` | `string` | Alt text for the image and fallback aria-label |
+|---|---|---|
+| `src` | `string \| null` | Image URL (resolved through auth hook) |
+| `alt` | `string` | Alt text; also used as initials source |
 | `fallbackText` | `string` | Overrides `alt` as the initials source |
 | `className` | `string` | Additional CSS classes |
 
-### `EntityImage`
-Main export. Renders an `<img>` tag when a valid `src` is provided and loads successfully. Falls back to a styled `<div>` showing two-letter initials (via `getFirstLastInitials`) or `?` when no initials can be derived.
-
-**Fallback triggers:**
-- `src` is `null` or `undefined`
-- Image fires an `onError` event (broken URL, network failure, etc.)
-- Image error state resets automatically when `src` changes
+**Behavior:**
+- Resolves authenticated image URLs via `useAuthedImageSrc`
+- Resets error state when the resolved source changes
+- Shows an initials badge (via `getFirstLastInitials`) when the image fails or is absent
+- Falls back to `"?"` when no initials can be derived
+- Responsive sizing: `52px` on mobile, `60px` on `md+` breakpoints
 
 ## Usage Example
 
 ```typescript
-import { EntityImage } from './entity-image'
-
-// Renders the avatar image
+// Basic usage with an image URL
 <EntityImage
-  src="https://cdn.example.com/avatars/acme.png"
-  alt="Acme Corp"
+  src="https://cdn.example.com/avatars/user-123.png"
+  alt="Jane Doe"
 />
 
-// Renders initials fallback "AC" if image fails
+// With a custom fallback text for initials
 <EntityImage
   src={null}
-  alt="Acme Corp"
-  className="my-custom-class"
+  alt="Jane Doe"
+  fallbackText="Jane Smith"
+  className="ring-2 ring-ods-primary"
 />
 
-// Override initials source independently from alt text
-<EntityImage
-  src="https://cdn.example.com/avatars/john.png"
-  alt="User avatar"
-  fallbackText="John Doe"
-/>
-```
+// Initials-only (no src provided) — renders "JD"
+<EntityImage alt="John Doe" />
+```
+
+## Notes
+
+- Requires the `useAuthedImageSrc` hook to inject auth headers/tokens into image requests
+- Initials are derived using `getFirstLastInitials`, which extracts first and last name initials from the provided text
+- Images use `object-contain` to preserve aspect ratio within the fixed square bounds

package/src/components/ui/.error-state.md

@@ -1,23 +1,23 @@
-<!-- source-hash: 147d509f918f296b0265bcdeb8f2a9c1 -->
-Flexible error state display component for rendering contextual error, warning, and info messages with optional retry and navigation actions.
+<!-- source-hash: 52edfb71ac657ff2d7c4cc10e092d7b1 -->
+A client-side React component that renders styled error, warning, and info state banners with optional action buttons and convenience wrappers for common error scenarios.
 
 ## Key Components
 
 ### `ErrorState`
-The core component accepting the following props:
+The primary component accepting the following props:
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `title` | `string` | `'Error'` | Heading text displayed above the message |
-| `message` | `string` | — | *(required)* Body text describing the error |
-| `variant` | `'error' \| 'warning' \| 'info'` | `'error'` | Controls color scheme and styling |
+| `title` | `string` | `'Error'` | Heading text |
+| `message` | `string` | — | Body message (**required**) |
+| `variant` | `'error' \| 'warning' \| 'info'` | `'error'` | Visual style using ODS design tokens |
 | `showIcon` | `boolean` | `true` | Toggles the `AlertTriangle` icon |
-| `showRetry` | `boolean` | `false` | Shows "Try Again" button when `onRetry` is also provided |
-| `showHome` | `boolean` | `false` | Shows "Go Home" button when `onHome` is also provided |
-| `onRetry` | `() => void` | — | Callback fired on retry button click |
-| `onHome` | `() => void` | — | Callback fired on home button click |
-| `className` | `string` | — | Applied to the inner bordered card |
-| `containerClassName` | `string` | — | Applied to the outer wrapper `div` |
+| `showRetry` | `boolean` | `false` | Shows "Try Again" button |
+| `showHome` | `boolean` | `false` | Shows "Go Home" button |
+| `onRetry` | `() => void` | — | Retry callback |
+| `onHome` | `() => void` | — | Home navigation callback |
+| `className` | `string` | — | Applied to inner card |
+| `containerClassName` | `string` | — | Applied to outer wrapper |
 
 ### Convenience Components
 
@@ -27,31 +27,35 @@ The core component accepting the following props:
 | `LoadError` | `error` | Retry |
 | `NotFoundError` | `warning` | Home |
 
+> **Note on ODS tokens:** Variant styles use `-secondary` background tokens (e.g., `bg-ods-error-secondary`) rather than Tailwind alpha modifiers, which are incompatible with hex-based CSS custom properties in Tailwind 3.x.
+
 ## Usage Example
 
 ```typescript
-import { ErrorState, PageError, LoadError, NotFoundError } from './error-state'
+import { ErrorState, LoadError, NotFoundError } from './error-state'
 
-// Full control via ErrorState
+// Generic error with retry
 <ErrorState
-  title="Connection Failed"
-  message="Unable to reach the server."
-  variant="warning"
+  title="Sync Failed"
+  message="Could not reach the server. Please try again."
+  variant="error"
   showRetry
   onRetry={() => refetch()}
 />
 
-// Convenience wrappers
-<PageError
-  message="Something went wrong loading this page."
-  onRetry={() => router.refresh()}
-  onHome={() => router.push('/')}
-/>
-
+// Convenience: loading error
 <LoadError
-  message="Failed to load device list."
-  onRetry={() => refetch()}
+  message="Failed to load devices."
+  onRetry={() => reload()}
 />
 
+// Convenience: 404-style warning
 <NotFoundError onHome={() => router.push('/')} />
+
+// Info banner (no icon)
+<ErrorState
+  variant="info"
+  message="No results match your current filters."
+  showIcon={false}
+/>
 ```

package/src/components/ui/.fade-preview.md

@@ -0,0 +1,44 @@
+<!-- source-hash: d542ea42b0980a55a14eb86a5aae0060 -->
+Shared progressive-disclosure primitive that clamps long content to a fixed height with a CSS fade mask and a "Show N more / Show less" toggle button.
+
+## Key Components
+
+### `FadePreviewProps`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `hiddenCount` | `number` | — | Items hidden while collapsed; drives "Show N more" label. `<= 0` disables clamping entirely |
+| `collapsedHeight` | `number` | `120` | Collapsed height in px before the fade mask kicks in |
+| `resetKey` | `unknown` | — | Resets expanded state when value changes (e.g. on data refetch) |
+| `children` | `React.ReactNode` | — | Content to render inside the clamp wrapper |
+
+### `FadePreview`
+
+Stateful component managing expand/collapse. When `hiddenCount <= 0`, renders children unwrapped with no height clamp — avoids clipping single-entry sections. Expanded height is measured from `scrollHeight` to handle variable-length content.
+
+## Usage Example
+
+```typescript
+import { FadePreview } from '@/components/fade-preview';
+
+// Basic usage — hide overflow items in a changelog list
+<FadePreview hiddenCount={releases.length - 3} resetKey={releases.length}>
+  {releases.map(r => <ReleaseEntry key={r.id} release={r} />)}
+</FadePreview>
+
+// Taller rows (e.g. a delivery table) — increase collapsed height
+<FadePreview hiddenCount={rows.length - 5} collapsedHeight={240}>
+  <DeliveryTable rows={rows} />
+</FadePreview>
+
+// Single entry — no fade, no toggle rendered
+<FadePreview hiddenCount={0}>
+  <SingleEntry entry={entry} />
+</FadePreview>
+```
+
+> **Do not re-inline the mask/clamp/toggle pattern.** All fade-preview surfaces must compose this component — it is the single shared implementation extracted from `ReleaseChangelogSection`.
+
+## Source
+
+[`fade-preview.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/fade-preview.tsx)

package/src/components/ui/.field-wrapper.md

@@ -1,47 +1,58 @@
-<!-- source-hash: 0d873ee81fa30b5916e604a92d4925d2 -->
-A layout wrapper component that provides consistent label and error message chrome for form fields, with reserved space to prevent layout shifts.
+<!-- source-hash: bd15d4489bb0eca1b2faabacba129705 -->
+A layout wrapper component that adds an optional label above and a status message below any form field, handling the visual chrome (label + feedback text) while letting the field itself remain unstyled.
 
 ## Key Components
 
 ### `FieldWrapper`
-A `forwardRef` component that wraps form field children with optional label and error/warning message display.
+A `forwardRef` component that wraps form fields with consistent label and feedback message rendering.
+
+**Props (`FieldWrapperProps`)**
 
-### `FieldWrapperProps`
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `label` | `string` | — | Label text rendered above the field |
-| `error` | `string` | — | Error message rendered below the field |
-| `errorVariant` | `"error" \| "warning"` | `"error"` | Controls error text color (red vs yellow) |
-| `className` | `string` | — | Additional classes for the outer wrapper |
-| `children` | `React.ReactNode` | — | The form field element(s) |
+| `error` | `string` | — | Status/feedback message rendered below the field |
+| `errorVariant` | `"error" \| "warning" \| "success" \| "muted"` | `"error"` | Color variant for the feedback message |
+| `className` | `string` | — | Additional class applied to the outer wrapper |
+| `children` | `React.ReactNode` | — | The field element(s) to wrap |
+
+**Behavior:**
+- When neither `label` nor `error` is present, the wrapper renders as `contents` (no layout box introduced).
+- When either exists, it renders as a full-width flex column.
+- The feedback message clamps to 2 lines with ellipsis; the full text is accessible via the native `title` tooltip.
 
-### Behavior Notes
-- When neither `label` nor `error` is provided, the wrapper renders as `contents` (no extra DOM box).
-- The error message is absolutely positioned (`translate-y-full`) below the field, preventing layout shifts in the surrounding form.
-- Long error messages are `truncate`d with the full text accessible via the `title` attribute.
+**Color Variants:**
+
+| Variant | Color token |
+|---------|------------|
+| `error` | `text-ods-error` |
+| `warning` | `text-ods-warning` |
+| `success` | `text-ods-success` |
+| `muted` | `text-ods-text-secondary` |
 
 ## Usage Example
 
 ```typescript
-import { FieldWrapper } from "./field-wrapper"
-import { TextInput } from "./text-input"
+import { FieldWrapper } from "@openframe-oss-lib/components"
 
-// Standard field with label and error
+// Basic usage with label and error feedback
 <FieldWrapper label="Email address" error="Invalid email format">
-  <TextInput type="email" value={email} onChange={handleChange} />
+  <input type="email" className="..." />
 </FieldWrapper>
 
-// Warning variant
+// Success state after validation
 <FieldWrapper
   label="Username"
-  error="Username is already taken"
-  errorVariant="warning"
+  error="Username is available!"
+  errorVariant="success"
 >
-  <TextInput value={username} onChange={handleChange} />
+  <input type="text" className="..." />
 </FieldWrapper>
 
-// No chrome — wrapper renders as contents
+// Passthrough — no wrapper box introduced in the DOM
 <FieldWrapper>
-  <TextInput placeholder="Search..." />
+  <input type="text" className="..." />
 </FieldWrapper>
-```
+```
+
+> **Source:** [`field-wrapper.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/field-wrapper.tsx)

package/src/components/ui/.file-upload.md

@@ -1,42 +1,54 @@
-<!-- source-hash: cf353b09cad830f836030fb8046e62bc -->
-A flexible React dropzone component supporting both simple file selection and async managed upload workflows, with drag-and-drop, validation, and file list rendering.
+<!-- source-hash: 4c976421380cc16af600736693d5afa7 -->
+A client-side React component providing a drag-and-drop file upload zone with support for both simple synchronous file handling and async managed upload workflows (e.g., presigned URL uploads).
 
 ## Key Components
 
 ### Interfaces
-- **`ManagedFileEntry`** — Represents an async-uploaded file with `id`, `fileName`, `fileSize`, `status` (`uploading` | `uploaded` | `error`), and optional `error` message
-- **`FileUploadProps`** — Full prop interface supporting both simple (`value`/`onChange`) and managed (`managedFiles`/`onRemoveManagedFile`) modes
 
-### Helpers
-- **`formatFileSize(bytes)`** — Converts bytes to human-readable string (B, KB, MB, GB)
-- **`matchesAccept(file, accept)`** — Validates a file against an accept string (MIME types, extensions, wildcards)
-- **`dragHasFiles(e)`** — Detects if a native drag event carries file data
+- **`ManagedFileEntry`** — Represents an async upload entry with `id`, `fileName`, `fileSize`, `status` (`"uploading" | "uploaded" | "error"`), and optional `error` message.
+- **`FileUploadProps`** — Full prop surface for the component, supporting both simple (`value`/`onChange`) and managed (`managedFiles`/`onRemoveManagedFile`) modes.
+
+### Internal Utilities
+
+- **`formatFileSize(bytes)`** — Converts byte count to a human-readable string (B, KB, MB, GB).
+- **`matchesAccept(file, accept)`** — Validates a `File` against an `accept` string (extension, wildcard MIME, or exact MIME).
+- **`dragHasFiles(e)`** — Checks whether a native `DragEvent` carries file payloads.
 
 ### Component
-- **`FileUpload`** — Main export; renders a dropzone button (when empty) or file list (when files exist), with optional window-level drop capture via `acceptWindowDrops`
+
+- **`FileUpload`** — Main export. Renders a dropzone with file list, validation, and optional window-level drop capture.
 
 ## Usage Example
 
 ```typescript
-// Simple single-file mode
+// Simple mode — synchronous, single file
 <FileUpload
   value={file}
   onChange={(f) => setFile(f as File)}
   accept="image/*"
   maxSize={5 * 1024 * 1024}
-  fieldLabel="Profile Photo"
+  fieldLabel="Attachment"
 />
 
-// Async managed upload mode
+// Managed mode — async upload workflow
 <FileUpload
-  onChange={(files) => uploadToS3(files as File[])}
-  managedFiles={managedFiles}
-  onRemoveManagedFile={(id) => removeManagedFile(id)}
+  managedFiles={uploadedFiles}
+  onChange={(files) => uploadToPresignedUrl(files as File[])}
+  onRemoveManagedFile={(id) => removeFile(id)}
+  onDownloadManagedFile={(id) => downloadFile(id)}
   multiple
+  accept=".pdf,.doc,.docx"
   maxFiles={5}
-  acceptWindowDrops
-  label="Drop attachments here"
+  acceptWindowDrops  // captures drops anywhere in the window
 />
 ```
 
-> **Tip:** Use `managedFiles` + `onRemoveManagedFile` for presigned URL or background upload flows where upload status (`uploading` | `uploaded` | `error`) needs to be reflected in the UI. Use plain `value`/`onChange` for synchronous or form-controlled scenarios.
+## Key Behaviors
+
+| Feature | Detail |
+|---|---|
+| Mode detection | `managedFiles !== undefined` switches to managed mode |
+| Validation | Type, size, and count checks before `onChange` fires |
+| Window drops | `acceptWindowDrops` suppresses browser default and routes drops here |
+| Single-file mode | Dropzone hides after a file is selected |
+| Scroll cap | `maxListHeight` constrains the file list with independent scroll |