@anchrd/intel-ui 0.6.0 → 0.7.2

package/src/folder-contents/folder-contents.tsx

@@ -0,0 +1,106 @@
+import { useQuery } from "@tanstack/react-query";
+import { useNavigate } from "@tanstack/react-router";
+import { treeLevelKey } from "@/app/tree-move/tree-move.tsx";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@/components/ui/table.tsx";
+import type { TreeEntry } from "@/data/intel-data-provider/intel-data-provider.types.ts";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+
+const icons: Record<TreeEntry["kind"], string> = {
+  folder: "knowledge.kind.folder",
+  document: "knowledge.kind.document",
+  attachment: "knowledge.kind.attachment",
+  table: "knowledge.kind.table",
+  flow: "knowledge.kind.flow",
+};
+
+/**
+ * A folder's own screen: what lies directly in it, as a table.
+ *
+ * ⚠️ It reads the SAME query the sidebar reads for the same folder — `treeLevelKey`, filled by
+ * `listTreeChildren`. Not a second call and not a second cache entry: two readers of one folder that
+ * fetch separately show it differently the moment one of them is stale, and that is the kind of
+ * difference a customer finds before anybody here does. The other half of the bargain is free —
+ * every invalidation the tree already does after a create, a move or an archive lands here too.
+ */
+export function FolderContents({ folderId }: { folderId: string }) {
+  const { data, i18n } = useIntelRouterContext();
+  const navigate = useNavigate();
+  const level = useQuery({
+    queryKey: treeLevelKey(folderId),
+    queryFn: () => data.listTreeChildren(folderId),
+  });
+
+  if (level.isPending) {
+    return <p className="p-6 text-sm text-muted-foreground">{i18n.t("common.loading")}</p>;
+  }
+  if (level.isError) {
+    return (
+      <p role="alert" className="p-6 text-sm text-destructive">
+        {i18n.t("knowledge.folderFailed")}
+      </p>
+    );
+  }
+
+  const entries = level.data ?? [];
+  // ⚠️ An empty folder keeps a sentence, unlike an empty row in the tree (#59). A folder IS this
+  // screen: a blank rectangle leaves someone who just created it with nowhere to go, which is the
+  // same reason `tree.empty` survives at the root.
+  if (entries.length === 0) {
+    return (
+      <div className="grid flex-1 place-items-center p-8 text-sm text-muted-foreground">
+        {i18n.t("knowledge.folderEmpty")}
+      </div>
+    );
+  }
+
+  return (
+    <div className="min-h-0 flex-1 overflow-y-auto p-4">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>{i18n.t("common.title")}</TableHead>
+            <TableHead>{i18n.t("knowledge.kind")}</TableHead>
+            <TableHead>{i18n.t("knowledge.changed")}</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {entries.map((entry) => {
+            const changed = entry.type === "flow" ? entry.flow.updatedAt : entry.node.updatedAt;
+            return (
+              <TableRow key={entry.id}>
+                {/* ⚠️ The button carries the whole cell rather than the cell carrying an onClick.
+                    A row that only reacts to a mouse is a row nobody can reach with a keyboard, and
+                    a `<tr onClick>` has no name to read out either. */}
+                <TableCell className="p-0">
+                  <button
+                    type="button"
+                    onClick={() =>
+                      void navigate({
+                        to: entry.type === "flow" ? "/flows" : "/knowledge",
+                        search: { select: entry.id },
+                      })
+                    }
+                    className="w-full px-2 py-2 text-left outline-none hover:underline focus-visible:ring-2 focus-visible:ring-ring"
+                  >
+                    {entry.title}
+                  </button>
+                </TableCell>
+                <TableCell className="text-muted-foreground">{i18n.t(icons[entry.kind])}</TableCell>
+                <TableCell className="text-muted-foreground">
+                  {new Date(changed).toLocaleDateString()}
+                </TableCell>
+              </TableRow>
+            );
+          })}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}

package/src/i18n/en.json

@@ -84,11 +84,15 @@
   "knowledge.table.empty": "No rows yet. Rows are appended by flows and agents.",
   "knowledge.table.undefined": "This table has no columns yet.",
   "knowledge.select": "Select a document or folder to work with it.",
-  "knowledge.folderHelp": "Select a child document, or create something inside this folder.",
-  "knowledge.contextPolicy": "AI context policy",
-  "knowledge.context.pinned": "Pinned in scope",
-  "knowledge.context.relevant": "Load when relevant",
-  "knowledge.context.explicit": "Only when referenced",
+  "knowledge.folderEmpty": "Nothing in this folder yet. Create something with the plus in the sidebar.",
+  "knowledge.folderFailed": "This folder could not be read.",
+  "knowledge.kind": "Kind",
+  "knowledge.changed": "Changed",
+  "knowledge.kind.folder": "Folder",
+  "knowledge.kind.document": "Document",
+  "knowledge.kind.attachment": "Upload",
+  "knowledge.kind.table": "Table",
+  "knowledge.kind.flow": "Flow",
   "knowledge.share": "Share",
   "knowledge.shareAction": "Grant access",
   "knowledge.email": "Email address",
@@ -116,7 +120,6 @@
   "view.showEditor": "Back to the editor",
   "view.showRuns": "Show this flow's runs",
   "view.graph": "Relation graph",
-  "view.graphDescription": "{nodes} nodes and {edges} relationships you are allowed to see.",
   "view.graphTruncated": "{omitted} more left out — this view draws at most {limit}.",
   "view.graphEmpty": "Nothing here that you may see.",
   "view.graphFailed": "The graph could not be loaded.",
@@ -158,25 +161,40 @@
   "flows.publish": "Publish",
   "flows.publishNothing": "Nothing new to publish",
   "flows.publishNeeded": "Publish — no run can start until you do",
-  "flows.run": "Start run",
-  "flows.runStarted": "Durable run started",
+  "flows.validate": "Check whether it would run",
+  "flows.validateReady": "This flow would start now.",
+  "flows.validateWhen": "Checked {when}. Tool access is asked with your own token each time, so this answer is a snapshot.",
+  "flows.problem.flow_execute_forbidden": "You may not run this flow",
+  "flows.problem.flow_not_published": "The flow is not published",
+  "flows.problem.flow_graph_invalid": "The graph cannot be run",
+  "flows.problem.flow_tools_unavailable": "A tool is out of reach",
+  "flows.problem.flow_knowledge_forbidden": "Material a step reads is out of reach",
+  "flows.problem.flow_subflow_unavailable": "A called flow is unavailable",
+  "flows.problem.flow_subflow_not_published": "A called flow is not published",
   "flows.addNode": "Add a step",
   "flows.closePalette": "Close the step bar",
   "flows.nodePalette": "Step types",
   "flows.node.trigger": "Start",
   "flows.startExists": "A flow has exactly one start, and this one already has it.",
   "flows.node.instruction": "Instruction",
-  "flows.node.knowledge": "Knowledge",
+  "flows.node.folder": "Folder",
+  "flows.node.document": "Document",
+  "flows.node.upload": "Upload",
+  "flows.node.table": "Table",
   "flows.node.tool": "Tool",
   "flows.node.condition": "Condition",
-  "flows.node.approval": "Approval",
-  "flows.node.subflow": "Sub-flow",
-  "flows.node.output": "Output",
+  "flows.node.subflow": "Flow",
+  "flows.node.output": "End",
   "flows.instruction": "Instruction for the AI or person",
   "flows.instructionHint": "Conditions, checks and branches can be described here in words. You do not need a separate node for every small decision.",
-  "flows.knowledgeIds": "Knowledge references",
-  "flows.knowledgeEmpty": "Create a knowledge item before adding this step.",
-  "flows.knowledgeQuery": "Semantic retrieval hint",
+  "flows.linkEmpty": "Nothing chosen yet",
+  "picker.search": "Search by name",
+  "picker.top": "All folders",
+  "picker.open": "Open {title}",
+  "picker.nothing": "Nothing here",
+  "flows.layer.marker": "Markers",
+  "flows.layer.step": "Steps",
+  "flows.layer.link": "Links",
   "flows.subflowTarget": "Flow to call",
   "flows.selectSubflow": "Select a flow to call",
   "flows.subflowRule": "A flow may call a flow in its own folder or below it, or one in a folder every user may run. Publishing names the reason if it may not.",

package/src/knowledge/knowledge.tsx

@@ -6,6 +6,7 @@ import { lazy, Suspense, useState } from "react";
 import { ActionSlot } from "@/app/action-slot/action-slot.tsx";
 import { ViewToggle } from "@/app/view-toggle/view-toggle.tsx";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
+import { FolderContents } from "@/folder-contents/folder-contents.tsx";
 import { GraphPane } from "@/graph-pane/graph-pane.tsx";
 import { KnowledgeTablePanel } from "@/knowledge-table/knowledge-table.tsx";
 import { useIntelRouterContext } from "@/router/router-context.ts";
@@ -135,9 +136,7 @@ export function Knowledge() {
                 }
               />
             ) : selected.kind === "folder" ? (
-              <div className="grid flex-1 place-items-center p-8 text-sm text-muted-foreground">
-                {i18n.t("knowledge.folderHelp")}
-              </div>
+              <FolderContents folderId={selected.id} />
             ) : selected.kind === "attachment" ? (
               <AttachmentPanel node={selected} />
             ) : selected.kind === "table" ? (

package/src/knowledge-graph/graph-notice.tsx

@@ -0,0 +1,21 @@
+import type { RelationGraph } from "@anchrd/intel-contract";
+import type { I18n } from "@/i18n/i18n.types.ts";
+
+/**
+ * The one line above a graph, and it appears only when there is something to say (#88).
+ *
+ * ⚠️ It counted what was drawn directly below it — "3 nodes and 0 relationships you are allowed to
+ * see" — permanently, above every graph. Three nodes are three nodes; the reader sees them. What
+ * they cannot see is what the view stopped short of, and that is what stayed.
+ *
+ * Its own file because `knowledge-graph.tsx` pulls Sigma in at module level, and Sigma needs WebGL:
+ * a case about this line could not render there at all.
+ */
+export function GraphNotice({ data, i18n }: { data: RelationGraph; i18n: I18n }) {
+  if (data.omitted === 0) return null;
+  return (
+    <p className="border-b px-6 py-3 text-sm text-muted-foreground">
+      {i18n.t("view.graphTruncated", { omitted: data.omitted, limit: data.limit })}
+    </p>
+  );
+}

package/src/knowledge-graph/knowledge-graph.tsx

@@ -3,6 +3,7 @@ import { ControlsContainer, SigmaContainer, useCamera, useRegisterEvents } from
 import { LocateFixed, Minus, Plus } from "lucide-react";
 import { useEffect, useMemo } from "react";
 import type { I18n } from "@/i18n/i18n.types.ts";
+import { GraphNotice } from "./graph-notice.tsx";
 import { createRelationGraph, resolveGraphColor } from "./knowledge-graph.ts";
 
 function labelColors() {
@@ -77,16 +78,7 @@ export function RelationGraphView({
   const byId = useMemo(() => new Map(data.nodes.map((node) => [node.id, node])), [data.nodes]);
   return (
     <section aria-label={i18n.t("view.graph")} className="flex min-h-0 flex-1 flex-col">
-      <p className="border-b px-6 py-3 text-sm text-muted-foreground">
-        {i18n.t("view.graphDescription", { nodes: data.nodes.length, edges: data.edges.length })}
-        {/* ⚠️ The cut-off is said out loud. A graph that quietly stopped drawing would read as "this
-            folder holds nothing else", which is worse than a graph that admits it is partial. */}
-        {data.omitted > 0 ? (
-          <span className="ml-2 rounded-md border px-2 py-0.5 text-xs">
-            {i18n.t("view.graphTruncated", { omitted: data.omitted, limit: data.limit })}
-          </span>
-        ) : null}
-      </p>
+      <GraphNotice data={data} i18n={i18n} />
       <div className="min-h-0 flex-1 bg-muted/20">
         {data.nodes.length === 0 ? (
           <div className="grid h-full place-items-center p-8 text-sm text-muted-foreground">

package/src/resource-menu/resource-menu.tsx

@@ -1,13 +1,22 @@
 import type {
-  ContextPolicy,
   Flow,
+  FlowValidation,
   KnowledgeNode,
   ResourceVerb,
   UnreadableKnowledge,
 } from "@anchrd/intel-contract";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useNavigate, useRouterState } from "@tanstack/react-router";
-import { Archive, CornerLeftUp, Ellipsis, Link2, Pencil, Share2, Trash2 } from "lucide-react";
+import {
+  Archive,
+  CornerLeftUp,
+  Ellipsis,
+  Link2,
+  Pencil,
+  Share2,
+  ShieldCheck,
+  Trash2,
+} from "lucide-react";
 import type * as React from "react";
 import { useState } from "react";
 import { moveErrorKey, useTreeMove } from "@/app/tree-move/tree-move.tsx";
@@ -15,12 +24,7 @@ import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
-  DropdownMenuRadioGroup,
-  DropdownMenuRadioItem,
   DropdownMenuSeparator,
-  DropdownMenuSub,
-  DropdownMenuSubContent,
-  DropdownMenuSubTrigger,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { flowEntry } from "@/data/intel-data-provider/intel-data-provider.ts";
@@ -93,8 +97,6 @@ export function resourceErrorKey(error: unknown): string {
   }
 }
 
-const contextPolicies: readonly ContextPolicy[] = ["pinned", "relevant", "explicit"];
-
 /**
  * The three-dot menu.
  *
@@ -122,6 +124,14 @@ export function ResourceMenu({
   // the name. #27 gave moving a second, equal route through a folder picker, and that route lived in
   // the tree row's menu. With the row menu gone (#58) it lives here, or it does not exist.
   const move = useTreeMove();
+  // ⚠️ Not a query. A validation is a snapshot taken when somebody asks (#72, ADR-0003): cached
+  // under a key it would be re-served later as if it still held, and the one thing it must never
+  // claim is that a moment which has passed is still true.
+  const [validation, setValidation] = useState<FlowValidation | null>(null);
+  const validate = useMutation({
+    mutationFn: () => data.validateFlow(id),
+    onSuccess: setValidation,
+  });
 
   const id = idOf(target);
   const title = titleOf(target);
@@ -192,26 +202,11 @@ export function ResourceMenu({
     },
   });
 
-  const setContextPolicy = useMutation({
-    mutationFn: async (contextPolicy: ContextPolicy) => {
-      if (target.type === "flow") throw new Error("A flow has no retrieval mode");
-      await data.updateKnowledge({
-        nodeId: target.node.id,
-        baseUpdatedAt: target.node.updatedAt,
-        contextPolicy,
-        idempotencyKey: crypto.randomUUID(),
-      });
-    },
-    onSuccess: refresh,
-  });
-
   const failure = rename.isError
     ? null // the rename dialog words its own refusal, beside the field that caused it
     : archive.isError
       ? archive.error
-      : setContextPolicy.isError
-        ? setContextPolicy.error
-        : undefined;
+      : undefined;
 
   return (
     <>
@@ -236,27 +231,15 @@ export function ResourceMenu({
             <CornerLeftUp aria-hidden="true" />
             {i18n.t("tree.move.action")}
           </DropdownMenuItem>
-          {retrievable || linkable || node ? <DropdownMenuSeparator /> : null}
-          {/* ⚠️ A submenu with a checked value, not an embedded `select`. A form control inside a
-              menu takes the keyboard away from the menu that contains it, and the current value is
-              then only readable by opening a second widget. */}
-          {retrievable && node ? (
-            <DropdownMenuSub>
-              <DropdownMenuSubTrigger>{i18n.t("knowledge.contextPolicy")}</DropdownMenuSubTrigger>
-              <DropdownMenuSubContent>
-                <DropdownMenuRadioGroup
-                  value={node.contextPolicy}
-                  onValueChange={(value) => setContextPolicy.mutate(value as ContextPolicy)}
-                >
-                  {contextPolicies.map((policy) => (
-                    <DropdownMenuRadioItem key={policy} value={policy}>
-                      {i18n.t(`knowledge.context.${policy}`)}
-                    </DropdownMenuRadioItem>
-                  ))}
-                </DropdownMenuRadioGroup>
-              </DropdownMenuSubContent>
-            </DropdownMenuSub>
+          {/* Only a flow can be run, so only a flow can be asked whether it would. Rarely needed —
+              which is why it is in the menu and not in the title line (#72). */}
+          {node === null ? (
+            <DropdownMenuItem onSelect={() => validate.mutate()}>
+              <ShieldCheck aria-hidden="true" />
+              {i18n.t("flows.validate")}
+            </DropdownMenuItem>
           ) : null}
+          {retrievable || linkable || node ? <DropdownMenuSeparator /> : null}
           {linkable ? (
             <DropdownMenuItem onSelect={() => setLinksOpen(true)}>
               <Link2 aria-hidden="true" />
@@ -295,6 +278,33 @@ export function ResourceMenu({
           `resourceErrorKey`: "that is not a folder" and "that would be a loop" have no equivalent
           among the changes above, and one shared sentence would leave the reader guessing. */}
       {move.error ? <MenuFailure>{i18n.t(moveErrorKey(move.error))}</MenuFailure> : null}
+      {/* ⚠️ Every reason at once, not the first one. Somebody with two missing tools should not have
+          to ask twice — and a success says so out loud, because an empty menu after a click reads
+          as "nothing happened" rather than "nothing is in the way". */}
+      {validation ? (
+        <Modal title={i18n.t("flows.validate")} close={() => setValidation(null)}>
+          {validation.problems.length === 0 ? (
+            <p className="text-sm">{i18n.t("flows.validateReady")}</p>
+          ) : (
+            <ul className="space-y-2">
+              {validation.problems.map((problem) => (
+                <li key={problem.code} className="rounded-md border p-3 text-sm">
+                  <span className="block font-medium">
+                    {i18n.t(`flows.problem.${problem.code}`)}
+                  </span>
+                  <span className="mt-1 block text-xs text-muted-foreground">{problem.detail}</span>
+                </li>
+              ))}
+            </ul>
+          )}
+          {/* A snapshot says when it was taken, or it will be read as a standing verdict. */}
+          <p className="mt-4 text-xs text-muted-foreground">
+            {i18n.t("flows.validateWhen", {
+              when: new Date(validation.checkedAt).toLocaleString(),
+            })}
+          </p>
+        </Modal>
+      ) : null}
       {move.dialog}
       {renaming ? (
         <RenameDialog