@breadc/tui 1.0.0-beta.4 → 1.0.0-beta.5

package/dist/index.d.mts

@@ -1,7 +1,137 @@
-//#region src/progress/types.d.ts
-interface ProgressOption {}
+import { Writable } from "node:stream";
+
+//#region src/chat/types.d.ts
+type AnyState = Record<string, unknown>;
+type LogLevel = 'log' | 'info' | 'warn' | 'error';
+interface LogEntry {
+  level: LogLevel;
+  tag?: string;
+  message: string;
+  createdAt: Date;
+}
+interface OutputStream {
+  write(chunk: string): boolean;
+  isTTY?: boolean;
+}
 //#endregion
-//#region src/progress/progress.d.ts
-declare function progress<T>(iterator: Iterable<T>): Iterable<T>;
+//#region src/chat/widget.d.ts
+interface RenderContext<S extends AnyState = AnyState> {
+  tick: number;
+  state: S;
+  fields: AnyState;
+}
+type WidgetTemplate<S extends AnyState = AnyState> = string | string[] | ((ctx: RenderContext<S>) => string | string[]);
+type WidgetFieldResolver<S extends AnyState = AnyState> = (ctx: RenderContext<S>) => unknown;
+type WidgetFields<S extends AnyState = AnyState> = Record<string, WidgetFieldResolver<S>>;
+interface WidgetSpec<S extends AnyState = AnyState> {
+  state: S;
+  template: WidgetTemplate<S>;
+  fields?: WidgetFields<S>;
+}
+interface WidgetHandle<S extends AnyState = AnyState> {
+  readonly id: string;
+  setState(next: Partial<S> | ((previous: S) => Partial<S> | S)): WidgetHandle<S>;
+  setTemplate(template: WidgetTemplate<S>): WidgetHandle<S>;
+  setFields(fields: WidgetFields<S>): WidgetHandle<S>;
+  remove(): void;
+}
+interface SpinnerWidgetState {
+  message: string;
+}
+interface SpinnerWidgetOptions<S extends AnyState = AnyState> {
+  frames?: string[];
+  template?: WidgetTemplate<SpinnerWidgetState & S>;
+  state?: S;
+  fields?: WidgetFields<SpinnerWidgetState & S>;
+}
+interface ProgressWidgetState {
+  message: string;
+  value: number;
+  total: number;
+}
+interface ProgressWidgetOptions<S extends AnyState = AnyState> {
+  value?: number;
+  total?: number;
+  width?: number;
+  complete?: string;
+  incomplete?: string;
+  template?: WidgetTemplate<ProgressWidgetState & S>;
+  state?: S;
+  fields?: WidgetFields<ProgressWidgetState & S>;
+}
 //#endregion
-export { ProgressOption, progress };
+//#region src/chat/renderer.d.ts
+interface RendererOptions {
+  stream: OutputStream;
+  isTTY: boolean;
+  tickInterval: number;
+  nonTTYInterval: number;
+}
+declare class Renderer {
+  private readonly stream;
+  private readonly isTTY;
+  private readonly tickInterval;
+  private readonly nonTTYInterval;
+  private readonly widgets;
+  private tick;
+  private disposed;
+  private idCounter;
+  private prevBottomCount;
+  private scheduled;
+  private queuedForce;
+  private ticker;
+  private lastNonTTYRender;
+  constructor(options: RendererOptions);
+  writeAboveBottom(line: string): void;
+  createWidget<S extends AnyState>(spec: WidgetSpec<S>): WidgetHandle<S>;
+  createSpinnerWidget<S extends AnyState = AnyState>(message: string, options?: SpinnerWidgetOptions<S>): WidgetHandle<SpinnerWidgetState & S>;
+  createProgressWidget<S extends AnyState = AnyState>(message: string, options?: ProgressWidgetOptions<S>): WidgetHandle<ProgressWidgetState & S>;
+  render(force?: boolean): void;
+  clearBottom(): void;
+  dispose(): void;
+  private createId;
+  private stopTicker;
+  private ensureTicker;
+  private clearBottomTTY;
+  private renderWidgets;
+  private drawBottomTTY;
+  private drawBottomNonTTY;
+  private scheduleRender;
+}
+//#endregion
+//#region src/chat/log.d.ts
+interface LogFormatterOptions {
+  tag?: string;
+  columns: number;
+  isTTY: boolean;
+}
+//#endregion
+//#region src/chat/chat.d.ts
+interface ChatOptions {
+  renderer?: Renderer;
+  stream?: Writable & {
+    isTTY?: boolean;
+    columns?: number;
+  };
+  tickInterval?: number;
+  nonTTYInterval?: number;
+  log?: {
+    tag?: string;
+    format?: (entry: LogEntry, options: LogFormatterOptions) => string;
+  };
+}
+interface Chat {
+  log(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+  widget<S extends AnyState>(spec: WidgetSpec<S>): WidgetHandle<S>;
+  spinner<S extends AnyState = AnyState>(message: string, options?: SpinnerWidgetOptions<S>): WidgetHandle<SpinnerWidgetState & S>;
+  progress<S extends AnyState = AnyState>(message: string, options?: ProgressWidgetOptions<S>): WidgetHandle<ProgressWidgetState & S>;
+  render(force?: boolean): void;
+  clearBottom(): void;
+  dispose(): void;
+}
+declare function chat(options?: ChatOptions): Chat;
+//#endregion
+export { AnyState, LogEntry, LogLevel, OutputStream, chat };

package/dist/index.mjs

@@ -1,7 +1,353 @@
-//#region src/progress/progress.ts
-function* progress(iterator) {
-	for (const item of iterator) yield item;
+import { format } from "node:util";
+import readline from "node:readline";
+import { cyan, gray, red, yellow } from "@breadc/color";
+
+//#region src/chat/helpers.ts
+function renderProgressBar(value, total, barOptions) {
+	const width = Math.max(1, barOptions.width);
+	const complete = barOptions.complete ?? "=";
+	const incomplete = barOptions.incomplete ?? "-";
+	const ratio = total > 0 ? clamp(value / total, 0, 1) : 0;
+	const completeCount = Math.round(ratio * width);
+	return complete.repeat(completeCount) + incomplete.repeat(width - completeCount);
+}
+function renderPercent(value, total) {
+	if (total <= 0) return 0;
+	return Math.floor(clamp(value / total * 100, 0, 100));
+}
+function renderTemplateLines(template, context, resolvedValues) {
+	const rawTemplate = typeof template === "function" ? template(context) : template;
+	const templateLines = Array.isArray(rawTemplate) ? rawTemplate : [rawTemplate];
+	const lines = [];
+	for (const line of templateLines) {
+		const text = line.replace(/\{([a-zA-Z0-9_]+)\}/g, (_, key) => {
+			const value = resolvedValues[key];
+			return stringifyValue(value);
+		});
+		for (const chunk of text.split(/\r?\n/g)) lines.push(chunk);
+	}
+	return lines;
+}
+function stringifyValue(value) {
+	if (value === void 0 || value === null) return "";
+	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+function numericOrDefault(value, fallback) {
+	const parsed = Number(value);
+	return Number.isFinite(parsed) ? parsed : fallback;
+}
+function normalizeProgressValue(value, total) {
+	if (total <= 0) return 0;
+	return clamp(value, 0, total);
+}
+function clamp(value, min, max) {
+	return Math.min(Math.max(value, min), max);
+}
+
+//#endregion
+//#region src/chat/renderer.ts
+const DEFAULT_SPINNER_FRAMES = [
+	"-",
+	"\\",
+	"|",
+	"/"
+];
+const DEFAULT_PROGRESS_WIDTH = 24;
+var Renderer = class {
+	constructor(options) {
+		this.widgets = [];
+		this.tick = 0;
+		this.disposed = false;
+		this.idCounter = 0;
+		this.prevBottomCount = 0;
+		this.scheduled = false;
+		this.queuedForce = false;
+		this.lastNonTTYRender = 0;
+		this.stream = options.stream;
+		this.isTTY = options.isTTY;
+		this.tickInterval = options.tickInterval;
+		this.nonTTYInterval = options.nonTTYInterval;
+	}
+	writeAboveBottom(line) {
+		if (this.disposed) return;
+		if (this.isTTY) this.clearBottomTTY();
+		this.stream.write(`${line}\n`);
+		if (this.isTTY) this.drawBottomTTY();
+	}
+	createWidget(spec) {
+		const widget = {
+			id: this.createId(),
+			state: { ...spec.state },
+			template: spec.template,
+			fields: { ...spec.fields ?? {} }
+		};
+		this.widgets.push(widget);
+		this.ensureTicker();
+		this.scheduleRender(true);
+		const handle = {
+			id: widget.id,
+			setState: (next) => {
+				if (this.disposed || !this.widgets.includes(widget)) return handle;
+				const patch = typeof next === "function" ? next({ ...widget.state }) : next;
+				widget.state = {
+					...widget.state,
+					...patch
+				};
+				this.scheduleRender(false);
+				return handle;
+			},
+			setTemplate: (template) => {
+				if (this.disposed || !this.widgets.includes(widget)) return handle;
+				widget.template = template;
+				this.scheduleRender(false);
+				return handle;
+			},
+			setFields: (fields) => {
+				if (this.disposed || !this.widgets.includes(widget)) return handle;
+				widget.fields = {
+					...widget.fields,
+					...fields
+				};
+				this.scheduleRender(false);
+				return handle;
+			},
+			remove: () => {
+				if (this.disposed) return;
+				const index = this.widgets.indexOf(widget);
+				if (index === -1) return;
+				this.widgets.splice(index, 1);
+				if (this.widgets.length === 0) this.stopTicker();
+				this.scheduleRender(true);
+			}
+		};
+		return handle;
+	}
+	createSpinnerWidget(message, options = {}) {
+		const frames = options.frames?.length ? options.frames : DEFAULT_SPINNER_FRAMES;
+		const template = options.template ?? "{frame} {message}";
+		const fields = {
+			frame: (ctx) => {
+				if (frames.length === 0) return "";
+				return frames[ctx.tick % frames.length];
+			},
+			...options.fields ?? {}
+		};
+		return this.createWidget({
+			state: {
+				message,
+				...options.state ?? {}
+			},
+			template,
+			fields
+		});
+	}
+	createProgressWidget(message, options = {}) {
+		const width = Math.max(1, options.width || DEFAULT_PROGRESS_WIDTH);
+		const complete = options.complete ?? "█";
+		const incomplete = options.incomplete ?? "░";
+		const template = options.template ?? "{message} [{bar}] {percent}% {value}/{total}";
+		const fields = {
+			bar: (ctx) => {
+				const total = numericOrDefault(ctx.state.total, 0);
+				return renderProgressBar(normalizeProgressValue(numericOrDefault(ctx.state.value, 0), total), total, {
+					width,
+					complete,
+					incomplete
+				});
+			},
+			percent: (ctx) => {
+				const total = numericOrDefault(ctx.state.total, 0);
+				return renderPercent(normalizeProgressValue(numericOrDefault(ctx.state.value, 0), total), total);
+			},
+			...options.fields ?? {}
+		};
+		return this.createWidget({
+			state: {
+				message,
+				value: options.value ?? 0,
+				total: options.total ?? 100,
+				...options.state ?? {}
+			},
+			template,
+			fields
+		});
+	}
+	render(force = false) {
+		if (this.disposed) return;
+		if (this.isTTY) {
+			this.clearBottomTTY();
+			this.drawBottomTTY();
+			return;
+		}
+		this.drawBottomNonTTY(force);
+	}
+	clearBottom() {
+		if (this.disposed || !this.isTTY) return;
+		this.clearBottomTTY();
+	}
+	dispose() {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.stopTicker();
+		this.widgets.length = 0;
+		if (this.isTTY) this.clearBottomTTY();
+	}
+	createId() {
+		this.idCounter += 1;
+		return `widget-${this.idCounter}`;
+	}
+	stopTicker() {
+		if (!this.ticker) return;
+		clearInterval(this.ticker);
+		this.ticker = void 0;
+	}
+	ensureTicker() {
+		if (this.ticker || this.disposed || this.widgets.length === 0) return;
+		this.ticker = setInterval(() => {
+			if (this.disposed || this.widgets.length === 0) {
+				this.stopTicker();
+				return;
+			}
+			this.tick += 1;
+			this.scheduleRender(false);
+		}, this.tickInterval);
+	}
+	clearBottomTTY() {
+		if (!this.isTTY || this.prevBottomCount === 0) return;
+		const output = this.stream;
+		if (this.prevBottomCount > 1) readline.moveCursor(output, 0, -(this.prevBottomCount - 1));
+		readline.cursorTo(output, 0);
+		readline.clearScreenDown(output);
+		this.prevBottomCount = 0;
+	}
+	renderWidgets() {
+		const lines = [];
+		for (const widget of this.widgets) {
+			const context = {
+				tick: this.tick,
+				state: widget.state,
+				fields: {}
+			};
+			const resolvedValues = {
+				...widget.state,
+				tick: this.tick
+			};
+			for (const [key, resolver] of Object.entries(widget.fields)) resolvedValues[key] = resolver(context);
+			lines.push(...renderTemplateLines(widget.template, context, resolvedValues));
+		}
+		return lines;
+	}
+	drawBottomTTY() {
+		const lines = this.renderWidgets();
+		if (lines.length === 0) {
+			this.prevBottomCount = 0;
+			return;
+		}
+		for (let i = 0; i < lines.length; i += 1) {
+			this.stream.write(lines[i]);
+			if (i < lines.length - 1) this.stream.write("\n");
+		}
+		this.prevBottomCount = lines.length;
+	}
+	drawBottomNonTTY(force) {
+		const now = Date.now();
+		if (!force && now - this.lastNonTTYRender < this.nonTTYInterval) return;
+		const lines = this.renderWidgets();
+		if (lines.length === 0) return;
+		for (const line of lines) this.stream.write(`${line}\n`);
+		this.lastNonTTYRender = now;
+	}
+	scheduleRender(force = false) {
+		if (this.disposed) return;
+		this.queuedForce = this.queuedForce || force;
+		if (this.scheduled) return;
+		this.scheduled = true;
+		queueMicrotask(() => {
+			this.scheduled = false;
+			const shouldForce = this.queuedForce;
+			this.queuedForce = false;
+			this.render(shouldForce);
+		});
+	}
+};
+
+//#endregion
+//#region src/chat/log.ts
+const LOG_LEVEL_PREFIX = {
+	log: "LOG",
+	info: "INFO",
+	warn: "WARN",
+	error: "ERROR"
+};
+const LOG_LEVEL_COLOR = {
+	log: gray,
+	info: cyan,
+	warn: yellow,
+	error: red
+};
+function defaultLogFormatter(entry, options) {
+	if (options.isTTY) {
+		if (entry.level === "log") return entry.message;
+		const color = LOG_LEVEL_COLOR[entry.level];
+		return `${color(`[${LOG_LEVEL_PREFIX[entry.level]}]`)} ${entry.message}`;
+	} else return `[${LOG_LEVEL_PREFIX[entry.level]}] ${entry.message}`;
+}
+
+//#endregion
+//#region src/chat/chat.ts
+const DEFAULT_TICK_INTERVAL = 80;
+const DEFAULT_NON_TTY_INTERVAL = 1e3;
+function chat(options = {}) {
+	const stream = options.stream ?? process.stderr;
+	const isTTY = !!stream.isTTY;
+	const tickInterval = Math.max(1, options.tickInterval ?? DEFAULT_TICK_INTERVAL);
+	const nonTTYInterval = Math.max(0, options.nonTTYInterval ?? DEFAULT_NON_TTY_INTERVAL);
+	const renderer = options.renderer ?? new Renderer({
+		stream,
+		isTTY,
+		tickInterval,
+		nonTTYInterval
+	});
+	const writeLog = (level, args) => {
+		const entry = {
+			level,
+			message: format(...args),
+			createdAt: /* @__PURE__ */ new Date()
+		};
+		const opt = {
+			tag: options.log?.tag,
+			columns: stream.columns || 80,
+			isTTY: stream.isTTY || false
+		};
+		const line = options.log?.format ? options.log.format(entry, opt) : defaultLogFormatter(entry, opt);
+		renderer.writeAboveBottom(line);
+	};
+	return {
+		log(...args) {
+			writeLog("log", args);
+		},
+		info(...args) {
+			writeLog("info", args);
+		},
+		warn(...args) {
+			writeLog("warn", args);
+		},
+		error(...args) {
+			writeLog("error", args);
+		},
+		widget: (spec) => renderer.createWidget(spec),
+		spinner: (message, spinnerOptions) => renderer.createSpinnerWidget(message, spinnerOptions),
+		progress: (message, progressOptions) => renderer.createProgressWidget(message, progressOptions),
+		render: (force) => renderer.render(force),
+		clearBottom: () => renderer.clearBottom(),
+		dispose: () => renderer.dispose()
+	};
 }
 
 //#endregion
-export { progress };
+export { chat };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@breadc/tui",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.5",
   "description": "TUI for Breadc",
   "keywords": [
     "breadc",
@@ -34,7 +34,7 @@
   "dependencies": {
     "std-env": "^3.10.0",
     "string-width": "^8.1.1",
-    "@breadc/color": "1.0.0-beta.4"
+    "@breadc/color": "1.0.0-beta.5"
   },
   "scripts": {
     "build": "tsdown",