@startsimpli/ui 0.4.104 → 0.4.106

package/src/foundry/LinkPanel.tsx

@@ -0,0 +1,394 @@
+'use client';
+
+/**
+ * THE LINKING UI — one component, both directions.
+ *
+ * "These records are associated with that one" is the interaction a generic
+ * record form cannot express: an association is a `core_relationship` row, not a
+ * field on `Entity.data`, so no arrangement of text inputs writes one. What this
+ * adds over a read-only "Related" list is the two verbs that make it a product:
+ * LINK and UNLINK.
+ *
+ * ONE PANEL, PARAMETERISED BY A LinkSide (see ./links), so the reverse direction
+ * cannot drift from the forward one — it is not a second implementation, it is
+ * the same one with `role` flipped.
+ *
+ * READS ARE SERVER-FILTERED, both of them:
+ *   - `?entity=&rel_type=`                            the edges (carry the id UNLINK deletes)
+ *   - `?related_to=&related_via=&related_direction=`   the far records (carry the names)
+ * Two bounded calls, joined by id. Neither grows with the size of the org.
+ *
+ * THE TENANT API IS INJECTED, not imported. Every tenant app owns its own
+ * `foundry-api.ts` bound to its own configured client; a shared component that
+ * imported one would only work in the app it was lifted from. The `api` prop is
+ * the six calls this panel makes and nothing else.
+ *
+ * Lifted out of a tenant fork (bd startsim-768w.63); originally bd startsim-16d5.
+ */
+import { useMemo, useState } from 'react';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { Plus, X, Search, Link2 } from 'lucide-react';
+
+import { Button } from '../components/ui/button';
+import { Input } from '../components/ui/input';
+import { notify } from '../components/toast/use-notify';
+import { useNow } from '../hooks/use-now';
+import {
+  edgeEndpoints,
+  edgesForSide,
+  farDirection,
+  farIdOf,
+  joinLinkRows,
+  linkCandidates,
+  recordLabel,
+  type LinkSide,
+} from './links';
+import {
+  readRecordValue,
+  type AttributeShape,
+  type EntityId,
+  type EntityRecordShape,
+  type EntityTypeShape,
+  type RelationshipEdgeShape,
+  type SchemaId,
+} from './types';
+
+/** One page of a DRF list response, as much of one as this panel reads. */
+export interface LinkPanelPage<T> {
+  results: T[];
+  next?: string | null;
+}
+
+/**
+ * The tenant calls this panel makes. Six, and none of them mentions a client
+ * type — an app supplies its own `foundry-api.ts` functions here.
+ */
+export interface LinkPanelApi {
+  /** Every declared type, for the far type's label. */
+  listTypes(): Promise<LinkPanelPage<EntityTypeShape>>;
+  /** Every edge on this record with one of these rel types. */
+  listEdgesFor(recordId: EntityId, relTypes: string[]): Promise<RelationshipEdgeShape[]>;
+  /** One page of the records on the far end of a side. */
+  listRelated(args: {
+    type: string;
+    relatedTo: EntityId;
+    via: string;
+    direction: 'in' | 'out';
+    page: number;
+  }): Promise<LinkPanelPage<EntityRecordShape>>;
+  /** A server-side `?search=` over one type, for the picker. */
+  searchRecords(typeKey: string, search: string): Promise<LinkPanelPage<EntityRecordShape>>;
+  createEdge(input: { relType: string; source: EntityId; target: EntityId }): Promise<unknown>;
+  deleteEdge(edgeId: SchemaId): Promise<unknown>;
+}
+
+/** The queryKey both halves of a side share, so one mutation invalidates both. */
+export function linkQueryKey(recordId: EntityId, side: LinkSide) {
+  return ['links', String(recordId), side.relType, side.role] as const;
+}
+
+/** The date attribute a far record's supporting line reads. First declared one,
+ *  unless the caller knows better. */
+function firstDateAttribute(type: EntityTypeShape | undefined | null): AttributeShape | null {
+  return (type?.attributes ?? []).find((a) => a.dataType === 'date') ?? null;
+}
+
+/** Every far record for a side, across pages (capped) — a list of associations
+ *  must not stop at page one. */
+async function listAllRelated(
+  api: LinkPanelApi,
+  side: LinkSide,
+  recordId: EntityId,
+  maxPages = 10,
+): Promise<EntityRecordShape[]> {
+  const all: EntityRecordShape[] = [];
+  for (let page = 1; page <= maxPages; page++) {
+    const res = await api.listRelated({
+      type: side.farTypeKey,
+      relatedTo: recordId,
+      via: side.relType,
+      direction: farDirection(side),
+      page,
+    });
+    all.push(...res.results);
+    if (!res.next) break;
+  }
+  return all;
+}
+
+/**
+ * A far record's supporting line. Deliberately SCHEMA-DRIVEN: `external_id` is
+ * the natural key for a tenant type, and the date comes from whatever `date`
+ * attribute the far type declares.
+ *
+ * A PAST DATE IS SHOWN, NOT HIDDEN. Suppressing the row would quietly make a
+ * record's association list disagree with its own links, and whether a date has
+ * passed is a different question from whether the association still holds.
+ */
+function FarRecordMeta({
+  record,
+  farType,
+  dateAttributeFor,
+}: {
+  record: EntityRecordShape;
+  farType?: EntityTypeShape;
+  dateAttributeFor?: (type: EntityTypeShape) => AttributeShape | null;
+}) {
+  const now = useNow();
+
+  const dateAttr = farType
+    ? (dateAttributeFor ?? firstDateAttribute)(farType)
+    : null;
+  const raw = dateAttr ? readRecordValue(record.data, dateAttr.name) : null;
+  const iso = raw == null ? '' : String(raw);
+  const parsed = iso ? new Date(iso) : null;
+  const valid = parsed && !Number.isNaN(parsed.getTime());
+  const expired = valid && now > 0 ? parsed.getTime() < now : false;
+
+  if (!record.externalId && !valid) return null;
+  return (
+    <span className="flex flex-wrap items-center gap-2 text-xs text-neutral-500">
+      {record.externalId ? (
+        <span className="rounded bg-neutral-100 px-1.5 py-0.5 font-mono text-[11px] text-neutral-600">
+          {record.externalId}
+        </span>
+      ) : null}
+      {valid ? (
+        <span className={expired ? 'font-medium text-red-600' : ''}>
+          {dateAttr?.name.replace(/_/g, ' ')} {parsed!.toLocaleDateString()}
+          {expired ? ' — expired' : ''}
+        </span>
+      ) : null}
+    </span>
+  );
+}
+
+export interface LinkPanelProps {
+  /** The record whose links these are. */
+  record: EntityRecordShape;
+  side: LinkSide;
+  /** The tenant calls. See LinkPanelApi. */
+  api: LinkPanelApi;
+  /** Heading override; defaults to the far type's label. */
+  title?: string;
+  /** One line saying what this association MEANS, shown under the heading. */
+  description?: string;
+  /** Shown when nothing is linked. The default deliberately does not read as a
+   *  statement that nothing exists. */
+  emptyMessage?: string;
+  /** Which attribute the supporting line dates a far record by. Defaults to the
+   *  first `date` attribute the far type declares. */
+  dateAttributeFor?: (type: EntityTypeShape) => AttributeShape | null;
+}
+
+export function LinkPanel({
+  record,
+  side,
+  api,
+  title,
+  description,
+  emptyMessage = 'Nothing linked yet. An empty list is not a statement that none exists.',
+  dateAttributeFor,
+}: LinkPanelProps) {
+  const qc = useQueryClient();
+  const [picking, setPicking] = useState(false);
+  const [search, setSearch] = useState('');
+  const [busy, setBusy] = useState(false);
+
+  const typesQuery = useQuery({ queryKey: ['schema-types'], queryFn: () => api.listTypes() });
+  const farType = typesQuery.data?.results.find((t) => t.key === side.farTypeKey);
+
+  const edgesQuery = useQuery({
+    queryKey: [...linkQueryKey(record.id, side), 'edges'],
+    queryFn: () => api.listEdgesFor(record.id, [side.relType]),
+  });
+  const farQuery = useQuery({
+    queryKey: [...linkQueryKey(record.id, side), 'far'],
+    queryFn: () => listAllRelated(api, side, record.id),
+  });
+
+  const rows = useMemo(() => {
+    const edges = edgesForSide(edgesQuery.data ?? [], side, record.id);
+    return joinLinkRows(edges, side, farQuery.data ?? []);
+  }, [edgesQuery.data, farQuery.data, side, record.id]);
+
+  const linkedIds = useMemo(() => rows.map((r) => farIdOf(r.edge, side)), [rows, side]);
+
+  // The picker's pool: a SERVER-side ?search= over the far type, so a corpus of
+  // thousands never lands in the browser to be filtered here.
+  const poolQuery = useQuery({
+    queryKey: ['link-candidates', side.farTypeKey, search],
+    queryFn: () => api.searchRecords(side.farTypeKey, search),
+    enabled: picking,
+  });
+  const candidates = useMemo(
+    () => linkCandidates(poolQuery.data?.results ?? [], linkedIds, record.id),
+    [poolQuery.data, linkedIds, record.id],
+  );
+
+  async function refresh() {
+    await qc.invalidateQueries({ queryKey: linkQueryKey(record.id, side) });
+    // The other end's panel and any table count are now stale too.
+    await qc.invalidateQueries({ queryKey: ['links'] });
+    await qc.invalidateQueries({ queryKey: ['link-counts'] });
+  }
+
+  async function link(far: EntityRecordShape) {
+    setBusy(true);
+    try {
+      // The DECLARED direction, not the user's viewpoint — see ./links.
+      await api.createEdge(edgeEndpoints(side, record.id, far.id));
+      await refresh();
+      notify.success(`Linked ${recordLabel(far)}.`);
+    } catch (err) {
+      notify.error(err instanceof Error ? err.message : 'Could not create the link.');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function unlink(edgeId: SchemaId, label: string) {
+    setBusy(true);
+    try {
+      await api.deleteEdge(edgeId);
+      await refresh();
+      notify.success(`Unlinked ${label}.`);
+    } catch (err) {
+      notify.error(err instanceof Error ? err.message : 'Could not remove the link.');
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const loading = edgesQuery.isLoading || farQuery.isLoading;
+  const heading = title ?? farType?.label ?? side.farTypeKey;
+
+  return (
+    <section className="rounded-lg border">
+      <header className="flex items-start justify-between gap-3 border-b px-4 py-3">
+        <div className="min-w-0">
+          <h3 className="flex items-center gap-2 text-sm font-semibold text-neutral-900">
+            <Link2 className="h-4 w-4 text-neutral-400" aria-hidden />
+            {heading}
+            <span className="rounded-full bg-neutral-100 px-2 py-0.5 text-xs font-normal text-neutral-600">
+              {loading ? '…' : rows.length}
+            </span>
+          </h3>
+          {description ? <p className="mt-0.5 text-xs text-neutral-500">{description}</p> : null}
+        </div>
+        <Button
+          size="sm"
+          variant={picking ? 'outline' : 'default'}
+          onClick={() => {
+            setPicking((p) => !p);
+            setSearch('');
+          }}
+        >
+          {picking ? (
+            'Done'
+          ) : (
+            <>
+              <Plus className="mr-1 h-3.5 w-3.5" aria-hidden /> Add
+            </>
+          )}
+        </Button>
+      </header>
+
+      {picking ? (
+        <div className="border-b bg-neutral-50 px-4 py-3">
+          <div className="relative">
+            <Search
+              className="pointer-events-none absolute left-2.5 top-1/2 h-3.5 w-3.5 -translate-y-1/2 text-neutral-400"
+              aria-hidden
+            />
+            <Input
+              autoFocus
+              value={search}
+              onChange={(e) => setSearch(e.target.value)}
+              placeholder={`Search ${heading.toLowerCase()}…`}
+              className="pl-8"
+              aria-label={`Search ${heading}`}
+            />
+          </div>
+          <ul className="mt-2 max-h-56 space-y-1 overflow-y-auto">
+            {poolQuery.isLoading ? (
+              <li className="px-1 py-2 text-sm text-neutral-500">Searching…</li>
+            ) : candidates.length === 0 ? (
+              <li className="px-1 py-2 text-sm text-neutral-500">
+                {(poolQuery.data?.results ?? []).length === 0
+                  ? `No ${heading.toLowerCase()} match.`
+                  : `Every match is already linked.`}
+              </li>
+            ) : (
+              candidates.map((c) => (
+                <li key={String(c.id)}>
+                  <button
+                    type="button"
+                    disabled={busy}
+                    onClick={() => link(c)}
+                    className="flex w-full items-center justify-between gap-3 rounded border bg-white px-3 py-2 text-left text-sm hover:bg-neutral-50 disabled:opacity-50"
+                  >
+                    <span className="min-w-0">
+                      <span className="block truncate">{recordLabel(c)}</span>
+                      <FarRecordMeta
+                        record={c}
+                        farType={farType}
+                        dateAttributeFor={dateAttributeFor}
+                      />
+                    </span>
+                    <Plus className="h-4 w-4 shrink-0 text-neutral-400" aria-hidden />
+                  </button>
+                </li>
+              ))
+            )}
+          </ul>
+        </div>
+      ) : null}
+
+      <div className="px-4 py-3">
+        {loading ? (
+          <p className="text-sm text-neutral-500">Loading…</p>
+        ) : rows.length === 0 ? (
+          <p className="text-sm text-neutral-500">{emptyMessage}</p>
+        ) : (
+          <ul className="space-y-1.5">
+            {rows.map(({ edge, record: far }) => {
+              const label = recordLabel(far, farIdOf(edge, side));
+              return (
+                <li
+                  key={String(edge.id)}
+                  className="flex items-center justify-between gap-3 rounded border px-3 py-2 text-sm"
+                >
+                  <span className="min-w-0">
+                    <span className="block truncate">{label}</span>
+                    {far ? (
+                      <FarRecordMeta
+                        record={far}
+                        farType={farType}
+                        dateAttributeFor={dateAttributeFor}
+                      />
+                    ) : (
+                      <span className="text-xs text-neutral-400">
+                        linked, but not readable by you
+                      </span>
+                    )}
+                  </span>
+                  <button
+                    type="button"
+                    disabled={busy}
+                    onClick={() => unlink(edge.id, label)}
+                    aria-label={`Unlink ${label}`}
+                    title={`Unlink ${label}`}
+                    className="shrink-0 rounded p-1 text-neutral-400 hover:bg-red-50 hover:text-red-600 disabled:opacity-50"
+                  >
+                    <X className="h-4 w-4" aria-hidden />
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+        )}
+      </div>
+    </section>
+  );
+}

package/src/foundry/__tests__/LinkPanel.test.tsx

@@ -0,0 +1,139 @@
+/**
+ * The panel's whole reason to be shared is that the REVERSE direction is the
+ * same code as the forward one. So the test drives both ends of one declared
+ * relationship against one fake tenant and asserts the edge it writes.
+ */
+import { render, screen, waitFor, fireEvent } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { LinkPanel, type LinkPanelApi } from '../LinkPanel'
+import { linkSidesFor, type LinkSide } from '../links'
+import type { EntityRecordShape, EntityTypeShape, RelationshipEdgeShape } from '../types'
+
+const PRODUCT: EntityTypeShape = { id: 't1', key: 'product', label: 'Products', attributes: [] }
+const PATENT: EntityTypeShape = {
+  id: 't2',
+  key: 'patent',
+  label: 'Patents',
+  attributes: [{ name: 'expiration', dataType: 'date' }],
+}
+
+const sides = linkSidesFor(PRODUCT, [{ key: 'marked_with', sourceType: 't1', targetType: 't2' }], [
+  PRODUCT,
+  PATENT,
+])
+const forward = sides[0] as LinkSide
+const reverse = linkSidesFor(PATENT, [{ key: 'marked_with', sourceType: 't1', targetType: 't2' }], [
+  PRODUCT,
+  PATENT,
+])[0] as LinkSide
+
+function fakeApi(overrides: Partial<LinkPanelApi> = {}): LinkPanelApi & { created: unknown[]; deleted: unknown[] } {
+  const created: unknown[] = []
+  const deleted: unknown[] = []
+  return {
+    created,
+    deleted,
+    listTypes: async () => ({ results: [PRODUCT, PATENT] }),
+    listEdgesFor: async () => [] as RelationshipEdgeShape[],
+    listRelated: async () => ({ results: [] as EntityRecordShape[], next: null }),
+    searchRecords: async () => ({ results: [] as EntityRecordShape[] }),
+    createEdge: async (input) => { created.push(input) },
+    deleteEdge: async (id) => { deleted.push(id) },
+    ...overrides,
+  }
+}
+
+function renderPanel(side: LinkSide, api: LinkPanelApi, record: EntityRecordShape) {
+  const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } })
+  return render(
+    <QueryClientProvider client={qc}>
+      <LinkPanel record={record} side={side} api={api} />
+    </QueryClientProvider>
+  )
+}
+
+describe('LinkPanel', () => {
+  it('heads the panel with the FAR type and lists the far records', async () => {
+    const api = fakeApi({
+      listEdgesFor: async () => [
+        { id: 'E1', relType: 'marked_with', source: 'P1', target: 'X1' },
+      ],
+      listRelated: async () => ({
+        results: [{ id: 'X1', name: 'A patent', externalId: 'US123', data: {} }],
+        next: null,
+      }),
+    })
+    renderPanel(forward, api, { id: 'P1', name: 'A product', data: {} })
+
+    expect(await screen.findByText('Patents')).toBeInTheDocument()
+    expect(await screen.findByText('A patent')).toBeInTheDocument()
+    expect(screen.getByText('US123')).toBeInTheDocument()
+  })
+
+  it('writes the DECLARED direction from the forward side', async () => {
+    const api = fakeApi({
+      searchRecords: async () => ({ results: [{ id: 'X1', name: 'A patent', data: {} }] }),
+    })
+    renderPanel(forward, api, { id: 'P1', name: 'A product', data: {} })
+
+    fireEvent.click(await screen.findByRole('button', { name: /add/i }))
+    fireEvent.click(await screen.findByText('A patent'))
+
+    await waitFor(() => expect(api.created).toHaveLength(1))
+    expect(api.created[0]).toEqual({ relType: 'marked_with', source: 'P1', target: 'X1' })
+  })
+
+  it('writes the SAME direction from the reverse side — the one nobody demos', async () => {
+    const api = fakeApi({
+      searchRecords: async () => ({ results: [{ id: 'P1', name: 'A product', data: {} }] }),
+    })
+    renderPanel(reverse, api, { id: 'X1', name: 'A patent', data: {} })
+
+    expect(await screen.findByText('Products')).toBeInTheDocument()
+    fireEvent.click(await screen.findByRole('button', { name: /add/i }))
+    fireEvent.click(await screen.findByText('A product'))
+
+    await waitFor(() => expect(api.created).toHaveLength(1))
+    // Not (thisRecord, thatRecord) — the def is product -> patent either way.
+    expect(api.created[0]).toEqual({ relType: 'marked_with', source: 'P1', target: 'X1' })
+  })
+
+  it('unlinks by the EDGE id, which only the edge read carries', async () => {
+    const api = fakeApi({
+      listEdgesFor: async () => [
+        { id: 'E1', relType: 'marked_with', source: 'P1', target: 'X1' },
+      ],
+      listRelated: async () => ({ results: [{ id: 'X1', name: 'A patent', data: {} }], next: null }),
+    })
+    renderPanel(forward, api, { id: 'P1', name: 'A product', data: {} })
+
+    fireEvent.click(await screen.findByRole('button', { name: 'Unlink A patent' }))
+    await waitFor(() => expect(api.deleted).toEqual(['E1']))
+  })
+
+  it('renders an edge whose far end this caller cannot read, rather than dropping it', async () => {
+    const api = fakeApi({
+      listEdgesFor: async () => [
+        { id: 'E1', relType: 'marked_with', source: 'P1', target: 'X-hidden' },
+      ],
+      listRelated: async () => ({ results: [], next: null }),
+    })
+    renderPanel(forward, api, { id: 'P1', name: 'A product', data: {} })
+
+    expect(await screen.findByText('linked, but not readable by you')).toBeInTheDocument()
+  })
+
+  it('never offers an already-linked record in the picker', async () => {
+    const api = fakeApi({
+      listEdgesFor: async () => [
+        { id: 'E1', relType: 'marked_with', source: 'P1', target: 'X1' },
+      ],
+      listRelated: async () => ({ results: [{ id: 'X1', name: 'A patent', data: {} }], next: null }),
+      searchRecords: async () => ({ results: [{ id: 'X1', name: 'A patent', data: {} }] }),
+    })
+    renderPanel(forward, api, { id: 'P1', name: 'A product', data: {} })
+
+    fireEvent.click(await screen.findByRole('button', { name: /add/i }))
+    expect(await screen.findByText('Every match is already linked.')).toBeInTheDocument()
+  })
+})