@usefillo/react 0.3.2 → 0.5.0

package/README.md

@@ -11,13 +11,11 @@ npm i @usefillo/react
 `react` and `react-dom` (18 or 19) are peer dependencies.
 
 ```tsx
-import { FilloForm, createClient } from "@usefillo/react";
+import { FilloForm } from "@usefillo/react";
 import "@usefillo/react/styles.css"; // optional default theme — or bring your own
 
-const client = createClient({ key: "pk_live_…" });
-
 export function Feedback() {
-  return <FilloForm client={client} formId="cust-feedback" onSubmitted={(r) => confetti()} />;
+  return <FilloForm formId="cust-feedback" onSubmitted={(r) => confetti()} />;
 }
 ```
 
@@ -29,6 +27,12 @@ Every part is replaceable. Pass your own field components, theme the form via th
 - `FormField` / `BlockRenderer` — render individual blocks
 - `defineForm()` — author a form in code and sync it to your workspace on first run
 
+Published `formId` embeds can fetch and submit without a publishable key. Use `createClient({ key })` when syncing `defineForm()` schemas from code, or when you need to point the SDK at a custom API origin.
+
+For tiny feedback widgets, set `settings.submitMode: "auto"` on a select/rating/checkbox/dropdown/linear scale form. The default renderer hides the first submit button, submits after a complete discrete answer, and brings the submit button back if that answer opens a text or upload follow-up. Add `submissionLimit: "once_per_visitor"` for browser-scoped one-response feedback.
+
+The default stylesheet follows system dark mode for unthemed embeds. Pass `theme={{ colorScheme: "dark" }}` or `"light"` when the host surface is known.
+
 This package re-exports the embedding surface from [`@usefillo/core`](https://www.npmjs.com/package/@usefillo/core) (`createClient`, `FormSchema`, `FormTheme`, …) so a single import is usually enough.
 
 ## Links

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
-import { FormSchema, FilloClient, ResponseData, FieldValue, FormPage, Block, FormStatus, FieldKind, Field, CodeForm, FormTheme, FilloError } from '@usefillo/core';
+import { FormSchema, FilloClient, ResponseData, FieldValue, FormPage, Block, FormStatus, FieldKind, Field, FormTheme, FilloError, CodeForm } from '@usefillo/core';
 export { CodeForm, Field, FieldValue, FileValue, FilloClient, FilloError, FormSchema, FormStatus, FormTheme, ProvisionWorkspaceResult, PublishedForm, ResponseData, createClient, defineForm, provisionWorkspace } from '@usefillo/core';
 
 /**
@@ -30,12 +30,22 @@ interface FilloApi {
     /** Used by upload fields to gate submission. */
     setUploading: (fieldId: string, busy: boolean) => void;
 }
-interface FieldComponentProps {
-    field: Field;
+interface FilloFieldIds {
+    inputId: string;
+    labelId: string;
+    descriptionId: string;
+    errorId: string;
+    name: string;
+}
+interface FieldComponentProps<F extends Field = Field> {
+    /** Narrow with the type param to skip a cast, e.g.
+     *  `FieldComponentProps<CustomField>` to read `field.config` directly. */
+    field: F;
     value: FieldValue;
     error: string | undefined;
     setValue: (value: FieldValue) => void;
     api: FilloApi;
+    ids?: FilloFieldIds;
 }
 /** Per-kind component overrides — swap any built-in field for your own. */
 type FieldComponents = Partial<Record<FieldKind, ComponentType<FieldComponentProps>>>;
@@ -46,12 +56,7 @@ type FieldComponents = Partial<Record<FieldKind, ComponentType<FieldComponentPro
  */
 type CustomComponents = Record<string, ComponentType<FieldComponentProps>>;
 
-interface FilloFormProps {
-    /** Render a schema directly, or a code-defined form from defineForm(). */
-    form?: FormSchema | CodeForm;
-    /** Or fetch it: a client plus the form id/slug. */
-    client?: FilloClient;
-    formId?: string;
+interface FilloFormBaseProps {
     theme?: FormTheme;
     /** Swap any built-in field kind for your own component. */
     components?: FieldComponents;
@@ -72,17 +77,34 @@ interface FilloFormProps {
     renderSuccess?: () => ReactNode;
     /** Custom error screen — receives the failure (e.g. 404 vs network). */
     renderError?: (error: FilloError) => ReactNode;
-    /** Let "Next" move between pages without validating — for builder previews. */
-    skipValidation?: boolean;
     /**
-     * Show the "Powered by Fillo" badge. Normally resolved from the workspace
-     * plan by the server; set explicitly only by Fillo's own hosted pages.
-     * Removing the badge on a free workspace violates the Fillo terms. Builder
-     * previews (`skipValidation`) never show it.
+     * @internal Builder/test preview: let "Next" move between pages without
+     * client-side validation. Submission and branding are still authoritative.
      */
-    poweredBy?: boolean;
+    skipValidation?: boolean;
     className?: string;
 }
+type HostedFormProps = FilloFormBaseProps & {
+    /** Fetch a published form by id/slug. A default Fillo client is created if omitted. */
+    formId: string;
+    form?: undefined;
+    client?: FilloClient;
+};
+type CodeBackedFormProps = FilloFormBaseProps & {
+    /** Render a schema directly, or a code-defined form from defineForm(). */
+    form: FormSchema | CodeForm;
+    /** Required for code-defined forms that should save responses in Fillo. */
+    client: FilloClient;
+    formId?: string;
+};
+type PreviewFormProps = FilloFormBaseProps & {
+    /** Builder/test preview: render locally and complete locally. */
+    form: FormSchema | CodeForm;
+    client?: FilloClient;
+    formId?: string;
+    skipValidation: true;
+};
+type FilloFormProps = HostedFormProps | CodeBackedFormProps | PreviewFormProps;
 declare function FilloForm(props: FilloFormProps): react.JSX.Element;
 
 interface ControllerOptions {
@@ -94,7 +116,7 @@ interface ControllerOptions {
     onSubmitted?: (responseId: string | undefined, data: ResponseData) => void;
     /** Anti-spam signals provided by the renderer (honeypot value). */
     getHoneypot?: () => string;
-    /** Let "next" move between pages without validating — for previews/builders. */
+    /** @internal Preview-only page navigation escape hatch. Submission still validates. */
     skipValidation?: boolean;
     /** Embedding surface; "headless" (FilloProvider) is server-enforced as paid. */
     surface?: "default" | "headless";
@@ -154,12 +176,18 @@ interface FieldHandle {
  */
 declare function useField(fieldId: string): FieldHandle;
 
-declare function BlockRenderer({ block, api, components, customComponents, }: {
+interface BlockRendererProps {
     block: Block;
     api: FilloApi;
     components?: FieldComponents;
     customComponents?: CustomComponents;
-}): react.JSX.Element | null;
+}
+declare function BlockRendererInner({ block, api, components, customComponents }: BlockRendererProps): react.JSX.Element | null;
+/**
+ * Memoized so a keystroke in one field doesn't re-render every other field —
+ * see blockPropsEqual for exactly what a block is allowed to depend on.
+ */
+declare const BlockRenderer: react.MemoExoticComponent<typeof BlockRendererInner>;
 /**
  * Render a single field by id using the default (or overridden) component —
  * drop it anywhere inside a <FilloProvider> to place fields in your own
@@ -176,6 +204,6 @@ declare function FormField({ id, components, customComponents, }: {
  * progress, multiple files. Replace it entirely via the `components` prop if
  * you want your own — completed uploads are just FileValue[] in the data.
  */
-declare function FileUploadField({ field, value, error, setValue, api }: FieldComponentProps): react.JSX.Element;
+declare function FileUploadField({ field, value, error, setValue, api, ids: providedIds }: FieldComponentProps): react.JSX.Element;
 
-export { BlockRenderer, type ControllerOptions, type CustomComponents, type FieldComponentProps, type FieldComponents, type FieldHandle, type FilloApi, FileUploadField as FilloFileUpload, FilloForm, type FilloFormProps, FilloProvider, type FilloProviderProps, FormField, useField, useFillo, useFilloController };
+export { BlockRenderer, type ControllerOptions, type CustomComponents, type FieldComponentProps, type FieldComponents, type FieldHandle, type FilloApi, type FilloFieldIds, FileUploadField as FilloFileUpload, FilloForm, type FilloFormProps, FilloProvider, type FilloProviderProps, FormField, useField, useFillo, useFilloController };