Add the module navigation contract: manifest v9, module routes, return-to-origin
Stage 1 PR 7 (ADR 0063). A module becomes a first-class part of the Dashboard. - Manifest v9 = v8 plus optional `navigation`: a Lucide icon from the curated MODULE_NAVIGATION_ICONS set, and up to 12 primary pages (stable id, safe label, kebab-case path relative to the module root; no traversal, schemes, queries, duplicates, or nesting). Validated before activation. - Version 8 stays accepted beside version 9, each read strictly as itself (discriminated union); no released manifest is rewritten. The template moves to v9; the released Signage 0.1.5 manifest is a test fixture. - Real module routes: /<id> is the landing view, /<id>/<page> a declared page, anything beneath a page a module-owned detail route; anything else is not-found and mounts nothing. api/assets/display are never pages. - Sidebar: declared icons, pages nested under an open module, one aria-current, collapsed and drawer behaviour; v8 modules unchanged. - module-ui-sdk: ModuleUiHostContext.navigation (location, subscribe, navigate, link, settings), refusing anything outside the module's routes; undefined on the display host. Mount ABI unchanged. - Return-to-origin: one `?return=` carrier on Settings URLs, validated by parseReturnTarget and against running modules' declared routes; Settings Back returns to exactly the originating module page, across refreshes. Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
ekklesia
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
7447381c8f
commit
4671622b9d
@@ -43,7 +43,13 @@ import {
|
||||
DashboardHostConfigurationError,
|
||||
createDashboardHostRoutes,
|
||||
} from "../src/dashboard-host-routes.js";
|
||||
import { DASHBOARD_PLATFORM_PAGES, SETTINGS_SECTIONS } from "@ekklesia/shell/dashboard-routes";
|
||||
import { MODULE_NAVIGATION_ICONS } from "@ekklesia/contracts";
|
||||
import {
|
||||
DASHBOARD_PLATFORM_PAGES,
|
||||
HOST_NAMESPACES,
|
||||
SETTINGS_SECTIONS,
|
||||
} from "@ekklesia/shell/dashboard-routes";
|
||||
import { DASHBOARD_MODULE_ICON_NAMES } from "@ekklesia/shell/module-icons";
|
||||
import {
|
||||
MODULE_DISPLAY_DESCRIPTOR_PREFIX,
|
||||
MODULE_DISPLAY_PAGE_PREFIX,
|
||||
@@ -417,6 +423,14 @@ describe("the platform's reserved top-level names (ADR 0057)", () => {
|
||||
}
|
||||
});
|
||||
|
||||
it("are exactly the Dashboard's platform pages plus the host namespaces it never treats as pages (ADR 0063)", () => {
|
||||
// With module routes nested beneath `/<module-id>/`, the shell must know every other top-level
|
||||
// name: `/api/v1/principal` must never read as the route `v1/principal` of a module called `api`.
|
||||
expect([...DASHBOARD_PLATFORM_PAGES, ...HOST_NAMESPACES].sort()).toEqual([
|
||||
...RESERVED_TOP_LEVEL_NAMES,
|
||||
]);
|
||||
});
|
||||
|
||||
it("include exactly the Settings sections the shell interprets, so /settings/<module-id> never collides (ADR 0061)", () => {
|
||||
expect([...SETTINGS_SECTIONS].sort()).toEqual([...RESERVED_SETTINGS_NAMES]);
|
||||
for (const section of SETTINGS_SECTIONS) {
|
||||
@@ -630,3 +644,10 @@ describe("Dashboard host boundaries", () => {
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("module navigation icons (ADR 0063)", () => {
|
||||
it("are the same set in the manifest contract and in the Dashboard that draws them", () => {
|
||||
// The platform cannot accept an icon the Dashboard cannot draw, nor draw one it would refuse.
|
||||
expect([...DASHBOARD_MODULE_ICON_NAMES]).toEqual([...MODULE_NAVIGATION_ICONS]);
|
||||
});
|
||||
});
|
||||
|
||||
@@ -55,6 +55,8 @@ interface ModuleFixture {
|
||||
readonly id: string;
|
||||
readonly name: string;
|
||||
readonly withUi?: boolean;
|
||||
/** Present, the fixture is a manifest v9 module declaring this navigation (ADR 0063). */
|
||||
readonly navigation?: unknown;
|
||||
}
|
||||
|
||||
async function createModule(modulesDirectory: string, fixture: ModuleFixture): Promise<void> {
|
||||
@@ -78,8 +80,9 @@ async function createModule(modulesDirectory: string, fixture: ModuleFixture): P
|
||||
...(fixture.withUi === false ? {} : { ui: "./dist/ui/index.js" }),
|
||||
},
|
||||
id: fixture.id,
|
||||
manifestVersion: 8,
|
||||
manifestVersion: fixture.navigation === undefined ? 8 : 9,
|
||||
name: fixture.name,
|
||||
...(fixture.navigation === undefined ? {} : { navigation: fixture.navigation }),
|
||||
version: "1.0.0",
|
||||
}),
|
||||
);
|
||||
@@ -170,6 +173,14 @@ function signedIn(): EkklesiaPrincipal {
|
||||
|
||||
interface NavigationEntry {
|
||||
readonly name: string;
|
||||
readonly navigation: {
|
||||
readonly icon: string | null;
|
||||
readonly pages: readonly {
|
||||
readonly id: string;
|
||||
readonly label: string;
|
||||
readonly path: string;
|
||||
}[];
|
||||
};
|
||||
readonly module: {
|
||||
readonly id: string;
|
||||
readonly version: string;
|
||||
@@ -284,7 +295,68 @@ describe("Dashboard navigation — reading", () => {
|
||||
ui: { url: "/api/v1/module-ui/livestream/1.0.0" },
|
||||
version: "1.0.0",
|
||||
});
|
||||
expect(Object.keys(livestream ?? {}).sort()).toEqual(["module", "name"]);
|
||||
expect(Object.keys(livestream ?? {}).sort()).toEqual(["module", "name", "navigation"]);
|
||||
// A module that declares no navigation — this manifest v8 fixture — is drawn with the generic
|
||||
// icon and has its root as its only page (ADR 0063). Never a group or an order.
|
||||
expect(livestream?.navigation).toEqual({ icon: null, pages: [] });
|
||||
});
|
||||
|
||||
it("carries a manifest v9 module's own icon and pages beside its descriptor, in declared order", async () => {
|
||||
const { app } = await install({
|
||||
fixtures: [
|
||||
{
|
||||
id: "signage",
|
||||
name: "Signage",
|
||||
navigation: {
|
||||
icon: "monitor-play",
|
||||
pages: [
|
||||
{ id: "playback", label: "Playback", path: "playback" },
|
||||
{ id: "timelines", label: "Timelines", path: "timelines" },
|
||||
{ id: "media", label: "Media", path: "media" },
|
||||
],
|
||||
},
|
||||
},
|
||||
{ id: "calendar", name: "Calendar" },
|
||||
],
|
||||
principal: signedIn(),
|
||||
});
|
||||
|
||||
const navigation = await navigationOf(app);
|
||||
const signage = navigation.ungrouped.find((entry) => entry.module.id === "signage");
|
||||
const calendar = navigation.ungrouped.find((entry) => entry.module.id === "calendar");
|
||||
|
||||
expect(signage?.navigation).toEqual({
|
||||
icon: "monitor-play",
|
||||
pages: [
|
||||
{ id: "playback", label: "Playback", path: "playback" },
|
||||
{ id: "timelines", label: "Timelines", path: "timelines" },
|
||||
{ id: "media", label: "Media", path: "media" },
|
||||
],
|
||||
});
|
||||
// The host-neutral descriptor is untouched by navigation: it lives beside it, never inside.
|
||||
expect(Object.keys(signage?.module ?? {}).sort()).toEqual(
|
||||
Object.keys(calendar?.module ?? {}).sort(),
|
||||
);
|
||||
// A manifest v8 module beside it keeps the generic icon and its single root page.
|
||||
expect(calendar?.navigation).toEqual({ icon: null, pages: [] });
|
||||
});
|
||||
|
||||
it("refuses at discovery a v9 module whose navigation is unsafe, so it never reaches the sidebar", async () => {
|
||||
const { app } = await install({
|
||||
fixtures: [
|
||||
{ id: "calendar", name: "Calendar" },
|
||||
{
|
||||
id: "escape",
|
||||
name: "Escape",
|
||||
navigation: { pages: [{ id: "out", label: "Out", path: "../settings" }] },
|
||||
},
|
||||
],
|
||||
principal: signedIn(),
|
||||
}).catch((error: unknown) => ({ app: undefined, error }));
|
||||
|
||||
// Discovery is atomic (ADR 0005): an invalid manifest fails the whole inventory rather than
|
||||
// quietly dropping one module, exactly as for any other manifest error.
|
||||
expect(app).toBeUndefined();
|
||||
});
|
||||
|
||||
it("agrees exactly with the generic inventory about what is mountable", async () => {
|
||||
|
||||
@@ -479,6 +479,7 @@ describe("end to end: a discovered module's UI mounts in the Ekklesia host", ()
|
||||
"contributions",
|
||||
"display",
|
||||
"moduleId",
|
||||
"navigation",
|
||||
"permissions",
|
||||
"principal",
|
||||
"realtime",
|
||||
|
||||
@@ -953,6 +953,7 @@ describe("module UI artifact publication — the generic loader consumes what is
|
||||
contributions: NO_MODULE_UI_CONTRIBUTIONS,
|
||||
display: undefined,
|
||||
moduleId: "announcements",
|
||||
navigation: undefined,
|
||||
permissions: { has: () => false },
|
||||
principal: { kind: "anonymous" as const },
|
||||
realtime: { subscribe: () => ({ close: () => undefined }) },
|
||||
|
||||
Reference in New Issue
Block a user