icalendar-rrule 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b891ac836e382f65aa522d6fc6b049483b3296deef1fe9d2bb196ed6bb2de9bc
-  data.tar.gz: 5f99a1568a014411c01559505dd71068e630fca5cdbeb3e32fbb246fecd24190
+  metadata.gz: 657bfb18be866339dcd5fa55c355864c8d5870ca96d71f83496d0e8065495c43
+  data.tar.gz: 37dd92456663dfb2b257db55146ca6868f492549a632a7d39f547896d3f44136
 SHA512:
-  metadata.gz: ab80482e0f12d0cc47b11e28bbcf7f887bf42e50ed9e6d74dea0f24202b42215c62585347e94e72e8cb5dd38e04bf0e507745520092c7a11af36bc48182ffea1
-  data.tar.gz: 6a62fab4d640445562924807ebd7ed8eeadba97d1a5630f2c8bcf399977e6d1ece789efe17dbf21c50e05ee04b289bf81220e81075a3a698ef79531dcba5dbe2
+  metadata.gz: 8e6eeaec9f4174fcf7211688d07955d7a75f972ec0d9fcc5613fb194174df5a7cae03384d220b98505ff12d5ab17d7ad7243a1d778b4fb9be4c7add149da40b6
+  data.tar.gz: b2dcc6a4c3c6e8d2dfca0a0b96c81b477a06a3ff2e4d5cac3ca6d44d18fb7a055dba42bd3a9638e74487684ca0cd0dbb0b6c4bb75a010314ee2466d141a54166

data/.github/workflows/ruby.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+  schedule:
+    # Runs at 04:17 on the 13th of every month to avoid the "1st of the month" peak
+    - cron: '17 4 13 * *'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Testing against 3.1, 3.4 and the latest stable release (currently 4.0)
+        ruby-version: ['3.2', '3.4', 'ruby']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true # Runs 'bundle install' and caches gems automatically
+
+      - name: Run specs
+        run: bundle exec rspec

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.0] - 2026-02-06
+
+### Changed
+- **BREAKING**: Minimum Ruby version increased to 3.2 (required by ActiveSupport 8.1)
+- Updated timezone handling for better DST stability
+- Added GitHub Actions CI pipeline
+
+
 ## [0.2.0] - 2025-12-24
 
 ### Added

data/README.md

@@ -84,6 +84,72 @@ Fri. Apr. 27.  8:30-17:00
 For a more elaborate example, please have a look at 
 <https://github.com/free-creations/sk_calendar>
 
+## Configuration
+
+### Logging
+
+By default, the gem logs nothing. You can enable logging for debugging timezone issues:
+
+```ruby
+# Enable logging to STDOUT
+Icalendar::Rrule.logger = Logger.new($stdout)
+
+# Or use Rails logger
+Icalendar::Rrule.logger = Rails.logger
+```
+
+## Time handling (start/end) and timezones
+
+This gem represents both VEVENTs and VTODOs uniformly as *occurrences* with a
+normalised `start_time` and `end_time` (both `ActiveSupport::TimeWithZone`).
+
+### Normalising start_time / end_time
+
+Input components can specify time using `DTSTART`, `DTEND`, `DUE` and/or `DURATION`.
+In practice these fields are often incomplete or inconsistent, therefore this gem
+derives a sensible time range using the following rules:
+
+- `start_time`
+  1. If `DTSTART` is present: `start_time = DTSTART`
+  2. Else if `DUE` and `DURATION` are present: `start_time = DUE - DURATION`
+  3. Else if only `DUE` is present: `start_time = DUE` (deadline-only / zero-duration)
+  4. Else: a null fallback is used (Unix epoch)
+
+- `end_time`
+  1. If `DUE` is present: `end_time = DUE`
+  2. Else if `DTEND` is present: `end_time = DTEND`
+  3. Else if `DTSTART` is present: `end_time = start_time + duration`
+  4. Else: `end_time = epoch + duration`
+
+For _all-day VEVENTs_ (`DTSTART` as DATE) without `DTEND`, `DUE` and `DURATION`, the
+duration is assumed to be one day (RFC 5545).
+
+### Recurrence semantics (RRULE)
+
+Recurrences are expanded in floating (wall-clock) time. The `RRULE` is unrolled
+without applying offsets during expansion; timezone conversion is applied only
+after occurrences have been generated.
+
+Rationale:
+
+- By keeping recurrence logic in wall-clock time and deferring timezone application,
+  this gem avoids DST-related drift, ambiguous instants and retroactive rule changes,
+  while remaining predictable and deterministic.
+
+### Timezone resolution
+
+When mapping values to `ActiveSupport::TimeWithZone`, timezones are resolved with
+the following precedence:
+
+1. An explicit timezone on the value itself (`TZID` / `TimeWithZone`)
+2. A timezone defined by the parent calendar (`VTIMEZONE` / calendar settings)
+3. The system timezone
+4. UTC as a final fallback
+
+Floating date-times(i.e. `DATE-TIME` values without `TZID` and without `Z`) are interpreted as 
+local time and materialised in the _system time zone_.
+
+
 ## Used Libraries
 
 - [iCalendar Gem](https://github.com/icalendar/icalendar).

data/icalendar-rrule.gemspec

@@ -28,11 +28,11 @@ Gem::Specification.new do |gem_spec|
   gem_spec.executables   = gem_spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   gem_spec.require_paths = ['lib']
 
-  gem_spec.required_ruby_version = '>= 2.5'
+  gem_spec.required_ruby_version = '>= 3.2'
 
-  gem_spec.add_dependency 'activesupport', '>= 5.1'
+  gem_spec.add_dependency 'activesupport', '>= 8.0'
   gem_spec.add_dependency 'icalendar', '>= 2.4'
-  gem_spec.add_dependency 'ice_cube', '>= 0.16'
+  gem_spec.add_dependency 'ice_cube', '>= 0.17'
 
   gem_spec.add_development_dependency 'bundler', '>= 2'
   gem_spec.add_development_dependency 'rake', '>= 12.3.3'

data/lib/icalendar/rrule/time_refinements.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'active_support/time_with_zone'
+require 'active_support/values/time_zone'
+
+module Icalendar
+  module Rrule
+    ##
+    # Refinements for Ruby's Time class to support iCalendar time concepts.
+    #
+    # This module provides extensions for handling:
+    # - Floating time (wall-clock time without timezone)
+    # - Timezone conversions (planned)
+    #
+    # @example
+    #   using Icalendar::Rrule::TimeRefinements
+    #
+    #   time = Time.new(2026, 1, 7, 14, 30, 0, 0)
+    #   time.floating?  # => true
+    #
+    module TimeRefinements
+      refine Time do
+        ##
+        # Checks if this Time object represents "floating time".
+        #
+        # Floating time is wall-clock time without timezone information,
+        # represented as a Time with zone == nil.
+        #
+        # In iCalendar terms, floating time is a DATETIME without TZID
+        # and without the "Z" suffix (e.g., "20260107T143000").
+        #
+        # This is semantically different from UTC:
+        # - UTC is a real timezone (the world reference)
+        # - Floating time means "interpret locally" (like a photo of a clock)
+        #
+        # @return [Boolean] true if this is floating time (zone is nil)
+        #
+        # @example Floating time
+        #   Time.new(2026, 1, 1, 12, 0, 0, 0).floating?  # => true
+        #
+        # @example UTC is NOT floating
+        #   Time.utc(2026, 1, 1, 12, 0, 0).floating?     # => false
+        #
+        # @example Zoned time is NOT floating
+        #   Time.new(2026, 1, 1, 12, 0, 0, "+01:00").floating?  # => false
+        #
+        def floating?
+          zone.nil? && utc_offset.zero?
+        rescue StandardError
+          false
+        end
+
+        ##
+        # Converts to floating time. No questions asked.
+        # @return [Time] floating time
+        def to_floating
+          return self if floating?
+          Time.new(year, month, day, hour, min, sec, 0)
+        end
+
+        ##
+        # Ensures this is floating-time, warns if conversion needed.
+        # @return [Time] floating time
+        def ensure_floating
+          return self if floating?
+
+          Icalendar::Rrule.logger.warn do
+            "[icalendar-rrule] Time should be floating but has offset: '#{inspect}' - converting"
+          end
+
+          to_floating
+        end
+
+
+        ##
+        # Embeds floating time into a specific timezone.
+        #
+        # Interprets the wall-clock components (year, month, day, hour, min, sec)
+        # as local time in the given timezone, creating a TimeWithZone.
+        #
+        # This is the inverse operation to `to_floating`.
+        #
+        # @param [ActiveSupport::TimeZone, String] timezone the target timezone
+        # @return [ActiveSupport::TimeWithZone] the time embedded in the given timezone
+        # @raise [ArgumentError] if called on non-floating time (to prevent accidental misuse)
+        #
+        # @example Embed floating time in Berlin timezone
+        #   floating = Time.new(2026, 3, 30, 10, 0, 0, 0)  # 10:00 floating
+        #   berlin_time = floating.into_timezone('Europe/Berlin')
+        #   # => 2026-03-30 10:00:00 +0200 (CEST, because DST active)
+        #
+        # @example Embed the same floating time in New York
+        #   ny_time = floating.into_timezone('America/New_York')
+        #   # => 2026-03-30 10:00:00 -0400 (EDT, because DST active)
+        #
+        def into_timezone(timezone)
+          unless floating?
+            raise ArgumentError, "Time::into_timezone can only be called on floating time, got: #{inspect}"
+          end
+
+          # Ensure we have an ActiveSupport::TimeZone object
+          tz = if timezone.is_a?(ActiveSupport::TimeZone)
+                 timezone
+               else
+                 ActiveSupport::TimeZone[timezone]
+               end
+
+          unless tz
+            Icalendar::Rrule.logger.warn do
+              "[icalendar-rrule] Invalid timezone '#{timezone.inspect}' in Time::into_timezone - falling back to UTC"
+            end
+            tz = ActiveSupport::TimeZone['UTC']
+          end
+
+          # Interpret wall-clock components as local time in target timezone
+          tz.local(year, month, day, hour, min, sec)
+        end
+
+      end
+    end
+  end
+end

data/lib/icalendar/rrule/version.rb

@@ -2,6 +2,6 @@
 
 module Icalendar
   module Rrule
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/icalendar/rrule.rb

@@ -6,3 +6,27 @@ require 'icalendar/scannable-calendar'
 
 require 'icalendar/rrule/version'
 require 'icalendar/rrule/occurrence'
+require 'icalendar/rrule/time_refinements'
+require 'logger'
+
+module Icalendar
+  module Rrule
+    class << self
+      # Configurable logger for the icalendar-rrule gem.
+      # By default, logs nothing (Logger to /dev/null).
+      #
+      # @example Enable logging to STDOUT
+      #   Icalendar::Rrule.logger = Logger.new($stdout)
+      #
+      # @example Use Rails logger
+      #   Icalendar::Rrule.logger = Rails.logger
+      #
+      # @return [Logger]
+      attr_writer :logger
+
+      def logger
+        @logger ||= Logger.new(File::NULL)  # default: silent
+      end
+    end
+  end
+end

data/lib/icalendar/scannable-calendar.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'icalendar/rrule/time_refinements'
+
 module Icalendar
   ##
   # Refines the  Icalendar::Calendar class by adding
@@ -14,6 +16,7 @@ module Icalendar
     # Icalendar::Calendar class
     refine Icalendar::Calendar do # rubocop:disable Metrics/BlockLength
       using Icalendar::Schedulable
+      using Icalendar::Rrule::TimeRefinements
       ##
       # @param[date_time] begin_time
       # @param[date_time] closing_time
@@ -49,26 +52,35 @@ module Icalendar
       end
 
       private def _occurrences_between(components, begin_time, closing_time)
+        # ice_cube does not support timezones well, so we have to work internally with _floating times_.
         result = []
-        components.each do |comp|
-          occurrences = comp.schedule.occurrences_between(begin_time, closing_time)
+        components.each do |base_component|
+          start_timezone = base_component._timezone_for_start
+          end_timezone = base_component._timezone_for_end
+          # we assume that that `start_timezone` and`end_timezone` are also appropriate for start and closing time of the scan.
+          # todo: simlify by using base_component._to_floating_time_auto
+          zoned_begin_time = base_component._date_to_time_with_zone(begin_time, start_timezone)
+          zoned_closing_time = base_component._date_to_time_with_zone(closing_time, end_timezone)
+
+          floating_begin_time = zoned_begin_time.to_time.to_floating
+          floating_closing_time = zoned_closing_time.to_time.to_floating
+
+          ice_cube_occurrences = base_component.schedule.occurrences_between(floating_begin_time, floating_closing_time)
 
-          # Get the target timezone from the component
-          target_tz = comp.start_time.time_zone
+          ice_cube_occurrences.each do |ice_oc|
+            # retrieve start and end for this ice_cube occurrence and convert into the
+            # target timezones
+            ice_comp_start_time = ice_oc.start_time
+            # we assert that ice_comp_start_time is floating here.
+            fail "expected floating-time for ice_start_time" unless  ice_comp_start_time.floating?
+            start_tz = ice_comp_start_time.into_timezone(start_timezone)
 
-          occurrences.each do |oc|
-            # Interpret the time components AS IF they're already in target timezone
-            # (don't convert, just reconstruct in the right zone)
-            start_tz = target_tz.local(
-              oc.start_time.year, oc.start_time.month, oc.start_time.day,
-              oc.start_time.hour, oc.start_time.min, oc.start_time.sec
-            )
-            end_tz = target_tz.local(
-              oc.end_time.year, oc.end_time.month, oc.end_time.day,
-              oc.end_time.hour, oc.end_time.min, oc.end_time.sec
-            )
+            ice_end_time = ice_oc.end_time
+            # we assert that ice_end_time is floating here.
+            fail "expected floating-time for ice_end_time" unless ice_end_time.floating?
+            end_tz = ice_end_time.into_timezone(end_timezone)
 
-            new_oc = Icalendar::Rrule::Occurrence.new(self, comp, start_tz, end_tz)
+            new_oc = Icalendar::Rrule::Occurrence.new(self, base_component, start_tz, end_tz)
             result << new_oc
           end
         end

data/lib/icalendar/schedulable-component.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
 require 'ice_cube'
+require 'active_support/time'
 require 'active_support/time_with_zone'
+require 'active_support/values/time_zone'
+require 'date'
+require 'time'
 
 module Icalendar
   ##
@@ -44,11 +48,11 @@ module Icalendar
     NULL_TIME = 0
 
     # the number of seconds in a minute
-    SEC_MIN  = 60
+    SEC_MIN = 60
     # the number of seconds in an hour
     SEC_HOUR = 60 * SEC_MIN
     # the number of seconds in a day
-    SEC_DAY  = 24 * SEC_HOUR
+    SEC_DAY = 24 * SEC_HOUR
     # the number of seconds in a week
     SEC_WEEK = 7 * SEC_DAY
     ##
@@ -214,6 +218,7 @@ module Icalendar
       # @return [Boolean] true if the component is an Event scheduled for an entire day,
       #                   false for tasks or timed events
       def all_day?
+        # todo: determine timezone purely from input parameters (i.e from _dtstart, _dtend, _due)
         return false unless self.is_a?(Icalendar::Event)
 
         _dtstart.is_a?(Icalendar::Values::Date) ||
@@ -234,13 +239,14 @@ module Icalendar
       #
       # @return [Boolean] true if the component has no duration
       def single_timestamp?
-        return false if start_time.nil? || end_time.nil?
+        # todo: determine timezone purely from input parameters (i.e from _dtstart, _dtend, _due)
+        return false if start_time.nil? || end_time.nil? # <--- ???? are never nil ????
         # Compare at second precision (ignore potential microsecond differences)
         start_time.to_i == end_time.to_i
       end
 
       ##
-      # Make sure, that we can always query for a _rrule_ array.
+      # Make sure that we can always query for a _rrule_ array.
       # @return [array] an array of _ical repeat-rules_ (or an empty array
       #                if no repeat-rules are defined for this component).
       # @api private
@@ -251,9 +257,10 @@ module Icalendar
       end
 
       ##
-      # Make sure, that we can always query for an _exdate_ array.
-      # @return [array<ActiveSupport::TimeWithZone>] an array of _ical exdates_ (or an empty array
-      #                if no repeat-rules are defined for this component).
+      # Make sure that we can always query for an `_exdate` array.
+      # @return [Array] an array of _ical exdates_ in their original format
+      #   (may be Icalendar::Values::DateTime, Icalendar::Values::Date, or other date/time types).
+      #   Returns an empty array if no exdates are defined or an error occurs.
       # @api private
       def _exdates
         Array(exdate).flatten
@@ -311,7 +318,7 @@ module Icalendar
       ##
       # Like the for _exdates, also for these dates do not schedule recurrence items.
       #
-      # @return [array<ActiveSupport::TimeWithZone>] an array of dates.
+      # @return [Array<Object>] an array of dates.
       # @api private
       def _overwritten_dates
         result = []
@@ -325,7 +332,7 @@ module Icalendar
       end
 
       ##
-      # Make sure, that we can always query for an rdate(Recurrence Date) array.
+      # Make sure that we can always query for a rdate(Recurrence Date) array.
       # @return [array] an array of _ical rdates_ (or an empty array
       #                if no repeat-rules are defined for this component).
       # @api private
@@ -339,33 +346,110 @@ module Icalendar
       # Creates a schedule for this event
       # @return [IceCube::Schedule]
       def schedule # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-        # Calculate duration in seconds
-        duration_seconds = (end_time.to_i - start_time.to_i)  # Integer seconds
+        # Calculate the duration of this base event in seconds
+        duration_seconds = (end_time.to_i - start_time.to_i) # Integer seconds
 
         # Create a schedule with start_time and duration
-        # Convert to Ruby Time for IceCube compatibility
-        schedule = IceCube::Schedule.new(start_time.to_time, duration: duration_seconds)
+        # Convert to floating Time for IceCube compatibility
+        schedule = IceCube::Schedule.new(_to_floating_time(start_time, _timezone_for_start), duration: duration_seconds)
 
         _rrules.each do |rrule|
-          ice_cube_recurrence_rule = IceCube::Rule.from_ical(rrule)
+          # Convert RRULE's UNTIL time (if present) to floating time in event's timezone
+          normalized_rrule = _normalize_rrule_until(rrule, _timezone_for_start)
+          ice_cube_recurrence_rule = IceCube::Rule.from_ical(normalized_rrule)
           schedule.add_recurrence_rule(ice_cube_recurrence_rule)
         end
 
-        _exdates.each do |time|
-          schedule.add_exception_time(_to_time_with_zone(time))
+        _exdates.each do |ex_time|
+          schedule.add_exception_time(_to_floating_time(ex_time, _timezone_for_start))
         end
 
-        _overwritten_dates.each do |time|
-          schedule.add_exception_time(_to_time_with_zone(time))
+        _overwritten_dates.each do |overwritten_time|
+          schedule.add_exception_time(_to_floating_time(overwritten_time, _timezone_for_start))
         end
 
         rdates = _rdates
-        rdates.each do |time|
-          schedule.add_recurrence_time(_to_time_with_zone(time))
+        rdates.each do |recurrence_time|
+          schedule.add_recurrence_time(_to_floating_time(recurrence_time, _timezone_for_start))
         end
         schedule
       end
 
+      ##
+      # Normalizes an RRULE string by converting UNTIL times to a format IceCube can handle.
+      #
+      # ## The IceCube System-Timezone Problem
+      #
+      # IceCube has a critical flaw: it interprets floating times (without Z suffix) in the
+      # **system timezone** at runtime, making PRODUCTION BEHAVIOR dependent on the server's
+      # timezone configuration. This isn't just a test problem - the same calendar file would
+      # produce different occurrences on different servers!
+      #
+      # Example with `UNTIL=20180609T190000` (floating, should be 19:00 in event's timezone):
+      # - Server in Detroit (UTC-4): IceCube interprets as 19:00 Detroit → 23:00 UTC ❌
+      # - Server in Brisbane (UTC+10): IceCube interprets as 19:00 Brisbane → 09:00 UTC ❌
+      # - Server in Berlin (UTC+2): IceCube interprets as 19:00 Berlin → 17:00 UTC ✅ (by luck!)
+      #
+      # This means the SAME iCalendar file would stop repeating at different times depending
+      # on WHERE the application is deployed. This is completely unacceptable for a calendar
+      # library that's supposed to provide consistent, predictable behavior.
+      #
+      # ## The Hack: Always append Z suffix
+      #
+      # IceCube treats times with Z suffix as absolute values and skips timezone conversion:
+      # - `UNTIL=20180609T190000Z` → IceCube uses 19:00 directly, no system-TZ applied ✅
+      #
+      # This is **technically incorrect** (Z means UTC in RFC 5545, not floating time), but it's
+      # the only way to get consistent, server-timezone-independent behavior. We convert times
+      # to the event's timezone first, then append Z to "lock in" that wall-clock time and
+      # prevent IceCube from applying system-TZ conversion.
+      #
+      # Without this hack, deployments would behave differently based on server timezone,
+      # breaking calendar consistency across environments.
+      #
+      # @param [String] rrule_string the RRULE string (e.g., "FREQ=WEEKLY;UNTIL=20180615T120000Z")
+      # @param [ActiveSupport::TimeZone] target_timezone the event's timezone
+      # @return [String] the normalized RRULE string with UNTIL time + Z suffix
+      # @api private
+      #
+      # @example RFC 5545 floating time gets Z appended (the hack!)
+      #   rrule = "FREQ=WEEKLY;UNTIL=20180609T190000"
+      #   _normalize_rrule_until(rrule, 'Europe/Berlin')
+      #   # => "FREQ=WEEKLY;UNTIL=20180609T190000Z"  (Z added to prevent system-TZ interpretation)
+      #
+      # @example UTC UNTIL gets converted to event timezone, then Z appended
+      #   rrule = "FREQ=WEEKLY;UNTIL=20180609T170000Z"  # 17:00 UTC
+      #   _normalize_rrule_until(rrule, 'Europe/Berlin')  # Event in Berlin (UTC+2)
+      #   # => "FREQ=WEEKLY;UNTIL=20180609T190000Z"  (17:00 UTC → 19:00 Berlin, Z prevents conversion)
+      #
+      def _normalize_rrule_until(rrule_string, target_timezone)
+        # Match UNTIL with UTC time (Z suffix) or with explicit time
+        # Matches: UNTIL=20180615T120000Z or UNTIL=20180615T120000
+        rrule_string.gsub(/UNTIL=(\d{8}T\d{6})(Z?)/) do |_match|
+          timestamp_str = $1
+          is_utc = $2 == 'Z'
+
+          # RFC 5545 floating time (no Z): pass through unchanged, but add Z to prevent
+          # IceCube from interpreting it in system-TZ
+          next "UNTIL=#{timestamp_str}Z" unless is_utc
+
+          # Already UTC with Z - convert to floating in target timezone but add Z to prevent
+          # IceCube from interpreting it in system-TZ
+          year = timestamp_str[0..3].to_i
+          month = timestamp_str[4..5].to_i
+          day = timestamp_str[6..7].to_i
+          hour = timestamp_str[9..10].to_i
+          minute = timestamp_str[11..12].to_i
+          second = timestamp_str[13..14].to_i
+
+          time_obj = Time.utc(year, month, day, hour, minute, second)
+          floating_until = _to_floating_time(time_obj, target_timezone)
+
+          # Format with Z to prevent IceCube system-TZ interpretation
+          "UNTIL=#{floating_until.strftime('%Y%m%dT%H%M%S')}Z"
+        end
+      end
+
       ##
       # Transform the given object into an object of type `ActiveSupport::TimeWithZone`.
       #
@@ -421,8 +505,8 @@ module Icalendar
           return _date_to_time_with_zone(date_time_value, timezone)
 
         elsif date_time_value.is_a?(Time)
-          # Preserve Time's timezone by converting to UTC first, then to target timezone
-          return timezone.at(date_time_value.getutc)
+          # Treat Ruby Time as quasi-floating: preserve wall-clock time, embed in the target timezone
+          return _embed_in_timezone_preserving_wall_clock(date_time_value, timezone)
 
         elsif date_time_value.respond_to?(:to_time)
           return timezone.at(date_time_value.to_time)
@@ -435,6 +519,7 @@ module Icalendar
         # Oops, the given object is unusable, we'll give back the NULL_DATE
         timezone.at(NULL_TIME)
       end
+
       # rubocop:enable Metrics/MethodLength,Metrics/AbcSize, Metrics/PerceivedComplexity, Metrics/CyclomaticComplexity
 
       ##
@@ -447,9 +532,158 @@ module Icalendar
         timezone.local(d.year, d.month, d.day)
       end
 
+      ##
+      # Converts any time to floating time, CONVERTING to the target timezone first.
+      #
+      # Use this when you want the wall-clock time in a DIFFERENT timezone.
+      # Example: EXDATE:20260330T080000Z (UTC) with event in Berlin → 10:00 floating (Berlin wall-clock)
+      #
+      # @param [Object] date_or_time any object representing a time (Icalendar::Values::DateTime,
+      #   ActiveSupport::TimeWithZone, Date, Time, Integer, etc.)
+      # @param [ActiveSupport::TimeZone,String] target_tz the timezone to interpret the time in
+      #   before converting to floating time.
+      # @return [Time] a Ruby Time object with UTC offset 0 (floating time)
+      # @api private
+      #
+      # @example Convert a UTC timestamp to floating time in Berlin
+      #   # UTC: 2018-01-01 15:00 UTC → Berlin: 2018-01-01 16:00 CET
+      #   floating = _to_floating_time(utc_time, ActiveSupport::TimeZone['Europe/Berlin'])
+      #   # => 2018-01-01 16:00:00 +0000 (floating)
+      def _to_floating_time(date_or_time, target_tz)
+
+        if date_or_time.is_a?(Date)
+          return Time.new(date_or_time.year, date_or_time.month, date_or_time.day, 0, 0, 0, 0)
+        end
+
+        if date_or_time.is_a?(Icalendar::Values::Date)
+          return Time.new(date_or_time.year, date_or_time.month, date_or_time.day, 0, 0, 0, 0)
+        end
+
+        active_target_tz = _ensure_active_timezone(target_tz)
+
+        # Convert to TimeWithZone in the target timezone first
+        time_with_zone = _embed_in_timezone_preserving_moment(date_or_time, active_target_tz)
+
+        # Extract wall-clock components and create floating time (offset 0)
+        Time.new(
+          time_with_zone.year,
+          time_with_zone.month,
+          time_with_zone.day,
+          time_with_zone.hour,
+          time_with_zone.min,
+          time_with_zone.sec,
+          0 # UTC offset 0 = floating time
+        )
+      end
+
+      ##
+      # Embeds a Ruby Time object into a timezone, preserving wall-clock time.
+      #
+      # This treats the Time as "quasi-floating" - we take its wall-clock components
+      # (year, month, day, hour, minute, second) and interpret them in the target timezone,
+      # ignoring the original offset. The UTC moment will change according to the
+      # timezone offset difference.
+      #
+      # A warning is logged if the Time's original offset doesn't match the target
+      # timezone's offset (indicating potential user confusion about timezones).
+      #
+      # Use this when the Time represents a wall-clock reading (e.g., from user input
+      # or an iCalendar floating time) that should be interpreted in a specific timezone.
+      #
+      # @example
+      #   local_time = Time.new(2026, 1, 15, 12, 0, 0, '+05:00')  # 12:00 somewhere
+      #   berlin = ActiveSupport::TimeZone['Europe/Berlin']
+      #   result = _embed_in_timezone_preserving_wall_clock(local_time, berlin)
+      #   # => 2026-01-15 12:00:00 +0100 (same wall-clock, different moment)
+      #
+      # @param [Time] time_value a Ruby Time object
+      # @param [ActiveSupport::TimeZone] timezone the target timezone
+      # @return [ActiveSupport::TimeWithZone] the time embedded in the target timezone
+      # @api private
+      # @see _embed_in_timezone_preserving_moment for the inverse operation
+      def _embed_in_timezone_preserving_wall_clock(time_value, timezone)
+        # Create the result in target timezone with same wall-clock time
+        result = timezone.local(
+          time_value.year,
+          time_value.month,
+          time_value.day,
+          time_value.hour,
+          time_value.min,
+          time_value.sec
+        )
+
+        # Warn if the original offset doesn't match the target timezone
+        if time_value.utc_offset != result.utc_offset
+          Icalendar::Rrule.logger.warn do
+            "[icalendar-rrule] Time offset (#{time_value.utc_offset}s) differs from target timezone " \
+              "#{timezone.name} - forcing to #{result.utc_offset}s"
+          end
+        end
+
+        result
+      end
+
+      ##
+      # Embeds a Ruby Time object into a timezone, preserving the UTC moment.
+      #
+      # Converts the Time to the target timezone while keeping the same instant in time.
+      # The wall-clock time will change according to the timezone offset difference.
+      #
+      # Use this when the Time represents a specific moment in time (e.g., from a database
+      # timestamp or API response) that should be displayed in a different timezone.
+      #
+      # @example
+      #   utc_time = Time.utc(2026, 1, 15, 12, 0, 0)  # 12:00 UTC
+      #   berlin = ActiveSupport::TimeZone['Europe/Berlin']
+      #   result = _embed_in_timezone_preserving_moment(utc_time, berlin)
+      #   # => 2026-01-15 13:00:00 +0100 (same moment, different wall-clock)
+      #
+      # @param [Time] time_value a Ruby Time object
+      # @param [ActiveSupport::TimeZone] timezone the target timezone
+      # @return [ActiveSupport::TimeWithZone] the time in the target timezone
+      # @api private
+      # @see _embed_time_preserving_wall_clock for the inverse operation
+      def _embed_in_timezone_preserving_moment(time_value, timezone)
+        if time_value.respond_to?(:to_time)
+          timezone.at(time_value.to_time.getutc)
+        elsif time_value.is_a?(Integer)
+          timezone.at(time_value)
+        else
+          throw ArgumentError, "Unexpected time value: #{time_value}"
+        end
+      end
+
+      ##
+      # Ensures the given `tz` is either an ActiveSupport::TimeZone object or the name of an existing timezone.
+      #
+      # If the given timezone name is invalid, logs a warning and returns UTC.
+      #
+      # @param [ActiveSupport::TimeZone,String] tz a timezone object or timezone name string
+      # @return [ActiveSupport::TimeZone] the given timezone object, the timezone with the given name,
+      #   or UTC if the given timezone-name is invalid
+      # @api private
+      def _ensure_active_timezone(tz)
+        # If already a TimeZone object, return it
+        return tz if tz.is_a?(ActiveSupport::TimeZone)
+
+        # Try to lookup by name/value
+        result = ActiveSupport::TimeZone[tz]
+        return result if result
+
+        # Invalid timezone - log warning and return UTC
+        Icalendar::Rrule.logger.warn do
+          "[icalendar-rrule] Invalid timezone '#{tz.inspect}' - falling back to UTC"
+        end
+
+        # Fallback to UTC
+        # Use offset 0 as fallback if even 'UTC' lookup fails (should never happen)
+        ActiveSupport::TimeZone['UTC'] || ActiveSupport::TimeZone[0]
+      end
+
       ##
       # Heuristic to determine the best timezone that shall be used in this component.
       # @return [ActiveSupport::TimeZone] the unique timezone used in this component
+      # @deprecated there is no unique timezone for a component. Use `timezone_for_start` or `timezone_for_end` instead.
       def component_timezone
         # let's try sequentially, the first non-nil wins.
         timezone ||= _extract_explicit_timezone(_dtend)
@@ -462,10 +696,26 @@ module Icalendar
         timezone || ActiveSupport::TimeZone['UTC']
       end
 
+      ##
+      # Determine the timezone that shall be used for `start_time` this component
+      # @return [ActiveSupport::TimeZone] the unique timezone used for the start_time of this component
+      def _timezone_for_start
+        # todo: determine timezone purely from input parameters (i.e from _dtstart, _dtend, _due)
+        start_time.time_zone
+      end
+
+      ##
+      # Determine the timezone that shall be used for `end_time` this component
+      # @return [ActiveSupport::TimeZone] the unique timezone used for the end_time of this component
+      def _timezone_for_end
+        # todo: determine timezone purely from input parameters (i.e from _dtstart, _dtend, _due)
+        end_time.time_zone
+      end
+
       ##
       # Try to determine this components time zone by inspecting the parents calendar.
       # @return[ActiveSupport::TimeZone, nil] the first valid timezone found in the
-      #    parent calender or nil if none could be found.
+      #    parent calendar or nil if none could be found.
       #
       # rubocop:disable Metrics/CyclomaticComplexity
       def _extract_calendar_timezone
@@ -483,6 +733,7 @@ module Icalendar
       rescue StandardError
         nil
       end
+
       # rubocop:enable Metrics/CyclomaticComplexity
 
       ##
@@ -501,9 +752,9 @@ module Icalendar
       # @return [ActiveSupport::TimeZone, nil] the explicitly set timezone, or nil if none found.
       # @api private
       def _extract_explicit_timezone(date_time)
-        timezone ||= _extract_ical_time_zone(date_time)      # try with ical TZID parameter (most specific)
-        timezone ||= _extract_act_sup_timezone(date_time)    # is the given value already ActiveSupport::TimeWithZone?
-        timezone || _extract_value_time_zone(date_time)      # is the ical.value of type ActiveSupport::TimeWithZone?
+        timezone ||= _extract_ical_time_zone(date_time) # try with ical TZID parameter (most specific)
+        timezone ||= _extract_act_sup_timezone(date_time) # is the given value already ActiveSupport::TimeWithZone?
+        timezone || _extract_value_time_zone(date_time) # is the ical.value of type ActiveSupport::TimeWithZone?
       end
 
       ##
@@ -545,6 +796,7 @@ module Icalendar
       #   Should respond to :utc_offset (e.g., Time, DateTime, Icalendar::Values::DateTime).
       # @return [ActiveSupport::TimeZone, nil] an ActiveSupport::TimeZone matching the UTC offset,
       #   or nil if no match is found or an error occurs.
+      # @deprecated makes little sense and can be avoided.
       # @api private
       def _guess_timezone_from_offset(date_time)
         # Extract value from Icalendar::Values::DateTime if needed
@@ -602,6 +854,8 @@ module Icalendar
       # Attempts to determine the system's timezone.
       # Tries multiple methods in order of reliability.
       #
+      # @note see also https://rubygems.org/gems/timezone_local - it does about the same as this.
+      #
       # @return [ActiveSupport::TimeZone, nil] the system timezone or nil if it cannot be determined.
       # @api private
       def _guess_system_timezone
@@ -646,7 +900,6 @@ module Icalendar
         nil
       end
 
-
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: icalendar-rrule
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Harald Postner
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.1'
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.1'
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: icalendar
   requirement: !ruby/object:Gem::Requirement
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '0.17'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.16'
+        version: '0.17'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -143,6 +143,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
@@ -157,6 +158,7 @@ files:
 - lib/icalendar-rrule.rb
 - lib/icalendar/rrule.rb
 - lib/icalendar/rrule/occurrence.rb
+- lib/icalendar/rrule/time_refinements.rb
 - lib/icalendar/rrule/version.rb
 - lib/icalendar/scannable-calendar.rb
 - lib/icalendar/schedulable-component.rb
@@ -174,7 +176,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="