@page-speed/forms 0.5.0 → 0.5.2

package/dist/integration.d.cts

@@ -1,4 +1,6 @@
 import * as React from 'react';
+import { ReactNode } from 'react';
+import { d as FormSubmissionBehavior, N as NewFormSubmissionActionConfig, m as UseFormReturn } from './types-CnOCn7b3.cjs';
 
 /**
  * @page-speed/forms - Rails API Serializer
@@ -378,4 +380,299 @@ declare function standardInputTransformer(blockProps: Record<string, unknown>, b
  */
 declare function createBlockAdapters<TComponents extends Record<string, React.ComponentType<any>>>(components: TComponents, options?: BlockAdapterOptions): Record<keyof TComponents, React.ComponentType<AdaptedComponentProps>>;
 
-export { type AdaptedComponentProps, type Block, type BlockAdapterOptions, type FormErrors, type RailsApiConfig, type RailsErrorResponse, type SerializedFormData, createBlockAdapter, createBlockAdapters, deserializeErrors, serializeForRails, standardInputTransformer };
+type PageSpeedFormMethod = "post" | "get" | "put" | "patch";
+type PageSpeedFormSubmissionFormat = "json" | "rails";
+interface PageSpeedFormSubmissionResult {
+    formData: Record<string, any>;
+    responseData: unknown;
+}
+interface PageSpeedFormSubmissionConfig {
+    /**
+     * Post-submit behavior.
+     * @default "showConfirmation"
+     */
+    behavior?: FormSubmissionBehavior;
+    /**
+     * Optional callback triggered on successful submission.
+     */
+    handleFormSubmission?: (result: PageSpeedFormSubmissionResult) => void | Promise<void>;
+    /**
+     * Redirect destination used when behavior is "redirect".
+     */
+    redirectUrl?: string;
+    /**
+     * Custom component rendered when behavior is "renderCustomComponent".
+     */
+    customComponent?: ReactNode;
+    /**
+     * Optional action to allow a fresh submission after success.
+     */
+    newFormSubmissionAction?: NewFormSubmissionActionConfig;
+}
+interface PageSpeedFormConfig {
+    /**
+     * API endpoint used for submission (also applied to form action).
+     */
+    endpoint?: string;
+    /**
+     * HTTP method for submission.
+     * @default "post"
+     */
+    method?: PageSpeedFormMethod;
+    /**
+     * Submission format.
+     * Defaults to "rails" when apiKey is present, otherwise "json".
+     */
+    format?: PageSpeedFormSubmissionFormat;
+    /**
+     * Additional headers for the submission request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Static values merged into the payload (e.g. subject, content).
+     */
+    values?: Record<string, unknown>;
+    /**
+     * Rails API key (required for rails format).
+     */
+    apiKey?: string;
+    /**
+     * Rails contact category token.
+     */
+    contactCategoryToken?: string;
+    /**
+     * Rails location ID.
+     */
+    locationId?: string;
+    /**
+     * Rails website ID.
+     */
+    websiteId?: string;
+    /**
+     * Rails website form assignment ID.
+     */
+    websiteFormAssignmentId?: string;
+    /**
+     * Rails visitor IP address override.
+     */
+    visitorIpAddress?: string;
+    /**
+     * Reset form values after a successful submission.
+     * @default true
+     */
+    resetOnSuccess?: boolean;
+    /**
+     * Optional post-submission behavior configuration.
+     */
+    submissionConfig?: PageSpeedFormSubmissionConfig;
+}
+declare class PageSpeedFormSubmissionError extends Error {
+    formErrors?: FormErrors;
+    status?: number;
+    constructor(message: string, options?: {
+        formErrors?: FormErrors;
+        status?: number;
+    });
+}
+declare function isValidEmail(value: string): boolean;
+declare function submitPageSpeedForm(values: Record<string, any>, config?: PageSpeedFormConfig): Promise<unknown>;
+
+/**
+ * Dynamic form field schema types and helpers.
+ *
+ * These utilities are intentionally exposed from the integration layer so
+ * block/rendering libraries can share one field schema contract.
+ */
+type FormFieldType = "text" | "email" | "search" | "password" | "tel" | "textarea" | "select" | "radio" | "checkbox" | "checkbox-group" | "number" | "url" | "date" | "date-picker" | "date-range" | "time" | "file" | "multi-select";
+interface SelectOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+    description?: string;
+}
+interface FormFieldConfig {
+    /**
+     * Unique field name (used as the key in form values)
+     */
+    name: string;
+    /**
+     * Field type
+     */
+    type: FormFieldType;
+    /**
+     * Display label for the field
+     */
+    label: string;
+    /**
+     * Placeholder text
+     */
+    placeholder?: string;
+    /**
+     * Whether the field is required
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Column span in grid layout (1-12)
+     * @default 12 (full width)
+     */
+    columnSpan?: number;
+    /**
+     * Options for select/radio/checkbox-group fields
+     */
+    options?: SelectOption[];
+    /**
+     * Number of rows for textarea
+     * @default 4
+     */
+    rows?: number;
+    /**
+     * Custom validation function
+     * Return undefined for valid, or an error message string for invalid
+     */
+    validator?: (value: any, allValues: Record<string, any>) => string | undefined;
+    /**
+     * Additional CSS classes for the field wrapper
+     */
+    className?: string;
+    /**
+     * Whether the field is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Accepted file types for file inputs (MIME types or extensions)
+     * @example ".pdf,.doc,.docx"
+     * @example "image/*,application/pdf"
+     */
+    accept?: string;
+    /**
+     * Maximum file size in bytes for file inputs
+     * @default 5MB (5 * 1024 * 1024)
+     */
+    maxSize?: number;
+    /**
+     * Maximum number of files for file inputs
+     * @default 1
+     */
+    maxFiles?: number;
+    /**
+     * Allow multiple file selection
+     * @default false
+     */
+    multiple?: boolean;
+    /**
+     * Description/help text displayed with the field
+     */
+    description?: string;
+    /**
+     * Layout for radio/checkbox groups
+     * @default "stacked"
+     */
+    layout?: "grid" | "stacked";
+}
+/**
+ * Generate initial values object from form field configs.
+ */
+declare function generateInitialValues(fields: FormFieldConfig[]): Record<string, any>;
+/**
+ * Generate validation schema from form field configs.
+ */
+declare function generateValidationSchema(fields: FormFieldConfig[]): Record<string, (value: any, allValues: Record<string, any>) => string | undefined>;
+/**
+ * Get grid column span class for Tailwind.
+ *
+ * On small screens the field is always full-width, then from `md` and up the
+ * configured span is applied.
+ */
+declare function getColumnSpanClass(span?: number): string;
+
+interface FileUploadProgress {
+    [fileName: string]: number;
+}
+interface UseFileUploadReturn {
+    uploadTokens: string[];
+    uploadProgress: FileUploadProgress;
+    isUploading: boolean;
+    uploadFiles: (files: File[]) => Promise<void>;
+    removeFile: (file: File, index: number) => void;
+    resetUpload: () => void;
+}
+interface UseFileUploadOptions {
+    onError?: (error: Error) => void;
+    /**
+     * Upload endpoint.
+     *
+     * Defaults to DashTrack contact form uploads endpoint.
+     */
+    endpoint?: string;
+}
+/**
+ * Upload helper for two-phase contact form uploads.
+ */
+declare function useFileUpload(options?: UseFileUploadOptions): UseFileUploadReturn;
+
+interface UseContactFormOptions {
+    /**
+     * Form field configurations.
+     */
+    formFields: FormFieldConfig[];
+    /**
+     * Form submission configuration.
+     */
+    formConfig?: PageSpeedFormConfig;
+    /**
+     * Optional custom submit handler.
+     */
+    onSubmit?: (values: Record<string, any>) => void | Promise<void>;
+    /**
+     * Optional success callback.
+     */
+    onSuccess?: (data: unknown) => void;
+    /**
+     * Optional error callback.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Reset form values after successful submission.
+     * @default true
+     */
+    resetOnSuccess?: boolean;
+    /**
+     * File upload tokens merged into payload.
+     */
+    uploadTokens?: string[];
+    /**
+     * Optional app-level navigation handler for internal redirects.
+     * Return `false` to force fallback browser navigation.
+     */
+    navigate?: (href: string) => boolean | void;
+}
+interface UseContactFormReturn {
+    form: UseFormReturn<Record<string, any>>;
+    isSubmitted: boolean;
+    submissionError: string | null;
+    formMethod: "get" | "post";
+    resetSubmissionState: () => void;
+}
+/**
+ * Form orchestration helper for dynamic contact forms.
+ */
+declare function useContactForm(options: UseContactFormOptions): UseContactFormReturn;
+
+interface DynamicFormFieldProps {
+    field: FormFieldConfig;
+    className?: string;
+    uploadProgress?: {
+        [fileName: string]: number;
+    };
+    onFileUpload?: (files: File[]) => Promise<void>;
+    onFileRemove?: (file: File, index: number) => void;
+    isUploading?: boolean;
+}
+/**
+ * Dynamic renderer for form field schema configuration.
+ */
+declare function DynamicFormField({ field, className, uploadProgress, onFileUpload, onFileRemove, isUploading, }: DynamicFormFieldProps): React.JSX.Element;
+
+export { type AdaptedComponentProps, type Block, type BlockAdapterOptions, DynamicFormField, type DynamicFormFieldProps, type FileUploadProgress, type FormErrors, type FormFieldConfig, type FormFieldType, type PageSpeedFormConfig, type PageSpeedFormMethod, type PageSpeedFormSubmissionConfig, PageSpeedFormSubmissionError, type PageSpeedFormSubmissionFormat, type PageSpeedFormSubmissionResult, type RailsApiConfig, type RailsErrorResponse, type SelectOption, type SerializedFormData, type UseContactFormOptions, type UseContactFormReturn, type UseFileUploadOptions, type UseFileUploadReturn, createBlockAdapter, createBlockAdapters, deserializeErrors, generateInitialValues, generateValidationSchema, getColumnSpanClass, isValidEmail, serializeForRails, standardInputTransformer, submitPageSpeedForm, useContactForm, useFileUpload };

package/dist/integration.d.ts

@@ -1,4 +1,6 @@
 import * as React from 'react';
+import { ReactNode } from 'react';
+import { d as FormSubmissionBehavior, N as NewFormSubmissionActionConfig, m as UseFormReturn } from './types-CnOCn7b3.js';
 
 /**
  * @page-speed/forms - Rails API Serializer
@@ -378,4 +380,299 @@ declare function standardInputTransformer(blockProps: Record<string, unknown>, b
  */
 declare function createBlockAdapters<TComponents extends Record<string, React.ComponentType<any>>>(components: TComponents, options?: BlockAdapterOptions): Record<keyof TComponents, React.ComponentType<AdaptedComponentProps>>;
 
-export { type AdaptedComponentProps, type Block, type BlockAdapterOptions, type FormErrors, type RailsApiConfig, type RailsErrorResponse, type SerializedFormData, createBlockAdapter, createBlockAdapters, deserializeErrors, serializeForRails, standardInputTransformer };
+type PageSpeedFormMethod = "post" | "get" | "put" | "patch";
+type PageSpeedFormSubmissionFormat = "json" | "rails";
+interface PageSpeedFormSubmissionResult {
+    formData: Record<string, any>;
+    responseData: unknown;
+}
+interface PageSpeedFormSubmissionConfig {
+    /**
+     * Post-submit behavior.
+     * @default "showConfirmation"
+     */
+    behavior?: FormSubmissionBehavior;
+    /**
+     * Optional callback triggered on successful submission.
+     */
+    handleFormSubmission?: (result: PageSpeedFormSubmissionResult) => void | Promise<void>;
+    /**
+     * Redirect destination used when behavior is "redirect".
+     */
+    redirectUrl?: string;
+    /**
+     * Custom component rendered when behavior is "renderCustomComponent".
+     */
+    customComponent?: ReactNode;
+    /**
+     * Optional action to allow a fresh submission after success.
+     */
+    newFormSubmissionAction?: NewFormSubmissionActionConfig;
+}
+interface PageSpeedFormConfig {
+    /**
+     * API endpoint used for submission (also applied to form action).
+     */
+    endpoint?: string;
+    /**
+     * HTTP method for submission.
+     * @default "post"
+     */
+    method?: PageSpeedFormMethod;
+    /**
+     * Submission format.
+     * Defaults to "rails" when apiKey is present, otherwise "json".
+     */
+    format?: PageSpeedFormSubmissionFormat;
+    /**
+     * Additional headers for the submission request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Static values merged into the payload (e.g. subject, content).
+     */
+    values?: Record<string, unknown>;
+    /**
+     * Rails API key (required for rails format).
+     */
+    apiKey?: string;
+    /**
+     * Rails contact category token.
+     */
+    contactCategoryToken?: string;
+    /**
+     * Rails location ID.
+     */
+    locationId?: string;
+    /**
+     * Rails website ID.
+     */
+    websiteId?: string;
+    /**
+     * Rails website form assignment ID.
+     */
+    websiteFormAssignmentId?: string;
+    /**
+     * Rails visitor IP address override.
+     */
+    visitorIpAddress?: string;
+    /**
+     * Reset form values after a successful submission.
+     * @default true
+     */
+    resetOnSuccess?: boolean;
+    /**
+     * Optional post-submission behavior configuration.
+     */
+    submissionConfig?: PageSpeedFormSubmissionConfig;
+}
+declare class PageSpeedFormSubmissionError extends Error {
+    formErrors?: FormErrors;
+    status?: number;
+    constructor(message: string, options?: {
+        formErrors?: FormErrors;
+        status?: number;
+    });
+}
+declare function isValidEmail(value: string): boolean;
+declare function submitPageSpeedForm(values: Record<string, any>, config?: PageSpeedFormConfig): Promise<unknown>;
+
+/**
+ * Dynamic form field schema types and helpers.
+ *
+ * These utilities are intentionally exposed from the integration layer so
+ * block/rendering libraries can share one field schema contract.
+ */
+type FormFieldType = "text" | "email" | "search" | "password" | "tel" | "textarea" | "select" | "radio" | "checkbox" | "checkbox-group" | "number" | "url" | "date" | "date-picker" | "date-range" | "time" | "file" | "multi-select";
+interface SelectOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+    description?: string;
+}
+interface FormFieldConfig {
+    /**
+     * Unique field name (used as the key in form values)
+     */
+    name: string;
+    /**
+     * Field type
+     */
+    type: FormFieldType;
+    /**
+     * Display label for the field
+     */
+    label: string;
+    /**
+     * Placeholder text
+     */
+    placeholder?: string;
+    /**
+     * Whether the field is required
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Column span in grid layout (1-12)
+     * @default 12 (full width)
+     */
+    columnSpan?: number;
+    /**
+     * Options for select/radio/checkbox-group fields
+     */
+    options?: SelectOption[];
+    /**
+     * Number of rows for textarea
+     * @default 4
+     */
+    rows?: number;
+    /**
+     * Custom validation function
+     * Return undefined for valid, or an error message string for invalid
+     */
+    validator?: (value: any, allValues: Record<string, any>) => string | undefined;
+    /**
+     * Additional CSS classes for the field wrapper
+     */
+    className?: string;
+    /**
+     * Whether the field is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Accepted file types for file inputs (MIME types or extensions)
+     * @example ".pdf,.doc,.docx"
+     * @example "image/*,application/pdf"
+     */
+    accept?: string;
+    /**
+     * Maximum file size in bytes for file inputs
+     * @default 5MB (5 * 1024 * 1024)
+     */
+    maxSize?: number;
+    /**
+     * Maximum number of files for file inputs
+     * @default 1
+     */
+    maxFiles?: number;
+    /**
+     * Allow multiple file selection
+     * @default false
+     */
+    multiple?: boolean;
+    /**
+     * Description/help text displayed with the field
+     */
+    description?: string;
+    /**
+     * Layout for radio/checkbox groups
+     * @default "stacked"
+     */
+    layout?: "grid" | "stacked";
+}
+/**
+ * Generate initial values object from form field configs.
+ */
+declare function generateInitialValues(fields: FormFieldConfig[]): Record<string, any>;
+/**
+ * Generate validation schema from form field configs.
+ */
+declare function generateValidationSchema(fields: FormFieldConfig[]): Record<string, (value: any, allValues: Record<string, any>) => string | undefined>;
+/**
+ * Get grid column span class for Tailwind.
+ *
+ * On small screens the field is always full-width, then from `md` and up the
+ * configured span is applied.
+ */
+declare function getColumnSpanClass(span?: number): string;
+
+interface FileUploadProgress {
+    [fileName: string]: number;
+}
+interface UseFileUploadReturn {
+    uploadTokens: string[];
+    uploadProgress: FileUploadProgress;
+    isUploading: boolean;
+    uploadFiles: (files: File[]) => Promise<void>;
+    removeFile: (file: File, index: number) => void;
+    resetUpload: () => void;
+}
+interface UseFileUploadOptions {
+    onError?: (error: Error) => void;
+    /**
+     * Upload endpoint.
+     *
+     * Defaults to DashTrack contact form uploads endpoint.
+     */
+    endpoint?: string;
+}
+/**
+ * Upload helper for two-phase contact form uploads.
+ */
+declare function useFileUpload(options?: UseFileUploadOptions): UseFileUploadReturn;
+
+interface UseContactFormOptions {
+    /**
+     * Form field configurations.
+     */
+    formFields: FormFieldConfig[];
+    /**
+     * Form submission configuration.
+     */
+    formConfig?: PageSpeedFormConfig;
+    /**
+     * Optional custom submit handler.
+     */
+    onSubmit?: (values: Record<string, any>) => void | Promise<void>;
+    /**
+     * Optional success callback.
+     */
+    onSuccess?: (data: unknown) => void;
+    /**
+     * Optional error callback.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Reset form values after successful submission.
+     * @default true
+     */
+    resetOnSuccess?: boolean;
+    /**
+     * File upload tokens merged into payload.
+     */
+    uploadTokens?: string[];
+    /**
+     * Optional app-level navigation handler for internal redirects.
+     * Return `false` to force fallback browser navigation.
+     */
+    navigate?: (href: string) => boolean | void;
+}
+interface UseContactFormReturn {
+    form: UseFormReturn<Record<string, any>>;
+    isSubmitted: boolean;
+    submissionError: string | null;
+    formMethod: "get" | "post";
+    resetSubmissionState: () => void;
+}
+/**
+ * Form orchestration helper for dynamic contact forms.
+ */
+declare function useContactForm(options: UseContactFormOptions): UseContactFormReturn;
+
+interface DynamicFormFieldProps {
+    field: FormFieldConfig;
+    className?: string;
+    uploadProgress?: {
+        [fileName: string]: number;
+    };
+    onFileUpload?: (files: File[]) => Promise<void>;
+    onFileRemove?: (file: File, index: number) => void;
+    isUploading?: boolean;
+}
+/**
+ * Dynamic renderer for form field schema configuration.
+ */
+declare function DynamicFormField({ field, className, uploadProgress, onFileUpload, onFileRemove, isUploading, }: DynamicFormFieldProps): React.JSX.Element;
+
+export { type AdaptedComponentProps, type Block, type BlockAdapterOptions, DynamicFormField, type DynamicFormFieldProps, type FileUploadProgress, type FormErrors, type FormFieldConfig, type FormFieldType, type PageSpeedFormConfig, type PageSpeedFormMethod, type PageSpeedFormSubmissionConfig, PageSpeedFormSubmissionError, type PageSpeedFormSubmissionFormat, type PageSpeedFormSubmissionResult, type RailsApiConfig, type RailsErrorResponse, type SelectOption, type SerializedFormData, type UseContactFormOptions, type UseContactFormReturn, type UseFileUploadOptions, type UseFileUploadReturn, createBlockAdapter, createBlockAdapters, deserializeErrors, generateInitialValues, generateValidationSchema, getColumnSpanClass, isValidEmail, serializeForRails, standardInputTransformer, submitPageSpeedForm, useContactForm, useFileUpload };