tempest-react-sdk 0.47.0 → 0.49.0

package/dist/icons/shard-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"shard-cache.js","names":[],"sources":["../../src/icons/shard-cache.ts"],"sourcesContent":["import type { LucideIcon } from \"lucide-react\";\n\nimport { iconAliases } from \"./generated/aliases\";\nimport { shardLoaders } from \"./generated/loaders\";\n\n/**\n * Slugs resolved so far, across every shard already fetched.\n *\n * Module-level and readable **synchronously**, which is the whole point: once a\n * page has rendered one icon whose slug starts with `s`, every other `s` icon is\n * already in memory and paints on its first frame. A cache that could only be\n * read from an effect would flash a fallback for each new icon, which is the\n * behavior `lucide-react`'s own `DynamicIcon` has.\n */\nconst resolved = new Map<string, LucideIcon>();\n\n/** In-flight shard fetches, so N icons from one shard trigger one import. */\nconst inFlight = new Map<string, Promise<void>>();\n\n/**\n * Initial letters whose shard has already settled.\n *\n * Needed to tell \"still loading\" from \"no such icon\": until the shard arrives,\n * absence from `resolved` proves nothing. Only once the letter is in here does a\n * missing slug mean the name is genuinely wrong — which is what lets `Icon` warn\n * about a typo without also warning on every icon mid-flight.\n */\nconst settledLetters = new Set<string>();\n\n/** Callbacks to run after a shard lands, so mounted `<Icon>`s re-render. */\nconst listeners = new Set<() => void>();\n\n/**\n * Map a slug to the canonical slug that owns the icon.\n *\n * Lucide keeps 257 deprecated aliases (`alert-circle` → `circle-alert`), and a\n * slug persisted in a database years ago is exactly the case this feature exists\n * for, so an alias must keep resolving after a lucide bump renames it.\n *\n * @param slug - Any icon slug, canonical or deprecated.\n * @returns The canonical slug.\n */\nexport function resolveIconAlias(slug: string): string {\n    return iconAliases[slug] ?? slug;\n}\n\n/**\n * Read an icon out of the cache without triggering a fetch.\n *\n * @param slug - Any icon slug, canonical or deprecated.\n * @returns The icon component, or `undefined` when its shard is not loaded yet.\n */\nexport function peekIcon(slug: string): LucideIcon | undefined {\n    return resolved.get(resolveIconAlias(slug));\n}\n\n/**\n * Load the shard that owns `slug`, if it is not loaded or loading already.\n *\n * Resolves without error for an unknown slug: a name that came from an API is\n * data, not a programming mistake, so the caller renders its fallback instead of\n * seeing an exception thrown mid-render.\n *\n * @param slug - Any icon slug, canonical or deprecated.\n * @returns A promise that settles once the shard is in the cache.\n */\nexport function loadIcon(slug: string): Promise<void> {\n    const canonical = resolveIconAlias(slug);\n    if (resolved.has(canonical)) return Promise.resolve();\n\n    const letter = canonical[0] ?? \"\";\n    const loader = shardLoaders[letter];\n    if (!loader) return Promise.resolve();\n\n    const pending = inFlight.get(letter);\n    if (pending) return pending;\n\n    const promise = loader()\n        .then((mod) => {\n            for (const [name, icon] of Object.entries(mod.default)) resolved.set(name, icon);\n        })\n        .catch(() => undefined)\n        .finally(() => {\n            inFlight.delete(letter);\n            settledLetters.add(letter);\n            for (const listener of listeners) listener();\n        });\n    inFlight.set(letter, promise);\n    return promise;\n}\n\n/**\n * Whether a slug is ready, still loading, or not an icon at all.\n *\n * `\"missing\"` is only reported once that is actually knowable: either lucide has\n * no icons under that initial letter, or the letter's shard already settled\n * without the slug in it.\n *\n * @param slug - Any icon slug, canonical or deprecated.\n * @returns The slug's resolution state.\n */\nexport function iconStatus(slug: string): \"ready\" | \"loading\" | \"missing\" {\n    const canonical = resolveIconAlias(slug);\n    if (resolved.has(canonical)) return \"ready\";\n    const letter = canonical[0] ?? \"\";\n    if (!shardLoaders[letter]) return \"missing\";\n    return settledLetters.has(letter) ? \"missing\" : \"loading\";\n}\n\n/**\n * Warm the cache for slugs you know you are about to render.\n *\n * Useful right before opening a menu or a picker: the shards land while the user\n * is still reaching for it, so nothing flashes a fallback.\n *\n * @param slugs - Icon slugs to preload.\n * @returns A promise that settles when every needed shard is in the cache.\n */\nexport async function preloadIcons(slugs: readonly string[]): Promise<void> {\n    await Promise.all(slugs.map(loadIcon));\n}\n\n/**\n * Subscribe to shard arrivals.\n *\n * @param listener - Called after each shard lands.\n * @returns An unsubscribe function.\n */\nexport function subscribeToIcons(listener: () => void): () => void {\n    listeners.add(listener);\n    return () => listeners.delete(listener);\n}\n"],"mappings":";;;AAcA,IAAM,oBAAW,IAAI,IAAwB,GAGvC,oBAAW,IAAI,IAA2B,GAU1C,oBAAiB,IAAI,IAAY,GAGjC,oBAAY,IAAI,IAAgB;AAYtC,SAAgB,EAAiB,GAAsB;CACnD,OAAO,EAAY,MAAS;AAChC;AAQA,SAAgB,EAAS,GAAsC;CAC3D,OAAO,EAAS,IAAI,EAAiB,CAAI,CAAC;AAC9C;AAYA,SAAgB,EAAS,GAA6B;CAClD,IAAM,IAAY,EAAiB,CAAI;CACvC,IAAI,EAAS,IAAI,CAAS,GAAG,OAAO,QAAQ,QAAQ;CAEpD,IAAM,IAAS,EAAU,MAAM,IACzB,IAAS,EAAa;CAC5B,IAAI,CAAC,GAAQ,OAAO,QAAQ,QAAQ;CAEpC,IAAM,IAAU,EAAS,IAAI,CAAM;CACnC,IAAI,GAAS,OAAO;CAEpB,IAAM,IAAU,EAAO,CAAC,CACnB,MAAM,MAAQ;EACX,KAAK,IAAM,CAAC,GAAM,MAAS,OAAO,QAAQ,EAAI,OAAO,GAAG,EAAS,IAAI,GAAM,CAAI;CACnF,CAAC,CAAC,CACD,YAAY,KAAA,CAAS,CAAC,CACtB,cAAc;EAEX,AADA,EAAS,OAAO,CAAM,GACtB,EAAe,IAAI,CAAM;EACzB,KAAK,IAAM,KAAY,GAAW,EAAS;CAC/C,CAAC;CAEL,OADA,EAAS,IAAI,GAAQ,CAAO,GACrB;AACX;AAYA,SAAgB,EAAW,GAA+C;CACtE,IAAM,IAAY,EAAiB,CAAI;CACvC,IAAI,EAAS,IAAI,CAAS,GAAG,OAAO;CACpC,IAAM,IAAS,EAAU,MAAM;CAE/B,OADK,EAAa,KACX,EAAe,IAAI,CAAM,IAAI,YAAY,YADd;AAEtC;AAWA,eAAsB,EAAa,GAAyC;CACxE,MAAM,QAAQ,IAAI,EAAM,IAAI,CAAQ,CAAC;AACzC;AAQA,SAAgB,EAAiB,GAAkC;CAE/D,OADA,EAAU,IAAI,CAAQ,SACT,EAAU,OAAO,CAAQ;AAC1C"}
+{"version":3,"file":"shard-cache.js","names":[],"sources":["../../src/icons/shard-cache.ts"],"sourcesContent":["import type { LucideIcon } from \"lucide-react\";\n\nimport { isDevBuild } from \"../utils/dev-mode\";\nimport { resolveIconAlias } from \"./alias\";\nimport { iconShards, type IconShard } from \"./generated/loaders\";\n\n/**\n * Slugs resolved so far, across every shard already fetched.\n *\n * Module-level and readable **synchronously**, which is the whole point: once a\n * page has rendered one icon, every other icon in that shard's range is already in\n * memory and paints on its first frame. A cache that could only be read from an\n * effect would flash a fallback for each new icon, which is the behavior\n * `lucide-react`'s own `DynamicIcon` has.\n */\nconst resolved = new Map<string, LucideIcon>();\n\n/** In-flight shard fetches, so N icons from one shard trigger one import. */\nconst inFlight = new Map<string, Promise<void>>();\n\n/**\n * Find the shard that owns a slug.\n *\n * The shards are contiguous, sorted ranges, so this is a binary search over their\n * lower bounds — 45 entries in the index rather than the 2000-entry slug→chunk map\n * that costs 120 KB in a main chunk.\n *\n * A slug sorting before the first range belongs to no shard, which is knowable\n * without any fetch: `\"0-not-an-icon\"` cannot be a lucide name.\n *\n * @param canonical - A canonical slug, aliases already resolved.\n * @returns The owning shard, or `undefined` when no range can hold it.\n */\nfunction shardFor(canonical: string): IconShard | undefined {\n    if (canonical === \"\" || canonical < iconShards[0].from) return undefined;\n\n    let low = 0;\n    let high = iconShards.length - 1;\n    while (low < high) {\n        const mid = Math.ceil((low + high) / 2);\n        if (iconShards[mid].from <= canonical) low = mid;\n        else high = mid - 1;\n    }\n    return iconShards[low];\n}\n\n/**\n * Shard ids whose chunk actually arrived.\n *\n * Needed to tell \"still loading\" from \"no such icon\": until the shard arrives,\n * absence from `resolved` proves nothing. Only once the shard is in here does a\n * missing slug mean the name is genuinely wrong — which is what lets `Icon` warn\n * about a typo without also warning on every icon mid-flight.\n *\n * A shard that *failed* deliberately does not land here. Collapsing \"the chunk\n * 404'd\" into \"no such icon\" is what made a stale deploy look like a typo.\n */\nconst loadedShards = new Set<string>();\n\n/**\n * Shards whose fetch gave up, and when.\n *\n * The timestamp is what stops a permanent fallback: `useIcon` re-runs its effect\n * on every miss, so a shard is retried on a later render — after a cooldown, so a\n * chunk that is genuinely gone cannot turn into a request loop.\n */\nconst failedShards = new Map<string, number>();\n\n/**\n * Backoff before each retry, in milliseconds.\n *\n * Two retries, both fast, because the failure this exists for is a transient one:\n * a flaky connection, or a chunk whose CDN edge has not caught up. A 404 from a\n * deploy that rotated hashed filenames is *not* fixed by retrying — for that, the\n * error subscription is the signal, and the app reloads.\n */\nconst RETRY_DELAYS = [100, 400] as const;\n\n/** How long a failed shard is left alone before another render may retry it. */\nconst RETRY_COOLDOWN_MS = 10_000;\n\n/** What a shard failure reports to whoever subscribed. */\nexport interface IconLoadError {\n    /** The shard key whose chunk could not be fetched. */\n    shard: string;\n    /** The slug whose render asked for it. */\n    slug: string;\n    /** Attempts made before giving up, retries included. */\n    attempts: number;\n    /** The last rejection from the dynamic import. */\n    error: unknown;\n}\n\n/** Callbacks to run when a shard fetch gives up. */\nconst errorListeners = new Set<(detail: IconLoadError) => void>();\n\n/** Callbacks to run after a shard lands, so mounted `<Icon>`s re-render. */\nconst listeners = new Set<() => void>();\n\n/**\n * Make icon components resolvable by slug, with no provider and no plugin.\n *\n * Call it once from an entrypoint. The icons land in the same table a fetched\n * shard fills, so every `<Icon>` below — including one that renders before the\n * call, since registering notifies subscribers — resolves them synchronously and\n * never issues a request.\n *\n * This is the whole setup for a closed catalog: an admin panel with twenty known\n * icons pays two lines instead of a build plugin plus a provider. `IconProvider`\n * stays for what is genuinely tree-scoped — the `size`/`strokeWidth` defaults and\n * a registry that must override the global one for one subtree.\n *\n * A slug lucide does not ship is registered as-is, which is how an app adds its\n * own artwork to the same `<Icon name>` call site.\n *\n * @example\n * import { registerIcons } from \"tempest-react-sdk/icons\";\n * import { Save, Trash2 } from \"lucide-react\";\n *\n * registerIcons({ save: Save, \"trash-2\": Trash2 });\n *\n * @param icons - Slug → icon component. Deprecated slugs are stored under the\n *   canonical name, so both spellings resolve.\n */\nexport function registerIcons(icons: Readonly<Record<string, LucideIcon>>): void {\n    let changed = false;\n    for (const [slug, icon] of Object.entries(icons)) {\n        const canonical = resolveIconAlias(slug);\n        if (resolved.get(canonical) === icon) continue;\n        resolved.set(canonical, icon);\n        changed = true;\n    }\n    if (!changed) return;\n    for (const listener of listeners) listener();\n}\n\n/**\n * Read an icon out of the cache without triggering a fetch.\n *\n * @param slug - Any icon slug, canonical or deprecated.\n * @returns The icon component, or `undefined` when its shard is not loaded yet.\n */\nexport function peekIcon(slug: string): LucideIcon | undefined {\n    return resolved.get(resolveIconAlias(slug));\n}\n\n/**\n * Load the shard that owns `slug`, if it is not loaded or loading already.\n *\n * Resolves without error for an unknown slug: a name that came from an API is\n * data, not a programming mistake, so the caller renders its fallback instead of\n * seeing an exception thrown mid-render.\n *\n * @param slug - Any icon slug, canonical or deprecated.\n * @returns A promise that settles once the shard is in the cache.\n */\nexport function loadIcon(slug: string): Promise<void> {\n    const canonical = resolveIconAlias(slug);\n    if (resolved.has(canonical)) return Promise.resolve();\n\n    const shard = shardFor(canonical);\n    if (!shard) return Promise.resolve();\n\n    const pending = inFlight.get(shard.id);\n    if (pending) return pending;\n\n    const failedAt = failedShards.get(shard.id);\n    if (failedAt !== undefined && performance.now() - failedAt < RETRY_COOLDOWN_MS) {\n        return Promise.resolve();\n    }\n\n    const promise = fetchShard(shard, canonical).finally(() => {\n        inFlight.delete(shard.id);\n        for (const listener of listeners) listener();\n    });\n    inFlight.set(shard.id, promise);\n    return promise;\n}\n\n/**\n * Fetch one shard, retrying a couple of times before giving up.\n *\n * Never rejects: an icon whose chunk did not arrive is a rendering outcome, not a\n * programming mistake, so the caller keeps showing its fallback. What it does\n * instead of swallowing the failure is record it — so `iconStatus` can say\n * `\"error\"` rather than lying with `\"missing\"` — and report it to whoever\n * subscribed.\n *\n * @param shard - The shard being fetched.\n * @param slug - The canonical slug whose render asked for it, for the report.\n * @returns A promise that settles once the attempts are done.\n */\nasync function fetchShard(shard: IconShard, slug: string): Promise<void> {\n    let lastError: unknown;\n\n    for (let attempt = 0; attempt <= RETRY_DELAYS.length; attempt += 1) {\n        try {\n            const mod = await shard.load();\n            for (const [name, icon] of Object.entries(mod.default)) resolved.set(name, icon);\n            loadedShards.add(shard.id);\n            failedShards.delete(shard.id);\n            return;\n        } catch (error) {\n            lastError = error;\n            const backoff = RETRY_DELAYS[attempt];\n            if (backoff === undefined) break;\n            await sleep(backoff);\n        }\n    }\n\n    failedShards.set(shard.id, performance.now());\n    reportIconLoadError({\n        shard: shard.id,\n        slug,\n        attempts: RETRY_DELAYS.length + 1,\n        error: lastError,\n    });\n}\n\n/**\n * Wait, as a promise.\n *\n * @param ms - Delay in milliseconds.\n * @returns A promise resolved after the delay.\n */\nfunction sleep(ms: number): Promise<void> {\n    return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/**\n * Hand a shard failure to whoever is listening.\n *\n * With no subscriber the failure would be silent, which is the state this\n * replaces — so in a dev build it warns instead. An app that wired the\n * subscription up owns the reporting from then on and gets no console noise.\n *\n * @param detail - What failed.\n */\nfunction reportIconLoadError(detail: IconLoadError): void {\n    if (errorListeners.size === 0) {\n        if (isDevBuild()) warnShardFailure(detail);\n        return;\n    }\n    for (const listener of errorListeners) listener(detail);\n}\n\nconst warnedShards = new Set<string>();\n\n/**\n * Warn once per shard that failed to load.\n *\n * Once, because every `<Icon>` under that letter re-triggers the path and a\n * warning per icon would bury the console.\n *\n * @param detail - What failed.\n */\nfunction warnShardFailure({ shard, slug, attempts }: IconLoadError): void {\n    if (warnedShards.has(shard)) return;\n    warnedShards.add(shard);\n    console.warn(\n        `[tempest-react-sdk] icon shard \"${shard}\" failed to load after ${attempts} attempts ` +\n            `(first asked for by \"${slug}\"). The usual cause is a deploy that rotated hashed ` +\n            `chunk names while this tab was open. Subscribe with \\`subscribeToIconErrors\\` to ` +\n            `report it and reload.`,\n    );\n}\n\n/**\n * Subscribe to shard fetches that gave up.\n *\n * The failure is routine in a long-lived tab: a deploy rotates hashed chunk\n * names, the old asset leaves the CDN, and the next icon that needs it 404s. That\n * used to end in a permanent fallback with no signal — nothing for the user,\n * nothing for observability. Subscribing is what turns it into both.\n *\n * @example\n * import { subscribeToIconErrors } from \"tempest-react-sdk/icons\";\n *\n * subscribeToIconErrors(({ shard, error }) => {\n *     Sentry.captureException(error, { tags: { iconShard: shard } });\n *     promptReloadForStaleChunks();\n * });\n *\n * @param listener - Called once per shard that gave up.\n * @returns An unsubscribe function.\n */\nexport function subscribeToIconErrors(listener: (detail: IconLoadError) => void): () => void {\n    errorListeners.add(listener);\n    return () => errorListeners.delete(listener);\n}\n\n/**\n * Whether a slug is ready, loading, unknown, or unreachable.\n *\n * `\"missing\"` is only reported once that is actually knowable: either lucide has\n * no icons under that initial letter, or the letter's shard **arrived** without\n * the slug in it. A shard that failed to load reports `\"error\"` instead — the two\n * used to collapse into `\"missing\"`, which turned a stale deploy into what looked\n * like a typo and made `Icon` warn about a name that is perfectly valid.\n *\n * @param slug - Any icon slug, canonical or deprecated.\n * @returns The slug's resolution state.\n */\nexport function iconStatus(slug: string): \"ready\" | \"loading\" | \"missing\" | \"error\" {\n    const canonical = resolveIconAlias(slug);\n    if (resolved.has(canonical)) return \"ready\";\n    const shard = shardFor(canonical);\n    if (!shard) return \"missing\";\n    if (loadedShards.has(shard.id)) return \"missing\";\n    return failedShards.has(shard.id) ? \"error\" : \"loading\";\n}\n\n/**\n * Warm the cache for slugs you know you are about to render.\n *\n * Useful right before opening a menu or a picker: the shards land while the user\n * is still reaching for it, so nothing flashes a fallback.\n *\n * @param slugs - Icon slugs to preload.\n * @returns A promise that settles when every needed shard is in the cache.\n */\nexport async function preloadIcons(slugs: readonly string[]): Promise<void> {\n    await Promise.all(slugs.map(loadIcon));\n}\n\n/**\n * Subscribe to shard arrivals.\n *\n * @param listener - Called after each shard lands.\n * @returns An unsubscribe function.\n */\nexport function subscribeToIcons(listener: () => void): () => void {\n    listeners.add(listener);\n    return () => listeners.delete(listener);\n}\n"],"mappings":"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"}

package/dist/icons/validate-icon-name.cjs

@@ -0,0 +1,2 @@
+const e=require("./normalize-icon-name.cjs"),t=require("./is-icon-name.cjs");var n=`Ícone inexistente. Use um slug do lucide, em kebab-case.`;function r(n,r){if(n.trim()!==``)return t.isIconName(e.normalizeIconName(n))?void 0:r??`Ícone inexistente. Use um slug do lucide, em kebab-case.`}exports.DEFAULT_ICON_PICKER_MESSAGE=n,exports.validateIconName=r;
+//# sourceMappingURL=validate-icon-name.cjs.map

package/dist/icons/validate-icon-name.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-icon-name.cjs","names":[],"sources":["../../src/icons/validate-icon-name.ts"],"sourcesContent":["import { isIconName } from \"./is-icon-name\";\nimport { normalizeIconName } from \"./normalize-icon-name\";\n\n/** The default message for a slug lucide does not ship. */\nexport const DEFAULT_ICON_PICKER_MESSAGE =\n    \"Ícone inexistente. Use um slug do lucide, em kebab-case.\";\n\n/**\n * Validate an icon slug the way `IconPicker` does.\n *\n * Its own module rather than living next to the component: a file that exports\n * both a component and other values breaks Fast Refresh in a consuming dev\n * server, which is what `react-refresh/only-export-components` guards and why\n * `icon-context.ts` is split off from `IconProvider` too.\n *\n * Exported because the picker is not the only place a slug is checked: a form\n * built on react-hook-form or zod validates before submitting, and duplicating\n * the rule there is how the two drift apart.\n *\n * Empty passes — \"no icon chosen\" is a `required` question, not a spelling one,\n * and conflating them would make the field impossible to clear.\n *\n * @example\n * // react-hook-form\n * register(\"icon\", { validate: (value) => validateIconName(value) ?? true });\n *\n * @example\n * // zod\n * z.string().refine((value) => !validateIconName(value), { message: \"Ícone inexistente\" });\n *\n * @param value - The slug to check, in any spelling the picker accepts.\n * @param message - Overrides the default message.\n * @returns The message when the slug does not exist, `undefined` when it is fine.\n */\nexport function validateIconName(value: string, message?: string): string | undefined {\n    if (value.trim() === \"\") return undefined;\n    return isIconName(normalizeIconName(value))\n        ? undefined\n        : (message ?? DEFAULT_ICON_PICKER_MESSAGE);\n}\n"],"mappings":"6EAIA,IAAa,EACT,2DA6BJ,SAAgB,EAAiB,EAAe,EAAsC,CAC9E,KAAM,KAAK,IAAM,GACrB,OAAO,EAAA,WAAW,EAAA,kBAAkB,CAAK,CAAC,EACpC,IAAA,GACC,GAAA,0DACX"}

package/dist/icons/validate-icon-name.js

@@ -0,0 +1,11 @@
+import { normalizeIconName as e } from "./normalize-icon-name.js";
+import { isIconName as t } from "./is-icon-name.js";
+//#region src/icons/validate-icon-name.ts
+var n = "Ícone inexistente. Use um slug do lucide, em kebab-case.";
+function r(n, r) {
+	if (n.trim() !== "") return t(e(n)) ? void 0 : r ?? "Ícone inexistente. Use um slug do lucide, em kebab-case.";
+}
+//#endregion
+export { n as DEFAULT_ICON_PICKER_MESSAGE, r as validateIconName };
+
+//# sourceMappingURL=validate-icon-name.js.map

package/dist/icons/validate-icon-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-icon-name.js","names":[],"sources":["../../src/icons/validate-icon-name.ts"],"sourcesContent":["import { isIconName } from \"./is-icon-name\";\nimport { normalizeIconName } from \"./normalize-icon-name\";\n\n/** The default message for a slug lucide does not ship. */\nexport const DEFAULT_ICON_PICKER_MESSAGE =\n    \"Ícone inexistente. Use um slug do lucide, em kebab-case.\";\n\n/**\n * Validate an icon slug the way `IconPicker` does.\n *\n * Its own module rather than living next to the component: a file that exports\n * both a component and other values breaks Fast Refresh in a consuming dev\n * server, which is what `react-refresh/only-export-components` guards and why\n * `icon-context.ts` is split off from `IconProvider` too.\n *\n * Exported because the picker is not the only place a slug is checked: a form\n * built on react-hook-form or zod validates before submitting, and duplicating\n * the rule there is how the two drift apart.\n *\n * Empty passes — \"no icon chosen\" is a `required` question, not a spelling one,\n * and conflating them would make the field impossible to clear.\n *\n * @example\n * // react-hook-form\n * register(\"icon\", { validate: (value) => validateIconName(value) ?? true });\n *\n * @example\n * // zod\n * z.string().refine((value) => !validateIconName(value), { message: \"Ícone inexistente\" });\n *\n * @param value - The slug to check, in any spelling the picker accepts.\n * @param message - Overrides the default message.\n * @returns The message when the slug does not exist, `undefined` when it is fine.\n */\nexport function validateIconName(value: string, message?: string): string | undefined {\n    if (value.trim() === \"\") return undefined;\n    return isIconName(normalizeIconName(value))\n        ? undefined\n        : (message ?? DEFAULT_ICON_PICKER_MESSAGE);\n}\n"],"mappings":";;;AAIA,IAAa,IACT;AA6BJ,SAAgB,EAAiB,GAAe,GAAsC;CAC9E,MAAM,KAAK,MAAM,IACrB,OAAO,EAAW,EAAkB,CAAK,CAAC,IACpC,KAAA,IACC,KAAA;AACX"}

package/dist/icons-virtual-id.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Types for the legacy `virtual:tempest-icons` module id.
+ *
+ * Kept for apps that already import that spelling. New code should import
+ * `tempest-react-sdk/icons/virtual` instead, which is a real module in the
+ * package: it needs no ambient declaration, and it resolves outside a Vite build
+ * with the plugin — to an empty registry — rather than failing to resolve at all.
+ *
+ * Reaching this declaration takes no setup: `dist/icons.d.ts` and
+ * `dist/icons-virtual.d.ts` both reference it, so importing anything from
+ * `tempest-react-sdk/icons` is enough.
+ */
+declare module "virtual:tempest-icons" {
+    import type { LucideIcon } from "lucide-react";
+
+    /**
+     * Every icon slug found as a literal in the scanned source, mapped to the
+     * statically imported lucide component.
+     *
+     * Pass it to `IconProvider`'s `registry` prop. Slugs resolved from here cost
+     * no extra request — they are ordinary imports the bundler tree-shakes.
+     */
+    export const staticIcons: Record<string, LucideIcon>;
+}

package/dist/icons-virtual.cjs

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e={};exports.staticIcons=e;
+//# sourceMappingURL=icons-virtual.cjs.map

package/dist/icons-virtual.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"icons-virtual.cjs","names":[],"sources":["../src/icons/virtual.ts"],"sourcesContent":["import type { IconRegistry } from \"./icon-context\";\n\n/**\n * The static icon registry, empty until a build plugin fills it in.\n *\n * `tempestIcons()` resolves this module id to the table it generated from the\n * slugs your source mentions. Every other runner — vitest without the plugin,\n * `tsx`, a Storybook builder, a Node script that imports a component — gets this\n * stub, so the import always resolves and `<Icon>` falls back to fetching shards.\n *\n * That fallback is why the stub exists: before it, an app that imported the\n * registry could not be loaded outside a Vite build with the plugin installed,\n * and the failure was the whole module graph refusing to resolve rather than one\n * icon going missing.\n *\n * @example\n * import { IconProvider } from \"tempest-react-sdk/icons\";\n * import { staticIcons } from \"tempest-react-sdk/icons/virtual\";\n *\n * <IconProvider registry={staticIcons}>\n *     <App />\n * </IconProvider>\n */\nexport const staticIcons: IconRegistry = {};\n"],"mappings":"mEAuBA,IAAa,EAA4B,CAAC"}

package/dist/icons-virtual.d.ts

@@ -1,22 +1,30 @@
-/**
- * Types for the module the `tempestIcons()` Vite plugin generates.
- *
- * Reference it once from an app's `vite-env.d.ts` (or any ambient `.d.ts`):
- *
- *     /// <reference types="tempest-react-sdk/icons/virtual" />
- *
- * Without it, `import { staticIcons } from "virtual:tempest-icons"` is an
- * unresolved module to `tsc`, even though Vite resolves it at build time.
- */
-declare module "virtual:tempest-icons" {
-    import type { LucideIcon } from "lucide-react";
-
-    /**
-     * Every icon slug found as a literal in the scanned source, mapped to the
-     * statically imported lucide component.
-     *
-     * Pass it to `IconProvider`'s `registry` prop. Slugs resolved from here cost
-     * no extra request — they are ordinary imports the bundler tree-shakes.
-     */
-    export const staticIcons: Record<string, LucideIcon>;
-}
+/// <reference path="./icons-virtual-id.d.ts" />
+import { LucideIcon } from 'lucide-react';
+
+/** A slug → icon-component table, as produced by `createIconRegistry`. */
+declare type IconRegistry = Readonly<Record<string, LucideIcon>>;
+
+/**
+ * The static icon registry, empty until a build plugin fills it in.
+ *
+ * `tempestIcons()` resolves this module id to the table it generated from the
+ * slugs your source mentions. Every other runner — vitest without the plugin,
+ * `tsx`, a Storybook builder, a Node script that imports a component — gets this
+ * stub, so the import always resolves and `<Icon>` falls back to fetching shards.
+ *
+ * That fallback is why the stub exists: before it, an app that imported the
+ * registry could not be loaded outside a Vite build with the plugin installed,
+ * and the failure was the whole module graph refusing to resolve rather than one
+ * icon going missing.
+ *
+ * @example
+ * import { IconProvider } from "tempest-react-sdk/icons";
+ * import { staticIcons } from "tempest-react-sdk/icons/virtual";
+ *
+ * <IconProvider registry={staticIcons}>
+ *     <App />
+ * </IconProvider>
+ */
+export declare const staticIcons: IconRegistry;
+
+export { }

package/dist/icons-virtual.js

@@ -0,0 +1,6 @@
+//#region src/icons/virtual.ts
+var e = {};
+//#endregion
+export { e as staticIcons };
+
+//# sourceMappingURL=icons-virtual.js.map

package/dist/icons-virtual.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"icons-virtual.js","names":[],"sources":["../src/icons/virtual.ts"],"sourcesContent":["import type { IconRegistry } from \"./icon-context\";\n\n/**\n * The static icon registry, empty until a build plugin fills it in.\n *\n * `tempestIcons()` resolves this module id to the table it generated from the\n * slugs your source mentions. Every other runner — vitest without the plugin,\n * `tsx`, a Storybook builder, a Node script that imports a component — gets this\n * stub, so the import always resolves and `<Icon>` falls back to fetching shards.\n *\n * That fallback is why the stub exists: before it, an app that imported the\n * registry could not be loaded outside a Vite build with the plugin installed,\n * and the failure was the whole module graph refusing to resolve rather than one\n * icon going missing.\n *\n * @example\n * import { IconProvider } from \"tempest-react-sdk/icons\";\n * import { staticIcons } from \"tempest-react-sdk/icons/virtual\";\n *\n * <IconProvider registry={staticIcons}>\n *     <App />\n * </IconProvider>\n */\nexport const staticIcons: IconRegistry = {};\n"],"mappings":";AAuBA,IAAa,IAA4B,CAAC"}

package/dist/icons.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./icons/generated/aliases.cjs"),t=require("./icons/generated/icon-names.cjs"),n=require("./icons/icon-context.cjs"),r=require("./icons/shard-cache.cjs"),i=require("./icons/use-icon.cjs"),a=require("./icons/Icon.cjs"),o=require("./icons/IconProvider.cjs"),s=require("./icons/is-icon-name.cjs"),c=require("./icons/material-symbols.cjs");exports.Icon=a.Icon,exports.IconProvider=o.IconProvider,exports.MATERIAL_SYMBOL_FALLBACK=c.MATERIAL_SYMBOL_FALLBACK,exports.createIconRegistry=n.createIconRegistry,exports.fromMaterialSymbol=c.fromMaterialSymbol,exports.iconAliases=e.iconAliases,exports.iconNames=t.iconNames,exports.iconStatus=r.iconStatus,exports.isIconName=s.isIconName,exports.loadIcon=r.loadIcon,exports.materialToLucide=c.materialToLucide,exports.peekIcon=r.peekIcon,exports.preloadIcons=r.preloadIcons,exports.resolveIconAlias=r.resolveIconAlias,exports.useIcon=i.useIcon;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./icons/generated/aliases.cjs"),t=require("./icons/generated/icon-names.cjs"),n=require("./icons/icon-context.cjs"),r=require("./icons/alias.cjs"),i=require("./icons/normalize-icon-name.cjs"),a=require("./icons/shard-cache.cjs"),o=require("./icons/use-icon.cjs"),s=require("./icons/Icon.cjs"),c=require("./icons/is-icon-name.cjs"),l=require("./icons/validate-icon-name.cjs"),u=require("./icons/IconPicker.cjs"),d=require("./icons/IconProvider.cjs"),f=require("./icons/material-symbols.cjs");exports.DEFAULT_ICON_PICKER_MESSAGE=l.DEFAULT_ICON_PICKER_MESSAGE,exports.Icon=s.Icon,exports.IconPicker=u.IconPicker,exports.IconProvider=d.IconProvider,exports.MATERIAL_SYMBOL_FALLBACK=f.MATERIAL_SYMBOL_FALLBACK,exports.createIconRegistry=n.createIconRegistry,exports.fromMaterialSymbol=f.fromMaterialSymbol,exports.iconAliases=e.iconAliases,exports.iconNames=t.iconNames,exports.iconStatus=a.iconStatus,exports.isIconName=c.isIconName,exports.loadIcon=a.loadIcon,exports.materialToLucide=f.materialToLucide,exports.normalizeIconName=i.normalizeIconName,exports.peekIcon=a.peekIcon,exports.preloadIcons=a.preloadIcons,exports.registerIcons=a.registerIcons,exports.resolveIconAlias=r.resolveIconAlias,exports.subscribeToIconErrors=a.subscribeToIconErrors,exports.useIcon=o.useIcon,exports.validateIconName=l.validateIconName;

package/dist/icons.d.ts

@@ -1,3 +1,5 @@
+/// <reference path="./icons-virtual-id.d.ts" />
+import { InputHTMLAttributes } from 'react';
 import { LucideIcon } from 'lucide-react';
 import { ReactNode } from 'react';
 import { SVGProps } from 'react';
@@ -20,6 +22,9 @@ import { SVGProps } from 'react';
  */
 export declare function createIconRegistry(icons: Record<string, LucideIcon>): IconRegistry;
 
+/** The default message for a slug lucide does not ship. */
+export declare const DEFAULT_ICON_PICKER_MESSAGE = "\u00CDcone inexistente. Use um slug do lucide, em kebab-case.";
+
 /**
  * Translate a Material Symbols code into a lucide slug, always returning one.
  *
@@ -56,11 +61,16 @@ export declare function fromMaterialSymbol(code: string | null | undefined, fall
  * An unknown slug renders `fallback` (nothing, by default) and warns in dev only
  * — it never throws, because a bad name from an API must not take down the tree.
  *
+ * `name` is normalized before the lookup, so a stored `icon_code` renders whether
+ * it was written `shopping_cart`, `" Save"` or under a slug lucide has since
+ * deprecated. Pass `normalize={false}` for a strict lookup.
+ *
  * @example
  * <Icon name="save" size={18} />
  * <Icon name={row.iconSlug} fallback={<span className="skeleton" />} />
+ * <Icon icon={Wrench} size={18} />
  */
-export declare function Icon({ name, size, strokeWidth, fallback, ...rest }: IconProps): ReactNode;
+export declare function Icon({ name, icon, size, strokeWidth, fallback, normalize, ...rest }: IconProps): ReactNode;
 
 /**
  * Lucide's 257 deprecated slugs, mapped to the canonical slug that
@@ -72,6 +82,72 @@ export declare function Icon({ name, size, strokeWidth, fallback, ...rest }: Ico
  */
 export declare const iconAliases: Record<string, string>;
 
+declare interface IconBaseProps extends Omit<SVGProps<SVGSVGElement>, "ref" | "name"> {
+    /** Width and height in px. Defaults to the provider's value, then lucide's `24`. */
+    size?: number | string;
+    /** Stroke width. Defaults to the provider's value, then lucide's `2`. */
+    strokeWidth?: number;
+    /**
+     * Rendered while the icon's shard is in flight, and for a slug that does not
+     * exist at all. Defaults to nothing.
+     *
+     * Pass a same-sized placeholder when the surrounding layout would otherwise
+     * shift. Note that a slug already in the registry or the cache never renders
+     * this — it resolves during render.
+     */
+    fallback?: ReactNode;
+    /**
+     * Clean up `name` before looking it up. Default `true`.
+     *
+     * A stored `icon_code` arrives dirty — `shopping_cart`, `" Save"`, a slug
+     * lucide deprecated two releases ago — and normalizing is what makes those
+     * render instead of falling back. `false` asks for a strict lookup, for the
+     * case where you want an unexpected spelling to be visible rather than
+     * quietly repaired.
+     *
+     * Ignored when the icon is passed as a component.
+     */
+    normalize?: boolean;
+}
+
+/**
+ * Address the icon by component, for a call site that already imported it.
+ *
+ * No lookup, no registry, no shard: the component is rendered as passed. It is
+ * there so a screen mixing literal icons with data-driven ones can keep using one
+ * component instead of alternating between `<Icon name>` and `<Wrench />`, which
+ * is what makes the shared `size`/`strokeWidth` defaults apply to both.
+ */
+declare interface IconByComponentProps extends IconBaseProps {
+    icon: LucideIcon;
+    name?: never;
+}
+
+/**
+ * Address the icon by slug — the reason this component exists.
+ *
+ * The slug is typed as the union of every name lucide ships, so a typo is a
+ * compile error, while still accepting a plain `string` for the case that
+ * motivates the whole module: a name arriving from an API, a CMS or a config
+ * table.
+ */
+declare interface IconByNameProps extends IconBaseProps {
+    name: IconName | (string & {});
+    icon?: never;
+}
+
+/** What a shard failure reports to whoever subscribed. */
+export declare interface IconLoadError {
+    /** The shard key whose chunk could not be fetched. */
+    shard: string;
+    /** The slug whose render asked for it. */
+    slug: string;
+    /** Attempts made before giving up, retries included. */
+    attempts: number;
+    /** The last rejection from the dynamic import. */
+    error: unknown;
+}
+
 /**
  * Every icon slug lucide ships, as a union of string literals.
  *
@@ -89,30 +165,68 @@ export declare type IconName = "a-arrow-down" | "a-arrow-up" | "a-large-small" |
  */
 export declare const iconNames: readonly IconName[];
 
-export declare interface IconProps extends Omit<SVGProps<SVGSVGElement>, "ref"> {
+/**
+ * An icon field: native autocomplete over every lucide slug, plus a preview.
+ *
+ * Every panel that lets someone choose an icon was rewriting this — filter the
+ * list, cap the suggestions, build the `<datalist>`, and block submit when the
+ * typed name does not exist. That last step is the one that matters: without it
+ * an invalid value reaches the database and only shows up later as a missing icon
+ * on every screen that renders the record.
+ *
+ * Validation is wired to the **native** form: the input carries a custom validity
+ * message, so a plain `<form>` refuses to submit and the browser points at the
+ * field. `validateIconName` is exported for react-hook-form and zod.
+ *
+ * Built on `<datalist>` rather than a custom listbox on purpose: keyboard,
+ * screen-reader and mobile behaviour come from the platform, and the component
+ * stays small enough that its cost is the slug list it has to import — ~7 KB
+ * brotli, which only a picker pays.
+ *
+ * @example
+ * const [icon, setIcon] = useState("");
+ *
+ * <form onSubmit={save}>
+ *     <IconPicker value={icon} onChange={setIcon} required />
+ *     <button type="submit">Salvar</button>
+ * </form>
+ */
+export declare function IconPicker({ value, onChange, limit, previewSize, invalidMessage, emptyPreview, className, ...rest }: IconPickerProps): ReactNode;
+
+/**
+ * @tempest-limits props-count — value/onChange are the field, limit/placeholder
+ * the suggestion list, and previewSize/invalidMessage the two things a form
+ * around it needs to restyle or translate.
+ */
+export declare interface IconPickerProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "value" | "onChange" | "list" | "type"> {
+    /** The chosen slug. Always canonical — see `onChange`. */
+    value: string;
     /**
-     * The lucide slug, kebab-case: `"save"`, `"trash-2"`, `"circle-alert"`.
+     * Fires with the **canonical** slug on every keystroke.
      *
-     * Typed as the union of every slug lucide ships, so a typo is a compile
-     * error — while still accepting a plain `string` for the case this component
-     * exists for: a name that arrives from an API, a CMS or a config table.
+     * Legacy spellings are normalized on the way out (`Shopping_Cart` →
+     * `shopping-cart`, `alert-circle` → `circle-alert`), so what a form stores is
+     * what `<Icon>` resolves without further cleanup.
      */
-    name: IconName | (string & {});
-    /** Width and height in px. Defaults to the provider's value, then lucide's `24`. */
-    size?: number | string;
-    /** Stroke width. Defaults to the provider's value, then lucide's `2`. */
-    strokeWidth?: number;
+    onChange: (slug: string) => void;
     /**
-     * Rendered while the icon's shard is in flight, and for a slug that does not
-     * exist at all. Defaults to nothing.
+     * How many suggestions to render. Default `40`.
      *
-     * Pass a same-sized placeholder when the surrounding layout would otherwise
-     * shift. Note that a slug already in the registry or the cache never renders
-     * this — it resolves during render.
+     * There are 2024 slugs, and building every one as an `<option>` on each
+     * keystroke freezes the datalist — which is the reason this prop exists rather
+     * than a "show everything" default.
      */
-    fallback?: ReactNode;
+    limit?: number;
+    /** Size of the preview glyph, in px. Default `20`. */
+    previewSize?: number;
+    /** Overrides the message shown for a slug that does not exist. */
+    invalidMessage?: string;
+    /** Rendered in the preview box while nothing valid is chosen. */
+    emptyPreview?: ReactNode;
 }
 
+export declare type IconProps = IconByNameProps | IconByComponentProps;
+
 /**
  * Provide a static icon registry and shared `<Icon>` defaults to a subtree.
  *
@@ -151,16 +265,18 @@ export declare interface IconProviderProps {
 export declare type IconRegistry = Readonly<Record<string, LucideIcon>>;
 
 /**
- * Whether a slug is ready, still loading, or not an icon at all.
+ * Whether a slug is ready, loading, unknown, or unreachable.
  *
  * `"missing"` is only reported once that is actually knowable: either lucide has
- * no icons under that initial letter, or the letter's shard already settled
- * without the slug in it.
+ * no icons under that initial letter, or the letter's shard **arrived** without
+ * the slug in it. A shard that failed to load reports `"error"` instead — the two
+ * used to collapse into `"missing"`, which turned a stale deploy into what looked
+ * like a typo and made `Icon` warn about a name that is perfectly valid.
  *
  * @param slug - Any icon slug, canonical or deprecated.
  * @returns The slug's resolution state.
  */
-export declare function iconStatus(slug: string): "ready" | "loading" | "missing";
+export declare function iconStatus(slug: string): "ready" | "loading" | "missing" | "error";
 
 /**
  * Narrow an arbitrary string to a known icon slug.
@@ -216,28 +332,77 @@ export declare const MATERIAL_SYMBOL_FALLBACK: IconName;
  * empty screen: a handful of codes collide by accident, so roughly one row in
  * ten draws the right icon and the bug reads as "some icons went missing".
  *
- * **This is a seed table, not the full vocabulary.** Material Symbols ships
- * ~3600 names and almost none of them will ever appear in an `icon_code` of
- * ours. It grows on demand, one hand-written pair at a time — a map generated by
- * name heuristics gets it badly wrong, starting with `build`, which is a wrench
- * in Material Symbols and not anything to do with construction.
- *
- * **Approximations, deliberate and not one-to-one:**
+ * **Still not the full vocabulary.** Material Symbols publishes ~6100 names and
+ * almost none of them will ever appear in an `icon_code` of ours, so this grows
+ * on demand, one hand-written pair at a time — a map generated by name
+ * heuristics gets it badly wrong, starting with `build`, which is a wrench in
+ * Material Symbols and nothing to do with construction.
+ *
+ * **How the codes were chosen.** Two lots, merged. The first was the trades seed
+ * the bridge started as. The second is the head of Material Symbols' own
+ * published popularity ranking (`fonts.google.com/metadata/icons`), which is
+ * measured usage rather than a guess at which names a seed will contain — every
+ * key was checked to exist in that vocabulary before landing.
+ *
+ * **Where the two lots disagreed**, six keys, the tie went to whichever mapping
+ * keeps two distinct Material Symbols names distinct in lucide: `error` →
+ * `circle-alert` because `cancel` already owns `circle-x`; `payments` →
+ * `banknote` because `account_balance_wallet` already owns `wallet`;
+ * `receipt_long` → `receipt-text` because `receipt` already owns `receipt`;
+ * `construction` → itself because `engineering` already owns `hard-hat`; and
+ * `today` → `calendar` with `event` → `calendar-days`, splitting the generic
+ * calendar names from the dated one.
+ *
+ * Every target is checked mechanically against the slug list by
+ * `material-symbols.test.ts`, so a pair pointing at a name lucide does not ship
+ * — or at one it has since deprecated — fails the suite instead of reaching a
+ * grid. What no test can check is whether the *chosen* icon is the right
+ * metaphor, which is why pairs go in by hand.
+ *
+ * **Approximations, deliberate and not one-to-one** (the full list lives in
+ * `docs/icons.md`):
  *
  * - `plumbing` → `shower-head`, because lucide has no pipe.
  * - `build`, `handyman` and `hardware` all land on `wrench` — Material Symbols
  *   distinguishes the tools, lucide does not.
  * - `pedal_bike`, `two_wheeler` and `delivery_dining` all land on `bike`.
+ * - `dentistry` → `face-slightly-smiling`, since lucide ships no tooth.
+ * - `iron` → `shirt` and `cleaning_services` → `spray-can`: the activity, not
+ *   the implement.
+ * - `roofing` → `house`, the same glyph as `home`, because lucide has no roof.
  *
- * The thirteen identity pairs are here on purpose. Their names happen to match
- * in both vocabularies, so they already render today — leaving them out would
- * send them to {@link MATERIAL_SYMBOL_FALLBACK} and make this bridge a
- * regression for exactly the codes that used to work.
+ * The identity pairs are here on purpose. Their names happen to match in both
+ * vocabularies, so they already render today — leaving them out would send them
+ * to {@link MATERIAL_SYMBOL_FALLBACK} and make this bridge a regression for
+ * exactly the codes that used to work.
  *
  * @see fromMaterialSymbol — the lookup you normally call.
  */
 export declare const materialToLucide: Readonly<Record<string, IconName>>;
 
+/**
+ * Clean up an icon code and resolve it to the slug lucide actually ships.
+ *
+ * Every backend that stores an `icon_code` stores it dirty: `snake_case` left over
+ * from an old form, a capital or a stray space from a hand-typed value, and slugs
+ * lucide has since deprecated. Each app was writing the same three-step cleanup
+ * before rendering — trim, lower-case, `_` → `-`, then `resolveIconAlias` — which
+ * is code that should not exist outside the SDK.
+ *
+ * Note that this does **not** check whether the result is a real icon: the point is
+ * to produce the canonical spelling, and deciding what to do with an unknown name
+ * belongs to the caller. Pair it with `isIconName` when you need that answer, or
+ * let `<Icon>` render its `fallback`.
+ *
+ * @example
+ * normalizeIconName("  Alert_Circle ");  // "circle-alert"
+ * normalizeIconName("shopping_cart");    // "shopping-cart"
+ *
+ * @param code - Any stored icon code.
+ * @returns The canonical, lucide-spelled slug.
+ */
+export declare function normalizeIconName(code: string): string;
+
 /**
  * Read an icon out of the cache without triggering a fetch.
  *
@@ -257,18 +422,73 @@ export declare function peekIcon(slug: string): LucideIcon | undefined;
  */
 export declare function preloadIcons(slugs: readonly string[]): Promise<void>;
 
+/**
+ * Make icon components resolvable by slug, with no provider and no plugin.
+ *
+ * Call it once from an entrypoint. The icons land in the same table a fetched
+ * shard fills, so every `<Icon>` below — including one that renders before the
+ * call, since registering notifies subscribers — resolves them synchronously and
+ * never issues a request.
+ *
+ * This is the whole setup for a closed catalog: an admin panel with twenty known
+ * icons pays two lines instead of a build plugin plus a provider. `IconProvider`
+ * stays for what is genuinely tree-scoped — the `size`/`strokeWidth` defaults and
+ * a registry that must override the global one for one subtree.
+ *
+ * A slug lucide does not ship is registered as-is, which is how an app adds its
+ * own artwork to the same `<Icon name>` call site.
+ *
+ * @example
+ * import { registerIcons } from "tempest-react-sdk/icons";
+ * import { Save, Trash2 } from "lucide-react";
+ *
+ * registerIcons({ save: Save, "trash-2": Trash2 });
+ *
+ * @param icons - Slug → icon component. Deprecated slugs are stored under the
+ *   canonical name, so both spellings resolve.
+ */
+export declare function registerIcons(icons: Readonly<Record<string, LucideIcon>>): void;
+
 /**
  * Map a slug to the canonical slug that owns the icon.
  *
  * Lucide keeps 257 deprecated aliases (`alert-circle` → `circle-alert`), and a
  * slug persisted in a database years ago is exactly the case this feature exists
- * for, so an alias must keep resolving after a lucide bump renames it.
+ * for, so an alias must keep resolving after a lucide bump renames it. Resolution
+ * happens before the shard lookup, since only canonical slugs are sharded.
+ *
+ * Its own module, not part of `shard-cache`: everything that merely *names* an
+ * icon needs this — `normalizeIconName`, `validateIconName`, a form checking a
+ * value before submit — and none of that needs the shard loader index. Sharing a
+ * module made a validator that never renders anything drag in all 45 shard
+ * modules.
  *
  * @param slug - Any icon slug, canonical or deprecated.
  * @returns The canonical slug.
  */
 export declare function resolveIconAlias(slug: string): string;
 
+/**
+ * Subscribe to shard fetches that gave up.
+ *
+ * The failure is routine in a long-lived tab: a deploy rotates hashed chunk
+ * names, the old asset leaves the CDN, and the next icon that needs it 404s. That
+ * used to end in a permanent fallback with no signal — nothing for the user,
+ * nothing for observability. Subscribing is what turns it into both.
+ *
+ * @example
+ * import { subscribeToIconErrors } from "tempest-react-sdk/icons";
+ *
+ * subscribeToIconErrors(({ shard, error }) => {
+ *     Sentry.captureException(error, { tags: { iconShard: shard } });
+ *     promptReloadForStaleChunks();
+ * });
+ *
+ * @param listener - Called once per shard that gave up.
+ * @returns An unsubscribe function.
+ */
+export declare function subscribeToIconErrors(listener: (detail: IconLoadError) => void): () => void;
+
 /**
  * Resolve an icon slug to its component.
  *
@@ -286,4 +506,33 @@ export declare function resolveIconAlias(slug: string): string;
  */
 export declare function useIcon(slug: string | undefined): LucideIcon | undefined;
 
+/**
+ * Validate an icon slug the way `IconPicker` does.
+ *
+ * Its own module rather than living next to the component: a file that exports
+ * both a component and other values breaks Fast Refresh in a consuming dev
+ * server, which is what `react-refresh/only-export-components` guards and why
+ * `icon-context.ts` is split off from `IconProvider` too.
+ *
+ * Exported because the picker is not the only place a slug is checked: a form
+ * built on react-hook-form or zod validates before submitting, and duplicating
+ * the rule there is how the two drift apart.
+ *
+ * Empty passes — "no icon chosen" is a `required` question, not a spelling one,
+ * and conflating them would make the field impossible to clear.
+ *
+ * @example
+ * // react-hook-form
+ * register("icon", { validate: (value) => validateIconName(value) ?? true });
+ *
+ * @example
+ * // zod
+ * z.string().refine((value) => !validateIconName(value), { message: "Ícone inexistente" });
+ *
+ * @param value - The slug to check, in any spelling the picker accepts.
+ * @param message - Overrides the default message.
+ * @returns The message when the slug does not exist, `undefined` when it is fine.
+ */
+export declare function validateIconName(value: string, message?: string): string | undefined;
+
 export { }

package/dist/icons.js

@@ -1,10 +1,14 @@
 import { iconAliases as e } from "./icons/generated/aliases.js";
 import { iconNames as t } from "./icons/generated/icon-names.js";
 import { createIconRegistry as n } from "./icons/icon-context.js";
-import { iconStatus as r, loadIcon as i, peekIcon as a, preloadIcons as o, resolveIconAlias as s } from "./icons/shard-cache.js";
-import { useIcon as c } from "./icons/use-icon.js";
-import { Icon as l } from "./icons/Icon.js";
-import { IconProvider as u } from "./icons/IconProvider.js";
-import { isIconName as d } from "./icons/is-icon-name.js";
-import { MATERIAL_SYMBOL_FALLBACK as f, fromMaterialSymbol as p, materialToLucide as m } from "./icons/material-symbols.js";
-export { l as Icon, u as IconProvider, f as MATERIAL_SYMBOL_FALLBACK, n as createIconRegistry, p as fromMaterialSymbol, e as iconAliases, t as iconNames, r as iconStatus, d as isIconName, i as loadIcon, m as materialToLucide, a as peekIcon, o as preloadIcons, s as resolveIconAlias, c as useIcon };
+import { resolveIconAlias as r } from "./icons/alias.js";
+import { normalizeIconName as i } from "./icons/normalize-icon-name.js";
+import { iconStatus as a, loadIcon as o, peekIcon as s, preloadIcons as c, registerIcons as l, subscribeToIconErrors as u } from "./icons/shard-cache.js";
+import { useIcon as d } from "./icons/use-icon.js";
+import { Icon as f } from "./icons/Icon.js";
+import { isIconName as p } from "./icons/is-icon-name.js";
+import { DEFAULT_ICON_PICKER_MESSAGE as m, validateIconName as h } from "./icons/validate-icon-name.js";
+import { IconPicker as g } from "./icons/IconPicker.js";
+import { IconProvider as _ } from "./icons/IconProvider.js";
+import { MATERIAL_SYMBOL_FALLBACK as v, fromMaterialSymbol as y, materialToLucide as b } from "./icons/material-symbols.js";
+export { m as DEFAULT_ICON_PICKER_MESSAGE, f as Icon, g as IconPicker, _ as IconProvider, v as MATERIAL_SYMBOL_FALLBACK, n as createIconRegistry, y as fromMaterialSymbol, e as iconAliases, t as iconNames, a as iconStatus, p as isIconName, o as loadIcon, b as materialToLucide, i as normalizeIconName, s as peekIcon, c as preloadIcons, l as registerIcons, r as resolveIconAlias, u as subscribeToIconErrors, d as useIcon, h as validateIconName };