react-prayer-widget/dist/index.d.ts

Embeddable prayer times widget components for React applications

import * as react_jsx_runtime from 'react/jsx-runtime';
import react, { ReactNode } from 'react';
import { ClassValue } from 'clsx';

type Location = {
    latitude: number;
    longitude: number;
    city: string;
    country: string;
    countryCode?: string;
    cityCode?: string;
    timezoneName?: string;
};

type PrayerTimes = {
    fajr: string;
    sunrise: string;
    dhuhr: string;
    asr: string;
    maghrib: string;
    isha: string;
    date: string;
    hijri: string;
};
declare const PRAYER_NAMES: readonly ["Fajr", "Sunrise", "Dhuhr", "Asr", "Maghrib", "Isha"];
type PrayerName = (typeof PRAYER_NAMES)[number];
type CalculationMethodId = 1 | 2 | 3 | 4 | 5 | 7 | 8 | 9 | 10 | 11 | 12 | 13;
type AsrMethodId = 0 | 1;
type PrayerSettings = {
    calculationMethod: CalculationMethodId;
    asrMethod: AsrMethodId;
    fajrOffset: number;
    dhuhrOffset: number;
    asrOffset: number;
    maghribOffset: number;
    ishaOffset: number;
    applySummerHour?: boolean;
    forceHourMore?: boolean;
    forceHourLess?: boolean;
};
type ExtendedPrayerSettings = PrayerSettings & {
    timezone?: string;
    countryCode?: string;
    city?: string;
    cityCode?: string;
    showOtherPrayers?: boolean;
    showCity?: boolean;
    showTicker?: boolean;
    showDate?: boolean;
    horizontalView?: boolean;
    timeFormat24h?: boolean;
    dimPreviousPrayers?: boolean;
    language?: "en" | "ar";
    autoDetectTimezone?: boolean;
    showClock?: boolean;
    tickerIntervalMs?: number;
    /** Custom colors for prayer UI text */
    prayerNameColor?: string;
    prayerTimeColor?: string;
    prayerCountdownColor?: string;
    /** Enable azan playback at prayer times */
    azanEnabled?: boolean;
    /** When true, customize azan per prayer; otherwise use one global choice */
    azanPerPrayer?: boolean;
    /** Per-prayer azan selection id (default|short|fajr|beep|off|custom) */
    azanByPrayer?: Partial<Record<"Fajr" | "Dhuhr" | "Asr" | "Maghrib" | "Isha", string>>;
    /** Display names for custom uploaded files per prayer */
    azanCustomNames?: Partial<Record<"Fajr" | "Dhuhr" | "Asr" | "Maghrib" | "Isha", string>>;
    /** Global azan volume 0..1 */
    azanVolume?: number;
    /** Global azan choice id used when not customizing per prayer */
    azanGlobalChoice?: string;
    /** Global custom azan uploaded by user (name only; data stored in localStorage) */
    azanGlobalCustomName?: string;
    /** Toggle edit mode to drag-drop azan files over prayer cards */
    azanEditMode?: boolean;
    /** Visual size of the next (center) card */
    nextCardSize?: "xxs" | "xs" | "sm" | "md" | "lg";
    /** Visual size of the other prayer cards */
    otherCardSize?: "xxs" | "xs" | "sm" | "md" | "lg";
    /** Max width for the overall app/cards container */
    appWidth?: "xxs" | "xs" | "md" | "lg" | "xl" | "2xl" | "3xl";
    /** Error flag for location/permission issues */
    locationError?: string;
};

/** Props for the TopBar component */
type TopBarProps = {
    showDate?: boolean;
    showClock?: boolean;
    showCity?: boolean;
    currentTime: Date;
    location?: {
        city?: string | null;
        countryCode?: string | null;
        country?: string | null;
    };
    timeFormat24h?: boolean;
    language?: "en" | "ar";
    className?: string;
    classes?: {
        container?: string;
        date?: string;
        clock?: string;
        city?: string;
        cityIcon?: string;
    };
};
declare function TopBar({ showDate, showClock, showCity, currentTime, location, timeFormat24h, language, className, classes, }: TopBarProps): react_jsx_runtime.JSX.Element;

type AllSettings = ExtendedPrayerSettings;

type SettingsDialogProps = {
    settings: AllSettings;
    onSettingsChange: (settings: Partial<AllSettings>) => void;
    open?: boolean;
    onOpenChange?: (open: boolean) => void;
};

type IslamicContent = {
    id: string;
    type: "hadith" | "ayah";
    arabic?: string;
    english: string;
    source: string;
};

declare function SettingsDialog({ settings, onSettingsChange, open: controlledOpen, onOpenChange: controlledOnOpenChange, }: SettingsDialogProps): react_jsx_runtime.JSX.Element;

type WidgetSettingsContextProps = {
    children: ReactNode;
    settings: Parameters<typeof SettingsDialog>[0]["settings"];
    onSettingsChange: Parameters<typeof SettingsDialog>[0]["onSettingsChange"];
};
declare function WidgetSettingsContext({ children, settings, onSettingsChange, }: WidgetSettingsContextProps): react_jsx_runtime.JSX.Element;

type Language = "en" | "ar";

declare function countryToFlag(countryOrCode?: string): string;

declare module "country-region-data" {
	export type Region = {
		name: string;
		shortCode: string;
	};

	export type CountryRegion = {
		countryName: string;
		countryShortCode: string;
		regions: Region[];
	};

	export const allCountries: CountryRegion[];
}

type TranslationContextType = {
    t: (key: string) => string;
    language: Language;
};
type TranslationProviderProps = {
    children: ReactNode;
    language: Language;
};
declare function TranslationProvider({ children, language, }: TranslationProviderProps): react_jsx_runtime.JSX.Element;
declare function useTranslation(): TranslationContextType;

declare function formatTimeDisplay(time24h: string, use24Hour: boolean, locale?: "en" | "ar"): string;
declare function formatMinutesHHmm(totalMinutes: number): string;
declare function formatCurrentTime(date: Date, use24Hour: boolean, language?: "en" | "ar"): string;

declare function cn(...inputs: ClassValue[]): string;

type DualDateDisplayProps = {
    className?: string;
};
declare function DualDateDisplay({ className }: DualDateDisplayProps): react_jsx_runtime.JSX.Element | null;

/** Represents the next upcoming prayer */
type NextPrayer = {
    name: PrayerName;
    time: string;
    progress: number;
    timeUntil: number;
};
/** Props for the NextPrayerCard component */
type NextPrayerCardProps = {
    nextPrayer: NextPrayer;
    timeFormat24h?: boolean;
    language?: "en" | "ar";
    className?: string;
    size?: WidgetPrayerCardSize;
    nextSize?: WidgetPrayerCardSize;
    gradientClass?: string;
    showIcon?: boolean;
    classes?: {
        container?: string;
        icon?: string;
        name?: string;
        time?: string;
        countdown?: string;
        overlay?: string;
        progressFill?: string;
    };
    /** Optional max width for the rendered card container */
    maxWidth?: MaxWidth;
};
type MaxWidthToken = "md" | "lg" | "xl" | "2xl" | "3xl";
type MaxWidthKeyword = "fit-content" | "max-content" | "min-content" | "auto";
type MaxWidthCustom = `${number}${"px" | "rem" | "em" | "%" | "vw" | "vh" | "ch"}` | `calc(${string})` | `clamp(${string})` | `min(${string})` | `max(${string})` | `var(${string})`;
type MaxWidth = MaxWidthToken | MaxWidthKeyword | MaxWidthCustom | number;
declare function NextPrayerCard({ nextPrayer, timeFormat24h, language, className, size, nextSize, gradientClass, showIcon, classes, maxWidth, }: NextPrayerCardProps): react_jsx_runtime.JSX.Element;

type WidgetPrayerCardSize = "xxs" | "xs" | "sm" | "md" | "lg";
type WidgetPrayerCardProps = {
    name: PrayerName;
    time: string;
    /** IANA timezone to determine local weekday (for Friday/Jumuʿah handling) */
    timezone?: string;
    /** Optional explicit Friday override from parent */
    isFriday?: boolean;
    isNext?: boolean;
    isCurrent?: boolean;
    progress?: number;
    className?: string;
    countdown?: string;
    horizontalView?: boolean;
    /** Base size token applied to paddings and text sizes */
    size?: WidgetPrayerCardSize;
    /** Optional size override specifically for the next (central) card */
    nextSize?: WidgetPrayerCardSize;
    /** Override the gradient/background classes */
    gradientClass?: string;
    /** Hide the icon if false */
    showIcon?: boolean;
    /** Provide custom icon per prayer */
    getIcon?: (name: PrayerName) => react.ReactNode;
    /** Class overrides for fine-grained styling */
    classes?: {
        container?: string;
        icon?: string;
        name?: string;
        time?: string;
        countdown?: string;
        overlay?: string;
        progressFill?: string;
    };
    /** Inline style on the container */
    style?: react.CSSProperties;
    /** Optional drop handler for custom azan files */
    onDropFile?: (file: File) => void;
};
declare function WidgetPrayerCard(props: WidgetPrayerCardProps): react_jsx_runtime.JSX.Element;

type WidgetPrayerCardSkeletonProps = {
    variant: "next" | "grid";
    horizontalView?: boolean;
    className?: string;
    /** Match WidgetPrayerCard size tokens */
    size?: WidgetPrayerCardSize;
    /** Match WidgetPrayerCard nextSize tokens */
    nextSize?: WidgetPrayerCardSize;
};
declare function WidgetPrayerCardSkeleton({ variant, horizontalView, className, size, nextSize, }: WidgetPrayerCardSkeletonProps): react_jsx_runtime.JSX.Element;

/** Props for the PrayerGrid component */
type PrayerGridProps = {
    prayerTimes: PrayerTimes;
    currentOrNextName?: string;
    dimPreviousPrayers?: boolean;
    horizontalView?: boolean;
    timeFormat24h?: boolean;
    language?: "en" | "ar";
    /** IANA timezone for weekday handling (Friday/Jumuʿah) */
    timezone?: string;
    /** Explicit Friday flag from parent */
    isFriday?: boolean;
    className?: string;
    size?: WidgetPrayerCardSize;
    gradientClass?: string;
    showIcon?: boolean;
    classes?: {
        container?: string;
        icon?: string;
        name?: string;
        time?: string;
    };
    /** Optional max width for the rendered grid container */
    maxWidth?: "md" | "lg" | "xl" | "2xl" | "3xl" | number | string;
};
declare function PrayerGrid({ prayerTimes, currentOrNextName, dimPreviousPrayers, horizontalView, timeFormat24h, language, timezone, isFriday, className, size, gradientClass, showIcon, classes, maxWidth, }: PrayerGridProps): react_jsx_runtime.JSX.Element;

type MinimalTickerProps = {
    className?: string;
    prayerTimes?: PrayerTimes | null;
    intervalMs?: number;
    /** Override the content pool completely */
    contentPool?: IslamicContent[];
    /** Hide the source line if false */
    showSource?: boolean;
    /** Class overrides */
    classes?: {
        container?: string;
        text?: string;
        source?: string;
    };
};
declare function MinimalTicker({ className, prayerTimes, intervalMs, contentPool, showSource, classes, }: MinimalTickerProps): react_jsx_runtime.JSX.Element;

type ScrollingTickerProps = {
    className?: string;
    contentPool?: IslamicContent[];
    showArabicDefault?: boolean;
    speedDefault?: number;
    enabledDefault?: boolean;
};
declare function ScrollingTicker({ className, contentPool, showArabicDefault, speedDefault, enabledDefault, }: ScrollingTickerProps): react_jsx_runtime.JSX.Element | null;

export { type AsrMethodId, type CalculationMethodId, DualDateDisplay, type ExtendedPrayerSettings, type Language, type Location, MinimalTicker, type NextPrayer, NextPrayerCard, type NextPrayerCardProps, PrayerGrid, type PrayerGridProps, type PrayerName, type PrayerSettings, type PrayerTimes, ScrollingTicker, SettingsDialog, type SettingsDialogProps, TopBar, type TopBarProps, TranslationProvider, WidgetPrayerCard, type WidgetPrayerCardProps, type WidgetPrayerCardSize, WidgetPrayerCardSkeleton, WidgetSettingsContext, cn, countryToFlag, formatCurrentTime, formatMinutesHHmm, formatTimeDisplay, useTranslation };