@ai-matrx/icons 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,178 @@
+import * as React from 'react';
+import React__default from 'react';
+
+/**
+ * Props every icon component in this registry accepts. Structural on purpose:
+ * the registry holds Lucide's ForwardRefExoticComponent icons AND (when the host
+ * installs the optional `react-icons` peer) react-icons' function components,
+ * without this package's public types depending on either library's type exports.
+ */
+interface IconRenderProps {
+    className?: string;
+    size?: string | number;
+    style?: React.CSSProperties;
+    color?: string;
+    strokeWidth?: string | number;
+}
+/**
+ * The one component shape this registry stores and renders. Lucide icons are
+ * assignable as-is; lazily loaded react-icons components are cast on entry.
+ */
+type IconComponentType = React.ComponentType<IconRenderProps>;
+
+declare const staticLucideIconMap: Record<string, IconComponentType>;
+/**
+ * Extend the static (synchronous, zero-latency) icon map with host-supplied
+ * components — extra statically imported Lucide icons a host uses on hot paths,
+ * or any component matching {@link IconComponentType}. Merges in place; later
+ * registrations override earlier entries of the same name.
+ */
+declare function extendStaticIcons(map: Record<string, IconComponentType>): void;
+
+/**
+ * Curated brand/custom icon names served from the OPTIONAL `react-icons` peer.
+ *
+ * Coupling inversion vs. the original (which statically imported react-icons):
+ * `react-icons` is an optional peerDependency, so these are lazy-imported on first
+ * use and cached at module level. When the host has not installed `react-icons`,
+ * loading degrades to null and the resolver renders the fallback icon instead —
+ * no install-time or import-time failure.
+ */
+
+/** True when `name` is one of the curated custom (react-icons) ids. */
+declare function isCustomIconName(name: string): boolean;
+/** The curated custom icon ids (known without loading react-icons). */
+declare function listCustomIconNames(): string[];
+/**
+ * Lazy-load a curated custom icon from the optional `react-icons` peer.
+ * Returns null for unknown names, a missing export, or when `react-icons`
+ * is not installed — the caller degrades to the fallback icon.
+ */
+declare function loadCustomIcon(name: string): Promise<IconComponentType | null>;
+
+/**
+ * Register (or override) `svg:` icon ids → asset URLs. Merges into the module-level
+ * registry, so multiple calls compose. Ids are stored without the `svg:` prefix.
+ */
+declare function registerSvgIcons(map: Record<string, string>): void;
+/** The registered asset URL for a `svg:…` icon value, or null when not a registered svg icon. */
+declare function parseSvgIconPath(value: string): string | null;
+/** True if `value` is a `svg:…` id with a registered asset path. */
+declare function isSvgIconValue(value: string | null | undefined): boolean;
+/** Every registered svg icon value, `svg:` prefix included (for pickers/galleries). */
+declare function listSvgIconValues(): string[];
+
+/**
+ * Lucide.dev lists icons in kebab-case (e.g. `alarm-clock`); the React package
+ * exports PascalCase (`AlarmClock`). Normalize pasted / typed names into candidates
+ * to validate against `lucide-react` exports.
+ */
+/**
+ * If the user pasted Lucide's JSX snippet (e.g. `'<BugPlay />'` or `<AlignCenterHorizontal />`),
+ * return the component name only. Otherwise return null.
+ *
+ * Supports optional outer quotes and optional attributes before the closing `/>`.
+ */
+declare function extractLucideJsxIconName(raw: string): string | null;
+/** `alarm-clock` → `AlarmClock`, `a-arrow-down` → `AArrowDown` */
+declare function kebabCaseToLucidePascalCase(raw: string): string;
+/**
+ * Ordered unique candidates: exact input, first-letter fix, kebab → Pascal variants.
+ * Skip Lucide heuristics for `svg:…` asset values (caller should pass only those as `[trimmed]`).
+ */
+declare function collectLucideIconNameCandidates(raw: string): string[];
+
+/**
+ * True if `exported` is the value of a Lucide icon entry for `name` in `import * as Lucide`.
+ * Does not mean the icon exists in the static resolver map — only that the lucide-react
+ * module exposes this name as a renderable component type.
+ */
+declare function isLucideModuleIconExport(name: string, exported: unknown): boolean;
+
+/**
+ * Finite list for a curated icon gallery: every statically bundled Lucide name,
+ * curated custom ids (react-icons), and all registered `svg:…` assets.
+ */
+declare function getCuratedIconIdsForPicker(): string[];
+/**
+ * True if this exact name maps to a known icon (static Lucide, curated custom id, or
+ * previously resolved dynamic Lucide cached under this key).
+ *
+ * Does not import lucide-react — use with {@link isRegisteredOrLucideIconName} for full checks.
+ */
+declare function isIconRegisteredSync(iconName: string | null | undefined): boolean;
+/**
+ * True if `iconName` is a real icon id: custom/static/cached, a registered `svg:…`
+ * asset, or a Lucide export that is a renderable component (not the fallback Zap).
+ *
+ * Prefer this over truthiness on {@link getIconComponent}, which always returns a component.
+ */
+declare function isRegisteredOrLucideIconName(iconName: string | null | undefined): Promise<boolean>;
+/**
+ * HOW TO ADD MORE STATIC ICONS:
+ *
+ * The curated hot set ships in the package (src/static-icons.ts). A host that
+ * frequently renders an icon outside the set keeps it zero-latency by statically
+ * importing it and registering it once at startup:
+ *
+ *   import { YourIcon } from "lucide-react";
+ *   import { extendStaticIcons } from "@ai-matrx/icons";
+ *   extendStaticIcons({ YourIcon });
+ */
+interface IconResolverProps {
+    iconName: string | null;
+    className?: string | undefined;
+    size?: number | undefined;
+    fallbackIcon?: string | undefined;
+    style?: React__default.CSSProperties | undefined;
+}
+/**
+ * IconResolver - A unified component for resolving and rendering icons by name
+ * Uses hybrid approach: static imports for common icons, dynamic imports for others
+ * Supports all lucide-react icons, curated custom icons (optional react-icons peer),
+ * and registered `svg:…` public assets.
+ */
+declare const IconResolver: React__default.FC<IconResolverProps>;
+
+/**
+ * Synchronous utility function for getting icon components directly
+ * Only works with statically imported icons plus already-loaded custom/dynamic icons.
+ * For dynamic Lucide icons not in the static map, use the IconResolver component instead
+ *
+ * **Always returns a component** (default/fallback Zap when unknown). Do not use the return
+ * value to infer whether `iconName` exists — use {@link isIconRegisteredSync} or
+ * {@link isRegisteredOrLucideIconName} instead.
+ */
+declare const getIconComponent: (iconName: string | null | undefined, fallbackIcon?: string) => IconComponentType;
+/**
+ * Renders an icon element directly with optional props
+ * This is the preferred method for rendering icons in JSX
+ */
+declare const renderIcon: (iconName: string | null | undefined, props?: IconRenderProps, fallbackIcon?: string) => React__default.JSX.Element;
+/**
+ * Utility to detect if a string is a hex color code
+ */
+declare const isHexColor: (color: string) => boolean;
+declare const getTextColorClass: (color?: string) => string | null;
+/**
+ * Utility function for rendering an icon with color and size
+ * Note: This is synchronous and only works with statically imported icons
+ * For dynamic icons, use the DynamicIcon component instead
+ */
+declare const getIconWithColorAndSize: (iconName: string | null, color?: string, size?: number) => React__default.JSX.Element;
+/**
+ * Simple Icon component for direct usage with color and size support
+ * Uses IconResolver internally to support both static and dynamic icons
+ *
+ * Supports both Tailwind color names (e.g., "blue", "red", "zinc") and hex colors (e.g., "#ff0000", "#666")
+ */
+interface DynamicIconProps {
+    name: string | null;
+    color?: string | undefined;
+    size?: number | undefined;
+    className?: string | undefined;
+    fallbackIcon?: string | undefined;
+}
+declare const DynamicIcon: React__default.FC<DynamicIconProps>;
+
+export { DynamicIcon, type DynamicIconProps, type IconComponentType, type IconRenderProps, IconResolver, type IconResolverProps, collectLucideIconNameCandidates, extendStaticIcons, extractLucideJsxIconName, getCuratedIconIdsForPicker, getIconComponent, getIconWithColorAndSize, getTextColorClass, isCustomIconName, isHexColor, isIconRegisteredSync, isLucideModuleIconExport, isRegisteredOrLucideIconName, isSvgIconValue, kebabCaseToLucidePascalCase, listCustomIconNames, listSvgIconValues, loadCustomIcon, parseSvgIconPath, registerSvgIcons, renderIcon, staticLucideIconMap };

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+import * as React from 'react';
+import React__default from 'react';
+
+/**
+ * Props every icon component in this registry accepts. Structural on purpose:
+ * the registry holds Lucide's ForwardRefExoticComponent icons AND (when the host
+ * installs the optional `react-icons` peer) react-icons' function components,
+ * without this package's public types depending on either library's type exports.
+ */
+interface IconRenderProps {
+    className?: string;
+    size?: string | number;
+    style?: React.CSSProperties;
+    color?: string;
+    strokeWidth?: string | number;
+}
+/**
+ * The one component shape this registry stores and renders. Lucide icons are
+ * assignable as-is; lazily loaded react-icons components are cast on entry.
+ */
+type IconComponentType = React.ComponentType<IconRenderProps>;
+
+declare const staticLucideIconMap: Record<string, IconComponentType>;
+/**
+ * Extend the static (synchronous, zero-latency) icon map with host-supplied
+ * components — extra statically imported Lucide icons a host uses on hot paths,
+ * or any component matching {@link IconComponentType}. Merges in place; later
+ * registrations override earlier entries of the same name.
+ */
+declare function extendStaticIcons(map: Record<string, IconComponentType>): void;
+
+/**
+ * Curated brand/custom icon names served from the OPTIONAL `react-icons` peer.
+ *
+ * Coupling inversion vs. the original (which statically imported react-icons):
+ * `react-icons` is an optional peerDependency, so these are lazy-imported on first
+ * use and cached at module level. When the host has not installed `react-icons`,
+ * loading degrades to null and the resolver renders the fallback icon instead —
+ * no install-time or import-time failure.
+ */
+
+/** True when `name` is one of the curated custom (react-icons) ids. */
+declare function isCustomIconName(name: string): boolean;
+/** The curated custom icon ids (known without loading react-icons). */
+declare function listCustomIconNames(): string[];
+/**
+ * Lazy-load a curated custom icon from the optional `react-icons` peer.
+ * Returns null for unknown names, a missing export, or when `react-icons`
+ * is not installed — the caller degrades to the fallback icon.
+ */
+declare function loadCustomIcon(name: string): Promise<IconComponentType | null>;
+
+/**
+ * Register (or override) `svg:` icon ids → asset URLs. Merges into the module-level
+ * registry, so multiple calls compose. Ids are stored without the `svg:` prefix.
+ */
+declare function registerSvgIcons(map: Record<string, string>): void;
+/** The registered asset URL for a `svg:…` icon value, or null when not a registered svg icon. */
+declare function parseSvgIconPath(value: string): string | null;
+/** True if `value` is a `svg:…` id with a registered asset path. */
+declare function isSvgIconValue(value: string | null | undefined): boolean;
+/** Every registered svg icon value, `svg:` prefix included (for pickers/galleries). */
+declare function listSvgIconValues(): string[];
+
+/**
+ * Lucide.dev lists icons in kebab-case (e.g. `alarm-clock`); the React package
+ * exports PascalCase (`AlarmClock`). Normalize pasted / typed names into candidates
+ * to validate against `lucide-react` exports.
+ */
+/**
+ * If the user pasted Lucide's JSX snippet (e.g. `'<BugPlay />'` or `<AlignCenterHorizontal />`),
+ * return the component name only. Otherwise return null.
+ *
+ * Supports optional outer quotes and optional attributes before the closing `/>`.
+ */
+declare function extractLucideJsxIconName(raw: string): string | null;
+/** `alarm-clock` → `AlarmClock`, `a-arrow-down` → `AArrowDown` */
+declare function kebabCaseToLucidePascalCase(raw: string): string;
+/**
+ * Ordered unique candidates: exact input, first-letter fix, kebab → Pascal variants.
+ * Skip Lucide heuristics for `svg:…` asset values (caller should pass only those as `[trimmed]`).
+ */
+declare function collectLucideIconNameCandidates(raw: string): string[];
+
+/**
+ * True if `exported` is the value of a Lucide icon entry for `name` in `import * as Lucide`.
+ * Does not mean the icon exists in the static resolver map — only that the lucide-react
+ * module exposes this name as a renderable component type.
+ */
+declare function isLucideModuleIconExport(name: string, exported: unknown): boolean;
+
+/**
+ * Finite list for a curated icon gallery: every statically bundled Lucide name,
+ * curated custom ids (react-icons), and all registered `svg:…` assets.
+ */
+declare function getCuratedIconIdsForPicker(): string[];
+/**
+ * True if this exact name maps to a known icon (static Lucide, curated custom id, or
+ * previously resolved dynamic Lucide cached under this key).
+ *
+ * Does not import lucide-react — use with {@link isRegisteredOrLucideIconName} for full checks.
+ */
+declare function isIconRegisteredSync(iconName: string | null | undefined): boolean;
+/**
+ * True if `iconName` is a real icon id: custom/static/cached, a registered `svg:…`
+ * asset, or a Lucide export that is a renderable component (not the fallback Zap).
+ *
+ * Prefer this over truthiness on {@link getIconComponent}, which always returns a component.
+ */
+declare function isRegisteredOrLucideIconName(iconName: string | null | undefined): Promise<boolean>;
+/**
+ * HOW TO ADD MORE STATIC ICONS:
+ *
+ * The curated hot set ships in the package (src/static-icons.ts). A host that
+ * frequently renders an icon outside the set keeps it zero-latency by statically
+ * importing it and registering it once at startup:
+ *
+ *   import { YourIcon } from "lucide-react";
+ *   import { extendStaticIcons } from "@ai-matrx/icons";
+ *   extendStaticIcons({ YourIcon });
+ */
+interface IconResolverProps {
+    iconName: string | null;
+    className?: string | undefined;
+    size?: number | undefined;
+    fallbackIcon?: string | undefined;
+    style?: React__default.CSSProperties | undefined;
+}
+/**
+ * IconResolver - A unified component for resolving and rendering icons by name
+ * Uses hybrid approach: static imports for common icons, dynamic imports for others
+ * Supports all lucide-react icons, curated custom icons (optional react-icons peer),
+ * and registered `svg:…` public assets.
+ */
+declare const IconResolver: React__default.FC<IconResolverProps>;
+
+/**
+ * Synchronous utility function for getting icon components directly
+ * Only works with statically imported icons plus already-loaded custom/dynamic icons.
+ * For dynamic Lucide icons not in the static map, use the IconResolver component instead
+ *
+ * **Always returns a component** (default/fallback Zap when unknown). Do not use the return
+ * value to infer whether `iconName` exists — use {@link isIconRegisteredSync} or
+ * {@link isRegisteredOrLucideIconName} instead.
+ */
+declare const getIconComponent: (iconName: string | null | undefined, fallbackIcon?: string) => IconComponentType;
+/**
+ * Renders an icon element directly with optional props
+ * This is the preferred method for rendering icons in JSX
+ */
+declare const renderIcon: (iconName: string | null | undefined, props?: IconRenderProps, fallbackIcon?: string) => React__default.JSX.Element;
+/**
+ * Utility to detect if a string is a hex color code
+ */
+declare const isHexColor: (color: string) => boolean;
+declare const getTextColorClass: (color?: string) => string | null;
+/**
+ * Utility function for rendering an icon with color and size
+ * Note: This is synchronous and only works with statically imported icons
+ * For dynamic icons, use the DynamicIcon component instead
+ */
+declare const getIconWithColorAndSize: (iconName: string | null, color?: string, size?: number) => React__default.JSX.Element;
+/**
+ * Simple Icon component for direct usage with color and size support
+ * Uses IconResolver internally to support both static and dynamic icons
+ *
+ * Supports both Tailwind color names (e.g., "blue", "red", "zinc") and hex colors (e.g., "#ff0000", "#666")
+ */
+interface DynamicIconProps {
+    name: string | null;
+    color?: string | undefined;
+    size?: number | undefined;
+    className?: string | undefined;
+    fallbackIcon?: string | undefined;
+}
+declare const DynamicIcon: React__default.FC<DynamicIconProps>;
+
+export { DynamicIcon, type DynamicIconProps, type IconComponentType, type IconRenderProps, IconResolver, type IconResolverProps, collectLucideIconNameCandidates, extendStaticIcons, extractLucideJsxIconName, getCuratedIconIdsForPicker, getIconComponent, getIconWithColorAndSize, getTextColorClass, isCustomIconName, isHexColor, isIconRegisteredSync, isLucideModuleIconExport, isRegisteredOrLucideIconName, isSvgIconValue, kebabCaseToLucidePascalCase, listCustomIconNames, listSvgIconValues, loadCustomIcon, parseSvgIconPath, registerSvgIcons, renderIcon, staticLucideIconMap };