@siratik/wp-component-library 0.1.0 → 0.1.2

package/components/icon-picker/api.js

@@ -0,0 +1,181 @@
+/**
+ * Icon Registry API
+ *
+ * Public functions for registering and removing icon sets.
+ * These are the functions blocks/themes call to populate the picker.
+ */
+
+import { dispatch, select } from "@wordpress/data";
+
+import {
+	clearIconSetLoader,
+	clearInFlightLoad,
+	getIconSetLoader,
+	getInFlightLoad,
+	setIconSetLoader,
+	setInFlightLoad,
+} from "./loaders";
+import { STORE_NAME } from "./store";
+
+/**
+ * Normalize lazy loader return value to an icon array.
+ *
+ * @param {Array|{ icons: Array }|*} result
+ * @returns {Array}
+ */
+function normalizeLoaderResult(result) {
+	if (Array.isArray(result)) {
+		return result;
+	}
+
+	if (result?.icons && Array.isArray(result.icons)) {
+		return result.icons;
+	}
+
+	if (result?.default && Array.isArray(result.default)) {
+		return result.default;
+	}
+
+	return [];
+}
+
+/**
+ * Register an icon set with the picker.
+ *
+ * Pass `icons` for eager sets, or `load` for lazy sets loaded when the picker opens:
+ *
+ * @example
+ * registerIconSet({
+ *   name: 'home-services',
+ *   label: 'Home Services',
+ *   priority: 120,
+ *   load: () => import('./home-services.js').then((m) => m.homeServicesIcons),
+ * });
+ *
+ * @param {Object} iconSet
+ * @param {string} iconSet.name    Unique identifier for this set (e.g. 'phosphor-icons').
+ * @param {string} iconSet.label   Human-readable label shown as group heading.
+ * @param {Array}  [iconSet.icons] Array of icon objects: { name, label, source }.
+ * @param {Function} [iconSet.load] Lazy loader returning icons (or a module with `.icons`).
+ * @param {number} [iconSet.priority=0]  Higher priority sets appear first.
+ */
+export function registerIconSet(iconSet) {
+	const { load, icons, ...rest } = iconSet;
+
+	if (typeof load === "function") {
+		setIconSetLoader(rest.name, load);
+
+		const previous = select(STORE_NAME)?.getIconSet?.(rest.name);
+		const libraryUrl = rest.libraryUrl ?? "";
+		const sameLibrary =
+			previous?.libraryUrl === libraryUrl && libraryUrl !== "";
+
+		dispatch(STORE_NAME).registerIconSet({
+			...rest,
+			libraryUrl,
+			priority: rest.priority ?? 0,
+			icons:
+				icons ??
+				(sameLibrary && previous?.icons?.length ? previous.icons : []),
+			loadStatus:
+				sameLibrary && previous?.loadStatus === "loaded"
+					? "loaded"
+					: "idle",
+		});
+		return;
+	}
+
+	clearIconSetLoader(rest.name);
+
+	dispatch(STORE_NAME).registerIconSet({
+		...rest,
+		priority: rest.priority ?? 0,
+		icons: icons ?? [],
+		loadStatus: "loaded",
+	});
+}
+
+/**
+ * Alias matching the 10up @10up/block-components registerIcons signature.
+ *
+ * @deprecated Prefer registerIconSet(). Kept for legacy theme bundles.
+ */
+export const registerIcons = registerIconSet;
+
+/**
+ * Load a single lazy icon set by name.
+ *
+ * @param {string} name
+ * @returns {Promise<void>}
+ */
+export async function loadIconSet(name) {
+	const store = select(STORE_NAME);
+	const set = store.getIconSet(name);
+
+	if (!set || set.loadStatus === "loaded") {
+		return;
+	}
+
+	const inFlight = getInFlightLoad(name);
+	if (inFlight) {
+		return inFlight;
+	}
+
+	const loader = getIconSetLoader(name);
+	if (!loader) {
+		dispatch(STORE_NAME).setIconSetError(
+			name,
+			"Icon set loader is not registered.",
+		);
+		return;
+	}
+
+	const loadPromise = (async () => {
+		dispatch(STORE_NAME).setIconSetLoading(name);
+
+		try {
+			const result = await loader();
+			const icons = normalizeLoaderResult(result);
+
+			dispatch(STORE_NAME).setIconSetIcons(name, icons);
+			clearIconSetLoader(name);
+		} catch (error) {
+			const message =
+				error instanceof Error ? error.message : String(error);
+			dispatch(STORE_NAME).setIconSetError(name, message);
+			throw error;
+		} finally {
+			clearInFlightLoad(name);
+		}
+	})();
+
+	setInFlightLoad(name, loadPromise);
+	return loadPromise;
+}
+
+/**
+ * Load every registered set that has not finished loading.
+ *
+ * @returns {Promise<void>}
+ */
+export async function loadAllIconSets() {
+	const store = select(STORE_NAME);
+	const pending = store
+		.getIconSets()
+		.filter(
+			(set) => set.loadStatus === "idle" || set.loadStatus === "error",
+		)
+		.map((set) => set.name);
+
+	await Promise.all(pending.map((name) => loadIconSet(name)));
+}
+
+/**
+ * Remove a previously registered icon set by name.
+ *
+ * @param {string} name The set name to remove.
+ */
+export function removeIconSet(name) {
+	clearIconSetLoader(name);
+	dispatch(STORE_NAME).removeIconSet(name);
+}

package/components/icon-picker/config-bootstrap.js

@@ -0,0 +1,108 @@
+/**
+ * Register icon sets declared in editor_experience.icons (Kitaris localize).
+ *
+ * @module icon-picker/config-bootstrap
+ */
+
+import { select } from "@wordpress/data";
+
+import { registerIconSet } from "./api";
+import { loadScript } from "./load-script";
+import { STORE_NAME } from "./store";
+
+/**
+ * Normalize lazy loader return value to an icon array.
+ *
+ * @param {Array|{ icons: Array }|*} result
+ * @returns {Array}
+ */
+function normalizeLoaderResult(result) {
+	if (Array.isArray(result)) {
+		return result;
+	}
+
+	if (result?.icons && Array.isArray(result.icons)) {
+		return result.icons;
+	}
+
+	if (result?.default && Array.isArray(result.default)) {
+		return result.default;
+	}
+
+	return [];
+}
+
+/**
+ * Load icons from a theme-built library URL (IIFE bundle).
+ *
+ * @param {string} url
+ * @param {string} setName
+ * @returns {Promise<Array>}
+ */
+async function loadIconsFromLibraryUrl(url, setName) {
+	if (typeof window !== "undefined" && window.wpcl?.iconSetExports?.[setName]) {
+		return window.wpcl.iconSetExports[setName];
+	}
+
+	await loadScript(url);
+
+	if (typeof window !== "undefined" && window.wpcl?.iconSetExports?.[setName]) {
+		return window.wpcl.iconSetExports[setName];
+	}
+
+	const store = select(STORE_NAME);
+	const set = store?.getIconSet?.(setName);
+
+	if (set?.icons?.length) {
+		return set.icons;
+	}
+
+	return [];
+}
+
+/**
+ * Register lazy icon sets from kitaris_localize editor_experience.icons config.
+ *
+ * Supports:
+ *   - `sets[]` with `library_url` (resolved in PHP from directory + file)
+ *   - Legacy top-level `library_url` (single register-icons.js bundle)
+ *
+ * @param {Object} [iconConfig]
+ */
+export function registerConfigIconSets(iconConfig) {
+	if (!iconConfig || typeof iconConfig !== "object") {
+		return;
+	}
+
+	const sets = [];
+
+	if (Array.isArray(iconConfig.sets) && iconConfig.sets.length) {
+		sets.push(...iconConfig.sets);
+	} else if (iconConfig.library_url) {
+		sets.push({
+			name: iconConfig.set_name ?? "theme-icons",
+			label: iconConfig.set_label ?? "Theme Icons",
+			priority: iconConfig.priority ?? 100,
+			library_url: iconConfig.library_url,
+		});
+	}
+
+	sets.forEach((set) => {
+		if (!set?.name || !set.library_url) {
+			return;
+		}
+
+		const libraryUrl = set.library_url;
+
+		registerIconSet({
+			name: set.name,
+			label: set.label ?? set.name,
+			priority: set.priority ?? 0,
+			libraryUrl,
+			load: () =>
+				loadIconsFromLibraryUrl(libraryUrl, set.name).then(
+					(icons) => normalizeLoaderResult(icons),
+				),
+		});
+	});
+}

package/components/icon-picker/hooks.js

@@ -0,0 +1,157 @@
+/**
+ * Icon Registry Hooks
+ *
+ * React hooks for reading icon data from the icon registry store.
+ */
+
+import { select as selectFromStore, useSelect } from "@wordpress/data";
+import { useEffect, useMemo } from "@wordpress/element";
+
+import { loadAllIconSets } from "./api";
+import { STORE_NAME } from "./store";
+
+/**
+ * Get all registered icon sets, sorted by priority.
+ *
+ * @returns {Array} Icon set objects in priority order.
+ */
+export function useIconSets() {
+	return useSelect((select) => select(STORE_NAME).getIconSets(), []);
+}
+
+/**
+ * Get icons for all sets, each annotated with their `iconSet` name.
+ * Returns sets in priority order for grouped rendering in the picker UI.
+ *
+ * @returns {Array<{ name, label, priority, icons: Array }>}
+ */
+export function useGroupedIcons() {
+	return useSelect((select) => {
+		const store = select(STORE_NAME);
+		return store.getIconSets().map((set) => ({
+			...set,
+			icons: store.getIcons(set.name).map((icon) => ({
+				...icon,
+				iconSet: set.name,
+			})),
+		}));
+	}, []);
+}
+
+/**
+ * Get a flat list of all icons across all sets, each annotated with `iconSet`.
+ * Useful for search across all sets.
+ *
+ * @returns {Array} Flat array of all icons.
+ */
+export function useAllIcons() {
+	return useSelect((select) => {
+		const store = select(STORE_NAME);
+		return store.getIconSets().flatMap((set) =>
+			store.getIcons(set.name).map((icon) => ({
+				...icon,
+				iconSet: set.name,
+			})),
+		);
+	}, []);
+}
+
+/**
+ * Get icons for a specific set, or all icons across all sets.
+ *
+ * Mirrors the 10up `useIcons(iconSetName)` hook signature.
+ *   - No argument (or empty string): returns all icons flat, each with `iconSet`.
+ *   - String argument: returns icons for that set only, each with `iconSet`.
+ *
+ * @param {string} [iconSetName] Optional set name to filter by.
+ * @returns {Array} Array of icon objects.
+ */
+export function useIcons(iconSetName = "") {
+	return useSelect((select) => {
+		const store = select(STORE_NAME);
+		if (iconSetName) {
+			return store.getIcons(iconSetName).map((icon) => ({
+				...icon,
+				iconSet: iconSetName,
+			}));
+		}
+		return store.getIconSets().flatMap((set) =>
+			store.getIcons(set.name).map((icon) => ({
+				...icon,
+				iconSet: set.name,
+			})),
+		);
+	}, [iconSetName]);
+}
+
+/**
+ * Look up a single icon from the registry.
+ *
+ * @param {string} iconSetName
+ * @param {string} iconName
+ * @returns {Object|undefined}
+ */
+export function useIcon(iconSetName, iconName) {
+	return useSelect(
+		(select) => select(STORE_NAME).getIcon(iconSetName, iconName),
+		[iconSetName, iconName],
+	);
+}
+
+/**
+ * Grouped icons for the picker modal — triggers lazy loading on mount.
+ *
+ * Groups are rebuilt only when a set changes (the store's sets map is
+ * replaced on every change), not on every store update.
+ *
+ * @returns {{ groups: Array, isLoading: boolean, isInitialLoad: boolean, hasPending: boolean }}
+ */
+export function useIconPickerGroups() {
+	const setsMap = useSelect(
+		(select) => select(STORE_NAME).getIconSetsMap(),
+		[],
+	);
+
+	const groups = useMemo(() => {
+		const store = selectFromStore(STORE_NAME);
+		return store.getIconSets().map((set) => ({
+			...set,
+			icons: store.getIcons(set.name).map((icon) => ({
+				...icon,
+				iconSet: set.name,
+			})),
+		}));
+		// setsMap is the cache key: the store replaces it whenever a set changes.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [setsMap]);
+
+	const sets = Object.values(setsMap);
+	const isLoading = sets.some((set) => set.loadStatus === "loading");
+	const pendingSets = sets.filter(
+		(set) => set.loadStatus === "idle" || set.loadStatus === "loading",
+	);
+	const hasPending = pendingSets.length > 0;
+	const pendingKey = pendingSets.map((set) => set.name).join("\0");
+
+	useEffect(() => {
+		if (!pendingKey) {
+			return;
+		}
+
+		loadAllIconSets().catch(() => {
+			// Errors are stored on the set; picker shows empty/error state.
+		});
+	}, [pendingKey]);
+
+	const iconCount = groups.reduce(
+		(count, group) => count + group.icons.length,
+		0,
+	);
+
+	return {
+		groups,
+		isLoading: hasPending || isLoading,
+		isInitialLoad: (hasPending || isLoading) && iconCount === 0,
+		hasPending,
+	};
+}

package/components/icon-picker/index.js

@@ -0,0 +1,39 @@
+/**
+ * Icon Picker
+ *
+ * Registry + UI components for icon selection in the block editor.
+ * Replaces @10up/block-components icon APIs.
+ */
+
+// Store (registers on import)
+export { iconStore, STORE_NAME as ICON_STORE_NAME } from "./store";
+
+// Registration API
+export {
+	registerIconSet,
+	registerIcons,
+	removeIconSet,
+	loadIconSet,
+	loadAllIconSets,
+} from "./api";
+export { registerConfigIconSets } from "./config-bootstrap";
+
+// SVG sanitizing for inline rendering
+export { safeSvgSource } from "./utils";
+
+// React hooks
+export {
+	useIconSets,
+	useGroupedIcons,
+	useIconPickerGroups,
+	useAllIcons,
+	useIcons,
+	useIcon,
+} from "./hooks";
+
+// UI components
+export { Icon } from "./Icon";
+export { IconPicker } from "./IconPicker";
+export { IconPickerModal } from "./IconPickerModal";
+export { IconPickerToolbarButton } from "./IconPickerToolbarButton";
+export { InlineIconPicker } from "./InlineIconPicker";

package/components/icon-picker/load-script.js

@@ -0,0 +1,33 @@
+/**
+ * Load a classic script URL (wp-scripts IIFE bundles) once.
+ *
+ * @param {string} url
+ * @returns {Promise<void>}
+ */
+const scriptPromises = new Map();
+
+export function loadScript(url) {
+	if (!url) {
+		return Promise.reject(new Error("Icon library URL is missing."));
+	}
+
+	const existing = scriptPromises.get(url);
+	if (existing) {
+		return existing;
+	}
+
+	const promise = new Promise((resolve, reject) => {
+		const script = document.createElement("script");
+		script.src = url;
+		script.async = true;
+		script.onload = () => resolve();
+		script.onerror = () => {
+			scriptPromises.delete(url);
+			reject(new Error(`Failed to load icon library: ${url}`));
+		};
+		document.head.appendChild(script);
+	});
+
+	scriptPromises.set(url, promise);
+	return promise;
+}

package/components/icon-picker/loaders.js

@@ -0,0 +1,79 @@
+/**
+ * Lazy icon-set loaders live outside Redux state (functions are not serializable).
+ * Stored on window.wpcl so theme editor bundles and the picker share one registry.
+ *
+ * @module icon-picker/loaders
+ */
+
+function getLoaderMap() {
+	if (typeof window !== "undefined") {
+		window.wpcl = window.wpcl || {};
+		if (!window.wpcl._iconSetLoaders) {
+			window.wpcl._iconSetLoaders = new Map();
+		}
+		return window.wpcl._iconSetLoaders;
+	}
+
+	return getLoaderMap.fallbackMap || (getLoaderMap.fallbackMap = new Map());
+}
+
+function getInFlightMap() {
+	if (typeof window !== "undefined") {
+		window.wpcl = window.wpcl || {};
+		if (!window.wpcl._iconSetLoadsInFlight) {
+			window.wpcl._iconSetLoadsInFlight = new Map();
+		}
+		return window.wpcl._iconSetLoadsInFlight;
+	}
+
+	return (
+		getInFlightMap.fallbackMap || (getInFlightMap.fallbackMap = new Map())
+	);
+}
+
+/**
+ * @param {string} name
+ * @param {() => Promise<Array>|Array} loader
+ */
+export function setIconSetLoader(name, loader) {
+	getLoaderMap().set(name, loader);
+}
+
+/**
+ * @param {string} name
+ * @returns {(() => Promise<Array>|Array)|undefined}
+ */
+export function getIconSetLoader(name) {
+	return getLoaderMap().get(name);
+}
+
+/**
+ * @param {string} name
+ */
+export function clearIconSetLoader(name) {
+	getLoaderMap().delete(name);
+	getInFlightMap().delete(name);
+}
+
+/**
+ * @param {string} name
+ * @param {Promise<void>} promise
+ */
+export function setInFlightLoad(name, promise) {
+	getInFlightMap().set(name, promise);
+}
+
+/**
+ * @param {string} name
+ * @returns {Promise<void>|undefined}
+ */
+export function getInFlightLoad(name) {
+	return getInFlightMap().get(name);
+}
+
+/**
+ * @param {string} name
+ */
+export function clearInFlightLoad(name) {
+	getInFlightMap().delete(name);
+}