feat(FR-1695): improve BAIFileExplorer UX with refresh functionality and loading optimization (#4664)

Resolves #4662 ([FR-1695](https://lablup.atlassian.net/browse/FR-1695))

## Problem & Motivation

Users frequently need to check for updated files in their virtual folders, especially after uploading files or when collaborating with others. Currently, BAIFileExplorer lacks an intuitive manual refresh mechanism, forcing users to close and reopen the modal or navigate away and back to see updated content.

## User Impact

### Before:
- Users cannot easily verify if their file uploads completed successfully
- Collaborators cannot see newly shared files without reopening the folder
- The loading experience feels unresponsive and unclear
- Users are unsure whether the file list is currently updating or showing stale data

### After:
- Users can manually refresh at any time with a single click
- Clear visual feedback shows when data was last updated (e.g., "Last Updated: 2 minutes ago")
- Loading states are optimized: spinner for first load, subtle opacity change for refreshes
- Users maintain context and control over their file browsing experience

## Changes

1. **Refresh Button Integration**: Added BAIFetchKeyButton to ExplorerActionControls with loading state feedback
2. **Loading State Optimization**:
   - Spinner loading for initial file list load
   - Opacity-based loading for subsequent refreshes
   - Distinguish between `isFirstFetching` and `isFetching` states
3. **Component Migration**: Moved BAIFetchKeyButton and useIntervalValue hooks to backend.ai-ui package for reusability
4. **i18n Support**: Added translations in 20+ languages following `comp:ComponentName.Key` pattern

## Test Plan

- [ ] Verify refresh button appears in file explorer
- [ ] Check that clicking refresh updates the file list
- [ ] Confirm "Last Updated" timestamp displays correctly
- [ ] Test initial loading shows spinner
- [ ] Test refresh shows opacity change (not spinner)
- [ ] Verify functionality works after file upload
- [ ] Test in both light and dark themes

[FR-1695]: https://lablup.atlassian.net/browse/FR-1695?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ

Author: yomybaby

packages/backend.ai-ui/src/__test__/matchMedia.mock.js

@@ -0,0 +1,13 @@
+Object.defineProperty(window, 'matchMedia', {
+  writable: true,
+  value: jest.fn().mockImplementation((query) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: jest.fn(), // deprecated
+    removeListener: jest.fn(), // deprecated
+    addEventListener: jest.fn(),
+    removeEventListener: jest.fn(),
+    dispatchEvent: jest.fn(),
+  })),
+});

react/src/components/BAIFetchKeyButton.tsx renamed to packages/backend.ai-ui/src/components/BAIFetchKeyButton.tsx

@@ -1,12 +1,14 @@
-import useControllableState_deprecated from '../hooks/useControllableState';
+import { omitNullAndUndefinedFields } from '../helper';
 import { useInterval, useIntervalValue } from '../hooks/useIntervalValue';
 import { ReloadOutlined } from '@ant-design/icons';
+import { useControllableValue } from 'ahooks';
 import { Button, ButtonProps, Tooltip } from 'antd';
 import dayjs from 'dayjs';
+import _ from 'lodash';
 import React, { useEffect, useLayoutEffect, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 
-interface BAIAutoRefetchButtonProps
+interface BAIFetchKeyButtonProps
   extends Omit<ButtonProps, 'value' | 'onChange' | 'loading'> {
   value: string;
   loading?: boolean;
@@ -18,7 +20,7 @@ interface BAIAutoRefetchButtonProps
   hidden?: boolean;
   pauseWhenHidden?: boolean;
 }
-const BAIFetchKeyButton: React.FC<BAIAutoRefetchButtonProps> = ({
+const BAIFetchKeyButton: React.FC<BAIFetchKeyButtonProps> = ({
   loading,
   onChange,
   showLastLoadTime,
@@ -29,11 +31,14 @@ const BAIFetchKeyButton: React.FC<BAIAutoRefetchButtonProps> = ({
   pauseWhenHidden = true,
   ...buttonProps
 }) => {
+  'use memo';
+
   const { t } = useTranslation();
-  const [lastLoadTime, setLastLoadTime] = useControllableState_deprecated(
-    {
+  const [lastLoadTime, setLastLoadTime] = useControllableValue(
+    // To use the default value when lastLoadTimeProp is undefined, we need to omit the value field
+    omitNullAndUndefinedFields({
       value: lastLoadTimeProp,
-    },
+    }),
     {
       defaultValue: new Date(),
     },
@@ -61,7 +66,7 @@ const BAIFetchKeyButton: React.FC<BAIAutoRefetchButtonProps> = ({
   const loadTimeMessage = useIntervalValue(
     () => {
       if (lastLoadTime) {
-        return `${t('general.LastUpdated')}: ${dayjs(lastLoadTime).fromNow()}`;
+        return `${t('comp:BAIFetchKeyButton.LastUpdated')}: ${dayjs(lastLoadTime).fromNow()}`;
       }
       return '';
     },
@@ -90,7 +95,7 @@ const BAIFetchKeyButton: React.FC<BAIAutoRefetchButtonProps> = ({
   return hidden ? null : (
     <Tooltip title={tooltipTitle} placement="topLeft">
       <Button
-        title={tooltipTitle ? undefined : t('general.Refresh')}
+        title={tooltipTitle ? undefined : t('comp:BAIFetchKeyButton.Refresh')}
         loading={displayLoading}
         size={size}
         icon={<ReloadOutlined />}

packages/backend.ai-ui/src/components/baiClient/FileExplorer/BAIFileExplorer.tsx

@@ -3,6 +3,7 @@ import {
   filterOutEmpty,
   localeCompare,
 } from '../../../helper';
+import BAIFetchKeyButton from '../../BAIFetchKeyButton';
 import BAIFlex from '../../BAIFlex';
 import BAILink from '../../BAILink';
 import BAIUnmountAfterClose from '../../BAIUnmountAfterClose';
@@ -43,6 +44,7 @@ export interface BAIFileExplorerProps {
   enableDownload?: boolean;
   enableDelete?: boolean;
   enableWrite?: boolean;
+  onChangeFetchKey?: (fetchKey: string) => void;
 }
 
 const BAIFileExplorer: React.FC<BAIFileExplorerProps> = ({
@@ -70,22 +72,13 @@ const BAIFileExplorer: React.FC<BAIFileExplorerProps> = ({
     files,
     directoryTree,
     isFetching,
+    isLoading: isFirstFetching,
     currentPath,
     navigateDown,
     navigateToPath,
     refetch,
   } = useSearchVFolderFiles(targetVFolderId, fetchKey);
 
-  const [fetchedFilesCache, setFetchedFilesCache] = useState<
-    Array<VFolderFile>
-  >([]);
-
-  useEffect(() => {
-    if (!_.isNil(files?.items)) {
-      setFetchedFilesCache(files.items);
-    }
-  }, [files]);
-
   const breadCrumbItems: Array<ItemType> = useMemo(() => {
     const pathParts = currentPath === '.' ? [] : currentPath.split('/');
 
@@ -153,7 +146,7 @@ const BAIFileExplorer: React.FC<BAIFileExplorerProps> = ({
       render: (name, record) => (
         <EditableFileName
           fileInfo={record}
-          existingFiles={fetchedFilesCache}
+          existingFiles={files?.items || []}
           disabled={!enableWrite}
           onEndEdit={() => {
             refetch();
@@ -247,7 +240,6 @@ const BAIFileExplorer: React.FC<BAIFileExplorerProps> = ({
     };
   }, []);
 
-  const mergedLoading = files?.items !== fetchedFilesCache || isFetching;
   return (
     <FolderInfoContext.Provider value={{ targetVFolderId, currentPath }}>
       {isDragMode && (
@@ -297,27 +289,34 @@ const BAIFileExplorer: React.FC<BAIFileExplorerProps> = ({
                 refetch();
               }
             }}
+            extra={
+              <BAIFetchKeyButton
+                loading={isFetching}
+                value={'_not_used_key_'}
+                onChange={() => {
+                  refetch();
+                }}
+              />
+            }
           />
         </BAIFlex>
 
         <BAITable
           rowKey="name"
           scroll={{ x: 'max-content' }}
-          dataSource={fetchedFilesCache}
+          dataSource={files?.items}
           columns={tableColumns}
           // If no files have been loaded yet (including cache), show spinner loading
-          spinnerLoading={!files?.items ? mergedLoading : undefined}
+          spinnerLoading={isFirstFetching}
           // If files have been loaded before, use normal loading style (opacity)
-          loading={
-            files?.items && files?.items.length >= 0 ? mergedLoading : undefined
-          }
+          loading={!isFirstFetching && isFetching}
           pagination={false}
           rowSelection={{
             type: 'checkbox',
             selectedRowKeys: _.map(selectedItems, 'name'),
             onChange: (selectedRowKeys) => {
               setSelectedItems(
-                fetchedFilesCache?.filter((file) =>
+                files?.items?.filter((file) =>
                   selectedRowKeys.includes(file.name),
                 ) || [],
               );

packages/backend.ai-ui/src/components/baiClient/FileExplorer/ExplorerActionControls.tsx

@@ -38,6 +38,8 @@ interface ExplorerActionControlsProps {
   onUpload: (files: Array<RcFile>, currentPath: string) => void;
   enableDelete?: boolean;
   enableWrite?: boolean;
+  // onClickRefresh?: (key: string) => void;
+  extra?: React.ReactNode;
 }
 
 const ExplorerActionControls: React.FC<ExplorerActionControlsProps> = ({
@@ -46,6 +48,7 @@ const ExplorerActionControls: React.FC<ExplorerActionControlsProps> = ({
   onUpload,
   enableDelete = false,
   enableWrite = false,
+  extra,
 }) => {
   const { t } = useTranslation();
   const { lg } = Grid.useBreakpoint();
@@ -163,6 +166,7 @@ const ExplorerActionControls: React.FC<ExplorerActionControlsProps> = ({
           toggleCreateModal();
         }}
       />
+      {extra}
     </BAIFlex>
   );
 };

packages/backend.ai-ui/src/components/baiClient/FileExplorer/hooks.ts

@@ -38,6 +38,7 @@ export const useSearchVFolderFiles = (vfolder: string, fetchKey?: string) => {
     data: files,
     refetch,
     isFetching,
+    isLoading,
   } = useQuery({
     queryKey: ['searchVFolderFiles', vfolder, currentPath, fetchKey],
     queryFn: () =>
@@ -61,6 +62,7 @@ export const useSearchVFolderFiles = (vfolder: string, fetchKey?: string) => {
     navigateToPath,
     refetch,
     isFetching,
+    isLoading,
   };
 };
 

packages/backend.ai-ui/src/components/index.ts

@@ -57,6 +57,7 @@ export { default as BAIConfirmModalWithInput } from './BAIConfirmModalWithInput'
 export type { BAIConfirmModalWithInputProps } from './BAIConfirmModalWithInput';
 export { default as BAIButton } from './BAIButton';
 export type { BAIButtonProps } from './BAIButton';
+export { default as BAIFetchKeyButton } from './BAIFetchKeyButton';
 export * from './Table';
 export * from './fragments';
 export * from './provider';

packages/backend.ai-ui/src/hooks/index.ts

@@ -38,3 +38,4 @@ export { default as useViewer } from './useViewer';
 export type { ErrorResponse } from './useErrorMessageResolver';
 export type { ESMClientErrorResponse } from './useErrorMessageResolver';
 export { default as useGetAvailableFolderName } from './useGetAvailableFolderName';
+export { useInterval, useIntervalValue } from './useIntervalValue';

react/src/hooks/useIntervalValue.test.tsx renamed to packages/backend.ai-ui/src/hooks/useIntervalValue.test.tsx

@@ -1,3 +1,4 @@
+import '../__test__/matchMedia.mock.js';
 import { useInterval, useIntervalValue } from './useIntervalValue';
 import { render, screen, act } from '@testing-library/react';
 import React from 'react';

react/src/hooks/useIntervalValue.tsx renamed to packages/backend.ai-ui/src/hooks/useIntervalValue.tsx

@@ -53,6 +53,10 @@
     "SuccessFullyRemoved": "Erfolgreich entfernt {{count}} Versionen.",
     "Version": "Version"
   },
+  "comp:BAIFetchKeyButton": {
+    "LastUpdated": "Zuletzt aktualisiert",
+    "Refresh": "Aktualisieren"
+  },
   "comp:BAIImportArtifactModal": {
     "ExcludedVersions": "{{count}} Versionen sind ausgeschlossen.",
     "FailedToPullVersions": "Versäumte, Versionen zu ziehen.",