@stigmer/react 3.4.0 → 3.5.0

package/src/sidebar/__tests__/SettingsSidebar.test.tsx

@@ -0,0 +1,107 @@
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { createRouterTransport } from "@connectrpc/connect";
+import { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { OrgProvider } from "../../organization/OrgProvider";
+import { SETTINGS_NAV_GROUPS } from "../../settings/settings-nav";
+import { SettingsSidebar } from "../SettingsSidebar";
+import type { RenderSidebarLink } from "../types";
+
+vi.mock("../../portal-container", () => ({
+  useStigmerPortalContainer: () => document.body,
+}));
+
+beforeAll(() => {
+  if (!("ResizeObserver" in globalThis)) {
+    (globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver =
+      class {
+        observe() {}
+        unobserve() {}
+        disconnect() {}
+      };
+  }
+});
+
+afterEach(cleanup);
+
+const renderAnchor: RenderSidebarLink = ({
+  id,
+  href,
+  className,
+  children,
+  "aria-current": ariaCurrent,
+}) => (
+  <a href={href} data-row-id={id} aria-current={ariaCurrent} className={className}>
+    {children}
+  </a>
+);
+
+function renderSidebar(ui: ReactNode) {
+  // No RPCs registered: the org switcher degrades gracefully, which is not
+  // this suite's subject (covered by WorkspaceSidebar's transport test).
+  const client = new Stigmer({
+    baseUrl: "/",
+    getAccessToken: () => "test-token",
+    customTransport: createRouterTransport(() => {}),
+  });
+  return render(
+    <StigmerContext.Provider value={client}>
+      <OrgProvider>{ui}</OrgProvider>
+    </StigmerContext.Provider>,
+  );
+}
+
+function baseProps() {
+  return {
+    groups: SETTINGS_NAV_GROUPS,
+    renderLink: renderAnchor,
+    footer: <span data-testid="footer-slot">footer</span>,
+  };
+}
+
+describe("SettingsSidebar", () => {
+  it("renders every group heading and item from the nav model", () => {
+    const { container } = renderSidebar(<SettingsSidebar {...baseProps()} />);
+
+    for (const group of SETTINGS_NAV_GROUPS) {
+      expect(screen.getByText(group.label)).toBeTruthy();
+      for (const item of group.items) {
+        const basename = item.href.slice(item.href.lastIndexOf("/") + 1);
+        const row = container.querySelector(`[data-row-id="${basename}"]`);
+        expect(row?.getAttribute("href")).toBe(item.href);
+      }
+    }
+  });
+
+  it("matches the active row by exact path or subpath, never by sibling prefix", () => {
+    const { container } = renderSidebar(
+      <SettingsSidebar {...baseProps()} activePath="/settings/api-keys/rotate" />,
+    );
+
+    const active = container.querySelector('[data-row-id="api-keys"]')!;
+    expect(active.getAttribute("aria-current")).toBe("page");
+    expect(active.className).toContain("bg-sidebar-accent");
+
+    // "/settings/api-keys/rotate" must not light up e.g. "/settings/members".
+    const inactive = container.querySelector('[data-row-id="members"]')!;
+    expect(inactive.getAttribute("aria-current")).toBeNull();
+  });
+
+  it("renders Back to Sessions as a muted exit row targeting backHref", () => {
+    const { container } = renderSidebar(
+      <SettingsSidebar {...baseProps()} backHref="/sessions/ses_123" />,
+    );
+
+    const back = container.querySelector('[data-row-id="back-to-sessions"]')!;
+    expect(back.getAttribute("href")).toBe("/sessions/ses_123");
+    expect(back.className).toContain("text-sidebar-muted-foreground");
+    expect(back.textContent).toContain("Back to Sessions");
+  });
+
+  it("renders the footer slot", () => {
+    renderSidebar(<SettingsSidebar {...baseProps()} />);
+    expect(screen.getByTestId("footer-slot")).toBeTruthy();
+  });
+});

package/src/sidebar/__tests__/WorkspaceSidebar.test.tsx

@@ -0,0 +1,236 @@
+import { describe, it, expect, vi, beforeAll, afterEach } from "vitest";
+import { render, screen, cleanup, within } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import { createRouterTransport } from "@connectrpc/connect";
+import { Stigmer } from "@stigmer/sdk";
+import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+import { OrganizationQueryController } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/query_pb";
+import { OrganizationsSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/io_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { StigmerContext } from "../../context";
+import { OrgProvider } from "../../organization/OrgProvider";
+import { WorkspaceSidebar } from "../WorkspaceSidebar";
+import type { RecentActivityEntry } from "../../activity/types";
+import type { RenderSidebarLink } from "../types";
+
+// Tooltips and the org switcher menu portal their content; without a
+// StigmerProvider the portal container is null — pin it to document.body
+// like sibling tests.
+vi.mock("../../portal-container", () => ({
+  useStigmerPortalContainer: () => document.body,
+}));
+
+beforeAll(() => {
+  // happy-dom lacks ResizeObserver, which Base UI positioners observe.
+  if (!("ResizeObserver" in globalThis)) {
+    (globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver =
+      class {
+        observe() {}
+        unobserve() {}
+        disconnect() {}
+      };
+  }
+});
+
+afterEach(cleanup);
+
+/** Frozen reference instant — fixtures must never read the real clock. */
+const NOW = new Date("2026-07-20T11:00:00Z");
+
+const hoursAgo = (h: number) => new Date(NOW.getTime() - h * 3_600_000);
+
+const ENTRIES: readonly RecentActivityEntry[] = [
+  {
+    id: "ses_today",
+    type: "session",
+    subject: "Draft email copy for the Q3 launch",
+    updatedAt: hoursAgo(2),
+  },
+  {
+    id: "wex_yesterday",
+    type: "workflow_execution",
+    subject: "Nightly refund sweep",
+    updatedAt: hoursAgo(26),
+    status: "failed",
+  },
+];
+
+/**
+ * The default consumer seam under test: an anchor per row, tagged with the
+ * row id so assertions can address rows the way real consumers do.
+ */
+const renderAnchor: RenderSidebarLink = ({
+  id,
+  href,
+  className,
+  children,
+  "aria-current": ariaCurrent,
+}) => (
+  <a href={href} data-row-id={id} aria-current={ariaCurrent} className={className}>
+    {children}
+  </a>
+);
+
+function renderSidebar(ui: ReactNode) {
+  const client = new Stigmer({
+    baseUrl: "/",
+    getAccessToken: () => "test-token",
+    customTransport: createRouterTransport((router) => {
+      router.service(OrganizationQueryController, {
+        findMyOrganizations: () =>
+          create(OrganizationsSchema, {
+            entries: [
+              create(OrganizationSchema, {
+                metadata: create(ApiResourceMetadataSchema, {
+                  id: "org_acme",
+                  slug: "acme",
+                  name: "Acme Corp",
+                }),
+              }),
+            ],
+          }),
+      });
+    }),
+  });
+  return render(
+    <StigmerContext.Provider value={client}>
+      <OrgProvider>{ui}</OrgProvider>
+    </StigmerContext.Provider>,
+  );
+}
+
+function baseProps() {
+  return {
+    renderLink: renderAnchor,
+    recentActivity: { entries: ENTRIES },
+    footer: <span data-testid="footer-slot">footer</span>,
+    now: NOW,
+  };
+}
+
+describe("WorkspaceSidebar — primary navigation", () => {
+  it("renders the three primary rows through renderLink with stable ids and hrefs", () => {
+    const { container } = renderSidebar(<WorkspaceSidebar {...baseProps()} />);
+
+    const row = (id: string) =>
+      container.querySelector<HTMLAnchorElement>(`[data-row-id="${id}"]`);
+    expect(row("new-session")?.getAttribute("href")).toBe("/");
+    expect(row("dashboard")?.getAttribute("href")).toBe("/dashboard");
+    expect(row("library")?.getAttribute("href")).toBe("/library");
+  });
+
+  it("marks only the active row with aria-current and the accent classes", () => {
+    const { container } = renderSidebar(
+      <WorkspaceSidebar {...baseProps()} activeNav="library" />,
+    );
+
+    const library = container.querySelector('[data-row-id="library"]')!;
+    expect(library.getAttribute("aria-current")).toBe("page");
+    expect(library.className.split(" ")).toContain("bg-sidebar-accent");
+
+    const dashboard = container.querySelector('[data-row-id="dashboard"]')!;
+    expect(dashboard.getAttribute("aria-current")).toBeNull();
+    // (hover:bg-sidebar-accent is fine — only the resting accent means active)
+    expect(dashboard.className.split(" ")).not.toContain("bg-sidebar-accent");
+  });
+});
+
+describe("WorkspaceSidebar — recents", () => {
+  it("buckets entries against the frozen `now`, never the live clock", () => {
+    renderSidebar(<WorkspaceSidebar {...baseProps()} />);
+
+    // 2h ago is Today; 26h ago is Yesterday — only under the frozen NOW.
+    expect(screen.getByText("Today")).toBeTruthy();
+    expect(screen.getByText("Yesterday")).toBeTruthy();
+    expect(screen.getByText("2h")).toBeTruthy();
+  });
+
+  it("passes the entry to renderLink and derives the viewer route from its type", () => {
+    const seen: Record<string, string> = {};
+    const spyLink: RenderSidebarLink = (props) => {
+      if (props.entry) seen[props.entry.id] = props.href;
+      return renderAnchor(props);
+    };
+
+    renderSidebar(<WorkspaceSidebar {...baseProps()} renderLink={spyLink} />);
+
+    expect(seen).toEqual({
+      ses_today: "/sessions/ses_today",
+      wex_yesterday: "/executions/wex_yesterday",
+    });
+  });
+
+  it("highlights the active session row and renders the status badge", () => {
+    const { container } = renderSidebar(
+      <WorkspaceSidebar {...baseProps()} activeSessionId="ses_today" />,
+    );
+
+    const active = container.querySelector('[data-row-id="ses_today"]')!;
+    expect(active.className).toContain("bg-sidebar-accent");
+    expect(active.getAttribute("aria-current")).toBe("page");
+    // The failed execution row explains why it is in the list.
+    const failed = container.querySelector('[data-row-id="wex_yesterday"]')!;
+    expect(within(failed as HTMLElement).getByText("failed")).toBeTruthy();
+  });
+
+  it("renders the per-entry accessory inside its row", () => {
+    const { container } = renderSidebar(
+      <WorkspaceSidebar
+        {...baseProps()}
+        renderEntryAccessory={(entry) =>
+          entry.id === "ses_today" ? <span data-testid="run-dot" /> : null
+        }
+      />,
+    );
+
+    const row = container.querySelector('[data-row-id="ses_today"]')!;
+    expect(within(row as HTMLElement).getByTestId("run-dot")).toBeTruthy();
+  });
+});
+
+describe("WorkspaceSidebar — fetch states", () => {
+  it("shows skeletons while loading", () => {
+    renderSidebar(
+      <WorkspaceSidebar
+        {...baseProps()}
+        recentActivity={{ entries: [], isLoading: true }}
+      />,
+    );
+    expect(screen.getByLabelText("Loading sessions")).toBeTruthy();
+  });
+
+  it("shows the error alert plus the empty state on failure", () => {
+    renderSidebar(
+      <WorkspaceSidebar
+        {...baseProps()}
+        recentActivity={{ entries: [], error: { message: "backend down" } }}
+      />,
+    );
+    expect(screen.getByRole("alert").textContent).toBe("backend down");
+    expect(screen.getByText("No recent activity")).toBeTruthy();
+  });
+
+  it("shows the empty state when there are no entries", () => {
+    renderSidebar(
+      <WorkspaceSidebar {...baseProps()} recentActivity={{ entries: [] }} />,
+    );
+    expect(screen.getByText("No recent activity")).toBeTruthy();
+  });
+});
+
+describe("WorkspaceSidebar — chrome", () => {
+  it("renders the footer slot and the collapse toggle with aria state", () => {
+    renderSidebar(<WorkspaceSidebar {...baseProps()} isOpen={false} />);
+
+    expect(screen.getByTestId("footer-slot")).toBeTruthy();
+    const toggle = screen.getByLabelText("Collapse sidebar");
+    expect(toggle.getAttribute("aria-expanded")).toBe("false");
+    expect(toggle.getAttribute("aria-controls")).toBe("sidebar");
+  });
+
+  it("resolves the org switcher from the mocked transport", async () => {
+    renderSidebar(<WorkspaceSidebar {...baseProps()} />);
+    expect(await screen.findByText("Acme Corp")).toBeTruthy();
+  });
+});

package/src/sidebar/chrome.tsx

@@ -0,0 +1,129 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { PanelLeft } from "lucide-react";
+import { cn } from "@stigmer/theme";
+import type { Organization } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
+import { OrgSwitcher } from "../organization/OrgSwitcher.js";
+
+// ---------------------------------------------------------------------------
+// Shared sidebar chrome — the pieces WorkspaceSidebar and SettingsSidebar
+// have in common: the nav container, the top row (collapse toggle + org
+// switcher), the hairline separator, the footer band, and the one nav-row
+// class recipe. Internal to the sidebar domain; not exported from the SDK.
+//
+// Every class here is transcribed from the console's sidebars — this file
+// IS the console's chrome now, so a change here changes the console, the
+// desktop app, and every documentation tour in one place.
+// ---------------------------------------------------------------------------
+
+/** Props shared by both sidebar variants' outer chrome. */
+export interface SidebarChromeProps {
+  /** Accessible name for the `<nav>` landmark. */
+  readonly ariaLabel: string;
+  /**
+   * Whether the sidebar is currently expanded, reflected as
+   * `aria-expanded` on the collapse toggle. @default true
+   */
+  readonly isOpen?: boolean;
+  /**
+   * Called when the collapse toggle is pressed. The sidebar renders the
+   * toggle either way (it is part of the depicted chrome); hosts that
+   * cannot collapse (fixed embeds) simply omit the handler.
+   */
+  readonly onCollapse?: () => void;
+  /** Passed through to {@link OrgSwitcher}. */
+  readonly onOrgChanged?: (org: Organization) => void;
+  /**
+   * Footer content — typically the host app's `UserMenu` wrapper, which
+   * bridges auth, theming, and routing. A slot rather than a built-in
+   * because every host wires those systems differently (DD-004).
+   */
+  readonly footer: ReactNode;
+  readonly children: ReactNode;
+}
+
+/**
+ * Outer sidebar frame: `<nav>` container, top row, content, footer band.
+ *
+ * The `id="sidebar"` / `aria-controls` pairing matches the console's DOM
+ * contract (the app shell's floating "Open sidebar" button targets it);
+ * only one sidebar renders at a time, so the id cannot collide.
+ */
+export function SidebarChrome({
+  ariaLabel,
+  isOpen = true,
+  onCollapse,
+  onOrgChanged,
+  footer,
+  children,
+}: SidebarChromeProps) {
+  return (
+    <nav
+      id="sidebar"
+      aria-label={ariaLabel}
+      className="bg-sidebar text-sidebar-foreground flex h-full flex-col"
+    >
+      {/* Top row: collapse toggle + org context */}
+      <div className="flex flex-none items-center gap-1 px-2 py-2">
+        <button
+          type="button"
+          onClick={onCollapse}
+          aria-expanded={isOpen}
+          aria-controls="sidebar"
+          aria-label="Collapse sidebar"
+          className={cn(
+            "inline-flex size-7 shrink-0 items-center justify-center rounded-md",
+            "text-sidebar-foreground transition-colors motion-reduce:transition-none",
+            "hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
+            "aria-expanded:bg-sidebar-accent aria-expanded:text-sidebar-accent-foreground",
+            "focus-visible:ring-sidebar-ring focus-visible:ring-2 focus-visible:outline-none",
+          )}
+        >
+          <PanelLeft className="size-4" />
+        </button>
+        <div className="min-w-0 flex-1">
+          <OrgSwitcher onOrgChanged={onOrgChanged} />
+        </div>
+      </div>
+
+      {children}
+
+      {/* Bottom: user menu */}
+      <div className="border-sidebar-border flex-none border-t px-3 py-2">
+        {footer}
+      </div>
+    </nav>
+  );
+}
+
+/** Hairline separator between sidebar sections. */
+export function SidebarSeparator() {
+  return (
+    <div className="px-3 py-1">
+      <div className="bg-sidebar-border h-px" />
+    </div>
+  );
+}
+
+/**
+ * The one nav-row class recipe both sidebars share: 14px medium labels,
+ * 16px icons (sized by callers), 8px/6px padding, rounded row highlight.
+ *
+ * `muted` renders the resting label in the muted sidebar tone — used by
+ * "Back to Sessions", which is an exit, not a destination.
+ */
+export function navRowClassName(
+  active: boolean,
+  { muted = false }: { muted?: boolean } = {},
+): string {
+  return cn(
+    "flex items-center gap-2 rounded-lg px-2 py-1.5 text-sm font-medium transition-colors",
+    active
+      ? "bg-sidebar-accent text-sidebar-accent-foreground"
+      : cn(
+          muted ? "text-sidebar-muted-foreground" : "text-sidebar-foreground",
+          "hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
+        ),
+  );
+}

package/src/sidebar/index.ts

@@ -0,0 +1,16 @@
+// Sidebar — the console's navigation chrome as shared SDK components.
+//
+// One source of truth for the sidebar the web console, desktop app, and
+// documentation tours all render (stigmer/stigmer#317): hosts inject their
+// router via `renderLink`, their data via props, and their user menu via
+// the `footer` slot.
+
+export { WorkspaceSidebar } from "./WorkspaceSidebar.js";
+export type {
+  WorkspaceSidebarProps,
+  WorkspaceSidebarActivity,
+  WorkspaceNavId,
+} from "./WorkspaceSidebar.js";
+export { SettingsSidebar } from "./SettingsSidebar.js";
+export type { SettingsSidebarProps } from "./SettingsSidebar.js";
+export type { SidebarLinkRenderProps, RenderSidebarLink } from "./types.js";

package/src/sidebar/types.ts

@@ -0,0 +1,55 @@
+import type { ReactElement, ReactNode } from "react";
+import type { RecentActivityEntry } from "../activity/types.js";
+
+/**
+ * Everything a sidebar hands to {@link RenderSidebarLink} to draw one
+ * interactive row.
+ *
+ * The sidebar owns the row's look (`className`, `children`) and state
+ * (`active`, `aria-current`); the consumer owns only the interactive
+ * element wrapping them. That split is what keeps one component serving
+ * three very different hosts: the web console returns `next/link`, the
+ * desktop app returns a `react-router` link, and documentation embeds
+ * return inert rows decorated with capture markers.
+ */
+export interface SidebarLinkRenderProps {
+  /**
+   * Stable row identifier, for consumers that vary behavior per row:
+   * `"new-session"` / `"dashboard"` / `"library"` in the workspace
+   * sidebar, `"back-to-sessions"` or the settings route basename (e.g.
+   * `"api-keys"`) in the settings sidebar, and the entry id for recent
+   * activity rows.
+   */
+  readonly id: string;
+  /** Console route this row targets (e.g. `/library`, `/sessions/<id>`). */
+  readonly href: string;
+  /** Whether the row is the current location. */
+  readonly active: boolean;
+  /**
+   * Fully-styled row classes computed by the sidebar. Apply verbatim —
+   * the row's geometry and type scale are the product surface tours and
+   * embeds depict, so consumers must not restyle them.
+   */
+  readonly className: string;
+  /** `"page"` when active, for assistive tech. Spread onto the element. */
+  readonly "aria-current": "page" | undefined;
+  /** Row content (icon, label, timestamps). Render inside the element. */
+  readonly children: ReactNode;
+  /**
+   * The recent-activity entry behind this row. Present only for recents
+   * rows in the workspace sidebar — consumers use it to pick the right
+   * navigation flow (session viewer vs. execution viewer) without
+   * parsing `href`.
+   */
+  readonly entry?: RecentActivityEntry;
+}
+
+/**
+ * Renders one sidebar row as the consumer's interactive element.
+ *
+ * Must return a single element that spreads unknown props onto its
+ * underlying DOM node (all DOM elements, `next/link`, and `react-router`
+ * links qualify): the sidebar composes tooltip triggers around recents
+ * rows by cloning the returned element with merged event handlers.
+ */
+export type RenderSidebarLink = (props: SidebarLinkRenderProps) => ReactElement;

package/src/skill/useSkillCount.ts

@@ -17,6 +17,8 @@ export interface UseSkillCountOptions {
    * @default "org"
    */
   readonly scope?: ResourceListScope;
+  /** Opaque token that forces a recount when its value changes. */
+  readonly refetchToken?: unknown;
 }
 
 /** Return value of {@link useSkillCount}. */