@btst/plugin-form-builder 0.0.0-stage → 1.0.0-beta.0

package/dist/client/index.d.mts

@@ -0,0 +1,410 @@
+import * as _btst_stack_client from '@btst/stack/client';
+import * as _btst_yar from '@btst/yar';
+import * as react from 'react';
+import { ComponentType } from 'react';
+import { A as AutoFormInputComponentProps, F as FormListPageComponent } from '../shared/plugin-form-builder.DWrQ3lRX.mjs';
+import { z } from 'zod';
+import 'react-hook-form';
+
+declare const FORM_BUILDER_LOCALIZATION: {
+    FORM_BUILDER_RENDERER_LOAD_FAILED: string;
+    FORM_BUILDER_RENDERER_UNEXPECTED_ERROR: string;
+    FORM_BUILDER_RENDERER_SUBMITTED_TITLE: string;
+    FORM_BUILDER_RENDERER_NOT_FOUND: string;
+    FORM_BUILDER_RENDERER_INACTIVE: string;
+    FORM_BUILDER_RENDERER_SCHEMA_ERROR: string;
+    FORM_BUILDER_RENDERER_THANK_YOU: string;
+    FORM_BUILDER_SUBMISSIONS_TITLE: string;
+    FORM_BUILDER_SUBMISSIONS_SUBTITLE: string;
+    FORM_BUILDER_SUBMISSIONS_EMPTY: string;
+    FORM_BUILDER_SUBMISSIONS_EMPTY_DESCRIPTION: string;
+    FORM_BUILDER_SUBMISSIONS_COLUMN_ID: string;
+    FORM_BUILDER_SUBMISSIONS_COLUMN_DATA: string;
+    FORM_BUILDER_SUBMISSIONS_COLUMN_SUBMITTED_AT: string;
+    FORM_BUILDER_SUBMISSIONS_COLUMN_IP_ADDRESS: string;
+    FORM_BUILDER_SUBMISSIONS_COLUMN_ACTIONS: string;
+    FORM_BUILDER_SUBMISSIONS_ACTION_VIEW: string;
+    FORM_BUILDER_SUBMISSIONS_ACTION_DELETE: string;
+    FORM_BUILDER_SUBMISSIONS_DELETE_TITLE: string;
+    FORM_BUILDER_SUBMISSIONS_DELETE_CONFIRM: string;
+    FORM_BUILDER_SUBMISSIONS_BACK_TO_FORM: string;
+    FORM_BUILDER_SUBMISSIONS_DETAILS_TITLE: string;
+    FORM_BUILDER_SUBMISSIONS_FIELD_ID: string;
+    FORM_BUILDER_SUBMISSIONS_FIELD_SUBMITTED: string;
+    FORM_BUILDER_SUBMISSIONS_FIELD_IP: string;
+    FORM_BUILDER_SUBMISSIONS_FIELD_USER_AGENT: string;
+    FORM_BUILDER_SUBMISSIONS_FIELD_DATA: string;
+    FORM_BUILDER_EDITOR_TITLE_NEW: string;
+    FORM_BUILDER_EDITOR_TITLE_EDIT: string;
+    FORM_BUILDER_EDITOR_SLUG_AUTO: string;
+    FORM_BUILDER_EDITOR_SLUG_MANUAL: string;
+    FORM_BUILDER_EDITOR_DELETE_CONFIRM: string;
+    FORM_BUILDER_EDITOR_UNSAVED_CHANGES: string;
+    FORM_BUILDER_EDITOR_NAME_PLACEHOLDER: string;
+    FORM_BUILDER_EDITOR_SLUG_PLACEHOLDER: string;
+    FORM_BUILDER_EDITOR_DESCRIPTION_PLACEHOLDER: string;
+    FORM_BUILDER_EDITOR_SUCCESS_MESSAGE_LABEL: string;
+    FORM_BUILDER_EDITOR_SUCCESS_MESSAGE_PLACEHOLDER: string;
+    FORM_BUILDER_EDITOR_REDIRECT_URL_LABEL: string;
+    FORM_BUILDER_EDITOR_REDIRECT_URL_PLACEHOLDER: string;
+    FORM_BUILDER_LIST_TITLE: string;
+    FORM_BUILDER_LIST_SUBTITLE: string;
+    FORM_BUILDER_LIST_EMPTY: string;
+    FORM_BUILDER_LIST_EMPTY_DESCRIPTION: string;
+    FORM_BUILDER_LIST_COLUMN_NAME: string;
+    FORM_BUILDER_LIST_COLUMN_SLUG: string;
+    FORM_BUILDER_LIST_COLUMN_STATUS: string;
+    FORM_BUILDER_LIST_COLUMN_CREATED: string;
+    FORM_BUILDER_LIST_COLUMN_ACTIONS: string;
+    FORM_BUILDER_LIST_ACTION_EDIT: string;
+    FORM_BUILDER_LIST_ACTION_DELETE: string;
+    FORM_BUILDER_LIST_ACTION_SUBMISSIONS: string;
+    FORM_BUILDER_LIST_DELETE_TITLE: string;
+    FORM_BUILDER_LIST_SEARCH_PLACEHOLDER: string;
+    FORM_BUILDER_LIST_SEARCH_EMPTY: string;
+    FORM_BUILDER_LIST_SEARCH_EMPTY_DESCRIPTION: string;
+    FORM_BUILDER_LIST_PAGINATION_SHOWING: string;
+    FORM_BUILDER_LIST_PAGINATION_PREVIOUS: string;
+    FORM_BUILDER_LIST_PAGINATION_NEXT: string;
+    FORM_BUILDER_TOAST_CREATE_SUCCESS: string;
+    FORM_BUILDER_TOAST_UPDATE_SUCCESS: string;
+    FORM_BUILDER_TOAST_DELETE_SUCCESS: string;
+    FORM_BUILDER_TOAST_SUBMIT_SUCCESS: string;
+    FORM_BUILDER_TOAST_ERROR: string;
+    FORM_BUILDER_TOAST_VALIDATION_ERROR: string;
+    FORM_BUILDER_TOAST_DUPLICATE_SLUG: string;
+    FORM_BUILDER_TOAST_SUBMISSION_DELETED: string;
+    FORM_BUILDER_TOAST_NAME_REQUIRED: string;
+    FORM_BUILDER_TOAST_SLUG_REQUIRED: string;
+    FORM_BUILDER_TOAST_SCHEMA_REQUIRED: string;
+    FORM_BUILDER_BUTTON_SAVE: string;
+    FORM_BUILDER_BUTTON_CANCEL: string;
+    FORM_BUILDER_BUTTON_DELETE: string;
+    FORM_BUILDER_BUTTON_CREATE: string;
+    FORM_BUILDER_BUTTON_BACK: string;
+    FORM_BUILDER_BUTTON_NEW_FORM: string;
+    FORM_BUILDER_BUTTON_SUBMIT: string;
+    FORM_BUILDER_LABEL_NAME: string;
+    FORM_BUILDER_LABEL_SLUG: string;
+    FORM_BUILDER_LABEL_SLUG_DESCRIPTION: string;
+    FORM_BUILDER_LABEL_DESCRIPTION: string;
+    FORM_BUILDER_LABEL_STATUS: string;
+    FORM_BUILDER_LABEL_CREATED_AT: string;
+    FORM_BUILDER_LABEL_UPDATED_AT: string;
+    FORM_BUILDER_LABEL_ACTIONS: string;
+    FORM_BUILDER_STATUS_LOADING: string;
+    FORM_BUILDER_STATUS_SAVING: string;
+    FORM_BUILDER_STATUS_DELETING: string;
+    FORM_BUILDER_STATUS_ACTIVE: string;
+    FORM_BUILDER_STATUS_INACTIVE: string;
+    FORM_BUILDER_STATUS_ARCHIVED: string;
+    FORM_BUILDER_ERROR_GENERIC: string;
+    FORM_BUILDER_ERROR_NOT_FOUND: string;
+    FORM_BUILDER_ERROR_VALIDATION: string;
+    FORM_BUILDER_404_TITLE: string;
+    FORM_BUILDER_404_DESCRIPTION: string;
+    FORM_BUILDER_404_BACK: string;
+    FORM_BUILDER_ATTRIBUTION: string;
+};
+type FormBuilderLocalization = typeof FORM_BUILDER_LOCALIZATION;
+
+/**
+ * Context passed to lifecycle hooks
+ */
+interface RouteContext {
+    /** Current route path */
+    path: string;
+    /** Route parameters (e.g., { id: "123" }) */
+    params?: Record<string, string>;
+    /** Whether rendering on server (true) or client (false) */
+    isSSR: boolean;
+    /** Additional context properties */
+    [key: string]: unknown;
+}
+/**
+ * Overridable components and functions for the Form Builder plugin
+ *
+ * External consumers can provide their own implementations to customize
+ * plugin-specific components and behavior.
+ */
+interface FormBuilderPluginOverrides {
+    /**
+     * Custom field components for AutoForm fields.
+     *
+     * These map field type names to React components. Use these to:
+     * - Override built-in field types (checkbox, date, select, radio, switch, textarea, file, number, fallback)
+     * - Add custom field types for your forms
+     *
+     * @example
+     * ```tsx
+     * fieldComponents: {
+     *   // Override the file type with custom S3 upload
+     *   file: ({ field, label, isRequired }) => (
+     *     <MyS3Upload
+     *       value={field.value}
+     *       onChange={field.onChange}
+     *       label={label}
+     *       required={isRequired}
+     *     />
+     *   ),
+     *   // Add a custom rich text editor
+     *   richText: ({ field, label }) => (
+     *     <MyRichTextEditor value={field.value} onChange={field.onChange} />
+     *   ),
+     * }
+     * ```
+     */
+    fieldComponents?: Record<string, ComponentType<AutoFormInputComponentProps>>;
+    /**
+     * Optional class names merged onto specific UI elements.
+     * Use these for targeted styling without replacing whole components.
+     */
+    classNames?: {
+        /** Page container shared by every Form Builder page */
+        container?: string;
+        /** Wrapper around the forms or submissions table */
+        table?: string;
+        /** Each body row in the forms or submissions table */
+        tableRow?: string;
+        /** Pagination footer under the forms or submissions list */
+        pagination?: string;
+        /** Root of `FormRenderer`, including loading, error, and success states */
+        form?: string;
+    };
+    /**
+     * Localization object for the Form Builder plugin
+     */
+    localization?: Partial<FormBuilderLocalization>;
+    /**
+     * Whether to show the attribution
+     */
+    showAttribution?: boolean;
+    /**
+     * Called when a route is rendered
+     * @param routeName - Name of the route (e.g., 'formList', 'formBuilder', 'submissions')
+     * @param context - Route context with path, params, etc.
+     */
+    onRouteRender?: (routeName: string, context: RouteContext) => void | Promise<void>;
+    /**
+     * Called when a route encounters an error
+     * @param routeName - Name of the route
+     * @param error - The error that occurred
+     * @param context - Route context
+     */
+    onRouteError?: (routeName: string, error: Error, context: RouteContext) => void | Promise<void>;
+}
+
+/**
+ * Context passed to loader hooks
+ */
+interface LoaderContext {
+    /** Current route path */
+    path: string;
+    /** Route parameters (e.g., { id: "123" }) */
+    params?: Record<string, string>;
+    /** Whether rendering on server (true) or client (false) */
+    isSSR: boolean;
+    /** Base URL for API calls */
+    apiBaseURL: string;
+    /** Path where the API is mounted */
+    apiBasePath: string;
+    /** Optional headers for the request */
+    headers?: Headers;
+    /** Additional context properties */
+    [key: string]: unknown;
+}
+/**
+ * Hooks for Form Builder client plugin
+ * All hooks are optional and allow consumers to customize behavior
+ */
+interface FormBuilderClientHooks {
+    /**
+     * Called before loading the form list page. Throw an error to cancel loading.
+     * @param context - Loader context with path, params, etc.
+     */
+    beforeLoadFormList?: (context: LoaderContext) => Promise<void> | void;
+    /**
+     * Called after the form list is loaded.
+     * @param context - Loader context
+     */
+    afterLoadFormList?: (context: LoaderContext) => Promise<void> | void;
+    /**
+     * Called before loading the form builder page. Throw an error to cancel loading.
+     * @param id - The form ID (undefined for new forms)
+     * @param context - Loader context
+     */
+    beforeLoadFormBuilder?: (id: string | undefined, context: LoaderContext) => Promise<void> | void;
+    /**
+     * Called after the form builder is loaded.
+     * @param id - The form ID (undefined for new forms)
+     * @param context - Loader context
+     */
+    afterLoadFormBuilder?: (id: string | undefined, context: LoaderContext) => Promise<void> | void;
+    /**
+     * Called before loading the submissions page. Throw an error to cancel loading.
+     * @param formId - The form ID
+     * @param context - Loader context
+     */
+    beforeLoadSubmissions?: (formId: string, context: LoaderContext) => Promise<void> | void;
+    /**
+     * Called after the submissions page is loaded.
+     * @param formId - The form ID
+     * @param context - Loader context
+     */
+    afterLoadSubmissions?: (formId: string, context: LoaderContext) => Promise<void> | void;
+    /**
+     * Called when a loading error occurs.
+     * Use this to report loader failures. Router error handling remains authoritative.
+     * @param error - The error that occurred
+     * @param context - Loader context
+     */
+    onErrorLoad?: (error: Error, context: LoaderContext) => Promise<void> | void;
+}
+/**
+ * Configuration for Form Builder client plugin
+ */
+interface FormBuilderClientConfig {
+    /** Optional hooks for route loading, redirects, and telemetry. */
+    hooks?: FormBuilderClientHooks;
+    /**
+     * Optional page component overrides.
+     * Replace any plugin page with a custom React component.
+     * The built-in component is used as the fallback when not provided.
+     */
+    pageComponents?: {
+        /** Replaces the form list page */
+        formList?: ComponentType;
+        /** Replaces the new form page */
+        newForm?: ComponentType;
+        /** Replaces the form editor page */
+        editForm?: ComponentType<{
+            params: {
+                id: string;
+            };
+        }>;
+        /** Replaces the form submissions page */
+        submissions?: ComponentType<{
+            params: {
+                id: string;
+            };
+        }>;
+    };
+}
+declare const formBuilderClientPlugin: (config?: FormBuilderClientConfig) => _btst_stack_client.ClientPluginDefinition<FormBuilderPluginOverrides, {
+    formList: _btst_yar.DefinedRoute<"/forms", {
+        readonly page: react.LazyExoticComponent<typeof FormListPageComponent>;
+        readonly loader: () => Promise<void>;
+        readonly meta: () => ({
+            title: string;
+            name?: undefined;
+            content?: undefined;
+        } | {
+            name: string;
+            content: string;
+            title?: undefined;
+        })[];
+    }, _btst_yar.RouteMeta>;
+    newForm: _btst_yar.DefinedRoute<"/forms/new", {
+        readonly page: () => react.JSX.Element;
+        readonly loader: () => Promise<void>;
+        readonly meta: () => ({
+            title: string;
+            name?: undefined;
+            content?: undefined;
+        } | {
+            name: string;
+            content: string;
+            title?: undefined;
+        })[];
+    }, _btst_yar.RouteMeta>;
+    editForm: _btst_yar.DefinedRoute<"/forms/:id/edit", {
+        readonly page: ({ params }: _btst_yar.RouteContext<"/forms/:id/edit", _btst_yar.RouteOptions>) => react.JSX.Element;
+        readonly loader: ({ params }: _btst_yar.RouteContext<"/forms/:id/edit", _btst_yar.RouteOptions>) => Promise<void>;
+        readonly meta: ({ params }: _btst_yar.RouteContext<"/forms/:id/edit", _btst_yar.RouteOptions>) => ({
+            title: string;
+            name?: undefined;
+            content?: undefined;
+        } | {
+            name: string;
+            content: string;
+            title?: undefined;
+        })[];
+    }, _btst_yar.RouteMeta>;
+    submissions: _btst_yar.DefinedRoute<"/forms/:id/submissions", {
+        readonly page: ({ params }: _btst_yar.RouteContext<"/forms/:id/submissions", _btst_yar.RouteOptions>) => react.JSX.Element;
+        readonly loader: ({ params }: _btst_yar.RouteContext<"/forms/:id/submissions", _btst_yar.RouteOptions>) => Promise<void>;
+        readonly meta: ({ params }: _btst_yar.RouteContext<"/forms/:id/submissions", _btst_yar.RouteOptions>) => ({
+            title: string;
+            name?: undefined;
+            content?: undefined;
+        } | {
+            name: string;
+            content: string;
+            title?: undefined;
+        })[];
+    }, _btst_yar.RouteMeta>;
+}, "formBuilder", Readonly<Record<string, never>>, never>;
+
+interface FormStep {
+    id: string;
+    title: string;
+}
+interface FormSchemaMetadata {
+    /** Multi-step form step definitions */
+    steps?: FormStep[];
+    /** Map of field names to their step indices */
+    stepGroupMap?: Record<string, number>;
+}
+interface JsonSchemaProperty {
+    type?: string;
+    format?: string;
+    formatMinimum?: string;
+    formatMaximum?: string;
+    stepGroup?: number;
+    properties?: Record<string, JsonSchemaProperty>;
+    [key: string]: unknown;
+}
+interface FormJsonSchema {
+    type?: string;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    steps?: FormStep[];
+    stepGroupMap?: Record<string, number>;
+    [key: string]: unknown;
+}
+/**
+ * Convert a Zod schema to JSON Schema with proper handling for:
+ * - z.date() → { type: "string", format: "date-time" }
+ * - Date min/max constraints → formatMinimum/formatMaximum
+ * - Steps metadata (if provided via schema.meta() or explicit metadata param)
+ *
+ * @param schema - The Zod schema to convert
+ * @param metadata - Optional explicit metadata to include (overrides schema meta)
+ */
+declare function zodToFormSchema<T extends z.ZodType>(schema: T, metadata?: FormSchemaMetadata): FormJsonSchema;
+/**
+ * Convert JSON Schema to Zod schema with proper handling for:
+ * - { type: "string", format: "date-time" } → date field (with constraints)
+ * - Steps metadata re-attachment (preserved via .meta())
+ * - Step group mapping
+ *
+ * @param jsonSchema - The JSON Schema to convert
+ * @returns A Zod schema ready for validation, with all metadata preserved
+ */
+declare function formSchemaToZod(jsonSchema: FormJsonSchema): z.ZodType;
+/**
+ * Check if a JSON Schema has multi-step configuration.
+ */
+declare function hasSteps(jsonSchema: FormJsonSchema): boolean;
+/**
+ * Get steps from a JSON Schema.
+ */
+declare function getSteps(jsonSchema: FormJsonSchema): FormStep[];
+/**
+ * Get the step group map from a JSON Schema.
+ * Returns a map of field names to step indices.
+ */
+declare function getStepGroupMap(jsonSchema: FormJsonSchema): Record<string, number>;
+
+export { AutoFormInputComponentProps, formBuilderClientPlugin, formSchemaToZod, getStepGroupMap, getSteps, hasSteps, zodToFormSchema };
+export type { FormBuilderClientConfig, FormBuilderClientHooks, FormBuilderLocalization, FormBuilderPluginOverrides, FormSchemaMetadata, FormStep, LoaderContext, RouteContext };