From be502a5856a680a821a1b5bd8266fa7599a552c9 Mon Sep 17 00:00:00 2001
From: interacsean <seanhasselback@gmail.com>
Date: Tue, 13 Oct 2026 15:37:51 +1100
Subject: [PATCH] feat(date-field): add showDayOfWeek to DateField, DatePicker
 and DateRangePicker (#1883)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Append the locale's short day of the week where the locale places it
(2025/12/19(金), Fri, 12/19/2025). Read-only and derived from the entered
date; while a date segment is mid-entry it holds the previous day of the week
so typing "25" never flashes the 2nd's. Screen readers hear the full day name
with each date segment's value.

Split out of the regional-format work (kept on
feat/date-field/1883-regional-date-format-weekday) after the team settled on
the day of the week alone.

Refs tailor-inc/platform-planning#1883

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .changeset/show-day-of-week.md                |  9 ++
 docs-manifest.json                            |  8 +-
 .../components/date-picker.docs.outline.md    | 11 ++-
 docs/components/date-picker.md                | 11 ++-
 .../src/pages/showcase/date-picker/page.tsx   | 20 ++++
 .../components/date-field/date-field.test.tsx | 93 +++++++++++++++++++
 .../src/components/date-field/date-field.tsx  |  8 ++
 .../date-field/date-input-group.tsx           | 40 +++++++-
 .../date-field/date-range-input-group.tsx     |  2 +
 .../date-field/date-range-picker.test.tsx     | 10 ++
 .../date-field/date-range-picker.tsx          |  4 +
 .../date-field/use-date-field-state.ts        | 82 ++++++++++++----
 12 files changed, 270 insertions(+), 28 deletions(-)
 create mode 100644 .changeset/show-day-of-week.md

diff --git a/.changeset/show-day-of-week.md b/.changeset/show-day-of-week.md
new file mode 100644
index 000000000..ac4c56de6
--- /dev/null
+++ b/.changeset/show-day-of-week.md
@@ -0,0 +1,9 @@
+---
+"@tailor-platform/app-shell": minor
+---
+
+Add `showDayOfWeek` to `DateField`, `DatePicker`, and `DateRangePicker`. It appends the locale's short day of the week where the locale places it (`2025/12/19(金)`, `Fri, 12/19/2025`). It is read-only and derived from the entered date. While a date segment is mid-entry it keeps showing the previous day of the week, so typing `25` never flashes the 2nd's. Screen readers hear the full day name with each date segment's value.
+
+```tsx
+<DatePicker aria-label="Closing date" showDayOfWeek />
+```
diff --git a/docs-manifest.json b/docs-manifest.json
index 06036a7e7..749f4e4b3 100644
--- a/docs-manifest.json
+++ b/docs-manifest.json
@@ -470,10 +470,10 @@
         "DateRangePickerProps"
       ],
       "hashes": {
-        "typeSurface": "6b07d4169fa991df",
-        "outline": "caab56e5766bdb72",
+        "typeSurface": "a0f5522359e8f81d",
+        "outline": "50e117ad2a0562ba",
         "snapshot": null,
-        "outputMd": "f39002ad79625dc4",
+        "outputMd": "bc69f14829004f9d",
         "examples": null
       }
     },
@@ -1694,7 +1694,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": "3e8474e4d1437c91",
-    "packages/core/skills/app-shell-patterns/references/components/date-picker.md": "f39002ad79625dc4",
+    "packages/core/skills/app-shell-patterns/references/components/date-picker.md": "bc69f14829004f9d",
     "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 81d3a8219..d6a97abd2 100644
--- a/docs-src/components/date-picker.docs.outline.md
+++ b/docs-src/components/date-picker.docs.outline.md
@@ -183,6 +183,14 @@ Locale and timezone come from AppShell automatically. Override per field with `l
 <DatePicker aria-label="Date" locale="ja-JP" />
 ```
 
+### Day of the week
+
+`showDayOfWeek` adds the locale's short day of the week where the locale places it — `2025/12/19(金)` for ja-JP, `Fri, 12/19/2025` for en-US. It is read-only and derived from the entered date: it shows a placeholder until the date is complete, and while a date segment is mid-entry it keeps the previous day of the week (muted), so typing `25` into the day never flashes the 2nd's. Screen readers hear the full day name with each date segment's value.
+
+```tsx
+<DatePicker aria-label="Closing date" showDayOfWeek />
+```
+
 ## Keyboard
 
 - **Segments:** `↑`/`↓` increment/decrement, digits type-to-fill (auto-advance), `←`/`→` move between segments, `Backspace` clears, `/` commits the current segment and advances.
@@ -209,6 +217,7 @@ Locale and timezone come from AppShell automatically. Override per field with `l
 | `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                                       |
+| `showDayOfWeek`                  | `boolean`                                                     | Show the locale's short day of the week next to the date     |
 | `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   |
@@ -231,7 +240,7 @@ See the calendar docs in-code: controlled/uncontrolled value, min/max, unavailab
 
 ### DateRangePickerProps
 
-The `DatePickerProps` surface (labeling, `isInvalid`, `min/maxValue`, `isDateUnavailable`, `granularity`, `hourCycle`, `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`, `showDayOfWeek`, `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 9d3bcab5f..481ecf2b4 100644
--- a/docs/components/date-picker.md
+++ b/docs/components/date-picker.md
@@ -181,6 +181,14 @@ Locale and timezone come from AppShell automatically. Override per field with `l
 <DatePicker aria-label="Date" locale="ja-JP" />
 ```
 
+### Day of the week
+
+`showDayOfWeek` adds the locale's short day of the week where the locale places it — `2025/12/19(金)` for ja-JP, `Fri, 12/19/2025` for en-US. It is read-only and derived from the entered date: it shows a placeholder until the date is complete, and while a date segment is mid-entry it keeps the previous day of the week (muted), so typing `25` into the day never flashes the 2nd's. Screen readers hear the full day name with each date segment's value.
+
+```tsx
+<DatePicker aria-label="Closing date" showDayOfWeek />
+```
+
 ## Keyboard
 
 - **Segments:** `↑`/`↓` increment/decrement, digits type-to-fill (auto-advance), `←`/`→` move between segments, `Backspace` clears, `/` commits the current segment and advances.
@@ -207,6 +215,7 @@ Locale and timezone come from AppShell automatically. Override per field with `l
 | `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                                       |
+| `showDayOfWeek`                  | `boolean`                                                     | Show the locale's short day of the week next to the date     |
 | `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   |
@@ -229,7 +238,7 @@ See the calendar docs in-code: controlled/uncontrolled value, min/max, unavailab
 
 ### DateRangePickerProps
 
-The `DatePickerProps` surface (labeling, `isInvalid`, `min/maxValue`, `isDateUnavailable`, `granularity`, `hourCycle`, `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`, `showDayOfWeek`, `autoFocus`, `isDisabled/ReadOnly/Required`), with the range-specific differences:
 
 | Prop                     | Type                             | Description                                                                     |
 | ------------------------ | -------------------------------- | ------------------------------------------------------------------------------- |
diff --git a/examples/vite-app/src/pages/showcase/date-picker/page.tsx b/examples/vite-app/src/pages/showcase/date-picker/page.tsx
index 25369abbb..6bca8104d 100644
--- a/examples/vite-app/src/pages/showcase/date-picker/page.tsx
+++ b/examples/vite-app/src/pages/showcase/date-picker/page.tsx
@@ -438,6 +438,26 @@ watch("period")?.start.toString(); // "2025-06-10"
             </div>
           </section>
 
+          {/* ── Day of the week ─────────────────────────────────────── */}
+          <section className="flex flex-col gap-4">
+            <h2 className="text-base font-semibold border-b pb-2">Day of the week</h2>
+            <p className="text-sm text-muted-foreground">
+              <code className="bg-muted px-1 py-0.5 rounded">showDayOfWeek</code> appends the
+              locale's short day of the week where the locale places it.
+            </p>
+            <div className="flex flex-wrap gap-6 items-start">
+              <DemoField id="date-picker-ja-dow" label="ja-JP">
+                <DatePicker locale="ja-JP" showDayOfWeek />
+              </DemoField>
+              <DemoField id="date-picker-en-dow" label="en-US">
+                <DatePicker locale="en-US" showDayOfWeek />
+              </DemoField>
+              <DemoField id="date-picker-ja-range-dow" label="ja-JP range">
+                <DateRangePicker locale="ja-JP" showDayOfWeek />
+              </DemoField>
+            </div>
+          </section>
+
           {/* ── Calendar ───────────────────────────────────────────── */}
           <section className="flex flex-col gap-4">
             <h2 className="text-base font-semibold border-b pb-2">Calendar (standalone)</h2>
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 dbc87c2c2..549d1c6e2 100644
--- a/packages/core/src/components/date-field/date-field.test.tsx
+++ b/packages/core/src/components/date-field/date-field.test.tsx
@@ -4,6 +4,7 @@ import { cleanup, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import {
   CalendarDate,
+  CalendarDateTime,
   parseDate,
   parseZonedDateTime,
   today,
@@ -835,6 +836,98 @@ describe("DateField keyboard shortcuts", () => {
   });
 });
 
+// ─── Date format + day of the week ────────────────────────────────────────────────────
+
+const groupText = () => screen.getByRole("group").textContent;
+const dayOfWeek = () => document.querySelector('[data-slot="date-segment"][data-type="dayOfWeek"]');
+
+describe("showDayOfWeek", () => {
+  const value = new CalendarDate(2025, 12, 19); // a Friday
+
+  it("shows the day of the week where the locale puts it", () => {
+    render(<DateField aria-label="Date" locale="ja-JP" showDayOfWeek defaultValue={value} />);
+    expect(groupText()).toBe("2025/12/19(金)");
+    cleanup();
+    render(<DateField aria-label="Date" locale="en-US" showDayOfWeek defaultValue={value} />);
+    expect(groupText()).toBe("Fri, 12/19/2025");
+  });
+
+  it("shows a placeholder day of the week until the date is complete", () => {
+    render(<DateField aria-label="Date" locale="en-US" showDayOfWeek />);
+    expect(dayOfWeek()?.textContent).toBe("––");
+    expect(dayOfWeek()?.hasAttribute("data-placeholder")).toBe(true);
+  });
+
+  it("holds the pre-entry day of the week while a date segment is mid-entry, so '25' never flashes the 2nd", async () => {
+    const user = userEvent.setup();
+    render(<DateField aria-label="Date" locale="en-US" showDayOfWeek defaultValue={value} />);
+
+    await user.click(screen.getByRole("spinbutton", { name: "day" }));
+    await user.keyboard("2");
+    // Still Friday (the pre-entry 19th), muted — never Tuesday (the 2nd).
+    expect(dayOfWeek()?.textContent).toBe("Fri");
+    expect(dayOfWeek()?.hasAttribute("data-placeholder")).toBe(true);
+    await user.keyboard("5");
+    expect(dayOfWeek()?.textContent).toBe("Thu"); // 25 Dec 2025
+    expect(dayOfWeek()?.hasAttribute("data-placeholder")).toBe(false);
+  });
+
+  it("never holds the day of the week while editing a time segment", async () => {
+    const user = userEvent.setup();
+    render(
+      <DateField
+        aria-label="Date"
+        locale="en-GB"
+        granularity="minute"
+        showDayOfWeek
+        defaultValue={new CalendarDateTime(2025, 12, 19, 10, 30)}
+      />,
+    );
+
+    await user.click(screen.getByRole("spinbutton", { name: "hour" }));
+    await user.keyboard("1");
+    expect(dayOfWeek()?.textContent).toBe("Fri");
+    expect(dayOfWeek()?.hasAttribute("data-placeholder")).toBe(false);
+  });
+
+  it("announces the day of the week with the date segments' values", async () => {
+    const user = userEvent.setup();
+    render(<DateField aria-label="Date" locale="en-US" showDayOfWeek defaultValue={value} />);
+    const day = screen.getByRole("spinbutton", { name: "day" });
+    expect(day.getAttribute("aria-valuetext")).toBe("19, Friday");
+    expect(dayOfWeek()?.getAttribute("aria-hidden")).toBe("true");
+
+    await user.click(day);
+    await user.keyboard("{ArrowUp}");
+    expect(day.getAttribute("aria-valuetext")).toBe("20, Saturday");
+  });
+
+  it("settles a single-digit entry when the segment loses focus", async () => {
+    const user = userEvent.setup();
+    render(<DateField aria-label="Date" locale="en-US" showDayOfWeek defaultValue={value} />);
+
+    await user.click(screen.getByRole("spinbutton", { name: "day" }));
+    await user.keyboard("2");
+    await user.tab();
+    expect(dayOfWeek()?.textContent).toBe("Tue"); // 2 Dec 2025
+  });
+
+  it("updates the day of the week immediately on arrow-key stepping", async () => {
+    const user = userEvent.setup();
+    render(<DateField aria-label="Date" locale="en-US" showDayOfWeek defaultValue={value} />);
+
+    await user.click(screen.getByRole("spinbutton", { name: "day" }));
+    await user.keyboard("{ArrowUp}");
+    expect(dayOfWeek()?.textContent).toBe("Sat");
+  });
+
+  it("keeps the day of the week out of the tab order", () => {
+    render(<DateField aria-label="Date" locale="en-US" showDayOfWeek defaultValue={value} />);
+    expect(dayOfWeek()?.hasAttribute("tabindex")).toBe(false);
+    expect(screen.getAllByRole("spinbutton")).toHaveLength(3);
+  });
+});
+
 // ─── DatePicker ───────────────────────────────────────────────────────────────
 
 describe("DatePicker", () => {
diff --git a/packages/core/src/components/date-field/date-field.tsx b/packages/core/src/components/date-field/date-field.tsx
index abad4738a..7eb719007 100644
--- a/packages/core/src/components/date-field/date-field.tsx
+++ b/packages/core/src/components/date-field/date-field.tsx
@@ -67,6 +67,8 @@ interface DateControlProps<T extends DateValue> {
   "aria-describedby"?: string;
   /** BCP-47 locale override; defaults to the AppShell formatting locale. */
   locale?: string;
+  /** Show the locale's short day of the week next to the date (e.g. `(金)`, `Fri,`). */
+  showDayOfWeek?: boolean;
 }
 
 export type DateFieldProps<T extends DateValue = DateValue> = DateControlProps<T>;
@@ -103,6 +105,7 @@ const DateField = forwardRef(function DateField<T extends DateValue = DateValue>
     placeholderValue,
     autoFocus,
     firstDayOfWeek,
+    showDayOfWeek,
     name,
     "aria-label": ariaLabel,
     "aria-labelledby": ariaLabelledby,
@@ -132,6 +135,7 @@ const DateField = forwardRef(function DateField<T extends DateValue = DateValue>
     maxValue,
     isDateUnavailable,
     firstDayOfWeek,
+    showDayOfWeek,
     isReadOnly: resolvedReadOnly,
   });
 
@@ -181,6 +185,7 @@ const DateField = forwardRef(function DateField<T extends DateValue = DateValue>
         setDayPeriod={state.setDayPeriod}
         clearSegment={state.clearSegment}
         applyShortcut={state.applyShortcut}
+        settleEntry={state.settleEntry}
         commitOnBlur={state.commitOnBlur}
         expandShortYear={state.expandShortYear}
         isDisabled={bindings.isDisabled}
@@ -229,6 +234,7 @@ const DatePicker = forwardRef(function DatePicker<T extends DateValue = DateValu
     placeholderValue,
     autoFocus,
     firstDayOfWeek,
+    showDayOfWeek,
     name,
     "aria-label": ariaLabel,
     "aria-labelledby": ariaLabelledby,
@@ -269,6 +275,7 @@ const DatePicker = forwardRef(function DatePicker<T extends DateValue = DateValu
     maxValue,
     isDateUnavailable,
     firstDayOfWeek,
+    showDayOfWeek,
     isReadOnly: resolvedReadOnly,
   });
 
@@ -384,6 +391,7 @@ const DatePicker = forwardRef(function DatePicker<T extends DateValue = DateValu
             setDayPeriod={fieldState.setDayPeriod}
             clearSegment={fieldState.clearSegment}
             applyShortcut={fieldState.applyShortcut}
+            settleEntry={fieldState.settleEntry}
             commitOnBlur={fieldState.commitOnBlur}
             expandShortYear={fieldState.expandShortYear}
             onOpenCalendar={() => handleOpenChange(true)}
diff --git a/packages/core/src/components/date-field/date-input-group.tsx b/packages/core/src/components/date-field/date-input-group.tsx
index 8c445dbec..e12c85ee1 100644
--- a/packages/core/src/components/date-field/date-input-group.tsx
+++ b/packages/core/src/components/date-field/date-input-group.tsx
@@ -47,17 +47,19 @@ export interface DateFieldRowHandle {
 
 interface DateFieldRowProps {
   segments: Segment[];
-  cycle: (type: Exclude<Segment["type"], "literal">, delta: number) => void;
+  cycle: (type: EditableSegmentType, delta: number) => void;
   setDigit: (
-    type: Exclude<Segment["type"], "literal">,
+    type: EditableSegmentType,
     digit: number,
     replace?: boolean,
     digitCount?: number,
   ) => { advance: boolean };
   setDayPeriod: (pm: boolean) => void;
-  clearSegment: (type: Exclude<Segment["type"], "literal">) => void;
+  clearSegment: (type: EditableSegmentType) => void;
   /** Apply a whole-date keyboard shortcut (today, month/year/week jumps, ±day). */
   applyShortcut: (cmd: DateShortcut) => void;
+  /** A segment lost focus, ending its typed entry (lets the day of the week settle). */
+  settleEntry?: () => void;
   /** Open the calendar popover (Alt+↓). Omitted for the popover-less `DateField`. */
   onOpenCalendar?: () => void;
   isDisabled?: boolean;
@@ -95,6 +97,7 @@ export function DateFieldRow({
   setDayPeriod,
   clearSegment,
   applyShortcut,
+  settleEntry,
   onOpenCalendar,
   isDisabled,
   isReadOnly,
@@ -129,6 +132,16 @@ export function DateFieldRow({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
+  // The settled day's full name, announced with each date segment's value
+  // so screen-reader users hear it as they edit (the visible span is hidden).
+  const dayOfWeekLabel = segments.find((s) => s.type === "dayOfWeek")?.label;
+
+  const segmentValueText = (segment: Segment): string => {
+    if (segment.isPlaceholder) return t("empty");
+    const isDate = segment.type === "year" || segment.type === "month" || segment.type === "day";
+    return isDate && dayOfWeekLabel ? `${segment.text}, ${dayOfWeekLabel}` : segment.text;
+  };
+
   // Index editable segments for left/right focus movement.
   const editableIndexById = useMemo(() => {
     const map = new Map<number, number>();
@@ -157,7 +170,7 @@ export function DateFieldRow({
     segment: Segment,
     editableIndex: number,
   ) => {
-    if (segment.type === "literal") return;
+    if (segment.type === "literal" || segment.type === "dayOfWeek") return;
     const type = segment.type;
 
     // Alt+↓ opens the calendar popover (APG date-picker pattern + QBO). No-op on
@@ -262,6 +275,22 @@ export function DateFieldRow({
             </span>
           );
         }
+        if (segment.type === "dayOfWeek") {
+          // Derived from the composed date, so read-only. Hidden from assistive
+          // tech: the date segments' `aria-valuetext` carries it instead.
+          return (
+            <span
+              key={idx}
+              aria-hidden="true"
+              data-slot="date-segment"
+              data-type="dayOfWeek"
+              data-placeholder={segment.isPlaceholder || undefined}
+              className="astw:select-none astw:px-px astw:data-[placeholder]:text-muted-foreground"
+            >
+              {segment.text}
+            </span>
+          );
+        }
         const editableIndex = editableIndexById.get(idx)!;
         return (
           // Editable date segment: the APG spinbutton pattern. A <div role="spinbutton">
@@ -288,10 +317,11 @@ export function DateFieldRow({
             aria-valuemin={segment.minValue}
             aria-valuemax={segment.maxValue}
             aria-valuenow={segment.value}
-            aria-valuetext={segment.isPlaceholder ? t("empty") : segment.text}
+            aria-valuetext={segmentValueText(segment)}
             onFocus={() => {
               typedCountRef.current = 0;
             }}
+            onBlur={settleEntry}
             onKeyDown={(e) => handleKeyDown(e, segment, editableIndex)}
             className={cn(
               "astw:rounded astw:px-0.5 astw:tabular-nums astw:caret-transparent astw:outline-none",
diff --git a/packages/core/src/components/date-field/date-range-input-group.tsx b/packages/core/src/components/date-field/date-range-input-group.tsx
index a1c98fec8..9113fcaa9 100644
--- a/packages/core/src/components/date-field/date-range-input-group.tsx
+++ b/packages/core/src/components/date-field/date-range-input-group.tsx
@@ -119,6 +119,7 @@ export function DateRangeInputGroup({
         setDayPeriod={start.setDayPeriod}
         clearSegment={start.clearSegment}
         applyShortcut={start.applyShortcut}
+        settleEntry={start.settleEntry}
         autoFocus={autoFocus}
         segmentLabel={segmentLabel(t("startDate"))}
         onNavigateOut={(edge) => {
@@ -144,6 +145,7 @@ export function DateRangeInputGroup({
         setDayPeriod={end.setDayPeriod}
         clearSegment={end.clearSegment}
         applyShortcut={end.applyShortcut}
+        settleEntry={end.settleEntry}
         segmentLabel={segmentLabel(t("endDate"))}
         onNavigateOut={(edge) => {
           if (edge === "prev") startHandle.current?.focusLast();
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 c499456d9..750a3eee3 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
@@ -517,3 +517,13 @@ describe("12-hour time display", () => {
     expect(text("end date", "AM/PM")).toBe("PM");
   });
 });
+
+describe("DateRangePicker showDayOfWeek", () => {
+  it("shows the day of the week for both ends", () => {
+    const range = { start: new CalendarDate(2025, 12, 19), end: new CalendarDate(2025, 12, 22) };
+    render(
+      <DateRangePicker aria-label="Period" locale="ja-JP" showDayOfWeek defaultValue={range} />,
+    );
+    expect(screen.getByRole("group").textContent).toBe("2025/12/19(金)–2025/12/22(月)");
+  });
+});
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 06f2cd404..0334240dc 100644
--- a/packages/core/src/components/date-field/date-range-picker.tsx
+++ b/packages/core/src/components/date-field/date-range-picker.tsx
@@ -88,6 +88,8 @@ export type DateRangePickerProps<T extends DateValue = DateValue> = {
   locale?: string;
   /** IANA timezone; defaults to the AppShell `timeZone`. */
   timeZone?: string;
+  /** Show the locale's short day of the week next to each date. */
+  showDayOfWeek?: boolean;
 };
 
 /** One-end snapshot the combined funnel reads to synthesize the range state. */
@@ -129,6 +131,7 @@ const DateRangePicker = forwardRef(function DateRangePicker<T extends DateValue
     isInvalid,
     autoFocus,
     firstDayOfWeek,
+    showDayOfWeek,
     name,
     startName,
     endName,
@@ -220,6 +223,7 @@ const DateRangePicker = forwardRef(function DateRangePicker<T extends DateValue
     minValue,
     maxValue,
     isDateUnavailable,
+    showDayOfWeek,
     isReadOnly: resolvedReadOnly,
   };
   const startField = useDateFieldState({
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 cf102d029..277bc9378 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
@@ -61,7 +61,8 @@ const SEGMENT_MAX_DIGITS: Record<EditableSegmentType, number> = {
 type Fields = Partial<Record<EditableSegmentType, number>>;
 
 export interface Segment {
-  type: EditableSegmentType | "literal";
+  /** `dayOfWeek` is read-only, derived from the composed date. */
+  type: EditableSegmentType | "literal" | "dayOfWeek";
   /** Display text (locale-formatted value, or placeholder when empty). */
   text: string;
   isEditable: boolean;
@@ -69,6 +70,8 @@ export interface Segment {
   value?: number;
   minValue?: number;
   maxValue?: number;
+  /** Day-of-week only: the full day name for assistive tech, once settled. */
+  label?: string;
 }
 
 /**
@@ -131,6 +134,8 @@ export interface DateFieldStateOptions {
   isDateUnavailable?: (date: DateValue) => boolean;
   /** Week-start for the `w`/`k` shortcuts; defaults to the locale convention. */
   firstDayOfWeek?: FirstDayOfWeek;
+  /** Append the locale's short day of the week as a read-only segment. */
+  showDayOfWeek?: boolean;
   isDisabled?: boolean;
   isReadOnly?: boolean;
 }
@@ -144,6 +149,7 @@ const PLACEHOLDERS: Record<EditableSegmentType, string> = {
   second: "––",
   dayPeriod: "AM",
 };
+const DAY_OF_WEEK_PLACEHOLDER = "––";
 
 /**
  * Snap an impossible day down to the entered month's real length — but only once
@@ -284,6 +290,7 @@ export function useDateFieldState(options: DateFieldStateOptions) {
     maxValue,
     isDateUnavailable,
     firstDayOfWeek,
+    showDayOfWeek = false,
     isReadOnly,
   } = options;
 
@@ -316,6 +323,15 @@ export function useDateFieldState(options: DateFieldStateOptions) {
   }
   const fields = internalFields;
 
+  // The date segment mid-way through typed entry (a first digit that may still
+  // take a second), plus the fields from before that entry began. Until it
+  // settles, the day of the week keeps showing the pre-entry date's (muted), so typing
+  // "25" never flashes the 2nd's day of the week and the field doesn't reflow.
+  const [pendingEntry, setPendingEntry] = useState<{
+    type: EditableSegmentType;
+    fallback: Fields;
+  } | null>(null);
+
   const lastEmitted = useRef<DateValue | null>(controlledValue ?? defaultValue ?? null);
 
   // Anchor for placeholder formatting + sensible increment starting points.
@@ -417,6 +433,7 @@ export function useDateFieldState(options: DateFieldStateOptions) {
       const f = intent === "edit" ? clampCompleteDay(next) : next;
       const change = buildStateChange(f, intent === "clear" ? "clear" : "edit");
       setInternalFields(f);
+      setPendingEntry(null);
       onStateChange?.(change);
 
       // While editing, only emit a *complete & valid* value — never `null` for a
@@ -453,6 +470,7 @@ export function useDateFieldState(options: DateFieldStateOptions) {
       const nextFields = fieldsFromValue(cv, is12);
       lastEmitted.current = cv;
       setInternalFields(nextFields);
+      setPendingEntry(null);
       onStateChange?.(buildStateChange(nextFields, "external"));
     }
   }, [buildStateChange, controlledValue, isControlled, is12, onStateChange]);
@@ -495,11 +513,20 @@ export function useDateFieldState(options: DateFieldStateOptions) {
       // "02" advances, while "2" still waits for a possible second digit).
       const advance = next * 10 > max || digitCount >= SEGMENT_MAX_DIGITS[type];
       commit({ ...fields, [type]: next });
+      // Time segments never affect the day of the week, so only date entry can pend.
+      if (!advance && DATE_SEGMENTS.includes(type)) {
+        setPendingEntry((prev) => (prev?.type === type ? prev : { type, fallback: fields }));
+      } else {
+        setPendingEntry(null);
+      }
       return { advance };
     },
     [fields, getLimits, commit, isReadOnly],
   );
 
+  /** Typed entry in the focused segment is over (it lost focus). */
+  const settleEntry = useCallback(() => setPendingEntry(null), []);
+
   const setDayPeriod = useCallback(
     (pm: boolean) => {
       if (isReadOnly) return;
@@ -620,14 +647,11 @@ export function useDateFieldState(options: DateFieldStateOptions) {
 
   // ── Display segments (locale-ordered) ────────────────────────────────────────
   // The Intl objects + the locale's part order/separators only depend on
-  // locale / granularity / hour-cycle / timezone (via the anchor) — never on
-  // `fields`. Build them once here so a keystroke (which only changes `fields`)
-  // doesn't spin up a fresh DateFormatter + two NumberFormats + formatToParts.
+  // locale / granularity / hour-cycle / day of the week / timezone (via the
+  // anchor) — never on `fields`. Build them once here so a keystroke (which only
+  // changes `fields`) doesn't spin up a fresh DateFormatter + formatToParts.
   const segmentFormat = useMemo(() => {
-    const formatter = new DateFormatter(locale, {
-      year: "numeric",
-      month: "2-digit",
-      day: "2-digit",
+    const shared: Intl.DateTimeFormatOptions = {
       ...(hasTime
         ? {
             hour: "2-digit",
@@ -636,8 +660,19 @@ export function useDateFieldState(options: DateFieldStateOptions) {
             hour12: is12,
           }
         : {}),
+      ...(showDayOfWeek ? { weekday: "short" } : {}),
       ...(timeZone ? { timeZone } : {}),
-    });
+    };
+    // Format the (always-valid) anchor to get the locale's segment ORDER and the
+    // literal separators. Each editable segment's *text* is then formatted from
+    // its own value, so an in-progress out-of-range value can never build an
+    // invalid date.
+    const parts = new DateFormatter(locale, {
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      ...shared,
+    }).formatToParts(anchor.toDate(timeZone ?? "UTC"));
     const pad2 = new Intl.NumberFormat(locale, { minimumIntegerDigits: 2, useGrouping: false });
     const yearFmt = new Intl.NumberFormat(locale, { useGrouping: false });
     const formatSegment = (type: EditableSegmentType, value: number): string => {
@@ -645,17 +680,29 @@ export function useDateFieldState(options: DateFieldStateOptions) {
       if (type === "year") return yearFmt.format(value);
       return pad2.format(value);
     };
-    // Format the (always-valid) anchor to get the locale's segment ORDER and the
-    // literal separators. Each editable segment's *text* is then formatted from
-    // its own value, so an in-progress out-of-range value can never build an
-    // invalid date.
-    const parts = formatter.formatToParts(anchor.toDate(timeZone ?? "UTC"));
-    return { parts, formatSegment };
-  }, [locale, hasTime, granularity, is12, timeZone, anchor]);
+    // Pinned to UTC on both sides so the day of the week is the calendar date's, never
+    // shifted by the host timezone.
+    const dayOfWeekFmt = new DateFormatter(locale, { weekday: "short", timeZone: "UTC" });
+    const dayOfWeekLongFmt = new DateFormatter(locale, { weekday: "long", timeZone: "UTC" });
+    const formatDayOfWeek = (value: DateValue, long = false): string =>
+      (long ? dayOfWeekLongFmt : dayOfWeekFmt).format(toCalendarDate(value as never).toDate("UTC"));
+    return { parts, formatSegment, formatDayOfWeek };
+  }, [locale, hasTime, granularity, is12, timeZone, anchor, showDayOfWeek]);
 
   const segments = useMemo<Segment[]>(() => {
     return segmentFormat.parts.map<Segment>((part) => {
       const rawType = part.type;
+      if (rawType === "weekday") {
+        const settled = pendingEntry == null ? composeValue(fields) : null;
+        const shown = settled ?? (pendingEntry ? composeValue(pendingEntry.fallback) : null);
+        return {
+          type: "dayOfWeek",
+          text: shown ? segmentFormat.formatDayOfWeek(shown) : DAY_OF_WEEK_PLACEHOLDER,
+          isEditable: false,
+          isPlaceholder: settled == null,
+          label: settled ? segmentFormat.formatDayOfWeek(settled, true) : undefined,
+        };
+      }
       if (!editableTypes.includes(rawType as EditableSegmentType)) {
         return { type: "literal", text: part.value, isEditable: false, isPlaceholder: false };
       }
@@ -673,7 +720,7 @@ export function useDateFieldState(options: DateFieldStateOptions) {
         maxValue: max,
       };
     });
-  }, [segmentFormat, fields, editableTypes, getLimits]);
+  }, [segmentFormat, fields, editableTypes, getLimits, pendingEntry, composeValue]);
 
   const currentChange = buildStateChange(fields, "edit");
 
@@ -690,5 +737,6 @@ export function useDateFieldState(options: DateFieldStateOptions) {
     applyShortcut,
     expandShortYear,
     commitOnBlur,
+    settleEntry,
   };
 }