@octaviaflow/icon-build-helpers 1.0.0

package/README.md

@@ -0,0 +1,50 @@
+# @octaviaflow/icon-build-helpers
+
+> Build helpers for the Carbon Design System icon library
+
+## Getting started
+
+To install `@octaviaflow/icon-build-helpers` in your project, you will need to run
+the following command using [npm](https://www.npmjs.com/):
+
+```bash
+npm install -S @octaviaflow/icon-build-helpers
+```
+
+If you prefer [Yarn](https://yarnpkg.com/en/), use the following command
+instead:
+
+```bash
+yarn add @octaviaflow/icon-build-helpers
+```
+
+## Usage
+
+`@octaviaflow/icon-build-helpers` is a private module in the Carbon Design System
+monorepo. The purpose of this module is to centralize tooling for:
+
+- Searching a directory of `.svg` assets and structuring them in terms of size
+  and prefixes
+- Custom builders for various libraries, which currently include:
+  - Vanilla
+  - React
+- Implementing repo status checks in CI around icon metadata files, namely
+  `metadata.yml` and `categories.yml`
+
+As a result, these file power the generation of the following SVG-based
+projects:
+
+- `@octaviaflow/icons`
+- `@octaviaflow/icons-react`
+- `@octaviaflow/pictograms`
+- `@octaviaflow/pictograms-react`
+
+## 🙌 Contributing
+
+We're always looking for contributors to help us fix bugs, build new features,
+or help us improve the project documentation. If you're interested, definitely
+check out our [Contributing Guide](/.github/CONTRIBUTING.md)! 👀
+
+## 📝 License
+
+Licensed under the [Apache 2.0 License](/LICENSE).

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@octaviaflow/icon-build-helpers",
+  "description": "Build helpers for the OctaviaFlow Design System icon library",
+  "version": "1.0.0",
+  "license": "Apache-2.0",
+  "main": "src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/octaviaflow-design-system.git",
+    "directory": "packages/icon-build-helpers"
+  },
+  "bugs": "https://github.com/octaviaflow-design-system/issues",
+  "keywords": [
+    "octaviaflow",
+    "icon-build-helpers",
+    "components",
+    "react"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@babel/core": "^7.24.7",
+    "@babel/generator": "^7.24.7",
+    "@babel/preset-env": "^7.24.7",
+    "@babel/preset-react": "^7.24.7",
+    "@babel/template": "^7.24.7",
+    "@babel/types": "^7.24.7",
+    "@hapi/joi": "^17.1.1",
+    "@octaviaflow/cli-reporter": "^1.0.0",
+    "@octaviaflow/icon-helpers": "^1.0.0",
+    "@rollup/plugin-babel": "^6.0.0",
+    "@rollup/plugin-replace": "^6.0.0",
+    "browserslist-config-octaviaflow": "^1.0.0",
+    "change-case": "^4.1.1",
+    "core-js": "^3.16.0",
+    "fs-extra": "^11.0.0",
+    "js-yaml": "^3.12.1",
+    "klaw-sync": "^6.0.0",
+    "memfs": "^4.0.0",
+    "prettier": "^3.3.3",
+    "prop-types": "^15.6.2",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "rimraf": "^6.0.0",
+    "rollup": "^2.79.1",
+    "rollup-plugin-strip-banner": "^3.0.0",
+    "svg-parser": "^2.0.4",
+    "svgo": "^1.1.1",
+    "svgson": "^5.2.1",
+    "typescript": "^5.9.3",
+    "typescript-config-octaviaflow": "^1.0.0"
+  },
+  "devDependencies": {}
+}

package/src/builders/index.js

@@ -0,0 +1,33 @@
+/**
+ * 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 react = require('./react/builder');
+const reactNext = require('./react/next');
+const svg = require('./svg');
+const vanilla = require('./vanilla');
+
+const builders = {
+  react: {
+    run: react,
+  },
+  reactNext: {
+    run: reactNext,
+  },
+  svg: {
+    run: svg,
+  },
+  vanilla: {
+    run: vanilla,
+  },
+};
+
+module.exports = builders;

package/src/builders/plugins/virtual.js

@@ -0,0 +1,51 @@
+/**
+ * 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 path = require('path');
+
+// Mirror of: https://github.com/rollup/rollup-plugin-virtual without the \0
+// prefix which noops in a lot of plugins
+const PREFIX = 'virtual:';
+
+module.exports = function virtual(modules) {
+  const resolvedIds = new Map();
+
+  Object.keys(modules).forEach((id) => {
+    resolvedIds.set(path.resolve(id), modules[id]);
+  });
+
+  return {
+    name: 'virtual',
+
+    resolveId(id, importer) {
+      if (id in modules) {
+        return PREFIX + id;
+      }
+
+      if (importer) {
+        if (importer.startsWith(PREFIX)) {
+          importer = importer.slice(PREFIX.length);
+        }
+        const resolved = path.resolve(path.dirname(importer), id);
+        if (resolvedIds.has(resolved)) {
+          return PREFIX + resolved;
+        }
+      }
+    },
+
+    load(id) {
+      if (id.startsWith(PREFIX)) {
+        id = id.slice(PREFIX.length);
+
+        return id in modules ? modules[id] : resolvedIds.get(id);
+      }
+    },
+  };
+};

package/src/builders/react/builder.js

@@ -0,0 +1,313 @@
+/**
+ * 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 { babel } = require("@rollup/plugin-babel");
+const { camelCase } = require("change-case");
+const fs = require("fs-extra");
+const path = require("path");
+const { rollup } = require("rollup");
+const virtual = require("../plugins/virtual");
+
+const BANNER = `/**
+ * Copyright IBM Corp. 2019, 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 external = ["@octaviaflow/icon-helpers", "react", "prop-types"];
+const babelConfig = {
+  babelrc: false,
+  exclude: /node_modules/,
+  presets: [
+    [
+      "@babel/preset-env",
+      {
+        targets: {
+          browsers: ["extends browserslist-config-octaviaflow"],
+        },
+      },
+    ],
+    "@babel/preset-react",
+    "@babel/preset-typescript",
+  ],
+  plugins: [
+    "@babel/plugin-transform-react-constant-elements",
+    "babel-plugin-dev-expression",
+  ],
+  babelHelpers: "bundled",
+  extensions: [".ts", ".tsx", ".js", ".jsx"],
+};
+
+async function builder(metadata, { output }) {
+  // Using the metadata, we can build up a list of modules that we want included
+  // in the different bundles we ship.
+  //
+  // For each module, we need to create two ways of consuming it. The first way
+  // is as a dedicated module, the second as a single function that we could
+  // export in an entrypoint.
+  const modules = metadata.icons.flatMap((icon) => {
+    return icon.output.map((size) => {
+      return {
+        source: createIconFlatExport(
+          size.moduleName,
+          size.descriptor,
+          icon.deprecated,
+        ),
+        entrypoint: createIconEntrypoint(
+          size.moduleName,
+          size.descriptor,
+          icon.deprecated,
+        ),
+        filepath: size.filepath,
+        moduleName: size.moduleName,
+      };
+    });
+  });
+
+  // Given the current size of our icons (~5000 modules) we need to split up the
+  // entrypoint into chunks. In the past, we tried re-exporting from the source
+  // but this ended up causing slowdowns due to module resolution.
+  //
+  // As a result, we sort our list of modules into buckets and generate
+  // entrypoints based on those. Then, the root `index.js` file re-exports from
+  // these entrypoints. This is a hybrid approach between a single entrypoint
+  // that is too big for most tooling, and a re-export strategy that takes too
+  // long due to the number of modules along with the time it takes tooling to
+  // process them.
+  const BUCKET_SIZE = 250;
+  const BUCKET_COUNT = Math.ceil(modules.length / BUCKET_SIZE);
+  const buckets = Array(BUCKET_COUNT);
+
+  for (let i = 0; i < buckets.length; i++) {
+    const start = BUCKET_SIZE * i;
+    const end = Math.min(start + BUCKET_SIZE, modules.length) - 1;
+    const bucket = Array(end - start + 1);
+
+    for (let j = start; j <= end; j++) {
+      bucket[j - start] = modules[j];
+    }
+
+    buckets[i] = bucket;
+  }
+
+  const files = {
+    "index.ts": `${BANNER}\n\nexport { default as Icon } from './Icon.tsx';`,
+  };
+  const input = {
+    "index.js": "index.ts",
+    "Icon.js": "./Icon.tsx",
+  };
+  for (const m of modules) {
+    files[m.filepath] = m.entrypoint;
+    input[m.filepath] = m.filepath;
+  }
+
+  for (let i = 0; i < buckets.length; i++) {
+    const bucket = buckets[i];
+    const filename = `__generated__/bucket-${i}.js`;
+
+    input[filename] = filename;
+    files[filename] = `${BANNER}
+
+import React from 'react';
+import Icon from './Icon.tsx';
+
+const didWarnAboutDeprecation = {};`;
+
+    for (const m of bucket) {
+      files[filename] += `export ${m.source}`;
+      files["index.ts"] += `export { ${m.moduleName} } from '${filename}';`;
+    }
+  }
+
+  const bundle = await rollup({
+    input,
+    external,
+    plugins: [
+      virtual({
+        "./Icon.tsx": await fs.readFile(
+          path.resolve(__dirname, "./components/Icon.tsx"),
+          "utf8",
+        ),
+        ...files,
+      }),
+      babel(babelConfig),
+    ],
+  });
+
+  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.ts",
+    external,
+    plugins: [
+      virtual({
+        "./Icon.tsx": await fs.readFile(
+          path.resolve(__dirname, "./components/Icon.tsx"),
+          "utf8",
+        ),
+        ...files,
+      }),
+      babel(babelConfig),
+    ],
+  });
+
+  await umd.write({
+    file: path.join(output, "umd/index.js"),
+    format: "umd",
+    name: "CarbonIconsReact",
+    globals: {
+      "@octaviaflow/icon-helpers": "CarbonIconHelpers",
+      "prop-types": "PropTypes",
+      react: "React",
+    },
+  });
+}
+
+/**
+ * Convert the given node to a JSX string source
+ * @param {object} node
+ * @returns {string}
+ */
+function convertToJSX(node) {
+  const { elem, attrs } = node;
+  return `<${elem} ${formatAttributes(attrs)} />`;
+}
+
+const attributeDenylist = ["data", "aria"];
+
+/**
+ * Determine if the given attribute should be transformed when being converted
+ * to a React prop or if we should pass it through as-is
+ * @param {string} attribute
+ * @returns {boolean}
+ */
+function shouldTransformAttribute(attribute) {
+  return attributeDenylist.every((prefix) => !attribute.startsWith(prefix));
+}
+
+/**
+ * Serialize a given object of key, value pairs to an JSX-compatible string
+ * @param {object} attrs
+ * @returns {string}
+ */
+function formatAttributes(attrs) {
+  return Object.keys(attrs).reduce((acc, key, index) => {
+    const attribute = shouldTransformAttribute(key)
+      ? `${camelCase(key)}="${attrs[key]}"`
+      : `${key}="${attrs[key]}"`;
+
+    if (index === 0) {
+      return attribute;
+    }
+    return acc + " " + attribute;
+  }, "");
+}
+
+function createIconFlatExport(moduleName, descriptor, isDeprecated = false) {
+  const deprecatedBlock = isDeprecated
+    ? `
+    if (__DEV__) {
+      if (!didWarnAboutDeprecation['${moduleName}']) {
+        didWarnAboutDeprecation['${moduleName}'] = true;
+        console.warn(
+          \`The ${moduleName} component has been deprecated and will be \` +
+          \`removed in the next major version of @octaviaflow/icons-react.\`
+        );
+      }
+    }
+    `
+    : "";
+  return createIconSource(moduleName, descriptor, deprecatedBlock);
+}
+
+function createIconEntrypoint(moduleName, descriptor, isDeprecated = false) {
+  const deprecatedPreamble = isDeprecated
+    ? "let didWarnAboutDeprecation = false;"
+    : "";
+  const deprecatedBlock = isDeprecated
+    ? `
+    if (__DEV__) {
+      if (!didWarnAboutDeprecation) {
+        didWarnAboutDeprecation = true;
+        console.warn(
+          \`The ${moduleName} component has been deprecated and will be \` +
+          \`removed in the next major version of @octaviaflow/icons-react.\`
+        );
+      }
+    }
+    `
+    : "";
+  const source = createIconSource(moduleName, descriptor, deprecatedBlock);
+  return `${BANNER}
+import React from 'react';
+import Icon from './Icon.tsx';
+${deprecatedPreamble}
+${source}
+export default ${moduleName};
+`;
+}
+
+/**
+ * Generate an icon component, which in our case is the string representation
+ * of the component, from a given moduleName and icon descriptor.
+ * @param {string} moduleName
+ * @param {object} descriptor
+ * @param {string} customBlock
+ */
+function createIconSource(moduleName, descriptor, customBlock = "") {
+  const { attrs, content } = descriptor;
+  const { width, height, viewBox, ...rest } = attrs;
+  return `
+    const ${moduleName} = /*#__PURE__*/ React.forwardRef(
+      function ${moduleName}({ children, ...rest }, ref) {
+        ${customBlock}
+        return (
+          <Icon
+            width={${width}}
+            height={${height}}
+            viewBox="${viewBox}"
+            ${formatAttributes(rest)}
+            ref={ref}
+            {...rest}>
+            ${content.map(convertToJSX).join("\n")}
+            {children}
+          </Icon>
+        );
+      }
+    );
+  `;
+}
+
+module.exports = builder;

package/src/builders/react/components/CarbonIcon.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+import { IconProps } from './Icon';
+
+export interface CarbonIconProps extends IconProps {
+  size?: number | string;
+}
+
+export type CarbonIconType = React.ForwardRefExoticComponent<
+  CarbonIconProps & React.RefAttributes<React.ReactSVGElement>
+>;

package/src/builders/react/components/Icon.tsx

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+
+import { getAttributes } from '@octaviaflow/icon-helpers';
+import PropTypes from 'prop-types';
+import React from 'react';
+
+export interface IconProps
+  extends Omit<React.SVGProps<React.ReactSVGElement>, 'ref' | 'tabIndex'> {
+  /**
+   * @see React.SVGAttributes.tabIndex
+   * @todo remove support for string in v12
+   */
+  tabIndex?: string | number | undefined;
+
+  title?: string | undefined;
+}
+
+const Icon = React.forwardRef(function Icon(
+  {
+    className,
+    children,
+    tabIndex,
+    xmlns = 'http://www.w3.org/2000/svg',
+    preserveAspectRatio = 'xMidYMid meet',
+    ...rest
+  }: IconProps,
+  ref: React.ForwardedRef<React.ReactSVGElement>
+) {
+  const { tabindex, ...attrs } = getAttributes({
+    ...rest,
+    tabindex: tabIndex,
+  });
+  const props: React.SVGProps<React.ReactSVGElement> = attrs;
+
+  if (className) {
+    props.className = className;
+  }
+
+  if (tabindex !== undefined && tabindex !== null) {
+    if (typeof tabindex === 'number') {
+      props.tabIndex = tabindex;
+    } else {
+      props.tabIndex = Number(tabIndex);
+    }
+  }
+
+  if (ref) {
+    props.ref = ref;
+  }
+
+  if (xmlns) {
+    props.xmlns = xmlns;
+  }
+
+  if (preserveAspectRatio) {
+    props.preserveAspectRatio = preserveAspectRatio;
+  }
+
+  return React.createElement('svg', props, children);
+});
+
+Icon.displayName = 'Icon';
+Icon.propTypes = {
+  'aria-hidden': PropTypes.oneOfType([
+    PropTypes.bool,
+    PropTypes.oneOf<'true' | 'false'>(['true', 'false']),
+  ]),
+  'aria-label': PropTypes.string,
+  'aria-labelledby': PropTypes.string,
+  children: PropTypes.node,
+  className: PropTypes.string,
+  height: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
+  preserveAspectRatio: PropTypes.string,
+  tabIndex: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
+  viewBox: PropTypes.string,
+  width: PropTypes.oneOfType([PropTypes.number, PropTypes.string]),
+  xmlns: PropTypes.string,
+};
+
+export default Icon;

package/src/builders/react/next/babel.js

@@ -0,0 +1,37 @@
+/**
+ * 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 babelConfig = {
+  babelrc: false,
+  exclude: /node_modules/,
+  presets: [
+    [
+      "@babel/preset-env",
+      {
+        targets: {
+          browsers: ["extends browserslist-config-octaviaflow"],
+        },
+      },
+    ],
+    "@babel/preset-react",
+    "@babel/preset-typescript",
+  ],
+  plugins: [
+    "@babel/plugin-transform-react-constant-elements",
+    "babel-plugin-dev-expression",
+  ],
+  babelHelpers: "bundled",
+  extensions: [".ts", ".tsx", ".js", ".jsx"],
+};
+
+module.exports = {
+  babelConfig,
+};