Ekklesia/surfaces/shell/tests/dashboard-routes.test.ts

// @vitest-environment node
import { readFile } from "node:fs/promises";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { describe, expect, it } from "vitest";
import {
  ACCOUNT_SECTIONS,
  DASHBOARD_PLATFORM_PAGES,
  dashboardPath,
  parseDashboardPath,
  DISCOVER_VIEWS,
  SETTINGS_SECTIONS,
} from "../src/dashboard-routes.js";

const packageDirectory = path.dirname(path.dirname(fileURLToPath(import.meta.url)));

describe("the Dashboard's own top-level pages", () => {
  it("are exactly Settings and Account, frozen", () => {
    expect(Object.isFrozen(DASHBOARD_PLATFORM_PAGES)).toBe(true);
    expect(DASHBOARD_PLATFORM_PAGES).toEqual(["settings", "account"]);
  });
});

describe("parseDashboardPath", () => {
  it("makes the root the Overview", () => {
    expect(parseDashboardPath("/")).toEqual({ kind: "overview" });
  });

  it("names a module page by its id at the top level, tolerating one trailing slash", () => {
    expect(parseDashboardPath("/signage")).toEqual({ kind: "module", moduleId: "signage" });
    expect(parseDashboardPath("/signage/")).toEqual({ kind: "module", moduleId: "signage" });
    expect(parseDashboardPath("/people")).toEqual({ kind: "module", moduleId: "people" });
  });

  it("decodes a percent-encoded segment, so an id is compared as the server spells it", () => {
    expect(parseDashboardPath("/sign%61ge")).toEqual({ kind: "module", moduleId: "signage" });
  });

  it("never reads a platform page as a module page", () => {
    expect(parseDashboardPath("/settings")).toEqual({ kind: "settings" });
    expect(parseDashboardPath("/account")).toEqual({ kind: "account" });
  });

  it("reads the account area: the account page and its personal settings pages (ADR 0062)", () => {
    expect(parseDashboardPath("/account")).toEqual({ kind: "account" });
    expect(parseDashboardPath("/account/")).toEqual({ kind: "account" });
    expect(parseDashboardPath("/account/appearance")).toEqual({
      kind: "account-section",
      section: "appearance",
    });
    expect(parseDashboardPath("/account/appearance/")).toEqual({
      kind: "account-section",
      section: "appearance",
    });
    expect(dashboardPath({ kind: "account" })).toBe("/account");
    expect(dashboardPath({ kind: "account-section", section: "appearance" })).toBe(
      "/account/appearance",
    );
    expect(ACCOUNT_SECTIONS).toEqual(["appearance"]);
    for (const pathname of [
      "/account/profile",
      "/account/appearance/extra",
      "/account/Appearance",
      "/account//appearance",
      "/accounts",
    ]) {
      expect(parseDashboardPath(pathname), pathname).toEqual(
        pathname === "/accounts" ? { kind: "module", moduleId: "accounts" } : { kind: "not-found" },
      );
    }
  });

  it("treats every other shape as not found rather than guessing", () => {
    for (const pathname of [
      "",
      "//",
      "//signage",
      "/signage//",
      // A module's own sub-pages need a contract that does not exist yet (ADR 0057).
      "/signage/timelines",
      "/signage/timelines/abc",
      "/%E0%A4%A",
      // Deeper Settings pages are reserved for later (ADR 0061).
      "/settings/displays/add",
      "/settings/signage/timelines",
      "/settings//signage",
      "signage",
    ]) {
      expect(parseDashboardPath(pathname), pathname).toEqual({ kind: "not-found" });
    }
  });
});

describe("Settings routes (ADR 0061)", () => {
  it("names exactly the platform's own Settings sections, frozen", () => {
    expect(Object.isFrozen(SETTINGS_SECTIONS)).toBe(true);
    expect(SETTINGS_SECTIONS).toEqual(["general", "branding", "displays", "discover", "system"]);
    expect(Object.isFrozen(DISCOVER_VIEWS)).toBe(true);
    expect(DISCOVER_VIEWS).toEqual(["browse", "installed", "updates"]);
  });

  it("has a landing page of its own, tolerating one trailing slash", () => {
    expect(parseDashboardPath("/settings")).toEqual({ kind: "settings" });
    expect(parseDashboardPath("/settings/")).toEqual({ kind: "settings" });
  });

  it("reads each platform section, and nothing else, as a platform section", () => {
    for (const section of ["general", "branding", "displays", "system"] as const) {
      expect(parseDashboardPath(`/settings/${section}`), section).toEqual({
        kind: "settings-section",
        section,
      });
    }
  });

  it("reads Discover's three views, entering Discover at Browse, its one canonical address", () => {
    for (const view of DISCOVER_VIEWS) {
      expect(parseDashboardPath(`/settings/discover/${view}`), view).toEqual({
        kind: "discover",
        view,
      });
    }
    // `/settings/discover` means Browse, and the shell respells it `/settings/discover/browse` in
    // place, so there is one meaningful Browse address rather than two.
    expect(parseDashboardPath("/settings/discover")).toEqual({ kind: "discover", view: "browse" });
    expect(dashboardPath({ kind: "discover", view: "browse" })).toBe("/settings/discover/browse");
    for (const pathname of [
      "/settings/discover/catalog",
      "/settings/discover/browse/signage",
      "/settings/discover//",
    ]) {
      expect(parseDashboardPath(pathname), pathname).toEqual({ kind: "not-found" });
    }
  });

  it("reads every other name as a module's settings — never under /settings/modules/", () => {
    expect(parseDashboardPath("/settings/signage")).toEqual({
      kind: "module-settings",
      moduleId: "signage",
    });
    expect(parseDashboardPath("/settings/sign%61ge/")).toEqual({
      kind: "module-settings",
      moduleId: "signage",
    });
    expect(parseDashboardPath("/settings/modules/signage")).toEqual({ kind: "not-found" });
    // `modules` is no longer a platform section, so it is simply a module id like any other.
    expect(parseDashboardPath("/settings/modules")).toEqual({
      kind: "module-settings",
      moduleId: "modules",
    });
  });

  it("spells each Settings destination canonically and round-trips it", () => {
    for (const [route, path] of [
      [{ kind: "settings" }, "/settings"],
      [{ kind: "settings-section", section: "displays" }, "/settings/displays"],
      [{ kind: "discover", view: "installed" }, "/settings/discover/installed"],
      [{ kind: "module-settings", moduleId: "signage" }, "/settings/signage"],
    ] as const) {
      expect(dashboardPath(route)).toBe(path);
      expect(parseDashboardPath(path)).toEqual(route);
    }
  });
});

describe("dashboardPath", () => {
  it("spells each route canonically, with no implementation prefix", () => {
    expect(dashboardPath({ kind: "overview" })).toBe("/");
    expect(dashboardPath({ kind: "module", moduleId: "signage" })).toBe("/signage");
  });

  it("encodes a module id so it can never escape its own segment", () => {
    expect(dashboardPath({ kind: "module", moduleId: "a/../b" })).toBe("/a%2F..%2Fb");
    expect(parseDashboardPath(dashboardPath({ kind: "module", moduleId: "a/../b" }))).toEqual({
      kind: "module",
      moduleId: "a/../b",
    });
  });

  it("round-trips through the parser", () => {
    for (const route of [
      { kind: "overview" } as const,
      { kind: "module", moduleId: "example" } as const,
    ]) {
      expect(parseDashboardPath(dashboardPath(route))).toEqual(route);
    }
  });
});

describe("the route locator is published for the API that serves the page", () => {
  it("is a narrow package subpath, not the shell root barrel", async () => {
    const manifest = JSON.parse(
      await readFile(path.join(packageDirectory, "package.json"), "utf8"),
    ) as { exports?: Record<string, unknown> };
    expect(manifest.exports?.["./dashboard-routes"]).toEqual({
      import: "./dist/dashboard-routes.js",
      types: "./dist/dashboard-routes.d.ts",
    });
  });
});