@openeuropa/bcl-builder 0.1.3 → 0.1.202411051450

package/README.md

@@ -0,0 +1,148 @@
+## BCL builder
+
+The `@openeuropa/bcl-builder` is a package providing scripts to be executed via
+the command line, `styles`, `scripts`, `copy`, `rename` and `sprite`.
+They can be used respectively to compile SASS files and minify css
+files, compile and minify js files, to copy files or rename files and to generate
+svg sprites.
+It comes with a `bin` file that is available when the package is installed and
+can be run as `npm run ecl-builder scriptName`.
+It supports a configuration file `bcl-builder.config.js` where each script can
+be configured to perform specific operations in the enviroment where they are
+used.
+
+### Api
+
+The builder uses by default a bcl-builder.config.js in the same folder where the
+builder script is executed.
+This file will define the different operations you want to perform via the builder.
+The config file is basically an export of the configuration for the different
+commands which all supports multiple operations as items in an array.
+
+`module.exports = { scripts: [{ entry, dest, options } ...], styles: [{ entry, dest, options } ...], rename: [{ entry, dest, options } ...], copy: [{ from, to, options } ...], sprite: [[{ entry, dest, options } ...], };`
+
+#### Styles
+
+`styles: [ { entry (string), dest (string), options (object) [plugins for postcss] https://github.com/postcss/postcss/blob/main/docs/plugins.md { minify (includes css nano for minification) } }, ],`
+
+#### Scripts
+
+`scripts: [ { entry (string), dest (string), options: (object) [rollup js configuration https://rollupjs.org/guide/en/#javascript-api] }, }, ],`
+
+#### Copy
+
+`copy: [ { from: (string), to: (string), options: (object) [copyfiles api conf https://www.npmjs.com/package/copyfiles], }, ],`
+
+#### Reaname
+
+`rename: [ { from: (string), to: (string), options: (object) { search: (glob), operation: [prefix|suffix|rewrite|extension], }, }, ],`
+
+#### Sprite
+
+`sprite: [ { entry: (string), dest: (string), options: (object) { file: (string) (defaut: bcl-icons.svg), list: (array of file names) (optional), }, }, ],`
+
+---
+
+#### Color Scheme
+
+```javascript
+ * Example config object: {
+ colorScheme: [
+  {
+    entry: path.resolve("resources/sass/color-scheme-variables.scss"),
+    dest: path.resolve(outputFolder, "assets/css/color_scheme.min.css"),
+    options: {
+      includePaths,
+      sourceMap: "file",
+    },
+  },
+],
+```
+
+This following example is the entry of the colorScheme. The scss file should look like this. It also support multiple color schemes.
+Example SCSS file of color-scheme.scss:
+
+```scss
+$colors-schemes: (
+  "ocean": (
+    "primary": #4eac00,
+    "secondary": #fbff00,
+    "danger": #ff8800,
+    "success": #4dff00,
+    "text": #294d26,
+    "background": #ffdfb0,
+    "link": #7b00ff,
+  ),
+);
+```
+
+You can find multiple plugins here:
+[Postcss Plugins](https://github.com/postcss/postcss/blob/main/docs/plugins.md)
+
+The color-scheme enables the possibility to theme the colors used in BCL. It overrides the variables `$theme-colors` used by Bootstrap ([Bootstrap Theme Colors](https://getbootstrap.com/docs/5.0/customize/color/#theme-colors)).
+
+We've also added some new variables that overwrite and make use of extra classes:
+
+- `.text-color-default`: Text color is changed based on the 'text' variable, overriding all text colors inside a component.
+- `.bg-default`: Background color is changed based on the 'background' variable. It adds a background for the component but does not override if it already has a `bg` class (e.g., `bg-primary`).
+
+### Prerequisites
+
+- BCL-Builder version >= 1.2.1
+- BCL-Bootstrap version >= 1.2.1
+- BCL-Theme-Default >= 1.2.1
+
+### Setup Color Schema
+
+Step 1:
+Depending on your package manager:
+
+Yarn:
+
+- yarn add @openeuropa/bcl-builder --save
+- yarn add @openeuropa/bcl-bootstrap --save
+- yarn add @openeuropa/bcl-theme-default --save
+
+NPM:
+
+- npm install @openeuropa/bcl-builder --save
+- npm install @openeuropa/bcl-bootstrap --save
+- npm install @openeuropa/bcl-theme-default --save
+
+Step 2:
+Add the following bcl-builder.config.js file:
+
+```javascript
+  colorScheme: [
+    {
+      entry: path.resolve(outputFolder, "path to the color-scheme scss file"),
+      dest: path.resolve(outputFolder, "compiled "),
+      options: {
+        includePaths,
+        minify: true,
+        sourceMap: "file",
+      },
+    },
+  ],
+```
+
+Step 3:
+Add in your package.json the following command:
+
+```javascript
+  "build:color-scheme": "bcl-builder color-scheme",
+```
+
+Note: We are using ([npm-run-all package](https://www.npmjs.com/package/npm-run-all)) in BCL in order for all scripts for bcl-builder to be run at once:
+Example:
+
+```javascript
+    "build": "npm-run-all build:*",
+    "build:styles": "bcl-builder styles",
+    "build:color-scheme": "bcl-builder color-scheme",
+    "build:scripts": "bcl-builder scripts",
+    "build:copy": "bcl-builder copy",
+    "build:sprite": "bcl-builder sprite",
+```
+
+---

package/bin/build.js

@@ -5,7 +5,10 @@ const program = require("commander");
 const buildScript = require("../scripts/scripts");
 const browserslist = require("browserslist");
 const { buildStyles } = require("../scripts/styles");
+const { buildColorScheme } = require("../scripts/colorScheme");
+const rename = require("../scripts/rename");
 const copyFiles = require("../scripts/copy");
+const makeSprite = require("../scripts/sprite");
 const pkg = require("../package.json");
 
 const loadConfig = (configFile) => {
@@ -55,6 +58,26 @@ program
     );
   });
 
+program
+  .command("color-scheme")
+  .description("compile Color scheme SCSS to CSS")
+  .action(() => {
+    const config = loadConfig(program.config);
+    config.colorScheme.forEach((conf) =>
+      buildColorScheme(conf.entry, conf.dest, conf.options)
+    );
+  });
+
+program
+  .command("sprite")
+  .description("make svg sprites")
+  .action(() => {
+    const config = loadConfig(program.config);
+    config.sprite.forEach((conf) =>
+      makeSprite(conf.entry || "**", conf.dest, conf.options)
+    );
+  });
+
 program
   .command("copy")
   .description("copy static files")
@@ -65,6 +88,14 @@ program
     );
   });
 
+program
+  .command("rename")
+  .description("rename files")
+  .action(() => {
+    const config = loadConfig(program.config);
+    config.rename.forEach((conf) => rename(conf.from, conf.to, conf.options));
+  });
+
 // If no arguments provided, display help menu.
 if (process.argv.slice(2).length <= 0) {
   program.help();

package/conf/svgoDefaultPlugins.js

@@ -0,0 +1,22 @@
+module.exports = [
+  {
+    name: "preset-default",
+    params: {
+      overrides: {
+        removeUnknownsAndDefaults: {
+          keepRoleAttr: true,
+        },
+        removeViewBox: false,
+      },
+    },
+  },
+  "cleanupListOfValues",
+  "removeXMLNS",
+  "sortAttrs",
+  {
+    name: "removeAttrs",
+    params: {
+      attrs: ["clip-rule", "data-name", "fill"],
+    },
+  },
+];

package/package.json

@@ -2,38 +2,39 @@
   "name": "@openeuropa/bcl-builder",
   "author": "European Commission",
   "license": "EUPL-1.2",
-  "version": "0.1.3",
+  "version": "0.1.202411051450",
   "description": "Bootstrap Component Library builder",
   "publishConfig": {
     "access": "public"
   },
-  "bin": {
-    "bcl-builder": "./bin/build.js"
-  },
+  "bin": "./bin/build.js",
   "dependencies": {
-    "@babel/core": "7.14.6",
-    "@babel/preset-env": "7.14.7",
-    "@babel/runtime": "7.14.6",
-    "@popperjs/core": "2.9.2",
-    "@rollup/plugin-babel": "5.3.0",
-    "@rollup/plugin-commonjs": "19.0.0",
-    "@rollup/plugin-node-resolve": "13.0.0",
-    "@rollup/plugin-replace": "2.4.2",
-    "autoprefixer": "10.2.6",
+    "@babel/core": "7.24.7",
+    "@babel/preset-env": "7.24.7",
+    "@babel/runtime": "7.24.7",
+    "@popperjs/core": "2.11.8",
+    "@rollup/plugin-babel": "6.0.4",
+    "@rollup/plugin-commonjs": "25.0.8",
+    "@rollup/plugin-node-resolve": "15.2.3",
+    "@rollup/plugin-replace": "5.0.7",
+    "autoprefixer": "10.4.19",
     "babel-eslint": "10.1.0",
-    "browser-sync": "2.27.1",
-    "commander": "6.2.0",
+    "browser-sync": "3.0.2",
+    "commander": "11.1.0",
     "copyfiles": "2.4.1",
     "cross-env": "7.0.3",
-    "cssnano": "5.0.6",
-    "postcss": "8.3.5",
-    "rollup": "2.52.2",
-    "rollup-plugin-istanbul": "3.0.0",
+    "cssnano": "6.1.2",
+    "postcss": "8.4.39",
+    "postcss-prefix-selector": "^1.16.1",
+    "rollup": "3.29.4",
+    "rollup-plugin-istanbul": "4.0.0",
     "rollup-plugin-terser": "7.0.2",
-    "sass": "1.35.1"
+    "sass": "1.77.6",
+    "svg-sprite": "2.0.4",
+    "svgo": "3.3.2"
   },
   "engines": {
-    "node": ">=12.0.0"
+    "node": ">=14.0.0"
   },
-  "gitHead": "ab1587b9ba4971ea0ca72c3de6b632f2c314c200"
+  "gitHead": "d553864c2d2214729cf74aa765606f2c447bb456"
 }

package/scripts/colorScheme.js

@@ -0,0 +1,127 @@
+/**
+ * Compile scss files.
+ *
+ * @param {string} from - Path to a folder or file.
+ * @param {string} to - String to prefix, suffix or replace the current file name.
+ * @param {object} options - Object
+ *
+ * Example config object: {
+ *
+ *  color-scheme: [
+ *   {
+ *     entry: path.resolve("resources/sass/color-scheme-variables.scss"),
+ *     dest: path.resolve(outputFolder, "assets/css/color_scheme.min.css"),
+ *     options: {
+ *       includePaths,
+ *       sourceMap: "file",
+ *     },
+ *   },
+ * ],
+ */
+
+const sass = require("sass");
+const path = require("path");
+const fs = require("fs");
+const postcss = require("postcss");
+const cssnano = require("cssnano");
+const prefixer = require("postcss-prefix-selector");
+const autoprefixer = require("autoprefixer");
+
+const getPlugins = (options) => {
+  const plugins = [];
+
+  plugins.push(autoprefixer({ grid: "no-autoplace" }));
+
+  if (options.minify) {
+    plugins.push(cssnano({ safe: true }));
+  }
+
+  return plugins;
+};
+
+const buildColorScheme = (entry, dest, options) => {
+  const plugins = getPlugins(options);
+
+  let postcssSourceMap = false;
+  if (options.sourceMap === true) {
+    postcssSourceMap = true; // inline
+  } else if (options.sourceMap === "file") {
+    postcssSourceMap = options.sourceMap; // as a file
+  }
+
+  // Read contents of the entry file and the base color scheme SCSS file
+  const entryVariables = fs.readFileSync(entry, "utf8");
+  const imports = fs.readFileSync(
+    path.resolve(
+      ...(options.includePaths || []),
+      "@openeuropa/bcl-theme-default/src/scss/color-scheme.scss"
+    ),
+    "utf8"
+  );
+  const generator = fs.readFileSync(
+    path.resolve(
+      ...(options.includePaths || []),
+      "@openeuropa/bcl-theme-default/src/scss/color_scheme/generator.scss"
+    ),
+    "utf8"
+  );
+
+  // Concatenate the contents
+  const scssContent = imports + "\n" + entryVariables + "\n" + generator;
+
+  const sassResult = sass.renderSync({
+    data: scssContent,
+    outFile: dest,
+    noErrorCss: true,
+    outputStyle: "expanded",
+    sourceMap: options.sourceMap !== false,
+    sourceMapContents: options.sourceMap === true,
+    sourceMapEmbed: options.sourceMap === true,
+    includePaths: [
+      path.resolve(process.cwd(), "node_modules"),
+      ...(options.includePaths || []),
+    ],
+  });
+
+  postcss(plugins)
+    .use(
+      prefixer({
+        prefix: options.prefix ? options.prefix : "",
+
+        transform: function (
+          prefix,
+          selector,
+          prefixedSelector,
+          filePath,
+          rule
+        ) {
+          if (prefix) {
+            return prefixedSelector;
+          } else {
+            return selector;
+          }
+        },
+      })
+    )
+    .process(sassResult.css, {
+      map:
+        postcssSourceMap === "file"
+          ? { inline: false, prev: sassResult.map.toString() }
+          : postcssSourceMap,
+      from: entry,
+      to: dest,
+    })
+    .then((postcssResult) => {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, postcssResult.css);
+
+      if (postcssResult.map) {
+        fs.writeFileSync(`${dest}.map`, postcssResult.map.toString());
+      }
+    });
+};
+
+module.exports = {
+  getPlugins,
+  buildColorScheme,
+};

package/scripts/copy.js

@@ -1,3 +1,20 @@
+/**
+ * Copy files.
+ *
+ * @param {string} from - Path to a folder or file.
+ * @param {string} to - String to prefix, suffix or replace the current file name.
+ * @param {object} options - Object
+ *
+ * Example config object: {
+ *  copy: [
+ *   {
+ *     from: [path.resolve(nodeModules, "myfile.js")],
+ *     to: path.resolve(outputFolder, "js"),
+ *     options: { up: true },
+ *   },
+ * ],
+ */
+
 const fs = require("fs");
 const path = require("path");
 const copy = require("copyfiles");

package/scripts/rename.js

@@ -0,0 +1,93 @@
+/**
+ * Rename files.
+ *
+ * @param {string} from - Path to a folder or file.
+ * @param {string} to - String to prefix, suffix or replace the current file name.
+ * @param {object} options - Options available:
+ *                              search: (string) the glob to find the files in the "from"
+ *                              glob: (glob) The glob to be added as a segment in the "from"
+ *                              operation: (string) Available options:
+ *                                prefix (string), suffix (String), rewrite (String),
+ *                                extension (boolean), newExtension (string)
+ * Example config object: {
+ *  rename: [
+ *   {
+ *     from: path.resolve(outputFolder, "templates"),
+ *     to: "bcl-",
+ *       options: {
+ *         search: "*.twig",
+ *         operation: "prefix",
+ *      },
+ *   }
+ *  ]
+ */
+
+const path = require("path");
+const { globSync } = require("glob");
+const { rename } = require("fs");
+
+module.exports = (from, to, options) => {
+  const executor = async () => {
+    let files = false;
+
+    if (options.glob) {
+      if (options.search) {
+        files = globSync(path.join(from, options.glob, options.search));
+      } else {
+        files = globSync(path.join(from, options.glob));
+      }
+    } else {
+      if (options.search) {
+        files = globSync(path.join(from, options.search));
+      } else {
+        files = globSync(from);
+      }
+    }
+
+    if (files[0]) {
+      files.forEach(async (file) => {
+        const fileName = path.basename(file);
+        const folder = path.dirname(file);
+        let newFileName = fileName;
+
+        if (!options.operation) {
+          options.operation = "prefix";
+        }
+
+        switch (options.operation) {
+          case "prefix":
+            newFileName = `${to}${fileName}`;
+            break;
+
+          case "suffix":
+            newFileName = `${fileName}${to}`;
+            break;
+
+          case "rewrite":
+            newFileName = to;
+            break;
+
+          case "extension":
+            const currentExtension = fileName.substring(fileName.indexOf("."));
+            const withoutExtension = fileName.replace(currentExtension, "");
+            const newExtension = options.newExtension || currentExtension;
+            newFileName = `${withoutExtension}${newExtension}`;
+            break;
+
+          default:
+            console.error("The requested operation was not recognized");
+        }
+
+        const newFile = `${folder}/${newFileName}`;
+
+        await rename(file, newFile, function (err) {
+          if (err) console.error(err);
+        });
+      });
+    } else {
+      console.error("We couldn't find the file(s) you wanted to rename");
+    }
+  };
+
+  executor();
+};

package/scripts/scripts.js

@@ -1,3 +1,36 @@
+/**
+ * Compile and bundle js files.
+ *
+ * @param {string} input - Path to a folder or file.
+ * @param {string} dest - String to prefix, suffix or replace the current file name.
+ * @param {object} options - Object
+ *
+ * Example config object: {
+ *
+ * scripts: [
+ *   {
+ *     entry: path.resolve(__dirname, "src/js/index.esm.js"),
+ *     dest: path.resolve(outputFolder, "js/oe-bcl-default.esm.js"),
+ *     options: {
+ *       format: "esm",
+ *       globals: { "@popperjs/core": "Popper" },
+ *       minify: true,
+ *       sourceMap: true,
+ *       minifyOptions: {
+ *         mangle: true,
+ *         format: {
+ *           comments: /^!/,
+ *         },
+ *         compress: {
+ *           passes: 2,
+ *         },
+ *       },
+ *       external: ["@popperjs/core"],
+ *     },
+ *   },
+ * ],
+ */
+
 const path = require("path");
 const { babel } = require("@rollup/plugin-babel");
 const { nodeResolve } = require("@rollup/plugin-node-resolve");

package/scripts/sprite.js

@@ -0,0 +1,96 @@
+/**
+ * Generate svg sprites.
+ *
+ * @param {string} entry - array of paths to a folder or file.
+ * @param {string} dest - Output folder path
+ * @param {object} options - Object
+ *
+ * Example config object: {
+ *
+ * sprite: [
+ *   {
+ *     entry: [
+ *       path.resolve(nodeModules, "bootstrap-icons/icons/"),
+ *       path.resolve(__dirname, "src/icons/custom-icons")
+ *     ],
+ *     dest: path.resolve(outputFolder, "icons/"),
+ *     options: {
+ *       file: "bcl-default-icons.svg",
+ *       list: myList,
+ *       transformPlugins: (array of svgo plugins objects)
+ *     },
+ *   },
+ * ],
+ */
+
+const fs = require("fs");
+const { globSync } = require("glob");
+const mkdirp = require("mkdirp");
+const path = require("path");
+const defaultPlugins = require("../conf/svgoDefaultPlugins");
+const SVGSpriter = require("svg-sprite");
+
+module.exports = (entry, dest, options) => {
+  const iconList = Array.isArray(options.list)
+    ? options.list.flat(1)
+    : options.list;
+  const outputFile = options.file
+    ? `${dest}/${options.file}`
+    : `${dest}/bcl-default-icons.svg`;
+  const files = iconList || globSync("*.svg", { cwd: entry });
+
+  const plugins = options.transformPlugins || defaultPlugins;
+
+  const spriter = new SVGSpriter({
+    dest,
+    shape: {
+      transform: [
+        {
+          svgo: {
+            multipass: true,
+            plugins: defaultPlugins,
+          },
+        },
+      ],
+    },
+    svg: {
+      namespaceClassnames: false,
+      xmlDeclaration: false,
+    },
+    mode: {
+      symbol: {
+        dest: "",
+        sprite: outputFile,
+      },
+    },
+  });
+
+  files.forEach((file) => {
+    let filePath;
+    if (Array.isArray(entry)) {
+      filePath = path.resolve(entry[0], file);
+      if (!fs.existsSync(filePath)) {
+        filePath = path.resolve(entry[1], file);
+      }
+    } else {
+      filePath = path.resolve(entry, file);
+    }
+    spriter.add(
+      filePath,
+      file,
+      fs.readFileSync(filePath, { encoding: "utf-8" })
+    );
+  });
+
+  spriter.compile((error, result, data) => {
+    Object.keys(result).forEach((mode) => {
+      Object.keys(result[mode]).forEach((resource) => {
+        mkdirp.sync(path.dirname(result[mode][resource].path));
+        fs.writeFileSync(
+          result[mode][resource].path,
+          result[mode][resource].contents
+        );
+      });
+    });
+  });
+};

package/scripts/styles.js

@@ -1,8 +1,30 @@
+/**
+ * Compile scss files.
+ *
+ * @param {string} from - Path to a folder or file.
+ * @param {string} to - String to prefix, suffix or replace the current file name.
+ * @param {object} options - Object
+ *
+ * Example config object: {
+ *
+ *  styles: [
+ *   {
+ *     entry: [path.resolve(nodeModules, "myfile.js")],
+ *     dest: path.resolve(outputFolder, "js"),
+ *     options: {
+ *       includePaths,
+ *       sourceMap: "file",
+ *     },
+ *   },
+ * ],
+ */
+
 const sass = require("sass");
 const path = require("path");
 const fs = require("fs");
 const postcss = require("postcss");
 const cssnano = require("cssnano");
+const prefixer = require("postcss-prefix-selector");
 const autoprefixer = require("autoprefixer");
 
 const getPlugins = (options) => {
@@ -41,7 +63,17 @@ const buildStyles = (entry, dest, options) => {
     ],
   });
 
-  postcss(plugins)
+  const processor = postcss(plugins);
+  if (options.prefix) {
+    console.error(
+      `The prefix option is deprecated, use 'prefixer' instead, e.g.: prefixer: { prefix: "${options.prefix}" }`
+    );
+    processor.use(prefixer({ prefix: options.prefix }));
+  } else if (options.prefixer) {
+    processor.use(prefixer(options.prefixer));
+  }
+
+  processor
     .process(sassResult.css, {
       map:
         postcssSourceMap === "file"