best-react-datepicker 0.2.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 best-react-datepicker contributors
+
+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

@@ -0,0 +1,273 @@
+# best-react-datepicker
+
+The most customizable, accessible, zero-dependency React date picker.
+
+- **7 picker components** — DatePicker, RangePicker, TimePicker, DateTimePicker, MonthPicker, YearPicker, WeekPicker
+- **Zero dependencies** — only React as a peer dependency
+- **Fully accessible** — keyboard navigation, ARIA labels, screen reader announcements
+- **CSS variable theming** — change one variable to retheme everything
+- **Dark mode** — built-in dark theme via `.brdp-dark` class
+- **Size variants** — `sm`, `md`, `lg` prop on all pickers
+- **Month/Year dropdowns** — native select elements for quick date jumps
+- **Range presets** — built-in preset helper with active state tracking
+- **Compact range mode** — single-calendar layout with presets below
+- **TypeScript** — full type definitions included
+
+## Install
+
+```bash
+npm install best-react-datepicker
+```
+
+## Quick Start
+
+```tsx
+import { DatePicker } from 'best-react-datepicker';
+import 'best-react-datepicker/styles.css';
+
+function App() {
+  const [date, setDate] = useState<Date | null>(null);
+
+  return (
+    <DatePicker
+      value={date}
+      onChange={setDate}
+      placeholder="Pick a date"
+    />
+  );
+}
+```
+
+## Components
+
+### DatePicker
+
+Single date selection with optional constraints.
+
+```tsx
+<DatePicker
+  value={date}
+  onChange={setDate}
+  placeholder="Pick a date"
+  minDate={new Date(2026, 0, 1)}
+  maxDate={new Date(2026, 11, 31)}
+  disabled={{ dayOfWeek: [0, 6] }}
+  clearable
+  size="md"
+/>
+```
+
+### RangePicker
+
+Date range selection with optional presets.
+
+```tsx
+import { RangePicker, createPresets } from 'best-react-datepicker';
+
+const presets = createPresets();
+
+<RangePicker
+  value={range}
+  onChange={setRange}
+  presets={presets}
+  showPresets
+  numberOfMonths={2}
+/>
+```
+
+**Compact mode** — single calendar with presets below:
+
+```tsx
+<RangePicker
+  value={range}
+  onChange={setRange}
+  presets={presets}
+  showPresets
+  compact
+  closeOnSelect
+/>
+```
+
+### TimePicker
+
+```tsx
+<TimePicker
+  value={time}
+  onChange={setTime}
+  minuteStep={5}
+  format="12h"
+/>
+```
+
+### DateTimePicker
+
+Combined date and time selection with tabbed interface.
+
+```tsx
+<DateTimePicker
+  value={dateTime}
+  onChange={setDateTime}
+  placeholder="Pick date & time"
+/>
+```
+
+### MonthPicker
+
+```tsx
+<MonthPicker
+  value={monthDate}
+  onChange={setMonthDate}
+  placeholder="Pick a month"
+/>
+```
+
+### YearPicker
+
+```tsx
+<YearPicker
+  value={year}
+  onChange={setYear}
+  placeholder="Pick a year"
+/>
+```
+
+### WeekPicker
+
+```tsx
+<WeekPicker
+  onChange={(start, end, weekNumber) => {
+    console.log(`Week ${weekNumber}: ${start} – ${end}`);
+  }}
+/>
+```
+
+## Size Variants
+
+All pickers accept a `size` prop: `"sm"`, `"md"` (default), or `"lg"`.
+
+```tsx
+<DatePicker size="sm" placeholder="Small" />
+<DatePicker size="md" placeholder="Medium" />
+<DatePicker size="lg" placeholder="Large" />
+```
+
+## Presets
+
+Use `createPresets()` to generate common range presets:
+
+```tsx
+import { createPresets } from 'best-react-datepicker';
+
+// All built-in presets
+const presets = createPresets();
+
+// Select specific presets
+const presets = createPresets({
+  include: ['today', 'last7', 'last30', 'thisMonth'],
+});
+
+// Add custom presets
+const presets = createPresets({
+  include: ['today', 'last7'],
+  custom: [
+    {
+      label: 'Next 7 days',
+      value: () => ({ from: new Date(), to: addDays(new Date(), 6) }),
+    },
+  ],
+});
+```
+
+Built-in preset keys: `today`, `yesterday`, `last7`, `last30`, `thisMonth`, `lastMonth`, `thisYear`
+
+## Theming
+
+Override CSS variables to match your brand:
+
+```tsx
+<div style={{
+  '--brdp-color-accent': '#8b5cf6',
+  '--brdp-color-accent-light': '#ede9fe',
+  '--brdp-color-accent-dark': '#7c3aed',
+}}>
+  <DatePicker placeholder="Purple theme" />
+</div>
+```
+
+### Dark Mode
+
+```tsx
+<div className="brdp-dark">
+  <DatePicker placeholder="Dark mode" />
+</div>
+```
+
+Or use the data attribute:
+
+```html
+<div data-brdp-theme="dark">...</div>
+```
+
+### Key CSS Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `--brdp-color-accent` | `#2563eb` | Primary accent color |
+| `--brdp-color-accent-light` | `#dbeafe` | Light accent (range background) |
+| `--brdp-color-accent-dark` | `#1d4ed8` | Dark accent (hover states) |
+| `--brdp-color-bg` | `#ffffff` | Background color |
+| `--brdp-color-text` | `#111827` | Text color |
+| `--brdp-color-border` | `#e5e7eb` | Border color |
+| `--brdp-cell-size` | `40px` | Day cell size |
+| `--brdp-radius-day` | `9999px` | Day cell border radius |
+| `--brdp-font-family` | `inherit` | Font family |
+
+## Headless Usage
+
+Use the hooks directly for full control over rendering:
+
+```tsx
+import { useDatePicker } from 'best-react-datepicker/hooks';
+
+function CustomDatePicker() {
+  const picker = useDatePicker({
+    onChange: (date) => console.log(date),
+    closeOnSelect: true,
+  });
+
+  // Build your own UI using picker state and methods
+  return <div>{/* your custom UI */}</div>;
+}
+```
+
+Available hooks: `useDatePicker`, `useRangePicker`, `useTimePicker`, `useDateTimePicker`, `useMonthPicker`, `useYearPicker`, `useWeekPicker`, `useCalendar`, `useMultiPicker`
+
+## Utilities
+
+Date utilities are available as a separate entry point:
+
+```tsx
+import {
+  addDays,
+  subMonths,
+  startOfMonth,
+  formatDate,
+  parseDate,
+} from 'best-react-datepicker/utils';
+```
+
+## Accessibility
+
+- Full keyboard navigation (arrow keys, Home/End, Page Up/Down, Escape)
+- ARIA labels on all interactive elements
+- Live region announcements for month changes
+- Focus trapping within popover
+- Screen reader support for selected states
+
+## Browser Support
+
+All modern browsers (Chrome, Firefox, Safari, Edge).
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "best-react-datepicker",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The most customizable, accessible, zero-dependency React date picker",
   "license": "MIT",
   "type": "module",