feat(knowledge-network): version picker by the title, readable comparisons and a danger zone

src/app/router/shell.tsx

@@ -11,6 +11,7 @@ import { useEffect, useState } from "react";
 import { SideNav } from "@/app/shell/SideNav";
 import { TopBar } from "@/app/shell/TopBar";
 import { WorkspaceLayout } from "@/app/shell/WorkspaceLayout";
+import { ShellTrailSlotProvider } from "@/app/shell/workspace-slots";
 import { LicenseStateBanner } from "@/framework/entitlement/LicenseStateBanner";
 
 const SIDENAV_COLLAPSED_STORAGE_KEY = "bkn-studio:sidenav-collapsed";
@@ -29,22 +30,24 @@ export function AppShell() {
   }, [sidenavCollapsed]);
 
   return (
-    <div className="console-shell">
-      <TopBar />
-      <LicenseStateBanner />
-      <div className={sidenavCollapsed ? "console-body is-sidenav-collapsed" : "console-body"}>
-        <SideNav
-          collapsed={sidenavCollapsed}
-          onToggleCollapsed={() => {
-            setSidenavCollapsed((current) => !current);
-          }}
-        />
-        <main className="console-main">
-          <WorkspaceLayout>
-            <Outlet />
-          </WorkspaceLayout>
-        </main>
+    <ShellTrailSlotProvider>
+      <div className="console-shell">
+        <TopBar />
+        <LicenseStateBanner />
+        <div className={sidenavCollapsed ? "console-body is-sidenav-collapsed" : "console-body"}>
+          <SideNav
+            collapsed={sidenavCollapsed}
+            onToggleCollapsed={() => {
+              setSidenavCollapsed((current) => !current);
+            }}
+          />
+          <main className="console-main">
+            <WorkspaceLayout>
+              <Outlet />
+            </WorkspaceLayout>
+          </main>
+        </div>
       </div>
-    </div>
+    </ShellTrailSlotProvider>
   );
 }

src/app/shell/TopBar.tsx

@@ -20,12 +20,13 @@ import {
 } from "@ant-design/icons";
 import { Badge, Modal } from "antd";
 import type { MenuProps } from "antd";
-import { useEffect, useMemo, useState } from "react";
+import { useContext, useEffect, useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { useLocation, useMatches, useNavigate, useParams } from "react-router-dom";
 
 import { getConsoleNavTrail } from "@/app/shell/console-navigation";
 import { UserPill } from "@/app/shell/UserPill";
+import { ShellTrailSlotContext } from "@/app/shell/workspace-slots-context";
 import { useResolvedTheme, useToggleTheme } from "@/app/theme/theme-context";
 import openBknLogo from "@/assets/brand/openbkn-logo-compact.webp";
 import type { AppRouteHandle } from "@/app/shell/route-meta";
@@ -49,6 +50,7 @@ import {
 
 export function TopBar() {
   const { t } = useTranslation();
+  const trailSlot = useContext(ShellTrailSlotContext);
   const location = useLocation();
   const matches = useMatches();
   const navigate = useNavigate();
@@ -367,6 +369,7 @@ export function TopBar() {
               ))}
             </div>
           ) : null}
+          <span className="console-brand-trail-slot" ref={trailSlot?.setTrailHost} />
         </div>
       </div>
 

src/app/shell/workspace-slots-context.ts

@@ -12,3 +12,11 @@ export type WorkspaceSlotsValue = {
 };
 
 export const WorkspaceSlotsContext = createContext<WorkspaceSlotsValue | null>(null);
+
+/** Where a page may add a small control right after the top bar's trail, such as a version picker. */
+export type ShellTrailSlotValue = {
+  setTrailHost: (host: HTMLSpanElement | null) => void;
+  trailHost: HTMLSpanElement | null;
+};
+
+export const ShellTrailSlotContext = createContext<ShellTrailSlotValue | null>(null);

src/app/shell/workspace-slots.tsx

@@ -6,11 +6,11 @@
  */
 
 import type { PropsWithChildren, ReactNode } from "react";
-import { useContext } from "react";
+import { useContext, useMemo, useState } from "react";
 
 import { createPortal } from "react-dom";
 
-import { WorkspaceSlotsContext } from "@/app/shell/workspace-slots-context";
+import { ShellTrailSlotContext, WorkspaceSlotsContext } from "@/app/shell/workspace-slots-context";
 
 export function WorkspaceToolbarPortal({
   children,
@@ -24,3 +24,27 @@ export function WorkspaceToolbarPortal({
 
   return createPortal(children, context.toolbarHost);
 }
+
+/** Renders after the top bar's trail; without a top bar it renders `fallback` in place. */
+export function ShellTrailPortal({
+  children,
+  fallback = null,
+}: PropsWithChildren<{ fallback?: ReactNode }>) {
+  const context = useContext(ShellTrailSlotContext);
+
+  if (!context?.trailHost) {
+    return <>{fallback}</>;
+  }
+
+  return createPortal(children, context.trailHost);
+}
+
+/**
+ * Lets a page add a control after the top bar's trail. Wrap both the TopBar and the page content
+ * in it; pages that render their own TopBar outside the console shell need it too.
+ */
+export function ShellTrailSlotProvider({ children }: PropsWithChildren) {
+  const [trailHost, setTrailHost] = useState<HTMLSpanElement | null>(null);
+  const value = useMemo(() => ({ setTrailHost, trailHost }), [trailHost]);
+  return <ShellTrailSlotContext.Provider value={value}>{children}</ShellTrailSlotContext.Provider>;
+}

src/modules/knowledge-network/components/versions/KnDiffModal.test.tsx

@@ -83,6 +83,20 @@ describe("KnDiffModal", () => {
     expect(diffVersions).toHaveBeenLastCalledWith("kn-1", 2, "draft");
   });
 
+  it("reads a pair picked newer-first from the older side", async () => {
+    diffVersions.mockResolvedValue({ changes: [] });
+    render(<KnDiffModal {...props} initialBase="running" initialTarget={2} open />);
+    await waitFor(() => expect(diffVersions).toHaveBeenCalledTimes(1));
+    expect(diffVersions).toHaveBeenLastCalledWith("kn-1", 2, "running");
+  });
+
+  it("puts the draft after any version", async () => {
+    diffVersions.mockResolvedValue({ changes: [] });
+    render(<KnDiffModal {...props} initialBase="draft" initialTarget={2} open />);
+    await waitFor(() => expect(diffVersions).toHaveBeenCalledTimes(1));
+    expect(diffVersions).toHaveBeenLastCalledWith("kn-1", 2, "draft");
+  });
+
   it("keeps the latest comparison when an earlier one answers last", async () => {
     let answerFirst: (value: KnDiffResult) => void = () => undefined;
     const first = { changes: [{ id: "old" }] } as unknown as KnDiffResult;

src/modules/knowledge-network/components/versions/KnDiffModal.tsx

@@ -15,7 +15,10 @@ import {
   useReadableKnVersions,
   versionOptionLabel,
 } from "@/modules/knowledge-network/components/versions/useReadableKnVersions";
-import { parseKnVersionView } from "@/modules/knowledge-network/lib/kn-version-format";
+import {
+  knVersionName,
+  parseKnVersionView,
+} from "@/modules/knowledge-network/lib/kn-version-format";
 import { diffKnVersions } from "@/modules/knowledge-network/services/kn-version.service";
 import type {
   KnDiffResult,
@@ -24,7 +27,7 @@ import type {
 } from "@/modules/knowledge-network/types/kn-version";
 
 type KnDiffModalProps = {
-  /** What to show on the left when the dialog opens. */
+  /** The pair to compare when the dialog opens; the older one ends up on the left. */
   initialBase?: KnVersionView;
   initialTarget?: KnVersionView;
   networkId: string;
@@ -73,7 +76,25 @@ export function KnDiffModal({
   const asValue = (view: KnVersionView) =>
     view === "running" ? String(versioning.running_version) : String(view);
 
-  const compare = (from: KnVersionView = base, to: KnVersionView = target) => {
+  const viewName = (view: KnVersionView) =>
+    view === "draft"
+      ? t("knowledgeNetwork.versions.draft")
+      : knVersionName(view === "running" ? versioning.running_version : view);
+
+  // Older first: the draft is newer than every version, and numbers grow with time.
+  const age = (view: KnVersionView) =>
+    view === "draft"
+      ? Number.POSITIVE_INFINITY
+      : view === "running"
+        ? versioning.running_version
+        : view;
+
+  // A comparison always reads from the older side to the newer one, so "added" means
+  // what the newer side has; a pair picked the other way round is turned around.
+  const compare = (picked: KnVersionView = base, other: KnVersionView = target) => {
+    const [from, to] = age(picked) > age(other) ? [other, picked] : [picked, other];
+    setBase(from);
+    setTarget(to);
     const request = ++latest.current;
     setLoading(true);
     setError(null);
@@ -102,10 +123,11 @@ export function KnDiffModal({
     if (!open) {
       return;
     }
-    setBase(initialBase);
-    setTarget(initialTarget);
     if (versioning.running_version > 0) {
       compare(initialBase, initialTarget);
+    } else {
+      setBase(initialBase);
+      setTarget(initialTarget);
     }
     // The selectors run it again on demand.
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -117,7 +139,7 @@ export function KnDiffModal({
       onCancel={onClose}
       open={open}
       title={t("knowledgeNetwork.versions.diff.title")}
-      width={720}
+      width={1040}
     >
       <Space style={{ marginBottom: 12 }} wrap>
         <Select
@@ -146,7 +168,13 @@ export function KnDiffModal({
           type="info"
         />
       ) : (
-        <KnDiffSummary error={error} loading={loading} result={result} />
+        <KnDiffSummary
+          baseLabel={viewName(base)}
+          error={error}
+          loading={loading}
+          result={result}
+          targetLabel={viewName(target)}
+        />
       )}
     </Modal>
   );