@wildwinter/toolkit 0.2.4 → 0.2.6

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
@@ -98,6 +120,7 @@ whose field has a type other than the claim's is an error naming where (the host
 | `flags` | A set of `values` | `[]` | As a set, value by value |
 | `quality` | One stage of `stages` (at least two, none empty, none twice) | The first stage | Three-way |
 | `reference` | The id of a node of the kind named by `to` | `""` | Three-way; validated to exist |
+| `pick` | One choice from the sources in `from` (below), as text, or `""` (automatic) | `""` | Three-way; validated against its sources |
 | `record` | Named `fields`, each a field declaration | Each field's default | Field by field |
 | `map` | Entries keyed by `key` (`{ type: "text" }` or `{ type: "reference", to }`), each of type `of` | `{}` | Key by key, then by the value's own type |
 | `list` with `id` | Records, each carrying the text field named by `id`, unique in the list | `[]` | Union by id, each item by its own type; order kept |
@@ -113,6 +136,32 @@ A value that does not fit is reported by `valueProblems`, through the kernel's `
 names no stage carries the stages either side of it as `options` (the kernel's `stagesEitherSide`, the whole
 ladder for a stage that is gone).
 
+### Picks
+
+A pick is a single choice whose choices come from sources the manifest names, in the order they're shown:
+
+```json5
+{ name: "to", type: "pick", from: [{ words: ["all"] }, { to: "cast" }, { list: "pointsOfInterest" }] }
+```
+
+- `words`: fixed words, named once each.
+- `to`: the nodes of a reference kind (the table above), held by id as a reference holds them.
+- `list`: a list of text (`{ type: "list", of: { type: "text" } }`, no `id`) on the extension's own `project`
+  target, by that field's name; the project node's value, else the field's default (`pickLists`).
+
+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.
+
+`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
+such name once for the project (`pick-clash`). `pickChoices` lists the choices, source by source, for an editor to
+draw.
+
+A host that renames a node of a `to` source rewrites the values naming it, as it rewrites references. A renamed
+entry of a project list isn't followed: a list of text can't tell a rename from a removal and an addition, so a value
+naming the old entry is reported missing.
+
 ### Stage renames
 
 An extension's ladder belongs to its manifest. A version that renames a stage says so on the field:
@@ -189,7 +238,7 @@ This covers every shard of a format, not only extension shards.
 ## Conformance
 
 `conformance/extensions/*.json` are the contract: hand-written cases for manifest validation, value validation,
-defaults, stage renames and the merge, with their expectations. `test/extensions.test.ts` runs them. A host that
+defaults, stage renames, picks and the merge, with their expectations. `test/extensions.test.ts` runs them. A host that
 reimplements any part runs the same files.
 
 This entry needs `@wildwinter/expr` and `@wildwinter/scoperegistry` (the kernel's value and ladder rules, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wildwinter/toolkit",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "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",