@jepepa/like-button 0.8.0

package/dist/index.d.ts

@@ -0,0 +1,580 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Particle System Type Definitions
+ *
+ * This file contains all type definitions for the enhanced particle effects system.
+ * Supports configurable shapes, animations, presets, and custom particle configurations.
+ */
+/**
+ * Built-in particle shape presets
+ *
+ * @example
+ * ```tsx
+ * <LikeButton particleConfig={{ shape: 'star' }} />
+ * <LikeButton particleConfig={{ shape: 'heart' }} />
+ * <LikeButton particleConfig={{ shape: 'sparkle' }} />
+ * ```
+ */
+type ParticleShapePreset = "heart" | "star" | "circle" | "square" | "sparkle";
+/**
+ * Props passed to particle shape render functions
+ *
+ * @example
+ * ```tsx
+ * const MyShape = ({ size, color, className }: ParticleShapeProps) => (
+ *   <svg width={size} height={size} className={className}>
+ *     <circle cx={size/2} cy={size/2} r={size/2} fill={color} />
+ *   </svg>
+ * );
+ * ```
+ */
+interface ParticleShapeProps {
+    /** Size of the shape in pixels */
+    size: number;
+    /** Color of the shape (hex or CSS color) */
+    color: string;
+    /** Additional CSS class names */
+    className?: string;
+}
+/**
+ * Custom particle shape configuration
+ *
+ * @example
+ * ```tsx
+ * const customShape: CustomParticleShape = {
+ *   render: ({ size, color }) => (
+ *     <svg width={size} height={size}>
+ *       <polygon points="..." fill={color} />
+ *     </svg>
+ *   )
+ * };
+ *
+ * <LikeButton particleConfig={{ shape: customShape }} />
+ * ```
+ */
+interface CustomParticleShape {
+    /** Custom render function for the particle shape */
+    render: (props: ParticleShapeProps) => React.ReactNode;
+}
+/**
+ * Particle shape - either a preset string or custom shape config
+ *
+ * @example
+ * ```tsx
+ * // Using preset
+ * const shape1: ParticleShape = 'star';
+ *
+ * // Using custom shape
+ * const shape2: ParticleShape = {
+ *   render: (props) => <MyCustomShape {...props} />
+ * };
+ * ```
+ */
+type ParticleShape = ParticleShapePreset | CustomParticleShape;
+/**
+ * Built-in particle effect presets
+ *
+ * - **burst**: Quick explosion of hearts in all directions (12 particles)
+ * - **fountain**: Upward spray effect (10 particles)
+ * - **confetti**: Colorful celebration with mixed shapes (15 particles)
+ * - **gentle**: Subtle floating effect (6 particles)
+ * - **fireworks**: Explosive sparkle effect (16 particles)
+ *
+ * @example
+ * ```tsx
+ * <LikeButton particlePreset="burst" />
+ * <LikeButton particlePreset="confetti" />
+ * <LikeButton particlePreset="fireworks" />
+ * ```
+ */
+type ParticlePreset = "burst" | "fountain" | "confetti" | "gentle" | "fireworks";
+/**
+ * Range configuration for numeric values
+ *
+ * @example
+ * ```tsx
+ * const distanceRange: Range = { min: 80, max: 120 };
+ * const sizeRange: Range = { min: 1.0, max: 2.0 };
+ *
+ * <LikeButton particleConfig={{
+ *   distance: distanceRange,
+ *   size: sizeRange
+ * }} />
+ * ```
+ */
+interface Range {
+    /** Minimum value */
+    min: number;
+    /** Maximum value */
+    max: number;
+}
+/**
+ * Complete particle configuration interface.
+ * All fields are optional - defaults will be applied.
+ *
+ * @example
+ * ```tsx
+ * const config: ParticleConfig = {
+ *   shape: 'star',
+ *   colors: ['#FFD700', '#FFA500'],
+ *   count: 12,
+ *   speed: 600,
+ *   distance: { min: 80, max: 120 },
+ *   spread: 180,
+ *   spreadOffset: -90,
+ * };
+ * ```
+ */
+interface ParticleConfig {
+    /**
+     * Particle shape - preset name or custom shape config
+     * @default 'heart'
+     */
+    shape?: ParticleShape;
+    /**
+     * Array of colors for particles (randomly selected)
+     * @default ['#EF4444', '#B9FF14', '#3B82F6']
+     */
+    colors?: string[];
+    /**
+     * Number of particles to spawn per click
+     * @default 8
+     */
+    count?: number;
+    /**
+     * Size range for particles (scale multiplier)
+     * Can be a single number or a range
+     * @default { min: 1.0, max: 1.5 }
+     */
+    size?: number | Range;
+    /**
+     * Animation duration in milliseconds
+     * @default 500
+     */
+    speed?: number;
+    /**
+     * Distance particles travel in pixels
+     * Can be a single number or a range
+     * @default { min: 60, max: 100 }
+     */
+    distance?: number | Range;
+    /**
+     * Spread angle in degrees (0-360)
+     * 360 = full circle, 180 = semicircle, etc.
+     * @default 360
+     */
+    spread?: number;
+    /**
+     * Starting angle offset in degrees
+     * 0 = right, 90 = down, 180 = left, 270 = up
+     * @default 0
+     */
+    spreadOffset?: number;
+    /**
+     * CSS easing function for particle animation
+     * @default 'cubic-bezier(0.22, 1, 0.36, 1)'
+     */
+    easing?: string;
+    /**
+     * Whether particles fade out during animation
+     * @default true
+     */
+    fadeOut?: boolean;
+}
+
+/** Data structure for a single particle effect */
+interface ParticleData {
+    id: string;
+    angle: number;
+    distance: number;
+    scale: number;
+    color: string;
+    shape: ParticleShape;
+    speed: number;
+    easing: string;
+    fadeOut: boolean;
+}
+/** Options for the useLikeButton hook */
+interface UseLikeButtonOptions {
+    /** Number of clicks by current user (controlled mode). If not provided, internal state is used. */
+    localClicks?: number;
+    /** Maximum number of clicks allowed per user */
+    maxClicks?: number;
+    /** Callback when button is clicked. Receives the new local click count. */
+    onClick?: (newLocalClicks: number) => void;
+    /** Callback when button is right-clicked. Receives the current click count. Does not increment or spawn particles. */
+    onRightClick?: (currentClicks: number) => void;
+    /** Whether the button is disabled */
+    disabled?: boolean;
+    /** Show particle effects on click */
+    showParticles?: boolean;
+    /** Custom aria-label override */
+    ariaLabel?: string;
+    /**
+     * Particle effect preset (burst, fountain, confetti, gentle, fireworks)
+     * @example
+     * ```tsx
+     * useLikeButton({ particlePreset: 'burst' })
+     * ```
+     */
+    particlePreset?: ParticlePreset;
+    /**
+     * Custom particle configuration (overrides preset)
+     * @example
+     * ```tsx
+     * useLikeButton({
+     *   particleConfig: {
+     *     shape: 'star',
+     *     colors: ['#FFD700', '#FFA500'],
+     *     count: 12,
+     *   }
+     * })
+     * ```
+     */
+    particleConfig?: Partial<ParticleConfig>;
+}
+/** Default values */
+declare const LIKE_BUTTON_DEFAULTS: {
+    readonly maxClicks: 14;
+    readonly size: 96;
+    readonly fillColor: "#EF4444";
+    readonly waveColor: "#B91C1C";
+};
+/** Return type for the useLikeButton hook */
+interface UseLikeButtonReturn {
+    /** Current click count */
+    localClicks: number;
+    /** Whether max clicks reached */
+    isMaxed: boolean;
+    /** Whether button is disabled */
+    disabled: boolean;
+    /** Fill percentage (0-100) */
+    fillPercentage: number;
+    /** Active particles to render */
+    particles: ParticleData[];
+    /** Click handler for the button */
+    handleClick: () => void;
+    /** Right-click handler for the button */
+    handleRightClick: (e: React.MouseEvent) => void;
+    /** Aria label for accessibility */
+    ariaLabel: string;
+    /** Whether button has been pressed */
+    isPressed: boolean;
+}
+/**
+ * Headless hook for LikeButton logic.
+ * Handles state management, particle spawning, and accessibility.
+ *
+ * @example
+ * ```tsx
+ * const { handleClick, localClicks, particles, ariaLabel } = useLikeButton({
+ *   maxClicks: 10,
+ *   onClick: (clicks) => console.log('Clicked!', clicks),
+ * });
+ * ```
+ */
+declare function useLikeButton(options?: UseLikeButtonOptions): UseLikeButtonReturn;
+
+/** Props passed to custom icon render function */
+interface IconRenderProps {
+    /** Suggested icon size in pixels (50% of button size by default) */
+    size: number;
+    /** Base CSS classes for positioning and transitions */
+    className: string;
+    /** Whether button is at max clicks */
+    isMaxed: boolean;
+    /** Current fill percentage (0-100) */
+    fillPercentage: number;
+}
+/** Preset shape values */
+type ShapePreset = "circle" | "rounded" | "square";
+/** Custom shape configuration */
+interface CustomShape {
+    /** CSS border-radius value (e.g., "1rem", "50%", "1rem 2rem") */
+    borderRadius?: string;
+    /** CSS clip-path value for custom shapes (e.g., "polygon(...)", "circle(...)") */
+    clipPath?: string;
+}
+/** Shape prop type - either a preset or custom configuration */
+type Shape = ShapePreset | CustomShape;
+/** Preset cursor values */
+type CursorPreset = "heart" | "star" | "thumbs-up" | "pointer" | "none";
+/** Custom cursor configuration */
+interface CustomCursor {
+    /**
+     * Cursor URL - can be a data URL (SVG/image) or external URL.
+     * @example "data:image/svg+xml;utf8,<svg>...</svg>"
+     * @example "/cursors/my-cursor.png"
+     */
+    url: string;
+    /** Hotspot X coordinate (default: 16) */
+    hotspotX?: number;
+    /** Hotspot Y coordinate (default: 16) */
+    hotspotY?: number;
+    /** Fallback cursor if custom cursor fails to load (default: "pointer") */
+    fallback?: "pointer" | "default" | "grab";
+}
+/**
+ * Cursor prop type - either a preset string or custom configuration.
+ * - "heart" (default): Heart-shaped cursor
+ * - "star": Star-shaped cursor
+ * - "thumbs-up": Thumbs up cursor
+ * - "pointer": Standard pointer cursor (disables custom cursor)
+ * - "none": Hides cursor entirely
+ * - CustomCursor: Custom cursor with URL and hotspot configuration
+ */
+type Cursor = CursorPreset | CustomCursor;
+/** Override brutalist styling */
+interface StyleOverrides {
+    /** Border width in pixels (default: 4) */
+    borderWidth?: number;
+    /** Border color (default: "#111827") */
+    borderColor?: string;
+    /** Shadow offset in pixels (default: 8) */
+    shadowOffset?: number;
+    /** Shadow color (default: "#111827") */
+    shadowColor?: string;
+    /** Background color (default: "white") */
+    backgroundColor?: string;
+}
+/**
+ * Base props shared between Tailwind and Vanilla CSS versions.
+ * Both versions accept identical props for API consistency.
+ */
+interface BaseLikeButtonProps extends UseLikeButtonOptions {
+    /** Button size in pixels */
+    size?: number;
+    /** Fill color for the liquid effect */
+    fillColor?: string;
+    /** Wave color (darker shade for back wave) */
+    waveColor?: string;
+    /** Additional CSS class name */
+    className?: string;
+    /**
+     * Initial/minimum fill percentage shown even before any clicks.
+     * Useful for custom shapes with narrow bottoms (e.g., hearts, diamonds)
+     * where low fill percentages may be invisible.
+     *
+     * Valid range: 0-85 (values above 85 will be clamped to 85)
+     * @default 0
+     * @example
+     * // Show 15% minimum fill for a heart shape
+     * <LikeButton minFillPercent={15} shape={{ clipPath: "polygon(...)" }} />
+     */
+    minFillPercent?: number;
+    /**
+     * Custom icon render function.
+     * - If undefined: renders default heart icon
+     * - If null: renders no icon
+     * - If function: calls with IconRenderProps
+     */
+    renderIcon?: ((props: IconRenderProps) => React.ReactNode) | null;
+    /**
+     * Button shape.
+     * - Presets: "circle" (default), "rounded", "square"
+     * - Custom: { borderRadius?: string, clipPath?: string }
+     */
+    shape?: Shape;
+    /** Override brutalist styling (border, shadow, background) */
+    styles?: StyleOverrides;
+    /**
+     * Cursor displayed when hovering over the button.
+     * - "heart" (default): Heart-shaped cursor
+     * - "star": Star-shaped cursor
+     * - "thumbs-up": Thumbs up cursor
+     * - "pointer": Standard pointer cursor
+     * - "none": Hides cursor
+     * - CustomCursor: { url, hotspotX?, hotspotY?, fallback? }
+     */
+    cursor?: Cursor;
+}
+/** Props for the LikeButton component (Tailwind version) */
+interface LikeButtonProps extends BaseLikeButtonProps {
+}
+/** Props for the LikeButton component (Vanilla CSS version) */
+interface LikeButtonVanillaProps extends BaseLikeButtonProps {
+}
+
+/**
+ * Default heart icon for LikeButton.
+ * Can be used as reference for creating custom icons.
+ */
+declare function DefaultHeartIcon({ size, className }: IconRenderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * LikeButton - Animated like button with liquid fill and particle effects.
+ * This version uses Tailwind CSS for styling.
+ *
+ * @example
+ * ```tsx
+ * // Default heart button
+ * <LikeButton onClick={(clicks) => console.log('Clicks:', clicks)} />
+ *
+ * // Custom icon
+ * <LikeButton renderIcon={({ size }) => <CustomIcon size={size} />} />
+ *
+ * // Custom shape
+ * <LikeButton shape="rounded" />
+ * <LikeButton shape={{ clipPath: "polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%)" }} />
+ *
+ * // Custom styles
+ * <LikeButton styles={{ shadowOffset: 4, borderWidth: 2 }} />
+ *
+ * // Custom cursor
+ * <LikeButton cursor="star" />
+ * <LikeButton cursor="pointer" /> // Standard pointer
+ * <LikeButton cursor={{ url: "data:image/svg+xml;...", hotspotX: 16, hotspotY: 16 }} />
+ *
+ * // Minimum fill for custom shapes
+ * <LikeButton minFillPercent={15} shape={{ clipPath: "polygon(...)" }} />
+ *
+ * // Particle presets
+ * <LikeButton particlePreset="burst" />
+ * <LikeButton particlePreset="confetti" />
+ * <LikeButton particlePreset="fireworks" />
+ *
+ * // Custom particle configuration
+ * <LikeButton particleConfig={{
+ *   shape: 'star',
+ *   colors: ['#FFD700', '#FFA500'],
+ *   count: 15,
+ *   speed: 800
+ * }} />
+ *
+ * // Combine preset with custom config
+ * <LikeButton
+ *   particlePreset="burst"
+ *   particleConfig={{ count: 20, colors: ['#ff0000'] }}
+ * />
+ *
+ * // Advanced particle configuration
+ * <LikeButton particleConfig={{
+ *   shape: 'sparkle',
+ *   count: 12,
+ *   speed: 600,
+ *   distance: { min: 80, max: 120 },
+ *   spread: 180,
+ *   spreadOffset: -90, // Upward spray
+ *   size: { min: 1.2, max: 2.0 },
+ *   easing: 'cubic-bezier(0.22, 1, 0.36, 1)',
+ *   fadeOut: true
+ * }} />
+ * ```
+ */
+declare function LikeButton({ size, fillColor, waveColor, className, showParticles, renderIcon, shape, styles, cursor, minFillPercent, ...hookOptions }: LikeButtonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * LikeButton - Animated like button with liquid fill and particle effects.
+ * This version uses vanilla CSS (no Tailwind dependency).
+ *
+ * @example
+ * ```tsx
+ * import { LikeButtonVanilla } from '@jepepa/like-button';
+ * import '@jepepa/like-button/styles.css';
+ *
+ * // Default usage
+ * <LikeButtonVanilla onClick={(clicks) => console.log('Clicks:', clicks)} />
+ *
+ * // Custom icon
+ * <LikeButtonVanilla renderIcon={({ size }) => <CustomIcon size={size} />} />
+ *
+ * // Custom shape
+ * <LikeButtonVanilla shape="rounded" />
+ * <LikeButtonVanilla shape={{ clipPath: "polygon(50% 0%, 100% 50%, 50% 100%, 0% 50%)" }} />
+ *
+ * // Custom styles
+ * <LikeButtonVanilla styles={{ shadowOffset: 4, borderWidth: 2 }} />
+ *
+ * // Custom cursor
+ * <LikeButtonVanilla cursor="star" />
+ * <LikeButtonVanilla cursor={{ url: "data:image/svg+xml;...", hotspotX: 16, hotspotY: 16 }} />
+ *
+ * // Minimum fill for custom shapes
+ * <LikeButtonVanilla minFillPercent={15} shape={{ clipPath: "polygon(...)" }} />
+ *
+ * // Particle presets (same API as Tailwind version)
+ * <LikeButtonVanilla particlePreset="burst" />
+ * <LikeButtonVanilla particlePreset="confetti" />
+ * <LikeButtonVanilla particlePreset="fireworks" />
+ *
+ * // Custom particle configuration
+ * <LikeButtonVanilla particleConfig={{
+ *   shape: 'star',
+ *   colors: ['#FFD700', '#FFA500'],
+ *   count: 15,
+ *   speed: 800
+ * }} />
+ *
+ * // Combine preset with custom config
+ * <LikeButtonVanilla
+ *   particlePreset="burst"
+ *   particleConfig={{ count: 20 }}
+ * />
+ * ```
+ */
+declare function LikeButtonVanilla({ size, fillColor, waveColor, className, showParticles, renderIcon, shape, styles, cursor, minFillPercent, ...hookOptions }: LikeButtonVanillaProps): react_jsx_runtime.JSX.Element;
+
+/** Props for particle components */
+interface ParticleProps {
+    /** Angle in degrees (0-360) for particle direction */
+    angle: number;
+    /** Distance in pixels the particle travels */
+    distance: number;
+    /** Scale multiplier for particle size */
+    scale: number;
+    /** Color of the particle (hex or CSS color) */
+    color: string;
+    /** Particle shape (preset or custom) */
+    shape: ParticleShape;
+    /** Animation duration in milliseconds */
+    speed: number;
+    /** CSS easing function for animation */
+    easing: string;
+    /** Whether particle should fade out */
+    fadeOut: boolean;
+}
+/** Return type for the useParticle hook */
+interface UseParticleReturn {
+    /** Whether the animation has started */
+    isAnimating: boolean;
+    /** X position offset in pixels */
+    x: number;
+    /** Y position offset in pixels */
+    y: number;
+    /** Computed transform string */
+    transform: string;
+    /** Computed opacity value */
+    opacity: number;
+    /** Animation duration in milliseconds */
+    speed: number;
+    /** CSS easing function */
+    easing: string;
+    /** Whether to fade out */
+    fadeOut: boolean;
+}
+/**
+ * Headless hook for particle animation logic.
+ * Handles animation state and position calculations.
+ */
+declare function useParticle({ angle, distance, scale, speed, easing, fadeOut, }: Pick<ParticleProps, "angle" | "distance" | "scale" | "speed" | "easing" | "fadeOut">): UseParticleReturn;
+
+/**
+ * Particle - Animated particle for burst effects.
+ * This version uses Tailwind CSS for styling.
+ *
+ * Supports multiple shapes (heart, star, circle, square, sparkle) and custom shapes.
+ * Animation is fully configurable via speed, easing, and fadeOut props.
+ */
+declare function Particle({ angle, distance, scale, color, shape, speed, easing, fadeOut, }: ParticleProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Particle - Animated particle for burst effects.
+ * This version uses vanilla CSS (no Tailwind dependency).
+ *
+ * Supports multiple shapes (heart, star, circle, square, sparkle) and custom shapes.
+ * Animation is fully configurable via speed, easing, and fadeOut props.
+ */
+declare function ParticleVanilla({ angle, distance, scale, color, shape, speed, easing, fadeOut, }: ParticleProps): react_jsx_runtime.JSX.Element;
+
+export { type BaseLikeButtonProps, type Cursor, type CursorPreset, type CustomCursor, type CustomShape, DefaultHeartIcon, type IconRenderProps, LIKE_BUTTON_DEFAULTS, LikeButton, type LikeButtonProps, LikeButtonVanilla, type LikeButtonVanillaProps, Particle, type ParticleData, type ParticleProps, ParticleVanilla, type Shape, type ShapePreset, type StyleOverrides, type UseLikeButtonOptions, type UseLikeButtonReturn, type UseParticleReturn, LikeButton as default, useLikeButton, useParticle };

package/dist/index.js

@@ -0,0 +1,22 @@
+import {
+  DefaultHeartIcon,
+  LIKE_BUTTON_DEFAULTS,
+  LikeButton,
+  LikeButtonVanilla,
+  Particle,
+  ParticleVanilla,
+  useLikeButton,
+  useParticle
+} from "./chunk-WTGBDIZW.js";
+export {
+  DefaultHeartIcon,
+  LIKE_BUTTON_DEFAULTS,
+  LikeButton,
+  LikeButtonVanilla,
+  Particle,
+  ParticleVanilla,
+  LikeButton as default,
+  useLikeButton,
+  useParticle
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/vanilla.d.ts

@@ -0,0 +1,2 @@
+export { BaseLikeButtonProps, Cursor, CursorPreset, CustomCursor, CustomShape, DefaultHeartIcon, IconRenderProps, LIKE_BUTTON_DEFAULTS, LikeButton, LikeButtonProps, LikeButtonVanilla, LikeButtonVanillaProps, Particle, ParticleData, ParticleProps, ParticleVanilla, Shape, ShapePreset, StyleOverrides, UseLikeButtonOptions, UseLikeButtonReturn, UseParticleReturn, LikeButtonVanilla as default, useLikeButton, useParticle } from './index.js';
+import 'react/jsx-runtime';

package/dist/vanilla.js

@@ -0,0 +1,22 @@
+import {
+  DefaultHeartIcon,
+  LIKE_BUTTON_DEFAULTS,
+  LikeButton,
+  LikeButtonVanilla,
+  Particle,
+  ParticleVanilla,
+  useLikeButton,
+  useParticle
+} from "./chunk-WTGBDIZW.js";
+export {
+  DefaultHeartIcon,
+  LIKE_BUTTON_DEFAULTS,
+  LikeButton,
+  LikeButtonVanilla,
+  Particle,
+  ParticleVanilla,
+  LikeButtonVanilla as default,
+  useLikeButton,
+  useParticle
+};
+//# sourceMappingURL=vanilla.js.map

package/dist/vanilla.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}