@wildwinter/toolkit 0.2.5 → 0.2.7

package/dist/extensions.d.cts

@@ -111,6 +111,23 @@ interface Manifest {
     readonly docs?: string;
     readonly settings?: readonly SettingDecl[];
     readonly targets: Readonly<Partial<Record<HostName, Readonly<Record<string, TargetDecl>>>>>;
+    /** Views the extension's installed package supplies (tier 2), each a web component a host opens in a window. */
+    readonly views?: readonly ViewDecl[];
+    /** Other extensions whose data this one's views read, by id. */
+    readonly reads?: readonly string[];
+}
+/** A view: a web component in the extension's installed package, opened by a host in a floating window. */
+interface ViewDecl {
+    /** Lower case, digits and hyphens, unique within the manifest. */
+    readonly id: string;
+    /** The window's title and the menu item. */
+    readonly name: string;
+    /** The component's script, a relative path within the package, such as `view/sheet.js`. */
+    readonly entry: string;
+    /** The custom element the script defines, such as `pattershot-sheet`. */
+    readonly element: string;
+    /** The hosts that offer it; every host the manifest targets when absent. */
+    readonly hosts?: readonly HostName[];
 }
 /** One thing wrong, with where it is. A host words it in its own report shape. */
 interface Problem {
@@ -145,6 +162,11 @@ interface UnresolvedEntry {
 declare function parseManifest(text: string): Manifest;
 /** Every problem with a manifest, by path. An empty list means it is sound. */
 declare function manifestProblems(manifest: unknown): Problem[];
+/** A package path a view's entry may name: relative, forward slashes, no `.` or `..` segment, a `.js` file. */
+declare function isViewEntry(entry: unknown): entry is string;
+/** The views a host offers from a manifest: those naming the host, or every view when it names none and the
+ *  manifest targets the host. A view that fails its checks is left out. */
+declare function viewsFor(manifest: Manifest, host: HostName): ViewDecl[];
 /** The host field each of a manifest's settings names, the project's choice
  *  first, else the setting's default. */
 declare function settingValues(manifest: Manifest, chosen?: Readonly<Record<string, unknown>>): Record<string, string>;
@@ -396,4 +418,4 @@ declare const atKey: (base: string, key: string) => string;
 /** `base` and then list position `i`. */
 declare const atIndex: (base: string, i: number) => string;
 
-export { ATOMIC, COMMENTS, type ClaimDecl, type Conflict, type ConflictKind, type DataMergeResult, type ExtensionData, type FieldDecl, HOSTS, type HostName, type HostSpec, type JsonValue, MANIFEST_FILE_SUFFIX, MANIFEST_SCHEMA, type Manifest, type MergeWarning, type PickChoice, type PickSource, type PickSources, type Problem, type ResolvedClaim, SCALAR_TYPES, SET, type ScalarType, type SettingDecl, type StageRename, type Strategy, type TargetDecl, type TreeMergeOptions, type TreeMergeResult, type TypeDecl, UNRESOLVED_KEY, type UnresolvedEntry, VALUE_TYPES, type ValueContext, type ValueType, atIndex, atKey, claimClashes, compileEntry, compiledTarget, defaultOf, effectiveClaim, entryProblems, extensionDataStrategy, isTextList, keyedBy, manifestProblems, mapOf, markUnresolved, mergeComments, mergeExtensionData, mergeTree, objectOf, orphanedEntries, parseManifest, pickChoices, pickClashes, pickLists, renameStages, resolvedClaims, settingValues, stableStringify, strategyForTarget, strategyForType, targetOf, unresolvedOf, unresolvedProblems, valueProblems, withoutMark };
+export { ATOMIC, COMMENTS, type ClaimDecl, type Conflict, type ConflictKind, type DataMergeResult, type ExtensionData, type FieldDecl, HOSTS, type HostName, type HostSpec, type JsonValue, MANIFEST_FILE_SUFFIX, MANIFEST_SCHEMA, type Manifest, type MergeWarning, type PickChoice, type PickSource, type PickSources, type Problem, type ResolvedClaim, SCALAR_TYPES, SET, type ScalarType, type SettingDecl, type StageRename, type Strategy, type TargetDecl, type TreeMergeOptions, type TreeMergeResult, type TypeDecl, UNRESOLVED_KEY, type UnresolvedEntry, VALUE_TYPES, type ValueContext, type ValueType, type ViewDecl, atIndex, atKey, claimClashes, compileEntry, compiledTarget, defaultOf, effectiveClaim, entryProblems, extensionDataStrategy, isTextList, isViewEntry, keyedBy, manifestProblems, mapOf, markUnresolved, mergeComments, mergeExtensionData, mergeTree, objectOf, orphanedEntries, parseManifest, pickChoices, pickClashes, pickLists, renameStages, resolvedClaims, settingValues, stableStringify, strategyForTarget, strategyForType, targetOf, unresolvedOf, unresolvedProblems, valueProblems, viewsFor, withoutMark };

package/dist/extensions.d.ts

@@ -111,6 +111,23 @@ interface Manifest {
     readonly docs?: string;
     readonly settings?: readonly SettingDecl[];
     readonly targets: Readonly<Partial<Record<HostName, Readonly<Record<string, TargetDecl>>>>>;
+    /** Views the extension's installed package supplies (tier 2), each a web component a host opens in a window. */
+    readonly views?: readonly ViewDecl[];
+    /** Other extensions whose data this one's views read, by id. */
+    readonly reads?: readonly string[];
+}
+/** A view: a web component in the extension's installed package, opened by a host in a floating window. */
+interface ViewDecl {
+    /** Lower case, digits and hyphens, unique within the manifest. */
+    readonly id: string;
+    /** The window's title and the menu item. */
+    readonly name: string;
+    /** The component's script, a relative path within the package, such as `view/sheet.js`. */
+    readonly entry: string;
+    /** The custom element the script defines, such as `pattershot-sheet`. */
+    readonly element: string;
+    /** The hosts that offer it; every host the manifest targets when absent. */
+    readonly hosts?: readonly HostName[];
 }
 /** One thing wrong, with where it is. A host words it in its own report shape. */
 interface Problem {
@@ -145,6 +162,11 @@ interface UnresolvedEntry {
 declare function parseManifest(text: string): Manifest;
 /** Every problem with a manifest, by path. An empty list means it is sound. */
 declare function manifestProblems(manifest: unknown): Problem[];
+/** A package path a view's entry may name: relative, forward slashes, no `.` or `..` segment, a `.js` file. */
+declare function isViewEntry(entry: unknown): entry is string;
+/** The views a host offers from a manifest: those naming the host, or every view when it names none and the
+ *  manifest targets the host. A view that fails its checks is left out. */
+declare function viewsFor(manifest: Manifest, host: HostName): ViewDecl[];
 /** The host field each of a manifest's settings names, the project's choice
  *  first, else the setting's default. */
 declare function settingValues(manifest: Manifest, chosen?: Readonly<Record<string, unknown>>): Record<string, string>;
@@ -396,4 +418,4 @@ declare const atKey: (base: string, key: string) => string;
 /** `base` and then list position `i`. */
 declare const atIndex: (base: string, i: number) => string;
 
-export { ATOMIC, COMMENTS, type ClaimDecl, type Conflict, type ConflictKind, type DataMergeResult, type ExtensionData, type FieldDecl, HOSTS, type HostName, type HostSpec, type JsonValue, MANIFEST_FILE_SUFFIX, MANIFEST_SCHEMA, type Manifest, type MergeWarning, type PickChoice, type PickSource, type PickSources, type Problem, type ResolvedClaim, SCALAR_TYPES, SET, type ScalarType, type SettingDecl, type StageRename, type Strategy, type TargetDecl, type TreeMergeOptions, type TreeMergeResult, type TypeDecl, UNRESOLVED_KEY, type UnresolvedEntry, VALUE_TYPES, type ValueContext, type ValueType, atIndex, atKey, claimClashes, compileEntry, compiledTarget, defaultOf, effectiveClaim, entryProblems, extensionDataStrategy, isTextList, keyedBy, manifestProblems, mapOf, markUnresolved, mergeComments, mergeExtensionData, mergeTree, objectOf, orphanedEntries, parseManifest, pickChoices, pickClashes, pickLists, renameStages, resolvedClaims, settingValues, stableStringify, strategyForTarget, strategyForType, targetOf, unresolvedOf, unresolvedProblems, valueProblems, withoutMark };
+export { ATOMIC, COMMENTS, type ClaimDecl, type Conflict, type ConflictKind, type DataMergeResult, type ExtensionData, type FieldDecl, HOSTS, type HostName, type HostSpec, type JsonValue, MANIFEST_FILE_SUFFIX, MANIFEST_SCHEMA, type Manifest, type MergeWarning, type PickChoice, type PickSource, type PickSources, type Problem, type ResolvedClaim, SCALAR_TYPES, SET, type ScalarType, type SettingDecl, type StageRename, type Strategy, type TargetDecl, type TreeMergeOptions, type TreeMergeResult, type TypeDecl, UNRESOLVED_KEY, type UnresolvedEntry, VALUE_TYPES, type ValueContext, type ValueType, type ViewDecl, atIndex, atKey, claimClashes, compileEntry, compiledTarget, defaultOf, effectiveClaim, entryProblems, extensionDataStrategy, isTextList, isViewEntry, keyedBy, manifestProblems, mapOf, markUnresolved, mergeComments, mergeExtensionData, mergeTree, objectOf, orphanedEntries, parseManifest, pickChoices, pickClashes, pickLists, renameStages, resolvedClaims, settingValues, stableStringify, strategyForTarget, strategyForType, targetOf, unresolvedOf, unresolvedProblems, valueProblems, viewsFor, withoutMark };

package/dist/extensions.js

@@ -360,7 +360,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);
@@ -382,6 +384,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"));
@@ -410,6 +414,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 }'));
@@ -480,6 +488,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)) {
@@ -691,12 +765,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`));
+        }
       }
     }
   }
@@ -1117,6 +1193,6 @@ function orphanedEntries(data, exists) {
   return out;
 }
 
-export { ATOMIC, COMMENTS, HOSTS, MANIFEST_FILE_SUFFIX, MANIFEST_SCHEMA, SCALAR_TYPES, SET, UNRESOLVED_KEY, VALUE_TYPES, atIndex, atKey, claimClashes, compileEntry, compiledTarget, defaultOf, effectiveClaim, entryProblems, extensionDataStrategy, isTextList, keyedBy, manifestProblems, mapOf, markUnresolved, mergeComments, mergeExtensionData, mergeTree, objectOf, orphanedEntries, parseManifest, pickChoices, pickClashes, pickLists, renameStages, resolvedClaims, settingValues, stableStringify, strategyForTarget, strategyForType, targetOf, unresolvedOf, unresolvedProblems, valueProblems, withoutMark };
+export { ATOMIC, COMMENTS, HOSTS, MANIFEST_FILE_SUFFIX, MANIFEST_SCHEMA, SCALAR_TYPES, SET, UNRESOLVED_KEY, VALUE_TYPES, atIndex, atKey, claimClashes, compileEntry, compiledTarget, defaultOf, effectiveClaim, entryProblems, extensionDataStrategy, isTextList, isViewEntry, keyedBy, manifestProblems, mapOf, markUnresolved, mergeComments, mergeExtensionData, mergeTree, objectOf, orphanedEntries, parseManifest, pickChoices, pickClashes, pickLists, renameStages, resolvedClaims, settingValues, stableStringify, strategyForTarget, strategyForType, targetOf, unresolvedOf, unresolvedProblems, valueProblems, viewsFor, withoutMark };
 //# sourceMappingURL=extensions.js.map
 //# sourceMappingURL=extensions.js.map