react-luminus-components 1.0.1 → 1.0.2

package/README.md

@@ -1,3 +1,351 @@
-## React Bnf Components
+# React Luminus Components
 
-Library of React Components reusable in bnf projects (Fleetman, CAFM)
+Library of React Components reusable in Luminus projects (Fleetman, CAFM)
+
+---
+
+## Some Documentation
+
+### Components
+
+- **Typography**\
+  Encapsulated text styles
+  - variant: 'h1' | 'h3' | 'h6' | 'subtitle' | 'body' | 'body2' | 'caption'
+  ***
+- **Loading**\
+  Loading indicator
+  ***
+- **MonthPicker**\
+  Month picker, gives you the first day of the picked month
+  - month: Date
+  - onChangeMonth: (month: Date) => void
+  ***
+- **HomeDashboard**\
+  Dashboard which renders widgets, user can pick his own widgets, reorder them, make some of them full-width...
+  - availableWidgets: DashboardWidget[]
+    - _set of the widgets available for the specific app/user_
+  ***
+- **ApiFileDownloadButton**\
+  Button which downloads the file from the API and saves it on the device
+  - fileLoader: () => Promise<Blob | null>
+  - fileName: string
+  ***
+- **SimpleTooltip**\
+  Renders text in a basic tooltip
+  - text: string
+  - placement: 'top' | 'bottom' | 'left' | 'right'
+  ***
+- **HtmlTooltip**\
+  More advanced tooltip, renders whatever you send as the content, you can also specify the action triggering the tooltip and the header of the tooltip
+  - heading: string
+  - content: ReactElement
+  - placement: 'top' | 'bottom' | 'left' | 'right'
+  - trigger?: 'click' | 'hover' | 'focus'
+  ***
+- **AvatarIcon**\
+  Avatar icon with person's initials, generates custom background color based on the person's name
+  - name: string
+  - fontSize?: number
+  - size?: number
+  ***
+- **UserAvatarDropdown**\
+  Renders the AvatarIcon which opens a dropdown of actions on click (suitable for Logout button for example), you send the items as the children
+  - userName: string
+  ***
+- **EmployeeSearch**\
+  Searches employees based on the input query, fires onEmployeeSelected on employee click
+  - onEmployeeSelected: (employee: EmployeeIndexModel) => void
+  ***
+- **EmployeeSearchModal**\
+  Renders the EmployeeSearch inside of a modal
+  - show: boolean
+  - onCancel: () => void
+  - onEmployeeSelected: (employee: EmployeeIndexModel) => void
+  ***
+- **EmployeePicker**\
+  Renders an input select element with custom logic which opens the EmployeeSearchModal to pick an employee
+  - defaultSelection: NameIdIntModel | null
+  - onSelect?: (employee: NameIdIntModel | null) => void
+  - label?: string
+  - withoutLabel?: boolean
+    - _doesn't render the floating label when set_
+  - size?: 'sm' | 'lg'
+  - hidden?: boolean
+  - disabled?: boolean
+  ***
+- **CheckInput**\
+  Just a check input
+  - value: boolean
+  - onChange?: (value: boolean) => void
+  - label?: string
+  - hidden?: boolean
+  - disabled?: boolean
+  - type?: 'switch' | 'checkbox'
+  ***
+- **TextInput**\
+  Just a text input
+  - type: 'text' | 'number' | 'password' | 'date' | 'datetime-local'
+  - value: string | number | null
+  - onChange?: (value: string | number | null) => void
+  - label?: string
+  - withoutLabel?: boolean
+    - _doesn't render the floating label when set_
+  - placeholder?: string
+  - size?: 'sm' | 'lg'
+  - hidden?: boolean
+  - disabled?: boolean
+  - showClearIcon?: boolean
+    - _renders an icon which clears the value on click_
+  - clearValue?: string | number
+    - _clear icon sets this value insted of a default one if specified_
+  ***
+- **SelectInput**\
+  Just a select input
+  - value: string | number | null
+  - options?: FormSelectOption[]
+    - _the options for the selection (dropdown list)_
+  - onChange?: (value: string | number | null) => void
+  - label?: string
+  - withoutLabel?: boolean
+    - _doesn't render the floating label when set_
+  - isNumber?: boolean
+    - _you must set this if the input value is numeric, it handles the parsing and sets null if the value is not a valid number_
+  - size?: 'sm' | 'lg'
+  - hidden?: boolean
+  - disabled?: boolean
+  - showClearIcon?: boolean
+    - _renders an icon which clears the value on click_
+  - clearValue?: string | number
+    - _clear icon sets this value insted of a default one if specified_
+  ***
+
+### Hook Form Inputs
+
+Input elements to be used in the react-hook-form, they handle some additional logic.\
+Each requires a hookFormProps prop which is of type HookFormInputProps and contains all the react-hook-form methods neccessary.
+
+_register: UseFormRegister<FieldValues>_\
+_formState: FormState<FieldValues>_\
+_getValues: UseFormGetValues<FieldValues>_\
+_setValue: UseFormSetValue<FieldValues>_\
+_watch: UseFormWatch<FieldValues>_
+
+Then each component also specifies it's own inputProps (similar to normal input components), listed below
+
+- **HookFormEmployeePicker**\
+  Just like the EmployeePicker
+  - formField: string
+    - _the react-hook-form field you register the input to_
+  - label: string
+  - defaultSelection: NameIdIntModel | null
+  - size?: 'sm' | 'lg'
+  - resetsFields?: string[]
+    - _list of form fields you want to reset when this input's value is changed_
+  - hidden?: boolean
+  - disabled?: boolean
+  ***
+- **HookFormCheckInput**\
+  Just a check input
+  - formField: string
+    - _the react-hook-form field you register the input to_
+  - label: string
+  - resetsFields?: string[]
+    - _list of form fields you want to reset when this input's value is changed_
+  - type?: 'switch' | 'checkbox'
+  - hidden?: boolean
+  - disabled?: boolean
+  ***
+- **HookFormRadioInput**\
+  Just a radio input
+  - formField: string
+    - _the react-hook-form field you register the input to_
+  - options: NameIdStringModel[]
+    - _the radio options_
+  - resetsFields?: string[]
+    - _list of form fields you want to reset when this input's value is changed_
+  - hidden?: boolean
+  - disabled?: boolean
+  ***
+- **HookFormSelectInput**\
+  Just a select input
+  - formField: string
+    - _the react-hook-form field you register the input to_
+  - label: string
+  - options: FormSelectOption[]
+    - _the options for the selection (dropdown list)_
+  - isNumber?: boolean
+    - _you must set this if the input value is numeric, it handles the parsing and sets null if the value is not a valid number_
+  - size?: 'sm' | 'lg'
+  - resetsFields?: string[]
+    - _list of form fields you want to reset when this input's value is changed_
+  - showClearIcon?: boolean
+    - _renders an icon which clears the value on click_
+  - clearValue?: string | number
+    - _clear icon sets this value insted of a default one if specified_
+  - hidden?: boolean
+  - disabled?: boolean
+  ***
+- **HookFormTextInput**\
+  Just a text input
+  - formField: string
+    - _the react-hook-form field you register the input to_
+  - type: 'text' | 'number' | 'password' | 'date' | 'datetime-local'
+  - label: string
+  - placeholder?: string
+  - size?: 'sm' | 'lg'
+  - resetsFields?: string[]
+    - _list of form fields you want to reset when this input's value is changed_
+  - showClearIcon?: boolean
+    - _renders an icon which clears the value on click_
+  - clearValue?: string | number
+    - _clear icon sets this value insted of a default one if specified_
+  - hidden?: boolean
+  - disabled?: boolean
+  ***
+- **HookFormTextAreaInput**\
+  Just a text area input
+  - formField: string
+    - _the react-hook-form field you register the input to_
+  - label: string
+  - size?: 'sm' | 'lg'
+  - resetsFields?: string[]
+    - _list of form fields you want to reset when this input's value is changed_
+  - showClearIcon?: boolean
+    - _renders an icon which clears the value on click_
+  - clearValue?: string | number
+    - _clear icon sets this value insted of a default one if specified_
+  - hidden?: boolean
+  - disabled?: boolean
+  ***
+
+### Layout
+
+Common layout components
+
+- **SideMenu**\
+  Renders the side menu with navigation items
+  - mainItems: MenuItemType[]
+  - secondaryItems: MenuItemType[]
+  - expanded: boolean
+  - onExpand: () => void
+  ***
+- **TopBar**\
+  Renders the top bar with the application name and child items
+  - appName: string
+  ***
+- **SideContentBar**\
+  Renders the side content bar on the right side, content is sent as children
+  - width: number
+  ***
+- **MainContainer**\
+  The main container for each page
+  - sideContent?: React.ReactNode
+    - _renders the SideContentBar with this content if specified_
+  ***
+- **FullScreenContainer**\
+  Container which always spans the whole screen with overflow hidden (you control the scrollbars in your content)
+  ***
+
+### Contexts
+
+- **LuminusComponentsContext**\
+  The app context for this Luminus Components package, you need to include this in your application to work with the Luminus Components.\
+  You set all of the text variables displayed by the Luminus Components here, as well as the axiosInstance to enable communication between the API and the Luminus Components
+  - axiosInstance: AxiosInstance
+  - LinkComponent: React.ForwardRefExoticComponent<LinkProps & React.RefAttributes<HTMLAnchorElement>>
+  - language: string
+  - axiosTexts: AxiosTexts
+  - confirmTexts: ConfirmTexts
+  - formValidationTexts: FormValidationTexts
+  - employeePickerModalTexts: EmployeeSearchModalTexts
+  - homeDashboardTexts: HomeDashboardTexts
+  ***
+- **LoadingContext**\
+  This context help you with the loading state visualisation, it keeps track of all of the loadings happening in the app and displays the Loading indicator whenever there's a loading running
+  - isLoading: boolean
+  - startLoading: (key: string) => void
+    - _you call this whenever you want some loading to start (key is the unique identifier for the loading in question (e.g. loadingVehicleDetail))_
+  - stopLoading: (key: string) => void
+    - _you call this whenever the loading you triggered previously ends to clear the loading state (you send the same key)_
+  ***
+- **UserContext**\
+  Keeps track of the currently logged-in user
+  - user: UserModel | null
+  - loginUser: () => Promise<boolean>
+  - logoutUser: () => void
+  ***
+
+### Hooks
+
+- **useAuth**\
+  The authentication process
+  - isAuthenticated: () => boolean
+  - getToken: () => string | null
+  - authenticate: (kid: string, password: string): Promise<boolean>
+  - logout: () => void
+  ***
+- **useAxios**\
+  Sets the axios instance up with some logic (e.g. displaying toasts whenever there's an error response)
+  - axiosInstance
+  - cancelToken: CancelTokenStatic
+  ***
+- **useConfirm**\
+  Custom confirm pop-up
+  - confirm: (t: string) => Promise<boolean>
+  ***
+- **useNotifications**\
+  Creates and shows custom toast notifications
+  - addNotification: (message: string, type: 'success' | 'warning' | 'danger') => void
+  ***
+- **useZodSchemaTypes**\
+  Common types for the zod schema you use with the react-hook-form for fluent validation
+  - zString
+    - _the field is any string_
+  - zStringRequired
+    - _the field is a required string_
+  - zNumber
+    - _the field is any number_
+  - zNumberRequired
+    - _the field is a required number_
+  - zBool
+    - _the field is a boolean_
+  - zDate
+    - _the field is a date-string in ISO format_
+  - zDateRequired
+    - _the field is a required date-string in ISO format_
+  - zEnum
+    - _the field is an enum value_
+  - zEnumRequired
+    - _the field is a required enum value_
+  - zObjectIdInt
+    - _the field is a numeric id of an object (most commonly NameIdIntModel)_
+  - zObjectIdIntRequired
+    - _the field is a required numeric id of an object (most commonly NameIdIntModel)_
+  - zObjectIdStr
+    - _the field is a string id of an object (most commonly NameIdStringModel)_
+  - zObjectIdStrRequired
+    - _the field is a required string id of an object (most commonly NameIdStringModel)_
+  ***
+
+### Utils
+
+- **Text Utils**
+  - **truncateText**: (str: string) => string
+    - _truncates text to the first 300 characters_
+  ***
+- **Date Utils**
+  - **isISODate**: (dateString: string) => boolean
+    - _checks if the string is a valid ISO date-string_
+  ***
+- **Object Utils**
+  - **isPrimitive**: (val: any) => boolean
+    - _checks if the value is a primitive (is not object or a function)_
+  - **fixNameIdNulls**: (obj: any) => void
+    - _modifies the object, sets null where the value is { id = null }_
+  ***
+- **Api Error Fields Utils**
+  - **extractErrorsFromResponse**: (error: any): ErrorField[]
+    - _takes the error api response and return the validation errors as ErrorField[] (if any)_
+  - **hookFormSetServerErrors**: (formMethods: any, error: any) => void
+    - _sets manual errors to react-hook-form from the error api response_
+  ***

package/dist/components/Form/CheckInput/CheckInput.d.ts

@@ -3,9 +3,10 @@ type Props = {
     value: boolean;
     onChange?: (value: boolean) => void;
     label?: string;
+    hidden?: boolean;
     disabled?: boolean;
     className?: string;
     type?: 'switch' | 'checkbox';
 };
-declare const CheckInput: ({ label, value, onChange, disabled, className, type }: Props) => import("react").JSX.Element;
+declare const CheckInput: ({ label, value, onChange, hidden, disabled, className, type }: Props) => import("react").JSX.Element;
 export default CheckInput;

package/dist/components/Form/Container/InputContainer.d.ts

@@ -2,7 +2,8 @@
 type InputContainerProps = {
     withoutLabel: boolean;
     label: string;
+    hidden?: boolean;
     children: React.ReactNode;
 };
-declare const InputContainer: ({ withoutLabel, label, children }: InputContainerProps) => import("react").JSX.Element;
+declare const InputContainer: ({ withoutLabel, label, hidden, children }: InputContainerProps) => import("react").JSX.Element;
 export default InputContainer;

package/dist/components/Form/EmployeePicker/EmployeePicker.d.ts

@@ -6,7 +6,8 @@ type Props = {
     label?: string;
     withoutLabel?: boolean;
     size?: 'sm' | 'lg';
+    hidden?: boolean;
     disabled?: boolean;
 };
-declare const EmployeePicker: ({ defaultSelection, onSelect, label, withoutLabel, size, disabled, }: Props) => import("react").JSX.Element;
+declare const EmployeePicker: ({ defaultSelection, onSelect, label, withoutLabel, size, hidden, disabled, }: Props) => import("react").JSX.Element;
 export default EmployeePicker;

package/dist/components/Form/SelectInput/SelectInput.d.ts

@@ -8,10 +8,11 @@ type Props = {
     withoutLabel?: boolean;
     isNumber?: boolean;
     size?: 'sm' | 'lg';
+    hidden?: boolean;
     disabled?: boolean;
     showClearIcon?: boolean;
     clearValue?: string | number;
     className?: string;
 };
-declare const SelectInput: ({ value, options, onChange, label, withoutLabel, isNumber, size, disabled, showClearIcon, clearValue, className, }: Props) => import("react").JSX.Element;
+declare const SelectInput: ({ value, options, onChange, label, withoutLabel, isNumber, size, hidden, disabled, showClearIcon, clearValue, className, }: Props) => import("react").JSX.Element;
 export default SelectInput;

package/dist/components/Form/TextInput/TextInput.d.ts

@@ -7,10 +7,11 @@ type Props = {
     withoutLabel?: boolean;
     placeholder?: string;
     size?: 'sm' | 'lg';
+    hidden?: boolean;
     disabled?: boolean;
     showClearIcon?: boolean;
     clearValue?: string | number;
     className?: string;
 };
-declare const TextInput: ({ type, value, onChange, label, withoutLabel, placeholder, size, disabled, showClearIcon, clearValue, className, }: Props) => import("react").JSX.Element;
+declare const TextInput: ({ type, value, onChange, label, withoutLabel, placeholder, size, hidden, disabled, showClearIcon, clearValue, className, }: Props) => import("react").JSX.Element;
 export default TextInput;