From db98b66c131ab1471a37769da294a324b6caf37f Mon Sep 17 00:00:00 2001 From: jstet Date: Wed, 4 Nov 2026 19:29:59 +0100 Subject: [PATCH] =?UTF-8?q?feat(lstsv):=20appearance=3Dautocomplete=20?= =?UTF-8?q?=E2=86=92=20searchable=20bootstrap=5Fdropdown=20(#226)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit An appearance can now select a LimeSurvey question theme through a new registry Appearance field, lsQuestionTheme {name, attributes?}: the name goes to the Q row's question_theme_name, each attribute to a column of its own. autocomplete on select_one / select_one_from_file becomes `!` + question_theme_name=bootstrap_dropdown + show_search=true, LimeSurvey's core searchable dropdown; minimal stays a plain `!`. The way back reads a Q row whose theme and attributes match as that appearance (show_search `1` or `true`); `!` without the theme stays minimal. This replaces the lsReverse flag. The convention text no longer says LimeSurvey has no built-in search, and the cdlvocab- cssclass is described as provenance only. Co-Authored-By: Claude Opus 5.5 --- ARCHITECTURE.md | 2 +- README.md | 11 +- codegen/emit_ts.py | 11 +- registry/conventions/externalCodeList.jsonld | 4 +- registry/root.jsonld | 9 +- registry/schema.jsonld | 6 +- src/conventions/questionTheme.ts | 53 ++++++ src/generated/Appearances.ts | 11 +- src/generated/conventions.json | 4 +- src/generated/conventions.ts | 4 +- src/instrument/lstsvTypes.ts | 16 +- src/lstsv/columns.ts | 9 + src/pipelines/lstsv2xlsform/README.md | 3 +- .../xlsform2lstsv/appearanceHandler.ts | 42 ++++- src/pipelines/xlsform2lstsv/index.ts | 1 + .../live/limesurvey/test_lstsv_attributes.py | 4 + tests/ts/integration/cli.test.ts | 5 +- tests/ts/unit/longFileList.test.ts | 19 +- tests/ts/unit/questionTheme.test.ts | 167 ++++++++++++++++++ 19 files changed, 336 insertions(+), 45 deletions(-) create mode 100644 src/conventions/questionTheme.ts create mode 100644 tests/ts/unit/questionTheme.test.ts diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 6248bf1..4a93808 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -36,7 +36,7 @@ The TypeScript library (`@correlaid/formtransform`), split into **format modules - **`src/instrument/`** — the parsed survey model (`types.ts`) and its parsers (`fromXlsform.ts`, `fromLstsv.ts`). Shared by every pipeline; it imports no format module or pipeline. See [The Instrument model](#the-instrument-model-69). -- **`src/conventions/`** — one module per registry convention (`other.ts`, `fromFile.ts`, `exclusive.ts`, `grid.ts`, `metadata.ts`). Each reads its values from `src/generated/conventions` and exposes helpers; every format module and pipeline imports them from here. No convention value (suffix, choice code, label, prefix) is written out anywhere else, which `tests/ts/unit/conventionLiterals.test.ts` enforces. +- **`src/conventions/`** — one module per registry convention (`other.ts`, `fromFile.ts`, `exclusive.ts`, `grid.ts`, `metadata.ts`). Each reads its values from `src/generated/conventions` and exposes helpers; every format module and pipeline imports them from here. No convention value (suffix, choice code, label, prefix) is written out anywhere else, which `tests/ts/unit/conventionLiterals.test.ts` enforces. `questionTheme.ts` is the one module for a registry field rather than a convention: an appearance's LimeSurvey question theme (`lsQuestionTheme`), shared by the forward emitter and the reverse type resolver. #### Pipelines diff --git a/README.md b/README.md index 8187283..6f90106 100644 --- a/README.md +++ b/README.md @@ -334,11 +334,12 @@ codes (`DE`). Any other code (a 12-digit regional key, `059700040040`) gets a file is reordered or rows are added or removed (`convention:externalCodeList`, `limesurveyCodes`). The mapping beside the TSV (see `--sanitize` below) records each derived code, and `lstsv2ddi --data` writes the file's own codes back. -`appearance: minimal` or `autocomplete` makes the question a LimeSurvey -dropdown instead of a radio list. LimeSurvey's dropdown has no search: its -`cssclass` `cdlvocab-` records where the options came from (the -way back reads it), and it is where a LimeSurvey theme can hook in a -searchable dropdown. formtransform ships no such theme. +`appearance: minimal` makes the question a LimeSurvey dropdown instead of a +radio list. `appearance: autocomplete` makes it a dropdown the respondent can +search by typing: LimeSurvey's core question theme `bootstrap_dropdown` with +`show_search=true` (no plugin needed), which suits a long list. Its `cssclass` +`cdlvocab-` only records where the options came from (the way +back reads it). An exclusive answer in a `select_multiple` ("Keine Angabe", "Nichts davon") is marked with an `exclusive` column (`yes`) on the choices sheet, not a diff --git a/codegen/emit_ts.py b/codegen/emit_ts.py index 3401cff..251fbd9 100644 --- a/codegen/emit_ts.py +++ b/codegen/emit_ts.py @@ -259,8 +259,11 @@ def generate_appearances(registry: dict[str, Any], output: Path): " lsTypeOverride?: string;", " /** False when a row bearing this appearance stores no response (matrix header). */", " carriesData?: boolean;", - " /** False when the way back from LimeSurvey writes another appearance for its override. */", - " lsReverse?: boolean;", + " /**", + " * LimeSurvey question theme the appearance selects: `name` goes to the Q row's", + " * `question_theme_name`, each of `attributes` to a column of its own.", + " */", + " lsQuestionTheme?: { name: string; attributes?: Record };", "}", "", "export const APPEARANCES: Record = {", @@ -302,8 +305,8 @@ def expand_types(types: list[str]) -> list[str]: # Only emitted when explicitly false — absence means "carries data". if data.get("carriesData") is False: lines.append(" carriesData: false,") - if data.get("lsReverse") is False: - lines.append(" lsReverse: false,") + if data.get("lsQuestionTheme"): + lines.append(f" lsQuestionTheme: {json.dumps(data['lsQuestionTheme'])},") lines.append(" },") lines.append("};") lines.append("") diff --git a/registry/conventions/externalCodeList.jsonld b/registry/conventions/externalCodeList.jsonld index 545e756..16fc3ce 100644 --- a/registry/conventions/externalCodeList.jsonld +++ b/registry/conventions/externalCodeList.jsonld @@ -33,9 +33,9 @@ "xlsformTypePattern": "^select_(one|multiple)_from_file (?P[^ ]+\\.csv)$", "ddiVocabFromFilename": "stripExtension", "ddiEmission": "concept[@vocab=''] in place of inline catgry; catgry MUST NOT be emitted", - "limesurveyEmission": "base select (L/M) with the vocabulary's options inlined as A/SQ rows + cssclass='cdlvocab-' carrying provenance (a registered LimeSurvey question attribute, so it survives import). appearance minimal or autocomplete makes a select_one a dropdown (!) instead of a radio list", + "limesurveyEmission": "base select (L/M) with the vocabulary's options inlined as A/SQ rows + cssclass='cdlvocab-' carrying provenance (a registered LimeSurvey question attribute, so it survives import). appearance minimal makes a select_one a dropdown (!) instead of a radio list; appearance autocomplete makes it a searchable dropdown: ! with LimeSurvey's core question theme bootstrap_dropdown and show_search=true (appearance:autocomplete lsQuestionTheme), which suits a long list", "limesurveyCssClassPrefix": "cdlvocab-", - "limesurveyCssClassPurpose": "A machine hook, not styling: it records which vocabulary the options came from (the way back reads it as select_*_from_file .csv), and it is where a LimeSurvey theme can attach a searchable dropdown to a long list (`.cdlvocab- select`). formtransform ships no such theme", + "limesurveyCssClassPurpose": "A machine hook, not styling: it records which vocabulary the options came from (the way back reads it as select_*_from_file .csv). It has no styling effect and is not needed for search: the searchable dropdown comes from appearance autocomplete", "limesurveyCodes": { "rule": "An option code that already fits LimeSurvey (convention:sanitization choiceCode: pattern and maxLength) is kept. Every other one gets a code derived from the code itself, never from its row: hash(code) in base 36, maxLength characters. The codes are the same whatever the order of the file or which rows are added or removed; a collision (with a kept code or an earlier hashed one, case-insensitively, codes taken in sorted order) re-hashes ``, n = 1, 2, …", "hash": "fnv1a32", diff --git a/registry/root.jsonld b/registry/root.jsonld index 2bd4daa..e4e102b 100644 --- a/registry/root.jsonld +++ b/registry/root.jsonld @@ -137,9 +137,14 @@ "select_one", "select_one_from_file" ], - "lsEffect": "Override LS type from L to ! (a dropdown; LimeSurvey has no built-in search, see convention:externalCodeList limesurveyCssClassPurpose)", + "lsEffect": "Override LS type from L to ! with LimeSurvey's core question theme bootstrap_dropdown and its show_search attribute: a dropdown the respondent can search by typing", "lsTypeOverride": "!", - "lsReverse": false + "lsQuestionTheme": { + "name": "bootstrap_dropdown", + "attributes": { + "show_search": "true" + } + } }, { "@id": "appearance:multiline", diff --git a/registry/schema.jsonld b/registry/schema.jsonld index 611b4f2..6ab96e5 100644 --- a/registry/schema.jsonld +++ b/registry/schema.jsonld @@ -899,13 +899,13 @@ ], "description": "False when a row bearing this appearance is presentation-only and stores no response (the matrix header row): it must not become a DDI variable. Absent means the row carries data as usual." }, - "lsReverse": { - "type": "boolean", + "lsQuestionTheme": { + "type": "object", "required": false, "consumedBy": [ "ls-transformer" ], - "description": "False when the way back from LimeSurvey must not write this appearance for its lsTypeOverride, because another appearance has the same override (autocomplete and minimal both give `!`; the way back writes minimal). Absent means it does." + "description": "`{name, attributes?}`: the LimeSurvey question theme this appearance selects, written to the Q row as `question_theme_name` = `name`, plus each of `attributes` (theme attribute → value) as a column of its own; LimeSurvey's TSV import sets the theme from `question_theme_name` and stores the other columns as question attributes. Applies where `validForTypes` allows, together with `lsTypeOverride` if any (autocomplete: `!` + bootstrap_dropdown + show_search=true). The way back writes this appearance for a Q row whose `question_theme_name` and attributes match (and whose type is `lsTypeOverride`, when set); a row with the override but not the theme reads back as the appearance that has the override and no theme (minimal)." } } }, diff --git a/src/conventions/questionTheme.ts b/src/conventions/questionTheme.ts new file mode 100644 index 0000000..f53d14b --- /dev/null +++ b/src/conventions/questionTheme.ts @@ -0,0 +1,53 @@ +/** + * An appearance can select a LimeSurvey question theme (registry Appearance + * `lsQuestionTheme`): `name` goes to the Q row's `question_theme_name`, each + * theme attribute to a column of its own. `autocomplete` → `!` + + * `bootstrap_dropdown` + `show_search=true`, LimeSurvey's searchable dropdown + * (#226). LimeSurvey's TSV import sets the theme from `question_theme_name` + * and stores the other columns as question attributes. + */ +import { APPEARANCES } from '../generated/Appearances.js'; + +type Row = Record; + +/** The structure-TSV column naming a Q row's LimeSurvey question theme. */ +export const QUESTION_THEME_COLUMN = 'question_theme_name'; + +function cell(row: Row, key: string): string { + return (row[key] ?? '').trim(); +} + +/** Appearances that select a LimeSurvey question theme (registry `lsQuestionTheme`). */ +const THEMED_APPEARANCES = Object.entries(APPEARANCES).filter( + ([, spec]) => spec.lsQuestionTheme, +); + +/** A theme attribute value as LimeSurvey may store a boolean (`true` / `1`). */ +function themeValue(value: string): string { + const v = value.trim().toLowerCase(); + return v === '1' ? 'true' : v; +} + +/** + * The appearance whose question theme and theme attributes this Q row carries + * (`!` + `bootstrap_dropdown` + `show_search=true` → `autocomplete`), if any. + */ +export function themedAppearanceOf( + lsCode: string, + base: string, + row: Row, +): string | undefined { + const theme = cell(row, QUESTION_THEME_COLUMN); + if (!theme) return undefined; + for (const [name, spec] of THEMED_APPEARANCES) { + const t = spec.lsQuestionTheme!; + if (t.name !== theme) continue; + if (spec.lsTypeOverride && spec.lsTypeOverride !== lsCode) continue; + if (spec.validForTypes && !spec.validForTypes.includes(base)) continue; + const attrs = Object.entries(t.attributes ?? {}); + if (attrs.every(([k, v]) => themeValue(cell(row, k)) === themeValue(v))) { + return name; + } + } + return undefined; +} diff --git a/src/generated/Appearances.ts b/src/generated/Appearances.ts index cbee12c..371e3e2 100644 --- a/src/generated/Appearances.ts +++ b/src/generated/Appearances.ts @@ -12,8 +12,11 @@ export interface AppearanceSpec { lsTypeOverride?: string; /** False when a row bearing this appearance stores no response (matrix header). */ carriesData?: boolean; - /** False when the way back from LimeSurvey writes another appearance for its override. */ - lsReverse?: boolean; + /** + * LimeSurvey question theme the appearance selects: `name` goes to the Q row's + * `question_theme_name`, each of `attributes` to a column of its own. + */ + lsQuestionTheme?: { name: string; attributes?: Record }; } export const APPEARANCES: Record = { @@ -28,9 +31,9 @@ export const APPEARANCES: Record = { supported: true, behavior: "handled", validForTypes: ["select_one", "select_one_from_file"], - lsEffect: "Override LS type from L to ! (a dropdown; LimeSurvey has no built-in search, see convention:externalCodeList limesurveyCssClassPurpose)", + lsEffect: "Override LS type from L to ! with LimeSurvey's core question theme bootstrap_dropdown and its show_search attribute: a dropdown the respondent can search by typing", lsTypeOverride: "!", - lsReverse: false, + lsQuestionTheme: {"name": "bootstrap_dropdown", "attributes": {"show_search": "true"}}, }, "multiline": { supported: true, diff --git a/src/generated/conventions.json b/src/generated/conventions.json index d2d790a..8364ae5 100644 --- a/src/generated/conventions.json +++ b/src/generated/conventions.json @@ -428,9 +428,9 @@ "xlsformTypePattern": "^select_(one|multiple)_from_file (?P[^ ]+\\.csv)$", "ddiVocabFromFilename": "stripExtension", "ddiEmission": "concept[@vocab=''] in place of inline catgry; catgry MUST NOT be emitted", - "limesurveyEmission": "base select (L/M) with the vocabulary's options inlined as A/SQ rows + cssclass='cdlvocab-' carrying provenance (a registered LimeSurvey question attribute, so it survives import). appearance minimal or autocomplete makes a select_one a dropdown (!) instead of a radio list", + "limesurveyEmission": "base select (L/M) with the vocabulary's options inlined as A/SQ rows + cssclass='cdlvocab-' carrying provenance (a registered LimeSurvey question attribute, so it survives import). appearance minimal makes a select_one a dropdown (!) instead of a radio list; appearance autocomplete makes it a searchable dropdown: ! with LimeSurvey's core question theme bootstrap_dropdown and show_search=true (appearance:autocomplete lsQuestionTheme), which suits a long list", "limesurveyCssClassPrefix": "cdlvocab-", - "limesurveyCssClassPurpose": "A machine hook, not styling: it records which vocabulary the options came from (the way back reads it as select_*_from_file .csv), and it is where a LimeSurvey theme can attach a searchable dropdown to a long list (`.cdlvocab- select`). formtransform ships no such theme", + "limesurveyCssClassPurpose": "A machine hook, not styling: it records which vocabulary the options came from (the way back reads it as select_*_from_file .csv). It has no styling effect and is not needed for search: the searchable dropdown comes from appearance autocomplete", "limesurveyCodes": { "rule": "An option code that already fits LimeSurvey (convention:sanitization choiceCode: pattern and maxLength) is kept. Every other one gets a code derived from the code itself, never from its row: hash(code) in base 36, maxLength characters. The codes are the same whatever the order of the file or which rows are added or removed; a collision (with a kept code or an earlier hashed one, case-insensitively, codes taken in sorted order) re-hashes ``, n = 1, 2, …", "hash": "fnv1a32", diff --git a/src/generated/conventions.ts b/src/generated/conventions.ts index 8cbc558..5afe328 100644 --- a/src/generated/conventions.ts +++ b/src/generated/conventions.ts @@ -437,9 +437,9 @@ const conventions = { "xlsformTypePattern": "^select_(one|multiple)_from_file (?P[^ ]+\\.csv)$", "ddiVocabFromFilename": "stripExtension", "ddiEmission": "concept[@vocab=''] in place of inline catgry; catgry MUST NOT be emitted", - "limesurveyEmission": "base select (L/M) with the vocabulary's options inlined as A/SQ rows + cssclass='cdlvocab-' carrying provenance (a registered LimeSurvey question attribute, so it survives import). appearance minimal or autocomplete makes a select_one a dropdown (!) instead of a radio list", + "limesurveyEmission": "base select (L/M) with the vocabulary's options inlined as A/SQ rows + cssclass='cdlvocab-' carrying provenance (a registered LimeSurvey question attribute, so it survives import). appearance minimal makes a select_one a dropdown (!) instead of a radio list; appearance autocomplete makes it a searchable dropdown: ! with LimeSurvey's core question theme bootstrap_dropdown and show_search=true (appearance:autocomplete lsQuestionTheme), which suits a long list", "limesurveyCssClassPrefix": "cdlvocab-", - "limesurveyCssClassPurpose": "A machine hook, not styling: it records which vocabulary the options came from (the way back reads it as select_*_from_file .csv), and it is where a LimeSurvey theme can attach a searchable dropdown to a long list (`.cdlvocab- select`). formtransform ships no such theme", + "limesurveyCssClassPurpose": "A machine hook, not styling: it records which vocabulary the options came from (the way back reads it as select_*_from_file .csv). It has no styling effect and is not needed for search: the searchable dropdown comes from appearance autocomplete", "limesurveyCodes": { "rule": "An option code that already fits LimeSurvey (convention:sanitization choiceCode: pattern and maxLength) is kept. Every other one gets a code derived from the code itself, never from its row: hash(code) in base 36, maxLength characters. The codes are the same whatever the order of the file or which rows are added or removed; a collision (with a kept code or an earlier hashed one, case-insensitively, codes taken in sorted order) re-hashes ``, n = 1, 2, …", "hash": "fnv1a32", diff --git a/src/instrument/lstsvTypes.ts b/src/instrument/lstsvTypes.ts index 9a36340..b0272af 100644 --- a/src/instrument/lstsvTypes.ts +++ b/src/instrument/lstsvTypes.ts @@ -5,6 +5,7 @@ */ import { APPEARANCES } from '../generated/Appearances.js'; import { TYPE_MAPPINGS } from '../generated/TypeMappings.js'; +import { themedAppearanceOf } from '../conventions/questionTheme.js'; type Row = Record; @@ -83,11 +84,14 @@ for (const [xfType, m] of Object.entries(TYPE_MAPPINGS)) { } } -/** Appearance name → LS type-override code it produces (e.g. `minimal` → `!`). */ +/** + * Appearance name → LS type-override code it produces (e.g. `minimal` → `!`). + * An appearance that also selects a question theme is told apart by that + * theme (see `themedAppearanceOf`), so the bare code reads as the other one. + */ const APPEARANCE_BY_OVERRIDE: Record = {}; for (const [name, spec] of Object.entries(APPEARANCES)) { - // `lsReverse: false`: another appearance has the override (autocomplete → `!` → minimal). - if (spec.lsTypeOverride && spec.lsReverse !== false) { + if (spec.lsTypeOverride && !spec.lsQuestionTheme) { APPEARANCE_BY_OVERRIDE[spec.lsTypeOverride] = name; } } @@ -100,6 +104,12 @@ export interface ResolvedType { /** Resolve a Q-row's `type/scale` (+ attribute hints) to an XLSForm type. */ export function resolveType(lsCode: string, row: Row): ResolvedType { + const resolved = resolveBaseType(lsCode, row); + const themed = themedAppearanceOf(lsCode, resolved.base, row); + return themed ? { ...resolved, appearance: themed } : resolved; +} + +function resolveBaseType(lsCode: string, row: Row): ResolvedType { const dateFormat = cell(row, 'date_format'); const overrideAppearance = APPEARANCE_BY_OVERRIDE[lsCode]; if (overrideAppearance) { diff --git a/src/lstsv/columns.ts b/src/lstsv/columns.ts index 3447042..d598181 100644 --- a/src/lstsv/columns.ts +++ b/src/lstsv/columns.ts @@ -53,6 +53,13 @@ export const BASE_COLUMNS = [ * - `other_replace_text`: the label of the native "other" answer's text box, * carrying the XLSForm `_other` companion's label (convention:other). * + * - `question_theme_name`, `show_search`: the LimeSurvey question theme an + * appearance selects and that theme's attributes (registry + * `lsQuestionTheme`): `autocomplete` → `bootstrap_dropdown` with + * `show_search=true`, a searchable dropdown. LimeSurvey's import sets the + * theme from `question_theme_name` and stores the other columns as + * question attributes. + * * A registry attribute missing here would be dropped silently; a test checks * the registry against this list. */ @@ -72,6 +79,8 @@ export const ATTRIBUTE_COLUMNS = [ 'array_filter', 'em_validation_q_tip', 'other_replace_text', + 'question_theme_name', + 'show_search', ] as const; export type BaseColumn = (typeof BASE_COLUMNS)[number]; diff --git a/src/pipelines/lstsv2xlsform/README.md b/src/pipelines/lstsv2xlsform/README.md index 1fff381..5fb2d19 100644 --- a/src/pipelines/lstsv2xlsform/README.md +++ b/src/pipelines/lstsv2xlsform/README.md @@ -41,7 +41,8 @@ CLI: `formtransform lstsv2xlsform `. | `other=Y` (+ `other_replace_text`) | re-add the `other` choice + `${base}_other` companion + relevance; the companion's label is `other_replace_text`, else the canonical one | shares `OTHER_CODE`/`OTHER_SUFFIX`/`otherLabelFor` with `lstsv/toVariables.ts` | | `cssclass=cdlvocab-` | `select_*_from_file .csv`, inlined A rows dropped | shares `vocabFromCssClass` with the DDI path | | `mandatory=Y` / `default` | `required: yes` / `default` | direct | -| type override `!` / `T` | `appearance: minimal` / `multiline` | inverts `APPEARANCES[*].lsTypeOverride` — registry-driven, not hardcoded; `autocomplete` (also `!`, `lsReverse: false`) comes back as `minimal` | +| type override `!` / `T` | `appearance: minimal` / `multiline` | inverts `APPEARANCES[*].lsTypeOverride` — registry-driven, not hardcoded | +| `question_theme_name` (+ theme attributes) | the appearance whose `lsQuestionTheme` matches: `!` + `bootstrap_dropdown` + `show_search=true` → `autocomplete` | inverts `APPEARANCES[*].lsQuestionTheme`; `bootstrap_dropdown` without `show_search=true` stays `minimal` | | F + SQ + A | `begin_group appearance=table-list` + child `select_one`s | inverts the grid → F encoding | | SL welcome/end text | `note` named `welcome` / `end` | inverts note promotion | | per-language rows | `label::` / `hint::` | direct | diff --git a/src/pipelines/xlsform2lstsv/appearanceHandler.ts b/src/pipelines/xlsform2lstsv/appearanceHandler.ts index c5d85f5..bb23465 100644 --- a/src/pipelines/xlsform2lstsv/appearanceHandler.ts +++ b/src/pipelines/xlsform2lstsv/appearanceHandler.ts @@ -1,4 +1,6 @@ import { APPEARANCES } from '../../generated/Appearances.js'; +import type { AppearanceSpec } from '../../generated/Appearances.js'; +import { QUESTION_THEME_COLUMN } from '../../conventions/questionTheme.js'; import { LSType } from './typeMapper.js'; import { consoleWarning } from '../../diagnostics.js'; import type { WarningHandler } from '../../diagnostics.js'; @@ -38,13 +40,39 @@ export class AppearanceHandler { * Mutates `lsType.type` in place. */ applyTypeOverrides(lsType: LSType, appearance: string, base: string): void { - if (!appearance) return; - for (const part of appearance.split(/\s+/)) { - const spec = APPEARANCES[part]; - if (!spec?.lsTypeOverride) continue; - if (!spec.validForTypes || spec.validForTypes.includes(base)) { - lsType.type = spec.lsTypeOverride; - } + for (const spec of applicable(appearance, base)) { + if (spec.lsTypeOverride) lsType.type = spec.lsTypeOverride; + } + } + + /** + * 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. + */ + themeAttributes(appearance: string, base: string): Record { + let columns: Record = {}; + for (const spec of applicable(appearance, base)) { + const theme = spec.lsQuestionTheme; + if (!theme) continue; + columns = { + [QUESTION_THEME_COLUMN]: theme.name, + ...(theme.attributes ?? {}), + }; } + return columns; } } + +/** The registered appearances in `appearance` that are valid on `base`. */ +function applicable(appearance: string, base: string): AppearanceSpec[] { + if (!appearance) return []; + return appearance + .split(/\s+/) + .map((part) => APPEARANCES[part]) + .filter( + (spec): spec is AppearanceSpec => + !!spec && (!spec.validForTypes || spec.validForTypes.includes(base)), + ); +} diff --git a/src/pipelines/xlsform2lstsv/index.ts b/src/pipelines/xlsform2lstsv/index.ts index b308247..c42ad18 100644 --- a/src/pipelines/xlsform2lstsv/index.ts +++ b/src/pipelines/xlsform2lstsv/index.ts @@ -636,6 +636,7 @@ class Conversion { ), ...fields.answerBounds, ...this.arrayFilterAttribute(questionName), + ...this.appearanceHandler.themeAttributes(appearance, xfTypeInfo.base), }, }; diff --git a/tests/live/limesurvey/test_lstsv_attributes.py b/tests/live/limesurvey/test_lstsv_attributes.py index 73bbbe4..b544386 100644 --- a/tests/live/limesurvey/test_lstsv_attributes.py +++ b/tests/live/limesurvey/test_lstsv_attributes.py @@ -134,6 +134,10 @@ def test_long_file_list_dropdown_with_derived_codes(limesurvey_client: Client, t try: q = _questions(limesurvey_client, survey_id)["kommune"] assert q["type"] == "!" + # autocomplete: LimeSurvey's searchable dropdown theme (#226). + props = limesurvey_client.get_question_properties(q["qid"], settings=["question_theme_name"]) + assert props.get("question_theme_name") == "bootstrap_dropdown", props + assert _attributes(limesurvey_client, q["qid"]).get("show_search") == "true" options = limesurvey_client.get_question_properties(q["qid"], settings=["answeroptions"])["answeroptions"] # Every derived code arrived unchanged (LimeSurvey stores varchar(5)), # and the mapping gives each one its file code back. diff --git a/tests/ts/integration/cli.test.ts b/tests/ts/integration/cli.test.ts index 3a0b017..f7a7e3a 100644 --- a/tests/ts/integration/cli.test.ts +++ b/tests/ts/integration/cli.test.ts @@ -509,7 +509,10 @@ describe('a long select_one_from_file list (#188)', () => { expect(r.stderr).toContain('50 code(s) of kommunen.csv'); expect(r.stderr).toContain('kommunen_form.mapping.json'); const tsv = rowsOf(readFileSync(out, 'utf-8')); - expect(tsv.find((x) => x.class === 'Q')?.['type/scale']).toBe('!'); + const q = tsv.find((x) => x.class === 'Q'); + expect(q?.['type/scale']).toBe('!'); + expect(q?.question_theme_name).toBe('bootstrap_dropdown'); + expect(q?.show_search).toBe('true'); const lsCode = tsv.filter((x) => x.class === 'A')[7].name; writeFileSync(join(dir, 'export.csv'), `id,kommune\n1,${lsCode}\n`); diff --git a/tests/ts/unit/longFileList.test.ts b/tests/ts/unit/longFileList.test.ts index bfe6a41..2079a18 100644 --- a/tests/ts/unit/longFileList.test.ts +++ b/tests/ts/unit/longFileList.test.ts @@ -163,14 +163,17 @@ describe('select_one_from_file with a long list', () => { }, ); - test('the way back reads the dropdown as minimal', async () => { - const { tsv } = await convert(survey('autocomplete'), file); - const back = lstsvToXlsform(tsv, { skipValidation: true }); - expect(back.survey[0]).toMatchObject({ - type: 'select_one_from_file kommunen.csv', - appearance: 'minimal', - }); - }); + test.each(['autocomplete', 'minimal'])( + 'the way back reads the dropdown as %s (#226)', + async (appearance) => { + const { tsv } = await convert(survey(appearance), file); + const back = lstsvToXlsform(tsv, { skipValidation: true }); + expect(back.survey[0]).toMatchObject({ + type: 'select_one_from_file kommunen.csv', + appearance, + }); + }, + ); test('a registered vocabulary whose codes fit keeps them', async () => { const { mapping } = await xlsformToLstsvWithMapping( diff --git a/tests/ts/unit/questionTheme.test.ts b/tests/ts/unit/questionTheme.test.ts new file mode 100644 index 0000000..cdc6eb7 --- /dev/null +++ b/tests/ts/unit/questionTheme.test.ts @@ -0,0 +1,167 @@ +/** + * #226: an appearance can select a LimeSurvey question theme (registry + * `lsQuestionTheme`). `autocomplete` → `!` + `question_theme_name = + * bootstrap_dropdown` + `show_search = true`, LimeSurvey's searchable + * dropdown; `minimal` stays a plain `!`. The way back reads the theme. + */ +import { describe, expect, test } from 'vitest'; + +import { + APPEARANCES, + lstsvToDdi, + lstsvToXlsform, + parseLstsv, + validateLstsvSubset, + xlsformToLstsv, +} from '../../../src/index.js'; +import { ATTRIBUTE_COLUMNS } from '../../../src/lstsv/columns.js'; + +const choices = [ + { list_name: 'land', name: 'de', label: 'Deutschland' }, + { list_name: 'land', name: 'fr', label: 'Frankreich' }, +]; + +const form = (type: string, appearance: string) => ({ + surveyData: [{ type, name: 'land', label: 'Land?', appearance }], + choicesData: choices, +}); + +const kommunen = [ + { list_name: 'kommunen.csv', name: '059700040040', label: 'Gemeinde A' }, + { list_name: 'kommunen.csv', name: '059700040041', label: 'Gemeinde B' }, +]; + +async function toTsv(type: string, appearance: string): Promise { + return xlsformToLstsv(form(type, appearance), { + fileChoices: { 'kommunen.csv': kommunen }, + onWarning: () => {}, + }); +} + +function questionRow(tsv: string): Record { + return parseLstsv(tsv).find((r) => r.class === 'Q')!; +} + +/** Rewrite one Q-row cell of a TSV (as a LimeSurvey export might differ). */ +function withCell(tsv: string, column: string, value: string): string { + const lines = tsv.split('\n'); + const header = lines[0].split('\t'); + const col = header.indexOf(column); + return lines + .map((line) => { + const cells = line.split('\t'); + if (cells[0] !== 'Q') return line; + cells[col] = value; + return cells.join('\t'); + }) + .join('\n'); +} + +describe('appearance → LimeSurvey question theme (#226)', () => { + test.each(['select_one land', 'select_one_from_file kommunen.csv'])( + '%s with autocomplete: ! + bootstrap_dropdown + show_search=true', + async (type) => { + const q = questionRow(await toTsv(type, 'autocomplete')); + expect(q['type/scale']).toBe('!'); + expect(q.question_theme_name).toBe('bootstrap_dropdown'); + expect(q.show_search).toBe('true'); + }, + ); + + test('minimal stays a plain dropdown: no theme columns at all', async () => { + const tsv = await toTsv('select_one land', 'minimal'); + expect(questionRow(tsv)['type/scale']).toBe('!'); + const header = tsv.split('\n')[0].split('\t'); + expect(header).not.toContain('question_theme_name'); + expect(header).not.toContain('show_search'); + }); + + test('minimal autocomplete: the searchable dropdown', async () => { + const q = questionRow( + await toTsv('select_one land', 'minimal autocomplete'), + ); + expect(q['type/scale']).toBe('!'); + expect(q.question_theme_name).toBe('bootstrap_dropdown'); + }); + + test('autocomplete on a type it is not valid for writes no theme', async () => { + const tsv = await toTsv('text', 'autocomplete'); + expect(questionRow(tsv)['type/scale']).toBe('S'); + expect(tsv.split('\n')[0]).not.toContain('question_theme_name'); + }); + + test('every theme column the registry names is a TSV column', () => { + const columns = new Set(ATTRIBUTE_COLUMNS); + for (const spec of Object.values(APPEARANCES)) { + const theme = spec.lsQuestionTheme; + if (!theme) continue; + expect(columns).toContain('question_theme_name'); + for (const attr of Object.keys(theme.attributes ?? {})) { + expect(columns).toContain(attr); + } + } + }); + + test('the lstsv subset validation accepts the theme columns', async () => { + const rows = parseLstsv(await toTsv('select_one land', 'autocomplete')); + expect(validateLstsvSubset(rows)).toEqual([]); + }); +}); + +describe('LimeSurvey question theme → appearance (#226)', () => { + test.each([ + ['select_one land', 'select_one land'], + ['select_one_from_file kommunen.csv', 'select_one_from_file kommunen.csv'], + ])('%s autocomplete round-trips as autocomplete', async (type, back) => { + const out = lstsvToXlsform(await toTsv(type, 'autocomplete'), { + skipValidation: true, + }); + expect(out.survey[0]).toMatchObject({ + type: back, + appearance: 'autocomplete', + }); + }); + + test('minimal round-trips as minimal', async () => { + const out = lstsvToXlsform(await toTsv('select_one land', 'minimal'), { + skipValidation: true, + }); + expect(out.survey[0]).toMatchObject({ appearance: 'minimal' }); + }); + + test('bootstrap_dropdown without show_search reads back as minimal', async () => { + const tsv = withCell( + await toTsv('select_one land', 'autocomplete'), + 'show_search', + '', + ); + const out = lstsvToXlsform(tsv, { skipValidation: true }); + expect(out.survey[0]).toMatchObject({ appearance: 'minimal' }); + }); + + test('show_search stored as 1 still reads back as autocomplete', async () => { + const tsv = withCell( + await toTsv('select_one land', 'autocomplete'), + 'show_search', + '1', + ); + const out = lstsvToXlsform(tsv, { skipValidation: true }); + expect(out.survey[0]).toMatchObject({ appearance: 'autocomplete' }); + }); + + test('another theme on a dropdown reads back as minimal', async () => { + const tsv = withCell( + await toTsv('select_one land', 'autocomplete'), + 'question_theme_name', + 'some_custom_theme', + ); + const out = lstsvToXlsform(tsv, { skipValidation: true }); + expect(out.survey[0]).toMatchObject({ appearance: 'minimal' }); + }); + + test('DDI from the TSV carries the appearance as autocomplete', async () => { + const ddi = lstsvToDdi(await toTsv('select_one land', 'autocomplete')); + expect(ddi).toMatch(/autocomplete/); + expect(ddi).not.toMatch(/bootstrap_dropdown/); + }); +});