@cantileva/icons 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# @cantileva/icons
+
+Import **your** Cantileva icons as React components:
+
+```tsx
+import { TrashIcon } from "@cantileva/icons";
+
+<TrashIcon className="size-6 text-amber-500" />
+```
+
+It works by **syncing** — a one-time download (per your API key) of the icons you
+made in the Cantileva app into this package as real components. No AI, no bundler
+plugin, no config: the bare import resolves in any bundler (Turbopack, Vite, webpack).
+
+## Setup
+
+```bash
+npm i @cantileva/icons
+```
+
+Set your API key (from the app → Settings → API keys). The sync reads it from your
+environment or a `.env`:
+
+```bash
+# .env
+CANTILEVA_API_KEY=cnt_yourkey
+```
+
+The icons sync automatically right after install. To re-sync after you add or edit
+icons in the app, run:
+
+```bash
+npx cantileva
+```
+
+Then import any icon by name:
+
+```tsx
+import { TrashIcon, RocketShipIcon } from "@cantileva/icons";
+```
+
+Icons use `currentColor` and `1em` sizing, so they inherit text color and font-size.
+Animated icons (ones you've animated in the app) also export a self-playing
+component, e.g. `import { RocketShipAnimated } from "@cantileva/icons"`.
+
+## How it works (and how it's secured)
+
+`npm i` (and `npx cantileva`) run a **sync** that calls the Cantileva API with your
+`CANTILEVA_API_KEY`. The backend **verifies the key and returns only your icons** —
+no key, or an invalid one, and nothing is downloaded. The components are written
+into the package, so importing them is a normal ESM import (no plugin, no runtime
+fetch, key never ships to the browser).
+
+This is the same shape as `prisma generate`: a local codegen step, scoped to you.
+
+## Notes
+
+- **No key yet?** Install still succeeds; the sync just skips. Set the key and run
+  `npx cantileva`.
+- **CI:** set `CANTILEVA_API_KEY` as a secret; the postinstall sync picks it up. If
+  you run installs with `--ignore-scripts`, run `npx cantileva` as a build step.
+- **Self-hosted / local:** point at your instance with `CANTILEVA_API_URL`
+  (default is the hosted Cantileva).

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,2 @@
+// Not synced yet. Set CANTILEVA_API_KEY and run `npx cantileva`.
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@cantileva/icons",
+  "version": "0.1.0",
+  "description": "Your Cantileva icon library, as React components.",
+  "type": "module",
+  "bin": {
+    "cantileva": "sync.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./runtime.d.ts",
+      "default": "./runtime.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "postinstall": "node sync.js"
+  },
+  "files": [
+    "sync.js",
+    "runtime.js",
+    "runtime.d.ts",
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["icons", "svg", "react", "cantileva"],
+  "license": "MIT"
+}

package/runtime.d.ts

@@ -0,0 +1,13 @@
+import type { HTMLAttributes, ReactElement } from "react";
+
+export interface IconProps extends HTMLAttributes<HTMLSpanElement> {
+  /** Icon slug, e.g. "trash" or "rocket-ship". */
+  name: string;
+  /** API key (defaults to NEXT_PUBLIC_CANTILEVA_API_KEY). */
+  apiKey?: string;
+  /** API base URL (defaults to NEXT_PUBLIC_CANTILEVA_API_URL or the hosted instance). */
+  url?: string;
+}
+
+export declare function Icon(props: IconProps): ReactElement;
+export default Icon;

package/runtime.js

@@ -0,0 +1,53 @@
+// Optional runtime icon: <Icon name="trash" />. Fetches the SVG live from your
+// Cantileva instance instead of syncing at build time — so new icons appear with
+// no rebuild. Trade-offs vs the synced named imports: a network request per icon
+// (cached), and the API key is used in the client, so use a read-only key you're
+// OK exposing (or point `url` at your own same-origin proxy). Results are cached
+// per icon name for the session.
+
+import { createElement as h, useState, useEffect } from "react";
+
+const DEFAULT_URL = "https://app.cantileva.com/api";
+const cache = new Map(); // name -> svg string
+const inflight = new Map(); // name -> Promise<string>
+
+function env(k) {
+  try { return typeof process !== "undefined" && process.env ? process.env[k] : undefined; } catch { return undefined; }
+}
+
+function load(name, url, key) {
+  if (cache.has(name)) return Promise.resolve(cache.get(name));
+  if (inflight.has(name)) return inflight.get(name);
+  const p = fetch(`${url}/v1/icons/${encodeURIComponent(name)}`, { headers: key ? { authorization: `Bearer ${key}` } : {} })
+    .then((r) => { if (!r.ok) throw new Error(`HTTP ${r.status}`); return r.json(); })
+    .then((data) => {
+      const base = data.base || {};
+      const svg = base.solid || Object.values(base)[0] || "";
+      cache.set(name, svg);
+      inflight.delete(name);
+      return svg;
+    })
+    .catch((e) => { inflight.delete(name); throw e; });
+  inflight.set(name, p);
+  return p;
+}
+
+export function Icon({ name, apiKey, url, ...props }) {
+  const base = (url || env("NEXT_PUBLIC_CANTILEVA_API_URL") || DEFAULT_URL).replace(/\/$/, "");
+  const key = apiKey || env("NEXT_PUBLIC_CANTILEVA_API_KEY") || "";
+  const [svg, setSvg] = useState(() => cache.get(name) || "");
+  useEffect(() => {
+    let live = true;
+    load(name, base, key).then((s) => { if (live) setSvg(s); }).catch(() => {});
+    return () => { live = false; };
+  }, [name, base, key]);
+  const html = svg
+    ? svg.replace(/\swidth="[^"]*"/, "").replace(/\sheight="[^"]*"/, "").replace(/<svg/, '<svg width="100%" height="100%"')
+    : "";
+  return h("span", Object.assign({
+    style: { display: "inline-flex", width: "1em", height: "1em", color: "currentColor" },
+    dangerouslySetInnerHTML: { __html: html },
+  }, props));
+}
+
+export default Icon;

package/sync.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// Sync: download YOUR Cantileva icons (the ones you made in the web app) into
+// this package as React components, so you can `import { FooIcon } from
+// "@cantileva/icons"`. No icons are created here — this only fetches what's
+// already in your library, gated by YOUR API key (the backend verifies it).
+//
+// Runs automatically on install (postinstall) and on demand via `npx cantileva`.
+// It writes into this package's own dist/, so the bare import resolves in any
+// bundler (Turbopack, Vite, webpack) with no plugin or config.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SELF = path.dirname(fileURLToPath(import.meta.url)); // the installed package dir
+const DIST = path.join(SELF, "dist");
+const URL = (process.env.CANTILEVA_API_URL || "https://app.cantileva.com/api").replace(/\/$/, "");
+
+// Pick up CANTILEVA_API_KEY from the consumer's .env if present (no hard dep).
+try { process.loadEnvFile?.(); } catch { /* no .env */ }
+const KEY = process.env.CANTILEVA_API_KEY;
+
+const pascal = (s) => String(s).replace(/[^a-z0-9]+/gi, " ").trim().split(/\s+/).map((w) => w[0].toUpperCase() + w.slice(1).toLowerCase()).join("");
+const iconName = (slug) => pascal(slug) + "Icon";
+const animName = (slug) => pascal(slug) + "Animated";
+const viewBoxOf = (svg) => (svg.match(/viewBox="([^"]+)"/) || [, "0 0 1024 1024"])[1];
+const innerOf = (svg) => svg.replace(/^[\s\S]*?<svg[^>]*>/, "").replace(/<\/svg>\s*$/, "").trim();
+const fillHost = (svg) => svg.replace(/\swidth="[^"]*"/, ' width="100%"').replace(/\sheight="[^"]*"/, ' height="100%"');
+
+const iconModule = (svg) => `import { createElement as h } from "react";
+const __html = ${JSON.stringify(innerOf(svg))};
+export default function Icon(props) {
+  return h("svg", Object.assign({ xmlns: "http://www.w3.org/2000/svg", viewBox: ${JSON.stringify(viewBoxOf(svg))}, width: "1em", height: "1em", fill: "currentColor", dangerouslySetInnerHTML: { __html } }, props));
+}
+`;
+const animModule = (frames, fps) => `import { createElement as h, useState, useEffect } from "react";
+const FRAMES = ${JSON.stringify(frames.map(fillHost))};
+export default function Animated({ fps = ${fps}, ...props }) {
+  const [i, setI] = useState(0);
+  useEffect(() => {
+    if (FRAMES.length < 2) return;
+    const id = setInterval(() => setI((x) => (x + 1) % FRAMES.length), 1000 / fps);
+    return () => clearInterval(id);
+  }, [fps]);
+  return h("span", Object.assign({ style: { display: "inline-flex", width: "1em", height: "1em", color: "currentColor" }, dangerouslySetInnerHTML: { __html: FRAMES[i] } }, props));
+}
+`;
+const STUB_JS = `// Not synced yet. Set CANTILEVA_API_KEY and run \`npx cantileva\` to download your icons.\nexport {};\n`;
+const STUB_DTS = `// Not synced yet — run \`npx cantileva\` (with CANTILEVA_API_KEY set).\nexport {};\n`;
+
+function writeStub() {
+  fs.mkdirSync(DIST, { recursive: true });
+  fs.writeFileSync(path.join(DIST, "index.js"), STUB_JS);
+  fs.writeFileSync(path.join(DIST, "index.d.ts"), STUB_DTS);
+}
+
+async function getJSON(route) {
+  const res = await fetch(URL + route, { headers: { authorization: `Bearer ${KEY}` } });
+  if (!res.ok) throw new Error(`HTTP ${res.status} for ${route}`);
+  return res.json();
+}
+
+async function sync() {
+  const { icons } = await getJSON("/v1/icons");
+  fs.rmSync(DIST, { recursive: true, force: true });
+  fs.mkdirSync(path.join(DIST, "icons"), { recursive: true });
+  const index = [];
+  const dts = [];
+  let n = 0;
+  let anims = 0;
+  for (const ic of icons || []) {
+    const base = ic.base || {};
+    const svg = base.solid || Object.values(base)[0];
+    if (!svg) continue;
+    const Name = iconName(ic.slug);
+    fs.writeFileSync(path.join(DIST, "icons", `${Name}.js`), iconModule(svg));
+    index.push(`export { default as ${Name} } from "./icons/${Name}.js";`);
+    dts.push(`export declare const ${Name}: FC<SVGProps<SVGSVGElement>>;`);
+    n++;
+    if (ic.hasAnimation) {
+      try {
+        const a = await getJSON(`/v1/icons/${encodeURIComponent(ic.slug)}/animation`);
+        if (a.frames?.length) {
+          const A = animName(ic.slug);
+          fs.writeFileSync(path.join(DIST, "icons", `${A}.js`), animModule(a.frames, a.fps || 12));
+          index.push(`export { default as ${A} } from "./icons/${A}.js";`);
+          dts.push(`export declare const ${A}: FC<HTMLAttributes<HTMLSpanElement> & { fps?: number }>;`);
+          anims++;
+        }
+      } catch { /* skip this animation */ }
+    }
+  }
+  if (!n) throw new Error("no icons returned");
+  fs.writeFileSync(path.join(DIST, "index.js"), index.join("\n") + "\n");
+  fs.writeFileSync(path.join(DIST, "index.d.ts"), `import type { FC, SVGProps, HTMLAttributes } from "react";\n` + dts.join("\n") + "\n");
+  return { n, anims };
+}
+
+const isPostinstall = process.env.npm_lifecycle_event === "postinstall";
+
+(async () => {
+  if (!KEY) {
+    if (!fs.existsSync(path.join(DIST, "index.js"))) writeStub();
+    console.log("[@cantileva/icons] No CANTILEVA_API_KEY — skipped icon sync.\n  Set it (env or .env), then run `npx cantileva`.");
+    process.exit(0); // never break an install
+  }
+  try {
+    const { n, anims } = await sync();
+    console.log(`[@cantileva/icons] Synced ${n} icons${anims ? ` + ${anims} animations` : ""}.`);
+    process.exit(0);
+  } catch (e) {
+    if (!fs.existsSync(path.join(DIST, "index.js"))) writeStub();
+    console.warn(`[@cantileva/icons] Sync failed: ${e.message}` + (isPostinstall ? "\n  Run `npx cantileva` once your key/connection is ready." : ""));
+    process.exit(isPostinstall ? 0 : 1); // don't fail installs; do fail explicit runs
+  }
+})();