@instincthub/react-ui 0.0.4 → 0.0.5

package/dist/src/types/components/forms/TextField.d.ts

@@ -1,23 +1,48 @@
 import { ChangeEvent } from "react";
 interface TextFieldProps {
-    types: string;
-    names: string;
-    labels: string;
-    requireds?: boolean;
-    defaultValues?: string | number | boolean;
-    ids?: string;
-    maxLengths?: number;
-    widths?: string;
-    disableds?: boolean;
-    notes?: string;
-    actives?: boolean;
+    type: string;
+    name: string;
+    label: string;
+    required?: boolean;
+    defaultValue?: string | number | boolean;
+    id?: string;
+    maxLength?: number;
+    width?: string;
+    disabled?: boolean;
+    note?: string;
+    active?: boolean;
     TextTransform?: "lowercase" | "uppercase" | "capitalize" | "none";
-    setValues?: (value: string) => void;
+    setValue?: (value: string) => void;
     onChange?: (e: ChangeEvent<HTMLInputElement>) => void;
     inputTarget?: (target: HTMLInputElement) => void;
     setNameValue?: (name: string, value: string) => void;
     arrayProps?: [number, string];
     setArrayProps?: (props: [number, string], value: string) => void;
 }
+/**
+ *
+ * @component
+ * @example
+ * ```tsx
+ *
+ * <TextField
+ *   label="Name"
+ *   name="name"
+ *   value="John Doe"
+ *   onChange={(e) => console.log(e.target.value)}
+ *   required={true}
+ *   placeholder="Enter your name"
+ *   disabled={false}
+ * />
+ * ```
+ * Props interface for the TextField component
+ * @property {string} label - Label text
+ * @property {string} name - Name of the input field
+ * @property {string} value - Value of the input field
+ * @property {(e: ChangeEvent<HTMLInputElement>) => void} onChange - Callback for input changes
+ * @property {boolean} required - Whether the field is required
+ * @property {string} placeholder - Placeholder text
+ * @property {boolean} disabled - Whether the field is disabled
+ * */
 declare function TextField(props: TextFieldProps): import("react/jsx-runtime").JSX.Element;
 export default TextField;

package/dist/src/types/components/forms/ToggleButton.d.ts

@@ -0,0 +1,29 @@
+import { ReactNode } from "react";
+interface ToggleButtonProps {
+    /** Name of the toggle */
+    name?: string;
+    /** Initial state of the toggle */
+    initialState?: boolean;
+    /** Callback function when toggle state changes */
+    onChange?: (isActive: boolean) => void;
+    /** Additional CSS class for custom styling */
+    className?: string;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Size of the toggle - small, medium, or large */
+    size?: "small" | "medium" | "large";
+    /** Label for the toggle */
+    label?: string | ReactNode;
+    /** Position of the label - left or right */
+    labelPosition?: "left" | "right";
+    /** Toggle without animation */
+    noAnimation?: boolean;
+    /** Background color when active - use CSS variable names */
+    activeColor?: string;
+    /** ID for the input element */
+    id?: string;
+    /** aria-label for accessibility */
+    ariaLabel?: string;
+}
+declare const ToggleButton: ({ name, initialState, onChange, className, disabled, size, label, labelPosition, noAnimation, activeColor, id, ariaLabel, }: ToggleButtonProps) => import("react/jsx-runtime").JSX.Element;
+export default ToggleButton;

package/dist/src/types/components/forms/radio-btn/RadioButton.d.ts

@@ -0,0 +1,57 @@
+import React from "react";
+/**
+ * Props for the RadioButton component
+ * @interface RadioButtonProps
+ */
+interface RadioButtonProps {
+    /** Unique identifier for the radio button */
+    id: string;
+    /** Name attribute for the radio input (for grouping) */
+    name: string;
+    /** Value of the radio button */
+    value: string;
+    /** Label text to display */
+    label: string;
+    /** Whether the radio button is checked */
+    checked?: boolean;
+    /** Whether the radio button is disabled */
+    disabled?: boolean;
+    /** Callback function when the radio button changes */
+    onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    /** Whether the input is required */
+    required?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+    /** Error message to display */
+    error?: string;
+    /** Help text to provide additional context */
+    helpText?: string;
+    /** Font size of the radio button */
+    fontSize?: string;
+}
+/**
+ * A customizable, accessible radio button component
+ * @example
+ * ```tsx
+ * <RadioButton
+ *  id="radio-button-1"
+ *  name="radio-button-group"
+ *  value="radio-button-1"
+ *  label="Radio Button 1"
+ * />
+ * ```
+ * @param id Unique identifier for the radio button
+ * @param name Name attribute for the radio input (for grouping)
+ * @param value Value of the radio button
+ * @param label Label text to display
+ * @param checked Whether the radio button is checked
+ * @param disabled Whether the radio button is disabled
+ * @param onChange Callback function when the radio button changes
+ * @param required Whether the radio button is required
+ * @param className Additional CSS classes
+ * @param error Error message to display
+ * @param helpText Help text to provide additional context
+ * @param fontSize Font size of the radio button
+ */
+declare const RadioButton: React.FC<RadioButtonProps>;
+export default RadioButton;

package/dist/src/types/components/forms/radio-btn/RadioGroup.d.ts

@@ -0,0 +1,48 @@
+import React from "react";
+/**
+ * Interface for radio option items
+ */
+interface RadioOption {
+    /** Unique identifier for the option */
+    id: string;
+    /** Value of the option */
+    value: string;
+    /** Display label for the option */
+    label: string;
+    /** Whether the option is disabled */
+    disabled?: boolean;
+    /** Help text for this specific option */
+    helpText?: string;
+}
+/**
+ * Props for the RadioGroup component
+ */
+interface RadioGroupProps {
+    /** Group label that describes the collection of options */
+    label: string;
+    /** Name attribute for all radio inputs in the group */
+    name: string;
+    /** Array of radio options to display */
+    options: RadioOption[];
+    /** Currently selected value */
+    selectedValue?: string;
+    /** Callback function when selection changes */
+    onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    /** Whether the field group is required */
+    required?: boolean;
+    /** Error message for the entire group */
+    error?: string;
+    /** Additional CSS classes */
+    className?: string;
+    /** Whether to display radio buttons inline horizontally */
+    inline?: boolean;
+    /** ID for the fieldset element */
+    id?: string;
+    /** Additional description for the group */
+    description?: string;
+}
+/**
+ * A component for grouping related radio buttons with a common label
+ */
+declare const RadioGroup: React.FC<RadioGroupProps>;
+export default RadioGroup;

package/dist/src/types/components/forms/uploads/IhubFileUploader.d.ts

@@ -1,46 +1,5 @@
-/**
- * Response interface for S3 uploads
- */
-export interface S3UploadResponseType {
-    bucket: string;
-    title: string;
-    key: string;
-    content_type: string;
-    size: number;
-    location: string;
-}
-/**
- * Props interface for the FileUploader component
- */
-export interface FileUploaderProps {
-    /** Header text to display above the uploader */
-    header?: string;
-    /** Label text for the dropzone area */
-    label?: string;
-    /** Accepted file types (e.g., 'image/*', 'video/*', '.pdf,.docx') */
-    accept?: string;
-    /** Maximum allowed file size in bytes */
-    maxFileSize?: number;
-    /** Input field name */
-    name?: string;
-    /** Module identifier for setting values */
-    module?: string;
-    /** Step identifier for setting values */
-    step?: string;
-    /** Username for file naming */
-    username?: string | null;
-    /** Callback for handling the upload response */
-    onUploadComplete?: (response: S3UploadResponseType) => void;
-    /** Callback for setting values */
-    setValues?: (name: string, value: string) => void;
-    /** Callback for setting module values */
-    setModules?: (module: string, name: string, value: string) => void;
-    /** Callback for setting step values */
-    setSteps?: (module: string, step: string, name: string, value: string) => void;
-    /** Additional CSS class names */
-    className?: string;
-}
+import { FileUploaderType } from "src/types";
 /**
  * A modern file uploader component with drag and drop support
  */
-export default function IhubFileUploader({ header, label, accept, maxFileSize, name, module, step, username, onUploadComplete, setValues, setModules, setSteps, className, }: FileUploaderProps): import("react/jsx-runtime").JSX.Element;
+export default function IhubFileUploader({ header, label, accept, maxFileSize, name, module, step, username, onUploadComplete, setValues, setModules, setSteps, className, }: FileUploaderType): import("react/jsx-runtime").JSX.Element;

package/dist/src/types/components/lib/auth/dbRequestst.d.ts

@@ -8,7 +8,16 @@ interface RequestParams {
 }
 /**
  * Fetches data from the API
+ * @example
+ * ```ts
+ * const data = await getData({ path: "/api/data", token: "your_token" });
+ * ```
  * @param params Request parameters
+ * @param params.path The path to the API endpoint (required) eg. "sis/${handle}/student/"
+ * @param params.token The token to use for the request (optional)
+ * @param params.method The method to use for the request (optional)
+ * @param params.type The type of the request (optional)
+ * @param params.channel The channel to use for the request (optional)
  * @returns Promise with the response data
  */
 export declare function getData(params: Partial<RequestParams>): Promise<any>;

package/dist/src/types/components/lib/charts.d.ts

@@ -0,0 +1,53 @@
+import { ChartDataPointType } from "@/types/charts";
+/**
+ * Formats a number for display in charts
+ * @param value The number to format
+ * @param prefix Optional prefix (e.g. '
+
+/**
+ * Transforms raw data for use in charts
+ * @param data Raw data array
+ * @param keyMap Mapping of source keys to destination keys
+ * @returns Transformed data array
+ */
+export declare const transformChartData: <T extends Record<string, any>>(data: T[], keyMap: Record<string, string>) => ChartDataPointType[];
+/**
+ * Groups data by a specified key and aggregates values
+ * @param data Array of data points
+ * @param groupByKey Key to group by
+ * @param valueKey Key containing values to aggregate
+ * @param aggregationType Type of aggregation to perform
+ * @returns Grouped and aggregated data
+ */
+export declare const groupAndAggregateData: <T extends Record<string, any>>(data: T[], groupByKey: string, valueKey: string, aggregationType?: "sum" | "avg" | "max" | "min") => ChartDataPointType[];
+/**
+ * Formats date values for chart display
+ * @param data Array of data points
+ * @param dateKey Key containing date values
+ * @param format Format to convert date to ('month', 'day', 'year', 'time', etc.)
+ * @returns Data with formatted date values
+ */
+export declare const formatDateForChart: <T extends Record<string, any>>(data: T[], dateKey: string, format?: "month" | "day" | "year" | "full" | "time" | "month-year") => T[];
+/**
+ * Creates a data series from a time range with optional default values
+ * @param startDate Start date of the range
+ * @param endDate End date of the range
+ * @param interval Time interval between points ('day', 'week', 'month', 'year')
+ * @param defaultValues Default values for each data point
+ * @returns Array of data points covering the time range
+ */
+export declare const createTimeSeriesTemplate: (startDate: Date, endDate: Date, interval: "day" | "week" | "month" | "year", defaultValues?: Record<string, any>) => ChartDataPointType[];
+export declare const formatChartValue: (value: number, prefix?: string, suffix?: string) => string;
+/**
+ * Calculates the percentage change between two values
+ * @param currentValue The current value
+ * @param previousValue The previous value to compare against
+ * @returns Percentage change as a number
+ */
+export declare const calculatePercentageChange: (currentValue: number, previousValue: number) => number;
+/**
+ * Generates colors from InstinctHub color palette
+ * @param count Number of colors needed
+ * @returns Array of color hex codes
+ */
+export declare const generateChartColors: (count: number) => string[];

package/dist/src/types/components/lib/helpFunction.d.ts

@@ -1,3 +1,4 @@
+import React from "react";
 export declare const IN_DEV_MODE: boolean;
 export declare const API_HOST_URL: string;
 export declare const FILE_URL: string;
@@ -74,6 +75,12 @@ export declare const extractSubDomain: (hostname: string) => SubDomainResult | n
  * @returns FormData object
  */
 export declare const convertArrayToFormData: (array: FormItem[]) => FormData;
+/**
+ * Checks if an object is empty
+ * @param obj Object to check
+ * @returns True if empty, false otherwise
+ */
+export declare const objectIsEmpty: (obj: any) => boolean;
 /**
  * Handles form validation errors.
  * @param e Event object from form input
@@ -101,6 +108,18 @@ export declare const convertToFloat: (value: string) => number;
  */
 export declare const formatNumberWithCommas: (number: number) => string;
 export declare const slugifyFileName: (fileName: string) => string;
+/**
+ * Converts a string to a URL-friendly slug format.
+ * @param value The string to convert to a slug
+ * @example
+ * ```ts
+ * const slug = convertToSlug("Hello World");
+ * console.log(slug); // "hello-world"
+ * ```
+ * @returns A lowercase string with spaces and special characters replaced by hyphens
+ * @throws Error if the resulting slug contains invalid characters
+ */
+export declare const convertToSlug: (value: string) => string;
 /**
  * Checks if an element is in the viewport.
  * @param element DOM element
@@ -183,26 +202,55 @@ export declare const printErr: (key: string, value: string, index: number) => vo
  * @param r_path Redirect path
  */
 export declare const handleError: (status: number, items: Record<string, string[]>, registerForm: HTMLFormElement | null, r_path: string | null) => void;
+/**
+ * Gets a value from an object using a path string (e.g., "course.title" or "course.lecturer.full_name")
+ * @param row The data object to extract value from
+ * @param accessor The path to the value (e.g., "course.title")
+ * @returns The value at the specified path or empty string if not found
+ */
+export declare function getNestedValue(row: any, accessor: string): any;
 /**
  * Creates request options for fetch API.
- * @param method HTTP method
- * @param data Request body
- * @param token Auth token
- * @param content_type Content type
- * @param channel Channel ID
- * @param auth_sk Use auth secret
+ * @param method HTTP method (GET, POST, PUT, DELETE)
+ * @param data Request body (BodyInit | FormData | null)
+ * @param token Auth token string or null
+ * @param content_type Content type (json, form-data, null, false)
+ * @param channel Channel ID string or null
+ * @param auth_sk Use auth secret boolean (true, false)
  * @returns Request options object
  */
 export declare const reqOptions: (method: string, data?: BodyInit | FormData | null, token?: string | null, content_type?: "json" | "form-data" | null | false, channel?: string | null, auth_sk?: boolean) => RequestOptions;
+/**
+ * Fetches paginated data from an API.
+ * @function
+ * @example
+ * ```ts
+ * fetchData(page, token, options, data, setData, setCount, setNext, setPrevious, setIsLoading, reset);
+ * ```
+ * @param page API endpoint
+ * @param token Auth token
+ * @param options Request options
+ * @param data Existing data
+ * @param setData Data setter
+ * @param setCount Count setter
+ * @param setNext Next page setter
+ * @param setPrevious Previous page setter
+ * @param setIsLoading Loading state setter
+ * @param reset Reset state
+ * @returns
+ * @see {@link FetchDataType}
+ */
+export declare const fetchData: (page: string, token: string | null, options: object, data: any[], setData: React.Dispatch<React.SetStateAction<any>>, setCount: React.Dispatch<React.SetStateAction<number>>, setNext: React.Dispatch<React.SetStateAction<string | null>>, setPrevious: React.Dispatch<React.SetStateAction<string | null>>, setIsLoading: React.Dispatch<React.SetStateAction<boolean>>, reset?: boolean) => Promise<void>;
 /**
  * Fetches data from an API with error handling.
  * @param session Callback or state setter
  * @param api API endpoint
  * @param reqOptions Request options
  * @param isFunctionComponent Is functional component
- * @param setStatus Status setter
- * @param setError Error setter
- * @param flag Handle status errors
+ * @param setIsLoading (optional) IsLoading state setter (boolean)
+ * @param setStatus (optional) Status setter (number | null)
+ * @param setError (optional) Error setter (any)
+ * @param flag (optional) Handle status errors (boolean)
  * @returns Promise with result or error
  */
 export declare const fetchAPI: <T>(session: {
@@ -211,7 +259,7 @@ export declare const fetchAPI: <T>(session: {
         status?: number | undefined;
         error?: any;
     }) => void;
-} | ((data: T) => void), api: string, reqOptions: RequestOptions, isFunctionComponent?: boolean, setStatus?: ((status: number | null) => void) | undefined, setError?: ((error: any) => void) | undefined, flag?: boolean) => Promise<T | Error>;
+} | ((data: T) => void), api: string, reqOptions: RequestOptions, isFunctionComponent?: boolean, setIsLoading?: ((loading: boolean) => void) | null | undefined, setStatus?: ((status: number | null) => void) | null | undefined, setError?: ((error: any) => void) | null | undefined, flag?: boolean) => Promise<T | Error>;
 /**
  * Handles HTTP status errors with navigation.
  * @param status HTTP status code

package/dist/src/types/components/lib/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./auth/actions";
 export * from "./auth/dbRequestst";
+export * from "./roles";
 export * from "./json/accounts";
 export * from "./json/countryNigeria";
 export * from "./json/countryObjects";
@@ -13,8 +14,14 @@ export * from "./formError";
 export * from "./getPriceObjects";
 export * from "./helpFunction";
 export * from "./loadScript";
-export * from "./modals";
 export * from "./oauth_json";
 export * from "./paystack";
 export * from "./permissions";
 export * from "./utils";
+export * from "./charts";
+export * from "./modals/modals";
+export * from "./modals/openConfirmDelete";
+export declare const instinctHubLogoUrl = "/assets/logo/instincthub-logo-color.png";
+export declare const instinctHubLogoUrlWhite = "/assets/logo/instincthub-logo-white.png";
+export declare const instinctHubLogoUrlBlack = "/assets/logo/instincthub-logo-black.png";
+export declare const instinctHubThumbnailLogo = "/assets/logo/instincthub-logo-thumbnail.png";

package/dist/src/types/components/lib/modals/openConfirmDelete.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Opens a confirmation modal for deleting an item
+ * @example
+ *
+ * const handleDelete = async (option) => {
+ *   const endpoint = `${API_HOST_URL}assessments/${handle}/assessment-link-tree-destroy/${option.id}/`;
+ *   const confirm = await openConfirmDelete(
+ *     option.title,
+ *     token,
+ *     endpoint,
+ *     true,
+ *     reqOptions,
+ *   );
+ *
+ *   if (confirm) {
+ *     // Update objects
+ *     const newObjects = data.filter((i) => i.id !== option.id);
+ *     setData(newObjects);
+ *   }
+ * };
+ *
+ * @property {string} message The name of the item to be deleted
+ * @property {string} token Authentication token for the API request
+ * @property {string} url API endpoint for deletion
+ * @property {boolean} pop Whether to show a popup confirmation (default: true)
+ * @returns Promise that resolves to boolean indicating success or failure
+ */
+export declare const openConfirmDelete: (message: string, token: string, url: string, pop?: boolean) => Promise<boolean>;

package/dist/src/types/components/lib/paystack.d.ts

@@ -1,58 +1,13 @@
-export interface PaystackMetadata {
-    channel_username?: string;
-    custom_fields?: Array<Record<string, any>>;
-    [key: string]: any;
-}
-export interface PaystackConfigObject {
-    authorization_code?: string;
-    email: string;
-    first_name: string;
-    last_name: string;
-    amount: number;
-    user_id?: string | number;
-    channel_id?: string | number;
-    content_type: string;
-    object_id: string | number;
-    metadata?: PaystackMetadata;
-}
-export interface PaystackConfig {
-    authorization_code?: string;
-    reference: string;
-    email: string;
-    first_name: string;
-    last_name: string;
-    amount: number;
-    publicKey: string | undefined;
-    key: string | undefined;
-    callback_url: string;
-    metadata?: PaystackMetadata;
-}
-export interface PaystackResponse {
-    status: string;
-    reference: string;
-    message?: string;
-    transaction?: string;
-    canceled?: boolean;
-    [key: string]: any;
-}
-export interface PaymentMethod {
-    authorization: {
-        authorization_code: string;
-        email: string;
-    };
-    card_type: string;
-    last4: string;
-}
+import { PaystackConfigObjectType, PaystackConfigType, PaystackResponseType, PaymentContextType } from "@/types";
 /**
  * Context for processing payments
  * @property {Event | null} [e] - The event object that triggered the payment
  * @property {Object} objects - Details about the item being purchased
  * @property {string} objects.title - Title of the item
- * @property {Object} [objects.object_type] - Type information for the item
- * @property {string} [objects.object_type.content_type] - Content type identifier
- * @property {string|number} [objects.object_id] - ID of the object being purchased
- * @property {PaystackConfigObject} configObj - Configuration for PayStack
- * @property {PaymentMethod} [paymentMethod] - Saved payment method if available
+ * @property {string | number | null} [objects.object_type] - Model ID of the object being purchased
+ * @property {string | number | null} [objects.object_id] - Object ID of the object being purchased
+ * @property {PaystackConfigObjectType} configObj - Configuration for PayStack
+ * @property {PaymentMethodType} [paymentMethod] - Saved payment method if available
  * @property {Function} setStatus - Function to update UI status during payment process
  * @property {Function} handleDBAction - Callback for processing successful payments
  * @property {boolean} [defaultConfirm] - Whether to show a confirmation dialog
@@ -61,49 +16,67 @@ export interface PaymentMethod {
  * @property {string} [defaultMsg] - Custom confirmation message
  * @property {number} [gatwayCharges] - Payment gateway charges percentage
  */
-export interface PaymentContext {
-    e?: Event | null;
-    objects: {
-        title: string;
-        object_type?: {
-            content_type: string;
-        };
-        object_id?: string | number;
-    };
-    configObj: PaystackConfigObject;
-    paymentMethod?: PaymentMethod;
-    setStatus: (status?: number) => void;
-    handleDBAction: (data?: any) => void;
-    defaultConfirm?: boolean;
-    label: string;
-    coupon?: string;
-    defaultMsg?: string;
-    gatwayCharges?: number;
-}
 /**
  * Configures the Paystack payment data for processing
  * @param obj - Object containing payment details
  * @returns PaystackConfig - Configured payment data
  */
-export declare const paystackDataConfig: (obj: PaystackConfigObject) => PaystackConfig;
+export declare const paystackDataConfig: (obj: PaystackConfigObjectType) => PaystackConfigType;
 /**
  * Charges a customer using an existing authorization
  * @param data - Payment configuration data
  * @returns Promise with transaction data
  */
-export declare const chargeAuthorization: (data: PaystackConfig) => Promise<any>;
+export declare const chargeAuthorization: (data: PaystackConfigType) => Promise<any>;
 /**
  * Initiates payment with Paystack popup
  * @param config - Payment configuration
  * @returns Promise with payment response
  */
-export declare const payWithPaystack: (config: PaystackConfig) => Promise<PaystackResponse>;
+export declare const payWithPaystack: (config: PaystackConfigType) => Promise<PaystackResponseType>;
 /**
  * Handles the complete payment submission process
+ * @example
+ * ```ts
+ * handlePaymentSubmit({
+ *   openConfirm: true,
+ *   defaultConfirm: true,
+ *   defaultMsg: "Are you sure you want to enroll for this course?",
+ *   label: "Course Name",
+ *   objects: {
+ *     object_id: "123",
+ *     object_type: "course",
+ *   },
+ *   configObj: {
+ *     email: "user@example.com",
+ *     amount: 1000,
+ *     currency: "NGN",
+ *     authorization_code: "1234567890",
+ *     first_name: "John",
+ *     last_name: "Doe",
+ *     email: "user@example.com",
+ *   },
+ *   coupon: "1234567890",
+ *   gatwayCharges: 10,
+ *   paymentMethod: {
+ *     authorization: {
+ *       card_type: "MasterCard",
+ *       last4: "1234",
+ *     },
+ *   },
+ *   handleDBAction: (data: any) => {
+ *     console.log(data);
+ *   },
+ *   setStatus: (status: number) => {
+ *     console.log(status);
+ *   },
+ *   e: Event,
+ * });
+ * ```
  * @param contexts - Payment context information
  * @context This function orchestrates the entire payment flow from confirmation to processing
  */
-export declare function handlePaymentSubmit(contexts: PaymentContext): Promise<void>;
+export declare function handlePaymentSubmit(contexts: PaymentContextType): Promise<void>;
 declare global {
     interface Window {
         PaystackPop: {