@mvriu5/payload-icon-picker 1.0.1 → 1.0.2

package/README.md

@@ -80,6 +80,14 @@ lucide:ArrowRight
 
 You can still use `resolveIcon` if you need a custom final storage format.
 
+### About `resolveIcon`
+
+When using `payloadIconPlugin()`, `resolveIcon` runs during Payload config setup. The resolved string is passed to the admin field as each icon's final `value`.
+
+That means normal `iconField()` usage does not require passing `resolveIcon` to the admin component manually.
+
+The `resolveIcon` prop on `IconRenderer`, `IconField`, and `createIconResolver()` is primarily for direct component usage, tests, or advanced cases where you bypass `payloadIconPlugin()`. If you use a custom `resolveIcon` for stored values, pass the same resolver when rendering or resolving those values outside the Payload admin UI.
+
 ## Rendering Stored Icons
 
 Use `IconRenderer` from the client export to render a stored icon string in your frontend.
@@ -174,6 +182,8 @@ payloadIconPlugin({
 
 Adapters support `prefix`, `include`, `exclude`, and optional label/value formatters:
 
+When registering icons from more than one library, use a unique `prefix` for every adapter. Many icon libraries export generic names such as `Home`, `Search`, or `User`; prefixes keep stored values unique and make it clear which library an icon came from.
+
 ```ts
 import * as SimpleIcons from "@icons-pack/react-simple-icons"
 import * as TablerIcons from "@tabler/icons-react"
@@ -195,6 +205,8 @@ payloadIconPlugin({
 
 With `prefix`, the adapter keeps `name` as the original library export name and sets `value` to `prefix:name`, for example `tabler:IconHome`.
 
+Without prefixes, duplicate icon values can collide. In development, the plugin warns when multiple registered icons resolve to the same stored value.
+
 Or pass explicit icon metadata:
 
 ```ts
@@ -213,7 +225,7 @@ payloadIconPlugin({
 
 ## Field Options
 
-`iconField()` accepts normal single-value Payload text field options, plus picker labels:
+`iconField()` accepts normal single-value Payload text field options, plus picker labels and per-field icon filters:
 
 ```ts
 iconField({
@@ -228,6 +240,36 @@ iconField({
 })
 ```
 
+Use `libraries` to limit a field to icons from selected adapter prefixes:
+
+```ts
+iconField({
+    name: "navigationIcon",
+    label: "Navigation Icon",
+    libraries: ["lucide"],
+})
+```
+
+Use `icons` to allow only specific stored icon values:
+
+```ts
+iconField({
+    name: "socialIcon",
+    label: "Social Icon",
+    icons: ["si:SiGithub", "si:SiDiscord"],
+})
+```
+
+You can combine both options. The filters are additive, so this example allows all Lucide icons plus the explicit GitHub icon:
+
+```ts
+iconField({
+    name: "featuredIcon",
+    libraries: ["lucide"],
+    icons: ["si:SiGithub"],
+})
+```
+
 ## Development
 
 The dev Payload config in `dev/payload.config.ts` registers the plugin with `lucide-react`, which is installed as a development dependency.

package/dist/adapters/phosphor.d.ts

@@ -1,7 +1,8 @@
 import type { IconFieldIcon } from "../utils.js";
 import type { IconAdapterOptions, IconLibrary } from "./utils.js";
-export type PhosphorIconWeight = "bold" | "duotone" | "fill" | "light" | "regular" | "thin";
+type PhosphorIconWeight = "bold" | "duotone" | "fill" | "light" | "regular" | "thin";
 export type PhosphorIconAdapterOptions = Omit<IconAdapterOptions, "weight"> & {
     weight?: PhosphorIconWeight;
 };
 export declare const phosphorIconAdapter: (icons: IconLibrary, options?: PhosphorIconAdapterOptions) => IconFieldIcon[];
+export {};

package/dist/adapters/utils.d.ts

@@ -1,5 +1,4 @@
 import type { IconFieldIcon } from "../utils.js";
-export type IconNode = Array<[string, Record<string, unknown>]>;
 export type IconAdapterOptions = {
     exclude?: string[];
     include?: string[];
@@ -11,14 +10,15 @@ export type IconAdapterOptions = {
     weight?: string;
 };
 export type IconLibrary = Record<string, unknown>;
-export type IconAdapterLabelArgs = {
+type IconAdapterLabelArgs = {
     defaultLabel: string;
     name: string;
     prefix?: string;
     value: string;
 };
-export type IconAdapterValueArgs = {
+type IconAdapterValueArgs = {
     name: string;
     prefix?: string;
 };
 export declare const createSvgIconAdapter: (icons: IconLibrary, options?: IconAdapterOptions) => IconFieldIcon[];
+export {};

package/dist/components/IconDialog.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import React, { useEffect, useMemo, useState } from "react";
+import React, { useEffect, useId, useMemo, useRef, useState } from "react";
 import { VirtuosoGrid } from "react-virtuoso";
 import "./IconDialog.css";
 import { sanitizeSvg } from "../sanitizeSvg.js";
@@ -8,6 +8,11 @@ import { getIconLabelParts, getIconLibrary } from "../utils.js";
 const SEARCH_DEBOUNCE_MS = 150;
 const ALL_LIBRARY_FILTER = "__all";
 export const IconDialog = ({ icons, isDisabled, noResultsLabel, onClear, onClose, onSelect, placeholder, resolveIcon, value })=>{
+    const dialogTitleId = useId();
+    const dialogDescriptionId = useId();
+    const dialogRef = useRef(null);
+    const searchInputRef = useRef(null);
+    const previouslyFocusedElementRef = useRef(null);
     const [query, setQuery] = useState("");
     const [activeLibrary, setActiveLibrary] = useState(ALL_LIBRARY_FILTER);
     const debouncedQuery = useDebouncedValue(query, SEARCH_DEBOUNCE_MS);
@@ -37,11 +42,42 @@ export const IconDialog = ({ icons, isDisabled, noResultsLabel, onClear, onClose
         icons,
         resolveIcon
     ]);
+    useEffect(()=>{
+        previouslyFocusedElementRef.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+        searchInputRef.current?.focus();
+        return ()=>{
+            previouslyFocusedElementRef.current?.focus();
+        };
+    }, []);
     useEffect(()=>{
         const handleKeyDown = (event)=>{
             if (event.key === "Escape") {
                 event.preventDefault();
                 onClose();
+                return;
+            }
+            if (event.key !== "Tab") {
+                return;
+            }
+            const dialog = dialogRef.current;
+            if (!dialog) return;
+            const focusableElements = getFocusableElements(dialog);
+            if (focusableElements.length === 0) {
+                event.preventDefault();
+                dialog.focus();
+                return;
+            }
+            const firstFocusableElement = focusableElements[0];
+            const lastFocusableElement = focusableElements[focusableElements.length - 1];
+            if (!firstFocusableElement || !lastFocusableElement) return;
+            if (event.shiftKey && document.activeElement === firstFocusableElement) {
+                event.preventDefault();
+                lastFocusableElement.focus();
+                return;
+            }
+            if (!event.shiftKey && document.activeElement === lastFocusableElement) {
+                event.preventDefault();
+                firstFocusableElement.focus();
             }
         };
         window.addEventListener("keydown", handleKeyDown);
@@ -50,10 +86,14 @@ export const IconDialog = ({ icons, isDisabled, noResultsLabel, onClear, onClose
         onClose
     ]);
     return /*#__PURE__*/ _jsx("div", {
+        "aria-describedby": dialogDescriptionId,
+        "aria-labelledby": dialogTitleId,
         "aria-modal": "true",
         className: "payload-icon-picker__overlay",
         onClick: onClose,
+        ref: dialogRef,
         role: "dialog",
+        tabIndex: -1,
         children: /*#__PURE__*/ _jsxs("div", {
             className: "payload-icon-picker__dialog",
             onClick: (event)=>event.stopPropagation(),
@@ -63,21 +103,28 @@ export const IconDialog = ({ icons, isDisabled, noResultsLabel, onClear, onClose
                     children: [
                         /*#__PURE__*/ _jsx("h3", {
                             className: "payload-icon-picker__dialog-title",
+                            id: dialogTitleId,
                             children: "Select icon"
                         }),
                         /*#__PURE__*/ _jsx("button", {
+                            "aria-label": "Close icon picker",
                             onClick: onClose,
                             type: "button",
                             children: "Close"
                         })
                     ]
                 }),
+                /*#__PURE__*/ _jsx("p", {
+                    id: dialogDescriptionId,
+                    hidden: true,
+                    children: "Search, filter, and select an icon. Press Escape to close the dialog."
+                }),
                 /*#__PURE__*/ _jsx("input", {
-                    autoFocus: true,
                     "aria-label": "Search icons",
                     className: "payload-icon-picker__search",
                     onChange: (event)=>setQuery(event.target.value),
                     placeholder: placeholder,
+                    ref: searchInputRef,
                     type: "search",
                     value: query
                 }),
@@ -108,6 +155,7 @@ export const IconDialog = ({ icons, isDisabled, noResultsLabel, onClear, onClose
                         const iconValue = resolveIcon(icon);
                         const isSelected = iconValue === value;
                         return /*#__PURE__*/ _jsxs("button", {
+                            "aria-label": `Select ${icon.label ?? icon.name}`,
                             "aria-selected": isSelected,
                             className: "payload-icon-picker__option",
                             onClick: ()=>{
@@ -164,6 +212,7 @@ const LibraryFilterButton = ({ isActive, label, onClick })=>/*#__PURE__*/ _jsx("
         type: "button",
         children: label
     });
+const getFocusableElements = (element)=>Array.from(element.querySelectorAll('a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])')).filter((focusableElement)=>!focusableElement.hasAttribute("hidden") && focusableElement.getAttribute("aria-hidden") !== "true");
 const useDebouncedValue = (value, delay)=>{
     const [debouncedValue, setDebouncedValue] = useState(value);
     useEffect(()=>{

package/dist/components/IconField.d.ts

@@ -7,6 +7,10 @@ export type IconFieldProps = TextFieldClientProps & {
     icons?: IconFieldIcon[] | IconFieldIconRecord;
     noResultsLabel?: string;
     placeholder?: string;
+    /**
+     * Primarily for direct component usage. With `payloadIconPlugin()`, icon
+     * values are already resolved before they reach this component.
+     */
     resolveIcon?: (icon: IconFieldIcon) => string;
 };
 export declare const IconField: React.FC<IconFieldProps>;

package/dist/components/IconRenderer.d.ts

@@ -4,6 +4,10 @@ import type { IconFieldIcon, IconFieldIconRecord } from "../utils.js";
 export type IconRendererProps = Omit<HTMLAttributes<HTMLSpanElement>, "children" | "dangerouslySetInnerHTML"> & {
     fallback?: ReactNode;
     icons: IconFieldIcon[] | IconFieldIconRecord;
+    /**
+     * Maps registered icons to the stored string. Pass this when your stored
+     * values were produced with a custom `payloadIconPlugin({ resolveIcon })`.
+     */
     resolveIcon?: (icon: IconFieldIcon) => string;
     size?: number | string;
     value?: null | string;

package/dist/index.d.ts

@@ -12,22 +12,42 @@ export type PayloadIconPluginConfig = {
      */
     disabled?: boolean;
     /**
-     * Maps a selected icon to the string that is stored in Payload.
+     * Maps each registered icon to the final string stored in Payload.
+     *
+     * In normal `payloadIconPlugin()` + `iconField()` usage this runs during
+     * Payload config setup. The resolved string is then passed to the admin
+     * field as `icon.value`, so you do not need to also pass `resolveIcon` to
+     * the admin component manually.
      */
     resolveIcon?: (icon: IconFieldIcon) => string;
 };
 export type IconFieldConfig = Omit<TextField, "admin" | "hasMany" | "maxRows" | "minRows" | "type"> & {
     admin?: TextField["admin"];
+    /**
+     * Limit this field to icons whose final stored value uses one of these
+     * prefixes. Example: `["lucide"]` matches `lucide:Home`.
+     */
+    libraries?: string[];
     noResultsLabel?: string;
+    /**
+     * Limit this field to specific final stored icon values.
+     * Example: `["lucide:Home", "si:SiGithub"]`.
+     */
+    icons?: string[];
     placeholder?: string;
 };
 export type ResolveIconFromStringConfig = {
     icons: IconFieldIcon[] | IconFieldIconRecord;
+    /**
+     * Maps registered icons to the stored string. Use the same resolver that
+     * produced existing stored values when resolving icons outside the Payload
+     * admin UI.
+     */
     resolveIcon?: (icon: IconFieldIcon) => string;
 };
 export type ResolvedIcon = IconFieldIcon & {
     resolvedValue: string;
 };
-export declare const iconField: ({ admin, noResultsLabel, placeholder, ...field }: IconFieldConfig) => TextField;
+export declare const iconField: ({ admin, icons, libraries, noResultsLabel, placeholder, ...field }: IconFieldConfig) => TextField;
 export declare const payloadIconPlugin: (pluginOptions: PayloadIconPluginConfig) => (config: Config) => Config;
 export declare const createIconResolver: ({ icons, resolveIcon }: ResolveIconFromStringConfig) => (value: null | string | undefined) => ResolvedIcon | undefined;

package/dist/index.js

@@ -2,7 +2,8 @@ import { sanitizeSvg } from "./sanitizeSvg.js";
 import { normalizeIcons } from "./utils.js";
 const ICON_FIELD_MARKER = "payloadIconPicker";
 const ICON_FIELD_COMPONENT = "@mvriu5/payload-icon-picker/client#IconField";
-export const iconField = ({ admin, noResultsLabel, placeholder, ...field })=>({
+const PACKAGE_NAME = "@mvriu5/payload-icon-picker";
+export const iconField = ({ admin, icons, libraries, noResultsLabel, placeholder, ...field })=>({
         ...field,
         hasMany: false,
         type: "text",
@@ -11,6 +12,8 @@ export const iconField = ({ admin, noResultsLabel, placeholder, ...field })=>({
             custom: {
                 ...admin?.custom ?? {},
                 [ICON_FIELD_MARKER]: {
+                    icons,
+                    libraries,
                     noResultsLabel,
                     placeholder
                 }
@@ -34,7 +37,9 @@ export const payloadIconPlugin = (pluginOptions)=>(config)=>{
     };
 export const createIconResolver = ({ icons, resolveIcon })=>{
     const iconMap = new Map();
-    normalizeIcons(icons).forEach((icon)=>{
+    const normalizedIcons = normalizeIcons(icons);
+    warnAboutDuplicateIconValues(normalizedIcons, (icon)=>resolveIcon ? resolveIcon(icon) : icon.value ?? icon.name);
+    normalizedIcons.forEach((icon)=>{
         const resolvedValue = resolveIcon ? resolveIcon(icon) : icon.value ?? icon.name;
         iconMap.set(resolvedValue, {
             ...icon,
@@ -53,6 +58,8 @@ const withIconFields = (fields, icons)=>(fields ?? []).map((field)=>{
         const fieldWithNestedFields = field;
         if ("admin" in field && field.admin?.custom?.[ICON_FIELD_MARKER]) {
             const marker = field.admin.custom[ICON_FIELD_MARKER];
+            const fieldName = "name" in field && typeof field.name === "string" ? field.name : undefined;
+            const filteredIcons = filterIconsForField(icons, marker, fieldName);
             const textField = field;
             const admin = textField.admin;
             return {
@@ -63,7 +70,7 @@ const withIconFields = (fields, icons)=>(fields ?? []).map((field)=>{
                         ...admin?.components ?? {},
                         Field: {
                             clientProps: {
-                                icons,
+                                icons: filteredIcons,
                                 noResultsLabel: marker.noResultsLabel,
                                 placeholder: marker.placeholder
                             },
@@ -101,7 +108,9 @@ const withIconFields = (fields, icons)=>(fields ?? []).map((field)=>{
         return field;
     });
 const normalizeIconsForClient = (icons, resolveIcon)=>{
-    return normalizeIcons(icons).map(({ Icon, component, ...icon })=>{
+    const normalizedIcons = normalizeIcons(icons);
+    warnAboutDuplicateIconValues(normalizedIcons, (icon)=>resolveIcon ? resolveIcon(icon) : icon.value ?? icon.name);
+    return normalizedIcons.map(({ Icon, component, ...icon })=>{
         const sanitizedSvg = sanitizeSvg(icon.svg);
         return {
             ...icon,
@@ -114,3 +123,62 @@ const normalizeIconsForClient = (icons, resolveIcon)=>{
         };
     });
 };
+const filterIconsForField = (icons, marker, fieldName)=>{
+    const allowedLibraries = new Set(marker.libraries ?? []);
+    const allowedIconValues = new Set(marker.icons ?? []);
+    if (allowedLibraries.size === 0 && allowedIconValues.size === 0) {
+        return icons;
+    }
+    const filteredIcons = icons.filter((icon)=>{
+        const library = getIconValueLibrary(icon.value);
+        return allowedIconValues.has(icon.value) || (library ? allowedLibraries.has(library) : false);
+    });
+    warnAboutUnmatchedIconFieldFilters({
+        allowedIconValues,
+        allowedLibraries,
+        fieldName,
+        filteredIcons,
+        icons
+    });
+    return filteredIcons;
+};
+const getIconValueLibrary = (value)=>{
+    const separatorIndex = value.indexOf(":");
+    if (separatorIndex <= 0) {
+        return undefined;
+    }
+    return value.slice(0, separatorIndex);
+};
+const warnAboutUnmatchedIconFieldFilters = ({ allowedIconValues, allowedLibraries, fieldName, filteredIcons, icons })=>{
+    if (isProduction()) return;
+    const knownIconValues = new Set(icons.map((icon)=>icon.value));
+    const knownLibraries = new Set(icons.map((icon)=>getIconValueLibrary(icon.value)).filter((library)=>Boolean(library)));
+    const unknownIconValues = Array.from(allowedIconValues).filter((value)=>!knownIconValues.has(value));
+    const unknownLibraries = Array.from(allowedLibraries).filter((library)=>!knownLibraries.has(library));
+    const fieldLabel = fieldName ? `iconField("${fieldName}")` : "iconField()";
+    if (unknownIconValues.length > 0) {
+        console.warn(`[${PACKAGE_NAME}] ${fieldLabel} references unknown icon values: ${unknownIconValues.map((value)=>`"${value}"`).join(", ")}. ` + "Make sure the matching icons are registered in payloadIconPlugin().");
+    }
+    if (unknownLibraries.length > 0) {
+        console.warn(`[${PACKAGE_NAME}] ${fieldLabel} references unknown icon libraries: ${unknownLibraries.map((library)=>`"${library}"`).join(", ")}. ` + "Make sure the matching adapters use these prefixes in payloadIconPlugin().");
+    }
+    if (filteredIcons.length === 0) {
+        console.warn(`[${PACKAGE_NAME}] ${fieldLabel} filter matched no icons. The picker will render with an empty icon list.`);
+    }
+};
+const warnAboutDuplicateIconValues = (icons, resolveValue)=>{
+    if (isProduction()) return;
+    const iconsByValue = new Map();
+    icons.forEach((icon)=>{
+        const value = resolveValue(icon);
+        const names = iconsByValue.get(value) ?? [];
+        names.push(icon.name);
+        iconsByValue.set(value, names);
+    });
+    const duplicateMessages = Array.from(iconsByValue.entries()).filter(([, names])=>names.length > 1).map(([value, names])=>`"${value}" used by ${names.map((name)=>`"${name}"`).join(", ")}`);
+    if (duplicateMessages.length === 0) {
+        return;
+    }
+    console.warn(`[${PACKAGE_NAME}] Duplicate icon values detected: ${duplicateMessages.join("; ")}. ` + "Icon values must be unique so stored values resolve predictably. Use adapter prefixes to avoid collisions.");
+};
+const isProduction = ()=>typeof process !== "undefined" && process.env.NODE_ENV === "production";

package/dist/utils.d.ts

@@ -1,5 +1,5 @@
 import type { ElementType } from "react";
-export type IconComponent = ElementType<{
+type IconComponent = ElementType<{
     "aria-hidden"?: boolean;
     className?: string;
     focusable?: boolean;
@@ -17,13 +17,9 @@ export type IconFieldIcon = {
 export type IconFieldIconRecord = Record<string, IconComponent> | Record<string, IconFieldIcon>;
 export declare const defaultResolveIcon: (icon: IconFieldIcon) => string;
 export declare const normalizeIcons: (icons: IconFieldIcon[] | IconFieldIconRecord | undefined) => IconFieldIcon[];
-export declare const isIconComponent: (icon: IconComponent | IconFieldIcon) => icon is IconComponent;
 export declare const getIconLabelParts: (icon: IconFieldIcon, resolveIcon: (icon: IconFieldIcon) => string) => {
     name: string;
     prefix?: string;
 };
 export declare const getIconLibrary: (icon: IconFieldIcon, resolveIcon: (icon: IconFieldIcon) => string) => string | undefined;
-export declare const splitPrefixedValue: (value: string) => {
-    name: string;
-    prefix: string;
-} | undefined;
+export {};

package/dist/utils.js

@@ -19,7 +19,7 @@ export const normalizeIcons = (icons)=>{
         };
     });
 };
-export const isIconComponent = (icon)=>{
+const isIconComponent = (icon)=>{
     if (typeof icon === "function" || typeof icon === "string") {
         return true;
     }
@@ -41,7 +41,7 @@ export const getIconLabelParts = (icon, resolveIcon)=>{
     };
 };
 export const getIconLibrary = (icon, resolveIcon)=>splitPrefixedValue(resolveIcon(icon))?.prefix;
-export const splitPrefixedValue = (value)=>{
+const splitPrefixedValue = (value)=>{
     const separatorIndex = value.indexOf(":");
     if (separatorIndex <= 0 || separatorIndex === value.length - 1) return undefined;
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mvriu5/payload-icon-picker",
-    "version": "1.0.1",
+    "version": "1.0.2",
     "description": "Payload plugin introducing an icon picker into the CMS.",
     "license": "MIT",
     "type": "module",
@@ -88,7 +88,6 @@
         "@types/react-dom": "19.2.3",
         "copyfiles": "2.4.1",
         "cross-env": "^7.0.3",
-        "eslint": "^9.23.0",
         "graphql": "^17.0.2",
         "knip": "^6.24.0",
         "lucide-react": "^1.23.0",
@@ -162,7 +161,6 @@
         "entry": [
             "src/exports/client.ts",
             "dev/payload.config.ts",
-            "dev/next.config.mjs",
             "dev/app/**/*.{ts,tsx}"
         ],
         "ignore": [