huspy-icons 0.1.0 → 0.1.2

package/README.md

@@ -1,220 +1,265 @@
 # huspy-icons
 
-A cross-platform icon package generated from raw SVGs. Ships separate builds for **web (React / Next.js)** and **native (Expo / React Native)** with a consistent API and first-class tree-shaking.
+A cross-platform icon package generated from raw SVGs. Ships separate builds for **web (React / Next.js)** with **SVG icons** and **native (Expo / React Native)** with **font-based icons** for optimal performance.
 
 ---
 
 ## ✨ Features
 
 * **Single source of truth**: raw SVGs → codegen → typed components
-* **Two targets**: `huspy-icons/react` (web) and `huspy-icons/native` (expo)
-* **Tree-shakable** per-icon files for optimal bundle size
-* **Theming ready**: `color="currentColor"` by default; size tokens
-* **A11y** for web (`title`, `aria-hidden`) and native (`accessibilityLabel`)
-* **Scales** to hundreds of icons with auto-generated exports and types
+* **Two rendering strategies**:
+  - **Web**: Inline SVG (tree-shakable, full styling control)
+  - **Native**: Font-based icons (better performance, smaller bundle)
+* **Unified API**: Same `<Icon name="..." />` syntax for both platforms
+* **TypeScript-first**: Auto-generated types with full autocomplete
+* **Theming ready**: `color` and `size` props on all icons
+* **A11y**: Proper accessibility labels for both platforms
+* **Scales**: Hundreds of icons with auto-generated exports
 
 ---
 
-## 📦 Install
+## 📦 Installation
 
-> Publish this package to your registry (npm/GitHub Packages) and install in each app.
-
-**Next.js (web):**
+**Next.js / React (Web):**
 
 ```bash
 npm install huspy-icons
 ```
 
-**Expo (native):**
+**Expo / React Native:**
 
 ```bash
-npx expo install react-native-svg
 npm install huspy-icons
 ```
 
-> `react` build has no extra peer deps. `native` build peers `react-native-svg`.
+> **Note**: Native build uses custom fonts - no need for `react-native-svg`!  
+> See [FONT_SETUP.md](./FONT_SETUP.md) for font installation instructions.
 
 ---
 
 ## 🚀 Quick Start
 
-**Web (React / Next.js)**
+### Web (React / Next.js)
 
 ```tsx
-import { ArrowLeft } from 'huspy-icons/react';
+import { Icon } from 'huspy-icons/react';
 
 export default function Example() {
   return (
-    <div style={{ color: '#111' }}>
-      <ArrowLeft size="md" />
+    <div>
+      <Icon name="arrow-left" size={24} color="#000" />
+      <Icon name="arrow-up-right" size={32} color="#6b7280" />
     </div>
   );
 }
 ```
 
-**Expo (React Native)**
+### Expo / React Native
+
+**1. First, set up the font** (one-time setup):
+
+See [FONT_SETUP.md](./FONT_SETUP.md) for detailed instructions.
+
+**2. Use the icons:**
 
 ```tsx
-import { ArrowLeft } from 'huspy-icons/native';
+import { Icon } from 'huspy-icons/native';
 
 export default function Example() {
-  return <ArrowLeft size={20} color="#111" accessibilityLabel="Back" />;
+  return (
+    <>
+      <Icon name="arrow-left" size={24} color="#000" />
+      <Icon name="arrow-up-right" size={32} color="#6b7280" />
+    </>
+  );
 }
 ```
 
 ---
 
-## 🗂️ Repo Structure (package)
-
-```
-packages/huspy-icons/
-  icons-src/          # raw .svg files (single source of truth)
-  src/
-    react/            # generated TSX for web
-    native/           # generated TSX for expo
-    shared/           # helper types/utilities (createIcon, resolveSize)
-  scripts/            # codegen utilities (svgr, registry, typedefs)
-  svgo.config.js
-  package.json
-  tsconfig.json
-```
-
----
+## 🎨 API
 
-## ⚙️ Scripts
+Both platforms use the same API:
 
-```json
-{
-  "scripts": {
-    "svgo": "svgo -f icons-src -o icons-src --config=svgo.config.js",
-    "gen:react": "svgr icons-src -d src/react --ext tsx --typescript --icon",
-    "gen:native": "svgr --native icons-src -d src/native --ext tsx --typescript --icon",
-    "gen": "npm run svgo && npm run gen:react && npm run gen:native",
-    "build": "tsup src/**/index.ts --format esm,cjs --dts --out-dir dist --clean",
-    "prepare": "npm run gen && npm run build"
-  }
-}
+```tsx
+<Icon 
+  name="arrow-left"    // Icon name (TypeScript autocomplete available)
+  size={24}            // Size in pixels (default: 16)
+  color="#000"         // Any valid color (default: 'currentColor' for web, '#000' for native)
+/>
 ```
 
-* **`svgo`**: normalize SVGs (remove width/height, hardcoded colors).
-* **`gen:*`**: generate typed components for each target using SVGR.
-* **`build`**: bundle per-target outputs with types.
+### Available Icons
 
----
+TypeScript will autocomplete available icon names. Current icons:
+- `arrow-left`
+- `arrow-up-right`
+- `icon-slot`
 
-## 🔁 Usage Patterns
+---
 
-### Named components (preferred)
+## 🏗️ Architecture
 
-```tsx
-import { ArrowLeft, ArrowUpRight } from 'huspy-icons/react';
-<ArrowLeft size="lg" />
-<ArrowUpRight size={20} color="#6b7280" />
-```
+### Web (SVG-based)
+- Individual SVG components generated from source files
+- Tree-shakable - only icons you use are bundled
+- Full CSS styling support
+- Color inherits from parent by default (`currentColor`)
 
-* Best **tree-shaking**, great DX, no runtime lookup.
+### Native (Font-based)
+- Custom font generated from SVG files
+- Single font file for all icons
+- Better performance than SVG rendering
+- Smaller bundle size for large icon sets
+- Uses React Native `Text` component
 
 ---
 
-## 🎨 Props & Theming
+## 🔧 Development
 
-All icons share a consistent API:
+### Adding New Icons
 
-* `size`: `number | 'xs' | 'sm' | 'md' | 'lg' | 'xl'` (defaults to `lg` ≈ 20)
-* `color`: any CSS color (web) or string color (native), defaults to `currentColor`
-* Web a11y: `title?`, `aria-hidden?` (decorative by default)
-* Native a11y: `accessibilityLabel?`
+1. Drop SVG files into `icons-src/` (24×24 viewBox recommended)
 
-> Because paths default to `currentColor`, icons inherit text color out of the box. Style a parent `color` (web) or pass `color` directly.
+2. Run codegen:
 
----
+```bash
+npm run gen
+```
 
-## ↔️ RTL & Logical Directions
+This will:
+- Optimize SVGs with SVGO
+- Generate React components (web)
+- Generate icon font + glyph map (native)
+- Generate TypeScript types
 
-Icons are designed with logical naming. For RTL support:
+3. Build the package:
 
-```tsx
-// web
-<div dir="rtl">
-  <ArrowLeft />
-</div>
-
-// native
-<View style={{ transform: [{ scaleX: I18nManager.isRTL ? -1 : 1 }] }}>
-  <ArrowLeft />
-</View>
+```bash
+npm run build
 ```
 
-You can also add a `rtlFlip` prop or generate RTL variants if your design system requires them.
+4. Publish:
 
----
+```bash
+npm version minor
+npm publish
+```
 
-## 🧩 Adding Icons
+### Project Structure
 
-1. Drop raw SVGs into `icons-src/` (use 24×24 viewBox if possible).
+```
+huspy-icons/
+├── icons-src/              # Source SVG files (single source of truth)
+├── src/
+│   ├── react/             # Generated web components (SVG)
+│   ├── native/            # Native Icon component (font-based)
+│   └── shared/            # Shared types and utilities
+├── dist/
+│   ├── fonts/             # Generated font files (TTF, WOFF, etc.)
+│   ├── react/             # Built web components
+│   └── native/            # Built native component
+├── scripts/
+│   ├── generate-font.js   # Font generation script (Fantasticon)
+│   ├── generate-types.js  # TypeScript type generation
+│   └── add-size-prop.js   # Post-processing for SVGR output
+└── package.json
+```
 
-2. Run codegen:
+### Available Scripts
 
-```bash
-npm run gen
+```json
+{
+  "svgo": "Optimize SVG files",
+  "gen:react": "Generate React/SVG components",
+  "gen:native": "Generate icon font and glyph map",
+  "gen:types": "Generate TypeScript types",
+  "gen": "Run all generation scripts",
+  "build": "Build TypeScript to JavaScript",
+  "prepare": "Full build (runs on npm install)"
+}
 ```
 
-3. Commit, version, and publish:
+---
+
+## 📦 Package Exports
 
-```bash
-npm version minor
-npm publish --access public
+```json
+{
+  "exports": {
+    "./react": {
+      "import": "./dist/react/index.mjs",
+      "require": "./dist/react/index.js",
+      "types": "./dist/react/index.d.ts"
+    },
+    "./native": {
+      "require": "./dist/native/index.js",
+      "types": "./dist/native/index.d.ts"
+    }
+  }
+}
 ```
 
-> Filenames become component names: `arrow-left.svg` → `ArrowLeft.tsx`.
+Usage:
+```tsx
+// Web
+import { Icon } from 'huspy-icons/react';
+
+// Native
+import { Icon } from 'huspy-icons/native';
+```
 
 ---
 
-## 🧪 Testing
+## 🔒 Versioning
 
-* Snapshot a subset of icons to detect accidental path changes.
-* `tsd` tests for prop typing.
-* Lint rule to ensure all icons export from the barrel.
+* **Patch**: Path tweaks, bug fixes, metadata changes
+* **Minor**: New icons, non-breaking API additions
+* **Major**: Icon removals/renames, breaking API changes
 
 ---
 
-## 🧰 Troubleshooting
+## 🐛 Troubleshooting
 
-### Next.js
+### Native: Font Not Loading
 
-* If using the **prebuilt** components (recommended), you **don't** need SVGR in the app.
-* Ensure the package exports are ESM/CJS as shipped by `tsup`. If you see "Cannot use import statement outside a module", align your Next.js transpilation or stick to ESM imports.
+See [FONT_SETUP.md](./FONT_SETUP.md) for detailed setup instructions.
 
-### Expo
+Common issues:
+- Font file not copied to correct location
+- Font not registered in app config
+- App not restarted after adding font
 
-* Ensure `react-native-svg` is installed via `npx expo install react-native-svg`.
-* If tree-shaking seems off in web builds via Expo Router, prefer the `react` entry for web.
+### Web: Icons Not Showing
 
----
-
-## 📦 Exports
+- Ensure you're importing from `huspy-icons/react`
+- Check that the icon name is correct (TypeScript will help)
+- Verify the package is installed and built
 
-```json
-{
-  "exports": {
-    "./react": "./dist/react/index.js",
-    "./native": "./dist/native/index.js"
-  }
-}
-```
+### TypeScript Errors
 
-* Web: `import { ArrowLeft, ArrowUpRight } from 'huspy-icons/react'`
-* Native: `import { ArrowLeft, ArrowUpRight } from 'huspy-icons/native'`
+If you see type errors after adding new icons:
+1. Run `npm run gen` to regenerate types
+2. Restart your TypeScript server
+3. Check that the built files in `dist/` are up to date
 
 ---
 
-## 🔒 Versioning
+## 🎯 Why This Architecture?
 
-* **Patch**: path tweaks, metadata fixes
-* **Minor**: new icons, non-breaking props
-* **Major**: removals/renames, breaking prop changes
+### Web uses SVG because:
+- ✅ Tree-shakable (only bundle icons you use)
+- ✅ Full CSS styling support
+- ✅ Can animate individual paths
+- ✅ No font loading required
+- ✅ Modern browsers handle SVG efficiently
 
-Use Changesets or Conventional Commits to automate changelog and release tags.
+### Native uses Fonts because:
+- ✅ Better performance at scale
+- ✅ Smaller bundle size for large icon sets
+- ✅ Native text rendering (faster than SVG)
+- ✅ Single font file vs. many SVG components
+- ✅ Consistent with native icon patterns
 
 ---
 
@@ -224,9 +269,19 @@ MIT © Huspy
 
 ---
 
-## 💡 Notes
+## 💡 Best Practices
+
+* Keep `icons-src/` clean and consistent (same viewBox, stroke width)
+* Use descriptive, kebab-case filenames (`arrow-left.svg`, not `arrow.svg`)
+* Default to outline style; namespace filled variants if needed
+* Test icons on both platforms before publishing
+* Document any platform-specific differences
+* Consider publishing a Storybook for visual reference
+
+---
 
-* Keep `icons-src/` clean and consistent (same stroke width family, grid).
-* Default to outlines; if you ship `filled` variants, namespace as `HomeIcon` / `HomeFilledIcon` or `HomeIcon` with a `variant="filled"` prop (generated).
-* Consider publishing a Storybook or gallery page in your web app to preview all icons.
+## 🔗 Related Docs
 
+- [FONT_SETUP.md](./FONT_SETUP.md) - React Native font setup guide
+- [USAGE.md](./USAGE.md) - Detailed usage examples
+- [PROJECT_SUMMARY.md](./PROJECT_SUMMARY.md) - Technical architecture

package/dist/fonts/HuspyIcons.css

@@ -0,0 +1,28 @@
+@font-face {
+    font-family: "HuspyIcons";
+    src: url(".//HuspyIcons.ttf?25d92884ac0b766c69d414744c2ffbc2") format("truetype"),
+url(".//HuspyIcons.woff?25d92884ac0b766c69d414744c2ffbc2") format("woff"),
+url(".//HuspyIcons.woff2?25d92884ac0b766c69d414744c2ffbc2") format("woff2"),
+url(".//HuspyIcons.eot?25d92884ac0b766c69d414744c2ffbc2#iefix") format("embedded-opentype");
+}
+
+.icon:before {
+    font-family: HuspyIcons !important;
+    font-style: normal;
+    font-weight: normal !important;
+    font-variant: normal;
+    text-transform: none;
+    line-height: 1;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+}
+
+.icon.huspy-icon-icon-slot:before {
+    content: "\f101";
+}
+.icon.huspy-icon-arrow-up-right:before {
+    content: "\f102";
+}
+.icon.huspy-icon-arrow-left:before {
+    content: "\f103";
+}

package/dist/fonts/HuspyIcons.d.ts

@@ -0,0 +1,9 @@
+export enum HuspyIcons {
+  ArrowLeft = "HuspyIcons-arrow-left",
+  ArrowUpRight = "HuspyIcons-arrow-up-right",
+  IconSlot = "HuspyIcons-icon-slot"
+}
+
+export type HuspyIconsClassname = "HuspyIcons-arrow-left" | "HuspyIcons-arrow-up-right" | "HuspyIcons-icon-slot"
+export type HuspyIconsIcon = "arrow-left" | "arrow-up-right" | "icon-slot"
+export const HuspyIconsPrefix = "HuspyIcons-"

package/dist/fonts/HuspyIcons.json

@@ -0,0 +1,5 @@
+{
+  "icon-slot": 61697,
+  "arrow-up-right": 61698,
+  "arrow-left": 61699
+}

package/dist/fonts/HuspyIcons.svg

@@ -0,0 +1,21 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd" >
+<svg xmlns="http://www.w3.org/2000/svg">
+<defs>
+  <font id="HuspyIcons" horiz-adv-x="24">
+    <font-face font-family="HuspyIcons"
+      units-per-em="24" ascent="24"
+      descent="0" />
+    <missing-glyph horiz-adv-x="0" />
+    <glyph glyph-name="arrow-left"
+      unicode="&#xE000;"
+      horiz-adv-x="24" d="M12.7071 19.70711C13.0976 19.31658 13.0976 18.68342 12.7071 18.29289L6.41421 12L12.7071 5.7071C13.0976 5.3166 13.0976 4.6834 12.7071 4.2929C12.3166 3.9024 11.6834 3.9024 11.2929 4.2929L4.29289 11.2929C3.90237 11.6834 3.90237 12.3166 4.29289 12.7071L11.2929 19.70711C11.6834 20.09763 12.3166 20.09763 12.7071 19.70711zM4 12C4 12.5523 4.44772 13 5 13H19C19.5523 13 20 12.5523 20 12C20 11.4477 19.5523 11 19 11H5C4.44772 11 4 11.4477 4 12z" />
+    <glyph glyph-name="arrow-up-right"
+      unicode="&#xE001;"
+      horiz-adv-x="24" d="M6 17C6 17.55228 6.44772 18 7 18H17C17.5523 18 18 17.55228 18 17V7C18 6.4477 17.5523 6 17 6C16.4477 6 16 6.4477 16 7V16H7C6.44772 16 6 16.44772 6 17zM17.7071 17.70711C18.0976 17.31658 18.0976 16.68342 17.7071 16.29289L7.70711 6.2929C7.31658 5.9024 6.68342 5.9024 6.29289 6.2929C5.90237 6.6834 5.90237 7.3166 6.29289 7.7071L16.2929 17.70711C16.6834 18.09763 17.3166 18.09763 17.7071 17.70711z" />
+    <glyph glyph-name="icon-slot"
+      unicode="&#xE002;"
+      horiz-adv-x="15" d="M13.3333 7.66667C13.3333 10.98038 10.647 13.66667 7.33333 13.66667C4.01962 13.66667 1.33333 10.98038 1.33333 7.66667C1.33333 4.353 4.01962 1.6667 7.33333 1.6667C10.647 1.6667 13.3333 4.353 13.3333 7.66667zM14.6667 7.66667C14.6667 3.6166 11.3834 0.3333 7.33333 0.3333C3.28325 0.3333 0 3.6166 0 7.66667C0 11.71675 3.28325 15 7.33333 15C11.3834 15 14.6667 11.71675 14.6667 7.66667z" />
+  </font>
+</defs>
+</svg>

package/dist/fonts/HuspyIcons.symbol.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="0" height="0" style="display:none;"><symbol viewBox="0 0 24 24" id="HuspyIcons-arrow-left"><path fill-rule="evenodd" clip-rule="evenodd" d="M12.7071 4.29289C13.0976 4.68342 13.0976 5.31658 12.7071 5.70711L6.41421 12L12.7071 18.2929C13.0976 18.6834 13.0976 19.3166 12.7071 19.7071C12.3166 20.0976 11.6834 20.0976 11.2929 19.7071L4.29289 12.7071C3.90237 12.3166 3.90237 11.6834 4.29289 11.2929L11.2929 4.29289C11.6834 3.90237 12.3166 3.90237 12.7071 4.29289Z" fill="currentColor"></path><path fill-rule="evenodd" clip-rule="evenodd" d="M4 12C4 11.4477 4.44772 11 5 11H19C19.5523 11 20 11.4477 20 12C20 12.5523 19.5523 13 19 13H5C4.44772 13 4 12.5523 4 12Z" fill="currentColor"></path></symbol><symbol viewBox="0 0 24 24" id="HuspyIcons-arrow-up-right"><path fill-rule="evenodd" clip-rule="evenodd" d="M6 7C6 6.44772 6.44772 6 7 6H17C17.5523 6 18 6.44772 18 7V17C18 17.5523 17.5523 18 17 18C16.4477 18 16 17.5523 16 17V8H7C6.44772 8 6 7.55228 6 7Z" fill="currentColor"></path><path fill-rule="evenodd" clip-rule="evenodd" d="M17.7071 6.29289C18.0976 6.68342 18.0976 7.31658 17.7071 7.70711L7.70711 17.7071C7.31658 18.0976 6.68342 18.0976 6.29289 17.7071C5.90237 17.3166 5.90237 16.6834 6.29289 16.2929L16.2929 6.29289C16.6834 5.90237 17.3166 5.90237 17.7071 6.29289Z" fill="currentColor"></path></symbol><symbol viewBox="0 0 15 15" id="HuspyIcons-icon-slot"><path d="M13.3333 7.33333C13.3333 4.01962 10.647 1.33333 7.33333 1.33333C4.01962 1.33333 1.33333 4.01962 1.33333 7.33333C1.33333 10.647 4.01962 13.3333 7.33333 13.3333C10.647 13.3333 13.3333 10.647 13.3333 7.33333ZM14.6667 7.33333C14.6667 11.3834 11.3834 14.6667 7.33333 14.6667C3.28325 14.6667 0 11.3834 0 7.33333C0 3.28325 3.28325 0 7.33333 0C11.3834 0 14.6667 3.28325 14.6667 7.33333Z" fill="currentColor"></path></symbol></svg>

package/dist/fonts/HuspyIcons.ts

@@ -0,0 +1,16 @@
+export type HuspyIconsId =
+  | "icon-slot"
+  | "arrow-up-right"
+  | "arrow-left";
+
+export enum HuspyIcons {
+  IconSlot = "icon-slot",
+  ArrowUpRight = "arrow-up-right",
+  ArrowLeft = "arrow-left",
+}
+
+export const HUSPY_ICONS_CODEPOINTS: { [key in HuspyIcons]: string } = {
+  [HuspyIcons.IconSlot]: "61697",
+  [HuspyIcons.ArrowUpRight]: "61698",
+  [HuspyIcons.ArrowLeft]: "61699",
+};

package/dist/native/index.d.ts

@@ -1,41 +1,47 @@
 import * as React from 'react';
+import { TextProps } from 'react-native';
 
-type IconSize = number | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 /**
- * Icon size presets
+ * Available icon names in the HuspyIcons font
  */
-declare const ICON_SIZES: {
-    readonly xs: 8;
-    readonly sm: 12;
-    readonly md: 16;
-    readonly lg: 20;
-    readonly xl: 24;
-};
+type IconName = 'icon-slot' | 'arrow-up-right' | 'arrow-left';
 /**
- * Icon size token type
+ * Mapping of icon names to unicode codepoints
+ * Used by the Icon component to render the correct glyph
  */
-type IconSizeToken = keyof typeof ICON_SIZES;
+declare const glyphMap: Record<IconName, number>;
 /**
- * Props for React Native icons
+ * Font family name for React Native
  */
-interface NativeIconProps {
-    size?: IconSize;
-    width?: number;
-    height?: number;
+declare const fontFamily = "HuspyIcons";
+
+/**
+ * Props for the Icon component (React Native)
+ */
+interface IconProps extends Omit<TextProps, 'children'> {
+    /**
+     * Name of the icon to display
+     */
+    name: IconName;
+    /**
+     * Size of the icon (default: 16)
+     */
+    size?: number;
+    /**
+     * Color of the icon (default: inherits from parent or 'black')
+     */
     color?: string;
-    style?: any;
 }
 /**
- * Resolves an icon size to a numeric value
- * @param size - Size value or token
- * @returns Numeric size in pixels
+ * Icon component for React Native
+ *
+ * Renders icons using a custom font (HuspyIcons)
+ *
+ * @example
+ * ```tsx
+ * <Icon name="arrow-left" size={24} color="#000" />
+ * ```
  */
-declare function resolveSize(size?: IconSize): number;
-
-declare const SvgArrowLeft: ({ size, ...props }: NativeIconProps) => React.JSX.Element;
-
-declare const SvgArrowUpRight: ({ size, ...props }: NativeIconProps) => React.JSX.Element;
-
-declare const SvgIconSlot: ({ size, ...props }: NativeIconProps) => React.JSX.Element;
+declare const Icon: ({ name, size, color, style, ...props }: IconProps) => React.JSX.Element | null;
 
-export { SvgArrowLeft as ArrowLeft, SvgArrowUpRight as ArrowUpRight, ICON_SIZES, type IconSize, type IconSizeToken, SvgIconSlot as IconSlot, type NativeIconProps, resolveSize };
+export { Icon, type IconName, type IconProps, fontFamily, glyphMap };