Files
kandev/apps/web/src/spa-routes.plugin.test.tsx
T
João Salavisa adad46fab1 feat(plugins): richer frontend SDK — page chrome, nav icons, more host UI (#1759)
* feat(plugins): richer frontend SDK — page chrome, nav icons, more host UI

Give native UI plugins the primitives to render kandev-native pages while
keeping everything configurable:

- registerRoute gains an options arg; plugin routes get a first-party
  PageTopbar title bar by default (title/icon derived from the nav item for
  the same path, or set via { topbar: { title, subtitle, icon, backHref,
  backLabel, actions } }). Pass { topbar: false } to render full-bleed and
  own the chrome.
- NavItem.icon now resolves against a curated name map (lib/plugins/icons.ts);
  unknown/missing names fall back to the puzzle glyph.
- host.ui expands to the primitives a native-feeling page needs (Dialog,
  DropdownMenu, Pagination, Sheet, Select, Tabs, Table, Tooltip, ...) plus
  first-party PageTopbar, Combobox, and TaskCreateDialog. Plugins must use
  these host instances — a bundled second copy of any Radix/portal component
  splits React context.
- host.navigate(href, { replace? }) for soft SPA navigation into native
  routes, and host.api.baseUrl for reaching first-party REST without
  re-deriving the split-origin backend URL.

The registry records each plugin's display name for derived titles and
getRoutes() entries now carry pluginId + options. Contract doc
(PLUGIN-API.md) updated to match.

* fix(plugins): expose full Sheet subcomponent family on host.ui

host.ui advertised Sheet but only exposed Sheet/Content/Header/Title, so
plugins (which must use host instances for portal/context components)
couldn't build an uncontrolled sheet — no Trigger/Close/Footer/Description.
Add the missing four for parity with the Dialog family.

* fix(plugins): clear plugin display name on unregisterPlugin

unregisterPlugin bulk-revoked every other registration but left the entry
in pluginNames, so getPluginName returned a stale name after disable and
names leaked across enable/disable cycles. Delete the name too, with a
regression test.

---------

Co-authored-by: Kandev Agent <agent@kandev.dev>
2026-07-17 18:10:49 +01:00

127 lines
3.9 KiB
TypeScript

import { cleanup, render, screen } from "@testing-library/react";
import { afterEach, describe, expect, it, vi } from "vitest";
import { StateProvider } from "@/components/state-provider";
import { pluginRegistry } from "@/lib/plugins/registry";
import { resolveSpaRoute, SpaRoutes } from "./spa-routes";
const PLUGIN_ID = "plugin-a";
const PLUGIN_PATH = "/plugins/hello";
function cleanupPlugins(...pluginIds: string[]) {
pluginIds.forEach((id) => pluginRegistry.unregisterPlugin(id));
}
describe("resolveSpaRoute — plugin fallthrough", () => {
afterEach(() => cleanupPlugins(PLUGIN_ID));
it("falls back to the kanban route when no plugin owns the path", () => {
expect(resolveSpaRoute("/plugins/hello", new URLSearchParams())).toEqual({
kind: "kanban",
workspaceId: undefined,
workflowId: undefined,
taskId: undefined,
sessionId: undefined,
});
});
it("resolves to the plugin route once a plugin registers the path", () => {
function HelloPage() {
return null;
}
pluginRegistry.forPlugin(PLUGIN_ID).registerRoute(PLUGIN_PATH, HelloPage);
expect(resolveSpaRoute(PLUGIN_PATH, new URLSearchParams())).toEqual({
kind: "plugin",
path: PLUGIN_PATH,
});
});
it("does not shadow a first-class static route with the same-looking plugin path", () => {
function TasksOverride() {
return null;
}
pluginRegistry.forPlugin(PLUGIN_ID).registerRoute("/tasks", TasksOverride);
expect(resolveSpaRoute("/tasks", new URLSearchParams())).toEqual({ kind: "tasks" });
});
});
describe("SpaRoutes — plugin route rendering", () => {
afterEach(() => {
cleanup();
cleanupPlugins(PLUGIN_ID);
window.history.pushState({}, "", "/");
});
it("renders the registered plugin component inside the app shell for a matching path", () => {
function HelloPage() {
return <div data-testid="plugin-hello-page">Hello from plugin</div>;
}
pluginRegistry.forPlugin(PLUGIN_ID).registerRoute(PLUGIN_PATH, HelloPage);
window.history.pushState({}, "", PLUGIN_PATH);
render(
<StateProvider>
<SpaRoutes />
</StateProvider>,
);
expect(screen.getByTestId("plugin-hello-page")).not.toBeNull();
});
it("wraps a plugin route in the kandev title bar by default", () => {
function HelloPage() {
return <div data-testid="plugin-hello-page" />;
}
pluginRegistry.forPlugin(PLUGIN_ID, "Hello Plugin").registerRoute(PLUGIN_PATH, HelloPage);
window.history.pushState({}, "", PLUGIN_PATH);
render(
<StateProvider>
<SpaRoutes />
</StateProvider>,
);
expect(screen.getByRole("banner")).not.toBeNull();
expect(screen.getByText("Hello Plugin")).not.toBeNull();
expect(screen.getByTestId("plugin-hello-page")).not.toBeNull();
});
it("renders the route full-bleed when it opts out via topbar: false", () => {
function HelloPage() {
return <div data-testid="plugin-hello-page" />;
}
pluginRegistry
.forPlugin(PLUGIN_ID, "Hello Plugin")
.registerRoute(PLUGIN_PATH, HelloPage, { topbar: false });
window.history.pushState({}, "", PLUGIN_PATH);
render(
<StateProvider>
<SpaRoutes />
</StateProvider>,
);
expect(screen.queryByRole("banner")).toBeNull();
expect(screen.getByTestId("plugin-hello-page")).not.toBeNull();
});
it("renders a fallback instead of white-screening when the plugin route component throws", () => {
const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
function ThrowingPage(): never {
throw new Error("boom");
}
pluginRegistry.forPlugin(PLUGIN_ID).registerRoute(PLUGIN_PATH, ThrowingPage);
window.history.pushState({}, "", PLUGIN_PATH);
render(
<StateProvider>
<SpaRoutes />
</StateProvider>,
);
expect(screen.getByText(/this plugin page failed to load/i)).not.toBeNull();
errorSpy.mockRestore();
});
});