react-luminus-components v1.3.225

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

  ---