Apply User-Defined Date Formatting Settings to WP Admin React Components

[mgascam]

Fixes #6567

This pull request refactors multiple components by replacing the direct usage of dateI18n with the newly introduced formatUserDateTime utility function. The formatUserDateTime wraps the dateI18n function and formats date and time with the user-defined settings.

Changes proposed in this Pull Request

• Introduced formatUserDateTime from wcpay/utils/date-time to handle date formatting.
• Updated all relevant functions to use formatUserDateTime, ensuring date display that respects user preferences.
• Removed dateI18n imports from various components.

Testing instructions

General Date and Time Display Testing

• Navigate to WP Admin > Settings > General and set your preferred Date and Time Formats and Timezone.
• Verify that the date format matches the user-defined settings in WordPress when you navigate to the WooPayments plugin pages.
• Verify that the dates and times are correctly converted from UTC to your preferred timezone.

Component Specific Testing

Transactions

• Navigate to WP Admin > Payments > Transactions.
• Verify the values in Date / Time and Deposit Date columns.

Capital Loans

This section is hidden if your user does not have capital loans. Follow the steps in this guide to create one offer for your user. Once the offer is created, your user will get an email to confirm it. Visit the link in the email, but make sure to use your local store URL, not the server one.

• Navigate to WP Admin > Payments > Capital loans
• Verify that the Active loan overview dates are formatted according to the user settings.
• Verify that the All Loans table dates are formatted according to the user settings. There are two columns that contain dates: Disbursed and First Paydown.

Deposits

• Navigate to WP Admin > Payments > Deposits
• Verify that the dates in the Deposit history table are formatted according to the user settings

• Click on a row and verify that the date and times in the Date /Time column of the deposit details are formatted correctly.

Disputes
You can use test cards to create disputed orders.

• Navigate to WP Admin > Payments > Disputes
• Verify the date and time in the Disputed on column (you may need to reveal it)

- Click one row to navigate to the details view and verify the dates

• Click on Challenge Dispute and verify the dates in the form are correct

Documents

In the server, you can use the cli to add a document to your account wp wcpay add_document_for_account 236870460 vat_invoice --period_from="2024-10-01 00:00:00" --period_to="2024-10-31 23:59:59"

• Navigate to WP Admin > Payments > Documents
• Verify that the dates in the Date and Description columns in the Documents list are correctly formatted

---

• Run npm run changelog to add a changelog file, choose patch to leave it empty if the change is not significant. You can add multiple changelog files in one PR by running this command a few times.
• Covered with tests (or have a good reason not to test in description ☝️)
• Tested on mobile (or does not apply)

Post merge

• Link to testing instructions from release testing doc following these instructions : Add link here / 'QA Testing Not Applicable'
• Add or update critical flows and testing instructions for critical flows, if applicable.
• Add what's changed (description, screenshot, demo videos etc.) to the release announcement post, if applicable.

[brucealdridge]

I have requested an optional review from Helix. Dates/Timezones have been on our radar recently.

[deepakpathania]

Left some comments.

[deepakpathania]

Changes mostly LGTM but have a question around data integrity for older plugins updating to a future version with these changes.

[deepakpathania]

For older plugins that don't have these - will there be any issues during updation? That is for reports or other places that folks might be downloading, will there be discrepancies in data format due to this? 🤔

[mgascam]

I focused on limiting changes to only the areas of code where dates are displayed to the user, so I don't expect any major issues. Additionally, the fact that the unit tests and snapshots passed with minimal adjustments gives me further confidence.

However, there is a chance that merchants might be confused, as the way dates and times are presented will change without any direct action from them. This includes the dates in downloaded files, which, as you mentioned, could potentially impact automated processes on their end (just thinking about a possible scenario). While the default WordPress date format (F j, Y) isn’t drastically different from the previously hard-coded format (M j, Y), which was the most commonly used before this change, there could still be some adjustments.

I'm not entirely sure how to assess the potential negative impact on merchants, to be honest. Overall, though, I see this as a welcome improvement, as it adapts date formats to user-selected settings, making them feel more intuitive. For example, the MM-DD-YYYY format can be confusing for Spanish speakers like myself, as we typically use the DD-MM-YYYY format. There’s also an option for merchants to use a custom format, allowing them to keep the previous date style if desired. However, it's worth noting that we weren’t using formats consistently across the WooPayments plugin codebase before this update.

But I may be wrong, so I'm wondering if I should gather more feedback in a p2 before going ahead with this change. What do you think?

[deepakpathania]

I feel we could make this a setting maybe in WooPayments that allows merchants to sync the date format with the WP admin settings maybe and default it to false. That way merchants can explicitly opt-in to if needed and would expect the change to be reflected from the toggle onwards. WDYT?

[mgascam]

Thank you for sharing this idea @deepakpathania; it’s definitely a possible solution, though I’m not entirely convinced. My concern is that there’s already a place to manage date and time formats in Settings > General. Adding a similar option under the WooPayments settings might create confusion. Additionally, the current behavior of ignoring user preferences is inconsistent, and introducing a setting here feels somewhat like a workaround for the core issue. That said, as you pointed out, this could help reduce potential confusion for merchants by giving them control over format changes.

I'm considering an alternative approach: we could inform merchants that they can select their preferred formats through WordPress settings. This could be done with an admin notice or a tooltip, perhaps in places like the date column in tables.

[mgascam]

This could be done with an admin notice or a tooltip, perhaps in places like the date column in tables.

Something like this:

Screen.Recording.2024-11-05.at.14.03.38.mov

[haszari]

This sounds worth consulting designers about! @mgascam I love the idea of leaning into WordPress core settings and simplifying things.

[deepakpathania]

This makes sense to me but as Rua mentioned, maybe let's consult someone from Design about this before shipping.

[mgascam]

This sounds worth consulting designers about!

Thanks for your insights, @deepakpathania and @haszari! I think consulting designers is a great idea.

@rogermattic, I noticed your recent post on table design, so I thought you might have some relevant context here. However, please feel free to redirect me if needed. To summarize, this PR aims to remove the hardcoded date & time formats currently in use in the WooPayments plugin, instead aligning them with WordPress General settings. While I believe this is the right direction, we’re aware this change could potentially inconvenience some merchants, as it will be applied automatically with the update.

To minimize disruption, we’re exploring a few options (see comments above). One approach we’re leaning towards is adding a tooltip in the relevant column headers to inform merchants of the change. The tooltip could guide users to the General settings where they can manage date & time formats. Do you think this is a suitable solution? Any additional insights or ideas would be much appreciated. 🙇

[rogermattic]

Thanks for tagging me @mgascam !

To summarize, this PR aims to remove the hardcoded date & time formats currently in use in the WooPayments plugin, instead aligning them with WordPress General settings. While I believe this is the right direction...

Thanks for the TLDR; ! I think it is a great idea!

...we’re aware this change could potentially inconvenience some merchants, as it will be applied automatically with the update.
Agreed— It's a small change but I agree it can be frustrating. We can definitely support users here, and I really like your ideas! I’m leaning slightly towards a dismissable admin notice (mentioned earlier) over a tooltip. We could also consider a mini spotlight, though I’ll need to explore how that might look. Something like this (a random example from somewhere else):

A tooltip might be less noticeable than a notice, especially if we're aiming to introduce this change smoothly and reduce potential user frustration. However, a tooltip could work well as a secondary guide, pointing out where to adjust settings and perhaps disappearing eventually after some time when the users get familiar with the flow.

To start, I’d suggest exploring either the admin notice or spotlight options. What do you think? If you’re on board, I can mock up two mini proposals for us to review.

Also, what will be the default view that the user sees after the update? Will it be something like this (from the Storybook)?:

Also, am I understanding this correctly, to adjust the settings the users will need to follow exactly the steps that you listed above as testing instructions?

1. Navigate to WP Admin > Settings > General and set your preferred Date and Time Formats and Timezone.
2. Verify that the date format matches the user-defined settings in WordPress when you navigate to the WooPayments plugin pages.
3. Verify that the dates and times are correctly converted from UTC to your preferred timezone.

[mgascam]

Thanks for your quick response @rogermattic 🙇 I loved your perspective and I feel we are aligned. Let's discuss the next steps 😄

To start, I’d suggest exploring either the admin notice or spotlight options. What do you think? If you’re on board, I can mock up two mini proposals for us to review.

Yes I agree that the admin notice and/or the spotlight options can work. Please share the mocks and, in the meantime, I'll look into how those components work from a code point of view (never used them yet)

Also, what will be the default view that the user sees after the update? Will it be something like this (from the Storybook)?

After the update, they will see the date & times formatted according to their saved preferences. The defaults are F j, Y for dates (e.g. November 6, 2024) and g:i a for time (e.g. 11:06 am) and the UTC timezone. The date in your example will be rendered like this January 01, 2021 / 12:00 am.

Also, am I understanding this correctly, to adjust the settings the users will need to follow exactly the steps that you listed above as testing instructions?

Yes, this is where date and time settings live in the WordPress Admin.

[mgascam]

What do you think? If you’re on board, I can mock up two mini proposals for us to review.

Hi @rogermattic 👋 , just checking in to see if you've had a chance to work on the mocks. I believe we could use the Notice component to inform merchants, but I'd prefer to hold off on any decisions until we've reviewed your proposals.

For your information, I'll be on support rotation next week, but I'd like to resume work on this the following week. It would be great if we could review the mocks in the meantime. Does that work for you?

Thanks in advance!