feat: useLanguage sensor

README.md

@@ -51,6 +51,7 @@
   - [`useIdle`](./docs/useIdle.md) — tracks whether user is being inactive.
   - [`useIntersection`](./docs/useIntersection.md) — tracks an HTML element's intersection. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-useintersection--demo)
   - [`useKey`](./docs/useKey.md), [`useKeyPress`](./docs/useKeyPress.md), [`useKeyboardJs`](./docs/useKeyboardJs.md), and [`useKeyPressEvent`](./docs/useKeyPressEvent.md) — track keys. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usekeypressevent--demo)
+  - [`useLanguage`](./docs/useLanguage.md) — tracks the language of the document.
   - [`useLocation`](./docs/useLocation.md) and [`useSearchParam`](./docs/useSearchParam.md) — tracks page navigation bar location state.
   - [`useLongPress`](./docs/useLongPress.md) — tracks long press gesture of some element.
   - [`useMedia`](./docs/useMedia.md) — tracks state of a CSS media query. [![][img-demo]](https://streamich.github.io/react-use/?path=/story/sensors-usemedia--demo)

docs/useLanguage.md

@@ -0,0 +1,26 @@
+# `useLanguage`
+
+React state hook that tracks the document's `lang` attribute.
+
+## Usage
+
+```jsx
+import { useLanguage } from 'react-use';
+
+const Demo = () => {
+  const [lang, setLang] = useLanguage();
+
+  return (
+    <div>
+      <div>
+        The document's current language is: {lang}
+      </div>
+
+      <br />
+
+      <button onClick={() => setLang("en-US") }>Change to US English</button>
+      <button onClick={() => setLang("es") }>Cambiar a español</button>
+    </div>
+  );
+};
+```

src/index.ts

@@ -42,6 +42,7 @@ export { default as createBreakpoint } from './factory/createBreakpoint';
 // export { default as useKeyboardJs } from './useKeyboardJs';
 export { default as useKeyPress } from './useKeyPress';
 export { default as useKeyPressEvent } from './useKeyPressEvent';
+export { default as useLanguage } from './useLanguage';
 export { default as useLatest } from './useLatest';
 export { default as useLifecycles } from './useLifecycles';
 export { default as useList } from './useList';

src/misc/util.ts

@@ -21,3 +21,5 @@ export function off<T extends Window | Document | HTMLElement | EventTarget>(
 export const isBrowser = typeof window !== 'undefined';
 
 export const isNavigator = typeof navigator !== 'undefined';
+
+export const isDocument = typeof document !== 'undefined';

src/useLanguage.ts

@@ -0,0 +1,34 @@
+import { useEffect, useState, Dispatch, SetStateAction } from 'react';
+import { isDocument } from './misc/util';
+
+function useLanguage() {
+  const [lang, setLangState] = useState<string>(document.documentElement.lang);
+
+  const setLang: Dispatch<SetStateAction<string>> = (action) => {
+    if (typeof action === 'function') {
+      document.documentElement.lang = action(lang);
+    } else {
+      document.documentElement.lang = action;
+    }
+  };
+
+  useEffect(() => {
+    const handler = () => {
+      setLangState(document.documentElement.lang);
+    };
+
+    const observer = new MutationObserver(handler);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['lang'],
+    });
+
+    return () => observer.disconnect();
+  }, []);
+
+  return [lang, setLang] as const;
+}
+
+export default isDocument
+  ? useLanguage
+  : () => ['', (_action: SetStateAction<string>) => {}] as const;

stories/useLanguage.story.tsx

@@ -0,0 +1,26 @@
+import { storiesOf } from '@storybook/react';
+import * as React from 'react';
+import { useLanguage } from '../src';
+import NewTabStory from './util/NewTabStory';
+import ShowDocs from './util/ShowDocs';
+
+const Demo = () => {
+  const [lang, setLang] = useLanguage();
+
+  return (
+    <NewTabStory>
+      <div>
+        <div>The document's current language is: {lang}</div>
+
+        <br />
+
+        <button onClick={() => setLang('en-US')}>Change to US English</button>
+        <button onClick={() => setLang('es')}>Cambiar a español</button>
+      </div>
+    </NewTabStory>
+  );
+};
+
+storiesOf('Sensors/useLanguage', module)
+  .add('Docs', () => <ShowDocs md={require('../docs/useLanguage.md')} />)
+  .add('Demo', () => <Demo />);

tests/useLanguage.test.ts

@@ -0,0 +1,25 @@
+import { renderHook } from '@testing-library/react-hooks';
+import useLanguage from '../src/useLanguage';
+
+describe('useLanguage', () => {
+  it('should be defined', () => {
+    expect(useLanguage).toBeDefined();
+  });
+
+  it('should retrieve the document language', () => {
+    document.documentElement.lang = 'ar-SA';
+    const hook = renderHook(() => useLanguage());
+
+    expect(document.documentElement.lang).toBe(hook.result.current[0]);
+  });
+
+  it('should update document language', () => {
+    const hook = renderHook(() => useLanguage());
+
+    hook.result.current[1]('bn-BD');
+    expect(document.documentElement.lang).toBe('bn-BD');
+
+    hook.result.current[1]('bn-IN');
+    expect(document.documentElement.lang).toBe('bn-IN');
+  });
+});