nepali_kit

A production-quality, all-in-one Nepali calendar, localization, and UI toolkit for Dart and Flutter.

---

🌐 Website

Visit https://nepalikit.tech for the Nepali calendar, date conversion, tithi, festivals, holidays and other Nepali utilities.

---

Package Introduction

nepali_kit provides an enterprise-ready suite of utilities for building Nepali applications in Dart and Flutter. It provides high-speed Bikram Sambat (BS) calendar calculations, verified bidirectional BS ↔ AD date conversions, pattern-based date formatting, South Asian number & currency systems, number-to-words conversions, official fiscal year calculations, public holidays datasets, and Flutter Material 3 calendar and date picker widgets.

---

Screenshots & Visual Showcase

Bikram Sambat Calendar	Dual BS + AD Calendar	Material 3 Date Picker

Date Range Picker	Bidirectional Conversion	Custom Day Rendering

Events & Holidays	Fiscal Year & Quarters	Numbers & Unicode Utilities

---

Why this package?

In the Dart & Flutter ecosystem, building a Nepali app typically requires stitching together 4 to 6 disparate packages:

• One package for basic BS date calculations,
• Another for number/Devanagari formatting,
• Another for fiscal year math,
• Another for holiday listings,
• And yet another for Flutter calendar UI or date pickers.

This fragmentation leads to:

1. Conflicting types (e.g. incompatible NepaliDateTime models across libraries),
2. Inconsistent calendar tables (subtle discrepancies between day counts across years),
3. Timezone bugs (hidden UTC/local conversion side-effects altering days),
4. Maintenance debt and dependency hell.

nepali_kit solves this once and for all. It offers a single, cohesive, thoroughly tested foundation with zero external dependencies in its pure Dart core.

---

Features

• Calendar Engine: Immutable NepaliDate (date-only) and NepaliDateTime (date + time) with equality, comparisons, date ranges, and arithmetic.
• Date Conversion: Verified bidirectional conversion ($\text{BS} \leftrightarrow \text{AD}$) with round-trip invariance across 1975 BS to 2099 BS.
• Formatting & Parsing: ICU-style format tokens (yyyy, MMMM, dd, EEEE, hh:mm a) supporting English and Nepali Devanagari locales, plus dual date formatting.
• Numbers: South Asian comma grouping (12,34,567.89) and conversion between ASCII digits (0-9) and Devanagari numerals (०-९).
• Currency: Currency formatting with custom or localized currency symbols (रु 12,34,567.89 / Rs. 12,34,567.89).
• Unicode/Text (Number to Words): Conversion of numeric amounts into spoken words in both Nepali (एक लाख तेइस हजार) and English up to Kharba and Arab.
• Relative Time (Nepali Moments): Human-friendly relative time strings ("भर्खरै", "५ मिनेट अगाडि", "हिजो", "भोलि") in Nepali and English.
• Fiscal Year: Accurate Nepali government fiscal year (NepaliFiscalYear) starting Shrawan 1 and ending Ashadh end, with automatic Q1–Q4 breakdowns.
• Holidays: Built-in national gazetted holidays database for standard years with full support for custom corporate/organization holiday providers.
• Flutter Calendar: Customizable Material 3 NepaliCalendarView and ADCalendarView with multi-event dots, custom builders, and theme support.
• Date Pickers: showNepaliDatePicker, showNepaliDateRangePicker, NepaliMonthPicker, and NepaliYearPicker.
• Calendar Events: Decoupled CalendarEvent model with category support, custom metadata, and multi-event day indicators.

---

Installation

Add nepali_kit to your pubspec.yaml:

dependencies:
  nepali_kit: "<latest_release>"

Pure Dart (Backend / CLI / Scripts)

For servers (Dart Frog, Serverpod), scripts, or CLI apps with zero Flutter dependencies:

import 'package:nepali_kit/nepali_kit_core.dart';

Flutter Applications

For Flutter apps requiring UI widgets, calendar pickers, and themes:

import 'package:nepali_kit/nepali_kit.dart';

---

Quick Start

import 'package:nepali_kit/nepali_kit.dart';

void main() {
  // Current Bikram Sambat date
  final today = NepaliDate.now();
  print('Today in BS: $today'); // e.g. 2081-06-13

  // Format with Nepali locale
  final formatted = NepaliDateFormat('EEEE, MMMM d, yyyy', Language.nepali).format(today);
  print('Formatted: $formatted'); // e.g. आइतबार, आश्विन १३, २०८१

  // Numbers to words
  final words = NepaliNumberToWords.convert(125000, language: Language.nepali);
  print('In words: $words'); // एक लाख पच्चीस हजार
}

---

BS ↔ AD Examples

Convert seamlessly between Bikram Sambat and Gregorian calendars:

import 'package:nepali_kit/nepali_kit_core.dart';

// BS to AD
final bsDate = NepaliDate(2081, 6, 13);
final adDateTime = bsDate.toDateTime(); // 2024-09-29 00:00:00.000

// AD to BS
final gregorian = DateTime(2024, 9, 29);
final convertedBs = NepaliDate.fromDateTime(gregorian); // 2081-06-13

// Direct low-level converter
final (year, month, day) = BsAdConverter.bsToAd(2081, 6, 13);
final (bsY, bsM, bsD) = BsAdConverter.adToBs(year, month, day);

// Fluent DateTime extension
final bsFromExt = DateTime(2024, 9, 29).toNepaliDate();

---

NepaliDate Examples

Construction & Validation

// Valid date
final date = NepaliDate(2081, 6, 13);

// Today
final now = NepaliDate.now();

// Properties
print(date.year); // 2081
print(date.month); // 6
print(date.day); // 13
print(date.weekday); // 1 (Sunday / आइतबार)
print(date.monthNameNepali); // आश्विन
print(date.daysInMonth); // 30
print(date.isLeapYear); // false
print(date.startOfMonth); // 2081-06-01
print(date.endOfMonth); // 2081-06-30

Date Arithmetic

final start = NepaliDate(2081, 3, 32); // Ashadh 32

// Adding days
final after10Days = start.addDays(10); // 2081-04-10 (handles month rollover)

// Month rollover with day-clamping
final nextMonth = start.addMonths(1); // Clamps to max days of Shrawan

// Year rollover
final nextYear = start.addYears(1); // 2082-03-31 (or 32 depending on year data)

// Difference between dates
final daysBetween = after10Days.differenceInDays(start); // 10

Comparisons & Ranges

final d1 = NepaliDate(2081, 1, 1);
final d2 = NepaliDate(2081, 1, 15);

print(d1 < d2); // true
print(d1.isBefore(d2)); // true

// Date ranges
final range = NepaliDateRange(start: d1, end: d2);
print(range.durationInDays); // 14
print(range.days.length); // 15 dates

---

Formatting Examples

Use NepaliDateFormat with standard pattern tokens across English and Nepali locales:

final dt = NepaliDateTime(2081, 6, 13, 15, 30, 45);

// English locale
final enFormat = NepaliDateFormat('yyyy-MM-dd HH:mm', Language.english);
print(enFormat.format(dt)); // 2081-06-13 15:30

// Nepali Devanagari locale
final npFormat = NepaliDateFormat('EEEE, MMMM dd, yyyy', Language.nepali);
print(npFormat.format(dt)); // आइतबार, आश्विन १३, २०८१

// Dual date formatting (BS + AD together)
final dual = NepaliDateFormat.formatDual(dt, language: Language.nepali);
print(dual); // "२०८१ आश्विन १३ (2024-09-29)"

Supported Pattern Tokens

Token	Description	Output (English)	Output (Nepali)
yyyy	4-digit Year	2081	२०८१
yy	2-digit Year	81	८१
MMMM	Full Month Name	Ashwin	आश्विन
MMM	Short Month Name	Ashw	आ
MM	2-digit Month	06	०६
M	1-digit Month	6	६
dd	2-digit Day	13	१३
d	1-digit Day	13	१३
EEEE	Full Weekday	Sunday	आइतबार
EEE	Short Weekday	Sun	आइत
HH	24-Hour (00–23)	15	१५
hh	12-Hour (01–12)	03	०३
mm	Minute (00–59)	30	३०
ss	Second (00–59)	45	४५
a	AM / PM marker	PM	अपराह्न

---

Number Examples

Grouping and Digits

Format numbers with South Asian grouping (last 3 digits, then groups of 2 digits):

import 'package:nepali_kit/nepali_kit_core.dart';

// South Asian comma grouping (English numerals)
NepaliNumberFormat.format(1234567.89); // "12,34,567.89"

// South Asian comma grouping (Devanagari numerals)
NepaliNumberFormat.format(1234567.89, language: Language.nepali); // "१२,३४,५६७.८९"

// Digit conversion
NepaliDigits.toNepali(2081); // "२०८१"
NepaliDigits.toEnglish('२०८१'); // "2081"

Numbers to Words

Convert numbers to spoken words up to Kharba and Arab:

// Nepali words
NepaliNumberToWords.convert(123456, language: Language.nepali);
// "एक लाख तेइस हजार चार सय छपन्न"

// English words
NepaliNumberToWords.convert(123456, language: Language.english);
// "One Lakh Twenty Three Thousand Four Hundred Fifty Six"

// Decimals and negatives
NepaliNumberToWords.convert(-50.75, language: Language.nepali);
// "ऋण पचास दशमलव सात पाँच"

---

Currency Examples

Format monetary amounts with standard symbols:

// Nepali currency format
NepaliNumberFormat.currency(52450.50, language: Language.nepali);
// "रु ५२,४५०.५०"

// English currency format
NepaliNumberFormat.currency(52450.50, language: Language.english);
// "Rs. 52,450.50"

// Custom currency symbol
NepaliNumberFormat.currency(52450, customSymbol: 'NPR');
// "NPR ५२,४५०"

---

Fiscal Year Examples

Nepal's fiscal year runs from Shrawan 1 to Ashadh end (mid-July to mid-July):

import 'package:nepali_kit/nepali_kit_core.dart';

// Fiscal year from date
final date = NepaliDate(2081, 6, 13);
final fy = NepaliFiscalYear.fromDate(date);

print(fy.label); // "2081/82"
print(fy.shortLabel); // "81/82"
print(fy.startDate); // 2081-04-01 (Shrawan 1)
print(fy.endDate); // 2082-03-31 (Ashadh end)

// Fiscal Quarters
final quarter = fy.quarterForDate(date);
print(quarter.quarter); // FiscalQuarter.first (Q1: Shrawan - Ashwin)
print(quarter.startDate); // 2081-04-01
print(quarter.endDate); // 2081-06-30

---

Holiday Examples

Query national gazetted holidays or inject custom organization holidays:

import 'package:nepali_kit/nepali_kit_core.dart';

// Check if a date is a public holiday
final date = NepaliDate(2081, 1, 1);
if (HolidayService.isHoliday(date)) {
  final holidays = HolidayService.holidaysOn(date);
  for (final h in holidays) {
    print('${h.nameNepali} (${h.nameEnglish}) - Public: ${h.isPublic}');
  }
}

// Custom holiday provider for companies or schools
HolidayService.registerProvider(CustomHolidayProvider([
  NepaliHoliday(
    date: NepaliDate(2081, 5, 20),
    nameNepali: 'कम्पनी स्थापना दिवस',
    nameEnglish: 'Company Foundation Day',
    isPublic: true,
  ),
]));

// Reset back to official national holidays
HolidayService.reset();

---

Calendar Examples

Embed interactive BS or AD calendars into your Flutter widgets:

import 'package:flutter/material.dart';
import 'package:nepali_kit/nepali_kit.dart';

class CalendarDemo extends StatefulWidget {
  @override
  State<CalendarDemo> createState() => _CalendarDemoState();
}

class _CalendarDemoState extends State<CalendarDemo> {
  NepaliDate _selectedDate = NepaliDate.now();

  @override
  Widget build(BuildContext context) {
    return NepaliCalendarView(
      initialDate: _selectedDate,
      selectedDate: _selectedDate,
      language: Language.nepali,
      onDateSelected: (date) {
        setState(() => _selectedDate = date);
      },
      events: [
        CalendarEvent(
          date: NepaliDate(2081, 6, 15),
          title: 'Project Deadline',
          category: 'work',
        ),
      ],
    );
  }
}

---

Date Picker Examples

Open a familiar Material 3 modal date picker adapted for Bikram Sambat:

final picked = await showNepaliDatePicker(
  context: context,
  initialDate: NepaliDate.now(),
  firstDate: NepaliDate(2070, 1, 1),
  lastDate: NepaliDate(2090, 12, 30),
  language: Language.nepali,
  confirmText: 'छान्नुहोस्',
  cancelText: 'रद्द गर्नुहोस्',
);

if (picked != null) {
  print('Selected BS date: $picked');
}

---

Range Picker Examples

Allow users to select an inclusive date span:

final pickedRange = await showNepaliDateRangePicker(
  context: context,
  firstDate: NepaliDate(2075, 1, 1),
  lastDate: NepaliDate(2085, 12, 30),
  language: Language.nepali,
);

if (pickedRange != null) {
  print('Range start: ${pickedRange.start}');
  print('Range end: ${pickedRange.end}');
  print('Total days: ${pickedRange.durationInDays}');
}

---

Events

Manage calendar events and render multi-indicator badges:

final eventList = [
  CalendarEvent(
    date: NepaliDate(2081, 7, 15),
    title: 'Laxmi Puja',
    color: Colors.amber,
  ),
  CalendarEvent(
    date: NepaliDate(2081, 7, 15),
    title: 'Family Gathering',
    color: Colors.purple,
  ),
];

final collection = CalendarEventCollection(eventList);
print(collection.hasEvents(NepaliDate(2081, 7, 15))); // true
print(collection.eventsForDate(NepaliDate(2081, 7, 15)).length); // 2

---

Romanized Nepali → Unicode Transliteration

Convert English literal phonetic Romanized Nepali into clean Devanagari Unicode using NepaliUnicode:

Basic Conversion

import 'package:nepali_kit/nepali_kit.dart';

// Greetings & conversation
final greeting = NepaliUnicode.convert(
  "namaste, tpaaii'laaii kasto chha?",
);
print(greeting);
// नमस्ते, तपाईंलाई कस्तो छ?

// Everyday sentences
final sentence = NepaliUnicode.convert(
  "mero naam Bikash ho, ma nepaalmaa baschhu.",
);
print(sentence);
// मेरो नाम् बिकश् हो, म नेपाल्मा बस्छु.

Live (Type-as-you-write) Conversion

For interactive input fields, set live: true to prevent premature character locking while the user continues typing:

TextField(
  onChanged: (text) {
    final liveNepali = NepaliUnicode.convert(
      text,
      live: true,
    );
    print(liveNepali);
  },
);

As the user types incrementally:

• m → म्
• ma → म
• maa → मा
• maala → माल
• maalaa → माला

Notation Reference

• Vowels: a (अ), A / aa (आ), i (इ), I / ii (ई), u (उ), U / uu (ऊ), e (ए), E / ai (ऐ), o (ओ), au (औ)
• Special Marks: ' (Anusvara ं), '' (Chandrabindu ँ), : (Visarga ः), | (Danda ।), || (Double Danda ॥), om / Om (ॐ)
• Consonant aspirated forms: kh (ख्), gh (घ्), ch (छ्), jh (झ्), th (थ्), dh (ध्), ph/f (फ्), bh (भ्), sh (श्)
• Retroflex consonants: T (ट्), Th (ठ्), D (ड्), Dh (ढ्), N (ण्), S (ष्)
• Digits: 0-9 automatically map to ०-९
• Non-Nepali Content Preservation: URLs (https://...), email addresses ([e-mail]), and already-Devanagari Unicode characters are detected and preserved without corruption.

---

Localization

nepali_kit provides first-class support for both English (Language.english) and Nepali (Language.nepali). All UI components, date pickers, month names, weekday labels, and number formatters accept a Language parameter.

// Relative time in Nepali
final past = NepaliDate.now().subtractDays(2);
print(NepaliMoment.fromNepaliDate(past, language: Language.nepali)); // "२ दिन अगाडि"

// Relative time in English
print(NepaliMoment.fromNepaliDate(past, language: Language.english)); // "2 days ago"

---

Architecture

nepali_kit enforces a strict architectural boundary between pure Dart logic and Flutter UI widgets:

nepali_kit/
├── lib/
│   ├── nepali_kit_core.dart       <-- Pure Dart entry point (zero Flutter dependencies)
│   │   ├── src/calendar/          (NepaliDate, NepaliDateTime, ranges, months)
│   │   ├── src/conversion/        (BS <-> AD conversion lookup table engine)
│   │   ├── src/formatting/        (NepaliDateFormat, token parser)
│   │   ├── src/numbers/           (NepaliDigits, NepaliNumberFormat, NumberToWords)
│   │   ├── src/fiscal/            (NepaliFiscalYear, quarters)
│   │   ├── src/holidays/          (Holiday models, datasets, service)
│   │   ├── src/relative_time/     (NepaliMoment)
│   │   ├── src/events/            (CalendarEvent model)
│   │   ├── src/text/              (NepaliUnicode transliteration engine)
│   │   └── src/core/              (Exceptions, constants, Language enum)
│   │
│   └── nepali_kit.dart            <-- Unified entry point for Flutter apps
│       └── src/flutter/           (NepaliCalendarView, pickers, dialogs, themes)

• Backend / CLI safe: nepali_kit_core.dart has zero Flutter imports and compiles seamlessly on Serverpod, Dart Frog, or command-line scripts.
• Pure-Dart testability: Core calendar algorithms are verified through pure-Dart unit tests independently of the Flutter engine.

---

Supported Date Range

Calendar	Minimum Date	Maximum Date
Bikram Sambat (BS)	2000-01-01 BS (or 1975-01-01 BS in verified table)	2099-12-30 BS
Gregorian (AD)	1918-04-13 AD	2043-04-13 AD

• Verified calendar tables guarantee exact month lengths matching official Nepalese Patro records across all 125 supported years.
• Attempting to construct a NepaliDate outside this range throws a descriptive NepaliDateException.

---

Limitations

• Astronomical Predictions beyond 2099 BS: Because the Bikram Sambat calendar is governed by solar-lunar astronomical positions published annually by Nepal's Panchanga Nirnayak Samiti, years beyond 2099 BS are not pre-calculated to prevent historical drift.
• Tithi Calculations: Lunar Tithis (such as Ekadashi, Purnima, Amavasya) depend on precise planetary coordinates at specific longitudes and are not included in this calendar engine.

---

Examples

A comprehensive Flutter example application is included in the example/ directory demonstrating:

1. Pure BS calendar with day selection,
2. Dual BS + AD calendar,
3. Multi-event indicators,
4. Material 3 modal date picker and range picker,
5. Dark theme and localization switching.

To run the example app:

cd example
flutter run

---

Testing

The package includes an extensive test suite verifying mathematical invariants, boundary conditions, and UI interactions:

# Run pure Dart and widget tests
flutter test

# Run static analysis
flutter analyze

Release Process

1. Update the version in pubspec.yaml (e.g. version: 1.0.2).
2. Update CHANGELOG.md with release notes for the new version.
3. Commit and push the changes to main:

   git add pubspec.yaml CHANGELOG.md
   git commit -m "chore: bump version to 1.0.2"
   git push origin main
   

4. Wait for the CI workflow to pass on main.
5. Create and push a matching Git tag (v prefix followed by the exact version):

   git tag v1.0.2
   git push origin v1.0.2
   

6. The GitHub Actions release workflow validates that the tag matches pubspec.yaml, executes format, analyze, test, and dry-run checks.
7. Upon successful validation, the package is automatically published to pub.dev via GitHub OIDC.

Note

The Git tag version must exactly match the version in pubspec.yaml (e.g., tag v1.0.2 matches version: 1.0.2). Mismatched tags are rejected by the workflow.

---

License

This package is released under the MIT License.

Libraries

nepali_kit

Unified library entry point for nepali_kit.

nepali_kit_core

Pure Dart library entry point for nepali_kit.