@kelpie/ui 0.6.0 → 0.8.0

package/src/api/resources/listMembers.ts

@@ -0,0 +1,173 @@
+import {
+  addListMemberBody,
+  listMemberSchema,
+  listMembershipSchema,
+} from '@kelpie/schemas'
+import type {
+  AddListMemberInput,
+  ListMember,
+  ListMembership,
+  RecordTargetType,
+} from '@kelpie/schemas'
+import {
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from '@tanstack/react-query'
+import type { InfiniteData } from '@tanstack/react-query'
+
+import type { Page } from '../client.ts'
+import { useApiClient } from '../context.ts'
+import { toError } from '../errors.ts'
+import { usePagedList } from '../resource.ts'
+import type { MutationResult, RecordListResult } from '../resource.ts'
+
+/**
+ * `/v1/lists/:id/members`. Nested per list, so the standard resource hook cannot
+ * mint the path. Built by hand with the same read/write cache invalidation
+ * pattern the other resources use.
+ */
+
+type MembersData = InfiniteData<Page<ListMember>, string | null>
+
+function membersKey(listId: string): readonly unknown[] {
+  return ['lists', 'members', listId]
+}
+
+function membershipsKey(targetType: string, targetId: string): readonly unknown[] {
+  return ['lists', 'memberships', targetType, targetId]
+}
+
+/** The list-level entries whose cached counts change when a member is added or removed. */
+function listsInvalidations(): readonly unknown[] {
+  return ['lists', 'list']
+}
+
+export interface ListMembershipsResult {
+  readonly memberships: readonly ListMembership[]
+  readonly isLoading: boolean
+  readonly error: Error | null
+}
+
+/**
+ * "Which lists is this record on?"
+ *
+ * A plain `useQuery` rather than the paged read: the endpoint is not paged.
+ * The invalidation key overlaps with `useListMembers` so adding or removing on
+ * either side refreshes both views.
+ */
+export function useListMembershipsFor(
+  targetType: RecordTargetType | undefined,
+  targetId: string | undefined,
+): ListMembershipsResult {
+  const client = useApiClient()
+  const enabled = targetType !== undefined && targetId !== undefined
+  const result = useQuery({
+    queryKey: membershipsKey(targetType ?? '', targetId ?? ''),
+    queryFn: async () => {
+      const page = await client.list(
+        '/list-memberships',
+        listMembershipSchema.parse,
+        { target_type: targetType, target_id: targetId },
+      )
+
+      return page.items
+    },
+    enabled,
+  })
+
+  return {
+    memberships: result.data ?? [],
+    isLoading: result.isPending && enabled,
+    error: toError(result.error),
+  }
+}
+
+export function useListMembers(listId: string | undefined): RecordListResult<ListMember> {
+  return usePagedList<ListMember>({
+    queryKey: membersKey(listId ?? ''),
+    path: `/lists/${listId ?? ''}/members`,
+    decode: listMemberSchema.parse,
+    query: {},
+    enabled: listId !== undefined,
+  })
+}
+
+export interface AddMemberArguments {
+  readonly listId: string
+  readonly input: AddListMemberInput
+}
+
+export function useAddListMember(): MutationResult<AddMemberArguments, ListMember> {
+  const client = useApiClient()
+  const queryClient = useQueryClient()
+  const mutation = useMutation({
+    mutationFn: ({ listId, input }: AddMemberArguments) =>
+      client.post(`/lists/${listId}/members`, addListMemberBody(input), listMemberSchema.parse),
+    onSettled: (_record, _error, { listId }) => {
+      void queryClient.invalidateQueries({ queryKey: membersKey(listId) })
+      void queryClient.invalidateQueries({ queryKey: listsInvalidations() })
+      void queryClient.invalidateQueries({ queryKey: ['lists', 'memberships'] })
+    },
+  })
+
+  return {
+    run: (input) => {
+      mutation.mutate(input)
+    },
+    runAsync: (input) => mutation.mutateAsync(input),
+    isPending: mutation.isPending,
+    error: toError(mutation.error),
+  }
+}
+
+export interface RemoveMemberArguments {
+  readonly listId: string
+  readonly id: string
+}
+
+export function useRemoveListMember(): MutationResult<RemoveMemberArguments, void> {
+  const client = useApiClient()
+  const queryClient = useQueryClient()
+  const mutation = useMutation({
+    mutationFn: ({ listId, id }: RemoveMemberArguments) =>
+      client.delete(`/lists/${listId}/members/${id}`),
+    onMutate: async ({ listId, id }) => {
+      await queryClient.cancelQueries({ queryKey: membersKey(listId) })
+      const previous = queryClient.getQueryData<MembersData>(membersKey(listId))
+
+      queryClient.setQueryData<MembersData>(membersKey(listId), (data) =>
+        data === undefined
+          ? data
+          : {
+              ...data,
+              pages: data.pages.map((page) => ({
+                ...page,
+                items: page.items.filter((item) => item.id !== id),
+              })),
+            },
+      )
+
+      return { previous }
+    },
+    onError: (_error, { listId }, context) => {
+      if (context?.previous !== undefined) {
+        queryClient.setQueryData(membersKey(listId), context.previous)
+      }
+    },
+    onSettled: (_record, _error, { listId }) => {
+      void queryClient.invalidateQueries({ queryKey: membersKey(listId) })
+      void queryClient.invalidateQueries({ queryKey: listsInvalidations() })
+      void queryClient.invalidateQueries({ queryKey: ['lists', 'memberships'] })
+    },
+  })
+
+  return {
+    run: (input) => {
+      mutation.mutate(input)
+    },
+    runAsync: (input) => mutation.mutateAsync(input),
+    isPending: mutation.isPending,
+    error: toError(mutation.error),
+  }
+}

package/src/api/resources/lists.ts

@@ -0,0 +1,61 @@
+import { createListBody, listBody, listSchema } from '@kelpie/schemas'
+import type { CreateListInput, List, ListInput, RecordTargetType } from '@kelpie/schemas'
+
+import type { QueryParameters } from '../client.ts'
+import { createResourceHooks } from '../resource.ts'
+import type {
+  ListOptions,
+  MutationResult,
+  RecordListResult,
+  RecordResult,
+  UpdateArguments,
+} from '../resource.ts'
+
+/** `/v1/lists`. A list holds records of one type; the type is fixed at creation. */
+
+const lists = createResourceHooks<List, CreateListInput, ListInput>({
+  name: 'lists',
+  path: '/lists',
+  decode: listSchema.parse,
+  createBody: createListBody,
+  updateBody: listBody,
+})
+
+export interface ListFilters {
+  readonly term?: string | undefined
+  readonly targetType?: RecordTargetType | undefined
+  readonly limit?: number | undefined
+  readonly sort?: string | undefined
+}
+
+function listsQuery(filters: ListFilters): QueryParameters {
+  return {
+    q: filters.term,
+    target_type: filters.targetType,
+    limit: filters.limit,
+    sort: filters.sort,
+  }
+}
+
+export function useLists(
+  filters: ListFilters = {},
+  options: ListOptions = {},
+): RecordListResult<List> {
+  return lists.useList(listsQuery(filters), options)
+}
+
+export function useList(id: string | undefined): RecordResult<List> {
+  return lists.useRecord(id)
+}
+
+export function useCreateList(): MutationResult<CreateListInput, List> {
+  return lists.useCreate()
+}
+
+export function useUpdateList(): MutationResult<UpdateArguments<ListInput>, List> {
+  return lists.useUpdate()
+}
+
+export function useDeleteList(): MutationResult<string, void> {
+  return lists.useRemove()
+}

package/src/api/resources/people.ts

@@ -25,7 +25,10 @@ const people = createResourceHooks<Person, CreatePersonInput, PersonInput>({
   updateBody: personBody,
   // Every write here emits an activity server-side, in the same transaction, so
   // a timeline rendered on this record is stale the moment the write lands.
-  alsoInvalidates: ['activities'],
+  // Setting or changing the email may also auto-link a Position, which changes
+  // both the person's position list and the `?person_id=` companies list that
+  // names the far side — without the latter, the new row renders as "Unknown".
+  alsoInvalidates: ['activities', 'positions', 'companies'],
 })
 
 /** The documented filters on `GET /v1/people`. There is no generic filter DSL. */

package/src/api/resources/publicConfig.ts

@@ -0,0 +1,33 @@
+import { publicConfigSchema } from '@kelpie/schemas'
+import type { PublicConfig } from '@kelpie/schemas'
+import { useQuery } from '@tanstack/react-query'
+
+import { useApiClient } from '../context.ts'
+import { toError } from '../errors.ts'
+
+/**
+ * The deployment metadata `GET /v1/public/config` reports.
+ *
+ * Read once, cached forever: neither `runtimeMode` nor `siteName` changes
+ * while the app is open. The endpoint is public, so this hook works before a
+ * session exists (the sign-in page reads it too).
+ */
+
+const PUBLIC_CONFIG_KEY = ['public-config'] as const
+
+export interface PublicConfigState {
+  readonly config: PublicConfig | undefined
+  readonly isLoading: boolean
+  readonly error: Error | null
+}
+
+export function usePublicConfig(): PublicConfigState {
+  const client = useApiClient()
+  const result = useQuery({
+    queryKey: PUBLIC_CONFIG_KEY,
+    queryFn: () => client.get('/public/config', publicConfigSchema.parse),
+    staleTime: Infinity,
+  })
+
+  return { config: result.data, isLoading: result.isPending, error: toError(result.error) }
+}

package/src/api/resources/roles.ts

@@ -35,10 +35,12 @@ export interface RoleFilters {
   /** Roles in any of these statuses. Repeats on the wire. */
   readonly statuses?: readonly RoleStatus[] | undefined
   readonly limit?: number | undefined
+  /** `field` ascending, `-field` descending. Only `title`, `created_at`, `updated_at` are sortable. */
+  readonly sort?: string | undefined
 }
 
 function roleQuery(filters: RoleFilters): QueryParameters {
-  return { q: filters.term, status: filters.statuses, limit: filters.limit }
+  return { q: filters.term, status: filters.statuses, limit: filters.limit, sort: filters.sort }
 }
 
 export function useRoles(

package/src/api/resources/sampleData.ts

@@ -0,0 +1,56 @@
+import { sampleDataCountsSchema } from '@kelpie/schemas'
+import type { SampleDataCounts } from '@kelpie/schemas'
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+
+import { useApiClient } from '../context.ts'
+import type { MutationResult } from '../resource.ts'
+import { asMutationResult } from './mutation.ts'
+
+/**
+ * `POST /v1/workspaces/:id/sample-data`: install the sample workspace.
+ *
+ * The workspace id arrives as a mutation argument rather than being read from
+ * the session. That lets the onboarding wizard install into the workspace it
+ * just created, before the session cache catches up with it.
+ *
+ * On success, every CRM list is invalidated because the rows this just wrote
+ * are in all of them.
+ */
+
+export interface InstallSampleDataInput {
+  readonly workspaceId: string
+}
+
+export function useInstallSampleData(): MutationResult<InstallSampleDataInput, SampleDataCounts> {
+  const client = useApiClient()
+  const cache = useQueryClient()
+  const mutation = useMutation({
+    mutationFn: ({ workspaceId }: InstallSampleDataInput) =>
+      client.post(
+        `/workspaces/${workspaceId}/sample-data`,
+        {},
+        sampleDataCountsSchema.parse,
+      ),
+    onSuccess: async () => {
+      await Promise.all(
+        [
+          'people',
+          'companies',
+          'positions',
+          'deals',
+          'plans',
+          'notes',
+          'activities',
+          'decisions',
+          'opportunities',
+          'raises',
+          'partnerships',
+          'roles',
+          'candidates',
+        ].map((name) => cache.invalidateQueries({ queryKey: [name] })),
+      )
+    },
+  })
+
+  return asMutationResult(mutation)
+}

package/src/api/resources/webhooks.ts

@@ -14,12 +14,11 @@ import type {
   WebhookDelivery,
   WebhookInput,
 } from '@kelpie/schemas'
-import { keepPreviousData, useInfiniteQuery, useMutation, useQueryClient } from '@tanstack/react-query'
+import { useMutation, useQueryClient } from '@tanstack/react-query'
 
 import type { QueryParameters } from '../client.ts'
 import { useApiClient } from '../context.ts'
-import { toError } from '../errors.ts'
-import { createResourceHooks } from '../resource.ts'
+import { createResourceHooks, usePagedList } from '../resource.ts'
 import type { MutationResult, RecordListResult, UpdateArguments } from '../resource.ts'
 import { asMutationResult } from './mutation.ts'
 
@@ -79,29 +78,14 @@ export function useWebhookDeliveries(
   webhookId: string,
   filters: WebhookDeliveryFilters = {},
 ): RecordListResult<WebhookDelivery> {
-  const client = useApiClient()
-  const result = useInfiniteQuery({
+  const query: QueryParameters = { status: filters.status }
+
+  return usePagedList<WebhookDelivery>({
     queryKey: ['webhooks', 'deliveries', webhookId, filters.status ?? 'all'],
-    queryFn: ({ pageParam }) =>
-      client.list(`/webhooks/${webhookId}/deliveries`, webhookDeliverySchema.parse, {
-        status: filters.status,
-        ...(pageParam === null ? {} : { cursor: pageParam }),
-      }),
-    initialPageParam: null as string | null,
-    getNextPageParam: (lastPage) => lastPage.nextCursor,
-    placeholderData: keepPreviousData,
+    path: `/webhooks/${webhookId}/deliveries`,
+    decode: webhookDeliverySchema.parse,
+    query,
   })
-
-  return {
-    records: result.data?.pages.flatMap((page) => page.items) ?? [],
-    isLoading: result.isPending,
-    error: toError(result.error),
-    hasMore: result.hasNextPage,
-    isLoadingMore: result.isFetchingNextPage,
-    loadMore: () => {
-      void result.fetchNextPage()
-    },
-  }
 }
 
 /**

package/src/app/KelpieApp.tsx

@@ -1,6 +1,7 @@
 import { BrowserRouter, Navigate, Route, Routes } from 'react-router'
 
 import { ApiProvider } from '../api/ApiProvider.tsx'
+import { EnvironmentBanner } from '../components/EnvironmentBanner.tsx'
 import { Shell } from '../components/Shell.tsx'
 import { CompaniesPage } from '../pages/CompaniesPage.tsx'
 import { CompanyDetail } from '../pages/CompanyDetail.tsx'
@@ -13,6 +14,8 @@ import { FormDetail } from '../pages/FormDetail.tsx'
 import { FormsPage } from '../pages/FormsPage.tsx'
 import { FundraisingPage } from '../pages/FundraisingPage.tsx'
 import { HiringPage } from '../pages/HiringPage.tsx'
+import { ListDetail } from '../pages/ListDetail.tsx'
+import { ListsPage } from '../pages/ListsPage.tsx'
 import { NotFoundPage } from '../pages/NotFoundPage.tsx'
 import { OpportunitiesPage } from '../pages/OpportunitiesPage.tsx'
 import { OpportunityDetail } from '../pages/OpportunityDetail.tsx'
@@ -78,6 +81,12 @@ export function KelpieApp({ extensions, baseUrl }: KelpieAppProps): React.JSX.El
     <ApiProvider baseUrl={baseUrl}>
       <UiExtensionProvider extensions={extensions}>
         <BrowserRouter>
+          {/* Above the router so the strip renders on the sign-in page as
+              well as the main app. Nothing forces a height here: on
+              production the banner returns null, and the Shell (or the sign-
+              in layout) fills the viewport as it did before. On non-
+              production the 20px strip stacks above them. */}
+          <EnvironmentBanner />
           <AppRoutes />
         </BrowserRouter>
       </UiExtensionProvider>
@@ -152,6 +161,8 @@ function AppRoutes(): React.JSX.Element {
           <Route path="partnerships" element={<PartnershipsPage />} />
           <Route path="partnerships/settings" element={<PartnershipStageSettingsPage />} />
           <Route path="partnerships/:id" element={<PartnershipDetail />} />
+          <Route path="lists" element={<ListsPage />} />
+          <Route path="lists/:id" element={<ListDetail />} />
           <Route path="planning" element={<PlanningPage />} />
           <Route path="decisions" element={<DecisionsPage />} />
           <Route path="forms" element={<FormsPage />} />

package/src/components/ActivitiesPanel.tsx

@@ -4,6 +4,7 @@ import { useTimezone } from '../api/resources/account.ts'
 import { useActivities } from '../api/resources/activities.ts'
 import { useMembers } from '../api/resources/members.ts'
 import { formatRelativeTime, monthLabel } from '../lib/dates.ts'
+import { Paginator } from './Paginator.tsx'
 import { ErrorPanel } from './QueryState.tsx'
 import { SectionHeader } from './SectionHeader.tsx'
 
@@ -118,16 +119,7 @@ export function ActivitiesPanel({
         ))}
       </div>
 
-      {activities.hasMore && (
-        <button
-          type="button"
-          onClick={activities.loadMore}
-          disabled={activities.isLoadingMore}
-          className="mt-3 rounded-md border border-border px-3 py-1.5 text-[12px] font-medium text-ink-muted transition hover:border-border-strong hover:text-ink"
-        >
-          {activities.isLoadingMore ? 'Loading…' : 'Load more'}
-        </button>
-      )}
+      <Paginator list={activities} />
     </section>
   )
 }

package/src/components/ColumnPicker.tsx

@@ -0,0 +1,124 @@
+import { useEffect, useRef, useState } from 'react'
+
+/**
+ * A "Columns" button that opens a popover of checkboxes for the columns a list
+ * page can show.
+ *
+ * The picker owns nothing but the popover: the selection lives with the caller
+ * (usually `useListView`) so the checked state cannot fall out of step with the
+ * table beside it. `options` is the full set the page supports, in the display
+ * order the header uses.
+ *
+ * The first column is pinned. A list with no columns at all is not a preference
+ * anyone would make on purpose, and the primary column is what makes each row
+ * identifiable — losing it turns every row into a set of anonymous fields.
+ */
+export interface ColumnPickerOption {
+  readonly key: string
+  readonly label: string
+}
+
+export interface ColumnPickerProps {
+  readonly options: readonly ColumnPickerOption[]
+  readonly visibleKeys: readonly string[]
+  readonly onChange: (keys: readonly string[]) => void
+}
+
+export function ColumnPicker({ options, visibleKeys, onChange }: ColumnPickerProps): React.JSX.Element {
+  const [open, setOpen] = useState(false)
+  const containerRef = useRef<HTMLDivElement>(null)
+  const pinnedKey = options[0]?.key
+
+  useEffect(() => {
+    if (!open) {
+      return
+    }
+
+    function onPointerDown(event: MouseEvent): void {
+      if (containerRef.current?.contains(event.target as Node) !== true) {
+        setOpen(false)
+      }
+    }
+
+    function onKeyDown(event: KeyboardEvent): void {
+      if (event.key === 'Escape') {
+        setOpen(false)
+      }
+    }
+
+    document.addEventListener('mousedown', onPointerDown)
+    document.addEventListener('keydown', onKeyDown)
+
+    return () => {
+      document.removeEventListener('mousedown', onPointerDown)
+      document.removeEventListener('keydown', onKeyDown)
+    }
+  }, [open])
+
+  function toggle(key: string, checked: boolean): void {
+    if (key === pinnedKey) {
+      return
+    }
+
+    // Preserve the order the caller passed in: the stored value is the visible
+    // set, and re-adding a column should put it back where the table draws it,
+    // not append it wherever the click landed.
+    const next = options.map((option) => option.key).filter((candidate) => {
+      if (candidate === key) {
+        return checked
+      }
+
+      return visibleKeys.includes(candidate)
+    })
+
+    onChange(next)
+  }
+
+  return (
+    <div className="relative" ref={containerRef}>
+      <button
+        type="button"
+        onClick={() => {
+          setOpen((current) => !current)
+        }}
+        aria-expanded={open}
+        aria-haspopup="menu"
+        className="rounded-md border border-border bg-surface-raised px-3 py-1.5 text-[12px] font-medium text-ink transition hover:border-border-strong hover:bg-surface-sunken"
+      >
+        Columns
+      </button>
+      {open && (
+        <div
+          role="menu"
+          className="absolute right-0 z-20 mt-1.5 max-h-80 w-56 overflow-y-auto rounded-md border border-border bg-surface-raised py-1"
+        >
+          {options.map((option) => {
+            const checked = visibleKeys.includes(option.key)
+            const pinned = option.key === pinnedKey
+
+            return (
+              <label
+                key={option.key}
+                className={[
+                  'flex items-center gap-2 px-3 py-1.5 text-[13px] text-ink',
+                  pinned ? 'cursor-default text-ink-muted' : 'cursor-pointer hover:bg-surface-sunken',
+                ].join(' ')}
+              >
+                <input
+                  type="checkbox"
+                  checked={checked}
+                  disabled={pinned}
+                  onChange={(event) => {
+                    toggle(option.key, event.target.checked)
+                  }}
+                  className="h-3.5 w-3.5"
+                />
+                <span>{option.label}</span>
+              </label>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}