@jskit-ai/ui-generator 0.1.49 → 0.1.50

package/test/outletSubcommand.test.js

@@ -75,6 +75,8 @@ import { computed } from "vue";
     assert.match(topologySource, /compact: \{/);
     assert.match(topologySource, /medium: \{/);
     assert.match(topologySource, /expanded: \{/);
+    assert.match(topologySource, /renderers: \{/);
+    assert.match(topologySource, /link: "local\.main\.ui\.surface-aware-menu-link-item"/);
 
     const rerun = await runGeneratorSubcommand({
       appRoot,
@@ -90,6 +92,224 @@ import { computed } from "vue";
   });
 });
 
+test("ui-generator outlet can inject a concrete outlet without topology", async () => {
+  await withTempApp(async (appRoot) => {
+    const targetFile = "src/components/ReportsPanel.vue";
+    const targetPath = path.join(appRoot, targetFile);
+
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, "<template><section /></template>\n", "utf8");
+
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "outlet",
+      args: [targetFile],
+      options: {
+        target: "reports:bottom-actions"
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, [targetFile]);
+    const output = await readFile(targetPath, "utf8");
+    assert.match(output, /<ShellOutlet target="reports:bottom-actions" \/>/);
+    const topologySource = await readFile(path.join(appRoot, "src", "placementTopology.js"), "utf8");
+    assert.doesNotMatch(topologySource, /reports\.actions/);
+  });
+});
+
+test("ui-generator topology creates adaptive component topology without injecting outlets", async () => {
+  await withTempApp(async (appRoot) => {
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "topology",
+      args: [],
+      options: {
+        placement: "reports.actions",
+        kind: "component",
+        "compact-target": "reports:bottom-actions",
+        "medium-target": "reports:toolbar-actions",
+        "expanded-target": "reports:side-actions",
+        surface: "admin",
+        description: "Report action controls."
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, ["src/placementTopology.js"]);
+    const topologySource = await readFile(path.join(appRoot, "src", "placementTopology.js"), "utf8");
+    assert.match(topologySource, /id: "reports\.actions"/);
+    assert.match(topologySource, /description: "Report action controls\."/);
+    assert.match(topologySource, /surfaces: \["admin"\]/);
+    assert.match(topologySource, /compact: \{\n {6}outlet: "reports:bottom-actions"\n {4}\}/);
+    assert.match(topologySource, /medium: \{\n {6}outlet: "reports:toolbar-actions"\n {4}\}/);
+    assert.match(topologySource, /expanded: \{\n {6}outlet: "reports:side-actions"\n {4}\}/);
+    assert.doesNotMatch(topologySource, /renderers: \{/);
+  });
+});
+
+test("ui-generator topology creates link topology with owner inference for one target", async () => {
+  await withTempApp(async (appRoot) => {
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "topology",
+      args: [],
+      options: {
+        placement: "page.section-nav",
+        kind: "link",
+        target: "report-view:sub-pages",
+        surface: "admin"
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, ["src/placementTopology.js"]);
+    const topologySource = await readFile(path.join(appRoot, "src", "placementTopology.js"), "utf8");
+    assert.match(topologySource, /id: "page\.section-nav"/);
+    assert.match(topologySource, /owner: "report-view"/);
+    assert.match(topologySource, /compact: \{\n {6}outlet: "report-view:sub-pages",/);
+    assert.match(topologySource, /medium: \{\n {6}outlet: "report-view:sub-pages",/);
+    assert.match(topologySource, /expanded: \{\n {6}outlet: "report-view:sub-pages",/);
+    assert.match(topologySource, /link: "local\.main\.ui\.surface-aware-menu-link-item"/);
+  });
+});
+
+test("ui-generator topology treats existing app topology id and owner as already present without a marker", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeFile(
+      path.join(appRoot, "src", "placementTopology.js"),
+      `export default {
+  placements: [
+    {
+      id: "page.actions",
+      owner: "customer-view",
+      surfaces: ["admin"],
+      variants: {
+        compact: { outlet: "customer-view:summary-actions" },
+        medium: { outlet: "customer-view:summary-actions" },
+        expanded: { outlet: "customer-view:summary-actions" }
+      }
+    }
+  ]
+};
+`,
+      "utf8"
+    );
+
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "topology",
+      args: [],
+      options: {
+        placement: "page.actions",
+        kind: "component",
+        target: "customer-view:summary-actions"
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, []);
+    const topologySource = await readFile(path.join(appRoot, "src", "placementTopology.js"), "utf8");
+    assert.equal((topologySource.match(/id: "page\.actions"/g) || []).length, 1);
+    assert.doesNotMatch(topologySource, /jskit:ui-generator\.topology:page\.actions:customer-view/);
+  });
+});
+
+test("ui-generator topology rejects an existing semantic id and owner with different outlets", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeFile(
+      path.join(appRoot, "src", "placementTopology.js"),
+      `export default {
+  placements: [
+    {
+      id: "page.actions",
+      owner: "customer-view",
+      surfaces: ["admin"],
+      variants: {
+        compact: { outlet: "customer-view:summary-actions" },
+        medium: { outlet: "customer-view:summary-actions" },
+        expanded: { outlet: "customer-view:summary-actions" }
+      }
+    }
+  ]
+};
+`,
+      "utf8"
+    );
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "topology",
+        args: [],
+        options: {
+          placement: "page.actions",
+          kind: "component",
+          target: "customer-view:footer-actions"
+        }
+      }),
+      /semantic placement "page\.actions" for owner "customer-view" already exists with different outlet mapping/
+    );
+  });
+});
+
+test("ui-generator topology requires owner for owner-scoped placements across multiple hosts", async () => {
+  await withTempApp(async (appRoot) => {
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "topology",
+        args: [],
+        options: {
+          placement: "page.section-nav",
+          kind: "link",
+          "compact-target": "report-compact:sub-pages",
+          "medium-target": "report-medium:sub-pages",
+          "expanded-target": "report-expanded:sub-pages",
+          surface: "admin"
+        }
+      }),
+      /ui-generator topology requires --owner because semantic placement "page\.section-nav" maps to multiple outlet hosts/
+    );
+  });
+});
+
+test("ui-generator outlet validates topology before writing the concrete outlet", async () => {
+  await withTempApp(async (appRoot) => {
+    const targetFile = "src/components/ContactDetailsPanel.vue";
+    const targetPath = path.join(appRoot, targetFile);
+    const originalSource = "<template><div /></template>\n";
+
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, originalSource, "utf8");
+    await writeFile(
+      path.join(appRoot, "src", "placementTopology.js"),
+      `export default {
+  placements: [
+    {
+      id: "page.actions",
+      owner: "contact-view",
+      variants: {}
+    }
+  ]
+};
+`,
+      "utf8"
+    );
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "outlet",
+        args: [targetFile],
+        options: {
+          target: "contact-view:summary-actions",
+          placement: "page.actions"
+        }
+      }),
+      /requires compact topology variant/
+    );
+
+    assert.equal(await readFile(targetPath, "utf8"), originalSource);
+  });
+});
+
 test("ui-generator outlet does not inject a second matching outlet", async () => {
   await withTempApp(async (appRoot) => {
     const targetFile = "src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/index.vue";
@@ -162,6 +382,44 @@ test("ui-generator outlet creates script setup when missing", async () => {
   });
 });
 
+test("ui-generator outlet creates script setup instead of adding template imports to normal script", async () => {
+  await withTempApp(async (appRoot) => {
+    const targetFile = "src/components/OptionsPanel.vue";
+    const targetPath = path.join(appRoot, targetFile);
+
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(
+      targetPath,
+      `<script>
+export default {
+  name: "OptionsPanel"
+};
+</script>
+
+<template>
+  <div>Options</div>
+</template>
+`,
+      "utf8"
+    );
+
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "outlet",
+      args: [targetFile],
+      options: {
+        target: "options:footer-actions",
+        placement: "page.actions"
+      }
+    });
+
+    const output = await readFile(targetPath, "utf8");
+    assert.match(output, /<script setup>\nimport ShellOutlet from "@jskit-ai\/shell-web\/client\/components\/ShellOutlet";\n<\/script>/);
+    assert.match(output, /<script>\nexport default/);
+    assert.match(output, /<ShellOutlet target="options:footer-actions" \/>/);
+  });
+});
+
 test("ui-generator outlet inserts generated script after existing route block", async () => {
   await withTempApp(async (appRoot) => {
     const targetFile = "src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/index.vue";

package/test/packageDescriptor.test.js

@@ -8,4 +8,15 @@ test("ui-generator surface options validate against enabled surface ids", () =>
   assert.equal(descriptor.metadata?.generatorSubcommands?.["placed-element"]?.optionNames?.includes("surface"), true);
   assert.equal(descriptor.metadata?.generatorSubcommands?.["placed-element"]?.requiredOptionNames?.includes("surface"), false);
   assert.equal(descriptor.metadata?.generatorSubcommands?.page?.optionNames?.includes("force"), true);
+  assert.equal(descriptor.options?.kind?.validationType, "enum");
+  assert.equal(descriptor.options?.["navigation-role"]?.validationType, "enum");
+  assert.deepEqual(
+    descriptor.options?.["navigation-role"]?.allowedValues,
+    ["primary", "secondary", "utility", "detail", "workflow", "none"]
+  );
+  assert.equal(descriptor.metadata?.generatorSubcommands?.page?.optionNames?.includes("navigation-role"), true);
+  assert.equal(descriptor.metadata?.generatorSubcommands?.outlet?.requiredOptionNames?.includes("placement"), false);
+  assert.equal(descriptor.metadata?.generatorSubcommands?.topology?.entrypoint, "src/server/subcommands/outlet.js");
+  assert.equal(descriptor.metadata?.generatorSubcommands?.topology?.optionNames?.includes("compact-target"), true);
+  assert.equal(descriptor.metadata?.generatorSubcommands?.topology?.requiredOptionNames?.includes("kind"), true);
 });

package/test/pageSubcommand.test.js

@@ -3,6 +3,7 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { tmpdir } from "node:os";
 import test from "node:test";
+import { assertGeneratedUiSourceContract } from "@jskit-ai/kernel/shared/support/generatedUiContract";
 import { runGeneratorSubcommand } from "../src/server/subcommands/page.js";
 
 async function withTempApp(run) {
@@ -65,6 +66,18 @@ async function writePlacementTopology(appRoot, entries = []) {
       surfaces: ["*"],
       outlet: "shell-layout:top-right",
       linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+    }),
+    renderTopologyEntry({
+      id: "shell.global-actions",
+      surfaces: ["*"],
+      outlet: "shell-layout:top-right",
+      linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+    }),
+    renderTopologyEntry({
+      id: "shell.secondary-nav",
+      surfaces: ["*"],
+      outlet: "shell-layout:secondary-menu",
+      linkRenderer: "local.main.ui.surface-aware-menu-link-item"
     })
   ];
   await writeFile(
@@ -104,6 +117,7 @@ async function writeAppFixture(appRoot, { configSource = "" } = {}) {
       default
     />
     <ShellOutlet target="shell-layout:top-right" />
+    <ShellOutlet target="shell-layout:secondary-menu" />
   </div>
 </template>
 `,
@@ -141,7 +155,16 @@ test("ui-generator page subcommand creates an index page from an explicit target
     assert.equal(result.summary, 'Generated UI page "/practice" at src/pages/w/[workspaceSlug]/admin/practice/index.vue.');
 
     const pageSource = await readFile(path.join(appRoot, toPagePath(targetFile)), "utf8");
-    assert.match(pageSource, /<h1 class="text-h5 mb-2">Practice<\/h1>/);
+    assertGeneratedUiSourceContract(pageSource, {
+      profile: "page",
+      sourceName: targetFile
+    });
+    assert.match(pageSource, /generated-ui-screen generated-ui-screen--operator generated-page-screen/);
+    assert.match(pageSource, /<p class="text-overline text-medium-emphasis mb-1">Workspace tool<\/p>/);
+    assert.match(pageSource, /<h1 class="generated-page-screen__title">Practice<\/h1>/);
+    assert.match(pageSource, /<v-sheet rounded="lg" border class="generated-page-screen__empty-state">/);
+    assert.match(pageSource, /No Practice activity yet/);
+    assert.doesNotMatch(pageSource, /Replace this scaffold|Use this area|This is your page|<v-card\b|v-card-title/);
 
     const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
     assert.match(placementSource, /id: "ui-generator\.page\.admin\.practice\.link"/);
@@ -150,7 +173,90 @@ test("ui-generator page subcommand creates an index page from an explicit target
   });
 });
 
-test("ui-generator page subcommand creates a file route and derives label from the file path", async () => {
+test("ui-generator page subcommand maps secondary navigation role to shell.secondary-nav", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/reports/index.vue";
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {
+        name: "Reports",
+        "navigation-role": "secondary"
+      }
+    });
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.match(placementSource, /target: "shell\.secondary-nav"/);
+    assert.match(placementSource, /kind: "link"/);
+  });
+});
+
+test("ui-generator page subcommand maps utility navigation role to shell.global-actions", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/help/index.vue";
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {
+        name: "Help",
+        "navigation-role": "utility"
+      }
+    });
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.match(placementSource, /target: "shell\.global-actions"/);
+    assert.match(placementSource, /kind: "link"/);
+  });
+});
+
+test("ui-generator page subcommand can generate detail pages without navigation placement", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/reports/[reportId].vue";
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {
+        name: "Report",
+        "navigation-role": "detail"
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, [toPagePath(targetFile)]);
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.doesNotMatch(placementSource, /ui-generator\.page\.admin\.reports\.report-id\.link/);
+  });
+});
+
+test("ui-generator page subcommand rejects no-link navigation roles with link placement options", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    await assert.rejects(
+      runGeneratorSubcommand({
+        appRoot,
+        subcommand: "page",
+        args: ["w/[workspaceSlug]/admin/reports/[reportId].vue"],
+        options: {
+          "navigation-role": "detail",
+          "link-placement": "shell.primary-nav"
+        }
+      }),
+      /navigation-role "detail" cannot be combined with --link-placement/
+    );
+  });
+});
+
+test("ui-generator page subcommand treats dynamic file routes as detail pages by default", async () => {
   await withTempApp(async (appRoot) => {
     await writeAppFixture(appRoot);
 
@@ -162,10 +268,33 @@ test("ui-generator page subcommand creates a file route and derives label from t
       options: {}
     });
 
-    assert.deepEqual(result.touchedFiles, [toPagePath(targetFile), "src/placement.js"]);
+    assert.deepEqual(result.touchedFiles, [toPagePath(targetFile)]);
 
     const pageSource = await readFile(path.join(appRoot, toPagePath(targetFile)), "utf8");
-    assert.match(pageSource, /<h1 class="text-h5 mb-2">Contact Id<\/h1>/);
+    assert.match(pageSource, /generated-ui-screen generated-ui-screen--operator generated-page-screen/);
+    assert.match(pageSource, /<h1 class="generated-page-screen__title">Contact Id<\/h1>/);
+    assert.match(pageSource, /No Contact Id activity yet/);
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.doesNotMatch(placementSource, /ui-generator\.page\.admin\.contacts\.contact-id\.link/);
+  });
+});
+
+test("ui-generator page subcommand allows explicit primary navigation for dynamic routes", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    const targetFile = "w/[workspaceSlug]/admin/contacts/[contactId].vue";
+    const result = await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "page",
+      args: [targetFile],
+      options: {
+        "navigation-role": "primary"
+      }
+    });
+
+    assert.deepEqual(result.touchedFiles, [toPagePath(targetFile), "src/placement.js"]);
 
     const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
     assert.match(placementSource, /scopedSuffix: "\/contacts\/\[contactId\]"/);
@@ -489,7 +618,7 @@ test("ui-generator page subcommand overwrites an existing page when --force is p
     assert.equal(result.summary, 'Regenerated UI page "/practice" at src/pages/w/[workspaceSlug]/admin/practice/index.vue.');
 
     const pageSource = await readFile(path.join(appRoot, toPagePath(targetFile)), "utf8");
-    assert.match(pageSource, /<h1 class="text-h5 mb-2">Practice<\/h1>/);
+    assert.match(pageSource, /<h1 class="generated-page-screen__title">Practice<\/h1>/);
     assert.doesNotMatch(pageSource, /custom practice page/);
   });
 });