@sigx/lynx-icons-fa-free 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Andreas Ekdahl
+
+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,85 @@
+# @sigx/lynx-icons-fa-free
+
+[Font Awesome Free](https://fontawesome.com/icons?d=gallery&p=2&m=free) adapter for [`@sigx/lynx-icons`](../lynx-icons). Reads glyph data from the official `@fortawesome/*` packages — no glyph data is re-bundled here, so adapter updates and FA releases stay decoupled.
+
+Supports the three Free styles: **solid**, **regular**, **brands**.
+
+## Install
+
+```bash
+pnpm add @sigx/lynx-icons @sigx/lynx-icons-fa-free
+pnpm add @fortawesome/fontawesome-free @fortawesome/free-solid-svg-icons
+# add the others if you need them:
+pnpm add @fortawesome/free-regular-svg-icons @fortawesome/free-brands-svg-icons
+```
+
+```ts
+// signalx.config.ts
+import { defineLynxConfig } from '@sigx/lynx-cli/config';
+
+export default defineLynxConfig({
+    iconSets: [
+        { id: 'fa',  source: '@sigx/lynx-icons-fa-free', styles: ['solid'] },
+        { id: 'fab', source: '@sigx/lynx-icons-fa-free', styles: ['brands'] },
+    ],
+});
+```
+
+Each `iconSets` entry maps to one runtime `set` id. Declare one per style you want to use — they're tree-shaken independently.
+
+## Usage
+
+```tsx
+import { Icon } from '@sigx/lynx-icons';
+
+<Icon set="fa" name="user" />
+<Icon set="fa" name="chevron-right" size={20} color="#0D9488" />
+<Icon set="fab" name="github" size={24} />
+```
+
+Glyph names are kebab-case (`chevron-right`, not `chevronRight`). The adapter converts to FA's `faChevronRight` export internally.
+
+## Why FA v6, not v7?
+
+This adapter pins peer FA packages to **`^6`**. Font Awesome v7 dropped TTF distribution — the `webfonts/` directory ships only WOFF2 now, and Lynx Android doesn't support WOFF2. v1 of `@sigx/lynx-icons` doesn't yet use the TTF (SVG mode only), but we keep the peer pinned to v6 so v1.1's font-mode work can land without breaking consumers.
+
+The JS API shape (`{ prefix, iconName, icon: [w, h, _, unicode, path] }`) is stable across v6 and v7, so the glyph lookups themselves would work either way.
+
+## Optional styles
+
+`regular` and `brands` are marked as **optional peerDeps**. If you only need solid, install just `@fortawesome/free-solid-svg-icons` — calls for unknown styles silently resolve to `null` and `<Icon>` renders the missing-glyph placeholder.
+
+## Dynamic / JSON-driven icons
+
+If the icon `name` comes from data (a JSON UI tree, a CMS field) the build-time scanner can't see it. Set `include: ['*']` on the iconSet to ship every glyph the adapter knows about for the configured styles:
+
+```ts
+iconSets: [
+    { id: 'fa', source: '@sigx/lynx-icons-fa-free', styles: ['solid'], include: ['*'] },
+],
+```
+
+This bundles **all ~1 900 FA-solid glyphs** (~2 MB of JS). Use it only on sets that need it; mix with normally-tree-shaken sets for the rest. The build prints the exact glyph count:
+
+```
+[@sigx/lynx-plugin] icons: fa bundling 1956 glyphs (include: ['*'])
+```
+
+`@sigx/lynx-icons`'s upcoming font mode (v1.1) will swap SVG-per-glyph for a single subsetted TTF — dramatically smaller for full-catalog scenarios. Stay tuned.
+
+## API
+
+```ts
+import faAdapter from '@sigx/lynx-icons-fa-free';
+
+faAdapter.styles;                          // ['solid', 'regular', 'brands']
+faAdapter.getGlyph('solid', 'user');       // { codepoint: 0xf007, svg: '<svg…>' }
+faAdapter.getFontPath('solid');            // absolute path to fa-solid-900.ttf
+faAdapter.getGlyph('solid', 'nope-nope');  // null
+```
+
+The adapter is normally consumed by `@sigx/lynx-plugin`'s icons slice — these direct exports are useful for tests and custom tooling.
+
+## Reference app
+
+`examples/showcase/src/screens/Settings.tsx` renders `<Icon set="fa" name="user" />`, `house`, `gear`, and `<Icon set="fab" name="github" />` in a card; the build-time scanner picks them up and writes their codepoints into `node_modules/.cache/sigx-lynx-icons/codepoints.mjs`.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { IconAdapter } from '@sigx/lynx-icons';
+declare const adapter: IconAdapter;
+export default adapter;

package/dist/index.js

@@ -0,0 +1,82 @@
+import { createRequire as e } from "node:module";
+import { dirname as t, join as n } from "node:path";
+//#region src/index.ts
+var r = e(import.meta.url), i = {
+	solid: "@fortawesome/free-solid-svg-icons",
+	regular: "@fortawesome/free-regular-svg-icons",
+	brands: "@fortawesome/free-brands-svg-icons"
+}, a = {
+	solid: "fa-solid-900.ttf",
+	regular: "fa-regular-400.ttf",
+	brands: "fa-brands-400.ttf"
+}, o = /* @__PURE__ */ new Map();
+function s(e) {
+	if (o.has(e)) return o.get(e) ?? null;
+	let t = i[e];
+	if (!t) return o.set(e, null), null;
+	try {
+		let n = r(t);
+		return o.set(e, n), n;
+	} catch {
+		return o.set(e, null), null;
+	}
+}
+function c(e) {
+	return "fa" + e.split("-").map((e) => e.charAt(0).toUpperCase() + e.slice(1)).join("");
+}
+function l(e) {
+	let t = e.slice(2);
+	if (t.length === 0) return "";
+	let n = t.charAt(0).toLowerCase();
+	for (let e = 1; e < t.length; e++) {
+		let r = t.charAt(e);
+		r >= "A" && r <= "Z" ? n += "-" + r.toLowerCase() : n += r;
+	}
+	return n;
+}
+function u() {
+	try {
+		return n(t(r.resolve("@fortawesome/fontawesome-free/package.json")), "webfonts");
+	} catch {
+		return null;
+	}
+}
+var d = {
+	styles: [
+		"solid",
+		"regular",
+		"brands"
+	],
+	getGlyph(e, t) {
+		let n = s(e);
+		if (!n) return null;
+		let r = n[c(t)];
+		if (!r || !Array.isArray(r.icon)) return null;
+		let [i, a, , o, l] = r.icon, u = parseInt(o, 16);
+		return Number.isFinite(u) ? {
+			codepoint: u,
+			svg: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${i} ${a}" fill="__COLOR__"><path d="${l}"/></svg>`
+		} : null;
+	},
+	getFontPath(e) {
+		let t = a[e];
+		if (!t) return null;
+		let r = u();
+		return r ? n(r, t) : null;
+	},
+	listGlyphs(e) {
+		let t = s(e);
+		if (!t) return [];
+		let n = [];
+		for (let [e, r] of Object.entries(t)) {
+			if (!e.startsWith("fa") || e.length < 3) continue;
+			let t = e.charAt(2);
+			t < "A" || t > "Z" || !r || typeof r != "object" || !Array.isArray(r.icon) || n.push(l(e));
+		}
+		return n;
+	}
+};
+//#endregion
+export { d as default };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { createRequire } from 'node:module';\nimport { dirname, join } from 'node:path';\nimport type { GlyphData, IconAdapter } from '@sigx/lynx-icons';\n\nconst require = createRequire(import.meta.url);\n\nconst STYLE_TO_PACKAGE: Record<string, string> = {\n    solid: '@fortawesome/free-solid-svg-icons',\n    regular: '@fortawesome/free-regular-svg-icons',\n    brands: '@fortawesome/free-brands-svg-icons',\n};\n\nconst STYLE_TO_TTF: Record<string, string> = {\n    solid: 'fa-solid-900.ttf',\n    regular: 'fa-regular-400.ttf',\n    brands: 'fa-brands-400.ttf',\n};\n\ninterface FaIconEntry {\n    prefix: string;\n    iconName: string;\n    icon: [number, number, unknown[], string, string];\n}\n\nconst moduleCache = new Map<string, Record<string, FaIconEntry> | null>();\n\nfunction loadStyleModule(style: string): Record<string, FaIconEntry> | null {\n    if (moduleCache.has(style)) return moduleCache.get(style) ?? null;\n    const pkg = STYLE_TO_PACKAGE[style];\n    if (!pkg) {\n        moduleCache.set(style, null);\n        return null;\n    }\n    try {\n        const mod = require(pkg) as Record<string, FaIconEntry>;\n        moduleCache.set(style, mod);\n        return mod;\n    } catch {\n        moduleCache.set(style, null);\n        return null;\n    }\n}\n\n/** Convert kebab-case glyph name → FA's PascalCase export name (`faChevronRight`). */\nfunction exportNameFor(name: string): string {\n    return 'fa' + name.split('-').map((seg) => seg.charAt(0).toUpperCase() + seg.slice(1)).join('');\n}\n\n/**\n * Inverse of `exportNameFor`: `faChevronRight` → `chevron-right`.\n * Used by `listGlyphs` to walk `Object.keys(module)` and emit canonical names.\n */\nfunction kebabFromExportName(exportName: string): string {\n    // Strip the leading `fa` prefix.\n    const body = exportName.slice(2);\n    if (body.length === 0) return '';\n    // Split on each uppercase letter and join with `-`, lowercasing everything.\n    let out = body.charAt(0).toLowerCase();\n    for (let i = 1; i < body.length; i++) {\n        const ch = body.charAt(i);\n        if (ch >= 'A' && ch <= 'Z') {\n            out += '-' + ch.toLowerCase();\n        } else {\n            out += ch;\n        }\n    }\n    return out;\n}\n\nfunction webfontsDir(): string | null {\n    try {\n        const pkgJson = require.resolve('@fortawesome/fontawesome-free/package.json');\n        return join(dirname(pkgJson), 'webfonts');\n    } catch {\n        return null;\n    }\n}\n\nconst adapter: IconAdapter = {\n    styles: ['solid', 'regular', 'brands'],\n\n    getGlyph(style: string, name: string): GlyphData | null {\n        const mod = loadStyleModule(style);\n        if (!mod) return null;\n        const entry = mod[exportNameFor(name)];\n        if (!entry || !Array.isArray(entry.icon)) return null;\n        const [w, h, , unicodeHex, path] = entry.icon;\n        const codepoint = parseInt(unicodeHex, 16);\n        if (!Number.isFinite(codepoint)) return null;\n        const svg = `<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 ${w} ${h}\" fill=\"__COLOR__\"><path d=\"${path}\"/></svg>`;\n        return { codepoint, svg };\n    },\n\n    getFontPath(style: string): string | null {\n        const filename = STYLE_TO_TTF[style];\n        if (!filename) return null;\n        const dir = webfontsDir();\n        if (!dir) return null;\n        return join(dir, filename);\n    },\n\n    listGlyphs(style: string): string[] {\n        const mod = loadStyleModule(style);\n        if (!mod) return [];\n        const out: string[] = [];\n        for (const [key, entry] of Object.entries(mod)) {\n            // The FA modules also export `prefix` ('fas' / 'far' / 'fab') and a\n            // single-letter alias matching the prefix. Filter to real icon\n            // entries — objects with a numeric icon[0] and a string icon[4].\n            if (!key.startsWith('fa') || key.length < 3) continue;\n            const ch = key.charAt(2);\n            if (ch < 'A' || ch > 'Z') continue; // skip `fas`, `far`, `fab`\n            if (!entry || typeof entry !== 'object' || !Array.isArray((entry as FaIconEntry).icon)) continue;\n            out.push(kebabFromExportName(key));\n        }\n        return out;\n    },\n};\n\nexport default adapter;\n"],"mappings":";;;AAIA,IAAM,IAAU,EAAc,OAAO,KAAK,IAAI,EAExC,IAA2C;CAC7C,OAAO;CACP,SAAS;CACT,QAAQ;CACX,EAEK,IAAuC;CACzC,OAAO;CACP,SAAS;CACT,QAAQ;CACX,EAQK,oBAAc,IAAI,KAAiD;AAEzE,SAAS,EAAgB,GAAmD;CACxE,IAAI,EAAY,IAAI,EAAM,EAAE,OAAO,EAAY,IAAI,EAAM,IAAI;CAC7D,IAAM,IAAM,EAAiB;CAC7B,IAAI,CAAC,GAED,OADA,EAAY,IAAI,GAAO,KAAK,EACrB;CAEX,IAAI;EACA,IAAM,IAAM,EAAQ,EAAI;EAExB,OADA,EAAY,IAAI,GAAO,EAAI,EACpB;SACH;EAEJ,OADA,EAAY,IAAI,GAAO,KAAK,EACrB;;;AAKf,SAAS,EAAc,GAAsB;CACzC,OAAO,OAAO,EAAK,MAAM,IAAI,CAAC,KAAK,MAAQ,EAAI,OAAO,EAAE,CAAC,aAAa,GAAG,EAAI,MAAM,EAAE,CAAC,CAAC,KAAK,GAAG;;AAOnG,SAAS,EAAoB,GAA4B;CAErD,IAAM,IAAO,EAAW,MAAM,EAAE;CAChC,IAAI,EAAK,WAAW,GAAG,OAAO;CAE9B,IAAI,IAAM,EAAK,OAAO,EAAE,CAAC,aAAa;CACtC,KAAK,IAAI,IAAI,GAAG,IAAI,EAAK,QAAQ,KAAK;EAClC,IAAM,IAAK,EAAK,OAAO,EAAE;EACzB,AAAI,KAAM,OAAO,KAAM,MACnB,KAAO,MAAM,EAAG,aAAa,GAE7B,KAAO;;CAGf,OAAO;;AAGX,SAAS,IAA6B;CAClC,IAAI;EAEA,OAAO,EAAK,EADI,EAAQ,QAAQ,6CACZ,CAAQ,EAAE,WAAW;SACrC;EACJ,OAAO;;;AAIf,IAAM,IAAuB;CACzB,QAAQ;EAAC;EAAS;EAAW;EAAS;CAEtC,SAAS,GAAe,GAAgC;EACpD,IAAM,IAAM,EAAgB,EAAM;EAClC,IAAI,CAAC,GAAK,OAAO;EACjB,IAAM,IAAQ,EAAI,EAAc,EAAK;EACrC,IAAI,CAAC,KAAS,CAAC,MAAM,QAAQ,EAAM,KAAK,EAAE,OAAO;EACjD,IAAM,CAAC,GAAG,KAAK,GAAY,KAAQ,EAAM,MACnC,IAAY,SAAS,GAAY,GAAG;EAG1C,OAFK,OAAO,SAAS,EAAU,GAExB;GAAE;GAAW,KAAA,wDADgD,EAAE,GAAG,EAAE,8BAA8B,EAAK;GACrF,GAFe;;CAK5C,YAAY,GAA8B;EACtC,IAAM,IAAW,EAAa;EAC9B,IAAI,CAAC,GAAU,OAAO;EACtB,IAAM,IAAM,GAAa;EAEzB,OADK,IACE,EAAK,GAAK,EAAS,GADT;;CAIrB,WAAW,GAAyB;EAChC,IAAM,IAAM,EAAgB,EAAM;EAClC,IAAI,CAAC,GAAK,OAAO,EAAE;EACnB,IAAM,IAAgB,EAAE;EACxB,KAAK,IAAM,CAAC,GAAK,MAAU,OAAO,QAAQ,EAAI,EAAE;GAI5C,IAAI,CAAC,EAAI,WAAW,KAAK,IAAI,EAAI,SAAS,GAAG;GAC7C,IAAM,IAAK,EAAI,OAAO,EAAE;GACpB,IAAK,OAAO,IAAK,OACjB,CAAC,KAAS,OAAO,KAAU,YAAY,CAAC,MAAM,QAAS,EAAsB,KAAK,IACtF,EAAI,KAAK,EAAoB,EAAI,CAAC;;EAEtC,OAAO;;CAEd"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@sigx/lynx-icons-fa-free",
+  "version": "0.4.0",
+  "description": "Font Awesome Free adapter for @sigx/lynx-icons. Provides solid/regular/brands styles via the official @fortawesome/* packages.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@fortawesome/fontawesome-free": "^6.0.0",
+    "@fortawesome/free-brands-svg-icons": "^6.0.0",
+    "@fortawesome/free-regular-svg-icons": "^6.0.0",
+    "@fortawesome/free-solid-svg-icons": "^6.0.0",
+    "@sigx/lynx-icons": "^0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@fortawesome/free-brands-svg-icons": {
+      "optional": true
+    },
+    "@fortawesome/free-regular-svg-icons": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@fortawesome/fontawesome-free": "^6.7.2",
+    "@fortawesome/free-brands-svg-icons": "^6.7.2",
+    "@fortawesome/free-regular-svg-icons": "^6.7.2",
+    "@fortawesome/free-solid-svg-icons": "^6.7.2",
+    "@sigx/vite": "^0.4.3",
+    "@types/node": "^25.7.0",
+    "typescript": "^6.0.3",
+    "@sigx/lynx-icons": "^0.4.0"
+  },
+  "author": "Andreas Ekdahl",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/signalxjs/lynx.git",
+    "directory": "packages/lynx-icons-fa-free"
+  },
+  "homepage": "https://github.com/signalxjs/lynx/tree/main/packages/lynx-icons-fa-free",
+  "bugs": {
+    "url": "https://github.com/signalxjs/lynx/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "signalx",
+    "sigx",
+    "lynx",
+    "icon",
+    "font-awesome",
+    "fontawesome"
+  ],
+  "scripts": {
+    "build": "vite build && tsgo --emitDeclarationOnly",
+    "dev": "vite build --watch"
+  }
+}