Initial commit

Author: Vovan-VE

.gitattributes

@@ -0,0 +1 @@
+* text eol=lf

.gitignore

@@ -0,0 +1,8 @@
+/coverage/
+
+dist/
+node_modules/
+.DS_Store
+package-lock.json
+yarn.lock
+*.log

.husky/pre-commit

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npm test \
+  && npx lint-staged \
+  && npm run lint

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0 (DEV)
+
+- Initial release.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2022 Vovan-VE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,280 @@
+# `@cubux/react-utils`
+
+[![NPM latest](https://img.shields.io/npm/v/@cubux/react-utils.svg)](https://www.npmjs.com/package/@cubux/react-utils)
+
+Utility functions related to React.
+
+## Install
+
+```sh
+npm i @cubux/react-utils
+```
+
+## API
+
+### `deprecated()` function
+
+Wrap a component to emit deprecation warning.
+
+```ts
+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()`.
+
+```tsx
+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
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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.
+
+```tsx
+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.
+
+```ts
+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:
+
+```ts
+// You are using CRA `react-scripts`, so
+import { ReactComponent } from './file.svg';
+```
+
+Or writing such component manually:
+
+```tsx
+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`.
+
+```ts
+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.
+
+```tsx
+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.
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+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.
+
+```ts
+function svgRot90R(Orig: SvgFC): SvgFC
+```
+
+Uses `svgTransform()` internally with `'rotate(90deg)'` transform value.
+
+See also: `transform()`, `svgRot180()`.

examples/react-18/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
+    <title>Playground</title>
+  </head>
+
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./index.tsx"></script>
+  </body>
+</html>

examples/react-18/index.tsx

@@ -0,0 +1,35 @@
+// import 'react-app-polyfill/stable';
+import React, { FC } from 'react';
+import { createRoot } from 'react-dom/client';
+import { svgRot90L } from '@cubux/react-utils';
+import { SvgFC, svgRot90R } from '@cubux/react-utils/svg';
+
+const SvgIcon: SvgFC = (props) => (
+  <svg
+    {...props}
+    width={16}
+    height={16}
+    viewBox="0 0 16 16"
+    fill="currentColor"
+  >
+    <path d="M2,5 h12 v6 z" />
+  </svg>
+);
+
+const IconR1: SvgFC = svgRot90R(SvgIcon);
+const IconL1: SvgFC = svgRot90L(SvgIcon);
+
+const App: FC = () => {
+  return (
+    <div>
+      <h1>Foo bar</h1>
+      <div>
+        <IconL1 />
+        <SvgIcon />
+        <IconR1 />
+      </div>
+    </div>
+  );
+};
+
+createRoot(document.getElementById('root')!).render(<App />);