k2-react-utils
A collection of standalone ES6 ReactJS utilities and hooks, written in TypeScript and transpiled to and bundled in ES5.
Table of Contents
Setup
This ES5 module is distributed via npm and should be installed as a production dependency.
Using yarn (preferred)
yarn add -E k2-react-utils
or via npm
npm i -S -E k2-react-utils
peerDependencies
Note: react@^16.8.0 would be required when using hook utils.
optionalDependencies
Type definitions come bundled in.
Documentation
k2-react-utils barrels (re-exports) the following utils and hooks as named exports:
<Content/> - source
A component that performs HTML sanitization.
Dependencies: react, react-dom
| Props | Type | Description |
|---|---|---|
| text | string (required) | Returns a DOM node with a <span/> wrapper |
Usage
import * as React from "react"; // standard TypeScript syntax
import { Content } from "k2-react-utils";
const Post: React.FunctionComponent<{}> = () => {
const stringifiedMarkup: string =
"<p>A Lion from Lannisport, and the sheep from the North</p>";
return <Content text={stringifiedMarkup} />; // returns a DOM node
};
classify - source
A function that takes in an object of classes along with conditionals, and returns a string of classnames
Dependencies: none
| Parameters | Type | Description |
|---|---|---|
| classObject | Object (required) | - |
Usage
import * as React from "react"; // standard TypeScript syntax
import { classify } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
const classNames = classify({
"js-active": true,
"js-focus": false
}); // returns "js-active"
return <div className={classNames} />;
};Alternatives
- This util would be helpful when to working imperively with CSS classes, example when authoring libraries.
styled-componentsis a much preferred alternative when styling React components.
connect - source
A re-implementation of react-redux's connect which suppresses @types/react-redux issues when using connect as a decorator to connect class components in TypeScript 2/3.
Dependencies: react, react-dom, react-redux
See connect's parameters here: https://react-redux.js.org/api/connect#connect-parameters
Usage
import * as React from 'react'; // standard TypeScript syntax
import { connect } from 'k2-react-utils';
import { IAppState, ILocale } from './models';
interface IStateProps{
locale: ILocale
}
@connect((state: IAppState)=>({
locale: state.locale
}))
class MyComponent: React.Component<IStateProps>{
render(){
const {locale}=this.props;
return <div>{locale.region}<div/>;
}
}Alternatives
- With
react-redux@7.0.0comes theuseSelectorhook which with less effort connect to yourreduxstore. - The
@connectutil would be ideal when working with stateful class components that would need to be connected to the store.
deviceService - source
A service that identifies the device's current browser, operating system or platform (desktop or mobile) via three getters; getBrowserName, getOperatingSystem, getPlatform.
Usage
import * as React from "react"; // standard TypeScript syntax
import {
getBrowserName,
getOperatingSystem,
getPlatform
} from "k2-react-utils";
getBrowserName(); // sample, "chrome"
getOperatingSystem(); // sample, "windows"
getPlatform(); // sample, "desktop"
fontUnitConverter (convertPixelsToRem, convertPixelsToEm) - source
A utility that converts pixels to rem/em units.
Dependencies: none
| Paramters | Type | Description |
|---|---|---|
| pixelValue | string (required) | Value to be converted into em/rem unitls |
| baseFontSize | string (optional) - default '16px' | root pixel value, set on the <html> or <body> tag |
Usage
// font-settings
import { convertPixelsToRem, convertPixelsToEm } from 'k2-react-utils';
// either
const fontSizes = {
f16: convertPixelsToRem('16px', '10px');
f20: convertPixelsToRem('20px', '10px');
};
// or for ems
const fontSizes = {
f16: convertPixelsToEm('16px');
f18: convertPixelsToEm('18px');
};
// Styled Component
import styled from 'styled-components';
import { fontSizes } from './fontSettings';
const MyComponent = styled`
font-size: ${fontSizes.f16}; // DOM output => font-size: 1.6rem;
`;
hostEnv - source
A util that returns an object denoting the current hostname and a boolean value, isLocal.
Dependencies: none
| Paramters | Type | Description |
|---|---|---|
| host | string (optional), default window.location.host
|
- |
Usage
import * as React from "react"; // standard TypeScript syntax
import { hostEnv } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
React.useEffect(() => {
window.fetch(getUrl());
}, []);
const getUrl = (): string => {
if (hostEnv.isLocal) {
return "http//dev.somesite.com/api/people";
} else if (hostEnv.host === "uat1.somesite.com") {
return "http//uat.somesite.com/api/people";
}
return "/api/people";
};
return <div />;
};Alternatives
- Consider using client-side environment variables configurable via an
.envfile.
convertXmlToJson - source
A function that converts xml into json.
Dependencies: xml-js
| Parameters | Type | Description |
|---|---|---|
| xmlNode | xml (required) | - |
Usage
import { convertXmlToJson } from "k2-react-utils";
const xmlNode = `<xml>
<title>Aerys</title>
</xml>`;
convertXmlToJson(xmlNode);
useBrowserStorage - source
A hook that performs getting, setting and clearing of values to localStorage and sessionStorage.
Dependencies: react, react-dom
| Parameters | Type | Description |
|---|---|---|
| storageType | 'LOCAL' | 'SESSION' (required) | context, point to localStorage, or sessionStorage |
| key | string | number | boolean (required) | property name to used in either local or session storage |
Usage
import * as React from "react"; // standard TypeScript syntax
import { useEffect } from "react";
import { useBrowserStorage } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
const [isUndead, setIsUndead, clearIsUndead] = useBrowserStorage<boolean>(
"SESSION",
"isUndead"
);
useEffect(() => {
setIsUndead(false);
() => {
clearIsUndead();
};
}, []);
return <div>Xhoan Daxos is Undead: {isUndead}</div>;
};
useDevice - source
A hook that identifies the device's current browser, operating system or platform (desktop or mobile).
Dependencies: react
Usage
import * as React from "react"; // standard TypeScript syntax
import { useDevice } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
const { browserName, operatingSystem, platform } = useDevice();
return (
<table>
<tbody>
<tr>
<td>Browser</td>
<td>{browserName}</td> // sample, "chrome"
</tr>
<tr>
<td>OS</td>
<td>{operatingSystem}</td> // sample, "windows"
</tr>
<tr>
<td>OS</td>
<td>{platform}</td> // sample, "desktop"
</tr>
</tbody>
</table>
);
};
useScroll - source
A hook that returns the y-position (integer) on scroll.
Dependencies: react, react-dom
Usage
import * as React from "react"; // standard TypeScript syntax
import { useScroll } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
const { verticalScrollPosition } = useScroll();
return <div>Vertical scroll position {verticalScrollPosition}</div>; // 0
};
useViewport - source
A hook that returns the current viewport's width, height and the document's scrollable height (as integers).
Dependencies: react, react-dom
Usage
import * as React from "react"; // standard TypeScript syntax
import { useViewport } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
const { viewportWidth, viewportHeight, documentHeight } = useViewport();
return (
<div>
width: {viewportWidth}, height: {viewportHeight}, documentHeight:{" "}
{documentHeight},
</div>
);
};Development
- Run
yarnon the root of the repository. - Run
yarn startto start the project. - Run
yarn test:watchto ammend tests.