Allow customization of time format

[breakthestatic]

Proposed change

This change adds the ability to use alternative (i.e. shorter) forms for time values where state-display is used. My primary goal was to make my badges that showed relative time a bit more concise. However, I think it could be generally useful anywhere that these formatted time strings are used (hence the expansion to the tile card).

I'm not really sold on the name of the property though; time_verbosity seems a bit clunky. Perhaps time_format or relative_time_format are more appropriate. I originally avoided those names because I did see a few other time-format-related props and didn't want to add confusion. If you have a better name for this property, I'd be more than happy to change it!

Also, I wanted to bring up the fact that the positional arguments to relativeTime are becoming more unwieldy with this addition. I thought about migrating to named props, but relativeTime is used somewhat extensively throughout the codebase and I didn't want to introduce such a large change without getting feedback from the team first.

Other thoughts:

• I think this is likely a more advanced use-case and should be YAML-only.
• I don't think it needs to be configurable per state-item. The provided format should be used for all state_content pieces.
• Documentation PR has not been created yet, as I wasn't sure if this PR would be accepted and if the form would change based on review comments.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New feature (thank you!)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Example configuration

Badge config (also works on tile cards):

type: entity
entity: sensor.sun_next_dusk
time_verbosity: narrow

Additional information

• This PR fixes or closes issue: fixes #
• This PR is related to issue or discussion:
• Link to documentation pull request:

Checklist

• The code change is tested and works locally.
• There is no commented out code in this PR.
• Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for www.home-assistant.io

[marcinbauer85]

This can be just in YAML and described in the documentation.

[karwosts]

I'm not really sold on the name of the property though

What if you didn't make a new property at all, and just added options the existing format property? Could add relative_narrow or relative_short as additional options here.

[piitaya]

I agree with @karwosts. We can simply use the time_format property and we can implement it in entity badge and tile card. Do you want to do the changes @breakthestatic or should I take the feature?

[breakthestatic]

I can take care of it. I have most of the changes ready in a separate branch. Didn't want to push them here early, in the event that wasn't the route you wanted to take.

[bramkragten]

I don't think we can do this, as relative time is also used for things like last_triggered, etc.

[breakthestatic]

Yeah, it was something I threw in somewhat last minute when I saw the alternative state_content timestamps weren't respecting the format. Would adding more specific guards for the other state content types be an acceptable alternative?

[breakthestatic]

I can't recall the specifics surrounding this, but I believe it had something to do with secondary info. Regardless, without that extra information I can't properly defend the change 😆, so I've removed this in the latest commit.

[bramkragten]

This would not be used ever, as we already would have returned the content === state part?

[breakthestatic]

I have to check this, but I'm pretty sure I saw this being reached at some point during my testing. I'll investigate a bit more and provide any pertinent data.

[breakthestatic]

This is definitely being hit frequently in my intended use-case (binary motion sensors displaying the last changed time).

The original content === state part is only hit when we explicitly want to render the base/default state item (and it additionally has the "correct" device class or domain). When content === "last_changed" for example, the requested format needs to be respected still.

Note the new formats are opt-in; when format - a new prop - isn't passed, it defaults to relative (aka long in the Intl library) which is existing behavior for both ha-relative-time and hui-timestamp-display.