@zaly/tui 0.0.4

package/dist/widgets/select.mjs

@@ -0,0 +1,195 @@
+import { S as unwrap, f as effect } from "../reactive-f7NpAi69.mjs";
+import { t as Node } from "../node-BZ7f6HzU.mjs";
+import { n as resolveSize } from "../size-D8JogYLy.mjs";
+import { fitAnsi, stringWidth } from "@zaly/shared/ansi";
+//#region src/widgets/select.ts
+/**
+* Selectable list. Items are rendered one per row with an active-row
+* highlight; navigation actions (`next`, `prev`, `first`, `last`,
+* `accept`, `complete`, `cancel`) live on `this.actions`, same pattern as
+* `Input`.
+*
+* Used standalone for simple lists and as the underlying list primitive for
+* `picker`, `tree`, and `autocomplete`. Doesn't open/close itself — callers
+* control visibility via `state.visible`.
+*/
+var Select = class Select extends Node {
+	static type = "select";
+	type = Select.type;
+	actions = {
+		"select.accept": () => {
+			const items = this.#items;
+			if (items.length === 0) return;
+			this.emit("accept", { item: items[this.active] });
+		},
+		"select.close": () => {
+			this.emit("close");
+		},
+		"select.complete": () => {
+			const items = this.#items;
+			if (items.length === 0) return;
+			this.emit("complete", { item: items[this.active] });
+		},
+		"select.first": () => {
+			if (this.#items.length === 0) return;
+			this.active = 0;
+		},
+		"select.last": () => {
+			const n = this.#items.length;
+			if (n === 0) return;
+			this.active = n - 1;
+		},
+		"select.next": () => {
+			if (this.#items.length === 0) return;
+			this.active += this.#direction;
+		},
+		"select.page-down": () => {
+			if (this.#items.length === 0) return;
+			const page = Math.max(this.pageSize - 1, 1);
+			this.state.active = this.#clamp(this.active + this.#direction * page);
+		},
+		"select.page-up": () => {
+			if (this.#items.length === 0) return;
+			const page = Math.max(this.pageSize - 1, 1);
+			this.state.active = this.#clamp(this.active - this.#direction * page);
+		},
+		"select.prev": () => {
+			if (this.#items.length === 0) return;
+			this.active -= this.#direction;
+		}
+	};
+	/** Top of the currently-rendered window, in absolute item indices.
+	*  Updated per render using the pin-until-leave rule: stays put
+	*  while `active` remains in `[start, start + visible)`, slides just
+	*  enough to re-admit it otherwise. */
+	#windowStart = 0;
+	constructor(initial) {
+		super({
+			active: 0,
+			...initial
+		});
+		let active = this.item;
+		effect(() => {
+			const next = this.item;
+			if (next === active) return;
+			active = next;
+			this.emit("changed", {
+				active: this.active,
+				item: next
+			});
+		});
+	}
+	get #direction() {
+		return this.state.reverse ? -1 : 1;
+	}
+	get #items() {
+		return unwrap(this.state.items);
+	}
+	#clamp(i) {
+		const n = this.#items.length;
+		return n === 0 ? 0 : Math.max(0, Math.min(n - 1, i));
+	}
+	set active(i) {
+		const n = this.#items.length;
+		this.state.active = n === 0 ? 0 : (i % n + n) % n;
+	}
+	get active() {
+		const a = this.state.active ?? 0;
+		const n = this.#items.length;
+		if (n === 0) return 0;
+		return Math.max(0, Math.min(n - 1, a));
+	}
+	bind(node) {
+		let n;
+		const getn = () => n = node instanceof Node ? node : node();
+		this.on("mount", () => getn().addActionTarget(this));
+		this.on("unmount", () => n?.removeActionTarget(this));
+		if (this.mounted) getn().addActionTarget(this);
+		return this;
+	}
+	get count() {
+		return this.#items.length;
+	}
+	get pageSize() {
+		return unwrap(this.state.maxHeight) ?? Math.max(this.#items.length, 1);
+	}
+	get item() {
+		return this.#items[this.active];
+	}
+	_render(ctx) {
+		const items = this.#items;
+		if (items.length === 0) return [];
+		const width = resolveSize(this.state.width ?? "fill", ctx.width) ?? ctx.width;
+		const active = this.active;
+		const height = Math.min(this.pageSize, items.length);
+		if (height === 0) return [];
+		let start = this.#windowStart;
+		if (active < start) start = active;
+		else if (active >= start + height) start = active - height + 1;
+		start = Math.max(0, Math.min(Math.max(0, items.length - height), start));
+		this.#windowStart = start;
+		const visible = items.slice(start, start + height);
+		const renderer = this.renderer;
+		const rows = [];
+		for (let i = start; i < start + height; i++) {
+			const item = items[i];
+			let row = renderer(item, {
+				...ctx,
+				active: i === active,
+				items,
+				visible
+			}).replace(/\n/g, " ");
+			row = fitAnsi(row, width);
+			rows.push(i === active ? ctx.style.optionActive(row) : row);
+		}
+		if (this.state.reverse) rows.reverse();
+		if (this.state.counter ?? items.length > height) {
+			const label = `(${items.length === 0 ? 0 : active + 1}/${items.length}${this.state.more ? "+" : ""})`;
+			rows.push(ctx.style.gutter(fitAnsi(label, width)));
+		}
+		return rows;
+	}
+	get renderer() {
+		return unwrap(this.state.render) ?? this.defaultRenderer();
+	}
+	extendRenderer(fn) {
+		const prev = this.renderer;
+		this.state.render = fn(prev);
+		return this;
+	}
+	defaultRenderer() {
+		let visible = [];
+		let labelWidth = 0;
+		const update = (ctx) => {
+			if (ctx.visible === visible) return;
+			visible = ctx.visible;
+			if (!visible.some((i) => i.desc)) return labelWidth = ctx.width;
+			labelWidth = this.state.labelWidth ?? 0;
+			labelWidth ||= visible.map(itemLabel).reduce((max, label) => Math.max(max, stringWidth(label)), 0);
+			labelWidth = Math.min(labelWidth, Math.floor(ctx.width / 2));
+		};
+		return (item, ctx) => {
+			update(ctx);
+			const label = fitAnsi(itemLabel(item), labelWidth);
+			if (!item.desc) return ctx.style.optionName(label);
+			const desc = fitAnsi(item.desc ?? "", Math.max(0, ctx.width - labelWidth - 2));
+			return `${ctx.style.optionName(label)}  ${ctx.style.optionDesc(desc)}`;
+		};
+	}
+};
+const itemLabel = (item) => (item.name ?? item.text).replace(/\s+/g, " ").trim();
+/**
+* Factory for a selectable list.
+*
+* ```ts
+* const s = select({ items: [{ text: "/help" }, { text: "/quit" }] })
+* s.on("accept", ({ item }) => console.log("picked", item.text))
+* ```
+*/
+function select(state) {
+	return new Select(state);
+}
+//#endregion
+export { Select, select };
+
+//# sourceMappingURL=select.mjs.map

package/dist/widgets/select.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.mjs","names":["#items","#direction","#clamp","#windowStart"],"sources":["../../src/widgets/select.ts"],"sourcesContent":["import type { RenderCtx } from \"../core/ctx.ts\"\nimport type { BaseEvents } from \"../core/node.ts\"\nimport type { Reactive, Ref } from \"../core/reactive.ts\"\nimport type { State } from \"../core/state.ts\"\nimport type { NodeActionMap } from \"../input/actions.ts\"\nimport type { Size } from \"../layout/size.ts\"\nimport type { Style } from \"../style/types.ts\"\n\nimport { fitAnsi, stringWidth } from \"@zaly/shared/ansi\"\nimport { Node } from \"../core/node.ts\"\nimport { effect, unwrap } from \"../core/reactive.ts\"\nimport { resolveSize } from \"../layout/size.ts\"\n\n/** Default shape for selectable options. `text` is the canonical\n *  searchable/fallback label. `name` overrides the displayed label in the\n *  default renderer, and `desc` is shown as a dim right-column description. */\nexport type Option = {\n  name?: string\n  desc?: string\n  text: string\n}\n\nexport type OptionRenderCtx<T> = RenderCtx & {\n  visible: readonly T[]\n  items: readonly T[]\n  active?: boolean\n  prefixWidth?: number\n}\n\n/** Per-row rendering hook. `ctx.active` lets callers branch on selection\n *  state (e.g. swap an icon or pick a different fg) — but Select still\n *  applies the `optionActive` theme slot uniformly so the highlight stays\n *  visually consistent. The returned string is clipped/padded to the row\n *  width by Select. */\nexport type OptionRender<T> = (item: T, ctx: OptionRenderCtx<T>) => string\n\nexport interface SelectState<T extends Option = Option> extends Style {\n  /** Items to show. Accepts a signal accessor so the list can be\n   *  driven from reactive state (filtered results, search, etc.). */\n  items: Reactive<readonly T[]>\n  /** Index of the highlighted row. Defaults to 0; clamped on render. */\n  active?: number\n  /** Max item rows visible at once. The counter (when shown) is an\n   *  extra row on top of this, not counted against the cap. Window\n   *  slides to keep `active` in view (pin-until-leave). */\n  maxHeight?: Reactive<number>\n  /** Show a `(active+1 / total)` footer as an extra row when items\n   *  don't fit. `undefined` (default) auto-shows when needed;\n   *  `false` disables, `true` forces on. */\n  counter?: boolean\n  /** Render width. Defaults to `fill`. */\n  width?: Size\n  /** Width of the label column for the default renderer. Defaults to the\n   *  widest visible label, capped to half the row width. Ignored when\n   *  `render` is set. */\n  labelWidth?: number\n  /** Per-item renderer. When omitted, the default two-column layout uses\n   *  `name ?? text` as the label and `desc` as the right-column hint. */\n  render?: Reactive<OptionRender<T> | undefined>\n  reverse?: boolean\n  /** Whether there are more items available than are currently shown. This is a hint for the\n   *  default renderer to show a \"more\" indicator in the counter. */\n  more?: boolean\n}\n\nexport interface SelectEvents<T extends Option = Option> extends BaseEvents {\n  /** Fired when the user completes the active item. Payload is the item. */\n  complete: { item: T }\n  /** Fired when the user picks the active item. Payload is the item. */\n  accept: { item: T }\n  /** Fired when the user closes the select (esc). */\n  close: {}\n  changed: { active: number; item?: T }\n}\n\n/**\n * Selectable list. Items are rendered one per row with an active-row\n * highlight; navigation actions (`next`, `prev`, `first`, `last`,\n * `accept`, `complete`, `cancel`) live on `this.actions`, same pattern as\n * `Input`.\n *\n * Used standalone for simple lists and as the underlying list primitive for\n * `picker`, `tree`, and `autocomplete`. Doesn't open/close itself — callers\n * control visibility via `state.visible`.\n */\nexport class Select<T extends Option = Option> extends Node<SelectState<T>, SelectEvents<T>> {\n  static readonly type = \"select\"\n  override readonly type = Select.type\n\n  override actions = {\n    \"select.accept\": (): void => {\n      const items = this.#items\n      if (items.length === 0) return\n      void this.emit(\"accept\", { item: items[this.active] })\n    },\n    \"select.close\": (): void => {\n      void this.emit(\"close\")\n    },\n    \"select.complete\": (): void => {\n      const items = this.#items\n      if (items.length === 0) return\n      void this.emit(\"complete\", { item: items[this.active] })\n    },\n    \"select.first\": (): void => {\n      if (this.#items.length === 0) return\n      this.active = 0\n    },\n    \"select.last\": (): void => {\n      const n = this.#items.length\n      if (n === 0) return\n      this.active = n - 1\n    },\n    \"select.next\": (): void => {\n      const n = this.#items.length\n      if (n === 0) return\n      this.active += this.#direction\n    },\n    \"select.page-down\": (): void => {\n      const n = this.#items.length\n      if (n === 0) return\n      const page = Math.max(this.pageSize - 1, 1)\n      this.state.active = this.#clamp(this.active + this.#direction * page)\n    },\n    \"select.page-up\": (): void => {\n      const n = this.#items.length\n      if (n === 0) return\n      const page = Math.max(this.pageSize - 1, 1)\n      this.state.active = this.#clamp(this.active - this.#direction * page)\n    },\n    \"select.prev\": (): void => {\n      const n = this.#items.length\n      if (n === 0) return\n      this.active -= this.#direction\n    },\n  } satisfies NodeActionMap\n\n  /** Top of the currently-rendered window, in absolute item indices.\n   *  Updated per render using the pin-until-leave rule: stays put\n   *  while `active` remains in `[start, start + visible)`, slides just\n   *  enough to re-admit it otherwise. */\n  #windowStart = 0\n\n  constructor(initial: SelectState<T>) {\n    super({ active: 0, ...initial } as SelectState<T>)\n\n    let active = this.item\n    effect(() => {\n      const next = this.item\n      if (next === active) return\n      active = next\n      void this.emit(\"changed\", { active: this.active, item: next })\n    })\n  }\n\n  get #direction(): 1 | -1 {\n    return this.state.reverse ? -1 : 1\n  }\n\n  get #items() {\n    return unwrap(this.state.items)\n  }\n\n  #clamp(i: number): number {\n    const n = this.#items.length\n    return n === 0 ? 0 : Math.max(0, Math.min(n - 1, i))\n  }\n\n  set active(i: number) {\n    const n = this.#items.length\n    this.state.active = n === 0 ? 0 : ((i % n) + n) % n\n  }\n\n  get active(): number {\n    const a = this.state.active ?? 0\n    const n = this.#items.length\n    if (n === 0) return 0\n    return Math.max(0, Math.min(n - 1, a))\n  }\n\n  bind(node: Node | Ref<Node>): this {\n    let n: Node | undefined\n    const getn = () => (n = node instanceof Node ? node : node())\n    this.on(\"mount\", () => getn().addActionTarget(this))\n    this.on(\"unmount\", () => n?.removeActionTarget(this))\n    if (this.mounted) getn().addActionTarget(this)\n    return this\n  }\n\n  get count(): number {\n    return this.#items.length\n  }\n\n  get pageSize(): number {\n    return unwrap(this.state.maxHeight) ?? Math.max(this.#items.length, 1)\n  }\n\n  get item(): T | undefined {\n    return this.#items[this.active]\n  }\n\n  protected _render(ctx: RenderCtx): string[] {\n    const items = this.#items\n    if (items.length === 0) return []\n\n    const width = resolveSize(this.state.width ?? \"fill\", ctx.width) ?? ctx.width\n    const active = this.active\n    const height = Math.min(this.pageSize, items.length)\n    if (height === 0) return []\n\n    // Pin-until-leave window. `#windowStart` is kept across renders so\n    // the list doesn't recenter while the user nudges up/down inside\n    let start = this.#windowStart\n    if (active < start) start = active\n    else if (active >= start + height) start = active - height + 1\n    start = Math.max(0, Math.min(Math.max(0, items.length - height), start))\n    this.#windowStart = start\n\n    const visible = items.slice(start, start + height)\n    const renderer = this.renderer\n\n    const rows: string[] = []\n    for (let i = start; i < start + height; i++) {\n      const item = items[i]\n      let row = renderer(item, {\n        ...ctx,\n        active: i === active,\n        items,\n        visible,\n      }).replace(/\\n/g, \" \")\n      row = fitAnsi(row, width)\n      rows.push(i === active ? ctx.style.optionActive(row) : row)\n    }\n    if (this.state.reverse) rows.reverse()\n\n    if (this.state.counter ?? items.length > height) {\n      const shown = items.length === 0 ? 0 : active + 1\n      const label = `(${shown}/${items.length}${this.state.more ? \"+\" : \"\"})`\n      rows.push(ctx.style.gutter(fitAnsi(label, width)))\n    }\n\n    return rows\n  }\n\n  get renderer(): OptionRender<T> {\n    return unwrap(this.state.render) ?? this.defaultRenderer()\n  }\n\n  extendRenderer(fn: (prev: OptionRender<T>) => OptionRender<T>): this {\n    const prev = this.renderer\n    this.state.render = fn(prev)\n    return this\n  }\n\n  defaultRenderer(): OptionRender<Option> {\n    let visible: readonly Option[] = []\n    let labelWidth = 0\n\n    const update = (ctx: OptionRenderCtx<Option>) => {\n      if (ctx.visible === visible) return\n      visible = ctx.visible\n      if (!visible.some((i) => i.desc)) return (labelWidth = ctx.width) // No desc, so full width\n      labelWidth = this.state.labelWidth ?? 0\n      labelWidth ||= visible\n        .map(itemLabel)\n        .reduce((max, label) => Math.max(max, stringWidth(label)), 0)\n      labelWidth = Math.min(labelWidth, Math.floor(ctx.width / 2))\n    }\n\n    return (item: Option, ctx): string => {\n      update(ctx)\n      const label = fitAnsi(itemLabel(item), labelWidth)\n      if (!item.desc) return ctx.style.optionName(label)\n      const desc = fitAnsi(item.desc ?? \"\", Math.max(0, ctx.width - labelWidth - 2))\n      return `${ctx.style.optionName(label)}  ${ctx.style.optionDesc(desc)}`\n    }\n  }\n}\n\nconst itemLabel = (item: Option): string => (item.name ?? item.text).replace(/\\s+/g, \" \").trim()\n\n/**\n * Factory for a selectable list.\n *\n * ```ts\n * const s = select({ items: [{ text: \"/help\" }, { text: \"/quit\" }] })\n * s.on(\"accept\", ({ item }) => console.log(\"picked\", item.text))\n * ```\n */\nexport function select<T extends Option = Option>(state: State<SelectState<T>>): Select<T> {\n  return new Select<T>(state)\n}\n"],"mappings":"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"}

package/dist/widgets/show.d.mts

@@ -0,0 +1,55 @@
+import { P as RenderCtx, nt as Reactive, p as Node } from "../queries-DH3bj74K.mjs";
+//#region src/widgets/show.d.ts
+type ShowGate = {
+  when: Reactive<unknown>;
+};
+type ShowBranch = {
+  when: Reactive<unknown>;
+  use: ShowChildren;
+};
+type ShowChildren = () => Node | Node[];
+type ShowSpec = (ShowGate | ShowBranch)[] | [...(ShowGate | ShowBranch)[], ShowChildren];
+/** Conditional fragment backing `show()`. Branches are created lazily:
+ * a `use` factory only runs the first time its condition wins. Once
+ * created, the branch remains mounted and owned; inactive branches simply
+ * don't participate in layout/rendering and contribute zero rows.
+ *
+ * Lazy factories run under the owner captured at `show()` creation time,
+ * so context reads behave as if the branch had been constructed eagerly.
+ */
+declare class Show extends Node {
+  #private;
+  constructor(spec: ShowSpec);
+  layoutChildren(): readonly Node[];
+  /** Standalone-render fallback. Box parents go through
+   *  `layoutChildren` and bypass this; only fires when `Show` sits
+   *  outside a layout container (root, overlay, etc.). */
+  protected _render(ctx: RenderCtx): Promise<string[]>;
+}
+/** Lazy conditional rendering.
+ *
+ * Specs are evaluated from left to right:
+ * - `{ when }` is a guard. When false, rendering stops with no rows; when
+ *   true, evaluation continues.
+ * - `{ when, use }` is a conditional branch. The first branch whose
+ *   condition is truthy is rendered.
+ * - A final bare factory is the fallback branch and must be the last
+ *   argument.
+ *
+ * Branch factories are lazy and run at most once. Created branches stay
+ * mounted across toggles, preserving state, effects, and async resources.
+ *
+ * ```ts
+ * show({ when: isLoading }, () => spinner({ color: "accent" }))
+ *
+ * show(
+ *   { when: full },
+ *   { when: isError, use: () => errorView() },
+ *   () => resultView()
+ * )
+ * ```
+ */
+declare function show(...spec: ShowSpec): Show;
+//#endregion
+export { type Show, ShowBranch, ShowChildren, ShowGate, ShowSpec, show };
+//# sourceMappingURL=show.d.mts.map

package/dist/widgets/show.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"show.d.mts","names":[],"sources":["../../src/widgets/show.ts"],"mappings":";;KAMY;EAAa,MAAM;;KACnB;EAAe,MAAM;EAAmB,KAAK;;KAC7C,qBAAqB,OAAO;KAC5B,YAAY,WAAW,qBAAqB,WAAW,eAAe;;;;;;;;;cAkB5E,aAAa;;EAIjB,YAAY,MAAM;EAqBT,2BAA2B;;;;YAepB,QAAQ,KAAK,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;iBA8B3B,QAAQ,MAAM,WAAW"}

package/dist/widgets/show.mjs

@@ -0,0 +1,85 @@
+import { C as useActiveOwner, E as withOwner, S as unwrap, x as untrack } from "../reactive-f7NpAi69.mjs";
+import { t as Node } from "../node-BZ7f6HzU.mjs";
+//#region src/widgets/show.ts
+/** Conditional fragment backing `show()`. Branches are created lazily:
+* a `use` factory only runs the first time its condition wins. Once
+* created, the branch remains mounted and owned; inactive branches simply
+* don't participate in layout/rendering and contribute zero rows.
+*
+* Lazy factories run under the owner captured at `show()` creation time,
+* so context reads behave as if the branch had been constructed eagerly.
+*/
+var Show = class extends Node {
+	#state = [];
+	#owner = useActiveOwner();
+	constructor(spec) {
+		super({});
+		let fallback = false;
+		for (const s of spec) {
+			if (fallback) throw new Error("Show: `fallback` must be the final argument");
+			if (typeof s === "function") {
+				this.#state.push({
+					use: s,
+					when: true
+				});
+				fallback = true;
+			} else this.#state.push(s);
+		}
+	}
+	#nodes(s, use) {
+		if (s.children) return s.children;
+		const create = () => untrack(use);
+		const nodes = this.#owner ? withOwner(this.#owner, create) : create();
+		s.children = Array.isArray(nodes) ? nodes : [nodes];
+		for (const c of s.children) this.add(c);
+		return s.children;
+	}
+	layoutChildren() {
+		for (const s of this.#state) {
+			const matches = unwrap(s.when);
+			if (s.use === void 0) {
+				if (!matches) return [];
+				continue;
+			} else if (!matches) continue;
+			return this.#nodes(s, s.use);
+		}
+		return [];
+	}
+	/** Standalone-render fallback. Box parents go through
+	*  `layoutChildren` and bypass this; only fires when `Show` sits
+	*  outside a layout container (root, overlay, etc.). */
+	async _render(ctx) {
+		const targets = this.layoutChildren();
+		return (await Promise.all(targets.map((c) => c.render(ctx)))).flat();
+	}
+};
+/** Lazy conditional rendering.
+*
+* Specs are evaluated from left to right:
+* - `{ when }` is a guard. When false, rendering stops with no rows; when
+*   true, evaluation continues.
+* - `{ when, use }` is a conditional branch. The first branch whose
+*   condition is truthy is rendered.
+* - A final bare factory is the fallback branch and must be the last
+*   argument.
+*
+* Branch factories are lazy and run at most once. Created branches stay
+* mounted across toggles, preserving state, effects, and async resources.
+*
+* ```ts
+* show({ when: isLoading }, () => spinner({ color: "accent" }))
+*
+* show(
+*   { when: full },
+*   { when: isError, use: () => errorView() },
+*   () => resultView()
+* )
+* ```
+*/
+function show(...spec) {
+	return new Show(spec);
+}
+//#endregion
+export { show };
+
+//# sourceMappingURL=show.mjs.map

package/dist/widgets/show.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"show.mjs","names":["#state","#owner","#nodes"],"sources":["../../src/widgets/show.ts"],"sourcesContent":["import type { RenderCtx } from \"../core/ctx.ts\"\nimport type { Reactive } from \"../core/reactive.ts\"\n\nimport { Node } from \"../core/node.ts\"\nimport { untrack, unwrap, useActiveOwner, withOwner } from \"../core/reactive.ts\"\n\nexport type ShowGate = { when: Reactive<unknown> }\nexport type ShowBranch = { when: Reactive<unknown>; use: ShowChildren }\nexport type ShowChildren = () => Node | Node[]\nexport type ShowSpec = (ShowGate | ShowBranch)[] | [...(ShowGate | ShowBranch)[], ShowChildren]\n\ntype ShowState = {\n  when: Reactive<unknown>\n  use?: ShowChildren\n  children?: Node[]\n}\n\nexport type { Show }\n\n/** Conditional fragment backing `show()`. Branches are created lazily:\n * a `use` factory only runs the first time its condition wins. Once\n * created, the branch remains mounted and owned; inactive branches simply\n * don't participate in layout/rendering and contribute zero rows.\n *\n * Lazy factories run under the owner captured at `show()` creation time,\n * so context reads behave as if the branch had been constructed eagerly.\n */\nclass Show extends Node {\n  #state: ShowState[] = []\n  #owner = useActiveOwner()\n\n  constructor(spec: ShowSpec) {\n    super({})\n    let fallback = false\n    for (const s of spec) {\n      if (fallback) throw new Error(\"Show: `fallback` must be the final argument\")\n      if (typeof s === \"function\") {\n        this.#state.push({ use: s, when: true })\n        fallback = true\n      } else this.#state.push(s)\n    }\n  }\n\n  #nodes(s: ShowState, use: ShowChildren): Node[] {\n    if (s.children) return s.children\n    const create = () => untrack(use)\n    const nodes = this.#owner ? withOwner(this.#owner, create) : create()\n    s.children = Array.isArray(nodes) ? nodes : [nodes]\n    for (const c of s.children) this.add(c)\n    return s.children\n  }\n\n  override layoutChildren(): readonly Node[] {\n    for (const s of this.#state) {\n      const matches = unwrap(s.when)\n      if (s.use === undefined) {\n        if (!matches) return []\n        continue\n      } else if (!matches) continue\n      return this.#nodes(s, s.use)\n    }\n    return []\n  }\n\n  /** Standalone-render fallback. Box parents go through\n   *  `layoutChildren` and bypass this; only fires when `Show` sits\n   *  outside a layout container (root, overlay, etc.). */\n  protected async _render(ctx: RenderCtx): Promise<string[]> {\n    const targets = this.layoutChildren()\n    const rows = await Promise.all(targets.map((c) => c.render(ctx)))\n    return rows.flat()\n  }\n}\n\n/** Lazy conditional rendering.\n *\n * Specs are evaluated from left to right:\n * - `{ when }` is a guard. When false, rendering stops with no rows; when\n *   true, evaluation continues.\n * - `{ when, use }` is a conditional branch. The first branch whose\n *   condition is truthy is rendered.\n * - A final bare factory is the fallback branch and must be the last\n *   argument.\n *\n * Branch factories are lazy and run at most once. Created branches stay\n * mounted across toggles, preserving state, effects, and async resources.\n *\n * ```ts\n * show({ when: isLoading }, () => spinner({ color: \"accent\" }))\n *\n * show(\n *   { when: full },\n *   { when: isError, use: () => errorView() },\n *   () => resultView()\n * )\n * ```\n */\nexport function show(...spec: ShowSpec): Show {\n  return new Show(spec)\n}\n"],"mappings":";;;;;;;;;;;AA2BA,IAAM,OAAN,cAAmB,KAAK;CACtB,SAAsB,CAAC;CACvB,SAAS,eAAe;CAExB,YAAY,MAAgB;EAC1B,MAAM,CAAC,CAAC;EACR,IAAI,WAAW;EACf,KAAK,MAAM,KAAK,MAAM;GACpB,IAAI,UAAU,MAAM,IAAI,MAAM,6CAA6C;GAC3E,IAAI,OAAO,MAAM,YAAY;IAC3B,KAAKA,OAAO,KAAK;KAAE,KAAK;KAAG,MAAM;IAAK,CAAC;IACvC,WAAW;GACb,OAAO,KAAKA,OAAO,KAAK,CAAC;EAC3B;CACF;CAEA,OAAO,GAAc,KAA2B;EAC9C,IAAI,EAAE,UAAU,OAAO,EAAE;EACzB,MAAM,eAAe,QAAQ,GAAG;EAChC,MAAM,QAAQ,KAAKC,SAAS,UAAU,KAAKA,QAAQ,MAAM,IAAI,OAAO;EACpE,EAAE,WAAW,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;EAClD,KAAK,MAAM,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;EACtC,OAAO,EAAE;CACX;CAEA,iBAA2C;EACzC,KAAK,MAAM,KAAK,KAAKD,QAAQ;GAC3B,MAAM,UAAU,OAAO,EAAE,IAAI;GAC7B,IAAI,EAAE,QAAQ,KAAA,GAAW;IACvB,IAAI,CAAC,SAAS,OAAO,CAAC;IACtB;GACF,OAAO,IAAI,CAAC,SAAS;GACrB,OAAO,KAAKE,OAAO,GAAG,EAAE,GAAG;EAC7B;EACA,OAAO,CAAC;CACV;;;;CAKA,MAAgB,QAAQ,KAAmC;EACzD,MAAM,UAAU,KAAK,eAAe;EAEpC,QAAO,MADY,QAAQ,IAAI,QAAQ,KAAK,MAAM,EAAE,OAAO,GAAG,CAAC,CAAC,EAAA,CACpD,KAAK;CACnB;AACF;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,KAAK,GAAG,MAAsB;CAC5C,OAAO,IAAI,KAAK,IAAI;AACtB"}

package/dist/widgets/spinner.d.mts

@@ -0,0 +1,65 @@
+import { P as RenderCtx, X as State, nt as Reactive, p as Node } from "../queries-DH3bj74K.mjs";
+import { o as AnyStyle } from "../types-B9Eh7k2v.mjs";
+//#region src/widgets/spinner.d.ts
+/**
+ * Frame sets from the common terminal-spinner vocabulary. Pick one to taste.
+ * @internal
+ */
+declare const spinnerFrames: {
+  readonly arrow: readonly ["←", "↖", "↑", "↗", "→", "↘", "↓", "↙"];
+  readonly bouncingBar: readonly ["[    ]", "[=   ]", "[==  ]", "[=== ]", "[ ===]", "[  ==]", "[   =]", "[    ]"];
+  readonly circle: readonly ["◐", "◓", "◑", "◒"];
+  readonly dots: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  readonly line: readonly ["-", "\\", "|", "/"];
+};
+type SpinnerStyle = keyof typeof spinnerFrames;
+interface SpinnerState {
+  /** Frame glyphs, cycled in order. Defaults to `dots`. */
+  frames?: SpinnerStyle | readonly string[];
+  /** Foreground theme slot or explicit color. Defaults to `primary`. */
+  color?: Reactive<AnyStyle>;
+  /** Whether the animation is ticking. Defaults to `true`. Accepts a
+   *  signal accessor so callers can drive the spinner from shared
+   *  reactive state. Setting `false` stops the interval; setting
+   *  `true` restarts it. */
+  running?: Reactive<boolean>;
+  idle?: string;
+}
+/**
+ * An animated spinner. Its *frame* is always a pure function of wall
+ * time and `speed`:
+ *
+ * ```ts
+ * const idx = Spinner.tick(speed) % frames.length
+ * ```
+ *
+ * That means the visible frame only depends on how much time has
+ * actually elapsed, never on how often you happen to render. Two
+ * spinners with the same `speed` stay in lockstep even if only one of
+ * them gets invalidated.
+ *
+ * Each spinner owns an `unref()`'d interval while it is mounted,
+ * visible, and running. The interval is reconciled from reactive
+ * state/lifecycle, not from `_render`, so hiding a spinner stops it
+ * even though invisible nodes skip rendering. Forgetting to `.stop()`
+ * is harmless — the unref'd timer doesn't pin the event loop.
+ */
+declare class Spinner extends Node<SpinnerState> {
+  #private;
+  constructor(state: SpinnerState);
+  /** Global tick index for a given `speed`. Shared across all callers. */
+  static tick(speed: number): number;
+  /** Shorthand for `state.set({ running: true })`. */
+  start(): this;
+  /** Shorthand for `state.set({ running: false })`. */
+  stop(): this;
+  protected _render(ctx: RenderCtx): string[];
+}
+/**
+ * Factory for `Spinner`. All options are optional — a bare `spinner()`
+ * gives you the braille `dots` set at 80ms in the theme's `primary` color.
+ */
+declare function spinner(state?: State<SpinnerState>): Spinner;
+//#endregion
+export { Spinner, SpinnerState, SpinnerStyle, spinner, spinnerFrames };
+//# sourceMappingURL=spinner.d.mts.map

package/dist/widgets/spinner.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.d.mts","names":[],"sources":["../../src/widgets/spinner.ts"],"mappings":";;;;;;;cAaa;WACX;WACA;WACA;WACA;WACA;;KAGU,4BAA4B;UAEvB;;EAEf,SAAS;;EAET,QAAQ,SAAS;;;;;EAKjB,UAAU;EACV;;;;;;;;;;;;;;;;;;;;;cA4DW,gBAAgB,KAAK;;EAChC,YAAY,OAAO;;SAYZ,KAAK;;EAKZ;;EAMA;YAcU,QAAQ,KAAK;;;;;;iBAoBT,QAAQ,QAAO,MAAM,gBAAqB"}

package/dist/widgets/spinner.mjs

@@ -0,0 +1,147 @@
+import { S as unwrap, f as effect, x as untrack } from "../reactive-f7NpAi69.mjs";
+import { t as Node } from "../node-BZ7f6HzU.mjs";
+import { stringWidth } from "@zaly/shared/ansi";
+//#region src/widgets/spinner.ts
+/**
+* Frame sets from the common terminal-spinner vocabulary. Pick one to taste.
+* @internal
+*/
+const spinnerFrames = {
+	arrow: [
+		"←",
+		"↖",
+		"↑",
+		"↗",
+		"→",
+		"↘",
+		"↓",
+		"↙"
+	],
+	bouncingBar: [
+		"[    ]",
+		"[=   ]",
+		"[==  ]",
+		"[=== ]",
+		"[ ===]",
+		"[  ==]",
+		"[   =]",
+		"[    ]"
+	],
+	circle: [
+		"◐",
+		"◓",
+		"◑",
+		"◒"
+	],
+	dots: [
+		"⠋",
+		"⠙",
+		"⠹",
+		"⠸",
+		"⠼",
+		"⠴",
+		"⠦",
+		"⠧",
+		"⠇",
+		"⠏"
+	],
+	line: [
+		"-",
+		"\\",
+		"|",
+		"/"
+	]
+};
+const SPEED = 80;
+var Animator = class {
+	#timer;
+	#spinners = /* @__PURE__ */ new Set();
+	#start() {
+		if (this.#timer !== void 0) return;
+		this.#timer = untrack(() => setInterval(() => this.#spinners.forEach((s) => s.invalidate()), SPEED));
+		this.#timer.unref();
+	}
+	#stop() {
+		if (this.#timer === void 0) return;
+		clearInterval(this.#timer);
+		this.#timer = void 0;
+	}
+	add(node) {
+		if (this.#spinners.has(node)) return;
+		this.#spinners.add(node);
+		this.#start();
+	}
+	del(node) {
+		if (!this.#spinners.has(node)) return;
+		this.#spinners.delete(node);
+		if (this.#spinners.size === 0) this.#stop();
+	}
+};
+const animator = new Animator();
+/**
+* An animated spinner. Its *frame* is always a pure function of wall
+* time and `speed`:
+*
+* ```ts
+* const idx = Spinner.tick(speed) % frames.length
+* ```
+*
+* That means the visible frame only depends on how much time has
+* actually elapsed, never on how often you happen to render. Two
+* spinners with the same `speed` stay in lockstep even if only one of
+* them gets invalidated.
+*
+* Each spinner owns an `unref()`'d interval while it is mounted,
+* visible, and running. The interval is reconciled from reactive
+* state/lifecycle, not from `_render`, so hiding a spinner stops it
+* even though invisible nodes skip rendering. Forgetting to `.stop()`
+* is harmless — the unref'd timer doesn't pin the event loop.
+*/
+var Spinner = class Spinner extends Node {
+	constructor(state) {
+		super(state);
+		this.on("mount", () => this.#check());
+		this.on("unmount", () => animator.del(this));
+		effect(() => this.#check());
+	}
+	/** Global tick index for a given `speed`. Shared across all callers. */
+	static tick(speed) {
+		return Math.floor(performance.now() / speed);
+	}
+	/** Shorthand for `state.set({ running: true })`. */
+	start() {
+		this.state.set({ running: true });
+		return this;
+	}
+	/** Shorthand for `state.set({ running: false })`. */
+	stop() {
+		this.state.set({ running: false });
+		return this;
+	}
+	/** Sync the interval to the current `running` state. Reading through
+	*  `unwrap` during a render subscribes the spinner to a signal
+	*  accessor so flips from elsewhere in the app retrigger this. */
+	#check() {
+		if (!(unwrap(this.state.running ?? true) && this.visible && this.mounted)) return animator.del(this);
+		animator.add(this);
+	}
+	_render(ctx) {
+		const f = this.state.frames;
+		const frames = (typeof f === "string" ? spinnerFrames[f] : f) ?? spinnerFrames.dots;
+		let frame = frames[Spinner.tick(SPEED) % frames.length];
+		if (!unwrap(this.state.running ?? true)) frame = (this.state.idle ?? " ").repeat(stringWidth(frame));
+		const color = this.state.color ?? "primary";
+		return [ctx.style.add(unwrap(color))(frame)];
+	}
+};
+/**
+* Factory for `Spinner`. All options are optional — a bare `spinner()`
+* gives you the braille `dots` set at 80ms in the theme's `primary` color.
+*/
+function spinner(state = {}) {
+	return new Spinner(state);
+}
+//#endregion
+export { Spinner, spinner, spinnerFrames };
+
+//# sourceMappingURL=spinner.mjs.map

package/dist/widgets/spinner.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"spinner.mjs","names":["#timer","#spinners","#start","#stop","#check"],"sources":["../../src/widgets/spinner.ts"],"sourcesContent":["import type { RenderCtx } from \"../core/ctx.ts\"\nimport type { Reactive } from \"../core/reactive.ts\"\nimport type { State } from \"../core/state.ts\"\nimport type { AnyStyle } from \"../style/types.ts\"\n\nimport { stringWidth } from \"@zaly/shared/ansi\"\nimport { Node } from \"../core/node.ts\"\nimport { effect, untrack, unwrap } from \"../core/reactive.ts\"\n\n/**\n * Frame sets from the common terminal-spinner vocabulary. Pick one to taste.\n * @internal\n */\nexport const spinnerFrames = {\n  arrow: [\"←\", \"↖\", \"↑\", \"↗\", \"→\", \"↘\", \"↓\", \"↙\"],\n  bouncingBar: [\"[    ]\", \"[=   ]\", \"[==  ]\", \"[=== ]\", \"[ ===]\", \"[  ==]\", \"[   =]\", \"[    ]\"],\n  circle: [\"◐\", \"◓\", \"◑\", \"◒\"],\n  dots: [\"⠋\", \"⠙\", \"⠹\", \"⠸\", \"⠼\", \"⠴\", \"⠦\", \"⠧\", \"⠇\", \"⠏\"],\n  line: [\"-\", \"\\\\\", \"|\", \"/\"],\n} as const\n\nexport type SpinnerStyle = keyof typeof spinnerFrames\n\nexport interface SpinnerState {\n  /** Frame glyphs, cycled in order. Defaults to `dots`. */\n  frames?: SpinnerStyle | readonly string[]\n  /** Foreground theme slot or explicit color. Defaults to `primary`. */\n  color?: Reactive<AnyStyle>\n  /** Whether the animation is ticking. Defaults to `true`. Accepts a\n   *  signal accessor so callers can drive the spinner from shared\n   *  reactive state. Setting `false` stops the interval; setting\n   *  `true` restarts it. */\n  running?: Reactive<boolean>\n  idle?: string\n}\n\nconst SPEED = 80\n\nclass Animator {\n  #timer?: ReturnType<typeof setInterval>\n  #spinners = new Set<Spinner>()\n\n  #start(): void {\n    if (this.#timer !== undefined) return\n    // `untracked` so the interval callback doesn't inherit the render's tracking ctx.\n    this.#timer = untrack(() =>\n      setInterval(() => this.#spinners.forEach((s) => s.invalidate()), SPEED)\n    )\n    // Don't pin the event loop — a forgotten spinner should never\n    // prevent the process from exiting.\n    this.#timer.unref()\n  }\n\n  #stop(): void {\n    if (this.#timer === undefined) return\n    clearInterval(this.#timer)\n    this.#timer = undefined\n  }\n\n  add(node: Spinner) {\n    if (this.#spinners.has(node)) return\n    this.#spinners.add(node)\n    this.#start()\n  }\n\n  del(node: Spinner) {\n    if (!this.#spinners.has(node)) return\n    this.#spinners.delete(node)\n    if (this.#spinners.size === 0) this.#stop()\n  }\n}\n\nconst animator = new Animator()\n\n/**\n * An animated spinner. Its *frame* is always a pure function of wall\n * time and `speed`:\n *\n * ```ts\n * const idx = Spinner.tick(speed) % frames.length\n * ```\n *\n * That means the visible frame only depends on how much time has\n * actually elapsed, never on how often you happen to render. Two\n * spinners with the same `speed` stay in lockstep even if only one of\n * them gets invalidated.\n *\n * Each spinner owns an `unref()`'d interval while it is mounted,\n * visible, and running. The interval is reconciled from reactive\n * state/lifecycle, not from `_render`, so hiding a spinner stops it\n * even though invisible nodes skip rendering. Forgetting to `.stop()`\n * is harmless — the unref'd timer doesn't pin the event loop.\n */\nexport class Spinner extends Node<SpinnerState> {\n  constructor(state: SpinnerState) {\n    super(state)\n    // Timer lifecycle is driven by mount + reactive state, not `_render`:\n    // invisible nodes skip rendering, but still need their interval stopped.\n    // Unmount always clears.\n    this.on(\"mount\", () => this.#check())\n    this.on(\"unmount\", () => animator.del(this))\n\n    effect(() => this.#check())\n  }\n\n  /** Global tick index for a given `speed`. Shared across all callers. */\n  static tick(speed: number): number {\n    return Math.floor(performance.now() / speed)\n  }\n\n  /** Shorthand for `state.set({ running: true })`. */\n  start(): this {\n    this.state.set({ running: true })\n    return this\n  }\n\n  /** Shorthand for `state.set({ running: false })`. */\n  stop(): this {\n    this.state.set({ running: false })\n    return this\n  }\n\n  /** Sync the interval to the current `running` state. Reading through\n   *  `unwrap` during a render subscribes the spinner to a signal\n   *  accessor so flips from elsewhere in the app retrigger this. */\n  #check(): void {\n    const enabled = unwrap(this.state.running ?? true) && this.visible && this.mounted // track\n    if (!enabled) return animator.del(this)\n    animator.add(this)\n  }\n\n  protected _render(ctx: RenderCtx): string[] {\n    const f = this.state.frames\n    const frames = (typeof f === \"string\" ? spinnerFrames[f] : f) ?? spinnerFrames.dots\n    let frame = frames[Spinner.tick(SPEED) % frames.length]\n    // When stopped, hold the slot open with blank space of the same\n    // cell width so surrounding layout doesn't jump as the spinner\n    // toggles. Stable-width frame sets (dots, line, circle) look the\n    // same; variable sets (bouncingBar) pick the longest frame's\n    // width so stops after a short frame still hold full space.\n    if (!unwrap(this.state.running ?? true))\n      frame = (this.state.idle ?? \" \").repeat(stringWidth(frame))\n    const color = this.state.color ?? \"primary\"\n    return [ctx.style.add(unwrap(color))(frame)]\n  }\n}\n\n/**\n * Factory for `Spinner`. All options are optional — a bare `spinner()`\n * gives you the braille `dots` set at 80ms in the theme's `primary` color.\n */\nexport function spinner(state: State<SpinnerState> = {}): Spinner {\n  return new Spinner(state)\n}\n"],"mappings":";;;;;;;;AAaA,MAAa,gBAAgB;CAC3B,OAAO;EAAC;EAAK;EAAK;EAAK;EAAK;EAAK;EAAK;EAAK;CAAG;CAC9C,aAAa;EAAC;EAAU;EAAU;EAAU;EAAU;EAAU;EAAU;EAAU;CAAQ;CAC5F,QAAQ;EAAC;EAAK;EAAK;EAAK;CAAG;CAC3B,MAAM;EAAC;EAAK;EAAK;EAAK;EAAK;EAAK;EAAK;EAAK;EAAK;EAAK;CAAG;CACvD,MAAM;EAAC;EAAK;EAAM;EAAK;CAAG;AAC5B;AAiBA,MAAM,QAAQ;AAEd,IAAM,WAAN,MAAe;CACb;CACA,4BAAY,IAAI,IAAa;CAE7B,SAAe;EACb,IAAI,KAAKA,WAAW,KAAA,GAAW;EAE/B,KAAKA,SAAS,cACZ,kBAAkB,KAAKC,UAAU,SAAS,MAAM,EAAE,WAAW,CAAC,GAAG,KAAK,CACxE;EAGA,KAAKD,OAAO,MAAM;CACpB;CAEA,QAAc;EACZ,IAAI,KAAKA,WAAW,KAAA,GAAW;EAC/B,cAAc,KAAKA,MAAM;EACzB,KAAKA,SAAS,KAAA;CAChB;CAEA,IAAI,MAAe;EACjB,IAAI,KAAKC,UAAU,IAAI,IAAI,GAAG;EAC9B,KAAKA,UAAU,IAAI,IAAI;EACvB,KAAKC,OAAO;CACd;CAEA,IAAI,MAAe;EACjB,IAAI,CAAC,KAAKD,UAAU,IAAI,IAAI,GAAG;EAC/B,KAAKA,UAAU,OAAO,IAAI;EAC1B,IAAI,KAAKA,UAAU,SAAS,GAAG,KAAKE,MAAM;CAC5C;AACF;AAEA,MAAM,WAAW,IAAI,SAAS;;;;;;;;;;;;;;;;;;;;AAqB9B,IAAa,UAAb,MAAa,gBAAgB,KAAmB;CAC9C,YAAY,OAAqB;EAC/B,MAAM,KAAK;EAIX,KAAK,GAAG,eAAe,KAAKC,OAAO,CAAC;EACpC,KAAK,GAAG,iBAAiB,SAAS,IAAI,IAAI,CAAC;EAE3C,aAAa,KAAKA,OAAO,CAAC;CAC5B;;CAGA,OAAO,KAAK,OAAuB;EACjC,OAAO,KAAK,MAAM,YAAY,IAAI,IAAI,KAAK;CAC7C;;CAGA,QAAc;EACZ,KAAK,MAAM,IAAI,EAAE,SAAS,KAAK,CAAC;EAChC,OAAO;CACT;;CAGA,OAAa;EACX,KAAK,MAAM,IAAI,EAAE,SAAS,MAAM,CAAC;EACjC,OAAO;CACT;;;;CAKA,SAAe;EAEb,IAAI,EADY,OAAO,KAAK,MAAM,WAAW,IAAI,KAAK,KAAK,WAAW,KAAK,UAC7D,OAAO,SAAS,IAAI,IAAI;EACtC,SAAS,IAAI,IAAI;CACnB;CAEA,QAAkB,KAA0B;EAC1C,MAAM,IAAI,KAAK,MAAM;EACrB,MAAM,UAAU,OAAO,MAAM,WAAW,cAAc,KAAK,MAAM,cAAc;EAC/E,IAAI,QAAQ,OAAO,QAAQ,KAAK,KAAK,IAAI,OAAO;EAMhD,IAAI,CAAC,OAAO,KAAK,MAAM,WAAW,IAAI,GACpC,SAAS,KAAK,MAAM,QAAQ,IAAA,CAAK,OAAO,YAAY,KAAK,CAAC;EAC5D,MAAM,QAAQ,KAAK,MAAM,SAAS;EAClC,OAAO,CAAC,IAAI,MAAM,IAAI,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;CAC7C;AACF;;;;;AAMA,SAAgB,QAAQ,QAA6B,CAAC,GAAY;CAChE,OAAO,IAAI,QAAQ,KAAK;AAC1B"}

package/dist/widgets/text.d.mts

@@ -0,0 +1,2 @@
+import { G as text, H as Text, K as textContent, U as TextContent, W as TextStyle } from "../queries-DH3bj74K.mjs";
+export { Text, TextContent, TextStyle, text, textContent };

package/dist/widgets/text.mjs

@@ -0,0 +1,32 @@
+import { S as unwrap } from "../reactive-f7NpAi69.mjs";
+import { t as Node } from "../node-BZ7f6HzU.mjs";
+import { calcLayout, formatText } from "../text.mjs";
+//#region src/widgets/text.ts
+var Text = class extends Node {
+	async _render(ctx) {
+		return formatText(await textContent(this.state.content, ctx), {
+			style: ctx.style.add(this.state),
+			width: ctx.width,
+			wrap: this.state.wrap
+		});
+	}
+	async layout(ctx) {
+		return calcLayout(await textContent(this.state.content, ctx), { wrap: this.state.wrap });
+	}
+};
+async function textContent(content, ctx) {
+	if (content === void 0) return;
+	const raw = unwrap(content);
+	return unwrap(typeof raw === "string" ? raw : await raw(ctx));
+}
+function text(first, style) {
+	if (typeof first === "string" || typeof first === "function") return new Text({
+		content: first,
+		...style
+	});
+	return new Text(first);
+}
+//#endregion
+export { Text, text, textContent };
+
+//# sourceMappingURL=text.mjs.map

package/dist/widgets/text.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"text.mjs","names":[],"sources":["../../src/widgets/text.ts"],"sourcesContent":["import type { MaybePromise } from \"@zaly/shared\"\nimport type { RenderCtx } from \"../core/ctx.ts\"\nimport type { Reactive } from \"../core/reactive.ts\"\nimport type { State } from \"../core/state.ts\"\nimport type { Style } from \"../style/types.ts\"\n\nimport { Node } from \"../core/node.ts\"\nimport { unwrap } from \"../core/reactive.ts\"\nimport { calcLayout, formatText } from \"../layout/text.ts\"\n\n/**\n * Text content — three forms, resolved at render time:\n *\n *   1. Plain string — static content.\n *   2. Reactive accessor (`signal()` / `memo()`) — re-reads on each\n *      render and subscribes the node so signal writes invalidate.\n *   3. `(ctx) => string` — computed from the render context. Use this\n *      for inline-styled spans via `ctx.style`.\n *\n * Branded accessors are picked up via `isAccessor`; any other function\n * is treated as the ctx-aware form. Plain strings pass through.\n *\n * ```ts\n * text(\"hello\")\n * text(name)                                  // signal accessor\n * text(({ style }) => style.ok(`✓ ${count}`)) // ctx-aware\n * ```\n */\nexport type TextContent = Reactive<string> | ((ctx: RenderCtx) => MaybePromise<Reactive<string>>)\n\nexport interface TextStyle extends Style {\n  content: TextContent\n  wrap?: \"word\" | \"char\" | \"none\"\n}\n\nexport class Text extends Node<TextStyle> {\n  protected async _render(ctx: RenderCtx): Promise<string[]> {\n    const content = await textContent(this.state.content, ctx)\n    return formatText(content, {\n      style: ctx.style.add(this.state),\n      width: ctx.width,\n      wrap: this.state.wrap,\n    })\n  }\n\n  override async layout(ctx: RenderCtx) {\n    return calcLayout(await textContent(this.state.content, ctx), { wrap: this.state.wrap })\n  }\n}\n\nexport function textContent(content: TextContent, ctx: RenderCtx): Promise<string>\nexport function textContent(content: TextContent | undefined, ctx: RenderCtx): Promise<undefined>\nexport async function textContent(\n  content: TextContent | undefined,\n  ctx: RenderCtx\n): Promise<string | undefined> {\n  if (content === undefined) return\n  const raw = unwrap(content)\n  return unwrap(typeof raw === \"string\" ? raw : await raw(ctx))\n}\n\n/**\n * Factory for `Text`. Content can be a plain string or a `(ctx) => string`\n * function that's called at render time — use the function form when you\n * want inline-styled spans via `ctx.style`.\n *\n * ```ts\n * text(\"hello\")\n * text(\"hello\", { fg: \"primary\", bold: true })\n * text({ content: \"hello\", fg: \"primary\" })\n * text(({ style }) => `ok: ${style.ok(\"yes\")}`)\n * ```\n */\nexport function text(content: TextContent, style?: Omit<State<TextStyle>, \"content\">): Text\nexport function text(style: State<TextStyle>): Text\nexport function text(\n  first: TextContent | State<TextStyle>,\n  style?: Omit<State<TextStyle>, \"content\">\n): Text {\n  // TextContent: string | function (incl. reactive accessor) | …\n  // TextStyle:   plain object with a `content` field.\n  // The TextStyle branch is picked only when `first` is a non-function\n  // object — accessors are functions, so they go through the content path.\n  if (typeof first === \"string\" || typeof first === \"function\") {\n    return new Text({ content: first, ...style })\n  }\n  return new Text(first)\n}\n"],"mappings":";;;;AAmCA,IAAa,OAAb,cAA0B,KAAgB;CACxC,MAAgB,QAAQ,KAAmC;EAEzD,OAAO,WAAW,MADI,YAAY,KAAK,MAAM,SAAS,GAAG,GAC9B;GACzB,OAAO,IAAI,MAAM,IAAI,KAAK,KAAK;GAC/B,OAAO,IAAI;GACX,MAAM,KAAK,MAAM;EACnB,CAAC;CACH;CAEA,MAAe,OAAO,KAAgB;EACpC,OAAO,WAAW,MAAM,YAAY,KAAK,MAAM,SAAS,GAAG,GAAG,EAAE,MAAM,KAAK,MAAM,KAAK,CAAC;CACzF;AACF;AAIA,eAAsB,YACpB,SACA,KAC6B;CAC7B,IAAI,YAAY,KAAA,GAAW;CAC3B,MAAM,MAAM,OAAO,OAAO;CAC1B,OAAO,OAAO,OAAO,QAAQ,WAAW,MAAM,MAAM,IAAI,GAAG,CAAC;AAC9D;AAgBA,SAAgB,KACd,OACA,OACM;CAKN,IAAI,OAAO,UAAU,YAAY,OAAO,UAAU,YAChD,OAAO,IAAI,KAAK;EAAE,SAAS;EAAO,GAAG;CAAM,CAAC;CAE9C,OAAO,IAAI,KAAK,KAAK;AACvB"}