@btst/stack 1.5.2 → 1.6.0

package/dist/plugins/form-builder/client/index.d.cts

@@ -0,0 +1,381 @@
+import * as _btst_stack_plugins_client from '@btst/stack/plugins/client';
+import * as react from 'react';
+import { ComponentType } from 'react';
+import * as _btst_yar from '@btst/yar';
+import { QueryClient } from '@tanstack/react-query';
+import { A as AutoFormInputComponentProps } from '../../../shared/stack.BIh2AXaW.cjs';
+export { b as FormSchemaMetadata, F as FormStep, f as formSchemaToZod, a as getStepGroupMap, g as getSteps, h as hasSteps, z as zodToFormSchema } from '../../../shared/stack.AX5nZ6A3.cjs';
+import 'react-hook-form';
+import 'zod';
+import 'react/jsx-runtime';
+
+/**
+ * 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. Return false to cancel loading.
+     * @param context - Loader context with path, params, etc.
+     */
+    beforeLoadFormList?: (context: LoaderContext) => Promise<boolean> | boolean;
+    /**
+     * Called after the form list is loaded.
+     * @param context - Loader context
+     */
+    afterLoadFormList?: (context: LoaderContext) => Promise<void> | void;
+    /**
+     * Called before loading the form builder page. Return false to cancel loading.
+     * @param id - The form ID (undefined for new forms)
+     * @param context - Loader context
+     */
+    beforeLoadFormBuilder?: (id: string | undefined, context: LoaderContext) => Promise<boolean> | boolean;
+    /**
+     * 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. Return false to cancel loading.
+     * @param formId - The form ID
+     * @param context - Loader context
+     */
+    beforeLoadSubmissions?: (formId: string, context: LoaderContext) => Promise<boolean> | boolean;
+    /**
+     * 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 for redirects on authorization failures.
+     * @param error - The error that occurred
+     * @param context - Loader context
+     */
+    onLoadError?: (error: Error, context: LoaderContext) => Promise<void> | void;
+}
+/**
+ * Configuration for Form Builder client plugin
+ */
+interface FormBuilderClientConfig {
+    /** Base URL for API calls (e.g., "http://localhost:3000") */
+    apiBaseURL: string;
+    /** Path where the API is mounted (e.g., "/api/data") */
+    apiBasePath: string;
+    /** Base URL of your site */
+    siteBaseURL: string;
+    /** Path where pages are mounted (e.g., "/pages") */
+    siteBasePath: string;
+    /** React Query client instance for caching */
+    queryClient: QueryClient;
+    /** Optional headers for SSR (e.g., forwarding cookies) */
+    headers?: Headers;
+    /** Optional hooks for customizing behavior (authorization, redirects, etc.) */
+    hooks?: FormBuilderClientHooks;
+}
+/**
+ * Form Builder client plugin
+ * Provides routes and components for the Form Builder admin interface
+ */
+declare const formBuilderClientPlugin: (config: FormBuilderClientConfig) => _btst_stack_plugins_client.ClientPlugin<Record<string, never>, {
+    formList: {
+        (inputCtx_0?: _btst_yar.InputContext<"/forms", _btst_yar.RouteOptions> | undefined): {
+            PageComponent?: react.ComponentType<unknown> | undefined;
+            LoadingComponent?: react.ComponentType<unknown> | undefined;
+            ErrorComponent?: react.ComponentType<unknown> | undefined;
+            loader?: (() => Promise<void>) | undefined;
+            meta?: (() => ({
+                title: string;
+                name?: undefined;
+                content?: undefined;
+            } | {
+                name: string;
+                content: string;
+                title?: undefined;
+            })[]) | undefined;
+            extra?: (() => any) | undefined;
+        };
+        options: _btst_yar.RouteOptions | undefined;
+        path: "/forms";
+        meta: _btst_yar.RouteMeta | undefined;
+    };
+    newForm: {
+        (inputCtx_0?: _btst_yar.InputContext<"/forms/new", _btst_yar.RouteOptions> | undefined): {
+            PageComponent?: react.ComponentType<unknown> | undefined;
+            LoadingComponent?: react.ComponentType<unknown> | undefined;
+            ErrorComponent?: react.ComponentType<unknown> | undefined;
+            loader?: (() => Promise<void>) | undefined;
+            meta?: (() => ({
+                title: string;
+                name?: undefined;
+                content?: undefined;
+            } | {
+                name: string;
+                content: string;
+                title?: undefined;
+            })[]) | undefined;
+            extra?: (() => any) | undefined;
+        };
+        options: _btst_yar.RouteOptions | undefined;
+        path: "/forms/new";
+        meta: _btst_yar.RouteMeta | undefined;
+    };
+    editForm: {
+        (inputCtx_0: _btst_yar.InputContext<"/forms/:id/edit", _btst_yar.RouteOptions>): {
+            PageComponent?: react.ComponentType<unknown> | undefined;
+            LoadingComponent?: react.ComponentType<unknown> | undefined;
+            ErrorComponent?: react.ComponentType<unknown> | undefined;
+            loader?: (() => Promise<void>) | undefined;
+            meta?: (() => ({
+                title: string;
+                name?: undefined;
+                content?: undefined;
+            } | {
+                name: string;
+                content: string;
+                title?: undefined;
+            })[]) | undefined;
+            extra?: (() => any) | undefined;
+        };
+        options: _btst_yar.RouteOptions | undefined;
+        path: "/forms/:id/edit";
+        meta: _btst_yar.RouteMeta | undefined;
+    };
+    submissions: {
+        (inputCtx_0: _btst_yar.InputContext<"/forms/:id/submissions", _btst_yar.RouteOptions>): {
+            PageComponent?: react.ComponentType<unknown> | undefined;
+            LoadingComponent?: react.ComponentType<unknown> | undefined;
+            ErrorComponent?: react.ComponentType<unknown> | undefined;
+            loader?: (() => Promise<void>) | undefined;
+            meta?: (() => ({
+                title: string;
+                name?: undefined;
+                content?: undefined;
+            } | {
+                name: string;
+                content: string;
+                title?: undefined;
+            })[]) | undefined;
+            extra?: (() => any) | undefined;
+        };
+        options: _btst_yar.RouteOptions | undefined;
+        path: "/forms/:id/submissions";
+        meta: _btst_yar.RouteMeta | undefined;
+    };
+}>;
+
+declare const FORM_BUILDER_LOCALIZATION: {
+    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_CONFIRM: string;
+    FORM_BUILDER_SUBMISSIONS_BACK_TO_FORM: 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_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_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_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 of these
+ * to customize the behavior for their framework (Next.js, React Router, etc.)
+ */
+interface FormBuilderPluginOverrides {
+    /**
+     * Link component for navigation
+     */
+    Link?: ComponentType<React.ComponentProps<"a"> & Record<string, unknown>>;
+    /**
+     * Navigation function for programmatic navigation
+     */
+    navigate: (path: string) => void | Promise<void>;
+    /**
+     * Refresh function to invalidate server-side cache (e.g., Next.js router.refresh())
+     */
+    refresh?: () => void | Promise<void>;
+    /**
+     * 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>>;
+    /**
+     * Localization object for the Form Builder plugin
+     */
+    localization?: FormBuilderLocalization;
+    /**
+     * API base URL
+     */
+    apiBaseURL: string;
+    /**
+     * API base path
+     */
+    apiBasePath: string;
+    /**
+     * Whether to show the attribution
+     */
+    showAttribution?: boolean;
+    /**
+     * Optional headers to pass with API requests (e.g., for SSR auth)
+     */
+    headers?: HeadersInit;
+    /**
+     * 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>;
+    /**
+     * Called before the form list page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param context - Route context
+     */
+    onBeforeFormListRendered?: (context: RouteContext) => boolean;
+    /**
+     * Called before the form builder page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param id - The form ID (null for new forms)
+     * @param context - Route context
+     */
+    onBeforeFormBuilderRendered?: (id: string | null, context: RouteContext) => boolean;
+    /**
+     * Called before the submissions page is rendered
+     * Return false to prevent rendering (e.g., for authorization)
+     * @param formId - The form ID
+     * @param context - Route context
+     */
+    onBeforeSubmissionsRendered?: (formId: string, context: RouteContext) => boolean;
+}
+
+export { AutoFormInputComponentProps, formBuilderClientPlugin };
+export type { FormBuilderClientConfig, FormBuilderClientHooks, FormBuilderLocalization, FormBuilderPluginOverrides, LoaderContext, RouteContext };