@teammates/consolonia 0.2.0

package/dist/input/text-matcher.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Matches printable text characters — anything with char code >= 32
+ * that is not DEL (0x7f) and not ESC (0x1b).
+ *
+ * Emits a KeyEvent for each printable character.
+ */
+import { type InputEvent } from "./events.js";
+import { type IMatcher, MatchResult } from "./matcher.js";
+export declare class TextMatcher implements IMatcher {
+    private result;
+    append(char: string): MatchResult;
+    flush(): InputEvent | null;
+    reset(): void;
+}

package/dist/input/text-matcher.js

@@ -0,0 +1,32 @@
+/**
+ * Matches printable text characters — anything with char code >= 32
+ * that is not DEL (0x7f) and not ESC (0x1b).
+ *
+ * Emits a KeyEvent for each printable character.
+ */
+import { keyEvent } from "./events.js";
+import { MatchResult } from "./matcher.js";
+export class TextMatcher {
+    result = null;
+    append(char) {
+        const code = char.charCodeAt(0);
+        // Printable: code >= 32, not DEL (127), not ESC (27).
+        // Also accept high-Unicode characters (surrogate pairs, emoji, etc.)
+        if (code >= 32 && code !== 127 && code !== 27) {
+            const isUpper = code >= 65 && code <= 90;
+            const key = char === " " ? "space" : char;
+            const charValue = char;
+            this.result = keyEvent(key, charValue, isUpper, false, false);
+            return MatchResult.Complete;
+        }
+        return MatchResult.NoMatch;
+    }
+    flush() {
+        const ev = this.result;
+        this.result = null;
+        return ev;
+    }
+    reset() {
+        this.result = null;
+    }
+}

package/dist/layout/box.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Box container — a single-child wrapper with padding.
+ *
+ * The Box adds padding around its child during measure and arrange,
+ * but produces no visual output of its own.
+ */
+import type { DrawingContext } from "../drawing/context.js";
+import { Control } from "./control.js";
+import type { Constraint, Rect, Size } from "./types.js";
+export interface BoxOptions {
+    child?: Control;
+    paddingTop?: number;
+    paddingRight?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    /** Shorthand: sets all four sides when the individual values are not given. */
+    padding?: number;
+}
+export declare class Box extends Control {
+    paddingTop: number;
+    paddingRight: number;
+    paddingBottom: number;
+    paddingLeft: number;
+    constructor(options?: BoxOptions);
+    /** The single child, or null. */
+    get child(): Control | null;
+    set child(ctrl: Control | null);
+    private get hPad();
+    private get vPad();
+    measure(constraint: Constraint): Size;
+    arrange(rect: Rect): void;
+    render(ctx: DrawingContext): void;
+}

package/dist/layout/box.js

@@ -0,0 +1,92 @@
+/**
+ * Box container — a single-child wrapper with padding.
+ *
+ * The Box adds padding around its child during measure and arrange,
+ * but produces no visual output of its own.
+ */
+import { Control, clampSize } from "./control.js";
+export class Box extends Control {
+    paddingTop;
+    paddingRight;
+    paddingBottom;
+    paddingLeft;
+    constructor(options = {}) {
+        super();
+        const p = options.padding ?? 0;
+        this.paddingTop = options.paddingTop ?? p;
+        this.paddingRight = options.paddingRight ?? p;
+        this.paddingBottom = options.paddingBottom ?? p;
+        this.paddingLeft = options.paddingLeft ?? p;
+        if (options.child) {
+            this.addChild(options.child);
+        }
+    }
+    /** The single child, or null. */
+    get child() {
+        return this.children.length > 0 ? this.children[0] : null;
+    }
+    set child(ctrl) {
+        // Remove existing child
+        while (this.children.length > 0) {
+            this.removeChild(this.children[0]);
+        }
+        if (ctrl) {
+            this.addChild(ctrl);
+        }
+    }
+    // ── Horizontal / vertical padding totals ──────────────────────────
+    get hPad() {
+        return this.paddingLeft + this.paddingRight;
+    }
+    get vPad() {
+        return this.paddingTop + this.paddingBottom;
+    }
+    // ── Layout ────────────────────────────────────────────────────────
+    measure(constraint) {
+        const innerConstraint = {
+            minWidth: Math.max(0, constraint.minWidth - this.hPad),
+            minHeight: Math.max(0, constraint.minHeight - this.vPad),
+            maxWidth: Math.max(0, constraint.maxWidth - this.hPad),
+            maxHeight: Math.max(0, constraint.maxHeight - this.vPad),
+        };
+        let childSize = { width: 0, height: 0 };
+        if (this.child?.visible) {
+            childSize = this.child.measure(innerConstraint);
+        }
+        const size = clampSize({
+            width: childSize.width + this.hPad,
+            height: childSize.height + this.vPad,
+        }, constraint);
+        this.desiredSize = size;
+        return size;
+    }
+    arrange(rect) {
+        this.bounds = rect;
+        if (this.child?.visible) {
+            const innerRect = {
+                x: this.paddingLeft,
+                y: this.paddingTop,
+                width: Math.max(0, rect.width - this.hPad),
+                height: Math.max(0, rect.height - this.vPad),
+            };
+            this.child.arrange(innerRect);
+        }
+    }
+    // ── Render ────────────────────────────────────────────────────────
+    render(ctx) {
+        if (this.child?.visible) {
+            const child = this.child;
+            ctx.pushClip({
+                x: child.bounds.x,
+                y: child.bounds.y,
+                width: child.bounds.width,
+                height: child.bounds.height,
+            });
+            ctx.pushTranslate(child.bounds.x, child.bounds.y);
+            child.render(ctx);
+            child.dirty = false;
+            ctx.popTranslate();
+            ctx.popClip();
+        }
+    }
+}

package/dist/layout/column.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Column — vertical layout container.
+ *
+ * Children are laid out top to bottom. If total desired heights exceed
+ * the available height, children are proportionally scaled down.
+ */
+import type { DrawingContext } from "../drawing/context.js";
+import { Control } from "./control.js";
+import type { Constraint, Rect, Size } from "./types.js";
+export interface ColumnOptions {
+    children?: Control[];
+    /** Spacing in rows between adjacent children (default 0). */
+    gap?: number;
+}
+export declare class Column extends Control {
+    gap: number;
+    constructor(options?: ColumnOptions);
+    measure(constraint: Constraint): Size;
+    arrange(rect: Rect): void;
+    render(ctx: DrawingContext): void;
+}

package/dist/layout/column.js

@@ -0,0 +1,90 @@
+/**
+ * Column — vertical layout container.
+ *
+ * Children are laid out top to bottom. If total desired heights exceed
+ * the available height, children are proportionally scaled down.
+ */
+import { Control, clampSize } from "./control.js";
+export class Column extends Control {
+    gap;
+    constructor(options = {}) {
+        super();
+        this.gap = options.gap ?? 0;
+        if (options.children) {
+            for (const child of options.children) {
+                this.addChild(child);
+            }
+        }
+    }
+    // ── Layout ────────────────────────────────────────────────────────
+    measure(constraint) {
+        const visible = this.children.filter((c) => c.visible);
+        if (visible.length === 0) {
+            const size = clampSize({ width: 0, height: 0 }, constraint);
+            this.desiredSize = size;
+            return size;
+        }
+        const totalGap = this.gap * (visible.length - 1);
+        let maxWidth = 0;
+        let totalHeight = 0;
+        for (const child of visible) {
+            const childConstraint = {
+                minWidth: constraint.minWidth,
+                minHeight: 0,
+                maxWidth: constraint.maxWidth,
+                maxHeight: Math.max(0, constraint.maxHeight - totalGap),
+            };
+            const childSize = child.measure(childConstraint);
+            maxWidth = Math.max(maxWidth, childSize.width);
+            totalHeight += childSize.height;
+        }
+        const size = clampSize({ width: maxWidth, height: totalHeight + totalGap }, constraint);
+        this.desiredSize = size;
+        return size;
+    }
+    arrange(rect) {
+        this.bounds = rect;
+        const visible = this.children.filter((c) => c.visible);
+        if (visible.length === 0)
+            return;
+        const totalGap = this.gap * (visible.length - 1);
+        const availableHeight = Math.max(0, rect.height - totalGap);
+        const totalDesired = visible.reduce((s, c) => s + c.desiredSize.height, 0);
+        let y = 0;
+        for (let i = 0; i < visible.length; i++) {
+            const child = visible[i];
+            let childHeight;
+            if (totalDesired <= availableHeight || totalDesired === 0) {
+                childHeight = child.desiredSize.height;
+            }
+            else {
+                childHeight = Math.floor((child.desiredSize.height / totalDesired) * availableHeight);
+            }
+            child.arrange({
+                x: 0,
+                y,
+                width: rect.width,
+                height: childHeight,
+            });
+            y += childHeight + this.gap;
+        }
+    }
+    // ── Render ────────────────────────────────────────────────────────
+    render(ctx) {
+        for (const child of this.children) {
+            if (!child.visible)
+                continue;
+            ctx.pushClip({
+                x: child.bounds.x,
+                y: child.bounds.y,
+                width: child.bounds.width,
+                height: child.bounds.height,
+            });
+            ctx.pushTranslate(child.bounds.x, child.bounds.y);
+            child.render(ctx);
+            child.dirty = false;
+            ctx.popTranslate();
+            ctx.popClip();
+        }
+    }
+}

package/dist/layout/control.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Base Control class — the root of the widget tree.
+ *
+ * Every UI element extends Control. It provides:
+ *  - Parent/child tree management
+ *  - Measure/arrange layout protocol
+ *  - Abstract render() for drawing
+ *  - Input event routing with bubbling
+ *  - Focus management (tab-cycle through focusable descendants)
+ *  - Dirty tracking with upward propagation
+ *  - Lightweight inline event emitter (no Node.js dependency)
+ */
+import type { DrawingContext } from "../drawing/context.js";
+import type { InputEvent } from "../input/events.js";
+import type { Constraint, Rect, Size } from "./types.js";
+/** Clamp a measured size to the constraint bounds. */
+declare function clampSize(size: Size, c: Constraint): Size;
+/** Collect all focusable controls in depth-first order. */
+declare function collectFocusable(root: Control): Control[];
+export declare abstract class Control {
+    parent: Control | null;
+    children: Control[];
+    desiredSize: Size;
+    bounds: Rect;
+    focusable: boolean;
+    focused: boolean;
+    visible: boolean;
+    dirty: boolean;
+    private _listeners;
+    /**
+     * Measure: determine desired size given constraints.
+     * Override in subclasses. Default returns (0,0) clamped to constraints.
+     */
+    measure(constraint: Constraint): Size;
+    /**
+     * Arrange: position this control within the given rect.
+     * Override in subclasses. Default sets this.bounds = rect.
+     */
+    arrange(rect: Rect): void;
+    /**
+     * Render this control using the drawing context.
+     * The context's coordinate system is already translated so (0,0) is
+     * this control's top-left corner. Override in subclasses.
+     */
+    abstract render(ctx: DrawingContext): void;
+    /**
+     * Handle an input event. Return true if consumed.
+     *
+     * Default behaviour:
+     *  1. If this is a Tab key event, cycle focus and consume.
+     *  2. Route to the focused child (depth-first) — if it consumes, return true.
+     *  3. Otherwise return false so the event bubbles up.
+     */
+    handleInput(event: InputEvent): boolean;
+    /** Check whether any descendant of the given control has focus. */
+    private _hasFocusedDescendant;
+    /** Called when this control gains focus. */
+    onFocus(): void;
+    /** Called when this control loses focus. */
+    onBlur(): void;
+    /** Move focus to the next focusable control in depth-first order. */
+    focusNext(): void;
+    /** Move focus to the previous focusable control in depth-first order. */
+    focusPrev(): void;
+    addChild(child: Control): void;
+    removeChild(child: Control): void;
+    /** Mark this control as needing re-render. Propagates up to the root. */
+    invalidate(): void;
+    on(event: string, handler: (...args: any[]) => void): void;
+    off(event: string, handler: (...args: any[]) => void): void;
+    emit(event: string, ...args: any[]): void;
+}
+export { clampSize, collectFocusable };

package/dist/layout/control.js

@@ -0,0 +1,215 @@
+/**
+ * Base Control class — the root of the widget tree.
+ *
+ * Every UI element extends Control. It provides:
+ *  - Parent/child tree management
+ *  - Measure/arrange layout protocol
+ *  - Abstract render() for drawing
+ *  - Input event routing with bubbling
+ *  - Focus management (tab-cycle through focusable descendants)
+ *  - Dirty tracking with upward propagation
+ *  - Lightweight inline event emitter (no Node.js dependency)
+ */
+// ── Helpers ─────────────────────────────────────────────────────────
+/** Clamp a measured size to the constraint bounds. */
+function clampSize(size, c) {
+    return {
+        width: Math.max(c.minWidth, Math.min(size.width, c.maxWidth)),
+        height: Math.max(c.minHeight, Math.min(size.height, c.maxHeight)),
+    };
+}
+/** Collect all focusable controls in depth-first order. */
+function collectFocusable(root) {
+    const result = [];
+    const walk = (ctrl) => {
+        if (!ctrl.visible)
+            return;
+        if (ctrl.focusable)
+            result.push(ctrl);
+        for (const child of ctrl.children) {
+            walk(child);
+        }
+    };
+    walk(root);
+    return result;
+}
+/** Walk up to the root of the tree. */
+function root(ctrl) {
+    let c = ctrl;
+    while (c.parent)
+        c = c.parent;
+    return c;
+}
+// ── Control ─────────────────────────────────────────────────────────
+export class Control {
+    // --- Tree ---
+    parent = null;
+    children = [];
+    // --- Layout state ---
+    desiredSize = { width: 0, height: 0 };
+    bounds = { x: 0, y: 0, width: 0, height: 0 };
+    // --- Focus ---
+    focusable = false;
+    focused = false;
+    // --- Visibility ---
+    visible = true;
+    // --- Dirty tracking ---
+    dirty = true;
+    // --- Event emitter storage ---
+    _listeners = new Map();
+    // ── Layout lifecycle ──────────────────────────────────────────────
+    /**
+     * Measure: determine desired size given constraints.
+     * Override in subclasses. Default returns (0,0) clamped to constraints.
+     */
+    measure(constraint) {
+        const size = clampSize({ width: 0, height: 0 }, constraint);
+        this.desiredSize = size;
+        return size;
+    }
+    /**
+     * Arrange: position this control within the given rect.
+     * Override in subclasses. Default sets this.bounds = rect.
+     */
+    arrange(rect) {
+        this.bounds = rect;
+    }
+    // ── Event handling ────────────────────────────────────────────────
+    /**
+     * Handle an input event. Return true if consumed.
+     *
+     * Default behaviour:
+     *  1. If this is a Tab key event, cycle focus and consume.
+     *  2. Route to the focused child (depth-first) — if it consumes, return true.
+     *  3. Otherwise return false so the event bubbles up.
+     */
+    handleInput(event) {
+        // Tab focus cycling at root or any level
+        if (event.type === "key") {
+            const ke = event.event;
+            if (ke.key === "tab" || ke.key === "Tab") {
+                if (ke.shift) {
+                    this.focusPrev();
+                }
+                else {
+                    this.focusNext();
+                }
+                return true;
+            }
+        }
+        // Route to focused child
+        for (const child of this.children) {
+            if (!child.visible)
+                continue;
+            if (child.focused || this._hasFocusedDescendant(child)) {
+                if (child.handleInput(event))
+                    return true;
+            }
+        }
+        return false;
+    }
+    /** Check whether any descendant of the given control has focus. */
+    _hasFocusedDescendant(ctrl) {
+        for (const child of ctrl.children) {
+            if (child.focused)
+                return true;
+            if (this._hasFocusedDescendant(child))
+                return true;
+        }
+        return false;
+    }
+    /** Called when this control gains focus. */
+    onFocus() {
+        this.focused = true;
+        this.invalidate();
+        this.emit("focus");
+    }
+    /** Called when this control loses focus. */
+    onBlur() {
+        this.focused = false;
+        this.invalidate();
+        this.emit("blur");
+    }
+    // ── Focus management ──────────────────────────────────────────────
+    /** Move focus to the next focusable control in depth-first order. */
+    focusNext() {
+        const r = root(this);
+        const list = collectFocusable(r);
+        if (list.length === 0)
+            return;
+        const currentIndex = list.findIndex((c) => c.focused);
+        // Blur current
+        if (currentIndex >= 0)
+            list[currentIndex].onBlur();
+        const nextIndex = currentIndex < 0 ? 0 : (currentIndex + 1) % list.length;
+        list[nextIndex].onFocus();
+    }
+    /** Move focus to the previous focusable control in depth-first order. */
+    focusPrev() {
+        const r = root(this);
+        const list = collectFocusable(r);
+        if (list.length === 0)
+            return;
+        const currentIndex = list.findIndex((c) => c.focused);
+        if (currentIndex >= 0)
+            list[currentIndex].onBlur();
+        const prevIndex = currentIndex <= 0 ? list.length - 1 : currentIndex - 1;
+        list[prevIndex].onFocus();
+    }
+    // ── Children management ───────────────────────────────────────────
+    addChild(child) {
+        if (child.parent) {
+            child.parent.removeChild(child);
+        }
+        child.parent = this;
+        this.children.push(child);
+        this.invalidate();
+    }
+    removeChild(child) {
+        const idx = this.children.indexOf(child);
+        if (idx >= 0) {
+            this.children.splice(idx, 1);
+            child.parent = null;
+            this.invalidate();
+        }
+    }
+    // ── Dirty tracking ───────────────────────────────────────────────
+    /** Mark this control as needing re-render. Propagates up to the root. */
+    invalidate() {
+        if (this.dirty)
+            return; // already dirty, no need to propagate again
+        this.dirty = true;
+        if (this.parent) {
+            this.parent.invalidate();
+        }
+    }
+    // ── Inline event emitter ──────────────────────────────────────────
+    on(event, handler) {
+        let handlers = this._listeners.get(event);
+        if (!handlers) {
+            handlers = [];
+            this._listeners.set(event, handlers);
+        }
+        handlers.push(handler);
+    }
+    off(event, handler) {
+        const handlers = this._listeners.get(event);
+        if (!handlers)
+            return;
+        const idx = handlers.indexOf(handler);
+        if (idx >= 0)
+            handlers.splice(idx, 1);
+        if (handlers.length === 0)
+            this._listeners.delete(event);
+    }
+    emit(event, ...args) {
+        const handlers = this._listeners.get(event);
+        if (!handlers)
+            return;
+        // Iterate over a copy so handlers can safely remove themselves
+        for (const h of [...handlers]) {
+            h(...args);
+        }
+    }
+}
+export { clampSize, collectFocusable };

package/dist/layout/row.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Row — horizontal layout container.
+ *
+ * Children are laid out left to right. If total desired widths exceed
+ * the available width, children are proportionally scaled down.
+ */
+import type { DrawingContext } from "../drawing/context.js";
+import { Control } from "./control.js";
+import type { Constraint, Rect, Size } from "./types.js";
+export interface RowOptions {
+    children?: Control[];
+    /** Spacing in columns between adjacent children (default 0). */
+    gap?: number;
+}
+export declare class Row extends Control {
+    gap: number;
+    constructor(options?: RowOptions);
+    measure(constraint: Constraint): Size;
+    arrange(rect: Rect): void;
+    render(ctx: DrawingContext): void;
+}

package/dist/layout/row.js

@@ -0,0 +1,95 @@
+/**
+ * Row — horizontal layout container.
+ *
+ * Children are laid out left to right. If total desired widths exceed
+ * the available width, children are proportionally scaled down.
+ */
+import { Control, clampSize } from "./control.js";
+export class Row extends Control {
+    gap;
+    constructor(options = {}) {
+        super();
+        this.gap = options.gap ?? 0;
+        if (options.children) {
+            for (const child of options.children) {
+                this.addChild(child);
+            }
+        }
+    }
+    // ── Layout ────────────────────────────────────────────────────────
+    measure(constraint) {
+        const visible = this.children.filter((c) => c.visible);
+        if (visible.length === 0) {
+            const size = clampSize({ width: 0, height: 0 }, constraint);
+            this.desiredSize = size;
+            return size;
+        }
+        const totalGap = this.gap * (visible.length - 1);
+        let totalWidth = 0;
+        let maxHeight = 0;
+        for (const child of visible) {
+            // Each child is measured with the full available height but
+            // unconstrained width (up to remaining space).
+            const childConstraint = {
+                minWidth: 0,
+                minHeight: constraint.minHeight,
+                maxWidth: Math.max(0, constraint.maxWidth - totalGap),
+                maxHeight: constraint.maxHeight,
+            };
+            const childSize = child.measure(childConstraint);
+            totalWidth += childSize.width;
+            maxHeight = Math.max(maxHeight, childSize.height);
+        }
+        const size = clampSize({ width: totalWidth + totalGap, height: maxHeight }, constraint);
+        this.desiredSize = size;
+        return size;
+    }
+    arrange(rect) {
+        this.bounds = rect;
+        const visible = this.children.filter((c) => c.visible);
+        if (visible.length === 0)
+            return;
+        const totalGap = this.gap * (visible.length - 1);
+        const availableWidth = Math.max(0, rect.width - totalGap);
+        // Sum of children's desired widths
+        const totalDesired = visible.reduce((s, c) => s + c.desiredSize.width, 0);
+        let x = 0;
+        for (let i = 0; i < visible.length; i++) {
+            const child = visible[i];
+            let childWidth;
+            if (totalDesired <= availableWidth || totalDesired === 0) {
+                // Enough space — give each child its desired width
+                childWidth = child.desiredSize.width;
+            }
+            else {
+                // Proportionally scale down
+                childWidth = Math.floor((child.desiredSize.width / totalDesired) * availableWidth);
+            }
+            child.arrange({
+                x,
+                y: 0,
+                width: childWidth,
+                height: rect.height,
+            });
+            x += childWidth + this.gap;
+        }
+    }
+    // ── Render ────────────────────────────────────────────────────────
+    render(ctx) {
+        for (const child of this.children) {
+            if (!child.visible)
+                continue;
+            ctx.pushClip({
+                x: child.bounds.x,
+                y: child.bounds.y,
+                width: child.bounds.width,
+                height: child.bounds.height,
+            });
+            ctx.pushTranslate(child.bounds.x, child.bounds.y);
+            child.render(ctx);
+            child.dirty = false;
+            ctx.popTranslate();
+            ctx.popClip();
+        }
+    }
+}