@teammates/consolonia 0.2.0

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

@@ -0,0 +1,43 @@
+/**
+ * Vertical scrollable container.
+ *
+ * Wraps a single child control and clips rendering to a visible
+ * window. Supports mouse wheel scrolling and arrow-key scrolling
+ * when the child does not consume the events.
+ */
+import type { DrawingContext } 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";
+export interface ScrollViewOptions {
+    child?: Control;
+    maxHeight?: number;
+}
+export declare class ScrollView extends Control {
+    private _child;
+    private _scrollOffset;
+    private _maxHeight;
+    /** The child's full measured height (updated after measure). */
+    private _contentHeight;
+    constructor(options?: ScrollViewOptions);
+    get child(): Control | null;
+    set child(value: Control | null);
+    get scrollOffset(): number;
+    set scrollOffset(value: number);
+    get maxHeight(): number;
+    set maxHeight(value: number);
+    /** Total height of the child content. */
+    get contentHeight(): number;
+    /** Currently visible line range (0-based, inclusive top, exclusive bottom). */
+    get visibleRange(): {
+        top: number;
+        bottom: number;
+    };
+    /** Scroll so that the given y position (in child coordinates) is visible. */
+    scrollTo(y: number): void;
+    measure(constraint: Constraint): Size;
+    arrange(rect: Rect): void;
+    render(ctx: DrawingContext): void;
+    handleInput(event: InputEvent): boolean;
+    private _clampOffset;
+}

package/dist/widgets/scroll-view.js

@@ -0,0 +1,182 @@
+/**
+ * Vertical scrollable container.
+ *
+ * Wraps a single child control and clips rendering to a visible
+ * window. Supports mouse wheel scrolling and arrow-key scrolling
+ * when the child does not consume the events.
+ */
+import { Control } from "../layout/control.js";
+export class ScrollView extends Control {
+    _child;
+    _scrollOffset = 0;
+    _maxHeight;
+    /** The child's full measured height (updated after measure). */
+    _contentHeight = 0;
+    constructor(options = {}) {
+        super();
+        this._child = options.child ?? null;
+        this._maxHeight = options.maxHeight ?? Infinity;
+        if (this._child) {
+            this.children.push(this._child);
+        }
+    }
+    // ── Properties ────────────────────────────────────────────────
+    get child() {
+        return this._child;
+    }
+    set child(value) {
+        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._scrollOffset = 0;
+        this.invalidate();
+    }
+    get scrollOffset() {
+        return this._scrollOffset;
+    }
+    set scrollOffset(value) {
+        const clamped = this._clampOffset(value);
+        if (this._scrollOffset !== clamped) {
+            this._scrollOffset = clamped;
+            this.invalidate();
+        }
+    }
+    get maxHeight() {
+        return this._maxHeight;
+    }
+    set maxHeight(value) {
+        if (this._maxHeight !== value) {
+            this._maxHeight = value;
+            this.invalidate();
+        }
+    }
+    /** Total height of the child content. */
+    get contentHeight() {
+        return this._contentHeight;
+    }
+    /** Currently visible line range (0-based, inclusive top, exclusive bottom). */
+    get visibleRange() {
+        const bounds = this.bounds;
+        const visibleH = bounds ? bounds.height : 0;
+        return {
+            top: this._scrollOffset,
+            bottom: this._scrollOffset + visibleH,
+        };
+    }
+    // ── Public methods ────────────────────────────────────────────
+    /** Scroll so that the given y position (in child coordinates) is visible. */
+    scrollTo(y) {
+        const bounds = this.bounds;
+        const visibleH = bounds ? bounds.height : 0;
+        if (y < this._scrollOffset) {
+            this.scrollOffset = y;
+        }
+        else if (y >= this._scrollOffset + visibleH) {
+            this.scrollOffset = y - visibleH + 1;
+        }
+    }
+    // ── Layout ────────────────────────────────────────────────────
+    measure(constraint) {
+        if (!this._child) {
+            this._contentHeight = 0;
+            return { width: 0, height: 0 };
+        }
+        // Let the child measure with unconstrained height
+        const _childConstraint = {
+            minWidth: constraint.minWidth,
+            minHeight: 0,
+            maxWidth: constraint.maxWidth,
+            maxHeight: Infinity,
+        };
+        // The child should have been measured by the layout engine;
+        // we read its desired size.
+        const childSize = this._child.desiredSize ?? { width: 0, height: 0 };
+        this._contentHeight = childSize.height;
+        const visibleHeight = Math.min(childSize.height, this._maxHeight, constraint.maxHeight);
+        return {
+            width: Math.min(childSize.width, constraint.maxWidth),
+            height: visibleHeight,
+        };
+    }
+    arrange(rect) {
+        if (!this._child)
+            return;
+        // Give the child its full content height, not the clamped visible height
+        this._child.arrange({
+            x: rect.x,
+            y: rect.y - this._scrollOffset,
+            width: rect.width,
+            height: this._contentHeight,
+        });
+        // Re-clamp scroll offset in case content height changed
+        this._scrollOffset = this._clampOffset(this._scrollOffset);
+    }
+    render(ctx) {
+        const bounds = this.bounds;
+        if (!bounds || !this._child)
+            return;
+        // Push a clip rectangle so the child only renders within visible area
+        ctx.pushClip(bounds);
+        // The child was arranged with y offset accounting for scroll,
+        // so it renders correctly within the clip.
+        this._child.render(ctx);
+        ctx.popClip();
+    }
+    // ── Input handling ────────────────────────────────────────────
+    handleInput(event) {
+        // Let child handle first
+        if (this._child) {
+            const childHandled = this._child.handleInput(event);
+            if (childHandled)
+                return true;
+        }
+        if (event.type === "mouse") {
+            const me = event.event;
+            if (me.type === "wheelup") {
+                this.scrollOffset = this._scrollOffset - 3;
+                return true;
+            }
+            if (me.type === "wheeldown") {
+                this.scrollOffset = this._scrollOffset + 3;
+                return true;
+            }
+        }
+        if (event.type === "key") {
+            const ke = event.event;
+            if (ke.key === "up") {
+                this.scrollOffset = this._scrollOffset - 1;
+                return true;
+            }
+            if (ke.key === "down") {
+                this.scrollOffset = this._scrollOffset + 1;
+                return true;
+            }
+            if (ke.key === "pageup") {
+                const bounds = this.bounds;
+                const pageSize = bounds ? bounds.height : 10;
+                this.scrollOffset = this._scrollOffset - pageSize;
+                return true;
+            }
+            if (ke.key === "pagedown") {
+                const bounds = this.bounds;
+                const pageSize = bounds ? bounds.height : 10;
+                this.scrollOffset = this._scrollOffset + pageSize;
+                return true;
+            }
+        }
+        return false;
+    }
+    // ── Internal helpers ──────────────────────────────────────────
+    _clampOffset(offset) {
+        const bounds = this.bounds;
+        const visibleH = bounds ? bounds.height : 0;
+        const maxOffset = Math.max(0, this._contentHeight - visibleH);
+        return Math.max(0, Math.min(offset, maxOffset));
+    }
+}

package/dist/widgets/styled-text.d.ts

@@ -0,0 +1,38 @@
+/**
+ * StyledText — text display widget that renders multi-styled lines.
+ *
+ * Unlike Text (which applies one TextStyle to the whole block), StyledText
+ * accepts StyledSpan lines where each segment can have its own color,
+ * bold, italic, etc.  Plain strings are also accepted and rendered with
+ * a default style.
+ *
+ * Supports word wrapping, but wrapping is computed on the plain-text
+ * representation and styles are carried across wrap boundaries.
+ */
+import type { DrawingContext, TextStyle } from "../drawing/context.js";
+import { Control } from "../layout/control.js";
+import type { Constraint, Size } from "../layout/types.js";
+import { type StyledSpan } from "../styled.js";
+/** A line of styled text: either a StyledSpan or a plain string. */
+export type StyledLine = StyledSpan | string;
+export interface StyledTextOptions {
+    lines?: StyledLine[];
+    defaultStyle?: TextStyle;
+    wrap?: boolean;
+}
+export declare class StyledText extends Control {
+    private _lines;
+    private _defaultStyle;
+    private _wrap;
+    /** Cached wrapped lines from the last measure pass. */
+    private _wrapped;
+    constructor(options?: StyledTextOptions);
+    get lines(): StyledLine[];
+    set lines(value: StyledLine[]);
+    get defaultStyle(): TextStyle;
+    set defaultStyle(value: TextStyle);
+    get wrap(): boolean;
+    set wrap(value: boolean);
+    measure(constraint: Constraint): Size;
+    render(ctx: DrawingContext): void;
+}

package/dist/widgets/styled-text.js

@@ -0,0 +1,183 @@
+/**
+ * StyledText — text display widget that renders multi-styled lines.
+ *
+ * Unlike Text (which applies one TextStyle to the whole block), StyledText
+ * accepts StyledSpan lines where each segment can have its own color,
+ * bold, italic, etc.  Plain strings are also accepted and rendered with
+ * a default style.
+ *
+ * Supports word wrapping, but wrapping is computed on the plain-text
+ * representation and styles are carried across wrap boundaries.
+ */
+import { Control } from "../layout/control.js";
+import { charWidth, stringDisplayWidth } from "../pixel/symbol.js";
+import { spanLength } from "../styled.js";
+// ── Widget ───────────────────────────────────────────────────────
+export class StyledText extends Control {
+    _lines;
+    _defaultStyle;
+    _wrap;
+    /** Cached wrapped lines from the last measure pass. */
+    _wrapped = [];
+    constructor(options = {}) {
+        super();
+        this._lines = options.lines ?? [];
+        this._defaultStyle = options.defaultStyle ?? {};
+        this._wrap = options.wrap ?? false;
+    }
+    // ── Properties ─────────────────────────────────────────────────
+    get lines() {
+        return this._lines;
+    }
+    set lines(value) {
+        this._lines = value;
+        this.invalidate();
+    }
+    get defaultStyle() {
+        return this._defaultStyle;
+    }
+    set defaultStyle(value) {
+        this._defaultStyle = value;
+        this.invalidate();
+    }
+    get wrap() {
+        return this._wrap;
+    }
+    set wrap(value) {
+        if (this._wrap !== value) {
+            this._wrap = value;
+            this.invalidate();
+        }
+    }
+    // ── Layout ─────────────────────────────────────────────────────
+    measure(constraint) {
+        if (this._lines.length === 0) {
+            this._wrapped = [];
+            return { width: 0, height: 0 };
+        }
+        if (!this._wrap) {
+            this._wrapped = this._lines;
+            const maxW = this._lines.reduce((max, line) => Math.max(max, lineLength(line)), 0);
+            return {
+                width: Math.min(maxW, constraint.maxWidth),
+                height: Math.min(this._lines.length, constraint.maxHeight),
+            };
+        }
+        // Word-wrap mode
+        const maxW = constraint.maxWidth;
+        if (maxW <= 0) {
+            this._wrapped = [];
+            return { width: 0, height: 0 };
+        }
+        const wrapped = [];
+        for (const line of this._lines) {
+            const sub = wrapStyledLine(line, maxW);
+            wrapped.push(...sub);
+        }
+        this._wrapped = wrapped;
+        const longestW = wrapped.reduce((max, line) => Math.max(max, lineLength(line)), 0);
+        return {
+            width: Math.min(longestW, constraint.maxWidth),
+            height: Math.min(wrapped.length, constraint.maxHeight),
+        };
+    }
+    render(ctx) {
+        const bounds = this.bounds;
+        if (!bounds || this._wrapped.length === 0)
+            return;
+        for (let i = 0; i < this._wrapped.length && i < bounds.height; i++) {
+            const line = this._wrapped[i];
+            if (typeof line === "string") {
+                ctx.drawText(bounds.x, bounds.y + i, line, this._defaultStyle);
+            }
+            else {
+                // Apply defaultStyle as fallback for segments without explicit colors
+                const merged = line.map((seg) => ({
+                    text: seg.text,
+                    style: mergeStyles(this._defaultStyle, seg.style),
+                }));
+                ctx.drawStyledText(bounds.x, bounds.y + i, merged);
+            }
+        }
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────
+function lineLength(line) {
+    if (typeof line === "string")
+        return stringDisplayWidth(line);
+    return spanLength(line);
+}
+/** Merge a default style with a segment's explicit style. */
+function mergeStyles(base, over) {
+    return {
+        fg: over.fg ?? base.fg,
+        bg: over.bg ?? base.bg,
+        bold: over.bold ?? base.bold,
+        italic: over.italic ?? base.italic,
+        underline: over.underline ?? base.underline,
+        strikethrough: over.strikethrough ?? base.strikethrough,
+    };
+}
+/**
+ * Wrap a styled line to fit within maxWidth.
+ * For plain strings, standard word-wrap. For StyledSpans,
+ * we wrap on the concatenated text and split segments at boundaries.
+ */
+function wrapStyledLine(line, maxWidth) {
+    if (typeof line === "string") {
+        return wrapPlainLine(line, maxWidth);
+    }
+    // Flatten to a stream of { char, style } for wrap calculation
+    const chars = [];
+    for (const seg of line) {
+        for (const ch of seg.text) {
+            chars.push({ char: ch, style: seg.style });
+        }
+    }
+    if (chars.length <= maxWidth)
+        return [line];
+    // Simple hard-wrap at maxWidth (word-aware wrap is complex for styled text)
+    const result = [];
+    for (let start = 0; start < chars.length; start += maxWidth) {
+        const slice = chars.slice(start, start + maxWidth);
+        // Coalesce consecutive chars with same style into segments
+        const segments = [];
+        let cur = null;
+        for (const { char, style } of slice) {
+            if (cur && cur.style === style) {
+                cur.text += char;
+            }
+            else {
+                if (cur)
+                    segments.push(cur);
+                cur = { text: char, style };
+            }
+        }
+        if (cur)
+            segments.push(cur);
+        result.push(segments);
+    }
+    return result;
+}
+function wrapPlainLine(text, maxWidth) {
+    if (stringDisplayWidth(text) <= maxWidth)
+        return [text];
+    const result = [];
+    let current = "";
+    let currentWidth = 0;
+    for (const char of text) {
+        const w = charWidth(char.codePointAt(0));
+        if (currentWidth + w > maxWidth && current.length > 0) {
+            result.push(current);
+            current = char;
+            currentWidth = w;
+        }
+        else {
+            current += char;
+            currentWidth += w;
+        }
+    }
+    if (current)
+        result.push(current);
+    return result;
+}

package/dist/widgets/syntax.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Syntax highlighting — plugin-driven tokenizer for code blocks.
+ *
+ * Each language plugin implements `SyntaxHighlighter` which splits a
+ * line of source code into `SyntaxToken[]`. The markdown renderer
+ * maps token types to `TextStyle` via `SyntaxTheme`.
+ *
+ * Built-in plugins: JavaScript/TypeScript, Python, C#.
+ *
+ * Register custom languages:
+ *   import { registerHighlighter } from "@teammates/consolonia";
+ *   registerHighlighter({ name: "ruby", aliases: ["rb"], tokenize: ... });
+ */
+import type { TextStyle } from "../drawing/context.js";
+/** Semantic token types produced by highlighters. */
+export type SyntaxTokenType = "keyword" | "string" | "number" | "comment" | "operator" | "punctuation" | "type" | "function" | "variable" | "constant" | "decorator" | "attribute" | "text";
+export interface SyntaxToken {
+    text: string;
+    type: SyntaxTokenType;
+}
+/** Maps token types to text styles. */
+export type SyntaxTheme = Record<SyntaxTokenType, TextStyle>;
+export declare const DEFAULT_SYNTAX_THEME: SyntaxTheme;
+export interface SyntaxHighlighter {
+    /** Canonical language name. */
+    name: string;
+    /** Language aliases (e.g. ["js", "jsx", "ts", "tsx"]). */
+    aliases: string[];
+    /** Tokenize a single line of source code. */
+    tokenize(line: string): SyntaxToken[];
+}
+/** Register a syntax highlighter for one or more language aliases. */
+export declare function registerHighlighter(highlighter: SyntaxHighlighter): void;
+/** Look up a highlighter by language name/alias. Returns null if not found. */
+export declare function getHighlighter(lang: string): SyntaxHighlighter | null;
+/** Tokenize a line using the registered highlighter for the given language. */
+export declare function highlightLine(lang: string, line: string): SyntaxToken[];