@zergai/ztc 0.2.6-dev.36101352252 → 0.2.7-dev.36236183737

package/dist/ui/widgets/panel_frame.d.ts

@@ -5,6 +5,7 @@
  * relative-time helpers live here so every picker draws the same chrome at the
  * same widths.
  */
+import { type LayoutNode } from '../core/index.js';
 import type { TextStyle } from '../core/types.js';
 export interface StyledSegment {
     text: string;
@@ -77,6 +78,38 @@ export declare function framedLine(segments: StyledSegment[], width: number, bac
 export declare function bottomBorder(width: number): StyledLine;
 /** `just now`, `12m ago`, `3h ago`, `2d ago` — coarse on purpose. */
 export declare function formatRelativeTime(isoTimestamp: string, nowMs: number): string;
+/**
+ * Build a full-page panel's styled view from its finished lines.
+ *
+ * Every full-page panel draws a framed surface and hands it to the host the
+ * same way, so the shape lives here rather than once per panel: a column of
+ * one-row boxes, offset by the surface's centring margin. Without the shared
+ * margin each panel would have to remember to re-emit it, and the one that
+ * forgot would paint at a different column from the page beside it.
+ *
+ * The margin is `marginLeft` on the frame rather than leading spaces in the
+ * text. The renderer then places the frame, and the panel's hit-test bands —
+ * which carry the same margin — describe the columns it landed on. Carrying it
+ * in both would double it.
+ */
+export declare function buildWidgetFrameView(lines: StyledLine[], inset: number): LayoutNode;
+/**
+ * The frame for a full-page panel, plus the margin it was placed at.
+ *
+ * A panel asks for the whole usable width and gets the shared cap on top, so
+ * every page draws at the same column on the same terminal; below the cap the
+ * frame keeps the full width it asked for.
+ *
+ * The frame is flush left, so the margin is zero and the spare columns sit to
+ * its right. It stays in the signature because the hit-test bands consume it.
+ *
+ * `termCols` is the terminal, not this surface: the host wraps every work
+ * surface in a `paddingX: 1` column, so `termCols - 2` is the usable width.
+ */
+export declare function widgetFrameGeometry(termCols: number): {
+    width: number;
+    inset: number;
+};
 /** Lines one wheel notch scrolls a picker pane, matching zmux's own step. */
 export declare const WHEEL_LINES = 3;
 /** Left frame cell plus its space, before the first content column. */
@@ -86,6 +119,10 @@ export declare const PANE_DIVIDER_WIDTH = 3;
 /**
  * A pane's scrollable rectangle in surface coordinates.
  *
+ * `inset` is the surface's centring margin: every band helper takes it so the
+ * hit-test columns follow the frame when a wide terminal caps it. A band left
+ * at the terminal origin would scroll a pane the pointer is not over.
+ *
  * Rows and columns count from the surface's own top-left corner, not the
  * terminal's: the host translates terminal cells into the widget's frame before
  * calling `handleMouse`, so a band recorded at paint time is directly
@@ -111,6 +148,49 @@ export interface PaneBands {
     list: PaneBand;
     preview: PaneBand;
 }
+/**
+ * Widest frame a full-page surface draws.
+ *
+ * Past roughly this many columns a two-column table stops reading as a table:
+ * the label and its value drift to opposite edges and the eye has to sweep the
+ * whole pane to pair them. 100 columns keeps a category rail, a label column,
+ * and a value column inside one glance on a normal font, and holds a preview
+ * pane beside its list without stranding either. Every full-page panel draws
+ * its frame at this width on a wider terminal.
+ */
+export declare const DEFAULT_MAX_SURFACE_WIDTH = 100;
+/**
+ * Narrowest frame a capped surface keeps.
+ *
+ * A clamp is not a floor: a terminal narrower than this still gets every column
+ * it has. The value exists so the cap and the floor are both spelled out, and so
+ * a caller can ask what the surface would have drawn at.
+ */
+export declare const MIN_CAPPED_SURFACE_WIDTH = 24;
+/**
+ * The frame width a surface should draw at, and the column it starts on.
+ *
+ * A surface may declare a cap, the widest frame its content still reads well
+ * at. Every full-page panel shares the one cap so the pickers line up: they are
+ * opened and dismissed constantly and the user is looking at one at a time, so
+ * a page drawn at a different width from its neighbour would make the frame
+ * jump sideways on every switch. The cap also keeps a two-column table
+ * readable — past it a label and its value drift to opposite edges and the eye
+ * has to sweep the whole pane to pair them.
+ *
+ * The frame is left-aligned, not centred. A centred frame on a wide terminal
+ * leaves a black band down the left of the pane, which reads as the card having
+ * been pushed off-centre; the spare columns are all spent on the right instead.
+ * `inset` stays in the return type because the hit-test bands take it — it is
+ * zero while the frame is flush left, and the bands follow the frame.
+ *
+ * Below the cap nothing is reserved: a terminal that cannot afford the margin
+ * gets every column it asked for.
+ */
+export declare function centeredSurface(availableWidth: number, maxWidth?: number): {
+    width: number;
+    inset: number;
+};
 /**
  * One band covering a panel's whole body.
  *
@@ -121,12 +201,12 @@ export interface PaneBands {
  * panel, which is the behaviour a user expects from a surface they are
  * pointing at.
  */
-export declare function bodyBand(top: number, bottom: number, innerWidth: number): PaneBand;
+export declare function bodyBand(top: number, bottom: number, innerWidth: number, inset?: number): PaneBand;
 /**
  * Both panes' bands for a side-by-side layout, where the panes share one
  * heading row and differ only in columns.
  */
-export declare function sideBySideBands(headerRow: number, lastRow: number, listWidth: number, previewWidth: number): PaneBands;
+export declare function sideBySideBands(headerRow: number, lastRow: number, listWidth: number, previewWidth: number, inset?: number): PaneBands;
 /**
  * Both panes' bands for a stacked layout.
  *
@@ -139,4 +219,4 @@ export declare function stackedBands(listRows: {
 }, previewRows: {
     top: number;
     bottom: number;
-}, innerWidth: number): PaneBands;
+}, innerWidth: number, inset?: number): PaneBands;

package/dist/ui/widgets/panel_frame.js

@@ -5,6 +5,7 @@
  * relative-time helpers live here so every picker draws the same chrome at the
  * same widths.
  */
+import { box, text } from '../core/index.js';
 import { displayWidth, sanitizeTerminalText } from '../core/text_width.js';
 import { TERMINAL_THEME } from '../views/theme.js';
 const graphemes = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
@@ -184,6 +185,52 @@ export function formatRelativeTime(isoTimestamp, nowMs) {
         return `${months}mo ago`;
     return `${Math.floor(months / 12)}y ago`;
 }
+/**
+ * Build a full-page panel's styled view from its finished lines.
+ *
+ * Every full-page panel draws a framed surface and hands it to the host the
+ * same way, so the shape lives here rather than once per panel: a column of
+ * one-row boxes, offset by the surface's centring margin. Without the shared
+ * margin each panel would have to remember to re-emit it, and the one that
+ * forgot would paint at a different column from the page beside it.
+ *
+ * The margin is `marginLeft` on the frame rather than leading spaces in the
+ * text. The renderer then places the frame, and the panel's hit-test bands —
+ * which carry the same margin — describe the columns it landed on. Carrying it
+ * in both would double it.
+ */
+export function buildWidgetFrameView(lines, inset) {
+    const frame = box(lines.map(line => box(line.segments.map(segment => text(segment.text, segment.style)), {
+        flexDirection: 'row',
+        height: 1,
+        flexShrink: 0,
+        backgroundColor: line.backgroundColor,
+    })), {
+        flexDirection: 'column',
+        height: lines.length,
+        flexShrink: 0,
+        backgroundColor: TERMINAL_THEME.bg,
+    });
+    return inset > 0
+        ? box([frame], { flexDirection: 'column', marginLeft: inset, flexShrink: 0 })
+        : frame;
+}
+/**
+ * The frame for a full-page panel, plus the margin it was placed at.
+ *
+ * A panel asks for the whole usable width and gets the shared cap on top, so
+ * every page draws at the same column on the same terminal; below the cap the
+ * frame keeps the full width it asked for.
+ *
+ * The frame is flush left, so the margin is zero and the spare columns sit to
+ * its right. It stays in the signature because the hit-test bands consume it.
+ *
+ * `termCols` is the terminal, not this surface: the host wraps every work
+ * surface in a `paddingX: 1` column, so `termCols - 2` is the usable width.
+ */
+export function widgetFrameGeometry(termCols) {
+    return centeredSurface(termCols - 2);
+}
 // ── Mouse hit-testing ────────────────────────────────────────────────────────
 /** Lines one wheel notch scrolls a picker pane, matching zmux's own step. */
 export const WHEEL_LINES = 3;
@@ -203,6 +250,56 @@ export function isInsideBand(band, x, y) {
         return false;
     return y >= band.y0 && y <= band.y1 && x >= band.x0 && x <= band.x1;
 }
+/**
+ * Widest frame a full-page surface draws.
+ *
+ * Past roughly this many columns a two-column table stops reading as a table:
+ * the label and its value drift to opposite edges and the eye has to sweep the
+ * whole pane to pair them. 100 columns keeps a category rail, a label column,
+ * and a value column inside one glance on a normal font, and holds a preview
+ * pane beside its list without stranding either. Every full-page panel draws
+ * its frame at this width on a wider terminal.
+ */
+export const DEFAULT_MAX_SURFACE_WIDTH = 100;
+/**
+ * Narrowest frame a capped surface keeps.
+ *
+ * A clamp is not a floor: a terminal narrower than this still gets every column
+ * it has. The value exists so the cap and the floor are both spelled out, and so
+ * a caller can ask what the surface would have drawn at.
+ */
+export const MIN_CAPPED_SURFACE_WIDTH = 24;
+/**
+ * The frame width a surface should draw at, and the column it starts on.
+ *
+ * A surface may declare a cap, the widest frame its content still reads well
+ * at. Every full-page panel shares the one cap so the pickers line up: they are
+ * opened and dismissed constantly and the user is looking at one at a time, so
+ * a page drawn at a different width from its neighbour would make the frame
+ * jump sideways on every switch. The cap also keeps a two-column table
+ * readable — past it a label and its value drift to opposite edges and the eye
+ * has to sweep the whole pane to pair them.
+ *
+ * The frame is left-aligned, not centred. A centred frame on a wide terminal
+ * leaves a black band down the left of the pane, which reads as the card having
+ * been pushed off-centre; the spare columns are all spent on the right instead.
+ * `inset` stays in the return type because the hit-test bands take it — it is
+ * zero while the frame is flush left, and the bands follow the frame.
+ *
+ * Below the cap nothing is reserved: a terminal that cannot afford the margin
+ * gets every column it asked for.
+ */
+export function centeredSurface(availableWidth, maxWidth = DEFAULT_MAX_SURFACE_WIDTH) {
+    const available = Math.max(1, Math.floor(availableWidth));
+    // Never wider than the room, never narrower than the floor, so a terminal
+    // that is already tighter than the floor keeps its own columns.
+    const capped = Math.min(available, Math.max(MIN_CAPPED_SURFACE_WIDTH, Math.floor(maxWidth)));
+    // Left-aligned: the frame starts at the pane's first column and the spare
+    // width sits to its right. Centring it left a black band on the left of a
+    // wide pane (and, with the host's `paddingX: 1`, one column more of it than
+    // on the right), which read as the card having been pushed off-centre.
+    return { width: capped, inset: 0 };
+}
 /**
  * One band covering a panel's whole body.
  *
@@ -213,21 +310,22 @@ export function isInsideBand(band, x, y) {
  * panel, which is the behaviour a user expects from a surface they are
  * pointing at.
  */
-export function bodyBand(top, bottom, innerWidth) {
+export function bodyBand(top, bottom, innerWidth, inset = 0) {
+    const x0 = CONTENT_INSET_X + inset;
     return {
         y0: top,
         y1: bottom,
-        x0: CONTENT_INSET_X,
-        x1: CONTENT_INSET_X + innerWidth - 1,
+        x0,
+        x1: x0 + innerWidth - 1,
     };
 }
 /**
  * Both panes' bands for a side-by-side layout, where the panes share one
  * heading row and differ only in columns.
  */
-export function sideBySideBands(headerRow, lastRow, listWidth, previewWidth) {
-    const listX0 = CONTENT_INSET_X;
-    const previewX0 = CONTENT_INSET_X + listWidth + PANE_DIVIDER_WIDTH;
+export function sideBySideBands(headerRow, lastRow, listWidth, previewWidth, inset = 0) {
+    const listX0 = CONTENT_INSET_X + inset;
+    const previewX0 = CONTENT_INSET_X + inset + listWidth + PANE_DIVIDER_WIDTH;
     return {
         list: { y0: headerRow, y1: lastRow, x0: listX0, x1: listX0 + listWidth - 1 },
         preview: { y0: headerRow, y1: lastRow, x0: previewX0, x1: previewX0 + previewWidth - 1 },
@@ -239,9 +337,9 @@ export function sideBySideBands(headerRow, lastRow, listWidth, previewWidth) {
  * Stacked, the panes share the full width and are told apart by rows, so each
  * band spans the content width and takes its own row range.
  */
-export function stackedBands(listRows, previewRows, innerWidth) {
-    const x0 = CONTENT_INSET_X;
-    const x1 = CONTENT_INSET_X + innerWidth - 1;
+export function stackedBands(listRows, previewRows, innerWidth, inset = 0) {
+    const x0 = CONTENT_INSET_X + inset;
+    const x1 = x0 + innerWidth - 1;
     return {
         list: { y0: listRows.top, y1: listRows.bottom, x0, x1 },
         preview: { y0: previewRows.top, y1: previewRows.bottom, x0, x1 },

package/dist/ui/widgets/questionnaire.d.ts

@@ -33,6 +33,8 @@ export interface QuestionnaireData {
     title?: string;
     questions: QuestionnaireQuestion[];
     allowOther?: boolean;
+    /** Show an optional prompt-style note beneath select options. Used by ask_user. */
+    allowOptionNotes?: boolean;
     callback: (answers: Record<string, string | string[]> | null) => void | Promise<void>;
 }
 export interface QuestionnaireSurface {
@@ -50,6 +52,8 @@ export declare class QuestionnaireWidget {
     private otherMode;
     private otherValue;
     private textValues;
+    private optionNotes;
+    private editingOptionNote;
     constructor(host: WidgetHost);
     /** Index of the option the agent flagged as recommended, or -1 when there is none. */
     private static recommendedOptionIndex;
@@ -57,6 +61,10 @@ export declare class QuestionnaireWidget {
     cancel(): void;
     isActive(): boolean;
     private goToQuestion;
+    private getOptionNote;
+    private setOptionNote;
+    private selectHighlightedOption;
+    private saveOptionNotes;
     private submitAnswers;
     private advanceOrSubmit;
     /**
@@ -66,6 +74,7 @@ export declare class QuestionnaireWidget {
      * key is not a delete key.
      */
     private applyDeleteKey;
+    private handleOptionNoteInput;
     handleInput(input: string, key: KeyEvent): void;
     /**
      * Styled rows for the form plus the plain-text view of those same rows.