@dynamic-icon/core 0.0.0-stage → 0.1.1

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 @@
-# Temporary Holding Version
-
-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.
+# @dynamic-icon/core

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,98 @@
+/** `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"];
+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, report) {
+    if (typeof source === "function") {
+        return (ref) => {
+            try {
+                return source(ref);
+            }
+            catch (error) {
+                report(error);
+                return undefined;
+            }
+        };
+    }
+    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.onError !== undefined && typeof config.onError !== "function") {
+        throw new TypeError("[dynamic-icon] onError must be a function");
+    }
+    const report = config.onError ?? ((error) => console.error("[dynamic-icon]", 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, report));
+    }
+    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) => (webType && webRef ? resolvers.get(webType)?.(webRef) : undefined),
+        fontTypes,
+        sanitize: sanitize
+            ? (html) => {
+                try {
+                    return sanitize(html);
+                }
+                catch (error) {
+                    report(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, 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,34 @@
+/**
+ * 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 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 errors thrown by function sources or `sanitize`. Default: `console.error`. The icon renders as unresolved. */
+    onError?: (error: unknown) => 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: 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,56 @@
+# @dynamic-icon/core
+
+Framework-independent icon registry. It maps `webType` + `webRef` pairs stored in a database (`lucide` + `car-front`)
+to components, and holds the fallback, defaults and markup sanitizer. **Zero dependencies, no DOM, no framework**
+(compiled with `lib: ES2022` only). The component type is a generic parameter, so any UI framework can reuse it;
+[`@dynamic-icon/svelte`](../svelte) is the Svelte 5 binding and re-exports everything you need.
+
+Most apps never import this package directly; they use `configureIcons` from `@dynamic-icon/svelte`.
+
+```ts
+import { configureIcons, resolveIcon } from '@dynamic-icon/core';
+
+configureIcons<MyComponent>({
+  sources: {
+    lucide: { 'car-front': CarFront },            // record keyed by the DB identifier (held by reference)
+    svg: (ref) => customIcons[toPascal(ref)]      // or a function: full control, memoise it yourself
+  },
+  fallback: CircleHelp,
+  defaults: { size: 24, strokeWidth: 2 },
+  sanitize: (html) => DOMPurify.sanitize(html),   // required for `markup`
+  onError: (e) => report(e)                       // function sources / sanitize that throw; default console.error
+});
+
+resolveIcon<MyComponent>('lucide', 'car-front'); // CarFront | undefined
+```
+
+## Behaviour
+
+- `configureIcons` validates eagerly (reserved names `image`/`emoji`/`markup`, non-positive defaults, wrong types), **throws and
+  keeps the previous configuration** on error, and otherwise replaces the whole configuration.
+- Record sources are **held by reference, never copied** (no extra memory; module namespaces work as-is). Lookups use
+  `Object.hasOwn`, so `constructor` / `__proto__` never resolve to `Object.prototype` members. Treat source objects as read-only:
+  later mutations are visible to lookups (and, on a server, would be shared across requests).
+- Function sources and `sanitize` are wrapped: a throw is reported to `onError` and the icon renders as unresolved.
+- The registry lives on `globalThis[Symbol.for('@dynamic-icon/core@1')]` and is captured once per module, so reads are a plain
+  property access. Duplicate installs of this package share one registry. The `@1` is the holder's format version.
+- SSR: the configuration is app-wide data that never changes per request, identical for every request, so a process-wide singleton is safe.
+  Call `configureIcons` once at module scope (e.g. `hooks.server.ts` / root `+layout.ts`), never per request or per component.
+
+> Framework-independent, zero-dependency icon registry. Maps `webType` + `webRef` strings from a database to components, and stores fallback, defaults, a markup sanitizer and an error 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.
+
+Key facts:
+- API: `configureIcons<C>(config)`, `resolveIcon<C>(webType, webRef): C | undefined`, `getIconConfig<C>()`.
+- `configureIcons` validates eagerly, throws (keeping the previous config) on invalid input, and replaces the whole configuration.
+- Record sources are held by reference (never copied; looked up with `Object.hasOwn`, so prototype keys cannot resolve; treat them as read-only); function sources and `sanitize` never throw to the caller (errors go to `onError`, default `console.error`).
+- State lives on `globalThis[Symbol.for('@dynamic-icon/core@1')]`, captured once per module; duplicate installs share one registry.
+- Reserved `webType` names (not allowed as source names): `image`, `emoji`, `markup`.
+
+## Docs
+
+- [Full documentation (Svelte binding + core)](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.1",
+  "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"
+  }
 }