@appinternalleads/ui 0.2.0

package/tools/ask/dist/elicit.mjs

@@ -0,0 +1,138 @@
+// src/fields/types.ts
+var ESCAPE_WORDING = /^(i don't know|i can't tell|not sure|none of these|unsure|no preference)/i;
+var isEscapeWording = (label) => ESCAPE_WORDING.test(label);
+function toOption(o) {
+  return typeof o === "string" ? { value: o, label: o, escape: isEscapeWording(o) } : { ...o, escape: o.escape ?? isEscapeWording(o.label) };
+}
+
+// src/fields/control.ts
+function defaultOf(field) {
+  return "default" in field ? field.default : void 0;
+}
+function resolveHint(field) {
+  if (!field.hint) return void 0;
+  return field.hint.replace(/\{([a-z]+(?:\.[a-zA-Z]+)?)\}/g, (whole, path) => {
+    if (path === "default") {
+      const d = defaultOf(field);
+      return d === void 0 ? whole : String(d);
+    }
+    const [head, tail] = path.split(".");
+    if (head === "constraints" && tail) {
+      const c = "constraints" in field ? field.constraints : void 0;
+      const v = c?.[tail];
+      return v === void 0 ? whole : String(v);
+    }
+    return whole;
+  });
+}
+
+// tools/ask/elicit.ts
+var CANNOT = {
+  group: "a group is nested, and elicitation allows no nesting \u2014 ask its children as one flat block",
+  variant: "a variant is a shape that depends on a choice, which a flat form cannot express",
+  range: "a range is two ends of one band; two numbers with a convention between them is not the same answer",
+  counters: "counters share a total and one submit, and a flat form has neither",
+  share: "a share must sum to 100, and nothing in a flat form can hold that invariant",
+  list: "a list of anything but strings is an array of objects, which elicitation excludes",
+  json: "a JSON payload is a nested value by definition",
+  file: "elicitation carries no file transport",
+  media: "elicitation cannot record",
+  action: "an action has no value \u2014 firing it IS the answer, and there is nothing to return"
+};
+var optionValues = (field) => (field.options ?? []).map((o) => toOption(o).value);
+function property(field) {
+  const title = field.label;
+  const description = resolveHint(field);
+  const base = { title, ...description ? { description } : {} };
+  const def = "default" in field ? field.default : void 0;
+  switch (field.type) {
+    case "text":
+      return { ...base, type: "string", ...typeof def === "string" ? { default: def } : {} };
+    case "email":
+      return {
+        ...base,
+        type: "string",
+        format: "email",
+        ...typeof def === "string" ? { default: def } : {}
+      };
+    case "number":
+      return { ...base, type: "number", ...typeof def === "number" ? { default: def } : {} };
+    case "toggle":
+      return { ...base, type: "boolean", ...typeof def === "boolean" ? { default: def } : {} };
+    case "date":
+      return {
+        ...base,
+        type: "string",
+        format: "date",
+        ...typeof def === "string" ? { default: def } : {}
+      };
+    case "datetime":
+      return {
+        ...base,
+        type: "string",
+        format: "date-time",
+        ...typeof def === "string" ? { default: def } : {}
+      };
+    case "enum": {
+      const values = optionValues(field);
+      if (!values.length) return void 0;
+      if (field.multiple === true) {
+        return {
+          ...base,
+          type: "array",
+          items: { type: "string", enum: values },
+          ...Array.isArray(def) ? { default: def } : {}
+        };
+      }
+      return {
+        ...base,
+        type: "string",
+        enum: values,
+        ...typeof def === "string" ? { default: def } : {}
+      };
+    }
+    case "list": {
+      const item = field.itemType ?? "text";
+      if (item !== "text" && item !== "email") return void 0;
+      return { ...base, type: "array", items: { type: "string", enum: [] } };
+    }
+    default:
+      return void 0;
+  }
+}
+function toElicitation(block) {
+  const refusals = [];
+  const properties = {};
+  const required = [];
+  const lost = [];
+  for (const field of block.fields) {
+    const flat = property(field);
+    if (!flat) {
+      refusals.push({
+        key: field.key,
+        type: field.type,
+        because: CANNOT[field.type] ?? (field.type === "enum" ? "its options come from a `source` the host has not resolved yet" : `a list of ${field.itemType} is an array of objects`)
+      });
+      continue;
+    }
+    properties[field.key] = flat;
+    if (field.required) required.push(field.key);
+    const control = field.control;
+    if (control && !["single", "multi", "select", "switch", "picker"].includes(control)) {
+      lost.push(`${field.key}: ${control}`);
+    }
+  }
+  if (refusals.length) return { ok: false, refusals };
+  return {
+    ok: true,
+    lost,
+    elicitation: {
+      mode: "form",
+      message: block.reason ? `${block.reason} ${block.question}` : block.question,
+      requestedSchema: { type: "object", properties, required }
+    }
+  };
+}
+export {
+  toElicitation
+};

package/tools/ask/dist/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>CompPack — an ask from the CLI</title>
+    <script type="module" crossorigin src="/ask.js"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/tools/ask/dist/lint.mjs

@@ -0,0 +1,196 @@
+/* GENERATED by tools/ask/build-support.mjs from src/fields/lint.ts. */
+
+// src/fields/control.ts
+var DEFAULT_CONTROL = {
+  text: "single",
+  email: "single",
+  number: "single",
+  toggle: "switch",
+  date: "picker",
+  datetime: "picker",
+  enum: "select",
+  list: "tags",
+  group: "section",
+  variant: "tabs",
+  json: "code",
+  range: "track",
+  counters: "rows",
+  share: "donut",
+  file: "dropzone",
+  media: "audio",
+  action: "buttons"
+};
+var LEGAL_PREFERRED = {
+  text: ["text-input-field", "text-field", "text-area"],
+  email: ["text-input-field", "text-field"],
+  number: ["slider", "numerical-holder"],
+  enum: ["dropdown", "radio-button", "horizontal-list-picker", "card-picker", "arc-picker", "checkboxes"],
+  date: ["date-time-picker"],
+  datetime: ["date-time-picker"],
+  range: ["range-picker"],
+  counters: ["counter-group"],
+  share: ["pie-chart-picker"],
+  file: ["file-upload"],
+  media: ["voice-recorder"],
+  action: ["button"]
+};
+function preferredOf(field) {
+  const want = field.preferred;
+  if (!want) return void 0;
+  const multi = field.type === "enum" && field.multiple === true;
+  const singleOnly = ["dropdown", "radio-button", "arc-picker", "horizontal-list-picker"];
+  if (multi && singleOnly.includes(want)) return void 0;
+  if (!multi && want === "checkboxes") return void 0;
+  return LEGAL_PREFERRED[field.type]?.includes(want) ? want : void 0;
+}
+function controlOf(field) {
+  return field.control ?? DEFAULT_CONTROL[field.type];
+}
+
+// src/fields/types.ts
+var ESCAPE_WORDING = /^(i don't know|i can't tell|not sure|none of these|unsure|no preference)/i;
+var isEscapeWording = (label) => ESCAPE_WORDING.test(label);
+function toOption(o) {
+  return typeof o === "string" ? { value: o, label: o, escape: isEscapeWording(o) } : { ...o, escape: o.escape ?? isEscapeWording(o.label) };
+}
+
+// src/fields/lint.ts
+var SOFT_FIELD_LIMIT = 6;
+var SEGMENTED_MAX = 4;
+var RADIO_MAX = 8;
+function lintQuestion(block) {
+  const out = [];
+  const add = (rule, level, where, message) => out.push({ rule, level, where, message });
+  if (block.fields.length > SOFT_FIELD_LIMIT) {
+    add(
+      "too-many-fields",
+      "warn",
+      block.slug,
+      `${block.fields.length} fields in one ask. Past ${SOFT_FIELD_LIMIT} it is usually two asks wearing one card \u2014 but split only if the halves stand alone.`
+    );
+  }
+  if (block.blocking && !block.reason && block.provenance === "derived") {
+    add(
+      "blocking-without-reason",
+      "info",
+      block.slug,
+      "A derived blocking ask with no `reason`. If the run stopped because something went wrong, say so \u2014 the user cannot see what it found."
+    );
+  }
+  if (block.reason && block.blocking === false) {
+    add(
+      "reason-without-blocking",
+      "info",
+      block.slug,
+      "`reason` on a non-blocking ask. Nothing has stopped, so there is nothing to explain."
+    );
+  }
+  for (const f of block.fields) out.push(...lintField(f));
+  return out;
+}
+function lintField(f) {
+  const out = [];
+  const add = (rule, level, message) => out.push({ rule, level, where: f.key, message });
+  const control = controlOf(f);
+  if (f.preferred && !preferredOf(f)) {
+    add(
+      "preferred-dropped",
+      "info",
+      `\`preferred: "${f.preferred}"\` is not legal for a ${f.type}${f.type === "enum" && f.multiple ? " (multiple)" : ""}, so it was dropped. The derived widget renders instead \u2014 this is a note, not a fault.`
+    );
+  }
+  if (f.type === "enum") {
+    const options = f.options?.map(toOption);
+    if (options) {
+      if (control === "segmented" && options.length > SEGMENTED_MAX) {
+        add(
+          "segmented-too-wide",
+          "warn",
+          `${options.length} options in a segmented control. Past ${SEGMENTED_MAX} the labels shrink below legible \u2014 this wants to be a select.`
+        );
+      }
+      if (control === "radio" && options.length > RADIO_MAX) {
+        add(
+          "radio-too-long",
+          "warn",
+          `${options.length} radio rows. Past ${RADIO_MAX} use a select \u2014 a list this long is scrolled, and a scrolled radio group hides its own options.`
+        );
+      }
+      if (control === "select" && options.length <= RADIO_MAX && options.length > 0) {
+        add(
+          "select-too-short",
+          "info",
+          `${options.length} options behind a menu. Below ${RADIO_MAX} use radio rows \u2014 options hidden behind a tap are options the user has to remember they can reach.`
+        );
+      }
+      const SHOWS_NOTE = ["cards", "radio", "chips"];
+      if (options.some((o) => o.note) && !SHOWS_NOTE.includes(control)) {
+        add(
+          "notes-not-shown",
+          "warn",
+          "Options carry `note` text that a " + control + " control does not draw. A face showing only a name has hidden the run's work."
+        );
+      }
+      if (f.required && !f.multiple && options.length > 1 && f.default === void 0) {
+        if (!options.some((o) => o.escape)) {
+          add(
+            "no-escape-option",
+            "warn",
+            "A required single-select with no escape and no default. Mark the way out with `escape: true`, or give the field a working default \u2014 forcing a choice from someone who has none produces a worse answer than the gap does."
+          );
+        }
+      }
+    }
+    if (!f.options && !f.source) {
+      add("enum-without-options", "warn", "An enum with neither `options` nor `source` can draw nothing.");
+    }
+  }
+  if (f.type === "share") {
+    const total = f.options.reduce((a, o) => a + (o.pct ?? 0), 0);
+    if (Math.abs(total - 100) > 0.01) {
+      add(
+        "share-does-not-sum",
+        "warn",
+        `Slices sum to ${total}, not 100. A share widget asserts a partition \u2014 if these are not parts of one whole, this is the wrong widget.`
+      );
+    }
+  }
+  if (f.type === "number" || f.type === "range") {
+    const c = f.constraints;
+    if (controlOf(f) === "slider" && (c?.min === void 0 || c?.max === void 0)) {
+      add(
+        "slider-without-bounds",
+        "warn",
+        "A slider with no `min`/`max`. The track has no meaning without both ends."
+      );
+    }
+  }
+  if (f.type === "range" && f.default) {
+    const [lo, hi] = f.default;
+    if (lo >= hi) {
+      add("range-default-inverted", "warn", `Default \`[${lo}, ${hi}]\` has no width.`);
+    }
+  }
+  if (f.type === "counters" && !f.counter?.empty) {
+    add(
+      "no-zero-consequence",
+      "info",
+      "No `counter.empty`. At zero the card will show a count where it should state the consequence of leaving it there."
+    );
+  }
+  if (f.type === "action" && !f.consequence.trim()) {
+    add(
+      "action-without-consequence",
+      "warn",
+      "An action with no consequence sentence asks the user to guess the blast radius."
+    );
+  }
+  if ("children" in f && f.children) {
+    for (const c of f.children) out.push(...lintField(c));
+  }
+  return out;
+}
+export {
+  SOFT_FIELD_LIMIT,
+  lintQuestion
+};

package/tools/ask/dist/speakable.mjs

@@ -0,0 +1,212 @@
+// src/fields/control.ts
+function defaultOf(field) {
+  return "default" in field ? field.default : void 0;
+}
+function resolveHint(field) {
+  if (!field.hint) return void 0;
+  return field.hint.replace(/\{([a-z]+(?:\.[a-zA-Z]+)?)\}/g, (whole, path) => {
+    if (path === "default") {
+      const d = defaultOf(field);
+      return d === void 0 ? whole : String(d);
+    }
+    const [head, tail] = path.split(".");
+    if (head === "constraints" && tail) {
+      const c = "constraints" in field ? field.constraints : void 0;
+      const v = c?.[tail];
+      return v === void 0 ? whole : String(v);
+    }
+    return whole;
+  });
+}
+
+// src/fields/types.ts
+var ESCAPE_WORDING = /^(i don't know|i can't tell|not sure|none of these|unsure|no preference)/i;
+var isEscapeWording = (label) => ESCAPE_WORDING.test(label);
+function toOption(o) {
+  return typeof o === "string" ? { value: o, label: o, escape: isEscapeWording(o) } : { ...o, escape: o.escape ?? isEscapeWording(o.label) };
+}
+
+// tools/speech/speakable.ts
+var NOTHING = "not answered";
+var DEFAULTS = {
+  hints: false,
+  maxOptions: 8
+};
+function joinSpoken(parts, conjunction = "and") {
+  const kept = parts.filter((p) => p !== "");
+  if (kept.length === 0) return "";
+  if (kept.length === 1) return kept[0];
+  return `${kept.slice(0, -1).join(", ")} ${conjunction} ${kept[kept.length - 1]}`;
+}
+function sentences(...parts) {
+  return parts.filter((p) => typeof p === "string" && p.trim() !== "").map((p) => /[.!?]$/.test(p.trim()) ? p.trim() : `${p.trim()}.`).join(" ");
+}
+var num = (n, o) => o?.formatNumber ? o.formatNumber(n) : String(n);
+function speakDate(iso, o) {
+  if (typeof iso !== "string" || iso === "") return NOTHING;
+  if (o?.formatDate) {
+    try {
+      return o.formatDate(iso);
+    } catch {
+      return iso;
+    }
+  }
+  return iso;
+}
+function labelFor(value, options) {
+  if (value === void 0 || value === null || value === "") return NOTHING;
+  const found = options?.map(toOption).find((op) => op.value === value);
+  return found ? found.label : String(value);
+}
+function speakableOfBlock(block, o = {}) {
+  if (!block || typeof block !== "object") return "";
+  const step = block.step ? `Step ${block.step.index}${block.step.label ? `, ${block.step.label}` : ""}` : void 0;
+  return sentences(step, block.question);
+}
+function speakableOfField(field, o = {}) {
+  if (!field || typeof field !== "object") return "";
+  const maxOptions = o.maxOptions ?? DEFAULTS.maxOptions;
+  const required = field.required ? "Required" : void 0;
+  const hint = o.hints ?? DEFAULTS.hints ? resolveHint(field) : void 0;
+  const choices = () => {
+    const opts = "options" in field && Array.isArray(field.options) ? field.options : void 0;
+    if (!opts || opts.length === 0) return void 0;
+    const labels = opts.map((op) => toOption(op).label);
+    if (labels.length <= maxOptions) return `Choose from ${joinSpoken(labels, "or")}`;
+    return `${labels.length} options, starting ${joinSpoken(labels.slice(0, maxOptions), "or")}`;
+  };
+  switch (field.type) {
+    case "action":
+      return sentences(field.label, field.consequence, required);
+    case "enum":
+    case "share":
+      return sentences(field.label, choices(), required, hint);
+    case "toggle":
+      return sentences(field.label, "Yes or no", required, hint);
+    case "range":
+      return sentences(field.label, "A low and a high value", required, hint);
+    case "counters":
+      return sentences(
+        field.label,
+        Array.isArray(field.rows) && field.rows.length > 0 ? `${field.rows.length} rows: ${joinSpoken(field.rows.map((r) => r?.label ?? r?.key ?? ""))}` : void 0,
+        required,
+        hint
+      );
+    case "media":
+      return sentences(field.label, "Record audio", required, hint);
+    case "file":
+      return sentences(field.label, "Attach a file", required, hint);
+    default:
+      return sentences(field.label, required, hint);
+  }
+}
+var REJECTION_SPOKEN = {
+  "re-plan": "I will plan this again",
+  widen: "I will widen the search",
+  escalate: "I will pass this to someone else",
+  "hard-stop": "I have stopped here"
+};
+var spokenRejection = (r) => r === void 0 ? void 0 : REJECTION_SPOKEN[r] ?? r;
+function speakableOfValue(field, value, o = {}) {
+  if (!field || typeof field !== "object") return NOTHING;
+  if (value === void 0 || value === null || value === "") {
+    return field.type === "action" ? "not fired" : NOTHING;
+  }
+  switch (field.type) {
+    case "toggle":
+      return value === true ? "yes" : value === false ? "no" : String(value);
+    case "number":
+      return typeof value === "number" ? num(value, o) : String(value);
+    case "date":
+    case "datetime":
+      return speakDate(value, o);
+    case "enum": {
+      const opts = field.options;
+      if (Array.isArray(value)) {
+        if (value.length === 0) return "none";
+        return joinSpoken(value.map((v) => labelFor(v, opts)));
+      }
+      return labelFor(value, opts);
+    }
+    case "share":
+      return labelFor(value, field.options);
+    case "list": {
+      if (!Array.isArray(value)) return String(value);
+      if (value.length === 0) return "empty";
+      return joinSpoken(value.map((v) => v === null || v === void 0 ? NOTHING : String(v)));
+    }
+    case "range": {
+      if (Array.isArray(value) && value.length === 2) {
+        const [lo, hi] = value;
+        const unit = "unit" in field && typeof field.unit === "string" ? ` ${field.unit}` : "";
+        return `${typeof lo === "number" ? num(lo, o) : String(lo)} to ${typeof hi === "number" ? num(hi, o) : String(hi)}${unit}`;
+      }
+      return String(value);
+    }
+    case "counters": {
+      if (typeof value !== "object" || Array.isArray(value)) return String(value);
+      const rows = Array.isArray(field.rows) ? field.rows : [];
+      const spoken = Object.entries(value).filter(([, n]) => typeof n === "number" && n !== 0).map(([k, n]) => `${rows.find((r) => r?.key === k)?.label ?? k} ${num(n, o)}`);
+      return spoken.length ? joinSpoken(spoken) : "none";
+    }
+    case "variant": {
+      if (typeof value !== "object") return String(value);
+      const v = value;
+      if (typeof v.variant !== "string") return String(value);
+      const child = Array.isArray(field.children) ? field.children.find((c) => c?.key === v.variant) : void 0;
+      const name = child?.label ?? v.variant;
+      if (v.value === void 0) return name;
+      return `${name}, ${child ? speakableOfValue(child, v.value, o) : String(v.value)}`;
+    }
+    case "file": {
+      if (!Array.isArray(value)) return String(value);
+      if (value.length === 0) return "no files";
+      const names = value.map((f) => f && typeof f === "object" && "name" in f ? String(f.name) : "a file");
+      return value.length === 1 ? names[0] : `${num(value.length, o)} files: ${joinSpoken(names)}`;
+    }
+    case "media": {
+      if (typeof value === "object" && value && "name" in value) {
+        return String(value.name);
+      }
+      return "a recording";
+    }
+    case "json":
+      return "a JSON value";
+    case "action":
+      return "fired";
+    default:
+      return String(value);
+  }
+}
+function speakableOfAnswers(block, answers, o = {}) {
+  if (!block || !Array.isArray(block.fields)) return "";
+  const a = answers && typeof answers === "object" ? answers : {};
+  const said = block.fields.filter((f) => f && typeof f === "object").map((f) => {
+    const v = a[f.key];
+    if (v === void 0 || v === null || v === "") return void 0;
+    if (Array.isArray(v) && v.length === 0) return void 0;
+    return `${f.label}, ${speakableOfValue(f, v, o)}`;
+  }).filter((s) => s !== void 0);
+  return said.length === 0 ? "Nothing answered yet." : sentences(...said);
+}
+function speakableOfEnvelope(envelope, block, o = {}) {
+  if (!envelope || typeof envelope !== "object") return "";
+  const { state, outcome } = envelope;
+  if (state === "skipped") return "Skipped.";
+  if (state === "failed") {
+    return sentences("That did not go through", spokenRejection(envelope.rejection));
+  }
+  if (state === "superseded") return "Reopened. The earlier answer no longer stands.";
+  if (outcome === "reject") return sentences("Declined", spokenRejection(envelope.rejection));
+  const body = block ? speakableOfAnswers(block, envelope.answers ?? {}, o) : "";
+  if (body === "" || body === "Nothing answered yet.") return "Done.";
+  return body;
+}
+export {
+  joinSpoken,
+  speakableOfAnswers,
+  speakableOfBlock,
+  speakableOfEnvelope,
+  speakableOfField,
+  speakableOfValue
+};