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

package/dist/plugins/devtools/review/answers/AnswersPanel.svelte

@@ -0,0 +1,526 @@
+<script lang="ts">
+  /**
+   * @file The Answers tab: every question a journey can ask, and the answer given — the Developer
+   * group's Responses screen in a reviewer's vocabulary.
+   *
+   * Four differences from that screen, all deliberate:
+   *  1. Rows are titled by the QUESTION the visitor saw (`field.label`), not `field.key`.
+   *  2. An object answer (an address, a chosen plan) is read-only with a Copy button. A reviewer
+   *     hand-editing a resolved object is how a record ends up pointing at the wrong thing.
+   *  3. An edit reports the SDK's own validation message on the row that caused it, and keeps the
+   *     draft so the reviewer can correct it.
+   *  4. Only fields a screen asks are listed (`asked`). What code commits behind the scenes is not
+   *     an answer anyone gave.
+   */
+  import type { Field, FieldValue, Picked } from '@picked/client'
+  import { Badge, Banner, Button, Card, CopyButton, EmptyState, Stack, Text } from '../../ui'
+  import { describeAnswer, systemPayload } from '../../derive'
+  import type { AnswerView, SafetyPosture } from '../../derive'
+
+  interface AnswersPanelProps {
+    client: Picked
+    posture: SafetyPosture
+    /** Every field a journey's screens ask — the rest is committed by code, not answered. */
+    asked: ReadonlySet<string>
+    /** A button offered after an edit, such as re-running a fetch the answers feed. */
+    followUp: { label: string; run: () => void } | null
+  }
+
+  const { client, posture, asked, followUp }: AnswersPanelProps = $props()
+
+  type Filter = 'answered' | 'unanswered' | 'all'
+
+  interface AnswerRow {
+    field: Field
+    view: AnswerView
+    value: unknown
+  }
+
+  // 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 fields = $derived(client.fields.listStore)
+  const responsesStore = $derived(client.responses.getAllStore)
+  // `unknown`, not `FieldValue`: the store's index signature types an ABSENT key as a PRESENT value,
+  // so a `=== undefined` guard would read as dead code while being the case that actually happens.
+  const responses: Readonly<Record<string, unknown>> = $derived($responsesStore)
+
+  let filter = $state<Filter>('answered')
+  let editingKey = $state<string | null>(null)
+  let draft = $state('')
+  let draftMultiple = $state<string[]>([])
+  let rowError = $state<string | null>(null)
+  let confirmingReset = $state(false)
+  let edited = $state(false)
+
+  /** Why a write is withheld, as the withheld control's tooltip. */
+  const withheld = $derived(posture.canEditAnswers ? undefined : (posture.reason ?? undefined))
+
+  const rows = $derived<AnswerRow[]>(
+    $fields
+      .filter((field) => asked.has(field.key))
+      .map((field) => ({
+        field,
+        value: responses[field.key],
+        view: describeAnswer(responses[field.key], field),
+      }))
+      .sort((a, b) => a.view.title.localeCompare(b.view.title)),
+  )
+
+  const answeredCount = $derived(rows.filter((row) => row.view.answered).length)
+  const visibleRows = $derived(
+    rows.filter((row) => {
+      if (filter === 'answered') return row.view.answered
+      if (filter === 'unanswered') return !row.view.answered
+      return true
+    }),
+  )
+
+  const filters = $derived<{ value: Filter; label: string }[]>([
+    { value: 'answered', label: `Answered (${answeredCount})` },
+    { value: 'unanswered', label: `Not answered (${rows.length - answeredCount})` },
+    { value: 'all', label: 'All' },
+  ])
+
+  /**
+   * Opens a row's editor, seeded with the answer it holds now.
+   *
+   * @param {AnswerRow} row - The row to edit.
+   * @example
+   * startEdit(row) // the row shows its options, or a text box, with Save and Cancel
+   */
+  function startEdit(row: AnswerRow): void {
+    editingKey = row.field.key
+    rowError = null
+    const current = row.value
+
+    if (row.field.multiple) {
+      draftMultiple = Array.isArray(current) ? current.map((entry) => String(entry)) : []
+      return
+    }
+
+    draft = current === null || current === undefined ? '' : String(current)
+  }
+
+  /**
+   * Closes the open editor and drops its draft.
+   *
+   * @example
+   * cancelEdit()
+   */
+  function cancelEdit(): void {
+    editingKey = null
+    draft = ''
+    draftMultiple = []
+    rowError = null
+  }
+
+  /**
+   * The value to commit, in the field's own type — the panel never asks a reviewer to type JSON.
+   *
+   * The mixed return type IS the contract: a field's committed value is whatever that field
+   * declares, and collapsing it to one type here would commit a string where the workspace declared
+   * a number. A number that does not parse to a finite value is committed as typed, so the field's
+   * own validation names the problem.
+   *
+   * @param {Field} field - The field being edited.
+   * @returns {FieldValue} The draft as the value to commit.
+   * @example
+   * draftValue(ageField) // 42, when the draft reads '42'
+   */
+  function draftValue(field: Field): FieldValue {
+    if (field.multiple) return [...draftMultiple]
+    if (draft === '') return null
+    if (field.type === 'number') {
+      const parsed = Number(draft)
+      return Number.isFinite(parsed) ? parsed : draft
+    }
+
+    if (field.type === 'boolean') return draft === 'true'
+    return draft
+  }
+
+  /**
+   * Commits the draft. A rejection shows the SDK's first validation message on the row and keeps
+   * the draft; a success closes the editor.
+   *
+   * @param {Field} field - The field being edited.
+   * @returns {Promise<void>} Settles once the commit has answered.
+   * @example
+   * await save(postcodeField)
+   */
+  async function save(field: Field): Promise<void> {
+    const result = await client.responses.commit({ [field.key]: draftValue(field) })
+    const message = result.errors.at(0)?.userMessage
+    if (message !== undefined) {
+      rowError = message
+      return
+    }
+
+    edited = true
+    cancelEdit()
+  }
+
+  /**
+   * Removes one answer.
+   *
+   * @param {Field} field - The field whose answer goes.
+   * @example
+   * clear(postcodeField)
+   */
+  function clear(field: Field): void {
+    client.responses.clear(field.key)
+    edited = true
+    if (editingKey === field.key) cancelEdit()
+  }
+
+  /**
+   * Removes every answer, once the reviewer has confirmed it.
+   *
+   * @example
+   * reset()
+   */
+  function reset(): void {
+    client.responses.clearAll()
+    confirmingReset = false
+    edited = false
+    cancelEdit()
+  }
+
+  /**
+   * Single-select: the clicked option becomes the whole draft.
+   *
+   * @param {string} value - The option's value, as text.
+   * @example
+   * selectOption('WA')
+   */
+  function selectOption(value: string): void {
+    draft = value
+  }
+
+  /**
+   * Multi-select: adds the option to the draft, or takes it out.
+   *
+   * @param {string} value - The option's value, as text.
+   * @example
+   * toggleOption('gas')
+   */
+  function toggleOption(value: string): void {
+    draftMultiple = draftMultiple.includes(value)
+      ? draftMultiple.filter((entry) => entry !== value)
+      : [...draftMultiple, value]
+  }
+
+  /**
+   * Runs the host's follow-up, which brings what the old answers produced up to date.
+   *
+   * @example
+   * runFollowUp()
+   */
+  function runFollowUp(): void {
+    followUp?.run()
+    edited = false
+  }
+</script>
+
+<Stack direction="vertical" gap="medium">
+  {#if posture.readOnly && posture.reason !== null}
+    <Banner status="warning" testId="devtools-answers-readonly">{posture.reason}</Banner>
+  {/if}
+
+  <div class="toolbar-row">
+    <div class="filters" role="group" aria-label="Show">
+      {#each filters as option (option.value)}
+        <button
+          type="button"
+          class="filter"
+          class:selected={filter === option.value}
+          aria-pressed={filter === option.value}
+          onclick={() => (filter = option.value)}
+        >
+          {option.label}
+        </button>
+      {/each}
+    </div>
+    <Button
+      variant="ghost"
+      size="small"
+      disabled={!posture.canEditAnswers || rows.length === 0}
+      title={withheld}
+      onclick={() => (confirmingReset = true)}
+      testId="devtools-answers-reset"
+    >
+      Start over
+    </Button>
+  </div>
+
+  {#if confirmingReset}
+    <Banner status="warning" title="Clear every answer?">
+      <Stack direction="vertical" gap="small">
+        <Text size="small">
+          This empties every answer in this session. Nothing about a real customer changes.
+        </Text>
+        <Stack direction="horizontal" gap="small">
+          <Button variant="destructive" size="small" onclick={reset}>Clear everything</Button>
+          <Button variant="secondary" size="small" onclick={() => (confirmingReset = false)}>
+            Keep my answers
+          </Button>
+        </Stack>
+      </Stack>
+    </Banner>
+  {/if}
+
+  {#if edited && followUp !== null}
+    <!-- An edited answer changes nothing already worked out from the old one until that runs
+         again. Saying so beats a reviewer reporting the stale screen as a bug. -->
+    <Banner status="info" testId="devtools-answers-follow-up">
+      <Stack direction="horizontal" gap="small" justify="center" align="space-between">
+        <Text size="small">What is on screen was worked out before this change.</Text>
+        <Button
+          variant="secondary"
+          size="small"
+          onclick={runFollowUp}
+          testId="devtools-answers-follow-up-run"
+        >
+          {followUp.label}
+        </Button>
+      </Stack>
+    </Banner>
+  {/if}
+
+  <Card sectioned>
+    {#if visibleRows.length === 0}
+      <EmptyState
+        message="Nothing to show here"
+        hint={filter === 'answered'
+          ? 'No questions have been answered yet. Start the journey on the page.'
+          : 'Every question this journey asks already has an answer.'}
+      />
+    {:else}
+      <ul class="rows" data-testid="devtools-answers">
+        {#each visibleRows as row (row.field.key)}
+          <li class="row" data-testid="devtools-answers-row" data-field-key={row.field.key}>
+            <div class="row-head">
+              <div class="row-title">
+                <Text size="medium" weight="medium">{row.view.title}</Text>
+                <!-- The title is the field's authored `label`, which is usually the question the
+                     visitor read, but not always: a label can be its step's heading. So when the
+                     short noun says something the title does not, it rides the second line ahead
+                     of the key. -->
+                <span class="row-meta">
+                  {#if row.view.noun !== row.view.title}
+                    <span>{row.view.noun}</span>
+                  {/if}
+                  <span class="row-key">{row.field.key}</span>
+                </span>
+              </div>
+              {#if row.view.editable}
+                {#if editingKey === row.field.key}
+                  <span class="row-actions">
+                    <Button variant="primary" size="small" onclick={() => void save(row.field)}>
+                      Save
+                    </Button>
+                    <Button variant="ghost" size="small" onclick={cancelEdit}>Cancel</Button>
+                  </span>
+                {:else}
+                  <span class="row-actions">
+                    <Button
+                      variant="secondary"
+                      size="small"
+                      disabled={!posture.canEditAnswers}
+                      title={withheld}
+                      onclick={() => startEdit(row)}
+                    >
+                      {row.view.answered ? 'Change' : 'Answer'}
+                    </Button>
+                    {#if row.view.answered}
+                      <Button
+                        variant="ghost"
+                        size="small"
+                        disabled={!posture.canEditAnswers}
+                        title={withheld}
+                        onclick={() => clear(row.field)}
+                      >
+                        Clear
+                      </Button>
+                    {/if}
+                  </span>
+                {/if}
+              {:else}
+                <Badge status="default" size="small">Change it on its screen</Badge>
+              {/if}
+            </div>
+
+            {#if editingKey === row.field.key}
+              <div class="editor">
+                {#if row.view.kind === 'options' && row.field.options}
+                  {#each row.field.options as option (option.id)}
+                    <label class="option-label">
+                      <input
+                        type={row.field.multiple ? 'checkbox' : 'radio'}
+                        name="answer-{row.field.key}"
+                        value={String(option.value)}
+                        checked={row.field.multiple
+                          ? draftMultiple.includes(String(option.value))
+                          : draft === String(option.value)}
+                        onchange={() =>
+                          row.field.multiple
+                            ? toggleOption(String(option.value))
+                            : selectOption(String(option.value))}
+                      />
+                      <Text size="small" inline>{option.label}</Text>
+                    </label>
+                  {/each}
+                {:else if row.view.kind === 'boolean'}
+                  {#each [{ value: 'true', label: 'Yes' }, { value: 'false', label: 'No' }] as option (option.value)}
+                    <label class="option-label">
+                      <input
+                        type="radio"
+                        name="answer-{row.field.key}"
+                        value={option.value}
+                        checked={draft === option.value}
+                        onchange={() => selectOption(option.value)}
+                      />
+                      <Text size="small" inline>{option.label}</Text>
+                    </label>
+                  {/each}
+                {:else}
+                  <input
+                    class="inline-input"
+                    type={row.view.kind === 'number' ? 'number' : 'text'}
+                    bind:value={draft}
+                    placeholder={row.field.placeholder ?? 'Type an answer'}
+                    aria-label={row.view.title}
+                  />
+                {/if}
+
+                {#if rowError !== null}
+                  <Text size="small" color="error">{rowError}</Text>
+                {/if}
+              </div>
+            {:else if row.view.kind === 'system' && row.view.answered}
+              <div class="system-value">
+                <Text size="small" color="subdued">{row.view.display}</Text>
+                <CopyButton text={systemPayload(row.value)} label="Copy" showLabel />
+              </div>
+            {:else if row.view.answered && row.view.display !== null}
+              <Text size="small" color="subdued">{row.view.display}</Text>
+            {:else}
+              <Text size="small" color="subdued">Not answered yet</Text>
+            {/if}
+          </li>
+        {/each}
+      </ul>
+    {/if}
+  </Card>
+</Stack>
+
+<style>
+  .toolbar-row {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--space-2);
+    flex-wrap: wrap;
+  }
+
+  .filters {
+    display: flex;
+    gap: var(--space-1);
+    flex-wrap: wrap;
+  }
+
+  .filter {
+    border: 1px solid var(--color-gray-200);
+    border-radius: var(--radius-full);
+    background: var(--color-white);
+    color: var(--color-gray-600);
+    font-family: inherit;
+    font-size: var(--text-xs);
+    padding: var(--space-1) var(--space-2-5);
+    cursor: pointer;
+  }
+
+  .filter:hover {
+    border-color: var(--color-gray-300);
+    color: var(--color-gray-900);
+  }
+
+  .filter.selected {
+    background: var(--color-blue-600);
+    border-color: var(--color-blue-600);
+    color: var(--color-white);
+  }
+
+  .filter:focus-visible {
+    outline: var(--ring-width) solid var(--ring-color);
+    outline-offset: var(--ring-offset);
+  }
+
+  .rows {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  .row {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-1);
+    padding: var(--space-3);
+    border-bottom: 1px solid var(--color-gray-200);
+  }
+
+  .row:last-child {
+    border-bottom: none;
+  }
+
+  .row-head {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: var(--space-2);
+  }
+
+  .row-title {
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+  }
+
+  /* The key is a developer's handle, not the reviewer's — present, dimmed, never the headline. */
+  .row-meta {
+    display: flex;
+    align-items: baseline;
+    gap: var(--space-1-5);
+    font-size: 10px;
+    color: var(--color-gray-500);
+    min-width: 0;
+    flex-wrap: wrap;
+  }
+
+  .row-key {
+    font-family: 'Monaco', 'Menlo', 'Courier New', monospace;
+    overflow-wrap: anywhere;
+  }
+
+  .row-actions {
+    display: inline-flex;
+    gap: var(--space-1);
+    flex-shrink: 0;
+  }
+
+  .editor {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2);
+    padding-top: var(--space-1);
+  }
+
+  .system-value {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--space-2);
+  }
+</style>

package/dist/plugins/devtools/review/guide/GuideLine.svelte

@@ -0,0 +1,20 @@
+<script lang="ts">
+  /** @file One line of guide text, with each `**control name**` in bold, built without raw HTML. */
+  import { emphasis } from '../../derive'
+
+  interface GuideLineProps {
+    text: string
+  }
+
+  const { text }: GuideLineProps = $props()
+</script>
+
+{#each emphasis(text) as run, index (index)}
+  {#if run.bold}<strong>{run.text}</strong>{:else}{run.text}{/if}
+{/each}
+
+<style>
+  strong {
+    font-weight: var(--font-semibold);
+  }
+</style>

package/dist/plugins/devtools/review/guide/GuidePanel.svelte

@@ -0,0 +1,133 @@
+<script lang="ts">
+  /**
+   * @file The How to use tab: each section's steps and notes, then the common problems and their
+   * fixes. The shell decides which sections a build shows; this lays them out and turns a section's
+   * tab into an "Open …" button.
+   */
+  import { Button, Card, Heading, Stack } from '../../ui'
+  import type { GuideFix, GuideSection } from '../../derive'
+  import GuideLine from './GuideLine.svelte'
+
+  interface GuidePanelProps {
+    sections: readonly GuideSection[]
+    fixes: readonly GuideFix[]
+    /** Each listed tab's name, by tab id. A section whose tab is missing here offers no button. */
+    tabLabels: Readonly<Record<string, string>>
+    onOpenTab: (id: string) => void
+  }
+
+  const { sections, fixes, tabLabels, onOpenTab }: GuidePanelProps = $props()
+
+  /**
+   * The "Open …" button a section offers, or null when its tab is not listed in this panel.
+   *
+   * @param {GuideSection} section - The section to read.
+   * @returns {{ id: string; label: string } | null} The tab to open and its name.
+   * @example
+   * openTarget({ ...section, tab: 'answers' }) // { id: 'answers', label: 'Answers' }
+   */
+  function openTarget(section: GuideSection): { id: string; label: string } | null {
+    const id = section.tab
+    if (id === null || !Object.hasOwn(tabLabels, id)) return null
+    return { id, label: tabLabels[id] }
+  }
+</script>
+
+<div class="guide" data-testid="devtools-guide">
+  {#each sections as section (section.id)}
+    {@const target = openTarget(section)}
+    <section data-testid="devtools-guide-{section.id}">
+      <Card>
+        <Stack direction="vertical" gap="small">
+          <Stack direction="horizontal" gap="small" align="space-between" justify="center">
+            <Heading level={3} size="small">{section.title}</Heading>
+            {#if target !== null}
+              <Button variant="secondary" size="small" onclick={() => onOpenTab(target.id)}>
+                Open {target.label}
+              </Button>
+            {/if}
+          </Stack>
+          {#if section.steps.length > 0}
+            <ol class="steps">
+              {#each section.steps as step, index (index)}
+                <li><GuideLine text={step} /></li>
+              {/each}
+            </ol>
+          {/if}
+          {#each section.notes as note, index (index)}
+            <p class="note"><GuideLine text={note} /></p>
+          {/each}
+        </Stack>
+      </Card>
+    </section>
+  {/each}
+
+  {#if fixes.length > 0}
+    <section data-testid="devtools-guide-fixes">
+      <Card>
+        <Stack direction="vertical" gap="small">
+          <Heading level={3} size="small">If something goes wrong</Heading>
+          <dl class="fixes">
+            {#each fixes as entry (entry.problem)}
+              <dt>{entry.problem}</dt>
+              <dd><GuideLine text={entry.fix} /></dd>
+            {/each}
+          </dl>
+        </Stack>
+      </Card>
+    </section>
+  {/if}
+</div>
+
+<style>
+  .guide {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-4);
+    max-width: 52rem;
+  }
+
+  /* A host page's base styles may strip list markers, and the numbers are the point of a step list. */
+  .steps {
+    list-style: decimal;
+    margin: 0;
+    padding-left: var(--space-6);
+    font-size: var(--text-sm);
+    line-height: 1.5;
+    color: var(--color-gray-900);
+  }
+
+  .steps li + li {
+    margin-top: var(--space-1);
+  }
+
+  .steps li::marker {
+    color: var(--color-gray-500);
+  }
+
+  .note {
+    margin: 0;
+    font-size: var(--text-sm);
+    line-height: 1.5;
+    color: var(--color-gray-700);
+  }
+
+  .fixes {
+    display: grid;
+    grid-template-columns: minmax(10rem, 1fr) 2fr;
+    gap: var(--space-2) var(--space-4);
+    margin: 0;
+    font-size: var(--text-sm);
+    line-height: 1.5;
+  }
+
+  .fixes dt {
+    font-weight: var(--font-medium);
+    color: var(--color-gray-900);
+  }
+
+  .fixes dd {
+    margin: 0;
+    color: var(--color-gray-700);
+  }
+</style>

package/dist/plugins/devtools/review/index.d.ts

@@ -0,0 +1,6 @@
+/** @file The review tabs' panels: How to use, This session, Answers, Journey map and Variations. */
+export { default as GuidePanel } from './guide/GuidePanel.svelte';
+export { default as SessionPanel } from './session/SessionPanel.svelte';
+export { default as AnswersPanel } from './answers/AnswersPanel.svelte';
+export { default as JourneyPanel } from './journey/JourneyPanel.svelte';
+export { default as VariationsPanel } from './variations/VariationsPanel.svelte';

package/dist/plugins/devtools/review/index.js

@@ -0,0 +1 @@
+import e from"./guide/GuidePanel.svelte";import t from"./session/SessionPanel.svelte";import n from"./answers/AnswersPanel.svelte";import r from"./journey/JourneyPanel.svelte";import i from"./variations/VariationsPanel.svelte";export{n as AnswersPanel,e as GuidePanel,r as JourneyPanel,t as SessionPanel,i as VariationsPanel};