stephy/calendarpicker

1. What this repo is

- This is a React Native component library that exports a single calendar/date-picker widget, CalendarPicker.

- The repo is split into the reusable library code, a test suite, and two sample apps (example and example_typescript) that demonstrate integration.

2. Public API boundary

- The library’s entrypoint is CalendarPicker/index.js.

- Consumers import the component and configure it entirely through props: selection mode, date bounds, labels, localization, styling, and initial view.

- The component also exposes a small imperative API through refs, such as moving between months, selecting a date programmatically, clearing selections, and jumping to a date.

3. Core rendering model

- The widget is built from a hierarchy of view components under CalendarPicker/.

- The main picker orchestrates which subview is shown: days, months, or years.

- This makes the architecture state-driven: the current date/view state determines whether the user sees a month grid, month selector, year selector, or the day grid.

4. Day-selection subsystem

- Day rendering and selection live in the day-oriented components:

- Day.js for an individual day cell

- DaysGridView.js for the month’s day grid

- EmptyDay.js for leading/trailing placeholder slots

- Weekdays.js for weekday headers

- These components translate calendar state into selectable cells, disabled cells, today highlighting, and range-selection styling.

5. Month and year navigation subsystem

- Month.js, MonthSelector.js, MonthsGridView.js, and MonthsHeader.js handle month browsing and selection.

- Year.js, YearSelector.js, YearsGridView.js, and YearsHeader.js do the same for years.

- The picker can start in any of these views via initialView, so view switching is a first-class part of the component architecture, not an afterthought.

6. Navigation controls and scroller

- Controls.js and HeaderControls.js implement previous/next navigation and header UI.

- Scroller.js supports the scrollable mode described in the README, where months are recycled in an infinite bidirectional scroll pattern.

- This creates two navigation paths:

- button/header-driven month changes

- scroll-driven month changes in scrollable mode

7. Date logic and constraints

- Utils.js holds shared date computations and helper logic.

- The calendar’s behavior is constrained by props such as minDate, maxDate, disabledDates, allowRangeSelection, and allowBackwardRangeSelect.

- Data flow is: incoming props and current selection state are normalized into per-day affordances, then each cell decides whether it is selectable, disabled, or part of a range.

8. Styling and customization boundary

- makeStyles.js centralizes style generation from props.

- localPropTypes.js defines the component’s prop contract.

- The README’s customization options map to this layer: selected/today styling, custom date styles, weekday header styles, text styles, shapes, and container styles.

- This architecture keeps the visual customization surface outside the calendar logic itself.

9. Callbacks and external interaction

- User interactions flow outward through callbacks like onDateChange and onMonthChange.

- Internally, a tap on a day or a navigation action updates component state, then emits the appropriate callback to the host app.

- For range selection, the callback distinguishes start vs. end selection, which is why the public API returns a second parameter such as START_DATE or END_DATE.

10. Testing

- There is a focused unit test suite in CalendarPicker/__tests__/CalendarPicker-test.js.

- This suggests the library’s core behavior is validated at the component boundary rather than through broad end-to-end coverage.

11. Example applications

- example/example is an Expo sample app in JavaScript.

- example/example_typescript is a parallel Expo sample in TypeScript, with its own app shell plus demo components under src/components.

- These apps are integration sandboxes, not part of the published library runtime.

12. TypeScript and sample app structure

- The TypeScript example wraps the calendar demo in a small app-level component tree, including a configurable CalendarView, Button, and shared color constants.

- This demonstrates how the library is consumed in a typed app, while keeping the actual picker implementation in the root library package.

13. Tooling and repo boundaries

- The repo uses Babel, Flow, ESLint, and Travis CI for library development and validation.

- A pre-commit hook and lint config indicate the project is maintained as a publishable package with code quality checks.

- The README notes that sample app source is copied from the root into example, reinforcing the separation between the distributable component and the demo app.

14. High-level diagram summary

- Think of the architecture as:

- Consumer app calls into CalendarPicker public API

- CalendarPicker container/state computes current view, selection, and constraints

- Day/Month/Year subcomponents render the appropriate calendar UI

- Utils + makeStyles provide date calculations and visual mapping

- Callbacks/ref methods send changes back to the consumer

- Example apps show the integration boundary, not core logic