@uxf/icons-generator 10.0.0 → 11.0.0

package/README.md

@@ -1,19 +1,20 @@
 # @uxf/icons-generator
+A well configurable tool for generating and managing custom SVG icons and sprites in web projects.
 
-## Quick start
+## Quick Start
 
-### Install
-```
+### Installation
+Use npm or yarn to install:
+```bash
 npm i -D @uxf/icons-generator
 ```
-
-or use yarn
-```
+```bash
 yarn add -D @uxf/icons-generator
 ```
 
-### Create simple JS config file (`icons.config.js`) in your root folder
-```js
+### Configuration
+Create a `icons.config.ts` file in your project's root:
+```ts
 module.exports = {
     icons: {
         test: {
@@ -24,35 +25,37 @@ module.exports = {
     }
 }
 ```
-Full list of config options is [here](#config).
+See the full configuration options [here](#config).
 
-### Run generator
-```
+### Generating Icons
+Run the generator:
+```bash
 icons-gen
 ```
-
-Or, if you need to use different name for config file:
-```
+For a custom config file name:
+```bash
 icons-gen --configFile=yourConfigFileName.js
 ```
 
-## Config
-
-| key                     | type                         | default                                                               | required | description                         |
-|-------------------------|------------------------------|-----------------------------------------------------------------------|----------|-------------------------------------|
-| mode                    | `"simple" \                  | "sizes"`                                                              | `"simple"`                   |                                     |                                   |
-| typescript              | `boolean`                    | `true`                                                                |          |                                     |
-| configDirectory         | `string`                     | `"/src/config/"`                                                      |          |                                     |
-| generatedDirectory      | `string`                     | `"/public/icons-generated/"`                                          |          |                                     |
-| spriteFileName          | `string`                     | `undefined`                                                           |          | custom content to definition file   |
-| typeName                | `string`                      | `IconsSet`                                                             |          |                                     |
-| moduleDefinition        | `ModuleDefinition`           | `"{ moduleName: "icons", typeName: "IconsSet", format: "interface"}"` |                                                  | allows to generate module definiton |
-| customDefinitionContent | `string`                     | `"_icon-sprite.svg"`                                                  |          |                                     |
-| icons                   | `Record<string, SimpleIcon \ | SizedIcon>`                                                           |                              | yes                                 | find out more [here](#icon-types) |
-
-## Icon types
-### SimpleIcon (for mode "simple")
-#### Type
+## Configuration Details
+
+| Key                     | Type                                      | Default                                                               | Required | Description                      |
+|-------------------------|-------------------------------------------|-----------------------------------------------------------------------|----------|----------------------------------|
+| mode                    | `"simple" \| "sizes"`                     | `"simple"`                                                            | No       | -                                |
+| typescript              | `boolean`                                 | `true`                                                                | No       | -                                |
+| configDirectory         | `string`                                  | `"/src/config/"`                                                      | No       | -                                |
+| generatedDirectory      | `string`                                  | `"/public/icons-generated/"`                                          | No       | -                                |
+| spriteFileName          | `string`                                  | `undefined`                                                           | No       | Specify custom sprite file name  |
+| typeName                | `string`                                  | `IconsSet`                                                            | No       | -                                |
+| moduleDefinition        | `ModuleDefinition`                        | `"{ moduleName: "icons", typeName: "IconsSet", format: "interface"}"` | No       | Custom module definition         |
+| customDefinitionContent | `string`                                  | `"_icon-sprite.svg"`                                                  | No       | -                                |
+| icons                   | `Record<string, SimpleIcon \| SizedIcon>` | -                                                                     | Yes      | More details [here](#icon-types) |
+| adapters                | -                                         | -                                                                     | No       | More details [here](#adapters)   |
+| fallbackFilesDirectory  | -                                         | -                                                                     | No       | More details [here](#adapters)   |
+
+## Icon Types
+
+### SimpleIcon (mode "simple")
 ```ts
 type SimpleIcon = {
     data: string;
@@ -60,8 +63,7 @@ type SimpleIcon = {
     width: number;
 };
 ```
-
-#### Example
+Example:
 ```js
 test: {
     width: 50,
@@ -70,13 +72,11 @@ test: {
 }
 ```
 
-### SizedIcon (for mode "sizes")
-#### Type
+### SizedIcon (mode "sizes")
 ```ts
 type SizedIcon = Record<number, string>;
 ```
-
-#### Example
+Example:
 ```js
 test: {
     24: `<path fill="#fecd09" d="M33.03 17.44c-1.68 0-3.12-.99-3.79-2.42h7.58a4.181 4.181 0 01-3.79 2.42z" />`,
@@ -84,24 +84,69 @@ test: {
 }
 ```
 
-## Recommended use (step-by-step)
-### 1. Create config file in root folder of your project...
+## Adapters
+Extend icon generation with adapters for external sources.
 
-... and configure all icons you need.
+### Adapter Structure
+An adapter in this context is a function designed to retrieve specific icon information, such as size and SVG path, based on the icon's name.
 
-### 2. Generate icons
+#### Example
+```ts
+export const getIconFromMyCustomAdapter = (iconName: string) => {
+    const icon = findIconDefinition({ iconName });
+    return { width: icon.width, height: icon.height, path: icon.data };
+};
+```
 
-Run `icons-gen` to generate:
+Integration into your icons configuration is straightforward:
+```ts
+import { getIconFromMyCustomAdapter } from "./my-custom-adapter";
+
+adapters: {
+    myAdapter: {
+        icons: ["user"],
+        getIcon: getIconFromMyCustomAdapter,
+    }
+}
+```
+
+For type safety, you can create a typed configuration. Use a generated type from your icon list as a generic for the icons configuration:
+```ts
+const iconConfig: IconsConfig<{ myAdapter: MyAdapterIconNames; }> = {};
+```
+
+## Predefined adapters
 
-- SVG sprite file with all icons
-- Separate SVG files for each icon
-- "Definition file" which contains list of all icons and their sizes
-- "Config file" which contains current icons version and path to generated sprite file
+### Font Awesome Pro Adapter
+#### Local Development Setup
+```bash
+// Set registry and token
+npm config set "@fortawesome:registry" https://npm.fontawesome.com/
+npm config set "//npm.fontawesome.com/:_authToken" YOUR_TOKEN
 
-### 3. Setup your Icon component
+// Install package
+npm install --save-dev @fortawesome/fontawesome-pro
+```
+
+#### Without Private Key
+If your project already contains generated icons, installing the Font Awesome Pro package is not necessary.
+The package automatically generates a 'fallback file' for the icons in use, ensuring functionality even without
+Font Awesome Pro. However, while this setup allows for the continued use of existing icons, adding new icons
+from the adapter will not be possible.
+
+## Recommended Usage (Step-by-Step)
+
+### 1. Configuration
+Create and configure your icon settings in a config file at the project's root.
+
+### 2. Icon Generation
+Execute `icons-gen` to produce:
+- SVG sprite and individual files.
+- Definition file with icon list and sizes.
+- Config file with icon version and sprite path.
 
-Implement generator output to your project structure.
-Example for `typescript` and `React`:
+### 3. Icon Component Setup
+Incorporate the generated output into your project. Example for TypeScript and React:
 
 ```tsx
 import { ICONS, IconsSet } from "src/config/icons";
@@ -128,8 +173,7 @@ export const Icon: FC<IconProps> = ({ name }) => {
 };
 ```
 
-### 4. Preload your sprite (optional)
-
+### 4. Sprite Preloading (Optional)
 ```tsx
 import { ICON_SPRITE, ICONS_VERSION } from "src/config/icons-config";
 
@@ -145,11 +189,5 @@ import { ICON_SPRITE, ICONS_VERSION } from "src/config/icons-config";
 </Head>
 ```
 
-### 5. Check it
-
-To be sure, you have generated the last version of icons, run:
-```
-icons-check
-```
-This command compares icons with config file and fails, when icons doesn't match current config.
-We strongly recommend add this command to your CI.
+### 5. Verification
+Run `icons-check` to ensure icon consistency with the config. It's recommended to integrate this check into your CI process.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uxf/icons-generator",
-  "version": "10.0.0",
+  "version": "11.0.0",
   "description": "",
   "main": "index.js",
   "scripts": {
@@ -22,8 +22,8 @@
   "author": "",
   "license": "ISC",
   "bin": {
-    "icons-gen": "./scripts/gen.js",
-    "icons-check": "./scripts/check.js"
+    "icons-gen": "./src/scripts/gen.js",
+    "icons-check": "./src/scripts/check.js"
   },
   "bugs": {
     "url": "https://gitlab.com/uxf-npm/icons-generator/issues"

package/src/adapters/fa-pro.d.ts

@@ -0,0 +1,5 @@
+export declare const getFaProIcon: (adapterKey: string) => (iconName: string) => {
+    width: any;
+    height: any;
+    path: string;
+};

package/src/adapters/fa-pro.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getFaProIcon = void 0;
+const fs_1 = require("fs");
+const _getConfig_1 = require("../utils/_getConfig");
+const removeComments = (str) => str.replace(/<!--([\s\S]*?)-->/g, "");
+const removeSvg = (str) => str.replace(/<svg[^>]*>/, "").replace(/<\/svg>/, "");
+const addFillAttribute = (str) => str.replace(/\/>/g, ' fill="currentColor"/>');
+const parseDimensions = (str) => {
+    const viewBox = str.match(/viewBox="([^"]*)"/);
+    let width, height;
+    if (viewBox && viewBox[1]) {
+        [, , width, height] = viewBox[1].split(" ");
+    }
+    if (!width || !height) {
+        throw new Error("Can't parse width or height.");
+    }
+    return { width, height };
+};
+const getFaProIcon = (adapterKey) => (iconName) => {
+    const config = (0, _getConfig_1._getConfig)();
+    if ((0, fs_1.existsSync)("./node_modules/@fortawesome/fontawesome-pro")) {
+        const [namespace, icon] = iconName.split(".");
+        let svg = (0, fs_1.readFileSync)(`./node_modules/@fortawesome/fontawesome-pro/svgs/${namespace}/${icon}.svg`).toString();
+        svg = removeComments(svg);
+        const { width, height } = parseDimensions(svg);
+        svg = removeSvg(svg);
+        svg = addFillAttribute(svg);
+        return { width, height, path: svg };
+    }
+    try {
+        const fallbackPath = config.fallbackFilesDirectory + adapterKey + ".json";
+        const fileContent = (0, fs_1.readFileSync)(fallbackPath).toString();
+        const icon = JSON.parse(fileContent)[iconName];
+        return { width: icon.width, height: icon.height, path: decodeURIComponent(icon.path) };
+    }
+    catch (e) {
+        throw new Error(`Can't find icon "${iconName}" in "${adapterKey}" fallback file.`);
+    }
+};
+exports.getFaProIcon = getFaProIcon;