@xplortech/apollo-icons 0.2.2 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Apollo Icons
 
-Apollo's Icon package.
+Apollo's Icon package with full TypeScript support.
 
 ## Installation
 
@@ -8,6 +8,228 @@ Apollo's Icon package.
 npm install @xplortech/apollo-icons@latest
 ```
 
-> Note: You will need to set up your NPM token in CI. [Check NPM's documentation on the topic][npm-ci-token].
+## Usage
 
-[npm-ci-token]: https://docs.npmjs.com/using-private-packages-in-a-ci-cd-workflow#set-the-token-as-an-environment-variable-on-the-cicd-server
+### Basic Usage
+
+```javascript
+import octicons from '@xplortech/apollo-icons';
+
+// Access an icon by name
+const icon = octicons['calendar-refresh'];
+
+// Generate SVG string
+const svg = icon.toSVG();
+// => '<svg version="1.1" width="16" height="16" viewBox="0 0 16 16" ...>...</svg>'
+```
+
+### TypeScript Support
+
+The package includes full TypeScript definitions with autocomplete for all icon names:
+
+```typescript
+import octicons, { Icon, IconName, SVGOptions } from '@xplortech/apollo-icons';
+
+// Icon names are typed - you get autocomplete!
+const icon = octicons['calendar-refresh']; // ✓ Type-safe
+
+// TypeScript will catch typos
+const invalid = octicons['calender-refresh']; // ✗ Error: not a valid IconName
+```
+
+### SVG Options
+
+Customize the SVG output with options:
+
+```javascript
+// Specify width (height scales proportionally)
+icon.toSVG({ width: 24 });
+
+// Specify height (width scales proportionally)
+icon.toSVG({ height: 32 });
+
+// Add custom CSS classes
+icon.toSVG({ class: 'my-icon text-primary' });
+
+// Add aria-label for accessibility (removes aria-hidden)
+icon.toSVG({ 'aria-label': 'Refresh calendar' });
+```
+
+### Getting Icons by Name
+
+Use `getIcon()` to safely retrieve an icon by name:
+
+```javascript
+import octicons from '@xplortech/apollo-icons';
+
+// Get an icon by name (returns Icon or undefined)
+const icon = octicons.getIcon('calendar-refresh');
+if (icon) {
+  console.log(icon.toSVG());
+}
+
+// Works with both direct access and getIcon()
+const directIcon = octicons['calendar-refresh'];
+const helperIcon = octicons.getIcon('calendar-refresh');
+// Both return the same icon object
+```
+
+### Finding Icons by Tag
+
+Use `getIconsByTag()` to find all icons that match a specific keyword/tag:
+
+```javascript
+import octicons from '@xplortech/apollo-icons';
+
+// Find all icons tagged with 'audio'
+const audioIcons = octicons.getIconsByTag('audio');
+// => [volume, headphones-4, microphone-3, ...]
+
+// Iterate over matching icons
+audioIcons.forEach(icon => {
+  console.log(icon.symbol); // Icon name
+  console.log(icon.toSVG({ width: 24 })); // SVG output
+});
+
+// Find icons for calendars
+const calendarIcons = octicons.getIconsByTag('calendar');
+
+// Find icons for navigation
+const navIcons = octicons.getIconsByTag('arrow');
+```
+
+### Icon Properties
+
+Each icon object has the following properties:
+
+```javascript
+const icon = octicons['calendar-refresh'];
+
+icon.symbol;    // 'calendar-refresh' - the icon name
+icon.keywords;  // ['calendar-refresh', 'reload', 'sync', ...] - searchable tags
+icon.heights;   // { '16': {...}, '24': {...}, ... } - available sizes
+icon.toSVG();   // Function to generate SVG string
+```
+
+### Available Heights
+
+Icons are available in multiple sizes. The `toSVG()` method automatically selects the best size based on the requested dimensions:
+
+```javascript
+// Request height 16 - uses 16px variant
+icon.toSVG({ height: 16 });
+
+// Request height 24 - uses 24px variant
+icon.toSVG({ height: 24 });
+
+// Request height 20 - uses closest available (16px scaled up)
+icon.toSVG({ height: 20 });
+```
+
+## Icon Name Aliasing (Deprecation Notice)
+
+Apollo Icons supports legacy icon names (called "apollo names") alongside the current naming convention (called "nucleo names"). **Apollo names are deprecated** and will be removed in the next major release.
+
+### Deprecation Warnings
+
+When you access an icon using a deprecated apollo name, you'll see a console warning:
+
+```javascript
+// Using a deprecated apollo name
+const icon = octicons['ai'];
+// Console warning: [octicons] Deprecation warning: Icon name "ai" is deprecated
+// and will be removed in the next major release. Please use "add-magic" instead.
+
+// Using the recommended nucleo name (no warning)
+const icon = octicons['add-magic'];
+```
+
+**Note:** Each deprecated name only warns once per session to avoid console spam.
+
+### Migrating from Apollo Names
+
+If you're using deprecated apollo names, update them to nucleo names:
+
+```javascript
+// ❌ Deprecated (apollo names)
+octicons['ai'];
+octicons['search'];
+octicons['home'];
+octicons['mail'];
+octicons['edit'];
+
+// ✅ Recommended (nucleo names)
+octicons['add-magic'];
+octicons['magnifier'];
+octicons['house-4'];
+octicons['envelope'];
+octicons['compose-2'];
+```
+
+### Checking Icon Availability
+
+Both naming conventions work with the `in` operator:
+
+```javascript
+'ai' in octicons; // true (but deprecated)
+'add-magic' in octicons; // true (recommended)
+```
+
+### Using getIcon() During Migration
+
+The `getIcon()` helper supports both naming conventions and provides a safe way to check icon availability:
+
+```javascript
+// Works with both naming conventions
+const icon1 = octicons.getIcon('ai'); // Warns about deprecation
+const icon2 = octicons.getIcon('add-magic'); // No warning
+
+// Returns undefined for non-existent icons
+const icon3 = octicons.getIcon('non-existent'); // undefined
+```
+
+## API Reference
+
+### `octicons[iconName]`
+
+Access an icon by its name. Returns an `Icon` object.
+
+```javascript
+const icon = octicons['calendar-refresh'];
+```
+
+**Note:** Supports both nucleo names (recommended) and apollo names (deprecated with warnings).
+
+### `octicons.getIcon(name: string): Icon | undefined`
+
+Get an icon by name with safe undefined handling. Returns the `Icon` object if found, or `undefined` if not found.
+
+```javascript
+const icon = octicons.getIcon('calendar-refresh');
+if (icon) {
+  console.log(icon.toSVG());
+}
+```
+
+**Note:** Supports both nucleo names (recommended) and apollo names (deprecated with warnings).
+
+### `octicons.getIconsByTag(tag: string): Icon[]`
+
+Returns an array of all icons that include the specified tag in their keywords.
+
+```javascript
+const audioIcons = octicons.getIconsByTag('audio');
+```
+
+### `Icon.toSVG(options?: SVGOptions): string`
+
+Generates an SVG string for the icon.
+
+**Options:**
+
+| Option       | Type     | Description                              |
+| ------------ | -------- | ---------------------------------------- |
+| `width`      | `number` | Width of the SVG in pixels               |
+| `height`     | `number` | Height of the SVG in pixels              |
+| `class`      | `string` | Additional CSS classes to add            |
+| `aria-label` | `string` | Accessible label (removes `aria-hidden`) |

package/build/build.css

@@ -1,6 +1,6 @@
 .octicon {
   display: inline-block;
   vertical-align: text-top;
-  fill: currentColor;
+  stroke: currentColor;
   overflow: visible;
 }