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

package/components/elements/section/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./section";
+export * from "./types";

package/components/elements/section/section.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="react" />
+import { ISectionProps } from "./types";
+export declare const Section: (props: ISectionProps) => JSX.Element;

package/components/elements/section/types.d.ts

@@ -0,0 +1,10 @@
+import { IFrontendEngineElementJsonSchema, TComponentOmitProps, TFrontendEngineFieldSchema } from "../../frontend-engine";
+import { IWrapperSchema } from "../wrapper";
+export interface ISectionSchema<V = undefined> extends IFrontendEngineElementJsonSchema<"section">, TComponentOmitProps<IWrapperSchema> {
+    children: Record<string, TFrontendEngineFieldSchema<V>>;
+}
+export interface ISectionProps {
+    id: string;
+    sectionSchema: ISectionSchema;
+    warnings?: Record<string, string> | undefined;
+}

package/components/elements/sections/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./sections";
+export * from "./types";

package/components/elements/sections/sections.d.ts

@@ -0,0 +1,15 @@
+/// <reference types="react" />
+import { ISectionsProps } from "./types";
+/**
+ * this component is meant to render "pages" which consists of individual Section component
+ * it is not rendering in pages yet because there are no use cases yet
+ * so this is just a placeholder for now
+ *
+ * this component renders the sections object and cannot be defined via `uiType`
+ * i.e. it is used internally only
+ *
+ * TODO:
+ * - render pages properly
+ * - handle validation and errors in each section before navigating away
+ */
+export declare const Sections: (props: ISectionsProps) => JSX.Element;

package/components/elements/sections/types.d.ts

@@ -0,0 +1,5 @@
+import { ISectionSchema } from "../section";
+export interface ISectionsProps {
+    schema?: Record<string, ISectionSchema> | undefined;
+    warnings?: Record<string, string> | undefined;
+}

package/components/elements/wrapper/conditional-renderer.d.ts

@@ -1,14 +1,16 @@
 import React from "react";
+import { TFrontendEngineFieldSchema } from "../../frontend-engine";
 import { TRenderRules } from "../../frontend-engine/yup";
 interface IProps {
     id: string;
     renderRules?: TRenderRules[] | undefined;
     children: React.ReactNode;
+    schema: TFrontendEngineFieldSchema;
 }
 /**
  * conditionally render children according to render rules provided
  * render conditions are based on Yup schema and the base schema is derived from corresponding validation config
  * automatically remove validation config on hide / unmount, for more complex fields, it still has to be done via the field itself
  */
-export declare const ConditionalRenderer: ({ id, renderRules, children }: IProps) => JSX.Element;
+export declare const ConditionalRenderer: ({ id, renderRules, children, schema }: IProps) => JSX.Element;
 export {};

package/components/elements/wrapper/types.d.ts

@@ -1,9 +1,16 @@
 /// <reference types="react" />
 import { TComponentOmitProps, TFrontendEngineFieldSchema } from "../../frontend-engine";
 import { TRenderRules } from "../../frontend-engine/yup";
-export type TWrapperType = "div" | "span" | "section" | "header" | "footer" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p";
+export type TWrapperType = "div" | "span" | "header" | "footer" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p";
 export interface IWrapperSchema extends TComponentOmitProps<React.HTMLAttributes<HTMLElement>, "children"> {
-    fieldType: TWrapperType;
+    uiType: TWrapperType;
     showIf?: TRenderRules[] | undefined;
     children: Record<string, TFrontendEngineFieldSchema> | string;
 }
+export interface IWrapperProps {
+    id?: string | undefined;
+    schema?: IWrapperSchema | undefined;
+    /** only used internally by FrontendEngine */
+    children?: Record<string, TFrontendEngineFieldSchema> | undefined;
+    warnings?: Record<string, string> | undefined;
+}

package/components/elements/wrapper/wrapper.d.ts

@@ -1,12 +1,3 @@
 /// <reference types="react" />
-import { TFrontendEngineFieldSchema } from "../../frontend-engine/types";
-import { IWrapperSchema } from "./types";
-interface IWrapperProps {
-    id?: string | undefined;
-    schema?: IWrapperSchema | undefined;
-    /** only used internally by FrontendEngine */
-    children?: Record<string, TFrontendEngineFieldSchema> | undefined;
-    warnings?: Record<string, string> | undefined;
-}
-export declare const Wrapper: (props: IWrapperProps) => JSX.Element;
-export {};
+import { IWrapperProps } from "./types";
+export declare const Wrapper: (props: IWrapperProps) => JSX.Element | null;

package/components/fields/contact-field/contact-field.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="react" />
+import { IGenericFieldProps } from "../../frontend-engine/types";
+import { IContactFieldSchema } from "./types";
+export declare const ContactField: (props: IGenericFieldProps<IContactFieldSchema>) => JSX.Element;

package/components/fields/contact-field/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./contact-field";
+export * from "./types";

package/components/fields/{contact-number → contact-field}/types.d.ts

@@ -2,12 +2,12 @@ import { FormInputProps } from "@lifesg/react-design-system/form/types";
 import { IFrontendEngineBaseFieldJsonSchema, TComponentOmitProps } from "../../frontend-engine/types";
 import { InternationalCallingCodeMap } from "./data";
 export type TCountry = keyof typeof InternationalCallingCodeMap;
-interface IContactNumberProps extends FormInputProps {
+interface IContactFieldProps extends FormInputProps {
     country?: TCountry;
     enableSearch?: boolean | undefined;
 }
 export type TSingaporeNumberRule = "default" | "house" | "mobile";
-export interface IContactNumberValidationRule {
+export interface IContactFieldValidationRule {
     contactNumber?: {
         internationalNumber: true;
         singaporeNumber?: never;
@@ -24,6 +24,6 @@ export interface IParsedPhoneNumber {
     prefix: string;
     number: string;
 }
-export interface IContactNumberSchema<V = undefined> extends IFrontendEngineBaseFieldJsonSchema<"contact", V, IContactNumberValidationRule>, TComponentOmitProps<IContactNumberProps> {
+export interface IContactFieldSchema<V = undefined> extends IFrontendEngineBaseFieldJsonSchema<"contact-field", V, IContactFieldValidationRule>, TComponentOmitProps<IContactFieldProps> {
 }
 export {};

package/components/fields/date-field/date-field.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="react" />
+import { IGenericFieldProps } from "../../frontend-engine/types";
+import { IDateFieldSchema } from "./types";
+export declare const DateField: (props: IGenericFieldProps<IDateFieldSchema>) => JSX.Element;

package/components/fields/date-field/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./date-field";
+export * from "./types";

package/components/fields/{date-input → date-field}/types.d.ts

@@ -1,6 +1,6 @@
 import { DateInputProps } from "@lifesg/react-design-system/date-input";
 import { IFrontendEngineBaseFieldJsonSchema, TComponentOmitProps } from "../../frontend-engine/types";
-export interface IDateInputValidationRule {
+export interface IDateFieldValidationRule {
     future?: boolean | undefined;
     past?: boolean | undefined;
     notFuture?: boolean | undefined;
@@ -8,7 +8,7 @@ export interface IDateInputValidationRule {
     minDate?: string | undefined;
     maxDate?: string | undefined;
 }
-export interface IDateInputSchema<V = undefined> extends IFrontendEngineBaseFieldJsonSchema<"date", V, IDateInputValidationRule>, TComponentOmitProps<DateInputProps> {
+export interface IDateFieldSchema<V = undefined> extends IFrontendEngineBaseFieldJsonSchema<"date-field", V, IDateFieldValidationRule>, TComponentOmitProps<DateInputProps> {
     useCurrentDate?: boolean | undefined;
     dateFormat?: string | undefined;
 }

package/components/fields/index.d.ts

@@ -1,11 +1,11 @@
 export * from "./checkbox-group";
 export * from "./chips";
-export * from "./contact-number";
-export * from "./date-input";
+export * from "./contact-field";
+export * from "./date-field";
 export * from "./multi-select";
 export * from "./radio-button";
 export * from "./select";
 export * from "./submit-button";
+export * from "./text-field";
 export * from "./textarea";
-export * from "./textfield";
-export * from "./time-picker";
+export * from "./time-field";

package/components/fields/text-field/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./text-field";
+export * from "./types";

package/components/fields/text-field/text-field.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="react" />
+import { IGenericFieldProps } from "../../frontend-engine";
+import { IEmailFieldSchema, INumericFieldSchema, ITextFieldSchema } from "./types";
+export declare const TextField: (props: IGenericFieldProps<ITextFieldSchema | IEmailFieldSchema | INumericFieldSchema>) => JSX.Element;

package/components/fields/text-field/types.d.ts

@@ -0,0 +1,8 @@
+import { FormInputProps } from "@lifesg/react-design-system/form/types";
+import { IFrontendEngineBaseFieldJsonSchema, TComponentOmitProps } from "../../frontend-engine";
+export interface ITextFieldSchema<V = undefined> extends IFrontendEngineBaseFieldJsonSchema<"text-field", V>, TComponentOmitProps<FormInputProps, "type" | "maxLength"> {
+}
+export interface IEmailFieldSchema<V = undefined> extends IFrontendEngineBaseFieldJsonSchema<"email-field", V>, TComponentOmitProps<FormInputProps, "type" | "maxLength"> {
+}
+export interface INumericFieldSchema<V = undefined> extends IFrontendEngineBaseFieldJsonSchema<"numeric-field", V>, TComponentOmitProps<FormInputProps, "type" | "max" | "min"> {
+}

package/components/fields/time-field/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./time-field";
+export * from "./types";

package/components/fields/time-field/time-field.d.ts

@@ -0,0 +1,4 @@
+/// <reference types="react" />
+import { IGenericFieldProps } from "../../frontend-engine";
+import { ITimeFieldSchema } from "./types";
+export declare const TimeField: (props: IGenericFieldProps<ITimeFieldSchema>) => JSX.Element;

package/components/fields/{time-picker → time-field}/types.d.ts

@@ -1,6 +1,6 @@
 import { TimepickerProps } from "@lifesg/react-design-system/timepicker";
 import { IFrontendEngineBaseFieldJsonSchema, TComponentOmitProps } from "../../frontend-engine";
-export interface ITimePickerSchema<V = undefined> extends IFrontendEngineBaseFieldJsonSchema<"time", V>, TComponentOmitProps<TimepickerProps> {
+export interface ITimeFieldSchema<V = undefined> extends IFrontendEngineBaseFieldJsonSchema<"time-field", V>, TComponentOmitProps<TimepickerProps> {
     useCurrentTime?: boolean | undefined;
     is24HourFormat?: boolean | undefined;
 }

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

@@ -1,20 +1,14 @@
 import { ReactElement, Ref } from "react";
-import { IFrontendEngineProps, IFrontendEngineRef } from "./types";
+import { IFrontendEngineProps, IFrontendEngineRef, TNoInfer } from "./types";
 import { IYupValidationRule } from "./yup";
-/**
- * prevents inferrence
- * https://stackoverflow.com/questions/56687668/a-way-to-disable-type-argument-inference-in-generics
- */
-type NoInfer<T, U> = [T][T extends U ? 0 : never];
 /**
  * The one and only component needed to create your form
  *
  * Minimally you will need to set the `data` props which is the JSON schema to define the form
  */
-export declare const FrontendEngine: <V = undefined>(props: IFrontendEngineProps<NoInfer<V, IYupValidationRule>> & {
+export declare const FrontendEngine: <V = undefined>(props: IFrontendEngineProps<TNoInfer<V, IYupValidationRule>> & {
     ref?: Ref<IFrontendEngineRef>;
 }) => ReactElement;
-export {};
 /**
  * casting as a function with generics as a way to define generics with forwardRef
  * the generics are a way to set custom definition of Yup validation config

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

@@ -1,13 +1,14 @@
 import { ControllerFieldState, ControllerRenderProps, UseFormSetValue, ValidationMode } from "react-hook-form";
 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, ISelectSchema, ISubmitButtonSchema, ITextFieldSchema, ITextareaSchema, ITimeFieldSchema } 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 +20,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 +35,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> | IAlertSchema | ITextSchema | ICustomComponentJsonSchema;
 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 +44,20 @@ 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;
 }
 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 +66,54 @@ 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 {
+    referenceKey: string;
+    [otherOptions: string]: unknown;
+    uiType?: never | 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",
+    "TIME-FIELD" = "TimeField",
     CHIPS = "Chips"
 }
+/**
+ * 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 +130,6 @@ export declare enum EElementType {
     "TEXT-XSMALL" = "Text",
     DIV = "Wrapper",
     SPAN = "Wrapper",
-    SECTION = "Wrapper",
     HEADER = "Wrapper",
     FOOTER = "Wrapper",
     H1 = "Wrapper",
@@ -115,3 +144,8 @@ export interface IGenericFieldProps<T = TFrontendEngineFieldSchema> extends Part
     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];