Changelog

All notable changes to react-minimal-survey-builder will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.4.1] — 2026-03-02

✨ Added

file question type — new 17th built-in type providing a drag-and-drop file upload zone. Supports a click-to-browse fallback, multi-file selection, and all the features below:
- accept — comma-separated MIME types or file extensions passed to the native <input accept> attribute (e.g. ".pdf,image/*"). Enforced client-side in code — files that do not match are rejected with an inline error, even when dropped via drag-and-drop.
- maxFiles — maximum number of files (default 1). Values > 1 enable multi-file mode; the drop zone hides once the cap is reached.
- maxFileSize — per-file size limit in bytes. Oversized files are rejected with a human-readable error message (B / KB / MB).
- maxTotalSize — combined size cap across all selected files in bytes.
- All four constraints are enforced both in real-time in the renderer (shown as inline errors immediately on file selection or drop) and by the validation engine on next-page / submit.
FileAnswer interface — exported from the main entry point. Shape: { name: string; size: number; type: string; lastModified: number; file: File }. The file property is the raw browser File object for use in FormData upload calls.
matchesAccept helper (internal) — validates a file against accept tokens supporting three formats: extension (.pdf), MIME wildcard (image/*), and exact MIME (application/pdf). Rejects all three drag-drop / keyboard / paste paths, not just the file-picker UI.
Real-time inline file validation — DefaultFileInput now shows constraint violations immediately, without waiting for form submission:
- Wrong file type → error naming each rejected file and the allowed types.
- Per-file size exceeded → error naming oversized files and the limit.
- Total size exceeded → error showing the combined size vs. the cap.
- Max files exceeded → message showing how many could not be added.
- Drop zone border turns red on any active error.
File config panel in the builder — QuestionEditor now includes a File Upload settings section with inputs for accepted types, max files (slider, 1–20), max file size (MB), and max total size (MB).
FileAnswer[] in AnswerValue — the AnswerValue union now includes FileAnswer[].
Website documentation for file type — new /docs/types/file page covering all props, the FileAnswer interface, built-in vs. custom validation, onSubmit FormData walkthrough, cross-question validators example, and a session-only tip. Also updated: types overview grid, API types reference (Question, QuestionType, AnswerValue, new FileAnswer section), all-types example per-type table, navigation sidebar, and search index.
questionNumber on QuestionComponentProps — the optional questionNumber prop is now included in the QuestionComponentProps type and is passed to all custom components registered via the components prop, enabling custom components to render consistent question numbering without having to compute it themselves.

🚀 Improved

Custom component full rendering autonomy — components registered via the components prop now take complete control of their output. Previously, the QuestionRenderer would always inject a label, description paragraph, and error message around every custom component. Now, when a custom component is detected, the wrapper is bypassed entirely and the component is responsible for its own label, description, and error display. Built-in components continue to receive the automatic label/description/error wrapper.
questionNumber forwarded to built-in components — built-in question renderers now also receive questionNumber so custom and built-in rendering paths are consistent.

🔄 Changed

Custom validator function signature changed to 3 parameters (breaking for custom validators) — was (value: AnswerValue, answers: SurveyAnswers), now (value: AnswerValue, question: Question, answers: SurveyAnswers). The question parameter (second) gives access to the full question definition inside a validator. Update any existing validators by adding the question param:
```
// before
validator: (value, answers) =>
  value === answers["password"] ? null : "No match";
// after
validator: (value, _question, answers) =>
  value === answers["password"] ? null : "No match";
```
Affected types: ValidationRule.validator, SurveyOptions.validators, SurveyPlugin.validators.
BuiltInQuestionType union now includes "file" — 17 built-in types total (up from 16).
Question interface extended with accept?: string, maxFiles?: number, maxFileSize?: number, maxTotalSize?: number.
Types overview page description updated from 16 to 17 built-in types.
All-types example per-type answer table updated with file → FileAnswer[] row.
API types page updated: BuiltInQuestionType, Question, AnswerValue, import list, and new FileAnswer section.
QuestionComponentProps interface extended with questionNumber?: number.
Internal component declarations in QuestionRenderer, SurveyRenderer, SurveyBuilder, and QuestionEditor migrated from React.FC<Props> to inline destructured-parameter type annotations — no runtime impact, improves TypeScript inference in strict mode.

🐛 Fixed

accept enforcement was previously only cosmetic (browser file-picker filter). Files dropped via drag-and-drop or selected by bypassing the picker were silently accepted regardless of their type. Now any file that does not match the accept token list is rejected before being added to the answer, with a descriptive error.
Removed-file re-validation: deleting a file from the list now re-validates all remaining files for per-file size and total size constraints and clears the error if all remaining files are compliant.

[0.4.0] — 2026-02-23

✨ Added

URL question type — new url built-in type using the browser's native type="url" input. Brings up the correct keyboard on mobile and supports the new url validation rule. Default placeholder is "https://example.com". Answer value is a string.
Password question type — new password built-in type with a masked input and an optional show/hide toggle button. Controlled by the new passwordShowToggle property (defaults to true; set to false to always keep input masked). Answer value is a string.
URL validation rule — new url rule type that validates the value with new URL() and requires the protocol to be http: or https:.
controlType for boolean questions — new controlType property ("radio" | "switch" | "checkbox") controls how a boolean question is rendered. "radio" (default) shows two radio buttons, "switch" renders an accessible toggle with false/true labels on each side, and "checkbox" renders a single checkbox where the question label doubles as the inline checkbox text.
hideLabel question property — new hideLabel: boolean on the Question interface suppresses the label element (useful when controlType: "checkbox" already shows the label inline).
Boolean required enforcement for checkboxes — when a boolean question uses controlType: "checkbox" and required: true, validation now enforces value === true (the box must be checked). Useful for ToS agreements and consent flows.
Documentation pages — new full reference pages for url (/docs/types/url) and password (/docs/types/password) with options tables, validation examples, and practical code examples.
Per-type playground schemas — added dedicated playground example schemas for all 16 built-in question types (type-text, type-textarea, type-number, type-email, type-radio, type-checkbox, type-select, type-date, type-time, type-datetime, type-slider, type-phone, type-url, type-password, type-rating, type-boolean).
Customisable playground button label — OpenInPlaygroundButton now accepts an optional text prop to override the default "Open in Playground" label.

🔄 Changed

boolean answer value is now a native boolean (breaking change) — previously returned the strings "yes" / "no". Now returns true / false. Update any visibleIf expressions that referred to === 'yes' / === 'no' to use === true / === false.
BuiltInQuestionType union now includes "url" and "password" (16 built-in types total, up from 14).
ValidationRuleType union now includes "url".
Question interface extended with passwordShowToggle, controlType, and hideLabel properties.
QuestionRenderer component: the hideLabel prop has been removed from the component's props; use question.hideLabel in the schema instead.
Types overview page updated to list all 16 built-in types with new grid cards for URL and Password.
Boolean type documentation page rewritten to cover all three controlType variants, the new boolean answer value, and required checkbox enforcement.
Validation documentation page fully rewritten to cover all 11 built-in rule types (required, minLength, maxLength, pattern, min, max, email, url, phone, time, custom) with per-rule code examples, default error messages, and an "Applies to" column in the overview table.
Navigation sidebar and search index updated with entries for URL and Password type pages.
Conditional logic documentation examples updated from === 'yes' to === true for boolean comparisons.
Schema documentation page: boolean question answer type corrected from string to boolean.
FAQ and landing page bundle size figures updated to reflect the current ~13 KB gzipped size (was ~11 KB).
Demo page default schema now generates question IDs with uid() instead of hard-coded q1…q6.
banner.svg removed from the repository and from the npm publish file list.

🐛 Fixed

Boolean radio and switch components: option onChange now correctly emits true / false values instead of the string literals "yes" / "no".
QuestionEditor (builder): url and password question types were missing from the type dropdown.

[0.3.0] — 2026-02-18

✨ Added

Time question type — new time built-in type using the browser's native time picker. Supports minTime / maxTime constraints and timeFormat preference ("12h" / "24h"). Answer value is a string in HH:MM format.
Datetime question type — new datetime built-in type using a native datetime-local input for combined date and time selection. Supports minDatetime / maxDatetime constraints. Answer value is a string in YYYY-MM-DDTHH:MM format.
Slider question type — new slider built-in type rendering a range slider with configurable sliderMin, sliderMax, sliderStep, optional unit suffix, showValue toggle, and minLabel / maxLabel scale labels. Answer value is a number.
Phone question type — new phone built-in type using a native tel input with an optional countryCode prefix badge. Answer value is a string.
Phone validation rule — new phone validation rule type that validates phone numbers against a flexible pattern (7–20 digits with optional +, spaces, dashes, and parentheses).
Time validation rule — new time validation rule type that validates time strings against HH:MM / HH:MM:SS 24-hour format.
Builder support — all 4 new types added to the question type dropdown in QuestionEditor with type-specific settings panels (slider min/max/step/unit/showValue, phone country code, time format/min/max, datetime min/max).
Documentation pages — full reference pages for each new type at /docs/types/time, /docs/types/datetime, /docs/types/slider, and /docs/types/phone with options tables, validation examples, and practical code examples.

🔄 Changed

BuiltInQuestionType union now includes "time", "datetime", "slider", and "phone" (14 built-in types total).
ValidationRuleType union now includes "phone" and "time".
Question interface extended with sliderMin, sliderMax, sliderStep, showValue, unit, countryCode, timeFormat, minTime, maxTime, minDatetime, and maxDatetime properties.
Types overview page updated to show 14 built-in types with new grid cards.
Schema documentation page updated with new types in the Question interface and type reference table.
All-types example and playground schema updated with a new "Contact & Scheduling" page showcasing all 4 new types.
Navigation sidebar updated with links to the 4 new type documentation pages.

[0.2.0] — 2026-02-18

✨ Added

Boolean question type — new boolean built-in type rendering a Yes/No radio group with customizable labels via options. Answer value is "yes" or "no".
Rating display modes — new displayMode property on rating questions: "stars" (default, existing star UI) or "buttons" (numbered 1–N button scale with exact-match selection).
Rating scale labels — new minLabel and maxLabel properties for rating questions to display descriptive text at the low and high ends of the scale (e.g. "Not at all likely" / "Extremely likely"). Works with both display modes.
Rating builder controls — display mode toggle, dynamic count label ("Number of Stars" / "Number of Buttons"), and min/max label inputs in both the QuestionEditor component and the demo SettingsPanel.

🚀 Improved

Question-based progress bar — progress calculation changed from page-based to question-based (answered visible questions / total visible questions) in the playground and demo, matching the useSurvey hook behavior.
Playground validation — added full validation support to the playground PreviewRenderer including required, minLength, maxLength, min, max, email, and pattern rules with inline error display and validation on Next/Submit.
visibleIf regex — fixed condition expression parsing from \{(\w+)\} to \{([^}]+)\} to support hyphenated question IDs in visibleIf expressions.

🔄 Changed

BuiltInQuestionType union now includes "boolean" (10 built-in types total).
Question interface extended with displayMode, minLabel, and maxLabel properties.
Rating documentation page updated with new properties table, display mode examples, and scale label examples.

[0.1.0] — 2026-02-17

✨ Added

Headless survey engine — a fully headless, JSON-schema driven survey hook for React with zero heavy dependencies.
9 built-in question types — text, textarea, number, email, radio group, checkbox group, select dropdown, date picker, and star rating.
Configurable star rating — adjustable star count (2–10) with a visual slider in the builder and live preview.
Multi-page surveys — organize questions across multiple pages with independent titles and descriptions.
Page navigation — next, previous, and direct go-to-page controls with configurable back-navigation.
Progress tracking — automatic percentage-based progress calculated from answered visible questions, with an optional progress bar.
Conditional visibility — show or hide questions and entire pages based on dynamic expressions referencing other answers, supporting comparison, logical, and containment operators.
Validation engine — 8 built-in validation rules (required, min/max length, pattern, min/max value, email, custom) with per-rule custom error messages.
Custom validators — support for user-defined validation functions that receive the current answer and all survey answers.
Drag-and-drop survey builder — visual builder component with HTML5 native drag & drop for reordering questions within and across pages, with no external dependencies.
Drop indicator — visual placeholder line showing the exact drop position while dragging questions or palette items.
Page management in builder — add, remove, rename, and reorder pages directly from the builder UI.
Question editor panel — inline property editor for label, type, required toggle, placeholder, description, options, visibility conditions, default values, and advanced settings.
Live preview — real-time survey preview alongside the builder, rendered with the actual survey renderer.
JSON editor — raw JSON editing tab for direct schema manipulation with live parsing.
Builder layout options — horizontal (side-by-side) and vertical layout modes.
Controlled builder component — standard value / onChange pattern for external schema management.
Custom question types — extensible type system allowing arbitrary custom question types with full autocomplete support for built-in types.
Custom component overrides — override any built-in question renderer or register components for entirely new question types.
Plugin system — plugin architecture supporting custom renderers, validators, and event middleware.
Render props — full layout control via render-prop children, custom header, footer, and completion screen renderers.
Survey settings — configurable progress bar visibility, question numbering, navigation button text, and page-change validation behavior.
Default values — per-question default answers merged with optional initial answer data.
Async submit handling — built-in submit flow with success/error handling and inline error display.
Reset support — full survey state reset to initial values.
Completion screen — default thank-you screen after submission, fully customizable.
Framework-agnostic core — standalone core module (/core) for schema parsing, validation, condition evaluation, and state management without React.
Event system — subscribe to answer changes, page changes, validation, submission, and visibility change events with cleanup support.
Accessibility — ARIA attributes on inputs, error messages, radio/checkbox groups, rating buttons, and required indicators; semantic HTML labels throughout.
Full TypeScript support — TypeScript-first codebase with 24+ exported types and interfaces, generic component props, and strict typing.
Three entry points — main package, /core (framework-agnostic), and /builder (visual builder only), all supporting CJS, ESM, and TypeScript.
Tree-shakable — marked sideEffects: false for optimal bundling.
Lightweight — ~11kb gzipped total bundle size.
SSR compatible — no browser-only APIs; safe for server-side rendering.
Schema validation — descriptive error messages for malformed survey schemas.
Performance optimized — memoized components and schema parsing for minimal re-renders.

Template for future releases:

[x.y.z] — YYYY-MM-DD

✨ Added

New features.

🚀 Improved

Performance or UX enhancements.

🐛 Fixed

Bug fixes.

🔄 Changed

Behavioral or API changes (non-breaking).

❌ Removed

Removed features or deprecated APIs.

🔒 Security

Security-related patches.

⚠ Breaking Changes

Changes requiring consumer action to upgrade.