@vestra-player/sdk 1.5.11 → 1.5.12

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.5.12
+
+**Keys of disabled commands pass on; `i18n check` fails on stale catalogs; translator notes in tables; the Button follows its text.** A fix release; `apiVersion` stays `vestra/1`.
+
+- **`TestHost.press` matches the player (0.4.3) for disabled commands.** A disabled command no longer swallows its key: the key goes to the next command bound to it (the one it shadowed in a conflict, then the global scope after a panel binding). With only disabled commands left, the first one with a `reason` shows the reason on the OSD and eats the key; without a reason the key reaches the focused control. `press` now resolves with what happened, `"ran"`, `"reason"` (see `host.osd`) or `"passed"`, instead of rejecting for a disabled command; it still rejects when nothing is bound and when the command that runs is busy. A test that expected `press` to reject for a disabled command now gets `"passed"` or `"reason"`.
+- **`vestra-plugin i18n check` exits with 1** when `locales/messages.pot` is out of date, missing while `.po` files exist, or a `.po` lacks some of the template's messages, so CI catches a forgotten `extract`. Before, it printed these and exited 0. The other findings stay warnings, and `vestra-plugin check` still only prints them.
+- **`TRANSLATORS:` notes on `as const` table entries.** A comment before a property or element of an object or array literal under `as const` (at any depth) now reaches the translators like one at a call site; before, texts extracted through a table lost their notes.
+- **`slint/vestra/widgets.slint`** (the copy of the player's library): `Button`'s preferred width follows its label (the minimum width is unchanged), so a longer translated label widens the button instead of overflowing it.
+
 ## 1.5.11
 
 **Text values: words mixed with data, translated by the player** (player 0.4.3). Additive; `apiVersion` stays `vestra/1`, and plugins that worked need no change. 1.5.9 and 1.5.10 were not published to npm; this release includes them. Round-2 i18n requests R2-audio-1, R2-video-1, R2-subtitles-1/2, R2-playlist-1/2, R2-store-1, R2-workshop-1, R2-nes-1, capture #1, P-2, the info and hotkeys export texts, timeline and subtitle titles: one mechanism. Guide: [Translate a plugin ▸ Text that mixes words and data](docs/how-to/i18n.md#text-that-mixes-words-and-data).

package/README.md

@@ -83,7 +83,7 @@ Complete, tested plugins in [`examples/`](https://github.com/vestrasys/vestra-pl
 | `vestra-plugin build [dir...] [--version x.y.z]`            | Writes `dist/`: types stripped, files copied, manifest versioned.          |
 | `vestra-plugin pack [dir...] [--version x.y.z] [--out dir]` | Builds, then packs `dist/` as `<id>-<version>.vxp`.                        |
 | `vestra-plugin i18n extract [dir...] [--locale lang]`       | Collects the texts to translate into `locales/`, keeping translations.     |
-| `vestra-plugin i18n check [dir...]`                         | Translation coverage and untranslatable text (warnings only).              |
+| `vestra-plugin i18n check [dir...]`                         | Translation coverage and untranslatable text; fails on stale catalogs.     |
 
 ## Compatibility
 

package/bin/vestra-plugin.mjs

@@ -29,7 +29,8 @@
  *   i18n check    coverage per language, placeholder and plural problems, a
  *                 stale messages.pot, and texts that cannot be translated
  *                 (composed in TypeScript, not literals, not English, Slint
- *                 text without @tr); warnings only, an unreadable .po fails
+ *                 text without @tr) as warnings; fails (exit 1) on a stale
+ *                 messages.pot, a .po missing messages, an unreadable file
  *
  * `check` prints the same i18n warnings when the plugin has locales/;
  * `build` compiles locales/<lang>.po to dist/locales/<lang>.json (the .po
@@ -430,7 +431,8 @@ async function i18nCheck(target) {
   dependencies(target);
   const { warnings, errors } = await i18nReport(target);
   for (const line of warnings) console.log(`${target.name}: i18n: ${line}`);
-  if (errors.length) fail(`${target.name}: ${errors.join("; ")}`);
+  // A stale messages.pot, a .po missing messages, an unreadable file.
+  if (errors.length) fail(`${target.name}: i18n: ${errors.join("; ")}`);
   if (!warnings.length) console.log(`${target.name}: i18n: no problems`);
 }
 

package/dist/i18n-tools.js

@@ -100,6 +100,34 @@ function ignored(node, text) {
         .slice(node.getFullStart(), node.getStart())
         .includes("i18n-ignore");
 }
+/**
+ * A string that is an entry (a property value or an element) of an object
+ * or array literal inside `… as const`, at any depth.
+ */
+function inConstTable(node) {
+    let current;
+    if (ts.isPropertyAssignment(node.parent) && node.parent.initializer === node)
+        current = node.parent.parent;
+    else if (ts.isArrayLiteralExpression(node.parent))
+        current = node.parent;
+    else
+        return false;
+    for (;;) {
+        const parent = current.parent;
+        if (ts.isAsExpression(parent) &&
+            ts.isTypeReferenceNode(parent.type) &&
+            ts.isIdentifier(parent.type.typeName) &&
+            parent.type.typeName.text === "const")
+            return true;
+        if (ts.isPropertyAssignment(parent))
+            current = parent.parent;
+        else if (ts.isArrayLiteralExpression(parent) ||
+            ts.isParenthesizedExpression(parent))
+            current = parent;
+        else
+            return false;
+    }
+}
 /** The statement (or class member) a node belongs to. */
 function statementOf(node) {
     let current = node;
@@ -111,6 +139,11 @@ function statementOf(node) {
 }
 class Extractor {
     found = [];
+    /**
+     * `TRANSLATORS:` notes on entries of `as const` tables, by text: a table
+     * entry is extracted through its literal type, which has no comments.
+     */
+    tableNotes = new Map();
     findings = [];
     #checker;
     constructor(checker) {
@@ -302,6 +335,20 @@ class Extractor {
         const visit = (node) => {
             if (ts.isCallExpression(node))
                 this.#call(node, file, source, text);
+            if ((ts.isStringLiteral(node) ||
+                ts.isNoSubstitutionTemplateLiteral(node)) &&
+                inConstTable(node)) {
+                // The comment sits before the entry: the property, or the element.
+                const entry = ts.isPropertyAssignment(node.parent) ? node.parent : node;
+                const notes = notesOf(entry, text);
+                if (notes.length) {
+                    const known = this.tableNotes.get(node.text) ?? [];
+                    for (const note of notes)
+                        if (!known.includes(note))
+                            known.push(note);
+                    this.tableNotes.set(node.text, known);
+                }
+            }
             // A text value written as data: `{ $vestraText: "…" }`.
             if (ts.isPropertyAssignment(node) &&
                 (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) &&
@@ -589,7 +636,10 @@ export function extract(options) {
         }
         if (occurrence.plural !== undefined && message.plural === undefined)
             message.plural = occurrence.plural;
-        for (const note of occurrence.notes)
+        const tableNotes = occurrence.context === undefined
+            ? (extractor.tableNotes.get(occurrence.id) ?? [])
+            : [];
+        for (const note of [...occurrence.notes, ...tableNotes])
             if (!message.notes.includes(note))
                 message.notes.push(note);
         if (!message.references.includes(reference))
@@ -683,24 +733,26 @@ export function checkCatalogs(directory, messages, findings) {
     const pot = join(locales, "messages.pot");
     const keys = (entries) => new Set(entries.map((e) => `${keyOf(e.context, e.id)}\u0000${e.plural ?? ""}`));
     const wanted = keys(messages);
+    const files = existsSync(locales)
+        ? readdirSync(locales)
+            .filter((name) => name.endsWith(".po"))
+            .sort()
+        : [];
+    // A stale template or a .po without some of its messages fails
+    // `i18n check` (an error); `check` prints it like the warnings.
     if (!existsSync(pot))
-        warnings.push("locales/messages.pot is missing: run vestra-plugin i18n extract");
+        (files.length ? errors : warnings).push("locales/messages.pot is missing: run vestra-plugin i18n extract");
     else {
         try {
             const have = keys(parsePo(readFileSync(pot, "utf8")).entries);
             const same = have.size === wanted.size && [...wanted].every((key) => have.has(key));
             if (!same)
-                warnings.push("locales/messages.pot is out of date: run vestra-plugin i18n extract");
+                errors.push("locales/messages.pot is out of date: run vestra-plugin i18n extract");
         }
         catch (error) {
             errors.push(`locales/messages.pot: ${error.message}`);
         }
     }
-    const files = existsSync(locales)
-        ? readdirSync(locales)
-            .filter((name) => name.endsWith(".po"))
-            .sort()
-        : [];
     for (const name of files) {
         const language = name.slice(0, -3);
         if (language === "en") {
@@ -729,7 +781,7 @@ export function checkCatalogs(directory, messages, findings) {
         const inFile = keys(live);
         const missing = [...wanted].filter((key) => !inFile.has(key)).length;
         if (missing)
-            warnings.push(`locales/${name}: ${missing} ${missing === 1 ? "message is" : "messages are"} not in this file: run vestra-plugin i18n extract`);
+            errors.push(`locales/${name}: ${missing} ${missing === 1 ? "message is" : "messages are"} not in this file: run vestra-plugin i18n extract`);
         for (const entry of live) {
             entry.strings.forEach((text, form) => {
                 if (text === "")

package/dist/plugin/testing.d.ts

@@ -1242,11 +1242,20 @@ export declare class TestHost implements Transport {
     failStream(producerId: number, message: string): void;
     /**
      * Press a binding like the host's table would: panel-focus bindings first
-     * when `panel` is true, then global ones; the earliest registration wins a
-     * conflict. Resolves after the command ran; rejects when nothing is bound
-     * or the command is disabled or busy. Bindings use the reference syntax
-     * (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`); the player's core actions
-     * match first, and user overrides in `bindings.overlay` apply.
+     * when `panel` is true, then global ones; within a scope the earliest
+     * registration first (the player's own commands before the plugin's), as
+     * the conflict rule orders them. A disabled command lets the key pass to
+     * the next command bound to it (SDK 1.5.12, as player 0.4.3): the one it
+     * shadowed, then the global scope. The first enabled one runs; `press`
+     * resolves after it ran (`"ran"`), or rejects when it is busy. When only
+     * disabled commands hold the key, the first one with a `reason` shows the
+     * reason on the OSD and eats the key (`"reason"`, see `host.osd`);
+     * without a reason the key goes on to the focused control (`"passed"`,
+     * nothing runs). Rejects when nothing is bound. Bindings use the
+     * reference syntax (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`), and user
+     * overrides in `bindings.overlay` apply.
+     *
+     * @returns What the key did: `"ran"`, `"reason"` or `"passed"`.
      *
      * @example
      * ```ts
@@ -1256,7 +1265,7 @@ export declare class TestHost implements Transport {
      */
     press(binding: string, options?: {
         panel?: boolean;
-    }): Promise<void>;
+    }): Promise<"ran" | "reason" | "passed">;
     /**
      * Bindings declared by more than one command, each as
      * `[binding, winner, ...ignored]` (command ids; core actions as

package/dist/plugin/testing.js

@@ -1749,11 +1749,20 @@ export class TestHost {
     }
     /**
      * Press a binding like the host's table would: panel-focus bindings first
-     * when `panel` is true, then global ones; the earliest registration wins a
-     * conflict. Resolves after the command ran; rejects when nothing is bound
-     * or the command is disabled or busy. Bindings use the reference syntax
-     * (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`); the player's core actions
-     * match first, and user overrides in `bindings.overlay` apply.
+     * when `panel` is true, then global ones; within a scope the earliest
+     * registration first (the player's own commands before the plugin's), as
+     * the conflict rule orders them. A disabled command lets the key pass to
+     * the next command bound to it (SDK 1.5.12, as player 0.4.3): the one it
+     * shadowed, then the global scope. The first enabled one runs; `press`
+     * resolves after it ran (`"ran"`), or rejects when it is busy. When only
+     * disabled commands hold the key, the first one with a `reason` shows the
+     * reason on the OSD and eats the key (`"reason"`, see `host.osd`);
+     * without a reason the key goes on to the focused control (`"passed"`,
+     * nothing runs). Rejects when nothing is bound. Bindings use the
+     * reference syntax (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`), and user
+     * overrides in `bindings.overlay` apply.
+     *
+     * @returns What the key did: `"ran"`, `"reason"` or `"passed"`.
      *
      * @example
      * ```ts
@@ -1763,11 +1772,28 @@ export class TestHost {
      */
     async press(binding, options = {}) {
         const claims = this.#claims();
-        const id = (options.panel ? claims.get(`panel ${binding}`)?.[0] : undefined) ??
-            claims.get(`global ${binding}`)?.[0];
-        if (!id)
+        const ids = [
+            ...(options.panel ? (claims.get(`panel ${binding}`) ?? []) : []),
+            ...(claims.get(`global ${binding}`) ?? []),
+        ];
+        if (!ids.length)
             throw new Error(`test host: nothing is bound to ${binding}`);
-        await (this.coreCommands.get(id) ?? this.command(id)).run();
+        const command = (id) => this.coreCommands.get(id) ?? this.command(id);
+        const enabled = ids.find((id) => command(id).state.enabled);
+        if (enabled !== undefined) {
+            await command(enabled).run();
+            return "ran";
+        }
+        for (const id of ids) {
+            const reason = this.commands.has(id)
+                ? command(id).display.reason
+                : command(id).state.reason;
+            if (typeof reason === "string" && reason !== "") {
+                this.osd.push(reason);
+                return "reason";
+            }
+        }
+        return "passed";
     }
     /**
      * Bindings declared by more than one command, each as

package/llms-full.txt

@@ -1,4 +1,4 @@
-# @vestra-player/sdk 1.5.11: full reference
+# @vestra-player/sdk 1.5.12: full reference
 
 > Everything needed to write a Vestra Player plugin (plugin API `vestra/1`): the guides, every public declaration of `@vestra-player/sdk` and `@vestra-player/sdk/testing` with its documentation, and the complete source of the example plugins. Generated from the SDK's sources by scripts/llms.mjs; the short index is llms.txt.
 
@@ -5230,11 +5230,12 @@ class TestHost implements Transport {
    */
   failStream(producerId: number, message: string): void;
   /**
-   * Press a binding like the host's table would: panel-focus bindings first when `panel` is true, then global ones; the earliest registration wins a conflict. Resolves after the command ran; rejects when nothing is bound or the command is disabled or busy. Bindings use the reference syntax (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`); the player's core actions match first, and user overrides in `bindings.overlay` apply.
+   * Press a binding like the host's table would: panel-focus bindings first when `panel` is true, then global ones; within a scope the earliest registration first (the player's own commands before the plugin's), as the conflict rule orders them. A disabled command lets the key pass to the next command bound to it (SDK 1.5.12, as player 0.4.3): the one it shadowed, then the global scope. The first enabled one runs; `press` resolves after it ran (`"ran"`), or rejects when it is busy. When only disabled commands hold the key, the first one with a `reason` shows the reason on the OSD and eats the key (`"reason"`, see `host.osd`); without a reason the key goes on to the focused control (`"passed"`, nothing runs). Rejects when nothing is bound. Bindings use the reference syntax (`"Space"`, `"Ctrl+O"`, `"Mouse:WheelUp"`), and user overrides in `bindings.overlay` apply.
+   * @returns What the key did: `"ran"`, `"reason"` or `"passed"`.
    */
   press(binding: string, options?: {
     panel?: boolean;
-  }): Promise<void>;
+  }): Promise<"ran" | "reason" | "passed">;
   /** Bindings declared by more than one command, each as `[binding, winner, ...ignored]` (command ids; core actions as `host/<id>`). Empty when there are none. */
   get conflicts(): string[][];
   /** The binding overlay `plugin.bindings.set` writes (`"<plugin>/<command>"` to inputs; preset it to simulate saved overrides). `press` honours it. */

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.5.11: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. llms-full.txt, next to this file, has every declaration, the guides and the examples; L<n> below are its line numbers.
+> @vestra-player/sdk 1.5.12: write plugins for Vestra Player in TypeScript (plugin API `vestra/1`). A plugin is a folder with `manifest.json` and an entry module whose default export `activate(plugin)` the player calls; it runs in its own Node.js process. llms-full.txt, next to this file, has every declaration, the guides and the examples; L<n> below are its line numbers.
 
 **How plugins run**
 
@@ -121,7 +121,7 @@ test("shows the position", async () => {
 - `vestra-plugin build [dir...] [--version x.y.z]`: Writes `dist/`: types stripped, files copied, manifest versioned.
 - `vestra-plugin pack [dir...] [--version x.y.z] [--out dir]`: Builds, then packs `dist/` as `<id>-<version>.vxp`.
 - `vestra-plugin i18n extract [dir...] [--locale lang]`: Collects the texts to translate into `locales/`, keeping translations.
-- `vestra-plugin i18n check [dir...]`: Translation coverage and untranslatable text (warnings only).
+- `vestra-plugin i18n check [dir...]`: Translation coverage and untranslatable text; fails on stale catalogs.
 - `vestra-player --plugin <dir>` runs a plugin from source, no build needed.
 
 **Error codes** (`error.code`; branch on it, never on `message`)
@@ -153,7 +153,7 @@ test("shows the position", async () => {
 - [How-to: Keep a slider responsive while dragging](https://vestrasys.github.io/vestra-player-sdk/documents/Keep_a_slider_responsive_while_dragging.html): L627–801
 - [How-to: Remember a window's state between runs](https://vestrasys.github.io/vestra-player-sdk/documents/Remember_a_window_s_state_between_runs.html): L802–931
 - [API: @vestra-player/sdk](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk.html): L932–4427
-- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html) (TestHost, startPlugin): L4428–5537
+- [API: @vestra-player/sdk/testing](https://vestrasys.github.io/vestra-player-sdk/modules/_vestra-player_sdk_testing.html) (TestHost, startPlugin): L4428–5538
 
 ## API
 
@@ -193,15 +193,15 @@ Where each module of `plugin` is declared:
 
 Complete plugins with tests, in [examples/](https://github.com/vestrasys/vestra-player-sdk/tree/main/examples) and in llms-full.txt:
 
-- hello: The README Quick start: one menu command and an on-screen message. L5954–6043
-- blur: A tool window with one slider that blurs the playing video. L6044–6305
-- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L6306–6638
-- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L6639–6823
-- panel-menu: A sidebar panel with its own right-click menu. L6824–7029
-- menus: Radio menu items, separator groups and a menu item whose title changes. L7030–7189
-- theme-widgets: A tool window drawn with the player's theme and widgets. L7190–7353
-- markdown: A window that shows a Markdown document. L7354–7547
-- i18n: A plugin in the player's language: English source text, a Chinese translation. L7548–7715
+- hello: The README Quick start: one menu command and an on-screen message. L5955–6044
+- blur: A tool window with one slider that blurs the playing video. L6045–6306
+- signal-generator: Generates its own video and audio: colour bars and a 1 kHz tone. L6307–6639
+- bookmark: A tool window bound to the playback state: remember the position and jump back to it. L6640–6824
+- panel-menu: A sidebar panel with its own right-click menu. L6825–7030
+- menus: Radio menu items, separator groups and a menu item whose title changes. L7031–7190
+- theme-widgets: A tool window drawn with the player's theme and widgets. L7191–7354
+- markdown: A window that shows a Markdown document. L7355–7548
+- i18n: A plugin in the player's language: English source text, a Chinese translation. L7549–7716
 
 ## Optional
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vestra-player/sdk",
-  "version": "1.5.11",
+  "version": "1.5.12",
   "description": "Plugin API types, test host and plugin CLI for Vestra Player (apiVersion vestra/1)",
   "license": "Apache-2.0",
   "repository": {

package/slint/vestra/widgets.slint

@@ -81,13 +81,17 @@ export component Button {
     min-height: root.icon-only ? root.icon-height : root.small ? Theme.button-small-height : Theme.button-height;
     min-width: root.icon-only ? root.icon-width : root.small ? Theme.button-small-min-width : Theme.button-min-width;
     preferred-height: self.min-height;
+    // A longer (translated) label widens the button instead of overflowing it.
+    preferred-width: root.icon-only ? self.min-width
+        : max(self.min-width, label.preferred-width + 2 * Theme.button-padding);
     accessible-role: button;
     accessible-label: root.text;
     accessible-enabled: root.enabled;
     accessible-checkable: root.icon-only;
     accessible-checked: root.checked;
     accessible-action-default => { if root.enabled { root.clicked(); } }
-    if !root.icon-only: Rectangle {
+    Rectangle {
+        visible: !root.icon-only;
         border-radius: Theme.radius-control;
         background: !root.enabled ? Theme.button-disabled
             : touch.pressed ? Theme.button-press
@@ -96,7 +100,7 @@ export component Button {
             padding-left: Theme.button-padding;
             padding-right: Theme.button-padding;
             alignment: center;
-            Text {
+            label := Text {
                 text: root.text;
                 color: root.enabled ? Theme.text-list : Theme.text-dim;
                 font-size: Theme.font-body;