Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
404d522
Linux management window: Components and APIs in the sidebar, like Win…
everettjf Nov 18, 2026
7f35ab1
Format every bundled example with Prettier
everettjf Nov 18, 2026
50de9c7
Explain the API, component and Android examples with comments
everettjf Nov 18, 2026
23c4097
Comment the bundled templates from Activity Rings to Focus Countdown
everettjf Nov 18, 2026
1d5824d
Comment the bundled templates from Photo Card to Year in Dots
everettjf Nov 18, 2026
0169403
Comment the bundled templates from Gauge Battery to Photo Album Rotator
everettjf Nov 18, 2026
3c45295
Merge branch 'worktree-agent-ae9ac9ae73aa03994' into linux-0.1.4
everettjf Nov 18, 2026
37a285f
Merge branch 'worktree-agent-a3c91ec3f95b69e6a' into linux-0.1.4
everettjf Nov 18, 2026
e739d0c
Merge branch 'worktree-agent-a6178a65eba84266a' into linux-0.1.4
everettjf Nov 18, 2026
acdac23
Align the shared helpers of the commented templates and sync the Gall…
everettjf Nov 18, 2026
d20397a
Linux 0.1.4
everettjf Nov 18, 2026
c4fd966
Linux docs: pictures of the Components and APIs pages
everettjf Nov 18, 2026
141b468
Regenerate the Material Study fixture after formatting, and record th…
everettjf Nov 18, 2026
e581cb3
Merge branch 'fixtures-after-format' into linux-0.1.4
everettjf Nov 18, 2026
7961fa9
Layout panel: read code as a formatter writes it
everettjf Nov 18, 2026
8f8b459
Docs: say for each component which systems draw it, and how
everettjf Nov 18, 2026
91550a6
Regenerate the Layout Starter fixture now that Layout reads formatted…
everettjf Nov 18, 2026
2f9c9df
Merge branch 'fixtures-after-format' into linux-0.1.4
everettjf Nov 18, 2026
c9825dd
Merge remote-tracking branch 'origin/main' into linux-0.1.4
everettjf Nov 18, 2026
9fbc00c
Record the 0.1.4 checks on the test machine
everettjf Nov 18, 2026
44318e1
Layout panel: edits keep one layer a line and carry the comment above…
everettjf Nov 18, 2026
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: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ Treat scripts, imported ZIPs, Gallery content, Skills, plugin manifests, network

- Swift: 4-space indentation, Xcode defaults, `UpperCamelCase` types and `lowerCamelCase` members. Prefer small SwiftUI views, modern Observation for new state models where deployment allows, stable `ForEach` identity, and accessibility labels for icon-only controls.
- JavaScript/React: 2-space indentation, `UpperCamelCase` components and `lowerCamelCase` functions. Match surrounding formatting; avoid unrelated whole-file rewrites.
- Runtime examples: keep `main.jsx` UTF-8, deterministic, within runtime budgets, and compatible with their declared permissions/hosts/plugins.
- Runtime examples: keep `main.jsx` UTF-8, deterministic, within runtime budgets, and compatible with their declared permissions/hosts/plugins. They are formatted with Prettier (`Editor/editorfe/node_modules/.bin/prettier --no-config --print-width 100`) and commented for a reader who is new to ScriptWidget; a text with two spaces in a row must be written as a string in braces, because the formatter joins them.
- Xcode projects use explicit file references. When adding shared Swift sources, add them to every app/widget/test target that compiles or references them, then lint both `.pbxproj` files with `plutil -lint`.
- Preserve user-authored or unrelated dirty-worktree changes. Generated editor bundles are the exception only when deliberately rebuilt from matching frontend source.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,40 +1,70 @@
// A counter with two declared actions. The buttons run them, and so can
// another app: on Android turn on Settings > Automation, allow this package,
// and send the "increment" or "reset" action from Tasker or a similar app.
const valueKey = "counter.value", sourceKey = "counter.source";
// The actions and their functions are declared under "actions" in widget.json, which
// also lists the "storage" permission that $storage needs.
// Try: change the step in increment(), or add a third action here and in widget.json.
// The keys under which $storage, the small store of this package, keeps the two values.
const valueKey = "counter.value",
sourceKey = "counter.source";

// The count is stored as text. If the text is not a number, start again from 0.
function read() {
const value = Number($storage.getString(valueKey));
return Number.isFinite(value) ? value : 0;
}
// Save the new count and what caused the change.
function write(value) {
$storage.setString(valueKey, String(value));
// "widget" for a tap, "shortcut" for an app shortcut, "automation" for another app.
$storage.setString(sourceKey, $getenv("action-source"));
$render(<text>{"Count " + value}</text>);
}
function increment() { write(read() + 1); }
function reset() { write(0); }
// These two names are the "function" values of the actions in widget.json.
function increment() {
write(read() + 1);
}
function reset() {
write(0);
}

// For a widget this is "small", "medium" or "large". "action" and "function" mean the
// script was started to run an action, not to draw the widget.
const size = $getenv("widget-size");
if (size === "action" || size === "function") {
// The host calls the declared function after this script was evaluated.
} else {
// Empty text until the count was changed for the first time.
const source = $storage.getString(sourceKey);
// A small widget has room for the icons only.
const small = size === "small";
// One button. actionID names an action declared in widget.json.
const control = (id, symbol, title) => (
<button actionID={id}>{small ? <icon systemName={symbol} size="26" color="material.primary" /> : <label systemName={symbol} title={title} color="material.primary" />}</button>
<button actionID={id}>
{small ? (
<icon systemName={symbol} size="26" color="material.primary" />
) : (
<label systemName={symbol} title={title} color="material.primary" />
)}
</button>
);
// Draw the widget. frame="max" makes the stack fill it. Colors named material.<role>
// follow the Android wallpaper.
$render(
<vstack frame="max" spacing="6" padding="14" background="material.surfaceContainer">
<text font="caption" color="material.onSurfaceVariant">Counter</text>
<text font="largeTitle,bold" color="material.primary">{String(read())}</text>
<text font="caption2" color="material.onSurfaceVariant">{source ? "Changed by " + source : "Not changed yet"}</text>
<text font="caption" color="material.onSurfaceVariant">
Counter
</text>
<text font="largeTitle,bold" color="material.primary">
{String(read())}
</text>
<text font="caption2" color="material.onSurfaceVariant">
{source ? "Changed by " + source : "Not changed yet"}
</text>
<hstack spacing={small ? "28" : "16"}>
{control("increment", "plus.circle.fill", "Add one")}
{control("reset", "arrow.counterclockwise", "Reset")}
</hstack>
</vstack>
</vstack>,
);
}
Original file line number Diff line number Diff line change
@@ -1,34 +1,79 @@
// A list that scrolls inside the widget, which only Android can do.
// Every row is a toggle that keeps its own state in package storage.
// iPhone widgets cannot scroll, so the first rows are shown there.
// $storage needs the "storage" permission, which widget.json lists.
// Try: change the texts in items, or the number of rows shown without a list.
const items = [
"Water the plants", "Reply to Sam", "Book the dentist", "Renew the library card", "Back up the photos",
"Order printer ink", "Call the plumber", "Pay the electricity bill", "Plan the weekend trip", "Clean the keyboard",
"Update the budget", "Return the parcel", "Charge the camera", "Sort the bookshelf", "Write to grandma",
"Check the tire pressure", "Buy a birthday card", "Defrost the freezer", "Review the notes", "Stretch for ten minutes",
"Water the plants",
"Reply to Sam",
"Book the dentist",
"Renew the library card",
"Back up the photos",
"Order printer ink",
"Call the plumber",
"Pay the electricity bill",
"Plan the weekend trip",
"Clean the keyboard",
"Update the budget",
"Return the parcel",
"Charge the camera",
"Sort the bookshelf",
"Write to grandma",
"Check the tire pressure",
"Buy a birthday card",
"Defrost the freezer",
"Review the notes",
"Stretch for ten minutes",
];
// $system.platform() says where the script runs. Only "android" has <list>.
const android = $system.platform() === "android";
const size = $getenv("widget-size");
// One stored value per row: the text "true" when the row is checked.
const done = items.map((_, index) => $storage.getString("check." + index) === "true");
const count = done.filter(Boolean).length;

// One row. stateKey is the $storage key that holds the state of this toggle.
// A checked row gets the quieter text color.
const row = (title, index) => (
<toggle stateKey={"check." + index} on={done[index]} padding="4,2,4,2">
<text font="subheadline" color={done[index] ? "material.onSurfaceVariant" : "material.onSurface"}>{title}</text>
<text
font="subheadline"
color={done[index] ? "material.onSurfaceVariant" : "material.onSurface"}
>
{title}
</text>
</toggle>
);

const rows = android
? <list spacing="2">{items.map(row)}</list>
: <vstack alignment="leading" spacing="4">{items.slice(0, size === "large" ? 7 : 2).map(row)}</vstack>;
// Android: every row, in a list that scrolls. Elsewhere <list> is unknown, so show the
// first 7 rows in a large widget and the first 2 in the other sizes.
const rows = android ? (
<list spacing="2">{items.map(row)}</list>
) : (
<vstack alignment="leading" spacing="4">
{items.slice(0, size === "large" ? 7 : 2).map(row)}
</vstack>
);

// frame="max,topLeading" fills the widget and puts the content in the top left corner.
$render(
<vstack frame="max,topLeading" alignment="leading" spacing="8" padding="14" background="material.surfaceContainer">
<vstack
frame="max,topLeading"
alignment="leading"
spacing="8"
padding="14"
background="material.surfaceContainer"
>
{/* The title on the left and "3 of 20" on the right; <spacer /> pushes them apart. */}
<hstack>
<text font="headline" color="material.onSurface">Checklist</text>
<text font="headline" color="material.onSurface">
Checklist
</text>
<spacer />
<text font="caption" color="material.primary">{count + " of " + items.length}</text>
<text font="caption" color="material.primary">
{count + " of " + items.length}
</text>
</hstack>
{rows}
</vstack>
</vstack>,
);
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,50 @@
// "material.<role>" in any color prop and the widget follows the wallpaper,
// in light and in dark mode. iPhone does not know these names and keeps its
// default colors.
// Try: replace a role in the list with another one, such as "surfaceVariant" or "outline".
// Used only for the last line of text, which says where the widget runs.
const android = $system.platform() === "android";
// A small widget gets shorter texts.
const small = $getenv("widget-size") === "small";
const roles = ["primary", "secondary", "tertiary", "primaryContainer", "secondaryContainer", "tertiaryContainer"];
// The roles shown as color swatches.
const roles = [
"primary",
"secondary",
"tertiary",
"primaryContainer",
"secondaryContainer",
"tertiaryContainer",
];

// frame="max,topLeading" fills the widget and puts the content in the top left corner.
$render(
<vstack frame="max,topLeading" alignment="leading" spacing="10" padding="14" background="material.surfaceContainer">
<text font="headline" color="material.onSurface">{small ? "Wallpaper" : "Wallpaper colors"}</text>
<vstack
frame="max,topLeading"
alignment="leading"
spacing="10"
padding="14"
background="material.surfaceContainer"
>
<text font="headline" color="material.onSurface">
{small ? "Wallpaper" : "Wallpaper colors"}
</text>
{/* One swatch per role. frame="max,26": as wide as possible and 26 points high. */}
<hstack spacing="6">
{roles.map((role) => <rect corner="8" color={"material." + role} frame="max,26" />)}
{roles.map((role) => (
<rect corner="8" color={"material." + role} frame="max,26" />
))}
</hstack>
{/* A card in a container color. Its text uses the matching "on" color to stay readable. */}
<hstack spacing="8" padding="10" background="material.primaryContainer" corner="14">
<icon systemName="paintpalette.fill" size="18" color="material.onPrimaryContainer" />
<text font="footnote" color="material.onPrimaryContainer">{small ? "Follows it" : "Change the wallpaper and this card follows."}</text>
<text font="footnote" color="material.onPrimaryContainer">
{small ? "Follows it" : "Change the wallpaper and this card follows."}
</text>
</hstack>
{/* <spacer /> takes the free room, so the last line sits at the bottom. */}
<spacer />
<text font="caption2" color="material.onSurfaceVariant">
{android ? (small ? "Material colors" : "Material colors of this phone") : "Android only"}
</text>
</vstack>
</vstack>,
);
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,8 @@ Notable user-visible changes are recorded here. ScriptWidget follows semantic ve
- 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.
- Format every bundled example with Prettier and add comments for readers new to ScriptWidget; no example draws anything different.
- Linux 0.1.4: the management window lists Components and APIs as their own sidebar entries, as on Windows.
- Continue expanded personal-data APIs, authenticated services/music and visual editing on the same release branch; M3–M5 remain in progress.

## Unreleased
Expand Down
20 changes: 16 additions & 4 deletions Editor/editorfe/scripts/generate-api-docs.mjs
Original file line number Diff line number Diff line change
@@ -1,7 +1,13 @@
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";
import { componentSupport, platformCell, platformColumns, platformRow, platformSentence, platformSupport } from "../src/platformSupport.js";

const componentTable = [
`| Component | ${platformColumns.map((column) => column.title).join(" | ")} |`,
`| --- | ${platformColumns.map(() => "---").join(" | ")} |`,
...componentSupport.map((row) => `| ${row.label ?? row.components.map((name) => `\`${name}\``).join(", ")} | ${platformColumns.map((column) => platformCell(row[column.id])).join(" | ")} |`),
];

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

Expand All @@ -10,6 +16,12 @@ const lines = [
"",
`> Generated from Studio's static API metadata (schema v${api.schemaVersion}, runtime ${api.runtimeVersion}). The native runtime switch is authoritative. Do not edit by hand.`,
"",
"## Which systems each component runs on",
"",
"Every component below exists on iPhone, iPad, Mac, Android, Windows and Linux, except the scrolling `<list>`, which only Android has and which is not in this reference (see [ScriptWidget for Android](android/README.md)). What a system draws differently is in this table; [Platform support](platform-support.md) has the same table beside the APIs and the widget features.",
"",
...componentTable,
"",
"## Components",
"",
];
Expand Down Expand Up @@ -80,16 +92,16 @@ function runsOn(apis) {
}

// Replaces what is between the two markers of a hand-written page.
async function writeBetweenMarkers(file, content) {
async function writeBetweenMarkers(file, content, start = "<!-- platforms:start -->", end = "<!-- platforms:end -->") {
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`);
if (from < 0 || to < from) throw new Error(`docs/${file} has no ${start} marker`);
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("platform-support.md", componentTable, "<!-- components:start -->", "<!-- components:end -->");
await writeBetweenMarkers("runtime-api.md", platformTable);
for (const [file, apis] of Object.entries({
"calendar-api.md": ["$calendar"],
Expand Down
22 changes: 22 additions & 0 deletions Editor/editorfe/src/platformSupport.js
Original file line number Diff line number Diff line change
Expand Up @@ -58,3 +58,25 @@ export function platformSentence(row) {
}
return { yes: yes.join(", "), no: no.join(", ") };
}

// The same for the JSX components. Android, Windows and Linux draw with one
// shared renderer, so a component exists on all three or on none; what differs
// is listed here. The authorities are docs/public-animations.md for the Apple
// columns and the "Differences" tables of docs/android, docs/windows and
// docs/linux for the others.
const lookAlike = "Yes; SF Symbols are drawn with look-alike icons, and a name without one shows a placeholder";
export const componentSupport = [
{ components: ["<vstack>", "<hstack>", "<zstack>", "<vgrid>", "<hgrid>", "<spacer>", "<divider>"], label: "Layout: `<vstack>`, `<hstack>`, `<zstack>`, `<vgrid>`, `<hgrid>`, `<spacer>`, `<divider>`", ...everywhere },
{ components: ["<text>", "<label>", "<badge>", "<chip>", "<stat>"], label: "Text: `<text>`, `<label>`, `<badge>`, `<chip>`, `<stat>`", ios: true, macos: true, android: "Yes, in Inter, which is wider than the Apple system font", windows: "Yes, in Inter", linux: "Yes, in Inter" },
{ components: ["<rect>", "<roundedrect>", "<capsule>", "<ellipse>", "<circle>", "<line>"], label: "Shapes: `<rect>`, `<roundedrect>`, `<capsule>`, `<ellipse>`, `<circle>`, `<line>`", ...everywhere },
{ components: ["<gauge>", "<progress>", "<ring>", "<chart>"], label: "Values: `<gauge>`, `<progress>`, `<ring>`, `<chart>`", ...everywhere },
{ components: ["<image>"], ...everywhere },
{ components: ["<icon>"], label: "`<icon>` and `systemName` images", ios: true, macos: true, android: lookAlike, windows: lookAlike, linux: lookAlike },
{ components: ["<date>"], ios: true, macos: true, android: "`timer` and a `time` of now tick by themselves; `relative`, `offset` and `date` are redrawn at each refresh", windows: "A timer is redrawn every second and a clock time every minute", linux: "A timer is redrawn every second and a clock time every minute" },
{ components: ["<gif>"], ios: "Animated in the app's preview; in a widget the system decides and may hold one frame", macos: "The first frame", android: "Up to 24 sampled frames", windows: "The first frame", linux: "Animated on the desktop, at most 60 frames" },
{ components: ["animation"], label: "The `animation` property (clock hands, swing)", ios: "Moves in the app's preview; in a widget the system schedules it and may hold one frame", macos: "Standard clock hands show the time without moving; the others stay at rest", android: "Standard clock hands are a system clock; swing and custom intervals play as frames", windows: "The first frame", linux: "The first frame" },
{ components: ["<button>", "<toggle>"], ios: "Yes, from iOS 17", macos: "Yes, from macOS 14", android: true, windows: true, linux: true },
{ components: ["<link>"], ios: true, macos: true, android: true, windows: "`http`, `https` and `mailto` only", linux: "`http`, `https` and `mailto` only" },
{ components: ["backgroundMaterial"], label: "The `backgroundMaterial` property", ios: true, macos: true, android: "The opaque `background` fallback", windows: "The opaque `background` fallback", linux: "The opaque `background` fallback" },
{ components: ["<list>"], label: "Scrolling `<list>`", ios: false, macos: false, android: true, windows: false, linux: false },
];
Loading
Loading