Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): a day whose midnight daylight saving skips starts at its first instant (#7081)

Cindy Zhang2fadc27f7159
diff --git a/.changeset/plain-date-skipped-midnight.md b/.changeset/plain-date-skipped-midnight.md
new file mode 100644
index 0000000000..2d21ef736b
--- /dev/null
+++ b/.changeset/plain-date-skipped-midnight.md
@@ -0,0 +1,10 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `plainDateToInstant` resolves wall times that daylight saving skips or repeats the way Temporal's default `"compatible"` disambiguation does (AST-067).
+
+- A skipped wall time moves forward by the length of the gap. In a zone that springs forward from a negative offset at local midnight, such as America/Santiago on September 6, 2026 or America/Havana on March 8, 2026, the start of that day came back as 11:00 PM the day before, so a week or day range landed on the wrong date; it is now the day's first instant (1:00 AM).
+- A repeated wall time resolves to its earlier occurrence in every zone. In zones with a positive offset, such as Europe/Berlin on October 25, 2026, it resolved to the later one.
+
+@cixzhang
diff --git a/apps/storybook/stories/Schedule.stories.tsx b/apps/storybook/stories/Schedule.stories.tsx
index 6414b39d67..902891b7e3 100644
--- a/apps/storybook/stories/Schedule.stories.tsx
+++ b/apps/storybook/stories/Schedule.stories.tsx
@@ -620,6 +620,92 @@ export const EventPopover: Story = {
},
};
+// Two zones that spring forward from a negative offset at local midnight, so
+// the first day of each week starts at 1:00 AM.
+const SKIPPED_MIDNIGHT_ZONES = [
+ {
+ timezoneID: 'America/Santiago',
+ date: Date.UTC(2026, 8, 6, 15) as Instant,
+ firstHour: '2026-09-06T04:30:00.000Z',
+ },
+ {
+ timezoneID: 'America/Havana',
+ date: Date.UTC(2026, 2, 8, 15) as Instant,
+ firstHour: '2026-03-08T05:30:00.000Z',
+ },
+];
+
+function SkippedMidnightZone({
+ timezoneID,
+ date: initialDate,
+ firstHour,
+}: (typeof SKIPPED_MIDNIGHT_ZONES)[number]) {
+ const [weekDate, setWeekDate] = useState<Instant>(initialDate);
+ const [dayDate, setDayDate] = useState<Instant>(initialDate);
+ const weekView = useMemo(
+ () => createScheduleWeeklyView({minHour: 0, maxHour: 4}),
+ [],
+ );
+ const dayView = useMemo(
+ () => createScheduleDayView({minHour: 0, maxHour: 4}),
+ [],
+ );
+ const zoneEvents = useMemo(
+ () => [
+ createEventFromISO({
+ id: `${timezoneID}-first-hour`,
+ title: 'First hour',
+ category: 'Focus',
+ start: firstHour,
+ end: new Date(Date.parse(firstHour) + 60 * 60 * 1000).toISOString(),
+ }),
+ ],
+ [timezoneID, firstHour],
+ );
+ return (
+ <section
+ aria-label={timezoneID}
+ data-zone={timezoneID}
+ style={{display: 'grid', gap: 8}}>
+ <Text type="label" weight="bold">
+ {timezoneID}
+ </Text>
+ <Schedule
+ view={weekView}
+ events={zoneEvents}
+ categories={categories}
+ date={weekDate}
+ focusDate={initialDate}
+ onChangeDate={setWeekDate}
+ timezoneID={timezoneID}
+ />
+ <Schedule
+ view={dayView}
+ events={zoneEvents}
+ categories={categories}
+ date={dayDate}
+ focusDate={initialDate}
+ onChangeDate={setDayDate}
+ timezoneID={timezoneID}
+ />
+ </section>
+ );
+}
+
+/**
+ * Weeks and days whose midnight daylight saving skips keep their own dates:
+ * seven columns in the week, one in the day view.
+ */
+export const SkippedMidnight: Story = {
+ render: () => (
+ <div style={{display: 'grid', gap: 24}}>
+ {SKIPPED_MIDNIGHT_ZONES.map(zone => (
+ <SkippedMidnightZone key={zone.timezoneID} {...zone} />
+ ))}
+ </div>
+ ),
+};
+
const midnightEvents: CalendarEvent[] = [
createEventFromISO({
id: 'planning',
diff --git a/docs/specs/AST-067-wall-time-resolution/spec.md b/docs/specs/AST-067-wall-time-resolution/spec.md
index d67c47dad5..71081a0c9e 100644
--- a/docs/specs/AST-067-wall-time-resolution/spec.md
+++ b/docs/specs/AST-067-wall-time-resolution/spec.md
@@ -74,7 +74,6 @@ Temporal agree on every instant.
- `plainDateToInstant` in `@astryxdesign/core/utils` is the governed API.
- Lab `Schedule` turns the days of its week and day ranges into instants through it; `component:Schedule` keeps ownership of how a range is chosen and laid out.
-- Implementation gap: in zones with negative offsets, `plainDateToInstant` resolves a skipped wall time backward (2:30 AM on America/Los_Angeles's spring-forward day becomes 1:30 AM), so a skipped midnight lands on the previous date (America/Santiago, America/Havana) and a Schedule week or day across that change starts a day early; in zones with positive offsets it resolves a repeated wall time to its later occurrence (Europe/Berlin, Australia/Sydney). Verification's named-zone cases are not yet in `plainDate.test.ts` or the Schedule tests.
- `architecture:public-component-api` continues to own the utility's export and
compatibility.
diff --git a/packages/core/src/utils/plainDate.test.ts b/packages/core/src/utils/plainDate.test.ts
index 7399f4729c..c4db911e68 100644
--- a/packages/core/src/utils/plainDate.test.ts
+++ b/packages/core/src/utils/plainDate.test.ts
@@ -412,6 +412,105 @@ describe('plainDateToInstant / plainDateFromInstant', () => {
).toBe(Date.UTC(2026, 4, 13, 16, 30));
});
+ it.each([
+ // Both spring forward from a negative offset at local midnight.
+ [
+ 'America/Santiago',
+ {year: 2026, month: 9, day: 6},
+ Date.UTC(2026, 8, 6, 4),
+ ],
+ ['America/Havana', {year: 2026, month: 3, day: 8}, Date.UTC(2026, 2, 8, 5)],
+ // A positive offset already resolved forward; it must not move.
+ ['Asia/Beirut', {year: 2026, month: 3, day: 29}, Date.UTC(2026, 2, 28, 22)],
+ ] as const)(
+ 'starts a day whose midnight daylight saving skips at its first instant (%s)',
+ (timezoneID, date, firstInstant) => {
+ const instant = plainDateToInstant(date, timezoneID);
+ expect(instant).toBe(firstInstant);
+ expect(plainDateFromInstant(instant, timezoneID)).toEqual(date);
+ expect(plainDateFromInstant(instant - 1, timezoneID)).not.toEqual(date);
+ },
+ );
+
+ it('resolves any wall time inside a daylight-saving gap forward', () => {
+ // 2:30 AM does not happen on March 8, 2026 in Los Angeles: 3:30 AM PDT.
+ expect(
+ plainDateToInstant(
+ {year: 2026, month: 3, day: 8},
+ 'America/Los_Angeles',
+ 2,
+ 30,
+ ),
+ ).toBe(Date.UTC(2026, 2, 8, 10, 30));
+ });
+
+ it('keeps the earlier instant of a wall time that happens twice', () => {
+ // Havana falls back at 1:00 AM on November 1, 2026: midnight once, then
+ // 12:00–1:00 AM twice; the first 12:30 AM is still daylight time.
+ expect(
+ plainDateToInstant(
+ {year: 2026, month: 11, day: 1},
+ 'America/Havana',
+ 0,
+ 30,
+ ),
+ ).toBe(Date.UTC(2026, 10, 1, 4, 30));
+ });
+
+ it.each([
+ // Berlin falls back at 3:00 AM CEST on October 25, 2026: 2:00–3:00 AM
+ // happens twice, first at +2, then at +1.
+ [
+ 'Europe/Berlin',
+ {year: 2026, month: 10, day: 25},
+ 2,
+ 30,
+ Date.UTC(2026, 9, 25, 0, 30),
+ ],
+ // Sydney falls back at 3:00 AM AEDT on April 5, 2026: first at +11.
+ [
+ 'Australia/Sydney',
+ {year: 2026, month: 4, day: 5},
+ 2,
+ 30,
+ Date.UTC(2026, 3, 4, 15, 30),
+ ],
+ ] as const)(
+ 'keeps the earlier instant of a repeated wall time in a positive-offset zone (%s)',
+ (timezoneID, date, hour, minute, earlier) => {
+ expect(plainDateToInstant(date, timezoneID, hour, minute)).toBe(earlier);
+ },
+ );
+
+ it('starts a date the zone skips at the first instant after the gap', () => {
+ // Samoa moved across the date line after December 29, 2011: December 30
+ // never happened in Pacific/Apia, so it resolves to 00:00 on December 31
+ // (+14), the next date.
+ const instant = plainDateToInstant(
+ {year: 2011, month: 12, day: 30},
+ 'Pacific/Apia',
+ );
+ expect(instant).toBe(Date.UTC(2011, 11, 30, 10));
+ expect(plainDateFromInstant(instant, 'Pacific/Apia')).toEqual({
+ year: 2011,
+ month: 12,
+ day: 31,
+ });
+ });
+
+ it('moves a wall time in a 30-minute gap forward by 30 minutes', () => {
+ // Lord Howe Island jumps from 2:00 to 2:30 AM on October 4, 2026, from
+ // +10:30 to +11: 2:15 AM does not happen and reads as 2:45 AM.
+ expect(
+ plainDateToInstant(
+ {year: 2026, month: 10, day: 4},
+ 'Australia/Lord_Howe',
+ 2,
+ 15,
+ ),
+ ).toBe(Date.UTC(2026, 9, 3, 15, 45));
+ });
+
it('keeps years 1-99 instead of mapping them to 1900-1999', () => {
const date: PlainDate = {year: 1, month: 1, day: 15};
// 0001-01-01T00:00:00Z is -62135596800000
diff --git a/packages/core/src/utils/plainDate.ts b/packages/core/src/utils/plainDate.ts
index 1256d93a52..1fbb1d6f81 100644
--- a/packages/core/src/utils/plainDate.ts
+++ b/packages/core/src/utils/plainDate.ts
@@ -185,17 +185,35 @@ function getTimezoneOffsetMS(timezoneID: string, instant: number): number {
);
}
+const DAY_MS = 24 * 60 * 60 * 1000;
+
export function plainDateToInstant(
date: PlainDate,
timezoneID: string,
hour = 0,
minute = 0,
): number {
- const utcGuess = utcTime(date.year, date.month - 1, date.day, hour, minute);
- const firstOffset = getTimezoneOffsetMS(timezoneID, utcGuess);
- const firstInstant = utcGuess - firstOffset;
- const secondOffset = getTimezoneOffsetMS(timezoneID, firstInstant);
- return utcGuess - secondOffset;
+ // The wall time read as if it were UTC; subtracting an offset gives a
+ // candidate instant.
+ const wallTime = utcTime(date.year, date.month - 1, date.day, hour, minute);
+ // The offsets in effect a day either side cover any transition that can make
+ // this wall time skipped or repeated.
+ const offsetBefore = getTimezoneOffsetMS(timezoneID, wallTime - DAY_MS);
+ const offsetAfter = getTimezoneOffsetMS(timezoneID, wallTime + DAY_MS);
+ // AST-067 (Temporal's "compatible" disambiguation): a wall time that happens
+ // twice resolves to its earlier occurrence, and one that never happens is
+ // read in the offset before the transition, which moves it forward by the
+ // length of the gap.
+ const candidates = [offsetBefore, offsetAfter]
+ .map(offset => wallTime - offset)
+ .filter(
+ (instant, index) =>
+ getTimezoneOffsetMS(timezoneID, instant) ===
+ (index === 0 ? offsetBefore : offsetAfter),
+ );
+ return candidates.length > 0
+ ? Math.min(...candidates)
+ : wallTime - offsetBefore;
}
export function plainDateFromInstant(
diff --git a/packages/lab/src/Schedule/Schedule.test.tsx b/packages/lab/src/Schedule/Schedule.test.tsx
index 0593316785..b30c62d78e 100644
--- a/packages/lab/src/Schedule/Schedule.test.tsx
+++ b/packages/lab/src/Schedule/Schedule.test.tsx
@@ -634,6 +634,103 @@ describe('Schedule', () => {
});
});
+describe('Schedule across a midnight that daylight saving skips', () => {
+ // Both zones spring forward at local midnight: the day starts at 01:00.
+ const cases = [
+ {
+ timezoneID: 'America/Santiago',
+ date: Date.UTC(2026, 8, 8, 15),
+ week: [
+ 'Sunday, September 6, 2026',
+ 'Monday, September 7, 2026',
+ 'Tuesday, September 8, 2026',
+ 'Wednesday, September 9, 2026',
+ 'Thursday, September 10, 2026',
+ 'Friday, September 11, 2026',
+ 'Saturday, September 12, 2026',
+ ],
+ },
+ {
+ timezoneID: 'America/Havana',
+ date: Date.UTC(2026, 2, 10, 15),
+ week: [
+ 'Sunday, March 8, 2026',
+ 'Monday, March 9, 2026',
+ 'Tuesday, March 10, 2026',
+ 'Wednesday, March 11, 2026',
+ 'Thursday, March 12, 2026',
+ 'Friday, March 13, 2026',
+ 'Saturday, March 14, 2026',
+ ],
+ },
+ ];
+ const renderPopover = () => null;
+ const dayGroups = () =>
+ screen
+ .getAllByRole('group')
+ .map(group => group.getAttribute('aria-label') ?? '')
+ .filter(name => /, \d{4}$/u.test(name));
+
+ it.each(cases)(
+ 'keeps seven days in the week and one in the day view in $timezoneID',
+ ({timezoneID, date, week}) => {
+ const {unmount} = render(
+ <Schedule
+ view={createScheduleWeeklyView({renderPopover})}
+ events={[]}
+ date={date}
+ timezoneID={timezoneID}
+ />,
+ );
+ expect(dayGroups()).toEqual(week);
+ unmount();
+ render(
+ <Schedule
+ view={createScheduleDayView({renderPopover})}
+ events={[]}
+ date={date - 2 * 24 * 60 * 60 * 1000}
+ timezoneID={timezoneID}
+ />,
+ );
+ expect(dayGroups()).toEqual([week[0]]);
+ },
+ );
+
+ it('keeps seven days in the week and one in the day view that end at the skipped midnight', () => {
+ // Santiago's week of Sunday, August 30, 2026 ends on Saturday, September 5;
+ // its end is the start of September 6, a midnight that never happens.
+ const timezoneID = 'America/Santiago';
+ const date = Date.UTC(2026, 8, 5, 15);
+ const {unmount} = render(
+ <Schedule
+ view={createScheduleWeeklyView({renderPopover})}
+ events={[]}
+ date={date}
+ timezoneID={timezoneID}
+ />,
+ );
+ expect(dayGroups()).toEqual([
+ 'Sunday, August 30, 2026',
+ 'Monday, August 31, 2026',
+ 'Tuesday, September 1, 2026',
+ 'Wednesday, September 2, 2026',
+ 'Thursday, September 3, 2026',
+ 'Friday, September 4, 2026',
+ 'Saturday, September 5, 2026',
+ ]);
+ unmount();
+ render(
+ <Schedule
+ view={createScheduleDayView({renderPopover})}
+ events={[]}
+ date={date}
+ timezoneID={timezoneID}
+ />,
+ );
+ expect(dayGroups()).toEqual(['Saturday, September 5, 2026']);
+ });
+});
+
describe('sortEvents', () => {
it('sorts mixed all-day and instant events by start time', () => {
const sortedEvents = sortEvents(
diff --git a/packages/lab/src/Schedule/__tests__/ScheduleTimeGridSkippedMidnight.a11y.chromium.spec.ts b/packages/lab/src/Schedule/__tests__/ScheduleTimeGridSkippedMidnight.a11y.chromium.spec.ts
new file mode 100644
index 0000000000..c1d1e06f67
--- /dev/null
+++ b/packages/lab/src/Schedule/__tests__/ScheduleTimeGridSkippedMidnight.a11y.chromium.spec.ts
@@ -0,0 +1,113 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ScheduleTimeGridSkippedMidnight.a11y.chromium.spec.ts
+ * @input The built Lab/Schedule SkippedMidnight story in real Chromium
+ * @output Receipted evidence that a week and a day whose midnight daylight
+ * saving skips keep their own dates: seven day columns in the week, one in
+ * the day view, in America/Santiago and America/Havana
+ * @position Browser binding for `component:Schedule` FR8 (no event or day is
+ * dropped) across a skipped midnight
+ */
+
+import {expect, test, type Page} from '@playwright/test';
+import {
+ finishEvidence,
+ record,
+ startEvidence,
+ storyUrl,
+ WIDE,
+ type Evidence,
+} from './timeGridProbe';
+
+const STORY = 'lab-schedule--skipped-midnight';
+const ZONES = [
+ {
+ timezoneID: 'America/Santiago',
+ week: [
+ 'Sunday, September 6, 2026',
+ 'Monday, September 7, 2026',
+ 'Tuesday, September 8, 2026',
+ 'Wednesday, September 9, 2026',
+ 'Thursday, September 10, 2026',
+ 'Friday, September 11, 2026',
+ 'Saturday, September 12, 2026',
+ ],
+ },
+ {
+ timezoneID: 'America/Havana',
+ week: [
+ 'Sunday, March 8, 2026',
+ 'Monday, March 9, 2026',
+ 'Tuesday, March 10, 2026',
+ 'Wednesday, March 11, 2026',
+ 'Thursday, March 12, 2026',
+ 'Friday, March 13, 2026',
+ 'Saturday, March 14, 2026',
+ ],
+ },
+] as const;
+
+let evidence: Evidence;
+
+/** The story holds four schedules, so wait for each zone's pair. */
+async function openSkippedMidnight(page: Page, globals?: string) {
+ await page.setViewportSize(WIDE);
+ await page.goto(storyUrl(evidence, STORY, globals), {waitUntil: 'load'});
+ await expect(page.locator('.astryx-schedule')).toHaveCount(4);
+ await page.evaluate(() => document.fonts.ready);
+ await page.waitForTimeout(100);
+}
+test.beforeAll(async () => {
+ evidence = await startEvidence();
+});
+test.afterAll(async () => {
+ await finishEvidence(evidence, 'skipped-midnight');
+});
+
+for (const [direction, globals] of [
+ ['ltr', undefined],
+ ['rtl', 'direction:rtl'],
+] as const) {
+ test(`a skipped midnight keeps seven days in the week and one in the day view (${direction})`, async ({
+ page,
+ }) => {
+ await openSkippedMidnight(page, globals);
+ const readings = [];
+ for (const zone of ZONES) {
+ const section = page.getByRole('region', {name: zone.timezoneID});
+ const grids = section.getByRole('grid', {name: 'Schedule time grid'});
+ await expect(grids).toHaveCount(2);
+ const days = async (index: number) =>
+ (
+ await grids
+ .nth(index)
+ .getByRole('columnheader')
+ .evaluateAll(headers =>
+ headers.map(header => header.textContent?.trim() ?? ''),
+ )
+ ).filter(name => /, \d{4}$/u.test(name));
+ const week = await days(0);
+ const day = await days(1);
+ // The first hour's event paints in the first day's column.
+ const firstHour = await section
+ .getByText('First hour', {exact: true})
+ .first()
+ .isVisible();
+ readings.push({zone: zone.timezoneID, week, day, firstHour});
+ expect(week, `${zone.timezoneID} week`).toEqual([...zone.week]);
+ expect(day, `${zone.timezoneID} day`).toEqual([zone.week[0]]);
+ expect(firstHour, `${zone.timezoneID} first hour painted`).toBe(true);
+ }
+ await record(
+ evidence,
+ page,
+ `skipped-midnight-${direction}`,
+ STORY,
+ direction,
+ {
+ readings,
+ },
+ );
+ });
+}