# Pages and dot API (/docs/products/dash-dots/reference/pages-and-dot) 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](/docs/products/dash-dots/developers/pages-and-state) and [Navigation](/docs/products/dash-dots/developers/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()`. ```ts 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`](#pageconfigs). | | `share` (optional) | `PageShare` | Which share links can open this page. See [`PageShare`](#pageshare). | | `hooks` (optional) | `PageHooks` | Functions Dash runs as the page opens, shows, hides, closes and refreshes. See [`PageHooks`](#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](/docs/products/dash-dots/developers/network-and-files#file-objects). See [Make a picture of a View](/docs/products/dash-dots/developers/views#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). | ### `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`](#navigationbaroptions). | | `tabBar` (optional) | `TabBarOptions` | Dash's tabs at the bottom of the screen. See [`TabBarOptions`](#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. ```ts type PageColors = Omit; ``` ## 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](/docs/products/dash-dots/developers/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`](#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`](#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](/docs/products/dash-dots/developers/theming#component-defaults). | | `icons` (optional) | `Record` | Your dot's own icons by name, each an SVG in `statics/`. See [Your own icons](/docs/products/dash-dots/developers/theming#your-own-icons). | | `gradients` (optional) | `Record` | Your dot's own gradients by name, for a View's `background`. See [`ThemeGradient`](#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` | 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` ```ts 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. ```ts type ThemeFont = 'system' | 'rounded' | 'serif' | 'mono'; ``` ### `ThemeWeight` ```ts type ThemeWeight = 'regular' | 'medium' | 'bold'; ``` ### `ThemeTextSize` ```ts type ThemeTextSize = 'small' | 'regular' | 'large'; ``` ### `ThemeDensity` ```ts type ThemeDensity = 'compact' | 'regular' | 'comfortable'; ``` ### `ThemeElevation` ```ts 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. ```ts type ValueEvent = DotEvent<{ value: Value }>; ``` ### `CheckedEvent` What Switch and Checkbox send. ```ts type CheckedEvent = DotEvent<{ checked: boolean }>; ``` ### `IndexEvent` What Scroll and Carousel send when another item comes into view. ```ts type IndexEvent = DotEvent<{ index: number }>; ``` ### `DataEvent` A tap whose element's `data-*` attributes tell the handler which item it was. They arrive as text. ```ts type DataEvent = DotEvent; ``` ## defineDot `dot.ts` exports `defineDot({ ... })`, which lists the pages and sets what applies to all of them. In its hooks, `this` is a `DotContext`. ```ts 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](/docs/products/dash-dots/developers/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). | ### `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](/docs/products/dash-dots/developers/testing). ```ts const page = await testPage(definition, { options, host, results }) ``` ### `TestPageOptions` | Member | Type | What it is | | -------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `options` (optional) | `Record` | 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` | 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. |