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

package/src/components/ui/.filter-modal.md

@@ -1,37 +1,34 @@
-<!-- source-hash: 0a032d083c46e509f8e9dcfa0550baef -->
-A modal dialog component for sorting and filtering table data, combining checkbox filter groups, column sorting, and tag key-value filters into a unified UI with loading and empty states.
+<!-- source-hash: ca205bda020052993b18624b8ae80fb9 -->
+A modal dialog component for sorting and filtering table data, supporting checkbox filter groups, column sorting, tag key-value filters, and date range filtering with draft state management.
 
 ## Key Components
 
-### `FilterModal`
-Main exported component that renders a `ModalV2`-based dialog with three content sections and footer action buttons.
+### Interfaces
 
-### Exported Types
-
-| Type | Description |
-|------|-------------|
+| Interface | Description |
+|---|---|
 | `FilterModalOption` | Single filter option with `id`, `label`, and optional `count` |
 | `FilterGroup` | Named group of `FilterModalOption` items |
-| `FilterModalProps` | Full props interface for `FilterModal` |
-| `SortConfig`, `SortDirection`, `SortableColumn` | Re-exported from `sort-column-item` |
-| `TagKeyConfig`, `TagValueOption` | Re-exported from `tag-key-value-filter` |
+| `FilterModalProps` | Full props definition for the modal |
+
+### Exported Types (re-exported)
+
+- `SortableColumn`, `SortConfig`, `SortDirection` — from `sort-column-item`
+- `TagKeyConfig`, `TagValueOption` — from `tag-key-value-filter`
 
-### Internal Behavior
-- **Local state** (`selectedFilters`, `pendingTags`) buffers user selections until **Apply** is clicked
-- **Reset** clears all filters and tags immediately via `onFilterChange({})` and `onTagsChange?.([])`
-- **Sync on open** — `useEffect` resets local state to `currentFilters`/`selectedTags` whenever the modal opens
-- **Empty state** renders when no sort columns, filter groups, or tag filters are present
-- **Loading state** renders skeleton placeholders when `isLoading` is `true`
+### Behavior
+
+- **Draft state**: All selections are held locally and only committed on **Apply**; **Reset** clears all filters to defaults and closes the modal.
+- **Scroll shadows**: `useScrollFade` adds top/bottom fade overlays as the filter list scrolls.
+- **Loading state**: When `isLoading` is true, renders skeleton rows instead of filter content.
+- **Empty state**: Renders an icon + message when no sort columns, filter groups, tag filters, or date filter are provided.
 
 ## Usage Example
 
 ```typescript
-const [filters, setFilters] = useState<TableFilters>({})
-const [tags, setTags] = useState<string[]>([])
-
 <FilterModal
-  isOpen={isModalOpen}
-  onClose={() => setIsModalOpen(false)}
+  isOpen={isFilterOpen}
+  onClose={() => setFilterOpen(false)}
   filterGroups={[
     {
       id: 'status',
@@ -42,18 +39,19 @@ const [tags, setTags] = useState<string[]>([])
       ],
     },
   ]}
+  currentFilters={activeFilters}
+  onFilterChange={(filters) => setActiveFilters(filters)}
   sortConfig={{
     title: 'Sort By',
-    sortBy: 'name',
-    sortDirection: 'asc',
-    columns: [{ key: 'name', label: 'Name' }],
+    sortBy: 'createdAt',
+    sortDirection: 'desc',
+    columns: [{ key: 'createdAt', label: 'Created Date' }],
+  }}
+  onSort={(column, direction) => handleSort(column, direction)}
+  dateFilter={{
+    title: 'Created Date',
+    sort: 'desc',
+    onChange: ({ sort, range }) => handleDateFilter(sort, range),
   }}
-  onSort={(column, direction) => console.log(column, direction)}
-  onFilterChange={setFilters}
-  currentFilters={filters}
-  tagFilterKeys={[{ key: 'env', label: 'Environment', values: [] }]}
-  selectedTags={tags}
-  onTagsChange={setTags}
-  isLoading={false}
 />
 ```

package/src/components/ui/.filter-pill-row.md

@@ -0,0 +1,58 @@
+<!-- source-hash: a577052f327703a1df3f43615b02c000 -->
+A responsive filter pill row component that renders a labeled set of toggle buttons inside a card container, used to filter catalog views by status, platform, section, or other dimensions.
+
+## Key Components
+
+### Interfaces
+
+| Interface | Description |
+|---|---|
+| `FilterPillRowOption` | Shape for each filter option: `value` (key) and `label` (display text) |
+| `FilterPillRowProps` | Full props contract for `FilterPillRow` |
+
+### `FilterPillRow` (named export)
+
+Renders a flex-wrap card containing:
+- A `Filter` icon + label on the left
+- A pill button per option (active pill uses `accent` variant, inactive uses `outline`)
+- An optional `countLabel` right-aligned (e.g. `"Showing 1-10 of 42 items"`)
+- Optional `children` to replace the default pill buttons with custom filter content
+
+## Usage Example
+
+```typescript
+import { FilterPillRow } from '@openframe-oss-lib/ui'
+
+const PLATFORM_OPTIONS = [
+  { value: 'all',     label: 'All'     },
+  { value: 'windows', label: 'Windows' },
+  { value: 'mac',     label: 'macOS'   },
+  { value: 'linux',   label: 'Linux'   },
+]
+
+export function ToolCatalogFilters() {
+  const [platform, setPlatform] = useState('all')
+
+  return (
+    <FilterPillRow
+      label="Platform"
+      selectedValue={platform}
+      onValueChange={setPlatform}
+      options={PLATFORM_OPTIONS}
+      countLabel="Showing 12 of 48 tools"
+    />
+  )
+}
+```
+
+**Custom content via `children`:**
+
+```typescript
+<FilterPillRow label="Status" selectedValue="" onValueChange={() => {}}>
+  <MyCustomToggleGroup />
+</FilterPillRow>
+```
+
+> **Note:** When `children` is provided it replaces the auto-generated pill buttons entirely; `options` is ignored.
+
+**Source:** [`components/filter-pill-row.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/components/filter-pill-row.tsx)

package/src/components/ui/.floating-tooltip.md

@@ -1,36 +1,24 @@
-<!-- source-hash: c7355b336531eeee83c49994040e5cbf -->
-A floating tooltip component built with `@floating-ui/react` that supports smart positioning, directional arrows, and inline color markup parsing.
+<!-- source-hash: 2b8cdba1cd5071a00b33994ad26e4c91 -->
+Accessible, positioned tooltip component built on `@floating-ui/react` that supports smart viewport-aware placement, overflow scrolling, and inline color markup parsing.
 
 ## Key Components
 
 ### `FloatingTooltip`
-The main exported component. Renders a portal-based tooltip with:
-- **Auto-positioning** via `flip`, `shift`, and `offset` middleware — avoids viewport clipping
-- **Arrow indicator** that dynamically repositions based on the resolved placement
-- **Hover interaction** with configurable open delay and safe polygon close detection
-- **`disabled` prop** — suppresses tooltip without unmounting the trigger wrapper
+The main exported component. Renders a hover-triggered tooltip using Floating UI's positioning engine with auto-update, flipping, shifting, and viewport-capped height.
 
-### `parseColoredText` (internal)
-Parses `[COLOR]text[/COLOR]` markup within string content and maps it to ODS CSS classes:
-
-| Tag | Tailwind Class |
-|-----|----------------|
-| `[YELLOW]` | `text-ods-accent` |
-| `[GREEN]` | `text-ods-success` |
-| `[RED]` | `text-ods-error` |
-| `[BLUE]` / `[CYAN]` | `text-ods-info` |
-| `[PINK]` | `text-ods-accent` |
-
-### `FloatingTooltipProps`
+**Props:**
 
 | Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `content` | `React.ReactNode` | — | Tooltip body; strings support color markup |
-| `children` | `React.ReactNode` | — | Trigger element |
+|---|---|---|---|
+| `content` | `React.ReactNode` | — | Tooltip content; strings support color markup |
+| `children` | `React.ReactNode` | — | The trigger element |
 | `side` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | Preferred placement |
-| `delayDuration` | `number` | `0` | Open delay in ms |
-| `disabled` | `boolean` | `false` | Suppresses tooltip |
-| `className` | `string` | — | Extra classes on the tooltip panel |
+| `className` | `string` | — | Additional classes for the tooltip panel |
+| `delayDuration` | `number` | `0` | Hover open delay in ms |
+| `disabled` | `boolean` | `false` | Disables tooltip without unmounting the trigger |
+
+### `parseColoredText` (internal)
+Parses `[COLOR]text[/COLOR]` markup within string content into styled `<span>` elements mapped to ODS design tokens. Supported color tags: `YELLOW`, `GREEN`, `RED`, `BLUE`, `PINK`, `CYAN`.
 
 ## Usage Example
 
@@ -38,21 +26,28 @@ Parses `[COLOR]text[/COLOR]` markup within string content and maps it to ODS CSS
 import { FloatingTooltip } from "./floating-tooltip"
 
 // Basic usage
-<FloatingTooltip content="Save changes">
+<FloatingTooltip content="Save your changes before leaving.">
   <button>Save</button>
 </FloatingTooltip>
 
-// With color markup and delay
+// With color markup and custom placement
 <FloatingTooltip
-  content="Status: [GREEN]Online[/GREEN] — [YELLOW]1 warning[/YELLOW]"
+  content="Status: [GREEN]Online[/GREEN] — latency [YELLOW]elevated[/YELLOW]"
   side="top"
   delayDuration={300}
 >
   <span>Hover me</span>
 </FloatingTooltip>
 
-// Disabled (wrapper renders, tooltip suppressed)
-<FloatingTooltip content="Hidden tip" disabled>
-  <button>No tooltip</button>
+// Conditionally disabled
+<FloatingTooltip content="Not available" disabled={!featureEnabled}>
+  <button>Feature</button>
 </FloatingTooltip>
-```
+```
+
+## Behavior Notes
+
+- Tooltip is rendered into a `FloatingPortal` at `z-index: 2147483647` to avoid stacking context issues
+- The `size` middleware caps tooltip height to available viewport space; tall content becomes scrollable via the inner wrapper
+- Arrow position is computed automatically and adjusts with placement flipping
+- `safePolygon()` prevents accidental dismissal when moving the cursor toward the tooltip

package/src/components/ui/.hidden-tags-popup.md

@@ -1,49 +1,47 @@
-<!-- source-hash: cc1ede727d1bab8a8e8ff3b969595614 -->
-A floating popup component that displays a list of hidden tag items with optional remove functionality, typically used in multi-select inputs when tags overflow the visible area.
+<!-- source-hash: 710e86ff076bce6ef45b86d10ed1ec51 -->
+A floating popup component that displays a list of hidden/overflow tags with optional removal capability, typically used when tag inputs have more items than visible space allows.
 
 ## Key Components
 
 ### Interfaces
 
-| Interface | Description |
-|-----------|-------------|
-| `HiddenTagItem` | Defines a tag item with a `label` (ReactNode) and `value` (unknown) |
-| `HiddenTagsPopupProps` | Props for the popup including `items`, `onRemove`, `disabled`, `className`, and `style` |
+- **`HiddenTagItem`** — Describes a single tag entry with a `label` (`ReactNode`) and `value` (`unknown`)
+- **`HiddenTagsPopupProps`** — Props for the popup component:
+  - `items` — Array of `HiddenTagItem` to render
+  - `onRemove` — Optional callback fired with the item's `value` when the remove button is clicked
+  - `disabled` — Hides remove buttons when `true`
+  - `className` / `style` — For positioning overrides (consumers set `style.left` or `className` for alignment)
 
-### Exports
+### Component
 
-- **`HiddenTagsPopup`** — A `forwardRef` component rendering an absolutely-positioned dropdown card listing overflow tags. Each item shows a truncated uppercase label and an optional remove button (`XmarkCircleIcon`) when `onRemove` is provided and `disabled` is false.
+- **`HiddenTagsPopup`** — A `forwardRef` div that renders absolutely below its anchor (`top-full`), with an animated entrance (`animate-in fade-in-0 zoom-in-95`). Each item row shows a truncated, uppercase label and an `XmarkCircleIcon` remove button (when not disabled).
 
 ## Usage Example
 
 ```typescript
-import { HiddenTagsPopup, HiddenTagItem } from "./hidden-tags-popup"
+import { HiddenTagsPopup } from "./hidden-tags-popup"
 
-const overflowTags: HiddenTagItem[] = [
+const overflowTags = [
   { label: "Engineering", value: "engineering" },
   { label: "Design", value: "design" },
 ]
 
-function TagSelector() {
+function TagInput() {
   const handleRemove = (value: unknown) => {
-    console.log("Remove tag:", value)
+    console.log("Removing tag:", value)
   }
 
   return (
-    <div style={{ position: "relative" }}>
+    <div className="relative">
+      {/* anchor element */}
       <HiddenTagsPopup
         items={overflowTags}
         onRemove={handleRemove}
-        disabled={false}
+        style={{ left: 0 }}
       />
     </div>
   )
 }
 ```
 
-## Notes
-
-- Renders with `z-50` and `top-full` positioning — expects a relatively-positioned parent container.
-- Includes entrance animation via `animate-in fade-in-0 zoom-in-95`.
-- Remove button uses `e.stopPropagation()` to prevent unintended parent click events.
-- Accessible via `aria-label` on each remove button.
+> **Note:** Wrap the popup in a relatively positioned container. Use `style.left` or a `className` override to control horizontal alignment.

package/src/components/ui/.highlight-card.md

@@ -1,43 +1,56 @@
-<!-- source-hash: a7601384671770e4376abbdab7aed0bf -->
-A React component system for displaying highlighted text cards with categories and responsive grid layouts.
+<!-- source-hash: 9562b3fbd93d3258fdb8884c703e1606 -->
+Renders a styled card with a colored highlight behind a category label, and a grid layout component for displaying multiple highlight cards with responsive borders.
 
 ## Key Components
 
-- **`HighlightCard`** - Individual card component with responsive highlight backgrounds and styled category text
-- **`HighlightCardGrid`** - Grid container for multiple highlight cards with configurable columns (2 or 3)
-- **`HighlightCardItem`** - Interface defining card data structure (category, colors, description)
-- **`HighlightCardProps`** - Props interface for individual cards
-- **`HighlightCardGridProps`** - Props interface for grid layout configuration
+| Export | Type | Description |
+|---|---|---|
+| `HighlightCardItem` | Interface | Data shape for a single card: `category`, `categoryColor`, `highlightBg`, `description` |
+| `HighlightCardProps` | Interface | Props for `HighlightCard`: `item` + optional `className` |
+| `HighlightCard` | Component | Single card with a color-highlighted category label and description text |
+| `HighlightCardGridProps` | Interface | Props for `HighlightCardGrid`: `items`, `columns` (2 or 3), `className`, `cardClassName` |
+| `HighlightCardGrid` | Component | Responsive grid of `HighlightCard` components with automatic border management |
 
 ## Usage Example
 
 ```typescript
-import { HighlightCard, HighlightCardGrid, HighlightCardItem } from './highlight-card';
+import { HighlightCardGrid, HighlightCardItem } from './highlight-card';
 
-const highlightItems: HighlightCardItem[] = [
+const items: HighlightCardItem[] = [
   {
-    category: 'data',
+    category: 'Network',
     categoryColor: '#3B82F6',
     highlightBg: '#DBEAFE',
-    description: 'visualization needs'
+    description: 'infrastructure is monitored 24/7',
   },
   {
-    category: 'workflow',
-    categoryColor: '#10B981',
-    highlightBg: '#D1FAE5',
-    description: 'automation solution'
-  }
+    category: 'Security',
+    categoryColor: '#EF4444',
+    highlightBg: '#FEE2E2',
+    description: 'posture is always up to date',
+  },
 ];
 
-// Single card
-<HighlightCard item={highlightItems[0]} />
+// 2-column grid (default)
+<HighlightCardGrid items={items} columns={2} />
 
-// Grid layout
-<HighlightCardGrid 
-  items={highlightItems}
-  columns={2}
+// 3-column grid with custom wrapper styles
+<HighlightCardGrid
+  items={items}
+  columns={3}
   className="my-8"
+  cardClassName="border border-gray-200 rounded-xl overflow-hidden"
+/>
+
+// Single card
+<HighlightCard
+  item={items[0]}
+  className="rounded-lg"
 />
 ```
 
-The component features responsive highlight backgrounds that scale with text length, custom typography using Azeret Mono font, and intelligent border management for grid layouts across mobile and desktop viewports.
+## Notes
+
+- Category highlight width is calculated dynamically from `category.length` (`×12px` mobile, `×14px` desktop).
+- `HighlightCardGrid` handles responsive border placement automatically — right borders appear only on desktop, bottom borders are suppressed on the last item/row per breakpoint.
+- Styling relies on Tailwind CSS with custom design tokens (`ods-bg`, `ods-text-primary`, `ods-border`, etc.) from the OpenFrame Design System.

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

@@ -0,0 +1,41 @@
+<!-- source-hash: 6f5652850fde2ac3f712e1ec49012b20 -->
+An invisible decoy input component for bot detection in React forms. It renders an off-screen, zero-size input that real users never interact with — bots that fill every visible field will trigger it, allowing the server to reject the submission.
+
+## Key Components
+
+- **`HoneypotField`** — A `forwardRef` component accepting a `name` prop, used to wire the input into form submission data and connect the ref from `useHumanitySignals`.
+
+## Usage Example
+
+```typescript
+import { HoneypotField } from './honeypot-field'
+import { useHumanitySignals } from '@/hooks/use-humanity-signals'
+
+function ContactForm() {
+  const { honeypotInputProps } = useHumanitySignals()
+
+  return (
+    <form action={submitAction}>
+      <input name="email" type="email" />
+      {/* Invisible to users; bots that fill it are blocked server-side */}
+      <HoneypotField {...honeypotInputProps} />
+      <button type="submit">Send</button>
+    </form>
+  )
+}
+```
+
+## Bot Detection Strategy
+
+The field is hidden using CSS layout utilities only (no `display:none`, `visibility:hidden`, or `type="hidden"`), since sophisticated bots skip those patterns. Instead it uses:
+
+| Technique | Purpose |
+|---|---|
+| `absolute w-px h-px -m-px overflow-hidden` | Off-screen, zero effective size |
+| `aria-hidden="true"` | Excluded from accessibility tree |
+| `tabIndex={-1}` | Excluded from tab order |
+| `pointer-events-none opacity-0` | Not clickable or visible |
+| `autoComplete="off"` | Prevents browser autofill from triggering it |
+| No `<label>` | Avoids id coupling and screen reader exposure |
+
+**Server-side:** reject any submission where this field's value is non-empty.

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

@@ -1,24 +1,31 @@
-<!-- source-hash: eee1f55a6c5cf2349c0897b18c2dfcf1 -->
-A reusable hover-triggered dropdown component that displays a list of clickable items. Uses fixed positioning via `getBoundingClientRect` to render correctly inside overflow-hidden containers like modals and sheets.
+<!-- source-hash: 5c15b5ebe13ad3bb647655980a430fb0 -->
+A hover-triggered dropdown component that renders a list of clickable items with smart viewport-aware positioning using `getBoundingClientRect` and fixed positioning — designed to escape `overflow: hidden` containers like modals and sheets.
 
 ## Key Components
 
-### Interfaces
+### Exports
 
-| Export | Description |
-|--------|-------------|
-| `HoverDropdownItem` | Defines each row: `label`, optional `icon`, `href`, `onClick`, `targetPlatform`, `path`, and an independent `secondaryAction` button |
-| `HoverDropdownRenderAnchorArgs` | Arguments passed to the `renderAnchor` slot for custom link routing |
-| `HoverDropdownProps` | Component props: `items`, `side`, `hideDelay`, `className`, `renderAnchor` |
+| Export | Type | Description |
+|---|---|---|
+| `HoverDropdown` | Component | Main dropdown component, triggered on hover (and click/tap) |
+| `HoverDropdownItem` | Interface | Shape for each dropdown row item |
+| `HoverDropdownRenderAnchorArgs` | Interface | Args passed to the `renderAnchor` slot |
 
-### Component
+### `HoverDropdownItem` Fields
 
-**`HoverDropdown`** — Main export. Wraps any trigger element and shows a positioned dropdown on hover (or tap). Each row supports three render modes:
-- **Link row** — rendered via `renderAnchor` (defaults to plain `<a>`)
-- **Button row** — rendered as `<button>` when `onClick` is provided
-- **Non-interactive row** — rendered as `<span>` when neither `href` nor `onClick` is present (useful when only a `secondaryAction` applies)
+| Field | Description |
+|---|---|
+| `label` | Display text for the row |
+| `icon` | Optional leading icon node |
+| `href` | Makes the row a link; routed via `renderAnchor` |
+| `targetPlatform` | Forwarded to `renderAnchor` for routing decisions |
+| `path` | In-app doc-tree path forwarded to `renderAnchor` for chat nav |
+| `onClick` | Fallback click handler when no `href` is present |
+| `secondaryAction` | Independent icon-button at the row's right edge |
 
-The dropdown auto-positions right → left → above/below based on available viewport space.
+### Positioning Logic
+
+The dropdown prefers placement **right** of the trigger, falls back **left**, then falls back **above/below** based on the `side` prop and available viewport space.
 
 ## Usage Example
 
@@ -28,27 +35,33 @@ The dropdown auto-positions right → left → above/below based on available vi
   <span>Blog Posts (3)</span>
 </HoverDropdown>
 
-// With custom anchor renderer (e.g., chat runtime routing)
-<HoverDropdown
-  items={[
-    {
-      label: 'Design Doc',
-      href: '/docs/design',
-      path: 'docs/design',
-      targetPlatform: 'markdown',
-      secondaryAction: {
-        icon: <AskIcon />,
-        label: 'Ask about this',
-        onClick: () => handleAsk('design'),
-      },
+// Chat consumer with custom anchor renderer and secondary action
+const items: HoverDropdownItem[] = [
+  {
+    label: 'Q3 Report',
+    href: '/docs/q3-report',
+    targetPlatform: 'markdown',
+    path: '/reports/q3',
+    secondaryAction: {
+      icon: <AskIcon />,
+      label: 'Ask about this',
+      onClick: () => handleAsk('q3-report'),
     },
-  ]}
-  renderAnchor={({ href, className, children }) => (
-    <NavLinkAnchorViaRuntime href={href} className={className}>
+  },
+]
+
+<HoverDropdown
+  items={items}
+  side="bottom"
+  hideDelay={300}
+  renderAnchor={({ href, path, className, children }) => (
+    <NavLinkAnchorViaRuntime href={href} path={path} className={className}>
       {children}
     </NavLinkAnchorViaRuntime>
   )}
 >
   <Chip>Documents</Chip>
 </HoverDropdown>
-```
+```
+
+> **Source:** [`hover-dropdown.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/hover-dropdown.tsx)

package/src/components/ui/.image-gallery-modal.md

@@ -1,59 +1,57 @@
-<!-- source-hash: 7ceb686fa07cb2b79511a1e43f5bce1a -->
-A full-screen image gallery modal component with keyboard navigation, prev/next controls, and an image counter. Extracted as a reusable component from the TMCG event detail page.
+<!-- source-hash: c830a3a2150d037a47f9fe653ca5eac0 -->
+Full-screen image gallery modal component with keyboard navigation, prev/next controls, and image counter display.
 
 ## Key Components
 
 ### `ImageGalleryModal`
-The primary export — a React client component wrapping the base `Modal` with gallery-specific behavior.
+
+The primary (and only) export. Renders a full-screen modal wrapping an image carousel.
 
 **Props (`ImageGalleryModalProps`):**
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `images` | `string[]` | Array of image URLs to display |
-| `isOpen` | `boolean` | Controls modal visibility |
-| `onClose` | `() => void` | Callback fired on close or `Escape` key |
-| `initialIndex` | `number` | Starting image index (default: `0`) |
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `images` | `string[]` | — | Array of image URLs to display |
+| `isOpen` | `boolean` | — | Controls modal visibility |
+| `onClose` | `() => void` | — | Callback fired on close |
+| `initialIndex` | `number` | `0` | Starting image index when modal opens |
 
-**Features:**
-- **Keyboard navigation** — `ArrowLeft`, `ArrowRight` to navigate; `Escape` to close
-- **Prev/Next buttons** — conditionally rendered based on current index boundaries
-- **Image counter** — shown when gallery has more than one image (e.g. `2 / 5`)
-- **Error handling** — gracefully handles unsupported formats (HEIC) with a download fallback
-- **Index reset** — resets to `initialIndex` each time the modal opens
+**Behaviors:**
+- **Keyboard navigation** — `ArrowLeft` / `ArrowRight` cycle through images; `Escape` closes the modal
+- **Error handling** — Detects unsupported formats (e.g. HEIC) and renders a fallback download link in place of broken images
+- **Index reset** — Resets to `initialIndex` whenever the modal re-opens
+- **Conditional controls** — Prev/next buttons and counter only render when `images.length > 1`
 
 ## Usage Example
 
 ```typescript
-import { ImageGalleryModal } from './image-gallery-modal';
+import { ImageGalleryModal } from '@/components/ui/image-gallery-modal';
 
 const screenshots = [
-  'https://cdn.example.com/img1.jpg',
-  'https://cdn.example.com/img2.jpg',
-  'https://cdn.example.com/img3.heic',
+  'https://cdn.example.com/photo-1.jpg',
+  'https://cdn.example.com/photo-2.jpg',
+  'https://cdn.example.com/photo-3.heic',
 ];
 
 export function EventDetail() {
-  const [isOpen, setIsOpen] = useState(false);
+  const [galleryOpen, setGalleryOpen] = useState(false);
   const [startIndex, setStartIndex] = useState(0);
 
   return (
     <>
-      {screenshots.map((src, i) => (
-        <img
-          key={src}
-          src={src}
-          onClick={() => { setStartIndex(i); setIsOpen(true); }}
-        />
-      ))}
+      <button onClick={() => { setStartIndex(0); setGalleryOpen(true); }}>
+        View Photos
+      </button>
 
       <ImageGalleryModal
         images={screenshots}
-        isOpen={isOpen}
-        onClose={() => setIsOpen(false)}
+        isOpen={galleryOpen}
+        onClose={() => setGalleryOpen(false)}
         initialIndex={startIndex}
       />
     </>
   );
 }
-```
+```
+
+> **Source:** [`components/ui/image-gallery-modal.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/components/ui/image-gallery-modal.tsx)