@dr.pogodin/react-utils 1.25.6 → 1.26.0

package/src/shared/utils/jest/index.tsx

@@ -0,0 +1,157 @@
+/* global expect, jest, document */
+/* eslint-disable import/no-extraneous-dependencies */
+
+import mockdate from 'mockdate';
+import { type ReactElement, type ReactNode } from 'react';
+import { type Root, createRoot } from 'react-dom/client';
+import TU, { act } from 'react-dom/test-utils';
+
+/* eslint-disable import/no-extraneous-dependencies */
+import Renderer from 'react-test-renderer';
+import { type ShallowRenderer, createRenderer } from 'react-test-renderer/shallow';
+/* eslint-enable import/no-extraneous-dependencies */
+
+/**
+ * An alias for [act(..)](https://reactjs.org/docs/test-utils.html#act)
+ * from `react-dom/test-utils`.
+ * @param {function} action
+ */
+export { act };
+
+export { default as getGlobal } from './global';
+
+declare global {
+  // eslint-disable-next-line no-var, vars-on-top
+  var IS_REACT_ACT_ENVIRONMENT: boolean | undefined;
+}
+
+global.IS_REACT_ACT_ENVIRONMENT = true;
+
+const originalProcessVersions = process.versions;
+
+/**
+ * Tricks **react-utils** into thinking the test is running within client-side
+ * (browser) environment.
+ */
+export function mockClientSide() {
+  Object.defineProperty(process, 'versions', { value: null });
+}
+
+/**
+ * Reverts the effect of {@link module:JU.mockClientSide mockClientSide(..)}.
+ */
+export function unmockClientSide() {
+  Object.defineProperty(process, 'versions', {
+    value: originalProcessVersions,
+    writable: false,
+  });
+}
+
+/**
+ * Generates a mock UUID, or better said it determenistically transforms given
+ * `seed` number into a UUID-formatted string.
+ * @param {number} seed
+ * @return {string}
+ */
+export function getMockUuid(seed = 0) {
+  const x = seed.toString(16).padStart(32, '0');
+  return `${x.slice(0, 8)}-${x.slice(8, 12)}-${x.slice(12, 16)}-${x.slice(16, 20)}-${x.slice(20)}`;
+}
+
+/**
+ * Advances mock timers, and mock date by the specified time.
+ * @param {number} time Time step [ms].
+ * @returns {Promise} Wait for this to "jump after" any async code which should
+ * be executed because of the mock time movement.
+ */
+export async function mockTimer(time: number) {
+  mockdate.set(time + Date.now());
+  jest.advanceTimersByTime(time);
+}
+
+export type MountedSceneT = HTMLElement & {
+  destroy: () => void;
+};
+
+/**
+ * Mounts `scene` to the DOM, and returns the root scene element.
+ * @param scene
+ * @return Created container DOM element with destroy() function
+ *  attached.
+ */
+export function mount(scene: ReactNode): MountedSceneT {
+  let root: Root;
+  const element = document.createElement('div');
+  document.body.appendChild(element);
+
+  const res: MountedSceneT = (element as unknown) as MountedSceneT;
+  res.destroy = () => {
+    act(() => root.unmount());
+    res.remove();
+  };
+
+  act(() => {
+    root = createRoot(res);
+    root.render(scene);
+  });
+  return res;
+}
+
+/* OLD STUFF BELOW THIS MARK */
+
+/**
+ * Renders provided ReactJS component into JSON representation of the component
+ * tree, using [`react-test-renderer`](https://www.npmjs.com/package/react-test-renderer).
+ * @param {object} component ReactJS component to render.
+ * @return {object} JSON representation of the rendered tree.
+ * @example
+ * import { JU } from '@dr.pogodin/react-utils';
+ * console.log(JU.render(<div>Example</div>));
+ */
+export function render(component: ReactElement) {
+  return Renderer.create(component).toJSON();
+}
+
+/**
+ * Generates a shallow render of given ReactJS component, using
+ * [react-test-renderer/shallow](https://reactjs.org/docs/shallow-renderer.html)
+ * and returns the result.
+ * @param {object} component ReactJS component to render.
+ * @return {object} JSON representation of the shallow component's render tree.
+ */
+export function shallowRender(component: ReactElement) {
+  const renderer: ShallowRenderer = createRenderer();
+  renderer.render(component);
+  return renderer.getRenderOutput();
+}
+
+/**
+ * Makes a shallow snapshot test of the given ReactJS component, and also
+ * returns JSON representation of the rendered component tree. Under the hood
+ * it uses {@link module:JU.shallowRender shallowRender(..)} to generate
+ * the render, then executes `expect(RENDER_RESULT).toMatchSnapshot()`,
+ * and finally returns the `RENDER_RESULT` to the caller.
+ * @param {object} component ReactJS component to render.
+ * @return {object} JSON representation of shallow render.
+ */
+export function shallowSnapshot(component: ReactElement) {
+  const res = shallowRender(component);
+  expect(res).toMatchSnapshot();
+  return res;
+}
+
+/**
+ * Makes snapshot test of the given ReactJS component, and also returns JSON
+ * representation of the rendered component tree. Under the hood, it uses
+ * {@link module:JU.render render(..)} to render it, then executes
+ * `expect(RENDER_RESULT).toMatchSnapshot()`, and then returns `RENDER_RESULT`.
+ * @param {object} component ReactJS component to render.
+ * @return {object} JSON render of the component.
+ */
+export function snapshot(component: ReactElement) {
+  const res = render(component);
+  expect(res).toMatchSnapshot();
+  return res;
+}
+
+export const simulate = TU.Simulate;

package/src/shared/utils/splitComponent.tsx

@@ -0,0 +1,255 @@
+/* eslint-disable react/jsx-props-no-spreading */
+/* global document */
+
+import PT from 'prop-types';
+
+import {
+  type ComponentType,
+  type ReactNode,
+  forwardRef,
+  lazy,
+  Suspense,
+  useInsertionEffect,
+} from 'react';
+
+import { Barrier } from '@dr.pogodin/js-utils';
+
+import { type ChunkGroupsT, getSsrContext } from './globalState';
+
+import {
+  IS_CLIENT_SIDE,
+  IS_SERVER_SIDE,
+  getBuildInfo,
+} from './isomorphy';
+
+// Note: At the client side we can get chunk groups immediately when loading
+// the module; at the server-side we only can get them within React render flow.
+// Thus, we set and use the following variable at the client-side, and then when
+// needed on the server side, we'll fetch it differently.
+let clientChunkGroups: ChunkGroupsT;
+
+if (IS_CLIENT_SIDE) {
+  // eslint-disable-next-line global-require
+  clientChunkGroups = require('client/getInj').default().CHUNK_GROUPS || {};
+}
+
+const refCounts: { [path: string]: number } = {};
+
+function getPublicPath() {
+  return getBuildInfo().publicPath;
+}
+
+/**
+ * Client-side only! Ensures the specified CSS stylesheet is loaded into
+ * the document; loads if it is missing; and does simple reference counting
+ * to facilitate future clean-up.
+ * @param name
+ * @param loadedSheets
+ * @param refCount
+ * @return
+ */
+function bookStyleSheet(
+  name: string,
+  loadedSheets: Set<string>,
+  refCount: boolean,
+): Promise<void> | undefined {
+  let res: Barrier<void> | undefined;
+  const path = `${getPublicPath()}/${name}`;
+  const fullPath = `${document.location.origin}${path}`;
+
+  if (!loadedSheets.has(fullPath)) {
+    let link = document.querySelector(`link[href="${path}"]`);
+
+    if (!link) {
+      link = document.createElement('link');
+      link.setAttribute('rel', 'stylesheet');
+      link.setAttribute('href', path);
+      document.head.appendChild(link);
+    }
+
+    res = new Barrier<void>();
+    link.addEventListener('load', () => res!.resolve());
+    link.addEventListener('error', () => res!.resolve());
+  }
+
+  if (refCount) {
+    const current = refCounts[path] || 0;
+    refCounts[path] = 1 + current;
+  }
+
+  return res;
+}
+
+/**
+ * Generates the set of URLs for currently loaded, linked stylesheets.
+ * @return
+ */
+function getLoadedStyleSheets(): Set<string> {
+  const res = new Set<string>();
+  const { styleSheets } = document;
+  for (let i = 0; i < styleSheets.length; ++i) {
+    const { href } = styleSheets[i];
+    if (href) res.add(href);
+  }
+  return res;
+}
+
+function assertChunkName(
+  chunkName: string,
+  chunkGroups: ChunkGroupsT,
+) {
+  if (chunkGroups[chunkName]) return;
+  throw Error(`Unknown chunk name "${chunkName}"`);
+}
+
+/**
+ * Client-side only! Ensures all CSS stylesheets required for the specified
+ * code chunk are loaded into the document; loads the missing ones; and does
+ * simple reference counting to facilitate future clean-up.
+ * @param chunkName Chunk name.
+ * @param refCount
+ * @return Resolves once all pending stylesheets, necessary for
+ *  the chunk, are either loaded, or failed to load.
+ */
+export function bookStyleSheets(
+  chunkName: string,
+  chunkGroups: ChunkGroupsT,
+  refCount: boolean,
+): Promise<void> {
+  const promises = [];
+  const assets = chunkGroups[chunkName];
+  const loadedSheets = getLoadedStyleSheets();
+
+  for (let i = 0; i < assets.length; ++i) {
+    const asset = assets[i];
+    if (asset.endsWith('.css')) {
+      const promise = bookStyleSheet(asset, loadedSheets, refCount);
+      if (promise) promises.push(promise);
+    }
+  }
+
+  return promises.length
+    ? Promise.allSettled(promises).then()
+    : Promise.resolve();
+}
+
+/**
+ * Client-side only! Frees from the document all CSS stylesheets that are
+ * required by the specified chunk, and have reference counter equal to one
+ * (for chunks with larger reference counter values, it just decrements
+ * the reference counter).
+ * @param {string} chunkName
+ */
+export function freeStyleSheets(
+  chunkName: string,
+  chunkGroups: ChunkGroupsT,
+) {
+  const assets = chunkGroups[chunkName];
+  for (let i = 0; i < assets.length; ++i) {
+    const asset = assets[i];
+    if (asset.endsWith('.css')) {
+      const path = `${getPublicPath()}/${asset}`;
+      if (--refCounts[path] <= 0) {
+        document.head.querySelector(`link[href="${path}"]`)!.remove();
+      }
+    }
+  }
+}
+
+// Holds the set of chunk names already used for splitComponent() calls.
+const usedChunkNames = new Set();
+
+type ComponentOrModule<PropsT> = ComponentType<PropsT> | {
+  default: ComponentType<PropsT>,
+};
+
+/**
+ * Given an async component retrieval function `getComponent()` it creates
+ * a special "code split" component, which uses <Suspense> to asynchronously
+ * load on demand the code required by `getComponent()`.
+ * @param options
+ * @param options.chunkName
+ * @param {function} options.getComponent
+ * @param {React.Element} [options.placeholder]
+ * @return {React.ElementType}
+ */
+export default function splitComponent<
+  ComponentPropsT extends { children?: ReactNode },
+>({
+  chunkName,
+  getComponent,
+  placeholder,
+}: {
+  chunkName: string;
+  getComponent: () => Promise<ComponentOrModule<ComponentPropsT>>,
+  placeholder?: ReactNode,
+}) {
+  // On the client side we can check right away if the chunk name is known.
+  if (IS_CLIENT_SIDE) assertChunkName(chunkName, clientChunkGroups);
+
+  // The correct usage of splitComponent() assumes a single call per chunk.
+  if (usedChunkNames.has(chunkName)) {
+    throw Error(`Repeated splitComponent() call for the chunk "${chunkName}"`);
+  } else usedChunkNames.add(chunkName);
+
+  const LazyComponent = lazy(async () => {
+    const resolved = await getComponent();
+    const Component = 'default' in resolved ? resolved.default : resolved;
+
+    // This pre-loads necessary stylesheets prior to the first mount of
+    // the component (the lazy load function is executed by React one at
+    // the frist mount).
+    if (IS_CLIENT_SIDE) {
+      await bookStyleSheets(chunkName, clientChunkGroups, false);
+    }
+
+    const Wrapper = forwardRef((
+      { children, ...rest }: ComponentPropsT,
+      ref,
+    ) => {
+      // On the server side we'll assert the chunk name here,
+      // and also push it to the SSR chunks array.
+      if (IS_SERVER_SIDE) {
+        const { chunkGroups, chunks } = getSsrContext()!;
+        assertChunkName(chunkName, chunkGroups);
+        if (!chunks.includes(chunkName)) chunks.push(chunkName);
+      }
+
+      // This takes care about stylesheets management every time an instance of
+      // this component is mounted / unmounted.
+      useInsertionEffect(() => {
+        bookStyleSheets(chunkName, clientChunkGroups, true);
+        return () => freeStyleSheets(chunkName, clientChunkGroups);
+      }, []);
+
+      return (
+        <Component ref={ref} {...rest as ComponentPropsT}>
+          {children}
+        </Component>
+      );
+    });
+
+    return { default: Wrapper };
+  });
+
+  const CodeSplit: React.FunctionComponent<ComponentPropsT> = ({
+    children,
+    ...rest
+  }: ComponentPropsT) => (
+    <Suspense fallback={placeholder}>
+      <LazyComponent {...rest as Parameters<typeof LazyComponent>[0]}>
+        {children}
+      </LazyComponent>
+    </Suspense>
+  );
+
+  CodeSplit.propTypes = {
+    children: PT.node,
+  } as React.WeakValidationMap<ComponentPropsT>;
+
+  CodeSplit.defaultProps = {
+    children: undefined,
+  } as Partial<ComponentPropsT>;
+
+  return CodeSplit;
+}

package/src/shared/utils/time.ts

@@ -0,0 +1,118 @@
+/* global document */
+
+import Cookie from 'cookie';
+import dayjs from 'dayjs';
+import { useEffect } from 'react';
+
+import {
+  DAY_MS,
+  HOUR_MS,
+  MIN_MS,
+  SEC_MS,
+  YEAR_MS,
+  timer,
+} from '@dr.pogodin/js-utils';
+
+import { type ForceT, useGlobalState } from '@dr.pogodin/react-global-state';
+
+import { getSsrContext } from './globalState';
+
+/**
+ * This react hook wraps Date.now() function in a SSR friendly way,
+ * ensuring that all calls to useCurrent() within the same render return
+ * exactly the same time (which is retrieved from Date.now() first, and
+ * then stored in the global state to be reused in all other calls), which
+ * is also passed and used in the first client side render, and then updated
+ * with a finite precision to avoid infinite re-rendering loops.
+ * @param [options] Optional settings.
+ * @param [options.globalStatePath="currentTime"] Global state path
+ *  to keep the current time value.
+ * @param [options.precision= 5 * time.SEC_MS] Current time precision.
+ *  The hook won't update the current time stored in the global state unless it
+ *  is different from Date.now() result by this number (in milliseconds).
+ *  Default to 5 seconds.
+ * @param [options.autorefresh=false] Set `true` to automatically
+ *  refresh time stored in the global state with the given `precision` (and
+ *  thus automatically re-rendering components dependent on this hook, or
+ *  the global state with the period equal to the `precision`.
+ * @return Unix timestamp in milliseconds.
+ */
+// TODO: Should we request the state type as generic parameter, to be able
+// to verify the give globalStatePath is correct?
+export function useCurrent({
+  autorefresh = false,
+  globalStatePath = 'currentTime',
+  precision = 5 * SEC_MS,
+} = {}) {
+  const [now, setter] = useGlobalState<ForceT, number>(globalStatePath, Date.now);
+  useEffect(() => {
+    let timerId: NodeJS.Timeout;
+    const update = () => {
+      setter((old) => {
+        const neu = Date.now();
+        return Math.abs(neu - old) > precision ? neu : old;
+      });
+      if (autorefresh) timerId = setTimeout(update, precision);
+    };
+    update();
+    return () => {
+      if (timerId) clearTimeout(timerId);
+    };
+  }, [autorefresh, precision, setter]);
+  return now;
+}
+
+/**
+ * Wraps the standard Date.getTimezoneOffset() method in a SSR-friendly way.
+ * This hook retrieves the offset value at the client side and uses a cookie
+ * to pass it to the server in subsequent requests from that user. At the server
+ * side the value from cookie is used in renders and passed back to the client
+ * via the global state. Prior to the value being known (in the very first
+ * request from the user, when the cookie is still missing), zero value is used
+ * as the default value.
+ *
+ * @param {object} [options] Optional settings.
+ * @param {string} [options.cookieName="timezoneOffset"] Optional. The name of
+ *  cookie to use to store the timezone offset. Defaults "timezoneOffset". Set
+ *  to a falsy value to forbid using cookies altogether (in that case the hook
+ *  will always return zero value at the server-side, and in the first render
+ *  at the client-side).
+ * @param {string} [options.timezoneOffset="timezoneOffset"] Optional.
+ *  The global state path to store the offset. Defaults "timezoneOffset".
+ * @return {number} Timezone offset.
+ */
+// TODO: Should we request the state type as generic parameter, to be able
+// to verify the give globalStatePath is correct?
+export function useTimezoneOffset({
+  cookieName = 'timezoneOffset',
+  globalStatePath = 'timezoneOffset',
+} = {}) {
+  const ssrContext = getSsrContext(false);
+  const [offset, setOffset] = useGlobalState<ForceT, number>(globalStatePath, () => {
+    const value = cookieName && ssrContext?.req?.cookies?.[cookieName];
+    return value ? parseInt(value, 10) : 0;
+  });
+  useEffect(() => {
+    const date = new Date();
+    const value = date.getTimezoneOffset();
+    setOffset(value);
+    if (cookieName) {
+      document.cookie = Cookie.serialize(cookieName, value.toString(), { path: '/' });
+    }
+  }, [cookieName, setOffset]);
+  return offset;
+}
+
+const time = {
+  DAY_MS,
+  HOUR_MS,
+  MIN_MS,
+  SEC_MS,
+  YEAR_MS,
+  now: Date.now,
+  timer,
+  useCurrent,
+  useTimezoneOffset,
+};
+
+export default Object.assign(dayjs, time);

package/src/shared/utils/webpack.ts

@@ -0,0 +1,45 @@
+import { IS_CLIENT_SIDE } from './isomorphy';
+
+/**
+ * Requires the specified module without including it into the bundle during
+ * Webpack build.
+ * @param modulePath
+ * @param [basePath]
+ * @return Required module.
+ */
+export function requireWeak(
+  modulePath: string,
+  basePath?: string,
+): NodeJS.Module | null {
+  if (IS_CLIENT_SIDE) return null;
+
+  try {
+    /* eslint-disable no-eval */
+    const { resolve } = eval('require')('path');
+    const path = basePath ? resolve(basePath, modulePath) : modulePath;
+    const { default: def, ...named } = eval('require')(path);
+    /* eslint-enable no-eval */
+
+    if (!def) return named;
+
+    Object.entries(named).forEach(([key, value]) => {
+      if (def[key]) throw Error('Conflict between default and named exports');
+      def[key] = value;
+    });
+    return def;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolves specified module path with help of Babel's module resolver.
+ * Yes, the function itself just returns its argument to the caller, but Babel
+ * is configured to resolve the first argument of resolveWeak(..) function, thus
+ * the result will be the resolved path.
+ * @param {string} modulePath
+ * @return {string} Absolute or relative path to the module.
+ */
+export function resolveWeak(modulePath: string): string {
+  return modulePath;
+}

package/src/styles/_global/reset.css

@@ -0,0 +1,52 @@
+/* Eric Meyer's "Reset CSS" 2.0 */
+
+/* http://meyerweb.com/eric/tools/css/reset/
+   v2.0 | 20110126
+   License: none (public domain)
+*/
+
+/* Having all selectors at individual lines is unreadable in the case of this
+ * style reset sheet. */
+/* stylelint-disable selector-list-comma-newline-after */
+a, abbr, acronym, address, applet, article, aside, audio, b, big, blockquote,
+body, canvas, caption, center, cite, code, dd, del, details, dfn, div, dl, dt,
+em, embed, fieldset, figcaption, figure, footer, form, h1, h2, h3, h4, h5, h6,
+header, hgroup, html, i, iframe, img, ins, kbd, label, legend, li, mark,  menu,
+nav, object, ol, output, p, pre, q, ruby, s, samp, section, small, span,
+strike, strong,sub, summary, sup, table, tbody, td, tfoot, th, thead, time, tr,
+tt, u, ul, var, video {
+  margin: 0;
+  padding: 0;
+  border: 0;
+  font: inherit;
+  font-size: 100%;
+  vertical-align: baseline;
+}
+
+/* HTML5 display-role reset for older browsers */
+article, aside, details, figcaption, figure, footer, header, hgroup, menu, nav,
+section {
+  display: block;
+}
+
+body {
+  line-height: 1;
+}
+
+ol, ul {
+  list-style: none;
+}
+
+blockquote, q {
+  quotes: none;
+}
+
+blockquote::before, blockquote::after, q::before, q::after {
+  content: "";
+  content: none;
+}
+
+table {
+  border-collapse: collapse;
+  border-spacing: 0;
+}

package/src/styles/global.scss

@@ -0,0 +1,11 @@
+/* Global styles. */
+
+@import "_global/reset";
+
+body {
+  text-rendering: auto;
+}
+
+* {
+  box-sizing: border-box;
+}

package/tsconfig.configs.json

@@ -0,0 +1,18 @@
+// TS configuration for configs pre-building from TS sources.
+
+{
+  "extends": "@tsconfig/recommended",
+  "include": [
+    "config-ts-src",
+  ],
+  "compilerOptions": {
+    "declaration": true,
+    "jsx": "react-jsx",
+    "rootDir": "config-ts-src",
+    "outDir": "config",
+    "paths": {
+      "*": ["./src/shared/*", "./src/*", "./*"]
+    },
+    "strict": true
+  }
+}

package/tsconfig.json

@@ -0,0 +1,27 @@
+// TS config for ESLint, editor plugins, and other tools that look-up and use
+// the default tsconfig.json file.
+{
+  // Note: Full relative paths, as some tools don't support Node module
+  // resolution mechanics.
+  "extends": "./node_modules/@tsconfig/recommended/tsconfig.json",
+
+  "compilerOptions": {
+    "jsx": "react-jsx",
+
+    // BEWARE: Different settings are likely to transform dynamic import()
+    // statements in the code, thus breaking Webpack's code splitting.
+    // See: https://davidea.st/articles/webpack-typescript-code-split-wont-work
+    "module": "ESNext",
+    "moduleResolution": "Node",
+
+    "paths": {
+      "*": ["./src/shared/*", "./src/*", "./*"]
+    },
+    "rootDirs": [".", "build/types-scss"],
+    "strict": true,
+
+    // This ensures TypeScript does not remove unused imports, which may cause
+    // troubles when we rely on some side-effects from imported modules.
+    "verbatimModuleSyntax": true,
+  }
+}