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

package/dist/esm/core/resources/useOperationDirectExecution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOperationDirectExecution.js","sourceRoot":"","sources":["../../../../../src/core/resources/useOperationDirectExecution.ts"],"names":[],"mappings":"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","sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState } from 'react';\n\nimport type { FieldMetaEntry } from '@wildo-ai/saas-models';\nimport { ResourcesConfig_OperationPathUtils } from '@wildo-ai/saas-models';\nimport { FrontendComponentType } from '@wildo-ai/presets-components-models';\nimport { useI18n } from '~wildo-frontend-lib/core/i18n/useI18n';\nimport { resolveComponentLabel } from '~wildo-frontend-lib/core/i18n/component-label-resolution.utils';\nimport { useResourceOperationViewContext } from '~wildo-frontend-lib/core/resources/ResourceOperationViewContext';\nimport { FrontendResourceUtils, frontendResourceUtils } from '~wildo-frontend-lib/core/resources/frontend-resource.utils';\nimport { useResourceRegistry } from '~wildo-frontend-lib/core/resources/useResourceRegistry';\nimport {\n  allowsDirectOperationFallback,\n  MissingRMMRuntimeError,\n  resolveDeclaredUpdateLikeMutationFallbackMode,\n} from '~wildo-frontend-lib/core/resources/rmm/update-like-mutation-fallback.frontend';\nimport { useResourceRMM } from '~wildo-frontend-lib/core/resources/rmm/useResourceRMM';\nimport { mutationErrorForReport } from '~wildo-frontend-lib/core/resources/rmm/mutation-error-report.utils';\nimport { ConflictStrategy, MutationPriority, MutationSourceType, MutationType } from '~wildo-frontend-lib/core/resources/rmm/types';\nimport {\n  performCanonicalRMMRead,\n  resolveCanonicalRMMReadOperationPathKey,\n} from '~wildo-frontend-lib/core/resources/rmm/canonical-read.frontend.utils';\nimport { isSingleResourceUpdateLikeOperation } from '~wildo-frontend-lib/core/resources/operation-semantics.frontend.utils';\nimport { useResourceOperationOutcomeEmitter } from '~wildo-frontend-lib/core/resources/useResourceOperationOutcomeEmitter';\n\nexport interface UseOperationDirectExecutionParams {\n  /** Replaces what happens AFTER a success. The outcome is announced either way. Omitted: go back within the zone. */\n  onSuccess?: (result: unknown) => void;\n  /** The message a failure is reported under. */\n  errorMessage: string;\n  /** The component a failure is attributed to in the report. */\n  errorComponent: string;\n}\n\nexport interface OperationDirectExecution {\n  /**\n   * Execute the hosted operation with this exact request body — no form, no validation pass beyond\n   * the server's. Resolves once the outcome has been announced (success) or reported (failure).\n   * Omitted means \"no body at all\", which is what a zero-input action sends — not an empty object.\n   */\n  execute: (requestData?: Record<string, unknown>) => Promise<void>;\n  /** True while a request is in flight. */\n  isExecuting: boolean;\n  /**\n   * True while an update-like operation with no target id in its context is resolving that id from\n   * the canonical READ. Execution must wait for it: the RMM that carries the mutation is keyed on it.\n   */\n  isBootstrapping: boolean;\n  /**\n   * The success path itself — announce the outcome, then `onSuccess` or go back. Exposed so a host\n   * that ALSO renders a form hands the form this very function, and \"what success means\" has one\n   * definition across the form and the form-less paths.\n   */\n  completeWithSuccess: (result: unknown) => void;\n  /** The failure path — reports under `errorMessage` / `errorComponent`. Same reason as above. */\n  reportFailure: (error: Error) => void;\n}\n\ntype BootstrappedTargetRow = {\n  contextKey: string;\n  row: Record<string, unknown>;\n};\n\n/**\n * Execute the NEAREST operation view's operation with a body the caller already has — the form-less\n * half of every operation host.\n *\n * ## Why this is its own hook\n *\n * It began as the zero-input branch of `ResourceLayout_SemanticOperationFallback` (\"Run\" with an\n * empty body), and a DROPDOWN action needs exactly the same thing with a one-field body: the pick is\n * the submission. The alternative — a second copy of the RMM-or-direct decision, the canonical-READ\n * bootstrap and the outcome announcement inside the dropdown — is the shape this package has already\n * paid for once (the bulk selector, spelled two ways). One hook, so a host that executes without a\n * form inherits the whole contract by using it:\n *\n * - **update-like single-resource operations run through the RMM**, never the plain `doOperation`\n *   lane, and fail closed with `MissingRMMRuntimeError` rather than writing without it;\n * - **a missing target id is resolved first** from the canonical READ, so a detail-less context (a\n *   bulk bar, a singleton) still mutates the right row;\n * - **everything else runs `executeCurrentOperation`**, which merges a bulk selection into the body;\n * - **the outcome is ALWAYS announced**, and `onSuccess` replaces only what happens next.\n *\n * Confirmation is NOT decided here. Each host owns the dialog it shows, because only the host knows\n * whether a person has already acted deliberately (typed a phrase, pressed Submit) or merely picked.\n *\n * Must be called under a `ResourceOperationViewProvider` for the operation being executed — a\n * detached host establishes one (`ResourceOperationDetachedHost`, `ResourceOperationActionDropdown`).\n */\nexport function useOperationDirectExecution({\n  onSuccess,\n  errorMessage,\n  errorComponent,\n}: UseOperationDirectExecutionParams): OperationDirectExecution {\n  const {\n    resourceContext: currentResourceContext,\n    resourceType,\n    operation,\n    reportError,\n    goBackWithinZone,\n    executeCurrentOperation,\n  } = useResourceOperationViewContext();\n  const { doOperation, registry } = useResourceRegistry();\n  // `resource` as well as the component: a resource may override the component's words, and the\n  // fallback this was extracted from resolved them resource-scoped.\n  const { tComponent } = useI18n({ component: FrontendComponentType.RESOURCES_LAYOUTS_ACTION, resource: resourceType });\n  const doOperationRef = useRef(doOperation);\n  doOperationRef.current = doOperation;\n\n  const [isExecuting, setIsExecuting] = useState(false);\n  const [isBootstrapping, setIsBootstrapping] = useState(false);\n  const [bootstrappedRow, setBootstrappedRow] = useState<BootstrappedTargetRow | null>(null);\n  /*\n   * A single-row update-like operation addresses ONE row, whichever lane it runs on, so its target id\n   * is resolved (the canonical-READ bootstrap below) for both lanes, and the row's RMM is attached when\n   * the row has one.\n   *\n   * It runs through that RMM when there is one. Without one it runs directly only if the operation\n   * DECLARED the direct lane (`operationFrontendConfig.updateLikeMutationFallbackMode`), read through the\n   * same function the form host and `useResourceOperationSurface` read, so the two hosts pick the same lane;\n   * otherwise it fails closed.\n   */\n  const isSingleRowUpdateLike = useMemo(() => isSingleResourceUpdateLikeOperation(operation), [operation]);\n  const acceptsDirectLane = isSingleRowUpdateLike\n    && allowsDirectOperationFallback(resolveDeclaredUpdateLikeMutationFallbackMode(operation));\n\n  const bootstrapContextKey = useMemo(() => JSON.stringify({\n    contextResourceIdentifiers: FrontendResourceUtils.buildContextResourceIdentifiersKey(\n      currentResourceContext.contextResourceIdentifiers ?? {},\n    ),\n    parentResourcesRequirements: currentResourceContext.parentResourcesRequirements ?? [],\n  }), [\n    currentResourceContext.contextResourceIdentifiers,\n    currentResourceContext.parentResourcesRequirements,\n  ]);\n  const routeResourceId = useMemo(() => {\n    const identifier = currentResourceContext.contextResourceIdentifiers?.[resourceType];\n    if (!identifier) {\n      return null;\n    }\n    return frontendResourceUtils.getResourceId(identifier) ?? null;\n  }, [currentResourceContext.contextResourceIdentifiers, resourceType]);\n  const currentResourceId = routeResourceId ?? (\n    bootstrappedRow?.contextKey === bootstrapContextKey\n    && typeof bootstrappedRow.row._id === 'string'\n    && bootstrappedRow.row._id.length > 0\n      ? bootstrappedRow.row._id\n      : null\n  );\n  const contextResourceIdentifiersWithResourceId = useMemo(() => {\n    if (!currentResourceId || currentResourceContext.contextResourceIdentifiers?.[resourceType]) {\n      return currentResourceContext.contextResourceIdentifiers;\n    }\n\n    return {\n      ...currentResourceContext.contextResourceIdentifiers,\n      [resourceType]: currentResourceId,\n    };\n  }, [currentResourceContext.contextResourceIdentifiers, currentResourceId, resourceType]);\n  const contextualParameters = useMemo(() => {\n    return FrontendResourceUtils.buildContextualParameters(\n      contextResourceIdentifiersWithResourceId,\n      registry,\n    );\n  }, [contextResourceIdentifiersWithResourceId, registry]);\n  const canonicalReadOperationPathKey = useMemo(() => {\n    return resolveCanonicalRMMReadOperationPathKey(resourceType, registry, {\n      hasResourceId: Boolean(currentResourceId),\n      contextResourceIdentifiers: contextResourceIdentifiersWithResourceId,\n      contextualParameters,\n    });\n  }, [contextResourceIdentifiersWithResourceId, contextualParameters, currentResourceId, registry, resourceType]);\n  const { rmm } = useResourceRMM({\n    resourceType,\n    resourceId: currentResourceId,\n    doOperationRef,\n    contextualParameters,\n    parentResourcesRequirements: currentResourceContext.parentResourcesRequirements,\n    contextResourceIdentifiers: contextResourceIdentifiersWithResourceId,\n    resourceSchema: registry.resourceConfigurations[resourceType]?.mainSchema,\n    enabled: isSingleRowUpdateLike && !!currentResourceId,\n    conflictPolicy: { strategy: ConflictStrategy.ACCEPT_REMOTE },\n    directFallbackAccepted: acceptsDirectLane,\n  });\n\n  const executionFailedLabel = useMemo(() => {\n    return resolveComponentLabel({\n      tComponent,\n      componentType: FrontendComponentType.RESOURCES_LAYOUTS_ACTION,\n      key: 'executionFailed',\n    });\n  }, [tComponent]);\n\n  /*\n   * Announced with the context that carries the RESOLVED row id, not the route's. A context-addressed\n   * singleton has no id on its route; the id comes from the canonical READ, and a page showing that row\n   * re-reads only when the announcement names it (#1782). The route context named no row, so an action\n   * whose result carries no `_id` (a secret's change outcome) announced a change to nobody.\n   */\n  const announcedContext = useMemo(\n    () => (contextResourceIdentifiersWithResourceId === currentResourceContext.contextResourceIdentifiers\n      ? currentResourceContext\n      : { ...currentResourceContext, contextResourceIdentifiers: contextResourceIdentifiersWithResourceId }),\n    [contextResourceIdentifiersWithResourceId, currentResourceContext],\n  );\n  const announceOutcome = useResourceOperationOutcomeEmitter(announcedContext, operation);\n  const handleSuccess = useCallback((result: unknown) => {\n    announceOutcome(result);\n    if (onSuccess) {\n      onSuccess(result);\n      return;\n    }\n    goBackWithinZone();\n  }, [announceOutcome, goBackWithinZone, onSuccess]);\n\n  const handleError = useCallback((error: Error) => {\n    reportError(error, errorMessage, errorComponent);\n  }, [errorComponent, errorMessage, reportError]);\n\n  useEffect(() => {\n    if (!isSingleRowUpdateLike || currentResourceId || !canonicalReadOperationPathKey) {\n      return;\n    }\n\n    let cancelled = false;\n    setIsBootstrapping(true);\n    void performCanonicalRMMRead({\n      doOperation: doOperationRef.current,\n      readOperationPathKey: canonicalReadOperationPathKey,\n      contextualParameters,\n      parentResourcesRequirements: currentResourceContext.parentResourcesRequirements,\n    }).then((row) => {\n      if (cancelled) return;\n      setBootstrappedRow({\n        contextKey: bootstrapContextKey,\n        row,\n      });\n    }).catch((error: unknown) => {\n      if (cancelled) return;\n      handleError(error instanceof Error ? error : new Error(String(error)));\n    }).finally(() => {\n      if (!cancelled) {\n        setIsBootstrapping(false);\n      }\n    });\n\n    return () => {\n      cancelled = true;\n    };\n  }, [\n    bootstrapContextKey,\n    canonicalReadOperationPathKey,\n    contextualParameters,\n    currentResourceContext.parentResourcesRequirements,\n    currentResourceId,\n    handleError,\n    isSingleRowUpdateLike,\n  ]);\n\n  useEffect(() => {\n    if (!rmm || !bootstrappedRow || bootstrappedRow.contextKey !== bootstrapContextKey) {\n      return;\n    }\n\n    if (typeof rmm.getSnapshot === 'function' && rmm.getSnapshot().confirmedData !== null) {\n      return;\n    }\n\n    if (typeof rmm.setInitialState === 'function') {\n      const row = bootstrappedRow.row;\n      rmm.setInitialState(\n        row,\n        (row._version as number | undefined) ?? 0,\n        row._field_meta as Record<string, FieldMetaEntry> | undefined,\n      );\n    }\n  }, [bootstrapContextKey, bootstrappedRow, rmm]);\n\n  const execute = useCallback(async (requestData?: Record<string, unknown>) => {\n    setIsExecuting(true);\n    try {\n      let result: unknown;\n\n      if (isSingleRowUpdateLike && (rmm || !acceptsDirectLane)) {\n        if (!rmm) {\n          throw new MissingRMMRuntimeError({\n            surfaceName: 'useOperationDirectExecution',\n            resourceType,\n            operationIdentifier: String(operation.operationIdentifier),\n          });\n        }\n\n        // No optimistic patch: the body is the OPERATION's input, not a set of resource fields, and a\n        // custom operation's input names need not be the row's. The row is read back on success.\n        const mutationResult = await rmm.queueMutation({}, {\n          type: MutationType.CUSTOM,\n          priority: MutationPriority.HIGH,\n          source: {\n            type: MutationSourceType.CUSTOM,\n            subscriberId: `direct-execution:${String(operation.operationIdentifier)}`,\n          },\n          transportOverride: {\n            operationPathKey: ResourcesConfig_OperationPathUtils.createOperationPathKeyFromOperation(operation),\n            contextualParameters,\n            parentResourcesRequirements: currentResourceContext.parentResourcesRequirements,\n            requestData: requestData ?? {},\n            readBackOnSuccess: true,\n          },\n        });\n\n        if (!mutationResult.success) {\n          throw mutationErrorForReport(mutationResult.error, executionFailedLabel);\n        }\n\n        result = mutationResult.responseData;\n      } else if (isSingleRowUpdateLike) {\n        /*\n         * No RMM and the direct lane declared, still for ONE row: sent with the parameters this hook resolved, which carry the\n         * bootstrapped id when the route had none. `executeCurrentOperation` builds its parameters from the\n         * route alone, so from a detail-less context (a singleton, a bulk bar) it would address `{id}`\n         * unresolved. With no id at all the operation has no row to act on, and says so instead of sending.\n         */\n        if (!currentResourceId) {\n          throw new Error(`${String(operation.operationIdentifier)} on ${resourceType} has no row to act on: no id on the route and none from its canonical READ.`);\n        }\n        result = await doOperationRef.current(ResourcesConfig_OperationPathUtils.createOperationPathKeyFromOperation(operation), {\n          contextualParameters,\n          parentResourcesRequirements: currentResourceContext.parentResourcesRequirements,\n          requestData: requestData ?? {},\n        });\n      } else {\n        result = await executeCurrentOperation(requestData);\n      }\n\n      handleSuccess(result);\n    } catch (error) {\n      handleError(error instanceof Error ? error : new Error(executionFailedLabel));\n    } finally {\n      setIsExecuting(false);\n    }\n  }, [\n    contextualParameters,\n    currentResourceContext.parentResourcesRequirements,\n    executeCurrentOperation,\n    handleError,\n    handleSuccess,\n    acceptsDirectLane,\n    isSingleRowUpdateLike,\n    currentResourceId,\n    operation,\n    resourceType,\n    rmm,\n    executionFailedLabel,\n  ]);\n\n  return {\n    execute,\n    isExecuting,\n    isBootstrapping,\n    completeWithSuccess: handleSuccess,\n    reportFailure: handleError,\n  };\n}\n"]}

package/dist/esm/core/resources/useOperationEnabled.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOperationEnabled.d.ts","sourceRoot":"","sources":["../../../../src/core/resources/useOperationEnabled.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"useOperationEnabled.d.ts","sourceRoot":"","sources":["../../../../../src/core/resources/useOperationEnabled.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,6BAA6B,CAAC"}

package/dist/esm/core/resources/useOperationEnabled.js.map

@@ -1 +1 @@
-{"version":3,"file":"useOperationEnabled.js","sourceRoot":"","sources":["../../../../src/core/resources/useOperationEnabled.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,mBAAmB,EACnB,oBAAoB,GAKrB,MAAM,6BAA6B,CAAC","sourcesContent":["/**\n * Re-export from the canonical implementation in hooks/useOperationEnabled.\n * \n * The canonical implementation lives in ./hooks/useOperationEnabled.ts.\n * This file exists as a public re-export point (used by index.ts barrel).\n */\nexport {\n  useOperationEnabled,\n  useOperationsEnabled,\n  type UseOperationEnabledParams,\n  type UseOperationEnabledResult,\n  type OperationEnabledEntry,\n  type FeatureAvailability,\n} from './hooks/useOperationEnabled';\n"]}
+{"version":3,"file":"useOperationEnabled.js","sourceRoot":"","sources":["../../../../../src/core/resources/useOperationEnabled.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,mBAAmB,EACnB,oBAAoB,GAKrB,MAAM,6BAA6B,CAAC","sourcesContent":["/**\n * Re-export from the canonical implementation in hooks/useOperationEnabled.\n * \n * The canonical implementation lives in ./hooks/useOperationEnabled.ts.\n * This file exists as a public re-export point (used by index.ts barrel).\n */\nexport {\n  useOperationEnabled,\n  useOperationsEnabled,\n  type UseOperationEnabledParams,\n  type UseOperationEnabledResult,\n  type OperationEnabledEntry,\n  type FeatureAvailability,\n} from './hooks/useOperationEnabled';\n"]}

package/dist/esm/core/resources/useResourceLabels.d.ts

@@ -1,13 +1,13 @@
 /**
  * useResourceLabels — Shared hook for resolving field labels, descriptions,
- * enum labels, and section labels from i18n with fallback to camelCase formatting.
+ * enum labels, and section labels from i18n. An unresolved label renders as its raw key (#420).
  *
  * Used by both AutomaticDisplayer (display mode) and AutomatedForm (edit mode).
  *
  * Resolution chain for labels:
  * 1. Explicit override from labels prop wins
  * 2. i18n resolution via tResourceFieldDisplay/tResourceFieldEdit
- *    (fallback is handled internally by I18nContext — consumers always get a usable string)
+ *    (fallback is handled internally by I18nContext — an unresolved label is the key itself, never invented words)
  *
  * Resolution chain for descriptions:
  * 1. Explicit override from labels prop wins
@@ -20,7 +20,7 @@
  *
  * Supports parameterized labels via {{param}} interpolation using current object data.
  */
-import { z } from 'zod';
+import type { z } from 'zod';
 import type { DisplayOrFormSectionLabel } from '@wildo-ai/presets-components-models';
 import type { LayoutRefManifest } from '../../core/resources/resources.frontend.schemas';
 export interface ResourceLabelContext {
@@ -33,6 +33,24 @@ export interface UseResourceLabelsOptions {
      * section names and wizard step names for i18n resolution.
      */
     layoutRefs?: LayoutRefManifest;
+    /**
+     * Resolve this schema's labels as if its fields sat at `<fieldPathPrefix>.<path>` in the resource.
+     *
+     * For a surface rendering the ITEM SHAPE of a collection that lives somewhere else in the owning
+     * resource. The resolved map stays keyed by the LOCAL path the surface renders (`objective`), while
+     * the i18n lookup uses the owning path (`tasks.objective`) — so one authoring serves both surfaces
+     * and neither can drift from the other.
+     *
+     * Added for the workbench's aspect popup (#638), which renders one entry of a family document as
+     * its own root. Every field in it read as its raw schema key — `objective`, `skillRefs`,
+     * `target.moduleRef` — beside a document one click away that labels the same fields correctly,
+     * because the document authors them under `tasks.` and the popup asked for them bare.
+     *
+     * Deliberately NOT a second place to author words: it changes which key is asked for, never what
+     * happens when the key is missing. An unauthored field still renders as its key, on both surfaces,
+     * which is what `display-text-comes-from-i18n.md` asks for.
+     */
+    fieldPathPrefix?: string;
     /** Explicit i18n-key overrides — these take priority over ref-derived defaults */
     overrides?: {
         fields?: Record<string, string>;
@@ -60,10 +78,10 @@ export interface UseResourceLabelsResult {
     groupLabels: Record<string, string>;
     /**
      * Whether the underlying resource-label i18n bundle has finished loading.
-     * The maps above always return usable strings (formatted field-name fallbacks)
-     * even while `false`, so this is NOT required for correctness — it lets callers
-     * hold a skeleton until the *real* labels land instead of flashing the
-     * humanized field-name fallback, then swapping (see `AutomatedForm`).
+     * The maps above always return a string (the raw key when unresolved) even while
+     * `false`, so this is NOT required for correctness — it lets callers hold a
+     * skeleton until the *real* labels land instead of flashing raw keys, then
+     * swapping (see `AutomatedForm`).
      */
     isReady: boolean;
 }
@@ -72,8 +90,8 @@ export interface UseResourceLabelsResult {
  * from i18n. Works for both display and edit modes.
  *
  * Fallback logic is handled by I18nContext functions themselves —
- * they never return raw keys, always a usable string (formatted field name,
- * raw enum value, or empty string).
+ * an unresolved field label is its raw key (leaf-shortened for nested paths),
+ * an unresolved enum value is the raw value, and an unresolved description is empty.
  *
  * @param schema - The Zod schema for the resource (used to extract field names and enum values)
  * @param resourceContext - Resource type and operation ID for i18n key construction

package/dist/esm/core/resources/useResourceLabels.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useResourceLabels.d.ts","sourceRoot":"","sources":["../../../../src/core/resources/useResourceLabels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+DAA+D,CAAC;AASvG,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,kFAAkF;IAClF,SAAS,CAAC,EAAE;QACV,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,oDAAoD;QACpD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;QACrD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;KACzD,CAAC;CACH;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;kGAC8F;IAC9F,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C;sGACkG;IAClG,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,+GAA+G;IAC/G,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;;;;OAMG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AA2JD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,CAAC,CAAC,UAAU,EACpB,eAAe,CAAC,EAAE,oBAAoB,EACtC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,GAAE,SAAS,GAAG,MAAkB,EACpC,OAAO,GAAE,wBAA6B,GACrC,uBAAuB,CAkUzB"}
+{"version":3,"file":"useResourceLabels.d.ts","sourceRoot":"","sources":["../../../../../src/core/resources/useResourceLabels.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+DAA+D,CAAC;AAcvG,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kFAAkF;IAClF,SAAS,CAAC,EAAE;QACV,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,oDAAoD;QACpD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACtC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;QACrD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC;KACzD,CAAC;CACH;AAED,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;kGAC8F;IAC9F,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C;sGACkG;IAClG,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,+GAA+G;IAC/G,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;;;;OAMG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAqDD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,CAAC,CAAC,UAAU,EACpB,eAAe,CAAC,EAAE,oBAAoB,EACtC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,IAAI,GAAE,SAAS,GAAG,MAAkB,EACpC,OAAO,GAAE,wBAA6B,GACrC,uBAAuB,CAiUzB"}

package/dist/esm/core/resources/useResourceLabels.js

@@ -1,13 +1,13 @@
 /**
  * useResourceLabels — Shared hook for resolving field labels, descriptions,
- * enum labels, and section labels from i18n with fallback to camelCase formatting.
+ * enum labels, and section labels from i18n. An unresolved label renders as its raw key (#420).
  *
  * Used by both AutomaticDisplayer (display mode) and AutomatedForm (edit mode).
  *
  * Resolution chain for labels:
  * 1. Explicit override from labels prop wins
  * 2. i18n resolution via tResourceFieldDisplay/tResourceFieldEdit
- *    (fallback is handled internally by I18nContext — consumers always get a usable string)
+ *    (fallback is handled internally by I18nContext — an unresolved label is the key itself, never invented words)
  *
  * Resolution chain for descriptions:
  * 1. Explicit override from labels prop wins
@@ -20,11 +20,11 @@
  *
  * Supports parameterized labels via {{param}} interpolation using current object data.
  */
-import { useMemo } from 'react';
-import { z } from 'zod';
-import { FieldSchemaType, getArrayItemSchema, getEnumValues, getSchemaType, getFieldUIDisplayConfig, getFieldUIEditConfig, getZodObjectShape, unwrapSchema } from '@wildo-ai/zod-decorators';
+import { useCallback, useMemo } from 'react';
+import { getEnumValues, getFieldUIDisplayConfig, getFieldUIEditConfig } from '@wildo-ai/zod-decorators';
 import { useI18n } from '../../core/i18n/useI18n.js';
 import { AutomatedLayoutFrontendUtils } from '../../core/automated-layout/automated-layout.frontend.utils.js';
+import { collectResourceLabelFieldEntries, resolveResourceLabelEnumSchema, } from '../../core/resources/resource-label-field-paths.frontend.utils.js';
 // =============================================================================
 // HELPERS
 // =============================================================================
@@ -46,93 +46,6 @@ function dataToParams(data) {
     }
     return Object.keys(params).length > 0 ? params : undefined;
 }
-/** Max object-nesting depth walked when collecting label/enum entries (guards against
- *  pathological / self-referential schemas while covering real nested settings objects
- *  like `privacy.dataProcessingConsent` and `regional.dateFormat`). */
-const MAX_NESTED_FIELD_DEPTH = 4;
-/**
- * Flatten a resource schema into every label-bearing field path, recursing into nested
- * OBJECT fields so that fields rendered inside an `<ObjectScope name="privacy">` (which look
- * their labels/enum-labels up by the dotted `privacy.dataProcessingConsent` key) resolve the
- * same way top-level fields do. Without this, nested object fields fell back to no label /
- * raw enum values. Arrays are recorded as leaves (their element enum, if any, is handled by
- * the enum-labels pass) but not descended into — per-index paths are dynamic.
- */
-function collectFieldEntries(schema, prefix, depth, acc) {
-    let shape;
-    try {
-        // Resolve the field shape the SAME way the form/display RENDER path does
-        // (`extractSchemaFieldList` / `formFieldShape` → `getObjectLikeFieldShape`).
-        // Polymorphic resources (e.g. todos) feed the form a `z.discriminatedUnion`
-        // request DTO; the object-only `getObjectShape` returns `null` for a union, so
-        // labels silently fell back to raw camelCase while the renderer happily showed
-        // every field (functional-but-unlabelled). `getObjectLikeFieldShape` treats a
-        // discriminated-union-of-objects as a single object-like field set; `commonOnly:
-        // false` MERGES keys across every variant so variant-only fields (rendered under
-        // a `<DiscriminatorSwitch>`, e.g. `recurrence`/`startDate`) also resolve labels.
-        shape = AutomatedLayoutFrontendUtils.getObjectLikeFieldShape(schema, { commonOnly: false });
-    }
-    catch {
-        return;
-    }
-    if (!shape)
-        return;
-    /*
-     * A DISCRIMINATED UNION's discriminator must collect its values across EVERY variant.
-     *
-     * The merged shape above keeps the FIRST variant's schema per key, which is right for the
-     * variant-only fields (each has one owner) and silently wrong for the one key every variant
-     * declares: the discriminator, a per-variant `z.literal`. Collected as the first variant's
-     * literal, its label map knew exactly one value — measured on the workbench build plan, where
-     * `target.kind` is a five-variant union: the authored `enum` labels served fine for `MODULE`
-     * and every other task printed the raw wire constant (`RESOURCE_STAGE`, fifty-odd times down
-     * the page), while its SIBLING `stage` resolved perfectly because only one variant declares it.
-     *
-     * So: where several variants declare the same key as distinct string literals, the collected
-     * schema becomes their union as a `z.enum`, and `getEnumValues` below sees the full vocabulary.
-     * The render path needs no change — it resolves the ACTUAL variant and looks its value up in
-     * this map.
-     */
-    const unionOptions = AutomatedLayoutFrontendUtils.getDiscriminatedUnionObjectOptions(unwrapSchema(schema));
-    const discriminatorEnums = {};
-    if (unionOptions.length > 1) {
-        const literalValuesByKey = {};
-        for (const option of unionOptions) {
-            for (const [name, fieldSchema] of Object.entries(getZodObjectShape(option))) {
-                const values = getEnumValues(fieldSchema);
-                if (values.length !== 1)
-                    continue;
-                (literalValuesByKey[name] ??= []).push(values[0]);
-            }
-        }
-        for (const [name, values] of Object.entries(literalValuesByKey)) {
-            if (values.length > 1)
-                discriminatorEnums[name] = z.enum(values);
-        }
-    }
-    for (const [name, fieldSchema] of Object.entries(shape)) {
-        const path = prefix ? `${prefix}.${name}` : name;
-        acc.push({ path, leaf: name, schema: discriminatorEnums[name] ?? fieldSchema });
-        if (depth < MAX_NESTED_FIELD_DEPTH && getSchemaType(fieldSchema) === FieldSchemaType.OBJECT) {
-            collectFieldEntries(fieldSchema, path, depth + 1, acc);
-        }
-        /*
-         * Descend into ARRAY-OF-OBJECT items too, under the item's INDEX-FREE path
-         * (`successCriteria.horizon`, never `successCriteria[0].horizon`): every item of one array
-         * shares one schema, so labels are per-FIELD, not per-row. Without this, a labelled enum
-         * inside an entry collection — a criterion's `horizon`, a constraint's `kind` — had no entry
-         * in `enumLabels`/`fieldLabels` at all and rendered its raw wire value, while the identical
-         * enum ONE level up resolved fine. The render path strips indices before its lookup
-         * (`DisplayField`), so the two sides meet on the same key.
-         */
-        if (depth < MAX_NESTED_FIELD_DEPTH && getSchemaType(fieldSchema) === FieldSchemaType.ARRAY) {
-            const itemSchema = getArrayItemSchema(fieldSchema);
-            if (itemSchema && getSchemaType(itemSchema) === FieldSchemaType.OBJECT) {
-                collectFieldEntries(itemSchema, path, depth + 1, acc);
-            }
-        }
-    }
-}
 /**
  * Resolve a single field label, substituting the LEAF segment when i18n resolved nothing.
  *
@@ -161,8 +74,8 @@ function resolveFieldLabel(path, leaf, resolved) {
  * from i18n. Works for both display and edit modes.
  *
  * Fallback logic is handled by I18nContext functions themselves —
- * they never return raw keys, always a usable string (formatted field name,
- * raw enum value, or empty string).
+ * an unresolved field label is its raw key (leaf-shortened for nested paths),
+ * an unresolved enum value is the raw value, and an unresolved description is empty.
  *
  * @param schema - The Zod schema for the resource (used to extract field names and enum values)
  * @param resourceContext - Resource type and operation ID for i18n key construction
@@ -174,7 +87,14 @@ export function useResourceLabels(schema, resourceContext, data, mode = 'display
     const { t, tResourceFieldDisplay, tResourceFieldEdit, tResourceFieldEnumValue, tResourceSection, tResourceWizardStep, isReady } = useI18n({
         resource: resourceContext?.resourceType,
     });
-    const { layoutRefs, overrides } = options;
+    const { layoutRefs, overrides, fieldPathPrefix } = options;
+    /**
+     * The i18n key a local path is looked up under — prefixed when this surface renders a nested item
+     * shape, identical otherwise. One helper so the field, description, tooltip and ENUM resolutions
+     * cannot disagree about it: an enum whose values resolved bare while its label resolved prefixed
+     * would show an authored heading over raw wire constants, which reads worse than either alone.
+     */
+    const resolveI18nPath = useCallback((path) => (fieldPathPrefix ? `${fieldPathPrefix}.${path}` : path), [fieldPathPrefix]);
     // -------------------------------------------------------------------------
     // FIELD LABELS
     // -------------------------------------------------------------------------
@@ -183,9 +103,9 @@ export function useResourceLabels(schema, resourceContext, data, mode = 'display
         const params = dataToParams(data);
         // Collect top-level AND nested (ObjectScope) field paths so a field rendered inside
         // `<ObjectScope name="privacy">` resolves its label by the dotted `privacy.x` key.
-        const entries = [];
+        let entries;
         try {
-            collectFieldEntries(schema, '', 0, entries);
+            entries = collectResourceLabelFieldEntries(schema);
         }
         catch {
             // Schema might not be an object (e.g., during loading)
@@ -200,17 +120,18 @@ export function useResourceLabels(schema, resourceContext, data, mode = 'display
                 continue;
             }
             // 2. i18n resolution (fallback handled internally; leaf-substituted for nested paths)
+            const i18nPath = resolveI18nPath(path);
             if (resourceContext) {
                 const tFn = mode === 'edit' ? tResourceFieldEdit : tResourceFieldDisplay;
-                result[path] = resolveFieldLabel(path, leaf, tFn(resourceContext.resourceType, path, 'label', params));
+                result[path] = resolveFieldLabel(i18nPath, leaf, tFn(resourceContext.resourceType, i18nPath, 'label', params));
             }
             else {
-                // No resource context — use the i18n function which will fallback to formatted name
-                result[path] = resolveFieldLabel(path, leaf, tResourceFieldDisplay('', path, 'label', params));
+                // No resource context — the i18n function still answers, with the raw key when unresolved
+                result[path] = resolveFieldLabel(i18nPath, leaf, tResourceFieldDisplay('', i18nPath, 'label', params));
             }
         }
         return result;
-    }, [schema, resourceContext, data, mode, overrides?.fields, tResourceFieldDisplay, tResourceFieldEdit]);
+    }, [schema, resourceContext, data, mode, overrides?.fields, resolveI18nPath, tResourceFieldDisplay, tResourceFieldEdit]);
     // -------------------------------------------------------------------------
     // FIELD DESCRIPTIONS
     // -------------------------------------------------------------------------
@@ -222,9 +143,9 @@ export function useResourceLabels(schema, resourceContext, data, mode = 'display
         const params = dataToParams(data);
         // Collect top-level AND nested field paths (mirrors fieldLabels) so ObjectScope-nested
         // fields can resolve descriptions by their dotted path.
-        const entries = [];
+        let entries;
         try {
-            collectFieldEntries(schema, '', 0, entries);
+            entries = collectResourceLabelFieldEntries(schema);
         }
         catch {
             return overrides?.descriptions ?? {};
@@ -238,14 +159,14 @@ export function useResourceLabels(schema, resourceContext, data, mode = 'display
             // 2. i18n resolution (only source for descriptions — Zod .describe() is NOT used for UI)
             if (resourceContext) {
                 const tFn = mode === 'edit' ? tResourceFieldEdit : tResourceFieldDisplay;
-                const resolved = tFn(resourceContext.resourceType, path, 'description', params);
+                const resolved = tFn(resourceContext.resourceType, resolveI18nPath(path), 'description', params);
                 if (resolved) {
                     result[path] = resolved;
                 }
             }
         }
         return result;
-    }, [schema, resourceContext, data, mode, overrides?.descriptions, tResourceFieldDisplay, tResourceFieldEdit]);
+    }, [schema, resourceContext, data, mode, overrides?.descriptions, resolveI18nPath, tResourceFieldDisplay, tResourceFieldEdit]);
     // -------------------------------------------------------------------------
     // FIELD TOOLTIPS
     // -------------------------------------------------------------------------
@@ -254,7 +175,7 @@ export function useResourceLabels(schema, resourceContext, data, mode = 'display
         const result = {};
         let shape;
         try {
-            // Mirror `collectFieldEntries`: object-LIKE resolution so a discriminated-union
+            // Mirror `collectResourceLabelFieldEntries`: object-LIKE resolution so a discriminated-union
             // request DTO (polymorphic resource) yields its merged field shape instead of
             // `undefined`, and tooltips resolve for variant-only fields too.
             shape = AutomatedLayoutFrontendUtils.getObjectLikeFieldShape(schema, { commonOnly: false });
@@ -277,24 +198,24 @@ export function useResourceLabels(schema, resourceContext, data, mode = 'display
                 continue;
             if (resourceContext) {
                 const tFn = mode === 'edit' ? tResourceFieldEdit : tResourceFieldDisplay;
-                const resolved = tFn(resourceContext.resourceType, fieldName, 'tooltip');
+                const resolved = tFn(resourceContext.resourceType, resolveI18nPath(fieldName), 'tooltip');
                 if (resolved) {
                     result[fieldName] = resolved;
                 }
             }
         }
         return result;
-    }, [schema, resourceContext, mode, tResourceFieldDisplay, tResourceFieldEdit]);
+    }, [schema, resourceContext, mode, resolveI18nPath, tResourceFieldDisplay, tResourceFieldEdit]);
     // -------------------------------------------------------------------------
     // ENUM LABELS
     // -------------------------------------------------------------------------
     const enumLabels = useMemo(() => {
         const result = {};
         // Collect top-level AND nested field paths (mirrors fieldLabels) so nested enum fields
-        // (`ui.theme`, `regional.dateFormat`, `privacy.dataProcessingConsent`) get enum labels.
-        const entries = [];
+        // (`ui.theme`, `regional.dateFormat`, `privacy.consentedPurposes`) get enum labels.
+        let entries;
         try {
-            collectFieldEntries(schema, '', 0, entries);
+            entries = collectResourceLabelFieldEntries(schema);
         }
         catch {
             return overrides?.enums ?? {};
@@ -304,17 +225,7 @@ export function useResourceLabels(schema, resourceContext, data, mode = 'display
             // (e.g. `roles: z.array(z.union([z.enum(CORE_ORG_ROLES), z.string()]))`, whose union
             // element still yields enum values via getEnumValues). Without the array branch,
             // array-of-enum fields rendered their members raw (e.g. `ORG_ADMIN`).
-            const schemaType = getSchemaType(fieldSchema);
-            let enumSchema;
-            if (schemaType === FieldSchemaType.ENUM) {
-                enumSchema = fieldSchema;
-            }
-            else if (schemaType === FieldSchemaType.ARRAY) {
-                const itemSchema = getArrayItemSchema(fieldSchema);
-                if (itemSchema && getSchemaType(itemSchema) === FieldSchemaType.ENUM) {
-                    enumSchema = itemSchema;
-                }
-            }
+            const enumSchema = resolveResourceLabelEnumSchema(fieldSchema);
             if (!enumSchema)
                 continue;
             // 1. Explicit override wins
@@ -322,20 +233,22 @@ export function useResourceLabels(schema, resourceContext, data, mode = 'display
                 result[path] = overrides.enums[path];
                 continue;
             }
-            // 2. i18n resolution (tResourceFieldEnumValue auto-cascades to system enum labels)
+            // 2. i18n resolution — the per-field word, else the words of the enum THIS field declares (read off
+            //    `fieldSchema`, which for a union discriminator is the collected enum carrying its variants'
+            //    declared vocabulary), else the raw value (#966)
             if (resourceContext) {
                 const values = getEnumValues(enumSchema);
                 if (values.length > 0) {
                     const enumMap = {};
                     for (const value of values) {
-                        enumMap[value] = tResourceFieldEnumValue(resourceContext.resourceType, path, value);
+                        enumMap[value] = tResourceFieldEnumValue(resourceContext.resourceType, resolveI18nPath(path), value, fieldSchema);
                     }
                     result[path] = enumMap;
                 }
             }
         }
         return result;
-    }, [schema, resourceContext, overrides?.enums, tResourceFieldEnumValue]);
+    }, [schema, resourceContext, overrides?.enums, resolveI18nPath, tResourceFieldEnumValue]);
     // -------------------------------------------------------------------------
     // SECTION LABELS
     // -------------------------------------------------------------------------
@@ -362,15 +275,11 @@ export function useResourceLabels(schema, resourceContext, data, mode = 'display
             const { resourceType } = resourceContext;
             for (const ref of layoutRefs.sections) {
                 if (!labels[ref]) {
-                    const resolvedLabel = tResourceSection(resourceType, ref, 'title');
-                    // Fall back to the section REF when no i18n title has been generated yet — the same
-                    // unresolved rendering field labels use, and for the same reason: it is visibly a key,
-                    // so it gets authored. Without any fallback a section renders TITLE-LESS (an invisible
-                    // group), so a multi-section settings page reads as one undifferentiated list — the
-                    // headings simply never appear, which is a worse failure than a visible raw ref. A real
-                    // generated or authored title still wins; this only keeps a declared section a visible,
-                    // named group.
-                    labels[ref] = resolvedLabel || AutomatedLayoutFrontendUtils.unresolvedFieldLabel(ref);
+                    // A section with no generated title shows `resources.<type>.sections.<ref>.title` — the
+                    // resolver's own answer for a missing primary label (#1450). It used to answer '' and this
+                    // site patched the gap with the bare ref; a TITLE-LESS section is an invisible group, so a
+                    // multi-section settings page read as one undifferentiated list.
+                    labels[ref] = tResourceSection(resourceType, ref, 'title');
                 }
                 if (!descriptions[ref]) {
                     // Descriptions are prose — there is no sensible humanized fallback, so an
@@ -413,10 +322,8 @@ export function useResourceLabels(schema, resourceContext, data, mode = 'display
             const { resourceType } = resourceContext;
             for (const ref of layoutRefs.wizardSteps) {
                 if (!labels[ref]) {
-                    const resolvedLabel = tResourceWizardStep(resourceType, ref, 'title');
-                    if (resolvedLabel) {
-                        labels[ref] = resolvedLabel;
-                    }
+                    // Never empty: an ungenerated step title is its key path (#1450), so a step is never unnamed.
+                    labels[ref] = tResourceWizardStep(resourceType, ref, 'title');
                 }
                 if (!descriptions[ref]) {
                     const resolvedDescription = tResourceWizardStep(resourceType, ref, 'description');