@appstrata/react 0.1.0

package/dist/use-static.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-static.d.ts","sourceRoot":"","sources":["../src/use-static.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uFAAuF;IACvF,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,kDAAkD;IAClD,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,+CAA+C;IAC/C,cAAc,EAAE,CAAC,sBAAsB,EAAE,MAAM,KAAK,IAAI,CAAC;IACzD,0BAA0B;IAC1B,aAAa,EAAE,MAAM,IAAI,CAAC;CAC3B;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,IAAI,eAAe,CAmB3C"}

package/dist/use-static.js

@@ -0,0 +1,45 @@
+/**
+ * useStatic - React hook for the AppStrata Static API.
+ *
+ * Convenience hook that returns capability-checked methods.
+ * All methods are safe no-ops if the "static" capability is unsupported.
+ */
+import { useMemo } from "react";
+import { usePlayer, useCapability } from "./hooks.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// HOOK
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Access the Static API with safe no-op methods when unsupported.
+ *
+ * Eliminates the need for `player.static?.markStatic()` optional chaining.
+ *
+ * @example
+ * ```tsx
+ * const { markStatic, markSemiStatic, supported } = useStatic();
+ *
+ * useEffect(() => {
+ *   if (isStaticContent) markStatic();
+ *   else markSemiStatic(3600); // refresh hourly
+ * }, [isStaticContent]);
+ * ```
+ */
+export function useStatic() {
+    const player = usePlayer();
+    const supported = useCapability("static");
+    return useMemo(() => ({
+        supported,
+        markStatic: () => {
+            if (supported)
+                player.static?.markStatic();
+        },
+        markSemiStatic: (refreshIntervalSeconds) => {
+            if (supported)
+                player.static?.markSemiStatic(refreshIntervalSeconds);
+        },
+        disableStatic: () => {
+            if (supported)
+                player.static?.disableStatic();
+        },
+    }), [supported, player]);
+}

package/dist/use-storage.d.ts

@@ -0,0 +1,72 @@
+/**
+ * useStorage - React hook for the AppStrata Storage API.
+ *
+ * Two calling modes:
+ * 1. Single-key mode: useStorage(key, defaultValue?, options?)
+ *    - Reactive: auto-loads value, manages loading state
+ * 2. Full API mode: useStorage(options?)
+ *    - Imperative: returns capability-checked methods, no auto-loading
+ */
+/**
+ * Fallback storage adapter for when the "storage" capability is unsupported.
+ * Implement these methods to route reads/writes through an alternative
+ * storage mechanism (e.g., localStorage).
+ */
+export interface StorageFallbackAdapter {
+    get: (key: string) => unknown;
+    set: (key: string, value: unknown) => void;
+    remove: (key: string) => void;
+    /** Only needed for full API mode */
+    list?: () => string[];
+    /** Only needed for full API mode */
+    clear?: () => void;
+}
+/**
+ * Options for useStorage (both modes).
+ */
+export interface UseStorageOptions {
+    fallback?: StorageFallbackAdapter;
+}
+/**
+ * Return type for single-key mode.
+ */
+export interface UseStorageKeyResult<T> {
+    /** Current value (defaultValue while loading or if unsupported without fallback) */
+    value: T | undefined;
+    /** Whether the initial load is in progress */
+    loading: boolean;
+    /** Whether the player supports the "storage" capability (null = not yet initialized) */
+    supported: boolean | null;
+    /** Set the value for this key */
+    set: (value: T) => Promise<void>;
+    /** Remove this key */
+    remove: () => Promise<void>;
+}
+/**
+ * Return type for full API mode.
+ */
+export interface UseStorageFullResult {
+    /** Whether the player supports the "storage" capability (null = not yet initialized) */
+    supported: boolean | null;
+    /** Get a value by key */
+    get: <T = unknown>(key: string) => Promise<T | undefined>;
+    /** Set a value for any key */
+    set: (key: string, value: unknown) => Promise<void>;
+    /** Remove a key */
+    remove: (key: string) => Promise<void>;
+    /** List all keys */
+    list: () => Promise<string[]>;
+    /** Clear all storage */
+    clear: () => Promise<void>;
+}
+/** Single-key mode with default value and options */
+export declare function useStorage<T = unknown>(key: string, defaultValue: T, options?: UseStorageOptions): UseStorageKeyResult<T>;
+/** Single-key mode with options (no default value) */
+export declare function useStorage<T = unknown>(key: string, options: UseStorageOptions): UseStorageKeyResult<T>;
+/** Single-key mode with just key */
+export declare function useStorage<T = unknown>(key: string): UseStorageKeyResult<T>;
+/** Full API mode with options */
+export declare function useStorage(options: UseStorageOptions): UseStorageFullResult;
+/** Full API mode without options */
+export declare function useStorage(): UseStorageFullResult;
+//# sourceMappingURL=use-storage.d.ts.map

package/dist/use-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-storage.d.ts","sourceRoot":"","sources":["../src/use-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAC9B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3C,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,MAAM,EAAE,CAAC;IACtB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,sBAAsB,CAAC;CACnC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,oFAAoF;IACpF,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;IACrB,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,iCAAiC;IACjC,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,sBAAsB;IACtB,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,wFAAwF;IACxF,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,yBAAyB;IACzB,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC1D,8BAA8B;IAC9B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,mBAAmB;IACnB,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,oBAAoB;IACpB,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9B,wBAAwB;IACxB,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAMD,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EACpC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,EACf,OAAO,CAAC,EAAE,iBAAiB,GAC1B,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAE1B,sDAAsD;AACtD,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EACpC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,iBAAiB,GACzB,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAE1B,oCAAoC;AACpC,wBAAgB,UAAU,CAAC,CAAC,GAAG,OAAO,EACpC,GAAG,EAAE,MAAM,GACV,mBAAmB,CAAC,CAAC,CAAC,CAAC;AAE1B,iCAAiC;AACjC,wBAAgB,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,oBAAoB,CAAC;AAE7E,oCAAoC;AACpC,wBAAgB,UAAU,IAAI,oBAAoB,CAAC"}

package/dist/use-storage.js

@@ -0,0 +1,161 @@
+/**
+ * useStorage - React hook for the AppStrata Storage API.
+ *
+ * Two calling modes:
+ * 1. Single-key mode: useStorage(key, defaultValue?, options?)
+ *    - Reactive: auto-loads value, manages loading state
+ * 2. Full API mode: useStorage(options?)
+ *    - Imperative: returns capability-checked methods, no auto-loading
+ */
+import { useState, useEffect, useCallback, useMemo, useRef } from "react";
+import { usePlayer, useCapability } from "./hooks.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// IMPLEMENTATION
+// ═══════════════════════════════════════════════════════════════════════════
+export function useStorage(keyOrOptions, defaultValueOrOptions, maybeOptions) {
+    // Parse arguments to determine mode
+    const isKeyMode = typeof keyOrOptions === "string";
+    if (isKeyMode) {
+        return useStorageKey(keyOrOptions, defaultValueOrOptions, maybeOptions);
+    }
+    else {
+        return useStorageFull(keyOrOptions);
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// SINGLE-KEY MODE
+// ═══════════════════════════════════════════════════════════════════════════
+function useStorageKey(key, defaultValueOrOptions, maybeOptions) {
+    // Parse second argument: could be defaultValue or options
+    let defaultValue;
+    let options;
+    if (defaultValueOrOptions !== undefined &&
+        typeof defaultValueOrOptions === "object" &&
+        defaultValueOrOptions !== null &&
+        "fallback" in defaultValueOrOptions) {
+        // Second arg is options (has fallback property)
+        options = defaultValueOrOptions;
+        defaultValue = undefined;
+    }
+    else {
+        defaultValue = defaultValueOrOptions;
+        options = maybeOptions;
+    }
+    const player = usePlayer();
+    const supported = useCapability("storage");
+    const fallback = options?.fallback;
+    const [value, setValue] = useState(defaultValue);
+    const [loading, setLoading] = useState(true);
+    // Keep key in a ref to avoid stale closures
+    const keyRef = useRef(key);
+    keyRef.current = key;
+    // Load initial value
+    useEffect(() => {
+        // Wait for player to initialize before resolving
+        if (supported === null)
+            return;
+        let cancelled = false;
+        async function load() {
+            if (supported && player.storage) {
+                const stored = await player.storage.get(key);
+                if (!cancelled) {
+                    setValue(stored !== undefined ? stored : defaultValue);
+                    setLoading(false);
+                }
+            }
+            else if (fallback) {
+                const stored = fallback.get(key);
+                if (!cancelled) {
+                    setValue(stored !== undefined ? stored : defaultValue);
+                    setLoading(false);
+                }
+            }
+            else {
+                // Genuinely unsupported, no fallback: just use defaultValue
+                if (!cancelled) {
+                    setValue(defaultValue);
+                    setLoading(false);
+                }
+            }
+        }
+        setLoading(true);
+        load();
+        return () => {
+            cancelled = true;
+        };
+    }, [key, supported, player, fallback, defaultValue]);
+    const set = useCallback(async (newValue) => {
+        if (supported && player.storage) {
+            await player.storage.set(keyRef.current, newValue);
+            setValue(newValue);
+        }
+        else if (fallback) {
+            fallback.set(keyRef.current, newValue);
+            setValue(newValue);
+        }
+        // Unsupported without fallback: no-op
+    }, [supported, player, fallback]);
+    const remove = useCallback(async () => {
+        if (supported && player.storage) {
+            await player.storage.remove(keyRef.current);
+            setValue(defaultValue);
+        }
+        else if (fallback) {
+            fallback.remove(keyRef.current);
+            setValue(defaultValue);
+        }
+        // Unsupported without fallback: no-op
+    }, [supported, player, fallback, defaultValue]);
+    return { value, loading, supported, set, remove };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// FULL API MODE
+// ═══════════════════════════════════════════════════════════════════════════
+function useStorageFull(options) {
+    const player = usePlayer();
+    const supported = useCapability("storage");
+    const fallback = options?.fallback;
+    const get = useCallback(async (key) => {
+        if (supported && player.storage) {
+            return player.storage.get(key);
+        }
+        if (fallback) {
+            return fallback.get(key);
+        }
+        return undefined;
+    }, [supported, player, fallback]);
+    const set = useCallback(async (key, value) => {
+        if (supported && player.storage) {
+            await player.storage.set(key, value);
+        }
+        else if (fallback) {
+            fallback.set(key, value);
+        }
+    }, [supported, player, fallback]);
+    const remove = useCallback(async (key) => {
+        if (supported && player.storage) {
+            await player.storage.remove(key);
+        }
+        else if (fallback) {
+            fallback.remove(key);
+        }
+    }, [supported, player, fallback]);
+    const list = useCallback(async () => {
+        if (supported && player.storage) {
+            return player.storage.list();
+        }
+        if (fallback?.list) {
+            return fallback.list();
+        }
+        return [];
+    }, [supported, player, fallback]);
+    const clear = useCallback(async () => {
+        if (supported && player.storage) {
+            await player.storage.clear();
+        }
+        else if (fallback?.clear) {
+            fallback.clear();
+        }
+    }, [supported, player, fallback]);
+    return useMemo(() => ({ supported, get, set, remove, list, clear }), [supported, get, set, remove, list, clear]);
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@appstrata/react",
+  "version": "0.1.0",
+  "description": "React hooks and components for AppStrata Digital Signage SDK",
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "digital-signage",
+    "appstrata",
+    "react",
+    "hooks",
+    "sdk"
+  ],
+  "author": "AppStrata Team",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "dependencies": {
+    "@appstrata/core": "0.1.0",
+    "@appstrata/utils": "0.1.0",
+    "@appstrata/web": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^18.3.28",
+    "@types/react-dom": "^18.3.7",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc --build tsconfig.build.json",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch"
+  }
+}