fix: use NumberValue to calculate datetime instead of parsing (#379)

**What**:
This PR makes use of the the locale-independent `NumberValue` (decimal
datetime value) from the Google Sheets API instead of parsing the
locale-dependent `FormattedValue` string.

The decimal datetime value stores dates as decimal numbers where:
- Integer part = days since December 30, 1899
- Fractional part = time of day (for DATE_TIME types)

This is documented in the [Google Sheets API formats
guide](https://developers.google.com/workspace/sheets/api/guides/formats)

It maintains a fallback to the old parsing in case `NumberValue` is
missing (this is unexpected and we can consider returning an error if we
want to be a bit strict).

Some examples:
Unhinged custom date/time formatting:
<img width="165" height="72" alt="Screenshot 2025-12-04 at 17 16 49"
src="https://github.com/user-attachments/assets/c8923ae9-fa40-475d-8ce2-ce7c4a39b807"
/>

This PR would render the above as (note that I set time to UTC +2):
<img width="162" height="113" alt="Screenshot 2025-12-04 at 16 21 54"
src="https://github.com/user-attachments/assets/c6c38c66-80d3-4479-88b8-c3f07f6e5296"
/>


**Why**:
The original implementation used `dateparse.ParseLocal()` to parse the
`FormattedValue` string (e.g., "1/5/2020" or "5/1/2020"), which caused
different date interpretations depending on the server's locale
settings.

For example, A date displayed as "1/5/2020" could be parsed as January
5th instead of the May 1st.

**Fixes**: 
Fixes #123

Author: fridgepoet

.changeset/khaki-apes-own.md

@@ -0,0 +1,5 @@
+---
+'grafana-google-sheets-datasource': patch
+---
+
+use NumberValue to calculate datetime instead of parsing

pkg/googlesheets/googlesheets.go

@@ -246,11 +246,36 @@ var timeConverter = data.FieldConverter{
 		if !ok {
 			return t, fmt.Errorf("expected type *sheets.CellData, but got %T", i)
 		}
-		parsedTime, err := dateparse.ParseLocal(cellData.FormattedValue)
-		if err != nil {
-			return t, fmt.Errorf("error while parsing date '%v'", cellData.FormattedValue)
+
+		switch {
+		// Convert time based on decimal "Number Value" if possible; format agnostic
+		case cellData.EffectiveValue != nil && cellData.EffectiveValue.NumberValue != nil:
+			const (
+				secondsPerDay        = 24 * 60 * 60
+				nanosecondsPerSecond = 1e9
+			)
+
+			// Dates are stored as decimal values where each whole number represents a day counted from December 30, 1899.
+			// See https://developers.google.com/workspace/sheets/api/guides/formats
+			decimalDateTime := *cellData.EffectiveValue.NumberValue
+			baseDate := time.Date(1899, 12, 30, 0, 0, 0, 0, time.UTC)
+			days := int64(decimalDateTime)
+			calculatedDate := baseDate.AddDate(0, 0, int(days))
+
+			timeRemainder := decimalDateTime - float64(days)
+
+			// Put calculated date and time remainder together
+			calculatedDateTime := calculatedDate.Add(time.Duration(timeRemainder * secondsPerDay * nanosecondsPerSecond))
+			return &calculatedDateTime, nil
+
+		// Else, fallback to the old parsing for backwards compatibility
+		default:
+			parsedTime, err := dateparse.ParseLocal(cellData.FormattedValue)
+			if err != nil {
+				return t, fmt.Errorf("error while parsing date '%v'", cellData.FormattedValue)
+			}
+			return &parsedTime, nil
 		}
-		return &parsedTime, nil
 	},
 }
 

pkg/googlesheets/googlesheets_test.go

@@ -370,3 +370,58 @@ func TestGooglesheets(t *testing.T) {
 		assert.Equal(t, "Plain Text Value", *strVal)
 	})
 }
+
+func Test_timeConverter(t *testing.T) {
+	t.Run("timeConverter with Number Value converts to time.Time", func(t *testing.T) {
+		serialDate := 43845.5 // 15 January 2020 12:00:00 (0.5 days = 12 hours)
+		cell := &sheets.CellData{
+			EffectiveValue: &sheets.ExtendedValue{
+				NumberValue: &serialDate,
+			},
+		}
+
+		result, err := timeConverter.Converter(cell)
+		require.NoError(t, err)
+
+		require.NotNil(t, result)
+		date, ok := result.(*time.Time)
+		require.True(t, ok)
+		assert.Equal(t, 2020, date.Year())
+		assert.Equal(t, time.January, date.Month())
+		assert.Equal(t, 15, date.Day())
+		assert.Equal(t, 12, date.Hour())
+		assert.Equal(t, 0, date.Minute())
+		assert.Equal(t, 0, date.Second())
+	})
+
+	t.Run("timeConverter without Number Value falls back to parsing FormattedValue", func(t *testing.T) {
+		cell := &sheets.CellData{
+			FormattedValue: "2020-01-15 12:00:00",
+		}
+
+		result, err := timeConverter.Converter(cell)
+		require.NoError(t, err)
+
+		require.NotNil(t, result)
+		date, ok := result.(*time.Time)
+		require.True(t, ok)
+		assert.Equal(t, 2020, date.Year())
+		assert.Equal(t, time.January, date.Month())
+		assert.Equal(t, 15, date.Day())
+		assert.Equal(t, 12, date.Hour())
+		assert.Equal(t, 0, date.Minute())
+		assert.Equal(t, 0, date.Second())
+	})
+
+	t.Run("timeConverter returns error when parsing FormattedValue fails", func(t *testing.T) {
+		cell := &sheets.CellData{
+			FormattedValue: "not a valid date",
+		}
+
+		_, err := timeConverter.Converter(cell)
+
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "error while parsing date")
+		assert.Contains(t, err.Error(), "not a valid date")
+	})
+}