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

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

@@ -0,0 +1,584 @@
+<script lang="ts">
+  /**
+   * @file The Journey map tab: any journey's flow in plain English — the Developer group's
+   * experience tree without the node ids or the raw JSON Logic. It opens on the journey in front
+   * of the reviewer, and the picker reaches every other experience in the workspace.
+   *
+   * Navigation is BACKWARDS ONLY, and only in the journey that is OPEN. A screen already visited is
+   * a plain `goToStepByKey`: the flow has been through every action in between, so returning to it
+   * is safe. A screen AHEAD is rendered but not clickable — jumping forward skips the actions that
+   * make it renderable, and the screen it lands on can render an error state no visitor could
+   * reach. Forward motion belongs to the journey itself, or to a custom tool that replays one.
+   *
+   * THREE VIEWS, ONE GRAPH. The outline answers "where am I, and why did it go there"; the map
+   * answers "what shape is this, and where does each branch end"; the timeline answers "in what
+   * order, and where do the branches meet again". All three read the same `treeStore` through the
+   * same vocabulary modules, so a screen is named identically in each and they cannot drift.
+   */
+  import type { Picked } from '@picked/client'
+  import { Badge, Banner, Button, Card, EmptyState, Stack } from '../../ui'
+  import { buildOutline, buildTimeline, buildTree } from '../../derive'
+  import type { FieldLookup, OutlineRow, SafetyPosture, Trails } from '../../derive'
+  import type { JourneyView } from '../../session'
+  import JourneyMap from './JourneyMap.svelte'
+  import JourneyTimeline from './JourneyTimeline.svelte'
+
+  interface JourneyPanelProps {
+    client: Picked
+    posture: SafetyPosture
+    journey: JourneyView | null
+    /** Step keys entered this session, per experience, from the session record. */
+    trails: Trails
+    /** Experience keys the picker never lists and the tab never follows. */
+    hiddenKeys: ReadonlySet<string>
+  }
+
+  const { client, posture, journey, trails, hiddenKeys }: JourneyPanelProps = $props()
+
+  /** The slice of an experience's flow graph the three views read. */
+  interface FlowGraph {
+    nodes: { id: string; type: string; name?: string }[]
+    edges: { id: string; sourceNodeId: string; destinationNodeId: string; sourceHandle?: string }[]
+    conditions: { id: string; name: string; logic: unknown }[]
+  }
+
+  interface JourneyChoice {
+    key: string
+    name: string
+    /** Nodes in its flow — read once, to pick a sensible default when no journey is open. */
+    size: number
+  }
+
+  const EMPTY_GRAPH: FlowGraph = { nodes: [], edges: [], conditions: [] }
+  const NOTHING_VISITED: ReadonlySet<string> = new Set()
+
+  // SDK stores read straight off the prop: effector stores meet Svelte's store contract, so `$`
+  // subscribes, and `$derived` keeps it on whichever client the panel is given.
+  const experiences = $derived(client.experiences.listStore)
+  // `null` FOLLOWS the open journey, so the tab keeps tracking the visitor until the reviewer picks
+  // something else on purpose.
+  let picked = $state<string | null>(null)
+  let expandedRule = $state<string | null>(null)
+  // The union goes on `$state`, not on the `let`. With the annotation alone TypeScript narrows the
+  // variable to its initial literal and the `view === 'map'` below reads as a comparison that can
+  // never hold — `$derived` is an expression in this same scope, so nothing widens it back.
+  let view = $state<'outline' | 'map' | 'timeline'>('map')
+
+  /** The open journey, unless it is one the tab never follows. */
+  const followed = $derived(
+    journey !== null && !hiddenKeys.has(journey.experienceKey) ? journey : null,
+  )
+
+  const choices = $derived<JourneyChoice[]>(
+    $experiences
+      .filter((experience) => !hiddenKeys.has(experience.key))
+      .map((experience) => ({
+        key: experience.key,
+        name: experience.name,
+        size: experience.treeStore.getState().nodes.length,
+      }))
+      .sort((a, b) => a.name.localeCompare(b.name)),
+  )
+
+  /** With nothing open and nothing picked, the largest flow — the main journey — is the one to show. */
+  const largest = $derived(
+    choices.reduce<JourneyChoice | null>(
+      (best, choice) => (best === null || choice.size > best.size ? choice : best),
+      null,
+    ),
+  )
+
+  const selectedKey = $derived(picked ?? followed?.experienceKey ?? largest?.key ?? null)
+  /** The trail, "you are here" and every jump belong to the journey the visitor is in, and only it. */
+  const isOpen = $derived(followed !== null && followed.experienceKey === selectedKey)
+
+  // The graph lives on the EXPERIENCE, not the instance, as its own store. Read through a `$derived`
+  // store variable, so Svelte re-subscribes when the selection points at a different journey and
+  // drops the old one — no hand-kept nested subscription.
+  //
+  // It reads the shared `listStore` rather than `experiences.getByKey`, which mints a NEW derived
+  // store per call and never releases it.
+  const treeStore = $derived(
+    selectedKey === null
+      ? undefined
+      : $experiences.find((experience) => experience.key === selectedKey)?.treeStore,
+  )
+  const graph: FlowGraph = $derived($treeStore ?? EMPTY_GRAPH)
+
+  // Fields arrive asynchronously and AFTER the graph does. Read reactively, so the views re-render
+  // into plain English once they land — read once instead, and a decision authored on a field that
+  // had not loaded yet would stay labelled by its raw key forever.
+  const fields = $derived(client.fields.listStore)
+
+  const fieldsByKey = $derived(new Map($fields.map((field) => [field.key, field])))
+
+  const fieldLookup = $derived<FieldLookup>((key) => {
+    const field = fieldsByKey.get(key)
+    if (field === undefined) return undefined
+
+    return { name: field.name, label: field.label, options: field.options ?? null }
+  })
+
+  const source = $derived({
+    nodes: graph.nodes,
+    edges: graph.edges,
+    conditions: graph.conditions,
+    fieldLookup,
+    visited: (selectedKey === null ? undefined : trails.get(selectedKey)) ?? NOTHING_VISITED,
+    currentStepKey: isOpen ? (followed?.stepKey ?? null) : null,
+  })
+
+  const rows = $derived(buildOutline(source))
+
+  // Laid out only while its view is on screen — the map is the default, so in practice nearly
+  // always, but a reviewer reading the outline pays nothing for it.
+  const layout = $derived(view === 'map' ? buildTree(source) : null)
+  const timeline = $derived(view === 'timeline' ? buildTimeline(source) : null)
+
+  const canNavigate = $derived(posture.canNavigate && isOpen)
+
+  /**
+   * Whether an outline row can take the visitor back to its screen.
+   *
+   * @param {OutlineRow} row - The row to test.
+   * @returns {boolean} True for a visited screen in the open journey, when the posture allows it.
+   * @example
+   * canJump(row) // true for a screen on the route taken
+   */
+  function canJump(row: OutlineRow): boolean {
+    return row.kind === 'screen' && row.state === 'visited' && row.stepKey !== null && canNavigate
+  }
+
+  /**
+   * Why a screen row cannot be jumped to, as its tooltip.
+   *
+   * @param {OutlineRow} row - The row to explain.
+   * @returns {string | undefined} The reason, or undefined when there is nothing to explain.
+   * @example
+   * jumpReason(aheadRow) // "You haven't answered enough to get here yet."
+   */
+  function jumpReason(row: OutlineRow): string | undefined {
+    if (row.kind !== 'screen') return undefined
+    if (posture.reason !== null) return posture.reason
+    if (!isOpen) return "This journey isn't open, so there is nowhere to go back to."
+    if (row.state === 'current') return "You're on this screen."
+    if (row.state === 'ahead') return "You haven't answered enough to get here yet."
+    return undefined
+  }
+
+  /**
+   * Moves the open journey back to a screen.
+   *
+   * @param {string} stepKey - The screen's step key.
+   * @example
+   * jumpTo('contact-details')
+   */
+  function jumpTo(stepKey: string): void {
+    if (followed === null || !isOpen) return
+    followed.goToStepByKey(stepKey)
+  }
+
+  /**
+   * Moves the open journey back to an outline row's screen.
+   *
+   * @param {OutlineRow} row - The row the reviewer chose.
+   * @example
+   * jump(row)
+   */
+  function jump(row: OutlineRow): void {
+    if (row.kind !== 'screen' || row.stepKey === null) return
+    jumpTo(row.stepKey)
+  }
+
+  /**
+   * Shows the journey chosen in the picker. Picking the open journey goes back to FOLLOWING it,
+   * rather than pinning it.
+   *
+   * @param {Event} event - The picker's change event.
+   * @example
+   * pick(event)
+   */
+  function pick(event: Event): void {
+    if (!(event.currentTarget instanceof HTMLSelectElement)) return
+    const key = event.currentTarget.value
+    picked = key === followed?.experienceKey ? null : key
+  }
+
+  /**
+   * Shows a decision's verbatim rule, or hides it again.
+   *
+   * @param {string} id - The decision row's id.
+   * @example
+   * toggleRule(row.id)
+   */
+  function toggleRule(id: string): void {
+    expandedRule = expandedRule === id ? null : id
+  }
+</script>
+
+<Stack direction="vertical" gap="medium">
+  {#if selectedKey === null}
+    <EmptyState
+      message="No journeys yet"
+      hint="The workspace has not loaded its experiences. Reload the page if this does not change."
+    />
+  {:else}
+    <!-- One row: how to look on the left, what to look at on the right. -->
+    <div class="controls">
+      <div class="views" role="group" aria-label="Journey view">
+        <button
+          type="button"
+          class="view"
+          class:selected={view === 'outline'}
+          aria-pressed={view === 'outline'}
+          data-testid="devtools-journey-view-outline"
+          onclick={() => (view = 'outline')}
+        >
+          Outline
+        </button>
+        <button
+          type="button"
+          class="view"
+          class:selected={view === 'map'}
+          aria-pressed={view === 'map'}
+          data-testid="devtools-journey-view-map"
+          onclick={() => (view = 'map')}
+        >
+          Map
+        </button>
+        <button
+          type="button"
+          class="view"
+          class:selected={view === 'timeline'}
+          aria-pressed={view === 'timeline'}
+          data-testid="devtools-journey-view-timeline"
+          onclick={() => (view = 'timeline')}
+        >
+          Timeline
+        </button>
+      </div>
+
+      <div class="picker">
+        {#if followed !== null && !isOpen}
+          <Button variant="ghost" size="small" onclick={() => (picked = null)}>
+            Back to the open journey
+          </Button>
+        {/if}
+        <select
+          class="picker-select"
+          aria-label="Journey"
+          value={selectedKey}
+          onchange={pick}
+          data-testid="devtools-journey-picker"
+        >
+          {#each choices as choice (choice.key)}
+            <option value={choice.key}>
+              {choice.name}{choice.key === followed?.experienceKey ? ' — open now' : ''}
+            </option>
+          {/each}
+        </select>
+      </div>
+    </div>
+
+    {#if posture.readOnly && posture.reason !== null}
+      <Banner status="warning" testId="devtools-journey-readonly">{posture.reason}</Banner>
+    {/if}
+
+    <Card sectioned>
+      {#if rows.length === 0}
+        <EmptyState
+          message="This journey has no screens yet"
+          hint="Its flow has not loaded, or it is built entirely from background steps."
+        />
+      {:else if layout !== null}
+        <!-- Keyed on the experience, so a switch re-frames the map instead of keeping the last
+             journey's pan and zoom over a different tree. -->
+        {#key selectedKey}
+          <JourneyMap {layout} {canNavigate} onJump={jumpTo} />
+        {/key}
+      {:else if timeline !== null}
+        {#key selectedKey}
+          <JourneyTimeline layout={timeline} {canNavigate} onJump={jumpTo} />
+        {/key}
+      {:else}
+        <ul class="outline" data-testid="devtools-journey">
+          {#each rows as row (row.id)}
+            <li class="row kind-{row.kind}" style:--depth={row.depth}>
+              {#if row.kind === 'screen'}
+                <button
+                  type="button"
+                  class="screen state-{row.state}"
+                  class:jumpable={canJump(row)}
+                  disabled={!canJump(row)}
+                  title={jumpReason(row)}
+                  data-testid="devtools-journey-screen"
+                  onclick={() => jump(row)}
+                >
+                  <span class="marker" aria-hidden="true"></span>
+                  <span class="screen-label">{row.label}</span>
+                  {#if row.state === 'current'}
+                    <Badge status="info" size="small">You are here</Badge>
+                  {:else if row.state === 'visited' && canNavigate}
+                    <span class="jump-hint">Go back</span>
+                  {/if}
+                </button>
+              {:else if row.kind === 'decision'}
+                <div class="decision">
+                  <span class="decision-label">If {row.label}</span>
+                  <button type="button" class="disclosure" onclick={() => toggleRule(row.id)}>
+                    {expandedRule === row.id ? 'Hide rule' : 'Show rule'}
+                  </button>
+                </div>
+                {#if expandedRule === row.id}
+                  <!-- The sentence above is lossy by design; this is what makes that safe. -->
+                  <pre class="rule">{row.rule}</pre>
+                {/if}
+              {:else if row.kind === 'arm'}
+                <span class="arm">{row.label}</span>
+              {:else if row.kind === 'end'}
+                <span class="end-row">⇥ Ends: {row.label} (behind the scenes)</span>
+              {:else if row.kind === 'journey'}
+                <span class="journey-row">
+                  <span class="marker muted" aria-hidden="true"></span>
+                  Opens {row.label}
+                </span>
+              {:else if row.kind === 'backref'}
+                <span class="backref">↩ back to {row.label}</span>
+              {:else}
+                <span class="start">{row.label}</span>
+              {/if}
+            </li>
+          {/each}
+        </ul>
+      {/if}
+    </Card>
+  {/if}
+</Stack>
+
+<style>
+  .controls {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--space-2);
+    flex-wrap: wrap;
+  }
+
+  .picker {
+    display: flex;
+    align-items: center;
+    gap: var(--space-2);
+  }
+
+  .picker-select {
+    min-width: 260px;
+    max-width: 100%;
+    padding: var(--space-1) var(--space-2);
+    font-family: inherit;
+    font-size: var(--text-sm);
+    color: var(--color-gray-900);
+    background-color: var(--color-white);
+    border: 1px solid var(--color-gray-300);
+    border-radius: var(--radius-md);
+  }
+
+  .picker-select:focus-visible {
+    outline: var(--ring-width) solid var(--ring-color);
+    outline-offset: var(--ring-offset);
+  }
+
+  .views {
+    display: inline-flex;
+    padding: 2px;
+    gap: 2px;
+    background-color: var(--color-gray-100);
+    border-radius: var(--radius-md);
+  }
+
+  .view {
+    padding: var(--space-0-5) var(--space-3);
+    font-family: inherit;
+    font-size: var(--text-xs);
+    font-weight: var(--font-medium);
+    color: var(--color-gray-500);
+    background: none;
+    border: none;
+    border-radius: var(--radius-sm);
+    cursor: pointer;
+  }
+
+  .view.selected {
+    color: var(--color-gray-900);
+    background-color: var(--color-white);
+    box-shadow: var(--shadow-card);
+  }
+
+  .view:focus-visible {
+    outline: var(--ring-width) solid var(--ring-color);
+    outline-offset: -1px;
+  }
+
+  .outline {
+    list-style: none;
+    margin: 0;
+    padding: var(--space-2) var(--space-1) var(--space-3);
+  }
+
+  .row {
+    padding-left: calc(var(--depth) * var(--space-3));
+  }
+
+  .screen {
+    display: flex;
+    align-items: center;
+    gap: var(--space-2);
+    width: 100%;
+    text-align: left;
+    background: none;
+    border: none;
+    font-family: inherit;
+    font-size: var(--text-sm);
+    color: var(--color-gray-900);
+    padding: var(--space-1-5) var(--space-2);
+    border-radius: var(--radius-md);
+  }
+
+  .screen:disabled {
+    cursor: default;
+  }
+
+  .screen.jumpable {
+    cursor: pointer;
+  }
+
+  .screen.jumpable:hover {
+    background-color: var(--color-gray-50);
+  }
+
+  .screen:focus-visible,
+  .disclosure:focus-visible {
+    outline: var(--ring-width) solid var(--ring-color);
+    outline-offset: calc(-1 * var(--ring-width));
+  }
+
+  .screen-label {
+    flex: 1;
+    min-width: 0;
+    overflow-wrap: anywhere;
+  }
+
+  .state-ahead .screen-label {
+    color: var(--color-gray-500);
+  }
+
+  .state-current .screen-label {
+    font-weight: var(--font-semibold);
+  }
+
+  .marker {
+    width: 8px;
+    height: 8px;
+    border-radius: var(--radius-full);
+    background-color: var(--color-gray-300);
+    flex-shrink: 0;
+  }
+
+  .state-visited .marker {
+    background-color: var(--color-blue-600);
+  }
+
+  .state-current .marker {
+    background-color: var(--color-blue-600);
+    box-shadow: 0 0 0 3px #dbeafe;
+  }
+
+  .marker.muted {
+    width: 6px;
+    height: 6px;
+    background-color: var(--color-gray-200);
+  }
+
+  .jump-hint {
+    font-size: var(--text-xs);
+    color: var(--color-blue-600);
+    opacity: 0;
+  }
+
+  .screen.jumpable:hover .jump-hint,
+  .screen.jumpable:focus-visible .jump-hint {
+    opacity: 1;
+  }
+
+  .decision {
+    display: flex;
+    align-items: baseline;
+    gap: var(--space-2);
+    padding: var(--space-2) var(--space-2) var(--space-1);
+  }
+
+  .decision-label {
+    flex: 1;
+    min-width: 0;
+    font-size: var(--text-sm);
+    font-weight: var(--font-medium);
+    color: var(--color-gray-700);
+    overflow-wrap: anywhere;
+  }
+
+  .disclosure {
+    background: none;
+    border: none;
+    font-family: inherit;
+    font-size: var(--text-xs);
+    color: var(--color-blue-600);
+    cursor: pointer;
+    padding: 0;
+    flex-shrink: 0;
+  }
+
+  .rule {
+    margin: 0 var(--space-2) var(--space-2);
+    padding: var(--space-2);
+    background-color: var(--color-gray-50);
+    border: 1px solid var(--color-gray-200);
+    border-radius: var(--radius-md);
+    font-family: 'Monaco', 'Menlo', 'Courier New', monospace;
+    font-size: 10px;
+    white-space: pre-wrap;
+    overflow-x: auto;
+  }
+
+  .arm {
+    display: inline-block;
+    font-size: var(--text-xs);
+    font-weight: var(--font-medium);
+    color: var(--color-gray-500);
+    padding: var(--space-1) var(--space-2);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+  }
+
+  .end-row {
+    display: block;
+    padding: var(--space-1) var(--space-2);
+    font-size: var(--text-xs);
+    color: var(--color-gray-500);
+  }
+
+  .journey-row,
+  .backref,
+  .start {
+    display: flex;
+    align-items: center;
+    gap: var(--space-2);
+    padding: var(--space-1-5) var(--space-2);
+    font-size: var(--text-xs);
+    color: var(--color-gray-500);
+  }
+
+  .start {
+    font-size: var(--text-sm);
+    font-weight: var(--font-medium);
+    color: var(--color-gray-700);
+  }
+</style>