@wyndlass/app-sdk 0.0.0-stage → 1.0.0

package/templates/vanilla/README.md

@@ -0,0 +1,22 @@
+# __APP_NAME__
+
+An app for Wyndlass's screens (`__APP_ID__`), built on [`@wyndlass/app-sdk`](https://www.npmjs.com/package/@wyndlass/app-sdk).
+
+- `app.json` is its definition: its id, version, name, element, params and the data it reads.
+- `src/app.ts` is its module: the element's class, the default export. `src/app.css` is its styles.
+
+## Commands
+
+- `npm run preview`: the app as screens run it, at http://127.0.0.1:5199/, drawn again as you change it. Its controls set the screen's size, the params, the clock, enter and exit, the time zone, the screen's facts and each data source's answer, and give the app tables from CSV or JSON, the people at the screen and the player's events where it uses them. `npm run preview -- --frame` runs it in the frame the CMS gives apps, where it has no storage.
+- `npm run check`: the checks Wyndlass makes when you import it.
+- `npm run pack`: `dist/__APP_ID__-<version>.zip`, the package to import, after the checks.
+- `npm run typecheck`: TypeScript's check.
+
+Import the package through the Wyndlass MCP (`app.prepareImport`, `npx wyndlass-app upload`, then `app.import`) or in the CMS (Content, Library, Import an app). A person who may approve media there reviews the app's first version, and any that asks for more than the one before it, before screens play it. Raise `version` in `app.json` for each new one.
+
+## What screens enforce
+
+- The time comes from `now()` (the `epochMs` `draw` is given), never `Date.now()`.
+- `ready()` within 5 s of the app's start.
+- No `localStorage` for anything that matters, and no secrets in params or the module: both are readable.
+- Data only from the sources `app.json` declares (`weather`, `news`, `image` or `calendar`), and the network hosts declared truthfully in `capabilities.network`: a person approves them.

package/templates/vanilla/app.json

@@ -0,0 +1,14 @@
+{
+  "id": "__APP_ID__",
+  "version": "0.1.0",
+  "name": "__APP_NAME__",
+  "element": "__ELEMENT__",
+  "description": "A heading and the time on one page, the weather on the next.",
+  "params": {
+    "heading": { "type": "string", "default": "Good morning", "label": "Heading" },
+    "accent": { "type": "color", "default": "#4f8cff", "label": "Accent" },
+    "units": { "type": "enum", "values": ["metric", "imperial"], "default": "metric", "label": "Units" },
+    "seconds": { "type": "boolean", "default": false, "label": "Show seconds" }
+  },
+  "data": ["weather"]
+}

package/templates/vanilla/gitignore

@@ -0,0 +1,2 @@
+node_modules/
+dist/

package/templates/vanilla/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "__PACKAGE__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "preview": "wyndlass-app preview",
+    "check": "wyndlass-app check",
+    "pack": "wyndlass-app pack",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@wyndlass/app-sdk": "__SDK__"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/templates/vanilla/src/app.css

@@ -0,0 +1,7 @@
+:host { display: block; width: 100%; height: 100%; color: #ffffff; font-family: system-ui, sans-serif; }
+.page { width: 100%; height: 100%; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: calc(var(--h) * .04); }
+.page[hidden] { display: none; }
+h1 { margin: 0; font-size: min(calc(var(--h) * .14), calc(var(--w) * .08)); font-weight: 600; color: var(--accent); }
+time { font-size: min(calc(var(--h) * .3), calc(var(--w) * .16)); font-variant-numeric: tabular-nums; }
+.temperature { font-size: min(calc(var(--h) * .3), calc(var(--w) * .16)); }
+.condition, .none { font-size: min(calc(var(--h) * .1), calc(var(--w) * .05)); opacity: .85; }

package/templates/vanilla/src/app.ts

@@ -0,0 +1,59 @@
+// __APP_NAME__: a heading and the time on one page, the weather on the next, built on Wyndlass's app SDK.
+// Everything it draws comes from the layout's clock (now()), so the designer's seek and pause show the right moment.
+import { WyndlassApp, color, contextOf, data, kept, type DataAnswer, type weather } from "@wyndlass/app-sdk";
+import css from "./app.css";
+
+/** How long each of the two pages shows. */
+const PAGE_MS = 8_000;
+/** How often the weather is asked for again. */
+const EVERY_MS = 10 * 60_000;
+
+export default class App extends WyndlassApp {
+  #pages: HTMLElement[] = [];
+  #heading!: HTMLElement;
+  #time!: HTMLElement;
+  #weather!: HTMLElement;
+  #answer?: DataAnswer<weather.Weather>;
+  #askedAt = -Infinity;
+  #format?: Intl.DateTimeFormat;
+
+  protected mount() {
+    this.css(css);
+    this.style.setProperty("--accent", color(this.prop("accent", "#4f8cff"), "#4f8cff"));
+    this.root.innerHTML = `<section class="page"><h1></h1><time></time></section><section class="page" hidden><div data-weather></div></section>`;
+    this.#pages = [...this.root.querySelectorAll<HTMLElement>(".page")];
+    this.#heading = this.root.querySelector("h1")!;
+    this.#time = this.root.querySelector("time")!;
+    this.#weather = this.root.querySelector("[data-weather]")!;
+    this.#heading.textContent = this.prop("heading", "Good morning");
+    this.#format = new Intl.DateTimeFormat(this.locale, { timeZone: this.timeZone, hour: "numeric", minute: "2-digit", ...(this.prop("seconds", false) ? { second: "2-digit" } : {}) });
+    // The answer the screen kept, at once: the app is ready without waiting for the network.
+    this.#answer = kept<weather.Weather>(this, "weather", this.#params());
+    if (this.#answer) this.ready();
+  }
+
+  /** The weather for the screen's place, or Winnipeg's where there is none (the designer's sample). */
+  #params() {
+    const place = contextOf(this)?.place ?? { lat: 49.9, lon: -97.14 };
+    return { lat: place.lat, lon: place.lon, units: this.prop("units", "metric") };
+  }
+
+  protected draw(epochMs: number) {
+    if (epochMs - this.#askedAt >= EVERY_MS) {
+      this.#askedAt = epochMs;
+      data<weather.Weather>(this, "weather", this.#params())
+        .then(answer => { this.#answer = answer; this.update(this.now()); }, () => undefined)
+        .finally(() => this.ready());
+    }
+    const page = Math.floor(Math.max(0, epochMs - this.startedAt()) / PAGE_MS) % 2;
+    this.#pages.forEach((p, i) => { p.hidden = i !== page; });
+    this.#time.textContent = this.#format!.format(epochMs);
+    const w = this.#answer?.data;
+    this.#weather.innerHTML = w
+      ? `<div class="temperature">${Math.round(w.current.temperature)}°${w.units === "imperial" ? "F" : "C"}</div><div class="condition">${w.current.condition.replace(/-/g, " ")}</div>`
+      : `<div class="none">The weather is on its way.</div>`;
+  }
+
+  /** Two pages of PAGE_MS each, for a layout that turns its enter and exit with them. */
+  paging() { return { count: 2, ms: PAGE_MS }; }
+}

package/templates/vanilla/src/env.d.ts

@@ -0,0 +1,5 @@
+// A CSS file the source imports is its text, for css(): pack bundles it so.
+declare module "*.css" {
+  const css: string;
+  export default css;
+}

package/templates/vanilla/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}