@nan0web/ui 1.0.0

package/src/View/View.js

@@ -0,0 +1,289 @@
+import { empty, equal, typeOf } from "@nan0web/types"
+import Frame, { FrameRenderMethod } from "../Frame/Frame.js"
+import Locale from "../Locale.js"
+import StdOut from "../StdOut.js"
+import StdIn from "../StdIn.js"
+import InputMessage from "../core/Message/InputMessage.js"
+import RenderOptions from "./RenderOptions.js"
+
+/**
+ * @typedef {Object} ComponentFn
+ * @property {string} name
+ * @property {(input: InputMessage) => Promise<any>} ask
+ * @property {Function} bind
+ */
+
+export default class View {
+	/** @type {typeof RenderOptions} */
+	static RenderOptions = RenderOptions
+	/** @type {typeof FrameRenderMethod} */
+	static RenderMethod = Frame.RenderMethod
+	/** @type {StdIn} */
+	stdin
+	/** @type {StdOut} */
+	stdout
+	/** @type {number} */
+	startedAt
+	/** @type {Frame} */
+	frame
+	/** @type {Locale} */
+	locale
+	/** @type {Map} */
+	vocab
+	/** @type {number[]} */
+	windowSize
+	/** @type {Map<string, ComponentFn>} */
+	components
+	/** @type {string} */
+	renderMethod
+	/**
+	 * @param {object} [input]
+	 * @param {StdIn} [input.stdin]
+	 * @param {StdOut} [input.stdout]
+	 * @param {number} [input.startedAt]
+	 * @param {Frame} [input.frame]
+	 * @param {Locale} [input.locale]
+	 * @param {Map} [input.vocab]
+	 * @param {number[]} [input.windowSize]
+	 * @param {Map<string, ComponentFn>} [input.components]
+	 * @param {string} [input.renderMethod]
+	 */
+	constructor(input = {}) {
+		const {
+			stdin = new StdIn(),
+			stdout = new StdOut(),
+			startedAt = Date.now(),
+			frame = new Frame(),
+			locale = Locale.from("uk-UA"),
+			vocab = new Map(),
+			windowSize = [0, 0],
+			components = new Map(),
+			renderMethod = Frame.RenderMethod.VISIBLE,
+		} = input
+		this.stdin = stdin
+		this.stdout = stdout
+		this.startedAt = startedAt
+		this.frame = frame
+		this.locale = locale
+		this.vocab = vocab
+		this.windowSize = null === windowSize ? this.stdout.getWindowSize() : windowSize
+		this.components = components
+		this.renderMethod = renderMethod
+		if (!empty(frame)) {
+			this.render(1)(this.frame)
+		}
+	}
+	get empty() {
+		return empty(this.frame)
+	}
+	get RenderMethod() {
+		return /** @type {typeof View} */ (this.constructor).RenderMethod
+	}
+	get RenderOptions() {
+		return /** @type {typeof View} */ (this.constructor).RenderOptions
+	}
+	getWindowSize() {
+		return equal(this.windowSize, [0, 0]) ? this.stdout.getWindowSize() : this.windowSize
+	}
+	setWindowSize(width, height) {
+		this.windowSize = [width, height]
+	}
+	startTimer() {
+		this.startedAt = Date.now()
+	}
+	spent(checkpoint = this.startedAt) {
+		return Math.round((Date.now() - checkpoint) / 1000)
+	}
+	/**
+	 * @param {boolean | number | Function | ComponentFn} [shouldRender=0]
+	 * @param {RenderOptions} [options]
+	 * @returns {(value: Frame|string|string[], ...args: any) => Frame}
+	 */
+	render(shouldRender = 0, options = new this.RenderOptions()) {
+		const [width, height] = this.getWindowSize()
+		options = this.RenderOptions.from({
+			...options,
+			renderMethod: this.renderMethod, width, height,
+			// @ts-ignore
+		})
+		const renderFn = "function" === typeof shouldRender // no errors.
+			// const renderFn = typeOf(Function)(shouldRender) // Property 'bind' does not exist on type 'number | boolean | Function'.
+			? shouldRender.bind(this) : "string" === typeof shouldRender
+				? this.components.get(shouldRender)?.bind(this)
+				: null
+
+		return (value, ...args) => {
+			if (renderFn) {
+				/** @type {Frame} */
+				let rendered = renderFn.bind(this)(value, ...args)
+				if (!(rendered instanceof Frame)) {
+					rendered = new Frame({
+						value: rendered,
+						renderMethod: options.renderMethod,
+						width: options.width,
+						height: options.height,
+					})
+				}
+				rendered = View.fixFrame(rendered, options)
+				rendered = rendered.transform(this.t.bind(this))
+				rendered.render()
+				if (options.render) {
+					this.stdout.write(String(rendered))
+					this.frame = rendered
+				}
+				return rendered
+			}
+
+			let frame = Frame.from({ ...options, value })
+			frame = View.fixFrame(frame, options)
+			let clearFrame = false
+			if (String(frame.value[0] ?? "") === Frame.BOF) {
+				frame.value = frame.value.slice(1)
+				clearFrame = true
+			}
+			let translated = options.translateFrame ? frame.transform(this.t.bind(this)) : frame
+			translated = View.fixFrame(translated, options)
+
+			let rendered = translated
+			rendered.render()
+			if (shouldRender) {
+				if (clearFrame) {
+					const distance = options.height - frame.value.length
+					this.stdout.write(Frame.BOF)
+					for (let i = 0; i < distance; i++) {
+						this.stdout.write(Frame.EOL)
+					}
+				}
+				this.stdout.write(Frame.RESET + String(rendered))
+				this.frame = rendered
+			}
+			return rendered
+		}
+	}
+
+	clear(shouldRender = 0) {
+		const [width, height] = this.windowSize
+		const frame = new Frame({ width, height, renderMethod: Frame.RenderMethod.REPLACE })
+		frame.value = []
+		for (let i = 0; i < height; i++) frame.value.push([])
+		return this.render(shouldRender)(frame)
+	}
+
+	progress(shouldRender = false) {
+		return (value) => {
+			const frame = Frame.from(value)
+			frame.renderMethod = Frame.RenderMethod.REPLACE
+			return this.render(!!shouldRender)(frame)
+		}
+	}
+
+	t(value) {
+		if (typeOf(Array)(value)) {
+			value = value.map(row => {
+				if (typeOf(Array)(row)) {
+					return row.map(col => {
+						return this.vocab.has(col) ? this.vocab.get(col) : col
+					})
+				}
+				return this.vocab.has(row) ? this.vocab.get(row) : row
+			})
+			return value
+		}
+		return this.vocab.has(value) ? this.vocab.get(value) : value
+	}
+
+	debug(...args) {
+		return this.render(1)(
+			[StdOut.STYLES.dim,
+				"Debug: ", args.join(" "), Frame.EOL, StdOut.RESET],
+		)
+	}
+
+	info(...args) {
+		return this.render(1)(
+			[StdOut.COLORS.green,
+				"Info : ", args.join(" "), Frame.EOL, StdOut.RESET],
+		)
+	}
+
+	warn(...args) {
+		return this.render(1)(
+			[StdOut.COLORS.yellow,
+				"Warn : ", args.join(" "), Frame.EOL, StdOut.RESET],
+		)
+	}
+
+	error(...args) {
+		return this.render(1)(
+			[StdOut.COLORS.red, StdOut.STYLES.bold,
+				"Error: ", args.join(" "), Frame.EOL, StdOut.RESET],
+		)
+	}
+
+	/**
+	 * @param {string} name
+	 * @param {ComponentFn} component
+	 */
+	register(name, component) {
+		if (undefined === component && "function" === typeof name) {
+			component = name
+			name = component.name
+		}
+		this.components.set(name, component)
+	}
+
+	/**
+	 * @param {string} name
+	 */
+	unregister(name) {
+		this.components.delete(name)
+	}
+
+	/**
+	 * @param {string} name
+	 * @returns {boolean}
+	 */
+	has(name) {
+		return this.components.has(name)
+	}
+
+	/**
+	 * @param {string} name
+	 * @returns {ComponentFn | undefined}
+	 */
+	get(name) {
+		return this.components.get(name)
+	}
+
+	/**
+	 * @param {InputMessage} input
+	 * @returns {Promise<InputMessage | null>}
+	 */
+	async ask(input) {
+		const name = input.constructor.name.replace(/Input$/, "")
+		const component = this.get(name)
+		if (component) {
+			return await component.ask.apply(this, [input])
+		}
+		let result = null
+		do {
+			const answer = await this.stdin.read()
+			result = /** @type {typeof InputMessage} */ (input.constructor).from(answer)
+		} while (!result.isValid && !result.escaped)
+		return result.escaped ? null : result
+	}
+
+	/**
+	 * @param {Frame} frame
+	 * @param {RenderOptions} [options]
+	 * @returns {Frame}
+	 */
+	static fixFrame(frame, options = new RenderOptions()) {
+		if (options.resizeToView && !equal(options.width, frame.width, options.height, frame.height)) {
+			frame.setWindowSize(options.width, options.height)
+		}
+		// @todo add multiline visibility, for instance extended frame row into rows if it's wider than width.
+		return frame
+	}
+
+}

package/src/View/View.test.js

@@ -0,0 +1,77 @@
+import { describe, it } from "node:test"
+import { strict as assert } from "node:assert"
+import stringWidth from "string-width"
+import View from "./View.js"
+import Frame from "../Frame/Frame.js"
+import FrameProps from "../Frame/Props.js"
+import Welcome from "../Component/Welcome/index.js"
+
+describe("View", () => {
+	it("should create empty instance", () => {
+		const view = new View()
+		assert.ok(view)
+	})
+	it("should print frame", () => {
+		const view = new View()
+		view.render(1)(["Hello"])
+		assert.equal(String(view.frame), Frame.CLEAR_LINE + "\r" + "Hello")
+		const value = view.render(0)(["No output"])
+		assert.deepStrictEqual({ ...value }, {
+			imprint: Frame.CLEAR_LINE + "\r" + "No output",
+			value: [["No output"]],
+			width: 144,
+			height: 33,
+			renderMethod: "visible",
+			defaultProps: new FrameProps(),
+		})
+		view.render(() => (["fn result"]))(["Even with a function"])
+		assert.equal(String(view.frame), Frame.CLEAR_LINE + "\r" + "fn result")
+		assert.deepStrictEqual(view.stdout.stream, [
+			Frame.RESET + Frame.CLEAR_LINE + "\r" + "Hello",
+			Frame.CLEAR_LINE + "\r" + "fn result"
+		])
+	})
+	it("should print frame with render method set to append", () => {
+		const view = new View({ renderMethod: View.RenderMethod.APPEND })
+		view.render(1)(["Hello"])
+		assert.equal(String(view.frame), "Hello" + " ".repeat(139))
+		view.render(1)(["world"])
+		assert.equal(String(view.frame), "world" + " ".repeat(139))
+		const value = view.render(0)(["No output"])
+		assert.deepStrictEqual({ ...value }, {
+			imprint: "No output" + " ".repeat(144 - "No output".length),
+			value: [["No output"]],
+			width: 144,
+			height: 33,
+			renderMethod: View.RenderMethod.APPEND,
+			defaultProps: new FrameProps(),
+		})
+		view.render(() => (["fn result"]))(["Even with a function"])
+		assert.equal(String(view.frame), "fn result" + " ".repeat(144 - 9))
+		assert.deepStrictEqual(view.stdout.stream, [
+			Frame.RESET + "Hello",
+			Frame.RESET + "world",
+			"fn result"
+		].map(
+			row => row + " ".repeat(144 - stringWidth(row))
+		))
+	})
+	it("should render Welcome component", () => {
+		const view = new View({
+			renderMethod: View.RenderMethod.APPEND,
+			width: 144,
+			height: 33,
+		})
+		view.register(Welcome)
+		const frame = view.render("Welcome")({ user: { name: "View" } })
+		assert.ok(frame instanceof Frame)
+		const expected = [
+			"Welcome View!",
+			"What can we do today great?",
+			"",
+		].map(
+			row => (row + " ".repeat(144 - row.length))
+		).join("\n")
+		assert.deepStrictEqual(view.stdout.stream, [expected])
+	})
+})

package/src/core/Form/Form.js

@@ -0,0 +1,289 @@
+import FormMessage from "./Message.js"
+import FormInput from "./Input.js"
+
+/**
+ * Abstract form for data entry.
+ *
+ * @class UIForm
+ * @extends FormMessage
+ * @property {FormInput[]} fields - Form fields.
+ * @property {Object} state - Current form state (field values).
+ * @property {string} title - Form title.
+ * @property {Object} schema - Validation schema (optional).
+ */
+export default class UIForm extends FormMessage {
+	/** @type {FormInput[]} */ fields = []
+	/** @type {Object} */ state = {}
+	/** @type {string} */ title = ''
+	/** @type {Object} */ schema = {}
+
+	/* ------------------------------------------------------------------ */
+	/*                     static validator registry                       */
+	/* ------------------------------------------------------------------ */
+
+	/** @type {Object<string,Function>} */
+	static _validators = {}
+
+	/**
+	 * Register a custom validator that can be referenced by name in a schema.
+	 *
+	 * @param {string} name - Identifier used in schema.validator.
+	 * @param {(value:any)=>true|string} fn - Function returns true if valid,
+	 *   otherwise returns an error message.
+	 */
+	static addValidator(name, fn) {
+		if (typeof name !== "string" || typeof fn !== "function") {
+			throw new Error("Validator name must be a string and fn must be a function")
+		}
+		UIForm._validators[name] = fn
+	}
+
+	/**
+	 * Create a new UIForm.
+	 *
+	 * @param {Object} [props={}] - Form properties.
+	 * @param {string} [props.title] - Form title.
+	 * @param {FormInput[]} [props.fields=[]] - Form fields.
+	 * @param {Object} [props.state={}] - Initial form state.
+	 * @param {Object} [props.schema] - Validation schema.
+	 */
+	constructor(props = {}) {
+		super(props)
+
+		const {
+			title = '',
+			fields = [],
+			state = {},
+			schema = {},
+			...rest
+		} = props
+
+		// Normalise fields
+		this.fields = fields.map(f => FormInput.from(f))
+		this.title = title
+		this.state = { ...state }
+		this.schema = schema
+
+		// Update meta with form data
+		this.meta = {
+			title: this.title,
+			fields: this.fields.map(f => f.toJSON ? f.toJSON() : f),
+			initialState: this.state
+		}
+	}
+
+	/* ------------------------------------------------------------------ */
+	/*                              API                                   */
+	/* ------------------------------------------------------------------ */
+
+	/**
+	 * Returns a new UIForm instance with updated state.
+	 *
+	 * @param {Object} data - Partial state to merge.
+	 * @returns {UIForm}
+	 */
+	setData(data) {
+		return new UIForm({
+			...this,
+			state: { ...this.state, ...data }
+		})
+	}
+
+	/**
+	 * Retrieves a field definition by its name.
+	 *
+	 * @param {string} name - Field name.
+	 * @returns {FormInput|undefined}
+	 */
+	getField(name) {
+		return this.fields.find(f => f.name === name)
+	}
+
+	/**
+	 * Returns current form values.
+	 *
+	 * @returns {Object}
+	 */
+	getValues() {
+		return { ...this.state }
+	}
+
+	/**
+	 * Validates the entire form.
+	 *
+	 * @returns {{isValid: boolean, errors: Object}} Validation result.
+	 */
+	validate() {
+		const errors = {}
+		let isValid = true
+
+		this.fields.forEach((field) => {
+			const fieldValue = this.state[field.name]
+
+			// Required validation based on field definition or schema
+			if (field.required && (fieldValue === '' || fieldValue === null || fieldValue === undefined)) {
+				errors[field.name] = 'This field is required'
+				isValid = false
+				return
+			}
+
+			// Validation via schema (if provided) or field type
+			const { isValid: fieldValid, errors: fieldErrors } = this.validateField(field.name, fieldValue)
+
+			if (!fieldValid) {
+				Object.assign(errors, fieldErrors)
+				isValid = false
+			}
+		})
+
+		return { isValid, errors }
+	}
+
+	/**
+	 * Validates a single field.
+	 *
+	 * @param {string} fieldName - Name of the field.
+	 * @param {*} value - Value to validate.
+	 * @returns {{isValid: boolean, errors: Object}}
+	 */
+	validateField(fieldName, value) {
+		const field = this.getField(fieldName)
+		if (!field) return { isValid: false, errors: { [fieldName]: 'Field not found' } }
+
+		// Merge schema from UIForm.schema with field.type if schema does not specify a type
+		const schemaFromField = this.schema?.[fieldName] ? { ...this.schema[fieldName] } : {}
+		if (!schemaFromField.type && field.type) {
+			schemaFromField.type = field.type
+		}
+
+		return this.validateValue(fieldName, value, schemaFromField)
+	}
+
+	/**
+	 * Validates a value against a schema.
+	 *
+	 * @param {string} fieldName - Name of the field.
+	 * @param {*} value - Value to validate.
+	 * @param {Object} schema - Validation schema.
+	 * @returns {{isValid: boolean, errors: Object}}
+	 */
+	validateValue(fieldName, value, schema) {
+		const errors = {}
+		let isValid = true
+
+		// Required rule (if defined in schema)
+		if (schema.required && (value === '' || value === null || value === undefined)) {
+			errors[fieldName] = 'This field is required'
+			isValid = false
+		}
+
+		if (schema.minLength && value && value.length < schema.minLength) {
+			errors[fieldName] = `Minimum length is ${schema.minLength}`
+			isValid = false
+		}
+
+		if (schema.maxLength && value && value.length > schema.maxLength) {
+			errors[fieldName] = `Maximum length is ${schema.maxLength}`
+			isValid = false
+		}
+
+		if (schema.pattern && value && !schema.pattern.test(value)) {
+			errors[fieldName] = schema.errorMessage || 'Invalid format'
+			isValid = false
+		}
+
+		// Type validation
+		if (schema.type) {
+			if (schema.type === 'email') {
+				const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+				if (value && !emailRegex.test(value)) {
+					errors[fieldName] = 'Invalid email format'
+					isValid = false
+				}
+			} else if (schema.type === 'number') {
+				if (value !== '' && isNaN(Number(value))) {
+					errors[fieldName] = 'Must be a number'
+					isValid = false
+				}
+			}
+		}
+
+		// Custom validator – can be a function or a string referencing a static validator
+		if (schema.validator) {
+			let result
+			if (typeof schema.validator === 'function') {
+				result = schema.validator(value)
+			} else if (typeof schema.validator === 'string') {
+				const fn = UIForm._validators[schema.validator]
+				if (!fn) {
+					throw new Error(`Validator "${schema.validator}" not registered`)
+				}
+				result = fn(value)
+			}
+			if (result !== true) {
+				errors[fieldName] = result || 'Invalid value'
+				isValid = false
+			}
+		}
+
+		return { isValid, errors }
+	}
+
+	/**
+	 * Serialises the form to a plain JSON object.
+	 *
+	 * @returns {Object}
+	 */
+	toJSON() {
+		return {
+			id: this.id,
+			type: this.type,
+			time: this.time.toISOString(),
+			title: this.title,
+			fields: this.fields.map(f => f.toJSON ? f.toJSON() : f),
+			state: this.state,
+			meta: this.meta
+		}
+	}
+
+	/**
+	 * @param {*} input
+	 * @returns {UIForm}
+	 */
+	static from(input) {
+		if (input instanceof UIForm) return input
+		return new UIForm(input)
+	}
+
+	/**
+	 * Auto‑generates form fields from a plain object.
+	 *
+	 * @param {Object} data - Example data object; its own enumerable keys become field names.
+	 * @param {Object<string, Partial<import("./Input.js").default>>} [overrides={}]
+	 *        Optional per‑field overrides (e.g. type, required, label).
+	 *
+	 * @returns {UIForm} Form with Array of `FormInput` instances as form.fields
+	 *
+	 * Example:
+	 *   const fields = generateFieldsFromObject({ name: "", age: 0 }, {
+	 *     age: { type: FormInput.TYPES.NUMBER, required: true }
+	 *   })
+	 */
+	static parse(data, overrides = {}) {
+		const fields = Object.keys(data).map((name) => {
+			const custom = overrides[name] || {}
+			const label = custom.label ?? name.charAt(0).toUpperCase() + name.slice(1)
+			return new FormInput({
+				name,
+				label,
+				type: custom.type ?? FormInput.TYPES.TEXT,
+				required: !!custom.required,
+				placeholder: custom.placeholder ?? "",
+				options: custom.options ?? [],
+				validator: custom.validator ?? undefined,
+				defaultValue: custom.defaultValue ?? "",
+			})
+		})
+		return new UIForm({ fields })
+	}
+}