riverbankcms 0.38.1 → 0.38.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -54,7 +54,6 @@ export default defineConfig({
54
54
  category: 'content',
55
55
  icon: 'Workflow',
56
56
  tags: ['process', 'steps', 'flow'],
57
- promotedFields: ['title', 'introText'],
58
57
  fields: [
59
58
  {
60
59
  id: 'title',
@@ -89,7 +88,53 @@ export default defineConfig({
89
88
  });
90
89
  ```
91
90
 
92
- `promotedFields` is optional. Promoted behaviour/data fields appear in “What it shows”, promoted appearance fields in “Look”, and content fields stay in “Text”. Remaining fields appear in “More settings”; there is no quick-field cap.
91
+ Until you say otherwise, the block's settings form is laid out from each field's `ui.intent`. To choose what sits at the top of the form and how the settings are grouped, declare `editing` (below).
92
+
93
+ #### How the settings form is laid out
94
+
95
+ A block's settings form opens with what the block is made of (its heading, its writing, its list of items), followed by its settings. Declare `editing` on the block to say which fields are which:
96
+
97
+ ```typescript
98
+ {
99
+ id: 'custom.our-flow',
100
+ // ...
101
+ editing: {
102
+ content: ['title', 'introText', 'steps'],
103
+ settings: [
104
+ {
105
+ id: 'reveal',
106
+ title: 'How steps open',
107
+ fields: ['revealOn', 'showNumbers'],
108
+ summary: {
109
+ parts: [
110
+ { field: 'revealOn', options: { hover: 'on hover', click: 'on click' } },
111
+ { field: 'showNumbers', on: 'numbered' },
112
+ ],
113
+ none: 'Steps open on hover',
114
+ },
115
+ },
116
+ ],
117
+ },
118
+ }
119
+ ```
120
+
121
+ The example assumes the block also has a `revealOn` select and a `showNumbers` switch.
122
+
123
+ - **`content`** lists the fields that sit open at the top of the form, in order.
124
+ - **`settings`** lists the rest, in order. An entry is either a named group (`id`, `title`, `fields` and a `summary`) or a single field path, for a setting that sits beside the groups.
125
+ - **`summary`** is the line shown on a group's row, saying what's chosen. Each part is tied to one of the group's fields: `on` (a switch that's on), `options` (a phrase for each option of a select, or `null` for an option that says nothing), `text` (something typed, with fixed words round it), `set` / `unset` (something is there, such as a photo or a link), `count` (how many items a list has; `{n}` is the number) and `chosen` (names the picked item where the editor can look it up, and says `fallback` when it can't). The parts are joined with commas, and `none` is the line when no part has anything to say.
126
+ - **`setup`** takes up to three field paths to ask before the block is added. It's accepted and checked now; the editor starts asking them in a later release.
127
+ - A path can be nested (`border.enabled`), and a nested field can be placed without its parent.
128
+
129
+ When four or more settings are on offer, the groups show as rows, each with its summary line, and a row opens a view of that group's fields. With three or fewer, the settings show in place under the content. Rows sit above the first list (`repeater`) field named in `content`, or after the content when it has no list. A field hidden by a `visibleWhen` condition is left out of the count and out of its group's summary.
130
+
131
+ Any field `editing` doesn't name is placed by its `ui.intent`. Content fields join the content, along with any display or behaviour field that's required and has no default, so it's hard to miss. Other behaviour fields go in a “What it shows” group, and everything else goes in “More settings”. A block with no `editing` at all is laid out the same way. It's still worth declaring `editing` for most blocks, because then you choose the groups and write their summary lines.
132
+
133
+ If the block should offer a photo behind its section, place `_sectionStyles.background.image` in `editing`, usually in `content`. That's how a custom block says it keeps a section photo; when `editing` doesn't place it, the photo isn't offered.
134
+
135
+ A field extension on a built-in block (`blockFieldExtensions`) can declare `editing` too, to place the fields it adds: `content`, `settings`, or `join` to put them in one of the block's existing groups (`{ group: 'card', fields: ['badge'], summary: [...] }`).
136
+
137
+ Declarations are checked when you push your config. A push is refused if a declaration names a field that doesn't exist, places a field twice, joins a group the block doesn't have, or has a summary part that doesn't match its field (a select option with no phrase, for example).
93
138
 
94
139
  A custom block or built-in block extension can also declare `lookField` with the ID of one of its own existing single-select fields. Its options become labelled Look tiles. This remains an ordinary content field on every editing surface, including the dashboard; it does not use built-in Default or pin behaviour.
95
140