@kelpie/ui 0.1.0

package/src/pages/forms/SubmissionsTable.tsx

@@ -0,0 +1,171 @@
+import type { Form, FormSubmission } from '@kelpie/schemas'
+import { useMemo } from 'react'
+import { Link } from 'react-router'
+
+import type { RecordListResult } from '../../api/resource.ts'
+import { useCompanies } from '../../api/resources/companies.ts'
+import { usePeople } from '../../api/resources/people.ts'
+import { DataTable } from '../../components/DataTable.tsx'
+import type { Column } from '../../components/DataTable.tsx'
+import { ErrorPanel, LoadingPanel } from '../../components/QueryState.tsx'
+import { SectionHeader } from '../../components/SectionHeader.tsx'
+import { formatDateTime } from '../../lib/dates.ts'
+
+/**
+ * What has arrived through this form.
+ *
+ * Person and company names are joined client-side against one page each, the
+ * same way the Decisions page does it: `api.md` has no include-expansion, and
+ * neither list takes a set of bare ids. A record past those pages is still
+ * linked, by its type rather than its name, which beats a raw id.
+ */
+
+/** `api.md`: `?limit=` maxes out at 200. */
+const MAX_PAGE = 200
+
+export interface SubmissionsTableProps {
+  readonly form: Form
+  readonly submissions: RecordListResult<FormSubmission>
+}
+
+export function SubmissionsTable({ form, submissions }: SubmissionsTableProps): React.JSX.Element {
+  const people = usePeople({ limit: MAX_PAGE })
+  const companies = useCompanies({ limit: MAX_PAGE })
+
+  const nameById = useMemo(
+    () => new Map([...people.records, ...companies.records].map((record) => [record.id, record.name])),
+    [people.records, companies.records],
+  )
+
+  const columns: readonly Column<FormSubmission>[] = [
+    {
+      key: 'submitted',
+      header: 'Submitted',
+      className: 'w-40',
+      render: (submission) => (
+        <span className="font-mono text-[12px] text-ink-muted">
+          {formatDateTime(submission.submittedAt)}
+        </span>
+      ),
+    },
+    {
+      key: 'person',
+      header: 'Person',
+      render: (submission) => (
+        <RecordLink to="/people" id={submission.personId} name={nameById} fallback="Person" />
+      ),
+    },
+    {
+      key: 'company',
+      header: 'Company',
+      render: (submission) => (
+        <RecordLink to="/companies" id={submission.companyId} name={nameById} fallback="Company" />
+      ),
+    },
+    {
+      key: 'deal',
+      header: 'Deal',
+      className: 'w-24',
+      render: (submission) =>
+        submission.dealId === null ? (
+          <span className="text-ink-faint">—</span>
+        ) : (
+          <Link to={`/deals/${submission.dealId}`} className="text-accent hover:underline">
+            View
+          </Link>
+        ),
+    },
+    {
+      key: 'answers',
+      header: 'Answers',
+      render: (submission) => (
+        <span className="text-[12px] text-ink-muted">{summarise(form, submission)}</span>
+      ),
+    },
+  ]
+
+  if (submissions.error !== null) {
+    return <ErrorPanel error={submissions.error} />
+  }
+
+  if (submissions.isLoading) {
+    return <LoadingPanel label="Loading submissions…" />
+  }
+
+  return (
+    <div>
+      <SectionHeader
+        title="Submissions"
+        description="Inbound answers, and the records each one created or matched."
+      />
+      <DataTable
+        columns={columns}
+        rows={submissions.records}
+        getRowId={(submission) => submission.id}
+        emptyMessage="No submissions yet"
+      />
+      {submissions.hasMore && (
+        <button
+          type="button"
+          onClick={submissions.loadMore}
+          disabled={submissions.isLoadingMore}
+          className="mt-3 rounded-md border border-border px-3 py-1.5 text-[12px] font-medium text-ink transition hover:border-border-strong hover:bg-surface-sunken disabled:opacity-50"
+        >
+          {submissions.isLoadingMore ? 'Loading…' : 'Load more'}
+        </button>
+      )}
+    </div>
+  )
+}
+
+function RecordLink({
+  to,
+  id,
+  name,
+  fallback,
+}: {
+  readonly to: string
+  readonly id: string | null
+  readonly name: ReadonlyMap<string, string>
+  readonly fallback: string
+}): React.JSX.Element {
+  if (id === null) {
+    return <span className="text-ink-faint">—</span>
+  }
+
+  return (
+    <Link to={`${to}/${id}`} className="text-accent hover:underline">
+      {name.get(id) ?? fallback}
+    </Link>
+  )
+}
+
+/**
+ * The first two answers that are not already a column.
+ *
+ * Name and email are the Person link, so repeating them would spend the row's
+ * remaining width saying what it already said. A select shows its label rather
+ * than the key that was stored.
+ */
+function summarise(form: Form, submission: FormSubmission): string {
+  const parts = form.fields
+    .filter((field) => field.mapTo !== 'person.name' && field.mapTo !== 'person.email')
+    .map((field) => {
+      const answer = submission.answers[field.id]
+
+      if (answer === undefined || answer.trim().length === 0) {
+        return undefined
+      }
+
+      const shown =
+        field.type === 'select'
+          ? (field.options.find((option) => option.key === answer)?.value ?? answer)
+          : answer
+
+      return `${field.label}: ${shown}`
+    })
+    .filter((part): part is string => part !== undefined)
+    .slice(0, 2)
+
+  return parts.length === 0 ? '—' : parts.join(' · ')
+}

package/src/pages/forms/fieldList.ts

@@ -0,0 +1,209 @@
+import {
+  FORM_FIELD_MAP_TARGETS,
+  FORM_FIELD_TYPES,
+  PERSON_EMAIL_TARGET,
+} from '@kelpie/schemas'
+import type { Form, FormFieldInput, FormFieldMapTarget, FormFieldType } from '@kelpie/schemas'
+
+import { NEW_SELECT_OPTIONS } from './template.ts'
+
+/**
+ * Editing a form's field list, as pure functions over an array.
+ *
+ * A write replaces the whole list, so the builder holds one and hands it back;
+ * these are the transformations it applies. No React and no fetching here, which
+ * is what makes the rules that keep a list valid testable on their own.
+ *
+ * The rules mirror `findFieldProblems` on the server. That is not duplication
+ * for its own sake: the server is the authority and answers `422`, and these
+ * keep the builder from constructing a list it already knows will be refused.
+ */
+
+/** A field being edited, with the identity the list uses to address it. */
+export interface EditableField extends FormFieldInput {
+  /** The stored field id, or a local one for a field not yet saved. */
+  readonly id: string
+}
+
+export const FIELD_TYPE_OPTIONS = FORM_FIELD_TYPES.map((type) => ({ value: type, label: type }))
+
+export const MAP_TARGET_OPTIONS = FORM_FIELD_MAP_TARGETS.map((target) => ({
+  value: target,
+  label: target,
+}))
+
+/** Reads a saved form into the shape the builder edits. */
+export function toEditableFields(form: Form): EditableField[] {
+  return form.fields.map((field) => ({
+    id: field.id,
+    label: field.label,
+    type: field.type,
+    required: field.required,
+    mapTo: field.mapTo,
+    options: field.options.map((option) => ({ ...option })),
+    placeholder: field.placeholder,
+  }))
+}
+
+/** Strips the local ids back off. Ids are assigned server-side on every write. */
+export function toFieldInputs(fields: readonly EditableField[]): FormFieldInput[] {
+  return fields.map(({ id: _id, ...field }) => field)
+}
+
+/**
+ * Whether an edited list differs from what is saved.
+ *
+ * Mirrors the server's own comparison so the Save button can be honest about
+ * whether there is anything to save. Order counts: it is the order the embed
+ * renders.
+ */
+export function fieldsChanged(form: Form, fields: readonly EditableField[]): boolean {
+  return JSON.stringify(toFieldInputs(toEditableFields(form))) !== JSON.stringify(toFieldInputs(fields))
+}
+
+function withoutOptions(field: EditableField): EditableField {
+  const { options: _options, ...rest } = field
+
+  return { ...rest, options: [] }
+}
+
+/**
+ * Applies one edit to one field, keeping the field internally consistent.
+ *
+ * A select gets starter options the moment it becomes one, and loses them the
+ * moment it stops, because the server refuses both of the states in between. The
+ * mockup's builder does the same, for the same reason a reader would expect it:
+ * choosing "select" and being shown an empty dropdown is not a state anybody
+ * meant to create.
+ */
+export function editField(
+  fields: readonly EditableField[],
+  id: string,
+  change: Partial<FormFieldInput>,
+): EditableField[] {
+  return fields.map((field) => {
+    if (field.id !== id) {
+      // Only one field may carry a CRM target, so taking one releases it
+      // wherever it was. `submission` is the target that may repeat.
+      return change.mapTo !== undefined &&
+        change.mapTo !== 'submission' &&
+        field.mapTo === change.mapTo
+        ? { ...field, mapTo: 'submission' }
+        : field
+    }
+
+    const next: EditableField = { ...field, ...change }
+
+    if (next.type !== 'select') {
+      return withoutOptions(next)
+    }
+
+    return (next.options ?? []).length === 0 ? { ...next, options: NEW_SELECT_OPTIONS } : next
+  })
+}
+
+/** Inserts a field after `afterId`, or at the end when there is nothing to follow. */
+export function insertField(
+  fields: readonly EditableField[],
+  field: EditableField,
+  afterId: string | null,
+): EditableField[] {
+  const index = afterId === null ? -1 : fields.findIndex((existing) => existing.id === afterId)
+
+  if (index < 0) {
+    return [...fields, field]
+  }
+
+  return [...fields.slice(0, index + 1), field, ...fields.slice(index + 1)]
+}
+
+export function removeField(fields: readonly EditableField[], id: string): EditableField[] {
+  return fields.filter((field) => field.id !== id)
+}
+
+/** Moves the dragged field to where it was dropped. */
+export function reorderFields(
+  fields: readonly EditableField[],
+  activeId: string,
+  overId: string,
+): EditableField[] {
+  const from = fields.findIndex((field) => field.id === activeId)
+  const to = fields.findIndex((field) => field.id === overId)
+
+  if (from < 0 || to < 0 || from === to) {
+    return [...fields]
+  }
+
+  const next = [...fields]
+  const [moved] = next.splice(from, 1)
+
+  if (moved === undefined) {
+    return [...fields]
+  }
+
+  next.splice(to, 0, moved)
+
+  return next
+}
+
+/**
+ * What the server would refuse about this list, as messages beside the field
+ * they belong to.
+ *
+ * Keyed by field id rather than by index, because the builder renders rows and
+ * an index moves when something above it is dragged.
+ */
+export interface FieldListProblems {
+  /** Problems about the list as a whole, not about any one field. */
+  readonly list: readonly string[]
+  readonly byField: ReadonlyMap<string, string>
+}
+
+export function findProblems(
+  fields: readonly EditableField[],
+  createsDeal: boolean,
+): FieldListProblems {
+  const list: string[] = []
+  const byField = new Map<string, string>()
+  const seen = new Set<FormFieldMapTarget>()
+
+  if (!fields.some((field) => field.mapTo === PERSON_EMAIL_TARGET)) {
+    list.push(`One field must map to ${PERSON_EMAIL_TARGET}, or no submission can be processed.`)
+  }
+
+  if (createsDeal && !fields.some((field) => field.mapTo.startsWith('company.'))) {
+    list.push('A form that creates deals needs a company field for the deal to belong to.')
+  }
+
+  for (const field of fields) {
+    if (field.mapTo !== 'submission') {
+      if (seen.has(field.mapTo)) {
+        byField.set(field.id, `Another field already maps to ${field.mapTo}.`)
+      }
+
+      seen.add(field.mapTo)
+    }
+
+    if (field.type === 'select' && (field.options ?? []).length === 0) {
+      byField.set(field.id, 'A select needs at least one option.')
+    }
+
+    const keys = (field.options ?? []).map((option) => option.key)
+
+    if (new Set(keys).size !== keys.length) {
+      byField.set(field.id, 'Two options share a key.')
+    }
+  }
+
+  return { list, byField }
+}
+
+/** True when the list is one the API will accept. */
+export function isUsable(problems: FieldListProblems): boolean {
+  return problems.list.length === 0 && problems.byField.size === 0
+}
+
+/** The types a mapping can sensibly render as. Choosing `person.email` implies an email input. */
+export function typeForTarget(target: FormFieldMapTarget, current: FormFieldType): FormFieldType {
+  return target === PERSON_EMAIL_TARGET ? 'email' : current
+}

package/src/pages/forms/template.ts

@@ -0,0 +1,37 @@
+import type { FormFieldInput } from '@kelpie/schemas'
+
+/**
+ * What a new form starts as: the mockup's contact template.
+ *
+ * Not an empty list. A form with no `person.email` mapping is one the API
+ * refuses, so "create then edit" would mean creating something invalid; and a
+ * contact form is what almost everybody is about to build anyway.
+ */
+export const CONTACT_FORM_FIELDS: readonly FormFieldInput[] = [
+  { label: 'Name', type: 'text', required: true, mapTo: 'person.name', placeholder: 'Your name' },
+  {
+    label: 'Email',
+    type: 'email',
+    required: true,
+    mapTo: 'person.email',
+    placeholder: 'you@company.com',
+  },
+  { label: 'Company', type: 'text', mapTo: 'company.name', placeholder: 'Company name' },
+  { label: 'Job title', type: 'text', mapTo: 'position.title', placeholder: 'Your role' },
+  { label: 'Message', type: 'textarea', mapTo: 'submission', placeholder: 'How can we help?' },
+]
+
+/** A field added by hand: submission-only, so it cannot collide with a mapping already in use. */
+export const NEW_FIELD: FormFieldInput = {
+  label: 'New field',
+  type: 'text',
+  required: false,
+  mapTo: 'submission',
+  placeholder: null,
+}
+
+/** What a select starts with, so it is valid the moment the type is chosen. */
+export const NEW_SELECT_OPTIONS = [
+  { key: 'option_a', value: 'Option A', valueType: 'string' as const },
+  { key: 'option_b', value: 'Option B', valueType: 'string' as const },
+]