@valfuse-node/react 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,446 @@
+import React$1, { ChangeEvent, PropsWithChildren } from 'react';
+import { ValfuseSchema, ValfuseFieldErrors } from '@valfuse-node/form';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as _valfuse_node_localization from '@valfuse-node/localization';
+import { RuntimeManifest } from '@valfuse-node/localization';
+
+/**
+ * Controls when validation is triggered — mirrors react-hook-form's `mode` option:
+ *
+ * | Mode         | Behaviour                                                               |
+ * |--------------|-------------------------------------------------------------------------|
+ * | `onSubmit`   | Validate only when the form is submitted (default)                      |
+ * | `onBlur`     | Validate when a field loses focus                                       |
+ * | `onChange`   | Validate on every keystroke / value change                              |
+ * | `onTouched`  | Validate on the first blur; after that validate on every change         |
+ * | `all`        | Validate on both `onChange` and `onBlur`                                |
+ */
+type ValfuseFormMode = "onSubmit" | "onBlur" | "onChange" | "onTouched" | "all";
+/** A single field error — extends the core error with a required `type` field */
+type ValfuseFieldError = {
+    message: string;
+    /** Error originator: "validation" | "server" | "manual" | "custom" */
+    type: string;
+    /** Optional semantic code (e.g. "email.required", "auth.not_found") */
+    code?: string;
+    metadata?: Record<string, unknown>;
+};
+type ValfuseFormErrors<TFieldValues extends Record<string, unknown>> = {
+    [K in keyof TFieldValues]?: ValfuseFieldError;
+};
+type ValfuseDirtyFields<TFieldValues extends Record<string, unknown>> = {
+    [K in keyof TFieldValues]?: boolean;
+};
+type ValfuseTouchedFields<TFieldValues extends Record<string, unknown>> = {
+    [K in keyof TFieldValues]?: boolean;
+};
+type ValfuseFormState<TFieldValues extends Record<string, unknown>> = {
+    /** All current field validation errors */
+    readonly errors: ValfuseFormErrors<TFieldValues>;
+    /** `true` while an async submit handler is running — never `undefined` */
+    readonly isSubmitting: boolean;
+    /** `true` after the form has been submitted at least once — never `undefined` */
+    readonly isSubmitted: boolean;
+    /**
+     * `true` if the most recent submission completed without validation errors
+     * and the `onValid` handler finished successfully — never `undefined`.
+     */
+    readonly isSubmitSuccessful: boolean;
+    /** Total number of submit attempts (resets on `reset()`) — never `undefined` */
+    readonly submitCount: number;
+    /** `true` if any field value differs from its default value — never `undefined` */
+    readonly isDirty: boolean;
+    /**
+     * `true` if current values pass schema validation and there are no active errors.
+     * Computed directly from the schema — accurate from the very first render.
+     */
+    readonly isValid: boolean;
+    /** Map of fields whose current value differs from the default (`{ email: true }`) */
+    readonly dirtyFields: ValfuseDirtyFields<TFieldValues>;
+    /** Map of fields the user has interacted with (focused + blurred) */
+    readonly touchedFields: ValfuseTouchedFields<TFieldValues>;
+    /** The `defaultValues` that were passed to `useValfuseForm` */
+    readonly defaultValues: Readonly<TFieldValues>;
+};
+/**
+ * Callback passed to `form.watch(callback)`.
+ * Called every time any field value changes.
+ */
+type ValfuseWatchCallback<TFieldValues extends Record<string, unknown>> = (values: TFieldValues, info: {
+    name?: string;
+    type?: string;
+}) => void;
+/**
+ * Callable type for `form.watch` — mirrors react-hook-form overloads:
+ *
+ * ```ts
+ * form.watch()                          // → TFieldValues (all values)
+ * form.watch("email")                   // → TFieldValues["email"]
+ * form.watch(["email", "name"])         // → Array of values in the same order
+ * form.watch((values, info) => void)    // → () => void  (unsubscribe)
+ * ```
+ */
+interface ValfuseWatchFunction<TFieldValues extends Record<string, unknown>> {
+    (): TFieldValues;
+    <TName extends keyof TFieldValues & string>(name: TName): TFieldValues[TName];
+    (names: Array<keyof TFieldValues & string>): Array<TFieldValues[keyof TFieldValues]>;
+    (callback: ValfuseWatchCallback<TFieldValues>): () => void;
+}
+/** Props returned by `form.register(name)` — spread directly onto `<input>` */
+type ValfuseRegisterReturn = {
+    name: string;
+    /** Current field value — compatible with HTML input `value` prop */
+    value: string | number | readonly string[] | undefined;
+    onChange: (e: ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+    onBlur: () => void;
+};
+/**
+ * Opaque control object — passed to `<ValfuseController control={...} />`.
+ * Internal fields are prefixed with `_` and not part of the public API.
+ */
+type ValfuseFormControl<TFieldValues extends Record<string, unknown>> = {
+    /** @internal Current field values */
+    _values: TFieldValues;
+    /** @internal Current validation errors */
+    _errors: ValfuseFormErrors<TFieldValues>;
+    /** @internal Update a single field value */
+    _updateField: <TName extends keyof TFieldValues & string>(name: TName, value: TFieldValues[TName]) => void;
+    /** @internal Mark a field as touched (triggers onBlur validation) */
+    _touchField: (name: string) => void;
+    /** @internal Set of names of fields the user has interacted with */
+    _touchedFields: ReadonlySet<string>;
+};
+type UseValfuseFormProps<TFieldValues extends Record<string, unknown>> = {
+    schema: ValfuseSchema;
+    defaultValues: TFieldValues;
+    /**
+     * When validation runs:
+     * - `"onSubmit"` (default) — only on form submission
+     * - `"onBlur"` — when a field loses focus
+     * - `"onChange"` — on every keystroke
+     * - `"onTouched"` — on first blur, then on every change after that
+     * - `"all"` — on both onChange and onBlur
+     */
+    mode?: ValfuseFormMode;
+};
+type UseValfuseFormReturn<TFieldValues extends Record<string, unknown>> = {
+    /** Registers an input field — spread the return value onto `<input>` */
+    register: <TName extends keyof TFieldValues & string>(name: TName) => ValfuseRegisterReturn;
+    /** Passed to `<ValfuseController control={...} />` */
+    control: ValfuseFormControl<TFieldValues>;
+    /** Wraps form submission: validates first, then calls `onValid` */
+    handleSubmit: (onValid: (values: TFieldValues) => void | Promise<void>) => (e?: React.FormEvent | {
+        preventDefault?: () => void;
+    }) => Promise<void>;
+    /**
+     * Reactive form state.
+     * Includes: errors, isSubmitting, isSubmitted, isSubmitSuccessful,
+     * submitCount, isDirty, isValid, dirtyFields, touchedFields, defaultValues.
+     */
+    formState: ValfuseFormState<TFieldValues>;
+    /** Inject external errors (e.g. from API responses) */
+    setErrors: (errors: ValfuseFieldErrors<Extract<keyof TFieldValues, string>>) => void;
+    /** Clear one, many, or all field errors */
+    clearErrors: (name?: keyof TFieldValues | Array<keyof TFieldValues>) => void;
+    /**
+     * Programmatically set a field value.
+     * Pass `{ shouldValidate: true }` to run validation immediately after setting.
+     */
+    setValue: <TName extends keyof TFieldValues>(name: TName, value: TFieldValues[TName], options?: {
+        shouldValidate?: boolean;
+    }) => void;
+    /**
+     * Manually trigger validation.
+     * - No argument → validate all fields
+     * - Single name → validate one field
+     * - Array of names → validate those fields
+     *
+     * Returns `true` if all triggered fields are valid, `false` otherwise.
+     */
+    trigger: (name?: keyof TFieldValues & string | Array<keyof TFieldValues & string>) => boolean;
+    /**
+     * Watch field values — mirrors react-hook-form's `watch`:
+     *
+     * ```ts
+     * form.watch()                           // all current values
+     * form.watch("email")                    // single field value
+     * form.watch(["email", "name"])          // array of values
+     * const unsub = form.watch((values, info) => { ... }); // subscribe
+     * unsub();                               // unsubscribe
+     * ```
+     */
+    watch: ValfuseWatchFunction<TFieldValues>;
+    /** Reset the form to default values (or provided partial values) */
+    reset: (values?: Partial<TFieldValues>) => void;
+};
+
+declare function useValfuseForm<TFieldValues extends Record<string, unknown>>(props: UseValfuseFormProps<TFieldValues>): UseValfuseFormReturn<TFieldValues>;
+
+type ValfuseControllerFieldState = {
+    error?: ValfuseFieldError;
+    isTouched: boolean;
+};
+type ValfuseControllerField<TValue> = {
+    name: string;
+    value: TValue;
+    /** Receives the raw value — not a DOM event */
+    onChange: (value: TValue) => void;
+    onBlur: () => void;
+};
+type ValfuseControllerRenderProps<TFieldValues extends Record<string, unknown>, TName extends keyof TFieldValues & string> = {
+    field: ValfuseControllerField<TFieldValues[TName]>;
+    fieldState: ValfuseControllerFieldState;
+};
+type ValfuseControllerProps<TFieldValues extends Record<string, unknown>, TName extends keyof TFieldValues & string = keyof TFieldValues & string> = {
+    control: ValfuseFormControl<TFieldValues>;
+    name: TName;
+    render: (props: ValfuseControllerRenderProps<TFieldValues, TName>) => React$1.ReactElement;
+};
+/**
+ * Controlled field wrapper for complex inputs (dropdowns, date-pickers, etc.)
+ * that cannot be registered with `form.register(name)`.
+ *
+ * `fieldState.error` is typed as `ValfuseFieldError | undefined`, so both
+ * `fieldState.error?.message` and `fieldState.error?.code` work out of the box.
+ *
+ * @example
+ * <ValfuseController
+ *   control={form.control}
+ *   name="roleId"
+ *   render={({ field, fieldState }) => (
+ *     <RoleDropdown
+ *       value={field.value}
+ *       onChange={field.onChange}
+ *       onBlur={field.onBlur}
+ *       error={fieldState.error?.code}
+ *     />
+ *   )}
+ * />
+ */
+declare function ValfuseController<TFieldValues extends Record<string, unknown>, TName extends keyof TFieldValues & string = keyof TFieldValues & string>({ control, name, render, }: ValfuseControllerProps<TFieldValues, TName>): React$1.ReactElement;
+
+/**
+ * Minimal runtime store contract used by React adapter hooks and provider.
+ */
+interface LocalizationStore {
+    /** Returns the currently active locale. */
+    getLocale(): string;
+    /** Updates the active locale. */
+    setLocale(locale: string): void;
+    /** Looks up a key with fallback and optional interpolation. */
+    t(key: string, params?: Record<string, string | number>): string;
+}
+/**
+ * Creates a lightweight mutable localization store for React runtime usage.
+ *
+ * @param manifest Generated runtime manifest from `@valfuse-node/localization`.
+ * @param initialLocale Optional starting locale; defaults to `manifest.base_locale`.
+ */
+declare function createLocalizationStore(manifest: RuntimeManifest, initialLocale?: string): LocalizationStore;
+
+/**
+ * Generic contract for persisting / reading the active locale.
+ *
+ * Implement this interface to connect any storage backend
+ * (localStorage, sessionStorage, cookies, IndexedDB, remote API, …).
+ */
+interface LocaleStorage {
+    /** Read the previously-saved locale. Returns `undefined` when nothing is stored. */
+    get(): string | undefined;
+    /** Persist the newly selected locale. */
+    set(locale: string): void;
+    /** Optional: remove the stored value (e.g. when locale is reset). */
+    remove?(): void;
+}
+interface LocalStorageStrategyOptions {
+    /** Storage key. Defaults to `"locale"`. */
+    key?: string;
+}
+interface SessionStorageStrategyOptions {
+    /** Storage key. Defaults to `"locale"`. */
+    key?: string;
+}
+interface CookieStrategyOptions {
+    /** Cookie name. Defaults to `"locale"`. */
+    key?: string;
+    /**
+     * Domain the cookie is scoped to.
+     * e.g. `".example.com"` shares across all sub-domains.
+     * Omit for the current host only.
+     */
+    domain?: string;
+    /** Cookie path. Defaults to `"/"`. */
+    path?: string;
+    /**
+     * Max age in seconds.
+     * Defaults to 1 year (`31_536_000`).
+     * Pass `0` to create a session cookie.
+     */
+    maxAge?: number;
+    /** Mark cookie as Secure. Defaults to `true` when on `https:`. */
+    secure?: boolean;
+    /** SameSite policy. Defaults to `"Lax"`. */
+    sameSite?: "Strict" | "Lax" | "None";
+}
+/**
+ * Persists the locale in `window.localStorage`.
+ *
+ * @example
+ * <LocalizationProvider storage={localStorageStrategy()} … />
+ */
+declare function localStorageStrategy(options?: LocalStorageStrategyOptions): LocaleStorage;
+/**
+ * Persists the locale in `window.sessionStorage` (cleared on tab close).
+ *
+ * @example
+ * <LocalizationProvider storage={sessionStorageStrategy()} … />
+ */
+declare function sessionStorageStrategy(options?: SessionStorageStrategyOptions): LocaleStorage;
+/**
+ * Persists the locale as an HTTP cookie.
+ *
+ * Supports `domain`, `path`, `maxAge`, `secure`, and `sameSite` options so the
+ * same cookie can be read server-side (e.g. for SSR / middleware redirects).
+ *
+ * @example
+ * <LocalizationProvider storage={cookieStrategy({ domain: ".example.com" })} … />
+ */
+declare function cookieStrategy(options?: CookieStrategyOptions): LocaleStorage;
+/**
+ * In-memory storage — locale is lost on page reload.
+ * Useful for testing or when no persistence is desired.
+ *
+ * @example
+ * <LocalizationProvider storage={memoryStrategy()} … />
+ */
+declare function memoryStrategy(options?: {
+    initialLocale?: string;
+}): LocaleStorage;
+/**
+ * Combines multiple storages in priority order.
+ * Reads from the first storage that returns a value; writes to **all** of them.
+ *
+ * @example
+ * const storage = composeStorage(
+ *   cookieStrategy({ domain: ".example.com" }),
+ *   localStorageStrategy()
+ * );
+ */
+declare function composeStorage(...storages: LocaleStorage[]): LocaleStorage;
+
+interface LocalizationContextValue {
+    /** Active locale currently used for runtime resolution. */
+    locale: string;
+    /** Updates the active locale for all consumers under the provider. */
+    setLocale: (locale: string) => void;
+    /** Runtime store — `store.t(key, params)` looks up translations. */
+    store: LocalizationStore;
+    /** Generated runtime manifest — source of truth for keys and messages. */
+    manifest: RuntimeManifest;
+}
+interface LocalizationProviderProps {
+    /** Generated runtime manifest from `valfuse-localization generate`. */
+    manifest: RuntimeManifest;
+    /**
+     * Optional initial locale. When `storage` is also provided the stored value
+     * takes precedence over `initialLocale`.
+     */
+    initialLocale?: string;
+    /**
+     * Pluggable locale storage strategy.
+     *
+     * Built-in helpers (imported from `@valfuse-node/react`):
+     * - `localStorageStrategy()` — persists in `window.localStorage`
+     * - `sessionStorageStrategy()` — persists in `window.sessionStorage`
+     * - `cookieStrategy({ domain, maxAge, … })` — persists as a cookie
+     * - `memoryStrategy()` — in-memory only (no persistence)
+     * - `composeStorage(a, b)` — combines multiple strategies
+     */
+    storage?: LocaleStorage;
+}
+/**
+ * Provides localization state and runtime store to the React subtree.
+ *
+ * Pass a `storage` strategy to persist the selected locale across page reloads.
+ *
+ * @example
+ * import { LocalizationProvider, localStorageStrategy } from "@valfuse-node/react";
+ *
+ * <LocalizationProvider manifest={manifest} storage={localStorageStrategy()}>
+ *   <App />
+ * </LocalizationProvider>
+ */
+declare function LocalizationProvider({ manifest, initialLocale, storage, children, }: PropsWithChildren<LocalizationProviderProps>): react_jsx_runtime.JSX.Element;
+
+type InterpolationParams = Record<string, string | number>;
+type GenderVariant = "male" | "female" | "other";
+interface NamespacedLocalizer {
+    translate(key: string, fallbackValue?: string | null): string;
+    /** Returns `null` when key does not exist or is `null`/`undefined`. */
+    translateOrNull(key: string | null | undefined): string | null;
+    format(key: string, params: InterpolationParams): string;
+    /** Returns `null` when key does not exist or is `null`/`undefined`. */
+    formatOrNull(key: string | null | undefined, params: InterpolationParams): string | null;
+    plural(key: string, count: number): string;
+    /** Returns `null` when key does not exist or is `null`/`undefined`. */
+    pluralOrNull(key: string | null | undefined, count: number): string | null;
+    gender(key: string, gender: GenderVariant, params: InterpolationParams): string;
+    context(key: string, context: string, params?: InterpolationParams): string;
+}
+type TranslationFallback = string | Record<string, string> | ((key: string) => string | undefined);
+interface UseLocalizationOptions {
+    fallback?: TranslationFallback;
+}
+/**
+ * Returns the current localization context from `LocalizationProvider`.
+ *
+ * @throws Error when called outside of `LocalizationProvider`.
+ */
+declare function useLocalization(options?: UseLocalizationOptions): {
+    translate: (key: string, fallbackValue?: string | null) => string;
+    translateOrNull: (key: string | null | undefined) => string | null;
+    format: (key: string, params: InterpolationParams) => string;
+    formatOrNull: (key: string | null | undefined, params: InterpolationParams) => string | null;
+    plural: (key: string, count: number) => string;
+    pluralOrNull: (key: string | null | undefined, count: number) => string | null;
+    gender: (key: string, value: GenderVariant, params: InterpolationParams) => string;
+    context: (key: string, value: string, params?: InterpolationParams) => string;
+    namespace: (scope: string) => NamespacedLocalizer;
+    entriesForLocale: [string, string][];
+    locale: string;
+    setLocale: (locale: string) => void;
+    store: LocalizationStore;
+    manifest: _valfuse_node_localization.RuntimeManifest;
+};
+
+/**
+ * Builds a nested object API from manifest entries for ergonomic app consumption.
+ *
+ * - Non-placeholder entries → string values.
+ * - Placeholder entries → functions accepting interpolation params.
+ */
+declare function useLocalizationTree(): {
+    strings: Record<string, unknown>;
+    placeholders: Record<string, unknown>;
+};
+
+/**
+ * Creates a lazy locale loader that fetches messages from a pre-built manifest.
+ *
+ * Useful for code-splitting scenarios or SSR hydration flows where you want to
+ * load only the active locale's messages on demand.
+ */
+declare function createLazyLocaleLoader(manifest: RuntimeManifest): (locale: string) => Promise<Record<string, string>>;
+
+/**
+ * Creates an SSR-safe localization state snapshot.
+ *
+ * Use this on the server to pre-render localized content and hydrate
+ * the client with the correct locale without a flash of incorrect content.
+ */
+declare function createSsrLocalizationState(manifest: RuntimeManifest, locale?: string): {
+    locale: string;
+    messages: Record<string, string>;
+};
+
+export { type GenderVariant, type InterpolationParams, type LocaleStorage, type LocalizationContextValue, LocalizationProvider, type LocalizationProviderProps, type LocalizationStore, type NamespacedLocalizer, type TranslationFallback, type UseLocalizationOptions, type UseValfuseFormProps, type UseValfuseFormReturn, ValfuseController, type ValfuseControllerField, type ValfuseControllerFieldState, type ValfuseControllerProps, type ValfuseControllerRenderProps, type ValfuseDirtyFields, type ValfuseFieldError, type ValfuseFormControl, type ValfuseFormErrors, type ValfuseFormMode, type ValfuseFormState, type ValfuseRegisterReturn, type ValfuseTouchedFields, type ValfuseWatchCallback, type ValfuseWatchFunction, composeStorage, cookieStrategy, createLazyLocaleLoader, createLocalizationStore, createSsrLocalizationState, localStorageStrategy, memoryStrategy, sessionStorageStrategy, useLocalization, useLocalizationTree, useValfuseForm };