jopijs 0.0.1

package/src/@uikit/core/jBundler_ifBrowser.ts

@@ -0,0 +1,4 @@
+export function registerUiKit() {
+    // Do nothing. Is here because "jopi-toolkit-server"
+    // will be replaced by "jopi-toolkit-browser" (by the bundler engine).
+}

package/src/@uikit/core/jBundler_ifServer.ts

@@ -0,0 +1,18 @@
+import * as jk_event from "jopi-toolkit/jk_events";
+import type {WebSite, WebSiteImpl} from "jopijs";
+import {UiKitModule} from "./UiKitModule.ts";
+
+/**
+ * Must be called manually from the server-side init to enable UiKit.
+ * This will allow replacing the instance of ModuleInitContext
+ * by an instance of UiKitModule.
+ */
+export function registerUiKit() {
+    // We want to replace the creation of the object ModuleInitContext
+    // with our own implementation, which extend the core functionalities.
+    //
+    jk_event.addListener<WebSite>("jopi.server.install.done", (webSite) => {
+        // @ts-ignore It doesn't correctly cast references.
+        (webSite as WebSiteImpl).setModuleInitClassInstancier(host => new UiKitModule(host));
+    });
+}

package/src/@uikit/forms/components.tsx

@@ -0,0 +1,97 @@
+// noinspection JSUnusedGlobalSymbols
+
+import React, {useRef} from "react";
+import {useVariant, VariantContext} from "../variants/index.tsx";
+import {
+    type JAutoFormFieldProps,
+    type JCheckboxFormFieldProps, type JFormMessageProps,
+    type JInputFormFieldProps, type JFieldProps,
+    type JFormComponentProps,
+    type JFormController, type JNumberFormFieldProps, type JFileSelectFieldProps
+} from "./interfaces.ts";
+import {FormContext, JFormControllerImpl} from "./private.ts";
+import {useJForm, useJFormField, UseJFormMessage} from "./hooks.ts";
+
+export function JForm({children, className, variants, ...p}: JFormComponentProps & {
+    children: React.ReactNode, className?: string, variants?: any
+})
+{
+    const formRef = useRef<HTMLFormElement>(null);
+    const ref = useRef<JFormControllerImpl>(new JFormControllerImpl(p, formRef));
+
+    const onSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+        e.preventDefault();
+        await ref.current.submit();
+    };
+
+    return <FormContext.Provider value={ref.current}>
+        <VariantContext.Provider value={variants}>
+            <form ref={formRef} className={className} onSubmit={onSubmit}>{children}</form>
+        </VariantContext.Provider>
+    </FormContext.Provider>
+}
+
+export function JFormStateListener({custom, ifSubmitted, ifNotSubmitted}: {
+    ifSubmitted?: React.ReactNode,
+    ifNotSubmitted?: React.ReactNode,
+    custom?: (form: JFormController) => React.ReactNode
+}) {
+    const form = useJForm();
+
+    if (form.submitted || form.submitting) {
+        if (ifSubmitted) return ifSubmitted;
+    } else {
+        if (ifNotSubmitted) return ifNotSubmitted;
+    }
+
+    return custom?.(form);
+}
+
+function renderField(variantName: string|undefined, p: JFieldProps) {
+    const field = useJFormField(p.name);
+    if (!field) return <div style={{color: "red"}}><strong>Form error: the field '{p.name}' doesn't exist.</strong></div>;
+
+    p = {...p};
+    if (p.title===undefined) p.title = field.title;
+    if (p.description===undefined) p.description = field.description;
+    if (p.placeholder===undefined) p.placeholder = field.placeholder;
+
+    if (!variantName) {
+        variantName = field.variantName;
+    }
+
+    const V = useVariant(variantName, p.variant);
+    return <V {...p} field={field} />;
+}
+
+export function JAutoFormField({variant, ...p}: JAutoFormFieldProps) {
+    return renderField(undefined, p);
+}
+
+//region Form Types
+
+export function JFormMessage(p: JFormMessageProps) {
+    const message = UseJFormMessage();
+    if (!message) return null;
+
+    const V = useVariant("FormMessage", p.variant);
+    return <V {...p} message={message} />;
+}
+
+export function JTextFormField({variant, ...p}: JInputFormFieldProps) {
+    return renderField("TextFormField", p);
+}
+
+export function JNumberFormField({variant, ...p}: JNumberFormFieldProps) {
+    return renderField("NumberFormField", p);
+}
+
+export function JCheckboxFormField({variant, ...p}: JCheckboxFormFieldProps) {
+    return renderField("CheckboxFormField", p);
+}
+
+export function JFileSelectField({variant, ...p}: JFileSelectFieldProps) {
+    return renderField("FileSelectField", p);
+}
+
+//endregion

package/src/@uikit/forms/hooks.ts

@@ -0,0 +1,38 @@
+import React, {useContext, useEffect} from "react";
+import type {JMessage, JFieldController, JFormController} from "./interfaces.ts";
+import {FormContext, JFormControllerImpl} from "./private.ts";
+
+export function useJForm(): JFormController {
+    const theForm = useContext(FormContext) as JFormControllerImpl;
+    if (!theForm) throw new Error("useJForm must be used within a JForm component.");
+
+    const [_, setCounter] = React.useState(0);
+
+    useEffect(() => {
+        function eventHandler() {
+            // Here use prevCount to always have the update counter value.
+            setCounter(prevCount => prevCount+1);
+        }
+
+        theForm.addStateChangeListener(eventHandler);
+        return () => { theForm.removeStateChangeListener(eventHandler) };
+    }, []);
+
+    return theForm;
+}
+
+export function UseJFormMessage(): JMessage|undefined {
+    let form = useJForm();
+    return form.formMessage
+}
+
+export function useJFormField(name: string): JFieldController {
+    const [_, setCounter] = React.useState(0);
+    const form = useJForm() as JFormControllerImpl;
+
+    let thisField = form.getField(name);
+    if (!thisField) return undefined as unknown as JFieldController;
+
+    thisField.onStateChange = () => { setCounter(prev => prev + 1) };
+    return thisField;
+}

package/src/@uikit/forms/index.ts

@@ -0,0 +1,3 @@
+export * from "./interfaces.ts";
+export * from "./components.tsx";
+export * from "./hooks.ts";

package/src/@uikit/forms/interfaces.ts

@@ -0,0 +1,159 @@
+import type {UiText} from "../helpers/tools";
+import {type Schema, type ValidationErrors} from "jopi-toolkit/jk_schema";
+import React from "react";
+
+//region Core
+
+export type SubmitFunction = (params: { data: any, form: JFormController, hasFiles: boolean })
+                              => Promise<JMessage|undefined|void> | JMessage | undefined | void;
+
+export interface JFormComponentProps {
+    schema: Schema;
+    action?: string;
+    submit?: SubmitFunction
+}
+
+export interface JFieldController {
+    form: JFormController;
+    variantName: string;
+
+    name: string;
+    type: string;
+
+    error: boolean;
+    errorMessage?: string;
+
+    title?: string;
+    description?: string;
+    placeholder?: string;
+
+    value: any;
+    oldValue: any;
+    onChange: (value: any) => void;
+    valueConverter: (value: any, isTyping: boolean) => any;
+
+    //region Type String
+
+    minLength?: number;
+    errorMessage_minLength?: string;
+
+    maxLength?: number;
+    errorMessage_maxLength?: string;
+
+    //endregion
+
+    //region Type Number
+
+    minValue?: number;
+    errorMessage_minValue?: string;
+
+    maxValue?: number;
+    errorMessage_maxValue?: string;
+
+    allowDecimal?: boolean;
+    roundMethod?: "round" | "floor" | "ceil";
+    errorMessage_dontAllowDecimal?: string;
+
+    incrStep?: number;
+
+    //endregion
+
+    //region Type File
+
+    maxFileCount?: number;
+    errorMessage_maxFileCount?: string;
+
+    acceptFileType?: string;
+    errorMessage_invalidFileType?: string;
+
+    maxFileSize?: number;
+    errorMessage_maxFileSize?: string;
+
+    //endregion
+
+    //region Type Boolean
+
+    requireTrue?: boolean;
+    errorMessage_requireTrue?: string;
+
+    requireFalse?: boolean;
+    errorMessage_requireFalse?: string;
+
+    //endregion
+}
+
+export interface JFormController {
+    error: boolean;
+    submitting: boolean;
+    submitted: boolean;
+    formMessage?: JMessage;
+
+    getData<T = any>(): T;
+    getFormData(): FormData;
+    getSubmitUrl(): string;
+
+    sendFormData(url?: string): Promise<JMessage>;
+    sendJsonData(url?: string): Promise<JMessage>;
+}
+
+export interface JMessage {
+    isOk: boolean;
+    isSubmitted: boolean;
+
+    message?: string;
+    code?: string;
+
+    fieldErrors?: ValidationErrors;
+}
+
+//endregion
+
+//region By type
+
+export interface JFieldProps {
+    name: string;
+    title?: UiText;
+    description?: UiText;
+    placeholder?: string;
+
+    variant?: React.FC<unknown>;
+
+    id?: string;
+    className?: string;
+}
+
+export interface JFormMessageProps {
+    id?: string;
+    className?: string;
+    variant?: React.FC<unknown>;
+    isBefore?: boolean;
+    message?: JMessage;
+
+    errorMessage?: UiText;
+
+    // false: allows hiding the submitted message.
+    submittedMessage?: UiText|false;
+
+    // false: allows hiding the message if field errors.
+    fieldErrorMessage?: UiText|false;
+}
+
+export interface JInputFormFieldProps extends JFieldProps {
+}
+
+export interface JCheckboxFormFieldProps extends JFieldProps {
+    defaultChecked?: boolean;
+}
+export interface JFileSelectFieldProps extends JFieldProps {
+}
+
+export interface JNumberFormFieldProps extends JFieldProps {
+    minValue?: number;
+    maxValue?: number;
+    incrStep?: number;
+}
+
+export interface JAutoFormFieldProps extends JInputFormFieldProps, JCheckboxFormFieldProps, JNumberFormFieldProps {
+}
+
+//endregion

package/src/@uikit/forms/private.ts

@@ -0,0 +1,365 @@
+import React from "react";
+import * as jk_schema from "jopi-toolkit/jk_schema";
+import type {
+    JMessage,
+    JFieldController,
+    JFormComponentProps,
+    JFormController,
+    SubmitFunction
+} from "./interfaces.ts";
+import type {ValidationErrors} from "jopi-toolkit/jk_schema";
+import {sendFormData, sendJsonData} from "../helpers/tools.ts";
+
+type Listener = () => void;
+
+export const FormContext = React.createContext<JFormController>(undefined as unknown as JFormController);
+
+interface JFieldController_Private extends JFieldController {
+    onStateChange?: () => void;
+}
+
+export class JFormControllerImpl implements JFormController {
+    private readonly fields: Record<string, JFieldController_Private> = {};
+    private readonly jsonSchema: jk_schema.SchemaDescriptor;
+    private readonly onStateChange: Listener[] = [];
+    private readonly submitHandler?: SubmitFunction;
+    private autoRevalidate = false;
+    private hasFiles = false;
+
+    error = false;
+    submitting = false;
+    submitted = false;
+    formMessage?: JMessage;
+    
+    constructor(private props: JFormComponentProps, private readonly formRef: React.RefObject<HTMLFormElement|null>) {
+        this.jsonSchema = jk_schema.toJson(this.props.schema).desc;
+        this.submitHandler = props.submit;
+    }
+
+    getData<T = any>(): T {
+        let data: any = {};
+
+        for (let name in this.fields) {
+            let field = this.fields[name];
+            data[name] = field.valueConverter(field.value, false);
+        }
+
+        return data as T;
+    }
+    
+    getFormData(): FormData {
+        let form = this.formRef.current!;
+        let formData = new FormData(form);
+
+        let data = this.getData();
+
+        // Values can have been updated by a normalization step.
+        // It's why we inject back the values.
+        //
+        for (let name in this.fields) {
+            let field = this.fields[name];
+            let value = data[name];
+
+            // Special case for files.
+            //
+            if (field.type === "file") {
+                if (field.value instanceof File) {
+                    formData.set(name, field.value);
+                } else if (field.value instanceof Array) {
+                    // Remove the current value.
+                    formData.delete(name);
+
+                    // Add each one file of the array.
+                    for (let i = 0; i < field.value.length; i++) {
+                        formData.append(name, field.value[i]);
+                    }
+                }
+            } else {
+                if (value !== undefined && value !== null) {
+                    formData.set(name, String(value));
+                }
+            }
+        }
+
+        return formData;
+    }
+
+    getSubmitUrl(): string {
+        return this.props.action || window.location.href
+    }
+
+    async sendJsonData(url?: string): Promise<JMessage> {
+        if (!url) url = this.getSubmitUrl();
+        return this.processSendToServerResponse(await sendJsonData(url, this.getData()));
+    }
+
+    async sendFormData(url?: string): Promise<JMessage> {
+        if (!url) url = this.getSubmitUrl();
+        return this.processSendToServerResponse(await sendFormData(url, this.getFormData()));
+    }
+
+    private processSendToServerResponse(response: Response): JMessage {
+        if (response.status === 200) {
+            return {isOk: true, isSubmitted: true};
+        }
+
+        return {
+            isOk: false,
+            isSubmitted: false,
+            message: response.status===500
+                ? "An error occurred with the server. Please try again later."
+                : "Invalid form content.",
+
+            code: response.status === 500
+                ? "SERVER_ERROR_500"
+                : "SERVER_INVALID_DATA"
+        };
+    }
+
+    private setFormMessage(message: JMessage): JMessage {
+        this.formMessage = message;
+
+        if (!message.message && message.fieldErrors && message.fieldErrors.globalError) {
+            message.message = message.fieldErrors.globalError;
+            message.code = "GLOBAL_ERROR";
+        }
+
+        if (message.isSubmitted) {
+            this.declareState_Submitted();
+        } else {
+            if (message.isOk) {
+                this.declareState_Reset();
+            }
+            else {
+                this.submitted = false;
+                this.submitting = false;
+                this.declareState_Error()
+            }
+        }
+
+        return message;
+    }
+
+    async submit(): Promise<JMessage|undefined> {
+        this.autoRevalidate = true;
+        let data = this.getData();
+        let fieldErrors = this.validateAux(data);
+
+        if (fieldErrors) {
+            return this.setFormMessage({isOk: false, isSubmitted: false, fieldErrors});
+        }
+
+        this.autoRevalidate = false;
+
+        let submitHandler = this.submitHandler;
+        if (!submitHandler) submitHandler = () => this.sendFormData()
+
+        this.declareState_Submitting();
+
+        try {
+            let r = submitHandler({data, form: this, hasFiles: this.hasFiles});
+
+            if (r instanceof Promise) r = await r;
+            if (r) return this.setFormMessage(r);
+        } catch (e) {
+            console.error("Error when submitting form:", e);
+
+            return this.setFormMessage({
+                isOk: false,
+                isSubmitted: false,
+                message: "An error occurred when submitting form",
+                code: "UNKNOWN_SUBMIT_ERROR"
+            });
+        }
+
+        return this.setFormMessage({isOk: true, isSubmitted: true});
+    }
+
+    validate(): ValidationErrors | undefined {
+        let errors = this.validateAux(this.getData());
+
+        if (errors) {
+            this.setFormMessage({isOk: false, isSubmitted: false, fieldErrors: errors});
+        } else {
+            this.declareState_Reset();
+        }
+
+        return errors;
+    }
+
+    private validateAux(data: any): ValidationErrors | undefined {
+        for (let field of Object.values(this.fields)) {
+            field.error = false;
+            field.errorMessage = undefined;
+        }
+
+        const errors = jk_schema.validateSchema(data, this.props.schema);
+
+        if (errors) {
+            if (errors.fields) {
+                for (let fieldError of Object.values(errors.fields)) {
+                    let fieldRef = this.getField(fieldError.fieldName);
+
+                    if (fieldRef) {
+                        fieldRef.error = true;
+                        fieldRef.errorMessage = fieldError.message;
+                    }
+                }
+            }
+        }
+
+        for (let field of Object.values(this.fields)) {
+            field.onStateChange?.();
+        }
+
+        return errors;
+    }
+
+    getField(name: string): JFieldController_Private|undefined {
+        let field: JFieldController_Private = this.fields[name];
+        if (field) return field;
+
+        const fieldDef = this.jsonSchema[name];
+        if (!fieldDef) return undefined;
+
+        const form = this;
+        const valueConverter = selectValueConverter(fieldDef.type);
+        
+        if (fieldDef.type==="file") {
+            this.hasFiles = true;
+        }
+
+        this.fields[name] = field = {
+            form: this,
+            variantName: getVariantName(fieldDef.type),
+
+            name: name,
+            error: false,
+
+            valueConverter,
+            value: fieldDef && fieldDef.default ? fieldDef.default : calcDefault(fieldDef),
+
+            oldValue: undefined,
+
+            onChange: (value: any) => {
+                if (value!==undefined) value = valueConverter(value, true);
+                if (value===field.value) return;
+
+                field.oldValue = field.value;
+                field.value = value;
+
+                if (form.autoRevalidate) form.validate();
+                else if (field.onStateChange) field.onStateChange();
+            },
+
+            ...fieldDef
+        } as JFieldController_Private;
+
+        return field;
+    }
+
+    private declareState_Submitting() {
+        this.submitting = true;
+        this.submitted = false;
+        this.error = false;
+
+        this.onStateChange.forEach(l => l());
+    }
+
+    private declareState_Submitted() {
+        this.submitting = false;
+        this.submitted = true;
+        this.error = false;
+
+        this.onStateChange.forEach(l => l());
+    }
+
+    private declareState_Error(isError = true) {
+        // Here we must keep the submitted state.
+        this.error = isError;
+
+        if (!isError) {
+            if (this.formMessage && !this.formMessage.isOk) {
+                this.formMessage = undefined;
+            }
+        }
+
+        this.onStateChange.forEach(l => l());
+    }
+
+    private declareState_Reset() {
+        this.submitting = false;
+        this.submitted = false;
+        this.declareState_Error(false);
+    }
+
+    addStateChangeListener(l: () => void) {
+        if (!this.onStateChange.includes(l)) {
+            this.onStateChange.push(l);
+        }
+    }
+
+    removeStateChangeListener(l: () => void) {
+        let idx = this.onStateChange.indexOf(l);
+        if (idx!==-1) this.onStateChange.splice(idx, 1);
+    }
+}
+
+function calcDefault(fieldDef: jk_schema.SchemaFieldInfos|undefined): any {
+    if (!fieldDef) return undefined;
+
+    if (fieldDef.type === "string") return "";
+    if (fieldDef.type === "number") return undefined;
+    if (fieldDef.type === "boolean") return false;
+    if (fieldDef.type === "object") return {};
+    if (fieldDef.type === "array") return [];
+    return undefined;
+}
+
+function getVariantName(fieldType: string): string {
+    switch (fieldType) {
+        case "string": return "TextFormField";
+        case "number": return "NumberFormField";
+        case "boolean": return "CheckboxFormField";
+        case "file": return "FileSelectField";
+    }
+
+    return "TextFormField";
+}
+
+function selectValueConverter(fieldType: string): ((v: any, isTyping: boolean) => any) {
+    switch (fieldType) {
+        case "string": return (v: any) => {
+            return String(v);
+        }
+
+        case "number": return (v: any, isTyping: boolean) => {
+            if (!isTyping) {
+                if (v===undefined) return undefined;
+                v = String(v).trim().replaceAll(",", ".");
+                if (v === "") return undefined;
+            }
+            else {
+                v = String(v).trim().replaceAll(",", ".");
+            }
+
+            let asNumber = Number(v);
+
+            // Must avoid blocking if doing something like "+5,3"
+
+            // Let it return a string.
+            // Will send an error of the type "number is required".
+            //
+            if (isNaN(asNumber)) return v;
+
+            if (v==="") return undefined;
+            return asNumber;
+        }
+
+        case "boolean":  return (v: any) => {
+            return Boolean(v);
+        }
+    }
+
+    return (v: any) => v;
+}