feat: add lang attribute to DayPicker root (#2907)

Author: gpbl

examples/__snapshots__/Range.test.tsx.snap

@@ -7,6 +7,7 @@ exports[`should match the snapshot 1`] = `
       class="rdp-root"
       data-mode="range"
       id="test"
+      lang="en-US"
     >
       <div
         class="rdp-months"
@@ -646,6 +647,7 @@ exports[`when a day in the range is clicked when the day is clicked again when a
       class="rdp-root"
       data-mode="range"
       id="test"
+      lang="en-US"
     >
       <div
         class="rdp-months"

examples/__snapshots__/StylingCssModules.test.tsx.snap

@@ -7,6 +7,7 @@ exports[`should match the snapshot 1`] = `
   <div
     class="rdp-root"
     data-mode="single"
+    lang="en-US"
   >
     <div
       class="rdp-months"

src/DayPicker.test.tsx

@@ -61,6 +61,23 @@ test("forward aria attributes to the root element", () => {
   expect(dayPicker()).toHaveAttribute("aria-labelledby", "calendar-heading");
 });
 
+describe("when rendering the root language tag", () => {
+  test("sets the default locale code when lang is not provided", () => {
+    render(<DayPicker data-testid={testId} />);
+    expect(dayPicker()).toHaveAttribute("lang", defaultLocale.code);
+  });
+
+  test("uses the locale code when locale is provided", () => {
+    render(<DayPicker data-testid={testId} locale={ja} />);
+    expect(dayPicker()).toHaveAttribute("lang", ja.code);
+  });
+
+  test("prefers lang over locale code when both are provided", () => {
+    render(<DayPicker data-testid={testId} locale={ja} lang="ar" />);
+    expect(dayPicker()).toHaveAttribute("lang", "ar");
+  });
+});
+
 test("use custom components", () => {
   render(
     <DayPicker

src/DayPicker.tsx

@@ -388,7 +388,7 @@ export function DayPicker(initialProps: DayPickerProps) {
         style={style}
         dir={props.dir}
         id={props.id}
-        lang={props.lang}
+        lang={props.lang ?? locale.code}
         nonce={props.nonce}
         title={props.title}
         role={props.role}

src/types/props.ts

@@ -428,7 +428,12 @@ export interface PropsBase {
   nonce?: HTMLDivElement["nonce"];
   /** Add a `title` attribute to the container element. */
   title?: HTMLDivElement["title"];
-  /** Add the language tag to the container element. */
+  /**
+   * Add the language tag to the container element.
+   *
+   * When omitted, DayPicker uses the active locale code (`locale.code`).
+   * Set this prop to override the language tag.
+   */
   lang?: HTMLDivElement["lang"];
   /**
    * The locale object used to localize dates. Pass a locale from

website/docs/localization/changing-locale.mdx

@@ -26,6 +26,26 @@ export function Spanish() {
   <Examples.Spanish />
 </BrowserWindow>
 
+## Language tag on the root element
+
+DayPicker sets the root element `lang` attribute from the active locale code (`locale.code`).
+
+If you need a different language tag, pass the `lang` prop explicitly.
+
+```tsx
+import { arSA } from "react-day-picker/locale";
+
+<DayPicker locale={arSA} />;
+```
+
+You can target locale-specific styles with the CSS `:lang(...)` selector:
+
+```css
+.rdp-root:lang(ar) {
+  font-family: "Noto Naskh Arabic", serif;
+}
+```
+
 ## Numerals
 
 Use the `numerals` prop to select the numbering system used by labels and formatters (for example, `latn`, `arab`, `thai`). Locale label translations also respect the numerals you choose.