npm package: @hero-design/react-native-month-year-picker
Description: React Native Month Year Picker
Author: Kien Tran
Latest version: 8.45.3-test-auto-workflow.3

# @hero-design/react-native-month-year-picker

## Overview

A React Native library that provides native month and year picker components for iOS and Android. It includes platform-specific implementations (`MonthYearPickerViewIOS` for iOS, `MonthYearPickerDialogueAndroid` for Android), date range constraints, internationalization support, theme support (light/dark mode), and is used internally by `@hero-design/rn` Calendar and DatePicker components.

## Installation

```sh
npm install @hero-design/react-native-month-year-picker
# or
yarn add @hero-design/react-native-month-year-picker
```

**Peer Dependencies:**

```sh
yarn add react@18.3.1 react-native@0.77.3
```

**Requirements:**
- React 18.3.1
- React Native 0.77.3 (compatible with Hero Design)
- Node.js >= 20.0.0 (20.x or 22.x supported)
- Yarn >= 4.0.2 (enabled via Corepack: `corepack enable`)
- iOS Simulator (iPhone 14, iOS 18+) or Android Emulator (Pixel 6, API 30) for development

### iOS Setup

After installing, you need to run pod install:

```sh
cd ios && pod install
```

**Note:** This package uses native modules and cannot be used with Expo Go. You must use a development build or bare React Native project.

## Usage

### iOS - MonthYearPickerViewIOS

The iOS component renders a native month/year picker view:

```tsx
import { MonthYearPickerViewIOS } from '@hero-design/react-native-month-year-picker';

function MyDatePicker() {
  const [selectedDate, setSelectedDate] = useState(new Date());

  return (
    <MonthYearPickerViewIOS
      value={selectedDate}
      onChange={(date) => setSelectedDate(date)}
      minimumDate={new Date(2020, 0, 1)}
      maximumDate={new Date(2030, 11, 31)}
      locale="en"
      textColor="#000000"
      style={{ height: '100%', width: '100%' }}
    />
  );
}
```

### Android - MonthYearPickerDialogueAndroid

The Android component displays a native dialog picker:

```tsx
import { MonthYearPickerDialogueAndroid } from '@hero-design/react-native-month-year-picker';

function MyDatePicker() {
  const [selectedDate, setSelectedDate] = useState(new Date());

  return (
    <MonthYearPickerDialogueAndroid
      value={selectedDate}
      onChange={(action, date) => {
        if (action === 'dateSetAction' && date) {
          setSelectedDate(date);
        }
      }}
      minimumDate={new Date(2020, 0, 1)}
      maximumDate={new Date(2030, 11, 31)}
      doneButtonLabel="Done"
      cancelButtonLabel="Cancel"
      locale="en"
      themeVariant="light"
    />
  );
}
```

### Platform-Specific Usage

For cross-platform usage, use Platform to conditionally render:

```tsx
import { Platform } from 'react-native';
import {
  MonthYearPickerViewIOS,
  MonthYearPickerDialogueAndroid,
} from '@hero-design/react-native-month-year-picker';

function MonthYearPicker({ value, onChange, ...props }) {
  if (Platform.OS === 'ios') {
    return (
      <MonthYearPickerViewIOS
        value={value}
        onChange={onChange}
        {...props}
      />
    );
  }

  return (
    <MonthYearPickerDialogueAndroid
      value={value}
      onChange={onChange}
      {...props}
    />
  );
}
```

## API Reference

### MonthYearPickerViewIOS Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Date` | `new Date()` | Currently selected date |
| `onChange` | `(date: Date) => void` | **Required** | Callback when date changes |
| `minimumDate` | `Date?` | `undefined` | Minimum selectable date |
| `maximumDate` | `Date?` | `undefined` | Maximum selectable date |
| `locale` | `string` | `'en'` | Locale for date formatting |
| `textColor` | `string?` | `undefined` | Text color for the picker |
| `autoTheme` | `boolean` | `false` | Automatically detect system theme |
| `style` | `ViewStyle?` | `undefined` | Style for the container view |

### MonthYearPickerDialogueAndroid Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Date` | `new Date()` | Currently selected date |
| `onChange` | `(action: string, date: Date \| undefined) => void` | **Required** | Callback when dialog action occurs |
| `minimumDate` | `Date?` | `undefined` | Minimum selectable date |
| `maximumDate` | `Date?` | `undefined` | Maximum selectable date |
| `doneButtonLabel` | `string` | `'Done'` | Label for the done button |
| `cancelButtonLabel` | `string` | `'Cancel'` | Label for the cancel button |
| `locale` | `string` | `'en'` | Locale for date formatting |
| `themeVariant` | `'light' \| 'dark'` | `undefined` | Theme variant (ignored if `autoTheme` is true) |
| `autoTheme` | `boolean` | `false` | Automatically detect system theme |

### Action Types

For Android `onChange` callback, the action parameter can be:

- `'dateSetAction'` - User confirmed the date selection
- `'dismissedAction'` - User dismissed the dialog without selecting

## Theming

### iOS Theming

The iOS picker supports text color customization and automatic theme detection:

```tsx
import { useTheme } from '@hero-design/rn';

function ThemedPicker() {
  const theme = useTheme();
  
  return (
    <MonthYearPickerViewIOS
      value={selectedDate}
      onChange={setSelectedDate}
      textColor={theme.colors.onDefaultGlobalSurface}
      autoTheme={true}
    />
  );
}
```

### Android Theming

The Android picker supports light/dark theme variants:

```tsx
import { useTheme } from '@hero-design/rn';

function ThemedPicker() {
  const theme = useTheme();
  
  return (
    <MonthYearPickerDialogueAndroid
      value={selectedDate}
      onChange={handleChange}
      themeVariant={theme.themeMode === 'dark' ? 'dark' : 'light'}
      autoTheme={true}
    />
  );
}
```

**Note:** When `autoTheme` is set to `true`, the `themeVariant` prop is ignored and the system theme is automatically detected.

## Examples

### Integration with Calendar Component

This picker is used internally by the `@hero-design/rn` Calendar component:

```tsx
import Calendar from '@hero-design/rn';

function MyCalendar() {
  return (
    <Calendar
      value={selectedDate}
      onChange={setSelectedDate}
      onToggleMonthPicker={(visible) => {
        // Month picker visibility is handled internally
      }}
      monthPickerConfirmLabel="Done"
      monthPickerCancelLabel="Cancel"
    />
  );
}
```

### Integration with DatePicker Component

Used in DatePicker for month-year selection variant:

```tsx
import { DatePicker } from '@hero-design/rn';

function MyDatePicker() {
  return (
    <DatePicker
      value={selectedDate}
      onChange={setSelectedDate}
      variant="month-year"
      label="Select Month & Year"
    />
  );
}
```

### Custom Dialog Implementation

Example of wrapping the Android picker in a custom dialog:

```tsx
import { useState } from 'react';
import { Button } from '@hero-design/rn';
import { MonthYearPickerDialogueAndroid } from '@hero-design/react-native-month-year-picker';

function CustomMonthPicker() {
  const [date, setDate] = useState(new Date());
  const [visible, setVisible] = useState(false);

  return (
    <>
      <Button text="Select Month/Year" onPress={() => setVisible(true)} />
      {visible && (
        <MonthYearPickerDialogueAndroid
          value={date}
          onChange={(action, newDate) => {
            if (action === 'dateSetAction' && newDate) {
              setDate(newDate);
            }
            setVisible(false);
          }}
          doneButtonLabel="Confirm"
          cancelButtonLabel="Cancel"
        />
      )}
    </>
  );
}
```

## Contributing

Contributions to `@hero-design/react-native-month-year-picker` are welcome!

To get started:

1. Clone the repository: `git clone git@github.com:Thinkei/hero-design.git`
2. Enable Corepack: `corepack enable`
3. Install dependencies: `yarn install`
4. Bootstrap the example app: `yarn workspace @hero-design/react-native-month-year-picker bootstrap`
5. Build the package: `yarn turbo run build --filter=@hero-design/react-native-month-year-picker`

For detailed contributing guidelines, see [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

MIT

---

Made with [react-native-builder-bob](https://github.com/callstack/react-native-builder-bob)