better-supabase 0.13.0 → 0.15.0

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

@@ -1,17 +1,64 @@
 /// <reference lib="esnext.temporal" />
-import { T as ErrorMapper, t as AsyncResult } from "../../result-mijqfoJN.js";
-import { t as StandardSchemaV1 } from "../../standard-16AIDny5.js";
-import { n as ExtraFields, r as FieldsOf } from "../../block-fields-DnXkMney.js";
-import { B as FormEventData, V as FormSubmissionEventData, it as SignatureEventData, wt as Events } from "../../events-DhGgwqQA.js";
+import { D as ValidationIssue, T as ErrorMapper, t as AsyncResult } from "../../result-DZeA5KS6.js";
+import { t as StandardSchemaV1$1 } from "../../standard-DBV730sF.js";
+import { r as FieldsOf } from "../../block-fields-BE7pInWZ.js";
+import { B as FormEventData, Ct as Events, V as FormSubmissionEventData } from "../../events-vcqenSYU.js";
 import { n as Logger } from "../../logger-DWVYUmwi.js";
-import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DBPhgF3W.js";
-import { n as BlockOptions, r as BlockTemporalOptions } from "../../block-helpers-DyA5BAW4.js";
-import { n as BlockHooks } from "../../block-hooks-BadAniNI.js";
-import { s as BlockOf } from "../../define-block-MyM4lH42.js";
-import { a as FormDefinition, c as FormJson, d as FormStep, f as formDefinitionProblems, i as FormCondition, l as FormJsonSchema, m as isFormDefinition, n as FORM_FIELD_TYPES, o as FormField, p as formSchema, r as FORM_SCHEMA_DIALECT, s as FormFieldType, t as FORM_DEFINITION_SCHEMA, u as FormOption } from "../../form-definition-DcVnFzl4.js";
-import { _ as visibleFields, a as createQuestionnaireController, b as answersSchema, c as QuestionnaireState, d as finishQuestionnaire, f as initialQuestionnaire, g as stepIssues, h as questionnaireSteps, i as QuestionnaireSnapshot, l as QuestionnaireStepView, m as questionnaireReducer, n as QuestionnaireController, o as QuestionnaireAction, p as pruneAnswers, r as QuestionnaireOptions, s as QuestionnaireForm, t as QuestionnaireActions, u as conditionHolds, v as visibleSteps, x as validateAnswers, y as FormAnswers } from "../../client-BsfsRHae.js";
+import { r as BlockTemporalOptions } from "../../block-helpers-CRpAHrp_.js";
+import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../../block-transport-DWZSJrwN.js";
+import { n as BlockHooks } from "../../block-hooks-DZN2w69m.js";
+import { c as BlockOf } from "../../define-block-BVcLQ3DF.js";
+import { n as Controller } from "../../controller-BrP0gn47.js";
+import { _ as isFormDefinition, a as FormDefinition, c as FormJson, d as FormScoring, f as FormStep, g as formSchema, h as formDefinitionProblems, i as FormCondition, l as FormJsonSchema, m as UNSCORED_FIELD_TYPES, n as FORM_FIELD_TYPES, o as FormField, p as NPS_MAX, r as FORM_SCHEMA_DIALECT, s as FormFieldType, t as FORM_DEFINITION_SCHEMA, u as FormOption } from "../../form-definition-BjEtH8BT.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/blocks/forms/validate.d.ts
+/** A submission's answers, by field key. */
+type FormAnswers = {
+  readonly [key: string]: FormJson;
+};
+/**
+ * Checks answers against a form version's schema with the keywords the
+ * generator emits, so a form can show errors before it submits. Postgres checks
+ * the same schema again on submit; this is not a general JSON Schema
+ * validator.
+ */
+export declare function validateAnswers(schema: FormJsonSchema, answers: unknown): readonly ValidationIssue[];
+/** A form version's schema as a Standard Schema, for form libraries. */
+export declare function answersSchema(schema: FormJsonSchema): StandardSchemaV1<unknown, FormAnswers>;
+//#endregion
+//#region src/blocks/forms/scoring.d.ts
+/** A scored submission's grade, as `form_score` computes it in Postgres. */
+interface FormScore {
+  /** The points the correct answers earned. */
+  readonly score: number;
+  /** The points of every scored field that showed. */
+  readonly maxScore: number;
+  /** Against `scoring.passMark`; `undefined` without one. */
+  readonly passed?: boolean;
+}
+/** An `nps` answer's bucket: 9 and 10 promote, 7 and 8 are passive. */
+type NpsCategory = "promoter" | "passive" | "detractor";
+/**
+ * The grade of `answers` against a definition with its `correct` answers: the
+ * TypeScript twin of `form_score`, for a preview before submitting. A field
+ * hidden by its `showIf` (or its step's) counts toward neither score.
+ * `undefined` when no field has a correct answer.
+ */
+export declare function formScore(definition: FormDefinition, answers: FormAnswers): FormScore | undefined;
+/** The bucket of an `nps` answer from 0 to 10. */
+export declare function npsCategory(answer: number): NpsCategory;
+/**
+ * The Net Promoter Score of the counts: the promoters' share minus the
+ * detractors', from -100 to 100, to one decimal. `undefined` without answers.
+ */
+export declare function npsScore(counts: {
+  readonly promoters: number;
+  readonly passives: number;
+  readonly detractors: number;
+}): number | undefined;
+//#endregion
 //#region src/blocks/forms/forms.d.ts
-interface FormsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+interface FormsOptions<S extends StandardSchemaV1$1 | undefined = undefined> extends BlockTemporalOptions {
   readonly transport: BlockTransport;
   /**
    * The module schema, or its API schema: `defineBlocks` passes it from
@@ -87,6 +134,41 @@ interface FormSubmission {
   readonly createdAt: Temporal.Instant;
   readonly submittedAt?: Temporal.Instant;
   readonly updatedAt: Temporal.Instant;
+  /**
+   * The grade Postgres gave a submission to a scored version; `undefined` for a
+   * draft or a form without correct answers.
+   */
+  readonly score?: FormScore;
+}
+/** The NPS counts of one period, or of every answer. */
+interface NpsCounts {
+  readonly responses: number;
+  readonly promoters: number;
+  readonly passives: number;
+  readonly detractors: number;
+  /** From -100 to 100, to one decimal; `undefined` without responses. */
+  readonly score?: number;
+}
+interface NpsPeriod extends NpsCounts {
+  /** The period's first instant (UTC). */
+  readonly start: Temporal.Instant;
+}
+/** `nps`: the counts over every answer, and per period with a `bucket`. */
+interface FormNps extends NpsCounts {
+  /** The `nps` field the counts are for. */
+  readonly field: string;
+  readonly periods: readonly NpsPeriod[];
+}
+type NpsBucket = "day" | "week" | "month" | "quarter" | "year";
+interface NpsOptions {
+  /** Default: the current version's first `nps` field. */
+  readonly field?: string;
+  /** Submissions from this instant on. */
+  readonly since?: Temporal.Instant;
+  /** Submissions before this instant. */
+  readonly until?: Temporal.Instant;
+  /** Adds `periods`, by UTC day, week, month, quarter or year. */
+  readonly bucket?: NpsBucket;
 }
 interface PublicSubmission {
   readonly id: string;
@@ -156,132 +238,130 @@ interface Forms<F extends object = Record<never, never>> {
   listSubmissions(formId: string, options?: SubmissionListOptions): AsyncResult<readonly FormSubmission[]>;
   review(id: string, status: "accepted" | "rejected" | "submitted"): AsyncResult<FormSubmission>;
   deleteSubmission(id: string): AsyncResult<boolean>;
-}
-/** The `forms` SQL module as typed calls. */
-export declare function createForms<S extends StandardSchemaV1 | undefined = undefined>(options: FormsOptions<S>): Forms<FieldsOf<S>>;
-//#endregion
-//#region src/blocks/forms/signatures.d.ts
-interface SignaturesOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockOptions {
   /**
-   * A Standard Schema for the request's extra columns
-   * (`blocks.signatures.options.extraColumns`), keyed by database name. It
-   * types and parses them on the request reads, and validates them on
-   * `request`.
+   * The Net Promoter Score of the form's submitted and accepted answers, for
+   * reviewers.
    */
-  readonly fields?: S;
-  /** `withBlockHooks` hooks around the client's methods. */
-  readonly hooks?: NoInfer<BlockHooks<Signatures<FieldsOf<S>>>>;
-  /** Receives the errors `after` hooks throw. Default: `console`. */
-  readonly logger?: Logger;
+  nps(formId: string, options?: NpsOptions): AsyncResult<FormNps>;
 }
-type SignatureMethod = "drawn" | "typed" | "click";
-type SignatureOrder = "parallel" | "sequential";
-type SignatureRequestStatus = "pending" | "completed" | "declined" | "cancelled";
-/** A request. `F` types the extra columns the `fields` schema describes. */
-interface SignatureRequest<F extends object = Record<never, never>> {
-  readonly id: string;
-  readonly organizationId: string;
-  readonly subjectType: string;
-  readonly subjectId: string;
-  /** The frozen version the signers sign. */
-  readonly versionId: string;
-  /** The version's content hash when the request was made. */
-  readonly contentHash: string;
-  readonly signers: readonly string[];
-  readonly order: SignatureOrder;
-  readonly status: SignatureRequestStatus;
-  readonly approvalRequestId?: string;
-  readonly message?: string;
-  readonly requestedBy?: string;
-  readonly createdAt: Temporal.Instant;
-  readonly completedAt?: Temporal.Instant;
-  /** The extra columns, keyed by database name. */
-  readonly fields: ExtraFields<F>;
-}
-interface Signature {
-  readonly id: string;
-  readonly requestId: string;
-  readonly signer: string;
-  readonly method: SignatureMethod;
-  readonly typedName?: string;
-  /** The attachment that holds a drawn signature's image. */
-  readonly imageAttachmentId?: string;
-  /**
-   * SHA-256 over the request, the content hash, the signer, the method and the
-   * time.
-   */
-  readonly signedHash: string;
-  readonly ip?: string;
-  readonly userAgent?: string;
-  readonly signedAt: Temporal.Instant;
-}
-interface SignatureVerification {
-  /** The signed version is unchanged and every signature hash matches. */
-  readonly valid: boolean;
-  /** The signed version's content still hashes to the requested hash. */
-  readonly contentMatches: boolean;
-  /** The record has a newer version than the one signed. */
-  readonly changedSince: boolean;
-  readonly latestVersionId?: string;
-  readonly signatures: readonly {
-    readonly id: string;
-    readonly signer: string;
-    readonly valid: boolean;
-  }[];
+/** The `forms` SQL module as typed calls. */
+export declare function createForms<S extends StandardSchemaV1$1 | undefined = undefined>(options: FormsOptions<S>): Forms<FieldsOf<S>>;
+//#endregion
+//#region src/blocks/forms/questionnaire.d.ts
+/**
+ * Whether `condition` holds for `answers`, with the semantics of its JSON
+ * Schema `if`.
+ */
+export declare function conditionHolds(condition: FormCondition | undefined, answers: FormAnswers): boolean;
+/** The steps whose `showIf` holds. */
+export declare function visibleSteps(definition: FormDefinition, answers: FormAnswers): readonly FormStep[];
+/** The step's fields whose `showIf` holds. */
+export declare function visibleFields(step: FormStep, answers: FormAnswers): readonly FormField[];
+/**
+ * The answers without the ones for hidden steps and fields. Removing an answer
+ * can hide a later field, so it repeats until nothing changes.
+ */
+export declare function pruneAnswers(definition: FormDefinition, answers: FormAnswers): FormAnswers;
+/** The schema's issues for the fields `step` shows. */
+export declare function stepIssues(schema: FormJsonSchema, step: FormStep, answers: FormAnswers): readonly ValidationIssue[];
+interface QuestionnaireState {
+  /** The step on screen, by key. */
+  readonly step: string;
+  readonly answers: FormAnswers;
+  /** The steps that passed their checks on `next`. */
+  readonly completed: readonly string[];
+  /** The issues of the step on screen after a `next` or `submit` that failed. */
+  readonly issues: readonly ValidationIssue[];
 }
-/** A request with its signatures and their verification, from `get`. */
-interface SignatureRequestDetail<F extends object = Record<never, never>> extends SignatureRequest<F> {
-  readonly signatures: readonly Signature[];
-  readonly verification: SignatureVerification;
+type QuestionnaireAction = {
+  readonly type: "answer";
+  readonly key: string;
+  readonly value: FormJson | undefined;
+} | {
+  readonly type: "next";
+} | {
+  readonly type: "back";
+} | {
+  readonly type: "goTo";
+  readonly step: string;
+} | {
+  readonly type: "reset";
+  readonly answers?: FormAnswers;
+};
+interface QuestionnaireForm {
+  readonly definition: FormDefinition;
+  /** The version's generated schema. */
+  readonly schema: FormJsonSchema;
 }
-interface SignatureRequestInput<F extends object = Record<never, never>> {
-  readonly organizationId: string;
-  readonly subjectType: string;
-  readonly subjectId: string;
-  /** Members of the organization, in signing order for `sequential`. */
-  readonly signers: readonly string[];
-  /** Default: a new snapshot of the record's versioned columns. */
-  readonly versionId?: string;
-  /** Default: `parallel`. */
-  readonly order?: SignatureOrder;
-  /** An approval request on the same record that a signer's signature decides. */
-  readonly approvalRequestId?: string;
-  readonly message?: string;
-  /** The extra columns to set. */
-  readonly fields?: Partial<F>;
+/** The state before the first answer. */
+export declare function initialQuestionnaire(form: QuestionnaireForm, answers?: FormAnswers): QuestionnaireState;
+/**
+ * The questionnaire as a reducer: answers, the current step and the steps done.
+ * `next` checks the step's fields against the version's schema and stays put
+ * with `issues` when one fails; hidden steps are skipped.
+ */
+export declare function questionnaireReducer(form: QuestionnaireForm, state: QuestionnaireState, action: QuestionnaireAction): QuestionnaireState;
+interface QuestionnaireStepView {
+  readonly key: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly fields: readonly FormField[];
+  readonly completed: boolean;
+  readonly active: boolean;
 }
-type SignInput = {
-  readonly method: "click";
-} | {
-  readonly method: "typed";
-  readonly typedName: string;
+/** The visible steps with their status, in the shape a Stepper renders. */
+export declare function questionnaireSteps(form: QuestionnaireForm, state: QuestionnaireState): readonly QuestionnaireStepView[];
+/** The pruned answers, or every issue when the whole form does not pass. */
+export declare function finishQuestionnaire(form: QuestionnaireForm, state: QuestionnaireState): {
+  readonly ok: true;
+  readonly answers: FormAnswers;
 } | {
-  readonly method: "drawn";
-  readonly imageAttachmentId: string;
+  readonly ok: false;
+  readonly issues: readonly ValidationIssue[];
 };
-interface SignatureRequestListOptions {
-  readonly subjectType?: string;
-  readonly subjectId?: string;
-  readonly status?: SignatureRequestStatus;
-  /** Only the requests the caller is asked to sign. */
-  readonly mine?: boolean;
-  readonly pageSize?: number;
-  /** Requests created before this time, for the next page. */
-  readonly before?: Temporal.Instant;
+//#endregion
+//#region src/blocks/forms/client.d.ts
+interface QuestionnaireOptions {
+  /** A form version, or anything with its `definition` and `schema`. */
+  readonly form: QuestionnaireForm;
+  /** Answers to start from, such as a saved draft. */
+  readonly initialAnswers?: FormAnswers;
+  /** Receives the answers of the visible fields once the whole form passes. */
+  readonly onSubmit: (answers: FormAnswers) => Promise<void> | void;
 }
-interface Signatures<F extends object = Record<never, never>> {
-  request(input: SignatureRequestInput<F>): AsyncResult<SignatureRequest<F>>;
-  sign(requestId: string, input: SignInput): AsyncResult<Signature & {
-    readonly requestStatus: SignatureRequestStatus;
-  }>;
-  decline(requestId: string, reason?: string): AsyncResult<SignatureRequest<F>>;
-  cancel(requestId: string): AsyncResult<SignatureRequest<F>>;
-  get(requestId: string): AsyncResult<SignatureRequestDetail<F>>;
-  /** Newest first. */
-  list(organizationId: string, options?: SignatureRequestListOptions): AsyncResult<readonly SignatureRequest<F>[]>;
+interface QuestionnaireSnapshot {
+  /** The visible steps, for a Stepper's items. */
+  readonly steps: readonly QuestionnaireStepView[];
+  /** The step on screen. */
+  readonly step: QuestionnaireStepView | undefined;
+  readonly answers: FormAnswers;
+  /**
+   * Issues by field key: the step on screen's after `next`, every field's after
+   * a failed `submit`.
+   */
+  readonly issues: Readonly<Record<string, readonly string[]>>;
+  readonly isFirst: boolean;
+  readonly isLast: boolean;
+  readonly submitting: boolean;
+}
+interface QuestionnaireActions {
+  /** `undefined` removes the answer. */
+  readonly setAnswer: (key: string, value: FormJson | undefined) => void;
+  /** Checks the step and moves to the next visible one. */
+  readonly next: () => void;
+  readonly back: () => void;
+  /** Moves to a step whose earlier steps are done, for a clickable Stepper. */
+  readonly goTo: (step: string) => void;
+  /** Checks the whole form, then calls `onSubmit`. Returns whether it passed. */
+  readonly submit: () => Promise<boolean>;
+  readonly reset: (answers?: FormAnswers) => void;
 }
-/** The `signatures` SQL module as typed calls. */
-export declare function createSignatures<S extends StandardSchemaV1 | undefined = undefined>(options: SignaturesOptions<S>): Signatures<FieldsOf<S>>;
+type QuestionnaireController = Controller<QuestionnaireSnapshot, QuestionnaireActions>;
+/**
+ * A multi-step form over a form version: the visible steps, the answers, and
+ * per-field issues checked against the version's JSON Schema.
+ */
+export declare function createQuestionnaireController(options: QuestionnaireOptions): QuestionnaireController;
 //#endregion
 //#region src/blocks/forms/events.d.ts
 /** The events of the `forms` block: type to data. */
@@ -294,21 +374,9 @@ type FormsEvents = {
 };
 /** The `forms` block's event types, for its manifest and `onBlockEvent`. */
 export declare const formsEvents: Events<FormsEvents>;
-/** The events of the `signatures` block: type to data. */
-type SignaturesEvents = {
-  readonly "signature.requested": SignatureEventData;
-  readonly "signature.signed": SignatureEventData;
-  readonly "signature.completed": SignatureEventData;
-  readonly "signature.declined": SignatureEventData;
-  readonly "signature.cancelled": SignatureEventData;
-};
-/** The `signatures` block's event types, for its manifest and `onBlockEvent`. */
-export declare const signaturesEvents: Events<SignaturesEvents>;
 //#endregion
 //#region src/blocks/forms/manifest.d.ts
 /** The `forms` block's manifest (ADR 0029). */
 export declare const formsBlock: BlockOf<"forms", typeof createForms, FormsEvents>;
-/** The `signatures` block's manifest (ADR 0029). */
-export declare const signaturesBlock: BlockOf<"signatures", typeof createSignatures, SignaturesEvents>;
 //#endregion
-export { type BlockTransport, FORM_DEFINITION_SCHEMA, FORM_FIELD_TYPES, FORM_SCHEMA_DIALECT, type Form, type FormAnswers, type FormCondition, type FormDefinition, type FormDetail, type FormField, type FormFieldType, type FormInput, type FormJson, type FormJsonSchema, type FormOption, type FormStatus, type FormStep, type FormSubmission, type FormSubmissionSource, type FormSubmissionStatus, type FormUpdate, type FormVersion, type Forms, type FormsEvents, type FormsOptions, type PublicForm, type PublicSubmission, type PublicSubmitOptions, type QuestionnaireAction, type QuestionnaireActions, type QuestionnaireController, type QuestionnaireForm, type QuestionnaireOptions, type QuestionnaireSnapshot, type QuestionnaireState, type QuestionnaireStepView, type SignInput, type Signature, type SignatureMethod, type SignatureOrder, type SignatureRequest, type SignatureRequestDetail, type SignatureRequestInput, type SignatureRequestListOptions, type SignatureRequestStatus, type SignatureVerification, type Signatures, type SignaturesEvents, type SignaturesOptions, type SubmissionListOptions, type SubmitOptions, answersSchema, conditionHolds, createQuestionnaireController, dbTransport, finishQuestionnaire, formDefinitionProblems, formSchema, initialQuestionnaire, isFormDefinition, pruneAnswers, questionnaireReducer, questionnaireSteps, rpcTransport, sqlTransport, stepIssues, validateAnswers, visibleFields, visibleSteps };
+export { type BlockTransport, FORM_DEFINITION_SCHEMA, FORM_FIELD_TYPES, FORM_SCHEMA_DIALECT, type Form, type FormAnswers, type FormCondition, type FormDefinition, type FormDetail, type FormField, type FormFieldType, type FormInput, type FormJson, type FormJsonSchema, type FormNps, type FormOption, type FormScore, type FormScoring, type FormStatus, type FormStep, type FormSubmission, type FormSubmissionSource, type FormSubmissionStatus, type FormUpdate, type FormVersion, type Forms, type FormsEvents, type FormsOptions, NPS_MAX, type NpsBucket, type NpsCategory, type NpsCounts, type NpsOptions, type NpsPeriod, type PublicForm, type PublicSubmission, type PublicSubmitOptions, type QuestionnaireAction, type QuestionnaireActions, type QuestionnaireController, type QuestionnaireForm, type QuestionnaireOptions, type QuestionnaireSnapshot, type QuestionnaireState, type QuestionnaireStepView, type SubmissionListOptions, type SubmitOptions, UNSCORED_FIELD_TYPES, dbTransport, formDefinitionProblems, formSchema, isFormDefinition, rpcTransport, sqlTransport };