@picked/svelte 0.0.1-dev.1789541668638 → 0.0.1-dev.1793756239746

package/dist/plugins/devtools/review/journey/JourneyTimeline.svelte

@@ -0,0 +1,756 @@
+<script lang="ts">
+  /**
+   * @file The journey drawn as a TIMELINE — `git log --graph` for a flow. One row per node, top to
+   * bottom; branches run in lanes beside the rows and MERGE back into the node they meet, so a
+   * screen many branches reach is one row with lines converging on it, not a tree full of dashed
+   * jumps. `derive/journey-timeline` owns the layout; this file owns selection and scrolling only.
+   *
+   * A LOOP is the one thing a git graph never has. It stays off the drawing and rides on its row as
+   * a "↩ back to …" note, and the details pane can take the reviewer to its target.
+   *
+   * COLOUR IS THE BRANCH, as in a git tool: every line and dot takes its branch's colour, so the
+   * eye can follow one route down the lanes. That frees the node KIND to be a SHAPE — a circle for
+   * a screen, a diamond for a decision, a square for another journey. Actions are not drawn at all;
+   * where a branch ends on one, the row names it.
+   *
+   * ROWS ARE HTML, LINES ARE SVG, the same split as the map: each row is a real `<button>` the full
+   * width of the timeline, and the graph column is painted over its left edge with
+   * `pointer-events: none`, so clicking a dot or its label selects the same row.
+   */
+  import { tick } from 'svelte'
+  import { COLOURS, ROW_HEIGHT } from '../../derive'
+  import type { TimelineLayout, TimelineNode, TreeNodeKind } from '../../derive'
+  import TimelineMarker from './TimelineMarker.svelte'
+
+  interface JourneyTimelineProps {
+    layout: TimelineLayout
+    /** Whether a screen may be jumped to at all — the posture, and whether this journey is open. */
+    canNavigate: boolean
+    onJump: (stepKey: string) => void
+  }
+
+  const { layout, canNavigate, onJump }: JourneyTimelineProps = $props()
+
+  const KIND_LABELS: Record<TreeNodeKind, string> = {
+    start: 'Start',
+    screen: 'Screen',
+    decision: 'Decision',
+    system: 'Behind the scenes',
+    journey: 'Opens another journey',
+  }
+
+  /** Marker size per kind — the start a little larger, as on the map. */
+  const RADIUS: Record<TreeNodeKind, number> = {
+    start: 7,
+    screen: 5.5,
+    decision: 6.5,
+    system: 4.5,
+    journey: 5,
+  }
+
+  /** One colour per branch, in turn — `COLOURS` long, and distinct from its neighbours. */
+  const PALETTE = [
+    '#2563eb',
+    '#db2777',
+    '#059669',
+    '#ea580c',
+    '#7c3aed',
+    '#0891b2',
+    '#ca8a04',
+    '#dc2626',
+  ]
+
+  // The palette and the layout must agree on how many colours there are, or a fork repeats one.
+  if (PALETTE.length !== COLOURS) throw new Error('The timeline palette must hold COLOURS colours.')
+
+  let scroller: HTMLDivElement | undefined = $state()
+  let selected = $state<string | null>(null)
+
+  const byId = $derived(new Map(layout.nodes.map((node) => [node.id, node])))
+  const selectedNode = $derived(selected === null ? null : (byId.get(selected) ?? null))
+
+  /**
+   * A branch's colour.
+   *
+   * @param {number} colour - The branch's index into the palette.
+   * @returns {string} The colour, as a CSS hex value.
+   * @example
+   * paint(9) // the palette's second colour
+   */
+  function paint(colour: number): string {
+    return PALETTE.at(colour % PALETTE.length) ?? '#94a3b8'
+  }
+
+  /**
+   * Whether a row can take the visitor back to its screen.
+   *
+   * @param {TimelineNode} node - The row to test.
+   * @returns {boolean} True for a visited screen in the open journey, when the posture allows it.
+   * @example
+   * canJump(node)
+   */
+  function canJump(node: TimelineNode): boolean {
+    return (
+      node.kind === 'screen' && node.state === 'visited' && node.stepKey !== null && canNavigate
+    )
+  }
+
+  /**
+   * A node's name, for a loop note or a "Leads to" link.
+   *
+   * @param {string} id - The node's id.
+   * @returns {string} The node's label.
+   * @example
+   * labelOf(next.to) // 'Contact details'
+   */
+  function labelOf(id: string): string {
+    return byId.get(id)?.label ?? 'an unnamed node'
+  }
+
+  /**
+   * Brings a row to the middle of the timeline.
+   *
+   * @param {TimelineNode} node - The row to show.
+   * @param {boolean} smooth - Whether to scroll smoothly.
+   * @example
+   * reveal(node, true)
+   */
+  function reveal(node: TimelineNode, smooth: boolean): void {
+    if (scroller === undefined) return
+    const top = node.row * ROW_HEIGHT + ROW_HEIGHT / 2 - scroller.clientHeight / 2
+    scroller.scrollTo({ top: Math.max(0, top), behavior: smooth ? 'smooth' : 'auto' })
+  }
+
+  /**
+   * Shows a row's details; a second click on the same row hides them.
+   *
+   * @param {TimelineNode} node - The row clicked.
+   * @example
+   * select(node)
+   */
+  function select(node: TimelineNode): void {
+    selected = selected === node.id ? null : node.id
+  }
+
+  /**
+   * From the details pane: follows a route to where it lands, and focuses that row.
+   *
+   * @param {string} id - The row to go to.
+   * @returns {Promise<void>} Settles once the row has focus.
+   * @example
+   * await goTo(next.to)
+   */
+  async function goTo(id: string): Promise<void> {
+    const node = byId.get(id)
+    if (node === undefined) return
+    selected = id
+    reveal(node, true)
+    await tick()
+    scroller?.querySelector<HTMLButtonElement>(`[data-row="${CSS.escape(id)}"]`)?.focus({
+      preventScroll: true,
+    })
+  }
+
+  /**
+   * Moves the open journey back to a row's screen.
+   *
+   * @param {TimelineNode} node - A visited screen.
+   * @example
+   * goBack(node)
+   */
+  function goBack(node: TimelineNode): void {
+    if (canJump(node) && node.stepKey !== null) onJump(node.stepKey)
+  }
+
+  /**
+   * Clears the selection on Escape, and only that — the panel itself stays open.
+   *
+   * @param {KeyboardEvent} event - The key event.
+   * @example
+   * onKeydown(event)
+   */
+  function onKeydown(event: KeyboardEvent): void {
+    if (event.key !== 'Escape' || selected === null) return
+    event.stopPropagation()
+    selected = null
+  }
+
+  /**
+   * Whether a line lights up: either end is the row the reviewer is looking at.
+   *
+   * @param {string} from - The line's upper row.
+   * @param {string} to - The line's lower row.
+   * @returns {boolean} True when either end is selected.
+   * @example
+   * active(edge.from, edge.to)
+   */
+  function active(from: string, to: string): boolean {
+    return selected !== null && (selected === from || selected === to)
+  }
+
+  // Scroll to where the visitor is whenever a DIFFERENT timeline arrives — keyed on its shape, as
+  // the map is, so a batch of fields landing does not yank the list from under the reviewer.
+  const shape = $derived(
+    [
+      layout.nodes.length,
+      layout.lanes,
+      layout.nodes.find((node) => node.state === 'current')?.id ?? '',
+    ].join(':'),
+  )
+  let revealed = ''
+
+  $effect(() => {
+    if (shape === revealed || scroller === undefined) return
+    revealed = shape
+    const here = layout.nodes.find((node) => node.state === 'current')
+    if (here !== undefined) reveal(here, false)
+    else scroller.scrollTo({ top: 0 })
+  })
+</script>
+
+<!-- svelte-ignore a11y_no_static_element_interactions -->
+<div class="timeline" onkeydown={onKeydown}>
+  <div class="body">
+    <div class="scroller" bind:this={scroller} data-testid="devtools-journey-timeline">
+      <div
+        class="canvas"
+        style:--height="{layout.height}px"
+        style:--graph="{layout.width}px"
+        style:--row="{ROW_HEIGHT}px"
+      >
+        {#each layout.nodes as node (node.id)}
+          {@const loops = node.next.filter((next) => next.loop)}
+          <button
+            type="button"
+            class="row kind-{node.kind} state-{node.state}"
+            class:selected={selected === node.id}
+            style:--top="{node.row * ROW_HEIGHT}px"
+            data-row={node.id}
+            data-testid={node.kind === 'screen' ? 'devtools-journey-screen' : undefined}
+            onclick={() => select(node)}
+          >
+            <span class="label">
+              {#if node.kind === 'decision'}<span class="if">If</span>{/if}
+              {node.label}
+            </span>
+            {#if node.state === 'current'}
+              <span class="here">You are here</span>
+            {/if}
+            {#each loops as loop (loop.to)}
+              <span class="loop" title="Loops back to {labelOf(loop.to)}"
+                >↩ {loop.label === null ? '' : `${loop.label}: `}back to {labelOf(loop.to)}</span
+              >
+            {/each}
+            {#each node.ends as end (end.key)}
+              <span class="end" title="Hands off to {end.label}, behind the scenes"
+                >⇥ {end.armLabel === null ? '' : `${end.armLabel}: `}{end.label}</span
+              >
+            {/each}
+          </button>
+        {/each}
+
+        <svg class="graph" width={layout.width} height={layout.height} aria-hidden="true">
+          {#each layout.edges as edge (edge.id)}
+            <path
+              class="edge"
+              class:travelled={edge.travelled}
+              class:active={active(edge.from, edge.to)}
+              stroke={paint(edge.colour)}
+              d={edge.path}
+            />
+          {/each}
+          {#each layout.nodes as node (node.id)}
+            {#if node.state === 'current'}
+              <circle class="halo" cx={node.x} cy={node.y} r={RADIUS[node.kind] + 6} />
+            {/if}
+            <TimelineMarker
+              kind={node.kind}
+              x={node.x}
+              y={node.y}
+              r={RADIUS[node.kind]}
+              fill={paint(node.colour)}
+              state={node.state}
+              selected={selected === node.id}
+            />
+          {/each}
+        </svg>
+      </div>
+    </div>
+
+    <aside class="details" aria-live="polite" data-testid="devtools-journey-details">
+      {#if selectedNode === null}
+        <p class="hint">
+          Pick a row to see what it does and where it leads. Branches run down the lanes on the left
+          and merge back where they meet.
+        </p>
+      {:else}
+        <div class="head">
+          <svg class="key-dot" width="14" height="14" aria-hidden="true">
+            <TimelineMarker
+              kind={selectedNode.kind}
+              x={7}
+              y={7}
+              r={5.5}
+              fill={paint(selectedNode.colour)}
+            />
+          </svg>
+          <span class="kind">{KIND_LABELS[selectedNode.kind]}</span>
+          <button type="button" class="close" aria-label="Close" onclick={() => (selected = null)}
+            >×</button
+          >
+        </div>
+
+        <p class="title">{selectedNode.label}</p>
+
+        {#if selectedNode.state === 'current'}
+          <p class="state">You are here</p>
+        {:else if selectedNode.state === 'visited'}
+          <p class="state">On the route taken this session</p>
+        {/if}
+
+        {#if selectedNode.detail !== null}
+          <code class="key">{selectedNode.detail}</code>
+        {/if}
+
+        {#if selectedNode.next.length > 0 || selectedNode.ends.length > 0}
+          <div class="next">
+            <span class="next-title">Leads to</span>
+            <ul>
+              {#each selectedNode.next as next (next.to)}
+                <li>
+                  {#if next.label !== null}
+                    <span class="arm arm-{next.arm ?? 'none'}">{next.label}</span>
+                  {/if}
+                  <button type="button" class="next-link" onclick={() => void goTo(next.to)}>
+                    {next.loop ? '↩ back to ' : ''}{labelOf(next.to)}
+                  </button>
+                </li>
+              {/each}
+              {#each selectedNode.ends as end (end.key)}
+                <li>
+                  {#if end.armLabel !== null}
+                    <span class="arm arm-{end.arm ?? 'none'}">{end.armLabel}</span>
+                  {/if}
+                  <span class="end-text">Ends: {end.label} (behind the scenes)</span>
+                </li>
+              {/each}
+            </ul>
+          </div>
+        {:else}
+          <p class="text">The journey ends here.</p>
+        {/if}
+
+        {#if selectedNode.rule !== null}
+          <!-- The sentence is lossy by design; the verbatim rule is what makes that safe. -->
+          <pre class="rule">{selectedNode.rule}</pre>
+        {/if}
+
+        {#if canJump(selectedNode)}
+          <button type="button" class="action" onclick={() => goBack(selectedNode)}>
+            Go back to this screen
+          </button>
+        {/if}
+      {/if}
+    </aside>
+  </div>
+
+  <p class="legend">
+    <span class="key-swatch kind-start"></span> Start
+    <span class="key-swatch kind-screen"></span> Screen
+    <span class="key-swatch kind-decision"></span> Decision
+    <span class="key-swatch kind-journey"></span> Opens another journey
+    <span class="key-swatch seen"></span> Seen
+    <span class="key-swatch current"></span> You are here
+    <span
+      >· each colour is one branch · a decision's Yes runs straight on · ↩ loops back · ⇥ hands off</span
+    >
+  </p>
+</div>
+
+<style>
+  .timeline {
+    flex: 1;
+    min-height: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2);
+  }
+
+  /* Takes the height the legend leaves in the frame, as the map's viewport does. */
+  .body {
+    flex: 1;
+    min-height: 0;
+    display: grid;
+    grid-template-columns: minmax(0, 1fr) 320px;
+    grid-template-rows: minmax(0, 1fr);
+    gap: var(--space-3);
+  }
+
+  @media (max-width: 760px) {
+    .body {
+      grid-template-columns: minmax(0, 1fr);
+      grid-template-rows: minmax(0, 2fr) minmax(0, 1fr);
+    }
+  }
+
+  .scroller,
+  .details {
+    box-sizing: border-box;
+    min-height: 0;
+    border: 1px solid var(--color-gray-200);
+    border-radius: var(--radius-lg);
+    background-color: var(--color-white);
+    overflow-y: auto;
+    scrollbar-width: thin;
+  }
+
+  .canvas {
+    position: relative;
+    height: var(--height);
+    min-width: 100%;
+  }
+
+  .graph {
+    position: absolute;
+    top: 0;
+    left: 0;
+    pointer-events: none;
+    overflow: visible;
+  }
+
+  .row {
+    position: absolute;
+    top: var(--top);
+    left: 0;
+    right: 0;
+    height: var(--row);
+    display: flex;
+    align-items: center;
+    gap: var(--space-2);
+    padding: 0 var(--space-3) 0 calc(var(--graph) + var(--space-1));
+    font-family: inherit;
+    text-align: left;
+    background: none;
+    border: none;
+    cursor: pointer;
+  }
+
+  .row:hover {
+    background-color: var(--color-gray-50);
+  }
+
+  .row.selected {
+    background-color: #eff6ff;
+  }
+
+  .row:focus-visible {
+    outline: var(--ring-width) solid var(--ring-color);
+    outline-offset: -2px;
+  }
+
+  .label {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-size: var(--text-sm);
+    color: var(--color-gray-900);
+  }
+
+  .kind-decision .label {
+    color: var(--color-gray-700);
+  }
+
+  .kind-start .label {
+    font-weight: var(--font-semibold);
+  }
+
+  .if {
+    font-weight: var(--font-semibold);
+    color: #b45309;
+  }
+
+  .state-visited .label,
+  .state-current .label {
+    color: var(--color-blue-700);
+  }
+
+  .here {
+    flex-shrink: 0;
+    padding: 1px var(--space-1-5);
+    font-size: 10px;
+    font-weight: var(--font-medium);
+    color: var(--color-blue-700);
+    background-color: #dbeafe;
+    border-radius: var(--radius-full);
+  }
+
+  .end {
+    flex-shrink: 0;
+    max-width: 40%;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    padding: 1px var(--space-1-5);
+    font-size: 10px;
+    color: var(--color-gray-600);
+    background-color: var(--color-gray-100);
+    border-radius: var(--radius-full);
+  }
+
+  .end-text {
+    color: var(--color-gray-600);
+  }
+
+  .loop {
+    flex-shrink: 0;
+    max-width: 40%;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    padding: 1px var(--space-1-5);
+    font-size: 10px;
+    color: #0369a1;
+    background-color: #e0f2fe;
+    border-radius: var(--radius-full);
+  }
+
+  /* The stroke is the branch's colour, set on the element; only the weight is styled here. */
+  .edge {
+    fill: none;
+    stroke-width: 2;
+    opacity: 0.85;
+  }
+
+  /* The visitor's route: the same branch colours, drawn heavier and at full strength. */
+  .edge.travelled {
+    stroke-width: 4;
+    opacity: 1;
+  }
+
+  .edge.active {
+    stroke-width: 3.5;
+    filter: drop-shadow(0 0 2px rgb(37 99 235 / 45%));
+  }
+
+  .halo {
+    fill: #bfdbfe;
+  }
+
+  .details {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2);
+    padding: var(--space-3);
+  }
+
+  .hint,
+  .text {
+    margin: 0;
+    font-size: var(--text-xs);
+    color: var(--color-gray-500);
+  }
+
+  .head {
+    display: flex;
+    align-items: center;
+    gap: var(--space-1-5);
+  }
+
+  .kind {
+    flex: 1;
+    font-size: var(--text-xs);
+    font-weight: var(--font-medium);
+    color: var(--color-gray-500);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+  }
+
+  .close {
+    width: 24px;
+    height: 24px;
+    padding: 0;
+    font-family: inherit;
+    font-size: var(--text-base);
+    line-height: 1;
+    color: var(--color-gray-500);
+    background: none;
+    border: none;
+    border-radius: var(--radius-md);
+    cursor: pointer;
+  }
+
+  .close:hover {
+    background-color: var(--color-gray-100);
+    color: var(--color-gray-900);
+  }
+
+  .close:focus-visible,
+  .action:focus-visible,
+  .next-link:focus-visible {
+    outline: var(--ring-width) solid var(--ring-color);
+    outline-offset: var(--ring-offset);
+  }
+
+  .title {
+    margin: 0;
+    font-size: var(--text-sm);
+    font-weight: var(--font-semibold);
+    color: var(--color-gray-900);
+    overflow-wrap: anywhere;
+  }
+
+  .state {
+    margin: 0;
+    font-size: var(--text-xs);
+    font-weight: var(--font-medium);
+    color: var(--color-blue-600);
+  }
+
+  .key,
+  .rule {
+    font-family: 'Monaco', 'Menlo', 'Courier New', monospace;
+    font-size: 10px;
+    color: var(--color-gray-500);
+  }
+
+  .key {
+    align-self: flex-start;
+    padding: 1px var(--space-1);
+    background-color: var(--color-gray-100);
+    border-radius: var(--radius-sm);
+    overflow-wrap: anywhere;
+  }
+
+  .next {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-1);
+  }
+
+  .next-title {
+    font-size: var(--text-xs);
+    font-weight: var(--font-medium);
+    color: var(--color-gray-500);
+  }
+
+  .next ul {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-1);
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .next li {
+    display: flex;
+    align-items: baseline;
+    gap: var(--space-1-5);
+    font-size: var(--text-xs);
+  }
+
+  .arm {
+    flex-shrink: 0;
+    font-weight: 700;
+  }
+
+  .arm.arm-yes {
+    color: #10b981;
+  }
+
+  .arm.arm-no {
+    color: var(--color-red-500);
+  }
+
+  .next-link {
+    padding: 0;
+    font-family: inherit;
+    font-size: var(--text-xs);
+    text-align: left;
+    color: var(--color-blue-600);
+    background: none;
+    border: none;
+    cursor: pointer;
+    overflow-wrap: anywhere;
+  }
+
+  .next-link:hover {
+    text-decoration: underline;
+  }
+
+  .rule {
+    max-height: 180px;
+    margin: 0;
+    padding: var(--space-2);
+    overflow: auto;
+    background-color: var(--color-gray-50);
+    border: 1px solid var(--color-gray-200);
+    border-radius: var(--radius-md);
+    white-space: pre-wrap;
+  }
+
+  .action {
+    align-self: flex-start;
+    padding: var(--space-1) var(--space-3);
+    font-family: inherit;
+    font-size: var(--text-xs);
+    font-weight: var(--font-medium);
+    color: var(--color-white);
+    background-color: var(--color-blue-600);
+    border: none;
+    border-radius: var(--radius-md);
+    cursor: pointer;
+  }
+
+  .action:hover {
+    background-color: var(--color-blue-700);
+  }
+
+  .legend {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: var(--space-1-5);
+    margin: 0;
+    font-size: var(--text-xs);
+    color: var(--color-gray-500);
+  }
+
+  /* Shapes only — the colours belong to branches, so the key is in a neutral grey. */
+  .key-swatch {
+    width: 10px;
+    height: 10px;
+    margin-left: var(--space-1);
+    border-radius: var(--radius-full);
+    background-color: #64748b;
+  }
+
+  .key-swatch.kind-start {
+    width: 13px;
+    height: 13px;
+  }
+
+  .key-swatch.kind-decision {
+    width: 9px;
+    height: 9px;
+    border-radius: 0;
+    transform: rotate(45deg);
+  }
+
+  .key-swatch.kind-journey {
+    border-radius: 2px;
+  }
+
+  .key-swatch.seen {
+    background-color: var(--color-white);
+    box-shadow: 0 0 0 2px #1e3a8a;
+  }
+
+  .key-swatch.current {
+    background-color: var(--color-white);
+    box-shadow:
+      0 0 0 2px #1e3a8a,
+      0 0 0 5px #bfdbfe;
+  }
+</style>