# islamic-icons

A **tree-shakeable** React component library of Islamic SVG icons.  
[![npm](https://img.shields.io/npm/v/islamic-icons.svg)](https://www.npmjs.com/package/islamic-icons) Built with TypeScript, Vite, and full accessibility support.

## Installation

```bash
npm install islamic-icons
# or
yarn add islamic-icons
pnpm add islamic-icons
```

**Requirements:** Node.js >= 18, React 16.8+ (web); for React Native / Expo, also install `react-native-svg` and use the `/native` entry (see below).

Security and supply-chain: this package has **no production dependencies**; only peer deps (React, react-native-svg). For Socket.dev and similar alerts, see [SECURITY.md](SECURITY.md).

| Environment        | Import from              |
|--------------------|--------------------------|
| Web (React DOM)    | `'islamic-icons'`        |
| React Native/Expo  | `'islamic-icons/native'` |

## Usage

Import only the icons you need for optimal bundle size (tree-shaking). Use the **component name** from the package, not the source SVG path:

```tsx
// ✅ Correct: import by icon name from the package
import { TasbihIcon, DomeIcon, CrescentIcon } from 'islamic-icons';

// ❌ Don’t: import from internal source paths like islamic-icons/icons/source/...
```

Example:
```tsx
import { CrescentIcon, StarIcon } from 'islamic-icons';

function App() {
  return (
    <>
      <CrescentIcon size={24} aria-label="Crescent moon" />
      <StarIcon size={32} color="#eab308" />
    </>
  );
}
```

### Props

All icons accept the same props (extends `SVGProps<SVGSVGElement>`):

| Prop          | Type             | Default     | Description                          |
|---------------|------------------|------------|--------------------------------------|
| `size`        | `number \| string` | `24`       | Width and height (e.g. `32` or `"2rem"`) |
| `color`       | `string`         | `currentColor` | Fill color (theming-friendly)     |
| `className`   | `string`         | —          | CSS class                            |
| `style`       | `object`         | —          | Inline styles                        |
| `aria-label`  | `string`         | —          | Accessible name (recommended for meaningful icons) |
| `title`       | `string`         | —          | Tooltip / title                      |

When neither `aria-label` nor `title` is set, icons get `aria-hidden="true"` so they are treated as decorative.

### Examples

```tsx
// Size and color
<CrescentIcon size={48} color="var(--primary)" />

// Custom class and style
<StarIcon className="my-icon" style={{ filter: 'drop-shadow(0 2px 4px rgba(0,0,0,0.2))' }} />

// Accessible (e.g. in buttons)
<button>
  <CrescentIcon size={20} aria-label="Islamic symbol" />
  <span>Symbol</span>
</button>
```

## Icon categories

- **Mosque & architecture** – domes, minarets, arches  
- **Religious symbols** – crescent, star, mosque lamp  
- **Prayer items** – prayer beads, prayer rug, Quran stand  
- **Hands / prayer positions** – takbir, ruku, sujud, tashahhud, salam  
- **Direction** – Qibla  
- **Phrases** – Bismillah, Alhamdulillah, etc. (as SVGs)

More icons are added over time. Run the documentation site (`npm run docs`, then open http://localhost:5174), the demo, or Storybook to see what’s available.

## React Native / Expo

Use the **`/native`** subpath so Metro bundles the React Native build (no pre-bundled React):

```tsx
import { TasbihIcon, DomeIcon, CrescentIcon } from 'islamic-icons/native';
```

**Install the peer dependency:**

```bash
npm install react-native-svg
# or
yarn add react-native-svg
```

- Icons use **react-native-svg** (`Svg`, `Path`, `Circle`, `Image`, etc.). Icons with embedded raster (e.g. Tasbih) use `Image` with the same data URI.
- Same props: `size`, `color`, `style`, `aria-label` (and standard `react-native-svg` props where applicable).

**Upgrading from an older version?** See [MIGRATION.md](MIGRATION.md) for the switch to `islamic-icons/native` on React Native.

## Icon sources (web vs RN)

- **Web:** Source SVGs are used as-is; embedded `<image>` (e.g. PNG via data URI) is kept so icons like Tasbih render correctly.
- **RN:** The same sources are converted to react-native-svg; vector elements become `Path`/`Circle`/`Rect`, and `<image>` becomes `Image` with the same `href`, so raster icons also work.

## Development

**Node:** Use Node 18 or newer (see `.nvmrc` for recommended version).

```bash
# Install dependencies
npm install

# Optimize SVG sources (icons/source/**/*.svg)
npm run optimize:svgs

# Generate React components from SVGs (web + native)
npm run generate:icons
npm run generate:icons:rn

# Type check
npm run typecheck

# Lint and type check
npm run lint
npm run typecheck

# Build library – web (dist/web) and React Native (dist/native)
npm run build
npm run build:native

# Dev demo
npm run dev

# Storybook
npm run storybook
```

### Adding new icons

1. Add SVG files under `icons/source/` (e.g. `icons/source/symbols/mosque-lamp.svg`).
2. Use `kebab-case.svg`; the script will create `MosqueLampIcon`.
3. Run `npm run optimize:svgs`, then `npm run generate:icons` and `npm run generate:icons:rn`.
4. Web exports live in `src/index.ts`; native in `src/native/index.ts`.

## Tech stack

- **Build:** Vite, SWC (React)
- **Language:** TypeScript
- **Output:** ESM + CommonJS, tree-shakeable
- **Icons:** SVG optimized with SVGO, generated via @svgr/core
- **Docs:** Storybook

## Publishing

- **npm 403 (2FA required):** See [docs/PUBLISH.md](docs/PUBLISH.md) for enabling 2FA or using an automation token.
- **Create the public GitHub repo:** See [docs/GITHUB_REPO.md](docs/GITHUB_REPO.md) for creating the repo and pushing.

## Step-by-step setup (first time)

1. **Clone and install**
   ```bash
   cd islamic-icons && npm install
   ```

2. **Add SVG sources**  
   Place `.svg` files under `icons/source/<category>/` (e.g. `icons/source/symbols/mosque-lamp.svg`). Use `kebab-case` names.

3. **Optimize SVGs (optional)**
   ```bash
   npm run optimize:svgs
   ```

4. **Generate React components**
   ```bash
   npm run generate:icons
   ```
   This creates/updates `src/icons/*.tsx` and `src/icons/index.ts`.

5. **Build the package**
   ```bash
   npm run build
   ```
   Output is in `dist/` (ESM + CJS + types).

6. **Publish to NPM**
   ```bash
   npm run prepublishOnly   # builds web + native
   npm login
   npm publish
   ```
   Ensure `package.json` has correct `name`, `version`, and `repository` before publishing.

## Security

- **Vulnerability reports:** See [SECURITY.md](SECURITY.md).
- **Consumers:** Keep `react` and `react-dom` up to date; the library does not execute remote code or use `eval`.

## License

MIT