accessibility: ♿️ Improve calendar header accessibility by adding screen reader text for week numbers

Closes #3797

Author: balajis-qb

src/calendar.tsx

@@ -477,8 +477,9 @@ export default class Calendar extends Component<CalendarProps, CalendarState> {
     const dayNames: React.ReactElement[] = [];
     if (this.props.showWeekNumbers) {
       dayNames.push(
-        <div key="W" className="react-datepicker__day-name">
-          {this.props.weekLabel || "#"}
+        <div key="W" className="react-datepicker__day-name" role="columnheader">
+          <span className="sr-only">Week number</span>
+          <span aria-hidden="true">{this.props.weekLabel || "#"}</span>
         </div>,
       );
     }
@@ -494,10 +495,13 @@ export default class Calendar extends Component<CalendarProps, CalendarState> {
         return (
           <div
             key={offset}
-            aria-label={formatDate(day, "EEEE", this.props.locale)}
+            role="columnheader"
             className={clsx("react-datepicker__day-name", weekDayClassName)}
           >
-            {weekDayName}
+            <span className="sr-only">
+              {formatDate(day, "EEEE", this.props.locale)}
+            </span>
+            <span aria-hidden="true">{weekDayName}</span>
           </div>
         );
       }),
@@ -852,7 +856,7 @@ export default class Calendar extends Component<CalendarProps, CalendarState> {
         {this.renderMonthYearDropdown(i !== 0)}
         {this.renderYearDropdown(i !== 0)}
       </div>
-      <div className="react-datepicker__day-names">
+      <div className="react-datepicker__day-names" role="row">
         {this.header(monthDate)}
       </div>
     </div>

src/stylesheets/datepicker.scss

@@ -2,6 +2,19 @@
 @use "variables" as *;
 @use "mixins" as *;
 
+/* sr-only utility class for accessibility */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
 .react-datepicker-wrapper {
   display: inline-block;
   padding: 0;

src/test/datepicker_test.test.tsx

@@ -3794,6 +3794,54 @@ describe("DatePicker", () => {
     });
   });
 
+  describe("Calendar Header Accessibility", () => {
+    it("renders day names with sr-only full weekday and visible short name", () => {
+      const { container } = render(<DatePicker />);
+      const input = safeQuerySelector(container, "input");
+      fireEvent.focus(input);
+
+      const headers = container.querySelectorAll(
+        '.react-datepicker__day-names > [role="columnheader"]',
+      );
+      expect(headers.length).toBe(7);
+
+      headers.forEach((header) => {
+        // Should have a visually hidden span with the full weekday name
+        const srOnly = header.querySelector(".sr-only");
+        expect(srOnly).toBeTruthy();
+        expect(srOnly?.textContent?.length).toBeGreaterThan(2);
+
+        // Should have a visible short name
+        const visible = header.querySelector('span[aria-hidden="true"]');
+        expect(visible).toBeTruthy();
+        expect(visible?.textContent?.length).toBeLessThanOrEqual(3);
+      });
+    });
+
+    it("renders week number column header with sr-only label and visible #", () => {
+      const { container } = render(<DatePicker showWeekNumbers />);
+      const input = safeQuerySelector(container, "input");
+      fireEvent.focus(input);
+
+      const headers = container.querySelectorAll(
+        '.react-datepicker__day-names > [role="columnheader"]',
+      );
+      expect(headers.length).toBe(8);
+
+      const weekNumberHeader = headers[0] as Element;
+      const srOnly = weekNumberHeader.querySelector(".sr-only");
+      expect(srOnly).toBeTruthy();
+      expect(srOnly?.textContent?.trim()?.toLowerCase()).toEqual("week number");
+
+      // Should have a visible short name
+      const visible = weekNumberHeader.querySelector(
+        'span[aria-hidden="true"]',
+      );
+      expect(visible).toBeTruthy();
+      expect(visible?.textContent?.trim()?.toLowerCase()).toEqual("#");
+    });
+  });
+
   it("should show the correct start of week for GB locale", () => {
     registerLocale("en-GB", enGB);