@jskit-ai/crud-ui-generator 0.1.14 → 0.1.16

package/README.md

@@ -0,0 +1,67 @@
+# @jskit-ai/crud-ui-generator
+
+Generate CRUD route trees from an explicit route root relative to `src/pages/...`.
+
+## Mental Model
+
+This generator follows the same file-driven model as `@jskit-ai/ui-generator`.
+
+- You point at one explicit route root relative to `src/pages/...`.
+- The surface is derived from that path.
+- The visible route URL is derived from that path.
+- The generated list-page link placement is inferred from the nearest real parent subpages host when there is one.
+- Explicit overrides still exist, but they are not required for the normal case.
+
+## Command
+
+```bash
+npx jskit generate @jskit-ai/crud-ui-generator crud \
+  admin/catalog/index/products \
+  --resource-file packages/products/src/shared/productResource.js
+```
+
+That generates:
+
+- `src/pages/admin/catalog/index/products/index.vue`
+- `src/pages/admin/catalog/index/products/[recordId]/index.vue`
+- `src/pages/admin/catalog/index/products/new.vue`
+- `src/pages/admin/catalog/index/products/[recordId]/edit.vue`
+- `src/pages/admin/catalog/index/products/_components/...`
+
+## Defaults
+
+From the explicit `target-root`, the generator derives:
+
+- the owning surface
+- the visible CRUD route
+- the default list-page placement target
+- the default link component token
+- the default relative `to` for nested subpage links
+
+The generated list-page link follows the same parent-host inference as `@jskit-ai/ui-generator page`.
+
+If you want the detailed behavior, read:
+
+- `npx jskit generate ui-generator page help`
+
+That is where the parent-host, tab-link, and relative `to` behavior is explained.
+
+## Options
+
+- `--resource-file`: required resource module path relative to the app root
+- `--operations`: optional comma-separated subset of `list,view,new,edit`, defaulting to all four
+- `--display-fields`: optional comma-separated subset of fields to render
+- `--id-param`: optional route param name for record pages, default `recordId`
+- `--link-placement`: optional link placement override for the generated list page
+- `--namespace`: optional CRUD namespace override when the resource module does not expose `resource.resource`
+
+## Route Roots
+
+Use the real route root you want in the app:
+
+- index-route parent child: `admin/catalog/index/products`
+- nested under a record view page: `admin/customers/[customerId]/index/pets`
+- file-route parent child: `admin/customers/[customerId]/orders`
+- top-level route: `admin/products`
+
+There is no separate `surface`, `directory-prefix`, `route-path`, or `container` assembly step anymore.

package/package.descriptor.mjs

@@ -1,22 +1,17 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/crud-ui-generator",
-  version: "0.1.14",
+  version: "0.1.16",
   kind: "generator",
-  description: "Generate app-local CRUD UI scaffolds from resource validators.",
+  description: "Generate CRUD route trees from resource validators at an explicit route root relative to src/pages/.",
   options: {
-    namespace: {
+    "target-root": {
       required: true,
       inputType: "text",
       defaultValue: "",
-      promptLabel: "UI namespace",
-      promptHint: "Required slug (example: contacts-alt, customers-ui, tickets-view)."
-    },
-    surface: {
-      required: true,
-      inputType: "text",
-      promptLabel: "Target surface",
-      promptHint: "Must match an enabled surface id."
+      normalizationType: "pages-relative-target-root",
+      promptLabel: "Target route root",
+      promptHint: "Explicit route root relative to src/pages/ (example: admin/catalog/products)."
     },
     "resource-file": {
       required: true,
@@ -26,11 +21,11 @@ export default Object.freeze({
       promptHint: "Relative path from app root to the resource module."
     },
     operations: {
-      required: true,
+      required: false,
       inputType: "text",
-      defaultValue: "",
+      defaultValue: "list,view,new,edit",
       promptLabel: "Operations",
-      promptHint: "Required comma-separated values from: list, view, new, edit."
+      promptHint: "Optional comma-separated values from: list, view, new, edit. Defaults to all four."
     },
     "display-fields": {
       required: false,
@@ -39,28 +34,6 @@ export default Object.freeze({
       promptLabel: "Display fields",
       promptHint: "Optional comma-separated field keys to render (must exist in selected operation schemas)."
     },
-    "api-path": {
-      required: false,
-      inputType: "text",
-      defaultFromOptionTemplate: "/${option:namespace|kebab}",
-      promptLabel: "API path",
-      promptHint: "Base API path without trailing id (defaults to /<namespace>, example: /contacts)."
-    },
-    "route-path": {
-      required: false,
-      inputType: "text",
-      defaultFromOptionTemplate: "${option:namespace|kebab}",
-      promptLabel: "Route path",
-      promptHint: "List route path under the target surface (defaults to <namespace>, example: contacts)."
-    },
-    container: {
-      required: false,
-      inputType: "text",
-      defaultValue: "",
-      promptLabel: "Container host",
-      promptHint:
-        "Optional container host slug (example: practice). Routes are generated under this prefix and list menu placement defaults to <container>:sub-pages."
-    },
     "id-param": {
       required: false,
       inputType: "text",
@@ -68,35 +41,26 @@ export default Object.freeze({
       promptLabel: "Route id param",
       promptHint: "Route param used by view and edit pages (default: recordId)."
     },
-    "directory-prefix": {
+    force: {
       required: false,
-      inputType: "text",
-      defaultValue: "",
-      promptLabel: "Page directory prefix",
-      promptHint: "Optional subpath under the selected surface pages root (example: crm or ops/team-a)."
-    },
-    placement: {
-      required: false,
-      inputType: "text",
+      inputType: "flag",
       defaultValue: "",
-      promptLabel: "Menu placement",
-      promptHint: "Optional host:position target (defaults to ShellLayout default outlet)."
+      promptLabel: "Force overwrite",
+      promptHint: "Overwrite generated CRUD files if the target root already exists."
     },
-    "placement-component-token": {
+    "link-placement": {
       required: false,
       inputType: "text",
       defaultValue: "",
-      promptLabel: "Placement component token",
-      promptHint:
-        "Optional component token override for generated menu placement. Use local.main.ui.tab-link-item for routed tab links (auto-provisions src/components/TabLinkItem.vue + MainClientProvider registration)."
+      promptLabel: "Link placement",
+      promptHint: "Optional host:position override for the generated list-page link placement."
     },
-    "placement-to": {
+    namespace: {
       required: false,
       inputType: "text",
       defaultValue: "",
-      promptLabel: "Placement to",
-      promptHint:
-        "Optional explicit props.to value for generated menu placement (example: ./pets). Required when adding placement for dynamic directory-prefix/route-path values."
+      promptLabel: "Namespace override",
+      promptHint: "Optional CRUD namespace override when the resource export does not expose resource.resource."
     }
   },
   dependsOn: [],
@@ -115,6 +79,53 @@ export default Object.freeze({
   metadata: {
     generatorPrimarySubcommand: "crud",
     generatorSubcommands: {
+      crud: {
+        description: "Create CRUD pages at an explicit route root relative to src/pages/.",
+        longDescription: [
+          "CRUD generation follows the same page-placement model as `ui-generator page`.",
+          "That means the generated list page link uses the same nearest-parent-host inference, tab-link inference, and relative `props.to` inference as a normal generated page. If you want the detailed host behavior, read `jskit generate ui-generator page help`."
+        ],
+        positionalArgs: [
+          {
+            name: "target-root",
+            required: true,
+            descriptionKey: "crud-target-root"
+          }
+        ],
+        optionNames: ["resource-file", "operations", "display-fields", "id-param", "link-placement", "namespace", "force"],
+        requiredOptionNames: ["resource-file"],
+        createTarget: {
+          pathTemplate: "src/pages/${option:target-root|trim}",
+          label: "target root",
+          allowExistingEmptyDirectory: true
+        },
+        notes: [
+          "The target root is the real route root relative to src/pages/.... JSKIT derives the surface and route from that path.",
+          "Operations default to list,view,new,edit. For list-page placement behavior, use the same mental model as ui-generator page.",
+          "If the target root already exists and is not empty, rerun with --force to overwrite generated files."
+        ],
+        examples: [
+          {
+            label: "Common usage",
+            lines: [
+              "npx jskit generate crud-ui-generator crud \\",
+              "  admin/catalog/index/products \\",
+              "  --resource-file packages/products/src/shared/productResource.js"
+            ]
+          },
+          {
+            label: "More advanced usage",
+            lines: [
+              "npx jskit generate crud-ui-generator crud \\",
+              "  admin/customers/[customerId]/index/pets \\",
+              "  --resource-file packages/pets/src/shared/petResource.js \\",
+              "  --id-param petId \\",
+              "  --display-fields name,breedId,sex \\",
+              "  --force"
+            ]
+          }
+        ]
+      },
       field: {
         entrypoint: "src/server/subcommands/addField.js",
         export: "runGeneratorSubcommand"
@@ -124,7 +135,7 @@ export default Object.freeze({
       surfaces: [
         {
           subpath: "./server/buildTemplateContext",
-          summary: "Builds deterministic template context values from selected resource operation validators."
+          summary: "Builds deterministic CRUD UI template context values from the explicit route root and resource validators."
         }
       ],
       containerTokens: {
@@ -136,7 +147,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/users-web": "0.1.46"
+        "@jskit-ai/users-web": "0.1.48"
       },
       dev: {}
     },
@@ -147,11 +158,10 @@ export default Object.freeze({
     files: [
       {
         from: "templates/src/pages/admin/ui-generator/ListElement.vue",
-        toSurface: "${option:surface|lower}",
-        toSurfacePath: "${option:directory-prefix|pathprefix}${option:container|pathprefix}${option:route-path|path}/index.vue",
+        to: "src/pages/${option:target-root|trim}/index.vue",
         reason: "Install generated list page.",
-        category: "ui-generator",
-        id: "ui-generator-page-list-${option:namespace|snake}",
+        category: "crud-ui-generator",
+        id: "crud-ui-page-list-${option:target-root|snake}",
         templateContext: {
           entrypoint: "src/server/buildTemplateContext.js",
           export: "buildUiTemplateContext"
@@ -163,12 +173,10 @@ export default Object.freeze({
       },
       {
         from: "templates/src/pages/admin/ui-generator/ViewElement.vue",
-        toSurface: "${option:surface|lower}",
-        toSurfacePath:
-          "${option:directory-prefix|pathprefix}${option:container|pathprefix}${option:route-path|path}/[${option:id-param|trim}]/index.vue",
+        to: "src/pages/${option:target-root|trim}/[${option:id-param|trim}]/index.vue",
         reason: "Install generated view page.",
-        category: "ui-generator",
-        id: "ui-generator-page-view-${option:namespace|snake}",
+        category: "crud-ui-generator",
+        id: "crud-ui-page-view-${option:target-root|snake}",
         templateContext: {
           entrypoint: "src/server/buildTemplateContext.js",
           export: "buildUiTemplateContext"
@@ -180,11 +188,10 @@ export default Object.freeze({
       },
       {
         from: "templates/src/pages/admin/ui-generator/NewWrapperElement.vue",
-        toSurface: "${option:surface|lower}",
-        toSurfacePath: "${option:directory-prefix|pathprefix}${option:container|pathprefix}${option:route-path|path}/new.vue",
+        to: "src/pages/${option:target-root|trim}/new.vue",
         reason: "Install generated new page.",
-        category: "ui-generator",
-        id: "ui-generator-page-new-${option:namespace|snake}",
+        category: "crud-ui-generator",
+        id: "crud-ui-page-new-${option:target-root|snake}",
         templateContext: {
           entrypoint: "src/server/buildTemplateContext.js",
           export: "buildUiTemplateContext"
@@ -204,12 +211,10 @@ export default Object.freeze({
       },
       {
         from: "templates/src/pages/admin/ui-generator/EditWrapperElement.vue",
-        toSurface: "${option:surface|lower}",
-        toSurfacePath:
-          "${option:directory-prefix|pathprefix}${option:container|pathprefix}${option:route-path|path}/[${option:id-param|trim}]/edit.vue",
+        to: "src/pages/${option:target-root|trim}/[${option:id-param|trim}]/edit.vue",
         reason: "Install generated edit page.",
-        category: "ui-generator",
-        id: "ui-generator-page-edit-${option:namespace|snake}",
+        category: "crud-ui-generator",
+        id: "crud-ui-page-edit-${option:target-root|snake}",
         templateContext: {
           entrypoint: "src/server/buildTemplateContext.js",
           export: "buildUiTemplateContext"
@@ -229,12 +234,10 @@ export default Object.freeze({
       },
       {
         from: "templates/src/pages/admin/ui-generator/AddEditForm.vue",
-        toSurface: "${option:surface|lower}",
-        toSurfacePath:
-          "${option:directory-prefix|pathprefix}${option:container|pathprefix}${option:route-path|path}/_components/${option:namespace|singular|pascal|default(Record)}AddEditForm.vue",
+        to: "src/pages/${option:target-root|trim}/_components/CrudAddEditForm.vue",
         reason: "Install generated shared add/edit form component.",
-        category: "ui-generator",
-        id: "ui-generator-page-add-edit-form-${option:namespace|snake}",
+        category: "crud-ui-generator",
+        id: "crud-ui-page-add-edit-form-${option:target-root|snake}",
         templateContext: {
           entrypoint: "src/server/buildTemplateContext.js",
           export: "buildUiTemplateContext"
@@ -254,12 +257,10 @@ export default Object.freeze({
       },
       {
         from: "templates/src/pages/admin/ui-generator/AddEditFormFields.js",
-        toSurface: "${option:surface|lower}",
-        toSurfacePath:
-          "${option:directory-prefix|pathprefix}${option:container|pathprefix}${option:route-path|path}/_components/${option:namespace|singular|pascal|default(Record)}AddEditFormFields.js",
+        to: "src/pages/${option:target-root|trim}/_components/CrudAddEditFormFields.js",
         reason: "Install generated shared add/edit form field definitions.",
-        category: "ui-generator",
-        id: "ui-generator-page-add-edit-form-fields-${option:namespace|snake}",
+        category: "crud-ui-generator",
+        id: "crud-ui-page-add-edit-form-fields-${option:target-root|snake}",
         templateContext: {
           entrypoint: "src/server/buildTemplateContext.js",
           export: "buildUiTemplateContext"
@@ -279,11 +280,10 @@ export default Object.freeze({
       },
       {
         from: "templates/src/pages/admin/ui-generator/NewElement.vue",
-        toSurface: "${option:surface|lower}",
-        toSurfacePath: "${option:directory-prefix|pathprefix}${option:container|pathprefix}${option:route-path|path}/new.vue",
+        to: "src/pages/${option:target-root|trim}/new.vue",
         reason: "Install generated new page.",
-        category: "ui-generator",
-        id: "ui-generator-page-new-standalone-${option:namespace|snake}",
+        category: "crud-ui-generator",
+        id: "crud-ui-page-new-standalone-${option:target-root|snake}",
         templateContext: {
           entrypoint: "src/server/buildTemplateContext.js",
           export: "buildUiTemplateContext"
@@ -303,12 +303,10 @@ export default Object.freeze({
       },
       {
         from: "templates/src/pages/admin/ui-generator/EditElement.vue",
-        toSurface: "${option:surface|lower}",
-        toSurfacePath:
-          "${option:directory-prefix|pathprefix}${option:container|pathprefix}${option:route-path|path}/[${option:id-param|trim}]/edit.vue",
+        to: "src/pages/${option:target-root|trim}/[${option:id-param|trim}]/edit.vue",
         reason: "Install generated edit page.",
-        category: "ui-generator",
-        id: "ui-generator-page-edit-standalone-${option:namespace|snake}",
+        category: "crud-ui-generator",
+        id: "crud-ui-page-edit-standalone-${option:target-root|snake}",
         templateContext: {
           entrypoint: "src/server/buildTemplateContext.js",
           export: "buildUiTemplateContext"
@@ -332,52 +330,19 @@ export default Object.freeze({
         op: "append-text",
         file: "src/placement.js",
         position: "bottom",
-        skipIfContains:
-          "jskit:ui-generator.menu:${option:namespace|kebab}:${option:directory-prefix|path}:${option:container|path}:${option:route-path|path}",
+        skipIfContains: "__JSKIT_UI_MENU_MARKER__",
         value:
-          "\n// jskit:ui-generator.menu:${option:namespace|kebab}:${option:directory-prefix|path}:${option:container|path}:${option:route-path|path}\n{\n  addPlacement({\n    id: \"ui-generator.${option:namespace|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:namespace|plural|pascal}\",\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 menu placement.",
-        category: "ui-generator",
-        id: "ui-generator-placement-menu",
+          "\n// __JSKIT_UI_MENU_MARKER__\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: [\"__JSKIT_UI_SURFACE_ID__\"],\n    order: 155,\n    componentToken: \"__JSKIT_UI_MENU_COMPONENT_TOKEN__\",\n    props: {\n      label: \"__JSKIT_UI_MENU_LABEL__\",\n      surface: \"__JSKIT_UI_SURFACE_ID__\",\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 CRUD list-page placement.",
+        category: "crud-ui-generator",
+        id: "crud-ui-placement-menu",
         templateContext: {
           entrypoint: "src/server/buildTemplateContext.js",
           export: "buildUiTemplateContext"
         },
         when: {
-          all: [
-            {
-              option: "operations",
-              in: ["list"]
-            },
-            {
-              any: [
-                {
-                  all: [
-                    {
-                      option: "route-path",
-                      notContains: "["
-                    },
-                    {
-                      option: "directory-prefix",
-                      notContains: "["
-                    }
-                  ]
-                },
-                {
-                  all: [
-                    {
-                      option: "placement",
-                      contains: ":"
-                    },
-                    {
-                      option: "placement-to",
-                      notEquals: ""
-                    }
-                  ]
-                }
-              ]
-            }
-          ]
+          option: "operations",
+          in: ["list"]
         }
       }
     ]

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@jskit-ai/crud-ui-generator",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.1.39",
-    "@jskit-ai/kernel": "0.1.31"
+    "@jskit-ai/crud-core": "0.1.41",
+    "@jskit-ai/kernel": "0.1.33"
   },
   "exports": {
     "./server/buildTemplateContext": "./src/server/buildTemplateContext.js"