@jskit-ai/users-web 0.1.72 → 0.1.74

package/package.descriptor.mjs

@@ -3,7 +3,7 @@ import { HOME_COG_OUTLET } from "./src/shared/toolsOutletContracts.js";
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/users-web",
-  version: "0.1.72",
+  version: "0.1.74",
   kind: "runtime",
   description: "Users web module: account/profile UI plus shared users web widgets.",
   dependsOn: [
@@ -46,6 +46,10 @@ export default Object.freeze({
           subpath: "./client/providers/UsersWebClientProvider",
           summary: "Exports users-web client provider class."
         },
+        {
+          subpath: "./client/components/AccountSettingsClientElement",
+          summary: "Exports the package-owned account settings host that renders placement-backed account sections."
+        },
         {
           subpath: "./client/components/ProfileClientElement",
           summary: "Exports profile settings client element scaffold component."
@@ -90,10 +94,6 @@ export default Object.freeze({
           subpath: "./client/lib/httpClient",
           summary: "Exports the shared users-web HTTP client with credentials and CSRF behavior."
         },
-        {
-          subpath: "./client/composables/useAccountSettingsRuntime",
-          summary: "Exports account settings runtime composable for app-owned settings UI."
-        },
         {
           subpath: "./client/account-settings/sections",
           summary: "Exports placement-backed account settings section helpers."
@@ -119,7 +119,7 @@ export default Object.freeze({
           {
             target: "account-settings:sections",
             surfaces: ["account"],
-            source: "templates/src/components/account/settings/AccountSettingsClientElement.vue"
+            source: "src/client/components/AccountSettingsClientElement.vue"
           }
         ],
         contributions: [
@@ -149,6 +149,30 @@ export default Object.freeze({
             componentToken: "local.main.ui.surface-aware-menu-link-item",
             when: "auth.authenticated === true",
             source: "mutations.text#users-web-home-tools-placement"
+          },
+          {
+            id: "users.account.settings.profile",
+            target: "account-settings:sections",
+            surfaces: ["account"],
+            order: 100,
+            componentToken: "local.main.account-settings.section.profile",
+            source: "mutations.text#users-web-account-settings-sections-placement"
+          },
+          {
+            id: "users.account.settings.preferences",
+            target: "account-settings:sections",
+            surfaces: ["account"],
+            order: 200,
+            componentToken: "local.main.account-settings.section.preferences",
+            source: "mutations.text#users-web-account-settings-sections-placement"
+          },
+          {
+            id: "users.account.settings.notifications",
+            target: "account-settings:sections",
+            surfaces: ["account"],
+            order: 300,
+            componentToken: "local.main.account-settings.section.notifications",
+            source: "mutations.text#users-web-account-settings-sections-placement"
           }
         ]
       }
@@ -159,12 +183,12 @@ export default Object.freeze({
       runtime: {
         "@tanstack/vue-query": "5.92.12",
         "@mdi/js": "^7.4.47",
-        "@jskit-ai/http-runtime": "0.1.56",
-        "@jskit-ai/realtime": "0.1.56",
-        "@jskit-ai/kernel": "0.1.57",
-        "@jskit-ai/shell-web": "0.1.56",
-        "@jskit-ai/uploads-image-web": "0.1.35",
-        "@jskit-ai/users-core": "0.1.67",
+        "@jskit-ai/http-runtime": "0.1.58",
+        "@jskit-ai/realtime": "0.1.58",
+        "@jskit-ai/kernel": "0.1.59",
+        "@jskit-ai/shell-web": "0.1.58",
+        "@jskit-ai/uploads-image-web": "0.1.37",
+        "@jskit-ai/users-core": "0.1.69",
         vuetify: "^4.0.0"
       },
       dev: {}
@@ -185,13 +209,6 @@ export default Object.freeze({
         category: "users-web",
         id: "users-web-page-account-root"
       },
-      {
-        from: "templates/src/components/account/settings/AccountSettingsClientElement.vue",
-        to: "src/components/account/settings/AccountSettingsClientElement.vue",
-        reason: "Install app-owned account settings container component scaffold.",
-        category: "users-web",
-        id: "users-web-component-account-settings-root"
-      },
       {
         from: "templates/src/components/account/settings/AccountSettingsProfileSection.vue",
         to: "src/components/account/settings/AccountSettingsProfileSection.vue",
@@ -247,6 +264,77 @@ export default Object.freeze({
         reason: "Append users-web home tools widget and settings menu placements into app-owned placement registry.",
         category: "users-web",
         id: "users-web-home-tools-placement"
+      },
+      {
+        op: "append-text",
+        file: "src/placement.js",
+        position: "bottom",
+        skipIfContains: "id: \"users.account.settings.profile\"",
+        value:
+          "\naddPlacement({\n  id: \"users.account.settings.profile\",\n  target: \"account-settings:sections\",\n  surfaces: [\"account\"],\n  order: 100,\n  componentToken: \"local.main.account-settings.section.profile\",\n  props: {\n    title: \"Profile\",\n    value: \"profile\",\n    usesSharedRuntime: true\n  }\n});\n\naddPlacement({\n  id: \"users.account.settings.preferences\",\n  target: \"account-settings:sections\",\n  surfaces: [\"account\"],\n  order: 200,\n  componentToken: \"local.main.account-settings.section.preferences\",\n  props: {\n    title: \"Preferences\",\n    value: \"preferences\",\n    usesSharedRuntime: true\n  }\n});\n\naddPlacement({\n  id: \"users.account.settings.notifications\",\n  target: \"account-settings:sections\",\n  surfaces: [\"account\"],\n  order: 300,\n  componentToken: \"local.main.account-settings.section.notifications\",\n  props: {\n    title: \"Notifications\",\n    value: \"notifications\",\n    usesSharedRuntime: true\n  }\n});\n",
+        reason: "Append users-web account settings section placements into the app-owned placement registry.",
+        category: "users-web",
+        id: "users-web-account-settings-sections-placement"
+      },
+      {
+        op: "append-text",
+        file: "packages/main/src/client/providers/MainClientProvider.js",
+        position: "top",
+        skipIfContains: "import AccountSettingsProfileSection from \"/src/components/account/settings/AccountSettingsProfileSection.vue\";",
+        value: "import AccountSettingsProfileSection from \"/src/components/account/settings/AccountSettingsProfileSection.vue\";\n",
+        reason: "Bind the app-owned account profile settings section into local main client provider imports.",
+        category: "users-web",
+        id: "users-web-main-client-provider-account-settings-profile-import"
+      },
+      {
+        op: "append-text",
+        file: "packages/main/src/client/providers/MainClientProvider.js",
+        position: "top",
+        skipIfContains: "import AccountSettingsPreferencesSection from \"/src/components/account/settings/AccountSettingsPreferencesSection.vue\";",
+        value: "import AccountSettingsPreferencesSection from \"/src/components/account/settings/AccountSettingsPreferencesSection.vue\";\n",
+        reason: "Bind the app-owned account preferences settings section into local main client provider imports.",
+        category: "users-web",
+        id: "users-web-main-client-provider-account-settings-preferences-import"
+      },
+      {
+        op: "append-text",
+        file: "packages/main/src/client/providers/MainClientProvider.js",
+        position: "top",
+        skipIfContains: "import AccountSettingsNotificationsSection from \"/src/components/account/settings/AccountSettingsNotificationsSection.vue\";",
+        value: "import AccountSettingsNotificationsSection from \"/src/components/account/settings/AccountSettingsNotificationsSection.vue\";\n",
+        reason: "Bind the app-owned account notifications settings section into local main client provider imports.",
+        category: "users-web",
+        id: "users-web-main-client-provider-account-settings-notifications-import"
+      },
+      {
+        op: "append-text",
+        file: "packages/main/src/client/providers/MainClientProvider.js",
+        position: "bottom",
+        skipIfContains: "registerMainClientComponent(\"local.main.account-settings.section.profile\", () => AccountSettingsProfileSection);",
+        value: "\nregisterMainClientComponent(\"local.main.account-settings.section.profile\", () => AccountSettingsProfileSection);\n",
+        reason: "Bind the app-owned account profile settings section token into local main client provider registry.",
+        category: "users-web",
+        id: "users-web-main-client-provider-account-settings-profile-register"
+      },
+      {
+        op: "append-text",
+        file: "packages/main/src/client/providers/MainClientProvider.js",
+        position: "bottom",
+        skipIfContains: "registerMainClientComponent(\"local.main.account-settings.section.preferences\", () => AccountSettingsPreferencesSection);",
+        value: "\nregisterMainClientComponent(\"local.main.account-settings.section.preferences\", () => AccountSettingsPreferencesSection);\n",
+        reason: "Bind the app-owned account preferences settings section token into local main client provider registry.",
+        category: "users-web",
+        id: "users-web-main-client-provider-account-settings-preferences-register"
+      },
+      {
+        op: "append-text",
+        file: "packages/main/src/client/providers/MainClientProvider.js",
+        position: "bottom",
+        skipIfContains: "registerMainClientComponent(\"local.main.account-settings.section.notifications\", () => AccountSettingsNotificationsSection);",
+        value: "\nregisterMainClientComponent(\"local.main.account-settings.section.notifications\", () => AccountSettingsNotificationsSection);\n",
+        reason: "Bind the app-owned account notifications settings section token into local main client provider registry.",
+        category: "users-web",
+        id: "users-web-main-client-provider-account-settings-notifications-register"
       }
     ]
   }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@jskit-ai/users-web",
-  "version": "0.1.72",
+  "version": "0.1.74",
   "type": "module",
   "scripts": {
     "test": "node --test"
   },
   "exports": {
     "./client": "./src/client/index.js",
+    "./client/components/AccountSettingsClientElement": "./src/client/components/AccountSettingsClientElement.vue",
     "./client/account-settings/sections": "./src/client/account-settings/sections.js",
     "./client/composables/useAddEdit": "./src/client/composables/records/useAddEdit.js",
     "./client/composables/useAccess": "./src/client/composables/useAccess.js",
@@ -24,7 +25,6 @@
     "./client/composables/useView": "./src/client/composables/records/useView.js",
     "./client/composables/useCrudView": "./src/client/composables/records/useCrudView.js",
     "./client/composables/usePagedCollection": "./src/client/composables/usePagedCollection.js",
-    "./client/composables/useAccountSettingsRuntime": "./src/client/composables/useAccountSettingsRuntime.js",
     "./client/composables/usePaths": "./src/client/composables/usePaths.js",
     "./client/composables/runtime/useUiFeedback": "./src/client/composables/runtime/useUiFeedback.js",
     "./client/lib/httpClient": "./src/client/lib/httpClient.js",
@@ -34,12 +34,12 @@
   "dependencies": {
     "@tanstack/vue-query": "5.92.12",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/http-runtime": "0.1.56",
-    "@jskit-ai/kernel": "0.1.57",
-    "@jskit-ai/realtime": "0.1.56",
-    "@jskit-ai/shell-web": "0.1.56",
-    "@jskit-ai/uploads-image-web": "0.1.35",
-    "@jskit-ai/users-core": "0.1.67",
+    "@jskit-ai/http-runtime": "0.1.58",
+    "@jskit-ai/kernel": "0.1.59",
+    "@jskit-ai/realtime": "0.1.58",
+    "@jskit-ai/shell-web": "0.1.58",
+    "@jskit-ai/uploads-image-web": "0.1.37",
+    "@jskit-ai/users-core": "0.1.69",
     "vuetify": "^4.0.0"
   },
   "peerDependencies": {

package/src/client/account-settings/sections.js

@@ -9,11 +9,6 @@ import { useWebPlacementContext } from "@jskit-ai/shell-web/client/placement";
 
 const ACCOUNT_SETTINGS_SECTION_TARGET = "account-settings:sections";
 const EMPTY_ACCOUNT_SETTINGS_SECTIONS = Object.freeze([]);
-const RESERVED_ACCOUNT_SETTINGS_SECTION_VALUES = Object.freeze([
-  "profile",
-  "preferences",
-  "notifications"
-]);
 const WEB_PLACEMENT_RUNTIME_INJECTION_KEY = "jskit.shell-web.runtime.web-placement.client";
 
 function normalizeAccountSettingsSectionEntry(entry = null) {
@@ -53,20 +48,30 @@ function sortAccountSettingsSections(entries = []) {
 }
 
 function resolveAccountSettingsSections(entries = []) {
-  const seen = new Set(RESERVED_ACCOUNT_SETTINGS_SECTION_VALUES);
   const normalized = [];
 
   for (const entry of Array.isArray(entries) ? entries : []) {
     const resolved = normalizeAccountSettingsSectionEntry(entry);
-    if (!resolved || seen.has(resolved.value)) {
+    if (!resolved) {
       continue;
     }
 
-    seen.add(resolved.value);
     normalized.push(resolved);
   }
 
-  return sortAccountSettingsSections(normalized);
+  const sorted = sortAccountSettingsSections(normalized);
+  const seen = new Set();
+  const deduplicated = [];
+  for (const entry of sorted) {
+    if (seen.has(entry.value)) {
+      continue;
+    }
+
+    seen.add(entry.value);
+    deduplicated.push(entry);
+  }
+
+  return Object.freeze(deduplicated);
 }
 
 function useAccountSettingsSections() {
@@ -114,7 +119,6 @@ function useAccountSettingsSections() {
 export {
   ACCOUNT_SETTINGS_SECTION_TARGET,
   EMPTY_ACCOUNT_SETTINGS_SECTIONS,
-  RESERVED_ACCOUNT_SETTINGS_SECTION_VALUES,
   normalizeAccountSettingsSectionEntry,
   resolveAccountSettingsSections,
   sortAccountSettingsSections,

package/{templates/src/components/account/settings → src/client/components}/AccountSettingsClientElement.vue

@@ -2,55 +2,25 @@
 import { computed } from "vue";
 import { useRoute, useRouter } from "vue-router";
 import { normalizeOneOf } from "@jskit-ai/kernel/shared/support/normalize";
-import { useAccountSettingsRuntime } from "@jskit-ai/users-web/client/composables/useAccountSettingsRuntime";
-import { useAccountSettingsSections } from "@jskit-ai/users-web/client/account-settings/sections";
-import AccountSettingsProfileSection from "./AccountSettingsProfileSection.vue";
-import AccountSettingsPreferencesSection from "./AccountSettingsPreferencesSection.vue";
-import AccountSettingsNotificationsSection from "./AccountSettingsNotificationsSection.vue";
+import { useAccountSettingsRuntime } from "../composables/useAccountSettingsRuntime.js";
+import { useAccountSettingsSections } from "../account-settings/sections.js";
 
 const runtime = useAccountSettingsRuntime();
 const route = useRoute();
 const router = useRouter();
-const extensionSections = useAccountSettingsSections();
-
-const sections = computed(() => {
-  const nextSections = [
-    { title: "Profile", value: "profile", component: AccountSettingsProfileSection, usesSharedRuntime: true, order: 100 },
-    {
-      title: "Preferences",
-      value: "preferences",
-      component: AccountSettingsPreferencesSection,
-      usesSharedRuntime: true,
-      order: 200
-    },
-    {
-      title: "Notifications",
-      value: "notifications",
-      component: AccountSettingsNotificationsSection,
-      usesSharedRuntime: true,
-      order: 300
-    }
-  ];
-
-  for (const entry of extensionSections.value) {
-    nextSections.push(entry);
+const sections = useAccountSettingsSections();
+const sectionValues = computed(() => Object.freeze(sections.value.map((section) => section.value)));
+const defaultSection = computed(() => {
+  if (sectionValues.value.includes("profile")) {
+    return "profile";
   }
 
-  return Object.freeze(
-    nextSections.sort((left, right) => {
-      const orderDelta = Number(left.order || 0) - Number(right.order || 0);
-      if (orderDelta !== 0) {
-        return orderDelta;
-      }
-      return String(left.value || "").localeCompare(String(right.value || ""));
-    })
-  );
+  return sectionValues.value[0] || "";
 });
-const sectionValues = computed(() => Object.freeze(sections.value.map((section) => section.value)));
 
 function normalizeSection(value) {
   const source = Array.isArray(value) ? value[0] : value;
-  return normalizeOneOf(source, sectionValues.value, "profile");
+  return normalizeOneOf(source, sectionValues.value, defaultSection.value);
 }
 
 function readRouteSection() {
@@ -64,14 +34,14 @@ const activeTab = computed({
   set(nextValue) {
     const normalizedSection = normalizeSection(nextValue);
     const currentSection = readRouteSection();
-    if (normalizedSection === currentSection) {
+    if (!normalizedSection || normalizedSection === currentSection) {
       return;
     }
 
     const nextQuery = {
       ...route.query
     };
-    if (normalizedSection === "profile") {
+    if (normalizedSection === defaultSection.value) {
       delete nextQuery.section;
     } else {
       nextQuery.section = normalizedSection;
@@ -108,6 +78,9 @@ const activeTab = computed({
           <v-skeleton-loader type="text@2, list-item-two-line@4" class="mb-4" />
           <v-skeleton-loader type="text@2, paragraph, button" />
         </template>
+        <template v-else-if="sections.length < 1">
+          <p class="text-body-2 text-medium-emphasis mb-0">No account settings sections are registered.</p>
+        </template>
         <template v-else>
           <v-progress-linear v-if="runtime.refreshingSettings.value" indeterminate class="mb-4" />
           <v-row class="settings-layout" no-gutters>

package/src/client/composables/crud/crudJsonApiTransportSupport.js

@@ -0,0 +1,137 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeCrudLookupNamespace } from "@jskit-ai/kernel/shared/support/crudLookup";
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function resolveSchemaFieldDefinitions(definition = null) {
+  const schema = definition?.schema;
+  if (!schema || typeof schema.getFieldDefinitions !== "function") {
+    return {};
+  }
+
+  const definitions = schema.getFieldDefinitions();
+  return isRecord(definitions) ? definitions : {};
+}
+
+function resolveLookupFieldMap(resource = null) {
+  const outputDefinition =
+    resource?.operations?.view?.output ||
+    resource?.operations?.create?.output ||
+    resource?.operations?.patch?.output ||
+    null;
+  const mapping = {};
+
+  for (const [fieldKey, fieldDefinition] of Object.entries(resolveSchemaFieldDefinitions(outputDefinition))) {
+    const normalizedFieldDefinition = isRecord(fieldDefinition) ? fieldDefinition : {};
+    if (!normalizeText(normalizedFieldDefinition.belongsTo)) {
+      continue;
+    }
+
+    const relationshipName = normalizeText(normalizedFieldDefinition.as, {
+      fallback: fieldKey
+    });
+    const normalizedFieldKey = normalizeText(fieldKey);
+    if (!normalizedFieldKey || !relationshipName) {
+      continue;
+    }
+
+    mapping[relationshipName] = normalizedFieldKey;
+  }
+
+  return Object.freeze(mapping);
+}
+
+function isJsonApiResourceTransport(transport = null) {
+  return normalizeText(transport?.kind).toLowerCase() === "jsonapi-resource";
+}
+
+function resolveCrudJsonApiResourceType(resource = null) {
+  return normalizeText(resource?.namespace);
+}
+
+function inferCrudLookupJsonApiTransport({ namespace = "", apiPath = "" } = {}) {
+  const resourceType =
+    normalizeCrudLookupNamespace(namespace) ||
+    normalizeCrudLookupNamespace(apiPath);
+  if (!resourceType) {
+    return null;
+  }
+
+  return Object.freeze({
+    kind: "jsonapi-resource",
+    responseType: resourceType,
+    responseKind: "collection"
+  });
+}
+
+function inferCrudJsonApiTransport(resource = null, { mode = "", operationName = "" } = {}) {
+  const resourceType = resolveCrudJsonApiResourceType(resource);
+  if (!resourceType) {
+    return null;
+  }
+
+  const normalizedMode = normalizeText(mode).toLowerCase();
+  const normalizedOperationName = normalizeText(operationName).toLowerCase();
+  if (normalizedMode === "list") {
+    return Object.freeze({
+      kind: "jsonapi-resource",
+      responseType: resourceType,
+      responseKind: "collection"
+    });
+  }
+
+  if (normalizedMode === "view") {
+    return Object.freeze({
+      kind: "jsonapi-resource",
+      responseType: resourceType,
+      responseKind: "record"
+    });
+  }
+
+  if (normalizedMode === "add-edit") {
+    return Object.freeze({
+      kind: "jsonapi-resource",
+      ...(normalizedOperationName ? { requestType: resourceType } : {}),
+      responseType: resourceType,
+      responseKind: "record"
+    });
+  }
+
+  return null;
+}
+
+function resolveCrudJsonApiTransport(transport = null, resource = null, options = {}) {
+  if (transport != null) {
+    throw new TypeError(
+      "CRUD hooks no longer accept explicit transport. Derive JSON:API transport from the shared resource instead."
+    );
+  }
+
+  const baseTransport = inferCrudJsonApiTransport(resource, options);
+  if (!isJsonApiResourceTransport(baseTransport)) {
+    return baseTransport;
+  }
+
+  const lookupFieldMap = resolveLookupFieldMap(resource);
+  const lookupContainerKey = normalizeText(resource?.contract?.lookup?.containerKey, {
+    fallback: "lookups"
+  });
+  if (Object.keys(lookupFieldMap).length < 1 && !lookupContainerKey) {
+    return baseTransport;
+  }
+
+  return Object.freeze({
+    ...baseTransport,
+    ...(Object.keys(lookupFieldMap).length > 0 ? { lookupFieldMap } : {}),
+    ...(lookupContainerKey ? { lookupContainerKey } : {})
+  });
+}
+
+export {
+  inferCrudJsonApiTransport,
+  inferCrudLookupJsonApiTransport,
+  resolveCrudJsonApiTransport,
+  resolveLookupFieldMap
+};

package/src/client/composables/crud/crudLookupFieldLabelSupport.js

@@ -102,6 +102,15 @@ function resolveLookupFieldDescriptor(field = {}, relationKind = "", valueKey =
   };
 }
 
+function resolveFallbackLookupKey(key = "") {
+  const normalizedKey = normalizeText(key);
+  if (!normalizedKey.endsWith("Id") || normalizedKey.length <= 2) {
+    return "";
+  }
+
+  return normalizedKey.slice(0, -2);
+}
+
 function resolveLookupFieldDisplayValue(record = {}, field = {}, relationKind = "", valueKey = "", labelKey = "") {
   const sourceRecord = asPlainObject(record);
   const descriptor = resolveLookupFieldDescriptor(field, relationKind, valueKey, labelKey);
@@ -118,7 +127,10 @@ function resolveLookupFieldDisplayValue(record = {}, field = {}, relationKind =
     context: `lookup relation "${key}" containerKey`
   });
   const sourceLookups = asPlainObject(sourceRecord[lookupContainerKey]);
-  const lookupRecord = asPlainObject(sourceLookups[key]);
+  let lookupRecord = asPlainObject(sourceLookups[key]);
+  if (Object.keys(lookupRecord).length < 1) {
+    lookupRecord = asPlainObject(sourceLookups[resolveFallbackLookupKey(key)]);
+  }
   const lookupLabel = resolveLookupItemLabel(lookupRecord, descriptor.relation.labelKey);
   if (lookupLabel) {
     return lookupLabel;

package/src/client/composables/crud/crudLookupFieldRuntime.js

@@ -11,6 +11,7 @@ import {
   resolveLookupItemLabel,
   resolveLookupFieldDisplayValue
 } from "./crudLookupFieldLabelSupport.js";
+import { inferCrudLookupJsonApiTransport } from "./crudJsonApiTransportSupport.js";
 import { asPlainObject } from "../support/scopeHelpers.js";
 
 function normalizeQueryKeyPrefix(value) {
@@ -104,6 +105,10 @@ function createCrudLookupFieldRuntime({
     }
     const explicitApiPath = normalizeCrudLookupApiPath(rawRelation.apiPath);
     const apiPath = explicitApiPath || resolveCrudLookupApiPathFromNamespace(namespace);
+    const transport = inferCrudLookupJsonApiTransport({
+      namespace,
+      apiPath
+    });
     const valueKey = normalizeText(rawRelation.valueKey);
     const labelKey = normalizeText(rawRelation.labelKey);
     const relationLookupContainerKey = normalizeCrudLookupContainerKey(rawRelation.containerKey, {
@@ -119,6 +124,7 @@ function createCrudLookupFieldRuntime({
       adapter: adapter || undefined,
       ...(relationSurfaceId ? { surfaceId: relationSurfaceId } : {}),
       apiSuffix: apiPath,
+      ...(transport ? { transport } : {}),
       queryKeyFactory: (surfaceId = "", scopeParamValue = "") => [
         ...normalizedQueryKeyPrefix,
         key,

package/src/client/composables/crud/crudSchemaFormHelpers.js

@@ -51,6 +51,10 @@ function isNullableFormField(field = {}) {
   return field?.nullable === true;
 }
 
+function isLookupFormField(field = {}) {
+  return field?.component === "lookup" || field?.relation?.kind === "lookup";
+}
+
 function padDateTimePart(value) {
   return String(value).padStart(2, "0");
 }
@@ -138,6 +142,10 @@ function resolveFormFieldInitialValue(field = {}) {
     return isNullableFormField(field) ? null : false;
   }
 
+  if (isNullableFormField(field) && isLookupFormField(field)) {
+    return null;
+  }
+
   return "";
 }
 
@@ -146,6 +154,10 @@ function shouldSerializeClearedFieldAsNull(field = {}) {
     return false;
   }
 
+  if (isLookupFormField(field)) {
+    return true;
+  }
+
   const fieldType = resolveFormFieldType(field);
   const fieldFormat = resolveFormFieldFormat(field);
 
@@ -208,6 +220,19 @@ function buildCrudFormPayload(fields = [], model = {}) {
       continue;
     }
 
+    if (isLookupFormField(field)) {
+      const normalizedLookupValue = String(rawValue).trim();
+      if (!normalizedLookupValue) {
+        if (clearAsNull) {
+          payload[fieldKey] = null;
+        }
+        continue;
+      }
+
+      payload[fieldKey] = normalizedLookupValue;
+      continue;
+    }
+
     if (fieldFormat === "date") {
       const normalizedValue = String(rawValue).trim();
       if (!normalizedValue) {
@@ -284,6 +309,11 @@ function applyCrudPayloadToForm(fields = [], model = {}, payload = {}) {
       continue;
     }
 
+    if (isLookupFormField(field)) {
+      targetModel[fieldKey] = rawValue == null ? null : String(rawValue);
+      continue;
+    }
+
     targetModel[fieldKey] = rawValue == null ? "" : String(rawValue);
   }
 }

package/src/client/composables/internal/crudListParentTitleSupport.js

@@ -133,7 +133,11 @@ function resolveCrudListParentTitleFromItems(items = [], descriptor = null) {
   }
 
   for (const item of sourceItems) {
+    const rawParentValue = toRouteParamValue(item?.[descriptor.fieldKey]);
     const resolvedTitle = normalizeText(resolveLookupFieldDisplayValue(item, descriptor.fieldDescriptor));
+    if (resolvedTitle && rawParentValue && resolvedTitle === rawParentValue) {
+      continue;
+    }
     if (resolvedTitle) {
       return resolvedTitle;
     }