@nice2dev/icons 1.0.0 → 1.0.3

package/dist/types/NtdIconBadge.d.ts

@@ -0,0 +1,209 @@
+/**
+ * @file NtdIconBadge.tsx
+ * @description Badge and status overlay system for icons
+ *
+ * Features:
+ * - Numeric badges (notification counts)
+ * - Status dots (online, offline, busy, away)
+ * - Checkmark overlays for completion states
+ * - Custom badge renderers
+ * - Animated badge changes
+ *
+ * @example
+ * ```tsx
+ * // Numeric badge
+ * <NtdBadge icon={NtdBell} count={5} />
+ *
+ * // Status dot
+ * <NtdStatusDot icon={NtdUser} status="online" />
+ *
+ * // Custom overlay
+ * <NtdIconOverlay icon={NtdFolder} overlay={<NtdPlus size="xs" />} />
+ * ```
+ *
+ * @version 1.0.0
+ * @since 2026-03
+ * @license MIT
+ */
+import React, { ComponentType, ReactNode } from 'react';
+import type { NtdIconProps, IconSize } from './types';
+export type BadgePosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left' | 'top-center' | 'bottom-center' | 'center-right' | 'center-left';
+export type StatusType = 'online' | 'offline' | 'busy' | 'away' | 'dnd' | 'invisible';
+export type BadgeVariant = 'standard' | 'dot' | 'pill';
+export interface NtdBadgeProps {
+    /** Icon component to wrap */
+    icon: ComponentType<NtdIconProps>;
+    /** Badge count (numbers or "99+") */
+    count?: number;
+    /** Maximum count to show (default: 99) */
+    maxCount?: number;
+    /** Show badge even when count is 0 */
+    showZero?: boolean;
+    /** Badge position */
+    position?: BadgePosition;
+    /** Badge variant style */
+    variant?: BadgeVariant;
+    /** Badge background color */
+    badgeColor?: string;
+    /** Badge text color */
+    textColor?: string;
+    /** Animate count changes */
+    animated?: boolean;
+    /** Pulse animation for attention */
+    pulse?: boolean;
+    /** Icon props passed to the wrapped icon */
+    iconProps?: NtdIconProps;
+    /** Additional class name */
+    className?: string;
+    /** Additional styles */
+    style?: React.CSSProperties;
+    /** Accessible label for badge */
+    'aria-label'?: string;
+}
+export interface NtdStatusDotProps {
+    /** Icon component to wrap */
+    icon: ComponentType<NtdIconProps>;
+    /** Status type */
+    status: StatusType;
+    /** Custom status color (overrides default) */
+    statusColor?: string;
+    /** Dot position */
+    position?: BadgePosition;
+    /** Dot size (relative to icon) */
+    dotSize?: 'sm' | 'md' | 'lg';
+    /** Animate presence */
+    animated?: boolean;
+    /** Pulse for online status */
+    pulse?: boolean;
+    /** Icon props passed to the wrapped icon */
+    iconProps?: NtdIconProps;
+    /** Additional class name */
+    className?: string;
+    /** Additional styles */
+    style?: React.CSSProperties;
+}
+export interface NtdIconOverlayProps {
+    /** Base icon component */
+    icon: ComponentType<NtdIconProps>;
+    /** Overlay content (icon, text, or custom React node) */
+    overlay: ReactNode;
+    /** Overlay position */
+    position?: BadgePosition;
+    /** Overlay size relative to base icon */
+    overlayScale?: number;
+    /** Overlay background */
+    overlayBg?: string;
+    /** Add circular background to overlay */
+    circularBg?: boolean;
+    /** Icon props for base icon */
+    iconProps?: NtdIconProps;
+    /** Additional class name */
+    className?: string;
+    /** Additional styles */
+    style?: React.CSSProperties;
+}
+/**
+ * Badge overlay component for icons with notification counts.
+ *
+ * @example
+ * ```tsx
+ * // Basic notification badge
+ * <NtdBadge icon={NtdBell} count={3} />
+ *
+ * // Large count with max
+ * <NtdBadge icon={NtdInbox} count={150} maxCount={99} />
+ *
+ * // Pulsing badge
+ * <NtdBadge icon={NtdMessage} count={1} pulse />
+ *
+ * // Custom colors
+ * <NtdBadge
+ *   icon={NtdHeart}
+ *   count={5}
+ *   badgeColor="#e91e63"
+ *   textColor="white"
+ * />
+ * ```
+ */
+export declare const NtdBadge: React.ForwardRefExoticComponent<NtdBadgeProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Status indicator dot overlay for icons.
+ *
+ * @example
+ * ```tsx
+ * // Online status
+ * <NtdStatusDot icon={NtdUser} status="online" />
+ *
+ * // Busy with pulse
+ * <NtdStatusDot icon={NtdUser} status="busy" pulse />
+ *
+ * // Custom position
+ * <NtdStatusDot icon={NtdUser} status="away" position="bottom-right" />
+ * ```
+ */
+export declare const NtdStatusDot: React.ForwardRefExoticComponent<NtdStatusDotProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Generic overlay component for composing icons.
+ *
+ * @example
+ * ```tsx
+ * // Folder with plus
+ * <NtdIconOverlay
+ *   icon={NtdFolder}
+ *   overlay={<NtdPlus size="xs" />}
+ *   position="bottom-right"
+ * />
+ *
+ * // With circular background
+ * <NtdIconOverlay
+ *   icon={NtdUser}
+ *   overlay={<NtdCheck size="xs" primaryColor="white" />}
+ *   circularBg
+ *   overlayBg="#22c55e"
+ * />
+ * ```
+ */
+export declare const NtdIconOverlay: React.ForwardRefExoticComponent<NtdIconOverlayProps & React.RefAttributes<HTMLDivElement>>;
+export interface NtdIconStackProps {
+    /** Base (background) icon */
+    base: ComponentType<NtdIconProps>;
+    /** Overlay (foreground) icon */
+    overlay: ComponentType<NtdIconProps>;
+    /** Base icon props */
+    baseProps?: NtdIconProps;
+    /** Overlay icon props */
+    overlayProps?: NtdIconProps;
+    /** Overlay position */
+    position?: BadgePosition;
+    /** Overlay scale relative to base */
+    overlayScale?: number;
+    /** Stack size override */
+    size?: IconSize;
+    /** Additional class name */
+    className?: string;
+    /** Additional styles */
+    style?: React.CSSProperties;
+}
+/**
+ * Stack two icons for composite imagery.
+ *
+ * @example
+ * ```tsx
+ * // Folder with star
+ * <NtdIconStack
+ *   base={NtdFolder}
+ *   overlay={NtdStar}
+ *   overlayProps={{ primaryColor: '#fbbf24' }}
+ * />
+ *
+ * // Ban overlay (slash through)
+ * <NtdIconStack
+ *   base={NtdCamera}
+ *   overlay={NtdSlash}
+ *   overlayProps={{ primaryColor: '#ef4444' }}
+ *   position="center"
+ * />
+ * ```
+ */
+export declare const NtdIconStack: React.ForwardRefExoticComponent<NtdIconStackProps & React.RefAttributes<HTMLDivElement>>;
+export default NtdBadge;

package/dist/types/NtdIconMorph.d.ts

@@ -0,0 +1,183 @@
+/**
+ * @file NtdIconMorph.tsx
+ * @description Smooth morphing transitions between icons
+ *
+ * Features:
+ * - SVG path morphing with interpolation
+ * - Predefined morph pairs (menu↔close, play↔pause, etc.)
+ * - Customizable duration, easing, direction
+ * - Trigger on hover/click/state change
+ *
+ * @example
+ * ```tsx
+ * // Basic morphing
+ * <NtdIconMorph from={NtdMenu} to={NtdClose} morphed={isOpen} />
+ *
+ * // With trigger
+ * <NtdIconMorph from={NtdPlay} to={NtdPause} trigger="click" />
+ *
+ * // Predefined pair
+ * <NtdIconMorphPair pair="menu-close" morphed={isOpen} />
+ * ```
+ *
+ * @version 1.0.0
+ * @since 2026-03
+ * @license MIT
+ */
+import React, { ComponentType } from 'react';
+import type { NtdIconProps, IconSize, IconVariant } from './types';
+export type MorphTrigger = 'none' | 'hover' | 'click' | 'focus';
+export type MorphDirection = 'normal' | 'reverse' | 'alternate';
+export type MorphEasing = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'spring' | 'bounce' | string;
+export interface NtdIconMorphProps {
+    /** Source icon component */
+    from: ComponentType<NtdIconProps>;
+    /** Target icon component */
+    to: ComponentType<NtdIconProps>;
+    /** Current morphed state (true = show 'to' icon) */
+    morphed?: boolean;
+    /** Auto-trigger morphing on interaction */
+    trigger?: MorphTrigger;
+    /** Animation duration in ms */
+    duration?: number;
+    /** Easing function */
+    easing?: MorphEasing;
+    /** Icon size */
+    size?: IconSize;
+    /** Icon variant */
+    variant?: IconVariant;
+    /** Primary color */
+    primaryColor?: string;
+    /** Secondary color (for duotone/flat) */
+    secondaryColor?: string;
+    /** Callback when morph starts */
+    onMorphStart?: (toMorphed: boolean) => void;
+    /** Callback when morph completes */
+    onMorphEnd?: (morphed: boolean) => void;
+    /** Additional class name */
+    className?: string;
+    /** Additional styles */
+    style?: React.CSSProperties;
+    /** Accessible label */
+    'aria-label'?: string;
+}
+export interface NtdMorphPairProps extends Omit<NtdIconMorphProps, 'from' | 'to'> {
+    /** Predefined icon pair */
+    pair: MorphPairName;
+}
+export type MorphPairName = 'menu-close' | 'play-pause' | 'plus-minus' | 'check-cross' | 'chevron-up-down' | 'expand-collapse' | 'sun-moon' | 'volume-mute' | 'lock-unlock' | 'eye-hidden' | 'heart-broken' | 'star-empty';
+/**
+ * Icon morphing component for smooth transitions between two icons.
+ *
+ * @example
+ * ```tsx
+ * // Controlled state
+ * <NtdIconMorph
+ *   from={NtdMenu}
+ *   to={NtdClose}
+ *   morphed={isOpen}
+ *   duration={300}
+ * />
+ *
+ * // Self-managed with trigger
+ * <NtdIconMorph
+ *   from={NtdPlay}
+ *   to={NtdPause}
+ *   trigger="click"
+ * />
+ * ```
+ */
+export declare const NtdIconMorph: React.ForwardRefExoticComponent<NtdIconMorphProps & React.RefAttributes<HTMLDivElement>>;
+export interface NtdPathMorphProps {
+    /** Predefined morph pair name */
+    pair: MorphPairName;
+    /** Current state (true = morphed to 'to' state) */
+    morphed?: boolean;
+    /** Auto-trigger on interaction */
+    trigger?: MorphTrigger;
+    /** Animation duration in ms */
+    duration?: number;
+    /** Easing function */
+    easing?: MorphEasing;
+    /** Icon size */
+    size?: IconSize;
+    /** Stroke/fill color */
+    color?: string;
+    /** Stroke width for outline style */
+    strokeWidth?: number;
+    /** Fill the path (default: false for stroke-based) */
+    filled?: boolean;
+    /** Callback when morph starts */
+    onMorphStart?: (toMorphed: boolean) => void;
+    /** Callback when morph completes */
+    onMorphEnd?: (morphed: boolean) => void;
+    /** Additional class name */
+    className?: string;
+    /** Additional styles */
+    style?: React.CSSProperties;
+    /** Accessible label */
+    'aria-label'?: string;
+}
+/**
+ * Path-based morphing using CSS transitions on SVG path data.
+ * Requires browser support for CSS `d` property transitions (modern browsers).
+ *
+ * @example
+ * ```tsx
+ * <NtdPathMorph
+ *   pair="menu-close"
+ *   morphed={isOpen}
+ *   duration={250}
+ *   color="#333"
+ * />
+ * ```
+ */
+export declare const NtdPathMorph: React.ForwardRefExoticComponent<NtdPathMorphProps & React.RefAttributes<SVGSVGElement>>;
+/**
+ * Convenience component for predefined icon morph pairs.
+ *
+ * @example
+ * ```tsx
+ * <NtdMorphPair pair="menu-close" morphed={isMenuOpen} />
+ * <NtdMorphPair pair="sun-moon" trigger="click" />
+ * ```
+ */
+export declare const NtdMorphPair: React.ForwardRefExoticComponent<NtdMorphPairProps & React.RefAttributes<HTMLDivElement>>;
+export interface UseMorphStateOptions {
+    /** Initial morphed state */
+    initial?: boolean;
+    /** Duration for callbacks timing */
+    duration?: number;
+    /** Callback when state changes */
+    onChange?: (morphed: boolean) => void;
+}
+export interface UseMorphStateReturn {
+    /** Current morphed state */
+    morphed: boolean;
+    /** Toggle the state */
+    toggle: () => void;
+    /** Set to morphed (true) */
+    morph: () => void;
+    /** Set to unmorphed (false) */
+    unmorph: () => void;
+    /** Set specific state */
+    setMorphed: (value: boolean) => void;
+    /** Whether currently animating */
+    isAnimating: boolean;
+}
+/**
+ * Hook for managing morph state with animation awareness.
+ *
+ * @example
+ * ```tsx
+ * const { morphed, toggle, isAnimating } = useMorphState({ duration: 300 });
+ *
+ * return (
+ *   <button onClick={toggle} disabled={isAnimating}>
+ *     <NtdIconMorph from={NtdMenu} to={NtdClose} morphed={morphed} />
+ *   </button>
+ * );
+ * ```
+ */
+export declare function useMorphState(options?: UseMorphStateOptions): UseMorphStateReturn;
+export default NtdIconMorph;

package/dist/types/NtdStateMorph.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @file NtdStateMorph.tsx
+ * @description State-based SVG path morphing for icons with multiple visual states.
+ *
+ * Unlike NtdIconMorph (which morphs between two different icon components),
+ * NtdStateMorph morphs a single icon between states — e.g., an empty heart
+ * filling up, a star being filled, a checkbox being checked.
+ *
+ * Supports liquid/fluid transitions via SVG path interpolation.
+ *
+ * @example
+ * ```tsx
+ * // Heart with fill animation
+ * <NtdStateMorph
+ *   states={{
+ *     empty: "M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z",
+ *     filled: "M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z"
+ *   }}
+ *   fills={{ empty: 'none', filled: '#e74c3c' }}
+ *   currentState="filled"
+ *   duration={400}
+ * />
+ *
+ * // Checkbox morph
+ * <NtdStateMorph
+ *   states={{
+ *     unchecked: "M19 3H5a2 2 0 00-2 2v14a2 2 0 002 2h14a2 2 0 002-2V5a2 2 0 00-2-2z",
+ *     checked: "M19 3H5a2 2 0 00-2 2v14a2 2 0 002 2h14a2 2 0 002-2V5a2 2 0 00-2-2zM9 17l-4-4 1.41-1.41L9 14.17l7.59-7.59L18 8l-9 9z"
+ *   }}
+ *   currentState={isChecked ? 'checked' : 'unchecked'}
+ * />
+ * ```
+ */
+import React from 'react';
+import type { IconSize } from './types';
+/** Map of state name → SVG path data string. */
+export type MorphStateMap = Record<string, string>;
+export interface NtdStateMorphProps {
+    /** Map of named states to SVG path strings */
+    states: MorphStateMap;
+    /** Current state to display */
+    currentState: string;
+    /** Fill color per state (optional — defaults to currentColor for all) */
+    fills?: Record<string, string>;
+    /** Stroke color per state (optional) */
+    strokes?: Record<string, string>;
+    /** Stroke width (default: 2) */
+    strokeWidth?: number;
+    /** Animation duration in ms (default: 300) */
+    duration?: number;
+    /** Easing function (default: 'ease-in-out') */
+    easing?: string;
+    /** Size */
+    size?: IconSize;
+    /** ViewBox (default: '0 0 24 24') */
+    viewBox?: string;
+    /** Additional class */
+    className?: string;
+    /** Additional styles */
+    style?: React.CSSProperties;
+    /** Accessible label */
+    'aria-label'?: string;
+    /** Callback when morph transition completes */
+    onTransitionEnd?: (state: string) => void;
+}
+export interface StateMorphHandle {
+    /** Get current state */
+    getState: () => string;
+    /** Programmatically set state */
+    setState: (state: string) => void;
+    /** Get SVG element ref */
+    getSvgElement: () => SVGSVGElement | null;
+}
+export declare const NtdStateMorph: React.ForwardRefExoticComponent<NtdStateMorphProps & React.RefAttributes<StateMorphHandle>>;
+/**
+ * Hook for managing morph state transitions.
+ *
+ * @example
+ * ```tsx
+ * const { state, setState, toggle, props } = useStateMorph(
+ *   { empty: emptyPath, filled: filledPath },
+ *   'empty',
+ *   { fills: { empty: 'none', filled: '#e74c3c' } },
+ * );
+ *
+ * <NtdStateMorph {...props} />
+ * <button onClick={toggle}>Toggle</button>
+ * ```
+ */
+export declare function useStateMorph(states: MorphStateMap, initialState: string, options?: {
+    fills?: Record<string, string>;
+    strokes?: Record<string, string>;
+    duration?: number;
+}): {
+    state: string;
+    setState: React.Dispatch<React.SetStateAction<string>>;
+    toggle: () => void;
+    props: NtdStateMorphProps;
+    stateNames: string[];
+};

package/dist/types/client.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @file client.tsx
+ * @description Client-only exports for @nice2dev/icons
+ *
+ * This module provides client-side features that require JavaScript:
+ * - Animation hooks and components
+ * - Interactive icons (hover/click effects)
+ * - Color scheme detection
+ * - Icon picker with state
+ *
+ * Use this module when you need client interactivity.
+ * For static icons in React Server Components, use '@nice2dev/icons/rsc'.
+ *
+ * @version 1.0.0
+ * @since 2026-03
+ * @license MIT
+ */
+export { AnimationController, InteractiveIcon, useAnimationSequence, createAnimationSequence, createHoverAnimation, createClickAnimation, createVisibilityAnimation, PRESET_SEQUENCES, PRESET_INTERACTIONS, } from './animationControls';
+export type { AnimationStep, AnimationSequenceConfig, AnimationPlaybackState, AnimationTrigger, InteractiveAnimationConfig, AnimationControllerHandle, AnimationControllerProps, InteractiveIconProps, } from './animationControls';
+export { NiceIconPicker } from './NiceIconPicker';
+export type { NiceIconPickerProps, NiceIconPickerHandle, IconPickerEntry } from './NiceIconPicker';
+export { NtdIconMorph, NtdPathMorph, NtdMorphPair, useMorphState, } from './NtdIconMorph';
+export type { NtdIconMorphProps, NtdPathMorphProps, NtdMorphPairProps, MorphTrigger, } from './NtdIconMorph';
+export { NtdBadge, NtdStatusDot, NtdIconOverlay, NtdIconStack, } from './NtdIconBadge';
+export type { NtdBadgeProps, NtdStatusDotProps, NtdIconOverlayProps, NtdIconStackProps, BadgePosition, StatusType, } from './NtdIconBadge';
+export { generateSmilAnimation, SmilAnimationWrapper, createSmilAnimationDef, isSmilSupported, SMIL_ANIMATION_TYPES, } from './smilAnimations';
+export type { SmilAnimationType, SmilAnimationConfig, SmilAnimationWrapperProps, } from './smilAnimations';