@sacred-time/web

Web plugin for easily integrating Islamic calendar dates into websites. Automatically detects user location and displays accurate dates based on sunset times.

Features

• 🌍 Automatic Location Detection: Uses browser geolocation API with IP fallback
• ⏰ Real-time Updates: Automatically updates when date changes at sunset
• 📱 Responsive Design: Works on all screen sizes
• 🎨 Customizable Styling: Easy to customize with CSS
• ⚛️ React Support: React component included
• 🔌 Easy Integration: Works with vanilla JS, React, or any framework

Installation

NPM

npm install @sacred-time/web

CDN (Coming Soon)

<script src="https://cdn.jsdelivr.net/npm/@sacred-time/web/dist/index.umd.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@sacred-time/web/dist/styles.css">

Usage

Vanilla JavaScript

Basic Usage

<div id="sacred-time-widget"></div>

<script src="path/to/sacred-time.umd.js"></script>
<script>
  SacredTime.initSacredTime({
    target: 'sacred-time-widget',
    autoDetectLocation: true
  });
</script>

With Custom Location

SacredTime.initSacredTime({
  target: 'sacred-time-widget',
  location: {
    latitude: 24.7136,
    longitude: 46.6753
  },
  autoDetectLocation: false
});

With Backend Integration

SacredTime.initSacredTime({
  target: 'sacred-time-widget',
  backendUrl: 'https://api.example.com',
  autoDetectLocation: true,
  onDateChange: (date) => {
    console.log('Date changed:', date);
  }
});

React

import { SacredTimeWidget } from '@sacred-time/web';

function App() {
  return (
    <SacredTimeWidget
      autoDetectLocation={true}
      onDateChange={(date) => console.log('Date:', date)}
    />
  );
}

React with Custom Props

import { SacredTimeWidget } from '@sacred-time/web';

function App() {
  return (
    <SacredTimeWidget
      location={{ latitude: 24.7136, longitude: 46.6753 }}
      backendUrl="https://api.example.com"
      updateInterval={30000} // Update every 30 seconds
      format={{
        showMonthName: true,
        showYear: true
      }}
      className="my-custom-class"
      onDateChange={(date) => {
        // Handle date change
      }}
      onLocationDetected={(location) => {
        console.log('Location:', location);
      }}
      onError={(error) => {
        console.error('Error:', error);
      }}
    />
  );
}

Programmatic API

import { SacredTimePlugin } from '@sacred-time/web';

const plugin = new SacredTimePlugin({
  target: 'my-widget',
  autoDetectLocation: true
});

await plugin.init();

// Get current date
const date = plugin.getCurrentDate();
console.log(date);

// Update location manually
await plugin.updateLocation({
  latitude: 24.7136,
  longitude: 46.6753
});

// Stop auto-updates
plugin.stop();

Configuration Options

WebPluginConfig

| Option | Type | Default | Description | |--------|------|---------|-------------| | target | string \| HTMLElement | 'sacred-time-widget' | Target element ID or element | | location | Location | Auto-detected | User's location | | backendUrl | string | undefined | Backend API URL for moon sightings | | updateInterval | number | 60000 | Update interval in milliseconds | | format | object | See below | Display format options | | classPrefix | string | 'sacred-time' | CSS class prefix | | autoDetectLocation | boolean | true | Auto-detect user location | | onDateChange | function | undefined | Callback when date changes | | onLocationDetected | function | undefined | Callback when location detected | | onError | function | undefined | Callback on error |

Format Options

format: {
  showMonthName?: boolean;  // Default: true
  showYear?: boolean;      // Default: true
  customFormat?: (date: { year: number; month: number; day: number }) => string;
}

Styling

The widget comes with default styles, but you can customize them:

/* Override default styles */
.sacred-time__container {
  background: your-color;
  border-radius: your-radius;
}

.sacred-time__day {
  font-size: your-size;
  color: your-color;
}

Theme Variants

Add these classes to your target element:

• sacred-time--dark: Dark theme
• sacred-time--light: Light theme
• sacred-time--minimal: Minimal styling

<div id="sacred-time-widget" class="sacred-time--dark"></div>

Location Detection

The plugin tries to detect location in this order:

1. Browser Geolocation API: Most accurate, requires user permission
2. IP-based Detection: Fallback using IP geolocation service
3. Default Location: Falls back to Makkah (21.3891, 39.8579) if all else fails

Browser Support

• Chrome/Edge: ✅ Full support
• Firefox: ✅ Full support
• Safari: ✅ Full support
• IE11: ❌ Not supported (use polyfills if needed)

Examples

See the examples/ directory for:

• vanilla.html - Vanilla JavaScript example
• react-example.tsx - React component example

License

MIT