feat: add back locale prop (#544)

* Revert "feat: remove locale prop (#540)"

This reverts commit 6637c03.

* chore: update docs and minor changes

* fix screenshot?

* improve docs and screenshot

Author: vonovak

.eslintrc.js

@@ -12,6 +12,9 @@ module.exports = {
     jest: true,
     jasmine: true,
     waitFor: true,
-    detoxCircus: true
-  }
+    detoxCircus: true,
+  },
+  rules: {
+    'no-var': 2,
+  },
 };

README.md

@@ -25,7 +25,7 @@ React Native date & time picker component for iOS, Android and Windows.
 <table>
   <tr><td colspan=2><strong>iOS</strong></td></tr>
   <tr>
-    <td><p align="center"><img src="./docs/images/ios_date.png" width="260" height="420"/></p></td>
+    <td><p align="center"><img src="./docs/images/ios_date_new.png" height="420"/></p></td>
     <td><p align="center"><img src="./docs/images/ios_time.png" width="260" height="420"/></p></td>
   </tr>
   <tr><td colspan=2><strong>Android</strong></td></tr>
@@ -67,6 +67,7 @@ React Native date & time picker component for iOS, Android and Windows.
     - [`firstDayOfWeek` (`optional`, `Windows only`)](#firstDayOfWeek-optional-windows-only)
     - [`textColor` (`optional`, `iOS only`)](#textColor-optional-ios-only)
     - [`themeVariant` (`optional`, `iOS only`)](#themeVariant-optional-ios-only)
+    - [`locale` (`optional`, `iOS only`)](#locale-optional-ios-only)
     - [`is24Hour` (`optional`, `Windows and Android only`)](#is24hour-optional-windows-and-android-only)
     - [`neutralButtonLabel` (`optional`, `Android only`)](#neutralbuttonlabel-optional-android-only)
     - [`minuteInterval` (`optional`)](#minuteinterval-optional)
@@ -176,12 +177,14 @@ export const App = () => {
 };
 ```
 
-## Locale note
+## Localization note
 
 On Android, the picker will be controlled by the system locale. If you wish to change it, [see instructions here](https://stackoverflow.com/a/2900144/2070942).
 
 On iOS, the locale can be controlled from xCode, as [documented here](https://developer.apple.com/documentation/xcode/adding-support-for-languages-and-regions).
 
+There is also the iOS-only locale prop that can be used to force locale in some cases but its usage is discouraged due to [not working robustly in all picker modes](./docs/images/ios_date_new.png) (note the mixed month and day names).
+
 For Expo, follow the [localization docs](https://docs.expo.dev/distribution/app-stores/#localizing-your-ios-app).
 
 ## Props
@@ -317,6 +320,15 @@ Allows changing of the textColor of the date picker. Has effect only when `displ
 <RNDateTimePicker textColor="red" />
 ```
 
+#### `locale` (`optional`, `iOS only`)
+
+Allows changing the locale of the component. By default, the device's locale is used. Please note using this prop is discouraged due to not working reliably in all picker modes.
+Prefer localization as documented in [Localization note](#localization-note).
+
+```js
+<RNDateTimePicker locale="es-ES" />
+```
+
 #### `is24Hour` (`optional`, `Windows and Android only`)
 
 Allows changing of the time picker to a 24 hour format. By default, this value is decided automatcially based on the user's chosen locale and other preferences.

docs/images/ios_date_new.png

@@ -114,7 +114,9 @@ export const App = () => {
     backgroundColor: isDarkMode ? Colors.dark : Colors.lighter,
   };
 
-  const toggleMinMaxDate = () => {
+  const toggleMinMaxDateInUTC = () => {
+    setTzOffsetInMinutes(0);
+
     const startOfTodayUTC = sourceMoment.utc().startOf('day').toDate();
     setMinimumDate(maximumDate ? undefined : startOfTodayUTC);
     const endOfTomorrowUTC = sourceMoment
@@ -285,7 +287,7 @@ export const App = () => {
               <Button
                 testID="setMinMax"
                 onPress={() => {
-                  toggleMinMaxDate();
+                  toggleMinMaxDateInUTC();
                   setShow(true);
                 }}
                 title="toggleMinMaxDate"

docs/images/ios_date.png renamed to docs/images/ios_date_old.png

@@ -189,7 +189,6 @@ describe('Example', () => {
 
     it('should let you pick tomorrow but not yesterday when setting min/max', async () => {
       await elementById('DateTimePickerScrollView').scrollTo('bottom');
-      await elementById('setTzOffsetToZero').tap();
       await elementById('setMinMax').tap();
 
       if (isIOS()) {
@@ -207,10 +206,10 @@ describe('Example', () => {
 
         // Ensure you can't select yesterday (Android)
         const focusTwelethOfNovemberInCalendar = async () => {
-          for (var i = 0; i < 4; i++) {
+          for (let i = 0; i < 4; i++) {
             await uiDevice.pressDPadDown();
           }
-          for (var i = 0; i < 3; i++) {
+          for (let i = 0; i < 3; i++) {
             await uiDevice.pressDPadLeft();
           }
         };
@@ -222,10 +221,10 @@ describe('Example', () => {
         // Ensure you can select tomorrow (Android)
         await userOpensPicker({mode: 'date', display: getPickerDisplay()});
         const focusFourteenthOfNovemberInCalendar = async () => {
-          for (var i = 0; i < 5; i++) {
+          for (let i = 0; i < 5; i++) {
             await uiDevice.pressDPadDown();
           }
-          for (var i = 0; i < 2; i++) {
+          for (let i = 0; i < 2; i++) {
             await uiDevice.pressDPadLeft();
           }
         };

example/App.js

@@ -97,6 +97,7 @@ + (NSString*) datepickerStyleToString: (UIDatePickerStyle) style  API_AVAILABLE(
 }
 
 RCT_EXPORT_VIEW_PROPERTY(date, NSDate)
+RCT_EXPORT_VIEW_PROPERTY(locale, NSLocale)
 RCT_EXPORT_VIEW_PROPERTY(minimumDate, NSDate)
 RCT_EXPORT_VIEW_PROPERTY(maximumDate, NSDate)
 RCT_EXPORT_VIEW_PROPERTY(minuteInterval, NSInteger)

example/e2e/detoxTest.spec.js

@@ -43,6 +43,7 @@ const getDisplaySafe = (display: IOSDisplay): IOSDisplay => {
 
 export default function Picker({
   value,
+  locale,
   maximumDate,
   minimumDate,
   style,
@@ -115,6 +116,7 @@ export default function Picker({
       ref={_picker}
       style={StyleSheet.compose(heightStyle, style)}
       date={dates.value}
+      locale={locale !== null && locale !== '' ? locale : undefined}
       maximumDate={dates.maximumDate}
       minimumDate={dates.minimumDate}
       mode={mode}

ios/RNDateTimePickerManager.m

@@ -67,6 +67,11 @@ export type IOSNativeProps = Readonly<
   BaseProps & {
     date?: Date;
 
+    /**
+     * The date picker locale.
+     */
+    locale?: string;
+
     /**
      * The interval at which minutes can be selected.
      */

src/datetimepicker.ios.js

@@ -88,6 +88,11 @@ export type IOSNativeProps = $ReadOnly<{|
   ...BaseProps,
   date?: ?Date,
 
+  /**
+   * The date picker locale.
+   */
+  locale?: ?string,
+
   /**
    * The interval at which minutes can be selected.
    */