@formancy/react 0.4.0 → 0.6.0

package/dist/index.d.mts

@@ -1,12 +1,29 @@
 import { ComponentType, ReactElement, ReactNode } from "react";
 import { ControlProps, FieldSnapshot, FormEngine, Path } from "@formancy/core";
-import { FieldType, RemoteOption, RichCommand } from "@formancy/spec";
+import { FormText, FormText as FormText$1, FormWordId, FormWordValues, FormWords, FormWordsByLocale, FormWordsByLocale as FormWordsByLocale$1 } from "@formancy/core/words";
+import { FieldType, RemoteOption, RemoteOptionsAnswer, RemoteOptionsAnswer as RemoteOptionsAnswer$1, RemoteOptionsPage, RichCommand } from "@formancy/spec";
 //#region src/context.d.ts
-export declare function FormancyProvider({ engine, children }: {
+export declare function FormancyProvider({ engine, words, children }: {
   engine: FormEngine;
+  /**
+   * Languages a host adds, and words it changes, by locale: `{ it: { 'form.next':
+   * 'Avanti' } }`, or `{ en: { 'form.submit': 'Send' } }`. Read in the language the
+   * questions are, a word at a time, and English for the rest. A constant, as any context
+   * value should be: a new object on every render is a new language for every control below.
+   */
+  words?: FormWordsByLocale$1;
   children?: ReactNode;
 }): import("react").JSX.Element;
 export declare function useFormEngine(): FormEngine;
+/**
+ * The form's words, in the language the reader chose for it.
+ *
+ * English outside a `FormancyProvider`, which has no engine to take a language from — a
+ * resume notice a host draws beside the form rather than inside its provider. Never the
+ * browser's language: the form's is the one the reader chose, and the browser's is the
+ * one their machine came with.
+ */
+export declare function useFormText(): FormText$1;
 //#endregion
 //#region src/use-field.d.ts
 interface FieldBinding extends FieldSnapshot {
@@ -41,6 +58,10 @@ interface RepeaterBinding {
   rowCount: number;
   /** Stable per-row keys, in row order. Never key a row by its index. */
   rowIds: readonly string[];
+  /** Whether the engine would add a row: under the repeater's `maxItems`, or unbounded. */
+  canAdd: boolean;
+  /** Whether the engine would remove a row: above the repeater's `minItems`. */
+  canRemove: boolean;
   addRow(): void;
   removeRow(index: number): void;
   /** Move a row. The keyboard route to reordering; a drag is a second route to this. */
@@ -229,7 +250,13 @@ interface OptionsRequest {
    * 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. */
+  /**
+   * How many rows the control can show. A hint: the control caps what arrives anyway.
+   *
+   * A source that pages reads `limit + 1` rows to know whether there are more, answers a
+   * page of `limit`, and never counts the rest: a count reads every matching row on every
+   * keystroke, which is the scan paging exists to avoid.
+   */
   limit: number;
   /** Aborted when the answer stops being wanted — a newer keystroke, or an unmount. */
   signal: AbortSignal;
@@ -244,10 +271,26 @@ interface OptionsRequest {
  * surface on a self-hosted instance.
  */
 interface OptionsSource {
-  resolve(request: OptionsRequest): Promise<readonly RemoteOption[]>;
+  /**
+   * Every matching row, as a list — exactly as before a page could be answered, its true
+   * total included — or one page of them: `{ options, more, withheld? }`.
+   *
+   * `more` says rows match beyond these, and the control says so without a number, since
+   * nobody counted one. `withheld` counts rows the source matched and cannot hand over — a
+   * value a select could not store — because a source withholds and counts rather than
+   * filtering silently. A page with any other key, a `more` that is not a boolean or a
+   * `withheld` that is not a whole count is refused whole, and the field says its source
+   * failed rather than showing a list that looks complete
+   * ([0177](../../../docs/decisions/0177-a-source-may-say-its-list-goes-on.md)).
+   */
+  resolve(request: OptionsRequest): Promise<RemoteOptionsAnswer$1>;
   /** 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. */
+  /**
+   * Below this many characters, do not ask at all. The control says so on screen: a
+   * typeahead how many to type, and a plain select — whose query is always empty, so it
+   * never asks — that its answers are found by searching.
+   */
   minQueryLength?: number;
   /** How many rows to show at once. */
   maxRows?: number;
@@ -472,6 +515,9 @@ export declare function useRichTextEditorFactory(): RichTextEditorFactory | unde
  * **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.
+ *
+ * **It speaks the form's language inside the form's `FormancyProvider`**, and English
+ * outside one, where there is no engine to take a language from (0171).
  */
 /** What `resumeDraft` reports. Structural, so a host need not import a type. */
 interface ResumeMigration {
@@ -489,5 +535,5 @@ interface ResumeNoticeProps {
 }
 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, UploadOptions, Uploader, WizardBinding };
+export type { ErrorSummaryProps, FieldBinding, FieldComponent, FieldComponentProps, FormText, FormWordId, FormWordValues, FormWords, FormWordsByLocale, FormancyFormProps, OptionsRequest, OptionsSource, OptionsSources, Registry, RemoteOption, RemoteOptionsAnswer, RemoteOptionsPage, RepeaterBinding, ResumeMigration, ResumeNoticeProps, RichTextEditorFactory, RichTextEditorHandle, RichTextEditorMount, ScanRequest, Scanner, StoredFile, SubmitOutcome, UploadOptions, 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/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":";;;;wBAagB,mBAAmB,QAAQ;EAAc,QAAQ;EAAY,WAAW;oBAAW,IAAA;wBAOnF,iBAAiB;;;UCfhB,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;;;;;;;;;;;;;;;;;UCQzC;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;;;;;;;;;;;;;;;;;;;;;;;;;wBCDP,aAAa,OAAO,oCAAiB,IAAA;;;UCnDpC;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;;;;;;;;;;UAWe;;;;;EAKf;;EAEA,QAAQ;;EAER,WAAW,cAAc;;;;;;;;;KAUf,YAAY,MAAM,MAAM,SAAS,kBAAkB,QAAQ;qBAI1D,kCAAgB,SAAA;;;;;;;;;wBAUb,eAAe;;;;;;;;;;;;;;;;;;;;;UC1Cd;;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"}
+{"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":";;;;;wBAsBgB,mBACd,QACA,OACA;EAEA,QAAQ;;;;;;;EAOR,QAAQ;EACR,WAAW;oBACZ,IAAA;wBAsBe,iBAAiB;;;;;;;;;wBAkBjB,eAAe;;;UCvEd,qBAAqB;EACpC,SAAS;EACT;;EAEA,cAAc;;EAEd;IAAc;IAAY;;;EAE1B;IAAc;;;;;;;;;;;;;wBAaA,SAAS,eAAe,OAAO;;;UCrB9B;EACf;;EAEA;;EAEA;;EAEA;EACA;EACA,UAAU;;EAEV,QAAQ,cAAc;;;;;;;wBAQR,YAAY,eAAe,OAAO;;;UCrBjC;EACf;EACA;;;EAGA;EACA;;EAEA,QAAQ;EACR;;EAEA,KAAK;;;;;;;wBAQS,aAAa;;;;;;;;;;;wBCTb;EAAqB;EAAa,QAAQ;;;;;;;;;;;;;;;;;UCQzC;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;;;;;;;;;;;;;;;;;;;;;;;;;wBCCP,aAAa,OAAO,oCAAiB,IAAA;;;UCrDpC;EACf,SAAS;;;;;;;;;;;wBAYK,eAAe,UAAU,oCAAiB,IAAA;;;;;;;;;;;;;;;;;;;;wBCI1C,WAAW;EAAY;IAAmB;;;;;;;;;;UCZzC;;;;;EAKf;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;;;EASA;;;;;;;;EAQA;;EAEA,QAAQ;;;;;;;;;;;UAYO;;;;;;;;;;;;;EAaf,QAAQ,SAAS,iBAAiB,QAAQ;;EAE1C;;;;;;EAMA;;EAEA;;;;;;;;;;;;;KAcU,iBAAiB,SAAS,eAAe;qBAIxC,wCAAsB,SAAA,SAAA,eAAA;;;;;;;;;wBAUnB,qBAAqB;;;;;;;;;;;;UC9FpB;;EAEf;;EAEA;;;;;;;;;;;;;;;;;;;KAoBU,WAAW,SAAS,gBAAgB;qBAInC,iCAAe,SAAA;;;;;;;;wBASZ,cAAc;;;;;;;;;;;;;UCpCb;;EAEf;EACA;EACA;EACA;;EAEA;;;;;;;;;;UAWe;;;;;EAKf;;EAEA,QAAQ;;EAER,WAAW,cAAc;;;;;;;;;KAUf,YAAY,MAAM,MAAM,SAAS,kBAAkB,QAAQ;qBAI1D,kCAAgB,SAAA;;;;;;;;;wBAUb,eAAe;;;;;;;;;;;;;;;;;;;;;UC1Cd;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UC9C3B;WACN;WACA,SAAS;aAAyB;aAAuB;;;UAGnD;;WAEN,YAAY;;WAEZ,SAAS,SAAS;;wBAGb,eAAe,WAAW,UAAU,oBAAoB"}