docs(svg): document new metadata API and migration from legacy API

.changeset/fuzzy-camels-sip.md

@@ -0,0 +1,5 @@
+---
+'@neodx/svg': minor
+---
+
+Introduce new `metadata` API

README.md

@@ -39,9 +39,9 @@ We have a some ideas for future development, so stay tuned and feel free to requ
 
 ### [@neodx/svg](./libs/svg)
 
-Are you converting every SVG icon to React component with SVGR or something similar? It's so ease to use!
+Are you converting every SVG icon to a React component with SVGR or something similar? It's so ease to use!
 
-But wait, did you know that SVG sprites are native approach for icons? It's even easier to use!
+But wait; did you know that SVG sprites are a native approach for icons? It's even easier to use!
 
 ```typescript jsx
 import { Icon } from '@/shared/ui';
@@ -75,7 +75,7 @@ export default defineConfig({
     svg({
       root: 'assets',
       output: 'public',
-      definitions: 'src/shared/ui/icon/sprite.h.ts'
+      metadata: 'src/shared/ui/icon/sprite.gen.ts'
     })
   ]
 });
@@ -94,7 +94,7 @@ export default {
     svg({
       root: 'assets',
       output: 'public',
-      definitions: 'src/shared/ui/icon/sprite.h.ts'
+      metadata: 'src/shared/ui/icon/sprite.gen.ts'
     })
   ]
 };
@@ -113,7 +113,7 @@ export default {
     svg({
       root: 'assets',
       output: 'public',
-      definitions: 'src/shared/ui/icon/sprite.h.ts'
+      metadata: 'src/shared/ui/icon/sprite.gen.ts'
     })
   ]
 };
@@ -132,7 +132,7 @@ export default {
     svg({
       root: 'assets',
       output: 'public',
-      definitions: 'src/shared/ui/icon/sprite.h.ts'
+      metadata: 'src/shared/ui/icon/sprite.gen.ts'
     })
   ]
 };
@@ -144,7 +144,7 @@ export default {
   <summary>CLI</summary>
 
 ```shell
-npx @neodx/svg --group --root assets --output public --definition src/shared/ui/icon/sprite.h.ts
+npx @neodx/svg --group --root assets --output public --definition src/shared/ui/icon/sprite.gen.ts
 # --root - root folder with SVGs
 # --group - group icons by folders (assets/common/add.svg -> common/add, assets/other/cut.svg -> other/cut)
 # --output (-o) - output folder for sprites
@@ -165,7 +165,7 @@ await buildSprites({
   root: 'assets',
   input: '**/*.svg',
   output: 'public',
-  definition: 'src/shared/ui/icon/sprite.h.ts'
+  metadata: 'src/shared/ui/icon/sprite.gen.ts'
 });
 ```
 
@@ -185,7 +185,7 @@ src/
   shared/
     ui/
       icon/
-+        sprite.h.ts // sprite definitions - types, metadata, etc.
++        sprite.gen.ts // sprite definitions - types, metadata, etc.
 public/
 +  sprite/
 +    common.svg
@@ -208,7 +208,7 @@ Having trouble finding a suitable logging library because they're too heavy, pla
 
 I faced the same issues, which led me to create `@neodx/log`.
 It's simple, efficient, and avoids most critical drawbacks.
-Furthermore, it's easily replaceable and extensible, making it the great fit for your development needs.
+Furthermore, it's easily replaceable and extensible, making it a great fit for your development needs.
 
 <div align="center">
   <img alt="Header" src="libs/log/docs/preview-intro.png" width="1458">

apps/docs/svg/frameworks-and-bundlers.md

@@ -18,7 +18,7 @@ export default defineConfig({
       root: 'assets',
       group: true,
       output: 'public',
-      definitions: 'src/shared/ui/icon/sprite.h.ts',
+      metadata: 'src/shared/ui/icon/sprite.gen.ts',
       resetColors: {
         replaceUnknown: 'currentColor'
       }

examples/svg-magic-with-figma-export/vite.config.ts

@@ -14,10 +14,10 @@ export default defineConfig({
       root: 'assets/icons',
       output: 'public',
       group: true,
+      metadata: 'src/shared/ui/icon/sprite.gen.ts',
       resetColors: {
         replace: ['#6C707E', '#A8ADBD', '#818594']
-      },
-      definitions: 'src/shared/ui/icon/sprite.gen.ts'
+      }
     })
   ]
 });

examples/svg-next/next.config.mjs

@@ -10,7 +10,7 @@ const nextConfig = {
         svg({
           root: 'assets',
           output: 'public',
-          definitions: 'src/shared/ui/icon/sprite.gen.ts',
+          metadata: 'src/shared/ui/icon/sprite.gen.ts',
           resetColors: {
             replaceUnknown: 'currentColor'
           }

examples/svg-vite/README.md

@@ -1,10 +1,9 @@
 # Example of using `@neodx/svg` Vite plugin
 
-> **Warning** In this example was used `experimentalRuntime` option and advanced `fileName` feature, API will be changed in the nearest future.
-
 This example shows how to use `@neodx/svg` as Vite plugin and simple step-by-step setup for React.
 
-In the addition you can see how to use multicolored icons with TailwindCSS and CSS variable (it's not very pleasant, but it works 🌝).
+In addition, you can see how to use multicolored icons with TailwindCSS and CSS variable
+(it's not very pleasant, but it works 🌝).
 
 ![result](./docs/result.png)
 
@@ -37,7 +36,14 @@ export default defineConfig(({ command }) => ({
       root: 'assets', // Root folder for SVG files, all source paths will be relative to this folder
       group: true, // Group SVG files by folder
       output: 'public', // Output folder for generated files
-      definitions: 'src/shared/ui/icon/sprite.gen.ts', // Output file for generated TypeScript definitions
+      metadata: {
+        path: 'src/shared/ui/icon/sprite.gen.ts', // Output file for generated TypeScript definitions
+        runtime: {
+          // Generate additional runtime information
+          size: true,
+          viewBox: true
+        }
+      },
       resetColors: {
         replace: ['#000', '#eee', '#6C707E'], // Resets all known colors to `currentColor`
         replaceUnknown: 'var(--icon-color)' // Replaces unknown colors with custom CSS variable