Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kareemkibue/k2-react-utils
A collection of standalone ES6 ReactJS utilities and hooks, written in TypeScript and transpiled to and bundled in ES5
https://github.com/kareemkibue/k2-react-utils
Last synced: 18 days ago
JSON representation
A collection of standalone ES6 ReactJS utilities and hooks, written in TypeScript and transpiled to and bundled in ES5
- Host: GitHub
- URL: https://github.com/kareemkibue/k2-react-utils
- Owner: kareemkibue
- License: mit
- Created: 2017-12-19T08:16:12.000Z (almost 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-07T04:25:14.000Z (almost 2 years ago)
- Last Synced: 2024-04-30T00:46:33.269Z (7 months ago)
- Language: TypeScript
- Homepage:
- Size: 1.68 MB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# k2-react-utils
[](https://www.npmjs.com/package/k2-react-utils)
[](https://www.npmjs.com/package/k2-react-utils)
[](https://www.npmjs.com/package/k2-react-utils)
[](https://github.com/kareemkibue/k2-react-utils/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)
[](https://github.com/kareemkibue/k2-react-utils/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc)
[](https://travis-ci.org/kareemkibue/k2-react-utils)
[](https://coveralls.io/github/kareemkibue/k2-react-utils?branch=master)
[](https://github.com/kareemkibue/k2-react-utils/blob/master/LICENSE)
A collection of standalone ES6 ReactJS utilities and hooks, written in TypeScript and transpiled to and bundled in ES5.
## Table of Contents
- [Setup](#setup)
- [Documentation](#documentation)
- [Development](#development)
## Setup
This ES5 module is distributed via [npm](https://www.npmjs.com/package/k2-react-utils) 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`](https://github.com/facebook/react)
- [`react-dom`](https://github.com/facebook/react/tree/master/packages/react-dom)
**Note:** `react@^16.8.0` would be required when using hook utils.
### `optionalDependencies`
- [`react-redux`](https://github.com/reduxjs/react-redux)
- [`xml-js`](https://github.com/nashwaan/xml-js)
Type definitions come bundled in.
## Documentation
`k2-react-utils` barrels (re-exports) the following utils and hooks as named exports:
### `` - [source](https://github.com/kareemkibue/k2-react-utils/blob/master/src/Content.tsx)
A component that performs HTML sanitization.
**Dependencies:** `react`, `react-dom`
| Props | Type | Description |
| ----- | ----------------- | ------------------------------------------- |
| text | string (required) | Returns a DOM node with a `` wrapper |
#### Usage
```tsx
import * as React from "react"; // standard TypeScript syntax
import { Content } from "k2-react-utils";
const Post: React.FunctionComponent<{}> = () => {
const stringifiedMarkup: string =
"
A Lion from Lannisport, and the sheep from the North
";
return ; // returns a DOM node
};
```
---
### `classify` - [source](https://github.com/kareemkibue/k2-react-utils/blob/master/src/classify.ts)
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
```tsx
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
;
};
```
_Alternatives_
- This util would be helpful when to working imperively with CSS classes, example when authoring libraries. [`styled-components`](https://www.styled-components.com/) is a much preferred alternative when styling React components.
---
### `connect` - [source](https://github.com/kareemkibue/k2-react-utils/blob/master/src/connect.ts)
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
```tsx
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{
render(){
const {locale}=this.props;
return
{locale.region};
}
}
```
_Alternatives_
- With [`[email protected]`](https://www.npmjs.com/package/react-redux) comes the [`useSelector`](https://react-redux.js.org/next/api/hooks#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](https://github.com/kareemkibue/k2-react-utils/blob/master/src/device.ts)
A service that identifies the device's current browser, operating system or platform (desktop or mobile) via three getters; `getBrowserName`, `getOperatingSystem`, `getPlatform`.
#### Usage
```ts
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](https://github.com/kareemkibue/k2-react-utils/blob/master/src/fontUnitConverter.tsx)
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 `` or `` tag |
#### Usage
```ts
// 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](https://github.com/kareemkibue/k2-react-utils/blob/master/src/hostEnv.ts)
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
```tsx
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
;
};
```
_Alternatives_
- Consider using client-side environment variables [configurable](https://medium.com/@trekinbami/using-environment-variables-in-react-6b0a99d83cf5) via an `.env` file.
---
### `convertXmlToJson` - [source](https://github.com/kareemkibue/k2-react-utils/blob/master/src/parser.ts)
A function that converts xml into json.
**Dependencies:** [xml-js](https://github.com/nashwaan/xml-js)
| Parameters | Type | Description |
| ---------- | -------------- | ----------- |
| xmlNode | xml (required) | - |
#### Usage
```ts
import { convertXmlToJson } from "k2-react-utils";
const xmlNode = `
Aerys
`;
convertXmlToJson(xmlNode);
```
---
### `useBrowserStorage` - [source](https://github.com/kareemkibue/k2-react-utils/blob/master/src/useBrowserStorage.ts)
A hook that performs getting, setting and clearing of values to [localStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) and [sessionStorage](https://developer.mozilla.org/en-US/docs/Web/API/Window/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
```tsx
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(
"SESSION",
"isUndead"
);
useEffect(() => {
setIsUndead(false);
() => {
clearIsUndead();
};
}, []);
return
Xhoan Daxos is Undead: {isUndead};
};
```
---
### `useDevice` - [source](https://github.com/kareemkibue/k2-react-utils/blob/master/src/useDevice.ts)
A hook that identifies the device's current browser, operating system or platform (desktop or mobile).
**Dependencies:** `react`
#### Usage
```tsx
import * as React from "react"; // standard TypeScript syntax
import { useDevice } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
const { browserName, operatingSystem, platform } = useDevice();
return (
Browser
{browserName} // sample, "chrome"
OS
{operatingSystem} // sample, "windows"
OS
{platform} // sample, "desktop"
);
};
```
---
### `useScroll` - [source](https://github.com/kareemkibue/k2-react-utils/blob/master/src/useScroll.ts)
A hook that returns the y-position (integer) on scroll.
**Dependencies:** `react`, `react-dom`
#### Usage
```tsx
import * as React from "react"; // standard TypeScript syntax
import { useScroll } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
const { verticalScrollPosition } = useScroll();
return
Vertical scroll position {verticalScrollPosition}; // 0
};
```
---
### `useViewport` - [source](https://github.com/kareemkibue/k2-react-utils/blob/master/src/useViewport.ts)
A hook that returns the current viewport's width, height and the document's scrollable height (as integers).
**Dependencies:** `react`, `react-dom`
#### Usage
```tsx
import * as React from "react"; // standard TypeScript syntax
import { useViewport } from "k2-react-utils";
const MyComponent: React.FunctionComponent<{}> = () => {
const { viewportWidth, viewportHeight, documentHeight } = useViewport();
return (
width: {viewportWidth}, height: {viewportHeight}, documentHeight:{" "}
{documentHeight},
);
};
```
---
## Development
- Run `yarn` on the root of the repository.
- Run `yarn start` to start the project.
- Run `yarn test:watch` to ammend tests.