@btst/stack 2.5.6 → 2.6.1

package/dist/components/form-builder/index.d.cts

@@ -0,0 +1,385 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { z } from 'zod';
+import { I as InputPropsByBackingType, c as FieldType, S as SerializableInputProps, J as JSONSchemaPropertyBase, A as AutoFormInputComponentProps } from '../../shared/stack.fdi94T4S.cjs';
+import 'react-hook-form';
+
+/**
+ * Represents a step in a multi-step form.
+ */
+interface FormStep {
+    /** Unique identifier for the step */
+    id: string;
+    /** Display title for the step */
+    title: string;
+}
+/**
+ * JSON Schema types for form builder I/O.
+ * Extends the shared base types with form-builder specific needs.
+ */
+interface JSONSchema {
+    type: "object";
+    properties: Record<string, JSONSchemaProperty>;
+    required?: string[];
+    $schema?: string;
+    /** Step definitions for multi-step forms (stored in schema meta) */
+    steps?: FormStep[];
+    additionalProperties?: boolean;
+}
+/**
+ * JSON Schema property with form-builder metadata.
+ * Extends the shared JSONSchemaPropertyBase for compatibility with auto-form.
+ */
+interface JSONSchemaProperty extends Omit<JSONSchemaPropertyBase, "type" | "enum" | "properties" | "items"> {
+    /** JSON Schema type - required for form-builder fields */
+    type: string;
+    /** Enum values for select/radio fields (string-only for form-builder) */
+    enum?: string[];
+    /** Nested properties for object types (self-referential) */
+    properties?: Record<string, JSONSchemaProperty>;
+    /** Item schema for array types (self-referential) */
+    items?: JSONSchemaProperty;
+    /** Minimum items for array types */
+    minItems?: number;
+    /** Maximum items for array types */
+    maxItems?: number;
+    /** Step group index for multi-step forms (0-indexed) */
+    stepGroup?: number;
+}
+/**
+ * Internal field representation used by form builder.
+ */
+interface FormBuilderField {
+    id: string;
+    type: string;
+    props: FormBuilderFieldProps;
+    /** Nested fields for object type containers */
+    children?: FormBuilderField[];
+    /** Template fields defining the shape of each array item */
+    itemTemplate?: FormBuilderField[];
+    /** Step group index (0-indexed) for multi-step forms */
+    stepGroup?: number;
+}
+/**
+ * Backing types supported by form-builder fields.
+ */
+type BackingType = keyof InputPropsByBackingType;
+/**
+ * Registry mapping component type names to their backing Zod types.
+ * This enables compile-time type checking for component definitions.
+ */
+declare const COMPONENT_BACKING_TYPES: {
+    readonly text: "string";
+    readonly email: "string";
+    readonly password: "string";
+    readonly url: "string";
+    readonly phone: "string";
+    readonly textarea: "string";
+    readonly number: "number";
+    readonly checkbox: "boolean";
+    readonly switch: "boolean";
+    readonly select: "enum";
+    readonly radio: "enum";
+    readonly date: "date";
+    readonly color: "string";
+};
+/**
+ * All registered component type names.
+ */
+type ComponentType = keyof typeof COMPONENT_BACKING_TYPES;
+/**
+ * Base properties shared by all form builder fields.
+ */
+interface BaseFieldProps {
+    /** Display label for the field */
+    label: string;
+    /** Description text */
+    description?: string;
+    /** Whether the field is required */
+    required?: boolean;
+    /** Field type override (checkbox, date, select, radio, switch, etc.) */
+    fieldType?: FieldType;
+    /** Additional input props passed through to the field */
+    inputProps?: SerializableInputProps;
+}
+/**
+ * Props for string-backed fields (text, email, password, url, phone, textarea).
+ */
+interface StringFieldProps extends BaseFieldProps {
+    /** Placeholder text */
+    placeholder?: string;
+    /** Minimum length */
+    minLength?: number;
+    /** Maximum length */
+    maxLength?: number;
+    /** Regex pattern for validation */
+    pattern?: string;
+    /** HTML input type (text, email, password, tel, url) */
+    inputType?: string;
+    /** Default value */
+    defaultValue?: string;
+}
+/**
+ * Props for number-backed fields.
+ */
+interface NumberFieldProps extends BaseFieldProps {
+    /** Placeholder text */
+    placeholder?: string;
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+    /** Default value */
+    defaultValue?: number;
+}
+/**
+ * Props for boolean-backed fields (checkbox, switch).
+ */
+interface BooleanFieldProps extends BaseFieldProps {
+    /** Default value */
+    defaultValue?: boolean;
+}
+/**
+ * Props for date-backed fields.
+ */
+interface DateFieldProps extends BaseFieldProps {
+    /** Minimum date */
+    minDate?: Date | string;
+    /** Maximum date */
+    maxDate?: Date | string;
+    /** Default value */
+    defaultValue?: Date | string;
+}
+/**
+ * Props for enum-backed fields (select, radio).
+ */
+interface EnumFieldProps extends BaseFieldProps {
+    /** Placeholder text (for select) */
+    placeholder?: string;
+    /** Options for the select/radio */
+    options?: string[];
+    /** Default value (must match one of the options) */
+    defaultValue?: string;
+}
+/**
+ * Maps backing types to their corresponding field props.
+ */
+interface FieldPropsByBackingType {
+    string: StringFieldProps;
+    number: NumberFieldProps;
+    boolean: BooleanFieldProps;
+    date: DateFieldProps;
+    enum: EnumFieldProps;
+}
+/**
+ * Get the correct field props type for a backing type.
+ */
+type FieldPropsFor<T extends BackingType> = FieldPropsByBackingType[T];
+/**
+ * Union of all discriminated field props.
+ */
+type TypedFieldProps = StringFieldProps | NumberFieldProps | BooleanFieldProps | DateFieldProps | EnumFieldProps;
+/**
+ * Properties for a form builder field.
+ * This is the runtime union type used when the backing type is not known.
+ *
+ * For type-safe field props, use the discriminated variants:
+ * - StringFieldProps for text, email, password, url, phone, textarea
+ * - NumberFieldProps for number fields
+ * - BooleanFieldProps for checkbox, switch
+ * - DateFieldProps for date fields
+ * - EnumFieldProps for select, radio
+ */
+interface FormBuilderFieldProps extends BaseFieldProps {
+    placeholder?: string;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    inputType?: string;
+    min?: number;
+    max?: number;
+    minDate?: Date | string;
+    maxDate?: Date | string;
+    options?: string[];
+    minItems?: number;
+    maxItems?: number;
+    defaultValue?: unknown;
+}
+/**
+ * Typed component definition for a specific backing type.
+ *
+ * Use this when defining components to get type-safe field props:
+ *
+ * @example
+ * ```typescript
+ * const textField: TypedComponentDefinition<"string"> = {
+ *   type: "text",
+ *   backingType: "string",
+ *   defaultProps: { label: "Text", placeholder: "Enter text" }, // ✓ type-safe
+ *   // ...
+ * };
+ * ```
+ */
+interface TypedComponentDefinition<T extends BackingType> {
+    /** Unique identifier for this component type */
+    type: ComponentType | string;
+    /** The backing Zod type for this component */
+    backingType: T;
+    /** Display name shown in the palette */
+    label: string;
+    /** Icon shown in the palette */
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    /** Default props when a new field is created - type-safe based on backing type */
+    defaultProps: Partial<FieldPropsFor<T>>;
+    /** Zod schema for the property panel */
+    propertiesSchema: z.ZodObject<z.ZodRawShape>;
+    /** Convert field props to JSON Schema property */
+    toJSONSchema: (props: FieldPropsFor<T>, isRequired: boolean) => JSONSchemaProperty;
+    /** Try to parse a JSON Schema property into this component type */
+    fromJSONSchema: (prop: JSONSchemaProperty, key: string, isRequired: boolean) => {
+        id: string;
+        type: string;
+        props: FieldPropsFor<T>;
+    } | null;
+    /** Optional custom preview component */
+    PreviewComponent?: React.ComponentType<{
+        field: FormBuilderField;
+    }>;
+}
+/**
+ * Component definition provided by developers.
+ *
+ * This is the runtime type used when the backing type is not known at compile time.
+ * For type-safe definitions, use `TypedComponentDefinition<T>`.
+ */
+interface FormBuilderComponentDefinition {
+    /** Unique identifier for this component type */
+    type: string;
+    /** The backing Zod type for this component (optional for backwards compatibility) */
+    backingType?: BackingType;
+    /** Display name shown in the palette */
+    label: string;
+    /** Icon shown in the palette */
+    icon?: React.ComponentType<{
+        className?: string;
+    }>;
+    /** Default props when a new field is created */
+    defaultProps: Partial<FormBuilderFieldProps>;
+    /** Zod schema for the property panel */
+    propertiesSchema: z.ZodObject<z.ZodRawShape>;
+    /** Convert field props to JSON Schema property */
+    toJSONSchema: (props: FormBuilderFieldProps, isRequired: boolean) => JSONSchemaProperty;
+    /** Try to parse a JSON Schema property into this component type */
+    fromJSONSchema: (prop: JSONSchemaProperty, key: string, isRequired: boolean) => FormBuilderField | null;
+    /** Optional custom preview component */
+    PreviewComponent?: React.ComponentType<{
+        field: FormBuilderField;
+    }>;
+}
+/**
+ * Helper to create a type-safe component definition.
+ * The returned definition is assignable to FormBuilderComponentDefinition.
+ */
+declare function defineComponent<T extends BackingType>(def: TypedComponentDefinition<T>): FormBuilderComponentDefinition;
+
+/**
+ * Object Field (Field Group)
+ *
+ * A container field that groups other fields together as nested properties.
+ * The actual children are stored in field.children and converted by schema-utils.
+ */
+declare const objectFieldDefinition: FormBuilderComponentDefinition;
+/**
+ * Array Field (Repeating Group)
+ *
+ * A container field for repeating items. Each item follows a template defined
+ * in field.itemTemplate. The template is converted by schema-utils.
+ */
+declare const arrayFieldDefinition: FormBuilderComponentDefinition;
+/**
+ * All default components in order of specificity (more specific first)
+ * This order matters for fromJSONSchema matching
+ *
+ * Custom field definitions (color, file, image, etc.) should be created by
+ * consumers using the exported `defineComponent` utility and passed via the
+ * `components` prop.
+ */
+declare const defaultComponents: FormBuilderComponentDefinition[];
+
+/**
+ * Validation Schemas Registry
+ *
+ * This file defines type-safe validation schemas for the form-builder properties editor.
+ * Based on the Zod serialization analysis, only serializable properties are included.
+ *
+ * Usage:
+ *   propertiesSchema: baseMetaSchema
+ *     .merge(VALIDATION_SCHEMAS[backingType])
+ *     .merge(z.object({ defaultValue: DEFAULT_VALUE_SCHEMAS[backingType] }))
+ */
+/**
+ * Base meta properties (universal - all field types)
+ * Includes: label, description, required
+ */
+declare const baseMetaSchema: z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Extended base with placeholder (for text-like fields only)
+ * Use for: text, email, password, url, phone, textarea, number, select
+ */
+declare const baseMetaSchemaWithPlaceholder: z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    required: z.ZodDefault<z.ZodBoolean>;
+    placeholder: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+
+interface FormBuilderProps {
+    /** Available components to use in the form builder */
+    components?: FormBuilderComponentDefinition[];
+    /** Current form schema (JSON Schema format) */
+    value?: JSONSchema;
+    /** Callback when form schema changes */
+    onChange?: (schema: JSONSchema) => void;
+    /** Additional CSS classes */
+    className?: string;
+    /**
+     * Custom field components for the form preview.
+     * Maps fieldType names to React components that render the field.
+     * These are merged with the default custom components (like color picker).
+     *
+     * @example
+     * ```tsx
+     * <FormBuilder
+     *   fieldComponents={{
+     *     rating: RatingComponent,
+     *     signature: SignatureComponent,
+     *   }}
+     * />
+     * ```
+     */
+    fieldComponents?: Record<string, React.ComponentType<AutoFormInputComponentProps>>;
+    /**
+     * Default values to pre-populate the form preview with.
+     * Useful for edit scenarios where the form should start with existing data.
+     *
+     * @example
+     * ```tsx
+     * <FormBuilder
+     *   defaultValues={{
+     *     username: "johndoe",
+     *     email: "john@example.com",
+     *   }}
+     * />
+     * ```
+     */
+    defaultValues?: Record<string, unknown>;
+}
+declare function FormBuilder({ components, value, onChange, className, fieldComponents, defaultValues, }: FormBuilderProps): react_jsx_runtime.JSX.Element;
+
+export { FormBuilder, arrayFieldDefinition, baseMetaSchema, baseMetaSchemaWithPlaceholder, defaultComponents, defineComponent, objectFieldDefinition };
+export type { BackingType, ComponentType, FormBuilderComponentDefinition, FormBuilderField, FormBuilderFieldProps, FormStep, JSONSchema, JSONSchemaProperty, StringFieldProps, TypedFieldProps };