React Luminus Components

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
  • debounceMs?: number
    • how long shoulud the input be unchanged before onChange fires
  • 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
formState: FormState
getValues: UseFormGetValues
setValue: UseFormSetValue
watch: UseFormWatch

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
  • headerItem: React.ReactNode
    • renders on top (intersection of SideMenu with TopBar)
  • mainItems: MenuItemType[]
  • secondaryItems: MenuItemType[]
  • expanded: boolean
  • setExpanded: (expanded: boolean) => 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 axiosOptions to enable communication between the API and the Luminus Components
  • axiosOptions: axiosOptions
  • language: string

  ---

• 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
  • logoutUser: () => void

  ---

Hooks

• useAuth
  The authentication process
  • isAuthenticated: () => boolean
  • getToken: () => string | null
  • authenticate: (kid: string, password: string): Promise
  • logout: () => void

  ---

• useAxios
  Creates the axios instance 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

  ---

• 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

  ---