@kelpie/ui 0.12.0 → 0.14.0

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

package/src/pages/onboarding/onboardingModules.ts

@@ -0,0 +1,202 @@
+import type { OrganisationChoiceId } from './handbookTemplates.ts'
+
+/**
+ * The six optional modules the setup wizard offers. Other toggleable modules
+ * stay on; Admin → Modules is where they change later.
+ *
+ * Ids match the server module catalog (`deals`, `raises`, …). The wizard is
+ * what writes the first `workspace_module_settings` rows for these six.
+ *
+ * Labels stay the domain names. Defaults and explanations follow the
+ * organisation type chosen on the previous step (`onboarding.md`).
+ */
+
+export type OnboardingModuleId =
+  | 'deals'
+  | 'opportunities'
+  | 'raises'
+  | 'partnerships'
+  | 'events'
+  | 'forms'
+
+export interface OnboardingModuleChoice {
+  readonly id: OnboardingModuleId
+  readonly label: string
+  readonly description: string
+  readonly defaultEnabled: boolean
+}
+
+interface ModulePreset {
+  readonly enabled: Readonly<Record<OnboardingModuleId, boolean>>
+  readonly descriptions: Readonly<Record<OnboardingModuleId, string>>
+}
+
+const LABELS: Readonly<Record<OnboardingModuleId, string>> = {
+  deals: 'Deals',
+  opportunities: 'Opportunities',
+  raises: 'Fundraising',
+  partnerships: 'Partnerships',
+  events: 'Events',
+  forms: 'Forms',
+}
+
+const MODULE_ORDER: readonly OnboardingModuleId[] = [
+  'deals',
+  'opportunities',
+  'raises',
+  'partnerships',
+  'events',
+  'forms',
+]
+
+/** Startup / Choose later — every optional module starts on. */
+const STARTUP: ModulePreset = {
+  enabled: {
+    deals: true,
+    opportunities: true,
+    raises: true,
+    partnerships: true,
+    events: true,
+    forms: true,
+  },
+  descriptions: {
+    deals: 'Track sales you are trying to close, from first chat to won or lost.',
+    opportunities: 'Chase things that are not sales — grants, awards, press, a speaking slot.',
+    raises: 'Run a funding round: who you are talking to, and where each one is up to.',
+    partnerships: 'Keep tabs on the people you work with long-term, and when to check in next.',
+    events: 'Plan meetups, dinners, and webinars, and see who is coming.',
+    forms: 'Put a form on your site. New sign-ups land in Kelpie on their own.',
+  },
+}
+
+const AGENCY: ModulePreset = {
+  enabled: {
+    deals: true,
+    opportunities: false,
+    raises: false,
+    partnerships: true,
+    events: true,
+    forms: true,
+  },
+  descriptions: {
+    deals: 'Track pitches, retainers, and projects you are trying to close.',
+    opportunities: 'Chase RFPs, awards, press, and speaking slots that are not billed work.',
+    raises: 'Run a funding round: who you are talking to, and where each one is up to.',
+    partnerships: 'Keep tabs on subcontractors, channel partners, and when to check in next.',
+    events: 'Plan workshops, client dinners, and webinars, and see who is coming.',
+    forms: 'Put a form on your site. New enquiries land in Kelpie on their own.',
+  },
+}
+
+const NONPROFIT: ModulePreset = {
+  enabled: {
+    deals: false,
+    opportunities: true,
+    raises: true,
+    partnerships: true,
+    events: true,
+    forms: true,
+  },
+  descriptions: {
+    deals: 'Track sponsorships or earned-income work you are trying to close.',
+    opportunities: 'Chase grants, awards, press, and speaking slots.',
+    raises: 'Track who you are raising from, and where each conversation is up to.',
+    partnerships: 'Keep tabs on the organisations you work with long-term, and when to check in next.',
+    events: 'Plan fundraisers, volunteer days, and community gatherings, and see who is coming.',
+    forms: 'Put a form on your site. New supporters land in Kelpie on their own.',
+  },
+}
+
+const COMMUNITY: ModulePreset = {
+  enabled: {
+    deals: false,
+    opportunities: true,
+    raises: true,
+    partnerships: true,
+    events: true,
+    forms: true,
+  },
+  descriptions: {
+    deals: 'Track sponsorships or paid programmes you are trying to close.',
+    opportunities: 'Chase grants, press, and speaking slots that are not membership sales.',
+    raises: 'Track who you are raising from, and where each conversation is up to.',
+    partnerships: 'Keep tabs on sister organisations and long-term collaborators, and when to check in next.',
+    events: 'Plan meetups, dinners, and member gatherings, and see who is coming.',
+    forms: 'Put a join or contact form on your site. New sign-ups land in Kelpie on their own.',
+  },
+}
+
+const PROFESSIONAL_SERVICES: ModulePreset = {
+  enabled: {
+    deals: true,
+    opportunities: false,
+    raises: false,
+    partnerships: false,
+    events: true,
+    forms: true,
+  },
+  descriptions: {
+    deals: 'Track engagements from first conversation to won or lost.',
+    opportunities: 'Chase tenders, panels, press, and speaking slots.',
+    raises: 'Run a funding round: who you are talking to, and where each one is up to.',
+    partnerships: 'Keep tabs on referral sources and when to check in next.',
+    events: 'Plan client seminars, dinners, and webinars, and see who is coming.',
+    forms: 'Put a form on your site. New enquiries land in Kelpie on their own.',
+  },
+}
+
+const CREATOR: ModulePreset = {
+  enabled: {
+    deals: true,
+    opportunities: true,
+    raises: false,
+    partnerships: false,
+    events: false,
+    forms: true,
+  },
+  descriptions: {
+    deals: 'Track brand deals and client work from first chat to won or lost.',
+    opportunities: 'Chase press, speaking, and other chances that are not billed work.',
+    raises: 'Run a funding round: who you are talking to, and where each one is up to.',
+    partnerships: 'Keep tabs on the brands you work with long-term, and when to check in next.',
+    events: 'Plan meetups, launches, and webinars, and see who is coming.',
+    forms: 'Put a form on your site. New enquiries land in Kelpie on their own.',
+  },
+}
+
+const PRESETS: Readonly<Record<Exclude<OrganisationChoiceId, 'later'>, ModulePreset>> = {
+  startup: STARTUP,
+  agency: AGENCY,
+  nonprofit: NONPROFIT,
+  community: COMMUNITY,
+  'professional-services': PROFESSIONAL_SERVICES,
+  creator: CREATOR,
+}
+
+function presetForChoice(choice: OrganisationChoiceId): ModulePreset {
+  return choice === 'later' ? STARTUP : PRESETS[choice]
+}
+
+/** Startup catalog. Prefer `onboardingModulesForChoice` when a type is known. */
+export const ONBOARDING_MODULES: readonly OnboardingModuleChoice[] = modulesFromPreset(STARTUP)
+
+export function onboardingModulesForChoice(
+  choice: OrganisationChoiceId,
+): readonly OnboardingModuleChoice[] {
+  return modulesFromPreset(presetForChoice(choice))
+}
+
+export function defaultOnboardingModuleState(
+  choice: OrganisationChoiceId = 'startup',
+): Record<OnboardingModuleId, boolean> {
+  return { ...presetForChoice(choice).enabled }
+}
+
+function modulesFromPreset(preset: ModulePreset): readonly OnboardingModuleChoice[] {
+  return MODULE_ORDER.map((id) => ({
+    id,
+    label: LABELS[id],
+    description: preset.descriptions[id],
+    defaultEnabled: preset.enabled[id],
+  }))
+}

package/src/pages/onboarding/onboardingRerun.ts

@@ -0,0 +1,41 @@
+/**
+ * A finished workspace can walk the wizard again from the account menu.
+ *
+ * `?rerun=1` marks that path. Organisation still runs so the reader can pick
+ * a type, but handbook pages are not seeded or replaced. The handbook review
+ * step is skipped: workspace → organisation → modules → invites → dashboard.
+ */
+
+export const ONBOARDING_RERUN_PARAM = 'rerun'
+export const ONBOARDING_RERUN_VALUE = '1'
+
+/** Organisation type chosen on step 2 — drives module defaults on step 3. */
+export const ONBOARDING_ORG_PARAM = 'org'
+
+/** Entry URL the account menu opens for a rerun. */
+export const ONBOARDING_RERUN_ENTRY = `/onboarding/workspace?${ONBOARDING_RERUN_PARAM}=${ONBOARDING_RERUN_VALUE}`
+
+export function isOnboardingRerun(searchParams: URLSearchParams): boolean {
+  return searchParams.get(ONBOARDING_RERUN_PARAM) === ONBOARDING_RERUN_VALUE
+}
+
+/**
+ * Keep the rerun flag and the organisation type when moving between onboarding
+ * routes. `org` is how the modules step knows which defaults to offer; nothing
+ * else is held in the browser (`onboarding.md`).
+ */
+export function onboardingPath(path: string, rerun: boolean, org?: string | null): string {
+  const params = new URLSearchParams()
+
+  if (rerun) {
+    params.set(ONBOARDING_RERUN_PARAM, ONBOARDING_RERUN_VALUE)
+  }
+
+  if (org !== undefined && org !== null && org !== '') {
+    params.set(ONBOARDING_ORG_PARAM, org)
+  }
+
+  const query = params.toString()
+
+  return query === '' ? path : `${path}?${query}`
+}

package/src/styles.css

@@ -41,6 +41,16 @@
   --color-success-soft: var(--success-soft);
   --color-warning: var(--warning);
   --color-warning-soft: var(--warning-soft);
+  --color-env-dev: var(--env-dev);
+  --color-env-dev-fg: var(--env-dev-fg);
+  --color-env-demo: var(--env-demo);
+  --color-env-demo-fg: var(--env-demo-fg);
+  --color-env-staging: var(--env-staging);
+  --color-env-staging-fg: var(--env-staging-fg);
+  --color-env-test: var(--env-test);
+  --color-env-test-fg: var(--env-test-fg);
+  --color-env-cloud: var(--env-cloud);
+  --color-env-cloud-fg: var(--env-cloud-fg);
   --color-sidebar: var(--sidebar);
   --color-sidebar-ink: var(--sidebar-ink);
   --color-sidebar-muted: var(--sidebar-muted);
@@ -73,6 +83,16 @@
   --success-soft: #ecfdf5;
   --warning: #d97706;
   --warning-soft: #fffbeb;
+  --env-dev: #d97706;
+  --env-dev-fg: #18181b;
+  --env-demo: var(--accent);
+  --env-demo-fg: var(--accent-fg);
+  --env-staging: #6d28d9;
+  --env-staging-fg: #ffffff;
+  --env-test: #475569;
+  --env-test-fg: #ffffff;
+  --env-cloud: #1d4ed8;
+  --env-cloud-fg: #ffffff;
   --sidebar: #fafafa;
   --sidebar-ink: #18181b;
   --sidebar-muted: #52525b;
@@ -105,6 +125,16 @@
   --success-soft: #064e3b;
   --warning: #fbbf24;
   --warning-soft: #451a03;
+  --env-dev: #fbbf24;
+  --env-dev-fg: #451a03;
+  --env-demo: var(--accent);
+  --env-demo-fg: var(--accent-fg);
+  --env-staging: #a78bfa;
+  --env-staging-fg: #1e1b4b;
+  --env-test: #94a3b8;
+  --env-test-fg: #0f172a;
+  --env-cloud: #60a5fa;
+  --env-cloud-fg: #1e3a8a;
   --sidebar: #0c0c0d;
   --sidebar-ink: #fafafa;
   --sidebar-muted: #a1a1aa;