@taylordb/forms-ui

React components and client-side runtime for TaylorDB conversational forms: one step at a time, keyboard-friendly navigation, optional autosave against a shared schema, and Typeform-style inputs.

Pair this package with @taylordb/forms-core for defineForm, shared step types, and validation that runs the same rules on the client and server. Core handlers do not validate; defineForm attaches default validators by field type when no custom validate is present, and you add validate on steps or composite fields to override defaults for product-specific rules.

Features

• Step flow: welcome screen, questions, statements, and end screen with progress and footer navigation.
• Bindings: answers keyed by step id; composite steps use name on child fields.
• Validation: optional shared sharedSteps from defineForm with built-in defaults, overridden by per-step / per-field validate in your schema (same code path client + server), or local <Question validate> for local-only forms. Handlers are not validators.
• Themes: light / dark or custom FormTheme tokens; bundled CSS via FormStyles.
• Autosave: createAutosaveBootstrap, createAutosaveAdapter, createFetchAutosaveClient, session storage helpers.
• UI locale: locale on <Form> / FormLocaleProvider, packaged locales/de and locales/ru, and useFormLocale() for built-in strings (footer, hints, placeholders). See docs/form-api.md.

Install

pnpm add @taylordb/forms-ui @taylordb/forms-core

Peer dependencies: react and react-dom 18+.

Dependencies (installed with this package): includes @radix-ui/react-select for Dropdown, react-phone-number-input for PhoneInput, zustand for form state, and @taylordb/forms-core.

Quick start

import { Form, Question, TextInput, Title, EndScreen } from '@taylordb/forms-ui'

export function Demo() {
  return (
    <Form keyboard theme="light" onSubmit={(answers) => console.log(answers)}>
      <Question id="name" required>
        <Title>Your name?</Title>
        <TextInput autoFocus placeholder="Ada Lovelace" />
      </Question>
      <EndScreen id="done" buttonText="Submit">
        <Title>Thanks!</Title>
      </EndScreen>
    </Form>
  )
}

UI locale (optional)

Built-in chrome (footer, OK row, dropdown search defaults, etc.) can follow a FormLocale object. Use locale on <Form> or import a pack:

import { Form } from '@taylordb/forms-ui'
import { deFormLocale } from '@taylordb/forms-ui/locales/de'

export function LocalizedDemo() {
  return (
    <Form keyboard locale={deFormLocale} theme="light" onSubmit={(answers) => console.log(answers)}>
      …
    </Form>
  )
}

Details: docs/form-api.md (section UI locale), useFormLocale, and FormLocaleProvider in docs/hooks-theming-exports.md.

Documentation

• example.md — end-to-end example aligned with the monorepo playground (autosave bootstrap provider, mappers, conditional steps, composites, ranking, media, legal).
• llm.txt — short index; follow links into docs/ for the full reference (components, hooks, autosave, pitfalls, custom questions).

Scale: what we support

Handler / question types (core registry)

@taylordb/forms-core ships a default typeHandlers map with 23 string keys (each maps to a value type for TypeScript and email HTML). Runtime defaults for these built-in keys are attached by defineForm, not by the handlers themselves, and the up-to-date source is packages/forms/core/src/types.ts (defaultValidateByType). They are:

text, email, rating, multipleChoice, short_text, long_text, deep_dive, website, number, phone_number, date, multiple_choice, dropdown, picture_choice, ranking, yes_no, checkbox, opinion_scale, nps, legal, file_upload, multi_format, address, contact_info

Not every key has a dedicated one-to-one JSX widget; several text-like types reuse TextInput / TextArea, and picture_choice uses MultipleChoice.Choice with an image prop.

Built-in answer inputs (this package)

There are 18 exported components that collect (or record) answers under a <Question id="…"> (or composite name fields):

| # | Component | Typical core type / notes | | --- | -------------------------------------------- | ----------------------------------------------- | | 1 | TextInput | text, short_text, … | | 2 | TextArea | long_text, deep_dive | | 3 | NumberInput | number | | 4 | DateInput | date | | 5 | PhoneInput | phone_number | | 6 | UrlInput | website | | 7 | Dropdown (+ Dropdown.Option) | dropdown | | 8 | MultipleChoice (+ MultipleChoice.Choice) | multiple_choice, picture_choice, checkbox | | 9 | Ranking (+ Ranking.Item) | ranking | | 10 | YesNo | yes_no (UI strings; map to boolean for core) | | 11 | Rating | rating | | 12 | Scale | opinion_scale, nps | | 13 | Legal | legal | | 14 | FileUpload | file_upload, multi_format | | 15 | VideoQuestion | file_upload (media) | | 16 | AudioQuestion | file_upload (media) | | 17 | AddressInput | address | | 18 | ContactInfoInput | contact_info |

Step & layout primitives

• Steps: WelcomeScreen, Statement, Question, EndScreen, and advanced StepPanel for custom question layouts.
• Copy: Title, Description.
• Chrome: Form, Progress, Controls, FooterNavigation, StartButton.

License

See the repository root for license terms.