@sonordev/site-kit 1.2.7

package/dist/forms/index.d.mts

@@ -0,0 +1,437 @@
+import { F as FormSubmission, M as ManagedFormConfig, a as FormField$2, b as ManagedFormProps, c as FormRenderProps } from '../types-0dmq3k20.mjs';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React__default from 'react';
+
+/**
+ * @sonordev/site-kit/forms - Forms API Client
+ *
+ * Full API client for form management. Allows developers to create, update,
+ * and delete forms programmatically. Changes sync to Portal automatically.
+ *
+ * @example
+ * ```tsx
+ * import { formsApi } from '@sonordev/site-kit/forms'
+ *
+ * // Create a new form
+ * const form = await formsApi.create({
+ *   projectId: 'xxx',
+ *   slug: 'contact-us',
+ *   name: 'Contact Form',
+ *   formType: 'prospect',
+ *   fields: [
+ *     { slug: 'name', label: 'Name', fieldType: 'text', isRequired: true },
+ *     { slug: 'email', label: 'Email', fieldType: 'email', isRequired: true },
+ *     { slug: 'message', label: 'Message', fieldType: 'textarea' },
+ *   ]
+ * })
+ *
+ * // Update fields
+ * await formsApi.update(form.id, {
+ *   fields: [...form.fields, { slug: 'phone', label: 'Phone', fieldType: 'phone' }]
+ * })
+ * ```
+ */
+type FormType = 'prospect' | 'contact' | 'support' | 'feedback' | 'newsletter' | 'custom';
+type FieldType = 'text' | 'email' | 'phone' | 'number' | 'textarea' | 'select' | 'multi_select' | 'radio' | 'checkbox' | 'date' | 'time' | 'datetime' | 'url' | 'file' | 'rating' | 'slider' | 'hidden' | 'heading' | 'paragraph';
+type FieldWidth = 'full' | 'half' | 'third' | 'quarter';
+interface FieldOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+interface FieldValidation {
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    patternMessage?: string;
+}
+interface FieldConditional {
+    field: string;
+    operator: 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'is_empty' | 'not_empty' | 'greater_than' | 'less_than';
+    value?: string | number | boolean;
+}
+interface FormField$1 {
+    id?: string;
+    slug: string;
+    label: string;
+    fieldType: FieldType;
+    placeholder?: string;
+    helpText?: string;
+    defaultValue?: string;
+    isRequired?: boolean;
+    validation?: FieldValidation;
+    options?: FieldOption[];
+    conditional?: FieldConditional;
+    width?: FieldWidth;
+    sortOrder?: number;
+    destinationField?: string;
+    stepId?: string;
+}
+interface FormStep {
+    id?: string;
+    stepNumber: number;
+    title?: string;
+    description?: string;
+    condition?: FieldConditional;
+}
+interface Form {
+    id: string;
+    projectId: string;
+    slug: string;
+    name: string;
+    description?: string;
+    formType: FormType;
+    successMessage: string;
+    redirectUrl?: string;
+    notificationEmails?: string[];
+    submitButtonText: string;
+    layout: 'stacked' | 'inline' | 'grid';
+    showProgress: boolean;
+    enableSaveDraft: boolean;
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+    fields?: FormField$1[];
+    steps?: FormStep[];
+}
+interface CreateFormInput {
+    projectId: string;
+    slug: string;
+    name: string;
+    description?: string;
+    formType?: FormType;
+    successMessage?: string;
+    redirectUrl?: string;
+    notificationEmails?: string[];
+    submitButtonText?: string;
+    layout?: 'stacked' | 'inline' | 'grid';
+    showProgress?: boolean;
+    enableSaveDraft?: boolean;
+    isActive?: boolean;
+    fields?: FormField$1[];
+    steps?: FormStep[];
+}
+interface UpdateFormInput {
+    slug?: string;
+    name?: string;
+    description?: string;
+    formType?: FormType;
+    successMessage?: string;
+    redirectUrl?: string;
+    notificationEmails?: string[];
+    submitButtonText?: string;
+    layout?: 'stacked' | 'inline' | 'grid';
+    showProgress?: boolean;
+    enableSaveDraft?: boolean;
+    isActive?: boolean;
+    fields?: FormField$1[];
+    steps?: FormStep[];
+}
+interface FormsListOptions {
+    projectId?: string;
+    formType?: FormType;
+    isActive?: boolean;
+    search?: string;
+}
+interface FormsApiConfig {
+    baseUrl: string;
+    apiKey?: string;
+    getAuthToken?: () => Promise<string> | string;
+}
+/**
+ * Configure the forms API client
+ */
+declare function configureFormsApi(options: FormsApiConfig): void;
+declare const formsApi: {
+    /**
+     * List all forms for a project
+     */
+    list(options?: FormsListOptions): Promise<Form[]>;
+    /**
+     * Get a single form by ID or slug
+     */
+    get(idOrSlug: string): Promise<Form>;
+    /**
+     * Create a new form
+     */
+    create(input: CreateFormInput): Promise<Form>;
+    /**
+     * Update an existing form
+     */
+    update(id: string, input: UpdateFormInput): Promise<Form>;
+    /**
+     * Delete a form
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Add a field to an existing form
+     */
+    addField(formId: string, field: FormField$1): Promise<Form>;
+    /**
+     * Update a field in an existing form
+     */
+    updateField(formId: string, fieldSlug: string, updates: Partial<FormField$1>): Promise<Form>;
+    /**
+     * Remove a field from a form
+     */
+    removeField(formId: string, fieldSlug: string): Promise<Form>;
+    /**
+     * Reorder fields in a form
+     */
+    reorderFields(formId: string, fieldSlugs: string[]): Promise<Form>;
+    /**
+     * Clone a form
+     */
+    clone(formId: string, newSlug: string, newName?: string): Promise<Form>;
+    /**
+     * Activate or deactivate a form
+     */
+    setActive(formId: string, isActive: boolean): Promise<Form>;
+    /**
+     * Sync a form definition to the backend
+     * Creates the form if it doesn't exist, updates if it does
+     * Perfect for defining forms in code during development
+     *
+     * @example
+     * ```tsx
+     * // In your app initialization or form component
+     * await formsApi.sync({
+     *   slug: 'contact',
+     *   name: 'Contact Form',
+     *   formType: 'prospect',
+     *   fields: [
+     *     field.text('name', 'Your Name', { isRequired: true }),
+     *     field.email('email', 'Email Address'),
+     *     field.phone('phone', 'Phone Number'),
+     *     field.textarea('message', 'Message'),
+     *   ]
+     * })
+     * ```
+     */
+    sync(input: Omit<CreateFormInput, "projectId">): Promise<Form & {
+        synced: boolean;
+        created: boolean;
+        updated: boolean;
+    }>;
+    /**
+     * Sync multiple forms at once
+     * Useful for initializing all forms in your app
+     */
+    syncAll(forms: Array<Omit<CreateFormInput, "projectId">>): Promise<Array<Form & {
+        synced: boolean;
+        created: boolean;
+        updated: boolean;
+    }>>;
+};
+/**
+ * Helper functions to build field definitions
+ */
+declare const field: {
+    text: (slug: string, label: string, options?: Partial<FormField$1>) => FormField$1;
+    email: (slug: string, label: string, options?: Partial<FormField$1>) => FormField$1;
+    phone: (slug: string, label: string, options?: Partial<FormField$1>) => FormField$1;
+    textarea: (slug: string, label: string, options?: Partial<FormField$1>) => FormField$1;
+    select: (slug: string, label: string, choices: Array<{
+        value: string;
+        label: string;
+    }>, options?: Partial<FormField$1>) => FormField$1;
+    radio: (slug: string, label: string, choices: Array<{
+        value: string;
+        label: string;
+    }>, options?: Partial<FormField$1>) => FormField$1;
+    checkbox: (slug: string, label: string, options?: Partial<FormField$1>) => FormField$1;
+    date: (slug: string, label: string, options?: Partial<FormField$1>) => FormField$1;
+    number: (slug: string, label: string, options?: Partial<FormField$1>) => FormField$1;
+    rating: (slug: string, label: string, options?: Partial<FormField$1>) => FormField$1;
+    file: (slug: string, label: string, options?: Partial<FormField$1>) => FormField$1;
+    hidden: (slug: string, defaultValue: string) => FormField$1;
+    heading: (slug: string, label: string) => FormField$1;
+    paragraph: (slug: string, label: string) => FormField$1;
+};
+interface FormDefinition extends Omit<CreateFormInput, 'projectId'> {
+    slug: string;
+    name: string;
+    fields: FormField$1[];
+}
+/**
+ * Define a form declaratively
+ * Returns a form definition that can be synced to the backend
+ *
+ * @example
+ * ```tsx
+ * // forms/contact.ts
+ * import { defineForm, field } from '@sonordev/site-kit/forms'
+ *
+ * export const contactForm = defineForm({
+ *   slug: 'contact',
+ *   name: 'Contact Us',
+ *   formType: 'prospect',
+ *   successMessage: 'Thanks! We\'ll be in touch soon.',
+ *   fields: [
+ *     field.text('name', 'Your Name', { isRequired: true }),
+ *     field.email('email', 'Email Address'),
+ *     field.phone('phone', 'Phone Number'),
+ *     field.select('service', 'Service Needed', [
+ *       { value: 'consultation', label: 'Free Consultation' },
+ *       { value: 'representation', label: 'Legal Representation' },
+ *     ]),
+ *     field.textarea('message', 'Tell us about your case'),
+ *   ]
+ * })
+ *
+ * // Then in your app:
+ * await formsApi.sync(contactForm)
+ * ```
+ */
+declare function defineForm(definition: FormDefinition): FormDefinition;
+/**
+ * Initialize multiple forms and sync them to the backend
+ * Call this once during app initialization (e.g., in layout.tsx or _app.tsx)
+ *
+ * @example
+ * ```tsx
+ * // app/layout.tsx
+ * import { initializeForms } from '@sonordev/site-kit/forms'
+ * import { contactForm } from './forms/contact'
+ * import { consultationForm } from './forms/consultation'
+ *
+ * // Initialize forms (runs once per build/server start in dev)
+ * if (process.env.NODE_ENV === 'development') {
+ *   initializeForms([contactForm, consultationForm])
+ * }
+ * ```
+ */
+declare function initializeForms(forms: FormDefinition[]): Promise<void>;
+
+/**
+ * @sonordev/site-kit/forms - useForm Hook
+ *
+ * Headless hook for complete control over form rendering.
+ * Fetches form config from API, handles validation, state, and submission.
+ *
+ * @example
+ * ```tsx
+ * const { form, fields, values, errors, setFieldValue, submit, isSubmitting } = useForm('contact-form')
+ *
+ * return (
+ *   <form onSubmit={(e) => { e.preventDefault(); submit() }}>
+ *     {fields.map(field => (
+ *       <MyCustomInput
+ *         key={field.slug}
+ *         label={field.label}
+ *         value={values[field.slug]}
+ *         error={errors[field.slug]}
+ *         onChange={(val) => setFieldValue(field.slug, val)}
+ *       />
+ *     ))}
+ *     <button type="submit" disabled={isSubmitting}>Submit</button>
+ *   </form>
+ * )
+ * ```
+ */
+
+interface UseFormOptions {
+    /** Project ID (defaults to SiteKitProvider config) */
+    projectId?: string;
+    /** Callback when form submits successfully */
+    onSuccess?: (submission: FormSubmission) => void;
+    /** Callback when submission fails */
+    onError?: (error: Error) => void;
+    /** Initial values to prefill */
+    initialValues?: Record<string, unknown>;
+    /** Auto-redirect after success (override form config) */
+    redirectUrl?: string | false;
+}
+interface UseFormReturn {
+    /** Form configuration (null while loading) */
+    form: ManagedFormConfig | null;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error fetching form */
+    fetchError: Error | null;
+    /** All form fields */
+    allFields: FormField$2[];
+    /** Fields for current step (multi-step) or all fields (single step) */
+    fields: FormField$2[];
+    /** Visible fields only (respecting conditional logic) */
+    visibleFields: FormField$2[];
+    /** Current form values */
+    values: Record<string, unknown>;
+    /** Current validation errors */
+    errors: Record<string, string>;
+    /** Set a single field value */
+    setFieldValue: (key: string, value: unknown) => void;
+    /** Set multiple field values at once */
+    setValues: (values: Record<string, unknown>) => void;
+    /** Clear all errors */
+    clearErrors: () => void;
+    /** Multi-step state */
+    step: number;
+    totalSteps: number;
+    isMultiStep: boolean;
+    progress: number;
+    /** Multi-step navigation */
+    nextStep: () => boolean;
+    prevStep: () => void;
+    goToStep: (step: number) => void;
+    canGoNext: boolean;
+    canGoPrev: boolean;
+    isLastStep: boolean;
+    /** Validate current step */
+    validate: () => boolean;
+    /** Validate a single field */
+    validateField: (field: FormField$2) => string | null;
+    /** Check if a field is visible (conditional logic) */
+    isFieldVisible: (field: FormField$2) => boolean;
+    /** Submit the form */
+    submit: () => Promise<void>;
+    /** Submission state */
+    isSubmitting: boolean;
+    isComplete: boolean;
+    /** Reset form to initial state */
+    reset: () => void;
+}
+declare function useForm(formIdOrSlug: string, options?: UseFormOptions): UseFormReturn;
+
+declare function ManagedForm({ formId, projectId, className, onSuccess, onError, children, }: ManagedFormProps): react_jsx_runtime.JSX.Element;
+
+interface FormClientProps {
+    config: ManagedFormConfig;
+    className?: string;
+    onSuccess?: (submission: FormSubmission) => void;
+    onError?: (error: Error) => void;
+    customRender?: (props: FormRenderProps) => React__default.ReactNode;
+}
+declare function FormClient({ config, className, onSuccess, onError, customRender, }: FormClientProps): react_jsx_runtime.JSX.Element;
+
+interface FormFieldProps {
+    field: FormField$2;
+    value: unknown;
+    error?: string;
+    onChange: (value: unknown) => void;
+    /** Optional class name prefix for custom styling */
+    classPrefix?: string;
+}
+declare function FormField({ field, value, error, onChange, classPrefix }: FormFieldProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * @sonordev/site-kit/forms - Form Tracking Hook
+ *
+ * Tracks form analytics including step progress and abandonment
+ */
+interface UseFormTrackingOptions {
+    formId: string;
+    totalSteps: number;
+    enabled?: boolean;
+    debug?: boolean;
+}
+interface FormTrackingReturn {
+    trackStepChange: (step: number) => void;
+    trackComplete: () => void;
+    sessionId: string;
+}
+declare function useFormTracking({ formId, totalSteps, enabled, debug, }: UseFormTrackingOptions): FormTrackingReturn;
+
+export { type CreateFormInput, type FieldType, type Form, FormClient, type FormDefinition, type FormField$1 as FormField, FormField as FormFieldComponent, FormField$2 as FormFieldConfig, type FormStep, FormSubmission, type FormType, type FormsListOptions, ManagedForm, ManagedFormConfig, type UpdateFormInput, type UseFormOptions, type UseFormReturn, configureFormsApi, defineForm, field, formsApi, initializeForms, useForm, useFormTracking };