[BUGFIX] (dashboards): apply dashboard.spec.timezone to TimeZoneProvider

dashboards/src/components/DashboardStickyToolbar/DashboardStickyToolbar.tsx

@@ -13,6 +13,7 @@
 
 import type { SxProps, Theme } from '@mui/material';
 import { AppBar, Box, IconButton, Stack, useMediaQuery, useScrollTrigger, useTheme } from '@mui/material';
+import { useTimeZone } from '@perses-dev/components';
 import { TimeRangeControls, useTimeZoneParams } from '@perses-dev/plugin-system';
 import PinOffOutline from 'mdi-material-ui/PinOffOutline';
 import PinOutline from 'mdi-material-ui/PinOutline';
@@ -34,7 +35,8 @@ export function DashboardStickyToolbar(props: DashboardStickyToolbarProps): Reac
 
   const isBiggerThanMd = useMediaQuery(useTheme().breakpoints.up('md'));
 
-  const { timeZone, setTimeZone } = useTimeZoneParams('local');
+  const { timeZone: contextTimeZone } = useTimeZone();
+  const { timeZone, setTimeZone } = useTimeZoneParams(contextTimeZone);
 
   return (
     // marginBottom={-1} counteracts the marginBottom={1} on every variable input.

dashboards/src/utils/index.ts

@@ -15,3 +15,4 @@ export * from './panelUtils';
 export * from './pluginVersioning';
 export * from './repeatLayoutUtils';
 export * from './gridLayoutUtils';
+export * from './timezone';

dashboards/src/utils/timezone.test.ts

@@ -0,0 +1,52 @@
+// Copyright The Perses Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { describe, expect, it } from 'vitest';
+
+import { resolveDashboardTimeZone } from './timezone';
+
+describe('resolveDashboardTimeZone', () => {
+  it.each([
+    // [dashboard, user, expected]
+    ['UTC', 'Europe/Berlin', 'UTC'],
+    ['America/New_York', 'UTC', 'America/New_York'],
+    ['Europe/London', 'local', 'Europe/London'],
+    ['local', 'UTC', 'local'],
+    ['Etc/UTC', undefined, 'Etc/UTC'],
+    ['GMT', null, 'GMT'],
+    ['  UTC  ', 'Europe/Berlin', 'UTC'],
+    [undefined, 'Europe/Paris', 'Europe/Paris'],
+    [null, 'Asia/Tokyo', 'Asia/Tokyo'],
+    ['', 'Europe/Berlin', 'Europe/Berlin'],
+    ['   ', 'UTC', 'UTC'],
+    [undefined, '  Europe/Berlin  ', 'Europe/Berlin'],
+    [undefined, undefined, 'local'],
+    [null, null, 'local'],
+    ['', '', 'local'],
+    ['  ', '  ', 'local'],
+    [undefined, '', 'local'],
+    ['', undefined, 'local'],
+  ] as const)('dashboard=%j user=%j → %j', (dashboard, user, expected) => {
+    expect(resolveDashboardTimeZone(dashboard, user)).toBe(expected);
+  });
+
+  it('matches docs hierarchy: panel/dashboard before user before browser local', () => {
+    // Documented order for dashboard-level resolution (URL ?tz= is separate).
+    const steps = [
+      resolveDashboardTimeZone('UTC', 'Europe/Berlin'),
+      resolveDashboardTimeZone(undefined, 'Europe/Berlin'),
+      resolveDashboardTimeZone(undefined, undefined),
+    ];
+    expect(steps).toEqual(['UTC', 'Europe/Berlin', 'local']);
+  });
+});

dashboards/src/utils/timezone.ts

@@ -0,0 +1,27 @@
+// Copyright The Perses Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/**
+ * Default timezone when URL `?tz=` is absent.
+ * Full runtime order (see useTimeZoneParams):
+ * 1. URL query `tz`
+ * 2. dashboard.spec.timezone
+ * 3. user preference timezone
+ * 4. browser `local`
+ */
+export function resolveDashboardTimeZone(
+  dashboardTimezone?: string | null,
+  userPreferenceTimezone?: string | null,
+): string {
+  return dashboardTimezone?.trim() || userPreferenceTimezone?.trim() || 'local';
+}

dashboards/src/views/ViewDashboard/DashboardApp.tsx

@@ -36,6 +36,7 @@ import {
 import type { OnSaveDashboard } from '../../context';
 import { useDashboard, useDiscardChangesConfirmationDialog, useEditMode } from '../../context';
 import { PanelFocusProvider } from '../../keyboard-shortcuts';
+import { resolveDashboardTimeZone } from '../../utils/timezone';
 
 export interface DashboardAppProps {
   dashboardResource: DashboardResource;
@@ -142,8 +143,8 @@ const DashboardAppContent = (props: DashboardAppProps): ReactElement => {
   });
 
   const toolBarTimezone = useMemo((): string => {
-    return dashboardResource.spec.timezone || userPreferenceTimezone || 'local';
-  }, [dashboardResource.spec, userPreferenceTimezone]);
+    return resolveDashboardTimeZone(dashboardResource.spec.timezone, userPreferenceTimezone);
+  }, [dashboardResource.spec.timezone, userPreferenceTimezone]);
 
   return (
     <Box

dashboards/src/views/ViewDashboard/ViewDashboard.tsx

@@ -28,6 +28,7 @@ import { DEFAULT_DASHBOARD_DURATION, DEFAULT_REFRESH_INTERVAL } from '../../cons
 import type { DatasourceStoreProviderProps, VariableProviderProps } from '../../context';
 import { DatasourceStoreProvider, VariableProviderWithQueryParams, AnnotationProvider } from '../../context';
 import { DashboardProviderWithQueryParams } from '../../context/DashboardProvider/DashboardProviderWithQueryParams';
+import { resolveDashboardTimeZone } from '../../utils/timezone';
 import type { DashboardAppProps } from './DashboardApp';
 import { DashboardApp } from './DashboardApp';
 
@@ -72,6 +73,11 @@ export function ViewDashboard(props: ViewDashboardProps): ReactElement {
   const dashboardRefreshInterval = spec.refreshInterval ?? DEFAULT_REFRESH_INTERVAL;
   const initialTimeRange = useInitialTimeRange(dashboardDuration);
   const initialRefreshInterval = useInitialRefreshInterval(dashboardRefreshInterval);
+  // Seed TimeRangeProviderWithQueryParams → useTimeZoneParams (URL ?tz= still wins).
+  const initialTimeZone = useMemo(
+    () => resolveDashboardTimeZone(spec.timezone, userPreferenceTimezone),
+    [spec.timezone, userPreferenceTimezone],
+  );
   const { data } = usePluginBuiltinVariableDefinitions();
 
   const builtinVariables = useMemo(() => {
@@ -121,6 +127,7 @@ export function ViewDashboard(props: ViewDashboardProps): ReactElement {
         <TimeRangeProviderWithQueryParams
           initialTimeRange={initialTimeRange}
           initialRefreshInterval={initialRefreshInterval}
+          initialTimeZone={initialTimeZone}
         >
           <VariableProviderWithQueryParams
             initialVariableDefinitions={spec.variables}

dashboards/src/views/ViewDashboard/tests/dashboardTimezone.test.tsx

@@ -0,0 +1,87 @@
+// Copyright The Perses Authors
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { useTimeZone } from '@perses-dev/components';
+import { TimeRangeProviderWithQueryParams } from '@perses-dev/plugin-system';
+import { screen } from '@testing-library/react';
+import { createMemoryHistory } from 'history';
+import type { ReactElement } from 'react';
+
+import { renderWithContext } from '../../../test';
+import { resolveDashboardTimeZone } from '../../../utils/timezone';
+
+/**
+ * Probe: charts read timezone from the single TimeZoneProvider inside
+ * TimeRangeProviderWithQueryParams.
+ */
+function TimeZoneProbe(): ReactElement {
+  const { timeZone } = useTimeZone();
+  return <output aria-label="chart-timezone">{timeZone}</output>;
+}
+
+/**
+ * Mirrors ViewDashboard: resolveDashboardTimeZone → initialTimeZone on the helper.
+ */
+function DashboardTimeZoneHarness(props: {
+  dashboardTimezone?: string;
+  userPreferenceTimezone?: string;
+}): ReactElement {
+  const initialTimeZone = resolveDashboardTimeZone(props.dashboardTimezone, props.userPreferenceTimezone);
+  return (
+    <TimeRangeProviderWithQueryParams initialTimeRange={{ pastDuration: '1h' }} initialTimeZone={initialTimeZone}>
+      <TimeZoneProbe />
+      <output aria-label="resolved-initial">{initialTimeZone}</output>
+    </TimeRangeProviderWithQueryParams>
+  );
+}
+
+describe('Dashboard timezone wiring (single TimeZoneProvider path)', () => {
+  it('charts see dashboard.spec.timezone when set (wins over user pref)', () => {
+    renderWithContext(<DashboardTimeZoneHarness dashboardTimezone="UTC" userPreferenceTimezone="Europe/Berlin" />);
+
+    expect(screen.getByLabelText('resolved-initial')).toHaveTextContent('UTC');
+    expect(screen.getByLabelText('chart-timezone')).toHaveTextContent('UTC');
+  });
+
+  it('charts see user preference when dashboard timezone is empty', () => {
+    renderWithContext(<DashboardTimeZoneHarness dashboardTimezone="" userPreferenceTimezone="Europe/Paris" />);
+
+    expect(screen.getByLabelText('chart-timezone')).toHaveTextContent('Europe/Paris');
+  });
+
+  it('charts fall back to local when neither is set', () => {
+    renderWithContext(<DashboardTimeZoneHarness />);
+
+    expect(screen.getByLabelText('chart-timezone')).toHaveTextContent('local');
+  });
+
+  it('explicit dashboard local wins over user UTC', () => {
+    renderWithContext(<DashboardTimeZoneHarness dashboardTimezone="local" userPreferenceTimezone="UTC" />);
+
+    expect(screen.getByLabelText('chart-timezone')).toHaveTextContent('local');
+  });
+
+  it('URL ?tz= overrides the resolved initial', () => {
+    const history = createMemoryHistory({
+      initialEntries: ['/?tz=Asia/Tokyo'],
+    });
+    renderWithContext(
+      <DashboardTimeZoneHarness dashboardTimezone="UTC" userPreferenceTimezone="Europe/Berlin" />,
+      undefined,
+      history,
+    );
+
+    expect(screen.getByLabelText('chart-timezone')).toHaveTextContent('Asia/Tokyo');
+    expect(screen.getByLabelText('resolved-initial')).toHaveTextContent('UTC');
+  });
+});

plugin-system/src/runtime/TimeRangeProvider/TimeRangeProviders.tsx

@@ -22,17 +22,20 @@ import { TimeRangeProvider } from './TimeRangeProvider';
 export interface TimeRangeProvidersProps {
   initialTimeRange: TimeRangeValue;
   initialRefreshInterval?: DurationString;
+  /** Seed for useTimeZoneParams when URL ?tz= is absent (default: local). */
+  initialTimeZone?: string;
   children?: React.ReactNode;
 }
 
 export function TimeRangeProviderWithQueryParams({
   initialTimeRange,
   initialRefreshInterval,
+  initialTimeZone = 'local',
   children,
 }: TimeRangeProvidersProps): ReactElement {
   const { timeRange, setTimeRange } = useTimeRangeParams(initialTimeRange);
   const { refreshInterval, setRefreshInterval } = useSetRefreshIntervalParams(initialRefreshInterval);
-  const { timeZone } = useTimeZoneParams('local');
+  const { timeZone } = useTimeZoneParams(initialTimeZone);
 
   return (
     <TimeRangeProvider