Add Count-Up Timer Functionality

[gazambuja]

This pull request introduces a significant new feature to the timer-bar-card: count-up timer functionality. This allows the card to display the elapsed time since a specified event, in addition to the existing countdown timer capabilities.

Key Features and Changes:

• Count-Up Mode: The card can now operate as a count-up timer, displaying the time elapsed since an entity's last_changed attribute (or a custom start time, if configured). This is activated by using the max_value option instead of the duration option.
• max_value Option: This new option controls the count-up behavior:
  • Specific Time: A string like "1h", "30m", "90s" sets a fixed maximum value for the progress bar. The bar fills completely when the elapsed time reaches this value.
  • "auto": Enables automatic expansion of the maximum value. The bar's maximum value increases as the elapsed time approaches the current maximum, creating a continuously expanding time window.
• auto_increment Option: When max_value is set to "auto", this option controls:
  • The initial maximum value of the bar.
  • The amount by which the maximum value increases when the elapsed time gets close to the current maximum (within 10% of the increment).
  • Defaults to "1h" if not specified. Accepts values like "15m", "2h", "30s".
• Automatic Time Format Switching: The time display now automatically switches between MM:SS (for times under 60 minutes) and HH:MM:SS (for times 60 minutes and over) when resolution: automatic is set. This improves readability.
• Mutual Exclusivity of duration and max_value: The code now ensures that if max_value is set, duration is effectively ignored (treated as null), and vice versa. This provides a clear and unambiguous way to switch between countdown and count-up modes.
• Improved Type Safety: Addressed TypeScript errors related to optional parameters and type mismatches.
• Comprehensive Documentation: Updated the README.md with detailed explanations of the new features, configuration options, and examples. Added a new section highlighting the count-up functionality, similar to the existing Mushroom styling section.
• Updated Files: types.ts, timer-bar-card.ts, timer-bar-entity-row.ts, timer-bar-mushroom-row.ts,helpers.ts and format-time.ts.

Code Structure and Implementation Details:

• The core logic for count-up is handled within helpers.ts (in timerTimeRemaining and timerTimePercent) and timer-bar-entity-row.ts (managing the _currentMaxValue state for the auto mode).
• The existing countdown functionality is fully preserved and remains the default behavior if duration is used.
• The code is designed to be backward-compatible with existing configurations.

Testing:

• The new functionality has been thoroughly tested with various configurations, including:
  • Basic count-up with a fixed max_value.
  • Count-up with max_value: auto.
  • Different auto_increment values.
  • Combinations of count-up and countdown configurations.
  • Edge cases (entity unavailability, invalid last_changed, etc.).
  • No unit test where added

Acknowledgments:

This feature was developed by Gustavo with significant assistance from Google's AI Studio. The collaborative process involved iterative refinement of the code, ensuring correct logic, type safety, and comprehensive documentation.

Example Configuration (Count-Up):

type: custom:timer-bar-card
entity: binary_sensor.oven_on  # Replace with your entity
max_value: 2h  # Bar fills completely after 2 hours

[GeraldG123]

Hi,

love the time bar for so many scenarios but for my washing machine the count-up would be also great, so are there already any news on this topic?

If not how can I install the fork directly (already tried a lot, failed a lot)?

best thanks for info/support

best regards
Gerald

[rianadon]

I haven't had time to review this yet. That's a lot of changes :) And many changes to important logic bits.

In the meantime, to run this directly:

1. Either install Node.js and typescript and run npm run dev to generate dist/timer-bar-card.js, or download this attachment: timer-bar-card.txt and rename it to timer-bar-card.js. The latter is what I just compiled from the fork.
2. Uninstall timer-bar-card from HACS if you used HACS.
3. Follow the manual installation instructions.

[drewkeller]

Love this feature! Thanks for working on it.

I have a couple of minor things to note based on my testing.

• It took me a while to figure out that I have to use "min" for minutes, not "m" (which is for months). It seems that the documentation for this feature is using "m" as minutes in a number of places.
• The size of the bar might need to be adjusted as the time string gets larger. Here are some screenshots at various stages.

Here is my configuration shown in the screenshots.

type: entities
entities:
  - entity: input_boolean.testtoggle
  - type: custom:timer-bar-card
    entity:
      - input_boolean.testtoggle
    max_value: auto
    duration: null
    active_state: "on"

As an additional option for this feature, it might be nice to have an option to reset to 0 or keep the ending value when the timer stops. Currently it resets to 0 as soon as it becomes inactive.