@businessflow/reviews 1.0.0

package/dist/react/index.d.ts

@@ -0,0 +1,311 @@
+import React from 'react';
+
+interface Review {
+    id: string | number;
+    reviewerName: string;
+    reviewerEmail?: string;
+    reviewerTitle?: string;
+    reviewerCompany?: string;
+    reviewerAvatar?: string;
+    rating: number;
+    content?: string;
+    createdAt: string | Date;
+    updatedAt?: string | Date;
+    featured?: boolean;
+    approved?: boolean;
+    metadata?: Record<string, any>;
+}
+interface ReviewFormData {
+    reviewerName: string;
+    reviewerEmail: string;
+    reviewerTitle?: string;
+    reviewerCompany?: string;
+    rating: number;
+    content?: string;
+    [key: string]: any;
+}
+interface ReviewApiResponse {
+    success: boolean;
+    message?: string;
+    reviewId?: string | number;
+    status?: 'pending' | 'approved' | 'rejected';
+    data?: any;
+}
+interface ReviewSubmissionConfig {
+    endpoint: string;
+    method?: 'POST' | 'PUT';
+    headers?: Record<string, string>;
+    maxRetries?: number;
+    timeout?: number;
+    transformRequest?: (data: ReviewFormData) => any;
+    transformResponse?: (response: any) => ReviewApiResponse;
+    onSuccess?: (response: ReviewApiResponse) => void;
+    onError?: (error: Error) => void;
+}
+interface ReviewFetchConfig {
+    endpoint: string;
+    method?: 'GET';
+    headers?: Record<string, string>;
+    maxRetries?: number;
+    timeout?: number;
+    params?: {
+        limit?: number;
+        offset?: number;
+        featured?: boolean;
+        minRating?: number;
+        sortBy?: 'date' | 'rating' | 'name';
+        sortOrder?: 'asc' | 'desc';
+    };
+    transformResponse?: (response: any) => Review[];
+    onError?: (error: Error) => void;
+}
+interface ReviewFieldConfig {
+    show?: boolean;
+    required?: boolean;
+    label?: string;
+    type?: string;
+    placeholder?: string;
+    validation?: ValidationRule[];
+}
+interface ReviewFormConfig {
+    fields?: {
+        reviewerName?: ReviewFieldConfig;
+        reviewerEmail?: ReviewFieldConfig;
+        reviewerTitle?: ReviewFieldConfig;
+        reviewerCompany?: ReviewFieldConfig;
+        rating?: ReviewFieldConfig;
+        content?: ReviewFieldConfig;
+        [key: string]: ReviewFieldConfig | undefined;
+    };
+    recaptcha?: {
+        siteKey: string;
+        action?: string;
+    };
+    styling?: {
+        className?: string;
+        fieldClassName?: string;
+        buttonClassName?: string;
+        errorClassName?: string;
+        starClassName?: string;
+    };
+}
+interface TestimonialDisplayConfig {
+    limit?: number;
+    showRating?: boolean;
+    showDate?: boolean;
+    showAvatar?: boolean;
+    showCompany?: boolean;
+    showTitle?: boolean;
+    layout?: 'grid' | 'list' | 'slider';
+    columns?: number;
+    autoRefresh?: boolean;
+    refreshInterval?: number;
+    styling?: {
+        containerClassName?: string;
+        cardClassName?: string;
+        headerClassName?: string;
+        contentClassName?: string;
+        ratingClassName?: string;
+    };
+}
+interface ValidationRule {
+    type: 'required' | 'email' | 'minLength' | 'maxLength' | 'pattern' | 'custom' | 'rating';
+    value?: string | number;
+    message?: string;
+    validator?: (value: any) => boolean | string;
+}
+interface ValidationErrors {
+    [field: string]: string;
+}
+interface ReviewHandlerConfig {
+    onFetch?: (params?: any) => Promise<Review[]>;
+    onSubmit?: (data: ReviewFormData) => Promise<ReviewApiResponse>;
+    recaptcha?: {
+        secretKey: string;
+        minimumScore?: number;
+    };
+    validation?: {
+        [field: string]: ValidationRule[];
+    };
+    onSuccess?: (data: ReviewFormData, response: ReviewApiResponse) => Promise<void>;
+    onError?: (data: ReviewFormData, error: Error) => Promise<void>;
+    rateLimiter?: (request: Request) => Promise<boolean>;
+}
+interface StarRatingProps {
+    rating: number;
+    maxRating?: number;
+    editable?: boolean;
+    onChange?: (rating: number) => void;
+    size?: 'small' | 'medium' | 'large';
+    className?: string;
+}
+
+/**
+ * Generic review client for fetching and submitting reviews
+ */
+declare class ReviewClient {
+    private fetchConfig?;
+    private submitConfig?;
+    private maxRetries;
+    private timeout;
+    constructor(config: {
+        fetchConfig?: ReviewFetchConfig;
+        submitConfig?: ReviewSubmissionConfig;
+        maxRetries?: number;
+        timeout?: number;
+    });
+    /**
+     * Fetch reviews with retry logic
+     */
+    fetchReviews(params?: {
+        limit?: number;
+        offset?: number;
+        featured?: boolean;
+        minRating?: number;
+    }, retryCount?: number): Promise<Review[]>;
+    /**
+     * Submit a review with retry logic
+     */
+    submitReview(reviewData: ReviewFormData, retryCount?: number): Promise<ReviewApiResponse>;
+    /**
+     * Update configuration
+     */
+    updateConfig(config: {
+        fetchConfig?: Partial<ReviewFetchConfig>;
+        submitConfig?: Partial<ReviewSubmissionConfig>;
+    }): void;
+}
+
+interface ReviewSubmissionState {
+    isSubmitting: boolean;
+    isSuccess: boolean;
+    error: string | null;
+    retryCount: number;
+    canRetry: boolean;
+    lastSubmissionTime: number | null;
+}
+interface UseReviewSubmissionConfig extends ReviewFormConfig {
+    endpoint?: string;
+    onSubmit?: (data: ReviewFormData) => Promise<ReviewApiResponse>;
+    onSuccess?: (response: ReviewApiResponse) => void;
+    onError?: (error: Error) => void;
+    maxRetries?: number;
+}
+interface UseReviewSubmissionReturn {
+    formData: ReviewFormData;
+    errors: ValidationErrors;
+    state: ReviewSubmissionState;
+    handleChange: (field: keyof ReviewFormData, value: any) => void;
+    handleSubmit: () => Promise<void>;
+    handleRetry: () => Promise<void>;
+    resetForm: () => void;
+    client: ReviewClient | null;
+}
+/**
+ * Generic review submission hook with validation, submission, and retry logic
+ */
+declare const useReviewSubmission: (config: UseReviewSubmissionConfig) => UseReviewSubmissionReturn;
+
+interface ReviewFormProps extends UseReviewSubmissionConfig {
+    className?: string;
+    children?: React.ReactNode;
+    renderField?: (field: {
+        name: keyof ReviewFormData;
+        label: string;
+        value: any;
+        type: string;
+        required: boolean;
+        placeholder?: string;
+        error?: string;
+        onChange: (value: any) => void;
+    }) => React.ReactNode;
+    renderSubmitButton?: (props: {
+        isSubmitting: boolean;
+        isDisabled: boolean;
+        onClick: () => void;
+    }) => React.ReactNode;
+    renderSuccess?: (message: string) => React.ReactNode;
+    renderError?: (error: string, canRetry: boolean, onRetry: () => void) => React.ReactNode;
+}
+/**
+ * Generic review form component with customizable rendering
+ */
+declare const ReviewForm: React.FC<ReviewFormProps>;
+declare const defaultReviewFormStyles = "\n  .review-form .form-field {\n    margin-bottom: 1rem;\n  }\n\n  .review-form .form-label {\n    display: block;\n    margin-bottom: 0.25rem;\n    font-weight: 500;\n  }\n\n  .review-form .required {\n    color: #e53e3e;\n    margin-left: 0.25rem;\n  }\n\n  .review-form .form-input {\n    width: 100%;\n    padding: 0.75rem;\n    border: 1px solid #d1d5db;\n    border-radius: 4px;\n    font-size: 1rem;\n    transition: border-color 0.2s;\n  }\n\n  .review-form .form-input:focus {\n    outline: none;\n    border-color: #3b82f6;\n    box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);\n  }\n\n  .review-form .form-input.error {\n    border-color: #e53e3e;\n  }\n\n  .review-form .rating-field {\n    display: flex;\n    align-items: center;\n    gap: 1rem;\n  }\n\n  .review-form .rating-label {\n    font-size: 0.875rem;\n    color: #6b7280;\n  }\n\n  .review-form .form-error {\n    color: #e53e3e;\n    font-size: 0.875rem;\n    margin-top: 0.25rem;\n    display: block;\n  }\n\n  .review-form .general-error {\n    background-color: #fee2e2;\n    border: 1px solid #fecaca;\n    border-radius: 4px;\n    padding: 1rem;\n    margin-bottom: 1rem;\n  }\n\n  .review-form .general-error p {\n    margin: 0 0 0.5rem 0;\n  }\n\n  .review-form .general-error button {\n    background-color: #ef4444;\n    color: white;\n    padding: 0.5rem 1rem;\n    border: none;\n    border-radius: 4px;\n    cursor: pointer;\n  }\n\n  .review-form .submit-button {\n    background-color: #3b82f6;\n    color: white;\n    padding: 0.75rem 1.5rem;\n    border: none;\n    border-radius: 4px;\n    font-size: 1rem;\n    cursor: pointer;\n    transition: background-color 0.2s;\n    width: 100%;\n  }\n\n  .review-form .submit-button:hover:not(:disabled) {\n    background-color: #2563eb;\n  }\n\n  .review-form .submit-button:disabled {\n    opacity: 0.6;\n    cursor: not-allowed;\n  }\n\n  .success-message {\n    text-align: center;\n    padding: 2rem 1rem;\n    background-color: #f0fdf4;\n    border: 1px solid #bbf7d0;\n    border-radius: 8px;\n  }\n\n  .success-message h3 {\n    color: #059669;\n    margin-bottom: 1rem;\n  }\n\n  .success-message button {\n    background-color: #6b7280;\n    color: white;\n    padding: 0.5rem 1rem;\n    border: none;\n    border-radius: 4px;\n    cursor: pointer;\n    margin-top: 1rem;\n  }\n";
+
+interface TestimonialsSectionProps extends TestimonialDisplayConfig {
+    fetchConfig: ReviewFetchConfig;
+    className?: string;
+    renderTestimonial?: (testimonial: Review) => React.ReactNode;
+    renderLoading?: () => React.ReactNode;
+    renderError?: (error: string, canRetry: boolean, onRetry: () => void) => React.ReactNode;
+    renderEmpty?: () => React.ReactNode;
+}
+/**
+ * Generic testimonials display component
+ */
+declare const TestimonialsSection: React.FC<TestimonialsSectionProps>;
+declare const defaultTestimonialsStyles = "\n  .testimonials-section {\n    width: 100%;\n  }\n\n  .testimonials-grid {\n    display: grid;\n    gap: 1.5rem;\n  }\n\n  .testimonials-grid.columns-1 {\n    grid-template-columns: 1fr;\n  }\n\n  .testimonials-grid.columns-2 {\n    grid-template-columns: repeat(2, 1fr);\n  }\n\n  .testimonials-grid.columns-3 {\n    grid-template-columns: repeat(3, 1fr);\n  }\n\n  .testimonials-grid.columns-4 {\n    grid-template-columns: repeat(4, 1fr);\n  }\n\n  @media (max-width: 768px) {\n    .testimonials-grid.columns-3,\n    .testimonials-grid.columns-4 {\n      grid-template-columns: 1fr;\n    }\n    \n    .testimonials-grid.columns-2 {\n      grid-template-columns: 1fr;\n    }\n  }\n\n  @media (max-width: 1024px) and (min-width: 769px) {\n    .testimonials-grid.columns-3,\n    .testimonials-grid.columns-4 {\n      grid-template-columns: repeat(2, 1fr);\n    }\n  }\n\n  .testimonials-list {\n    display: flex;\n    flex-direction: column;\n    gap: 1.5rem;\n  }\n\n  .testimonials-slider {\n    display: flex;\n    overflow-x: auto;\n    gap: 1.5rem;\n    padding-bottom: 1rem;\n    scrollbar-width: thin;\n  }\n\n  .testimonials-slider::-webkit-scrollbar {\n    height: 8px;\n  }\n\n  .testimonials-slider::-webkit-scrollbar-track {\n    background: #f1f5f9;\n    border-radius: 4px;\n  }\n\n  .testimonials-slider::-webkit-scrollbar-thumb {\n    background: #cbd5e1;\n    border-radius: 4px;\n  }\n\n  .testimonials-slider .testimonial-card {\n    flex: 0 0 300px;\n  }\n\n  .testimonial-card {\n    background: white;\n    border: 1px solid #e2e8f0;\n    border-radius: 8px;\n    padding: 1.5rem;\n    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);\n    transition: box-shadow 0.2s ease;\n  }\n\n  .testimonial-card:hover {\n    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);\n  }\n\n  .testimonial-header {\n    display: flex;\n    justify-content: space-between;\n    align-items: flex-start;\n    margin-bottom: 1rem;\n  }\n\n  .reviewer-info {\n    display: flex;\n    gap: 0.75rem;\n    align-items: center;\n  }\n\n  .reviewer-avatar {\n    width: 48px;\n    height: 48px;\n    border-radius: 50%;\n    object-fit: cover;\n  }\n\n  .reviewer-name {\n    margin: 0 0 0.25rem 0;\n    font-size: 1rem;\n    font-weight: 600;\n    color: #1f2937;\n  }\n\n  .reviewer-title,\n  .reviewer-company {\n    margin: 0;\n    font-size: 0.875rem;\n    color: #6b7280;\n  }\n\n  .testimonial-content {\n    margin-bottom: 1rem;\n  }\n\n  .testimonial-content blockquote {\n    margin: 0;\n    font-style: italic;\n    color: #374151;\n    line-height: 1.6;\n  }\n\n  .testimonial-date {\n    font-size: 0.75rem;\n    color: #9ca3af;\n    text-align: right;\n  }\n\n  .loading-spinner {\n    text-align: center;\n    padding: 3rem;\n    color: #6b7280;\n  }\n\n  .error-message {\n    text-align: center;\n    padding: 3rem;\n    color: #ef4444;\n  }\n\n  .retry-button {\n    background-color: #3b82f6;\n    color: white;\n    border: none;\n    padding: 0.5rem 1rem;\n    border-radius: 4px;\n    cursor: pointer;\n    margin-top: 1rem;\n  }\n\n  .retry-button:hover {\n    background-color: #2563eb;\n  }\n\n  .refresh-indicator {\n    text-align: center;\n    padding: 1rem;\n    font-size: 0.875rem;\n    color: #6b7280;\n  }\n\n  .empty {\n    text-align: center;\n    padding: 3rem;\n    color: #6b7280;\n  }\n";
+
+/**
+ * Star rating component for displaying and selecting ratings
+ */
+declare const StarRating: React.FC<StarRatingProps>;
+declare const defaultStarRatingStyles = "\n  .star-rating {\n    display: inline-flex;\n    gap: 2px;\n  }\n\n  .star {\n    display: inline-block;\n    cursor: default;\n    user-select: none;\n    transition: color 0.2s ease;\n  }\n\n  .star.editable {\n    cursor: pointer;\n  }\n\n  .star.editable:hover {\n    transform: scale(1.1);\n  }\n\n  .star.editable:focus {\n    outline: 2px solid #3b82f6;\n    outline-offset: 2px;\n    border-radius: 2px;\n  }\n\n  .star.small {\n    font-size: 1rem;\n  }\n\n  .star.medium {\n    font-size: 1.5rem;\n  }\n\n  .star.large {\n    font-size: 2rem;\n  }\n\n  .star.filled {\n    color: #fbbf24;\n  }\n\n  .star.empty {\n    color: #d1d5db;\n  }\n\n  .star.editable.empty:hover {\n    color: #fbbf24;\n  }\n";
+
+interface TestimonialsState {
+    testimonials: Review[];
+    isLoading: boolean;
+    error: string | null;
+    retryCount: number;
+    canRetry: boolean;
+    lastFetchTime: number | null;
+}
+interface UseTestimonialsConfig {
+    fetchConfig: ReviewFetchConfig;
+    limit?: number;
+    featured?: boolean;
+    minRating?: number;
+    autoRefresh?: boolean;
+    refreshInterval?: number;
+    maxRetries?: number;
+}
+interface UseTestimonialsReturn {
+    testimonials: Review[];
+    isLoading: boolean;
+    error: string | null;
+    retryCount: number;
+    canRetry: boolean;
+    refetch: () => Promise<void>;
+    handleRetry: () => Promise<void>;
+}
+/**
+ * Generic hook for fetching and managing testimonials/reviews
+ */
+declare const useTestimonials: (config: UseTestimonialsConfig) => UseTestimonialsReturn;
+
+interface UseRecaptchaConfig {
+    siteKey: string;
+    action?: string;
+}
+interface UseRecaptchaReturn {
+    executeRecaptcha: () => Promise<string>;
+    isLoaded: boolean;
+    error: string | null;
+}
+declare global {
+    interface Window {
+        grecaptcha: {
+            ready: (callback: () => void) => void;
+            execute: (siteKey: string, options: {
+                action: string;
+            }) => Promise<string>;
+        };
+    }
+}
+/**
+ * Generic reCAPTCHA hook for form submissions
+ */
+declare const useRecaptcha: (config: UseRecaptchaConfig) => UseRecaptchaReturn;
+
+export { type Review, type ReviewApiResponse, type ReviewFetchConfig, type ReviewFieldConfig, ReviewForm, type ReviewFormConfig, type ReviewFormData, type ReviewFormProps, type ReviewHandlerConfig, type ReviewSubmissionConfig, type ReviewSubmissionState, StarRating, type StarRatingProps, type TestimonialDisplayConfig, TestimonialsSection, type TestimonialsSectionProps, type TestimonialsState, type UseRecaptchaConfig, type UseRecaptchaReturn, type UseReviewSubmissionConfig, type UseReviewSubmissionReturn, type UseTestimonialsConfig, type UseTestimonialsReturn, type ValidationErrors, type ValidationRule, defaultReviewFormStyles, defaultStarRatingStyles, defaultTestimonialsStyles, useRecaptcha, useReviewSubmission, useTestimonials };