@jskit-ai/ui-generator 0.1.14 → 0.1.15

package/package.descriptor.mjs

@@ -1,96 +1,91 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/ui-generator",
-  version: "0.1.14",
+  version: "0.1.15",
   kind: "generator",
-  description: "Generate app-local non-CRUD UI pages and outlet elements.",
+  description: "Create non-CRUD pages, reusable UI elements, and subpage hosts.",
   options: {
     name: {
-      required: true,
+      required: false,
       inputType: "text",
       defaultValue: "",
-      promptLabel: "Element name",
-      promptHint: "Display name and route slug source (example: Reports Dashboard)."
+      promptLabel: "Display label",
+      promptHint:
+        "Display label used for generated page links and named UI elements. For page, if omitted, it is derived from the target file path."
     },
     surface: {
-      required: true,
+      required: false,
       inputType: "text",
+      validationType: "enabled-surface-id",
       defaultFromConfig: "surfaceDefaultId",
       promptLabel: "Target surface",
-      promptHint: "Defaults to config.public.surfaceDefaultId. Must match an enabled surface id."
+      promptHint: "Used by the placed-element subcommand. Must match an enabled surface id."
     },
     path: {
       required: false,
       inputType: "text",
       defaultValue: "src/components",
       promptLabel: "Component path",
-      promptHint: "Component directory relative to app root (used by element subcommand)."
+      promptHint: "Component directory relative to app root (used by placed-element and add-subpages support scaffold)."
     },
-    "directory-prefix": {
+    force: {
       required: false,
-      inputType: "text",
+      inputType: "flag",
       defaultValue: "",
-      promptLabel: "Page directory prefix",
-      promptHint: "Optional subpath under the selected surface pages root (example: crm or ops/team-a)."
-    },
-    "route-path": {
-      required: false,
-      inputType: "text",
-      defaultValue: "",
-      promptLabel: "Route path",
-      promptHint:
-        "Optional explicit container route path (example: contact-tools or contacts/[contactId]). Defaults to --name."
+      promptLabel: "Force overwrite",
+      promptHint: "Overwrite the generated file if it already exists."
     },
     placement: {
       required: false,
       inputType: "text",
       defaultValue: "",
       promptLabel: "Placement target",
-      promptHint: "Optional host:position target (defaults to app ShellOutlet default target)."
+      promptHint: "Optional host:position target for placed-element placement (defaults to shell-layout:top-right)."
     },
-    "placement-component-token": {
+    "link-placement": {
       required: false,
       inputType: "text",
       defaultValue: "",
-      promptLabel: "Placement component token",
-      promptHint:
-        "Optional component token override for generated menu placement (example: local.main.ui.tab-link-item)."
+      promptLabel: "Link placement",
+      promptHint: "Optional host:position target for the generated page link placement."
     },
-    "placement-to": {
+    "link-component-token": {
       required: false,
       inputType: "text",
       defaultValue: "",
-      promptLabel: "Placement to",
+      promptLabel: "Link component token",
       promptHint:
-        "Optional explicit props.to value for generated menu placement (example: ./notes). If omitted and directory-prefix includes a nestedChildren route group, defaults to ./<page-slug>."
+        "Optional component token override for the generated page link placement (example: local.main.ui.tab-link-item)."
     },
-    file: {
+    "link-to": {
       required: false,
       inputType: "text",
       defaultValue: "",
-      promptLabel: "Target Vue file",
-      promptHint: "Vue SFC path relative to app root (used by outlet subcommand)."
+      promptLabel: "Link to",
+      promptHint:
+        "Optional explicit props.to value for the generated page link placement (example: ./notes). If omitted for pages under a detected parent subpages host, it is inferred from the page path."
     },
-    host: {
+    target: {
       required: false,
       inputType: "text",
       defaultValue: "",
-      promptLabel: "Outlet host",
-      promptHint: "ShellOutlet host value to inject into target file."
+      promptLabel: "Outlet target",
+      promptHint:
+        "Used by add-subpages and outlet. Accepts host or host:position. If only host is given, position defaults to sub-pages."
     },
-    position: {
+    title: {
       required: false,
       inputType: "text",
-      defaultValue: "sub-pages",
-      promptLabel: "Outlet position",
-      promptHint: "ShellOutlet position value to inject into target file."
+      defaultValue: "",
+      promptLabel: "Section title",
+      promptHint: "Optional SectionContainerShell title override for add-subpages."
     },
-    mode: {
+    subtitle: {
       required: false,
       inputType: "text",
-      defaultValue: "routed",
-      promptLabel: "Outlet mode",
-      promptHint: "routed | outlet-only (routed injects RouterView when missing)."
+      defaultValue: "",
+      promptLabel: "Section subtitle",
+      promptHint: "Optional SectionContainerShell subtitle override for add-subpages."
     }
   },
   dependsOn: [],
@@ -110,27 +105,157 @@ export default Object.freeze({
     generatorPrimarySubcommand: "page",
     generatorSubcommands: {
       page: {
-        description: "Scaffold a non-CRUD page and add a menu placement entry.",
-        optionNames: ["name", "surface", "directory-prefix", "placement", "placement-component-token", "placement-to"]
+        entrypoint: "src/server/subcommands/page.js",
+        export: "runGeneratorSubcommand",
+        description: "Create a route page at an explicit target file and add a link placement entry for it.",
+        longDescription: [
+          "This command always creates one route page file. By default, its page link is placed from the page path itself.",
+          "If an ancestor page has already been enhanced with sub-pages, JSKIT treats that ancestor as the real host. In that case the new page is linked into the nearest parent sub-pages outlet instead of the shell menu.",
+          "That means the generated link normally becomes a tab or child-page link under that ancestor host, and `props.to` is inferred relative to that host. If the host page is `index.vue`, child pages belong under `index/...` so the router keeps the parent page visible while the child route renders underneath it."
+        ],
+        positionalArgs: [
+          {
+            name: "target-file",
+            required: true,
+            descriptionKey: "page-target-file"
+          }
+        ],
+        optionNames: ["name", "link-placement", "link-component-token", "link-to", "force"],
+        notes: [
+          "If a nearest parent subpages host is found, placement, link component token, and props.to are inferred automatically.",
+          "If the parent host page is index.vue, child pages belong under index/...",
+          "If the target page file already exists, rerun with --force to overwrite it."
+        ],
+        examples: [
+          {
+            label: "Common usage",
+            lines: [
+              "npx jskit generate ui-generator page \\",
+              "  admin/reports/index.vue \\",
+              "  --name \"Reports\""
+            ]
+          },
+          {
+            label: "More advanced usage",
+            lines: [
+              "npx jskit generate ui-generator page \\",
+              "  admin/customers/[customerId]/index/notes/index.vue \\",
+              "  --name \"Notes\" \\",
+              "  --force"
+            ]
+          }
+        ]
       },
-      element: {
+      "placed-element": {
         entrypoint: "src/server/subcommands/element.js",
         export: "runGeneratorSubcommand",
-        description: "Scaffold a reusable UI element component and register a placement.",
-        optionNames: ["name", "surface", "path", "placement"]
+        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"],
+        notes: [
+          "If --placement is omitted, the placed element is added at shell-layout:top-right.",
+          "If the component file already exists, rerun with --force to overwrite it."
+        ],
+        examples: [
+          {
+            label: "Common usage",
+            lines: [
+              "npx jskit generate ui-generator placed-element \\",
+              "  --name \"Alerts Widget\" \\",
+              "  --surface admin"
+            ]
+          },
+          {
+            label: "More advanced usage",
+            lines: [
+              "npx jskit generate ui-generator placed-element \\",
+              "  --name \"Ops Panel\" \\",
+              "  --surface admin \\",
+              "  --path src/widgets \\",
+              "  --placement shell-layout:top-right \\",
+              "  --force"
+            ]
+          }
+        ]
       },
-      container: {
-        entrypoint: "src/server/subcommands/container.js",
+      "add-subpages": {
+        entrypoint: "src/server/subcommands/addSubpages.js",
         export: "runGeneratorSubcommand",
-        description: "Scaffold a routed section container page with a tab outlet. Adds a menu entry only when --placement is passed.",
-        optionNames: ["name", "surface", "directory-prefix", "route-path", "path", "placement"]
+        description: "Upgrade an existing page into a routed subpage host with SectionContainerShell, ShellOutlet, and RouterView.",
+        positionalArgs: [
+          {
+            name: "target-file",
+            required: true,
+            descriptionKey: "existing-page-target-file"
+          }
+        ],
+        optionNames: ["target", "path", "title", "subtitle"],
+        notes: [
+          "Use this when the page should render shared content plus child routes below it.",
+          "If the host page is index.vue, create child pages under index/..."
+        ],
+        examples: [
+          {
+            label: "Common usage",
+            lines: [
+              "npx jskit generate ui-generator add-subpages \\",
+              "  admin/customers/[customerId]/index.vue \\",
+              "  --title \"Customer\" \\",
+              "  --subtitle \"View and manage this customer.\""
+            ]
+          },
+          {
+            label: "More advanced usage",
+            lines: [
+              "npx jskit generate ui-generator add-subpages \\",
+              "  admin/contacts/[contactId]/index.vue \\",
+              "  --target contact-view:summary-tabs \\",
+              "  --path src/components/admin \\",
+              "  --title \"Contact\" \\",
+              "  --subtitle \"Manage contact modules.\""
+            ]
+          }
+        ]
       },
       outlet: {
         entrypoint: "src/server/subcommands/outlet.js",
         export: "runGeneratorSubcommand",
-        description: "Inject a ShellOutlet block into an existing Vue page/component.",
-        optionNames: ["file", "host", "position", "mode"],
-        requiredOptionNames: ["file", "host"]
+        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 it as `host:position`. That makes the target 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 `host:position`."
+        ],
+        positionalArgs: [
+          {
+            name: "target-file",
+            required: true,
+            descriptionKey: "existing-vue-sfc-target-file"
+          }
+        ],
+        optionNames: ["target"],
+        requiredOptionNames: ["target"],
+        notes: [
+          "Use --target host or --target host:position. If only host is given, position defaults to sub-pages."
+        ],
+        examples: [
+          {
+            label: "Common usage",
+            lines: [
+              "npx jskit generate ui-generator outlet \\",
+              "  src/components/ContactSummaryCard.vue \\",
+              "  --target contact-view"
+            ]
+          },
+          {
+            label: "More advanced usage",
+            lines: [
+              "npx jskit generate ui-generator outlet \\",
+              "  src/pages/admin/customers/[customerId]/index.vue \\",
+              "  --target customer-view:summary-actions"
+            ]
+          }
+        ]
       }
     },
     apiSummary: {
@@ -149,7 +274,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/users-web": "0.1.46"
+        "@jskit-ai/users-web": "0.1.47"
       },
       dev: {}
     },
@@ -157,32 +282,7 @@ export default Object.freeze({
       scripts: {}
     },
     procfile: {},
-    files: [
-      {
-        from: "templates/src/pages/admin/ui-generator/Page.vue",
-        toSurface: "${option:surface|lower}",
-        toSurfacePath: "${option:directory-prefix|pathprefix}${option:name|path}/index.vue",
-        reason: "Install generated UI page scaffold.",
-        category: "ui-generator",
-        id: "ui-generator-page-${option:name|snake}"
-      }
-    ],
-    text: [
-      {
-        op: "append-text",
-        file: "src/placement.js",
-        position: "bottom",
-        skipIfContains: "jskit:ui-generator.page.menu:${option:surface|lower}:${option:directory-prefix|path}:${option:name|path}",
-        value:
-          "\n// jskit:ui-generator.page.menu:${option:surface|lower}:${option:directory-prefix|path}:${option:name|path}\n{\n  addPlacement({\n    id: \"__JSKIT_UI_MENU_PLACEMENT_ID__\",\n    host: \"__JSKIT_UI_MENU_PLACEMENT_HOST__\",\n    position: \"__JSKIT_UI_MENU_PLACEMENT_POSITION__\",\n    surfaces: [\"${option:surface|lower}\"],\n    order: 155,\n    componentToken: \"__JSKIT_UI_MENU_COMPONENT_TOKEN__\",\n    props: {\n      label: \"${option:name|trim}\",\n      surface: \"${option:surface|lower}\",\n      workspaceSuffix: \"__JSKIT_UI_MENU_WORKSPACE_SUFFIX__\",\n      nonWorkspaceSuffix: \"__JSKIT_UI_MENU_NON_WORKSPACE_SUFFIX__\",\n__JSKIT_UI_MENU_TO_PROP_LINE__    },\n    when: ({ auth }) => Boolean(auth?.authenticated)\n  });\n}\n",
-        reason: "Append generated UI page menu placement.",
-        category: "ui-generator",
-        id: "ui-generator-page-placement-menu-${option:name|snake}",
-        templateContext: {
-          entrypoint: "src/server/buildTemplateContext.js",
-          export: "buildUiPageTemplateContext"
-        }
-      }
-    ]
+    files: [],
+    text: []
   }
 });

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@jskit-ai/ui-generator",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.31"
+    "@jskit-ai/kernel": "0.1.32"
   },
   "exports": {
     "./server/buildTemplateContext": "./src/server/buildTemplateContext.js"

package/src/server/buildTemplateContext.js

@@ -1,148 +1,43 @@
-import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-import { resolveShellOutletPlacementTargetFromApp } from "@jskit-ai/kernel/server/support";
+import {
+  resolvePageLinkTargetDetails,
+  resolvePageTargetDetails
+} from "@jskit-ai/kernel/server/support";
 
-const DEFAULT_MENU_COMPONENT_TOKEN = "users.web.shell.surface-aware-menu-link-item";
-const NESTED_CHILDREN_GROUPS = new Set(["nestedchildren", "nested-children"]);
-
-function splitTextIntoWords(value = "") {
-  const normalized = String(value || "")
-    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
-    .replace(/[^A-Za-z0-9]+/g, " ")
-    .trim();
-  if (!normalized) {
-    return [];
-  }
-  return normalized
-    .split(/\s+/)
-    .map((entry) => entry.toLowerCase())
-    .filter(Boolean);
-}
-
-function wordsToKebab(words = []) {
-  return (Array.isArray(words) ? words : [])
-    .map((entry) => String(entry || "").toLowerCase())
-    .filter(Boolean)
-    .join("-");
-}
-
-function normalizePathValue(value = "") {
-  return String(value || "")
-    .replaceAll("\\", "/")
-    .split("/")
-    .map((segment) => {
-      const normalizedSegment = normalizeText(segment);
-      if (!normalizedSegment) {
-        return "";
-      }
-      if (/^\[[^\]]+\]$/.test(normalizedSegment)) {
-        return normalizedSegment;
-      }
-      const routeGroupMatch = /^\(([^()]+)\)$/.exec(normalizedSegment);
-      if (routeGroupMatch) {
-        const routeGroupName = wordsToKebab(splitTextIntoWords(routeGroupMatch[1]));
-        return routeGroupName ? `(${routeGroupName})` : "";
-      }
-      return wordsToKebab(splitTextIntoWords(normalizedSegment));
-    })
-    .filter(Boolean)
-    .join("/");
-}
-
-function splitPathSegments(value = "") {
-  return normalizePathValue(value)
-    .split("/")
-    .map((entry) => normalizeText(entry))
-    .filter(Boolean);
-}
-
-function isRouteGroupSegment(value = "") {
-  const source = normalizeText(value);
-  return source.startsWith("(") && source.endsWith(")");
-}
-
-function isNestedChildrenRouteGroupSegment(value = "") {
-  const source = normalizeText(value);
-  if (!isRouteGroupSegment(source)) {
-    return false;
-  }
-  const groupName = source.slice(1, -1).trim().toLowerCase();
-  return NESTED_CHILDREN_GROUPS.has(groupName);
-}
-
-function resolvePlacementUrlSuffix(options = {}) {
-  const routeSegments = [
-    ...splitPathSegments(options?.["directory-prefix"]),
-    ...splitPathSegments(options?.name)
-  ].filter((segment) => !isRouteGroupSegment(segment));
-  if (routeSegments.length < 1) {
-    return "/";
-  }
-  return `/${routeSegments.join("/")}`;
-}
-
-function resolveMenuComponentToken(options = {}) {
-  const explicitToken = normalizeText(options?.["placement-component-token"]);
-  if (explicitToken) {
-    return explicitToken;
-  }
-  return DEFAULT_MENU_COMPONENT_TOKEN;
-}
-
-function resolveAutoRelativePlacementTo(options = {}) {
-  const explicitPlacementTo = normalizeText(options?.["placement-to"]);
-  if (explicitPlacementTo) {
-    return explicitPlacementTo;
-  }
-  const directorySegments = splitPathSegments(options?.["directory-prefix"]);
-  const hasNestedChildrenGroup = directorySegments.some((segment) => isNestedChildrenRouteGroupSegment(segment));
-  if (!hasNestedChildrenGroup) {
+function resolveLinkToPropLine(linkTo = "") {
+  if (!linkTo) {
     return "";
   }
-  const pagePath = normalizePathValue(options?.name);
-  if (!pagePath) {
-    return "";
-  }
-  return `./${pagePath}`;
+  return `      to: ${JSON.stringify(linkTo)},\n`;
 }
 
-function resolveMenuToPropLine(options = {}) {
-  const placementTo = resolveAutoRelativePlacementTo(options);
-  if (!placementTo) {
-    return "";
-  }
-  return `      to: ${JSON.stringify(placementTo)},\n`;
-}
-
-function normalizePlacementIdSegment(value = "") {
-  return wordsToKebab(splitTextIntoWords(value));
-}
-
-function resolveMenuPlacementId(options = {}) {
-  const idSegments = [
-    ...splitPathSegments(options?.["directory-prefix"]),
-    ...splitPathSegments(options?.name)
-  ]
-    .map((segment) => normalizePlacementIdSegment(segment))
-    .filter(Boolean);
-
-  return `ui-generator.page.${idSegments.join(".")}.menu`;
-}
-
-async function buildUiPageTemplateContext({ appRoot, options } = {}) {
-  const placementTarget = await resolveShellOutletPlacementTargetFromApp({
+async function buildUiPageTemplateContext({
+  appRoot,
+  targetFile = "",
+  options = {}
+} = {}) {
+  const pageTarget = await resolvePageTargetDetails({
     appRoot,
-    context: "ui-generator",
-    placement: options?.placement
+    targetFile,
+    context: "ui-generator page"
+  });
+  const linkTarget = await resolvePageLinkTargetDetails({
+    appRoot: pageTarget.appRoot,
+    pageTarget,
+    targetFile,
+    context: "ui-generator page",
+    placement: options?.["link-placement"],
+    componentToken: options?.["link-component-token"],
+    linkTo: options?.["link-to"]
   });
 
   return {
-    __JSKIT_UI_MENU_PLACEMENT_ID__: resolveMenuPlacementId(options),
-    __JSKIT_UI_MENU_PLACEMENT_HOST__: normalizeText(placementTarget?.host),
-    __JSKIT_UI_MENU_PLACEMENT_POSITION__: normalizeText(placementTarget?.position),
-    __JSKIT_UI_MENU_COMPONENT_TOKEN__: resolveMenuComponentToken(options),
-    __JSKIT_UI_MENU_WORKSPACE_SUFFIX__: resolvePlacementUrlSuffix(options),
-    __JSKIT_UI_MENU_NON_WORKSPACE_SUFFIX__: resolvePlacementUrlSuffix(options),
-    __JSKIT_UI_MENU_TO_PROP_LINE__: resolveMenuToPropLine(options)
+    __JSKIT_UI_LINK_PLACEMENT_ID__: pageTarget.placementId,
+    __JSKIT_UI_LINK_PLACEMENT_HOST__: String(linkTarget.placementTarget?.host || ""),
+    __JSKIT_UI_LINK_PLACEMENT_POSITION__: String(linkTarget.placementTarget?.position || ""),
+    __JSKIT_UI_LINK_COMPONENT_TOKEN__: String(linkTarget.componentToken || ""),
+    __JSKIT_UI_LINK_WORKSPACE_SUFFIX__: pageTarget.routeUrlSuffix,
+    __JSKIT_UI_LINK_NON_WORKSPACE_SUFFIX__: pageTarget.routeUrlSuffix,
+    __JSKIT_UI_LINK_TO_PROP_LINE__: resolveLinkToPropLine(linkTarget.linkTo)
   };
 }
 

package/src/server/subcommands/addSubpages.js

@@ -0,0 +1,73 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  DEFAULT_COMPONENT_DIRECTORY,
+  DEFAULT_SUBPAGES_POSITION,
+  deriveDefaultSubpagesHost,
+  resolvePageTargetDetails,
+  upgradePageFileToSubpages
+} from "./pageSupport.js";
+import {
+  requireSinglePositionalTargetFile,
+  resolveOutletTargetId,
+  rejectUnexpectedOptions
+} from "./support.js";
+
+function resolveSubpagesOutletTarget(options = {}, pageTarget = {}) {
+  const rawTarget = normalizeText(options?.target);
+  return resolveOutletTargetId(rawTarget || deriveDefaultSubpagesHost(pageTarget), {
+    context: "ui-generator add-subpages",
+    optionName: "target",
+    defaultPosition: DEFAULT_SUBPAGES_POSITION
+  });
+}
+
+async function runGeneratorSubcommand({
+  appRoot,
+  subcommand = "",
+  args = [],
+  options = {},
+  dryRun = false
+} = {}) {
+  const normalizedSubcommand = normalizeText(subcommand).toLowerCase();
+  if (normalizedSubcommand !== "add-subpages") {
+    throw new Error(`Unsupported ui-generator subcommand: ${normalizedSubcommand || "<empty>"}.`);
+  }
+  const targetFile = requireSinglePositionalTargetFile(args, { context: "ui-generator add-subpages" });
+  rejectUnexpectedOptions(
+    options,
+    ["target", "path", "title", "subtitle"],
+    { context: "ui-generator add-subpages" }
+  );
+
+  const componentDirectory = normalizeText(options?.path) || DEFAULT_COMPONENT_DIRECTORY;
+  const title = normalizeText(options?.title);
+  const subtitle = normalizeText(options?.subtitle);
+  const pageTarget = await resolvePageTargetDetails({
+    appRoot,
+    targetFile,
+    context: "ui-generator add-subpages"
+  });
+  const outletTarget = resolveSubpagesOutletTarget(options, pageTarget);
+
+  const result = await upgradePageFileToSubpages({
+    appRoot,
+    targetFile,
+    host: outletTarget.host,
+    position: outletTarget.position,
+    title,
+    subtitle,
+    componentDirectory,
+    preserveExistingContent: true,
+    dryRun
+  });
+
+  return {
+    touchedFiles: result.touchedFiles,
+    summary:
+      result.touchedFiles.length > 0
+        ? `Enabled subpages in ${result.targetFile} for "${pageTarget.routeUrlSuffix}" using outlet target "${outletTarget.id}".`
+        : `Subpages are already enabled in ${result.targetFile}.`
+  };
+}
+
+export { runGeneratorSubcommand };