@wildwinter/app-shell 0.48.0 → 0.50.0

package/dist/index.cjs

@@ -3120,6 +3120,432 @@ function mountLinkStatus(host, opts) {
   };
 }
 
+// src/value-control.ts
+function fallbackText(decl) {
+  const d = decl.default;
+  if (d !== void 0 && d !== null) {
+    if (typeof d === "boolean") return d ? "True" : "False";
+    if (Array.isArray(d)) return d.length === 0 ? "none" : d.join(", ");
+    return d === "" ? "none" : String(d);
+  }
+  switch (decl.type) {
+    case "boolean":
+      return "False";
+    case "number":
+      return "0";
+    case "enum":
+      return decl.values?.[0] ?? "none";
+    case "quality":
+      return decl.stages?.[0] ?? "first stage";
+    case "flags":
+      return "none";
+    default:
+      return "empty";
+  }
+}
+var defaultLabel = (decl) => `default (${fallbackText(decl)})`;
+function stageGateNote(gates) {
+  if (gates <= 0) return "";
+  return gates === 1 ? "1 gate compares against this ladder, and it now reads the new order." : `${gates} gates compare against this ladder, and each now reads the new order.`;
+}
+function rungStrip(opts) {
+  const make = opts.doc === void 0 ? el : (tag, props) => {
+    const node2 = opts.doc.createElement(tag);
+    node2.className = props.className;
+    if (props.text !== void 0) node2.textContent = props.text;
+    if (props.tip !== void 0) {
+      node2.title = props.tip;
+      node2.setAttribute("aria-label", props.tip);
+    }
+    if (props.onClick) node2.addEventListener("click", props.onClick);
+    if (tag === "button") node2.type = "button";
+    return node2;
+  };
+  const strip = make("span", { className: "seg shell-rungs" });
+  const decl = opts.decl ?? { type: "quality", stages: opts.stages };
+  const unset = opts.value === void 0;
+  const fallback = typeof decl.default === "string" && opts.stages.includes(decl.default) ? decl.default : opts.stages[0];
+  const readOnly = opts.onPick === void 0;
+  if (opts.onClear) {
+    strip.append(make("button", {
+      className: `seg-opt shell-rung shell-rung-default${unset ? " on" : ""}`,
+      text: defaultLabel(decl),
+      tip: unset ? "Not set here: the declared default holds" : "Clear the value, back to the default",
+      onClick: () => {
+        if (!unset) opts.onClear();
+      }
+    }));
+  }
+  for (const stage of opts.stages) {
+    const current3 = opts.value === stage;
+    const falls = unset && stage === fallback;
+    const rung = make(readOnly ? "span" : "button", {
+      className: `seg-opt shell-rung${current3 ? " on" : ""}${falls ? " fallback" : ""}`,
+      text: stage,
+      tip: current3 ? "The current stage" : falls ? "The stage it falls back to" : readOnly ? stage : opts.pickTip?.(stage) ?? `Set to "${stage}"`,
+      ...readOnly ? {} : { onClick: () => {
+        if (!current3) opts.onPick(stage);
+      } }
+    });
+    strip.append(rung);
+  }
+  if (!unset && !opts.stages.includes(opts.value)) {
+    strip.append(make("span", {
+      className: "seg-opt shell-rung stray on",
+      text: opts.value,
+      tip: `"${opts.value}" is not one of the stages: pick the one it belongs at now`
+    }));
+  }
+  return strip;
+}
+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 "";
+  switch (decl.type) {
+    case "number":
+      return typeof value === "number" && Number.isFinite(value) ? "" : "Not a number.";
+    case "boolean":
+      return typeof value === "boolean" ? "" : "Not True or False.";
+    case "enum":
+      return decl.values && !decl.values.includes(String(value)) ? `"${String(value)}" is not one of the values.` : "";
+    case "quality":
+      return decl.stages && !decl.stages.includes(String(value)) ? `"${String(value)}" is not one of the stages.` : "";
+    case "flags": {
+      if (!Array.isArray(value)) return "Not a list of flags.";
+      const strays = decl.values ? value.filter((v) => !decl.values.includes(String(v))) : [];
+      if (strays.length === 0) return "";
+      return strays.length === 1 ? `"${String(strays[0])}" is not one of the values.` : `${strays.map((s) => `"${String(s)}"`).join(", ")} are not among the values.`;
+    }
+    default:
+      return "";
+  }
+}
+var isTextual = (type) => type !== "boolean" && type !== "enum" && type !== "flags" && type !== "quality";
+var controlShape = (o) => JSON.stringify([
+  o.decl.type,
+  o.decl.values ?? null,
+  o.decl.stages ?? null,
+  o.decl.default ?? null,
+  o.onCommit === void 0,
+  o.disabled === true,
+  o.controlClassName ?? "",
+  o.decl.type === "quality" && (o.decl.stages?.length ?? 0) === 0
+]);
+function fieldRow(initial) {
+  let opts = initial;
+  const row = el("div", `shell-fieldrow${opts.className ? ` ${opts.className}` : ""}`);
+  const caption = el("span", `shell-fieldrow-label${opts.labelClassName ? ` ${opts.labelClassName}` : ""}`);
+  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 problem = el("p", "shell-fieldrow-problem");
+  problem.setAttribute("role", "status");
+  row.append(caption, body);
+  let shape = "";
+  let show2 = () => {
+  };
+  let typing = "";
+  const commit = (v) => {
+    opts.onCommit?.(v);
+  };
+  const editable = () => opts.onCommit !== void 0 && opts.disabled !== true;
+  const ctl = (base) => opts.controlClassName ? `${base.replace(/^field /, "")} ${opts.controlClassName}` : base;
+  const labelledBy = (node2) => {
+    node2.setAttribute("aria-labelledby", caption.id);
+    const described = [purpose.id, problem.id].filter(Boolean).join(" ");
+    if (described) node2.setAttribute("aria-describedby", described);
+  };
+  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 !== "");
+    problem.textContent = words.join(" ");
+    problem.hidden = words.length === 0;
+    row.classList.toggle("has-problem", words.length > 0);
+    row.classList.toggle("shell-fieldrow-textual", isTextual(opts.decl.type));
+  };
+  const build = () => {
+    const decl = opts.decl;
+    typing = "";
+    if (decl.type === "quality" && (decl.stages?.length ?? 0) > 0) {
+      const holder = el("span", "shell-fieldrow-rungs");
+      show2 = (value) => {
+        holder.replaceChildren(rungStrip({
+          stages: decl.stages,
+          value: typeof value === "string" && value !== "" ? value : void 0,
+          decl,
+          ...editable() ? { onPick: (stage) => {
+            opts = { ...opts, value: stage };
+            show2(stage);
+            sayProblem();
+            commit(stage);
+          }, onClear: () => {
+            opts = { ...opts, value: void 0 };
+            show2(void 0);
+            sayProblem();
+            commit(void 0);
+          } } : {}
+        }));
+        const strip = holder.firstElementChild;
+        if (strip) {
+          strip.setAttribute("role", "group");
+          labelledBy(strip);
+        }
+      };
+      return holder;
+    }
+    if (decl.type === "boolean" || decl.type === "enum") {
+      const sel = el("select", ctl("field shell-fieldrow-select"));
+      labelledBy(sel);
+      sel.disabled = !editable();
+      const choices = decl.type === "boolean" ? [["true", "True"], ["false", "False"]] : (decl.values ?? []).map((v) => [v, v]);
+      show2 = (value) => {
+        const current3 = value === void 0 || value === null || value === "" ? "" : String(value);
+        sel.replaceChildren();
+        const add = (v, label2) => {
+          const o = el("option", void 0, label2);
+          o.value = v;
+          sel.append(o);
+        };
+        add("", defaultLabel(decl));
+        for (const [v, label2] of choices) add(v, label2);
+        if (current3 !== "" && !choices.some(([v]) => v === current3)) add(current3, current3);
+        sel.value = current3;
+      };
+      sel.addEventListener("change", () => {
+        const raw = sel.value;
+        const v = raw === "" ? void 0 : decl.type === "boolean" ? raw === "true" : raw;
+        opts = { ...opts, value: v };
+        sayProblem();
+        commit(v);
+      });
+      return sel;
+    }
+    if (decl.type === "flags" && (decl.values?.length ?? 0) > 0) {
+      const holder = el("span", "shell-flags");
+      holder.setAttribute("role", "group");
+      labelledBy(holder);
+      show2 = (value) => {
+        const unset = !Array.isArray(value);
+        const held = unset ? fallbackFlags(decl) : value.map(String);
+        holder.replaceChildren();
+        const chip2 = (text, cls, pressed, tip2, onClick) => {
+          const b = el(onClick && editable() ? "button" : "span", { className: `shell-flag${cls}`, text, tip: tip2 });
+          b.setAttribute("aria-label", `${text}: ${tip2}`);
+          if (b instanceof HTMLButtonElement) {
+            b.type = "button";
+            b.addEventListener("click", onClick);
+          }
+          if (pressed !== void 0) b.setAttribute("aria-pressed", String(pressed));
+          holder.append(b);
+        };
+        const set = (next) => {
+          opts = { ...opts, value: next };
+          show2(next);
+          sayProblem();
+          commit(next);
+        };
+        chip2(
+          defaultLabel(decl),
+          ` shell-flag-default${unset ? " on" : ""}`,
+          void 0,
+          unset ? "Not set here: the declared default holds" : "Clear the value, back to the default",
+          unset ? void 0 : () => set(void 0)
+        );
+        for (const v of decl.values) {
+          const on = held.includes(v);
+          chip2(
+            v,
+            `${on ? " on" : ""}${on && unset ? " fallback" : ""}`,
+            on,
+            on ? `Unset ${v}` : `Set ${v}`,
+            () => set(on ? held.filter((x) => x !== v) : decl.values.filter((x) => x === v || held.includes(x)).concat(held.filter((x) => !decl.values.includes(x))))
+          );
+        }
+        for (const v of held.filter((x) => !decl.values.includes(x))) {
+          chip2(v, " stray on", true, `"${v}" is not one of the values: click to drop it`, () => set(held.filter((x) => x !== v)));
+        }
+      };
+      return holder;
+    }
+    if (decl.type === "flags") {
+      const holder = el("span", "shell-fieldrow-chips");
+      show2 = (value) => {
+        const box = { values: Array.isArray(value) ? value.map(String) : [] };
+        const chips = tagChips(box, () => {
+          const next = box.values.length > 0 ? [...box.values] : void 0;
+          opts = { ...opts, value: next };
+          sayProblem();
+          commit(next);
+        });
+        const input = chips.querySelector("input");
+        if (input) {
+          labelledBy(input);
+          input.placeholder = Array.isArray(value) ? "Add value" : defaultLabel(decl);
+          input.disabled = !editable();
+        }
+        chips.querySelectorAll("button").forEach((b) => {
+          b.disabled = !editable();
+        });
+        holder.replaceChildren(chips);
+      };
+      return holder;
+    }
+    const multiline = decl.type === "multiline";
+    const field = multiline ? el("textarea", ctl("field shell-fieldrow-text")) : el("input", ctl("field shell-fieldrow-text"));
+    if (field instanceof HTMLInputElement) {
+      field.type = "text";
+      if (decl.type === "number") field.inputMode = "decimal";
+    } else field.rows = 3;
+    labelledBy(field);
+    field.placeholder = defaultLabel(decl);
+    field.disabled = !editable();
+    const asText = (value) => value === void 0 || value === null ? "" : Array.isArray(value) ? value.join(", ") : String(value);
+    const read = (raw) => {
+      if (raw.trim() === "") return {};
+      if (decl.type !== "number") return { value: raw };
+      const n = Number(raw.trim());
+      return Number.isFinite(n) ? { value: n } : { bad: "Not a number." };
+    };
+    let atFocus = "";
+    show2 = (value) => {
+      if (field.ownerDocument.activeElement === field || keeper.restoring(field) || keeper.holds(row)) return;
+      field.value = asText(value);
+    };
+    const take = () => {
+      const r = read(field.value);
+      typing = r.bad ?? "";
+      if (r.bad === void 0) opts = { ...opts, value: r.value };
+      sayProblem();
+      if (r.bad === void 0) commit(r.value);
+    };
+    field.addEventListener("focus", () => {
+      if (!keeper.restoring(field)) atFocus = field.value;
+    });
+    field.addEventListener("input", take);
+    field.addEventListener("keydown", (e) => {
+      if (e.key !== "Escape" || field.value === atFocus) return;
+      field.value = atFocus;
+      take();
+    });
+    return field;
+  };
+  const draw = (next) => {
+    const decl = next.decl;
+    const label2 = next.label ?? decl.name;
+    if (typeof label2 === "string") caption.textContent = label2;
+    else caption.replaceChildren(label2);
+    caption.className = `shell-fieldrow-label${next.labelClassName ? ` ${next.labelClassName}` : ""}`;
+    row.className = `shell-fieldrow${next.className ? ` ${next.className}` : ""}`;
+    const nextShape = controlShape(next);
+    opts = next;
+    if (nextShape !== shape) {
+      shape = nextShape;
+      body.replaceChildren(build());
+    }
+    show2(next.value);
+    purpose.textContent = decl.purpose ?? "";
+    if (decl.purpose) body.append(purpose);
+    else purpose.remove();
+    body.append(problem);
+    sayProblem();
+  };
+  draw(initial);
+  keeper.watch(row);
+  return { el: row, update: draw };
+}
+var keeper = /* @__PURE__ */ (() => {
+  const memos = /* @__PURE__ */ new WeakMap();
+  const restoringNow = /* @__PURE__ */ new WeakSet();
+  const redrawn = /* @__PURE__ */ new WeakMap();
+  const put = (row) => {
+    const memo = memos.get(row);
+    if (!memo) return;
+    const doc = row.ownerDocument;
+    const active2 = doc.activeElement;
+    if (!row.isConnected || !memo.field.isConnected || !row.contains(memo.field)) return;
+    if (active2 && active2 !== doc.body && !row.contains(active2)) {
+      memos.delete(row);
+      return;
+    }
+    if (active2 === memo.field && memo.field.matches(":focus")) return;
+    restoringNow.add(memo.field);
+    try {
+      memo.field.focus({ preventScroll: true });
+      if (!(memo.field instanceof HTMLSelectElement) && memo.start !== null) memo.field.setSelectionRange(memo.start, memo.end ?? memo.start);
+    } finally {
+      restoringNow.delete(memo.field);
+    }
+  };
+  return {
+    watch(row) {
+      const note = (e) => {
+        const t = e.target;
+        if (!(t instanceof HTMLInputElement || t instanceof HTMLTextAreaElement || t instanceof HTMLSelectElement)) return;
+        const text = !(t instanceof HTMLSelectElement);
+        memos.set(row, { field: t, start: text ? t.selectionStart : null, end: text ? t.selectionEnd : null });
+      };
+      row.addEventListener("focusin", note);
+      row.addEventListener("input", note);
+      row.addEventListener("keyup", note);
+      row.addEventListener("mouseup", note);
+      row.addEventListener("focusout", (e) => {
+        const at = performance.now();
+        const late = e.relatedTarget === null && at - (redrawn.get(row) ?? -Infinity) < 250;
+        if (late && memos.has(row)) {
+          queueMicrotask(() => put(row));
+          return;
+        }
+        queueMicrotask(() => {
+          if ((redrawn.get(row) ?? -Infinity) >= at) {
+            put(row);
+            return;
+          }
+          if (row.isConnected && !row.contains(row.ownerDocument.activeElement)) memos.delete(row);
+        });
+      });
+    },
+    /** Give the focus back to the row, if the author was in it and has not gone anywhere else since. */
+    restore(row) {
+      if (!memos.has(row)) return;
+      redrawn.set(row, performance.now());
+      queueMicrotask(() => put(row));
+    },
+    restoring: (field) => restoringNow.has(field),
+    /** Forget the row's focus if the author has since gone somewhere else (before the row is redrawn). */
+    settle(row) {
+      const active2 = row.ownerDocument.activeElement;
+      if (active2 && active2 !== row.ownerDocument.body && !row.contains(active2)) memos.delete(row);
+    },
+    /** The row the author is in (before a redraw takes it out). */
+    holds: (row) => memos.has(row)
+  };
+})();
+function fieldRows() {
+  const rows = /* @__PURE__ */ new Map();
+  return {
+    row(key, opts) {
+      const had = rows.get(key);
+      if (had) {
+        had.used = true;
+        keeper.settle(had.handle.el);
+        had.handle.update(opts);
+        keeper.restore(had.handle.el);
+        return had.handle.el;
+      }
+      const handle = fieldRow(opts);
+      rows.set(key, { handle, used: true });
+      return handle.el;
+    },
+    sweep() {
+      for (const [key, entry] of rows) {
+        if (!entry.used) rows.delete(key);
+        else entry.used = false;
+      }
+    }
+  };
+}
+
 // src/property-list.ts
 var PROPERTY_TYPES = [
   ["number", "Number"],
@@ -3135,35 +3561,37 @@ var option = (value, label2, selected) => {
   o.selected = selected;
   return o;
 };
-var NONE = "(none)";
+var NONE_CHOSEN = "\0none";
 function defaultControl(p, onChange, opts = {}) {
   const typed = opts.typed === true;
   const write = (raw) => {
-    if (raw === "") {
-      if (typed) delete p.default;
-      else p.default = "";
-    } else if (typed && p.type === "boolean") p.default = raw === "true";
+    if (raw === "") delete p.default;
+    else if (raw === NONE_CHOSEN) p.default = "";
+    else if (typed && p.type === "boolean") p.default = raw === "true";
     else if (typed && p.type === "number") p.default = Number(raw);
     else p.default = raw;
     onChange?.();
   };
   const current3 = p.default === void 0 || p.default === null ? "" : String(p.default);
+  const unsetLabel = opts.unsetLabel ?? defaultLabel({ ...p, default: void 0 });
   if (p.type === "boolean") {
     const sel = el("select", "field set-default");
-    sel.append(option("", NONE, current3 === ""), option("true", "True", current3 === "true"), option("false", "False", current3 === "false"));
+    sel.append(option("", unsetLabel, current3 === ""), option("true", "True", current3 === "true"), option("false", "False", current3 === "false"));
     sel.addEventListener("change", () => write(sel.value));
     return sel;
   }
   if (p.type === "enum") {
     const sel = el("select", "field set-default");
-    sel.append(option("", NONE, current3 === ""));
+    const none = opts.noneChosen === true && p.default === "";
+    sel.append(option("", unsetLabel, current3 === "" && !none));
+    if (opts.noneChosen) sel.append(option(NONE_CHOSEN, "(none)", none));
     for (const v of p.values ?? []) sel.append(option(v, v, current3 === v));
     sel.addEventListener("change", () => write(sel.value));
     return sel;
   }
   if (p.type === "quality") {
     const sel = el("select", "field set-default");
-    sel.append(option("", "(first stage)", current3 === ""));
+    sel.append(option("", unsetLabel, current3 === ""));
     for (const v of p.stages ?? []) sel.append(option(v, v, current3 === v));
     sel.addEventListener("change", () => write(sel.value));
     return sel;
@@ -3175,7 +3603,7 @@ function defaultControl(p, onChange, opts = {}) {
   }
   const input = el("input", "field set-default");
   input.type = p.type === "number" ? "number" : "text";
-  input.placeholder = "Default";
+  input.placeholder = p.type === "number" ? `Default (${fallbackText({ type: "number" })})` : "Default";
   input.value = current3;
   input.addEventListener("input", () => write(input.value));
   return input;
@@ -3186,24 +3614,32 @@ function mountPropertyList(host, decls, opts = {}) {
   const types = opts.types ?? PROPERTY_TYPES;
   const list = el("div", "set-list");
   const keep = (parts) => (parts ?? []).filter((p) => p !== null);
+  const noun = opts.noun ?? "property";
+  const Noun = noun.charAt(0).toUpperCase() + noun.slice(1);
+  const freeNames = opts.names === "free";
   const row = (p, i) => {
     const name = el("input", "field set-name");
     name.type = "text";
-    name.placeholder = "Property name";
+    name.placeholder = `${Noun} name`;
     name.value = p.name;
     name.spellcheck = false;
-    name.dataset["tip"] = PROPERTY_NAME_HINT;
-    bindPropertyName(name, (v) => {
-      p.name = v;
+    if (freeNames) name.addEventListener("input", () => {
+      p.name = name.value;
       changed();
-    }, { hint: PROPERTY_NAME_HINT });
+    });
+    else {
+      name.dataset["tip"] = PROPERTY_NAME_HINT;
+      bindPropertyName(name, (v) => {
+        p.name = v;
+        changed();
+      }, { hint: PROPERTY_NAME_HINT });
+    }
     guard.track(name);
     const type = el("select", "field set-type");
     for (const [v, label2] of types) type.append(option(v, label2, v === p.type));
     type.addEventListener("change", () => {
       p.type = type.value;
-      if (opts.typed) delete p.default;
-      else p.default = "";
+      delete p.default;
       if (p.type === "enum" || p.type === "flags") p.values ??= [];
       else delete p.values;
       if (p.type === "quality") p.stages ??= [];
@@ -3230,7 +3666,7 @@ function mountPropertyList(host, decls, opts = {}) {
         changed();
       }
     }, i === decls.length - 1);
-    const del = iconBtn("close", "Delete property", () => {
+    const del = iconBtn("close", `Delete ${noun}`, () => {
       decls.splice(i, 1);
       render();
       changed();
@@ -3255,7 +3691,7 @@ function mountPropertyList(host, decls, opts = {}) {
     if (opts.purpose !== false) {
       const purpose = el("input", "field set-purpose");
       purpose.type = "text";
-      purpose.placeholder = "What this property is for";
+      purpose.placeholder = `What this ${noun} is for`;
       purpose.value = p.purpose ?? "";
       purpose.addEventListener("input", () => {
         if (purpose.value.trim()) p.purpose = purpose.value;
@@ -3285,9 +3721,9 @@ function mountPropertyList(host, decls, opts = {}) {
   host.append(list, add);
   return {
     firstDuplicate: () => guard.firstDuplicate(),
-    firstIllegalName: () => firstIllegalPropertyName(host),
+    firstIllegalName: () => freeNames ? null : firstIllegalPropertyName(host),
     // The Save gate takes both faults; the field's own rollover says which.
-    firstInvalid: () => guard.firstDuplicate() ?? firstIllegalPropertyName(host),
+    firstInvalid: () => guard.firstDuplicate() ?? (freeNames ? null : firstIllegalPropertyName(host)),
     render
   };
 }
@@ -3390,6 +3826,7 @@ exports.createNavHistory = createNavHistory;
 exports.createSaveController = createSaveController;
 exports.debounce = debounce;
 exports.defaultControl = defaultControl;
+exports.defaultLabel = defaultLabel;
 exports.defaultProblemCopy = defaultProblemCopy;
 exports.describeProblem = describeProblem;
 exports.dialogFrame = dialogFrame;
@@ -3397,7 +3834,11 @@ exports.dismissToast = dismissToast;
 exports.dupGuard = dupGuard;
 exports.el = el;
 exports.expandableRow = expandableRow;
+exports.fallbackText = fallbackText;
 exports.feedUpdaterDownloadProgress = feedUpdaterDownloadProgress;
+exports.fieldRow = fieldRow;
+exports.fieldRows = fieldRows;
+exports.fieldValueProblem = fieldValueProblem;
 exports.firstIllegalPropertyName = firstIllegalPropertyName;
 exports.focusNewRow = focusNewRow;
 exports.foldVc = foldVc;
@@ -3462,11 +3903,13 @@ exports.renderStepperBar = renderStepperBar;
 exports.revalidatePropertyRefs = revalidatePropertyRefs;
 exports.revealRow = revealRow;
 exports.revealRowWhenReady = revealRowWhenReady;
+exports.rungStrip = rungStrip;
 exports.saveIndicator = saveIndicator;
 exports.setKeyPlatform = setKeyPlatform;
 exports.showAbout = showAbout;
 exports.showUpdaterDialog = showUpdaterDialog;
 exports.stageChips = stageChips;
+exports.stageGateNote = stageGateNote;
 exports.staleBar = staleBar;
 exports.tagChips = tagChips;
 exports.tipAt = tipAt;