@docusaurus/plugin-ideal-image 2.0.0-beta.ff31de0ff → 2.0.1

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 } 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, PluginOptions>): PluginOptions;

package/lib/index.js

@@ -1,15 +1,35 @@
 "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 });
-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';
+exports.validateOptions = void 0;
+const utils_validation_1 = require("@docusaurus/utils-validation");
+const theme_translations_1 = require("@docusaurus/theme-translations");
+function pluginIdealImage(context, options) {
+    const { i18n: { currentLocale }, } = context;
     return {
         name: 'docusaurus-plugin-ideal-image',
         getThemePath() {
-            return path_1.default.resolve(__dirname, './theme');
+            return '../lib/theme';
+        },
+        getTypeScriptThemePath() {
+            return '../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',
@@ -17,19 +37,18 @@ function default_1(_context, options) {
                 module: {
                     rules: [
                         {
-                            test: /\.(png|jpe?g|gif)$/i,
+                            test: /\.(?:png|jpe?g)$/i,
                             use: [
                                 require.resolve('@docusaurus/lqip-loader'),
                                 {
                                     loader: require.resolve('@docusaurus/responsive-loader'),
                                     options: {
+                                        // Don't emit for server-side rendering
                                         emitFile: !isServer,
-                                        disable: !isProd,
+                                        // eslint-disable-next-line global-require
                                         adapter: require('@docusaurus/responsive-loader/sharp'),
-                                        name: isProd
-                                            ? 'assets/ideal-img/[name].[hash:hex:7].[width].[ext]'
-                                            : 'assets/ideal-img/[name].[width].[ext]',
-                                        ...options,
+                                        name: 'assets/ideal-img/[name].[hash:hex:7].[width].[ext]',
+                                        ...loaderOptions,
                                     },
                                 },
                             ],
@@ -40,4 +59,11 @@ function default_1(_context, options) {
         },
     };
 }
-exports.default = default_1;
+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.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
+function 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
+function 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,14 @@
 {
   "name": "@docusaurus/plugin-ideal-image",
-  "version": "2.0.0-beta.ff31de0ff",
+  "version": "2.0.1",
   "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": "tsc --build && node ../../admin/scripts/copyUntypedFiles.js && prettier --config ../../.prettierrc --write \"lib/theme/**/*.js\"",
+    "watch": "run-p -c copy:watch build:watch",
+    "build:watch": "tsc --build --watch",
+    "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "publishConfig": {
     "access": "public"
@@ -16,26 +19,36 @@
     "directory": "packages/docusaurus-plugin-ideal-image"
   },
   "license": "MIT",
-  "devDependencies": {
-    "fs-extra": "^9.1.0"
-  },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.ff31de0ff",
-    "@docusaurus/lqip-loader": "2.0.0-beta.ff31de0ff",
-    "@docusaurus/responsive-loader": "1.4.0",
-    "@docusaurus/types": "2.0.0-beta.ff31de0ff",
+    "@docusaurus/core": "2.0.1",
+    "@docusaurus/lqip-loader": "2.0.1",
+    "@docusaurus/responsive-loader": "^1.7.0",
+    "@docusaurus/theme-translations": "2.0.1",
+    "@docusaurus/types": "2.0.1",
+    "@docusaurus/utils-validation": "2.0.1",
     "@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.3.0",
+    "sharp": "^0.30.7",
+    "tslib": "^2.4.0",
+    "webpack": "^5.73.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "2.0.1",
+    "@docusaurus/types": "2.0.0-beta.21",
+    "fs-extra": "^10.1.0"
   },
   "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": ">=16.14"
   },
-  "gitHead": "6cacb313da4a21283fe08176097df89df836ee23"
+  "gitHead": "1ddee1c29cabf9bb52e4d78af6ebfaaabb1bc1f9"
 }

package/src/deps.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 type SrcType = {
+    width: number;
+    src?: string;
+    size?: number;
+    format?: 'webp' | 'jpeg' | 'png' | 'gif';
+  };
+
+  type ThemeKey = 'placeholder' | 'img' | 'icon' | 'noscript';
+
+  export interface ImageProps
+    extends Omit<ComponentProps<'img'>, 'srcSet' | 'placeholder'> {
+    /**
+     * 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<{[icon in 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<{[key in 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,87 @@
+/**
+ * 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 {Joi} from '@docusaurus/utils-validation';
+import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
+import type {
+  LoadContext,
+  Plugin,
+  OptionValidationContext,
+} from '@docusaurus/types';
+import type {PluginOptions} from '@docusaurus/plugin-ideal-image';
+
+export default function pluginIdealImage(
+  context: LoadContext,
+  options: PluginOptions,
+): Plugin<void> {
+  const {
+    i18n: {currentLocale},
+  } = context;
+
+  return {
+    name: 'docusaurus-plugin-ideal-image',
+
+    getThemePath() {
+      return '../lib/theme';
+    },
+
+    getTypeScriptThemePath() {
+      return '../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)$/i,
+              use: [
+                require.resolve('@docusaurus/lqip-loader'),
+                {
+                  loader: require.resolve('@docusaurus/responsive-loader'),
+                  options: {
+                    // Don't emit for server-side rendering
+                    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,
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      };
+    },
+  };
+}
+
+export function validateOptions({
+  validate,
+  options,
+}: OptionValidationContext<PluginOptions, PluginOptions>): PluginOptions {
+  const pluginOptionsSchema = Joi.object<PluginOptions>({
+    disableInDev: Joi.boolean().default(true),
+  }).unknown();
+  return validate(pluginOptionsSchema, options);
+}

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

@@ -0,0 +1,74 @@
+/**
+ * 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).
+     */
+    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 {@link PluginOptions.min}
+     */
+    max?: number;
+    /**
+     * Configure the number of images generated between `min` and `max`
+     * (inclusive)
+     */
+    steps?: number;
+    /**
+     * JPEG compression quality
+     */
+    quality?: number;
+    /**
+     * You can test ideal image behavior in dev mode by setting this to `false`.
+     * Tip: use network throttling in your browser to simulate slow networks.
+     */
+    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;
+}

package/src/theme/IdealImage/index.tsx

@@ -0,0 +1,114 @@
+/**
+ * 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, {
+  type IconKey,
+  type State,
+} from '@endiliey/react-ideal-image';
+import {translate} from '@docusaurus/Translate';
+
+import type {Props} from '@theme/IdealImage';
+
+// Adopted from https://github.com/endiliey/react-ideal-image/blob/master/src/components/helpers.js#L59-L65
+function bytesToSize(bytes: number) {
+  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
+function getMessage(icon: IconKey, state: 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: Props): JSX.Element {
+  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}
+    />
+  );
+}