@jskit-ai/ui-generator 0.1.17 → 0.1.19

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/ui-generator",
-  version: "0.1.17",
+  version: "0.1.19",
   kind: "generator",
   description: "Create non-CRUD pages, reusable UI elements, and subpage hosts.",
   options: {
@@ -19,7 +19,7 @@ export default Object.freeze({
       validationType: "enabled-surface-id",
       defaultFromConfig: "surfaceDefaultId",
       promptLabel: "Target surface",
-      promptHint: "Used by the placed-element subcommand. Must match an enabled surface id."
+      promptHint: "Optional. Used when JSKIT cannot infer the target surface from placement or app topology."
     },
     path: {
       required: false,
@@ -152,9 +152,11 @@ export default Object.freeze({
         export: "runGeneratorSubcommand",
         description: "Create a Vue component file under the chosen component directory (default: src/components) and add a placement entry that renders it.",
         optionNames: ["name", "surface", "path", "placement", "force"],
-        requiredOptionNames: ["name", "surface"],
+        requiredOptionNames: ["name"],
         notes: [
           "If --placement is omitted, the placed element is added at shell-layout:top-right.",
+          "If the placement target belongs to a page-owned outlet, JSKIT infers the surface automatically.",
+          "If the target is shared and the app has multiple enabled surfaces, pass --surface explicitly.",
           "If the component file already exists, rerun with --force to overwrite it."
         ],
         examples: [
@@ -162,8 +164,7 @@ export default Object.freeze({
             label: "Common usage",
             lines: [
               "npx jskit generate ui-generator placed-element \\",
-              "  --name \"Alerts Widget\" \\",
-              "  --surface admin"
+              "  --name \"Alerts Widget\""
             ]
           },
           {
@@ -277,7 +278,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/users-web": "0.1.49"
+        "@jskit-ai/users-web": "0.1.51"
       },
       dev: {}
     },

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@jskit-ai/ui-generator",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.34",
-    "@jskit-ai/shell-web": "0.1.33"
+    "@jskit-ai/kernel": "0.1.36",
+    "@jskit-ai/shell-web": "0.1.35"
   },
   "exports": {
     "./server/buildTemplateContext": "./src/server/buildTemplateContext.js"

package/src/server/subcommands/element.js

@@ -1,9 +1,12 @@
 import path from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import {
+  listSurfacePageRoots,
+  resolveBestSurfaceMatchFromPageFile,
   resolveShellOutletPlacementTargetFromApp,
   toPosixPath
 } from "@jskit-ai/kernel/server/support";
+import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface";
 import { normalizeBoolean, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import {
   DEFAULT_COMPONENT_DIRECTORY,
@@ -31,6 +34,47 @@ function renderElementComponentSource(elementName = "") {
 `;
 }
 
+async function resolvePlacedElementSurface({
+  appRoot,
+  placementTarget = {},
+  surface = "",
+  context = "ui-generator placed-element"
+} = {}) {
+  const explicitSurface = normalizeSurfaceId(surface);
+  const inferredSurfaceMatch = await resolveBestSurfaceMatchFromPageFile(
+    String(placementTarget?.sourcePath || ""),
+    await listSurfacePageRoots(appRoot, { context }),
+    { context }
+  );
+  const inferredSurface = normalizeSurfaceId(inferredSurfaceMatch?.surfaceId);
+
+  if (explicitSurface) {
+    if (inferredSurface && explicitSurface !== inferredSurface) {
+      throw new Error(
+        `${context} target "${normalizeText(placementTarget?.id) || "<unknown>"}" belongs to surface "${inferredSurface}", ` +
+        `so --surface ${explicitSurface} is invalid.`
+      );
+    }
+    return explicitSurface;
+  }
+
+  if (inferredSurface) {
+    return inferredSurface;
+  }
+
+  const surfacePageRoots = await listSurfacePageRoots(appRoot, { context });
+  if (surfacePageRoots.length === 1) {
+    return normalizeSurfaceId(surfacePageRoots[0]?.id);
+  }
+
+  const targetId = normalizeText(placementTarget?.id) || "<unknown>";
+  const enabledSurfaceIds = surfacePageRoots.map((entry) => normalizeSurfaceId(entry?.id)).filter(Boolean);
+  throw new Error(
+    `${context} could not infer a surface for placement target "${targetId}". ` +
+    `Pass --surface explicitly. Enabled surfaces: ${enabledSurfaceIds.join(", ") || "<none>"}.`
+  );
+}
+
 async function runGeneratorSubcommand({
   appRoot,
   subcommand = "",
@@ -50,7 +94,6 @@ async function runGeneratorSubcommand({
   });
 
   const name = requireOption(options, "name", { context: "ui-generator placed-element" });
-  const surface = requireOption(options, "surface", { context: "ui-generator placed-element" }).toLowerCase();
   const componentDirectory = normalizeText(options.path) || DEFAULT_COMPONENT_DIRECTORY;
   const forceOverwrite = Object.prototype.hasOwnProperty.call(options, "force")
     ? normalizeBoolean(options.force)
@@ -77,6 +120,12 @@ async function runGeneratorSubcommand({
     context: "ui-generator",
     placement: options?.placement || DEFAULT_ELEMENT_PLACEMENT
   });
+  const surface = await resolvePlacedElementSurface({
+    appRoot,
+    placementTarget,
+    surface: options?.surface,
+    context: "ui-generator placed-element"
+  });
 
   const touchedFiles = new Set();
   const desiredComponentSource = renderElementComponentSource(name);

package/test/addSubpagesSubcommand.test.js

@@ -46,17 +46,8 @@ export default function getPlacements() {
     path.join(appRoot, "packages", "main", "src", "client", "providers", "MainClientProvider.js"),
     `const mainClientComponents = [];
 
-function registerMainClientComponent(componentToken, resolveComponent) {
-  const token = String(componentToken || "").trim();
-  if (!token || typeof resolveComponent !== "function") {
-    return;
-  }
-  mainClientComponents.push(
-    Object.freeze({
-      token,
-      resolveComponent
-    })
-  );
+function registerMainClientComponent(token, resolveComponent) {
+  mainClientComponents.push({ token, resolveComponent });
 }
 
 class MainClientProvider {}

package/test/elementSubcommand.test.js

@@ -15,10 +15,27 @@ async function withTempApp(run) {
 }
 
 async function writeAppFixture(appRoot) {
+  await mkdir(path.join(appRoot, "config"), { recursive: true });
   await mkdir(path.join(appRoot, "src", "components"), { recursive: true });
   await mkdir(path.join(appRoot, "src", "pages", "admin", "workspace", "settings"), { recursive: true });
   await mkdir(path.join(appRoot, "packages", "main", "src", "client", "providers"), { recursive: true });
 
+  await writeFile(
+    path.join(appRoot, "config", "public.js"),
+    `export const config = {
+  surfaceDefaultId: "admin",
+  surfaceDefinitions: {
+    admin: {
+      id: "admin",
+      pagesRoot: "admin/workspace",
+      enabled: true
+    }
+  }
+};
+`,
+    "utf8"
+  );
+
   await writeFile(
     path.join(appRoot, "src", "components", "ShellLayout.vue"),
     `<template>
@@ -59,17 +76,8 @@ export default function getPlacements() {
     path.join(appRoot, "packages", "main", "src", "client", "providers", "MainClientProvider.js"),
     `const mainClientComponents = [];
 
-function registerMainClientComponent(componentToken, resolveComponent) {
-  const token = String(componentToken || "").trim();
-  if (!token || typeof resolveComponent !== "function") {
-    return;
-  }
-  mainClientComponents.push(
-    Object.freeze({
-      token,
-      resolveComponent
-    })
-  );
+function registerMainClientComponent(token, resolveComponent) {
+  mainClientComponents.push({ token, resolveComponent });
 }
 
 class MainClientProvider {}
@@ -132,6 +140,101 @@ test("ui-generator placed-element subcommand supports explicit placement overrid
   });
 });
 
+test("ui-generator placed-element infers surface from a page-owned placement target", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "placed-element",
+      options: {
+        name: "Ops Panel",
+        placement: "admin-settings:forms"
+      }
+    });
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.match(placementSource, /target: "admin-settings:forms"/);
+    assert.match(placementSource, /surfaces: \["admin"\]/);
+  });
+});
+
+test("ui-generator placed-element infers the only enabled surface for shared shell targets", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    await runGeneratorSubcommand({
+      appRoot,
+      subcommand: "placed-element",
+      options: {
+        name: "Ops Panel"
+      }
+    });
+
+    const placementSource = await readFile(path.join(appRoot, "src", "placement.js"), "utf8");
+    assert.match(placementSource, /target: "shell-layout:top-right"/);
+    assert.match(placementSource, /surfaces: \["admin"\]/);
+  });
+});
+
+test("ui-generator placed-element requires explicit surface when a shared shell target is ambiguous", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+    await writeFile(
+      path.join(appRoot, "config", "public.js"),
+      `export const config = {
+  surfaceDefaultId: "admin",
+  surfaceDefinitions: {
+    admin: {
+      id: "admin",
+      pagesRoot: "admin/workspace",
+      enabled: true
+    },
+    console: {
+      id: "console",
+      pagesRoot: "console",
+      enabled: true
+    }
+  }
+};
+`,
+      "utf8"
+    );
+
+    await assert.rejects(
+      () =>
+        runGeneratorSubcommand({
+          appRoot,
+          subcommand: "placed-element",
+          options: {
+            name: "Ops Panel"
+          }
+        }),
+      /could not infer a surface for placement target "shell-layout:top-right". Pass --surface explicitly/
+    );
+  });
+});
+
+test("ui-generator placed-element rejects explicit surfaces that conflict with page-owned targets", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeAppFixture(appRoot);
+
+    await assert.rejects(
+      () =>
+        runGeneratorSubcommand({
+          appRoot,
+          subcommand: "placed-element",
+          options: {
+            name: "Ops Panel",
+            placement: "admin-settings:forms",
+            surface: "console"
+          }
+        }),
+      /target "admin-settings:forms" belongs to surface "admin", so --surface console is invalid/
+    );
+  });
+});
+
 test("ui-generator placed-element subcommand refuses to overwrite an existing component without force", async () => {
   await withTempApp(async (appRoot) => {
     await writeAppFixture(appRoot);

package/test/packageDescriptor.test.js

@@ -6,5 +6,6 @@ test("ui-generator surface options validate against enabled surface ids", () =>
   assert.equal(descriptor.kind, "generator");
   assert.equal(descriptor.options?.surface?.validationType, "enabled-surface-id");
   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);
 });