@vef-framework/components 1.0.5

package/dist/vef-form/props.d.ts

@@ -0,0 +1,158 @@
+import type { AnyValue, ApiResponse, BasicSize, BiConsumer, BiMapper, Consumer, Handler, LengthValue, MaybePromise, MutationApi, ObjectType, ObjectValue, Provider, TriConsumer, VefError } from "@vef-framework/shared";
+import type { Variant } from "antd/es/config-provider";
+import type { ReactNode } from "react";
+import type { Except, LiteralUnion } from "@vef-framework/shared";
+import type { FormActionButtonConfig, FormLabelAlign, FormLabelPosition, FormLayoutMode, FormScene, FormSchema, FormTabsUse, FormValues, FormVirtualKeys } from "./types";
+/**
+ * The instance of the VefForm component.
+ *
+ * @param Values - The type of the form values.
+ */
+export interface VefFormInstance<Values extends ObjectType = ObjectValue> {
+    /**
+     * The submit provider of the form.
+     */
+    submit: Provider<MaybePromise<void>>;
+    /**
+     * The reset handler of the form.
+     */
+    reset: Handler;
+    /**
+     * The get values provider of the form.
+     */
+    getValues: Provider<FormValues<Values>>;
+    /**
+     * The set values consumer of the form.
+     */
+    setValues: Consumer<FormValues<Values>>;
+}
+/**
+ * The props of the VefForm component.
+ *
+ * @param Values - The type of the form values.
+ * @param Result - The type of the submitted result of the form.
+ * @param Scene - The type of the form scene.
+ * @param Schema - The type of the form schema.
+ * @param VirtualKeys - The type of the virtual keys of the form.
+ */
+export interface VefFormProps<Values extends ObjectType = ObjectValue, Result = AnyValue, Scene extends FormScene = FormScene, Schema extends FormSchema<Values, Scene> = FormSchema<Values, Scene>, VirtualKeys extends FormVirtualKeys<Schema> = FormVirtualKeys<Schema>> {
+    /**
+     * The scene of the form.
+     */
+    scene: Scene;
+    /**
+     * The schema of the form.
+     */
+    schema: Schema;
+    /**
+     * The initial values of the form.
+     */
+    initialValues?: Partial<Values>;
+    /**
+     * The layout mode of the form.
+     */
+    layoutMode?: FormLayoutMode;
+    /**
+     * Whether to auto expand the remaining space of the row.
+     * Only works when the `layoutMode` is `responsive`.
+     */
+    autoExpand?: boolean;
+    /**
+     * The position of the label.
+     */
+    labelPosition?: FormLabelPosition;
+    /**
+     * The alignment of the label.
+     * Only works when the `labelPosition` is `left`.
+     */
+    labelAlign?: FormLabelAlign;
+    /**
+     * The width of the label.
+     * Only works when the `labelPosition` is `left`.
+     */
+    labelWidth?: number;
+    /**
+     * The variant of the form.
+     */
+    variant?: Variant;
+    /**
+     * Whether to show tabs.
+     * When set to true, the form will be displayed in tabs, default use is 'switch'.
+     * When set to 'switch', the form will be displayed in switchable tabs.
+     * When set to 'navigation', the form will be displayed in navigation tabs.
+     */
+    showTabs?: boolean | FormTabsUse;
+    /**
+     * The height of the form.
+     */
+    height?: LiteralUnion<"auto", LengthValue>;
+    /**
+     * The size of the form.
+     */
+    size?: BasicSize;
+    /**
+     * Whether the form is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * The submission button of the form.
+     */
+    submissionButton?: false | FormActionButtonConfig;
+    /**
+     * The reset button of the form.
+     */
+    resetButton?: false | FormActionButtonConfig;
+    /**
+     * The submit tip of the form.
+     */
+    submitTip?: ReactNode | BiMapper<Values, Scene, ReactNode>;
+    /**
+     * The submit API of the form.
+     */
+    submitApi?: Readonly<MutationApi<Except<Values, VirtualKeys>, Result>>;
+    /**
+     * The handler for processing the values of the form before submit.
+     *
+     * @param values - The values of the form.
+     * @param scene - The scene of the form.
+     * @returns The processed values of the form.
+     */
+    onBeforeSubmit?: BiMapper<Values, Scene, MaybePromise<Values>>;
+    /**
+     * The submit handler for customized processing logics.
+     *
+     * @param values - The values of the form.
+     * @param scene - The scene of the form.
+     */
+    onSubmit?: BiMapper<Except<Values, VirtualKeys>, Scene, MaybePromise<void>>;
+    /**
+     * The submit success event handler.
+     *
+     * @param result - The result of the submit API.
+     * @param values - The values of the form.
+     * @param scene - The scene of the form.
+     */
+    onSubmitSuccess?: TriConsumer<ApiResponse<Result>, Values, Scene>;
+    /**
+     * The submit failure event handler.
+     *
+     * @param error - The error.
+     * @param values - The values of the form.
+     * @param scene - The scene of the form.
+     */
+    onSubmitFailure?: TriConsumer<VefError, Values, Scene>;
+    /**
+     * The reset event handler.
+     *
+     * @param values - The values of the form.
+     * @param scene - The scene of the form.
+     */
+    onReset?: BiConsumer<FormValues<Values>, Scene>;
+    /**
+     * The change event handler.
+     *
+     * @param values - The values of the form.
+     * @param scene - The scene of the form.
+     */
+    onChange?: BiConsumer<FormValues<Values>, Scene>;
+}

package/dist/vef-form/store.d.ts

@@ -0,0 +1,89 @@
+import type { FormInstance } from "antd";
+import { type BiConsumer, type BiConsumerOptional, type ChildrenProps, type Consumer, type Mapper, type MaybeNull, type ObjectType, type Provider, type StringKey } from "@vef-framework/shared";
+import { type StoreApi } from "zustand";
+import type { FormEventBus } from "./event";
+import type { FormContext, FormScene, FormValues } from "./types";
+/**
+ * The form state.
+ */
+export interface FormState<Values extends ObjectType, Scene extends FormScene = FormScene> {
+    /**
+     * The scene of the form.
+     */
+    scene: Scene;
+    /**
+     * The form instance.
+     */
+    form: FormInstance<Values>;
+    /**
+     * The event bus of the form.
+     */
+    eventBus: FormEventBus<Values>;
+    /**
+     * The initial values of the form.
+     */
+    initialValues: Partial<Values>;
+    /**
+     * The value change handlers of the form.
+     */
+    valueChangeHandlers: Record<StringKey<Values>, BiConsumer<MaybeNull<Values[StringKey<Values>]>, FormContext<Values, Scene>>>;
+    /**
+     * Invokes the value change handlers of the form.
+     *
+     * @param values The values to invoke the value change handlers with
+     */
+    invokeValueChangeHandlers: BiConsumerOptional<FormValues<Values>, Array<StringKey<Values>>>;
+    /**
+     * The virtual field names of the form.
+     */
+    virtualFieldNames: Array<StringKey<Values>>;
+    /**
+     * Gets the form values.
+     *
+     * @returns The form values.
+     */
+    getValues: Provider<FormValues<Values>>;
+    /**
+     * Updates form values
+     *
+     * @param values The partial form values to update
+     */
+    setValues: Consumer<FormValues<Values>>;
+    /**
+     * The loading state of the form.
+     */
+    isLoading: boolean;
+    /**
+     * Sets the loading state of the form.
+     *
+     * @param loading The loading state to set
+     */
+    setIsLoading: Consumer<boolean>;
+    /**
+     * Whether to show the action buttons.
+     */
+    showActionButtons: boolean;
+    /**
+     * Sets whether to show the action buttons.
+     *
+     * @param showActionButtons The show action buttons state to set
+     */
+    setShowActionButtons: Consumer<boolean>;
+}
+/**
+ * The props of the form store provider
+ */
+export interface FormStoreProviderProps<Values extends ObjectType, Scene extends FormScene = FormScene> extends Pick<FormState<Values, Scene>, "form" | "scene" | "eventBus" | "initialValues" | "valueChangeHandlers" | "virtualFieldNames">, ChildrenProps {
+}
+/**
+ * The provider component of the form store.
+ */
+export declare function FormStoreProvider<Values extends ObjectType, Scene extends FormScene = FormScene>({ children, ...props }: FormStoreProviderProps<Values, Scene>): import("react").FunctionComponentElement<import("react").ProviderProps<MaybeNull<StoreApi<FormState<any, any>>>>>;
+/**
+ * The hook to use the form store api.
+ */
+export declare function useFormStoreApi<Values extends ObjectType, Scene extends FormScene = FormScene>(): StoreApi<FormState<Values, Scene>>;
+/**
+ * The hook to use the form store.
+ */
+export declare function useFormStore<Values extends ObjectType, Result, Scene extends FormScene = FormScene>(selector: Mapper<FormState<Values, Scene>, Result>): Result;

package/dist/vef-form/store.js

@@ -0,0 +1,3 @@
+/*! VefFramework version: 1.0.5, build time: 2024-12-10T10:24:47.065Z, made by Venus. */
+import{useSingleton as e,useUpdateEffect as t}from"@vef-framework/hooks";import{isEqual as n,VefError as o}from"@vef-framework/shared";import{createContext as s,createElement as r,useContext as i}from"react";import{createStore as a}from"zustand";import{useStoreWithEqualityFn as l}from"zustand/traditional";const u=s(null);function c({children:o,...s}){const i=e((()=>{return e=s,a(((t,o)=>({...e,invokeValueChangeHandlers(e,t){const{scene:n,valueChangeHandlers:s,initialValues:r,setValues:i}=o(),a=e??r,l=t?new Set(t):null;for(const[e,t]of Object.entries(s))l&&!l.has(e)||t(a[e]??null,{values:a,scene:n,setValues:i})},getValues(){const{form:e,initialValues:t}=o();return e.isFieldsTouched(!0)?t:e.getFieldsValue()},setValues(e){const{form:t,eventBus:s,invokeValueChangeHandlers:r}=o(),i=t.getFieldsValue(),a=Object.keys(e).filter((t=>!n(e[t],i[t])));t.setFieldsValue(e);const l=t.getFieldsValue();s.emitChange(l),r(l,a)},isLoading:!1,setIsLoading(e){t({isLoading:e})},showActionButtons:!0,setShowActionButtons(e){t({showActionButtons:e})}})));var e})),{scene:l}=s;return t((()=>{i.setState({scene:l})}),[l]),r(u.Provider,{value:i},o)}function d(){const e=i(u);if(!e)throw new o(-2,"FormStore can be used only inside FormStoreProvider");return e}function f(e){return l(d(),e,n)}export{c as FormStoreProvider,f as useFormStore,d as useFormStoreApi};
+/*! VefFramework is a blazingly high-level, modern, flexible, easy-to-use UI framework made by Venus. Follow me on Github: https://github.com/ilxqx! @ilxqx */

package/dist/vef-form/types.d.ts

@@ -0,0 +1,335 @@
+import type { Align, BiConsumer, BiMapper, Consumer, KeyValue, Mapper, MaybeComputed, MaybeComputedControlOptions, MaybeNull, ObjectType, ObjectValue, presetFormScenes, StringKey, ValidationRule } from "@vef-framework/shared";
+import type { ReactNode } from "react";
+import type { LiteralUnion, NonEmptyTuple } from "@vef-framework/shared";
+/**
+ * The layout mode of the form.
+ */
+export type FormLayoutMode = "responsive" | "fixed";
+/**
+ * The position of the form label.
+ */
+export type FormLabelPosition = "top" | "left";
+/**
+ * The alignment of the form label.
+ */
+export type FormLabelAlign = Exclude<Align, "center">;
+/**
+ * The use of the form tabs.
+ */
+export type FormTabsUse = "switch" | "navigation";
+/**
+ * The preset scene of the form.
+ */
+export type PresetFormScene = typeof presetFormScenes[number];
+/**
+ * The scene of the form.
+ */
+export type FormScene = LiteralUnion<PresetFormScene, string>;
+/**
+ * The form values.
+ */
+export type FormValues<Values extends ObjectType> = {
+    [K in keyof Values]?: MaybeNull<Values[K]>;
+};
+/**
+ * The configuration of the form action button.
+ */
+export interface FormActionButtonConfig {
+    /**
+     * The text of the form action button.
+     */
+    text?: string;
+    /**
+     * Whether to display the form action button as a block element.
+     */
+    block?: boolean;
+    /**
+     * The icon of the form action button.
+     */
+    icon?: ReactNode;
+}
+/**
+ * The validation rule of the form item.
+ */
+export type FormValidationRule<Values extends ObjectType, Key extends StringKey<Values>, Scene extends FormScene> = Mapper<FormItem<Values, Key, Scene>, ValidationRule[]>;
+/**
+ * The compute function of the form.
+ */
+type ComputeFn<Values extends ObjectType, Scene extends FormScene, ComputedValue> = BiMapper<FormValues<Values>, Scene, ComputedValue>;
+/**
+ * The computed type of the form.
+ */
+export type FormComputedType<Values extends ObjectType, Scene extends FormScene, ComputedValue> = MaybeComputed<ComputedValue, ComputeFn<Values, Scene, ComputedValue>>;
+/**
+ * The control options of the form.
+ */
+type ControlOptions<Values extends ObjectType, Scene extends FormScene> = MaybeComputedControlOptions<ComputeFn<Values, Scene, boolean>>;
+/**
+ * The context of the form.
+ */
+export interface FormContext<Values extends ObjectType, Scene extends FormScene> {
+    /**
+     * The values of the form.
+     */
+    values: FormValues<Values>;
+    /**
+     * The scene of the form.
+     */
+    scene: Scene;
+    /**
+     * Set the values of the form.
+     *
+     * @param values - The values of the form.
+     */
+    setValues: Consumer<FormValues<Values>>;
+}
+/**
+ * The internal context of the form.
+ */
+export interface InternalFormContext {
+    /**
+     * The layout mode of the form.
+     */
+    layoutMode: FormLayoutMode;
+    /**
+     * The position of the form label.
+     */
+    labelPosition: FormLabelPosition;
+    /**
+     * The width of the form label.
+     */
+    labelWidth?: number;
+    /**
+     * Whether to auto expand the remaining space of the row.
+     */
+    autoExpand: boolean;
+}
+/**
+ * The virtual keys of the form.
+ */
+export type FormVirtualKeys<S extends ReadonlyArray<FormGroup<any, any>>> = FormVirtualItems<FlattenFormItem<S>>[number];
+type FormVirtualItems<T extends ReadonlyArray<FormItem<any>>> = {
+    [K in keyof T]: T[K]["virtual"] extends true ? T[K]["name"] : never;
+};
+type FlattenFormItem<T extends readonly any[]> = T extends readonly [infer Head, ...infer Tail] ? Head extends FormGroup<any> ? [...FlattenFormItem<Head["rows"]>, ...FlattenFormItem<Tail>] : Head extends FormRow<any> ? [...FlattenFormItem<Head["columns"]>, ...FlattenFormItem<Tail>] : Head extends FormColumn<any> ? [...FlattenFormItem<Head["items"]>, ...FlattenFormItem<Tail>] : Head extends FormItem<any> ? [Head, ...FlattenFormItem<Tail>] : FlattenFormItem<Tail> : [];
+/**
+ * The form schema.
+ */
+export type FormSchema<Values extends ObjectType, Scene extends FormScene = FormScene> = NonEmptyTuple<FormGroup<Values, Scene>>;
+/**
+ * The form group of the form.
+ */
+export interface FormGroup<Values extends ObjectType = ObjectValue, Scene extends FormScene = FormScene> extends ControlOptions<Values, Scene> {
+    /**
+     * The key of the form group.
+     */
+    key: KeyValue;
+    /**
+     * The title of the form group.
+     */
+    title?: FormComputedType<Values, Scene, ReactNode>;
+    /**
+     * The rows of the form group.
+     */
+    rows: ReadonlyArray<FormRow<Values, Scene>>;
+}
+/**
+ * The row of the form group.
+ */
+export interface FormRow<Values extends ObjectType = ObjectValue, Scene extends FormScene = FormScene> extends ControlOptions<Values, Scene> {
+    /**
+     * The key of the form row.
+     */
+    key: KeyValue;
+    /**
+     * Whether to auto expand the remaining space of the form row.
+     */
+    autoExpand?: boolean;
+    /**
+     * The columns of the form row.
+     */
+    columns: ReadonlyArray<FormColumn<Values, Scene>>;
+}
+/**
+ * The column of the form row.
+ */
+export interface FormColumn<Values extends ObjectType = ObjectValue, Scene extends FormScene = FormScene> extends ControlOptions<Values, Scene> {
+    /**
+     * The key of the form column.
+     */
+    key: KeyValue;
+    /**
+     * The span of the form column.
+     */
+    span?: number;
+    /**
+     * The items of the form column.
+     */
+    items: ReadonlyArray<FormItem<Values, StringKey<Values>, Scene>>;
+}
+/**
+ * The form item.
+ */
+export type FormItem<Values extends ObjectType = ObjectValue, Key extends StringKey<Values> = StringKey<Values>, Scene extends FormScene = FormScene> = FormItemHidden<Values, Key, Scene> | FormItemInput<Values, Key, Scene> | FormItemInputNumber<Values, Key, Scene>;
+/**
+ * The base form item.
+ */
+export interface FormItemBase<Values extends ObjectType, Key extends StringKey<Values> = StringKey<Values>, Scene extends FormScene = FormScene> extends ControlOptions<Values, Scene> {
+    /**
+     * The name of the form item.
+     */
+    name: Key;
+    /**
+     * The label of the form item.
+     */
+    label?: FormComputedType<Values, Scene, ReactNode>;
+    /**
+     * The tip of the form item.
+     */
+    tip?: FormComputedType<Values, Scene, ReactNode>;
+    /**
+     * The validation rules of the form item.
+     */
+    rules?: FormComputedType<Values, Scene, Array<FormValidationRule<Values, Key, Scene>>>;
+    /**
+     * Whether the form item is virtual.
+     * That means the form item is not a real form item to input data, but a virtual item to help control the other form items.
+     */
+    virtual?: boolean;
+    /**
+     * The default value of the form item.
+     */
+    defaultValue?: Values[Key];
+}
+/**
+ * The hidden form item.
+ */
+export interface FormItemHidden<Values extends ObjectType, Key extends StringKey<Values> = StringKey<Values>, Scene extends FormScene = FormScene> extends FormItemBase<Values, Key, Scene> {
+    /**
+     * The type of the hidden form item.
+     */
+    type: "Hidden";
+    /**
+     * The label of the form item.
+     */
+    label?: undefined;
+    /**
+     * The tip of the form item.
+     */
+    tip?: undefined;
+    /**
+     * The validation rules of the form item.
+     */
+    rules?: undefined;
+    /**
+     * Whether to disable the form item.
+     */
+    disabled?: undefined;
+    /**
+     * The default value of the hidden form item.
+     */
+    defaultValue?: Values[Key];
+}
+/**
+ * The input form item.
+ */
+export interface FormItemInput<Values extends ObjectType, Key extends StringKey<Values> = StringKey<Values>, Scene extends FormScene = FormScene> extends FormItemBase<Values, Key, Scene> {
+    /**
+     * The type of the input form item.
+     */
+    type: "Input";
+    /**
+     * The default value of the form item.
+     */
+    defaultValue?: Values[Key] & string;
+    /**
+     * The placeholder of the input form item.
+     */
+    placeholder?: FormComputedType<Values, Scene, string>;
+    /**
+     * Whether the input form item is allow clear.
+     */
+    clearable?: boolean;
+    /**
+     * The maximum number of characters in the input form item.
+     */
+    maxLength?: FormComputedType<Values, Scene, number>;
+    /**
+     * The prefix of the input form item.
+     */
+    prefix?: FormComputedType<Values, Scene, ReactNode>;
+    /**
+     * The suffix of the input form item.
+     */
+    suffix?: FormComputedType<Values, Scene, ReactNode>;
+    /**
+     * The on change event handler of the form item.
+     */
+    onChange?: BiConsumer<MaybeNull<Values[Key] & string>, FormContext<Values, Scene>>;
+    /**
+     * The enter key press event handler of the input form item.
+     */
+    onEnterKeyPress?: BiConsumer<MaybeNull<Values[Key] & string>, FormContext<Values, Scene>>;
+    /**
+     * The blur event handler of the input form item.
+     */
+    onBlur?: BiConsumer<MaybeNull<Values[Key] & string>, FormContext<Values, Scene>>;
+    /**
+     * The focus event handler of the input form item.
+     */
+    onFocus?: BiConsumer<MaybeNull<Values[Key] & string>, FormContext<Values, Scene>>;
+    /**
+     * The clear event handler of the input form item.
+     */
+    onClear?: Consumer<FormContext<Values, Scene>>;
+}
+/**
+ * The input number form item.
+ */
+export interface FormItemInputNumber<Values extends ObjectType, Key extends StringKey<Values> = StringKey<Values>, Scene extends FormScene = FormScene> extends FormItemBase<Values, Key, Scene> {
+    /**
+     * The type of the input number form item.
+     */
+    type: "InputNumber";
+    /**
+     * The default value of the form item.
+     */
+    defaultValue?: Values[Key] & number;
+    /**
+     * The placeholder of the input number form item.
+     */
+    placeholder?: FormComputedType<Values, Scene, string>;
+    /**
+     * The prefix of the input number form item.
+     */
+    prefix?: FormComputedType<Values, Scene, ReactNode>;
+    /**
+     * The suffix of the input number form item.
+     */
+    suffix?: FormComputedType<Values, Scene, ReactNode>;
+    /**
+     * The maximum value of the input number form item.
+     */
+    max?: FormComputedType<Values, Scene, number>;
+    /**
+     * The minimum value of the input number form item.
+     */
+    min?: FormComputedType<Values, Scene, number>;
+    /**
+     * The on change event handler of the input number form item.
+     */
+    onChange?: BiConsumer<MaybeNull<Values[Key] & number>, FormContext<Values, Scene>>;
+    /**
+     * The enter key press event handler of the input number form item.
+     */
+    onEnterKeyPress?: BiConsumer<MaybeNull<Values[Key] & number>, FormContext<Values, Scene>>;
+    /**
+     * The blur event handler of the input number form item.
+     */
+    onBlur?: BiConsumer<MaybeNull<Values[Key] & number>, FormContext<Values, Scene>>;
+    /**
+     * The focus event handler of the input number form item.
+     */
+    onFocus?: BiConsumer<MaybeNull<Values[Key] & number>, FormContext<Values, Scene>>;
+}
+export {};