docs(mobile): add documentation for utils

.scripts/commands/generateDocs/index.ts

@@ -40,6 +40,17 @@ export async function generateDocs(names: string[]) {
                     ctx.docSource = docSource;
                   },
                 },
+                {
+                  title: `Write English document`,
+                  task: async ctx => {
+                    const { docSource } = ctx;
+                    const dirname = path.dirname(sourceFilePath);
+
+                    if (docSource != null) {
+                      await fs.writeFile(`${dirname}/${name}.md`, docSource);
+                    }
+                  },
+                },
                 {
                   title: `Translate markdown to Korean`,
                   task: async ctx => {
@@ -48,37 +59,45 @@ export async function generateDocs(names: string[]) {
 
                     let isFileExists = false;
                     try {
-                      await fs.access(`${dirname}/${name}.md`);
                       await fs.access(`${dirname}/ko/${name}.md`);
                       isFileExists = true;
                     } catch {
                       isFileExists = false;
                     }
 
-                    if (isFileExists && (await fs.readFile(`${dirname}/${name}.md`)).toString() === docSource) {
-                      return;
+                    // Skip if Korean file already exists and English file hasn't changed
+                    if (isFileExists) {
+                      try {
+                        const existingEnglish = await fs.readFile(`${dirname}/${name}.md`, 'utf-8');
+                        if (existingEnglish === docSource) {
+                          return;
+                        }
+                      } catch {
+                        // Continue with translation if we can't read existing file
+                      }
                     }
 
                     if (docSource == null) {
                       throw new Error('docSource is not found');
                     }
 
-                    const translatedDoc = await translate(docSource);
-
-                    ctx.translatedDoc = translatedDoc;
+                    try {
+                      const translatedDoc = await translate(docSource);
+                      ctx.translatedDoc = translatedDoc;
+                    } catch (error) {
+                      // Log the error but don't fail the task - English doc is already saved
+                      console.warn(`Translation failed for ${name}: ${error instanceof Error ? error.message : error}`);
+                      ctx.translatedDoc = null;
+                    }
                   },
                 },
                 {
-                  title: `Write document files`,
+                  title: `Write Korean document`,
+                  skip: ctx => ctx.translatedDoc == null,
                   task: async ctx => {
-                    const { docSource, translatedDoc } = ctx;
-
+                    const { translatedDoc } = ctx;
                     const dirname = path.dirname(sourceFilePath);
 
-                    if (docSource != null) {
-                      await fs.writeFile(`${dirname}/${name}.md`, docSource);
-                    }
-
                     if (translatedDoc != null) {
                       await fs.mkdir(`${dirname}/ko`).catch(e => {
                         if (e.code === 'EEXIST') {
@@ -92,7 +111,7 @@ export async function generateDocs(names: string[]) {
                   },
                 },
               ],
-              { concurrent: false, ctx: subCtx }
+              { concurrent: false, ctx: subCtx, exitOnError: false }
             ),
         },
       ]);
@@ -108,7 +127,8 @@ function parseJSDoc(source: string) {
 
   const template = targetComment.tags.find(tag => tag.tag === 'template');
 
-  const description = targetComment.tags.find(tag => tag.tag === 'description')?.description ?? '';
+  const description =
+    targetComment.tags.find(tag => tag.tag === 'description')?.description ?? targetComment.description ?? '';
 
   const params = targetComment.tags.filter(tag => tag.tag === 'param');
 

.scripts/commands/generateDocs/translate.ts

@@ -284,7 +284,7 @@ ${origin}
   `;
 
   const response = await client.chat.completions.create({
-    model: 'gpt-4o',
+    model: 'gpt-3.5-turbo',
     messages: [{ role: 'user', content: prompt }],
     response_format: { type: 'json_object' },
   });

.scripts/index.ts

@@ -1,7 +1,13 @@
-import 'dotenv/config';
+import dotenv from 'dotenv';
+import path from 'path';
 
 import { Command } from 'commander';
 
+import { getRootPath } from './utils/getRootPath.ts';
+
+// Load .env from project root
+dotenv.config({ path: path.join(getRootPath(), '.env') });
+
 import { generateDocs } from './commands/generateDocs/index.ts';
 import { scaffold } from './commands/scaffold/index.ts';
 

.vitepress/config.mts

@@ -51,6 +51,10 @@ export default defineConfig({
     'packages/mobile/src/hooks/:hook/:hook.md': 'mobile/hooks/:hook.md',
     'packages/mobile/src/hooks/:hook/ko/:hook.md': 'ko/mobile/hooks/:hook.md',
 
+    // Mobile utils
+    'packages/mobile/src/utils/:util/:util.md': 'mobile/utils/:util.md',
+    'packages/mobile/src/utils/:util/ko/:util.md': 'ko/mobile/utils/:util.md',
+
     // Mobile keyboardHeight (special case - folder name differs from hook name)
     'packages/mobile/src/hooks/keyboardHeight/useKeyboardHeight.md': 'mobile/hooks/useKeyboardHeight.md',
     'packages/mobile/src/hooks/keyboardHeight/ko/useKeyboardHeight.md': 'ko/mobile/hooks/useKeyboardHeight.md',

.vitepress/en.mts

@@ -89,6 +89,11 @@ function mobileSidebar(): DefaultTheme.SidebarItem[] {
           collapsed: false,
           items: getSidebarItems(mobilePackageRoot, 'hooks', '/mobile'),
         },
+        {
+          text: 'Utils',
+          collapsed: false,
+          items: getSidebarItems(mobilePackageRoot, 'utils', '/mobile'),
+        },
       ],
     },
   ];

.vitepress/ko.mts

@@ -89,6 +89,11 @@ function mobileSidebar(): DefaultTheme.SidebarItem[] {
           collapsed: false,
           items: getSidebarItems(mobilePackageRoot, 'hooks', '/mobile', 'ko'),
         },
+        {
+          text: '유틸리티',
+          collapsed: false,
+          items: getSidebarItems(mobilePackageRoot, 'utils', '/mobile', 'ko'),
+        },
       ],
     },
   ];

packages/mobile/src/hooks/keyboardHeight/useKeyboardHeight.test.ts

@@ -1,11 +1,11 @@
 import { act, renderHook } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
-import { subscribeKeyboardHeight } from '../../utils/keyboard/subscribeKeyboardHeight.ts';
+import { subscribeKeyboardHeight } from '../../utils/subscribeKeyboardHeight/index.ts';
 
 import { useKeyboardHeight } from './useKeyboardHeight.ts';
 
-vi.mock('../../utils/keyboard/subscribeKeyboardHeight.ts', () => ({
+vi.mock('../../utils/subscribeKeyboardHeight/index.ts', () => ({
   subscribeKeyboardHeight: vi.fn(),
 }));
 

packages/mobile/src/hooks/keyboardHeight/useKeyboardHeight.ts

@@ -1,6 +1,6 @@
 import { useEffect, useState } from 'react';
 
-import { subscribeKeyboardHeight } from '../../utils/keyboard/subscribeKeyboardHeight.ts';
+import { subscribeKeyboardHeight } from '../../utils/subscribeKeyboardHeight/index.ts';
 
 type UseKeyboardHeightOptions = {
   /**

packages/mobile/src/hooks/useBodyScrollLock/useBodyScrollLock.ts

@@ -1,6 +1,7 @@
 import { useEffect } from 'react';
 
-import { disableBodyScrollLock, enableBodyScrollLock } from '../../utils/bodyScrollLock.ts';
+import { disableBodyScrollLock } from '../../utils/disableBodyScrollLock/index.ts';
+import { enableBodyScrollLock } from '../../utils/enableBodyScrollLock/index.ts';
 
 /**
  * Hook to lock body scroll

packages/mobile/src/hooks/useNetworkStatus/useNetworkStatus.ts

@@ -1,6 +1,6 @@
 import { useEffect, useState } from 'react';
 
-import { isServer } from '../../utils/isServer.ts';
+import { isServer } from '../../utils/isServer/index.ts';
 
 /**
  * Effective connection type based on Network Information API

packages/mobile/src/hooks/usePageVisibility/usePageVisibility.ts

@@ -1,6 +1,6 @@
 import { useEffect, useState } from 'react';
 
-import { isServer } from '../../utils/isServer.ts';
+import { isServer } from '../../utils/isServer/index.ts';
 
 /**
  * Page visibility state derived from browser's DocumentVisibilityState.

packages/mobile/src/hooks/useSafeAreaInset/useSafeAreaInset.ts

@@ -1,7 +1,7 @@
 import { startTransition, useCallback, useEffect, useState } from 'react';
 
-import { isServer } from '../../utils/isServer.ts';
-import { getSafeAreaInset, type SafeAreaInset } from '../../utils/safeArea/getSafeAreaInset.ts';
+import { getSafeAreaInset, type SafeAreaInset } from '../../utils/getSafeAreaInset/index.ts';
+import { isServer } from '../../utils/isServer/index.ts';
 
 /**
  * React hook to track safe area inset changes

packages/mobile/src/hooks/useScrollDirection/useScrollDirection.ts

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 
-import { isServer } from '../../utils/isServer.ts';
+import { isServer } from '../../utils/isServer/index.ts';
 
 type ScrollDirection = 'up' | 'down' | null;
 

packages/mobile/src/hooks/useVisualViewport/useVisualViewport.ts

@@ -1,6 +1,6 @@
 import { startTransition, useCallback, useEffect, useState } from 'react';
 
-import { isServer } from '../../utils/isServer.ts';
+import { isServer } from '../../utils/isServer/index.ts';
 
 type VisualViewportState = {
   /** Viewport width (px) */

packages/mobile/src/index.ts

@@ -13,10 +13,13 @@ export { useScrollDirection } from './hooks/useScrollDirection/index.ts';
 export { useVisualViewport } from './hooks/useVisualViewport/index.ts';
 
 // Utils
-export { disableBodyScrollLock, enableBodyScrollLock } from './utils/bodyScrollLock.ts';
-export { isAndroid, isIOS } from './utils/device/device.ts';
-export { isServer } from './utils/isServer.ts';
-export { getKeyboardHeight } from './utils/keyboard/getKeyboardHeight.ts';
-export { isKeyboardVisible } from './utils/keyboard/isKeyboardVisible.ts';
-export { subscribeKeyboardHeight } from './utils/keyboard/subscribeKeyboardHeight.ts';
-export { getSafeAreaInset } from './utils/safeArea/getSafeAreaInset.ts';
+export { disableBodyScrollLock } from './utils/disableBodyScrollLock/index.ts';
+export { enableBodyScrollLock } from './utils/enableBodyScrollLock/index.ts';
+export { getKeyboardHeight } from './utils/getKeyboardHeight/index.ts';
+export type { SafeAreaInset } from './utils/getSafeAreaInset/index.ts';
+export { getSafeAreaInset } from './utils/getSafeAreaInset/index.ts';
+export { isAndroid } from './utils/isAndroid/index.ts';
+export { isIOS } from './utils/isIOS/index.ts';
+export { isKeyboardVisible } from './utils/isKeyboardVisible/index.ts';
+export { isServer } from './utils/isServer/index.ts';
+export { subscribeKeyboardHeight } from './utils/subscribeKeyboardHeight/index.ts';