AsyncChoicesInterfaceTypescript Type

Source
import type { AsyncChoicesInterface } from "@prestojs/viewmodel";
AsyncChoicesInterface<ItemType,ValueType>

Interface for asynchronous choices. If you wish to write a compatible class for use with asyncChoices you must conform to this interface. See AsyncChoices for a concrete implementation that is suitable for most cases.

A choice is a value that identifies the item (eg. an id) and a label that describes the item and is shown to users (eg. the name).

When multiple is true multiple values can be selected.

To define async choices two things are required:

  1. A function to resolve existing value(s). This is used when viewing existing value(s) and need label(s) to show (e.g. when displaying a choice on a detail view or rendering the value selected on a select widget).
  2. A function to list & filter the available choices. This is used when selecting a value (e.g. the options shown in a select widget).

Both of these functions may need to store state (eg. pagination for a listing) or access things from context (eg. read values from a cache). This can be done via two hooks - useListProps and useRetrieveProps. These functions should be called from a component or hook that deals with async choices when calling list and retrieve respectively. The return value from the hook is passed to the corresponding function.

See useAsyncChoices for a React hook to use async choices.

API

Methods

getChoices(items)
Source

Generate the list of choices. This can return an array of single choices or grouped choices.

A grouped choice is a 2 element Array with a label and a list of choices.

A single choice looks like:

const choice = {
  value: 1,
  label: "Item 1",
}

Grouped choices are an array of 2-tuples, the group label and choices for that label:

const choicesGrouped = [
  [
    "Group1",
    [
      { value: 1, label: "Item 1" },
      { value: 2, label: "Item 2" },
    ],
  ],
  ["Group 2", [{ value: 3, label: "Item 3" }]],
]

Arguments:

ArgumentTypeDescription
*itemsItemType[]

The items to extract choices from

Returns:(|[string, []])[]

Either an array of single choices or grouped choices.

getLabel(item)
Source

Get a label for an item

Arguments:

ArgumentTypeDescription
*itemItemType

The item to get a label for

Returns:ReactNode
getMissingLabel(value)
Source

Return label to use when an item can't be found. This can be used by widgets to control what is rendered when an item for a value cannot be found (eg. when it's deleted or when it's loading). The exact details of how this is used depend on the widget.

Arguments:

ArgumentTypeDescription
*valueValueType

The value to return the missing label for

Returns:ReactNode
getValue(item)
Source

Get the value to use for an item. The value should be unique and is what's used when a choice is selected (e.g. it's the value that would be saved to a database).

Arguments:

ArgumentTypeDescription
*itemItemType

The item to get the value for

Returns:ValueType
list(params)
Source

Function to resolve a list of choices based on the provided params.

What this function is passed depends on the implementation but when used with useAsyncChoices it will be passed query (the query object eg. to filter results with), paginator (the current paginator if any) and listOptions (any additional options passed on the listOptions prop to useAsyncChoices). Official presto widgets all use useAsyncChoices and so will use these parameters.

Arguments:

ArgumentTypeDescription
*paramsRecord

Construct a type with a set of properties K of type T

Returns:Promise
parseValue(value)
Source

Given a value parse it into the expected type.

For example, if the value comes in as a string (e.g. from a URL query parameter) then this could parse the value as a number so it matches the id returned from the server.

Arguments:

ArgumentTypeDescription
*valueany
Returns:ValueType
retrieve(value,?deps)
Source

Function to resolve specific values. This is used to know how to render the label for a value(s).

The first parameter is the value to retrieve (will be an array when multiple is true).

deps is the value returned by useRetrieveProps.

Arguments:

ArgumentTypeDescription
*valueValueType|ValueType[]

The value(s) to retrieve. If multiple is true this will be an array.

depsany
Returns:Promise
useListProps(args)
Source

Hook that returns any extra props to pass through to list in components/hooks that consume this (eg. useAsyncChoices). This is useful to store state for things like pagination.

What this function is passed depends on the implementation but when used with useAsyncChoices it will be query (the query object eg. to filter results with) and listOptions (any additional options passed on the listOptions prop to useAsyncChoices). Official presto widgets all use useAsyncChoices and so will use these parameters.

Arguments:

ArgumentTypeDescription
*argsany
Returns:any
useResolveItems<T>(item)
Source

Resolve the specific instance of an item to use. By default, this should just return item but can be used to resolve a specific instance of a class from a cache for example.

Arguments:

ArgumentTypeDescription
*itemT
Returns:T
useRetrieveProps(args)
Source

Hook that returns props to pass through to retrieve in components/hooks that consume this (eg. useAsyncChoices. This is useful for things like hooking into an existing cache (eg. useViewModelCache). The value returned here is passed as the second parameter to retrieve. In addition the existingValues key is passed through to useAsyncValue as the list of items it can resolve existing values from.

What this function is passed depends on the implementation but when used with useAsyncChoices it will be passed id if there's a current value and it's not an array, ids if there's a current value and it is an array, existingValues which is the values returned by list (may be null if list not yet called) and retrieveOptions (any additional options passed on the retrieveOptions prop to useAsyncChoices). Official presto widgets all use useAsyncChoices and so will use these parameters.

Arguments:

ArgumentTypeDescription
*argsany
Returns:any

Properties

multiple

Source
boolean

If true then multiple values can be selected. When this is true retrieve() will be passed and return an array rather than a single value.