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

package/src/hooks/ui/.use-image-edge-color.md

@@ -0,0 +1,42 @@
+<!-- source-hash: 38dbaa1fd6bace90952c3ff98f54f23a -->
+A React hook that extracts the dominant edge color from an image URL for use as a background fill behind letterboxed (`object-contain`) images.
+
+## Key Components
+
+### `extractEdgeColor(img: HTMLImageElement): string`
+Internal utility that performs canvas-based pixel analysis:
+- Scales the image down to a 100×100 thumbnail for performance
+- Samples a 15% border band along all four edges
+- Quantizes RGB values into 32-step buckets to group similar colors
+- Returns the averaged RGB of the most common bucket as a CSS `rgb(...)` string
+
+### `useImageEdgeColor(imageUrl, fallback?): string`
+Exported React hook that wraps `extractEdgeColor` with async image loading:
+- Sets `crossOrigin="anonymous"` for canvas pixel access on CDN-hosted images
+- Cancels stale updates via cleanup flag on unmount or URL change
+- Falls back to the provided color (default `#000000`) on load error or missing URL
+
+## Usage Example
+
+```typescript
+import { useImageEdgeColor } from './use-image-edge-color';
+
+function ProductImage({ src }: { src: string }) {
+  const bgColor = useImageEdgeColor(src, '#1a1a1a');
+
+  return (
+    <div style={{ backgroundColor: bgColor, padding: '1rem' }}>
+      <img
+        src={src}
+        style={{ objectFit: 'contain', width: '100%', height: '300px' }}
+        alt="Product"
+      />
+    </div>
+  );
+}
+```
+
+## Notes
+
+- **CORS requirement:** The image server must return CORS headers. Supabase, Cloudflare Images, and the Flamingo image proxy all support this. If CORS fails, `onerror` fires and the fallback color is used.
+- **Why bucketing vs. averaging:** Simple pixel averaging produces muddy mid-tones when edges contain distinct color regions (e.g., blue sky above tan sand). Bucketing picks the *dominant* region instead.

package/src/hooks/ui/.use-media-query.md

@@ -1,40 +1,48 @@
-<!-- source-hash: ad8be7d69a54d22da2cee837d13753b7 -->
-A React hook for detecting CSS media query matches with SSR-safe hydration handling. Returns `undefined` during server-side rendering and initial client-side render to prevent hydration mismatches.
+<!-- source-hash: 658ce45ffa6bcde5f5bc895ea6b0b28a -->
+React hook for responsive design that detects whether a CSS media query matches the current viewport, returning `undefined` during SSR to avoid hydration mismatches.
 
 ## Key Components
 
-- **`useMediaQuery(query: string)`** - Core hook that accepts any CSS media query string and returns match status
-- **`breakpoints`** - Predefined Tailwind CSS-compatible breakpoint definitions (sm, md, lg, xl, 2xl)
-- **Convenience hooks** - `useSmUp()`, `useMdUp()`, `useLgUp()`, `useXlUp()`, `use2xlUp()` for common responsive breakpoints
+| Export | Type | Description |
+|--------|------|-------------|
+| `useMediaQuery` | Hook | Core hook accepting any CSS media query string |
+| `breakpoints` | Object | Predefined breakpoints: `md` (800px), `lg` (1280px) |
+| `useMdUp` | Hook | Returns `true` when viewport ≥ 800px |
+| `useLgUp` | Hook | Returns `true` when viewport ≥ 1280px |
+| `useSmUp` | Hook | ⚠️ Deprecated — alias for `useMdUp` |
 
 ## Usage Example
 
 ```typescript
-import { useMediaQuery, useMdUp, breakpoints } from './use-media-query'
-
-function ResponsiveComponent() {
-  // Custom media query
-  const isDarkMode = useMediaQuery('(prefers-color-scheme: dark)')
-  
-  // Predefined breakpoint
-  const isMdUp = useMdUp()
-  
-  // Custom breakpoint
-  const isWide = useMediaQuery('(min-width: 1400px)')
-
-  // Handle undefined state during SSR/hydration
-  if (isDarkMode === undefined || isMdUp === undefined) {
-    return <div>Loading...</div>
-  }
+import { useMediaQuery, useMdUp, useLgUp, breakpoints } from "./use-media-query"
+
+// Custom query
+function Component() {
+  const isPortrait = useMediaQuery("(orientation: portrait)")
+
+  // Returns undefined on first render (SSR-safe)
+  if (isPortrait === undefined) return <Skeleton />
+  return <div>{isPortrait ? "Portrait" : "Landscape"}</div>
+}
+
+// Predefined breakpoints
+function ResponsiveLayout() {
+  const isMd = useMdUp()  // >= 800px
+  const isLg = useLgUp()  // >= 1280px
 
   return (
     <div>
-      <p>Dark mode: {isDarkMode ? 'Yes' : 'No'}</p>
-      <p>Medium screen or larger: {isMdUp ? 'Yes' : 'No'}</p>
-      <p>Wide screen: {isWide ? 'Yes' : 'No'}</p>
+      {isLg ? <DesktopNav /> : isMd ? <TabletNav /> : <MobileNav />}
     </div>
   )
 }
+
+// Using breakpoints object directly
+const isDesktop = useMediaQuery(breakpoints.lg)
 ```
 
-The hook uses `useLayoutEffect` to avoid visual flicker and properly cleans up event listeners to prevent memory leaks.
+## Notes
+
+- Returns `undefined` during SSR and initial render — always guard against this before conditionally rendering UI
+- Uses `useLayoutEffect` to synchronously read the media query state before paint, preventing layout flicker
+- Automatically cleans up the `change` event listener on unmount

package/src/hooks/ui/.use-search.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 8ccc6891a2b3966ffa91a4330f0065e9 -->
+Generic React hook for managing debounced async search state, including loading, error handling, and result mapping.
+
+## Key Components
+
+### `UseSearchConfig<T>`
+Configuration interface for the hook:
+- `searchFn` — async function that receives the query string and returns raw results
+- `mapResult` — transforms each raw result into a `SearchResult`
+- `debounceMs` — debounce delay in milliseconds (default: `300`)
+- `minQueryLength` — minimum characters before triggering a search (default: `2`)
+
+### `UseSearchReturn`
+Return shape exposing:
+- `query` / `setQuery` — controlled input state
+- `results` — mapped `SearchResult[]`
+- `isLoading` — `true` while the async search is in flight
+- `error` — error message string or `null`
+- `clearResults` — resets results and error state
+
+### `useSearch<T>(config)`
+Core hook that orchestrates debouncing via `useDebounce`, fires `searchFn` when the debounced query meets `minQueryLength`, and cancels stale in-flight requests via a `cancelled` flag on cleanup.
+
+## Usage Example
+
+```typescript
+import { useSearch } from "@/hooks/use-search"
+import type { Device } from "@/types"
+
+const { query, setQuery, results, isLoading, error } = useSearch<Device>({
+  searchFn: async (q) => await api.devices.search(q),
+  mapResult: (device) => ({
+    id: device.id,
+    label: device.hostname,
+    description: device.ipAddress,
+  }),
+  debounceMs: 400,
+  minQueryLength: 3,
+})
+
+// Bind to an input
+<SearchInput
+  value={query}
+  onChange={setQuery}
+  results={results}
+  loading={isLoading}
+  error={error}
+/>
+```
+
+> Stale request cancellation is handled automatically — if the query changes before a previous search resolves, its result is silently discarded.

package/src/nats/.nats.md

@@ -1,51 +1,72 @@
-<!-- source-hash: c85909ba81ed8077d3a889ff6145d073 -->
-A WebSocket-based NATS client wrapper that provides type-safe publish, subscribe, and request-reply messaging patterns for browser and Tauri environments. Built on top of the `nats.ws` library with automatic codec handling for bytes, strings, and JSON payloads.
+<!-- source-hash: 418321f518535eef27f0004848e1e1b3 -->
+A browser/Tauri-only NATS client factory for WebSocket-based NATS connections (`nats.ws`), providing typed pub/sub, request/reply, JetStream ordered consumer subscriptions, and connection lifecycle management.
 
 ## Key Components
 
-- **`createNatsClient(options)`** - Factory function that creates a NATS client instance
-- **`NatsClient`** - Main interface providing connection management and messaging operations
-- **`NatsClientOptions`** - Configuration interface for server URLs, authentication, and connection behavior
-- **Message Publishing** - `publishBytes()`, `publishString()`, `publishJson()` methods for fire-and-forget messaging
-- **Request-Reply** - `requestBytes()`, `requestString()`, `requestJson()` methods for synchronous communication
-- **Subscriptions** - `subscribeBytes()`, `subscribeString()`, `subscribeJson()` methods with queue groups and auto-unsubscribe
-- **Status Monitoring** - `onStatus()` method for connection state changes and error handling
+### Interfaces & Types
+| Export | Description |
+|--------|-------------|
+| `NatsClient` | Core client interface with all pub/sub/request/JetStream methods |
+| `NatsClientOptions` | Connection config: servers, auth, reconnect, exponential backoff, ping |
+| `NatsSubscribeOptions` | Per-subscription options: queue group, max messages, abort signal |
+| `NatsPublishOptions` / `NatsRequestOptions` | Optional headers and timeout per operation |
+| `JetStreamOrderedSubscribeOptions` | JetStream ephemeral consumer config: stream, filter, deliver policy, start sequence |
+| `NatsStatus` / `NatsStatusEvent` | Connection state machine: `connecting`, `connected`, `disconnected`, `reconnecting`, `closed`, `error` |
+
+### Factory Function
+- **`createNatsClient(options)`** — Returns a `NatsClient` instance. Lazily imports `nats.ws` (browser-safe). All methods are lazy-connected and browser-only (throws if `window` is undefined).
+
+### Internal Helpers
+- **`createExponentialBackoffHandler`** — Configurable exponential backoff with optional crypto jitter for reconnect delays.
+- **`toNatsHeaders`** — Converts `Record<string, string>` or native `NatsHeaders` into a `nats.ws` headers object.
+- **`mapNatsTypeToStatus`** — Normalizes raw `nats.ws` status events to the typed `NatsStatus` union.
 
 ## Usage Example
 
 ```typescript
 import { createNatsClient } from './nats'
 
-// Create client with WebSocket connection
 const client = createNatsClient({
   servers: 'wss://nats.example.com:443',
-  name: 'my-app',
-  token: 'auth-token'
+  name: 'flamingo-ui',
+  token: 'my-token',
+  exponentialBackoff: {
+    initialDelayMs: 500,
+    maxDelayMs: 15_000,
+    multiplier: 2,
+    jitter: true,
+  },
+})
+
+// Listen for connection status changes
+const off = client.onStatus((event) => {
+  console.log('NATS status:', event.status)
 })
 
-// Connect and handle status
 await client.connect()
-client.onStatus(({ status }) => console.log('NATS status:', status))
 
-// Publish JSON message
-client.publishJson('user.created', { id: 123, name: 'Alice' })
+// Typed JSON publish
+client.publishJson('telemetry.events', { deviceId: 'abc', value: 42 })
 
-// Subscribe to messages with queue group
-const handle = client.subscribeJson<UserEvent>('user.*', 
-  (payload, msg) => {
-    console.log('Received:', payload, 'on subject:', msg.subject)
-  },
-  { queue: 'workers' }
+// Typed JSON request/reply
+const response = await client.requestJson<{ ok: boolean }>(
+  'devices.query',
+  { id: 'abc' },
+  { timeoutMs: 3000 },
 )
 
-// Request-reply pattern
-const response = await client.requestJson<UserResponse, UserRequest>(
-  'user.get', 
-  { userId: 123 },
-  { timeoutMs: 5000 }
+// JetStream ordered consumer (live-tail)
+const handle = await client.subscribeJetStreamOrdered(
+  (msg) => console.log('JetStream msg:', msg.seq),
+  {
+    streamName: 'EVENTS',
+    filterSubject: 'events.>',
+    deliverPolicy: 'new',
+  },
 )
 
-// Clean up
+// Cleanup
 handle.unsubscribe()
+off()
 await client.close()
 ```

package/src/nats/index.ts

@@ -1 +1,4 @@
 export * from './nats'
+export * from './shared-connection'
+export * from './nats-provider'
+export * from './use-nats-subscription'

package/src/nats/nats-provider.tsx

@@ -0,0 +1,146 @@
+'use client'
+
+import * as React from 'react'
+import type { NatsClient, NatsStatus } from './nats'
+import {
+  acquireClient,
+  releaseClient,
+  startConnectionLifecycle,
+  type AcquireClientOptions,
+  type NatsReconnectionBackoff,
+} from './shared-connection'
+
+export type { NatsReconnectionBackoff } from './shared-connection'
+
+export interface NatsProviderProps {
+  children: React.ReactNode
+  /** Return the current NATS WebSocket URL (or null when not yet available, e.g. unauthenticated). */
+  getWsUrl: () => string | null
+  /** Called before each reconnect attempt. */
+  onBeforeReconnect?: () => Promise<void> | void
+  clientConfig?: AcquireClientOptions
+  reconnectionBackoff?: NatsReconnectionBackoff
+  /**
+   * Bump this to force re-evaluating `getWsUrl()` (e.g. when auth state flips).
+   * Provider does not subscribe to external auth state by itself.
+   */
+  urlRevision?: unknown
+}
+
+export interface NatsContextValue {
+  client: NatsClient | null
+  status: NatsStatus
+  isReady: boolean
+  reconnectionCount: number
+}
+
+const NatsContext = React.createContext<NatsContextValue | null>(null)
+
+export function NatsProvider({
+  children,
+  getWsUrl,
+  onBeforeReconnect,
+  clientConfig,
+  reconnectionBackoff,
+  urlRevision,
+}: NatsProviderProps) {
+  const [client, setClient] = React.useState<NatsClient | null>(null)
+  const [status, setStatus] = React.useState<NatsStatus>('closed')
+  const [reconnectionCount, setReconnectionCount] = React.useState(0)
+
+  const getWsUrlRef = React.useRef(getWsUrl)
+  React.useEffect(() => {
+    getWsUrlRef.current = getWsUrl
+  }, [getWsUrl])
+
+  const onBeforeReconnectRef = React.useRef(onBeforeReconnect)
+  React.useEffect(() => {
+    onBeforeReconnectRef.current = onBeforeReconnect
+  }, [onBeforeReconnect])
+
+  const reconnectionBackoffRef = React.useRef(reconnectionBackoff)
+  React.useEffect(() => {
+    reconnectionBackoffRef.current = reconnectionBackoff
+  }, [reconnectionBackoff])
+
+  const clientConfigRef = React.useRef(clientConfig)
+  React.useEffect(() => {
+    clientConfigRef.current = clientConfig
+  }, [clientConfig])
+
+  const heldUrlRef = React.useRef<string | null>(null)
+  const hadConnectionBeforeRef = React.useRef(false)
+
+  React.useEffect(() => {
+    const wsUrl = getWsUrlRef.current()
+
+    if (!wsUrl) {
+      if (heldUrlRef.current) {
+        releaseClient(heldUrlRef.current)
+        heldUrlRef.current = null
+        setClient(null)
+        setStatus('closed')
+      }
+      return
+    }
+
+    if (heldUrlRef.current && heldUrlRef.current !== wsUrl) {
+      releaseClient(heldUrlRef.current)
+      heldUrlRef.current = null
+    }
+
+    const conn = acquireClient(wsUrl, clientConfigRef.current)
+    heldUrlRef.current = wsUrl
+    setClient(conn.client)
+    setStatus(conn.client.isConnected() ? 'connected' : 'connecting')
+
+    const lifecycle = startConnectionLifecycle({
+      conn,
+      wsUrl,
+      onBeforeReconnect: () => onBeforeReconnectRef.current?.(),
+      backoff: reconnectionBackoffRef.current,
+      getFreshUrl: () => getWsUrlRef.current(),
+      onStatusChange: (newStatus) => {
+        setStatus(newStatus)
+        if (newStatus === 'connected') {
+          if (hadConnectionBeforeRef.current) {
+            setReconnectionCount((c) => c + 1)
+          }
+          hadConnectionBeforeRef.current = true
+        }
+      },
+    })
+
+    return () => {
+      lifecycle.stop()
+      if (heldUrlRef.current) {
+        releaseClient(heldUrlRef.current)
+        heldUrlRef.current = null
+      }
+      setClient(null)
+      setStatus('closed')
+    }
+  }, [urlRevision])
+
+  const value = React.useMemo<NatsContextValue>(
+    () => ({
+      client,
+      status,
+      isReady: status === 'connected' && client !== null,
+      reconnectionCount,
+    }),
+    [client, status, reconnectionCount],
+  )
+
+  return <NatsContext.Provider value={value}>{children}</NatsContext.Provider>
+}
+
+export function useNats(): NatsContextValue {
+  const ctx = React.useContext(NatsContext)
+  if (!ctx) throw new Error('useNats must be used inside <NatsProvider>')
+  return ctx
+}
+
+export function useOptionalNats(): NatsContextValue | null {
+  return React.useContext(NatsContext)
+}

package/src/nats/nats.ts

@@ -9,6 +9,8 @@ import type {
   Subscription,
 } from 'nats.ws'
 
+export type { JsMsg, Msg, Subscription } from 'nats.ws'
+
 export type JetStreamDeliverPolicy = 'new' | 'byStartSequence'
 
 export interface JetStreamOrderedSubscribeOptions {