SQHooks 🎣
Getting Started
> npm install @selectquotelabs/sqhooksLocal Development
NPM Version: lts/fermium
> npm install🧙♂️ HIGHLY recommend running
npm run test.watchduring development to ensure tests are passing
Testing your changes before you commit
- Build your source code
> npm run build- package your code for
npm
npm pack-
Copy the path of the tarball file
-
From the consumer repo
npm install ~/path/to/selectquotelabs-sqhooks-x.x.x.tgz🧙♂️ It's easiest to test consumption on a non-Docker project such as SQForm, senior-admin-ui, senior-aqe-ui, scplus-shared-components, etc.
- Import your custom hook, write necessary code and test to ensure it works 🚀
Example
import {useDialog} from '@selectquotelabs/sqhooks';
Hopefully you know how to consume a hook within a component
Contributing
Conventional Commits
Coming soon...
SQHooks API Rules
Hook names should be prefixed with use
✅
useCounter
⛔️
counter
Hook arguments and return value MUST be either a single value or an object
✅
function useMyState(initialState) {
const [state, setState] = useState(initialState);
return {state, setState};
}⛔️
function useMyState(initialState) {
const [state, setState] = useState(initialState);
return [state, setState];
}🧙♂️ Being strict and opinionated about our hooks argument and return value creates a predictable API. This also makes typing and testing easier.
Documentation
useDialog
Description Controls a dialog open state
Example
const {isDialogOpen, openDialog, closeDialog} = useDialog(false);Parameters
isOpen: boolean Is the initial Dialog open state. Defaults to false if not specified
Returns {isDialogOpen: boolean, openDialog: void fn, closeDialog: void fn}
usePrevious
Description Get the previous value of props or state
Example
const [count, setCount] = useState(0);
const prevCount = usePrevious(count);
// If the `count` increments to 1 the `prevCount` will be 0Parameters
value: the value whose previous state we want to track
initialValue: (optional) the return value of the hook on initial render. If an initialValue isn't provided the initial return value will be undefined.
Returns The previous value of the target state
useDebounce / useDebouncedCallback
Description useDebounce for simple values, useDebouncedCallback for callbacks
Example
// useDebounce
const [text, setText] = useState('Hello');
const [value] = useDebounce(text, 1000);
return (
<div>
<input
defaultValue={text}
onChange={(event) => setText(event.target.value)}
/>
<p>Actual value: {text}</p>
<p>Debounced value: {value}</p>
</div>
);
// useDebouncedCallback
const [value, setValue] = useState('');
const debounced = useDebouncedCallback((value) => {
setValue(value);
}, 1000);
return (
<div>
<input
defaultValue={value}
onChange={(event) => debounced(event.target.value)}
/>
<p>Debounced value: {value}</p>
</div>
);useLocalStorage
Description Sync state to local storage (similar to useState) so that it persists through a page refresh. Tests utilize the jest-localstorage-mock.
Example
const {storedValue, setValue} = useLocalStorage('ID', 'abc123');Parameters
key: string The localStorage key you want to read/create/update.
initialValue (optional) The initial value to set if the value of the key in localStorage is empty.
Returns
{
storedValue: Type | undefined;
setValue: React.Dispatch<React.SetStateAction<Type | undefined>>;
}useIsomorphicLocalStorage
Description An isomorphic version of useLocalStorage. Sync state to local storage (similar to useState) so that it persists through a page refresh. Tests utilize the jest-localstorage-mock.
Example
const {storedValue, storeValue, isFetching} = useIsomorphicLocalStorage(
'ID',
'abc123'
);Parameters
key: string The localStorage key you want to read/create/update.
initialValue (optional) The initial value to set if the value of the key in localStorage is empty.
Returns the stored value from localStorage, a function to store a value in localStorage, and a boolean value to indicate fetching state.
{
storedValue: string;
storeValue: React.Dispatch<React.SetStateAction<Type | undefined>>;
isFetching: boolean;
}useToggle
Description Simple hook that returns a boolean value and a function that toggles that value to the inverse of its current state.
Example
const {value, toggle} = useToggle();Parameters
initialValue: boolean (optional) The initial value of value. Defaults to false if not specified.
Returns
{
value: boolean;
toggle: () => void
}useDropdownOptions
Description Transforms your array of objects into the shape our form system expects.
Example
const users = [
{firstName: 'Franken', lastName: 'Berry', ID: 123},
{firstName: 'Count', lastName: 'Chocula', ID: 456},
{firstName: 'Boo', lastName: 'Berry', ID: 789},
];
const options = useDropdownOptions('firstName', 'ID', users);
/*
options:
[
{ label: 'Franken', value: 123 },
{ label: 'Count', value: 456 },
{ label: 'Boo', value: 789 },
]
*/Parameters
label: the key in the provided items object array to use as the value of the label property in the returned options object array
value: the key in the provided items object array to use as the value of the value property in the returned options object array
items: array of objects from which to draw the values of label and value to build the options object array
Returns Array of objects to be used as dropdown options
{
label: string | number;
value: string | number | null;
}
[];useClipboard
Description Returns a function to copy a given value to the clipboard, and a ref to pass to an element to enable copying its innerText using the function as the element's onClick handler.
Example
// copies 'hello'
const {onClick, ref} = useClipboard();
return (
<button onClick={onClick} ref={ref}>
hello
</button>
);
// copies 'world'
const {onClick, ref} = useClipboard('world');
return (
<button onClick={onClick} ref={ref}>
hello
</button>
);Parameters
contentToCopy: string (optional) Content to copy to the clipboard when onClick is called. If a value is not specified, the innerText of the clicked element will be copied.
Returns
{
onClick: () => Promise<void>;
ref: React.RefObject<HTMLElement>;
}useAutoHeight
Description Returns a callback function which works the same as a ref that should be attached to the component that is to be auto-size. Also returns a height string which should be added to that component's styles as well. Note: This only works for components that are the last child of their parent.
Example
const {containerRef, autoHeight} = useAutoHeight();
return <div ref={containerRef} style={{height: autoHeight}} />;Returns
{
containerRef: (node: HTMLElement) => void;
autoHeight: String | undefined;
}Migrate to SQHooks
Use the library for net-new code. As a PR reviewer, encourage the use of Hooks from this library. Squads should create backlog tickets to replace a hook, with it's SQHooks equivalent.
Upgrading
v1 to v2
Affected hooks: useDropdownOptions
v2 of SQHooks includes a change to useDropdownOptions that allows it to return an empty array. Previously if an empty array was passed for items then the hook would return an array with the "empty" option, {label: '- -', value: null}. v2 will now return an empty array. If you still want that "empty" on your dropdown or autocomplete then you should use the displayEmpty prop on your component.