@jskit-ai/ui-generator 0.1.5 → 0.1.6

package/README.md

@@ -46,28 +46,128 @@ Generate a route container page with nested outlet (for embedded sub-pages):
 npx jskit generate @jskit-ai/ui-generator container --name "Practice" --surface admin
 ```
 
+Generate a route container with explicit dynamic route path:
+
+```bash
+npx jskit generate @jskit-ai/ui-generator container --name "Contact" --surface admin --directory-prefix contacts --route-path "[contactId]"
+```
+
+Add a shell menu entry for that container (optional):
+
+```bash
+npx jskit generate @jskit-ai/ui-generator container --name "Practice" --surface admin --placement shell-layout:primary-menu
+```
+
+Inject an inline outlet into an existing Vue page/component:
+
+```bash
+npx jskit generate @jskit-ai/ui-generator outlet --file src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/index.vue --host contact-view
+```
+
+Show generator and subcommand help:
+
+```bash
+npx jskit generate @jskit-ai/ui-generator help
+npx jskit generate @jskit-ai/ui-generator outlet help
+npx jskit generate @jskit-ai/ui-generator outlet
+```
+
 ## Commands
 
 - `page`: `--name --surface [--directory-prefix] [--placement]`
 - `element`: `--name --surface [--path] [--placement]`
-- `container`: `--name --surface [--directory-prefix] [--placement]`
+- `container`: `--name --surface [--directory-prefix] [--route-path] [--placement]`
+- `outlet`: `--file --host [--position] [--mode]`
+
+`page` also supports:
+
+- `--placement-component-token` to override the placement component token.
+- `--placement-to` to set explicit `props.to` in the generated placement block.
+- if `--placement-to` is omitted and `--directory-prefix` includes a `(nestedChildren)` route group, `props.to` is auto-set to `./<page-slug>`.
 
 ## Container Workflow
 
 - `container` creates app-owned scaffolding:
   - `src/components/SectionContainerShell.vue` (shared container shell with responsive tab row)
-  - `src/components/SectionShellTabLinkItem.vue` (tab link item token component)
-  - `packages/main/src/client/providers/MainClientProvider.js` registration for `local.main.ui.section-shell.tab-link-item`
-  - `<route>.vue` as a thin wrapper around `SectionContainerShell` + `<RouterView />`
+  - `src/components/TabLinkItem.vue` (tab link item token component)
+  - `packages/main/src/client/providers/MainClientProvider.js` registration for `local.main.ui.tab-link-item`
+  - `<route>.vue` as a thin wrapper around `SectionContainerShell` + `<RouterView />`, with route meta outlet declaration at `meta.jskit.placements.outlets`
+  - no shell menu placement is added unless `--placement` is explicitly provided
 - Generate CRUD pages into that container using `@jskit-ai/crud-ui-generator` with:
   - `--container <route-slug>`
   - `--route-path <resource-slug>`
   - optional `--placement` override (default becomes `<container>:sub-pages` for list pages)
 
+## Inline Outlet Workflow
+
+- `outlet` patches an app-owned Vue SFC by adding:
+  - `import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";`
+  - `<ShellOutlet host="<host>" position="<position>" />` in template
+  - optional `<RouterView />` (when `--mode routed`, only if one does not already exist in the file)
+- `--mode` supports:
+  - `routed` (default): insert `RouterView` if missing
+  - `outlet-only`: insert only `ShellOutlet`
+
+## End-to-End Example: Embed Pets CRUD in Contact View
+
+Goal: render pets CRUD pages inside `contacts/[contactId]/index.vue` using a routed outlet and tab-style placement links.
+
+1. Inject a routed outlet into the contact page:
+
+```bash
+npx jskit generate ui-generator outlet \
+  --file src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/index.vue \
+  --host contact-view \
+  --position sub-pages \
+  --mode routed
+```
+
+What each option does:
+
+- `--file`: target Vue SFC to patch.
+- `--host`: outlet host namespace (used later by placements).
+- `--position`: outlet position key under that host.
+- `--mode routed`: ensures `<RouterView />` exists so nested pages render inline.
+
+2. Generate pets CRUD pages under the nested-children group and place a tab link into that outlet:
+
+```bash
+npx jskit generate crud-ui-generator \
+  --namespace pets \
+  --surface admin \
+  --operations list,view,new,edit \
+  --resource-file packages/pets/src/shared/petResource.js \
+  --directory-prefix "contacts/[contactId]/(nestedChildren)" \
+  --placement contact-view:sub-pages \
+  --placement-component-token local.main.ui.tab-link-item \
+  --placement-to ./pets \
+  --id-param petId
+```
+
+What each option does:
+
+- `--namespace pets`: CRUD namespace for generated UI artifacts.
+- `--surface admin`: generate pages under admin surface routes.
+- `--operations list,view,new,edit`: generate full CRUD page set.
+- `--resource-file`: resource contract used to scaffold fields/forms.
+- `--directory-prefix "contacts/[contactId]/(nestedChildren)"`: place generated routes under the contact context, in a route-group folder that does not appear in URL.
+- `--placement contact-view:sub-pages`: append a placement targeting the outlet created in step 1.
+- `--placement-component-token local.main.ui.tab-link-item`: render placement as a tab link component.
+- `--placement-to ./pets`: tab link resolves relative to current contact route (for example `/contacts/538779/pets`).
+- `--id-param petId`: dynamic route parameter for view/edit pages.
+
+Expected result:
+
+- Contact page keeps its own route and renders nested pets pages inline via `RouterView`.
+- Pets routes are generated under `contacts/[contactId]/(nestedChildren)/pets/...`.
+- URL remains clean (`(nestedChildren)` is not part of URL).
+- A placement entry is added so the pets tab appears in `contact-view:sub-pages`.
+
 ## Placement Notes
 
 - `--placement` expects `host:position`.
 - Targets come from:
   - app-declared `<ShellOutlet host="..." position="..." />` in `src/**/*.vue`
+  - app route meta `meta.jskit.placements.outlets` declarations in `src/**/*.vue`
   - installed package metadata `metadata.ui.placements.outlets`
 - If `--placement` is omitted, the app default outlet is used.

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/ui-generator",
-  version: "0.1.5",
+  version: "0.1.6",
   kind: "generator",
   description: "Generate app-local non-CRUD UI pages and outlet elements.",
   options: {
@@ -33,12 +33,64 @@ export default Object.freeze({
       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."
+    },
     placement: {
       required: false,
       inputType: "text",
       defaultValue: "",
       promptLabel: "Placement target",
       promptHint: "Optional host:position target (defaults to app ShellOutlet default target)."
+    },
+    "placement-component-token": {
+      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)."
+    },
+    "placement-to": {
+      required: false,
+      inputType: "text",
+      defaultValue: "",
+      promptLabel: "Placement to",
+      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>."
+    },
+    file: {
+      required: false,
+      inputType: "text",
+      defaultValue: "",
+      promptLabel: "Target Vue file",
+      promptHint: "Vue SFC path relative to app root (used by outlet subcommand)."
+    },
+    host: {
+      required: false,
+      inputType: "text",
+      defaultValue: "",
+      promptLabel: "Outlet host",
+      promptHint: "ShellOutlet host value to inject into target file."
+    },
+    position: {
+      required: false,
+      inputType: "text",
+      defaultValue: "sub-pages",
+      promptLabel: "Outlet position",
+      promptHint: "ShellOutlet position value to inject into target file."
+    },
+    mode: {
+      required: false,
+      inputType: "text",
+      defaultValue: "routed",
+      promptLabel: "Outlet mode",
+      promptHint: "routed | outlet-only (routed injects RouterView when missing)."
     }
   },
   dependsOn: [],
@@ -57,13 +109,28 @@ export default Object.freeze({
   metadata: {
     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"]
+      },
       element: {
         entrypoint: "src/server/subcommands/element.js",
-        export: "runGeneratorSubcommand"
+        export: "runGeneratorSubcommand",
+        description: "Scaffold a reusable UI element component and register a placement.",
+        optionNames: ["name", "surface", "path", "placement"]
       },
       container: {
         entrypoint: "src/server/subcommands/container.js",
-        export: "runGeneratorSubcommand"
+        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"]
+      },
+      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"]
       }
     },
     apiSummary: {
@@ -82,7 +149,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/users-web": "0.1.36"
+        "@jskit-ai/users-web": "0.1.37"
       },
       dev: {}
     },
@@ -107,7 +174,7 @@ export default Object.freeze({
         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: \"ui-generator.page.${option:name|kebab}.menu\",\n    host: \"__JSKIT_UI_MENU_PLACEMENT_HOST__\",\n    position: \"__JSKIT_UI_MENU_PLACEMENT_POSITION__\",\n    surfaces: [\"${option:surface|lower}\"],\n    order: 155,\n    componentToken: \"users.web.shell.surface-aware-menu-link-item\",\n    props: {\n      label: \"${option:name|trim}\",\n      surface: \"${option:surface|lower}\",\n      workspaceSuffix: \"/${option:directory-prefix|pathprefix}${option:name|path}\",\n      nonWorkspaceSuffix: \"/${option:directory-prefix|pathprefix}${option:name|path}\"\n    },\n    when: ({ auth }) => Boolean(auth?.authenticated)\n  });\n}\n",
+          "\n// jskit:ui-generator.page.menu:${option:surface|lower}:${option:directory-prefix|path}:${option:name|path}\n{\n  addPlacement({\n    id: \"ui-generator.page.${option:name|kebab}.menu\",\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}",

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@jskit-ai/ui-generator",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.22"
+    "@jskit-ai/kernel": "0.1.23"
   },
   "exports": {
     "./server/buildTemplateContext": "./src/server/buildTemplateContext.js"

package/src/server/buildTemplateContext.js

@@ -1,6 +1,118 @@
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { resolveShellOutletPlacementTargetFromApp } 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) {
+    return "";
+  }
+  const pagePath = normalizePathValue(options?.name);
+  if (!pagePath) {
+    return "";
+  }
+  return `./${pagePath}`;
+}
+
+function resolveMenuToPropLine(options = {}) {
+  const placementTo = resolveAutoRelativePlacementTo(options);
+  if (!placementTo) {
+    return "";
+  }
+  return `      to: ${JSON.stringify(placementTo)},\n`;
+}
+
 async function buildUiPageTemplateContext({ appRoot, options } = {}) {
   const placementTarget = await resolveShellOutletPlacementTargetFromApp({
     appRoot,
@@ -10,7 +122,11 @@ async function buildUiPageTemplateContext({ appRoot, options } = {}) {
 
   return {
     __JSKIT_UI_MENU_PLACEMENT_HOST__: normalizeText(placementTarget?.host),
-    __JSKIT_UI_MENU_PLACEMENT_POSITION__: normalizeText(placementTarget?.position)
+    __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)
   };
 }