# LifecycleFigure A state machine: what something can be, and what moves it between states. - Group: Diagrams - Import: `import { LifecycleFigure } from '@misoto22/folio/diagrams'` - Page: https://ui.misoto22.com/components/lifecycle-figure/ - Related: workflow-figure, steps ## When to reach for it The one figure that spends colour, and it spends exactly the two tokens the system reserves for state. Every other distinction is shape, so a greyscale print keeps six of the eight. ## Anatomy - **Figure shell** (required) — The frame around the picture. What a machine hands it is a transition list with each note folded in after an em dash, so the condition on an arrow — the timeout, the retry count — is in the text copy and not only on the line. - **State plate** (required) — One shape per kind: a filled cap for a start, a diamond for a decision, a dashed frame for a wait, a cut corner for an external, and the two washes the system reserves for the terminals. The name is centred, step sits in the leading corner and tag along the bottom edge. - **Main rail** — The first lane’s states, sorted by col and joined consecutively at the emphasis weight — one line per neighbouring pair the transitions do not already declare, so a spine written out in full is drawn from the transitions and a spine left implied is drawn anyway. Without it the top row reads as five unconnected boxes, because the spine of a machine is the part nobody writes down. - **Transition** — A routed line with its label on a mask and its note in a quieter line beneath. A declared transition between two rail neighbours replaces the implicit one rather than doubling it. - **Lane** — A rule with a mono caption above it, drawn only as far as that lane’s own states reach. A lane past the first has its columns shifted along the main rail, which is what keeps a drop out of the spine vertical rather than a dogleg. ## Best practices ### Do - Keep the first lane for the ordered spine and nothing else. Consecutive states there are joined by the implicit rail even when no transition declares the pair, so a state parked in lane 0 for spacing invents an edge the machine does not have. A state whose lane id nothing declares is kept out of that rail and reported as DIAGRAM_LANE_UNKNOWN instead, because a typo should not be able to add an arrow. - Count a secondary lane’s columns from the rail. Every col in a lane past the first is shifted two columns along, so col: 0 in the second lane sits under col: 2 in the first — the convention archify’s lifecycle contract already implies, restated here because it is what makes a drop land on the state it came from. - Say whether a failure is recoverable with an edge, not with the type. type: "failure" only paints the plate; a retryable error and a terminal one are identical until a reader follows the arrows out, and the one with none is where the run ended. ### Don’t - yOffset moves the plate and moves nothing out of its way. The lane’s rule is drawn from what that lane holds, so a negative nudge drags the rule up with the state and a large positive one drops the plate into the band below — a state needing that much room wants a column of its own rather than a push. - The figure claims a state can be left only the ways its arrows say. A cancel that can happen from anywhere and is drawn from nowhere reads as impossible, which is a reading the picture makes and the specification never wrote — draw it, or say in the subtitle that it is not drawn. ## Accessibility - success and failure are the only coloured marks in the package’s diagrams, and each is also a distinct plate shape — colour is never the only carrier. - The main rail is drawn between consecutive states in the first lane even when the specification does not list those transitions, because they are the diagram’s spine rather than its exceptions. ## LifecycleFigure A state machine: what something can BE, and what moves it. The one figure here that spends colour, and it spends exactly the two tokens this system reserves for state: `--success` on a terminal success, `--danger` on a terminal failure. Nothing else in the package is allowed those two, and a lifecycle diagram is the case they were reserved for — the whole point of the picture is which end a run came out of. The other six kinds are carried by shape, so a greyscale print loses the two outcomes' hue and keeps every other distinction: a start is a filled cap, a decision is a diamond, a wait is a dashed frame, an external is a plate with a cut corner. A RECOVERABLE FAILURE IS A FAILURE WITH A WAY BACK. `type: "failure"` says how a state is drawn; a transition OUT of it is what says whether the run is over. A retryable error and a terminal one look identical until you follow the arrows, which is correct — the difference between them is a real edge in the machine, not an adjective on a box. ### Props - `spec` (required) — `LifecycleSpec`. Also accepts: `FigureChrome`. ## Example — default ```tsx import { LifecycleFigure } from '@misoto22/folio/diagrams' ``` ## Example — a decision with both ends ```tsx import { LifecycleFigure } from '@misoto22/folio/diagrams' ``` ## Example — a failure with a way back ```tsx import { LifecycleFigure } from '@misoto22/folio/diagrams' ``` ## Example — the implicit rail ```tsx import { LifecycleFigure } from '@misoto22/folio/diagrams' ```