@smartmemory/wiki-components 0.2.0 → 0.3.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: five calls (`identity`, `featureHub`, `decisions`, `decisionsPage`, `search`), the endpoint and
+`src/data-client.d.ts` is the contract: six calls (`identity`, `featureHub`, `decisions`, `decisionsPage`, `sourcesPage`, `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,7 +34,7 @@ to each other. `<WikiDataProvider>` refuses a client missing a method.
 ## Use
 
 ```jsx
-import { WikiDataProvider, FeatureHub, Search, Decisions, wikiPath } from "@smartmemory/wiki-components";
+import { WikiDataProvider, FeatureHub, Search, Decisions, Sources, wikiPath } from "@smartmemory/wiki-components";
 
 <WikiDataProvider client={myClient}>
   <FeatureHub featureId="CORE-1" workspace="wiki-eng" />
@@ -42,6 +42,7 @@ import { WikiDataProvider, FeatureHub, Search, Decisions, wikiPath } from "@smar
     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" />
+  <Sources workspace="wiki-eng" />
 </WikiDataProvider>
 ```
 
@@ -50,6 +51,11 @@ import { WikiDataProvider, FeatureHub, Search, Decisions, wikiPath } from "@smar
   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`.
+- `Sources` is the paged list of the workspace's ingestion sources, 50 a page, with status, last success, indexing age,
+  publication delay and an overdue badge (an unknown value reads "unknown", never 0 or "on time"). Its data is
+  `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`.
 - `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.2.0",
+  "version": "0.3.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/Sources.jsx

@@ -0,0 +1,41 @@
+import React from "react";
+import { useDataClient, useWorkspaces } from "./data-client";
+import { usePagedCall } from "./paged";
+import { fmtDuration } 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";
+import FreshnessBadge from "./parts/FreshnessBadge";
+import OverdueBadge from "./parts/OverdueBadge";
+
+/** The sources list: every ingestion source of `workspace` (default: the first of identity().workspaces), 50 a page with a
+ *  pager, each with its status, last success, indexing age, publication delay and overdue flag. `onNavigate` / `hrefFor`
+ *  are accepted for the host contract shared by the screens; the list has no links. Data: DataClient sourcesPage. */
+export default function Sources({ workspace: given }) {
+  const client = useDataClient();
+  const ws = useWorkspaces(given ? [given] : undefined);
+  const workspace = given || ws.workspaces?.[0];
+  const p = usePagedCall(["sources", workspace], (page) => client.sourcesPage({ workspace, ...page }), { enabled: !!workspace });
+  return (
+    <ListPage header={<PageHeader title="Sources">Where the indexer reads from, and how fresh each one is.</PageHeader>} foot={<Pager p={p} />}>
+      <Table head={["Source", "Plugin", "Host", "Docs", "Coverage", "Status", "Last success", "Indexing age", "Publication delay", "Overdue"]} loading={p.isLoading || ws.isLoading} error={p.error || ws.error} count={p.items.length}>
+        {p.items.map((s) => (
+          <tr key={s.source_id} className="align-top hover:bg-neutral-50/60">
+            <td className="px-3 py-2.5 font-medium">{s.source_id}</td>
+            <td className="px-3 py-2.5 font-mono text-xs text-neutral-600">{s.plugin}</td>
+            <td className="px-3 py-2.5 font-mono text-xs text-neutral-600">{s.host}</td>
+            <td className="px-3 py-2.5 tabular-nums">{s.discovered.toLocaleString()}</td>
+            <td className="px-3 py-2.5 text-xs text-neutral-600">{s.coverage}</td>
+            <td className="px-3 py-2.5"><StatusChip status={s.status} /></td>
+            <td className="px-3 py-2.5"><FreshnessBadge at={s.last_success} /></td>
+            <td className="px-3 py-2.5 tabular-nums text-xs text-neutral-600">{fmtDuration(s.indexing_age_s)}</td>
+            <td className="px-3 py-2.5 tabular-nums text-xs text-neutral-600">{fmtDuration(s.publication_delay_s)}</td>
+            <td className="px-3 py-2.5"><OverdueBadge overdue={s.overdue} /></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, Search and Decisions screens make, and nothing else.
+// WIKI-UI-COMPONENTS-1: the DataClient contract. Every call the FeatureHub, Search, Decisions and Sources 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.
 //
@@ -10,6 +10,7 @@
 //   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?}}
+//   sourcesPage  POST /query/sources          {query: "sources",     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.
@@ -89,6 +90,20 @@ export interface QueryResult<T> {
   generated_at: string;
 }
 
+/** query.schema.json $defs/source_item. `overdue` and the two durations are null when unknown (never shown as 0 or "on time"). */
+export interface SourceItem {
+  source_id: string;
+  plugin: string;
+  host: "us1" | "mac";
+  status: "ok" | "offline" | "failed" | "cursor_lost";
+  coverage: "full_text" | "excerpt" | "metadata";
+  last_success: string | null;
+  discovered: number;
+  indexing_age_s: number | null;
+  publication_delay_s: number | null;
+  overdue: boolean | null;
+}
+
 /** 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;
@@ -110,6 +125,9 @@ export interface DataClient {
   /** 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/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/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

@@ -7,6 +7,7 @@ export const DATA_CLIENT_CALLS = [
   { 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: "sourcesPage", endpoint: "POST /query/sources", query: "sources", page: { size: 50 } },
   { method: "search", endpoint: "POST /query/search", query: "search", page: {} },
 ];
 

package/src/index.d.ts

@@ -25,6 +25,9 @@ export const DATA_CLIENT_CALLS: { method: keyof DataClient; endpoint: string; qu
 /** 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;
 
+/** 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;
+
 /** 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,
@@ -32,6 +35,11 @@ export function usePagedCall<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 FreshnessBadge(props: { at?: string | null }): ReactElement;
+export function OverdueBadge(props: { overdue?: boolean | null }): ReactElement;
+export function ago(d?: string | null): string;
+export function fmtDuration(s?: number | null): string;
+export function useNow(ms?: number): number;
 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;
 

package/src/index.js

@@ -3,9 +3,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 { usePagedCall } from "./paged";
 export { WikiDataProvider, useDataClient, useClientCall, DATA_CLIENT_CALLS } from "./data-client";
-export { wikiPath, wsName, wsUrl, noteUrl, toDate, fmtDate, summaryOf } from "./lib";
+export { wikiPath, wsName, wsUrl, noteUrl, 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";
 export { default as Section } from "./parts/Section";
@@ -22,3 +24,5 @@ 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 FreshnessBadge } from "./parts/FreshnessBadge";
+export { default as OverdueBadge } from "./parts/OverdueBadge";

package/src/lib.js

@@ -1,4 +1,4 @@
-import { format } from "date-fns";
+import { format, formatDistanceToNowStrict } from "date-fns";
 
 // Helpers the screens share with the rest of the /ui/ app (ui/src/lib/wiki.js re-exports them: one home).
 
@@ -14,6 +14,19 @@ 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);
 export const fmtDate = (d) => (d ? format(toDate(d), "MMM d, yyyy") : "—");
+export const ago = (d) => (d ? formatDistanceToNowStrict(toDate(d), { addSuffix: true }) : "never");
+
+/** Whole seconds as "45s", "5m", "1h 30m", "2d 1h". A missing value is "unknown", never 0 or blank. */
+export const fmtDuration = (s) => {
+  if (s === null || s === undefined || !Number.isFinite(s) || s < 0) return "unknown";
+  if (s < 60) return `${Math.floor(s)}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return m % 60 ? `${h}h ${m % 60}m` : `${h}h`;
+  const d = Math.floor(h / 24);
+  return h % 24 ? `${d}d ${h % 24}h` : `${d}d`;
+};
 /** A feature's index summary: the trimmed string, or null when absent or blank (nothing is drawn for null). */
 export const summaryOf = (feature) => (typeof feature?.summary === "string" && feature.summary.trim() ? feature.summary.trim() : null);
 

package/src/parts/FreshnessBadge.jsx

@@ -0,0 +1,15 @@
+import React from "react";
+import useNow from "../useNow";
+import { ago, toDate } from "../lib";
+
+export default function FreshnessBadge({ at }) {
+  const now = useNow(30000);
+  const mins = at ? (now - toDate(at).getTime()) / 60000 : Infinity;
+  const tone = mins < 10 ? "bg-emerald-50 text-emerald-700 border-emerald-200" : mins < 60 ? "bg-amber-50 text-amber-700 border-amber-200" : "bg-red-50 text-red-700 border-red-200";
+  const dot = mins < 10 ? "bg-emerald-500" : mins < 60 ? "bg-amber-500" : "bg-red-500";
+  return (
+    <span className={`inline-flex items-center gap-1.5 whitespace-nowrap rounded-full border px-2 py-0.5 text-[11px] font-medium ${tone}`}>
+      <span className={`h-1.5 w-1.5 rounded-full ${dot}`} />{ago(at)}
+    </span>
+  );
+}

package/src/parts/OverdueBadge.jsx

@@ -0,0 +1,9 @@
+import React from "react";
+
+/** overdue: true = past its freshness line, false = within it, null/undefined = unknown (never shown as "on time"). */
+export default function OverdueBadge({ overdue }) {
+  const [tone, label] = overdue === true ? ["bg-red-50 text-red-700 border-red-200", "overdue"]
+    : overdue === false ? ["bg-emerald-50 text-emerald-700 border-emerald-200", "on time"]
+    : ["bg-neutral-50 text-neutral-500 border-neutral-200", "unknown"];
+  return <span className={`inline-flex whitespace-nowrap rounded-full border px-2 py-0.5 text-[11px] font-medium ${tone}`}>{label}</span>;
+}

package/src/useNow.js

@@ -0,0 +1,7 @@
+import { useEffect, useState } from "react";
+
+export default function useNow(ms = 30000) {
+  const [now, setNow] = useState(Date.now());
+  useEffect(() => { const t = setInterval(() => setNow(Date.now()), ms); return () => clearInterval(t); }, [ms]);
+  return now;
+}