@formancy/react 0.1.0 → 0.3.0

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { ComponentType, ReactNode } from "react";
+import { ComponentType, ReactElement, ReactNode } from "react";
 import { ControlProps, FieldSnapshot, FormEngine, Path } from "@formancy/core";
-import { FieldType } from "@formancy/spec";
+import { FieldType, RemoteOption, RichCommand } from "@formancy/spec";
 //#region src/context.d.ts
 export declare function FormancyProvider({ engine, children }: {
   engine: FormEngine;
@@ -43,6 +43,8 @@ interface RepeaterBinding {
   rowIds: readonly string[];
   addRow(): void;
   removeRow(index: number): void;
+  /** Move a row. The keyboard route to reordering; a drag is a second route to this. */
+  moveRow(from: number, to: number): void;
 }
 /**
  * A repeater's live row list. Renders exactly when rows are added, removed or
@@ -55,6 +57,10 @@ export declare function useRepeater(path: string | Path): RepeaterBinding;
 interface WizardBinding {
   page: number;
   pageCount: number;
+  /** Whether there is a live page after this one. Not `page < pageCount - 1`
+   *  once a page can be walked past: the last live page is not always the last. */
+  canGoNext: boolean;
+  canGoBack: boolean;
   /** Resolves true iff the page advanced; a failed validation keeps the page. */
   next(): Promise<boolean>;
   back(): void;
@@ -82,7 +88,13 @@ export declare function useSubmit(): () => {
   errors: Record<string, string[]>;
 };
 //#endregion
-//#region src/form.d.ts
+//#region src/fields/internals.d.ts
+/**
+ * The pieces every control shares: the shell it renders inside, the prop shapes, and the few helpers more than one of them needs.
+ *
+ * One file per control, because a control changes for its own reasons.
+ * These were one 2,154-line file — the largest in the repository.
+ */
 /**
  * The component registry — theming mechanism number two. The schema decides
  * WHAT a field is; the registry decides what RENDERS it, with per-path entries
@@ -114,9 +126,30 @@ interface FormancyFormProps {
    */
   labels?: Record<string, string>;
   registry?: Registry;
+  /**
+   * Render a named entry from the schema's `layouts` instead of model order —
+   * `"web"`, `"print"`, whatever the document defines. Unknown or absent, the
+   * form falls back to model order, because a mistyped layout name should not
+   * produce an empty form.
+   */
+  layout?: string;
   submitLabel?: string;
   onSubmit?: (outcome: SubmitOutcome) => void;
 }
+//#endregion
+//#region src/form.d.ts
+/**
+ * The form, the list that walks it, and which component renders which type.
+ *
+ * What is left after the controls moved into `fields/`: 2,154 lines that had
+ * become the place things went. Three subjects remain here and they are one —
+ * a form renders a list, a list renders a slot, a slot may render a repeater,
+ * and a repeater renders a list. Mutual recursion is not a seam.
+ *
+ * `null` in the map is not an omission. `hidden` renders nothing by design, and
+ * `group`, `page` and `repeater` are containers the list itself walks rather
+ * than controls.
+ */
 /**
  * Renders the whole form from the engine: one slot per field, resolved through
  * the registry. Slots subscribe individually, so a keystroke re-renders one
@@ -143,5 +176,299 @@ interface ErrorSummaryProps {
  */
 export declare function ErrorSummary({ labels }: ErrorSummaryProps): import("react").JSX.Element | null;
 //#endregion
-export type { ErrorSummaryProps, FieldBinding, FieldComponent, FieldComponentProps, FormancyFormProps, Registry, RepeaterBinding, SubmitOutcome, WizardBinding };
+//#region src/rich-text.d.ts
+/**
+ * Showing a `richtext` answer.
+ *
+ * Every element here is created by React from a typed tree. The stored answer
+ * never reaches `dangerouslySetInnerHTML`, and there is no sanitiser, because
+ * there is nothing to sanitise: the parser in `@formancy/spec` has already
+ * turned the characters somebody typed into `{ kind: 'text' }` nodes, and a
+ * text node cannot be an element however it is spelled.
+ *
+ * That is the whole reason the grammar exists rather than storing HTML. A form
+ * answer is written by anyone who can reach the form and read later by an
+ * administrator, which is the exact shape of a stored cross-site scripting
+ * bug ([0052](../../../docs/decisions/0052-richtext-is-not-html.md)).
+ *
+ * The Angular renderer builds the same tree into the same elements, from the
+ * same parser, so the two cannot disagree about what an answer says.
+ */
+export declare function RichText({ source }: {
+  source: string;
+}): ReactElement | null;
+//#endregion
+//#region src/options-source.d.ts
+/**
+ * What a source is asked for.
+ *
+ * `kind` is a flat discriminator rather than a union of two interfaces, on the same
+ * reasoning the scanner uses: a host written in plain JavaScript must be harmless, and
+ * a shape it can read with one `if` is a shape it gets right.
+ */
+interface OptionsRequest {
+  /**
+   * `search` — somebody is typing and wants matching rows.
+   * `labels` — the form holds these values already and needs their names.
+   */
+  kind: 'search' | 'labels';
+  /** The name the document gave, which the deployment resolves. */
+  source: string;
+  /** The field's data path, e.g. `canton` or `people[1].canton`. */
+  path: string;
+  /** What was typed. Empty on a `labels` request. */
+  query: string;
+  /** The stored values to name. Empty on a `search`. */
+  values: readonly string[];
+  /**
+   * The locale the form is being resolved in — the engine's, which is the host's own
+   * `locale` when it passed one and the document's default otherwise.
+   *
+   * A remote label is a plain string, never a `{$t}` reference: nothing can check a
+   * reference that arrives at runtime, and an unchecked one resolves to nothing and
+   * shows an opaque identifier. So the source answers in the right language instead.
+   */
+  locale: string;
+  /** How many rows the control can show. A hint: the control caps what arrives anyway. */
+  limit: number;
+  /** Aborted when the answer stops being wanted — a newer keystroke, or an unmount. */
+  signal: AbortSignal;
+}
+/**
+ * Where one named list of options comes from.
+ *
+ * The third instance of the inversion the uploader and the scanner already are: the
+ * document names a list, the deployment says what that name means, and nothing in
+ * formancy ever makes a request of its own. A URL in a form document would be a
+ * deployment detail in a portable format, unfixable once published, and an SSRF
+ * surface on a self-hosted instance.
+ */
+interface OptionsSource {
+  resolve(request: OptionsRequest): Promise<readonly RemoteOption[]>;
+  /** How long to wait after a keystroke before asking. The control has a default. */
+  debounceMs?: number;
+  /** Below this many characters, do not ask at all. The control says so on screen. */
+  minQueryLength?: number;
+  /** How many rows to show at once. */
+  maxRows?: number;
+}
+/**
+ * Every source this deployment has, by the name a document would use.
+ *
+ * A MAP rather than one resolver function, and that is the one deliberate difference
+ * from `Scanner`. The control has to know **synchronously** whether a name resolves,
+ * because absence here is the *file field's* branch and not the scanner's: a text
+ * field with no scanner still collects the answer by typing, but a select whose
+ * options come only from a source collects nothing at all, so it must say so instead
+ * of rendering an empty chooser. With a single resolver, absence would only be
+ * discoverable by calling it and failing.
+ */
+type OptionsSources = Readonly<Record<string, OptionsSource>>;
+export declare const OptionsSourcesProvider: import("react").Provider<Readonly<Record<string, OptionsSource>> | undefined>;
+/**
+ * The host's sources, or undefined when there are none.
+ *
+ * Undefined is a supported state and not a misconfiguration — a form with no sourced
+ * field never needs one. What it costs, when a document DOES name a source, is the
+ * whole field: it renders a message where the chooser would be, exactly as the file
+ * field does without an uploader.
+ */
+export declare function useOptionsSources(): OptionsSources | undefined;
+//#endregion
+//#region src/scanning.d.ts
+/**
+ * What a scanner is asked to read.
+ *
+ * The field's resolved label and its data path, and nothing else. A host's camera sheet
+ * needs to say what it is looking for, and the path lets a host meter one field's scans.
+ *
+ * **Nothing about the format is here.** `pattern` is the field's and the engine checks
+ * it; a scanner told to pre-filter would be a second validator drifting from the first.
+ */
+interface ScanRequest {
+  /** The field's label, resolved through the message catalogue. */
+  label: string;
+  /** The field's data path, e.g. `serial` or `items[1].serial`. */
+  path: string;
+}
+/**
+ * Reads a code and reports the text on it.
+ *
+ * The camera, the permission prompt, the viewfinder and the decoding all belong to
+ * whoever mounted the form ([0071](../../../docs/decisions/0071-a-scanner-is-supplied-not-built.md)).
+ *
+ * **Resolving with `null` means nobody scanned anything** — the sheet was closed. That
+ * is not a failure and the field says nothing about it.
+ *
+ * **Rejecting means the device did not work**: permission refused, no camera, a stream
+ * that died. The field says so in its status region rather than its error region,
+ * because a hardware problem is not a wrong answer.
+ *
+ * What comes back is stored exactly as typing it would be. **A scanner may not
+ * pre-validate**: a value the field's `pattern` refuses is still what the camera read,
+ * and dropping it would leave the field looking empty with no record of why.
+ */
+type Scanner = (request: ScanRequest) => Promise<string | null>;
+export declare const ScannerProvider: import("react").Provider<Scanner | undefined>;
+/**
+ * The host's scanner, or undefined when there is none.
+ *
+ * Undefined is a supported state. A `scanner` widget with no scanner behind it renders
+ * the ordinary text input and no button — typing was always the field's primary route,
+ * so there is nothing to disable and a Scan button that opened nothing would be worse.
+ */
+export declare function useScanner(): Scanner | undefined;
+//#endregion
+//#region src/uploads.d.ts
+/**
+ * Where a file goes, and what the submission remembers about it.
+ *
+ * This package has no opinion about the destination: the same field works against local
+ * disk, S3 or a customer's own service, and none of them is a dependency of a renderer.
+ *
+ * **The bytes never pass through the submission.** What is stored is what the file is
+ * and where it went, so a submission read back years later is small, readable on its
+ * own, and says what was attached even if the object store has since been emptied.
+ */
+interface StoredFile {
+  /** Stable within the submission; how a row is keyed and removed. */
+  id: string;
+  name: string;
+  size: number;
+  contentType: string;
+  /** Where the bytes are, in whatever the host's storage calls a location. */
+  storageKey: string;
+}
+/**
+ * Uploads one file and reports what was stored.
+ *
+ * **Rejecting is a real answer**: the field says so out loud rather than dropping the
+ * file, because a submission somebody believes carries their evidence and does not is
+ * the worst outcome available here.
+ */
+type Uploader = (file: File) => Promise<StoredFile>;
+export declare const UploaderProvider: import("react").Provider<Uploader | undefined>;
+/**
+ * The host's uploader, or undefined when there is none.
+ *
+ * Undefined is a supported state, not a misconfiguration: a form with no file
+ * fields needs no uploader, and a file field without one renders read-only and
+ * says why. The alternative — throwing — would turn a form that mostly works
+ * into a blank page.
+ */
+export declare function useUploader(): Uploader | undefined;
+//#endregion
+//#region src/rich-text-editor.d.ts
+/**
+ * A rich-text editing surface, supplied by the host.
+ *
+ * The same split as the uploader, for the same reason. A contenteditable editor
+ * means ProseMirror, and ProseMirror is larger than this entire package — so a
+ * form with no rich-text field, which is most of them, must not pay for one.
+ * The host passes a factory; without one the field is a textarea with a toolbar,
+ * which is a working editor and not a degraded mode
+ * ([0061](../../../docs/decisions/0061-tiptap-over-the-closed-grammar.md)).
+ *
+ * What crosses this boundary is **the stored grammar in both directions, never
+ * markup**. That is the whole reason an editor is admissible: nothing on either
+ * side of this interface holds a string of HTML, so no consumer of an answer
+ * becomes a sanitiser ([0052](../../../docs/decisions/0052-richtext-is-not-html.md)).
+ * A factory that returned HTML here would be the bug this design exists to
+ * prevent, which is why the type says `string` and the documentation says which
+ * string.
+ */
+interface RichTextEditorHandle {
+  /** The stored answer, in the grammar. */
+  value: () => string;
+  /** Replace the content when the form's value changes underneath the editor. */
+  setValue: (value: string) => void;
+  /**
+   * Run a formatting command, so the field's own toolbar keeps working.
+   *
+   * Needed because an editor library brings keyboard shortcuts and no toolbar
+   * UI. Leaving the field's toolbar out made Bold reachable by Ctrl+B and by no
+   * visible control, which is a regression against the `<textarea>` it replaced
+   * and unusable for anybody who does not know the shortcut.
+   *
+   * The commands are the grammar's whole surface — the same `RichCommand`
+   * values the textarea's toolbar uses — so one toolbar drives either surface
+   * and the two cannot offer different things.
+   */
+  run: (command: RichCommand, href?: string) => void;
+  /** Whether the command is on at the caret, for the toolbar's pressed state. */
+  isActive: (command: RichCommand) => boolean;
+  destroy: () => void;
+}
+interface RichTextEditorMount {
+  /** Where to mount. The host's factory owns what it puts inside. */
+  readonly element: Element;
+  /** The stored answer to open with, in the grammar. */
+  readonly value: string;
+  /** Called with the new stored answer, in the grammar. */
+  readonly onChange: (value: string) => void;
+  readonly editable: boolean;
+  /**
+   * Attributes for the editing surface itself, so the ENGINE keeps owning the
+   * accessibility wiring.
+   *
+   * The ids in here are minted by the engine and composed centrally, which is
+   * what makes `aria-describedby` correct in both renderers rather than in
+   * three separate implementations. An editor package that invented its own
+   * labelling would be the fourth implementation, and the one nobody tests.
+   */
+  readonly attributes: Readonly<Record<string, string>>;
+}
+type RichTextEditorFactory = (mount: RichTextEditorMount) => RichTextEditorHandle;
+export declare const RichTextEditorProvider: import("react").Provider<RichTextEditorFactory | undefined>;
+/**
+ * The host's editor factory, or undefined when there is none.
+ *
+ * Undefined is a supported state and the default one. Unlike the uploader — where
+ * its absence makes a file field read-only, because there is nowhere to put the
+ * bytes — its absence here costs nothing but the WYSIWYG surface: the answer is
+ * still editable, still valid, and still the same grammar.
+ */
+export declare function useRichTextEditorFactory(): RichTextEditorFactory | undefined;
+//#endregion
+//#region src/resume-notice.d.ts
+/**
+ * Telling somebody their draft came back changed.
+ *
+ * The server already does the careful half. A republished form migrates a draft
+ * lazily on resume, and answers whose field no longer exists move to
+ * `data.__orphaned` rather than being deleted
+ * ([0027](../../../docs/decisions/0027-lazy-draft-migration.md)). It reports what
+ * happened as a severity and a list of changes.
+ *
+ * This is what shows it. Without it somebody resumes a draft, some of their answers are
+ * no longer on the form, and they submit believing everything they typed is in it — the
+ * answers are not lost from storage, they are lost from the submission.
+ *
+ * It is built like the error summary, and for the same reason: something important
+ * happened and the person may be looking at the middle of a long form. The container
+ * takes focus through `tabindex="-1"`, and is **not** `role="alert"` and carries no
+ * `aria-live` — focusing a container already makes a screen reader announce it, and
+ * doing both announces it twice.
+ *
+ * **A library cannot make a host render it.** Resuming a draft is the host's call, so
+ * this component exists and is documented, and showing it is the deployment's
+ * responsibility. `SAFETY-ANALYSIS.md` says so rather than claiming a guarantee.
+ */
+/** What `resumeDraft` reports. Structural, so a host need not import a type. */
+interface ResumeMigration {
+  readonly severity: 'lossy' | 'breaking';
+  readonly changes: ReadonlyArray<{
+    readonly kind: string;
+    readonly path?: string;
+  }>;
+}
+interface ResumeNoticeProps {
+  /** Omitted or undefined when the draft came back unchanged. */
+  readonly migration?: ResumeMigration | undefined;
+  /** Question wording for a field key, since a key is not what the form asked. */
+  readonly labels?: Readonly<Record<string, string>>;
+}
+export declare function ResumeNotice({ migration, labels }: ResumeNoticeProps): ReactElement | null;
+//#endregion
+export type { ErrorSummaryProps, FieldBinding, FieldComponent, FieldComponentProps, FormancyFormProps, OptionsRequest, OptionsSource, OptionsSources, Registry, RepeaterBinding, ResumeMigration, ResumeNoticeProps, RichTextEditorFactory, RichTextEditorHandle, RichTextEditorMount, ScanRequest, Scanner, StoredFile, SubmitOutcome, Uploader, WizardBinding };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/context.tsx","../src/use-field.ts","../src/use-repeater.ts","../src/use-wizard.ts","../src/use-submit.ts","../src/form.tsx","../src/error-summary.tsx"],"mappings":";;;;wBAYgB,mBAAmB,QAAQ;EAAc,QAAQ;EAAY,WAAW;oBAAW,IAAA;wBAInF,iBAAiB;;;UCXhB,qBAAqB;EACpC,SAAS;EACT;;EAEA,cAAc;;EAEd;IAAc;IAAY;;;EAE1B;IAAc;;;;;;;;;;;;;wBAaA,SAAS,eAAe,OAAO;;;UCrB9B;EACf;;EAEA;EACA;EACA,UAAU;;;;;;;wBAQI,YAAY,eAAe,OAAO;;;UCfjC;EACf;EACA;;EAEA,QAAQ;EACR;;EAEA,KAAK;;;;;;;wBAQS,aAAa;;;;;;;;;;;wBCNb;EAAqB;EAAa,QAAQ;;;;;;;;;;;UCKzC;EACf;EACA;;KAGU,iBAAiB,cAAc;UAE1B;EACf,SAAS,QAAQ,OAAO,WAAW;EACnC,SAAS,eAAe;;UAGT;EACf;EACA,QAAQ;;EAER;;UAGe;;;;;;;EAOf,SAAS;EACT,WAAW;EACX;EACA,YAAY,SAAS;;;;;;;;;;;wBAYP,aAAa,OAAO,oCAAiB,IAAA;;;UCtDpC;EACf,SAAS;;;;;;;;;;;wBAYK,eAAe,UAAU,oCAAiB,IAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/context.tsx","../src/use-field.ts","../src/use-repeater.ts","../src/use-wizard.ts","../src/use-submit.ts","../src/fields/internals.tsx","../src/form.tsx","../src/error-summary.tsx","../src/rich-text.tsx","../src/options-source.ts","../src/scanning.ts","../src/uploads.ts","../src/rich-text-editor.ts","../src/resume-notice.tsx"],"mappings":";;;;wBAYgB,mBAAmB,QAAQ;EAAc,QAAQ;EAAY,WAAW;oBAAW,IAAA;wBAInF,iBAAiB;;;UCXhB,qBAAqB;EACpC,SAAS;EACT;;EAEA,cAAc;;EAEd;IAAc;IAAY;;;EAE1B;IAAc;;;;;;;;;;;;;wBAaA,SAAS,eAAe,OAAO;;;UCrB9B;EACf;;EAEA;EACA;EACA,UAAU;;EAEV,QAAQ,cAAc;;;;;;;wBAQR,YAAY,eAAe,OAAO;;;UCjBjC;EACf;EACA;;;EAGA;EACA;;EAEA,QAAQ;EACR;;EAEA,KAAK;;;;;;;wBAQS,aAAa;;;;;;;;;;;wBCTb;EAAqB;EAAa,QAAQ;;;;;;;;;;;;;;;;;UCOzC;EACf;EACA;;KAGU,iBAAiB,cAAc;UAE1B;EACf,SAAS,QAAQ,OAAO,WAAW;EACnC,SAAS,eAAe;;UAGT;EACf;EACA,QAAQ;;EAER;;UAGe;;;;;;;EAOf,SAAS;EACT,WAAW;;;;;;;EAOX;EACA;EACA,YAAY,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;wBCHP,aAAa,OAAO,oCAAiB,IAAA;;;UChDpC;EACf,SAAS;;;;;;;;;;;wBAYK,eAAe,UAAU,oCAAiB,IAAA;;;;;;;;;;;;;;;;;;;;wBCI1C,WAAW;EAAY;IAAmB;;;;;;;;;;UCZzC;;;;;EAKf;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;EASA;;EAEA;;EAEA,QAAQ;;;;;;;;;;;UAYO;EACf,QAAQ,SAAS,iBAAiB,iBAAiB;;EAEnD;;EAEA;;EAEA;;;;;;;;;;;;;KAcU,iBAAiB,SAAS,eAAe;qBAIxC,wCAAsB,SAAA,SAAA,eAAA;;;;;;;;;wBAUnB,qBAAqB;;;;;;;;;;;;UCxEpB;;EAEf;;EAEA;;;;;;;;;;;;;;;;;;;KAoBU,WAAW,SAAS,gBAAgB;qBAInC,iCAAe,SAAA;;;;;;;;wBASZ,cAAc;;;;;;;;;;;;;UCpCb;;EAEf;EACA;EACA;EACA;;EAEA;;;;;;;;;KAUU,YAAY,MAAM,SAAS,QAAQ;qBAIlC,kCAAgB,SAAA;;;;;;;;;wBAUb,eAAe;;;;;;;;;;;;;;;;;;;;;UCtBd;;EAEf;;EAEA,WAAW;;;;;;;;;;;;;EAaX,MAAM,SAAS,aAAa;;EAE5B,WAAW,SAAS;EACpB;;UAGe;;WAEN,SAAS;;WAET;;WAEA,WAAW;WACX;;;;;;;;;;WAUA,YAAY,SAAS;;KAGpB,yBAAyB,OAAO,wBAAwB;qBAIvD,wCAAsB,SAAA;;;;;;;;;wBAUnB,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;UClD3B;WACN;WACA,SAAS;aAAyB;aAAuB;;;UAGnD;;WAEN,YAAY;;WAEZ,SAAS,SAAS;;wBAGb,eAAe,WAAW,UAAU,oBAAoB"}