feat: Custom getIconID option

- Configurable `getIconId` option

Author: tancredi

README.md

@@ -35,7 +35,7 @@ fantasticon my-icons -o icon-dist
 
 ### Command-line
 
-**Note:** Not all options can be specified through the command line - for `formatOptions`, `pathOptions` and `templates` use a [configuration file](#configuration-file) or the JavaScript API.
+**Note:** Not all options can be specified through the command line - for `formatOptions`, `pathOptions`, `getIconId` and `templates` use a [configuration file](#configuration-file) or the JavaScript [API](#api).
 
 ```
 Usage: fantasticon [options] [input-dir]
@@ -62,7 +62,7 @@ Options:
 
 ### Configuration file
 
-Some options (specifically, `formatOptions` and `pathOptions`) cannot be passed to the CLI directly.
+Some options (specifically, `formatOptions`, `pathOptions` and `getIconId`) cannot be passed to the CLI directly.
 
 To have more control and better readability, you can create a simple configuration file.
 
@@ -113,7 +113,15 @@ module.exports = {
     'chevron-right': 57345,
     'thumbs-up': 57358,
     'thumbs-down': 57359
-  }
+  },
+  // Customize generated icon IDs (unavailable with `.json` config file)
+  getIconId: ({
+    basename, // `string` - Example: 'foo';
+    relativeDirPath, // `string` - Example: 'sub/dir/foo.svg'
+    absoluteFilePath, // `string` - Example: '/var/icons/sub/dir/foo.svg'
+    relativeFilePath, // `string` - Example: 'foo.svg'
+    index // `number` - Example: `0`
+  }) => [index, basename].join('_') // '0_foo'
 };
 ```
 
@@ -186,6 +194,8 @@ And the generated icon IDs would be:
 | `symbol-chevron-left`  | `.icon.icon-chevron-left`    |
 | `symbol-chevron-right` | `.icon.icon-chevron-right`   |
 
+You can provide a `getIconId` function via the configuration file to customize how the icon IDs / CSS selectors are derived from the filepath. The function will receive relative paths to the icon and the input directory as arguments, and must return a unique string to be used as the ID.
+
 ### Contribute
 
 PRs are always welcome. If you need help questions, want to bounce ideas or just say hi, [join the Discord channel](https://discord.gg/BXAY3Kc3mp).

src/__mocks__/path.ts

@@ -7,7 +7,7 @@ const resolve = (...paths: string[]) => {
   let path = '';
 
   for (const cur of paths) {
-    path = !path ? normalise(cur) : _path.join(path, normalise(cur));
+    path = !path ? normalize(cur) : _path.join(path, normalize(cur));
   }
 
   if (path.startsWith(projectDir)) {
@@ -22,11 +22,11 @@ const resolve = (...paths: string[]) => {
     }
   }
 
-  return normalise(path);
+  return normalize(path);
 };
 
 const relative = (a: string, b: string) =>
-  normalise(_relative(_path.normalize(a), _path.normalize(b)));
+  normalize(_relative(_path.normalize(a), _path.normalize(b)));
 
 const join = (...segments: string[]): string => {
   const trimmed: string[] = [];
@@ -49,8 +49,8 @@ const join = (...segments: string[]): string => {
   return trimmed.join('/');
 };
 
-const normalise = (path: string) => path.replace(/\\/g, '/');
+const normalize = (path: string) => path.replace(/\\/g, '/');
 
 const isAbsolute = (path: string) => path.startsWith('/root');
 
-module.exports = { resolve, relative, join, isAbsolute };
+module.exports = { resolve, relative, join, isAbsolute, normalize };

src/constants.ts

@@ -1,6 +1,7 @@
 import { resolve } from 'path';
 import { RunnerOptions } from './types/runner';
 import { FontAssetType, OtherAssetType } from './types/misc';
+import { getIconId } from './utils/icon-id';
 
 export const TEMPLATES_DIR = resolve(__dirname, '../templates');
 
@@ -24,7 +25,8 @@ export const DEFAULT_OPTIONS: Omit<RunnerOptions, 'inputDir' | 'outputDir'> = {
   selector: null,
   tag: 'i',
   prefix: 'icon',
-  fontsUrl: undefined
+  fontsUrl: undefined,
+  getIconId: getIconId
 };
 
 export const DEFAULT_START_CODEPOINT = 0xf101;

src/core/__tests__/config-parser.ts

@@ -1,5 +1,6 @@
 import { parseConfig } from '../config-parser';
 import { checkPath } from '../../utils/fs-async';
+import { DEFAULT_OPTIONS } from '../../constants';
 
 const checkPathMock = (checkPath as any) as jest.Mock;
 
@@ -32,7 +33,8 @@ const mockConfig = {
     sass: 'sass',
     scss: 'scss',
     html: 'html'
-  }
+  },
+  getIconId: DEFAULT_OPTIONS.getIconId
 };
 
 const testError = async (options: object, key: string, message: string) =>
@@ -87,6 +89,7 @@ describe('Config parser', () => {
       'normalize',
       'must be a boolean value'
     );
+    await testError({ getIconId: true }, 'getIconId', 'true is not a function');
   });
 
   test('correctly validates existance of input and output paths', async () => {

src/core/__tests__/runner.ts

@@ -114,7 +114,11 @@ describe('Runner', () => {
     await generateFonts(optionsIn);
 
     expect(loadAssetsMock).toHaveBeenCalledTimes(1);
-    expect(loadAssetsMock).toHaveBeenCalledWith(inputDir);
+    expect(loadAssetsMock).toHaveBeenCalledWith({
+      ...DEFAULT_OPTIONS,
+      ...optionsIn,
+      parsed: true
+    });
   });
 
   test('`generateFonts` calls `getGeneratorOptions` correctly', async () => {

src/core/config-parser.ts

@@ -4,6 +4,7 @@ import {
   parseDir,
   parseString,
   parseBoolean,
+  parseFunction,
   listMembersParser,
   parseNumeric,
   optional,
@@ -30,7 +31,8 @@ const CONFIG_VALIDATORS: {
   selector: [nullable(parseString)],
   tag: [parseString],
   prefix: [parseString],
-  fontsUrl: [optional(parseString)]
+  fontsUrl: [optional(parseString)],
+  getIconId: [optional(parseFunction)]
 };
 
 export const parseConfig = async (input: object = {}) => {

src/core/runner.ts

@@ -41,7 +41,7 @@ export const generateFonts = async (
     throw new Error('You must specify an output directory');
   }
 
-  const assetsIn = await loadAssets(options.inputDir);
+  const assetsIn = await loadAssets(options);
   const generatorOptions = getGeneratorOptions(options, assetsIn);
   const assetsOut = await generateAssets(generatorOptions);
   const writeResults = outputDir ? await writeAssets(assetsOut, options) : [];

src/index.ts

@@ -2,7 +2,9 @@ export {
   FontAssetType,
   OtherAssetType,
   ASSET_TYPES,
-  AssetType
+  AssetType,
+  GetIconIdFn,
+  GetIconIdOptions
 } from './types/misc';
 
 export { RunnerOptions } from './types/runner';

src/types/misc.ts

@@ -25,3 +25,13 @@ export const ASSET_TYPES_WITH_TEMPLATE = [
 export const ASSET_TYPES = { ...FontAssetType, ...OtherAssetType };
 
 export type AssetType = FontAssetType | OtherAssetType;
+
+export interface GetIconIdOptions {
+  basename: string;
+  relativeDirPath: string;
+  absoluteFilePath: string;
+  relativeFilePath: string;
+  index: number;
+}
+
+export type GetIconIdFn = (options: GetIconIdOptions) => string;

src/types/runner.ts

@@ -1,5 +1,5 @@
 import { CodepointsMap } from '../utils/codepoints';
-import { FontAssetType, OtherAssetType, AssetType } from './misc';
+import { FontAssetType, OtherAssetType, AssetType, GetIconIdFn } from './misc';
 import { FormatOptions } from './format';
 
 export interface RunnerMandatoryOptions {
@@ -23,6 +23,7 @@ export type RunnerOptionalOptions = {
   templates: { [key in OtherAssetType]?: string };
   prefix: string;
   fontsUrl: string;
+  getIconId: GetIconIdFn;
 };
 
 export type RunnerOptionsInput = RunnerMandatoryOptions &