@vestra-player/sdk 1.5.3 → 1.5.4

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.5.4
+
+**Markdown in list rows** (the player after 0.4.0). Additive; `apiVersion` stays `vestra/1`, and plugins written for 1.5.3 need no change.
+
+- **A `MarkdownRef` at any depth.** A document from `plugin.ui.markdown` may now be a field at any depth of a property value, wherever the Slint type is `[MarkdownBlock]`: for example the `body` of each row of a chat's `[Message]` list. Before, it could only be the whole value of a `[MarkdownBlock]` property. `PropValue` is now `PropData | ImageRef`, where the new **`PropData`** is JSON whose values may also be `MarkdownRef`s, at any depth. A released document is refused with `invalid` wherever it is in the value. An `ImageRef` stays a whole value only: nested in an array or object it is `invalid` (a type error in TypeScript, and refused by the SDK and the player). Older players refuse a nested document like any value they cannot convert.
+- **Limits:** a document still holds at most 256 KB of text, 4000 blocks and 64 images; all of a value's text, its documents' text included, counts toward the value's 1 MiB; each document is one of its 4096 values.
+- **`MarkdownBlocks`** (new in `@vestra/markdown.slint`): the blocks of a document without scrolling, as tall as their content, for your own layout or a `ListView` row. `in [MarkdownBlock] blocks`, `in bool code-copy` (default `false`), callbacks `link-clicked(string)` and `copy-code(string)`. `MarkdownView` is now a `ScrollView` around it and gains the same `code-copy` and `copy-code`; it looks as before.
+- **Code copy, opt in.** With `code-copy: true`, code blocks get a 复制 button that reports `copy-code(code)` with the block's text; the plugin copies it (`plugin.clipboard.writeText`). Off by default: views that do not set it look and behave as before.
+- **Cheaper updates** (player): writing a value again with unchanged documents does not parse them again (a new reference for the same text included), and a value with documents is updated in place where its shape allows: changed rows, rows added or removed at the end, and only the changed blocks of a changed document. Streaming a reply into the last row of a 200-message list therefore keeps the list, its scroll position and the other rows. Nothing to change in plugins.
+- `TestHost` keeps nested documents in the view's properties as they were sent; `host.markdown(value)` reads one back from a field (`host.markdown(rows[0].body)`).
 ## 1.5.3
 
 **File resolvers: local files as generated streams** (player 0.4.1). Additive; `apiVersion` stays `vestra/1`. Plugins that register one set `"minPlayerVersion": "0.4.1"`: an older player refuses the declaration (`invalid`).

package/dist/plugin/testing.d.ts

@@ -1128,9 +1128,16 @@ export declare class TestHost implements Transport {
      */
     readonly remoteImages: Map<string, string | null>;
     /**
-     * The Markdown document a property holds (its wire form read back), or
+     * The Markdown document a value holds (its wire form read back), or
      * `null` when the value is not one. `images` maps each remote address to
-     * the downloaded file.
+     * the downloaded file. Pass a whole property value or a field of one: a
+     * document nested in rows is read the same way.
+     *
+     * @example
+     * ```ts
+     * const rows = host.window("chat").props["messages"] as { body: Json }[];
+     * assert.equal(host.markdown(rows[0]!.body)?.text, "**Hello**");
+     * ```
      */
     markdown(value: Json | undefined): MarkdownWire | null;
     /**

package/dist/plugin/testing.js

@@ -1482,9 +1482,16 @@ export class TestHost {
      */
     remoteImages = new Map();
     /**
-     * The Markdown document a property holds (its wire form read back), or
+     * The Markdown document a value holds (its wire form read back), or
      * `null` when the value is not one. `images` maps each remote address to
-     * the downloaded file.
+     * the downloaded file. Pass a whole property value or a field of one: a
+     * document nested in rows is read the same way.
+     *
+     * @example
+     * ```ts
+     * const rows = host.window("chat").props["messages"] as { body: Json }[];
+     * assert.equal(host.markdown(rows[0]!.body)?.text, "**Hello**");
+     * ```
      */
     markdown(value) {
         const doc = value

package/dist/plugin/types.d.ts

@@ -562,18 +562,31 @@ export interface ImageRef {
     readonly __vestraImage: true;
 }
 /**
- * A Markdown document for `MarkdownView`, made by {@link Ui.markdown}.
+ * A Markdown document for `MarkdownView` or `MarkdownBlocks`, made by
+ * {@link Ui.markdown}.
  *
  * @remarks
- * Opaque, like {@link ImageRef}: pass it as the whole value of a
- * `[MarkdownBlock]` property (the `blocks` of `MarkdownView` from
- * `@vestra/markdown.slint`). It carries the text, the base address and the
- * local copies of its remote images; the player parses and draws it. It
- * belongs to the scope that created it: once that scope is disposed, writing
- * it fails with `invalid`.
- *
- * @player 0.2.0
- * @see {@link Ui.markdown}, {@link MarkdownOptions}
+ * Opaque, like {@link ImageRef}: pass it where the Slint type is
+ * `[MarkdownBlock]`: the whole value of such a property (the `blocks` of
+ * `MarkdownView` from `@vestra/markdown.slint`) or, from SDK 1.5.4, a
+ * `[MarkdownBlock]` field at any depth of a property value, such as the
+ * `body` of each row of a chat's message list. It carries the text, the
+ * base address and the local copies of its remote images; the player parses
+ * and draws it. Writing a document whose text did not change (a new
+ * reference for the same text included) costs the player no parsing, and a
+ * changed document updates only the blocks that changed. It belongs to the
+ * scope that created it: once that scope is disposed, writing it fails with
+ * `invalid`, wherever it is in the value.
+ *
+ * @example Chat messages, one document per row
+ * ```ts
+ * const chat = plugin.windows.create("ui/chat.slint");
+ * const body = await plugin.ui.markdown("**Hello**", { remoteImages: false });
+ * chat.set({ messages: [{ id: "m1", role: "assistant", body }] });
+ * ```
+ *
+ * @player 0.2.0; nested in a value: the player after 0.4.0
+ * @see {@link Ui.markdown}, {@link MarkdownOptions}, {@link PropValue}
  * @since 1.1.0
  * @category UI
  */
@@ -607,8 +620,9 @@ export interface MarkdownOptions {
     remoteImages?: boolean;
 }
 /**
- * The value of one Slint property: JSON, or an image or a Markdown document
- * as the whole value of a property.
+ * The value of one Slint property: JSON with Markdown documents at any
+ * depth ({@link PropData}), or an image as the whole value of an `image`
+ * property.
  *
  * @remarks
  * JSON becomes Slint values as you would expect: booleans for `bool`,
@@ -618,14 +632,37 @@ export interface MarkdownOptions {
  * is refused (Slint treats `_` and `-` as the same, so use camelCase or
  * kebab-case).
  *
- * Limits per value: nesting depth 8, 4096 values in total, 1024 rows per
- * array, 64 KiB per string and 1 MiB of text in total. A value over a limit
- * is a failed write (see {@link View}).
+ * A {@link MarkdownRef} goes where the Slint type is `[MarkdownBlock]`: the
+ * whole value, or a field at any depth (SDK 1.5.4; older players refuse a
+ * nested one). An {@link ImageRef} only as the whole value: nested in an
+ * array or object it is `invalid`.
+ *
+ * Limits per value: nesting depth 8, 4096 values in total (a document is
+ * one), 1024 rows per array, 64 KiB per string and 1 MiB of text in total,
+ * the text of its Markdown documents included (256 KB per document). A
+ * value over a limit is a failed write (see {@link View}).
  *
  * @since 1.0.0
  * @category UI
  */
-export type PropValue = Json | ImageRef | MarkdownRef;
+export type PropValue = PropData | ImageRef;
+/**
+ * JSON whose values may also be Markdown documents, at any depth: the part
+ * of {@link PropValue} that nests.
+ *
+ * @example A message list whose rows carry a document
+ * ```ts
+ * const messages: PropData = [
+ *   { id: "m1", role: "user", body: await plugin.ui.markdown("Hi") },
+ * ];
+ * ```
+ *
+ * @since 1.5.4
+ * @category UI
+ */
+export type PropData = null | boolean | number | string | MarkdownRef | PropData[] | {
+    [key: string]: PropData;
+};
 /**
  * Properties to write to a view, by name.
  *

package/dist/plugin/ui.js

@@ -31,18 +31,33 @@ export class ImageHandle {
         return { $vestraImage: this.path, ref: this.#ref };
     }
 }
-/** A property value as sent: images and documents in wire form; released ones refused. */
-function wireValue(value) {
+/**
+ * A property value as sent: images and documents in wire form, documents at
+ * any depth (released ones refused wherever they are); an image only as the
+ * whole value, like the player.
+ */
+function wireValue(value, nested = false) {
     if (value instanceof MarkdownHandle) {
         if (value.released)
             throw failure("invalid", "Markdown document was released with the scope that created it");
         return value.toJSON();
     }
-    if (!(value instanceof ImageHandle))
-        return value;
-    if (value.released)
-        throw failure("invalid", `image ${value.path} was released with the scope that created it`);
-    return value.toJSON();
+    if (value instanceof ImageHandle) {
+        if (nested)
+            throw failure("invalid", `image ${value.path}: an image reference must be the whole value of an image property`);
+        if (value.released)
+            throw failure("invalid", `image ${value.path} was released with the scope that created it`);
+        return value.toJSON();
+    }
+    if (Array.isArray(value))
+        return value.map((item) => wireValue(item, true));
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, item] of Object.entries(value))
+            out[key] = wireValue(item, true);
+        return out;
+    }
+    return value;
 }
 export const ui = (scope) => ({
     image(path) {

package/package.json

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

package/slint/vestra/markdown.slint

@@ -1,9 +1,14 @@
 // Markdown display (store proposal §5):
-//   import { MarkdownView, MarkdownBlock } from "@vestra/markdown.slint";
+//   import { MarkdownView, MarkdownBlocks, MarkdownBlock } from "@vestra/markdown.slint";
 // Give `blocks` the value of `plugin.ui.markdown(text)`; the player parses
 // the Markdown and fills the rows. Links report `link-clicked(url)` with the
 // address resolved against the document's base; the plugin decides what to
 // open (usually `plugin.system.openUrl`).
+// `MarkdownView` scrolls one document. `MarkdownBlocks` does not scroll and
+// is as tall as its content: put it in your own layout or in a `ListView`
+// row (a chat message: a `[MarkdownBlock]` field of the row's struct).
+// `code-copy: true` adds a 复制 button to code blocks that reports
+// `copy-code(code)`; the plugin copies it (`plugin.clipboard`).
 import { ScrollView } from "std-widgets.slint";
 import { Theme } from "theme.slint";
 import { Icon } from "icons.slint";
@@ -45,7 +50,9 @@ export struct MarkdownBlock {
 component MarkdownBlockView {
     in property <MarkdownBlock> block;
     in property <length> available;
+    in property <bool> code-copy;
     callback link-clicked(string);
+    callback copy-code(string);
     private property <length> quote-indent: block.quote * 12px;
     private property <length> list-indent: block.indent * 16px;
     private property <length> inner: max(16px, root.available - root.quote-indent - root.list-indent);
@@ -124,6 +131,24 @@ component MarkdownBlockView {
                         default-font-size: Theme.font-body;
                     }
                 }
+                if root.code-copy: Rectangle {
+                    x: parent.width - self.width - 4px;
+                    y: 4px;
+                    width: copy-label.preferred-width + 12px;
+                    height: Theme.button-small-height;
+                    border-radius: Theme.radius-control;
+                    background: copy-touch.pressed ? Theme.button-press : copy-touch.has-hover ? Theme.button-hover : Theme.button-bg;
+                    copy-label := Text {
+                        text: "复制";
+                        color: copy-touch.has-hover ? Theme.text : Theme.text-dim;
+                        font-size: Theme.font-body;
+                        vertical-alignment: center;
+                    }
+                    copy-touch := TouchArea {
+                        mouse-cursor: pointer;
+                        clicked => { root.copy-code(block.code); }
+                    }
+                }
             }
             if block.kind == "image" && block.has-image: HorizontalLayout {
                 alignment: start;
@@ -186,12 +211,38 @@ component MarkdownBlockView {
     }
 }
 
+// Markdown blocks without scrolling, as tall as their content.
+export component MarkdownBlocks inherits Rectangle {
+    in property <[MarkdownBlock]> blocks;
+    // A 复制 button on code blocks, reporting `copy-code(code)`.
+    in property <bool> code-copy: false;
+    callback link-clicked(string);
+    callback copy-code(string);
+    min-height: column.min-height;
+    preferred-height: column.preferred-height;
+    column := VerticalLayout {
+        width: root.width;
+        spacing: 8px;
+        alignment: start;
+        for block in root.blocks: MarkdownBlockView {
+            block: block;
+            available: root.width;
+            code-copy: root.code-copy;
+            link-clicked(url) => { root.link-clicked(url); }
+            copy-code(code) => { root.copy-code(code); }
+        }
+    }
+}
+
 // A scrolling Markdown document.
 export component MarkdownView inherits Rectangle {
     in property <[MarkdownBlock]> blocks;
     // Space around the document.
     in property <length> inset: 10px;
+    // A 复制 button on code blocks, reporting `copy-code(code)`.
+    in property <bool> code-copy: false;
     callback link-clicked(string);
+    callback copy-code(string);
     scroll := ScrollView {
         width: 100%;
         height: 100%;
@@ -200,12 +251,12 @@ export component MarkdownView inherits Rectangle {
         column := VerticalLayout {
             width: scroll.visible-width;
             padding: root.inset;
-            spacing: 8px;
             alignment: start;
-            for block in root.blocks: MarkdownBlockView {
-                block: block;
-                available: scroll.visible-width - 2 * root.inset;
+            MarkdownBlocks {
+                blocks: root.blocks;
+                code-copy: root.code-copy;
                 link-clicked(url) => { root.link-clicked(url); }
+                copy-code(code) => { root.copy-code(code); }
             }
         }
     }