@kelpie/ui 0.11.0 → 0.13.0

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>
+  )
+}

package/src/pages/onboarding/OrganisationStepPage.tsx

@@ -0,0 +1,130 @@
+import { useState } from 'react'
+import type { FormEvent } from 'react'
+import { useNavigate, useSearchParams } from 'react-router'
+
+import { useHandbookPages } from '../../api/resources/handbookPages.ts'
+import { useSeedHandbookForWorkspace } from '../../api/resources/handbookSeed.ts'
+import { ErrorPanel, LoadingPanel } from '../../components/QueryState.tsx'
+import { AuthLayout } from '../auth/AuthLayout.tsx'
+import {
+  handbookTemplateForChoice,
+  ORGANISATION_CHOICES,
+  organisationChoiceFromParam,
+} from './handbookTemplates.ts'
+import type { OrganisationChoiceId } from './handbookTemplates.ts'
+import { OnboardingNav } from './OnboardingNav.tsx'
+import { isOnboardingRerun, ONBOARDING_ORG_PARAM, onboardingPath } from './onboardingRerun.ts'
+
+/**
+ * Onboarding step 2: organisation type, then seed the starter handbook.
+ *
+ * The workspace already exists. This step writes pages through
+ * `POST /v1/workspaces/:id/handbook/seed`. "Choose later" seeds the original
+ * startup handbook. Changing the choice (via Previous) replaces pages only
+ * while they are still unedited starter stubs.
+ *
+ * A rerun still shows the choices, but does not seed or replace handbook
+ * pages. Next moves on to modules with those pages left alone.
+ */
+export function OrganisationStepPage(): React.JSX.Element {
+  const navigate = useNavigate()
+  const [searchParams] = useSearchParams()
+  const rerun = isOnboardingRerun(searchParams)
+  const seedHandbook = useSeedHandbookForWorkspace()
+  const { records: pages, isLoading } = useHandbookPages()
+  const [choice, setChoice] = useState<OrganisationChoiceId>(() =>
+    organisationChoiceFromParam(searchParams.get(ONBOARDING_ORG_PARAM)),
+  )
+
+  function goToModules(): void {
+    navigate(onboardingPath('/onboarding/modules', rerun, choice), { replace: true })
+  }
+
+  function submit(event: FormEvent): void {
+    event.preventDefault()
+
+    if (rerun) {
+      goToModules()
+      return
+    }
+
+    seedHandbook
+      .runAsync({
+        handbookTemplate: handbookTemplateForChoice(choice),
+        replace: pages.length > 0,
+      })
+      .then(() => {
+        goToModules()
+      })
+      .catch(() => undefined)
+  }
+
+  if (!rerun && isLoading) {
+    return (
+      <AuthLayout
+        step={2}
+        title="What kind of organisation is this?"
+        description="This picks the starter handbook pages agents read to learn what your company is."
+      >
+        <div className="mt-5">
+          <LoadingPanel label="Loading…" />
+        </div>
+      </AuthLayout>
+    )
+  }
+
+  return (
+    <AuthLayout
+      step={2}
+      title="What kind of organisation is this?"
+      description={
+        rerun
+          ? 'Pick a type to continue.'
+          : 'This picks the starter handbook pages agents read to learn what your company is.'
+      }
+    >
+      <form onSubmit={submit} className="mt-5 space-y-3">
+        <ul className="grid gap-2 sm:grid-cols-2">
+          {ORGANISATION_CHOICES.map((option) => (
+            <li
+              key={option.id}
+              className={option.id === 'later' ? 'h-full sm:col-span-2' : 'h-full'}
+            >
+              <label
+                className={`flex h-full cursor-pointer items-start gap-2 rounded-md border px-3 py-2 text-[12px] ${
+                  choice === option.id
+                    ? 'border-accent bg-accent/5 text-ink'
+                    : 'border-border bg-surface text-ink'
+                }`}
+              >
+                <input
+                  type="radio"
+                  name="organisation-type"
+                  value={option.id}
+                  checked={choice === option.id}
+                  disabled={seedHandbook.isPending}
+                  onChange={() => {
+                    setChoice(option.id)
+                  }}
+                  className="mt-0.5 h-4 w-4 border-border text-accent focus:ring-accent disabled:opacity-50"
+                />
+                <span>
+                  <span className="font-medium">{option.label}</span>
+                  <span className="mt-0.5 block text-[11px] text-ink-muted">{option.description}</span>
+                </span>
+              </label>
+            </li>
+          ))}
+        </ul>
+
+        {seedHandbook.error !== null && <ErrorPanel error={seedHandbook.error} />}
+        <OnboardingNav
+          step={2}
+          nextLabel="Next"
+          nextPendingLabel="Preparing handbook…"
+          isPending={seedHandbook.isPending}
+        />
+      </form>
+    </AuthLayout>
+  )
+}

package/src/pages/onboarding/WorkspaceStepPage.tsx

@@ -1,12 +1,13 @@
 import { useState } from 'react'
 import type { FormEvent } from 'react'
-import { Link, Navigate, useNavigate } from 'react-router'
+import { Link, Navigate, useNavigate, useSearchParams } from 'react-router'
 
-import { useInstallSampleData } from '../../api/resources/sampleData.ts'
 import { useCreateWorkspace, useSession } from '../../api/resources/session.ts'
 import { ErrorPanel } from '../../components/QueryState.tsx'
-import { SubmitButton, TextField } from '../auth/AuthForm.tsx'
+import { TextField } from '../auth/AuthForm.tsx'
 import { AuthLayout } from '../auth/AuthLayout.tsx'
+import { OnboardingNav } from './OnboardingNav.tsx'
+import { isOnboardingRerun, ONBOARDING_ORG_PARAM, onboardingPath } from './onboardingRerun.ts'
 
 /**
  * Onboarding step 1: the workspace, against `POST /v1/workspaces`.
@@ -15,9 +16,9 @@ import { AuthLayout } from '../auth/AuthLayout.tsx'
  * no workspace, so until this succeeds every CRM endpoint answers `403`, and
  * `SessionGate` sends anyone in that state here.
  *
- * One request does the whole thing: the service seeds the starter handbook and
- * the pipeline stages in the same transaction and moves this session into the
- * new workspace. There is nothing to re-login for and nothing to create next.
+ * One request creates the workspace, seeds pipeline stages, and moves this
+ * session into it. The starter handbook is seeded on step 4 once the reader
+ * picks an organisation type.
  *
  * It sits outside `SessionGate`, because being sent here *is* what the gate does
  * with an account that has no workspace, so gating it would loop. That leaves
@@ -47,14 +48,15 @@ function browserTimezone(): string {
 
 export function WorkspaceStepPage(): React.JSX.Element {
   const navigate = useNavigate()
-  const { isSignedOut } = useSession()
+  const [searchParams] = useSearchParams()
+  const rerun = isOnboardingRerun(searchParams)
+  const { isSignedOut, session } = useSession()
   const createWorkspace = useCreateWorkspace()
-  const installSampleData = useInstallSampleData()
+  const hasWorkspace = session?.workspaceId !== null && session?.workspaceId !== undefined
   const [name, setName] = useState('')
   const [slug, setSlug] = useState('')
   const [slugEdited, setSlugEdited] = useState(false)
   const [timezone] = useState(browserTimezone)
-  const [seedSample, setSeedSample] = useState(false)
 
   function changeName(value: string): void {
     setName(value)
@@ -74,17 +76,8 @@ export function WorkspaceStepPage(): React.JSX.Element {
 
     createWorkspace
       .runAsync({ name: name.trim(), slug: slug.trim(), timezone })
-      .then(async (workspace) => {
-        if (seedSample) {
-          // A refusal here does not block the wizard: the workspace itself is
-          // already created, and the invites step is what comes next either
-          // way. The error stays on screen so the reader sees what failed.
-          await installSampleData
-            .runAsync({ workspaceId: workspace.id })
-            .catch(() => undefined)
-        }
-
-        navigate('/onboarding/invites', { replace: true })
+      .then(() => {
+        navigate('/onboarding/organisation', { replace: true })
       })
       .catch(() => undefined)
   }
@@ -93,6 +86,41 @@ export function WorkspaceStepPage(): React.JSX.Element {
     return <Navigate to="/login" replace />
   }
 
+  /**
+   * Previous on a later step lands here after the workspace already exists.
+   * Showing the create form again would offer a second POST that this account
+   * cannot use. Next is the only action that remains. A rerun keeps the flag
+   * so organisation does not seed handbook pages and the review step is skipped.
+   */
+  if (hasWorkspace) {
+    return (
+      <AuthLayout
+        step={1}
+        title="Your workspace is ready"
+        description="Use Next to choose your organisation type and starter handbook."
+        footer={
+          <Link to="/login" className="font-medium text-accent hover:underline">
+            Sign in as somebody else
+          </Link>
+        }
+      >
+        <div className="mt-5">
+          <OnboardingNav
+            step={1}
+            nextLabel="Next"
+            nextType="button"
+            onNext={() => {
+              navigate(
+                onboardingPath('/onboarding/organisation', rerun, searchParams.get(ONBOARDING_ORG_PARAM)),
+                { replace: true },
+              )
+            }}
+          />
+        </div>
+      </AuthLayout>
+    )
+  }
+
   return (
     <AuthLayout
       step={1}
@@ -124,25 +152,12 @@ export function WorkspaceStepPage(): React.JSX.Element {
         <p className="text-[11px] text-ink-faint">
           Timezone: {timezone}. Change it later in Admin → Workspace.
         </p>
-        <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>
-            Install sample data — a small set of companies, people, deals, enquiries, opportunities,
-            fundraising, partnerships, and hiring so the workspace has something to look at.
-            You can delete it later.
-          </span>
-        </label>
         {createWorkspace.error !== null && <ErrorPanel error={createWorkspace.error} />}
-        {installSampleData.error !== null && <ErrorPanel error={installSampleData.error} />}
-        <SubmitButton
-          label="Continue"
-          pendingLabel={installSampleData.isPending ? 'Installing sample data…' : 'Creating…'}
-          isPending={createWorkspace.isPending || installSampleData.isPending}
+        <OnboardingNav
+          step={1}
+          nextLabel="Next"
+          nextPendingLabel="Creating…"
+          isPending={createWorkspace.isPending}
         />
       </form>
     </AuthLayout>

package/src/pages/onboarding/handbookTemplates.ts

@@ -0,0 +1,77 @@
+import type { HandbookTemplateId } from '@kelpie/schemas'
+
+/**
+ * Labels and descriptions for the organisation-type step. Page lists live
+ * server-side; `later` maps to the startup (original) handbook template.
+ */
+
+export type OrganisationChoiceId = HandbookTemplateId | 'later'
+
+export interface OrganisationChoice {
+  readonly id: OrganisationChoiceId
+  readonly label: string
+  readonly description: string
+}
+
+export const ORGANISATION_CHOICES: readonly OrganisationChoice[] = [
+  {
+    id: 'startup',
+    label: 'Startup',
+    description: 'Product company, SaaS, or tech startup.',
+  },
+  {
+    id: 'agency',
+    label: 'Agency',
+    description: 'Consultancy, design shop, dev shop, or marketing agency.',
+  },
+  {
+    id: 'nonprofit',
+    label: 'Nonprofit',
+    description: 'Charity, foundation, or social enterprise.',
+  },
+  {
+    id: 'community',
+    label: 'Community',
+    description: 'Club, association, co-op, or membership organisation.',
+  },
+  {
+    id: 'professional-services',
+    label: 'Professional services',
+    description: 'Law, accounting, architecture, or advisory practice.',
+  },
+  {
+    id: 'creator',
+    label: 'Creator',
+    description: 'Solo creator, freelancer, or personal brand.',
+  },
+  {
+    id: 'later',
+    label: 'Choose later',
+    description: 'Use the standard startup handbook for now. Edit pages any time.',
+  },
+]
+
+export const DEFAULT_ORGANISATION_CHOICE: OrganisationChoiceId = 'startup'
+
+export function isOrganisationChoiceId(value: string): value is OrganisationChoiceId {
+  return ORGANISATION_CHOICES.some((option) => option.id === value)
+}
+
+export function organisationChoiceFromParam(value: string | null): OrganisationChoiceId {
+  return value !== null && isOrganisationChoiceId(value) ? value : DEFAULT_ORGANISATION_CHOICE
+}
+
+export function organisationChoiceLabel(choice: OrganisationChoiceId): string {
+  for (const option of ORGANISATION_CHOICES) {
+    if (option.id === choice) {
+      return option.label
+    }
+  }
+
+  return 'Startup'
+}
+
+/** `later` seeds the original startup pages. */
+export function handbookTemplateForChoice(choice: OrganisationChoiceId): HandbookTemplateId {
+  return choice === 'later' ? 'startup' : choice
+}