@wildwinter/app-shell 0.51.0 → 0.53.0

package/dist/value-control.d.cts

@@ -55,7 +55,15 @@ interface FieldDeclLike extends ValueDeclLike {
     name: string;
     /** What the field is for, shown under the control. */
     purpose?: string;
+    /** A sentence about each value (an enum's values, the flags, a quality's stages), as an extension's manifest
+     *  gives them: the chosen value's is shown under the control, and each chosen flag's. */
+    valueHelp?: Readonly<Record<string, string>>;
 }
+/**
+ * The help for what `decl` holds: the chosen enum value's or stage's (the one it falls back to, when unset), or
+ * each chosen flag's, "name: sentence" a line each. Empty when the declaration describes none of them.
+ */
+declare function valueHelpText(decl: FieldDeclLike, value: unknown): string;
 interface FieldRowOptions {
     decl: FieldDeclLike;
     /** The node's own value, typed (a flags value is a string list), or undefined where the node sets none. */
@@ -66,6 +74,9 @@ interface FieldRowOptions {
     disabled?: boolean;
     /** A message of the app's own about this value (a check the row cannot make), shown under the control. */
     problem?: string;
+    /** The app's own sentence INSTEAD of the row's (a renamed stage said better than "not one of the stages").
+     *  Given, it is the whole message; `problem` is ignored. */
+    replaceProblem?: string;
     /** The caption; default the field's name. */
     label?: string | Node;
     /** Added to the row and its caption, so a row sits in its app's layout. */
@@ -109,4 +120,4 @@ interface FieldRows {
 /** A cache of field rows for a host that redraws its whole view on every change. */
 declare function fieldRows(): FieldRows;
 
-export { type FieldDeclLike, type FieldRowHandle, type FieldRowOptions, type FieldRows, type FieldValue, type RungStripOptions, type ValueDeclLike, defaultLabel, fallbackText, fieldRow, fieldRowFocus, fieldRows, fieldValueProblem, rungStrip, stageGateNote };
+export { type FieldDeclLike, type FieldRowHandle, type FieldRowOptions, type FieldRows, type FieldValue, type RungStripOptions, type ValueDeclLike, defaultLabel, fallbackText, fieldRow, fieldRowFocus, fieldRows, fieldValueProblem, rungStrip, stageGateNote, valueHelpText };

package/dist/value-control.d.ts

@@ -55,7 +55,15 @@ interface FieldDeclLike extends ValueDeclLike {
     name: string;
     /** What the field is for, shown under the control. */
     purpose?: string;
+    /** A sentence about each value (an enum's values, the flags, a quality's stages), as an extension's manifest
+     *  gives them: the chosen value's is shown under the control, and each chosen flag's. */
+    valueHelp?: Readonly<Record<string, string>>;
 }
+/**
+ * The help for what `decl` holds: the chosen enum value's or stage's (the one it falls back to, when unset), or
+ * each chosen flag's, "name: sentence" a line each. Empty when the declaration describes none of them.
+ */
+declare function valueHelpText(decl: FieldDeclLike, value: unknown): string;
 interface FieldRowOptions {
     decl: FieldDeclLike;
     /** The node's own value, typed (a flags value is a string list), or undefined where the node sets none. */
@@ -66,6 +74,9 @@ interface FieldRowOptions {
     disabled?: boolean;
     /** A message of the app's own about this value (a check the row cannot make), shown under the control. */
     problem?: string;
+    /** The app's own sentence INSTEAD of the row's (a renamed stage said better than "not one of the stages").
+     *  Given, it is the whole message; `problem` is ignored. */
+    replaceProblem?: string;
     /** The caption; default the field's name. */
     label?: string | Node;
     /** Added to the row and its caption, so a row sits in its app's layout. */
@@ -109,4 +120,4 @@ interface FieldRows {
 /** A cache of field rows for a host that redraws its whole view on every change. */
 declare function fieldRows(): FieldRows;
 
-export { type FieldDeclLike, type FieldRowHandle, type FieldRowOptions, type FieldRows, type FieldValue, type RungStripOptions, type ValueDeclLike, defaultLabel, fallbackText, fieldRow, fieldRowFocus, fieldRows, fieldValueProblem, rungStrip, stageGateNote };
+export { type FieldDeclLike, type FieldRowHandle, type FieldRowOptions, type FieldRows, type FieldValue, type RungStripOptions, type ValueDeclLike, defaultLabel, fallbackText, fieldRow, fieldRowFocus, fieldRows, fieldValueProblem, rungStrip, stageGateNote, valueHelpText };

package/dist/value-control.js

@@ -1,4 +1,4 @@
-export { defaultLabel, fallbackText, fieldRow, fieldRowFocus, fieldRows, fieldValueProblem, rungStrip, stageGateNote } from './chunk-ELEDQRZ7.js';
+export { defaultLabel, fallbackText, fieldRow, fieldRowFocus, fieldRows, fieldValueProblem, rungStrip, stageGateNote, valueHelpText } from './chunk-XJM733E6.js';
 import './chunk-W4WC4FO5.js';
 //# sourceMappingURL=value-control.js.map
 //# sourceMappingURL=value-control.js.map

package/dist/value-rows.cjs

@@ -478,6 +478,23 @@ function rungStrip(opts) {
   }
   return strip;
 }
+function valueHelpText(decl, value) {
+  const help = decl.valueHelp;
+  if (help === void 0) return "";
+  const said = (v) => Object.prototype.hasOwnProperty.call(help, v) ? help[v] : void 0;
+  if (decl.type === "enum" || decl.type === "quality") {
+    const held = typeof value === "string" && value !== "" ? value : typeof decl.default === "string" && decl.default !== "" ? decl.default : decl.type === "enum" ? decl.values?.[0] : decl.stages?.[0];
+    return held === void 0 ? "" : said(held) ?? "";
+  }
+  if (decl.type === "flags") {
+    const held = Array.isArray(value) ? value.map(String) : Array.isArray(decl.default) ? decl.default.map(String) : [];
+    return held.flatMap((v) => {
+      const h = said(v);
+      return h === void 0 ? [] : [`${v}: ${h}`];
+    }).join("\n");
+  }
+  return "";
+}
 var fallbackFlags = (decl) => Array.isArray(decl.default) ? decl.default.filter((v) => typeof v === "string") : [];
 function fieldValueProblem(decl, value) {
   if (value === void 0 || value === null || value === "") return "";
@@ -518,6 +535,7 @@ function fieldRow(initial) {
   caption.id = `shell-fr-${Math.random().toString(36).slice(2, 9)}`;
   const body = el("div", "shell-fieldrow-body");
   const purpose = el("p", "shell-fieldrow-purpose");
+  const valueHelp = el("p", "shell-fieldrow-purpose shell-fieldrow-valuehelp");
   const problem = el("p", "shell-fieldrow-problem");
   problem.setAttribute("role", "status");
   row.append(caption, body);
@@ -538,7 +556,10 @@ function fieldRow(initial) {
   purpose.id = `${caption.id}-p`;
   problem.id = `${caption.id}-m`;
   const sayProblem = () => {
-    const words = [typing || fieldValueProblem(opts.decl, opts.value), opts.problem ?? ""].filter((w) => w !== "");
+    const help = valueHelpText(opts.decl, opts.value);
+    valueHelp.textContent = help;
+    valueHelp.hidden = help === "";
+    const words = opts.replaceProblem !== void 0 ? [opts.replaceProblem].filter((w) => w !== "") : [typing || fieldValueProblem(opts.decl, opts.value), opts.problem ?? ""].filter((w) => w !== "");
     problem.textContent = words.join(" ");
     problem.hidden = words.length === 0;
     row.classList.toggle("has-problem", words.length > 0);
@@ -727,7 +748,7 @@ function fieldRow(initial) {
     purpose.textContent = decl.purpose ?? "";
     if (decl.purpose) body.append(purpose);
     else purpose.remove();
-    body.append(problem);
+    body.append(valueHelp, problem);
     sayProblem();
   };
   draw(initial);
@@ -807,13 +828,16 @@ var fieldRowFocus = {
 };
 
 // src/value-rows.ts
+function nodeLabel(adapter, kind, id) {
+  return adapter.nodes(kind).find((n) => n.id === id)?.label ?? adapter.label?.(kind, id);
+}
 var SCALARS = /* @__PURE__ */ new Set(["text", "multiline", "number", "boolean", "enum", "flags", "quality", "string"]);
 var isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 var nameOf = (decl) => decl.label ?? decl.name;
 var asDecl = (d, name) => ({ ...d, name: d.name ?? name });
 function ownProblems(decl, value, adapter) {
   if (value === void 0) return "";
-  const exists = adapter ? (kind, id) => adapter.nodes(kind).some((n) => n.id === id) : void 0;
+  const exists = adapter ? (kind, id) => nodeLabel(adapter, kind, id) !== void 0 : void 0;
   return extensions.valueProblems(decl, value, exists ? { exists } : {}).filter((p) => p.path === "" && p.severity === "error" && p.code !== "not-a-value" && p.code !== "not-a-stage").map((p) => `${p.message.replace(/^the value/, "The value")}.`).join(" ");
 }
 function valueRow(initial) {
@@ -832,6 +856,7 @@ function scalarRow(initial) {
       ...o.onCommit ? { onCommit: (v) => o.onCommit(v) } : {},
       ...o.disabled !== void 0 ? { disabled: o.disabled } : {},
       ...problem !== "" ? { problem } : {},
+      ...o.replaceProblem !== void 0 ? { replaceProblem: o.replaceProblem } : {},
       label: o.label ?? nameOf(o.decl),
       ...o.className !== void 0 ? { className: o.className } : {},
       ...o.labelClassName !== void 0 ? { labelClassName: o.labelClassName } : {},
@@ -882,12 +907,15 @@ function referenceRow(initial) {
     };
     add("", "default (none)");
     for (const n of nodes) add(n.id, n.label);
-    if (held !== "" && !nodes.some((n) => n.id === held)) add(held, `${held} (gone)`);
+    if (held !== "" && !nodes.some((n) => n.id === held)) {
+      const name = o.adapter.label?.(o.decl.to ?? "", held);
+      add(held, name ?? `${held} (gone)`);
+    }
     sel.value = held;
     sel.disabled = o.onCommit === void 0 || o.disabled === true;
     help.textContent = o.decl.help ?? o.decl.purpose ?? "";
     help.hidden = help.textContent === "";
-    const words = [ownProblems(o.decl, o.value, o.adapter), o.problem ?? ""].filter((w) => w !== "").join(" ");
+    const words = o.replaceProblem ?? [ownProblems(o.decl, o.value, o.adapter), o.problem ?? ""].filter((w) => w !== "").join(" ");
     problem.textContent = words;
     problem.hidden = words === "";
     row.classList.toggle("has-problem", words !== "");
@@ -970,14 +998,15 @@ function structuredRow(initial) {
     } else if (decl.type === "map" && decl.of) {
       const value = isObject(o.value) ? o.value : {};
       const keyNodes = decl.key?.type === "reference" && o.adapter ? o.adapter.nodes(decl.key.to ?? "") : void 0;
-      const keyLabel = (k) => keyNodes?.find((n) => n.id === k)?.label ?? k;
+      const keyKind = decl.key?.to ?? "";
+      const keyLabel = (k) => (o.adapter && keyNodes !== void 0 ? nodeLabel(o.adapter, keyKind, k) : void 0) ?? k;
       for (const k of Object.keys(value)) {
         const remove = editable() ? [iconBtn("close", `Remove ${keyLabel(k)}`, () => {
           const next = { ...isObject(opts.value) ? opts.value : {} };
           delete next[k];
           commit(Object.keys(next).length > 0 ? next : void 0);
         })] : [];
-        const gone = keyNodes !== void 0 && !keyNodes.some((n) => n.id === k) ? `${keyLabel(k)} is not here any more.` : void 0;
+        const gone = keyNodes !== void 0 && o.adapter && nodeLabel(o.adapter, keyKind, k) === void 0 ? `${k} is not here any more.` : void 0;
         child(`k:${k}`, asDecl(decl.of, k), value[k], (v) => {
           const next = { ...isObject(opts.value) ? opts.value : {} };
           next[k] = v === void 0 ? extensions.defaultOf(decl.of) : v;
@@ -1063,7 +1092,7 @@ function structuredRow(initial) {
     if (decl.type !== "record" && editable()) body.append(adder);
     help.textContent = decl.help ?? decl.purpose ?? "";
     if (help.textContent !== "") body.append(help);
-    const words = [ownProblems(decl, o.value, o.adapter), o.problem ?? ""].filter((w) => w !== "").join(" ");
+    const words = o.replaceProblem ?? [ownProblems(decl, o.value, o.adapter), o.problem ?? ""].filter((w) => w !== "").join(" ");
     problem.textContent = words;
     problem.hidden = words === "";
     body.append(problem);