Skip to content

Commit 41293c8

Browse files
binodnepalibinodnepali
authored
docs: update documentation for Bikram Sambat date, time, and datetime pickers; enhance API overview and usage examples (#28)
1 parent c9788bd commit 41293c8

62 files changed

Lines changed: 3933 additions & 125 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎apps/docs/.vitepress/config.ts‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ export default defineConfig({
77
base: DOCS_BASE,
88
title: 'react-nepali-datetime-picker',
99
description:
10-
'Bikram Sambat calendar and date picker for React and React Native',
10+
'Bikram Sambat calendar, date, time, and datetime pickers for React and React Native',
1111
cleanUrls: true,
1212
themeConfig: {
1313
nav: [
@@ -23,14 +23,21 @@ export default defineConfig({
2323
text: 'Guide',
2424
items: [
2525
{ text: 'Getting Started', link: '/getting-started' },
26-
{ text: 'BsDayPicker API', link: '/api' },
2726
{ text: 'Localization', link: '/localization' },
2827
{ text: 'Styling', link: '/styling' },
2928
{ text: 'Data Source', link: '/data' },
3029
{ text: 'React Native', link: '/react-native' },
3130
{ text: 'Migration from v1', link: '/migration' },
3231
],
3332
},
33+
{
34+
text: 'API',
35+
items: [
36+
{ text: 'Overview', link: '/api' },
37+
{ text: 'BsDayPicker', link: '/api/day-picker' },
38+
{ text: 'Pickers', link: '/api/pickers' },
39+
],
40+
},
3441
],
3542
},
3643
})

‎apps/docs/api.md‎

Lines changed: 7 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
1-
# BsDayPicker API
1+
# API overview
22

3-
The headless primitive mirrors the minimal [React DayPicker](https://daypicker.dev/) API.
3+
Shared types and BS ↔ AD helpers used across registry items. Component-specific props live on dedicated pages:
4+
5+
- [BsDayPicker](/api/day-picker) — headless calendar primitive and `useBsCalendar`
6+
- [Pickers](/api/pickers) — `BsDatePicker`, `BsTimePicker`, `BsDateTimePicker`
47

58
## `BsDate`
69

@@ -14,7 +17,7 @@ type BsDate = {
1417

1518
Months are **1-indexed** to match Hamro Patro URLs (`/calendar/2083/1`).
1619

17-
## BS ↔ AD
20+
## BS ↔ AD {#bs-ad}
1821

1922
`onSelect`, `onChange`, and `onValueChange` return **`BsDate` only** (Bikram Sambat year / month / day). They do **not** include the Gregorian (AD) date in the callback.
2023

@@ -43,50 +46,4 @@ function handleSelect(bs: BsDate | undefined) {
4346
| `formatAdDate(adDate, locale)` | Localized AD label for display |
4447
| `getCurrentBsDate()` | Today as `BsDate` (from calendar data) |
4548

46-
## `BsDayPicker` props
47-
48-
| Prop | Type | Default | Description |
49-
| ----------------- | ----------------------------------- | ---------- | ---------------------------------------------------- |
50-
| `mode` | `"single" \| "multiple" \| "range"` | `"single"` | v1 implements `single` only |
51-
| `selected` | `BsDate \| undefined` | — | Selected date |
52-
| `onSelect` | `(date?: BsDate) => void` | — | Selection callback (BS only — see [BS ↔ AD](#bs-ad)) |
53-
| `locale` | `"en" \| "ne"` | `"ne"` | Labels and digit formatting |
54-
| `month` | `{ year, month }` | today | Visible month |
55-
| `onMonthChange` | `(month) => void` | — | Month navigation callback |
56-
| `captionLayout` | `"label" \| "dropdown"` | `"label"` | Caption UI |
57-
| `showOutsideDays` | `boolean` | `true` | Show adjacent-month days |
58-
| `disabled` | `boolean \| (date) => boolean` | — | Disable days |
59-
| `className` | `string` | — | Root class |
60-
| `classNames` | `BsDayPickerClassNames` | — | Slot class map |
61-
| `components` | `BsDayPickerComponents` | — | Sub-component overrides |
62-
| `footer` | `ReactNode` | — | Footer below grid |
63-
64-
## `useBsCalendar`
65-
66-
```ts
67-
const {
68-
month,
69-
weeks,
70-
weekdayLabels,
71-
years,
72-
months,
73-
goToPreviousMonth,
74-
goToNextMonth,
75-
setMonth,
76-
selectDate,
77-
} = useBsCalendar({
78-
locale: "ne",
79-
month: { year: 2083, month: 1 },
80-
selected,
81-
onSelect,
82-
});
83-
```
84-
85-
## `BsDatePicker` (web)
86-
87-
| Prop | Type | Description |
88-
| ------------- | -------------------------- | ------------------------------------------------ |
89-
| `value` | `BsDate` | Selected value |
90-
| `onChange` | `(value?: BsDate) => void` | Change handler (BS only — see [BS ↔ AD](#bs-ad)) |
91-
| `locale` | `"en" \| "ne"` | Display locale |
92-
| `placeholder` | `string` | Trigger placeholder |
49+
For datetime values, see [BS ↔ AD datetime](/api/pickers#bs-ad-datetime) on the pickers page.

‎apps/docs/api/day-picker.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# BsDayPicker
2+
3+
The headless primitive mirrors the minimal [React DayPicker](https://daypicker.dev/) API. Install via **`bs-calendar`**; see [API overview](/api) for `BsDate` and [BS ↔ AD](/api#bs-ad).
4+
5+
## `BsDayPicker` props
6+
7+
| Prop | Type | Default | Description |
8+
| ----------------- | ----------------------------------- | ---------- | ---------------------------------------------------- |
9+
| `mode` | `"single" \| "multiple" \| "range"` | `"single"` | v1 implements `single` only |
10+
| `selected` | `BsDate \| undefined` | — | Selected date |
11+
| `onSelect` | `(date?: BsDate) => void` | — | Selection callback (BS only — see [BS ↔ AD](/api#bs-ad)) |
12+
| `locale` | `"en" \| "ne"` | `"ne"` | Labels and digit formatting |
13+
| `month` | `{ year, month }` | today | Visible month |
14+
| `onMonthChange` | `(month) => void` | — | Month navigation callback |
15+
| `captionLayout` | `"label" \| "dropdown"` | `"label"` | Caption UI |
16+
| `showOutsideDays` | `boolean` | `true` | Show adjacent-month days |
17+
| `disabled` | `boolean \| (date) => boolean` | — | Disable days |
18+
| `className` | `string` | — | Root class |
19+
| `classNames` | `BsDayPickerClassNames` | — | Slot class map |
20+
| `components` | `BsDayPickerComponents` | — | Sub-component overrides |
21+
| `footer` | `ReactNode` | — | Footer below grid |
22+
23+
## `useBsCalendar`
24+
25+
```ts
26+
const {
27+
month,
28+
weeks,
29+
weekdayLabels,
30+
years,
31+
months,
32+
goToPreviousMonth,
33+
goToNextMonth,
34+
setMonth,
35+
selectDate,
36+
} = useBsCalendar({
37+
locale: "ne",
38+
month: { year: 2083, month: 1 },
39+
selected,
40+
onSelect,
41+
});
42+
```
43+
44+
## Related
45+
46+
- [BsDatePicker](/api/pickers#bsdatepicker) — trigger + popover/dialog wrapper
47+
- [Pickers](/api/pickers) — time and datetime components

‎apps/docs/api/pickers.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Pickers
2+
3+
Registry items: **`bs-date-picker`**, **`bs-time-picker`**, **`bs-datetime-picker`**.
4+
5+
Date callbacks return **`BsDate` only** — see [BS ↔ AD](/api#bs-ad) on the overview page.
6+
7+
## `BsDatePicker`
8+
9+
| Prop | Type | Default | Description |
10+
| --------------- | -------------------------- | ------- | ------------------------------------------------ |
11+
| `value` | `BsDate` | — | Selected value |
12+
| `onChange` | `(value?: BsDate) => void` | — | Change handler (web) |
13+
| `onValueChange` | `(value?: BsDate) => void` | — | Change handler (native) |
14+
| `locale` | `"en" \| "ne"` | `"ne"` | Display locale |
15+
| `placeholder` | `string` | — | Trigger placeholder |
16+
| `disabled` | `boolean` | — | Disable trigger |
17+
18+
| Platform | UX |
19+
| -------- | ------------------------------------- |
20+
| iOS | Bottom sheet with BS date wheels |
21+
| Android | Material calendar dialog |
22+
| Web | Popover with `BsCalendar` |
23+
24+
## `BsTime`
25+
26+
```ts
27+
type BsTime = {
28+
hour: number; // 0–23
29+
minute: number; // 0–59
30+
};
31+
```
32+
33+
Internal storage is always **24-hour**. Set `is24Hour={false}` on pickers for 12-hour display with AM/PM.
34+
35+
Nepali period labels in the picker UI: **एम** (AM), **पिम** (PM).
36+
37+
## `BsTimePicker`
38+
39+
| Prop | Type | Default | Description |
40+
| --------------- | --------------------------- | ------- | ------------------------ |
41+
| `value` | `BsTime` | — | Selected time |
42+
| `onChange` | `(value?: BsTime) => void` | — | Change handler (web) |
43+
| `onValueChange` | `(value?: BsTime) => void` | — | Change handler (native) |
44+
| `locale` | `"en" \| "ne"` | `"ne"` | Labels and digits |
45+
| `is24Hour` | `boolean` | `false` | 24h vs 12h + AM/PM |
46+
| `placeholder` | `string` | — | Trigger placeholder |
47+
| `disabled` | `boolean` | — | Disable trigger |
48+
49+
| Platform | UX |
50+
| -------- | ----------------------------------------------- |
51+
| iOS | Bottom sheet with hour / minute / AM·PM wheels |
52+
| Android | Material time dialog (digital + analog clock) |
53+
| Web | Popover with hour, minute, and period selects |
54+
55+
## `BsDateTime`
56+
57+
```ts
58+
type BsDateTime = BsDate & BsTime;
59+
// { year, month, day, hour, minute }
60+
```
61+
62+
### BS ↔ AD datetime {#bs-ad-datetime}
63+
64+
Use `toAdDate()` when submitting to APIs that expect a Gregorian `Date`:
65+
66+
```ts
67+
import type { BsDateTime } from "@/lib/bs-time-picker/time/types";
68+
import { toAdDate } from "@/lib/bs-datetime-picker";
69+
70+
function submitJourney(bsDateTime: BsDateTime) {
71+
const ad = toAdDate(bsDateTime); // Date in local timezone or null if day missing from data
72+
if (!ad) return;
73+
// e.g. OTP journeyDate
74+
}
75+
```
76+
77+
| Helper | Returns |
78+
| ----------------------------- | --------------------------------------------- |
79+
| `toAdDate(bsDateTime)` | `Date` or `null` (uses `getDayAdDate` + time) |
80+
| `formatBsDateTime()` | Localized BS date + time label |
81+
| `getDefaultBsDateTime()` | Today + now as `BsDateTime` |
82+
| `mergeBsDateTime(date, time)` | Combine `BsDate` + `BsTime` |
83+
84+
## `BsDateTimePicker`
85+
86+
Same props as `BsTimePicker`, plus date selection. Web uses `onChange`; native uses `onValueChange`.
87+
88+
| Platform | UX |
89+
| -------- | ----------------------------------------------- |
90+
| iOS | Bottom sheet: BS date wheel + hour/minute wheels |
91+
| Android | Material calendar dialog → time dialog |
92+
| Web | Popover: calendar + time selects |
93+
94+
## Related
95+
96+
- [BsDayPicker](/api/day-picker) — headless calendar used inside date pickers
97+
- [API overview](/api) — shared `BsDate` type and date BS ↔ AD helpers

‎apps/docs/data.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,10 @@ type BsCalendarData = Record<string, Record<string, {
4141
4242
`2000` – `2089` BS (matching Hamro Patro navigation).
4343
44+
## Date + time pickers
45+
46+
`BsDateTimePicker` and `toAdDate()` resolve the Gregorian date from the same `bs-calendar.json` entries (`adDate` per BS day). If a day is missing from the dataset, `getDayAdDate` / `toAdDate` return `null` — handle that in submit handlers.
47+
4448
## Attribution
4549
4650
Hamro Patro is the authoritative source for BS–AD mapping and festival labels. Re-scrape periodically to pick up calendar corrections.

‎apps/docs/getting-started.md‎

Lines changed: 79 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,19 @@
11
# Getting Started
22

3-
**react-nepali-datetime-picker** is a registry-first Bikram Sambat calendar. Install components into your project the same way you add [shadcn/ui](https://ui.shadcn.com) components — they are copied into your codebase, not installed from npm.
3+
**react-nepali-datetime-picker** is a registry-first Bikram Sambat calendar and picker suite. Install components into your project the same way you add [shadcn/ui](https://ui.shadcn.com) components — they are copied into your codebase, not installed from npm.
44

5-
Registry items: **`bs-calendar`**, **`bs-date-picker`**. Headless engine: **`lib/bs-day-picker/`** (`BsDayPicker`, `useBsCalendar`).
5+
## Registry items
6+
7+
| Item | Description |
8+
| ---- | ----------- |
9+
| **`bs-calendar`** | Inline BS calendar grid + headless `lib/bs-day-picker/` |
10+
| **`bs-date-picker`** | Trigger + popover / sheet / Material dialog |
11+
| **`bs-time-picker`** | 12h/24h time selection |
12+
| **`bs-datetime-picker`** | Combined BS date + time |
13+
14+
**Install order:** `bs-calendar` → `bs-date-picker` → `bs-time-picker` → `bs-datetime-picker` (each step pulls shared libs).
15+
16+
See [API overview](/api) for types and [Pickers](/api/pickers) for props.
617

718
## Web (React + Tailwind)
819

@@ -23,18 +34,21 @@ pnpm registry:build
2334
Then install from your app or UI package (use the **built** JSON under `apps/docs/public/r/`, not `registry/web/`):
2435

2536
```bash
26-
# From your shadcn app or UI package root
27-
pnpm dlx shadcn@latest add /absolute/path/to/react-nepali-datetime-picker/apps/docs/public/r/bs-calendar.json --overwrite
28-
pnpm dlx shadcn@latest add /absolute/path/to/react-nepali-datetime-picker/apps/docs/public/r/bs-date-picker.json --overwrite
29-
```
37+
REG="/absolute/path/to/react-nepali-datetime-picker/apps/docs/public/r"
3038

31-
Install **bs-calendar first**, then **bs-date-picker**.
39+
pnpm dlx shadcn@latest add "$REG/bs-calendar.json" --overwrite
40+
pnpm dlx shadcn@latest add "$REG/bs-date-picker.json" --overwrite
41+
pnpm dlx shadcn@latest add "$REG/bs-time-picker.json" --overwrite
42+
pnpm dlx shadcn@latest add "$REG/bs-datetime-picker.json" --overwrite
43+
```
3244

3345
When docs are deployed ([GitHub Pages](https://binodnepali.github.io/react-nepali-datetime-picker/)):
3446

3547
```bash
3648
pnpm dlx shadcn@latest add https://binodnepali.github.io/react-nepali-datetime-picker/r/bs-calendar.json
3749
pnpm dlx shadcn@latest add https://binodnepali.github.io/react-nepali-datetime-picker/r/bs-date-picker.json
50+
pnpm dlx shadcn@latest add https://binodnepali.github.io/react-nepali-datetime-picker/r/bs-time-picker.json
51+
pnpm dlx shadcn@latest add https://binodnepali.github.io/react-nepali-datetime-picker/r/bs-datetime-picker.json
3852
```
3953

4054
For namespaced installs over HTTP, register the registry once:
@@ -43,10 +57,14 @@ For namespaced installs over HTTP, register the registry once:
4357
pnpm dlx shadcn@latest registry add @react-nepali-datetime-picker=https://binodnepali.github.io/react-nepali-datetime-picker/r/{name}.json
4458
pnpm dlx shadcn@latest add @react-nepali-datetime-picker/bs-calendar
4559
pnpm dlx shadcn@latest add @react-nepali-datetime-picker/bs-date-picker
60+
pnpm dlx shadcn@latest add @react-nepali-datetime-picker/bs-time-picker
61+
pnpm dlx shadcn@latest add @react-nepali-datetime-picker/bs-datetime-picker
4662
```
4763

4864
### Usage
4965

66+
**Inline calendar**
67+
5068
```tsx
5169
import { useState } from "react"
5270
import { BsCalendar, type BsDate } from "@/components/bs-calendar"
@@ -66,7 +84,7 @@ export function Example() {
6684
}
6785
```
6886

69-
### Date picker with popover
87+
**Date picker**
7088

7189
```tsx
7290
import { useState } from "react"
@@ -87,10 +105,61 @@ export function Example() {
87105
}
88106
```
89107

108+
**Time picker**
109+
110+
```tsx
111+
import { useState } from "react"
112+
import { BsTimePicker } from "@/components/bs-time-picker"
113+
import type { BsTime } from "@/lib/bs-time-picker/time/types"
114+
115+
export function Example() {
116+
const [value, setValue] = useState<BsTime>()
117+
118+
return (
119+
<BsTimePicker
120+
value={value}
121+
onChange={setValue}
122+
locale="ne"
123+
is24Hour={false}
124+
placeholder="समय छान्नुहोस्"
125+
/>
126+
)
127+
}
128+
```
129+
130+
**Date + time picker**
131+
132+
```tsx
133+
import { useState } from "react"
134+
import { BsDateTimePicker } from "@/components/bs-datetime-picker"
135+
import { toAdDate } from "@/lib/bs-datetime-picker"
136+
import type { BsDateTime } from "@/lib/bs-time-picker/time/types"
137+
138+
export function Example() {
139+
const [value, setValue] = useState<BsDateTime>()
140+
141+
const handleSubmit = () => {
142+
if (!value) return
143+
const ad = toAdDate(value) // Gregorian Date for APIs (e.g. trip planner)
144+
if (!ad) return
145+
// …
146+
}
147+
148+
return (
149+
<BsDateTimePicker
150+
value={value}
151+
onChange={setValue}
152+
locale="ne"
153+
placeholder="मिति र समय छान्नुहोस्"
154+
/>
155+
)
156+
}
157+
```
158+
90159
## React Native
91160

92-
See [React Native](/react-native) for the NativeWind registry install and `PortalHost` notes.
161+
See [React Native](/react-native) for the NativeWind registry install, platform files, and `PortalHost` notes.
93162

94163
## Headless usage
95164

96-
The copied `lib/bs-day-picker/` folder includes a headless `BsDayPicker` and `useBsCalendar` hook if you want to build a fully custom UI.
165+
The copied `lib/bs-day-picker/` folder includes a headless [BsDayPicker](/api/day-picker) and `useBsCalendar` hook if you want to build a fully custom UI. Time helpers live under `lib/bs-time-picker/`.

0 commit comments

Comments
 (0)