@vestra-player/sdk 1.6.7 → 1.6.8

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.6.8
+
+**Who must change: nobody; authors of a bottom bar should move to `content-min-width`.** Documentation, a read-only Slint property and a removed CLI warning: no change to the TypeScript API, the wire or `TestHost`, `apiVersion` stays `vestra/1`, no new capability. A plugin's `button` declarations stay as they are. A bottom bar that still places `BarButtons` keeps working on player 0.7.6 (it shows that strip, and the player draws no second one); it is deprecated and goes in a later patch.
+
+- **The player places the bottom bar's button strip** (player 0.7.6, menu redesign step 3a). It draws the strip at the right end of the bottom slot, also when no plugin mounts a bottom bar (in a band of its own): the plugins' buttons, a » menu, the player's **Command Palette** (`host/palette`, a magnifier) and **Toggle Sidebar**. [Bottom-bar buttons](docs/explanation/commands.md#bottom-bar-buttons) now reads: buttons are ordered by `order`, then by plugin id; lower `order` comes first and stays visible longest; when the strip runs out of room, or more than 8 plugin buttons are declared, the remaining buttons move to the » menu, in the same order; a button is never dropped. Before player 0.7.6 a narrow strip lost its lowest orders first and the player left out all but the eight highest; `BAR_BUTTON_LIMITS.total` is now what the strip holds. [Reference: commands](docs/reference/commands.md#bottom-bar-buttons), [Reference: limits](docs/reference/limits.md#bottom-bar-buttons), `CommandButton`, `CommandOptions.button` and `BAR_BUTTON_LIMITS` say so.
+- **Writing a bottom bar** ([Interface guidelines](docs/guidelines/interface.md#writing-a-bottom-bar)): a bar places nothing. It reports the least width of its own controls in a `content-min-width` length property on the mounted component (the player gives the strip the rest, so the time label is never covered) and ends its row at the strip, reading `BarButtonsHost.width` (new, read only; `fixed` for an optional control kept ahead of plugin buttons) from `@vestra/bar-buttons.slint`. The file stays in the Slint library copy for that global; its `BarButtons` component is deprecated.
+- **`@vestra/bar-buttons.slint`** (the read-only copy of the player's widget library, synced): `BarButtonsHost` gains `width`, `fixed`, `shown` and `more` (out: the strip's width, the cells a bar must leave free (the player's own and the » cell), the plugin buttons in the strip, whether » shows) and the player's `palette`, `overflow` and `room`; the comments describe the player's strip and mark `BarButtons` deprecated.
+- **`vestra-plugin check` no longer warns** that a bottom bar does not place `BarButtons`: since player 0.7.6 that is the right thing to do.
+
 ## 1.6.7
 
 **Who must change: nobody.** The 1.6.6 release below, published again under a new number: its npm publish failed (the provenance transparency log returned 500, then 409 for the same tarball), so 1.6.6 never reached npm. Nothing else changed.

package/bin/vestra-plugin.mjs

@@ -81,7 +81,6 @@ import {
   basename,
   dirname,
   extname,
-  isAbsolute,
   join,
   relative,
   resolve,
@@ -363,10 +362,7 @@ async function check(target, report = null) {
   }
   say(`${target.name}: capabilities declared for every API use`);
   if (report) return;
-  for (const line of [
-    ...(await bottomBarWarnings(target)),
-    ...(await forWarnings(target)),
-  ])
+  for (const line of await forWarnings(target))
     console.log(`${target.name}: warning: ${line}`);
   // Translation warnings never fail the check.
   if (present(join(target.directory, "locales"))) {
@@ -432,85 +428,6 @@ function slintCode(text) {
   return out;
 }
 
-/** Whether `path` lies inside `directory` (not a sibling sharing its prefix). */
-function inside(directory, path) {
-  const rel = relative(resolve(directory), path);
-  return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
-}
-
-/**
- * Whether the Slint file at `file` (relative to the plugin directory)
- * imports `BarButtons` from `@vestra/bar-buttons.slint`, itself or
- * through the plugin's own Slint files (relative paths, any depth, inside
- * the plugin directory). Local re-exports count as such files too:
- * `export { Row } from "row.slint"` and `export * from "row.slint"` are
- * followed, and `export { BarButtons } from "@vestra/bar-buttons.slint"` (or
- * `export * from` it) in a file the bar imports counts as placing it.
- * Comments do not count.
- */
-async function importsBarButtons(target, file, seen = new Set()) {
-  const path = resolve(target.directory, file);
-  if (seen.has(path) || !inside(target.directory, path)) return false;
-  seen.add(path);
-  const text = await readFile(path, "utf8").catch(() => null);
-  if (text === null) return false;
-  const code = slintCode(text);
-  // { names (or "*"), from }: imports, and re-exports with a source file.
-  const imports = [
-    ...code.matchAll(
-      /\b(?:import|export)\s*(?:(\*)\s*from\s*|\{([^}]*)\}\s*from\s*)?"([^"]+)"/g,
-    ),
-  ].map(([, star, names, from]) => ({ names: star ?? names ?? "", from }));
-  for (const { names, from } of imports)
-    if (
-      from === "@vestra/bar-buttons.slint" &&
-      (names === "*" ||
-        names
-          .split(",")
-          .some((name) => /^BarButtons(\s+as\s+[\w-]+)?$/.test(name.trim())))
-    )
-      return true;
-  for (const { from } of imports) {
-    if (
-      from.startsWith("@") ||
-      !from.endsWith(".slint") ||
-      from === "std-widgets.slint"
-    )
-      continue;
-    if (await importsBarButtons(target, join(dirname(file), from), seen))
-      return true;
-  }
-  return false;
-}
-
-/**
- * A plugin that mounts a bottom bar (`panels.mount("bottom", "<file>")`)
- * whose Slint file does not import `BarButtons` (`@vestra/bar-buttons.slint`),
- * itself or through its local imports: while it is the bottom bar, no
- * plugin's command button shows (SDK 1.5.29). The mount is read from the
- * source text: a literal file name in the call.
- */
-async function bottomBarWarnings(target) {
-  const { typescript: sources } = await sourceFiles(target);
-  const files = new Set();
-  for (const file of sources) {
-    const text = await readFile(join(target.directory, file), "utf8");
-    for (const match of text.matchAll(
-      /\.mount\(\s*["'`]bottom["'`]\s*,\s*["'`]([^"'`$]+)["'`]/g,
-    ))
-      files.add(match[1]);
-  }
-  const warnings = [];
-  for (const file of files) {
-    if (!present(join(target.directory, file))) continue;
-    if (await importsBarButtons(target, file)) continue;
-    warnings.push(
-      `${file} is a bottom bar without BarButtons (import { BarButtons } from "@vestra/bar-buttons.slint"): while it is mounted, the command buttons of every plugin (and the player's sidebar toggle) show nowhere; see docs/guidelines/interface.md#writing-a-bottom-bar`,
-    );
-  }
-  return warnings;
-}
-
 /**
  * A `for` over an array the plugin binds (an `in` or `in-out` property of
  * array type of a component or global in the same file), outside a

package/dist/commands.d.ts

@@ -158,12 +158,11 @@ export declare const BAR_BUTTON_ICONS: readonly ["play", "pause", "stop", "back"
 /**
  * The player's limits on bottom-bar buttons (`CommandOptions.button`), the
  * same values as the player's (its tests check that they agree). A button
- * past `perPlugin` or `total` is left out: its command still registers and
- * its menu entry stays, and the player logs the button it left out
- * (`limit`). Which ones stay: each plugin's first declared button, then the
- * `total` highest by order, plugin id and declaration order: as in a narrow
- * strip, the lowest order goes first (equal orders: the smaller plugin id,
- * then the earlier declaration, goes first).
+ * past `perPlugin` has none (its command still registers and its menu entry
+ * stays). `total` is what the strip holds: the `total` lowest by order,
+ * plugin id and declaration order; the rest are in the strip's » menu, in
+ * the same order (older players keep the `total` highest and leave the
+ * others out).
  *
  * @since 1.5.29
  *
@@ -172,7 +171,7 @@ export declare const BAR_BUTTON_ICONS: readonly ["play", "pause", "stop", "back"
 export declare const BAR_BUTTON_LIMITS: {
     /** Buttons one plugin shows (1). */
     readonly perPlugin: 1;
-    /** Buttons the player shows, every plugin together, besides its own sidebar toggle (8). */
+    /** Buttons in the strip, every plugin together, besides the player's own (8); the rest are in its » menu. */
     readonly total: 8;
     /** The highest `order` (999; the lowest is 0). */
     readonly maxOrder: 999;

package/dist/commands.js

@@ -202,12 +202,11 @@ export const BAR_BUTTON_ICONS = [
 /**
  * The player's limits on bottom-bar buttons (`CommandOptions.button`), the
  * same values as the player's (its tests check that they agree). A button
- * past `perPlugin` or `total` is left out: its command still registers and
- * its menu entry stays, and the player logs the button it left out
- * (`limit`). Which ones stay: each plugin's first declared button, then the
- * `total` highest by order, plugin id and declaration order: as in a narrow
- * strip, the lowest order goes first (equal orders: the smaller plugin id,
- * then the earlier declaration, goes first).
+ * past `perPlugin` has none (its command still registers and its menu entry
+ * stays). `total` is what the strip holds: the `total` lowest by order,
+ * plugin id and declaration order; the rest are in the strip's » menu, in
+ * the same order (older players keep the `total` highest and leave the
+ * others out).
  *
  * @since 1.5.29
  *
@@ -216,7 +215,7 @@ export const BAR_BUTTON_ICONS = [
 export const BAR_BUTTON_LIMITS = {
     /** Buttons one plugin shows (1). */
     perPlugin: 1,
-    /** Buttons the player shows, every plugin together, besides its own sidebar toggle (8). */
+    /** Buttons in the strip, every plugin together, besides the player's own (8); the rest are in its » menu. */
     total: 8,
     /** The highest `order` (999; the lowest is 0). */
     maxOrder: 999,

package/dist/plugin/testing.d.ts

@@ -2645,8 +2645,8 @@ export declare class TestHost implements Transport {
      * The plugin's bottom-bar buttons (`CommandOptions.button`) as the player
      * shows them: at most one, the first declared (`BAR_BUTTON_LIMITS`; a
      * later one stays a menu item only). Empty once the command is disposed.
-     * Whether the bar places them is the bar's business: the list is what
-     * the player hands to `BarButtons`.
+     * Whether one is in the strip or its » menu is the player's business
+     * (the room and the other plugins' buttons).
      *
      * @example Click the plugin's bottom-bar button in a test
      * The test finds the plugin's Store button, clicks it and checks that the

package/dist/plugin/testing.js

@@ -3405,8 +3405,8 @@ export class TestHost {
      * The plugin's bottom-bar buttons (`CommandOptions.button`) as the player
      * shows them: at most one, the first declared (`BAR_BUTTON_LIMITS`; a
      * later one stays a menu item only). Empty once the command is disposed.
-     * Whether the bar places them is the bar's business: the list is what
-     * the player hands to `BarButtons`.
+     * Whether one is in the strip or its » menu is the player's business
+     * (the room and the other plugins' buttons).
      *
      * @example Click the plugin's bottom-bar button in a test
      * The test finds the plugin's Store button, clicks it and checks that the

package/dist/plugin/types.d.ts

@@ -954,17 +954,17 @@ export type BarButtonIcon = "play" | "pause" | "stop" | "back" | "forward" | "op
  * A command's button on the bottom bar: {@link CommandOptions.button}.
  *
  * @remarks
- * **Where it shows.** The bottom bar places the player's strip of command
- * buttons, `BarButtons` from `@vestra/bar-buttons.slint`, at its right end;
- * the player fills it with the buttons of every plugin, left to right by
- * `order`, and its own sidebar toggle rightmost. When the window is narrow
- * the strip loses cells from its outer (left) end inward: the lowest order
- * goes first, the sidebar toggle last. A
- * bottom bar that does not place `BarButtons` shows no buttons: the
- * command's menu entry stays, and the player logs the buttons it cannot
- * show and whose bar hides them. The built-in bar (`vestra.playback`) places
- * it; see
- * [Writing a bottom bar](../../docs/guidelines/interface.md#writing-a-bottom-bar).
+ * **Where it shows.** The player draws the bottom bar's button strip and
+ * decides where it goes: today at the right end of the bottom bar; this may
+ * change (older players let the bar place `BarButtons` itself). Buttons
+ * are ordered by `order`, then by plugin id; lower `order` comes first and
+ * stays visible longest. When the strip runs out of room, or more than 8
+ * plugin buttons are declared, the remaining buttons move to the strip's »
+ * menu, in the same order. A button is never dropped: it is either in the
+ * strip or in the » menu, and its command keeps its menu entry, its key and
+ * its place in the command palette. Users may pin and unpin buttons later;
+ * do not rely on a position. See
+ * [Bottom-bar buttons](../../docs/explanation/commands.md#bottom-bar-buttons).
  *
  * **What it shows.** The icon, the command's title (translated, a trailing
  * "…" removed) and its first key as the tooltip ("Plugin Store (F9)"),
@@ -974,9 +974,9 @@ export type BarButtonIcon = "play" | "pause" | "stop" | "back" | "forward" | "op
  * a command with `checked` shows a small dot under its icon while checked.
  * A click runs the command exactly like a click on its menu item.
  *
- * **Limits.** One button per plugin and eight in the player
- * (`BAR_BUTTON_LIMITS`): a button past them is left out (its command and
- * menu entry stay) and the player logs it with `limit`. The button goes
+ * **Limits.** One button per plugin, the first it declares (a later one
+ * stays a menu item only), and eight in the strip (`BAR_BUTTON_LIMITS`); the
+ * rest are in the » menu. The button goes
  * with its command: disposing the command, or disabling, stopping or
  * uninstalling the plugin, removes it.
  *
@@ -984,8 +984,7 @@ export type BarButtonIcon = "play" | "pause" | "stop" | "back" | "forward" | "op
  * A Store icon appears in the bottom bar's button strip; a click opens
  * the store window, exactly like the menu item. The player draws the
  * button from the command's title, keys and state, and places it by
- * `order` (200 is where the player's own Plugin Store button sits); a
- * bar that does not place `BarButtons` shows only the menu item.
+ * `order` (200 is where the player's own Plugin Store button sits).
  * ```ts
  * const store = plugin.windows.create("ui/store.slint");
  * plugin.commands.add({
@@ -1238,8 +1237,8 @@ export interface CommandOptions {
     /**
      * A button for this command on the bottom bar (SDK 1.5.29, player 0.5.10):
      * an icon and a place, `{ icon: "store", order: 200 }`. Needs a `path`: the
-     * menu entry is where the command stays reachable when the bar shows no
-     * button (a bar without `BarButtons`, a narrow window, a limit). See
+     * menu entry is where the command stays reachable wherever the button
+     * is (the strip or its » menu). See
      * {@link CommandButton} for where it shows, what it shows and the limits.
      * Fails with `invalid` for an unknown icon name, an order outside 0–999 or
      * a button without a path.

package/llms.txt

@@ -1,6 +1,6 @@
 # Vestra Player SDK
 
-> @vestra-player/sdk 1.6.7: 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. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
+> @vestra-player/sdk 1.6.8: 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. The documentation is a tree of short pages read by path, like `go doc`: the same pages and API as https://vestrasys.github.io/vestra-player-sdk/.
 
 ## Read the documentation
 

package/package.json

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

package/slint/vestra/bar-buttons.slint

@@ -1,15 +1,26 @@
-// Command buttons of a bottom bar (player 0.5.10, SDK 1.5.29): the buttons
+// Command buttons of the bottom bar (player 0.5.10, SDK 1.5.29): the buttons
 // that plugins' commands contribute (`commands.add({ button })`) and the
-// player's sidebar toggle, rightmost. The player fills `BarButtonsHost` in
-// every window it composes and runs the clicks; a bottom bar places one
-// `BarButtons` in its own layout and gives it the width it can spare:
-//   import { BarButtons } from "@vestra/bar-buttons.slint";
-//   strip := BarButtons { x: parent.width - self.width - 4px; room: ...; }
-// It shows as many 41×40 cells as fit in `room`, the strip as wide as the
-// cells shown (`width`). Cells go from the strip's outer (left) end inward:
-// of the plugins' buttons (ascending `order`, left to right) the lowest
-// order goes first, and the sidebar toggle goes last. A bar without a `BarButtons` shows none of them (their menu
-// entries stay; the player logs which buttons are hidden).
+// player's own. Since SDK 1.6.8 (menu redesign step 3a) the player draws
+// the strip itself, at the right end of the bottom slot, its 40px cells on
+// the slot's bottom edge (a bar's 40px button row), and also when no plugin
+// mounts a bottom bar: `[plugin buttons…][»][Command Palette][Toggle
+// Sidebar]`. A bottom bar places nothing: it lays its controls out left of
+// the strip and says how wide they must stay:
+//   import { BarButtonsHost } from "@vestra/bar-buttons.slint";
+//   export component MyBar inherits Rectangle {
+//       out property <length> content-min-width: ...; // the least your row needs
+//       // your row ends at: root.width - BarButtonsHost.width - 4px
+//   }
+// The player gives its strip `bar width - content-min-width - 4px` (all of
+// the width without `content-min-width`), so plugin buttons never cover
+// what the bar needs (its time label, UI-BAR-10). Plugin buttons go left to
+// right by ascending `order`, then plugin id, then registration; at most 8
+// are in the strip, and the ones past 8 or past the room are in the `»`
+// menu, in the same order: the lowest order stays longest. `»` shows only
+// while something is in it; the player's own cells always show.
+//
+// `BarButtons` (below) is deprecated: the strip a bar placed itself before
+// SDK 1.6.8. While a bar still places it, the player draws no second strip.
 //
 // The cells look like the bar's own icon buttons: a 32×32 plate on hover
 // and press, the bar's tooltip (ToolTipArea). Every enabled cell draws its
@@ -43,14 +54,56 @@ export struct BarButtonItem {
     dimmed: bool,
 }
 
-// Filled by the player; a bar reads it only through `BarButtons`.
+// Filled by the player. A bar reads `width` (to end its own row left of
+// the strip) and `fixed`; everything else is the player's.
 export global BarButtonsHost {
-    // The plugins' buttons, left to right, at most 8.
+    // The plugins' buttons for the strip, left to right, at most 8.
     in property <[BarButtonItem]> buttons;
+    // How many plugin buttons are past those 8 (always in the `»` menu).
+    in property <int> overflow;
     // The sidebar toggle (`token` "" while there is none).
     in property <BarButtonItem> toggle;
-    // Set when a `BarButtons` exists in this window.
+    // The command palette (`host/palette`; `token` "" while there is none).
+    in property <BarButtonItem> palette;
+    // Set when a (deprecated) `BarButtons` exists in this window.
     in-out property <bool> placed;
+    // The width the player gives its strip (the player sets it).
+    in-out property <length> room;
+    // The player's own cells, always shown (step 3b adds Adjust).
+    private property <int> own: (root.palette.token != "" ? 1 : 0) + (root.toggle.token != "" ? 1 : 0);
+    // The cells a bar must always leave free, 41px each: the player's own,
+    // and the `»` cell whenever any plugin button exists (drawn only on
+    // overflow, but always reserved, so `»` never covers the bar). Never
+    // depends on `room`. A bar that keeps an optional control ahead of the
+    // plugins' buttons counts it in `content-min-width` while it fits
+    // beside these.
+    out property <int> fixed: root.own + (root.buttons.length > 0 || root.overflow > 0 ? 1 : 0);
+    // The strip's layout for a room, as pure functions, so the player's
+    // strip binds them to its own `room` (no frame behind the shell's
+    // layout) and the properties below give the same numbers for `room`.
+    // The plugin buttons in the strip (the first of `buttons`) at `room`.
+    public pure function shown-in(room: length) -> int {
+        // Cells left for plugin buttons and `»`.
+        let free = Math.max(0, Math.floor(room / 41px) - root.own);
+        if root.overflow == 0 && root.buttons.length <= free {
+            return root.buttons.length;
+        }
+        return Math.max(0, Math.min(root.buttons.length, free - 1));
+    }
+    // Whether `»` shows at `room` (a button past 8 or past the room).
+    public pure function more-in(room: length) -> bool {
+        return root.shown-in(room) < root.buttons.length || root.overflow > 0;
+    }
+    // The strip's width at `room` (0 while a bar places `BarButtons`).
+    public pure function width-in(room: length) -> length {
+        if root.placed {
+            return 0px;
+        }
+        return (root.shown-in(room) + (root.more-in(room) ? 1 : 0) + root.own) * 41px;
+    }
+    out property <int> shown: root.shown-in(root.room);
+    out property <bool> more: root.more-in(root.room);
+    out property <length> width: root.width-in(root.room);
     // A click on the cell with this token.
     callback clicked(string);
 }
@@ -127,8 +180,11 @@ component Cell inherits Rectangle {
     }
 }
 
-// The strip: place it at the bar's right end and give it the width you can
-// spare; it is as wide as the cells it shows (read `width` to lay out the rest).
+// Deprecated (SDK 1.6.8; the player places its strip): the strip a bar
+// placed at its right end with the width it could spare. A bar that still
+// places it shows this one instead of the player's (no palette cell, no
+// `»`): the cells that fit in `room`, lost from its outer (left) end
+// inward, the sidebar toggle last; it is as wide as the cells it shows.
 export component BarButtons {
     // The width the bar can give the strip; the cells that fit show.
     in property <length> room;