@nextlyhq/plugin-form-builder 0.0.2-alpha.74 → 0.0.2-alpha.76

package/README.md

@@ -66,7 +66,8 @@ import "@nextlyhq/plugin-form-builder/admin";
 - **Admin routes:** `/admin/collections/forms` and `/admin/collections/form-submissions`
 - **Collections:** `forms`, `form-submissions`
 - **Form lifecycle states:** Draft, Published, Closed
-- **Optional integrations:** email notifications, a `form.submission.created` webhook through Nextly's own webhooks, spam protection (honeypot, rate limit, reCAPTCHA v3)
+- **One response per person:** by email address, browser or network address, refused atomically by a keyed digest (the browser mode needs your form's script to send a token; see the docs)
+- **Optional integrations:** email notifications, a `form.submission.created` webhook through Nextly's own webhooks, spam protection (honeypot, rate limit, and a reCAPTCHA v3 or Cloudflare Turnstile bot check verified on the server)
 
 ### Submission privacy
 

package/dist/admin/index.d.ts

@@ -1,7 +1,7 @@
-import { O as FormSettings, S as FormFieldTypeId, T as FormNotification, b as FormField, i as AnyFormField, r as NewSubmissionsData } from "../new-submissions-CzlhVGhH.js";
-import { ComponentPath, DocumentLockGates } from "@nextlyhq/plugin-sdk/admin";
+import { D as FormSettings, Z as NewSubmissionsData, t as AnyFormField, w as FormNotification, x as FormFieldTypeId } from "../types-XdBrUfi1.js";
+import { ComponentPath, DocumentLockGates, FieldPickerChoice } from "@nextlyhq/plugin-sdk/admin";
 import React, { JSX, ReactNode } from "react";
-import { FieldTypeCatalogEntry, FormFieldCatalogType } from "nextly/field-catalog";
+import { FormFieldCatalogType } from "nextly/field-catalog";
 interface FormBuilderViewProps {
   id?: string;
   entryId?: string;
@@ -14,6 +14,8 @@ interface FormBuilderViewProps {
     slug?: string;
     description?: string;
     status?: "draft" | "published" | "closed";
+    /** When the form first went live: what fixes its ID. */
+    wentLiveAt?: string | null;
     closedMessage?: string;
     fields?: unknown[];
     settings?: Record<string, unknown>;
@@ -24,8 +26,15 @@ interface FormBuilderViewProps {
      */
     _rev?: string;
   };
-  onSave?: (data: unknown) => void;
+  /**
+   * Saves the form in the host's own way, in place of the builder's request.
+   * The builder counts the form saved once this returns, or once the promise
+   * it may return settles without failing.
+   */
+  onSave?: (data: unknown) => void | Promise<void>;
   onSuccess?: (entry?: Record<string, unknown>) => void;
+  /** Called once the form has been deleted from the editor's More menu. */
+  onDelete?: () => void;
   onCancel?: () => void;
   /**
    * What a colleague's claim on this form withholds, handed over by the admin
@@ -37,8 +46,20 @@ interface FormBuilderViewProps {
    * it too.
    */
   documentLock?: DocumentLockGates;
+  /**
+   * The page of the editor the address names (`"settings"` at
+   * `/admin/collections/forms/<id>/settings`); absent on the form's edit
+   * address, which opens Builder.
+   */
+  view?: string;
 }
-export declare function FormBuilderView({ id, entryId, collection, collectionSlug, isCreating, initialData, onSave, onSuccess, onCancel, documentLock }: FormBuilderViewProps): JSX.Element;
+export declare function FormBuilderView({ id, entryId, collection, collectionSlug, isCreating, initialData, onSave, onSuccess, onDelete, documentLock, view }: FormBuilderViewProps): JSX.Element;
+/**
+ * A submission as the entries API answers it, and the readings of it the
+ * list and a submission's page share, so the two cannot read it differently.
+ *
+ * @module admin/components/submissions/submission-row
+ */
 interface SubmissionRow {
   id: string;
   form: string | {
@@ -47,46 +68,64 @@ interface SubmissionRow {
   };
   data: Record<string, unknown>;
   status: string;
+  /** Who sent it, as the write seam named it (`utils/submission-title`). */
+  title?: string | null;
   spamReason?: string | null;
   notes?: string | null;
   ipAddress?: string | null;
   userAgent?: string | null;
+  /** The page it was sent from: origin and path. */
+  page?: string | null;
   submittedAt?: string | null;
+  createdAt?: string | null;
   editedAt?: string | null;
   editedBy?: string | null;
-  /** The submission's version as the list read it; see `submissionPatch`. */
+  /** What it was asked, as the write seam stored it. */
+  asked?: unknown;
+  /** Its version as read, sent back with a change. */
   _rev?: string;
 }
-interface FormOption {
-  id: string;
-  name: string;
-  fields: FormField[];
-}
 interface SubmissionsViewProps {
   collectionSlug?: string;
+  /**
+   * Show only this form's submissions, with no choice of form: the list as a
+   * form's own Submissions tab draws it.
+   */
+  formId?: string;
 }
-export declare function SubmissionsView({ collectionSlug }: SubmissionsViewProps): JSX.Element;
-interface SubmissionSheetProps {
-  submission: SubmissionRow;
-  form: FormOption;
-  canUpdate: boolean;
-  onClose: () => void;
-  onPrev?: () => void;
-  onNext?: () => void;
-  onSave: (changes: Record<string, unknown>) => Promise<void>;
+export declare function SubmissionsView({ collectionSlug, formId }: SubmissionsViewProps): JSX.Element;
+/** A submission as the entries API answers it. */
+type SubmissionDocument = SubmissionRow;
+interface SubmissionPageProps {
+  entryId?: string;
+  collectionSlug?: string;
+  initialData?: Partial<SubmissionDocument>;
+  /**
+   * What a colleague's claim on this submission withholds, as the entry page
+   * hands it over. While either is set the page offers no change and sends
+   * none, the automatic Read among them.
+   */
+  documentLock?: DocumentLockGates;
+  /**
+   * Tells the entry page the submission was deleted: it stands its leave
+   * guard down and returns to the list. Used when unsaved work is on the
+   * page; otherwise the page moves to the next submission itself.
+   */
+  onDelete?: () => void;
 }
-export declare function SubmissionSheet({ submission, form, canUpdate, onClose, onPrev, onNext, onSave }: SubmissionSheetProps): JSX.Element;
-/** The card's rows, as many as its size holds. */
-export declare function NewSubmissionsCard({ data }: {
+export declare function SubmissionPage({ entryId, collectionSlug, initialData, documentLock, onDelete }: SubmissionPageProps): JSX.Element;
+/** The card's rows: its reader's "Number of entries", the rows its `load` read. */
+export declare function NewSubmissionsCard({ data, settings }: {
   data: NewSubmissionsData;
+  /** The card's settings as its `load` read them; `limit` is its "Number of entries". */
+  settings?: Record<string, unknown>;
 }): JSX.Element;
 interface FieldCardsProps {
   /**
    * Form-surface types the host has NOT excluded (the plugin's field
    * enable/disable option). `null` while the host configuration is still
-   * loading — the Add dialog waits rather than flashing the unfiltered set.
-   * Types outside this set stay renderable on existing fields but cannot be
-   * added.
+   * loading: Add field waits rather than offering the unfiltered set. Types
+   * outside this set stay editable on existing fields but cannot be added.
    */
   enabledTypes: readonly FormFieldCatalogType[] | null;
   /**
@@ -95,52 +134,23 @@ interface FieldCardsProps {
    * contributed types.
    */
   disabledFieldTypes?: ReadonlySet<string>;
-  /** Creates a field of the given type and returns it (context helper). */
-  onAddField: (type: FormFieldTypeId) => void;
-}
-export declare function FieldCards({ enabledTypes, disabledFieldTypes, onAddField }: FieldCardsProps): JSX.Element;
-interface AddFieldDialogProps {
-  open: boolean;
-  onOpenChange: (open: boolean) => void;
   /**
-   * The form surface's catalog — built-ins already filtered by the host's
-   * excludes plus any plugin field types that opted into the forms surface;
-   * `null` while the host configuration is still loading. `type` is the open
-   * `FormFieldTypeId` so a plugin entry shares this shape with the built-ins.
+   * Creates and selects a field of the chosen type. The picker's whole choice
+   * comes second (the label the person typed and the name it gives), so a host
+   * written for the type alone keeps working and one that wants the label
+   * reads it there. The third is where in the list it goes, when it was added
+   * between two rows or below one; absent for the end.
    */
-  entries: readonly FieldTypeCatalogEntry<FormFieldTypeId>[] | null;
-  /** Called with the chosen type; the parent creates and selects the field. */
-  onAdd: (type: FormFieldTypeId) => void;
-}
-export declare function AddFieldDialog({ open, onOpenChange, entries, onAdd }: AddFieldDialogProps): JSX.Element;
-interface FieldEditorProps {
-  /** The field being edited (built-in or plugin-contributed). */
-  field: AnyFormField;
-  /** All fields in the form (for conditional logic references) */
-  allFields: AnyFormField[];
-  /** Callback when field is updated */
-  onUpdate: (updates: Partial<AnyFormField>) => void;
+  onAddField: (type: FormFieldTypeId, choice?: FieldPickerChoice, index?: number) => void;
+  /**
+   * Where the selected field's settings dock from 1024px: `"beside"` the list
+   * (the default, for a list drawn on its own), or by the `"host"` page,
+   * which draws `FieldInspector` against the window's edge itself. Below
+   * 1024px they open under the row either way.
+   */
+  dockedSettings?: "beside" | "host";
 }
-/**
- * FieldEditor - Field properties configuration panel
- *
- * Provides a tabbed interface for editing field properties:
- * - General: name, label, placeholder, help text, required, width, type-specific options
- * - Validation: error messages, min/max length, patterns, etc.
- * - Conditional: show/hide logic based on other field values
- *
- * @example
- * ```tsx
- * <FieldEditor
- *   field={selectedField}
- *   allFields={allFields}
- *   onUpdate={handleUpdate}
- *   onDelete={handleDelete}
- *   onDuplicate={handleDuplicate}
- * />
- * ```
- */
-export declare function FieldEditor({ field, allFields, onUpdate }: FieldEditorProps): JSX.Element;
+export declare function FieldCards({ enabledTypes, disabledFieldTypes, onAddField, dockedSettings }: FieldCardsProps): JSX.Element;
 interface FormPreviewProps {
   /** Array of form fields to preview (built-in or plugin-contributed). */
   fields: AnyFormField[];
@@ -152,12 +162,23 @@ interface FormPreviewProps {
   };
 }
 export declare function FormPreview({ fields, formData }: FormPreviewProps): JSX.Element;
+/**
+ * Generate a readable unique field name: the type itself for the first
+ * field of that type, then a numeric suffix (`email`, `email_2`, ...).
+ * Names key submission data, so they should read like keys a developer
+ * would have chosen, not timestamps.
+ */
+export declare function generateFieldName(type: FormFieldTypeId, existingNames?: readonly string[]): string;
 interface FormBuilderState {
   /** Form fields array */
   fields: AnyFormField[];
   /** Currently selected field ID (name) */
   selectedFieldId: string | null;
-  /** Active tab: builder, preview, settings, or notifications */
+  /**
+   * Active tab: builder, preview, settings, or notifications.
+   * @deprecated The editor shows the page its address names; this is no
+   * longer what it shows, and is kept for hosts that read it.
+   */
   activeTab: "builder" | "preview" | "settings" | "notifications";
   /** Whether form has unsaved changes */
   isDirty: boolean;
@@ -191,7 +212,10 @@ interface FormBuilderActions {
   duplicateField: (fieldName: string) => void;
   /** Select a field */
   selectField: (fieldName: string | null) => void;
-  /** Set active tab */
+  /**
+   * Set active tab.
+   * @deprecated The editor's tabs are links to each page's address.
+   */
   setActiveTab: (tab: "builder" | "preview" | "settings" | "notifications") => void;
   /** Update form metadata */
   updateFormData: (updates: Partial<FormBuilderState["formData"]>) => void;
@@ -219,6 +243,8 @@ interface FormBuilderProviderProps {
     slug?: string;
     description?: string;
     status?: "draft" | "published" | "closed";
+    /** When the form first went live, as the server stamped it. */
+    wentLiveAt?: string | null;
     closedMessage?: string;
     fields?: AnyFormField[];
     settings?: Partial<FormSettings>;
@@ -241,14 +267,7 @@ interface FormBuilderProviderProps {
 /** Default form settings (the canonical defaults from the settings reader) */
 export declare const DEFAULT_SETTINGS: FormSettings;
 /** Create a new notification rule with default values */
-export declare function createNotification(): FormNotification;
-/**
- * Generate a readable unique field name: the type itself for the first
- * field of that type, then a numeric suffix (`email`, `email_2`, ...).
- * Names key submission data, so they should read like keys a developer
- * would have chosen, not timestamps.
- */
-export declare function generateFieldName(type: FormFieldTypeId, existingNames?: readonly string[]): string;
+export declare function createNotification(kind?: "team" | "visitor", fields?: readonly AnyFormField[]): FormNotification;
 /**
  * Generate a human-readable label from field type, using the shared catalog
  * so a new field's default label matches what the picker called the type. A
@@ -310,7 +329,22 @@ export declare function useFormBuilder(): FormBuilderContextValue;
  * @returns Form builder context value or null
  */
 export declare function useOptionalFormBuilder(): FormBuilderContextValue | null;
-interface SpamDefaults {
+type BotProvider = "recaptcha" | "turnstile";
+/** What the plugin's options say about bot checks and the rate limit. */
+interface BotCheckSiteDefaults {
+  /** The provider "Site default" resolves to, or null for none. */
+  botCheckDefault?: BotProvider | null;
+  /** Which providers have their keys set. */
+  botChecks?: Record<BotProvider, {
+    secret: boolean;
+    siteKey: boolean;
+  }>;
+  rateLimit?: {
+    maxSubmissions: number;
+    windowMs: number;
+  } | null;
+}
+interface SpamDefaults extends BotCheckSiteDefaults {
   honeypot?: boolean;
   recaptchaEnabled?: boolean;
 }
@@ -340,16 +374,12 @@ interface FormNotificationsTabProps {
   /** `null` while the builder-config request is still settling. */
   defaults: NotificationDefaults | null;
 }
-/**
- * FormNotificationsTab - the form's notification rules.
- *
- * Each rule references an existing email provider and template rather than
- * duplicating provider credentials or embedding a second template editor.
- */
 export declare function FormNotificationsTab({ defaults }: FormNotificationsTabProps): JSX.Element;
 /** Component path for FormBuilderView */
 export declare const FORM_BUILDER_VIEW_PATH: ComponentPath;
 /** Component path for SubmissionsView */
 export declare const SUBMISSIONS_VIEW_PATH: ComponentPath;
-export type { AddFieldDialogProps, FieldCardsProps, FieldEditorProps, FormBuilderActions, FormBuilderContextValue, FormBuilderProviderProps, FormBuilderState, FormBuilderViewProps, FormNotification, FormPreviewProps, FormSettings };
+/** Component path for SubmissionPage, a submission's own page */
+export declare const SUBMISSION_PAGE_PATH: ComponentPath;
+export type { FieldCardsProps, FormBuilderActions, FormBuilderContextValue, FormBuilderProviderProps, FormBuilderState, FormBuilderViewProps, FormNotification, FormPreviewProps, FormSettings, SubmissionPageProps };
 //# sourceMappingURL=index.d.ts.map