analytica-frontend-lib/dist/hooks/useStudentsHighlight.d.ts

Repositório público dos componentes utilizados nas plataformas da Analytica Ensino

import { z } from 'zod';
/**
 * Period tabs configuration matching the Figma design
 */
export declare const PERIOD_TABS: readonly [{
    readonly value: "7_DAYS";
    readonly label: "7 dias";
}, {
    readonly value: "1_MONTH";
    readonly label: "1 mês";
}, {
    readonly value: "3_MONTHS";
    readonly label: "3 meses";
}, {
    readonly value: "6_MONTHS";
    readonly label: "6 meses";
}, {
    readonly value: "1_YEAR";
    readonly label: "1 ano";
}];
/**
 * Period filter options for students highlight (derived from PERIOD_TABS)
 */
export type StudentsHighlightPeriod = (typeof PERIOD_TABS)[number]['value'];
/**
 * Type filter options for students highlight
 */
export type StudentsHighlightType = 'ACTIVITIES' | 'LESSON_CONTENT';
/**
 * Trend direction for student performance
 */
export type TrendDirection = 'up' | 'down' | 'stable';
/**
 * Filters for students highlight API request
 */
export interface StudentsHighlightFilters {
    type?: StudentsHighlightType;
    period?: StudentsHighlightPeriod;
    subjectId?: string;
    schoolYearId?: string;
    classId?: string;
    schoolId?: string;
}
/**
 * Student highlight item from API response
 */
export interface StudentHighlightApiItem {
    id: string;
    name: string;
    correctAnswers: number;
    incorrectAnswers: number;
    totalQuestions: number;
    trend: number | null;
    trendDirection: TrendDirection | null;
}
/**
 * API response structure for students highlight endpoint
 */
export interface StudentsHighlightApiResponse {
    message: string;
    data: {
        topStudents: StudentHighlightApiItem[];
        bottomStudents: StudentHighlightApiItem[];
    };
}
/**
 * Transformed student item for UI display
 */
export interface StudentHighlightItem {
    /** Student ID */
    id: string;
    /** Student position in the ranking */
    position: number;
    /** Student name */
    name: string;
    /** Performance percentage (0-100) */
    percentage: number;
    /** Correct answers count */
    correctAnswers: number;
    /** Incorrect answers count */
    incorrectAnswers: number;
    /** Total questions answered */
    totalQuestions: number;
    /** Trend value (percentage change) */
    trend: number | null;
    /** Trend direction */
    trendDirection: TrendDirection | null;
}
/**
 * Zod schema for students highlight API response validation
 */
export declare const studentsHighlightApiResponseSchema: z.ZodObject<{
    message: z.ZodString;
    data: z.ZodObject<{
        topStudents: z.ZodArray<z.ZodObject<{
            id: z.ZodString;
            name: z.ZodString;
            correctAnswers: z.ZodNumber;
            incorrectAnswers: z.ZodNumber;
            totalQuestions: z.ZodNumber;
            trend: z.ZodNullable<z.ZodNumber>;
            trendDirection: z.ZodNullable<z.ZodEnum<{
                stable: "stable";
                up: "up";
                down: "down";
            }>>;
        }, z.core.$strip>>;
        bottomStudents: z.ZodArray<z.ZodObject<{
            id: z.ZodString;
            name: z.ZodString;
            correctAnswers: z.ZodNumber;
            incorrectAnswers: z.ZodNumber;
            totalQuestions: z.ZodNumber;
            trend: z.ZodNullable<z.ZodNumber>;
            trendDirection: z.ZodNullable<z.ZodEnum<{
                stable: "stable";
                up: "up";
                down: "down";
            }>>;
        }, z.core.$strip>>;
    }, z.core.$strip>;
}, z.core.$strip>;
/**
 * Hook state interface
 */
export interface UseStudentsHighlightState {
    topStudents: StudentHighlightItem[];
    bottomStudents: StudentHighlightItem[];
    loading: boolean;
    error: string | null;
}
/**
 * Hook return type
 */
export interface UseStudentsHighlightReturn extends UseStudentsHighlightState {
    fetchStudentsHighlight: (filters?: StudentsHighlightFilters) => Promise<void>;
    reset: () => void;
}
/**
 * Calculate performance percentage based on correct answers and total questions
 * @param correctAnswers - Number of correct answers
 * @param totalQuestions - Total number of questions
 * @returns Performance percentage (0-100)
 */
export declare const calculatePerformancePercentage: (correctAnswers: number, totalQuestions: number) => number;
/**
 * Transform API student item to UI display format
 * @param item - Student item from API response
 * @param position - Position in the ranking (1-based)
 * @returns Transformed student item for UI
 */
export declare const transformStudentHighlightItem: (item: StudentHighlightApiItem, position: number) => StudentHighlightItem;
/**
 * Handle errors during students highlight fetch
 * @param error - Error object
 * @returns Error message for UI display
 */
export declare const handleStudentsHighlightFetchError: (error: unknown) => string;
/**
 * Factory function to create useStudentsHighlight hook
 *
 * @param fetchStudentsHighlightApi - Function to fetch students highlight from API
 * @returns Hook for managing students highlight data
 *
 * @example
 * ```tsx
 * // In your app setup
 * const fetchStudentsHighlightApi = async (filters) => {
 *   const response = await api.get('/performance/students-highlight', { params: filters });
 *   return response.data;
 * };
 *
 * const useStudentsHighlight = createUseStudentsHighlight(fetchStudentsHighlightApi);
 *
 * // In your component
 * const { topStudents, bottomStudents, loading, error, fetchStudentsHighlight } = useStudentsHighlight();
 *
 * useEffect(() => {
 *   fetchStudentsHighlight({ period: '1_MONTH' });
 * }, []);
 * ```
 */
export declare const createUseStudentsHighlight: (fetchStudentsHighlightApi: (filters?: StudentsHighlightFilters) => Promise<StudentsHighlightApiResponse>) => () => UseStudentsHighlightReturn;
/**
 * Alias for createUseStudentsHighlight
 */
export declare const createStudentsHighlightHook: (fetchStudentsHighlightApi: (filters?: StudentsHighlightFilters) => Promise<StudentsHighlightApiResponse>) => () => UseStudentsHighlightReturn;
//# sourceMappingURL=useStudentsHighlight.d.ts.map