@krizaka/ui 3.0.0 → 3.2.0

package/dist/native/form.d.ts

@@ -0,0 +1,376 @@
+import { AnyFieldApi, StandardSchemaV1, DeepKeys, AnyFormApi } from '@tanstack/react-form';
+import * as React from 'react';
+import { DateFieldLabels, BrandId, TextFieldProps as TextFieldProps$1 } from '@krizaka/ui/native';
+import { StyleProp, ViewStyle } from 'react-native';
+
+/** A value a message placeholder takes (`{minimum}`, `{suggestion}`). */
+type FormMessageValue = string | number;
+/** An error of a field or of the whole form: the key of its words in the app's catalogue, and what fills them in. */
+interface FormFieldError {
+    /** The i18n key: `form.errors.required`, or the key a schema names (`z.string().min(3, "signUp.username.short")`). */
+    key: string;
+    /** The placeholders of the message (`{ minimum: 3 }`). */
+    values?: Readonly<Record<string, FormMessageValue>>;
+    /** The server's own words, in English: shown only when the catalogue has no message for the key. */
+    message?: string;
+    /** A value to offer instead (a free username): a button under the error sets it. Its label is passed translated. */
+    suggestion?: {
+        readonly label: string;
+        readonly value: unknown;
+    };
+    /** Shown at once, while the person types (an availability check), not only once they leave the field. */
+    immediate?: boolean;
+    /** Where it comes from: the schema (default), a field's check, or the server's answer (kept until the field changes). */
+    source?: "schema" | "check" | "server";
+}
+/** The English defaults of the generic errors, by code — the words a form shows when the app's catalogue has none. */
+declare const formMessages: Readonly<Record<string, string>>;
+/** How a form finds its words: the app's translate function, and the prefixes of its keys. */
+interface FormI18n {
+    /** The app's translate function (`(key, values) => t(key, values)`): a string, or `undefined` when the key is missing. */
+    t?: (key: string, values?: Readonly<Record<string, FormMessageValue>>) => string | undefined;
+    /** The prefix of the generic field errors. Default `form.errors` (→ `form.errors.tooShort`). */
+    prefix?: string;
+    /** The prefix of the server's codes for the whole form, as `KrizakaApiError.messageKey()`. Default `apiErrors`. */
+    apiPrefix?: string;
+    /** The locale of numbers, money and dates. Default `en`. */
+    locale?: string;
+}
+/** The words of an error: the app's catalogue, else the English default of its code, else the server's words, else the key. */
+declare function formMessage(error: FormFieldError | string, i18n?: FormI18n): string;
+/**
+ * A refusal the form shows, serialisable (a Server Action returns it): the shape of `KrizakaApiError` of @krizaka/query —
+ * a `KrizakaApiError` *is* a `FormProblem`. `fields` go under their fields, the rest above the submit button.
+ */
+interface FormProblem {
+    /** The HTTP status (0 when no response arrived). */
+    status?: number;
+    /** The stable code of the refusal (`rate-limited`, `conflict`, `ACCOUNT_EXISTS`): the key of its words. */
+    code?: string;
+    /** The server's sentence, in English: shown only when the catalogue has no message for the code. */
+    detail?: string;
+    /** The refused fields, by name: a server's `{ code, message }`, or an error the form already knows (`key`). */
+    fields?: Readonly<Record<string, {
+        code?: string;
+        message: string;
+    } | FormFieldError | string>>;
+    /** Epoch ms before which the same call is refused (a 429). */
+    retryAt?: number;
+}
+
+/** A schema the form validates with: any Standard Schema — zod 4 (`z.object`), valibot, arktype. */
+type FormSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output>;
+/** The values a form holds: the schema's input. */
+type FormValues<S> = S extends {
+    readonly "~standard": {
+        readonly types?: {
+            readonly input: infer I;
+        };
+    };
+} ? I : never;
+/** The values a form sends: the schema's output (zod transforms applied). */
+type FormOutput<S> = S extends {
+    readonly "~standard": {
+        readonly types?: {
+            readonly output: infer O;
+        };
+    };
+} ? O : never;
+/** A field's name: `email`, `address.city`, `links[0].url`. */
+type FieldName<V> = DeepKeys<V> & string;
+/** What a Server Action (or any submit) answers: done, or a refusal the form shows. */
+type FormActionResult<T = unknown> = {
+    ok: true;
+    data?: T;
+} | {
+    ok: false;
+    problem: FormProblem;
+};
+/** A value checked on the server as it is typed: an error (or its key), or nothing when the value is fine. */
+type FieldCheck<T = unknown> = (value: T, signal: AbortSignal) => Promise<FormFieldError | string | null | undefined> | FormFieldError | string | null | undefined;
+interface KrizakaFormDefinition<S extends FormSchema> {
+    /** The schema of the values (zod 4): the same one the server parses with. */
+    schema: S;
+    /** The values at first: every field of the schema. */
+    defaultValues: FormValues<S>;
+    /** The words: the app's translate function, the key prefixes, the locale. */
+    i18n?: FormI18n;
+}
+interface UseKrizakaFormOptions<S extends FormSchema, R = unknown> {
+    /** Sends the values (the schema's output): a mutation of @krizaka/query, a Server Action. Throw a `KrizakaApiError` or
+     * return `{ ok: false, problem }` to refuse: its `fields` go under their fields, the rest above the button. */
+    onSubmit?: (values: FormOutput<S>) => R | Promise<R>;
+    /** Called after a successful submit with what `onSubmit` returned (`data` of a `{ ok: true, data }`). */
+    onSuccess?: (result: R extends FormActionResult<infer T> ? T | undefined : R) => void;
+    /** Values that replace the definition's (a profile loaded from the server). */
+    defaultValues?: FormValues<S>;
+    /** Overrides the definition's words (the translate function of a hook). */
+    i18n?: FormI18n;
+    /** The server's codes that belong to a field (`{ UNDERAGE: "dateOfBirth", USERNAME_RESERVED: "username" }`): a refusal
+     * with that code shows under the field, as `form.errors.<CODE>`, instead of above the button. */
+    codeFields?: Readonly<Record<string, string>>;
+}
+/** The state of a form, for its fields and its button. */
+interface FormContextValue {
+    /** TanStack's form, through the facade: never import @tanstack/* in a product. */
+    readonly api: AnyFormApi;
+    readonly i18n: FormI18n;
+    /** The whole form's error (a refusal without a field), or null. */
+    readonly error: FormFieldError | null;
+    /** Sends the form: validates, focuses (web) or announces (native) the first error, else calls `onSubmit`. */
+    readonly submit: () => Promise<boolean>;
+}
+/** The form around a field: inside `form.Form`. */
+declare function useFormContext(): FormContextValue;
+interface FieldOptions<T> {
+    /** Checks the value on the server as it is typed (a username's availability): debounced, aborted when it changes. */
+    validateAsync?: FieldCheck<T>;
+    /** The wait, in ms, between the last change and `validateAsync`. Default 350. */
+    asyncDebounceMs?: number;
+}
+/** A field as its component draws it: the value, its setter, its error in words, its state. */
+interface KrizakaField<T = unknown> {
+    /** The id of the control (`htmlFor` of its label). */
+    readonly id: string;
+    readonly name: string;
+    readonly value: T;
+    /** Sets the value (clears a refusal of the server on it). */
+    setValue(value: T): void;
+    /** Call when the control loses focus: from then on, its errors show. */
+    readonly onBlur: () => void;
+    /** The error to show, in words — only once it should show. */
+    readonly error: string | undefined;
+    /** The error itself, with its suggestion. */
+    readonly errorDetail: FormFieldError | undefined;
+    /** A check (`validateAsync`) is running. */
+    readonly validating: boolean;
+    /** The check passed for the current value. */
+    readonly available: boolean;
+    /** The ids of the hint and the error (`aria-describedby`). */
+    readonly hintId: string;
+    readonly errorId: string;
+    /** The form's locale (numbers, money, dates). */
+    readonly locale: string;
+    /** TanStack's field, through the facade. */
+    readonly api: AnyFieldApi;
+}
+/** Binds a field of the form around it (inside `form.Form`): what the platform's field components are made of. */
+declare function useKrizakaField<T = unknown>(name: string, options?: FieldOptions<T>): KrizakaField<T>;
+/** The array of a field array, with its operations (`form.FieldArray`). */
+interface KrizakaFieldArray<T = unknown> {
+    readonly name: string;
+    readonly items: readonly T[];
+    /** Adds an item at the end. */
+    readonly push: (item: T) => void;
+    /** Removes the item at `index`. */
+    readonly remove: (index: number) => void;
+    /** Moves an item. */
+    readonly move: (from: number, to: number) => void;
+    /** The name of a sub-field of an item: `name(0, "url")` → `links[0].url`. */
+    readonly fieldName: (index: number, key?: string) => string;
+    /** The error of the array itself (too few, too many), in words, once it should show. */
+    readonly error: string | undefined;
+}
+/** Binds an array of the form (a list of links, of tiers): its items and their operations. */
+declare function useKrizakaFieldArray<T = unknown>(name: string): KrizakaFieldArray<T>;
+/** The value of a field, kept up to date (`form.Watch`): show a part of the form only when a box is ticked. */
+declare function useFormValue<T = unknown>(name: string): T;
+/** The state of the submit, for a button: sending, and whether the last try succeeded. */
+declare function useFormStatus(): {
+    submitting: boolean;
+    succeeded: boolean;
+    attempts: number;
+};
+/** The platform's components, typed by the form's field names: `name` completes and is checked against the schema. */
+type BoundFields<C, N extends string> = {
+    [K in keyof C]: C[K] extends (props: infer P) => infer R ? (P extends {
+        name: string;
+    } ? (props: Omit<P, "name"> & {
+        name: N;
+    }) => R : C[K]) : C[K];
+};
+/** A form in a component: its fields (typed by the schema), its submit and its state. */
+type KrizakaFormInstance<S extends FormSchema, C, RootProps> = BoundFields<C, FieldName<FormValues<S>>> & {
+    /** The form element (web) or view (native): renders its fields and provides them the form. */
+    Form: (props: RootProps) => React.ReactElement;
+    /** Sends the form (what `Submit` does): `true` when it went through. */
+    submit: () => Promise<boolean>;
+    /** Back to the default values (or the given ones), errors cleared. */
+    reset: (values?: FormValues<S>) => void;
+    /** Sets a field's value from outside (a suggestion, a preset). */
+    setValue: (name: FieldName<FormValues<S>>, value: unknown) => void;
+    /** The values now. */
+    getValues: () => FormValues<S>;
+    /** The whole form's error (a refusal without a field), or null. */
+    error: FormFieldError | null;
+    /** TanStack's form, the escape hatch — never import @tanstack/* in a product. */
+    api: AnyFormApi;
+};
+/** A form defined once (schema + defaults), used in components: `signUp.useForm({ onSubmit })`. */
+interface KrizakaFormFactory<S extends FormSchema, C, RootProps> {
+    readonly schema: S;
+    readonly defaultValues: FormValues<S>;
+    /** The form in a component: `onSubmit` sends the values (a mutation), a thrown `KrizakaApiError` lands on the fields. */
+    useForm<R = unknown>(options?: UseKrizakaFormOptions<S, R>): KrizakaFormInstance<S, C, RootProps>;
+    /** The form sent by a Server Action: it receives the values and answers `{ ok: true, data }` or `{ ok: false, problem }`. */
+    useFormWithAction<T = unknown>(action: (values: FormOutput<S>) => Promise<FormActionResult<T>>, options?: Omit<UseKrizakaFormOptions<S, FormActionResult<T>>, "onSubmit">): KrizakaFormInstance<S, C, RootProps>;
+}
+
+/** True for a real calendar date written `YYYY-MM-DD` (not `2001-02-30`). */
+declare function isRealDate(value: string): boolean;
+/** The latest date of birth of someone `age` years old today (`YYYY-MM-DD`): an age gate's `max`, `value <= latestBirthDate(18)`. */
+declare function latestBirthDate(age: number, today?: Date): string;
+
+type Base = {
+    /** The field's name in the schema (typed by the form). */
+    name: string;
+    /** The visible label, passed translated (also the accessible name). */
+    label: string;
+    /** A help text under the control; the error takes its place when there is one. */
+    hint?: string;
+    /** Not available. */
+    disabled?: boolean;
+    /** Styles merged last, on the field. */
+    style?: StyleProp<ViewStyle>;
+};
+type FormProps = {
+    /** The fields, the error and the button. */
+    children?: React.ReactNode;
+    /** The form's accessible name ("Create your account"), passed translated. */
+    "aria-label"?: string;
+    /** The form is the screen's scrolling content: it moves above the keyboard (iOS), keeps the focused field in view, and
+     * a tap on a button works while the keyboard is open. Give the form `flex: 1` room (a screen). */
+    scroll?: boolean;
+    /** Styles merged last, on the form's view — or its scrolled content (a column with a 16-pt gap by default). */
+    style?: StyleProp<ViewStyle>;
+};
+type SubmitProps = {
+    /** The button's words, passed translated ("Create my account"). */
+    label: string;
+    /** The look. Default `primary`. */
+    variant?: "primary" | "gradient" | "secondary" | "outline" | "ghost" | "danger";
+    /** The product whose animated mark turns in the button while the form is sent (the brand's loader); the system's spinner otherwise. */
+    brand?: BrandId;
+    /** Styles merged last, on the button. */
+    style?: StyleProp<ViewStyle>;
+};
+/** Sends the form: busy while it is sent (the product's mark turning, or a spinner); a refused submit announces its first error. */
+declare function Submit({ label, variant, brand, style }: SubmitProps): React.JSX.Element;
+type FormErrorProps = {
+    /** A headline above the message, passed translated. */
+    title?: string;
+    /** Styles merged last. */
+    style?: StyleProp<ViewStyle>;
+};
+/** The whole form's error — a refusal that belongs to no field (a conflict, too many tries, no network). */
+declare function FormError({ title, style }: FormErrorProps): React.JSX.Element | null;
+type TextFieldProps = Base & Pick<TextFieldProps$1, "secureTextEntry" | "keyboardType" | "autoComplete" | "autoCapitalize" | "autoCorrect" | "textContentType" | "returnKeyType" | "onSubmitEditing" | "placeholder" | "maxLength" | "inputRef"> & {
+    /** Cleans what is typed before it is stored (`(v) => v.toLowerCase()`). */
+    transform?: (raw: string) => string;
+    /** Checks the value on the server as it is typed (availability): an error key, or nothing when it is fine. */
+    validateAsync?: FieldCheck<string>;
+    /** The wait, in ms, before `validateAsync`. Default 350. */
+    asyncDebounceMs?: number;
+    /** The words once `validateAsync` accepted the value ("@eric is free"), passed translated. */
+    availableHint?: string;
+    /** The name of the wait while it checks ("Checking"), passed translated. */
+    checkingLabel?: string;
+};
+/** A text field of the form: its label, the input, the hint or the error, an optional check on the server. */
+declare function TextField({ name, label, hint, disabled, style, transform, validateAsync, asyncDebounceMs, availableHint, checkingLabel, ...input }: TextFieldProps): React.JSX.Element;
+type TextAreaProps = Base & {
+    /** An example, passed translated. */
+    placeholder?: string;
+    /** The most characters. */
+    maxLength?: number;
+};
+/** A longer text of the form (a bio, a description, a report). */
+declare function TextArea({ name, label, hint, disabled, style, ...input }: TextAreaProps): React.JSX.Element;
+type CheckboxProps = Omit<Base, "label" | "hint"> & {
+    /** The words next to the box: text, or a `Txt` with links inside (then name it with `accessibleLabel`). */
+    label: React.ReactNode;
+    /** The accessible name when `label` is not plain text, passed translated. */
+    accessibleLabel?: string;
+};
+/** A box of the form (`boolean`): terms to accept, an option. */
+declare function Checkbox({ name, label, accessibleLabel, disabled, style }: CheckboxProps): React.JSX.Element;
+/** An on/off setting of the form (`boolean`): its label and hint beside the system's switch. */
+declare function Switch({ name, label, hint, disabled, style }: Base): React.JSX.Element;
+/** A choice of the form: the value stored and its words (passed translated). */
+type FormOption = {
+    value: string;
+    label: string;
+    disabled?: boolean;
+};
+type RadioGroupProps = Base & {
+    /** The choices, as chips (one chosen). */
+    options: readonly FormOption[];
+    /** Scrolls the chips sideways instead of wrapping them (many choices). */
+    scrollable?: boolean;
+};
+/** One choice among a few, as chips (a radio group). On native, `Select` is the same control. */
+declare function RadioGroup({ name, label, hint, disabled, style, options, scrollable }: RadioGroupProps): React.JSX.Element;
+/** One choice among several (the web's `<select>`): chips on native, scrolled sideways when they are many. */
+declare function Select(props: RadioGroupProps): React.JSX.Element;
+type DateFieldProps = Base & {
+    /** The names of the boxes (`day`, `month`, `year`), passed translated. */
+    labels?: Partial<DateFieldLabels>;
+    /** `bday` for a date of birth. */
+    autoComplete?: "bday" | "off";
+};
+/** A date of the form (`YYYY-MM-DD`): day, month and year typed in the locale's order — the schema checks it. */
+declare function DateField({ name, label, hint, disabled, style, labels, autoComplete }: DateFieldProps): React.JSX.Element;
+type MoneyProps = Base & {
+    /** The currency (ISO 4217): its sign beside the amount, its decimals. */
+    currency: string;
+    /** An example of an amount, passed translated. */
+    placeholder?: string;
+};
+/** An amount of the form, stored as integer minor units (cents), typed on the decimal keypad the locale's way. */
+declare function Money({ name, label, hint, disabled, style, currency, placeholder }: MoneyProps): React.JSX.Element;
+type FormFieldProps<T = unknown> = {
+    /** The field's name in the schema (typed by the form). */
+    name: string;
+    /** Checks the value on the server as it changes. */
+    validateAsync?: FieldCheck<T>;
+    /** The wait, in ms, before `validateAsync`. */
+    asyncDebounceMs?: number;
+    /** Draws the field: its value, setter, error (`useKrizakaField`). */
+    children: (field: KrizakaField<T>) => React.ReactNode;
+};
+/** A field drawn by the app (a control the package does not have). */
+declare function FormField({ name, validateAsync, asyncDebounceMs, children }: FormFieldProps): React.JSX.Element;
+type FieldArrayProps<T = unknown> = {
+    /** The array's name in the schema (typed by the form). */
+    name: string;
+    /** Draws the items: `items`, `push`, `remove`, `move`, `fieldName(i, "url")`. */
+    children: (array: KrizakaFieldArray<T>) => React.ReactNode;
+};
+/** A list of fields that grows and shrinks: each item's fields named `links[0].url`. */
+declare function FieldArray({ name, children }: FieldArrayProps): React.JSX.Element;
+type WatchProps<T = unknown> = {
+    /** The field to follow (typed by the form). */
+    name: string;
+    /** Draws from its current value. */
+    children: (value: T) => React.ReactNode;
+};
+/** Renders from a field's current value (a part shown only when a choice is made). */
+declare function Watch({ name, children }: WatchProps): React.JSX.Element;
+/** A form, defined once — the same schema and defaults as the web (`packages/core` of a product) — on native fields. */
+declare const createKrizakaForm: <S extends FormSchema>(definition: KrizakaFormDefinition<S>) => KrizakaFormFactory<S, {
+    TextField: typeof TextField;
+    TextArea: typeof TextArea;
+    Checkbox: typeof Checkbox;
+    Switch: typeof Switch;
+    RadioGroup: typeof RadioGroup;
+    Select: typeof Select;
+    DateField: typeof DateField;
+    Money: typeof Money;
+    Field: typeof FormField;
+    FieldArray: typeof FieldArray;
+    Watch: typeof Watch;
+    Submit: typeof Submit;
+    FormError: typeof FormError;
+}, FormProps>;
+
+export { Checkbox, type CheckboxProps, DateField, type DateFieldProps, FieldArray, type FieldArrayProps, type FieldCheck, type FormActionResult, FormError, type FormErrorProps, FormField, type FormFieldError, type FormFieldProps, type FormI18n, type FormOption, type FormOutput, type FormProblem, type FormProps, type FormSchema, type FormValues, type KrizakaField, type KrizakaFieldArray, type KrizakaFormFactory, type KrizakaFormInstance, Money, type MoneyProps, RadioGroup, type RadioGroupProps, Select, Submit, type SubmitProps, Switch, TextArea, type TextAreaProps, TextField, type TextFieldProps, Watch, type WatchProps, createKrizakaForm, formMessage, formMessages, isRealDate, latestBirthDate, useFormContext, useFormStatus, useFormValue, useKrizakaField, useKrizakaFieldArray };