@wildwinter/toolkit 0.2.7 → 0.3.1

package/extensions.md

@@ -23,14 +23,10 @@ read the same one. It is JSON (JSON5 is read too), and is called `<id>.extension
   name: "Pattershot",
   version: "1.2.0",               // major.minor.patch
   docs: "https://example.com/pattershot",
-  settings: [                     // project settings, each naming a host field a claim presents
-    { name: "moodField", label: "Mood field", help: "The card field holding the mood.", default: "mood" },
-  ],
   targets: {
     storylets: {                  // a host: "patter" or "storylets"
       card: {                     // a node kind of that host
         fields: [ /* field declarations, below */ ],
-        claims: [ /* claims on host fields, below */ ],
       },
     },
   },
@@ -40,13 +36,13 @@ read the same one. It is JSON (JSON5 is read too), and is called `<id>.extension
 - **Identity**: `id`, `name`, `version`, and optionally `docs`, a link to the extension's own documentation.
 - **Targets**, by host and node kind:
 
-  | Host | Node kinds | References | Kinds with host fields (claimable) |
-  |---|---|---|---|
-  | `patter` | `scene`, `block`, `snippet`, `line`, `text`, `gameEvent`, `option`, `project` | `cast`, `scene`, `block`, `snippet`, `line` | every kind but `project` (game data) |
-  | `storylets` | `box`, `tagGroup`, `tag`, `deck`, `card`, `outcome`, `handTemplate`, `hand`, `project` | `box`, `deck`, `card`, `outcome`, `tag` | `card`, `outcome` (fields) |
+  | Host | Node kinds | References |
+  |---|---|---|
+  | `patter` | `scene`, `block`, `snippet`, `line`, `text`, `gameEvent`, `option`, `project` | `cast`, `scene`, `block`, `snippet`, `line` |
+  | `storylets` | `box`, `tagGroup`, `tag`, `deck`, `card`, `outcome`, `handTemplate`, `hand`, `project` | `box`, `deck`, `card`, `outcome`, `tag` |
 
-- **Fields** per target, in the order the editor shows them.
-- **Claims** on host fields, named through a project setting.
+- **Fields** per target, in the order the editor shows them. An extension's data is always its own: it never puts
+  its control on a field the host already has. A value the whole project shares is a field on the `project` target.
 
 ### Views and reads
 
@@ -70,6 +66,18 @@ reads: ["patterstage"],
 - `reads`: other extensions whose data the views read, by id. An extension always reads its own; naming itself is a
   warning.
 
+### Requirements
+
+```json5
+requires: ["patterstage"],
+```
+
+`requires` names other extensions, by id, that a project must take for this one to work: Pattershot's runner
+attaches to Patterstage's Director, so a project with Pattershot and no Patterstage can't play its performances.
+Each id appears once, and never the extension's own. A host refuses to add an extension whose requirements the
+project doesn't take (or offers to add them first), its validation warns of a project that takes one without them,
+and it tells the extension's views which are missing. `missingRequirements(manifest, taken)` lists them.
+
 ### Field declarations
 
 ```json5
@@ -84,6 +92,7 @@ reads: ["patterstage"],
   required: true,                 // a node of this kind must set it
   group: "Delivery",              // a heading within the extension's group, in field order
   editorOnly: true,               // stripped at compile; editor data, never in the bundle
+  editor: "sheet",                // a map of records only: one of the manifest's views edits it
 }
 ```
 
@@ -91,23 +100,17 @@ reads: ["patterstage"],
   `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.
+- `editor` names one of the manifest's views, by id, that edits the field: the host's inspector opens that view at
+  the node instead of its own grid for a map of records. It's allowed on a target's own fields only, the view must
+  open in that target's host, and on a field that isn't a map of records it's warned of and ignored, as such a field
+  is edited in place.
 
-### Claims on host fields
-
-A claim presents a field the host already has, with this manifest's control, help and validation, without moving the
-data. It names the field through a setting, so a project whose field has another name says so once:
-
-```json5
-{ setting: "moodField", type: "enum", values: ["calm", "tense"], label: "Mood", help: "..." }
-```
+### Removed keys
 
-A claim is a scalar. It may leave out an enum's or flags' `values` and a quality's `stages`: the host's
-declaration is then the vocabulary, as the host's ladder always is, and the claim adds its label, help and
-`valueHelp`, which may describe values the host does not declare (they are simply unused). `effectiveClaim(claim,
-hostDecl)` gives the declaration a host draws and checks the field with. The project names the extension's settings when it opts in (each host's project shard says
-how); a setting the project leaves out takes the setting's `default`. A claimed field keeps the host's own merge
-rule, ladder and renames. Two extensions claiming one field is an error naming both (`claimClashes`); a host
-whose field has a type other than the claim's is an error naming where (the host checks: in Storylets, per box).
+Earlier versions of the spec had `settings`, each naming a host field, and `claims` on a target, presenting that
+host field with the manifest's control. Both are gone: a manifest that still carries one is warned of by name
+(`removed-key`) and the key is ignored. Declare a field of the extension's own instead, which the runtimes hand
+the game with every other extension value.
 
 ## The types
 

package/package.json

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