@viyv/agent-ui-schema 0.1.0

package/src/__tests__/expression.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest';
+import { isExpression, parseExpression } from '../expression.js';
+
+describe('isExpression', () => {
+	it('returns true for $-prefixed strings', () => {
+		expect(isExpression('$hook.sales')).toBe(true);
+		expect(isExpression('$state.filter')).toBe(true);
+	});
+
+	it('returns false for non-expressions', () => {
+		expect(isExpression('hello')).toBe(false);
+		expect(isExpression(42)).toBe(false);
+		expect(isExpression(null)).toBe(false);
+	});
+});
+
+describe('parseExpression', () => {
+	it('parses $hook.xxx', () => {
+		const ref = parseExpression('$hook.sales');
+		expect(ref).toEqual({ type: 'hook', hookId: 'sales', path: [] });
+	});
+
+	it('parses $hook.xxx.data.nested', () => {
+		const ref = parseExpression('$hook.sales.data.items');
+		expect(ref).toEqual({ type: 'hook', hookId: 'sales', path: ['data', 'items'] });
+	});
+
+	it('parses $state.xxx', () => {
+		const ref = parseExpression('$state.filter');
+		expect(ref).toEqual({ type: 'state', key: 'filter' });
+	});
+
+	it('parses $bindState.xxx', () => {
+		const ref = parseExpression('$bindState.searchTerm');
+		expect(ref).toEqual({ type: 'bindState', key: 'searchTerm' });
+	});
+
+	it('parses $action.xxx', () => {
+		const ref = parseExpression('$action.refresh');
+		expect(ref).toEqual({ type: 'action', actionId: 'refresh' });
+	});
+
+	it('parses $expr(...)', () => {
+		const ref = parseExpression('$expr(hook.sales.length > 0)');
+		expect(ref).toEqual({ type: 'expr', code: 'hook.sales.length > 0' });
+	});
+
+	it('parses $hook with deep nesting (a.b.c.d)', () => {
+		const ref = parseExpression('$hook.data.a.b.c.d');
+		expect(ref).toEqual({ type: 'hook', hookId: 'data', path: ['a', 'b', 'c', 'd'] });
+	});
+
+	it('parses hook IDs with hyphens', () => {
+		const ref = parseExpression('$hook.my-hook');
+		expect(ref).toEqual({ type: 'hook', hookId: 'my-hook', path: [] });
+	});
+
+	it('parses state keys with hyphens', () => {
+		const ref = parseExpression('$state.my-state');
+		expect(ref).toEqual({ type: 'state', key: 'my-state' });
+	});
+
+	it('parses action IDs with hyphens', () => {
+		const ref = parseExpression('$action.my-action');
+		expect(ref).toEqual({ type: 'action', actionId: 'my-action' });
+	});
+
+	it('parses $expr with nested parentheses', () => {
+		const ref = parseExpression('$expr(Math.max(hook.a, hook.b))');
+		expect(ref).toEqual({ type: 'expr', code: 'Math.max(hook.a, hook.b)' });
+	});
+
+	it('parses $item (whole object)', () => {
+		const ref = parseExpression('$item');
+		expect(ref).toEqual({ type: 'item', path: [] });
+	});
+
+	it('parses $item.name', () => {
+		const ref = parseExpression('$item.name');
+		expect(ref).toEqual({ type: 'item', path: ['name'] });
+	});
+
+	it('parses $item.a.b.c (deep path)', () => {
+		const ref = parseExpression('$item.a.b.c');
+		expect(ref).toEqual({ type: 'item', path: ['a', 'b', 'c'] });
+	});
+
+	it('returns null for invalid expressions', () => {
+		expect(parseExpression('$invalid')).toBeNull();
+		expect(parseExpression('$')).toBeNull();
+		expect(parseExpression('$$hook.x')).toBeNull();
+	});
+});

package/src/__tests__/page-spec.test.ts

@@ -0,0 +1,242 @@
+import { describe, expect, it } from 'vitest';
+import { ActionDefSchema } from '../action-def.js';
+import { PageSpecSchema } from '../page-spec.js';
+import { validatePageSpec } from '../validator.js';
+
+describe('ActionDefSchema — CRUD actions', () => {
+	it('parses addItem action', () => {
+		const result = ActionDefSchema.safeParse({
+			type: 'addItem',
+			hookId: 'tasks',
+			stateKey: 'newTask',
+			idPrefix: 'TASK',
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it('parses removeItem action', () => {
+		const result = ActionDefSchema.safeParse({
+			type: 'removeItem',
+			hookId: 'tasks',
+			key: 'id',
+			stateKey: 'editingTask',
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it('parses updateItem action', () => {
+		const result = ActionDefSchema.safeParse({
+			type: 'updateItem',
+			hookId: 'tasks',
+			key: 'id',
+			stateKey: 'editingTask',
+			onComplete: { showEditDialog: false },
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it('parses setState with onComplete', () => {
+		const result = ActionDefSchema.safeParse({
+			type: 'setState',
+			key: 'showDialog',
+			value: true,
+			onComplete: { newTask: { title: '' } },
+		});
+		expect(result.success).toBe(true);
+	});
+
+	it('rejects addItem without required hookId', () => {
+		const result = ActionDefSchema.safeParse({
+			type: 'addItem',
+			stateKey: 'newTask',
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it('rejects removeItem without required key', () => {
+		const result = ActionDefSchema.safeParse({
+			type: 'removeItem',
+			hookId: 'tasks',
+			stateKey: 'editingTask',
+		});
+		expect(result.success).toBe(false);
+	});
+
+	it('rejects updateItem without required stateKey', () => {
+		const result = ActionDefSchema.safeParse({
+			type: 'updateItem',
+			hookId: 'tasks',
+			key: 'id',
+		});
+		expect(result.success).toBe(false);
+	});
+});
+
+describe('validatePageSpec — CRUD hookId validation', () => {
+	const baseSpec = {
+		id: 'test',
+		title: 'Test',
+		root: 'root',
+		elements: { root: { type: 'Stack', props: {} } },
+		state: {},
+	};
+
+	it('errors when hookId references undefined hook', () => {
+		const result = validatePageSpec({
+			...baseSpec,
+			hooks: {},
+			actions: {
+				add: { type: 'addItem', hookId: 'missing', stateKey: 'x' },
+			},
+		});
+		expect(result.valid).toBe(false);
+		expect(result.errors.some((e) => e.message.includes('"missing" not defined'))).toBe(true);
+	});
+
+	it('errors when hookId references non-useState hook', () => {
+		const result = validatePageSpec({
+			...baseSpec,
+			hooks: {
+				derived: { use: 'useDerived', from: 'tasks', params: {} },
+				tasks: { use: 'useState', params: { initial: [] } },
+			},
+			actions: {
+				add: { type: 'addItem', hookId: 'derived', stateKey: 'x' },
+			},
+		});
+		expect(result.valid).toBe(false);
+		expect(result.errors.some((e) => e.message.includes('not useState'))).toBe(true);
+	});
+
+	it('passes when hookId references useState hook', () => {
+		const result = validatePageSpec({
+			...baseSpec,
+			hooks: {
+				tasks: { use: 'useState', params: { initial: [] } },
+			},
+			actions: {
+				add: { type: 'addItem', hookId: 'tasks', stateKey: 'newTask' },
+			},
+		});
+		expect(result.valid).toBe(true);
+	});
+
+	it('errors for removeItem targeting non-useState hook', () => {
+		const result = validatePageSpec({
+			...baseSpec,
+			hooks: {
+				tasks: { use: 'useState', params: { initial: [] } },
+				derived: { use: 'useDerived', from: 'tasks', params: {} },
+			},
+			actions: {
+				remove: { type: 'removeItem', hookId: 'derived', key: 'id', stateKey: 'x' },
+			},
+		});
+		expect(result.valid).toBe(false);
+		expect(result.errors.some((e) => e.message.includes('not useState'))).toBe(true);
+	});
+
+	it('errors for updateItem targeting undefined hook', () => {
+		const result = validatePageSpec({
+			...baseSpec,
+			hooks: {},
+			actions: {
+				update: { type: 'updateItem', hookId: 'missing', key: 'id', stateKey: 'x' },
+			},
+		});
+		expect(result.valid).toBe(false);
+		expect(result.errors.some((e) => e.message.includes('"missing" not defined'))).toBe(true);
+	});
+
+	it('does not validate refreshHook hookId against useState', () => {
+		const result = validatePageSpec({
+			...baseSpec,
+			hooks: {
+				data: {
+					use: 'useSqlQuery',
+					params: { connection: 'db', query: 'SELECT 1' },
+				},
+			},
+			actions: {
+				refresh: { type: 'refreshHook', hookId: 'data' },
+			},
+		});
+		expect(result.valid).toBe(true);
+	});
+});
+
+describe('PageSpecSchema', () => {
+	it('validates a minimal page spec', () => {
+		const spec = {
+			id: 'test-page',
+			title: 'Test Page',
+			root: 'root',
+			elements: {
+				root: { type: 'Stack', props: { direction: 'vertical' } },
+			},
+		};
+
+		const result = PageSpecSchema.safeParse(spec);
+		expect(result.success).toBe(true);
+		if (result.success) {
+			expect(result.data.id).toBe('test-page');
+			expect(result.data.hooks).toEqual({});
+			expect(result.data.state).toEqual({});
+			expect(result.data.actions).toEqual({});
+		}
+	});
+
+	it('validates a full page spec with hooks and actions', () => {
+		const spec = {
+			id: 'sales-dashboard',
+			title: 'Sales Dashboard',
+			description: 'Monthly sales overview',
+			root: 'root',
+			elements: {
+				root: {
+					type: 'Stack',
+					props: { direction: 'vertical' },
+					children: ['header', 'table'],
+				},
+				header: { type: 'Header', props: { title: 'Sales' } },
+				table: {
+					type: 'DataTable',
+					props: { data: '$hook.sales', columns: [] },
+				},
+			},
+			hooks: {
+				sales: {
+					use: 'useSqlQuery',
+					params: {
+						connection: 'main-db',
+						query: 'SELECT * FROM sales',
+						refreshInterval: 60000,
+					},
+				},
+			},
+			state: { filter: '' },
+			actions: {
+				refresh: { type: 'refreshHook', hookId: 'sales' },
+			},
+			theme: { colorScheme: 'light', spacing: 'default' },
+		};
+
+		const result = PageSpecSchema.safeParse(spec);
+		expect(result.success).toBe(true);
+	});
+
+	it('rejects invalid hook definitions', () => {
+		const spec = {
+			id: 'test',
+			title: 'Test',
+			root: 'root',
+			elements: { root: { type: 'Stack', props: {} } },
+			hooks: {
+				bad: { use: 'useInvalid', params: {} },
+			},
+		};
+
+		const result = PageSpecSchema.safeParse(spec);
+		expect(result.success).toBe(false);
+	});
+});

package/src/__tests__/validator.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, it } from 'vitest';
+import { validatePageSpec } from '../validator.js';
+
+describe('validatePageSpec', () => {
+	const validSpec = {
+		id: 'test',
+		title: 'Test',
+		root: 'root',
+		elements: {
+			root: {
+				type: 'Stack',
+				props: { direction: 'vertical' },
+				children: ['header'],
+			},
+			header: { type: 'Header', props: { title: 'Hello' } },
+		},
+		hooks: {},
+		state: {},
+		actions: {},
+	};
+
+	it('validates a correct spec', () => {
+		const result = validatePageSpec(validSpec);
+		expect(result.valid).toBe(true);
+		expect(result.errors).toHaveLength(0);
+	});
+
+	it('detects missing root element', () => {
+		const result = validatePageSpec({
+			...validSpec,
+			root: 'nonexistent',
+		});
+		expect(result.valid).toBe(false);
+		expect(result.errors.some((e) => e.message.includes('Root element'))).toBe(true);
+	});
+
+	it('detects missing child references', () => {
+		const result = validatePageSpec({
+			...validSpec,
+			elements: {
+				root: {
+					type: 'Stack',
+					props: {},
+					children: ['missing-child'],
+				},
+			},
+		});
+		expect(result.valid).toBe(false);
+		expect(result.errors.some((e) => e.message.includes('Child element'))).toBe(true);
+	});
+
+	it('detects undefined hook references', () => {
+		const result = validatePageSpec({
+			...validSpec,
+			elements: {
+				root: {
+					type: 'DataTable',
+					props: { data: '$hook.nonexistent' },
+				},
+			},
+		});
+		expect(result.valid).toBe(false);
+		expect(result.errors.some((e) => e.message.includes('Hook "nonexistent"'))).toBe(true);
+	});
+
+	it('detects unsafe SQL', () => {
+		const result = validatePageSpec({
+			...validSpec,
+			hooks: {
+				bad: {
+					use: 'useSqlQuery',
+					params: {
+						connection: 'db',
+						query: 'DROP TABLE users',
+					},
+				},
+			},
+		});
+		expect(result.valid).toBe(false);
+		expect(result.errors.some((e) => e.message.includes('unsafe SQL'))).toBe(true);
+	});
+
+	it('detects hook cycle', () => {
+		const result = validatePageSpec({
+			...validSpec,
+			hooks: {
+				a: { use: 'useDerived', from: 'b', params: {} },
+				b: { use: 'useDerived', from: 'a', params: {} },
+			},
+		});
+		expect(result.valid).toBe(false);
+		expect(result.errors.some((e) => e.message.includes('Circular dependency'))).toBe(true);
+	});
+
+	it('validates action references in elements', () => {
+		const result = validatePageSpec({
+			...validSpec,
+			elements: {
+				root: {
+					type: 'Button',
+					props: { onClick: '$action.nonexistent' },
+				},
+			},
+		});
+		expect(result.valid).toBe(false);
+		expect(result.errors.some((e) => e.message.includes('Action "nonexistent"'))).toBe(true);
+	});
+
+	it('rejects non-SELECT SQL queries', () => {
+		const result = validatePageSpec({
+			...validSpec,
+			hooks: {
+				insert: {
+					use: 'useSqlQuery',
+					params: {
+						connection: 'db',
+						query: 'INSERT INTO users VALUES (1)',
+					},
+				},
+			},
+		});
+		expect(result.valid).toBe(false);
+	});
+
+	it('detects dangling useDerived source', () => {
+		const result = validatePageSpec({
+			...validSpec,
+			hooks: {
+				derived: { use: 'useDerived', from: 'nonexistent', params: {} },
+			},
+		});
+		expect(result.valid).toBe(false);
+		expect(result.errors.some((e) => e.message.includes('undefined source hook'))).toBe(true);
+	});
+
+	it('validates visibility expression hook references', () => {
+		const result = validatePageSpec({
+			...validSpec,
+			elements: {
+				root: {
+					type: 'Stack',
+					props: {},
+					visible: { expr: '$hook.nonexistent' },
+				},
+			},
+		});
+		expect(result.valid).toBe(false);
+		expect(result.errors.some((e) => e.path.includes('visible.expr'))).toBe(true);
+	});
+
+	it('no warning for $item inside Repeater descendant', () => {
+		const result = validatePageSpec({
+			...validSpec,
+			elements: {
+				root: {
+					type: 'Repeater',
+					props: { data: '$hook.items' },
+					children: ['itemText'],
+				},
+				itemText: {
+					type: 'Text',
+					props: { content: '$item.name' },
+				},
+			},
+			hooks: {
+				items: {
+					use: 'useSqlQuery',
+					params: { connection: 'viyv-db', query: 'SELECT name FROM items' },
+				},
+			},
+		});
+		expect(result.valid).toBe(true);
+		expect(result.warnings).toHaveLength(0);
+	});
+
+	it('warns for $item outside Repeater context', () => {
+		const result = validatePageSpec({
+			...validSpec,
+			elements: {
+				root: {
+					type: 'Text',
+					props: { content: '$item.name' },
+				},
+			},
+		});
+		expect(result.valid).toBe(true); // warning, not error
+		expect(result.warnings.some((w) => w.message.includes('$item expression used outside Repeater'))).toBe(true);
+	});
+});

package/src/action-def.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+
+export const SetStateActionSchema = z.object({
+	type: z.literal('setState'),
+	key: z.string().min(1),
+	value: z.unknown().optional(),
+	onComplete: z.record(z.unknown()).optional(),
+});
+
+export const RefreshHookActionSchema = z.object({
+	type: z.literal('refreshHook'),
+	hookId: z.string().min(1),
+});
+
+export const NavigateActionSchema = z.object({
+	type: z.literal('navigate'),
+	url: z.string().min(1),
+});
+
+export const SubmitFormActionSchema = z.object({
+	type: z.literal('submitForm'),
+	url: z.string().min(1),
+	method: z.enum(['POST', 'PUT', 'PATCH']).default('POST'),
+	stateKey: z.string().optional(),
+	onComplete: z.record(z.unknown()).optional(),
+});
+
+export const AddItemActionSchema = z.object({
+	type: z.literal('addItem'),
+	hookId: z.string().min(1),
+	stateKey: z.string().min(1),
+	idField: z.string().optional(),
+	idPrefix: z.string().optional(),
+	onComplete: z.record(z.unknown()).optional(),
+});
+
+export const RemoveItemActionSchema = z.object({
+	type: z.literal('removeItem'),
+	hookId: z.string().min(1),
+	key: z.string().min(1),
+	stateKey: z.string().min(1),
+	onComplete: z.record(z.unknown()).optional(),
+});
+
+export const UpdateItemActionSchema = z.object({
+	type: z.literal('updateItem'),
+	hookId: z.string().min(1),
+	key: z.string().min(1),
+	stateKey: z.string().min(1),
+	onComplete: z.record(z.unknown()).optional(),
+});
+
+export const ActionDefSchema = z.discriminatedUnion('type', [
+	SetStateActionSchema,
+	RefreshHookActionSchema,
+	NavigateActionSchema,
+	SubmitFormActionSchema,
+	AddItemActionSchema,
+	RemoveItemActionSchema,
+	UpdateItemActionSchema,
+]);
+
+export type ActionDef = z.infer<typeof ActionDefSchema>;

package/src/catalog.ts

@@ -0,0 +1,24 @@
+import type { z } from 'zod';
+
+export interface ComponentMeta {
+	type: string;
+	label: string;
+	description: string;
+	category: 'layout' | 'display' | 'data' | 'chart' | 'input' | 'control' | 'navigation' | 'overlay' | 'feedback' | 'map';
+	propsSchema: z.ZodType;
+	acceptsChildren: boolean;
+	/** When true, ElementRenderer passes `open` prop from visibility instead of unmounting */
+	overlay?: boolean;
+}
+
+export interface ComponentCatalog {
+	components: Record<string, ComponentMeta>;
+}
+
+export function defineCatalog(components: ComponentMeta[]): ComponentCatalog {
+	const map: Record<string, ComponentMeta> = {};
+	for (const comp of components) {
+		map[comp.type] = comp;
+	}
+	return { components: map };
+}

package/src/data-source.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+
+export const ColumnMetaSchema = z.object({
+	name: z.string().min(1),
+	type: z.string().min(1),
+	nullable: z.boolean().default(false),
+	description: z.string().optional(),
+});
+
+export const TableMetaSchema = z.object({
+	name: z.string().min(1),
+	columns: z.array(ColumnMetaSchema),
+	description: z.string().optional(),
+	rowCount: z.number().optional(),
+});
+
+export const EndpointMetaSchema = z.object({
+	path: z.string().min(1),
+	method: z.enum(['GET', 'POST']),
+	description: z.string().optional(),
+	responseSchema: z.record(z.unknown()).optional(),
+});
+
+export const DataSourceMetaSchema = z.object({
+	id: z.string().min(1),
+	name: z.string().min(1),
+	type: z.enum(['sql', 'rest', 'static']),
+	description: z.string().optional(),
+	tables: z.array(TableMetaSchema).optional(),
+	endpoints: z.array(EndpointMetaSchema).optional(),
+});
+
+export type ColumnMeta = z.infer<typeof ColumnMetaSchema>;
+export type TableMeta = z.infer<typeof TableMetaSchema>;
+export type EndpointMeta = z.infer<typeof EndpointMetaSchema>;
+export type DataSourceMeta = z.infer<typeof DataSourceMetaSchema>;
+
+/**
+ * DataConnector port interface.
+ * Implemented in the server package for each data source type.
+ */
+export interface DataConnector {
+	readonly meta: DataSourceMeta;
+	describe(): Promise<DataSourceMeta>;
+	query(params: Record<string, unknown>): Promise<unknown>;
+}

package/src/element-def.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+
+export const VisibilityConditionSchema = z
+	.object({
+		expr: z.string(),
+	})
+	.optional();
+
+export const ElementDefSchema = z.object({
+	type: z.string().min(1),
+	props: z.record(z.unknown()).default({}),
+	children: z.array(z.string().min(1)).optional(),
+	visible: VisibilityConditionSchema,
+});
+
+export type ElementDef = z.infer<typeof ElementDefSchema>;
+export type VisibilityCondition = z.infer<typeof VisibilityConditionSchema>;