@kodezen/kz-react-datepicker 1.0.0-beta.0

package/README.md

@@ -0,0 +1,147 @@
+# @kodezen/kz-react-datepicker
+
+A fully custom React date picker component built from scratch — no external date libraries. Supports range selection, single date, dark/light/auto themes, dynamic placements, shortcuts, and full customization via CSS variables.
+
+*Inspired by [react-advance-datepicker](https://github.com/danish1717/react-advance-datepicker).*
+
+## Preview
+
+| Light Mode | Dark Mode |
+|:---:|:---:|
+| ![Light Mode](./src/assets/images/demo-view/kz-react-datepicker-light-mode.png) | ![Dark Mode](./src/assets/images/demo-view/kz-react-datepicker-dark-mode.png) |
+
+## Requirements
+
+| Dependency | Version |
+|---|---|
+| Node.js | `>= 14.x` (recommended `>= 18.x`) |
+| React | `^16.8.0 \|\| ^17.0.0 \|\| ^18.0.0` |
+| react-dom | `^16.8.0 \|\| ^17.0.0 \|\| ^18.0.0` |
+
+> **Note:** React and react-dom are **peer dependencies** and must be installed in your project separately.
+
+## Installation
+
+```bash
+npm install @kodezen/kz-react-datepicker
+```
+
+## Basic Usage
+
+```jsx
+import React, { useState } from 'react';
+import DatePicker from '@kodezen/kz-react-datepicker';
+import '@kodezen/kz-react-datepicker/dist/index.css';
+
+const App = () => {
+  const [date, setDate] = useState(null);
+
+  return (
+    <DatePicker
+      value={date}
+      onChange={(newDate) => setDate(newDate)}
+    />
+  );
+};
+
+export default App;
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `{ startDate, endDate } \| null` | `null` | The selected date value. Each date can be a `Date` object or date string. |
+| `onChange` | `(value, e?) => void` | — | **Required.** Callback fired when the user selects a date. |
+| `asSingle` | `boolean` | `false` | If `true`, only allows picking a single date instead of a range. |
+| `useRange` | `boolean` | `true` | If `false`, hides the second calendar and disables range selection. |
+| `placeholder` | `string` | — | Input placeholder text. |
+| `displayFormat` | `string` | `"YYYY-MM-DD"` | Format string for how dates are displayed in the input. |
+| `separator` | `string` | `"~"` | String used to separate start and end dates in the input. |
+| `startFrom` | `Date \| string \| null` | `null` | The date the calendar should open to initially. |
+| `minDate` | `Date \| string \| null` | `null` | Minimum selectable date. |
+| `maxDate` | `Date \| string \| null` | `null` | Maximum selectable date. |
+| `disabledDates` | `Array<{ start, end }> \| null` | `null` | Array of date ranges to disable. |
+| `disabled` | `boolean` | `false` | Disables the entire input. |
+| `readOnly` | `boolean` | `false` | Makes the text input read-only (calendar still opens). |
+| `theme` | `"auto" \| "light" \| "dark"` | `"auto"` | Color theme. `"auto"` follows the OS system preference. |
+| `placement` | `"bottom" \| "top" \| "left" \| "right" \| "auto"` | `"bottom"` | Where the calendar popup opens relative to the input. `"auto"` picks the best position based on available screen space. |
+| `showShortcuts` | `boolean` | `false` | Show quick date shortcut buttons (e.g., Today, Last 7 days). |
+| `showFooter` | `boolean` | `false` | Show Apply/Cancel footer buttons. |
+| `shortcutText` | `string \| null` | `null` | Prefix label shown inside the input on the left side. |
+| `primaryColor` | `string` | `"blue"` | Primary accent color for the datepicker. |
+| `i18n` | `string` | `"en"` | Locale string for internationalization. |
+| `startWeekOn` | `"sun" \| "mon"` | `"sun"` | Day the week starts on. |
+| `dateLooking` | `"forward" \| "backward" \| "middle"` | `"forward"` | Controls how incomplete ranges are displayed. |
+| `inputId` | `string` | — | `id` attribute for the input element. |
+| `inputName` | `string` | — | `name` attribute for the input element. |
+| `inputClassName` | `string \| (cls: string) => string` | — | Custom class(es) for the input element. |
+| `containerClassName` | `string \| (cls: string) => string` | — | Custom class(es) for the outer container. |
+| `toggleClassName` | `string \| (cls: string) => string` | — | Custom class(es) for the calendar toggle button. |
+| `toggleIcon` | `(open: boolean) => ReactNode` | — | Custom icon component for the toggle button. |
+| `classNames` | `Object` | — | Fine-grained class overrides for sub-components. |
+| `configs` | `Object` | — | Advanced configuration options for shortcuts. |
+| `suffix` | `string` | `""` | Suffix appended to all internal CSS class names (useful for multiple instances). |
+| `popoverDirection` | `string` | — | Legacy popover direction override. Prefer `placement` instead. |
+
+## Styling & Customization
+
+The datepicker uses CSS Custom Properties (variables) for theming — no `!important` needed.
+
+### CSS Variables
+
+Override these in your `:root` or a parent selector:
+
+```css
+:root {
+  --kz-datepicker-primary: #3b82f6;       /* Accent / primary color */
+  --kz-datepicker-bg: #ffffff;            /* Background color */
+  --kz-datepicker-text: #374151;          /* Text color */
+  --kz-datepicker-border: #d1d5db;        /* Border color */
+  --kz-datepicker-border-radius: 4px;     /* Border radius */
+  --kz-datepicker-font-family: inherit;   /* Font family */
+  --kz-datepicker-hover-bg: #f3f4f6;     /* Hover background */
+}
+```
+
+### Class Prop Overrides
+
+Use these props to inject custom classes into different parts:
+
+| Prop | Targets |
+|---|---|
+| `containerClassName` | Outer wrapper `<div>` |
+| `inputClassName` | The text `<input>` |
+| `toggleClassName` | Calendar toggle `<button>` |
+| `dayClassName` *(via classNames)* | Individual day cells |
+| `calendarClassName` *(via classNames)* | Calendar popover container |
+
+## Theme Examples
+
+```jsx
+// Follow OS preference (default)
+<DatePicker value={date} onChange={setDate} theme="auto" />
+
+// Always light
+<DatePicker value={date} onChange={setDate} theme="light" />
+
+// Always dark
+<DatePicker value={date} onChange={setDate} theme="dark" />
+```
+
+## Placement Examples
+
+```jsx
+// Opens below (default)
+<DatePicker value={date} onChange={setDate} placement="bottom" />
+
+// Opens above
+<DatePicker value={date} onChange={setDate} placement="top" />
+
+// Auto-detect based on available viewport space
+<DatePicker value={date} onChange={setDate} placement="auto" />
+```
+
+## License
+
+ISC

package/dist/index.cjs.css

@@ -0,0 +1,2 @@
+:root{--kz-datepicker-primary:#007bff;--kz-datepicker-bg:#fff;--kz-datepicker-text:#333;--kz-datepicker-border:#ccc;--kz-datepicker-border-radius:4px;--kz-datepicker-font-family:inherit;--kz-datepicker-hover-bg:#f0f0f0}.kz-datepicker{color:var(--kz-datepicker-text);display:inline-block;font-family:var(--kz-datepicker-font-family);position:relative}.kz-datepicker-input{background-color:var(--kz-datepicker-bg);border:1px solid var(--kz-datepicker-border);border-radius:var(--kz-datepicker-border-radius);color:inherit;cursor:pointer;font-family:inherit;outline:none;padding:8px 12px}.kz-datepicker-input:focus{border-color:var(--kz-datepicker-primary);box-shadow:0 0 0 2px rgba(0,123,255,.25)}.kz-datepicker-calendar{background-color:var(--kz-datepicker-bg);border:1px solid var(--kz-datepicker-border);border-radius:var(--kz-datepicker-border-radius);box-shadow:0 4px 6px rgba(0,0,0,.1);left:0;padding:16px;position:absolute;top:calc(100% + 4px);z-index:1000}
+/*# sourceMappingURL=index.cjs.css.map */

package/dist/index.cjs.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["index.scss"],"names":[],"mappings":"AAAA,MACE,+BAAgC,CAChC,uBAA2B,CAC3B,yBAA6B,CAC7B,2BAA+B,CAC/B,iCAAkC,CAClC,mCAAoC,CACpC,gCACF,CAEA,eAIE,+BAAgC,CADhC,oBAAqB,CAFrB,4CAA6C,CAC7C,iBAGF,CACA,qBAIE,wCAAyC,CAFzC,4CAA6C,CAC7C,gDAAiD,CAEjD,aAAc,CAEd,cAAe,CADf,mBAAoB,CAEpB,YAAa,CAPb,gBAQF,CACA,2BACE,yCAA0C,CAC1C,wCACF,CACA,wBAKE,wCAAyC,CACzC,4CAA6C,CAC7C,gDAAiD,CAEjD,mCAAwC,CANxC,MAAO,CAKP,YAAa,CAPb,iBAAkB,CAClB,oBAAqB,CAErB,YAMF","file":"index.cjs.css","sourcesContent":[":root {\n  --kz-datepicker-primary: #007bff;\n  --kz-datepicker-bg: #ffffff;\n  --kz-datepicker-text: #333333;\n  --kz-datepicker-border: #cccccc;\n  --kz-datepicker-border-radius: 4px;\n  --kz-datepicker-font-family: inherit;\n  --kz-datepicker-hover-bg: #f0f0f0;\n}\n\n.kz-datepicker {\n  font-family: var(--kz-datepicker-font-family);\n  position: relative;\n  display: inline-block;\n  color: var(--kz-datepicker-text);\n}\n.kz-datepicker-input {\n  padding: 8px 12px;\n  border: 1px solid var(--kz-datepicker-border);\n  border-radius: var(--kz-datepicker-border-radius);\n  background-color: var(--kz-datepicker-bg);\n  color: inherit;\n  font-family: inherit;\n  cursor: pointer;\n  outline: none;\n}\n.kz-datepicker-input:focus {\n  border-color: var(--kz-datepicker-primary);\n  box-shadow: 0 0 0 2px rgba(0, 123, 255, 0.25);\n}\n.kz-datepicker-calendar {\n  position: absolute;\n  top: calc(100% + 4px);\n  left: 0;\n  z-index: 1000;\n  background-color: var(--kz-datepicker-bg);\n  border: 1px solid var(--kz-datepicker-border);\n  border-radius: var(--kz-datepicker-border-radius);\n  padding: 16px;\n  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);\n}"]}