@octaviaflow/icon-build-helpers 1.0.0

package/src/builders/vanilla.js

@@ -0,0 +1,115 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const { babel } = require("@rollup/plugin-babel");
+const path = require("path");
+const { rollup } = require("rollup");
+const virtual = require("./plugins/virtual");
+
+const BANNER = `/**
+ * Copyright IBM Corp. 2016, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * Code generated by @octaviaflow/icon-build-helpers. DO NOT EDIT.
+ */`;
+
+const babelConfig = {
+  babelrc: false,
+  exclude: /node_modules/,
+  presets: [
+    [
+      "@babel/preset-env",
+      {
+        targets: {
+          browsers: ["extends browserslist-config-octaviaflow"],
+        },
+      },
+    ],
+  ],
+  babelHelpers: "bundled",
+};
+
+async function builder(metadata, { output }) {
+  const modules = metadata.icons.flatMap((icon) => {
+    return icon.output.map((size) => {
+      const source = `export default ${JSON.stringify(size.descriptor)};`;
+      return {
+        source,
+        filepath: size.filepath,
+        moduleName: size.moduleName,
+      };
+    });
+  });
+
+  const files = {
+    "index.js": `${BANNER}\n\n`,
+  };
+  const input = {
+    "index.js": "index.js",
+  };
+
+  for (const m of modules) {
+    files[m.filepath] = m.source;
+    input[m.filepath] = m.filepath;
+    files["index.js"] +=
+      `\nexport { default as ${m.moduleName} } from '${m.filepath}';`;
+  }
+
+  const bundle = await rollup({
+    input,
+    plugins: [virtual(files), babel(babelConfig)],
+    onwarn: (warning, warn) => {
+      // Suppress warnings for large number of files
+      if (warning.code === "CIRCULAR_DEPENDENCY") return;
+      warn(warning);
+    },
+  });
+
+  const bundles = [
+    {
+      directory: path.join(output, "es"),
+      format: "esm",
+    },
+    {
+      directory: path.join(output, "lib"),
+      format: "commonjs",
+    },
+  ];
+
+  for (const { directory, format } of bundles) {
+    const outputOptions = {
+      dir: directory,
+      format,
+      entryFileNames: "[name]",
+      banner: BANNER,
+      exports: "auto",
+    };
+
+    await bundle.write(outputOptions);
+  }
+
+  const umd = await rollup({
+    input: "index.js",
+    plugins: [virtual(files), babel(babelConfig)],
+    onwarn: (warning, warn) => {
+      if (warning.code === "CIRCULAR_DEPENDENCY") return;
+      warn(warning);
+    },
+  });
+
+  await umd.write({
+    file: path.join(output, "umd/index.js"),
+    format: "umd",
+    name: "OctaviaFlowIcons",
+  });
+}
+
+module.exports = builder;

package/src/index.js

@@ -0,0 +1,21 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ * 
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+
+'use strict';
+
+const builders = require('./builders');
+const Metadata = require('./metadata');
+const Registry = require('./registry');
+
+module.exports = {
+  builders,
+  Metadata,
+  Registry,
+};

package/src/metadata/README.md

@@ -0,0 +1,37 @@
+# Metadata
+
+## About
+
+We store metadata for a collection of SVG assets to help with searching and
+using icons in the Carbon Design System. However, due to the large number of
+assets we maintain, we needed to build a system for organizing information about
+these icons and creating an output file to be consumed by tooling.
+
+As a result, the Metadata module provides support for building, scaffolding, and
+verifying metadata information about a collection of SVG assets. Under the hood,
+this module will build up a registry of all available assets and compare them
+against metadata files called "extensions". These files are typically written in
+YAML and are separated to make authoring of specific types of data easier.
+
+In general, we support the following extension types:
+
+- Icons: provides information for icons available from the source directory of
+  SVG assets
+- Categories: provides category and subcategory information for a collection of
+  icons
+- Module name: provides computed names used in code for an icon
+- Deprecations: provides a listing of icons that have been deprecated and
+  details how to update usage to the preferred format
+
+To support the above use-cases, Metadata makes use of the following concepts:
+
+- [Registry](./registry.js): build up a source of truth for all available SVG
+  assets in a source tree
+- [Extensions](./extensions/index.js): distinct sources of metadata captured for
+  icons. These modules provide support for verifying file structure, extending
+  the resulting output metadata, and logical checks to verify information
+  present (or not present) in these files
+- [Adapters](./adapters.js): provide support for authoring metadata in a variety
+  of formats, we currently author in YAML
+- [Storage](./storage.js): ability to read and write extension files for a given
+  adapter

package/src/metadata/adapters/index.js

@@ -0,0 +1,34 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ * 
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Copyright IBM Corp. 2020, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+const memory = require('./memory');
+const yml = require('./yml');
+
+/**
+ * An adapter defines how we work with a specific file format and defines the
+ * operations for reading and writing files of that type for a particular
+ * location
+ * @typedef {object} Adapter
+ * @property {Function} read
+ * @property {Function} write
+ */
+
+module.exports = {
+  memory,
+  yml,
+};

package/src/metadata/adapters/memory.js

@@ -0,0 +1,55 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ * 
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Copyright IBM Corp. 2020, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+const path = require('path');
+
+const filesystem = new Map();
+
+/**
+ * @param {string} directory
+ * @param {string} name
+ * @returns {Promise<any>}
+ */
+async function read(directory, name) {
+  const filepath = path.join(directory, path.format({ name }));
+
+  if (filesystem.has(filepath)) {
+    return filesystem.get(filepath);
+  }
+
+  throw new Error(
+    `Unable to find extension \`${name}\` at filepath: ${filepath}`
+  );
+}
+
+/**
+ * @param {string} directory
+ * @param {string} name
+ * @param {any} data
+ * @returns {Promise<void>}
+ */
+async function write(directory, name, data) {
+  const filepath = path.join(directory, path.format({ name }));
+  filesystem.set(filepath, data);
+}
+
+module.exports = {
+  read,
+  write,
+  filesystem,
+};

package/src/metadata/adapters/yml.js

@@ -0,0 +1,92 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ * 
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Copyright IBM Corp. 2020, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+const path = require('path');
+
+/**
+ * Get the filename for a given path basename. This is helpful to
+ * figure out which file we need to load in from the filesystem for the given
+ * adapter.
+ * @param {string} name
+ * @returns {string}
+ */
+function getFilenameFor(name) {
+  return path.format({
+    name,
+    ext: '.yml',
+  });
+}
+
+/**
+ * Serialize the given data to a YML format
+ * @param {object} data
+ * @returns {string}
+ */
+function serialize(data) {
+  return yaml.safeDump(data);
+}
+
+/**
+ * Deserialize the given YML data to JavaScript
+ * @param {object} data
+ * @returns {string}
+ */
+function deserialize(data) {
+  return yaml.safeLoad(data);
+}
+
+/**
+ * @param {string} directory
+ * @param {string} name
+ * @returns {Promise<any>}
+ */
+async function read(directory, name) {
+  const filepath = path.join(directory, getFilenameFor(name));
+
+  if (!(await fs.pathExists(filepath))) {
+    throw new Error(
+      `Unable to find extension \`${name}\` at filepath: ` +
+        `${filepath}. Either create the file or update the extension ` +
+        `to be computed.`
+    );
+  }
+
+  return deserialize(await fs.readFile(filepath, 'utf8'));
+}
+
+/**
+ * @param {string} directory
+ * @param {string} name
+ * @param {any} data
+ * @returns {Promise<void>}
+ */
+async function write(directory, name, data) {
+  const filepath = path.join(directory, getFilenameFor(name));
+
+  await fs.ensureFile(filepath);
+  await fs.writeFile(filepath, serialize(data), 'utf8');
+}
+
+module.exports = {
+  serialize,
+  deserialize,
+  read,
+  write,
+};

package/src/metadata/extension.js

@@ -0,0 +1,92 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ * 
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Copyright IBM Corp. 2020, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+/**
+ * @typedef {object} Extension
+ * @property {string} name - the name of the extension
+ * @property {JoiSchema} [schema] - a schema that validates the structure of
+ * the file for an extension
+ * @property {Function} [extend] - add information for the extension to the
+ * output metadata structure
+ * @property {Function} [validate] - validate that the data available in the
+ * registry matches the data received for the extension
+ */
+
+/**
+ * @typedef {Function} ExtensionBuilder
+ * @param {object} config
+ * @returns {Extension}
+ */
+
+/**
+ * @param {Extension} extension
+ * @returns {void}
+ */
+function validate(extension) {
+  if (!extension.name) {
+    throw new Error(
+      `Expected extension to have a name, instead received: \`${extension.name}\``
+    );
+  }
+}
+
+/**
+ * @param {(ExtensionBuilder | [Extension, object])} builderOrOptions
+ * @returns {Extension}
+ */
+function loadExtension(builderOrOptions) {
+  if (Array.isArray(builderOrOptions)) {
+    const [builder, options] = builderOrOptions;
+    const extension = builder(options);
+    validate(extension);
+    return extension;
+  }
+  const extension = builderOrOptions();
+  validate(extension);
+  return extension;
+}
+
+/**
+ * @param {Array<ExtensionBuilder | [Extension, object]>} [builderOrOptions]
+ * @returns {Array<Extension>}
+ */
+function load(builderOrOptions = []) {
+  const extensions = builderOrOptions.map(loadExtension);
+  const runOrder = [];
+
+  function order(extension) {
+    const match = runOrder.find((entry) => entry.name === extension.name);
+    if (match) {
+      return;
+    }
+
+    if (Array.isArray(extension.before)) {
+      extension.before.map(loadExtension).forEach(order);
+    }
+
+    runOrder.push(extension);
+  }
+
+  extensions.forEach(order);
+
+  return runOrder;
+}
+
+module.exports = {
+  load,
+};

package/src/metadata/extensions/assets.js

@@ -0,0 +1,45 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ * 
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Copyright IBM Corp. 2020, 2023
+ *
+ * This assets code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this assets tree.
+ */
+
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+
+/**
+ * Provide source and filepath asset information for a given icon
+ * @type {Extension}
+ */
+const assets = () => {
+  return {
+    name: 'assets',
+    computed: true,
+    extend(metadata, _data, registry, { input }) {
+      for (const entry of metadata.icons) {
+        const icon = registry.get(entry.name);
+        entry.assets = icon.assets.map(({ size, filepath }) => {
+          return {
+            size,
+            filepath: path.relative(input.svg, filepath),
+            source: fs.readFileSync(filepath, 'utf8'),
+          };
+        });
+      }
+    },
+  };
+};
+
+module.exports = assets;

package/src/metadata/extensions/categories.js

@@ -0,0 +1,141 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ * 
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Copyright IBM Corp. 2020, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+const Joi = require('@hapi/joi');
+
+// Supports both top-level categories and subcategories
+//
+// categories:
+// - name: Category name
+//   members:
+//   - Member 1
+//   - Member 2
+//
+// categories:
+// - name: Category name
+//   subcategories:
+//   - name: Subcategory name
+//     members:
+//     - Member 1
+//     - Member 2
+const categories = () => {
+  return {
+    name: 'categories',
+
+    schema: Joi.object().keys({
+      categories: Joi.array()
+        .items(
+          Joi.object().keys({
+            name: Joi.string().required(),
+            members: Joi.array().items(Joi.string()),
+            subcategories: Joi.array().items(
+              Joi.object().keys({
+                name: Joi.string().required(),
+                members: Joi.array().items(Joi.string()).required(),
+              })
+            ),
+          })
+        )
+        .required(),
+    }),
+
+    extend(metadata, data) {
+      const { categories } = data;
+
+      metadata.categories = categories;
+
+      for (const category of categories) {
+        const { name, members, subcategories } = category;
+
+        if (Array.isArray(subcategories)) {
+          for (const subcategory of subcategories) {
+            for (const member of subcategory.members) {
+              const icon = metadata.icons.find(({ name }) => name === member);
+              icon.category = name;
+              icon.subcategory = subcategory.name;
+            }
+          }
+          continue;
+        }
+
+        for (const member of members) {
+          const icon = metadata.icons.find(({ name }) => name === member);
+          icon.category = name;
+        }
+      }
+    },
+
+    validate(registry, data) {
+      // Flatten the category data into a flat list of members with corresponding
+      // name and category data
+      const members = [];
+
+      for (const category of data.categories) {
+        if (Array.isArray(category.subcategories)) {
+          for (const subcategory of category.subcategories) {
+            for (const member of subcategory.members) {
+              members.push({
+                name: member,
+                category: category.name,
+                subcategory: subcategory.name,
+              });
+            }
+          }
+          continue;
+        }
+
+        for (const member of category.members) {
+          members.push({
+            name: member,
+            category: category.name,
+          });
+        }
+      }
+
+      // Verify that every asset in the registry has category information
+      for (const icon of registry.values()) {
+        const match = members.find((member) => member.name === icon.id);
+        if (!match) {
+          const filepaths = icon.assets.map((asset) => asset.filepath);
+          throw new Error(
+            `Expected the following icon to have category information: ` +
+              `\`${icon.id}\`. This icon has assets in the following locations:\n` +
+              filepaths.join('\n')
+          );
+        }
+      }
+
+      // Verify that every asset with a category exists in the registry
+      for (const member of members) {
+        if (!registry.has(member.name)) {
+          let categoryPath = `category \`${member.category}\``;
+          if (member.subcategory) {
+            categoryPath += `, subcategory \`${member.subcategory}\``;
+          }
+          throw new Error(
+            `Found the entry \`${member.name}\` in ${categoryPath} that does ` +
+              `not have a corresponding icon or asset. Either this icon does ` +
+              `not exist, or is not available in the current directory.`
+          );
+        }
+      }
+    },
+  };
+};
+
+module.exports = categories;

package/src/metadata/extensions/deprecated.js

@@ -0,0 +1,73 @@
+/**
+ * Copyright OctaviaFlow
+ * Author: Vishal Kumar
+ * Created: 11/November/2025
+ * 
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Copyright IBM Corp. 2020, 2023
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+'use strict';
+
+const Joi = require('@hapi/joi');
+
+// Supports a list of deprecated assets
+//
+// deprecated:
+//   - name: asset-name-1
+//   - name: asset-name-2
+//
+// In the future, we may want to include a reason for the deprecation, or a
+// notice for what icon to use instead.
+const deprecated = () => {
+  return {
+    name: 'deprecated',
+
+    schema: Joi.object().keys({
+      deprecated: Joi.array()
+        .items(
+          Joi.object().keys({
+            name: Joi.string().required(),
+            reason: Joi.string(),
+          })
+        )
+        .required(),
+    }),
+
+    extend(metadata, data) {
+      const { deprecated } = data;
+
+      for (const icon of metadata.icons) {
+        const entry = deprecated.find(({ name }) => name === icon.name);
+        if (entry) {
+          icon.deprecated = true;
+          if (entry.reason) {
+            icon.reason = entry.reason;
+          }
+        }
+      }
+    },
+
+    validate(registry, data) {
+      for (const icon of data.deprecated) {
+        const entry = registry.has(icon.name);
+        if (!entry) {
+          throw new Error(
+            `Expected the deprecated icon \`${icon.name}\` to exist. Either ` +
+              `this icon does not exist, or is not available in the given SVG ` +
+              `directory`
+          );
+        }
+      }
+    },
+  };
+};
+
+module.exports = deprecated;