@wise/dynamic-flow-types 2.26.0 → 2.27.0

package/build/next/feature/Action.d.ts

@@ -7,7 +7,6 @@ import type { JsonElement } from '../JsonElement';
 * the flow must end.
 * An endpoint can respond to a submitting action with an error status code and the standard error response format in order to display errors to the user.
 * ### Behavior
-* #### Non-Exiting Actions
 * If an action does not specify the `exit` property as true, it is expected that the action will submit the step payload.
 * For example, the following action is a non-exiting action.
 * ```kt
@@ -19,7 +18,6 @@ import type { JsonElement } from '../JsonElement';
 * #### Exiting Actions
 * If an action specifies `exit` as `true`, it is expected that this action should terminate the flow. For exiting actions,
 * the `url` property is optional.
-* #### Non-Submitting Exiting Actions
 * If the `url` property is not specified, when the action is taken the flow will be terminated and the value of the result
 * property will be used as the result of the flow.
 * ##### Example

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

@@ -12,7 +12,10 @@ export type ReviewLayoutField = {
     */
     value: string;
     /**
-    * The value without any formatting.
+    * The value of the field without any formatting applied. This can be used
+    * when you display a formatted value to the user, but want to provide an
+    * unformatted value to the client for other uses, for example when copying
+    * the value to the clipboard.
     */
     rawValue?: string;
     /**

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

@@ -8,6 +8,7 @@ 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.
+* If no items are entered, the value for submission is an empty array.
 */
 export type ArraySchemaList = {
     /**

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

@@ -7,6 +7,7 @@ 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.
+* As ordering needs to remain consistent, the submission value will include null values where applicable.
 * The minItems and maxItems validation has no purpose for a tuple, and should be ignored if provided.
 */
 export type ArraySchemaTuple = {

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

@@ -7,6 +7,7 @@ import type { AlertLayout } from '../layout/AlertLayout';
 import type { Help } from '../feature/Help';
 /**
 * Represents a boolean value in the submission.
+* The submission value is either `true` or `false`, defaulting to `false`.
 */
 export type BooleanSchema = {
     /**

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

@@ -8,6 +8,7 @@ import type { AutocompleteToken } from '../misc/AutocompleteToken';
 import type { Help } from '../feature/Help';
 /**
 * Represents a numeric value which must be a whole number. For floating point numbers, use a [NumberSchema] instead.
+* When not provided, the submission value is `null`.
 */
 export type IntegerSchema = {
     /**

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

@@ -9,6 +9,7 @@ import type { Help } from '../feature/Help';
 /**
 * Represents any numeric value - either an integer or a floating point number.
 * If the value should always be an integer, consider using an [IntegerSchema] instead.
+* When not provided, the submission value is `null`.
 */
 export type NumberSchema = {
     /**

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

@@ -6,6 +6,7 @@ import type { SummaryProvider } from '../feature/SummaryProvider';
 import type { AlertLayout } from '../layout/AlertLayout';
 /**
 * Represents an object value in the submission.
+* The value for submission includes only non-null property values. If all property values are null, the value is an empty object.
 * 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].

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

@@ -9,7 +9,72 @@ 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).
+* or alternative sections of a form (e.g. when the user can complete either a form in tab A or tab B).
+* ### Preselection
+* Sometimes you may want to load a step with an option selected - for example in order to retain the selected option
+* after a refresh.
+* To figure out which item to select, we look at the step model. Clients will first populate the form with the model, and
+* then inspect each oneOf option and compare them with the model to see which ones match. **If no options match, or if
+* multiple match, we will not select anything.**
+* This is the full matching algorithm:
+* ```ts
+* function isPartialMatch(optionValue, stepModel) {
+*   if (isArray(optionValue) && isArray(stepModel)) {
+*     return (
+*       optionValue.length === stepModel.length &&
+*       optionValue.every((value, index) => isPartialModelMatch(value, stepModel[index]))
+*     );
+*   }
+*   if (isObject(optionValue) && isObject(stepModel)) {
+*     // Don't look at properties with null values
+*     const nonNullishKeysInBoth = intersection(nonNullishKeys(optionValue), nonNullishKeys(stepModel));
+*     return (
+*       nonNullishKeysInBoth.length > 0 &&
+*       nonNullishKeysInBoth.every((key) => isPartialModelMatch(optionValue[key], stepModel[key]))
+*     );
+*   }
+*   return optionValue === stepModel;
+* };
+* ```
+* #### Caveats
+* Persisted fields are ignored, as are keys with nullish values.
+* #### Discriminators
+* If your oneOf options share schema property names, you will need to add a discriminator to ensure successful
+* preselection. For example - if the following example did **not** contain a const type discriminator and the step
+* model was `{ "name": "Jane" }`, we would not know which option to select, as both match. Conversely, if you remove
+* the name property from the schemas, the const discriminator would be unnecessary, as there would be no ambiguity. *
+* ```kt
+* schemas {
+*     obj {
+*         title = "Iban option"
+*         properties {
+*             const("type") {
+*                 value = JsonPrimitive("IBAN")
+*             }
+*             string("iban") {
+*                 title = "IBAN"
+*             }
+*             string("name") {
+*                 title = "Name"
+*             }
+*         }
+*     }
+*     obj {
+*         title = "Bic option"
+*         properties {
+*             const("type") {
+*                 value = JsonPrimitive("BIC")
+*             }
+*             string("bic") {
+*                 title = "BIC"
+*             }
+*             string("name") {
+*                 title = "Name"
+*             }
+*         }
+*     }
+* }
+* ```
 */
 export type OneOfSchema = {
     /**

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

@@ -18,5 +18,11 @@ import type { StringSchema } from './StringSchema';
 * 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.
+* When building submission values from schemas a few rules apply depending on the schema type.
+* - Primitive schemas ([com.wise.dynamicflow.schema.IntegerSchema], [com.wise.dynamicflow.schema.NumberSchema], [com.wise.dynamicflow.schema.StringSchema]) will submit `null` if they contain no value.
+*   - A [com.wise.dynamicflow.schema.BooleanSchema] will always submit `true` or `false`, never `null`.
+*   - Clients consider an empty string equivalent to having no value for a [com.wise.dynamicflow.schema.StringSchema].
+* - An [com.wise.dynamicflow.schema.ObjectSchema] will always submit a JSON Object. Properties that have a value of `null` are ignored.
+* - An [com.wise.dynamicflow.schema.ArraySchema] will always submit a JSON Array.
 */
 export type Schema = AllOfSchema | ArraySchema | BlobSchema | BooleanSchema | ConstSchema | IntegerSchema | NumberSchema | ObjectSchema | OneOfSchema | StringSchema;

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

@@ -13,6 +13,7 @@ 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).
+* When not provided, the submission value is `null`.
 */
 export type StringSchema = {
     type: 'string';

package/build/renderers/ReviewRendererProps.d.ts

@@ -11,8 +11,11 @@ export type ReviewField = {
     help?: string;
     label: string;
     value: string;
+    rawValue?: string;
 };
 export type ReviewCallToAction = {
+    accessibilityDescription?: string;
+    href?: string;
     title: string;
     onClick: () => void;
 };

package/build/spec/LayoutComponent.d.ts

@@ -200,6 +200,7 @@ export type ReviewLayout = {
     callToAction?: {
         title: string;
         action: Action;
+        behavior?: Behavior;
     };
 };
 export type SearchLayout = SearchConfig & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wise/dynamic-flow-types",
-  "version": "2.26.0",
+  "version": "2.27.0",
   "description": "Dynamic Flow TypeScript Types",
   "license": "Apache-2.0",
   "repository": {