@nice2dev/icons 1.0.0 → 1.0.2

package/dist/types/headless-ui.d.ts

@@ -0,0 +1,462 @@
+/**
+ * @file headless-ui.tsx
+ * @description Headless UI / shadcn/ui compatibility layer for @nice2dev/icons
+ *
+ * Provides seamless integration with:
+ * - Radix UI components (via asChild pattern)
+ * - Headless UI components
+ * - shadcn/ui design system
+ *
+ * @example
+ * ```tsx
+ * // With shadcn/ui Button
+ * import { Button } from '@/components/ui/button';
+ * import { NtdSettings } from '@nice2dev/icons';
+ * import { forwardRefIcon } from '@nice2dev/icons/headless-ui';
+ *
+ * const SettingsIcon = forwardRefIcon(NtdSettings);
+ *
+ * <Button variant="ghost" size="icon" asChild>
+ *   <SettingsIcon className="h-4 w-4" />
+ * </Button>
+ * ```
+ *
+ * @version 1.0.0
+ * @since 2026-03
+ * @license MIT
+ */
+import React, { type ComponentType, type SVGProps, type ForwardRefExoticComponent, type PropsWithoutRef, type RefAttributes } from 'react';
+/**
+ * Base icon props interface
+ */
+export interface IconProps extends SVGProps<SVGSVGElement> {
+    size?: number | string;
+    color?: string;
+    primaryColor?: string;
+    secondaryColor?: string;
+    strokeWidth?: number | string;
+    variant?: string;
+    animation?: string;
+    animated?: boolean;
+    [key: `data-${string}`]: string | boolean | undefined;
+}
+/**
+ * Props for Radix UI asChild pattern compatibility
+ */
+export interface AsChildProps {
+    asChild?: boolean;
+    children?: React.ReactNode;
+}
+/**
+ * Combined props for headless-compatible icons
+ */
+export type HeadlessIconProps = IconProps & AsChildProps & {
+    [key: `data-${string}`]: string | boolean | undefined;
+};
+/**
+ * Slot props for Radix UI Slot pattern
+ */
+interface SlotProps {
+    children?: React.ReactNode;
+}
+/**
+ * ForwardRef icon component type
+ */
+export type ForwardRefIcon = ForwardRefExoticComponent<PropsWithoutRef<HeadlessIconProps> & RefAttributes<SVGSVGElement>>;
+/**
+ * Simple Slot implementation for asChild pattern.
+ * Compatible with Radix UI's Slot component behavior.
+ */
+export declare const Slot: React.ForwardRefExoticComponent<Omit<SlotProps & Record<string, unknown>, "ref"> & React.RefAttributes<Element>>;
+/**
+ * Wraps a NtdIcon component with forwardRef for Headless UI / Radix compatibility.
+ * Supports the asChild pattern used by shadcn/ui and Radix primitives.
+ *
+ * @param IconComponent - The NtdIcon component to wrap
+ * @param displayName - Optional display name for debugging
+ * @returns A forwardRef-wrapped icon component
+ *
+ * @example
+ * ```tsx
+ * import { NtdUser, NtdSettings } from '@nice2dev/icons';
+ * import { forwardRefIcon } from '@nice2dev/icons/headless-ui';
+ *
+ * // Create ref-compatible versions
+ * const UserIcon = forwardRefIcon(NtdUser);
+ * const SettingsIcon = forwardRefIcon(NtdSettings, 'SettingsIcon');
+ *
+ * // Use with Radix UI / shadcn
+ * <DropdownMenu.Trigger asChild>
+ *   <SettingsIcon className="h-5 w-5" />
+ * </DropdownMenu.Trigger>
+ * ```
+ */
+export declare function forwardRefIcon(IconComponent: ComponentType<any>, displayName?: string): ForwardRefIcon;
+/**
+ * shadcn/ui icon size presets matching their button sizes
+ */
+export declare const SHADCN_ICON_SIZES: {
+    readonly default: "1rem";
+    readonly sm: "0.875rem";
+    readonly lg: "1.125rem";
+    readonly icon: "1rem";
+};
+/**
+ * shadcn/ui color tokens mapping
+ */
+export declare const SHADCN_COLOR_TOKENS: {
+    readonly foreground: "hsl(var(--foreground))";
+    readonly mutedForeground: "hsl(var(--muted-foreground))";
+    readonly primary: "hsl(var(--primary))";
+    readonly primaryForeground: "hsl(var(--primary-foreground))";
+    readonly secondary: "hsl(var(--secondary))";
+    readonly secondaryForeground: "hsl(var(--secondary-foreground))";
+    readonly accent: "hsl(var(--accent))";
+    readonly accentForeground: "hsl(var(--accent-foreground))";
+    readonly destructive: "hsl(var(--destructive))";
+    readonly destructiveForeground: "hsl(var(--destructive-foreground))";
+};
+/**
+ * Creates shadcn/ui themed icon props
+ *
+ * @param variant - shadcn button variant
+ * @param size - shadcn button size
+ * @returns Props object for the icon
+ */
+export declare function getShadcnIconProps(variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link', size?: keyof typeof SHADCN_ICON_SIZES): Partial<IconProps>;
+/**
+ * Preset shadcn/ui className utilities for icons
+ */
+export declare const shadcnIconClasses: {
+    /** Standard icon in button */
+    readonly button: "h-4 w-4";
+    /** Icon with right margin (before text) */
+    readonly buttonLeft: "mr-2 h-4 w-4";
+    /** Icon with left margin (after text) */
+    readonly buttonRight: "ml-2 h-4 w-4";
+    /** Small icon */
+    readonly sm: "h-3.5 w-3.5";
+    /** Large icon */
+    readonly lg: "h-5 w-5";
+    /** Icon-only button */
+    readonly iconOnly: "h-4 w-4";
+    /** Navigation menu icon */
+    readonly nav: "h-4 w-4 shrink-0";
+    /** Dropdown menu icon */
+    readonly dropdown: "mr-2 h-4 w-4";
+    /** Alert/toast icon */
+    readonly alert: "h-4 w-4";
+    /** Badge icon */
+    readonly badge: "h-3 w-3";
+    /** Card header icon */
+    readonly card: "h-5 w-5 text-muted-foreground";
+    /** Spinner/loading */
+    readonly spinner: "h-4 w-4 animate-spin";
+};
+/**
+ * Creates an icon component compatible with Radix UI primitives.
+ * Automatically handles ref forwarding and asChild pattern.
+ *
+ * @param IconComponent - The NtdIcon component
+ * @param defaultProps - Default props to apply
+ * @returns Radix-compatible icon component
+ *
+ * @example
+ * ```tsx
+ * import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
+ * import { NtdChevronDown } from '@nice2dev/icons';
+ * import { createRadixIcon } from '@nice2dev/icons/headless-ui';
+ *
+ * const ChevronIcon = createRadixIcon(NtdChevronDown, {
+ *   className: 'h-4 w-4 text-muted-foreground'
+ * });
+ *
+ * <DropdownMenu.Trigger>
+ *   Options <ChevronIcon />
+ * </DropdownMenu.Trigger>
+ * ```
+ */
+export declare function createRadixIcon(IconComponent: ComponentType<any>, defaultProps?: Partial<IconProps>): ForwardRefIcon;
+/**
+ * HOC that adds Radix UI state-based styling to icons.
+ * Supports data-state attributes for open/closed states.
+ *
+ * @param IconComponent - The icon component to enhance
+ * @returns Enhanced icon with state-aware styling
+ *
+ * @example
+ * ```tsx
+ * const StateAwareChevron = withRadixState(NtdChevronDown);
+ *
+ * // Automatically rotates when parent has data-state="open"
+ * <Collapsible.Trigger>
+ *   <StateAwareChevron />
+ * </Collapsible.Trigger>
+ * ```
+ */
+export declare function withRadixState(IconComponent: ComponentType<any>): ForwardRefIcon;
+/**
+ * Transition presets for Headless UI Transition component with icons.
+ */
+export declare const headlessTransitions: {
+    /** Fade in/out */
+    readonly fade: {
+        readonly enter: "transition-opacity duration-150 ease-out";
+        readonly enterFrom: "opacity-0";
+        readonly enterTo: "opacity-100";
+        readonly leave: "transition-opacity duration-100 ease-in";
+        readonly leaveFrom: "opacity-100";
+        readonly leaveTo: "opacity-0";
+    };
+    /** Scale up/down */
+    readonly scale: {
+        readonly enter: "transition-transform duration-150 ease-out";
+        readonly enterFrom: "scale-75";
+        readonly enterTo: "scale-100";
+        readonly leave: "transition-transform duration-100 ease-in";
+        readonly leaveFrom: "scale-100";
+        readonly leaveTo: "scale-75";
+    };
+    /** Rotate */
+    readonly rotate: {
+        readonly enter: "transition-transform duration-200 ease-out";
+        readonly enterFrom: "rotate-0";
+        readonly enterTo: "rotate-180";
+        readonly leave: "transition-transform duration-200 ease-in";
+        readonly leaveFrom: "rotate-180";
+        readonly leaveTo: "rotate-0";
+    };
+    /** Spin (for loading) */
+    readonly spin: {
+        readonly enter: "animate-spin";
+        readonly enterFrom: "";
+        readonly enterTo: "";
+        readonly leave: "";
+        readonly leaveFrom: "";
+        readonly leaveTo: "";
+    };
+};
+/**
+ * Creates a Headless UI compatible icon with transition support.
+ *
+ * @param IconComponent - The icon component
+ * @param transition - Transition preset name
+ * @returns Icon component with transition classes
+ */
+export declare function createHeadlessIcon(IconComponent: ComponentType<any>, transition?: keyof typeof headlessTransitions): ComponentType<IconProps & {
+    show?: boolean;
+}>;
+/**
+ * Props generator for common icon button patterns in shadcn/ui.
+ */
+export declare const iconButtonPresets: {
+    /**
+     * Close button (X icon)
+     */
+    readonly close: {
+        readonly className: "rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground";
+        readonly size: 16;
+    };
+    /**
+     * Chevron (accordion, collapsible)
+     */
+    readonly chevron: {
+        readonly className: "h-4 w-4 shrink-0 transition-transform duration-200";
+        readonly 'data-chevron': true;
+    };
+    /**
+     * Menu trigger
+     */
+    readonly menuTrigger: {
+        readonly className: "h-5 w-5";
+        readonly strokeWidth: 1.5;
+    };
+    /**
+     * Navigation item icon
+     */
+    readonly navItem: {
+        readonly className: "mr-2 h-4 w-4 shrink-0";
+    };
+    /**
+     * Sidebar icon
+     */
+    readonly sidebar: {
+        readonly className: "h-4 w-4";
+        readonly strokeWidth: 2;
+    };
+    /**
+     * Toast icon
+     */
+    readonly toast: {
+        readonly className: "h-5 w-5";
+    };
+    /**
+     * Dialog icon
+     */
+    readonly dialog: {
+        readonly className: "h-4 w-4 opacity-70";
+    };
+};
+/**
+ * Merges icon props with shadcn/ui defaults.
+ *
+ * @param props - User-provided props
+ * @param preset - Preset name from iconButtonPresets
+ * @returns Merged props
+ */
+export declare function mergeIconProps<T extends IconProps>(props: T, preset: keyof typeof iconButtonPresets): T & {
+    className: string;
+};
+/**
+ * Creates a className string for icons based on variant and size.
+ *
+ * @param options - Styling options
+ * @returns Tailwind className string
+ */
+export declare function getIconClassName(options?: {
+    variant?: 'default' | 'muted' | 'primary' | 'destructive';
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    interactive?: boolean;
+    spinning?: boolean;
+}): string;
+declare const _default: {
+    forwardRefIcon: typeof forwardRefIcon;
+    createRadixIcon: typeof createRadixIcon;
+    withRadixState: typeof withRadixState;
+    createHeadlessIcon: typeof createHeadlessIcon;
+    getShadcnIconProps: typeof getShadcnIconProps;
+    mergeIconProps: typeof mergeIconProps;
+    getIconClassName: typeof getIconClassName;
+    Slot: React.ForwardRefExoticComponent<Omit<SlotProps & Record<string, unknown>, "ref"> & React.RefAttributes<Element>>;
+    SHADCN_ICON_SIZES: {
+        readonly default: "1rem";
+        readonly sm: "0.875rem";
+        readonly lg: "1.125rem";
+        readonly icon: "1rem";
+    };
+    SHADCN_COLOR_TOKENS: {
+        readonly foreground: "hsl(var(--foreground))";
+        readonly mutedForeground: "hsl(var(--muted-foreground))";
+        readonly primary: "hsl(var(--primary))";
+        readonly primaryForeground: "hsl(var(--primary-foreground))";
+        readonly secondary: "hsl(var(--secondary))";
+        readonly secondaryForeground: "hsl(var(--secondary-foreground))";
+        readonly accent: "hsl(var(--accent))";
+        readonly accentForeground: "hsl(var(--accent-foreground))";
+        readonly destructive: "hsl(var(--destructive))";
+        readonly destructiveForeground: "hsl(var(--destructive-foreground))";
+    };
+    shadcnIconClasses: {
+        /** Standard icon in button */
+        readonly button: "h-4 w-4";
+        /** Icon with right margin (before text) */
+        readonly buttonLeft: "mr-2 h-4 w-4";
+        /** Icon with left margin (after text) */
+        readonly buttonRight: "ml-2 h-4 w-4";
+        /** Small icon */
+        readonly sm: "h-3.5 w-3.5";
+        /** Large icon */
+        readonly lg: "h-5 w-5";
+        /** Icon-only button */
+        readonly iconOnly: "h-4 w-4";
+        /** Navigation menu icon */
+        readonly nav: "h-4 w-4 shrink-0";
+        /** Dropdown menu icon */
+        readonly dropdown: "mr-2 h-4 w-4";
+        /** Alert/toast icon */
+        readonly alert: "h-4 w-4";
+        /** Badge icon */
+        readonly badge: "h-3 w-3";
+        /** Card header icon */
+        readonly card: "h-5 w-5 text-muted-foreground";
+        /** Spinner/loading */
+        readonly spinner: "h-4 w-4 animate-spin";
+    };
+    headlessTransitions: {
+        /** Fade in/out */
+        readonly fade: {
+            readonly enter: "transition-opacity duration-150 ease-out";
+            readonly enterFrom: "opacity-0";
+            readonly enterTo: "opacity-100";
+            readonly leave: "transition-opacity duration-100 ease-in";
+            readonly leaveFrom: "opacity-100";
+            readonly leaveTo: "opacity-0";
+        };
+        /** Scale up/down */
+        readonly scale: {
+            readonly enter: "transition-transform duration-150 ease-out";
+            readonly enterFrom: "scale-75";
+            readonly enterTo: "scale-100";
+            readonly leave: "transition-transform duration-100 ease-in";
+            readonly leaveFrom: "scale-100";
+            readonly leaveTo: "scale-75";
+        };
+        /** Rotate */
+        readonly rotate: {
+            readonly enter: "transition-transform duration-200 ease-out";
+            readonly enterFrom: "rotate-0";
+            readonly enterTo: "rotate-180";
+            readonly leave: "transition-transform duration-200 ease-in";
+            readonly leaveFrom: "rotate-180";
+            readonly leaveTo: "rotate-0";
+        };
+        /** Spin (for loading) */
+        readonly spin: {
+            readonly enter: "animate-spin";
+            readonly enterFrom: "";
+            readonly enterTo: "";
+            readonly leave: "";
+            readonly leaveFrom: "";
+            readonly leaveTo: "";
+        };
+    };
+    iconButtonPresets: {
+        /**
+         * Close button (X icon)
+         */
+        readonly close: {
+            readonly className: "rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground";
+            readonly size: 16;
+        };
+        /**
+         * Chevron (accordion, collapsible)
+         */
+        readonly chevron: {
+            readonly className: "h-4 w-4 shrink-0 transition-transform duration-200";
+            readonly 'data-chevron': true;
+        };
+        /**
+         * Menu trigger
+         */
+        readonly menuTrigger: {
+            readonly className: "h-5 w-5";
+            readonly strokeWidth: 1.5;
+        };
+        /**
+         * Navigation item icon
+         */
+        readonly navItem: {
+            readonly className: "mr-2 h-4 w-4 shrink-0";
+        };
+        /**
+         * Sidebar icon
+         */
+        readonly sidebar: {
+            readonly className: "h-4 w-4";
+            readonly strokeWidth: 2;
+        };
+        /**
+         * Toast icon
+         */
+        readonly toast: {
+            readonly className: "h-5 w-5";
+        };
+        /**
+         * Dialog icon
+         */
+        readonly dialog: {
+            readonly className: "h-4 w-4 opacity-70";
+        };
+    };
+};
+export default _default;

package/dist/types/iconAnalytics.d.ts

@@ -0,0 +1,131 @@
+/**
+ * @file iconAnalytics.tsx
+ * @description Optional icon usage analytics — tracks which icons are rendered,
+ * provides a dashboard component, and recommendations for unused icons.
+ *
+ * @example
+ * ```tsx
+ * // 1. Wrap your app with the analytics provider
+ * const { AnalyticsProvider, useIconAnalytics } = createIconAnalyticsProvider();
+ *
+ * function App() {
+ *   return (
+ *     <AnalyticsProvider>
+ *       <MyApp />
+ *       <IconAnalyticsDashboard />
+ *     </AnalyticsProvider>
+ *   );
+ * }
+ *
+ * // 2. Use the hook inside icon wrappers or manually
+ * function TrackedIcon(props) {
+ *   const analytics = useIconAnalytics();
+ *   useEffect(() => { analytics.track('NtdHome'); }, []);
+ *   return <NtdHome {...props} />;
+ * }
+ * ```
+ */
+import React from 'react';
+/** A single usage tracking event. */
+export interface IconUsageEvent {
+    /** Icon component name (e.g. 'NtdHome') */
+    name: string;
+    /** Timestamp of last render */
+    lastSeen: number;
+    /** Total render count */
+    count: number;
+    /** Variant used (last) */
+    variant?: string;
+    /** Size used (last) */
+    size?: string | number;
+    /** Component path where the icon was rendered */
+    location?: string;
+}
+/** Configuration for the analytics system. */
+export interface IconAnalyticsOptions {
+    /** Enable/disable tracking (default: true in dev, false in prod) */
+    enabled?: boolean;
+    /** Maximum events to retain in memory */
+    maxEvents?: number;
+    /** Callback when a new icon is tracked */
+    onTrack?: (event: IconUsageEvent) => void;
+    /** Persist to localStorage key (default: none) */
+    storageKey?: string;
+}
+/** Aggregated analytics report. */
+export interface IconAnalyticsReport {
+    /** Total unique icons tracked */
+    totalUniqueIcons: number;
+    /** Total render count across all icons */
+    totalRenderCount: number;
+    /** Icons sorted by usage (most used first) */
+    mostUsed: IconUsageEvent[];
+    /** Icons that were rendered only once */
+    rarelyUsed: IconUsageEvent[];
+    /** Timestamp of report generation */
+    generatedAt: number;
+}
+declare class IconAnalyticsEngine {
+    private events;
+    private options;
+    constructor(options?: IconAnalyticsOptions);
+    track(name: string, meta?: {
+        variant?: string;
+        size?: string | number;
+        location?: string;
+    }): void;
+    getReport(): IconAnalyticsReport;
+    getAll(): IconUsageEvent[];
+    clear(): void;
+    private persist;
+}
+interface IconAnalyticsContextValue {
+    track: (name: string, meta?: {
+        variant?: string;
+        size?: string | number;
+        location?: string;
+    }) => void;
+    getReport: () => IconAnalyticsReport;
+    getAll: () => IconUsageEvent[];
+    clear: () => void;
+}
+/**
+ * Hook to access the icon analytics tracker.
+ *
+ * @returns Analytics functions: `track`, `getReport`, `getAll`, `clear`.
+ *
+ * @example
+ * ```tsx
+ * const analytics = useIconAnalytics();
+ * analytics.track('NtdHome', { variant: 'solid', size: 'lg' });
+ * const report = analytics.getReport();
+ * ```
+ */
+export declare function useIconAnalytics(): IconAnalyticsContextValue;
+/**
+ * Creates an analytics provider and hook pair.
+ *
+ * @param options - Analytics configuration
+ * @returns `{ AnalyticsProvider, useIconAnalytics }` to wrap your app.
+ */
+export declare function createIconAnalyticsProvider(options?: IconAnalyticsOptions): {
+    AnalyticsProvider: React.FC<{
+        children: React.ReactNode;
+    }>;
+    useIconAnalytics: typeof useIconAnalytics;
+    engine: IconAnalyticsEngine;
+};
+export interface IconAnalyticsDashboardProps {
+    /** Max items to show in top list */
+    maxItems?: number;
+    /** Additional class */
+    className?: string;
+    /** Additional styles */
+    style?: React.CSSProperties;
+}
+/**
+ * Dashboard component showing icon usage analytics.
+ * Displays most-used icons, render counts, and recommendations.
+ */
+export declare const IconAnalyticsDashboard: React.FC<IconAnalyticsDashboardProps>;
+export {};