@dynamic-icon/core 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dynamic-icon contributors
+
+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

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @dynamic-icon/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Experimental package — do not use in production.
+
+Framework-independent icon registry behind [`@dynamic-icon/svelte`](../svelte): maps `webType` + `webRef` strings from a
+database to components. Zero dependencies, no DOM, no framework. Most apps use `configureIcons` from `@dynamic-icon/svelte`
+and never import this package directly.
+
+```ts
+import { configureIcons, resolveIcon } from '@dynamic-icon/core';
+
+configureIcons<MyComponent>({ sources: { lucide: { 'car-front': CarFront } } });
+resolveIcon<MyComponent>('lucide', 'car-front'); // CarFront | undefined
+```
+
+**Full reference** (options, logging, registry, SSR rules): [`llms.txt`](./llms.txt), shipped in the npm package, e.g.
+`https://unpkg.com/@dynamic-icon/core/llms.txt`.

package/dist/config.d.ts

@@ -0,0 +1,15 @@
+import type { IconConfig, ResolvedIconConfig } from "./types.js";
+/**
+ * Sets the icon configuration. Call once at app start (module scope of your root/hooks file, not inside a
+ * component), identically on server and client. Replaces any previous configuration; throws on invalid
+ * input and keeps the previous configuration in that case.
+ */
+export declare function configureIcons<C = unknown>(config: IconConfig<C>): void;
+/**
+ * The current configuration (defaults apply until `configureIcons` is called).
+ * `C` is a type assertion: the registry stores whatever `configureIcons` was given, so framework wrappers
+ * must be the only writers for their `C`.
+ */
+export declare function getIconConfig<C = unknown>(): ResolvedIconConfig<C>;
+/** Resolves a component for `webType`/`webRef`, or `undefined`. Usable outside components. */
+export declare function resolveIcon<C = unknown>(webType: string | undefined, webRef: string | undefined): C | undefined;

package/dist/config.js

@@ -0,0 +1,140 @@
+/** `webType`s handled by the renderer itself and therefore not usable as source names. */
+const RESERVED = new Set(["image", "emoji", "markup"]);
+const DEFAULT_FONT_TYPES = ["material", "font-awesome", "remix"];
+/** Distinct messages reported per configuration; protects against unbounded growth from bad data. */
+const MAX_LOGGED = 500;
+const defaultLog = ({ type, message, error }) => error === undefined ? console[type](message) : console[type](message, error);
+function positive(name, value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`[dynamic-icon] ${name} must be a positive finite number, got ${value}`);
+    }
+    return value;
+}
+function toResolver(type, source) {
+    if (typeof source === "function")
+        return source;
+    if (source !== null && typeof source === "object") {
+        // Held by reference, never copied: no extra memory, and module namespaces work as-is. `hasOwn` keeps
+        // identifiers such as "constructor" or "toString" from reaching Object.prototype. Treat the object as
+        // read-only: later mutations are visible to lookups.
+        return (ref) => (Object.hasOwn(source, ref) ? source[ref] : undefined);
+    }
+    throw new TypeError(`[dynamic-icon] source "${type}" must be a record or a function`);
+}
+function build(config) {
+    if (config.sanitize !== undefined && typeof config.sanitize !== "function") {
+        throw new TypeError("[dynamic-icon] sanitize must be a function");
+    }
+    if (config.onLog !== undefined && typeof config.onLog !== "function") {
+        throw new TypeError("[dynamic-icon] onLog must be a function");
+    }
+    // Each distinct message is delivered once per configuration (so 1,000 icons with one typo log once, and a
+    // server does not log per request). A throwing `onLog` never reaches rendering.
+    const onLog = config.onLog ?? defaultLog;
+    const seen = new Set();
+    const emit = (entry) => {
+        try {
+            onLog(entry);
+        }
+        catch {
+            /* logging must never break rendering */
+        }
+    };
+    const log = (type, message, error) => {
+        if (seen.has(message))
+            return;
+        if (seen.size >= MAX_LOGGED) {
+            if (seen.size === MAX_LOGGED) {
+                seen.add(""); // marks the notice as sent
+                emit({ type: "warn", message: "[dynamic-icon] too many distinct messages; further ones are suppressed" });
+            }
+            return;
+        }
+        seen.add(message);
+        emit(error === undefined ? { type, message } : { type, message, error });
+    };
+    const resolvers = new Map();
+    for (const [type, source] of Object.entries(config.sources ?? {})) {
+        if (RESERVED.has(type)) {
+            throw new Error(`[dynamic-icon] "${type}" is a built-in type and cannot be used as a source name`);
+        }
+        resolvers.set(type, toResolver(type, source));
+    }
+    const fontTypes = new Set(config.fontTypes ?? DEFAULT_FONT_TYPES);
+    for (const type of fontTypes) {
+        if (RESERVED.has(type) || resolvers.has(type)) {
+            throw new Error(`[dynamic-icon] "${type}" cannot be both a font type and a source/built-in type`);
+        }
+    }
+    const { sanitize } = config;
+    return {
+        resolve: (webType, webRef) => {
+            if (!webType || !webRef)
+                return undefined; // an empty record is not an error
+            const resolver = resolvers.get(webType);
+            if (resolver) {
+                try {
+                    const component = resolver(webRef);
+                    if (component === undefined)
+                        log("warn", `[dynamic-icon] icon "${webRef}" not found in source "${webType}"`);
+                    return component;
+                }
+                catch (error) {
+                    log("error", `[dynamic-icon] source "${webType}" threw while resolving "${webRef}"`, error);
+                    return undefined;
+                }
+            }
+            // Not a source: only the built-in renderers are legitimate here, anything else is a data/config bug.
+            if (!RESERVED.has(webType) && !fontTypes.has(webType)) {
+                log("warn", `[dynamic-icon] unknown webType "${webType}" (not a source, built-in or font type); icon "${webRef}" not rendered`);
+            }
+            else if (webType === "markup" && !sanitize) {
+                log("error", '[dynamic-icon] "markup" icon not rendered: configureIcons({ sanitize }) is not set');
+            }
+            return undefined;
+        },
+        fontTypes,
+        sanitize: sanitize
+            ? (html) => {
+                try {
+                    return sanitize(html);
+                }
+                catch (error) {
+                    log("error", "[dynamic-icon] sanitize threw; icon rendered empty", error);
+                    return "";
+                }
+            }
+            : undefined,
+        fallback: config.fallback,
+        size: positive("defaults.size", config.defaults?.size ?? 24),
+        strokeWidth: positive("defaults.strokeWidth", config.defaults?.strokeWidth ?? 2)
+    };
+}
+// One registry per realm. The holder is created once and captured by this module, so every read is a plain
+// property access. `Symbol.for` makes duplicate copies of this package (version skew, nested installs) share
+// the same holder instead of silently keeping separate registries. The `@1` is the holder's format version:
+// bump it on a breaking change so incompatible copies never share state. The config is immutable and
+// identical for every SSR request, so a process-wide singleton needs no per-request isolation.
+const KEY = Symbol.for("@dynamic-icon/core@1");
+const realm = globalThis;
+const holder = (realm[KEY] ??= { config: build({}) });
+/**
+ * Sets the icon configuration. Call once at app start (module scope of your root/hooks file, not inside a
+ * component), identically on server and client. Replaces any previous configuration; throws on invalid
+ * input and keeps the previous configuration in that case.
+ */
+export function configureIcons(config) {
+    holder.config = build(config);
+}
+/**
+ * The current configuration (defaults apply until `configureIcons` is called).
+ * `C` is a type assertion: the registry stores whatever `configureIcons` was given, so framework wrappers
+ * must be the only writers for their `C`.
+ */
+export function getIconConfig() {
+    return holder.config;
+}
+/** Resolves a component for `webType`/`webRef`, or `undefined`. Usable outside components. */
+export function resolveIcon(webType, webRef) {
+    return holder.config.resolve(webType, webRef);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { configureIcons, getIconConfig, resolveIcon } from "./config.js";
+export type { IconConfig, IconLogEntry, IconSource, ResolvedIconConfig } from "./types.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { configureIcons, getIconConfig, resolveIcon } from "./config.js";

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Where components for one `webType` come from. `C` is the framework's component type.
+ * - A record keyed by the identifier stored in the database: `{ 'car-front': CarFront }`.
+ * - A function: full control (lazy tables, key normalisation, memoisation, ...).
+ */
+export type IconSource<C = unknown> = Readonly<Record<string, C>> | ((ref: string) => C | undefined);
+export interface IconLogEntry {
+    type: "error" | "warn";
+    message: string;
+    /** The original thrown value, when there is one. */
+    error?: unknown;
+}
+export interface IconConfig<C = unknown> {
+    /** Component sources by `webType`. Reserved names: `image`, `emoji`, `markup`. */
+    sources?: Readonly<Record<string, IconSource<C>>>;
+    /** `webType`s rendered as `<i class={webRef}>` (icon fonts). Default: material, font-awesome, remix. */
+    fontTypes?: readonly string[];
+    /** Required for `markup`: raw HTML is only rendered after passing through this. */
+    sanitize?: (html: string) => string;
+    /** Rendered when nothing else resolves (and no per-instance fallback is given). */
+    fallback?: C;
+    /** Defaults for `size` (px, default 24) and `strokeWidth` (default 2). */
+    defaults?: {
+        size?: number;
+        strokeWidth?: number;
+    };
+    /**
+     * Receives diagnostics: icons missing from a source, unknown `webType`s, `markup` without `sanitize`, and
+     * errors thrown by function sources or `sanitize` (`error` carries the original). Each distinct message is
+     * delivered once. Default: `console.warn` / `console.error`. Override to silence or route (e.g. dev only).
+     */
+    onLog?: (entry: IconLogEntry) => void;
+}
+/** Validated configuration built by `configureIcons`. Record sources are referenced, not copied. */
+export interface ResolvedIconConfig<C = unknown> {
+    /** Component for `webType`/`webRef`, or `undefined`. Never throws. */
+    readonly resolve: (webType: string | undefined, webRef: string | undefined) => C | undefined;
+    readonly fontTypes: ReadonlySet<string>;
+    /** Never throws: logs and returns `''` if the user's sanitizer throws. */
+    readonly sanitize: ((html: string) => string) | undefined;
+    readonly fallback: C | undefined;
+    readonly size: number;
+    readonly strokeWidth: number;
+}

package/dist/types.js

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

package/llms.txt

@@ -0,0 +1,57 @@
+# @dynamic-icon/core
+
+> Framework-independent, zero-dependency icon registry. Maps `webType` + `webRef` strings from a database to components, and stores fallback, defaults, a markup sanitizer and a log hook. The component type is a generic parameter `C`. For Svelte 5 use `@dynamic-icon/svelte`, which re-exports a typed `configureIcons` / `resolveIcon` over this package.
+
+## API
+
+- `configureIcons<C>(config: IconConfig<C>): void`: validates eagerly and replaces the whole configuration. On invalid input it throws and the previous configuration stays active.
+- `resolveIcon<C>(webType, webRef): C | undefined`: the lookup the component uses. Never throws.
+- `getIconConfig<C>(): ResolvedIconConfig<C>`: the current configuration (defaults apply until `configureIcons` is called).
+
+## IconConfig
+
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `sources` | `Record<webType, Record<ref, C> \| (ref) => C \| undefined>` | `{}` | Component sources by `webType`. `image`, `emoji`, `markup` are reserved and throw. |
+| `fontTypes` | `string[]` | `['material','font-awesome','remix']` | `webType`s rendered as `<i class={webRef}>` by the framework binding. Must not collide with sources or reserved names. |
+| `sanitize` | `(html: string) => string` | none | Required for `markup`. Failures are logged and yield `''`. |
+| `fallback` | `C` | none | Rendered by the framework binding when nothing resolves. |
+| `defaults` | `{ size?: number; strokeWidth?: number }` | `{ size: 24, strokeWidth: 2 }` | Must be positive finite numbers or it throws. |
+| `onLog` | `(entry: { type: 'error' \| 'warn'; message: string; error?: unknown }) => void` | `console.warn` / `console.error` | Receives diagnostics (below). Override to silence or route, e.g. dev only. |
+
+## Sources
+
+- A record is held **by reference, never copied** (no extra memory; module namespaces work as-is). Lookups use `Object.hasOwn`, so `constructor`, `__proto__`, `toString` never resolve. Treat the object as read-only: later mutations are visible to lookups, and on a server would be shared across requests.
+- A function source gets full control (key normalisation, lazy tables, memoisation). It is the way to defer loading; there is no separate getter mode.
+
+## Logging (`onLog`)
+
+Reported by `resolve` (so for every icon the framework binding renders):
+
+| When | type | message |
+| --- | --- | --- |
+| `webType` is a configured source but the ref is missing | `warn` | `icon "x" not found in source "lucide"` |
+| `webType` is not a source, built-in (`image`, `emoji`, `markup`) or font type | `warn` | `unknown webType "x" ...` |
+| `webType` is `markup` and no `sanitize` is configured | `error` | `"markup" icon not rendered: configureIcons({ sanitize }) is not set` |
+| A function source throws | `error` (+ `error`) | `source "x" threw while resolving "y"` |
+| `sanitize` throws | `error` (+ `error`) | `sanitize threw; icon rendered empty` |
+
+Not logged: empty records (no `webType` or no `webRef`), built-in types, font types.
+Each distinct message is delivered **once per configuration** (1,000 icons with one typo log once; a server does not log per request). After 500 distinct messages one suppression notice is sent and the rest are dropped. A throwing `onLog` is swallowed: logging never breaks rendering.
+
+Dev-only logging in a Vite app: `onLog: import.meta.env.DEV ? undefined : () => {}` (`undefined` keeps the console default).
+
+## Registry and SSR
+
+- State is one holder object on `globalThis[Symbol.for('@dynamic-icon/core@1')]`, captured once per module so reads are plain property access. Duplicate installs share it; `@1` is the holder format version (bumped on breaking changes so incompatible copies never share state).
+- The configuration is app-wide data that does not vary per request, so a process-wide singleton is safe on the server. Call `configureIcons` once at module scope, identically on server and client; never per request or per component. Per-request or per-tenant icon sets are not supported.
+- Built with `lib: ES2022` only: no DOM, no Node typings, no dependencies.
+
+## Docs
+
+- [Svelte binding and full documentation](https://unpkg.com/@dynamic-icon/svelte/llms-full.txt)
+- [README](https://unpkg.com/@dynamic-icon/core/README.md)
+
+## Optional
+
+- Same files via jsDelivr: https://cdn.jsdelivr.net/npm/@dynamic-icon/core/llms.txt

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@dynamic-icon/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.2",
+  "description": "Framework-independent icon registry: maps database identifiers to components. Zero dependencies.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./llms.txt": "./llms.txt",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "llms.txt"
+  ],
+  "devDependencies": {
+    "publint": "^0.2.12",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "lint:package": "publint"
+  }
 }