@viveksinghind/narrative-form-react 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,897 @@
+import React from 'react';
+import { NarrativeField, NarrativeFormConfig, NarrativeTheme, NarrativeTypewriter, NarrativeWelcome, NarrativeDone, NarrativeCallbacks, NarrativeRefHandle, NarrativeFieldValues, NarrativeI18n, NarrativeCrossFieldValidator, NarrativeMeta, FormStateSnapshot, FieldStatus, NarrativeErrorDisplay } from '@viveksinghind/narrative-form-core';
+export { AsyncValidationHandle, FieldStatus, FormStateEngine, FormStateSnapshot, NarrativeCallbacks, NarrativeCrossFieldValidator, NarrativeDone, NarrativeErrorDisplay, NarrativeField, NarrativeFieldType, NarrativeFieldValues, NarrativeFormConfig, NarrativeI18n, NarrativeMeta, NarrativeRefHandle, NarrativeServerValidation, NarrativeTheme, NarrativeTypewriter, NarrativeValidation, NarrativeValidationRule, NarrativeWelcome, ValidationResult, ValidatorFn, clearValidators, defaultStrings, getRegisteredValidatorNames, getValidator, hasAsyncValidation, hasValidator, mergeStrings, registerBuiltinValidators, registerValidator, unregisterValidator, validateField, validateFieldAsync } from '@viveksinghind/narrative-form-core';
+
+/**
+ * NarrativeForm — root component for narrative-form.
+ *
+ * @remarks
+ * Main entry point for consumers. Renders fields one by one with typewriter
+ * animations and manages the full lifecycle: welcome → fields → done.
+ *
+ * Supports: theming, dark mode, welcome/done screens, async validation,
+ * dynamic forms (fieldsUrl/formConfig), controlled mode, default values,
+ * field dependencies (showIf), step locking (lockPrevious), i18n/RTL,
+ * and cross-field validation.
+ *
+ * CSS classes: `ns-root`, `ns-letter`, `ns-root--complete`,
+ * `ns-root--dark`, `ns-root--submitting`, `ns-root--loading`, `ns-root--error`
+ */
+
+/** Props for the NarrativeForm component. */
+interface NarrativeFormProps {
+    /** Ordered list of field configurations (static mode). */
+    fields?: NarrativeField[];
+    /** URL to fetch form config from (dynamic mode). */
+    fieldsUrl?: string;
+    /** Headers for the fieldsUrl fetch request. */
+    fieldsUrlHeaders?: Record<string, string>;
+    /** Pre-fetched form config object (dynamic mode). */
+    formConfig?: NarrativeFormConfig;
+    /** Theme configuration — colours, typography, spacing. */
+    theme?: NarrativeTheme;
+    /** Typewriter animation settings. */
+    typewriter?: NarrativeTypewriter;
+    /** Welcome screen configuration. Pass `{ show: false }` to skip. */
+    welcome?: NarrativeWelcome;
+    /** Done screen configuration. Pass `{ show: false }` to skip. */
+    done?: NarrativeDone;
+    /** Whether confirmed fields show an edit icon. Default: true */
+    editable?: boolean;
+    /** Label for the edit button. Default: "Edit" */
+    editLabel?: string;
+    /** Additional CSS class added to the root element. */
+    className?: string;
+    /** Event callbacks for analytics and integration. */
+    callbacks?: NarrativeCallbacks;
+    /** Ref handle for imperative API (next, getValues, reset, focusField). */
+    formRef?: React.Ref<NarrativeRefHandle>;
+    /** Default values — pre-fill fields as already confirmed. */
+    defaultValues?: NarrativeFieldValues;
+    /** Controlled mode — external values source of truth. */
+    values?: NarrativeFieldValues;
+    /** i18n string overrides. */
+    strings?: Partial<NarrativeI18n>;
+    /** BCP 47 locale code. */
+    locale?: string;
+    /** Text direction. Auto-detected from locale if not set. */
+    direction?: "ltr" | "rtl";
+    /** Cross-field validation rules. */
+    crossFieldValidators?: NarrativeCrossFieldValidator[];
+    /** Custom loading component while fetching dynamic config. */
+    loadingComponent?: React.ReactNode;
+    /** Custom error component when config fetch fails. */
+    errorComponent?: React.ReactNode;
+    /** Callback when config fetch fails. */
+    onFetchError?: (error: Error) => void;
+    /** Label for the retry button on fetch error. */
+    retryLabel?: string;
+    /** Whether reduced motion should be forced. */
+    reducedMotion?: boolean;
+}
+/**
+ * The root narrative-form component.
+ *
+ * Renders fields one by one with typewriter animations. Each field follows
+ * the lifecycle: idle → typing → active → confirmed → editing.
+ *
+ * @param props - Form configuration
+ */
+declare const NarrativeForm: React.FC<NarrativeFormProps>;
+
+/**
+ * ThemeProvider — applies NarrativeTheme tokens as CSS custom properties.
+ *
+ * @remarks
+ * Converts theme token names (e.g., `background`, `textColor`) into CSS
+ * variable names (e.g., `--ns-bg`, `--ns-text`) and applies them as inline
+ * style on a wrapper element. This avoids any CSS-in-JS dependency.
+ *
+ * Supports dark mode via `theme.mode` (`'light'`, `'dark'`, `'auto'`).
+ * When `'auto'`, it uses `matchMedia('(prefers-color-scheme: dark)')`.
+ *
+ * CSS classes: none (uses ns-root--dark on root via className)
+ */
+
+/** Resolved theme context value. */
+interface ThemeContextValue {
+    /** The resolved theme tokens (merged with dark overrides if applicable). */
+    theme: NarrativeTheme;
+    /** Whether dark mode is currently active. */
+    isDark: boolean;
+}
+/**
+ * Hook to access the current theme context.
+ *
+ * @returns The resolved theme and dark mode state
+ */
+declare function useTheme(): ThemeContextValue;
+/** Props for the ThemeProvider component. */
+interface ThemeProviderProps {
+    /** The theme configuration. */
+    theme?: NarrativeTheme;
+    /** Children to render. */
+    children: React.ReactNode;
+}
+/**
+ * Provides theme context and applies CSS custom properties.
+ *
+ * @param props - Theme provider configuration
+ */
+declare const ThemeProvider: React.FC<ThemeProviderProps>;
+
+/**
+ * WelcomeScreen — the opening screen of the narrative form.
+ *
+ * @remarks
+ * Displays a heading (with optional typewriter animation), supporting
+ * subtext, and a call-to-action button. Shown before any form fields.
+ *
+ * CSS classes: `ns-welcome`, `ns-welcome-heading`, `ns-welcome-subtext`,
+ * `ns-welcome-cta`
+ */
+
+/** Props for the WelcomeScreen component. */
+interface WelcomeScreenProps {
+    /** Welcome screen configuration. */
+    welcome: NarrativeWelcome;
+    /** Typewriter settings for the heading animation. */
+    typewriter?: NarrativeTypewriter;
+    /** Called when the CTA button is clicked to start the form. */
+    onStart: () => void;
+    /** Additional CSS class for the wrapper. */
+    className?: string;
+}
+/**
+ * Renders the welcome screen with an animated heading and CTA.
+ *
+ * @param props - Welcome screen configuration
+ */
+declare const WelcomeScreen: React.FC<WelcomeScreenProps>;
+
+/**
+ * DoneScreen — the completion screen shown after all fields are confirmed.
+ *
+ * @remarks
+ * Displays a personalised message (with template variable interpolation)
+ * and a submit CTA button. Supports `{key}` placeholders in the message
+ * string that are replaced with confirmed field values.
+ *
+ * Also supports a function-mode message: `(values) => string`.
+ *
+ * CSS classes: `ns-done`, `ns-done-message`, `ns-done-cta`,
+ * `ns-done-cta--loading`, `ns-done-cta--success`, `ns-done-cta--error`,
+ * `ns-done-error`
+ */
+
+/** Props for the DoneScreen component. */
+interface DoneScreenProps {
+    /** Done screen configuration. */
+    done: NarrativeDone;
+    /** All confirmed field values. */
+    values: NarrativeFieldValues;
+    /** Analytics metadata. */
+    meta: NarrativeMeta;
+    /** Typewriter settings for the message animation. */
+    typewriter?: NarrativeTypewriter;
+    /** Additional CSS class for the wrapper. */
+    className?: string;
+}
+/**
+ * Renders the done screen with a personalised message and submit button.
+ *
+ * @param props - Done screen configuration
+ */
+declare const DoneScreen: React.FC<DoneScreenProps>;
+
+/**
+ * Core typewriter animation hook for narrative-form.
+ *
+ * @remarks
+ * Animates a string character by character to create the "letter being written"
+ * effect. Cleans up the interval on unmount to prevent memory leaks.
+ * Respects `prefers-reduced-motion` — skips animation entirely if set.
+ *
+ * @example
+ * ```tsx
+ * const { displayedText, isTyping, isComplete } = useTypewriter({
+ *   text: "My name is",
+ *   speed: 38,
+ * });
+ * ```
+ */
+/** Configuration options for the useTypewriter hook. */
+interface UseTypewriterOptions {
+    /** The full text to type out. */
+    text: string;
+    /** Milliseconds per character. Default: 38 */
+    speed?: number;
+    /** Whether animation is enabled. Default: true */
+    enabled?: boolean;
+    /** Milliseconds to pause after typing completes before signalling done. Default: 100 */
+    pauseAfter?: number;
+    /** Callback fired when typing is fully complete (after pause). */
+    onComplete?: () => void;
+}
+/** Return value of the useTypewriter hook. */
+interface UseTypewriterResult {
+    /** The currently visible portion of the text. */
+    displayedText: string;
+    /** Whether the typewriter is actively typing characters. */
+    isTyping: boolean;
+    /** Whether typing is fully complete (including the post-typing pause). */
+    isComplete: boolean;
+}
+/**
+ * React hook that animates text character by character.
+ *
+ * @param options - Typewriter configuration
+ * @returns Object with displayedText, isTyping, and isComplete
+ */
+declare function useTypewriter(options: UseTypewriterOptions): UseTypewriterResult;
+
+/**
+ * React hook wrapping the core FormStateEngine.
+ *
+ * @remarks
+ * Bridges the framework-agnostic FormStateEngine with React's
+ * state management. Each state mutation in the engine triggers
+ * a React re-render via `useSyncExternalStore`-like pattern.
+ */
+
+/** Return value of the useFormState hook. */
+interface UseFormStateResult {
+    /** Current snapshot of the form state. */
+    snapshot: FormStateSnapshot;
+    /** Start the typewriter animation for a field. */
+    startTyping: (key: string) => void;
+    /** Mark a field as active (typewriter done, input visible). */
+    activateField: (key: string) => void;
+    /** Confirm a field with a value. */
+    confirmField: (key: string, value: string | string[]) => void;
+    /** Reopen a confirmed field for editing. */
+    editField: (key: string) => void;
+    /** Re-confirm a field after editing. */
+    reconfirmField: (key: string, value: string | string[]) => void;
+    /** Move to the next field. */
+    next: () => void;
+    /** Focus a specific field by key. */
+    focusField: (key: string) => void;
+    /** Reset all form state. */
+    reset: () => void;
+    /** Get all confirmed values. */
+    getValues: () => NarrativeFieldValues;
+    /** Get analytics metadata. */
+    getMeta: (formId?: string, formVersion?: number) => NarrativeMeta;
+}
+/**
+ * React hook that manages the narrative form state.
+ *
+ * @param fields - Ordered array of field configurations
+ * @returns Form state and mutation methods
+ */
+declare function useFormState(fields: readonly NarrativeField[]): UseFormStateResult;
+
+/**
+ * Line — single sentence row orchestrator for narrative-form.
+ *
+ * @remarks
+ * Manages the full lifecycle of a single field within the form:
+ * `typing → active → confirmed → editing`.
+ *
+ * Composes: Prose + InlineInput (or FilledValue + EditIcon) + ErrorMessage.
+ * Runs validation on confirm — blocks confirmation if validation fails.
+ * Supports async validation with loading/success visual states.
+ * CSS classes: `ns-line`, `ns-line--active`, `ns-line--confirmed`,
+ * `ns-line--editing`, `ns-line--error`, `ns-line-[key]`
+ */
+
+/** Props for the Line component. */
+interface LineProps {
+    /** The field configuration for this line. */
+    field: NarrativeField;
+    /** Current lifecycle status of this field. */
+    status: FieldStatus;
+    /** The confirmed value (if any). */
+    value?: string | string[];
+    /** All confirmed values so far (for cross-field validation). */
+    allValues?: NarrativeFieldValues;
+    /** Typewriter configuration. */
+    typewriter?: NarrativeTypewriter;
+    /** Whether editing is enabled globally. Default: true */
+    editable?: boolean;
+    /** Whether this field is locked (lockPrevious). */
+    locked?: boolean;
+    /** Label for the edit button. */
+    editLabel?: string;
+    /** Called when typing animation completes — field should become active. */
+    onTypingComplete: (key: string) => void;
+    /** Called when the field value is confirmed (after validation passes). */
+    onConfirm: (key: string, value: string) => void;
+    /** Called when the edit icon is clicked. */
+    onEdit: (key: string) => void;
+    /** Called when validation fails. */
+    onError?: (key: string, message: string) => void;
+    /** Called on every keystroke. */
+    onChange?: (key: string, value: string) => void;
+    /** Called when input receives focus. */
+    onFocus?: (key: string) => void;
+    /** Called when input loses focus. */
+    onBlur?: (key: string, value: string) => void;
+}
+/**
+ * Renders a single sentence row — the core building block of the narrative form.
+ *
+ * Lifecycle:
+ * 1. `typing` — Prose types out the prefix text
+ * 2. `active` — Input appears for the user to fill
+ * 3. `confirmed` — Value is locked, shown as filled text with edit icon
+ * 4. `editing` — User clicked edit, input re-appears with current value
+ *
+ * Validation runs on confirm. If it fails, the field stays active and
+ * an error message is displayed below the input.
+ *
+ * @param props - Line configuration
+ */
+declare const Line: React.FC<LineProps>;
+
+/**
+ * Typewriter prose text component.
+ *
+ * @remarks
+ * Wraps the `useTypewriter` hook to render the sentence prefix
+ * (e.g., "My name is") character by character, followed by a blinking cursor.
+ * CSS classes: `ns-prose`, `ns-prose--typing`
+ */
+
+/** Props for the Prose component. */
+interface ProseProps {
+    /** The full sentence text to type out. */
+    text: string;
+    /** Whether typewriter animation is enabled. Default: true */
+    animate?: boolean;
+    /** Milliseconds per character. Default: 38 */
+    speed?: number;
+    /** Whether to show a blinking cursor while typing. Default: true */
+    cursor?: boolean;
+    /** Custom cursor character. Default: "|" */
+    cursorChar?: string;
+    /** Milliseconds to pause after typing before input appears. Default: 100 */
+    pauseAfter?: number;
+    /** Callback fired when typing is fully complete. */
+    onComplete?: () => void;
+    /** Additional CSS class name. */
+    className?: string;
+}
+/**
+ * Renders a sentence prefix with a typewriter animation.
+ *
+ * @param props - Prose configuration
+ */
+declare const Prose: React.FC<ProseProps>;
+
+/**
+ * Blinking cursor component for the typewriter effect.
+ *
+ * @remarks
+ * Renders a single character that blinks via CSS animation.
+ * Visible only while the typewriter is actively typing.
+ * CSS class: `ns-cursor`
+ */
+
+/** Props for the Cursor component. */
+interface CursorProps {
+    /** The character to display as the cursor. Default: "|" */
+    cursorChar?: string;
+    /** Additional CSS class name. */
+    className?: string;
+}
+/**
+ * A blinking cursor character displayed during typewriter animation.
+ *
+ * @param props - Cursor configuration
+ */
+declare const Cursor: React.FC<CursorProps>;
+
+/**
+ * Base inline input component for narrative-form.
+ *
+ * @remarks
+ * Renders an inline text input that appears after the typewriter finishes.
+ * Handles Enter key to confirm, Escape to cancel, and auto-focuses when it mounts.
+ * Supports sanitise function on input and paste events.
+ * CSS classes: `ns-input-wrap`, `ns-input`, `ns-input--[type]`, `ns-input--focused`
+ */
+
+/** Props for the InlineInput component. */
+interface InlineInputProps {
+    /** Unique field key used for identification. */
+    fieldKey: string;
+    /** HTML input type attribute. Default: "text" */
+    type?: string;
+    /** Placeholder text inside the input. */
+    placeholder?: string;
+    /** Initial value for the input. */
+    defaultValue?: string;
+    /** Suffix text displayed after the input. */
+    suffix?: string;
+    /** Sanitise function applied on input and paste. */
+    sanitise?: (value: string) => string;
+    /** Callback fired when the value is confirmed (Enter key or button). */
+    onConfirm: (value: string) => void;
+    /** Callback fired on every keystroke. */
+    onChange?: (value: string) => void;
+    /** Callback fired when input receives focus. */
+    onFocus?: () => void;
+    /** Callback fired when input loses focus. */
+    onBlur?: (value: string) => void;
+    /** Callback fired when Escape is pressed (cancel edit). */
+    onEscape?: () => void;
+    /** Additional CSS class for the input element. */
+    inputClassName?: string;
+    /** Additional CSS class for the wrapper. */
+    className?: string;
+}
+/**
+ * An inline input that lives within a sentence.
+ * Auto-focuses on mount and confirms on Enter key press.
+ *
+ * @param props - Input configuration
+ */
+declare const InlineInput: React.FC<InlineInputProps>;
+
+/**
+ * EnterButton — the ↵ confirm button displayed next to inline inputs.
+ *
+ * @remarks
+ * Triggers field confirmation when clicked.
+ * CSS class: `ns-enter-btn`
+ */
+
+/** Props for the EnterButton component. */
+interface EnterButtonProps {
+    /** Callback fired when the button is clicked. */
+    onConfirm: () => void;
+    /** Button label. Default: "↵" */
+    label?: string;
+    /** Additional CSS class name. */
+    className?: string;
+}
+/**
+ * A small inline button that confirms the current field value.
+ *
+ * @param props - Button configuration
+ */
+declare const EnterButton: React.FC<EnterButtonProps>;
+
+/**
+ * Confirmed/filled value display component.
+ *
+ * @remarks
+ * Renders the confirmed field value as styled italic text alongside
+ * an edit icon. Shown after a field is confirmed.
+ * CSS classes: `ns-filled-wrap`, `ns-filled-value`
+ */
+
+/** Props for the FilledValue component. */
+interface FilledValueProps {
+    /** The confirmed value to display. */
+    value: string;
+    /** Suffix text displayed after the value. */
+    suffix?: string;
+    /** Whether the edit icon should be shown. Default: true */
+    editable?: boolean;
+    /** Callback fired when the edit icon is clicked. */
+    onEdit?: () => void;
+    /** Label for the edit button. Default: "Edit" */
+    editLabel?: string;
+    /** Additional CSS class name. */
+    className?: string;
+}
+/**
+ * Displays a confirmed field value with an optional edit icon.
+ *
+ * @param props - FilledValue configuration
+ */
+declare const FilledValue: React.FC<FilledValueProps>;
+
+/**
+ * Pencil edit icon button for confirmed fields.
+ *
+ * @remarks
+ * Appears inline next to the filled value after a field is confirmed.
+ * Clicking it reopens the field for editing.
+ * CSS class: `ns-edit-btn`
+ */
+
+/** Props for the EditIcon component. */
+interface EditIconProps {
+    /** Callback fired when the edit icon is clicked. */
+    onEdit: () => void;
+    /** Accessible label for the button. Default: "Edit" */
+    label?: string;
+    /** Additional CSS class name. */
+    className?: string;
+}
+/**
+ * A small pencil icon button that triggers field editing.
+ *
+ * @param props - Edit icon configuration
+ */
+declare const EditIcon: React.FC<EditIconProps>;
+
+/**
+ * ErrorMessage — validation error display for narrative-form.
+ *
+ * @remarks
+ * Displays validation errors based on the configured mode (inline, tooltip).
+ * Supports animations (fadeUp, slideDown, shake) and optional icons.
+ *
+ * CSS classes:
+ * - `ns-error-wrap` (base)
+ * - `ns-error-wrap--tooltip` / `ns-error-wrap--inline`
+ * - `ns-error-wrap--above` / `ns-error-wrap--below`
+ * - `ns-error-text`
+ * - `ns-error-text--shake`
+ * - `ns-animate-fade-up` / `ns-animate-slide-down`
+ */
+
+/** Props for the ErrorMessage component. */
+interface ErrorMessageProps {
+    /** The error message to display. */
+    message: string;
+    /** Display configuration for the error. */
+    display?: NarrativeErrorDisplay;
+    /** Additional CSS class name. */
+    className?: string;
+}
+/**
+ * Renders a validation error message.
+ *
+ * @param props - Error message configuration
+ */
+declare const ErrorMessage: React.FC<ErrorMessageProps>;
+
+/**
+ * TextField — the default text input field type for narrative-form.
+ *
+ * @remarks
+ * Wraps InlineInput with text-specific defaults.
+ * This is the simplest field type — all other types build on this pattern.
+ * CSS class: `ns-input--text`
+ */
+
+/** Props for the TextField component. */
+interface TextFieldProps {
+    /** Unique field key. */
+    fieldKey: string;
+    /** Placeholder text. */
+    placeholder?: string;
+    /** Initial value (for edit mode). */
+    defaultValue?: string;
+    /** Suffix text after the input. */
+    suffix?: string;
+    /** Callback when the value is confirmed. */
+    onConfirm: (value: string) => void;
+    /** Callback on every keystroke. */
+    onChange?: (value: string) => void;
+    /** Callback when input receives focus. */
+    onFocus?: () => void;
+    /** Callback when input loses focus. */
+    onBlur?: (value: string) => void;
+    /** Additional CSS class for the input element. */
+    inputClassName?: string;
+    /** Additional CSS class for the wrapper. */
+    className?: string;
+}
+/**
+ * A text input field rendered inline within a sentence.
+ *
+ * @param props - TextField configuration
+ */
+declare const TextField: React.FC<TextFieldProps>;
+
+/**
+ * TelField — phone number input field for narrative-form.
+ *
+ * @remarks
+ * Renders an inline input with `type="tel"` for numeric keyboard on mobile.
+ * CSS class: `ns-input--tel`
+ */
+
+/** Props for the TelField component. */
+interface TelFieldProps {
+    /** Unique field key. */
+    fieldKey: string;
+    /** Placeholder text. */
+    placeholder?: string;
+    /** Initial value (for edit mode). */
+    defaultValue?: string;
+    /** Suffix text after the input. */
+    suffix?: string;
+    /** Callback when the value is confirmed. */
+    onConfirm: (value: string) => void;
+    /** Callback on every keystroke. */
+    onChange?: (value: string) => void;
+    /** Callback when input receives focus. */
+    onFocus?: () => void;
+    /** Callback when input loses focus. */
+    onBlur?: (value: string) => void;
+    /** Additional CSS class for the input element. */
+    inputClassName?: string;
+    /** Additional CSS class for the wrapper. */
+    className?: string;
+}
+/**
+ * A phone number input field rendered inline within a sentence.
+ *
+ * @param props - TelField configuration
+ */
+declare const TelField: React.FC<TelFieldProps>;
+
+/**
+ * EmailField — email input field for narrative-form.
+ *
+ * @remarks
+ * Renders an inline input with `type="email"` for email keyboard on mobile.
+ * CSS class: `ns-input--email`
+ */
+
+/** Props for the EmailField component. */
+interface EmailFieldProps {
+    /** Unique field key. */
+    fieldKey: string;
+    /** Placeholder text. */
+    placeholder?: string;
+    /** Initial value (for edit mode). */
+    defaultValue?: string;
+    /** Suffix text after the input. */
+    suffix?: string;
+    /** Callback when the value is confirmed. */
+    onConfirm: (value: string) => void;
+    /** Callback on every keystroke. */
+    onChange?: (value: string) => void;
+    /** Callback when input receives focus. */
+    onFocus?: () => void;
+    /** Callback when input loses focus. */
+    onBlur?: (value: string) => void;
+    /** Additional CSS class for the input element. */
+    inputClassName?: string;
+    /** Additional CSS class for the wrapper. */
+    className?: string;
+}
+/**
+ * An email input field rendered inline within a sentence.
+ *
+ * @param props - EmailField configuration
+ */
+declare const EmailField: React.FC<EmailFieldProps>;
+
+/**
+ * PasswordField — masked password input for narrative-form.
+ *
+ * @remarks
+ * Renders an inline input with `type="password"` and a show/hide toggle.
+ * CSS classes: `ns-input--password`, `ns-password-toggle`
+ */
+
+/** Props for the PasswordField component. */
+interface PasswordFieldProps {
+    /** Unique field key. */
+    fieldKey: string;
+    /** Placeholder text. */
+    placeholder?: string;
+    /** Initial value (for edit mode). */
+    defaultValue?: string;
+    /** Suffix text after the input. */
+    suffix?: string;
+    /** Callback when the value is confirmed. */
+    onConfirm: (value: string) => void;
+    /** Callback on every keystroke. */
+    onChange?: (value: string) => void;
+    /** Callback when input receives focus. */
+    onFocus?: () => void;
+    /** Callback when input loses focus. */
+    onBlur?: (value: string) => void;
+    /** Whether to show a show/hide toggle. Default: true */
+    showToggle?: boolean;
+    /** Additional CSS class for the input element. */
+    inputClassName?: string;
+    /** Additional CSS class for the wrapper. */
+    className?: string;
+}
+/**
+ * A masked password input field with optional show/hide toggle.
+ *
+ * @param props - PasswordField configuration
+ */
+declare const PasswordField: React.FC<PasswordFieldProps>;
+
+/**
+ * NumberField — numeric input field for narrative-form.
+ *
+ * @remarks
+ * Renders an inline input with `type="number"` for numeric entry.
+ * CSS class: `ns-input--number`
+ */
+
+/** Props for the NumberField component. */
+interface NumberFieldProps {
+    /** Unique field key. */
+    fieldKey: string;
+    /** Placeholder text. */
+    placeholder?: string;
+    /** Initial value (for edit mode). */
+    defaultValue?: string;
+    /** Suffix text after the input. */
+    suffix?: string;
+    /** Callback when the value is confirmed. */
+    onConfirm: (value: string) => void;
+    /** Callback on every keystroke. */
+    onChange?: (value: string) => void;
+    /** Callback when input receives focus. */
+    onFocus?: () => void;
+    /** Callback when input loses focus. */
+    onBlur?: (value: string) => void;
+    /** Additional CSS class for the input element. */
+    inputClassName?: string;
+    /** Additional CSS class for the wrapper. */
+    className?: string;
+}
+/**
+ * A numeric input field rendered inline within a sentence.
+ *
+ * @param props - NumberField configuration
+ */
+declare const NumberField: React.FC<NumberFieldProps>;
+
+/**
+ * ChipsField — tap to select one option for narrative-form.
+ *
+ * @remarks
+ * Renders a row of pill-shaped chips. User taps one to select it.
+ * Supports optional auto-advance, keyboard navigation (Arrow keys + Space),
+ * and RTL layout.
+ * CSS classes: `ns-chips-wrap`, `ns-chip`, `ns-chip--active`, `ns-chip--hover`
+ */
+
+/** Props for the ChipsField component. */
+interface ChipsFieldProps {
+    /** Unique field key. */
+    fieldKey: string;
+    /** Array of option labels. */
+    options: string[];
+    /** Currently selected value (for edit mode). */
+    defaultValue?: string;
+    /** Whether to auto-confirm on selection. Default: false */
+    autoAdvance?: boolean;
+    /** Callback when a value is confirmed. */
+    onConfirm: (value: string) => void;
+    /** Callback on selection change. */
+    onChange?: (value: string) => void;
+    /** Additional CSS class for the wrapper. */
+    className?: string;
+}
+/**
+ * A single-select chip field rendered inline within a sentence.
+ * Supports Arrow Left/Right keyboard navigation and Space to select.
+ *
+ * @param props - ChipsField configuration
+ */
+declare const ChipsField: React.FC<ChipsFieldProps>;
+
+/**
+ * MultiChipsField — tap to select multiple options for narrative-form.
+ *
+ * @remarks
+ * Renders a row of pill-shaped chips. User can tap multiple to select them.
+ * Confirmed value is an array of selected option strings.
+ * CSS classes: `ns-chips-wrap`, `ns-chip`, `ns-chip--active`, `ns-chip--hover`
+ */
+
+/** Props for the MultiChipsField component. */
+interface MultiChipsFieldProps {
+    /** Unique field key. */
+    fieldKey: string;
+    /** Array of option labels. */
+    options: string[];
+    /** Currently selected values (for edit mode). */
+    defaultValue?: string[];
+    /** Callback when values are confirmed. Receives comma-separated string. */
+    onConfirm: (value: string) => void;
+    /** Callback on selection change. */
+    onChange?: (value: string) => void;
+    /** Additional CSS class for the wrapper. */
+    className?: string;
+}
+/**
+ * A multi-select chip field rendered inline within a sentence.
+ *
+ * @param props - MultiChipsField configuration
+ */
+declare const MultiChipsField: React.FC<MultiChipsFieldProps>;
+
+/**
+ * SelectField — inline dropdown for narrative-form.
+ *
+ * @remarks
+ * Renders a native `<select>` element inline within a sentence.
+ * CSS classes: `ns-select-wrap`, `ns-select`
+ */
+
+/** Props for the SelectField component. */
+interface SelectFieldProps {
+    /** Unique field key. */
+    fieldKey: string;
+    /** Array of option labels. */
+    options: string[];
+    /** Placeholder text for the default empty option. */
+    placeholder?: string;
+    /** Currently selected value (for edit mode). */
+    defaultValue?: string;
+    /** Whether to auto-confirm on selection. Default: false */
+    autoAdvance?: boolean;
+    /** Callback when a value is confirmed. */
+    onConfirm: (value: string) => void;
+    /** Callback on selection change. */
+    onChange?: (value: string) => void;
+    /** Callback when input receives focus. */
+    onFocus?: () => void;
+    /** Callback when input loses focus. */
+    onBlur?: (value: string) => void;
+    /** Additional CSS class for the select element. */
+    inputClassName?: string;
+    /** Additional CSS class for the wrapper. */
+    className?: string;
+}
+/**
+ * An inline dropdown select field rendered within a sentence.
+ *
+ * @param props - SelectField configuration
+ */
+declare const SelectField: React.FC<SelectFieldProps>;
+
+/**
+ * OtpField — N-digit OTP input for narrative-form.
+ *
+ * @remarks
+ * Each digit is a separate focusable input. Auto-focuses the next box
+ * on digit entry, auto-focuses previous on backspace. Paste distributes
+ * across all boxes. Never logs or exposes the OTP value in console.
+ *
+ * CSS classes: `ns-otp-wrap`, `ns-otp-box`, `ns-otp-box--filled`,
+ * `ns-otp-box--active`, `ns-otp-box--error`, `ns-otp-resend`,
+ * `ns-otp-resend--disabled`, `ns-otp-timer`
+ */
+
+/** Props for the OtpField component. */
+interface OtpFieldProps {
+    /** Unique field key. */
+    fieldKey: string;
+    /** Number of OTP digit boxes. Default: 6 */
+    otpLength?: number;
+    /** Whether to auto-submit when all digits are filled. Default: true */
+    autoAdvance?: boolean;
+    /** Called when the OTP field first appears — triggers OTP send. */
+    onRequest?: () => void | Promise<void>;
+    /** Called when all digits are filled. */
+    onVerify?: (otp: string) => void | Promise<void>;
+    /** Callback when the full OTP is confirmed. */
+    onConfirm: (value: string) => void;
+    /** Callback on value change. */
+    onChange?: (value: string) => void;
+    /** Label for the resend link. Default: "Resend code" */
+    resendLabel?: string;
+    /** Seconds before resend is allowed. Default: 30 */
+    resendDelay?: number;
+    /** Additional CSS class for the wrapper. */
+    className?: string;
+}
+/**
+ * An N-digit OTP input with auto-focus, paste distribution, and resend timer.
+ *
+ * @param props - OtpField configuration
+ */
+declare const OtpField: React.FC<OtpFieldProps>;
+
+export { ChipsField, type ChipsFieldProps, Cursor, type CursorProps, DoneScreen, type DoneScreenProps, EditIcon, type EditIconProps, EmailField, type EmailFieldProps, EnterButton, type EnterButtonProps, ErrorMessage, type ErrorMessageProps, FilledValue, type FilledValueProps, InlineInput, type InlineInputProps, Line, type LineProps, MultiChipsField, type MultiChipsFieldProps, NarrativeForm, type NarrativeFormProps, NumberField, type NumberFieldProps, OtpField, type OtpFieldProps, PasswordField, type PasswordFieldProps, Prose, type ProseProps, SelectField, type SelectFieldProps, TelField, type TelFieldProps, TextField, type TextFieldProps, type ThemeContextValue, ThemeProvider, type ThemeProviderProps, type UseFormStateResult, type UseTypewriterOptions, type UseTypewriterResult, WelcomeScreen, type WelcomeScreenProps, useFormState, useTheme, useTypewriter };