@dex-ai/vue-tui 0.1.10

package/src/composables/index.ts

@@ -0,0 +1,19 @@
+// ---------------------------------------------------------------------------
+// @dex-ai/vue-tui/composables — barrel export
+// ---------------------------------------------------------------------------
+
+export { useForm } from "./useForm";
+export type { UseFormOptions, UseFormReturn } from "./useForm";
+
+export { useFocusList } from "./useFocusList";
+export type { UseFocusListOptions, FocusListState } from "./useFocusList";
+
+export { useSelectList } from "./useSelectList";
+export type { UseSelectListOptions, SelectListState } from "./useSelectList";
+
+export type {
+	FormField,
+	FormState,
+	FormActions,
+	FormResult,
+} from "../types/form";

package/src/composables/useFocusList.ts

@@ -0,0 +1,101 @@
+// ---------------------------------------------------------------------------
+// @dex-ai/vue-tui — useFocusList composable
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for useFocusList.
+ */
+export interface UseFocusListOptions {
+	/** Number of items, or a getter that returns the count. */
+	count: number | (() => number);
+	/** Whether navigation wraps around. Default: true. */
+	wrap?: boolean | undefined;
+	/** Initial focused index. Default: 0. */
+	initialIndex?: number | undefined;
+}
+
+/**
+ * Return type for useFocusList.
+ */
+export interface FocusListState {
+	/** Currently focused index. */
+	index: number;
+	/** Move focus up (decrement). */
+	up(): void;
+	/** Move focus down (increment). */
+	down(): void;
+	/** Set focus to a specific index. */
+	set(i: number): void;
+	/**
+	 * Handle a key event. Returns true if consumed.
+	 * Handles "up" and "down" key names.
+	 */
+	handleKey(key: { name: string }): boolean;
+}
+
+/**
+ * Composable for managing a focused index in a list.
+ * Handles up/down navigation with optional wrapping.
+ */
+export function useFocusList(options: UseFocusListOptions): FocusListState {
+	const wrap = options.wrap ?? true;
+	let index = options.initialIndex ?? 0;
+
+	function getCount(): number {
+		return typeof options.count === "function" ? options.count() : options.count;
+	}
+
+	function up(): void {
+		const count = getCount();
+		if (count === 0) return;
+		if (index > 0) {
+			index--;
+		} else if (wrap) {
+			index = count - 1;
+		}
+	}
+
+	function down(): void {
+		const count = getCount();
+		if (count === 0) return;
+		if (index < count - 1) {
+			index++;
+		} else if (wrap) {
+			index = 0;
+		}
+	}
+
+	function set(i: number): void {
+		const count = getCount();
+		if (i >= 0 && i < count) {
+			index = i;
+		}
+	}
+
+	function handleKey(key: { name: string }): boolean {
+		if (key.name === "up") {
+			up();
+			return true;
+		}
+		if (key.name === "down") {
+			down();
+			return true;
+		}
+		return false;
+	}
+
+	const state: FocusListState = {
+		get index() {
+			return index;
+		},
+		set index(v: number) {
+			set(v);
+		},
+		up,
+		down,
+		set,
+		handleKey,
+	};
+
+	return state;
+}

package/src/composables/useForm.ts

@@ -0,0 +1,335 @@
+// ---------------------------------------------------------------------------
+// @dex-ai/vue-tui — useForm composable
+// ---------------------------------------------------------------------------
+
+import type { FormField, FormState, FormActions, FormResult } from "../types/form";
+import { useFocusList } from "./useFocusList";
+
+/**
+ * Options for useForm.
+ */
+export interface UseFormOptions {
+	/** Field definitions. */
+	fields: FormField[];
+	/** Called when the form is submitted with valid values. */
+	onSubmit?: ((values: Record<string, string | boolean>) => void) | undefined;
+	/** Called when the form is cancelled (Escape at top level). */
+	onCancel?: (() => void) | undefined;
+}
+
+/**
+ * Return type for useForm.
+ */
+export interface UseFormReturn {
+	/** The field definitions (passed through for rendering). */
+	fields: FormField[];
+	/** Reactive form state. */
+	state: FormState;
+	/** Actions to manipulate form state. */
+	actions: FormActions;
+	/** Current result — check after handleKey to see if form should dismiss. */
+	result: FormResult;
+}
+
+/**
+ * Composable that manages a multi-field form with focus navigation,
+ * inline editing, validation, and submission.
+ *
+ * Key bindings (not editing):
+ * - ↑/↓ — navigate fields
+ * - Enter/Tab — start editing (or toggle checkbox)
+ * - Space — toggle checkbox
+ * - Ctrl+S — submit
+ * - Escape — cancel form
+ *
+ * Key bindings (editing):
+ * - Printable chars — append to buffer
+ * - Backspace — delete from buffer
+ * - Enter/Tab — confirm edit, advance to next field
+ * - Escape — revert edit
+ */
+export function useForm(options: UseFormOptions): UseFormReturn {
+	const { fields } = options;
+
+	// Count of navigable fields (skip readonly for editing, but still focusable)
+	const focusList = useFocusList({
+		count: fields.length,
+		wrap: true,
+		initialIndex: 0,
+	});
+
+	// Initialize values from field defaults
+	const values: Record<string, string | boolean> = {};
+	for (const field of fields) {
+		if (field.value !== undefined) {
+			values[field.key] = field.value;
+		} else if (field.type === "checkbox") {
+			values[field.key] = false;
+		} else {
+			values[field.key] = "";
+		}
+	}
+
+	let editing = false;
+	let editBuffer = "";
+	let errors: Record<string, string> = {};
+	let submitted = false;
+	let result: FormResult = { status: "pending" };
+
+	// --- State accessors ---
+
+	const state: FormState = {
+		get values() {
+			return values;
+		},
+		get focusedIndex() {
+			return focusList.index;
+		},
+		get editing() {
+			return editing;
+		},
+		get editBuffer() {
+			return editBuffer;
+		},
+		get errors() {
+			return errors;
+		},
+		get submitted() {
+			return submitted;
+		},
+	};
+
+	// --- Actions ---
+
+	function focusUp(): void {
+		if (editing) return;
+		focusList.up();
+	}
+
+	function focusDown(): void {
+		if (editing) return;
+		focusList.down();
+	}
+
+	function currentField(): FormField | undefined {
+		return fields[focusList.index];
+	}
+
+	function startEdit(): void {
+		const field = currentField();
+		if (!field || field.readonly) return;
+		if (field.type === "checkbox") {
+			toggle();
+			return;
+		}
+		editing = true;
+		const current = values[field.key];
+		editBuffer = typeof current === "string" ? current : "";
+	}
+
+	function confirmEdit(): void {
+		if (!editing) return;
+		const field = currentField();
+		if (!field) return;
+
+		// Apply the edit
+		values[field.key] = editBuffer;
+		editing = false;
+		editBuffer = "";
+
+		// Clear error for this field
+		delete errors[field.key];
+
+		// Run field validation
+		if (field.validate) {
+			const err = field.validate(values[field.key]!);
+			if (err) {
+				errors[field.key] = err;
+			}
+		}
+	}
+
+	function cancelEdit(): void {
+		if (!editing) return;
+		editing = false;
+		editBuffer = "";
+	}
+
+	function type(char: string): void {
+		if (!editing) return;
+		editBuffer += char;
+	}
+
+	function backspace(): void {
+		if (!editing) return;
+		editBuffer = editBuffer.slice(0, -1);
+	}
+
+	function toggle(): void {
+		const field = currentField();
+		if (!field || field.readonly || field.type !== "checkbox") return;
+		values[field.key] = !values[field.key];
+	}
+
+	function validate(): boolean {
+		errors = {};
+		let valid = true;
+
+		for (const field of fields) {
+			const value = values[field.key];
+
+			// Required check
+			if (field.required && !field.readonly) {
+				if (
+					value === undefined ||
+					value === "" ||
+					value === false
+				) {
+					errors[field.key] = `${field.label} is required`;
+					valid = false;
+					continue;
+				}
+			}
+
+			// Custom validation
+			if (field.validate && value !== undefined) {
+				const err = field.validate(value);
+				if (err) {
+					errors[field.key] = err;
+					valid = false;
+				}
+			}
+		}
+
+		return valid;
+	}
+
+	function submit(): Record<string, string | boolean> | null {
+		// Confirm any in-progress edit
+		if (editing) confirmEdit();
+
+		submitted = true;
+
+		if (!validate()) {
+			// Focus first errored field
+			const firstError = fields.findIndex((f) => errors[f.key]);
+			if (firstError >= 0) {
+				focusList.set(firstError);
+			}
+			return null;
+		}
+
+		result = { status: "submitted", values: { ...values } };
+		options.onSubmit?.({ ...values });
+		return { ...values };
+	}
+
+	function reset(): void {
+		for (const field of fields) {
+			if (field.value !== undefined) {
+				values[field.key] = field.value;
+			} else if (field.type === "checkbox") {
+				values[field.key] = false;
+			} else {
+				values[field.key] = "";
+			}
+		}
+		editing = false;
+		editBuffer = "";
+		errors = {};
+		submitted = false;
+		result = { status: "pending" };
+		focusList.set(0);
+	}
+
+	function handleKey(key: {
+		name: string;
+		char?: string | undefined;
+		ctrl?: boolean | undefined;
+		shift?: boolean | undefined;
+	}): boolean {
+		// --- Editing mode ---
+		if (editing) {
+			if (key.name === "enter" || key.name === "tab") {
+				confirmEdit();
+				// Tab advances to next field
+				if (key.name === "tab") {
+					focusList.down();
+				}
+				return true;
+			}
+			if (key.name === "escape") {
+				cancelEdit();
+				return true;
+			}
+			if (key.name === "backspace") {
+				backspace();
+				return true;
+			}
+			if (key.name === "char" && key.char) {
+				type(key.char);
+				return true;
+			}
+			// Ignore other keys in edit mode
+			return true;
+		}
+
+		// --- Navigation mode ---
+		if (key.name === "up") {
+			focusUp();
+			return true;
+		}
+		if (key.name === "down") {
+			focusDown();
+			return true;
+		}
+		if (key.name === "enter" || key.name === "tab") {
+			startEdit();
+			return true;
+		}
+		if (key.name === "char" && key.char === " ") {
+			const field = currentField();
+			if (field?.type === "checkbox") {
+				toggle();
+				return true;
+			}
+			// Space on non-checkbox starts edit
+			startEdit();
+			return true;
+		}
+		if (key.name === "s" && key.ctrl) {
+			submit();
+			return true;
+		}
+		if (key.name === "escape") {
+			result = { status: "cancelled" };
+			options.onCancel?.();
+			return true;
+		}
+
+		return false;
+	}
+
+	const actions: FormActions = {
+		focusUp,
+		focusDown,
+		startEdit,
+		confirmEdit,
+		cancelEdit,
+		type,
+		backspace,
+		toggle,
+		submit,
+		reset,
+		handleKey,
+	};
+
+	return {
+		fields,
+		state,
+		actions,
+		get result() {
+			return result;
+		},
+	};
+}

package/src/composables/useSelectList.ts

@@ -0,0 +1,199 @@
+// ---------------------------------------------------------------------------
+// @dex-ai/vue-tui — useSelectList composable
+// ---------------------------------------------------------------------------
+
+/**
+ * Options for useSelectList.
+ */
+export interface UseSelectListOptions {
+	/** Available items, or a getter. */
+	items: string[] | (() => string[]);
+	/** Whether type-ahead filtering is enabled. Default: true. */
+	allowFilter?: boolean | undefined;
+	/** Maximum number of visible items (for scroll windowing). */
+	maxVisible?: number | undefined;
+	/** Called when an item is selected. */
+	onSelect?: ((item: string, index: number) => void) | undefined;
+}
+
+/**
+ * Return type for useSelectList.
+ */
+export interface SelectListState {
+	/** Filtered items (or all items if filter is empty). */
+	readonly filtered: string[];
+	/** Currently highlighted index within filtered list. */
+	selectedIndex: number;
+	/** Current filter string. */
+	filter: string;
+	/** Scroll offset for windowed display. */
+	readonly scrollOffset: number;
+	/** Move highlight up. */
+	up(): void;
+	/** Move highlight down. */
+	down(): void;
+	/** Confirm selection. Returns the selected item or null. */
+	select(): string | null;
+	/** Append a character to the filter. */
+	type(char: string): void;
+	/** Delete last character from the filter. */
+	backspace(): void;
+	/** Clear the filter. */
+	clearFilter(): void;
+	/**
+	 * Handle a key event. Returns true if consumed.
+	 * Handles: up, down, enter (select), backspace, printable chars.
+	 */
+	handleKey(key: { name: string; char?: string | undefined }): boolean;
+}
+
+/**
+ * Composable for a filterable select list with type-ahead and scroll windowing.
+ */
+export function useSelectList(options: UseSelectListOptions): SelectListState {
+	const allowFilter = options.allowFilter ?? true;
+	const maxVisible = options.maxVisible ?? 10;
+
+	let filter = "";
+	let selectedIndex = 0;
+	let scrollOffset = 0;
+
+	function getItems(): string[] {
+		return typeof options.items === "function" ? options.items() : options.items;
+	}
+
+	function getFiltered(): string[] {
+		const items = getItems();
+		if (!filter) return items;
+		const lower = filter.toLowerCase();
+		return items.filter((item) => item.toLowerCase().includes(lower));
+	}
+
+	function clampIndex(): void {
+		const filtered = getFiltered();
+		if (filtered.length === 0) {
+			selectedIndex = 0;
+		} else if (selectedIndex >= filtered.length) {
+			selectedIndex = filtered.length - 1;
+		}
+	}
+
+	function updateScroll(): void {
+		const filtered = getFiltered();
+		const visCount = Math.min(maxVisible, filtered.length);
+		if (selectedIndex < scrollOffset) {
+			scrollOffset = selectedIndex;
+		} else if (selectedIndex >= scrollOffset + visCount) {
+			scrollOffset = selectedIndex - visCount + 1;
+		}
+	}
+
+	function up(): void {
+		const filtered = getFiltered();
+		if (filtered.length === 0) return;
+		if (selectedIndex > 0) {
+			selectedIndex--;
+		} else {
+			selectedIndex = filtered.length - 1;
+		}
+		updateScroll();
+	}
+
+	function down(): void {
+		const filtered = getFiltered();
+		if (filtered.length === 0) return;
+		if (selectedIndex < filtered.length - 1) {
+			selectedIndex++;
+		} else {
+			selectedIndex = 0;
+		}
+		updateScroll();
+	}
+
+	function select(): string | null {
+		const filtered = getFiltered();
+		if (filtered.length === 0) return null;
+		const item = filtered[selectedIndex];
+		if (item === undefined) return null;
+		options.onSelect?.(item, selectedIndex);
+		return item;
+	}
+
+	function type(char: string): void {
+		if (!allowFilter) return;
+		filter += char;
+		clampIndex();
+		updateScroll();
+	}
+
+	function backspace(): void {
+		if (!allowFilter || filter.length === 0) return;
+		filter = filter.slice(0, -1);
+		clampIndex();
+		updateScroll();
+	}
+
+	function clearFilter(): void {
+		filter = "";
+		clampIndex();
+		updateScroll();
+	}
+
+	function handleKey(key: { name: string; char?: string | undefined }): boolean {
+		if (key.name === "up") {
+			up();
+			return true;
+		}
+		if (key.name === "down") {
+			down();
+			return true;
+		}
+		if (key.name === "enter") {
+			select();
+			return true;
+		}
+		if (key.name === "backspace") {
+			backspace();
+			return true;
+		}
+		if (key.name === "char" && key.char) {
+			type(key.char);
+			return true;
+		}
+		return false;
+	}
+
+	const state: SelectListState = {
+		get filtered() {
+			return getFiltered();
+		},
+		get selectedIndex() {
+			return selectedIndex;
+		},
+		set selectedIndex(v: number) {
+			selectedIndex = v;
+			clampIndex();
+			updateScroll();
+		},
+		get filter() {
+			return filter;
+		},
+		set filter(v: string) {
+			filter = v;
+			clampIndex();
+			updateScroll();
+		},
+		get scrollOffset() {
+			return scrollOffset;
+		},
+		up,
+		down,
+		select,
+		type,
+		backspace,
+		clearFilter,
+		handleKey,
+	};
+
+	return state;
+}

package/src/env.d.ts

@@ -0,0 +1,6 @@
+// Type shim for .vue files
+declare module "*.vue" {
+  import type { Component } from "@vue/runtime-core";
+  const component: Component;
+  export default component;
+}