@wise/dynamic-flow-types 2.7.0 → 2.9.0

package/build/next/layout/SearchLayout.d.ts

@@ -1,12 +1,41 @@
 import type { HttpMethod } from '../misc/HttpMethod';
 import type { Size } from '../misc/Size';
+/**
+* Displays a search input field, which performs a search and returns a [com.wise.dynamicflow.responses.search.SearchResult].
+* Results are actions or further searches.
+*/
 export type SearchLayout = {
+    /**
+    * It must be `search`.
+    */
     type: 'search';
+    /**
+    * A title to be displayed as a label for the search field.
+    */
     title: string;
+    /**
+    * The HTTP method to use for the request.
+    */
     method: HttpMethod;
+    /**
+    * The URL for the request. Either absolute or relative to the base URL of the flow.
+    */
     url: string;
+    /**
+    * The name of the parameter to place the search term under.
+    * If the method is GET, this will be included as a query parameter, otherwise, this will be a property of the JSON object in the request body.
+    */
     param: string;
+    /**
+    * A markdown message which the client should display if the results array is empty.
+    */
     emptyMessage?: string;
+    /**
+    * Specify a particular control to use to represent the layout. If the control is unknown, it will be ignored.
+    */
     control?: string;
+    /**
+    * The vertical margin to apply above this component. Defaults to `md`.
+    */
     margin?: Size;
 };

package/build/next/layout/StatusListLayout.d.ts

@@ -1,9 +1,27 @@
 import type { StatusListLayoutItem } from './StatusListLayoutItem';
 import type { Size } from '../misc/Size';
+/**
+* A list of items with statuses.
+*/
 export type StatusListLayout = {
+    /**
+    * It must be `status-list`.
+    */
     type: 'status-list';
+    /**
+    * Array of items.
+    */
     items: StatusListLayoutItem[];
+    /**
+    * The user-facing title.
+    */
     title?: string;
+    /**
+    * Specify a particular control to use to represent the layout. If the control is unknown, it will be ignored.
+    */
     control?: string;
+    /**
+    * The vertical margin to apply above this component. Defaults to `md`.
+    */
     margin?: Size;
 };

package/build/next/layout/StatusListLayoutItem.d.ts

@@ -1,8 +1,23 @@
 import type { Icon } from '../misc/Icon';
 import type { StatusListLayoutStatus } from './StatusListLayoutStatus';
+/**
+* A single entry in a [StatusListLayout].
+*/
 export type StatusListLayoutItem = {
+    /**
+    * A user-facing title.
+    */
     title: string;
+    /**
+    * A user-facing description.
+    */
     description?: string;
+    /**
+    * An icon to represent the item.
+    */
     icon: Icon;
+    /**
+    * The status of the item, if it has one.
+    */
     status?: StatusListLayoutStatus;
 };

package/build/next/layout/StatusListLayoutStatus.d.ts

@@ -1 +1,4 @@
+/**
+* Represents the state of an item in a [StatusListLayout].
+*/
 export type StatusListLayoutStatus = 'not-done' | 'pending' | 'done';

package/build/next/misc/Align.d.ts

@@ -1 +1,4 @@
+/**
+* An enum describing how the content of a layout should be aligned.
+*/
 export type Align = 'left' | 'center' | 'right';

package/build/next/misc/AutocompleteToken.d.ts

@@ -1 +1,8 @@
+/**
+* A token which can be used in an autocomplete hint to tell clients what kind of data is expected. This can enable the
+* user agent or assistive technologies to automatically suggest or fill in information specific to the user.
+* Please note that not all values will work on all platforms. For the most benefit, it is helpful to combine controls
+* with autocomplete hint - i.e a common pattern is to have password control on string schemas that can be combined
+* with `PASSWORD` or `NEW_PASSWORD` autocomplete hints for the best possible user experience.
+*/
 export type AutocompleteToken = 'on' | 'name' | 'name-prefix' | 'given-name' | 'additional-name' | 'family-name' | 'name-suffix' | 'nickname' | 'email' | 'username' | 'new-username' | 'new-password' | 'password' | 'one-time-code' | 'job-title' | 'organization-name' | 'full-street-address' | 'street-address-line-1' | 'street-address-line-2' | 'street-address-line-3' | 'address-level-1' | 'address-level-2' | 'address-level-3' | 'address-level-4' | 'country-code' | 'country-name' | 'postal-code' | 'credit-card-name' | 'credit-card-given-name' | 'credit-card-middle-name' | 'credit-card-family-name' | 'credit-card-number' | 'credit-card-expiration' | 'credit-card-expiration-month' | 'credit-card-expiration-year' | 'credit-card-security-code' | 'credit-card-type' | 'transaction-currency' | 'transaction-amount' | 'language' | 'birthdate' | 'birthdate-day' | 'birthdate-month' | 'birthdate-year' | 'gender' | 'phone-number' | 'phone-country-code' | 'phone-national' | 'phone-area-code' | 'phone-local' | 'phone-local-prefix' | 'phone-local-suffix' | 'phone-extension' | 'url' | 'photo' | 'impp' | 'shipping' | 'billing' | 'home' | 'work' | 'mobile' | 'fax' | 'pager';

package/build/next/misc/Context.d.ts

@@ -1 +1,6 @@
+/**
+* An enum describing the sentiment of a layout component, typically used to apply variations on a layout style.
+* The specific meaning of these values is dependent on the client and it's possible that multiple values may be
+* mapped to the same style in some implementations.
+*/
 export type Context = 'positive' | 'neutral' | 'warning' | 'negative' | 'success' | 'failure' | 'info' | 'primary';

package/build/next/misc/HttpMethod.d.ts

@@ -1 +1,4 @@
+/**
+* An enum describing which HTTP verb to be used.
+*/
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';

package/build/next/misc/Icon.d.ts

@@ -1,3 +1,6 @@
 import type { IconNamed } from './IconNamed';
 import type { IconText } from './IconText';
+/**
+* Client-side icons based on well-known names or text content.
+*/
 export type Icon = IconNamed | IconText;

package/build/next/misc/IconNamed.d.ts

@@ -1,3 +1,10 @@
+/**
+* A named icon.
+*/
 export type IconNamed = {
+    /**
+    * The name of the icon that is known and can be rendered by the client. An icon name is typically the
+    * equivalent to the icon identifier in many design systems.
+    */
     name: string;
 };

package/build/next/misc/IconText.d.ts

@@ -1,3 +1,9 @@
+/**
+* A textual icon.
+*/
 export type IconText = {
+    /**
+    * The text to be used to generate the icon (e.g. initials for an avatar)
+    */
     text: string;
 };

package/build/next/misc/Image.d.ts

@@ -1,10 +1,17 @@
+/**
+* Images fetched from URLs.
+*/
 export type Image = {
-    url: string;
     /**
     * @deprecated Please use 'accessibilityDescription' instead
     */
     text?: string;
     /**
+    * The URL to use to fetch the image.
+    */
+    url: string;
+    /**
+    * A description of the content of the image to be used by screen readers.
     * @experimental This feature may be changed in the future without notice.
     */
     accessibilityDescription?: string;

package/build/next/misc/Size.d.ts

@@ -1 +1,7 @@
+/**
+* An enum describing a size in generic terms.
+* The size enum is used to describe sizes in multiple situations - for example margin, image, and heading sizes. The
+* specific meaning of these values is dependent on the client, and it is possible that multiple values may be mapped to
+* the same size in some implementations.
+*/
 export type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl';

package/build/next/responses/action/ActionResponseBody.d.ts

@@ -1,4 +1,15 @@
 import type { Action } from '../../feature/Action';
+/**
+* Represents an action response body.
+* A response is determined to be an Action 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: action` header is provided.
+* When this response is received, the client performs the provided action. When doing so the client doesn't run any
+* validation and no additional data from the step is included in the submission - any submission data must
+* be provided in the action's `data` property. See [com.wise.dynamicflow.feature.Action].
+*/
 export type ActionResponseBody = {
+    /**
+    * The action to perform when this response is received.
+    */
     action: Action;
 };

package/build/next/responses/error/ErrorResponseBody.d.ts

@@ -1,14 +1,58 @@
 import type { JsonElement } from '../../JsonElement';
+/**
+* Represents an error response body.
+* A response is determined to be an error when the status code of a response is outside of the 200-299 range.
+*/
 export type ErrorResponseBody = {
-    error?: string;
-    validation?: JsonElement;
-    refreshUrl?: string;
     /**
     * @deprecated Please use 'refreshUrl' instead
     */
     refreshFormUrl?: string;
     /**
+    * Additional data to be included in any analytics events generated by clients for this error.
     * @experimental This feature may be changed in the future without notice.
     */
     analytics?: Record<string, string>;
+    /**
+    * A user-facing, general error message, not related to any particular schema.
+    */
+    error?: string;
+    /**
+    * Error messages related to specific fields. The structure of this value must match the structure of the data
+    * to be validated.
+    * For example, given the following model:
+    * ```
+    * {
+    *   "name": "A Person",
+    *   "bankDetails": {
+    *     "accountNumber": "31510604",
+    *     "sortCode": "100000"
+    *   }
+    * }
+    * ```
+    * A validation message for the "sortCode" field would be provided as follows:
+    * ```
+    * {
+    *   "bankDetails": {
+    *     "sortCode": "Please enter a valid sort code"
+    *   }
+    * }
+    * ```
+    * Multiple validation messages can be returned at once, for example:
+    * ```
+    * {
+    *   "name": "Please enter a full name",
+    *   "bankDetails": {
+    *     "sortCode": "Please enter a valid sort code"
+    *   }
+    * }
+    * ```
+    */
+    validation?: JsonElement;
+    /**
+    * If present, the client will refresh the step using the given URL. Any errors also present in the response should
+    * be applied to the refreshed step.
+    * See [com.wise.dynamicflow.feature.RefreshOnChange].
+    */
+    refreshUrl?: string;
 };

package/build/next/responses/search/SearchResponseBody.d.ts

@@ -1,4 +1,10 @@
 import type { SearchResult } from './SearchResult';
+/**
+* Represents the result of a search. See [com.wise.dynamicflow.layout.SearchLayout].
+*/
 export type SearchResponseBody = {
+    /**
+    * A list of results.
+    */
     results: SearchResult[];
 };

package/build/next/responses/search/SearchResult.d.ts

@@ -1,3 +1,6 @@
 import type { SearchResultAction } from './SearchResultAction';
 import type { SearchResultSearch } from './SearchResultSearch';
+/**
+* Represents a single entry in a [SearchResponseBody].
+*/
 export type SearchResult = SearchResultAction | SearchResultSearch;

package/build/next/responses/search/SearchResultAction.d.ts

@@ -1,11 +1,32 @@
 import type { Icon } from '../../misc/Icon';
 import type { ImageLayout } from '../../layout/ImageLayout';
 import type { Action } from '../../feature/Action';
+/**
+* A search result which contains an [com.wise.dynamicflow.feature.Action] to perform when the result is selected.
+*/
 export type SearchResultAction = {
+    /**
+    * It must be `action`.
+    */
     type: 'action';
+    /**
+    * The user-facing title.
+    */
     title: string;
+    /**
+    * The user-facing description.
+    */
     description?: string;
+    /**
+    * An icon representing the result.
+    */
     icon?: Icon;
+    /**
+    * An image representing the result.
+    */
     image?: ImageLayout;
+    /**
+    * The action to perform when the option is selected.
+    */
     value: Action;
 };

package/build/next/responses/search/SearchResultSearch.d.ts

@@ -1,11 +1,33 @@
 import type { Icon } from '../../misc/Icon';
 import type { ImageLayout } from '../../layout/ImageLayout';
 import type { SearchSearchRequest } from './SearchSearchRequest';
+/**
+* A search result which contains another search to be performed when selected. Can be used to provide groups of
+* results or simple pagination.
+*/
 export type SearchResultSearch = {
+    /**
+    * It must be `search`.
+    */
     type: 'search';
+    /**
+    * The user-facing title.
+    */
     title: string;
+    /**
+    * The user-facing description.
+    */
     description?: string;
+    /**
+    * An icon representing the result.
+    */
     icon?: Icon;
+    /**
+    * An image representing the result.
+    */
     image?: ImageLayout;
+    /**
+    * A search configuration to used when the option is selected.
+    */
     value: SearchSearchRequest;
 };

package/build/next/responses/search/SearchSearchRequest.d.ts

@@ -1,7 +1,24 @@
 import type { HttpMethod } from '../../misc/HttpMethod';
+/**
+* A search request.
+*/
 export type SearchSearchRequest = {
+    /**
+    * The URL for the request. Either absolute or relative to the base URL of the flow.
+    */
     url: string;
+    /**
+    * The HTTP method to use for the request.
+    */
     method: HttpMethod;
+    /**
+    * The name of the parameter to place the search term under.
+    * If the HTTP method allows a request body this will be the property name to use in the request body JSON object.
+    * If the HTTP method does not allow a request body, this will be included as a query parameter.
+    */
     param: string;
+    /**
+    * The value of the query.
+    */
     query: string;
 };

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

@@ -3,22 +3,74 @@ import type { Icon } from '../misc/Icon';
 import type { Image } from '../misc/Image';
 import type { SummaryProvider } from '../feature/SummaryProvider';
 import type { AlertLayout } from '../layout/AlertLayout';
+/**
+* A schema which merges the value of its child schemas.
+* Use an allOf schema to represent a form section where the submission payload is the result of merging the allOf's child schemas.
+* This can be useful if you need to have one object in your submission payload, but want to split the properties into two or more sections.
+*/
 export type AllOfSchema = {
+    /**
+    * 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;
+    /**
+    * The child schemas of the allOf. The values of these schemas will be merged from first to last to create the
+    * submission value.
+    */
     allOf: Schema[];
+    /**
+    * 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;
+    /**
+    * 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;
-    alert?: AlertLayout;
     /**
-    * @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;
 };

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

@@ -1,3 +1,9 @@
 import type { ArraySchemaList } from './ArraySchemaList';
 import type { ArraySchemaTuple } from './ArraySchemaTuple';
+/**
+* Represents an array of data in the submission.
+* Arrays are either a list or a tuple:
+* - A list is a set of fields which can be repeated a number of times, with each set being an element in the array.
+* - A tuple is a fixed set of fields, where each field corresponds to an element in the array.
+*/
 export type ArraySchema = ArraySchemaList | ArraySchemaTuple;

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

@@ -5,29 +5,100 @@ import type { SummarySummariser } from '../feature/SummarySummariser';
 import type { PersistAsync } from '../feature/PersistAsync';
 import type { ValidateAsync } from '../feature/ValidateAsync';
 import type { AlertLayout } from '../layout/AlertLayout';
+/**
+* A variable length array where each item matches the items JSON schema. This can be used, for example, to create a
+* repeating form section, or multi-file upload.
+*/
 export type ArraySchemaList = {
+    /**
+    * It must be `array`.
+    */
     type: 'array';
+    /**
+    * @deprecated Please use nested oneOf schemas instead.
+    */
+    promoted?: boolean;
+    /**
+    * A unique id which can be used to refer to the schema.
+    */
     $id?: string;
+    /**
+    * A schema which describes the structure of each array element.
+    */
     items: Schema;
+    /**
+    * The title for the add a new item, and the title for the screen to enter the item info.
+    */
     addItemTitle: string;
+    /**
+    * The title for the screen to edit the item info.
+    */
     editItemTitle: string;
+    /**
+    * The minimum number of items in the array.
+    */
     minItems?: number;
+    /**
+    * The maximum number of items in the array.
+    */
     maxItems?: number;
+    /**
+    * 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?: SummarySummariser;
+    /**
+    * 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;
+    /**
+    * @see PersistAsync
+    */
     persistAsync?: PersistAsync;
+    /**
+    * @see ValidateAsync
+    */
     validationAsync?: ValidateAsync;
+    /**
+    * 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.
+    */
     alert?: AlertLayout;
-    validationMessages?: Record<string, string>;
     /**
-    * @deprecated Please use nested oneOf schemas 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.
     */
-    promoted?: boolean;
+    validationMessages?: Record<string, string>;
 };

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

@@ -5,24 +5,79 @@ import type { SummaryProvider } from '../feature/SummaryProvider';
 import type { PersistAsync } from '../feature/PersistAsync';
 import type { ValidateAsync } from '../feature/ValidateAsync';
 import type { AlertLayout } from '../layout/AlertLayout';
+/**
+* A fixed-length array where each schema represents the data at the corresponding element in the array.
+* The minItems and maxItems validation has no purpose for a tuple, and should be ignored if provided.
+*/
 export type ArraySchemaTuple = {
+    /**
+    * It must be `array`.
+    */
     type: 'array';
+    /**
+    * @deprecated Please use nested oneOf schemas instead.
+    */
+    promoted?: boolean;
+    /**
+    * A unique id which can be used to refer to the schema.
+    */
     $id?: string;
+    /**
+    * An array of schemas which define each element that appears in this array.
+    */
     items: Schema[];
+    /**
+    * 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;
+    /**
+    * 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;
+    /**
+    * @see PersistAsync
+    */
     persistAsync?: PersistAsync;
+    /**
+    * @see ValidateAsync
+    */
     validationAsync?: ValidateAsync;
-    alert?: AlertLayout;
     /**
-    * @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;
 };