@dr.pogodin/react-utils 1.26.0 → 1.26.2

package/build/types-code/shared/components/Throbber/index.d.ts

@@ -1,6 +1,7 @@
 import { type Theme } from '@dr.pogodin/react-themes';
 type PropsT = {
     theme: Theme & {
+        bouncing?: string;
         container?: string;
         circle?: string;
     };

package/config/babel/node-ssr.d.ts

@@ -0,0 +1,17 @@
+import { type BabelCompilerI, type ConfigT, type OptionsT as WebpackConfigOptionsT } from './webpack';
+type OptionsT = WebpackConfigOptionsT & {
+    baseAssetsOutputPath?: string;
+};
+/**
+ * Generates Babel config for NodeJS compilation and server-side  execution.
+ * @param babel Babel compiler instance.
+ * @param [ops] Preset options. It supports all options accepted by
+ *  the underlying {@link module:babel/webpack preset for Webpack}, but it
+ *  overrides `targets` option by `current node` value, and also accepts
+ *  the following additional options:
+ * @param [ops.baseAssetsOutputPath] Path prefix for emitted image
+ *  assets.
+ * @return Generated config.
+ */
+export default function getConfig(babel: BabelCompilerI, ops?: OptionsT): ConfigT;
+export {};

package/config/babel/node-ssr.js

@@ -0,0 +1,91 @@
+"use strict";
+/* eslint-disable import/no-extraneous-dependencies */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const lodash_1 = require("lodash");
+const webpack_1 = __importStar(require("./webpack"));
+/**
+ * Creates a new base config.
+ * @param {object} babel Babel compiler.
+ * @param {object} [options] It supports all options of
+ *  {@link module:babel/webpack.getPreset babel/webpack's getPreset()},
+ *  but it overrides `targets` option with `current node` value, and further
+ *  accepts the following:
+ * @param {string} [options.baseAssetsOutputPath] Path prefix for emitted
+ *  image assets.
+ * @return {object} Created config object.
+ * @ignore
+ */
+function newBase(babel, options = {}) {
+    const config = (0, webpack_1.default)(babel, Object.assign(Object.assign({}, options), { targets: 'current node' }));
+    const baseAssetsOutputPath = options.baseAssetsOutputPath || '';
+    config.plugins.push(['@dr.pogodin/transform-assets', {
+            extensions: ['gif', 'jpeg', 'jpg', 'png'],
+            name: `${baseAssetsOutputPath}/images/[md4:hash:20].[ext]`,
+        }]);
+    const moduleResolverPluginOps = (config.plugins.find((x) => x[0] === 'module-resolver'))[1];
+    moduleResolverPluginOps.transformFunctions = [
+        'requireWeak',
+        'resolveWeak',
+        'webpack.requireWeak',
+        'webpack.resolveWeak',
+    ];
+    if (babel.env() === webpack_1.ENVIRONMENTS.DEV) {
+        (0, lodash_1.pull)(config.plugins, 'react-refresh/babel');
+    }
+    return config;
+}
+/**
+ * Updates given `config` with styling ((S)CSS-related) setup.
+ *
+ * **Beware:** It mutates `config`.
+ *
+ * @param {object} config
+ * @return {object} Returns mutated config for chaining.
+ * @ignore
+ */
+function addStyling(config) {
+    const cssModulesOps = config.plugins.find(([name]) => name === '@dr.pogodin/react-css-modules')[1];
+    cssModulesOps.replaceImport = true;
+    return config;
+}
+/**
+ * Generates Babel config for NodeJS compilation and server-side  execution.
+ * @param babel Babel compiler instance.
+ * @param [ops] Preset options. It supports all options accepted by
+ *  the underlying {@link module:babel/webpack preset for Webpack}, but it
+ *  overrides `targets` option by `current node` value, and also accepts
+ *  the following additional options:
+ * @param [ops.baseAssetsOutputPath] Path prefix for emitted image
+ *  assets.
+ * @return Generated config.
+ */
+function getConfig(babel, ops = {}) {
+    const config = newBase(babel, ops);
+    if (!ops.noStyling)
+        addStyling(config);
+    return config;
+}
+exports.default = getConfig;

package/config/babel/webpack.d.ts

@@ -0,0 +1,40 @@
+export interface BabelCompilerI {
+    env: () => string;
+}
+/**
+ * Supported Babel environments.
+ */
+export declare enum ENVIRONMENTS {
+    DEV = "development",
+    PROD = "production",
+    TEST = "test"
+}
+export interface PresetOrPluginOptionsI {
+}
+type PresetOrPluginT = string | [string, PresetOrPluginOptionsI];
+export type ConfigT = {
+    presets: PresetOrPluginT[];
+    plugins: PresetOrPluginT[];
+};
+export type OptionsT = {
+    noRR?: boolean;
+    noStyling?: boolean;
+    targets?: string | string[] | {
+        [key: string]: string;
+    };
+    typescript?: boolean;
+};
+/**
+ * Generates Babel preset for Webpack.
+ * @param babel Babel compiler.
+ * @param [ops] Preset options.
+ * @param [ops.noRR] If truthy `react-refresh/babel` plugin is not
+ *  included into config, no matter the environment.
+ * @param [ops.noStyling] If truthy all setup related to styling
+ *  ((S)CSS processing) will be skipped.
+ * @param [ops.targets=defaults] Targets for
+ *  `@babel/preset-env`.
+ * @return Generated config.
+ */
+export default function getPreset(babel: BabelCompilerI, ops?: OptionsT): ConfigT;
+export {};

package/config/babel/webpack.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENVIRONMENTS = void 0;
+const { generateScopedNameFactory, } = require('@dr.pogodin/babel-plugin-react-css-modules/utils');
+const generateScopedNameDev = generateScopedNameFactory('[package]___[path][name]___[local]___[hash:base64:6]');
+const generateScopedNameProd = generateScopedNameFactory('[hash:base64:6]');
+/**
+ * Supported Babel environments.
+ */
+var ENVIRONMENTS;
+(function (ENVIRONMENTS) {
+    ENVIRONMENTS["DEV"] = "development";
+    ENVIRONMENTS["PROD"] = "production";
+    ENVIRONMENTS["TEST"] = "test";
+})(ENVIRONMENTS || (exports.ENVIRONMENTS = ENVIRONMENTS = {}));
+/**
+ * Creates a new base config.
+ * @param [options] Base config options.
+ * @return Generated config.
+ */
+function newBaseConfig(options) {
+    return {
+        presets: [
+            // Chrome 69 is the browser for Android API 28.
+            ['@babel/env', { targets: options.targets || 'defaults or chrome >= 69' }],
+            // TODO: Starting from Babel 8, "automatic" will be the default runtime,
+            // thus once upgraded to Babel 8, runtime should be removed from
+            // @babel/react options below.
+            ['@babel/react', { runtime: 'automatic' }],
+            '@dr.pogodin/babel-preset-svgr',
+        ],
+        plugins: [
+            ['module-resolver', {
+                    extensions: ['.js', '.jsx', '.ts', '.tsx'],
+                    root: [
+                        './src/shared',
+                        './src',
+                    ],
+                }],
+            '@babel/transform-runtime',
+        ],
+    };
+}
+/**
+ * Updates given `config` with styling ((S)CSS-related) setup.
+ *
+ * **Beware:** It mutates `config`.
+ *
+ * @param {object} config
+ * @param {string} env Target environment: `development` or `production`.
+ * @return {object} Returns mutated config for chaining.
+ * @ignore
+ */
+function addStyling(config, env) {
+    const cssModulesOps = {
+        autoResolveMultipleImports: true,
+        filetypes: {
+            '.scss': { syntax: 'postcss-scss' },
+        },
+    };
+    config.plugins.push(['@dr.pogodin/react-css-modules', cssModulesOps]);
+    switch (env) {
+        case ENVIRONMENTS.DEV:
+        case ENVIRONMENTS.TEST:
+            cssModulesOps.generateScopedName = generateScopedNameDev;
+            break;
+        case ENVIRONMENTS.PROD:
+            cssModulesOps.generateScopedName = generateScopedNameProd;
+            break;
+        default:
+    }
+    return config;
+}
+/**
+ * Generates Babel preset for Webpack.
+ * @param babel Babel compiler.
+ * @param [ops] Preset options.
+ * @param [ops.noRR] If truthy `react-refresh/babel` plugin is not
+ *  included into config, no matter the environment.
+ * @param [ops.noStyling] If truthy all setup related to styling
+ *  ((S)CSS processing) will be skipped.
+ * @param [ops.targets=defaults] Targets for
+ *  `@babel/preset-env`.
+ * @return Generated config.
+ */
+function getPreset(babel, ops = {}) {
+    const env = babel.env();
+    const res = newBaseConfig(ops);
+    if (!ops.noStyling)
+        addStyling(res, env);
+    if (env === ENVIRONMENTS.DEV && !ops.noRR) {
+        res.plugins.push('react-refresh/babel');
+    }
+    // Conditional to not require non-TypeScript projects to install TypeScript-
+    // specific dependencies for build process.
+    if (ops.typescript) {
+        res.presets.push(['@babel/typescript', {
+                // This ensures TypeScript compilation does not remove "unused" imports,
+                // as in most cases it considers assets (e.g. stylesheet) imports as
+                // unused, while other steps of our build process rely on them
+                // (e.g. @dr.pogodin/react-css-modules plugin).
+                onlyRemoveTypeImports: true,
+            }]);
+    }
+    return res;
+}
+exports.default = getPreset;

package/config/webpack/app-base.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @category Configs
+ * @module webpack/app-base
+ * @desc
+ * Base [Webpack](https://webpack.js.org/) configuration for apps.
+ */
+/// <reference types="node" />
+import nodeFs from 'fs';
+import { type Configuration } from 'webpack';
+export type BuildInfoT = {
+    key: string;
+    publicPath: string;
+    timestamp: string;
+    useServiceWorker: boolean;
+};
+export type OptionsT = {
+    babelEnv: string;
+    babelLoaderOptions?: object;
+    context: string;
+    cssLocalIdent?: string;
+    dontEmitBuildInfo?: boolean;
+    dontUseProgressPlugin?: boolean;
+    entry: string | string[];
+    fs?: typeof nodeFs;
+    keepBuildInfo?: boolean | BuildInfoT;
+    mode: 'development' | 'none' | 'production';
+    outputPath?: string;
+    publicPath?: string;
+    sitemap?: string;
+    typescript?: boolean;
+    workbox?: boolean | object;
+};
+/**
+ * Creates a new Webpack config object, and performs some auxiliary operations
+ * on the way.
+ * @param {object} ops Configuration params. This allows to modify some
+ * frequently changed options in a convenient way, without a need to manipulate
+ * directly with the created config object.
+ * @param {string} ops.babelEnv Babel environment to use for the Babel
+ * compilation step.
+ * @param {object} [ops.babelLoaderOptions] Overrides for default Babel options
+ * of JSX and SVG files loader.
+ * @param ops.context Base URL for resolution of relative config paths.
+ * @param {string} [ops.cssLocalIdent=hash:base64:6] The template for
+ * CSS classnames generation by the Webpack's `css-loader`; it is passed into
+ * the `localIdentName` param of the loader. It should match the corresponding
+ * setting in the Babel config.
+ * @param {boolean} [ops.dontEmitBuildInfo] If set the `.build-info` file won't
+ * be created at the disk during the compilation.
+ * @param [ops.dontUseProgressPlugin] Set to not include progress
+ *  plugin.
+ * @param {string|string[]} ops.entry Entry points for "main" chunk. The config
+ * will prepend them by some necessary polyfills, e.g.:
+ * ([babel-polyfill](https://babeljs.io/docs/usage/polyfill/),
+ * [nodelist-foreach-polyfill](https://www.npmjs.com/package/nodelist-foreach-polyfill)).
+ * @param {boolean|object} ops.workbox If evaluates to a truthy value,
+ * [Workbox's InjectManifest plugin](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin#injectmanifest_plugin)
+ * is added to the array of Webpack plugins, to generate service worker for
+ * browser. If the value is an object, it is merged into the options passed
+ * into the plugin, otherwise default options are used:
+ * ```json
+ * {
+ *   "importWorkboxFrom": "local",
+ *   "swSrc": "@dr.pogodin/react-utils/config/workbox/default.js",
+ *   "swDest": "__service-worker.js"
+ * }
+ * ```
+ * If service worker is generated by this option, it will be automatically
+ * initiated at the client side by the standard
+ * [client-side initialization script](docs/client.md)
+ * provided by **@dr.pogodin/react-utils**. Note that `swDest`'s value cannot be
+ * overriden by config options provided via `workbox` object.
+ * @param {object} [ops.fs] Filesystem to use instead of the Node's FS.
+ * @param {boolean|object} [ops.keepBuildInfo] If `true` and a `.build-info`
+ *  file from a previous build exists in the context directory, it will be
+ *  loaded and used, rather than re-generated by the config factory. It allows
+ *  to re-create the Webpack config during a server launch without re-generation
+ *  of the build info file created during a previous build (and thus bundled
+ *  into the frontend bundle). If an object is provided, it will be used as
+ *  the build info, instead of trying to load it from the filesystem. This
+ *  feature is intended for testing context.
+ * @param {string} ops.mode
+ * [Webpack mode](https://webpack.js.org/concepts/mode/).
+ * @param {string} [ops.outputPath=build] Optional. Output path for the build.
+ * @param {string} ops.publicPath Base URL for the output of the build assets.
+ * @param {string} [ops.sitemap] The path to JS or JSON config for sitemap.
+ * It can be relative to the context, and can be a factory, which returns
+ * the config. The config should be compatible with
+ * [`sitemap`](https://www.npmjs.com/package/sitemap) library, and if
+ * provided the Webpack config factory will use it to gererate `sitemap.xml`
+ * file in the output folder, and then serve it from the app root.
+ * @return The generated config will opt to:
+ * - Bundle the font assets (EOF, OTF, SVG, TTF, WOFF, WOFF2 files from
+ *   the `src/assets/fonts` folder of your source code will be bundled
+ *   and output into the `[PUBLIC_PATH]/fonts` folder);
+ * - Bundle image assets (GIF, JPEG, JPG, PNG files from any folder of
+ *   your source code will be bundled and output into the
+ *   `[PUBLIC_PATH]/images` folder);
+ * - Bundle SCSS files from any folder of your source code, beside
+ *   `node_modules` and its subfolders. The files will be compiled,
+ *    bundled and extracted into the `[PUBLIC_PATH]/[CHUNK_NAME].css`
+ *    bundles;
+ * - Bundle CSS files from any folder of your code. The files will be
+ *   bundled and extracted into the `[PUBLIC_PATH]/[CHUNK_NAME].css`
+ *   bundles;
+ * - Bundle JS, JSX, and SVG files; they will be compiled into the
+ *   `[PUBLIC_PATH]/[CHUNK_NAME].js` bundles, using the Babel environment
+ *   specified in the factory options, and
+ *   [`config/babel/webpack`](./babel-config.js#webpack) config.
+ *
+ * - The following path aliases will be automatically set:
+ * - **`assets`** for `[CONTEXT]/src/assets`;
+ * - **`components`** for `[CONTEXT]/src/shared/components`;
+ * - **`fonts`** for `[CONTEXT]/src/assets/fonts`;
+ * - **`styles`** for `[CONTEXT]/src/styles`.
+ *
+ * Also `resolve.symlinks` Webpack option is set to *false* to avoid problems
+ * with resolution of assets from packages linked with `npm link`.
+ *
+ * - The following global variables will be emulated inside the output
+ *   JS bundle:
+ *   - **`BUILD_RNDKEY`** &mdash; A random 32 bit key that can be used
+ *     for encryption, it is set just as a global variable accessible in
+ *     the code;
+ *   - **`BUILD_TIMESTAMP`** &mdash; UTC timestamp of the beginning of
+ *     the build;
+ *   - **`FRONT_END`** &mdash; It will be set *true* inside the bundle,
+ *     so that shared code can use it to determine that it is executed
+ *     at the client side.
+ *
+ * - It also opts to polyfill the `__dirname` global variable,
+ *   and to ignore imports of the `fs` Node package;
+ *
+ * - Also, it will store to the disk (re-writes if exists) the file
+ *   `[CONTEXT]/.build-info` which will contain a stringified JSON
+ *   object with the following fields:
+ *   - **`rndkey`** &mdash; The value set for `BUILD_RNDKEY`;
+ *   - **`timestamp`** &mdash; The value set for `BUILD_TIMESTAMP`.
+ */
+export default function configFactory(ops: OptionsT): Configuration;