@skygraph/react 0.0.0-placeholder.0 → 0.4.0

package/dist/form.d.cts

@@ -0,0 +1,530 @@
+import { Core, FormEngine, FormOptions, FormState, ValidationResult, ValidationMode, Rule, FormListOperation } from '@skygraph/core';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React__default from 'react';
+import { B as BaseComponentProps, I as InteractiveProps, S as SizableProps } from './common-CdpocIEz.cjs';
+
+interface UseFieldReturn {
+    value: unknown;
+    errors: string[];
+    warnings: string[];
+    error: string | null;
+    touched: boolean;
+    dirty: boolean;
+    validating: boolean;
+    status: 'success' | 'warning' | 'error' | 'validating' | undefined;
+    onChange: (value: unknown) => void;
+    onBlur: () => void;
+}
+declare function useField(core: Core, form: FormEngine, name: string): UseFieldReturn;
+
+interface UseFormOptions extends FormOptions {
+    onSubmit?: (values: Record<string, unknown>) => void | Promise<void>;
+    onSubmitInvalid?: (errors: Record<string, string[]>) => void;
+}
+interface UseFormReturn {
+    core: Core;
+    form: FormEngine;
+    formState: FormState;
+    submit: () => Promise<void>;
+    reset: (values?: Record<string, unknown>) => void;
+    setFieldValue: (name: string, value: unknown) => void;
+    setFieldsValue: (values: Record<string, unknown>) => void;
+    getFieldValue: (name: string) => unknown;
+    getFieldsValue: () => Record<string, unknown>;
+    validateFields: (name?: string) => Promise<ValidationResult>;
+}
+declare function useForm(options?: UseFormOptions): UseFormReturn;
+
+/** Props for the root form wrapper; merges {@link UseFormOptions} with layout and UI settings. */
+interface FormProps extends UseFormOptions {
+    /** Controlled form instance from {@link useForm}; when omitted, an internal instance is created. */
+    form?: UseFormReturn;
+    /** `name` attribute on the native `<form>` element. */
+    name?: string;
+    /** Arrangement of labels and controls.
+     * @default 'vertical'
+     */
+    layout?: 'horizontal' | 'vertical' | 'inline';
+    /** Field/control size for context consumers. */
+    size?: 'small' | 'middle' | 'large';
+    /** Disables fields that read this value from form context. */
+    disabled?: boolean;
+    /** When `true`, appends a colon after labels that support it. */
+    colon?: boolean;
+    /** How required fields are marked in labels (`*` vs “optional”). */
+    requiredMark?: boolean | 'optional';
+    /** Label column grid settings (24-column) for horizontal layout. */
+    labelCol?: {
+        /** Column span (out of 24). */
+        span?: number;
+        /** Column offset (out of 24). */
+        offset?: number;
+    };
+    /** Control column grid settings (24-column) for horizontal layout. */
+    wrapperCol?: {
+        /** Column span (out of 24). */
+        span?: number;
+        /** Column offset (out of 24). */
+        offset?: number;
+    };
+    /** Text alignment for the label column. */
+    labelAlign?: 'left' | 'right';
+    /** Additional class names on the `<form>`. */
+    className?: string;
+    /** Inline styles on the `<form>`. */
+    style?: React__default.CSSProperties;
+    /** Form body content. */
+    children: React__default.ReactNode;
+    /** After submit, scroll the first invalid field into view (`true` uses smooth centering). */
+    scrollToFirstError?: boolean | ScrollIntoViewOptions;
+    /** Keeps unmounted field values in the form store. */
+    preserve?: boolean;
+    /** Events that trigger validation (passed through to form options). */
+    validateTrigger?: ValidationMode | ValidationMode[];
+    /** Custom icons shown for field feedback states. */
+    feedbackIcons?: {
+        /** Icon for successful validation. */
+        success?: React__default.ReactNode;
+        /** Icon for warning validation. */
+        warning?: React__default.ReactNode;
+        /** Icon for error validation. */
+        error?: React__default.ReactNode;
+        /** Icon while async validation is running. */
+        validating?: React__default.ReactNode;
+    };
+    /**
+     * Called with the form values when the form passes validation and submits.
+     * Alias for `onSubmit`. Both fire; if both are provided, `onSubmit` runs first.
+     */
+    onFinish?: (values: Record<string, unknown>) => void | Promise<void>;
+    /**
+     * Initial field values. Alias for `defaultValues` (the underlying Form
+     * engine option). When both are provided, `defaultValues` wins.
+     */
+    initialValues?: Record<string, unknown>;
+}
+/**
+ * Renders a `<form>` and provides {@link FormContext} for fields and lists.
+ * Submits via the engine’s `submit` and optionally scrolls to the first error.
+ */
+declare function Form({ form: externalForm, name: formName, layout, size: sizeProp, disabled: disabledProp, colon, requiredMark, labelCol, wrapperCol, labelAlign, className, style, children, scrollToFirstError, preserve, feedbackIcons, onFinish, initialValues, ...formOptions }: FormProps): react_jsx_runtime.JSX.Element;
+
+/** Props for a single named field with validation, layout, and optional custom control. */
+interface FieldProps extends BaseComponentProps {
+    /** Registered path in the form store. */
+    name: string;
+    /** Visible label text; layout comes from {@link FormContext}. */
+    label?: string;
+    /** When `true`, prepends a required rule in addition to `rules`. */
+    required?: boolean;
+    /** Validation rules for this field.
+     * @default []
+     */
+    rules?: Rule[];
+    /** Rules that produce warnings without failing validation. */
+    warningRules?: Rule[];
+    /** Re-validates this field when any listed field changes. */
+    dependencies?: string[];
+    /** When `true`, the field renders nothing (values can remain registered). */
+    hidden?: boolean;
+    /** Disables the control; falls back to form context `disabled`. */
+    disabled?: boolean;
+    /** Placeholder for the built-in `Input` / `Textarea`. */
+    placeholder?: string;
+    /** Built-in control type when `children` is not provided.
+     * @default 'text'
+     */
+    type?: 'text' | 'email' | 'password' | 'number' | 'textarea';
+    /** Helper text shown below the control when there are no errors/warnings. */
+    help?: React__default.ReactNode;
+    /** Supplementary content below the control area. */
+    extra?: React__default.ReactNode;
+    /** Tooltip title wrapping the label text. */
+    tooltip?: string;
+    /** Custom control, render prop, or omit for default input/textarea. */
+    children?: React__default.ReactNode | ((field: UseFieldReturn) => React__default.ReactNode);
+    /** Renders only the control (validation wiring) without layout chrome. */
+    noStyle?: boolean;
+    /** Maps raw change values before committing to the store. */
+    normalize?: (value: unknown, prevValue: unknown) => unknown;
+    /** Custom extractor for control events (reserved for controlled wrappers). */
+    getValueFromEvent?: (...args: unknown[]) => unknown;
+    /** Prop name on the child that holds the value (for custom controls). */
+    valuePropName?: string;
+    /** Stops after the first failing rule when validating. */
+    validateFirst?: boolean;
+    /** Manual validation status badge; overrides engine-derived status when set. */
+    validateStatus?: 'success' | 'warning' | 'error' | 'validating';
+    /** Shows feedback icons when the field has been touched. */
+    hasFeedback?: boolean;
+    /** Keeps value on unregister; overrides form-level `preserve` when set. */
+    preserve?: boolean;
+    /** Overrides form `labelCol` for this field in horizontal layout. */
+    labelCol?: {
+        /** Column span (out of 24). */
+        span?: number;
+        /** Column offset (out of 24). */
+        offset?: number;
+    };
+    /** Overrides form `wrapperCol` for this field in horizontal layout. */
+    wrapperCol?: {
+        /** Column span (out of 24). */
+        span?: number;
+        /** Column offset (out of 24). */
+        offset?: number;
+    };
+    /** Template variables merged into validation messages for this field. */
+    messageVariables?: Record<string, string>;
+}
+/**
+ * Registers `name` with the form engine, renders label/help/errors, and either
+ * a built-in input or custom `children` / render-prop control.
+ */
+declare function Field({ name, label, required, rules, warningRules, dependencies, hidden, disabled: fieldDisabled, unstyled, placeholder, type, help, extra, tooltip, children, noStyle, normalize, getValueFromEvent: _getValueFromEvent, validateFirst, validateStatus: manualStatus, hasFeedback, preserve, labelCol: fieldLabelCol, wrapperCol: fieldWrapperCol, messageVariables: _messageVariables, }: FieldProps): react_jsx_runtime.JSX.Element | null;
+
+/** Props for a primary-styled submit {@link Button} used inside {@link Form}. */
+interface SubmitButtonProps {
+    /** Button label; falls back when omitted in destructuring.
+     * @default 'Submit'
+     */
+    children?: React__default.ReactNode;
+    /** Disables the button. */
+    disabled?: boolean;
+    /** Shows a loading state on the button. */
+    loading?: boolean;
+    /** Extra class names passed to {@link Button}. */
+    className?: string;
+    /** Inline styles forwarded to the underlying {@link Button}. */
+    style?: React__default.CSSProperties;
+    /** Strips built-in button styles on the underlying {@link Button}. */
+    unstyled?: boolean;
+}
+/**
+ * `type="submit"` primary button; forwards disabled/loading and styling to {@link Button}.
+ */
+declare function SubmitButton({ children, disabled, loading, className, style, unstyled, }: SubmitButtonProps): react_jsx_runtime.JSX.Element;
+
+/** Values exposed by {@link FormContext} to descendant fields and hooks. */
+interface FormContextValue {
+    /** Shared Skygraph core instance for the form tree. */
+    core: Core;
+    /** Form engine coordinating values, validation, and submit. */
+    form: FormEngine;
+    /** Active form layout from the nearest {@link Form}. */
+    layout?: 'horizontal' | 'vertical' | 'inline';
+    /** Active control size from the nearest {@link Form}. */
+    size?: 'small' | 'middle' | 'large';
+    /** Whether the form tree is disabled. */
+    disabled?: boolean;
+    /** Whether labels show a trailing colon. */
+    colon?: boolean;
+    /** Required/optional marking mode for labels. */
+    requiredMark?: boolean | 'optional';
+    /** Default label column grid for horizontal layout. */
+    labelCol?: {
+        /** Column span (out of 24). */
+        span?: number;
+        /** Column offset (out of 24). */
+        offset?: number;
+    };
+    /** Default control column grid for horizontal layout. */
+    wrapperCol?: {
+        /** Column span (out of 24). */
+        span?: number;
+        /** Column offset (out of 24). */
+        offset?: number;
+    };
+    /** Default label text alignment. */
+    labelAlign?: 'left' | 'right';
+    /** Whether unmounted field values are preserved. */
+    preserve?: boolean;
+    /** Icons used for field feedback states. */
+    feedbackIcons?: {
+        /** Success-state icon. */
+        success?: React__default.ReactNode;
+        /** Warning-state icon. */
+        warning?: React__default.ReactNode;
+        /** Error-state icon. */
+        error?: React__default.ReactNode;
+        /** Validating-state icon. */
+        validating?: React__default.ReactNode;
+    };
+}
+declare const FormContext: React__default.Context<FormContextValue | null>;
+/**
+ * Returns the current `FormContextValue` from the nearest {@link Form}.
+ * @throws If used outside `<Form>`.
+ */
+declare function useFormContext(): FormContextValue;
+
+/** Stable identity and position of one row in a {@link FormList}. */
+interface FormListField {
+    /** Stable React key for list reconciliation. */
+    key: string;
+    /** Zero-based index in the list value array. */
+    index: number;
+}
+/** Props for a dynamic array field bound to form state. */
+interface FormListProps {
+    /** Field path in the form store holding the array value. */
+    name: string;
+    /** Seeds the store when the path is unset on first mount. */
+    initialValue?: unknown[];
+    /** When `true`, each row receives `dragProps` for HTML5 drag-and-drop reordering. */
+    draggable?: boolean;
+    /** Render function receiving fields, list operations, and validation meta. */
+    children: (fields: FormListField[], operation: FormListOperation, meta: {
+        errors: string[];
+    }) => React__default.ReactNode;
+}
+/**
+ * Manages an array at `name` with stable keys, add/remove/move/replace helpers,
+ * and optional drag reordering when `draggable` is enabled.
+ */
+declare function FormList({ name, initialValue, draggable, children }: FormListProps): react_jsx_runtime.JSX.Element;
+
+declare function useWatch(core: Core, name: string): unknown;
+
+interface UseFieldArrayReturn {
+    fields: {
+        key: string;
+        index: number;
+    }[];
+    append: (defaultValue?: unknown) => void;
+    remove: (index: number) => void;
+    move: (from: number, to: number) => void;
+    replace: (values: unknown[]) => void;
+}
+declare function useFieldArray(form: FormEngine, name: string): UseFieldArrayReturn;
+
+/** Supported input kinds for form field rendering and inference. */
+type FieldType = 'string' | 'number' | 'boolean' | 'email' | 'url' | 'date' | 'time' | 'textarea' | 'select' | 'multiselect' | 'password' | 'color' | 'slider' | 'rate' | 'file' | 'switch' | 'radio';
+/** Single choice label/value pair for select, multiselect, or radio fields. */
+interface AutoFieldOption {
+    /** Display text for the option. */
+    label: string;
+    /** Stored value when the option is selected. */
+    value: string | number;
+}
+/** Props for a form field that picks its control from field name, value shape, and `type`. */
+interface AutoFieldProps extends BaseComponentProps, InteractiveProps {
+    /** Form field key used with `useFormContext`. */
+    name: string;
+    /** Caption shown above the control (or inline for checkbox/switch). */
+    label?: React__default.ReactNode;
+    /** Forces a control type; otherwise inferred from value and `options`. */
+    type?: FieldType;
+    /** Options for select, multiselect, or radio types. */
+    options?: AutoFieldOption[];
+    /** Placeholder or empty-option label where applicable. */
+    placeholder?: string;
+    /** Minimum numeric or range value. */
+    min?: number;
+    /** Maximum numeric, range, or star rating count. */
+    max?: number;
+    /** Step for number inputs and range sliders. */
+    step?: number;
+    /** `accept` attribute for file inputs. */
+    accept?: string;
+    /** Allows multiple files when type is `file`. */
+    multiple?: boolean;
+}
+/**
+ * Renders an appropriate input for a form field based on `type`, options, and current value.
+ * Reads and writes through `FormContext` using `name`.
+ */
+declare function AutoField(props: AutoFieldProps): react_jsx_runtime.JSX.Element;
+
+interface JSONSchemaProperty {
+    type?: string;
+    title?: string;
+    description?: string;
+    default?: unknown;
+    enum?: unknown[];
+    enumNames?: string[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+    items?: JSONSchemaProperty;
+    required?: string[];
+    properties?: Record<string, JSONSchemaProperty>;
+    oneOf?: Array<{
+        const: unknown;
+        title?: string;
+    }>;
+}
+interface JSONSchema extends JSONSchemaProperty {
+    $schema?: string;
+}
+interface AutoFieldConfig {
+    name: string;
+    label?: string;
+    type: FieldType;
+    placeholder?: string;
+    options?: AutoFieldOption[];
+    min?: number;
+    max?: number;
+    step?: number;
+}
+declare function jsonSchemaToFields(schema: JSONSchema): AutoFieldConfig[];
+declare function jsonSchemaToRules(schema: JSONSchema): Record<string, Rule[]>;
+declare function jsonSchemaToDefaults(schema: JSONSchema): Record<string, unknown>;
+
+/**
+ * Zod schema adapter. Converts a Zod schema (or any schema with .safeParse)
+ * into SkyGraph form rules.
+ *
+ * Works with Zod v3/v4 or any library that implements:
+ *   { safeParse(value: unknown): { success: boolean; error?: { issues: Array<{ message: string }> } } }
+ */
+interface ZodLikeSchema {
+    safeParse(value: unknown): {
+        success: boolean;
+        error?: {
+            issues: Array<{
+                message: string;
+                path?: (string | number)[];
+            }>;
+        };
+    };
+}
+interface ZodAdapterOptions {
+    /** Custom error message override */
+    message?: string;
+    /** Which issue to pick when multiple exist (default: 'first') */
+    pick?: 'first' | 'all';
+}
+/**
+ * Convert a single Zod schema into a SkyGraph Rule for one field.
+ */
+declare function zodRule(schema: ZodLikeSchema, options?: ZodAdapterOptions): Rule;
+/**
+ * Convert a Zod object schema into a map of field name -> Rule[].
+ * Useful for auto-registering all fields from a schema.
+ */
+interface ZodObjectLikeSchema {
+    shape: Record<string, ZodLikeSchema>;
+}
+declare function zodRules(schema: ZodObjectLikeSchema, options?: ZodAdapterOptions): Record<string, Rule[]>;
+/**
+ * Extract default values from a Zod schema.
+ * Uses safeParse(undefined) to trigger Zod's .default() mechanism,
+ * then reads the parsed data for the actual default value.
+ */
+declare function zodDefaults(schema: ZodObjectLikeSchema): Record<string, unknown>;
+interface ZodDef {
+    typeName?: string;
+    checks?: Array<{
+        kind: string;
+        value?: unknown;
+        regex?: RegExp;
+        message?: string;
+    }>;
+    values?: unknown[];
+    innerType?: {
+        _def: ZodDef;
+    };
+    type?: {
+        _def: ZodDef;
+    };
+    options?: Array<{
+        _def: ZodDef;
+    }>;
+}
+interface ZodFieldSchema {
+    _def: ZodDef;
+    description?: string;
+}
+interface ZodObjectSchema {
+    _def: ZodDef;
+    shape?: Record<string, ZodFieldSchema>;
+}
+/**
+ * Converts a Zod schema to a minimal JSON Schema representation for SchemaForm.
+ */
+declare function zodToJsonSchema(schema: ZodObjectSchema): JSONSchema;
+
+interface FormProviderContextValue {
+    registerForm: (name: string, form: FormEngine) => void;
+    unregisterForm: (name: string) => void;
+    onFormFinish?: (name: string, info: {
+        values: Record<string, unknown>;
+        forms: Record<string, FormEngine>;
+    }) => void;
+    onFormChange?: (name: string, info: {
+        changedFields: string[];
+        forms: Record<string, FormEngine>;
+    }) => void;
+}
+/** Props for a registry of named forms and their lifecycle callbacks. */
+interface FormProviderProps {
+    /** Called after a registered form finishes submit successfully. */
+    onFormFinish?: (name: string, info: {
+        values: Record<string, unknown>;
+        forms: Record<string, FormEngine>;
+    }) => void;
+    /** Called when values change in a registered form. */
+    onFormChange?: (name: string, info: {
+        changedFields: string[];
+        forms: Record<string, FormEngine>;
+    }) => void;
+    /** Tree of forms and other UI that may register with this provider. */
+    children: React__default.ReactNode;
+}
+/**
+ * Provides a context so named {@link Form} instances can register and report
+ * `onFormFinish` / `onFormChange` to a single parent.
+ */
+declare function FormProvider({ onFormFinish, onFormChange, children }: FormProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Returns the optional multi-form provider context, or `null` if there is no {@link FormProvider}.
+ */
+declare function useFormProvider(): FormProviderContextValue | null;
+
+/** Builds a {@link Form} from JSON Schema or Zod (converted to JSON Schema) with {@link Field} + {@link AutoField} rows. */
+interface SchemaFormProps extends BaseComponentProps, SizableProps {
+    /** JSON Schema object or a Zod schema (`_def` present) to derive fields and rules. */
+    schema: JSONSchema | {
+        _def?: unknown;
+    };
+    /** Called with all values on successful submit. */
+    onSubmit?: (values: Record<string, unknown>) => void | Promise<void>;
+    /** Passed through to the inner {@link Form}. */
+    layout?: 'horizontal' | 'vertical' | 'inline';
+    /** Disables generated controls and the inner {@link Form}. */
+    disabled?: boolean;
+    /** External form instance; otherwise an internal `useForm` is created with schema defaults. */
+    form?: UseFormReturn;
+    /** Passed through to the inner {@link Form}. */
+    labelCol?: {
+        /** Column span (out of 24). */
+        span?: number;
+        /** Column offset (out of 24). */
+        offset?: number;
+    };
+    /** Passed through to the inner {@link Form}. */
+    wrapperCol?: {
+        /** Column span (out of 24). */
+        span?: number;
+        /** Column offset (out of 24). */
+        offset?: number;
+    };
+    className?: string;
+    style?: React__default.CSSProperties;
+    /** Label for the default submit button when `children` is omitted.
+     * @default 'Submit'
+     */
+    submitText?: string;
+    /** Replaces the default submit button; omit to use a primary `<button type="submit">`. */
+    children?: React__default.ReactNode;
+}
+/**
+ * Generates fields from `schema`, wires validation, and wraps them in {@link Form}.
+ * Supports Zod input by converting it to JSON Schema first.
+ */
+declare function SchemaForm({ schema: rawSchema, onSubmit, layout, size, disabled, form: externalForm, labelCol, wrapperCol, className, style, submitText: submitTextProp, children, }: SchemaFormProps): react_jsx_runtime.JSX.Element;
+
+export { AutoField, type AutoFieldConfig, type AutoFieldOption, type AutoFieldProps, Field, type FieldProps, type FieldType, Form, FormContext, FormList, type FormListField, type FormListProps, type FormProps, FormProvider, type FormProviderProps, type JSONSchema, type JSONSchemaProperty, SchemaForm, type SchemaFormProps, SubmitButton, type SubmitButtonProps, type UseFieldArrayReturn, type UseFieldReturn, type UseFormOptions, type UseFormReturn, type ZodAdapterOptions, type ZodLikeSchema, type ZodObjectLikeSchema, jsonSchemaToDefaults, jsonSchemaToFields, jsonSchemaToRules, useField, useFieldArray, useForm, useFormContext, useFormProvider, useWatch, zodDefaults, zodRule, zodRules, zodToJsonSchema };