@nan0web/ui 1.0.0

package/src/core/Form/Form.test.js

@@ -0,0 +1,116 @@
+import { describe, it } from "node:test"
+import { strict as assert } from "node:assert"
+import UIForm from "./Form.js"
+import FormInput from "./Input.js"
+
+describe("UIForm", () => {
+	it("should create instance with default values", () => {
+		const form = new UIForm()
+		assert.ok(form instanceof UIForm)
+		assert.equal(form.title, "")
+		assert.deepEqual(form.fields, [])
+		assert.deepEqual(form.state, {})
+	})
+
+	it("should create instance with custom values", () => {
+		const fields = [
+			new FormInput({ name: "name", label: "Name", required: true }),
+			new FormInput({ name: "email", label: "Email", type: "email" })
+		]
+		const props = {
+			title: "Test Form",
+			fields,
+			state: { name: "John" }
+		}
+		const form = new UIForm(props)
+		assert.equal(form.title, "Test Form")
+		assert.equal(form.fields.length, 2)
+		assert.deepEqual(form.state, { name: "John" })
+	})
+
+	it("should set data", () => {
+		const form = new UIForm({ state: { name: "John" } })
+		const newForm = form.setData({ email: "john@example.com" })
+		assert.deepEqual(newForm.state, { name: "John", email: "john@example.com" })
+	})
+
+	it("should get field by name", () => {
+		const fields = [new FormInput({ name: "test", label: "Test Field" })]
+		const form = new UIForm({ fields })
+		const field = form.getField("test")
+		assert.ok(field)
+		assert.equal(field.name, "test")
+	})
+
+	it("should get values", () => {
+		const form = new UIForm({ state: { name: "John", age: 30 } })
+		const values = form.getValues()
+		assert.deepEqual(values, { name: "John", age: 30 })
+	})
+
+	it("should validate form", () => {
+		const fields = [new FormInput({ name: "requiredField", required: true })]
+		const form = new UIForm({ fields, state: {} })
+		const result = form.validate()
+		assert.ok(!result.isValid)
+		assert.ok(result.errors.requiredField)
+	})
+
+	it("should validate individual field", () => {
+		const fields = [new FormInput({ name: "email", type: "email" })]
+		const form = new UIForm({ fields })
+		const result = form.validateField("email", "invalid-email")
+		assert.ok(!result.isValid)
+		assert.ok(result.errors.email)
+	})
+
+	it("should convert to JSON", () => {
+		const form = new UIForm({ title: "Test", state: { name: "John" } })
+		const json = form.toJSON()
+		assert.ok(json.id)
+		assert.equal(json.title, "Test")
+		assert.ok(Array.isArray(json.fields))
+		assert.ok(json.state)
+		assert.ok(json.meta)
+	})
+
+	it("parses default text fields", () => {
+		const data = { name: "", email: "" }
+		const { fields } = UIForm.parse(data)
+		assert.equal(fields.length, 2)
+		assert.ok(fields[0] instanceof FormInput)
+		assert.equal(fields[0].name, "name")
+		assert.equal(fields[0].label, "Name")
+		assert.equal(fields[0].type, FormInput.TYPES.TEXT)
+		assert.equal(fields[0].required, false)
+	})
+
+	it("applies overrides correctly", () => {
+		const data = { age: "" }
+		const { fields } = UIForm.parse(data, {
+			age: { type: FormInput.TYPES.NUMBER, required: true, label: "User Age" },
+		})
+		const ageField = fields[0]
+		assert.equal(ageField.type, FormInput.TYPES.NUMBER)
+		assert.ok(ageField.required)
+		assert.equal(ageField.label, "User Age")
+	})
+
+	it("supports static custom validators", () => {
+		// register a validator that ensures a string contains only digits
+		UIForm.addValidator("digitsOnly", value => {
+			return /^\d+$/.test(value) ? true : "Must contain only digits"
+		})
+
+		const fields = [
+			new FormInput({ name: "phone", label: "Phone", required: true })
+		]
+		const schema = {
+			phone: { validator: "digitsOnly" }
+		}
+		const form = new UIForm({ fields, schema, state: { phone: "12a34" } })
+		const result = form.validate()
+		assert.ok(!result.isValid)
+		assert.equal(result.errors.phone, "Must contain only digits")
+	})
+})

package/src/core/Form/Input.js

@@ -0,0 +1,116 @@
+/**
+ * Form input field descriptor.
+ *
+ * @class FormInput
+ * @property {string} name - Field name.
+ * @property {string} label - Display label.
+ * @property {string} type - Input type (text, email, number, select, etc.).
+ * @property {boolean} required - Whether the field is required.
+ * @property {string} placeholder - Placeholder text.
+ * @property {Array<string>} options - Select options (if type is 'select').
+ * @property {Function|null} validator - Custom validation function.
+ * @property {*} defaultValue - Default value.
+ */
+export default class FormInput {
+	/** @type {string} */ name = ''
+	/** @type {string} */ label = ''
+	/** @type {string} */ type = 'text'
+	/** @type {boolean} */ required = false
+	/** @type {string} */ placeholder = ''
+	/** @type {Array<string>} */ options = []
+	/** @type {Function|null} */ validator = null
+	/** @type {*} */ defaultValue = null
+
+	/**
+	 * Predefined input types.
+	 */
+	static TYPES = {
+		TEXT: 'text',
+		EMAIL: 'email',
+		NUMBER: 'number',
+		SELECT: 'select',
+		CHECKBOX: 'checkbox',
+		TEXTAREA: 'textarea'
+	}
+
+	/**
+	 * Create a new form input.
+	 *
+	 * @param {Object} props - Input properties.
+	 * @param {string} props.name - Field name.
+	 * @param {string} [props.label=props.name] - Display label.
+	 * @param {string} [props.type='text'] - Input type.
+	 * @param {boolean} [props.required=false] - Is required.
+	 * @param {string} [props.placeholder=''] - Placeholder.
+	 * @param {Array<string>} [props.options=[]] - Select options.
+	 * @param {Function} [props.validator=null] - Custom validator.
+	 * @param {*} [props.defaultValue=null] - Default value.
+	 */
+	constructor(props) {
+		const {
+			name,
+			label = name,
+			type = FormInput.TYPES.TEXT,
+			required = this.required,
+			placeholder = this.placeholder,
+			options = [],
+			validator = this.validator,
+			defaultValue = this.defaultValue
+		} = props
+
+		if (!name) {
+			throw new TypeError('FormInput.name is required')
+		}
+
+		this.name = String(name)
+		this.label = String(label)
+		this.type = String(type)
+		this.required = Boolean(required)
+		this.placeholder = String(placeholder)
+		this.options = options
+		this.validator = validator
+		this.defaultValue = defaultValue
+
+		this.requireValidType()
+	}
+
+	requireValidType() {
+		if (!Object.values(FormInput.TYPES).includes(this.type)) {
+			throw new TypeError([
+				"FormInput.type is invalid!",
+				["Provided", this.type].join(": "),
+				"Available types:",
+				...Object.values(FormInput.TYPES).map(t => `  - ${t}`)
+			].join("\n"))
+		}
+	}
+
+	/**
+	 * Serialises the input to a plain JSON object.
+	 *
+	 * @returns {Object}
+	 */
+	toJSON() {
+		return {
+			name: this.name,
+			label: this.label,
+			type: this.type,
+			required: this.required,
+			placeholder: this.placeholder,
+			options: this.options,
+			defaultValue: this.defaultValue
+		}
+	}
+
+	/**
+	 * @param {*} input
+	 * @returns {FormInput}
+	 */
+	static from(input) {
+		if (input instanceof FormInput) return input
+		if ("string" === typeof input) {
+			return new FormInput({ name: input, label: input })
+		}
+		return new FormInput(input)
+	}
+}

package/src/core/Form/Input.test.js

@@ -0,0 +1,58 @@
+import { describe, it } from "node:test"
+import { strict as assert } from "node:assert"
+import FormInput from "./Input.js"
+
+describe("FormInput", () => {
+	it("should create instance with default values", () => {
+		const input = new FormInput({ name: "name" })
+		assert.ok(input instanceof FormInput)
+		assert.equal(input.type, FormInput.TYPES.TEXT)
+		assert.equal(input.required, false)
+		assert.equal(input.name, "name")
+		assert.equal(input.placeholder, "")
+		assert.deepEqual(input.options, [])
+	})
+
+	it("should create instance with custom values", () => {
+		const props = {
+			type: "email",
+			name: "email",
+			label: "Email Address",
+			required: true,
+			placeholder: "Enter email",
+			options: ["option1", "option2"],
+			defaultValue: "test@example.com"
+		}
+		const input = new FormInput(props)
+		assert.equal(input.type, "email")
+		assert.equal(input.name, "email")
+		assert.equal(input.label, "Email Address")
+		assert.equal(input.required, true)
+		assert.equal(input.placeholder, "Enter email")
+		assert.deepEqual(input.options, ["option1", "option2"])
+		assert.equal(input.defaultValue, "test@example.com")
+	})
+
+	it("should create from string", () => {
+		const input = FormInput.from("testField")
+		assert.equal(input.name, "testField")
+		assert.equal(input.label, "testField")
+	})
+
+	it("should create from object", () => {
+		const objInput = { name: "test", type: "text" }
+		const input = FormInput.from(objInput)
+		assert.ok(input instanceof FormInput)
+		assert.equal(input.name, "test")
+	})
+
+	it("should validate type", async () => {
+		const validInput = new FormInput({ name: "email", type: "email" })
+		assert.ok(validInput)
+		const fn = async () => new FormInput({ name: "email", type: "invalid" })
+		await assert.rejects(fn, {
+			name: "TypeError",
+			message: /FormInput\.type is invalid!/
+		})
+	})
+})

package/src/core/Form/Message.js

@@ -0,0 +1,86 @@
+import OutputMessage from "../Message/OutputMessage.js"
+
+/**
+ * FormMessage – specialized OutputMessage for forms.
+ *
+ * @class FormMessage
+ * @extends OutputMessage
+ */
+export default class FormMessage extends OutputMessage {
+	/**
+	 * Creates a FormMessage.
+	 *
+	 * @param {Object} [input={}] - Message properties.
+	 */
+	constructor(input = {}) {
+		super({
+			...input,
+			type: OutputMessage.TYPES.FORM,
+		})
+		const {
+			data = {},
+			schema = {},
+		} = input
+
+		// Store data and schema for easy access
+		this.data = data
+		this.schema = schema
+	}
+
+	/**
+	 * Returns a new FormMessage with merged data.
+	 *
+	 * @param {Object} newData - Data to merge.
+	 * @returns {FormMessage}
+	 */
+	addData(newData) {
+		return new FormMessage({
+			...this,
+			data: { ...this.data, ...newData },
+		})
+	}
+
+	/**
+	 * Validates the provided data against the schema.
+	 *
+	 * @param {Object} data - Data to validate.
+	 * @returns {{isValid: boolean, errors: Object}}
+	 */
+	validateData(data) {
+		const errors = {}
+
+		if (!this.schema) return { isValid: true, errors }
+
+		for (const [field, rules] of Object.entries(this.schema)) {
+			const value = data[field]
+
+			if (rules.required && (value === undefined || value === null || value === '')) {
+				errors[field] = 'Field is required'
+				continue
+			}
+
+			if (rules.type) {
+				if (rules.type === 'email') {
+					const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+					if (value && !emailRegex.test(value)) {
+						errors[field] = 'Invalid email format'
+					}
+				} else if (rules.type === 'number') {
+					if (value !== '' && isNaN(Number(value))) {
+						errors[field] = 'Must be a number'
+					}
+				}
+			}
+
+			if (rules.minLength && value && value.length < rules.minLength) {
+				errors[field] = `Minimum length is ${rules.minLength}`
+			}
+
+			if (rules.maxLength && value && value.length > rules.maxLength) {
+				errors[field] = `Maximum length is ${rules.maxLength}`
+			}
+		}
+
+		return { isValid: Object.keys(errors).length === 0, errors }
+	}
+}

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

@@ -0,0 +1,54 @@
+import { describe, it } from "node:test"
+import { strict as assert } from "node:assert"
+import FormMessage from "./Message.js"
+
+describe("FormMessage", () => {
+	it("should create instance with default values", () => {
+		const msg = new FormMessage()
+		assert.ok(msg instanceof FormMessage)
+		assert.deepEqual(msg.data, {})
+		assert.deepEqual(msg.schema, {})
+		assert.equal(msg.type, "form")
+	})
+
+	it("should create instance with custom values", () => {
+		const props = {
+			data: { name: "John" },
+			schema: { name: { required: true } },
+			body: ["Form content"]
+		}
+		const msg = new FormMessage(props)
+		assert.deepEqual(msg.data, { name: "John" })
+		assert.deepEqual(msg.schema, { name: { required: true } })
+		assert.deepEqual(msg.body, ["Form content"])
+	})
+
+	it("should add data", () => {
+		const msg = new FormMessage({ data: { name: "John" } })
+		const newMsg = msg.addData({ age: 30 })
+		assert.deepEqual(newMsg.data, { name: "John", age: 30 })
+	})
+
+	it("should validate data correctly", () => {
+		const schema = {
+			name: { required: true },
+			email: { type: "email" },
+			age: { type: "number" }
+		}
+		const msg = new FormMessage({ schema })
+		
+		// Valid data
+		const validData = { name: "John", email: "john@example.com", age: "30" }
+		const validResult = msg.validateData(validData)
+		assert.ok(validResult.isValid)
+		assert.deepEqual(validResult.errors, {})
+		
+		// Invalid data
+		const invalidData = { email: "invalid-email", age: "not-a-number" }
+		const invalidResult = msg.validateData(invalidData)
+		assert.ok(!invalidResult.isValid)
+		assert.ok(invalidResult.errors.name)
+		assert.ok(invalidResult.errors.email)
+		assert.ok(invalidResult.errors.age)
+	})
+})

package/src/core/Form/index.js

@@ -0,0 +1,11 @@
+import FormInput from "./Input.js"
+import FormMessage from "./Message.js"
+import Form from "./Form.js"
+
+export {
+	FormInput,
+	FormMessage,
+	Form,
+}
+
+export default Form

package/src/core/InputAdapter.js

@@ -0,0 +1,41 @@
+import Event from "@nan0web/event/oop"
+import InputMessage from "./Message/InputMessage.js"
+
+/**
+ * Abstract input adapter for UI implementations.
+ *
+ * @class InputAdapter
+ * @extends Event
+ */
+class InputAdapter extends Event {
+	/**
+	 * Starts listening for input and emits an `input` event.
+	 *
+	 * @returns {void}
+	 */
+	start() {
+		this.emit('input',
+			InputMessage.from({ value: "Adapter started" })
+		)
+	}
+
+	/**
+	 * Stops listening for input. Default implementation does nothing.
+	 *
+	 * @returns {void}
+	 */
+	stop() {
+		// Default implementation – does nothing
+	}
+
+	/**
+	 * Checks whether the adapter is ready to receive input.
+	 *
+	 * @returns {boolean} Always true in base class.
+	 */
+	isReady() {
+		return true
+	}
+}
+
+export default InputAdapter

package/src/core/InputAdapter.test.js

@@ -0,0 +1,35 @@
+import { describe, it } from "node:test"
+import { strict as assert } from "node:assert"
+import InputAdapter from "./InputAdapter.js"
+
+describe("InputAdapter", () => {
+	it("should create instance", () => {
+		const adapter = new InputAdapter()
+		assert.ok(adapter instanceof InputAdapter)
+	})
+
+	it("should start and emit input message", () => {
+		const adapter = new InputAdapter()
+		let emitted = false
+		let message = null
+		
+		adapter.on('input', (msg) => {
+			emitted = true
+			message = msg
+		})
+		
+		adapter.start()
+		assert.ok(emitted)
+		assert.ok(message)
+	})
+
+	it("should stop without error", () => {
+		const adapter = new InputAdapter()
+		assert.doesNotThrow(() => adapter.stop())
+	})
+
+	it("should be ready by default", () => {
+		const adapter = new InputAdapter()
+		assert.ok(adapter.isReady())
+	})
+})

package/src/core/Message/InputMessage.js

@@ -0,0 +1,119 @@
+import { notEmpty } from "@nan0web/types"
+import { Message } from "@nan0web/co"
+
+/** @typedef {Message | string | null} InputMessageValue */
+
+/**
+ * Represents a message input with value, options, and metadata.
+ */
+export default class InputMessage {
+	static ESCAPE = String.fromCharCode(27)
+	/** @type {InputMessageValue} Input value */
+	value
+
+	/** @type {string[]} Available options for this input */
+	options
+
+	/** @type {boolean} Whether this input is waiting for response */
+	waiting
+
+	/** @type {number} Timestamp when input was created */
+	#time
+
+	/**
+	 * Creates a new InputMessage instance.
+	 * @param {object} props - Input message properties
+	 * @param {InputMessageValue} [props.value=""] - Input value
+	 * @param {string[]|string} [props.options=[]] - Available options
+	 * @param {boolean} [props.waiting=false] - Waiting state flag
+	 * @param {boolean} [props.escaped=false] - Sets value to escape when true
+	 */
+	constructor(props = {}) {
+		if ("string" === typeof props) {
+			props = { value: props }
+		}
+		const {
+			value = "",
+			waiting = false,
+			options = [],
+			escaped = false,
+		} = props
+		this.#time = Date.now()
+		this.waiting = Boolean(waiting)
+
+		// Properly handle string options by converting to array
+		this.options = Array.isArray(options) ? options.map(String) : [String(options)]
+		this.value = String(value)
+		if (!this.value && escaped) {
+			this.value = this.ESCAPE
+		}
+	}
+
+	/**
+	 * Checks if the input value is empty.
+	 * @returns {boolean} True if value is empty or null, false otherwise
+	 */
+	get empty() {
+		return null === this.value || 0 === String(this.value).length
+	}
+
+	/**
+	 * Gets the timestamp when input was created.
+	 * @returns {number} Creation timestamp
+	 */
+	get time() {
+		return this.#time
+	}
+
+	/**
+	 * Returns the escape value.
+	 * @returns {string}
+	 */
+	get ESCAPE() {
+		return /** @type {typeof InputMessage} */ (this.constructor).ESCAPE
+	}
+
+	/**
+	 * Checks if the input is an escape sequence.
+	 * @returns {boolean} True if input value is escape sequence, false otherwise
+	 */
+	get escaped() {
+		return this.ESCAPE === this.value
+	}
+
+	/**
+	 * Validates if the input has a non-empty value.
+	 * @returns {boolean} True if input is valid, false otherwise
+	 */
+	get isValid() {
+		// An input is valid only if it has a non-empty value and is not an escape sequence
+		return notEmpty(this.value) && this.value !== this.ESCAPE
+	}
+
+	/**
+	 * Converts the input to a plain object representation.
+	 * @returns {object} Object with all properties including timestamp
+	 */
+	toObject() {
+		return { ...this, time: this.time }
+	}
+
+	/**
+	 * Converts the input to a string representation including timestamp.
+	 * @returns {string} String representation with timestamp and value
+	 */
+	toString() {
+		const date = new Date(this.time)
+		return `${date.toISOString().split(".")[0]} ${this.value}`
+	}
+
+	/**
+	 * Creates an InputMessage instance from the given value.
+	 * @param {InputMessage|object|string} value - The value to create from
+	 * @returns {InputMessage} An InputMessage instance
+	 */
+	static from(value) {
+		if (value instanceof InputMessage) return value
+		return new this(value)
+	}
+}

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

@@ -0,0 +1,45 @@
+import { describe, it } from "node:test"
+import { strict as assert } from "node:assert"
+import InputMessage from "./InputMessage.js"
+import { notEmpty, empty } from "@nan0web/types"
+
+describe("InputMessage", () => {
+	it("should create instance with default values", () => {
+		const msg = new InputMessage()
+		assert.ok(msg instanceof InputMessage)
+		assert.equal(msg.value, "")
+		assert.equal(msg.waiting, false)
+		assert.deepEqual(msg.options, [])
+	})
+
+	it("should create instance with custom values", () => {
+		const props = {
+			value: "user input",
+			waiting: true,
+			options: ["option1", "option2"]
+		}
+		const msg = new InputMessage(props)
+		assert.equal(msg.value, "user input")
+		assert.equal(msg.waiting, true)
+		assert.deepEqual(msg.options, ["option1", "option2"])
+	})
+
+	it("should handle string options correctly", () => {
+		const msg = new InputMessage({ options: "single-option" })
+		assert.deepEqual(msg.options, ["single-option"])
+	})
+
+	it("should detect empty value", () => {
+		const emptyMsg = new InputMessage({ value: "" })
+		const nonEmptyMsg = new InputMessage({ value: "test" })
+		assert.ok(emptyMsg.empty)
+		assert.ok(!nonEmptyMsg.empty)
+	})
+
+	it("should validate message", () => {
+		const validMsg = new InputMessage({ value: "test" })
+		const invalidMsg = new InputMessage({ value: "" })
+		assert.ok(validMsg.isValid)
+		assert.ok(!invalidMsg.isValid)
+	})
+})