[pickers] How can I get access to the Pickers Adapter Utils for use with usePickersTranslations?

[kealjones-wk]

The problem in depth

#13657 Added usePickersTranslations which is awesome, but it didn't provide a public version of useUtils like was requested in #12691

Access to the Adapter Utils is necessary to use at least 3 of the properties on LocaleText, see: openDatePickerDialogue, openTimePickerDialogue, and clockLabelText. There is currently no public way to get the utils for this argument that i know of. Is there some way that i don't know of?

Actual in depth issue explained in a comment below: #13768 (comment)

Your environment

No response

Search keywords: useUtils, date pickers, localization, localeText, adapter, utils
Order ID: 82849

[LukasTy]

Hello @kealjones-wk.
Thank you for rushing to use the new export and creating this issue. 🙏
Could you tell me a bit more about your use case?
Where do you need to use these mentioned localization functions?
Are you building a custom Text Field? Or a Clock? 🤔

[github-actions]

The issue has been inactive for 7 days and has been automatically closed.

[kealjones-wk]

Hello @LukasTy sorry for the delay in response I went on holiday after creating this and just got back.

Our use case is Wrapping DateRangePicker (and probably others in the future) to change its functionality to act and look more similar to the DatePicker component, meaning having the Open Picker Button/Icon Adornment instead of opening on click, adding ability to use the keyboard with the calendar, etc.

Because we added the Open Picker Button we need openDatePickerDialogue to set the aria label on that button to match DatePicker's accessibility. I can go into this more if you'd like but that is the tldr.

[flaviendelangle]

I struggle to understand what is missing for you.
You should have access to openDatePickerDialogue in usePickersTranslations.

If you could create a working reproduction case, it would help us a lot 🙏

[kealjones-wk]

Note

Edited emphasises and word choices to not be such a doo doo head.

You should have access to openDatePickerDialogue in usePickersTranslations.

@flaviendelangle Yes, I have access to the methods, but thats not the problem. The problem is that they are unusable because they require a utils/adapter argument and without useUtils being public there is no way to provide that argument to those localeText methods.

I cannot create a working reproduction... but here is an example of not being able to use the method, see line 25 of Demo.tsx: https://stackblitz.com/edit/react-qyafei-7h6nfa?file=Demo.tsx

For some further context:
openDatePickerDialogue requires a utils arg: https://github.com/mui/mui-x/blob/master/packages/x-date-pickers/src/locales/utils/pickersLocaleTextApi.ts#L73
openTimePickerDialogue requires a utils arg: https://github.com/mui/mui-x/blob/master/packages/x-date-pickers/src/locales/utils/pickersLocaleTextApi.ts#L74
clockLabelText requires an adapter arg: https://github.com/mui/mui-x/blob/master/packages/x-date-pickers/src/locales/utils/pickersLocaleTextApi.ts#L64

Now check:

mui-x/packages/x-date-pickers/src/DesktopDatePicker/DesktopDatePicker.tsx

Lines 94 to 95 in 39b38ae

	getOpenDialogAriaText:
	props.localeText?.openDatePickerDialogue ?? translations.openDatePickerDialogue,

and follow that through to the useDesktopPicker hook here and notice that it is getting passed a utils var:

mui-x/packages/x-date-pickers/src/internals/hooks/useDesktopPicker/useDesktopPicker.tsx

Line 110 in 39b38ae

'aria-label': getOpenDialogAriaText(pickerFieldProps.value, utils),

that utils var is set using useUtils which is internal and not publicly available:

mui-x/packages/x-date-pickers/src/internals/hooks/useDesktopPicker/useDesktopPicker.tsx

Line 69 in 39b38ae

const utils = useUtils<TDate>();

is there some other way to get the adapter/utils that is public? cause if not openDatePickerDialogue, openTimePickerDialogue, and clockLabelText are unusable without useUtils being a public hook.

Let me know if you need anything else. :)

[flaviendelangle]

OK, I totally missed this "detail".

@LukasTy, we should be able to host the utils at a higher level instead of passing it when calling the translation function.
Or we could simply export useUtils

[michelengelen]

If I get it right the utils are actually just the current adapter.
IMO it would not hurt to just export useUtils. 🤷🏼

[flaviendelangle]

I like the idea that the user never has to directly interact with the adapter.
He gives an adapter so that the pickers works perfectly with his date library, but he always interacts with his date using his date library not its adapter.

Right now the adapter is public API, so I respect semver, but people never have to use it so I have no bad feeling breaking things in majors.
If we export useUtils, my "fear" is that people start using adapters, start calling its methods because it can be convenient and that we loose this flexibility.

So I'm not a big fan of exporting useUtils if we have another solution.

Plus, if utils is an internal thing, then having to do:

const utils = useUtils();
const translations = usePickersTranslations();
const label = translations.openTimePickerDialogue(value, utils);

Is a worse DX than this IMHO:

const translations = usePickersTranslations();
const label = translations.openTimePickerDialogue(value);

Since we ask people to import something from our package just to pass it back.

[michelengelen]

Good points @flaviendelangle ... I'll look into moving the utils a level up so that they don't have to be passed into these methods

[LukasTy]

@flaviendelangle That is a great suggestion. 👍
I can only second the argument to avoid publically exposing adapter utils if possible unless there is a very clear need.

In this case, I fear that the proposed change is hardly doable without a BC, at least a slight one, because translations are public and if we decide to change their API then it could mean a migration to someone with custom local translations.
Although, as we can see, these translations are hardly used in a custom way, given that it is not easy to change the built-in behavior... 🙈

As for the technical part of the change, we are talking about something like this?

-openDatePickerDialogue: (value, utils) =>
+openDatePickerDialogue: (value, formattedDate) =>
-    value !== null && utils.isValid(value)
+    value !== null && formattedDate
-      ? `Choose date, selected date is ${utils.format(value, 'fullDate')}`
+      ? `Choose date, selected date is ${formattedDate}`
      : 'Choose date',

And on the usage side:

-'aria-label': getOpenDialogAriaText(pickerFieldProps.value, utils),
+'aria-label': getOpenDialogAriaText(pickerFieldProps.value, utils.isValid(pickerFieldProps.value) ? utils.format(pickerFieldProps.value, 'fullDate') : null),

[flaviendelangle]

What if we keep the utils for now but make it nullable, and stop using it in the actual translations.
That way we don't have a BC in the signature of the translations and we can remove the old param in v8.

As for the technical part, I did not dive into it honestly.
My first idea was to change the signature of the translation object to be something like (utils) => PickersLocaleText but this is probably not doable without a BC.

[kealjones-wk]

I am 100% behind @flaviendelangle idea of making the 2nd arg nullable/undefinable and mui using the utils internal instead of requiring the arg. That seems like a clean and easy change without the need for a BC but opens the 2nd arg for removal in like v6/7 if desired.

PERSONALLY, I don't think there are many consumers of this API besides me as no one tends to be complaining about this besides me, AND the fact that the ONLY way to even provide that 2nd arg that i can think of is to construct your own unique instance of an adapter that might not match the one that was provided by the consumers which would cause its own issues. so like that utils/adapter arg is impossible to use currently anyway so its not gonna hurt when its removed in the future.

[kealjones-wk]

PS. @flaviendelangle sorry for any rudeness in my comment above. I was in a bad headspace that week. I should have explained much of those details in the original issue. Thank you for putting up with me anyway and sorry about that. <3

[flaviendelangle]

No offense taken 🙏

[kealjones-wk]

Just wanted to check in on this and see if it was gonna be picked up?

[flaviendelangle]

@kealjones-wk I took over the topic
We should be able to have it delivered in the coming weeks.

[kealjones-wk]

<3 awesome! Thanks so much @flaviendelangle

[github-actions]

This issue has been closed. If you have a similar problem but not exactly the same, please open a new issue.
Now, if you have additional information related to this issue or things that could help future readers, feel free to leave a comment.

Note

We value your feedback @kealjones-wk! How was your experience with our support team?
If you could spare a moment, we'd love to hear your thoughts in this brief Support Satisfaction survey. Your insights help us improve!