@jskit-ai/ui-generator 0.1.49 → 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.49",
+  version: "0.1.50",
   kind: "generator",
   description: "Create non-CRUD pages, reusable UI elements, and subpage hosts.",
   options: {
@@ -40,7 +42,16 @@ export default Object.freeze({
       inputType: "text",
       defaultValue: "",
       promptLabel: "Placement target",
-      promptHint: "Semantic placement target for placed-element and outlet mapping (format: area.slot, default for placed-element: shell.status)."
+      promptHint: "Semantic placement target for placed-element, outlet, and topology mapping (format: area.slot, default for placed-element: shell.status)."
+    },
+    kind: {
+      required: false,
+      inputType: "text",
+      validationType: "enum",
+      allowedValues: ["component", "link"],
+      defaultValue: "",
+      promptLabel: "Placement kind",
+      promptHint: "Use component for componentToken-backed entries, or link when topology should provide a link renderer."
     },
     owner: {
       required: false,
@@ -70,6 +81,7 @@ export default Object.freeze({
       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",
@@ -83,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,
@@ -133,7 +166,7 @@ export default Object.freeze({
             descriptionKey: "page-target-file"
           }
         ],
-        optionNames: ["name", "link-placement", "link-to", "force"],
+        optionNames: ["name", "navigation-role", "link-placement", "link-to", "force"],
         notes: [
           "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/...",
@@ -217,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.\""
             ]
           },
           {
@@ -240,8 +273,8 @@ export default Object.freeze({
         description: "Inject a generic ShellOutlet block into an existing Vue page/component.",
         longDescription: [
           "A ShellOutlet creates a concrete placement recipient inside a Vue file.",
-          "The command also appends the semantic topology mapping for that outlet, so `jskit list-placements` exposes the public `area.slot` placement instead of leaving the concrete recipient unused.",
-          "Generated topology includes compact, medium, and expanded variants. By default all three point at the inserted outlet; hand-edit `src/placementTopology.js` if the adaptive layout uses different concrete outlets."
+          "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: [
           {
@@ -250,11 +283,12 @@ export default Object.freeze({
             descriptionKey: "existing-vue-sfc-target-file"
           }
         ],
-        optionNames: ["target", "placement", "owner", "surface", "description", "link-renderer"],
-        requiredOptionNames: ["target", "placement"],
+        optionNames: ["target", "placement", "owner", "surface", "description", "kind", "link-renderer", "compact-target", "medium-target", "expanded-target"],
+        requiredOptionNames: ["target"],
         notes: [
           "Use --target host:position for the concrete outlet and --placement area.slot for the public semantic placement.",
-          "The generated topology maps compact, medium, and expanded to the new concrete outlet."
+          "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: [
           {
@@ -277,6 +311,48 @@ export default Object.freeze({
             ]
           }
         ]
+      },
+      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"
+            ]
+          }
+        ]
       }
     },
     apiSummary: {
@@ -295,7 +371,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/users-web": "0.1.81"
+        "@jskit-ai/users-web": "0.1.82"
       },
       dev: {}
     },

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@jskit-ai/ui-generator",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.66",
-    "@jskit-ai/shell-web": "0.1.65"
+    "@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";
 
@@ -19,6 +24,27 @@ function resolveOwnerLine(owner = "") {
   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 = "",
@@ -34,7 +60,9 @@ async function buildUiPageTemplateContext({
     pageTarget,
     targetFile,
     context: "ui-generator page",
-    placement: options?.["link-placement"],
+    placement: resolveNavigationRoleLinkPlacement(options, {
+      routePath: resolveNavigationInferenceRoutePath(pageTarget)
+    }),
     linkTo: options?.["link-to"]
   });
 
@@ -51,4 +79,10 @@ async function buildUiPageTemplateContext({
   };
 }
 
-export { buildUiPageTemplateContext };
+export {
+  buildUiPageTemplateContext,
+  normalizeGeneratedUiNavigationRole as normalizeNavigationRole,
+  resolveNavigationInferenceRoutePath,
+  resolveNavigationRoleLinkPlacement,
+  shouldCreateNavigationLink
+};

package/src/server/subcommands/addSubpages.js

@@ -3,13 +3,14 @@ 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,
-  appendBlockIfMarkerMissing,
+  appendTopologyBlockIfPlacementMissing,
   requireSinglePositionalTargetFile,
   resolvePathWithinApp,
   resolveOutletTargetId,
@@ -42,19 +43,19 @@ function renderSectionNavTopologyBlock({
     "    compact: {\n" +
     `      outlet: "${target}",\n` +
     "      renderers: {\n" +
-    `        link: "local.main.ui.surface-aware-menu-link-item"\n` +
+    `        link: "${SUBPAGES_LINK_COMPONENT_TOKEN}"\n` +
     "      }\n" +
     "    },\n" +
     "    medium: {\n" +
     `      outlet: "${target}",\n` +
     "      renderers: {\n" +
-    `        link: "local.main.ui.surface-aware-menu-link-item"\n` +
+    `        link: "${SUBPAGES_LINK_COMPONENT_TOKEN}"\n` +
     "      }\n" +
     "    },\n" +
     "    expanded: {\n" +
     `      outlet: "${target}",\n` +
     "      renderers: {\n" +
-    `        link: "local.main.ui.surface-aware-menu-link-item"\n` +
+    `        link: "${SUBPAGES_LINK_COMPONENT_TOKEN}"\n` +
     "      }\n" +
     "    }\n" +
     "  }\n" +
@@ -99,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,
@@ -110,22 +138,6 @@ async function runGeneratorSubcommand({
     dryRun
   });
 
-  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 topologyApplied = appendBlockIfMarkerMissing(
-    topologySource,
-    topologyMarker,
-    renderSectionNavTopologyBlock({
-      marker: topologyMarker,
-      owner,
-      surface: result.surfaceId,
-      target: outletTarget.id
-    })
-  );
   const touchedFiles = new Set(result.touchedFiles);
   if (topologyApplied.changed) {
     if (dryRun !== true) {

package/src/server/subcommands/element.js

@@ -26,11 +26,25 @@ 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>
 `;
 }