# @bigbinary/neeto-time-zones

![npm version](https://img.shields.io/npm/v/@bigbinary/neeto-time-zones.svg) ![license](https://img.shields.io/npm/l/@bigbinary/neeto-time-zones.svg)

A simple and lightweight NPM package for working with time zones. This package provides a human friendly timezone selector and utility functions for timezones.


## Installation

You can install the package using yarn:

```bash
yarn add @bigbinary/neeto-time-zones
```

## Importing CSS styles to the main stylesheet

You should add the following to `main.scss` file:

```css
@import "@bigbinary/neeto-time-zones/dist/style.css";
```

## NeetoTimezoneSelector

[Check out the live demo](https://codepen.io/Jijin-Haridas/full/wvQbeOr)

### Usage 1

```jsx
import { NeetoTimezoneSelector } from "@bigbinary/neeto-time-zones";

const ReactComponent = () => {
  const timezoneRef = useCallback(node => {
    if (!(node !== null)) return;

    new NeetoTimezoneSelector(node, {
      elementId: "custom-selector-element",
      className: "custom-selector-class",
      initialValue: "initial-timezone",
      position: "top",
      onChange: (timezone) => {
        console.log(timezone);
      },
      onHourFormatChange: (timeFormat) => {
        console.log(timeFormat);
      }
    });
  }, []);

  return (
    <div
      ref={timezoneRef}
    />
  );
};
```

### Usage 2

```jsx
import NeetoTimezoneSelector from "@bigbinary/neeto-time-zones/react";

const ReactComponent = () => {
  return (
    <NeetoTimezoneSelector
      elementId="custom-selector-element"
      className="custom-selector-class"
      initialValue="initial-timezone"
      position="top"
      onChange={(timezone) => {
        console.log(timezone);
      }}
      onHourFormatChange={(timeFormat) => {
        console.log(timeFormat);
      }}
    />
  );
}
```

### Configuration
You can pass options as the second parameter to configure the timezone selector component.

1. elementId: ID for the NeetoTimezoneSelector. By default the ID will be `timezone-selector`
2. className: Custom classes that can be added to the component.
3. initialValue: Initial Value of the timezone selector.
4. position: Position in which the selector should open in. Available options: `top`, `bottom`. Default position is `bottom`.
5. onChange: Function to be called when the timezone selector changes.
6. onHourFormatChange: Function to be called when the time format changes.
7. isTimeFormatSwitchVisible: Setting this to false will hide the time format toggle. The default value is true.
8. isTimeFormat24H: When the internal time format toggle is disabled, use this prop to pass the time format option. This will be used to change the time format inside the timezone selector.


### ianaTimezoneToHumanReadable

```js
import { ianaTimezoneToHumanReadable } from "@bigbinary/neeto-time-zones";

ianaTimezoneToHumanReadable("Asia/Calcutta") // => Indian Standard Time

ianaTimezoneToHumanReadable("America/New_York") // => Eastern Standard Time

ianaTimezoneToHumanReadable("Europe/Berlin") // => Central Standard Time
```

### Transliteration support

Timezone labels can be displayed in the user's browser language script (e.g., Hindi, Arabic, Japanese). This is **transliteration** — the English timezone names are written phonetically in the target script, not translated.

The picker widget automatically detects the browser locale via `navigator.language` and loads the appropriate transliteration file. No configuration is needed for the picker.

For consuming apps that use `ianaTimezoneToHumanReadable` directly (without rendering the picker), call `initTranslations()` once at app startup to pre-load the transliteration data:

```js
import { initTranslations } from "@bigbinary/neeto-time-zones";

// Call once at app startup (e.g., in your entry point)
initTranslations();

// After initTranslations resolves, ianaTimezoneToHumanReadable
// returns transliterated labels based on the browser locale.
ianaTimezoneToHumanReadable("Asia/Calcutta")
// => "इंडियन स्टैंडर्ड टाइम" (when browser locale is "hi")
// => "Indian Standard Time" (when browser locale is "en" or unsupported)
```

#### Supported locales (35)

ar, bg, ca, cs, da, de, es, es-MX, et, fi, fil, fr, he, hi, hr, hu, id, it, ja, ko, nl, pl, pt, pt-BR, ro, ru, sk, sl, sv, th, tr, uk, vi, zh-CN, zh-TW

Chinese locale variants are handled automatically:
- `zh-Hans-CN`, `zh-Hans`, `zh-SG`, `zh` → Simplified Chinese (`zh-CN`)
- `zh-Hant-TW`, `zh-Hant`, `zh-HK`, `zh-MO` → Traditional Chinese (`zh-TW`)

#### Adding a new locale

1. Create `data/translations/<locale>.json` with the required structure (see existing files for reference)
2. Copy the file to `ruby/data/translations/<locale>.json`
3. Add a `case "<locale>": return () => import("../../data/translations/<locale>.json");` entry in `js/translations/index.js`
4. Rebuild the package

### getTimezoneObject

```js
import { getTimezoneObject } from "@bigbinary/neeto-time-zones";

getTimezoneObject("Asia/Kolkata")
// => { utc: ["Asia/Kolkata", "Asia/Calcutta"], main: "Asia/Kolkata", label: "Indian Standard Time", ... }
```

### isValidTimezone

```js
import { isValidTimezone } from "@bigbinary/neeto-time-zones";

isValidTimezone("Asia/Kolkata") // => true
isValidTimezone("Invalid/Zone") // => false
```

### getBrowserTimezone

```js
import { getBrowserTimezone } from "@bigbinary/neeto-time-zones";

getBrowserTimezone() // => "Asia/Kolkata" (based on browser's Intl API)
```

## Development

### Clone the repo

```bash
git clone git@github.com:bigbinary/neeto-time-zones.git
cd neeto-time-zones/js
yarn install
yarn dev
```

To bundle with host app:

```bash
yarn build && cp dist/* ../../neeto-cal-web/node_modules/@bigbinary/neeto-time-zones/dist
```

## Instructions for Publishing

A package is released upon merging a PR labeled as patch, minor, or major into the main branch. The patch label addresses bug fixes, minor signifies the addition of new features, and major denotes breaking changes, adhering to the principles outlined in [Semantic Versioning (SemVer)](https://semver.org/).

You can checkout the Create and publish releases workflow in GitHub Actions to get a live update.