📮 RFC: Templateselect template names

[I-Valchev]

When using the templateselect field, I want to see semantic and meaningful names for templates, rather than the actual twig filename.

How can you help?

I can build it, or help people who want to build it 😉

[Vondry]

RFC: Semantic display names for templateselect options

Summary

Let content editors see meaningful template names ("Homepage", "Standard page") in the templateselect dropdown instead of raw Twig filenames (index.twig, record.twig). Fully opt-in, purely additive, with no breaking changes or migration.

How it would be used

A theme author ships friendly names for templates in the theme's own theme.yaml:

templateselect:
  labels:
    index.twig: 'Homepage'
    record.twig: 'Standard page'
    partials/landing.twig: 'Landing page'

All templateselect behaviour in theme.yaml lives under a single top-level key (labels today, display format below), adding one key to the {{ theme.* }} variables instead of several.

A site owner who doesn't want to edit a (possibly vendored and update-overwritten) theme puts the same templateselect: block in the site's config.yaml. Theme values override general ones—the same cascade Bolt already uses for record_template, listing_template, and related settings. For labels, values merge per filename (allowing a site to add or override individual entries); format and extract are scalar values where the most specific level wins.

A site developer who needs different wording for one specific field (or labels for a theme that doesn't ship any) adds them to the field definition in contenttypes.yaml:

template:
  type: templateselect
  filter: '/^[^_].*\.twig$/'
  labels:
    record.twig: 'Article layout'

The editor opening a record then sees a dropdown reading "Homepage (index.twig)", "Article layout (record.twig)" instead of bare filenames. Selecting, saving, and template resolution behave exactly as before because the stored value remains the filename.

Resolution order for each file the field lists:

1. Field-level labels
2. Theme-level templateselect.labels (theme.yaml)
3. Site-level templateselect.labels (config.yaml)
4. The filename itself (current behaviour)

Both maps are keyed by the template's relative pathname—the same string the dropdown stores today—so there is exactly one identifier concept throughout the feature.

Label keys: full relative paths, exact match

Label keys must be the template's full relative pathname from the theme's template directory (e.g. partials/landing.twig)—exactly the string the dropdown stores today, and the same string already used for record_template, listing_template, and related settings. Discovering the right key is therefore trivial: it is literally what the dropdown currently displays.

Lookup is by exact match; there is no basename matching. record.twig labels only the root-level record.twig, never partials/record.twig. Files sharing a basename in different folders are distinct entries and are labeled independently.

Basename fallback is deliberately rejected: it would introduce a second identifier concept, and with foo/detail.twig and bar/detail.twig present, a bare detail.twig key would either label both (ambiguous) or neither (surprising)—and adding a second file later would silently change existing behaviour. Exact match keeps resolution a single array lookup with no precedence rules within a level. Sites that genuinely want "the same label for every detail.twig anywhere" can express that pattern-based case with extract/format (below) instead of fuzzy label keys.

Two supporting rules make exact matching robust:

• Normalization. Before lookup, both label keys and discovered pathnames are normalized to forward slashes with no leading ./ (Symfony Finder's getRelativePathname() uses the platform directory separator, and users may write ./partials/landing.twig). This removes a whole class of "my label doesn't apply" surprises, on Windows in particular.
• Keys are independent of the field's path option. When a field restricts discovery with path:, the stored key (and therefore the label key) remains relative to the theme's template root, not to that subfolder—matching current behaviour, where path() only filters and getRelativePathname() stays anchored at the template directory. Label maps therefore work unchanged across fields with different path settings.

Development-mode warnings for dead label keys

Because a label key that matches no template silently falls back to the filename, the feature includes a development-mode check that surfaces dead keys instead of leaving them to be discovered by eye:

• Whenever a templateselect option list is built in the dev environment, every configured label key is checked against the templates it could apply to: field-level labels against that field's discovered list (a field-level label for a file the field's filter/path can never show is dead by definition), and theme-/site-level labels against the files in the theme's template directory.
• Keys are normalized (forward slashes, no leading ./) before the check—the same normalization used for lookup—so the warning fires only for genuinely dead keys, not formatting variants.
• An unmatched key is reported through the standard Symfony logger at warning level, making it visible in the profiler toolbar and dev log. The message names the key, the configuration source (field / theme.yaml / config.yaml), and the nearest existing pathname when one is similar (catching the common rename-without-relabel case).
• The check runs only in the dev environment. Production builds skip it entirely, so it adds no cost and can never affect rendered output—the fallback-to-filename behaviour is identical with or without the warning.

For reuse, the same lookup is exposed as a Twig function, template_label(filename, field = null), allowing extensions or custom admin screens that display template filenames to reuse the same friendly names without reimplementing the mapping. Field-level labels only exist relative to a field, so the optional field argument enables that level; without it, only theme- and site-level labels apply.

Labels are escaped, never raw HTML

The admin's select component renders option display values as raw HTML (v-html in Select.vue). Today those values are discovered filenames; this feature replaces them with arbitrary strings from theme.yaml—a file that frequently ships inside third-party, vendored themes. Without escaping, a theme could inject markup or script into an editor's admin session through a label.

Therefore, as a hard requirement rather than an implementation detail: resolved labels, extract-derived placeholder values, and the final format output are HTML-escaped before they enter the option's display value. Labels are plain text by contract; there is no supported way to style or embed markup in an option.

Everything is opt-in: a site that configures nothing sees no difference whatsoever.

Configuring the display format

Bolt already has a house idiom for composing display strings using placeholders (for example, title_format: '{heading} - {subheading}'). Reusing that convention, two settings control how each option is rendered, cascading field definition → theme.yaml → config.yaml → built-in default:

# theme.yaml — theme/site-wide defaults
templateselect:
  format: '{label}'
  extract: '/^(?<stem>.*)\.twig$/'
  labels:
    index.twig: 'Homepage'

# contenttypes.yaml — per-field override
template:
  type: templateselect
  format: '{label} — {stem}'
  extract: '/^pages\/(?<stem>.*)\.twig$/'

• format composes the displayed text from placeholders: {label} (resolved semantic name), {filename} (the relative path), and every named capture group from extract. Whether filenames appear is controlled simply by including or omitting {filename}.
• extract defines which parts of the filename become placeholders. Named capture groups become placeholders (for example, pages/about_us.twig yields {stem} = about_us). Extraction and formatting remain independent. Like label keys, extract runs against the normalized full relative pathname, so patterns can match on folder structure (e.g. distinguish pages/ from partials/).

Fallback rules keep the behaviour predictable:

• No format configured anywhere → the built-in default ("Label (filename)" when a label exists, otherwise the filename). This preserves today's behaviour.
• An explicitly configured format is applied verbatim. {label} automatically falls back to the filename when no label exists, so format: '{label}' never produces an empty option.
• An invalid or non-matching extract regex causes its placeholders to fall back to the full filename, using the same validation approach as the existing filter option. A bad regex cannot blank out the dropdown.
• Built-in placeholders ({label}, {filename}) always take precedence over identically named capture groups from extract.
• A placeholder that is neither built-in nor an extract capture group (e.g. the typo {lable}) renders as (unknown), matching how Bolt's existing title_format handling (ContentHelper) treats unresolvable placeholders. This makes the typo visible in the dropdown instead of silently swallowed.
• The implicit default ("Label (filename)" only when a label exists) is intentionally not expressible in the format language itself. An explicit format is always applied literally.
• The "(file seems to be missing)" marker is appended after formatting.

Additional consequences:

• Still non-breaking by construction — these settings affect only the displayed value; the stored key remains the filename.
• Visual ambiguity becomes user-configurable — using format: '{label}' with duplicate labels, or an extract that collapses multiple filenames into the same placeholder, can produce visually identical options. Selection remains unambiguous because the stored keys are unique.
• One more configuration cascade to document, but it follows the same precedence model as label lookup and introduces no new mental model.
• Future flexibility — new derived placeholders ({dir}, {basename}, etc.) can be added later without changing existing configuration.

Breaking-change analysis

The design is non-breaking by construction. The dropdown options have always had separate key (stored) and value (displayed) fields; this feature changes only the displayed value.

• Stored content — records continue storing filenames. No migration is required, and existing records render identically. TemplateChooser never sees labels.
• Unconfigured sites — with no templateselect configuration or field labels, the generated option list is byte-for-byte identical to today's output. This should be protected by a regression test.
• Configuration compatibility — earlier Bolt 6 releases ignore the unknown templateselect key, while the content-type parser already preserves unknown field keys such as labels. Themes shipping labels remain installable on those releases; the labels are simply not shown.
• Templates, frontend output, and APIs — {{ record.template }}, GraphQL/JSON output, and theme rendering continue exposing filenames unchanged. Labels exist only in the editor UI.
• Removed or renamed files — existing "file seems to be missing" behaviour is unchanged. Labels simply decorate that existing entry.

Risks

• Labels drift from files. A template may be renamed without updating its label. The stale mapping simply stops matching and the filename is displayed instead; the development-mode warning flags the dead key (with a nearest-match hint) so the drift is caught during development rather than noticed by editors.
• Bare-filename expectations. Users may expect record.twig to also match templates in subfolders; it doesn't. The label silently doesn't apply and the filename is shown—the same failure mode as a typo'd key, and surfaced by the same development-mode warning.
• Duplicate labels. Multiple templates can intentionally share the same label. Selection remains unambiguous because filenames remain the stored values.
• Editor/developer vocabulary split. Editors may refer to labels rather than filenames. Displaying filenames alongside labels preserves traceability.
• Localization expectations. Labels are plain YAML strings, so multilingual backends display one language for everyone. Translator integration can be layered on later.
• Sorting under label-only display. Options remain filename-sorted. With format: '{label}', this may appear arbitrary, making label-based ordering a logical follow-up feature.
• Typos in label keys. A label that matches no template silently falls back to the filename in all environments; the development-mode warning makes such keys visible during development.
• labels sits one character from the reserved label key. Field definitions already use label (singular) for the field's admin display name, assigned during content-type parsing. A user who writes label: with a mapping under it corrupts the field's admin label instead of defining template labels—and the development-mode warning cannot catch it, because no labels key exists in that case. The name is kept regardless, since it matches the theme-level key; documentation should show the two keys side by side.
• Configuration caching. Label and format changes require the usual configuration cache clear. Bolt's select-options cache layer (caching.selectoptions / SelectOptionsCacher) wraps only content-type-backed selects, not list_templates, so templateselect options—and therefore labels—are rebuilt on each render and cannot go stale there.
• Performance. Negligible. Label resolution adds only one array lookup per discovered template.

Flexibility

Flexibility comes from introducing a single label-resolution layer between template discovery and rendering. Concretely, this layer is a dedicated service (TemplateLabelResolver, in the mold of TemplateChooser) injected into FieldExtension, rather than logic inlined in getListTemplates(). The template_label Twig function and the development-mode warning are thin wrappers around the same service. Making it a service is what turns the extension points below from aspiration into mechanism—extensions can decorate or replace it through the container, as with any Bolt service.

• New label sources—such as in-template annotations ({# templateselect: Homepage #}), extension-provided providers, or translation catalogs—can simply become additional resolution steps.
• Richer metadata—if theme.yaml later supports structures such as index.twig: { name: ..., description: ..., group: ... }, only the resolution layer changes. Today's filename: label format remains valid.
• Per-context overrides are already supported through field-level labels, allowing different templateselect fields to describe the same template differently.
• Presentation changes—such as hiding filenames, grouping templates, or sorting by label—remain independent UI decisions built on top of the resolved labels.

The key design constraint is that the filename remains the sole identifier throughout the system; labels are purely decorative. That property keeps future extensions non-breaking because nothing downstream can depend on labels.

Out of scope (deferred)

• In-template annotations as a label source (would require per-render file reads and caching).
• Translator pass-through for localized labels.
• Label-based ordering (options continue using filename order).
• Optional-placeholder grammar in format (for conditional rendering).
• Glob or pattern-based label keys (exact relative-path matching only; pattern-based display needs are served by extract/format).