@sio-group/form-react 0.1.0 → 0.2.0

package/src/components/Link/index.tsx

@@ -0,0 +1,106 @@
+import { LinkProps } from "../../types";
+import React from "react";
+
+const LinkComponent: React.FC<LinkProps> = ({
+    label,
+    to = '#',
+    onClick,
+    color = 'default',
+    size = 'md',
+    block = false,
+    loading = false,
+    disabled = false,
+    className = '',
+    ariaLabel = '',
+    navigate,
+    external = false,
+    style = {},
+    children,
+}: LinkProps) => {
+  const isDisabled: boolean = disabled || loading;
+  const isExternal: boolean = external || /^(https?:|mailto:|tel:|ftp:)/.test(to);
+
+  const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+    if (isDisabled) {
+      e.preventDefault();
+      return;
+    }
+
+    onClick?.(e);
+
+    if (!isExternal && navigate) {
+      e.preventDefault();
+      navigate();
+    }
+  };
+
+  const linkClasses = [
+    'link',
+    `link--${color}`,
+    `btn--${size}`,
+    block && 'link--block',
+    loading && 'link--loading',
+    isDisabled && 'link--disabled',
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <a
+      href={isDisabled ? undefined : to}
+      onClick={handleClick}
+      className={linkClasses}
+      style={style}
+      aria-label={ariaLabel || (label as string)}
+      aria-busy={loading}
+      aria-disabled={isDisabled}
+      target={isExternal ? '_blank' : undefined}
+      rel={isExternal ? 'noopener noreferrer' : undefined}>
+      {loading ? (
+        <>
+						<span className='btn__spinner' aria-hidden='true'>
+							<svg viewBox='0 0 20 20'>
+								<circle cx='10' cy='10' r='8' />
+							</svg>
+						</span>
+          <span className='btn__loading-text'>Processing...</span>
+        </>
+      ) : (
+        <>
+          {children}
+          {label && <span className="btn__label">{label}</span>}
+        </>
+      )}
+    </a>
+  );
+}
+
+/**
+ * Custom Link component for internal or external navigation
+ *
+ * @component
+ * @example
+ * // Internal link
+ * <Link to="/dashboard" label="Dashboard" />
+ *
+ * @example
+ * // External link
+ * // external property is optional
+ * // http(s), ftp, email and tel with automatically render as external
+ * <Link to="https://example.com" label="Visit website" external />
+ *
+ * @example
+ * // Link with loading state
+ * <Link to="/profile" label="Profile" loading />
+ *
+ * @example
+ * // Link with custom click handler en navigation
+ * <Link
+ *   to="/settings"
+ *   label="Settings"
+ *   onClick={() => console.log('clicked')}
+ *   navigate={customNavigate}
+ * />
+ */
+export const Link: React.FC<LinkProps> = React.memo(LinkComponent);

package/src/hooks/useConnectionStatus.ts

@@ -0,0 +1,20 @@
+import { useEffect, useState } from "react";
+
+export const useConnectionStatus = (): boolean => {
+  const [isOnline, setIsOnline] = useState<boolean>(navigator.onLine);
+
+  useEffect(() => {
+    const handleOnline = () => setIsOnline(true);
+    const handleOffline = () => setIsOnline(false);
+
+    window.addEventListener('online', handleOnline);
+    window.addEventListener('offline', handleOffline);
+
+    return () => {
+      window.removeEventListener('online', handleOnline);
+      window.removeEventListener('offline', handleOffline);
+    }
+  }, []);
+
+  return isOnline;
+}

package/src/hooks/useForm.ts

@@ -0,0 +1,230 @@
+import { useCallback, useState } from "react";
+import { useConnectionStatus } from "./useConnectionStatus";
+import { FormField, ValidationRule } from "@sio-group/form-types";
+import { slugify } from "../utils/slugify";
+import { createFieldState } from "../utils/create-field-state";
+import { createFieldProps } from "../utils/create-field-props";
+import { FieldProps, UseFormOptions, FieldState, FieldSetters } from "../types";
+
+export const  useForm = ({ disableWhenOffline }: UseFormOptions = { disableWhenOffline: true }) => {
+  const isOnline: boolean = useConnectionStatus();
+
+  const [fields, setFields] = useState<Record<string, FieldState>>({});
+  const [isDirty, setIsDirty] = useState<boolean>(false);
+  const [isBusy, setIsBusy] = useState<boolean>(false);
+
+  /**
+   * Runs all validations for a field.
+   * @param value
+   * @param validations
+   * @param label
+   */
+  const validateField = (value: unknown, validations: ValidationRule<any>[], label?: string): string[] => {
+    return validations
+      .map((validation: ValidationRule<any>): string | null => validation(value, label))
+      .filter((error: string | null): error is string => !!error);
+  }
+
+  /**
+   * Validates the entire form.
+   */
+  const validateForm = (): boolean => {
+    return Object.values(fields).every((field: FieldState): boolean => field.errors?.length === 0);
+  };
+
+  /**
+   * Register a field to the form.
+   */
+  const register = useCallback((name: string, config: FormField, renderLayout?: boolean): FieldProps => {
+    if (!name) throw new Error('Field name is required');
+
+    const id: string = slugify(name);
+
+    const existing: FieldState = fields[name];
+    const shouldCreate: boolean = !existing || existing.type !== config.type;
+
+    let field: FieldState;
+    if (shouldCreate) {
+      field = createFieldState(name, id, config);
+      setFields((prevState) => ({
+        ...prevState,
+        [name]: {
+          ...field,
+          errors: validateField(field.value, field.validations, field.label)
+        }
+      }));
+    } else {
+      field = existing;
+    }
+
+    const setters: FieldSetters = {
+      handleChange: (value: unknown) => {
+        setIsDirty(true);
+        setFields((prevState) => {
+          const current = prevState[name];
+          if (!current) return prevState;
+
+          return {
+            ...prevState,
+            [name]: {
+              ...current,
+              value,
+              errors: validateField(value, current.validations, current.label)
+            }
+          };
+        });
+      },
+      setFocused: (focused: boolean) => {
+        setFields((prevState) => {
+          const current: FieldState = prevState[name];
+          if (!current) return prevState;
+
+          return {
+            ...prevState,
+            [name]: {
+              ...current,
+              focused,
+            },
+          }
+        });
+      },
+      setTouched: (touched: boolean) => {
+        setFields((prevState) => {
+          const current: FieldState = prevState[name];
+          if (!current) return prevState;
+
+          return {
+            ...prevState,
+            [name]: {
+              ...current,
+              touched,
+            },
+          }
+        });
+      },
+      setErrors: (errors: string[]) => {
+        setFields((prevState) => {
+          const current: FieldState = prevState[name];
+          if (!current) return prevState;
+
+          return {
+            ...prevState,
+            [name]: {
+              ...current,
+              errors,
+            },
+          }
+        });
+      },
+    };
+
+    return createFieldProps(
+      field,
+      setters,
+      config.config?.disabled || (!isOnline && disableWhenOffline),
+      renderLayout
+    );
+  }, [disableWhenOffline, isOnline, fields]);
+
+  /**
+   * Unregister a field from the form.
+   * @param name
+   */
+  const unregister = (name: string) => {
+    setFields((prevState) => {
+      const { [name]: _, ...rest } = prevState;
+      return rest;
+    });
+  }
+
+  /**
+   * Set the value of a field.
+   * @param name
+   * @param value
+   */
+  const setValue = (name: string, value: unknown) => {
+    if (fields[name]) {
+      setFields((prevState) => {
+        const current: FieldState = prevState[name];
+        if (!current) return prevState;
+
+        return {
+          ...prevState,
+          [name]: {
+            ...current,
+            value,
+            errors: validateField(
+              value,
+              prevState[name].validations,
+              prevState[name].label,
+            ),
+          },
+        }
+      });
+    }
+  };
+
+  /**
+   * Get all form values
+   */
+  const getValues = (): Record<string, any> => {
+    return Object.keys(fields).reduce((acc: Record<string, any>, key: string) => {
+      acc[key] = fields[key].value || null;
+      return acc;
+    }, {});
+  }
+
+  /**
+   * Fet the value of a specific field by name.
+   * @param name
+   */
+  const getValue = (name: string) => {
+    return fields[name]?.value ?? null;
+  }
+
+  /**
+   * Reset and rebuild the form.
+   */
+  const reset = () => {
+    setFields({});
+    setIsDirty(false);
+    setIsBusy(false);
+  }
+
+  /**
+   * Handle submit and submit state
+   * @param onSubmit
+   */
+  const handleSubmit = async (onSubmit: (values: Record<string, any>) => void | Promise<void>): Promise<void> => {
+    if (isBusy) return;
+
+    try {
+      setIsBusy(true);
+      await onSubmit(getValues());
+    } finally {
+      setIsBusy(false);
+    }
+  }
+
+  /**
+   * Get e specific field
+   * @param name
+   */
+  const getField = (name: string): FieldState | undefined => {
+    return fields[name] || undefined;
+  }
+
+  return {
+    register: register,
+    unregister: unregister,
+    setValue: setValue,
+    getValues: getValues,
+    getValue: getValue,
+    reset: reset,
+    isValid: validateForm,
+    isDirty: () => isDirty,
+    isBusy: () => isBusy,
+    submit: handleSubmit,
+    getField: getField,
+  };
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+export { Form } from './components/Form';
+
+export { useForm } from './hooks/useForm';
+
+export { Button } from './components/Button';
+export { Link } from './components/Link';
+export * from './components/Fields';
+
+export type {
+  FieldProps,
+  FormConfig,
+  FormLayout,
+  ButtonProps,
+  LinkProps,
+} from './types'

package/src/types/field-props.d.ts

@@ -0,0 +1,94 @@
+import { AcceptType, CaptureType, IconType, Option, SelectOption, SpinnerVariant } from "@sio-group/form-types";
+import { Properties } from 'csstype';
+
+export type BaseFieldProps = {
+  id: string;
+  name: string;
+  label?: string;
+  placeholder?: string;
+  value: unknown;
+  errors: string[];
+  required?: boolean;
+  autocomplete?: string;
+  touched: boolean;
+  focused: boolean;
+  readOnly?: boolean;
+  disabled: boolean;
+  icon?: IconType;
+  description?: string;
+  onChange: (value: unknown) => void;
+  setFocused: (focused: boolean) => void;
+  setTouched: (touched: boolean) => void;
+  className?: string;
+  style?: Properties;
+};
+
+export type TextareaFieldProps = BaseFieldProps & {
+  type: "textarea";
+  rows?: number;
+  cols?: number;
+};
+
+export type FileFieldProps = BaseFieldProps & {
+  type: "file";
+  accept?: AcceptType;
+  multiple: boolean;
+  capture: CaptureType;
+  onError: (errors: string[]) => void;
+  filesize: number;
+  onFileRemove?: (file: File, index: number, files: File[]) => void;
+  onRemoveAll?: (files: File[]) => void;
+};
+
+export type NumberFieldProps = BaseFieldProps & {
+  type: "number";
+  min: number;
+  max: number;
+  step: number;
+  spinner: boolean | SpinnerVariant;
+};
+
+export type RangeFieldProps = BaseFieldProps & {
+  type: "range";
+  min: number;
+  max: number;
+  step: number;
+  showValue: boolean;
+};
+
+export type DateFieldProps = BaseFieldProps & {
+  type: "date" | "time" | "datetime-local";
+  min: string;
+  max: string;
+  step: number;
+};
+
+export type UrlFieldProps = BaseFieldProps & {
+  type: "url";
+  allowLocalhost: boolean;
+  allowFtp: boolean;
+  secureOnly: boolean;
+};
+
+export type SelectFieldProps = BaseFieldProps & {
+  type: "select" | "creatable";
+  options: SelectOption[];
+  multiple: boolean;
+};
+
+export type RadioFieldProps = BaseFieldProps & {
+  type: "radio";
+  options: string[] | Option[];
+  inline: boolean;
+};
+
+export type FieldProps =
+  | FileFieldProps
+  | TextareaFieldProps
+  | NumberFieldProps
+  | RangeFieldProps
+  | DateFieldProps
+  | UrlFieldProps
+  | SelectFieldProps
+  | RadioFieldProps
+  | (BaseFieldProps & { type: Exclude<FieldType, "file" | "textarea" | "range" | "date" | "time" | "datetime-local" | "url" | "select" | "creatable" | "radio"> });

package/src/types/field-setters.d.ts

@@ -0,0 +1,6 @@
+export interface FieldSetters {
+  handleChange: (value: unknown) => void;
+  setFocused: (focussed: boolean) => void;
+  setTouched: (touched: boolean) => void;
+  setErrors: (errors: string[]) => void;
+}

package/src/types/field-state.d.ts

@@ -0,0 +1,21 @@
+import { FieldConfigMap } from "@sio-group/form-types";
+import { ValidationRule } from "@sio-group/form-types/src/core/valudation-rule";
+
+export type FieldType = keyof FieldConfigMap;
+
+export type FieldState = {
+  [K in FieldType]: {
+    type: K;
+    id: string;
+    name: string;
+    value: FieldConfigMap[T]['defaultValue'];
+
+    validations: ValidationRule<T>[];
+    errors: string[];
+
+    touched: boolean;
+    focused: boolean;
+  } & FieldConfigMap[K]
+}[FieldType];
+
+export type FieldValue<T extends FieldType> = FieldState<T>['value'];

package/src/types/form-config.d.ts

@@ -0,0 +1,30 @@
+import { ComponentType, CSSProperties, ComponentPropsWithoutRef, HTMLAttributes } from "react";
+import { FormField } from "@sio-group/form-types";
+import { FormLayout } from "./form-layout";
+import { ButtonProps, LinkProps } from "./ui-props";
+
+type FormContainerProps = ComponentPropsWithoutRef<'form'>;
+type ButtonContainerProps = HTMLAttributes<HTMLDivElement>;
+
+export interface FormConfig {
+  fields: FormField[];
+  layout?: FormLayout[];
+
+  submitShow?: boolean;
+  submitAction: (values: Record<string, any>) => void | Promise<void>;
+  submitLabel?: string;
+  cancelShow?: boolean;
+  cancelAction?: () => void;
+  cancelLabel?: string;
+
+  buttons?: (ButtonProps | LinkProps)[];
+  extraValidation?: (values: Record<string, any>) => boolean | Promise<boolean>
+
+  className?: string;
+  style?: CSSProperties;
+
+  disableWhenOffline?: boolean;
+
+  container?: ComponentType<FormContainerProps>;
+  buttonContainer?: ComponentType<ButtonContainerProps>;
+}

package/src/types/form-layout.d.ts

@@ -0,0 +1,6 @@
+import { LayoutType } from "@sio-group/form-types";
+
+export interface FormLayout {
+  fields: string[];
+  layout?: LayoutType;
+}

package/src/types/index.ts

@@ -0,0 +1,18 @@
+export type {
+  FieldProps,
+  BaseFieldProps,
+  TextareaFieldProps,
+  FileFieldProps,
+  NumberFieldProps,
+  RangeFieldProps,
+  DateFieldProps,
+  UrlFieldProps,
+  SelectFieldProps,
+  RadioFieldProps,
+} from './field-props';
+export type { FieldSetters } from './field-setters';
+export type { FieldType, FieldState, FieldValue } from './field-state';
+export type { FormConfig } from './form-config';
+export type { FormLayout } from './form-layout';
+export type { ButtonProps, LinkProps } from './ui-props';
+export type { UseFormOptions } from './use-form-options';

package/src/types/ui-props.d.ts

@@ -0,0 +1,33 @@
+import React from 'react';
+
+export type ButtonType = 'button' | 'submit' | 'reset';
+export type Variant = 'primary' | 'secondary' | 'link';
+export type Color = 'default' | 'error' | 'success' | 'warning' | 'info';
+export type Size = 'sm' | 'md' | 'lg';
+
+type BaseUiProps = {
+  variant?: Variant;
+  label?: string | React.ReactNode;
+  color?: Color;
+  size?: Size;
+  block?: boolean;
+  loading?: boolean;
+  disabled?: boolean;
+  className?: string;
+  ariaLabel?: string;
+  style?: React.CSSProperties;
+  children?: React.ReactNode;
+};
+
+export type ButtonProps = BaseUiProps & {
+  type?: ButtonType;
+  onClick: (e: React.MouseEvent) => void;
+};
+
+export type LinkProps = Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'onClick' | 'color'> &
+  BaseUiProps & {
+  to: string;
+  navigate?: () => void;
+  external?: boolean;
+  onClick?: (e: React.MouseEvent) => void;
+};

package/src/types/use-form-options.d.ts

@@ -0,0 +1,3 @@
+export interface UseFormOptions {
+  disableWhenOffline: boolean;
+}