Dynamic values: consumer API — standalone settings dialog, labels, portalContainer

[KapplerJulien]

Why

Products that pick dynamic values from outside a field — a page builder's own dialog, a block editor's toolbar (Tangible Certificates' template builder is the first) — had no way in. The settings modal and its helpers were internal to the bundle, the API object needed a host field (dynamicValuesAPI(value, setValue, …)), and the dialog's strings were hardcoded.

Everything here is additive; defaults reproduce today's behaviour and BaseWrapper is unchanged.

What

Exports (assets/src/index.tsx): DynamicFieldSettings, DynamicValueSettings (a value's settings sub-form on its own) and a dynamicValues namespace — createAPI, buildGroupedChoices, stringify, parse, regex, defaultLabels.

createDynamicValuesAPI({ types, categories, mode }) returns the same shape as dynamicValuesAPI with the value-bound members inert, so the modal, wrappers and choice builder don't care which one they got.

DynamicFieldSettings props

• modes — ['builtin'] hides the Field Type toggle (a consumer whose "custom" means something of its own).
• labels — every string of the dialog.
• portalContainer — the same prop renderField() accepts. The dialog goes through usePortalContainer like every other dialog in the module, which creates the interface wrapper (tf-interface, tf-context-<name>, tui-interface) inside it; the hook learns to take the portal container and wrapper explicitly when there is no context above it. Our styles are scoped under those classes and TUI portals the pickers' panels into the nearest .tui-interface, so the panel is styled by the module's own TUI copy (without it a consumer's TUI styles the panel; we hit a half-width search box).
• context — the tf-context name when rendered outside any field.
• onSubmit(raw, meta) — raw is the full [[name::setting=value]] token, the saved-value format render_value() takes (it used to omit the delimiters, an internal convenience of the editor's serialiser — review follow-up). meta describes the pick: mode, value, label, group, settings.
• Blank settings no longer travel in the token: [[user_meta::meta_name=x]], not [[user_meta::source=::meta_name=x]] (the parser defaults missing settings to '' anyway).

Refactor: the modal's settings loop moves into DynamicValueSettings; the modal uses buildGroupedChoices instead of its own copy. Both work without a ControlContext above them (EnsureControlContext provides the same context renderField() builds).

Consumer example

const { DynamicFieldSettings, dynamicValues } = window.tangibleFields

<DynamicFieldSettings
  open={ open }
  onOpenChange={ setOpen }
  dynamic={ dynamicValues.createAPI({ categories: ['user', 'general'] }) }
  modes={ ['builtin'] }
  labels={ { title: 'Insert a field', select: 'Field' } }
  portalContainer={ host }
  context="wp"
  onSubmit={ (token, meta) => insertChip(token, meta.label) }
/>

Verification

• Jest: 10 new tests in tests/jest/cases/dynamic/consumer-api.test.tsx (factory, modal props, portal wrapper, editing, sub-form); dynamic-values cases at 54 passing, full suite at 572.
• Storybook: Dynamic Values / Settings dialog — autodocs plus four stories (default, built-in narrowed, custom labels, editing a reference). Built and driven headlessly.
• Real page: driven from a WordPress block editor via window.tangibleFields — grouped list, settings sub-form, edit-in-place, blank settings dropped.
• tsc reports no errors in the changed files (the two in index.tsx are pre-existing).

Notes for review

• An earlier revision carried an extraGroups prop (consumer-provided groups listed after the registry). Dropped: the consumer that motivated it keeps its document-scoped choices in its own picker, and without a use case it was the one client-side notion in a registry-driven dialog.
• An earlier revision mounted the dialog straight into a consumer's element and added the interface classes to it. Replaced by portalContainer through the shared hook, so no consumer DOM is touched and the module keeps one concept for "where overlays go".
• Windows: storybook build needs Node ≥ 20.19 and two native bindings npm ci skips (@oxc-parser/binding-win32-x64-msvc, @rolldown/binding-win32-x64-msvc) — unrelated to this PR, noting it for whoever builds Storybook next.

🤖 Generated with Claude Code

[nicolas-jaussaud]

Looks good to me!

The only thing we might want to change is the format of raw returned by onSubmit() (see associated comment)

[nicolas-jaussaud]

Merged despite failing checks. Tests are passing and issue is linked to #96