@docusaurus/plugin-ideal-image 2.0.0-beta.15d451942 → 2.0.0-beta.16

package/lib/index.d.ts

@@ -4,6 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { LoadContext, Plugin } from '@docusaurus/types';
-import { PluginOptions } from './types';
-export default function (_context: LoadContext, options: PluginOptions): Plugin<void>;
+import type { LoadContext, Plugin, OptionValidationContext, ValidationResult } from '@docusaurus/types';
+import type { PluginOptions } from '@docusaurus/plugin-ideal-image';
+export default function pluginIdealImage(context: LoadContext, options: PluginOptions): Plugin<void>;
+export declare function validateOptions({ validate, options, }: OptionValidationContext<PluginOptions>): ValidationResult<PluginOptions>;

package/lib/index.js

@@ -1,43 +1,72 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const tslib_1 = require("tslib");
-const path_1 = tslib_1.__importDefault(require("path"));
-function default_1(_context, options) {
-    const isProd = process.env.NODE_ENV === 'production';
-    return {
-        name: 'docusaurus-plugin-ideal-image',
-        getThemePath() {
-            return path_1.default.resolve(__dirname, './theme');
+'use strict';
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, '__esModule', {value: true});
+exports.validateOptions = void 0;
+const tslib_1 = require('tslib');
+const utils_validation_1 = require('@docusaurus/utils-validation');
+const theme_translations_1 = require('@docusaurus/theme-translations');
+const path_1 = (0, tslib_1.__importDefault)(require('path'));
+function pluginIdealImage(context, options) {
+  const {
+    i18n: {currentLocale},
+  } = context;
+  return {
+    name: 'docusaurus-plugin-ideal-image',
+    getThemePath() {
+      return path_1.default.resolve(__dirname, '../lib/theme');
+    },
+    getTypeScriptThemePath() {
+      return path_1.default.resolve(__dirname, '../src/theme');
+    },
+    getDefaultCodeTranslationMessages() {
+      return (0, theme_translations_1.readDefaultCodeTranslationMessages)({
+        locale: currentLocale,
+        name: 'plugin-ideal-image',
+      });
+    },
+    configureWebpack(_config, isServer) {
+      const {disableInDev, ...loaderOptions} = options;
+      if (disableInDev && process.env.NODE_ENV !== 'production') {
+        return {};
+      }
+      return {
+        mergeStrategy: {
+          'module.rules': 'prepend',
         },
-        configureWebpack(_config, isServer) {
-            return {
-                mergeStrategy: {
-                    'module.rules': 'prepend',
+        module: {
+          rules: [
+            {
+              test: /\.(?:png|jpe?g|gif)$/i,
+              use: [
+                require.resolve('@docusaurus/lqip-loader'),
+                {
+                  loader: require.resolve('@docusaurus/responsive-loader'),
+                  options: {
+                    emitFile: !isServer,
+                    // eslint-disable-next-line global-require
+                    adapter: require('@docusaurus/responsive-loader/sharp'),
+                    name: 'assets/ideal-img/[name].[hash:hex:7].[width].[ext]',
+                    ...loaderOptions,
+                  },
                 },
-                module: {
-                    rules: [
-                        {
-                            test: /\.(png|jpe?g|gif)$/i,
-                            use: [
-                                require.resolve('@docusaurus/lqip-loader'),
-                                {
-                                    loader: require.resolve('@docusaurus/responsive-loader'),
-                                    options: {
-                                        emitFile: !isServer,
-                                        disable: !isProd,
-                                        adapter: require('@docusaurus/responsive-loader/sharp'),
-                                        name: isProd
-                                            ? 'assets/ideal-img/[name].[hash:hex:7].[width].[ext]'
-                                            : 'assets/ideal-img/[name].[width].[ext]',
-                                        ...options,
-                                    },
-                                },
-                            ],
-                        },
-                    ],
-                },
-            };
+              ],
+            },
+          ],
         },
-    };
+      };
+    },
+  };
+}
+exports.default = pluginIdealImage;
+function validateOptions({validate, options}) {
+  const pluginOptionsSchema = utils_validation_1.Joi.object({
+    disableInDev: utils_validation_1.Joi.boolean().default(true),
+  }).unknown();
+  return validate(pluginOptionsSchema, options);
 }
-exports.default = default_1;
+exports.validateOptions = validateOptions;

package/lib/{types.js → theme/IdealImage/index.d.ts}

@@ -1,8 +1,9 @@
-"use strict";
 /**
  * Copyright (c) Facebook, Inc. and its affiliates.
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
+/// <reference types="react" />
+import type { Props } from '@theme/IdealImage';
+export default function IdealImage(props: Props): JSX.Element;

package/lib/theme/IdealImage/index.js

@@ -0,0 +1,103 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import ReactIdealImage from '@endiliey/react-ideal-image';
+import {translate} from '@docusaurus/Translate';
+// Adopted from https://github.com/endiliey/react-ideal-image/blob/master/src/components/helpers.js#L59-L65
+const bytesToSize = (bytes) => {
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+  if (bytes === 0) {
+    return 'n/a';
+  }
+  const scale = Math.floor(Math.log(bytes) / Math.log(1024));
+  if (scale === 0) {
+    return `${bytes} ${sizes[scale]}`;
+  }
+  return `${(bytes / 1024 ** scale).toFixed(1)} ${sizes[scale]}`;
+};
+// Adopted from https://github.com/endiliey/react-ideal-image/blob/master/src/components/IdealImage/index.js#L43-L75
+const getMessage = (icon, state) => {
+  switch (icon) {
+    case 'noicon':
+    case 'loaded':
+      return null;
+    case 'loading':
+      return translate({
+        id: 'theme.IdealImageMessage.loading',
+        message: 'Loading...',
+        description: 'When the full-scale image is loading',
+      });
+    case 'load': {
+      // we can show `alt` here
+      const {pickedSrc} = state;
+      const {size} = pickedSrc;
+      const sizeMessage = size ? ` (${bytesToSize(size)})` : '';
+      return translate(
+        {
+          id: 'theme.IdealImageMessage.load',
+          message: 'Click to load{sizeMessage}',
+          description:
+            'To prompt users to load the full image. sizeMessage is a parenthesized size figure.',
+        },
+        {sizeMessage},
+      );
+    }
+    case 'offline':
+      return translate({
+        id: 'theme.IdealImageMessage.offline',
+        message: 'Your browser is offline. Image not loaded',
+        description: 'When the user is viewing an offline document',
+      });
+    case 'error': {
+      const {loadInfo} = state;
+      if (loadInfo === 404) {
+        return translate({
+          id: 'theme.IdealImageMessage.404error',
+          message: '404. Image not found',
+          description: 'When the image is not found',
+        });
+      }
+      return translate({
+        id: 'theme.IdealImageMessage.error',
+        message: 'Error. Click to reload',
+        description: 'When the image fails to load for unknown error',
+      });
+    }
+    default:
+      throw new Error(`Wrong icon: ${icon}`);
+  }
+};
+export default function IdealImage(props) {
+  const {alt, className, img} = props;
+  // In dev env just use regular img with original file
+  if (typeof img === 'string' || 'default' in img) {
+    return (
+      <img
+        src={typeof img === 'string' ? img : img.default}
+        className={className}
+        alt={alt}
+        {...props}
+      />
+    );
+  }
+  return (
+    <ReactIdealImage
+      {...props}
+      alt={alt}
+      className={className}
+      height={img.src.height || 100}
+      width={img.src.width || 100}
+      placeholder={{lqip: img.preSrc}}
+      src={img.src.src}
+      srcSet={img.src.images.map((image) => ({
+        ...image,
+        src: image.path,
+      }))}
+      getMessage={getMessage}
+    />
+  );
+}

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@docusaurus/plugin-ideal-image",
-  "version": "2.0.0-beta.15d451942",
+  "version": "2.0.0-beta.16",
   "description": "Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder).",
   "main": "lib/index.js",
+  "types": "src/plugin-ideal-image.d.ts",
   "scripts": {
-    "build": "tsc && node copyUntypedFiles.js",
-    "watch": "node copyUntypedFiles.js && tsc --watch"
+    "build": "yarn build:server && yarn build:browser && yarn build:copy && yarn build:format",
+    "build:server": "tsc --project tsconfig.server.json",
+    "build:browser": "tsc --project tsconfig.browser.json",
+    "build:copy": "node copyUntypedFiles.mjs",
+    "build:format": "prettier --config ../../.prettierrc --write \"lib/**/*.js\""
   },
   "publishConfig": {
     "access": "public"
@@ -16,26 +20,35 @@
     "directory": "packages/docusaurus-plugin-ideal-image"
   },
   "license": "MIT",
-  "devDependencies": {
-    "fs-extra": "^9.1.0"
-  },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.15d451942",
-    "@docusaurus/lqip-loader": "2.0.0-beta.15d451942",
-    "@docusaurus/responsive-loader": "1.4.0",
-    "@docusaurus/types": "2.0.0-beta.15d451942",
+    "@docusaurus/core": "2.0.0-beta.16",
+    "@docusaurus/lqip-loader": "2.0.0-beta.16",
+    "@docusaurus/responsive-loader": "^1.7.0",
+    "@docusaurus/theme-translations": "2.0.0-beta.16",
+    "@docusaurus/utils-validation": "2.0.0-beta.16",
     "@endiliey/react-ideal-image": "^0.0.11",
-    "react-waypoint": "^9.0.2",
-    "sharp": "^0.28.2",
-    "tslib": "^2.1.0",
-    "webpack": "^5.28.0"
+    "react-waypoint": "^10.1.0",
+    "sharp": "^0.30.1",
+    "tslib": "^2.3.1",
+    "webpack": "^5.69.1"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "2.0.0-beta.16",
+    "@docusaurus/types": "2.0.0-beta.16",
+    "fs-extra": "^10.0.1"
   },
   "peerDependencies": {
+    "jimp": "*",
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
+  "peerDependenciesMeta": {
+    "jimp": {
+      "optional": true
+    }
+  },
   "engines": {
-    "node": ">=12.13.0"
+    "node": ">=14"
   },
-  "gitHead": "dfceae8bd3e8b42ba8fc14f1449d861046c26143"
+  "gitHead": "eb43c4d4f95a4fb97dc9bb9dc615413e0dc2e1e7"
 }

package/src/deps.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/// <reference types="@docusaurus/module-type-aliases" />
+
+/**
+ * @see https://github.com/endiliey/react-ideal-image/blob/master/index.d.ts
+ * Note: the original type definition is WRONG. getIcon & getMessage receive
+ * full state object.
+ */
+declare module '@endiliey/react-ideal-image' {
+  import type {ComponentProps, ComponentType, CSSProperties} from 'react';
+
+  export type LoadingState = 'initial' | 'loading' | 'loaded' | 'error';
+
+  export type State = {
+    pickedSrc: {
+      size: number;
+    };
+    loadInfo: 404 | null;
+    loadState: LoadingState;
+  };
+
+  export type IconKey =
+    | 'load'
+    | 'loading'
+    | 'loaded'
+    | 'error'
+    | 'noicon'
+    | 'offline';
+
+  export interface SrcType {
+    width: number;
+    src?: string;
+    size?: number;
+    format?: 'webp' | 'jpeg' | 'png' | 'gif';
+  }
+
+  type ThemeKey = 'placeholder' | 'img' | 'icon' | 'noscript';
+
+  export interface ImageProps extends ComponentProps<'img'> {
+    /**
+     * This function decides what icon to show based on the current state of the
+     * component.
+     */
+    getIcon?: (state: State) => IconKey;
+    /**
+     * This function decides what message to show based on the icon (returned
+     * from `getIcon` prop) and the current state of the component.
+     */
+    getMessage?: (icon: IconKey, state: State) => string | null;
+    /**
+     * This function is called as soon as the component enters the viewport and
+     * is used to generate urls based on width and format if `props.srcSet`
+     * doesn't provide `src` field.
+     */
+    getUrl?: (srcType: SrcType) => string;
+    /**
+     * The Height of the image in px.
+     */
+    height: number;
+    /**
+     * This provides a map of the icons. By default, the component uses icons
+     * from material design, Implemented as React components with the SVG
+     * element. You can customize icons
+     */
+    icons?: Partial<Record<IconKey, ComponentType>>;
+    /**
+     * This prop takes one of the 2 options, xhr and image.
+     * Read more about it:
+     * https://github.com/stereobooster/react-ideal-image/blob/master/introduction.md#cancel-download
+     */
+    loader?: 'xhr' | 'image';
+    /**
+     * https://github.com/stereobooster/react-ideal-image/blob/master/introduction.md#lqip
+     */
+    placeholder: {color: string} | {lqip: string};
+    /**
+     * This function decides if image should be downloaded automatically. The
+     * default function returns false for a 2g network, for a 3g network it
+     * decides based on `props.threshold` and for a 4g network it returns true
+     * by default.
+     */
+    shouldAutoDownload?: (options: {
+      connection?: 'slow-2g' | '2g' | '3g' | '4g';
+      size?: number;
+      threshold?: number;
+      possiblySlowNetwork?: boolean;
+    }) => boolean;
+    /**
+     * This provides an array of sources of different format and size of the
+     * image. Read more about it:
+     * https://github.com/stereobooster/react-ideal-image/blob/master/introduction.md#srcset
+     */
+    srcSet: SrcType[];
+    /**
+     * This provides a theme to the component. By default, the component uses
+     * inline styles, but it is also possible to use CSS modules and override
+     * all styles.
+     */
+    theme?: Partial<Record<ThemeKey, string | CSSProperties>>;
+    /**
+     * Tells how much to wait in milliseconds until consider the download to be
+     * slow.
+     */
+    threshold?: number;
+    /**
+     * Width of the image in px.
+     */
+    width: number;
+  }
+
+  export default function IdealImage(props: ImageProps): JSX.Element;
+}

package/src/index.ts

@@ -0,0 +1,89 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {
+  LoadContext,
+  Plugin,
+  OptionValidationContext,
+  ValidationResult,
+} from '@docusaurus/types';
+import type {PluginOptions} from '@docusaurus/plugin-ideal-image';
+import {Joi} from '@docusaurus/utils-validation';
+import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
+
+import path from 'path';
+
+export default function pluginIdealImage(
+  context: LoadContext,
+  options: PluginOptions,
+): Plugin<void> {
+  const {
+    i18n: {currentLocale},
+  } = context;
+
+  return {
+    name: 'docusaurus-plugin-ideal-image',
+
+    getThemePath() {
+      return path.resolve(__dirname, '../lib/theme');
+    },
+
+    getTypeScriptThemePath() {
+      return path.resolve(__dirname, '../src/theme');
+    },
+
+    getDefaultCodeTranslationMessages() {
+      return readDefaultCodeTranslationMessages({
+        locale: currentLocale,
+        name: 'plugin-ideal-image',
+      });
+    },
+
+    configureWebpack(_config, isServer) {
+      const {disableInDev, ...loaderOptions} = options;
+      if (disableInDev && process.env.NODE_ENV !== 'production') {
+        return {};
+      }
+
+      return {
+        mergeStrategy: {
+          'module.rules': 'prepend',
+        },
+        module: {
+          rules: [
+            {
+              test: /\.(?:png|jpe?g|gif)$/i,
+              use: [
+                require.resolve('@docusaurus/lqip-loader'),
+                {
+                  loader: require.resolve('@docusaurus/responsive-loader'),
+                  options: {
+                    emitFile: !isServer, // don't emit for server-side rendering
+                    // eslint-disable-next-line global-require
+                    adapter: require('@docusaurus/responsive-loader/sharp'),
+                    name: 'assets/ideal-img/[name].[hash:hex:7].[width].[ext]',
+                    ...loaderOptions,
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      };
+    },
+  };
+}
+
+export function validateOptions({
+  validate,
+  options,
+}: OptionValidationContext<PluginOptions>): ValidationResult<PluginOptions> {
+  const pluginOptionsSchema = Joi.object({
+    disableInDev: Joi.boolean().default(true),
+  }).unknown();
+  return validate(pluginOptionsSchema, options);
+}

package/src/plugin-ideal-image.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+declare module '@docusaurus/plugin-ideal-image' {
+  export type PluginOptions = {
+    /**
+     * Filename template for output files.
+     */
+    name?: string;
+    /**
+     * Specify all widths you want to use; if a specified size exceeds the
+     * original image's width, the latter will be used (i.e. images won't be
+     * scaled up). You may also declare a default sizes array in the loader
+     * options in your webpack.config.js.
+     */
+    sizes?: number[];
+    /**
+     * Specify one width you want to use; if the specified size exceeds the
+     * original image's width, the latter will be used (i.e. images won't be
+     * scaled up)
+     */
+    size?: number;
+    /**
+     * As an alternative to manually specifying sizes, you can specify min, max
+     * and steps, and the sizes will be generated for you.
+     */
+    min?: number;
+    /**
+     * See min above
+     */
+    max?: number;
+    /**
+     * Configure the number of images generated between min and max (inclusive)
+     */
+    steps?: number;
+    /**
+     * JPEG compression quality
+     */
+    quality?: number;
+    /**
+     * Just use regular images in dev mode
+     */
+    disableInDev?: boolean;
+  };
+}
+
+declare module '@theme/IdealImage' {
+  import type {ComponentProps} from 'react';
+
+  export type SrcType = {
+    width: number;
+    path?: string;
+    size?: number;
+    format?: 'webp' | 'jpeg' | 'png' | 'gif';
+  };
+
+  export type SrcImage = {
+    height?: number;
+    width?: number;
+    preSrc: string;
+    src: string;
+    images: SrcType[];
+  };
+
+  export interface Props extends ComponentProps<'img'> {
+    readonly img: {default: string} | {src: SrcImage; preSrc: string} | string;
+  }
+  export default function IdealImage(props: Props): JSX.Element;
+}