@anchrd/intel-ui 0.3.0 → 0.5.0

package/src/document-link/document-link.tsx

@@ -0,0 +1,132 @@
+import { DocumentLinkInlineType } from "@anchrd/intel-contract";
+import { BlockNoteSchema } from "@blocknote/core";
+import { createReactInlineContentSpec } from "@blocknote/react";
+import { FileText, Link2Off } from "lucide-react";
+import { createContext, useContext } from "react";
+
+/**
+ * What a document link resolves to for the person reading it.
+ *
+ * ⚠️ `titles` holds only the documents this reader may see. A missing entry is the whole answer for
+ * both of the reasons an entry can be missing — the target is gone, or it is not theirs to reach —
+ * and nothing here may ever be given a way to tell those apart. `pending` exists so the editor can
+ * hold back the difference between "not resolved yet" and "does not resolve", which would otherwise
+ * flash a broken link at every reader for one render.
+ */
+export interface DocumentLinkResolution {
+  titles: ReadonlyMap<string, string>;
+  pending: boolean;
+  // The one word an unresolved link says. It travels in the context because a BlockNote inline
+  // element is rendered by the editor rather than by a view that could reach the i18n catalog.
+  unresolvedLabel: string;
+}
+
+const DocumentLinkContext = createContext<DocumentLinkResolution>({
+  titles: new Map(),
+  pending: false,
+  unresolvedLabel: "Unavailable document",
+});
+
+export const DocumentLinkProvider = DocumentLinkContext.Provider;
+
+export function useDocumentLinkResolution(): DocumentLinkResolution {
+  return useContext(DocumentLinkContext);
+}
+
+/**
+ * One document link inside the text (#41).
+ *
+ * ⚠️ The element stores the target's ID and nothing else. A stored title would be wrong the moment
+ * the target is renamed and a stored path the moment it is moved — and both would put a name into a
+ * document that any reader of it could then read, whether or not they may reach the target.
+ *
+ * ⚠️ An unresolved link says that it does not resolve and nothing more: no title, no path, no ID on
+ * screen, no hint of which of the two reasons applies. That is the whole of the leak this feature
+ * could have introduced, and the reason the broken form carries no data at all.
+ */
+export function DocumentLinkText({ nodeId }: { nodeId: string }) {
+  const { titles, pending, unresolvedLabel } = useDocumentLinkResolution();
+  const title = titles.get(nodeId);
+  if (title === undefined) {
+    return (
+      <span
+        data-document-link={pending ? "pending" : "unresolved"}
+        className={
+          pending
+            ? "inline-flex items-center gap-1 rounded-sm px-1 text-muted-foreground"
+            : "inline-flex items-center gap-1 rounded-sm bg-destructive/10 px-1 text-destructive line-through"
+        }
+      >
+        {pending ? null : <Link2Off aria-hidden="true" className="size-3.5" />}
+        {pending ? "…" : unresolvedLabel}
+      </span>
+    );
+  }
+  return (
+    <span
+      data-document-link="resolved"
+      data-node-id={nodeId}
+      className="inline-flex items-center gap-1 rounded-sm bg-muted px-1 text-foreground"
+    >
+      <FileText aria-hidden="true" className="size-3.5" />
+      {title}
+    </span>
+  );
+}
+
+export const documentLinkSpec = createReactInlineContentSpec(
+  {
+    type: DocumentLinkInlineType,
+    propSchema: { nodeId: { default: "" } },
+    // The link has no editable text of its own: what it reads is the target's title, and a title
+    // somebody could type over would stop following the target the first time they did (#41).
+    content: "none",
+  },
+  {
+    render: (props) => <DocumentLinkText nodeId={String(props.inlineContent.props.nodeId)} />,
+  },
+);
+
+// One schema for the editor and for everything that reads its documents back: BlockNote's defaults
+// plus the one inline element #41 adds.
+//
+// ⚠️ `extend` rather than `create({ inlineContentSpecs: { ...defaults, documentLink } })`. Both
+// build the same schema at run time, but only `extend` keeps the added type in the schema's own
+// generics under this repo's `exactOptionalPropertyTypes` — with the spread form the editor infers
+// BlockNote's default schema, typechecks, and then refuses to insert a document link.
+export const intelEditorSchema = BlockNoteSchema.create().extend({
+  inlineContentSpecs: { documentLink: documentLinkSpec },
+});
+
+// The schema carries its own editor and block types as declaration-only properties, which is the
+// only way to name them here: writing `BlockNoteEditor<typeof schema.blockSchema, ...>` by hand
+// fails BlockNote's own constraint under `exactOptionalPropertyTypes`.
+export type IntelEditor = (typeof intelEditorSchema)["BlockNoteEditor"];
+export type IntelEditorPartialBlock = (typeof intelEditorSchema)["PartialBlock"];
+
+/**
+ * The IDs a stored BlockNote document links to.
+ *
+ * The server reads the same thing out of the same content when the document is saved; this side
+ * needs it too, to ask which of them it may show a title for.
+ */
+export function documentLinkIds(blocks: unknown): string[] {
+  const found = new Set<string>();
+  const walk = (value: unknown): void => {
+    if (Array.isArray(value)) {
+      for (const entry of value) walk(entry);
+      return;
+    }
+    if (typeof value !== "object" || value === null) return;
+    const record = value as Record<string, unknown>;
+    if (record.type === DocumentLinkInlineType) {
+      const props = record.props as Record<string, unknown> | undefined;
+      const nodeId = props?.nodeId;
+      if (typeof nodeId === "string" && nodeId.length > 0) found.add(nodeId);
+    }
+    walk(record.content);
+    walk(record.children);
+  };
+  walk(blocks);
+  return [...found];
+}

package/src/flow-runs/flow-runs.tsx

@@ -0,0 +1,225 @@
+import type { FlowRunSummary } from "@anchrd/intel-contract";
+import { useInfiniteQuery, useQuery } from "@tanstack/react-query";
+import { ChevronDown, ChevronRight, CornerDownRight } from "lucide-react";
+import { useState } from "react";
+import type { I18n } from "@/i18n/i18n.types.ts";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+
+// One page is what a person reads before deciding, not what a database can return. The server caps
+// it at fifty; twenty is what fits on a screen without scrolling past the answer.
+const PageSize = 20;
+
+function formatDuration(ms: number, i18n: I18n): string {
+  if (ms < 1_000) return i18n.t("runs.durationMs", { value: ms });
+  if (ms < 60_000) return i18n.t("runs.durationSeconds", { value: (ms / 1_000).toFixed(1) });
+  return i18n.t("runs.durationMinutes", { value: Math.round(ms / 60_000) });
+}
+
+/**
+ * The third view of the flow screen: what this flow has done (#35).
+ *
+ * **A view, not a dialog.** Comparing runs and looking things up is what fault-finding is, and that
+ * needs the room and the working memory of a whole surface — a modal would block everything else on
+ * the screen while doing exactly the task that needs the rest of it. So it joins the switch #19
+ * already built rather than opening somewhere new.
+ *
+ * ⚠️ What it shows is what a run *did*. Neither the input a run was given nor the result it
+ * produced is in the answer it reads, because a run reaches Knowledge and tools with the rights of
+ * whoever started it — and the person reading this list is not necessarily that person.
+ */
+export function FlowRuns({ flowId }: { flowId: string }) {
+  const { data, i18n } = useIntelRouterContext();
+  const [failedOnly, setFailedOnly] = useState(false);
+  const [openRunId, setOpenRunId] = useState<string | null>(null);
+  // The filter belongs in the key: "only the failed ones" is a different question with a different
+  // answer, and reusing one cache entry for both would show the wrong one for a frame.
+  const runs = useInfiniteQuery({
+    queryKey: ["flow-runs", flowId, failedOnly],
+    queryFn: ({ pageParam }) =>
+      data.listFlowRuns({ flowId, failedOnly, limit: PageSize, cursor: pageParam }),
+    initialPageParam: null as string | null,
+    getNextPageParam: (last) => last.nextCursor,
+  });
+  const items = runs.data?.pages.flatMap((page) => page.items) ?? [];
+
+  return (
+    <section aria-label={i18n.t("runs.title")} className="flex min-h-0 flex-1 flex-col">
+      <div className="flex items-center gap-3 border-b px-5 py-3">
+        <h2 className="text-sm font-semibold">{i18n.t("runs.title")}</h2>
+        {/* The one filter. Everything beyond it is a report rather than a search for a fault. */}
+        <label className="ml-auto flex cursor-pointer items-center gap-2 text-sm">
+          <input
+            type="checkbox"
+            checked={failedOnly}
+            onChange={(event) => {
+              setFailedOnly(event.target.checked);
+              setOpenRunId(null);
+            }}
+            className="size-4 accent-primary"
+          />
+          {i18n.t("runs.onlyFailed")}
+        </label>
+      </div>
+      <div className="min-h-0 flex-1 overflow-y-auto p-5">
+        {runs.isPending && (
+          <p className="text-sm text-muted-foreground">{i18n.t("common.loading")}</p>
+        )}
+        {runs.isError && (
+          <div role="alert" className="space-y-3 text-sm">
+            <p className="text-destructive">{i18n.t("runs.failedToLoad")}</p>
+            <button
+              type="button"
+              onClick={() => void runs.refetch()}
+              className="rounded-md border px-3 py-2 outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              {i18n.t("common.retry")}
+            </button>
+          </div>
+        )}
+        {/* ⚠️ Two different answers, kept apart: this flow has never run, and this flow has never
+            failed. Saying the first when the filter is on would be wrong for exactly the person who
+            came here worried. */}
+        {runs.data && items.length === 0 && (
+          <p className="text-sm text-muted-foreground">
+            {i18n.t(failedOnly ? "runs.emptyFailed" : "runs.empty")}
+          </p>
+        )}
+        {items.length > 0 && (
+          <ul className="space-y-2">
+            {items.map((run) => (
+              <RunRow
+                key={run.id}
+                run={run}
+                open={openRunId === run.id}
+                toggle={() => setOpenRunId(openRunId === run.id ? null : run.id)}
+              />
+            ))}
+          </ul>
+        )}
+        {runs.hasNextPage && (
+          <button
+            type="button"
+            onClick={() => void runs.fetchNextPage()}
+            disabled={runs.isFetchingNextPage}
+            className="mt-4 rounded-md border px-3 py-2 text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+          >
+            {runs.isFetchingNextPage ? i18n.t("common.loading") : i18n.t("runs.more")}
+          </button>
+        )}
+      </div>
+    </section>
+  );
+}
+
+function RunRow({ run, open, toggle }: { run: FlowRunSummary; open: boolean; toggle(): void }) {
+  const { i18n } = useIntelRouterContext();
+  const failed = run.status === "failed";
+  const Chevron = open ? ChevronDown : ChevronRight;
+  return (
+    <li className="rounded-lg border bg-card">
+      <button
+        type="button"
+        onClick={toggle}
+        aria-expanded={open}
+        className="flex w-full items-start gap-3 rounded-lg px-4 py-3 text-left outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+      >
+        <Chevron aria-hidden="true" className="mt-0.5 size-4 shrink-0 text-muted-foreground" />
+        <span className="min-w-0 flex-1">
+          <span className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm">
+            <span
+              className={`rounded-full border px-2 py-0.5 text-xs ${failed ? "border-destructive/40 text-destructive" : "text-muted-foreground"}`}
+            >
+              {i18n.t(`runs.status.${run.status}`)}
+            </span>
+            <span>{new Date(run.startedAt).toLocaleString(i18n.locale)}</span>
+            <span className="text-muted-foreground">
+              {run.durationMs === null
+                ? i18n.t("runs.stillRunning")
+                : formatDuration(run.durationMs, i18n)}
+            </span>
+            <span className="text-muted-foreground">{i18n.t(`runs.trigger.${run.trigger}`)}</span>
+          </span>
+          {/* The step that ended it, in the words the failure itself used. The list does not
+              summarize them into "failed" — that is the sentence #20 replaced. */}
+          {run.failure && (
+            <span className="mt-1.5 block text-sm text-destructive">
+              <span className="font-medium">
+                {i18n.t("runs.failedAt", { step: run.failure.nodeLabel })}
+              </span>{" "}
+              {run.failure.detail}
+            </span>
+          )}
+        </span>
+      </button>
+      {open && <RunSteps runId={run.id} />}
+    </li>
+  );
+}
+
+// The drill-down: every step this run took, in order. The failed node is reported rather than drawn
+// onto the canvas because a run took an immutable version and the editor shows the current one —
+// marking a node in the wrong graph would point confidently at the wrong step.
+function RunSteps({ runId }: { runId: string }) {
+  const { data, i18n } = useIntelRouterContext();
+  const history = useQuery({
+    queryKey: ["flow-run-steps", runId],
+    queryFn: () => data.getFlowRunSteps(runId),
+  });
+  return (
+    <div className="border-t px-4 py-3">
+      {history.isPending && (
+        <p className="text-sm text-muted-foreground">{i18n.t("common.loading")}</p>
+      )}
+      {history.isError && (
+        <p role="alert" className="text-sm text-destructive">
+          {i18n.t("runs.stepsFailedToLoad")}
+        </p>
+      )}
+      {history.data && (
+        <>
+          {/* Which step of which flow this run is, outermost caller first (#17). Only worth saying
+              when there is more than one link in the chain. */}
+          {history.data.trail.length > 1 && (
+            <p className="mb-3 flex flex-wrap items-center gap-1 text-xs text-muted-foreground">
+              {history.data.trail.map((entry, index) => (
+                <span key={entry.runId} className="flex items-center gap-1">
+                  {index > 0 && <CornerDownRight aria-hidden="true" className="size-3" />}
+                  <span>{entry.flowTitle}</span>
+                  {entry.nodeLabel && <span>· {entry.nodeLabel}</span>}
+                </span>
+              ))}
+            </p>
+          )}
+          {history.data.steps.length === 0 ? (
+            <p className="text-sm text-muted-foreground">{i18n.t("runs.stepsEmpty")}</p>
+          ) : (
+            <ol aria-label={i18n.t("runs.stepsTitle")} className="space-y-2">
+              {history.data.steps.map((step) => (
+                <li key={step.nodeId} className="text-sm">
+                  <span
+                    className={
+                      step.outcome === "failed" ? "font-medium text-destructive" : "font-medium"
+                    }
+                  >
+                    {step.nodeLabel}
+                  </span>
+                  <span className="ml-2 text-xs text-muted-foreground">
+                    {i18n.t(`runs.outcome.${step.outcome}`)}
+                    {step.branch ? ` · ${step.branch}` : ""}
+                  </span>
+                  {step.detail && (
+                    <span
+                      className={`mt-0.5 block text-xs ${step.outcome === "failed" ? "text-destructive" : "text-muted-foreground"}`}
+                    >
+                      {step.detail}
+                    </span>
+                  )}
+                </li>
+              ))}
+            </ol>
+          )}
+        </>
+      )}
+    </div>
+  );
+}