@smartmemory/wiki-components 0.3.0 → 0.5.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: six calls (`identity`, `featureHub`, `decisions`, `decisionsPage`, `sourcesPage`, `search`), the endpoint and
+`src/data-client.d.ts` is the contract: nine calls (`identity`, `featureHub`, `decisions`, `decisionsPage`, `sourcesPage`, `docsByArea`, `ledger`, `upcomingCalls`, `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,15 +34,17 @@ to each other. `<WikiDataProvider>` refuses a client missing a method.
 ## Use
 
 ```jsx
-import { WikiDataProvider, FeatureHub, Search, Decisions, Sources, wikiPath } from "@smartmemory/wiki-components";
+import { WikiDataProvider, FeatureHub, Search, Decisions, Sources, AreaDocs, Ledger, 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)}
+    onNavigate={(target) => /* {kind: "search", query?, workspace?} | {kind: "note", workspace, docId} | {kind: "area", area} */ go(target)}
     hrefFor={(target) => `http://127.0.0.1:8791/ui${wikiPath(target)}`} />
   <Decisions workspace="wiki-eng" />
   <Sources workspace="wiki-eng" />
+  <AreaDocs area="search" workspace="wiki-eng" onNavigate={go} hrefFor={href} />
+  <Ledger workspace="wiki-eng" />
 </WikiDataProvider>
 ```
 
@@ -56,6 +58,17 @@ import { WikiDataProvider, FeatureHub, Search, Decisions, Sources, wikiPath } fr
   `client.sourcesPage({workspace, cursor?, size?})` (`POST /query/sources`, `filters: {}`, `page: {size, cursor?}`), which
   resolves `{items, total, next_cursor, generated_at}` with `SourceItem` rows. Also exported: `FreshnessBadge`,
   `OverdueBadge`, `useNow`, `ago`, `fmtDuration`.
+- `AreaDocs` is the paged list of the docs filed under one area (`area` prop, required), 50 a page. Its data is
+  `client.docsByArea({workspace, area, cursor?, size?})` (`POST /query/docs_by_area`, `filters: {area}`, `page: {size, cursor?}`),
+  which resolves `{items, total, next_cursor, generated_at}` with `DocItem` rows. With `onNavigate` or `hrefFor`, each doc
+  lists its areas as links, the new NavTarget `{kind: "area", area}` (`wikiPath` gives `/area/<area>`; `areaUrl` is exported).
+- `Ledger` is the last 30 days of the workspace's ledger, newest first, 50 a page, plus an "Upcoming calls" section when
+  the host serves that feed. Its data is `client.ledger({workspace, from, to, cursor?, size?})` (`POST /query/ledger`,
+  `filters: {from, to}`, ISO instants with an offset; the sort is the host's, `ts` newest first, a screen never sends it),
+  which resolves `{items, total, next_cursor, generated_at}` with `EntryItem` rows, and `client.upcomingCalls({workspace})`
+  (`GET /feeds/upcoming_calls`), which resolves `{items, errors}`, or `null` when the host does not serve the feed (the
+  section is then left out; an empty feed still shows "No upcoming calls."). The window is 30 days back to one day ahead of
+  `now`, an optional prop (ms since the epoch) for tests, else the first render's time. Also exported: `LedgerTimeline`.
 - `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.3.0",
+  "version": "0.5.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/AreaDocs.jsx

@@ -0,0 +1,26 @@
+import React from "react";
+import { useDataClient, useWorkspaces } from "./data-client";
+import { usePagedCall } from "./paged";
+import ListPage from "./parts/ListPage";
+import PageHeader from "./parts/PageHeader";
+import DocRow from "./parts/DocRow";
+import Loading from "./parts/Loading";
+import Pager from "./parts/Pager";
+import ErrorBox from "./parts/ErrorBox";
+
+/** The docs filed under one area: `area` of `workspace` (default: the first of identity().workspaces), 50 a page with a
+ *  pager. Each doc lists its areas as links: `onNavigate({kind: "area", area})` follows one, `hrefFor(target)` is its href.
+ *  Data: DataClient docsByArea. */
+export default function AreaDocs({ area, workspace: given, onNavigate, hrefFor }) {
+  const client = useDataClient();
+  const ws = useWorkspaces(given ? [given] : undefined);
+  const workspace = given || ws.workspaces?.[0];
+  const p = usePagedCall(["docs_by_area", workspace, area], (page) => client.docsByArea({ workspace, area, ...page }), { enabled: !!workspace && !!area });
+  const error = p.error || ws.error;
+  return (
+    <ListPage header={<PageHeader eyebrow="Area" title={area}>{p.total != null && `${p.total} docs`}</PageHeader>} foot={<Pager p={p} />}>
+      <ErrorBox error={error} />
+      {p.isLoading || ws.isLoading ? <Loading /> : !error && p.items.length === 0 ? <p className="text-sm text-neutral-400">No docs in this area yet.</p> : p.items.map((d) => <DocRow key={d.doc_id} doc={d} onNavigate={onNavigate} hrefFor={hrefFor} />)}
+    </ListPage>
+  );
+}

package/src/Ledger.jsx

@@ -0,0 +1,47 @@
+import React, { useMemo } from "react";
+import { useClientCall, useDataClient, useWorkspaces } from "./data-client";
+import { usePagedCall } from "./paged";
+import ListPage from "./parts/ListPage";
+import PageHeader from "./parts/PageHeader";
+import LedgerTimeline from "./parts/LedgerTimeline";
+import EntryRows from "./parts/EntryRows";
+import Section from "./parts/Section";
+import Loading from "./parts/Loading";
+import Pager from "./parts/Pager";
+import ErrorBox from "./parts/ErrorBox";
+
+const DAY_MS = 86_400_000;
+const iso = (ms) => new Date(ms).toISOString().replace(/\.\d+Z$/, "Z");
+
+/** The ledger timeline: the last 30 days of `workspace` (default: the first of identity().workspaces), newest first, 50 a
+ *  page with a pager, and an "Upcoming calls" section when the host serves that feed. The window runs from 30 days before
+ *  `now` to one day after it (ms since the epoch; default: the time of the first render, kept for the life of the screen so
+ *  the query key stays stable). `onNavigate` / `hrefFor` are accepted for the host contract shared by the screens; the
+ *  timeline has no links yet. Data: DataClient ledger (one call per page) and upcomingCalls (one call). */
+export default function Ledger({ workspace: given, now }) {
+  const client = useDataClient();
+  const ws = useWorkspaces(given ? [given] : undefined);
+  const workspace = given || ws.workspaces?.[0];
+  const fixedNow = useMemo(() => Date.now(), []);
+  const at = now ?? fixedNow;
+  const range = useMemo(() => ({ from: iso(at - 30 * DAY_MS), to: iso(at + DAY_MS) }), [at]);
+  const p = usePagedCall(["ledger", workspace, range], (page) => client.ledger({ workspace, ...range, ...page }), { enabled: !!workspace });
+  const calls = useClientCall(["upcoming_calls", workspace], () => client.upcomingCalls({ workspace }), { enabled: !!workspace });
+  const error = p.error || ws.error;
+  return (
+    <ListPage header={<PageHeader title="Ledger">{p.total != null && `${p.total.toLocaleString()} entries in the last 30 days, newest first`}</PageHeader>} foot={<Pager p={p} />}>
+      <ErrorBox error={error} />
+      {p.isLoading || ws.isLoading ? <Loading /> : <LedgerTimeline entries={p.items} />}
+      {/* the calendar feed is served only on a host that wires it: elsewhere (null) there is no calls section */}
+      {!calls.isLoading && calls.data !== null && (calls.data || calls.error) && (
+        <Section title="Upcoming calls" className="mt-12">
+          {(calls.data?.errors || []).map((e) => (
+            <p key={e.code} role="status" className="mb-2 rounded-md border border-amber-200 bg-amber-50 px-3 py-2 text-sm text-amber-800">Calls are incomplete: {e.message} ({e.code})</p>
+          ))}
+          <ErrorBox error={calls.error} />
+          {calls.data && <EntryRows entries={calls.data.items} empty="No upcoming calls." />}
+        </Section>
+      )}
+    </ListPage>
+  );
+}

package/src/data-client.d.ts

@@ -1,4 +1,4 @@
-// WIKI-UI-COMPONENTS-1: the DataClient contract. Every call the FeatureHub, Search, Decisions and Sources screens make, and nothing else.
+// WIKI-UI-COMPONENTS-1: the DataClient contract. Every call the FeatureHub, Search, Decisions, Sources, AreaDocs and Ledger 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.
 //
@@ -11,6 +11,9 @@
 //   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?}}
 //   sourcesPage  POST /query/sources          {query: "sources",     workspace, filters: {},           page: {size: 50, cursor?}}
+//   docsByArea   POST /query/docs_by_area     {query: "docs_by_area", workspace, filters: {area}, page: {size: 50, cursor?}}
+//   ledger       POST /query/ledger           {query: "ledger",      workspace, filters: {from, to}, page: {size: 50, cursor?}}  (sort is the host's: ts, newest first)
+//   upcomingCalls GET /feeds/upcoming_calls?workspace=  (none) -> data_envelope; an absent feed (the wiki answers 404 not_found) resolves to null
 //   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.
@@ -104,6 +107,12 @@ export interface SourceItem {
   overdue: boolean | null;
 }
 
+/** The upcoming_calls feed (component.schema.json data_envelope): `items` are entries; `errors` say what a partial answer is missing. */
+export interface UpcomingCalls {
+  items: EntryItem[];
+  errors: { code: string; message?: string }[];
+}
+
 /** x-named-queries.feature_hub.result: the feature's docs plus the feature itself (null when it is not on the roadmap). */
 export interface FeatureHubResult extends QueryResult<DocItem> {
   feature: FeatureItem | null;
@@ -128,6 +137,14 @@ export interface DataClient {
   /** POST /query/sources, filters {}, page {size (default 50), cursor?}: one page of the workspace's ingestion sources.
    *  `cursor` is the previous page's `next_cursor`, opaque. */
   sourcesPage(args: { workspace: Workspace; cursor?: string; size?: number }): Promise<QueryResult<SourceItem>>;
+  /** POST /query/docs_by_area, filters {area} (required, 1 to 200 characters), page {size (default 50), cursor?}: one page of the live docs
+   *  filed under `area`. `cursor` is the previous page's `next_cursor`, opaque. */
+  docsByArea(args: { workspace: Workspace; area: string; cursor?: string; size?: number }): Promise<QueryResult<DocItem>>;
+  /** POST /query/ledger, filters {from, to} (both required: ISO instants with an offset, `from` <= `to`, at most 366 days apart), page {size (default 50), cursor?}:
+   *  one page of the ledger entries in the window, newest first (the sort is fixed by the host, never sent by a screen). `cursor` is the previous page's `next_cursor`, opaque. */
+  ledger(args: { workspace: Workspace; from: string; to: string; cursor?: string; size?: number }): Promise<QueryResult<EntryItem>>;
+  /** GET /feeds/upcoming_calls: the calendar feed's items, or null when this host does not serve the feed (not an error, not an empty list). */
+  upcomingCalls(args: { workspace: Workspace }): Promise<UpcomingCalls | null>;
   /** POST /query/search, filters {q} (1 to 256 characters), page {}. One call per workspace searched. */
   search(args: { workspace: Workspace; q: string }): Promise<SearchResult>;
 }
@@ -136,4 +153,5 @@ export interface DataClient {
  *  (the /ui/ app: wikiPath()). */
 export type NavTarget =
   | { kind: "search"; query?: string; workspace?: Workspace }
-  | { kind: "note"; workspace: Workspace; docId: string };
+  | { kind: "note"; workspace: Workspace; docId: string }
+  | { kind: "area"; area: string };

package/src/data-client.jsx

@@ -8,6 +8,9 @@ export const DATA_CLIENT_CALLS = [
   { method: "decisions", endpoint: "POST /query/decisions", query: "decisions", page: { size: 50 } },
   { method: "decisionsPage", endpoint: "POST /query/decisions", query: "decisions", page: { size: 50 } },
   { method: "sourcesPage", endpoint: "POST /query/sources", query: "sources", page: { size: 50 } },
+  { method: "docsByArea", endpoint: "POST /query/docs_by_area", query: "docs_by_area", page: { size: 50 } },
+  { method: "ledger", endpoint: "POST /query/ledger", query: "ledger", page: { size: 50 } },
+  { method: "upcomingCalls", endpoint: "GET /feeds/upcoming_calls" },
   { 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, QueryResult, Workspace } from "./data-client";
+import type { DataClient, EntryItem, NavTarget, QueryResult, Workspace } from "./data-client";
 
 export * from "./data-client";
 
@@ -28,6 +28,13 @@ export function Decisions(props: { workspace?: Workspace | null } & NavProps): R
 /** Every ingestion source of `workspace` (default: the first of identity().workspaces), 50 a page with a pager. */
 export function Sources(props: { workspace?: Workspace | null } & NavProps): ReactElement;
 
+/** The docs filed under `area` of `workspace` (default: the first of identity().workspaces), 50 a page with a pager. Each doc's other areas link to their own AreaDocs through `onNavigate({kind: "area", area})`. */
+export function AreaDocs(props: { area: string; workspace?: Workspace | null } & NavProps): ReactElement;
+
+/** The last 30 days of `workspace` (default: the first of identity().workspaces), newest first, 50 a page with a pager, plus an "Upcoming calls" section when the host serves that feed. `now` (ms since the epoch) fixes the window's end for tests; default: the first render's time. */
+export function Ledger(props: { workspace?: Workspace | null; now?: number } & NavProps): ReactElement;
+export function LedgerTimeline(props: { entries: EntryItem[] }): 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,
@@ -46,3 +53,5 @@ export function Pager(props: { p: { total?: number; index: number; size: number;
 /** 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;
+/** The path of an area's docs page in the wiki's /ui/ app. */
+export function areaUrl(area: string): string;

package/src/index.js

@@ -4,9 +4,11 @@ export { default as FeatureHub, prefixOnly } from "./FeatureHub";
 export { default as Search } from "./Search";
 export { default as Decisions } from "./Decisions";
 export { default as Sources } from "./Sources";
+export { default as AreaDocs } from "./AreaDocs";
+export { default as Ledger } from "./Ledger";
 export { usePagedCall } from "./paged";
 export { WikiDataProvider, useDataClient, useClientCall, DATA_CLIENT_CALLS } from "./data-client";
-export { wikiPath, wsName, wsUrl, noteUrl, toDate, fmtDate, ago, fmtDuration, summaryOf } from "./lib";
+export { wikiPath, wsName, wsUrl, noteUrl, areaUrl, toDate, fmtDate, ago, fmtDuration, summaryOf } from "./lib";
 export { default as useNow } from "./useNow";
 // The parts the screens are built from; the /ui/ app's other pages use them too (ui/src/components/wiki/* re-export them).
 export { default as ErrorBox } from "./parts/ErrorBox";
@@ -24,5 +26,6 @@ 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";
+export { default as LedgerTimeline } from "./parts/LedgerTimeline";
 export { default as FreshnessBadge } from "./parts/FreshnessBadge";
 export { default as OverdueBadge } from "./parts/OverdueBadge";

package/src/lib.js

@@ -10,6 +10,7 @@ export const wsName = (ws) => {
   return WS_NAMES[tail] || tail.split(/[-_]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(" ") || "Workspace";
 };
 export const wsUrl = (ws) => `/w/${encodeURIComponent(ws)}`;
+export const areaUrl = (a) => `/area/${encodeURIComponent(a)}`;
 export const noteUrl = (ws, id) => `${wsUrl(ws)}/note?id=${encodeURIComponent(id)}`;
 
 export const toDate = (d) => (d ? new Date(d.length <= 10 || /([zZ]|[+-]\d\d:?\d\d)$/.test(d) ? d : d + "Z") : null);
@@ -33,6 +34,7 @@ export const summaryOf = (feature) => (typeof feature?.summary === "string" && f
 /** A NavTarget (data-client.d.ts) as a route of the wiki's own /ui/ app, relative to its basename. */
 export function wikiPath(target) {
   if (target.kind === "note") return noteUrl(target.workspace, target.docId);
+  if (target.kind === "area") return areaUrl(target.area);
   if (target.kind === "search") {
     const p = new URLSearchParams({ ...(target.query ? { q: target.query } : {}), ...(target.workspace ? { workspace: target.workspace } : {}) });
     return `/search?${p}`;

package/src/parts/DocRow.jsx

@@ -1,9 +1,13 @@
 import React from "react";
 import TypeBadge from "./TypeBadge";
+import NavLink from "./NavLink";
 import { fmtDate } from "../lib";
 
-export default function DocRow({ doc, right }) {
-  return (
+/** One doc. With `onNavigate` or `hrefFor` (a screen that links, e.g. AreaDocs) the doc's areas are listed under the row,
+ *  each a NavTarget {kind: "area"}; without them the row is exactly as before. */
+export default function DocRow({ doc, right, onNavigate, hrefFor }) {
+  const links = (onNavigate || hrefFor) && doc.areas?.length > 0;
+  const row = (
     <div className="grid items-center gap-3 rounded-md px-3 py-2 hover:bg-neutral-50 grid-cols-[6.5rem_1fr_auto] sm:grid-cols-[6.5rem_1fr_16rem_6.5rem]">
       <TypeBadge type={doc.kind} />
       <span className="truncate font-medium text-neutral-900">{doc.title}</span>
@@ -12,4 +16,15 @@ export default function DocRow({ doc, right }) {
       {right}
     </div>
   );
+  if (!links) return row;
+  return (
+    <div>
+      {row}
+      <div className="flex flex-wrap gap-1.5 px-3 pb-2 pl-[7.75rem]" data-testid="area-links">
+        {doc.areas.map((a) => (
+          <NavLink key={a} target={{ kind: "area", area: a }} hrefFor={hrefFor} onNavigate={onNavigate} className="rounded-full border border-neutral-200 px-2 py-0.5 text-[11px] text-neutral-600 hover:border-blue-500 hover:text-neutral-900">{a}</NavLink>
+        ))}
+      </div>
+    </div>
+  );
 }

package/src/parts/LedgerTimeline.jsx

@@ -0,0 +1,20 @@
+import React from "react";
+import { fmtDate } from "../lib";
+
+export default function LedgerTimeline({ entries }) {
+  if (!entries.length) return <p className="px-3 text-sm text-neutral-400">No ledger entries.</p>;
+  return (
+    <ol className="relative ml-2 border-l border-neutral-200">
+      {entries.map((e, i) => (
+        <li key={e.entry_id} className="relative pb-4 pl-5">
+          <span className="absolute -left-[4.5px] top-1.5 h-2 w-2 rounded-full bg-neutral-300" />
+          {(i === 0 || entries[i - 1].ts.slice(0, 10) !== e.ts.slice(0, 10)) && <div className="mb-1 text-xs font-semibold text-neutral-500">{fmtDate(e.ts)}</div>}
+          <div className="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+            <span className="font-mono text-[11px] text-neutral-400">{e.ts.slice(11, 16)}</span>
+            <span className="text-[13px] text-neutral-800">{e.text}</span>
+          </div>
+        </li>
+      ))}
+    </ol>
+  );
+}