Pages and focus
A MicroTS application changes pages by writing a signal that a conditional
branch reads. The AOT view subset has no router, page stack, dynamic
component or lazy import. Each page is a child component, the root model holds
the current page, and Switch/Match or v-if selects the mounted branch.
This page describes the branch forms, the lifetime of page state and the
position of focus after a switch. The guest build of an application with
app.aot: true uses the same branch and state rules as its native build.
Focus differs between the two builds in the cases
listed below.
| What you want to do | Where to start |
|---|---|
| Show one of several pages | Select a page |
| Keep a page's state while another page is shown | Page state across a switch |
| Know which node receives the next press | Focus after a switch |
| Compare the browser preview with the device | Differences in the guest build |
| Fade a page out before the next one mounts | Animate a switch |
Select a page
The root model declares the page as a string-literal union and exports the functions that change it:
// app.ts
import { createSignal } from "solid-js";
export type Page = "home" | "settings";
export const [page, setPage] = createSignal<Page>("home");
export function openSettings(): void {
setPage("settings");
}
export function goHome(): void {
setPage("home");
}The root view mounts one Match branch. Pages report navigation through
callback props, and the root passes them to model functions:
// app.tsx
import { Match, Switch } from "solid-js";
import { ActionHandler, View } from "@pocketjs/framework/solid/components";
import { BTN } from "@pocketjs/framework/input";
import HomePage from "./HomePage.tsx";
import SettingsPage from "./SettingsPage.tsx";
import { goHome, openSettings, page } from "./app";
export default function App() {
return (
<View class="w-full h-full flex-col p-4 bg-slate-50">
<ActionHandler button={BTN.CROSS} active={page() === "settings"} onPress={goHome} />
<Switch>
<Match when={page() === "home"}>
<HomePage onOpenSettings={() => openSettings()} />
</Match>
<Match when={page() === "settings"}>
<SettingsPage onBack={() => goHome()} />
</Match>
</Switch>
</View>
);
}// HomePage.tsx
import { Text, View } from "@pocketjs/framework/solid/components";
export default function HomePage(props: { onOpenSettings: () => void }) {
return (
<View class="flex-col gap-2">
<Text class="text-lg text-slate-950">Home</Text>
<View class="p-2 bg-blue-600 focus:bg-blue-500" focusable
onPress={() => props.onOpenSettings()}>
<Text class="text-sm text-white">Open settings</Text>
</View>
</View>
);
}A Vue root uses v-if branches on the page components. Its model exports
page as ref<Page>("home"), and the pages declare their events with
defineEmits:
<!-- app.vue -->
<script setup lang="ts">
import { ActionHandler, View } from "@pocketjs/framework/vue-vapor/components";
import { BTN } from "@pocketjs/framework/vue-vapor/input";
import HomePage from "./HomePage.vue";
import SettingsPage from "./SettingsPage.vue";
import { goHome, openSettings, page } from "./app";
</script>
<template>
<View class="w-full h-full flex-col p-4 bg-slate-50">
<ActionHandler :button="BTN.CROSS" :active="page === 'settings'" @press="goHome()" />
<HomePage v-if="page === 'home'" @open="openSettings()" />
<SettingsPage v-else @back="goHome()" />
</View>
</template>A child position takes JSX elements, not expressions that produce them.
The Solid front end rejects page() === "home" ? <HomePage /> : <SettingsPage />
and page() === "home" && <HomePage /> with
Conditional children use <Show> or <Switch>. Branch conditions are boolean:
compare the union with a literal. A third page adds a Match branch or a
v-else-if.
Every page compiles into the application binary. The guest components
Screen, Portal, Modal, Lazy, Gallery, FocusScope and FocusGrid
have no AOT form. Importing one into an AOT view fails with
<Name> has no native runtime in Solid and
Host component <Name> is outside the AOT subset in Vue. The
Solid diagnostics table lists the
other rejected forms.
Page state across a switch
A branch swap unmounts the old page and mounts the new page in one view update. A page with a model factory owns a region. Unmount cancels that region's tasks and drops its state; the next mount runs the factory from its seeds.
| Where the state lives | After leaving and returning to the page |
|---|---|
| Signals or refs in the root model | Unchanged |
| A page factory's signals, memos and tasks | New instance; tasks from the previous mount are cancelled |
| Mount-time factory arguments | Read from the parent's values at the new mount |
State that outlives a page belongs to the root model and reaches the page through props or context.
To keep a page mounted while another page is shown, wrap each page in a View
and switch its display. Solid selects between two complete class literals;
Vue uses v-show on the host element:
<View class={page() === "home" ? "flex-col" : "hidden"}>
<HomePage onOpenSettings={() => openSettings()} />
</View>
<View class={page() === "settings" ? "flex-col" : "hidden"}>
<SettingsPage onBack={() => goHome()} />
</View><View v-show="page === 'home'" class="flex-col"><HomePage @open="openSettings()" /></View>
<View v-show="page === 'settings'" class="flex-col"><SettingsPage @back="goHome()" /></View>Hiding a page does not unmount it: both pages keep their nodes, factory state and tasks.
Focus after a switch
The AOT view and model subsets contain no call that moves focus. The
guest framework's FocusScope, FocusGrid and focusNode are outside the
subset. The native runtime, microts::Ui, applies these rules:
DOWNandRIGHTfocus the next focusable node in document order;UPandLEFTfocus the previous one. Movement stops at both ends.CIRCLEpresses the focused node. A press whose target is hidden or not focusable is dropped.- With no focused node, or with a hidden one,
DOWNorRIGHTfocuses the first visible focusable node andUPorLEFTfocuses the last.
After a branch swap that removed the focused node, no node is focused. Unmount destroys a page's nodes one at a time, children before their parent. A destroyed node that holds focus passes it to the first focusable node of a following sibling subtree, then of a preceding one, then to the nearest focusable ancestor. When the page's last focusable node is destroyed, its sibling subtrees hold none, and focus becomes empty unless an ancestor is focusable. A focusable node beside the page branch does not receive it.
| Page structure | Focus after the switch | First CIRCLE |
|---|---|---|
| Branch swap, press came from a node of the old page | None | Dropped until a direction press |
Hidden wrapper (hidden class or v-show) |
Stays on the hidden node | Dropped until a direction press |
| Press came from a focusable node outside both pages | Stays on that node | Presses that node |
Three inputs act on the frame after a switch without a direction press:
- An
ActionHandlerruns for its named button with or without focus. Use one for back navigation, as the root view above does withBTN.CROSS. - A focused node outside the page branch keeps focus across the swap. A
tab row or a toolbar placed beside the
Switchstays focused while the pages under it change. - A touch host passes the pressed node in
Input.target. The press reaches that node's handler with no focused node.
A native host can assign focus with Ui::set_focus(node) between frames.
Ui::initial_focus() returns the focusable node with the lowest node id: the
earliest created one while no id has been reused. The core reuses the ids of
destroyed nodes, so after an unmount the result has no fixed relation to
document order.
Differences in the guest build
The guest build runs the framework's focus manager in place of microts::Ui.
It repairs focus once per removed subtree, from that subtree's root, and it
delivers CIRCLE to the focused node without a visibility test. A browser
preview differs from the device in these cases:
| Case | Native build | Guest build |
|---|---|---|
| The focused node is inside the removed page and a focusable node follows the branch | No node is focused | The node after the branch receives focus |
| The focused node is inside a hidden wrapper | CIRCLE is dropped |
CIRCLE runs the hidden node's handler |
A Rust host on the development machine reproduces the device's focus
position: call frame with Input::buttons(...) and read Ui::focused().
See Input & focus for the guest focus manager.
Animate a switch
A branch swap has no exit phase. The old page's nodes are destroyed in the
update that mounts the new page. To animate the change, an async model
function awaits an animation on a node that stays mounted and writes the page
signal after the await:
// app.ts
import { createSignal } from "solid-js";
import { animate, createNodeRef } from "@pocketjs/framework/animation";
import type { i32 } from "@pocketjs/framework/solid/std";
export type Page = "home" | "settings";
export const [page, setPage] = createSignal<Page>("home");
export const stage = createNodeRef();
async function show(next: Page): Promise<void> {
await animate(stage, "opacity", 0, { dur: 100 as i32 });
setPage(next);
animate(stage, "opacity", 1, { dur: 100 as i32 });
}
export async function openSettings(): Promise<void> {
await show("settings");
}<View class="flex-col" ref={stage}>
<Switch>
<Match when={page() === "home"}>
<HomePage onOpenSettings={() => openSettings()} />
</Match>
<Match when={page() === "settings"}>
<SettingsPage onBack={() => goHome()} />
</Match>
</Switch>
</View>The task resumes at the frame boundary after the animation ends, so the old
page stays mounted for the fade. At 60 ticks per second the 100 ms fade above
holds the old page for six frames. A second call to show before the first
finishes cancels the first, as the
task rules describe. Style
changes on a mounted node can use the transition-* classes from
Styling without a task.