@wise/dynamic-flow-types 2.8.0 → 2.9.0

package/build/next/schema/ObjectSchema.d.ts

@@ -4,29 +4,92 @@ import type { Icon } from '../misc/Icon';
 import type { Image } from '../misc/Image';
 import type { SummaryProvider } from '../feature/SummaryProvider';
 import type { AlertLayout } from '../layout/AlertLayout';
+/**
+* Represents an object value in the submission.
+* Objects can optionally be given a title to have them appear as form sections.
+* If you'd like to group your fields into separate sections while keeping them in the same object in your submission,
+* consider using [AllOfSchema].
+*/
 export type ObjectSchema = {
+    /**
+    * It must be `object`.
+    */
     type: 'object';
+    /**
+    * If true, the UI for this schema will not accept input, but the corresponding data will still be submitted.
+    *  Defaults to false.
+    */
     disabled?: boolean;
+    /**
+    * @deprecated Please use nested oneOf schemas instead.
+    */
+    promoted?: boolean;
+    /**
+    * Provide additional help information to the user.
+    * @deprecated Only supported on web clients
+    */
+    help?: Help;
+    /**
+    * The properties of the object.
+    */
     properties: Record<string, Schema>;
+    /**
+    * The order in which the properties should be rendered by the client. This is required because objects are
+    * inherently unordered, and all properties must be included or they will not be displayed.
+    */
     displayOrder: string[];
+    /**
+    * An array containing the names of the properties which must have a non-null value for the object to be valid.
+    */
     required?: string[];
+    /**
+    * A unique id which can be used to refer to the schema.
+    */
     $id?: string;
+    /**
+    * A user-facing title for the schema.
+    */
     title?: string;
+    /**
+    * A user-facing description for the schema.
+    */
     description?: string;
+    /**
+    * An identifier which can be used to request the client use a particular UI control to represent this schema.
+    */
     control?: string;
+    /**
+    * If true, no UI will be shown to the user for this schema, but the corresponding data will still be submitted.
+    * Defaults to false.
+    */
     hidden?: boolean;
+    /**
+    * An icon which the client can use to represent this schema.
+    */
     icon?: Icon;
+    /**
+    * An image which the client can use to represent this schema.
+    */
     image?: Image;
+    /**
+    * A list of keywords that can be used when searching or filtering items in a [com.wise.dynamicflow.schema.OneOfSchema].
+    * Only applies when this schema is child schema in a [com.wise.dynamicflow.schema.OneOfSchema].
+    */
     keywords?: string[];
+    /**
+    * Configure how this schema will be summarised when included in an [ArraySchema].
+    */
     summary?: SummaryProvider;
-    analyticsId?: string;
-    alert?: AlertLayout;
     /**
-    * @deprecated Please use nested oneOf schemas instead.
+    * An internal id which is attached to analytics events relating to the schema.
+    * It allows you to override $id during event emission, it is not user-facing and does not have to be unique within the step.
     */
-    promoted?: boolean;
+    analyticsId?: string;
     /**
-    * @deprecated Only supported on web clients
+    * Configure an alert which will be displayed above the UI for this schema. This can be used to provide warnings or
+    * additional information to the user, but shouldn't be used for validation. For client-side validation please see
+    * the validation available on each schema type, or see [com.wise.dynamicflow.feature.ValidateAsync] and
+    * [com.wise.dynamicflow.feature.Action] for server-side validation.
     */
-    help?: Help;
+    alert?: AlertLayout;
 };

package/build/next/schema/OneOfSchema.d.ts

@@ -6,49 +6,142 @@ import type { SummaryProvider } from '../feature/SummaryProvider';
 import type { AlertLayout } from '../layout/AlertLayout';
 import type { Help } from '../feature/Help';
 import type { AutocompleteToken } from '../misc/AutocompleteToken';
+/**
+* Offers a choice between a number of child schemas.
+* Use a oneOf schema to represent either the selection of one of many constant values (e.g. a select box or dropdown)
+* or alternative sections of a form (e.g. when the user can complete either section A or section B).
+*/
 export type OneOfSchema = {
+    /**
+    * If true, the UI for this schema will not accept input, but the corresponding data will still be submitted.
+    *  Defaults to false.
+    */
     disabled?: boolean;
+    /**
+    * @deprecated This property is deprecated
+    */
+    autofillProvider?: string;
+    /**
+    * @deprecated Please use nested oneOf schemas instead.
+    */
+    promoted?: boolean;
+    /**
+    * @deprecated Please use 'refreshStepOnChange' instead
+    */
+    refreshFormOnChange?: boolean;
+    /**
+    * @deprecated Please use 'refreshUrl' in Step instead
+    */
+    refreshUrl?: string;
+    /**
+    * @deprecated Please use 'refreshUrl' in Step instead
+    */
+    refreshFormUrl?: string;
+    /**
+    * @deprecated OneOf Promotion is no longer supported
+    */
+    promotion?: JsonElement;
+    /**
+    * The child schemas to be selected between.
+    */
     oneOf: Schema[];
+    /**
+    * A user-facing placeholder value to use for the field. This can be used to provide an example of the expected
+    * input.
+    */
     placeholder?: string;
+    /**
+    * A unique id which can be used to refer to the schema.
+    */
     $id?: string;
+    /**
+    * A user-facing title for the schema.
+    */
     title?: string;
+    /**
+    * A user-facing description for the schema.
+    */
     description?: string;
+    /**
+    * An identifier which can be used to request the client use a particular UI control to represent this schema.
+    */
     control?: string;
+    /**
+    * The default value to use for this schema. This will be overridden by a value in the model of the
+    * [com.wise.dynamicflow.step.Step] if one is provided.
+    */
     default?: JsonElement;
+    /**
+    * If true, no UI will be shown to the user for this schema, but the corresponding data will still be submitted.
+    * Defaults to false.
+    */
     hidden?: boolean;
+    /**
+    * An icon which the client can use to represent this schema.
+    */
     icon?: Icon;
+    /**
+    * An image which the client can use to represent this schema.
+    */
     image?: Image;
+    /**
+    * A list of keywords that can be used when searching or filtering items in a [com.wise.dynamicflow.schema.OneOfSchema].
+    * Only applies when this schema is child schema in a [com.wise.dynamicflow.schema.OneOfSchema].
+    */
     keywords?: string[];
+    /**
+    * Configure how this schema will be summarised when included in an [ArraySchema].
+    */
     summary?: SummaryProvider;
+    /**
+    * An internal id which is attached to analytics events relating to the schema.
+    * It allows you to override $id during event emission, it is not user-facing and does not have to be unique within the step.
+    */
     analyticsId?: string;
-    refreshStepOnChange?: boolean;
-    alert?: AlertLayout;
-    help?: Help;
-    autocompleteHint?: AutocompleteToken[];
-    autofillKey?: string;
-    validationMessages?: Record<string, string>;
     /**
-    * @deprecated This property is deprecated
+    * When true, the step will be refreshed when the value of this schema changes.
     */
-    autofillProvider?: string;
+    refreshStepOnChange?: boolean;
     /**
-    * @deprecated Please use nested oneOf schemas instead.
+    * Configure an alert which will be displayed above the UI for this schema. This can be used to provide warnings or
+    * additional information to the user, but shouldn't be used for validation. For client-side validation please see
+    * the validation available on each schema type, or see [com.wise.dynamicflow.feature.ValidateAsync] and
+    * [com.wise.dynamicflow.feature.Action] for server-side validation.
     */
-    promoted?: boolean;
+    alert?: AlertLayout;
     /**
-    * @deprecated Please use 'refreshStepOnChange' instead
+    * Provide additional help information to the user.
     */
-    refreshFormOnChange?: boolean;
+    help?: Help;
     /**
-    * @deprecated Please use 'refreshUrl' in Step instead
+    * A list of tokens describing to the client what kind of field it is. This can enable the user agent or assistive
+    * technologies to automatically suggest or fill in information specific to the user.
+    * Values not recognised by the client will be discarded, and clients that only support single values will take the
+    * first supported value in the list.
     */
-    refreshUrl?: string;
+    autocompleteHint?: AutocompleteToken[];
     /**
-    * @deprecated Please use 'refreshUrl' in Step instead
+    * Identifies the type of data which the client can autofill for this schema. This is provided in a `.`
+    * delimited string, in the format `source.prop`, e.g `contact.email`. In this example, the client should
+    * suggest values from the `email` property on objects retrieved from the `contact` source to autofill
+    * this field.
+    * The only currently supported source is `contact`. It will inspect contacts from the native client address
+    * book (if available).
+    * Supported properties on the `contact` source are:
+    * - `givenName`
+    * - `familyName`
+    * - `fullName`
+    * - `email`
+    * - `firstLine`
+    * - `city`
+    * - `state`
+    * - `postalCode`
+    * - `countryCode`
     */
-    refreshFormUrl?: string;
+    autofillKey?: string;
     /**
-    * @deprecated OneOf Promotion is no longer supported
+    * An object where each property/value pair is the name of a validation property (e.g. maximum)
+    * to the user-facing error message to display if the validation fails.
     */
-    promotion?: JsonElement;
+    validationMessages?: Record<string, string>;
 };

package/build/next/schema/Schema.d.ts

@@ -8,4 +8,15 @@ import type { NumberSchema } from './NumberSchema';
 import type { ObjectSchema } from './ObjectSchema';
 import type { OneOfSchema } from './OneOfSchema';
 import type { StringSchema } from './StringSchema';
+/**
+* The data to be collected, its validation rules, and how it is presented to the user are defined through a subset of
+* [JSON Schema](https://json-schema.org/),
+* with some additional properties added to improve the user experience and functionality. Each form step contains an
+* array of schemas - typically there would only be one root schema but in order to support more layouts
+* it's possible to provide any number. These schemas are mapped to their corresponding input components to be presented to
+* the user, for example, a string schema would be mapped to a text input.
+* At submission time, the values entered for each root schema are merged and submitted to the endpoint
+* defined by the [com.wise.dynamicflow.feature.Action] the user has taken. In the case of any conflicting definitions,
+* schemas which appear later in the schemas array will overwrite any values from schemas earlier in the array.
+*/
 export type Schema = AllOfSchema | ArraySchema | BlobSchema | BooleanSchema | ConstSchema | IntegerSchema | NumberSchema | ObjectSchema | OneOfSchema | StringSchema;

package/build/next/schema/StringSchema.d.ts

@@ -9,70 +9,195 @@ import type { JsonElement } from '../JsonElement';
 import type { UploadSource } from '../feature/UploadSource';
 import type { AutocompleteToken } from '../misc/AutocompleteToken';
 import type { Help } from '../feature/Help';
+/**
+* Represents a string value in the submission.
+* This could be used for standard text input, or a format can be provided
+* to specify a particular type of string (e.g. a date).
+*/
 export type StringSchema = {
     type: 'string';
+    /**
+    * @deprecated This property is deprecated
+    */
+    autofillProvider?: string;
+    /**
+    * @deprecated Please use nested oneOf schemas instead.
+    */
+    promoted?: boolean;
+    /**
+    * @deprecated Please use 'refreshStepOnChange' instead
+    */
+    refreshFormOnChange?: boolean;
+    /**
+    * @deprecated Please use 'refreshUrl' in Step instead
+    */
+    refreshUrl?: string;
+    /**
+    * @deprecated Please use 'refreshUrl' in Step instead
+    */
+    refreshFormUrl?: string;
+    /**
+    * The type of data the string represents.
+    */
     format?: StringSchemaFormat;
+    /**
+    * An input mask where a * represents a user-input character. Only the user input is submitted, not the full string.
+    */
     displayFormat?: string;
+    /**
+    * A user-facing placeholder value to use for the field. This can be used to provide an example of the expected
+    * input.
+    */
     placeholder?: string;
+    /**
+    * The minimum length permitted for the value, if null then there is no minimum length. This is ignored if a format
+    * with a specific structure is provided (e.g. `date`).
+    */
     minLength?: number;
+    /**
+    * The maximum length permitted for the value, if null then there is no maximum length. This is ignored if a format
+    * with a specific structure is provided (e.g. `date`).
+    */
     maxLength?: number;
+    /**
+    * The minimum value permitted. If null then there is no minimum. This is used for formats with a specific structure
+    * (e.g. `date`).
+    */
     minimum?: string;
+    /**
+    * The maximum value permitted. If null then there is no maximum. This is used for formats with a specific structure
+    * (e.g. `date`).
+    */
     maximum?: string;
+    /**
+    * A regular expression that the value must match to be valid. This is ignored if a format with a specific
+    * structure is provided (e.g. `date`).
+    */
     pattern?: string;
+    /**
+    * A unique id which can be used to refer to the schema.
+    */
     $id?: string;
+    /**
+    * A user-facing title for the schema.
+    */
     title?: string;
+    /**
+    * A user-facing description for the schema.
+    */
     description?: string;
+    /**
+    * An identifier which can be used to request the client use a particular UI control to represent this schema.
+    */
     control?: string;
+    /**
+    * The default value to use for this schema. This will be overridden by a value in the model of the
+    * [com.wise.dynamicflow.step.Step] if one is provided.
+    */
     default?: string;
+    /**
+    * If true, no UI will be shown to the user for this schema, but the corresponding data will still be submitted.
+    * Defaults to false.
+    */
     hidden?: boolean;
+    /**
+    * If true, the UI for this schema will not accept input, but the corresponding data will still be submitted.
+    *  Defaults to false.
+    */
     disabled?: boolean;
+    /**
+    * An icon which the client can use to represent this schema.
+    */
     icon?: Icon;
+    /**
+    * An image which the client can use to represent this schema.
+    */
     image?: Image;
+    /**
+    * A list of keywords that can be used when searching or filtering items in a [com.wise.dynamicflow.schema.OneOfSchema].
+    * Only applies when this schema is child schema in a [com.wise.dynamicflow.schema.OneOfSchema].
+    */
     keywords?: string[];
+    /**
+    * Configure how this schema will be summarised when included in an [ArraySchema].
+    */
     summary?: SummaryProvider;
+    /**
+    * An internal id which is attached to analytics events relating to the schema.
+    * It allows you to override $id during event emission, it is not user-facing and does not have to be unique within the step.
+    */
     analyticsId?: string;
-    persistAsync?: PersistAsync;
-    refreshStepOnChange?: boolean;
-    validationAsync?: ValidateAsync;
-    validationMessages?: Record<string, string>;
-    alert?: AlertLayout;
-    autocompleteHint?: AutocompleteToken[];
-    autofillKey?: string;
-    help?: Help;
     /**
-    * @deprecated This property is deprecated
+    * @see PersistAsync
     */
-    autofillProvider?: string;
+    persistAsync?: PersistAsync;
     /**
-    * @deprecated Please use nested oneOf schemas instead.
+    * When true, the step will be refreshed when the value of this schema changes.
     */
-    promoted?: boolean;
+    refreshStepOnChange?: boolean;
     /**
-    * @deprecated Please use 'refreshStepOnChange' instead
+    * @see ValidateAsync
     */
-    refreshFormOnChange?: boolean;
+    validationAsync?: ValidateAsync;
     /**
-    * @deprecated Please use 'refreshUrl' in Step instead
+    * An object where each property/value pair is the name of a validation property (e.g. maximum)
+    * to the user-facing error message to display if the validation fails.
     */
-    refreshUrl?: string;
+    validationMessages?: Record<string, string>;
     /**
-    * @deprecated Please use 'refreshUrl' in Step instead
+    * Configure an alert which will be displayed above the UI for this schema. This can be used to provide warnings or
+    * additional information to the user, but shouldn't be used for validation. For client-side validation please see
+    * the validation available on each schema type, or see [com.wise.dynamicflow.feature.ValidateAsync] and
+    * [com.wise.dynamicflow.feature.Action] for server-side validation.
     */
-    refreshFormUrl?: string;
+    alert?: AlertLayout;
     /**
-    * @deprecated Please use 'persistAsync' with a 'BlobSchema' instead.
+    * Provide client-specific configuration for the camera capture experience.
     */
     cameraConfig?: JsonElement;
     /**
-    * @deprecated Please use 'persistAsync' with a 'BlobSchema' instead.
+    * Array of MIME types the field should accept. If null, any type of file is accepted.
+    * Wildcard MIME types are allowed, but support for them varies from platform to platform.
+    * Clients must support at least image, audio, and video.
+    * Any unrecognised MIME types will be ignored.
     */
     accepts?: string[];
     /**
-    * @deprecated Please use 'persistAsync' with a 'BlobSchema' instead.
+    * The maximum file size in bytes. If null, file size is unlimited.
     */
     maxSize?: number;
     /**
-    * @deprecated Please use 'persistAsync' with a 'BlobSchema' instead.
+    * Valid sources for the file. If null, any source is permitted.
     */
     source?: UploadSource;
+    /**
+    * A list of tokens describing to the client what kind of field it is. This can enable the user agent or assistive
+    * technologies to automatically suggest or fill in information specific to the user.
+    * Values not recognised by the client will be discarded, and clients that only support single values will take the
+    * first supported value in the list.
+    */
+    autocompleteHint?: AutocompleteToken[];
+    /**
+    * Identifies the type of data which the client can autofill for this schema. This is provided in a `.`
+    * delimited string, in the format `source.prop`, e.g `contact.email`. In this example, the client should
+    * suggest values from the `email` property on objects retrieved from the `contact` source to autofill
+    * this field.
+    * The only currently supported source is `contact`. It will inspect contacts from the native client address
+    * book (if available).
+    * Supported properties on the `contact` source are:
+    * - `givenName`
+    * - `familyName`
+    * - `fullName`
+    * - `email`
+    * - `firstLine`
+    * - `city`
+    * - `state`
+    * - `postalCode`
+    * - `countryCode`
+    */
+    autofillKey?: string;
+    /**
+    * Provide additional help information to the user.
+    */
+    help?: Help;
 };

package/build/next/schema/StringSchemaFormat.d.ts

@@ -1 +1,4 @@
+/**
+* Formats for string values
+*/
 export type StringSchemaFormat = 'date' | 'email' | 'numeric' | 'password' | 'phone-number' | 'base64url';

package/build/next/step/Step.d.ts

@@ -7,19 +7,14 @@ import type { Polling } from '../feature/Polling';
 import type { LinkHandler } from '../feature/LinkHandler';
 import type { StepError } from '../feature/StepError';
 import type { Navigation } from '../feature/Navigation';
+/**
+* A step represents a single screen in a flow. It is made up of schemas, which represent data to be collected from the
+* user, layouts which describe how the screen looks, and a number of advanced features to provide more complex
+* behaviours.
+* ### Step Response
+* A response is determined to be a Step when the status code is in the 200-299 range, the `exit` property in the triggering action was not set to `true`, and the `X-DF-Response-Type: step` header is provided.
+*/
 export type Step = {
-    id: string;
-    title: string;
-    schemas: Schema[];
-    layout: Layout[];
-    model?: JsonElement;
-    external?: External;
-    polling?: Polling;
-    linkHandlers?: LinkHandler[];
-    analytics?: Record<string, string>;
-    errors?: StepError;
-    navigation?: Navigation;
-    refreshUrl?: string;
     /**
     * @deprecated Please use 'id' instead
     */
@@ -40,4 +35,59 @@ export type Step = {
     * @deprecated Please use 'refreshUrl' instead
     */
     refreshFormUrl?: string;
+    /**
+    * An identifier which is added to analytics events as `stepId`.
+    */
+    id: string;
+    /**
+    * A user-facing title.
+    */
+    title: string;
+    /**
+    * An array of schemas describing the data for the user to input. Each root schemas which should be displayed to the
+    * user must be referenced by a [com.wise.dynamicflow.layout.FormLayout] in the `layout` property. If a schema is
+    * not referenced by a [com.wise.dynamicflow.layout.FormLayout], it won't be displayed, but it will still be submitted.
+    * On submission, the values corresponding to each element in the `schemas` array will be merged, as if they were contained in an
+    * [com.wise.dynamicflow.schema.AllOfSchema].
+    */
+    schemas: Schema[];
+    /**
+    * An array of layouts describing how the step should be structured.
+    */
+    layout: Layout[];
+    /**
+    * The data to use when initialising the step. It must follow the structure the schemas array describes, and any
+    * data which doesn't correspond to the schema is ignored.
+    */
+    model?: JsonElement;
+    /**
+    * Used to configure an app or web page to be opened when the step is first loaded.
+    */
+    external?: External;
+    /**
+    * Used to configure a polling behaviour, allowing the flow to progress automatically.
+    */
+    polling?: Polling;
+    /**
+    * Used to configure deep/universal link handling, allowing the flow to progress based on incoming redirects/links.
+    */
+    linkHandlers?: LinkHandler[];
+    /**
+    * Additional data to be included in analytics events. The keys/values in this object will be included in all events
+    * generated by clients.
+    */
+    analytics?: Record<string, string>;
+    /**
+    * Errors which will be shown when the step loads.
+    */
+    errors?: StepError;
+    /**
+    * Used to configure navigational behaviour of the step, for example to provide an
+    * [com.wise.dynamicflow.feature.Action] to perform when navigating back.
+    */
+    navigation?: Navigation;
+    /**
+    * The URL to use to fetch an updated step when the value of a schema marked refreshStepOnChange is updated.
+    */
+    refreshUrl?: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wise/dynamic-flow-types",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Dynamic Flow TypeScript Types",
   "license": "Apache-2.0",
   "repository": {
@@ -15,9 +15,9 @@
   ],
   "devDependencies": {
     "@formatjs/cli": "^6.2.7",
-    "esbuild": "0.20.1",
+    "esbuild": "0.20.2",
     "npm-run-all2": "5.0.2",
-    "ts-to-zod": "3.7.1",
+    "ts-to-zod": "3.7.3",
     "typescript": "4.9.5"
   },
   "peerDependencies": {},