# Transitions

Source: https://material.spynejs.com/transitions
Part of: Material shell gallery, Google's Material Design 3 for SpyneJS. Index: https://material.spynejs.com/llms.txt

Material's transitions between pages. The template names every move from the route and moves the pages to suit: a fade between destinations, a slide down or up a level, and a card growing into its page. A model does not ask for a transition; which one a move takes follows from the route and from what was followed.

## In an app model

Nothing. A transition follows from where the move goes and from what was followed, not from a key. What a model decides is the pages and their levels: a page with sub-pages shows them as cards, and following a card down a level is the container transform.

## Which move takes which transition

The Material channel reads the kind of move from the route change and names it:

| Transition | The move | What is seen |
| --- | --- | --- |
| `top-level` | between destinations, or between two pages at the same level. A move from a sub-page straight to another destination is this one too. | the page fades out, then the next fades in |
| `forward` | down a level, by anything but a card | the page slides out to one side as the next slides in from the other |
| `container-transform` | down a level, by a card (`a.page-card`) | the card’s shape grows into its page |
| `backward` | back up a level, by any way: a link, the breadcrumb, the browser’s Back | where the page returned to shows the page being left as a card, that page shrinks into its card, however it was reached. Where it has no such card, the pages slide, the mirror of forward. |

- To get the container transform, lead down a level with the template’s own card. Any other link down a level slides.
- The channel’s actions, for a view that must know of a move: `CHANNEL_MATERIAL_PAGE_LEAVING_EVENT` with `{ pageMoveId, transition, from }` when a move begins, and `CHANNEL_MATERIAL_PAGE_LEFT_EVENT` with `{ pageMoveId, transition }` when the leaving page’s time is up.
- A page learns of the move that made it from a second channel, `CHANNEL_MATERIAL_PAGES`, which replays. Its one action out, `CHANNEL_MATERIAL_PAGES_MOVE_EVENT`, always carries the whole move: `{ pageMoveId, transition, from, phase }`.
- A leaving page carries the class `is-leaving`; the stage carries the move’s name in `data-page-transition`. The moves themselves are styles.
- A card growing into its page, and a page shrinking into its card, use the browser’s view transitions. Where a browser has none, the move down takes `forward` and the move back stays the slide.
- With reduced motion asked for, every move keeps its fades and loses the rest.
- Never time a page’s exit in a view. The wait is the channel’s.

## Where it is in the template

| File | What it holds | By name |
| --- | --- | --- |
| `src/app/channels/channel-material.js` | the Material channel: a move beginning and ending, and how long a leaving page is given (`pageExitDuration`) | `CHANNEL_MATERIAL_PAGE_LEAVING_EVENT`, `CHANNEL_MATERIAL_PAGE_LEFT_EVENT`, `pageExitDuration` |
| `src/app/traits/channel/channel-material-traits.js` | names the transition from the route change | `channelMaterial$OnRouteChange`, `pageTransitionFromRoute` |
| `src/app/channels/channel-material-pages.js` | the move under way, in full, replayed to a page made by it | `CHANNEL_MATERIAL_PAGES_MOVE_EVENT` |
| `src/app/traits/app/stage-container-traits.js` | the stage: changes the pages over, and writes the move’s name on their holder | `stage$OnPageMove`, `stage$OnPageLeaving`, `stage$OnPageCollapse` |
| `src/app/traits/page/page-leave-traits.js` | how a page leaves; marks the card a move began on | `pageLeave$OnRouteChange` |
| `src/app/traits/page/page-return-traits.js` | a page being returned to: finds the card the leaving page collapses into | `pageReturn$OnPageMove` |
| `src/scss/03-components/material/_motion.scss` | the moves themselves, with their timings |  |

The template is public: https://github.com/spynejs/application-shell-material. An app made from it has these same files.

What it rests on in `@spynejs/grammar`: `op:react-to-route-diff`, `op:state-machine-in-channel`, `op:choose-replay-semantics`, `op:escape-to-raw-rxjs`.

## As the page shows it

The page’s own words, in its own order, read from the page as it is drawn in the light colour scheme. They were written for someone looking at the page: “above”, “below” and “marked” mean the drawn page. A thing the page draws is named here in its place (`Button:`, `Field:`, `Switch:`), and a box that reports what the reader does is as it starts, empty. What depends on the reader’s own window is left out.

The template names every move between pages from the route, and moves the pages to suit. This page has one of each.

### Top level

Between destinations: the page fades out, and then the next fades in. The links in the sidebar do the same.

- [To Foundations](https://material.spynejs.com/foundations.md)
- [To Components](https://material.spynejs.com/components.md)

### Forward and backward

Down a level by anything but a card: the page slides out to one side as the next slides in from the other. Back up is the mirror of it.

- [Sample A, by a plain link](https://material.spynejs.com/transitions/sample-a.md)

### Container transform

Down a level by a card: the card's shape grows into its page. Back up, the page shrinks into its card. The cards are below.

- [Sample A](https://material.spynejs.com/transitions/sample-a.md): A page under Transitions.
- [Sample B](https://material.spynejs.com/transitions/sample-b.md): Another.
- [Sample C](https://material.spynejs.com/transitions/sample-c.md): And a third.
