From 19c3a1376eebad8a18b3683e459239da3b82b36c Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 12:22:02 +0100
Subject: [PATCH 01/19] feat(dom): resolve label position from labelPosition,
 then legacy labelAfter

Refs #243
---
 src/lib/js/common/dom.js                  |  15 ++--
 src/lib/js/common/dom.test.js             |  16 ++++
 src/lib/js/common/label-position.mjs      |  75 ++++++++++++++++
 src/lib/js/common/label-position.test.mjs | 103 ++++++++++++++++++++++
 4 files changed, 199 insertions(+), 10 deletions(-)
 create mode 100644 src/lib/js/common/label-position.mjs
 create mode 100644 src/lib/js/common/label-position.test.mjs

diff --git a/src/lib/js/common/dom.js b/src/lib/js/common/dom.js
index 94fe5553..973b1516 100644
--- a/src/lib/js/common/dom.js
+++ b/src/lib/js/common/dom.js
@@ -13,6 +13,7 @@ import {
 } from '../constants.js'
 import animate from './animation.js'
 import h, { forEach } from './helpers.mjs'
+import { isLabelAfter, resolveLabelPosition } from './label-position.mjs'
 import { loaded } from './loaders.js'
 import { componentType, merge, uuid } from './utils/index.mjs'
 import { extractTextFromHtml, groupInputName, slugify, truncateByWord } from './utils/string.mjs'
@@ -278,9 +279,6 @@ class DOM {
           if (_this.labelAfter(elem)) {
             wrapContent.reverse()
           }
-          // if has label config, must be a field.
-          // @todo change this logic so dom.create is project agnostic
-          // wrap.className.push('formeo-field')
           wrap.children.push(wrapContent)
         }
       }
@@ -763,15 +761,12 @@ class DOM {
   }
 
   /**
-   * Test if label should be display before or after an element
-   * @param  {Object} elem config
-   * @return {Boolean} labelAfter
+   * Whether a field's label comes after its control: bottom and after (#243). See label-position.mjs
+   * @param  {Object} elem field config
+   * @return {Boolean}
    */
   labelAfter(elem) {
-    const type = h.get(elem, 'attrs.type')
-    const labelAfter = h.get(elem, 'config.labelAfter')
-    const isCB = type === 'checkbox' || type === 'radio'
-    return labelAfter === undefined ? isCB : labelAfter
+    return isLabelAfter(resolveLabelPosition(elem))
   }
 
   /**
diff --git a/src/lib/js/common/dom.test.js b/src/lib/js/common/dom.test.js
index e51658e9..77eba822 100644
--- a/src/lib/js/common/dom.test.js
+++ b/src/lib/js/common/dom.test.js
@@ -115,6 +115,22 @@ describe('DOM Class', async _t => {
     assert.equal(dom.labelAfter(explicitLabelAfter), true)
   })
 
+  await test('create puts the label where config.labelPosition says (#243)', () => {
+    const order = labelPosition => {
+      const wrap = dom.create({
+        tag: 'input',
+        id: 'lp',
+        attrs: { type: 'text' },
+        config: { label: 'Name', labelPosition },
+      })
+      return [...wrap.children].map(child => child.tagName.toLowerCase())
+    }
+    assert.deepEqual(order('top'), ['label', 'input'])
+    assert.deepEqual(order('before'), ['label', 'input'])
+    assert.deepEqual(order('bottom'), ['input', 'label'])
+    assert.deepEqual(order('after'), ['input', 'label'])
+  })
+
   await test('isDOMElement', () => {
     const elem = document.createElement('div')
     assert.equal(dom.isDOMElement(elem), true)
diff --git a/src/lib/js/common/label-position.mjs b/src/lib/js/common/label-position.mjs
new file mode 100644
index 00000000..4ce2514a
--- /dev/null
+++ b/src/lib/js/common/label-position.mjs
@@ -0,0 +1,75 @@
+// Where a field's label sits relative to its control (#243). Pure: no DOM and no editor state.
+
+/** top and bottom stack; before and after sit side by side (mirrored in RTL). DOM order always matches visual order. */
+export const LABEL_POSITIONS = ['top', 'bottom', 'before', 'after']
+
+/** The class on a rendered field's label wrapper, and on the editor's label and preview wrapper */
+export const FIELD_WRAP_CLASSNAME = 'f-field'
+
+const warnedValues = new Set()
+
+/**
+ * A checkbox or radio input on its own, not a group of options: its label defaults to after it
+ * @param {Object} field
+ * @return {Boolean}
+ */
+const isLoneCheckable = ({ attrs, options } = {}) => ['checkbox', 'radio'].includes(attrs?.type) && !options
+
+/**
+ * The position a field's label renders in: a valid config.labelPosition, then legacy config.labelAfter, then the
+ * default (after for a lone checkbox or radio, top for everything else)
+ * @param {Object} [field] field data: { attrs, config, options }
+ * @return {'top'|'bottom'|'before'|'after'}
+ */
+export const resolveLabelPosition = (field = {}) => {
+  const { labelPosition, labelAfter } = field.config || {}
+  if (LABEL_POSITIONS.includes(labelPosition)) {
+    return labelPosition
+  }
+  if (labelPosition !== undefined && !warnedValues.has(String(labelPosition))) {
+    warnedValues.add(String(labelPosition))
+    console.warn(`formeo: unknown labelPosition "${labelPosition}"; use one of ${LABEL_POSITIONS.join(', ')}`)
+  }
+  const lone = isLoneCheckable(field)
+  if (typeof labelAfter === 'boolean') {
+    if (lone) {
+      return labelAfter ? 'after' : 'before'
+    }
+    return labelAfter ? 'bottom' : 'top'
+  }
+  return lone ? 'after' : 'top'
+}
+
+/**
+ * Whether the label comes after the control in the DOM (and on screen)
+ * @param {String} position a label position
+ * @return {Boolean}
+ */
+export const isLabelAfter = position => position === 'bottom' || position === 'after'
+
+/**
+ * The label wrapper's classes for a position
+ * @param {String} position a label position
+ * @return {String[]} ['f-field', 'f-label-<position>']
+ */
+export const labelWrapClassNames = position => [FIELD_WRAP_CLASSNAME, `f-label-${position}`]
+
+/**
+ * A field's config with legacy labelAfter, or an unknown labelPosition, replaced by the labelPosition it resolves to.
+ * Returns the same object when there is nothing to convert. Never mutates the field.
+ * @param {Object} field field data
+ * @return {Object|undefined} config
+ */
+export const normalizeLabelConfig = (field = {}) => {
+  const { config } = field
+  if (!config) {
+    return config
+  }
+  const hasLegacy = 'labelAfter' in config
+  const hasUnknown = config.labelPosition !== undefined && !LABEL_POSITIONS.includes(config.labelPosition)
+  if (!hasLegacy && !hasUnknown) {
+    return config
+  }
+  const { labelAfter: _labelAfter, ...rest } = config
+  return { ...rest, labelPosition: resolveLabelPosition(field) }
+}
diff --git a/src/lib/js/common/label-position.test.mjs b/src/lib/js/common/label-position.test.mjs
new file mode 100644
index 00000000..dd31f2ae
--- /dev/null
+++ b/src/lib/js/common/label-position.test.mjs
@@ -0,0 +1,103 @@
+import assert from 'node:assert/strict'
+import { describe, it, mock } from 'node:test'
+import {
+  FIELD_WRAP_CLASSNAME,
+  isLabelAfter,
+  LABEL_POSITIONS,
+  labelWrapClassNames,
+  normalizeLabelConfig,
+  resolveLabelPosition,
+} from './label-position.mjs'
+
+const text = config => ({ tag: 'input', attrs: { type: 'text' }, config })
+const checkbox = config => ({ tag: 'input', attrs: { type: 'checkbox' }, config })
+const radio = config => ({ tag: 'input', attrs: { type: 'radio' }, config })
+const group = config => ({ tag: 'input', attrs: { type: 'checkbox' }, config, options: [{ label: 'A', value: 'a' }] })
+
+describe('resolveLabelPosition (#243)', () => {
+  it('uses a valid config.labelPosition as is', () => {
+    for (const position of LABEL_POSITIONS) {
+      assert.equal(resolveLabelPosition(text({ labelPosition: position })), position)
+      assert.equal(resolveLabelPosition(checkbox({ labelPosition: position })), position)
+    }
+  })
+
+  it('defaults to after for a lone checkbox or radio and top for everything else', () => {
+    assert.equal(resolveLabelPosition(text({})), 'top')
+    assert.equal(resolveLabelPosition(checkbox({})), 'after')
+    assert.equal(resolveLabelPosition(radio({})), 'after')
+    assert.equal(resolveLabelPosition(group({})), 'top')
+    assert.equal(resolveLabelPosition({ tag: 'select', config: {} }), 'top')
+    assert.equal(resolveLabelPosition({ config: {} }), 'top')
+    assert.equal(resolveLabelPosition(), 'top')
+  })
+
+  it('maps legacy labelAfter: stacked for most controls, beside for a lone checkbox or radio', () => {
+    assert.equal(resolveLabelPosition(text({ labelAfter: true })), 'bottom')
+    assert.equal(resolveLabelPosition(text({ labelAfter: false })), 'top')
+    assert.equal(resolveLabelPosition(checkbox({ labelAfter: true })), 'after')
+    assert.equal(resolveLabelPosition(checkbox({ labelAfter: false })), 'before')
+    assert.equal(resolveLabelPosition(radio({ labelAfter: false })), 'before')
+    assert.equal(resolveLabelPosition(group({ labelAfter: true })), 'bottom')
+    assert.equal(resolveLabelPosition({ config: { labelAfter: true } }), 'bottom')
+  })
+
+  it('lets labelPosition win over labelAfter', () => {
+    assert.equal(resolveLabelPosition(text({ labelPosition: 'before', labelAfter: true })), 'before')
+  })
+
+  it('warns once about an unknown labelPosition and falls back', () => {
+    const warn = mock.method(console, 'warn', () => {})
+    try {
+      assert.equal(resolveLabelPosition(text({ labelPosition: 'left' })), 'top')
+      assert.equal(resolveLabelPosition(checkbox({ labelPosition: 'left', labelAfter: false })), 'before')
+      assert.equal(warn.mock.callCount(), 1, 'one warning per unknown value')
+      assert.match(warn.mock.calls[0].arguments[0], /^formeo: unknown labelPosition "left"/)
+    } finally {
+      warn.mock.restore()
+    }
+  })
+})
+
+describe('isLabelAfter and labelWrapClassNames', () => {
+  it('puts the label after the control for bottom and after only', () => {
+    assert.deepEqual(LABEL_POSITIONS.map(isLabelAfter), [false, true, false, true])
+  })
+
+  it('names the wrapper f-field plus a position modifier', () => {
+    assert.equal(FIELD_WRAP_CLASSNAME, 'f-field')
+    assert.deepEqual(labelWrapClassNames('before'), ['f-field', 'f-label-before'])
+  })
+})
+
+describe('normalizeLabelConfig', () => {
+  it('returns the same config when there is nothing to convert', () => {
+    const plain = { label: 'Name' }
+    const positioned = { label: 'Name', labelPosition: 'after' }
+    assert.equal(normalizeLabelConfig(text(plain)), plain)
+    assert.equal(normalizeLabelConfig(text(positioned)), positioned)
+    assert.equal(normalizeLabelConfig({ tag: 'hr' }), undefined)
+  })
+
+  it('replaces labelAfter with the position it resolves to, without mutating the input', () => {
+    const legacy = { label: 'Name', labelAfter: true }
+    assert.deepEqual(normalizeLabelConfig(text(legacy)), { label: 'Name', labelPosition: 'bottom' })
+    assert.deepEqual(legacy, { label: 'Name', labelAfter: true })
+    assert.deepEqual(normalizeLabelConfig(checkbox({ labelAfter: false })), { labelPosition: 'before' })
+  })
+
+  it('drops labelAfter when labelPosition is already set', () => {
+    assert.deepEqual(normalizeLabelConfig(text({ labelPosition: 'after', labelAfter: false })), {
+      labelPosition: 'after',
+    })
+  })
+
+  it('replaces an unknown labelPosition with the resolved one', () => {
+    const warn = mock.method(console, 'warn', () => {})
+    try {
+      assert.deepEqual(normalizeLabelConfig(text({ labelPosition: 'sideways' })), { labelPosition: 'top' })
+    } finally {
+      warn.mock.restore()
+    }
+  })
+})

From 9dbcfc2461f9e235827ee1422d64b56df685b7ed Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 12:24:15 +0100
Subject: [PATCH 02/19] feat(renderer): give labelled fields an f-field
 f-label-<position> wrapper

Refs #243
---
 src/lib/js/common/dom.js                   |  20 ++-
 src/lib/js/renderer/index.js               |  21 ++-
 src/lib/js/renderer/label-position.test.js | 177 +++++++++++++++++++++
 3 files changed, 213 insertions(+), 5 deletions(-)
 create mode 100644 src/lib/js/renderer/label-position.test.js

diff --git a/src/lib/js/common/dom.js b/src/lib/js/common/dom.js
index 973b1516..38419819 100644
--- a/src/lib/js/common/dom.js
+++ b/src/lib/js/common/dom.js
@@ -61,6 +61,17 @@ const GROUP_CONSUMED_ATTRS = new Set(['type', 'id', 'name', 'className', 'value'
 export const groupWrapperAttrs = (attrs = {}) =>
   Object.fromEntries(Object.entries(attrs).filter(([key]) => !GROUP_CONSUMED_ATTRS.has(key)))
 
+/**
+ * Class values (strings, arrays, nested arrays) as one space-separated string
+ * @param {...(String|Array)} values
+ * @return {String}
+ */
+const joinClassNames = (...values) =>
+  values
+    .flat(Infinity)
+    .filter(value => typeof value === 'string' && value.trim())
+    .join(' ')
+
 const stripOn = str => str.replace(/^on([A-Z])/, (_, l) => l.toLowerCase())
 const useCaptureEvts = new Set(['focus', 'blur'])
 const defaultActionHandler = event => {
@@ -600,10 +611,6 @@ class DOM {
           className: [`f-${fieldType}`],
         }
 
-        if (attrs.className) {
-          elem.config = { ...elem.config, inputWrap: attrs.className }
-        }
-
         if (elem.config?.inline) {
           inputWrap.className.push(`f-${fieldType}-inline`)
         }
@@ -651,6 +658,11 @@ class DOM {
       return optionMarkup[fieldType]?.(option)
     }
 
+    // a checkbox or radio group's class also lands on its label wrapper, after the wrapper's own classes (f-field)
+    if (attrs.className && ['checkbox', 'radio'].includes(fieldType)) {
+      elem.config = { ...elem.config, inputWrap: joinClassNames(elem.config?.inputWrap, attrs.className) }
+    }
+
     const mappedOptions = options.map(optionMap)
 
     if (withOther) {
diff --git a/src/lib/js/renderer/index.js b/src/lib/js/renderer/index.js
index c3d1dbea..38ac04d6 100644
--- a/src/lib/js/renderer/index.js
+++ b/src/lib/js/renderer/index.js
@@ -5,6 +5,7 @@ import dom, {
   OTHER_NAME_SUFFIX,
   REQUIRED_GROUP_ATTR,
 } from '../common/dom.js'
+import { labelWrapClassNames, resolveLabelPosition } from '../common/label-position.mjs'
 import { fetchDependencies } from '../common/loaders.js'
 import { cleanFormData, isAddress, merge, uuid } from '../common/utils/index.mjs'
 import { splitAddress } from '../common/utils/string.mjs'
@@ -48,6 +49,20 @@ const classNames = value => {
   return [resolved].flat(Infinity).filter(name => typeof name === 'string' && name.trim())
 }
 
+/**
+ * A field's config with its label wrapper's classes (#243): any `inputWrap`, then `f-field f-label-<position>`.
+ * dom.create only builds that wrapper when the label renders, so fields without one are unaffected.
+ * @param {Object} field processed field data
+ * @return {Object|undefined} config
+ */
+const fieldWrapConfig = field => {
+  if (!field.config) {
+    return field.config
+  }
+  const inputWrap = [...classNames(field.config.inputWrap), ...labelWrapClassNames(resolveLabelPosition(field))]
+  return { ...field.config, inputWrap: inputWrap.join(' ') }
+}
+
 /**
  * A row's or column's own attributes, ready to render (#112). `id` and `tag` are Formeo's: the element is found by
  * `#f-<id>` (conditions use it) and is always a div. Formeo's own class list (the component's top-level `className`),
@@ -599,7 +614,11 @@ export default class FormeoRenderer {
 
       const mergedFieldData = merge({ action }, field)
 
-      return this.cacheComponent({ ...mergedFieldData, id: this.prefixId(id) })
+      return this.cacheComponent({
+        ...mergedFieldData,
+        config: fieldWrapConfig(mergedFieldData),
+        id: this.prefixId(id),
+      })
     })
 
   get processedData() {
diff --git a/src/lib/js/renderer/label-position.test.js b/src/lib/js/renderer/label-position.test.js
new file mode 100644
index 00000000..88c116bc
--- /dev/null
+++ b/src/lib/js/renderer/label-position.test.js
@@ -0,0 +1,177 @@
+import assert from 'node:assert/strict'
+import { afterEach, beforeEach, describe, mock, test } from 'node:test'
+import { JSDOM } from 'jsdom'
+import FormeoRenderer from './index.js'
+
+const formWith = (fields, rowConfig = {}) => {
+  const ids = Object.keys(fields)
+  return {
+    id: 'label-position-form',
+    stages: { 'stage-1': { id: 'stage-1', children: ['row-1'] } },
+    rows: { 'row-1': { id: 'row-1', config: rowConfig, children: ids.map(id => `column-${id}`) } },
+    columns: Object.fromEntries(
+      ids.map(id => [`column-${id}`, { id: `column-${id}`, config: { width: '100%' }, children: [id] }])
+    ),
+    fields,
+  }
+}
+
+const textField = (id, config = {}, attrs = {}) => ({
+  id,
+  tag: 'input',
+  attrs: { type: 'text', ...attrs },
+  config: { label: 'Name', ...config },
+})
+
+const groupField = (id, type, config = {}, attrs = {}) => ({
+  id,
+  tag: 'input',
+  attrs: { type, ...attrs },
+  config: { label: 'Colour', ...config },
+  options: [
+    { label: 'Red', value: 'red' },
+    { label: 'Blue', value: 'blue' },
+  ],
+})
+
+const GLOBALS = ['document', 'window', 'Element', 'HTMLElement', 'HTMLFormElement', 'Node', 'FormData']
+
+describe('label position in the renderer (#243)', () => {
+  let window
+  let container
+  const nativeEvent = global.Event
+
+  beforeEach(() => {
+    const jsdom = new JSDOM('<!DOCTYPE html><html><body><div id="container"></div></body></html>', {
+      url: 'http://localhost',
+      pretendToBeVisual: true,
+    })
+    window = jsdom.window
+    global.document = window.document
+    global.window = window
+    global.Element = window.Element
+    global.HTMLElement = window.HTMLElement
+    global.HTMLFormElement = window.HTMLFormElement
+    global.Node = window.Node
+    global.FormData = window.FormData
+    global.Event = window.Event
+    container = window.document.getElementById('container')
+  })
+
+  afterEach(() => {
+    for (const key of GLOBALS) {
+      delete global[key]
+    }
+    global.Event = nativeEvent
+  })
+
+  const render = (fields, rowConfig) => {
+    const renderer = new FormeoRenderer({ renderContainer: container, formData: formWith(fields, rowConfig) })
+    renderer.render()
+    return renderer
+  }
+
+  /** The element that holds a field's label and control: the parent of its `#f-<id>` control */
+  const wrapperOf = id => container.querySelector(`#f-${id}`).parentElement
+  const tagsIn = elem => [...elem.children].map(child => child.tagName.toLowerCase())
+
+  describe('wrapper classes', () => {
+    for (const labelPosition of ['top', 'bottom', 'before', 'after']) {
+      test(`a ${labelPosition} label's wrapper is f-field f-label-${labelPosition}`, () => {
+        render({ name: textField('name', { labelPosition }) })
+        assert.deepEqual([...wrapperOf('name').classList], ['f-field', `f-label-${labelPosition}`])
+      })
+    }
+
+    test('label and control are in position order', () => {
+      render({ top: textField('top', { labelPosition: 'top' }), after: textField('after', { labelPosition: 'after' }) })
+      assert.deepEqual(tagsIn(wrapperOf('top')), ['label', 'input'])
+      assert.deepEqual(tagsIn(wrapperOf('after')), ['input', 'label'])
+    })
+
+    test('without labelPosition a text field is top and a lone checkbox is after', () => {
+      render({
+        name: textField('name'),
+        agree: { id: 'agree', tag: 'input', attrs: { type: 'checkbox' }, config: { label: 'I agree' } },
+      })
+      assert.ok(wrapperOf('name').classList.contains('f-label-top'))
+      assert.ok(wrapperOf('agree').classList.contains('f-label-after'))
+    })
+
+    test('legacy labelAfter on a text field renders as bottom', () => {
+      render({ name: textField('name', { labelAfter: true }) })
+      assert.ok(wrapperOf('name').classList.contains('f-label-bottom'))
+      assert.deepEqual(tagsIn(wrapperOf('name')), ['input', 'label'])
+    })
+
+    test('a configured inputWrap class stays on the wrapper', () => {
+      render({ name: textField('name', { inputWrap: 'my-wrap', labelPosition: 'before' }) })
+      assert.deepEqual([...wrapperOf('name').classList], ['my-wrap', 'f-field', 'f-label-before'])
+    })
+
+    test('a field whose label is hidden gets no wrapper, even with a labelPosition', () => {
+      render({
+        quiet: textField('quiet', { hideLabel: true, labelPosition: 'before' }),
+        secret: { id: 'secret', tag: 'input', attrs: { type: 'hidden' }, config: { label: 'S', hideLabel: true } },
+        heading: { id: 'heading', tag: 'h1', config: { label: 'H', hideLabel: true }, content: 'Heading' },
+      })
+      assert.equal(container.querySelectorAll('.f-field').length, 0)
+      assert.equal(wrapperOf('quiet').id, 'f-column-quiet', 'the bare input sits in its column')
+    })
+
+    test('an unknown labelPosition warns and renders as the default', () => {
+      const warn = mock.method(console, 'warn', () => {})
+      try {
+        render({ name: textField('name', { labelPosition: 'upside-down' }) })
+        assert.ok(wrapperOf('name').classList.contains('f-label-top'))
+        assert.ok(warn.mock.calls.some(({ arguments: [message] }) => message.includes('"upside-down"')))
+      } finally {
+        warn.mock.restore()
+      }
+    })
+
+    test('an input group clone of a positioned field keeps its wrapper classes', () => {
+      render({ name: textField('name', { labelPosition: 'before' }) }, { inputGroup: true })
+      container.querySelector('.add-input-group').click()
+      const wrappers = [...container.querySelectorAll('.f-field.f-label-before')]
+      assert.equal(wrappers.length, 2, 'original and clone')
+    })
+
+    test('a condition that hides a positioned field hides only its wrapper', () => {
+      const source = {
+        id: 'source',
+        tag: 'select',
+        attrs: {},
+        config: { label: 'Source' },
+        options: [
+          { label: 'A', value: 'a' },
+          { label: 'B', value: 'b' },
+        ],
+      }
+      const target = textField('target', { labelPosition: 'before' })
+      target.conditions = [
+        {
+          if: [
+            { source: 'fields.source', sourceProperty: 'value', comparison: 'equals', target: 'b', targetProperty: '' },
+          ],
+          then: [{ target: 'fields.target', targetProperty: 'isNotVisible', assignment: '', value: '' }],
+        },
+      ]
+      render({ source, target })
+      const select = container.querySelector('#f-source')
+      select.value = 'b'
+      select.dispatchEvent(new window.Event('change', { bubbles: true }))
+      assert.equal(wrapperOf('target').hasAttribute('hidden'), true)
+      assert.equal(container.querySelector('#f-column-target').hasAttribute('hidden'), false)
+    })
+  })
+
+  describe('group class names', () => {
+    test("a group's attrs.className lands on the group and on its wrapper, next to f-field", () => {
+      render({ colour: groupField('colour', 'radio', { labelPosition: 'before' }, { className: 'my-group' }) })
+      const group = container.querySelector('#f-colour')
+      assert.ok(group.classList.contains('my-group'))
+      assert.deepEqual([...group.parentElement.classList], ['f-field', 'f-label-before', 'my-group'])
+    })
+  })
+})

From 3682d3ce98f87b7880b938ae0c3d960ef514fe43 Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 12:27:37 +0100
Subject: [PATCH 03/19] fix(renderer): name checkbox and radio groups by their
 label with role=group

Refs #243
---
 src/lib/js/common/dom.js                   | 25 ++++++++--
 src/lib/js/renderer/label-position.test.js | 54 ++++++++++++++++++++++
 src/lib/js/renderer/option-groups.test.js  |  2 +-
 3 files changed, 77 insertions(+), 4 deletions(-)

diff --git a/src/lib/js/common/dom.js b/src/lib/js/common/dom.js
index 38419819..a5a0658f 100644
--- a/src/lib/js/common/dom.js
+++ b/src/lib/js/common/dom.js
@@ -247,6 +247,12 @@ class DOM {
         wrap.attrs = groupWrapperAttrs(groupAttrs)
         // config.required only drives the label's required mark; `required` itself lives on the option inputs
         wrap.config = { ...elem.config, required: Boolean(groupAttrs.required) }
+        const groupLabelId = this.groupLabelId(elem, isPreview)
+        if (groupLabelId) {
+          // the user's own role or aria-labelledby wins
+          wrap.attrs = { role: 'group', 'aria-labelledby': groupLabelId, ...wrap.attrs }
+          wrap.config.labelId = groupLabelId
+        }
         // which of the group's inputs are required or enabled depends on what is checked, so re-sync on change
         const groupSyncs = []
         if (!isPreview && groupAttrs.type === 'checkbox' && groupAttrs.required) {
@@ -829,6 +835,19 @@ class DOM {
     children: helpText,
   })
 
+  /**
+   * The id of a rendered checkbox or radio group's label, or null when no group label renders. A <label for> can't
+   * name a <div>, so the group gets role="group" and aria-labelledby this id instead (#243).
+   * @param  {Object}  elem      group config
+   * @param  {Boolean} isPreview editor preview
+   * @return {String|null}
+   */
+  groupLabelId(elem, isPreview) {
+    const { id, attrs = {}, config = {} } = elem
+    const isOptionGroup = attrs.type === 'checkbox' || attrs.type === 'radio'
+    return !isPreview && isOptionGroup && id && config.label && !config.hideLabel ? `${id}-label` : null
+  }
+
   /**
    * Generate a label
    * @param  {Object} elem config object
@@ -842,14 +861,14 @@ class DOM {
       config: { label: labelText = '', helpText = '', tooltip = null },
     } = elem
     const { id: elemId, attrs } = elem
+    const { labelId } = elem.config
     if (typeof labelText === 'function') {
       labelText = labelText()
     }
     const fieldLabel = {
       tag: 'label',
-      attrs: {
-        for: elemId || attrs?.id,
-      },
+      // a group's label names it through aria-labelledby; a control's label points at it with for
+      attrs: labelId ? { id: labelId } : { for: elemId || attrs?.id },
       className: [],
       children: [
         labelText,
diff --git a/src/lib/js/renderer/label-position.test.js b/src/lib/js/renderer/label-position.test.js
index 88c116bc..f6f0116f 100644
--- a/src/lib/js/renderer/label-position.test.js
+++ b/src/lib/js/renderer/label-position.test.js
@@ -174,4 +174,58 @@ describe('label position in the renderer (#243)', () => {
       assert.deepEqual([...group.parentElement.classList], ['f-field', 'f-label-before', 'my-group'])
     })
   })
+
+  describe('groups', () => {
+    test("a group's label names it: role=group and aria-labelledby, label with an id and no for", () => {
+      render({ colour: groupField('colour', 'radio') })
+      const group = container.querySelector('#f-colour')
+      const label = container.querySelector('#f-colour-label')
+      assert.equal(group.getAttribute('role'), 'group')
+      assert.equal(group.getAttribute('aria-labelledby'), 'f-colour-label')
+      assert.equal(label.tagName, 'LABEL')
+      assert.equal(label.hasAttribute('for'), false)
+      assert.equal(label.textContent, 'Colour')
+    })
+
+    test('a role or aria-labelledby set in attrs wins', () => {
+      render({ colour: groupField('colour', 'checkbox', {}, { role: 'radiogroup', 'aria-labelledby': 'mine' }) })
+      const group = container.querySelector('#f-colour')
+      assert.equal(group.getAttribute('role'), 'radiogroup')
+      assert.equal(group.getAttribute('aria-labelledby'), 'mine')
+    })
+
+    test('a group with a hidden label gets no role or label id', () => {
+      render({ colour: groupField('colour', 'checkbox', { hideLabel: true }) })
+      const group = container.querySelector('#f-colour')
+      assert.equal(group.hasAttribute('role'), false)
+      assert.equal(container.querySelector('#f-colour-label'), null)
+    })
+
+    test('labelPosition moves the group label; option labels stay after their inputs', () => {
+      render({ colour: groupField('colour', 'checkbox', { labelPosition: 'after' }) })
+      const wrapper = wrapperOf('colour')
+      assert.deepEqual(tagsIn(wrapper), ['div', 'label'])
+      assert.ok(wrapper.classList.contains('f-label-after'))
+      for (const option of container.querySelectorAll('#f-colour .f-checkbox')) {
+        assert.deepEqual(tagsIn(option), ['input', 'label'])
+      }
+    })
+
+    test('the Other choice keeps its own label and text box name', () => {
+      render({ colour: groupField('colour', 'radio', { other: true, labelPosition: 'before' }) })
+      const text = container.querySelector('#f-colour-other-value')
+      assert.equal(text.getAttribute('aria-labelledby'), 'f-colour-other-label')
+      assert.equal(container.querySelector('#f-colour-other-label').getAttribute('for'), 'f-colour-other')
+    })
+
+    test('an input group clone gets its own group label id', () => {
+      render({ colour: groupField('colour', 'radio') }, { inputGroup: true })
+      container.querySelector('.add-input-group').click()
+      const groups = [...container.querySelectorAll('[role="group"]')]
+      assert.equal(groups.length, 2)
+      const [original, clone] = groups.map(group => group.getAttribute('aria-labelledby'))
+      assert.notEqual(original, clone)
+      assert.ok(container.querySelector(`#${clone}`), "the clone's label id exists")
+    })
+  })
 })
diff --git a/src/lib/js/renderer/option-groups.test.js b/src/lib/js/renderer/option-groups.test.js
index 389fe2a1..4f570579 100644
--- a/src/lib/js/renderer/option-groups.test.js
+++ b/src/lib/js/renderer/option-groups.test.js
@@ -125,7 +125,7 @@ describe('checkbox and radio groups', () => {
         inputsOf('radio-1').map(input => input.required),
         [true, true]
       )
-      assert.ok(container.querySelector('label[for="f-radio-1"] .text-error'), 'group label has the * mark')
+      assert.ok(container.querySelector('#f-radio-1-label .text-error'), 'group label has the * mark')
     })
 
     test('a required radio group blocks submission until an option is chosen', () => {

From e9af548bbe2286050ba7ad1832c5f31a0f95ac73 Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 12:30:00 +0100
Subject: [PATCH 04/19] feat(editor): config panel dropdowns from an options
 list on a config declaration

Refs #243
---
 .../components/edit-panel/config-options.mjs  | 53 ++++++++++++++++---
 .../edit-panel/config-options.test.mjs        | 37 +++++++++++++
 .../components/edit-panel/edit-panel-item.mjs |  9 ++++
 .../components/edit-panel/edit-panel.test.js  | 37 +++++++++++++
 4 files changed, 128 insertions(+), 8 deletions(-)

diff --git a/src/lib/js/components/edit-panel/config-options.mjs b/src/lib/js/components/edit-panel/config-options.mjs
index ce1a14cd..fbf2c97c 100644
--- a/src/lib/js/components/edit-panel/config-options.mjs
+++ b/src/lib/js/components/edit-panel/config-options.mjs
@@ -1,14 +1,45 @@
+import i18n from '@draggable/i18n'
+import { toTitleCase } from '../../common/utils/string.mjs'
 import { labelHelper } from './helpers.mjs'
 
-// a Config panel item edits its value with a checkbox or a text input, so only these defaults can be declared
+// a Config panel item edits its value with a checkbox, a text input or (with options) a select
 const EDITABLE_DEFAULT_TYPES = new Set(['boolean', 'string', 'number'])
 const warnedKeys = new Set()
 
+const warnOnce = (key, problem) => {
+  if (!warnedKeys.has(key)) {
+    warnedKeys.add(key)
+    console.warn(`formeo: config option "${key}" ${problem}; it is ignored`)
+  }
+}
+
+/**
+ * A declaration's dropdown choices, labelled, or null when they can't be offered: they must be a non-empty list of
+ * string values that includes the default
+ * @param {String} key config key
+ * @param {Object} declaration
+ * @return {Array<{value: String, label: String}>|null}
+ */
+const declaredChoices = (key, { options, default: defaultValue }) => {
+  const usable =
+    Array.isArray(options) &&
+    options.length > 0 &&
+    options.every(option => typeof option?.value === 'string') &&
+    options.some(option => option.value === defaultValue)
+  if (!usable) {
+    return null
+  }
+  return options.map(({ value, label }) => ({
+    value,
+    label: label || i18n.get(`${key}.${value}`) || toTitleCase(value),
+  }))
+}
+
 /**
  * The config keys a component's Config panel offers: its resolved `panels.config.options` without the
- * `panels.config.disabled` ones. A declaration whose default the panel can't edit is dropped with a warning.
+ * `panels.config.disabled` ones. A declaration the panel can't edit is dropped with a warning.
  * @param {Object} [componentConfig] a component's resolved config (Component#config)
- * @return {Map<String, {label: String, default: boolean|string|number}>} the keys, in declaration order
+ * @return {Map<String, {label: String, default: boolean|string|number, options?: Array}>} the keys, in declaration order
  */
 export const configOptionsOf = componentConfig => {
   const { options = {}, disabled = [] } = componentConfig?.panels?.config || {}
@@ -18,13 +49,19 @@ export const configOptionsOf = componentConfig => {
       continue
     }
     if (!EDITABLE_DEFAULT_TYPES.has(typeof declaration?.default)) {
-      if (!warnedKeys.has(key)) {
-        warnedKeys.add(key)
-        console.warn(`formeo: config option "${key}" needs a boolean, string or number default; it is ignored`)
-      }
+      warnOnce(key, 'needs a boolean, string or number default')
       continue
     }
-    declared.set(key, { label: declaration.label || labelHelper(`config.${key}`), default: declaration.default })
+    const entry = { label: declaration.label || labelHelper(`config.${key}`), default: declaration.default }
+    if (declaration.options !== undefined) {
+      const choices = declaredChoices(key, declaration)
+      if (!choices) {
+        warnOnce(key, 'needs options with string values that include its default')
+        continue
+      }
+      entry.options = choices
+    }
+    declared.set(key, entry)
   }
   return declared
 }
diff --git a/src/lib/js/components/edit-panel/config-options.test.mjs b/src/lib/js/components/edit-panel/config-options.test.mjs
index 70d197a6..4dc9fb69 100644
--- a/src/lib/js/components/edit-panel/config-options.test.mjs
+++ b/src/lib/js/components/edit-panel/config-options.test.mjs
@@ -47,4 +47,41 @@ describe('configOptionsOf', () => {
       warn.mock.restore()
     }
   })
+
+  it('keeps declared options, labelling each one', () => {
+    const declared = configOptionsOf(
+      withOptions({
+        density: {
+          default: 'cosy',
+          options: [{ value: 'cosy' }, { value: 'compact', label: 'Tight' }],
+        },
+      })
+    )
+    assert.deepEqual(declared.get('density'), {
+      label: labelHelper('config.density'),
+      default: 'cosy',
+      options: [
+        { value: 'cosy', label: 'Cosy' },
+        { value: 'compact', label: 'Tight' },
+      ],
+    })
+  })
+
+  it('drops, and warns once about, options it cannot offer', () => {
+    const warn = mock.method(console, 'warn', () => {})
+    try {
+      const config = withOptions({
+        emptyChoice: { default: 'a', options: [] },
+        numberChoice: { default: 'a', options: [{ value: 1 }] },
+        missingDefault: { default: 'z', options: [{ value: 'a' }] },
+        notAList: { default: 'a', options: 'a,b' },
+      })
+      assert.equal(configOptionsOf(config).size, 0)
+      configOptionsOf(config)
+      assert.equal(warn.mock.callCount(), 4, 'one warning per bad key, not per call')
+      assert.match(warn.mock.calls[0].arguments[0], /^formeo: config option "emptyChoice" needs options/)
+    } finally {
+      warn.mock.restore()
+    }
+  })
 })
diff --git a/src/lib/js/components/edit-panel/edit-panel-item.mjs b/src/lib/js/components/edit-panel/edit-panel-item.mjs
index 4d3cb2c2..576bfe96 100644
--- a/src/lib/js/components/edit-panel/edit-panel-item.mjs
+++ b/src/lib/js/components/edit-panel/edit-panel-item.mjs
@@ -324,6 +324,15 @@ export default class EditPanelItem {
       }
     }
 
+    // a Config panel key declared with options is a dropdown (#243)
+    if (this.panelName === 'config') {
+      const choices = configOptionsOf(this.field.config).get(key.replace(/^config\./, ''))?.options
+      if (choices) {
+        effectiveValue = choices.map(choice => ({ ...choice, selected: choice.value === value }))
+        valType = 'array'
+      }
+    }
+
     const dataKey = panelDataKeyMap.get(this.panelName)?.({ itemKey: this.itemKey, key }) || this.itemKey
     const labelKey = dataKey.split('.').filter(Number.isNaN).join('.') || key
     const baseConfig = ITEM_INPUT_TYPE_MAP[valType]({ key, value: effectiveValue })
diff --git a/src/lib/js/components/edit-panel/edit-panel.test.js b/src/lib/js/components/edit-panel/edit-panel.test.js
index efc79e9c..09c2e395 100644
--- a/src/lib/js/components/edit-panel/edit-panel.test.js
+++ b/src/lib/js/components/edit-panel/edit-panel.test.js
@@ -260,6 +260,43 @@ describe('Config panel declarations', () => {
     assert.deepEqual(panelKeys(field), ['config.label', 'config.hint'])
   })
 
+  const densityConfig = {
+    fields: {
+      all: {
+        panels: {
+          config: {
+            options: {
+              density: { default: 'cosy', options: [{ value: 'cosy' }, { value: 'compact' }] },
+            },
+          },
+        },
+      },
+    },
+  }
+
+  it('renders a key declared with options as a select with its value selected', () => {
+    const field = textField(editorWith(densityConfig), { density: 'compact' })
+    const select = field.editPanels.get('config').props.querySelector('select.config-density')
+    assert.ok(select, 'a select, not a text input')
+    assert.deepEqual(
+      [...select.options].map(option => [option.value, option.textContent]),
+      [
+        ['cosy', 'Cosy'],
+        ['compact', 'Compact'],
+      ]
+    )
+    assert.equal(select.value, 'compact')
+  })
+
+  it('writes the chosen option to the field', () => {
+    const field = textField(editorWith(densityConfig), { density: 'cosy' })
+    mock.method(field, 'debouncedUpdatePreview', () => {})
+    const select = field.editPanels.get('config').props.querySelector('select.config-density')
+    select.value = 'compact'
+    select.dispatchEvent(new window.Event('change', { bubbles: true }))
+    assert.equal(field.get('config.density'), 'compact')
+  })
+
   it('a stage has no Config panel without pages', () => {
     const stage = editorWith().stages.get('s-1')
     assert.equal(stage.editPanels.has('config'), false)

From 5f75b1176f3f75c7317abdf512a65765b05c6f44 Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 12:32:45 +0100
Subject: [PATCH 05/19] feat(editor): offer Label Position in the Config panel
 and convert labelAfter on load

Refs #243
---
 .../controls/control-config-options.test.js   |  2 +-
 .../components/edit-panel/edit-panel.test.js  | 12 +--
 .../fields/field-label-position.test.js       | 84 +++++++++++++++++++
 src/lib/js/components/fields/field.js         | 14 ++++
 src/lib/js/components/fields/index.js         |  4 +-
 tests/add-configuration.spec.js               | 20 ++---
 6 files changed, 118 insertions(+), 18 deletions(-)
 create mode 100644 src/lib/js/components/fields/field-label-position.test.js

diff --git a/src/lib/js/components/controls/control-config-options.test.js b/src/lib/js/components/controls/control-config-options.test.js
index 1fafb15f..e873d8c3 100644
--- a/src/lib/js/components/controls/control-config-options.test.js
+++ b/src/lib/js/components/controls/control-config-options.test.js
@@ -55,7 +55,7 @@ describe('control configOptions', () => {
     assert.deepEqual(panelKeys(other), ['config.label'])
     assert.deepEqual(
       [...configOptionsOf(other.config).keys()],
-      ['label', 'hideLabel', 'helpText', 'labelAfter', 'disableHtmlLabel', 'tooltip']
+      ['label', 'hideLabel', 'helpText', 'labelPosition', 'disableHtmlLabel', 'tooltip']
     )
   })
 
diff --git a/src/lib/js/components/edit-panel/edit-panel.test.js b/src/lib/js/components/edit-panel/edit-panel.test.js
index 09c2e395..5f3290ac 100644
--- a/src/lib/js/components/edit-panel/edit-panel.test.js
+++ b/src/lib/js/components/edit-panel/edit-panel.test.js
@@ -326,7 +326,7 @@ describe('Config panel "Add config"', () => {
   it('offers the declared keys not set yet, with their labels', () => {
     const panel = textField(editorWith()).editPanels.get('config')
     const addable = panel.addableConfigOptions()
-    assert.deepEqual([...addable.keys()], ['hideLabel', 'helpText', 'labelAfter', 'disableHtmlLabel', 'tooltip'])
+    assert.deepEqual([...addable.keys()], ['hideLabel', 'helpText', 'labelPosition', 'disableHtmlLabel', 'tooltip'])
     assert.equal(addable.get('tooltip').label, labelHelper('config.tooltip'))
   })
 
@@ -338,10 +338,10 @@ describe('Config panel "Add config"', () => {
   it('adds a key with its declared default, once', () => {
     const field = textField(editorWith())
     const panel = field.editPanels.get('config')
-    panel.addConfigItem('labelAfter')
-    panel.addConfigItem('labelAfter')
-    assert.equal(field.get('config.labelAfter'), false)
-    const items = panel.editPanelItems.filter(({ itemKey }) => itemKey === 'config.labelAfter')
+    panel.addConfigItem('labelPosition')
+    panel.addConfigItem('labelPosition')
+    assert.equal(field.get('config.labelPosition'), 'top')
+    const items = panel.editPanelItems.filter(({ itemKey }) => itemKey === 'config.labelPosition')
     assert.equal(items.length, 1)
     assert.ok(panel.props.contains(items[0].dom))
   })
@@ -365,7 +365,7 @@ describe('Config panel "Add config"', () => {
     const field = textField(editorWith(), {
       hideLabel: false,
       helpText: '',
-      labelAfter: false,
+      labelPosition: 'top',
       disableHtmlLabel: false,
       tooltip: '',
     })
diff --git a/src/lib/js/components/fields/field-label-position.test.js b/src/lib/js/components/fields/field-label-position.test.js
new file mode 100644
index 00000000..973032d9
--- /dev/null
+++ b/src/lib/js/components/fields/field-label-position.test.js
@@ -0,0 +1,84 @@
+import assert from 'node:assert/strict'
+import { describe, it, mock } from 'node:test'
+import { Actions } from '../../common/actions.js'
+import { Events } from '../../common/events.js'
+import { Components } from '../index.js'
+import Field from './field.js'
+
+// an editor's Components loaded with one empty stage
+const editor = () => {
+  const events = new Events().init({})
+  const editorComponents = new Components({ events, actions: new Actions(events).init({}) })
+  editorComponents.load({ id: 'form-lp', stages: { 's-1': { id: 's-1', config: {}, children: [] } } })
+  return editorComponents
+}
+
+const textField = (editorComponents, config = {}) =>
+  new Field(
+    {
+      id: 'f-lp',
+      tag: 'input',
+      attrs: { type: 'text' },
+      config: { label: 'Name', controlId: 'text-input', ...config },
+    },
+    editorComponents
+  )
+
+describe('Field label position data (#243)', () => {
+  it('converts legacy labelAfter to labelPosition on load', () => {
+    const field = textField(editor(), { labelAfter: true })
+    assert.equal(field.get('config.labelPosition'), 'bottom')
+    assert.equal('labelAfter' in field.get('config'), false)
+  })
+
+  it('maps labelAfter: false on a lone checkbox to before', () => {
+    const field = new Field(
+      { id: 'f-cb', tag: 'input', attrs: { type: 'checkbox' }, config: { label: 'Agree', labelAfter: false } },
+      editor()
+    )
+    assert.equal(field.get('config.labelPosition'), 'before')
+  })
+
+  it('keeps labelPosition when both are set, and drops labelAfter', () => {
+    const field = textField(editor(), { labelPosition: 'before', labelAfter: true })
+    assert.equal(field.get('config.labelPosition'), 'before')
+    assert.equal('labelAfter' in field.get('config'), false)
+  })
+
+  it('rewrites an unknown labelPosition to the resolved one', () => {
+    const warn = mock.method(console, 'warn', () => {})
+    try {
+      const field = textField(editor(), { labelPosition: 'left' })
+      assert.equal(field.get('config.labelPosition'), 'top')
+    } finally {
+      warn.mock.restore()
+    }
+  })
+
+  it('leaves the data it was given, such as a control definition, untouched', () => {
+    const definitionConfig = { label: 'Name', controlId: 'text-input', labelAfter: true }
+    new Field({ id: 'f-def', tag: 'input', attrs: { type: 'text' }, config: definitionConfig }, editor())
+    assert.deepEqual(definitionConfig, { label: 'Name', controlId: 'text-input', labelAfter: true })
+  })
+
+  it('fires no update events for the conversion', () => {
+    const editorComponents = editor()
+    const formeoUpdated = mock.method(editorComponents.events, 'formeoUpdated')
+    textField(editorComponents, { labelAfter: true })
+    const labelChanges = formeoUpdated.mock.calls.filter(({ arguments: [evt] }) =>
+      /label(Position|After)/.test(evt?.changePath || '')
+    )
+    assert.equal(labelChanges.length, 0)
+  })
+
+  it('shows the converted value in a Label Position dropdown', () => {
+    const field = textField(editor(), { labelAfter: true })
+    const select = field.editPanels.get('config').props.querySelector('select.config-labelPosition')
+    assert.ok(select)
+    assert.deepEqual(
+      [...select.options].map(option => option.value),
+      ['top', 'bottom', 'before', 'after']
+    )
+    assert.equal(select.value, 'bottom')
+  })
+})
diff --git a/src/lib/js/components/fields/field.js b/src/lib/js/components/fields/field.js
index 8fe11e21..ea221739 100644
--- a/src/lib/js/components/fields/field.js
+++ b/src/lib/js/components/fields/field.js
@@ -1,6 +1,7 @@
 import i18n from '@draggable/i18n'
 import dom from '../../common/dom.js'
 import { indexOfNode } from '../../common/helpers.mjs'
+import { normalizeLabelConfig } from '../../common/label-position.mjs'
 import { clone, debounce } from '../../common/utils/index.mjs'
 import { FIELD_CLASSNAME } from '../../constants.js'
 import Component from '../component.js'
@@ -21,6 +22,7 @@ export default class Field extends Component {
   constructor(fieldData = Object.create(null), components) {
     super('field', fieldData, components)
 
+    this.normalizeLabelConfig()
     this.controlId = this.get('config.controlId') || this.get('meta.id')
     this.applyControlAttrConfig()
 
@@ -66,6 +68,18 @@ export default class Field extends Component {
    * panels.attrs config. Reads both the registered control definition and the field's own
    * saved config so forms saved before a control changed still pick up its rules.
    */
+  /**
+   * Converts legacy config.labelAfter, and an unknown config.labelPosition, to the labelPosition it resolves to (#243).
+   * Replaces the config object instead of calling set(), so loading a form fires no update events and the data it was
+   * given (a saved form, a control definition) is never mutated.
+   */
+  normalizeLabelConfig() {
+    const config = normalizeLabelConfig(this.data)
+    if (config !== this.data.config) {
+      this.data.config = config
+    }
+  }
+
   applyControlAttrConfig() {
     const controlConfig = getControlConfig(this.components.controls?.get(this.controlId))
     const attrConfig = controlAttrPanelConfig(controlConfig, this.get('config'))
diff --git a/src/lib/js/components/fields/index.js b/src/lib/js/components/fields/index.js
index aaa9d1eb..85c2e67b 100644
--- a/src/lib/js/components/fields/index.js
+++ b/src/lib/js/components/fields/index.js
@@ -1,3 +1,4 @@
+import { LABEL_POSITIONS } from '../../common/label-position.mjs'
 import { parseData } from '../../common/utils/index.mjs'
 import { get, set } from '../../common/utils/object.mjs'
 import ComponentData from '../component-data.js'
@@ -22,7 +23,8 @@ const DEFAULT_CONFIG = () => ({
         label: { default: 'New Field' },
         hideLabel: { default: false },
         helpText: { default: '' },
-        labelAfter: { default: false },
+        // where the label sits; replaces labelAfter, which the editor converts on load (#243)
+        labelPosition: { default: 'top', options: LABEL_POSITIONS.map(value => ({ value })) },
         disableHtmlLabel: { default: false },
         tooltip: { default: '' },
       },
diff --git a/tests/add-configuration.spec.js b/tests/add-configuration.spec.js
index 93b92764..d01020cf 100644
--- a/tests/add-configuration.spec.js
+++ b/tests/add-configuration.spec.js
@@ -82,7 +82,7 @@ test.describe('Add Configuration to Field', () => {
     expect(configItemsAfter).toBeGreaterThan(configItemsBefore)
   })
 
-  test('should add labelAfter configuration to field', async ({ page }) => {
+  test('should add labelPosition configuration to field', async ({ page }) => {
     // Add an email field (different field type to verify it works across controls)
     await page.getByRole('button', { name: 'Email' }).click()
     await page.waitForTimeout(300)
@@ -105,8 +105,8 @@ test.describe('Add Configuration to Field', () => {
     const dialog = page.locator('.formeo-dialog.config-item-dialog')
     await expect(dialog).toBeVisible()
 
-    // Select labelAfter option
-    await dialog.locator('select.config-key-select').selectOption('labelAfter')
+    // Select labelPosition option
+    await dialog.locator('select.config-key-select').selectOption('labelPosition')
 
     // Click submit
     await dialog.locator('button[type="submit"]').click()
@@ -114,10 +114,10 @@ test.describe('Add Configuration to Field', () => {
     // Wait for dialog to close
     await expect(dialog).not.toBeVisible()
 
-    // Verify labelAfter config item exists in the panel
+    // Verify the labelPosition config item exists in the panel, with its default
     await page.waitForTimeout(200)
-    const labelAfterItem = page.locator('.config-panel').getByText('Label After')
-    await expect(labelAfterItem).toBeVisible()
+    const labelPositionItem = page.locator('.config-panel select.config-labelPosition')
+    await expect(labelPositionItem).toHaveValue('top')
   })
 
   test('should filter out already existing config options', async ({ page }) => {
@@ -153,8 +153,8 @@ test.describe('Add Configuration to Field', () => {
     expect(optionValues).not.toContain('label')
     expect(optionValues).not.toContain('hideLabel')
 
-    // But labelAfter, tooltip, disableHtmlLabel should still be available
-    expect(optionValues).toContain('labelAfter')
+    // But labelPosition, tooltip, disableHtmlLabel should still be available
+    expect(optionValues).toContain('labelPosition')
     expect(optionValues).toContain('tooltip')
     expect(optionValues).toContain('disableHtmlLabel')
 
@@ -233,11 +233,11 @@ test.describe('Add Configuration to Field', () => {
     await expect(dialog).not.toBeVisible()
     await page.waitForTimeout(200)
 
-    // Add second config item (labelAfter)
+    // Add second config item (labelPosition)
     await editPanel.locator('.add-config').click()
     dialog = page.locator('.formeo-dialog.config-item-dialog')
     await expect(dialog).toBeVisible()
-    await dialog.locator('select.config-key-select').selectOption('labelAfter')
+    await dialog.locator('select.config-key-select').selectOption('labelPosition')
     await dialog.locator('button[type="submit"]').click()
     await expect(dialog).not.toBeVisible()
     await page.waitForTimeout(200)

From ae517ae29beba303146f2b6976a5763312ca2379 Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 12:34:58 +0100
Subject: [PATCH 06/19] fix(editor): keep each field method's docblock and test
 an empty config

Refs #243
---
 .../fields/field-label-position.test.js          |  5 +++++
 src/lib/js/components/fields/field.js            | 16 ++++++++--------
 2 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/src/lib/js/components/fields/field-label-position.test.js b/src/lib/js/components/fields/field-label-position.test.js
index 973032d9..97337a0a 100644
--- a/src/lib/js/components/fields/field-label-position.test.js
+++ b/src/lib/js/components/fields/field-label-position.test.js
@@ -71,6 +71,11 @@ describe('Field label position data (#243)', () => {
     assert.equal(labelChanges.length, 0)
   })
 
+  it('constructs a field with an empty config, without writing labelPosition', () => {
+    const field = new Field({ id: 'f-hr', tag: 'hr', config: {} }, editor())
+    assert.equal(field.get('config.labelPosition'), undefined)
+  })
+
   it('shows the converted value in a Label Position dropdown', () => {
     const field = textField(editor(), { labelAfter: true })
     const select = field.editPanels.get('config').props.querySelector('select.config-labelPosition')
diff --git a/src/lib/js/components/fields/field.js b/src/lib/js/components/fields/field.js
index ea221739..7013d3eb 100644
--- a/src/lib/js/components/fields/field.js
+++ b/src/lib/js/components/fields/field.js
@@ -68,6 +68,14 @@ export default class Field extends Component {
    * panels.attrs config. Reads both the registered control definition and the field's own
    * saved config so forms saved before a control changed still pick up its rules.
    */
+  applyControlAttrConfig() {
+    const controlConfig = getControlConfig(this.components.controls?.get(this.controlId))
+    const attrConfig = controlAttrPanelConfig(controlConfig, this.get('config'))
+    if (attrConfig) {
+      this.config = { [this.id]: attrConfig }
+    }
+  }
+
   /**
    * Converts legacy config.labelAfter, and an unknown config.labelPosition, to the labelPosition it resolves to (#243).
    * Replaces the config object instead of calling set(), so loading a form fires no update events and the data it was
@@ -80,14 +88,6 @@ export default class Field extends Component {
     }
   }
 
-  applyControlAttrConfig() {
-    const controlConfig = getControlConfig(this.components.controls?.get(this.controlId))
-    const attrConfig = controlAttrPanelConfig(controlConfig, this.get('config'))
-    if (attrConfig) {
-      this.config = { [this.id]: attrConfig }
-    }
-  }
-
   get labelConfig() {
     const hideLabel = !!this.get('config.hideLabel')
 

From 7a130f23930002bd9e219ccc3c0681e24d2ad5c5 Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 12:37:46 +0100
Subject: [PATCH 07/19] feat(editor): wrap a field's label and preview in
 f-field, in label-position order

Refs #243
---
 .../fields/field-label-position.test.js       | 46 +++++++++++++++++
 src/lib/js/components/fields/field.js         | 49 ++++++++++---------
 src/lib/sass/__fixtures__/formeo-baseline.css |  3 +-
 src/lib/sass/components/_group-actions.scss   |  3 +-
 4 files changed, 75 insertions(+), 26 deletions(-)

diff --git a/src/lib/js/components/fields/field-label-position.test.js b/src/lib/js/components/fields/field-label-position.test.js
index 97337a0a..04800924 100644
--- a/src/lib/js/components/fields/field-label-position.test.js
+++ b/src/lib/js/components/fields/field-label-position.test.js
@@ -87,3 +87,49 @@ describe('Field label position data (#243)', () => {
     assert.equal(select.value, 'bottom')
   })
 })
+
+describe('Field preview wrapper (#243)', () => {
+  const wrapOf = field => field.dom.querySelector(':scope > .f-field')
+  const partsOf = field => [...wrapOf(field).children].map(child => child.className)
+
+  it('wraps the label and preview in f-field f-label-<position>, in position order', () => {
+    const top = textField(editor())
+    assert.equal(wrapOf(top).className, 'f-field f-label-top')
+    assert.deepEqual(partsOf(top), ['prev-label', 'field-preview'])
+
+    const after = textField(editor(), { labelPosition: 'after' })
+    assert.equal(wrapOf(after).className, 'f-field f-label-after')
+    assert.deepEqual(partsOf(after), ['field-preview', 'prev-label'])
+  })
+
+  it('renders legacy labelAfter after the preview on first render', () => {
+    const field = textField(editor(), { labelAfter: true })
+    assert.deepEqual(partsOf(field), ['field-preview', 'prev-label'])
+  })
+
+  it('puts the edit window after the wrapper', () => {
+    const field = textField(editor())
+    const children = [...field.dom.children]
+    assert.ok(children.indexOf(wrapOf(field)) < children.indexOf(field.dom.querySelector('.field-edit')))
+  })
+
+  it('moves the label and swaps the class when labelPosition changes', () => {
+    const field = textField(editor())
+    field.set('config.labelPosition', 'before')
+    field.updatePreview()
+    assert.equal(wrapOf(field).className, 'f-field f-label-before')
+    field.set('config.labelPosition', 'bottom')
+    field.updatePreview()
+    assert.deepEqual(partsOf(field), ['field-preview', 'prev-label'])
+  })
+
+  it('keeps the wrapper with only the preview while the label is hidden, and brings the label back', () => {
+    const field = textField(editor(), { labelPosition: 'after' })
+    field.set('config.hideLabel', true)
+    assert.doesNotThrow(() => field.updatePreview())
+    assert.deepEqual(partsOf(field), ['field-preview'])
+    field.set('config.hideLabel', false)
+    field.updatePreview()
+    assert.deepEqual(partsOf(field), ['field-preview', 'prev-label'])
+  })
+})
diff --git a/src/lib/js/components/fields/field.js b/src/lib/js/components/fields/field.js
index 7013d3eb..9ab250f7 100644
--- a/src/lib/js/components/fields/field.js
+++ b/src/lib/js/components/fields/field.js
@@ -1,7 +1,13 @@
 import i18n from '@draggable/i18n'
 import dom from '../../common/dom.js'
 import { indexOfNode } from '../../common/helpers.mjs'
-import { normalizeLabelConfig } from '../../common/label-position.mjs'
+import {
+  FIELD_WRAP_CLASSNAME,
+  isLabelAfter,
+  labelWrapClassNames,
+  normalizeLabelConfig,
+  resolveLabelPosition,
+} from '../../common/label-position.mjs'
 import { clone, debounce } from '../../common/utils/index.mjs'
 import { FIELD_CLASSNAME } from '../../constants.js'
 import Component from '../component.js'
@@ -33,6 +39,9 @@ export default class Field extends Component {
 
     this.preview = this.fieldPreview()
 
+    this.labelWrap = dom.create({ className: FIELD_WRAP_CLASSNAME })
+    this.syncLabelWrap()
+
     const actionButtons = this.getActionButtons()
     const hasEditButton = this.actionButtons.some(child => child.meta?.id === 'edit')
 
@@ -45,11 +54,10 @@ export default class Field extends Component {
       },
       id: this.id,
       children: [
-        this.label,
         this.getComponentTag(),
         actionButtons,
+        this.labelWrap, // label and preview, in label-position order (#243)
         hasEditButton && this.editWindow, // fieldEdit window,
-        this.preview,
       ].filter(Boolean),
       panelNav: this.panelNav,
       dataset: {
@@ -154,35 +162,32 @@ export default class Field extends Component {
   }
 
   /**
-   * Update the label dom when label data changes
+   * Puts the label and preview into the field wrapper in label-position order, with the matching classes (#243)
    */
-  updateLabel() {
-    const newLabel = dom.create(this.labelConfig)
-
-    if (this.label || !newLabel) {
-      this.label.remove()
-    }
-
-    if (newLabel) {
-      if (this.data.config?.labelAfter) {
-        this.dom.append(newLabel)
-      } else {
-        this.dom.prepend(newLabel)
-      }
+  syncLabelWrap() {
+    const position = resolveLabelPosition(this.data)
+    const children = [this.label, this.preview].filter(Boolean)
+    if (isLabelAfter(position)) {
+      children.reverse()
     }
+    this.labelWrap.className = labelWrapClassNames(position).join(' ')
+    this.labelWrap.replaceChildren(...children)
+  }
 
-    this.label = newLabel
+  /**
+   * Rebuilds the label from the field's data
+   */
+  updateLabel() {
+    this.label = dom.create(this.labelConfig)
+    this.syncLabelWrap()
   }
 
   /**
    * Updates a field's preview
-   * @return {Object} fresh preview
    */
   updatePreview = () => {
+    this.preview = this.fieldPreview()
     this.updateLabel()
-    const newPreview = this.fieldPreview()
-    this.preview.replaceWith(newPreview)
-    this.preview = newPreview
   }
 
   get defaultPreviewActions() {
diff --git a/src/lib/sass/__fixtures__/formeo-baseline.css b/src/lib/sass/__fixtures__/formeo-baseline.css
index 8b6950bc..6fc182a7 100644
--- a/src/lib/sass/__fixtures__/formeo-baseline.css
+++ b/src/lib/sass/__fixtures__/formeo-baseline.css
@@ -812,8 +812,7 @@ button[class*=-clone]:hover .svg-icon {
   display: none;
 }
 .formeo.formeo-editor .hovering > .children,
-.formeo.formeo-editor .hovering > .field-preview,
-.formeo.formeo-editor .hovering > .prev-label {
+.formeo.formeo-editor .hovering > .f-field {
   opacity: 0.65;
 }
 .formeo.formeo-editor .hovering .group-actions .f-i-handle {
diff --git a/src/lib/sass/components/_group-actions.scss b/src/lib/sass/components/_group-actions.scss
index 693c4333..19e2969e 100644
--- a/src/lib/sass/components/_group-actions.scss
+++ b/src/lib/sass/components/_group-actions.scss
@@ -83,8 +83,7 @@
 
 .hovering {
   > .children,
-  > .field-preview,
-  > .prev-label {
+  > .f-field {
     opacity: 0.65;
   }
 

From eeded7e0743d903c81fbc77390e774c891957347 Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 12:40:07 +0100
Subject: [PATCH 08/19] feat(styles): lay out before/after labels beside their
 control and stack them when narrow

Refs #243
---
 src/lib/sass/__fixtures__/formeo-baseline.css | 26 +++++++++++++
 src/lib/sass/base/_bs.scss                    | 39 +++++++++++++++++++
 src/lib/sass/base/_properties.scss            |  3 ++
 src/lib/sass/css-properties.test.mjs          | 10 +++++
 4 files changed, 78 insertions(+)

diff --git a/src/lib/sass/__fixtures__/formeo-baseline.css b/src/lib/sass/__fixtures__/formeo-baseline.css
index 6fc182a7..49ed5f7a 100644
--- a/src/lib/sass/__fixtures__/formeo-baseline.css
+++ b/src/lib/sass/__fixtures__/formeo-baseline.css
@@ -428,6 +428,32 @@ button[class*=-clone]:hover .svg-icon {
 .formeo .f-field-group button {
   margin-right: 4px;
 }
+.formeo .f-field.f-label-before, .formeo .f-field.f-label-after {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  gap: 4px 8px;
+}
+.formeo .f-field.f-label-before > label,
+.formeo .f-field.f-label-before > .prev-label, .formeo .f-field.f-label-after > label,
+.formeo .f-field.f-label-after > .prev-label {
+  flex: 1 1 10rem;
+}
+.formeo .f-field.f-label-before > :not(label, .prev-label), .formeo .f-field.f-label-after > :not(label, .prev-label) {
+  flex: 999 1 0;
+  min-inline-size: 50%;
+}
+.formeo .f-field.f-label-before > input:is([type=checkbox], [type=radio]),
+.formeo .f-field.f-label-before > .field-preview:has(> input:is([type=checkbox], [type=radio])), .formeo .f-field.f-label-after > input:is([type=checkbox], [type=radio]),
+.formeo .f-field.f-label-after > .field-preview:has(> input:is([type=checkbox], [type=radio])) {
+  flex: 0 0 auto;
+  min-inline-size: auto;
+}
+.formeo .f-field.f-label-top > label,
+.formeo .f-field.f-label-top > .prev-label, .formeo .f-field.f-label-bottom > label,
+.formeo .f-field.f-label-bottom > .prev-label {
+  display: block;
+}
 .formeo select {
   font-size: 100%;
   font-family: inherit;
diff --git a/src/lib/sass/base/_bs.scss b/src/lib/sass/base/_bs.scss
index a4b61602..407cd83a 100644
--- a/src/lib/sass/base/_bs.scss
+++ b/src/lib/sass/base/_bs.scss
@@ -36,6 +36,45 @@ hr {
   }
 }
 
+// label position (#243). .f-field wraps a rendered field's label and control, and the editor's label and preview.
+// DOM order is the visual order, so nothing here reorders.
+.f-field {
+  &.f-label-before,
+  &.f-label-after {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: baseline;
+    gap: var.$half-space mixins.space(1);
+
+    // the label keeps --formeo-label-width and the control takes the rest, until the control would drop below half
+    // the row: then both wrap to full width, so a narrow column or viewport stacks them
+    > label,
+    > .prev-label {
+      flex: 1 1 var(--formeo-label-width);
+    }
+
+    > :not(label, .prev-label) {
+      flex: 999 1 0;
+      min-inline-size: 50%;
+    }
+
+    // a lone checkbox or radio keeps its own size next to its label
+    > input:is([type='checkbox'], [type='radio']),
+    > .field-preview:has(> input:is([type='checkbox'], [type='radio'])) {
+      flex: 0 0 auto;
+      min-inline-size: auto;
+    }
+  }
+
+  &.f-label-top,
+  &.f-label-bottom {
+    > label,
+    > .prev-label {
+      display: block;
+    }
+  }
+}
+
 select {
   @include mixins.input-style;
 
diff --git a/src/lib/sass/base/_properties.scss b/src/lib/sass/base/_properties.scss
index dce7b69a..45665fc1 100644
--- a/src/lib/sass/base/_properties.scss
+++ b/src/lib/sass/base/_properties.scss
@@ -43,6 +43,9 @@ $_structural: (
   --formeo-remove-bg: #{c.$remove-bg};
   --formeo-column-outline-soft: #{sass-color.adjust(c.$column-outline-color, $lightness: 15%)};
 
+  // layout: the label's width when it sits beside its control (labelPosition before / after)
+  --formeo-label-width: 10rem;
+
   @each $name, $values in $_structural {
     --formeo-#{$name}-outline: #{list.nth($values, 1)};
     --formeo-#{$name}-outline-text: #{list.nth($values, 2)};
diff --git a/src/lib/sass/css-properties.test.mjs b/src/lib/sass/css-properties.test.mjs
index 978343b1..bf102bd2 100644
--- a/src/lib/sass/css-properties.test.mjs
+++ b/src/lib/sass/css-properties.test.mjs
@@ -34,6 +34,7 @@ const EXPECTED = [
   'info',
   'remove-bg',
   'column-outline-soft',
+  'label-width',
   ...['stage', 'row', 'column', 'field', 'option'].flatMap(s => [
     `${s}-outline`,
     `${s}-outline-text`,
@@ -180,6 +181,15 @@ suite('resolveFormeoProperties purity', () => {
       /:where\(\.formeo-dark\) may only declare .*found: background: black/
     )
   })
+
+  test('side-by-side label positions wrap instead of reordering, and use --formeo-label-width (#243)', t => {
+    const compiled = compileFormeoCss()
+    const sideBySide = compiledRule('.formeo .f-field.f-label-before,')
+    t.assert.match(sideBySide, /display: flex;/)
+    t.assert.match(sideBySide, /flex-wrap: wrap;/)
+    t.assert.match(compiled, /flex: 1 1 var\(--formeo-label-width\);/)
+    t.assert.doesNotMatch(compiled, /\.f-field[^{]*\{[^}]*(?:\border:|flex-direction: \w+-reverse)/)
+  })
 })
 
 /** The single compiled rule starting with `start`, trimmed. */

From 8f5e7fedd5b0035f111e016b0af06d299a6ce9a5 Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 12:42:51 +0100
Subject: [PATCH 09/19] feat(types): labelPosition in the formData schema and
 type definitions

Refs #243
---
 src/lib/js/formdata-schema.test.mjs | 20 ++++++++++++++++++++
 src/types/formeo.d.ts               | 14 ++++++++++++++
 src/types/formeo.test-d.ts          | 14 ++++++++++++++
 tools/formdata-schema.mjs           |  8 ++++++++
 4 files changed, 56 insertions(+)

diff --git a/src/lib/js/formdata-schema.test.mjs b/src/lib/js/formdata-schema.test.mjs
index a0d96d17..1b8d6b56 100644
--- a/src/lib/js/formdata-schema.test.mjs
+++ b/src/lib/js/formdata-schema.test.mjs
@@ -24,6 +24,26 @@ suite('formData schema', () => {
     t.assert.ok(result.success, JSON.stringify(result.error?.issues))
   })
 
+  test('accepts a field labelPosition and legacy labelAfter, and rejects other positions (#243)', t => {
+    const data = structuredClone(conditionalFields)
+    const [fieldId] = Object.keys(data.fields)
+    const withConfig = config => {
+      data.fields[fieldId].config = { label: 'Name', ...config }
+      return formDataSchema.safeParse(data).success
+    }
+    for (const labelPosition of ['top', 'bottom', 'before', 'after']) {
+      t.assert.ok(withConfig({ labelPosition }), labelPosition)
+    }
+    t.assert.strictEqual(withConfig({ labelPosition: 'left' }), false)
+    t.assert.ok(withConfig({ labelAfter: true }))
+    t.assert.strictEqual(withConfig({ labelAfter: 'yes' }), false)
+  })
+
+  test('the generated JSON schema lists the label positions (#243)', t => {
+    const config = buildFormDataJsonSchema().properties.fields.additionalProperties.properties.config
+    t.assert.deepStrictEqual(config.properties.labelPosition.enum, ['top', 'bottom', 'before', 'after'])
+  })
+
   test('accepts the logical operator between if clauses and rejects unknown ones', t => {
     t.assert.ok(formDataSchema.safeParse(withSecondClause('&&')).success)
     t.assert.ok(formDataSchema.safeParse(withSecondClause('||')).success)
diff --git a/src/types/formeo.d.ts b/src/types/formeo.d.ts
index 14e2381c..96e9855e 100644
--- a/src/types/formeo.d.ts
+++ b/src/types/formeo.d.ts
@@ -23,6 +23,9 @@ export type ComponentType = 'stage' | 'row' | 'column' | 'field'
  * the symbols; the renderer also accepts the words. `&&` binds tighter than `||`.
  */
 export type LogicalOperator = '&&' | '||' | 'and' | 'or'
+
+/** Where a field's label sits: `top`/`bottom` stack, `before`/`after` sit beside the control (mirrored in RTL). */
+export type LabelPosition = 'top' | 'bottom' | 'before' | 'after'
 /** Symbols are what the editor stores; the renderer also accepts the names. */
 export type ComparisonOperator = '==' | '!=' | '⊃' | '!⊃' | 'equals' | 'notEquals' | 'contains' | 'notContains'
 export type AssignmentOperator = '=' | 'equals'
@@ -122,6 +125,12 @@ export interface FieldConfigData {
   label?: string
   editorLabel?: string
   hideLabel?: boolean
+  /** Where the label sits relative to the control. Defaults to `after` for a lone checkbox or radio, `top` otherwise. */
+  labelPosition?: LabelPosition
+  /**
+   * @deprecated Use `labelPosition`. Still read by the renderer (`true` is `bottom`, or `after` for a lone checkbox or
+   * radio); the editor converts it to `labelPosition` on load.
+   */
   labelAfter?: boolean
   disableHtmlLabel?: boolean
   editableContent?: boolean
@@ -353,6 +362,11 @@ export interface ConfigOptionDeclaration {
   label?: string
   /** The value a key added from the dialog starts with. Its type picks the input: a checkbox for boolean, text otherwise. */
   default: boolean | string | number
+  /**
+   * Makes the item a dropdown of these choices. Each `value` is a string, and `default` must be one of them. A missing
+   * `label` is the `<key>.<value>` translation, then the value in title case.
+   */
+  options?: Array<{ value: string; label?: string }>
 }
 
 export interface ComponentConfig {
diff --git a/src/types/formeo.test-d.ts b/src/types/formeo.test-d.ts
index fa795fdb..5983eef5 100644
--- a/src/types/formeo.test-d.ts
+++ b/src/types/formeo.test-d.ts
@@ -17,6 +17,7 @@ import {
   type FormeoOptions,
   FormeoRenderer,
   type FormeoRendererOptions,
+  type LabelPosition,
   type LogicalOperator,
   type RemoveItemsActionEvent,
   type UserData,
@@ -452,3 +453,16 @@ export {
   values,
   withLayoutAttrs,
 }
+
+// #243: label position
+const besideLabel: FieldData = { id: 'x', tag: 'input', config: { label: 'Name', labelPosition: 'before' } }
+const everyPosition: LabelPosition[] = ['top', 'bottom', 'before', 'after']
+// @ts-expect-error labelPosition is 'top', 'bottom', 'before' or 'after'; 'before' puts the label on the left
+const leftLabel: FieldData = { id: 'x', tag: 'input', config: { labelPosition: 'left' } }
+const legacyLabel: FieldData = { id: 'x', tag: 'input', config: { labelAfter: true } }
+const positionDeclaration: ConfigOptionDeclaration = {
+  default: 'top',
+  options: [{ value: 'top' }, { value: 'before', label: 'Left' }],
+}
+// @ts-expect-error an option's value is a string
+const numericChoice: ConfigOptionDeclaration = { default: 1, options: [{ value: 1 }] }
diff --git a/tools/formdata-schema.mjs b/tools/formdata-schema.mjs
index a59b1334..b52c4db8 100644
--- a/tools/formdata-schema.mjs
+++ b/tools/formdata-schema.mjs
@@ -112,6 +112,14 @@ export const formDataSchema = z
               .object({
                 label: z.string().optional(),
                 hideLabel: z.boolean().optional(),
+                labelPosition: z
+                  .enum(['top', 'bottom', 'before', 'after'])
+                  .optional()
+                  .describe('Where the label sits: top/bottom stack, before/after sit beside the control'),
+                labelAfter: z
+                  .boolean()
+                  .optional()
+                  .describe('Legacy: replaced by labelPosition, which wins when both are set'),
                 editableContent: z.boolean().optional(),
                 controlId: z.string().optional(),
                 disabledAttrs: z.array(z.string()).optional(),

From 7acea3a94e1da7133801d7561f42fb8c6878a5df Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 12:43:58 +0100
Subject: [PATCH 10/19] fix(types): export the label position fixtures and
 regroup LabelPosition

Refs #243
---
 src/types/formeo.d.ts      | 6 +++---
 src/types/formeo.test-d.ts | 6 ++++++
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/src/types/formeo.d.ts b/src/types/formeo.d.ts
index 96e9855e..f38dccd6 100644
--- a/src/types/formeo.d.ts
+++ b/src/types/formeo.d.ts
@@ -23,9 +23,6 @@ export type ComponentType = 'stage' | 'row' | 'column' | 'field'
  * the symbols; the renderer also accepts the words. `&&` binds tighter than `||`.
  */
 export type LogicalOperator = '&&' | '||' | 'and' | 'or'
-
-/** Where a field's label sits: `top`/`bottom` stack, `before`/`after` sit beside the control (mirrored in RTL). */
-export type LabelPosition = 'top' | 'bottom' | 'before' | 'after'
 /** Symbols are what the editor stores; the renderer also accepts the names. */
 export type ComparisonOperator = '==' | '!=' | '⊃' | '!⊃' | 'equals' | 'notEquals' | 'contains' | 'notContains'
 export type AssignmentOperator = '=' | 'equals'
@@ -33,6 +30,9 @@ export type AssignmentOperator = '=' | 'equals'
 export type ConditionSourceProperty = 'value' | 'isChecked' | 'isNotChecked' | 'isVisible' | 'isNotVisible' | 'checked'
 export type ConditionTargetProperty = 'value' | 'isChecked' | 'isNotChecked' | 'isVisible' | 'isNotVisible'
 
+/** Where a field's label sits: `top`/`bottom` stack, `before`/`after` sit beside the control (mirrored in RTL). */
+export type LabelPosition = 'top' | 'bottom' | 'before' | 'after'
+
 /** Empty strings are what an unfinished condition row in the editor saves. */
 type Blank = ''
 
diff --git a/src/types/formeo.test-d.ts b/src/types/formeo.test-d.ts
index 5983eef5..d37d562d 100644
--- a/src/types/formeo.test-d.ts
+++ b/src/types/formeo.test-d.ts
@@ -432,17 +432,23 @@ export {
   badPanelDefault,
   badStage,
   bare,
+  besideLabel,
   clearAll,
   componentEvents,
   describeReorder,
+  everyPosition,
   fromGlobal,
   headless,
   html,
   jquery,
   json,
+  leftLabel,
+  legacyLabel,
   lockedDown,
   newPage,
+  numericChoice,
   otherChoiceForm,
+  positionDeclaration,
   queried,
   ratingControl,
   stars,

From 0788ec6a23aa350aa12d5c3180577037b2262694 Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 12:46:44 +0100
Subject: [PATCH 11/19] docs: label position, the f-field wrapper and
 --formeo-label-width

Refs #243
---
 README.md                       |  3 +-
 docs/css-frameworks.md          |  3 ++
 docs/options/config/README.md   |  9 ++++--
 docs/options/controls/README.md | 13 +++++++-
 docs/renderer/renderer.md       | 53 +++++++++++++++++++++++++++++++++
 5 files changed, 77 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 692d2a75..afddcd09 100644
--- a/README.md
+++ b/README.md
@@ -177,7 +177,7 @@ Formeo can be integrated with popular frontend frameworks:
 
 ## Theming
 
-Every color formeo uses is a `--formeo-*` CSS custom property, declared on `:root` with zero specificity. Override them on `:root` or `<body>`: formeo appends its dialogs to `document.body`, so a rule scoped to the editor's container misses them. A narrower selector works too if it also covers `.formeo-dialog` and, when you move the controls panel with `controls.container`, `.formeo-controls`. For example, to map your own dark theme:
+Every color formeo uses is a `--formeo-*` CSS custom property, and so is the width of a label that sits beside its control, all declared on `:root` with zero specificity. Override them on `:root` or `<body>`: formeo appends its dialogs to `document.body`, so a rule scoped to the editor's container misses them. A narrower selector works too if it also covers `.formeo-dialog` and, when you move the controls panel with `controls.container`, `.formeo-controls`. For example, to map your own dark theme:
 
 ```css
 :root {
@@ -203,6 +203,7 @@ The full list, with defaults, is in [`_properties.scss`](https://github.com/Drag
 - **Borders and focus:** `border`, `border-strong`, `focus`
 - **Accents:** `primary`, `success`, `warning` and `danger` (each with a `-dark` variant), `danger-subtle`, `info`, `remove-bg`
 - **Component outlines:** `{stage,row,column,field,option}-outline`, `-outline-text`, `-highlight` and `-highlight-text`, plus `column-outline-soft`
+- **Layout:** `label-width` (the label's width when `labelPosition` is `before` or `after`, `10rem`)
 
 **Visual changes from 5.1.3:** icons that hard-coded `#444` (header, paragraph and the triangles) now use `--formeo-icon`, which defaults to `#000`. The column resize-handle triangles now use the column outline color (`--formeo-column-outline-soft`, or the darker `--formeo-column-outline` on hover) instead of `#444`.
 
diff --git a/docs/css-frameworks.md b/docs/css-frameworks.md
index a3da23b0..d2181256 100644
--- a/docs/css-frameworks.md
+++ b/docs/css-frameworks.md
@@ -35,6 +35,9 @@ group and a select, trimmed to the structural elements and their classes:
 - **Column:** same as rows — editor-built columns carry `className: ['formeo-column']`; hand-written data may not.
   Either way its width comes from an inline `style="width: ...%"` (from the column's `config.width`, `100%` if
   unset).
+- **Field:** a field with a visible label is wrapped in a div with `f-field` and its label position,
+  `f-label-top|bottom|before|after` (see [Label position](renderer/renderer.md#label-position)). A field without a
+  visible label has no wrapper.
 - **Checkbox/radio options:** each option is wrapped in a div with a fixed `f-checkbox` or `f-radio` class.
 - **Required mark:** the `*` next to a label is a `<span class="text-error">`.
 - **Tooltip:** `<span class="f-tooltip" data-tooltip="...">`.
diff --git a/docs/options/config/README.md b/docs/options/config/README.md
index de344fbf..40635d74 100644
--- a/docs/options/config/README.md
+++ b/docs/options/config/README.md
@@ -71,18 +71,23 @@ A component's Configuration panel shows the `config` keys declared for it in `pa
 "Add config" dialog offers the declared keys the component doesn't have yet, and its Add button hides when there are
 none left. Keys that aren't declared, such as `controlId`, never show.
 
-- `fields.all` declares `label`, `hideLabel`, `helpText`, `labelAfter`, `disableHtmlLabel` and `tooltip`.
+- `fields.all` declares `label`, `hideLabel`, `helpText`, `labelPosition`, `disableHtmlLabel` and `tooltip`.
+  `labelPosition` is a dropdown (see [Label position](../../renderer/renderer.md#label-position)). It replaces
+  `labelAfter`, which the editor converts on load.
 - A control can declare more for its own fields with `configOptions` (see [elements](../controls/README.md#configoptions)).
 - The checkbox and radio group controls declare `other` and `otherLabel`, which add an
   [Other choice](../../renderer/renderer.md#other-choice) to the group.
 - Stages declare `title` when the editor's [`pages`](../../editor/pages.md) option is on and nothing otherwise, so a
   stage without pages has no Configuration panel.
 
-A declaration is `{ default, label }`:
+A declaration is `{ default, label, options }`:
 
 - `default` is the value a key added from the dialog starts with. It must be a boolean (edited with a checkbox), a
   string or a number (edited with a text input). Other defaults are ignored with a console warning.
 - `label` is optional. It defaults to the `config.<key>` translation, then to the key in title case.
+- `options` is optional and makes the item a dropdown: `[{ value, label }]`, where each `value` is a string and
+  `default` is one of them. A missing `label` is the `<key>.<value>` translation, then the value in title case.
+  Options that don't meet these rules make the declaration ignored, with a console warning.
 
 Declarations merge in this order, later ones winning: `all`, the control's own `configOptions`, the field type, then the
 component id. A key listed in `disabled` at any of those levels is hidden from the panel and the dialog. It stays in
diff --git a/docs/options/controls/README.md b/docs/options/controls/README.md
index b7a7d335..0ddc0513 100644
--- a/docs/options/controls/README.md
+++ b/docs/options/controls/README.md
@@ -101,7 +101,7 @@ An element with a `controlSet` key adds a group of fields at once; see
 ### configOptions
 
 `configOptions` declares `config` keys the element's fields offer in their Configuration panel, on top of the keys every
-field has. Each one is `{ default, label }`, as described in
+field has. Each one is `{ default, label, options }`, as described in
 [Configuration panel keys](../config/README.md#configuration-panel-keys). `configOptions` itself is never saved in
 form data. A field only gets one of these keys when the element's `config` sets it or a user adds it from the dialog.
 The editor's `config` option can still relabel or disable them.
@@ -116,6 +116,17 @@ The editor's `config` option can still relabel or disable them.
 }
 ```
 
+A lone checkbox or radio control can start its label after the box in the panel's dropdown:
+
+```javascript
+configOptions: {
+  labelPosition: {
+    default: 'after',
+    options: [{ value: 'top' }, { value: 'bottom' }, { value: 'before' }, { value: 'after' }],
+  },
+},
+```
+
 ## elementOrder
 
 Set the element order within a control group. May be overridden if [sortable](#sortable) is set to true
diff --git a/docs/renderer/renderer.md b/docs/renderer/renderer.md
index 1ea7e61e..0433bf81 100644
--- a/docs/renderer/renderer.md
+++ b/docs/renderer/renderer.md
@@ -1074,6 +1074,59 @@ rows: {
   `config.width` is added after it, so `config.width` always wins.
 - `id` and `tag` are ignored: Formeo needs the element's id and always renders a `div`.
 
+### Label position
+
+`config.labelPosition` sets where a field's label sits:
+
+| Value    | Layout                 | Order          |
+| -------- | ---------------------- | -------------- |
+| `top`    | label above            | label, control |
+| `bottom` | label below            | control, label |
+| `before` | label beside, leading  | label, control |
+| `after`  | label beside, trailing | control, label |
+
+`before` and `after` follow the text direction, so in a right-to-left form `before` is on the right. The label and
+control are always in the DOM in the order you see them, so screen readers read them in that order. In the editor it's
+the Label Position dropdown in a field's Configuration panel.
+
+Without `labelPosition`, a lone checkbox or radio is `after` and everything else is `top`. A checkbox or radio group's
+`labelPosition` moves the group's label. Each option's label always follows its own input.
+
+Every rendered field with a visible label is wrapped like this:
+
+```html
+<div class="f-field f-label-before">
+  <label for="f-name">Name</label>
+  <input id="f-name" name="name" type="text">
+</div>
+```
+
+`before` and `after` sit side by side while the control has at least half the row. In a narrower column or viewport
+they stack, with the label above (`before`) or below (`after`). The label's width beside the control is
+`--formeo-label-width`, `10rem` by default:
+
+```css
+.my-form {
+  --formeo-label-width: 14rem;
+}
+```
+
+A checkbox or radio group is named by its label: the group is `role="group"` with `aria-labelledby` pointing at the
+label, whose id is `f-<id>-label`.
+
+Fields without a visible label (`hideLabel`, hidden inputs, headers, paragraphs, dividers and buttons) have no wrapper,
+and `labelPosition` doesn't apply to them.
+
+**`labelAfter`:** older forms and control definitions may use `config.labelAfter`. The renderer still reads it: `true`
+is `bottom` (`after` for a lone checkbox or radio) and `false` is `top` (`before`). `labelPosition` wins when both are
+set. The editor converts `labelAfter` to `labelPosition` when it loads a field, so the form saves with
+`labelPosition`.
+
+**Replacing a `:has()` workaround:** if you used a rule like
+`.formeo-render div:has(> label + input) { display: flex; }` to put labels beside inputs, set `labelPosition: 'before'`
+on those fields (or target `.f-field.f-label-before`) and delete the rule. The built-in layout also stacks on narrow
+screens.
+
 ### Accessing Components
 
 The renderer caches all rendered components internally:

From 3cc941ef48799478f2f6fd157fbe9ff4b2188ab9 Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 12:49:22 +0100
Subject: [PATCH 12/19] test(e2e): label positions in the editor and the
 rendered form

Refs #243
---
 tests/label-position.spec.js | 207 +++++++++++++++++++++++++++++++++++
 1 file changed, 207 insertions(+)
 create mode 100644 tests/label-position.spec.js

diff --git a/tests/label-position.spec.js b/tests/label-position.spec.js
new file mode 100644
index 00000000..1fac2041
--- /dev/null
+++ b/tests/label-position.spec.js
@@ -0,0 +1,207 @@
+// @ts-check
+import { expect, test } from '@playwright/test'
+
+const POSITIONS = ['top', 'bottom', 'before', 'after']
+
+/** One text field `field-lp` (and optionally more fields) in a single-column form */
+const formWith = (fields = {}) => {
+  const ids = Object.keys(fields)
+  return {
+    id: 'form-lp',
+    stages: { 'stage-lp': { id: 'stage-lp', children: ['row-lp'] } },
+    rows: { 'row-lp': { id: 'row-lp', config: {}, children: ['col-lp'] } },
+    columns: { 'col-lp': { id: 'col-lp', config: { width: '100%' }, children: ids } },
+    fields,
+  }
+}
+
+const textField = (config = {}) => ({
+  'field-lp': {
+    id: 'field-lp',
+    tag: 'input',
+    attrs: { type: 'text' },
+    config: { label: 'Name', controlId: 'text-input', ...config },
+  },
+})
+
+/**
+ * Mounts an editor in #e2e-lp (above the demo editor). The editor is window.__editor.
+ * @param {import('@playwright/test').Page} page
+ * @param {Object} formData
+ */
+const mountEditor = async (page, formData) => {
+  await page.goto('/')
+  await expect(page.locator('.formeo-editor').first()).toBeVisible()
+  await page.evaluate(async formData => {
+    const container = document.createElement('div')
+    container.id = 'e2e-lp'
+    document.body.prepend(container)
+    window.__editor = new window.FormeoEditor(
+      { editorContainer: container, sessionStorage: false, style: null },
+      formData
+    )
+    await window.__editor.whenReady()
+  }, formData)
+  return page.locator('#e2e-lp')
+}
+
+/**
+ * Renders the editor's formData into #e2e-lp-render
+ * @param {import('@playwright/test').Page} page
+ * @param {{ width?: string, dir?: string }} [opts]
+ */
+const renderEditorForm = (page, { width = '', dir = '' } = {}) =>
+  page.evaluate(
+    ({ width, dir }) => {
+      const container = Object.assign(document.createElement('div'), { id: 'e2e-lp-render' })
+      container.style.width = width
+      if (dir) {
+        container.dir = dir
+      }
+      document.body.appendChild(container)
+      new window.FormeoRenderer({ renderContainer: container }).render(window.__editor.formData)
+    },
+    { width, dir }
+  )
+
+const formDataOf = page => page.evaluate(() => window.__editor.formData)
+
+/** Bounding boxes of a label and its control */
+const boxesOf = async (label, control) => {
+  const [l, c] = [await label.boundingBox(), await control.boundingBox()]
+  if (!l || !c) throw new Error('label or control is not visible')
+  return { l, c }
+}
+
+const overlapsVertically = ({ l, c }) => l.y < c.y + c.height && c.y < l.y + l.height
+
+/** Asserts the label sits where `position` puts it, for left-to-right text */
+const expectPlaced = (position, boxes) => {
+  const { l, c } = boxes
+  if (position === 'top') expect(l.y + l.height).toBeLessThanOrEqual(c.y + 1)
+  if (position === 'bottom') expect(c.y + c.height).toBeLessThanOrEqual(l.y + 1)
+  if (position === 'before') {
+    expect(overlapsVertically(boxes)).toBe(true)
+    expect(l.x + l.width).toBeLessThanOrEqual(c.x + 1)
+  }
+  if (position === 'after') {
+    expect(overlapsVertically(boxes)).toBe(true)
+    expect(c.x + c.width).toBeLessThanOrEqual(l.x + 1)
+  }
+}
+
+test.describe('label position (#243)', () => {
+  for (const position of POSITIONS) {
+    test(`${position}: the editor preview and the rendered form agree`, async ({ page }) => {
+      const editor = await mountEditor(page, formWith(textField({ labelPosition: position })))
+      const field = editor.locator('.formeo-field').first()
+      await expect(field.locator(':scope > .f-field')).toHaveClass(`f-field f-label-${position}`)
+      expectPlaced(position, await boxesOf(field.locator('.prev-label'), field.locator('.field-preview input')))
+
+      await renderEditorForm(page)
+      const wrapper = page.locator('#e2e-lp-render .f-field')
+      await expect(wrapper).toHaveClass(`f-field f-label-${position}`)
+      expectPlaced(position, await boxesOf(wrapper.locator('label'), wrapper.locator('input')))
+    })
+  }
+
+  test('the Configuration panel sets labelPosition from a dropdown', async ({ page }) => {
+    const editor = await mountEditor(page, formWith(textField()))
+    const field = editor.locator('.formeo-field').first()
+    await field.hover()
+    await field.locator('.field-actions').hover()
+    await field.locator('.field-actions .edit-toggle').click()
+    const editWindow = field.locator('.field-edit')
+    await expect(editWindow).toBeVisible()
+    await editWindow.getByRole('heading', { name: 'Configuration' }).click()
+    await editWindow.locator('.add-config').click()
+    const dialog = page.locator('.formeo-dialog.config-item-dialog')
+    await dialog.locator('select.config-key-select').selectOption('labelPosition')
+    await dialog.locator('button[type="submit"]').click()
+
+    await editWindow.locator('select.config-labelPosition').selectOption('before')
+    await expect.poll(async () => (await formDataOf(page)).fields['field-lp'].config.labelPosition).toBe('before')
+
+    await field.locator('.field-actions .edit-toggle').click()
+    await expect(field.locator(':scope > .f-field')).toHaveClass('f-field f-label-before')
+  })
+
+  test('a form saved with labelAfter loads as bottom and keeps its look', async ({ page }) => {
+    const editor = await mountEditor(page, formWith(textField({ labelAfter: true })))
+    const { config } = (await formDataOf(page)).fields['field-lp']
+    expect(config.labelPosition).toBe('bottom')
+    expect('labelAfter' in config).toBe(false)
+    const field = editor.locator('.formeo-field').first()
+    expectPlaced('bottom', await boxesOf(field.locator('.prev-label'), field.locator('.field-preview input')))
+  })
+
+  test('before stacks in a narrow container, with the input at full width', async ({ page }) => {
+    await mountEditor(page, formWith(textField({ labelPosition: 'before' })))
+    await renderEditorForm(page, { width: '240px' })
+    const wrapper = page.locator('#e2e-lp-render .f-field')
+    const { l, c } = await boxesOf(wrapper.locator('label'), wrapper.locator('input'))
+    const w = await wrapper.boundingBox()
+    expect(l.y + l.height).toBeLessThanOrEqual(c.y + 1)
+    expect(Math.abs(c.width - (w?.width ?? 0))).toBeLessThanOrEqual(1)
+  })
+
+  test('before is on the right in a right-to-left form', async ({ page }) => {
+    await mountEditor(page, formWith(textField({ labelPosition: 'before' })))
+    await renderEditorForm(page, { dir: 'rtl' })
+    const wrapper = page.locator('#e2e-lp-render .f-field')
+    const boxes = await boxesOf(wrapper.locator('label'), wrapper.locator('input'))
+    expect(overlapsVertically(boxes)).toBe(true)
+    expect(boxes.l.x).toBeGreaterThanOrEqual(boxes.c.x + boxes.c.width - 1)
+  })
+
+  test('a long before label wraps beside the input instead of pushing it down', async ({ page }) => {
+    const label = 'A label much longer than the default label width, so its text has to wrap'
+    await mountEditor(page, formWith(textField({ label, labelPosition: 'before' })))
+    await renderEditorForm(page, { width: '900px' })
+    const wrapper = page.locator('#e2e-lp-render .f-field')
+    expectPlaced('before', await boxesOf(wrapper.locator('label'), wrapper.locator('input')))
+  })
+
+  test('clicking a label focuses its input in every position', async ({ page }) => {
+    const fields = Object.fromEntries(
+      POSITIONS.map(position => [
+        `field-${position}`,
+        {
+          id: `field-${position}`,
+          tag: 'input',
+          attrs: { type: 'text' },
+          config: { label: `Label ${position}`, controlId: 'text-input', labelPosition: position },
+        },
+      ])
+    )
+    await mountEditor(page, formWith(fields))
+    await renderEditorForm(page)
+    for (const position of POSITIONS) {
+      await page.locator(`#e2e-lp-render label[for="f-field-${position}"]`).click()
+      await expect(page.locator(`#e2e-lp-render #f-field-${position}`)).toBeFocused()
+    }
+  })
+
+  test('checkbox and radio groups are named by their label', async ({ page }) => {
+    const group = (id, type, label) => ({
+      id,
+      tag: 'input',
+      attrs: { type },
+      config: { label, controlId: type, labelPosition: 'before' },
+      options: [
+        { label: 'One', value: 'one' },
+        { label: 'Two', value: 'two' },
+      ],
+    })
+    await mountEditor(
+      page,
+      formWith({ colours: group('colours', 'checkbox', 'Colours'), size: group('size', 'radio', 'Size') })
+    )
+    await renderEditorForm(page)
+    const form = page.locator('#e2e-lp-render')
+    await expect(form.getByRole('group', { name: 'Colours' })).toBeVisible()
+    await expect(form.getByRole('group', { name: 'Size' })).toBeVisible()
+    await form.getByRole('group', { name: 'Size' }).getByLabel('Two').check()
+    await expect(form.locator('#f-size-1')).toBeChecked()
+  })
+})

From 51f05f6e576cd1de19aced922de5e45449189551 Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 13:00:46 +0100
Subject: [PATCH 13/19] test(styles): move the label position CSS test into the
 custom properties suite

Refs #243
---
 src/lib/sass/css-properties.test.mjs | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/src/lib/sass/css-properties.test.mjs b/src/lib/sass/css-properties.test.mjs
index bf102bd2..e2637b8a 100644
--- a/src/lib/sass/css-properties.test.mjs
+++ b/src/lib/sass/css-properties.test.mjs
@@ -140,6 +140,15 @@ suite('formeo CSS custom properties', () => {
       t.assert.ok(!css.includes(fragment), `${fragment} must be stripped before baseline comparison`)
     }
   })
+
+  test('side-by-side label positions wrap instead of reordering, and use --formeo-label-width (#243)', t => {
+    const compiled = compileFormeoCss()
+    const sideBySide = compiledRule('.formeo .f-field.f-label-before,')
+    t.assert.match(sideBySide, /display: flex;/)
+    t.assert.match(sideBySide, /flex-wrap: wrap;/)
+    t.assert.match(compiled, /flex: 1 1 var\(--formeo-label-width\);/)
+    t.assert.doesNotMatch(compiled, /\.f-field[^{]*\{[^}]*(?:\border:|flex-direction: \w+-reverse)/)
+  })
 })
 
 suite('resolveFormeoProperties purity', () => {
@@ -181,15 +190,6 @@ suite('resolveFormeoProperties purity', () => {
       /:where\(\.formeo-dark\) may only declare .*found: background: black/
     )
   })
-
-  test('side-by-side label positions wrap instead of reordering, and use --formeo-label-width (#243)', t => {
-    const compiled = compileFormeoCss()
-    const sideBySide = compiledRule('.formeo .f-field.f-label-before,')
-    t.assert.match(sideBySide, /display: flex;/)
-    t.assert.match(sideBySide, /flex-wrap: wrap;/)
-    t.assert.match(compiled, /flex: 1 1 var\(--formeo-label-width\);/)
-    t.assert.doesNotMatch(compiled, /\.f-field[^{]*\{[^}]*(?:\border:|flex-direction: \w+-reverse)/)
-  })
 })
 
 /** The single compiled rule starting with `start`, trimmed. */

From d24c2bf6aed852f3f4aa1143581e28b9c94e6b5b Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 13:02:25 +0100
Subject: [PATCH 14/19] fix(styles): keep condition-hidden before/after fields
 hidden

Refs #243
---
 src/lib/sass/__fixtures__/formeo-baseline.css |  3 ++
 src/lib/sass/base/_bs.scss                    |  5 +++
 src/lib/sass/css-properties.test.mjs          |  4 +++
 tests/label-position.spec.js                  | 32 +++++++++++++++++++
 4 files changed, 44 insertions(+)

diff --git a/src/lib/sass/__fixtures__/formeo-baseline.css b/src/lib/sass/__fixtures__/formeo-baseline.css
index 49ed5f7a..72ec34d3 100644
--- a/src/lib/sass/__fixtures__/formeo-baseline.css
+++ b/src/lib/sass/__fixtures__/formeo-baseline.css
@@ -454,6 +454,9 @@ button[class*=-clone]:hover .svg-icon {
 .formeo .f-field.f-label-bottom > .prev-label {
   display: block;
 }
+.formeo .f-field[hidden] {
+  display: none;
+}
 .formeo select {
   font-size: 100%;
   font-family: inherit;
diff --git a/src/lib/sass/base/_bs.scss b/src/lib/sass/base/_bs.scss
index 407cd83a..a5aa294b 100644
--- a/src/lib/sass/base/_bs.scss
+++ b/src/lib/sass/base/_bs.scss
@@ -73,6 +73,11 @@ hr {
       display: block;
     }
   }
+
+  // a condition hides a field by setting `hidden` on this wrapper, which the flex display above would override
+  &[hidden] {
+    display: none;
+  }
 }
 
 select {
diff --git a/src/lib/sass/css-properties.test.mjs b/src/lib/sass/css-properties.test.mjs
index e2637b8a..aade94c1 100644
--- a/src/lib/sass/css-properties.test.mjs
+++ b/src/lib/sass/css-properties.test.mjs
@@ -149,6 +149,10 @@ suite('formeo CSS custom properties', () => {
     t.assert.match(compiled, /flex: 1 1 var\(--formeo-label-width\);/)
     t.assert.doesNotMatch(compiled, /\.f-field[^{]*\{[^}]*(?:\border:|flex-direction: \w+-reverse)/)
   })
+
+  test('a hidden label wrapper stays hidden in every position, so conditions can hide it (#243)', t => {
+    t.assert.strictEqual(compiledRule('.formeo .f-field[hidden] {'), '.formeo .f-field[hidden] {\n  display: none;\n}')
+  })
 })
 
 suite('resolveFormeoProperties purity', () => {
diff --git a/tests/label-position.spec.js b/tests/label-position.spec.js
index 1fac2041..15557f08 100644
--- a/tests/label-position.spec.js
+++ b/tests/label-position.spec.js
@@ -182,6 +182,38 @@ test.describe('label position (#243)', () => {
     }
   })
 
+  test('a condition hides a before field and a lone checkbox', async ({ page }) => {
+    const hide = target => ({
+      if: [
+        { source: 'fields.trigger', sourceProperty: 'value', comparison: 'equals', target: 'hide', targetProperty: '' },
+      ],
+      then: [{ target: `fields.${target}`, targetProperty: 'isNotVisible', assignment: '', value: '' }],
+    })
+    const formData = formWith({
+      trigger: { id: 'trigger', tag: 'input', attrs: { type: 'text' }, config: { label: 'Trigger' } },
+      ...textField({ labelPosition: 'before' }),
+      agree: { id: 'agree', tag: 'input', attrs: { type: 'checkbox' }, config: { label: 'I agree' } },
+    })
+    formData.stages['stage-lp'].conditions = [hide('field-lp'), hide('agree')]
+    await page.goto('/')
+    await page.evaluate(formData => {
+      const container = Object.assign(document.createElement('div'), { id: 'e2e-lp-render' })
+      document.body.appendChild(container)
+      new window.FormeoRenderer({ renderContainer: container }).render(formData)
+    }, formData)
+    const form = page.locator('#e2e-lp-render')
+    const before = form.locator('.f-field:has(> #f-field-lp)')
+    const checkbox = form.locator('.f-field:has(> #f-agree)')
+    await expect(before).toHaveClass('f-field f-label-before')
+    await expect(checkbox).toHaveClass('f-field f-label-after')
+    await expect(before).toBeVisible()
+    await expect(checkbox).toBeVisible()
+
+    await form.locator('#f-trigger').fill('hide')
+    await expect(before).toBeHidden()
+    await expect(checkbox).toBeHidden()
+  })
+
   test('checkbox and radio groups are named by their label', async ({ page }) => {
     const group = (id, type, label) => ({
       id,

From 796cf6802bca2ffbefb1a9d137d45c453e1cf5ca Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 13:05:04 +0100
Subject: [PATCH 15/19] fix(dom): keep label wrapper classes off the group
 element and button container

Refs #243
---
 src/lib/js/common/dom.js                   |  6 ++---
 src/lib/js/renderer/label-position.test.js | 31 ++++++++++++++++++++++
 tests/label-position.spec.js               | 18 +++++++++++++
 3 files changed, 52 insertions(+), 3 deletions(-)

diff --git a/src/lib/js/common/dom.js b/src/lib/js/common/dom.js
index a5a0658f..b2550433 100644
--- a/src/lib/js/common/dom.js
+++ b/src/lib/js/common/dom.js
@@ -240,9 +240,9 @@ class DOM {
           wrap.children.push(_this.create(option, isPreview))
         })
         const groupAttrs = elem.attrs || {}
-        if (groupAttrs.className) {
-          wrap.className = groupAttrs.className
-        }
+        // the group (or button container) gets only its own class; config.inputWrap (f-field f-label-*) stays in
+        // wrap.config for the label wrapper, which is only built when the label renders
+        wrap.className = groupAttrs.className || []
         wrap.id = elem.id
         wrap.attrs = groupWrapperAttrs(groupAttrs)
         // config.required only drives the label's required mark; `required` itself lives on the option inputs
diff --git a/src/lib/js/renderer/label-position.test.js b/src/lib/js/renderer/label-position.test.js
index f6f0116f..857ec693 100644
--- a/src/lib/js/renderer/label-position.test.js
+++ b/src/lib/js/renderer/label-position.test.js
@@ -173,6 +173,37 @@ describe('label position in the renderer (#243)', () => {
       assert.ok(group.classList.contains('my-group'))
       assert.deepEqual([...group.parentElement.classList], ['f-field', 'f-label-before', 'my-group'])
     })
+
+    test('a group without a className keeps f-field off the group element', () => {
+      render({ colour: groupField('colour', 'checkbox', { labelPosition: 'before' }) })
+      const group = container.querySelector('#f-colour')
+      assert.equal(group.classList.contains('f-field'), false)
+      assert.equal(group.className.includes('f-label-'), false)
+      assert.deepEqual([...group.parentElement.classList], ['f-field', 'f-label-before'])
+      assert.equal(container.querySelector('#f-column-colour').querySelectorAll('.f-field').length, 1)
+    })
+
+    test('a group with a hidden label has no f-field at all', () => {
+      render({ colour: groupField('colour', 'radio', { hideLabel: true, labelPosition: 'before' }) })
+      assert.equal(container.querySelector('#f-column-colour').querySelectorAll('.f-field').length, 0)
+    })
+
+    const buttonField = (id, attrs) => ({
+      id,
+      tag: 'button',
+      attrs,
+      config: { label: 'Button', hideLabel: true },
+      options: [{ label: 'Go', type: 'button', className: '' }],
+    })
+
+    test('a button with an empty or missing attrs.className has no f-field', () => {
+      render({ empty: buttonField('empty', { className: '' }), none: buttonField('none', {}) })
+      for (const id of ['empty', 'none']) {
+        const column = container.querySelector(`#f-column-${id}`)
+        assert.ok(column.querySelector('button'), `${id} renders its button`)
+        assert.equal(column.querySelectorAll('.f-field').length, 0, `${id} has no f-field`)
+      }
+    })
   })
 
   describe('groups', () => {
diff --git a/tests/label-position.spec.js b/tests/label-position.spec.js
index 15557f08..0cb87ea2 100644
--- a/tests/label-position.spec.js
+++ b/tests/label-position.spec.js
@@ -214,6 +214,24 @@ test.describe('label position (#243)', () => {
     await expect(checkbox).toBeHidden()
   })
 
+  test('a radio group with a before label is not itself a label-position flex wrapper', async ({ page }) => {
+    const size = {
+      id: 'size',
+      tag: 'input',
+      attrs: { type: 'radio' },
+      config: { label: 'Size', controlId: 'radio', labelPosition: 'before' },
+      options: ['S', 'M', 'L'].map(label => ({ label, value: label.toLowerCase() })),
+    }
+    await mountEditor(page, formWith({ size }))
+    await renderEditorForm(page)
+    const form = page.locator('#e2e-lp-render')
+    const group = form.locator('#f-size')
+    await expect(form.locator('.f-field')).toHaveCount(1)
+    await expect(group).not.toHaveClass(/f-field/)
+    expect(await group.evaluate(el => getComputedStyle(el).display)).toBe('block')
+    expectPlaced('before', await boxesOf(form.locator('#f-size-label'), group))
+  })
+
   test('checkbox and radio groups are named by their label', async ({ page }) => {
     const group = (id, type, label) => ({
       id,

From 653606f0569df68ec976d04573d521524ee18a57 Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 13:06:09 +0100
Subject: [PATCH 16/19] fix(editor): start an added Label Position at the
 field's current position

Refs #243
---
 .../js/components/edit-panel/edit-panel.js    |  6 +++--
 .../components/edit-panel/edit-panel.test.js  | 23 +++++++++++++++++++
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/src/lib/js/components/edit-panel/edit-panel.js b/src/lib/js/components/edit-panel/edit-panel.js
index 5f3391af..b7f249f2 100644
--- a/src/lib/js/components/edit-panel/edit-panel.js
+++ b/src/lib/js/components/edit-panel/edit-panel.js
@@ -2,6 +2,7 @@ import i18n from '@draggable/i18n'
 import Sortable from 'sortablejs'
 import dom from '../../common/dom.js'
 import { capitalize, safeAttrName } from '../../common/helpers.mjs'
+import { resolveLabelPosition } from '../../common/label-position.mjs'
 import { slugify, slugifyAddress, toTitleCase } from '../../common/utils/string.mjs'
 import { PANEL_CLASSNAME } from '../../constants.js'
 import Dialog from '../dialog.js'
@@ -348,7 +349,8 @@ export default class EditPanel {
   }
 
   /**
-   * Adds a declared config key, set to its declared default, when it can still be added
+   * Adds a declared config key, set to its declared default, when it can still be added. labelPosition starts at
+   * the position the label already renders in (after, for a lone checkbox or radio), so adding it doesn't move it.
    * @param {String} configKey
    */
   addConfigItem = configKey => {
@@ -358,7 +360,7 @@ export default class EditPanel {
     }
     const newConfig = new EditPanelItem({
       key: `config.${configKey}`,
-      data: declaration.default,
+      data: configKey === 'labelPosition' ? resolveLabelPosition(this.component.data) : declaration.default,
       field: this.component,
       panel: this,
     })
diff --git a/src/lib/js/components/edit-panel/edit-panel.test.js b/src/lib/js/components/edit-panel/edit-panel.test.js
index 5f3290ac..d8107bda 100644
--- a/src/lib/js/components/edit-panel/edit-panel.test.js
+++ b/src/lib/js/components/edit-panel/edit-panel.test.js
@@ -346,6 +346,29 @@ describe('Config panel "Add config"', () => {
     assert.ok(panel.props.contains(items[0].dom))
   })
 
+  it("adds Label Position at the field's current position, so the label doesn't move", () => {
+    const editorComponents = editorWith()
+    const checkbox = new Field(
+      {
+        id: 'f-lone',
+        tag: 'input',
+        attrs: { type: 'checkbox' },
+        config: { label: 'Agree', controlId: 'checkbox' },
+      },
+      editorComponents
+    )
+    const text = textField(editorComponents)
+    for (const [field, expected] of [
+      [checkbox, 'after'],
+      [text, 'top'],
+    ]) {
+      const panel = field.editPanels.get('config')
+      panel.addConfigItem('labelPosition')
+      assert.equal(field.get('config.labelPosition'), expected)
+      assert.equal(panel.props.querySelector('select.config-labelPosition').value, expected)
+    }
+  })
+
   it('ignores a key that is not declared', () => {
     const field = textField(editorWith())
     field.editPanels.get('config').addConfigItem('bogus')

From 83672d450b8df282eec63e80bc81103496d0cf4a Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 13:06:36 +0100
Subject: [PATCH 17/19] docs: how Label position is added in the editor, and
 that a lone checkbox never stacks

Refs #243
---
 docs/options/config/README.md |  5 +++--
 docs/renderer/renderer.md     | 10 ++++++----
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/docs/options/config/README.md b/docs/options/config/README.md
index 40635d74..6871cbe0 100644
--- a/docs/options/config/README.md
+++ b/docs/options/config/README.md
@@ -72,8 +72,9 @@ A component's Configuration panel shows the `config` keys declared for it in `pa
 none left. Keys that aren't declared, such as `controlId`, never show.
 
 - `fields.all` declares `label`, `hideLabel`, `helpText`, `labelPosition`, `disableHtmlLabel` and `tooltip`.
-  `labelPosition` is a dropdown (see [Label position](../../renderer/renderer.md#label-position)). It replaces
-  `labelAfter`, which the editor converts on load.
+  `labelPosition` is a dropdown (see [Label position](../../renderer/renderer.md#label-position)). Added from the
+  dialog, it starts at the position the label already has rather than its declared default, so the label doesn't
+  move. It replaces `labelAfter`, which the editor converts on load.
 - A control can declare more for its own fields with `configOptions` (see [elements](../controls/README.md#configoptions)).
 - The checkbox and radio group controls declare `other` and `otherLabel`, which add an
   [Other choice](../../renderer/renderer.md#other-choice) to the group.
diff --git a/docs/renderer/renderer.md b/docs/renderer/renderer.md
index 0433bf81..13978e56 100644
--- a/docs/renderer/renderer.md
+++ b/docs/renderer/renderer.md
@@ -1086,8 +1086,10 @@ rows: {
 | `after`  | label beside, trailing | control, label |
 
 `before` and `after` follow the text direction, so in a right-to-left form `before` is on the right. The label and
-control are always in the DOM in the order you see them, so screen readers read them in that order. In the editor it's
-the Label Position dropdown in a field's Configuration panel.
+control are always in the DOM in the order you see them, so screen readers read them in that order. In the editor, add
+Label position to a field from its Configuration panel's "Add config" dialog. It starts at the position the label
+already has, and is then a dropdown in that panel. A field whose data already has `labelPosition` shows the dropdown
+straight away.
 
 Without `labelPosition`, a lone checkbox or radio is `after` and everything else is `top`. A checkbox or radio group's
 `labelPosition` moves the group's label. Each option's label always follows its own input.
@@ -1102,8 +1104,8 @@ Every rendered field with a visible label is wrapped like this:
 ```
 
 `before` and `after` sit side by side while the control has at least half the row. In a narrower column or viewport
-they stack, with the label above (`before`) or below (`after`). The label's width beside the control is
-`--formeo-label-width`, `10rem` by default:
+they stack, with the label above (`before`) or below (`after`). (A lone checkbox or radio keeps its own size, so it
+never stacks.) The label's width beside the control is `--formeo-label-width`, `10rem` by default:
 
 ```css
 .my-form {

From 72084da6caddfafbea18941f7a1428ea58632023 Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 13:06:36 +0100
Subject: [PATCH 18/19] docs(types): a ConfigOptionDeclaration with options is
 a dropdown

Refs #243
---
 src/types/formeo.d.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/types/formeo.d.ts b/src/types/formeo.d.ts
index f38dccd6..c1da085d 100644
--- a/src/types/formeo.d.ts
+++ b/src/types/formeo.d.ts
@@ -360,7 +360,10 @@ export interface ComponentEvents {
 export interface ConfigOptionDeclaration {
   /** Shown in the panel and its "Add config" dialog. Defaults to the `config.<key>` translation, then the key in title case. */
   label?: string
-  /** The value a key added from the dialog starts with. Its type picks the input: a checkbox for boolean, text otherwise. */
+  /**
+   * The value a key added from the dialog starts with (`labelPosition` starts at the field's current position instead).
+   * Its type picks the input: a checkbox for boolean, text otherwise. With `options`, the input is a dropdown.
+   */
   default: boolean | string | number
   /**
    * Makes the item a dropdown of these choices. Each `value` is a string, and `default` must be one of them. A missing

From d908c13871efd4e5436d3ecf26d02c5b241d7759 Mon Sep 17 00:00:00 2001
From: Kevin Chappell <kevin@chappell.dev>
Date: Thu, 1 Oct 2026 14:04:36 +0100
Subject: [PATCH 19/19] fix(editor): start only a field's added Label Position
 at its current position

A stage, row or column that declares its own labelPosition config option
keeps its declared default when it's added from the dialog. Those
components have no field label to resolve.

Refs #243
---
 src/lib/js/components/edit-panel/edit-panel.js      | 8 +++++---
 src/lib/js/components/edit-panel/edit-panel.test.js | 9 +++++++++
 2 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/src/lib/js/components/edit-panel/edit-panel.js b/src/lib/js/components/edit-panel/edit-panel.js
index b7f249f2..c36fe8d2 100644
--- a/src/lib/js/components/edit-panel/edit-panel.js
+++ b/src/lib/js/components/edit-panel/edit-panel.js
@@ -349,8 +349,9 @@ export default class EditPanel {
   }
 
   /**
-   * Adds a declared config key, set to its declared default, when it can still be added. labelPosition starts at
-   * the position the label already renders in (after, for a lone checkbox or radio), so adding it doesn't move it.
+   * Adds a declared config key, set to its declared default, when it can still be added. A field's labelPosition
+   * starts at the position its label already renders in (after, for a lone checkbox or radio), so adding it doesn't
+   * move it. Other components have no field label, so their labelPosition keeps its declared default.
    * @param {String} configKey
    */
   addConfigItem = configKey => {
@@ -358,9 +359,10 @@ export default class EditPanel {
     if (!declaration) {
       return
     }
+    const isFieldLabelPosition = configKey === 'labelPosition' && this.component.name === 'field'
     const newConfig = new EditPanelItem({
       key: `config.${configKey}`,
-      data: configKey === 'labelPosition' ? resolveLabelPosition(this.component.data) : declaration.default,
+      data: isFieldLabelPosition ? resolveLabelPosition(this.component.data) : declaration.default,
       field: this.component,
       panel: this,
     })
diff --git a/src/lib/js/components/edit-panel/edit-panel.test.js b/src/lib/js/components/edit-panel/edit-panel.test.js
index d8107bda..457ffe9a 100644
--- a/src/lib/js/components/edit-panel/edit-panel.test.js
+++ b/src/lib/js/components/edit-panel/edit-panel.test.js
@@ -384,6 +384,15 @@ describe('Config panel "Add config"', () => {
     assert.deepEqual(panelKeys(stage), ['config.note'])
   })
 
+  it('adds a labelPosition key declared on a non-field component at its declared default', () => {
+    const options = [{ value: 'top' }, { value: 'side' }]
+    const stage = editorWith({
+      stages: { all: { panels: { config: { options: { labelPosition: { default: 'side', options } } } } } },
+    }).stages.get('s-1')
+    stage.editPanels.get('config').addConfigItem('labelPosition')
+    assert.equal(stage.get('config.labelPosition'), 'side')
+  })
+
   it('hides the Add button while nothing is left to add, and shows it again after a remove', () => {
     const field = textField(editorWith(), {
       hideLabel: false,