Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ Notable user-visible changes are recorded here. ScriptWidget follows semantic ve
- Fix native Promise callback ownership so completed and abandoned executions release their JavaScript VM and snapshot.
- Serialize native runtime subscription, result delivery and cancellation to prevent intermittent empty results and reference-lifetime crashes.
- Fix bundled templates whose text was cut off or pushed out of the widget, most visibly with the wider font of Android, Windows and Linux: Month Calendar (long month names, six-week months), the Daily Command Center, Family Command Board, Travel Day and Wellness dashboards, World Clock Faces and Year in Dots at the extra-large size, and fifteen smaller templates.
- Give 21 bundled templates that had one layout a small-widget layout showing their essential content (clocks, battery, focus, reading, sleep, system and the five dashboards), give the Daily Command Center, Family Command Board, Monthly Budget, Travel Day and Wellness dashboards a medium layout, and fix the overlapping rows of the large Monthly Budget Planner and the cut-off header of the medium Personal Dashboard.
- Fix Text Year Days Left, which counted to 31 January of the next year and so showed 31 days too many.
- Continue expanded personal-data APIs, authenticated services/music and visual editing on the same release branch; M3–M5 remain in progress.

## Unreleased
Expand Down
86 changes: 83 additions & 3 deletions Editor/editorfe/scripts/generate-api-docs.mjs
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { writeFile } from "node:fs/promises";
import { readFile, writeFile } from "node:fs/promises";
import { scriptWidgetAPI as api } from "../src/scriptWidgetAPI.js";
import { dataAPICatalog } from "../src/dataAPICatalog.js";
import { platformCell, platformColumns, platformRow, platformSentence, platformSupport } from "../src/platformSupport.js";

const outputURL = new URL("../../../docs/scriptwidget-runtime-api.md", import.meta.url);

Expand Down Expand Up @@ -32,17 +33,96 @@ lines.push("", "## Environment values", "", ...api.environmentValues.map((name)

await writeFile(outputURL, `${lines.join("\n")}\n`);

// Which systems each API runs on, from platformSupport.js.

// Its Apple columns must say what the catalog says.
for (const group of [...new Set(dataAPICatalog.map((item) => item.group))]) {
const row = platformRow(`$${group}`);
if (!row) throw new Error(`platformSupport.js has no row for $${group}`);
for (const item of dataAPICatalog.filter((entry) => entry.group === group)) {
for (const id of ["ios", "macos"]) {
if (item.platforms.includes(id) !== (row[id] !== false)) {
throw new Error(`${item.id}: platformSupport.js and dataAPICatalog.js disagree about ${id}`);
}
}
}
}

const code = (names) => names.map((name) => `\`${name}\``).join(", ");

const platformTable = [
`| API | ${platformColumns.map((column) => column.title).join(" | ")} |`,
`| --- | ${platformColumns.map(() => "---").join(" | ")} |`,
...platformSupport.map((row) => `| ${row.label ?? code(row.apis)} | ${platformColumns.map((column) => platformCell(row[column.id])).join(" | ")} |`),
];

function sentence(row) {
const { yes, no } = platformSentence(row);
return `${yes}.${no ? ` **Not on:** ${no}.` : ""}`;
}

// The note at the top of a page about one API or a few.
function runsOn(apis) {
const rows = [...new Set(apis.map((name) => {
const row = platformRow(name);
if (!row) throw new Error(`platformSupport.js has no row for ${name}`);
return row;
}))];
const link = "Details and limits: [Platform support](platform-support.md).";
if (rows.length === 1) return [`> **Runs on:** ${sentence(rows[0])} ${link}`];
return [
"> **Runs on**",
">",
...rows.map((row) => `> - ${code(row.apis.filter((name) => apis.includes(name)))}: ${sentence(row)}`),
">",
`> ${link}`,
];
}

// Replaces what is between the two markers of a hand-written page.
async function writeBetweenMarkers(file, content) {
const url = new URL(`../../../docs/${file}`, import.meta.url);
const text = await readFile(url, "utf8");
const start = "<!-- platforms:start -->", end = "<!-- platforms:end -->";
const from = text.indexOf(start), to = text.indexOf(end);
if (from < 0 || to < from) throw new Error(`docs/${file} has no platforms markers`);
await writeFile(url, `${text.slice(0, from + start.length)}\n${content.join("\n")}\n${text.slice(to)}`);
}

await writeBetweenMarkers("platform-support.md", platformTable);
await writeBetweenMarkers("runtime-api.md", platformTable);
for (const [file, apis] of Object.entries({
"calendar-api.md": ["$calendar"],
"file-api.md": ["$file"],
"health-api.md": ["$health"],
"http-response-api.md": ["$http"],
"icloud-json-api.md": ["$icloud"],
"location-api.md": ["$location"],
"music-api.md": ["$music"],
"photos-api.md": ["$photos"],
"reminders-api.md": ["$reminders"],
"services-api.md": ["$services"],
"storage-api.md": ["$storage"],
"system-services-api.md": ["$weather", "$alarms", "$documents", "$contacts", "$maps", "$home", "$notifications"],
})) {
await writeBetweenMarkers(file, runsOn(apis));
}

const dataLines = [
"# Data API capability catalog", "",
"> Generated from `Editor/editorfe/src/dataAPICatalog.js`. Native JSExport protocols remain authoritative. This catalog is descriptive and grants no permissions.", "",
"> Generated from `Editor/editorfe/src/dataAPICatalog.js` and `Editor/editorfe/src/platformSupport.js`. Native JSExport protocols remain authoritative. This catalog is descriptive and grants no permissions.", "",
"This covers device, system, health, location, calendar, reminders, photos and connected-service data methods. Files, network, storage, rendering and runtime configuration retain their own contracts. Platforms list intended real-data support, not mocked browser execution; hardware and OS authorization still determine availability.", "",
"Existing data-method return formats are unchanged. Present manifests now undergo package and minimum-version validation before execution. In particular, HealthKit does not expose individual read-denial status, and location cache presence is not proof that permission is still granted. Default mock values are illustrative, never measurements from the current device.", "",
"## Which systems each API runs on", "",
"\"Native platforms\" in the method table below means the Apple systems. Android, Windows and Linux run the same scripts on another engine; what they support is per API, not per method, and [Platform support](platform-support.md) explains each limit. An API a system lacks answers `false` from `isAvailable()` and rejects with `[unsupported_platform]`.", "",
...platformTable, "",
"## Methods", "",
"| API | Minimum native API | Native platforms | Execution | Authorization | Operation |", "| --- | --- | --- | --- | --- | --- |",
...dataAPICatalog.map((item) => `| \`${item.id}(${item.arguments.join(", ")})\` | ${item.minimumRuntimeVersion} | ${item.platforms.join(", ")} | ${item.asynchronous ? "Promise" : "Synchronous"} | ${item.authorization} | ${item.operation} |`), "",
];
for (const group of [...new Set(dataAPICatalog.map((item) => item.group))]) {
const entries = dataAPICatalog.filter((item) => item.group === group);
dataLines.push(`## ${group}`, "", entries[0].notes, "");
dataLines.push(`## ${group}`, "", entries[0].notes, "", `**Runs on:** ${sentence(platformRow(`$${group}`))}`, "");
for (const entry of entries) {
dataLines.push(`### \`${entry.id}\``, "", "Default editable preview sample:", "", "```json", JSON.stringify(entry.value, null, 2), "```", "");
}
Expand Down
60 changes: 60 additions & 0 deletions Editor/editorfe/src/platformSupport.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
// Which systems each global API runs on. One row per API (or group of APIs
// with the same answer). `true` is "Yes", `false` is "No", a string is "Yes"
// with that limit, written as the cell's text.
//
// This file is the source of the tables that `npm run docs` writes into
// docs/platform-support.md, docs/runtime-api.md, docs/data-api-catalog.md and
// the per-API pages. The authorities for each column are named in
// docs/platform-support.md; change this file when one of them changes.
//
// The iPhone/iPad and Mac columns of the data APIs must agree with the
// `platforms` of dataAPICatalog.js; the generator refuses to run otherwise.

export const platformColumns = [
{ id: "ios", title: "iPhone and iPad" },
{ id: "macos", title: "Mac" },
{ id: "android", title: "Android" },
{ id: "windows", title: "Windows" },
{ id: "linux", title: "Linux" },
];

const everywhere = { ios: true, macos: true, android: true, windows: true, linux: true };
const appleOnly = { android: false, windows: false, linux: false };

export const platformSupport = [
{ apis: ["$device", "$system", "$storage", "$file", "fetch", "$http", "$xml"], ...everywhere },
{ apis: ["$dataSource"], label: "`$dataSource` (Data Source Plugins)", ...everywhere },
{ apis: ["$weather"], ...everywhere },
{ apis: ["$calendar"], ios: true, macos: true, android: "Yes, for calendars selected in the app", windows: false, linux: false },
{ apis: ["$photos"], ios: true, macos: true, android: "Individual photos picked in the app, no albums", windows: false, linux: false },
{ apis: ["$contacts", "$documents"], ios: true, macos: true, android: "Yes, for items picked in the app", windows: false, linux: false },
{ apis: ["$maps"], ios: true, macos: true, android: "Geocoding and place search; no `snapshot`", windows: false, linux: false },
{ apis: ["$notifications"], ios: true, macos: true, android: "Yes, delivery is inexact", windows: false, linux: false },
{ apis: ["$services"], label: "`$services` (GitHub)", ios: true, macos: true, android: "With a fine-grained token, no OAuth sign-in", windows: false, linux: false },
{ apis: ["$icloud"], ios: true, macos: true, android: "A sync folder the user picks; cannot exchange data with an iPhone", windows: false, linux: false },
{ apis: ["$location"], ios: true, macos: false, android: "Yes; widgets see the position saved while the app was open", windows: false, linux: false },
{ apis: ["$health"], ios: true, macos: false, android: "Health Connect; no ring goals or stand time", windows: false, linux: false },
{ apis: ["$music"], ios: true, macos: false, android: "The active media session of any app", windows: false, linux: false },
{ apis: ["$alarms"], ios: true, macos: false, android: "Yes, inexact, no system alarm UI", windows: false, linux: false },
{ apis: ["$reminders"], ios: true, macos: true, ...appleOnly },
{ apis: ["$home"], ios: true, macos: false, ...appleOnly },
];

export function platformRow(api) {
return platformSupport.find((row) => row.apis.includes(api));
}

export function platformCell(value) {
return value === true ? "Yes" : value === false ? "No" : value;
}

// "iPhone and iPad, Mac, Android (…)" and "Windows, Linux" for one row.
export function platformSentence(row) {
const yes = [], no = [];
for (const column of platformColumns) {
const value = row[column.id];
if (value === false) no.push(column.title);
else yes.push(value === true ? column.title : `${column.title} (${value.replace(/^Yes[,;] /, "")})`);
}
return { yes: yes.join(", "), no: no.join(", ") };
}
35 changes: 35 additions & 0 deletions Editor/editorfe/test/platformSupport.test.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
import test from "node:test";
import assert from "node:assert/strict";
import { dataAPICatalog } from "../src/dataAPICatalog.js";
import { platformColumns, platformRow, platformSentence, platformSupport } from "../src/platformSupport.js";

test("every API is in one row and every row answers for every system", () => {
const names = platformSupport.flatMap((row) => row.apis);
assert.equal(new Set(names).size, names.length);
for (const row of platformSupport) {
for (const column of platformColumns) {
const value = row[column.id];
assert.ok(typeof value === "boolean" || (typeof value === "string" && value.length > 0), `${row.apis[0]} ${column.id}`);
}
}
});

test("the Apple columns agree with the data API catalog", () => {
for (const item of dataAPICatalog) {
const row = platformRow(`$${item.group}`);
assert.ok(row, item.group);
assert.equal(row.ios !== false, item.platforms.includes("ios"), item.id);
assert.equal(row.macos !== false, item.platforms.includes("macos"), item.id);
}
});

test("a row reads as a sentence", () => {
assert.deepEqual(platformSentence(platformRow("$health")), {
yes: "iPhone and iPad, Android (Health Connect; no ring goals or stand time)",
no: "Mac, Windows, Linux",
});
assert.deepEqual(platformSentence(platformRow("$storage")), {
yes: "iPhone and iPad, Mac, Android, Windows, Linux",
no: "",
});
});
19 changes: 19 additions & 0 deletions README_AR.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,25 @@ ScriptWidget منصة مفتوحة المصدر بترخيص Apache 2.0 لإنش

تطبيق Android (الإصدار 1.0.0، يتطلب Android 15 أو أحدث) متاح كملف [APK على GitHub Releases](https://github.com/everettjf/scriptwidget/releases/tag/android-v1.0.0). على Google Play هو في اختبار مغلق: للانضمام، انضم إلى [مجموعة Atomsprout Testers](https://groups.google.com/g/atomsprout). راجع [ScriptWidget لنظام Android](docs/android/README.md).

نسختا Windows وLinux تجريبيتان: [Windows 0.1.0](https://github.com/everettjf/scriptwidget/releases/tag/windows-v0.1.0) يتطلب Windows 11، راجع [ScriptWidget لنظام Windows](docs/windows/README.md)؛ ونسخة Linux تعمل حاليًا على [Omarchy](https://omarchy.org) 4.5، والأرشيفات متاحة على [GitHub Releases](https://github.com/everettjf/scriptwidget/releases)، راجع [ScriptWidget لنظام Linux](docs/linux/README.md). تشغّل النسختان حزم الأدوات المصغّرة نفسها، لكن لا تتوفر فيهما واجهات بيانات الجهاز مثل الصحة والتقويم والموقع والموسيقى.

### لقطات شاشة من كل منصة

جميعها لقطات شاشة حقيقية. نسختا Windows وLinux تجريبيتان.

| iPhone | iPad | Mac |
| --- | --- | --- |
| ![معرض القوالب على iPhone](docs/images/platforms/iphone-templates.webp) | ![المحرر على iPad](docs/images/platforms/ipad-editor.webp) | ![ScriptWidget Studio على Mac](docs/images/platforms/mac-studio.webp) |

| Android | Windows | Linux (Omarchy) |
| --- | --- | --- |
| ![أدوات مصغّرة على شاشة Android الرئيسية](docs/images/platforms/android-widgets.webp) | ![أدوات مصغّرة على سطح مكتب Windows](docs/images/platforms/windows-desktop.webp) | ![أدوات مصغّرة على سطح مكتب Omarchy](docs/images/platforms/linux-desktop.webp) |
| ![المحرر على Android](docs/images/platforms/android-editor.webp) | ![المحرر على Windows](docs/images/platforms/windows-editor.webp) | ![المحرر على Linux](docs/images/platforms/linux-editor.webp) |

| Web Studio |
| --- |
| ![Web Studio في المتصفح](docs/images/platforms/web-studio.webp) |

## لماذا ScriptWidget؟

- يعمل السكربت نفسه على iOS وiPadOS وmacOS، وكذلك على Android (قيد الاختبار)، مع تخطيطات متكيفة عبر `$getenv("widget-size")`.
Expand Down
19 changes: 19 additions & 0 deletions README_DE.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,25 @@ ScriptWidget ist eine Open-Source-Plattform unter der Apache 2.0-Lizenz zum Erst

Die Android-App (Version 1.0.0, ab Android 15) gibt es als [APK in den GitHub Releases](https://github.com/everettjf/scriptwidget/releases/tag/android-v1.0.0). Bei Google Play läuft ein geschlossener Test: Wer teilnehmen möchte, tritt der [Gruppe Atomsprout Testers](https://groups.google.com/g/atomsprout) bei. Siehe [ScriptWidget für Android](docs/android/README.md).

Die Versionen für Windows und Linux sind Vorschauversionen: [Windows 0.1.0](https://github.com/everettjf/scriptwidget/releases/tag/windows-v0.1.0) benötigt Windows 11, siehe [ScriptWidget für Windows](docs/windows/README.md); die Linux-Version läuft derzeit unter [Omarchy](https://omarchy.org) 4.5, die Archive liegen in den [GitHub Releases](https://github.com/everettjf/scriptwidget/releases), siehe [ScriptWidget für Linux](docs/linux/README.md). Beide führen dieselben Widget-Pakete aus, haben aber keine APIs für Gerätedaten wie Gesundheit, Kalender, Standort und Musik.

### Screenshots aller Plattformen

Alles echte Screenshots. Windows und Linux sind Vorschauversionen.

| iPhone | iPad | Mac |
| --- | --- | --- |
| ![Vorlagengalerie auf dem iPhone](docs/images/platforms/iphone-templates.webp) | ![Editor auf dem iPad](docs/images/platforms/ipad-editor.webp) | ![ScriptWidget Studio auf dem Mac](docs/images/platforms/mac-studio.webp) |

| Android | Windows | Linux (Omarchy) |
| --- | --- | --- |
| ![Widgets auf dem Android-Startbildschirm](docs/images/platforms/android-widgets.webp) | ![Widgets auf dem Windows-Desktop](docs/images/platforms/windows-desktop.webp) | ![Widgets auf dem Omarchy-Desktop](docs/images/platforms/linux-desktop.webp) |
| ![Editor unter Android](docs/images/platforms/android-editor.webp) | ![Editor unter Windows](docs/images/platforms/windows-editor.webp) | ![Editor unter Linux](docs/images/platforms/linux-editor.webp) |

| Web Studio |
| --- |
| ![Web Studio im Browser](docs/images/platforms/web-studio.webp) |

## Warum ScriptWidget?

- Ein Skript läuft auf iOS, iPadOS und macOS sowie auf Android (im Test); Layouts lassen sich mit `$getenv("widget-size")` anpassen.
Expand Down
19 changes: 19 additions & 0 deletions README_ES.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,25 @@ ScriptWidget es una plataforma de código abierto con licencia Apache 2.0 para c

La app para Android (versión 1.0.0, Android 15 o posterior) está disponible como [APK en GitHub Releases](https://github.com/everettjf/scriptwidget/releases/tag/android-v1.0.0). En Google Play está en prueba cerrada: para participar, únete al [grupo Atomsprout Testers](https://groups.google.com/g/atomsprout). Consulta [ScriptWidget para Android](docs/android/README.md).

Las versiones para Windows y Linux son versiones preliminares: [Windows 0.1.0](https://github.com/everettjf/scriptwidget/releases/tag/windows-v0.1.0) requiere Windows 11, consulta [ScriptWidget para Windows](docs/windows/README.md); la versión para Linux funciona por ahora en [Omarchy](https://omarchy.org) 4.5, los archivos están en [GitHub Releases](https://github.com/everettjf/scriptwidget/releases), consulta [ScriptWidget para Linux](docs/linux/README.md). Ambas ejecutan los mismos paquetes de widgets, pero no tienen las API de datos del dispositivo como salud, calendario, ubicación y música.

### Capturas de cada plataforma

Todas son capturas reales. Windows y Linux son versiones preliminares.

| iPhone | iPad | Mac |
| --- | --- | --- |
| ![Galería de plantillas en el iPhone](docs/images/platforms/iphone-templates.webp) | ![Editor en el iPad](docs/images/platforms/ipad-editor.webp) | ![ScriptWidget Studio en el Mac](docs/images/platforms/mac-studio.webp) |

| Android | Windows | Linux (Omarchy) |
| --- | --- | --- |
| ![Widgets en la pantalla de inicio de Android](docs/images/platforms/android-widgets.webp) | ![Widgets en el escritorio de Windows](docs/images/platforms/windows-desktop.webp) | ![Widgets en el escritorio de Omarchy](docs/images/platforms/linux-desktop.webp) |
| ![Editor en Android](docs/images/platforms/android-editor.webp) | ![Editor en Windows](docs/images/platforms/windows-editor.webp) | ![Editor en Linux](docs/images/platforms/linux-editor.webp) |

| Web Studio |
| --- |
| ![Web Studio en el navegador](docs/images/platforms/web-studio.webp) |

## Por qué elegir ScriptWidget

- Un mismo script funciona en iOS, iPadOS y macOS, y también en Android (en pruebas), con diseños adaptables mediante `$getenv("widget-size")`.
Expand Down
Loading
Loading