@lifesg/web-frontend-engine 1.0.0-alpha.2 → 1.0.0-alpha.4

package/components/frontend-engine/types.d.ts

@@ -1,13 +1,15 @@
-import { ControllerFieldState, ControllerRenderProps, UseFormSetValue, ValidationMode } from "react-hook-form";
+import { ControllerFieldState, ControllerRenderProps, UseFormReset, UseFormSetValue, ValidationMode } from "react-hook-form";
+import { IFilterSchema } from "../custom/filter/filter/types";
 import { IAlertSchema, ITextSchema } from "../elements";
+import { ISectionSchema } from "../elements/section";
 import { IWrapperSchema } from "../elements/wrapper";
-import { ICheckboxGroupSchema, IChipsSchema, IContactNumberSchema, IDateInputSchema, IEmailSchema, IMultiSelectSchema, INumberSchema, IRadioButtonGroupSchema, ISelectSchema, ISubmitButtonSchema, ITextareaSchema, ITextfieldSchema, ITimePickerSchema } from "../fields";
+import { ICheckboxGroupSchema, IChipsSchema, IContactFieldSchema, IDateFieldSchema, IEmailFieldSchema, IMultiSelectSchema, INumericFieldSchema, IRadioButtonGroupSchema, IResetButtonSchema, ISelectSchema, ISubmitButtonSchema, ITextFieldSchema, ITextareaSchema, ITimeFieldSchema, IUnitNumberFieldSchema } from "../fields";
 import { IYupValidationRule, TRenderRules, TYupSchemaType } from "./yup";
 export type { IYupValidationRule } from "./yup";
 export interface IFrontendEngineProps<V = undefined> {
     /** HTML class attribute that is applied on the `<form>` element */
     className?: string;
-    /** JSON configuration to define the fields and functionalities of the form */
+    /** JSON configuration to define the components and functionalities of the form */
     data?: IFrontendEngineData<V> | undefined;
     /** Fires every time a value changes in any fields */
     onChange?: ((values: TFrontendEngineValues, isValid?: boolean | undefined) => unknown) | undefined;
@@ -19,8 +21,14 @@ export interface IFrontendEngineData<V = undefined> {
     className?: string | undefined;
     /** Fields' initial values on mount. The key of each field needs to match the id used in the field */
     defaultValues?: TFrontendEngineValues | undefined;
-    /** All elements within the form in key-value format, key refers to the id of the field while value refers to the JSON schema of the field */
-    fields: Record<string, TFrontendEngineFieldSchema<V>>;
+    /**
+     * Specifies the components to be rendered
+     *
+     * All components within the form are in key-value format, key refers to the id of the components while value refers to its JSON schema
+     *
+     * Note: sections accept only section `uiType`, the subsequent children accepts uiType other than section
+     * */
+    sections: Record<string, ISectionSchema<V>>;
     /** Unique HTML id attribute that is applied on the `<form>` element */
     id?: string | undefined;
     /** Validation strategy when inputs with errors get re-validated after a user submits the form (onSubmit event) */
@@ -28,7 +36,7 @@ export interface IFrontendEngineData<V = undefined> {
     /** Validation strategy before a user submits the form (onSubmit event) */
     validationMode?: TValidationMode | undefined;
 }
-export type TFrontendEngineFieldSchema<V = undefined> = ITextareaSchema<V> | ITextfieldSchema<V> | IEmailSchema<V> | INumberSchema<V> | ISubmitButtonSchema | ISelectSchema<V> | IMultiSelectSchema<V> | ICheckboxGroupSchema<V> | IDateInputSchema<V> | IWrapperSchema | IContactNumberSchema<V> | IRadioButtonGroupSchema<V> | ITimePickerSchema<V> | IChipsSchema<V> | IAlertSchema | ITextSchema;
+export type TFrontendEngineFieldSchema<V = undefined> = ITextareaSchema<V> | ITextFieldSchema<V> | IEmailFieldSchema<V> | INumericFieldSchema<V> | ISubmitButtonSchema | ISelectSchema<V> | IMultiSelectSchema<V> | ICheckboxGroupSchema<V> | IDateFieldSchema<V> | IWrapperSchema | IContactFieldSchema<V> | IRadioButtonGroupSchema<V> | ITimeFieldSchema<V> | IChipsSchema<V> | IUnitNumberFieldSchema<V> | IAlertSchema | ITextSchema | IResetButtonSchema | IFilterSchema | ICustomComponentJsonSchema<V>;
 export type TFrontendEngineValues<T = any> = Record<keyof T, T[keyof T]>;
 export type TRevalidationMode = Exclude<keyof ValidationMode, "onTouched" | "all">;
 export type TValidationMode = keyof ValidationMode;
@@ -37,19 +45,22 @@ export type TErrorPayload = Record<string, TErrorMessage>;
 export interface IFrontendEngineRef extends HTMLFormElement {
     /** gets form values */
     getValues: () => TFrontendEngineValues;
-    /** set field value by id */
+    /** sets field value by id */
     setValue: UseFormSetValue<TFrontendEngineValues>;
-    /** check if form is valid */
+    /** checks if form is valid */
     isValid: () => boolean;
     /** triggers form submission */
     submit: () => void;
+    /** adds custom validation rule */
     addCustomValidation: (type: TYupSchemaType | "mixed", name: string, fn: (value: unknown, arg: unknown) => boolean) => void;
-    /** allow setting of custom errors thrown by endpoints */
+    /** allows setting of custom errors thrown by endpoints */
     setErrors: (errors: TErrorPayload) => void;
+    /** resets the form to the default state */
+    reset: UseFormReset<TFrontendEngineValues>;
 }
 export interface IFrontendEngineBaseFieldJsonSchema<T, V = undefined, U = undefined> {
-    /** defines what kind of field to be rendered */
-    fieldType: T;
+    /** defines what kind of component to be rendered */
+    uiType: T;
     /** caption for the field */
     label: string;
     /** render conditions
@@ -58,32 +69,62 @@ export interface IFrontendEngineBaseFieldJsonSchema<T, V = undefined, U = undefi
     showIf?: TRenderRules[] | undefined;
     /** validation config, can be customised by passing generics */
     validation?: (V | U | IYupValidationRule)[];
+    /** escape hatch for other form / frontend engines to have unsupported attributes */
+    customOptions?: Record<string, unknown> | undefined;
+}
+/**
+ * to support custom components from other form / frontend engines
+ */
+export interface ICustomComponentJsonSchema<T> {
+    referenceKey: T;
+    uiType?: never | undefined;
+}
+export interface ICustomFieldJsonSchema<T, V = undefined, U = undefined> extends ICustomComponentJsonSchema<T> {
+    validation?: (V | U | IYupValidationRule)[];
+    /** render conditions
+     * - need to fulfil at least 1 object in array (OR condition)
+     * - in order for an object to be valid, need to fulfil all conditions in that object (AND condition) */
+    showIf?: TRenderRules[] | undefined;
 }
 /**
  * JSON keys to omit from field schema when extending from other interfaces
  * - keys already defined in `IFrontendEngineBaseFieldJsonSchema` to prevent collision
  * - some inherited HTML attributes
  */
-export type TFrontendEngineFieldJsonSchemaOmitKeys = "id" | "label" | "validation" | "fieldType" | "showIf" | "children" | "value";
+export type TFrontendEngineFieldJsonSchemaOmitKeys = "id" | "label" | "validation" | "uiType" | "showIf" | "children" | "value";
 export interface IFrontendEngineElementJsonSchema<T> extends Omit<IFrontendEngineBaseFieldJsonSchema<T>, "label" | "validation"> {
 }
 type UnionOptionalKeys<T = undefined> = T extends string | number | symbol ? TFrontendEngineFieldJsonSchemaOmitKeys | T : TFrontendEngineFieldJsonSchemaOmitKeys;
+/**
+ * Omits clashing keys between native props and frontend engine
+ */
 export type TComponentOmitProps<T, V = undefined> = Omit<T, UnionOptionalKeys<V>>;
+/**
+ * Field types
+ * - components that can contain values that can get submitted
+ */
 export declare enum EFieldType {
     TEXTAREA = "Textarea",
-    TEXT = "TextField",
-    NUMERIC = "TextField",
-    EMAIL = "TextField",
+    "TEXT-FIELD" = "TextField",
+    "NUMERIC-FIELD" = "TextField",
+    "EMAIL-FIELD" = "TextField",
     SUBMIT = "SubmitButton",
     SELECT = "Select",
     "MULTI-SELECT" = "MultiSelect",
-    DATE = "DateInput",
+    "DATE-FIELD" = "DateField",
     CHECKBOX = "CheckboxGroup",
-    CONTACT = "ContactNumber",
+    "CONTACT-FIELD" = "ContactField",
     RADIO = "RadioButtonGroup",
-    TIME = "TimePicker",
-    CHIPS = "Chips"
+    "TIME-FIELD" = "TimeField",
+    CHIPS = "Chips",
+    RESET = "ResetButton",
+    "UNIT-NUMBER-FIELD" = "UnitNumberField"
 }
+/**
+ * Non-field types
+ * - components that do not have values
+ * - typically used for layouts and messages
+ */
 export declare enum EElementType {
     ALERT = "Alert",
     "TEXT-D1" = "Text",
@@ -100,7 +141,6 @@ export declare enum EElementType {
     "TEXT-XSMALL" = "Text",
     DIV = "Wrapper",
     SPAN = "Wrapper",
-    SECTION = "Wrapper",
     HEADER = "Wrapper",
     FOOTER = "Wrapper",
     H1 = "Wrapper",
@@ -111,7 +151,23 @@ export declare enum EElementType {
     H6 = "Wrapper",
     P = "Wrapper"
 }
+/**
+ * Custom element types
+ * - components that do not have uiType and have specific schema to render
+ */
+export declare enum ECustomElementType {
+    FILTER = "Filter",
+    "FILTER-ITEM" = "FilterItem"
+}
+export declare enum ECustomFieldType {
+    "FILTER-CHECKBOX" = "FilterCheckbox"
+}
 export interface IGenericFieldProps<T = TFrontendEngineFieldSchema> extends Partial<ControllerFieldState>, Partial<ControllerRenderProps> {
     id: string;
     schema: T;
 }
+/**
+ * prevents inferrence
+ * https://stackoverflow.com/questions/56687668/a-way-to-disable-type-argument-inference-in-generics
+ */
+export type TNoInfer<T, U> = [T][T extends U ? 0 : never];

package/components/frontend-engine/yup/context-provider.d.ts

@@ -8,5 +8,5 @@ interface IProps {
     children: ReactElement;
 }
 export declare const YupContext: React.Context<IYupContext>;
-export declare const YupProvider: ({ children }: IProps) => JSX.Element;
+export declare const YupProvider: ({ children }: IProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/components/shared/chip/chip.d.ts

@@ -2,5 +2,5 @@ import React from "react";
 import { IChipButtonProps } from "./types";
 interface IProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, IChipButtonProps {
 }
-export declare const Chip: ({ children, ...otherProps }: IProps) => JSX.Element;
+export declare const Chip: ({ children, ...otherProps }: IProps) => import("react/jsx-runtime").JSX.Element;
 export {};

package/components/shared/error-messages.d.ts

@@ -18,6 +18,9 @@ export declare const ERROR_MESSAGES: {
         MAX_DATE: (date: string) => string;
         INVALID: string;
     };
+    UNIT_NUMBER: {
+        INVALID: string;
+    };
     GENERIC: {
         INVALID: string;
         UNSUPPORTED: string;

package/components/shared/sanitize/sanitize.d.ts

@@ -3,5 +3,5 @@ interface IProps {
     id?: string;
     children: string | React.ReactNode;
 }
-export declare const Sanitize: (props: IProps) => JSX.Element;
+export declare const Sanitize: (props: IProps) => import("react/jsx-runtime").JSX.Element;
 export {};