proicons 4.8.1 → 4.10.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 ProCode
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 ProCode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,64 +1,108 @@
-# ProIcons
-<img src="./.github/images/cover.png">
-
-  [![Version](https://img.shields.io/npm/v/proicons?style=for-the-badge)](https://github.com/ProCode-Software/proicons/releases)
-[![Stars](https://img.shields.io/github/stars/ProCode-Software/proicons?style=for-the-badge&color=edd311)]()
-[![NPM Package](https://img.shields.io/npm/dm/proicons?color=98E8F3&label=downloads&style=for-the-badge)](https://www.npmjs.com/package/proicons)
-
-<p align="center"><b>A collection of 400+ modern and open-source icons and logos</b></p>
-
-## Usage
-### Node.js
-1. Install the ProIcons package via [NPM](https://https://www.npmjs.com/package/proicons):
-```console
-npm install proicons
-```
-2. Use ProIcons inside JavaScript
-```javascript
-import proicons from 'proicons'
-
-// Refer to the icon
-proicons.icons.add
-```
-_or_
-
-```html
-<!-- Insert the icon -->
-<i proicon="add"></i>
-
-<script src="path/to/proicons/dist/proicons.js"></script>
-
-<!-- Replace icons with SVG -->
-<script>proicons.replace()</script>
-```
-
-### HTML
-If you are not inside a Node environment, you can import the ProIcons script via a CDN provider
-
-```html
-<!-- Insert the icon -->
-<i proicon="add"></i>
-
-<script src="https://unpkg.com/proicons"></script>
-
-<!-- Replace icons with SVG -->
-<script>proicons.replace()</script>
-```
-
-## Roadmap
-- [x] NPM package
-- [ ] Write documentation and guidelines
-- [ ] PNG source code
-- [ ] Figma plugin
-
-
-## License
-ProIcons is MIT-licensed, giving you peace of mind using these icons in your project. Learn more [here](./LICENSE)
-
-> [!WARNING]
-> I do not own any of the logos used in the icon pack nor am I affiliated with their companies. Please use these logos under their respective company's terms and guidelines.
-
-## Credits
-- Icon design and guidelines inspired by Microsoft's [Fluent System Icons](https://github.com/microsoft/fluentui-system-icons)
-- Alpha bleeding script from https://github.com/Corecii/Transparent-Pixel-Fix
-- API based on [Feather Icons](https://github.com/feathericons/feather)
+# ProIcons
+
+<img src="https://raw.githubusercontent.com/ProCode-Software/proicons/main/.github/images/github-cover_light.png#gh-light-mode-only">
+<img src="https://raw.githubusercontent.com/ProCode-Software/proicons/main/.github/images/github-cover_dark.png#gh-dark-mode-only">
+
+<p align="center">
+    <a href="https://github.com/ProCode-Software/proicons/releases">
+        <img src="https://img.shields.io/github/v/release/ProCode-Software/proicons?style=for-the-badge&color=orange"
+            alt="Version">
+    </a>
+    <a href="">
+        <img src="https://img.shields.io/github/stars/ProCode-Software/proicons?style=for-the-badge"
+            alt="Stars">
+    </a>
+    <a href="https://www.npmjs.com/package/proicons">
+        <img src="https://img.shields.io/npm/dm/proicons?label=downloads&amp;style=for-the-badge"
+            alt="NPM Package">
+    </a>
+    <a href="https://github.com/ProCode-Software/proicons/blob/main/LICENSE">
+        <img src="https://img.shields.io/github/license/ProCode-Software/proicons?style=for-the-badge"
+            alt="License">
+    </a>
+</p>
+
+<p align="center">
+    <b>A collection of 400+ modern and open-source icons and logos</b>
+    <br>
+    <a href="https://procode-software.github.io/proicons">Icons</a> | 
+    <a href="https://procode-software.github.io/proicons/docs/introduction/about">Documentation</a> | 
+    <a href="https://github.com/ProCode-Software/proicons">GitHub</a> | 
+    <a href="https://www.npmjs.com/package/proicons">NPM Package</a>
+</p>
+
+> **Work in progress**
+> 
+> Most of the website and planned packages aren't currently finished, but you can start using the beta package right now on NPM. See [ROADMAP.md](/ROADMAP.md) to learn more.
+
+## Usage
+
+### Node.js
+
+1. Install the ProIcons package via [NPM](https://www.npmjs.com/package/proicons):
+
+```
+npm install proicons
+```
+
+2. Use ProIcons inside JavaScript
+
+```javascript
+import { icons } from 'proicons';
+// or
+const { icons } = require('proicons')
+
+// Refer to the icon
+icons.add;
+```
+
+_or_
+
+```html
+<!-- Insert the icon -->
+<i proicon="add"></i>
+
+<script src="path/to/proicons/dist/umd/proicons.cjs"></script>
+
+<!-- Replace icons with SVG -->
+<script>
+    proicons.replace();
+</script>
+```
+
+### HTML
+You can import the ProIcons package via a CDN provider
+
+```html
+<!-- Insert the icon -->
+<i proicon="add"></i>
+
+<script src="https://unpkg.com/proicons"></script>
+
+<!-- Replace icons with SVG -->
+<script>
+    proicons.replace();
+</script>
+```
+
+### Packages
+ProIcons is also available in the following packages:
+
+- **[Webfont](https://procode-software.github.io/proicons/docs/packages/webfont):** Use ProIcons on your website as a webfont, similar to Font Awesome, without the need of scripts.
+
+## License
+
+ProIcons is MIT-licensed, giving you peace of mind using these icons in your project. Learn more [here](./LICENSE)
+
+> [!WARNING]
+> This library contains brand icons that may not be MIT-licensed and may have additional terms and guidelines. Learn more [here](https://procode-software.github.io/proicons/docs/introduction/about#usage-of-brand-icons)
+
+## Contributing
+For more info on how to contribute, please see our [contributing guide](https://github.com/ProCode-Software/proicons/blob/main/CONTRIBUTING.md).
+
+## Credits
+
+-   Icon design and guidelines inspired by Microsoft's [Fluent System Icons](https://github.com/microsoft/fluentui-system-icons)
+-   Alpha bleeding script from https://github.com/Corecii/Transparent-Pixel-Fix
+-   API based on [Feather Icons](https://github.com/feathericons/feather)
+-   Website design inspired by [Lucide](https://github.com/lucide-icons/lucide) and built using [VitePress](https://github.com/vuejs/vitepress)

package/lib/categories.d.ts

@@ -1,2 +1,3 @@
+/** List of all icon categories */
 declare const categories: string[];
 export default categories;

package/lib/getIconInfo.d.ts

@@ -1,3 +1,12 @@
 import { ProIconInfo } from './interfaces';
+/**
+ * Returns information about an icon from the provided key.
+ * Throws an error if the provided key does not match an icon name in Friendly Form, camelCase or kebab-case. Use the method `search` instead to return icons that contain a keyword inside its name or tags.
+ * @param key The icon name in Friendly Form, camelCase or kebab-case. Throws an error if the provided key is invalid. Case-insensitive
+ * @example The following keys are valid:
+ * getIconInfo('Add Square')
+ * getIconInfo('addSquare')
+ * getIconInfo('add-square')
+ */
 declare function getIconInfo(key: string): ProIconInfo;
 export default getIconInfo;

package/lib/interfaces.d.ts

@@ -1,20 +1,46 @@
 export interface ProIconReplaceConfig {
+    /** Determines the color of the icons. Defaults to `currentColor`. */
     color: string;
+    /** Determines the default stroke width of the icon. Defaults to `1.5`. This only works on SVG elements with existing strokes; add `strokeFilledElements` for this property to affect such elements. */
     strokeWidth: number;
+    /** Apply strokes to filled SVG elements, such as circles, by the provided amount with `1.5` (default stroke value) subtracted, if `strokeWidth` is set to a value above `1.5`. Defaults to `false`
+     * @example If `strokeWidth` is set to `2`, filled SVG elements will have an additional `0.5`px stroke
+     */
     strokeFilledElements: boolean;
+    /** Defaults to `round` */
     strokeCaps: 'round' | 'square' | 'butt';
+    /** Defaults to `round` */
     strokeJoin: 'round' | 'miter' | 'bevel';
+    /** Determines the corner radius of SVG elements. Does not apply to all rounded elements. */
     cornerRadius: number;
+    /** The attribute name that is checked for when converting elements to icons. Defaults to `proicon`. */
     attributeName: string;
+    /** Determines whether to overwrite elements when converting to icons. Setting this to `auto` will overwrite only if the element does not have any children. Defaults to `auto`. */
     overwrite: boolean | 'auto';
+    /** Determines whether to apply existing HTMl attributes such as styles to the converted SVGs. Defaults to `true` */
     useAttributes: false;
 }
 export declare class ProIconInfo {
+    /** The name of the icon in Friendly Form */
     name: string;
+    /** The name of the icon in kebab-case */
     kebabCase: string;
+    /** The name of the icon in camelCase */
     camelCase: string;
-    element: SVGElement;
+    /** The icon as an `SVGSVGElement`. Use the `outerHTML` property on this to return the icon as a string. */
+    element: SVGSVGElement;
+    /** The category of the icon. */
     category: string;
+    /** An array of the icon's tags. */
     tags: string[];
-    constructor(name: string, kebabCase: string, camelCase: string, element: SVGElement, tags: string[], category: string);
+    /**
+     *
+     * @param name The name of the icon in Friendly Form
+     * @param kebabCase The name of the icon in kebab-case
+     * @param camelCase The name of the icon in camelCase
+     * @param element The icon as an `SVGSVGElement`. Use the `outerHTML` property on this to return the icon as a string.
+     * @param category The category of the icon.
+     * @param tags An array of the icon's tags.
+     */
+    constructor(name: string, kebabCase: string, camelCase: string, element: SVGSVGElement, tags: string[], category: string);
 }