react-native-bikram-sambat 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog and this project follows Semantic Versioning.
+
+## [0.1.2] - 2026-05-16
+
+### Changed
+
+- Improved npm metadata for discoverability and package SEO.
+- Rewrote the README with production-ready documentation, badges, and accurate usage examples.
+- Added contribution guidance, changelog tracking, and GitHub issue templates.

package/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+Thank you for contributing to `react-native-bikram-sambat`.
+
+## Development Setup
+
+1. Clone the repository.
+2. Install dependencies:
+
+```sh
+npm install
+```
+
+3. Run the main validation steps:
+
+```sh
+npm run typecheck
+npm test
+npm run build
+```
+
+## Contribution Guidelines
+
+- Keep public APIs backward compatible unless a breaking change is clearly discussed.
+- Add or update tests when changing exported behavior.
+- Keep README examples aligned with the actual exported API.
+- Avoid adding dependencies unless they are necessary for the package.
+- Keep commits focused and easy to review.
+
+## Pull Requests
+
+- Describe the problem and the proposed fix clearly.
+- Include screenshots or usage examples when changing UI behavior.
+- Mention any changes to exports, documentation, or package metadata.
+
+## Issues
+
+- Use the bug report template for incorrect behavior, crashes, or packaging problems.
+- Use the feature request template for new APIs, components, or enhancements.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026
+Copyright (c) 2026 jeevandhl
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,8 +1,25 @@
-# react-native-bikram-sambat
+# React Native Bikram Sambat Calendar, Nepali Date Picker, and AD to BS Converter
 
-A production-grade Bikram Sambat (BS) calendar engine and React Native date picker for React Native.
+![npm](https://img.shields.io/npm/v/react-native-bikram-sambat)
+![downloads](https://img.shields.io/npm/dm/react-native-bikram-sambat)
+![license](https://img.shields.io/npm/l/react-native-bikram-sambat)
+![types](https://img.shields.io/npm/types/react-native-bikram-sambat)
 
-TypeScript-first helpers for BS/AD conversion, formatting, parsing, and calendar grid generation, plus ready-to-use React Native UI components with theming, dark mode, and accessibility.
+`react-native-bikram-sambat` is a TypeScript React Native calendar package for building Nepali calendar experiences in mobile apps. It combines a React Native Bikram Sambat calendar UI, a Nepali date picker, and reliable Nepali date conversion helpers for AD to BS conversion and BS to AD conversion.
+
+If you need a Nepali calendar for React Native, a Bikram Sambat calendar component, or an AD to BS converter for app logic, this package gives you both the UI layer and the core date engine in one place. It is designed for teams that want production-ready Bikram Sambat and Nepali date conversion support without maintaining custom date tables and picker components themselves.
+
+## Features
+
+- React Native Bikram Sambat calendar component
+- Nepali date picker and range picker components
+- AD to BS converter and BS to AD converter helpers
+- Bikram Sambat calendar month grid generation
+- Nepali date conversion utilities for formatting, parsing, validation, and arithmetic
+- English and Nepali locale support
+- Latin and Devanagari numeral support
+- TypeScript-first exports and generated declaration files
+- Theme overrides, dark mode support, and accessibility-friendly interactions
 
 ## Installation
 
@@ -18,16 +35,12 @@ yarn add react-native-bikram-sambat
 
 ## Quick Start
 
-### Date Picker
-
-The simplest way to let users pick a BS date:
-
 ```tsx
 import React, { useState } from 'react';
 import { SafeAreaView } from 'react-native';
 import {
   NepaliDatePicker,
-  type BSDateValue
+  type BSDateValue,
 } from 'react-native-bikram-sambat';
 
 export default function App() {
@@ -47,83 +60,90 @@ export default function App() {
 }
 ```
 
-### Calendar Component
+## AD to BS Example
 
-For inline calendar display:
+Use the built-in AD to BS converter when you need to convert a Gregorian date to a Bikram Sambat date.
 
-```tsx
-import React, { useState } from 'react';
-import { SafeAreaView } from 'react-native';
-import { NepaliCalendar, type BSDateValue } from 'react-native-bikram-sambat';
+```ts
+import { toBS } from 'react-native-bikram-sambat';
 
-export default function App() {
-  const [date, setDate] = useState<BSDateValue | null>(null);
+const bsDate = toBS({
+  calendar: 'AD',
+  year: 2024,
+  month: 4,
+  day: 13,
+});
 
-  return (
-    <SafeAreaView style={{ flex: 1 }}>
-      <NepaliCalendar value={date} onChange={setDate} />
-    </SafeAreaView>
-  );
-}
+// Example result shape:
+// { calendar: 'BS', year: 2081, month: 1, day: 1 }
 ```
 
-### Date Picker Modal
+## BS to AD Example
+
+Use the BS to AD converter when your app stores Bikram Sambat values and needs Gregorian output.
 
-For custom modal control:
+```ts
+import { toAD } from 'react-native-bikram-sambat';
+
+const adDate = toAD({
+  calendar: 'BS',
+  year: 2081,
+  month: 1,
+  day: 1,
+});
+
+// Example result shape:
+// { calendar: 'AD', year: 2024, month: 4, day: 13 }
+```
+
+## React Native Date Picker Example
 
 ```tsx
 import React, { useState } from 'react';
-import { Button, SafeAreaView } from 'react-native';
+import { SafeAreaView } from 'react-native';
 import {
-  DatePickerModal,
-  type BSDateValue
+  NepaliDatePicker,
+  type BSDateValue,
 } from 'react-native-bikram-sambat';
 
 export default function App() {
-  const [visible, setVisible] = useState(false);
-  const [date, setDate] = useState<BSDateValue | null>(null);
+  const [selectedDate, setSelectedDate] = useState<BSDateValue | null>(null);
 
   return (
     <SafeAreaView style={{ flex: 1, padding: 16 }}>
-      <Button title="Open date picker" onPress={() => setVisible(true)} />
-
-      <DatePickerModal
-        visible={visible}
-        value={date}
-        onChange={setDate}
-        onClose={() => setVisible(false)}
-        locale="ne"
-        numerals="devanagari"
+      <NepaliDatePicker
+        value={selectedDate}
+        onChange={setSelectedDate}
+        placeholder="Choose a BS date"
+        displayFormat="yyyy-MM-dd"
+        locale="en"
+        numerals="latin"
       />
     </SafeAreaView>
   );
 }
 ```
 
-### Range Picker
+## More Usage Examples
 
-For selecting a date range:
+### Inline Bikram Sambat calendar
 
 ```tsx
 import React, { useState } from 'react';
 import { SafeAreaView } from 'react-native';
 import {
-  NepaliRangePicker,
-  type DateRangeValue
+  NepaliCalendar,
+  type BSDateValue,
 } from 'react-native-bikram-sambat';
 
 export default function App() {
-  const [range, setRange] = useState<DateRangeValue>({
-    start: null,
-    end: null,
-  });
+  const [date, setDate] = useState<BSDateValue | null>(null);
 
   return (
     <SafeAreaView style={{ flex: 1, padding: 16 }}>
-      <NepaliRangePicker
-        value={range}
-        onChange={setRange}
-        placeholder="Select date range"
+      <NepaliCalendar
+        value={date}
+        onChange={setDate}
         locale="ne"
         numerals="devanagari"
       />
@@ -132,20 +152,17 @@ export default function App() {
 }
 ```
 
-### Range Picker Modal
-
-For custom range picker modal control:
+### Nepali date range picker
 
 ```tsx
 import React, { useState } from 'react';
-import { Button, SafeAreaView } from 'react-native';
+import { SafeAreaView } from 'react-native';
 import {
-  RangePickerModal,
-  type DateRangeValue
+  NepaliRangePicker,
+  type DateRangeValue,
 } from 'react-native-bikram-sambat';
 
 export default function App() {
-  const [visible, setVisible] = useState(false);
   const [range, setRange] = useState<DateRangeValue>({
     start: null,
     end: null,
@@ -153,206 +170,104 @@ export default function App() {
 
   return (
     <SafeAreaView style={{ flex: 1, padding: 16 }}>
-      <Button title="Open range picker" onPress={() => setVisible(true)} />
-
-      <RangePickerModal
-        visible={visible}
+      <NepaliRangePicker
         value={range}
         onChange={setRange}
-        onClose={() => setVisible(false)}
-        locale="ne"
-        numerals="devanagari"
+        placeholder="Select date range"
       />
     </SafeAreaView>
   );
 }
 ```
 
-## Core Utilities
-
-### BS ⇄ AD Conversion
-
-```ts
-import { toBS, toAD, isValidBSDate, isValidADDate } from 'react-native-bikram-sambat';
-
-const bs = toBS({ calendar: 'AD', year: 2024, month: 4, day: 13 });
-const ad = toAD({ calendar: 'BS', year: 2081, month: 1, day: 1 });
-
-const valid = isValidBSDate({ calendar: 'BS', year: 2081, month: 1, day: 1 });
-const validAD = isValidADDate({ calendar: 'AD', year: 2024, month: 4, day: 13 });
-```
-
-### Formatting and Parsing
-
-```ts
-import { formatBS, parseBS, toNepaliNumerals, toLatinNumerals } from 'react-native-bikram-sambat';
-
-const date = { calendar: 'BS', year: 2081, month: 1, day: 5 };
-
-formatBS(date, 'yyyy-MM-dd');           // '2081-01-05'
-formatBS(date, 'dd MMMM yyyy');         // '05 Baisakh 2081'
-formatBS(date, 'dd MMMM yyyy', { locale: 'ne', numerals: 'devanagari' }); // '०५ बैशाख २०८१'
-
-parseBS('2081-01-05', 'yyyy-MM-dd');    // { calendar: 'BS', year: 2081, month: 1, day: 5 }
-
-toNepaliNumerals('2081');               // '२०८१'
-toLatinNumerals('२०८१');               // '2081'
-```
-
-### Date Arithmetic
-
-```ts
-import { compareBS, addBSDays, subBSDays, todayBS } from 'react-native-bikram-sambat';
-
-const today = todayBS();
-const future = addBSDays(today, 30);
-const past = subBSDays(today, 30);
-const cmp = compareBS(future, past); // > 0
-```
-
-### Date Keys
-
-```ts
-import { createBSDateKey, parseBSDateKey } from 'react-native-bikram-sambat';
-
-const key = createBSDateKey({ calendar: 'BS', year: 2081, month: 1, day: 1 });
-// '2081-01-01'
-
-const parsed = parseBSDateKey('2081-01-01');
-// { calendar: 'BS', year: 2081, month: 1, day: 1 }
-```
-
-### Supported Range
-
-```ts
-import { getSupportedBSRange, isBSDateInSupportedRange } from 'react-native-bikram-sambat';
-
-const range = getSupportedBSRange(); // { start: 2081, end: 2081 }
-const inRange = isBSDateInSupportedRange({ calendar: 'BS', year: 2081, month: 1, day: 1 });
-```
-
-### Calendar Grid
-
-```ts
-import { getCalendarMonthGrid } from 'react-native-bikram-sambat';
-
-const grid = getCalendarMonthGrid({
-  year: 2081,
-  month: 1,
-  weekStartsOn: 0, // 0 = Sunday
-  minDate: { calendar: 'BS', year: 2081, month: 1, day: 1 },
-  maxDate: { calendar: 'BS', year: 2081, month: 12, day: 30 },
-});
-
-// grid.weeks is a 2D array of cells
-```
-
-## TypeScript Usage
-
-All public APIs are fully typed:
+### Formatting and parsing Nepali dates
 
 ```ts
 import {
-  type BSDateValue,
-  type ADDateValue,
-  type DateRangeValue,
-  type CalendarTheme,
-  type CalendarMarkedDate,
-  type NepaliCalendarProps,
-  type NepaliDatePickerProps,
-  type DatePickerModalProps,
-  type NepaliRangePickerProps,
-  type RangePickerModalProps,
-  type CalendarLocale,
-  type LocaleCode,
-  type NumeralSystem,
+  formatBS,
+  parseBS,
+  toNepaliNumerals,
+  toLatinNumerals,
 } from 'react-native-bikram-sambat';
-```
-
-## Theme Customization
 
-### Light and Dark Mode
+const date = { calendar: 'BS', year: 2081, month: 1, day: 5 } as const;
 
-```tsx
-import { NepaliCalendar } from 'react-native-bikram-sambat';
-
-// System default (auto-detects device theme)
-<NepaliCalendar colorScheme="system" />
-
-// Force dark mode
-<NepaliCalendar colorScheme="dark" />
+const isoLike = formatBS(date, 'yyyy-MM-dd');
+const nepaliFormatted = formatBS(date, 'dd MMMM yyyy', {
+  locale: 'ne',
+  numerals: 'devanagari',
+});
 
-// Force light mode
-<NepaliCalendar colorScheme="light" />
+const parsed = parseBS('2081-01-05', 'yyyy-MM-dd');
+const devanagari = toNepaliNumerals('2081');
+const latin = toLatinNumerals('२०८१');
 ```
 
-### Custom Theme Override
+## API Reference
 
-```tsx
-import { NepaliDatePicker, type CalendarTheme } from 'react-native-bikram-sambat';
-
-const customTheme: Partial<CalendarTheme> = {
-  colors: {
-    primary: '#7c3aed',
-    primaryText: '#ffffff',
-  },
-  radius: {
-    day: 16,
-    calendar: 16,
-  },
-};
-
-<NepaliDatePicker theme={customTheme} />
-```
+### Components
 
-## Local Package Testing
+- `NepaliCalendar`: Inline Bikram Sambat calendar component for React Native
+- `NepaliDatePicker`: Pressable Nepali date picker input with modal calendar
+- `DatePickerModal`: Controlled date picker modal component
+- `NepaliRangePicker`: Range picker input for selecting start and end BS dates
+- `RangePickerModal`: Controlled range picker modal component
 
-When developing locally, test the package before publishing:
+### Conversion and formatting
 
-```sh
-npm run typecheck
-npm test
-npm run build
-npm pack --dry-run
-npm pack
-```
+- `toBS`: Convert an AD date to a BS date
+- `toAD`: Convert a BS date to an AD date
+- `formatBS`: Format a BS date using supported tokens
+- `parseBS`: Parse a BS date string using the supported `yyyy-MM-dd` pattern
+- `toNepaliNumerals`: Convert Latin digits to Devanagari digits
+- `toLatinNumerals`: Convert Devanagari digits to Latin digits
 
-This produces a `.tgz` file. Test it in another React Native CLI app:
+### Validation and helpers
 
-```sh
-cd /path/to/your/app
-npm install ../Calender/react-native-bikram-sambat-0.1.0.tgz
-```
+- `isValidBSDate`
+- `isValidADDate`
+- `isBSDateInSupportedRange`
+- `getSupportedBSRange`
+- `createBSDateKey`
+- `parseBSDateKey`
+- `compareBS`
+- `addBSDays`
+- `subBSDays`
+- `todayBS`
+- `getCalendarMonthGrid`
 
-## Supported BS Range
+## Use Cases
 
-The package currently supports the verified BS date range included in its data table. Dates outside the supported range will throw or return `false` depending on the API.
+- Building a Nepali date picker in a React Native checkout, booking, or profile flow
+- Showing a Bikram Sambat calendar in education, finance, HR, government, or scheduling apps
+- Converting user-entered Gregorian dates with an AD to BS converter
+- Converting stored BS values to Gregorian dates with a BS to AD converter
+- Supporting Nepali date conversion and display in apps for users in Nepal
+- Adding a TypeScript React Native calendar package to an Expo or React Native CLI codebase
 
-Core conversion functions throw `RangeError` for out-of-range dates.
-UI components handle invalid dates gracefully without crashing.
+## Why Use This Package?
 
-## Publishing
+- It gives you a single package for both Nepali date conversion and React Native UI components.
+- It reduces maintenance compared with rolling your own Bikram Sambat calendar logic.
+- It keeps TypeScript types close to the public API for better editor support and safer integration.
+- It supports theming, locales, numerals, and accessibility so teams can ship a more polished Nepali calendar for React Native.
 
-Publishing is handled by GitHub Actions when code is pushed to `main`.
+## TypeScript Support
 
-Before publishing, add an npm automation token in GitHub:
+This package is built with TypeScript and publishes declaration files via the `types` field. Public types include `BSDateValue`, `ADDateValue`, `DateRangeValue`, `NepaliCalendarProps`, `NepaliDatePickerProps`, `RangePickerModalProps`, and theme-related types.
 
-- Repository settings → Secrets and variables → Actions
-- Add secret named `NPM_TOKEN`
+## Expo and React Native CLI Compatibility
 
-To publish a new version:
+This package currently appears suitable for both Expo-managed and React Native CLI projects because the published source is JavaScript and TypeScript only and does not define custom native modules. You should still test your target screens in your own app, especially if you rely on specific React Native versions, theming constraints, or accessibility requirements.
 
-```sh
-npm version patch
-git push origin main --follow-tags
-```
+## Preview
 
-The workflow publishes only if the current package version is not already on npm.
+![Calendar view](./docs/screenshots/iphone-15-pro-max-calendar.png)
 
-## Screenshot
+## Contributing
 
-![Calendar view](./docs/screenshots/iphone-15-pro-max-calendar.png)
+Contributions are welcome. Please open an issue for bugs, feature requests, or API discussions before large changes, and see [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup and contribution guidance.
 
 ## License
 
-MIT
+MIT. See [LICENSE](./LICENSE).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "react-native-bikram-sambat",
-  "version": "0.1.1",
-  "description": "A production-grade Bikram Sambat calendar engine and React Native date picker for React Native.",
+  "version": "0.1.3",
+  "description": "React Native Bikram Sambat calendar and Nepali date picker with AD to BS converter, BS to AD converter, and TypeScript support.",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -38,20 +38,35 @@
     "!lib/**/*.test.d.ts.map",
     "docs/screenshots",
     "README.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
     "LICENSE"
   ],
   "keywords": [
     "react-native",
+    "react native",
     "bikram-sambat",
+    "bikram sambat",
+    "bikram-sambat-calendar",
     "nepali-calendar",
-    "bs-date",
-    "date-picker",
-    "calendar",
     "nepali-date",
+    "nepali-date-picker",
+    "nepali date picker",
+    "bs-date",
+    "ad-bs",
+    "ad-to-bs",
     "bs-to-ad",
-    "ad-to-bs"
+    "date-converter",
+    "calendar",
+    "datepicker",
+    "date-picker",
+    "nepal",
+    "nepali",
+    "typescript",
+    "react-native-calendar",
+    "date-conversion"
   ],
-  "author": "",
+  "author": "jeevandhl <udsjeevan@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",