@appstrata/react 0.1.0

package/README.md

@@ -0,0 +1,863 @@
+# @appstrata/react
+
+React hooks for building digital signage apps with the AppStrata SDK. Provides a clean, reactive API on top of `@appstrata/core` and `@appstrata/web`.
+
+**Requires React 18 or later.**
+
+## Installation
+
+> **Note:** This is a private npm package. Requires an npm access token — contact the AppStrata team to get one, then add it to your `~/.npmrc`:
+>
+> ```
+> //registry.npmjs.org/:_authToken=YOUR_TOKEN
+> ```
+
+```bash
+npm install @appstrata/react @appstrata/web @appstrata/core
+```
+
+## Quick Start
+
+Wrap your app with `AppStrataProvider` and use hooks inside your components:
+
+```tsx
+import { createRoot } from "react-dom/client";
+import { AppStrataProvider, useAppContext, useLifecycle } from "@appstrata/react";
+
+function App() {
+  const context = useAppContext();
+
+  useLifecycle({
+    onStart: () => console.log("App started!"),
+    onStop: () => console.log("App stopped!"),
+  });
+
+  if (!context) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h1>{context.config.title as string}</h1>
+      <p>Playing on: {context.device.name}</p>
+    </div>
+  );
+}
+
+const root = createRoot(document.getElementById("root")!);
+root.render(
+  <AppStrataProvider>
+    <App />
+  </AppStrataProvider>
+);
+```
+
+---
+
+## API Reference
+
+### Provider
+
+#### `<AppStrataProvider>`
+
+Required wrapper for all AppStrata hooks. Initializes the player connection and manages context state.
+
+```tsx
+import { AppStrataProvider } from "@appstrata/react";
+
+root.render(
+  <AppStrataProvider>
+    <App />
+  </AppStrataProvider>
+);
+```
+
+**Props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Child components |
+| `player` | `SignagePlayer` (optional) | Custom player instance. Defaults to `getPlayer()` singleton from `@appstrata/web`. Useful for testing. |
+
+---
+
+### Core Hooks
+
+#### `useAppContext()`
+
+Access the complete `AppContext`. Re-renders on **any** context change. Returns `null` before the player initializes.
+
+```tsx
+function App() {
+  const context = useAppContext();
+  if (!context) return <div>Loading...</div>;
+
+  return (
+    <div style={{ width: context.viewportWidth, height: context.viewportHeight }}>
+      <h1>{context.config.title as string}</h1>
+      <p>Instance: {context.instanceId}</p>
+    </div>
+  );
+}
+```
+
+#### `useConfig<T>()`
+
+Access the app configuration object. Only re-renders when `config` actually changes (deep comparison).
+
+```tsx
+interface MyConfig {
+  title: string;
+  bgcolor: string;
+  refreshInterval: number;
+}
+
+function Header() {
+  const config = useConfig<MyConfig>();
+  if (!config) return null;
+
+  return (
+    <h1 style={{ background: config.bgcolor }}>
+      {config.title}
+    </h1>
+  );
+}
+```
+
+#### `useResources()`
+
+Access the resources array. Only re-renders when resources change (deep comparison).
+
+```tsx
+function ResourceLoader() {
+  const resources = useResources();
+  const [loaded, setLoaded] = useState(false);
+
+  useEffect(() => {
+    if (!resources) return;
+    setLoaded(false);
+    loadFonts(resources).then(() => setLoaded(true));
+  }, [resources]);
+
+  if (!loaded) return <div>Loading resources...</div>;
+  return null;
+}
+```
+
+Resources include fonts, images, and other assets configured in the CMS:
+
+```tsx
+function FontLoader() {
+  const resources = useResources();
+
+  useEffect(() => {
+    if (!resources) return;
+    const fonts = resources.filter(r => r.category === "font");
+    fonts.forEach(font => {
+      const link = document.createElement("link");
+      link.rel = "stylesheet";
+      link.href = font.source;
+      document.head.appendChild(link);
+    });
+  }, [resources]);
+
+  return null;
+}
+```
+
+#### `useDevice()`
+
+Access device information. Only re-renders when device info changes (deep comparison).
+
+```tsx
+function DeviceFooter() {
+  const device = useDevice();
+  if (!device) return null;
+
+  return (
+    <footer>
+      <p>Device: {device.name}</p>
+      <p>Timezone: {device.timezone}</p>
+      <p>Locale: {device.locale}</p>
+    </footer>
+  );
+}
+```
+
+#### `usePlayer()`
+
+Access the raw `SignagePlayer` instance for imperative operations.
+
+```tsx
+function CompletionButton() {
+  const player = usePlayer();
+
+  return (
+    <button onClick={() => player.notifyComplete()}>
+      Done
+    </button>
+  );
+}
+```
+
+#### `useCapability(capability)`
+
+Check if a capability is available. Returns a tri-state value:
+
+- `null` -- player hasn't initialized yet
+- `true` -- capability is supported
+- `false` -- capability is NOT supported
+
+```tsx
+function StorageStatus() {
+  const hasStorage = useCapability("storage");
+
+  if (hasStorage === null) return <span>Initializing...</span>;
+  if (hasStorage) return <span>Storage available</span>;
+  return <span>Storage not available</span>;
+}
+```
+
+Since `null` is falsy, simple boolean checks work naturally:
+
+```tsx
+const hasProxy = useCapability("proxy");
+if (hasProxy) {
+  // Only runs when initialized AND supported
+}
+```
+
+#### `useLifecycle(callbacks)`
+
+Subscribe to player lifecycle events. Your callbacks always see the latest state -- no need to memoize them with `useCallback`. Callbacks can optionally return a cleanup function that runs on unmount.
+
+```tsx
+function AnimatedWidget() {
+  useLifecycle({
+    onShow: () => {
+      console.log("Widget became visible");
+    },
+    onStart: () => {
+      console.log("Starting animations");
+      startAnimations();
+      return () => {
+        // Cleanup: called on unmount
+        stopAnimations();
+      };
+    },
+    onHide: () => {
+      console.log("Widget hidden");
+    },
+    onStop: () => {
+      console.log("Widget stopped");
+    },
+  });
+
+  return <div className="animated-content">...</div>;
+}
+```
+
+**Transient phases (`onShow` / `onHide`):** Because `useLifecycle` registers handlers inside a `useEffect` (which runs after paint), handlers for transient phases like `Show` and `Hide` may not fire if the phase has already passed by the time the effect runs. This commonly happens after HMR updates — the component re-mounts while the lifecycle is already in the `Start` phase, so the late subscriber for `onShow` doesn't fire (only `onStart` does, since that's the current phase).
+
+For work that must not be skipped, use `onStart` / `onStop` instead. Alternatively, use `useLifecyclePhase()` to derive visibility state from the current phase:
+
+```tsx
+const phase = useLifecyclePhase();
+const isVisible = phase === LifecyclePhase.Show || phase === LifecyclePhase.Start;
+```
+
+---
+
+### Granular Re-Render Optimization
+
+The core context hooks (`useConfig`, `useResources`, `useDevice`) use deep comparison internally. Each hook subscribes to its own slice of the context store, so a component only re-renders when the data it actually uses has changed -- even if the player sends a completely new context object.
+
+For best results, put each granular hook in its own component:
+
+```tsx
+function OptimizedApp() {
+  return (
+    <div>
+      <Header />
+      <DeviceFooter />
+      <ResourceLoader />
+    </div>
+  );
+}
+
+function Header() {
+  // Only re-renders when config changes
+  const config = useConfig<{ title: string; bgcolor: string }>();
+  if (!config) return null;
+  return <h1 style={{ background: config.bgcolor }}>{config.title}</h1>;
+}
+```
+
+---
+
+### Data-Fetching Hooks
+
+All data-fetching hooks share a common pattern:
+
+- They wait for the player to initialize before fetching
+- They return a `loading` flag (`true` before init and during fetch)
+- They return a `supported` tri-state (`null | boolean`)
+- They support an optional `fallback` for when the capability is unsupported
+- Pass `url: null` (or `key: null`) to skip fetching
+
+#### `useProxy<T>(url, options?)`
+
+Fetch data through the player's HTTP proxy with caching support.
+
+**Basic usage:**
+
+```tsx
+interface WeatherData {
+  temperature: number;
+  condition: string;
+}
+
+function WeatherWidget() {
+  const { data, loading, error } = useProxy<WeatherData>(
+    "https://api.weather.com/current?city=NYC"
+  );
+
+  if (loading) return <div>Loading weather...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!data) return null;
+
+  return <div>{data.temperature}F - {data.condition}</div>;
+}
+```
+
+**With full options (method, headers, body, cache):**
+
+```tsx
+const { data } = useProxy<SearchResult[]>(
+  "https://api.example.com/search",
+  {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ query: searchTerm }),
+    cache: { maxAge: 60 },
+  }
+);
+```
+
+**With fallback for unsupported players:**
+
+```tsx
+const { data, loading } = useProxy<WeatherData>(
+  "https://api.weather.com/current",
+  {
+    cache: { maxAge: 300 },
+    fallback: (req) =>
+      fetch(req.url, {
+        method: req.method,
+        headers: req.headers,
+        body: req.body,
+      }).then(r => r.json()),
+  }
+);
+// Works on all players -- uses proxy when available, falls back to direct fetch
+```
+
+**Conditional fetching:**
+
+```tsx
+const config = useConfig<{ lat: number; lon: number }>();
+
+// Only fetch when config is available
+const { data } = useProxy<WeatherData>(
+  config ? `https://api.weather.com/current?lat=${config.lat}&lon=${config.lon}` : null
+);
+```
+
+**Manual refetch:**
+
+```tsx
+const { data, refetch } = useProxy<StockData>("https://api.stocks.com/AAPL");
+
+return (
+  <div>
+    <p>Price: {data?.price}</p>
+    <button onClick={refetch}>Refresh</button>
+  </div>
+);
+```
+
+**Return type:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `data` | `T \| null` | Parsed response data |
+| `loading` | `boolean` | Whether a fetch is in progress (or waiting for init) |
+| `error` | `Error \| null` | Error from the last fetch attempt |
+| `supported` | `boolean \| null` | Proxy capability status |
+| `refetch` | `() => Promise<void>` | Manually trigger a refetch |
+
+---
+
+#### `useStorage(key, defaultValue?, options?)`  -- Single-Key Mode
+
+Reactive storage for a single key. Auto-loads the value after init and manages loading state.
+
+**Basic usage:**
+
+```tsx
+function ThemeSelector() {
+  const { value: theme, loading, set } = useStorage<string>("theme", "light");
+
+  if (loading) return <div>Loading...</div>;
+
+  return (
+    <div className={`theme-${theme}`}>
+      <button onClick={() => set("dark")}>Dark</button>
+      <button onClick={() => set("light")}>Light</button>
+    </div>
+  );
+}
+```
+
+**With fallback to localStorage:**
+
+```tsx
+const { value, set, remove } = useStorage<string>("theme", "dark", {
+  fallback: {
+    get: (key) => JSON.parse(localStorage.getItem(key) ?? "undefined"),
+    set: (key, val) => localStorage.setItem(key, JSON.stringify(val)),
+    remove: (key) => localStorage.removeItem(key),
+  },
+});
+// Works on all players -- uses player storage when available, localStorage otherwise
+```
+
+**Persisting slideshow position:**
+
+```tsx
+function SlideshowApp() {
+  const { value: currentSlide, loading, set: saveSlide } = useStorage<number>(
+    "currentSlide",
+    0, // Start at slide 0 by default
+  );
+
+  useLifecycle({
+    onStop: () => {
+      if (currentSlide !== undefined) saveSlide(currentSlide);
+    },
+  });
+
+  if (loading) return <div>Loading...</div>;
+  return <Slide index={currentSlide ?? 0} />;
+}
+```
+
+**Return type (single-key):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `value` | `T \| undefined` | Current value (defaultValue while loading) |
+| `loading` | `boolean` | Whether the initial load is in progress |
+| `supported` | `boolean \| null` | Storage capability status |
+| `set` | `(value: T) => Promise<void>` | Update the value |
+| `remove` | `() => Promise<void>` | Remove the key (resets to defaultValue) |
+
+---
+
+#### `useStorage(options?)` -- Full API Mode
+
+Imperative access to all storage operations. No auto-loading -- you call the methods yourself.
+
+```tsx
+function StorageManager() {
+  const { get, set, remove, list, clear, supported } = useStorage();
+
+  const handleExport = async () => {
+    const keys = await list();
+    const data: Record<string, unknown> = {};
+    for (const key of keys) {
+      data[key] = await get(key);
+    }
+    console.log("All storage:", data);
+  };
+
+  const handleClearAll = async () => {
+    await clear();
+    console.log("Storage cleared");
+  };
+
+  return (
+    <div>
+      <button onClick={handleExport}>Export Data</button>
+      <button onClick={handleClearAll}>Clear All</button>
+    </div>
+  );
+}
+```
+
+**With fallback adapter:**
+
+```tsx
+const { get, set, list, clear } = useStorage({
+  fallback: {
+    get: (key) => JSON.parse(localStorage.getItem(key) ?? "undefined"),
+    set: (key, val) => localStorage.setItem(key, JSON.stringify(val)),
+    remove: (key) => localStorage.removeItem(key),
+    list: () => Object.keys(localStorage),
+    clear: () => localStorage.clear(),
+  },
+});
+```
+
+**Return type (full API):**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `supported` | `boolean \| null` | Storage capability status |
+| `get` | `<T>(key: string) => Promise<T \| undefined>` | Get a value |
+| `set` | `(key: string, value: unknown) => Promise<void>` | Set a value |
+| `remove` | `(key: string) => Promise<void>` | Remove a key |
+| `list` | `() => Promise<string[]>` | List all keys |
+| `clear` | `() => Promise<void>` | Clear all storage |
+
+---
+
+#### `useMediaCache(url, options?)`
+
+Download and cache media files. Returns a `file` object with a `localPath` that is always usable.
+
+**Basic usage (works everywhere):**
+
+```tsx
+function HeroVideo() {
+  const { file, loading } = useMediaCache("https://example.com/hero.mp4");
+
+  if (loading) return <div>Downloading...</div>;
+  if (!file) return null;
+
+  // file.localPath is always usable:
+  // - When supported: points to local cached file
+  // - When unsupported: auto-passthrough to the original URL
+  return <video src={file.localPath} autoPlay loop />;
+}
+```
+
+**With custom fallback:**
+
+```tsx
+const { file, loading } = useMediaCache("https://example.com/hero.mp4", {
+  fallback: async (url) => ({
+    md5: "",
+    localPath: url, // Use original URL
+    fileName: "hero.mp4",
+    size: 0,
+    status: "cached" as const,
+  }),
+});
+```
+
+**Conditional download:**
+
+```tsx
+const config = useConfig<{ videoUrl?: string }>();
+
+const { file, loading, error } = useMediaCache(config?.videoUrl ?? null);
+```
+
+**Manual re-download:**
+
+```tsx
+const { file, refetch } = useMediaCache("https://example.com/data.json");
+
+return (
+  <div>
+    {file && <pre>{file.localPath}</pre>}
+    <button onClick={refetch}>Re-download</button>
+  </div>
+);
+```
+
+**Return type:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `file` | `MediaFile \| null` | Cached file info (with usable `localPath`) |
+| `loading` | `boolean` | Whether a download is in progress |
+| `error` | `Error \| null` | Error from the last download attempt |
+| `supported` | `boolean \| null` | MediaCache capability status |
+| `refetch` | `() => Promise<void>` | Manually trigger a re-download |
+
+---
+
+### Convenience Hooks
+
+#### `useStatic()`
+
+Control static/semi-static rendering optimization. All methods are safe no-ops when the capability is unsupported.
+
+```tsx
+function StaticContent() {
+  const config = useConfig<{ content: string; enableAnimations: boolean }>();
+  const { markStatic, markSemiStatic, disableStatic } = useStatic();
+
+  useEffect(() => {
+    if (!config) return;
+
+    if (config.enableAnimations) {
+      disableStatic(); // Dynamic content, no screenshot optimization
+    } else {
+      markStatic(); // Content is static, player can take a screenshot
+    }
+  }, [config]);
+
+  if (!config) return <div>Loading...</div>;
+  return <div>{config.content}</div>;
+}
+```
+
+**Semi-static content (refreshes periodically):**
+
+```tsx
+function ClockWidget() {
+  const { markSemiStatic } = useStatic();
+
+  useEffect(() => {
+    markSemiStatic(60); // Refresh screenshot every 60 seconds
+  }, []);
+
+  return <div>{new Date().toLocaleTimeString()}</div>;
+}
+```
+
+**Return type:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `supported` | `boolean \| null` | Static capability status |
+| `markStatic` | `() => void` | Signal that content is ready for static capture |
+| `markSemiStatic` | `(refreshIntervalSeconds: number) => void` | Signal semi-static with refresh interval |
+| `disableStatic` | `() => void` | Disable static mode |
+
+---
+
+#### `useInteraction(handler)`
+
+Subscribe to hardware interaction events (buttons, remote controls, sensors). Auto-subscribes on mount, auto-unsubscribes on unmount. No-op when unsupported.
+
+```tsx
+function InteractiveMenu() {
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  const { supported } = useInteraction((event) => {
+    if (event.type === "key") {
+      if (event.key === "up") setSelectedIndex(i => Math.max(0, i - 1));
+      if (event.key === "down") setSelectedIndex(i => i + 1);
+      if (event.key === "enter") handleSelect(selectedIndex);
+    }
+  });
+
+  return (
+    <div>
+      <Menu selectedIndex={selectedIndex} />
+      {!supported && <p>Touch/click to navigate</p>}
+    </div>
+  );
+}
+```
+
+**Return type:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `supported` | `boolean \| null` | Interaction capability status |
+
+---
+
+## Capabilities
+
+The AppStrata SDK defines optional capabilities that a player may or may not support:
+
+| Capability | Hook | Description |
+|------------|------|-------------|
+| `storage` | `useStorage()` | Key-value persistent storage |
+| `proxy` | `useProxy()` | HTTP proxy with caching |
+| `mediaCache` | `useMediaCache()` | Media file download and caching |
+| `static` | `useStatic()` | Static/semi-static rendering optimization |
+| `interaction` | `useInteraction()` | Hardware buttons, remote controls, sensors |
+
+All capability hooks handle unsupported scenarios gracefully:
+
+- **`useProxy`** and **`useStorage`**: Accept a `fallback` option for custom alternative logic
+- **`useMediaCache`**: Auto-passthrough (uses original URL as `localPath`) when unsupported
+- **`useStatic`**: Methods become safe no-ops
+- **`useInteraction`**: Silently does nothing
+
+---
+
+## The `supported` Tri-State
+
+All capability hooks return a `supported` field with type `boolean | null`:
+
+| Value | Meaning |
+|-------|---------|
+| `null` | Player hasn't initialized yet (waiting for READY message) |
+| `true` | Initialized and capability is supported |
+| `false` | Initialized and capability is NOT supported |
+
+**For most apps, you don't need to check `supported` at all.** The hooks handle initialization and fallback internally. The `loading` flag is your universal gate:
+
+```tsx
+const { data, loading } = useProxy<MyData>("https://api.example.com/data", {
+  fallback: (req) => fetch(req.url).then(r => r.json()),
+});
+
+if (loading) return <Spinner />;
+return <Display data={data} />;
+```
+
+The tri-state is available for power users who need to distinguish "not yet initialized" from "genuinely unsupported."
+
+---
+
+## Complete Example
+
+```tsx
+import {
+  AppStrataProvider,
+  useAppContext,
+  useConfig,
+  useDevice,
+  useResources,
+  useLifecycle,
+  useProxy,
+  useStorage,
+  useMediaCache,
+  useStatic,
+} from "@appstrata/react";
+
+interface AppConfig {
+  title: string;
+  bgcolor: string;
+  apiUrl: string;
+  heroVideo: string;
+}
+
+function App() {
+  const context = useAppContext();
+
+  useLifecycle({
+    onStart: () => console.log("App started"),
+    onStop: () => console.log("App stopped"),
+  });
+
+  if (!context) return <div className="loading">Initializing...</div>;
+
+  return (
+    <div className="app">
+      <Header />
+      <Content />
+      <Footer />
+    </div>
+  );
+}
+
+function Header() {
+  const config = useConfig<AppConfig>();
+  if (!config) return null;
+
+  return (
+    <header style={{ background: config.bgcolor }}>
+      <h1>{config.title}</h1>
+    </header>
+  );
+}
+
+function Content() {
+  const config = useConfig<AppConfig>();
+
+  // Fetch API data with fallback
+  const { data, loading: apiLoading } = useProxy<{ items: string[] }>(
+    config?.apiUrl ?? null,
+    {
+      cache: { maxAge: 300 },
+      fallback: (req) => fetch(req.url).then(r => r.json()),
+    }
+  );
+
+  // Cache hero video locally
+  const { file: heroFile, loading: videoLoading } = useMediaCache(
+    config?.heroVideo ?? null
+  );
+
+  // Persist scroll position
+  const { value: scrollPos, set: saveScroll } = useStorage<number>("scrollPos", 0);
+
+  // Mark as semi-static (refresh every 5 minutes)
+  const { markSemiStatic } = useStatic();
+  useEffect(() => { markSemiStatic(300); }, []);
+
+  if (apiLoading || videoLoading) return <div>Loading content...</div>;
+
+  return (
+    <div>
+      {heroFile && <video src={heroFile.localPath} autoPlay loop muted />}
+      <ul>
+        {data?.items.map((item, i) => <li key={i}>{item}</li>)}
+      </ul>
+    </div>
+  );
+}
+
+function Footer() {
+  const device = useDevice();
+  const resources = useResources();
+
+  return (
+    <footer>
+      {device && <span>Playing on: {device.name}</span>}
+      {resources && <span>{resources.length} resources loaded</span>}
+    </footer>
+  );
+}
+
+// Entry point
+const root = createRoot(document.getElementById("root")!);
+root.render(
+  <AppStrataProvider>
+    <App />
+  </AppStrataProvider>
+);
+```
+
+---
+
+## Testing
+
+The `AppStrataProvider` accepts an optional `player` prop, making it easy to inject a mock player for testing:
+
+```tsx
+import { AppStrataProvider } from "@appstrata/react";
+import { renderHook, act } from "@testing-library/react";
+
+const mockPlayer = createMockPlayer(); // Your mock implementation
+
+function wrapper({ children }) {
+  return (
+    <AppStrataProvider player={mockPlayer}>
+      {children}
+    </AppStrataProvider>
+  );
+}
+
+const { result } = renderHook(() => useConfig(), { wrapper });
+act(() => simulateInit(mockPlayer));
+expect(result.current).toEqual({ title: "Test" });
+```
+
+---
+
+## Peer Dependencies
+
+- `react` >= 18
+
+## License
+
+MIT