# Custom Fields Settings Audit vs Reference 6.9.5

Scope: Custom Fields module only. CPT Builder, Taxonomy Builder, Options Page Builder, and other modules are intentionally excluded.

Reference source checked: all `external-field-plugin/schemas/fields/v1/*.json` field schemas in Reference 6.9.5, plus Reference field classes where behavior was ambiguous. The PHP field classes are treated as the source of truth for builder UI controls because the JSON schemas include some broader import/API properties that are not rendered as field settings.

Schema files compared in this pass: `accordion`, `button_group`, `checkbox`, `clone`, `color_picker`, `date_picker`, `date_time_picker`, `email`, `file`, `flexible_content`, `gallery`, `google_map`, `group`, `icon_picker`, `image`, `link`, `message`, `number`, `oembed`, `page_link`, `password`, `post_object`, `radio`, `range`, `relationship`, `repeater`, `select`, `tab`, `taxonomy`, `text`, `textarea`, `time_picker`, `true_false`, `url`, `user`, and `wysiwyg`.

## Builder Order

The field editor should lead with the decision editors make first:

1. Field type
2. Label
3. Generated field key preview
4. Instructions
5. Type-specific basics
6. Display settings
7. Logic and relationships

New rows should not create a fallback key before a label exists. The key preview should stay blank until the label can produce a meaningful slug. Existing fields keep their persisted key.

## Settings Visibility Rules

Display-only fields (`message`, `tab`, `accordion`) should not show storage, required, admin-list, or conditional logic controls.

Nested stored fields (`group`, `repeater`, `flexible_content`, `clone`) still need storage/key controls because they save data. They should usually hide admin-list columns because their values are composite and not useful in list tables.

Reference exposes `allow_in_bindings` as a common field setting for Core block binding output. WP PowerSuite does not yet register a Core block binding source, so this remains an architectural parity item rather than a per-field UI toggle.

## Per-Type Settings Matrix

| Field type | Reference settings found | WP PowerSuite target behavior |
| --- | --- | --- |
| `text` | default, placeholder, prepend, append, maxlength | Show placeholder, default, character limit, before/after. |
| `textarea` | default, placeholder, maxlength, rows, new_lines | Show placeholder, default, character limit, rows, and new-lines output formatting. Do not show prepend/append in the builder; those appear only in the broader Reference JSON schema, not in the Reference field settings UI. |
| `number` | default, placeholder, prepend, append, min, max, step | Show placeholder, default, min/max/step, before/after. |
| `range` | default, prepend, append, min, max, step | Show default, min/max/step, and before/after. |
| `email` | default, placeholder, prepend, append | Show placeholder, default, and before/after. Do not show character limit because the reference plugin's Email field class does not render that setting. |
| `phone` | WP PowerSuite-only | Treat like text/email: placeholder, default, character limit, before/after. |
| `url` | default, placeholder | Show placeholder and default only. Hide character limit, format checks, and before/after for closer reference field behavior. |
| `password` | placeholder, prepend, append | Show placeholder and before/after. Hide default, character limit, and format checks for closer reference parity. |
| `date` | display/return format, first day, current date | Show display format, return format, first day, and default-current behavior. Hide normal default value and numeric min/max/step because Reference does not use those controls here. Keep Save Format only as legacy compatibility when an existing imported field already has a `save_format` value. |
| `time` | display/return format | Show display format and return format. Hide normal default value, default-current, and numeric min/max/step because Reference does not use those controls here. |
| `datetime` | display/return format, first day, current date | Show display format, return format, first day, and default-current behavior. Hide normal default value and numeric min/max/step because Reference does not use those controls here. |
| `color` | default, opacity, return format, palette | Show default, opacity, return format, custom/theme palette source, palette colors, and color-wheel visibility. Hide placeholder because Reference treats color defaults as values, not placeholder text. |
| `toggle` | default, message, UI, on/off text | Show default as a boolean control, message, plain-checkbox UI by default, optional stylized UI mode, and configurable on/off text only when stylized UI is enabled. |
| `select` | choices, default, multiple, allow null, UI/ajax, return format, create/save options | Show choices, default, multiple, allow empty, enhanced UI/AJAX/create/save flags, and value/label/array return format. Full Select2-style remote querying remains a later endpoint/UI pass. |
| `radio` | choices, default, layout, allow null, other choice, return format | Show choices, default, layout, allow empty, other choice/save-other behavior, and value/label/array return format. |
| `checkbox` | choices, default, layout, custom choice, toggle, return format | Show choices, multi-line default values, layout, custom choice/save-custom behavior, toggle-all, and value/label/array return format. |
| `button_group` | choices, default, layout, allow null, return format | Show choices, default, layout, allow empty, and value/label/array return format. |
| `nav_menu` | allow null, save format, container | Show menu selector, allow empty, id/object/rendered-menu return format, safe HTML container setting with the reference plugin's `0` value for no wrapper, and Gutenberg menu options. |
| `message` | message, new lines, escape HTML | Show message content, new-line handling defaulting to automatic paragraphs, and escape-HTML mode. |
| `separator` | type | Show a display-only divider with no meta storage or value settings. |
| `output` | html | Show safe display-only HTML with no meta storage or value settings. |
| `tab` | placement, endpoint | Show placement, endpoint metadata, and runtime tab behavior. Do not keep selected-state metadata; the reference plugin's active Tab field class does not render that setting. |
| `accordion` | open, multi-expand, endpoint | Show open, multi-expand, endpoint metadata, and runtime accordion behavior. |
| `icon_picker` | tabs, return format | Show source tabs for Dashicons, media library, and URL icons, plus string/array return format. |
| `google_map` | center lat/lng, zoom, height | Show address/lat/lng/zoom in the classic and Gutenberg input renderers, builder defaults for map center/zoom/height, and an editor map preview/open-in-Maps action from the current address or coordinates. |
| `wysiwyg` | default, tabs, toolbar, media upload, delay | Show default, tabs, toolbar, media upload toggle, and delay metadata. Do not show rows; the reference plugin's WYSIWYG field class does not render a rows setting. |
| `oembed` | width, height | Show width and height. Hide text placeholder/default/format/character controls because they do not match reference plugin. |
| `link` | return format | Show array/url return format. Hide unrelated choice/media/relationship controls. |
| `image` | return format, preview size, library, min/max size/dimensions, mime types | Show id/url/array return format, library, MIME, file size, dimensions, preview size defaulting to `medium`, and integer REST storage. |
| `gallery` | return format, preview size, insert, library, min/max count, size/dimensions, mime types | Show id/url/array return format, library, MIME, file size, dimensions, min/max count, preview size defaulting to `medium`, and insert position. |
| `file` | return format, library, min/max size, mime types | Show id/url/array return format, library, MIME, size, and integer REST storage. |
| `post_object` | post type, taxonomy, allow null, multiple, return format, UI, bidirectional | Show post type, post status, reference-compatible multi taxonomy term filter, allow empty, multiple, searchable UI, id/object return format, and bidirectional. Legacy single-taxonomy filters remain supported as a fallback. |
| `relationship` | post type, taxonomy, min/max, filters, elements, return format, bidirectional | Show post type, post status, reference-compatible multi taxonomy term filter, reference-compatible filter toggles, classic and Gutenberg dynamic post-type/taxonomy picker filters, featured-image selected-item previews, min/max item count, id/object return format, bidirectional sync, and two-pane selected-item UI. Do not show a separate multiple toggle; relationship is fixed multi-value. Legacy single-taxonomy filters remain supported as a fallback. |
| `page_link` | post type, post status, taxonomy, allow null, multiple, archives | Show post type, post status, reference-compatible multi taxonomy term filter, multiple, allow empty, and archive links. Do not show a return-format selector; Reference Page Link returns URLs. Legacy single-taxonomy filters remain supported as a fallback. |
| `term` | taxonomy, field type, allow null, return format, add/load/save terms, bidirectional | Default to Category + Checkboxes with Create Terms enabled, show select/multi/radio/checkbox UI modes, allow empty only when the UI is not Checkboxes, id/object return format, add/load/save terms, and bidirectional sync. Do not show a separate multiple toggle; multi-value behavior comes from Multi Select or Checkboxes. |
| `user` | role, multiple, allow null, return format, bidirectional | Show role, multiple, allow empty, id/object/array return format, and bidirectional. |
| `group` | sub fields, layout | Show storage/key, required, sub-fields, and block/table/row layout modes. Hide admin-list column. |
| `repeater` | sub fields, min/max, layout, button label, collapsed, rows per page | Show storage/key, required, sub-fields, min/max item count, layout, button label, collapsed preview, drag sorting, and rows-per-page pagination. |
| `flexible_content` | layouts, min/max, button label | Show storage/key, required, layouts, structured layout sub-fields, field min/max, per-layout display/min/max, button label, layout choice buttons, and row controls. Do not show the Group/Repeater field-level layout dropdown. |
| `clone` | clone source, display, layout, prefix label/name | Show storage/key, required, multi-source field/group picker, display, layout, prefix labels, prefix names, and self-recursion protection. |

## Known Problem Areas

- Conditional logic currently depends on field keys, so new fields without labels cannot be used as condition sources until they are named. New labeled rows now submit synchronized hidden key/name values instead of relying only on a visual preview.
- Conditional value dropdowns are smart for local choice fields and boolean fields. Relational value pickers still need a type-aware UI.
- Location/display rules are much better than before, but Reference has a broader location matrix; this module should add those carefully without mixing into CPT/Taxonomy/Options builders.
- Composite fields still need polish: repeater, flexible content, and clone now have structured controls, but they still need drag sorting, collapsed previews, and richer Reference layout behavior.
- Classic meta-box placement in the block editor can be effectively invisible when WordPress collapses the meta-box liner. Side-position simple groups should use the native document sidebar whenever possible; above/below-editor groups still need clear guidance or a more modern editing surface.
- The Gutenberg display block now targets block API v3, and the editing sidebar prefers the current `wp.editor.PluginDocumentSettingPanel` API with a fallback for older WordPress builds.

## Layout Corrections

The builder now treats settings rows as dynamic 12-column rows with consistent gutters. JavaScript recalculates visible controls after every field-type or dependent-option change: one visible control fills the row, two split the row evenly, three render as thirds, and additional controls wrap into another filled row. Text, Text Area, Number, media constraints, image dimensions, choice settings, repeatable counts, flags, and clone settings no longer leave awkward unused column space or use narrow fixed columns.

## Import / Export Corrections

External JSON imports are normalized before validation. Common external keys now map into this module's schema: `active` to enabled state, `position=acf_after_title` to Above the editor, reference `location` groups to internal location rules, `post_type`/`post_status` to relational allowlists, relational `taxonomy` term filters to term IDs, `filters`/`elements` to Relationship runtime controls, `field_type`/`add_term`/`load_terms`/`save_terms` to Taxonomy Term settings, and `return_format`/`default_value`/`prepend`/`append`/`library`/`preview_size` to their WP PowerSuite equivalents.

Browser QA imported a true reference-compatible group with `location`, `acf_after_title`, Relationship, and Taxonomy fields. The imported group opened with Above the editor selected, a `post_type == post` location rule, Relationship post/status/term filters preserved, and Taxonomy field type/add/load/save settings preserved.
