@wildwinter/toolkit 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @wildwinter/toolkit
 
+## 0.2.7
+
+### Added
+
+- **Value help on a pick** (`./extensions`): a pick's `valueHelp` describes its fixed `words`, a sentence each; the
+  manifest check holds each key to one of them, since the project's lists and nodes are the project's to describe.
+
+## 0.2.6
+
+### Added
+
+- **Views and reads in a manifest** (`./extensions`, tier 2): `views` declares the web components an extension's
+  installed package supplies, each with an `id`, a `name`, an `entry` script inside the package, the custom `element`
+  it defines, and optionally the `hosts` that offer it; `reads` names the other extensions whose data the views read.
+  The manifest check holds both to their shape. `viewsFor(manifest, host)` lists the views a host offers, and
+  `isViewEntry` keeps an entry inside its package.
+
 ## 0.2.5
 
 ### Added

package/conformance/extensions/manifest.json

@@ -571,6 +571,81 @@
         }
       ]
     },
+    {
+      "name": "a pick's value help describes its fixed words, never its lists or nodes",
+      "manifest": {
+        "schema": "wildwinter/extension@0",
+        "id": "probe",
+        "name": "Probe",
+        "version": "1.0.0",
+        "targets": {
+          "patter": {
+            "project": {
+              "fields": [
+                {
+                  "name": "types",
+                  "type": "list",
+                  "of": {
+                    "type": "text"
+                  }
+                }
+              ]
+            },
+            "scene": {
+              "fields": [
+                {
+                  "name": "type",
+                  "type": "pick",
+                  "from": [
+                    {
+                      "words": [
+                        "ambient",
+                        "cinematic"
+                      ]
+                    },
+                    {
+                      "list": "types"
+                    },
+                    {
+                      "words": [
+                        "bark"
+                      ]
+                    }
+                  ],
+                  "valueHelp": {
+                    "ambient": "Voices from sources.",
+                    "bark": "A one-off line.",
+                    "duel": "One of the project's types: not the manifest's to describe."
+                  }
+                },
+                {
+                  "name": "to",
+                  "type": "pick",
+                  "from": [
+                    {
+                      "to": "cast"
+                    }
+                  ],
+                  "valueHelp": {
+                    "WREN": "A cast member."
+                  }
+                }
+              ]
+            }
+          }
+        }
+      },
+      "problems": [
+        {
+          "path": "targets.patter.scene.fields[0].valueHelp.duel",
+          "code": "value-help"
+        },
+        {
+          "path": "targets.patter.scene.fields[1].valueHelp.WREN",
+          "code": "value-help"
+        }
+      ]
+    },
     {
       "name": "a reference names a kind its host can point at",
       "manifest": {
@@ -1438,6 +1513,238 @@
           "code": "default-misfit"
         }
       ]
+    },
+    {
+      "name": "views and reads pass",
+      "manifest": {
+        "schema": "wildwinter/extension@0",
+        "id": "probe",
+        "name": "Probe",
+        "version": "1.0.0",
+        "targets": {
+          "patter": {
+            "line": {
+              "fields": [
+                {
+                  "name": "mood",
+                  "type": "text"
+                }
+              ]
+            }
+          }
+        },
+        "views": [
+          {
+            "id": "sheet",
+            "name": "Sheet",
+            "entry": "view/sheet.js",
+            "element": "probe-sheet"
+          },
+          {
+            "id": "cards",
+            "name": "Cards",
+            "entry": "cards.js",
+            "element": "probe-cards",
+            "hosts": [
+              "patter"
+            ]
+          }
+        ],
+        "reads": [
+          "patterstage"
+        ]
+      },
+      "problems": []
+    },
+    {
+      "name": "a view's shape is checked",
+      "manifest": {
+        "schema": "wildwinter/extension@0",
+        "id": "probe",
+        "name": "Probe",
+        "version": "1.0.0",
+        "targets": {
+          "patter": {
+            "line": {
+              "fields": [
+                {
+                  "name": "mood",
+                  "type": "text"
+                }
+              ]
+            }
+          }
+        },
+        "views": [
+          {
+            "id": "Sheet",
+            "name": " ",
+            "entry": "../sheet.js",
+            "element": "sheet",
+            "colour": "red"
+          },
+          {
+            "id": "two",
+            "name": "Two",
+            "entry": "/abs/two.js",
+            "element": "Probe-Two",
+            "hosts": []
+          },
+          {
+            "id": "three",
+            "name": "Three",
+            "entry": "view\\three.js",
+            "element": "probe-three",
+            "hosts": [
+              "ink",
+              "storylets"
+            ]
+          },
+          {
+            "id": "three",
+            "name": "Again",
+            "entry": "view/again.mjs",
+            "element": "probe-three"
+          }
+        ]
+      },
+      "problems": [
+        {
+          "path": "views[0].colour",
+          "code": "unknown-key",
+          "severity": "warning"
+        },
+        {
+          "path": "views[0].id",
+          "code": "view-id"
+        },
+        {
+          "path": "views[0].name",
+          "code": "view-name"
+        },
+        {
+          "path": "views[0].entry",
+          "code": "view-entry"
+        },
+        {
+          "path": "views[0].element",
+          "code": "view-element"
+        },
+        {
+          "path": "views[1].entry",
+          "code": "view-entry"
+        },
+        {
+          "path": "views[1].element",
+          "code": "view-element"
+        },
+        {
+          "path": "views[1].hosts",
+          "code": "view-hosts"
+        },
+        {
+          "path": "views[2].entry",
+          "code": "view-entry"
+        },
+        {
+          "path": "views[2].hosts[0]",
+          "code": "unknown-host"
+        },
+        {
+          "path": "views[2].hosts[1]",
+          "code": "view-host-untargeted",
+          "severity": "warning"
+        },
+        {
+          "path": "views[3].id",
+          "code": "view-duplicate"
+        },
+        {
+          "path": "views[3].entry",
+          "code": "view-entry"
+        },
+        {
+          "path": "views[3].element",
+          "code": "view-duplicate"
+        }
+      ]
+    },
+    {
+      "name": "reads name other extensions, once each",
+      "manifest": {
+        "schema": "wildwinter/extension@0",
+        "id": "probe",
+        "name": "Probe",
+        "version": "1.0.0",
+        "targets": {
+          "patter": {
+            "line": {
+              "fields": [
+                {
+                  "name": "mood",
+                  "type": "text"
+                }
+              ]
+            }
+          }
+        },
+        "reads": [
+          "patterstage",
+          "probe",
+          "patterstage",
+          "Bad"
+        ]
+      },
+      "problems": [
+        {
+          "path": "reads[1]",
+          "code": "reads-self",
+          "severity": "warning"
+        },
+        {
+          "path": "reads[2]",
+          "code": "reads-duplicate"
+        },
+        {
+          "path": "reads[3]",
+          "code": "reads-id"
+        }
+      ]
+    },
+    {
+      "name": "views and reads must be lists",
+      "manifest": {
+        "schema": "wildwinter/extension@0",
+        "id": "probe",
+        "name": "Probe",
+        "version": "1.0.0",
+        "targets": {
+          "patter": {
+            "line": {
+              "fields": [
+                {
+                  "name": "mood",
+                  "type": "text"
+                }
+              ]
+            }
+          }
+        },
+        "views": {
+          "id": "sheet"
+        },
+        "reads": "patterstage"
+      },
+      "problems": [
+        {
+          "path": "views",
+          "code": "not-a-list"
+        },
+        {
+          "path": "reads",
+          "code": "not-a-list"
+        }
+      ]
     }
   ]
 }

package/dist/extensions.cjs

@@ -370,7 +370,9 @@ var TYPE_KEYS = ["type", "values", "stages", "renamedStages", "to", "from", "fie
 var FIELD_KEYS = /* @__PURE__ */ new Set([...TYPE_KEYS, "name", "label", "help", "required", "group", "editorOnly"]);
 var CLAIM_KEYS = /* @__PURE__ */ new Set([...TYPE_KEYS, "setting", "label", "help", "required"]);
 var BARE_KEYS = new Set(TYPE_KEYS);
-var MANIFEST_KEYS = /* @__PURE__ */ new Set(["schema", "id", "name", "version", "docs", "settings", "targets"]);
+var MANIFEST_KEYS = /* @__PURE__ */ new Set(["schema", "id", "name", "version", "docs", "settings", "targets", "views", "reads"]);
+var VIEW_KEYS = /* @__PURE__ */ new Set(["id", "name", "entry", "element", "hosts"]);
+var ELEMENT = /^[a-z][a-z0-9._]*-[a-z0-9._-]*$/;
 var err2 = (code, path, message) => ({ severity: "error", code, path, message });
 function parseManifest(text) {
   return parseSource(text);
@@ -392,6 +394,8 @@ function manifestProblems(manifest) {
   }
   if (m["docs"] !== void 0 && typeof m["docs"] !== "string") out.push(err2("docs", "docs", "docs is a link, as text"));
   const settings = settingsProblems(m["settings"], out);
+  viewsProblems(m["views"], m["targets"], out);
+  readsProblems(m["reads"], m["id"], out);
   const targets = m["targets"];
   if (!isObject(targets) || Object.keys(targets).length === 0) {
     out.push(err2("no-targets", "targets", "the manifest targets no host"));
@@ -420,6 +424,10 @@ function manifestProblems(manifest) {
   }
   return out;
 }
+function pickWords(from) {
+  if (!Array.isArray(from)) return [];
+  return from.flatMap((s) => isObject(s) && Array.isArray(s["words"]) ? s["words"].filter((w) => typeof w === "string") : []);
+}
 function pickSourcesSound(host, from, path, out) {
   if (!Array.isArray(from) || from.length === 0) {
     out.push(err2("pick-from", path, 'a pick lists its sources in "from": { "words": [...] }, { "to": a node kind }, or { "list": a project list }'));
@@ -490,6 +498,72 @@ function pickListProblems(kinds, hostPath, out) {
     target["fields"].forEach((f, i) => walk(f, atIndex(atKey(atKey(hostPath, kind), "fields"), i)));
   }
 }
+function isViewEntry(entry) {
+  if (typeof entry !== "string" || !entry.endsWith(".js") || entry.includes("\\")) return false;
+  const parts = entry.split("/");
+  return parts.every((p) => p !== "" && p !== "." && p !== "..");
+}
+function viewsProblems(views, targets, out) {
+  if (views === void 0) return;
+  if (!Array.isArray(views)) {
+    out.push(err2("not-a-list", "views", "views are a list"));
+    return;
+  }
+  const ids = /* @__PURE__ */ new Set();
+  const elements = /* @__PURE__ */ new Set();
+  const targeted = isObject(targets) ? Object.keys(targets) : [];
+  views.forEach((v, i) => {
+    const at = atIndex("views", i);
+    if (!isObject(v)) {
+      out.push(err2("not-an-object", at, "a view is an object"));
+      return;
+    }
+    unknownKeys(v, VIEW_KEYS, at, out);
+    const id = v["id"];
+    if (typeof id !== "string" || !ID.test(id)) out.push(err2("view-id", atKey(at, "id"), "a view's id is lower case letters, digits and hyphens, starting with a letter"));
+    else if (ids.has(id)) out.push(err2("view-duplicate", atKey(at, "id"), `two views are called "${id}"`));
+    else ids.add(id);
+    if (typeof v["name"] !== "string" || v["name"].trim() === "") out.push(err2("view-name", atKey(at, "name"), "a view has a name, shown as its window's title"));
+    if (!isViewEntry(v["entry"])) {
+      out.push(err2("view-entry", atKey(at, "entry"), "a view's entry is a .js file in the extension's package, as a relative path such as view/sheet.js"));
+    }
+    const element = v["element"];
+    if (typeof element !== "string" || !ELEMENT.test(element)) {
+      out.push(err2("view-element", atKey(at, "element"), "a view's element is a custom element name: lower case, starting with a letter, with a hyphen, such as probe-view"));
+    } else if (elements.has(element)) out.push(err2("view-duplicate", atKey(at, "element"), `two views define <${element}>`));
+    else elements.add(element);
+    const hosts = v["hosts"];
+    if (hosts === void 0) return;
+    if (!Array.isArray(hosts) || hosts.length === 0) {
+      out.push(err2("view-hosts", atKey(at, "hosts"), "a view's hosts are a list of at least one host"));
+      return;
+    }
+    hosts.forEach((h, j) => {
+      const hp = atIndex(atKey(at, "hosts"), j);
+      if (typeof h !== "string" || !own(HOSTS, h)) out.push(err2("unknown-host", hp, `${JSON.stringify(h)} is not a host; a view opens in "patter" or "storylets"`));
+      else if (!targeted.includes(h)) out.push({ severity: "warning", code: "view-host-untargeted", path: hp, message: `the view opens in ${h}, but the manifest targets nothing there` });
+    });
+  });
+}
+function readsProblems(reads, self, out) {
+  if (reads === void 0) return;
+  if (!Array.isArray(reads)) {
+    out.push(err2("not-a-list", "reads", "reads is a list of extension ids"));
+    return;
+  }
+  const seen = /* @__PURE__ */ new Set();
+  reads.forEach((r, i) => {
+    const at = atIndex("reads", i);
+    if (typeof r !== "string" || !ID.test(r)) out.push(err2("reads-id", at, "an extension read is named by its id: lower case letters, digits and hyphens"));
+    else if (r === self) out.push({ severity: "warning", code: "reads-self", path: at, message: "an extension always reads its own data; this entry is ignored" });
+    else if (seen.has(r)) out.push(err2("reads-duplicate", at, `"${r}" is listed twice`));
+    else seen.add(r);
+  });
+}
+function viewsFor(manifest, host) {
+  const targeted = Object.keys(manifest.targets ?? {});
+  return (Array.isArray(manifest.views) ? manifest.views : []).filter((v) => isObject(v) && typeof v.id === "string" && ID.test(v.id) && typeof v.name === "string" && isViewEntry(v.entry) && typeof v.element === "string" && ELEMENT.test(v.element) && (v.hosts === void 0 ? targeted.includes(host) : Array.isArray(v.hosts) && v.hosts.includes(host)));
+}
 function unknownKeys(obj, known, path, out) {
   for (const k of Object.keys(obj)) {
     if (!known.has(k)) {
@@ -701,12 +775,14 @@ function typeProblems(host, decl, path, named, out, claim = false) {
       out.push(err2("value-help", at("valueHelp"), "value help describes the values of an enum or flags field, or a quality's stages"));
     }
   } else if (decl.valueHelp !== void 0) {
-    const vocabulary = decl.type === "quality" ? decl.stages : decl.type === "enum" || decl.type === "flags" ? decl.values : void 0;
+    const vocabulary = decl.type === "quality" ? decl.stages : decl.type === "enum" || decl.type === "flags" ? decl.values : decl.type === "pick" ? pickWords(decl.from) : void 0;
     if (vocabulary === void 0 || !isObject(decl.valueHelp)) {
-      out.push(err2("value-help", at("valueHelp"), "value help describes the values of an enum or flags field, or a quality's stages"));
+      out.push(err2("value-help", at("valueHelp"), "value help describes the values of an enum or flags field, a quality's stages, or a pick's words"));
     } else {
       for (const k of Object.keys(decl.valueHelp)) {
-        if (!vocabulary.includes(k)) out.push(err2("value-help", atKey(at("valueHelp"), k), `"${k}" is not one of its values`));
+        if (!vocabulary.includes(k)) {
+          out.push(err2("value-help", atKey(at("valueHelp"), k), decl.type === "pick" ? `"${k}" is not one of its words: value help describes a pick's fixed words, never the project's lists or nodes` : `"${k}" is not one of its values`));
+        }
       }
     }
   }
@@ -1146,6 +1222,7 @@ exports.effectiveClaim = effectiveClaim;
 exports.entryProblems = entryProblems;
 exports.extensionDataStrategy = extensionDataStrategy;
 exports.isTextList = isTextList;
+exports.isViewEntry = isViewEntry;
 exports.keyedBy = keyedBy;
 exports.manifestProblems = manifestProblems;
 exports.mapOf = mapOf;
@@ -1169,6 +1246,7 @@ exports.targetOf = targetOf;
 exports.unresolvedOf = unresolvedOf;
 exports.unresolvedProblems = unresolvedProblems;
 exports.valueProblems = valueProblems;
+exports.viewsFor = viewsFor;
 exports.withoutMark = withoutMark;
 //# sourceMappingURL=extensions.cjs.map
 //# sourceMappingURL=extensions.cjs.map