@teammates/consolonia 0.2.0

package/dist/styled.js

@@ -0,0 +1,176 @@
+/**
+ * Styled — a chalk-like fluent API for building styled text segments.
+ *
+ * Instead of producing ANSI escape codes (which only work on raw stdout),
+ * Styled produces {text, style} segment arrays that can be rendered into
+ * a pixel buffer via DrawingContext.
+ *
+ * Usage:
+ *   import { pen } from "@teammates/consolonia";
+ *
+ *   // Single styled segment
+ *   pen.cyan("hello")            → [{ text: "hello", style: { fg: CYAN } }]
+ *
+ *   // Chained styles
+ *   pen.bold.red("error")        → [{ text: "error", style: { fg: RED, bold: true } }]
+ *
+ *   // Concatenation with +
+ *   pen.green("✔ ") + pen.white("done")
+ *     → [{ text: "✔ ", style: { fg: GREEN } }, { text: "done", style: { fg: WHITE } }]
+ *
+ *   // Mixed plain + styled
+ *   pen("prefix ") + pen.cyan("@name")
+ *     → [{ text: "prefix ", style: {} }, { text: "@name", style: { fg: CYAN } }]
+ *
+ *   // Gray is dim white (like chalk.gray)
+ *   pen.gray("muted")           → [{ text: "muted", style: { fg: GRAY } }]
+ */
+import { BLACK, BLACK_BRIGHT, BLUE, BLUE_BRIGHT, CYAN, CYAN_BRIGHT, DARK_GRAY, GRAY, GREEN, GREEN_BRIGHT, LIGHT_GRAY, MAGENTA, MAGENTA_BRIGHT, RED, RED_BRIGHT, WHITE, WHITE_BRIGHT, YELLOW, YELLOW_BRIGHT, } from "./pixel/color.js";
+import { charWidth } from "./pixel/symbol.js";
+/** Create a StyledSpan from segments. */
+function span(segments) {
+    const arr = segments;
+    arr.__brand = "StyledSpan";
+    return arr;
+}
+/** Check if a value is a StyledSpan. */
+export function isStyledSpan(v) {
+    return Array.isArray(v) && v.__brand === "StyledSpan";
+}
+/** Concatenate styled spans and/or plain strings. */
+export function concat(...parts) {
+    const segments = [];
+    for (const part of parts) {
+        if (typeof part === "string") {
+            segments.push({ text: part, style: {} });
+        }
+        else {
+            segments.push(...part);
+        }
+    }
+    return span(segments);
+}
+/** Get the visible (unstyled) text from a StyledSpan. */
+export function spanText(s) {
+    return s.map((seg) => seg.text).join("");
+}
+/** Get the visible display width of a StyledSpan (accounts for wide characters). */
+export function spanLength(s) {
+    let width = 0;
+    for (const seg of s) {
+        for (const ch of seg.text) {
+            width += charWidth(ch.codePointAt(0));
+        }
+    }
+    return width;
+}
+// ── Named colors ─────────────────────────────────────────────────
+//
+// Maps match chalk's naming conventions exactly.
+const FG_COLORS = {
+    // Standard (chalk: black, red, green, yellow, blue, magenta, cyan, white)
+    black: BLACK,
+    red: RED,
+    green: GREEN,
+    yellow: YELLOW,
+    blue: BLUE,
+    magenta: MAGENTA,
+    cyan: CYAN,
+    white: WHITE,
+    // Bright (chalk: blackBright … whiteBright)
+    blackBright: BLACK_BRIGHT,
+    redBright: RED_BRIGHT,
+    greenBright: GREEN_BRIGHT,
+    yellowBright: YELLOW_BRIGHT,
+    blueBright: BLUE_BRIGHT,
+    magentaBright: MAGENTA_BRIGHT,
+    cyanBright: CYAN_BRIGHT,
+    whiteBright: WHITE_BRIGHT,
+    // Aliases (chalk: gray = grey = blackBright)
+    gray: GRAY,
+    grey: GRAY,
+    // Extra consolonia aliases
+    darkGray: DARK_GRAY,
+    lightGray: LIGHT_GRAY,
+};
+const BG_COLORS = {
+    // Standard
+    bgBlack: BLACK,
+    bgRed: RED,
+    bgGreen: GREEN,
+    bgYellow: YELLOW,
+    bgBlue: BLUE,
+    bgMagenta: MAGENTA,
+    bgCyan: CYAN,
+    bgWhite: WHITE,
+    // Bright
+    bgBlackBright: BLACK_BRIGHT,
+    bgRedBright: RED_BRIGHT,
+    bgGreenBright: GREEN_BRIGHT,
+    bgYellowBright: YELLOW_BRIGHT,
+    bgBlueBright: BLUE_BRIGHT,
+    bgMagentaBright: MAGENTA_BRIGHT,
+    bgCyanBright: CYAN_BRIGHT,
+    bgWhiteBright: WHITE_BRIGHT,
+    // Aliases (chalk: bgGray = bgGrey = bgBlackBright)
+    bgGray: BLACK_BRIGHT,
+    bgGrey: BLACK_BRIGHT,
+};
+// Style flag names
+const STYLE_FLAGS = {
+    bold: "bold",
+    italic: "italic",
+    underline: "underline",
+    strikethrough: "strikethrough",
+    dim: "bold", // dim maps to non-bold (handled specially)
+};
+function createPen(accumulated) {
+    const callable = (text) => {
+        return span([{ text, style: { ...accumulated } }]);
+    };
+    return new Proxy(callable, {
+        get(_target, prop) {
+            // Arbitrary foreground: pen.fg(color)
+            if (prop === "fg") {
+                return (c) => createPen({ ...accumulated, fg: c });
+            }
+            // Arbitrary background: pen.bg(color)
+            if (prop === "bg") {
+                return (c) => createPen({ ...accumulated, bg: c });
+            }
+            // Named foreground colors
+            if (prop in FG_COLORS) {
+                return createPen({ ...accumulated, fg: FG_COLORS[prop] });
+            }
+            // Named background colors
+            if (prop in BG_COLORS) {
+                return createPen({ ...accumulated, bg: BG_COLORS[prop] });
+            }
+            // Style flags
+            if (prop in STYLE_FLAGS) {
+                if (prop === "dim") {
+                    // dim is represented as gray foreground if no fg set
+                    return createPen({
+                        ...accumulated,
+                        fg: accumulated.fg ?? GRAY,
+                    });
+                }
+                return createPen({
+                    ...accumulated,
+                    [STYLE_FLAGS[prop]]: true,
+                });
+            }
+            return undefined;
+        },
+    });
+}
+/**
+ * The default pen — starting point for building styled text.
+ *
+ * Usage:
+ *   pen("plain text")
+ *   pen.cyan("colored")
+ *   pen.bold.red("bold red")
+ *   pen.bgBlue.white("white on blue")
+ */
+export const pen = createPen({});

package/dist/widgets/border.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Box-drawing border around a single child control.
+ *
+ * Draws a Unicode box-drawing rectangle (via DrawingContext.drawBox)
+ * and optionally renders a title string embedded in the top border
+ * in the form: ┤ Title ├
+ */
+import type { BoxStyle, DrawingContext, TextStyle } from "../drawing/context.js";
+import { Control } from "../layout/control.js";
+import type { Constraint, Rect, Size } from "../layout/types.js";
+export interface BorderOptions {
+    child?: Control;
+    title?: string;
+    style?: BoxStyle;
+    titleStyle?: TextStyle;
+}
+export declare class Border extends Control {
+    private _child;
+    private _title;
+    private _style;
+    private _titleStyle;
+    constructor(options?: BorderOptions);
+    get child(): Control | null;
+    set child(value: Control | null);
+    get title(): string;
+    set title(value: string);
+    get style(): BoxStyle;
+    set style(value: BoxStyle);
+    get titleStyle(): TextStyle;
+    set titleStyle(value: TextStyle);
+    measure(constraint: Constraint): Size;
+    arrange(rect: Rect): void;
+    render(ctx: DrawingContext): void;
+}

package/dist/widgets/border.js

@@ -0,0 +1,121 @@
+/**
+ * Box-drawing border around a single child control.
+ *
+ * Draws a Unicode box-drawing rectangle (via DrawingContext.drawBox)
+ * and optionally renders a title string embedded in the top border
+ * in the form: ┤ Title ├
+ */
+import { Control } from "../layout/control.js";
+export class Border extends Control {
+    _child;
+    _title;
+    _style;
+    _titleStyle;
+    constructor(options = {}) {
+        super();
+        this._child = options.child ?? null;
+        this._title = options.title ?? "";
+        this._style = options.style ?? {};
+        this._titleStyle = options.titleStyle ?? {};
+        if (this._child) {
+            this.children.push(this._child);
+        }
+    }
+    // ── Properties ────────────────────────────────────────────────
+    get child() {
+        return this._child;
+    }
+    set child(value) {
+        // Remove old child
+        if (this._child) {
+            const idx = this.children.indexOf(this._child);
+            if (idx >= 0)
+                this.children.splice(idx, 1);
+        }
+        this._child = value;
+        if (value) {
+            this.children.push(value);
+        }
+        this.invalidate();
+    }
+    get title() {
+        return this._title;
+    }
+    set title(value) {
+        if (this._title !== value) {
+            this._title = value;
+            this.invalidate();
+        }
+    }
+    get style() {
+        return this._style;
+    }
+    set style(value) {
+        this._style = value;
+        this.invalidate();
+    }
+    get titleStyle() {
+        return this._titleStyle;
+    }
+    set titleStyle(value) {
+        this._titleStyle = value;
+        this.invalidate();
+    }
+    // ── Layout ────────────────────────────────────────────────────
+    measure(constraint) {
+        // Border takes 1 cell on each side (2 total per axis)
+        const _innerConstraint = {
+            minWidth: Math.max(0, constraint.minWidth - 2),
+            minHeight: Math.max(0, constraint.minHeight - 2),
+            maxWidth: Math.max(0, constraint.maxWidth - 2),
+            maxHeight: Math.max(0, constraint.maxHeight - 2),
+        };
+        if (this._child) {
+            // Trigger child measure through its public API
+            const childSize = this._child.desiredSize ?? { width: 0, height: 0 };
+            // We need to invoke the child's layout — in a typical layout system
+            // the parent is responsible for measuring children. We'll call the
+            // child's measure indirectly by having the layout system handle it.
+            // For now, return border + child desired.
+            return {
+                width: (childSize.width ?? 0) + 2,
+                height: (childSize.height ?? 0) + 2,
+            };
+        }
+        // No child: just the border itself (minimum 2x2 for corners)
+        return { width: 2, height: 2 };
+    }
+    arrange(rect) {
+        if (this._child) {
+            this._child.arrange({
+                x: rect.x + 1,
+                y: rect.y + 1,
+                width: Math.max(0, rect.width - 2),
+                height: Math.max(0, rect.height - 2),
+            });
+        }
+    }
+    render(ctx) {
+        const bounds = this.bounds;
+        if (!bounds || bounds.width < 2 || bounds.height < 2)
+            return;
+        // Draw the box border
+        ctx.drawBox(bounds, this._style);
+        // Draw title in the top border if present
+        if (this._title.length > 0) {
+            const maxTitleLen = bounds.width - 4; // room for ┤ and ├ plus spaces
+            if (maxTitleLen > 0) {
+                const displayTitle = this._title.length > maxTitleLen
+                    ? this._title.slice(0, maxTitleLen)
+                    : this._title;
+                // Draw "┤ Title ├" starting 2 cells from the left edge of top border
+                const startX = bounds.x + 2;
+                ctx.drawText(startX, bounds.y, `\u2524 ${displayTitle} \u251C`, this._titleStyle);
+            }
+        }
+        // Render child
+        if (this._child) {
+            this._child.render(ctx);
+        }
+    }
+}

package/dist/widgets/chat-view.d.ts

@@ -0,0 +1,239 @@
+/**
+ * ChatView — full-screen chat widget for terminal REPLs.
+ *
+ * Layout (top to bottom):
+ *
+ *   ┌─ banner ──────────────────────────────┐
+ *   │  customizable multi-line header text   │
+ *   ├───────────────────────────────────────-┤
+ *   │                                        │
+ *   │  scrollable feed area                  │
+ *   │  (messages, agent output, etc.)        │
+ *   │                                        │
+ *   ├───────────────────────────────────────-┤
+ *   │  progress message (optional)           │
+ *   │  ❯ input box                           │
+ *   │  ┌─ dropdown ───────────────────────┐  │
+ *   │  │  /command1   description          │  │
+ *   │  │  /command2   description          │  │
+ *   │  └──────────────────────────────────-┘  │
+ *   └────────────────────────────────────────┘
+ *
+ * The feed is the terminal's own scrollback: new content is appended
+ * as Text children to the feed Column. Everything is double-buffered
+ * through Consolonia's PixelBuffer so resizing redraws cleanly.
+ *
+ * Events emitted:
+ *   "submit"  (text: string)         — user pressed Enter
+ *   "change"  (text: string)         — input value changed
+ *   "cancel"  ()                     — user pressed Escape
+ *   "tab"     ()                     — user pressed Tab (for autocomplete)
+ */
+import type { DrawingContext, TextStyle } from "../drawing/context.js";
+import type { InputEvent } from "../input/events.js";
+import { Control } from "../layout/control.js";
+import type { Constraint, Rect, Size } from "../layout/types.js";
+import type { StyledSpan } from "../styled.js";
+import { type StyledLine } from "./styled-text.js";
+import { type DeleteSizer, type InputColorizer, TextInput } from "./text-input.js";
+export interface DropdownItem {
+    /** Display label (left column). */
+    label: string;
+    /** Description (right column). */
+    description: string;
+    /** Full text to insert on accept. */
+    completion: string;
+}
+/** A single action item within an action line. */
+export interface FeedActionItem {
+    id: string;
+    normalStyle: StyledLine;
+    hoverStyle: StyledLine;
+}
+export interface ChatViewOptions {
+    /** Banner text shown at the top of the chat area. */
+    banner?: string;
+    /** Style for the banner text. */
+    bannerStyle?: TextStyle;
+    /** Custom widget to use as the banner instead of the built-in Text. */
+    bannerWidget?: Control;
+    /** Prompt string for the input box (default "❯ "). */
+    prompt?: string;
+    /** Style for the prompt. */
+    promptStyle?: TextStyle;
+    /** Style for input text. */
+    inputStyle?: TextStyle;
+    /** Style for the cursor. */
+    cursorStyle?: TextStyle;
+    /** Per-character colorizer for input text. */
+    inputColorize?: InputColorizer;
+    /** Callback to determine delete size for backspace/delete in input. */
+    inputDeleteSize?: DeleteSizer;
+    /** Hint callback — returns dim text shown after the cursor (e.g. param placeholders). */
+    inputHint?: (value: string) => string | null;
+    /** Style for input hint text (default: dim). */
+    inputHintStyle?: TextStyle;
+    /** Placeholder when input is empty. */
+    placeholder?: string;
+    /** Style for placeholder text. */
+    placeholderStyle?: TextStyle;
+    /** Style for feed text (default messages). */
+    feedStyle?: TextStyle;
+    /** Style for progress message text. */
+    progressStyle?: TextStyle;
+    /** Style for the separator lines between banner/feed/input. */
+    separatorStyle?: TextStyle;
+    /** Character used for separator lines (default "─"). */
+    separatorChar?: string;
+    /** Style for highlighted dropdown item. */
+    dropdownHighlightStyle?: TextStyle;
+    /** Style for normal dropdown item description. */
+    dropdownStyle?: TextStyle;
+    /** Style for non-highlighted dropdown item label (/command, @name). */
+    dropdownLabelStyle?: TextStyle;
+    /** Maximum number of lines the input box can grow to (default 1). */
+    maxInputHeight?: number;
+    /** Footer content shown below the input (StyledLine for mixed colors). */
+    footer?: StyledLine;
+    /** Style for footer text (used as default when footer is a plain string). */
+    footerStyle?: TextStyle;
+    /** Command history entries. */
+    history?: string[];
+}
+export declare class ChatView extends Control {
+    private _banner;
+    private _topSeparator;
+    private _feedLines;
+    /** Maps feed line index → action(s) for clickable lines. */
+    private _feedActions;
+    /** Feed line index currently hovered (-1 if none). */
+    private _hoveredAction;
+    /** Maps screen Y → feed line index (rebuilt each render). */
+    private _screenToFeedLine;
+    /** Maps screen Y → row offset within the feed line (for multi-row wrapped lines). */
+    private _screenToFeedRow;
+    private _bottomSeparator;
+    private _progressText;
+    private _input;
+    private _inputSeparator;
+    private _footer;
+    private _dropdownItems;
+    private _dropdownIndex;
+    private _feedStyle;
+    private _progressStyle;
+    private _separatorStyle;
+    private _separatorChar;
+    private _dropdownHighlightStyle;
+    private _dropdownStyle;
+    private _footerStyle;
+    private _maxInputH;
+    private _feedScrollOffset;
+    private _feedX;
+    private _contentWidth;
+    /** Cached from last render for hit-testing. */
+    private _scrollbarX;
+    private _feedY;
+    private _feedH;
+    private _thumbPos;
+    private _thumbSize;
+    private _maxScroll;
+    private _scrollbarVisible;
+    /** True while the user is dragging the scrollbar thumb. */
+    private _dragging;
+    /** The Y offset within the thumb where the drag started. */
+    private _dragOffsetY;
+    /** Optional widget that replaces the input area (e.g. Interview). */
+    private _inputOverride;
+    constructor(options?: ChatViewOptions);
+    /** Get the banner text (only works when using the built-in Text banner). */
+    get banner(): string;
+    /** Set the banner text (only works when using the built-in Text banner). */
+    set banner(text: string);
+    /** Get the banner style (only works when using the built-in Text banner). */
+    get bannerStyle(): TextStyle;
+    /** Set the banner style (only works when using the built-in Text banner). */
+    set bannerStyle(style: TextStyle);
+    /** Replace the banner with a custom widget. */
+    set bannerWidget(widget: Control);
+    /** Get the current banner widget. */
+    get bannerWidget(): Control;
+    /** Set footer content (plain string or StyledSpan for mixed colors). */
+    setFooter(content: StyledLine): void;
+    /** Append a line of plain text to the feed. Auto-scrolls to bottom. */
+    appendToFeed(text: string, style?: TextStyle): void;
+    /** Append a styled line (StyledSpan) to the feed. */
+    appendStyledToFeed(styledLine: StyledSpan): void;
+    /** Append a clickable action line to the feed. Emits "action" on click. */
+    appendAction(id: string, normalContent: StyledLine, hoverContent: StyledLine): void;
+    /** Append a line with multiple side-by-side clickable actions. */
+    appendActionList(actions: FeedActionItem[]): void;
+    /** Concatenate multiple StyledLine arrays into one. */
+    private _concatSpans;
+    /** Append multiple plain lines to the feed. */
+    appendLines(lines: string[], style?: TextStyle): void;
+    /** Clear everything between the banner and the input box. */
+    clear(): void;
+    /** Total number of feed lines. */
+    get feedLineCount(): number;
+    /** Update the content of an existing feed line by index. Also removes its action if any. */
+    updateFeedLine(index: number, content: StyledLine): void;
+    /** Scroll the feed to the bottom. */
+    scrollToBottom(): void;
+    /** Scroll the feed by a delta (positive = down, negative = up). */
+    scrollFeed(delta: number): void;
+    /** Get current input value. */
+    get inputValue(): string;
+    /** Set the input value and move cursor to end. */
+    set inputValue(text: string);
+    /** Get the underlying TextInput for advanced use. */
+    get input(): TextInput;
+    /** Get input history. */
+    get history(): string[];
+    /** Set the input prompt text. */
+    set prompt(text: string);
+    get prompt(): string;
+    /** Show a progress/status message just above the separator. */
+    setProgress(content: StyledLine | null): void;
+    /** Show dropdown items below the input box. */
+    showDropdown(items: DropdownItem[]): void;
+    /** Hide the dropdown. */
+    hideDropdown(): void;
+    /** Move dropdown selection down. */
+    dropdownDown(): boolean;
+    /** Move dropdown selection up. */
+    dropdownUp(): boolean;
+    /** Accept the currently highlighted dropdown item. Returns it, or null. */
+    acceptDropdownItem(): DropdownItem | null;
+    /** Get current dropdown items. */
+    get dropdownItems(): DropdownItem[];
+    /** Get current dropdown selection index. */
+    get dropdownIndex(): number;
+    /**
+     * Replace the normal input/footer area with a custom widget
+     * (e.g. an Interview). While an override is active the normal
+     * input, separator, footer and dropdown are hidden and input
+     * events are routed to the override widget.
+     *
+     * Pass `null` to remove the override and restore normal input.
+     */
+    setInputOverride(widget: Control | null): void;
+    /** Get the current input override widget, or null. */
+    get inputOverride(): Control | null;
+    handleInput(event: InputEvent): boolean;
+    /** Extract the plain text content of a feed line. */
+    private _extractFeedLineText;
+    /** Find the URL at the given character offset, if any. */
+    private _findUrlAtOffset;
+    /** Resolve which action item the mouse x-position falls on. */
+    private _resolveActionItem;
+    /** Build a hover line: highlight only the target item, keep others normal. */
+    private _buildHoverLine;
+    /** Get the plain text length of a StyledLine. */
+    private _spanTextLength;
+    measure(constraint: Constraint): Size;
+    arrange(rect: Rect): void;
+    render(ctx: DrawingContext): void;
+    private _renderFeed;
+    private _renderDropdown;
+    private _autoScrollToBottom;
+}