@jskit-ai/ui-generator 0.1.48 → 0.1.50

package/test/elementSubcommand.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/element.js";
 
 async function withTempApp(run) {
@@ -14,6 +15,39 @@ async function withTempApp(run) {
   }
 }
 
+function renderTopologyEntry({
+  id = "",
+  owner = "",
+  surfaces = ["*"],
+  defaultPlacement = false,
+  outlet = "",
+  linkRenderer = ""
+} = {}) {
+  const ownerLine = owner ? `    owner: "${owner}",\n` : "";
+  const defaultLine = defaultPlacement ? "    default: true,\n" : "";
+  const rendererLines = linkRenderer
+    ? `,
+      renderers: {
+        link: "${linkRenderer}"
+      }`
+    : "";
+  return `  {
+    id: "${id}",
+${ownerLine}    surfaces: ${JSON.stringify(surfaces)},
+${defaultLine}    variants: {
+      compact: {
+        outlet: "${outlet}"${rendererLines}
+      },
+      medium: {
+        outlet: "${outlet}"${rendererLines}
+      },
+      expanded: {
+        outlet: "${outlet}"${rendererLines}
+      }
+    }
+  }`;
+}
+
 async function writeAppFixture(appRoot) {
   await mkdir(path.join(appRoot, "config"), { recursive: true });
   await mkdir(path.join(appRoot, "src", "components"), { recursive: true });
@@ -43,11 +77,39 @@ async function writeAppFixture(appRoot) {
     <ShellOutlet
       target="shell-layout:primary-menu"
       default
-      default-link-component-token="local.main.ui.surface-aware-menu-link-item"
     />
     <ShellOutlet target="shell-layout:top-right" />
   </div>
 </template>
+`,
+    "utf8"
+  );
+  await writeFile(
+    path.join(appRoot, "src", "placementTopology.js"),
+    `export default {
+  placements: [
+${[
+  renderTopologyEntry({
+    id: "shell.primary-nav",
+    surfaces: ["*"],
+    defaultPlacement: true,
+    outlet: "shell-layout:primary-menu",
+    linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+  }),
+  renderTopologyEntry({
+    id: "shell.status",
+    surfaces: ["*"],
+    outlet: "shell-layout:top-right"
+  }),
+  renderTopologyEntry({
+    id: "settings.sections",
+    owner: "admin-settings",
+    surfaces: ["admin"],
+    outlet: "admin-settings:forms"
+  })
+].join(",\n")}
+  ]
+};
 `,
     "utf8"
   );
@@ -114,9 +176,20 @@ test("ui-generator placed-element subcommand creates component and outlet placem
     assert.match(providerSource, /import OpsPanelElement from "\/src\/components\/OpsPanelElement\.vue";/);
     assert.match(providerSource, /registerMainClientComponent\("local\.main\.ui\.element\.ops-panel", \(\) => OpsPanelElement\);/);
 
+    const componentSource = await readFile(path.join(appRoot, "src", "components", "OpsPanelElement.vue"), "utf8");
+    assertGeneratedUiSourceContract(componentSource, {
+      profile: "placed-element",
+      sourceName: "OpsPanelElement.vue"
+    });
+    assert.match(componentSource, /class="generated-element-panel"/);
+    assert.match(componentSource, /<h2 class="text-subtitle-1 font-weight-medium mb-0">Ops Panel<\/h2>/);
+    assert.match(componentSource, /<v-chip color="primary" variant="tonal" size="small">Ready<\/v-chip>/);
+    assert.doesNotMatch(componentSource, /Replace this scaffold|Use this area|This is your page/);
+
     const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
     assert.match(placementSource, /id: "ui-generator\.element\.ops-panel"/);
-    assert.match(placementSource, /target: "shell-layout:top-right"/);
+    assert.match(placementSource, /target: "shell\.status"/);
+    assert.match(placementSource, /kind: "component"/);
     assert.match(placementSource, /componentToken: "local\.main\.ui\.element\.ops-panel"/);
   });
 });
@@ -131,16 +204,16 @@ test("ui-generator placed-element subcommand supports explicit placement overrid
       options: {
         name: "Ops Panel",
         surface: "admin",
-        placement: "shell-layout:primary-menu"
+        placement: "shell.primary-nav"
       }
     });
 
     const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
-    assert.match(placementSource, /target: "shell-layout:primary-menu"/);
+    assert.match(placementSource, /target: "shell\.primary-nav"/);
   });
 });
 
-test("ui-generator placed-element infers surface from a page-owned placement target", async () => {
+test("ui-generator placed-element infers surface from an owner-scoped semantic placement", async () => {
   await withTempApp(async (appRoot) => {
     await writeAppFixture(appRoot);
 
@@ -149,12 +222,14 @@ test("ui-generator placed-element infers surface from a page-owned placement tar
       subcommand: "placed-element",
       options: {
         name: "Ops Panel",
-        placement: "admin-settings:forms"
+        placement: "settings.sections",
+        owner: "admin-settings"
       }
     });
 
     const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
-    assert.match(placementSource, /target: "admin-settings:forms"/);
+    assert.match(placementSource, /target: "settings\.sections"/);
+    assert.match(placementSource, /owner: "admin-settings"/);
     assert.match(placementSource, /surfaces: \["admin"\]/);
   });
 });
@@ -172,7 +247,7 @@ test("ui-generator placed-element infers the only enabled surface for shared she
     });
 
     const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
-    assert.match(placementSource, /target: "shell-layout:top-right"/);
+    assert.match(placementSource, /target: "shell\.status"/);
     assert.match(placementSource, /surfaces: \["admin"\]/);
   });
 });
@@ -210,7 +285,7 @@ test("ui-generator placed-element requires explicit surface when a shared shell
             name: "Ops Panel"
           }
         }),
-      /could not infer a surface for placement target "shell-layout:top-right". Pass --surface explicitly/
+      /could not infer a surface for placement target "shell.status". Pass --surface explicitly/
     );
   });
 });
@@ -226,11 +301,12 @@ test("ui-generator placed-element rejects explicit surfaces that conflict with p
           subcommand: "placed-element",
           options: {
             name: "Ops Panel",
-            placement: "admin-settings:forms",
+            placement: "settings.sections",
+            owner: "admin-settings",
             surface: "console"
           }
         }),
-      /target "admin-settings:forms" belongs to surface "admin", so --surface console is invalid/
+      /target "settings.sections" is not available on surface "console"/
     );
   });
 });
@@ -285,7 +361,8 @@ test("ui-generator placed-element subcommand overwrites an existing component wh
     ]);
 
     const componentSource = await readFile(path.join(appRoot, "src", "components", "OpsPanelElement.vue"), "utf8");
-    assert.match(componentSource, /<h2 class="text-h6 mb-2">Ops Panel<\/h2>/);
+    assert.match(componentSource, /<h2 class="text-subtitle-1 font-weight-medium mb-0">Ops Panel<\/h2>/);
+    assert.doesNotMatch(componentSource, /custom/);
   });
 });
 

package/test/outletSubcommand.test.js

@@ -8,6 +8,23 @@ import { runGeneratorSubcommand } from "../src/server/subcommands/outlet.js";
 async function withTempApp(run) {
   const appRoot = await mkdtemp(path.join(tmpdir(), "ui-generator-outlet-"));
   try {
+    await mkdir(path.join(appRoot, "src"), { recursive: true });
+    await writeFile(
+      path.join(appRoot, "src", "placementTopology.js"),
+      `const placements = [];
+
+function addPlacementTopology(value = {}) {
+  placements.push(value);
+}
+
+export { addPlacementTopology };
+
+export default function getPlacementTopology() {
+  return { placements };
+}
+`,
+      "utf8"
+    );
     return await run(appRoot);
   } finally {
     await rm(appRoot, { recursive: true, force: true });
@@ -40,24 +57,34 @@ import { computed } from "vue";
       subcommand: "outlet",
       args: [targetFile],
       options: {
-        target: "contact-view:sub-pages"
+        target: "contact-view:sub-pages",
+        placement: "page.section-nav"
       }
     });
 
-    assert.deepEqual(result.touchedFiles, [targetFile]);
+    assert.deepEqual(result.touchedFiles, [targetFile, "src/placementTopology.js"]);
 
     const output = await readFile(targetPath, "utf8");
     assert.match(output, /import ShellOutlet from "@jskit-ai\/shell-web\/client\/components\/ShellOutlet";/);
     assert.match(output, /<ShellOutlet target="contact-view:sub-pages" \/>/);
     assert.doesNotMatch(output, /RouterView/);
     assert.doesNotMatch(output, /jskit:ui-generator\.outlet:/);
+    const topologySource = await readFile(path.join(appRoot, "src", "placementTopology.js"), "utf8");
+    assert.match(topologySource, /id: "page\.section-nav"/);
+    assert.match(topologySource, /owner: "contact-view"/);
+    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,
       subcommand: "outlet",
       args: [targetFile],
       options: {
-        target: "contact-view:sub-pages"
+        target: "contact-view:sub-pages",
+        placement: "page.section-nav"
       }
     });
 
@@ -65,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";
@@ -91,7 +336,8 @@ import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
       subcommand: "outlet",
       args: [targetFile],
       options: {
-        target: "contact-view:sub-pages"
+        target: "contact-view:sub-pages",
+        placement: "page.section-nav"
       }
     });
 
@@ -124,7 +370,8 @@ test("ui-generator outlet creates script setup when missing", async () => {
       subcommand: "outlet",
       args: [targetFile],
       options: {
-        target: "contact-view:sub-pages"
+        target: "contact-view:sub-pages",
+        placement: "page.section-nav"
       }
     });
 
@@ -135,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";
@@ -161,7 +446,8 @@ test("ui-generator outlet inserts generated script after existing route block",
       subcommand: "outlet",
       args: [targetFile],
       options: {
-        target: "contact-view:sub-pages"
+        target: "contact-view:sub-pages",
+        placement: "page.section-nav"
       }
     });
 
@@ -203,7 +489,8 @@ test("ui-generator outlet keeps indentation when injected into nested template b
       subcommand: "outlet",
       args: [targetFile],
       options: {
-        target: "contact-view:sub-pages"
+        target: "contact-view:sub-pages",
+        placement: "page.section-nav"
       }
     });
 
@@ -229,6 +516,7 @@ test("ui-generator outlet rejects unsupported options", async () => {
       args: [targetFile],
       options: {
         target: "contact-view:sub-pages",
+        placement: "page.section-nav",
         bogus: "routed"
       }
       }),
@@ -250,7 +538,8 @@ test("ui-generator outlet supports explicit target host:position", async () => {
       subcommand: "outlet",
       args: [targetFile],
       options: {
-        target: "customer-view:summary-actions"
+        target: "customer-view:summary-actions",
+        placement: "page.actions"
       }
     });
 
@@ -272,9 +561,10 @@ test("ui-generator outlet rejects non-vue target files without changing them", a
       runGeneratorSubcommand({
         appRoot,
         subcommand: "outlet",
-        args: [targetFile],
-        options: {
-          target: "vet-view:sub-pages"
+      args: [targetFile],
+      options: {
+          target: "vet-view:sub-pages",
+          placement: "page.section-nav"
         }
       }),
       /ui-generator outlet target file must be an existing Vue SFC \(\.vue\): src\/pages\/w\/\[workspaceSlug\]\/admin\/practice\/vets\/_components\/VetAddEditFormFields\.js\./
@@ -297,9 +587,10 @@ test("ui-generator outlet validates target format", async () => {
       runGeneratorSubcommand({
         appRoot,
         subcommand: "outlet",
-        args: [targetFile],
-        options: {
-          target: "customer-view:"
+      args: [targetFile],
+      options: {
+          target: "customer-view:",
+          placement: "page.actions"
         }
       }),
       /ui-generator outlet option "target" must be a target in "host:position" format\./

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);
 });