k2-react-utils v0.15.6

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
• Documentation
• Development

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

• react
• react-dom

Note: react@^16.8.0 would be required when using hook utils.

optionalDependencies

• react-redux
• xml-js

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

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

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-components is 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.0 comes the useSelector hook which with less effort connect to your redux store.
• The @connect util 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

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

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 .env file.

convertXmlToJson - source

A function that converts xml into json.

Dependencies: xml-js

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

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 yarn on the root of the repository.
• Run yarn start to start the project.
• Run yarn test:watch to ammend tests.