@kelpie/ui 0.11.0 → 0.13.0

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/registry/context.ts

@@ -2,6 +2,7 @@ import { createContext, useContext } from 'react'
 import type { ComponentType } from 'react'
 
 import type {
+  AuthMethod,
   DashboardCard,
   ExtensibleRecordType,
   NavItem,
@@ -53,6 +54,11 @@ export function useDashboardCards(): readonly DashboardCard[] {
   return useUiExtensions().dashboardCards()
 }
 
+/** Extra ways to sign in, for the signed-out pages to render beside their form. */
+export function useAuthMethods(): readonly AuthMethod[] {
+  return useUiExtensions().authMethods()
+}
+
 /**
  * The component to render for an overridable: a module's replacement, or core's
  * own. Core calls this instead of rendering its component directly.

package/src/registry/contributions.ts

@@ -25,6 +25,32 @@ export interface NavItem {
   readonly icon?: ReactNode
 }
 
+/**
+ * What a sign-in method is rendering against.
+ *
+ * `intent` because the same button reads differently on the two pages, and
+ * `next` because where the browser lands afterwards is the page's to decide,
+ * not the module's. The page has already checked it is a path within the app.
+ */
+export interface AuthMethodContext {
+  readonly intent: 'login' | 'signup'
+  readonly next: string
+}
+
+/**
+ * Another way to sign in, offered beside the password form.
+ *
+ * Core renders whatever a module returns and nothing around it: no divider, no
+ * heading. A module cannot always tell at build time whether it has anything to
+ * offer (an unconfigured provider renders nothing at all), and core framing
+ * would then decorate an empty space.
+ */
+export interface AuthMethod {
+  readonly id: string
+  readonly order?: number
+  readonly render: (context: AuthMethodContext) => ReactNode
+}
+
 /** A whole page, mounted under the shell's chrome. */
 export interface RouteContribution {
   readonly path: string

package/src/registry/registry.ts

@@ -1,6 +1,7 @@
 import type { ComponentType } from 'react'
 
 import type {
+  AuthMethod,
   DashboardCard,
   ExtensibleRecordType,
   NavItem,
@@ -31,6 +32,8 @@ export interface UiModuleContext {
   recordTab(objectType: ExtensibleRecordType, tab: RecordTab): void
   recordSidebarCard(objectType: ExtensibleRecordType, card: RecordSidebarCard): void
   dashboardCard(card: DashboardCard): void
+  /** Another way to sign in, rendered beside the password form on `/login` and `/signup`. */
+  authMethod(method: AuthMethod): void
   /** Replaces a core component. Prefer a slot; see `modules.md`. */
   override<Props>(token: Overridable<Props>, component: ComponentType<Props>): void
 }
@@ -47,6 +50,7 @@ export interface UiExtensions {
   recordTabs(objectType: ExtensibleRecordType): readonly RecordTab[]
   recordSidebarCards(objectType: ExtensibleRecordType): readonly RecordSidebarCard[]
   dashboardCards(): readonly DashboardCard[]
+  authMethods(): readonly AuthMethod[]
   componentFor<Props>(token: Overridable<Props>): ComponentType<Props>
 }
 
@@ -70,6 +74,7 @@ interface Accumulator {
   readonly recordTabs: Map<ExtensibleRecordType, RecordTab[]>
   readonly recordSidebarCards: Map<ExtensibleRecordType, RecordSidebarCard[]>
   readonly dashboardCards: DashboardCard[]
+  readonly authMethods: AuthMethod[]
   readonly overrides: OverrideStore
 }
 
@@ -134,6 +139,11 @@ function createModuleContext(
       accumulator.dashboardCards.push(card)
     },
 
+    authMethod(method) {
+      claim(taken, module.id, 'auth.methods', method.id)
+      accumulator.authMethods.push(method)
+    },
+
     override(token, component) {
       if (accumulator.overrides.has(token.key)) {
         throw new UiModuleError(
@@ -158,6 +168,7 @@ export function registerUiModules(modules: readonly UiModule[]): UiExtensions {
     recordTabs: new Map(),
     recordSidebarCards: new Map(),
     dashboardCards: [],
+    authMethods: [],
     overrides: createOverrideStore(),
   }
   const taken = new Set<string>()
@@ -179,6 +190,7 @@ export function registerUiModules(modules: readonly UiModule[]): UiExtensions {
     recordSidebarCards: (objectType) =>
       inSlotOrder(accumulator.recordSidebarCards.get(objectType) ?? []),
     dashboardCards: () => inSlotOrder(accumulator.dashboardCards),
+    authMethods: () => inSlotOrder(accumulator.authMethods),
     componentFor: (token) => accumulator.overrides.get(token),
   }
 }

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;