feat: add useDocumentTitle hook (#102)

A hook that dynamically update the title of a web page.

.changeset/eighty-rivers-wave.md

@@ -0,0 +1,5 @@
+---
+'@raddix/use-document-title': major
+---
+
+Added the useDocumentTitle hook

docs/_config.json

@@ -12,6 +12,10 @@
           "title": "useClickOutside",
           "path": "/hooks/use-click-outside"
         },
+        {
+          "title": "useDocumentTitle",
+          "path": "/hooks/use-document-title"
+        },
         {
           "title": "useEventListener",
           "path": "/hooks/use-event-listener"

docs/en/use-document-title.mdx

@@ -0,0 +1,42 @@
+---
+title: useDocumentTitle
+description: Dynamically update the title of a web page.
+---
+
+## Installation
+
+Install the custom hook from your command line.
+
+<Snippet pkg text='@raddix/use-document-title' />
+
+## Usage
+
+```tsx
+import { useState } from 'react';
+import { useDocumentTitle } from '@raddix/use-document-title';
+
+export default function App() {
+  const [count, setCount] = useState(0)
+  useDocumentTitle(`Clicked ${count} times.`);
+
+  return (
+    <button onClick={() => setCount(count + 1)}>
+        Increment Count: {count}
+    </button>
+  )
+}
+```
+
+## API
+
+### Parameters
+
+<ApiTable
+  data={[
+    {
+      name: 'title',
+      type: 'string',
+      description: 'The title to be set for the document.',
+    }
+  ]}
+ />

docs/es/use-document-title.mdx

@@ -0,0 +1,45 @@
+---
+title: useDocumentTitle
+description: Actualiza dinámicamente el título de una página web.
+---
+
+## Instalación
+
+Instala el custom hook desde su linea de comando.
+
+<Snippet pkg text='@raddix/use-document-title' />
+
+## Uso
+
+```tsx
+import { useState } from 'react';
+import { useDocumentTitle } from '@raddix/use-document-title';
+
+export default function App() {
+  const [count, setCount] = useState(0)
+  useDocumentTitle(`Clicked ${count} times.`);
+
+  return (
+    <button onClick={() => setCount(count + 1)}>
+        Increment Count: {count}
+    </button>
+  )
+}
+```
+
+## API
+
+### Parámetros
+
+<ApiTable
+  head={{
+    name: 'Nombre'
+  }}
+  data={[
+    {
+      name: 'title',
+      type: 'string',
+      description: 'El título que se establecerá para el documento.',
+    }
+  ]}
+ />

packages/hooks/use-document-title/README.md

@@ -0,0 +1,5 @@
+# useDocumentTitle
+
+A hook that dynamically update the title of a web page.
+
+Please refer to the [documentation](https://raddix.dev/hooks/use-document-title) for more information.

packages/hooks/use-document-title/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@raddix/use-document-title",
+  "description": "A hook that dynamically update the title of a web page.",
+  "version": "0.1.0",
+  "license": "MIT",
+  "main": "src/index.ts",
+  "author": "Moises Machuca Valverde <[email protected]> (https://www.moisesmachuca.com)",
+  "homepage": "https://raddix.dev/hooks/use-document-title",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gdvu/raddix.git"
+  },
+  "keywords": [
+    "react-hook",
+    "react-title-hook",
+    "react-use-title",
+    "use-title",
+    "use-document-title",
+    "use-title-hook",
+    "hook-title"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "lint": "eslint \"{src,tests}/*.{ts,tsx,css}\"",
+    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist",
+    "build": "tsup src --dts",
+    "prepack": "clean-package",
+    "postpack": "clean-package restore"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0",
+    "@raddix/use-isomorphic-effect": "workspace:*"
+  },
+  "clean-package": "../../../clean-package.config.json",
+  "tsup": {
+    "clean": true,
+    "target": "es2019",
+    "format": [
+      "cjs",
+      "esm"
+    ]
+  }
+}

packages/hooks/use-document-title/src/index.ts

@@ -0,0 +1,20 @@
+import { useRef } from 'react';
+import { useIsomorphicEffect } from '@raddix/use-isomorphic-effect';
+
+export const useDocumentTitle = (title: string, restoreTitle = true): void => {
+  const defaultTitle = useRef<string | null>(null);
+
+  useIsomorphicEffect(() => {
+    defaultTitle.current = window.document.title;
+
+    return () => {
+      if (restoreTitle && defaultTitle.current) {
+        window.document.title = defaultTitle.current;
+      }
+    };
+  }, [restoreTitle]);
+
+  useIsomorphicEffect(() => {
+    document.title = title.trim();
+  }, [title]);
+};

packages/hooks/use-document-title/tests/index.test.ts

@@ -0,0 +1,30 @@
+import { renderHook } from '@testing-library/react';
+import { useDocumentTitle } from '../src';
+
+describe('useDocumentTitle test:', () => {
+  beforeEach(() => {
+    document.title = 'initial';
+  });
+
+  it('should change the title of the document', () => {
+    renderHook(() => useDocumentTitle('test'));
+
+    expect(document.title).toEqual('test');
+  });
+
+  it('should restore the initial title when unmounting', () => {
+    const { unmount } = renderHook(() => useDocumentTitle('test'));
+
+    expect(document.title).toEqual('test');
+    unmount();
+    expect(document.title).toEqual('initial');
+  });
+
+  it('should not restore the initial title when unmounting.', () => {
+    const { unmount } = renderHook(() => useDocumentTitle('test', false));
+
+    expect(document.title).toEqual('test');
+    unmount();
+    expect(document.title).toEqual('test');
+  });
+});