@nan0web/ui 1.0.0

package/src/core/Message/Message.js

@@ -0,0 +1,77 @@
+import { Message as BaseMessage } from "@nan0web/co"
+
+/**
+ * Base UI message class.
+ *
+ * @class UIMessage
+ * @extends BaseMessage
+ */
+class UIMessage extends BaseMessage {
+	static TYPES = {
+		TEXT: 'text',
+		FORM: 'form',
+		PROGRESS: 'progress',
+		ERROR: 'error',
+		INFO: 'info',
+		SUCCESS: 'success',
+		WARNING: 'warning',
+		COMMAND: 'command',
+		NAVIGATION: 'navigation'
+	}
+
+	/** @type {string} */
+	type = ""
+	/** @type {string} */
+	id = ""
+
+	/**
+	 * Creates a UIMessage.
+	 *
+	 * @param {Object} [input={}] - Message properties.
+	 */
+	constructor(input = {}) {
+		super(input)
+
+		const {
+			type = this.type,
+			id = this.id,
+		} = input
+		this.id = id || `ui-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+		this.type = String(type)
+
+		if (!('body' in input) && 'content' in input) {
+			this.body = Array.isArray(input.content) ? input.content : [input.content]
+		}
+	}
+
+	/**
+	 * Creates a UIMessage instance from plain data.
+	 *
+	 * @param {Object} data - Message data.
+	 * @returns {UIMessage}
+	 */
+	static from(data) {
+		if (data instanceof UIMessage) return data
+		return new this(data)
+	}
+
+	/**
+	 * Checks if the message type is valid.
+	 *
+	 * @returns {boolean}
+	 */
+	isValidType() {
+		return Object.values(UIMessage.TYPES).includes(this.type)
+	}
+
+	/**
+	 * Checks whether the message contains any body content.
+	 *
+	 * @returns {boolean}
+	 */
+	isEmpty() {
+		return !this.body || this.body.length === 0
+	}
+}
+
+export default UIMessage

package/src/core/Message/Message.test.js

@@ -0,0 +1,58 @@
+import { describe, it } from "node:test"
+import { strict as assert } from "node:assert"
+import UIMessage from "./Message.js"
+
+describe("UIMessage", () => {
+	it("should create instance with default values", () => {
+		const msg = new UIMessage()
+		assert.ok(msg instanceof UIMessage)
+		assert.equal(typeof msg.type, "string")
+		assert.equal(typeof msg.id, "string")
+		assert.ok(msg.time instanceof Date)
+	})
+
+	it("should create instance with custom values", () => {
+		const props = {
+			type: "test",
+			id: "custom-id",
+			body: ["test content"]
+		}
+		const msg = new UIMessage(props)
+		assert.equal(msg.type, "test")
+		assert.equal(msg.id, "custom-id")
+		assert.deepEqual(msg.body, ["test content"])
+	})
+
+	it("should generate unique id when not provided", () => {
+		const msg1 = new UIMessage()
+		const msg2 = new UIMessage()
+		assert.notEqual(msg1.id, msg2.id)
+	})
+
+	it("should use content as body when body not provided", () => {
+		const msg = new UIMessage({ content: ["hello"] })
+		assert.deepEqual(msg.body, ["hello"])
+	})
+
+	it("should create from data using from() method", () => {
+		const data = { type: "info", body: ["test"] }
+		const msg = UIMessage.from(data)
+		assert.ok(msg instanceof UIMessage)
+		assert.equal(msg.type, "info")
+		assert.deepEqual(msg.body, ["test"])
+	})
+
+	it("should validate type correctly", () => {
+		const validMsg = new UIMessage({ type: UIMessage.TYPES.TEXT })
+		const invalidMsg = new UIMessage({ type: "invalid-type" })
+		assert.ok(validMsg.isValidType())
+		assert.ok(!invalidMsg.isValidType())
+	})
+
+	it("should check if message is empty", () => {
+		const emptyMsg = new UIMessage()
+		const nonEmptyMsg = new UIMessage({ body: ["content"] })
+		assert.ok(emptyMsg.isEmpty())
+		assert.ok(!nonEmptyMsg.isEmpty())
+	})
+})

package/src/core/Message/OutputMessage.js

@@ -0,0 +1,143 @@
+import UIMessage from "./Message.js"
+
+/**
+ * OutputMessage – message sent from the system to the UI.
+ *
+ * @class OutputMessage
+ * @extends UIMessage
+ */
+export default class OutputMessage extends UIMessage {
+	static PRIORITY = {
+		LOW: 0,
+		NORMAL: 1,
+		HIGH: 2,
+		CRITICAL: 3
+	}
+
+	/** @type {string[]} */
+	body
+	/** @type {Object} */
+	meta = {}
+	/** @type {Error|null} */
+	error = null
+	/** @type {number} */
+	priority = OutputMessage.PRIORITY.NORMAL
+
+	/**
+	 * Creates an OutputMessage.
+	 *
+	 * @param {Object} [input={}] - Message properties.
+	 */
+	constructor(input = {}) {
+		super(input)
+
+		const {
+			content = [],
+			body = [],
+			meta = {},
+			error = null,
+			priority = OutputMessage.PRIORITY.NORMAL
+		} = input
+
+		const contentSource = 'body' in input ? body :
+			'content' in input ? content : []
+
+		this.body = Array.isArray(contentSource) ?
+			contentSource :
+			(contentSource ? [String(contentSource)] : [])
+
+		this.meta = meta
+		this.error = error instanceof Error ? error :
+			error ? new Error(String(error)) : null
+		this.priority = Number(priority)
+
+		if (!this.type && this.error) {
+			this.type = UIMessage.TYPES.ERROR
+		} else if (!this.type) {
+			this.type = UIMessage.TYPES.INFO
+		}
+	}
+
+	/** @returns {string[]} */
+	get content() {
+		return this.body
+	}
+	/** @param {string[]|string} value */
+	set content(value) {
+		this.body = Array.isArray(value) ? value : [String(value)]
+	}
+	/** @returns {number} */
+	get size() {
+		return this.content.length
+	}
+	/** @returns {boolean} */
+	get isError() {
+		return this.error !== null || this.type === UIMessage.TYPES.ERROR
+	}
+	/** @returns {boolean} */
+	get isInfo() {
+		return this.type === UIMessage.TYPES.INFO || this.type === UIMessage.TYPES.SUCCESS
+	}
+
+	/**
+	 * Combines multiple messages into a new one.
+	 *
+	 * @param {...OutputMessage} messages - Messages to combine.
+	 * @returns {OutputMessage}
+	 */
+	combine(...messages) {
+		const combinedContent = [...this.content]
+		let combinedMeta = { ...this.meta }
+		let combinedError = this.error
+		let combinedPriority = this.priority
+
+		messages.forEach(msg => {
+			if (msg instanceof OutputMessage) {
+				combinedContent.push(...msg.content)
+				combinedMeta = { ...combinedMeta, ...msg.meta }
+				if (msg.error) combinedError = msg.error
+				combinedPriority = Math.max(combinedPriority, msg.priority)
+			}
+		})
+
+		return new OutputMessage({
+			content: combinedContent,
+			meta: combinedMeta,
+			error: combinedError,
+			priority: combinedPriority,
+			type: this.type
+		})
+	}
+
+	/**
+	 * Serialises the message to a plain JSON object.
+	 *
+	 * @returns {Object}
+	 */
+	toJSON() {
+		return {
+			body: this.body,
+			content: this.content,
+			meta: this.meta,
+			type: this.type,
+			id: this.id,
+			time: this.time.toISOString(),
+			error: this.error ? {
+				message: this.error.message,
+				stack: this.error.stack
+			} : null,
+			priority: this.priority
+		}
+	}
+
+	/**
+	 * Creates an OutputMessage from plain input.
+	 *
+	 * @param {Object} input - Message data.
+	 * @returns {OutputMessage}
+	 */
+	static from(input) {
+		if (input instanceof OutputMessage) return input
+		return new OutputMessage(input)
+	}
+}

package/src/core/Message/OutputMessage.test.js

@@ -0,0 +1,61 @@
+import { describe, it } from "node:test"
+import { strict as assert } from "node:assert"
+import OutputMessage from "./OutputMessage.js"
+
+describe("OutputMessage", () => {
+	it("should create instance with default values", () => {
+		const msg = new OutputMessage()
+		assert.ok(msg instanceof OutputMessage)
+		assert.deepEqual(msg.body, [])
+		assert.deepEqual(msg.meta, {})
+		assert.equal(msg.error, null)
+		assert.equal(msg.priority, OutputMessage.PRIORITY.NORMAL)
+	})
+
+	it("should create instance with custom values", () => {
+		const props = {
+			content: ["test content"],
+			meta: { key: "value" },
+			error: new Error("test error"),
+			priority: OutputMessage.PRIORITY.HIGH
+		}
+		const msg = new OutputMessage(props)
+		assert.deepEqual(msg.content, ["test content"])
+		assert.deepEqual(msg.meta, { key: "value" })
+		assert.ok(msg.error instanceof Error)
+		assert.equal(msg.priority, OutputMessage.PRIORITY.HIGH)
+	})
+
+	it("should set type based on error presence", () => {
+		const errorMsg = new OutputMessage({ error: "error occurred" })
+		const infoMsg = new OutputMessage({ content: ["info"] })
+		assert.equal(errorMsg.type, "error")
+		assert.equal(infoMsg.type, "info")
+	})
+
+	it("should handle string content", () => {
+		const msg = new OutputMessage({ content: "single string" })
+		assert.deepEqual(msg.content, ["single string"])
+	})
+
+	it("should combine messages", () => {
+		const msg1 = new OutputMessage({ content: ["part1"], priority: 1 })
+		const msg2 = new OutputMessage({ content: ["part2"], priority: 2 })
+		const combined = msg1.combine(msg2)
+		assert.deepEqual(combined.content, ["part1", "part2"])
+		assert.equal(combined.priority, 2)
+	})
+
+	it("should convert to JSON", () => {
+		const msg = new OutputMessage({ 
+			content: ["test"],
+			meta: { test: true },
+			error: new Error("test error")
+		})
+		const json = msg.toJSON()
+		assert.ok(json.body)
+		assert.ok(json.meta)
+		assert.ok(json.error)
+		assert.ok(json.time)
+	})
+})

package/src/core/Message/index.js

@@ -0,0 +1,7 @@
+import UIMessage from "./Message.js"
+import InputMessage from "./InputMessage.js"
+import OutputMessage from "./OutputMessage.js"
+
+export { UIMessage, InputMessage, OutputMessage }
+
+export default UIMessage

package/src/core/OutputAdapter.js

@@ -0,0 +1,50 @@
+import Event from '@nan0web/event/oop'
+import OutputMessage from './Message/OutputMessage.js'
+import FormMessage from './Form/Message.js'
+
+/**
+ * Abstract output adapter for UI implementations.
+ *
+ * @class OutputAdapter
+ * @extends Event
+ */
+class OutputAdapter extends Event {
+	/**
+	 * Renders a message to the user.
+	 *
+	 * @param {OutputMessage|FormMessage} message - Message to render.
+	 * @throws {Error} If not overridden by a subclass.
+	 */
+	render(message) {
+		throw new Error("render() must be implemented by subclass")
+	}
+
+	/**
+	 * Shows progress of a long‑running operation.
+	 *
+	 * @param {number} progress - Progress value in range 0‑1.
+	 * @param {Object} [metadata={}] - Additional metadata.
+	 * @returns {void}
+	 */
+	progress(progress, metadata = {}) {
+		this.render(OutputMessage.from({
+			content: [],
+			metadata: {
+				...metadata,
+				progress,
+				elementType: "progress"
+			}
+		}))
+	}
+
+	/**
+	 * Stops the output stream. Default implementation does nothing.
+	 *
+	 * @returns {void}
+	 */
+	stop() {
+		// Default implementation – does nothing
+	}
+}
+
+export default OutputAdapter

package/src/core/OutputAdapter.test.js

@@ -0,0 +1,35 @@
+import { describe, it } from "node:test"
+import { strict as assert } from "node:assert"
+import OutputAdapter from "./OutputAdapter.js"
+
+describe("OutputAdapter", () => {
+	it("should create instance", () => {
+		const adapter = new OutputAdapter()
+		assert.ok(adapter instanceof OutputAdapter)
+	})
+
+	it("should throw error on render method", () => {
+		const adapter = new OutputAdapter()
+		assert.throws(() => adapter.render(), {
+			message: "render() must be implemented by subclass"
+		})
+	})
+
+	it("should call render on progress", () => {
+		const adapter = new OutputAdapter()
+		let rendered = false
+		
+		// Override render for test
+		adapter.render = () => {
+			rendered = true
+		}
+		
+		adapter.progress(0.5)
+		assert.ok(rendered)
+	})
+
+	it("should stop without error", () => {
+		const adapter = new OutputAdapter()
+		assert.doesNotThrow(() => adapter.stop())
+	})
+})

package/src/core/Stream.js

@@ -0,0 +1,71 @@
+import StreamEntry from "./StreamEntry.js"
+
+/**
+ * Agnostic UI stream for processing progress.
+ *
+ * @class UIStream
+ */
+export default class UIStream {
+	/**
+	 * Creates an async generator that runs the supplied processor function.
+	 *
+	 * @param {AbortSignal} signal - Abort signal.
+	 * @param {() => Promise<StreamEntry>} processorFn - Async function that returns a result.
+	 * @returns {() => AsyncGenerator<StreamEntry>} Async generator function.
+	 */
+	static createProcessor(signal, processorFn) {
+		return async function* () {
+			try {
+				const result = await processorFn()
+				yield result
+			} catch (/** @type {any} */ error) {
+				if (error.name === 'AbortError') {
+					yield StreamEntry.from({ done: true, cancelled: true })
+				} else {
+					yield StreamEntry.from({ error: error.message })
+				}
+			}
+		}
+	}
+
+	/**
+	 * Runs a generator with progress callbacks and abort handling.
+	 *
+	 * @param {AbortSignal} signal - Abort signal.
+	 * @param {Function} generator - Function returning an async iterator.
+	 * @param {Function} [onProgress] - Called with (progress, item).
+	 * @param {Function} [onError] - Called with (errorMessage, item).
+	 * @param {Function} [onComplete] - Called with (item) when done.
+	 * @returns {Promise<void>}
+	 */
+	static async process(signal, generator, onProgress, onError, onComplete) {
+		const iter = generator()
+
+		try {
+			for await (const item of iter) {
+				if (signal.aborted) {
+					throw new DOMException('Aborted', 'AbortError')
+				}
+
+				if (item.progress !== undefined) {
+					onProgress?.(item.progress, item)
+				} else if (item.error) {
+					onError?.(item.error, item)
+				} else if (item.done) {
+					onComplete?.(item)
+					break
+				} else {
+					// Intermediate results
+					onProgress?.(null, item)
+				}
+			}
+		} catch (/** @type {any} */ error) {
+			if (error.name === 'AbortError') {
+				onComplete?.({ cancelled: true })
+			} else {
+				onError?.(error.message)
+			}
+			throw error
+		}
+	}
+}

package/src/core/Stream.test.js

@@ -0,0 +1,78 @@
+import { describe, it } from "node:test"
+import { strict as assert } from "node:assert"
+import UIStream from "./Stream.js"
+import StreamEntry from "./StreamEntry.js"
+
+describe("UIStream", () => {
+	it("should create processor generator", async () => {
+		const controller = new AbortController()
+		const processorFn = () => Promise.resolve("test result")
+		const generator = UIStream.createProcessor(controller.signal, processorFn)
+
+		assert.equal(typeof generator, "function")
+
+		for await (const item of generator()) {
+			assert.equal(item, "test result")
+			break
+		}
+	})
+
+	it("should handle aborted signal", async () => {
+		const controller = new AbortController()
+		controller.abort()
+
+		const processorFn = () => Promise.resolve(StreamEntry.from({ value: "Hello", done: true }))
+		const generator = UIStream.createProcessor(controller.signal, processorFn)
+
+		for await (const item of generator()) {
+			assert.deepEqual(item, StreamEntry.from({ done: true, value: "Hello" }))
+			break
+		}
+	})
+
+	it("should process stream with callbacks", async () => {
+		const controller = new AbortController()
+		let progressCalled = false
+		let completeCalled = false
+
+		const generatorFn = async function* () {
+			yield StreamEntry.from({ progress: 0.5 })
+			yield StreamEntry.from({ done: true })
+		}
+
+		const onProgress = () => { progressCalled = true }
+		const onComplete = () => { completeCalled = true }
+
+		await UIStream.process(
+			controller.signal,
+			generatorFn,
+			onProgress,
+			null,
+			onComplete
+		)
+
+		assert.ok(progressCalled)
+		assert.ok(completeCalled)
+	})
+
+	it("should handle errors in stream processing", async () => {
+		const controller = new AbortController()
+		let errorCalled = false
+
+		const generatorFn = async function* () {
+			yield { error: "test error" }
+		}
+
+		const onError = () => { errorCalled = true }
+
+		await UIStream.process(
+			controller.signal,
+			generatorFn,
+			null,
+			onError,
+			null
+		)
+
+		assert.ok(errorCalled)
+	})
+})

package/src/core/StreamEntry.js

@@ -0,0 +1,59 @@
+/**
+ * Represents an entry in a stream with value, completion status, cancellation status, and error message.
+ */
+export default class StreamEntry {
+	/**
+	 * The value of the stream entry.
+	 * @type {any}
+	 */
+	value = undefined
+
+	/**
+	 * Indicates if the stream entry is done (completed).
+	 * @type {boolean}
+	 */
+	done = false
+
+	/**
+	 * Indicates if the stream entry has been cancelled.
+	 * @type {boolean}
+	 */
+	cancelled = false
+
+	/**
+	 * Error message associated with the stream entry.
+	 * @type {string}
+	 */
+	error = ""
+
+	/**
+	 * Creates a new StreamEntry instance.
+	 * @param {Object} [input={}] - Input object to initialize the stream entry.
+	 * @param {any} [input.value] - The value for the stream entry.
+	 * @param {boolean} [input.done] - Whether the stream entry is completed.
+	 * @param {boolean} [input.cancelled] - Whether the stream entry is cancelled.
+	 * @param {string} [input.error] - Error message for the stream entry.
+	 */
+	constructor(input = {}) {
+		const {
+			value = this.value,
+			done = this.done,
+			cancelled = this.cancelled,
+			error = this.error,
+		} = input
+		this.value = value
+		this.done = Boolean(done)
+		this.cancelled = Boolean(cancelled)
+		this.error = String(error)
+	}
+
+	/**
+	 * Creates a StreamEntry instance from the given input.
+	 * @param {any} input - The input to create a StreamEntry from.
+	 * @returns {StreamEntry} A new or existing StreamEntry instance.
+	 */
+	static from(input) {
+		if (input instanceof StreamEntry) return input
+		return new StreamEntry(input)
+	}
+}

package/src/core/index.js

@@ -0,0 +1,13 @@
+// export default App
+
+export { default as InputAdapter } from "./InputAdapter.js"
+export { default as OutputAdapter } from "./OutputAdapter.js"
+export { default as UIStream } from "./Stream.js"
+
+export { default as UIMessage } from "./Message/Message.js"
+export { default as InputMessage } from "./Message/InputMessage.js"
+export { default as OutputMessage } from "./Message/OutputMessage.js"
+
+export { default as FormMessage } from "./Form/Message.js"
+export { default as FormInput } from "./Form/Input.js"
+export { default as UIForm } from "./Form/Form.js"

package/src/functions.js

@@ -0,0 +1,38 @@
+import { empty } from "@nan0web/types"
+
+export const spaces = (options = {}) => {
+	const { cols = [], padding = 1, aligns = [] } = options
+	return (row) => (
+		row.map((str, i) => {
+			const pad = " ".repeat(cols[i] - str.length + padding)
+			return aligns[i] === "r" ? pad + str : str + pad
+		})
+	)
+}
+
+export const weight = (arr) => {
+	return (Fn = v => v) => {
+		const cols = []
+		arr.forEach(m => {
+			Fn(m).forEach((str, i) => {
+				if (undefined === cols[i]) cols[i] = 0
+				cols[i] = Math.max(str.length, cols[i])
+			})
+		})
+		return cols
+	}
+}
+
+
+export const table = (options = {}) => {
+	const {
+		Fn = v => v,
+		cols = [],
+		padding = 1,
+		aligns = []
+	} = options
+	return (arr) => {
+		const options = { cols: empty(cols) ? weight(arr)(Fn) : cols, padding, aligns }
+		return arr.map(row => spaces(options)(row))
+	}
+}