timet 1.3.1 → 1.4.0

data/lib/timet/table.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+module Timet
+  # This module is responsible for formatting the output of the `timet` application.
+  # It provides methods for formatting the table header, separators, and rows.
+  module Table
+    # Generates and displays a table summarizing time entries, including headers, time blocks, and total durations.
+    #
+    # @example
+    #   table
+    #
+    # @return [Array<(String, Hash)>] An array containing the time block string and a hash of durations by tag.
+    #
+    # @note
+    #   - The method relies on the `header`, `process_time_entries`, `separator`, and `total` methods.
+    #   - The `header` method is responsible for printing the table header.
+    #   - The `process_time_entries` method processes the time entries and returns the time block and duration by tag.
+    #   - The `separator` method returns a string representing the separator line.
+    #   - The `total` method prints the total duration.
+    #
+    # @see #header
+    # @see #process_time_entries
+    # @see #separator
+    # @see #total
+    def table
+      header
+      time_block, duration_by_tag = process_time_entries
+      puts separator
+      total
+      [time_block, duration_by_tag]
+    end
+
+    # Formats the header of the time tracking report table.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing
+    # the formatted header.
+    #
+    # @example Format and print the table header
+    #   header
+    #
+    # @note The method constructs a string representing the table header and prints it.
+    def header
+      title = "Tracked time report [#{@filter.blink.red}]:"
+      header = <<~TABLE
+        #{title}
+        #{separator}
+        \033[32m| Id    | Date       | Tag    | Start    | End      | Duration | Notes              |\033[0m
+        #{separator}
+      TABLE
+      puts header
+    end
+
+    # Formats the separator line for the time tracking report table.
+    #
+    # @return [String] The formatted separator line.
+    #
+    # @example Get the formatted table separator
+    #   separator # => '+-------+------------+--------+----------+----------+----------+------------+'
+    #
+    # @note The method returns a string representing the separator line for the table.
+    def separator
+      '+-------+------------+--------+----------+----------+----------+--------------------+'
+    end
+
+    # Processes each time entry in the `items` array and updates the time block and duration by tag.
+    #
+    # @return [Array<(Hash, Hash)>] An array containing the updated time block and duration by tag.
+    #
+    # @example
+    #   items = [
+    #     [start_time1, end_time1, tag1],
+    #     [start_time2, end_time2, tag2]
+    #   ]
+    #   process_time_entries
+    #   #=> [{ '2024-10-21' => { 8 => [duration1, tag1], 9 => [duration2, tag2] } },
+    #   { tag1 => total_duration1, tag2 => total_duration2 }]
+    #
+    # @note
+    #   - The method relies on the `items` instance variable, which should be an array of arrays.
+    #   - Each sub-array in `items` is expected to contain a start time, end time, and a tag.
+    #   - The `display_time_entry` method is used to display each time entry.
+    #   - The `process_time_block_item` method processes each time entry and updates the time block and duration by tag.
+    #
+    # @see #items
+    # @see #display_time_entry
+    # @see #process_time_block_item
+    def process_time_entries
+      duration_by_tag = Hash.new(0)
+      time_block = Hash.new { |hash, key| hash[key] = {} }
+
+      items.each_with_index do |item, idx|
+        display_time_entry(item, TimeHelper.extract_date(items, idx))
+        time_block, duration_by_tag = process_time_block_item(item, time_block, duration_by_tag)
+      end
+      [time_block, duration_by_tag]
+    end
+
+    # Processes a time block item and updates the time block hash.
+    #
+    # @param item [Array] The time entry to process, containing the start time, end time, and tag.
+    # @param time_block [Hash] A hash containing time block data, where keys are dates and values are hashes of time
+    # slots and their corresponding values.
+    # @param duration_by_tag [Hash] A hash containing the total duration by tag.
+    #
+    # @return [Array<(Hash, Hash)>] An array containing the updated time block hash and the updated duration
+    # by tag hash.
+    #
+    # @example
+    #   item = [nil, Time.new(2024, 10, 21, 8, 0, 0), Time.new(2024, 10, 21, 9, 0, 0), 'work']
+    #   time_block = {}
+    #   duration_by_tag = {}
+    #   process_time_block_item(item, time_block, duration_by_tag)
+    #   #=> [{ '2024-10-21' => { 8 => [3600, 'work'] } }, { 'work' => 3600 }]
+    #
+    # @note
+    #   - The method relies on the `TimeHelper` module for time-related calculations.
+    #   - The `add_hashes` method is used to merge the new time block data into the existing time block hash.
+    #   - The `calculate_duration` method calculates the duration between the start and end times.
+    #
+    # @see TimeHelper#count_seconds_per_hour_block
+    # @see TimeHelper#timestamp_to_date
+    # @see TimeHelper#calculate_duration
+    # @see #add_hashes
+    def process_time_block_item(item, time_block, duration_by_tag)
+      _, start_time, end_time, tag = item
+
+      block_hour = TimeHelper.count_seconds_per_hour_block(start_time, end_time, tag)
+      date_line = TimeHelper.timestamp_to_date(start_time)
+      time_block[date_line] = add_hashes(time_block[date_line], block_hour)
+      duration_by_tag[tag] += TimeHelper.calculate_duration(start_time, end_time)
+      [time_block, duration_by_tag]
+    end
+
+    # Displays a single time entry in the report.
+    #
+    # @param item [Array] The item to display.
+    # @param date [String, nil] The date to display. If nil, the date is not displayed.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing the row.
+    #
+    # @example Display a time entry
+    #   display_time_entry(item, '2021-10-01')
+    #
+    # @note The method formats and prints the row for the time entry.
+    def display_time_entry(item, date = nil)
+      return puts 'Missing time entry data.' unless item
+
+      id, start_time_value, end_time_value, tag_name, notes = item
+      duration = TimeHelper.calculate_duration(start_time_value, end_time_value)
+      start_time = TimeHelper.format_time(start_time_value)
+      end_time = TimeHelper.format_time(end_time_value)
+      start_date = date || (' ' * 10)
+      puts format_table_row(id, tag_name[0..5], start_date, start_time, end_time, duration, notes)
+    end
+
+    # Formats a table row with the given row data.
+    #
+    # @param row [Array] The row data to format, containing the following elements:
+    #   - id [Integer] The ID of the time entry.
+    #   - tag [String] The tag associated with the time entry.
+    #   - start_date [String] The start date of the time entry.
+    #   - start_time [String] The start time of the time entry.
+    #   - end_time [String] The end time of the time entry.
+    #   - duration [Integer] The duration of the time entry in seconds.
+    #   - notes [String] Any notes associated with the time entry.
+    #
+    # @return [String] The formatted table row.
+    #
+    # @example
+    #   row = [1, 'work', '2024-10-21', '08:00:00', '09:00:00', 3600, 'Completed task A']
+    #   format_table_row(*row)
+    #   #=> "|      1| 2024-10-21 | work   | 08:00:00 | 09:00:00 |   1:00:00 | Completed task A  |"
+    #
+    # @note
+    #   - The method relies on the `@db` instance variable, which should be an object with `find_item`
+    #   and `seconds_to_hms` methods.
+    #   - The `format_end_time`, `format_mark`, and `format_notes` methods are used to format specific parts of the row.
+    #
+    # @see #format_end_time
+    # @see #format_mark
+    # @see #format_notes
+    def format_table_row(*row)
+      id, tag, start_date, start_time, end_time, duration, notes = row
+      end_time = format_end_time(end_time, id, duration)
+      mark = format_mark(id)
+
+      "| #{id.to_s.rjust(6)}| #{start_date} | #{tag.ljust(6)} | #{start_time.split[1]} | " \
+        "#{end_time.rjust(8)} | #{@db.seconds_to_hms(duration).rjust(8)} | #{format_notes(notes)}  #{mark}"
+    end
+
+    # Formats the end time of the time entry.
+    #
+    # @param end_time [String] The end time of the time entry.
+    # @param id [Integer] The ID of the time entry.
+    # @param duration [Integer] The duration of the time entry in seconds.
+    #
+    # @return [String] The formatted end time.
+    #
+    # @example
+    #   format_end_time('09:00:00', 1, 3600)
+    #   #=> "09:00:00"
+    #
+    # @note
+    #   - The method relies on the `@db` instance variable, which should be an object with a `find_item` method.
+    #   - If the `pomodoro` value is positive and the end time is not set, a blinking `timet` is added.
+    #
+    # @see #format_table_row
+    def format_end_time(end_time, id, duration)
+      end_time = end_time ? end_time.split[1] : '-'
+      pomodoro = @db.find_item(id)[5] || 0
+
+      if pomodoro.positive? && end_time == '-'
+        delta = (@db.find_item(id)[5] - (duration / 60.0)).round(1)
+        timet = "\e]8;;Session ends\a#{delta} min\e]8;;\a".green
+        end_time = " #{timet}".blink
+      end
+
+      end_time
+    end
+
+    # Formats the mark for the time entry.
+    #
+    # @param id [Integer] The ID of the time entry.
+    #
+    # @return [String] The formatted mark.
+    #
+    # @example
+    #   format_mark(1)
+    #   #=> "|"
+    #
+    # @note
+    #   - The method relies on the `@db` instance variable, which should be an object with a `find_item` method.
+    #   - If the `pomodoro` value is positive, a special mark is added.
+    #
+    # @see #format_table_row
+    def format_mark(id)
+      pomodoro = @db.find_item(id)[5] || 0
+      mark = '|'
+      mark = "#{'├'.white} #{'P'.blue.blink}" if pomodoro.positive?
+      mark
+    end
+
+    # Formats the notes column of the time tracking report table.
+    #
+    # @param notes [String, nil] The notes to be formatted.
+    # @return [String] The formatted notes.
+    #
+    # @example Format notes
+    #   format_notes('This is a long note that needs to be truncated')
+    #
+    # @note The method truncates the notes to a maximum of 20 characters and pads them to a fixed width.
+    def format_notes(notes)
+      spaces = 17
+      return ' ' * spaces unless notes
+
+      max_length = spaces - 3
+      notes = "#{notes.slice(0, max_length)}..." if notes.length > max_length
+      notes.ljust(spaces)
+    end
+
+    # Displays the total duration of the tracked time entries.
+    #
+    # @return [void] This method does not return a value; it performs side effects such as printing the total duration.
+    #
+    # @example Display the total duration
+    #   total
+    #
+    # @note The method calculates and prints the total duration of the tracked time entries.
+    def total
+      total = @items.map do |item|
+        TimeHelper.calculate_duration(item[1], item[2])
+      end.sum
+      puts "|#{' ' * 43}#{'Total:'.blue}  | #{@db.seconds_to_hms(total).rjust(8).blue} |#{' ' * 20}|"
+      puts separator
+      display_pomodoro_label
+    end
+
+    # Displays a blinking "Pomodoro" label if the sum of the compacted values in the 6th column of @items is positive.
+    #
+    # @example
+    #   display_pomodoro_label
+    #
+    # @return [void] This method returns nothing.
+    #
+    # @note
+    #   - The method relies on the `@items` instance variable, which should be an array of arrays.
+    #   - The 6th column of each sub-array in `@items` is expected to contain numeric values.
+    #   - The method uses the `blue.blink` color formatting, which assumes the presence of a `String` extension or
+    #   gem that supports color formatting.
+    #
+    # @see #@items
+    # @see String#blue
+    # @see String#blink
+    def display_pomodoro_label
+      return unless @items.map { |x| x[5] }.compact.sum.positive?
+
+      puts "#{'P'.blue.blink}omodoro"
+    end
+  end
+end

data/lib/timet/tag_distribution.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Timet
+  # The TagDistribution module provides functionality to format and display the distribution of tags based on their
+  # durations. This is particularly useful for visualizing how time is distributed across different tags in a project
+  # or task management system.
+  module TagDistribution
+    MAX_BAR_LENGTH = 70
+    BLOCK_CHAR = '▅'
+    TAG_SIZE = 12
+
+    # Formats and displays the tag distribution.
+    #
+    # @param duration_by_tag [Hash<String, Integer>] A hash where keys are tags and values are durations in seconds.
+    # @return [void] This method outputs the formatted tag distribution to the console.
+    #
+    # @example
+    #   duration_by_tag = { "timet" => 3600, "nextjs" => 1800 }
+    #   Formatter.format_tag_distribution(duration_by_tag)
+    #   # Output:
+    #   #  timet:   66.67%  ====================
+    #   #  nextjs:   33.33%  ==========
+    def tag_distribution(duration_by_tag, colors)
+      total = duration_by_tag.values.sum
+      return unless total.positive?
+
+      sorted_duration_by_tag = duration_by_tag.sort_by { |_, duration| -duration }
+      process_and_print_tags(sorted_duration_by_tag, total, colors)
+    end
+
+    # Processes and prints the tag distribution information.
+    #
+    # @param sorted_duration_by_tag [Array<Array(String, Numeric)>] An array of arrays where each inner array contains a
+    # tag and its corresponding duration, sorted by duration in descending order.
+    # @param total [Numeric] The total duration of all tags combined.
+    # @return [void] This method outputs the tag distribution information to the standard output.
+    def process_and_print_tags(sorted_duration_by_tag, total, colors)
+      sorted_duration_by_tag.each do |tag, duration|
+        value, bar_length = calculate_value_and_bar_length(duration, total)
+        horizontal_bar = (BLOCK_CHAR * bar_length).to_s.color(colors[tag] + 1)
+        tag = tag[0..TAG_SIZE - 1] if tag.size >= TAG_SIZE
+        puts "#{tag.rjust(TAG_SIZE)}: #{value.to_s.rjust(5)}%  #{horizontal_bar}"
+      end
+    end
+
+    # Calculates the percentage value and bar length for a given duration and total duration.
+    #
+    # @param duration [Numeric] The duration for the current tag.
+    # @param total [Numeric] The total duration.
+    # @return [Array<(Float, Integer)>] An array containing the calculated value and bar length.
+    #
+    # @example
+    #   calculate_value_and_bar_length(50, 100, 2) #=> [50.0, 25]
+    def calculate_value_and_bar_length(duration, total)
+      value = duration.to_f / total
+      percentage_value = (duration.to_f / total * 100).round(2)
+      bar_length = (value * MAX_BAR_LENGTH).round
+      [percentage_value, bar_length]
+    end
+  end
+end

data/lib/timet/time_block_chart.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module Timet
+  # This module is responsible for formatting the output of the `timet` application.
+  # It provides methods for formatting the table header, separators, and rows.
+  module TimeBlockChart
+    CHAR_MAPPING = {
+      0..120 => '_',
+      121..450 => '▁',
+      451..900 => '▂',
+      901..1350 => '▃',
+      1351..1800 => '▄',
+      1801..2250 => '▅',
+      2251..2700 => '▆',
+      2701..3150 => '▇',
+      3151..3600 => '█'
+    }.freeze
+
+    SEPARATOR_CHAR = '░'
+
+    # Prints a time block chart based on the provided time block and colors.
+    #
+    # @param time_block [Hash] A hash where the keys are time blocks and the values are hashes of time slots and their
+    # corresponding values.
+    #   Example: { "block1" => { 10 => "value1", 11 => "value2" }, "block2" => { 12 => "value3" } }
+    # @param colors [Hash] A hash where the keys are time slots and the values are the colors to be used
+    # for those slots.
+    #   Example: { 10 => "red", 11 => "blue", 12 => "green" }
+    #
+    # @return [void] This method does not return a value; it prints the chart directly to the output.
+    #
+    # @example
+    #   time_block = { "block1" => { 10 => "value1", 11 => "value2" }, "block2" => { 12 => "value3" } }
+    #   colors = { 10 => "red", 11 => "blue", 12 => "green" }
+    #   print_time_block_chart(time_block, colors)
+    #
+    # @note This method relies on two helper methods: `print_header` and `print_blocks`.
+    #   Ensure these methods are defined and available in the scope where `print_time_block_chart` is called.
+    #
+    # @see #print_header
+    # @see #print_blocks
+    def print_time_block_chart(time_block, colors)
+      start_hour = time_block.values.map(&:keys).flatten.uniq.min.to_i
+      print_header(start_hour)
+      print_blocks(time_block, colors, start_hour)
+    end
+
+    # Prints the header of the time block chart.
+    #
+    # The header includes a visual representation of the time slots from the given start time to 23.
+    # Each time slot is formatted as a two-digit number and aligned to the right within a fixed width.
+    #
+    # @param start_hour [Integer] The starting time for the chart. This should be an integer between 0 and 23.
+    #
+    # @return [void] This method does not return a value; it prints the header directly to the output.
+    #
+    # @example
+    #   print_header(10)
+    #   # Output:
+    #   #
+    #   #      ⏳ ↦ [ 10  11  12  13  14  15  16  17  18  19  20  21  22  23]
+    #
+    # @note The method assumes that the start_hour is within the valid range of 0 to 23.
+    #   If the start_hour is outside this range, the output may not be as expected.
+    def print_header(start_hour)
+      puts
+      print ' ' * 19
+      (start_hour..23).each { |hour| print format('%02d', hour).rjust(4) }
+      puts
+      puts '┌╴W ╴╴╴╴╴╴⏰╴╴╴╴╴╴┼'.gray + "#{'╴' * (24 - start_hour) * 4}╴╴╴┼".gray
+    end
+
+    # Prints the time blocks for each date in the given time block data structure.
+    #
+    # @param time_block [Hash] A hash where keys are date strings and values are time block data.
+    # @param colors [Hash] A hash containing color codes for formatting.
+    # @param start_hour [Integer] The starting hour for the time blocks.
+    # @return [void]
+    def print_blocks(time_block, colors, start_hour)
+      return unless time_block
+
+      weeks = []
+      time_block.each_key do |date_string|
+        date = Date.parse(date_string)
+        day = date.strftime('%a')[0..1]
+
+        format_and_print_date_info(date_string, day, weeks, start_hour)
+
+        time_block_initial = time_block[date_string]
+        print_time_blocks(start_hour, time_block_initial, colors)
+
+        calculate_and_print_hours(time_block_initial)
+      end
+      print_footer(start_hour)
+    end
+
+    # Calculates the total hours from the given time block data and prints it.
+    #
+    # @param time_block_initial [Hash] A hash containing time block data for a specific date.
+    # @return [void]
+    def calculate_and_print_hours(time_block_initial)
+      total_seconds = time_block_initial.values.map { |item| item[0] }.sum
+      hours_per_day = (total_seconds / 3600.0).round(1)
+      print "-┆#{hours_per_day}h".gray
+      puts
+    end
+
+    # Formats and prints the date information including the week and day.
+    #
+    # @param date_string [String] The date string in a parsable format.
+    # @param day [String] The abbreviated day of the week (e.g., "Mo" for Monday).
+    # @param weeks [Array<Integer>] An array storing the week numbers.
+    # @param start_hour [Integer] The starting hour for the time blocks.
+    # @return [void]
+    def format_and_print_date_info(date_string, day, weeks, start_hour)
+      weekend = date_string
+      day = day.red if %w[Sa Su].include?(day)
+      weekend = weekend.red if %w[Sa Su].include?(day)
+
+      week = format_and_print_week(date_string, weeks, start_hour)
+
+      print '┆'.gray + "#{week} #{weekend} #{day} " + '┆- '.gray
+    end
+
+    # Formats and prints the week information including the separator if necessary.
+    #
+    # @param date_string [String] The date string in a parsable format.
+    # @param weeks [Array<Integer>] An array storing the week numbers.
+    # @param start_hour [Integer] The starting hour for the time blocks.
+    # @return [String] The formatted week string.
+    def format_and_print_week(date_string, weeks, start_hour)
+      week, current_index = determine_week(date_string, weeks)
+      print_separator(start_hour, week, current_index)
+      week
+    end
+
+    # Determines the week string based on the date and the previous week.
+    #
+    # @param date_string [String] The date string in a parsable format.
+    # @param weeks [Array<Integer>] An array storing the week numbers.
+    # @return [Array<String, Integer>] An array containing the formatted week string and the current index.
+    def determine_week(date_string, weeks)
+      weeks << Date.parse(date_string).cweek
+      current_index = weeks.size - 1
+      current_week = weeks[current_index]
+      week = current_week == weeks[current_index - 1] && current_index.positive? ? '  ' : current_week.to_s.underline
+      [week, current_index]
+    end
+
+    # Prints the separator line if the week string is not empty and the current index is positive.
+    #
+    # @param start_hour [Integer] The starting hour for the time blocks.
+    # @param week [String] The formatted week string.
+    # @param current_index [Integer] The current index in the weeks array.
+    # @return [void]
+    def print_separator(start_hour, week, current_index)
+      return unless week != '  ' && current_index.positive?
+
+      sep = SEPARATOR_CHAR
+      puts "┆#{sep * 17}┼#{sep * (24 - start_hour) * 4}#{sep * 3}┼#{sep * 4}".gray
+    end
+
+    # Prints the footer of the report.
+    #
+    # @param start_hour [Integer] The start time used to calculate the footer length.
+    # @return [void] This method does not return a value; it prints directly to the standard output.
+    def print_footer(start_hour)
+      timet = "\e]8;;https://github.com/frankvielma/timet/\aTimet\e]8;;\a".green
+      puts '└╴╴╴╴╴╴╴'.gray + timet + "╴╴╴╴╴┴#{'╴' * (24 - start_hour) * 4}╴╴╴┴".gray
+      puts
+    end
+
+    # Prints time blocks for each hour from the start time to 23.
+    #
+    # @param start_time [Integer] The starting hour for printing time blocks.
+    # @param time_block_initial [Hash] A hash containing time block data, where keys are formatted hours and values
+    # are arrays containing block data.
+    # @param colors [Hash] A hash mapping tags to color codes.
+    # @return [void]
+    #
+    # @example
+    #   time_block_initial = {
+    #     '01' => ['block_char_data', 'tag']
+    #   }
+    #   colors = { 'tag' => 1 }
+    #   print_time_blocks(1, time_block_initial, colors) # Prints time blocks for hours 1 to 23
+    def print_time_blocks(start_time, time_block_initial, colors)
+      (start_time..23).each do |hour|
+        tag, block_char = get_formatted_block_char(hour, time_block_initial)
+        print_colored_block(block_char, tag, colors)
+      end
+    end
+
+    # Returns the formatted block character and its associated tag for a given hour.
+    #
+    # @param hour [Integer] The hour for which to retrieve the block character.
+    # @param time_block_initial [Hash] A hash containing time block data, where keys are formatted hours and values
+    # are arrays containing block data.
+    # @return [Array<(String, String)>] An array containing the tag and the block character.
+    #
+    # @example
+    #   time_block_initial = {
+    #     '01' => ['block_char_data', 'tag']
+    #   }
+    #   get_formatted_block_char(1, time_block_initial) #=> ['tag', 'block_char']
+    def get_formatted_block_char(hour, time_block_initial)
+      formatted_hour = format('%02d', hour)
+      hour_data = time_block_initial[formatted_hour]
+      tag = hour_data&.last
+      [tag, get_block_char(hour_data&.first)]
+    end
+
+    # Prints a colored block character based on the provided tag and block character.
+    #
+    # @param block_char [String] The block character to be printed.
+    # @param tag [String] The tag associated with the block character, used to determine the color.
+    # @param colors [Hash] A hash mapping tags to color codes.
+    #
+    # @example
+    #   colors = { 'tag' => 1 }
+    #   print_colored_block('X', 'tag', colors) # Prints a colored block character 'XX'
+    def print_colored_block(block_char, tag, colors)
+      color_code = colors[tag]
+      block = block_char * 2
+      colored_block = color_code ? "#{block.color(color_code + 1)}  " : block
+      print colored_block.rjust(4)
+    end
+
+    # Determines the block character based on the value.
+    #
+    # @param value [Integer] The value to determine the block character for.
+    # @return [String] The block character corresponding to the value.
+    def get_block_char(value)
+      return ' ' unless value
+
+      CHAR_MAPPING.find { |range, _| range.include?(value) }&.last || ' '
+    end
+  end
+end