Pages and dot API

Your dot is written in two functions, definePage and defineDot, and a page reaches everything else through this. Both functions are available everywhere in a dot, no import needed.

Keep in mind:

Up to 16 pages can be open at once. Opening one more fails. Use replace or back to keep the stack short.
The first page never closes. Going back from it closes the dot.
Launch options, the data you hand a page as you open it, are always strings.

The Pages and state and Navigation guides show all of this in use.

definePage

Each page's controller.ts exports definePage({ ... }). A mutation is a function (state, event) => changes that returns the parts of the state that change. An action is a function (state, event) that can be async, call Dash and navigate, and changes the state with this.setState().

TypeScript

export default definePage({ initialState, hooks, mutations, actions, configs })

`PageOptions`

Member	Type	What it is
`initialState`	`object`	The data the page starts with, usually the default export of its `state.ts`. Plain JSON data only.
`configs` (optional)	`PageConfigs`	Dash's bars and the page's colors, on top of `defineDot`'s `configs`. See `PageConfigs`.
`share` (optional)	`PageShare`	Which share links can open this page. See `PageShare`.
`hooks` (optional)	`PageHooks`	Functions Dash runs as the page opens, shows, hides, closes and refreshes. See `PageHooks`.
`mutations` (optional)	`object`	Handlers that return what changes in the state, by name.
`actions` (optional)	`object`	Handlers that can be async, call Dash, navigate and set the state, by name.

`PageHooks`

Member	Type	What it is
`onLoad(options)`	Function	The page opens. `options` are the launch options the opening page passed, all strings.
`onShow()`	Function	The page comes to the top, or the person comes back to Dash.
`onHide()`	Function	Another page covers this one, or the person leaves Dash.
`onUnload()`	Function	The page closes.
`onRefresh()`	Function	The person pulled the page down to refresh it. Its spinner shows until this finishes. Only a page with this hook can be pulled.

`PageShare`

Lets a share link open this page, with some of its launch options. Without it, a link opens the dot's first page.

Member	Type	What it is
`options` (optional)	`string[]`	The launch options a share link to this page carries, by name. Keep private ones, such as an account number, off the list. Write the list inline, not from a variable.

this in hooks and actions

Inside a page's hooks and actions, this gives the page's state and tools. Actions also get navigation. Mutations get no this: they only return changes.

`PageContext`

Member	Type	What it is
`id`	`string`	The page's id, such as `checkout`.
`state`	`object`	The page's state now.
`dash`	`Dash`	Dash's features. Calls still running when the page closes are cancelled.
`setState(update)`	Function	Changes some of the state: pass the changes, or a function of the current state that returns them.
`setNavigationBar(options)`	Function	Changes Dash's navigation bar on this page, on top of what definePage set.
`setTabBar(options)`	Function	Hides or shows Dash's tab bar while this page shows.
`setColors(colors)`	Function	Changes this page's colors, on top of what definePage set, such as `{ background: { light: "#FFF3E0" } }`. Set `light` or `dark` to undefined to use the theme's color again.
`captureView(id)`	Function	Makes a PNG of the View with this `id`, and gives it back as a file object. See Make a picture of a View.
`mutations`	`object`	The page's mutations, to run one from a hook or an action, such as `this.mutations.reset()`.
`actions`	`object`	The page's actions, to run one from another, such as `await this.actions.refresh()`.

`ActionContext`

Member	Type	What it is
`navigation`	`PageNavigation`	Opens, replaces and closes pages. See `PageNavigation`.

`PageNavigation`

Member	Type	What it is
`push(page, options?)`	Function	Opens `page` on top of this one.
`replace(page, options?)`	Function	Opens `page` in place of this one.
`reset(page, options?)`	Function	Closes every page and opens `page`.
`back(delta?)`	Function	Closes this page, or `delta` pages.
`pushForResult(page, options?)`	Function	Opens `page` on top, and resolves with what it gives back with `backWithResult`, or undefined if it closes without one, as when the person goes back.
`backWithResult(result)`	Function	Closes this page, and gives `result` to the page below if it opened this one with `pushForResult`.

Dash's bars and page colors

configs in defineDot and definePage set what Dash's navigation bar and tab bar show, and a page's own colors. this.setNavigationBar(), this.setTabBar() and this.setColors() change them while a page shows.

`PageConfigs`

Member	Type	What it is
`navigationBar` (optional)	`NavigationBarOptions`	The bar at the top of the screen. See `NavigationBarOptions`.
`tabBar` (optional)	`TabBarOptions`	Dash's tabs at the bottom of the screen. See `TabBarOptions`.
`colors` (optional)	`PageColors`	The page's own colors, as #RRGGBB for each scheme, in place of the theme's, such as `{ background: { light: "#FFF3E0" } }`. Dash paints the background behind the page too, and picks bar and status bar colors that read on it.

`NavigationBarOptions`

Dash restores its own bars when the page closes, and its own value for any option set to undefined.

Member	Type	What it is
`title` (optional)	`string`	Shown in place of the dot's name, up to 60 characters. A title naming Dash or Monime shows the dot's name instead.
`hidden` (optional)	`boolean`	Hides the bar.
`backgroundColor` (optional)	`string`	The bar's color, as `#RRGGBB`.
`textColor` (optional)	`string`	The color of the bar's title and buttons, as `#RRGGBB`.

`TabBarOptions`

Member	Type	What it is
`hidden` (optional)	`boolean`	Hides Dash's own tabs at the bottom of the screen.

`PageColors`

The colors a page sets in place of the theme's. Any color it leaves out stays the theme's.

TypeScript

type PageColors = Omit<ThemeColors, 'custom'>;

Theme

How a dot looks everywhere: its colors, corners, fonts, spacing and shadows, default props for components, and its own icons and gradients. See Theming.

Set with theme in defineDot, and changed while the dot runs with this.setTheme() in its hooks.

Member	Type	What it is
`scheme` (optional)	`ColorScheme \| 'system'`	`system` follows the device. `light` or `dark` forces one. Default: `system`.
`colors` (optional)	`ThemeColors`	The dot's colors. See `ThemeColors`.
`shape` (optional)	`ThemeShape`	How rounded corners are: `square`, `subtle`, `soft` or `rounded`. Default: `soft`.
`font` (optional)	`ThemeFont`	The font of all text, one of the phone's own. See `ThemeFont`.
`headingFont` (optional)	`ThemeFont`	The font of headings: Text's display, title and subtitle, and the titles of sheets and empty states. Default: the same as `font`.
`headingWeight` (optional)	`ThemeWeight`	How heavy headings are. Default: bold, and medium for subtitles. A Text's own `weight` wins.
`textSize` (optional)	`ThemeTextSize`	How large all text is: `small` is a tenth smaller than `regular`, the default, and `large` a tenth larger. Text in fields stays large enough that iPhones don't zoom in on them.
`density` (optional)	`ThemeDensity`	How much room gaps and padding take: `compact` is three quarters of `regular`, the default, and `comfortable` a quarter more. Components' own spacing inside them stays as it is.
`elevation` (optional)	`ThemeElevation`	`raised` gives cards and lists a soft shadow in place of their hairline. Default: `flat`.
`components` (optional)	`ThemeComponents`	Default props for every use of a component, and for each of its variants. Props set in markup still win. See Component defaults.
`icons` (optional)	`Record<string, string>`	Your dot's own icons by name, each an SVG in `statics/`. See Your own icons.
`gradients` (optional)	`Record<string, ThemeGradient>`	Your dot's own gradients by name, for a View's `background`. See `ThemeGradient`.

`ThemeColors`

Left out, a color is Dash's own. When the background is set but the surface, muted, border or subtle colors aren't, Dash works them out from the background so they sit well on it.

Member	Type	What it is
`primary` (optional)	`SchemeColor`	The main color, such as for primary buttons.
`background` (optional)	`SchemeColor`	The page's background.
`surface` (optional)	`SchemeColor`	Cards, lists, sheets and fields.
`text` (optional)	`SchemeColor`	Text.
`muted` (optional)	`SchemeColor`	Quiet fills, such as secondary buttons and chips.
`border` (optional)	`SchemeColor`	Lines around cards and fields.
`subtle` (optional)	`SchemeColor`	Quieter text, such as captions.
`info` (optional)	`SchemeColor`	The `info` tone, for text, soft tints, messages and buttons. Pick one that reads as text on the background.
`success` (optional)	`SchemeColor`	The `success` tone.
`warning` (optional)	`SchemeColor`	The `warning` tone.
`danger` (optional)	`SchemeColor`	The `danger` tone.
`custom` (optional)	`Record<string, SchemeColor>`	Your dot's own colors by name, such as `gold`, for a View's `background` and a Text's `tone`. Names are camelCase, and can't be ones those props already have, such as `surface`.

`SchemeColor`

Member	Type	What it is
`light` (optional)	`HexColor`	The color in light mode, as `#RRGGBB`.
`dark` (optional)	`HexColor`	The color in dark mode, as `#RRGGBB`. Left out, the light color is used in both.

`ThemeGradient`

A gradient between two colors.

Member	Type	What it is
`from`	`string`	Where it starts: a color of the theme, such as `primary`, or one of your own.
`to`	`string`	Where it ends, chosen the same way.
`direction` (optional)	`'down' \| 'right' \| 'diagonal'`	Which way it goes: `down`, `right`, or `diagonal` from the top start corner. Default: `down`.

`ThemeShape`

TypeScript

type ThemeShape = 'square' | 'subtle' | 'soft' | 'rounded';

`ThemeFont`

One of the phone's own fonts, so nothing is downloaded. Default: system. A phone without a rounded font, such as most Android phones, uses its system font.

TypeScript

type ThemeFont = 'system' | 'rounded' | 'serif' | 'mono';

`ThemeWeight`

TypeScript

type ThemeWeight = 'regular' | 'medium' | 'bold';

`ThemeTextSize`

TypeScript

type ThemeTextSize = 'small' | 'regular' | 'large';

`ThemeDensity`

TypeScript

type ThemeDensity = 'compact' | 'regular' | 'comfortable';

`ThemeElevation`

TypeScript

type ThemeElevation = 'flat' | 'raised';

Events

Handlers receive the event as their second argument. These types name the events components send. Pages use them without an import.

`DotEvent`

data holds the data-* attributes of the component that raised the event: data-account-id arrives as data.accountId.

Member	Type	What it is
`type`	`string`	The event's name, such as `change`.
`detail`	`object`	What the component reports, such as `{ value }` for a field.
`data`	`object`	The component's `data-*` attributes, with camelCase names.

`ValueEvent`

What a field sends as it changes: text from Input, TextArea, Select, Tabs, RadioGroup and CodeInput, a number from Slider, and a number or null from AmountInput.

TypeScript

type ValueEvent<Value = string> = DotEvent<{ value: Value }>;

`CheckedEvent`

What Switch and Checkbox send.

TypeScript

type CheckedEvent = DotEvent<{ checked: boolean }>;

`IndexEvent`

What Scroll and Carousel send when another item comes into view.

TypeScript

type IndexEvent = DotEvent<{ index: number }>;

`DataEvent`

A tap whose element's data-* attributes tell the handler which item it was. They arrive as text.

TypeScript

type DataEvent<Data> = DotEvent<unknown, Data>;

defineDot

dot.ts exports defineDot({ ... }), which lists the pages and sets what applies to all of them. In its hooks, this is a DotContext.

TypeScript

export default defineDot({ pages: ['index', ...], theme, configs, hooks })

`DotDefinition`

Member	Type	What it is
`theme` (optional)	`Theme`	How the dot looks on every page. See Theming.
`pages`	`string[]`	Every page the dot may open, by id. The first is where the dot starts.
`configs` (optional)	`PageConfigs`	Dash's bars and the colors of every page. A page's own configs override them.
`hooks` (optional)	`DotHooks`	Functions Dash runs when the dot starts and when something fails. See `DotHooks`.

`DotHooks`

Member	Type	What it is
`onLaunch()`	Function	The dot starts.
`onError(error)`	Function	Something in the dot failed and nothing caught it.

`DotContext`

Member	Type	What it is
`theme`	`Theme`	The theme now.
`setTheme(theme)`	Function	Changes the theme while the dot runs.

testPage

testPage from @monimesl/dot-runtime/testing runs a page without Dash, for tests. See Testing.

TypeScript

const page = await testPage(definition, { options, host, results })

`TestPageOptions`

Member	Type	What it is
`options` (optional)	`Record<string, string>`	The launch options `onLoad` gets.
`host` (optional)	`object`	Fake answers for the Dash calls the page makes, by name, such as `'dash.ui.alert'`. Any other call fails with `unsupported`.
`results` (optional)	`Record<string, unknown>`	What each page the test page opens with `pushForResult` gives back, by its id. A page not listed gives undefined, as if the person went back.

`PageTest`

Member	Type	What it is
`state`	`object`	The page's state now.
`patches`	`object[]`	Every change to the state, in order.
`navigations`	`object[]`	Every navigation the page asked for.
`hostCalls`	`{ method, params }[]`	Every Dash call the page made, such as `{ method: 'dash.ui.alert', params }`.
`bars`	`object`	What Dash's bars show over the page now.
`result`	`unknown`	What the page gave back with `backWithResult`, or undefined.
`tap(name, detail?)`	Function	Runs a mutation or an action by name, with `detail` as the event's detail, and waits for it.
`dispatch(name, event?)`	Function	Runs a handler with a whole event, such as one with `data`.
`show()`	Function	Runs `onShow`.
`hide()`	Function	Runs `onHide`.
`unload()`	Function	Runs `onUnload`.
`refresh()`	Function	Runs the page's `onRefresh`, as when the person pulls it down.

Pages and dot API

definePage

`PageOptions`

`PageHooks`

`PageShare`

this in hooks and actions

`PageContext`

`ActionContext`

`PageNavigation`

Dash's bars and page colors

`PageConfigs`

`NavigationBarOptions`

`TabBarOptions`

`PageColors`

Theme

`ThemeColors`

`SchemeColor`

`ThemeGradient`

`ThemeShape`

`ThemeFont`

`ThemeWeight`

`ThemeTextSize`

`ThemeDensity`

`ThemeElevation`

Events

`DotEvent`

`ValueEvent`

`CheckedEvent`

`IndexEvent`

`DataEvent`

defineDot

`DotDefinition`

`DotHooks`

`DotContext`

testPage

`TestPageOptions`

`PageTest`

Keep reading

On this page