Types
Every other public type, grouped as the contracts define them, with the page that uses it.
On this page
The package exports its TypeScript contracts from the root: import type { … } from '@cloudlet/toast'. The types of the factory, the controller and the Toaster are on their own pages; this page covers the rest, grouped as in the contracts, and links each type to the page where it is used. Core types take a Slot parameter for rich content; the React… aliases at the end fix it to ReactNode.
Identity
Handles and tokens are capabilities minted by the controller. They are never built by hand, compared across controllers or stored across reloads.
| Type | Definition | Description |
|---|---|---|
NotificationHandle | { id, controller, generation } | One appearance of a notification, returned by show and track. Pass it to update and dismiss. Not a serializable ID: keep the id string for that. |
ControllerIdentity | opaque string | Which controller minted a handle; ControllerSnapshot.controller. |
Generation | opaque string | Which appearance of an ID a handle belongs to; a reused ID gets a new generation. |
OperationAttemptToken | opaque string | One attempt of a tracked operation; see track. |
ActionAttemptToken | opaque string | One run of a command action; see PrimaryAction. |
Unsubscribe | () => void | Returned by subscribe and onEvent. Calling it again is harmless. |
HandleRejection | 'invalid-handle' | 'foreign-controller' | 'stale-handle' | Why a handle was refused; part of MutationRejection and FocusResult. |
InputIssue | { path: string; message: string } | One invalid field of a rejected show, update or track. |
Notifications
| Type | Definition | Used on |
|---|---|---|
NotificationKind | 'info' | 'success' | 'loading' | 'warning' | 'error' | show, Notifications & time |
Priority | 'normal' | 'high' | show, track: record metadata that does not reorder the stack. |
AnnouncementPriority | 'polite' | 'assertive' | 'off' | show, Labels & announcements |
Duration | number | null | show: readable milliseconds ≥ 0, or null to stay until closed. |
Attention | 'auto' | 'open' | 'stack' | show, Positioning & offsets |
NotificationContent | title, description?, icon?, progress?, action?, announcementPriority?, duration?, attention? | What a notification shows; the content of track's pending, success, error and cancelled. |
NotificationSpec | NotificationContent and id?, kind?, priority?, dedupeKey?, onClose? | show |
NotificationPatch | the changeable fields, null removes | update |
AdmissionResult, AdmissionRejection | created, deduplicated or rejected | show |
OperationAdmissionResult | AdmissionResult without deduplicated | OperationHandle.admission |
OverflowSnapshot | { count, pending } | onOverflow, ControllerSnapshot.overflow |
Description
Description<Slot>, the text under the title:
| Variant | Fields | Description |
|---|---|---|
{ kind: 'text' } | text: string | Plain text; may be empty. |
{ kind: 'rich' } | content: Slot, announcement: string | Your own non-interactive content (a ReactNode), and the non-empty text screen readers hear instead of it. Buttons and links belong in the action. |
Progress
Progress, a ring around the icon:
| Variant | Fields | Description |
|---|---|---|
{ kind: 'indeterminate' } | label?: string | Work of unknown length. |
{ kind: 'determinate' } | value: number, label?: string | value is finite, from 0 to 1; out-of-range values are rejected, not clamped. label names the progress for assistive technology. |
PrimaryAction
PrimaryAction is a CommandAction, a NavigationAction or a FormAction; a notification has at most one. Operations & cancellation shows both.
CommandAction runs your function:
| Prop | Type | Default | Description |
|---|---|---|---|
kind | 'command' | — | Required. |
label | string | — | Required, non-empty. The button text. |
run | (context: ActionContext) => unknown | — | Required. May return a value, nothing or a promise. While it runs the button is pending and a second press is refused; success closes the notification (action-success), failure keeps it with a message and allows another try. |
errorMessage | (error: unknown) => string | messages.actionError | Turns a failure into the message shown on the card. |
ActionContext is passed to run: handle, the notification's NotificationHandle, and token, the ActionAttemptToken of this run.
NavigationAction is a real link:
| Prop | Type | Default | Description |
|---|---|---|---|
kind | 'link' | — | Required. |
label | string | — | Required, non-empty. The link text. |
href | string | — | Required. Relative and fragment URLs, http:, https:, mailto: and tel:; other schemes are rejected. |
target | '_self' | '_blank' | '_parent' | '_top' | — | Where it opens. _blank always gets noopener. |
rel | string | — | Your rel; noopener is added to it, never replacing it. |
Following the link closes the notification with the reason navigation; modifier keys and new tabs behave as for any link.
FormAction puts one to three fields in the Island and submits them like a command:
| Prop | Type | Default | Description |
|---|---|---|---|
kind | 'form' | — | Required. |
fields | readonly FormField[] | — | Required, one to three, with unique names. |
label | string | — | Required, non-empty. The submit button's accessible name. |
run | (context: FormContext) => unknown | — | Required. Called with the values once they pass the checks; pending, success and failure work as for a command. |
errorMessage | (error: unknown) => string | messages.actionError | Turns a failure into the message under the form. |
validate | (values: FormValues) => FormValidation | — | Runs on submit after required and maxLength. |
FormField describes one field:
| Prop | Type | Default | Description |
|---|---|---|---|
name | string | — | Required. The key of its value in FormValues. |
kind | FormFieldKind | — | Required: 'text' for one line, 'textarea' for several. |
label | string | — | Required. Read by screen readers; also the placeholder when there is none. |
placeholder | string | label | The hint inside the empty field. |
defaultValue | string | '' | The starting value; not longer than maxLength. |
required | boolean | false | An empty value, or only spaces, stops the submit with messages.fieldRequired. |
maxLength | number | — | A positive integer; a longer value stops the submit with messages.fieldTooLong. |
autoComplete | string | — | The field's autocomplete. |
inputMode | FormInputMode | — | The on-screen keyboard: 'text', 'email', 'numeric', 'decimal', 'tel', 'url' or 'search'. |
FormValues maps each field name to its text, as typed. TypeScript takes the names from fields, so values.reply is a string and a misspelt name does not compile. FormContext is the ActionContext plus values. FormValidation is what validate returns: true to submit, a string for a message under the form, or messages keyed by field name.
CloseReason
CloseNotice is what onClose receives: handle and reason, a CloseReason:
| Reason | Closed by |
|---|---|
'timeout' | Its readable time ran out. |
'programmatic' | dismiss(handle). |
'close-button' | The user pressed close. |
'swipe' | The user swiped the pill away. |
'action-success' | Its command action succeeded. |
'navigation' | Its link was followed. |
'clear' | clear(). |
'clear-button' | The user pressed the Island's clear button twice. |
'dispose' | dispose(). |
Operations
| Type | Definition | Used on |
|---|---|---|
OperationSource<T> | PromiseLike<T> | OperationFactory<T> | track |
OperationFactory<T, Signal> | (context: OperationContext<Signal>) => T | PromiseLike<T> | track: called once per attempt. |
OperationContext<Signal> | { signal, token, attempt } | The factory's argument: this attempt's signal, its OperationAttemptToken and its number from 1. |
OperationStatus | 'pending' | 'fulfilled' | 'rejected' | 'cancelled' | OperationSnapshot |
OperationSnapshot | the current attempt's state | OperationHandle.getSnapshot |
OperationAttempt<T> | { token, attempt, result } | Returned for each new attempt by retry and restart. |
OperationHandle<T> | the first attempt plus commands | track |
AttemptStartResult<T>, CancelResult | results of retry/restart and cancel | OperationHandle |
TrackOptions<T, Slot, Signal> | the options of track | track |
CancellationSignal is the minimal abort port the core needs, so it runs without the DOM. A native AbortSignal implements it, and the React controller gives factories a real AbortSignal.
| Member | Type | Description |
|---|---|---|
aborted | boolean | Cancellation was requested. |
reason | unknown | The reason passed to cancel. |
throwIfAborted | () => void | Throws the reason if aborted. |
addEventListener | (type: 'abort', listener, options?) => void | Listens for the request; { once: true } is supported. |
removeEventListener | (type: 'abort', listener) => void | Stops listening. |
Snapshots
| Type | Definition | Used on |
|---|---|---|
ControllerSnapshot | the whole state | getSnapshot |
IslandSnapshot | { open, reason, current } | ControllerSnapshot.island; reason and current are null exactly when closed. |
IslandReason | 'user' | 'attention' | Whether the user opened the Island or a notification needing attention did. |
NotificationLocation | 'stack' | 'current' | current is the one presented notification: the pill, or the Island's slide. |
NotificationSnapshot
One notification in ControllerSnapshot.notifications, also passed to the announcement formatters.
| Field | Type | Description |
|---|---|---|
handle | NotificationHandle | Its handle. |
kind | NotificationKind | Its current kind. |
content | NotificationContent | What it shows. |
priority | Priority | Its metadata priority. |
occurrences | number | 1, plus each deduplicated repeat. |
location | NotificationLocation | 'current' when presented, otherwise 'stack'. |
remainingMs | number | null | Readable time left when the snapshot was taken (it does not tick); null when it stays until closed. |
pauseReasons | readonly PauseReason[] | Why its time is not running; empty while it runs. |
operation | OperationSnapshot | null | The tracked operation, or null for a plain notification. |
action | ActionSnapshot | The state of its command or form action. |
draft | boolean | A form whose values differ from their defaults. The values themselves stay inside Cloudlet. |
ActionSnapshot is { status: 'idle' }, { status: 'pending', token } while a command runs, or { status: 'failed', token, message } after it failed.
PauseReason, the reasons a notification's time stands still; time runs only when there are none:
| Reason | Meaning |
|---|---|
'inactive' | It is not the presented notification. |
'no-host' | No Toaster is attached. |
'presentation-pending' | It is about to be shown and is not readable yet. |
'hover' | The pointer is over the notifications. |
'focus' | Keyboard focus is inside the notifications. |
'gesture' | A swipe is in progress. |
'action-pending' | Its command action is running. |
'content-transition' | Its content is being swapped on screen. |
'island' | It is the Island's slide and the user opened the Island, or it asks for action. |
'draft' | Its form holds text that was not sent. |
'document-hidden' | The tab is hidden. |
'window-blur' | The window lost focus. |
Events
| Type | Definition | Used on |
|---|---|---|
SemanticEvent | EventBase and one variant per type | onEvent |
EventBase | { controller, sequence, at } | The fields every event has. |
Diagnostic | { code, source, message, handle?, error? } | onDiagnostic, the diagnostic event |
DiagnosticCode | 'invalid-input' | 'second-host' | … | onDiagnostic |
Controller
| Type | Used on |
|---|---|
CloudletController<Slot, Signal> | Controller: the generic controller. |
NotificationController<Slot> | Controller: the controller without track. |
ControllerOptions, FallbackMessages | createCloudlet |
MutationResult, MutationRejection | update, dismiss, acknowledgeOverflow |
ClearResult | clear |
FocusTarget, FocusResult | requestFocus |
React
The React entry fixes Slot to ReactNode and Signal to AbortSignal:
| Type | Equals | Used on |
|---|---|---|
ReactCloudletController | CloudletController<ReactNode, AbortSignal> | createCloudlet, useCloudlet, useOptionalCloudlet |
ReactNotificationSpec | NotificationSpec<ReactNode> | show |
ReactNotificationPatch | NotificationPatch<ReactNode> | update |
ReactTrackOptions<T> | TrackOptions<T, ReactNode, AbortSignal> | track |
ReactOperationFactory<T> | OperationFactory<T, AbortSignal> | track |
ReactOperationContext | OperationContext<AbortSignal> | track |
CreateCloudlet | (options?: ControllerOptions) => ReactCloudletController | createCloudlet |
CloudletProviderComponent, UseCloudlet, UseOptionalCloudlet, ToasterComponent | the signatures of the two components and the two hooks | Toaster props |
ToasterProps, ToasterOffsets, EdgeInsets, ToasterAttention, ToasterMotion, CloudletPart | the Toaster's props | Toaster props |
CloudletMotionConstants, CloudletMotionOverrides, CloudletSpring, CloudletTimedSpring | the motion debugging channel | ToasterMotion |
CloudletLabels, AnnouncementFormatters | the Toaster's texts | Labels & announcements |
CloudletProviderProps | the provider's props | CloudletProvider |