@cubux/react-utils

Utility functions related to React.

Install

npm i @cubux/react-utils

API

deprecated() function

Wrap a component to emit deprecation warning.

function deprecated<T extends React.ComponentType<any>>(
  Origin: T,
  options?: Options,
): React.ComponentType<React.ComponentProps<T>>

The options object can have the following properties:

property	type	default	description
comment	string	—	Extra comment to emit in console warning. Can also be obtained later with getDevInfo().
tag	string	—	A tag property to bypass to setDevInfo(). Can be obtained later with getDevInfo().
withRef	boolean	false	Whether to use React.forwardRef(), so ref React attribute can be used to refer to underlying element of the Origin component.

A getDevInfo() can be used in development env to get details about deprecation. This can be used on "dev only" internal pages.

Notice: Component's (static) properties like propTypes, defaultProps, etc. are not touched because it was not necessary yet.

Does nothing in production env and returns origin component as is.

See also: DevInfo, getDevInfo().

import { deprecated, getDevInfo } from '@cubux/react-utils';

function OldComponentOrigin() {
  return <div>...</div>;
}

const OldComponent = deprecated(OldComponentOrigin, {
  comment: 'Use `NewComponent` instead.',
});

if (process.env.NODE_ENV === 'development') {
  console.log(getDevInfo(OldComponent));
}

DevInfo type

interface DevInfo {
  type: string;
  tag?: string;
  Orig?: React.ComponentType<any>;
  comment?: string;
}

See also: getDevInfo(), setDevInfo().

getDevInfo() function

Get DevInfo for the given generated component.

function getDevInfo<T extends DevInfo = DevInfo>(
  subject: ComponentType<any>,
): T | undefined

Does nothing in production env and always returns undefined.

An example can be found in deprecated().

See also: setDevInfo().

setDevInfo() function

Set given DevInfo for the given component.

function setDevInfo<T extends DevInfo>(
  subject: ComponentType<any>,
  info: T,
): void

Does nothing in production env.

See also: getDevInfo().

isElementOf() function

Check whether the given element is an element of the given component.

function isElementOf<T extends React.ElementType>(
  element: any,
  component: T,
): element is React.ReactElement<React.ComponentPropsWithoutRef<T>, T>

NOTICE: The react-is peer dependency must be installed to use this function.

Enhanced version of isElement() from react-is package to use as Type Guard function.

import { FC, PropsWithChildren } from 'react';

interface FooProps {
  x: number;
  y?: string;
}
const Foo: FC<FooProps> = () => <div />;

const element = <Foo x={42} y="foo bar">baz</Foo>;
if (isElementOf(element, Foo)) {
  const { props } = element;
  // `props` type is `PropsWithChildren<FooProps>`
  console.log(props);
  // { x: 42, y: "foo bar", children: "baz" }
}

console.log(isElementOf(element, 'div'));
// => `false`
console.log(isElementOf(<div/>, Foo));
// => `false`
console.log(isElementOf(<div/>, 'a'));
// => `false`
console.log(isElementOf(<div/>, 'div'));
// => `true`

SvgFC type

A React.FunctionComponent component receiving properties for <svg/> element.

type SvgFC = React.FC<React.SVGProps<SVGSVGElement>>

A component of this signature can be given for example with svgo package, which is used internally in CRA react-scripts for SVG files imports like following:

// You are using CRA `react-scripts`, so
import { ReactComponent } from './file.svg';

Or writing such component manually:

const MySvg: SvgFC = (props) => (
  <svg
    {...props}
    width={16}
    height={16}
    viewBox="0 0 16 16"
    fill="currentColor"
  >
    <path d="M2,5 h12 v6 z" />
  </svg>
);

svgTransform function

Creates new SvgFC component by reusing origin SvgFC applying a CSS transform.

type CssTransform = string;
type CalcTransform = (prev: CssTransform | undefined) => CssTransform;

function svgTransform(
  Orig: SvgFC,
  transform: CssTransform | CalcTransform,
): SvgFC

A getDevInfo() can be used in development env to get details about underlying transform. This can be used on "dev only" internal pages.

const MySvg: SvgFC = (props) => (
  <svg
    {...props}
    width={16}
    height={16}
    viewBox="0 0 16 16"
    fill="currentColor"
  >
    <path d="M2,5 h12 v6 z" />
  </svg>
);

const MySvg1 = svgTransform(MySvg, 'scaleX(0.75), rotate(45deg)');

See also: getDevInfo().

svgFlipH() function

Creates new SvgFC applying horizontal flip to origin SvgFC with CSS transform.

function svgFlipH(Orig: SvgFC): SvgFC

Uses svgTransform() internally with 'scaleX(-1)' transform value.

See also: transform(), svgFlipV(), svgRot180().

svgFlipV() function

Creates new SvgFC applying vertical flip to origin SvgFC with CSS transform.

function svgFlipV(Orig: SvgFC): SvgFC

Uses svgTransform() internally with 'scaleY(-1)' transform value.

See also: transform(), svgFlipH(), svgRot180().

svgRot180() function

Creates new SvgFC applying rotation 180 deg to origin SvgFC with CSS transform.

function svgRot180(Orig: SvgFC): SvgFC

Uses svgTransform() internally with 'rotate(180deg)' transform value.

See also: transform(), svgFlipH(), svgFlipV().

svgRot90L() function

Creates new SvgFC applying rotation 90 deg anti-clockwise to origin SvgFC with CSS transform.

function svgRot90L(Orig: SvgFC): SvgFC

Uses svgTransform() internally with 'rotate(-90deg)' transform value.

See also: transform(), svgRot180().

svgRot90R() function

Creates new SvgFC applying rotation 90 deg clockwise to origin SvgFC with CSS transform.

function svgRot90R(Orig: SvgFC): SvgFC

Uses svgTransform() internally with 'rotate(90deg)' transform value.

See also: transform(), svgRot180().