@10x-media/form-builder 0.1.0-beta.0

package/dist/exports/react.d.ts

@@ -0,0 +1,550 @@
+import { n as AnyFormFieldDefinition } from "../fieldTypes-B8jkNRob.js";
+import { C as evaluateCalc, D as AggregationBucket, E as CalcExpression, F as SubmissionValue, M as FormFieldInstance, S as evaluateCondition, T as computeCalcFields, _ as PrefillOptions, c as PresentationDescriptor, g as FormEventSink, i as buildRecallResolver, k as FieldAggregation, n as DEFAULT_HONEYPOT_FIELD, o as interpolate, r as RecallResolver, t as CAPTCHA_TOKEN_KEY, u as AnyValidationRuleDefinition, v as valuesFromSearchParams } from "../constants-B-BUfetP.js";
+import { r as FormFlow } from "../types-DsJ_6kGJ.js";
+import { ComponentType, ReactNode, Ref, RefObject } from "react";
+
+//#region src/flow/engine.d.ts
+/** The entry step id (the first step), or `undefined` for an empty flow. */
+declare const firstStepId: (flow: FormFlow) => string | undefined;
+/** The field machine names a step renders (empty for an unknown step). */
+declare const stepFieldNames: (flow: FormFlow, id: string) => string[];
+/**
+ * Resolve the next step id from the current step + answers: the first transition whose `when` matches
+ * (via `evaluateCondition`), else the default `next`, else `undefined` (terminal). Pure + isomorphic.
+ */
+declare const resolveNextStepId: (flow: FormFlow, currentId: string, answers: Record<string, unknown>) => string | undefined;
+/** Whether the current step is terminal (no matching transition + no default next). */
+declare const isTerminalStepId: (flow: FormFlow, currentId: string, answers: Record<string, unknown>) => boolean;
+//#endregion
+//#region src/react/contract.d.ts
+/** A localized translator the renderer uses for built-in copy. `(key) => string`; unknown keys return the key. */
+type RendererTranslate = (key: string) => string;
+/**
+ * The props every field renderer receives. The renderer turns one field instance plus its current value
+ * into an accessible control. Supplied by `<Form>` or directly in tests. Generic over the
+ * value type so custom renderers can narrow it.
+ */
+type FieldRendererProps<TValue = unknown> = {
+  /** The stored field instance (name, label, blockType, required, placeholder, description, options, ...). */field: FormFieldInstance; /** The control's stable id, for label/aria wiring. */
+  id: string; /** The field machine name (form value key). */
+  name: string;
+  value: TValue | undefined;
+  onChange: (value: TValue) => void;
+  onBlur: () => void; /** Blocking error messages for this field (already filtered to error severity). */
+  errors: string[]; /** Advisory messages (warning severity). */
+  warnings?: string[];
+  required: boolean;
+  disabled?: boolean;
+  locale: string;
+  t: RendererTranslate;
+};
+/** A field renderer: maps `FieldRendererProps` to React output. */
+type FieldRenderer<TValue = unknown> = (props: FieldRendererProps<TValue>) => ReactNode;
+/** Identity helper that pins a renderer to the `FieldRenderer` type so authors get prop inference. */
+declare const defineFieldRenderer: <TValue = unknown>(renderer: FieldRenderer<TValue>) => FieldRenderer<TValue>;
+//#endregion
+//#region src/react/presentation/types.d.ts
+type PresentationWrapperProps = {
+  presentation: FormPresentation;
+  open: boolean;
+  onClose: () => void; /** Accessible name for an overlay surface (e.g. the form title). */
+  title?: string; /** Label for the overlay close control. */
+  closeLabel?: string;
+  children: ReactNode;
+};
+/** A descriptor plus an optional React wrapper. page/inline omit the wrapper; modal/drawer provide one. */
+type FormPresentation = PresentationDescriptor & {
+  Wrapper?: ComponentType<PresentationWrapperProps>;
+};
+//#endregion
+//#region src/react/presentation/registry.d.ts
+type PresentationRegistry = Map<string, FormPresentation>;
+/** `false` removes, `true` keeps the default, a presentation adds or replaces one. */
+type PresentationOption = boolean | FormPresentation;
+type PresentationsConfig = Record<string, PresentationOption>;
+declare const resolvePresentations: (defaults?: Record<string, FormPresentation>, config?: PresentationsConfig) => PresentationRegistry;
+//#endregion
+//#region src/react/registry.d.ts
+type RendererRegistry = Map<string, FieldRenderer>;
+/** Per-type renderer override: `false` removes, `true` keeps the default, a renderer adds or replaces one. */
+type RendererOption = boolean | FieldRenderer;
+type RenderersConfig = Record<string, RendererOption>;
+/**
+ * Resolve the active renderer registry from the defaults and a consumer override map. `false` removes a
+ * type, `true` keeps the default (no-op when none exists), a renderer adds a new type or replaces one.
+ * Mirrors the field-type and validation-rule registry convention.
+ */
+declare const resolveRenderers: (defaults: Record<string, FieldRenderer>, config?: RenderersConfig) => RendererRegistry;
+//#endregion
+//#region src/react/submitForm.d.ts
+type SubmitFormInput = {
+  formId: number | string;
+  values: SubmissionValue[]; /** Payload API route prefix; defaults to `/api`. */
+  apiRoute?: string; /** Injectable for testing; defaults to global `fetch`. */
+  fetchImpl?: typeof fetch;
+};
+type SubmitFormResult = {
+  ok: true;
+  submissionId?: string;
+} | {
+  ok: false;
+  fieldErrors?: Record<string, string[]>;
+  message?: string;
+};
+/**
+ * The default submission transport: POST `{apiRoute}/form-submissions` with `{ form, values }`. On 201
+ * returns the created submission id; on a 400 Payload `ValidationError` maps `data.errors[].path` to
+ * per-field messages; otherwise returns a generic message. Pure: inject `fetchImpl` in tests.
+ */
+declare const submitForm: (input: SubmitFormInput) => Promise<SubmitFormResult>;
+/** A consumer override for the transport: given the form id + values, resolve to a submit result. */
+type SubmitHandler = (input: {
+  formId: number | string;
+  values: SubmissionValue[];
+}) => Promise<SubmitFormResult>;
+//#endregion
+//#region src/react/Form.d.ts
+type FormDocument = {
+  id: number | string;
+  fields: FormFieldInstance[];
+  flow?: FormFlow; /** Stored presentation name; overridden by the `presentation` prop. */
+  defaultPresentation?: string;
+};
+type FormProps = {
+  form: FormDocument;
+  fieldTypes?: AnyFormFieldDefinition[];
+  rules?: AnyValidationRuleDefinition[];
+  renderers?: RenderersConfig;
+  apiRoute?: string;
+  onSubmit?: SubmitHandler;
+  onSuccess?: (submissionId?: string) => void;
+  onError?: (message: string) => void;
+  events?: FormEventSink;
+  t?: RendererTranslate;
+  locale?: string;
+  layout?: boolean;
+  submitLabel?: string;
+  nextLabel?: string;
+  backLabel?: string; /** Label for the overlay close control (modal/drawer). */
+  closeLabel?: string;
+  successMessage?: string; /** Active presentation: a name into the registry or an inline presentation. Overrides the form's stored default. */
+  presentation?: string | FormPresentation; /** Per-render presentation overrides merged onto the defaults (add, replace, or `false` to remove). */
+  presentations?: PresentationsConfig; /** Invoked when an overlay presentation dismisses (close button, Escape, outside click, or `dismissOnSuccess`). */
+  onClose?: () => void; /** Accessible name for an overlay surface. */
+  title?: string; /** Seed initial field values (e.g. from `valuesFromSearchParams`). Still validated on submit. */
+  initialValues?: Record<string, unknown>; /** Honeypot decoy (on by default). `false` removes it; `{ name }` matches a customized server `spam.honeypot.fieldName`. */
+  honeypot?: false | {
+    name?: string;
+  }; /** A token from your captcha widget; verified server-side when a captcha provider is configured. */
+  captchaToken?: string; /** Custom layout: render fields with `useField`/`useFormState` instead of the auto-rendered field loop. */
+  children?: ReactNode;
+};
+/** The headless form controller: state, progressive client validation, conditional visibility, submission, events. */
+declare const Form: ({
+  form,
+  fieldTypes,
+  rules,
+  renderers,
+  apiRoute,
+  onSubmit,
+  onSuccess,
+  onError,
+  events,
+  t,
+  locale,
+  layout,
+  submitLabel,
+  nextLabel,
+  backLabel,
+  closeLabel,
+  successMessage,
+  presentation,
+  presentations,
+  onClose,
+  title,
+  initialValues,
+  honeypot,
+  captchaToken,
+  children
+}: FormProps) => import("react/jsx-runtime").JSX.Element;
+//#endregion
+//#region src/react/state.d.ts
+type FieldErrors = Record<string, string[]>;
+type FormState = {
+  values: Record<string, unknown>;
+  errors: FieldErrors;
+  warnings: FieldErrors;
+  touched: Record<string, boolean>;
+  submitting: boolean;
+  submitted: boolean;
+  submitAttempted: boolean;
+  submitError?: string;
+};
+//#endregion
+//#region src/react/FormContext.d.ts
+/** Multi-step navigation state. Defaults to a single terminal step when the form has no flow. */
+type FormStepInfo = {
+  flow?: FormFlow;
+  currentStepId?: string;
+  stepIndex: number;
+  stepCount: number;
+  isFirst: boolean;
+  isTerminal: boolean;
+  goNext: () => void;
+  goBack: () => void;
+};
+//#endregion
+//#region src/react/FormLayout.d.ts
+type FieldWidth = 'full' | 'half' | 'third' | 'twoThirds';
+type FormLayoutProps = {
+  children: ReactNode; /** When false, render a plain container with no grid class (document-order layout). */
+  enabled?: boolean;
+};
+/** Establishes the layout container. With the stylesheet imported, children with `data-width` flow into a grid. */
+declare const FormLayout: ({
+  children,
+  enabled
+}: FormLayoutProps) => import("react/jsx-runtime").JSX.Element;
+/** Props to spread onto a field wrapper to declare its grid width. */
+declare const widthProps: (width: FieldWidth | undefined) => {
+  'data-width': FieldWidth;
+};
+//#endregion
+//#region src/react/FormResults.d.ts
+type FormResultsProps = {
+  /** One field aggregation or several (a survey summary), resolved server-side and passed in. */results: FieldAggregation | FieldAggregation[]; /** Localized translator for built-in copy. Defaults to identity (returns the key). */
+  t?: RendererTranslate;
+  locale?: string; /** Show the raw count beside each option. Default true. */
+  showCounts?: boolean;
+};
+/**
+ * Presentational results view for polls and survey summaries: per-option bars with percentages. Headless,
+ * data resolved server-side via `aggregateFieldResponses`/`aggregateFormResponses` and passed in (it never
+ * fetches). The option label, count, and percentage are real text (the accessible content); the bar fill
+ * is `aria-hidden` visual sugar sized by inline width.
+ */
+declare const FormResults: ({
+  results,
+  t,
+  showCounts
+}: FormResultsProps) => ReactNode;
+//#endregion
+//#region src/react/fetchResults.d.ts
+type FetchResultsInput = {
+  formId: number | string; /** Restrict to one field. Omit to get every public/enumerable field. */
+  field?: string; /** Payload API route prefix; defaults to `/api`. */
+  apiRoute?: string; /** Injectable for testing; defaults to global `fetch`. */
+  fetchImpl?: typeof fetch;
+};
+type FetchResultsResult = {
+  ok: true;
+  results: FieldAggregation[];
+} | {
+  ok: false;
+  message?: string;
+};
+/**
+ * Fetch aggregate poll/survey results from the form-builder results endpoint
+ * (`GET {apiRoute}/forms/:id/results`). Returns the server-resolved aggregations; the endpoint gates public
+ * access by the form's `showResults` opt-in. Pure: inject `fetchImpl` in tests.
+ */
+declare const fetchFormResults: (input: FetchResultsInput) => Promise<FetchResultsResult>;
+//#endregion
+//#region src/react/Honeypot.d.ts
+type HoneypotProps = {
+  name: string;
+  inputRef?: Ref<HTMLInputElement>;
+};
+/**
+ * A visually hidden honeypot decoy. Real users never see or tab to it; bots that fill every input trip it,
+ * and the server rejects the submission. Off-screen + aria-hidden + tabIndex -1 + autoComplete off.
+ */
+declare const Honeypot: ({
+  name,
+  inputRef
+}: HoneypotProps) => import("react/jsx-runtime").JSX.Element;
+//#endregion
+//#region src/react/Poll.d.ts
+type PollProps = FormProps & {
+  /** The choice field whose results are shown after voting (should match the form's public `resultsField`). */resultsField: string; /** localStorage key for the per-browser voted guard. Default `fb-poll-{form.id}`. */
+  storageKey?: string; /** Force the voted state (controlled). Omit to use the localStorage guard. */
+  hasVoted?: boolean;
+  /**
+   * Injectable results fetch (testing); defaults to `fetchFormResults`. Pass a stable reference (module
+   * scope, `useCallback`, or `useMemo`): an inline function re-runs the load effect and double-fetches.
+   */
+  fetchResultsImpl?: typeof fetchFormResults;
+};
+/**
+ * A poll: renders `<Form>` until the visitor votes, then fetches the aggregate results and shows
+ * `<FormResults>`. A per-browser localStorage flag (`storageKey`) skips straight to results on revisit. The
+ * guard is UX, not integrity (bypassable): server-enforced one-per-identity dedup composes via `req.user`
+ * (authed forms) or a `notAlreadySubmitted` rule, with cookie/IP identity deferred to the spam phase.
+ */
+declare const Poll: ({
+  resultsField,
+  storageKey,
+  hasVoted,
+  fetchResultsImpl,
+  apiRoute,
+  onSuccess,
+  ...formProps
+}: PollProps) => import("react/jsx-runtime").JSX.Element | null;
+//#endregion
+//#region src/react/presentation/Backdrop.d.ts
+type BackdropProps = {
+  onClick?: () => void;
+  className?: string;
+};
+/** A full-viewport backdrop behind an overlay surface. Styling comes from the `data-fb-backdrop` hook. */
+declare const Backdrop: ({
+  onClick,
+  className
+}: BackdropProps) => import("react").DetailedReactHTMLElement<{
+  'data-fb-backdrop': string;
+  className: string | undefined;
+  onClick: (() => void) | undefined;
+  'aria-hidden': true;
+}, HTMLElement>;
+//#endregion
+//#region src/react/presentation/DialogSurface.d.ts
+type DialogSurfaceProps = {
+  open: boolean;
+  onClose: () => void; /** Accessible name; pass either label or labelledBy. */
+  label?: string;
+  labelledBy?: string; /** CSS data hook, e.g. 'modal' | 'drawer'. */
+  surface?: string;
+  closeLabel?: string;
+  closeOnEscape?: boolean;
+  closeOnOutsideClick?: boolean;
+  children?: ReactNode;
+};
+/**
+ * Accessible, dependency-free overlay surface: backdrop + role=dialog/aria-modal, focus-trap,
+ * scroll-lock, Escape/outside-click dismiss, initial focus, and focus restore on close. Composes the
+ * exported primitives so a consumer can rebuild it from the same parts.
+ */
+declare const DialogSurface: ({
+  open,
+  onClose,
+  label,
+  labelledBy,
+  surface,
+  closeLabel,
+  closeOnEscape,
+  closeOnOutsideClick,
+  children
+}: DialogSurfaceProps) => import("react").ReactElement<{
+  'data-fb-overlay': string;
+}, string | import("react").JSXElementConstructor<any>> | null;
+//#endregion
+//#region src/react/presentation/presentations.d.ts
+declare const defaultPresentations: Record<string, FormPresentation>;
+//#endregion
+//#region src/react/presentation/useDismiss.d.ts
+type UseDismissOptions = {
+  active: boolean;
+  onDismiss: () => void;
+  closeOnEscape?: boolean;
+  closeOnOutsideClick?: boolean;
+};
+/** Dismiss-on-Escape and dismiss-on-outside-pointerdown for an overlay surface. */
+declare const useDismiss: ({
+  active,
+  onDismiss,
+  closeOnEscape,
+  closeOnOutsideClick
+}: UseDismissOptions, ref: RefObject<HTMLElement | null>) => void;
+//#endregion
+//#region src/react/presentation/useFocusTrap.d.ts
+/** Trap Tab focus within the container while active. */
+declare const useFocusTrap: (ref: RefObject<HTMLElement | null>, active: boolean) => void;
+//#endregion
+//#region src/react/presentation/useScrollLock.d.ts
+/** Lock body scroll while active; restores the prior value on cleanup. */
+declare const useScrollLock: (active: boolean) => void;
+//#endregion
+//#region src/react/primitives/Checkbox.d.ts
+type CheckboxProps = {
+  id: string;
+  name: string;
+  checked: boolean;
+  onChange: (checked: boolean) => void;
+  onBlur?: () => void;
+  required?: boolean;
+  disabled?: boolean;
+  invalid?: boolean;
+  describedById?: string;
+};
+declare const Checkbox: ({
+  id,
+  name,
+  checked,
+  onChange,
+  onBlur,
+  required,
+  disabled,
+  invalid,
+  describedById
+}: CheckboxProps) => import("react/jsx-runtime").JSX.Element;
+//#endregion
+//#region src/react/primitives/FieldShell.d.ts
+type FieldShellProps = {
+  /** The control id this shell labels and describes. */id: string;
+  label?: string;
+  description?: string;
+  required?: boolean;
+  errors?: string[];
+  warnings?: string[]; /** id used for aria-describedby on the control; the shell renders description + messages under it. */
+  describedById: string;
+  children: ReactNode;
+};
+/**
+ * Accessible wrapper for a single field: a `<label>` bound to the control, the control slot, an optional
+ * description, and error/warning messages. The control inside must set `aria-describedby={describedById}`
+ * and `aria-invalid` when errors exist; this shell renders the matching `id={describedById}` region.
+ */
+declare const FieldShell: ({
+  id,
+  label,
+  description,
+  required,
+  errors,
+  warnings,
+  describedById,
+  children
+}: FieldShellProps) => import("react/jsx-runtime").JSX.Element;
+//#endregion
+//#region src/react/primitives/Input.d.ts
+type InputProps = {
+  id: string;
+  name: string;
+  type?: 'text' | 'email' | 'number';
+  value: string;
+  onChange: (value: string) => void;
+  onBlur?: () => void;
+  placeholder?: string;
+  required?: boolean;
+  disabled?: boolean;
+  invalid?: boolean;
+  describedById?: string;
+};
+declare const Input: ({
+  id,
+  name,
+  type,
+  value,
+  onChange,
+  onBlur,
+  placeholder,
+  required,
+  disabled,
+  invalid,
+  describedById
+}: InputProps) => import("react/jsx-runtime").JSX.Element;
+//#endregion
+//#region src/react/primitives/Select.d.ts
+type SelectOption = {
+  label: string;
+  value: string;
+};
+type SelectProps = {
+  id: string;
+  name: string;
+  value: string;
+  options: SelectOption[];
+  onChange: (value: string) => void;
+  onBlur?: () => void;
+  required?: boolean;
+  disabled?: boolean;
+  invalid?: boolean;
+  describedById?: string;
+  placeholder?: string;
+};
+declare const Select: ({
+  id,
+  name,
+  value,
+  options,
+  onChange,
+  onBlur,
+  required,
+  disabled,
+  invalid,
+  describedById,
+  placeholder
+}: SelectProps) => import("react/jsx-runtime").JSX.Element;
+//#endregion
+//#region src/react/primitives/Textarea.d.ts
+type TextareaProps = {
+  id: string;
+  name: string;
+  value: string;
+  onChange: (value: string) => void;
+  onBlur?: () => void;
+  placeholder?: string;
+  required?: boolean;
+  disabled?: boolean;
+  invalid?: boolean;
+  describedById?: string;
+};
+declare const Textarea: ({
+  id,
+  name,
+  value,
+  onChange,
+  onBlur,
+  placeholder,
+  required,
+  disabled,
+  invalid,
+  describedById
+}: TextareaProps) => import("react/jsx-runtime").JSX.Element;
+//#endregion
+//#region src/react/renderers/index.d.ts
+/** The built-in field renderers, keyed by field-type slug. Override via the renderer registry. */
+declare const defaultRenderers: Record<string, FieldRenderer>;
+//#endregion
+//#region src/react/uploadFile.d.ts
+type UploadFileInput = {
+  file: File; /** Upload collection slug. Defaults to `form-uploads`. */
+  collection?: string;
+  apiRoute?: string;
+  fetchImpl?: typeof fetch;
+};
+type UploadFileResult = {
+  ok: true;
+  id: string | number;
+} | {
+  ok: false;
+  message?: string;
+};
+/**
+ * Upload one file to a Payload upload collection (`POST {apiRoute}/{collection}`, multipart) and return its
+ * id, which the file field stores as its value. The server re-derives the file metadata from the stored doc
+ * at submit, so the client is never trusted for it. Pure: inject `fetchImpl` in tests.
+ */
+declare const uploadFile: (input: UploadFileInput) => Promise<UploadFileResult>;
+//#endregion
+//#region src/react/useField.d.ts
+type UseFieldResult<TValue = unknown> = {
+  value: TValue | undefined;
+  errors: string[];
+  warnings: string[];
+  touched: boolean;
+  setValue: (value: TValue) => void; /** Mark touched and validate now (call on blur). */
+  onBlur: () => void;
+};
+/** Bind one field by name to the form controller: its value, issues, and change/blur handlers. */
+declare const useField: <TValue = unknown>(name: string) => UseFieldResult<TValue>;
+//#endregion
+//#region src/react/useFormState.d.ts
+/** The whole form state (values, errors, warnings, touched, submitting, submitted, submitError). */
+declare const useFormState: () => FormState;
+//#endregion
+//#region src/react/useFormStep.d.ts
+/** Multi-step navigation state for the current form (single-step default when the form has no flow). */
+declare const useFormStep: () => FormStepInfo;
+//#endregion
+export { type AggregationBucket, Backdrop, type BackdropProps, CAPTCHA_TOKEN_KEY, type CalcExpression, Checkbox, type CheckboxProps, DEFAULT_HONEYPOT_FIELD, DialogSurface, type DialogSurfaceProps, type FetchResultsInput, type FetchResultsResult, type FieldAggregation, type FieldRenderer, type FieldRendererProps, FieldShell, type FieldShellProps, type FieldWidth, Form, type FormDocument, FormLayout, type FormLayoutProps, type FormPresentation, type FormProps, FormResults, type FormResultsProps, type FormState, type FormStepInfo, Honeypot, type HoneypotProps, Input, type InputProps, Poll, type PollProps, type PrefillOptions, type PresentationOption, type PresentationRegistry, type PresentationWrapperProps, type PresentationsConfig, type RecallResolver, type RendererOption, type RendererRegistry, type RendererTranslate, type RenderersConfig, Select, type SelectOption, type SelectProps, type SubmitFormResult, type SubmitHandler, Textarea, type TextareaProps, type UploadFileInput, type UploadFileResult, type UseDismissOptions, type UseFieldResult, buildRecallResolver, computeCalcFields, defaultPresentations, defaultRenderers, defineFieldRenderer, evaluateCalc, evaluateCondition, fetchFormResults, firstStepId, interpolate, isTerminalStepId, resolveNextStepId, resolvePresentations, resolveRenderers, stepFieldNames, submitForm, uploadFile, useDismiss, useField, useFocusTrap, useFormState, useFormStep, useScrollLock, valuesFromSearchParams, widthProps };
+//# sourceMappingURL=react.d.ts.map