Trace

Use it for an entrance that shows how a piece of UI is wired: a hero demo, a launch moment, a dashboard coming online. A thin signal comes in from beside the frame and runs both ways round its border. Then it spreads down the layout: along each box's edge, across the gutter above what the box holds and down a short square connector into each region, round that region's border, and on to every part, all branches at once. Each part glows briefly on its edge as the signal reaches it, then appears. Keep it to one moment on a page: it asks to be watched.

#Installation

#Usage

Wrap the UI in TraceEntrance. It lights up its first child and plays on mount.

import { TraceEntrance } from '@youj/motion'

export function Hero() {
  return (
    <TraceEntrance>
      <Dashboard />
    </TraceEntrance>
  )
}

Change play to play it again (a counter works), or set it to false to show the UI as it is. onFinish is called when the run ends.

For an element you don't render with React, call the engine. It returns a cancel() and a finished promise, and an AbortSignal in signal cancels it too. To drive it from a clock of your own (a video rendered frame by frame, a scrubber), pass paused: true and call seek(t) with the time in ms from its start: it shows that moment and holds it. It only goes forwards, and a time at or past its end ends it.

import { trace } from '@youj/motion'

const run = trace(document.querySelector('#overview')!, { speed: 1.5 })
await run.finished

#Color

The signal is the theme's foreground, so it reads on every theme. accent draws it in the theme's accent instead. The path it has run stays etched faintly behind it until the run settles, then fades.

#Pacing

The run goes through three stages: enter (the signal comes in and runs round the frame, and the frame fills in behind it), spread (it runs down the layout and lights every part) and settle (the etched path fades and anything floating fades in). The signal runs at one speed through the spread, so near parts light first and the farthest part lights last.

The length grows with the demo: about 2 seconds for a card and about 3.5 for a small screen. Three options tune it:

• duration fixes the whole run, in milliseconds.
• speed scales it: 2 plays twice as fast. It applies on top of duration and the provider's speed.
• phases shares the run out between the three stages. The values are weights, so they are normalized and never change the total; a stage left out keeps its default ({ enter: 14, spread: 74, settle: 12 }), and 0 skips it.

// a quick run that is nearly all spread
<TraceEntrance duration={1400} phases={{ enter: 8, spread: 84, settle: 8 }}>
  <PricingCard />
</TraceEntrance>

#What it reads

The layout comes from the real DOM, read once before the first frame: roles, tags and data-slot first, then geometry. The main regions and the panels too big to be one part are the branches, each inside the smallest one that holds it; their borders are traced on their own edges, rounded corners included, and a panel fills in as its border is traced. The parts are the leaves: a field, a button, a stat card, a list row, a paragraph, or a part with nothing inside it (a chart, an image). What's inside a part comes with it. Open popovers simply fade in at the end.

#Reference

function trace(node: HTMLElement, options?: TraceOptions): { cancel(): void; finished: Promise<void>; seek(t: number): void }