[Toolkit][Shadcn] Add questionnaire recipe

Author: ker0x

src/Toolkit/CHANGELOG.md

@@ -6,6 +6,7 @@
 - Add support for blocks: ready-to-use page sections built from a kit's components, installed and previewed as a unit
 - [Shadcn] Add the `login-01` and `login-02` login blocks
 - [Shadcn] Add `input-otp` recipe
+- [Shadcn] Add `questionnaire` recipe
 - [Shadcn] Add `menubar` recipe
 - [Shadcn] Add `navigation-menu` recipe
 - [Shadcn] Add `popover` recipe

src/Toolkit/kits/shadcn/questionnaire/README.md

@@ -0,0 +1,324 @@
+import { Controller } from '@hotwired/stimulus';
+
+const LETTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const DEFAULT_ERROR = 'Please answer this question.';
+
+export default class extends Controller {
+    static targets = [
+        'item',
+        'progress',
+        'progressCurrent',
+        'progressTotal',
+        'progressStep',
+        'answer',
+        'freeform',
+        'error',
+        'previous',
+        'skip',
+        'next',
+        'submit',
+    ];
+    static values = { activeItem: String, shortcuts: String };
+
+    // The freeform input shares its name with the fixed choices, so while it is empty its name is
+    // parked here to keep it from submitting a value that shadows the selected answer.
+    _freeformNames = new WeakMap();
+
+    freeformTargetConnected(input) {
+        this._freeformNames.set(input, input.getAttribute('name'));
+        this._syncFreeformName(input);
+    }
+
+    connect() {
+        this._assignShortcuts();
+
+        if (!this._itemByName(this.activeItemValue)) {
+            const [first] = this._navigableItems();
+            this.activeItemValue = first ? first.dataset.name : '';
+        }
+
+        this._render();
+    }
+
+    activeItemValueChanged() {
+        this._render();
+    }
+
+    next() {
+        if (!this._validate(this.activeItem)) return;
+
+        // Only promote to `answered`, so navigating past a skipped item does not undo the skip.
+        if (this._isAnswered(this.activeItem)) {
+            this._setStatus(this.activeItem, 'answered');
+        }
+        this._move(1);
+    }
+
+    previous() {
+        this._clearError(this.activeItem);
+        this._move(-1);
+    }
+
+    skip() {
+        const item = this.activeItem;
+        if (!item) return;
+
+        this._reset(item);
+        this._setStatus(item, 'skipped');
+        this._clearError(item);
+        this._move(1);
+    }
+
+    onSubmit(event) {
+        if (!this._validate(this.activeItem)) {
+            event.preventDefault();
+            return;
+        }
+
+        if (this._isAnswered(this.activeItem)) {
+            this._setStatus(this.activeItem, 'answered');
+        }
+    }
+
+    onAnswerChange(event) {
+        const item = this._itemOf(event.target);
+        if (!item || !this.answerTargets.includes(event.target)) return;
+
+        if (event.target.dataset.slot === 'questionnaire-choice-input') {
+            this._clearFreeform(item);
+        }
+
+        this._setStatus(item, this._isAnswered(item) ? 'answered' : 'unanswered');
+        this._clearError(item);
+        this._render();
+    }
+
+    onAnswerInput(event) {
+        const input = event.target;
+        if (!this.freeformTargets.includes(input)) return;
+
+        const item = this._itemOf(input);
+        if (!item) return;
+
+        this._syncFreeformName(input);
+
+        if (input.value && item.dataset.multiple !== 'true') {
+            this._choicesOf(item).forEach((choice) => (choice.checked = false));
+        }
+
+        this._setStatus(item, this._isAnswered(item) ? 'answered' : 'unanswered');
+        this._clearError(item);
+        this._render();
+    }
+
+    onKeyDown(event) {
+        if (event.metaKey || event.ctrlKey || event.altKey) return;
+
+        const item = this.activeItem;
+        if (!item) return;
+
+        if (event.key === 'Enter') {
+            if (event.target.type === 'submit') return;
+
+            event.preventDefault();
+            if (this._isLast(item)) {
+                this.element.requestSubmit();
+            } else {
+                this.next();
+            }
+            return;
+        }
+
+        if (this.freeformTargets.includes(event.target)) return;
+
+        const choice = this._choicesOf(item).find(
+            (input) => input.closest('[data-slot="questionnaire-choice"]')?.dataset.shortcut === event.key.toUpperCase()
+        );
+        if (!choice || choice.disabled) return;
+
+        event.preventDefault();
+        choice.checked = item.dataset.multiple === 'true' ? !choice.checked : true;
+        choice.dispatchEvent(new Event('change', { bubbles: true }));
+    }
+
+    get activeItem() {
+        return this._itemByName(this.activeItemValue);
+    }
+
+    _move(offset) {
+        const items = this._navigableItems();
+        const index = items.indexOf(this.activeItem);
+        const target = items[index + offset];
+
+        if (target) {
+            this.activeItemValue = target.dataset.name;
+        }
+    }
+
+    _render() {
+        const items = this._navigableItems();
+        const active = this.activeItem;
+
+        this.itemTargets.forEach((item) => {
+            const isActive = item === active;
+            item.dataset.active = isActive ? 'true' : 'false';
+            item.toggleAttribute('hidden', !isActive);
+            item.toggleAttribute('inert', !isActive);
+        });
+
+        const current = Math.max(items.indexOf(active) + 1, 1);
+        const total = Math.max(items.length, 1);
+
+        this.progressTargets.forEach((progress) => {
+            progress.setAttribute('aria-valuenow', String(current));
+            progress.setAttribute('aria-valuemax', String(total));
+        });
+        this.progressCurrentTargets.forEach((element) => (element.textContent = String(current)));
+        this.progressTotalTargets.forEach((element) => (element.textContent = String(total)));
+        this.progressStepTargets.forEach((step, index) => {
+            step.dataset.active = index < current ? 'true' : 'false';
+        });
+
+        const first = active === items[0];
+        const last = this._isLast(active);
+
+        this._toggle(this.previousTargets, !first);
+        this._toggle(this.skipTargets, Boolean(active) && active.dataset.required !== 'true');
+        this._toggle(this.nextTargets, !last);
+        this._toggle(this.submitTargets, last);
+    }
+
+    _toggle(elements, visible) {
+        elements.forEach((element) => {
+            element.toggleAttribute('hidden', !visible);
+            element.disabled = !visible;
+        });
+    }
+
+    _validate(item) {
+        if (!item || item.dataset.required !== 'true' || this._isAnswered(item)) return true;
+
+        this._showError(item);
+
+        return false;
+    }
+
+    _showError(item) {
+        item.setAttribute('aria-invalid', 'true');
+
+        const [error] = this._errorsOf(item);
+        if (!error) return;
+
+        if (!error.textContent.trim()) {
+            error.textContent = DEFAULT_ERROR;
+        }
+        error.removeAttribute('hidden');
+        item.setAttribute('aria-describedby', error.id);
+
+        const [answer] = this._answersOf(item).filter((input) => !input.disabled);
+        answer?.focus();
+    }
+
+    _clearError(item) {
+        if (!item) return;
+
+        item.removeAttribute('aria-invalid');
+        item.removeAttribute('aria-describedby');
+        this._errorsOf(item).forEach((error) => error.setAttribute('hidden', ''));
+    }
+
+    _reset(item) {
+        this._choicesOf(item).forEach((choice) => (choice.checked = false));
+        this._clearFreeform(item);
+    }
+
+    _clearFreeform(item) {
+        this._freeformOf(item).forEach((input) => {
+            input.value = '';
+            this._syncFreeformName(input);
+        });
+    }
+
+    _syncFreeformName(input) {
+        const name = this._freeformNames.get(input);
+        if (!name) return;
+
+        if (input.value.trim()) {
+            input.setAttribute('name', name);
+        } else {
+            input.removeAttribute('name');
+        }
+    }
+
+    _isAnswered(item) {
+        return (
+            this._choicesOf(item).some((choice) => choice.checked) ||
+            this._freeformOf(item).some((input) => input.value.trim())
+        );
+    }
+
+    _isLast(item) {
+        const items = this._navigableItems();
+
+        return !item || item === items[items.length - 1];
+    }
+
+    _setStatus(item, status) {
+        if (item) {
+            item.dataset.status = status;
+        }
+    }
+
+    _assignShortcuts() {
+        const mode = this.shortcutsValue;
+
+        this.itemTargets.forEach((item) => {
+            this._choicesOf(item).forEach((choice, index) => {
+                const label = choice.closest('[data-slot="questionnaire-choice"]');
+                if (!label) return;
+
+                const shortcut = mode === 'letters' ? LETTERS[index] : mode === 'numbers' ? String(index + 1) : null;
+
+                if (!shortcut) {
+                    delete label.dataset.shortcut;
+
+                    return;
+                }
+
+                label.dataset.shortcut = shortcut;
+                const badge = label.querySelector('[data-slot="questionnaire-choice-shortcut"]');
+                if (badge) {
+                    badge.textContent = shortcut;
+                }
+            });
+        });
+    }
+
+    _navigableItems() {
+        return this.itemTargets.filter((item) => !item.disabled);
+    }
+
+    _itemByName(name) {
+        return name ? this._navigableItems().find((item) => item.dataset.name === name) : undefined;
+    }
+
+    _itemOf(element) {
+        return this.itemTargets.find((item) => item.contains(element));
+    }
+
+    _answersOf(item) {
+        return this.answerTargets.filter((input) => item.contains(input));
+    }
+
+    _choicesOf(item) {
+        return this._answersOf(item).filter((input) => input.dataset.slot === 'questionnaire-choice-input');
+    }
+
+    _freeformOf(item) {
+        return this.freeformTargets.filter((input) => item.contains(input));
+    }
+
+    _errorsOf(item) {
+        return this.errorTargets.filter((error) => item.contains(error));
+    }
+}

src/Toolkit/kits/shadcn/questionnaire/assets/controllers/questionnaire_controller.js

@@ -0,0 +1,19 @@
+{
+    "$schema": "../../../schema-kit-recipe-v1.json",
+    "type": "component",
+    "name": "Questionnaire",
+    "version-added": "3.5",
+    "copy-files": {
+        "assets/": "assets/",
+        "templates/": "templates/"
+    },
+    "dependencies": {
+        "recipe": ["button"],
+        "composer": [
+            "twig/html-extra:^3.24.0",
+            "symfony/ux-icons",
+            "symfony/ux-twig-component:^3.5",
+            "tales-from-a-dev/twig-tailwind-extra:^1.3.0"
+        ]
+    }
+}

src/Toolkit/kits/shadcn/questionnaire/manifest.json

@@ -0,0 +1,20 @@
+{# @prop id string Unique identifier used to generate internal Questionnaire IDs. #}
+{# @prop defaultItem string Name of the `Questionnaire:Item` shown on initial render. #}
+{# @prop shortcuts 'letters'|'numbers'|null Keyboard shortcut style assigned to each answer. #}
+{# @block content The questionnaire structure, typically includes `Questionnaire:Progress`, `Questionnaire:Item` and `Questionnaire:Actions`. #}
+{%- props id = 'questionnaire', defaultItem = '', shortcuts = null -%}
+{%- do provide('questionnaire.id', id) -%}
+{%- do provide('questionnaire.defaultItem', defaultItem) -%}
+<form
+    id="{{ id }}"
+    data-slot="questionnaire"
+    data-questionnaire-active-item-value="{{ defaultItem }}"
+    data-questionnaire-shortcuts-value="{{ shortcuts }}"
+    {{ attributes.defaults({
+        class: 'flex w-full min-w-0 flex-col gap-4'|tailwind_classes,
+        'data-controller': 'questionnaire',
+        'data-action': 'keydown->questionnaire#onKeyDown submit->questionnaire#onSubmit change->questionnaire#onAnswerChange input->questionnaire#onAnswerInput',
+    }) }}
+>
+    {%- block content %}{% endblock -%}
+</form>

src/Toolkit/kits/shadcn/questionnaire/templates/components/Questionnaire.html.twig

@@ -0,0 +1,9 @@
+{# @block content The navigation buttons, typically `Questionnaire:Previous`, `Questionnaire:Skip`, `Questionnaire:Next` and `Questionnaire:Submit`. #}
+<div
+    data-slot="questionnaire-actions"
+    {{ attributes.defaults({
+        class: 'grid min-h-11 w-full grid-cols-[minmax(0,1fr)_auto_auto] items-center gap-2 sm:min-h-8'|tailwind_classes,
+    }) }}
+>
+    {%- block content %}{% endblock -%}
+</div>