@servicetitan/form-state 22.4.0

package/src/demo/dropdown-state.tsx

@@ -0,0 +1,233 @@
+import { useRef, Fragment, FC } from 'react';
+
+import { InMemoryDataSource, AsyncDataSource, FilterDescriptor } from '@servicetitan/data-query';
+
+import {
+    AnvilSelect,
+    AnvilSelectOptionsProps,
+    Text,
+    ButtonGroup,
+    Button,
+} from '@servicetitan/design-system';
+
+import { FieldState } from 'formstate';
+import { observer } from 'mobx-react';
+
+import { DropdownState, DropdownOption } from '..';
+
+function useDropdownField<T>(initial: T) {
+    return useRef(new FieldState(initial)).current;
+}
+
+function useDropdownState<T extends DropdownOption<any>>(state: DropdownState<T>) {
+    return useRef(state).current;
+}
+
+interface Planet extends DropdownOption<number> {
+    diameter: number;
+    moons: number;
+}
+
+const options: Planet[] = [
+    { value: 1, text: 'Alderaan', diameter: 12500, moons: 0 },
+    { value: 2, text: 'Bespin', diameter: 118000, moons: 2 },
+    { value: 3, text: 'Coruscant', diameter: 12240, moons: 4 },
+    { value: 4, text: 'Dagobah', diameter: 14410, moons: 0 },
+    { value: 5, text: 'Hoth', diameter: 7200, moons: 3 },
+    { value: 6, text: 'Kashyyyk', diameter: 12765, moons: 3 },
+    { value: 7, text: 'Naboo', diameter: 12120, moons: 3 },
+    { value: 8, text: 'Tatooine', diameter: 10465, moons: 3 },
+    { value: 9, text: 'Yavin', diameter: 200000, moons: 26 },
+];
+
+interface Character extends DropdownOption<number> {
+    group: string;
+}
+
+const optionsWithGroups: Character[] = [
+    { value: 1, text: 'Hem Dazon', group: 'Arcona' },
+    { value: 2, text: 'El-Les', group: 'Arcona' },
+    { value: 3, text: 'Jheeg', group: 'Arcona' },
+    { value: 4, text: 'Paploo', group: 'Ewok' },
+    { value: 5, text: 'Gallo', group: 'Gungan' },
+    { value: 6, text: 'Lyonie', group: 'Gungan' },
+    { value: 7, text: 'Tobler Ceel', group: 'Gungan' },
+    { value: 8, text: 'Ganne', group: 'Gungan' },
+    { value: 9, text: 'Augara Jowil', group: 'Gungan' },
+    { value: 10, text: 'Reegesk', group: 'Ranat' },
+    { value: 11, text: 'Rik-tak', group: 'Ranat' },
+    { value: 12, text: 'Bahb', group: 'Zeltron' },
+    { value: 13, text: 'Chantique', group: 'Zeltron' },
+    { value: 14, text: 'Luxa', group: 'Zeltron' },
+    { value: 15, text: 'Rahuhl', group: 'Zeltron' },
+];
+
+const InMemoryDropdownStateExample: FC = observer(() => {
+    const field = useDropdownField<AnvilSelectOptionsProps[]>([]);
+    const state = useDropdownState(
+        new DropdownState<Planet | Character>({
+            dataSource: new InMemoryDataSource(options),
+        })
+    );
+
+    const handleChange = (data: AnvilSelectOptionsProps | AnvilSelectOptionsProps[]) => {
+        field.onChange(Array.isArray(data) ? data : [data]);
+    };
+
+    const withReset = (handler: () => void) => {
+        return async () => {
+            handleChange([]);
+            state.setSearch('');
+            state.setDataSource(null);
+            state.setSearchByGroup(false);
+            state.setSort([{ field: 'text' }]);
+            state.setFilter(null);
+            state.setGroup([{ field: 'group' }]);
+
+            await Promise.resolve();
+
+            handler();
+        };
+    };
+
+    const withoutGroups = withReset(() => {
+        state.setDataSource(new InMemoryDataSource(options));
+    });
+
+    const withGroups = withReset(() => {
+        state.setDataSource(new InMemoryDataSource(optionsWithGroups));
+    });
+
+    const withGroupsAndSearch = withReset(() => {
+        state.setDataSource(new InMemoryDataSource(optionsWithGroups));
+        state.setSearchByGroup(true);
+    });
+
+    const customSort = withReset(() => {
+        state.setDataSource(new InMemoryDataSource(options));
+        state.setSort([{ field: 'diameter', dir: 'desc' }]);
+    });
+
+    const customFilter = withReset(() => {
+        state.setDataSource(new InMemoryDataSource(options));
+        state.setFilter({
+            logic: 'and',
+            filters: [{ field: 'diameter', value: 12250, operator: 'gte' }],
+        });
+    });
+
+    const customGroup = withReset(() => {
+        state.setDataSource(new InMemoryDataSource(options));
+        state.setGroup([{ field: 'moons', dir: 'desc' }]);
+    });
+
+    return (
+        <Fragment>
+            <AnvilSelect
+                value={field.value}
+                onChange={handleChange}
+                options={state.options}
+                search={{ value: state.search, onChange: state.onSearchChange }}
+                multiple
+            />
+
+            <Text size={4} className="m-t-4 m-b-half">
+                Without groups
+            </Text>
+            <Button onClick={withoutGroups}>Apply</Button>
+
+            <Text size={4} className="m-t-4 m-b-half">
+                With groups
+            </Text>
+            <ButtonGroup>
+                <Button onClick={withGroups}>Search in options</Button>
+                <Button onClick={withGroupsAndSearch}>Search in options & groups</Button>
+            </ButtonGroup>
+
+            <Text size={4} className="m-t-4 m-b-half">
+                Custom sort
+            </Text>
+            <Button onClick={customSort}>Apply</Button>
+
+            <Text size={4} className="m-t-4 m-b-half">
+                Custom filter
+            </Text>
+            <Button onClick={customFilter}>Apply</Button>
+
+            <Text size={4} className="m-t-4 m-b-half">
+                Custom group
+            </Text>
+            <Button onClick={customGroup}>Apply</Button>
+        </Fragment>
+    );
+});
+
+const AsyncDropdownStateExample: FC = observer(() => {
+    const field = useDropdownField<AnvilSelectOptionsProps[]>([]);
+    const state = useDropdownState(
+        new DropdownState<Planet>({
+            dataSource: new AsyncDataSource(
+                {
+                    async get({ filter }) {
+                        const search = (filter?.filters?.[0] as FilterDescriptor | undefined)
+                            ?.value as string | undefined;
+
+                        const result = search
+                            ? options.filter(({ text }) =>
+                                  text.toLowerCase().includes(search.toLowerCase())
+                              )
+                            : options;
+
+                        await new Promise(resolver => setTimeout(resolver, 1000));
+
+                        return {
+                            data: result,
+                            total: result.length,
+                        };
+                    },
+                },
+                undefined,
+                true
+            ),
+            lazy: true,
+        })
+    );
+
+    const handleChange = (data: AnvilSelectOptionsProps | AnvilSelectOptionsProps[]) => {
+        field.onChange(Array.isArray(data) ? data : [data]);
+    };
+
+    const handleOpenChange = (open: boolean) => {
+        if (open) {
+            state.fetch();
+        }
+    };
+
+    return (
+        <AnvilSelect
+            value={field.value}
+            onChange={handleChange}
+            options={state.options}
+            search={{ value: state.search, onChange: state.onSearchChange }}
+            onOpenChange={handleOpenChange}
+            loading={state.loading}
+            multiple
+        />
+    );
+});
+
+export const DropdownStateExample: FC = () => {
+    return (
+        <Fragment>
+            <Text size={5} className="m-b-half">
+                InMemoryDataSource
+            </Text>
+            <InMemoryDropdownStateExample />
+
+            <Text size={5} className="m-t-5 m-b-half">
+                AsyncDataSource
+            </Text>
+            <AsyncDropdownStateExample />
+        </Fragment>
+    );
+};

package/src/demo/index.ts

@@ -0,0 +1 @@
+export * from './dropdown-state';

package/src/dropdown-state.ts

@@ -0,0 +1,205 @@
+import { ChangeEvent } from 'react';
+import {
+    State,
+    SortDescriptor,
+    CompositeFilterDescriptor,
+    GroupDescriptor,
+    GroupResult,
+    DataSource,
+} from '@servicetitan/data-query';
+
+import { InputOnChangeData, AnvilSelectOptionsProps } from '@servicetitan/design-system';
+
+import { observable, computed, action, runInAction, makeObservable } from 'mobx';
+
+import debounce from 'debounce';
+
+function isGroupItem<T>(item: T | GroupResult<T>, groupedBy: string): item is GroupResult<T> {
+    const { items, field } = item as GroupResult<T>;
+    return !!items && field === groupedBy;
+}
+
+export interface DropdownOption<T> {
+    value: T;
+    text: string;
+}
+
+interface DropdownStateConstructorParams<T> {
+    dataSource?: DataSource<T>;
+    searchByGroup?: boolean;
+    state?: {
+        sort?: SortDescriptor[];
+        filter?: CompositeFilterDescriptor;
+        group?: [GroupDescriptor];
+    };
+    lazy?: boolean;
+}
+
+export class DropdownState<T extends DropdownOption<any>> {
+    @observable loading = false;
+    @observable search = '';
+
+    @computed get options() {
+        const result = new Map<T[keyof T], AnvilSelectOptionsProps>();
+        const flat: AnvilSelectOptionsProps[] = [];
+
+        const groupField = this.group[0].field;
+
+        this.traverse(
+            this.data,
+            item => {
+                const group = item[groupField as keyof T];
+
+                if (group) {
+                    if (result.has(group)) {
+                        result.get(group)?.options?.push(item);
+                    } else {
+                        result.set(group, {
+                            value: group,
+                            text: String(group),
+                            options: [item],
+                        });
+                    }
+                } else {
+                    flat.push(item);
+                }
+            },
+            groupField
+        );
+
+        return [...flat, ...Array.from(result.values())];
+    }
+
+    @computed get state() {
+        return {
+            sort: this.sort,
+            filter:
+                this.searchFilter || this.filter
+                    ? this.searchFilter && this.filter
+                        ? { logic: 'and', filters: [this.searchFilter, this.filter] }
+                        : this.searchFilter ?? this.filter
+                    : undefined,
+            group: this.group,
+        } as State;
+    }
+
+    @computed private get searchFilter() {
+        if (!this.search) {
+            return undefined;
+        }
+
+        const filter = { operator: 'contains', value: this.search, ignoreCase: true };
+
+        return {
+            logic: 'or',
+            filters: [
+                { ...filter, field: 'text' },
+                ...(this.searchByGroup ? [{ ...filter, field: 'group' }] : []),
+            ],
+        } as CompositeFilterDescriptor;
+    }
+
+    @observable private dataSource: DataSource<T> | null;
+    @observable private searchByGroup: boolean;
+    @observable private sort: SortDescriptor[];
+    @observable private filter: CompositeFilterDescriptor | null;
+    @observable private group: [GroupDescriptor];
+
+    @observable private data: T[] | GroupResult<T>[] = [];
+
+    constructor({
+        dataSource,
+        searchByGroup,
+        state,
+        lazy,
+    }: DropdownStateConstructorParams<T> = {}) {
+        makeObservable(this);
+
+        this.dataSource = dataSource ?? null;
+        this.searchByGroup = searchByGroup ?? false;
+        this.sort = state?.sort ?? [{ field: 'text' }];
+        this.filter = state?.filter ?? null;
+        this.group = state?.group ?? [{ field: 'group' }];
+
+        if (!lazy) {
+            this.fetch();
+        }
+    }
+
+    // eslint-disable-next-line @typescript-eslint/member-ordering
+    onSearchChange = (() => {
+        const fetch = debounce(() => this.fetch(), 100);
+        return (_0: ChangeEvent<HTMLInputElement>, data: InputOnChangeData) => {
+            runInAction(() => {
+                this.search = data.value;
+            });
+            fetch();
+        };
+    })();
+
+    @action
+    setSearch = async (search: string) => {
+        this.search = search;
+        await this.fetch();
+    };
+
+    @action
+    setDataSource = async (dataSource: DataSource<T> | null) => {
+        this.dataSource = dataSource;
+        await this.fetch();
+    };
+
+    @action
+    setSearchByGroup = async (searchByGroup: boolean) => {
+        this.searchByGroup = searchByGroup;
+        await this.fetch();
+    };
+
+    @action
+    setSort = async (sort: SortDescriptor[]) => {
+        this.sort = sort;
+        await this.fetch();
+    };
+
+    @action
+    setFilter = async (filter: CompositeFilterDescriptor | null) => {
+        this.filter = filter;
+        await this.fetch();
+    };
+
+    @action
+    setGroup = async (group: [GroupDescriptor]) => {
+        this.group = group;
+        await this.fetch();
+    };
+
+    @action
+    fetch = async () => {
+        this.loading = true;
+
+        const response = await this.dataSource?.getData(this.state);
+
+        runInAction(() => {
+            this.data = response?.data ?? [];
+            this.loading = false;
+        });
+    };
+
+    private traverse = (
+        items: T[] | GroupResult<T>[],
+        itemCallback: (item: T) => void,
+        groupedBy: string
+    ) => {
+        if (!items) {
+            return;
+        }
+
+        for (const item of items) {
+            if (isGroupItem(item, groupedBy)) {
+                this.traverse(item.items, itemCallback, groupedBy);
+            } else {
+                itemCallback(item);
+            }
+        }
+    };
+}

package/src/form-helpers.ts

@@ -0,0 +1,259 @@
+import { SyntheticEvent, ChangeEvent, Key, ReactNode } from 'react';
+import { FieldState, FormState, ValidatableMapOrArray, ComposibleValidatable } from 'formstate';
+import { toJS, isObservableMap, runInAction, transaction, computed, comparer } from 'mobx';
+
+export class CheckboxFieldState extends FieldState<boolean> {
+    onChangeHandler = (_0: any, checked: boolean) => {
+        this.onChange(checked);
+    };
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    DEPRECATED_onChangeHandler = (
+        _0: SyntheticEvent<HTMLInputElement>,
+        data: { checked?: boolean }
+    ) => {
+        this.onChange(!!data.checked);
+    };
+}
+
+export class InputFieldState<T> extends FieldState<T> {
+    onChangeHandler = (_0: SyntheticEvent<HTMLInputElement>, data: { value: T }) => {
+        this.onChange(data.value);
+    };
+    onChangeNativeHandler = (event: ChangeEvent<HTMLInputElement>) => {
+        this.onChange(event.currentTarget.value as unknown as T);
+    };
+}
+
+export class TextAreaFieldState<T> extends FieldState<T> {
+    /**
+     * react-semantic type for onChange event of TextArea component seems to have a bug with data object type
+     * so declaring data as any
+     */
+    onChangeHandler = (_0: SyntheticEvent<HTMLTextAreaElement>, data: any) => {
+        this.onChange(data.value);
+    };
+}
+
+export class DropdownFieldState<T> extends FieldState<T> {
+    /**
+     * react-semantic type for onChange event of Dropdown component seems to have a bug with data object type
+     * so declaring data as any
+     */
+    onChangeHandler = (_0: SyntheticEvent<HTMLElement>, data: any) => {
+        this.onChange(data.value);
+    };
+}
+
+export class DropdownSearchFieldState<T> extends FieldState<T> {
+    onChangeHandler = (_0: SyntheticEvent<HTMLElement>, data: { searchQuery: T }) => {
+        this.onChange(data.searchQuery);
+    };
+}
+
+export class DatetimeFieldState extends FieldState<Date | null> {
+    onChangeHandler = (event: { target: { value: Date | null } }) => {
+        this.onChange(event.target.value);
+    };
+}
+
+export interface Option<T> {
+    key: Key;
+    text: ReactNode;
+    value: T;
+}
+
+export function enumToOptions<T>(
+    enumObject: T,
+    nameProvider?: (value: T[keyof T]) => Option<T[keyof T]>['text']
+): Option<T[keyof T]>[] {
+    return getEnumKeys(enumObject).map(k => ({
+        key: k as string,
+        text: nameProvider ? nameProvider(enumObject[k]) : k,
+        value: enumObject[k],
+    }));
+}
+
+export function getEnumKeys<T>(enumObject: T) {
+    let keys = Object.keys(enumObject) as (keyof T)[];
+
+    if (keys.some(k => typeof enumObject[k] === 'number')) {
+        keys = keys.filter(k => typeof enumObject[k] === 'number');
+    }
+
+    return keys;
+}
+
+export function getEnumValues<T>(enumObject: T) {
+    return getEnumKeys(enumObject).map(k => enumObject[k]);
+}
+
+export type FormValues = string | number | boolean | (string | number | boolean)[];
+export interface FormStateAsJS {
+    [index: string]: FormValues | Map<any, any> | Set<any> | FormStateAsJS;
+}
+
+export function traverseFormState<T extends ValidatableMapOrArray>(
+    recursive: boolean,
+    formState: FormState<T>,
+    onFormVisit?: (key: string, form: FormState<any>) => void,
+    onFieldVisit?: (key: string, field: FieldState<any>) => void
+) {
+    const visitChild = (key: string, child: ComposibleValidatable<any>) => {
+        if (child instanceof FormState) {
+            if (recursive) {
+                traverseFormState(recursive, child, onFormVisit, onFieldVisit);
+            }
+            if (onFormVisit) {
+                onFormVisit(key, child);
+            }
+        } else if (onFieldVisit) {
+            onFieldVisit(key, child as FieldState<any>);
+        }
+    };
+
+    if (Array.isArray(formState.$)) {
+        formState.$.forEach((child, index) => visitChild(index.toString(), child));
+    } else {
+        (isObservableMap(formState.$)
+            ? Array.from(formState.$ as Map<any, ComposibleValidatable<any>>)
+            : Object.entries(formState.$ as Record<string, ComposibleValidatable<any>>)
+        ).forEach(([key, child]) => visitChild(key, child));
+    }
+}
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export function BAD_formStateToJS<T extends ValidatableMapOrArray>(formState: FormState<T>) {
+    const formValues = {} as any;
+    traverseFormState(
+        false,
+        formState,
+        (key: any, form: FormState<any>) => (formValues[key] = BAD_formStateToJS(form)),
+        (key: any, field: FieldState<any>) => (formValues[key] = toJS(field.value))
+    );
+    return formValues as unknown as FormStateAsJS;
+}
+
+export type FormStateShape<T> = T extends FormState<infer U>[]
+    ? FormStateMapOrObject<U>[]
+    : FormStateMapOrObject<T>;
+
+type FormStateMapOrObject<T> = T extends Map<infer K, infer V>
+    ? FormStateObject<Record<K & (string | number | symbol), V>>
+    : FormStateObject<T>;
+
+type FormStateObject<T> = {
+    [P in keyof T]: T[P] extends FieldState<infer U>
+        ? U
+        : T[P] extends FormState<infer U>
+        ? FormStateShape<U>
+        : never;
+};
+
+export function formStateToJS<T extends ValidatableMapOrArray>(
+    formState: FormState<T>
+): FormStateShape<T> {
+    const formValues = Array.isArray(formState.$) ? [] : ({} as any);
+    traverseFormState(
+        false,
+        formState,
+        (key: any, form: FormState<any>) => (formValues[key] = formStateToJS(form)),
+        (key: any, field: FieldState<any>) => (formValues[key] = toJS(field.$))
+    );
+    return formValues as unknown as FormStateShape<T>;
+}
+
+export type RecursivePartial<T> = T extends (infer U)[]
+    ? RecursivePartialObject<U>[]
+    : RecursivePartialObject<T>;
+
+type RecursivePartialObject<T> = {
+    [P in keyof T]?: T[P] extends Record<any, any> ? RecursivePartial<T[P]> : T[P];
+};
+
+export function setFormStateValues<T extends ValidatableMapOrArray>(
+    formState: FormState<T>,
+    data: RecursivePartial<FormStateShape<T>>,
+    triggerValidation = false
+): FormState<T> {
+    if (Array.isArray(formState.$) && (data as any[]).length !== formState.$.length) {
+        throw new Error(
+            'Number of elements in data object node is different from number of element in form.' +
+                ' All array nodes should match in size before values can be applied to form.'
+        );
+    }
+    transaction(() => {
+        traverseFormState(
+            false,
+            formState,
+            (key: string, form: FormState<any>) => {
+                if (data instanceof Map || isObservableMap(data)) {
+                    if (data.has(key)) {
+                        setFormStateValues(form, data.get(key));
+                    }
+                } else {
+                    if (Object.prototype.hasOwnProperty.call(data, key)) {
+                        setFormStateValues(form, data[key as keyof typeof data]);
+                    }
+                }
+            },
+            (key: string, field: FieldState<any>) => {
+                if (data instanceof Map || isObservableMap(data)) {
+                    if (data.has(key)) {
+                        runInAction(() => {
+                            field.value = data.get(key);
+                            field.$ = data.get(key);
+                        });
+                    }
+                } else {
+                    if (Object.prototype.hasOwnProperty.call(data, key)) {
+                        runInAction(() => {
+                            field.value = data[key as keyof typeof data];
+                            field.$ = data[key as keyof typeof data];
+                        });
+                    }
+                }
+            }
+        );
+        if (triggerValidation) {
+            const setValidatedSubFields = (form: FormState<any>) => {
+                form.validatedSubFields = (form as any).getValues();
+            };
+            traverseFormState(true, formState, (_0: string, form: FormState<any>) => {
+                setValidatedSubFields(form);
+            });
+            setValidatedSubFields(formState);
+            formState.validate();
+        }
+    });
+    return formState;
+}
+
+export function commitFormState<T extends ValidatableMapOrArray>(formState: FormState<T>) {
+    traverseFormState(true, formState, undefined, (_0: string, field: FieldState<any>) => {
+        field.dirty = false;
+        (field as any)._initValue = field.value;
+    });
+}
+
+export function camelCaseToTitleCase(value: string) {
+    const regexp = /[A-Z](?=[A-Z][a-z])|[^A-Z](?=[A-Z])|[A-Za-z](?=[^A-Za-z])/g;
+    return value.replace(regexp, '$& ');
+}
+
+export function isFormStateChanged<T extends ValidatableMapOrArray>(formState: FormState<T>) {
+    return computed(() => {
+        let isChanged = false;
+        traverseFormState(true, formState, undefined, (_0: string, field: FieldState<any>) => {
+            const isValueChanged = () => {
+                if (field instanceof InputFieldState) {
+                    if ((field as any)._initValue === undefined && field.value === '') {
+                        return false;
+                    }
+                }
+                return !comparer.structural((field as any)._initValue, field.value);
+            };
+            isChanged = isChanged || (field.dirty === true && isValueChanged());
+        });
+        return isChanged;
+    });
+}