@jskit-ai/ui-generator 0.1.48 → 0.1.50

package/package.descriptor.mjs

@@ -1,7 +1,9 @@
+import { GENERATED_UI_NAVIGATION_ROLE_OPTION } from "@jskit-ai/kernel/shared/support/generatedUiContract";
+
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/ui-generator",
-  version: "0.1.48",
+  version: "0.1.50",
   kind: "generator",
   description: "Create non-CRUD pages, reusable UI elements, and subpage hosts.",
   options: {
@@ -40,23 +42,46 @@ export default Object.freeze({
       inputType: "text",
       defaultValue: "",
       promptLabel: "Placement target",
-      promptHint: "Optional target for placed-element placement (format: host:position, default: shell-layout:top-right)."
+      promptHint: "Semantic placement target for placed-element, outlet, and topology mapping (format: area.slot, default for placed-element: shell.status)."
     },
-    "link-placement": {
+    kind: {
       required: false,
       inputType: "text",
+      validationType: "enum",
+      allowedValues: ["component", "link"],
       defaultValue: "",
-      promptLabel: "Link placement",
-      promptHint: "Optional target for the generated page link placement (format: host:position)."
+      promptLabel: "Placement kind",
+      promptHint: "Use component for componentToken-backed entries, or link when topology should provide a link renderer."
     },
-    "link-component-token": {
+    owner: {
       required: false,
       inputType: "text",
       defaultValue: "",
-      promptLabel: "Link component token",
-      promptHint:
-        "Optional component token override for the generated page link placement (example: local.main.ui.tab-link-item)."
+      promptLabel: "Placement owner",
+      promptHint: "Optional owner id for semantic topology mappings. Page/settings placements default to the outlet host."
+    },
+    description: {
+      required: false,
+      inputType: "text",
+      defaultValue: "",
+      promptLabel: "Description",
+      promptHint: "Optional description for generated semantic topology mappings."
+    },
+    "link-renderer": {
+      required: false,
+      inputType: "text",
+      defaultValue: "local.main.ui.surface-aware-menu-link-item",
+      promptLabel: "Link renderer",
+      promptHint: "Default link renderer token for generated topology variants."
     },
+    "link-placement": {
+      required: false,
+      inputType: "text",
+      defaultValue: "",
+      promptLabel: "Link placement",
+      promptHint: "Optional semantic target for the generated page link placement (format: area.slot)."
+    },
+    "navigation-role": GENERATED_UI_NAVIGATION_ROLE_OPTION,
     "link-to": {
       required: false,
       inputType: "text",
@@ -70,7 +95,28 @@ export default Object.freeze({
       inputType: "text",
       defaultValue: "",
       promptLabel: "Outlet target",
-      promptHint: "Used by add-subpages and outlet. Must be a target in host:position format."
+      promptHint: "Used by add-subpages, outlet, and topology. Must be a target in host:position format. For topology, maps all layouts unless layout-specific targets are provided."
+    },
+    "compact-target": {
+      required: false,
+      inputType: "text",
+      defaultValue: "",
+      promptLabel: "Compact outlet target",
+      promptHint: "Concrete outlet used by topology for compact layouts, in host:position format."
+    },
+    "medium-target": {
+      required: false,
+      inputType: "text",
+      defaultValue: "",
+      promptLabel: "Medium outlet target",
+      promptHint: "Concrete outlet used by topology for medium layouts, in host:position format."
+    },
+    "expanded-target": {
+      required: false,
+      inputType: "text",
+      defaultValue: "",
+      promptLabel: "Expanded outlet target",
+      promptHint: "Concrete outlet used by topology for expanded layouts, in host:position format."
     },
     title: {
       required: false,
@@ -120,9 +166,9 @@ export default Object.freeze({
             descriptionKey: "page-target-file"
           }
         ],
-        optionNames: ["name", "link-placement", "link-component-token", "link-to", "force"],
+        optionNames: ["name", "navigation-role", "link-placement", "link-to", "force"],
         notes: [
-          "If a nearest parent subpages target is found, placement, link component token, and props.to are inferred automatically.",
+          "If a nearest parent subpages target is found, semantic placement and props.to are inferred automatically.",
           "If the parent target page is index.vue, child pages belong under index/...",
           "If the target page file already exists, rerun with --force to overwrite it."
         ],
@@ -151,10 +197,10 @@ export default Object.freeze({
         entrypoint: "src/server/subcommands/element.js",
         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"],
+        optionNames: ["name", "surface", "path", "placement", "owner", "force"],
         requiredOptionNames: ["name"],
         notes: [
-          "If --placement is omitted, the placed element is added at shell-layout:top-right.",
+          "If --placement is omitted, the placed element is added at shell.status.",
           "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."
@@ -174,7 +220,7 @@ export default Object.freeze({
               "  --name \"Ops Panel\" \\",
               "  --surface admin \\",
               "  --path src/widgets \\",
-              "  --placement shell-layout:top-right \\",
+              "  --placement shell.status \\",
               "  --force"
             ]
           }
@@ -204,7 +250,7 @@ export default Object.freeze({
               "npx jskit generate ui-generator add-subpages \\",
               "  admin/customers/[customerId]/index.vue \\",
               "  --title \"Customer\" \\",
-              "  --subtitle \"View and manage this customer.\""
+              "  --subtitle \"Customer profile and activity.\""
             ]
           },
           {
@@ -226,9 +272,9 @@ export default Object.freeze({
         export: "runGeneratorSubcommand",
         description: "Inject a generic ShellOutlet block into an existing Vue page/component.",
         longDescription: [
-          "A ShellOutlet creates a named placement target inside a Vue file. That target is what other parts of JSKIT render into later.",
-          "After an outlet exists, `jskit list-placements` will discover it and show its `target`. That makes the outlet visible to humans and to generators that need a placement destination.",
-          "Commands that create placed UI, such as `ui-generator placed-element`, and commands that add page links can then target that outlet by writing placement entries that point at the same target."
+          "A ShellOutlet creates a concrete placement recipient inside a Vue file.",
+          "If --placement is provided, the command also appends semantic topology for that outlet, so `jskit list-placements` exposes the public `area.slot` placement.",
+          "If --placement is omitted, the command only injects the concrete outlet. Use this before `ui-generator topology` when compact, medium, and expanded should map to different outlets."
         ],
         positionalArgs: [
           {
@@ -237,10 +283,12 @@ export default Object.freeze({
             descriptionKey: "existing-vue-sfc-target-file"
           }
         ],
-        optionNames: ["target"],
+        optionNames: ["target", "placement", "owner", "surface", "description", "kind", "link-renderer", "compact-target", "medium-target", "expanded-target"],
         requiredOptionNames: ["target"],
         notes: [
-          "Use --target host:position."
+          "Use --target host:position for the concrete outlet and --placement area.slot for the public semantic placement.",
+          "Omit --placement when you only want to add the concrete destination.",
+          "When --placement is present, the generated topology maps compact, medium, and expanded to the new concrete outlet unless layout-specific targets are provided."
         ],
         examples: [
           {
@@ -248,7 +296,8 @@ export default Object.freeze({
             lines: [
               "npx jskit generate ui-generator outlet \\",
               "  src/components/ContactSummaryCard.vue \\",
-              "  --target contact-view:sub-pages"
+              "  --target contact-view:sub-pages \\",
+              "  --placement page.section-nav"
             ]
           },
           {
@@ -256,7 +305,51 @@ export default Object.freeze({
             lines: [
               "npx jskit generate ui-generator outlet \\",
               "  src/pages/admin/customers/[customerId]/index.vue \\",
-              "  --target customer-view:summary-actions"
+              "  --target customer-view:summary-actions \\",
+              "  --placement page.actions \\",
+              "  --surface admin"
+            ]
+          }
+        ]
+      },
+      topology: {
+        requiresShellWeb: true,
+        entrypoint: "src/server/subcommands/outlet.js",
+        export: "runGeneratorSubcommand",
+        description: "Append semantic placement topology that maps compact, medium, and expanded layouts to concrete outlets.",
+        longDescription: [
+          "Use this after adding one or more concrete ShellOutlet destinations.",
+          "The command writes only `src/placementTopology.js`; it does not inject Vue outlets.",
+          "Use --kind component for componentToken-backed elements. Use --kind link when topology should provide the standard link renderer."
+        ],
+        optionNames: ["placement", "kind", "target", "compact-target", "medium-target", "expanded-target", "owner", "surface", "description", "link-renderer"],
+        requiredOptionNames: ["placement", "kind"],
+        notes: [
+          "Use --target host:position when all layout classes should render in the same outlet.",
+          "Use --compact-target, --medium-target, and --expanded-target when layout classes should render in different outlets.",
+          "For page.* and settings.* placements, pass --owner if the layout targets use different outlet hosts."
+        ],
+        examples: [
+          {
+            label: "Component placement with adaptive outlets",
+            lines: [
+              "npx jskit generate ui-generator topology \\",
+              "  --placement reports.actions \\",
+              "  --kind component \\",
+              "  --compact-target reports:bottom-actions \\",
+              "  --medium-target reports:toolbar-actions \\",
+              "  --expanded-target reports:side-actions \\",
+              "  --surface admin"
+            ]
+          },
+          {
+            label: "Link placement using one outlet for every layout",
+            lines: [
+              "npx jskit generate ui-generator topology \\",
+              "  --placement page.section-nav \\",
+              "  --kind link \\",
+              "  --target report-view:sub-pages \\",
+              "  --surface admin"
             ]
           }
         ]
@@ -278,7 +371,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/users-web": "0.1.80"
+        "@jskit-ai/users-web": "0.1.82"
       },
       dev: {}
     },

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@jskit-ai/ui-generator",
-  "version": "0.1.48",
+  "version": "0.1.50",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.65",
-    "@jskit-ai/shell-web": "0.1.64"
+    "@jskit-ai/kernel": "0.1.67",
+    "@jskit-ai/shell-web": "0.1.66"
   },
   "exports": {
     "./server/buildTemplateContext": "./src/server/buildTemplateContext.js"

package/src/server/buildTemplateContext.js

@@ -2,6 +2,11 @@ import {
   resolvePageLinkTargetDetails,
   resolvePageTargetDetails
 } from "@jskit-ai/kernel/server/support";
+import {
+  normalizeGeneratedUiNavigationRole,
+  resolveGeneratedUiNavigationRoleLinkPlacement,
+  shouldCreateGeneratedUiNavigationLink
+} from "@jskit-ai/kernel/shared/support/generatedUiContract";
 
 const DEFAULT_GENERATED_LINK_ICON = "mdi-view-list-outline";
 
@@ -12,6 +17,34 @@ function resolveLinkToPropLine(linkTo = "") {
   return `      to: ${JSON.stringify(linkTo)},\n`;
 }
 
+function resolveOwnerLine(owner = "") {
+  if (!owner) {
+    return "";
+  }
+  return `    owner: ${JSON.stringify(owner)},\n`;
+}
+
+function resolveNavigationInferenceRoutePath(pageTarget = {}) {
+  const routeSegments = Array.isArray(pageTarget?.visibleRouteSegments)
+    ? pageTarget.visibleRouteSegments.map((entry) => String(entry || "").trim()).filter(Boolean)
+    : [];
+  if (routeSegments.length > 0) {
+    return `/${routeSegments.join("/")}`;
+  }
+  return String(pageTarget?.routeUrlSuffix || "");
+}
+
+function shouldCreateNavigationLink(options = {}, inferenceContext = {}) {
+  return shouldCreateGeneratedUiNavigationLink(options, {
+    allowLinkTo: true,
+    routePath: inferenceContext?.routePath
+  });
+}
+
+function resolveNavigationRoleLinkPlacement(options = {}, inferenceContext = {}) {
+  return resolveGeneratedUiNavigationRoleLinkPlacement(options, inferenceContext);
+}
+
 async function buildUiPageTemplateContext({
   appRoot,
   targetFile = "",
@@ -27,14 +60,16 @@ async function buildUiPageTemplateContext({
     pageTarget,
     targetFile,
     context: "ui-generator page",
-    placement: options?.["link-placement"],
-    componentToken: options?.["link-component-token"],
+    placement: resolveNavigationRoleLinkPlacement(options, {
+      routePath: resolveNavigationInferenceRoutePath(pageTarget)
+    }),
     linkTo: options?.["link-to"]
   });
 
   return {
     __JSKIT_UI_LINK_PLACEMENT_ID__: pageTarget.placementId,
     __JSKIT_UI_LINK_PLACEMENT_TARGET__: String(linkTarget.placementTarget?.id || ""),
+    __JSKIT_UI_LINK_OWNER_LINE__: resolveOwnerLine(linkTarget.placementTarget?.owner || ""),
     __JSKIT_UI_LINK_COMPONENT_TOKEN__: String(linkTarget.componentToken || ""),
     __JSKIT_UI_LINK_ICON__: DEFAULT_GENERATED_LINK_ICON,
     __JSKIT_UI_LINK_WORKSPACE_SUFFIX__: pageTarget.routeUrlSuffix,
@@ -44,4 +79,10 @@ async function buildUiPageTemplateContext({
   };
 }
 
-export { buildUiPageTemplateContext };
+export {
+  buildUiPageTemplateContext,
+  normalizeGeneratedUiNavigationRole as normalizeNavigationRole,
+  resolveNavigationInferenceRoutePath,
+  resolveNavigationRoleLinkPlacement,
+  shouldCreateNavigationLink
+};

package/src/server/subcommands/addSubpages.js

@@ -1,17 +1,68 @@
+import { readFile, writeFile } from "node:fs/promises";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import {
   DEFAULT_COMPONENT_DIRECTORY,
   DEFAULT_SUBPAGES_POSITION,
+  SUBPAGES_LINK_COMPONENT_TOKEN,
   deriveDefaultSubpagesHost,
   resolvePageTargetDetails,
   upgradePageFileToSubpages
 } from "./pageSupport.js";
 import {
+  PLACEMENT_TOPOLOGY_FILE,
+  appendTopologyBlockIfPlacementMissing,
   requireSinglePositionalTargetFile,
+  resolvePathWithinApp,
   resolveOutletTargetId,
   rejectUnexpectedOptions
 } from "./support.js";
 
+function resolveOutletOwner(target = "") {
+  const normalizedTarget = normalizeText(target);
+  const separatorIndex = normalizedTarget.indexOf(":");
+  if (separatorIndex <= 0) {
+    return "";
+  }
+  return normalizedTarget.slice(0, separatorIndex);
+}
+
+function renderSectionNavTopologyBlock({
+  marker = "",
+  owner = "",
+  surface = "",
+  target = ""
+} = {}) {
+  return (
+    `// ${marker}\n` +
+    "addPlacementTopology({\n" +
+    `  id: "page.section-nav",\n` +
+    `  owner: "${owner}",\n` +
+    `  description: "Navigation between child pages in this section.",\n` +
+    `  surfaces: ["${surface}"],\n` +
+    "  variants: {\n" +
+    "    compact: {\n" +
+    `      outlet: "${target}",\n` +
+    "      renderers: {\n" +
+    `        link: "${SUBPAGES_LINK_COMPONENT_TOKEN}"\n` +
+    "      }\n" +
+    "    },\n" +
+    "    medium: {\n" +
+    `      outlet: "${target}",\n` +
+    "      renderers: {\n" +
+    `        link: "${SUBPAGES_LINK_COMPONENT_TOKEN}"\n` +
+    "      }\n" +
+    "    },\n" +
+    "    expanded: {\n" +
+    `      outlet: "${target}",\n` +
+    "      renderers: {\n" +
+    `        link: "${SUBPAGES_LINK_COMPONENT_TOKEN}"\n` +
+    "      }\n" +
+    "    }\n" +
+    "  }\n" +
+    "});\n"
+  );
+}
+
 function resolveSubpagesOutletTarget(options = {}, pageTarget = {}) {
   const rawTarget = normalizeText(options?.target);
   const defaultTarget = `${deriveDefaultSubpagesHost(pageTarget)}:${DEFAULT_SUBPAGES_POSITION}`;
@@ -49,6 +100,33 @@ async function runGeneratorSubcommand({
   });
   const outletTarget = resolveSubpagesOutletTarget(options, pageTarget);
 
+  const topologyPath = resolvePathWithinApp(appRoot, PLACEMENT_TOPOLOGY_FILE, {
+    context: "ui-generator add-subpages"
+  });
+  const owner = resolveOutletOwner(outletTarget.id);
+  const topologyMarker = `jskit:ui-generator.topology:page.section-nav:${owner}`;
+  const topologySource = await readFile(topologyPath.absolutePath, "utf8");
+  const expectedVariantTargets = {
+    compact: outletTarget.id,
+    medium: outletTarget.id,
+    expanded: outletTarget.id
+  };
+  const topologyApplied = await appendTopologyBlockIfPlacementMissing({
+    topologyPath,
+    source: topologySource,
+    marker: topologyMarker,
+    block: renderSectionNavTopologyBlock({
+      marker: topologyMarker,
+      owner,
+      surface: pageTarget.surfaceId,
+      target: outletTarget.id
+    }),
+    placementId: "page.section-nav",
+    owner,
+    variantTargets: expectedVariantTargets,
+    context: "ui-generator add-subpages"
+  });
+
   const result = await upgradePageFileToSubpages({
     appRoot,
     targetFile,
@@ -60,10 +138,19 @@ async function runGeneratorSubcommand({
     dryRun
   });
 
+  const touchedFiles = new Set(result.touchedFiles);
+  if (topologyApplied.changed) {
+    if (dryRun !== true) {
+      await writeFile(topologyPath.absolutePath, topologyApplied.content, "utf8");
+    }
+    touchedFiles.add(topologyPath.relativePath);
+  }
+  const touchedFileList = [...touchedFiles].sort((left, right) => left.localeCompare(right));
+
   return {
-    touchedFiles: result.touchedFiles,
+    touchedFiles: touchedFileList,
     summary:
-      result.touchedFiles.length > 0
+      touchedFileList.length > 0
         ? `Enabled subpages in ${result.targetFile} for "${pageTarget.routeUrlSuffix}" using outlet target "${outletTarget.id}".`
         : `Subpages are already enabled in ${result.targetFile}.`
   };

package/src/server/subcommands/element.js

@@ -3,7 +3,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import {
   listSurfacePageRoots,
   resolveBestSurfaceMatchFromPageFile,
-  resolveShellOutletPlacementTargetFromApp,
+  resolveSemanticPlacementTargetFromApp,
   toPosixPath
 } from "@jskit-ai/kernel/server/support";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface";
@@ -22,15 +22,29 @@ import {
   insertBeforeClassDeclaration
 } from "./support.js";
 
-const DEFAULT_ELEMENT_PLACEMENT = "shell-layout:top-right";
+const DEFAULT_ELEMENT_PLACEMENT = "shell.status";
 
 function renderElementComponentSource(elementName = "") {
   return `<template>
-  <section class="pa-4">
-    <h2 class="text-h6 mb-2">${elementName}</h2>
-    <p class="text-body-2 text-medium-emphasis">Replace this scaffold with your UI element implementation.</p>
+  <section class="generated-element-panel">
+    <div>
+      <p class="text-caption text-medium-emphasis mb-1">Status</p>
+      <h2 class="text-subtitle-1 font-weight-medium mb-0">${elementName}</h2>
+    </div>
+    <v-chip color="primary" variant="tonal" size="small">Ready</v-chip>
   </section>
 </template>
+
+<style scoped>
+.generated-element-panel {
+  align-items: center;
+  display: flex;
+  gap: 0.75rem;
+  justify-content: space-between;
+  min-height: 48px;
+  min-width: 0;
+}
+</style>
 `;
 }
 
@@ -41,14 +55,28 @@ async function resolvePlacedElementSurface({
   context = "ui-generator placed-element"
 } = {}) {
   const explicitSurface = normalizeSurfaceId(surface);
+  const placementSurfaces = Array.isArray(placementTarget?.surfaces)
+    ? placementTarget.surfaces.map((entry) => normalizeSurfaceId(entry)).filter(Boolean)
+    : [];
+  const isPlacementGlobal = placementSurfaces.length < 1 || placementSurfaces.includes("*");
+  const concreteSourcePath = normalizeText(placementTarget?.sourcePath).startsWith("src/")
+    ? normalizeText(placementTarget?.sourcePath)
+    : "";
   const inferredSurfaceMatch = await resolveBestSurfaceMatchFromPageFile(
-    String(placementTarget?.sourcePath || ""),
+    concreteSourcePath,
     await listSurfacePageRoots(appRoot, { context }),
     { context }
   );
-  const inferredSurface = normalizeSurfaceId(inferredSurfaceMatch?.surfaceId);
+  const inferredSurface =
+    normalizeSurfaceId(inferredSurfaceMatch?.surfaceId) ||
+    (placementSurfaces.length === 1 && !isPlacementGlobal ? placementSurfaces[0] : "");
 
   if (explicitSurface) {
+    if (!isPlacementGlobal && placementSurfaces.length > 0 && !placementSurfaces.includes(explicitSurface)) {
+      throw new Error(
+        `${context} target "${normalizeText(placementTarget?.id) || "<unknown>"}" is not available on surface "${explicitSurface}".`
+      );
+    }
     if (inferredSurface && explicitSurface !== inferredSurface) {
       throw new Error(
         `${context} target "${normalizeText(placementTarget?.id) || "<unknown>"}" belongs to surface "${inferredSurface}", ` +
@@ -89,7 +117,7 @@ async function runGeneratorSubcommand({
   if (Array.isArray(args) && args.length > 0) {
     throw new Error("ui-generator placed-element does not accept positional arguments.");
   }
-  rejectUnexpectedOptions(options, ["name", "surface", "path", "placement", "force"], {
+  rejectUnexpectedOptions(options, ["name", "surface", "path", "placement", "owner", "force"], {
     context: "ui-generator placed-element"
   });
 
@@ -115,10 +143,11 @@ async function runGeneratorSubcommand({
     context: "ui-generator placed-element"
   });
   const componentToken = `local.main.ui.element.${elementNameKebab}`;
-  const placementTarget = await resolveShellOutletPlacementTargetFromApp({
+  const placementTarget = await resolveSemanticPlacementTargetFromApp({
     appRoot,
     context: "ui-generator",
-    placement: options?.placement || DEFAULT_ELEMENT_PLACEMENT
+    placement: options?.placement || DEFAULT_ELEMENT_PLACEMENT,
+    owner: options?.owner
   });
   const surface = await resolvePlacedElementSurface({
     appRoot,
@@ -179,12 +208,15 @@ async function runGeneratorSubcommand({
 
   const placementSource = await readFile(placementPath.absolutePath, "utf8");
   const placementMarker = `jskit:ui-generator.element:${surface}:${elementNameKebab}`;
+  const ownerLine = placementTarget.owner ? `    owner: "${placementTarget.owner}",\n` : "";
   const placementBlock =
     `// ${placementMarker}\n` +
     "{\n" +
     "  addPlacement({\n" +
     `    id: "ui-generator.element.${elementNameKebab}",\n` +
     `    target: "${placementTarget.id}",\n` +
+    ownerLine +
+    `    kind: "component",\n` +
     `    surfaces: ["${surface}"],\n` +
     "    order: 155,\n" +
     `    componentToken: "${componentToken}"\n` +