@dragcraft/form-generator 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT hackycy <https://github.com/hackycy>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,357 @@
+import { Component, ComputedRef, InjectionKey, PropType, Ref, VNodeChild } from "vue";
+import { I18nInstance } from "@dragcraft/i18n";
+//#region src/types.d.ts
+/**
+ * Context object passed to visible/disabled predicates.
+ * Provides access to the current form values so fields can react to each other.
+ */
+interface FormContext {
+  /** Current flat key-value map of all form field values */
+  values: Record<string, unknown>;
+}
+/**
+ * Validation rule for a single field.
+ */
+interface ValidationRule {
+  /** If true (or predicate returns true), the field must have a non-empty/non-null value */
+  required?: boolean | ((ctx: FormContext) => boolean);
+  /** Error message to display when validation fails */
+  message?: string;
+  /** Custom validator returning true (pass) or a string (error message) */
+  validator?: (value: unknown, ctx: FormContext) => boolean | string;
+  /** Minimum value (number only) */
+  min?: number;
+  /** Maximum value (number only) */
+  max?: number;
+  /** Minimum string length */
+  minLength?: number;
+  /** Maximum string length */
+  maxLength?: number;
+  /** Regex pattern the string must match */
+  pattern?: RegExp;
+  /** Value must be one of these */
+  enum?: unknown[];
+}
+/**
+ * Validation error associated with a specific field.
+ */
+interface ValidationError {
+  key: string;
+  message: string;
+}
+/**
+ * Describes a single form field.
+ */
+type FieldComponentProps<Props extends object = Record<string, unknown>> = Props | ((ctx: FormContext) => Props);
+/**
+ * Reactive form state available to an inline field render factory.
+ */
+interface FieldRenderContext {
+  /** Dependency-resolved field schema. */
+  field: ComputedRef<FieldSchema>;
+  /** Reactive flat key-value map of all form field values. */
+  values: Record<string, unknown>;
+  /** Current formatted field value. */
+  value: ComputedRef<unknown>;
+  /** Resolved global and field-level disabled state. */
+  disabled: ComputedRef<boolean>;
+  /** Resolved static or dynamic component props, including i18n transforms. */
+  componentProps: ComputedRef<Record<string, unknown>>;
+  /** Translate a message key, with an optional fallback. */
+  t: (key: string, fallback?: string) => string;
+  /** Write a value through the field parse, change, and validation pipeline. */
+  setValue: (value: unknown) => void;
+  /** Validate the field against its current resolved schema. */
+  validate: () => void;
+}
+/**
+ * Creates inline field content from reactive form state.
+ *
+ * Any function assigned to FieldSchema.component is treated as a render
+ * factory. Reusable Vue functional components must be registered under a
+ * string key in FieldComponentMap.
+ */
+type FieldRenderFactory = (ctx: FieldRenderContext) => () => VNodeChild;
+type FieldBindingScope = 'node' | 'schema' | 'globalConfig' | 'container';
+interface FieldBindingTarget {
+  /** The document area this field writes to. Defaults depend on the host form. */
+  scope?: FieldBindingScope;
+  /** Dot path inside the selected scope. */
+  path: string;
+}
+interface FieldSchema<ComponentType extends string | FieldRenderFactory = string | FieldRenderFactory, ComponentProps extends object = Record<string, unknown>> {
+  /** Property key in the values object (e.g., 'text', 'fontSize') */
+  key: string;
+  /** Human-readable label */
+  label: string;
+  /** i18n message key for label; overrides `label` when i18n is active */
+  labelKey?: string;
+  /** i18n message key for placeholder; overrides field.componentProps.placeholder when i18n is active */
+  placeholderKey?: string;
+  /**
+   * i18n key prefix for select/radio option labels.
+   * Each option label is resolved as `${optionKeyPrefix}.${option.value}`.
+   * Falls back to the static `option.label` when the key is missing.
+   */
+  optionKeyPrefix?: string;
+  /** Registered field component name or an inline field render factory. */
+  component: ComponentType;
+  /** Optional DSL path binding used by host applications such as the designer. */
+  bindTo?: string | FieldBindingTarget;
+  /** Props forwarded to the registered UI component. Static or dynamic. */
+  componentProps?: FieldComponentProps<ComponentProps>;
+  /** Declares which other fields this field depends on, and how to react. */
+  dependencies?: FieldDependencies<FieldSchema<ComponentType, ComponentProps>>;
+  /** If false (or predicate returns false), field is hidden via CSS (preserves DOM state). */
+  show?: boolean | ((ctx: FormContext) => boolean);
+  /** If false (or predicate returns false), field is removed from DOM entirely. */
+  ifShow?: boolean | ((ctx: FormContext) => boolean);
+  /** Transform value before writing to form model (input -> model). */
+  parseValue?: (value: unknown, ctx: FormContext) => unknown;
+  /** Transform value before passing to component (model -> component). */
+  valueFormat?: (value: unknown, ctx: FormContext) => unknown;
+  /** Default value used when the actual value is undefined */
+  defaultValue?: unknown;
+  /** Dynamic visibility predicate */
+  visible?: (ctx: FormContext) => boolean;
+  /** Dynamic disabled predicate */
+  disabled?: (ctx: FormContext) => boolean;
+  /** Validation rules */
+  rules?: ValidationRule[];
+  /** Optional tooltip / help text */
+  tooltip?: string;
+  /** Number of grid columns this field spans (requires section.columns > 1) */
+  span?: number;
+}
+/**
+ * Declares dependencies on other fields and how to react when they change.
+ */
+interface FieldDependencies<Field extends FieldSchema<string | FieldRenderFactory, object> = FieldSchema> {
+  /** Field keys this field depends on. */
+  fields: string[];
+  /**
+   * Called when any dependency field changes.
+   * Returns partial FieldSchema overrides.
+   * Cannot override key, component, or dependencies (to prevent cycles).
+   */
+  handler: (form: Record<string, unknown>, fieldValue: unknown) => Partial<Omit<Field, 'key' | 'component' | 'dependencies'>>;
+}
+/**
+ * A titled group of fields.
+ */
+interface SectionSchema<Field extends FieldSchema<string | FieldRenderFactory, object> = FieldSchema> {
+  title: string;
+  /** i18n message key for title; overrides `title` when i18n is active */
+  titleKey?: string;
+  /** Whether the section starts collapsed. Defaults to false. */
+  collapsed?: boolean;
+  fields: Field[];
+  /** Number of grid columns. Defaults to 1 (vertical stack). */
+  columns?: number;
+}
+/**
+ * Top-level schema that FormGenerator accepts.
+ */
+interface FormSchema<Field extends FieldSchema<string | FieldRenderFactory, object> = FieldSchema> {
+  sections: Array<SectionSchema<Field>>;
+}
+type TypedFieldSchema<PropsMap extends object> = { [ComponentType in Extract<keyof PropsMap, string>]: PropsMap[ComponentType] extends object ? FieldSchema<ComponentType, PropsMap[ComponentType]> : never; }[Extract<keyof PropsMap, string>] | FieldSchema<FieldRenderFactory>;
+type TypedSectionSchema<PropsMap extends object> = SectionSchema<TypedFieldSchema<PropsMap>>;
+type TypedFormSchema<PropsMap extends object> = FormSchema<TypedFieldSchema<PropsMap>>;
+interface FieldComponentTransformContext {
+  field: FieldSchema;
+  values: Record<string, unknown>;
+}
+/**
+ * Describes how a schema field binds to a concrete Vue UI component.
+ */
+interface FieldComponentDefinition {
+  /** Vue component rendered for this field type. */
+  component: Component;
+  /** Prop name used by the UI component as its model value. Defaults to `modelValue`. */
+  modelPropName?: string;
+  /** Event prop used to receive model updates. Defaults to `onUpdate:modelValue`. */
+  updateEventName?: string;
+  /** Default UI component props merged before field.componentProps. */
+  defaultProps?: Record<string, unknown>;
+  /** Transform model value before passing it to the UI component. */
+  formatValue?: (value: unknown, ctx: FieldComponentTransformContext) => unknown;
+  /** Transform UI component value before writing it to the form model. */
+  normalizeValue?: (value: unknown, ctx: FieldComponentTransformContext) => unknown;
+}
+/**
+ * Maps field component names (e.g., 'Input', 'Select') to component adapters.
+ */
+type FieldComponentMap = Record<string, FieldComponentDefinition>;
+/**
+ * Props accepted by the FormGenerator root component.
+ */
+interface FormGeneratorProps {
+  /** Schema describing sections and fields to render */
+  schema: FormSchema;
+  /** Current values keyed by field key */
+  values: Record<string, unknown>;
+  /** Globally disable all fields */
+  disabled?: boolean;
+  /** Field components keyed by schema component name */
+  fieldComponentMap?: FieldComponentMap;
+}
+/**
+ * Change event payload emitted by FormGenerator.
+ */
+interface FieldChangePayload {
+  /** Which field changed */
+  key: string;
+  /** New value */
+  value: unknown;
+}
+/**
+ * Section toggle event payload.
+ */
+interface SectionTogglePayload {
+  /** Index of the section in the schema */
+  index: number;
+  /** Title of the section */
+  title: string;
+  /** Whether the section is now collapsed */
+  collapsed: boolean;
+}
+/**
+ * Internal context provided to all FormGenerator descendants via provide/inject.
+ */
+interface FormGeneratorContext {
+  /** Field component map available to nested fields */
+  fieldComponentMap: FieldComponentMap;
+  /** Callback invoked when any field value changes */
+  onFieldChange: (key: string, value: unknown) => void;
+  /** Read a specific field value from the current model */
+  getFieldValue: (key: string) => unknown;
+  /** Get all current values as a snapshot */
+  getFormValues: () => Record<string, unknown>;
+  /** Reactive values — use for fine-grained dependency tracking in computed/watch */
+  values: Record<string, unknown>;
+  /** Global disabled ref */
+  disabled: Ref<boolean>;
+  /** Map of field key -> validation error messages (reactive) */
+  fieldErrors: Ref<Record<string, string | undefined>>;
+  /** Validate a specific field, optionally with a resolved field for dependency-driven rules */
+  validateField: (key: string, resolvedField?: FieldSchema) => string | undefined;
+}
+/**
+ * Injection key for the form generator context.
+ */
+declare const FORM_GENERATOR_CONTEXT_KEY: InjectionKey<FormGeneratorContext>;
+//#endregion
+//#region src/components/FormGenerator.d.ts
+declare const _default: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  schema: {
+    type: PropType<FormSchema>;
+    required: true;
+  };
+  values: {
+    type: PropType<Record<string, unknown>>;
+    required: true;
+  };
+  disabled: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  fieldComponentMap: {
+    type: PropType<FieldComponentMap>;
+    default: undefined;
+  };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+  change: (_payload: FieldChangePayload) => true;
+  'section:toggle': (_payload: SectionTogglePayload) => true;
+  submit: (_values: Record<string, unknown>) => true;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  schema: {
+    type: PropType<FormSchema>;
+    required: true;
+  };
+  values: {
+    type: PropType<Record<string, unknown>>;
+    required: true;
+  };
+  disabled: {
+    type: BooleanConstructor;
+    default: boolean;
+  };
+  fieldComponentMap: {
+    type: PropType<FieldComponentMap>;
+    default: undefined;
+  };
+}>> & Readonly<{
+  onChange?: ((_payload: FieldChangePayload) => any) | undefined;
+  "onSection:toggle"?: ((_payload: SectionTogglePayload) => any) | undefined;
+  onSubmit?: ((_values: Record<string, unknown>) => any) | undefined;
+}>, {
+  disabled: boolean;
+  fieldComponentMap: FieldComponentMap;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+//#endregion
+//#region src/composables/useFieldDependencies.d.ts
+interface FieldDependenciesResult {
+  resolvedField: ComputedRef<FieldSchema>;
+}
+type FieldSource = FieldSchema | (() => FieldSchema);
+/**
+ * Resolves dynamic field schema overrides driven by explicit field dependencies.
+ * When a field declares `dependencies`, this composable watches those fields
+ * and merges the handler's return into a resolved FieldSchema.
+ */
+declare function useFieldDependencies(field: FieldSource, ctx: FormGeneratorContext): FieldDependenciesResult;
+//#endregion
+//#region src/composables/useFieldState.d.ts
+/**
+ * Reactive interaction state computed for a single field.
+ */
+interface FieldState {
+  /** Whether the field should be rendered in the DOM (ifShow / visible). */
+  isVisible: ComputedRef<boolean>;
+  /** Whether the field should be visually displayed (show -- CSS visibility). */
+  isShown: ComputedRef<boolean>;
+  /** Whether the field is disabled. */
+  isDisabled: ComputedRef<boolean>;
+}
+/**
+ * Computes reactive visibility, display, and disabled state for a given field.
+ * Evaluates the field's predicates against the current form values.
+ */
+declare function useFieldState(getField: () => FieldSchema, ctx: FormGeneratorContext): FieldState;
+//#endregion
+//#region src/composables/useFormValidation.d.ts
+/**
+ * Form-level validation interface.
+ */
+interface FormValidation {
+  /** Reactive map of field key -> error message (undefined = no error) */
+  fieldErrors: Ref<Record<string, string | undefined>>;
+  /** Validate a single field by key. Optionally pass a resolved field for dependency-driven rules. */
+  validateField: (key: string, resolvedField?: FieldSchema) => string | undefined;
+  /** Validate all fields. Returns array of errors (empty = all valid). */
+  validateAll: () => ValidationError[];
+  /** Clear all validation errors */
+  clearErrors: () => void;
+}
+type FormSchemaSource = FormSchema | (() => FormSchema);
+declare function findFieldSchema(schema: FormSchema, key: string): FieldSchema | undefined;
+/**
+ * Creates a form-level validation system.
+ * Validates fields against their rules and tracks errors reactively.
+ */
+declare function useFormValidation(schema: FormSchemaSource, getValues: () => Record<string, unknown>, resolveField?: (key: string) => FieldSchema | undefined): FormValidation;
+//#endregion
+//#region src/context.d.ts
+/**
+ * Injects the FormGeneratorContext from the nearest ancestor FormGenerator.
+ * Throws if called outside a FormGenerator tree.
+ */
+declare function useFormGeneratorContext(): FormGeneratorContext;
+//#endregion
+//#region src/utils.d.ts
+declare function resolveFieldComponentProps(field: FieldSchema, formCtx: FormContext, t: I18nInstance['t']): Record<string, unknown>;
+//#endregion
+export { FORM_GENERATOR_CONTEXT_KEY, type FieldBindingScope, type FieldBindingTarget, type FieldChangePayload, type FieldComponentDefinition, type FieldComponentMap, type FieldComponentProps, type FieldComponentTransformContext, type FieldDependencies, type FieldDependenciesResult, type FieldRenderContext, type FieldRenderFactory, type FieldSchema, type FieldState, type FormContext, _default as FormGenerator, type FormGeneratorContext, type FormGeneratorProps, type FormSchema, type FormValidation, type SectionSchema, type SectionTogglePayload, type TypedFieldSchema, type TypedFormSchema, type TypedSectionSchema, type ValidationError, type ValidationRule, findFieldSchema, resolveFieldComponentProps, useFieldDependencies, useFieldState, useFormGeneratorContext, useFormValidation };

package/dist/index.mjs

@@ -0,0 +1,491 @@
+import { computed, defineComponent, h, inject, provide, reactive, ref, watch } from "vue";
+import { useI18n } from "@dragcraft/i18n";
+import { IconChevronDown } from "@dragcraft/icons";
+//#region src/utils.ts
+function createFormContext(values) {
+	return { values };
+}
+function copyFormValues(values) {
+	return { ...values };
+}
+function resolveFieldModelValue(field, values) {
+	const value = values[field.key];
+	return value === void 0 ? field.defaultValue : value;
+}
+function syncReactiveRecord(target, source) {
+	for (const key of Object.keys(target)) if (!(key in source)) delete target[key];
+	for (const [key, value] of Object.entries(source)) target[key] = value;
+}
+function evaluateBoolean(value, ctx, defaultValue) {
+	if (value === void 0) return defaultValue;
+	return typeof value === "function" ? value(ctx) : value;
+}
+function resolveFieldDependencies(field, values, fieldValue) {
+	if (!field.dependencies) return field;
+	const overrides = field.dependencies.handler(copyFormValues(values), fieldValue);
+	return {
+		...field,
+		...overrides,
+		key: field.key,
+		component: field.component,
+		dependencies: field.dependencies
+	};
+}
+function resolveFieldComponentProps(field, formCtx, t) {
+	const resolvedProps = { ...typeof field.componentProps === "function" ? field.componentProps(formCtx) : field.componentProps ?? {} };
+	if (field.placeholderKey) resolvedProps.placeholder = t(field.placeholderKey, String(resolvedProps.placeholder ?? ""));
+	if (field.optionKeyPrefix && Array.isArray(resolvedProps.options)) resolvedProps.options = resolvedProps.options.map((option) => {
+		if (!option || typeof option !== "object" || !("value" in option)) return option;
+		const value = option.value;
+		const label = "label" in option ? String(option.label ?? "") : "";
+		return {
+			...option,
+			label: t(`${field.optionKeyPrefix}.${String(value)}`, label)
+		};
+	});
+	return resolvedProps;
+}
+//#endregion
+//#region src/composables/useFormValidation.ts
+function resolveSchema(schema) {
+	return typeof schema === "function" ? schema() : schema;
+}
+function createFieldIndex(schema) {
+	const index = /* @__PURE__ */ new Map();
+	for (const section of schema.sections) for (const field of section.fields) {
+		if (index.has(field.key)) console.warn(`[dragcraft/form-generator] Duplicate field key "${field.key}" found in schema.`);
+		index.set(field.key, field);
+	}
+	return index;
+}
+function findFieldSchema(schema, key) {
+	for (const section of schema.sections) for (const field of section.fields) if (field.key === key) return field;
+}
+function isEmptyValue(value) {
+	return value === null || value === void 0 || value === "";
+}
+function shouldValidateField(field, formCtx) {
+	return evaluateBoolean(field.ifShow !== void 0 ? field.ifShow : field.visible, formCtx, true) && evaluateBoolean(field.show, formCtx, true);
+}
+function runFieldValidation(field, value, formCtx) {
+	if (!field.rules || field.rules.length === 0) return void 0;
+	for (const rule of field.rules) {
+		if ((typeof rule.required === "function" ? rule.required(formCtx) : rule.required) && isEmptyValue(value)) return rule.message ?? "This field is required";
+		if (rule.min !== void 0 && typeof value === "number" && value < rule.min) return rule.message ?? `Value must be at least ${rule.min}`;
+		if (rule.max !== void 0 && typeof value === "number" && value > rule.max) return rule.message ?? `Value must be at most ${rule.max}`;
+		if (rule.minLength !== void 0 && typeof value === "string" && value.length < rule.minLength) return rule.message ?? `Must be at least ${rule.minLength} characters`;
+		if (rule.maxLength !== void 0 && typeof value === "string" && value.length > rule.maxLength) return rule.message ?? `Must be at most ${rule.maxLength} characters`;
+		if (rule.pattern && typeof value === "string") {
+			rule.pattern.lastIndex = 0;
+			if (!rule.pattern.test(value)) return rule.message ?? "Invalid format";
+		}
+		if (rule.enum && !rule.enum.includes(value)) return rule.message ?? `Must be one of: ${rule.enum.join(", ")}`;
+		if (rule.validator) {
+			const result = rule.validator(value, formCtx);
+			if (typeof result === "string") return result;
+			if (result === false) return rule.message ?? "Validation failed";
+		}
+	}
+}
+/**
+* Creates a form-level validation system.
+* Validates fields against their rules and tracks errors reactively.
+*/
+function useFormValidation(schema, getValues, resolveField) {
+	const fieldErrors = ref({});
+	const currentSchema = () => resolveSchema(schema);
+	let cachedSchema;
+	let cachedFieldIndex = /* @__PURE__ */ new Map();
+	const getFieldIndex = () => {
+		const schema = currentSchema();
+		if (schema !== cachedSchema) {
+			cachedSchema = schema;
+			cachedFieldIndex = createFieldIndex(schema);
+		}
+		return cachedFieldIndex;
+	};
+	const validateField = (key, resolvedField) => {
+		const field = resolvedField ?? getFieldIndex().get(key);
+		if (!field) return void 0;
+		const values = getValues();
+		const value = resolveFieldModelValue(field, values);
+		const formCtx = createFormContext(values);
+		if (!shouldValidateField(field, formCtx)) {
+			fieldErrors.value = {
+				...fieldErrors.value,
+				[key]: void 0
+			};
+			return;
+		}
+		const error = runFieldValidation(field, value, formCtx);
+		fieldErrors.value = {
+			...fieldErrors.value,
+			[key]: error
+		};
+		return error;
+	};
+	const validateAll = () => {
+		const errors = [];
+		const values = getValues();
+		const formCtx = createFormContext(values);
+		const newFieldErrors = {};
+		for (const section of currentSchema().sections) for (const field of section.fields) {
+			const resolved = resolveField?.(field.key) ?? field;
+			const value = resolveFieldModelValue(resolved, values);
+			if (!shouldValidateField(resolved, formCtx)) {
+				newFieldErrors[resolved.key] = void 0;
+				continue;
+			}
+			const error = runFieldValidation(resolved, value, formCtx);
+			newFieldErrors[resolved.key] = error;
+			if (error) errors.push({
+				key: resolved.key,
+				message: error
+			});
+		}
+		fieldErrors.value = newFieldErrors;
+		return errors;
+	};
+	const clearErrors = () => {
+		fieldErrors.value = {};
+	};
+	return {
+		fieldErrors,
+		validateField,
+		validateAll,
+		clearErrors
+	};
+}
+//#endregion
+//#region src/types.ts
+/**
+* Injection key for the form generator context.
+*/
+const FORM_GENERATOR_CONTEXT_KEY = Symbol("dc-form-generator");
+//#endregion
+//#region src/composables/useFieldDependencies.ts
+function resolveFieldSource(field) {
+	return typeof field === "function" ? field() : field;
+}
+function createDependencySnapshot(field, values) {
+	const snapshot = {};
+	for (const key of field.dependencies?.fields ?? []) snapshot[key] = values[key];
+	return snapshot;
+}
+/**
+* Resolves dynamic field schema overrides driven by explicit field dependencies.
+* When a field declares `dependencies`, this composable watches those fields
+* and merges the handler's return into a resolved FieldSchema.
+*/
+function useFieldDependencies(field, ctx) {
+	return { resolvedField: computed(() => {
+		const currentField = resolveFieldSource(field);
+		if (!currentField.dependencies) return currentField;
+		return resolveFieldDependencies(currentField, createDependencySnapshot(currentField, ctx.values), ctx.getFieldValue(currentField.key));
+	}) };
+}
+//#endregion
+//#region src/composables/useFieldState.ts
+/**
+* Computes reactive visibility, display, and disabled state for a given field.
+* Evaluates the field's predicates against the current form values.
+*/
+function useFieldState(getField, ctx) {
+	const getFormContext = () => createFormContext(ctx.values);
+	return {
+		isVisible: computed(() => {
+			const field = getField();
+			return evaluateBoolean(field.ifShow !== void 0 ? field.ifShow : field.visible, getFormContext(), true);
+		}),
+		isShown: computed(() => {
+			return evaluateBoolean(getField().show, getFormContext(), true);
+		}),
+		isDisabled: computed(() => {
+			const field = getField();
+			if (ctx.disabled.value) return true;
+			if (!field.disabled) return false;
+			return evaluateBoolean(field.disabled, getFormContext(), false);
+		})
+	};
+}
+//#endregion
+//#region src/context.ts
+/**
+* Injects the FormGeneratorContext from the nearest ancestor FormGenerator.
+* Throws if called outside a FormGenerator tree.
+*/
+function useFormGeneratorContext() {
+	const ctx = inject(FORM_GENERATOR_CONTEXT_KEY);
+	if (!ctx) throw new Error("[dragcraft/form-generator] FormGeneratorContext not found. Ensure this component is a descendant of FormGenerator.");
+	return ctx;
+}
+//#endregion
+//#region src/components/FormField.ts
+var FormField_default = defineComponent({
+	name: "DcFormField",
+	props: { field: {
+		type: Object,
+		required: true
+	} },
+	setup(props) {
+		const ctx = useFormGeneratorContext();
+		const { t } = useI18n();
+		const { resolvedField } = useFieldDependencies(() => props.field, ctx);
+		const { isVisible, isShown, isDisabled } = useFieldState(() => resolvedField.value, ctx);
+		const value = computed(() => {
+			const field = resolvedField.value;
+			const modelValue = resolveFieldModelValue(field, ctx.values);
+			return field.valueFormat?.(modelValue, createFormContext(ctx.values)) ?? modelValue;
+		});
+		const componentProps = computed(() => resolveFieldComponentProps(resolvedField.value, createFormContext(ctx.values), t));
+		const validate = () => {
+			const field = resolvedField.value;
+			ctx.validateField(field.key, field);
+		};
+		const setValue = (value) => {
+			const field = resolvedField.value;
+			const transformed = field.parseValue?.(value, createFormContext(ctx.values)) ?? value;
+			ctx.onFieldChange(field.key, transformed);
+			validate();
+		};
+		const fieldRender = typeof props.field.component === "function" ? props.field.component({
+			field: resolvedField,
+			values: ctx.values,
+			value,
+			disabled: isDisabled,
+			componentProps,
+			t,
+			setValue,
+			validate
+		}) : void 0;
+		const renderRegisteredField = (field, disabled) => {
+			const definition = typeof field.component === "string" ? ctx.fieldComponentMap[field.component] : void 0;
+			const transformCtx = {
+				field,
+				values: ctx.values
+			};
+			const currentValue = definition?.formatValue?.(value.value, transformCtx) ?? value.value;
+			const FieldComponent = definition?.component;
+			const fieldContent = definition && FieldComponent ? h(FieldComponent, {
+				...definition.defaultProps,
+				...componentProps.value,
+				disabled,
+				[definition.modelPropName ?? "modelValue"]: currentValue,
+				[definition.updateEventName ?? "onUpdate:modelValue"]: (value) => {
+					const normalized = definition.normalizeValue?.(value, transformCtx) ?? value;
+					setValue(normalized);
+				}
+			}) : h("div", {
+				"class": "dc-field-unknown",
+				"data-dc-part": "unknown"
+			}, `Unknown field: ${String(field.component)}`);
+			return [h("label", {
+				"class": "dc-form-field__label",
+				"data-dc-part": "label"
+			}, field.labelKey ? t(field.labelKey, field.label) : field.label), h("div", {
+				"class": "dc-form-field__control",
+				"data-dc-part": "control"
+			}, [fieldContent])];
+		};
+		return () => {
+			if (!isVisible.value) return null;
+			const field = resolvedField.value;
+			const errorMsg = ctx.fieldErrors.value[field.key];
+			const disabled = isDisabled.value;
+			const children = fieldRender ? [fieldRender()] : renderRegisteredField(field, disabled);
+			if (field.tooltip) children.push(h("div", {
+				"class": "dc-form-field__tooltip",
+				"data-dc-part": "tooltip"
+			}, field.tooltip));
+			if (errorMsg) children.push(h("div", {
+				"class": "dc-form-field__error",
+				"data-dc-part": "error"
+			}, errorMsg));
+			const span = field.span ?? 1;
+			const wrapperClass = ["dc-form-field", {
+				"dc-form-field--disabled": disabled,
+				"dc-form-field--error": !!errorMsg
+			}];
+			const wrapperStyle = {};
+			if (span > 1) {
+				wrapperClass.push(`dc-form-field--span-${span}`);
+				wrapperStyle["--_dc-span"] = String(span);
+			}
+			if (!isShown.value) wrapperStyle.display = "none";
+			return h("div", {
+				"class": wrapperClass,
+				"style": wrapperStyle,
+				"data-dc-component": "form-field",
+				"data-dc-state": [disabled ? "disabled" : null, errorMsg ? "error" : null].filter(Boolean).join(" ") || void 0
+			}, children);
+		};
+	}
+});
+//#endregion
+//#region src/components/FormSection.ts
+var FormSection_default = defineComponent({
+	name: "DcFormSection",
+	props: {
+		section: {
+			type: Object,
+			required: true
+		},
+		onToggle: {
+			type: Function,
+			default: void 0
+		}
+	},
+	setup(props) {
+		const { t } = useI18n();
+		const collapsed = ref(props.section.collapsed ?? false);
+		watch(() => props.section.collapsed, (val) => {
+			if (val !== void 0) collapsed.value = val;
+		});
+		const toggleCollapse = () => {
+			collapsed.value = !collapsed.value;
+			props.onToggle?.(collapsed.value);
+		};
+		return () => {
+			const section = props.section;
+			const columns = section.columns ?? 1;
+			const header = h("button", {
+				"type": "button",
+				"class": "dc-form-section__header",
+				"data-dc-part": "header",
+				"aria-expanded": !collapsed.value,
+				"onClick": toggleCollapse
+			}, [h("span", {
+				"class": "dc-form-section__title",
+				"data-dc-part": "title"
+			}, section.titleKey ? t(section.titleKey, section.title) : section.title), h("span", {
+				"class": collapsed.value ? "dc-form-section__toggle dc-form-section__toggle--collapsed" : "dc-form-section__toggle",
+				"data-dc-part": "toggle"
+			}, [h(IconChevronDown, { size: 15 })])]);
+			if (collapsed.value) return h("div", {
+				"class": "dc-form-section",
+				"data-dc-component": "form-section",
+				"data-dc-state": "collapsed"
+			}, [header]);
+			const bodyClass = ["dc-form-section__body"];
+			const bodyStyle = {};
+			if (columns > 1) {
+				bodyClass.push("dc-form-section--grid");
+				bodyStyle["--_dc-columns"] = String(columns);
+			}
+			return h("div", {
+				"class": "dc-form-section",
+				"data-dc-component": "form-section",
+				"data-dc-state": "expanded"
+			}, [header, h("div", {
+				"class": bodyClass,
+				"style": bodyStyle,
+				"data-dc-part": "body"
+			}, section.fields.map((field) => h(FormField_default, {
+				key: field.key,
+				field
+			})))]);
+		};
+	}
+});
+//#endregion
+//#region src/components/FormGenerator.ts
+function createDependencyIndex(schema) {
+	const index = /* @__PURE__ */ new Map();
+	for (const section of schema.sections) for (const field of section.fields) for (const dependencyKey of field.dependencies?.fields ?? []) {
+		const dependentKeys = index.get(dependencyKey) ?? [];
+		dependentKeys.push(field.key);
+		index.set(dependencyKey, dependentKeys);
+	}
+	return index;
+}
+var FormGenerator_default = defineComponent({
+	name: "DcFormGenerator",
+	props: {
+		schema: {
+			type: Object,
+			required: true
+		},
+		values: {
+			type: Object,
+			required: true
+		},
+		disabled: {
+			type: Boolean,
+			default: false
+		},
+		fieldComponentMap: {
+			type: Object,
+			default: void 0
+		}
+	},
+	emits: {
+		"change": (_payload) => true,
+		"section:toggle": (_payload) => true,
+		"submit": (_values) => true
+	},
+	setup(props, { emit, expose }) {
+		const localValues = reactive(copyFormValues(props.values));
+		watch(() => props.values, (newValues) => {
+			syncReactiveRecord(localValues, newValues);
+		}, { deep: true });
+		const fieldComponentMapRef = computed(() => props.fieldComponentMap ?? {});
+		const dependencyIndex = computed(() => createDependencyIndex(props.schema));
+		const getFormValues = () => copyFormValues(localValues);
+		const resolveField = (key) => {
+			const field = findFieldSchema(props.schema, key);
+			return field ? resolveFieldDependencies(field, localValues, localValues[key]) : void 0;
+		};
+		const { fieldErrors, validateField, validateAll, clearErrors } = useFormValidation(() => props.schema, getFormValues, resolveField);
+		const validateResolvedField = (key, resolvedField) => {
+			const field = resolvedField ?? resolveField(key);
+			if (field) validateField(key, field);
+		};
+		const onFieldChange = (key, value) => {
+			localValues[key] = value;
+			emit("change", {
+				key,
+				value
+			});
+			for (const dependentKey of dependencyIndex.value.get(key) ?? []) validateResolvedField(dependentKey);
+		};
+		provide(FORM_GENERATOR_CONTEXT_KEY, {
+			get fieldComponentMap() {
+				return fieldComponentMapRef.value;
+			},
+			onFieldChange,
+			getFieldValue: (key) => localValues[key],
+			getFormValues,
+			values: localValues,
+			disabled: computed(() => props.disabled),
+			fieldErrors,
+			validateField
+		});
+		const submit = () => {
+			emit("submit", getFormValues());
+		};
+		expose({
+			validate: validateAll,
+			clearErrors,
+			submit
+		});
+		return () => {
+			const schema = props.schema;
+			return h("div", {
+				"class": "dc-form-generator",
+				"data-dc-component": "form-generator"
+			}, schema.sections.map((section, i) => h(FormSection_default, {
+				key: `${section.title}-${i}`,
+				section,
+				onToggle: (collapsed) => {
+					emit("section:toggle", {
+						index: i,
+						title: section.title,
+						collapsed
+					});
+				}
+			})));
+		};
+	}
+});
+//#endregion
+export { FORM_GENERATOR_CONTEXT_KEY, FormGenerator_default as FormGenerator, findFieldSchema, resolveFieldComponentProps, useFieldDependencies, useFieldState, useFormGeneratorContext, useFormValidation };

package/dist/structure.css

@@ -0,0 +1,69 @@
+.dc-form-generator, .dc-form-section, .dc-form-section__header, .dc-form-section__body, .dc-form-field, .dc-form-field__control, .dc-field-unknown {
+  box-sizing: border-box;
+}
+
+.dc-field-unknown {
+  border: 1px dashed #0000;
+}
+
+.dc-form-generator {
+  padding: 0 12px;
+}
+
+.dc-form-section {
+  margin-bottom: 4px;
+}
+
+.dc-form-section__header {
+  text-align: left;
+  cursor: pointer;
+  user-select: none;
+  border: 0;
+  justify-content: space-between;
+  align-items: center;
+  width: 100%;
+  min-height: 34px;
+  padding: 0 6px;
+  display: flex;
+}
+
+.dc-form-section__toggle {
+  flex: none;
+  display: inline-flex;
+}
+
+.dc-form-section__toggle--collapsed {
+  transform: rotate(-90deg);
+}
+
+.dc-form-section__body {
+  padding-bottom: 8px;
+}
+
+.dc-form-section--grid {
+  grid-template-columns: repeat(var(--_dc-columns), minmax(0, 1fr));
+  gap: 10px 12px;
+  display: grid;
+}
+
+.dc-form-field {
+  flex-direction: column;
+  gap: 4px;
+  margin-bottom: 10px;
+  display: flex;
+}
+
+.dc-form-section--grid > .dc-form-field {
+  grid-column: span min(var(--_dc-span, 1), var(--_dc-columns));
+  min-width: 0;
+  margin-bottom: 0;
+}
+
+.dc-form-field__control {
+  width: 100%;
+  min-width: 0;
+}
+
+.dc-field-unknown {
+  padding: 6px 8px;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@dragcraft/form-generator",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "@dragcraft/form-generator",
+  "author": "hackycy <hackycy@outlook.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/hackycy/dragcraft#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hackycy/dragcraft.git"
+  },
+  "bugs": "https://github.com/hackycy/dragcraft/issues",
+  "keywords": [],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json",
+    "./structure.css": "./dist/structure.css"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "vue": ">=3.0.0"
+  },
+  "dependencies": {
+    "@dragcraft/i18n": "0.0.1",
+    "@dragcraft/icons": "0.0.1"
+  },
+  "devDependencies": {
+    "happy-dom": "^20.10.6",
+    "vitest": "^4.0.7",
+    "vue": "^3.5.27"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "eslint",
+    "release": "bumpp",
+    "start": "tsx src/index.ts",
+    "test": "vitest",
+    "typecheck": "tsc"
+  }
+}