@ai-matrx/icons 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.0 — 2026-08-28
+
+- Created the package, ported verbatim from the Matrx frontend icon system
+  (`IconResolver` + the lucide name-normalize / module-icon-validation / svg-registry
+  utilities): the curated ~140-icon static Lucide map, the validated dynamic
+  `import("lucide-react")` with a module-level cache, the `svg:` asset short-circuit to
+  an `<img>`, and the fallback-icon-while-loading behavior.
+- Coupling inversions (the only behavior deltas vs. the original):
+  - `cn` is a tiny local class join — no tailwind-merge/clsx dependency.
+  - The SVG public-asset registry is injectable: ships empty; hosts call
+    `registerSvgIcons(map)` at startup (the previous hardcoded app registry moved to the
+    README as the host-registration example).
+  - `react-icons` became an OPTIONAL peer: the curated brand icons are lazy-imported on
+    first use and every path degrades to the fallback icon when the peer is absent —
+    which also means a brand icon's very first sync `getIconComponent` lookup falls back
+    until the lazy load completes.
+- New host hooks: `extendStaticIcons(map)` to add zero-latency static hits, and the
+  static map itself is exported.
+- Peers `react >= 18`, `lucide-react >= 0.400.0`, optional `react-icons >= 5`; zero
+  runtime dependencies. ESM + CommonJS with `"use client"` stamped on built chunks; the
+  release gate installs the packed tarball into an empty project (required peers only —
+  proving the no-react-icons degradation) and loads it through both `import` and
+  `require`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+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

@@ -0,0 +1,119 @@
+# @ai-matrx/icons
+
+Turn any icon **name** into a rendered component. One resolver, four sources, zero
+flash-of-nothing:
+
+- **A curated static map of ~140 hot Lucide icons** — a hit renders synchronously, no
+  dynamic-import latency. The map is exported (`staticLucideIconMap`) and extensible
+  (`extendStaticIcons`).
+- **The full Lucide catalog via a validated dynamic `import("lucide-react")`** — resolved
+  once, cached at module level, with the export checked to actually be a renderable
+  component before it is ever rendered.
+- **Curated brand icons from the optional `react-icons` peer** — lazy-imported on first
+  use; when `react-icons` is not installed the resolver degrades to the fallback icon
+  instead of failing.
+- **Your own SVG assets via `svg:` ids** — an injectable registry maps
+  `svg:icons/Home` → `/icons/Home.svg` and renders an `<img>`; you register your app's
+  asset paths once at startup.
+
+While a dynamic icon loads, the fallback icon (default `Zap`) renders in its place — the
+layout never jumps and nothing flashes empty.
+
+```bash
+npm install @ai-matrx/icons lucide-react
+# optional, for the curated brand icons (FcGoogle, FaBrave, …):
+npm install react-icons
+```
+
+Peers: `react >= 18`, `lucide-react >= 0.400.0`, and optionally `react-icons >= 5`.
+
+## Usage
+
+```tsx
+import { IconResolver, DynamicIcon, getIconComponent, renderIcon } from "@ai-matrx/icons";
+
+// The unified component — static, dynamic, custom, and svg: names all work:
+<IconResolver iconName="AlarmClock" className="h-4 w-4" />
+
+// Color/size convenience wrapper (Tailwind color names or hex):
+<DynamicIcon name="Home" color="blue" size={5} />
+<DynamicIcon name="Home" color="#ff6600" size={5} />
+
+// Synchronous lookup (static map + already-cached icons only; always returns a component):
+const Icon = getIconComponent("Settings");
+
+// Direct element render:
+{renderIcon("Check", { className: "h-4 w-4" })}
+```
+
+Existence checks (never infer existence from `getIconComponent`, which always returns a
+component): `isIconRegisteredSync(name)` for the synchronous registries,
+`await isRegisteredOrLucideIconName(name)` for the full check including the Lucide catalog.
+
+Name normalization for user-typed/pasted input: `collectLucideIconNameCandidates("alarm-clock")`
+→ `["alarm-clock", "Alarm-clock", "AlarmClock"]`, and `extractLucideJsxIconName("<BugPlay />")`
+→ `"BugPlay"` — validate candidates with `isRegisteredOrLucideIconName`.
+
+Icon pickers: `getCuratedIconIdsForPicker()` returns the finite, sorted set of every
+static Lucide name, curated brand id, and registered `svg:` id.
+
+## Registering your app's SVG assets
+
+The package ships with an **empty** `svg:` registry — register your public asset paths
+once at startup (any module that runs before icons render):
+
+```ts
+import { registerSvgIcons } from "@ai-matrx/icons";
+
+registerSvgIcons({
+  "icons/Home": "/icons/Home.svg",
+  "icons/brands/microsoft": "/icons/brands/microsoft.svg",
+  "icons/copy": "/icons/copy.svg",
+  "icons/hamburger": "/icons/hamburger.svg",
+  "icons/loading-circle": "/icons/loading-circle.svg",
+  "icons/logo": "/icons/logo.svg",
+  "icons/play": "/icons/play.svg",
+  "icons/share": "/icons/share.svg",
+  "icons/three-dots": "/icons/three-dots.svg",
+  "matrx/matrx-icon": "/matrx/matrx-icon.svg",
+  "matrx/matrx-icon-blue": "/matrx/matrx-icon-blue.svg",
+  "matrx/matrx-icon-cyan": "/matrx/matrx-icon-cyan.svg",
+  "matrx/matrx-icon-green": "/matrx/matrx-icon-green.svg",
+  "matrx/matrx-icon-indigo": "/matrx/matrx-icon-indigo.svg",
+  "matrx/matrx-icon-orange": "/matrx/matrx-icon-orange.svg",
+  "matrx/matrx-icon-pink": "/matrx/matrx-icon-pink.svg",
+  "matrx/matrx-icon-purple": "/matrx/matrx-icon-purple.svg",
+  "matrx/matrx-icon-slate": "/matrx/matrx-icon-slate.svg",
+  "matrx/matrx-icon-teal": "/matrx/matrx-icon-teal.svg",
+  "matrx/matrx-icon-yellow": "/matrx/matrx-icon-yellow.svg",
+  "matrx/matrx-imagen-logo-text": "/matrx/matrx-imagen-logo-text.svg",
+  "matrx/safari-pinned-tab": "/matrx/safari-pinned-tab.svg",
+  "dark-turbulence-noise": "/dark-turbulence-noise.svg",
+});
+```
+
+Then `<IconResolver iconName="svg:matrx/matrx-icon" size={24} />` renders
+`<img src="/matrx/matrx-icon.svg" …>`. Calls merge, so features can register their own
+ids independently. An unregistered `svg:` id falls back like any unknown name.
+
+## Keeping your own hot icons synchronous
+
+```ts
+import { BrainCircuit } from "lucide-react";
+import { extendStaticIcons } from "@ai-matrx/icons";
+
+extendStaticIcons({ BrainCircuit }); // now a zero-latency static hit everywhere
+```
+
+## Design
+
+- The static map + validated dynamic import + module cache + fallback-while-loading
+  architecture **is** the product; the curated hot set ships in the package.
+- `react-icons` is optional by construction: it is only ever loaded lazily, and every
+  path degrades to the fallback icon when it is absent.
+- Class names in helpers (`getTextColorClass`, `DynamicIcon` sizing) are Tailwind-shaped
+  strings; the package ships no CSS.
+- ESM + CommonJS conditions with matching declarations, proven from the packed tarball,
+  `"use client"` stamped on every built chunk.
+
+MIT © AI Matrx