@vibesdotdev/config 0.0.1

package/src/form/core/groups.ts

@@ -0,0 +1,96 @@
+/**
+ * Field Grouping
+ *
+ * Organize fields into groups for UI rendering
+ */
+import type { ConfigManifest, ConfigFieldGroup, ConfigContext } from '../../manifest/types.ts';
+import type { ResolvedField, ResolvedGroup } from './types.ts';
+import { evaluateRule } from './visibility.ts';
+
+/**
+ * Resolve groups with their fields and visibility
+ */
+export function resolveGroups(
+	manifest: ConfigManifest,
+	fields: ResolvedField[],
+	values: Record<string, unknown>,
+	context: ConfigContext
+): ResolvedGroup[] {
+	const groups = manifest.groups || [];
+	const fieldsByGroup = new Map<string | undefined, ResolvedField[]>();
+
+	// Group fields by group ID
+	for (const field of fields) {
+		const groupId = field.meta.ui.group;
+		if (!fieldsByGroup.has(groupId)) {
+			fieldsByGroup.set(groupId, []);
+		}
+		fieldsByGroup.get(groupId)!.push(field);
+	}
+
+	const resolved: ResolvedGroup[] = [];
+
+	// Process defined groups first (in order)
+	const sortedGroups = [...groups].sort((a, b) => (a.order ?? 999) - (b.order ?? 999));
+
+	for (const group of sortedGroups) {
+		const groupFields = fieldsByGroup.get(group.id) || [];
+
+		// Only include groups that have visible fields
+		const visibleFields = groupFields.filter((f) => f.visible);
+		if (visibleFields.length === 0) continue;
+
+		const visible = evaluateRule(group.visibleWhen, values, context);
+
+		resolved.push({
+			group,
+			fields: visibleFields,
+			visible
+		});
+
+		// Remove processed fields
+		fieldsByGroup.delete(group.id);
+	}
+
+	// Add ungrouped fields (no group ID)
+	const ungroupedFields = fieldsByGroup.get(undefined) || [];
+	if (ungroupedFields.length > 0) {
+		const visibleUngrouped = ungroupedFields.filter((f) => f.visible);
+		if (visibleUngrouped.length > 0) {
+			resolved.push({
+				group: {
+					id: '_ungrouped',
+					label: 'Other Settings',
+					order: 9999
+				},
+				fields: visibleUngrouped,
+				visible: true
+			});
+		}
+	}
+
+	return resolved;
+}
+
+/**
+ * Get fields for a specific group
+ */
+export function getGroupFields(groupId: string, fields: ResolvedField[]): ResolvedField[] {
+	return fields.filter((f) => f.meta.ui.group === groupId);
+}
+
+/**
+ * Check if a group should be collapsed by default
+ */
+export function isGroupCollapsed(
+	group: ConfigFieldGroup,
+	userPreferences?: Record<string, boolean>
+): boolean {
+	// Check user preference first
+	if (userPreferences && group.id in userPreferences) {
+		return userPreferences[group.id];
+	}
+
+	// Fall back to group default
+	return group.defaultCollapsed ?? false;
+}

package/src/form/core/index.ts

@@ -0,0 +1,41 @@
+
+export type {
+	RenderContext,
+	ComponentOverride,
+	FormRenderOptions,
+	ResolvedField,
+	ResolvedGroup,
+	FormState,
+	FormActions
+} from './types.ts';
+export {
+	inferFieldComponent,
+	getFieldDefault,
+	resolveFields,
+	groupFields,
+	resolveFieldDefault,
+	resolveDefaults
+} from './field-resolver.ts';
+export type { FieldValidationResult, FormValidationResult } from './validation.ts';
+export {
+	validateField,
+	validateForm,
+	getFieldSchema
+} from './validation.ts';
+export {
+	evaluateRule,
+	isFieldVisible,
+	isFieldDisabled,
+	isFieldRequired
+} from './visibility.ts';
+export {
+	resolveGroups,
+	getGroupFields,
+	isGroupCollapsed
+} from './groups.ts';
+export {
+	getNestedValue,
+	setNestedValue,
+	buildNestedObject,
+	flattenNestedObject
+} from './nested-utils.ts';

package/src/form/core/nested-utils.ts

@@ -0,0 +1,115 @@
+/**
+ * Nested Path Utilities
+ *
+ * Helpers for working with dot-notation paths in nested objects
+ */
+
+/**
+ * Get a value at a dot-notation path from an object
+ * Supports both flat keys (e.g., obj['configuration.apiKey'])
+ * and nested objects (e.g., obj.configuration.apiKey)
+ *
+ * @example
+ * getNestedValue({ a: { b: 1 } }, 'a.b') // => 1
+ * getNestedValue({ 'a.b': 1 }, 'a.b') // => 1
+ */
+export function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+	// First try direct key lookup (for flat form values)
+	if (path in obj) {
+		return obj[path];
+	}
+
+	// Then try dot-notation path lookup (for nested objects)
+	const parts = path.split('.');
+	let current: unknown = obj;
+	for (const part of parts) {
+		if (current == null || typeof current !== 'object') {
+			return undefined;
+		}
+		current = (current as Record<string, unknown>)[part];
+	}
+	return current;
+}
+
+/**
+ * Set a value at a dot-notation path in an object
+ * Creates nested objects as needed
+ *
+ * @example
+ * setNestedValue({}, 'a.b.c', 1) // => { a: { b: { c: 1 } } }
+ */
+export function setNestedValue(
+	obj: Record<string, unknown>,
+	path: string,
+	value: unknown
+): Record<string, unknown> {
+	const parts = path.split('.');
+
+	if (parts.length === 1) {
+		// Simple key, just set it
+		obj[path] = value;
+		return obj;
+	}
+
+	// Navigate/create nested structure
+	let current: Record<string, unknown> = obj;
+	for (let i = 0; i < parts.length - 1; i++) {
+		const part = parts[i];
+		if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+			current[part] = {};
+		}
+		current = current[part] as Record<string, unknown>;
+	}
+
+	// Set the final value
+	current[parts[parts.length - 1]] = value;
+	return obj;
+}
+
+/**
+ * Build a nested object from flat dot-notation keys
+ *
+ * @example
+ * buildNestedObject({ 'a.b': 1, 'a.c': 2, d: 3 })
+ * // => { a: { b: 1, c: 2 }, d: 3 }
+ */
+export function buildNestedObject(flat: Record<string, unknown>): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+
+	for (const [key, value] of Object.entries(flat)) {
+		if (key.includes('.')) {
+			setNestedValue(result, key, value);
+		} else {
+			result[key] = value;
+		}
+	}
+
+	return result;
+}
+
+/**
+ * Flatten a nested object to dot-notation keys
+ *
+ * @example
+ * flattenNestedObject({ a: { b: 1, c: 2 }, d: 3 })
+ * // => { 'a.b': 1, 'a.c': 2, d: 3 }
+ */
+export function flattenNestedObject(
+	nested: Record<string, unknown>,
+	prefix = ''
+): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+
+	for (const [key, value] of Object.entries(nested)) {
+		const fullKey = prefix ? `${prefix}.${key}` : key;
+
+		if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+			// Recurse into nested objects
+			Object.assign(result, flattenNestedObject(value as Record<string, unknown>, fullKey));
+		} else {
+			result[fullKey] = value;
+		}
+	}
+
+	return result;
+}

package/src/form/core/schemas/validation.schema.ts

@@ -0,0 +1,9 @@
+export interface FieldValidationResult {
+	valid: boolean;
+	error?: string;
+}
+
+export interface FormValidationResult {
+	valid: boolean;
+	errors: Record<string, string | undefined>;
+}

package/src/form/core/types.ts

@@ -0,0 +1,115 @@
+/**
+ * Form Renderer Core Types
+ */
+import type { ZodTypeAny } from 'zod/v4';
+import type {
+	ConfigManifest,
+	ConfigFieldMeta,
+	ConfigFieldGroup,
+	ConfigContext,
+	FieldComponent
+} from '../../manifest/types.ts';
+
+/**
+ * Context available during form rendering
+ */
+export interface RenderContext {
+	manifest: ConfigManifest;
+	values: Record<string, unknown>;
+	errors: Record<string, string | undefined>;
+	touched: Record<string, boolean>;
+	context: ConfigContext;
+	onChange: (field: string, value: unknown) => void;
+	onBlur: (field: string) => void;
+}
+
+/**
+ * Override for a specific field's rendering
+ */
+export interface ComponentOverride {
+	/** Replace with custom component */
+	component?: unknown; // Component type varies by surface
+	/** Additional props to pass */
+	props?: Record<string, unknown>;
+	/** Custom render function */
+	render?: (field: ConfigFieldMeta, defaultRender: () => unknown) => unknown;
+	/** Hide this field entirely */
+	hidden?: boolean;
+	/** Render in a named slot instead of inline */
+	slot?: string;
+}
+
+/**
+ * Options for form rendering
+ */
+export interface FormRenderOptions {
+	/** Current field values */
+	values: Record<string, unknown>;
+	/** Field change handler */
+	onChange: (field: string, value: unknown) => void;
+	/** Form submission handler */
+	onSubmit: () => void;
+	/** Field-level overrides */
+	overrides?: Record<string, ComponentOverride>;
+	/** Form layout */
+	layout?: 'vertical' | 'horizontal' | 'grid';
+	/** Runtime context */
+	context?: Partial<ConfigContext>;
+	/** Whether form is disabled */
+	disabled?: boolean;
+	/** Whether form is loading */
+	loading?: boolean;
+}
+
+/**
+ * Result of field resolution
+ */
+export interface ResolvedField {
+	key: string;
+	meta: ConfigFieldMeta;
+	component: FieldComponent;
+	value: unknown;
+	error?: string;
+	visible: boolean;
+	disabled: boolean;
+	required: boolean;
+	override?: ComponentOverride;
+	/** Field's Zod schema (if available) for reference metadata extraction */
+	fieldSchema?: ZodTypeAny;
+}
+
+/**
+ * Result of group resolution
+ */
+export interface ResolvedGroup {
+	group: ConfigFieldGroup;
+	fields: ResolvedField[];
+	visible: boolean;
+}
+
+/**
+ * Form state returned by form hooks/stores
+ */
+export interface FormState<T = Record<string, unknown>> {
+	values: T;
+	errors: Record<string, string | undefined>;
+	touched: Record<string, boolean>;
+	isDirty: boolean;
+	isValid: boolean;
+	isSubmitting: boolean;
+}
+
+/**
+ * Form actions returned by form hooks/stores
+ */
+export interface FormActions<T = Record<string, unknown>> {
+	setValue: (field: keyof T, value: unknown) => void;
+	setValues: (values: Partial<T>) => void;
+	/** Apply values and update dirty baseline — form stays clean after call */
+	resetTo: (values: Partial<T>) => void;
+	setError: (field: keyof T, error: string | undefined) => void;
+	setTouched: (field: keyof T, touched: boolean) => void;
+	reset: () => void;
+	submit: () => Promise<void>;
+	validate: () => Promise<boolean>;
+}

package/src/form/core/validation.ts

@@ -0,0 +1,137 @@
+/**
+ * Form Validation
+ *
+ * Runtime validation using manifest schemas
+ */
+import type { z } from 'zod/v4';
+import type { ConfigManifest } from '../../manifest/types.ts';
+
+import type { FieldValidationResult, FormValidationResult } from './schemas/validation.schema.ts';
+
+export type { FieldValidationResult, FormValidationResult } from './schemas/validation.schema.ts';
+
+/**
+ * Type guard to check if a schema is a ZodObject with a shape property
+ */
+function isZodObjectWithShape(schema: z.ZodTypeAny): schema is z.ZodObject<z.ZodRawShape> {
+	return (
+		schema !== null &&
+		typeof schema === 'object' &&
+		'shape' in schema &&
+		typeof schema.shape === 'object' &&
+		schema.shape !== null
+	);
+}
+
+/**
+ * Get the shape from a ZodObject schema
+ */
+function getObjectShape(schema: z.ZodTypeAny): Record<string, z.ZodTypeAny> | undefined {
+	if (isZodObjectWithShape(schema)) {
+		return schema.shape as Record<string, z.ZodTypeAny>;
+	}
+	return undefined;
+}
+
+/**
+ * Get schema at a dot-notation path
+ */
+function getSchemaAtPath(rootSchema: z.ZodTypeAny, path: string): z.ZodTypeAny | undefined {
+	const parts = path.split('.');
+	let current: z.ZodTypeAny | undefined = rootSchema;
+
+	for (const part of parts) {
+		if (!current) return undefined;
+
+		const shape = getObjectShape(current);
+		if (shape) {
+			current = shape[part];
+		} else {
+			return undefined;
+		}
+	}
+
+	return current;
+}
+
+/**
+ * Validate a single field value against its schema
+ * Supports dot-notation paths for nested fields
+ */
+export function validateField(
+	manifest: ConfigManifest,
+	fieldKey: string,
+	value: unknown
+): FieldValidationResult {
+	try {
+		const schema = manifest.schema;
+
+		// Handle nested paths (e.g., 'configuration.apiKey')
+		const fieldSchema = fieldKey.includes('.')
+			? getSchemaAtPath(schema, fieldKey)
+			: getTopLevelFieldSchema(schema, fieldKey);
+
+		if (fieldSchema) {
+			const result = fieldSchema.safeParse(value);
+			if (!result.success) {
+				const firstError = result.error.issues[0];
+				return { valid: false, error: firstError?.message || 'Invalid value' };
+			}
+		}
+
+		return { valid: true };
+	} catch {
+		return { valid: true }; // If we can't validate, assume valid
+	}
+}
+
+/**
+ * Get schema for a top-level field
+ */
+function getTopLevelFieldSchema(schema: z.ZodTypeAny, fieldKey: string): z.ZodTypeAny | undefined {
+	const shape = getObjectShape(schema);
+	if (shape) {
+		return shape[fieldKey];
+	}
+	return undefined;
+}
+
+/**
+ * Validate all form values against manifest schema
+ */
+export function validateForm(
+	manifest: ConfigManifest,
+	values: Record<string, unknown>
+): FormValidationResult {
+	const errors: Record<string, string | undefined> = {};
+
+	try {
+		const result = manifest.schema.safeParse(values);
+
+		if (!result.success) {
+			for (const issue of result.error.issues) {
+				const path = issue.path.join('.');
+				errors[path] = issue.message;
+			}
+			return { valid: false, errors };
+		}
+
+		return { valid: true, errors };
+	} catch {
+		return { valid: true, errors };
+	}
+}
+
+/**
+ * Get validation schema for a field (for client-side use)
+ */
+export function getFieldSchema(
+	manifest: ConfigManifest,
+	fieldKey: string
+): z.ZodTypeAny | undefined {
+	const shape = getObjectShape(manifest.schema);
+	if (shape) {
+		return shape[fieldKey];
+	}
+	return undefined;
+}

package/src/form/core/visibility.ts

@@ -0,0 +1,172 @@
+/**
+ * Visibility and Rule Evaluation
+ *
+ * Evaluates ConfigRules to determine field visibility, disabled state, etc.
+ */
+import type {
+	ConfigRule,
+	ConfigFieldRule,
+	ConfigContextRule,
+	ConfigAndRule,
+	ConfigOrRule,
+	ConfigNotRule,
+	ConfigFunctionRule,
+	ConfigContext
+} from '../../manifest/types.ts';
+
+/**
+ * Evaluate a configuration rule
+ */
+export function evaluateRule(
+	rule: ConfigRule | undefined,
+	values: Record<string, unknown>,
+	context: ConfigContext
+): boolean {
+	if (!rule) return true;
+
+	// Field-based rule
+	if ('field' in rule) {
+		return evaluateFieldRule(rule as ConfigFieldRule, values);
+	}
+
+	// Context-based rule
+	if ('context' in rule) {
+		return evaluateContextRule(rule as ConfigContextRule, context);
+	}
+
+	// AND rule
+	if ('and' in rule) {
+		return (rule as ConfigAndRule).and.every((r) => evaluateRule(r, values, context));
+	}
+
+	// OR rule
+	if ('or' in rule) {
+		return (rule as ConfigOrRule).or.some((r) => evaluateRule(r, values, context));
+	}
+
+	// NOT rule
+	if ('not' in rule) {
+		return !evaluateRule((rule as ConfigNotRule).not, values, context);
+	}
+
+	// Function rule
+	if ('fn' in rule) {
+		return (rule as ConfigFunctionRule).fn(context, values);
+	}
+
+	return true;
+}
+
+/**
+ * Get a value at a dot-notation path from an object
+ */
+function getValueAtPath(obj: Record<string, unknown>, path: string): unknown {
+	// First try direct key lookup (for flat form values)
+	if (path in obj) {
+		return obj[path];
+	}
+
+	// Then try dot-notation path lookup (for nested objects)
+	const parts = path.split('.');
+	let current: unknown = obj;
+	for (const part of parts) {
+		if (current == null || typeof current !== 'object') {
+			return undefined;
+		}
+		current = (current as Record<string, unknown>)[part];
+	}
+	return current;
+}
+
+/**
+ * Evaluate a field-based rule
+ */
+function evaluateFieldRule(rule: ConfigFieldRule, values: Record<string, unknown>): boolean {
+	const fieldValue = getValueAtPath(values, rule.field);
+
+	switch (rule.operator) {
+		case 'equals':
+			return fieldValue === rule.value;
+		case 'notEquals':
+			return fieldValue !== rule.value;
+		case 'in':
+			return Array.isArray(rule.value) && rule.value.includes(fieldValue);
+		case 'notIn':
+			return Array.isArray(rule.value) && !rule.value.includes(fieldValue);
+		case 'exists':
+			return fieldValue !== undefined && fieldValue !== null;
+		case 'isEmpty':
+			return fieldValue === undefined || fieldValue === null || fieldValue === '';
+		default:
+			return true;
+	}
+}
+
+/**
+ * Evaluate a context-based rule
+ */
+function evaluateContextRule(rule: ConfigContextRule, context: ConfigContext): boolean {
+	let contextValue: unknown;
+
+	// Handle custom context paths
+	if (rule.context.startsWith('custom.')) {
+		const customKey = rule.context.slice(7);
+		contextValue = context.custom[customKey];
+	} else {
+		contextValue = context[rule.context as keyof Omit<ConfigContext, 'get' | 'custom'>];
+	}
+
+	switch (rule.operator) {
+		case 'equals':
+			return contextValue === rule.value;
+		case 'notEquals':
+			return contextValue !== rule.value;
+		case 'in':
+			return Array.isArray(rule.value) && rule.value.includes(contextValue);
+		case 'notIn':
+			return Array.isArray(rule.value) && !rule.value.includes(contextValue);
+		case 'exists':
+			return contextValue !== undefined && contextValue !== null;
+		default:
+			return true;
+	}
+}
+
+/**
+ * Check if a field should be visible
+ */
+export function isFieldVisible(
+	fieldMeta: { rules?: { visibleWhen?: ConfigRule } },
+	values: Record<string, unknown>,
+	context: ConfigContext
+): boolean {
+	return evaluateRule(fieldMeta.rules?.visibleWhen, values, context);
+}
+
+/**
+ * Check if a field should be disabled
+ * Returns false if no disabledWhen rule is defined (field is enabled by default)
+ */
+export function isFieldDisabled(
+	fieldMeta: { rules?: { disabledWhen?: ConfigRule } },
+	values: Record<string, unknown>,
+	context: ConfigContext
+): boolean {
+	// No rule = not disabled (enabled by default)
+	if (!fieldMeta.rules?.disabledWhen) return false;
+	return evaluateRule(fieldMeta.rules.disabledWhen, values, context);
+}
+
+/**
+ * Check if a field is required (beyond schema)
+ * Returns false if no requiredWhen rule is defined (not required by default)
+ */
+export function isFieldRequired(
+	fieldMeta: { rules?: { requiredWhen?: ConfigRule } },
+	values: Record<string, unknown>,
+	context: ConfigContext
+): boolean {
+	// No rule = not required (optional by default)
+	if (!fieldMeta.rules?.requiredWhen) return false;
+	return evaluateRule(fieldMeta.rules.requiredWhen, values, context);
+}