@dynamic-icon/svelte 0.1.1 → 0.1.2

package/README.md

@@ -1,35 +1,27 @@
 # @dynamic-icon/svelte
 
-Svelte 5 component that renders icons from database records. It knows nothing about any icon library: you register
-sources once with `configureIcons` (backed by the framework-free [`@dynamic-icon/core`](../core), installed automatically).
+> Experimental package — do not use in production.
+
+Svelte 5 component that renders icons from database records (`{ webType: 'lucide', webRef: 'car-front' }`).
+Icon-library agnostic: you register the icons you use once. Built for pages with hundreds of icons.
+
+```bash
+pnpm add @dynamic-icon/svelte lucide-svelte
+```
 
 ```ts
-// app root, once (identically on server and client)
+// app root, once, same on server and client
 import { configureIcons } from '@dynamic-icon/svelte';
 import CarFront from 'lucide-svelte/icons/car-front';
 
-configureIcons({ sources: { lucide: { 'car-front': CarFront } }, fallback: CircleHelp });
+configureIcons({ sources: { lucide: { 'car-front': CarFront } } });
 ```
 
 ```svelte
 <DynamicIcon {...record.icon} size={24} class="text-primary" />
 ```
 
-Props: `webType`, `webRef`, `color`, `media`, `scale`, `size`, `strokeWidth`, `class`, `fallback` (snippet).
-
-| Prop | Notes |
-| --- | --- |
-| `webType` / `webRef` | `image`, `emoji`, `markup`, a font type (`material`, `font-awesome`, `remix`) or a configured source. |
-| `color` | A CSS colour (`#fff`, `rgb()`, `oklch()`, `var()`, `red`) goes in `style`; anything else is added as classes. |
-| `size` | px for numbers; a plain CSS length for strings (`1.5rem`). Invalid values (including `24px;...`) use the default size. |
-| `scale` | Multiplies a numeric `size`, rounded. Ignored if not a positive finite number. |
-| `fallback` | Snippet shown when unresolved; wins over `configureIcons({ fallback })`. |
-
-- Only `image` and `markup` icons get a wrapper `<span>`; everything else is a single element. All icons are `aria-hidden`
-  (decorative): put meaning in adjacent text, or give the parent an `aria-label`.
-- `markup` renders only through your `sanitize` function; without one it shows the fallback. `image` uses `loading="lazy"`.
-- Icon components receive `size`, `strokeWidth`, `class`, `style` (CSS colours only) and `aria-hidden`; `lucide-svelte` icons
-  accept these as-is. Custom icons should spread rest props onto their root `<svg>`.
+Icons that can't be resolved render nothing (or your `fallback`) and are reported once through `onLog`.
 
-AI-readable docs: [`llms.txt`](./llms.txt) and [`llms-full.txt`](./llms-full.txt), shipped in the npm package, e.g.
-`https://unpkg.com/@dynamic-icon/svelte/llms-full.txt` once published.
+**Full documentation** (props, configuration, logging, security, SSR, performance, architecture): [`llms-full.txt`](./llms-full.txt)
+and [`llms.txt`](./llms.txt), shipped in the npm package, e.g. `https://unpkg.com/@dynamic-icon/svelte/llms-full.txt`.

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 export { default as DynamicIcon } from "./DynamicIcon.svelte";
 export { configureIcons, resolveIcon } from "./config.js";
-export type { IconComponent, IconComponentProps, IconConfig, IconEntry, IconMedia, IconProps, IconSource } from "./types.js";
+export type { IconComponent, IconComponentProps, IconConfig, IconEntry, IconLogEntry, IconMedia, IconProps, IconSource } from "./types.js";

package/dist/types.d.ts

@@ -1,5 +1,6 @@
 import type { Component, ComponentType, Snippet, SvelteComponent } from "svelte";
 import type { IconConfig as CoreIconConfig, IconSource as CoreIconSource } from "@dynamic-icon/core";
+export type { IconLogEntry } from "@dynamic-icon/core";
 /** Props `DynamicIcon` passes to every icon component. `lucide-svelte` icons already accept them. */
 export interface IconComponentProps {
     size?: number | string;

package/llms-full.txt

@@ -44,7 +44,7 @@ configureIcons({
 | `sanitize` | `(html: string) => string` | none | Required for `markup`. Without it, `markup` icons show the fallback. |
 | `fallback` | `Component` | none | Rendered when nothing resolves (unknown icon, empty record, failed source). A per-instance `fallback` snippet wins. |
 | `defaults` | `{ size?: number; strokeWidth?: number }` | `{ size: 24, strokeWidth: 2 }` | Must be positive finite numbers or it throws. |
-| `onError` | `(error: unknown) => void` | `console.error` | Receives errors thrown by function sources or `sanitize`. |
+| `onLog` | `(entry: { type: 'error' \| 'warn'; message: string; error?: unknown }) => void` | `console.warn` / `console.error` | Diagnostics (see section 5). Override to silence or route, e.g. dev only. |
 
 Semantics: validates eagerly; on invalid input it throws and the previous configuration stays active; on success it replaces the
 whole configuration (idempotent). Record sources are held by reference, never copied (lookups use `Object.hasOwn`, so
@@ -80,46 +80,64 @@ accept these. Custom icons should spread rest props onto their root `<svg>`. Exp
 3. `markup` with `webRef` and a configured `sanitize` -> sized wrapper `<span>` with `{@html sanitize(webRef)}`.
 4. `emoji` -> `<span style="font-size">`.
 5. Font type -> `<i class="{webRef} ...">`.
-6. Else: per-instance `fallback` snippet, else `configureIcons({ fallback })`, else nothing.
+6. Else: per-instance `fallback` snippet, else `configureIcons({ fallback })`, else **nothing: no DOM node is rendered** (layout collapses, no placeholder).
 
-## 5. Security model
+## 5. Undefined icons and logging
+An icon that cannot be resolved never throws; it follows the fallback chain in section 4 and is reported through `onLog`.
+
+| When | type | message |
+| --- | --- | --- |
+| `webType` is a configured source, ref missing | `warn` | `icon "x" not found in source "lucide"` |
+| `webType` is not a source, built-in or font type | `warn` | `unknown webType "x" ...` |
+| `markup` without `sanitize` | `error` | `"markup" icon not rendered: configureIcons({ sanitize }) is not set` |
+| 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`/`webRef`), built-in types, font types, `image` without `media.link`.
+- Each distinct message is delivered once per configuration: 1,000 icons with the same 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. Default sink: `console.warn` / `console.error` (the original error is the second argument).
+- Dev-only in a Vite app: `configureIcons({ ..., onLog: import.meta.env.DEV ? undefined : () => {} })` (`undefined` keeps the console default). Route to monitoring: `onLog: (e) => Sentry.captureMessage(e.message, e.type === 'error' ? 'error' : 'warning')`.
+- Logging happens during resolution, so it also runs on the server (once per distinct message per process).
+
+## 6. Security model
 - DB-controlled strings reach the DOM only as: escaped text, class tokens, `<img src>`, a validated CSS colour, a validated CSS length, and (for `markup`) sanitizer output.
 - `color` is only placed in `style` if it matches a strict colour grammar (no `;`, braces, quotes); otherwise it is a class token, which cannot inject declarations.
 - `size` strings must match a plain CSS length; numbers must be finite and > 0.
 - `markup` is never rendered unsanitized. Provide a real sanitizer (e.g. DOMPurify on the client, an SSR-capable one on the server); an identity function is unsafe.
 - `media.link` is not scheme-filtered; validate image URLs upstream if they are user-supplied.
 - Registry keys are looked up with `Object.hasOwn`: prototype keys cannot resolve.
-- A throwing function source or sanitizer cannot crash the page: it is reported to `onError` and the icon renders as unresolved.
+- A throwing function source or sanitizer cannot crash the page: it is logged through `onLog` and the icon renders as unresolved.
 
-## 6. SSR rules
+## 7. SSR rules
 - The configuration is app-wide data, identical for all requests, so a process-wide singleton is safe. Never mutate a source record per request (it is shared by reference). Per-request or per-tenant icon sets are not supported; use a function source that reads your own request-scoped state only if you accept that trade-off.
 - Call `configureIcons` once at module scope, on both server and client, with the same config (otherwise hydration markup can differ). Do not call it inside components or per request.
 - Components read the config once at instance creation; configure before the first render.
 - Nothing touches `window`/`document` at import or render time.
 
-## 7. Performance notes
+## 8. Performance notes
 - Per icon: one registry lookup (`Object.hasOwn` + index), one `$derived`, plain string building. No `tailwind-merge`/`clsx`, no string case conversion.
 - Bundle: the package imports no icon library. Only icons you list in `sources` ship. Use per-icon imports; never `import * as Icons`.
 - Measured (Node, 1,000 icons): `Map.get` ~16-19 ns, `Object.hasOwn` + index ~23 ns, `globalThis[Symbol]` ~5 ns. Sources are held by reference, so the registry adds no copy of your icon data; the difference between strategies is a few ns per icon, negligible next to component instantiation.
 - Only `image`/`markup` add a wrapper element. Component icons render a single element.
 - Wrapper styles are scoped CSS in the component (Tailwind does not scan `node_modules`).
 
-## 8. Architecture
+## 9. Architecture
 - `@dynamic-icon/core`: pure TypeScript (`lib: ES2022`, no DOM, no deps). `configureIcons`, `resolveIcon`, `getIconConfig`, generic over the component type `C`. State: one holder object at `globalThis[Symbol.for('@dynamic-icon/core@1')]`, captured per module so reads are plain property access; duplicate installs share it; the `@1` is the holder format version.
 - `@dynamic-icon/svelte`: `DynamicIcon.svelte`, typed wrappers fixing `C = IconComponent`, small pure helpers (`utils.ts`). Ships `.svelte` source via `svelte-package`.
 - Store choice: a global holder (not Svelte context) with sources held by reference. Context would add a `getContext` per instance, only works during component init, needs a provider around every consumer (including other libraries' components and separately mounted roots), and buys only per-request isolation that an app-wide icon set does not need. Why not Svelte context: the registry is app-wide config; context adds a lookup per instance and only works during component init. Why not per-instance props: 1,000 icons would each carry the config.
 - Adding another framework: create `@dynamic-icon/<framework>` with a component calling `getIconConfig<Component>()`; reuse core and `utils` logic.
 
-## 9. Common mistakes
+## 10. Common mistakes
 - `import * as Icons from 'lucide-svelte'` as a source: ships every icon. Register individual icons.
 - Using PascalCase keys with kebab-case DB values: use a function source (`(ref) => map[toPascal(ref)]`) or kebab-case keys.
 - Calling `configureIcons` in a component or per request.
-- Expecting `markup` to render without `sanitize`.
+- Expecting `markup` to render without `sanitize` (it logs an error and shows the fallback).
+- Wanting silent production: pass an `onLog` that returns early outside dev; do not rely on the console default.
 - Passing `size="24px;..."` or `size="calc(...)"`: falls back to the default size.
 - Expecting Tailwind conflict resolution between `color` and `class`: classes are concatenated, not merged.
 - Using `webType: 'image'|'emoji'|'markup'` as a source name: throws at configure time.
 
-## 10. Types
+## 11. Types
 `IconEntry<T extends string = string>` { name?, webType?, webRef?, color?, media?, scale? }; `IconProps<T>` adds { size?, class?, strokeWidth?, fallback? };
-`IconMedia` { link, caption? }; `IconConfig`, `IconSource`, `IconComponent`, `IconComponentProps` exported from `@dynamic-icon/svelte`.
-Core exports `IconConfig<C>`, `IconSource<C>`, `ResolvedIconConfig<C>`.
+`IconMedia` { link, caption? }; `IconLogEntry` { type: 'error' | 'warn'; message; error? }; `IconConfig`, `IconSource`, `IconComponent`, `IconComponentProps` exported from `@dynamic-icon/svelte`.
+Core exports `IconConfig<C>`, `IconSource<C>`, `IconLogEntry`, `ResolvedIconConfig<C>`.

package/llms.txt

@@ -4,9 +4,10 @@
 
 Key facts for code generation:
 - Install `@dynamic-icon/svelte` (peer: `svelte@^5`). It depends on `@dynamic-icon/core`, a zero-dependency registry; do not install core separately.
-- Call `configureIcons({ sources, fallback?, defaults?, sanitize?, fontTypes?, onError? })` exactly once, at module scope of the app root, with identical config on server and client. Never inside a component or per request.
+- Call `configureIcons({ sources, fallback?, defaults?, sanitize?, fontTypes?, onLog? })` exactly once, at module scope of the app root, with identical config on server and client. Never inside a component or per request.
 - Register only the icons you need, with per-icon imports (`import CarFront from 'lucide-svelte/icons/car-front'`), keyed by the identifier stored in the database. Never `import * as` a whole library: it defeats tree-shaking.
 - Render with `<DynamicIcon {...record.icon} size={24} class="text-primary" />`.
+- Unresolvable icons render the fallback or nothing and are reported once each through `onLog({ type: 'error' | 'warn', message, error? })` (default: console). Override it to log only in development.
 - Libraries that render `DynamicIcon` need no setup; only the host app configures.
 - Built-in `webType`s: `image` (uses `media.link`), `emoji`, `markup` (needs `sanitize`), and icon fonts `material`, `font-awesome`, `remix` (`<i class={webRef}>`). Any other `webType` must be a configured source.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynamic-icon/svelte",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Tiny Svelte 5 component that renders database-driven icons. Sources are plugged in via @dynamic-icon/core.",
   "license": "MIT",
   "type": "module",
@@ -48,7 +48,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@dynamic-icon/core": "^0.1.1"
+    "@dynamic-icon/core": "^0.1.2"
   },
   "scripts": {
     "build": "svelte-package -i src -o dist",