@smartmemory/wiki-components 0.1.0 → 0.2.0

package/README.md

@@ -26,7 +26,7 @@ npm install @smartmemory/wiki-components react react-dom date-fns lucide-react
 
 ## Contract
 
-`src/data-client.d.ts` is the contract: four calls (`identity`, `featureHub`, `decisions`, `search`), the endpoint and
+`src/data-client.d.ts` is the contract: five calls (`identity`, `featureHub`, `decisions`, `decisionsPage`, `search`), the endpoint and
 request body each maps to on the wiki API, and the result types (from `wiki/contracts/query.schema.json`). The same list is
 runtime data in `DATA_CLIENT_CALLS`; `ui/test/wiki-components.test.jsx` pins the typed file, the table and the app's client
 to each other. `<WikiDataProvider>` refuses a client missing a method.
@@ -34,16 +34,22 @@ to each other. `<WikiDataProvider>` refuses a client missing a method.
 ## Use
 
 ```jsx
-import { WikiDataProvider, FeatureHub, Search, wikiPath } from "@smartmemory/wiki-components";
+import { WikiDataProvider, FeatureHub, Search, Decisions, wikiPath } from "@smartmemory/wiki-components";
 
 <WikiDataProvider client={myClient}>
   <FeatureHub featureId="CORE-1" workspace="wiki-eng" />
   <Search query="recall" workspaces={["wiki-eng", "wiki-gtm"]}
     onNavigate={(target) => /* {kind: "search", query?, workspace?} | {kind: "note", workspace, docId} */ go(target)}
     hrefFor={(target) => `http://127.0.0.1:8791/ui${wikiPath(target)}`} />
+  <Decisions workspace="wiki-eng" />
 </WikiDataProvider>
 ```
 
+- `Decisions` is the paged list of every decision of the workspace, newest first, 50 a page. Its data is
+  `client.decisionsPage({workspace, cursor?, size?})` (`POST /query/decisions`, `filters: {}`, `page: {size, cursor?}`),
+  which resolves `{items, total, next_cursor, generated_at}`. `cursor` is the previous page's `next_cursor`, opaque.
+  The paging pieces are exported for the next screens: `usePagedCall(key, run, {size})` (the cursor stack in component
+  state, no react-query), `Table`, `Pager`.
 - `workspace` / `workspaces` are optional: without them a screen calls `client.identity()` and uses the caller's grants
   (FeatureHub the first one).
 - `onNavigate(target)` receives a plain left click on a link and the search box's submit. `hrefFor(target)` is each link's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartmemory/wiki-components",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "The wiki's feature hub and search screens as router-free React components fed by an injected DataClient (WIKI-UI-COMPONENTS-1). Ships JSX source for a bundler host (Vite).",
   "license": "BUSL-1.1",
   "author": "Regression Analytics LLC",

package/src/Decisions.jsx

@@ -0,0 +1,34 @@
+import React from "react";
+import { useDataClient, useWorkspaces } from "./data-client";
+import { usePagedCall } from "./paged";
+import { fmtDate } from "./lib";
+import ListPage from "./parts/ListPage";
+import PageHeader from "./parts/PageHeader";
+import Table from "./parts/Table";
+import Pager from "./parts/Pager";
+import StatusChip from "./parts/StatusChip";
+
+/** The decisions list: every recorded decision of `workspace` (default: the first of identity().workspaces), newest first,
+ *  50 a page with a pager. `onNavigate` / `hrefFor` are accepted for the host contract shared by the screens; the list has
+ *  no links yet. Data: DataClient decisionsPage, one call per page. */
+export default function Decisions({ workspace: given }) {
+  const client = useDataClient();
+  const ws = useWorkspaces(given ? [given] : undefined);
+  const workspace = given || ws.workspaces?.[0];
+  const p = usePagedCall(["decisions", workspace], (page) => client.decisionsPage({ workspace, ...page }), { enabled: !!workspace });
+  return (
+    <ListPage header={<PageHeader title="Decisions">Recorded decisions and the docs they came from.</PageHeader>} foot={<Pager p={p} />}>
+      <Table head={["Entry", "Text", "Status", "Refs", "Date"]} loading={p.isLoading || ws.isLoading} error={p.error || ws.error} count={p.items.length}>
+        {p.items.map((e) => (
+          <tr key={e.entry_id} className="align-top hover:bg-neutral-50/60">
+            <td className="whitespace-nowrap px-3 py-2 font-mono text-[12px] text-neutral-600">{e.entry_id}</td>
+            <td className="px-3 py-2 text-neutral-800">{e.text}</td>
+            <td className="px-3 py-2">{e.status && <StatusChip status={e.status} />}</td>
+            <td className="px-3 py-2 font-mono text-[11px] text-neutral-500">{(e.refs || []).join(", ")}</td>
+            <td className="whitespace-nowrap px-3 py-2 text-xs tabular-nums text-neutral-500">{fmtDate(e.ts)}</td>
+          </tr>
+        ))}
+      </Table>
+    </ListPage>
+  );
+}

package/src/data-client.d.ts

@@ -1,4 +1,4 @@
-// WIKI-UI-COMPONENTS-1: the DataClient contract. Every call the FeatureHub and Search screens make, and nothing else.
+// WIKI-UI-COMPONENTS-1: the DataClient contract. Every call the FeatureHub, Search and Decisions screens make, and nothing else.
 // A host (the wiki's /ui/ app, Compose's wiki tab) passes one object with these async methods to <WikiDataProvider>.
 // The components never fetch: each call below is the whole of their I/O.
 //
@@ -9,6 +9,7 @@
 //   identity     GET  /identity               (none)  -> identity_response, wiki/contracts/identity.schema.json
 //   featureHub   POST /query/feature_hub      {query: "feature_hub", workspace, filters: {feature_id}, page: {size: 200}}
 //   decisions    POST /query/decisions        {query: "decisions",   workspace, filters: {feature_id}, page: {size: 50}}
+//   decisionsPage POST /query/decisions       {query: "decisions",   workspace, filters: {},           page: {size: 50, cursor?}}
 //   search       POST /query/search           {query: "search",      workspace, filters: {q},          page: {}}
 //
 // The same table is runtime data in data-client.jsx (DATA_CLIENT_CALLS); a test pins the two to each other.
@@ -106,6 +107,9 @@ export interface DataClient {
   featureHub(args: { workspace: Workspace; featureId: string }): Promise<FeatureHubResult>;
   /** POST /query/decisions, filters {feature_id}, page {size: 50}. */
   decisions(args: { workspace: Workspace; featureId: string }): Promise<QueryResult<EntryItem>>;
+  /** POST /query/decisions, filters {}, page {size (default 50), cursor?}: one page of every decision of the workspace, newest first.
+   *  `cursor` is the previous page's `next_cursor`, opaque. */
+  decisionsPage(args: { workspace: Workspace; cursor?: string; size?: number }): Promise<QueryResult<EntryItem>>;
   /** POST /query/search, filters {q} (1 to 256 characters), page {}. One call per workspace searched. */
   search(args: { workspace: Workspace; q: string }): Promise<SearchResult>;
 }

package/src/data-client.jsx

@@ -6,6 +6,7 @@ export const DATA_CLIENT_CALLS = [
   { method: "identity", endpoint: "GET /identity" },
   { method: "featureHub", endpoint: "POST /query/feature_hub", query: "feature_hub", page: { size: 200 } },
   { method: "decisions", endpoint: "POST /query/decisions", query: "decisions", page: { size: 50 } },
+  { method: "decisionsPage", endpoint: "POST /query/decisions", query: "decisions", page: { size: 50 } },
   { method: "search", endpoint: "POST /query/search", query: "search", page: {} },
 ];
 

package/src/index.d.ts

@@ -1,6 +1,6 @@
 // Types for @smartmemory/wiki-components. The DataClient contract and NavTarget: data-client.d.ts.
 import type { ReactElement, ReactNode } from "react";
-import type { DataClient, NavTarget, Workspace } from "./data-client";
+import type { DataClient, NavTarget, QueryResult, Workspace } from "./data-client";
 
 export * from "./data-client";
 
@@ -22,6 +22,19 @@ export function Search(props: { query?: string; workspace?: Workspace | null; wo
 
 export const DATA_CLIENT_CALLS: { method: keyof DataClient; endpoint: string; query?: string; page?: Record<string, number> }[];
 
+/** Every recorded decision of `workspace` (default: the first of identity().workspaces), 50 a page with a pager. */
+export function Decisions(props: { workspace?: Workspace | null } & NavProps): ReactElement;
+
+/** One DataClient call paged by cursor. `run({cursor?, size})` fetches a page; a new `key` restarts at page one. */
+export function usePagedCall<T>(
+  key: unknown,
+  run: (page: { cursor?: string; size: number }) => Promise<QueryResult<T>>,
+  opts?: { size?: number; enabled?: boolean },
+): { items: T[]; result?: QueryResult<T>; total?: number; isLoading: boolean; error: Error | null; index: number; size: number; next: (() => void) | null; prev: (() => void) | null };
+
+export function Table(props: { head: ReactNode[]; children?: ReactNode; loading?: boolean; error?: Error | null; empty?: string; count?: number }): ReactElement;
+export function Pager(props: { p: { total?: number; index: number; size: number; items: unknown[]; next: (() => void) | null; prev: (() => void) | null } }): ReactElement | null;
+
 /** A NavTarget as a path of the wiki's /ui/ app (relative to its basename, e.g. "/search?q=x"). */
 export function wikiPath(target: NavTarget): string;
 export function wsName(workspace: Workspace): string;

package/src/index.js

@@ -2,6 +2,8 @@
 // data from an injected DataClient (data-client.d.ts). The wiki's /ui/ app and Compose's wiki tab both render these.
 export { default as FeatureHub, prefixOnly } from "./FeatureHub";
 export { default as Search } from "./Search";
+export { default as Decisions } from "./Decisions";
+export { usePagedCall } from "./paged";
 export { WikiDataProvider, useDataClient, useClientCall, DATA_CLIENT_CALLS } from "./data-client";
 export { wikiPath, wsName, wsUrl, noteUrl, toDate, fmtDate, summaryOf } from "./lib";
 // The parts the screens are built from; the /ui/ app's other pages use them too (ui/src/components/wiki/* re-export them).
@@ -18,3 +20,5 @@ export { default as ListPage } from "./parts/ListPage";
 export { default as SearchGroup } from "./parts/SearchGroup";
 export { default as SearchBox } from "./parts/SearchBox";
 export { default as NavLink } from "./parts/NavLink";
+export { default as Table } from "./parts/Table";
+export { default as Pager } from "./parts/Pager";

package/src/paged.jsx

@@ -0,0 +1,26 @@
+import { useState } from "react";
+import { useClientCall } from "./data-client";
+
+/** A DataClient call paged by cursor (no react-query). `run({cursor, size})` is one page: the host's method with the
+ *  caller's fixed arguments. The cursor stack lives in this component's state: `next` pushes the page's `next_cursor`,
+ *  `prev` pops it, and a new `key` (any JSON value naming the arguments) starts again at the first page. The result is
+ *  the shape the Pager takes: `items`, `total`, `index` (0-based page), `size`, `next`/`prev` (null when unavailable). */
+export function usePagedCall(key, run, { size = 50, enabled = true } = {}) {
+  const k = JSON.stringify(key);
+  const [state, setState] = useState({ key: k, cursors: [null] });
+  const cursors = state.key === k ? state.cursors : [null];
+  const cursor = cursors[cursors.length - 1];
+  const q = useClientCall(["paged", key, size, cursor], () => run({ ...(cursor ? { cursor } : {}), size }), { enabled, keepPrevious: true });
+  const next = q.data?.next_cursor;
+  return {
+    items: q.data?.items || [],
+    result: q.data,
+    total: q.data?.total,
+    isLoading: q.isLoading,
+    error: q.error,
+    index: cursors.length - 1,
+    size,
+    next: next ? () => setState({ key: k, cursors: [...cursors, next] }) : null,
+    prev: cursors.length > 1 ? () => setState({ key: k, cursors: cursors.slice(0, -1) }) : null,
+  };
+}

package/src/parts/Pager.jsx

@@ -0,0 +1,17 @@
+import React from "react";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+
+const btn = "inline-flex h-7 w-7 items-center justify-center rounded border border-neutral-200 text-neutral-600 hover:border-blue-600 hover:text-blue-600 disabled:opacity-30 disabled:hover:border-neutral-200 disabled:hover:text-neutral-600";
+
+export default function Pager({ p }) {
+  if (!p.total) return null;
+  const start = p.index * p.size + 1;
+  const end = Math.min(start + p.items.length - 1, p.total);
+  return (
+    <div className="mt-3 flex shrink-0 items-center justify-end gap-3 text-xs tabular-nums text-neutral-500">
+      <span>{start.toLocaleString()}–{end.toLocaleString()} of {p.total.toLocaleString()}</span>
+      <button className={btn} disabled={!p.prev} onClick={p.prev} aria-label="Previous page"><ChevronLeft className="h-4 w-4" /></button>
+      <button className={btn} disabled={!p.next} onClick={p.next} aria-label="Next page"><ChevronRight className="h-4 w-4" /></button>
+    </div>
+  );
+}

package/src/parts/Table.jsx

@@ -0,0 +1,17 @@
+import React from "react";
+import Loading from "./Loading";
+import ErrorBox from "./ErrorBox";
+
+export default function Table({ head, children, loading, error, empty = "Nothing here.", count }) {
+  return (
+    <div className="rounded-lg border border-neutral-200">
+      <table className="w-full text-left text-[13px]">
+        <thead className="sticky top-0 z-10 bg-neutral-50 text-[11px] uppercase tracking-wider text-neutral-500">
+          <tr>{head.map((h, i) => <th key={i} className="whitespace-nowrap px-3 py-2 font-medium">{h}</th>)}</tr>
+        </thead>
+        <tbody className="divide-y divide-neutral-100">{children}</tbody>
+      </table>
+      {error ? <ErrorBox error={error} className="m-3" /> : loading ? <div className="px-3"><Loading /></div> : count === 0 && <p className="px-3 py-6 text-sm text-neutral-400">{empty}</p>}
+    </div>
+  );
+}