@kelpie/ui 0.7.0 → 0.8.0

package/src/components/DataTable.tsx

@@ -1,5 +1,8 @@
 import type { ReactNode } from 'react'
 
+import { sortRowsBy } from '../lib/sort.ts'
+import type { SortValue } from '../lib/sort.ts'
+
 export interface Column<TRow> {
   readonly key: string
   readonly header: string
@@ -7,6 +10,14 @@ export interface Column<TRow> {
   readonly render: (row: TRow) => ReactNode
   /** The `?sort=` field this column drives. Omit for a column with no server-side sort. */
   readonly sortKey?: string | undefined
+  /**
+   * Returns the value this column sorts by on the client. Set on any column
+   * whose resource cannot sort on it server-side (join columns, computed
+   * values, fields not in the resource's `_SORTS` map). When the active sort
+   * names a `Column.key` with this set, `DataTable` orders the loaded rows in
+   * place and does not forward the change to the server.
+   */
+  readonly getSortValue?: ((row: TRow) => SortValue) | undefined
 }
 
 export interface DataTableGroup<TRow> {
@@ -35,6 +46,12 @@ export interface DataTableProps<TRow> {
   readonly sort?: string | undefined
   /** Fires with the next `?sort=` value when a sortable header is clicked. Required for any column to be clickable. */
   readonly onSortChange?: ((sort: string | undefined) => void) | undefined
+  /**
+   * Restricts rendering to these column keys, in the order the header uses.
+   * Undefined shows every column. An unknown key is ignored rather than raising:
+   * a stored preference outliving a rename should hide only what it recognises.
+   */
+  readonly visibleColumnKeys?: readonly string[] | undefined
 }
 
 type SortDirection = 'asc' | 'desc'
@@ -62,6 +79,35 @@ function nextSort(sort: string | undefined, field: string): string | undefined {
   return current === 'asc' ? `-${field}` : undefined
 }
 
+/**
+ * The identifier a column contributes to the sort string. Server sorts use the
+ * `sortKey` — the field the server knows — so a stored sort keeps working when
+ * a column is renamed in the UI. Client-only sorts fall back to the display
+ * `key`, since there is no server field to reference.
+ */
+function sortFieldOf<TRow>(column: Column<TRow>): string | undefined {
+  if (column.sortKey !== undefined) {
+    return column.sortKey
+  }
+
+  return column.getSortValue !== undefined ? column.key : undefined
+}
+
+function findActiveClientColumn<TRow>(
+  columns: readonly Column<TRow>[],
+  sort: string | undefined,
+): Column<TRow> | undefined {
+  if (sort === undefined) {
+    return undefined
+  }
+
+  const bare = sort.startsWith('-') ? sort.slice(1) : sort
+
+  return columns.find(
+    (column) => column.getSortValue !== undefined && column.sortKey === undefined && column.key === bare,
+  )
+}
+
 export function DataTable<TRow>({
   columns,
   rows,
@@ -73,8 +119,34 @@ export function DataTable<TRow>({
   getRowId,
   sort,
   onSortChange,
+  visibleColumnKeys,
 }: DataTableProps<TRow>): React.JSX.Element {
   const flatRows = groups === undefined ? (rows ?? []) : groups.flatMap((group) => group.rows)
+  const displayedColumns =
+    visibleColumnKeys === undefined
+      ? columns
+      : columns.filter((column) => visibleColumnKeys.includes(column.key))
+
+  // Client sort is a page-local reorder: the server-returned page order stays
+  // the same, and only what is on screen shifts. Groups sort within each group,
+  // because the group is the primary key of the view — mixing rows across
+  // groups would break what the group header claims to count.
+  const clientSortColumn = findActiveClientColumn(displayedColumns, sort)
+  const clientDirection: SortDirection | undefined =
+    clientSortColumn === undefined
+      ? undefined
+      : directionOf(sort, clientSortColumn.key) ?? undefined
+  const displayedRows =
+    clientSortColumn === undefined || clientDirection === undefined || rows === undefined
+      ? rows
+      : sortRowsBy(rows, clientSortColumn.getSortValue!, clientDirection)
+  const displayedGroups =
+    clientSortColumn === undefined || clientDirection === undefined || groups === undefined
+      ? groups
+      : groups.map((group) => ({
+          ...group,
+          rows: sortRowsBy(group.rows, clientSortColumn.getSortValue!, clientDirection),
+        }))
 
   if (flatRows.length === 0) {
     return (
@@ -99,20 +171,21 @@ export function DataTable<TRow>({
       <table className="w-full border-collapse text-left text-[13px]">
         <thead>
           <tr className="border-b border-border">
-            {columns.map((column) => {
-              const direction = directionOf(sort, column.sortKey)
-              const sortable = column.sortKey !== undefined && onSortChange !== undefined
+            {displayedColumns.map((column) => {
+              const field = sortFieldOf(column)
+              const direction = directionOf(sort, field)
+              const sortable = field !== undefined && onSortChange !== undefined
 
               return (
                 <th
                   key={column.key}
                   className={`px-3 py-2 text-[11px] font-medium text-ink-faint ${column.className ?? ''}`}
                 >
-                  {sortable ? (
+                  {sortable && field !== undefined ? (
                     <button
                       type="button"
                       onClick={() => {
-                        onSortChange?.(nextSort(sort, column.sortKey ?? ''))
+                        onSortChange?.(nextSort(sort, field))
                       }}
                       className="inline-flex items-center gap-1 transition hover:text-ink"
                     >
@@ -130,26 +203,32 @@ export function DataTable<TRow>({
           </tr>
         </thead>
         <tbody>
-          {groups === undefined
-            ? (rows ?? []).map((row) => (
+          {displayedGroups === undefined
+            ? (displayedRows ?? []).map((row) => (
                 <DataRow
                   key={getRowId(row)}
                   row={row}
-                  columns={columns}
+                  columns={displayedColumns}
                   onRowClick={onRowClick}
                 />
               ))
-            : groups.map((group) => (
+            : displayedGroups.map((group) => (
                 <GroupRows
                   key={group.id}
                   group={group}
-                  columns={columns}
+                  columns={displayedColumns}
                   onRowClick={onRowClick}
                   getRowId={getRowId}
                 />
               ))}
         </tbody>
       </table>
+      {clientSortColumn !== undefined && (
+        <p className="border-t border-border bg-surface-sunken/40 px-3 py-1.5 text-[11px] text-ink-faint">
+          Sorted by {clientSortColumn.header.toLowerCase()} on this page. Other pages sort by their
+          own defaults.
+        </p>
+      )}
     </div>
   )
 }

package/src/components/DecisionsPanel.tsx

@@ -7,6 +7,7 @@ import { useTimezone } from '../api/resources/account.ts'
 import { useCreateDecision, useDecisions, useDeleteDecision } from '../api/resources/decisions.ts'
 import { useMembers } from '../api/resources/members.ts'
 import { formatDate } from '../lib/dates.ts'
+import { Paginator } from './Paginator.tsx'
 import { ErrorPanel } from './QueryState.tsx'
 import { SectionHeader } from './SectionHeader.tsx'
 
@@ -35,8 +36,8 @@ export function DecisionsPanel({ targetType, targetId }: DecisionsPanelProps): R
 
   // Due date first, decided date otherwise, newest down — the mockup's order.
   // The list arrives in `-decided_at` order and the API cannot sort on the
-  // nullable `due_at`, so this reorders what is loaded; across a "Load more"
-  // boundary the interleave can be wrong, which is the cheaper wrong than a
+  // nullable `due_at`, so this reorders what is on this page; across page
+  // boundaries the interleave can be wrong, which is the cheaper wrong than a
   // second request per panel.
   const ordered = [...decisions.records].sort(
     (left, right) =>
@@ -167,16 +168,7 @@ export function DecisionsPanel({ targetType, targetId }: DecisionsPanelProps): R
         )
       )}
 
-      {decisions.hasMore && (
-        <button
-          type="button"
-          onClick={decisions.loadMore}
-          disabled={decisions.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"
-        >
-          {decisions.isLoadingMore ? 'Loading…' : 'Load more'}
-        </button>
-      )}
+      <Paginator list={decisions} />
 
       <p className="mt-2 text-[11px] text-ink-faint">
         <Link to="/decisions" className="text-accent hover:underline">

package/src/components/EntitySearch.tsx

@@ -50,10 +50,16 @@ export function EntitySearch({
 }: EntitySearchProps): React.JSX.Element {
   const listId = useId()
   const rootRef = useRef<HTMLDivElement>(null)
-  const selected = options.find((option) => option.id === value)
   const [query, setQuery] = useState('')
   const [open, setOpen] = useState(false)
   const [highlight, setHighlight] = useState(0)
+  // A picked option must keep rendering even when the current `options` list
+  // no longer contains it — for a server-backed search, clearing the query on
+  // pick swaps the answer to a different page that may not include the pick.
+  const [remembered, setRemembered] = useState<SearchOption | null>(null)
+  const selected =
+    options.find((option) => option.id === value) ??
+    (remembered !== null && remembered.id === value ? remembered : undefined)
 
   const filtered = useMemo(() => {
     const term = query.trim().toLowerCase()
@@ -105,8 +111,9 @@ export function EntitySearch({
     onQueryChange?.(next)
   }
 
-  function pick(id: string): void {
-    onChange(id)
+  function pick(option: SearchOption): void {
+    setRemembered(option)
+    onChange(option.id)
     setOpen(false)
     search('')
   }
@@ -183,7 +190,7 @@ export function EntitySearch({
               const hit = filtered[highlight]
 
               if (hit !== undefined) {
-                pick(hit.id)
+                pick(hit)
               } else if (showCreate) {
                 create()
               }
@@ -219,7 +226,7 @@ export function EntitySearch({
                       setHighlight(index)
                     }}
                     onClick={() => {
-                      pick(option.id)
+                      pick(option)
                     }}
                     className={[
                       'flex w-full flex-col px-3 py-1.5 text-left',

package/src/components/ListsPanel.tsx

@@ -0,0 +1,176 @@
+import { RECORD_TARGET_TYPE_LABELS } from '@kelpie/schemas'
+import type { List, ListMembership, RecordTargetType } from '@kelpie/schemas'
+import { useState } from 'react'
+import { Link } from 'react-router'
+
+import {
+  useAddListMember,
+  useListMembershipsFor,
+  useRemoveListMember,
+} from '../api/resources/listMembers.ts'
+import { useLists } from '../api/resources/lists.ts'
+import { EntitySearch } from './EntitySearch.tsx'
+import type { SearchOption } from './EntitySearch.tsx'
+import { ErrorPanel, LoadingPanel } from './QueryState.tsx'
+import { SectionHeader } from './SectionHeader.tsx'
+
+/**
+ * "What lists is this record on?" panel, for any record's detail page.
+ *
+ * A record can only join a list whose `target_type` matches its own, so the
+ * picker is filtered accordingly. Removing a chip calls
+ * `DELETE /v1/lists/{id}/members/{memberId}` and the cached counts on the
+ * lists index refresh with it.
+ */
+export function ListsPanel({
+  targetType,
+  targetId,
+}: {
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+}): React.JSX.Element {
+  const memberships = useListMembershipsFor(targetType, targetId)
+  const [adding, setAdding] = useState(false)
+
+  return (
+    <section>
+      <SectionHeader
+        title="Lists"
+        onAdd={() => {
+          setAdding((current) => !current)
+        }}
+        addLabel="Add to list"
+      />
+
+      {adding && (
+        <div className="mb-3 flex gap-2">
+          <div className="min-w-0 flex-1">
+            <ListPicker
+              targetType={targetType}
+              targetId={targetId}
+              excludeListIds={new Set(memberships.memberships.map((row) => row.listId))}
+              onAdded={() => {
+                setAdding(false)
+              }}
+            />
+          </div>
+          <button
+            type="button"
+            onClick={() => {
+              setAdding(false)
+            }}
+            className="shrink-0 rounded-md px-2.5 py-1.5 text-[12px] font-medium text-ink-muted hover:text-ink"
+          >
+            Cancel
+          </button>
+        </div>
+      )}
+
+      {memberships.error !== null && <ErrorPanel error={memberships.error} />}
+
+      {memberships.isLoading ? (
+        <LoadingPanel label="Loading lists…" />
+      ) : memberships.memberships.length === 0 && !adding ? (
+        <p className="text-[13px] text-ink-faint">
+          Not on any lists yet. Add this {RECORD_TARGET_TYPE_LABELS[targetType].toLowerCase()} to
+          a list to group it with others.
+        </p>
+      ) : (
+        <ul className="overflow-hidden rounded-md border border-border">
+          {memberships.memberships.map((membership) => (
+            <MembershipRow key={membership.id} membership={membership} />
+          ))}
+        </ul>
+      )}
+    </section>
+  )
+}
+
+function MembershipRow({
+  membership,
+}: {
+  readonly membership: ListMembership
+}): React.JSX.Element {
+  const remove = useRemoveListMember()
+
+  return (
+    <li className="border-b border-border px-4 py-3 last:border-0">
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <Link
+          to={`/lists/${membership.listId}`}
+          className="text-left text-[13px] font-medium text-ink hover:text-accent"
+        >
+          {membership.listName}
+        </Link>
+        <button
+          type="button"
+          disabled={remove.isPending}
+          onClick={() => {
+            remove.run({ listId: membership.listId, id: membership.id })
+          }}
+          className="text-[11px] font-medium text-danger hover:underline disabled:opacity-50"
+        >
+          Remove
+        </button>
+      </div>
+
+      {remove.error !== null && (
+        <div className="mt-2">
+          <ErrorPanel error={remove.error} />
+        </div>
+      )}
+    </li>
+  )
+}
+
+function ListPicker({
+  targetType,
+  targetId,
+  excludeListIds,
+  onAdded,
+}: {
+  readonly targetType: RecordTargetType
+  readonly targetId: string
+  readonly excludeListIds: ReadonlySet<string>
+  readonly onAdded: () => void
+}): React.JSX.Element {
+  const [search, setSearch] = useState('')
+  const term = search.trim()
+  // Only lists whose type matches — the DB will refuse a mismatched member,
+  // but the picker filters up front so the surface never offers one.
+  const lists = useLists({
+    targetType,
+    term: term.length > 0 ? term : undefined,
+  })
+  const addMember = useAddListMember()
+
+  const options: readonly SearchOption[] = lists.records
+    .filter((row: List) => !excludeListIds.has(row.id))
+    .map((row: List) => ({ id: row.id, label: row.name }))
+
+  function pick(listId: string): void {
+    addMember
+      .runAsync({ listId, input: { targetType, targetId } })
+      .then(onAdded)
+      .catch(() => undefined)
+  }
+
+  return (
+    <div>
+      <EntitySearch
+        options={options}
+        value=""
+        onChange={pick}
+        onQueryChange={setSearch}
+        placeholder="Search lists…"
+        emptyMessage="No matching lists"
+        size="md"
+      />
+      {addMember.error !== null && (
+        <div className="mt-2">
+          <ErrorPanel error={addMember.error} />
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/NotesPanel.tsx

@@ -6,6 +6,7 @@ import { useTimezone } from '../api/resources/account.ts'
 import { useMembers } from '../api/resources/members.ts'
 import { useCreateNote, useNotes } from '../api/resources/notes.ts'
 import { formatDateTime } from '../lib/dates.ts'
+import { Paginator } from './Paginator.tsx'
 import { ErrorPanel } from './QueryState.tsx'
 import { SectionHeader } from './SectionHeader.tsx'
 
@@ -33,10 +34,10 @@ export function NotesPanel({ targetType, targetId }: NotesPanelProps): React.JSX
   const [body, setBody] = useState('')
 
   // Pinned first, then newest. The list arrives in `-created_at` order and the
-  // API has no two-column sort, so this reorders what is loaded. Across a
-  // "Load more" boundary a pinned note on a later page sorts after unpinned
-  // ones already shown; pinned notes are few enough that this is the cheaper
-  // wrong than a second request per panel.
+  // API has no two-column sort, so this reorders what is on this page. Across
+  // page boundaries a pinned note on a later page sorts after unpinned ones on
+  // an earlier one; pinned notes are few enough that this is the cheaper wrong
+  // than a second request per panel.
   const ordered = [...notes.records].sort((left, right) => Number(right.pinned) - Number(left.pinned))
 
   function reset(): void {
@@ -116,16 +117,7 @@ export function NotesPanel({ targetType, targetId }: NotesPanelProps): React.JSX
         </ul>
       )}
 
-      {notes.hasMore && (
-        <button
-          type="button"
-          onClick={notes.loadMore}
-          disabled={notes.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"
-        >
-          {notes.isLoadingMore ? 'Loading…' : 'Load more'}
-        </button>
-      )}
+      <Paginator list={notes} />
     </section>
   )
 }

package/src/components/Paginator.tsx

@@ -0,0 +1,78 @@
+import type { Paged } from '../api/resource.ts'
+
+/**
+ * Prev / Next with a page indicator and an optional page size selector.
+ *
+ * The API is cursor-only (`api.md`), so there is no total count and no jump
+ * to page N. `pageIndex` is one-based on screen but zero-based in `Paged` —
+ * the label adds one so page 1 does not read as page 0.
+ *
+ * `Prev` disables when nothing came before, `Next` when the server said the
+ * current page was the last one. A cached prior page is instant; going past
+ * the fetched set kicks off exactly one fetch, and both buttons hold their
+ * disabled state until it settles so a fast double click does not skip two.
+ */
+
+export interface PaginatorProps {
+  readonly list: Paged
+  /** Options offered by the page size selector. Omit to hide the selector. */
+  readonly pageSizes?: readonly number[]
+  /**
+   * Where on the list this paginator sits. `top` places it above the rows —
+   * the per-page selector then defers to the `bottom` copy so the two do not
+   * duplicate the same control side by side.
+   */
+  readonly placement?: 'top' | 'bottom'
+}
+
+const DEFAULT_PAGE_SIZES: readonly number[] = [25, 50, 100, 200]
+
+const buttonClass =
+  'rounded-md border border-border bg-surface-raised px-2.5 py-1 text-[12px] font-medium text-ink transition hover:border-border-strong hover:bg-surface-sunken disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:border-border disabled:hover:bg-surface-raised'
+
+export function Paginator({
+  list,
+  pageSizes = DEFAULT_PAGE_SIZES,
+  placement = 'bottom',
+}: PaginatorProps): React.JSX.Element {
+  const prevDisabled = !list.hasPrev || list.isChangingPage
+  const nextDisabled = !list.hasNext || list.isChangingPage
+  const options = pageSizes.includes(list.pageSize) ? pageSizes : [...pageSizes, list.pageSize].sort((a, b) => a - b)
+  const showPageSize = placement === 'bottom' && pageSizes.length > 0
+  const wrapperClass =
+    placement === 'top'
+      ? 'mt-3 mb-3 flex flex-wrap items-center gap-3 text-[12px] text-ink-muted'
+      : 'mt-3 flex flex-wrap items-center gap-3 text-[12px] text-ink-muted'
+
+  return (
+    <div className={wrapperClass}>
+      <div className="flex items-center gap-1">
+        <button type="button" onClick={list.prevPage} disabled={prevDisabled} className={buttonClass}>
+          Prev
+        </button>
+        <button type="button" onClick={list.nextPage} disabled={nextDisabled} className={buttonClass}>
+          {list.isChangingPage ? 'Loading…' : 'Next'}
+        </button>
+      </div>
+      <span aria-live="polite">Page {list.pageIndex + 1}</span>
+      {showPageSize && (
+        <label className="ml-auto flex items-center gap-2">
+          <span>Per page</span>
+          <select
+            value={list.pageSize}
+            onChange={(event) => {
+              list.setPageSize(Number(event.target.value))
+            }}
+            className="rounded-md border border-border bg-surface-raised px-2 py-1 text-[12px] outline-none focus:border-accent"
+          >
+            {options.map((size) => (
+              <option key={size} value={size}>
+                {size}
+              </option>
+            ))}
+          </select>
+        </label>
+      )}
+    </div>
+  )
+}

package/src/components/PlanPanel.tsx

@@ -13,6 +13,7 @@ import {
 import { formatDay } from '../lib/dates.ts'
 import { planStatusTone } from '../lib/plan.ts'
 import { Chip } from './Chip.tsx'
+import { Paginator } from './Paginator.tsx'
 import { ErrorPanel } from './QueryState.tsx'
 import { SectionHeader } from './SectionHeader.tsx'
 
@@ -102,16 +103,7 @@ export function PlanPanel({ targetType, targetId }: PlanPanelProps): React.JSX.E
         </ul>
       )}
 
-      {items.hasMore && (
-        <button
-          type="button"
-          onClick={items.loadMore}
-          disabled={items.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"
-        >
-          {items.isLoadingMore ? 'Loading…' : 'Load more'}
-        </button>
-      )}
+      <Paginator list={items} />
     </section>
   )
 }

package/src/components/Shell.tsx

@@ -38,6 +38,7 @@ const CORE_NAV: readonly NavItem[] = [
   { id: 'opportunities', label: 'Opportunities', to: '/opportunities', order: 350 },
   { id: 'fundraising', label: 'Fundraising', to: '/fundraising', order: 360 },
   { id: 'partnerships', label: 'Partnerships', to: '/partnerships', order: 375 },
+  { id: 'lists', label: 'Lists', to: '/lists', order: 378 },
   { id: 'forms', label: 'Forms', to: '/forms', order: 380 },
   { id: 'handbook', label: 'Handbook', to: '/handbook', order: 390 },
   { id: 'planning', label: 'Planning', to: '/planning', order: 400 },

package/src/index.ts

@@ -13,10 +13,12 @@ export type { ApiProviderProps } from './api/ApiProvider.tsx'
 export { useApiClient } from './api/context.ts'
 export { toError } from './api/errors.ts'
 export { createQueryClient } from './api/queryClient.ts'
-export { createResourceHooks } from './api/resource.ts'
+export { createResourceHooks, DEFAULT_PAGE_SIZE, usePagedList } from './api/resource.ts'
 export type {
   ListOptions,
   MutationResult,
+  Paged,
+  PagedListInput,
   RecordListResult,
   RecordResult,
   ResourceDefinition,
@@ -88,6 +90,8 @@ export { AgentTasks } from './components/AgentTasks.tsx'
 export type { AgentTasksProps } from './components/AgentTasks.tsx'
 export { Chip } from './components/Chip.tsx'
 export type { ChipProps, ChipTone } from './components/Chip.tsx'
+export { ColumnPicker } from './components/ColumnPicker.tsx'
+export type { ColumnPickerOption, ColumnPickerProps } from './components/ColumnPicker.tsx'
 export { DataTable } from './components/DataTable.tsx'
 export type { Column, DataTableGroup, DataTableProps } from './components/DataTable.tsx'
 export { DecisionsPanel } from './components/DecisionsPanel.tsx'
@@ -100,6 +104,8 @@ export { InlineEdit } from './components/InlineEdit.tsx'
 export type { InlineEditProps } from './components/InlineEdit.tsx'
 export { FilterBar, PageHeader } from './components/PageHeader.tsx'
 export type { FilterBarProps, PageHeaderProps } from './components/PageHeader.tsx'
+export { Paginator } from './components/Paginator.tsx'
+export type { PaginatorProps } from './components/Paginator.tsx'
 export { PhonesField } from './components/PhonesField.tsx'
 export type { PhonesFieldProps } from './components/PhonesField.tsx'
 export { PlanAttention, RelatedPlanAttention } from './components/PlanAttention.tsx'
@@ -151,6 +157,9 @@ export {
 } from './lib/plan.ts'
 export type { DueBucketId, PlanAttention as PlanAttentionSummary } from './lib/plan.ts'
 
+export { useListView } from './lib/listView.ts'
+export type { ListViewController } from './lib/listView.ts'
+
 export { applyTheme, getStoredTheme, resolveTheme, setStoredTheme, watchSystemTheme } from './lib/theme.ts'
 export type { ThemePreference } from './lib/theme.ts'