@linxiraos/pi-tui 1.4.13 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/CHANGELOG.md +17 -34
  2. package/dist/types/chat/messages.d.ts +2 -0
  3. package/dist/types/chat/spotlight.d.ts +8 -3
  4. package/dist/types/chat/transcript-render-helpers.d.ts +5 -0
  5. package/dist/types/components/editor.d.ts +4 -1
  6. package/dist/types/html-form/data.d.ts +56 -0
  7. package/dist/types/html-form/dialog.d.ts +51 -0
  8. package/dist/types/html-form/media.d.ts +28 -0
  9. package/dist/types/html-form/paginate.d.ts +43 -0
  10. package/dist/types/html-form/parse.d.ts +99 -0
  11. package/dist/types/overlays/ask-dialog.d.ts +11 -6
  12. package/dist/types/overlays/copy-targets.d.ts +8 -6
  13. package/dist/types/overlays/hook-editor.d.ts +3 -1
  14. package/dist/types/overlays/hub-frame.d.ts +2 -0
  15. package/dist/types/overlays/model-hub.d.ts +2 -0
  16. package/dist/types/overlays/team-hub.d.ts +150 -0
  17. package/dist/types/render/row-moves.d.ts +41 -0
  18. package/dist/types/status-line/component.d.ts +5 -0
  19. package/dist/types/status-line/host.d.ts +2 -2
  20. package/dist/types/status-line/schema.d.ts +1 -1
  21. package/dist/types/status-line/types.d.ts +8 -0
  22. package/dist/types/tools/ask.d.ts +11 -49
  23. package/dist/types/tools/autoresearch.d.ts +2 -2
  24. package/dist/types/tools/eval.d.ts +4 -0
  25. package/dist/types/tools/grouped-file-output.d.ts +2 -0
  26. package/dist/types/tools/shell-viz.d.ts +6 -2
  27. package/dist/types/tools/xd-url.d.ts +6 -0
  28. package/dist/types/windows-input-mode.d.ts +8 -0
  29. package/package.json +9 -9
  30. package/src/charts/table-data.ts +18 -5
  31. package/src/chat/chat-transcript-builder.ts +27 -10
  32. package/src/chat/image-loading.ts +55 -0
  33. package/src/chat/messages.d.ts +2 -0
  34. package/src/chat/messages.ts +3 -0
  35. package/src/chat/spotlight.d.ts +8 -3
  36. package/src/chat/spotlight.ts +23 -11
  37. package/src/chat/tool-execution.ts +5 -0
  38. package/src/chat/transcript-render-helpers.d.ts +5 -0
  39. package/src/chat/transcript-render-helpers.ts +13 -0
  40. package/src/chrome/transcript-container.ts +1 -1
  41. package/src/components/editor.d.ts +4 -1
  42. package/src/components/editor.ts +3 -2
  43. package/src/components/markdown.ts +70 -12
  44. package/src/html-form/data.d.ts +56 -0
  45. package/src/html-form/data.ts +177 -0
  46. package/src/html-form/dialog.ts +1450 -0
  47. package/src/html-form/media.ts +105 -0
  48. package/src/html-form/paginate.ts +99 -0
  49. package/src/html-form/parse.d.ts +99 -0
  50. package/src/html-form/parse.ts +568 -0
  51. package/src/lang-from-path.ts +1 -0
  52. package/src/latex-block.ts +3 -3
  53. package/src/latex-to-unicode.ts +18 -5
  54. package/src/overlays/ask-dialog.ts +69 -52
  55. package/src/overlays/copy-targets.d.ts +8 -6
  56. package/src/overlays/copy-targets.ts +25 -46
  57. package/src/overlays/hook-editor.ts +16 -15
  58. package/src/overlays/hub-frame.ts +8 -1
  59. package/src/overlays/model-hub.ts +12 -2
  60. package/src/overlays/spotlight-sheet.ts +18 -18
  61. package/src/overlays/team-hub.ts +901 -0
  62. package/src/render/row-moves.d.ts +41 -0
  63. package/src/render/row-moves.ts +109 -0
  64. package/src/setup/wizard-overlay.ts +7 -3
  65. package/src/status-line/component.ts +19 -0
  66. package/src/status-line/footer.ts +2 -2
  67. package/src/status-line/host.ts +2 -2
  68. package/src/status-line/presets.ts +6 -6
  69. package/src/status-line/schema.ts +2 -1
  70. package/src/status-line/segments.ts +31 -4
  71. package/src/status-line/startup.ts +1 -1
  72. package/src/status-line/types.ts +8 -0
  73. package/src/stdin-buffer.ts +15 -1
  74. package/src/terminal-capabilities.ts +12 -3
  75. package/src/terminal.ts +41 -3
  76. package/src/tools/ask.d.ts +11 -49
  77. package/src/tools/ask.ts +201 -606
  78. package/src/tools/autoresearch.ts +2 -2
  79. package/src/tools/debug.ts +31 -38
  80. package/src/tools/eval.d.ts +4 -0
  81. package/src/tools/eval.ts +4 -0
  82. package/src/tools/grep.ts +38 -16
  83. package/src/tools/grouped-file-output.d.ts +2 -0
  84. package/src/tools/grouped-file-output.ts +5 -0
  85. package/src/tools/shell-viz-render.ts +37 -6
  86. package/src/tools/shell-viz.d.ts +6 -2
  87. package/src/tools/shell-viz.ts +19 -6
  88. package/src/tools/xd-url.d.ts +6 -0
  89. package/src/tools/xd-url.ts +19 -1
  90. package/src/tui.ts +129 -1
  91. package/src/windows-input-mode.d.ts +8 -0
  92. package/src/windows-input-mode.ts +13 -0
@@ -19,6 +19,8 @@ export declare const BACKGROUND_TAN_DISPATCH_MESSAGE_TYPE = "background-tan-disp
19
19
  export declare const PREWALK_PLAN_MESSAGE_TYPE = "prewalk-plan";
20
20
  /** Custom message type for the transient Vibe mode directive. */
21
21
  export declare const VIBE_MODE_CONTEXT_MESSAGE_TYPE = "vibe-mode-context";
22
+ /** Custom message type for the transient Lead (PM) mode directive. */
23
+ export declare const LEAD_MODE_CONTEXT_MESSAGE_TYPE = "lead-mode-context";
22
24
  /** Fallback type for extension-injected messages that omit a custom type. */
23
25
  export declare const DEFAULT_CUSTOM_MESSAGE_TYPE = "custom-message";
24
26
  /** Custom message carrying a coding request delegated by the live voice model. */
@@ -28,6 +28,9 @@ export const PREWALK_PLAN_MESSAGE_TYPE = "prewalk-plan";
28
28
  /** Custom message type for the transient Vibe mode directive. */
29
29
  export const VIBE_MODE_CONTEXT_MESSAGE_TYPE = "vibe-mode-context";
30
30
 
31
+ /** Custom message type for the transient Lead (PM) mode directive. */
32
+ export const LEAD_MODE_CONTEXT_MESSAGE_TYPE = "lead-mode-context";
33
+
31
34
  /** Fallback type for extension-injected messages that omit a custom type. */
32
35
  export const DEFAULT_CUSTOM_MESSAGE_TYPE = "custom-message";
33
36
 
@@ -14,8 +14,9 @@ export interface SpotlightOriginal {
14
14
  /** The file a `read` showed (picks the sheet's grammar). */
15
15
  path?: string;
16
16
  /**
17
- * One character per original line, from its first (at most {@link SPOTLIGHT_VIEW_LINES}): Spotlight's score as
18
- * `0`–`9` relative to the result's hottest line, `-` for a line it never scored. Lines past the end are unscored.
17
+ * One character per original line, from its first (at most {@link SPOTLIGHT_VIEW_LINES}): the line's rank among
18
+ * the lines Spotlight scored, `0` (coldest) to `9` (hottest), `-` for a line it never scored. Lines past the end
19
+ * are unscored.
19
20
  */
20
21
  heat: string;
21
22
  /** Runs of original lines the model was shown verbatim, `[first, last]` 1-based positions in the original. */
@@ -149,7 +150,11 @@ export interface SpotlightDetails {
149
150
  export declare function spotlightSaving(spotlight: SpotlightDetails): number;
150
151
  /** The trace a result's details carry, or undefined when the experiment did not shape it. */
151
152
  export declare function spotlightDetails(details: unknown): SpotlightDetails | undefined;
152
- /** The {@link SpotlightOriginal.heat} of per-line scores: each relative to the best, in ten steps. */
153
+ /**
154
+ * The {@link SpotlightOriginal.heat} of per-line scores: each scored line's rank among them in ten steps, ties sharing
155
+ * their mean place. Spotlight's attention is heavy-tailed (a line or two take most of it), so a share of the hottest
156
+ * line would put nearly every line at `0`.
157
+ */
153
158
  export declare function encodeHeat(scores: readonly (number | null)[]): string;
154
159
  /** The heat of original line `i` (0-based) in [0, 1], or undefined when Spotlight never scored it. */
155
160
  export declare function heatAt(heat: string, i: number): number | undefined;
@@ -25,8 +25,9 @@ export interface SpotlightOriginal {
25
25
  /** The file a `read` showed (picks the sheet's grammar). */
26
26
  path?: string;
27
27
  /**
28
- * One character per original line, from its first (at most {@link SPOTLIGHT_VIEW_LINES}): Spotlight's score as
29
- * `0`–`9` relative to the result's hottest line, `-` for a line it never scored. Lines past the end are unscored.
28
+ * One character per original line, from its first (at most {@link SPOTLIGHT_VIEW_LINES}): the line's rank among
29
+ * the lines Spotlight scored, `0` (coldest) to `9` (hottest), `-` for a line it never scored. Lines past the end
30
+ * are unscored.
30
31
  */
31
32
  heat: string;
32
33
  /** Runs of original lines the model was shown verbatim, `[first, last]` 1-based positions in the original. */
@@ -194,17 +195,28 @@ export function spotlightDetails(details: unknown): SpotlightDetails | undefined
194
195
  return s as unknown as SpotlightDetails;
195
196
  }
196
197
 
197
- /** The {@link SpotlightOriginal.heat} of per-line scores: each relative to the best, in ten steps. */
198
+ /**
199
+ * The {@link SpotlightOriginal.heat} of per-line scores: each scored line's rank among them in ten steps, ties sharing
200
+ * their mean place. Spotlight's attention is heavy-tailed (a line or two take most of it), so a share of the hottest
201
+ * line would put nearly every line at `0`.
202
+ */
198
203
  export function encodeHeat(scores: readonly (number | null)[]): string {
199
204
  const n = Math.min(scores.length, SPOTLIGHT_VIEW_LINES);
200
- let top = 0;
201
- for (let i = 0; i < n; i++) top = Math.max(top, scores[i] ?? 0);
202
- let out = "";
205
+ const order: { score: number; line: number }[] = [];
203
206
  for (let i = 0; i < n; i++) {
204
- const s = scores[i];
205
- out += s === null || s === undefined ? "-" : String(top > 0 ? Math.round((Math.max(0, s) / top) * 9) : 0);
207
+ const score = scores[i];
208
+ if (score !== null && score !== undefined) order.push({ score, line: i });
209
+ }
210
+ order.sort((a, b) => a.score - b.score);
211
+ const digits = Array.from<string>({ length: n }).fill("-");
212
+ for (let i = 0; i < order.length;) {
213
+ let j = i;
214
+ while (j + 1 < order.length && order[j + 1].score === order[i].score) j++;
215
+ const digit = String(order.length > 1 ? Math.round(((i + j) / 2 / (order.length - 1)) * 9) : 9);
216
+ for (let k = i; k <= j; k++) digits[order[k].line] = digit;
217
+ i = j + 1;
206
218
  }
207
- return out.replace(/-+$/, "");
219
+ return digits.join("").replace(/-+$/, "");
208
220
  }
209
221
 
210
222
  /** The heat of original line `i` (0-based) in [0, 1], or undefined when Spotlight never scored it. */
@@ -226,8 +238,8 @@ export function keptRanges(kept: readonly boolean[]): [number, number][] {
226
238
  return out;
227
239
  }
228
240
 
229
- /** Heat digit from which a line counts as hot: a hidden one was cut though hot. */
230
- const HOT_DIGIT = 6;
241
+ /** Heat digit from which a line counts as hot (its output's top ~6 %): a hidden one was cut though hot. */
242
+ const HOT_DIGIT = 9;
231
243
 
232
244
  /** Whether original line `i` (0-based) scored hot: a heat digit of {@link HOT_DIGIT} or more. */
233
245
  export function spotlightHot(heat: string, i: number): boolean {
@@ -656,6 +656,11 @@ export class ToolExecutionComponent extends Container {
656
656
  const source = this.#shellTrace
657
657
  ? shellVisualization(this.#shellTrace)
658
658
  : (this.#shellPendingTrace ??= new RunTrace(script));
659
+ // An unrestorable stored trace renders like visualization-off: plain command and output.
660
+ if (!source) {
661
+ this.#shellPresentation = undefined;
662
+ return undefined;
663
+ }
659
664
  this.#shellPresentation = readShellPresentation(
660
665
  source,
661
666
  this.#shellPreferences,
@@ -41,6 +41,11 @@ export declare function buildLaunchCompletionBlock(message: CustomOrHookMessage)
41
41
  * the live expanded-state getter for the cached card.
42
42
  */
43
43
  export declare function buildIrcMessageCard(message: CustomOrHookMessage, getExpanded: () => boolean): Component;
44
+ /** Present a consumed parent steer as an IRC card without interpreting its model-facing envelope. */
45
+ export declare function buildParentIrcMessageCard(parentIrc: {
46
+ from: string;
47
+ body: string;
48
+ }, timestamp: number, getExpanded: () => boolean): Component;
44
49
  /**
45
50
  * Render a `fileMention` message's files as a transcript block of "Read <path>"
46
51
  * rows. `indent` sets the left pad: the live chat renders within an outer gutter
@@ -225,6 +225,19 @@ export function buildIrcMessageCard(message: CustomOrHookMessage, getExpanded: (
225
225
  );
226
226
  }
227
227
 
228
+ /** Present a consumed parent steer as an IRC card without interpreting its model-facing envelope. */
229
+ export function buildParentIrcMessageCard(
230
+ parentIrc: { from: string; body: string },
231
+ timestamp: number,
232
+ getExpanded: () => boolean,
233
+ ): Component {
234
+ return createIrcMessageCard(
235
+ { kind: "incoming", from: parentIrc.from, body: parentIrc.body, timestamp },
236
+ getExpanded,
237
+ theme,
238
+ );
239
+ }
240
+
228
241
  /**
229
242
  * Render a `fileMention` message's files as a transcript block of "Read <path>"
230
243
  * rows. `indent` sets the left pad: the live chat renders within an outer gutter
@@ -335,7 +335,7 @@ class CompactRun implements Component {
335
335
  }
336
336
 
337
337
  describe(): NativeNode {
338
- this.#node ??= col(this.#members, { role: "omp.compact", gap: "none" });
338
+ this.#node ??= col(this.#members, { role: "zeta.compact", gap: "none" });
339
339
  return this.#node;
340
340
  }
341
341
  }
@@ -323,7 +323,10 @@ export declare class Editor implements Component, Focusable {
323
323
  * Used for command-like autocomplete actions whose typed trigger should not count as the edit being undone.
324
324
  */
325
325
  undoPastTransientText(transientText: string): void;
326
- setText(text: string): void;
326
+ /** Replace the buffer; the caret lands at the end unless `cursor: "start"` (multi-row text only). */
327
+ setText(text: string, options?: {
328
+ cursor?: "start" | "end";
329
+ }): void;
327
330
  submit(): void;
328
331
  /** Insert text at the current cursor position */
329
332
  insertText(text: string): void;
@@ -3476,10 +3476,11 @@ export class Editor implements Component, Focusable {
3476
3476
  this.#applyUndo();
3477
3477
  }
3478
3478
 
3479
- setText(text: string): void {
3479
+ /** Replace the buffer; the caret lands at the end unless `cursor: "start"` (multi-row text only). */
3480
+ setText(text: string, options: { cursor?: "start" | "end" } = {}): void {
3480
3481
  this.#historyIndex = -1; // Exit history browsing mode
3481
3482
  this.#resetKillSequence();
3482
- this.#setTextInternal(text);
3483
+ this.#setTextInternal(text, options.cursor);
3483
3484
  }
3484
3485
  submit(): void {
3485
3486
  if (this.disableSubmit) return;
@@ -1,3 +1,4 @@
1
+ import { stripVTControlCharacters } from "node:util";
1
2
  import { LRUCache } from "@linxiraos/pi-utils/lru";
2
3
  import {
3
4
  Lexer,
@@ -395,6 +396,58 @@ function replaceLast(raw: string, from: string, to: string): string | undefined
395
396
  return at < 0 ? undefined : raw.slice(0, at) + to + raw.slice(at + from.length);
396
397
  }
397
398
 
399
+ // The lone `-` line a streaming source ends on while a bullet is still being typed.
400
+ const PENDING_BULLET_LINE = /\n[ \t>]*-[ \t]*$/;
401
+
402
+ /** `text` without its last line (and the newline in front of it). */
403
+ function dropLastLine(text: string): string {
404
+ return text.slice(0, Math.max(0, text.lastIndexOf("\n")));
405
+ }
406
+
407
+ /**
408
+ * A copy of `token`, the last block of a streaming render, without the lone
409
+ * `-` line the source ends on when that line underlines a paragraph, or
410
+ * `undefined` when the source does not end that way. Under a paragraph a lone
411
+ * `-` is a setext H2 underline, but a stream ending on one is almost always
412
+ * typing a bullet (`- item`), which leaves the paragraph a paragraph: held
413
+ * back, the paragraph keeps its rows instead of flashing as a heading for a
414
+ * frame. A `-` line followed by a newline, or a longer underline, is a heading
415
+ * as written. Follows the last list item or blockquote child; every `raw` on
416
+ * the way drops the held line, so row caches keyed on it see the source the
417
+ * copy renders.
418
+ */
419
+ function holdPendingBullet(token: Token): Token | undefined {
420
+ if (!PENDING_BULLET_LINE.test(token.raw)) return undefined;
421
+ const raw = dropLastLine(token.raw);
422
+ switch (token.type) {
423
+ case "heading":
424
+ return { type: "paragraph", raw, text: token.text, tokens: token.tokens ?? [] };
425
+ case "blockquote": {
426
+ const children: Token[] = token.tokens ?? [];
427
+ const inner = children.at(-1);
428
+ const held = inner && holdPendingBullet(inner);
429
+ if (!held) return undefined;
430
+ return { ...token, raw, text: dropLastLine(token.text), tokens: [...children.slice(0, -1), held] };
431
+ }
432
+ case "list": {
433
+ const items: Tokens.ListItem[] = token.items;
434
+ const item = items.at(-1);
435
+ const inner = item?.tokens.at(-1);
436
+ const held = inner && holdPendingBullet(inner);
437
+ if (!item || !held) return undefined;
438
+ const grown = {
439
+ ...item,
440
+ raw: dropLastLine(item.raw),
441
+ text: dropLastLine(item.text),
442
+ tokens: [...item.tokens.slice(0, -1), held],
443
+ };
444
+ return { ...token, raw, items: [...items.slice(0, -1), grown] };
445
+ }
446
+ default:
447
+ return undefined;
448
+ }
449
+ }
450
+
398
451
  /**
399
452
  * A copy of `token`, the last block of a streaming render, whose still-written
400
453
  * inline run is speculatively closed ({@link speculativeInlineClose}), or
@@ -2006,7 +2059,7 @@ function plainInlineTokens(tokens: Token[]): string {
2006
2059
  let result = "";
2007
2060
  for (const token of tokens) {
2008
2061
  if (isMathToken(token)) {
2009
- result += renderMathToken(token.text);
2062
+ result += stripVTControlCharacters(renderMathToken(token.text));
2010
2063
  continue;
2011
2064
  }
2012
2065
  switch (token.type) {
@@ -3225,7 +3278,9 @@ export class Markdown implements Component {
3225
3278
  // being written renders its open link or math span as already closed.
3226
3279
  const lexed = this.#lexTokens(normalizedText);
3227
3280
  const tail = lexed.at(-1);
3228
- const speculated = this.transientRenderCache && tail ? speculateStreamingToken(tail) : undefined;
3281
+ const held = this.transientRenderCache && tail ? holdPendingBullet(tail) : undefined;
3282
+ const open = held ?? tail;
3283
+ const speculated = this.transientRenderCache && open ? (speculateStreamingToken(open) ?? held) : undefined;
3229
3284
  const tokens = speculated ? [...lexed.slice(0, -1), speculated] : lexed;
3230
3285
  let contentLines: string[];
3231
3286
  this.#activeRenderSignature = signature;
@@ -3972,10 +4027,8 @@ export class Markdown implements Component {
3972
4027
  switch (token.type) {
3973
4028
  case "heading": {
3974
4029
  const headingLevel = token.depth;
3975
- const headingPrefix = `${"#".repeat(headingLevel)} `;
3976
4030
  const headingText = this.#renderInlineTokens(token.tokens || [], this.#proseFgExemptContext(styleContext));
3977
4031
  const headingPlainText = plainInlineTokens(token.tokens || []);
3978
- let styledHeading: string;
3979
4032
  // A sized heading draws plain text, which would drop a clickable extension link's marker.
3980
4033
  if (headingLevel === 1 && TERMINAL.textSizing && stripExtensionLinkMarkers(headingText) === headingText) {
3981
4034
  const plainWidth = visibleWidth(headingPlainText);
@@ -3991,14 +4044,7 @@ export class Markdown implements Component {
3991
4044
  break;
3992
4045
  }
3993
4046
  }
3994
- if (headingLevel === 1) {
3995
- styledHeading = this.#theme.heading(this.#theme.bold(this.#theme.underline(headingText)), 1);
3996
- } else if (headingLevel === 2) {
3997
- styledHeading = this.#theme.heading(this.#theme.bold(headingText), 2);
3998
- } else {
3999
- styledHeading = this.#theme.heading(this.#theme.bold(headingPrefix + headingText), headingLevel);
4000
- }
4001
- lines.push(renderedLine(styledHeading));
4047
+ lines.push(renderedLine(this.#styleHeading(headingLevel, headingText)));
4002
4048
  if (nextTokenType && nextTokenType !== "space") {
4003
4049
  lines.push(renderedLine("")); // Add spacing after headings (unless space token follows)
4004
4050
  }
@@ -4572,6 +4618,11 @@ export class Markdown implements Component {
4572
4618
  } else {
4573
4619
  lines.push({ text: this.#renderInlineTokens(token.tokens || [], styleContext), nested: false });
4574
4620
  }
4621
+ } else if (token.type === "heading") {
4622
+ // A heading in a list item (an ATX line, or a paragraph over a setext
4623
+ // underline) keeps its inline formatting and heading style.
4624
+ const headingText = this.#renderInlineTokens(token.tokens || [], this.#proseFgExemptContext(styleContext));
4625
+ lines.push({ text: this.#styleHeading(token.depth, headingText), nested: false });
4575
4626
  } else if (token.type === "code") {
4576
4627
  // Code block in list item
4577
4628
  const codeIndent = padding(this.#codeBlockIndent);
@@ -4600,6 +4651,13 @@ export class Markdown implements Component {
4600
4651
  return lines;
4601
4652
  }
4602
4653
 
4654
+ /** Rendered inline heading text styled for its level, as one (unsized) line. */
4655
+ #styleHeading(depth: number, headingText: string): string {
4656
+ if (depth === 1) return this.#theme.heading(this.#theme.bold(this.#theme.underline(headingText)), 1);
4657
+ if (depth === 2) return this.#theme.heading(this.#theme.bold(headingText), 2);
4658
+ return this.#theme.heading(this.#theme.bold(`${"#".repeat(depth)} ${headingText}`), depth);
4659
+ }
4660
+
4603
4661
  /**
4604
4662
  * Get the visible width of the longest word in a string.
4605
4663
  */
@@ -0,0 +1,56 @@
1
+ /**
2
+ * Answers of a parsed {@link HtmlForm}: the data shape a submission reports,
3
+ * the defaults a form opens with, and a readable question/answer listing for
4
+ * transcripts and non-interactive hosts.
5
+ *
6
+ * @example
7
+ * const form = parseHtmlForm(html);
8
+ * const data = defaultFormData(form); // { db: "sqlite", notes: "" }
9
+ * formAnswers(form, data); // [{ name: "db", question: "Database", answer: "SQLite" }, …]
10
+ */
11
+ import { type ChoiceField, type FormField, type HtmlForm, type TextField } from "./parse";
12
+ /** Submitted value of one control: text, a number for `number`/`range` inputs, or a group's checked values. */
13
+ export type HtmlFormValue = string | number | string[];
14
+ /**
15
+ * Submitted form data by control `name`. Radios, single checkboxes and single
16
+ * selects give their value (omitted when nothing is chosen); checkbox groups
17
+ * and multi-selects give an array; text fields always give their text.
18
+ * Disabled options, unnamed controls and buttons never appear; hidden inputs do.
19
+ */
20
+ export type HtmlFormData = Record<string, HtmlFormValue>;
21
+ /** One field as a question and its answer, both plain text. */
22
+ export interface FormAnswer {
23
+ name: string;
24
+ question: string;
25
+ answer: string;
26
+ }
27
+ /** Label of the free-text answer the UI adds to radio and checkbox groups ({@link ChoiceField.other}). */
28
+ export declare const OTHER_LABEL = "Other";
29
+ /** Whether a choice field reports an array (checkbox group, multi-select) rather than one value. */
30
+ export declare function isArrayChoice(field: ChoiceField): boolean;
31
+ /**
32
+ * Value a choice field contributes given its checked option indices and, when
33
+ * the user chose its "Other" answer, that answer's text: the typed text stands
34
+ * in for a radio's value, or joins a checkbox group's array. Undefined when the
35
+ * field contributes nothing; blank Other text counts as no answer.
36
+ */
37
+ export declare function choiceValue(field: ChoiceField, checked: ReadonlySet<number>, other?: string): HtmlFormValue | undefined;
38
+ /** Value a text field contributes: a number for non-empty numeric `number`/`range` inputs, else the text. */
39
+ export declare function textValue(field: TextField, text: string): HtmlFormValue;
40
+ /**
41
+ * Why `value` is not an acceptable answer for `field`, or undefined when it is.
42
+ * Enforces `required`, numeric `min`/`max`, `minlength`/`maxlength`, `email`
43
+ * and `url` shapes, and `pattern` (anchored, as HTML does; an invalid pattern
44
+ * is ignored).
45
+ */
46
+ export declare function fieldError(field: FormField, value: HtmlFormValue | undefined): string | undefined;
47
+ /** Data the form submits untouched: hidden inputs, preselected options and prefilled text. */
48
+ export declare function defaultFormData(form: HtmlForm): HtmlFormData;
49
+ /**
50
+ * The question each field answers: its own label, else the text block right
51
+ * before it (`<p>Which database?</p>` above a radio group), else its section
52
+ * title, else a lone option's label (a single checkbox), else its name.
53
+ */
54
+ export declare function fieldQuestions(form: HtmlForm): Map<FormField, string>;
55
+ /** Answers of every named field, in form order, with option values shown as their labels. */
56
+ export declare function formAnswers(form: HtmlForm, data: HtmlFormData): FormAnswer[];
@@ -0,0 +1,177 @@
1
+ /**
2
+ * Answers of a parsed {@link HtmlForm}: the data shape a submission reports,
3
+ * the defaults a form opens with, and a readable question/answer listing for
4
+ * transcripts and non-interactive hosts.
5
+ *
6
+ * @example
7
+ * const form = parseHtmlForm(html);
8
+ * const data = defaultFormData(form); // { db: "sqlite", notes: "" }
9
+ * formAnswers(form, data); // [{ name: "db", question: "Database", answer: "SQLite" }, …]
10
+ */
11
+ import { type ChoiceField, type FormField, type HtmlForm, spansText, type TextField } from "./parse";
12
+
13
+ /** Submitted value of one control: text, a number for `number`/`range` inputs, or a group's checked values. */
14
+ export type HtmlFormValue = string | number | string[];
15
+
16
+ /**
17
+ * Submitted form data by control `name`. Radios, single checkboxes and single
18
+ * selects give their value (omitted when nothing is chosen); checkbox groups
19
+ * and multi-selects give an array; text fields always give their text.
20
+ * Disabled options, unnamed controls and buttons never appear; hidden inputs do.
21
+ */
22
+ export type HtmlFormData = Record<string, HtmlFormValue>;
23
+
24
+ /** One field as a question and its answer, both plain text. */
25
+ export interface FormAnswer {
26
+ name: string;
27
+ question: string;
28
+ answer: string;
29
+ }
30
+
31
+ /** Label of the free-text answer the UI adds to radio and checkbox groups ({@link ChoiceField.other}). */
32
+ export const OTHER_LABEL = "Other";
33
+
34
+ /** Whether a choice field reports an array (checkbox group, multi-select) rather than one value. */
35
+ export function isArrayChoice(field: ChoiceField): boolean {
36
+ return field.multi && field.options.length > 1;
37
+ }
38
+
39
+ /**
40
+ * Value a choice field contributes given its checked option indices and, when
41
+ * the user chose its "Other" answer, that answer's text: the typed text stands
42
+ * in for a radio's value, or joins a checkbox group's array. Undefined when the
43
+ * field contributes nothing; blank Other text counts as no answer.
44
+ */
45
+ export function choiceValue(
46
+ field: ChoiceField,
47
+ checked: ReadonlySet<number>,
48
+ other?: string,
49
+ ): HtmlFormValue | undefined {
50
+ const typed = field.other ? other?.trim() : undefined;
51
+ const values = field.options.flatMap((option, index) =>
52
+ checked.has(index) && !option.disabled ? [option.value] : [],
53
+ );
54
+ if (isArrayChoice(field)) return typed ? [...values, typed] : values;
55
+ return typed || values[0];
56
+ }
57
+
58
+ /** Value a text field contributes: a number for non-empty numeric `number`/`range` inputs, else the text. */
59
+ export function textValue(field: TextField, text: string): HtmlFormValue {
60
+ if ((field.type === "number" || field.type === "range") && text.trim() !== "") {
61
+ const number = Number(text);
62
+ if (Number.isFinite(number)) return number;
63
+ }
64
+ return text;
65
+ }
66
+
67
+ /**
68
+ * Why `value` is not an acceptable answer for `field`, or undefined when it is.
69
+ * Enforces `required`, numeric `min`/`max`, `minlength`/`maxlength`, `email`
70
+ * and `url` shapes, and `pattern` (anchored, as HTML does; an invalid pattern
71
+ * is ignored).
72
+ */
73
+ export function fieldError(field: FormField, value: HtmlFormValue | undefined): string | undefined {
74
+ if (field.kind === "choice") {
75
+ const empty = value === undefined || (Array.isArray(value) && value.length === 0);
76
+ if (!field.required || !empty) return undefined;
77
+ return isArrayChoice(field) ? "Select at least one" : "Required";
78
+ }
79
+ const text = value === undefined ? "" : String(value);
80
+ if (text.trim() === "") return field.required ? "Required" : undefined;
81
+ if (field.type === "number" || field.type === "range") {
82
+ const number = Number(text);
83
+ if (!Number.isFinite(number)) return "Enter a number";
84
+ if (field.min !== undefined && number < field.min) return `Must be at least ${field.min}`;
85
+ if (field.max !== undefined && number > field.max) return `Must be at most ${field.max}`;
86
+ }
87
+ if (field.minLength !== undefined && text.length < field.minLength)
88
+ return `Needs at least ${field.minLength} characters`;
89
+ if (field.maxLength !== undefined && text.length > field.maxLength) return `At most ${field.maxLength} characters`;
90
+ if (field.type === "email" && !/^[^\s@]+@[^\s@]+$/.test(text)) return "Enter an email address";
91
+ if (field.type === "url" && !URL.canParse(text)) return "Enter a full URL";
92
+ if (field.pattern && compilePattern(field.pattern)?.test(text) === false) {
93
+ return `Must match ${field.pattern.length > 40 ? `${field.pattern.slice(0, 39)}…` : field.pattern}`;
94
+ }
95
+ return undefined;
96
+ }
97
+
98
+ /** `^(?:pattern)$` as HTML matches `pattern`, or undefined when the model wrote an invalid one. */
99
+ function compilePattern(pattern: string): RegExp | undefined {
100
+ try {
101
+ return new RegExp(`^(?:${pattern})$`, "v");
102
+ } catch {
103
+ return undefined;
104
+ }
105
+ }
106
+
107
+ /** Data the form submits untouched: hidden inputs, preselected options and prefilled text. */
108
+ export function defaultFormData(form: HtmlForm): HtmlFormData {
109
+ const data: HtmlFormData = {};
110
+ for (const [name, value] of form.hidden) data[name] = value;
111
+ for (const field of form.fields) {
112
+ if (!field.name) continue;
113
+ const value =
114
+ field.kind === "text"
115
+ ? textValue(field, field.value)
116
+ : choiceValue(field, new Set(field.options.flatMap((option, index) => (option.checked ? [index] : []))));
117
+ if (value !== undefined) data[field.name] = value;
118
+ }
119
+ return data;
120
+ }
121
+
122
+ /**
123
+ * The question each field answers: its own label, else the text block right
124
+ * before it (`<p>Which database?</p>` above a radio group), else its section
125
+ * title, else a lone option's label (a single checkbox), else its name.
126
+ */
127
+ export function fieldQuestions(form: HtmlForm): Map<FormField, string> {
128
+ const questions = new Map<FormField, string>();
129
+ for (const section of form.sections) {
130
+ const title = spansText(section.title);
131
+ let caption = "";
132
+ for (const block of section.blocks) {
133
+ if (block.kind === "field") {
134
+ const field = block.field;
135
+ const own = spansText(field.label);
136
+ const lone =
137
+ field.kind === "choice" && field.options.length === 1 ? spansText(field.options[0]!.label) : "";
138
+ questions.set(field, oneLine(own || caption || title || lone || field.name));
139
+ caption = "";
140
+ continue;
141
+ }
142
+ caption = block.kind === "text" ? spansText(block.spans) : "";
143
+ }
144
+ }
145
+ return questions;
146
+ }
147
+
148
+ /** Answers of every named field, in form order, with option values shown as their labels. */
149
+ export function formAnswers(form: HtmlForm, data: HtmlFormData): FormAnswer[] {
150
+ const questions = fieldQuestions(form);
151
+ const answers: FormAnswer[] = [];
152
+ for (const field of form.fields) {
153
+ if (!field.name) continue;
154
+ const value = data[field.name];
155
+ answers.push({
156
+ name: field.name,
157
+ question: questions.get(field) ?? field.name,
158
+ answer: answerText(field, value),
159
+ });
160
+ }
161
+ return answers;
162
+ }
163
+
164
+ function answerText(field: FormField, value: HtmlFormValue | undefined): string {
165
+ if (value === undefined) return "";
166
+ if (field.kind === "text") return String(value);
167
+ const labelOf = (raw: string): string => {
168
+ const option = field.options.find(candidate => candidate.value === raw);
169
+ if (option) return oneLine(spansText(option.label)) || raw;
170
+ return field.other ? `${OTHER_LABEL}: ${raw}` : raw;
171
+ };
172
+ return Array.isArray(value) ? value.map(labelOf).join(", ") : labelOf(String(value));
173
+ }
174
+
175
+ function oneLine(text: string): string {
176
+ return text.replace(/\s+/g, " ").trim();
177
+ }