@kelpie/ui 0.12.0 → 0.14.0

package/src/pages/dashboard/attention.ts

@@ -3,16 +3,16 @@ import type {
   DashboardPlanItem,
   DashboardStaleContact,
   DashboardTouchpoint,
-  PipelineKind,
+  DashboardUpcomingEvent,
   RecordTargetType,
 } from '@kelpie/schemas'
 
 import type { ChipTone } from '../../components/Chip.tsx'
-import { formatDay } from '../../lib/dates.ts'
+import { formatDate, formatDay } from '../../lib/dates.ts'
 
 /**
- * Reading the workspace snapshot as a page: one attention list, and the brief
- * above it.
+ * Reading the workspace snapshot as a page: one attention list from the
+ * signals the service already ranked.
  *
  * Pure functions over the decoded response, so the page renders and these are
  * tested separately. Nothing here recomputes a signal: the service already
@@ -30,6 +30,8 @@ const ROUTES: Readonly<Record<RecordTargetType, string | undefined>> = {
   raise: '/fundraising',
   enquiry: '/enquiries',
   candidate: undefined,
+  event: '/events',
+  attendance: undefined,
 }
 
 const TARGET_TYPE_LABELS: Readonly<Record<RecordTargetType, string>> = {
@@ -41,6 +43,8 @@ const TARGET_TYPE_LABELS: Readonly<Record<RecordTargetType, string>> = {
   raise: 'Fundraising',
   enquiry: 'Enquiry',
   candidate: 'Candidate',
+  event: 'Event',
+  attendance: 'Attendance',
 }
 
 export function targetTypeLabel(targetType: RecordTargetType): string {
@@ -115,8 +119,22 @@ function staleContactRow(contact: DashboardStaleContact): AttentionRow {
   }
 }
 
+function upcomingEventRow(event: DashboardUpcomingEvent, timezone: string): AttentionRow {
+  const where = event.location.length > 0 ? event.location : event.format
+
+  return {
+    id: `event-${event.id}`,
+    label: 'Upcoming event',
+    tone: 'accent',
+    meta: formatDate(event.startsAt, timezone),
+    title: event.name,
+    detail: `${String(event.attendeeCount)} registered · ${where}`,
+    href: `/events/${event.id}`,
+  }
+}
+
 /**
- * The signals behind the brief, most urgent first.
+ * The attention list, most urgent first.
  *
  * The groups are concatenated rather than sorted: each arrives from the API in
  * its own order — plan items soonest first, contacts coldest first — and a
@@ -131,79 +149,7 @@ export function attentionRows(dashboard: Dashboard): readonly AttentionRow[] {
     ...touchpoints.filter((touchpoint) => touchpoint.overdue).map(touchpointRow),
     ...dashboard.dueSoonPlanItems.items.map((item) => planItemRow(item, false)),
     ...touchpoints.filter((touchpoint) => !touchpoint.overdue).map(touchpointRow),
+    ...dashboard.upcomingEvents.items.map((item) => upcomingEventRow(item, dashboard.timezone)),
     ...dashboard.staleContacts.items.map(staleContactRow),
   ]
 }
-
-function plural(count: number, singular: string, pluralForm = `${singular}s`): string {
-  return `${String(count)} ${count === 1 ? singular : pluralForm}`
-}
-
-/**
- * How a count of open records reads mid-sentence.
- *
- * Not `PIPELINE_KIND_LABELS`: that one is nav wording, where a Raise is filed
- * under "Fundraising", and "3 fundraisings" is not a sentence. Written out
- * rather than suffixed, because "opportunitys" is not one either.
- */
-const OPEN_PIPELINE_NOUNS: Readonly<
-  Record<PipelineKind, { readonly one: string; readonly many: string }>
-> = {
-  enquiry: { one: 'enquiry', many: 'enquiries' },
-  deal: { one: 'deal', many: 'deals' },
-  opportunity: { one: 'opportunity', many: 'opportunities' },
-  raise: { one: 'raise', many: 'raises' },
-  partnership: { one: 'partnership', many: 'partnerships' },
-}
-
-/**
- * The brief, built from the totals rather than from the rows.
- *
- * A list is capped by the request's limit and a total is not, so counting the
- * rows on screen would understate every workspace with more than a page of them.
- */
-export function briefLines(dashboard: Dashboard): readonly string[] {
-  const lines: string[] = []
-
-  if (dashboard.overduePlanItems.total > 0) {
-    lines.push(
-      `${plural(dashboard.overduePlanItems.total, 'plan item')} overdue — triage Planning first.`,
-    )
-  }
-
-  if (dashboard.dueSoonPlanItems.total > 0) {
-    lines.push(
-      `${plural(dashboard.dueSoonPlanItems.total, 'plan item')} due in the next ${plural(dashboard.upcomingDays, 'day')}.`,
-    )
-  }
-
-  if (dashboard.partnershipTouchpoints.total > 0) {
-    lines.push(
-      `${plural(dashboard.partnershipTouchpoints.total, 'partnership touchpoint')} at hand.`,
-    )
-  }
-
-  if (dashboard.staleContacts.total > 0) {
-    lines.push(
-      `${plural(dashboard.staleContacts.total, 'contact')} past the ${String(dashboard.staleContactDays)}-day touch threshold.`,
-    )
-  }
-
-  const open = dashboard.pipelines.filter((pipeline) => pipeline.open > 0)
-
-  if (open.length > 0) {
-    lines.push(
-      `Open: ${open
-        .map((pipeline) => {
-          const noun = OPEN_PIPELINE_NOUNS[pipeline.kind]
-
-          return plural(pipeline.open, noun.one, noun.many)
-        })
-        .join(', ')}.`,
-    )
-  }
-
-  return lines.length === 0
-    ? ['Nothing urgent. Pipeline and relationships look quiet today.']
-    : lines
-}

package/src/pages/dashboard/sections.tsx

@@ -9,6 +9,7 @@ import type { ReactNode } from 'react'
 import { Link } from 'react-router'
 
 import { Chip } from '../../components/Chip.tsx'
+import { MarkdownView } from '../../components/MarkdownView.tsx'
 import { SectionHeader } from '../../components/SectionHeader.tsx'
 import { formatDate, formatRelativeTime } from '../../lib/dates.ts'
 import { targetHref, targetTypeLabel } from './attention.ts'
@@ -72,7 +73,10 @@ function EmptyOr({
 export function AttentionList({ rows }: { readonly rows: readonly AttentionRow[] }): React.JSX.Element {
   return (
     <section>
-      <SectionHeader title="Needs attention" description="The signals behind the brief." />
+      <SectionHeader
+        title="Needs attention"
+        description="Overdue Plans, partnership touchpoints, and contacts going cold."
+      />
       <EmptyOr isEmpty={rows.length === 0} empty="Nothing urgent right now.">
         <ul className="divide-y divide-border border-y border-border">
           {rows.map((row) => (
@@ -201,7 +205,9 @@ export function NotesList({
           {notes.map((note) => (
             <li key={note.id} className="py-3">
               <div className="flex items-start justify-between gap-2">
-                <p className="line-clamp-3 text-[13px] leading-relaxed text-ink">{note.body}</p>
+                <div className="line-clamp-3 min-w-0 flex-1">
+                  <MarkdownView source={note.body} />
+                </div>
                 {note.pinned && (
                   <span className="shrink-0 text-[10px] font-medium tracking-wide text-accent uppercase">
                     Pinned

package/src/pages/forms/FormActions.tsx

@@ -1,9 +1,10 @@
-import { PIPELINE_KINDS } from '@kelpie/schemas'
-import type { Form, FormAttachTarget, PipelineKind } from '@kelpie/schemas'
+import { FORM_ATTACH_TARGET_TYPES, PLAN_ITEM_TARGET_TYPE_LABELS } from '@kelpie/schemas'
+import type { Form, FormAttachTarget, FormAttachTargetType, PipelineKind } from '@kelpie/schemas'
 import { useMemo, useState } from 'react'
 
 import { useDeals } from '../../api/resources/deals.ts'
 import { useEnquiries } from '../../api/resources/enquiries.ts'
+import { useEvents } from '../../api/resources/events.ts'
 import { useUpdateForm } from '../../api/resources/forms.ts'
 import { useLists } from '../../api/resources/lists.ts'
 import { useMembers } from '../../api/resources/members.ts'
@@ -400,12 +401,13 @@ interface AttachRecord {
   readonly name: string
 }
 
-function useAttachOptions(kind: PipelineKind): readonly AttachRecord[] {
+function useAttachOptions(kind: FormAttachTargetType): readonly AttachRecord[] {
   const deals = useDeals({}, { enabled: kind === 'deal' })
   const opportunities = useOpportunities({}, { enabled: kind === 'opportunity' })
   const raises = useRaises({}, { enabled: kind === 'raise' })
   const partnerships = usePartnerships({}, { enabled: kind === 'partnership' })
   const enquiries = useEnquiries({}, { enabled: kind === 'enquiry' })
+  const events = useEvents({}, { enabled: kind === 'event' })
 
   switch (kind) {
     case 'deal':
@@ -421,6 +423,8 @@ function useAttachOptions(kind: PipelineKind): readonly AttachRecord[] {
       }))
     case 'enquiry':
       return enquiries.records.map((enquiry) => ({ id: enquiry.id, name: enquiry.name }))
+    case 'event':
+      return events.records.map((record) => ({ id: record.id, name: record.name }))
   }
 }
 
@@ -431,7 +435,7 @@ function AttachTargetsBlock({
   readonly form: Form
   readonly onChange: (next: readonly FormAttachTarget[]) => void
 }): React.JSX.Element {
-  const [kind, setKind] = useState<PipelineKind>('deal')
+  const [kind, setKind] = useState<FormAttachTargetType>('deal')
   const [pick, setPick] = useState('')
   const options = useAttachOptions(kind)
   const chosen = form.attachTargets
@@ -459,7 +463,9 @@ function AttachTargetsBlock({
     <div className="space-y-2 rounded-md border border-border p-4">
       <div className="text-[13px] font-medium text-ink">Attach the submitter to a record</div>
       <p className="text-[11px] text-ink-faint">
-        Every submitter is linked into these records through <code>person_links</code>.
+        Pipeline records receive a <code>person_links</code> row. An Event
+        registers Attendance instead: the submitter is marked registered, and a
+        second submit of the same person is a no-op.
       </p>
       <ul className="divide-y divide-border">
         {chosen.length === 0 && (
@@ -496,13 +502,13 @@ function AttachTargetsBlock({
           className={inputClass}
           value={kind}
           onChange={(event) => {
-            setKind(event.target.value as PipelineKind)
+            setKind(event.target.value as FormAttachTargetType)
             setPick('')
           }}
         >
-          {PIPELINE_KINDS.map((option) => (
+          {FORM_ATTACH_TARGET_TYPES.map((option) => (
             <option key={option} value={option}>
-              {option}
+              {PLAN_ITEM_TARGET_TYPE_LABELS[option]}
             </option>
           ))}
         </select>

package/src/pages/onboarding/HandbookStepPage.tsx

@@ -1,45 +1,47 @@
-import { useNavigate } from 'react-router'
+import { Navigate, useNavigate, useSearchParams } from 'react-router'
 
 import { useHandbookPages } from '../../api/resources/handbookPages.ts'
 import { ErrorPanel, LoadingPanel } from '../../components/QueryState.tsx'
-import { PrimaryButton } from '../auth/AuthForm.tsx'
 import { AuthLayout } from '../auth/AuthLayout.tsx'
+import { OnboardingNav } from './OnboardingNav.tsx'
+import { isOnboardingRerun } from './onboardingRerun.ts'
 
 /**
- * Onboarding step 3: the starter handbook.
+ * Onboarding step 5: review the starter handbook.
  *
- * The mockup's button created these pages. Against the real API they already
- * exist: `POST /v1/workspaces` seeded them in the same transaction that created
- * the workspace, two steps ago. So this reads them back and shows what is there.
+ * Pages were seeded on step 2 when the reader picked an organisation type.
+ * This step reads them back and shows what agents will learn from.
  *
- * That is the deviation, and it is the honest one. A button labelled "create"
- * that creates nothing teaches a reader something false about the product, and
- * the alternative — deleting the step — would drop the one screen that tells a
- * new workspace its handbook is what agents read.
+ * A rerun skips this step: the pages are already in place.
  */
 export function HandbookStepPage(): React.JSX.Element {
   const navigate = useNavigate()
+  const [searchParams] = useSearchParams()
   const { records: pages, isLoading, error } = useHandbookPages()
 
+  if (isOnboardingRerun(searchParams)) {
+    return <Navigate to="/dashboard" replace />
+  }
+
   function finish(): void {
-    // The wizard ends on the dashboard, per `onboarding.md`. It is empty for a
-    // brand new workspace, which is the point: it says what there is to fill in.
     navigate('/dashboard', { replace: true })
   }
 
+  const sortedPages = [...pages].sort((left, right) => left.sortOrder - right.sortOrder)
+
   return (
     <AuthLayout
-      step={3}
+      step={5}
       title="Your starter handbook"
-      description="These markdown pages are ready. Agents read them to learn what your company is."
+      description="These markdown pages were chosen for your organisation type. Agents read them to learn what your company is."
     >
       <div className="mt-5 space-y-4">
         {error !== null && <ErrorPanel error={error} />}
         {error === null && isLoading && <LoadingPanel label="Loading your handbook…" />}
 
-        {error === null && !isLoading && pages.length > 0 && (
+        {error === null && !isLoading && sortedPages.length > 0 && (
           <ul className="max-h-56 overflow-y-auto rounded-md border border-border bg-surface">
-            {pages.map((page) => (
+            {sortedPages.map((page) => (
               <li
                 key={page.id}
                 className="border-b border-border px-3 py-2 text-[13px] text-ink last:border-0"
@@ -50,25 +52,20 @@ export function HandbookStepPage(): React.JSX.Element {
           </ul>
         )}
 
-        {/* An empty box under a heading that says the pages are ready would
-            assert one thing and show another. The handbook is seeded with the
-            workspace, so nothing here is the seeding having not happened. */}
-        {error === null && !isLoading && pages.length === 0 && (
+        {error === null && !isLoading && sortedPages.length === 0 && (
           <p className="rounded-md border border-border bg-surface px-3 py-2 text-[13px] text-ink-muted">
             This workspace has no handbook pages. That is not what a new workspace should look
             like — the Handbook tab is where to add them.
           </p>
         )}
 
-        {pages.length > 0 && (
+        {sortedPages.length > 0 && (
           <p className="text-[12px] text-ink-muted">
             Every page starts as a stub. Write them from the Handbook tab whenever you are ready.
           </p>
         )}
 
-        {/* Not a submit: the work behind this step already happened, so the
-            button only moves the reader on. */}
-        <PrimaryButton label="Go to Kelpie" onClick={finish} />
+        <OnboardingNav step={5} nextLabel="Go to Kelpie" nextType="button" onNext={finish} />
       </div>
     </AuthLayout>
   )

package/src/pages/onboarding/InvitesStepPage.tsx

@@ -2,14 +2,16 @@ import { INVITABLE_ROLES } from '@kelpie/schemas'
 import type { InvitableRole } from '@kelpie/schemas'
 import { useState } from 'react'
 import type { FormEvent } from 'react'
-import { useNavigate } from 'react-router'
+import { useNavigate, useSearchParams } from 'react-router'
 
 import { useSendInvite } from '../../api/resources/invites.ts'
-import { AUTH_INPUT_CLASS, SecondaryButton, SubmitButton } from '../auth/AuthForm.tsx'
+import { AUTH_INPUT_CLASS, SecondaryButton } from '../auth/AuthForm.tsx'
 import { AuthLayout } from '../auth/AuthLayout.tsx'
+import { OnboardingNav } from './OnboardingNav.tsx'
+import { isOnboardingRerun } from './onboardingRerun.ts'
 
 /**
- * Onboarding step 2: invitations, against `POST /v1/workspaces/:id/invites`.
+ * Onboarding step 4: invitations, against `POST /v1/workspaces/:id/invites`.
  *
  * One request per address, and they can fail one at a time — an address already
  * invited answers `409` while its neighbours succeed. The mockup could ignore
@@ -38,9 +40,16 @@ function isOutstanding(row: InviteRow): boolean {
 
 export function InvitesStepPage(): React.JSX.Element {
   const navigate = useNavigate()
+  const [searchParams] = useSearchParams()
+  const rerun = isOnboardingRerun(searchParams)
   const sendInvite = useSendInvite()
   const [rows, setRows] = useState<readonly InviteRow[]>([emptyRow()])
 
+  /** First run reviews the handbook next; a rerun leaves those pages alone. */
+  function afterInvites(): void {
+    navigate(rerun ? '/dashboard' : '/onboarding/handbook', { replace: true })
+  }
+
   function changeRow(index: number, changes: Partial<InviteRow>): void {
     setRows((previous) =>
       previous.map((row, at) => (at === index ? { ...row, ...changes } : row)),
@@ -80,7 +89,7 @@ export function InvitesStepPage(): React.JSX.Element {
     sendOutstanding()
       .then((allSent) => {
         if (allSent) {
-          navigate('/onboarding/handbook', { replace: true })
+          afterInvites()
         }
       })
       .catch(() => undefined)
@@ -90,7 +99,7 @@ export function InvitesStepPage(): React.JSX.Element {
 
   return (
     <AuthLayout
-      step={2}
+      step={4}
       title="Invite teammates"
       description="Optional. You can always invite people later from Admin → Team."
     >
@@ -117,20 +126,19 @@ export function InvitesStepPage(): React.JSX.Element {
           Add another
         </button>
 
-        <div className="flex flex-col gap-2 pt-1">
-          <SubmitButton
-            label={outstanding === 0 ? 'Continue' : 'Send invitations'}
-            pendingLabel="Sending…"
-            isPending={sendInvite.isPending}
-          />
-          <SecondaryButton
-            label="Skip for now"
-            disabled={sendInvite.isPending}
-            onClick={() => {
-              navigate('/onboarding/handbook', { replace: true })
-            }}
-          />
-        </div>
+        <OnboardingNav
+          step={4}
+          nextLabel={outstanding === 0 ? 'Next' : 'Send invitations'}
+          nextPendingLabel="Sending…"
+          isPending={sendInvite.isPending}
+          extra={
+            <SecondaryButton
+              label="Skip for now"
+              disabled={sendInvite.isPending}
+              onClick={afterInvites}
+            />
+          }
+        />
       </form>
     </AuthLayout>
   )

package/src/pages/onboarding/ModulesStepPage.tsx

@@ -0,0 +1,145 @@
+import { useState } from 'react'
+import type { FormEvent } from 'react'
+import { useNavigate, useSearchParams } from 'react-router'
+
+import { useSetModuleEnabled } from '../../api/resources/moduleSettings.ts'
+import { useInstallSampleData } from '../../api/resources/sampleData.ts'
+import { useSession } from '../../api/resources/session.ts'
+import { ErrorPanel, LoadingPanel } from '../../components/QueryState.tsx'
+import { AuthLayout } from '../auth/AuthLayout.tsx'
+import { organisationChoiceFromParam, organisationChoiceLabel } from './handbookTemplates.ts'
+import type { OrganisationChoiceId } from './handbookTemplates.ts'
+import { OnboardingNav } from './OnboardingNav.tsx'
+import { defaultOnboardingModuleState, onboardingModulesForChoice } from './onboardingModules.ts'
+import { isOnboardingRerun, ONBOARDING_ORG_PARAM, onboardingPath } from './onboardingRerun.ts'
+
+function modulesStepDescription(org: OrganisationChoiceId): string {
+  if (org === 'startup' || org === 'later') {
+    return 'Pick the parts of Kelpie your team needs today. Turn the rest on whenever you like — nothing here is permanent.'
+  }
+
+  return `Suggested for ${organisationChoiceLabel(org)}. Turn the rest on whenever you like — nothing here is permanent.`
+}
+
+/**
+ * Onboarding step 3: which optional modules this workspace runs.
+ *
+ * The workspace already exists. This step writes each of the six choices
+ * through `PATCH /v1/workspaces/:id/modules/:moduleId`, then optionally
+ * installs sample data, then moves on to invites. Defaults and explanations
+ * follow the organisation type on `?org=`. Other toggleable modules stay
+ * on; Admin → Modules is where they change later.
+ */
+
+export function ModulesStepPage(): React.JSX.Element {
+  const navigate = useNavigate()
+  const [searchParams] = useSearchParams()
+  const rerun = isOnboardingRerun(searchParams)
+  const org = organisationChoiceFromParam(searchParams.get(ONBOARDING_ORG_PARAM))
+  const modules = onboardingModulesForChoice(org)
+  const { session, isLoading } = useSession()
+  const setEnabled = useSetModuleEnabled()
+  const installSampleData = useInstallSampleData()
+  const [enabled, setEnabledState] = useState(() => defaultOnboardingModuleState(org))
+  const [seedSample, setSeedSample] = useState(false)
+  const [saving, setSaving] = useState(false)
+
+  function toggle(moduleId: (typeof modules)[number]['id'], next: boolean): void {
+    setEnabledState((previous) => ({ ...previous, [moduleId]: next }))
+  }
+
+  function submit(event: FormEvent): void {
+    event.preventDefault()
+
+    const workspaceId = session?.workspaceId
+
+    if (workspaceId === null || workspaceId === undefined) {
+      return
+    }
+
+    setSaving(true)
+
+    persistChoices()
+      .then(async () => {
+        if (seedSample) {
+          await installSampleData.runAsync({ workspaceId })
+        }
+
+        navigate(onboardingPath('/onboarding/invites', rerun, org), { replace: true })
+      })
+      .catch(() => undefined)
+      .finally(() => {
+        setSaving(false)
+      })
+  }
+
+  async function persistChoices(): Promise<void> {
+    for (const choice of modules) {
+      await setEnabled.runAsync({
+        moduleId: choice.id,
+        enabled: enabled[choice.id] === true,
+      })
+    }
+  }
+
+  const isPending = saving || setEnabled.isPending || installSampleData.isPending
+  const workspaceId = session?.workspaceId
+  const description = modulesStepDescription(org)
+
+  if (isLoading || workspaceId === null || workspaceId === undefined) {
+    return (
+      <AuthLayout step={3} title="What do you want to use?" description={description}>
+        <div className="mt-5">
+          <LoadingPanel label="Loading…" />
+        </div>
+      </AuthLayout>
+    )
+  }
+
+  return (
+    <AuthLayout step={3} title="What do you want to use?" description={description}>
+      <form onSubmit={submit} className="mt-5 space-y-3">
+        <ul className="space-y-3">
+          {modules.map((choice) => (
+            <li key={choice.id}>
+              <label className="flex items-start gap-2 text-[12px] text-ink">
+                <input
+                  type="checkbox"
+                  checked={enabled[choice.id] === true}
+                  onChange={(event) => {
+                    toggle(choice.id, event.target.checked)
+                  }}
+                  className="mt-0.5 h-4 w-4 rounded border-border text-accent focus:ring-accent"
+                />
+                <span>
+                  <span className="font-medium">{choice.label}</span>
+                  <span className="mt-0.5 block text-[11px] text-ink-muted">{choice.description}</span>
+                </span>
+              </label>
+            </li>
+          ))}
+        </ul>
+        <label className="flex items-start gap-2 text-[12px] text-ink">
+          <input
+            type="checkbox"
+            checked={seedSample}
+            onChange={(event) => setSeedSample(event.target.checked)}
+            className="mt-0.5 h-4 w-4 rounded border-border text-accent focus:ring-accent"
+          />
+          <span>
+            Fill it with sample data — a few companies, people, and records for the parts you
+            turned on, so you are not staring at an empty screen. Clear it out any time.
+          </span>
+        </label>
+        {setEnabled.error !== null && <ErrorPanel error={setEnabled.error} />}
+        {installSampleData.error !== null && <ErrorPanel error={installSampleData.error} />}
+        <OnboardingNav
+          step={3}
+          nextLabel="Next"
+          nextPendingLabel={installSampleData.isPending ? 'Installing sample data…' : 'Saving…'}
+          isPending={isPending}
+        />
+      </form>
+    </AuthLayout>
+  )
+}

package/src/pages/onboarding/OnboardingNav.tsx

@@ -0,0 +1,97 @@
+import type { ReactNode } from 'react'
+import { useNavigate, useSearchParams } from 'react-router'
+
+import type { OnboardingStep } from '../auth/AuthLayout.tsx'
+import { isOnboardingRerun, ONBOARDING_ORG_PARAM, onboardingPath } from './onboardingRerun.ts'
+
+/**
+ * The Previous / Next row every onboarding step shares.
+ *
+ * Forward still commits on the step that owns the form. This only moves
+ * between the five routes. Step 1 has no previous onboarding page, so
+ * Previous stays off there. The `rerun` and `org` queries are kept on
+ * Previous so a finished workspace that walks the wizard again still skips
+ * handbook seeding, and the modules step still sees the organisation type.
+ */
+
+const ONBOARDING_PATHS = {
+  1: '/onboarding/workspace',
+  2: '/onboarding/organisation',
+  3: '/onboarding/modules',
+  4: '/onboarding/invites',
+  5: '/onboarding/handbook',
+} as const
+
+const PRIMARY_CLASS =
+  'flex-1 rounded-md bg-accent px-3.5 py-2 text-[12px] font-semibold text-accent-fg transition hover:bg-accent-hover disabled:opacity-50'
+
+const SECONDARY_CLASS =
+  'flex-1 rounded-md border border-border bg-surface px-3.5 py-2 text-[12px] font-medium text-ink-muted transition hover:bg-surface-raised disabled:opacity-50'
+
+export interface OnboardingNavProps {
+  readonly step: OnboardingStep
+  readonly nextLabel: string
+  /** Shown while the step's request is in flight. */
+  readonly nextPendingLabel?: string
+  readonly isPending?: boolean
+  /** `submit` inside a form; `button` when the step only navigates. */
+  readonly nextType?: 'submit' | 'button'
+  readonly onNext?: () => void
+  /** A third action under the row, such as Skip on invites. */
+  readonly extra?: ReactNode
+}
+
+export function previousOnboardingPath(
+  step: OnboardingStep,
+  rerun = false,
+  org?: string | null,
+): string | undefined {
+  if (step === 1) {
+    return undefined
+  }
+
+  return onboardingPath(ONBOARDING_PATHS[(step - 1) as OnboardingStep], rerun, org)
+}
+
+export function OnboardingNav({
+  step,
+  nextLabel,
+  nextPendingLabel,
+  isPending = false,
+  nextType = 'submit',
+  onNext,
+  extra,
+}: OnboardingNavProps): React.JSX.Element {
+  const navigate = useNavigate()
+  const [searchParams] = useSearchParams()
+  const rerun = isOnboardingRerun(searchParams)
+  const previousTo = previousOnboardingPath(step, rerun, searchParams.get(ONBOARDING_ORG_PARAM))
+
+  return (
+    <div className="flex flex-col gap-2 pt-1">
+      <div className="flex gap-2">
+        {previousTo !== undefined && (
+          <button
+            type="button"
+            disabled={isPending}
+            onClick={() => {
+              navigate(previousTo, { replace: true })
+            }}
+            className={SECONDARY_CLASS}
+          >
+            Previous
+          </button>
+        )}
+        <button
+          type={nextType}
+          disabled={isPending}
+          onClick={onNext}
+          className={PRIMARY_CLASS}
+        >
+          {isPending && nextPendingLabel !== undefined ? nextPendingLabel : nextLabel}
+        </button>
+      </div>
+      {extra}
+    </div>
+  )
+}