@picked/svelte 0.0.1-dev.1793758300441 → 0.0.1-dev.1793769511104

package/dist/plugins/devtools/review/personas/PersonasPanel.svelte

@@ -0,0 +1,546 @@
+<script lang="ts">
+  /**
+   * @file The Personas & Scenarios tab: customers and situations to try the journey as. The site's
+   * own come from the plugin's `personas` option. A reviewer makes theirs in this browser, either by
+   * answering the journey's questions here, screen by screen, or from where they are on the page.
+   * A persona keeps the answers a customer gives on fields they can see, the screens moved on from,
+   * the screen it stops on and the page it starts on. Loading one reloads that page clean and walks
+   * the journey with its answers, screen by screen, up to that screen.
+   */
+  import type { FieldValue, Picked } from '@picked/client'
+  import { getStepFields } from '@picked/client/form'
+  import { Banner, Button, Card, EmptyState, RadioGroup, Stack, Text, TextField } from '../../ui'
+  import {
+    buildPersona,
+    customerAnswers,
+    deslug,
+    entryUrlOf,
+    isBlank,
+    passedScreens,
+    readSavedPersonas,
+    writeSavedPersonas,
+    type Persona,
+    type BuilderWalk,
+    type PersonaCapture,
+    type PersonaLanding,
+    type PersonaStorageGetter,
+    type RouteEntry,
+    type SafetyPosture,
+  } from '../../derive'
+  import type { JourneyView } from '../../session'
+  import { loadUrl, startPersonaLoad } from './load-persona'
+  import PersonaBuilder from './PersonaBuilder.svelte'
+  import PersonaCard from './PersonaCard.svelte'
+
+  interface PersonasPanelProps {
+    client: Picked
+    posture: SafetyPosture
+    /** The journey in front, which a new persona lands on. */
+    journey: JourneyView | null
+    /** The site's own personas. */
+    personas: readonly Persona[]
+    /** Every field a journey's screens ask, minus the code-owned ones. */
+    asked: ReadonlySet<string>
+    /** Every screen moved on from this session, in order. */
+    route: readonly RouteEntry[]
+    /** Experience keys the devtools never follow. */
+    hiddenKeys: ReadonlySet<string>
+    /** Keys a screen carries only for its code. */
+    codeOwned: ReadonlySet<string>
+    /** Screens that move on by themselves, and actions that open another journey. */
+    personaWalk: {
+      selfAdvancingSteps: ReadonlySet<string>
+      handoffs: Readonly<Record<string, string>>
+    }
+    /** How the last load's walk ended; `null` when no load ran on this page. */
+    walkNotice: Notice | null
+    onWalkNoticeDismiss: () => void
+    /** The storage saved personas live in. */
+    getStorage?: PersonaStorageGetter
+    /** The tab's storage, which carries a load across its reload. */
+    getSessionStorage?: () => Pick<Storage, 'setItem'>
+    /**
+     * Goes to a URL; a load reloads the page through it.
+     *
+     * @param url - The URL.
+     */
+    navigate?: (url: string) => void
+  }
+
+  /** A banner's tone and words. */
+  interface Notice {
+    status: 'info' | 'success' | 'warning' | 'error'
+    text: string
+  }
+
+  const {
+    client,
+    posture,
+    journey,
+    personas,
+    asked,
+    route,
+    hiddenKeys,
+    codeOwned,
+    personaWalk,
+    walkNotice,
+    onWalkNoticeDismiss,
+    getStorage = () => window.localStorage,
+    getSessionStorage = () => window.sessionStorage,
+    navigate = (url: string) => {
+      window.location.assign(url)
+    },
+  }: PersonasPanelProps = $props()
+
+  // 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 responsesStore = $derived(client.responses.getAllStore)
+
+  /**
+   * This browser's saved personas for the client's project.
+   *
+   * @returns {Persona[]} The saved personas, oldest first.
+   * @example readSaved()
+   */
+  function readSaved(): Persona[] {
+    return readSavedPersonas(getStorage, client.projectId)
+  }
+
+  let saved = $state<Persona[]>(readSaved())
+  let creating = $state(false)
+  /** How a new persona is made: answered here, or taken from where the reviewer is. */
+  let mode = $state<'build' | 'capture'>('build')
+  let name = $state('')
+  let description = $state('')
+  let entryText = $state('')
+  let nameError = $state<string | null>(null)
+  let entryError = $state<string | null>(null)
+  /** The journey a build starts in, its draft answers, and its picks on the site's outcomes. */
+  let buildStart = $state('')
+  let buildAnswers = $state.raw<Record<string, FieldValue>>({})
+  let buildChoices = $state.raw<Record<string, boolean>>({})
+  let buildWalk = $state.raw<BuilderWalk | null>(null)
+  let notice = $state<Notice | null>(null)
+  let loadingId = $state<string | null>(null)
+  /** The answers Save would keep; `null` while they are read. */
+  let captured = $state<Record<string, FieldValue> | null>(null)
+
+  const isEmpty = $derived(personas.length === 0 && saved.length === 0)
+  const postureReason = $derived(posture.canEditAnswers ? undefined : (posture.reason ?? undefined))
+
+  /**
+   * Why a persona's Load is withheld: the session's posture, or another persona loading.
+   *
+   * @param {Persona} persona - The persona on the card.
+   * @returns {string | undefined} The reason, or `undefined` while Load is allowed.
+   * @example loadReason(persona)
+   */
+  function loadReason(persona: Persona): string | undefined {
+    if (postureReason !== undefined) return postureReason
+    return loadingId !== null && loadingId !== persona.id
+      ? 'Another persona is loading.'
+      : undefined
+  }
+  const landing = $derived<PersonaLanding | null>(
+    journey === null
+      ? null
+      : {
+          experienceKey: journey.experienceKey,
+          experienceName: journey.experienceName,
+          stepKey: journey.stepKey,
+          stepName: journey.stepName,
+        },
+  )
+  const buildSummary = $derived.by(() => {
+    if (buildWalk === null) return 'Working out the route…'
+    const count = Object.keys(buildWalk.answers).length
+    const answers = count === 1 ? '1 answer' : `${count} answers`
+    const stop = buildWalk.landing
+    if (stop === null) return `Saves ${answers}.`
+    const screen = stop.stepName ?? deslug(stop.stepKey ?? '')
+    return `Saves ${answers}. Loading it walks the journey to ${screen}.`
+  })
+
+  const captureSummary = $derived.by(() => {
+    if (captured === null) return 'Reading your answers…'
+    const count = Object.keys(captured).length
+    const answers = count === 1 ? '1 answer' : `${count} answers`
+    if (landing === null)
+      return `Saves ${answers}. No journey is open, so it loads the answers only.`
+    const journeyName = landing.experienceName ?? deslug(landing.experienceKey)
+    if (landing.stepKey === null) return `Saves ${answers}. Loading it walks ${journeyName}.`
+    const screen = landing.stepName ?? deslug(landing.stepKey)
+    return `Saves ${answers}. Loading it walks ${journeyName} to ${screen}.`
+  })
+
+  /**
+   * The answers a customer gave: held values of the fields a journey's screens ask, minus any whose
+   * own condition hides it now.
+   *
+   * @param {Readonly<Record<string, FieldValue>>} responses - Every held response.
+   * @returns {Promise<Record<string, FieldValue>>} The answers a persona keeps.
+   * @example await readCustomerAnswers(client.responses.getAllStore.getState())
+   */
+  async function readCustomerAnswers(
+    responses: Readonly<Record<string, FieldValue>>,
+  ): Promise<Record<string, FieldValue>> {
+    const answered = client.fields.listStore
+      .getState()
+      .filter((field) => asked.has(field.key) && !isBlank(responses[field.key]))
+    const visible = await getStepFields(client, answered)
+    return customerAnswers(responses, new Set(visible.map((field) => field.key)))
+  }
+
+  // While the form is open, keep what Save would keep in step with the answers.
+  $effect(() => {
+    if (!creating || mode !== 'capture') return
+    let current = true
+    void readCustomerAnswers($responsesStore).then((answers) => {
+      if (current) captured = answers
+    })
+    return () => {
+      current = false
+    }
+  })
+
+  /**
+   * A new persona's id, unique in this browser.
+   *
+   * @returns {string} The id.
+   * @example newId() // 'persona-lx2k9-4f1a2b3c'
+   */
+  function newId(): string {
+    const [entropy = 0] = crypto.getRandomValues(new Uint32Array(1))
+    return `persona-${Date.now().toString(36)}-${entropy.toString(16)}`
+  }
+
+  /**
+   * The journey a build starts in: the one in front, else the first one open.
+   *
+   * @returns {string} Its experience key, or nothing when no journey is open.
+   * @example defaultStart() // 'needs-analysis'
+   */
+  function defaultStart(): string {
+    if (journey !== null) return journey.experienceKey
+    const open = client.experienceInstances.listStore
+      .getState()
+      .find(
+        (instance) => instance.isOpenStore.getState() && !hiddenKeys.has(instance.experienceKey),
+      )
+    return open?.experienceKey ?? ''
+  }
+
+  /**
+   * Opens the form that makes a persona: answered here on a fresh page, or from where the reviewer
+   * is once they have answered something on it.
+   *
+   * @example startCreate()
+   */
+  function startCreate(): void {
+    const responses = client.responses.getAllStore.getState()
+    const answeredHere = [...asked].some((key) => !isBlank(responses[key]))
+    creating = true
+    mode = answeredHere ? 'capture' : 'build'
+    name = ''
+    description = ''
+    entryText = `${window.location.pathname}${window.location.search}`
+    nameError = null
+    entryError = null
+    notice = null
+    captured = null
+    buildStart = defaultStart()
+    buildAnswers = {}
+    buildChoices = {}
+    buildWalk = null
+  }
+
+  /**
+   * What Save keeps, from the build or from where the reviewer is.
+   *
+   * @param {string | null} entryUrl - The page a load starts on.
+   * @returns {Promise<PersonaCapture | null>} The capture, or `null` while the build's route is worked out.
+   * @example await capture('/compare')
+   */
+  async function capture(entryUrl: string | null): Promise<PersonaCapture | null> {
+    const id = newId()
+    const savedAt = new Date().toISOString()
+    if (mode === 'build') {
+      if (buildWalk === null) return null
+      return {
+        responses: buildWalk.answers,
+        journey: buildWalk.landing,
+        passed: buildWalk.passed,
+        entryUrl: entryUrl ?? '',
+        id,
+        savedAt,
+      }
+    }
+
+    return {
+      responses: await readCustomerAnswers(client.responses.getAllStore.getState()),
+      journey: landing,
+      passed: passedScreens(route, hiddenKeys),
+      entryUrl: entryUrl ?? `${window.location.pathname}${window.location.search}`,
+      id,
+      savedAt,
+    }
+  }
+
+  /**
+   * Saves where the reviewer is as a new persona, in this browser.
+   *
+   * @returns {Promise<void>} Settles once it is saved or refused.
+   * @example await save()
+   */
+  async function save(): Promise<void> {
+    const entryUrl = entryUrlOf(entryText, window.location.origin)
+    if (entryText.trim().length > 0 && entryUrl === null) {
+      entryError = 'Use a page on this site, such as /compare.'
+      return
+    }
+
+    const kept = await capture(entryUrl)
+    if (kept === null) return
+    const result = buildPersona({ name, description }, kept)
+    if (!result.ok) {
+      nameError = result.error
+      return
+    }
+
+    saved = [...saved, result.persona]
+    creating = false
+    const stored = writeSavedPersonas(getStorage, client.projectId, saved)
+    notice = stored
+      ? { status: 'success', text: `Saved ${result.persona.name}.` }
+      : {
+          status: 'warning',
+          text: `${result.persona.name} is here until you reload. This browser would not let it be saved.`,
+        }
+  }
+
+  /**
+   * Deletes a saved persona.
+   *
+   * @param {Persona} persona - The persona to delete.
+   * @example remove(persona)
+   */
+  function remove(persona: Persona): void {
+    saved = saved.filter((entry) => entry.id !== persona.id)
+    writeSavedPersonas(getStorage, client.projectId, saved)
+    notice = { status: 'success', text: `Deleted ${persona.name}.` }
+  }
+
+  /**
+   * Loads a persona: the site's own loader when it has one, else a clean reload that walks its
+   * journey on the persona's page, keeping this page's query.
+   *
+   * @param {Persona} persona - The persona to load.
+   * @returns {Promise<void>} Settles once it has loaded, failed, or the reload is under way.
+   * @example await load(persona)
+   */
+  async function load(persona: Persona): Promise<void> {
+    loadingId = persona.id
+    notice = null
+    onWalkNoticeDismiss()
+    try {
+      if (persona.load === null) {
+        const started = startPersonaLoad(client, persona, {
+          storage: getSessionStorage(),
+          url: loadUrl(persona.entryUrl, window.location),
+          navigate,
+        })
+        if (!started) {
+          notice = { status: 'error', text: 'This browser would not let the load start.' }
+          loadingId = null
+        }
+
+        return
+      }
+
+      await persona.load(client)
+      notice = { status: 'success', text: `Loaded ${persona.name}.` }
+      loadingId = null
+    } catch (error) {
+      const detail = error instanceof Error ? ` ${error.message}` : ''
+      notice = { status: 'error', text: `${persona.name} did not load.${detail}` }
+      loadingId = null
+    }
+  }
+</script>
+
+<div class="personas" data-testid="devtools-personas">
+  {#if walkNotice}
+    <Banner
+      status={walkNotice.status}
+      testId="devtools-persona-walk"
+      onDismiss={onWalkNoticeDismiss}
+    >
+      {walkNotice.text}
+    </Banner>
+  {/if}
+
+  {#if notice}
+    <Banner status={notice.status} onDismiss={() => (notice = null)}>{notice.text}</Banner>
+  {/if}
+
+  {#if creating}
+    <Card>
+      <div class="form">
+        <Stack direction="vertical" gap="medium">
+          <Text weight="semibold">New persona</Text>
+          <RadioGroup
+            label="Make it by"
+            name="persona-mode"
+            orientation="horizontal"
+            value={mode}
+            options={[
+              { value: 'build', label: 'Answering the questions here' },
+              { value: 'capture', label: 'Using where I am now' },
+            ]}
+            onchange={(value) => (mode = value === 'capture' ? 'capture' : 'build')}
+          />
+          <TextField
+            label="Name"
+            name="persona-name"
+            placeholder="Young family"
+            required
+            value={name}
+            error={nameError ?? undefined}
+            oninput={(value) => {
+              name = value
+              nameError = null
+            }}
+          />
+          <TextField
+            label="Description"
+            name="persona-description"
+            helpText="Who they are, or what they test, in a sentence."
+            value={description}
+            oninput={(value) => (description = value)}
+          />
+          <TextField
+            label="Starts on"
+            name="persona-entry-url"
+            helpText="The page a load opens. Keep a campaign page's address to load it as that campaign."
+            value={entryText}
+            error={entryError ?? undefined}
+            oninput={(value) => {
+              entryText = value
+              entryError = null
+            }}
+          />
+          {#if mode === 'build'}
+            <PersonaBuilder
+              {client}
+              start={buildStart}
+              answers={buildAnswers}
+              choices={buildChoices}
+              entryUrl={entryUrlOf(entryText, window.location.origin) ?? window.location.pathname}
+              {asked}
+              {codeOwned}
+              selfAdvancing={personaWalk.selfAdvancingSteps}
+              handoffs={personaWalk.handoffs}
+              {hiddenKeys}
+              onStartChange={(key) => (buildStart = key)}
+              onAnswersChange={(next) => (buildAnswers = next)}
+              onChoicesChange={(next) => (buildChoices = next)}
+              onWalk={(next) => (buildWalk = next)}
+            />
+          {/if}
+          <Text size="small" color="subdued">
+            {mode === 'build' ? buildSummary : captureSummary}
+          </Text>
+          <div class="form-actions">
+            <Button variant="primary" size="small" onclick={() => void save()}>Save</Button>
+            <Button variant="ghost" size="small" onclick={() => (creating = false)}>Cancel</Button>
+          </div>
+        </Stack>
+      </div>
+    </Card>
+  {:else if isEmpty}
+    <div class="empty">
+      <EmptyState
+        message="No personas or scenarios yet"
+        hint="Walk the journey the way a customer would, then save it here to load it again in one click."
+      />
+      <Button variant="primary" onclick={startCreate}>Create</Button>
+    </div>
+  {:else}
+    <div class="toolbar">
+      <Button variant="secondary" size="small" onclick={startCreate}>Create</Button>
+    </div>
+  {/if}
+
+  {#if personas.length > 0}
+    <section class="group" aria-label="For this site">
+      <h3 class="group-title">For this site</h3>
+      {#each personas as persona (persona.id)}
+        <PersonaCard
+          {persona}
+          loadReason={loadReason(persona)}
+          loading={loadingId === persona.id}
+          onLoad={() => void load(persona)}
+        />
+      {/each}
+    </section>
+  {/if}
+
+  {#if saved.length > 0}
+    <section class="group" aria-label="Saved in this browser">
+      <h3 class="group-title">Saved in this browser</h3>
+      {#each saved as persona (persona.id)}
+        <PersonaCard
+          {persona}
+          loadReason={loadReason(persona)}
+          loading={loadingId === persona.id}
+          onLoad={() => void load(persona)}
+          onDelete={() => remove(persona)}
+        />
+      {/each}
+    </section>
+  {/if}
+</div>
+
+<style>
+  .personas {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-4);
+  }
+
+  .form {
+    max-width: 36rem;
+  }
+
+  .empty {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--space-3);
+  }
+
+  .toolbar,
+  .form-actions {
+    display: flex;
+    gap: var(--space-2);
+  }
+
+  .toolbar {
+    justify-content: flex-end;
+  }
+
+  .group {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2);
+  }
+
+  .group-title {
+    margin: 0;
+    font-size: var(--text-xs);
+    font-weight: var(--font-semibold);
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    color: var(--color-gray-500);
+  }
+</style>