From a9ff3dacd5d6aa4facbb352848e5f5f28adf1d7f Mon Sep 17 00:00:00 2001
From: interacsean <seanhasselback@gmail.com>
Date: Thu, 8 Oct 2026 16:40:13 +1100
Subject: [PATCH] fix(date-field): show PM times correctly in 12-hour display

fieldsFromValue copied the 0-23 hour straight into the segments and never
set dayPeriod, while composeValue reads 12-hour segments as
`hour % 12 + (pm ? 12 : 0)`. 18:00 showed as "18:00 AM" and any edit
saved it as 06:xx. Split the hour into 1-12 + dayPeriod in 12-hour mode,
and re-encode stored segments when the hour cycle flips on a mounted
field (hourCycle prop or locale change).

Refs tailor-inc/platform-planning#2039

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/date-field-12-hour-pm.md           |   5 +
 docs-manifest.json                            |   6 +-
 .../components/date-picker.docs.outline.md    |  44 ++---
 docs/components/date-picker.md                |  44 ++---
 .../components/date-field/date-field.test.tsx | 154 ++++++++++++++++++
 .../src/components/date-field/date-field.tsx  |   1 +
 .../date-field/date-range-picker.test.tsx     |  26 ++-
 .../date-field/date-range-picker.tsx          |   1 +
 .../date-field/use-date-field-state.ts        |  48 ++++--
 9 files changed, 270 insertions(+), 59 deletions(-)
 create mode 100644 .changeset/date-field-12-hour-pm.md

diff --git a/.changeset/date-field-12-hour-pm.md b/.changeset/date-field-12-hour-pm.md
new file mode 100644
index 000000000..a47e84a2e
--- /dev/null
+++ b/.changeset/date-field-12-hour-pm.md
@@ -0,0 +1,5 @@
+---
+"@tailor-platform/app-shell": patch
+---
+
+Fix 12-hour time display in `DateField`, `DatePicker` and `DateRangePicker`. With `granularity` set to `hour`, `minute` or `second` and a 12-hour cycle (`hourCycle={12}`, or a 12-hour locale such as `en-US`), afternoon values showed as e.g. "18:00 AM", and editing any segment saved them 12 hours early (06:xx). PM values now show as "06:00 PM", midnight and noon as 12 AM / 12 PM, and edits keep the correct hour. Changing `hourCycle` (or a locale change that flips the default cycle) on a mounted field now re-encodes the time segments instead of misreading them. Refs tailor-inc/platform-planning#2039.
diff --git a/docs-manifest.json b/docs-manifest.json
index fca243a66..4466b07c4 100644
--- a/docs-manifest.json
+++ b/docs-manifest.json
@@ -468,9 +468,9 @@
       ],
       "hashes": {
         "typeSurface": "6b07d4169fa991df",
-        "outline": "85b4b50ff4dbc265",
+        "outline": "caab56e5766bdb72",
         "snapshot": null,
-        "outputMd": "33902be121ff69db",
+        "outputMd": "f39002ad79625dc4",
         "examples": null
       }
     },
@@ -1674,7 +1674,7 @@
     "packages/core/skills/app-shell-patterns/references/components/command-palette.md": "7e5bc675a593791a",
     "packages/core/skills/app-shell-patterns/references/components/csv-importer.md": "53d3c795ca21b9dc",
     "packages/core/skills/app-shell-patterns/references/components/data-table.md": "dd2da884d7550daf",
-    "packages/core/skills/app-shell-patterns/references/components/date-picker.md": "33902be121ff69db",
+    "packages/core/skills/app-shell-patterns/references/components/date-picker.md": "f39002ad79625dc4",
     "packages/core/skills/app-shell-patterns/references/components/default-header.md": "375e55f4b12fa2be",
     "packages/core/skills/app-shell-patterns/references/components/default-sidebar.md": "3422388a0cc78571",
     "packages/core/skills/app-shell-patterns/references/components/description-card.md": "a347fd1f4ccd433e",
diff --git a/docs-src/components/date-picker.docs.outline.md b/docs-src/components/date-picker.docs.outline.md
index a1c219eda..81d3a8219 100644
--- a/docs-src/components/date-picker.docs.outline.md
+++ b/docs-src/components/date-picker.docs.outline.md
@@ -193,26 +193,28 @@ Locale and timezone come from AppShell automatically. Override per field with `l
 
 ### DateFieldProps
 
-| Prop                             | Type                                                          | Description                                                |
-| -------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------- |
-| `value` / `defaultValue`         | `DateValue \| null`                                           | Controlled / uncontrolled value                            |
-| `onChange`                       | `(v: DateValue \| null) => void`                              | Fires when the value changes                               |
-| `onBlur`                         | `() => void`                                                  | Fires when focus leaves the whole segmented control        |
-| `minValue` / `maxValue`          | `DateValue`                                                   | Inclusive date range bounds                                |
-| `isDateUnavailable`              | `(date: DateValue) => boolean`                                | Marks specific dates unavailable                           |
-| `isDisabled`                     | `boolean`                                                     | Disables interaction and form submission                   |
-| `isReadOnly`                     | `boolean`                                                     | Allows focus/navigation without editing                    |
-| `isRequired`                     | `boolean`                                                     | Marks the control required                                 |
-| `isInvalid`                      | `boolean`                                                     | Adds invalid styling / `aria-invalid` to the segmented UI  |
-| `placeholderValue`               | `DateValue`                                                   | Seeds unset segments                                       |
-| `autoFocus`                      | `boolean`                                                     | Focus the first segment on mount                           |
-| `locale`                         | `string`                                                      | BCP-47 locale override                                     |
-| `name`                           | `string`                                                      | Emits a form value through the proxy input                 |
-| `id`                             | `string`                                                      | Proxy input id (use with external `<label htmlFor>`).      |
-| `firstDayOfWeek`                 | `"sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat"` | Override the locale week start used by `w` / `k` shortcuts |
-| `aria-label` / `aria-labelledby` | `string`                                                      | Accessible name                                            |
-| `aria-describedby`               | `string`                                                      | IDs of description / error elements                        |
-| `className`                      | `string`                                                      | Root element class                                         |
+| Prop                             | Type                                                          | Description                                                  |
+| -------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
+| `value` / `defaultValue`         | `DateValue \| null`                                           | Controlled / uncontrolled value                              |
+| `onChange`                       | `(v: DateValue \| null) => void`                              | Fires when the value changes                                 |
+| `onBlur`                         | `() => void`                                                  | Fires when focus leaves the whole segmented control          |
+| `minValue` / `maxValue`          | `DateValue`                                                   | Inclusive date range bounds                                  |
+| `isDateUnavailable`              | `(date: DateValue) => boolean`                                | Marks specific dates unavailable                             |
+| `isDisabled`                     | `boolean`                                                     | Disables interaction and form submission                     |
+| `isReadOnly`                     | `boolean`                                                     | Allows focus/navigation without editing                      |
+| `isRequired`                     | `boolean`                                                     | Marks the control required                                   |
+| `isInvalid`                      | `boolean`                                                     | Adds invalid styling / `aria-invalid` to the segmented UI    |
+| `placeholderValue`               | `DateValue`                                                   | Seeds unset segments                                         |
+| `granularity`                    | `"day" \| "hour" \| "minute" \| "second"`                     | Smallest editable unit; time granularities add time segments |
+| `hourCycle`                      | `12 \| 24`                                                    | Force 12- or 24-hour time; defaults to the locale            |
+| `autoFocus`                      | `boolean`                                                     | Focus the first segment on mount                             |
+| `locale`                         | `string`                                                      | BCP-47 locale override                                       |
+| `name`                           | `string`                                                      | Emits a form value through the proxy input                   |
+| `id`                             | `string`                                                      | Proxy input id (use with external `<label htmlFor>`).        |
+| `firstDayOfWeek`                 | `"sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat"` | Override the locale week start used by `w` / `k` shortcuts   |
+| `aria-label` / `aria-labelledby` | `string`                                                      | Accessible name                                              |
+| `aria-describedby`               | `string`                                                      | IDs of description / error elements                          |
+| `className`                      | `string`                                                      | Root element class                                           |
 
 ### DatePickerProps
 
@@ -229,7 +231,7 @@ See the calendar docs in-code: controlled/uncontrolled value, min/max, unavailab
 
 ### DateRangePickerProps
 
-The `DatePickerProps` surface (labeling, `isInvalid`, `min/maxValue`, `isDateUnavailable`, `granularity`, `firstDayOfWeek`, `timeZone`, `locale`, `autoFocus`, `isDisabled/ReadOnly/Required`), with the range-specific differences:
+The `DatePickerProps` surface (labeling, `isInvalid`, `min/maxValue`, `isDateUnavailable`, `granularity`, `hourCycle`, `firstDayOfWeek`, `timeZone`, `locale`, `autoFocus`, `isDisabled/ReadOnly/Required`), with the range-specific differences:
 
 | Prop                     | Type                             | Description                                                                     |
 | ------------------------ | -------------------------------- | ------------------------------------------------------------------------------- |
diff --git a/docs/components/date-picker.md b/docs/components/date-picker.md
index d06b2d842..9d3bcab5f 100644
--- a/docs/components/date-picker.md
+++ b/docs/components/date-picker.md
@@ -191,26 +191,28 @@ Locale and timezone come from AppShell automatically. Override per field with `l
 
 ### DateFieldProps
 
-| Prop                             | Type                                                          | Description                                                |
-| -------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------- |
-| `value` / `defaultValue`         | `DateValue \| null`                                           | Controlled / uncontrolled value                            |
-| `onChange`                       | `(v: DateValue \| null) => void`                              | Fires when the value changes                               |
-| `onBlur`                         | `() => void`                                                  | Fires when focus leaves the whole segmented control        |
-| `minValue` / `maxValue`          | `DateValue`                                                   | Inclusive date range bounds                                |
-| `isDateUnavailable`              | `(date: DateValue) => boolean`                                | Marks specific dates unavailable                           |
-| `isDisabled`                     | `boolean`                                                     | Disables interaction and form submission                   |
-| `isReadOnly`                     | `boolean`                                                     | Allows focus/navigation without editing                    |
-| `isRequired`                     | `boolean`                                                     | Marks the control required                                 |
-| `isInvalid`                      | `boolean`                                                     | Adds invalid styling / `aria-invalid` to the segmented UI  |
-| `placeholderValue`               | `DateValue`                                                   | Seeds unset segments                                       |
-| `autoFocus`                      | `boolean`                                                     | Focus the first segment on mount                           |
-| `locale`                         | `string`                                                      | BCP-47 locale override                                     |
-| `name`                           | `string`                                                      | Emits a form value through the proxy input                 |
-| `id`                             | `string`                                                      | Proxy input id (use with external `<label htmlFor>`).      |
-| `firstDayOfWeek`                 | `"sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat"` | Override the locale week start used by `w` / `k` shortcuts |
-| `aria-label` / `aria-labelledby` | `string`                                                      | Accessible name                                            |
-| `aria-describedby`               | `string`                                                      | IDs of description / error elements                        |
-| `className`                      | `string`                                                      | Root element class                                         |
+| Prop                             | Type                                                          | Description                                                  |
+| -------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
+| `value` / `defaultValue`         | `DateValue \| null`                                           | Controlled / uncontrolled value                              |
+| `onChange`                       | `(v: DateValue \| null) => void`                              | Fires when the value changes                                 |
+| `onBlur`                         | `() => void`                                                  | Fires when focus leaves the whole segmented control          |
+| `minValue` / `maxValue`          | `DateValue`                                                   | Inclusive date range bounds                                  |
+| `isDateUnavailable`              | `(date: DateValue) => boolean`                                | Marks specific dates unavailable                             |
+| `isDisabled`                     | `boolean`                                                     | Disables interaction and form submission                     |
+| `isReadOnly`                     | `boolean`                                                     | Allows focus/navigation without editing                      |
+| `isRequired`                     | `boolean`                                                     | Marks the control required                                   |
+| `isInvalid`                      | `boolean`                                                     | Adds invalid styling / `aria-invalid` to the segmented UI    |
+| `placeholderValue`               | `DateValue`                                                   | Seeds unset segments                                         |
+| `granularity`                    | `"day" \| "hour" \| "minute" \| "second"`                     | Smallest editable unit; time granularities add time segments |
+| `hourCycle`                      | `12 \| 24`                                                    | Force 12- or 24-hour time; defaults to the locale            |
+| `autoFocus`                      | `boolean`                                                     | Focus the first segment on mount                             |
+| `locale`                         | `string`                                                      | BCP-47 locale override                                       |
+| `name`                           | `string`                                                      | Emits a form value through the proxy input                   |
+| `id`                             | `string`                                                      | Proxy input id (use with external `<label htmlFor>`).        |
+| `firstDayOfWeek`                 | `"sun" \| "mon" \| "tue" \| "wed" \| "thu" \| "fri" \| "sat"` | Override the locale week start used by `w` / `k` shortcuts   |
+| `aria-label` / `aria-labelledby` | `string`                                                      | Accessible name                                              |
+| `aria-describedby`               | `string`                                                      | IDs of description / error elements                          |
+| `className`                      | `string`                                                      | Root element class                                           |
 
 ### DatePickerProps
 
@@ -227,7 +229,7 @@ See the calendar docs in-code: controlled/uncontrolled value, min/max, unavailab
 
 ### DateRangePickerProps
 
-The `DatePickerProps` surface (labeling, `isInvalid`, `min/maxValue`, `isDateUnavailable`, `granularity`, `firstDayOfWeek`, `timeZone`, `locale`, `autoFocus`, `isDisabled/ReadOnly/Required`), with the range-specific differences:
+The `DatePickerProps` surface (labeling, `isInvalid`, `min/maxValue`, `isDateUnavailable`, `granularity`, `hourCycle`, `firstDayOfWeek`, `timeZone`, `locale`, `autoFocus`, `isDisabled/ReadOnly/Required`), with the range-specific differences:
 
 | Prop                     | Type                             | Description                                                                     |
 | ------------------------ | -------------------------------- | ------------------------------------------------------------------------------- |
diff --git a/packages/core/src/components/date-field/date-field.test.tsx b/packages/core/src/components/date-field/date-field.test.tsx
index 7f82f8c1e..dbc87c2c2 100644
--- a/packages/core/src/components/date-field/date-field.test.tsx
+++ b/packages/core/src/components/date-field/date-field.test.tsx
@@ -5,6 +5,7 @@ import userEvent from "@testing-library/user-event";
 import {
   CalendarDate,
   parseDate,
+  parseZonedDateTime,
   today,
   getLocalTimeZone,
   startOfWeek,
@@ -1360,3 +1361,156 @@ describe("RHF integration", () => {
     });
   });
 });
+
+describe("12-hour time display", () => {
+  const TZ = "Asia/Tokyo";
+  const zoned = (iso: string) => parseZonedDateTime(`${iso}[${TZ}]`);
+  const segText = (name: string) =>
+    screen.getByRole("spinbutton", { name }).getAttribute("aria-valuetext");
+
+  it("shows a PM value as 06 PM, not 18 AM", () => {
+    render(
+      <DatePicker
+        aria-label="Deadline"
+        granularity="minute"
+        hourCycle={12}
+        locale="en-US"
+        timeZone={TZ}
+        defaultValue={zoned("2026-10-12T18:00")}
+      />,
+    );
+    expect(segText("hour")).toBe("06");
+    expect(segText("AM/PM")).toBe("PM");
+  });
+
+  it.each([
+    ["2026-10-12T00:30", "12", "AM"],
+    ["2026-10-12T12:30", "12", "PM"],
+  ])("shows %s as %s %s", (iso, hour, period) => {
+    render(
+      <DatePicker
+        aria-label="Deadline"
+        granularity="minute"
+        hourCycle={12}
+        locale="en-US"
+        timeZone={TZ}
+        defaultValue={zoned(iso)}
+      />,
+    );
+    expect(segText("hour")).toBe(hour);
+    expect(segText("AM/PM")).toBe(period);
+  });
+
+  it.each(["2026-10-12T18:00", "2026-10-12T00:00", "2026-10-12T12:00"])(
+    "keeps the hour of %s when the minute is edited",
+    async (iso) => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      render(
+        <DatePicker
+          aria-label="Deadline"
+          granularity="minute"
+          hourCycle={12}
+          locale="en-US"
+          timeZone={TZ}
+          defaultValue={zoned(iso)}
+          onChange={onChange}
+        />,
+      );
+      await user.click(screen.getByRole("spinbutton", { name: "minute" }));
+      await user.keyboard("{ArrowUp}");
+      expect(onChange.mock.lastCall?.[0]?.toString()).toBe(
+        zoned(iso).add({ minutes: 1 }).toString(),
+      );
+    },
+  );
+
+  it("shows an externally updated PM value correctly", () => {
+    const { rerender } = render(
+      <DatePicker
+        aria-label="Deadline"
+        granularity="minute"
+        hourCycle={12}
+        locale="en-US"
+        timeZone={TZ}
+        value={zoned("2026-10-12T09:00")}
+      />,
+    );
+    expect(segText("AM/PM")).toBe("AM");
+    rerender(
+      <DatePicker
+        aria-label="Deadline"
+        granularity="minute"
+        hourCycle={12}
+        locale="en-US"
+        timeZone={TZ}
+        value={zoned("2026-10-12T21:15")}
+      />,
+    );
+    expect(segText("hour")).toBe("09");
+    expect(segText("AM/PM")).toBe("PM");
+  });
+
+  describe("when hourCycle changes on a mounted field", () => {
+    const props = (onChange = vi.fn()) => ({
+      "aria-label": "Deadline",
+      granularity: "minute" as const,
+      locale: "en-US",
+      timeZone: TZ,
+      defaultValue: zoned("2026-10-12T18:00"),
+      onChange,
+    });
+
+    it("re-encodes 12 → 24 and keeps the value", async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      const { rerender } = render(<DatePicker {...props(onChange)} hourCycle={12} />);
+      rerender(<DatePicker {...props(onChange)} hourCycle={24} />);
+      expect(segText("hour")).toBe("18");
+      expect(screen.queryByRole("spinbutton", { name: "AM/PM" })).toBeNull();
+      expect(onChange).not.toHaveBeenCalled();
+      await user.click(screen.getByRole("spinbutton", { name: "minute" }));
+      await user.keyboard("{ArrowUp}");
+      expect(onChange.mock.lastCall?.[0]?.toString()).toBe(zoned("2026-10-12T18:01").toString());
+    });
+
+    it("re-encodes 24 → 12 and keeps the value", async () => {
+      const user = userEvent.setup();
+      const onChange = vi.fn();
+      const { rerender } = render(<DatePicker {...props(onChange)} hourCycle={24} />);
+      rerender(<DatePicker {...props(onChange)} hourCycle={12} />);
+      expect(segText("hour")).toBe("06");
+      expect(segText("AM/PM")).toBe("PM");
+      expect(onChange).not.toHaveBeenCalled();
+      await user.click(screen.getByRole("spinbutton", { name: "minute" }));
+      await user.keyboard("{ArrowUp}");
+      expect(onChange.mock.lastCall?.[0]?.toString()).toBe(zoned("2026-10-12T18:01").toString());
+    });
+
+    it("re-encodes a half-typed hour", async () => {
+      const user = userEvent.setup();
+      const base = { "aria-label": "Deadline", granularity: "minute" as const, locale: "en-US" };
+      const { rerender } = render(<DateField {...base} hourCycle={24} />);
+      await user.click(screen.getByRole("spinbutton", { name: "hour" }));
+      await user.keyboard("21");
+      rerender(<DateField {...base} hourCycle={12} />);
+      expect(segText("hour")).toBe("09");
+      expect(segText("AM/PM")).toBe("PM");
+    });
+  });
+
+  it("leaves 24-hour display unchanged", () => {
+    render(
+      <DatePicker
+        aria-label="Deadline"
+        granularity="minute"
+        hourCycle={24}
+        locale="en-US"
+        timeZone={TZ}
+        defaultValue={zoned("2026-10-12T18:00")}
+      />,
+    );
+    expect(segText("hour")).toBe("18");
+    expect(screen.queryByRole("spinbutton", { name: "AM/PM" })).toBeNull();
+  });
+});
diff --git a/packages/core/src/components/date-field/date-field.tsx b/packages/core/src/components/date-field/date-field.tsx
index 660e53144..abad4738a 100644
--- a/packages/core/src/components/date-field/date-field.tsx
+++ b/packages/core/src/components/date-field/date-field.tsx
@@ -52,6 +52,7 @@ interface DateControlProps<T extends DateValue> {
   isRequired?: boolean;
   isInvalid?: boolean;
   autoFocus?: boolean;
+  /** 12- or 24-hour time; defaults to the locale. */
   hourCycle?: HourCycle;
   placeholderValue?: DateValue;
   firstDayOfWeek?: FirstDayOfWeek;
diff --git a/packages/core/src/components/date-field/date-range-picker.test.tsx b/packages/core/src/components/date-field/date-range-picker.test.tsx
index b46310882..c499456d9 100644
--- a/packages/core/src/components/date-field/date-range-picker.test.tsx
+++ b/packages/core/src/components/date-field/date-range-picker.test.tsx
@@ -1,7 +1,7 @@
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { cleanup, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
-import { CalendarDate, parseDate, isSameDay } from "@internationalized/date";
+import { CalendarDate, parseDate, parseZonedDateTime, isSameDay } from "@internationalized/date";
 import { renderRHFForm } from "../../../tests/rhf-test-utils";
 import { createAppShellWrapper } from "../../../tests/test-utils";
 import { Field } from "../field";
@@ -493,3 +493,27 @@ describe("DateRangePicker popover", () => {
     expect(isSameDay(range.end, d("2025-03-12"))).toBe(true);
   });
 });
+
+describe("12-hour time display", () => {
+  it("shows PM ends as PM, not as 24-hour AM", () => {
+    const tz = "Asia/Tokyo";
+    render(
+      <DateRangePicker
+        aria-label="Shift"
+        granularity="minute"
+        hourCycle={12}
+        locale="en-US"
+        timeZone={tz}
+        defaultValue={{
+          start: parseZonedDateTime(`2026-10-12T13:00[${tz}]`),
+          end: parseZonedDateTime(`2026-10-12T18:30[${tz}]`),
+        }}
+      />,
+    );
+    const text = (field: Field, name: string) => seg(field, name).getAttribute("aria-valuetext");
+    expect(text("start date", "hour")).toBe("01");
+    expect(text("start date", "AM/PM")).toBe("PM");
+    expect(text("end date", "hour")).toBe("06");
+    expect(text("end date", "AM/PM")).toBe("PM");
+  });
+});
diff --git a/packages/core/src/components/date-field/date-range-picker.tsx b/packages/core/src/components/date-field/date-range-picker.tsx
index 3daf965a1..06f2cd404 100644
--- a/packages/core/src/components/date-field/date-range-picker.tsx
+++ b/packages/core/src/components/date-field/date-range-picker.tsx
@@ -62,6 +62,7 @@ export type DateRangePickerProps<T extends DateValue = DateValue> = {
   isRequired?: boolean;
   isInvalid?: boolean;
   autoFocus?: boolean;
+  /** 12- or 24-hour time; defaults to the locale. */
   hourCycle?: HourCycle;
   placeholderValue?: DateValue;
   firstDayOfWeek?: FirstDayOfWeek;
diff --git a/packages/core/src/components/date-field/use-date-field-state.ts b/packages/core/src/components/date-field/use-date-field-state.ts
index dd1c28eb6..cf102d029 100644
--- a/packages/core/src/components/date-field/use-date-field-state.ts
+++ b/packages/core/src/components/date-field/use-date-field-state.ts
@@ -173,7 +173,11 @@ function completeCalendarDate(f: Fields): CalendarDate | null {
   return new CalendarDate(f.year, f.month, f.day);
 }
 
-function fieldsFromValue(v: DateValue | null | undefined): Fields {
+/**
+ * Split a value into segment fields. In 12-hour mode the hour is stored as
+ * 1–12 plus `dayPeriod`, the inverse of the conversion in `composeValue`.
+ */
+function fieldsFromValue(v: DateValue | null | undefined, is12: boolean): Fields {
   if (!v) return {};
   const f: Fields = {};
   if ("year" in v) {
@@ -182,14 +186,27 @@ function fieldsFromValue(v: DateValue | null | undefined): Fields {
     f.day = v.day;
   }
   if ("hour" in v) {
-    f.hour = v.hour;
+    f.hour = is12 ? v.hour % 12 || 12 : v.hour;
     f.minute = v.minute;
     f.second = v.second;
+    if (is12) f.dayPeriod = v.hour >= 12 ? 1 : 0;
   }
   return f;
 }
 
-function use12HourCycle(locale: string, hourCycle?: HourCycle): boolean {
+/**
+ * Re-encode the hour of (possibly partial) fields for a new hour cycle. An
+ * unset `dayPeriod` reads as AM, matching `composeValue`, so the composed
+ * value is unchanged.
+ */
+function convertHourCycle(f: Fields, is12: boolean): Fields {
+  const { dayPeriod, ...rest } = f;
+  if (f.hour == null) return rest;
+  if (is12) return { ...rest, hour: f.hour % 12 || 12, dayPeriod: f.hour >= 12 ? 1 : 0 };
+  return { ...rest, hour: (f.hour % 12) + (dayPeriod === 1 ? 12 : 0) };
+}
+
+function resolveIs12HourCycle(locale: string, hourCycle?: HourCycle): boolean {
   if (hourCycle === 12) return true;
   if (hourCycle === 24) return false;
   // Derive from the locale's resolved hour cycle.
@@ -272,7 +289,7 @@ export function useDateFieldState(options: DateFieldStateOptions) {
 
   const isControlled = controlledValue !== undefined;
   const hasTime = granularity !== "day";
-  const is12 = use12HourCycle(locale, hourCycle);
+  const is12 = useMemo(() => resolveIs12HourCycle(locale, hourCycle), [locale, hourCycle]);
 
   // The editable segment order, before locale reordering.
   const editableTypes = useMemo<EditableSegmentType[]>(() => {
@@ -286,8 +303,17 @@ export function useDateFieldState(options: DateFieldStateOptions) {
   // segments) survive the round-trip through `onChange`. A `controlled` value
   // that changes *externally* is synced back in via the effect below.
   const [internalFields, setInternalFields] = useState<Fields>(() =>
-    fieldsFromValue(controlledValue ?? defaultValue),
+    fieldsFromValue(controlledValue ?? defaultValue, is12),
   );
+
+  // `fields` stores the hour in the current cycle's encoding. When the cycle
+  // flips (`hourCycle` or `locale` changed), re-encode during render so no
+  // commit ever reads the old encoding the new way.
+  const [fieldsIs12, setFieldsIs12] = useState(is12);
+  if (fieldsIs12 !== is12) {
+    setFieldsIs12(is12);
+    setInternalFields((f) => convertHourCycle(f, is12));
+  }
   const fields = internalFields;
 
   const lastEmitted = useRef<DateValue | null>(controlledValue ?? defaultValue ?? null);
@@ -303,7 +329,7 @@ export function useDateFieldState(options: DateFieldStateOptions) {
 
   // Anchor as a plain field record — used to seed increments and to populate
   // unfilled segments for display formatting.
-  const anchorFields = useMemo<Fields>(() => fieldsFromValue(anchor), [anchor]);
+  const anchorFields = useMemo<Fields>(() => fieldsFromValue(anchor, is12), [anchor, is12]);
 
   // ── Limits ──────────────────────────────────────────────────────────────────
   const getLimits = useCallback(
@@ -424,12 +450,12 @@ export function useDateFieldState(options: DateFieldStateOptions) {
     const same =
       (cv == null && le == null) || (cv != null && le != null && cv.compare(le as never) === 0);
     if (!same) {
-      const nextFields = fieldsFromValue(cv);
+      const nextFields = fieldsFromValue(cv, is12);
       lastEmitted.current = cv;
       setInternalFields(nextFields);
       onStateChange?.(buildStateChange(nextFields, "external"));
     }
-  }, [buildStateChange, controlledValue, isControlled, onStateChange]);
+  }, [buildStateChange, controlledValue, isControlled, is12, onStateChange]);
 
   // ── Mutations ───────────────────────────────────────────────────────────────
   const cycle = useCallback(
@@ -440,11 +466,7 @@ export function useDateFieldState(options: DateFieldStateOptions) {
       let next: number;
       if (current == null) {
         // Start from the anchor's value for that field, or the min.
-        if (type === "dayPeriod") {
-          next = (anchorFields.hour ?? 0) >= 12 ? 1 : 0;
-        } else {
-          next = anchorFields[type] ?? min;
-        }
+        next = anchorFields[type] ?? min;
       } else {
         const span = max - min + 1;
         next = ((current - min + delta + span * 1000) % span) + min;