@startsimpli/integrations 0.1.4 → 0.1.5

package/src/components/pages/LibraryPage.tsx

@@ -0,0 +1,612 @@
+/**
+ * The Library — the corpus surface, as ONE composer (bd startsim-768w.38.6).
+ *
+ * `<LibraryPage api={corpus} scope={scope} />` is the whole integration. An app
+ * owns theme classNames and a wrapper of ten lines, the same shape as
+ * `ConnectionsPage` and for the same reason: shipping primitives and letting
+ * each app assemble the page just relocates the duplication one level up
+ * (feedback_share_page_composers_not_just_primitives).
+ *
+ * WHAT IT RENDERS, in the order the question is actually asked:
+ *
+ *   1. FRESHNESS per source — when did each one last pull, and did it work. This
+ *      is on the screen, not in a settings page, because a corpus silently four
+ *      days stale is what makes an AI answer confidently wrong.
+ *   2. FILTERS — search, source, party, date window. Every one of them is a
+ *      SERVER parameter (CLAUDE.md rule 8); nothing is filtered in the browser.
+ *   3. The LIST, every row wearing its source as a visible badge.
+ *   4. The DETAIL, with participants as Party links and whatever long-form the
+ *      source attached, under the source's own name for it.
+ *
+ * NOTHING HERE NAMES A VENDOR. The standing test for every element below is
+ * "would this row, badge, filter or empty state still make sense if the only
+ * connected source were Dropbox?" — so the source list comes from the freshness
+ * data, the badge renders whatever label the catalog gave it, and long-form text
+ * is a labelled `section` rather than a transcript. A screen that only works for
+ * meeting notes is a failed design even though it would demo fine.
+ */
+import * as React from 'react';
+
+import { enforceScope } from '../../corpus/retrieval';
+import type {
+  CorpusApi,
+  CorpusScope,
+  DocumentQuery,
+  Party,
+  SourceDocument,
+  SourceFreshness,
+} from '../../corpus/types';
+
+export interface LibraryPageProps {
+  api: CorpusApi;
+  /** The asking principal's tenant scope. Rows outside it are never rendered. */
+  scope: CorpusScope;
+  /** Open straight onto one record — how a citation from the Ask surface lands. */
+  initialDocumentId?: string;
+  /** Told whenever the open record changes, so an app can put it in the URL. */
+  onSelectDocument?: (documentId: string | null) => void;
+  pageSize?: number;
+  classNames?: Partial<Record<LibrarySlot, string>>;
+}
+
+type LibrarySlot =
+  | 'root'
+  | 'section'
+  | 'heading'
+  | 'card'
+  | 'row'
+  | 'badge'
+  | 'button'
+  | 'input'
+  | 'muted'
+  | 'error'
+  | 'warning';
+
+const DEFAULTS: Record<LibrarySlot, string> = {
+  root: 'space-y-6',
+  section: 'space-y-3',
+  heading: 'text-lg font-semibold text-gray-900',
+  card: 'rounded-lg border border-gray-200 p-4',
+  row: 'w-full rounded-lg border border-gray-200 p-4 text-left hover:border-gray-400',
+  badge: 'inline-flex items-center rounded-full border border-gray-300 px-2 py-0.5 text-xs text-gray-700',
+  button: 'rounded-md bg-gray-900 px-3 py-1.5 text-sm font-medium text-white disabled:opacity-50',
+  input: 'rounded-md border border-gray-300 px-3 py-1.5 text-sm',
+  muted: 'text-sm text-gray-500',
+  error: 'text-sm text-red-600',
+  warning: 'rounded-md border border-amber-300 bg-amber-50 p-2 text-sm text-amber-800',
+};
+
+/** A refusal must read as a refusal, not as an empty corpus. */
+function readFailureMessage(err: unknown): string {
+  const status = (err as { status?: number })?.status;
+  if (status === 403) return 'You do not have access to this workspace’s records.';
+  if (status === 401) return 'Your session has expired. Sign in again.';
+  return (err as { message?: string })?.message || 'Could not load the library.';
+}
+
+function formatDate(value: string | null | undefined): string {
+  if (!value) return 'No date';
+  const at = Date.parse(value);
+  if (Number.isNaN(at)) return 'No date';
+  return new Date(at).toLocaleDateString(undefined, {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  });
+}
+
+function relative(value: string | null | undefined, now: number): string {
+  if (!value) return 'never';
+  const at = Date.parse(value);
+  if (Number.isNaN(at)) return 'never';
+  const minutes = Math.round((now - at) / 60000);
+  if (minutes < 1) return 'just now';
+  if (minutes < 60) return `${minutes} min ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) return `${hours}h ago`;
+  return `${Math.round(hours / 24)}d ago`;
+}
+
+function preview(document: SourceDocument, length = 180): string {
+  const text = document.body || document.sections[0]?.text || '';
+  if (!text) return '';
+  return text.length > length ? `${text.slice(0, length).trim()}…` : text;
+}
+
+// ---------------------------------------------------------------------------
+
+export function LibraryPage({
+  api,
+  scope,
+  initialDocumentId,
+  onSelectDocument,
+  pageSize = 20,
+  classNames = {},
+}: LibraryPageProps) {
+  const cn = { ...DEFAULTS, ...classNames };
+
+  const [filters, setFilters] = React.useState<DocumentQuery>({ page: 1, pageSize });
+  const [draftSearch, setDraftSearch] = React.useState('');
+  const [documents, setDocuments] = React.useState<SourceDocument[]>([]);
+  const [count, setCount] = React.useState(0);
+  const [applied, setApplied] = React.useState<string[] | undefined>(undefined);
+  const [sources, setSources] = React.useState<SourceFreshness[]>([]);
+  const [parties, setParties] = React.useState<Party[]>([]);
+  const [selectedId, setSelectedId] = React.useState<string | null>(initialDocumentId ?? null);
+  const [selected, setSelected] = React.useState<SourceDocument | null>(null);
+  const [loading, setLoading] = React.useState(true);
+  const [loadError, setLoadError] = React.useState('');
+  /**
+   * LATCHED, not per-page. "The data API returned another workspace's rows" is a
+   * fact about the API, and paging forward past the offending page must not make
+   * the warning disappear as though it were fixed.
+   */
+  const [droppedOutOfScope, setDroppedOutOfScope] = React.useState(0);
+
+  // The reference-only surfaces (which sources exist, which parties exist) load
+  // once. They are what makes the filter controls DATA rather than a hardcoded
+  // vendor list — add a connector and its option appears with no code change.
+  React.useEffect(() => {
+    let live = true;
+    void (async () => {
+      const [freshness, partyPage] = await Promise.all([
+        api.listSources().catch(() => [] as SourceFreshness[]),
+        api.listParties({ page: 1, pageSize: 100 }).catch(() => ({
+          count: 0, next: null, previous: null, results: [] as Party[],
+        })),
+      ]);
+      if (!live) return;
+      setSources(freshness);
+      setParties(partyPage.results ?? []);
+    })();
+    return () => { live = false; };
+  }, [api]);
+
+  React.useEffect(() => {
+    let live = true;
+    setLoading(true);
+    void (async () => {
+      try {
+        const page = await api.listDocuments(filters);
+        if (!live) return;
+        // THE GUARD RUNS ON THE LIST, not only on the detail panel. A row from
+        // another workspace is a leak the moment it is drawn — its title and its
+        // preview text are already on the screen, and nobody has to click. The
+        // API scopes reads and RLS scopes them again; this is the third check,
+        // and a non-zero drop is stated rather than absorbed.
+        const { kept, dropped } = enforceScope(page.results ?? [], scope);
+        setDocuments(kept);
+        setDroppedOutOfScope((seen) => seen + dropped.length);
+        setCount(Math.max(0, (page.count ?? 0) - dropped.length));
+        setApplied(page.appliedFilters);
+        setLoadError('');
+      } catch (err) {
+        if (live) setLoadError(readFailureMessage(err));
+      } finally {
+        if (live) setLoading(false);
+      }
+    })();
+    return () => { live = false; };
+  }, [api, filters, scope]);
+
+  React.useEffect(() => {
+    if (!selectedId) { setSelected(null); return; }
+    let live = true;
+    void (async () => {
+      // Prefer the row already on screen; fall back to a fetch so a citation
+      // deep-link opens a record that is not on the current page.
+      const onPage = documents.find((document) => document.id === selectedId);
+      if (onPage) { setSelected(onPage); return; }
+      try {
+        const fetched = await api.getDocument(selectedId);
+        if (live) setSelected(fetched);
+      } catch {
+        if (live) setSelected(null);
+      }
+    })();
+    return () => { live = false; };
+  }, [api, selectedId, documents]);
+
+  const select = React.useCallback((id: string | null) => {
+    setSelectedId(id);
+    onSelectDocument?.(id);
+  }, [onSelectDocument]);
+
+  const update = React.useCallback((patch: Partial<DocumentQuery>) => {
+    // Any filter change resets to page 1 — page 3 of the old result set is not
+    // page 3 of the new one, and silently keeping it shows an empty list.
+    setFilters((prev) => ({ ...prev, ...patch, page: patch.page ?? 1 }));
+  }, []);
+
+  const page = filters.page ?? 1;
+  const size = filters.pageSize ?? pageSize;
+  const lastPage = Math.max(1, Math.ceil(count / size));
+  const now = Date.now();
+
+  /**
+   * A filter the SERVER did not apply. Rendering the unfiltered list under a
+   * filled-in search box is a lie the user cannot catch, so it is stated.
+   */
+  const ignored = React.useMemo(() => {
+    if (!applied) return [] as string[];
+    const requested: Array<[string, unknown]> = [
+      ['search', filters.search],
+      ['source', filters.source],
+      ['party', filters.partyId],
+      ['date', filters.occurredAfter || filters.occurredBefore],
+    ];
+    const keyFor: Record<string, string[]> = {
+      search: ['search'], source: ['source'], party: ['partyId'],
+      date: ['occurredAfter', 'occurredBefore'],
+    };
+    return requested
+      .filter(([name, value]) => value && !keyFor[name].some((key) => applied.includes(key)))
+      .map(([name]) => name);
+  }, [applied, filters]);
+
+  if (loadError) {
+    return <p className={cn.error} role="alert">{loadError}</p>;
+  }
+
+  return (
+    <div className={cn.root}>
+      <FreshnessStrip sources={sources} classNames={cn} now={now} />
+
+      <section className={cn.section}>
+        <form
+          className="flex flex-wrap items-end gap-2"
+          onSubmit={(event) => { event.preventDefault(); update({ search: draftSearch || undefined }); }}
+        >
+          <label className="flex flex-col gap-1">
+            <span className="text-xs font-medium text-gray-700">Search</span>
+            <input
+              className={cn.input}
+              type="search"
+              value={draftSearch}
+              placeholder="Search everything pulled in"
+              onChange={(event) => setDraftSearch(event.target.value)}
+            />
+          </label>
+
+          <label className="flex flex-col gap-1">
+            <span className="text-xs font-medium text-gray-700">Source</span>
+            <select
+              className={cn.input}
+              value={filters.source ?? ''}
+              onChange={(event) => update({ source: event.target.value || undefined })}
+            >
+              <option value="">All sources</option>
+              {/* Options are DATA. A fourth connector appears here by existing. */}
+              {sources.map((source) => (
+                <option key={source.source} value={source.source}>{source.label}</option>
+              ))}
+            </select>
+          </label>
+
+          <label className="flex flex-col gap-1">
+            <span className="text-xs font-medium text-gray-700">Party</span>
+            <select
+              className={cn.input}
+              value={filters.partyId ?? ''}
+              onChange={(event) => update({ partyId: event.target.value || undefined })}
+            >
+              <option value="">Anyone</option>
+              {parties.map((party) => (
+                <option key={party.id} value={party.id}>{party.name}</option>
+              ))}
+            </select>
+          </label>
+
+          <label className="flex flex-col gap-1">
+            <span className="text-xs font-medium text-gray-700">From</span>
+            <input
+              className={cn.input}
+              type="date"
+              value={(filters.occurredAfter ?? '').slice(0, 10)}
+              onChange={(event) => update({
+                occurredAfter: event.target.value ? `${event.target.value}T00:00:00Z` : undefined,
+              })}
+            />
+          </label>
+
+          <label className="flex flex-col gap-1">
+            <span className="text-xs font-medium text-gray-700">To</span>
+            <input
+              className={cn.input}
+              type="date"
+              value={(filters.occurredBefore ?? '').slice(0, 10)}
+              onChange={(event) => update({
+                occurredBefore: event.target.value ? `${event.target.value}T23:59:59Z` : undefined,
+              })}
+            />
+          </label>
+
+          <button type="submit" className={cn.button}>Search</button>
+          <button
+            type="button"
+            className={cn.button}
+            onClick={() => { setDraftSearch(''); setFilters({ page: 1, pageSize: size }); }}
+          >
+            Clear
+          </button>
+        </form>
+
+        {ignored.length ? (
+          <p className={cn.warning} role="status">
+            This workspace’s data API does not filter by {ignored.join(', ')} yet, so the list below
+            is not narrowed by {ignored.length > 1 ? 'those' : 'that'}.
+          </p>
+        ) : null}
+
+        {droppedOutOfScope > 0 ? (
+          // Good news about the guard, bad news about the API. Both are worth
+          // seeing: a data plane returning other workspaces' rows is a bug that
+          // silence would let run for months.
+          <p className={cn.error} role="alert">
+            This workspace’s data API returned {droppedOutOfScope} record
+            {droppedOutOfScope === 1 ? '' : 's'} belonging to another workspace. They were hidden,
+            and the record counts below exclude them.
+          </p>
+        ) : null}
+      </section>
+
+      <section className={cn.section}>
+        <div className="flex items-baseline justify-between">
+          <h2 className={cn.heading}>Library</h2>
+          <p className={cn.muted}>
+            {count} record{count === 1 ? '' : 's'}
+            {count > 0 ? ` · page ${page} of ${lastPage}` : ''}
+          </p>
+        </div>
+
+        {loading && documents.length === 0 ? <p className={cn.muted}>Loading…</p> : null}
+
+        {!loading && documents.length === 0 ? (
+          <EmptyState hasFilters={Boolean(filters.search || filters.source || filters.partyId || filters.occurredAfter || filters.occurredBefore)} sources={sources} classNames={cn} />
+        ) : null}
+
+        <div className="space-y-2">
+          {documents.map((document) => (
+            <button
+              key={document.id}
+              type="button"
+              className={cn.row}
+              aria-expanded={selectedId === document.id}
+              onClick={() => select(selectedId === document.id ? null : document.id)}
+            >
+              <div className="flex flex-wrap items-center gap-2">
+                {/* The source is a BADGE on every row, never a hidden column:
+                    "the AI learned this from a meeting" and "…from a contract in
+                    Drive" are different claims to whoever reads a draft later. */}
+                <span className={cn.badge}>{document.sourceLabel || document.source}</span>
+                <span className="font-medium text-gray-900">{document.title}</span>
+              </div>
+              <p className={cn.muted}>
+                {formatDate(document.occurredAt)}
+                {document.participants.length
+                  ? ` · ${document.participants.map((party) => party.name).join(', ')}`
+                  : ''}
+                {document.sections.length
+                  ? ` · ${document.sections.map((section) => section.label).join(', ')}`
+                  : ''}
+              </p>
+              {preview(document) ? (
+                <p className="mt-1 text-sm text-gray-600">{preview(document)}</p>
+              ) : (
+                <p className={cn.muted}>No text was captured for this record.</p>
+              )}
+            </button>
+          ))}
+        </div>
+
+        {count > size ? (
+          <div className="flex items-center gap-2">
+            <button
+              type="button"
+              className={cn.button}
+              disabled={page <= 1 || loading}
+              onClick={() => setFilters((prev) => ({ ...prev, page: Math.max(1, page - 1) }))}
+            >
+              Previous
+            </button>
+            <button
+              type="button"
+              className={cn.button}
+              disabled={page >= lastPage || loading}
+              onClick={() => setFilters((prev) => ({ ...prev, page: page + 1 }))}
+            >
+              Next
+            </button>
+            {/* Paging is a SERVER round trip (CLAUDE.md rule 8) — the browser
+                never holds the corpus, so this keeps working at any size. */}
+            <span className={cn.muted}>Page {page} of {lastPage}</span>
+          </div>
+        ) : null}
+      </section>
+
+      {selected ? (
+        <DocumentDetail
+          document={selected}
+          scope={scope}
+          classNames={cn}
+          onClose={() => select(null)}
+          onFilterByParty={(partyId) => update({ partyId })}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+//  freshness
+// ---------------------------------------------------------------------------
+
+const FRESHNESS_WORDS: Record<SourceFreshness['status'], string> = {
+  ok: 'Up to date',
+  stale: 'Stale',
+  error: 'Failing',
+  never: 'Nothing yet',
+};
+
+function FreshnessStrip({
+  sources, classNames: cn, now,
+}: { sources: SourceFreshness[]; classNames: Record<LibrarySlot, string>; now: number }) {
+  if (sources.length === 0) return null;
+  return (
+    <section className={cn.section} aria-label="Source freshness">
+      <div className="flex flex-wrap gap-2">
+        {sources.map((source) => (
+          <div key={source.source} className={cn.card}>
+            <div className="flex items-center gap-2">
+              <span className={cn.badge}>{source.label}</span>
+              <span
+                className={source.status === 'ok' ? 'text-xs text-gray-500' : 'text-xs font-medium text-amber-700'}
+              >
+                {FRESHNESS_WORDS[source.status]}
+              </span>
+            </div>
+            <p className={cn.muted}>
+              {source.documentCount} record{source.documentCount === 1 ? '' : 's'} · synced{' '}
+              {relative(source.lastSyncedAt, now)}
+            </p>
+            {/* A source that is failing says so HERE, next to the corpus it is
+                supposed to be filling — not on a settings page nobody opens. */}
+            {source.detail ? <p className="text-xs text-amber-700">{source.detail}</p> : null}
+          </div>
+        ))}
+      </div>
+    </section>
+  );
+}
+
+// ---------------------------------------------------------------------------
+//  empty state
+// ---------------------------------------------------------------------------
+
+/**
+ * Three different nothings, because they need three different actions: no
+ * sources connected, sources connected but nothing arrived, and a filter that
+ * matched nothing. One generic "No results" would send the user to the wrong
+ * place in two of the three.
+ */
+function EmptyState({
+  hasFilters, sources, classNames: cn,
+}: { hasFilters: boolean; sources: SourceFreshness[]; classNames: Record<LibrarySlot, string> }) {
+  if (hasFilters) {
+    return <p className={cn.muted}>Nothing matches those filters. Clear them to see everything.</p>;
+  }
+  if (sources.length === 0) {
+    return (
+      <p className={cn.muted}>
+        Nothing has been pulled in yet. Connect a source and its records appear here.
+      </p>
+    );
+  }
+  const failing = sources.filter((source) => source.status === 'error');
+  if (failing.length) {
+    return (
+      <p className={cn.warning} role="status">
+        Nothing has arrived yet, and {failing.map((source) => source.label).join(', ')}{' '}
+        {failing.length === 1 ? 'is' : 'are'} failing to sync.
+      </p>
+    );
+  }
+  return <p className={cn.muted}>Your sources are connected but have not delivered any records yet.</p>;
+}
+
+// ---------------------------------------------------------------------------
+//  detail
+// ---------------------------------------------------------------------------
+
+function DocumentDetail({
+  document, scope, classNames: cn, onClose, onFilterByParty,
+}: {
+  document: SourceDocument;
+  scope: CorpusScope;
+  classNames: Record<LibrarySlot, string>;
+  onClose: () => void;
+  onFilterByParty: (partyId: string) => void;
+}) {
+  // Defense in depth. The API scopes reads and Postgres RLS scopes them again,
+  // but a record that reached this component from the wrong workspace must not
+  // render — a leak is worst at the moment it is displayed as fact.
+  if (document.scope?.orgId && document.scope.orgId !== scope.orgId) {
+    return (
+      <section className={cn.card} aria-label="Record">
+        <p className={cn.error} role="alert">This record belongs to another workspace and was not shown.</p>
+      </section>
+    );
+  }
+
+  return (
+    <section className={cn.card} aria-label="Record detail">
+      <div className="flex items-start justify-between gap-4">
+        <div>
+          <div className="flex flex-wrap items-center gap-2">
+            <span className={cn.badge}>{document.sourceLabel || document.source}</span>
+            <h3 className={cn.heading}>{document.title}</h3>
+          </div>
+          <p className={cn.muted}>
+            {formatDate(document.occurredAt)}
+            {document.sourceRef ? ` · ${document.sourceRef}` : ''}
+          </p>
+        </div>
+        <button type="button" className={cn.button} onClick={onClose}>Close</button>
+      </div>
+
+      {document.url ? (
+        <p className="mt-2">
+          {/* Open it where it LIVES. A corpus that cannot point back at the
+              original is a copy nobody can check. */}
+          <a className="text-sm text-blue-700 underline" href={document.url} target="_blank" rel="noreferrer">
+            Open in {document.sourceLabel || document.source}
+          </a>
+        </p>
+      ) : null}
+
+      {document.participants.length ? (
+        <div className="mt-3">
+          <p className="text-sm font-medium text-gray-900">Parties</p>
+          <div className="mt-1 flex flex-wrap gap-2">
+            {document.participants.map((party) => (
+              <button
+                key={party.id}
+                type="button"
+                className={cn.badge}
+                onClick={() => onFilterByParty(party.id)}
+                title={`Show everything involving ${party.name}`}
+              >
+                {party.name}{party.kind ? ` · ${party.kind}` : ''}
+              </button>
+            ))}
+          </div>
+        </div>
+      ) : null}
+
+      {document.body ? (
+        <div className="mt-3">
+          <p className="text-sm font-medium text-gray-900">Summary</p>
+          <p className="mt-1 whitespace-pre-wrap text-sm text-gray-700">{document.body}</p>
+        </div>
+      ) : null}
+
+      {/* Long-form under the SOURCE's own name for it — "Transcript" for a
+          meeting, "Extracted text" for a PDF. This component does not know
+          which is which, and must not. */}
+      {document.sections.map((section) => (
+        <details key={section.key} className="mt-3">
+          <summary className="cursor-pointer text-sm font-medium text-gray-900">{section.label}</summary>
+          <pre className="mt-2 max-h-96 overflow-auto whitespace-pre-wrap rounded bg-gray-50 p-2 text-xs text-gray-700">
+            {section.text}
+          </pre>
+        </details>
+      ))}
+
+      {!document.body && document.sections.length === 0 ? (
+        <p className={`mt-3 ${cn.muted}`}>
+          This record arrived with no text. Its source may have deleted the content upstream.
+        </p>
+      ) : null}
+    </section>
+  );
+}