Merge remote-tracking branch 'origin/main' into fix/5939

Author: martijnrusschen

CLAUDE.md

@@ -1 +1,164 @@
-Use yarn instead of npm for running commands
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Package Manager
+
+**Always use `yarn` instead of `npm`** for all commands in this repository (yarn@4.9.2).
+
+## Common Commands
+
+### Development
+
+- `yarn install` - Install dependencies (run from project root)
+- `yarn start` - Start the docs-site development server at http://localhost:5173
+- `yarn build` - Full production build (JS + CSS in all formats)
+- `yarn build-dev` - Development build with file watching
+
+### Testing and Quality
+
+- `yarn test` - Run the full test suite (Jest with ts-jest)
+- `yarn test src/test/calendar_test.test.tsx` - Run a single test file
+- `yarn test:watch` - Run tests in watch mode
+- `yarn test:ci` - Run tests with coverage for CI
+- `yarn lint` - Run both ESLint and Stylelint
+- `yarn eslint` - Run ESLint on src directory
+- `yarn sass-lint` - Run Stylelint on SCSS files
+- `yarn type-check` - Run TypeScript type checking without emitting files
+- `yarn prettier` - Format all JS/JSX/TS/TSX files
+- `yarn prettier:check` - Check formatting without making changes
+
+### Building Individual Pieces
+
+- `yarn build:src` - Build JS using Rollup
+- `yarn js:dev` - Build JS in watch mode
+- `yarn css:prod` - Build minified production CSS
+- `yarn css:dev` - Build expanded development CSS
+- `yarn css:modules:prod` - Build CSS modules (minified)
+- `yarn css:modules:dev` - Build CSS modules (expanded)
+
+## Architecture Overview
+
+### Component Hierarchy
+
+The main entry point is `src/index.tsx` which exports the `DatePicker` component. The component hierarchy flows as follows:
+
+```
+DatePicker (index.tsx) - Main component, class-based
+├── PopperComponent (popper_component.tsx) - Positioned calendar container
+│   ├── withFloating HOC (with_floating.tsx) - Floating UI integration
+│   ├── Portal (portal.tsx) - Optional portal rendering
+│   └── TabLoop (tab_loop.tsx) - Keyboard navigation wrapper
+│       └── Calendar (calendar.tsx) - Core calendar logic
+│           ├── ClickOutsideWrapper - Handles outside clicks
+│           ├── Month/Year/Time components - Date selection UI
+│           └── Various dropdowns for date navigation
+```
+
+### Key Architectural Patterns
+
+**Positioning System**: The datepicker uses `@floating-ui/react` (v0.27.15) for positioning the calendar relative to the input. The `withFloating` HOC wraps `PopperComponent` to provide positioning logic.
+
+**Date Utilities**: All date manipulation goes through `date_utils.ts`, which wraps `date-fns` (v4.1.0). This provides a consistent API across the codebase and makes it easier to maintain date-related logic.
+
+**State Management**: The main `DatePicker` component is class-based and manages state internally. Most child components are controlled components that receive props and callbacks.
+
+**Styling**: SCSS source files live in `src/stylesheets/`. The build process generates multiple CSS outputs:
+
+- Regular CSS: `react-datepicker.css` (dev) and `react-datepicker.min.css` (prod)
+- CSS Modules: `react-datepicker-cssmodules.css` and `react-datepicker.module.css`
+
+### Build Output
+
+Rollup (configured in `rollup.config.mjs`) generates multiple bundle formats in the `dist/` directory:
+
+- **UMD**: `react-datepicker.js` and `react-datepicker.min.js` (browser)
+- **CommonJS**: `index.js` (Node/bundlers)
+- **ES Modules**: `index.es.js` (modern bundlers)
+- **Types**: `index.d.ts` (TypeScript definitions)
+
+### Testing Architecture
+
+Tests use Jest with `@testing-library/react` and are located in `src/test/`. The test setup:
+
+- Configuration: `jest.config.js`
+- Setup file: `src/test/index.ts`
+- Helper components: `src/test/helper_components/`
+- Coverage is collected and reported to Codecov
+
+**Important for tests**: Some components use ShadowDOM for testing. The `shadow_root.tsx` helper uses `flushSync` to ensure synchronous updates required by tests.
+
+### Floating UI Integration Notes
+
+The codebase uses `@floating-ui/react` for positioning. **Important**: The Floating UI library requires refs and context to be accessed during render, which is by design. When fixing linting errors:
+
+- Use `eslint-disable` comments for Floating UI ref accesses (e.g., `popperProps.refs.setFloating`, `popperProps.context`, `arrowRef`)
+- These are **not** violations of React best practices—they're intentional library usage
+- See `popper_component.tsx` and `with_floating.tsx` for examples
+
+### React Hooks Rules
+
+This codebase uses `eslint-plugin-react-hooks` v7.0.1+ which has strict rules about:
+
+- **Ref access during render**: Generally not allowed, but see Floating UI exception above
+- **setState in effects**: Avoid calling setState directly in effects; use `flushSync` when synchronous updates are needed
+- When refs must be updated based on props, do it in `useEffect`, not during render
+
+## Development Workflow
+
+### Local Development Setup (Full)
+
+1. Install node >=16.0.0 and yarn >=4.6.x
+2. `yarn install` from project root
+3. `yarn build` from project root (generates dist/ directory)
+4. `yarn start` to launch docs at http://localhost:5173
+5. In a new terminal, run `yarn build-dev` to auto-rebuild on changes
+
+**Note**: The docs-site uses a portal: dependency (`"react-datepicker": "portal:../"`) which links to the parent project. Changes to the main package are reflected in the docs when you rebuild.
+
+### Alternative Setup with yarn link (from CONTRIBUTING.md)
+
+If you need tighter integration during development:
+
+1. Run `yarn link` from project root
+2. Run `cd docs-site && yarn link react-datepicker`
+3. Then follow steps above
+
+### Quick Development Workflow
+
+After initial setup, when making changes:
+
+- **JS/TS changes**: Changes auto-rebuild if `yarn build-dev` is running
+- **SCSS changes**: Run `yarn run css:dev && yarn run css:modules:dev`
+
+### Pre-commit Hooks
+
+The repo uses Husky with lint-staged. On commit:
+
+- Prettier formats staged files automatically
+- Files are automatically added to the commit (via `git add` in lint-staged config)
+
+## Dependencies
+
+### Core Runtime Dependencies
+
+- `react` and `react-dom` (^16.9.0 || ^17 || ^18 || ^19) - peer dependencies
+- `date-fns` (^4.1.0) - Date manipulation library
+- `@floating-ui/react` (^0.27.15) - Positioning engine
+- `clsx` (^2.1.1) - Conditional className utility
+
+### Important Dev Tools
+
+- **Build**: Rollup with Babel and TypeScript plugins
+- **Testing**: Jest, ts-jest, @testing-library/react, jest-axe
+- **Linting**: ESLint 9, TypeScript ESLint, Stylelint
+- **Formatting**: Prettier 3.4.2
+- **CSS**: Sass 1.93.2
+
+## Code Conventions
+
+- **Prettier handles all code formatting** - don't worry about tabs vs spaces
+- **ESLint enforces coding standards** - run `yarn lint` before committing
+- **TypeScript strict mode** - the codebase is fully typed
+- **Tests are required** - add Jest tests for new functionality
+- **Accessibility matters** - maintain ARIA attributes and keyboard navigation

README.md

@@ -62,6 +62,31 @@ You can use `onSelect` event handler which fires each time some calendar date ha
 
 See [here](https://github.com/Hacker0x01/react-datepicker/blob/main/docs/datepicker.md) for a full list of props that may be passed to the component. Examples are given on the [main website](https://hacker0x01.github.io/react-datepicker).
 
+### Working with Examples
+
+When using examples from the documentation site, note that they may reference utilities from external libraries. Common imports you might need:
+
+**Date manipulation** (from `date-fns`):
+
+```js
+import { getYear, getMonth, addDays, subDays, setHours, setMinutes } from "date-fns";
+```
+
+**Utility functions**:
+
+- For `range()` function used in custom headers: `import range from "lodash/range";`
+- Or implement your own: `const range = (start, end, step) => Array.from({ length: (end - start) / step }, (_, i) => start + i * step);`
+
+**TypeScript types**:
+
+```ts
+import type { ReactDatePickerCustomHeaderProps } from "react-datepicker";
+```
+
+All examples on the documentation site include commented import statements at the top showing exactly what you need to import for your own project.
+
+For a comprehensive guide on imports, see the [Common Imports Guide](https://github.com/Hacker0x01/react-datepicker/blob/main/docs/imports-guide.md).
+
 ### Time picker
 
 You can also include a time picker by adding the showTimeSelect prop

docs-site/package.json

@@ -6,7 +6,7 @@
   "dependencies": {
     "copy-to-clipboard": "^3.3.3",
     "date-fns": "^4.1.0",
-    "esbuild-wasm": "^0.25.11",
+    "esbuild-wasm": "^0.27.0",
     "highlight.js": "^11.11.1",
     "lodash": "^4.17.21",
     "prism-react-renderer": "^2.4.1",
@@ -24,21 +24,21 @@
     "type-check": "tsc --noEmit"
   },
   "devDependencies": {
-    "@eslint/js": "^9.37.0",
-    "@types/lodash": "^4.17.0",
-    "@types/react": "^19.2.2",
-    "@types/react-dom": "^19.2.2",
-    "@typescript-eslint/eslint-plugin": "^8.46.1",
-    "@typescript-eslint/parser": "^8.46.1",
-    "@vitejs/plugin-react": "^5.0.3",
-    "eslint": "^9.37.0",
+    "@eslint/js": "^9.39.1",
+    "@types/lodash": "^4.17.21",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.48.0",
+    "@typescript-eslint/parser": "^8.48.0",
+    "@vitejs/plugin-react": "^5.1.1",
+    "eslint": "^9.39.1",
     "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-react-hooks": "^7.0.0",
+    "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.4.24",
-    "globals": "^16.4.0",
-    "sass": "^1.93.2",
+    "globals": "^16.5.0",
+    "sass": "^1.94.2",
     "typescript": "^5.9.3",
-    "vite": "^7.1.10"
+    "vite": "^7.2.4"
   },
   "packageManager": "yarn@4.9.2"
 }

docs-site/src/examples/ts/calendarContainer.tsx

@@ -23,7 +23,7 @@ const CustomCalendarContainer = () => {
   return (
     <DatePicker
       selected={selectedDate}
-      onChange={(date: Date | null) => setSelectedDate(date)}
+      onChange={setSelectedDate}
       calendarContainer={MyContainer}
     />
   );

docs-site/src/examples/ts/calendarIcon.tsx

@@ -2,11 +2,7 @@ const CalendarIcon = () => {
   const [selectedDate, setSelectedDate] = useState<Date | null>(new Date());
 
   return (
-    <DatePicker
-      showIcon
-      selected={selectedDate}
-      onChange={(date: Date | null) => setSelectedDate(date)}
-    />
+    <DatePicker showIcon selected={selectedDate} onChange={setSelectedDate} />
   );
 };
 

docs-site/src/examples/ts/calendarIconExternal.tsx

@@ -5,7 +5,7 @@ const CalendarIconExternal = () => {
     <DatePicker
       showIcon
       selected={selectedDate}
-      onChange={(date: Date | null) => setSelectedDate(date)}
+      onChange={setSelectedDate}
       icon="fa fa-calendar"
     />
   );

docs-site/src/examples/ts/calendarIconSvgIcon.tsx

@@ -5,7 +5,7 @@ const CalendarIconSvgIcon = () => {
     <DatePicker
       showIcon
       selected={selectedDate}
-      onChange={(date: Date | null) => setSelectedDate(date)}
+      onChange={setSelectedDate}
       icon={
         <svg
           xmlns="http://www.w3.org/2000/svg"

docs-site/src/examples/ts/calendarStartDay.tsx

@@ -4,7 +4,7 @@ const CalendarStartDay = () => {
   return (
     <DatePicker
       selected={selectedDate}
-      onChange={(date: Date | null) => setSelectedDate(date)}
+      onChange={setSelectedDate}
       calendarStartDay={3}
     />
   );

docs-site/src/examples/ts/children.tsx

@@ -2,10 +2,7 @@ const Children = () => {
   const [selectedDate, setSelectedDate] = useState<Date | null>(new Date());
 
   return (
-    <DatePicker
-      selected={selectedDate}
-      onChange={(date: Date | null) => setSelectedDate(date)}
-    >
+    <DatePicker selected={selectedDate} onChange={setSelectedDate}>
       <div style={{ color: "red" }}>Don't forget to check the weather!</div>
     </DatePicker>
   );

docs-site/src/examples/ts/clearInput.tsx

@@ -4,7 +4,7 @@ const ClearInput = () => {
   return (
     <DatePicker
       selected={selectedDate}
-      onChange={(date: Date | null) => setSelectedDate(date)}
+      onChange={setSelectedDate}
       isClearable
       placeholderText="I have been cleared!"
     />