@fixture-inc/forms-react 0.1.0-beta.1

package/dist/index.d.cts

@@ -0,0 +1,200 @@
+import { Form as Form$1, SubmitResult, FormField, FormStatus, FieldType, FieldValueMap } from '@fixture-inc/forms-core';
+export { FieldType, FormField, FormResponse, FormStatus, Form as FormType, NormalizedError, SubmitResult } from '@fixture-inc/forms-core';
+import * as React$1 from 'react';
+import React__default from 'react';
+import { FormClient } from '@fixture-inc/forms-browser';
+export { FormClient, FormClientConfig } from '@fixture-inc/forms-browser';
+
+/**
+ * React hooks for Fixture Forms
+ */
+
+/**
+ * Options for useFixtureForm hook
+ */
+interface UseFixtureFormOptions {
+    /** API endpoint. Defaults to inferred from context or 'https://api.fixture.app' */
+    apiUrl?: string;
+    /** Disable auto-fetching. Useful for SSR or conditional rendering. Default: true */
+    enabled?: boolean;
+    /** Pre-populate with server-fetched data (for SSR hydration) */
+    initialData?: {
+        form: Form$1;
+        nonce: string;
+    };
+    /** Custom fetch function (for testing, SSR, or proxying) */
+    fetcher?: (formId: string) => Promise<{
+        form: Form$1;
+        nonce: string;
+    }>;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Called on successful submission */
+    onSuccess?: (result: SubmitResult) => void;
+    /** Called on any error */
+    onError?: (error: {
+        message: string;
+    }) => void;
+}
+/**
+ * Props for binding to form inputs
+ */
+interface FieldInputProps {
+    id: string;
+    name: string;
+    value: string | boolean;
+    onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+    required?: boolean;
+    type?: string;
+    checked?: boolean;
+}
+/**
+ * Return type for useFixtureForm hook
+ */
+interface UseFixtureFormReturn {
+    /** Form definition (null while loading) */
+    form: Form$1 | null;
+    /** Form fields array (empty while loading) */
+    fields: FormField[];
+    /** Current form status */
+    status: FormStatus;
+    /** Global error message */
+    error: string | null;
+    /** Submission result (available after success) */
+    result: SubmitResult | null;
+    /** Current field values. Use getFieldValue() for type-safe access. */
+    values: Record<string, unknown>;
+    /** Field validation errors */
+    errors: Record<string, string>;
+    /** Get field value with canonical type */
+    getFieldValue: <T extends FieldType>(fieldId: string) => FieldValueMap[T] | undefined;
+    /** Set a single field value */
+    setValue: (fieldId: string, value: unknown) => void;
+    /** Set multiple field values */
+    setValues: (values: Record<string, unknown>) => void;
+    /** Submit the form */
+    submit: () => Promise<void>;
+    /** Reset form to initial values */
+    reset: () => void;
+    /** Refetch form from server */
+    refetch: () => Promise<void>;
+    /** Get props for binding to an input element */
+    getFieldProps: (fieldId: string) => FieldInputProps;
+}
+/**
+ * Hook for using Fixture Forms in React
+ *
+ * @example
+ * ```tsx
+ * function ContactForm() {
+ *   const { form, fields, values, setValue, submit, status } = useFixtureForm('contact-form')
+ *
+ *   if (status === 'loading') return <div>Loading...</div>
+ *   if (status === 'success') return <div>Thanks!</div>
+ *
+ *   return (
+ *     <form onSubmit={(e) => { e.preventDefault(); submit(); }}>
+ *       {fields.map(field => (
+ *         <input
+ *           key={field.id}
+ *           {...getFieldProps(field.id)}
+ *         />
+ *       ))}
+ *       <button type="submit" disabled={status === 'submitting'}>
+ *         Submit
+ *       </button>
+ *     </form>
+ *   )
+ * }
+ * ```
+ */
+declare function useFixtureForm(formId: string, options?: UseFixtureFormOptions): UseFixtureFormReturn;
+/**
+ * Hook to get the visitor ID from the forms tracker
+ */
+declare function useVisitorId(): string | null;
+
+/**
+ * Context value for the forms provider
+ */
+interface FixtureFormsContextValue {
+    /** Shared FormClient instance */
+    client: FormClient;
+    /** Default API URL */
+    apiUrl?: string;
+    /** Debug mode enabled */
+    debug?: boolean;
+}
+/**
+ * Context for sharing FormClient across components
+ */
+declare const FixtureFormsContext: React$1.Context<FixtureFormsContextValue | null>;
+/**
+ * Hook to access the forms context
+ *
+ * @returns Context value or null if not in provider
+ */
+declare function useFixtureFormsContext(): FixtureFormsContextValue | null;
+
+/**
+ * Pre-built Form component
+ *
+ * A complete, styled form component that handles loading, submission, and success states.
+ */
+
+interface FormProps extends UseFixtureFormOptions {
+    /** Form ID to render */
+    formId: string;
+    /** Custom className for the form container */
+    className?: string;
+    /** Custom submit button text */
+    submitText?: string;
+    /** Custom submitting button text */
+    submittingText?: string;
+    /** Custom success title */
+    successTitle?: string;
+    /** Custom success message (overrides server response) */
+    successMessage?: string;
+    /** Custom loading message */
+    loadingMessage?: string;
+    /** Hide the "Powered by Fixture" badge */
+    hideBadge?: boolean;
+    /** Custom render function for the form */
+    children?: (props: {
+        form: Form$1;
+        fields: Form$1['fields'];
+        values: Record<string, unknown>;
+        errors: Record<string, string>;
+        setValue: (fieldId: string, value: unknown) => void;
+        getFieldProps: (fieldId: string) => FieldInputProps;
+        submit: () => Promise<void>;
+        status: string;
+    }) => React__default.ReactNode;
+}
+/**
+ * Pre-built form component with default styling
+ */
+declare function Form({ formId, className, submitText, submittingText, successTitle, successMessage, loadingMessage, hideBadge, children, ...options }: FormProps): React__default.ReactElement;
+
+/**
+ * Pre-built Field component
+ *
+ * Renders a single form field with appropriate input type and styling.
+ */
+
+interface FieldProps {
+    /** Field definition */
+    field: FormField;
+    /** Current value */
+    value: unknown;
+    /** Validation error */
+    error?: string;
+    /** Called when value changes */
+    onChange: (value: unknown) => void;
+}
+/**
+ * Render a single form field
+ */
+declare function Field({ field, value, error, onChange, }: FieldProps): React__default.ReactElement;
+
+export { Field, type FieldInputProps, type FieldProps, FixtureFormsContext, type FixtureFormsContextValue, Form, type FormProps, type UseFixtureFormOptions, type UseFixtureFormReturn, useFixtureForm, useFixtureFormsContext, useVisitorId };

package/dist/index.d.ts

@@ -0,0 +1,200 @@
+import { Form as Form$1, SubmitResult, FormField, FormStatus, FieldType, FieldValueMap } from '@fixture-inc/forms-core';
+export { FieldType, FormField, FormResponse, FormStatus, Form as FormType, NormalizedError, SubmitResult } from '@fixture-inc/forms-core';
+import * as React$1 from 'react';
+import React__default from 'react';
+import { FormClient } from '@fixture-inc/forms-browser';
+export { FormClient, FormClientConfig } from '@fixture-inc/forms-browser';
+
+/**
+ * React hooks for Fixture Forms
+ */
+
+/**
+ * Options for useFixtureForm hook
+ */
+interface UseFixtureFormOptions {
+    /** API endpoint. Defaults to inferred from context or 'https://api.fixture.app' */
+    apiUrl?: string;
+    /** Disable auto-fetching. Useful for SSR or conditional rendering. Default: true */
+    enabled?: boolean;
+    /** Pre-populate with server-fetched data (for SSR hydration) */
+    initialData?: {
+        form: Form$1;
+        nonce: string;
+    };
+    /** Custom fetch function (for testing, SSR, or proxying) */
+    fetcher?: (formId: string) => Promise<{
+        form: Form$1;
+        nonce: string;
+    }>;
+    /** Enable debug logging */
+    debug?: boolean;
+    /** Called on successful submission */
+    onSuccess?: (result: SubmitResult) => void;
+    /** Called on any error */
+    onError?: (error: {
+        message: string;
+    }) => void;
+}
+/**
+ * Props for binding to form inputs
+ */
+interface FieldInputProps {
+    id: string;
+    name: string;
+    value: string | boolean;
+    onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+    required?: boolean;
+    type?: string;
+    checked?: boolean;
+}
+/**
+ * Return type for useFixtureForm hook
+ */
+interface UseFixtureFormReturn {
+    /** Form definition (null while loading) */
+    form: Form$1 | null;
+    /** Form fields array (empty while loading) */
+    fields: FormField[];
+    /** Current form status */
+    status: FormStatus;
+    /** Global error message */
+    error: string | null;
+    /** Submission result (available after success) */
+    result: SubmitResult | null;
+    /** Current field values. Use getFieldValue() for type-safe access. */
+    values: Record<string, unknown>;
+    /** Field validation errors */
+    errors: Record<string, string>;
+    /** Get field value with canonical type */
+    getFieldValue: <T extends FieldType>(fieldId: string) => FieldValueMap[T] | undefined;
+    /** Set a single field value */
+    setValue: (fieldId: string, value: unknown) => void;
+    /** Set multiple field values */
+    setValues: (values: Record<string, unknown>) => void;
+    /** Submit the form */
+    submit: () => Promise<void>;
+    /** Reset form to initial values */
+    reset: () => void;
+    /** Refetch form from server */
+    refetch: () => Promise<void>;
+    /** Get props for binding to an input element */
+    getFieldProps: (fieldId: string) => FieldInputProps;
+}
+/**
+ * Hook for using Fixture Forms in React
+ *
+ * @example
+ * ```tsx
+ * function ContactForm() {
+ *   const { form, fields, values, setValue, submit, status } = useFixtureForm('contact-form')
+ *
+ *   if (status === 'loading') return <div>Loading...</div>
+ *   if (status === 'success') return <div>Thanks!</div>
+ *
+ *   return (
+ *     <form onSubmit={(e) => { e.preventDefault(); submit(); }}>
+ *       {fields.map(field => (
+ *         <input
+ *           key={field.id}
+ *           {...getFieldProps(field.id)}
+ *         />
+ *       ))}
+ *       <button type="submit" disabled={status === 'submitting'}>
+ *         Submit
+ *       </button>
+ *     </form>
+ *   )
+ * }
+ * ```
+ */
+declare function useFixtureForm(formId: string, options?: UseFixtureFormOptions): UseFixtureFormReturn;
+/**
+ * Hook to get the visitor ID from the forms tracker
+ */
+declare function useVisitorId(): string | null;
+
+/**
+ * Context value for the forms provider
+ */
+interface FixtureFormsContextValue {
+    /** Shared FormClient instance */
+    client: FormClient;
+    /** Default API URL */
+    apiUrl?: string;
+    /** Debug mode enabled */
+    debug?: boolean;
+}
+/**
+ * Context for sharing FormClient across components
+ */
+declare const FixtureFormsContext: React$1.Context<FixtureFormsContextValue | null>;
+/**
+ * Hook to access the forms context
+ *
+ * @returns Context value or null if not in provider
+ */
+declare function useFixtureFormsContext(): FixtureFormsContextValue | null;
+
+/**
+ * Pre-built Form component
+ *
+ * A complete, styled form component that handles loading, submission, and success states.
+ */
+
+interface FormProps extends UseFixtureFormOptions {
+    /** Form ID to render */
+    formId: string;
+    /** Custom className for the form container */
+    className?: string;
+    /** Custom submit button text */
+    submitText?: string;
+    /** Custom submitting button text */
+    submittingText?: string;
+    /** Custom success title */
+    successTitle?: string;
+    /** Custom success message (overrides server response) */
+    successMessage?: string;
+    /** Custom loading message */
+    loadingMessage?: string;
+    /** Hide the "Powered by Fixture" badge */
+    hideBadge?: boolean;
+    /** Custom render function for the form */
+    children?: (props: {
+        form: Form$1;
+        fields: Form$1['fields'];
+        values: Record<string, unknown>;
+        errors: Record<string, string>;
+        setValue: (fieldId: string, value: unknown) => void;
+        getFieldProps: (fieldId: string) => FieldInputProps;
+        submit: () => Promise<void>;
+        status: string;
+    }) => React__default.ReactNode;
+}
+/**
+ * Pre-built form component with default styling
+ */
+declare function Form({ formId, className, submitText, submittingText, successTitle, successMessage, loadingMessage, hideBadge, children, ...options }: FormProps): React__default.ReactElement;
+
+/**
+ * Pre-built Field component
+ *
+ * Renders a single form field with appropriate input type and styling.
+ */
+
+interface FieldProps {
+    /** Field definition */
+    field: FormField;
+    /** Current value */
+    value: unknown;
+    /** Validation error */
+    error?: string;
+    /** Called when value changes */
+    onChange: (value: unknown) => void;
+}
+/**
+ * Render a single form field
+ */
+declare function Field({ field, value, error, onChange, }: FieldProps): React__default.ReactElement;
+
+export { Field, type FieldInputProps, type FieldProps, FixtureFormsContext, type FixtureFormsContextValue, Form, type FormProps, type UseFixtureFormOptions, type UseFixtureFormReturn, useFixtureForm, useFixtureFormsContext, useVisitorId };