@wildwinter/toolkit 0.2.5 → 0.2.6

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"));
@@ -480,6 +484,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)) {
@@ -1117,6 +1187,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