Motion, boundaries and islands
Things on a screen move by themselves when they change, a part that fails falls back without breaking the screen, a part that loads shows a skeleton of itself, and a part below the fold can wait until it is needed. examples/motion shows all of it.
Automatic motion
When a <show> swaps its side, or a <list> adds, removes or reorders rows, the change moves, with nothing written (decision 0055):
- an element that comes plays in (on the web a 200 ms fade with a 6 px rise);
- an element that goes stays drawn where it was, inert and hidden from assistive technology, and plays out before it is removed;
- everything beside the change that moved glides from its old place to its new one.
A show's or list's first build never moves: the screen arriving is the navigation transition's to play.
Presets
motion="..." names the movement an element plays as it comes and goes:
<show when={saved}>
<view motion="slide-up" class="p-3 rounded-md bg-surface">Saved</view>
</show>
<list each={todos} as="todo" key={todo.id} motion="scale">...</list>
The presets are fade, scale, slide-up, slide-down, slide-left, slide-right, spring, and none to switch automatic motion off. On a list it is every row's. An unknown name is E0240, and a preset written as an expression is E0245: each target prepares the movement when it builds.
With reduced motion set on the device, nothing glides, and every preset is a short fade.
Morphs and the back gesture
morph="name" names an element. When the screen being left and the screen arriving both have an element of that name, it travels from one place and size to the other during the transition (decision 0056):
<!-- pages/index.duo -->
<view href={`/post/${post.id}`}>
<view morph={`post-${post.id}`} class="thumb rounded-md" />
</view>
<!-- pages/post/[id].duo -->
<view morph={`post-${id}`} class="picture" />
On touch, a swipe from the leading edge goes back with the screen under the finger. On iOS and Android morph flies a copy of the arriving element from the leaving element's place (decision 0056), and the phone's own back button and gesture pop the stack.
Boundaries
<boundary> keeps a failure to its own part of the screen (decision 0058). A throw while its content is built, or while any of its bindings updates, shows its <fallback> instead; the rest of the screen carries on.
<boundary>
<Chart data={sales} />
<fallback as="failure">
<text>{failure.message}</text>
<button on:press={failure.retry}>Try again</button>
</fallback>
</boundary>
failure.message is a sentence, failure.error what was thrown, and failure.retry() builds the content again. Without a fallback, a boundary shows "Something went wrong here." and a Try again button. Throws in event handlers are not caught; handle them there. A fallback outside a boundary is E0242, and a second fallback E0243.
Skeletons
<boundary loading={...}> shows a skeleton while loading is truthy (decision 0059). The skeleton is the content's own markup built without data: blank text, empty conditions, three blank rows for a list, drawn as blocks that cannot be pressed. There is nothing to draw by hand.
<boundary loading={feed.loading} remember="home-feed">
<list each={feed.value} as="post" key={post.id}>...</list>
</boundary>
With remember="name", once the content has shown, its shape is kept under that name, and the next skeleton draws the shape it last had.
Islands
Any placed component takes load="visible", "idle" or "interaction", which makes it an island: it is built only when it comes near the viewport, when the browser is idle, or when it is pressed or focused (decision 0057). Until then its skeleton holds its place.
<Comments post={post.id} load="visible" />
On the web an island's code is its own module, downloaded only when its directive fires, and a failed download is the island's failure, with Try again. A directive written as an expression is E0244, and an unknown one E0241.
On native
Presets, automatic motion, boundaries, fallbacks and skeletons are built on iOS and Android (packages/engine/src/motion.tsx, boundary.tsx), and nothing in pages changes. An island is built at once there, because the bundle on the phone already holds every component's code. morph works there too (decision 0056). See native.md.
Related
- navigation.md: transitions between screens.
- data.md: the loaded state a skeleton waits for.
- testing.md:
pending()keeps loaded state loading, so a test can check the skeleton.