@azerion/bunosaurus-plugin-css-cascade-layers 0.0.0-stage → 4.0.0-canary-6927

package/README.md

@@ -1,3 +1,7 @@
-# Temporary Holding Version
+# `@docusaurus/plugin-css-cascade-layers`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CSS Cascade Layer plugin for Docusaurus
+
+## Usage
+
+See [plugin-css-cascade-layers documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-css-cascade-layers).

package/lib/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 } from '@docusaurus/types';
+import type { PluginOptions, Options } from './options';
+export default function pluginCssCascadeLayers(context: LoadContext, options: PluginOptions): Plugin | null;
+export { validateOptions } from './options';
+export type { PluginOptions, Options };

package/lib/index.js

@@ -0,0 +1,44 @@
+"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;
+exports.default = pluginCssCascadeLayers;
+const tslib_1 = require("tslib");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const postCssPlugin_1 = require("./postCssPlugin");
+const layers_1 = require("./layers");
+const PluginName = 'docusaurus-plugin-css-cascade-layers';
+const LayersDeclarationModule = 'layers.css';
+function getLayersDeclarationPath(context, options) {
+    const { generatedFilesDir } = context;
+    const pluginId = options.id;
+    if (pluginId !== 'default') {
+        // Since it's only possible to declare a single layer order
+        // using this plugin twice doesn't really make sense
+        throw new Error('The CSS Cascade Layers plugin does not support multiple instances.');
+    }
+    return node_path_1.default.join(generatedFilesDir, PluginName, pluginId, LayersDeclarationModule);
+}
+function pluginCssCascadeLayers(context, options) {
+    const layersDeclarationPath = getLayersDeclarationPath(context, options);
+    return {
+        name: PluginName,
+        getClientModules() {
+            return [layersDeclarationPath];
+        },
+        async contentLoaded({ actions }) {
+            await actions.createData(LayersDeclarationModule, (0, layers_1.generateLayersDeclaration)(Object.keys(options.layers)));
+        },
+        configurePostCss(postCssOptions) {
+            postCssOptions.plugins.push((0, postCssPlugin_1.PostCssPluginWrapInLayer)(options));
+            return postCssOptions;
+        },
+    };
+}
+var options_1 = require("./options");
+Object.defineProperty(exports, "validateOptions", { enumerable: true, get: function () { return options_1.validateOptions; } });

package/lib/layers.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+export type LayerEntry = [string, (filePath: string) => boolean];
+export declare function isValidLayerName(layer: string): boolean;
+export declare function generateLayersDeclaration(layers: string[]): string;
+export declare function findLayer(filePath: string, layers: LayerEntry[]): string | undefined;

package/lib/layers.js

@@ -0,0 +1,24 @@
+"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.isValidLayerName = isValidLayerName;
+exports.generateLayersDeclaration = generateLayersDeclaration;
+exports.findLayer = findLayer;
+function isValidLayerName(layer) {
+    // TODO improve validation rule to match spec, not high priority
+    return !layer.includes(',') && !layer.includes(' ');
+}
+function generateLayersDeclaration(layers) {
+    return `@layer ${layers.join(', ')};`;
+}
+function findLayer(filePath, layers) {
+    // Using find() => layers order matter
+    // The first layer that matches is used in priority even if others match too
+    const layerEntry = layers.find((layer) => layer[1](filePath));
+    return layerEntry?.[0]; // return layer name
+}

package/lib/options.d.ts

@@ -0,0 +1,10 @@
+import type { OptionValidationContext } from '@docusaurus/types';
+export type PluginOptions = {
+    id: string;
+    layers: Record<string, (filePath: string) => boolean>;
+};
+export type Options = {
+    layers?: PluginOptions['layers'];
+};
+export declare const DEFAULT_OPTIONS: Partial<PluginOptions>;
+export declare function validateOptions({ validate, options, }: OptionValidationContext<Options, PluginOptions>): PluginOptions;

package/lib/options.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_OPTIONS = void 0;
+exports.validateOptions = validateOptions;
+/**
+ * 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.
+ */
+const utils_validation_1 = require("@docusaurus/utils-validation");
+const utils_1 = require("@docusaurus/utils");
+const layers_1 = require("./layers");
+// Not ideal to compute layers using "filePath.includes()"
+// But this is mostly temporary until we add first-class layers everywhere
+function layerFor(...params) {
+    return (filePath) => {
+        const posixFilePath = (0, utils_1.posixPath)(filePath);
+        return params.some((p) => posixFilePath.includes(p));
+    };
+}
+// Object order matters, it defines the layer order
+const DEFAULT_LAYERS = {
+    'docusaurus.infima': layerFor('node_modules/infima/dist'),
+    'docusaurus.theme-common': layerFor('packages/docusaurus-theme-common/lib', 'node_modules/@docusaurus/theme-common/lib'),
+    'docusaurus.theme-classic': layerFor('packages/docusaurus-theme-classic/lib', 'node_modules/@docusaurus/theme-classic/lib'),
+    'docusaurus.core': layerFor('packages/docusaurus/lib', 'node_modules/@docusaurus/core/lib'),
+    'docusaurus.plugin-debug': layerFor('packages/docusaurus-plugin-debug/lib', 'node_modules/@docusaurus/plugin-debug/lib'),
+    'docusaurus.theme-mermaid': layerFor('packages/docusaurus-theme-mermaid/lib', 'node_modules/@docusaurus/theme-mermaid/lib'),
+    'docusaurus.theme-live-codeblock': layerFor('packages/docusaurus-theme-live-codeblock/lib', 'node_modules/@docusaurus/theme-live-codeblock/lib'),
+    'docusaurus.theme-search-algolia.docsearch': layerFor('node_modules/@docsearch/css/dist'),
+    'docusaurus.theme-search-algolia': layerFor('packages/docusaurus-theme-search-algolia/lib', 'node_modules/@docusaurus/theme-search-algolia/lib'),
+    // docusaurus.website layer ? (declare it, even if empty?)
+};
+exports.DEFAULT_OPTIONS = {
+    id: 'default',
+    layers: DEFAULT_LAYERS,
+};
+const pluginOptionsSchema = utils_validation_1.Joi.object({
+    layers: utils_validation_1.Joi.object()
+        .pattern(utils_validation_1.Joi.custom((val, helpers) => {
+        if (!(0, layers_1.isValidLayerName)(val)) {
+            return helpers.error('any.invalid');
+        }
+        return val;
+    }), utils_validation_1.Joi.function().arity(1).required())
+        .default(DEFAULT_LAYERS),
+});
+function validateOptions({ validate, options, }) {
+    return validate(pluginOptionsSchema, options);
+}

package/lib/postCssPlugin.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 { PluginCreator } from 'postcss';
+import type { PluginOptions } from './options';
+export declare const PostCssPluginWrapInLayer: PluginCreator<{
+    layers: PluginOptions['layers'];
+}>;

package/lib/postCssPlugin.js

@@ -0,0 +1,41 @@
+"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.PostCssPluginWrapInLayer = void 0;
+const layers_1 = require("./layers");
+function wrapCssRootInLayer(root, layer) {
+    const rootBefore = root.clone();
+    root.removeAll();
+    root.append({
+        type: 'atrule',
+        name: 'layer',
+        params: layer,
+        nodes: rootBefore.nodes,
+    });
+}
+const PostCssPluginWrapInLayer = (options) => {
+    if (!options) {
+        throw new Error('PostCssPluginWrapInLayer options are mandatory');
+    }
+    const layers = Object.entries(options.layers);
+    return {
+        postcssPlugin: 'postcss-wrap-in-layer',
+        Once(root) {
+            const filePath = root.source?.input.file;
+            if (!filePath) {
+                return;
+            }
+            const layer = (0, layers_1.findLayer)(filePath, layers);
+            if (layer) {
+                wrapCssRootInLayer(root, layer);
+            }
+        },
+    };
+};
+exports.PostCssPluginWrapInLayer = PostCssPluginWrapInLayer;
+exports.PostCssPluginWrapInLayer.postcss = true;

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "@azerion/bunosaurus-plugin-css-cascade-layers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.0-canary-6927+e0f3c69e5",
+  "description": "CSS Cascade Layer plugin for Docusaurus.",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "tsc --build",
+    "watch": "tsc --build --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/azerion/bunosaurus.git",
+    "directory": "packages/docusaurus-plugin-css-cascade-layers"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@docusaurus/core": "npm:@azerion/bunosaurus-core@4.0.0-canary-6927+e0f3c69e5",
+    "@docusaurus/types": "npm:@azerion/bunosaurus-types@4.0.0-canary-6927+e0f3c69e5",
+    "@docusaurus/utils": "npm:@azerion/bunosaurus-utils@4.0.0-canary-6927+e0f3c69e5",
+    "@docusaurus/utils-validation": "npm:@azerion/bunosaurus-utils-validation@4.0.0-canary-6927+e0f3c69e5",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "npm:@azerion/bunosaurus-module-type-aliases@4.0.0-canary-6927+e0f3c69e5",
+    "postcss": "^8.5.28"
+  },
+  "engines": {
+    "bun": ">=1.4.1"
+  }
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 path from 'node:path';
+import {PostCssPluginWrapInLayer} from './postCssPlugin';
+import {generateLayersDeclaration} from './layers';
+import type {LoadContext, Plugin} from '@docusaurus/types';
+import type {PluginOptions, Options} from './options';
+
+const PluginName = 'docusaurus-plugin-css-cascade-layers';
+
+const LayersDeclarationModule = 'layers.css';
+
+function getLayersDeclarationPath(
+  context: LoadContext,
+  options: PluginOptions,
+) {
+  const {generatedFilesDir} = context;
+  const pluginId = options.id;
+  if (pluginId !== 'default') {
+    // Since it's only possible to declare a single layer order
+    // using this plugin twice doesn't really make sense
+    throw new Error(
+      'The CSS Cascade Layers plugin does not support multiple instances.',
+    );
+  }
+  return path.join(
+    generatedFilesDir,
+    PluginName,
+    pluginId,
+    LayersDeclarationModule,
+  );
+}
+
+export default function pluginCssCascadeLayers(
+  context: LoadContext,
+  options: PluginOptions,
+): Plugin | null {
+  const layersDeclarationPath = getLayersDeclarationPath(context, options);
+
+  return {
+    name: PluginName,
+
+    getClientModules() {
+      return [layersDeclarationPath];
+    },
+
+    async contentLoaded({actions}) {
+      await actions.createData(
+        LayersDeclarationModule,
+        generateLayersDeclaration(Object.keys(options.layers)),
+      );
+    },
+
+    configurePostCss(postCssOptions) {
+      postCssOptions.plugins.push(PostCssPluginWrapInLayer(options));
+      return postCssOptions;
+    },
+  };
+}
+
+export {validateOptions} from './options';
+
+export type {PluginOptions, Options};

package/src/layers.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+
+export type LayerEntry = [string, (filePath: string) => boolean];
+
+export function isValidLayerName(layer: string): boolean {
+  // TODO improve validation rule to match spec, not high priority
+  return !layer.includes(',') && !layer.includes(' ');
+}
+
+export function generateLayersDeclaration(layers: string[]): string {
+  return `@layer ${layers.join(', ')};`;
+}
+
+export function findLayer(
+  filePath: string,
+  layers: LayerEntry[],
+): string | undefined {
+  // Using find() => layers order matter
+  // The first layer that matches is used in priority even if others match too
+  const layerEntry = layers.find((layer) => layer[1](filePath));
+  return layerEntry?.[0]; // return layer name
+}

package/src/options.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 {posixPath} from '@docusaurus/utils';
+import {isValidLayerName} from './layers';
+import type {OptionValidationContext} from '@docusaurus/types';
+
+export type PluginOptions = {
+  id: string; // plugin id
+  layers: Record<string, (filePath: string) => boolean>;
+};
+
+export type Options = {
+  layers?: PluginOptions['layers'];
+};
+
+// Not ideal to compute layers using "filePath.includes()"
+// But this is mostly temporary until we add first-class layers everywhere
+function layerFor(...params: string[]) {
+  return (filePath: string) => {
+    const posixFilePath = posixPath(filePath);
+    return params.some((p) => posixFilePath.includes(p));
+  };
+}
+
+// Object order matters, it defines the layer order
+const DEFAULT_LAYERS: PluginOptions['layers'] = {
+  'docusaurus.infima': layerFor('node_modules/infima/dist'),
+  'docusaurus.theme-common': layerFor(
+    'packages/docusaurus-theme-common/lib',
+    'node_modules/@docusaurus/theme-common/lib',
+  ),
+  'docusaurus.theme-classic': layerFor(
+    'packages/docusaurus-theme-classic/lib',
+    'node_modules/@docusaurus/theme-classic/lib',
+  ),
+  'docusaurus.core': layerFor(
+    'packages/docusaurus/lib',
+    'node_modules/@docusaurus/core/lib',
+  ),
+  'docusaurus.plugin-debug': layerFor(
+    'packages/docusaurus-plugin-debug/lib',
+    'node_modules/@docusaurus/plugin-debug/lib',
+  ),
+  'docusaurus.theme-mermaid': layerFor(
+    'packages/docusaurus-theme-mermaid/lib',
+    'node_modules/@docusaurus/theme-mermaid/lib',
+  ),
+  'docusaurus.theme-live-codeblock': layerFor(
+    'packages/docusaurus-theme-live-codeblock/lib',
+    'node_modules/@docusaurus/theme-live-codeblock/lib',
+  ),
+  'docusaurus.theme-search-algolia.docsearch': layerFor(
+    'node_modules/@docsearch/css/dist',
+  ),
+  'docusaurus.theme-search-algolia': layerFor(
+    'packages/docusaurus-theme-search-algolia/lib',
+    'node_modules/@docusaurus/theme-search-algolia/lib',
+  ),
+  // docusaurus.website layer ? (declare it, even if empty?)
+};
+
+export const DEFAULT_OPTIONS: Partial<PluginOptions> = {
+  id: 'default',
+  layers: DEFAULT_LAYERS,
+};
+
+const pluginOptionsSchema = Joi.object<PluginOptions>({
+  layers: Joi.object()
+    .pattern(
+      Joi.custom((val, helpers) => {
+        if (!isValidLayerName(val)) {
+          return helpers.error('any.invalid');
+        }
+        return val;
+      }),
+      Joi.function().arity(1).required(),
+    )
+    .default(DEFAULT_LAYERS),
+});
+
+export function validateOptions({
+  validate,
+  options,
+}: OptionValidationContext<Options, PluginOptions>): PluginOptions {
+  return validate(pluginOptionsSchema, options);
+}

package/src/postCssPlugin.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 {findLayer} from './layers';
+import type {Root, PluginCreator} from 'postcss';
+import type {PluginOptions} from './options';
+
+function wrapCssRootInLayer(root: Root, layer: string): void {
+  const rootBefore = root.clone();
+  root.removeAll();
+  root.append({
+    type: 'atrule',
+    name: 'layer',
+    params: layer,
+    nodes: rootBefore.nodes,
+  });
+}
+
+export const PostCssPluginWrapInLayer: PluginCreator<{
+  layers: PluginOptions['layers'];
+}> = (options) => {
+  if (!options) {
+    throw new Error('PostCssPluginWrapInLayer options are mandatory');
+  }
+  const layers = Object.entries(options.layers);
+  return {
+    postcssPlugin: 'postcss-wrap-in-layer',
+    Once(root) {
+      const filePath = root.source?.input.file;
+      if (!filePath) {
+        return;
+      }
+      const layer = findLayer(filePath, layers);
+      if (layer) {
+        wrapCssRootInLayer(root, layer);
+      }
+    },
+  };
+};
+
+PostCssPluginWrapInLayer.postcss = true;

package/src/types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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" />