@khester/create-dynamics-app 3.2.0 → 3.4.0

package/templates/grid-customizer/dev/harness/MockGrid.tsx

@@ -1,9 +1,12 @@
 import * as React from 'react';
 import type {
+  CellEditorOverrides,
+  CellEditorProps,
   CellRendererOverrides,
   CellRendererProps,
   ColumnDataType,
   ColumnDefinition,
+  GetEditorParams,
   GetRendererParams,
 } from '../../{{componentName}}/types';
 
@@ -20,8 +23,23 @@ import type {
  *
  * If a renderer works here and not in the org, the difference is the platform (versions,
  * bindings, publish state) — not the contract. It deliberately does NOT reimplement sorting,
- * filtering, selection, paging or inline editing: the real grid owns all of those, and a
- * fake one that drifted from them would be worse than none.
+ * filtering, selection or paging: the real grid owns all of those, and a fake one that drifted
+ * from them would be worse than none.
+ *
+ * ★ It DOES reimplement just enough inline editing to invoke `cellEditorOverrides`, because
+ * without it that half of the contract had never been executed anywhere — the map shipped
+ * empty, the only example lived in a docblock, and "it typechecks" was the whole of its
+ * coverage. Edit mode dispatches editors by the same rules as renderers:
+ *   - keyed by `ColumnDataType`, never by column name;
+ *   - `(CellEditorProps, GetEditorParams)`, with `colDefs` + `columnIndex` for narrowing;
+ *   - `undefined` means "use the platform's own editor", NOT "render nothing".
+ * ⚠️ The double-click GESTURE is the harness's own invention — the platform also has a
+ * type-to-edit path that seeds `charPress`, which this never populates.
+ *
+ * ⚠️ What it CANNOT tell you: whether the real grid commits the value the way this does. The
+ * platform owns commit (`onChange` vs `onCellValueChanged` vs `stopEditing`) and none of that
+ * is observable here. Edit mode proves the map is reached, keyed and narrowed correctly; it
+ * does not prove a write lands in Dataverse.
  */
 
 /** One column of the fake grid: the platform's `ColumnDefinition` plus a display width. */
@@ -30,6 +48,8 @@ export interface HarnessColumn {
   displayName: string;
   dataType: ColumnDataType;
   width?: number;
+  /** Per-column editability. The platform sets this from metadata/security, not per grid. */
+  editable?: boolean;
 }
 
 /** One cell: the raw value the platform would pass, and the text it would have painted. */
@@ -47,6 +67,18 @@ export interface MockGridProps {
   overrides: CellRendererOverrides;
   /** Row height in px — the real grid gives cells a fixed height, so mirror that. */
   rowHeight?: number;
+  /** Editor map to dispatch when a cell is being edited. Omit for a read-only grid. */
+  editorOverrides?: CellEditorOverrides;
+  /** Turn inline editing on. Without it the grid behaves exactly as it always has. */
+  editable?: boolean;
+  /** Commit handler — the harness owns the row data, as the platform owns the record. */
+  onCellCommit?: (rowIndex: number, columnName: string, next: unknown) => void;
+}
+
+/** Which cell is open for editing. */
+interface EditTarget {
+  rowIndex: number;
+  columnIndex: number;
 }
 
 const ROW_HEIGHT = 42;
@@ -68,7 +100,26 @@ export const MockGrid: React.FC<MockGridProps> = ({
   rows,
   overrides,
   rowHeight = ROW_HEIGHT,
+  editorOverrides,
+  editable = false,
+  onCellCommit,
 }) => {
+  const [editing, setEditing] = React.useState<EditTarget | null>(null);
+  // Leaving edit mode must also close any open editor, or the cell stays stuck in an editor
+  // the grid no longer considers editable.
+  React.useEffect(() => {
+    if (!editable) setEditing(null);
+  }, [editable]);
+  // ★ `editing` is a pair of INDICES. If the recordset is swapped underneath it (Mock↔Live, a
+  // reload, a different $select) the same indices address a different record and a commit would
+  // write into it. Close the editor whenever that happens.
+  //
+  // Keyed on `columns`, NOT `rows`: the harness replaces the columns array on every dataset
+  // change, while a COMMIT replaces the rows array too — so depending on `rows` would close the
+  // editor after every single edit, which is a worse bug than the one being fixed.
+  React.useEffect(() => {
+    setEditing(null);
+  }, [columns]);
   // Built once per render and shared by every cell, exactly as the grid does — a handler
   // that inspects sibling columns sees the same array the platform would give it.
   const colDefs: ColumnDefinition[] = columns.map((c, i) => ({
@@ -110,12 +161,15 @@ export const MockGrid: React.FC<MockGridProps> = ({
               {columns.map((col, columnIndex) => {
                 const cell = row[col.name] ?? { raw: undefined, formatted: '' };
 
+                const isEditing =
+                  editing?.rowIndex === rowIndex && editing?.columnIndex === columnIndex;
+
                 const props: CellRendererProps = {
                   value: cell.raw,
                   formattedValue: cell.formatted,
                   columnDataType: col.dataType,
                   rowHeight,
-                  columnEditable: false,
+                  columnEditable: editable && (col.editable ?? true),
                   isRightAligned:
                     col.dataType === 'Currency' ||
                     col.dataType === 'Decimal' ||
@@ -135,9 +189,82 @@ export const MockGrid: React.FC<MockGridProps> = ({
                 const handler = overrides[col.dataType];
                 const custom = handler ? handler(props, params) : undefined;
 
+                let content: React.ReactNode;
+                if (isEditing) {
+                  const stopEditing = (): void => setEditing(null);
+                  const commit = (next: unknown): void => {
+                    onCellCommit?.(rowIndex, col.name, next);
+                  };
+                  const editorProps: CellEditorProps = {
+                    value: cell.raw,
+                    rowHeight,
+                    columnDataType: col.dataType,
+                    isRequired: false,
+                    charPress: null,
+                    // The documented commit path. The harness treats it as authoritative and
+                    // writes straight through to the row data.
+                    onChange: commit,
+                  };
+                  const editorParams: GetEditorParams = {
+                    colDefs,
+                    columnIndex,
+                    // Part of the contract. Wired so a handler that calls it is not a crash,
+                    // but the harness commits on onChange — see the file header.
+                    onCellValueChanged: commit,
+                    rowData: { __rec_id: String(rowIndex) },
+                    stopEditing,
+                  };
+                  const editorHandler = editorOverrides?.[col.dataType];
+                  const customEditor = editorHandler
+                    ? editorHandler(editorProps, editorParams)
+                    : undefined;
+
+                  content = (
+                    // ★ Guarded blur. Un-guarded, React's bubbling onBlur tears the editor down
+                    // on ANY internal focus move — and Fluent's SpinButton blurs its input when
+                    // you mousedown an arrow, so a single click would apply one step and close.
+                    <div
+                      onBlur={(e) => {
+                        if (!e.currentTarget.contains(e.relatedTarget as Node | null)) stopEditing();
+                      }}
+                      ref={(el) => {
+                        // Focus the custom editor on open; only the fallback input self-focuses.
+                        if (el && !el.contains(document.activeElement)) {
+                          el.querySelector<HTMLElement>('input, [tabindex]')?.focus();
+                        }
+                      }}
+                    >
+                      {/* ★ undefined => the PLATFORM's editor, not an empty cell. The stand-in
+                          for that is a plain input, which is what the grid falls back to. */}
+                      {customEditor ?? (
+                        <input
+                          autoFocus
+                          defaultValue={cell.formatted}
+                          // ★ Commits on BLUR as well as Enter. The real grid commits its
+                          // built-in editors on blur, and this input stands in for those — if it
+                          // discarded on blur it would model the platform backwards on the one
+                          // gesture a user makes constantly.
+                          onBlur={(e) => commit(e.target.value)}
+                          onKeyDown={(e) => {
+                            if (e.key === 'Enter') commit((e.target as HTMLInputElement).value);
+                            if (e.key === 'Escape') stopEditing();
+                            if (e.key === 'Enter') stopEditing();
+                          }}
+                          style={{ width: '100%', font: 'inherit', boxSizing: 'border-box' }}
+                        />
+                      )}
+                    </div>
+                  );
+                } else {
+                  // ★ null/undefined => the grid's own rendering, not an empty cell.
+                  content = custom ?? cell.formatted;
+                }
+
                 return (
                   <td
                     key={col.name}
+                    onDoubleClick={editable ? () => setEditing({ rowIndex, columnIndex }) : undefined}
+                    title={editable && !isEditing ? 'Double-click to edit' : undefined}
                     style={{
                       height: rowHeight,
                       padding: '0 8px',
@@ -146,13 +273,13 @@ export const MockGrid: React.FC<MockGridProps> = ({
                       overflow: 'hidden',
                       textOverflow: 'ellipsis',
                       whiteSpace: 'nowrap',
+                      cursor: editable && !isEditing ? 'cell' : undefined,
                       // The real grid right-aligns numerics itself; a custom renderer that
                       // returns undefined must therefore still land in the default layout.
-                      textAlign: props.isRightAligned && !custom ? 'right' : 'left',
+                      textAlign: props.isRightAligned && !custom && !isEditing ? 'right' : 'left',
                     }}
                   >
-                    {/* ★ null/undefined => the grid's own rendering, not an empty cell. */}
-                    {custom ?? cell.formatted}
+                    {content}
                   </td>
                 );
               })}

package/templates/grid-customizer/dev/main.tsx

@@ -10,6 +10,7 @@ import {
   type HarnessField,
 } from '@dataverse-kit/pcf-dev-harness/shell';
 import { createCellRendererOverrides } from '../{{componentName}}/customizers/CellRendererOverrides';
+import { createCellEditorOverrides } from '../{{componentName}}/customizers/CellEditorOverrides';
 import { MockGrid, type HarnessColumn, type HarnessRow } from './harness/MockGrid';
 import { fetchGridData, type HttpError } from './harness/dataverse';
 
@@ -132,23 +133,52 @@ const Harness: React.FC = () => {
     'percentcomplete',
   );
 
+  // Edit mode is persisted like the other knobs so a reload keeps you in the editor path.
+  const [editable, setEditable] = usePersistedState('editable', false);
+
   const [columns, setColumns] = React.useState<HarnessColumn[]>(MOCK_COLUMNS);
   const [rows, setRows] = React.useState<HarnessRow[]>(MOCK_ROWS);
   const [liveStatus, setLiveStatus] = React.useState<React.ReactNode>(null);
 
   // The real override map, rebuilt only when the progress-column list changes. This is the
   // same factory index.ts calls — the harness never forks the renderers.
-  const overrides = React.useMemo(
+  // ★ Parsed ONCE and shared. Two copies of this split/trim/filter could drift, which would
+  // silently retarget the renderers and the editors at different columns.
+  const progressColumnList = React.useMemo(
     () =>
-      createCellRendererOverrides({
-        progressColumns: progressColumns
-          .split(',')
-          .map((s) => s.trim())
-          .filter(Boolean),
-      }),
+      progressColumns
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean),
     [progressColumns],
   );
 
+  const overrides = React.useMemo(
+    () => createCellRendererOverrides({ progressColumns: progressColumnList }),
+    [progressColumnList],
+  );
+
+  // ★ The customizer's REAL editor map, from the same factory index.ts calls and retargeted at
+  // the same columns as the renderers — so the harness never forks the editors either.
+  const editorOverrides = React.useMemo(
+    () => createCellEditorOverrides({ progressColumns: progressColumnList }),
+    [progressColumnList],
+  );
+
+  /** Commit an edited cell back into the harness's row data — the platform owns the record. */
+  const onCellCommit = React.useCallback(
+    (rowIndex: number, columnName: string, next: unknown): void => {
+      setRows((prev) =>
+        prev.map((row, i) =>
+          i === rowIndex
+            ? { ...row, [columnName]: { raw: next, formatted: next === null || next === undefined ? '' : String(next) } }
+            : row,
+        ),
+      );
+    },
+    [],
+  );
+
   // On reload with a restored Live selection: clear and prompt for Load — or fall back to
   // Mock when this session has no org configured. Runs once on mount.
   React.useEffect(() => {
@@ -250,9 +280,25 @@ const Harness: React.FC = () => {
           value: progressColumns,
           onChange: setProgressColumns,
         },
+        {
+          // ★ The only way to reach `cellEditorOverrides` at all. With it off the grid is
+          // read-only and that half of the customizer contract never executes — which is
+          // exactly the state this template shipped in until edit mode existed.
+          kind: 'boolean',
+          label: 'Edit mode (double-click a cell) — exercises cellEditorOverrides',
+          value: editable,
+          onChange: setEditable,
+        },
       ]}
     >
-      <MockGrid columns={columns} rows={rows} overrides={overrides} />
+      <MockGrid
+        columns={columns}
+        rows={rows}
+        overrides={overrides}
+        editorOverrides={editorOverrides}
+        editable={editable}
+        onCellCommit={onCellCommit}
+      />
     </HarnessShell>
   );
 };

package/templates/grid-customizer/{{componentName}}/customizers/CellEditorOverrides.tsx

@@ -1,38 +1,107 @@
-import type { CellEditorOverrides } from '../types';
+import * as React from 'react';
+import { SpinButton } from '@fluentui/react';
+import type { CellEditorOverrides, CellEditorProps, GetEditorParams } from '../types';
+import { PROGRESS_COLUMNS, PROGRESS_MAX, toNumber } from './config';
 
 /**
  * Cell EDITOR overrides — what a cell becomes when the user starts editing it.
  *
- * Empty by default: OneGrid's built-in editors already handle every column type correctly,
- * including the lookup search and option-set pickers that are genuinely hard to reimplement.
- * Override only where the default is wrong for your data.
- *
  * The keys and the fall-through rule are identical to `CellRendererOverrides`: key by
  * `ColumnDataType`, narrow to a column with `editorParams.colDefs[editorParams.columnIndex]`,
  * and return `undefined` to keep the platform editor.
  *
- * A worked example — clamp a percentage column to 0–100:
- *
- * ```tsx
- * import * as React from 'react';
- * import { SpinButton } from '@fluentui/react';
+ * ★ Override editors SPARINGLY. OneGrid's built-ins already handle every column type, including
+ * the lookup search and option-set pickers that are genuinely hard to reimplement — and unlike a
+ * renderer, a wrong editor WRITES BAD DATA rather than merely looking wrong. Only `Decimal` is
+ * registered here, and only for the columns you opt in.
  *
- * export const cellEditorOverrides: CellEditorOverrides = {
- *   Decimal: (defaultProps, editorParams) => {
- *     const name = editorParams.colDefs[editorParams.columnIndex]?.name;
- *     if (name !== 'dvk_percentcomplete') return undefined;
- *     return (
- *       <SpinButton
- *         min={0}
- *         max={100}
- *         step={5}
- *         defaultValue={String(defaultProps.value ?? 0)}
- *         // Commit through onChange; the grid writes the value back to the record.
- *         onChange={(_e, v) => defaultProps.onChange(Number(v ?? 0))}
- *       />
- *     );
- *   },
- * };
- * ```
+ * ⚠️ **Runtime coverage is LOCAL only.** This map is exercised by the dev harness (`npm run dev`
+ * → Edit mode) and by a unit test that invokes it. It has NOT been driven by a real editable
+ * grid in an org: doing that needs a live editable subgrid, and the customizer contract's commit
+ * semantics (`onChange` vs `editorParams.onCellValueChanged` vs `stopEditing`) are therefore
+ * UNVERIFIED here. This file calls `defaultProps.onChange` because it is the only value-carrying
+ * callback on `CellEditorProps` — **not** because Microsoft documents it; their editable-grid
+ * page has no editor sample, and their own reference control returns `null`. If you hit a commit
+ * that does not stick in an org, that is the first thing to re-check — and please record the
+ * answer here.
  */
-export const cellEditorOverrides: CellEditorOverrides = {};
+
+/** Per-instance knobs, mirroring `RendererOptions` so the harness can retarget the same map. */
+export interface EditorOptions {
+  /**
+   * Columns that get the clamped numeric editor. Defaults to `config.PROGRESS_COLUMNS` — the
+   * SAME list that drives the progress-bar renderer, so a column shown as a 0–100 bar is also
+   * edited as one, instead of as a free-text decimal that can be set to 900.
+   */
+  progressColumns?: readonly string[];
+}
+
+/** The column logical name for the cell currently being edited. */
+function columnName(params: GetEditorParams): string | undefined {
+  return params.colDefs[params.columnIndex]?.name;
+}
+
+/** Build the editor map. `cellEditorOverrides` below is the configured singleton. */
+export function createCellEditorOverrides(options: EditorOptions = {}): CellEditorOverrides {
+  const progressColumns = options.progressColumns ?? PROGRESS_COLUMNS;
+
+  return {
+    // ★ Same per-column narrowing as the Decimal RENDERER. `PROGRESS_COLUMNS` is empty by
+    // default, so a scaffold that has not been configured registers this handler and then
+    // falls through on every cell — the editor path is inert until you opt a column in, which
+    // is the conservative default for something that writes.
+    Decimal: (defaultProps: CellEditorProps, editorParams: GetEditorParams) => {
+      const name = columnName(editorParams);
+      if (!name || !progressColumns.includes(name)) return undefined;
+
+      const current = toNumber(defaultProps.value) ?? 0;
+      const clamp = (n: number): number => Math.min(PROGRESS_MAX, Math.max(0, n));
+
+      // ★ Commit through `onChange` ONLY.
+      //
+      // Do not add `onValidate`: Fluent v8's SpinButton calls `onValidate(entered)` and then
+      // feeds the result through `useControllableValue`, which calls `onChange` as well — so a
+      // single committed edit fires this twice (measured: typing 900 then blurring commits
+      // [100, 100]; junk input commits the unchanged value twice). Fluent's built-in validation
+      // already clamps to `min`/`max`, so the clamp below is defence-in-depth, not the mechanism.
+      //
+      // Nor `editorParams.onCellValueChanged` — that is a separate member of the contract and
+      // firing both risks the same double write.
+      //
+      // ⚠️ Why `onChange` and not one of the others: it is the ONLY value-carrying callback on
+      // `CellEditorProps` (see ../types.ts). Microsoft's editable-grid page documents no editor
+      // sample at all — their own PowerAppsGridCustomizerControl ships `return null` — so this
+      // is inference from the type, not a documented guarantee. See the header caveat.
+      // ⚠️ `packages/export-engine`'s PA-grid emitter uses a DIFFERENT convention for the same
+      // undocumented contract (`onChange` followed by `editorParams.stopEditing()`, and empty →
+      // `onChange(null)`). They disagree; whoever verifies against a live editable grid should
+      // settle both at once.
+      const commit = (raw?: string): void => {
+        // Empty means "clear the cell", not "re-commit what was there" — matching the
+        // export-engine emitter. Without this a user can never blank an opted-in column.
+        if (raw !== undefined && raw.trim() === '') {
+          defaultProps.onChange(null);
+          return;
+        }
+        const parsed = toNumber(raw);
+        defaultProps.onChange(clamp(parsed === undefined ? current : parsed));
+      };
+
+      return (
+        <SpinButton
+          min={0}
+          max={PROGRESS_MAX}
+          step={5}
+          defaultValue={String(current)}
+          // Fires once, on a COMMITTED edit (blur / Enter / arrow) — v8 holds an uncommitted
+          // `intermediateValue` while typing, so this is not per-keystroke.
+          onChange={(_e, v) => commit(v)}
+          styles={{ root: { minWidth: 0, width: '100%' } }}
+        />
+      );
+    },
+  };
+}
+
+/** What the control registers with the grid — see `index.ts`. */
+export const cellEditorOverrides: CellEditorOverrides = createCellEditorOverrides();

package/templates/pcf-field/dev/harness/dataverse.ts

@@ -47,6 +47,112 @@ export async function readField(
     };
 }
 
+/** One choice, in the UPPERCASE shape the live PCF `attributes.Options` API uses. */
+export interface ChoiceOption {
+    Value: number;
+    Label: string;
+}
+
+/**
+ * Read the REAL choice metadata for a column, so a live option-set value renders its actual
+ * label instead of falling back to the Dropdown's placeholder.
+ *
+ * ★ Why this exists: the harness used to hand the control a hard-coded `Options: [1, 2, 3]`.
+ * Reading a real value like `100000002` then matched nothing, so the *read* was correct (the
+ * status line proved it) while the *rendered label* was blank — which looks exactly like a
+ * broken control. Verified against `dvk_devitem.dvk_status`, whose real options are
+ * 100000000/Draft, 100000001/Active, 100000002/Done.
+ *
+ * Three round trips, on each Load (not at mount):
+ *   1. entity SET name → entity LOGICAL name (`EntityDefinitions?$filter=EntitySetName eq …`)
+ *      — the binding gives us the plural set name, but the metadata tree is keyed by logical name.
+ *   2. the attribute's `AttributeTypeName` — which decides the cast in step 3. Guessing instead
+ *      costs the same number of calls in the worst case and fails non-deterministically.
+ *   3. the typed cast, with `OptionSet` expanded.
+ *
+ * ★ The cast is NOT always `PicklistAttributeMetadata`. A `statuscode` column is
+ * `StatusAttributeMetadata` and `statecode` is `StateAttributeMetadata`; asking for the Picklist
+ * cast on `account.statuscode` returns **404**, not an empty option list — so a single hard-coded
+ * cast silently yields no labels on exactly the columns most likely to be bound.
+ *
+ * Returns `null` for any column that has no choices (a String column, say) or when metadata is
+ * unreadable — the caller then keeps its mock options, which is the right behaviour for a
+ * harness: never fail the whole panel because one metadata lookup didn't apply.
+ */
+export async function readChoiceOptions(
+    entitySetName: string,
+    column: string,
+): Promise<ChoiceOption[] | null> {
+    // OData string literals escape a quote by doubling it; the result is then URL-encoded
+    // because both of these are free-text harness inputs and a stray `#` would truncate the
+    // request at the fragment, yielding a 400 the caller can only read as "no choices".
+    // (`%24` for `$` is cosmetic consistency with the rest of this file — `readField` above
+    // uses a raw `$select` and works fine; there is no shell in the browser→proxy→org path.)
+    const setName = encodeURIComponent(entitySetName.replace(/'/g, "''"));
+    const defs = await apiFetch(
+        `/api/data/v9.2/EntityDefinitions?%24select=LogicalName&%24filter=EntitySetName%20eq%20'${setName}'`,
+    );
+    if (!defs.ok) return null;
+    const logicalName = ((await defs.json()) as { value?: { LogicalName: string }[] }).value?.[0]
+        ?.LogicalName;
+    if (!logicalName) return null;
+
+    const safeColumn = encodeURIComponent(column.replace(/'/g, "''"));
+    const attrPath = `/api/data/v9.2/EntityDefinitions(LogicalName='${logicalName}')/Attributes(LogicalName='${safeColumn}')`;
+    const typeRes = await apiFetch(`${attrPath}?%24select=AttributeType,AttributeTypeName`);
+    if (!typeRes.ok) return null;
+    const attr = (await typeRes.json()) as {
+        AttributeType?: string;
+        AttributeTypeName?: { Value?: string };
+    };
+
+    // ★ Dispatch on `AttributeTypeName.Value`, NOT `AttributeType` (corrected in review of #306).
+    // `AttributeType` is the legacy `AttributeTypeCode` enum, whose 21 members do NOT include
+    // MultiSelectPicklist — a multi-select choice reports `AttributeType: "Virtual"`, so keying on
+    // it made that entry unreachable. `AttributeTypeName` carries the real discriminator.
+    // Measured against orge2e285aa:
+    //   account.statuscode → Status/StatusType     account.statecode          → State/StateType
+    //   account.name       → String/StringType     account.accountcategorycode → Picklist/PicklistType
+    const cast = {
+        PicklistType: 'PicklistAttributeMetadata',
+        StatusType: 'StatusAttributeMetadata',
+        StateType: 'StateAttributeMetadata',
+        MultiSelectPicklistType: 'MultiSelectPicklistAttributeMetadata',
+    }[attr.AttributeTypeName?.Value ?? ''];
+    if (!cast) return null; // not a choice column — the caller shows the value raw
+
+    // `GlobalOptionSet` is expanded as belt-and-braces only. Measured across all 20 picklist
+    // columns on `account` in orge2e285aa, `OptionSet` was populated EVERY time, including for
+    // global-backed choices — so this is not a confirmed gap, just the same defensive read the
+    // gallery's own optionset function does. Costs nothing; do not read it as a known failure.
+    const meta = await apiFetch(
+        `${attrPath}/Microsoft.Dynamics.CRM.${cast}?%24expand=OptionSet(%24select=Options),GlobalOptionSet(%24select=Options)`,
+    );
+    if (!meta.ok) return null;
+
+    type OptionRow = {
+        Value: number;
+        Label?: { UserLocalizedLabel?: { Label?: string }; LocalizedLabels?: { Label?: string }[] };
+    };
+    const body = (await meta.json()) as {
+        OptionSet?: { Options?: OptionRow[] };
+        GlobalOptionSet?: { Options?: OptionRow[] };
+    };
+    const options = body.OptionSet?.Options ?? body.GlobalOptionSet?.Options;
+    if (!options?.length) return null;
+
+    return options.map((o) => ({
+        Value: o.Value,
+        // `UserLocalizedLabel` is null when the caller's UI language has no provisioned label —
+        // a live scenario on CDX orgs — so fall through to the first localised label, then to the
+        // raw value. A visible number beats a blank option.
+        Label:
+            o.Label?.UserLocalizedLabel?.Label ??
+            o.Label?.LocalizedLabels?.[0]?.Label ??
+            String(o.Value),
+    }));
+}
+
 /**
  * Write one column back to one record — the save half of the round-trip.
  *