@nice2dev/icons 1.0.0 → 1.0.3

package/dist/types/utilities.d.ts

@@ -0,0 +1,221 @@
+/**
+ * @file utilities.ts
+ * @description Utility hooks and functions for @nice2dev/icons
+ *
+ * Provides:
+ * - useIcon hook for dynamic icon loading
+ * - useReducedMotion hook for accessibility
+ * - preloadIcons for performance optimization
+ * - Icon type guards and helpers
+ *
+ * @example
+ * ```tsx
+ * import { useIcon, useReducedMotion, preloadIcons } from '@nice2dev/icons/utilities';
+ *
+ * // Dynamic icon loading
+ * const { Icon, isLoading } = useIcon('NtdHome');
+ *
+ * // Respect user preference for reduced motion
+ * const prefersReducedMotion = useReducedMotion();
+ *
+ * // Preload icons for better performance
+ * await preloadIcons(['NtdHome', 'NtdSearch', 'NtdUser']);
+ * ```
+ *
+ * @version 1.0.0
+ * @since 2026-03
+ * @license MIT
+ */
+import React from 'react';
+import type { ComponentType } from 'react';
+import type { NtdIconProps } from './types';
+/**
+ * Icon component type
+ */
+export type IconComponentType = ComponentType<NtdIconProps>;
+/**
+ * Result of useIcon hook
+ */
+export interface UseIconResult {
+    /** The loaded icon component, or null if loading/not found */
+    Icon: IconComponentType | null;
+    /** Whether the icon is currently loading */
+    isLoading: boolean;
+    /** Error if icon failed to load */
+    error: Error | null;
+}
+/**
+ * Options for useIcon hook
+ */
+export interface UseIconOptions {
+    /** Fallback icon while loading */
+    fallback?: IconComponentType;
+    /** Cache loaded icons */
+    cache?: boolean;
+}
+/**
+ * Registers an icon in the global registry
+ */
+export declare function registerIcon(name: string, component: IconComponentType): void;
+/**
+ * Gets an icon from the registry
+ */
+export declare function getIconFromRegistry(name: string): IconComponentType | undefined;
+/**
+ * Clears the icon registry
+ */
+export declare function clearIconRegistry(): void;
+/**
+ * Gets all registered icon names
+ */
+export declare function getRegisteredIconNames(): string[];
+/**
+ * Hook for dynamically loading icons by name.
+ *
+ * @param iconName - Name of the icon to load (e.g., 'NtdHome')
+ * @param options - Loading options
+ * @returns Icon component, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function DynamicIcon({ name }: { name: string }) {
+ *   const { Icon, isLoading, error } = useIcon(name);
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error || !Icon) return <FallbackIcon />;
+ *
+ *   return <Icon size="md" />;
+ * }
+ * ```
+ */
+export declare function useIcon(iconName: string | undefined, options?: UseIconOptions): UseIconResult;
+/**
+ * Hook that returns true if user prefers reduced motion.
+ * Uses useSyncExternalStore for SSR compatibility.
+ *
+ * @returns Whether the user prefers reduced motion
+ *
+ * @example
+ * ```tsx
+ * function AnimatedIcon() {
+ *   const prefersReducedMotion = useReducedMotion();
+ *
+ *   return (
+ *     <NtdHeart
+ *       animation={prefersReducedMotion ? undefined : 'pulse'}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export declare function useReducedMotion(): boolean;
+/**
+ * Preloads icons into the registry for instant access.
+ *
+ * @param iconNames - Array of icon names to preload
+ * @returns Promise that resolves when all icons are loaded
+ *
+ * @example
+ * ```tsx
+ * // Preload critical icons at app startup
+ * useEffect(() => {
+ *   preloadIcons(['NtdHome', 'NtdSearch', 'NtdUser', 'NtdMenu']);
+ * }, []);
+ * ```
+ */
+export declare function preloadIcons(iconNames: string[]): Promise<Map<string, IconComponentType>>;
+/**
+ * Creates a preloader component that preloads icons on mount.
+ *
+ * @param iconNames - Icons to preload
+ * @returns React component that preloads icons
+ *
+ * @example
+ * ```tsx
+ * const IconPreloader = createIconPreloader(['NtdHome', 'NtdSearch']);
+ *
+ * function App() {
+ *   return (
+ *     <>
+ *       <IconPreloader />
+ *       <MainContent />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function createIconPreloader(iconNames: string[]): React.FC;
+/**
+ * Creates props with animation disabled if user prefers reduced motion.
+ *
+ * @param props - Original icon props
+ * @param prefersReducedMotion - Whether user prefers reduced motion
+ * @returns Props with animation conditionally disabled
+ */
+export declare function withReducedMotionProps<T extends Partial<NtdIconProps>>(props: T, prefersReducedMotion: boolean): T;
+/**
+ * Creates accessible icon props based on context.
+ *
+ * @param options - Accessibility options
+ * @returns Icon props for accessibility
+ */
+export declare function createAccessibleIconProps(options: {
+    label?: string;
+    isDecorative?: boolean;
+    role?: string;
+}): Partial<NtdIconProps>;
+/**
+ * Checks if a value is a valid icon component.
+ * Handles both regular components and forwardRef components.
+ */
+export declare function isIconComponent(value: unknown): value is IconComponentType;
+/**
+ * Checks if an icon name is valid.
+ */
+export declare function isValidIconName(name: string): boolean;
+/**
+ * Configuration for batch icon rendering.
+ */
+export interface BatchIconConfig {
+    name: string;
+    props?: Partial<NtdIconProps>;
+}
+/**
+ * Creates a function that renders multiple icons efficiently.
+ *
+ * @param configs - Array of icon configurations
+ * @returns Function that renders all configured icons
+ *
+ * @example
+ * ```tsx
+ * const renderNavIcons = createBatchIconRenderer([
+ *   { name: 'NtdHome', props: { size: 'md' } },
+ *   { name: 'NtdSearch', props: { size: 'md' } },
+ *   { name: 'NtdUser', props: { size: 'md' } },
+ * ]);
+ *
+ * // In component
+ * const icons = renderNavIcons();
+ * ```
+ */
+export declare function useBatchIcons(configs: BatchIconConfig[]): {
+    renderIcon: (name: string, additionalProps?: Partial<NtdIconProps>) => React.ReactElement<NtdIconProps, string | React.JSXElementConstructor<any>> | null;
+    isLoading: boolean;
+    icons: Map<string, IconComponentType>;
+};
+declare const _default: {
+    useIcon: typeof useIcon;
+    useReducedMotion: typeof useReducedMotion;
+    preloadIcons: typeof preloadIcons;
+    createIconPreloader: typeof createIconPreloader;
+    registerIcon: typeof registerIcon;
+    getIconFromRegistry: typeof getIconFromRegistry;
+    clearIconRegistry: typeof clearIconRegistry;
+    getRegisteredIconNames: typeof getRegisteredIconNames;
+    withReducedMotionProps: typeof withReducedMotionProps;
+    createAccessibleIconProps: typeof createAccessibleIconProps;
+    isIconComponent: typeof isIconComponent;
+    isValidIconName: typeof isValidIconName;
+    useBatchIcons: typeof useBatchIcons;
+};
+export default _default;

package/dist/types/variantProps.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @file variantProps.ts
+ * @description Discriminated unions and strict prop validation per icon variant.
+ *
+ * Provides narrowed prop types for each icon variant (solid, outline, duotone, flat,
+ * sharp, rounded, mini, 3d) with variant-specific required/optional props.
+ *
+ * @example
+ * ```tsx
+ * // Narrows to DuotoneIconProps — guarantees secondaryColor is accepted
+ * const props: VariantIconProps = {
+ *   variant: 'duotone',
+ *   primaryColor: '#3b82f6',
+ *   secondaryColor: '#93c5fd',
+ *   secondaryOpacity: 0.4,
+ * };
+ *
+ * // Type guard usage
+ * if (isDuotoneProps(props)) {
+ *   props.secondaryColor; // string — narrowed
+ * }
+ * ```
+ */
+import type { NtdIconProps, IconSize, IconAnimation, GradientPreset, SemanticColor } from './types';
+interface SharedIconProps {
+    size?: IconSize;
+    color?: SemanticColor;
+    primaryColor?: string;
+    animation?: IconAnimation;
+    animationDuration?: string;
+    gradient?: GradientPreset;
+    rotate?: number;
+    flipX?: boolean;
+    flipY?: boolean;
+    scale?: number;
+    title?: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/** Props for `variant="solid"` — filled shapes, no stroke-specific props needed. */
+export interface SolidIconProps extends SharedIconProps {
+    variant: 'solid';
+}
+/** Props for `variant="outline"` — stroke-based, strokeWidth is important. */
+export interface OutlineIconProps extends SharedIconProps {
+    variant: 'outline';
+    strokeWidth?: number;
+    strokeLinecap?: 'round' | 'square' | 'butt';
+    strokeLinejoin?: 'round' | 'miter' | 'bevel';
+}
+/** Props for `variant="duotone"` — two-color rendering with opacity control. */
+export interface DuotoneIconProps extends SharedIconProps {
+    variant: 'duotone';
+    secondaryColor?: string;
+    secondaryOpacity?: number;
+    strokeWidth?: number;
+}
+/** Props for `variant="flat"` — badge-style with background color. */
+export interface FlatIconProps extends SharedIconProps {
+    variant: 'flat';
+    secondaryColor?: string;
+}
+/** Props for `variant="sharp"` — solid with sharp corners. */
+export interface SharpIconProps extends SharedIconProps {
+    variant: 'sharp';
+}
+/** Props for `variant="rounded"` — solid with extra-rounded corners. */
+export interface RoundedIconProps extends SharedIconProps {
+    variant: 'rounded';
+}
+/** Props for `variant="mini"` — compact, optimized for small sizes. */
+export interface MiniIconProps extends SharedIconProps {
+    variant: 'mini';
+}
+/** Props for `variant="3d"` — pseudo-3D with highlights and shadows. */
+export interface ThreeDIconProps extends SharedIconProps {
+    variant: '3d';
+    accentColor?: string;
+    accentOpacity?: number;
+}
+/**
+ * Discriminated union of all variant-specific prop types.
+ *
+ * Use this when you want TypeScript to narrow the type based on `variant`.
+ *
+ * @example
+ * ```tsx
+ * function renderIcon(props: VariantIconProps) {
+ *   switch (props.variant) {
+ *     case 'duotone':
+ *       return <NtdHome {...props} />; // props.secondaryColor is available
+ *     case 'outline':
+ *       return <NtdHome {...props} />; // props.strokeWidth is available
+ *     default:
+ *       return <NtdHome {...props} />;
+ *   }
+ * }
+ * ```
+ */
+export type VariantIconProps = SolidIconProps | OutlineIconProps | DuotoneIconProps | FlatIconProps | SharpIconProps | RoundedIconProps | MiniIconProps | ThreeDIconProps;
+/** Narrows to `SolidIconProps` when `variant === 'solid'`. */
+export declare function isSolidProps(props: VariantIconProps): props is SolidIconProps;
+/** Narrows to `OutlineIconProps` when `variant === 'outline'`. */
+export declare function isOutlineProps(props: VariantIconProps): props is OutlineIconProps;
+/** Narrows to `DuotoneIconProps` when `variant === 'duotone'`. */
+export declare function isDuotoneProps(props: VariantIconProps): props is DuotoneIconProps;
+/** Narrows to `FlatIconProps` when `variant === 'flat'`. */
+export declare function isFlatProps(props: VariantIconProps): props is FlatIconProps;
+/** Narrows to `SharpIconProps` when `variant === 'sharp'`. */
+export declare function isSharpProps(props: VariantIconProps): props is SharpIconProps;
+/** Narrows to `RoundedIconProps` when `variant === 'rounded'`. */
+export declare function isRoundedProps(props: VariantIconProps): props is RoundedIconProps;
+/** Narrows to `MiniIconProps` when `variant === 'mini'`. */
+export declare function isMiniProps(props: VariantIconProps): props is MiniIconProps;
+/** Narrows to `ThreeDIconProps` when `variant === '3d'`. */
+export declare function isThreeDProps(props: VariantIconProps): props is ThreeDIconProps;
+/**
+ * Converts a discriminated `VariantIconProps` into the general `NtdIconProps`.
+ * Useful when passing narrowed props to actual icon components.
+ */
+export declare function toIconProps(props: VariantIconProps): NtdIconProps;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice2dev/icons",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Beautiful, lightweight, multi-color SVG icon library for React with animations",
   "author": "NiceToDev <contact@nicetodev.com>",
   "license": "MIT",
@@ -16,11 +16,53 @@
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    },
+    "./rsc": {
+      "import": "./dist/esm/rsc.js",
+      "require": "./dist/cjs/rsc.js",
+      "types": "./dist/types/rsc.d.ts"
+    },
+    "./client": {
+      "import": "./dist/esm/client.js",
+      "require": "./dist/cjs/client.js",
+      "types": "./dist/types/client.d.ts"
+    },
+    "./tailwind": {
+      "import": "./dist/esm/tailwind-plugin.js",
+      "require": "./dist/cjs/tailwind-plugin.js",
+      "types": "./dist/types/tailwind-plugin.d.ts"
+    },
+    "./design-tokens": {
+      "import": "./dist/esm/design-tokens.js",
+      "require": "./dist/cjs/design-tokens.js",
+      "types": "./dist/types/design-tokens.d.ts"
+    },
+    "./headless-ui": {
+      "import": "./dist/esm/headless-ui.js",
+      "require": "./dist/cjs/headless-ui.js",
+      "types": "./dist/types/headless-ui.d.ts"
+    },
+    "./utilities": {
+      "import": "./dist/esm/utilities.js",
+      "require": "./dist/cjs/utilities.js",
+      "types": "./dist/types/utilities.d.ts"
+    },
+    "./styles.css": "./dist/animations.css"
+  },
+  "bin": {
+    "ntd-icons": "./bin/ntd-icons.mjs"
+  },
   "sideEffects": [
     "*.css"
   ],
   "files": [
     "dist",
+    "bin",
     "LICENSE",
     "CHANGELOG.md",
     "README.md"
@@ -28,6 +70,11 @@
   "scripts": {
     "build": "npm run build:types && rollup -c",
     "build:types": "tsc -p tsconfig.types.json",
+    "build:cdn": "vite build -c vite.cdn.config.ts",
+    "build:spritesheet": "node scripts/generate-spritesheet.mjs",
+    "build:iconfont": "node scripts/generate-iconfont.mjs",
+    "audit:treeshaking": "node scripts/tree-shaking-audit.mjs",
+    "audit:treeshaking:verbose": "node scripts/tree-shaking-audit.mjs --verbose --output reports/treeshaking-report.json",
     "dev": "rollup -c -w",
     "demo": "vite demo",
     "demo:build": "vite build demo",
@@ -37,7 +84,12 @@
     "test:coverage": "vitest run --config vitest.config.ts --coverage",
     "prepublishOnly": "npm run build",
     "storybook": "storybook dev -p 6006",
-    "build-storybook": "storybook build"
+    "build-storybook": "storybook build",
+    "test:visual": "npx chromatic --exit-zero-on-changes",
+    "test:visual:ci": "npx chromatic --auto-accept-changes=main",
+    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
+    "changelog:first": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
+    "version": "npm run changelog && git add CHANGELOG.md"
   },
   "keywords": [
     "icons",
@@ -49,8 +101,6 @@
     "duotone",
     "nicetodev"
   ],
-  "author": "NiceToDev",
-  "license": "MIT",
   "peerDependencies": {
     "react": ">=17.0.0",
     "react-dom": ">=17.0.0"
@@ -81,6 +131,9 @@
     "tslib": "^2.7.0",
     "typescript": "^5.6.0",
     "vite": "^6.0.0",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.0",
+    "chromatic": "^11.25.0",
+    "conventional-changelog-cli": "^5.0.0",
+    "conventional-changelog-angular": "^8.0.0"
   }
 }