@wildo-ai/saas-frontend-lib 1.1.5 → 1.1.6

package/dist/esm/core/resources/resource-label-field-paths.frontend.utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource-label-field-paths.frontend.utils.js","sourceRoot":"","sources":["../../../../../src/core/resources/resource-label-field-paths.frontend.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The label-bearing field paths of a schema — the exact population `useResourceLabels` asks i18n for.\n *\n * Extracted from `useResourceLabels` so the question \"which keys will this surface look up?\" has ONE\n * answer that a hook and a test can both ask. Before this it was module-private, so any check that\n * wanted to hold an authored label tree to what a surface renders had to re-derive the walk — and a\n * re-derived walk is the copy that drifts first (a discriminated union's merged discriminator, the\n * index-free array-item paths, the depth bound).\n *\n * The workbench's aspect-popup label totality check (#638) is the first such consumer: it walks every\n * family aspect's item schema through THIS function, so a key it reports missing is a key the popup\n * really asks for, and a key it does not report is one the popup never asks for.\n */\n\nimport type { z } from 'zod';\nimport {\n  FieldSchemaType,\n  getArrayItemSchema,\n  getEnumValues,\n  getSchemaType,\n  getUnionObjectMembers,\n  getZodObjectShape,\n  unwrapSchema,\n} from '@wildo-ai/zod-decorators';\nimport { resolveDeclaredSystemEnumName, resolveFieldEnumSchema, synthesizeUnionDiscriminatorEnums } from '@wildo-ai/presets-components-models';\nimport { AutomatedLayoutFrontendUtils } from '~wildo-frontend-lib/core/automated-layout/automated-layout.frontend.utils';\n\n/** Max object-nesting depth walked when collecting label/enum entries (guards against\n *  pathological / self-referential schemas while covering real nested settings objects\n *  like `privacy.consentedPurposes` and `regional.dateFormat`). */\nconst MAX_NESTED_FIELD_DEPTH = 4;\n\n/** A field reachable from the resource schema, identified by its dotted runtime path. */\nexport interface ResourceLabelFieldEntry {\n  /** Dotted path as seen by `DisplayField`/`FormField` inside an `ObjectScope` (e.g. `privacy.consentedPurposes`). */\n  path: string;\n  /** Final path segment, used for the unresolved-label rendering. */\n  leaf: string;\n  /** The field's Zod schema (decorators intact). */\n  schema: z.ZodTypeAny;\n}\n\n/**\n * Flatten a resource schema into every label-bearing field path, recursing into nested\n * OBJECT fields so that fields rendered inside an `<ObjectScope name=\"privacy\">` (which look\n * their labels/enum-labels up by the dotted `privacy.consentedPurposes` key) resolve the\n * same way top-level fields do. Without this, nested object fields fell back to no label /\n * raw enum values. Arrays of scalars are recorded as leaves (their element enum, if any, is\n * handled by {@link resolveResourceLabelEnumSchema}); arrays of OBJECTS are descended into under\n * their index-free path.\n *\n * Throws only if the underlying shape resolution throws; callers that render treat that as\n * \"no entries yet\" (a schema briefly undefined on first mount).\n */\nexport function collectResourceLabelFieldEntries(schema: z.ZodTypeAny): ResourceLabelFieldEntry[] {\n  const acc: ResourceLabelFieldEntry[] = [];\n  collectInto(schema, '', 0, acc);\n  return acc;\n}\n\nfunction collectInto(\n  schema: z.ZodTypeAny,\n  prefix: string,\n  depth: number,\n  acc: ResourceLabelFieldEntry[],\n): void {\n  let shape: Record<string, z.ZodTypeAny> | undefined;\n  let unionMembers: z.ZodTypeAny[] = [];\n  try {\n    /*\n     * A UNION of objects is walked PER MEMBER, merged by field name (the first member owning a key keeps\n     * it), so a member-only field — rendered under a `<DiscriminatorSwitch>`, or as the one member an item\n     * resolved to — still resolves its label. Membership is `getUnionObjectMembers`: a declared\n     * `z.discriminatedUnion`, or a plain `z.union` of objects one key discriminates — every member declares\n     * it as a literal with disjoint values, or omits it while being a `z.strictObject` (at most one member may\n     * omit it, since a strict member rejects the key, its absence places a value exactly). The compliance\n     * programme is that second case: V1 predates `schemaVersion` and omits it; V2 declares `z.literal(2)`.\n     * The display resolves an item's member through the SAME discriminator (`resolveDiscriminatedUnionVariant`),\n     * so the walk collects exactly the fields a rendered member can show.\n     *\n     * The plain-union half is #1022. The walk used to resolve unions only through `getObjectLikeFieldShape`,\n     * which knows DECLARED discriminated unions alone; the compliance programme's `documentationRequirements`\n     * items are `z.union([V1, V2])` keyed on `schemaVersion`, so nothing inside an item — its\n     * `governanceScope.subjectKind`, declaring `GovernedDocumentGovernanceSubjectKind` — had an entry, and\n     * its words could not resolve.\n     *\n     * CONTRACT with the application label deciders: a union `getUnionObjectMembers` rejects yields no shape\n     * here, so this walk collects NOTHING below it and asks for no word there. The labelling planner and the\n     * frontend label introspection mirror that by registering no enum of any shape anywhere in such a\n     * subtree (`insideUnresolvableUnion`) — change one side and the other plans words nobody reads.\n     *\n     * Anything else resolves the way the form/display RENDER path does (`getObjectLikeFieldShape`): a plain\n     * object's shape, or nothing.\n     */\n    unionMembers = getUnionObjectMembers(unwrapSchema(schema));\n    shape = unionMembers.length > 0\n      ? mergeUnionMemberShapes(unionMembers)\n      : AutomatedLayoutFrontendUtils.getObjectLikeFieldShape(schema, { commonOnly: false });\n  } catch {\n    return;\n  }\n  if (!shape) return;\n\n  /*\n   * The union's discriminator is collected across EVERY member, carrying the members' declared vocabulary\n   * only when they all agree — see `synthesizeUnionDiscriminatorEnums`, which the application labelling\n   * planner and the frontend label introspection call too, so the words asked for here and the words\n   * planned there come from one synthesis (#1021). The render path needs no change: it resolves the ACTUAL\n   * member and looks its value up in the resulting map.\n   */\n  const discriminatorEnums = synthesizeUnionDiscriminatorEnums(unionMembers);\n\n  for (const [name, fieldSchema] of Object.entries(shape)) {\n    const path = prefix ? `${prefix}.${name}` : name;\n    acc.push({ path, leaf: name, schema: discriminatorEnums[name] ?? fieldSchema });\n    if (depth < MAX_NESTED_FIELD_DEPTH && getSchemaType(fieldSchema) === FieldSchemaType.OBJECT) {\n      collectInto(fieldSchema, path, depth + 1, acc);\n    }\n    /*\n     * Descend into ARRAY-OF-OBJECT items too, under the item's INDEX-FREE path\n     * (`successCriteria.horizon`, never `successCriteria[0].horizon`): every item of one array\n     * shares one schema, so labels are per-FIELD, not per-row. Without this, a labelled enum\n     * inside an entry collection — a criterion's `horizon`, a constraint's `kind` — had no entry\n     * in `enumLabels`/`fieldLabels` at all and rendered its raw wire value, while the identical\n     * enum ONE level up resolved fine. The render path strips indices before its lookup\n     * (`DisplayField`), so the two sides meet on the same key.\n     *\n     * An item that is a union of objects is OBJECT-typed here too (`getSchemaType` reads a union of objects\n     * through its first member), and the recursion walks it per member — see the top of this function.\n     */\n    if (depth < MAX_NESTED_FIELD_DEPTH && getSchemaType(fieldSchema) === FieldSchemaType.ARRAY) {\n      const itemSchema = getArrayItemSchema(fieldSchema);\n      if (itemSchema && getSchemaType(itemSchema) === FieldSchemaType.OBJECT) {\n        collectInto(itemSchema, path, depth + 1, acc);\n      }\n    }\n  }\n}\n\n/** Merge a union's member shapes by field name; the first member declaring a key keeps its schema. */\nfunction mergeUnionMemberShapes(members: readonly z.ZodTypeAny[]): Record<string, z.ZodTypeAny> {\n  const merged: Record<string, z.ZodTypeAny> = {};\n  for (const member of members) {\n    for (const [name, fieldSchema] of Object.entries(getZodObjectShape(member))) {\n      if (!Object.prototype.hasOwnProperty.call(merged, name)) merged[name] = fieldSchema as z.ZodTypeAny;\n    }\n  }\n  return merged;\n}\n\n/**\n * The enum-bearing schema behind a collected field, if any: a direct enum (or string literal), or the\n * ELEMENT of an enum array (e.g. `roles: z.array(z.union([z.enum(CORE_ORG_ROLES), z.string()]))`, whose\n * union element still yields enum values via `getEnumValues`). Without the array branch, array-of-enum\n * fields rendered their members raw (e.g. `ORG_ADMIN`).\n *\n * Delegates to `resolveFieldEnumSchema` (`@wildo-ai/presets-components-models`), the same answer the dev\n * companion's labelling planner and frontend label introspection read, so a field this renderer looks words\n * up for is a field those plan words for (#1021, #1079).\n */\nexport function resolveResourceLabelEnumSchema(fieldSchema: z.ZodTypeAny): z.ZodTypeAny | undefined {\n  return resolveFieldEnumSchema(fieldSchema);\n}\n\n/**\n * The system enum a collected field DECLARES — the vocabulary whose `system_enums.<name>.<value>` words\n * label its values — or `undefined` when it declares none.\n *\n * Reads the enum-bearing schema ({@link resolveResourceLabelEnumSchema}: the field itself, or an array's\n * element) through `resolveDeclaredSystemEnumName`, the same function the dev companion's labelling planner\n * uses to decide which fields' words it plans under `system_enums`. That shared answer is the whole point:\n * the cascade used to guess the enum from the VALUE across every registered vocabulary, so a value two\n * vocabularies share read the first one's word (#966).\n */\nexport function resolveResourceLabelSystemEnumName(fieldSchema: z.ZodTypeAny): string | undefined {\n  const enumSchema = resolveResourceLabelEnumSchema(fieldSchema);\n  if (!enumSchema) return undefined;\n  return resolveDeclaredSystemEnumName(enumSchema, getEnumValues(enumSchema));\n}\n"]}
+{"version":3,"file":"resource-label-field-paths.frontend.utils.js","sourceRoot":"","sources":["../../../../../src/core/resources/resource-label-field-paths.frontend.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The label-bearing field paths of a schema — the exact population `useResourceLabels` asks i18n for.\n *\n * Extracted from `useResourceLabels` so the question \"which keys will this surface look up?\" has ONE\n * answer that a hook and a test can both ask. Before this it was module-private, so any check that\n * wanted to hold an authored label tree to what a surface renders had to re-derive the walk — and a\n * re-derived walk is the copy that drifts first (a discriminated union's merged discriminator, the\n * index-free array-item paths, the depth bound).\n *\n * The workbench's aspect-popup label totality check (#638) is the first such consumer: it walks every\n * family aspect's item schema through THIS function, so a key it reports missing is a key the popup\n * really asks for, and a key it does not report is one the popup never asks for.\n */\n\nimport type { z } from 'zod';\nimport {\n  FieldSchemaType,\n  getArrayItemSchema,\n  getEnumValues,\n  getSchemaType,\n  getUnionObjectMembers,\n  getZodObjectShape,\n  isFieldContainerSchema,\n  unwrapSchema,\n} from '@wildo-ai/zod-decorators';\nimport { resolveDeclaredSystemEnumName, resolveFieldEnumSchema, synthesizeUnionDiscriminatorEnums } from '@wildo-ai/presets-components-models';\nimport { AutomatedLayoutFrontendUtils } from '~wildo-frontend-lib/core/automated-layout/automated-layout.frontend.utils';\n\n/** Max object-nesting depth walked when collecting label/enum entries (guards against\n *  pathological / self-referential schemas while covering real nested settings objects\n *  like `privacy.consentedPurposes` and `regional.dateFormat`). */\nconst MAX_NESTED_FIELD_DEPTH = 4;\n\n/** A field reachable from the resource schema, identified by its dotted runtime path. */\nexport interface ResourceLabelFieldEntry {\n  /** Dotted path as seen by `DisplayField`/`FormField` inside an `ObjectScope` (e.g. `privacy.consentedPurposes`). */\n  path: string;\n  /** Final path segment, used for the unresolved-label rendering. */\n  leaf: string;\n  /** The field's Zod schema (decorators intact). */\n  schema: z.ZodTypeAny;\n}\n\n/**\n * Flatten a resource schema into every label-bearing field path, recursing into nested\n * OBJECT fields so that fields rendered inside an `<ObjectScope name=\"privacy\">` (which look\n * their labels/enum-labels up by the dotted `privacy.consentedPurposes` key) resolve the\n * same way top-level fields do. Without this, nested object fields fell back to no label /\n * raw enum values. Arrays of scalars are recorded as leaves (their element enum, if any, is\n * handled by {@link resolveResourceLabelEnumSchema}); arrays of OBJECTS are descended into under\n * their index-free path.\n *\n * Throws only if the underlying shape resolution throws; callers that render treat that as\n * \"no entries yet\" (a schema briefly undefined on first mount).\n */\nexport function collectResourceLabelFieldEntries(schema: z.ZodTypeAny): ResourceLabelFieldEntry[] {\n  const acc: ResourceLabelFieldEntry[] = [];\n  collectInto(schema, '', 0, acc);\n  return acc;\n}\n\nfunction collectInto(\n  schema: z.ZodTypeAny,\n  prefix: string,\n  depth: number,\n  acc: ResourceLabelFieldEntry[],\n): void {\n  let shape: Record<string, z.ZodTypeAny> | undefined;\n  let unionMembers: z.ZodTypeAny[] = [];\n  try {\n    /*\n     * A UNION of objects is walked PER MEMBER, merged by field name (the first member owning a key keeps\n     * it), so a member-only field — rendered under a `<DiscriminatorSwitch>`, or as the one member an item\n     * resolved to — still resolves its label. Membership is `getUnionObjectMembers`: a declared\n     * `z.discriminatedUnion`, or a plain `z.union` of objects one key discriminates — every member declares\n     * it as a literal with disjoint values, or omits it while being a `z.strictObject` (at most one member may\n     * omit it, since a strict member rejects the key, its absence places a value exactly). The compliance\n     * programme is that second case: V1 predates `schemaVersion` and omits it; V2 declares `z.literal(2)`.\n     * The display resolves an item's member through the SAME discriminator (`resolveDiscriminatedUnionVariant`),\n     * so the walk collects exactly the fields a rendered member can show.\n     *\n     * The plain-union half is #1022. The walk used to resolve unions only through `getObjectLikeFieldShape`,\n     * which knows DECLARED discriminated unions alone; the compliance programme's `documentationRequirements`\n     * items are `z.union([V1, V2])` keyed on `schemaVersion`, so nothing inside an item — its\n     * `governanceScope.subjectKind`, declaring `GovernedDocumentGovernanceSubjectKind` — had an entry, and\n     * its words could not resolve.\n     *\n     * CONTRACT with the application label deciders: a union `getUnionObjectMembers` rejects yields no shape\n     * here, so this walk collects NOTHING below it and asks for no word there. The labelling planner and the\n     * frontend label introspection mirror that by registering no enum of any shape anywhere in such a\n     * subtree (`insideUnresolvableUnion`) — change one side and the other plans words nobody reads.\n     *\n     * Anything else resolves the way the form/display RENDER path does (`getObjectLikeFieldShape`): a plain\n     * object's shape, or nothing.\n     */\n    unionMembers = getUnionObjectMembers(unwrapSchema(schema));\n    shape = unionMembers.length > 0\n      ? mergeUnionMemberShapes(unionMembers)\n      : AutomatedLayoutFrontendUtils.getObjectLikeFieldShape(schema, { commonOnly: false });\n  } catch {\n    return;\n  }\n  if (!shape) return;\n\n  /*\n   * The union's discriminator is collected across EVERY member, carrying the members' declared vocabulary\n   * only when they all agree — see `synthesizeUnionDiscriminatorEnums`, which the application labelling\n   * planner and the frontend label introspection call too, so the words asked for here and the words\n   * planned there come from one synthesis (#1021). The render path needs no change: it resolves the ACTUAL\n   * member and looks its value up in the resulting map.\n   */\n  const discriminatorEnums = synthesizeUnionDiscriminatorEnums(unionMembers);\n\n  for (const [name, fieldSchema] of Object.entries(shape)) {\n    const path = prefix ? `${prefix}.${name}` : name;\n    acc.push({ path, leaf: name, schema: discriminatorEnums[name] ?? fieldSchema });\n    /*\n     * Descend only into a schema that HOLDS FIELDS (`isFieldContainerSchema`): a plain object, or a `versioned()`\n     * one, whose children the display renders field by field. A structured value — money, address, duration,\n     * code, file, every range — is a Zod object too, but its parts are labelled by the value's own component, so\n     * nothing here asks for a word below it. The application labelling planner and the frontend label\n     * introspection stop at the same answer, so the words planned and the words asked for stay one set (#1959).\n     */\n    if (depth < MAX_NESTED_FIELD_DEPTH && isFieldContainerSchema(fieldSchema)) {\n      collectInto(fieldSchema, path, depth + 1, acc);\n    }\n    /*\n     * Descend into ARRAY-OF-OBJECT items too, under the item's INDEX-FREE path\n     * (`successCriteria.horizon`, never `successCriteria[0].horizon`): every item of one array\n     * shares one schema, so labels are per-FIELD, not per-row. Without this, a labelled enum\n     * inside an entry collection — a criterion's `horizon`, a constraint's `kind` — had no entry\n     * in `enumLabels`/`fieldLabels` at all and rendered its raw wire value, while the identical\n     * enum ONE level up resolved fine. The render path strips indices before its lookup\n     * (`DisplayField`), so the two sides meet on the same key.\n     *\n     * An item that is a union of objects is OBJECT-typed here too (`getSchemaType` reads a union of objects\n     * through its first member), and the recursion walks it per member — see the top of this function.\n     */\n    if (depth < MAX_NESTED_FIELD_DEPTH && getSchemaType(fieldSchema) === FieldSchemaType.ARRAY) {\n      const itemSchema = getArrayItemSchema(fieldSchema);\n      if (itemSchema && isFieldContainerSchema(itemSchema)) {\n        collectInto(itemSchema, path, depth + 1, acc);\n      }\n    }\n  }\n}\n\n/** Merge a union's member shapes by field name; the first member declaring a key keeps its schema. */\nfunction mergeUnionMemberShapes(members: readonly z.ZodTypeAny[]): Record<string, z.ZodTypeAny> {\n  const merged: Record<string, z.ZodTypeAny> = {};\n  for (const member of members) {\n    for (const [name, fieldSchema] of Object.entries(getZodObjectShape(member))) {\n      if (!Object.prototype.hasOwnProperty.call(merged, name)) merged[name] = fieldSchema as z.ZodTypeAny;\n    }\n  }\n  return merged;\n}\n\n/**\n * The enum-bearing schema behind a collected field, if any: a direct enum (or string literal), or the\n * ELEMENT of an enum array (e.g. `roles: z.array(z.union([z.enum(CORE_ORG_ROLES), z.string()]))`, whose\n * union element still yields enum values via `getEnumValues`). Without the array branch, array-of-enum\n * fields rendered their members raw (e.g. `ORG_ADMIN`).\n *\n * Delegates to `resolveFieldEnumSchema` (`@wildo-ai/presets-components-models`), the same answer the dev\n * companion's labelling planner and frontend label introspection read, so a field this renderer looks words\n * up for is a field those plan words for (#1021, #1079).\n */\nexport function resolveResourceLabelEnumSchema(fieldSchema: z.ZodTypeAny): z.ZodTypeAny | undefined {\n  return resolveFieldEnumSchema(fieldSchema);\n}\n\n/**\n * The system enum a collected field DECLARES — the vocabulary whose words label its values\n * (`resolveVocabularyWordKey`: `system_enums.<name>.<value>`, or a feature's and a limit's billing section) — or\n * `undefined` when it declares none.\n *\n * Reads the enum-bearing schema ({@link resolveResourceLabelEnumSchema}: the field itself, or an array's\n * element) through `resolveDeclaredSystemEnumName`, the same function the dev companion's labelling planner\n * uses to decide which fields' words it plans under `system_enums`. That shared answer is the whole point:\n * the cascade used to guess the enum from the VALUE across every registered vocabulary, so a value two\n * vocabularies share read the first one's word (#966).\n */\nexport function resolveResourceLabelSystemEnumName(fieldSchema: z.ZodTypeAny): string | undefined {\n  const enumSchema = resolveResourceLabelEnumSchema(fieldSchema);\n  if (!enumSchema) return undefined;\n  return resolveDeclaredSystemEnumName(enumSchema, getEnumValues(enumSchema));\n}\n"]}

package/dist/esm/core/resources/resources-repository.frontend.service.d.ts

@@ -43,6 +43,12 @@ export declare class ResourcesRepositoryFrontendService {
         [key: string]: string;
     }, customShared_ResourcesRelationships?: ResourceRelationship[], excludedResourceTypes?: ReadonlySet<string>, resourceUIBehavior?: ResourceUIBehavior, customNotificationBadgeDefinitions?: NotificationBadgeDefinition[]): Promise<void>;
     private normalizeResourceConfigurationRelationships;
+    /**
+     * Run {@link carryReferenceIdentityOntoCustomRequestDto} over every author-owned request DTO of
+     * every resource. The general overlay below skips these DTOs on purpose; this carries the one fact
+     * it may not skip — which of their fields are references.
+     */
+    private carryReferenceIdentityOntoCustomRequestDtos;
     /**
      * Re-applies ui-behavior `fields` decorators onto the rebuilt operation DTOs the frontend
      * reads — both the DISPLAY DTOs (`responseDto` / `summaryDto` / `contextDto`) and the

package/dist/esm/core/resources/resources-repository.frontend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resources-repository.frontend.service.d.ts","sourceRoot":"","sources":["../../../../../src/core/resources/resources-repository.frontend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,sEAAsE,CAAC;AAC9G,OAAO,EAAE,gCAAgC,EAAE,MAAM,gFAAgF,CAAC;AAOlI,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+DAA+D,CAAC;AAIxG,OAAO,EAGL,2CAA2C,EAE3C,oBAAoB,EAoByC,MAAM,uBAAuB,CAAC;AAC7F,OAAO,KAAK,EAEV,2BAA2B,EAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAGV,yBAAyB,EAE1B,MAAM,+DAA+D,CAAC;AAgJvE,qBAAa,kCAAkC;IAM3C,OAAO,CAAC,UAAU;IALpB,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,mBAAmB,CAAiD;gBAGlE,UAAU,EAAE,sBAAsB;IAG5C;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAa/B;;;;;;;;;OASG;IACU,mBAAmB,CAC9B,8CAA8C,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,2CAA2C,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;KAAE,EAC9H,oCAAoC,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,EAChE,mCAAmC,CAAC,EAAE,oBAAoB,EAAE,EAC5D,qBAAqB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,EAC3C,kBAAkB,CAAC,EAAE,kBAAkB,EACvC,kCAAkC,CAAC,EAAE,2BAA2B,EAAE,GACjE,OAAO,CAAC,IAAI,CAAC;IAmPhB,OAAO,CAAC,2CAA2C;IA4BnD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,8BAA8B;IA0BtC;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,mCAAmC;IAyN3C,OAAO,CAAC,qCAAqC;IAsB7C,OAAO,CAAC,qCAAqC;IAsC7C;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,mCAAmC;IAwJ3C;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,wCAAwC;IAsFhD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,wBAAwB;IAyChC;;;;;;OAMG;IACH,OAAO,CAAC,gCAAgC;IAgBxC;;OAEG;IACI,oBAAoB,IAAI,yBAAyB;IAUxD;;OAEG;IACI,yBAAyB,IAAI,MAAM,EAAE;IAO5C;;OAEG;IACI,eAAe,IAAI;QACxB,uBAAuB,EAAE,MAAM,EAAE,CAAC;KACnC;IAUD;;;OAGG;IACI,sBAAsB,IAAI,gCAAgC;IAUjE;;;;;;;;;;;;OAYG;IACI,wBAAwB,IAAI,sBAAsB;IAIzD;;;;;;OAMG;IACH,OAAO,CAAC,4BAA4B;IAuCpC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,kCAAkC;IAoD1C;;;;;;OAMG;IACH,OAAO,CAAC,sCAAsC;CAkC/C"}
+{"version":3,"file":"resources-repository.frontend.service.d.ts","sourceRoot":"","sources":["../../../../../src/core/resources/resources-repository.frontend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,sEAAsE,CAAC;AAC9G,OAAO,EAAE,gCAAgC,EAAE,MAAM,gFAAgF,CAAC;AAOlI,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+DAA+D,CAAC;AAIxG,OAAO,EAGL,2CAA2C,EAE3C,oBAAoB,EAoByC,MAAM,uBAAuB,CAAC;AAC7F,OAAO,KAAK,EAEV,2BAA2B,EAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAGV,yBAAyB,EAE1B,MAAM,+DAA+D,CAAC;AAuNvE,qBAAa,kCAAkC;IAM3C,OAAO,CAAC,UAAU;IALpB,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,mBAAmB,CAAiD;gBAGlE,UAAU,EAAE,sBAAsB;IAG5C;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAa/B;;;;;;;;;OASG;IACU,mBAAmB,CAC9B,8CAA8C,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,2CAA2C,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;KAAE,EAC9H,oCAAoC,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,EAChE,mCAAmC,CAAC,EAAE,oBAAoB,EAAE,EAC5D,qBAAqB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,EAC3C,kBAAkB,CAAC,EAAE,kBAAkB,EACvC,kCAAkC,CAAC,EAAE,2BAA2B,EAAE,GACjE,OAAO,CAAC,IAAI,CAAC;IA2PhB,OAAO,CAAC,2CAA2C;IA4BnD;;;;OAIG;IACH,OAAO,CAAC,2CAA2C;IAYnD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,8BAA8B;IA0BtC;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,mCAAmC;IAyN3C,OAAO,CAAC,qCAAqC;IAsB7C,OAAO,CAAC,qCAAqC;IAsC7C;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,mCAAmC;IAwJ3C;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,wCAAwC;IAsFhD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,wBAAwB;IAyChC;;;;;;OAMG;IACH,OAAO,CAAC,gCAAgC;IAgBxC;;OAEG;IACI,oBAAoB,IAAI,yBAAyB;IAUxD;;OAEG;IACI,yBAAyB,IAAI,MAAM,EAAE;IAO5C;;OAEG;IACI,eAAe,IAAI;QACxB,uBAAuB,EAAE,MAAM,EAAE,CAAC;KACnC;IAUD;;;OAGG;IACI,sBAAsB,IAAI,gCAAgC;IAUjE;;;;;;;;;;;;OAYG;IACI,wBAAwB,IAAI,sBAAsB;IAIzD;;;;;;OAMG;IACH,OAAO,CAAC,4BAA4B;IAuCpC;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,kCAAkC;IAoD1C;;;;;;OAMG;IACH,OAAO,CAAC,sCAAsC;CAkC/C"}

package/dist/esm/core/resources/resources-repository.frontend.service.js

@@ -17,7 +17,7 @@ import { envLoader } from '../../core/runtime/env-variable-loader.frontend.servi
 import { FRONTEND_SCHEMA_KEY, } from '../../core/resources/resources.frontend.schemas.js';
 import { ENGINE_RUNTIME_REQUIRED_RESOURCE_TYPES, ResourcePrimaryScope, coreShared_ResourcesConfigurations_FactoryMap, coreSharedResourceRelationship, coreResourceShared_FieldIdentifier, coreResourceShared_FieldIdentifierPriority, ResourceOperationVariantType, ResourceOperationFrontendSurface, ResourcesConfigOperationsUrlsBuilderUtils, ResourcesConfigOperationsDtosBuilderUtils, ErrorType, ErrorCustomMessageReference, computeSubtreeMap, CoreResourceOperation, deriveRequestDto, ParentDisplay, RelationshipDisplayConfigSchema, reconcileGeneratedRelationshipBulkOperations, Resources_SharedUtils, ResourceRelationshipAccessScopeStrategy, coreNotificationBadgeDefinitions, findDuplicateRelationshipRegistrations, describeCaughtError } from '@wildo-ai/saas-models';
 import { buildResourceCompositeViewTranslationRef, } from '../../core/config/composite-view.schemas.js';
-import { getZodObjectShape, isForeignKeyField, unwrapSchema, getCustomFieldMetadata, addDecorators, ZodDecorator, ForeignKeyDisplayMode, SCHEMA_METADATA, getFileMetadata, getFieldUIDisplayConfig, declaredFileNatureCanDisplay, FileDisplayPresentation, FileActivationPolicy } from '@wildo-ai/zod-decorators';
+import { getZodObjectShape, isForeignKeyField, getSchemaType, FieldSchemaType, unwrapSchema, getCustomFieldMetadata, addDecorators, ZodDecorator, ForeignKeyDisplayMode, SCHEMA_METADATA, getFileMetadata, getFieldUIDisplayConfig, declaredFileNatureCanDisplay, FileDisplayPresentation, FileActivationPolicy } from '@wildo-ai/zod-decorators';
 import { sharedErrorBuilder } from '../../core/errors/errors-builder.frontend.services.js';
 import { AutomatedLayoutFrontendUtils } from '../../core/automated-layout/automated-layout.frontend.utils.js';
 /**
@@ -144,6 +144,76 @@ function overlayUiBehaviorFieldDecorators(dto, frontendSchema) {
         dtoField[SCHEMA_METADATA] = { ...dtoMeta, ...frontendMeta };
     }
 }
+/**
+ * The decorators that make a field a REFERENCE — its identity as a foreign key and how its picker
+ * reads — and nothing else. Named so the carry-over below cannot quietly grow into a general overlay.
+ */
+const REFERENCE_IDENTITY_DECORATORS = [ZodDecorator.IS_FOREIGN_KEY, ZodDecorator.FOREIGN_KEY_UI];
+/**
+ * Give a CUSTOM request DTO's field the reference identity of the resource field it names.
+ *
+ * ## Why this exists
+ *
+ * A custom operation's `requestDto` is authored by hand, and the natural spelling of "assign this todo
+ * to a user" is `requestDto: z.object({ assignedToUserId: z.string().min(1) })` — the field the
+ * operation writes, by its own name. That field reached every form as a bare STRING: the form decides
+ * "reference picker" from the field's own `isForeignKey` decorator, and nothing put one there. So
+ * Wonder Todos' "Assign" asked for a user by making the person type a raw id into a text box, while
+ * the backend — which resolves the reference through the RELATIONSHIP that names `assignedToUserId`,
+ * scope confinement and all — knew perfectly well what it was.
+ *
+ * The resource already declares the answer twice (the schema field is `.isForeignKey()`, and a
+ * relationship names it as its `foreignKeyField`). Asking every author to restate it on every custom
+ * operation that writes the field is a question the framework can derive, and a forgotten restatement
+ * fails silently as a text box.
+ *
+ * ## Why ONLY the reference identity, and not the general overlay
+ *
+ * `overlayUiBehaviorDtoDecorators` deliberately skips custom request DTOs: a custom DTO is the
+ * author's shape, and copying the resource field's whole metadata would drag STRUCTURAL decorators
+ * across with it — `excludeFromUpdate` on the resource field would hide the very input the custom
+ * operation exists to collect. Whether a field IS a reference is not that kind of fact: it is what the
+ * value MEANS, and a custom operation that writes `assignedToUserId` writes the same kind of value.
+ *
+ * ## Guards
+ *
+ * - a field the author already declared a reference is left exactly as authored, `foreignKeyUI` too;
+ * - the shapes must agree — a scalar id against a scalar foreign key, a list against a list — or the
+ *   two fields merely share a name;
+ * - only metadata is written, so the DTO's parse contract is untouched (the same argument as the
+ *   general overlay's).
+ *
+ * Caveat, shared with the general overlay: the write lands on the author's field INSTANCE. A field
+ * schema reused as a constant in some other DTO carries the reference identity there too — correct
+ * whenever the reuse means the same value, which is the only reason to reuse a field schema.
+ */
+function carryReferenceIdentityOntoCustomRequestDto(requestDto, resourceSchema) {
+    if (!requestDto || !resourceSchema)
+        return;
+    const dtoShape = AutomatedLayoutFrontendUtils.getObjectLikeFieldShape(requestDto, { commonOnly: false });
+    const resourceShape = AutomatedLayoutFrontendUtils.getObjectLikeFieldShape(resourceSchema, { commonOnly: false });
+    if (!dtoShape || !resourceShape)
+        return;
+    for (const [fieldName, dtoField] of Object.entries(dtoShape)) {
+        const resourceField = resourceShape[fieldName];
+        if (!dtoField || !resourceField)
+            continue;
+        if (!isForeignKeyField(resourceField) || isForeignKeyField(dtoField))
+            continue;
+        const dtoIsList = getSchemaType(dtoField) === FieldSchemaType.ARRAY;
+        const resourceIsList = getSchemaType(resourceField) === FieldSchemaType.ARRAY;
+        if (dtoIsList !== resourceIsList)
+            continue;
+        const resourceMeta = getCustomFieldMetadata(resourceField);
+        const carried = {};
+        for (const key of REFERENCE_IDENTITY_DECORATORS) {
+            if (key in resourceMeta)
+                carried[key] = resourceMeta[key];
+        }
+        // `as any` for the symbol-keyed metadata write — same idiom as `overlayUiBehaviorFieldDecorators`.
+        dtoField[SCHEMA_METADATA] = { ...getCustomFieldMetadata(dtoField), ...carried };
+    }
+}
 export class ResourcesRepositoryFrontendService {
     httpClient;
     registry = null;
@@ -282,6 +352,11 @@ export class ResourcesRepositoryFrontendService {
             // MUST run after the rebuild, or it is silently discarded. See
             // `overlayUiBehaviorFieldDecorators` for the rationale.
             this.overlayUiBehaviorDtoDecorators(frontendResourceConfigurations, resourceUIBehavior);
+            // A custom request DTO that names one of the resource's foreign keys collects a REFERENCE, and
+            // must render as one (the searchable picker, not a text box). Every resource, preset or not:
+            // the identity lives on the schema, not in the ui-behavior. See
+            // `carryReferenceIdentityOntoCustomRequestDto`.
+            this.carryReferenceIdentityOntoCustomRequestDtos(frontendResourceConfigurations);
             // Reverse map fieldIdentifier → REFERENCED resourceType — built by THE shared
             // implementation (Resources_SharedUtils.buildFieldIdentifierToResourceTypeMap).
             // This repository and the backend registry service used to carry hand-kept
@@ -349,6 +424,20 @@ export class ResourcesRepositoryFrontendService {
             };
         }
     }
+    /**
+     * Run {@link carryReferenceIdentityOntoCustomRequestDto} over every author-owned request DTO of
+     * every resource. The general overlay below skips these DTOs on purpose; this carries the one fact
+     * it may not skip — which of their fields are references.
+     */
+    carryReferenceIdentityOntoCustomRequestDtos(resourceConfigurations) {
+        for (const entry of Object.values(resourceConfigurations)) {
+            for (const op of entry.operations ?? []) {
+                if (op.hasCustomRequestDto) {
+                    carryReferenceIdentityOntoCustomRequestDto(op.requestDto, entry.mainSchema);
+                }
+            }
+        }
+    }
     /**
      * Re-applies ui-behavior `fields` decorators onto the rebuilt operation DTOs the frontend
      * reads — both the DISPLAY DTOs (`responseDto` / `summaryDto` / `contextDto`) and the