Migration Guide

This guide details the steps to migrate your code from nepali-bs-calendar-react v0.2.0 to v1.0.1.

Overview of Major Changes

In version 1.0.1, the package continues to support the improved provider-backed calendar architecture and introduces a new custom calendar rendering option.

1. Component Renaming

Calendar has been renamed/split into StaticNepaliCalendar and NepaliCalendar (the popup picker component).
DatePicker has been consolidated into NepaliCalendar with label, placeholder, and validation error capabilities.

2. Context Provider is Required

You must wrap components with NepaliCalendarProvider and pass defaultCalendarData or your own custom calendar definitions.

import { NepaliCalendarProvider, defaultCalendarData } from 'nepali-bs-calendar-react'
 
function App() {
  return (
    <NepaliCalendarProvider data={defaultCalendarData}>
      {/* Your components */}
    </NepaliCalendarProvider>
  )
}

Step-by-Step Upgrade Guide

Step 1: Update the Dependency

Install the latest version from npm:

npm install nepali-bs-calendar-react@1.0.1

Step 2: Set Up the Provider

Add the NepaliCalendarProvider at the root of your application layouts (or wrapping the forms where you use the calendar).

Step 3: Replace Imports and Elements

Replacing `Calendar` (Static view)

If you rendered a calendar directly on a page:

// Before
import { Calendar } from 'nepali-bs-calendar-react'
<Calendar value={date} onChange={setDate} />
 
// After
import { StaticNepaliCalendar } from 'nepali-bs-calendar-react'
<StaticNepaliCalendar value={date} onChange={setDate} />

If you used the text-input trigger that displays a popup:

// Before
import { DatePicker } from 'nepali-bs-calendar-react'
<DatePicker value={date} onChange={setDate} placeholder="Select date" />
 
// After
import { NepaliCalendar } from 'nepali-bs-calendar-react'
<NepaliCalendar value={date} onChange={setDate} placeholder="Select date" />

Step 4: Use the new `calendarComponent` prop

If you want full control over the calendar UI, pass a custom component to calendarComponent on either NepaliCalendar or StaticNepaliCalendar.

Step 5: Verify Props and CSS Overrides

Confirm that your custom style overrides are defined globally on :root or body using CSS variables like --nc-bg.
Double check that you've imported the default CSS:

import 'nepali-bs-calendar-react/styles.css'

Utility hook usage

If you need access to Nepali date helpers outside the calendar UI, use the useNepaliDateUtils hook inside a component wrapped by NepaliCalendarProvider.

import {
  NepaliCalendarProvider,
  defaultCalendarData,
  useNepaliDateUtils,
} from 'nepali-bs-calendar-react'
 
function DateInfo() {
  const utils = useNepaliDateUtils()
  const firstDate = utils.getFirstValidDate()
  const formatted = utils.formatBSDate(firstDate)
  const weekday = utils.getWeekdayOfBSDate(firstDate)
 
  return (
    <div>
      <p>First valid BS date: {formatted}</p>
      <p>Weekday: {weekday}</p>
    </div>
  )
}
 
function App() {
  return (
    <NepaliCalendarProvider data={defaultCalendarData}>
      <DateInfo />
    </NepaliCalendarProvider>
  )
}