@wildwinter/toolkit 0.2.5 → 0.2.7

package/extensions.md

@@ -48,6 +48,28 @@ read the same one. It is JSON (JSON5 is read too), and is called `<id>.extension
 - **Fields** per target, in the order the editor shows them.
 - **Claims** on host fields, named through a project setting.
 
+### Views and reads
+
+A manifest can declare views: web components in the extension's installed package, each opened by a host in a
+floating window of its own, sandboxed, talking to the host only through the host API (`@wildwinter/app-shell`'s
+`view-client`). The project's copy of the manifest declares them; the code comes from the package installed on the
+machine, never from the project folder.
+
+```json5
+views: [
+  { id: "sheet", name: "Performance sheet", entry: "view/sheet.js", element: "pattershot-sheet", hosts: ["patter"] },
+],
+reads: ["patterstage"],
+```
+
+- `id`: lower case, digits and hyphens, unique among the views; `name`: the window's title and the menu item.
+- `entry`: the component's script, a relative `.js` path inside the package, with no `.` or `..` segment
+  (`isViewEntry`). `element`: the custom element it defines, lower case with a hyphen, unique among the views.
+- `hosts`: the hosts that offer the view. When absent, every host the manifest targets does; naming a host the
+  manifest targets nothing in is a warning. `viewsFor(manifest, host)` lists what a host offers.
+- `reads`: other extensions whose data the views read, by id. An extension always reads its own; naming itself is a
+  warning.
+
 ### Field declarations
 
 ```json5
@@ -65,8 +87,8 @@ read the same one. It is JSON (JSON5 is read too), and is called `<id>.extension
 }
 ```
 
-- `label`, `help`, `valueHelp` (one sentence per enum or flags value or quality stage) and `group` are for the
-  editor, and never reach a bundle.
+- `label`, `help`, `valueHelp` (one sentence per enum or flags value, quality stage, or a pick's fixed word) and
+  `group` are for the editor, and never reach a bundle.
 - `required`, `min` and `max` (numbers only) are validation.
 - `editorOnly` is allowed on a target's own fields only, not inside a record.
 
@@ -130,6 +152,8 @@ A pick is a single choice whose choices come from sources the manifest names, in
 Empty is automatic: no word for it is stored, and an editor shows it as "auto". A pick isn't an `enum` whose values
 change: an enum's values are fixed and checked against the manifest, a pick's are the project's.
 
+`valueHelp` may describe a pick's fixed `words`, never its nodes or lists, which are the project's.
+
 `valueProblems` reports a value no source holds (`not-a-choice`, an error), given the host's nodes (`exists`) and
 lists (`list`) in its context; a source it can't see is not checked, so a value is reported missing only when every
 source can say. A value two sources hold is ambiguous (`pick-ambiguous`, a warning), and `pickClashes` reports each

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildwinter/toolkit",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Small shared pieces of the authoring tooling: opaque ids, a stable hash, JSON5 source parsing, find/replace matching, the archive guards, and (in ./extensions) the spec and merge for Patter extensions and Storylet extensions. Nothing here runs in a game.",
   "type": "module",
   "license": "MIT",