@wyndlass/app-sdk 0.0.0-stage → 1.0.0

package/dist/qr.js

@@ -0,0 +1,14 @@
+// QR codes for apps (WP-0101 decision 2: `@wyndlass/app-sdk/qr`), drawn without the network on qrcode-generator, as
+// the pairing screen's are. A subpath of its own, so an app that draws none bundles none of the encoder.
+import qrcode from "qrcode-generator";
+/**
+ * The QR code for `text`: its modules row by row, true where dark. Error correction M (15%: a screen seen at an angle,
+ * a smudge), the smallest version that holds it; byte mode, so any URL fits.
+ */
+export function qrModules(text) {
+    const code = qrcode(0, "M");
+    code.addData(text, "Byte");
+    code.make();
+    const n = code.getModuleCount();
+    return Array.from({ length: n }, (_, r) => Array.from({ length: n }, (_, c) => code.isDark(r, c)));
+}

package/dist/react.d.ts

@@ -0,0 +1,52 @@
+/**
+ * React apps (WP-0101 decision 4, `@wyndlass/app-sdk/react`): a component rendered in the app's shadow root, its element
+ * a WyndlassApp, with hooks for what the app is given. React is a peer dependency, bundled into the app by `pack`.
+ *
+ * What a component reaches is the element, through React's context, and a bridge to it kept in this module's scope, so
+ * React's tree (which hangs off the shadow root's nodes) holds nothing another app could use: data, images and the
+ * rest go through the SDK's functions, as for any app.
+ */
+import { type ComponentType } from "react";
+import type { DataAnswer, ScreenFacts } from "./contract/app-contract.js";
+type Params = Record<string, string | number | boolean>;
+/**
+ * An element class for a component, the module's default export: `export default reactApp(Board, { css })`. `css` is
+ * the app's styles, as a constructable stylesheet in its shadow root (a CSS file the source imports is text, for it).
+ */
+export declare function reactApp(Component: ComponentType, options?: {
+    css?: string;
+}): CustomElementConstructor;
+/**
+ * The app as a component reads it: its props with their defaults, ready() (once, within 5 s of its start), its time
+ * zone and locale, the screen's place and facts, and whether it is in the CMS's preview. None of it changes with time.
+ */
+export declare function useApp(): {
+    prop: <T>(name: string, fallback: T) => T;
+    ready: () => void;
+    timeZone: string;
+    locale: string;
+    place: {
+        lat: number;
+        lon: number;
+    } | undefined;
+    screen: ScreenFacts | null;
+    preview: boolean;
+};
+/** The layout's clock, drawn again at each of its frames: seeking and pausing show the right moment. */
+export declare function useNow(): number;
+/**
+ * Which of `count` pages shows now, each `ms` long from the layout's start, and the pages said to the host, so a layout
+ * can turn its enter and exit with them (ADR 0071, decision 5).
+ */
+export declare function usePaging(count: number, ms: number): number;
+/**
+ * A data source's answer (one the definition declares): the one the screen kept, at once, then the service's; asked
+ * again every `everyMs` and when the params change. `error` once an ask has failed with no answer to show.
+ */
+export declare function useData<T = unknown>(source: string, params: Params, everyMs?: number): {
+    answer?: DataAnswer<T>;
+    error?: Error;
+};
+/** A data table's snapshot (null without one), read again each frame the layout draws: a bound table's rows change with time. */
+export declare function useSnapshot(table: string): unknown | null;
+export {};

package/dist/react.js

@@ -0,0 +1,149 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+/**
+ * React apps (WP-0101 decision 4, `@wyndlass/app-sdk/react`): a component rendered in the app's shadow root, its element
+ * a WyndlassApp, with hooks for what the app is given. React is a peer dependency, bundled into the app by `pack`.
+ *
+ * What a component reaches is the element, through React's context, and a bridge to it kept in this module's scope, so
+ * React's tree (which hangs off the shadow root's nodes) holds nothing another app could use: data, images and the
+ * rest go through the SDK's functions, as for any app.
+ */
+import { createContext, createElement, useContext, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { createRoot } from "react-dom/client";
+import { contextOf, data, kept, snapshot, WyndlassApp } from "./index.js";
+const bridges = new WeakMap();
+const App = createContext(null);
+function useBridge() {
+    const app = useContext(App);
+    const bridge = app && bridges.get(app);
+    if (!app || !bridge)
+        throw new Error("a Wyndlass hook is used outside an app made by reactApp()");
+    return [app, bridge];
+}
+/**
+ * An element class for a component, the module's default export: `export default reactApp(Board, { css })`. `css` is
+ * the app's styles, as a constructable stylesheet in its shadow root (a CSS file the source imports is text, for it).
+ */
+export function reactApp(Component, options = {}) {
+    var _ReactApp_root, _ReactApp_listeners, _ReactApp_paging, _ReactApp_time, _a;
+    return _a = class ReactApp extends WyndlassApp {
+            constructor() {
+                super(...arguments);
+                _ReactApp_root.set(this, void 0);
+                _ReactApp_listeners.set(this, new Set());
+                _ReactApp_paging.set(this, null);
+                _ReactApp_time.set(this, 0);
+            }
+            mount() {
+                if (options.css)
+                    this.css(options.css);
+                __classPrivateFieldSet(this, _ReactApp_time, this.now(), "f");
+                bridges.set(this, {
+                    prop: (name, fallback) => this.prop(name, fallback),
+                    ready: () => this.ready(),
+                    time: () => __classPrivateFieldGet(this, _ReactApp_time, "f"),
+                    startedAt: () => this.startedAt(),
+                    timeZone: () => this.timeZone,
+                    locale: () => this.locale,
+                    subscribe: listener => { __classPrivateFieldGet(this, _ReactApp_listeners, "f").add(listener); return () => { __classPrivateFieldGet(this, _ReactApp_listeners, "f").delete(listener); }; },
+                    setPaging: paging => { __classPrivateFieldSet(this, _ReactApp_paging, paging, "f"); },
+                });
+                const host = document.createElement("div");
+                host.style.cssText = "width:100%;height:100%";
+                this.root.append(host);
+                __classPrivateFieldSet(this, _ReactApp_root, createRoot(host), "f");
+                __classPrivateFieldGet(this, _ReactApp_root, "f").render(createElement(App.Provider, { value: this }, createElement(Component)));
+            }
+            draw(epochMs) {
+                __classPrivateFieldSet(this, _ReactApp_time, epochMs, "f");
+                for (const listener of __classPrivateFieldGet(this, _ReactApp_listeners, "f"))
+                    listener();
+            }
+            paging() { return __classPrivateFieldGet(this, _ReactApp_paging, "f"); }
+            disconnectedCallback() {
+                super.disconnectedCallback();
+                // A box the layout takes away for good is not connected again: React lets the component go with it.
+                const root = __classPrivateFieldGet(this, _ReactApp_root, "f");
+                queueMicrotask(() => { if (!this.isConnected) {
+                    root?.unmount();
+                    __classPrivateFieldSet(this, _ReactApp_root, undefined, "f");
+                } });
+            }
+        },
+        _ReactApp_root = new WeakMap(),
+        _ReactApp_listeners = new WeakMap(),
+        _ReactApp_paging = new WeakMap(),
+        _ReactApp_time = new WeakMap(),
+        _a;
+}
+/**
+ * The app as a component reads it: its props with their defaults, ready() (once, within 5 s of its start), its time
+ * zone and locale, the screen's place and facts, and whether it is in the CMS's preview. None of it changes with time.
+ */
+export function useApp() {
+    const [app, bridge] = useBridge();
+    return useMemo(() => {
+        const context = contextOf(app);
+        return {
+            prop: (name, fallback) => bridge.prop(name, fallback),
+            ready: () => bridge.ready(),
+            timeZone: bridge.timeZone(),
+            locale: bridge.locale(),
+            place: context?.place,
+            screen: (context?.screen ?? null),
+            preview: !!context?.preview,
+        };
+    }, [app, bridge]);
+}
+/** The layout's clock, drawn again at each of its frames: seeking and pausing show the right moment. */
+export function useNow() {
+    const [, bridge] = useBridge();
+    return useSyncExternalStore(bridge.subscribe, bridge.time, bridge.time);
+}
+/**
+ * Which of `count` pages shows now, each `ms` long from the layout's start, and the pages said to the host, so a layout
+ * can turn its enter and exit with them (ADR 0071, decision 5).
+ */
+export function usePaging(count, ms) {
+    const [, bridge] = useBridge();
+    const now = useNow();
+    useEffect(() => { bridge.setPaging(count > 1 && ms > 0 ? { count, ms } : null); }, [bridge, count, ms]);
+    return count > 1 && ms > 0 ? Math.floor(Math.max(0, now - bridge.startedAt()) / ms) % count : 0;
+}
+/**
+ * A data source's answer (one the definition declares): the one the screen kept, at once, then the service's; asked
+ * again every `everyMs` and when the params change. `error` once an ask has failed with no answer to show.
+ */
+export function useData(source, params, everyMs = 10 * 60000) {
+    const [app] = useBridge();
+    const key = JSON.stringify([source, params]);
+    const [state, setState] = useState(() => ({ key, answer: kept(app, source, params) }));
+    useEffect(() => {
+        let live = true;
+        const ask = () => data(app, source, params).then(answer => { if (live)
+            setState({ key, answer }); }, error => { if (live)
+            setState(s => s.key === key && s.answer ? s : { key, error: error }); });
+        if (state.key !== key)
+            setState({ key, answer: kept(app, source, params) });
+        void ask();
+        const timer = setInterval(ask, everyMs);
+        return () => { live = false; clearInterval(timer); };
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- the params by value
+    }, [app, key, everyMs]);
+    return state.key === key ? { answer: state.answer, error: state.error } : { answer: kept(app, source, params) };
+}
+/** A data table's snapshot (null without one), read again each frame the layout draws: a bound table's rows change with time. */
+export function useSnapshot(table) {
+    const [app] = useBridge();
+    useNow();
+    return snapshot(app, table);
+}

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "@wyndlass/app-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Build apps for Wyndlass's screens: web components on the app contract (Player API 2), with the runtime Wyndlass's own apps use.",
+  "keywords": [
+    "wyndlass",
+    "digital-signage",
+    "signage",
+    "web-components"
+  ],
+  "license": "MIT",
+  "author": "Northwynd Labs LLC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NorthwyndLabs/wyndlass.git",
+    "directory": "app-sdk"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "wyndlass-app": "./cli/main.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./qr": {
+      "types": "./dist/qr.d.ts",
+      "import": "./dist/qr.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./app-definition.schema.json": "./protocol/app-definition.schema.json",
+    "./common.schema.json": "./protocol/common.schema.json"
+  },
+  "files": [
+    "dist",
+    "cli",
+    "templates",
+    "protocol",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "acorn": "8.19.0",
+    "ajv": "8.17.1",
+    "ajv-formats": "3.0.1",
+    "esbuild": "^0.28.2",
+    "qrcode-generator": "2.0.4"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "22",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "playwright-core": "1.63.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "tsx": "^4.23.15",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "copy-protocol": "node scripts/copy-protocol.mjs",
+    "typecheck": "tsc -p tsconfig.json && tsc -p preview/tsconfig.json",
+    "build": "node scripts/copy-protocol.mjs --check && tsc -p tsconfig.build.json && node scripts/build-preview.mjs",
+    "test": "pnpm build && node --import tsx --test --test-force-exit test/*.test.ts",
+    "check": "node scripts/copy-protocol.mjs --check && pnpm typecheck"
+  }
 }