Palettes: reusable param groups composed by reference (use: <palette>) #305

New issue

Open

opened 2026-10-15 12:27:55 +02:00 by dominik.polakovics · 0 comments

dominik.polakovics commented

2026-10-15 12:27:55 +02:00

Owner

This was generated by AI during triage.

Summary

Reusable groups of params a sidecar composes by reference: a palette file under editor/palettes/ holds a params list, and an element's or page type's params list says use: <palette> where it wants them. First case: a heading palette with the heading text and a select for the heading level, so a feature or the scaffold defines "a heading" once.

Context

From a design discussion on 2026-10-15 about TCA-style sidecar extension. Sibling issues: engine capabilities for Access-tab fields, and class-wide overlays with a theme hook registry. Sidecar versioning (#302) is the groundwork: the use: entry is a new shape in the params list the canonical serializer must own.

Today every element declares its params inline (scaffold/editor/elements/hero.yaml declares heading and the shortcode hard-codes an h2). The link companions <name>Target and <name>Title are already an engine-owned param group in disguise.

Design settled in the discussion

A fifth sidecar family, editor/palettes/<name>.yaml, loaded by internal/sidecardir like the others: the name rule, the strict decode, the language file beside it. A feature ships one like any file; it is listed in the receipt and removed with the feature. Feature palettes carry the feature's prefix.
use: <palette> is an entry in the params: (or page-type fields:) list and expands in place. Each expanded param's tab comes from the palette; order within a tab is list order, today's rule.
Expansion happens in the loader before validation, so everything downstream sees plain params and the client never learns the concept (ADR 0015). The cross-schema pass gains one reference kind: the palette must exist.
Strict in v1, loosened later as optional keys: a palette param name colliding with the element's own or with another palette's is a load error; no palette uses a palette; no per-use overrides. A rule that starts strict can be relaxed without touching a production site; the reverse breaks sites.
Language files translate the expanded schema by name; where a param came from is invisible to them. The palette's own language file is the default text; the element's language file may override a palette param's label by name, the element being the nearer owner.
Stored param names are frozen by content, so the naming rule for using one palette twice in an element (an as: prefix giving subHeading) is decided in v1 even if not implemented.

Open for triage

The as: naming rule, and whether a heading palette may own the implicit title.
Per-use overrides to allow first, when needed: required, default, label, tab.
Whether the scaffold ships a heading palette and a ce/heading.html partial, and which shipped elements adopt it (hero, cta, quote).
harness sidecar: drafting a use: entry from a shortcode's call to the palette's partial.
The served form: an optional fieldset grouping for a palette, later.
Docs: AGENTS.md "Element sidecar schema", "Page types" and "Sidecar language files", a new "Palettes" section, the theme README; skills add-element, add-page-type, create-feature, redo-theme; internal/element/agentsdoc_test.go and scaffold/skills_test.go.

Blocked by

#302

> *This was generated by AI during triage.* ## Summary Reusable groups of params a sidecar composes by reference: a palette file under `editor/palettes/` holds a params list, and an element's or page type's params list says `use: <palette>` where it wants them. First case: a heading palette with the heading text and a select for the heading level, so a feature or the scaffold defines "a heading" once. ## Context From a design discussion on 2026-10-15 about TCA-style sidecar extension. Sibling issues: engine capabilities for Access-tab fields, and class-wide overlays with a theme hook registry. Sidecar versioning (#302) is the groundwork: the `use:` entry is a new shape in the params list the canonical serializer must own. Today every element declares its params inline (`scaffold/editor/elements/hero.yaml` declares `heading` and the shortcode hard-codes an h2). The link companions `<name>Target` and `<name>Title` are already an engine-owned param group in disguise. ## Design settled in the discussion - A fifth sidecar family, `editor/palettes/<name>.yaml`, loaded by `internal/sidecardir` like the others: the name rule, the strict decode, the language file beside it. A feature ships one like any file; it is listed in the receipt and removed with the feature. Feature palettes carry the feature's prefix. - `use: <palette>` is an entry in the `params:` (or page-type `fields:`) list and expands in place. Each expanded param's tab comes from the palette; order within a tab is list order, today's rule. - Expansion happens in the loader before validation, so everything downstream sees plain params and the client never learns the concept (ADR 0015). The cross-schema pass gains one reference kind: the palette must exist. - Strict in v1, loosened later as optional keys: a palette param name colliding with the element's own or with another palette's is a load error; no palette uses a palette; no per-use overrides. A rule that starts strict can be relaxed without touching a production site; the reverse breaks sites. - Language files translate the expanded schema by name; where a param came from is invisible to them. The palette's own language file is the default text; the element's language file may override a palette param's label by name, the element being the nearer owner. - Stored param names are frozen by content, so the naming rule for using one palette twice in an element (an `as:` prefix giving `subHeading`) is decided in v1 even if not implemented. ## Open for triage - The `as:` naming rule, and whether a heading palette may own the implicit `title`. - Per-use overrides to allow first, when needed: `required`, `default`, `label`, `tab`. - Whether the scaffold ships a heading palette and a `ce/heading.html` partial, and which shipped elements adopt it (hero, cta, quote). - `harness sidecar`: drafting a `use:` entry from a shortcode's call to the palette's partial. - The served form: an optional fieldset grouping for a palette, later. - Docs: AGENTS.md "Element sidecar schema", "Page types" and "Sidecar language files", a new "Palettes" section, the theme README; skills `add-element`, `add-page-type`, `create-feature`, `redo-theme`; `internal/element/agentsdoc_test.go` and `scaffold/skills_test.go`. ## Blocked by - #302

dominik.polakovics added the

needs-triage

enhancement

labels

2026-10-15 12:27:55 +02:00