TZ Medical React Hooks

This repository contains a collection of custom React hooks.

useFilter

The useFilter hook is designed to filter a list of objects based on a human-inputted text sting. The input can be a word or string to search against all of the preconfigured search fields or a word/string to search against a specific field or a combination of both. The list of fields to search/support is passed into the useFilter hook. See the following table for example interpretations of some example inputs

User Input	Include all objects for which:
global	any field contains the word "global"
-global	no fields contain the word "global"
multiple words	any field contains the word "multiple" and any field contains the word "words"
-multiple words	no fields contain the word multiple and any field contains the wor "words"
"one phrase"	any field contains the string "one phrase"
-"one phrase"	no fields contain the string "one phrase"
name:example	the field associated with the name keyword contains the word "example"
-name:example	the field associated with the name keyword does not contain the word "example"
name:"include spaces"	the field associated with the name keyword contains the string "include spaces"

Usage

The following example shows how to configure and use this hook in a component:

import useFilter from "@tzmedical/react-hooks/useFilter"

const filterFields = {
  // searches starting with `name:` search `element.objectNameField` and
  // the field `objectNameField` is also included in keyword-less inputs
  name: "objectNameField",
  // searches starting with `plural:` search both `element.pluralOne` and `element.pluralTwo`
  // the fields `pluralOne` and `pluralTwo` are also included in keyword-less inputs
  plural: ["pluralOne", "pluralTwo"],
  // searches starting with `callback:` will apply the following function to each element, where value is the content after the colon
  callback: (element, value) => complexFilterFunction(element, value),
  // verb keywords like `is` or `has` can be defined as an object listing allowable nouns
  is: {
    // searches for `is:default` will apply the following function to return all elements where `someDefaultFlag` is true
    default: (element) => element.someDefaultFlag
  },
  has: {
    // searches for `has:something` will apply the following function to return all elements where `somethingList` has a length greater than 0
    something: (element) => element.somethingList?.length > 0,
  }
}

function SomeComponent({ originalList, filterText }) {
  const filteredList = useFilter(originalList, filterText, filterFields)

  // do something with filteredList
}

useInterval

Usage

The following example shows how to configure and use this hook in a component:

import React from "react"
import useInterval from "@tzmedical/react-hooks/useInterval"

const INTERVAL_PERIOD_MS = 15 * 1000

function SomeComponent({  }) {
  // Setting manualTrigger to true will cause the periodicFunction to be run immediately
  // Set to true on first render to cause a first run of the function
  // (This state variable is often tied to a component loading state)
  const [manualTrigger, setManualTrigger] = React.useState(true);

  const periodicFunction = React.useCallback(() => {
    // Needs to do something periodically
  })

  useInterval(periodicFunction, INTERVAL_PERIOD_MS, manualTrigger)
}

useSort

Usage

The following example shows how to configure and use this hook in a component:

import useSort from "@tzmedical/react-hooks/useSort"

// By default, on first render sort all elements by the primary field in ascending order,
// Then sort all elements grouped by the primary field according to the secondary field in descending order
const sortOptions = {
  caseSensitive: false,
  defaultSort: [
    { field: 'primary', reverse: false},
    { field: 'secondary', reverse: true},
  ],
}

function SomeComponent({ originalList }) {
  const [sortedList, handleSortCallback, currentSort] = useSort(originalList, sortOptions)

  // Use sortedList to display the data
  // Use currentSort to display the selected sort field and direction
  // Use handleSortCallback to pass the name of a field to sort by. Passing the name of the current sort field reverses direction.
}

useCheckExists

Usage

The following example shows how to configure and use this hook in a component:

import useCheckExists from "@tzmedical/react-hooks/useCheckExists"

// An example list to check against
const list = [
  { name: 'a', value: 1 },
  { name: 'b', value: 2 },
  { name: 'c', value: 3 },
];

function SomeComponent({ myName = 'b' }) {

  const nameExists = useCheckExists(
    list,               // the list of Objects to search
    "name",             // the field to check on each object
    myName,             // a value to skip when checking the list
    "My error message"  // the message to return if a match is NOT found
  );

  // Returns `true`, since an element with the `name` of `a` exists in `list`
  nameExists('a');

  // Returns `My error message`, since no element with the `name` of `z` exists in `list`
  nameExists('z');


  // Returns `My error message`, since elements with the `name` of `b` are skipped in the check
  nameExists('b');
}

useCheckUnique

Usage

The following example shows how to configure and use this hook in a component:

import useCheckUnique from "@tzmedical/react-hooks/useCheckUnique"

// An example list to check against
const list = [
  { name: 'a', value: 1 },
  { name: 'b', value: 2 },
  { name: 'c', value: 3 },
];

function SomeComponent({ myName = 'b' }) {

  const uniqueName = useCheckUnique(
    list,               // the list of Objects to search
    "name",             // the field to check on each object
    myName,             // a value to skip when checking the list
    "My error message"  // the message to return if a match is found
  );

  // Returns `true`, since no element with the `name` of `z` exists in `list`
  uniqueName('z');

  // Returns `My error message`, since an element with the `name` of `a` exists in `list`
  uniqueName('a');

  // Returns `true`, since elements with the `name` of `b` are skipped in the check
  uniqueName('b');
}

useLocalStorage

Usage

The following example shows how to configure and use this hook in a component:

import useLocalStorage from "@tzmedical/react-hooks/useLocalStorage"

function SomeComponent({ myName = 'b' }) {

  const [myState, setMyState] = useLocalStorage("my.state.id", {default: "value"});

  // Use `myState` and `setMyState` just like `React.useState`!
}

Contributing

For local development, an extra step is needed when using npm link to test changes with an external application to prevent multiple versions of React errors:

# Step 1 - link the React package from the application into this package
npm link ../path/to/test/application/node_modules/react

# Step 2 - expose this package for linking
npm link

# Step 3 - link this package into the application
cd ../path/to/test/application
npm link @tzmedical/react-hooks