feat(controls): control sets, a control that adds a row of fields at once

[kevinchappell]

What

Control sets: a control that adds several predefined fields at once, like formBuilder's inputSets. Clicking or dropping one adds a single new row holding all of its fields, with new ids every time.

A set is an ordinary controls.elements entry with a controlSet key:

{
  id: 'address-set-control', // optional: lets your code call controls.addElement('address-set-control')
  meta: { group: 'common', id: 'address-set', icon: 'rows' },
  config: { label: 'Address' },
  controlSet: {
    layout: 'stacked', // default: one column; 'columns' gives each field its own column
    row: { config: { fieldset: true, legend: 'Address' } }, // optional data for the new row
    fields: [
      { control: 'text-input', attrs: { name: 'street' }, config: { label: 'Street' } },
      { control: 'select', attrs: { name: 'country' }, options: [{ label: 'Canada', value: 'ca', selected: false }] },
    ],
  },
}

• Members with control start from that control's data (its meta.id) and override it; arrays such as options replace the control's instead of being appended. Members without control are field data as is, and can name their control with meta.id.
• Placement: a click appends the row to the current page. A drop on a page puts it at the drop position; a drop on a row or column puts it in a new row right after that row (a set never goes inside an existing column, and the row it was dropped on keeps its column widths).
• Hooks: onBeforeAdd / formeoBeforeAdd (Feature: event/action upgrades #281) run once for the whole set with componentType: 'controlSet', the set's controlId, data: { layout, row, fields }, and the page and index the row goes to. A held drop is added once allowed, unless its target was removed meanwhile. The usual onAddRow / onAddColumn / onAddField events follow. controls.addElement(id) adds a set without the hook.
• Errors: an unknown member control, a layout control, another set, or a member that isn't an object is skipped with a formeo: control set "<id>" … console warning. A set left with no fields adds nothing and runs no hook.
• Dragging a set shows its own button, not a single-field ghost preview.
• The demo has an Address set (street, city, postcode, country).

Existing controls and existing onBeforeAdd handlers are unchanged; handlers that switch on componentType may now also see 'controlSet'.

Docs

docs/controls/custom-controls.md ("Control sets"), a pointer in docs/options/controls/README.md, and 'controlSet' in the onBeforeAdd section of docs/options/events/README.md.

Testing

• npm test: 701 pass (672 on main). New: src/lib/js/components/controls/control-set.test.js, src/lib/js/components/control-sets.test.js
• npm run lint: clean
• Playwright: 174 passed, 3 skipped (the pre-existing test.skips). New spec: tests/control-sets.spec.js

Follow-ups

• Save a canvas row as a set; multi-row and nested sets; inserting a set into an existing column
• Show/hide a set's row as one unit (Visability by Group #277)
• controls.addElement could accept a control's meta.id (today it needs the control's own id, for every control)

Fixes #227

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[kevinchappell]

🎉 This PR is included in version 5.12.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀