iconora 1.0.0

package/README.md

@@ -0,0 +1,1475 @@
+# Iconora
+
+A lightweight, customizable React icon package built with TypeScript and SVG, with built-in CLI tooling for importing, deriving, generating, validating, inspecting, and managing icons.
+
+Iconora provides clean, reusable icons designed for modern React applications with a simple and consistent API. It also provides a source-to-package workflow that can derive icons from external icon repositories such as Lucide and convert them into the Iconora architecture.
+
+## Features
+
+- ⚛️ Built for React
+
+- 🔷 Written in TypeScript
+
+- 🎨 Customizable icon color
+
+- 📏 Customizable icon size
+
+- ✏️ Customizable stroke width
+
+- 🧩 Supports standard SVG props
+
+- 🌳 Tree-shakeable
+
+- 📦 Available as an npm package
+
+- 🪶 Lightweight and dependency-friendly
+
+- 🔄 Automated SVG → TSX icon generation
+
+- 🧪 Automated icon validation and testing
+
+- 🗂️ Automatic icon metadata generation
+
+- 🛠️ Built-in CLI tools for icon management and source import
+
+📥 Lucide repository icon import and derivation
+
+🔄 Source SVG → Iconora architecture conversion
+
+- 🔍 Metadata inspection for individual or multiple icons
+
+- ✅ Production project verification
+
+---
+
+## Installation
+
+Install Iconora using npm:
+
+```bash
+
+npm install iconora
+
+```
+
+Or using other package managers:
+
+```bash
+
+yarn add iconora
+
+```
+
+```bash
+
+pnpm add iconora
+
+```
+
+---
+
+## Usage
+
+Import an icon from Iconora:
+
+```tsx
+
+import { Search } from "iconora";
+
+```
+
+Then use it inside your React component:
+
+```tsx
+
+<Search />
+
+```
+
+---
+
+## Customization
+
+Iconora icons can be customized using props.
+
+### Size
+
+```tsx
+
+<Search size={24} />
+
+```
+
+```tsx
+
+<Search size={48} />
+
+```
+
+### Color
+
+```tsx
+
+<Search color="red" />
+
+```
+
+```tsx
+
+<Search color="#0f95" />
+
+```
+
+You can also use CSS-based coloring:
+
+```tsx
+
+<Search className="text-red-500" />
+
+```
+
+### Stroke Width
+
+```tsx
+
+<Search strokeWidth={3} />
+
+```
+
+### Combining Props
+
+```tsx
+
+<Search
+
+  size={48}
+
+  color="#0f95"
+
+  strokeWidth={3}
+
+/>
+
+```
+
+---
+
+## SVG Props
+
+Iconora icons support standard React SVG properties.
+
+For example:
+
+```tsx
+
+<Search
+
+  size={32}
+
+  className="my-icon"
+
+  aria-label="Search"
+
+/>
+
+```
+
+You can also use standard SVG-related props such as:
+
+```text
+
+id
+
+style
+
+role
+
+aria-label
+
+onClick
+
+```
+
+Because Iconora icons are React SVG components, standard React SVG attributes and event handlers can be used where supported by React.
+
+---
+
+## TypeScript
+
+Iconora includes TypeScript type declarations, so you get type safety and editor autocomplete when using the package.
+
+```tsx
+
+import {
+
+  Search,
+
+  type IconProps,
+
+} from "iconora";
+
+```
+
+---
+
+# Importing Icons from Lucide
+
+Iconora can import and derive the SVG icon collection from the official Lucide GitHub repository using a built-in CLI.
+
+The import command is:
+
+npm run import:lucide
+
+This command is designed for source acquisition and derivation. It extracts the Lucide SVG icon sources and places them into Iconora's icons/ source directory.
+
+It does not directly create the final React components. The imported SVG files become Iconora source files and then pass through the normal Iconora generation pipeline.
+
+## Lucide Import Workflow
+
+The complete flow is:
+
+Lucide GitHub Repository
+        │
+        ▼
+npm run import:lucide
+        │
+        ▼
+icons/*.svg
+        │
+        ▼
+npm run validate
+        │
+        ▼
+npm run generate
+        │
+        ├───────────────┬───────────────┐
+        ▼               ▼               ▼
+    TSX icons        index.ts       metadata
+        │               │               │
+        └───────────────┼───────────────┘
+                        ▼
+                  npm run check
+                        │
+                ┌───────┼───────┐
+                ▼       ▼       ▼
+            typecheck  tests    build
+                │       │       │
+                └───────┼───────┘
+                        ▼
+                   📦 Iconora
+
+## What npm run import:lucide Does
+
+The command is responsible for:
+
+Obtaining the Lucide SVG icon sources from the Lucide GitHub repository.
+
+Extracting the SVG icon files.
+
+Deriving the source collection into Iconora's icons/ directory.
+
+Preparing the icons for Iconora's validation and generation pipeline.
+
+Keeping external icon acquisition separate from React component generation.
+
+The important architectural distinction is:
+
+import:lucide
+    ↓
+External source → Iconora SVG source
+
+generate
+    ↓
+Iconora SVG source → Iconora React architecture
+
+## Example
+
+Run:
+
+npm run import:lucide
+
+The imported source collection is placed under:
+
+icons/
+├── activity.svg
+├── airplay.svg
+├── alarm-clock.svg
+├── search.svg
+├── x.svg
+└── ...
+
+After importing, validate the collection:
+
+npm run validate
+
+Then generate the Iconora components:
+
+npm run generate
+
+Finally verify the complete project:
+
+npm run check
+
+## Important
+
+npm run import:lucide is an import/derivation command, not the final Iconora generation command.
+
+The commands have separate responsibilities:
+
+Command
+
+Responsibility
+
+npm run import:lucide
+
+Derive/import Lucide SVG sources into Iconora
+
+npm run validate
+
+Validate Iconora SVG sources
+
+npm run generate
+
+Convert SVG sources into Iconora React/TypeScript architecture
+
+npm run check
+
+Verify TypeScript, tests, and production build
+
+This separation allows Iconora to remain a standalone icon package instead of being tightly coupled to Lucide's runtime package.
+
+## Recommended Lucide Import Workflow
+
+When refreshing the Lucide-derived icon collection:
+
+npm run import:lucide
+npm run validate
+npm run generate
+npm run check
+
+After the import, icons/ remains the source layer used by the rest of the Iconora pipeline.
+
+---
+
+# Adding New Icons
+
+Iconora uses SVG files as the **source of truth**.
+
+You do not manually create the corresponding `.tsx` icon component, update `index.ts`, or update the metadata file.
+
+Instead, add the SVG to:
+
+```text
+
+icons/
+
+```
+
+and let Iconora generate everything automatically.
+
+---
+
+## 1. Add the SVG
+
+Place your SVG file inside:
+
+```text
+
+icons/
+
+```
+
+For example:
+
+```text
+
+icons/
+
+├── search.svg
+
+├── x.svg
+
+└── home.svg
+
+```
+
+The filename determines the generated component name.
+
+For example:
+
+```text
+
+search.svg → Search
+
+x.svg      → X
+
+home.svg   → Home
+
+```
+
+For names containing hyphens:
+
+```text
+
+arrow-left.svg → ArrowLeft
+
+chevron-down.svg → ChevronDown
+
+```
+
+---
+
+## 2. Validate the SVG
+
+After adding the SVG, run:
+
+```bash
+
+npm run validate
+
+```
+
+This checks the source SVG collection before generating the React components.
+
+Example:
+
+```text
+
+Iconora SVG validation
+
+✓ Iconora SVG validation passed
+
+3 SVG icons checked
+
+0 failed
+
+```
+
+If validation fails, fix the SVG before continuing.
+
+---
+
+## 3. Generate the Icon
+
+Once validation passes, run:
+
+```bash
+
+npm run generate
+
+```
+
+Iconora automatically generates the React/TypeScript component.
+
+For example:
+
+```text
+
+icons/home.svg
+
+```
+
+becomes:
+
+```text
+
+src/icons/Home.tsx
+
+```
+
+The generator also updates:
+
+```text
+
+src/index.ts
+
+```
+
+and:
+
+```text
+
+src/metadata/icons.json
+
+```
+
+The generated structure looks like:
+
+```text
+
+src/
+
+├── icons/
+
+│   ├── Search.tsx
+
+│   ├── X.tsx
+
+│   └── Home.tsx
+
+│
+
+├── metadata/
+
+│   └── icons.json
+
+│
+
+└── index.ts
+
+```
+
+### Important
+
+Do not manually edit generated files:
+
+```text
+
+src/icons/
+
+src/index.ts
+
+src/metadata/icons.json
+
+```
+
+If you need to change an icon, modify the original SVG inside:
+
+```text
+
+icons/
+
+```
+
+and run:
+
+```bash
+
+npm run generate
+
+```
+
+again.
+
+---
+
+## 4. Verify the Project
+
+After generating the icon, run:
+
+```bash
+
+npm run check
+
+```
+
+This is the recommended verification command.
+
+It automatically runs:
+
+```text
+
+npm run validate
+
+      ↓
+
+npm run typecheck
+
+      ↓
+
+npm run test:run
+
+      ↓
+
+npm run build
+
+```
+
+A successful check means the generated icon passes:
+
+- SVG validation
+
+- TypeScript type checking
+
+- Icon tests
+
+- Production build
+
+---
+
+## Complete New Icon Workflow
+
+Whenever you add a new icon, the recommended workflow is:
+
+```bash
+
+npm run validate
+
+npm run generate
+
+npm run check
+
+```
+
+The complete process is:
+
+```text
+
+icons/home.svg
+
+      │
+
+      ▼
+
+npm run validate
+
+      │
+
+      ▼
+
+npm run generate
+
+      │
+
+      ├───────────────┐
+
+      ▼               ▼
+
+Home.tsx          metadata
+
+      │
+
+      └───────┬───────┘
+
+              ▼
+
+           index.ts
+
+              │
+
+              ▼
+
+        npm run check
+
+              │
+
+       ┌──────┼──────┐
+
+       ▼      ▼      ▼
+
+   Typecheck Tests  Build
+
+       │      │      │
+
+       └──────┼──────┘
+
+              ▼
+
+          📦 Iconora
+
+```
+
+---
+
+# Inspecting Icon Metadata
+
+Iconora provides a metadata inspection command.
+
+## Single Icon
+
+```bash
+
+npm run getMetadata -- Search
+
+```
+
+Icon names are case-insensitive:
+
+```bash
+
+npm run getMetadata -- Search
+
+```
+
+```bash
+
+npm run getMetadata -- search
+
+```
+
+```bash
+
+npm run getMetadata -- SEARCH
+
+```
+
+These all refer to the same icon.
+
+---
+
+## Multiple Icons
+
+You can inspect multiple icons at once:
+
+```bash
+
+npm run getMetadata -- Search X Home
+
+```
+
+You can also use:
+
+```bash
+
+npm run getMetadata -- --Search --X --Home
+
+```
+
+---
+
+## All Icons
+
+To display metadata for every icon:
+
+```bash
+
+npm run getMetadata -- --all
+
+```
+
+> **Note:** This can produce a large amount of terminal output for large icon collections.
+
+---
+
+## Missing Icons
+
+Missing icons are reported without stopping successful lookups.
+
+For example:
+
+```bash
+
+npm run getMetadata -- Search X DoesNotExist
+
+```
+
+The command will display the metadata for `Search` and `X` while reporting:
+
+```text
+
+✗ DoesNotExist
+
+  Metadata not found
+
+```
+
+---
+
+## Metadata Source
+
+Metadata is read from:
+
+```text
+
+src/metadata/icons.json
+
+```
+
+`getMetadata` is completely **read-only**.
+
+It does not modify:
+
+```text
+
+icons/
+
+src/icons/
+
+src/index.ts
+
+src/metadata/icons.json
+
+```
+
+If the metadata file is missing or outdated, run:
+
+```bash
+
+npm run generate
+
+```
+
+before using `getMetadata`.
+
+---
+
+# Removing Icons
+
+Iconora provides a CLI command for removing icons.
+
+## Full Icon Deletion
+
+To completely remove an icon:
+
+```bash
+
+npm run delete -- Search
+
+```
+
+This removes:
+
+```text
+
+icons/search.svg
+
+src/icons/Search.tsx
+
+Search from src/index.ts
+
+Search from src/metadata/icons.json
+
+```
+
+Icon names are case-insensitive:
+
+```bash
+
+npm run delete -- Search
+
+npm run delete -- search
+
+npm run delete -- SEARCH
+
+```
+
+Iconora asks for confirmation before performing the deletion.
+
+---
+
+## Selective Deletion
+
+You can also delete individual parts of an icon.
+
+### Delete only the SVG
+
+```bash
+
+npm run delete -- --Search svg
+
+```
+
+### Delete only the generated TSX
+
+```bash
+
+npm run delete -- --Search tsx
+
+```
+
+### Delete only metadata
+
+```bash
+
+npm run delete -- --Search metadata
+
+```
+
+### Delete multiple parts
+
+```bash
+
+npm run delete -- --Search svg tsx
+
+```
+
+Deletion targets are case-insensitive:
+
+```bash
+
+npm run delete -- --SEARCH SVG TSX
+
+```
+
+### Important
+
+Selective deletion can intentionally leave generated files out of sync.
+
+For normal icon removal, use:
+
+```bash
+
+npm run delete -- Search
+
+```
+
+If you intentionally perform a partial deletion and need to regenerate the project state from the remaining SVG sources, run:
+
+```bash
+
+npm run generate
+
+```
+
+---
+
+# Iconora CLI Architecture
+
+Iconora's built-in CLIs are organized as a pipeline rather than as unrelated utilities.
+
+┌───────────────────────────────┐
+│ External Icon Source          │
+│ Lucide GitHub Repository      │
+└───────────────┬───────────────┘
+                │
+                ▼
+      npm run import:lucide
+                │
+                ▼
+┌───────────────────────────────┐
+│ Iconora Source Layer          │
+│ icons/*.svg                   │
+└───────────────┬───────────────┘
+                │
+                ▼
+         npm run validate
+                │
+                ▼
+         npm run generate
+                │
+       ┌────────┼────────┐
+       ▼        ▼        ▼
+     TSX      index    metadata
+       │        │        │
+       └────────┼────────┘
+                ▼
+          npm run check
+                │
+       ┌────────┼────────┐
+       ▼        ▼        ▼
+   typecheck  tests     build
+                │
+                ▼
+           📦 Iconora
+
+This architecture gives Iconora a clear separation of concerns:
+
+Import/derivation acquires external icon sources.
+
+Source SVGs are the Iconora collection's source layer.
+
+Validation checks source correctness.
+
+Generation converts SVGs into the Iconora React/TypeScript architecture.
+
+Metadata tooling provides icon information.
+
+Deletion tooling manages the source and generated collection.
+
+Verification ensures the package is production-ready.
+
+The package is therefore not simply a wrapper around Lucide. Lucide can be one source used to derive the Iconora collection, while Iconora maintains its own source, generation, metadata, and package architecture.
+
+---
+
+# Development
+
+Clone the repository:
+
+```bash
+
+git clone <repository-url>
+
+```
+
+Enter the project:
+
+```bash
+
+cd iconora
+
+```
+
+Install dependencies:
+
+```bash
+
+npm install
+
+```
+
+---
+
+## Development Commands
+
+### Validate SVG icons
+
+```bash
+
+npm run validate
+
+```
+
+### Generate icon components
+
+```bash
+
+npm run generate
+
+```
+
+### Delete an icon
+
+```bash
+
+npm run delete -- IconName
+
+```
+
+### Get icon metadata
+
+```bash
+
+npm run getMetadata -- IconName
+
+```
+
+### Check the complete project
+
+```bash
+
+npm run check
+
+```
+
+### Typecheck
+
+```bash
+
+npm run typecheck
+
+```
+
+### Run tests once
+
+```bash
+
+npm run test:run
+
+```
+
+### Run tests in development mode
+
+```bash
+
+npm run test
+
+```
+
+### Run tests in watch mode
+
+```bash
+
+npm run test:watch
+
+```
+
+### Build the package
+
+```bash
+
+npm run build
+
+```
+
+For a detailed explanation of every command, see:
+
+```text
+
+docs/commands.md
+
+```
+
+---
+
+# Project Structure
+
+```text
+
+iconora/
+
+│
+
+├── icons/
+
+│   ├── search.svg
+
+│   └── x.svg
+
+│
+
+├── src/
+
+│   ├── components/
+
+│   │   └── IconBase.tsx
+
+│   │
+
+│   ├── icons/
+
+│   │   ├── Search.tsx
+
+│   │   └── X.tsx
+
+│   │
+
+│   ├── metadata/
+
+│   │   ├── icons.json
+
+│   │   └── types.ts
+
+│   │
+
+│   ├── types.ts
+
+│   └── index.ts
+
+│
+
+├── scripts/
+
+│   ├── check.ts
+
+│   ├── delete-icons.ts
+
+│   ├── generate-icons.ts
+
+│   ├── get-metadata.ts
+
+│   └── validate-icons.ts
+
+│
+
+├── tests/
+
+│   ├── icons.test.tsx
+
+│   └── setup.ts
+
+│
+
+├── docs/
+
+│   └── commands.md
+
+│
+
+├── .gitignore
+
+├── LICENSE
+
+├── README.md
+
+├── package.json
+
+├── package-lock.json
+
+├── tsconfig.json
+
+└── tsup.config.ts
+
+```
+
+---
+
+# Source of Truth
+
+The most important rule in Iconora is:
+
+```text
+
+icons/
+
+```
+
+is the **source of truth**.
+
+The SVG files inside `icons/` are the original icon sources.
+
+Generated files include:
+
+```text
+
+src/icons/
+
+src/index.ts
+
+src/metadata/icons.json
+
+```
+
+These files should normally **not be edited manually**.
+
+The intended architecture is:
+
+```text
+
+              SVG SOURCE
+
+                  │
+
+                  ▼
+
+              icons/*.svg
+
+                  │
+
+                  ▼
+
+          npm run validate
+
+                  │
+
+                  ▼
+
+           npm run generate
+
+                  │
+
+          ┌───────┼────────┐
+
+          ▼       ▼        ▼
+
+        TSX     index   metadata
+
+          │       │        │
+
+          └───────┼────────┘
+
+                  ▼
+
+             npm run check
+
+                  │
+
+          ┌───────┼────────┐
+
+          ▼       ▼        ▼
+
+     typecheck   tests    build
+
+          │       │        │
+
+          └───────┼────────┘
+
+                  ▼
+
+              📦 Iconora
+
+```
+
+---
+
+# Production Verification
+
+Before publishing a version of Iconora, run:
+
+```bash
+
+npm run validate
+
+npm run generate
+
+npm run check
+
+```
+
+The `check` command automatically runs:
+
+```bash
+
+npm run typecheck
+
+npm run test:run
+
+npm run build
+
+```
+
+Therefore, the complete production workflow is:
+
+```text
+
+npm run validate
+
+        ↓
+
+npm run generate
+
+        ↓
+
+npm run check
+
+        ↓
+
+┌───────────────────┐
+
+│ TypeScript        │
+
+│ Tests             │
+
+│ Production Build  │
+
+└───────────────────┘
+
+        ↓
+
+   ✓ Ready to publish
+
+```
+
+All commands should complete successfully.
+
+If any command fails, **do not publish the package** until the issue has been resolved.
+
+---
+
+# Roadmap
+
+- [x] Initial npm package setup
+
+- [x] TypeScript support
+
+- [x] React support
+
+- [x] SVG icon architecture
+
+- [x] Initial icons
+
+- [x] Local package testing
+
+- [x] Automated SVG validation
+
+- [x] Automated SVG → TSX generation
+
+- [x] Automatic icon exports
+
+- [x] Automatic icon metadata generation
+
+- [x] Aggregated icon tests
+
+- [x] Type checking
+
+- [x] ESM build
+
+- [x] CommonJS build
+
+- [x] Type declaration generation
+
+- [x] Icon deletion CLI
+
+- [x] Metadata inspection CLI
+
+- [x] Project verification CLI
+
+- [x] Command documentation
+
+- [ ] Expand icon collection
+
+- [ ] Add continuous integration
+
+- [ ] Improve package tooling
+
+- [ ] Publish stable release to npm
+
+- [ ] Expand documentation
+
+- [ ] Build Iconora documentation website
+
+---
+
+# License
+
+Iconora is released under the MIT License.
+
+You are free to use, modify, and redistribute Iconora in personal, commercial, educational, and other projects, subject to the terms of the MIT License.
+
+The license grants permission to use and modify the software; it does not transfer ownership or intellectual property rights in the original Iconora project or its original assets.
+
+See the [LICENSE](LICENSE) file for the complete license text.
+
+---
+
+# Contributing
+
+Contributions, suggestions, bug reports, and new icon ideas are welcome.
+
+If you want to contribute a new icon:
+
+1. Add the SVG to `icons/`.
+
+2. Run `npm run validate`.
+
+3. Run `npm run generate`.
+
+4. Run `npm run check`.
+
+5. Submit your changes.
+
+The `check` command automatically runs:
+
+```text
+
+TypeScript typecheck
+
+Tests
+
+Production build
+
+```
+
+Please do not manually edit generated icon files unless you are specifically working on the generation system itself.
+
+---
+
+# Documentation
+
+Detailed command documentation is available at:
+
+```text
+
+docs/commands.md
+
+```
+
+The command documentation covers:
+
+- SVG validation
+
+- Icon generation
+
+- Icon deletion
+
+- Metadata generation
+
+- Metadata inspection
+
+- Project verification
+
+- Type checking
+
+- Testing
+
+- Test watch mode
+
+- Production builds
+
+- Recommended development workflows
+
+---
+
+Made with ❤️ for React developers.
+
+**Iconora — Simple icons. Your way.**