From e2e8045cc7b1d7e11c2d02272f1f84272302ca1f Mon Sep 17 00:00:00 2001 From: gimy Date: Wed, 4 Oct 2023 07:23:43 +0800 Subject: [PATCH] docs: added formatter config page --- README.md | 6 ++-- docs/config/config.md | 62 +++++++++++++++++------------------ docs/config/formatter.md | 60 +++++++++++++++++++++++++++++++-- docs/guide/getting-started.md | 2 +- docs/index.md | 2 +- 5 files changed, 94 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 39991ed..b78501b 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ -# Prayes-call +# Prayers-call -Reactive prayer times calculation library for node and the browser built with Typescript. +A TypeScript library for calculating Islamic prayer times, built with reactivity in mind. Compatible with both Node.js and the browser. + +For insights into the motivation and features of this project, visit the [Why prayers-call](https://prayers-ts.netlify.app/guide/introduction.html#why-this-library) section. [![npm version](https://badge.fury.io/js/prayers-call.svg)](https://badge.fury.io/js/prayers-call) diff --git a/docs/config/config.md b/docs/config/config.md index fbbcb3a..be61b7c 100644 --- a/docs/config/config.md +++ b/docs/config/config.md @@ -4,55 +4,55 @@ The `StaticCalculator` and the `ReactiveCalculator` class in `prayers-call` both ### date (`StaticCalculator` only) -- Required: `true` -- Type: `Date` +- **Required:** `true` +- **Type:** `Date` The date for which the prayer times will be calculated it can be past current or future. This property is specific to `StaticCalculator`. ### latitude and longitude -- Required: `true` -- Type: `number` +- **Required:** `true` +- **Type:** `number` The geographical coordinates of the location for which the prayer times will be calculated. ### method -- Required: `false` -- Type: `Methods | CustomMethod` -- Default: `Methods.UMM_AL_QURA` +- **Required:** `false` +- **Type:** `Methods | CustomMethod` +- **Default:** `Methods.UMM_AL_QURA` The calculation method to use. You can use one of the built-in methods or provide a custom method. for a comprehensive guide of available methods, see [Calculation Methods](./methods.md). ### adjustments -- Required: `false` -- Type: `Partial` -- Default: `{ fajr: 0, sunrise: 0, dhuhr: 0, asr: 0, maghrib: 0, isha: 0 }` +- **Required:** `false` +- **Type:** `Partial` +- **Default:** `{ fajr: 0, sunrise: 0, dhuhr: 0, asr: 0, maghrib: 0, isha: 0 }` Custom adjustments in minutes for each prayer time. ### asrTime -- Required: `false` -- Type: `AsrTime` -- Default: `AsrTime.JUMHOOR` +- **Required:** `false` +- **Type:** `AsrTime` +- **Default:** `AsrTime.JUMHOOR` Whether to use the earlier (Jumhoor) or later (Hanafi) Asr time calculation. ### iqama -- Required: `false` -- Type: `Partial` -- Default: `{ fajr: 20, dhuhr: 10, asr: 10, maghrib: 5, isha: 15 }` +- **Required:** `false` +- **Type:** `Partial` +- **Default:** `{ fajr: 20, dhuhr: 10, asr: 10, maghrib: 5, isha: 15 }` Waiting time in minutes for iqama after the actual prayer time. ### adjustForRamadan -- Required: `false` -- Type: `boolean` -- Default: `false` +- **Required:** `false` +- **Type:** `boolean` +- **Default:** `false` Whether to adjust the prayer times for Ramadan by adding 30 minutes to Isha. @@ -62,33 +62,33 @@ When using `UMM_AL_QURA` method `prayer-calls` will automatically adjust the pra ### hijriCalendar -- Required: `false` -- Type: `HijriCalendar` -- Default: `HijriCalendar.UMM_AL_QURA` +- **Required:** `false` +- **Type:** `HijriCalendar` +- **Default:** `HijriCalendar.UMM_AL_QURA` The Hijri calendar to use in conjunction with `adjustForRamadan` to determine the start and end of Ramadan. for a comprehensive list of available calendars, see [HijriCalendar](../api.md#HijriCalendar). ### highLatitudeRule -- Required: `false` -- Type: `ValueOf` -- Default: `HighLatitudeRule.MiddleOfTheNight` +- **Required:** `false` +- **Type:** `ValueOf` +- **Default:** `HighLatitudeRule.MiddleOfTheNight` Rule to use for calculating prayer times at high latitudes. See the [Advanced section](#advanced-configuration) for more details. ### polarCircleResolution -- Required: `false` -- Type: `ValueOf` -- Default: `PolarCircleResolution.Unresolved` +- **Required:** `false` +- **Type:** `ValueOf` +- **Default:** `PolarCircleResolution.Unresolved` How to handle Midnight Sun & Polar Night days. See the [Advanced section](#advanced-configuration) for more details. ### debug (`ReactiveCalculator` only) -- Required: `false` -- Type: `boolean` -- Default: `false` +- **Required:** `false` +- **Type:** `boolean` +- **Default:** `false` Enable debugging logs for the `ReactiveCalculator`. diff --git a/docs/config/formatter.md b/docs/config/formatter.md index 465c9ce..0ffd2d5 100644 --- a/docs/config/formatter.md +++ b/docs/config/formatter.md @@ -1,7 +1,61 @@ # Formatter Config -WIP +The `Formatter` class in `prayers-call` allows you to format dates and times, including Islamic (Hijri) dates. It uses a configuration object that can be passed to its constructor. This page will guide you through the available configuration options. - +## `locale` - +- **Required**: `false` +- **Type**: `string | string[]` +- **Default**: `'en-US'` + +The locale determines the language and formatting conventions to be used. For example, using `'en-US'` will format the date in the United States' customary style, while `'en-GB'` will use the United Kingdom's style. + +For a comprehensive list of available locales, see [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat). + +## `Intl.DateTimeFormatOptions` + +The `FormatterConfig` object extends the `Intl.DateTimeFormatOptions`, you can use any of the properties available in in JavaScript's `Intl.DateTimeFormatOptions` to fine-tune your date and time formatting. + +- **Required:** `false` + +### Options include: + +```ts +{ + weekday: 'narrow' | 'short' | 'long', + era: 'narrow' | 'short' | 'long', + year: 'numeric' | '2-digit', + month: 'numeric' | '2-digit' | 'narrow' | 'short' | 'long', + day: 'numeric' | '2-digit', + hour: 'numeric' | '2-digit', + minute: 'numeric' | '2-digit', + second: 'numeric' | '2-digit', + timeZoneName: 'short' | 'long', + calendar: 'gregory' | 'islamic' | 'iso8601' // and more + timeZone: 'Asia/Shanghai', + hour12: true | false, + hourCycle: 'h11' | 'h12' | 'h23' | 'h24', + formatMatcher: 'basic' | 'best fit' +} +``` + +For a complete list of options, refer to the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat). + +## Example Usage + +Here's an example that includes multiple configuration options: + +```ts +import { Formatter } from 'prayers-call' + +const formatter = new Formatter({ + locale: 'en-GB', + weekday: 'long', + year: 'numeric', + month: 'long', + day: 'numeric', +}) + +const date = new Date(2022, 1, 1) +console.log(formatter.formatDate(date)) // Outputs: 'Saturday, 1 February 2022' +``` diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md index bed390c..64d97fd 100644 --- a/docs/guide/getting-started.md +++ b/docs/guide/getting-started.md @@ -2,7 +2,7 @@ ## Overview -`prayers-call` is a TypeScript library designed for calculating Islamic prayer times. It's engineered to be reactive and is compatible with both Node.js and browser environments. +`prayers-call` is a TypeScript library for calculating Islamic prayer times, built with reactivity in mind it's compatible with both Node.js and browser environments. For insights into the motivation and features of this project, visit the [Why prayers-call](./introduction.md#why-this-library) section. diff --git a/docs/index.md b/docs/index.md index 4216f6c..b9e7ed5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,7 +2,7 @@ layout: home title: prayers-call -titleTemplate: Reactive Prayer Times Calculator +titleTemplate: A Reactive Prayer Times Calculator hero: name: Prayers-Call