@jskit-ai/crud-ui-generator 0.1.5 → 0.1.6

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/crud-ui-generator",
-  version: "0.1.5",
+  version: "0.1.6",
   kind: "generator",
   description: "Generate app-local CRUD UI scaffolds from resource validators.",
   options: {
@@ -81,6 +81,22 @@ export default Object.freeze({
       defaultValue: "",
       promptLabel: "Menu placement",
       promptHint: "Optional host:position target (defaults to ShellLayout default outlet)."
+    },
+    "placement-component-token": {
+      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)."
+    },
+    "placement-to": {
+      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."
     }
   },
   dependsOn: [],
@@ -120,7 +136,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/users-web": "0.1.36"
+        "@jskit-ai/users-web": "0.1.37"
       },
       dev: {}
     },
@@ -204,7 +220,7 @@ export default Object.freeze({
         skipIfContains:
           "jskit:ui-generator.menu:${option:namespace|kebab}:${option:directory-prefix|path}:${option:container|path}:${option:route-path|path}",
         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: \"/${option:directory-prefix|pathprefix}${option:container|pathprefix}${option:route-path|path}\",\n      nonWorkspaceSuffix: \"/${option:directory-prefix|pathprefix}${option:container|pathprefix}${option:route-path|path}\"\n    },\n    when: ({ auth }) => Boolean(auth?.authenticated)\n  });\n}\n",
+          "\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",
@@ -219,8 +235,32 @@ export default Object.freeze({
               in: ["list"]
             },
             {
-              option: "route-path",
-              notContains: "["
+              any: [
+                {
+                  all: [
+                    {
+                      option: "route-path",
+                      notContains: "["
+                    },
+                    {
+                      option: "directory-prefix",
+                      notContains: "["
+                    }
+                  ]
+                },
+                {
+                  all: [
+                    {
+                      option: "placement",
+                      contains: ":"
+                    },
+                    {
+                      option: "placement-to",
+                      notEquals: ""
+                    }
+                  ]
+                }
+              ]
             }
           ]
         }

package/package.json

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

package/src/server/buildTemplateContext.js

@@ -27,7 +27,24 @@ const ALLOWED_OPERATIONS = new Set(["list", "view", "new", "edit"]);
 const DEFAULT_LIST_HIDDEN_FIELD_KEYS = new Set(["createdAt", "updatedAt"]);
 const CONTAINER_TOKEN_PATTERN = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/;
 const DEFAULT_MENU_COMPONENT_TOKEN = "users.web.shell.surface-aware-menu-link-item";
-const CONTAINER_MENU_COMPONENT_TOKEN = "local.main.ui.section-shell.tab-link-item";
+const CONTAINER_MENU_COMPONENT_TOKEN = "local.main.ui.tab-link-item";
+
+function splitPathSegments(value = "") {
+  return normalizeText(value)
+    .replaceAll("\\", "/")
+    .split("/")
+    .map((entry) => normalizeText(entry))
+    .filter(Boolean);
+}
+
+function isRouteGroupSegment(value = "") {
+  const source = normalizeText(value);
+  return source.startsWith("(") && source.endsWith(")");
+}
+
+function joinPathSegments(segments = []) {
+  return (Array.isArray(segments) ? segments : []).join("/");
+}
 
 function resolveContainerOption(options = {}) {
   const container = normalizeText(options?.container).toLowerCase();
@@ -45,31 +62,50 @@ function resolveContainerOption(options = {}) {
 }
 
 function resolveRoutePathWithContainer(options = {}) {
-  const routePath = normalizeText(options?.["route-path"]);
-  if (!routePath) {
-    return "";
-  }
-
   const container = resolveContainerOption(options);
-  if (!container) {
-    return routePath;
-  }
+  const routeSegments = [
+    ...splitPathSegments(options?.["directory-prefix"]),
+    ...splitPathSegments(container),
+    ...splitPathSegments(options?.["route-path"])
+  ];
+  return joinPathSegments(routeSegments);
+}
 
-  return `${container}/${routePath}`;
+function resolvePlacementUrlSuffix(options = {}) {
+  const routeSegments = splitPathSegments(resolveRoutePathWithContainer(options))
+    .filter((segment) => !isRouteGroupSegment(segment));
+  if (routeSegments.length < 1) {
+    return "/";
+  }
+  return `/${joinPathSegments(routeSegments)}`;
 }
 
 function resolveMenuComponentToken(options = {}) {
+  const explicitToken = normalizeText(options?.["placement-component-token"]);
+  if (explicitToken) {
+    return explicitToken;
+  }
+
   const container = resolveContainerOption(options);
   return container ? CONTAINER_MENU_COMPONENT_TOKEN : DEFAULT_MENU_COMPONENT_TOKEN;
 }
 
+function resolveMenuToPropLine(options = {}) {
+  const placementTo = normalizeText(options?.["placement-to"]);
+  if (!placementTo) {
+    return "";
+  }
+
+  return `      to: ${JSON.stringify(placementTo)},\n`;
+}
+
 async function resolveMenuPlacementTarget({ appRoot, options, hasListOperation } = {}) {
   if (hasListOperation !== true) {
     return null;
   }
 
   const routePath = resolveRoutePathWithContainer(options);
-  if (!routePath || routePath.includes("[")) {
+  if (!routePath) {
     return null;
   }
 
@@ -209,6 +245,22 @@ function ensureFields(fields, fallbackFields = createFieldDefinitions({})) {
   return fallbackFields;
 }
 
+function resolveViewTitleFallbackFieldKey(fields = []) {
+  const sourceFields = Array.isArray(fields) ? fields : [];
+  for (const field of sourceFields) {
+    if (normalizeText(field?.type).toLowerCase() !== "string") {
+      continue;
+    }
+
+    const key = normalizeText(field?.key);
+    if (key) {
+      return key;
+    }
+  }
+
+  return "";
+}
+
 async function buildUiTemplateContext({ appRoot, options } = {}) {
   const selectedOperations = parseOperationsOption(options);
   const selectedDisplayFields = parseDisplayFieldsOption(options);
@@ -298,6 +350,9 @@ async function buildUiTemplateContext({ appRoot, options } = {}) {
   const viewFields = hasViewOperation
     ? filterDisplayFields(selectedDisplayFields, ensureFields(viewFieldsAll))
     : createFieldDefinitions({});
+  const viewTitleFallbackFieldKey = hasViewOperation
+    ? resolveViewTitleFallbackFieldKey(viewFieldsAll)
+    : "";
   const createFields = hasNewOperation
     ? filterDisplayFields(selectedDisplayFields, createFieldsAll)
     : [];
@@ -325,6 +380,7 @@ async function buildUiTemplateContext({ appRoot, options } = {}) {
     __JSKIT_UI_LIST_REALTIME_EVENTS__: JSON.stringify(listRealtimeEvents),
     __JSKIT_UI_LIST_RECORD_ID_EXPR__: resolveRecordIdExpression(recordIdFields),
     __JSKIT_UI_VIEW_COLUMNS__: buildViewColumns(viewFields),
+    __JSKIT_UI_VIEW_TITLE_FALLBACK_FIELD_KEY__: JSON.stringify(viewTitleFallbackFieldKey),
     __JSKIT_UI_RECORD_CHANGED_EVENT__: JSON.stringify(defaultRecordChangedEvent),
     __JSKIT_UI_HAS_LIST_ROUTE__: hasListOperation ? "true" : "false",
     __JSKIT_UI_HAS_VIEW_ROUTE__: hasViewOperation ? "true" : "false",
@@ -338,7 +394,10 @@ async function buildUiTemplateContext({ appRoot, options } = {}) {
     __JSKIT_UI_EDIT_FORM_FIELD_PUSH_LINES__: renderObjectPushLines("UI_EDIT_FORM_FIELDS", editFields),
     __JSKIT_UI_MENU_PLACEMENT_HOST__: normalizeText(menuPlacementTarget?.host),
     __JSKIT_UI_MENU_PLACEMENT_POSITION__: normalizeText(menuPlacementTarget?.position),
-    __JSKIT_UI_MENU_COMPONENT_TOKEN__: resolveMenuComponentToken(options)
+    __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)
   };
 }
 

package/src/server/resourceSupport.js

@@ -281,6 +281,62 @@ function toFieldLabel(key) {
     .join(" ");
 }
 
+function isSupportedSelectOptionValue(value) {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+
+function toSelectOptionLabel(value) {
+  if (typeof value === "string") {
+    const normalizedValue = normalizeText(value);
+    return normalizedValue ? toFieldLabel(normalizedValue) : "";
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  return "";
+}
+
+function toSelectOptionIdentity(value) {
+  return `${typeof value}:${String(value)}`;
+}
+
+function normalizeFieldUiOptions(rawOptions, { context = "resource fieldMeta ui.options" } = {}) {
+  if (rawOptions === undefined || rawOptions === null) {
+    return [];
+  }
+  if (!Array.isArray(rawOptions)) {
+    throw new Error(`${context} must be an array of { value, label? } entries.`);
+  }
+
+  const options = [];
+  const seenValues = new Set();
+  for (const [index, rawEntry] of rawOptions.entries()) {
+    if (!rawEntry || typeof rawEntry !== "object" || Array.isArray(rawEntry)) {
+      throw new Error(`${context}[${index}] must be an object.`);
+    }
+
+    const value = rawEntry.value;
+    if (!isSupportedSelectOptionValue(value)) {
+      throw new Error(`${context}[${index}].value must be a string, number, or boolean.`);
+    }
+
+    const identity = toSelectOptionIdentity(value);
+    if (seenValues.has(identity)) {
+      continue;
+    }
+    seenValues.add(identity);
+
+    const explicitLabel = normalizeText(rawEntry.label);
+    const fallbackLabel = toSelectOptionLabel(value);
+    options.push({
+      value,
+      label: explicitLabel || fallbackLabel || String(value)
+    });
+  }
+
+  return options;
+}
+
 function stripLookupIdSuffix(key = "") {
   const normalizedKey = normalizeText(key);
   if (!normalizedKey) {
@@ -425,6 +481,9 @@ function buildResourceFieldMetaMap(resource = {}) {
     }
 
     const relation = normalizeLookupRelation(rawEntry.relation);
+    const fieldUiOptions = normalizeFieldUiOptions(rawEntry?.ui?.options, {
+      context: `resource.fieldMeta["${key}"].ui.options`
+    });
     if (relation) {
       nextEntry.relation = relation;
       const formControl = checkCrudLookupFormControl(rawEntry?.ui?.formControl, {
@@ -437,6 +496,12 @@ function buildResourceFieldMetaMap(resource = {}) {
         };
       }
     }
+    if (fieldUiOptions.length > 0) {
+      nextEntry.ui = {
+        ...(nextEntry.ui || {}),
+        options: fieldUiOptions
+      };
+    }
 
     map[key] = nextEntry;
   }
@@ -559,6 +624,16 @@ function createFormFieldDefinitions(
 
     const schemaType = resolveSchemaType(schema);
     const relation = toLookupRelation(fieldMetaMap, key, { lookupContainerKey });
+    const fieldUiOptions = Array.isArray(fieldMetaMap?.[key]?.ui?.options)
+      ? fieldMetaMap[key].ui.options
+      : [];
+    const schemaEnumValues = Array.isArray(schemaType.schema?.enum) ? schemaType.schema.enum : [];
+    if (!relation && schemaEnumValues.length > 0 && fieldUiOptions.length < 1) {
+      throw new Error(
+        `resource form field "${key}" defines schema enum values but is missing resource.fieldMeta["${key}"].ui.options.`
+      );
+    }
+    const selectOptions = relation ? [] : fieldUiOptions;
     const lookupFormControl = relation
       ? checkCrudLookupFormControl(fieldMetaMap?.[key]?.ui?.formControl, {
           context: `resource.fieldMeta["${key}"].ui.formControl`,
@@ -573,9 +648,14 @@ function createFormFieldDefinitions(
       nullable: schemaType.nullable,
       relation,
       inputType: resolveFormInputType(schemaType.type, schemaType.format),
-      component: resolveFormFieldComponent(schemaType.type, relation),
+      component: selectOptions.length > 0
+        ? "select"
+        : resolveFormFieldComponent(schemaType.type, relation),
       maxLength: toPositiveInteger(schemaType.schema?.maxLength)
     };
+    if (selectOptions.length > 0) {
+      fieldDefinition.options = selectOptions;
+    }
     if (normalizedParentRouteParamKey && key === normalizedParentRouteParamKey) {
       fieldDefinition.hidden = true;
       fieldDefinition.routeParamKey = normalizedParentRouteParamKey;
@@ -622,6 +702,10 @@ function escapeHtml(value) {
     .replaceAll("'", "&#39;");
 }
 
+function serializeTemplateBindingValue(value) {
+  return JSON.stringify(value).replaceAll("'", "\\u0027");
+}
+
 function buildListHeaderColumns(fields = []) {
   return (Array.isArray(fields) ? fields : [])
     .map((field) => `                <th>${escapeHtml(field.label)}</th>`)
@@ -723,11 +807,25 @@ function buildFormColumns(fields = []) {
                 label="${label}"
                 color="primary"
                 hide-details="auto"
-                :disabled="
-                  !formRuntime.addEdit.canSave ||
-                  formRuntime.addEdit.isSaving ||
-                  formRuntime.addEdit.isRefetching
-                "
+                :disabled="formRuntime.addEdit.isFieldLocked"
+                :error-messages='${fieldErrorExpression}'
+              />
+            </v-col>`;
+      }
+
+      if (component === "select") {
+        const selectOptions = Array.isArray(field?.options) ? field.options : [];
+        return `            <v-col cols="12" md="6">
+              <v-select
+                v-model="${formAccessor}"
+                label="${label}"
+                variant="outlined"
+                density="comfortable"
+                :items='${serializeTemplateBindingValue(selectOptions)}'
+                item-title="label"
+                item-value="value"
+                :disabled="formRuntime.addEdit.isFieldLocked"
+                :clearable="${field.nullable === true ? "true" : "false"}"
                 :error-messages='${fieldErrorExpression}'
               />
             </v-col>`;
@@ -753,11 +851,7 @@ function buildFormColumns(fields = []) {
                 item-value="value"
                 ${lookupNoFilterLine}
                 :loading='resolveLookupLoading(${JSON.stringify(key)})'
-                :disabled="
-                  !formRuntime.addEdit.canSave ||
-                  formRuntime.addEdit.isSaving ||
-                  formRuntime.addEdit.isRefetching
-                "
+                :disabled="formRuntime.addEdit.isFieldLocked"
                 :clearable="${field.nullable === true ? "true" : "false"}"
                 :error-messages='${fieldErrorExpression}'
               />
@@ -776,11 +870,7 @@ function buildFormColumns(fields = []) {
                 variant="outlined"
                 density="comfortable"
                 :maxlength="${maxLength}"
-                :readonly="
-                  !formRuntime.addEdit.canSave ||
-                  formRuntime.addEdit.isSaving ||
-                  formRuntime.addEdit.isRefetching
-                "
+                :readonly="formRuntime.addEdit.isFieldLocked"
                 :error-messages='${fieldErrorExpression}'
               />
             </v-col>`;

package/templates/src/pages/admin/ui-generator/EditElement.vue

@@ -11,18 +11,14 @@
           <v-btn
             v-if="UI_CANCEL_URL"
             variant="text"
-            :to="formRuntime.addEdit.resolveParams(UI_CANCEL_URL)"
+            :to="{ path: formRuntime.addEdit.resolveParams(UI_CANCEL_URL), query: $route.query }"
           >
             Cancel
           </v-btn>
           <v-btn
             color="primary"
             :loading="formRuntime.addEdit.isSaving"
-            :disabled="
-              formRuntime.addEdit.isInitialLoading ||
-              formRuntime.addEdit.isRefetching ||
-              !formRuntime.addEdit.canSave
-            "
+            :disabled="formRuntime.addEdit.isSubmitDisabled"
             @click="formRuntime.addEdit.submit"
           >
             Save changes

package/templates/src/pages/admin/ui-generator/ListElement.vue

@@ -40,8 +40,8 @@
               <tr>
 __JSKIT_UI_LIST_HEADER_COLUMNS__
                 <!-- jskit:crud-ui-fields:list-header -->
-                <th v-if="UI_VIEW_URL" class="text-right">Open</th>
-                <th v-if="UI_EDIT_URL" class="text-right">Edit</th>
+                <th v-if="UI_VIEW_URL" class="text-right"></th>
+                <th v-if="UI_EDIT_URL" class="text-right"></th>
               </tr>
             </thead>
             <tbody>
@@ -52,7 +52,7 @@ __JSKIT_UI_LIST_ROW_COLUMNS__
                   <v-btn
                     size="small"
                     variant="text"
-                    :to="records.resolveViewUrl(record)"
+                    :to="{ path: records.resolveViewUrl(record), query: $route.query }"
                     :disabled="!records.resolveViewUrl(record)"
                   >
                     Open
@@ -62,7 +62,7 @@ __JSKIT_UI_LIST_ROW_COLUMNS__
                   <v-btn
                     size="small"
                     variant="text"
-                    :to="records.resolveEditUrl(record)"
+                    :to="{ path: records.resolveEditUrl(record), query: $route.query }"
                     :disabled="!records.resolveEditUrl(record)"
                   >
                     Edit
@@ -92,6 +92,7 @@ const UI_VIEW_URL = __JSKIT_UI_HAS_VIEW_ROUTE__ ? `./:${UI_RECORD_ID_PARAM}` : "
 const UI_EDIT_URL = __JSKIT_UI_HAS_EDIT_ROUTE__ ? `./:${UI_RECORD_ID_PARAM}/edit` : "";
 const UI_NEW_URL = __JSKIT_UI_HAS_NEW_ROUTE__ ? "./new" : "";
 const UI_RECORD_CHANGED_EVENTS = __JSKIT_UI_LIST_REALTIME_EVENTS__;
+const UI_ROUTE_QUERY_BLACKLIST = Object.freeze(["include", "cursor", "limit"]);
 
 const records = useList({
   adapter: UI_OPERATION_ADAPTER || undefined,
@@ -108,6 +109,13 @@ const records = useList({
     enabled: true,
     mode: "query"
   },
+  syncToRoute: {
+    enabled: true,
+    mode: "replace",
+    search: true,
+    queryParams: true,
+    queryParamBlacklist: UI_ROUTE_QUERY_BLACKLIST
+  },
   placementSource: "ui-generator.${option:namespace|kebab}.list",
   fallbackLoadError: "Unable to load records.",
   recordIdParam: UI_RECORD_ID_PARAM,

package/templates/src/pages/admin/ui-generator/NewElement.vue

@@ -12,11 +12,7 @@
           <v-btn
             color="primary"
             :loading="formRuntime.addEdit.isSaving"
-            :disabled="
-              formRuntime.addEdit.isInitialLoading ||
-              formRuntime.addEdit.isRefetching ||
-              !formRuntime.addEdit.canSave
-            "
+            :disabled="formRuntime.addEdit.isSubmitDisabled"
             @click="formRuntime.addEdit.submit"
           >
             Save ${option:namespace|singular|default(record)}

package/templates/src/pages/admin/ui-generator/ViewElement.vue

@@ -4,12 +4,32 @@
       <v-card-item>
         <div class="d-flex align-center ga-3 flex-wrap w-100">
           <div>
-            <v-card-title class="px-0">${option:namespace|singular|pascal|default(Record)}</v-card-title>
+            <v-card-title class="px-0">
+              {{
+                view.resolveRecordTitle(view.record, {
+                  fallbackKey: UI_VIEW_TITLE_FALLBACK_FIELD_KEY,
+                  defaultValue: "${option:namespace|singular|pascal|default(Record)}"
+                })
+              }}
+            </v-card-title>
             <v-card-subtitle class="px-0">View and manage this ${option:namespace|singular|default(record)}.</v-card-subtitle>
           </div>
           <v-spacer />
-          <v-btn v-if="UI_LIST_URL" variant="text" :to="view.resolveParams(UI_LIST_URL)">Back to ${option:namespace|plural|default(records)}</v-btn>
-          <v-btn v-if="UI_EDIT_URL" color="primary" variant="outlined" :to="view.resolveParams(UI_EDIT_URL)">Edit</v-btn>
+          <v-btn
+            v-if="UI_LIST_URL"
+            variant="text"
+            :to="{ path: view.resolveParams(UI_LIST_URL), query: $route.query }"
+          >
+            Back to ${option:namespace|plural|default(records)}
+          </v-btn>
+          <v-btn
+            v-if="UI_EDIT_URL"
+            color="primary"
+            variant="outlined"
+            :to="{ path: view.resolveParams(UI_EDIT_URL), query: $route.query }"
+          >
+            Edit
+          </v-btn>
         </div>
       </v-card-item>
       <v-divider />
@@ -43,6 +63,7 @@ const UI_API_BASE_URL = "${option:api-path|trim}";
 const UI_VIEW_API_URL = `${UI_API_BASE_URL}/:${UI_RECORD_ID_PARAM}`;
 const UI_LIST_URL = __JSKIT_UI_HAS_LIST_ROUTE__ ? ".." : "";
 const UI_EDIT_URL = __JSKIT_UI_HAS_EDIT_ROUTE__ ? "./edit" : "";
+const UI_VIEW_TITLE_FALLBACK_FIELD_KEY = __JSKIT_UI_VIEW_TITLE_FALLBACK_FIELD_KEY__;
 const UI_RECORD_CHANGED_EVENT = __JSKIT_UI_RECORD_CHANGED_EVENT__;
 
 const view = useView({

package/test/buildTemplateContext.test.js

@@ -193,6 +193,7 @@ test("buildUiTemplateContext derives list/view/new/edit placeholders from resour
     assert.doesNotMatch(context.__JSKIT_UI_LIST_ROW_COLUMNS__, /record\.updatedAt/);
     assert.match(context.__JSKIT_UI_VIEW_COLUMNS__, /view\.record\?\.vip/);
     assert.match(context.__JSKIT_UI_VIEW_COLUMNS__, /view\.record\?\.updatedAt/);
+    assert.equal(context.__JSKIT_UI_VIEW_TITLE_FALLBACK_FIELD_KEY__, "\"firstName\"");
     assert.equal(context.__JSKIT_UI_LIST_RECORD_ID_EXPR__, "item.id");
     assert.equal(context.__JSKIT_UI_RECORD_CHANGED_EVENT__, "\"customers.record.changed\"");
     assert.equal(context.__JSKIT_UI_LIST_REALTIME_EVENTS__, "[\"customers.record.changed\"]");
@@ -495,10 +496,149 @@ export { resource };
     assert.equal(context.__JSKIT_UI_HAS_VIEW_ROUTE__, "true");
     assert.equal(context.__JSKIT_UI_HAS_NEW_ROUTE__, "false");
     assert.equal(context.__JSKIT_UI_HAS_EDIT_ROUTE__, "false");
+    assert.equal(context.__JSKIT_UI_VIEW_TITLE_FALLBACK_FIELD_KEY__, "\"fullName\"");
     assert.equal(context.__JSKIT_UI_RECORD_CHANGED_EVENT__, "\"customers.record.changed\"");
   });
 });
 
+test("buildUiTemplateContext renders enum fields as select controls in forms", async () => {
+  await withTempApp(async (appRoot) => {
+    const resourceFile = "packages/pets/src/shared/petResource.js";
+    await writeResource(
+      appRoot,
+      resourceFile,
+      `const resource = {
+  operations: {
+    create: {
+      bodyValidator: {
+        schema: {
+          type: "object",
+          properties: {
+            temperament: { type: "string", enum: ["relaxed", "friendly_excitable", "unknown"] }
+          }
+        }
+      },
+      outputValidator: {
+        schema: {
+          type: "object",
+          properties: {
+            id: { type: "integer" }
+          }
+        }
+      }
+    },
+    patch: {
+      bodyValidator: {
+        schema: {
+          type: "object",
+          properties: {
+            temperament: { type: "string", enum: ["relaxed", "friendly_excitable", "unknown"] }
+          }
+        }
+      },
+      outputValidator: {
+        schema: {
+          type: "object",
+          properties: {
+            id: { type: "integer" }
+          }
+        }
+      }
+    }
+  },
+  fieldMeta: [
+    {
+      key: "temperament",
+      ui: {
+        formControl: "select",
+        options: [
+          { value: "relaxed", label: "Relaxed" },
+          { value: "friendly_excitable", label: "Friendly / Excitable" },
+          { value: "unknown", label: "Unknown temperament" }
+        ]
+      }
+    }
+  ]
+};
+
+export { resource };
+`
+    );
+
+    const context = await buildUiTemplateContext({
+      appRoot,
+      options: {
+        namespace: "pets-ui",
+        "api-path": "/pets",
+        operations: "new,edit",
+        "resource-file": resourceFile
+      }
+    });
+
+    const createFields = JSON.parse(context.__JSKIT_UI_CREATE_FORM_FIELDS__);
+    const temperament = createFields.find((field) => field.key === "temperament");
+    assert.ok(temperament);
+    assert.equal(temperament.component, "select");
+    assert.deepEqual(temperament.options, [
+      { value: "relaxed", label: "Relaxed" },
+      { value: "friendly_excitable", label: "Friendly / Excitable" },
+      { value: "unknown", label: "Unknown temperament" }
+    ]);
+    assert.match(context.__JSKIT_UI_CREATE_FORM_COLUMNS__, /<v-select/);
+    assert.match(context.__JSKIT_UI_CREATE_FORM_COLUMNS__, /:disabled="formRuntime\.addEdit\.isFieldLocked"/);
+    assert.doesNotMatch(context.__JSKIT_UI_CREATE_FORM_COLUMNS__, /!formRuntime\.addEdit\.canSave/);
+  });
+});
+
+test("buildUiTemplateContext fails when enum schema field omits resource fieldMeta ui.options", async () => {
+  await withTempApp(async (appRoot) => {
+    const resourceFile = "packages/pets/src/shared/petResource.js";
+    await writeResource(
+      appRoot,
+      resourceFile,
+      `const resource = {
+  operations: {
+    create: {
+      bodyValidator: {
+        schema: {
+          type: "object",
+          properties: {
+            temperament: { type: "string", enum: ["relaxed", "unknown"] }
+          }
+        }
+      },
+      outputValidator: {
+        schema: {
+          type: "object",
+          properties: {
+            id: { type: "integer" }
+          }
+        }
+      }
+    }
+  }
+};
+
+export { resource };
+`
+    );
+
+    await assert.rejects(
+      () =>
+        buildUiTemplateContext({
+          appRoot,
+          options: {
+            namespace: "pets-ui",
+            "api-path": "/pets",
+            operations: "new",
+            "resource-file": resourceFile
+          }
+        }),
+      /schema enum values but is missing resource\.fieldMeta\["temperament"\]\.ui\.options/
+    );
+  });
+});
+
 test("buildUiTemplateContext maps lookup relations from resource fieldMeta into lookup form fields", async () => {
   await withTempApp(async (appRoot) => {
     const resourceFile = "packages/contacts/src/shared/contactResource.js";
@@ -1049,7 +1189,7 @@ test("buildUiTemplateContext defaults list placement to container host when cont
 
     assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_HOST__, "practice");
     assert.equal(context.__JSKIT_UI_MENU_PLACEMENT_POSITION__, "sub-pages");
-    assert.equal(context.__JSKIT_UI_MENU_COMPONENT_TOKEN__, "local.main.ui.section-shell.tab-link-item");
+    assert.equal(context.__JSKIT_UI_MENU_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
   });
 });
 
@@ -1105,3 +1245,85 @@ test("buildUiTemplateContext applies explicit placement override and validates t
     );
   });
 });
+
+test("buildUiTemplateContext allows placement component token override", async () => {
+  await withTempApp(async (appRoot) => {
+    const resourceFile = "packages/customers/src/shared/customerResource.js";
+    await writeResource(appRoot, resourceFile, FULL_RESOURCE_SOURCE);
+    await writeShellLayout(appRoot);
+
+    const context = await buildUiTemplateContext({
+      appRoot,
+      options: {
+        namespace: "customers-ui",
+        "api-path": "/crud/customers",
+        "route-path": "ops/customers",
+        operations: "list",
+        placement: "shell-layout:secondary-menu",
+        "placement-component-token": "local.main.ui.tab-link-item",
+        "resource-file": resourceFile,
+      }
+    });
+
+    assert.equal(context.__JSKIT_UI_MENU_COMPONENT_TOKEN__, "local.main.ui.tab-link-item");
+  });
+});
+
+test("buildUiTemplateContext renders optional placement-to props line", async () => {
+  await withTempApp(async (appRoot) => {
+    const resourceFile = "packages/customers/src/shared/customerResource.js";
+    await writeResource(appRoot, resourceFile, FULL_RESOURCE_SOURCE);
+    await writeShellLayout(appRoot);
+
+    const defaultContext = await buildUiTemplateContext({
+      appRoot,
+      options: {
+        namespace: "customers-ui",
+        "api-path": "/crud/customers",
+        "route-path": "ops/customers",
+        operations: "list",
+        placement: "shell-layout:secondary-menu",
+        "resource-file": resourceFile,
+      }
+    });
+    assert.equal(defaultContext.__JSKIT_UI_MENU_TO_PROP_LINE__, "");
+
+    const explicitToContext = await buildUiTemplateContext({
+      appRoot,
+      options: {
+        namespace: "customers-ui",
+        "api-path": "/crud/customers",
+        "route-path": "ops/customers",
+        operations: "list",
+        placement: "shell-layout:secondary-menu",
+        "placement-to": "./pets",
+        "resource-file": resourceFile,
+      }
+    });
+    assert.equal(explicitToContext.__JSKIT_UI_MENU_TO_PROP_LINE__, "      to: \"./pets\",\n");
+  });
+});
+
+test("buildUiTemplateContext strips route-group filesystem segments from menu URL suffix", async () => {
+  await withTempApp(async (appRoot) => {
+    const resourceFile = "packages/customers/src/shared/customerResource.js";
+    await writeResource(appRoot, resourceFile, FULL_RESOURCE_SOURCE);
+    await writeShellLayout(appRoot);
+
+    const context = await buildUiTemplateContext({
+      appRoot,
+      options: {
+        namespace: "customers-ui",
+        "api-path": "/crud/customers",
+        "directory-prefix": "ops/(nestedChildren)",
+        "route-path": "customers",
+        operations: "list",
+        placement: "shell-layout:secondary-menu",
+        "resource-file": resourceFile
+      }
+    });
+
+    assert.equal(context.__JSKIT_UI_MENU_WORKSPACE_SUFFIX__, "/ops/customers");
+    assert.equal(context.__JSKIT_UI_MENU_NON_WORKSPACE_SUFFIX__, "/ops/customers");
+  });
+});