# stephy/calendarpicker architecture

> Architecture diagram of the GitHub repository stephy/calendarpicker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stephy/calendarpicker
- Repository: https://github.com/stephy/calendarpicker

## Overview

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

Main entry points: [`CalendarPicker/index.js`](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/index.js) (CalendarPicker), [`CalendarPicker/DaysGridView.js`](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/DaysGridView.js) (Days grid), [`CalendarPicker/MonthSelector.js`](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/MonthSelector.js) (Month selector), [`CalendarPicker/YearSelector.js`](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/YearSelector.js) (Year selector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_library["Library"]
  node_entrypoint["CalendarPicker<br/>public API<br/>[index.js]"]
  node_picker_day["Day cell<br/>day view<br/>[Day.js]"]
  node_picker_daysgrid["Days grid<br/>day grid<br/>[DaysGridView.js]"]
  node_picker_emptyday["Empty day<br/>calendar slot<br/>[EmptyDay.js]"]
  node_picker_weekdays["Weekdays<br/>weekday header<br/>[Weekdays.js]"]
  node_picker_month["Month cell<br/>month view<br/>[Month.js]"]
  node_picker_monthselector["Month selector<br/>month nav<br/>[MonthSelector.js]"]
  node_picker_monthsgrid["Months grid<br/>month grid<br/>[MonthsGridView.js]"]
  node_picker_monthsheader["Months header<br/>month header<br/>[MonthsHeader.js]"]
  node_picker_year["Year cell<br/>year view<br/>[Year.js]"]
  node_picker_yearselector["Year selector<br/>year nav<br/>[YearSelector.js]"]
  node_picker_yearsgrid["Years grid<br/>year grid<br/>[YearsGridView.js]"]
  node_picker_yearsheader["Years header<br/>year header<br/>[YearsHeader.js]"]
  node_picker_controls["Controls<br/>navigation<br/>[Controls.js]"]
  node_picker_headercontrols["Header controls<br/>header nav<br/>[HeaderControls.js]"]
  node_picker_scroller["Scroller<br/>scroll nav<br/>[Scroller.js]"]
  node_picker_utils["Utils<br/>date logic<br/>[Utils.js]"]
  node_picker_styles["Styles<br/>style factory<br/>[makeStyles.js]"]
  node_picker_props["Prop types<br/>contract<br/>[localPropTypes.js]"]
  node_picker_tests["Component tests<br/>test suite"]
end

subgraph group_examples["Examples"]
  node_example_js_app["Example app<br/>expo sample<br/>[App.js]"]
  node_example_ts_app["TS app<br/>expo sample<br/>[App.tsx]"]
  node_example_ts_calendar["Calendar view<br/>demo component<br/>[index.tsx]"]
  node_example_ts_button["Button<br/>demo component<br/>[index.tsx]"]
  node_example_ts_colors["Colors<br/>shared constants<br/>[colors.ts]"]
end

subgraph group_tooling["Tooling"]
  node_package_config["Package config<br/>package metadata<br/>[package.json]"]
  node_build_lint["Build & lint<br/>tooling config"]
end

node_entrypoint -->|"renders"| node_picker_day
node_entrypoint -->|"shows"| node_picker_daysgrid
node_entrypoint -->|"switches to"| node_picker_monthselector
node_entrypoint -->|"switches to"| node_picker_yearselector
node_entrypoint -->|"navigates"| node_picker_controls
node_entrypoint -->|"optional mode"| node_picker_scroller
node_entrypoint -->|"uses"| node_picker_utils
node_entrypoint -->|"styles via"| node_picker_styles
node_entrypoint -->|"validated by"| node_picker_props
node_picker_daysgrid -->|"fills"| node_picker_emptyday
node_picker_daysgrid -->|"labels"| node_picker_weekdays
node_picker_daysgrid -->|"computes"| node_picker_utils
node_picker_daysgrid -->|"styles via"| node_picker_styles
node_picker_monthselector -->|"lists"| node_picker_month
node_picker_monthselector -->|"lays out"| node_picker_monthsgrid
node_picker_monthselector -->|"headed by"| node_picker_monthsheader
node_picker_yearselector -->|"lists"| node_picker_year
node_picker_yearselector -->|"lays out"| node_picker_yearsgrid
node_picker_yearselector -->|"headed by"| node_picker_yearsheader
node_picker_controls -->|"wraps"| node_picker_headercontrols
node_picker_scroller -->|"advances dates"| node_picker_utils
node_example_js_app -->|"consumes"| node_entrypoint
node_example_ts_app -->|"hosts"| node_example_ts_calendar
node_example_ts_calendar -->|"consumes"| node_entrypoint
node_example_ts_calendar -->|"uses"| node_example_ts_button
node_example_ts_calendar -->|"styles from"| node_example_ts_colors
node_package_config -->|"publishes"| node_entrypoint
node_build_lint -->|"validates"| node_entrypoint
node_picker_tests -->|"tests"| node_entrypoint

click node_entrypoint "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/index.js"
click node_picker_day "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/Day.js"
click node_picker_daysgrid "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/DaysGridView.js"
click node_picker_emptyday "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/EmptyDay.js"
click node_picker_weekdays "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/Weekdays.js"
click node_picker_month "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/Month.js"
click node_picker_monthselector "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/MonthSelector.js"
click node_picker_monthsgrid "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/MonthsGridView.js"
click node_picker_monthsheader "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/MonthsHeader.js"
click node_picker_year "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/Year.js"
click node_picker_yearselector "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/YearSelector.js"
click node_picker_yearsgrid "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/YearsGridView.js"
click node_picker_yearsheader "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/YearsHeader.js"
click node_picker_controls "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/Controls.js"
click node_picker_headercontrols "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/HeaderControls.js"
click node_picker_scroller "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/Scroller.js"
click node_picker_utils "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/Utils.js"
click node_picker_styles "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/makeStyles.js"
click node_picker_props "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/localPropTypes.js"
click node_picker_tests "https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/__tests__/CalendarPicker-test.js"
click node_example_js_app "https://github.com/stephy/calendarpicker/blob/master/example/example/App.js"
click node_example_ts_app "https://github.com/stephy/calendarpicker/blob/master/example/example_typescript/App.tsx"
click node_example_ts_calendar "https://github.com/stephy/calendarpicker/blob/master/example/example_typescript/src/components/CalendarView/index.tsx"
click node_example_ts_button "https://github.com/stephy/calendarpicker/blob/master/example/example_typescript/src/components/Button/index.tsx"
click node_example_ts_colors "https://github.com/stephy/calendarpicker/blob/master/example/example_typescript/src/global/colors.ts"
click node_package_config "https://github.com/stephy/calendarpicker/blob/master/package.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entrypoint,node_picker_day,node_picker_daysgrid,node_picker_emptyday,node_picker_weekdays,node_picker_month,node_picker_monthselector,node_picker_monthsgrid,node_picker_monthsheader,node_picker_year,node_picker_yearselector,node_picker_yearsgrid,node_picker_yearsheader,node_picker_controls,node_picker_headercontrols,node_picker_scroller,node_picker_utils,node_picker_styles,node_picker_props,node_picker_tests toneBlue
class node_example_js_app,node_example_ts_app,node_example_ts_calendar,node_example_ts_button,node_example_ts_colors toneAmber
class node_package_config,node_build_lint toneMint
```

## Components

### Library

Published CalendarPicker component and its internal view/state modules.

- [CalendarPicker](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/index.js): public API · Library entrypoint and exported component surface. · `CalendarPicker/index.js`
- [Day cell](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/Day.js): day view · Individual selectable day rendering and state styling. · `CalendarPicker/Day.js`
- [Days grid](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/DaysGridView.js): day grid · Month day grid and day-selection layout. · `CalendarPicker/DaysGridView.js`
- [Empty day](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/EmptyDay.js): calendar slot · Leading and trailing placeholder cells in the month grid. · `CalendarPicker/EmptyDay.js`
- [Weekdays](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/Weekdays.js): weekday header · Weekday labels above the day grid. · `CalendarPicker/Weekdays.js`
- [Month cell](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/Month.js): month view · Single month item used in month browsing and selection. · `CalendarPicker/Month.js`
- [Month selector](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/MonthSelector.js): month nav · Month selection view and switching logic. · `CalendarPicker/MonthSelector.js`
- [Months grid](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/MonthsGridView.js): month grid · Grid layout for browsing months. · `CalendarPicker/MonthsGridView.js`
- [Months header](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/MonthsHeader.js): month header · Header controls for month view navigation. · `CalendarPicker/MonthsHeader.js`
- [Year cell](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/Year.js): year view · Single year item used in year browsing and selection. · `CalendarPicker/Year.js`
- [Year selector](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/YearSelector.js): year nav · Year selection view and switching logic. · `CalendarPicker/YearSelector.js`
- [Years grid](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/YearsGridView.js): year grid · Grid layout for browsing years. · `CalendarPicker/YearsGridView.js`
- [Years header](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/YearsHeader.js): year header · Header controls for year view navigation. · `CalendarPicker/YearsHeader.js`
- [Controls](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/Controls.js): navigation · Previous/next navigation actions for the picker. · `CalendarPicker/Controls.js`
- [Header controls](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/HeaderControls.js): header nav · Header-level navigation UI and action wiring. · `CalendarPicker/HeaderControls.js`
- [Scroller](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/Scroller.js): scroll nav · Scrollable infinite month navigation mode. · `CalendarPicker/Scroller.js`
- [Utils](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/Utils.js): date logic · Shared date computations, bounds checks, and selection helpers. · `CalendarPicker/Utils.js`
- [Styles](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/makeStyles.js): style factory · Style generation from props and customization inputs. · `CalendarPicker/makeStyles.js`
- [Prop types](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/localPropTypes.js): contract · Component prop contract and validation shape. · `CalendarPicker/localPropTypes.js`
- [Component tests](https://github.com/stephy/calendarpicker/blob/master/CalendarPicker/__tests__/CalendarPicker-test.js): test suite · Focused unit tests at the CalendarPicker boundary. · `CalendarPicker/__tests__/CalendarPicker-test.js`

### Examples

Expo sample apps that demonstrate library integration in JavaScript and TypeScript.

- [Example app](https://github.com/stephy/calendarpicker/blob/master/example/example/App.js): expo sample · JavaScript Expo sample demonstrating library usage. · `example/example/App.js`
- [TS app](https://github.com/stephy/calendarpicker/blob/master/example/example_typescript/App.tsx): expo sample · TypeScript Expo sample app shell for the picker demo. · `example/example_typescript/App.tsx`
- [Calendar view](https://github.com/stephy/calendarpicker/blob/master/example/example_typescript/src/components/CalendarView/index.tsx): demo component · Typed demo wrapper that configures and renders the picker. · `example/example_typescript/src/components/CalendarView/index.tsx`
- [Button](https://github.com/stephy/calendarpicker/blob/master/example/example_typescript/src/components/Button/index.tsx): demo component · Shared button used by the TypeScript demo UI. · `example/example_typescript/src/components/Button/index.tsx`
- [Colors](https://github.com/stephy/calendarpicker/blob/master/example/example_typescript/src/global/colors.ts): shared constants · Shared palette values for the TypeScript sample app. · `example/example_typescript/src/global/colors.ts`

### Tooling

Repository validation, linting, and package-level configuration.

- [Package config](https://github.com/stephy/calendarpicker/blob/master/package.json): package metadata · Repository package metadata and entry configuration. · `package.json`
- **Build & lint**: tooling config · Babel, Flow, ESLint, and CI configuration for development validation.

## Connections

- CalendarPicker → Day cell: renders · Public component delegates day-cell rendering to the day subsystem.
- CalendarPicker → Days grid: shows · Main picker renders the day grid in month view.
- CalendarPicker → Month selector: switches to · Picker can enter month selection mode.
- CalendarPicker → Year selector: switches to · Picker can enter year selection mode.
- CalendarPicker → Controls: navigates · Picker exposes button-driven navigation actions.
- CalendarPicker → Scroller: optional mode · Scrollable mode replaces button navigation with recycled month scrolling.
- CalendarPicker → Utils: uses · Date normalization and constraint logic feed the component state.
- CalendarPicker → Styles: styles via · Customization props are transformed into style objects.
- CalendarPicker → Prop types: validated by · Component API is defined by local prop contracts.
- Days grid → Empty day: fills · Grid uses placeholders for leading and trailing slots.
- Days grid → Weekdays: labels · Day grid is aligned with weekday headers.
- Days grid → Utils: computes · Grid state depends on date math and selection constraints.
- Days grid → Styles: styles via · Cell appearance is derived from style generation.
- Month selector → Month cell: lists · Month selector is built from month cells.
- Month selector → Months grid: lays out · Month browsing uses a grid view.
- Month selector → Months header: headed by · Month selector uses its header controls.
- Year selector → Year cell: lists · Year selector is built from year cells.
- Year selector → Years grid: lays out · Year browsing uses a grid view.
- Year selector → Years header: headed by · Year selector uses its header controls.
- Controls → Header controls: wraps · Navigation controls drive header UI interactions.
- Scroller → Utils: advances dates · Scrollable navigation depends on date calculations.
- Example app → CalendarPicker: consumes · JavaScript sample imports and renders the library component.
- TS app → Calendar view: hosts · TypeScript app mounts the calendar demo component.
- Calendar view → CalendarPicker: consumes · Typed demo wrapper configures the library picker.
- Calendar view → Button: uses · Demo UI includes reusable buttons.
- Calendar view → Colors: styles from · Demo styling depends on shared color constants.
- Package config → CalendarPicker: publishes · Package metadata points to the library entry surface.
- Build & lint → CalendarPicker: validates · Tooling checks the library source during development and CI.
- Component tests → CalendarPicker: tests · Unit tests cover the component boundary behavior.