From 42118deecf4527a8457da98e0575a7553d64b302 Mon Sep 17 00:00:00 2001 From: jstet Date: Wed, 4 Nov 2026 19:59:40 +0100 Subject: [PATCH] feat(lstsv): map appearance horizontal to the bootstrap_buttons question theme (#227) horizontal and horizontal-compact on select_one use the registry's lsQuestionTheme (#232): question_theme_name=bootstrap_buttons. The way back reads the first registered appearance of a theme, horizontal. A theme that doesn't override the type is kept only on a plain list. Co-Authored-By: Claude Opus 5.5 --- registry/root.jsonld | 34 ++++++++ .../references/xlsform-syntax.md | 2 + src/generated/Appearances.ts | 14 ++++ .../xlsform2lstsv/appearanceHandler.ts | 12 ++- src/pipelines/xlsform2lstsv/index.ts | 6 +- tests/ts/unit/appearance.test.ts | 4 +- tests/ts/unit/horizontalButtons.test.ts | 77 +++++++++++++++++++ 7 files changed, 143 insertions(+), 6 deletions(-) create mode 100644 tests/ts/unit/horizontalButtons.test.ts diff --git a/registry/root.jsonld b/registry/root.jsonld index e4e102b..f40b426 100644 --- a/registry/root.jsonld +++ b/registry/root.jsonld @@ -146,6 +146,40 @@ } } }, + { + "@id": "appearance:horizontal", + "@type": "Appearance", + "skos:prefLabel": "Horizontal choices (buttons)", + "xlsform": { + "appearanceString": "horizontal" + }, + "supported": true, + "behavior": "handled", + "validForTypes": [ + "select_one" + ], + "lsEffect": "LimeSurvey's core question theme bootstrap_buttons on a list (L): the options as a row of buttons", + "lsQuestionTheme": { + "name": "bootstrap_buttons" + } + }, + { + "@id": "appearance:horizontal-compact", + "@type": "Appearance", + "skos:prefLabel": "Horizontal choices, compact (buttons)", + "xlsform": { + "appearanceString": "horizontal-compact" + }, + "supported": true, + "behavior": "handled", + "validForTypes": [ + "select_one" + ], + "lsEffect": "As horizontal: bootstrap_buttons on a list (L). The way back gives the first registered appearance of a theme, horizontal", + "lsQuestionTheme": { + "name": "bootstrap_buttons" + } + }, { "@id": "appearance:multiline", "@type": "Appearance", diff --git a/skills/cdl-survey-types/references/xlsform-syntax.md b/skills/cdl-survey-types/references/xlsform-syntax.md index 2594206..385dc9b 100644 --- a/skills/cdl-survey-types/references/xlsform-syntax.md +++ b/skills/cdl-survey-types/references/xlsform-syntax.md @@ -56,6 +56,8 @@ To limit how many answers a `select_multiple` takes, write `count-selected(.) <= |---|---|---| | `autocomplete` | Dropdown with search (autocomplete) | `select_one`, `select_one_from_file` | | `field-list` | Field list group | `begin_group` | +| `horizontal` | Horizontal choices (buttons) | `select_one` | +| `horizontal-compact` | Horizontal choices, compact (buttons) | `select_one` | | `label` | Matrix header row | `begin_group`, `select_one` | | `likert` | Likert appearance hint | `select_one` | | `list-nolabel` | Matrix body row | `select_one` | diff --git a/src/generated/Appearances.ts b/src/generated/Appearances.ts index 371e3e2..e110c79 100644 --- a/src/generated/Appearances.ts +++ b/src/generated/Appearances.ts @@ -35,6 +35,20 @@ export const APPEARANCES: Record = { lsTypeOverride: "!", lsQuestionTheme: {"name": "bootstrap_dropdown", "attributes": {"show_search": "true"}}, }, + "horizontal": { + supported: true, + behavior: "handled", + validForTypes: ["select_one"], + lsEffect: "LimeSurvey's core question theme bootstrap_buttons on a list (L): the options as a row of buttons", + lsQuestionTheme: {"name": "bootstrap_buttons"}, + }, + "horizontal-compact": { + supported: true, + behavior: "handled", + validForTypes: ["select_one"], + lsEffect: "As horizontal: bootstrap_buttons on a list (L). The way back gives the first registered appearance of a theme, horizontal", + lsQuestionTheme: {"name": "bootstrap_buttons"}, + }, "multiline": { supported: true, behavior: "handled", diff --git a/src/pipelines/xlsform2lstsv/appearanceHandler.ts b/src/pipelines/xlsform2lstsv/appearanceHandler.ts index bb23465..85e0061 100644 --- a/src/pipelines/xlsform2lstsv/appearanceHandler.ts +++ b/src/pipelines/xlsform2lstsv/appearanceHandler.ts @@ -49,13 +49,19 @@ export class AppearanceHandler { * The Q-row columns of the LimeSurvey question theme an appearance selects * (registry `lsQuestionTheme`): `question_theme_name` plus the theme's * attributes, e.g. `autocomplete` → `bootstrap_dropdown` + `show_search`. - * The last appearance with a theme wins, as with type overrides. + * The last appearance with a theme wins, as with type overrides. A theme + * that doesn't override the type (`bootstrap_buttons`) is for a plain list + * only: a dropdown from another appearance (`minimal`) keeps none. */ - themeAttributes(appearance: string, base: string): Record { + themeAttributes( + lsType: LSType, + appearance: string, + base: string, + ): Record { let columns: Record = {}; for (const spec of applicable(appearance, base)) { const theme = spec.lsQuestionTheme; - if (!theme) continue; + if (!theme || (!spec.lsTypeOverride && lsType.type !== 'L')) continue; columns = { [QUESTION_THEME_COLUMN]: theme.name, ...(theme.attributes ?? {}), diff --git a/src/pipelines/xlsform2lstsv/index.ts b/src/pipelines/xlsform2lstsv/index.ts index c42ad18..4d4298f 100644 --- a/src/pipelines/xlsform2lstsv/index.ts +++ b/src/pipelines/xlsform2lstsv/index.ts @@ -636,7 +636,11 @@ class Conversion { ), ...fields.answerBounds, ...this.arrayFilterAttribute(questionName), - ...this.appearanceHandler.themeAttributes(appearance, xfTypeInfo.base), + ...this.appearanceHandler.themeAttributes( + lsType, + appearance, + xfTypeInfo.base, + ), }, }; diff --git a/tests/ts/unit/appearance.test.ts b/tests/ts/unit/appearance.test.ts index 4e9cdaa..da53487 100644 --- a/tests/ts/unit/appearance.test.ts +++ b/tests/ts/unit/appearance.test.ts @@ -164,7 +164,7 @@ describe('Appearance Handling', () => { type: 'select_one yn', name: 'q1', label: 'Pick', - appearance: 'minimal horizontal', + appearance: 'minimal quick', }, ]; const choices = createChoices('yn', [ @@ -177,7 +177,7 @@ describe('Appearance Handling', () => { typeof call[0] === 'string' && call[0].includes('will be ignored'), ); expect(appearanceWarnings).toHaveLength(1); - expect(appearanceWarnings[0][0]).toContain('"horizontal"'); + expect(appearanceWarnings[0][0]).toContain('"quick"'); warnSpy.mockRestore(); }); diff --git a/tests/ts/unit/horizontalButtons.test.ts b/tests/ts/unit/horizontalButtons.test.ts new file mode 100644 index 0000000..1647c4a --- /dev/null +++ b/tests/ts/unit/horizontalButtons.test.ts @@ -0,0 +1,77 @@ +/** + * #227: `appearance: horizontal` (and `horizontal-compact`) on a select_one + * becomes LimeSurvey's `bootstrap_buttons` question theme, and comes back. + */ +import { describe, expect, test } from 'vitest'; + +import { XLSFormToTSVConverter } from '../../../src/pipelines/xlsform2lstsv/index.js'; +import { lstsvToXlsform } from '../../../src/pipelines/lstsv2xlsform/index.js'; +import type { Diagnostic } from '../../../src/diagnostics.js'; +import { findRowByName, parseTSV } from './helpers'; + +const choices = [ + { list_name: 'yn', name: 'ja', label: 'Ja' }, + { list_name: 'yn', name: 'nein', label: 'Nein' }, +]; + +async function convert(survey: Record[]) { + const warnings: Diagnostic[] = []; + const tsv = await new XLSFormToTSVConverter({ + onWarning: (w) => warnings.push(w), + }).convert(survey, choices, [{ form_title: 'T', default_language: 'de' }]); + return { tsv, rows: parseTSV(tsv), warnings }; +} + +const q = (appearance: string, type = 'select_one yn') => ({ + type, + name: 'q1', + label: 'Q', + appearance, +}); + +const theme = (rows: unknown[]) => + ((findRowByName(rows as never, 'q1') ?? {}) as Record)[ + 'question_theme_name' + ] ?? ''; + +describe('horizontal → bootstrap_buttons', () => { + test.each(['horizontal', 'horizontal-compact'])( + '%s on select_one sets the theme, type stays L, no warning', + async (appearance) => { + const { rows, warnings } = await convert([q(appearance)]); + expect(theme(rows)).toBe('bootstrap_buttons'); + expect(findRowByName(rows, 'q1')!['type/scale']).toBe('L'); + expect(warnings).toEqual([]); + }, + ); + + test('no question_theme_name column without the appearance', async () => { + const { tsv } = await convert([q('')]); + expect(tsv.split('\n')[0].split('\t')).not.toContain('question_theme_name'); + }); + + test('a dropdown appearance wins over the theme', async () => { + const { rows } = await convert([q('minimal horizontal')]); + expect(findRowByName(rows, 'q1')!['type/scale']).toBe('!'); + expect(theme(rows)).toBe(''); + }); + + test('horizontal on select_multiple warns and sets no theme', async () => { + const { rows, warnings } = await convert([ + q('horizontal', 'select_multiple yn'), + ]); + expect(theme(rows)).toBe(''); + expect(warnings.length).toBeGreaterThan(0); + }); + + test('round trip: bootstrap_buttons comes back as horizontal', async () => { + for (const appearance of ['horizontal', 'horizontal-compact']) { + const { tsv } = await convert([q(appearance)]); + const back = await lstsvToXlsform(tsv); + const row = back.survey.find((r) => r.name === 'q1'); + expect(row?.type).toBe('select_one q1'); + // Both give the same theme; the first registered appearance is the way back. + expect(row?.appearance).toBe('horizontal'); + } + }); +});