@nepdatejs/datepicker 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shishir Rai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# @nepdatejs/datepicker
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-free BS/AD date picker behaviour:
+
+- `inline: true` keeps the panel open (`state.inline`) for calendars shown in the page
+- typed text ⇄ value, year first, in ASCII or Devanagari digits; dashes fill in as digits are typed (`mask: false` turns that off, `maskDateText` is exported)
+- validation with English or Nepali messages
+- the BS/AD switch
+- open/close
+- single and range values
+
+It renders nothing; the adapters (`@nepdatejs/react`, `@nepdatejs/vanilla`) do.
+
+```bash
+npm install @nepdatejs/datepicker
+```
+
+```ts
+import { createDatePicker } from '@nepdatejs/datepicker';
+
+const picker = createDatePicker({
+  defaultCalendar: 'BS',
+  min: '2026-01-01', // AD "YYYY-MM-DD"
+  onChange: (value, detail) => save(value), // value is always AD, e.g. "2026-10-10"
+});
+
+picker.actions.type('२०८३-०६-२४');
+picker.getState();
+// { value: '2026-10-10', text: '२०८३-०६-२४', equivalentText: '10 October 2026 AD', error: null, … }
+picker.actions.switchCalendar('AD'); // the text becomes "2026-10-10"; the value does not change
+```
+
+## The value contract
+
+- **Value:** always the AD day as `"YYYY-MM-DD"`, or `""` when empty or invalid. A BS date is never sent as the value.
+- **`onChange(value, detail)`:** called for user actions only (typing, picking, clear, reset). `detail` is `{ ad, bs }` or `null`.
+- **Outside values:** `setValue()` and `setOptions({ value })` never call `onChange`. Passing back the value the user just typed leaves their text alone, so the cursor doesn't jump.
+
+## Errors
+
+`state.error` is `{ code, message }`, with `code` one of `'format'`, `'range'`, `'disabled'`, `'tooShort'` or `'tooLong'`. The message is already translated, e.g. "Choose 2083-06-15 or later." or "वि.सं. मिति YYYY-MM-DD ढाँचामा लेख्नुहोस्।".
+
+## Presets
+
+Shortcuts shown beside the calendar. Weeks, months and years count in the calendar on screen, so "This month" is the BS month in BS mode.
+
+```ts
+createDateRangePicker({
+  presets: ['last7Days', 'thisMonth', 'lastMonth', 'thisFiscalYear', 'lastFiscalYear'],
+});
+createDatePicker({
+  presets: [
+    'today',
+    'yesterday',
+    { id: 'admission', label: 'Admission day', resolve: () => bsDate(2083, 1, 15) },
+  ],
+});
+picker.getState().presets; // [{ id, label, isActive, isDisabled }]
+picker.actions.applyPreset('thisFiscalYear'); // 2083-04-01 → 2084-03-32 BS
+```
+
+| Picker | Built-in presets                                                                                                                                  |
+| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Single | `today`, `yesterday`, `tomorrow`                                                                                                                  |
+| Range  | `today`, `yesterday`, `thisWeek`, `lastWeek`, `last7Days`, `last30Days`, `thisMonth`, `lastMonth`, `thisYear`, `thisFiscalYear`, `lastFiscalYear` |
+
+A preset is disabled when its range falls outside `min`/`max` or breaks `minDays`/`maxDays`.
+
+## Range picker
+
+```ts
+import { createDateRangePicker } from '@nepdatejs/datepicker';
+
+const range = createDateRangePicker({ minDays: 1, maxDays: 15 });
+range.actions.select(start); // a click in the panel
+range.actions.select(end);
+range.getState().value; // { start: '2026-10-22', end: '2026-10-25' }
+```
+
+## Date and time
+
+```ts
+import { createDateTimePicker } from '@nepdatejs/datepicker';
+
+const picker = createDateTimePicker({
+  minuteStep: 15,
+  defaultTime: '09:00',
+  hour12: true,
+});
+picker.actions.typeDate('2083-06-24');
+picker.actions.typeTime('2:30 pm');
+picker.getState().value; // "2026-10-10T14:30:00+05:45": one instant, with Nepal's offset
+picker.getState().hours; // hour cells for the time column; minutes likewise
+```
+
+Use `timeZone` to show and store another zone. Values without an offset are taken as wall times in that zone.
+
+## Multiple dates
+
+```ts
+import { createMultiDatePicker } from '@nepdatejs/datepicker';
+
+const picker = createMultiDatePicker({ maxDates: 5 });
+picker.actions.select(bsDate(2083, 7, 8)); // a click adds a day, a second click removes it
+picker.actions.type('2083-07-01, 2083-07-05'); // or type them, separated by commas
+picker.getState().value; // ['2026-10-18', '2026-10-22']: sorted AD days
+```
+
+Every store exposes the panel's calendar store as `.calendar` (see `@nepdatejs/calendar`). The pure helpers `parseInput`, `checkDate`, `formatInput` and `equivalentText` are exported too.
+
+MIT © Shishir Rai