@uxf/icons-generator 11.118.0 → 11.122.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,69 +1,85 @@
1
1
  # @uxf/icons-generator
2
2
 
3
- A well configurable tool for generating and managing custom SVG icons and sprites in web projects.
3
+ CLI that bundles a project's SVG icons into a single sprite and generates the matching TypeScript definitions that power `@uxf/ui`'s `<Icon>` component.
4
4
 
5
- ## Quick Start
5
+ ## When to use
6
6
 
7
- ### Installation
7
+ Use it in any UXF web project that renders icons through `@uxf/ui/icon`. From a declarative config (`icons.config.js`) of inline SVGs and/or Font Awesome Pro references it produces an SVG sprite, one standalone SVG per icon, and a generated `icons.ts` that:
8
8
 
9
- Use npm or yarn to install:
9
+ - exports `ICONS` (per-icon `{ w, h }` map) and `ICONS_VERSION` (md5 of the sprite), and
10
+ - augments `@uxf/ui/icon/theme`'s `IconsSet` interface, so `IconName` (`keyof IconsSet`) autocompletes every icon you declared.
10
11
 
11
- ```bash
12
- npm i -D @uxf/icons-generator
13
- ```
12
+ This is a build-time dev tool run via the `icons-gen` binary. The runtime `<Icon>` component itself lives in `@uxf/ui/icon`, not here.
14
13
 
15
- ```bash
14
+ ## Installation
15
+
16
+ ```
16
17
  yarn add -D @uxf/icons-generator
17
18
  ```
18
19
 
19
- ### Configuration
20
+ Requires Node `>= 24`. Peer dependency: `@uxf/core` (`11.114.0`). To use the Font Awesome Pro adapter, additionally install the per-style FA packages you reference (see [Providers](#providers--font-awesome-pro-adapter)).
20
21
 
21
- Create a `icons.config.js` file in your project's root:
22
+ ## Quick start
22
23
 
23
- ```ts
24
- module.exports = {
25
- icons: {
26
- test: {
27
- width: 24,
28
- height: 24,
29
- data: `<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" />`,
30
- },
31
- },
32
- };
33
- ```
24
+ 1. Create `icons.config.js` in your project root:
25
+
26
+ ```js
27
+ /** @type {import('@uxf/icons-generator/src/types').IconsConfig} */
28
+ module.exports = {
29
+ generatedDirectory: "/public/icons-generated/",
30
+ icons: {
31
+ flame: {
32
+ width: 43,
33
+ height: 48,
34
+ data: `<path fill="#fff" d="M30.84 20.51a1.51 1.51 0 0 0-1.16-.71..." />`,
35
+ },
36
+ },
37
+ };
38
+ ```
39
+
40
+ 2. Run the generator:
34
41
 
35
- See the full configuration options [here](#config).
42
+ ```bash
43
+ icons-gen
44
+ ```
36
45
 
37
- ### Generating Icons
46
+ 3. Wire the generated `ICONS` + sprite into `@uxf/ui` and render icons (see [Integration](#integration-with-uxfuiicon)).
38
47
 
39
- Run the generator:
48
+ ## CLI
40
49
 
41
50
  ```bash
42
- icons-gen
51
+ icons-gen [options]
43
52
  ```
44
53
 
45
- For a custom config file name:
54
+ | Flag | Alias | Default | Description |
55
+ | -------------- | ----- | ------------------ | -------------------------------------------------- |
56
+ | `--configFile` | `-c` | `icons.config.js` | Path to the config file, resolved from `cwd`. |
57
+ | `--help` | `-h` | — | Print help and exit. |
46
58
 
47
59
  ```bash
48
- icons-gen --configFile=yourConfigFileName.js
60
+ icons-gen --configFile=custom.icons.config.js
49
61
  ```
50
62
 
51
- ## Configuration Details
63
+ ## Configuration
52
64
 
53
- | Key | Type | Default | Required | Description |
54
- | ----------------------- | -------------------------------------------------------------------- | ---------------------------- | -------- | -------------------------------- |
55
- | typescript | `boolean` | `true` | No | - |
56
- | configDirectory | `string` | `"/src/config/"` | No | - |
57
- | generatedDirectory | `string` | `"/public/icons-generated/"` | No | - |
58
- | spriteFileName | `string` | `_icon-sprite.svg` | No | Specify custom sprite file name |
59
- | typeName | `string` | `IconsSet` | No | - |
60
- | customDefinitionContent | `string` | - | No | - |
61
- | icons | `Record<string, SimpleIcon \| SizedIcon \| IconFromAdapterFunction>` | - | Yes | More details [here](#icon-types) |
62
- | fallbackFilesDirectory | - | - | No | More details [here](#adapters) |
65
+ The config file exports an `IconsConfig` object via `module.exports`.
63
66
 
64
- ## Icon Types
67
+ | Key | Type | Default | Required | Description |
68
+ | ------------------------- | ----------------------------------------------------------------------- | ------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------- |
69
+ | `icons` | `Partial<Record<string, SimpleIcon \| SizedIcon \| IconFromProviderFunction>>` | — | Yes | Icons to generate, keyed by icon name (see [Icon types](#icon-types)). |
70
+ | `generatedDirectory` | `string` | `"/public/icons-generated/"` | No | Output dir (relative to `cwd`) for the sprite and standalone SVG files. Must start/end with `/`. |
71
+ | `configDirectory` | `string` | `"/src/config/"` | No | Output dir (relative to `cwd`) for the generated `icons.ts` and provider fallbacks. Must start/end with `/`. |
72
+ | `spriteFileName` | `string` | `"_icon-sprite.svg"` | No | Sprite file name written into `generatedDirectory`. |
73
+ | `typeName` | `string` | `"IconsSet"` | No | Name of the `keyof typeof ICONS` type exported by the generated file. |
74
+ | `typescript` | `boolean` | `true` | No | Emit `icons.ts` vs `icons.js`. See [Gotchas](#gotchas). |
75
+ | `moduleDefinition` | `ModuleDefinition \| false` | augments `@uxf/ui/icon/theme` (see below) | No | Controls the `declare module` type augmentation; `false` disables it. |
76
+ | `customDefinitionContent` | `string` | — | No | Extra content appended verbatim to the end of the generated definition file. |
65
77
 
66
- ### SimpleIcon
78
+ ### Icon types
79
+
80
+ #### SimpleIcon
81
+
82
+ A single-size icon.
67
83
 
68
84
  ```ts
69
85
  type SimpleIcon = {
@@ -73,51 +89,87 @@ type SimpleIcon = {
73
89
  };
74
90
  ```
75
91
 
76
- Example:
77
-
78
92
  ```js
79
- test: {
80
- width: 50,
81
- height: 60,
82
- data: `<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" />`,
93
+ flame: {
94
+ width: 43,
95
+ height: 48,
96
+ data: `<path fill="#fff" d="M30.84 20.51a1.51 1.51 0 0 0-1.16-.71..." />`,
83
97
  }
84
98
  ```
85
99
 
86
- ### SizedIcon
100
+ #### SizedIcon
101
+
102
+ Different SVG data per pixel size. Each size produces its own sprite symbol (`icon-sprite--<name>_<size>`) and standalone file (`<name>_<size>.svg`).
87
103
 
88
104
  ```ts
89
105
  type SizedIcon = Record<number, string>;
90
106
  ```
91
107
 
92
- Example:
93
-
94
108
  ```js
95
- test: {
96
- 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" />`,
97
- 44: `<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" />`,
109
+ logo: {
110
+ 24: `<path fill="#fff" d="..." />`,
111
+ 48: `<path fill="#fff" d="..." />`,
98
112
  }
99
113
  ```
100
114
 
101
- ## Predefined providers
115
+ #### IconFromProviderFunction
102
116
 
103
- ### Font Awesome Pro Adapter
117
+ A function that resolves an icon from a provider (e.g. `faPro.icon(...)`). See [Providers](#providers--font-awesome-pro-adapter).
104
118
 
105
- The adapter reads icons from per-style packages — install only the styles you actually use:
119
+ ```ts
120
+ type IconFromProviderFunction = (config: _IconsConfig) => { width: number; height: number; path: string };
121
+ ```
106
122
 
107
- | Namespace | Package |
108
- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
109
- | `brands.*` | `@fortawesome/free-brands-svg-icons` |
110
- | `regular.*` | `@fortawesome/pro-regular-svg-icons` |
111
- | `solid.*` | `@fortawesome/pro-solid-svg-icons` |
112
- | `light.*` | `@fortawesome/pro-light-svg-icons` |
113
- | `thin.*` | `@fortawesome/pro-thin-svg-icons` |
114
- | `duotone.*`, `duotone-regular.*`, `duotone-light.*`, `duotone-thin.*` | `@fortawesome/pro-duotone[-{variant}]-svg-icons` |
115
- | `sharp-regular.*`, `sharp-solid.*`, `sharp-light.*`, `sharp-thin.*` | `@fortawesome/sharp-{variant}-svg-icons` |
116
- | `sharp-duotone-regular.*`, `sharp-duotone-solid.*`, `sharp-duotone-light.*`, `sharp-duotone-thin.*` | `@fortawesome/sharp-duotone-{variant}-svg-icons` |
123
+ ### Module augmentation (`moduleDefinition`)
117
124
 
118
- The legacy `@fortawesome/fontawesome-pro` monolith is no longer supported — uninstall it if present.
125
+ ```ts
126
+ type ModuleDefinition = {
127
+ moduleName: string;
128
+ typeName: string;
129
+ format: "type" | "interface";
130
+ };
131
+ ```
119
132
 
120
- #### Local Development Setup
133
+ Defaults to `{ moduleName: "@uxf/ui/icon/theme", typeName: "IconsSet", format: "interface" }`. With these defaults the generated file emits:
134
+
135
+ ```ts
136
+ declare module "@uxf/ui/icon/theme" {
137
+ interface IconsSet {
138
+ "flame": true;
139
+ // ...one line per icon
140
+ }
141
+ }
142
+ ```
143
+
144
+ This augmentation is what makes `@uxf/ui/icon`'s `IconName` (`keyof IconsSet`) aware of your icons. Set `moduleDefinition: false` to skip it.
145
+
146
+ ## Providers — Font Awesome Pro adapter
147
+
148
+ The `faPro` adapter reads icon data from the per-style Font Awesome packages. Install only the styles you actually use.
149
+
150
+ | Namespace | Package |
151
+ | -------------------------- | ------------------------------------------------ |
152
+ | `brands.*` | `@fortawesome/free-brands-svg-icons` |
153
+ | `regular.*` | `@fortawesome/pro-regular-svg-icons` |
154
+ | `solid.*` | `@fortawesome/pro-solid-svg-icons` |
155
+ | `light.*` | `@fortawesome/pro-light-svg-icons` |
156
+ | `thin.*` | `@fortawesome/pro-thin-svg-icons` |
157
+ | `duotone.*` | `@fortawesome/pro-duotone-svg-icons` |
158
+ | `duotone-regular.*` | `@fortawesome/duotone-regular-svg-icons` |
159
+ | `duotone-light.*` | `@fortawesome/duotone-light-svg-icons` |
160
+ | `duotone-thin.*` | `@fortawesome/duotone-thin-svg-icons` |
161
+ | `sharp-regular.*` | `@fortawesome/sharp-regular-svg-icons` |
162
+ | `sharp-solid.*` | `@fortawesome/sharp-solid-svg-icons` |
163
+ | `sharp-light.*` | `@fortawesome/sharp-light-svg-icons` |
164
+ | `sharp-thin.*` | `@fortawesome/sharp-thin-svg-icons` |
165
+ | `sharp-duotone-regular.*` | `@fortawesome/sharp-duotone-regular-svg-icons` |
166
+ | `sharp-duotone-solid.*` | `@fortawesome/sharp-duotone-solid-svg-icons` |
167
+ | `sharp-duotone-light.*` | `@fortawesome/sharp-duotone-light-svg-icons` |
168
+ | `sharp-duotone-thin.*` | `@fortawesome/sharp-duotone-thin-svg-icons` |
169
+
170
+ An icon is referenced as `"<namespace>.<kebab-icon-name>"` (e.g. `"regular.calendar-check"`). The legacy `@fortawesome/fontawesome-pro` monolith is no longer supported — the adapter throws if it is installed, so uninstall it.
171
+
172
+ ### Local development setup
121
173
 
122
174
  ```bash
123
175
  # Set registry and token
@@ -128,81 +180,101 @@ npm config set "//npm.fontawesome.com/:_authToken" YOUR_TOKEN
128
180
  npm install --save-dev @fortawesome/pro-regular-svg-icons @fortawesome/free-brands-svg-icons
129
181
  ```
130
182
 
131
- #### Usage
183
+ ### Usage
132
184
 
133
185
  ```js
134
- const { faPro } = require('@uxf/icons-generator/providers/fa-pro');
186
+ const { faPro } = require("@uxf/icons-generator/src/providers/fa-pro");
135
187
 
136
- icons: {
137
- // for icons with default name (preferred)
138
- ...faPro.adapter(["brands.linkedin"]),
139
- // to define custom name for an icon
140
- twitter: faPro.icon("brands.twitter"),
141
- }
188
+ module.exports = {
189
+ generatedDirectory: "/public/icons-generated/",
190
+ icons: {
191
+ // keeps the default name, e.g. "faPro_brands.linkedin"
192
+ ...faPro.adapter(["brands.linkedin"]),
193
+ // or assign a custom name
194
+ twitter: faPro.icon("brands.twitter"),
195
+ },
196
+ };
142
197
  ```
143
198
 
144
- #### Without Private Key
145
-
146
- If your project already contains generated icons, installing the Font Awesome Pro packages is not necessary.
147
- The package automatically generates a 'fallback file' for the icons in use, ensuring functionality even without
148
- Font Awesome Pro. However, while this setup allows for the continued use of existing icons, adding new icons
149
- from the adapter will not be possible.
199
+ `faPro.adapter([...])` names each icon `faPro_<namespace>.<name>`, while `faPro.icon(...)` lets you assign a custom key.
150
200
 
151
- ## Recommended Usage (Step-by-Step)
201
+ ### Without the private key
152
202
 
153
- ### 1. Configuration
203
+ If your project already has generated icons, the Font Awesome Pro packages are not required to rebuild them. On each successful resolve the adapter caches the icon into `<configDirectory>/icons-fallbacks/faPro.json`; when a package is missing, it reads from that fallback file instead. Existing icons keep working, but **adding new** provider icons still requires the corresponding FA package installed.
154
204
 
155
- Create and configure your icon settings in a config file at the project's root.
205
+ ## Generated output
156
206
 
157
- ### 2. Icon Generation
207
+ Running `icons-gen` (re)writes:
158
208
 
159
- Execute `icons-gen` to produce:
209
+ - `<generatedDirectory>/<spriteFileName>` — the SVG sprite: one `<symbol id="icon-sprite--<name>">` per icon (sized icons: `icon-sprite--<name>_<size>`).
210
+ - `<generatedDirectory>/<name>.svg` — one standalone SVG per icon (sized: `<name>_<size>.svg`). SVGs for icons removed from the config are cleaned up on the next run.
211
+ - `<configDirectory>/icons.ts` — the definition file (see below).
212
+ - `<configDirectory>/icons-fallbacks/<provider>.json` — cached provider icon data (e.g. `faPro.json`).
160
213
 
161
- - SVG sprite and individual files.
162
- - Definition file with icon list and sizes.
163
- - Config file with icon version and sprite path.
214
+ The definition file exports:
164
215
 
165
- ### 3. Icon Component Setup
216
+ ```ts
217
+ // this file is generated automatically, do not change anything manually in the contents of this file
166
218
 
167
- Incorporate the generated output into your project. Example for TypeScript and React:
219
+ export const ICONS_VERSION = "<md5 of the sprite file>";
168
220
 
169
- ```tsx
170
- import { ICONS, IconsSet } from "src/config/icons";
171
- import { ICON_SPRITE } from "src/config/icons-config";
221
+ export const ICONS = {
222
+ "flame": { w: 43, h: 48 },
223
+ "logo": [24, 48],
224
+ // ...
225
+ } as const;
172
226
 
173
- type IconProps = {
174
- name: IconsSet;
175
- };
227
+ export type IconsSet = keyof typeof ICONS; // name comes from `typeName`
176
228
 
177
- export const Icon: FC<IconProps> = ({ name }) => {
178
- const sizes = ICONS[name];
179
-
180
- return (
181
- <svg
182
- height={sizes.h}
183
- width={sizes.w}
184
- preserveAspectRatio="xMidYMid meet"
185
- role="img"
186
- viewBox={`0 0 ${sizes.w} ${sizes.h}`}
187
- >
188
- <use xlinkHref={`${ICON_SPRITE}#icon-sprite--${name}`} />
189
- </svg>
190
- );
191
- };
229
+ declare module "@uxf/ui/icon/theme" { // omitted when moduleDefinition: false
230
+ interface IconsSet {
231
+ "flame": true;
232
+ // ...
233
+ }
234
+ }
192
235
  ```
193
236
 
194
- ### 4. Sprite Preloading (Optional)
237
+ ## Integration with `@uxf/ui/icon`
195
238
 
196
- ```tsx
197
- import { ICON_SPRITE, ICONS_VERSION } from "src/config/icons-config";
239
+ 1. Run `icons-gen` (wire it into a `gen`/prebuild script).
240
+ 2. Pass the generated `ICONS` and sprite path to `@uxf/ui`'s `UiContextProvider`. Because `generatedDirectory` lives under `public/`, the browser URL drops that segment (`/public/icons-generated/…` → `/icons-generated/…`):
198
241
 
199
- // code here...
242
+ ```tsx
243
+ import { UiContextProvider, UiContextType } from "@uxf/ui/context";
244
+ import { ICONS, ICONS_VERSION } from "@/config/icons";
200
245
 
201
- <Head>
202
- <link as="image" href={`${ICON_SPRITE}?v=${ICONS_VERSION}`} rel="preload" type="image/svg+xml" />
203
- </Head>;
204
- ```
246
+ const uiConfig: UiContextType = {
247
+ icon: {
248
+ iconsConfig: ICONS,
249
+ spriteFilePath: `/icons-generated/_icon-sprite.svg?v=${ICONS_VERSION}`,
250
+ },
251
+ // ...other UI context options (colorScheme, localeConfig, rasterImage, translationFn)
252
+ };
253
+ ```
254
+
255
+ 3. Render icons via `@uxf/ui`'s `<Icon>`. The `name` prop autocompletes every generated icon thanks to the module augmentation:
256
+
257
+ ```tsx
258
+ import { Icon } from "@uxf/ui/icon";
259
+
260
+ <Icon name="flame" size={24} />;
261
+ ```
262
+
263
+ 4. (Optional) Preload the sprite:
264
+
265
+ ```tsx
266
+ <link as="image" href={`/icons-generated/_icon-sprite.svg?v=${ICONS_VERSION}`} rel="preload" type="image/svg+xml" />
267
+ ```
268
+
269
+ ## Gotchas
270
+
271
+ - **Dev/build tool only.** The `<Icon>` runtime component is `@uxf/ui/icon`; this package just generates the sprite and types.
272
+ - **Paths are `cwd`-relative and need slashes.** `configDirectory` and `generatedDirectory` are joined onto `process.cwd()`, so both must start and end with `/`.
273
+ - **`typescript: false` currently has no effect.** The generator always emits `icons.ts` — the flag falls back to `true` internally.
274
+ - **The `faPro` provider is a deep import:** `@uxf/icons-generator/src/providers/fa-pro` (the published files preserve the `src/` layout). The `IconsConfig` type is at `@uxf/icons-generator/src/types`.
275
+ - **Keep the default `moduleName`** (`@uxf/ui/icon/theme`) unless you intentionally augment a different module; changing it breaks the `@uxf/ui` `IconName` inference.
205
276
 
206
- ### 5. Verification
277
+ ## Links
207
278
 
208
- Run `icons-check` to ensure icon consistency with the config. It's recommended to integrate this check into your CI process.
279
+ - Repository: [gitlab.com/uxf-npm/icons-generator](https://gitlab.com/uxf-npm/icons-generator)
280
+ - Consumed by `@uxf/ui/icon` (the `<Icon>` component and `IconsSet`/`IconName` types).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uxf/icons-generator",
3
- "version": "11.118.0",
3
+ "version": "11.122.4",
4
4
  "description": "",
5
5
  "main": "index.js",
6
6
  "scripts": {
@@ -6,8 +6,13 @@ function _createSpriteContent(config) {
6
6
  let spriteTextContent = `<svg xmlns="http://www.w3.org/2000/svg">`;
7
7
  Object.keys(config.icons).map((name) => {
8
8
  const icon = config.icons[name];
9
+ // `overflow="visible"` guards against source icons (notably some FontAwesome v7
10
+ // glyphs) whose path extends beyond their declared width/height — the symbol
11
+ // viewport would otherwise clip the bleed (UA default `overflow: hidden`), and
12
+ // consumers can't reach it via CSS because the sprite is referenced across
13
+ // documents with <use>. Paired with `.uxf-icon { overflow: visible }` in @uxf/ui.
9
14
  if (_iconTypeResolver_1._iconTypeResolver.isSimpleIcon(icon)) {
10
- spriteTextContent += `<symbol id="icon-sprite--${name}" viewBox="0 0 ${icon.width} ${icon.height}">`;
15
+ spriteTextContent += `<symbol id="icon-sprite--${name}" viewBox="0 0 ${icon.width} ${icon.height}" overflow="visible">`;
11
16
  spriteTextContent += icon.data;
12
17
  spriteTextContent += `</symbol>`;
13
18
  return;
@@ -15,13 +20,13 @@ function _createSpriteContent(config) {
15
20
  if (_iconTypeResolver_1._iconTypeResolver.isSizedIcon(icon)) {
16
21
  Object.keys(icon).map((s) => {
17
22
  const svg = icon[Number(s)];
18
- spriteTextContent += `<symbol id="icon-sprite--${name}_${s}" viewBox="0 0 ${s} ${s}">${svg}</symbol>`;
23
+ spriteTextContent += `<symbol id="icon-sprite--${name}_${s}" viewBox="0 0 ${s} ${s}" overflow="visible">${svg}</symbol>`;
19
24
  });
20
25
  return;
21
26
  }
22
27
  if (_iconTypeResolver_1._iconTypeResolver.isFromAdapter(icon)) {
23
28
  const svg = icon(config);
24
- spriteTextContent += `<symbol id="icon-sprite--${name}" viewBox="0 0 ${svg.width} ${svg.height}">${svg.path}</symbol>`;
29
+ spriteTextContent += `<symbol id="icon-sprite--${name}" viewBox="0 0 ${svg.width} ${svg.height}" overflow="visible">${svg.path}</symbol>`;
25
30
  return;
26
31
  }
27
32
  throw new Error(`Unknown icon format for icon: "${name}".`);