Merge branch 'main' of https://github.com/siberiacancode/reactuse

docs/.vitepress/config.mts

@@ -1,10 +1,27 @@
 import { fileURLToPath } from 'node:url';
+import type { DefaultTheme } from 'vitepress';
 import { defineConfig } from 'vitepress';
 
 import { getHookItems } from '../src/utils';
 
 export default async () => {
-  const sidebarHookItems = await getHookItems();
+  const hookItems = await getHookItems();
+  const sidebarHookItems = hookItems.reduce<DefaultTheme.SidebarItem[]>((categoryItems, hookItem) => {
+    const category = categoryItems.find((group) => group.text === hookItem.category);
+
+    if (!category) {
+      categoryItems.push({ text: hookItem.category, items: [hookItem] });
+    } else {
+      category.items!.push(hookItem);
+    }
+
+    return categoryItems;
+  }, []);
+  const homePageFeatures = hookItems.map((item) => ({
+    title: item.text,
+    details: item.description,
+    link: item.link
+  }));
 
   return defineConfig({
     base: '/reactuse/',
@@ -19,11 +36,7 @@ export default async () => {
     },
     transformPageData: (pageData) => {
       if (pageData.relativePath === 'index.md') {
-        pageData.frontmatter.features = sidebarHookItems.map((item) => ({
-          title: item.text,
-          details: item.description,
-          link: item.link
-        }))
+        pageData.frontmatter.features = homePageFeatures
       }
 
       if (pageData.relativePath.includes('hooks')) {
@@ -73,10 +86,7 @@ export default async () => {
               text: 'Getting started',
               link: '/getting-started'
             },
-            {
-              text: 'Hooks',
-              items: [...sidebarHookItems]
-            }
+            ...sidebarHookItems
           ]
         }
       }

docs/functions/hooks/[name].md

@@ -1,11 +1,14 @@
 <script setup>
+import Meta from '../../src/components/meta.vue'
 import Api from '../../src/components/api.vue'
 import Demo from '../../src/components/demo.vue'
 import Contributors from '../../src/components/contributors.vue'
 </script>
 
 # {{ $params.name }}
 
+<Meta :last-modified="$params.lastModified" :category="$params.category" />
+
 {{ $params.description }}
 
 ```typescript-vue

docs/functions/hooks/[name].paths.ts

@@ -6,8 +6,8 @@ export default {
 
     const params = await Promise.all(
       hooks.map(async (hook) => {
-        const file = await getHookFile(hook);
-        const jsdocMatch = matchJsdoc(file);
+        const { content, stats } = await getHookFile(hook);
+        const jsdocMatch = matchJsdoc(content);
 
         if (!jsdocMatch) {
           console.error(`No jsdoc comment found for ${hook}`);
@@ -26,6 +26,8 @@ export default {
             id: hook,
             name: hook,
             description: jsdoc.description.description,
+            category: jsdoc.category?.name,
+            lastModified: stats.mtime.getTime(),
             usage: jsdoc.usage.description,
             apiParameters: jsdoc.apiParameters
           }

docs/src/components/meta.vue

@@ -0,0 +1,62 @@
+<script setup>
+const props = defineProps({
+  lastModified: {
+    type: Number
+  },
+  category: {
+    type: String
+  }
+});
+
+const timeAgo = (timestamp, locale = 'en') => {
+  let value;
+  const diff = Math.floor((new Date().getTime() - timestamp) / 1000);
+  const minutes = Math.floor(diff / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+  const months = Math.floor(days / 30);
+  const years = Math.floor(months / 12);
+  const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+
+  if (years > 0) {
+    value = rtf.format(0 - years, "year");
+  } else if (months > 0) {
+    value = rtf.format(0 - months, "month");
+  } else if (days > 0) {
+    value = rtf.format(0 - days, "day");
+  } else if (hours > 0) {
+    value = rtf.format(0 - hours, "hour");
+  } else if (minutes > 0) {
+    value = rtf.format(0 - minutes, "minute");
+  } else {
+    value = rtf.format(0 - diff, "second");
+  }
+  return value;
+}
+</script>
+
+<template>
+  <div class="meta">
+    <template v-if="category">
+      <div>Category</div>
+      <div><code>{{ category }}</code></div>
+    </template>
+    <ClientOnly v-if="lastModified">
+      <div>Last Changed</div>
+      <div>{{ timeAgo(lastModified) }}</div>
+    </ClientOnly>
+  </div>
+</template>
+
+<style scoped>
+.meta {
+  font-size: .875rem;
+  line-height: 1.25rem;
+  display: grid;
+  grid-template-columns: 100px auto;
+  gap: .5rem;
+  align-items: flex-start;
+  margin-top: 1rem;
+  margin-bottom: 2rem;
+}
+</style>

docs/src/utils/hooks/getHookFile.ts

@@ -2,8 +2,12 @@ import fs from 'node:fs';
 
 export const getHookFile = async (name: string) => {
   try {
-    const fileContent = await fs.promises.readFile(`./src/hooks/${name}/${name}.ts`, 'utf-8');
-    return fileContent;
+    const filePath = `./src/hooks/${name}/${name}.ts`;
+
+    const stats = await fs.promises.stat(filePath);
+    const content = await fs.promises.readFile(filePath, 'utf-8');
+
+    return { stats, content };
   } catch (error) {
     console.error(`Error reading file: ${error}`);
     throw error;

docs/src/utils/hooks/getHookItems.ts

@@ -5,6 +5,7 @@ import { getHooks } from './getHooks';
 
 interface HookItem {
   text: string;
+  category: string;
   description: string;
   link: string;
 }
@@ -14,10 +15,10 @@ export const getHookItems = async (): Promise<HookItem[]> => {
 
   const sidebar = await Promise.all(
     hooks.map(async (hook) => {
-      const file = await getHookFile(hook);
+      const { content } = await getHookFile(hook);
 
       const jsdocCommentRegex = /\/\*\*\s*\n([^\\*]|(\*(?!\/)))*\*\//;
-      const match = file.match(jsdocCommentRegex);
+      const match = content.match(jsdocCommentRegex);
 
       if (!match) {
         console.error(`No jsdoc comment found for ${hook}`);
@@ -34,6 +35,7 @@ export const getHookItems = async (): Promise<HookItem[]> => {
       return {
         text: hook,
         description: jsdoc.description.description,
+        category: jsdoc.category?.name,
         link: `/functions/hooks/${hook}`
       };
     })

docs/src/utils/parseHookJsdoc.ts

@@ -5,9 +5,10 @@ export const parseHookJsdoc = (file: string) => {
   const description = jsdoc.tags.find(({ tag }) => tag === 'description');
   const usage = jsdoc.tags.find(({ tag }) => tag === 'example');
   const deprecated = jsdoc.tags.find(({ tag }) => tag === 'deprecated');
+  const category = jsdoc.tags.find(({ tag }) => tag === 'category');
   const apiParameters = jsdoc.tags.filter(
     ({ tag }) => tag === 'param' || tag === 'overload' || tag === 'returns'
   );
 
-  return { description, usage, apiParameters, deprecated };
+  return { description, usage, apiParameters, deprecated, category };
 };

src/hooks/useBattery/useBattery.ts

@@ -27,6 +27,7 @@ interface UseBatteryStateReturn {
 /**
  * @name useBattery
  * @description - Hook for getting information about battery status
+ * @category Browser
  *
  * @returns {UseBatteryStateReturn} Object containing battery information & Battery API support
  *

src/hooks/useBoolean/useBoolean.ts

@@ -11,6 +11,7 @@ type UseBooleanReturn = [
 /**
  * @name useBoolean
  * @description - Hook provides a boolean state and a function to toggle the boolean value
+ * @category Utilities
  *
  * @param {boolean} [initialValue=false] The initial boolean value
  * @returns {UseBooleanReturn} An object containing the boolean state value and utility functions to manipulate the state

src/hooks/useBrowserLanguage/useBrowserLanguage.ts

@@ -10,6 +10,7 @@ const subscribe = (cb: () => void) => {
 /**
  * @name useBrowserLanguage
  * @description - Hook that returns the current browser language
+ * @category Browser
  *
  * @returns {string} The current browser language
  *

src/hooks/useClickOutside/useClickOutside.ts

@@ -38,6 +38,7 @@ export type UseClickOutside = {
 /**
  * @name useClickOutside
  * @description - Hook to handle click events outside the specified target element(s)
+ * @category Sensors
  *
  * @overload
  * @template Target The target element(s)

src/hooks/useCopyToClipboard/useCopyToClipboard.ts

@@ -20,6 +20,7 @@ interface UseCopyToClipboardReturn {
 /**
  * @name useCopyToClipboard
  * @description - Hook that manages a copy to clipboard
+ * @category Browser
  *
  * @returns {UseCopyToClipboardReturn} An object containing the boolean state value and utility functions to manipulate the state
  *

src/hooks/useCounter/useCounter.ts

@@ -41,6 +41,7 @@ export type UseCounter = {
 /**
  * @name useCounter
  * @description - Hook that manages a counter with increment, decrement, reset, and set functionalities
+ * @category Utilities
  *
  * @overload
  * @param {number} [initialValue=0] The initial number value
@@ -56,7 +57,7 @@ export type UseCounter = {
  *
  * @example
  * const { count, dec, inc, reset, set } = useCounter(5);
- * 
+ *
  * @example
  * const { count, dec, inc, reset, set } = useCounter({ initialValue: 5, min: 0, max: 10 });
  */

src/hooks/useDebounceCallback/useDebounceCallback.ts

@@ -5,6 +5,7 @@ import { debounce } from '@/utils/helpers';
 /**
  * @name useDebounceCallback
  * @description - Hook that creates a debounced callback and returns a stable reference of it
+ * @category Utilities
  *
  * @template Params The type of the params
  * @template Return The type of the return

src/hooks/useDebounceValue/useDebounceValue.ts

@@ -5,6 +5,7 @@ import { useDebounceCallback } from '../useDebounceCallback/useDebounceCallback'
 /**
  * @name useDebounceValue
  * @description - Hook that creates a debounced value and returns a stable reference of it
+ * @category Utilities
  *
  * @template Value The type of the value
  * @param {Value} value The value to be debounced

src/hooks/useDefault/useDefault.ts

@@ -3,6 +3,7 @@ import { useState } from 'react';
 /**
  * @name useDefault
  * @description - Hook that returns the default value
+ * @category Utilities
  *
  * @template Value The type of the value
  * @param {Value} initialValue The initial value

src/hooks/useDidUpdate/useDidUpdate.ts

@@ -6,6 +6,7 @@ import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect/useIsomo
 /**
  * @name useDidUpdate
  * @description – Hook that behaves like useEffect, but skips the effect on the initial render
+ * @category Lifecycle
  *
  * @param {EffectCallback} effect The effect callback
  * @param {DependencyList} [deps] The dependencies list for the effect

src/hooks/useDisclosure/useDisclosure.ts

@@ -15,6 +15,7 @@ interface UseDisclosureReturn {
 /**
  * @name useDisclosure
  * @description - Hook that allows you to open and close a modal
+ * @category Utilities
  *
  * @param {boolean} initialValue The initial value of the component
  * @param {() => void} [options.onOpen] The callback function to be invoked on open

src/hooks/useDocumentEvent/useDocumentEvent.ts

@@ -4,6 +4,7 @@ import { useEventListener } from '../useEventListener/useEventListener';
 /**
  * @name useDocumentEvent
  * @description - Hook attaches an event listener to the document object for the specified event
+ * @category Browser
  *
  * @template Event Key of document event map.
  * @param {Event} event The event to listen for.

src/hooks/useDocumentTitle/useDocumentTitle.ts

@@ -21,6 +21,7 @@ export type UseDocumentTitleReturn = [
 /**
  * @name useDocumentTitle
  * @description - Hook that manages the document title and allows updating it
+ * @category Browser
  *
  * @param {string} [value] The initial title. If not provided, the current document title will be used
  * @param {boolean} [options.restoreOnUnmount] Restore the previous title on unmount

src/hooks/useDocumentVisibility/useDocumentVisibility.ts

@@ -12,6 +12,7 @@ const subscribe = (callback: () => void) => {
 /**
  * @name useDocumentVisibility
  * @description – Hook that provides the current visibility state of the document
+ * @category Browser
  *
  * @returns {DocumentVisibilityState} The current visibility state of the document, which can be 'visible' or 'hidden'
  *

src/hooks/useEvent/useEvent.ts

@@ -5,6 +5,7 @@ import { useIsomorphicLayoutEffect } from '../useIsomorphicLayoutEffect/useIsomo
 /**
  * @name useEvent
  * @description - Hook that creates an event and returns a stable reference of it
+ * @category Browser
  *
  * @template Params The type of the params
  * @template Return The type of the return

src/hooks/useEyeDropper/useEyeDropper.ts

@@ -23,6 +23,7 @@ export interface UseEyeDropperReturn {
 /**
  * @name useEyeDropper
  * @description - Hook that gives you access to the eye dropper
+ * @category Browser
  *
  * @param {string} [initialValue=undefined] The initial value for the eye dropper
  * @returns {UseEyeDropperReturn} An object containing the supported status, the value and the open method

src/hooks/useFavicon/useFavicon.ts

@@ -10,6 +10,7 @@ export type UseFaviconReturn = [string, Dispatch<SetStateAction<string>>];
 /**
  * @name useFavicon
  * @description - Hook that manages the favicon
+ * @category Browser
  *
  * @param {string} [initialFavicon] The initial favicon. If not provided, the current favicon will be used
  * @returns {UseFaviconReturn} An array containing the current favicon and a function to update the favicon

src/hooks/useField/useField.ts

@@ -82,8 +82,9 @@ export interface UseFieldReturn<Value> {
 }
 
 /**
- * @name UseField
+ * @name useField
  * @description - Hook to manage a form field
+ * @category Utilities
  *
  * @template Value The input value
  * @template Type The input value type

src/hooks/useFps/useFps.ts

@@ -3,6 +3,7 @@ import { useEffect, useState } from 'react';
 /**
  * @name useFps
  * @description - Hook that measures frames per second
+ * @category Sensors
  *
  * @returns {number} A number which determines frames per second
  *

src/hooks/useFullscreen/useFullscreen.ts

@@ -53,6 +53,7 @@ export type UseFullScreen = {
 /**
  * @name useFullscreen
  * @description - Hook to handle fullscreen events
+ * @category Browser
  *
  * @overload
  * @template Target The target element for fullscreen

src/hooks/useHash/useHash.ts

@@ -8,6 +8,7 @@ type UseHashReturn = [string, (value: string) => void];
 /**
  * @name useHash
  * @description - Hook that manages the hash value
+ * @category Browser
  *
  * @returns {UseHashReturn} An array containing the hash value and a function to set the hash value
  *

src/hooks/useHotkeys/useHotkeys.ts

@@ -39,6 +39,7 @@ export type UseHotkeysKey = { key: string; code: string; alias: string };
 /**
  * @name useHotkeys
  * @description - Hook that listens for hotkeys
+ * @category Sensors
  *
  * @param {UseHotkeysHotkeys} hotkeys The key or keys to listen for
  * @param {(event: KeyboardEvent) => void} callback The callback function to be called when the hotkey is pressed