@kelpie/ui 0.1.0

package/src/pages/onboarding/InvitesStepPage.tsx

@@ -0,0 +1,180 @@
+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 { useSendInvite } from '../../api/resources/invites.ts'
+import { AUTH_INPUT_CLASS, SecondaryButton, SubmitButton } from '../auth/AuthForm.tsx'
+import { AuthLayout } from '../auth/AuthLayout.tsx'
+
+/**
+ * Onboarding step 2: 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
+ * this because it sent nothing. Here a row carries its own outcome, a sent one
+ * is never sent twice, and the step only advances once nothing is outstanding.
+ *
+ * Skippable, per `onboarding.md`. Admin → Team does the same job later.
+ */
+
+interface InviteRow {
+  readonly email: string
+  readonly role: InvitableRole
+  /** Accepted by the service. A retry of the other rows must not send it again. */
+  readonly sent: boolean
+  readonly failure: string | null
+}
+
+function emptyRow(): InviteRow {
+  return { email: '', role: 'member', sent: false, failure: null }
+}
+
+/** A row worth sending: it has an address and has not already been accepted. */
+function isOutstanding(row: InviteRow): boolean {
+  return row.email.trim().length > 0 && !row.sent
+}
+
+export function InvitesStepPage(): React.JSX.Element {
+  const navigate = useNavigate()
+  const sendInvite = useSendInvite()
+  const [rows, setRows] = useState<readonly InviteRow[]>([emptyRow()])
+
+  function changeRow(index: number, changes: Partial<InviteRow>): void {
+    setRows((previous) =>
+      previous.map((row, at) => (at === index ? { ...row, ...changes } : row)),
+    )
+  }
+
+  /**
+   * Sends every outstanding row, one at a time, and reports each result on its
+   * own row. Sequential rather than concurrent: a person reading a list of
+   * failures wants them in the order they typed the addresses.
+   */
+  async function sendOutstanding(): Promise<boolean> {
+    let allSent = true
+
+    for (const [index, row] of rows.entries()) {
+      if (!isOutstanding(row)) {
+        continue
+      }
+
+      try {
+        await sendInvite.runAsync({ email: row.email.trim(), role: row.role })
+        changeRow(index, { sent: true, failure: null })
+      } catch (error: unknown) {
+        allSent = false
+        changeRow(index, {
+          failure: error instanceof Error ? error.message : 'Could not send this invitation.',
+        })
+      }
+    }
+
+    return allSent
+  }
+
+  function submit(event: FormEvent): void {
+    event.preventDefault()
+
+    sendOutstanding()
+      .then((allSent) => {
+        if (allSent) {
+          navigate('/onboarding/handbook', { replace: true })
+        }
+      })
+      .catch(() => undefined)
+  }
+
+  const outstanding = rows.filter(isOutstanding).length
+
+  return (
+    <AuthLayout
+      step={2}
+      title="Invite teammates"
+      description="Optional. You can always invite people later from Admin → Team."
+    >
+      <form onSubmit={submit} className="mt-5 space-y-3">
+        {rows.map((row, index) => (
+          <InviteRowFields
+            // Rows are only appended, so the position is stable for the life of
+            // the page and identifies the row a result belongs to.
+            key={index}
+            row={row}
+            onChange={(changes) => {
+              changeRow(index, changes)
+            }}
+          />
+        ))}
+
+        <button
+          type="button"
+          onClick={() => {
+            setRows((previous) => [...previous, emptyRow()])
+          }}
+          className="text-[12px] font-medium text-accent hover:underline"
+        >
+          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>
+      </form>
+    </AuthLayout>
+  )
+}
+
+function InviteRowFields({
+  row,
+  onChange,
+}: {
+  readonly row: InviteRow
+  readonly onChange: (changes: Partial<InviteRow>) => void
+}): React.JSX.Element {
+  return (
+    <div>
+      <div className="flex gap-2">
+        <input
+          type="email"
+          value={row.email}
+          onChange={(event) => {
+            // Editing an address makes it a different invitation, so a failure
+            // recorded against the old one no longer applies.
+            onChange({ email: event.target.value, failure: null })
+          }}
+          disabled={row.sent}
+          placeholder="colleague@company.com"
+          className={`min-w-0 flex-1 ${AUTH_INPUT_CLASS} disabled:opacity-60`}
+        />
+        <select
+          value={row.role}
+          onChange={(event) => {
+            onChange({ role: event.target.value as InvitableRole })
+          }}
+          disabled={row.sent}
+          className="rounded-md border border-border bg-surface px-2 py-2 text-[12px] outline-none focus:border-accent disabled:opacity-60"
+        >
+          {INVITABLE_ROLES.map((role) => (
+            <option key={role} value={role}>
+              {role === 'admin' ? 'Admin' : 'Member'}
+            </option>
+          ))}
+        </select>
+      </div>
+      {row.sent && <p className="mt-1 text-[11px] font-medium text-success">Invitation sent</p>}
+      {row.failure !== null && <p className="mt-1 text-[11px] text-danger">{row.failure}</p>}
+    </div>
+  )
+}

package/src/pages/onboarding/WorkspaceStepPage.tsx

@@ -0,0 +1,122 @@
+import { useState } from 'react'
+import type { FormEvent } from 'react'
+import { Link, Navigate, useNavigate } from 'react-router'
+
+import { useCreateWorkspace, useSession } from '../../api/resources/session.ts'
+import { ErrorPanel } from '../../components/QueryState.tsx'
+import { SubmitButton, TextField } from '../auth/AuthForm.tsx'
+import { AuthLayout } from '../auth/AuthLayout.tsx'
+
+/**
+ * Onboarding step 1: the workspace, against `POST /v1/workspaces`.
+ *
+ * This is the step the rest of the app waits on. Signup creates an account and
+ * 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.
+ *
+ * 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
+ * the signed-out case to the page: without this check, somebody arriving here
+ * signed out fills in a form whose only possible answer is `401`.
+ */
+
+/** The rule the API enforces: lowercase letters, digits, and hyphens. */
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/gu, '-')
+    .replace(/^-+|-+$/gu, '')
+    .slice(0, 63)
+}
+
+/**
+ * The zone the browser is in.
+ *
+ * The mockup offered a list of five. A guess from the platform is right more
+ * often than a five-item list is, and Admin → Workspace is where it gets
+ * changed. The value is shown rather than hidden so a wrong guess is visible.
+ */
+function browserTimezone(): string {
+  return Intl.DateTimeFormat().resolvedOptions().timeZone
+}
+
+export function WorkspaceStepPage(): React.JSX.Element {
+  const navigate = useNavigate()
+  const { isSignedOut } = useSession()
+  const createWorkspace = useCreateWorkspace()
+  const [name, setName] = useState('')
+  const [slug, setSlug] = useState('')
+  const [slugEdited, setSlugEdited] = useState(false)
+  const [timezone] = useState(browserTimezone)
+
+  function changeName(value: string): void {
+    setName(value)
+
+    if (!slugEdited) {
+      setSlug(slugify(value))
+    }
+  }
+
+  function changeSlug(value: string): void {
+    setSlugEdited(true)
+    setSlug(slugify(value))
+  }
+
+  function submit(event: FormEvent): void {
+    event.preventDefault()
+
+    createWorkspace
+      .runAsync({ name: name.trim(), slug: slug.trim(), timezone })
+      .then(() => navigate('/onboarding/invites', { replace: true }))
+      .catch(() => undefined)
+  }
+
+  if (isSignedOut) {
+    return <Navigate to="/login" replace />
+  }
+
+  return (
+    <AuthLayout
+      step={1}
+      title="Create your workspace"
+      description="A workspace is your company brain — CRM records, handbook, and team."
+      footer={
+        <Link to="/login" className="font-medium text-accent hover:underline">
+          Sign in as somebody else
+        </Link>
+      }
+    >
+      <form onSubmit={submit} className="mt-5 space-y-3">
+        <TextField
+          label="Workspace name"
+          value={name}
+          onChange={changeName}
+          placeholder="Acme Labs"
+          autoComplete="organization"
+          required
+        />
+        <TextField
+          label="Slug"
+          value={slug}
+          onChange={changeSlug}
+          hint="Lowercase letters, digits, and hyphens. It appears in URLs."
+          mono
+          required
+        />
+        <p className="text-[11px] text-ink-faint">
+          Timezone: {timezone}. Change it later in Admin → Workspace.
+        </p>
+        {createWorkspace.error !== null && <ErrorPanel error={createWorkspace.error} />}
+        <SubmitButton
+          label="Continue"
+          pendingLabel="Creating…"
+          isPending={createWorkspace.isPending}
+        />
+      </form>
+    </AuthLayout>
+  )
+}

package/src/pages/positionDirectory.ts

@@ -0,0 +1,98 @@
+import { useMemo } from 'react'
+
+import { useCompanies } from '../api/resources/companies.ts'
+import { usePositions } from '../api/resources/positions.ts'
+
+/**
+ * Titles and company names for the people on screen, and head counts for the
+ * companies on screen.
+ *
+ * A list row needs data from three resources, and `api.md` has no
+ * include-expansion. What it does have is repeatable id filters, so each of
+ * these asks about exactly the rows the page is rendering: two extra requests
+ * for the page, not one per row, and no cap that a real workspace could grow
+ * past.
+ *
+ * Both hold their request back until the ids are known. Asking with the filter
+ * omitted would answer with every record in the workspace, which is the wrong
+ * answer rather than a slow one.
+ */
+
+/** `api.md`: `?limit=` and an id filter both max out at 200. */
+const MAX_PAGE = 200
+
+export interface PeopleDirectory {
+  /** The first title a person holds, matching the mockup's primary position. */
+  titleFor(personId: string): string | undefined
+  companyNamesFor(personId: string): readonly string[]
+  readonly isLoading: boolean
+  /**
+   * False when these people hold more positions than one page could return.
+   * Rare, and the page says so rather than leaving a cell blank, because a blank
+   * that means "we did not look" reads the same as one that means "no company".
+   */
+  readonly isComplete: boolean
+}
+
+export function usePeopleDirectory(personIds: readonly string[]): PeopleDirectory {
+  const enabled = personIds.length > 0
+  const positions = usePositions({ personIds, limit: MAX_PAGE }, { enabled })
+  const companies = useCompanies({ personIds, limit: MAX_PAGE }, { enabled })
+
+  const companyNameById = useMemo(
+    () => new Map(companies.records.map((company) => [company.id, company.name])),
+    [companies.records],
+  )
+
+  const byPerson = useMemo(() => {
+    const grouped = new Map<string, { title: string; companyId: string }[]>()
+
+    for (const position of positions.records) {
+      const held = grouped.get(position.personId) ?? []
+
+      held.push({ title: position.title, companyId: position.companyId })
+      grouped.set(position.personId, held)
+    }
+
+    return grouped
+  }, [positions.records])
+
+  return {
+    titleFor: (personId) => byPerson.get(personId)?.[0]?.title,
+    companyNamesFor: (personId) =>
+      (byPerson.get(personId) ?? [])
+        .map((held) => companyNameById.get(held.companyId))
+        .filter((name): name is string => name !== undefined),
+    isLoading: positions.isLoading || companies.isLoading,
+    isComplete: !positions.hasMore && !companies.hasMore,
+  }
+}
+
+export interface CompanyHeadcounts {
+  countFor(companyId: string): number
+  readonly isLoading: boolean
+  readonly isComplete: boolean
+}
+
+export function useCompanyHeadcounts(companyIds: readonly string[]): CompanyHeadcounts {
+  const positions = usePositions(
+    { companyIds, limit: MAX_PAGE },
+    { enabled: companyIds.length > 0 },
+  )
+
+  const countByCompany = useMemo(() => {
+    const counts = new Map<string, number>()
+
+    for (const position of positions.records) {
+      counts.set(position.companyId, (counts.get(position.companyId) ?? 0) + 1)
+    }
+
+    return counts
+  }, [positions.records])
+
+  return {
+    countFor: (companyId) => countByCompany.get(companyId) ?? 0,
+    isLoading: positions.isLoading,
+    isComplete: !positions.hasMore,
+  }
+}

package/src/registry/UiExtensionProvider.tsx

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react'
+
+import { UiExtensionContext } from './context.ts'
+import type { UiExtensions } from './registry.ts'
+
+export interface UiExtensionProviderProps {
+  readonly extensions: UiExtensions
+  readonly children: ReactNode
+}
+
+/**
+ * Puts a built registry in reach of the tree below it. The assembly wraps its
+ * root in one of these; nothing else should need to.
+ */
+export function UiExtensionProvider({
+  extensions,
+  children,
+}: UiExtensionProviderProps): React.JSX.Element {
+  return <UiExtensionContext value={extensions}>{children}</UiExtensionContext>
+}

package/src/registry/context.ts

@@ -0,0 +1,67 @@
+import { createContext, useContext } from 'react'
+import type { ComponentType } from 'react'
+
+import type {
+  DashboardCard,
+  ExtensibleRecordType,
+  IntegrationProvider,
+  NavItem,
+  NavSlot,
+  RecordSidebarCard,
+  RecordTab,
+  RouteContribution,
+} from './contributions.ts'
+import type { Overridable } from './overridable.ts'
+import { NO_UI_MODULES } from './registry.ts'
+import type { UiExtensions } from './registry.ts'
+
+/**
+ * Reading the registry from a component.
+ *
+ * The default is the empty registry rather than an error, so a component tree
+ * without a provider behaves exactly like an assembly with no modules: every
+ * slot empty, every overridable rendering core's own component. A page under
+ * test needs no setup to look right.
+ *
+ * The provider lives in its own file so Fast Refresh keeps working; a module
+ * that exports both a component and a hook loses it.
+ */
+export const UiExtensionContext = createContext<UiExtensions>(NO_UI_MODULES)
+
+export function useUiExtensions(): UiExtensions {
+  return useContext(UiExtensionContext)
+}
+
+/** Module nav items for one slot, in order. The shell merges its own items in. */
+export function useNavItems(slot: NavSlot): readonly NavItem[] {
+  return useUiExtensions().navItems(slot)
+}
+
+/** Whole pages modules contribute, mounted under the shell's chrome. */
+export function useModuleRoutes(): readonly RouteContribution[] {
+  return useUiExtensions().routes()
+}
+
+export function useRecordTabs(objectType: ExtensibleRecordType): readonly RecordTab[] {
+  return useUiExtensions().recordTabs(objectType)
+}
+
+export function useRecordSidebarCards(objectType: ExtensibleRecordType): readonly RecordSidebarCard[] {
+  return useUiExtensions().recordSidebarCards(objectType)
+}
+
+export function useDashboardCards(): readonly DashboardCard[] {
+  return useUiExtensions().dashboardCards()
+}
+
+export function useIntegrationProviders(): readonly IntegrationProvider[] {
+  return useUiExtensions().integrationProviders()
+}
+
+/**
+ * The component to render for an overridable: a module's replacement, or core's
+ * own. Core calls this instead of rendering its component directly.
+ */
+export function useOverridable<Props>(token: Overridable<Props>): ComponentType<Props> {
+  return useUiExtensions().componentFor(token)
+}

package/src/registry/contributions.ts

@@ -0,0 +1,89 @@
+import type { ExtensibleRecordType } from '@kelpie/schemas'
+import type { ComponentType, ReactNode } from 'react'
+
+/**
+ * What a UI module may add to the shell, per the slot table in `modules.md`.
+ *
+ * Every slot renders nothing when empty. A core page has to look finished with
+ * no modules loaded at all, because the open-source assembly is exactly that.
+ */
+
+export const NAV_SLOTS = ['primary', 'admin', 'account'] as const
+
+export type NavSlot = (typeof NAV_SLOTS)[number]
+
+export interface NavItem {
+  readonly id: string
+  readonly label: string
+  /** Route path, the same string the shell's router matches. */
+  readonly to: string
+  /**
+   * Where it sits among the core items. Core numbers itself in hundreds, so a
+   * module can land between two of them without core renumbering.
+   */
+  readonly order?: number
+  readonly icon?: ReactNode
+}
+
+/** A whole page, mounted under the shell's chrome. */
+export interface RouteContribution {
+  readonly path: string
+  readonly element: ReactNode
+}
+
+/**
+ * The record types a detail page exists for, and therefore the ones a module can
+ * add a tab or a sidebar card to.
+ *
+ * Now in `@kelpie/schemas`, which is the shared-schema package this file's
+ * previous note was waiting for. Re-exported rather than moved outright: it is
+ * part of the contribution vocabulary, and a module author reading this file
+ * should not have to follow an import to learn what a record type is.
+ */
+export { EXTENSIBLE_RECORD_TYPES } from '@kelpie/schemas'
+export type { ExtensibleRecordType }
+
+/** What a tab or card is rendering against. Ids, not records: the contributor fetches its own data. */
+export interface RecordContext {
+  readonly objectType: ExtensibleRecordType
+  readonly recordId: string
+}
+
+export interface RecordTab {
+  readonly id: string
+  readonly label: string
+  readonly order?: number
+  readonly render: (context: RecordContext) => ReactNode
+}
+
+export interface RecordSidebarCard {
+  readonly id: string
+  readonly order?: number
+  readonly render: (context: RecordContext) => ReactNode
+}
+
+export interface DashboardCard {
+  readonly id: string
+  readonly order?: number
+  readonly render: () => ReactNode
+}
+
+export const INTEGRATION_CATEGORIES = [
+  'messaging',
+  'identity',
+  'enrichment',
+  'email',
+  'calendar',
+] as const
+
+export type IntegrationCategory = (typeof INTEGRATION_CATEGORIES)[number]
+
+/** A catalog entry on the admin integrations page. Core owns the page and the connection lifecycle. */
+export interface IntegrationProvider {
+  readonly id: string
+  readonly name: string
+  readonly category: IntegrationCategory
+  readonly description: string
+  /** Rendered on the provider's own settings panel once connected. */
+  readonly settings?: ComponentType<Record<string, never>>
+}

package/src/registry/overridable.ts

@@ -0,0 +1,62 @@
+import type { ComponentType } from 'react'
+
+/**
+ * The override escape hatch from `modules.md`: a module replaces a core
+ * component outright. Prefer a slot; this is for the cases a slot cannot reach.
+ *
+ * A core component is replaceable only if it hands out a token, and the token
+ * carries its props type. So an override that does not accept the props core
+ * passes is a compile error, and a key nothing declared cannot be overridden at
+ * all: there is no token to name it with.
+ */
+
+export interface Overridable<Props> {
+  readonly key: string
+  /** What renders when no module overrides it. Core's own component. */
+  readonly fallback: ComponentType<Props>
+}
+
+/**
+ * @param key Stable across releases. It is the name a module writes down.
+ */
+export function defineOverridable<Props>(
+  key: string,
+  fallback: ComponentType<Props>,
+): Overridable<Props> {
+  return { key, fallback }
+}
+
+export interface OverrideStore {
+  set<Props>(token: Overridable<Props>, component: ComponentType<Props>): void
+  /** @returns The override, or the token's own fallback when no module replaced it. */
+  get<Props>(token: Overridable<Props>): ComponentType<Props>
+  has(key: string): boolean
+}
+
+export function createOverrideStore(): OverrideStore {
+  // One map holding components with different props types, so the value type is
+  // the only one they share. `ComponentType<never>` looks like the tighter
+  // choice and is not: `ComponentClass.defaultProps` is covariant in Props, so
+  // nothing is assignable to it.
+  const byKey = new Map<string, unknown>()
+
+  return {
+    set<Props>(token: Overridable<Props>, component: ComponentType<Props>): void {
+      byKey.set(token.key, component)
+    },
+
+    get<Props>(token: Overridable<Props>): ComponentType<Props> {
+      const override = byKey.get(token.key)
+
+      if (override === undefined) {
+        return token.fallback
+      }
+
+      // Sound by construction: the only writer is `set`, which accepts nothing
+      // but a component for this token's own props.
+      return override as ComponentType<Props>
+    },
+
+    has: (key) => byKey.has(key),
+  }
+}