@sevenfold/setto-client 0.6.1 → 0.7.0

package/dist/modules/forms/fields.d.ts

@@ -0,0 +1,112 @@
+import type { i18n as I18nType, TFunction } from 'i18next';
+/**
+ * What a form is made of, and where that lives.
+ *
+ * A form's fields are content, not code. They sit in the locale bundle under
+ * `form.<formId>.fields.<n>` as an ordinary Setto list — the same shape a
+ * repeater uses — so the editor can add, remove, reorder and relabel them
+ * with the draft store it already has, and publishing writes them to
+ * `no.json` through the path that already exists. Nothing new has to be
+ * stored, fetched or deployed for a form to change.
+ *
+ *   "form": {
+ *     "kontakt": {
+ *       "submit": "Send", "success": "Takk! …", "error": "Noe gikk galt.",
+ *       "fields": {
+ *         "1": { "name": "navn", "type": "text", "label": "Navn", "required": "true" },
+ *         "2": { "name": "epost", "type": "email", "label": "E-post", "required": "true" },
+ *         "3": { "name": "tjeneste", "type": "select", "label": "Hva gjelder det?",
+ *                "options": "Tak\nVindu\nAnnet" },
+ *         "4": { "name": "melding", "type": "textarea", "label": "Melding" }
+ *       }
+ *     }
+ *   }
+ *
+ * Every value is a string because every locale value is: `required` is
+ * `"true"`, `options` is one per line. `label`, `placeholder` and `options`
+ * are per language; `name`, `type` and `required` are the same in all of them.
+ */
+export declare const FORM_FIELD_TYPES: readonly ["text", "email", "tel", "number", "url", "date", "textarea", "select", "radio", "checkbox", "checkboxes"];
+export type FormFieldType = (typeof FORM_FIELD_TYPES)[number];
+/** What the editor calls each type. */
+export declare const FORM_FIELD_TYPE_LABELS: Record<FormFieldType, string>;
+/** Field props that are the same in every language. */
+export declare const STRUCTURAL_FIELD_PROPS: readonly ["name", "type", "required"];
+export declare function isFormFieldType(value: unknown): value is FormFieldType;
+export declare function fieldTypeHasOptions(type: FormFieldType): boolean;
+export declare function fieldTypeHasPlaceholder(type: FormFieldType): boolean;
+/** A field as the form renders it, whichever source it came from. */
+export interface ResolvedFormField {
+    /** Item key under `form.<id>.fields` — absent when the field came from props. */
+    itemKey?: string;
+    name: string;
+    type: FormFieldType;
+    /** i18n key the label is rendered (and inline-edited) through. */
+    labelKey: string;
+    label: string;
+    placeholder: string;
+    required: boolean;
+    options: string[];
+}
+export declare function formFieldsPrefix(formId: string): string;
+export declare function parseOptions(value: string | undefined): string[];
+/**
+ * Fields as the locale bundle defines them, or null when no loaded language
+ * has a `fields` list for this form and it should fall back to whatever the
+ * host passed. The current language is read first, then i18next's fallback
+ * chain, so a second language that has not translated the form still gets
+ * its structure. Items without a name are skipped: they are the empty husks a
+ * half-finished edit can leave behind, not fields.
+ */
+export declare function readLocaleFields(i18n: I18nType, lng: string, formId: string, ns?: string): ResolvedFormField[] | null;
+/** The host-supplied shape a form can still be given as a prop. */
+export interface FormFieldProp {
+    /** Submitted form field name. */
+    name: string;
+    type: FormFieldType;
+    required?: boolean;
+    /** i18n key for the field label. */
+    labelKey: string;
+    /** i18n key for the placeholder text. */
+    placeholderKey?: string;
+    /** i18n key for the options of a select/radio/checkboxes field, one per line. */
+    optionsKey?: string;
+}
+export declare function resolvePropFields(fields: FormFieldProp[], t: TFunction): ResolvedFormField[];
+/** `Hva gjelder det?` → `hva-gjelder-det`; falls back to `felt`. */
+export declare function slugifyFieldName(label: string): string;
+/** A name no existing field uses. */
+export declare function uniqueFieldName(base: string, taken: Iterable<string>): string;
+export type FormValue = string | boolean | string[];
+export type FormValues = Record<string, FormValue>;
+export declare function emptyValue(type: FormFieldType): FormValue;
+export declare function emptyValues(fields: ResolvedFormField[]): FormValues;
+export type FieldErrorCode = 'required' | 'email' | 'url' | 'number';
+/** Norwegian fallbacks; a site overrides them via `form.validation.<code>`. */
+export declare const FIELD_ERROR_DEFAULTS: Record<FieldErrorCode, string>;
+export declare function validateValues(fields: ResolvedFormField[], values: FormValues): Record<string, FieldErrorCode>;
+/**
+ * The body `SettoForm` posts to setto-server. See `form-submission.ts` there.
+ *
+ * `hp` and `elapsed` are the bot signals: the honeypot's value (a person
+ * cannot see the field, so anything in it came from a script) and the
+ * milliseconds between the visitor's first touch of the form and submit
+ * (a script fills a form in tens of milliseconds; a person cannot).
+ */
+export interface SubmissionEnvelope {
+    data: FormValues;
+    labels: Record<string, string>;
+    order: string[];
+    title?: string;
+    page?: string;
+    hp: string;
+    elapsed: number;
+}
+export declare function buildEnvelope(fields: ResolvedFormField[], values: FormValues, extra: {
+    title?: string;
+    page?: string;
+    hp: string;
+    elapsed: number;
+}): SubmissionEnvelope;
+/** Where a site's forms go unless the host says otherwise. */
+export declare function settoSubmissionUrl(apiUrl: string, siteId: string, formId: string): string;

package/dist/modules/forms/index.d.ts

@@ -0,0 +1,12 @@
+import type { SettoModule } from '../module';
+/**
+ * The forms module: a form primitive the site renders, an inbox in the
+ * dashboard, and the api segment between them. Server side lives in
+ * setto-server `src/modules/forms`.
+ */
+export declare const formsModule: SettoModule;
+export { SettoForm } from './SettoForm';
+export type { SettoFormProps, SettoFormClassNames } from './SettoForm';
+export type { FormSettings, FormSubmissionRow, FormsApi } from './api';
+export { FORM_FIELD_TYPES, FORM_FIELD_TYPE_LABELS, formFieldsPrefix, isFormFieldType, readLocaleFields, settoSubmissionUrl, } from './fields';
+export type { FormFieldProp, FormFieldType, FormValue, FormValues, ResolvedFormField, SubmissionEnvelope, } from './fields';

package/dist/modules/index.d.ts

@@ -0,0 +1,5 @@
+import type { SettoModule } from './module';
+export type { SettoModule } from './module';
+/** Every module the dashboard shows, in tab order. */
+export declare const SETTO_MODULES: readonly SettoModule[];
+export declare function findModule(id: string | null): SettoModule | undefined;

package/dist/modules/module.d.ts

@@ -0,0 +1,30 @@
+import type { ComponentType } from 'react';
+/**
+ * What a Setto module is, from the client's side.
+ *
+ * A module is a capability a site gets by using the library — forms today;
+ * bookings, newsletters, reviews later. Each one is a directory under
+ * `src/modules/<id>` that owns its three faces:
+ *
+ *   - a primitive the site renders (`SettoForm`), with edit chrome for the
+ *     owner and content that lives in the locale so it publishes with the
+ *     rest of the site;
+ *   - a panel in the dashboard at `/setto?view=<id>` (`AdminView`), reached
+ *     from the editor toolbar's settings item;
+ *   - an api segment (`createFormsApi`) that `createApi` mounts under its id,
+ *     against routes setto-server keeps under `src/modules/<id>`.
+ *
+ * Registering the module in `src/modules/index.ts` is what puts its tab in
+ * the dashboard. The primitive and the types are exported from the package
+ * root like everything else.
+ */
+export interface SettoModule {
+    /** Stable id — also the dashboard view name and the api segment name. */
+    id: string;
+    /** Tab label in the dashboard, in Norwegian. */
+    label: string;
+    /** The dashboard panel for the current site. */
+    AdminView: ComponentType<{
+        siteId: string;
+    }>;
+}