@jskit-ai/ui-generator 0.1.3

package/README.md

@@ -0,0 +1,73 @@
+# @jskit-ai/ui-generator
+
+Generate non-CRUD UI pages and outlet elements for JSKIT apps.
+
+## Quick Start
+
+List available placement targets in the current app:
+
+```bash
+npx jskit list placements
+```
+
+Generate a page (default placement target):
+
+```bash
+npx jskit generate @jskit-ai/ui-generator page --name "Reports Dashboard" --surface admin
+```
+
+Generate a page in a subdirectory:
+
+```bash
+npx jskit generate @jskit-ai/ui-generator page --name "Reports Dashboard" --surface admin --directory-prefix ops
+```
+
+Generate a page and place its menu entry in the workspace cog dropdown:
+
+```bash
+npx jskit generate @jskit-ai/ui-generator page --name "Reports" --surface admin --placement workspace-tools:primary-menu
+```
+
+Generate an element at a specific outlet:
+
+```bash
+npx jskit generate @jskit-ai/ui-generator element --name "Ops Panel" --surface admin --placement workspace-settings:forms
+```
+
+Generate an element with custom component path:
+
+```bash
+npx jskit generate @jskit-ai/ui-generator element --name "Alerts Widget" --surface admin --path src/widgets --placement shell-layout:top-right
+```
+
+Generate a route container page with nested outlet (for embedded sub-pages):
+
+```bash
+npx jskit generate @jskit-ai/ui-generator container --name "Practice" --surface admin
+```
+
+## Commands
+
+- `page`: `--name --surface [--directory-prefix] [--placement]`
+- `element`: `--name --surface [--path] [--placement]`
+- `container`: `--name --surface [--directory-prefix] [--placement]`
+
+## 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 />`
+- 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)
+
+## Placement Notes
+
+- `--placement` expects `host:position`.
+- Targets come from:
+  - app-declared `<ShellOutlet host="..." position="..." />` in `src/**/*.vue`
+  - installed package metadata `metadata.ui.placements.outlets`
+- If `--placement` is omitted, the app default outlet is used.

package/package.descriptor.mjs

@@ -0,0 +1,121 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@jskit-ai/ui-generator",
+  version: "0.1.3",
+  kind: "generator",
+  description: "Generate app-local non-CRUD UI pages and outlet elements.",
+  options: {
+    name: {
+      required: true,
+      inputType: "text",
+      defaultValue: "",
+      promptLabel: "Element name",
+      promptHint: "Display name and route slug source (example: Reports Dashboard)."
+    },
+    surface: {
+      required: true,
+      inputType: "text",
+      defaultFromConfig: "surfaceDefaultId",
+      promptLabel: "Target surface",
+      promptHint: "Defaults to config.public.surfaceDefaultId. 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)."
+    },
+    "directory-prefix": {
+      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",
+      defaultValue: "",
+      promptLabel: "Placement target",
+      promptHint: "Optional host:position target (defaults to app ShellOutlet default target)."
+    }
+  },
+  dependsOn: [],
+  capabilities: {
+    provides: ["ui-generator"],
+    requires: []
+  },
+  runtime: {
+    server: {
+      providers: []
+    },
+    client: {
+      providers: []
+    }
+  },
+  metadata: {
+    generatorPrimarySubcommand: "page",
+    generatorSubcommands: {
+      element: {
+        entrypoint: "src/server/subcommands/element.js",
+        export: "runGeneratorSubcommand"
+      },
+      container: {
+        entrypoint: "src/server/subcommands/container.js",
+        export: "runGeneratorSubcommand"
+      }
+    },
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./server/buildTemplateContext",
+          summary: "Builds deterministic page menu placement template context values."
+        }
+      ],
+      containerTokens: {
+        server: [],
+        client: []
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        "@jskit-ai/users-web": "0.1.34"
+      },
+      dev: {}
+    },
+    packageJson: {
+      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: \"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",
+        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"
+        }
+      }
+    ]
+  }
+});

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@jskit-ai/ui-generator",
+  "version": "0.1.3",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "@jskit-ai/kernel": "0.1.20"
+  },
+  "exports": {
+    "./server/buildTemplateContext": "./src/server/buildTemplateContext.js"
+  }
+}

package/src/server/buildTemplateContext.js

@@ -0,0 +1,17 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { resolveShellOutletPlacementTargetFromApp } from "@jskit-ai/kernel/server/support";
+
+async function buildUiPageTemplateContext({ appRoot, options } = {}) {
+  const placementTarget = await resolveShellOutletPlacementTargetFromApp({
+    appRoot,
+    context: "ui-generator",
+    placement: options?.placement
+  });
+
+  return {
+    __JSKIT_UI_MENU_PLACEMENT_HOST__: normalizeText(placementTarget?.host),
+    __JSKIT_UI_MENU_PLACEMENT_POSITION__: normalizeText(placementTarget?.position)
+  };
+}
+
+export { buildUiPageTemplateContext };