fix: update tests

Reduce menuRowBaseClassName padding from px-3 to px-2 to match main branch spacing.
Replace raw div with DropdownMenuItem for theme row to fix icon alignment and ARIA semantics.

.agents/skills/frontend-testing/SKILL.md

@@ -204,16 +204,6 @@ When assigned to test a directory/path, test **ALL content** within that path:
 
 > See [Test Structure Template](#test-structure-template) for correct import/mock patterns.
 
-### `nuqs` Query State Testing (Required for URL State Hooks)
-
-When a component or hook uses `useQueryState` / `useQueryStates`:
-
-- ✅ Use `NuqsTestingAdapter` (prefer shared helpers in `web/test/nuqs-testing.tsx`)
-- ✅ Assert URL synchronization via `onUrlUpdate` (`searchParams`, `options.history`)
-- ✅ For custom parsers (`createParser`), keep `parse` and `serialize` bijective and add round-trip edge cases (`%2F`, `%25`, spaces, legacy encoded values)
-- ✅ Verify default-clearing behavior (default values should be removed from URL when applicable)
-- ⚠️ Only mock `nuqs` directly when URL behavior is explicitly out of scope for the test
-
 ## Core Principles
 
 ### 1. AAA Pattern (Arrange-Act-Assert)

.agents/skills/frontend-testing/references/checklist.md

@@ -80,9 +80,6 @@ Use this checklist when generating or reviewing tests for Dify frontend componen
 - [ ] Router mocks match actual Next.js API
 - [ ] Mocks reflect actual component conditional behavior
 - [ ] Only mock: API services, complex context providers, third-party libs
-- [ ] For `nuqs` URL-state tests, wrap with `NuqsTestingAdapter` (prefer `web/test/nuqs-testing.tsx`)
-- [ ] For `nuqs` URL-state tests, assert `onUrlUpdate` payload (`searchParams`, `options.history`)
-- [ ] If custom `nuqs` parser exists, add round-trip tests for encoded edge cases (`%2F`, `%25`, spaces, legacy encoded values)
 
 ### Queries
 

.agents/skills/frontend-testing/references/mocking.md

@@ -125,31 +125,6 @@ describe('Component', () => {
 })
 ```
 
-### 2.1 `nuqs` Query State (Preferred: Testing Adapter)
-
-For tests that validate URL query behavior, use `NuqsTestingAdapter` instead of mocking `nuqs` directly.
-
-```typescript
-import { renderHookWithNuqs } from '@/test/nuqs-testing'
-
-it('should sync query to URL with push history', async () => {
-  const { result, onUrlUpdate } = renderHookWithNuqs(() => useMyQueryState(), {
-    searchParams: '?page=1',
-  })
-
-  act(() => {
-    result.current.setQuery({ page: 2 })
-  })
-
-  await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-  const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-  expect(update.options.history).toBe('push')
-  expect(update.searchParams.get('page')).toBe('2')
-})
-```
-
-Use direct `vi.mock('nuqs')` only when URL synchronization is intentionally out of scope.
-
 ### 3. Portal Components (with Shared State)
 
 ```typescript

.github/workflows/style.yml

@@ -89,7 +89,7 @@ jobs:
         uses: actions/setup-node@v6
         if: steps.changed-files.outputs.any_changed == 'true'
         with:
-          node-version: 22
+          node-version: 24
           cache: pnpm
           cache-dependency-path: ./web/pnpm-lock.yaml
 

.github/workflows/tool-test-sdks.yaml

@@ -28,7 +28,7 @@ jobs:
       - name: Use Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: 24
           cache: ''
           cache-dependency-path: 'pnpm-lock.yaml'
 

.github/workflows/translate-i18n-claude.yml

@@ -57,7 +57,7 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: 24
           cache: pnpm
           cache-dependency-path: ./web/pnpm-lock.yaml
 

.github/workflows/web-tests.yml

@@ -39,7 +39,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: 24
           cache: pnpm
           cache-dependency-path: ./web/pnpm-lock.yaml
 
@@ -83,7 +83,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 22
+          node-version: 24
           cache: pnpm
           cache-dependency-path: ./web/pnpm-lock.yaml
 
@@ -457,7 +457,7 @@ jobs:
         uses: actions/setup-node@v6
         if: steps.changed-files.outputs.any_changed == 'true'
         with:
-          node-version: 22
+          node-version: 24
           cache: pnpm
           cache-dependency-path: ./web/pnpm-lock.yaml
 

api/controllers/console/datasets/datasets.py

@@ -119,14 +119,6 @@ def _validate_indexing_technique(value: str | None) -> str | None:
     return value
 
 
-def _validate_doc_form(value: str | None) -> str | None:
-    if value is None:
-        return value
-    if value not in Dataset.DOC_FORM_LIST:
-        raise ValueError("Invalid doc_form.")
-    return value
-
-
 class DatasetCreatePayload(BaseModel):
     name: str = Field(..., min_length=1, max_length=40)
     description: str = Field("", max_length=400)
@@ -187,14 +179,6 @@ class IndexingEstimatePayload(BaseModel):
             raise ValueError("indexing_technique is required.")
         return result
 
-    @field_validator("doc_form")
-    @classmethod
-    def validate_doc_form(cls, value: str) -> str:
-        result = _validate_doc_form(value)
-        if result is None:
-            return "text_model"
-        return result
-
 
 class ConsoleDatasetListQuery(BaseModel):
     page: int = Field(default=1, description="Page number")

api/controllers/service_api/dataset/document.py

@@ -4,7 +4,7 @@ from uuid import UUID
 
 from flask import request
 from flask_restx import marshal
-from pydantic import BaseModel, Field, field_validator, model_validator
+from pydantic import BaseModel, Field, model_validator
 from sqlalchemy import desc, select
 from werkzeug.exceptions import Forbidden, NotFound
 
@@ -60,13 +60,6 @@ class DocumentTextCreatePayload(BaseModel):
     embedding_model: str | None = None
     embedding_model_provider: str | None = None
 
-    @field_validator("doc_form")
-    @classmethod
-    def validate_doc_form(cls, value: str) -> str:
-        if value not in Dataset.DOC_FORM_LIST:
-            raise ValueError("Invalid doc_form.")
-        return value
-
 
 DEFAULT_REF_TEMPLATE_SWAGGER_2_0 = "#/definitions/{model}"
 
@@ -79,13 +72,6 @@ class DocumentTextUpdate(BaseModel):
     doc_language: str = "English"
     retrieval_model: RetrievalModel | None = None
 
-    @field_validator("doc_form")
-    @classmethod
-    def validate_doc_form(cls, value: str) -> str:
-        if value not in Dataset.DOC_FORM_LIST:
-            raise ValueError("Invalid doc_form.")
-        return value
-
     @model_validator(mode="after")
     def check_text_and_name(self) -> Self:
         if self.text is not None and self.name is None:

api/models/dataset.py

@@ -19,7 +19,6 @@ from sqlalchemy.orm import Mapped, Session, mapped_column
 
 from configs import dify_config
 from core.rag.index_processor.constant.built_in_field import BuiltInField, MetadataDataSource
-from core.rag.index_processor.constant.index_type import IndexStructureType
 from core.rag.index_processor.constant.query_type import QueryType
 from core.rag.retrieval.retrieval_methods import RetrievalMethod
 from core.tools.signature import sign_upload_file
@@ -52,7 +51,6 @@ class Dataset(Base):
 
     INDEXING_TECHNIQUE_LIST = ["high_quality", "economy", None]
     PROVIDER_LIST = ["vendor", "external", None]
-    DOC_FORM_LIST = [member.value for member in IndexStructureType]
 
     id: Mapped[str] = mapped_column(StringUUID, default=lambda: str(uuid4()))
     tenant_id: Mapped[str] = mapped_column(StringUUID)

api/pyproject.toml

@@ -172,7 +172,7 @@ dev = [
     "sseclient-py>=1.8.0",
     "pytest-timeout>=2.4.0",
     "pytest-xdist>=3.8.0",
-    "pyrefly>=0.55.0",
+    "pyrefly>=0.54.0",
 ]
 
 ############################################################

api/services/entities/knowledge_entities/knowledge_entities.py

@@ -1,9 +1,8 @@
 from enum import StrEnum
 from typing import Literal
 
-from pydantic import BaseModel, field_validator
+from pydantic import BaseModel
 
-from core.rag.index_processor.constant.index_type import IndexStructureType
 from core.rag.retrieval.retrieval_methods import RetrievalMethod
 
 
@@ -128,18 +127,6 @@ class KnowledgeConfig(BaseModel):
     name: str | None = None
     is_multimodal: bool = False
 
-    @field_validator("doc_form")
-    @classmethod
-    def validate_doc_form(cls, value: str) -> str:
-        valid_forms = [
-            IndexStructureType.PARAGRAPH_INDEX,
-            IndexStructureType.QA_INDEX,
-            IndexStructureType.PARENT_CHILD_INDEX,
-        ]
-        if value not in valid_forms:
-            raise ValueError("Invalid doc_form.")
-        return value
-
 
 class SegmentCreateArgs(BaseModel):
     content: str | None = None

api/tests/test_containers_integration_tests/services/test_dataset_service_batch_update_document_status.py

@@ -1,660 +0,0 @@
-"""Integration tests for DocumentService.batch_update_document_status.
-
-This suite validates SQL-backed batch status updates with testcontainers.
-It keeps database access real and only patches non-DB side effects.
-"""
-
-import datetime
-import json
-from dataclasses import dataclass
-from unittest.mock import call, patch
-from uuid import uuid4
-
-import pytest
-
-from extensions.ext_database import db
-from models.dataset import Dataset, Document
-from services.dataset_service import DocumentService
-from services.errors.document import DocumentIndexingError
-
-FIXED_TIME = datetime.datetime(2023, 1, 1, 12, 0, 0)
-
-
-@dataclass
-class UserDouble:
-    """Minimal user object for batch update operations."""
-
-    id: str
-
-
-class DocumentBatchUpdateIntegrationDataFactory:
-    """Factory for creating persisted entities used in integration tests."""
-
-    @staticmethod
-    def create_dataset(
-        dataset_id: str | None = None,
-        tenant_id: str | None = None,
-        name: str = "Test Dataset",
-        created_by: str | None = None,
-    ) -> Dataset:
-        """Create and persist a dataset."""
-        dataset = Dataset(
-            tenant_id=tenant_id or str(uuid4()),
-            name=name,
-            data_source_type="upload_file",
-            created_by=created_by or str(uuid4()),
-        )
-        if dataset_id:
-            dataset.id = dataset_id
-
-        db.session.add(dataset)
-        db.session.commit()
-        return dataset
-
-    @staticmethod
-    def create_document(
-        dataset: Dataset,
-        document_id: str | None = None,
-        name: str = "test_document.pdf",
-        enabled: bool = True,
-        archived: bool = False,
-        indexing_status: str = "completed",
-        completed_at: datetime.datetime | None = None,
-        position: int = 1,
-        created_by: str | None = None,
-        commit: bool = True,
-        **kwargs,
-    ) -> Document:
-        """Create a document bound to the given dataset and persist it."""
-        document = Document(
-            tenant_id=dataset.tenant_id,
-            dataset_id=dataset.id,
-            position=position,
-            data_source_type="upload_file",
-            data_source_info=json.dumps({"upload_file_id": str(uuid4())}),
-            batch=f"batch-{uuid4()}",
-            name=name,
-            created_from="web",
-            created_by=created_by or str(uuid4()),
-            doc_form="text_model",
-        )
-        document.id = document_id or str(uuid4())
-        document.enabled = enabled
-        document.archived = archived
-        document.indexing_status = indexing_status
-        document.completed_at = (
-            completed_at if completed_at is not None else (FIXED_TIME if indexing_status == "completed" else None)
-        )
-
-        for key, value in kwargs.items():
-            setattr(document, key, value)
-
-        db.session.add(document)
-        if commit:
-            db.session.commit()
-        return document
-
-    @staticmethod
-    def create_multiple_documents(
-        dataset: Dataset,
-        document_ids: list[str],
-        enabled: bool = True,
-        archived: bool = False,
-        indexing_status: str = "completed",
-    ) -> list[Document]:
-        """Create and persist multiple documents for one dataset in a single transaction."""
-        documents: list[Document] = []
-        for index, doc_id in enumerate(document_ids, start=1):
-            document = DocumentBatchUpdateIntegrationDataFactory.create_document(
-                dataset=dataset,
-                document_id=doc_id,
-                name=f"document_{doc_id}.pdf",
-                enabled=enabled,
-                archived=archived,
-                indexing_status=indexing_status,
-                position=index,
-                commit=False,
-            )
-            documents.append(document)
-        db.session.commit()
-        return documents
-
-    @staticmethod
-    def create_user(user_id: str | None = None) -> UserDouble:
-        """Create a lightweight user for update metadata fields."""
-        return UserDouble(id=user_id or str(uuid4()))
-
-
-class TestDatasetServiceBatchUpdateDocumentStatus:
-    """Integration coverage for batch document status updates."""
-
-    @pytest.fixture
-    def patched_dependencies(self):
-        """Patch non-DB collaborators only."""
-        with (
-            patch("services.dataset_service.redis_client") as redis_client,
-            patch("services.dataset_service.add_document_to_index_task") as add_task,
-            patch("services.dataset_service.remove_document_from_index_task") as remove_task,
-            patch("services.dataset_service.naive_utc_now") as naive_utc_now,
-        ):
-            naive_utc_now.return_value = FIXED_TIME
-            redis_client.get.return_value = None
-            yield {
-                "redis_client": redis_client,
-                "add_task": add_task,
-                "remove_task": remove_task,
-                "naive_utc_now": naive_utc_now,
-            }
-
-    def _assert_document_enabled(self, document: Document, current_time: datetime.datetime):
-        """Verify enabled-state fields after action=enable."""
-        assert document.enabled is True
-        assert document.disabled_at is None
-        assert document.disabled_by is None
-        assert document.updated_at == current_time
-
-    def _assert_document_disabled(self, document: Document, user_id: str, current_time: datetime.datetime):
-        """Verify disabled-state fields after action=disable."""
-        assert document.enabled is False
-        assert document.disabled_at == current_time
-        assert document.disabled_by == user_id
-        assert document.updated_at == current_time
-
-    def _assert_document_archived(self, document: Document, user_id: str, current_time: datetime.datetime):
-        """Verify archived-state fields after action=archive."""
-        assert document.archived is True
-        assert document.archived_at == current_time
-        assert document.archived_by == user_id
-        assert document.updated_at == current_time
-
-    def _assert_document_unarchived(self, document: Document):
-        """Verify unarchived-state fields after action=un_archive."""
-        assert document.archived is False
-        assert document.archived_at is None
-        assert document.archived_by is None
-
-    def test_batch_update_enable_documents_success(self, db_session_with_containers, patched_dependencies):
-        """Enable disabled documents and trigger indexing side effects."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        document_ids = [str(uuid4()), str(uuid4())]
-        disabled_docs = DocumentBatchUpdateIntegrationDataFactory.create_multiple_documents(
-            dataset=dataset,
-            document_ids=document_ids,
-            enabled=False,
-        )
-
-        # Act
-        DocumentService.batch_update_document_status(
-            dataset=dataset, document_ids=document_ids, action="enable", user=user
-        )
-
-        # Assert
-        for document in disabled_docs:
-            db.session.refresh(document)
-            self._assert_document_enabled(document, FIXED_TIME)
-
-        expected_get_calls = [call(f"document_{doc_id}_indexing") for doc_id in document_ids]
-        expected_setex_calls = [call(f"document_{doc_id}_indexing", 600, 1) for doc_id in document_ids]
-        expected_add_calls = [call(doc_id) for doc_id in document_ids]
-        patched_dependencies["redis_client"].get.assert_has_calls(expected_get_calls)
-        patched_dependencies["redis_client"].setex.assert_has_calls(expected_setex_calls)
-        patched_dependencies["add_task"].delay.assert_has_calls(expected_add_calls)
-
-    def test_batch_update_enable_already_enabled_document_skipped(
-        self, db_session_with_containers, patched_dependencies
-    ):
-        """Skip enable operation for already-enabled documents."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        document = DocumentBatchUpdateIntegrationDataFactory.create_document(dataset=dataset, enabled=True)
-
-        # Act
-        DocumentService.batch_update_document_status(
-            dataset=dataset,
-            document_ids=[document.id],
-            action="enable",
-            user=user,
-        )
-
-        # Assert
-        db.session.refresh(document)
-        assert document.enabled is True
-        patched_dependencies["redis_client"].setex.assert_not_called()
-        patched_dependencies["add_task"].delay.assert_not_called()
-
-    def test_batch_update_disable_documents_success(self, db_session_with_containers, patched_dependencies):
-        """Disable completed documents and trigger remove-index tasks."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        document_ids = [str(uuid4()), str(uuid4())]
-        enabled_docs = DocumentBatchUpdateIntegrationDataFactory.create_multiple_documents(
-            dataset=dataset,
-            document_ids=document_ids,
-            enabled=True,
-            indexing_status="completed",
-        )
-
-        # Act
-        DocumentService.batch_update_document_status(
-            dataset=dataset,
-            document_ids=document_ids,
-            action="disable",
-            user=user,
-        )
-
-        # Assert
-        for document in enabled_docs:
-            db.session.refresh(document)
-            self._assert_document_disabled(document, user.id, FIXED_TIME)
-
-        expected_get_calls = [call(f"document_{doc_id}_indexing") for doc_id in document_ids]
-        expected_setex_calls = [call(f"document_{doc_id}_indexing", 600, 1) for doc_id in document_ids]
-        expected_remove_calls = [call(doc_id) for doc_id in document_ids]
-        patched_dependencies["redis_client"].get.assert_has_calls(expected_get_calls)
-        patched_dependencies["redis_client"].setex.assert_has_calls(expected_setex_calls)
-        patched_dependencies["remove_task"].delay.assert_has_calls(expected_remove_calls)
-
-    def test_batch_update_disable_already_disabled_document_skipped(
-        self, db_session_with_containers, patched_dependencies
-    ):
-        """Skip disable operation for already-disabled documents."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        disabled_doc = DocumentBatchUpdateIntegrationDataFactory.create_document(
-            dataset=dataset,
-            enabled=False,
-            indexing_status="completed",
-            completed_at=FIXED_TIME,
-        )
-
-        # Act
-        DocumentService.batch_update_document_status(
-            dataset=dataset,
-            document_ids=[disabled_doc.id],
-            action="disable",
-            user=user,
-        )
-
-        # Assert
-        db.session.refresh(disabled_doc)
-        assert disabled_doc.enabled is False
-        patched_dependencies["redis_client"].setex.assert_not_called()
-        patched_dependencies["remove_task"].delay.assert_not_called()
-
-    def test_batch_update_disable_non_completed_document_error(self, db_session_with_containers, patched_dependencies):
-        """Raise error when disabling a non-completed document."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        non_completed_doc = DocumentBatchUpdateIntegrationDataFactory.create_document(
-            dataset=dataset,
-            enabled=True,
-            indexing_status="indexing",
-            completed_at=None,
-        )
-
-        # Act / Assert
-        with pytest.raises(DocumentIndexingError, match="is not completed"):
-            DocumentService.batch_update_document_status(
-                dataset=dataset,
-                document_ids=[non_completed_doc.id],
-                action="disable",
-                user=user,
-            )
-
-    def test_batch_update_archive_documents_success(self, db_session_with_containers, patched_dependencies):
-        """Archive enabled documents and trigger remove-index task."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        document = DocumentBatchUpdateIntegrationDataFactory.create_document(
-            dataset=dataset, enabled=True, archived=False
-        )
-
-        # Act
-        DocumentService.batch_update_document_status(
-            dataset=dataset,
-            document_ids=[document.id],
-            action="archive",
-            user=user,
-        )
-
-        # Assert
-        db.session.refresh(document)
-        self._assert_document_archived(document, user.id, FIXED_TIME)
-        patched_dependencies["redis_client"].get.assert_called_once_with(f"document_{document.id}_indexing")
-        patched_dependencies["redis_client"].setex.assert_called_once_with(f"document_{document.id}_indexing", 600, 1)
-        patched_dependencies["remove_task"].delay.assert_called_once_with(document.id)
-
-    def test_batch_update_archive_already_archived_document_skipped(
-        self, db_session_with_containers, patched_dependencies
-    ):
-        """Skip archive operation for already-archived documents."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        document = DocumentBatchUpdateIntegrationDataFactory.create_document(
-            dataset=dataset, enabled=True, archived=True
-        )
-
-        # Act
-        DocumentService.batch_update_document_status(
-            dataset=dataset,
-            document_ids=[document.id],
-            action="archive",
-            user=user,
-        )
-
-        # Assert
-        db.session.refresh(document)
-        assert document.archived is True
-        patched_dependencies["redis_client"].setex.assert_not_called()
-        patched_dependencies["remove_task"].delay.assert_not_called()
-
-    def test_batch_update_archive_disabled_document_no_index_removal(
-        self, db_session_with_containers, patched_dependencies
-    ):
-        """Archive disabled document without index-removal side effects."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        document = DocumentBatchUpdateIntegrationDataFactory.create_document(
-            dataset=dataset, enabled=False, archived=False
-        )
-
-        # Act
-        DocumentService.batch_update_document_status(
-            dataset=dataset,
-            document_ids=[document.id],
-            action="archive",
-            user=user,
-        )
-
-        # Assert
-        db.session.refresh(document)
-        self._assert_document_archived(document, user.id, FIXED_TIME)
-        patched_dependencies["redis_client"].setex.assert_not_called()
-        patched_dependencies["remove_task"].delay.assert_not_called()
-
-    def test_batch_update_unarchive_documents_success(self, db_session_with_containers, patched_dependencies):
-        """Unarchive enabled documents and trigger add-index task."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        document = DocumentBatchUpdateIntegrationDataFactory.create_document(
-            dataset=dataset, enabled=True, archived=True
-        )
-
-        # Act
-        DocumentService.batch_update_document_status(
-            dataset=dataset,
-            document_ids=[document.id],
-            action="un_archive",
-            user=user,
-        )
-
-        # Assert
-        db.session.refresh(document)
-        self._assert_document_unarchived(document)
-        assert document.updated_at == FIXED_TIME
-        patched_dependencies["redis_client"].get.assert_called_once_with(f"document_{document.id}_indexing")
-        patched_dependencies["redis_client"].setex.assert_called_once_with(f"document_{document.id}_indexing", 600, 1)
-        patched_dependencies["add_task"].delay.assert_called_once_with(document.id)
-
-    def test_batch_update_unarchive_already_unarchived_document_skipped(
-        self, db_session_with_containers, patched_dependencies
-    ):
-        """Skip unarchive operation for already-unarchived documents."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        document = DocumentBatchUpdateIntegrationDataFactory.create_document(
-            dataset=dataset, enabled=True, archived=False
-        )
-
-        # Act
-        DocumentService.batch_update_document_status(
-            dataset=dataset,
-            document_ids=[document.id],
-            action="un_archive",
-            user=user,
-        )
-
-        # Assert
-        db.session.refresh(document)
-        assert document.archived is False
-        patched_dependencies["redis_client"].setex.assert_not_called()
-        patched_dependencies["add_task"].delay.assert_not_called()
-
-    def test_batch_update_unarchive_disabled_document_no_index_addition(
-        self, db_session_with_containers, patched_dependencies
-    ):
-        """Unarchive disabled document without index-add side effects."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        document = DocumentBatchUpdateIntegrationDataFactory.create_document(
-            dataset=dataset, enabled=False, archived=True
-        )
-
-        # Act
-        DocumentService.batch_update_document_status(
-            dataset=dataset,
-            document_ids=[document.id],
-            action="un_archive",
-            user=user,
-        )
-
-        # Assert
-        db.session.refresh(document)
-        self._assert_document_unarchived(document)
-        assert document.updated_at == FIXED_TIME
-        patched_dependencies["redis_client"].setex.assert_not_called()
-        patched_dependencies["add_task"].delay.assert_not_called()
-
-    def test_batch_update_document_indexing_error_redis_cache_hit(
-        self, db_session_with_containers, patched_dependencies
-    ):
-        """Raise DocumentIndexingError when redis indicates active indexing."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        document = DocumentBatchUpdateIntegrationDataFactory.create_document(
-            dataset=dataset,
-            name="test_document.pdf",
-            enabled=True,
-        )
-        patched_dependencies["redis_client"].get.return_value = "indexing"
-
-        # Act / Assert
-        with pytest.raises(DocumentIndexingError, match="is being indexed") as exc_info:
-            DocumentService.batch_update_document_status(
-                dataset=dataset,
-                document_ids=[document.id],
-                action="enable",
-                user=user,
-            )
-
-        assert "test_document.pdf" in str(exc_info.value)
-        patched_dependencies["redis_client"].get.assert_called_once_with(f"document_{document.id}_indexing")
-
-    def test_batch_update_async_task_error_handling(self, db_session_with_containers, patched_dependencies):
-        """Persist DB update, then propagate async task error."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        document = DocumentBatchUpdateIntegrationDataFactory.create_document(dataset=dataset, enabled=False)
-        patched_dependencies["add_task"].delay.side_effect = Exception("Celery task error")
-
-        # Act / Assert
-        with pytest.raises(Exception, match="Celery task error"):
-            DocumentService.batch_update_document_status(
-                dataset=dataset,
-                document_ids=[document.id],
-                action="enable",
-                user=user,
-            )
-
-        db.session.refresh(document)
-        self._assert_document_enabled(document, FIXED_TIME)
-        patched_dependencies["redis_client"].setex.assert_called_once_with(f"document_{document.id}_indexing", 600, 1)
-
-    def test_batch_update_empty_document_list(self, db_session_with_containers, patched_dependencies):
-        """Return early when document_ids is empty."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-
-        # Act
-        result = DocumentService.batch_update_document_status(
-            dataset=dataset, document_ids=[], action="enable", user=user
-        )
-
-        # Assert
-        assert result is None
-        patched_dependencies["redis_client"].get.assert_not_called()
-        patched_dependencies["redis_client"].setex.assert_not_called()
-
-    def test_batch_update_document_not_found_skipped(self, db_session_with_containers, patched_dependencies):
-        """Skip IDs that do not map to existing dataset documents."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        missing_document_id = str(uuid4())
-
-        # Act
-        DocumentService.batch_update_document_status(
-            dataset=dataset,
-            document_ids=[missing_document_id],
-            action="enable",
-            user=user,
-        )
-
-        # Assert
-        patched_dependencies["redis_client"].get.assert_not_called()
-        patched_dependencies["redis_client"].setex.assert_not_called()
-        patched_dependencies["add_task"].delay.assert_not_called()
-
-    def test_batch_update_mixed_document_states_and_actions(self, db_session_with_containers, patched_dependencies):
-        """Process only the applicable document in a mixed-state enable batch."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        disabled_doc = DocumentBatchUpdateIntegrationDataFactory.create_document(dataset=dataset, enabled=False)
-        enabled_doc = DocumentBatchUpdateIntegrationDataFactory.create_document(
-            dataset=dataset,
-            enabled=True,
-            position=2,
-        )
-        archived_doc = DocumentBatchUpdateIntegrationDataFactory.create_document(
-            dataset=dataset,
-            enabled=True,
-            archived=True,
-            position=3,
-        )
-        document_ids = [disabled_doc.id, enabled_doc.id, archived_doc.id]
-
-        # Act
-        DocumentService.batch_update_document_status(
-            dataset=dataset,
-            document_ids=document_ids,
-            action="enable",
-            user=user,
-        )
-
-        # Assert
-        db.session.refresh(disabled_doc)
-        db.session.refresh(enabled_doc)
-        db.session.refresh(archived_doc)
-        self._assert_document_enabled(disabled_doc, FIXED_TIME)
-        assert enabled_doc.enabled is True
-        assert archived_doc.enabled is True
-
-        patched_dependencies["redis_client"].setex.assert_called_once_with(
-            f"document_{disabled_doc.id}_indexing",
-            600,
-            1,
-        )
-        patched_dependencies["add_task"].delay.assert_called_once_with(disabled_doc.id)
-
-    def test_batch_update_large_document_list_performance(self, db_session_with_containers, patched_dependencies):
-        """Handle large document lists with consistent updates and side effects."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        document_ids = [str(uuid4()) for _ in range(100)]
-        documents = DocumentBatchUpdateIntegrationDataFactory.create_multiple_documents(
-            dataset=dataset,
-            document_ids=document_ids,
-            enabled=False,
-        )
-
-        # Act
-        DocumentService.batch_update_document_status(
-            dataset=dataset,
-            document_ids=document_ids,
-            action="enable",
-            user=user,
-        )
-
-        # Assert
-        for document in documents:
-            db.session.refresh(document)
-            self._assert_document_enabled(document, FIXED_TIME)
-
-        assert patched_dependencies["redis_client"].setex.call_count == len(document_ids)
-        assert patched_dependencies["add_task"].delay.call_count == len(document_ids)
-
-        expected_setex_calls = [call(f"document_{doc_id}_indexing", 600, 1) for doc_id in document_ids]
-        expected_task_calls = [call(doc_id) for doc_id in document_ids]
-        patched_dependencies["redis_client"].setex.assert_has_calls(expected_setex_calls)
-        patched_dependencies["add_task"].delay.assert_has_calls(expected_task_calls)
-
-    def test_batch_update_mixed_document_states_complex_scenario(
-        self, db_session_with_containers, patched_dependencies
-    ):
-        """Process a complex mixed-state batch and update only eligible records."""
-        # Arrange
-        dataset = DocumentBatchUpdateIntegrationDataFactory.create_dataset()
-        user = DocumentBatchUpdateIntegrationDataFactory.create_user()
-        doc1 = DocumentBatchUpdateIntegrationDataFactory.create_document(dataset=dataset, enabled=False)
-        doc2 = DocumentBatchUpdateIntegrationDataFactory.create_document(dataset=dataset, enabled=True, position=2)
-        doc3 = DocumentBatchUpdateIntegrationDataFactory.create_document(dataset=dataset, enabled=True, position=3)
-        doc4 = DocumentBatchUpdateIntegrationDataFactory.create_document(dataset=dataset, enabled=True, position=4)
-        doc5 = DocumentBatchUpdateIntegrationDataFactory.create_document(
-            dataset=dataset,
-            enabled=True,
-            archived=True,
-            position=5,
-        )
-        missing_id = str(uuid4())
-
-        document_ids = [doc1.id, doc2.id, doc3.id, doc4.id, doc5.id, missing_id]
-
-        # Act
-        DocumentService.batch_update_document_status(
-            dataset=dataset,
-            document_ids=document_ids,
-            action="enable",
-            user=user,
-        )
-
-        # Assert
-        db.session.refresh(doc1)
-        db.session.refresh(doc2)
-        db.session.refresh(doc3)
-        db.session.refresh(doc4)
-        db.session.refresh(doc5)
-        self._assert_document_enabled(doc1, FIXED_TIME)
-        assert doc2.enabled is True
-        assert doc3.enabled is True
-        assert doc4.enabled is True
-        assert doc5.enabled is True
-
-        patched_dependencies["redis_client"].setex.assert_called_once_with(f"document_{doc1.id}_indexing", 600, 1)
-        patched_dependencies["add_task"].delay.assert_called_once_with(doc1.id)

api/tests/unit_tests/services/test_dataset_service_batch_update_document_status.py

@@ -1,10 +1,13 @@
 import datetime
-from unittest.mock import Mock, patch
+
+# Mock redis_client before importing dataset_service
+from unittest.mock import Mock, call, patch
 
 import pytest
 
 from models.dataset import Dataset, Document
 from services.dataset_service import DocumentService
+from services.errors.document import DocumentIndexingError
 from tests.unit_tests.conftest import redis_mock
 
 
@@ -45,6 +48,7 @@ class DocumentBatchUpdateTestDataFactory:
         document.indexing_status = indexing_status
         document.completed_at = completed_at or datetime.datetime.now()
 
+        # Set default values for optional fields
         document.disabled_at = None
         document.disabled_by = None
         document.archived_at = None
@@ -55,9 +59,32 @@ class DocumentBatchUpdateTestDataFactory:
             setattr(document, key, value)
         return document
 
+    @staticmethod
+    def create_multiple_documents(
+        document_ids: list[str], enabled: bool = True, archived: bool = False, indexing_status: str = "completed"
+    ) -> list[Mock]:
+        """Create multiple mock documents with specified attributes."""
+        documents = []
+        for doc_id in document_ids:
+            doc = DocumentBatchUpdateTestDataFactory.create_document_mock(
+                document_id=doc_id,
+                name=f"document_{doc_id}.pdf",
+                enabled=enabled,
+                archived=archived,
+                indexing_status=indexing_status,
+            )
+            documents.append(doc)
+        return documents
+
 
 class TestDatasetServiceBatchUpdateDocumentStatus:
-    """Unit tests for non-SQL path in DocumentService.batch_update_document_status."""
+    """
+    Comprehensive unit tests for DocumentService.batch_update_document_status method.
+
+    This test suite covers all supported actions (enable, disable, archive, un_archive),
+    error conditions, edge cases, and validates proper interaction with Redis cache,
+    database operations, and async task triggers.
+    """
 
     @pytest.fixture
     def mock_document_service_dependencies(self):
@@ -77,24 +104,697 @@ class TestDatasetServiceBatchUpdateDocumentStatus:
                 "current_time": current_time,
             }
 
+    @pytest.fixture
+    def mock_async_task_dependencies(self):
+        """Mock setup for async task dependencies."""
+        with (
+            patch("services.dataset_service.add_document_to_index_task") as mock_add_task,
+            patch("services.dataset_service.remove_document_from_index_task") as mock_remove_task,
+        ):
+            yield {"add_task": mock_add_task, "remove_task": mock_remove_task}
+
+    def _assert_document_enabled(self, document: Mock, user_id: str, current_time: datetime.datetime):
+        """Helper method to verify document was enabled correctly."""
+        assert document.enabled == True
+        assert document.disabled_at is None
+        assert document.disabled_by is None
+        assert document.updated_at == current_time
+
+    def _assert_document_disabled(self, document: Mock, user_id: str, current_time: datetime.datetime):
+        """Helper method to verify document was disabled correctly."""
+        assert document.enabled == False
+        assert document.disabled_at == current_time
+        assert document.disabled_by == user_id
+        assert document.updated_at == current_time
+
+    def _assert_document_archived(self, document: Mock, user_id: str, current_time: datetime.datetime):
+        """Helper method to verify document was archived correctly."""
+        assert document.archived == True
+        assert document.archived_at == current_time
+        assert document.archived_by == user_id
+        assert document.updated_at == current_time
+
+    def _assert_document_unarchived(self, document: Mock):
+        """Helper method to verify document was unarchived correctly."""
+        assert document.archived == False
+        assert document.archived_at is None
+        assert document.archived_by is None
+
+    def _assert_redis_cache_operations(self, document_ids: list[str], action: str = "setex"):
+        """Helper method to verify Redis cache operations."""
+        if action == "setex":
+            expected_calls = [call(f"document_{doc_id}_indexing", 600, 1) for doc_id in document_ids]
+            redis_mock.setex.assert_has_calls(expected_calls)
+        elif action == "get":
+            expected_calls = [call(f"document_{doc_id}_indexing") for doc_id in document_ids]
+            redis_mock.get.assert_has_calls(expected_calls)
+
+    def _assert_async_task_calls(self, mock_task, document_ids: list[str], task_type: str):
+        """Helper method to verify async task calls."""
+        expected_calls = [call(doc_id) for doc_id in document_ids]
+        if task_type in {"add", "remove"}:
+            mock_task.delay.assert_has_calls(expected_calls)
+
+    # ==================== Enable Document Tests ====================
+
+    def test_batch_update_enable_documents_success(
+        self, mock_document_service_dependencies, mock_async_task_dependencies
+    ):
+        """Test successful enabling of disabled documents."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create disabled documents
+        disabled_docs = DocumentBatchUpdateTestDataFactory.create_multiple_documents(["doc-1", "doc-2"], enabled=False)
+        mock_document_service_dependencies["get_document"].side_effect = disabled_docs
+
+        # Reset module-level Redis mock
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = None
+
+        # Call the method to enable documents
+        DocumentService.batch_update_document_status(
+            dataset=dataset, document_ids=["doc-1", "doc-2"], action="enable", user=user
+        )
+
+        # Verify document attributes were updated correctly
+        for doc in disabled_docs:
+            self._assert_document_enabled(doc, user.id, mock_document_service_dependencies["current_time"])
+
+        # Verify Redis cache operations
+        self._assert_redis_cache_operations(["doc-1", "doc-2"], "get")
+        self._assert_redis_cache_operations(["doc-1", "doc-2"], "setex")
+
+        # Verify async tasks were triggered for indexing
+        self._assert_async_task_calls(mock_async_task_dependencies["add_task"], ["doc-1", "doc-2"], "add")
+
+        # Verify database operations
+        mock_db = mock_document_service_dependencies["db_session"]
+        assert mock_db.add.call_count == 2
+        assert mock_db.commit.call_count == 1
+
+    def test_batch_update_enable_already_enabled_document_skipped(self, mock_document_service_dependencies):
+        """Test enabling documents that are already enabled."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create already enabled document
+        enabled_doc = DocumentBatchUpdateTestDataFactory.create_document_mock(enabled=True)
+        mock_document_service_dependencies["get_document"].return_value = enabled_doc
+
+        # Reset module-level Redis mock
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = None
+
+        # Attempt to enable already enabled document
+        DocumentService.batch_update_document_status(
+            dataset=dataset, document_ids=["doc-1"], action="enable", user=user
+        )
+
+        # Verify no database operations occurred (document was skipped)
+        mock_db = mock_document_service_dependencies["db_session"]
+        mock_db.commit.assert_not_called()
+
+        # Verify no Redis setex operations occurred (document was skipped)
+        redis_mock.setex.assert_not_called()
+
+    # ==================== Disable Document Tests ====================
+
+    def test_batch_update_disable_documents_success(
+        self, mock_document_service_dependencies, mock_async_task_dependencies
+    ):
+        """Test successful disabling of enabled and completed documents."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create enabled documents
+        enabled_docs = DocumentBatchUpdateTestDataFactory.create_multiple_documents(["doc-1", "doc-2"], enabled=True)
+        mock_document_service_dependencies["get_document"].side_effect = enabled_docs
+
+        # Reset module-level Redis mock
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = None
+
+        # Call the method to disable documents
+        DocumentService.batch_update_document_status(
+            dataset=dataset, document_ids=["doc-1", "doc-2"], action="disable", user=user
+        )
+
+        # Verify document attributes were updated correctly
+        for doc in enabled_docs:
+            self._assert_document_disabled(doc, user.id, mock_document_service_dependencies["current_time"])
+
+        # Verify Redis cache operations for indexing prevention
+        self._assert_redis_cache_operations(["doc-1", "doc-2"], "setex")
+
+        # Verify async tasks were triggered to remove from index
+        self._assert_async_task_calls(mock_async_task_dependencies["remove_task"], ["doc-1", "doc-2"], "remove")
+
+        # Verify database operations
+        mock_db = mock_document_service_dependencies["db_session"]
+        assert mock_db.add.call_count == 2
+        assert mock_db.commit.call_count == 1
+
+    def test_batch_update_disable_already_disabled_document_skipped(
+        self, mock_document_service_dependencies, mock_async_task_dependencies
+    ):
+        """Test disabling documents that are already disabled."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create already disabled document
+        disabled_doc = DocumentBatchUpdateTestDataFactory.create_document_mock(enabled=False)
+        mock_document_service_dependencies["get_document"].return_value = disabled_doc
+
+        # Reset module-level Redis mock
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = None
+
+        # Attempt to disable already disabled document
+        DocumentService.batch_update_document_status(
+            dataset=dataset, document_ids=["doc-1"], action="disable", user=user
+        )
+
+        # Verify no database operations occurred (document was skipped)
+        mock_db = mock_document_service_dependencies["db_session"]
+        mock_db.commit.assert_not_called()
+
+        # Verify no Redis setex operations occurred (document was skipped)
+        redis_mock.setex.assert_not_called()
+
+        # Verify no async tasks were triggered (document was skipped)
+        mock_async_task_dependencies["add_task"].delay.assert_not_called()
+
+    def test_batch_update_disable_non_completed_document_error(self, mock_document_service_dependencies):
+        """Test that DocumentIndexingError is raised when trying to disable non-completed documents."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create a document that's not completed
+        non_completed_doc = DocumentBatchUpdateTestDataFactory.create_document_mock(
+            enabled=True,
+            indexing_status="indexing",  # Not completed
+            completed_at=None,  # Not completed
+        )
+        mock_document_service_dependencies["get_document"].return_value = non_completed_doc
+
+        # Verify that DocumentIndexingError is raised
+        with pytest.raises(DocumentIndexingError) as exc_info:
+            DocumentService.batch_update_document_status(
+                dataset=dataset, document_ids=["doc-1"], action="disable", user=user
+            )
+
+        # Verify error message indicates document is not completed
+        assert "is not completed" in str(exc_info.value)
+
+    # ==================== Archive Document Tests ====================
+
+    def test_batch_update_archive_documents_success(
+        self, mock_document_service_dependencies, mock_async_task_dependencies
+    ):
+        """Test successful archiving of unarchived documents."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create unarchived enabled document
+        unarchived_doc = DocumentBatchUpdateTestDataFactory.create_document_mock(enabled=True, archived=False)
+        mock_document_service_dependencies["get_document"].return_value = unarchived_doc
+
+        # Reset module-level Redis mock
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = None
+
+        # Call the method to archive documents
+        DocumentService.batch_update_document_status(
+            dataset=dataset, document_ids=["doc-1"], action="archive", user=user
+        )
+
+        # Verify document attributes were updated correctly
+        self._assert_document_archived(unarchived_doc, user.id, mock_document_service_dependencies["current_time"])
+
+        # Verify Redis cache was set (because document was enabled)
+        redis_mock.setex.assert_called_once_with("document_doc-1_indexing", 600, 1)
+
+        # Verify async task was triggered to remove from index (because enabled)
+        mock_async_task_dependencies["remove_task"].delay.assert_called_once_with("doc-1")
+
+        # Verify database operations
+        mock_db = mock_document_service_dependencies["db_session"]
+        mock_db.add.assert_called_once()
+        mock_db.commit.assert_called_once()
+
+    def test_batch_update_archive_already_archived_document_skipped(self, mock_document_service_dependencies):
+        """Test archiving documents that are already archived."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create already archived document
+        archived_doc = DocumentBatchUpdateTestDataFactory.create_document_mock(enabled=True, archived=True)
+        mock_document_service_dependencies["get_document"].return_value = archived_doc
+
+        # Reset module-level Redis mock
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = None
+
+        # Attempt to archive already archived document
+        DocumentService.batch_update_document_status(
+            dataset=dataset, document_ids=["doc-3"], action="archive", user=user
+        )
+
+        # Verify no database operations occurred (document was skipped)
+        mock_db = mock_document_service_dependencies["db_session"]
+        mock_db.commit.assert_not_called()
+
+        # Verify no Redis setex operations occurred (document was skipped)
+        redis_mock.setex.assert_not_called()
+
+    def test_batch_update_archive_disabled_document_no_index_removal(
+        self, mock_document_service_dependencies, mock_async_task_dependencies
+    ):
+        """Test archiving disabled documents (should not trigger index removal)."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Set up disabled, unarchived document
+        disabled_unarchived_doc = DocumentBatchUpdateTestDataFactory.create_document_mock(enabled=False, archived=False)
+        mock_document_service_dependencies["get_document"].return_value = disabled_unarchived_doc
+
+        # Reset module-level Redis mock
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = None
+
+        # Archive the disabled document
+        DocumentService.batch_update_document_status(
+            dataset=dataset, document_ids=["doc-1"], action="archive", user=user
+        )
+
+        # Verify document was archived
+        self._assert_document_archived(
+            disabled_unarchived_doc, user.id, mock_document_service_dependencies["current_time"]
+        )
+
+        # Verify no Redis cache was set (document is disabled)
+        redis_mock.setex.assert_not_called()
+
+        # Verify no index removal task was triggered (document is disabled)
+        mock_async_task_dependencies["remove_task"].delay.assert_not_called()
+
+        # Verify database operations still occurred
+        mock_db = mock_document_service_dependencies["db_session"]
+        mock_db.add.assert_called_once()
+        mock_db.commit.assert_called_once()
+
+    # ==================== Unarchive Document Tests ====================
+
+    def test_batch_update_unarchive_documents_success(
+        self, mock_document_service_dependencies, mock_async_task_dependencies
+    ):
+        """Test successful unarchiving of archived documents."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create mock archived document
+        archived_doc = DocumentBatchUpdateTestDataFactory.create_document_mock(enabled=True, archived=True)
+        mock_document_service_dependencies["get_document"].return_value = archived_doc
+
+        # Reset module-level Redis mock
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = None
+
+        # Call the method to unarchive documents
+        DocumentService.batch_update_document_status(
+            dataset=dataset, document_ids=["doc-1"], action="un_archive", user=user
+        )
+
+        # Verify document attributes were updated correctly
+        self._assert_document_unarchived(archived_doc)
+        assert archived_doc.updated_at == mock_document_service_dependencies["current_time"]
+
+        # Verify Redis cache was set (because document is enabled)
+        redis_mock.setex.assert_called_once_with("document_doc-1_indexing", 600, 1)
+
+        # Verify async task was triggered to add back to index (because enabled)
+        mock_async_task_dependencies["add_task"].delay.assert_called_once_with("doc-1")
+
+        # Verify database operations
+        mock_db = mock_document_service_dependencies["db_session"]
+        mock_db.add.assert_called_once()
+        mock_db.commit.assert_called_once()
+
+    def test_batch_update_unarchive_already_unarchived_document_skipped(
+        self, mock_document_service_dependencies, mock_async_task_dependencies
+    ):
+        """Test unarchiving documents that are already unarchived."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create already unarchived document
+        unarchived_doc = DocumentBatchUpdateTestDataFactory.create_document_mock(enabled=True, archived=False)
+        mock_document_service_dependencies["get_document"].return_value = unarchived_doc
+
+        # Reset module-level Redis mock
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = None
+
+        # Attempt to unarchive already unarchived document
+        DocumentService.batch_update_document_status(
+            dataset=dataset, document_ids=["doc-1"], action="un_archive", user=user
+        )
+
+        # Verify no database operations occurred (document was skipped)
+        mock_db = mock_document_service_dependencies["db_session"]
+        mock_db.commit.assert_not_called()
+
+        # Verify no Redis setex operations occurred (document was skipped)
+        redis_mock.setex.assert_not_called()
+
+        # Verify no async tasks were triggered (document was skipped)
+        mock_async_task_dependencies["add_task"].delay.assert_not_called()
+
+    def test_batch_update_unarchive_disabled_document_no_index_addition(
+        self, mock_document_service_dependencies, mock_async_task_dependencies
+    ):
+        """Test unarchiving disabled documents (should not trigger index addition)."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create mock archived but disabled document
+        archived_disabled_doc = DocumentBatchUpdateTestDataFactory.create_document_mock(enabled=False, archived=True)
+        mock_document_service_dependencies["get_document"].return_value = archived_disabled_doc
+
+        # Reset module-level Redis mock
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = None
+
+        # Unarchive the disabled document
+        DocumentService.batch_update_document_status(
+            dataset=dataset, document_ids=["doc-1"], action="un_archive", user=user
+        )
+
+        # Verify document was unarchived
+        self._assert_document_unarchived(archived_disabled_doc)
+        assert archived_disabled_doc.updated_at == mock_document_service_dependencies["current_time"]
+
+        # Verify no Redis cache was set (document is disabled)
+        redis_mock.setex.assert_not_called()
+
+        # Verify no index addition task was triggered (document is disabled)
+        mock_async_task_dependencies["add_task"].delay.assert_not_called()
+
+        # Verify database operations still occurred
+        mock_db = mock_document_service_dependencies["db_session"]
+        mock_db.add.assert_called_once()
+        mock_db.commit.assert_called_once()
+
+    # ==================== Error Handling Tests ====================
+
+    def test_batch_update_document_indexing_error_redis_cache_hit(self, mock_document_service_dependencies):
+        """Test that DocumentIndexingError is raised when documents are currently being indexed."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create mock enabled document
+        enabled_doc = DocumentBatchUpdateTestDataFactory.create_document_mock(enabled=True)
+        mock_document_service_dependencies["get_document"].return_value = enabled_doc
+
+        # Set up mock to indicate document is being indexed
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = "indexing"
+
+        # Verify that DocumentIndexingError is raised
+        with pytest.raises(DocumentIndexingError) as exc_info:
+            DocumentService.batch_update_document_status(
+                dataset=dataset, document_ids=["doc-1"], action="enable", user=user
+            )
+
+        # Verify error message contains document name
+        assert "test_document.pdf" in str(exc_info.value)
+        assert "is being indexed" in str(exc_info.value)
+
+        # Verify Redis cache was checked
+        redis_mock.get.assert_called_once_with("document_doc-1_indexing")
+
     def test_batch_update_invalid_action_error(self, mock_document_service_dependencies):
         """Test that ValueError is raised when an invalid action is provided."""
         dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
         user = DocumentBatchUpdateTestDataFactory.create_user_mock()
 
+        # Create mock document
         doc = DocumentBatchUpdateTestDataFactory.create_document_mock(enabled=True)
         mock_document_service_dependencies["get_document"].return_value = doc
 
+        # Reset module-level Redis mock
         redis_mock.reset_mock()
         redis_mock.get.return_value = None
 
+        # Test with invalid action
         invalid_action = "invalid_action"
         with pytest.raises(ValueError) as exc_info:
             DocumentService.batch_update_document_status(
                 dataset=dataset, document_ids=["doc-1"], action=invalid_action, user=user
             )
 
+        # Verify error message contains the invalid action
         assert invalid_action in str(exc_info.value)
         assert "Invalid action" in str(exc_info.value)
 
+        # Verify no Redis operations occurred
         redis_mock.setex.assert_not_called()
+
+    def test_batch_update_async_task_error_handling(
+        self, mock_document_service_dependencies, mock_async_task_dependencies
+    ):
+        """Test handling of async task errors during batch operations."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create mock disabled document
+        disabled_doc = DocumentBatchUpdateTestDataFactory.create_document_mock(enabled=False)
+        mock_document_service_dependencies["get_document"].return_value = disabled_doc
+
+        # Mock async task to raise an exception
+        mock_async_task_dependencies["add_task"].delay.side_effect = Exception("Celery task error")
+
+        # Reset module-level Redis mock
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = None
+
+        # Verify that async task error is propagated
+        with pytest.raises(Exception) as exc_info:
+            DocumentService.batch_update_document_status(
+                dataset=dataset, document_ids=["doc-1"], action="enable", user=user
+            )
+
+        # Verify error message
+        assert "Celery task error" in str(exc_info.value)
+
+        # Verify database operations completed successfully
+        mock_db = mock_document_service_dependencies["db_session"]
+        mock_db.add.assert_called_once()
+        mock_db.commit.assert_called_once()
+
+        # Verify Redis cache was set successfully
+        redis_mock.setex.assert_called_once_with("document_doc-1_indexing", 600, 1)
+
+        # Verify document was updated
+        self._assert_document_enabled(disabled_doc, user.id, mock_document_service_dependencies["current_time"])
+
+    # ==================== Edge Case Tests ====================
+
+    def test_batch_update_empty_document_list(self, mock_document_service_dependencies):
+        """Test batch operations with an empty document ID list."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Call method with empty document list
+        result = DocumentService.batch_update_document_status(
+            dataset=dataset, document_ids=[], action="enable", user=user
+        )
+
+        # Verify no document lookups were performed
+        mock_document_service_dependencies["get_document"].assert_not_called()
+
+        # Verify method returns None (early return)
+        assert result is None
+
+    def test_batch_update_document_not_found_skipped(self, mock_document_service_dependencies):
+        """Test behavior when some documents don't exist in the database."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Mock document service to return None (document not found)
+        mock_document_service_dependencies["get_document"].return_value = None
+
+        # Call method with non-existent document ID
+        # This should not raise an error, just skip the missing document
+        try:
+            DocumentService.batch_update_document_status(
+                dataset=dataset, document_ids=["non-existent-doc"], action="enable", user=user
+            )
+        except Exception as e:
+            pytest.fail(f"Method should not raise exception for missing documents: {e}")
+
+        # Verify document lookup was attempted
+        mock_document_service_dependencies["get_document"].assert_called_once_with(dataset.id, "non-existent-doc")
+
+    def test_batch_update_mixed_document_states_and_actions(
+        self, mock_document_service_dependencies, mock_async_task_dependencies
+    ):
+        """Test batch operations on documents with mixed states and various scenarios."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create documents in various states
+        disabled_doc = DocumentBatchUpdateTestDataFactory.create_document_mock("doc-1", enabled=False)
+        enabled_doc = DocumentBatchUpdateTestDataFactory.create_document_mock("doc-2", enabled=True)
+        archived_doc = DocumentBatchUpdateTestDataFactory.create_document_mock("doc-3", enabled=True, archived=True)
+
+        # Mix of different document states
+        documents = [disabled_doc, enabled_doc, archived_doc]
+        mock_document_service_dependencies["get_document"].side_effect = documents
+
+        # Reset module-level Redis mock
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = None
+
+        # Perform enable operation on mixed state documents
+        DocumentService.batch_update_document_status(
+            dataset=dataset, document_ids=["doc-1", "doc-2", "doc-3"], action="enable", user=user
+        )
+
+        # Verify only the disabled document was processed
+        # (enabled and archived documents should be skipped for enable action)
+
+        # Only one add should occur (for the disabled document that was enabled)
+        mock_db = mock_document_service_dependencies["db_session"]
+        mock_db.add.assert_called_once()
+        # Only one commit should occur
+        mock_db.commit.assert_called_once()
+
+        # Only one Redis setex should occur (for the document that was enabled)
+        redis_mock.setex.assert_called_once_with("document_doc-1_indexing", 600, 1)
+
+        # Only one async task should be triggered (for the document that was enabled)
+        mock_async_task_dependencies["add_task"].delay.assert_called_once_with("doc-1")
+
+    # ==================== Performance Tests ====================
+
+    def test_batch_update_large_document_list_performance(
+        self, mock_document_service_dependencies, mock_async_task_dependencies
+    ):
+        """Test batch operations with a large number of documents."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create large list of document IDs
+        document_ids = [f"doc-{i}" for i in range(1, 101)]  # 100 documents
+
+        # Create mock documents
+        mock_documents = DocumentBatchUpdateTestDataFactory.create_multiple_documents(
+            document_ids,
+            enabled=False,  # All disabled, will be enabled
+        )
+        mock_document_service_dependencies["get_document"].side_effect = mock_documents
+
+        # Reset module-level Redis mock
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = None
+
+        # Perform batch enable operation
+        DocumentService.batch_update_document_status(
+            dataset=dataset, document_ids=document_ids, action="enable", user=user
+        )
+
+        # Verify all documents were processed
+        assert mock_document_service_dependencies["get_document"].call_count == 100
+
+        # Verify all documents were updated
+        for mock_doc in mock_documents:
+            self._assert_document_enabled(mock_doc, user.id, mock_document_service_dependencies["current_time"])
+
+        # Verify database operations
+        mock_db = mock_document_service_dependencies["db_session"]
+        assert mock_db.add.call_count == 100
+        assert mock_db.commit.call_count == 1
+
+        # Verify Redis cache operations occurred for each document
+        assert redis_mock.setex.call_count == 100
+
+        # Verify async tasks were triggered for each document
+        assert mock_async_task_dependencies["add_task"].delay.call_count == 100
+
+        # Verify correct Redis cache keys were set
+        expected_redis_calls = [call(f"document_doc-{i}_indexing", 600, 1) for i in range(1, 101)]
+        redis_mock.setex.assert_has_calls(expected_redis_calls)
+
+        # Verify correct async task calls
+        expected_task_calls = [call(f"doc-{i}") for i in range(1, 101)]
+        mock_async_task_dependencies["add_task"].delay.assert_has_calls(expected_task_calls)
+
+    def test_batch_update_mixed_document_states_complex_scenario(
+        self, mock_document_service_dependencies, mock_async_task_dependencies
+    ):
+        """Test complex batch operations with documents in various states."""
+        dataset = DocumentBatchUpdateTestDataFactory.create_dataset_mock()
+        user = DocumentBatchUpdateTestDataFactory.create_user_mock()
+
+        # Create documents in various states
+        doc1 = DocumentBatchUpdateTestDataFactory.create_document_mock("doc-1", enabled=False)  # Will be enabled
+        doc2 = DocumentBatchUpdateTestDataFactory.create_document_mock(
+            "doc-2", enabled=True
+        )  # Already enabled, will be skipped
+        doc3 = DocumentBatchUpdateTestDataFactory.create_document_mock(
+            "doc-3", enabled=True
+        )  # Already enabled, will be skipped
+        doc4 = DocumentBatchUpdateTestDataFactory.create_document_mock(
+            "doc-4", enabled=True
+        )  # Not affected by enable action
+        doc5 = DocumentBatchUpdateTestDataFactory.create_document_mock(
+            "doc-5", enabled=True, archived=True
+        )  # Not affected by enable action
+        doc6 = None  # Non-existent, will be skipped
+
+        mock_document_service_dependencies["get_document"].side_effect = [doc1, doc2, doc3, doc4, doc5, doc6]
+
+        # Reset module-level Redis mock
+        redis_mock.reset_mock()
+        redis_mock.get.return_value = None
+
+        # Perform mixed batch operations
+        DocumentService.batch_update_document_status(
+            dataset=dataset,
+            document_ids=["doc-1", "doc-2", "doc-3", "doc-4", "doc-5", "doc-6"],
+            action="enable",  # This will only affect doc1
+            user=user,
+        )
+
+        # Verify document 1 was enabled
+        self._assert_document_enabled(doc1, user.id, mock_document_service_dependencies["current_time"])
+
+        # Verify other documents were skipped appropriately
+        assert doc2.enabled == True  # No change
+        assert doc3.enabled == True  # No change
+        assert doc4.enabled == True  # No change
+        assert doc5.enabled == True  # No change
+
+        # Verify database commits occurred for processed documents
+        # Only doc1 should be added (others were skipped, doc6 doesn't exist)
+        mock_db = mock_document_service_dependencies["db_session"]
+        assert mock_db.add.call_count == 1
+        assert mock_db.commit.call_count == 1
+
+        # Verify Redis cache operations occurred for processed documents
+        # Only doc1 should have Redis operations
+        assert redis_mock.setex.call_count == 1
+
+        # Verify async tasks were triggered for processed documents
+        # Only doc1 should trigger tasks
+        assert mock_async_task_dependencies["add_task"].delay.call_count == 1
+
+        # Verify correct Redis cache keys were set
+        expected_redis_calls = [call("document_doc-1_indexing", 600, 1)]
+        redis_mock.setex.assert_has_calls(expected_redis_calls)
+
+        # Verify correct async task calls
+        expected_task_calls = [call("doc-1")]
+        mock_async_task_dependencies["add_task"].delay.assert_has_calls(expected_task_calls)

web/.nvmrc

@@ -1 +1 @@
-22
+24

web/Dockerfile

@@ -1,5 +1,5 @@
 # base image
-FROM node:22-alpine AS base
+FROM node:24-alpine AS base
 LABEL maintainer="takatost@gmail.com"
 
 # if you located in China, you can use aliyun mirror to speed up

web/__tests__/apps/app-list-browsing-flow.test.tsx

@@ -8,11 +8,11 @@
  */
 import type { AppListResponse } from '@/models/app'
 import type { App } from '@/types/app'
-import { fireEvent, screen } from '@testing-library/react'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import List from '@/app/components/apps/list'
 import { AccessMode } from '@/models/access-control'
-import { renderWithNuqs } from '@/test/nuqs-testing'
 import { AppModeEnum } from '@/types/app'
 
 let mockIsCurrentWorkspaceEditor = true
@@ -161,9 +161,10 @@ const createPage = (apps: App[], hasMore = false, page = 1): AppListResponse =>
 })
 
 const renderList = (searchParams?: Record<string, string>) => {
-  return renderWithNuqs(
-    <List controlRefreshList={0} />,
-    { searchParams },
+  return render(
+    <NuqsTestingAdapter searchParams={searchParams}>
+      <List controlRefreshList={0} />
+    </NuqsTestingAdapter>,
   )
 }
 
@@ -208,7 +209,11 @@ describe('App List Browsing Flow', () => {
 
     it('should transition from loading to content when data loads', () => {
       mockIsLoading = true
-      const { rerender } = renderWithNuqs(<List controlRefreshList={0} />)
+      const { rerender } = render(
+        <NuqsTestingAdapter>
+          <List controlRefreshList={0} />
+        </NuqsTestingAdapter>,
+      )
 
       const skeletonCards = document.querySelectorAll('.animate-pulse')
       expect(skeletonCards.length).toBeGreaterThan(0)
@@ -219,7 +224,11 @@ describe('App List Browsing Flow', () => {
         createMockApp({ id: 'app-1', name: 'Loaded App' }),
       ])]
 
-      rerender(<List controlRefreshList={0} />)
+      rerender(
+        <NuqsTestingAdapter>
+          <List controlRefreshList={0} />
+        </NuqsTestingAdapter>,
+      )
 
       expect(screen.getByText('Loaded App')).toBeInTheDocument()
     })
@@ -415,9 +424,17 @@ describe('App List Browsing Flow', () => {
     it('should call refetch when controlRefreshList increments', () => {
       mockPages = [createPage([createMockApp()])]
 
-      const { rerender } = renderWithNuqs(<List controlRefreshList={0} />)
+      const { rerender } = render(
+        <NuqsTestingAdapter>
+          <List controlRefreshList={0} />
+        </NuqsTestingAdapter>,
+      )
 
-      rerender(<List controlRefreshList={1} />)
+      rerender(
+        <NuqsTestingAdapter>
+          <List controlRefreshList={1} />
+        </NuqsTestingAdapter>,
+      )
 
       expect(mockRefetch).toHaveBeenCalled()
     })

web/__tests__/apps/create-app-flow.test.tsx

@@ -9,11 +9,11 @@
  */
 import type { AppListResponse } from '@/models/app'
 import type { App } from '@/types/app'
-import { fireEvent, screen, waitFor } from '@testing-library/react'
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import List from '@/app/components/apps/list'
 import { AccessMode } from '@/models/access-control'
-import { renderWithNuqs } from '@/test/nuqs-testing'
 import { AppModeEnum } from '@/types/app'
 
 let mockIsCurrentWorkspaceEditor = true
@@ -214,7 +214,11 @@ const createPage = (apps: App[]): AppListResponse => ({
 })
 
 const renderList = () => {
-  return renderWithNuqs(<List controlRefreshList={0} />)
+  return render(
+    <NuqsTestingAdapter>
+      <List controlRefreshList={0} />
+    </NuqsTestingAdapter>,
+  )
 }
 
 describe('Create App Flow', () => {

web/__tests__/datasets/document-management.test.tsx

@@ -7,10 +7,9 @@
  */
 
 import type { SimpleDocumentDetail } from '@/models/datasets'
-import { act, renderHook, waitFor } from '@testing-library/react'
+import { act, renderHook } from '@testing-library/react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { DataSourceType } from '@/models/datasets'
-import { renderHookWithNuqs } from '@/test/nuqs-testing'
 
 const mockPush = vi.fn()
 vi.mock('next/navigation', () => ({
@@ -29,16 +28,12 @@ const { useDocumentSort } = await import(
 const { useDocumentSelection } = await import(
   '@/app/components/datasets/documents/components/document-list/hooks/use-document-selection',
 )
-const { useDocumentListQueryState } = await import(
+const { default: useDocumentListQueryState } = await import(
   '@/app/components/datasets/documents/hooks/use-document-list-query-state',
 )
 
 type LocalDoc = SimpleDocumentDetail & { percent?: number }
 
-const renderQueryStateHook = (searchParams = '') => {
-  return renderHookWithNuqs(() => useDocumentListQueryState(), { searchParams })
-}
-
 const createDoc = (overrides?: Partial<LocalDoc>): LocalDoc => ({
   id: `doc-${Math.random().toString(36).slice(2, 8)}`,
   name: 'test-doc.txt',
@@ -90,7 +85,7 @@ describe('Document Management Flow', () => {
 
   describe('URL-based Query State', () => {
     it('should parse default query from empty URL params', () => {
-      const { result } = renderQueryStateHook()
+      const { result } = renderHook(() => useDocumentListQueryState())
 
       expect(result.current.query).toEqual({
         page: 1,
@@ -101,85 +96,107 @@ describe('Document Management Flow', () => {
       })
     })
 
-    it('should update keyword query with replace history', async () => {
-      const { result, onUrlUpdate } = renderQueryStateHook()
+    it('should update query and push to router', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
 
       act(() => {
         result.current.updateQuery({ keyword: 'test', page: 2 })
       })
 
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.options.history).toBe('replace')
-      expect(update.searchParams.get('keyword')).toBe('test')
-      expect(update.searchParams.get('page')).toBe('2')
+      expect(mockPush).toHaveBeenCalled()
+      // The push call should contain the updated query params
+      const pushUrl = mockPush.mock.calls[0][0] as string
+      expect(pushUrl).toContain('keyword=test')
+      expect(pushUrl).toContain('page=2')
     })
 
-    it('should reset query to defaults', async () => {
-      const { result, onUrlUpdate } = renderQueryStateHook()
+    it('should reset query to defaults', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
 
       act(() => {
         result.current.resetQuery()
       })
 
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.options.history).toBe('replace')
-      expect(update.searchParams.toString()).toBe('')
+      expect(mockPush).toHaveBeenCalled()
+      // Default query omits default values from URL
+      const pushUrl = mockPush.mock.calls[0][0] as string
+      expect(pushUrl).toBe('/datasets/ds-1/documents')
     })
   })
 
   describe('Document Sort Integration', () => {
-    it('should derive sort field and order from remote sort value', () => {
+    it('should return documents unsorted when no sort field set', () => {
+      const docs = [
+        createDoc({ id: 'doc-1', name: 'Banana.txt', word_count: 300 }),
+        createDoc({ id: 'doc-2', name: 'Apple.txt', word_count: 100 }),
+        createDoc({ id: 'doc-3', name: 'Cherry.txt', word_count: 200 }),
+      ]
+
       const { result } = renderHook(() => useDocumentSort({
+        documents: docs,
+        statusFilterValue: '',
         remoteSortValue: '-created_at',
-        onRemoteSortChange: vi.fn(),
       }))
 
-      expect(result.current.sortField).toBe('created_at')
+      expect(result.current.sortField).toBeNull()
+      expect(result.current.sortedDocuments).toHaveLength(3)
+    })
+
+    it('should sort by name descending', () => {
+      const docs = [
+        createDoc({ id: 'doc-1', name: 'Banana.txt' }),
+        createDoc({ id: 'doc-2', name: 'Apple.txt' }),
+        createDoc({ id: 'doc-3', name: 'Cherry.txt' }),
+      ]
+
+      const { result } = renderHook(() => useDocumentSort({
+        documents: docs,
+        statusFilterValue: '',
+        remoteSortValue: '-created_at',
+      }))
+
+      act(() => {
+        result.current.handleSort('name')
+      })
+
+      expect(result.current.sortField).toBe('name')
       expect(result.current.sortOrder).toBe('desc')
+      const names = result.current.sortedDocuments.map(d => d.name)
+      expect(names).toEqual(['Cherry.txt', 'Banana.txt', 'Apple.txt'])
     })
 
-    it('should call remote sort change with descending sort for a new field', () => {
-      const onRemoteSortChange = vi.fn()
+    it('should toggle sort order on same field click', () => {
+      const docs = [createDoc({ id: 'doc-1', name: 'A.txt' }), createDoc({ id: 'doc-2', name: 'B.txt' })]
+
       const { result } = renderHook(() => useDocumentSort({
+        documents: docs,
+        statusFilterValue: '',
         remoteSortValue: '-created_at',
-        onRemoteSortChange,
       }))
 
-      act(() => {
-        result.current.handleSort('hit_count')
-      })
+      act(() => result.current.handleSort('name'))
+      expect(result.current.sortOrder).toBe('desc')
 
-      expect(onRemoteSortChange).toHaveBeenCalledWith('-hit_count')
+      act(() => result.current.handleSort('name'))
+      expect(result.current.sortOrder).toBe('asc')
     })
 
-    it('should toggle descending to ascending when clicking active field', () => {
-      const onRemoteSortChange = vi.fn()
-      const { result } = renderHook(() => useDocumentSort({
-        remoteSortValue: '-hit_count',
-        onRemoteSortChange,
-      }))
+    it('should filter by status before sorting', () => {
+      const docs = [
+        createDoc({ id: 'doc-1', name: 'A.txt', display_status: 'available' }),
+        createDoc({ id: 'doc-2', name: 'B.txt', display_status: 'error' }),
+        createDoc({ id: 'doc-3', name: 'C.txt', display_status: 'available' }),
+      ]
 
-      act(() => {
-        result.current.handleSort('hit_count')
-      })
-
-      expect(onRemoteSortChange).toHaveBeenCalledWith('hit_count')
-    })
-
-    it('should ignore null sort field updates', () => {
-      const onRemoteSortChange = vi.fn()
       const { result } = renderHook(() => useDocumentSort({
+        documents: docs,
+        statusFilterValue: 'available',
         remoteSortValue: '-created_at',
-        onRemoteSortChange,
       }))
 
-      act(() => {
-        result.current.handleSort(null)
-      })
-
-      expect(onRemoteSortChange).not.toHaveBeenCalled()
+      // Only 'available' documents should remain
+      expect(result.current.sortedDocuments).toHaveLength(2)
+      expect(result.current.sortedDocuments.every(d => d.display_status === 'available')).toBe(true)
     })
   })
 
@@ -292,13 +309,14 @@ describe('Document Management Flow', () => {
   describe('Cross-Module: Query State → Sort → Selection Pipeline', () => {
     it('should maintain consistent default state across all hooks', () => {
       const docs = [createDoc({ id: 'doc-1' })]
-      const { result: queryResult } = renderQueryStateHook()
+      const { result: queryResult } = renderHook(() => useDocumentListQueryState())
       const { result: sortResult } = renderHook(() => useDocumentSort({
+        documents: docs,
+        statusFilterValue: queryResult.current.query.status,
         remoteSortValue: queryResult.current.query.sort,
-        onRemoteSortChange: vi.fn(),
       }))
       const { result: selResult } = renderHook(() => useDocumentSelection({
-        documents: docs,
+        documents: sortResult.current.sortedDocuments,
         selectedIds: [],
         onSelectedIdChange: vi.fn(),
       }))
@@ -307,9 +325,8 @@ describe('Document Management Flow', () => {
       expect(queryResult.current.query.sort).toBe('-created_at')
       expect(queryResult.current.query.status).toBe('all')
 
-      // Sort state is derived from URL default sort.
-      expect(sortResult.current.sortField).toBe('created_at')
-      expect(sortResult.current.sortOrder).toBe('desc')
+      // Sort inherits 'all' status → no filtering applied
+      expect(sortResult.current.sortedDocuments).toHaveLength(1)
 
       // Selection starts empty
       expect(selResult.current.isAllSelected).toBe(false)

web/__tests__/tools/tool-browsing-and-filtering.test.tsx

@@ -28,13 +28,9 @@ vi.mock('react-i18next', () => ({
   }),
 }))
 
-vi.mock('nuqs', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('nuqs')>()
-  return {
-    ...actual,
-    useQueryState: () => ['builtin', vi.fn()],
-  }
-})
+vi.mock('nuqs', () => ({
+  useQueryState: () => ['builtin', vi.fn()],
+}))
 
 vi.mock('@/context/global-public-context', () => ({
   useGlobalPublicStore: () => ({ enable_marketplace: false }),
@@ -216,12 +212,6 @@ vi.mock('@/app/components/tools/marketplace', () => ({
   default: () => null,
 }))
 
-vi.mock('@/app/components/tools/marketplace/hooks', () => ({
-  useMarketplace: () => ({
-    handleScroll: vi.fn(),
-  }),
-}))
-
 vi.mock('@/app/components/tools/mcp', () => ({
   default: () => <div data-testid="mcp-list">MCP List</div>,
 }))

web/app/components/apps/__tests__/list.spec.tsx

@@ -1,7 +1,9 @@
-import { act, fireEvent, screen } from '@testing-library/react'
+import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
+import type { ReactNode } from 'react'
+import { act, fireEvent, render, screen } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import * as React from 'react'
 import { useStore as useTagStore } from '@/app/components/base/tag-management/store'
-import { renderWithNuqs } from '@/test/nuqs-testing'
 import { AppModeEnum } from '@/types/app'
 
 import List from '../list'
@@ -184,14 +186,21 @@ beforeAll(() => {
   } as unknown as typeof IntersectionObserver
 })
 
-// Render helper wrapping with shared nuqs testing helper.
+// Render helper wrapping with NuqsTestingAdapter
+const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
 const renderList = (searchParams = '') => {
-  return renderWithNuqs(<List />, { searchParams })
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={onUrlUpdate}>
+      {children}
+    </NuqsTestingAdapter>
+  )
+  return render(<List />, { wrapper })
 }
 
 describe('List', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    onUrlUpdate.mockClear()
     useTagStore.setState({
       tagList: [{ id: 'tag-1', name: 'Test Tag', type: 'app', binding_count: 0 }],
       showTagManagementModal: false,
@@ -268,7 +277,7 @@ describe('List', () => {
 
   describe('Tab Navigation', () => {
     it('should update URL when workflow tab is clicked', async () => {
-      const { onUrlUpdate } = renderList()
+      renderList()
 
       fireEvent.click(screen.getByText('app.types.workflow'))
 
@@ -278,7 +287,7 @@ describe('List', () => {
     })
 
     it('should update URL when all tab is clicked', async () => {
-      const { onUrlUpdate } = renderList('?category=workflow')
+      renderList('?category=workflow')
 
       fireEvent.click(screen.getByText('app.types.all'))
 
@@ -382,10 +391,18 @@ describe('List', () => {
 
   describe('Edge Cases', () => {
     it('should handle multiple renders without issues', () => {
-      const { rerender } = renderWithNuqs(<List />)
+      const { rerender } = render(
+        <NuqsTestingAdapter>
+          <List />
+        </NuqsTestingAdapter>,
+      )
       expect(screen.getByText('app.types.all')).toBeInTheDocument()
 
-      rerender(<List />)
+      rerender(
+        <NuqsTestingAdapter>
+          <List />
+        </NuqsTestingAdapter>,
+      )
       expect(screen.getByText('app.types.all')).toBeInTheDocument()
     })
 
@@ -431,7 +448,7 @@ describe('List', () => {
     })
 
     it('should update URL for each app type tab click', async () => {
-      const { onUrlUpdate } = renderList()
+      renderList()
 
       const appTypeTexts = [
         { mode: AppModeEnum.WORKFLOW, text: 'app.types.workflow' },

web/app/components/apps/hooks/__tests__/use-apps-query-state.spec.tsx

@@ -1,9 +1,18 @@
-import { act, waitFor } from '@testing-library/react'
-import { renderHookWithNuqs } from '@/test/nuqs-testing'
+import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
+import type { ReactNode } from 'react'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import useAppsQueryState from '../use-apps-query-state'
 
 const renderWithAdapter = (searchParams = '') => {
-  return renderHookWithNuqs(() => useAppsQueryState(), { searchParams })
+  const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={onUrlUpdate}>
+      {children}
+    </NuqsTestingAdapter>
+  )
+  const { result } = renderHook(() => useAppsQueryState(), { wrapper })
+  return { result, onUrlUpdate }
 }
 
 describe('useAppsQueryState', () => {

web/app/components/apps/list.tsx

@@ -3,7 +3,7 @@
 import type { FC } from 'react'
 import { useDebounceFn } from 'ahooks'
 import dynamic from 'next/dynamic'
-import { parseAsStringLiteral, useQueryState } from 'nuqs'
+import { parseAsString, useQueryState } from 'nuqs'
 import { useCallback, useEffect, useRef, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import Input from '@/app/components/base/input'
@@ -16,7 +16,7 @@ import { useAppContext } from '@/context/app-context'
 import { useGlobalPublicStore } from '@/context/global-public-context'
 import { CheckModal } from '@/hooks/use-pay'
 import { useInfiniteAppList } from '@/service/use-apps'
-import { AppModeEnum, AppModes } from '@/types/app'
+import { AppModeEnum } from '@/types/app'
 import { cn } from '@/utils/classnames'
 import AppCard from './app-card'
 import { AppCardSkeleton } from './app-card-skeleton'
@@ -33,18 +33,6 @@ const CreateFromDSLModal = dynamic(() => import('@/app/components/app/create-fro
   ssr: false,
 })
 
-const APP_LIST_CATEGORY_VALUES = ['all', ...AppModes] as const
-type AppListCategory = typeof APP_LIST_CATEGORY_VALUES[number]
-const appListCategorySet = new Set<string>(APP_LIST_CATEGORY_VALUES)
-
-const isAppListCategory = (value: string): value is AppListCategory => {
-  return appListCategorySet.has(value)
-}
-
-const parseAsAppListCategory = parseAsStringLiteral(APP_LIST_CATEGORY_VALUES)
-  .withDefault('all')
-  .withOptions({ history: 'push' })
-
 type Props = {
   controlRefreshList?: number
 }
@@ -57,7 +45,7 @@ const List: FC<Props> = ({
   const showTagManagementModal = useTagStore(s => s.showTagManagementModal)
   const [activeTab, setActiveTab] = useQueryState(
     'category',
-    parseAsAppListCategory,
+    parseAsString.withDefault('all').withOptions({ history: 'push' }),
   )
 
   const { query: { tagIDs = [], keywords = '', isCreatedByMe: queryIsCreatedByMe = false }, setQuery } = useAppsQueryState()
@@ -92,7 +80,7 @@ const List: FC<Props> = ({
     name: searchKeywords,
     tag_ids: tagIDs,
     is_created_by_me: isCreatedByMe,
-    ...(activeTab !== 'all' ? { mode: activeTab } : {}),
+    ...(activeTab !== 'all' ? { mode: activeTab as AppModeEnum } : {}),
   }
 
   const {
@@ -198,10 +186,7 @@ const List: FC<Props> = ({
         <div className="sticky top-0 z-10 flex flex-wrap items-center justify-between gap-y-2 bg-background-body px-12 pb-5 pt-7">
           <TabSliderNew
             value={activeTab}
-            onChange={(nextValue) => {
-              if (isAppListCategory(nextValue))
-                setActiveTab(nextValue)
-            }}
+            onChange={setActiveTab}
             options={options}
           />
           <div className="flex items-center gap-2">

web/app/components/base/ui/dialog/__tests__/index.spec.tsx

@@ -1,6 +1,7 @@
+import type { ComponentPropsWithoutRef } from 'react'
 import { Dialog as BaseDialog } from '@base-ui/react/dialog'
 import { render, screen } from '@testing-library/react'
-import { describe, expect, it } from 'vitest'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
 import {
   Dialog,
   DialogClose,
@@ -10,61 +11,133 @@ import {
   DialogTrigger,
 } from '../index'
 
+type DivPrimitiveProps = ComponentPropsWithoutRef<'div'>
+type ButtonPrimitiveProps = ComponentPropsWithoutRef<'button'>
+type SectionPrimitiveProps = ComponentPropsWithoutRef<'section'>
+
+vi.mock('@base-ui/react/dialog', () => {
+  const createDivPrimitive = () => {
+    return vi.fn(({ children, ...props }: DivPrimitiveProps) => (
+      <div {...props}>
+        {children}
+      </div>
+    ))
+  }
+
+  const createButtonPrimitive = () => {
+    return vi.fn(({ children, ...props }: ButtonPrimitiveProps) => (
+      <button type="button" {...props}>
+        {children}
+      </button>
+    ))
+  }
+
+  const createPopupPrimitive = () => {
+    return vi.fn(({ children, ...props }: SectionPrimitiveProps) => (
+      <section role="dialog" {...props}>
+        {children}
+      </section>
+    ))
+  }
+
+  return {
+    Dialog: {
+      Root: createDivPrimitive(),
+      Trigger: createDivPrimitive(),
+      Title: createDivPrimitive(),
+      Description: createDivPrimitive(),
+      Close: createButtonPrimitive(),
+      Portal: createDivPrimitive(),
+      Backdrop: createDivPrimitive(),
+      Popup: createPopupPrimitive(),
+    },
+  }
+})
+
 describe('Dialog wrapper', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // Rendering behavior for wrapper-specific structure and content.
   describe('Rendering', () => {
-    it('should render dialog content when dialog is open', () => {
+    it('should render portal structure and dialog content when DialogContent is rendered', () => {
+      // Arrange
+      const contentText = 'dialog body'
+
+      // Act
       render(
-        <Dialog open>
-          <DialogContent>
-            <DialogTitle>Dialog Title</DialogTitle>
-            <DialogDescription>Dialog Description</DialogDescription>
-          </DialogContent>
-        </Dialog>,
+        <DialogContent>
+          <span>{contentText}</span>
+        </DialogContent>,
       )
 
-      const dialog = screen.getByRole('dialog')
-      expect(dialog).toHaveTextContent('Dialog Title')
-      expect(dialog).toHaveTextContent('Dialog Description')
+      // Assert
+      expect(vi.mocked(BaseDialog.Portal)).toHaveBeenCalledTimes(1)
+      expect(vi.mocked(BaseDialog.Backdrop)).toHaveBeenCalledTimes(1)
+      expect(vi.mocked(BaseDialog.Popup)).toHaveBeenCalledTimes(1)
+      expect(screen.getByRole('dialog')).toBeInTheDocument()
+      expect(screen.getByText(contentText)).toBeInTheDocument()
     })
   })
 
+  // Props behavior for closable semantics and defaults.
   describe('Props', () => {
     it('should not render close button when closable is omitted', () => {
+      // Arrange
       render(
-        <Dialog open>
-          <DialogContent>
-            <span>Dialog body</span>
-          </DialogContent>
-        </Dialog>,
+        <DialogContent>
+          <span>content</span>
+        </DialogContent>,
       )
 
+      // Assert
       expect(screen.queryByRole('button', { name: 'Close' })).not.toBeInTheDocument()
     })
 
-    it('should render close button when closable is true', () => {
+    it('should not render close button when closable is false', () => {
+      // Arrange
       render(
-        <Dialog open>
-          <DialogContent closable>
-            <span>Dialog body</span>
-          </DialogContent>
-        </Dialog>,
+        <DialogContent closable={false}>
+          <span>content</span>
+        </DialogContent>,
       )
 
-      const dialog = screen.getByRole('dialog')
-      const closeButton = screen.getByRole('button', { name: 'Close' })
+      // Assert
+      expect(screen.queryByRole('button', { name: 'Close' })).not.toBeInTheDocument()
+    })
 
-      expect(dialog).toContainElement(closeButton)
+    it('should render semantic close button when closable is true', () => {
+      // Arrange
+      render(
+        <DialogContent closable>
+          <span>content</span>
+        </DialogContent>,
+      )
+
+      // Assert
+      const closeButton = screen.getByRole('button', { name: 'Close' })
       expect(closeButton).toHaveAttribute('aria-label', 'Close')
+      expect(screen.getByRole('dialog')).toContainElement(closeButton)
+
+      const closeIcon = closeButton.querySelector('span')
+      expect(closeIcon).toBeInTheDocument()
+      expect(closeButton).toContainElement(closeIcon)
     })
   })
 
+  // Export mapping ensures wrapper aliases point to base primitives.
   describe('Exports', () => {
     it('should map dialog aliases to the matching base dialog primitives', () => {
-      expect(Dialog).toBe(BaseDialog.Root)
-      expect(DialogTrigger).toBe(BaseDialog.Trigger)
-      expect(DialogTitle).toBe(BaseDialog.Title)
-      expect(DialogDescription).toBe(BaseDialog.Description)
-      expect(DialogClose).toBe(BaseDialog.Close)
+      // Arrange
+      const basePrimitives = BaseDialog
+
+      // Act & Assert
+      expect(Dialog).toBe(basePrimitives.Root)
+      expect(DialogTrigger).toBe(basePrimitives.Trigger)
+      expect(DialogTitle).toBe(basePrimitives.Title)
+      expect(DialogDescription).toBe(basePrimitives.Description)
+      expect(DialogClose).toBe(basePrimitives.Close)
     })
   })
 })

web/app/components/base/ui/dropdown-menu/__tests__/index.spec.tsx

@@ -1,6 +1,7 @@
+import type { Placement } from '@/app/components/base/ui/placement'
 import { Menu } from '@base-ui/react/menu'
 import { fireEvent, render, screen, within } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
+import { parsePlacement } from '@/app/components/base/ui/placement'
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -15,9 +16,108 @@ import {
   DropdownMenuTrigger,
 } from '../index'
 
+vi.mock('@base-ui/react/menu', async () => {
+  const React = await import('react')
+
+  type PrimitiveProps = React.HTMLAttributes<HTMLDivElement> & {
+    children?: React.ReactNode
+  }
+
+  type PrimitiveOptions = {
+    displayName: string
+    defaultRole?: React.AriaRole
+  }
+
+  type PositionerProps = PrimitiveProps & {
+    side?: string
+    align?: string
+    sideOffset?: number
+    alignOffset?: number
+  }
+
+  const createPrimitive = ({ displayName, defaultRole }: PrimitiveOptions) => {
+    const Primitive = React.forwardRef<HTMLDivElement, PrimitiveProps>(({ children, role, ...props }, ref) => {
+      return React.createElement(
+        'div',
+        {
+          ref,
+          role: role ?? defaultRole,
+          ...props,
+        },
+        children,
+      )
+    })
+    Primitive.displayName = displayName
+    return Primitive
+  }
+
+  const Portal = ({ children }: PrimitiveProps) => {
+    return React.createElement(React.Fragment, null, children)
+  }
+  Portal.displayName = 'menu-portal'
+
+  const Positioner = React.forwardRef<HTMLDivElement, PositionerProps>(({ children, role, side, align, sideOffset, alignOffset, ...props }, ref) => {
+    return React.createElement(
+      'div',
+      {
+        ref,
+        'role': role ?? 'group',
+        'data-side': side,
+        'data-align': align,
+        'data-side-offset': sideOffset,
+        'data-align-offset': alignOffset,
+        ...props,
+      },
+      children,
+    )
+  })
+  Positioner.displayName = 'menu-positioner'
+
+  const Menu = {
+    Root: createPrimitive({ displayName: 'menu-root' }),
+    Portal,
+    Trigger: createPrimitive({ displayName: 'menu-trigger', defaultRole: 'button' }),
+    SubmenuRoot: createPrimitive({ displayName: 'menu-submenu-root' }),
+    Group: createPrimitive({ displayName: 'menu-group', defaultRole: 'group' }),
+    GroupLabel: createPrimitive({ displayName: 'menu-group-label' }),
+    RadioGroup: createPrimitive({ displayName: 'menu-radio-group', defaultRole: 'radiogroup' }),
+    RadioItem: createPrimitive({ displayName: 'menu-radio-item', defaultRole: 'menuitemradio' }),
+    RadioItemIndicator: createPrimitive({ displayName: 'menu-radio-item-indicator' }),
+    CheckboxItem: createPrimitive({ displayName: 'menu-checkbox-item', defaultRole: 'menuitemcheckbox' }),
+    CheckboxItemIndicator: createPrimitive({ displayName: 'menu-checkbox-item-indicator' }),
+    Positioner,
+    Popup: createPrimitive({ displayName: 'menu-popup', defaultRole: 'menu' }),
+    SubmenuTrigger: createPrimitive({ displayName: 'menu-submenu-trigger', defaultRole: 'menuitem' }),
+    Item: createPrimitive({ displayName: 'menu-item', defaultRole: 'menuitem' }),
+    Separator: createPrimitive({ displayName: 'menu-separator', defaultRole: 'separator' }),
+  }
+
+  return { Menu }
+})
+
+vi.mock('@/app/components/base/ui/placement', () => ({
+  parsePlacement: vi.fn((placement: Placement) => {
+    const [side, align] = placement.split('-') as [string, string | undefined]
+    return {
+      side: side as 'top' | 'right' | 'bottom' | 'left',
+      align: (align ?? 'center') as 'start' | 'center' | 'end',
+    }
+  }),
+}))
+
 describe('dropdown-menu wrapper', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // Ensures exported aliases stay aligned with the wrapped Menu primitives.
   describe('alias exports', () => {
     it('should map direct aliases to the corresponding Menu primitive when importing menu roots', () => {
+      // Arrange
+
+      // Act
+
+      // Assert
       expect(DropdownMenu).toBe(Menu.Root)
       expect(DropdownMenuPortal).toBe(Menu.Portal)
       expect(DropdownMenuTrigger).toBe(Menu.Trigger)
@@ -27,75 +127,88 @@ describe('dropdown-menu wrapper', () => {
     })
   })
 
+  // Verifies content popup placement and passthrough behavior.
   describe('DropdownMenuContent', () => {
-    it('should position content at bottom-end with default placement when props are omitted', () => {
+    it('should position content at bottom-end with default offsets when placement props are omitted', () => {
+      // Arrange
+      const parsePlacementMock = vi.mocked(parsePlacement)
+
+      // Act
       render(
-        <DropdownMenu open>
-          <DropdownMenuTrigger aria-label="menu trigger">Open</DropdownMenuTrigger>
-          <DropdownMenuContent positionerProps={{ 'role': 'group', 'aria-label': 'content positioner' }}>
-            <DropdownMenuItem>Content action</DropdownMenuItem>
-          </DropdownMenuContent>
-        </DropdownMenu>,
+        <DropdownMenuContent>
+          <button type="button">content action</button>
+        </DropdownMenuContent>,
       )
 
-      const positioner = screen.getByRole('group', { name: 'content positioner' })
+      // Assert
       const popup = screen.getByRole('menu')
+      const positioner = popup.parentElement
 
+      expect(parsePlacementMock).toHaveBeenCalledTimes(1)
+      expect(parsePlacementMock).toHaveBeenCalledWith('bottom-end')
+      expect(positioner).not.toBeNull()
       expect(positioner).toHaveAttribute('data-side', 'bottom')
       expect(positioner).toHaveAttribute('data-align', 'end')
-      expect(within(popup).getByRole('menuitem', { name: 'Content action' })).toBeInTheDocument()
+      expect(positioner).toHaveAttribute('data-side-offset', '4')
+      expect(positioner).toHaveAttribute('data-align-offset', '0')
+      expect(within(popup).getByRole('button', { name: 'content action' })).toBeInTheDocument()
     })
 
-    it('should apply custom placement when custom positioning props are provided', () => {
+    it('should apply custom placement offsets when custom positioning props are provided', () => {
+      // Arrange
+      const parsePlacementMock = vi.mocked(parsePlacement)
+
+      // Act
       render(
-        <DropdownMenu open>
-          <DropdownMenuTrigger aria-label="menu trigger">Open</DropdownMenuTrigger>
-          <DropdownMenuContent
-            placement="top-start"
-            sideOffset={12}
-            alignOffset={-3}
-            positionerProps={{ 'role': 'group', 'aria-label': 'custom content positioner' }}
-          >
-            <DropdownMenuItem>Custom content</DropdownMenuItem>
-          </DropdownMenuContent>
-        </DropdownMenu>,
+        <DropdownMenuContent
+          placement="top-start"
+          sideOffset={12}
+          alignOffset={-3}
+        >
+          <span>custom content</span>
+        </DropdownMenuContent>,
       )
 
-      const positioner = screen.getByRole('group', { name: 'custom content positioner' })
+      // Assert
       const popup = screen.getByRole('menu')
+      const positioner = popup.parentElement
 
+      expect(parsePlacementMock).toHaveBeenCalledTimes(1)
+      expect(parsePlacementMock).toHaveBeenCalledWith('top-start')
+      expect(positioner).not.toBeNull()
       expect(positioner).toHaveAttribute('data-side', 'top')
       expect(positioner).toHaveAttribute('data-align', 'start')
-      expect(within(popup).getByRole('menuitem', { name: 'Custom content' })).toBeInTheDocument()
+      expect(positioner).toHaveAttribute('data-side-offset', '12')
+      expect(positioner).toHaveAttribute('data-align-offset', '-3')
+      expect(within(popup).getByText('custom content')).toBeInTheDocument()
     })
 
     it('should forward passthrough attributes and handlers when positionerProps and popupProps are provided', () => {
+      // Arrange
       const handlePositionerMouseEnter = vi.fn()
       const handlePopupClick = vi.fn()
 
+      // Act
       render(
-        <DropdownMenu open>
-          <DropdownMenuTrigger aria-label="menu trigger">Open</DropdownMenuTrigger>
-          <DropdownMenuContent
-            positionerProps={{
-              'role': 'group',
-              'aria-label': 'dropdown content positioner',
-              'id': 'dropdown-content-positioner',
-              'onMouseEnter': handlePositionerMouseEnter,
-            }}
-            popupProps={{
-              role: 'menu',
-              id: 'dropdown-content-popup',
-              onClick: handlePopupClick,
-            }}
-          >
-            <DropdownMenuItem>Passthrough content</DropdownMenuItem>
-          </DropdownMenuContent>
-        </DropdownMenu>,
+        <DropdownMenuContent
+          positionerProps={{
+            'aria-label': 'dropdown content positioner',
+            'id': 'dropdown-content-positioner',
+            'onMouseEnter': handlePositionerMouseEnter,
+          }}
+          popupProps={{
+            'aria-label': 'dropdown content popup',
+            'id': 'dropdown-content-popup',
+            'onClick': handlePopupClick,
+          }}
+        >
+          <span>passthrough content</span>
+        </DropdownMenuContent>,
       )
 
+      // Assert
       const positioner = screen.getByRole('group', { name: 'dropdown content positioner' })
-      const popup = screen.getByRole('menu')
+      const popup = screen.getByRole('menu', { name: 'dropdown content popup' })
       fireEvent.mouseEnter(positioner)
       fireEvent.click(popup)
 
@@ -106,68 +219,72 @@ describe('dropdown-menu wrapper', () => {
     })
   })
 
+  // Verifies submenu popup placement and passthrough behavior.
   describe('DropdownMenuSubContent', () => {
-    it('should position sub-content at left-start with default placement when props are omitted', () => {
+    it('should position sub-content at left-start with default offsets when props are omitted', () => {
+      // Arrange
+      const parsePlacementMock = vi.mocked(parsePlacement)
+
+      // Act
       render(
-        <DropdownMenu open>
-          <DropdownMenuTrigger aria-label="menu trigger">Open</DropdownMenuTrigger>
-          <DropdownMenuContent>
-            <DropdownMenuSub open>
-              <DropdownMenuSubTrigger>More actions</DropdownMenuSubTrigger>
-              <DropdownMenuSubContent positionerProps={{ 'role': 'group', 'aria-label': 'sub positioner' }}>
-                <DropdownMenuItem>Sub action</DropdownMenuItem>
-              </DropdownMenuSubContent>
-            </DropdownMenuSub>
-          </DropdownMenuContent>
-        </DropdownMenu>,
+        <DropdownMenuSubContent>
+          <button type="button">sub action</button>
+        </DropdownMenuSubContent>,
       )
 
-      const positioner = screen.getByRole('group', { name: 'sub positioner' })
+      // Assert
+      const popup = screen.getByRole('menu')
+      const positioner = popup.parentElement
+
+      expect(parsePlacementMock).toHaveBeenCalledTimes(1)
+      expect(parsePlacementMock).toHaveBeenCalledWith('left-start')
+      expect(positioner).not.toBeNull()
       expect(positioner).toHaveAttribute('data-side', 'left')
       expect(positioner).toHaveAttribute('data-align', 'start')
-      expect(screen.getByRole('menuitem', { name: 'Sub action' })).toBeInTheDocument()
+      expect(positioner).toHaveAttribute('data-side-offset', '4')
+      expect(positioner).toHaveAttribute('data-align-offset', '0')
+      expect(within(popup).getByRole('button', { name: 'sub action' })).toBeInTheDocument()
     })
 
-    it('should apply custom placement and forward passthrough props for sub-content when custom props are provided', () => {
+    it('should apply custom placement offsets and forward passthrough props when custom sub-content props are provided', () => {
+      // Arrange
+      const parsePlacementMock = vi.mocked(parsePlacement)
       const handlePositionerFocus = vi.fn()
       const handlePopupClick = vi.fn()
 
+      // Act
       render(
-        <DropdownMenu open>
-          <DropdownMenuTrigger aria-label="menu trigger">Open</DropdownMenuTrigger>
-          <DropdownMenuContent>
-            <DropdownMenuSub open>
-              <DropdownMenuSubTrigger>More actions</DropdownMenuSubTrigger>
-              <DropdownMenuSubContent
-                placement="right-end"
-                sideOffset={6}
-                alignOffset={2}
-                positionerProps={{
-                  'role': 'group',
-                  'aria-label': 'dropdown sub positioner',
-                  'id': 'dropdown-sub-positioner',
-                  'onFocus': handlePositionerFocus,
-                }}
-                popupProps={{
-                  role: 'menu',
-                  id: 'dropdown-sub-popup',
-                  onClick: handlePopupClick,
-                }}
-              >
-                <DropdownMenuItem>Custom sub action</DropdownMenuItem>
-              </DropdownMenuSubContent>
-            </DropdownMenuSub>
-          </DropdownMenuContent>
-        </DropdownMenu>,
+        <DropdownMenuSubContent
+          placement="right-end"
+          sideOffset={6}
+          alignOffset={2}
+          positionerProps={{
+            'aria-label': 'dropdown sub positioner',
+            'id': 'dropdown-sub-positioner',
+            'onFocus': handlePositionerFocus,
+          }}
+          popupProps={{
+            'aria-label': 'dropdown sub popup',
+            'id': 'dropdown-sub-popup',
+            'onClick': handlePopupClick,
+          }}
+        >
+          <span>custom sub content</span>
+        </DropdownMenuSubContent>,
       )
 
+      // Assert
       const positioner = screen.getByRole('group', { name: 'dropdown sub positioner' })
-      const popup = screen.getByRole('menu', { name: 'More actions' })
+      const popup = screen.getByRole('menu', { name: 'dropdown sub popup' })
       fireEvent.focus(positioner)
       fireEvent.click(popup)
 
+      expect(parsePlacementMock).toHaveBeenCalledTimes(1)
+      expect(parsePlacementMock).toHaveBeenCalledWith('right-end')
       expect(positioner).toHaveAttribute('data-side', 'right')
       expect(positioner).toHaveAttribute('data-align', 'end')
+      expect(positioner).toHaveAttribute('data-side-offset', '6')
+      expect(positioner).toHaveAttribute('data-align-offset', '2')
       expect(positioner).toHaveAttribute('id', 'dropdown-sub-positioner')
       expect(popup).toHaveAttribute('id', 'dropdown-sub-popup')
       expect(handlePositionerFocus).toHaveBeenCalledTimes(1)
@@ -175,43 +292,40 @@ describe('dropdown-menu wrapper', () => {
     })
   })
 
+  // Covers submenu trigger behavior with and without destructive flag.
   describe('DropdownMenuSubTrigger', () => {
-    it('should render submenu trigger content when trigger children are provided', () => {
+    it('should render label and submenu chevron when trigger children are provided', () => {
+      // Arrange
+
+      // Act
       render(
-        <DropdownMenu open>
-          <DropdownMenuTrigger aria-label="menu trigger">Open</DropdownMenuTrigger>
-          <DropdownMenuContent>
-            <DropdownMenuSub open>
-              <DropdownMenuSubTrigger>Trigger item</DropdownMenuSubTrigger>
-            </DropdownMenuSub>
-          </DropdownMenuContent>
-        </DropdownMenu>,
+        <DropdownMenuSubTrigger>
+          Trigger item
+        </DropdownMenuSubTrigger>,
       )
 
-      expect(screen.getByRole('menuitem', { name: 'Trigger item' })).toBeInTheDocument()
+      // Assert
+      const subTrigger = screen.getByRole('menuitem', { name: 'Trigger item' })
+      expect(subTrigger.querySelector('span[aria-hidden="true"]')).not.toBeNull()
     })
 
     it.each([true, false])('should remain interactive and not leak destructive prop when destructive is %s', (destructive) => {
+      // Arrange
       const handleClick = vi.fn()
 
+      // Act
       render(
-        <DropdownMenu open>
-          <DropdownMenuTrigger aria-label="menu trigger">Open</DropdownMenuTrigger>
-          <DropdownMenuContent>
-            <DropdownMenuSub open>
-              <DropdownMenuSubTrigger
-                destructive={destructive}
-                aria-label="submenu action"
-                id={`submenu-trigger-${String(destructive)}`}
-                onClick={handleClick}
-              >
-                Trigger item
-              </DropdownMenuSubTrigger>
-            </DropdownMenuSub>
-          </DropdownMenuContent>
-        </DropdownMenu>,
+        <DropdownMenuSubTrigger
+          destructive={destructive}
+          aria-label="submenu action"
+          id={`submenu-trigger-${String(destructive)}`}
+          onClick={handleClick}
+        >
+          Trigger item
+        </DropdownMenuSubTrigger>,
       )
 
+      // Assert
       const subTrigger = screen.getByRole('menuitem', { name: 'submenu action' })
       fireEvent.click(subTrigger)
 
@@ -221,26 +335,25 @@ describe('dropdown-menu wrapper', () => {
     })
   })
 
+  // Covers menu item behavior with and without destructive flag.
   describe('DropdownMenuItem', () => {
     it.each([true, false])('should remain interactive and not leak destructive prop when destructive is %s', (destructive) => {
+      // Arrange
       const handleClick = vi.fn()
 
+      // Act
       render(
-        <DropdownMenu open>
-          <DropdownMenuTrigger aria-label="menu trigger">Open</DropdownMenuTrigger>
-          <DropdownMenuContent>
-            <DropdownMenuItem
-              destructive={destructive}
-              aria-label="menu action"
-              id={`menu-item-${String(destructive)}`}
-              onClick={handleClick}
-            >
-              Item label
-            </DropdownMenuItem>
-          </DropdownMenuContent>
-        </DropdownMenu>,
+        <DropdownMenuItem
+          destructive={destructive}
+          aria-label="menu action"
+          id={`menu-item-${String(destructive)}`}
+          onClick={handleClick}
+        >
+          Item label
+        </DropdownMenuItem>,
       )
 
+      // Assert
       const item = screen.getByRole('menuitem', { name: 'menu action' })
       fireEvent.click(item)
 
@@ -250,23 +363,22 @@ describe('dropdown-menu wrapper', () => {
     })
   })
 
+  // Verifies separator semantics and row separation behavior.
   describe('DropdownMenuSeparator', () => {
     it('should forward passthrough props and handlers when separator props are provided', () => {
+      // Arrange
       const handleMouseEnter = vi.fn()
 
+      // Act
       render(
-        <DropdownMenu open>
-          <DropdownMenuTrigger aria-label="menu trigger">Open</DropdownMenuTrigger>
-          <DropdownMenuContent>
-            <DropdownMenuSeparator
-              aria-label="actions divider"
-              id="menu-separator"
-              onMouseEnter={handleMouseEnter}
-            />
-          </DropdownMenuContent>
-        </DropdownMenu>,
+        <DropdownMenuSeparator
+          aria-label="actions divider"
+          id="menu-separator"
+          onMouseEnter={handleMouseEnter}
+        />,
       )
 
+      // Assert
       const separator = screen.getByRole('separator', { name: 'actions divider' })
       fireEvent.mouseEnter(separator)
 
@@ -275,17 +387,18 @@ describe('dropdown-menu wrapper', () => {
     })
 
     it('should keep surrounding menu rows rendered when separator is placed between items', () => {
+      // Arrange
+
+      // Act
       render(
-        <DropdownMenu open>
-          <DropdownMenuTrigger aria-label="menu trigger">Open</DropdownMenuTrigger>
-          <DropdownMenuContent>
-            <DropdownMenuItem>First action</DropdownMenuItem>
-            <DropdownMenuSeparator />
-            <DropdownMenuItem>Second action</DropdownMenuItem>
-          </DropdownMenuContent>
-        </DropdownMenu>,
+        <>
+          <DropdownMenuItem>First action</DropdownMenuItem>
+          <DropdownMenuSeparator />
+          <DropdownMenuItem>Second action</DropdownMenuItem>
+        </>,
       )
 
+      // Assert
       expect(screen.getByRole('menuitem', { name: 'First action' })).toBeInTheDocument()
       expect(screen.getByRole('menuitem', { name: 'Second action' })).toBeInTheDocument()
       expect(screen.getAllByRole('separator')).toHaveLength(1)

web/app/components/base/ui/popover/__tests__/index.spec.tsx

@@ -1,6 +1,6 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react'
 import { Popover as BasePopover } from '@base-ui/react/popover'
-import { fireEvent, render, screen } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
 import {
   Popover,
   PopoverClose,
@@ -10,98 +10,190 @@ import {
   PopoverTrigger,
 } from '..'
 
+type PrimitiveProps = ComponentPropsWithoutRef<'div'> & {
+  children?: ReactNode
+}
+
+type PositionerProps = PrimitiveProps & {
+  side?: 'top' | 'bottom' | 'left' | 'right'
+  align?: 'start' | 'center' | 'end'
+  sideOffset?: number
+  alignOffset?: number
+}
+
+vi.mock('@base-ui/react/popover', () => {
+  const Root = ({ children, ...props }: PrimitiveProps) => (
+    <div {...props}>
+      {children}
+    </div>
+  )
+
+  const Trigger = ({ children, ...props }: ComponentPropsWithoutRef<'button'>) => (
+    <button type="button" {...props}>
+      {children}
+    </button>
+  )
+
+  const Close = ({ children, ...props }: ComponentPropsWithoutRef<'button'>) => (
+    <button type="button" {...props}>
+      {children}
+    </button>
+  )
+
+  const Title = ({ children, ...props }: ComponentPropsWithoutRef<'h2'>) => (
+    <h2 {...props}>
+      {children}
+    </h2>
+  )
+
+  const Description = ({ children, ...props }: ComponentPropsWithoutRef<'p'>) => (
+    <p {...props}>
+      {children}
+    </p>
+  )
+
+  const Portal = ({ children }: PrimitiveProps) => (
+    <div>{children}</div>
+  )
+
+  const Positioner = ({
+    children,
+    side,
+    align,
+    sideOffset,
+    alignOffset,
+    ...props
+  }: PositionerProps) => (
+    <div
+      data-side={side}
+      data-align={align}
+      data-side-offset={String(sideOffset)}
+      data-align-offset={String(alignOffset)}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+
+  const Popup = ({ children, ...props }: PrimitiveProps) => (
+    <div {...props}>
+      {children}
+    </div>
+  )
+
+  return {
+    Popover: {
+      Root,
+      Trigger,
+      Close,
+      Title,
+      Description,
+      Portal,
+      Positioner,
+      Popup,
+    },
+  }
+})
+
 describe('PopoverContent', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // Placement and default value behaviors.
   describe('Placement', () => {
     it('should use bottom placement and default offsets when placement props are not provided', () => {
+      // Arrange
       render(
-        <Popover open>
-          <PopoverTrigger aria-label="popover trigger">Open</PopoverTrigger>
-          <PopoverContent
-            positionerProps={{ 'role': 'group', 'aria-label': 'default positioner' }}
-            popupProps={{ 'role': 'dialog', 'aria-label': 'default popover' }}
-          >
-            <span>Default content</span>
-          </PopoverContent>
-        </Popover>,
+        <PopoverContent positionerProps={{ 'aria-label': 'default positioner' }}>
+          <span>Default content</span>
+        </PopoverContent>,
       )
 
-      const positioner = screen.getByRole('group', { name: 'default positioner' })
-      const popup = screen.getByRole('dialog', { name: 'default popover' })
+      // Act
+      const positioner = screen.getByLabelText('default positioner')
 
+      // Assert
       expect(positioner).toHaveAttribute('data-side', 'bottom')
       expect(positioner).toHaveAttribute('data-align', 'center')
-      expect(popup).toHaveTextContent('Default content')
+      expect(positioner).toHaveAttribute('data-side-offset', '8')
+      expect(positioner).toHaveAttribute('data-align-offset', '0')
+      expect(screen.getByText('Default content')).toBeInTheDocument()
     })
 
     it('should apply parsed custom placement and custom offsets when placement props are provided', () => {
+      // Arrange
       render(
-        <Popover open>
-          <PopoverTrigger aria-label="popover trigger">Open</PopoverTrigger>
-          <PopoverContent
-            placement="top-end"
-            sideOffset={14}
-            alignOffset={6}
-            positionerProps={{ 'role': 'group', 'aria-label': 'custom positioner' }}
-            popupProps={{ 'role': 'dialog', 'aria-label': 'custom popover' }}
-          >
-            <span>Custom placement content</span>
-          </PopoverContent>
-        </Popover>,
+        <PopoverContent
+          placement="top-end"
+          sideOffset={14}
+          alignOffset={6}
+          positionerProps={{ 'aria-label': 'custom positioner' }}
+        >
+          <span>Custom placement content</span>
+        </PopoverContent>,
       )
 
-      const positioner = screen.getByRole('group', { name: 'custom positioner' })
-      const popup = screen.getByRole('dialog', { name: 'custom popover' })
+      // Act
+      const positioner = screen.getByLabelText('custom positioner')
 
+      // Assert
       expect(positioner).toHaveAttribute('data-side', 'top')
       expect(positioner).toHaveAttribute('data-align', 'end')
-      expect(popup).toHaveTextContent('Custom placement content')
+      expect(positioner).toHaveAttribute('data-side-offset', '14')
+      expect(positioner).toHaveAttribute('data-align-offset', '6')
     })
   })
 
+  // Passthrough behavior for delegated primitives.
   describe('Passthrough props', () => {
     it('should forward positionerProps and popupProps when passthrough props are provided', () => {
-      const onPopupClick = vi.fn()
-
+      // Arrange
       render(
-        <Popover open>
-          <PopoverTrigger aria-label="popover trigger">Open</PopoverTrigger>
-          <PopoverContent
-            positionerProps={{
-              'role': 'group',
-              'aria-label': 'popover positioner',
-              'id': 'popover-positioner-id',
-            }}
-            popupProps={{
-              'id': 'popover-popup-id',
-              'role': 'dialog',
-              'aria-label': 'popover content',
-              'onClick': onPopupClick,
-            }}
-          >
-            <span>Popover body</span>
-          </PopoverContent>
-        </Popover>,
+        <PopoverContent
+          positionerProps={{
+            'aria-label': 'popover positioner',
+          }}
+          popupProps={{
+            'id': 'popover-popup-id',
+            'role': 'dialog',
+            'aria-label': 'popover content',
+          }}
+        >
+          <span>Popover body</span>
+        </PopoverContent>,
       )
 
-      const positioner = screen.getByRole('group', { name: 'popover positioner' })
+      // Act
+      const positioner = screen.getByLabelText('popover positioner')
       const popup = screen.getByRole('dialog', { name: 'popover content' })
-      fireEvent.click(popup)
 
-      expect(positioner).toHaveAttribute('id', 'popover-positioner-id')
+      // Assert
+      expect(positioner).toHaveAttribute('aria-label', 'popover positioner')
       expect(popup).toHaveAttribute('id', 'popover-popup-id')
-      expect(onPopupClick).toHaveBeenCalledTimes(1)
+      expect(popup).toHaveAttribute('role', 'dialog')
+      expect(popup).toHaveAttribute('aria-label', 'popover content')
     })
   })
 })
 
 describe('Popover aliases', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  // Export mapping behavior to keep wrapper aliases aligned.
   describe('Export mapping', () => {
     it('should map aliases to the matching base popover primitives when wrapper exports are imported', () => {
-      expect(Popover).toBe(BasePopover.Root)
-      expect(PopoverTrigger).toBe(BasePopover.Trigger)
-      expect(PopoverClose).toBe(BasePopover.Close)
-      expect(PopoverTitle).toBe(BasePopover.Title)
-      expect(PopoverDescription).toBe(BasePopover.Description)
+      // Arrange
+      const basePrimitives = BasePopover
+
+      // Act & Assert
+      expect(Popover).toBe(basePrimitives.Root)
+      expect(PopoverTrigger).toBe(basePrimitives.Trigger)
+      expect(PopoverClose).toBe(basePrimitives.Close)
+      expect(PopoverTitle).toBe(basePrimitives.Title)
+      expect(PopoverDescription).toBe(basePrimitives.Description)
     })
   })
 })

web/app/components/base/ui/select/__tests__/index.spec.tsx

@@ -1,219 +1,325 @@
+import type {
+  ButtonHTMLAttributes,
+  HTMLAttributes,
+  ReactNode,
+} from 'react'
 import { fireEvent, render, screen } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
-import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../index'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+} from '../index'
 
-const renderOpenSelect = ({
-  triggerProps = {},
-  contentProps = {},
-  onValueChange,
-}: {
-  triggerProps?: Record<string, unknown>
-  contentProps?: Record<string, unknown>
-  onValueChange?: (value: string | null) => void
-} = {}) => {
-  return render(
-    <Select open defaultValue="seattle" onValueChange={onValueChange}>
-      <SelectTrigger aria-label="city select" {...triggerProps}>
-        <SelectValue />
-      </SelectTrigger>
-      <SelectContent
-        positionerProps={{
-          'role': 'group',
-          'aria-label': 'select positioner',
-        }}
-        popupProps={{
-          'role': 'dialog',
-          'aria-label': 'select popup',
-        }}
-        listProps={{
-          'role': 'listbox',
-          'aria-label': 'select list',
-        }}
-        {...contentProps}
-      >
-        <SelectItem value="seattle">Seattle</SelectItem>
-        <SelectItem value="new-york">New York</SelectItem>
-      </SelectContent>
-    </Select>,
-  )
+type ParsedPlacement = {
+  side: 'top' | 'bottom' | 'left' | 'right'
+  align: 'start' | 'center' | 'end'
 }
 
+const { mockParsePlacement } = vi.hoisted(() => ({
+  mockParsePlacement: vi.fn<(placement: string) => ParsedPlacement>(),
+}))
+
+vi.mock('@/app/components/base/ui/placement', () => ({
+  parsePlacement: mockParsePlacement,
+}))
+
+vi.mock('@base-ui/react/select', () => {
+  type WithChildren = { children?: ReactNode }
+  type PositionerProps = HTMLAttributes<HTMLDivElement> & {
+    side?: 'top' | 'bottom' | 'left' | 'right'
+    align?: 'start' | 'center' | 'end'
+    sideOffset?: number
+    alignOffset?: number
+    alignItemWithTrigger?: boolean
+  }
+
+  const Root = ({ children }: WithChildren) => <div>{children}</div>
+  const Value = ({ children }: WithChildren) => <span>{children}</span>
+  const Group = ({ children }: WithChildren) => <div>{children}</div>
+  const GroupLabel = ({ children }: WithChildren) => <div>{children}</div>
+  const Separator = (props: HTMLAttributes<HTMLHRElement>) => <hr {...props} />
+
+  const Trigger = ({ children, ...props }: ButtonHTMLAttributes<HTMLButtonElement>) => (
+    <button type="button" {...props}>
+      {children}
+    </button>
+  )
+  const Icon = ({ children, ...props }: HTMLAttributes<HTMLSpanElement>) => (
+    <span aria-label="Open select menu" role="img" {...props}>
+      {children}
+    </span>
+  )
+
+  const Portal = ({ children }: WithChildren) => <div>{children}</div>
+  const Positioner = ({
+    children,
+    side,
+    align,
+    sideOffset,
+    alignOffset,
+    alignItemWithTrigger,
+    className,
+    ...props
+  }: PositionerProps) => (
+    <div
+      data-align={align}
+      data-align-offset={alignOffset}
+      data-align-item-with-trigger={alignItemWithTrigger === undefined ? undefined : String(alignItemWithTrigger)}
+      data-side={side}
+      data-side-offset={sideOffset}
+      className={className}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+  const Popup = ({ children, ...props }: HTMLAttributes<HTMLDivElement>) => (
+    <div {...props}>
+      {children}
+    </div>
+  )
+  const List = ({ children, ...props }: HTMLAttributes<HTMLDivElement>) => (
+    <div {...props}>
+      {children}
+    </div>
+  )
+
+  const Item = ({ children, ...props }: HTMLAttributes<HTMLDivElement>) => (
+    <div role="option" {...props}>
+      {children}
+    </div>
+  )
+  const ItemText = ({ children, ...props }: HTMLAttributes<HTMLSpanElement>) => (
+    <span {...props}>
+      {children}
+    </span>
+  )
+  const ItemIndicator = ({ children, ...props }: HTMLAttributes<HTMLSpanElement>) => (
+    <span aria-label="Selected item indicator" role="img" {...props}>
+      {children}
+    </span>
+  )
+
+  return {
+    Select: {
+      Root,
+      Value,
+      Group,
+      GroupLabel,
+      Separator,
+      Trigger,
+      Icon,
+      Portal,
+      Positioner,
+      Popup,
+      List,
+      Item,
+      ItemText,
+      ItemIndicator,
+    },
+  }
+})
+
 describe('Select wrappers', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockParsePlacement.mockReturnValue({ side: 'bottom', align: 'start' })
+  })
+
+  // Covers default rendering and visual branches for trigger content.
   describe('SelectTrigger', () => {
-    it('should render clear button when clearable is true and loading is false', () => {
-      renderOpenSelect({
-        triggerProps: { clearable: true },
-      })
-
-      expect(screen.getByRole('button', { name: /clear selection/i })).toBeInTheDocument()
-    })
-
-    it('should hide clear button when loading is true', () => {
-      renderOpenSelect({
-        triggerProps: { clearable: true, loading: true },
-      })
+    it('should render the default icon when clearable and loading are not enabled', () => {
+      // Arrange
+      render(<SelectTrigger>Trigger Label</SelectTrigger>)
 
+      // Assert
+      expect(screen.getByText('Trigger Label')).toBeInTheDocument()
+      expect(screen.getByRole('img', { name: /open select menu/i })).toBeInTheDocument()
       expect(screen.queryByRole('button', { name: /clear selection/i })).not.toBeInTheDocument()
     })
 
-    it('should forward native trigger props when trigger props are provided', () => {
-      renderOpenSelect({
-        triggerProps: {
-          'aria-label': 'Choose option',
-          'disabled': true,
-        },
-      })
+    it('should render clear button when clearable is true and loading is false', () => {
+      // Arrange
+      render(<SelectTrigger clearable>Trigger Label</SelectTrigger>)
 
-      const trigger = screen.getByRole('combobox', { name: 'Choose option' })
+      // Assert
+      expect(screen.getByRole('button', { name: /clear selection/i })).toBeInTheDocument()
+      expect(screen.queryByRole('img', { name: /open select menu/i })).not.toBeInTheDocument()
+    })
+
+    it('should render loading indicator and hide clear button when loading is true', () => {
+      // Arrange
+      render(<SelectTrigger clearable loading>Trigger Label</SelectTrigger>)
+
+      // Assert
+      expect(screen.getByRole('button', { name: /trigger label/i })).toBeInTheDocument()
+      expect(screen.queryByRole('button', { name: /clear selection/i })).not.toBeInTheDocument()
+      expect(screen.queryByRole('img', { name: /open select menu/i })).not.toBeInTheDocument()
+    })
+
+    it('should forward native trigger props when trigger props are provided', () => {
+      // Arrange
+      render(
+        <SelectTrigger
+          aria-label="Choose option"
+          disabled
+        >
+          Trigger Label
+        </SelectTrigger>,
+      )
+
+      // Assert
+      const trigger = screen.getByRole('button', { name: /choose option/i })
       expect(trigger).toBeDisabled()
+      expect(trigger).toHaveAttribute('aria-label', 'Choose option')
     })
 
     it('should call onClear and stop click propagation when clear button is clicked', () => {
+      // Arrange
       const onClear = vi.fn()
       const onTriggerClick = vi.fn()
+      render(
+        <SelectTrigger clearable onClear={onClear} onClick={onTriggerClick}>
+          Trigger Label
+        </SelectTrigger>,
+      )
 
-      renderOpenSelect({
-        triggerProps: {
-          clearable: true,
-          onClear,
-          onClick: onTriggerClick,
-        },
-      })
-
+      // Act
       fireEvent.click(screen.getByRole('button', { name: /clear selection/i }))
 
+      // Assert
       expect(onClear).toHaveBeenCalledTimes(1)
       expect(onTriggerClick).not.toHaveBeenCalled()
     })
 
     it('should stop mouse down propagation when clear button receives mouse down', () => {
+      // Arrange
       const onTriggerMouseDown = vi.fn()
+      render(
+        <SelectTrigger clearable onMouseDown={onTriggerMouseDown}>
+          Trigger Label
+        </SelectTrigger>,
+      )
 
-      renderOpenSelect({
-        triggerProps: {
-          clearable: true,
-          onMouseDown: onTriggerMouseDown,
-        },
-      })
-
+      // Act
       fireEvent.mouseDown(screen.getByRole('button', { name: /clear selection/i }))
 
+      // Assert
       expect(onTriggerMouseDown).not.toHaveBeenCalled()
     })
 
     it('should not throw when clear button is clicked without onClear handler', () => {
-      renderOpenSelect({
-        triggerProps: { clearable: true },
-      })
-
+      // Arrange
+      render(<SelectTrigger clearable>Trigger Label</SelectTrigger>)
       const clearButton = screen.getByRole('button', { name: /clear selection/i })
+
+      // Act & Assert
       expect(() => fireEvent.click(clearButton)).not.toThrow()
     })
   })
 
+  // Covers content placement parsing, forwarding props, and slot rendering.
   describe('SelectContent', () => {
-    it('should use default placement when placement is not provided', () => {
-      renderOpenSelect()
+    it('should call parsePlacement with default placement when placement is not provided', () => {
+      // Arrange
+      mockParsePlacement.mockReturnValueOnce({ side: 'bottom', align: 'start' })
 
-      const positioner = screen.getByRole('group', { name: 'select positioner' })
-      expect(positioner).toHaveAttribute('data-side', 'bottom')
-      expect(positioner).toHaveAttribute('data-align', 'start')
+      // Act
+      render(
+        <SelectContent>
+          <span>Option A</span>
+        </SelectContent>,
+      )
+
+      // Assert
+      expect(mockParsePlacement).toHaveBeenCalledWith('bottom-start')
+      expect(screen.getByText('Option A')).toBeInTheDocument()
     })
 
-    it('should apply custom placement when placement props are provided', () => {
-      renderOpenSelect({
-        contentProps: {
-          placement: 'top-end',
-          sideOffset: 12,
-          alignOffset: 6,
-        },
-      })
+    it('should pass parsed side align and offsets to Positioner when custom placement and offsets are provided', () => {
+      // Arrange
+      mockParsePlacement.mockReturnValueOnce({ side: 'top', align: 'end' })
 
-      const positioner = screen.getByRole('group', { name: 'select positioner' })
+      // Act
+      render(
+        <SelectContent
+          alignOffset={6}
+          placement="top-end"
+          sideOffset={12}
+          positionerProps={{ 'role': 'group', 'aria-label': 'Select positioner' }}
+        >
+          <div>Option A</div>
+        </SelectContent>,
+      )
+
+      // Assert
+      const positioner = screen.getByRole('group', { name: /select positioner/i })
+      expect(mockParsePlacement).toHaveBeenCalledWith('top-end')
       expect(positioner).toHaveAttribute('data-side', 'top')
       expect(positioner).toHaveAttribute('data-align', 'end')
+      expect(positioner).toHaveAttribute('data-side-offset', '12')
+      expect(positioner).toHaveAttribute('data-align-offset', '6')
+      expect(positioner).toHaveAttribute('data-align-item-with-trigger', 'false')
     })
 
     it('should forward passthrough props to positioner popup and list when passthrough props are provided', () => {
-      const onPositionerMouseEnter = vi.fn()
-      const onPopupClick = vi.fn()
-      const onListFocus = vi.fn()
-
+      // Arrange & Act
       render(
-        <Select open defaultValue="seattle">
-          <SelectTrigger aria-label="city select">
-            <SelectValue />
-          </SelectTrigger>
-          <SelectContent
-            positionerProps={{
-              'role': 'group',
-              'aria-label': 'select positioner',
-              'id': 'select-positioner',
-              'onMouseEnter': onPositionerMouseEnter,
-            }}
-            popupProps={{
-              'role': 'dialog',
-              'aria-label': 'select popup',
-              'id': 'select-popup',
-              'onClick': onPopupClick,
-            }}
-            listProps={{
-              'role': 'listbox',
-              'aria-label': 'select list',
-              'id': 'select-list',
-              'onFocus': onListFocus,
-            }}
-          >
-            <SelectItem value="seattle">Seattle</SelectItem>
-          </SelectContent>
-        </Select>,
+        <SelectContent
+          positionerProps={{
+            'role': 'group',
+            'aria-label': 'select positioner',
+          }}
+          popupProps={{
+            'role': 'dialog',
+            'aria-label': 'select popup',
+          }}
+          listProps={{
+            'role': 'listbox',
+            'aria-label': 'select list',
+          }}
+        >
+          <div>Option A</div>
+        </SelectContent>,
       )
 
-      const positioner = screen.getByRole('group', { name: 'select positioner' })
-      const popup = screen.getByRole('dialog', { name: 'select popup' })
-      const list = screen.getByRole('listbox', { name: 'select list' })
+      // Assert
+      const positioner = screen.getByRole('group', { name: /select positioner/i })
+      const popup = screen.getByRole('dialog', { name: /select popup/i })
+      const list = screen.getByRole('listbox', { name: /select list/i })
 
-      fireEvent.mouseEnter(positioner)
-      fireEvent.click(popup)
-      fireEvent.focus(list)
-
-      expect(positioner).toHaveAttribute('id', 'select-positioner')
-      expect(popup).toHaveAttribute('id', 'select-popup')
-      expect(list).toHaveAttribute('id', 'select-list')
-      expect(onPositionerMouseEnter).toHaveBeenCalledTimes(1)
-      expect(onPopupClick).toHaveBeenCalledTimes(1)
-      expect(onListFocus).toHaveBeenCalledTimes(1)
+      expect(positioner).toHaveAttribute('aria-label', 'select positioner')
+      expect(popup).toHaveAttribute('role', 'dialog')
+      expect(popup).toHaveAttribute('aria-label', 'select popup')
+      expect(list).toHaveAttribute('role', 'listbox')
+      expect(list).toHaveAttribute('aria-label', 'select list')
     })
   })
 
+  // Covers option item rendering and prop forwarding behavior.
   describe('SelectItem', () => {
-    it('should render options when children are provided', () => {
-      renderOpenSelect()
+    it('should render item text and indicator when children are provided', () => {
+      // Arrange
+      render(<SelectItem>Seattle</SelectItem>)
 
-      expect(screen.getByRole('option', { name: 'Seattle' })).toBeInTheDocument()
-      expect(screen.getByRole('option', { name: 'New York' })).toBeInTheDocument()
+      // Assert
+      expect(screen.getByRole('option', { name: /seattle/i })).toBeInTheDocument()
+      expect(screen.getByRole('img', { name: /selected item indicator/i })).toBeInTheDocument()
     })
 
-    it('should not call onValueChange when disabled item is clicked', () => {
-      const onValueChange = vi.fn()
-
+    it('should forward item props when item props are provided', () => {
+      // Arrange
       render(
-        <Select open defaultValue="seattle" onValueChange={onValueChange}>
-          <SelectTrigger aria-label="city select">
-            <SelectValue />
-          </SelectTrigger>
-          <SelectContent listProps={{ 'role': 'listbox', 'aria-label': 'select list' }}>
-            <SelectItem value="seattle">Seattle</SelectItem>
-            <SelectItem value="new-york" disabled aria-label="Disabled New York">
-              New York
-            </SelectItem>
-          </SelectContent>
-        </Select>,
+        <SelectItem aria-label="City option" disabled>
+          Seattle
+        </SelectItem>,
       )
 
-      fireEvent.click(screen.getByRole('option', { name: 'Disabled New York' }))
-
-      expect(onValueChange).not.toHaveBeenCalled()
+      // Assert
+      const item = screen.getByRole('option', { name: /city option/i })
+      expect(item).toHaveAttribute('aria-label', 'City option')
+      expect(item).toHaveAttribute('disabled')
     })
   })
 })

web/app/components/base/ui/tooltip/__tests__/index.spec.tsx

@@ -1,95 +1,207 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react'
+import type { Placement } from '@/app/components/base/ui/placement'
 import { Tooltip as BaseTooltip } from '@base-ui/react/tooltip'
-import { fireEvent, render, screen } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '../index'
 
-describe('TooltipContent', () => {
-  describe('Placement and offsets', () => {
-    it('should use default top placement when placement is not provided', () => {
-      render(
-        <Tooltip open>
-          <TooltipTrigger aria-label="tooltip trigger">Trigger</TooltipTrigger>
-          <TooltipContent role="tooltip" aria-label="default tooltip">
-            Tooltip body
-          </TooltipContent>
-        </Tooltip>,
-      )
+type ParsedPlacement = {
+  side: 'top' | 'bottom' | 'left' | 'right'
+  align: 'start' | 'center' | 'end'
+}
 
-      const popup = screen.getByRole('tooltip', { name: 'default tooltip' })
-      expect(popup).toHaveAttribute('data-side', 'top')
-      expect(popup).toHaveAttribute('data-align', 'center')
-      expect(popup).toHaveTextContent('Tooltip body')
+type PositionerMockProps = ComponentPropsWithoutRef<'div'> & {
+  side?: ParsedPlacement['side']
+  align?: ParsedPlacement['align']
+  sideOffset?: number
+  alignOffset?: number
+}
+
+const positionerPropsSpy = vi.fn<(props: PositionerMockProps) => void>()
+const popupPropsSpy = vi.fn<(props: ComponentPropsWithoutRef<'div'>) => void>()
+const parsePlacementMock = vi.fn<(placement: Placement) => ParsedPlacement>()
+
+vi.mock('@/app/components/base/ui/placement', () => ({
+  parsePlacement: (placement: Placement) => parsePlacementMock(placement),
+}))
+
+vi.mock('@base-ui/react/tooltip', () => {
+  const Portal = ({ children }: { children?: ReactNode }) => (
+    <div>{children}</div>
+  )
+
+  const Positioner = ({ children, ...props }: PositionerMockProps) => {
+    positionerPropsSpy(props)
+    return <div>{children}</div>
+  }
+
+  const Popup = ({ children, className, ...props }: ComponentPropsWithoutRef<'div'>) => {
+    popupPropsSpy({ className, ...props })
+    return (
+      <div className={className} {...props}>
+        {children}
+      </div>
+    )
+  }
+
+  const Provider = ({ children }: { children?: ReactNode }) => (
+    <div>{children}</div>
+  )
+
+  const Root = ({ children }: { children?: ReactNode }) => (
+    <div>{children}</div>
+  )
+
+  const Trigger = ({ children }: { children?: ReactNode }) => (
+    <button type="button">
+      {children}
+    </button>
+  )
+
+  return {
+    Tooltip: {
+      Portal,
+      Positioner,
+      Popup,
+      Provider,
+      Root,
+      Trigger,
+    },
+  }
+})
+
+describe('TooltipContent', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    parsePlacementMock.mockReturnValue({ side: 'top', align: 'center' })
+  })
+
+  describe('Placement and offsets', () => {
+    it('should use default placement and offsets when optional props are not provided', () => {
+      // Arrange
+      render(<TooltipContent>Tooltip body</TooltipContent>)
+
+      // Act
+      const positionerProps = positionerPropsSpy.mock.calls.at(-1)?.[0]
+
+      // Assert
+      expect(parsePlacementMock).toHaveBeenCalledWith('top')
+      expect(positionerProps).toEqual(expect.objectContaining({
+        side: 'top',
+        align: 'center',
+        sideOffset: 8,
+        alignOffset: 0,
+      }))
+      expect(screen.getByText('Tooltip body')).toBeInTheDocument()
     })
 
-    it('should apply custom placement when placement props are provided', () => {
-      render(
-        <Tooltip open>
-          <TooltipTrigger aria-label="tooltip trigger">Trigger</TooltipTrigger>
-          <TooltipContent
-            placement="bottom-start"
-            sideOffset={16}
-            alignOffset={6}
-            role="tooltip"
-            aria-label="custom tooltip"
-          >
-            Custom tooltip body
-          </TooltipContent>
-        </Tooltip>,
-      )
+    it('should use parsed placement and custom offsets when placement props are provided', () => {
+      // Arrange
+      parsePlacementMock.mockReturnValue({ side: 'bottom', align: 'start' })
+      const customPlacement: Placement = 'bottom-start'
 
-      const popup = screen.getByRole('tooltip', { name: 'custom tooltip' })
-      expect(popup).toHaveAttribute('data-side', 'bottom')
-      expect(popup).toHaveAttribute('data-align', 'start')
-      expect(popup).toHaveTextContent('Custom tooltip body')
+      // Act
+      render(
+        <TooltipContent
+          placement={customPlacement}
+          sideOffset={16}
+          alignOffset={6}
+        >
+          Custom tooltip body
+        </TooltipContent>,
+      )
+      const positionerProps = positionerPropsSpy.mock.calls.at(-1)?.[0]
+
+      // Assert
+      expect(parsePlacementMock).toHaveBeenCalledWith(customPlacement)
+      expect(positionerProps).toEqual(expect.objectContaining({
+        side: 'bottom',
+        align: 'start',
+        sideOffset: 16,
+        alignOffset: 6,
+      }))
+      expect(screen.getByText('Custom tooltip body')).toBeInTheDocument()
     })
   })
 
-  describe('Variant and popup props', () => {
-    it('should render popup content when variant is plain', () => {
-      render(
-        <Tooltip open>
-          <TooltipTrigger aria-label="tooltip trigger">Trigger</TooltipTrigger>
-          <TooltipContent variant="plain" role="tooltip" aria-label="plain tooltip">
-            Plain tooltip body
-          </TooltipContent>
-        </Tooltip>,
+  describe('Variant behavior', () => {
+    it('should compute a different popup presentation contract for plain variant than default', () => {
+      // Arrange
+      const { rerender } = render(
+        <TooltipContent variant="default">
+          Default tooltip body
+        </TooltipContent>,
       )
+      const defaultPopupProps = popupPropsSpy.mock.calls.at(-1)?.[0]
 
-      expect(screen.getByRole('tooltip', { name: 'plain tooltip' })).toHaveTextContent('Plain tooltip body')
+      // Act
+      rerender(
+        <TooltipContent variant="plain">
+          Plain tooltip body
+        </TooltipContent>,
+      )
+      const plainPopupProps = popupPropsSpy.mock.calls.at(-1)?.[0]
+
+      // Assert
+      expect(screen.getByText('Plain tooltip body')).toBeInTheDocument()
+      expect(defaultPopupProps?.className).toBeTypeOf('string')
+      expect(plainPopupProps?.className).toBeTypeOf('string')
+      expect(plainPopupProps?.className).not.toBe(defaultPopupProps?.className)
     })
+  })
 
-    it('should forward popup props and handlers when popup props are provided', () => {
-      const onMouseEnter = vi.fn()
-
+  describe('Popup prop forwarding', () => {
+    it('should forward popup props to BaseTooltip.Popup when popup props are provided', () => {
+      // Arrange
       render(
-        <Tooltip open>
-          <TooltipTrigger aria-label="tooltip trigger">Trigger</TooltipTrigger>
-          <TooltipContent
-            id="tooltip-popup-id"
-            role="tooltip"
-            aria-label="help text"
-            data-track-id="tooltip-track"
-            onMouseEnter={onMouseEnter}
-          >
-            Tooltip body
-          </TooltipContent>
-        </Tooltip>,
+        <TooltipContent
+          id="popup-id"
+          role="tooltip"
+          aria-label="help text"
+          data-track-id="tooltip-track"
+        >
+          Tooltip body
+        </TooltipContent>,
       )
 
+      // Act
       const popup = screen.getByRole('tooltip', { name: 'help text' })
-      fireEvent.mouseEnter(popup)
+      const popupProps = popupPropsSpy.mock.calls.at(-1)?.[0]
 
-      expect(popup).toHaveAttribute('id', 'tooltip-popup-id')
+      // Assert
+      expect(popupProps).toEqual(expect.objectContaining({
+        'id': 'popup-id',
+        'role': 'tooltip',
+        'aria-label': 'help text',
+        'data-track-id': 'tooltip-track',
+      }))
+      expect(popup).toHaveAttribute('id', 'popup-id')
+      expect(popup).toHaveAttribute('role', 'tooltip')
+      expect(popup).toHaveAttribute('aria-label', 'help text')
       expect(popup).toHaveAttribute('data-track-id', 'tooltip-track')
-      expect(onMouseEnter).toHaveBeenCalledTimes(1)
     })
   })
 })
 
 describe('Tooltip aliases', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
   it('should map alias exports to BaseTooltip components when wrapper exports are imported', () => {
-    expect(TooltipProvider).toBe(BaseTooltip.Provider)
-    expect(Tooltip).toBe(BaseTooltip.Root)
-    expect(TooltipTrigger).toBe(BaseTooltip.Trigger)
+    // Arrange
+    const provider = BaseTooltip.Provider
+    const root = BaseTooltip.Root
+    const trigger = BaseTooltip.Trigger
+
+    // Act
+    const exportedProvider = TooltipProvider
+    const exportedTooltip = Tooltip
+    const exportedTrigger = TooltipTrigger
+
+    // Assert
+    expect(exportedProvider).toBe(provider)
+    expect(exportedTooltip).toBe(root)
+    expect(exportedTrigger).toBe(trigger)
   })
 })

web/app/components/datasets/documents/__tests__/index.spec.tsx

@@ -4,7 +4,7 @@ import { useDatasetDetailContextWithSelector } from '@/context/dataset-detail'
 import { useProviderContext } from '@/context/provider-context'
 import { DataSourceType } from '@/models/datasets'
 import { useDocumentList } from '@/service/knowledge/use-document'
-import { useDocumentsPageState } from '../hooks/use-documents-page-state'
+import useDocumentsPageState from '../hooks/use-documents-page-state'
 import Documents from '../index'
 
 // Type for mock selector function - use `as MockState` to bypass strict type checking in tests
@@ -117,10 +117,13 @@ const mockHandleStatusFilterClear = vi.fn()
 const mockHandleSortChange = vi.fn()
 const mockHandlePageChange = vi.fn()
 const mockHandleLimitChange = vi.fn()
+const mockUpdatePollingState = vi.fn()
+const mockAdjustPageForTotal = vi.fn()
 
 vi.mock('../hooks/use-documents-page-state', () => ({
-  useDocumentsPageState: vi.fn(() => ({
+  default: vi.fn(() => ({
     inputValue: '',
+    searchValue: '',
     debouncedSearchValue: '',
     handleInputChange: mockHandleInputChange,
     statusFilterValue: 'all',
@@ -135,6 +138,9 @@ vi.mock('../hooks/use-documents-page-state', () => ({
     handleLimitChange: mockHandleLimitChange,
     selectedIds: [] as string[],
     setSelectedIds: mockSetSelectedIds,
+    timerCanRun: false,
+    updatePollingState: mockUpdatePollingState,
+    adjustPageForTotal: mockAdjustPageForTotal,
   })),
 }))
 
@@ -313,33 +319,6 @@ describe('Documents', () => {
       expect(screen.queryByTestId('documents-list')).not.toBeInTheDocument()
     })
 
-    it('should keep rendering list when loading with existing data', () => {
-      vi.mocked(useDocumentList).mockReturnValueOnce({
-        data: {
-          data: [
-            {
-              id: 'doc-1',
-              name: 'Document 1',
-              indexing_status: 'completed',
-              data_source_type: 'upload_file',
-              position: 1,
-              enabled: true,
-            },
-          ],
-          total: 1,
-          page: 1,
-          limit: 10,
-          has_more: false,
-        } as DocumentListResponse,
-        isLoading: true,
-        refetch: vi.fn(),
-      } as unknown as ReturnType<typeof useDocumentList>)
-
-      render(<Documents {...defaultProps} />)
-      expect(screen.getByTestId('documents-list')).toBeInTheDocument()
-      expect(screen.getByTestId('list-documents-count')).toHaveTextContent('1')
-    })
-
     it('should render empty element when no documents exist', () => {
       vi.mocked(useDocumentList).mockReturnValueOnce({
         data: { data: [], total: 0, page: 1, limit: 10, has_more: false },
@@ -505,75 +484,17 @@ describe('Documents', () => {
     })
   })
 
-  describe('Query Options', () => {
-    it('should pass function refetchInterval to useDocumentList', () => {
+  describe('Side Effects and Cleanup', () => {
+    it('should call updatePollingState when documents response changes', () => {
       render(<Documents {...defaultProps} />)
 
-      const payload = vi.mocked(useDocumentList).mock.calls.at(-1)?.[0]
-      expect(payload).toBeDefined()
-      expect(typeof payload?.refetchInterval).toBe('function')
+      expect(mockUpdatePollingState).toHaveBeenCalled()
     })
 
-    it('should stop polling when all documents are in terminal statuses', () => {
+    it('should call adjustPageForTotal when documents response changes', () => {
       render(<Documents {...defaultProps} />)
 
-      const payload = vi.mocked(useDocumentList).mock.calls.at(-1)?.[0]
-      const refetchInterval = payload?.refetchInterval
-      expect(typeof refetchInterval).toBe('function')
-      if (typeof refetchInterval !== 'function')
-        throw new Error('Expected function refetchInterval')
-
-      const interval = refetchInterval({
-        state: {
-          data: {
-            data: [
-              { indexing_status: 'completed' },
-              { indexing_status: 'paused' },
-              { indexing_status: 'error' },
-            ],
-          },
-        },
-      } as unknown as Parameters<typeof refetchInterval>[0])
-
-      expect(interval).toBe(false)
-    })
-
-    it('should keep polling for transient status filters', () => {
-      vi.mocked(useDocumentsPageState).mockReturnValueOnce({
-        inputValue: '',
-        debouncedSearchValue: '',
-        handleInputChange: mockHandleInputChange,
-        statusFilterValue: 'indexing',
-        sortValue: '-created_at' as const,
-        normalizedStatusFilterValue: 'indexing',
-        handleStatusFilterChange: mockHandleStatusFilterChange,
-        handleStatusFilterClear: mockHandleStatusFilterClear,
-        handleSortChange: mockHandleSortChange,
-        currPage: 0,
-        limit: 10,
-        handlePageChange: mockHandlePageChange,
-        handleLimitChange: mockHandleLimitChange,
-        selectedIds: [] as string[],
-        setSelectedIds: mockSetSelectedIds,
-      })
-
-      render(<Documents {...defaultProps} />)
-
-      const payload = vi.mocked(useDocumentList).mock.calls.at(-1)?.[0]
-      const refetchInterval = payload?.refetchInterval
-      expect(typeof refetchInterval).toBe('function')
-      if (typeof refetchInterval !== 'function')
-        throw new Error('Expected function refetchInterval')
-
-      const interval = refetchInterval({
-        state: {
-          data: {
-            data: [{ indexing_status: 'completed' }],
-          },
-        },
-      } as unknown as Parameters<typeof refetchInterval>[0])
-
-      expect(interval).toBe(2500)
+      expect(mockAdjustPageForTotal).toHaveBeenCalled()
     })
   })
 
@@ -670,6 +591,36 @@ describe('Documents', () => {
     })
   })
 
+  describe('Polling State', () => {
+    it('should enable polling when documents are indexing', () => {
+      vi.mocked(useDocumentsPageState).mockReturnValueOnce({
+        inputValue: '',
+        searchValue: '',
+        debouncedSearchValue: '',
+        handleInputChange: mockHandleInputChange,
+        statusFilterValue: 'all',
+        sortValue: '-created_at' as const,
+        normalizedStatusFilterValue: 'all',
+        handleStatusFilterChange: mockHandleStatusFilterChange,
+        handleStatusFilterClear: mockHandleStatusFilterClear,
+        handleSortChange: mockHandleSortChange,
+        currPage: 0,
+        limit: 10,
+        handlePageChange: mockHandlePageChange,
+        handleLimitChange: mockHandleLimitChange,
+        selectedIds: [] as string[],
+        setSelectedIds: mockSetSelectedIds,
+        timerCanRun: true,
+        updatePollingState: mockUpdatePollingState,
+        adjustPageForTotal: mockAdjustPageForTotal,
+      })
+
+      render(<Documents {...defaultProps} />)
+
+      expect(screen.getByTestId('documents-list')).toBeInTheDocument()
+    })
+  })
+
   describe('Pagination', () => {
     it('should display correct total in list', () => {
       render(<Documents {...defaultProps} />)
@@ -684,6 +635,7 @@ describe('Documents', () => {
     it('should handle page changes', () => {
       vi.mocked(useDocumentsPageState).mockReturnValueOnce({
         inputValue: '',
+        searchValue: '',
         debouncedSearchValue: '',
         handleInputChange: mockHandleInputChange,
         statusFilterValue: 'all',
@@ -698,6 +650,9 @@ describe('Documents', () => {
         handleLimitChange: mockHandleLimitChange,
         selectedIds: [] as string[],
         setSelectedIds: mockSetSelectedIds,
+        timerCanRun: false,
+        updatePollingState: mockUpdatePollingState,
+        adjustPageForTotal: mockAdjustPageForTotal,
       })
 
       render(<Documents {...defaultProps} />)
@@ -709,6 +664,7 @@ describe('Documents', () => {
     it('should display selected count', () => {
       vi.mocked(useDocumentsPageState).mockReturnValueOnce({
         inputValue: '',
+        searchValue: '',
         debouncedSearchValue: '',
         handleInputChange: mockHandleInputChange,
         statusFilterValue: 'all',
@@ -723,6 +679,9 @@ describe('Documents', () => {
         handleLimitChange: mockHandleLimitChange,
         selectedIds: ['doc-1', 'doc-2'],
         setSelectedIds: mockSetSelectedIds,
+        timerCanRun: false,
+        updatePollingState: mockUpdatePollingState,
+        adjustPageForTotal: mockAdjustPageForTotal,
       })
 
       render(<Documents {...defaultProps} />)
@@ -734,6 +693,7 @@ describe('Documents', () => {
     it('should pass filter value to list', () => {
       vi.mocked(useDocumentsPageState).mockReturnValueOnce({
         inputValue: 'test search',
+        searchValue: 'test search',
         debouncedSearchValue: 'test search',
         handleInputChange: mockHandleInputChange,
         statusFilterValue: 'completed',
@@ -748,6 +708,9 @@ describe('Documents', () => {
         handleLimitChange: mockHandleLimitChange,
         selectedIds: [] as string[],
         setSelectedIds: mockSetSelectedIds,
+        timerCanRun: false,
+        updatePollingState: mockUpdatePollingState,
+        adjustPageForTotal: mockAdjustPageForTotal,
       })
 
       render(<Documents {...defaultProps} />)

web/app/components/datasets/documents/components/__tests__/list.spec.tsx

@@ -20,8 +20,9 @@ const mockHandleSave = vi.fn()
 vi.mock('../document-list/hooks', () => ({
   useDocumentSort: vi.fn(() => ({
     sortField: null,
-    sortOrder: 'desc',
+    sortOrder: null,
     handleSort: mockHandleSort,
+    sortedDocuments: [],
   })),
   useDocumentSelection: vi.fn(() => ({
     isAllSelected: false,
@@ -124,8 +125,8 @@ const defaultProps = {
   pagination: { total: 0, current: 1, limit: 10, onChange: vi.fn() },
   onUpdate: vi.fn(),
   onManageMetadata: vi.fn(),
-  remoteSortValue: '-created_at',
-  onSortChange: vi.fn(),
+  statusFilterValue: 'all',
+  remoteSortValue: '',
 }
 
 describe('DocumentList', () => {
@@ -139,6 +140,8 @@ describe('DocumentList', () => {
       render(<DocumentList {...defaultProps} />)
 
       expect(screen.getByText('#')).toBeInTheDocument()
+      expect(screen.getByTestId('sort-name')).toBeInTheDocument()
+      expect(screen.getByTestId('sort-word_count')).toBeInTheDocument()
       expect(screen.getByTestId('sort-hit_count')).toBeInTheDocument()
       expect(screen.getByTestId('sort-created_at')).toBeInTheDocument()
     })
@@ -161,9 +164,10 @@ describe('DocumentList', () => {
     it('should render document rows from sortedDocuments', () => {
       const docs = [createDoc({ id: 'a', name: 'Doc A' }), createDoc({ id: 'b', name: 'Doc B' })]
       vi.mocked(useDocumentSort).mockReturnValue({
-        sortField: 'created_at',
+        sortField: null,
         sortOrder: 'desc',
         handleSort: mockHandleSort,
+        sortedDocuments: docs,
       } as unknown as ReturnType<typeof useDocumentSort>)
 
       render(<DocumentList {...defaultProps} documents={docs} />)
@@ -178,9 +182,9 @@ describe('DocumentList', () => {
     it('should call handleSort when sort header is clicked', () => {
       render(<DocumentList {...defaultProps} />)
 
-      fireEvent.click(screen.getByTestId('sort-created_at'))
+      fireEvent.click(screen.getByTestId('sort-name'))
 
-      expect(mockHandleSort).toHaveBeenCalledWith('created_at')
+      expect(mockHandleSort).toHaveBeenCalledWith('name')
     })
   })
 
@@ -225,6 +229,7 @@ describe('DocumentList', () => {
         sortField: null,
         sortOrder: 'desc',
         handleSort: mockHandleSort,
+        sortedDocuments: [],
       } as unknown as ReturnType<typeof useDocumentSort>)
 
       render(<DocumentList {...defaultProps} documents={[]} />)

web/app/components/datasets/documents/components/document-list/__tests__/index.spec.tsx

@@ -2,7 +2,7 @@ import type { ReactNode } from 'react'
 import type { Props as PaginationProps } from '@/app/components/base/pagination'
 import type { SimpleDocumentDetail } from '@/models/datasets'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { act, fireEvent, render, screen } from '@testing-library/react'
+import { fireEvent, render, screen } from '@testing-library/react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { ChunkingMode, DataSourceType } from '@/models/datasets'
 import DocumentList from '../../list'
@@ -13,7 +13,6 @@ vi.mock('next/navigation', () => ({
   useRouter: () => ({
     push: mockPush,
   }),
-  useSearchParams: () => new URLSearchParams(),
 }))
 
 vi.mock('@/context/dataset-detail', () => ({
@@ -91,8 +90,8 @@ describe('DocumentList', () => {
     pagination: defaultPagination,
     onUpdate: vi.fn(),
     onManageMetadata: vi.fn(),
-    remoteSortValue: '-created_at',
-    onSortChange: vi.fn(),
+    statusFilterValue: '',
+    remoteSortValue: '',
   }
 
   beforeEach(() => {
@@ -221,15 +220,16 @@ describe('DocumentList', () => {
       expect(sortIcons.length).toBeGreaterThan(0)
     })
 
-    it('should call onSortChange when sortable header is clicked', () => {
-      const onSortChange = vi.fn()
-      const { container } = render(<DocumentList {...defaultProps} onSortChange={onSortChange} />, { wrapper: createWrapper() })
+    it('should update sort order when sort header is clicked', () => {
+      render(<DocumentList {...defaultProps} />, { wrapper: createWrapper() })
 
-      const sortableHeaders = container.querySelectorAll('thead button')
-      if (sortableHeaders.length > 0)
+      // Find and click a sort header by its parent div containing the label text
+      const sortableHeaders = document.querySelectorAll('[class*="cursor-pointer"]')
+      if (sortableHeaders.length > 0) {
         fireEvent.click(sortableHeaders[0])
+      }
 
-      expect(onSortChange).toHaveBeenCalled()
+      expect(screen.getByRole('table')).toBeInTheDocument()
     })
   })
 
@@ -360,15 +360,13 @@ describe('DocumentList', () => {
       expect(modal).not.toBeInTheDocument()
     })
 
-    it('should show rename modal when rename button is clicked', async () => {
+    it('should show rename modal when rename button is clicked', () => {
       const { container } = render(<DocumentList {...defaultProps} />, { wrapper: createWrapper() })
 
       // Find and click the rename button in the first row
       const renameButtons = container.querySelectorAll('.cursor-pointer.rounded-md')
       if (renameButtons.length > 0) {
-        await act(async () => {
-          fireEvent.click(renameButtons[0])
-        })
+        fireEvent.click(renameButtons[0])
       }
 
       // After clicking rename, the modal should potentially be visible
@@ -386,7 +384,7 @@ describe('DocumentList', () => {
   })
 
   describe('Edit Metadata Modal', () => {
-    it('should handle edit metadata action', async () => {
+    it('should handle edit metadata action', () => {
       const props = {
         ...defaultProps,
         selectedIds: ['doc-1'],
@@ -395,9 +393,7 @@ describe('DocumentList', () => {
 
       const editButton = screen.queryByRole('button', { name: /metadata/i })
       if (editButton) {
-        await act(async () => {
-          fireEvent.click(editButton)
-        })
+        fireEvent.click(editButton)
       }
 
       expect(screen.getByRole('table')).toBeInTheDocument()
@@ -458,6 +454,16 @@ describe('DocumentList', () => {
       expect(screen.getByRole('table')).toBeInTheDocument()
     })
 
+    it('should handle status filter value', () => {
+      const props = {
+        ...defaultProps,
+        statusFilterValue: 'completed',
+      }
+      render(<DocumentList {...props} />, { wrapper: createWrapper() })
+
+      expect(screen.getByRole('table')).toBeInTheDocument()
+    })
+
     it('should handle remote sort value', () => {
       const props = {
         ...defaultProps,

web/app/components/datasets/documents/components/document-list/components/__tests__/document-table-row.spec.tsx

@@ -7,13 +7,11 @@ import { DataSourceType } from '@/models/datasets'
 import DocumentTableRow from '../document-table-row'
 
 const mockPush = vi.fn()
-let mockSearchParams = ''
 
 vi.mock('next/navigation', () => ({
   useRouter: () => ({
     push: mockPush,
   }),
-  useSearchParams: () => new URLSearchParams(mockSearchParams),
 }))
 
 const createTestQueryClient = () => new QueryClient({
@@ -97,7 +95,6 @@ describe('DocumentTableRow', () => {
 
   beforeEach(() => {
     vi.clearAllMocks()
-    mockSearchParams = ''
   })
 
   describe('Rendering', () => {
@@ -189,15 +186,6 @@ describe('DocumentTableRow', () => {
 
       expect(mockPush).toHaveBeenCalledWith('/datasets/custom-dataset/documents/custom-doc')
     })
-
-    it('should preserve search params when navigating to detail', () => {
-      mockSearchParams = 'page=2&status=error'
-      render(<DocumentTableRow {...defaultProps} />, { wrapper: createWrapper() })
-
-      fireEvent.click(screen.getByRole('row'))
-
-      expect(mockPush).toHaveBeenCalledWith('/datasets/dataset-1/documents/doc-1?page=2&status=error')
-    })
   })
 
   describe('Word Count Display', () => {

web/app/components/datasets/documents/components/document-list/components/__tests__/sort-header.spec.tsx

@@ -4,8 +4,8 @@ import SortHeader from '../sort-header'
 
 describe('SortHeader', () => {
   const defaultProps = {
-    field: 'created_at' as const,
-    label: 'Upload Time',
+    field: 'name' as const,
+    label: 'File Name',
     currentSortField: null,
     sortOrder: 'desc' as const,
     onSort: vi.fn(),
@@ -14,12 +14,12 @@ describe('SortHeader', () => {
   describe('rendering', () => {
     it('should render the label', () => {
       render(<SortHeader {...defaultProps} />)
-      expect(screen.getByText('Upload Time')).toBeInTheDocument()
+      expect(screen.getByText('File Name')).toBeInTheDocument()
     })
 
     it('should render the sort icon', () => {
       const { container } = render(<SortHeader {...defaultProps} />)
-      const icon = container.querySelector('button span')
+      const icon = container.querySelector('svg')
       expect(icon).toBeInTheDocument()
     })
   })
@@ -27,13 +27,13 @@ describe('SortHeader', () => {
   describe('inactive state', () => {
     it('should have disabled text color when not active', () => {
       const { container } = render(<SortHeader {...defaultProps} />)
-      const icon = container.querySelector('button span')
+      const icon = container.querySelector('svg')
       expect(icon).toHaveClass('text-text-disabled')
     })
 
     it('should not be rotated when not active', () => {
       const { container } = render(<SortHeader {...defaultProps} />)
-      const icon = container.querySelector('button span')
+      const icon = container.querySelector('svg')
       expect(icon).not.toHaveClass('rotate-180')
     })
   })
@@ -41,25 +41,25 @@ describe('SortHeader', () => {
   describe('active state', () => {
     it('should have tertiary text color when active', () => {
       const { container } = render(
-        <SortHeader {...defaultProps} currentSortField="created_at" />,
+        <SortHeader {...defaultProps} currentSortField="name" />,
       )
-      const icon = container.querySelector('button span')
+      const icon = container.querySelector('svg')
       expect(icon).toHaveClass('text-text-tertiary')
     })
 
     it('should not be rotated when active and desc', () => {
       const { container } = render(
-        <SortHeader {...defaultProps} currentSortField="created_at" sortOrder="desc" />,
+        <SortHeader {...defaultProps} currentSortField="name" sortOrder="desc" />,
       )
-      const icon = container.querySelector('button span')
+      const icon = container.querySelector('svg')
       expect(icon).not.toHaveClass('rotate-180')
     })
 
     it('should be rotated when active and asc', () => {
       const { container } = render(
-        <SortHeader {...defaultProps} currentSortField="created_at" sortOrder="asc" />,
+        <SortHeader {...defaultProps} currentSortField="name" sortOrder="asc" />,
       )
-      const icon = container.querySelector('button span')
+      const icon = container.querySelector('svg')
       expect(icon).toHaveClass('rotate-180')
     })
   })
@@ -69,22 +69,34 @@ describe('SortHeader', () => {
       const onSort = vi.fn()
       render(<SortHeader {...defaultProps} onSort={onSort} />)
 
-      fireEvent.click(screen.getByText('Upload Time'))
+      fireEvent.click(screen.getByText('File Name'))
 
-      expect(onSort).toHaveBeenCalledWith('created_at')
+      expect(onSort).toHaveBeenCalledWith('name')
     })
 
     it('should call onSort with correct field', () => {
       const onSort = vi.fn()
-      render(<SortHeader {...defaultProps} field="hit_count" onSort={onSort} />)
+      render(<SortHeader {...defaultProps} field="word_count" onSort={onSort} />)
 
-      fireEvent.click(screen.getByText('Upload Time'))
+      fireEvent.click(screen.getByText('File Name'))
 
-      expect(onSort).toHaveBeenCalledWith('hit_count')
+      expect(onSort).toHaveBeenCalledWith('word_count')
     })
   })
 
   describe('different fields', () => {
+    it('should work with word_count field', () => {
+      render(
+        <SortHeader
+          {...defaultProps}
+          field="word_count"
+          label="Words"
+          currentSortField="word_count"
+        />,
+      )
+      expect(screen.getByText('Words')).toBeInTheDocument()
+    })
+
     it('should work with hit_count field', () => {
       render(
         <SortHeader

web/app/components/datasets/documents/components/document-list/components/document-table-row.tsx

@@ -1,7 +1,8 @@
 import type { FC } from 'react'
 import type { SimpleDocumentDetail } from '@/models/datasets'
+import { RiEditLine } from '@remixicon/react'
 import { pick } from 'es-toolkit/object'
-import { useRouter, useSearchParams } from 'next/navigation'
+import { useRouter } from 'next/navigation'
 import * as React from 'react'
 import { useCallback } from 'react'
 import { useTranslation } from 'react-i18next'
@@ -61,15 +62,13 @@ const DocumentTableRow: FC<DocumentTableRowProps> = React.memo(({
   const { t } = useTranslation()
   const { formatTime } = useTimestamp()
   const router = useRouter()
-  const searchParams = useSearchParams()
 
   const isFile = doc.data_source_type === DataSourceType.FILE
   const fileType = isFile ? doc.data_source_detail_dict?.upload_file?.extension : ''
-  const queryString = searchParams.toString()
 
   const handleRowClick = useCallback(() => {
-    router.push(`/datasets/${datasetId}/documents/${doc.id}${queryString ? `?${queryString}` : ''}`)
-  }, [router, datasetId, doc.id, queryString])
+    router.push(`/datasets/${datasetId}/documents/${doc.id}`)
+  }, [router, datasetId, doc.id])
 
   const handleCheckboxClick = useCallback((e: React.MouseEvent) => {
     e.stopPropagation()
@@ -101,7 +100,7 @@ const DocumentTableRow: FC<DocumentTableRowProps> = React.memo(({
             <DocumentSourceIcon doc={doc} fileType={fileType} />
           </div>
           <Tooltip popupContent={doc.name}>
-            <span className="grow truncate text-sm">{doc.name}</span>
+            <span className="grow-1 truncate text-sm">{doc.name}</span>
           </Tooltip>
           {doc.summary_index_status && (
             <div className="ml-1 hidden shrink-0 group-hover:flex">
@@ -114,7 +113,7 @@ const DocumentTableRow: FC<DocumentTableRowProps> = React.memo(({
                 className="cursor-pointer rounded-md p-1 hover:bg-state-base-hover"
                 onClick={handleRenameClick}
               >
-                <span className="i-ri-edit-line h-4 w-4 text-text-tertiary" />
+                <RiEditLine className="h-4 w-4 text-text-tertiary" />
               </div>
             </Tooltip>
           </div>

web/app/components/datasets/documents/components/document-list/components/sort-header.tsx

@@ -1,5 +1,6 @@
 import type { FC } from 'react'
 import type { SortField, SortOrder } from '../hooks'
+import { RiArrowDownLine } from '@remixicon/react'
 import * as React from 'react'
 import { cn } from '@/utils/classnames'
 
@@ -22,20 +23,19 @@ const SortHeader: FC<SortHeaderProps> = React.memo(({
   const isDesc = isActive && sortOrder === 'desc'
 
   return (
-    <button
-      type="button"
-      className="flex items-center bg-transparent p-0 text-left hover:text-text-secondary"
+    <div
+      className="flex cursor-pointer items-center hover:text-text-secondary"
       onClick={() => onSort(field)}
     >
       {label}
-      <span
+      <RiArrowDownLine
         className={cn(
-          'i-ri-arrow-down-line ml-0.5 h-3 w-3 transition-all',
+          'ml-0.5 h-3 w-3 transition-all',
           isActive ? 'text-text-tertiary' : 'text-text-disabled',
           isActive && !isDesc ? 'rotate-180' : '',
         )}
       />
-    </button>
+    </div>
   )
 })
 

web/app/components/datasets/documents/components/document-list/hooks/__tests__/use-document-sort.spec.ts

@@ -1,98 +1,340 @@
+import type { SimpleDocumentDetail } from '@/models/datasets'
 import { act, renderHook } from '@testing-library/react'
-import { describe, expect, it, vi } from 'vitest'
+import { describe, expect, it } from 'vitest'
 import { useDocumentSort } from '../use-document-sort'
 
-describe('useDocumentSort', () => {
-  describe('remote state parsing', () => {
-    it('should parse descending created_at sort', () => {
-      const onRemoteSortChange = vi.fn()
-      const { result } = renderHook(() => useDocumentSort({
-        remoteSortValue: '-created_at',
-        onRemoteSortChange,
-      }))
+type LocalDoc = SimpleDocumentDetail & { percent?: number }
 
-      expect(result.current.sortField).toBe('created_at')
+const createMockDocument = (overrides: Partial<LocalDoc> = {}): LocalDoc => ({
+  id: 'doc1',
+  name: 'Test Document',
+  data_source_type: 'upload_file',
+  data_source_info: {},
+  data_source_detail_dict: {},
+  word_count: 100,
+  hit_count: 10,
+  created_at: 1000000,
+  position: 1,
+  doc_form: 'text_model',
+  enabled: true,
+  archived: false,
+  display_status: 'available',
+  created_from: 'api',
+  ...overrides,
+} as LocalDoc)
+
+describe('useDocumentSort', () => {
+  describe('initial state', () => {
+    it('should return null sortField initially', () => {
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: [],
+          statusFilterValue: '',
+          remoteSortValue: '',
+        }),
+      )
+
+      expect(result.current.sortField).toBeNull()
       expect(result.current.sortOrder).toBe('desc')
     })
 
-    it('should parse ascending hit_count sort', () => {
-      const onRemoteSortChange = vi.fn()
-      const { result } = renderHook(() => useDocumentSort({
-        remoteSortValue: 'hit_count',
-        onRemoteSortChange,
-      }))
+    it('should return documents unchanged when no sort is applied', () => {
+      const docs = [
+        createMockDocument({ id: 'doc1', name: 'B' }),
+        createMockDocument({ id: 'doc2', name: 'A' }),
+      ]
 
-      expect(result.current.sortField).toBe('hit_count')
-      expect(result.current.sortOrder).toBe('asc')
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: docs,
+          statusFilterValue: '',
+          remoteSortValue: '',
+        }),
+      )
+
+      expect(result.current.sortedDocuments).toEqual(docs)
+    })
+  })
+
+  describe('handleSort', () => {
+    it('should set sort field when called', () => {
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: [],
+          statusFilterValue: '',
+          remoteSortValue: '',
+        }),
+      )
+
+      act(() => {
+        result.current.handleSort('name')
+      })
+
+      expect(result.current.sortField).toBe('name')
+      expect(result.current.sortOrder).toBe('desc')
     })
 
-    it('should fallback to inactive field for unsupported sort key', () => {
-      const onRemoteSortChange = vi.fn()
-      const { result } = renderHook(() => useDocumentSort({
-        remoteSortValue: '-name',
-        onRemoteSortChange,
-      }))
+    it('should toggle sort order when same field is clicked twice', () => {
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: [],
+          statusFilterValue: '',
+          remoteSortValue: '',
+        }),
+      )
+
+      act(() => {
+        result.current.handleSort('name')
+      })
+      expect(result.current.sortOrder).toBe('desc')
+
+      act(() => {
+        result.current.handleSort('name')
+      })
+      expect(result.current.sortOrder).toBe('asc')
+
+      act(() => {
+        result.current.handleSort('name')
+      })
+      expect(result.current.sortOrder).toBe('desc')
+    })
+
+    it('should reset to desc when different field is selected', () => {
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: [],
+          statusFilterValue: '',
+          remoteSortValue: '',
+        }),
+      )
+
+      act(() => {
+        result.current.handleSort('name')
+      })
+      act(() => {
+        result.current.handleSort('name')
+      })
+      expect(result.current.sortOrder).toBe('asc')
+
+      act(() => {
+        result.current.handleSort('word_count')
+      })
+      expect(result.current.sortField).toBe('word_count')
+      expect(result.current.sortOrder).toBe('desc')
+    })
+
+    it('should not change state when null is passed', () => {
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: [],
+          statusFilterValue: '',
+          remoteSortValue: '',
+        }),
+      )
+
+      act(() => {
+        result.current.handleSort(null)
+      })
+
+      expect(result.current.sortField).toBeNull()
+    })
+  })
+
+  describe('sorting documents', () => {
+    const docs = [
+      createMockDocument({ id: 'doc1', name: 'Banana', word_count: 200, hit_count: 5, created_at: 3000 }),
+      createMockDocument({ id: 'doc2', name: 'Apple', word_count: 100, hit_count: 10, created_at: 1000 }),
+      createMockDocument({ id: 'doc3', name: 'Cherry', word_count: 300, hit_count: 1, created_at: 2000 }),
+    ]
+
+    it('should sort by name descending', () => {
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: docs,
+          statusFilterValue: '',
+          remoteSortValue: '',
+        }),
+      )
+
+      act(() => {
+        result.current.handleSort('name')
+      })
+
+      const names = result.current.sortedDocuments.map(d => d.name)
+      expect(names).toEqual(['Cherry', 'Banana', 'Apple'])
+    })
+
+    it('should sort by name ascending', () => {
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: docs,
+          statusFilterValue: '',
+          remoteSortValue: '',
+        }),
+      )
+
+      act(() => {
+        result.current.handleSort('name')
+      })
+      act(() => {
+        result.current.handleSort('name')
+      })
+
+      const names = result.current.sortedDocuments.map(d => d.name)
+      expect(names).toEqual(['Apple', 'Banana', 'Cherry'])
+    })
+
+    it('should sort by word_count descending', () => {
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: docs,
+          statusFilterValue: '',
+          remoteSortValue: '',
+        }),
+      )
+
+      act(() => {
+        result.current.handleSort('word_count')
+      })
+
+      const counts = result.current.sortedDocuments.map(d => d.word_count)
+      expect(counts).toEqual([300, 200, 100])
+    })
+
+    it('should sort by hit_count ascending', () => {
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: docs,
+          statusFilterValue: '',
+          remoteSortValue: '',
+        }),
+      )
+
+      act(() => {
+        result.current.handleSort('hit_count')
+      })
+      act(() => {
+        result.current.handleSort('hit_count')
+      })
+
+      const counts = result.current.sortedDocuments.map(d => d.hit_count)
+      expect(counts).toEqual([1, 5, 10])
+    })
+
+    it('should sort by created_at descending', () => {
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: docs,
+          statusFilterValue: '',
+          remoteSortValue: '',
+        }),
+      )
+
+      act(() => {
+        result.current.handleSort('created_at')
+      })
+
+      const times = result.current.sortedDocuments.map(d => d.created_at)
+      expect(times).toEqual([3000, 2000, 1000])
+    })
+  })
+
+  describe('status filtering', () => {
+    const docs = [
+      createMockDocument({ id: 'doc1', display_status: 'available' }),
+      createMockDocument({ id: 'doc2', display_status: 'error' }),
+      createMockDocument({ id: 'doc3', display_status: 'available' }),
+    ]
+
+    it('should not filter when statusFilterValue is empty', () => {
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: docs,
+          statusFilterValue: '',
+          remoteSortValue: '',
+        }),
+      )
+
+      expect(result.current.sortedDocuments.length).toBe(3)
+    })
+
+    it('should not filter when statusFilterValue is all', () => {
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: docs,
+          statusFilterValue: 'all',
+          remoteSortValue: '',
+        }),
+      )
+
+      expect(result.current.sortedDocuments.length).toBe(3)
+    })
+  })
+
+  describe('remoteSortValue reset', () => {
+    it('should reset sort state when remoteSortValue changes', () => {
+      const { result, rerender } = renderHook(
+        ({ remoteSortValue }) =>
+          useDocumentSort({
+            documents: [],
+            statusFilterValue: '',
+            remoteSortValue,
+          }),
+        { initialProps: { remoteSortValue: 'initial' } },
+      )
+
+      act(() => {
+        result.current.handleSort('name')
+      })
+      act(() => {
+        result.current.handleSort('name')
+      })
+      expect(result.current.sortField).toBe('name')
+      expect(result.current.sortOrder).toBe('asc')
+
+      rerender({ remoteSortValue: 'changed' })
 
       expect(result.current.sortField).toBeNull()
       expect(result.current.sortOrder).toBe('desc')
     })
   })
 
-  describe('handleSort', () => {
-    it('should switch to desc when selecting a different field', () => {
-      const onRemoteSortChange = vi.fn()
-      const { result } = renderHook(() => useDocumentSort({
-        remoteSortValue: '-created_at',
-        onRemoteSortChange,
-      }))
+  describe('edge cases', () => {
+    it('should handle documents with missing values', () => {
+      const docs = [
+        createMockDocument({ id: 'doc1', name: undefined as unknown as string, word_count: undefined }),
+        createMockDocument({ id: 'doc2', name: 'Test', word_count: 100 }),
+      ]
+
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: docs,
+          statusFilterValue: '',
+          remoteSortValue: '',
+        }),
+      )
 
       act(() => {
-        result.current.handleSort('hit_count')
+        result.current.handleSort('name')
       })
 
-      expect(onRemoteSortChange).toHaveBeenCalledWith('-hit_count')
+      expect(result.current.sortedDocuments.length).toBe(2)
     })
 
-    it('should toggle desc -> asc when clicking active field', () => {
-      const onRemoteSortChange = vi.fn()
-      const { result } = renderHook(() => useDocumentSort({
-        remoteSortValue: '-hit_count',
-        onRemoteSortChange,
-      }))
+    it('should handle empty documents array', () => {
+      const { result } = renderHook(() =>
+        useDocumentSort({
+          documents: [],
+          statusFilterValue: '',
+          remoteSortValue: '',
+        }),
+      )
 
       act(() => {
-        result.current.handleSort('hit_count')
+        result.current.handleSort('name')
       })
 
-      expect(onRemoteSortChange).toHaveBeenCalledWith('hit_count')
-    })
-
-    it('should toggle asc -> desc when clicking active field', () => {
-      const onRemoteSortChange = vi.fn()
-      const { result } = renderHook(() => useDocumentSort({
-        remoteSortValue: 'created_at',
-        onRemoteSortChange,
-      }))
-
-      act(() => {
-        result.current.handleSort('created_at')
-      })
-
-      expect(onRemoteSortChange).toHaveBeenCalledWith('-created_at')
-    })
-
-    it('should ignore null field', () => {
-      const onRemoteSortChange = vi.fn()
-      const { result } = renderHook(() => useDocumentSort({
-        remoteSortValue: '-created_at',
-        onRemoteSortChange,
-      }))
-
-      act(() => {
-        result.current.handleSort(null)
-      })
-
-      expect(onRemoteSortChange).not.toHaveBeenCalled()
+      expect(result.current.sortedDocuments).toEqual([])
     })
   })
 })

web/app/components/datasets/documents/components/document-list/hooks/use-document-sort.ts

@@ -1,42 +1,102 @@
-import { useCallback, useMemo } from 'react'
+import type { SimpleDocumentDetail } from '@/models/datasets'
+import { useCallback, useMemo, useRef, useState } from 'react'
+import { normalizeStatusForQuery } from '@/app/components/datasets/documents/status-filter'
 
-type RemoteSortField = 'hit_count' | 'created_at'
-const REMOTE_SORT_FIELDS = new Set<RemoteSortField>(['hit_count', 'created_at'])
-
-export type SortField = RemoteSortField | null
+export type SortField = 'name' | 'word_count' | 'hit_count' | 'created_at' | null
 export type SortOrder = 'asc' | 'desc'
 
+type LocalDoc = SimpleDocumentDetail & { percent?: number }
+
 type UseDocumentSortOptions = {
+  documents: LocalDoc[]
+  statusFilterValue: string
   remoteSortValue: string
-  onRemoteSortChange: (nextSortValue: string) => void
 }
 
 export const useDocumentSort = ({
+  documents,
+  statusFilterValue,
   remoteSortValue,
-  onRemoteSortChange,
 }: UseDocumentSortOptions) => {
-  const sortOrder: SortOrder = remoteSortValue.startsWith('-') ? 'desc' : 'asc'
-  const sortKey = remoteSortValue.startsWith('-') ? remoteSortValue.slice(1) : remoteSortValue
+  const [sortField, setSortField] = useState<SortField>(null)
+  const [sortOrder, setSortOrder] = useState<SortOrder>('desc')
+  const prevRemoteSortValueRef = useRef(remoteSortValue)
 
-  const sortField = useMemo<SortField>(() => {
-    return REMOTE_SORT_FIELDS.has(sortKey as RemoteSortField) ? sortKey as RemoteSortField : null
-  }, [sortKey])
+  // Reset sort when remote sort changes
+  if (prevRemoteSortValueRef.current !== remoteSortValue) {
+    prevRemoteSortValueRef.current = remoteSortValue
+    setSortField(null)
+    setSortOrder('desc')
+  }
 
   const handleSort = useCallback((field: SortField) => {
-    if (!field)
+    if (field === null)
       return
 
     if (sortField === field) {
-      const nextSortOrder = sortOrder === 'desc' ? 'asc' : 'desc'
-      onRemoteSortChange(nextSortOrder === 'desc' ? `-${field}` : field)
-      return
+      setSortOrder(prev => prev === 'asc' ? 'desc' : 'asc')
     }
-    onRemoteSortChange(`-${field}`)
-  }, [onRemoteSortChange, sortField, sortOrder])
+    else {
+      setSortField(field)
+      setSortOrder('desc')
+    }
+  }, [sortField])
+
+  const sortedDocuments = useMemo(() => {
+    let filteredDocs = documents
+
+    if (statusFilterValue && statusFilterValue !== 'all') {
+      filteredDocs = filteredDocs.filter(doc =>
+        typeof doc.display_status === 'string'
+        && normalizeStatusForQuery(doc.display_status) === statusFilterValue,
+      )
+    }
+
+    if (!sortField)
+      return filteredDocs
+
+    const sortedDocs = [...filteredDocs].sort((a, b) => {
+      let aValue: string | number
+      let bValue: string | number
+
+      switch (sortField) {
+        case 'name':
+          aValue = a.name?.toLowerCase() || ''
+          bValue = b.name?.toLowerCase() || ''
+          break
+        case 'word_count':
+          aValue = a.word_count || 0
+          bValue = b.word_count || 0
+          break
+        case 'hit_count':
+          aValue = a.hit_count || 0
+          bValue = b.hit_count || 0
+          break
+        case 'created_at':
+          aValue = a.created_at
+          bValue = b.created_at
+          break
+        default:
+          return 0
+      }
+
+      if (sortField === 'name') {
+        const result = (aValue as string).localeCompare(bValue as string)
+        return sortOrder === 'asc' ? result : -result
+      }
+      else {
+        const result = (aValue as number) - (bValue as number)
+        return sortOrder === 'asc' ? result : -result
+      }
+    })
+
+    return sortedDocs
+  }, [documents, sortField, sortOrder, statusFilterValue])
 
   return {
     sortField,
     sortOrder,
     handleSort,
+    sortedDocuments,
   }
 }

web/app/components/datasets/documents/components/list.tsx

@@ -14,7 +14,7 @@ import { useDatasetDetailContextWithSelector as useDatasetDetailContext } from '
 import { ChunkingMode, DocumentActionType } from '@/models/datasets'
 import BatchAction from '../detail/completed/common/batch-action'
 import s from '../style.module.css'
-import { DocumentTableRow, SortHeader } from './document-list/components'
+import { DocumentTableRow, renderTdValue, SortHeader } from './document-list/components'
 import { useDocumentActions, useDocumentSelection, useDocumentSort } from './document-list/hooks'
 import RenameModal from './rename-modal'
 
@@ -29,8 +29,8 @@ type DocumentListProps = {
   pagination: PaginationProps
   onUpdate: () => void
   onManageMetadata: () => void
+  statusFilterValue: string
   remoteSortValue: string
-  onSortChange: (value: string) => void
 }
 
 /**
@@ -45,8 +45,8 @@ const DocumentList: FC<DocumentListProps> = ({
   pagination,
   onUpdate,
   onManageMetadata,
+  statusFilterValue,
   remoteSortValue,
-  onSortChange,
 }) => {
   const { t } = useTranslation()
   const datasetConfig = useDatasetDetailContext(s => s.dataset)
@@ -55,9 +55,10 @@ const DocumentList: FC<DocumentListProps> = ({
   const isQAMode = chunkingMode === ChunkingMode.qa
 
   // Sorting
-  const { sortField, sortOrder, handleSort } = useDocumentSort({
+  const { sortField, sortOrder, handleSort, sortedDocuments } = useDocumentSort({
+    documents,
+    statusFilterValue,
     remoteSortValue,
-    onRemoteSortChange: onSortChange,
   })
 
   // Selection
@@ -70,7 +71,7 @@ const DocumentList: FC<DocumentListProps> = ({
     downloadableSelectedIds,
     clearSelection,
   } = useDocumentSelection({
-    documents,
+    documents: sortedDocuments,
     selectedIds,
     onSelectedIdChange,
   })
@@ -134,10 +135,24 @@ const DocumentList: FC<DocumentListProps> = ({
                 </div>
               </td>
               <td>
-                {t('list.table.header.fileName', { ns: 'datasetDocuments' })}
+                <SortHeader
+                  field="name"
+                  label={t('list.table.header.fileName', { ns: 'datasetDocuments' })}
+                  currentSortField={sortField}
+                  sortOrder={sortOrder}
+                  onSort={handleSort}
+                />
               </td>
               <td className="w-[130px]">{t('list.table.header.chunkingMode', { ns: 'datasetDocuments' })}</td>
-              <td className="w-24">{t('list.table.header.words', { ns: 'datasetDocuments' })}</td>
+              <td className="w-24">
+                <SortHeader
+                  field="word_count"
+                  label={t('list.table.header.words', { ns: 'datasetDocuments' })}
+                  currentSortField={sortField}
+                  sortOrder={sortOrder}
+                  onSort={handleSort}
+                />
+              </td>
               <td className="w-44">
                 <SortHeader
                   field="hit_count"
@@ -161,7 +176,7 @@ const DocumentList: FC<DocumentListProps> = ({
             </tr>
           </thead>
           <tbody className="text-text-secondary">
-            {documents.map((doc, index) => (
+            {sortedDocuments.map((doc, index) => (
               <DocumentTableRow
                 key={doc.id}
                 doc={doc}
@@ -233,3 +248,5 @@ const DocumentList: FC<DocumentListProps> = ({
 }
 
 export default DocumentList
+
+export { renderTdValue }

web/app/components/datasets/documents/detail/__tests__/index.spec.tsx

@@ -9,7 +9,6 @@ const mocks = vi.hoisted(() => {
     documentError: null as Error | null,
     documentMetadata: null as Record<string, unknown> | null,
     media: 'desktop' as string,
-    searchParams: '' as string,
   }
   return {
     state,
@@ -27,7 +26,6 @@ const mocks = vi.hoisted(() => {
 // --- External mocks ---
 vi.mock('next/navigation', () => ({
   useRouter: () => ({ push: mocks.push }),
-  useSearchParams: () => new URLSearchParams(mocks.state.searchParams),
 }))
 
 vi.mock('@/hooks/use-breakpoints', () => ({
@@ -195,7 +193,6 @@ describe('DocumentDetail', () => {
     mocks.state.documentError = null
     mocks.state.documentMetadata = null
     mocks.state.media = 'desktop'
-    mocks.state.searchParams = ''
   })
 
   afterEach(() => {
@@ -289,23 +286,15 @@ describe('DocumentDetail', () => {
     })
 
     it('should toggle metadata panel when button clicked', () => {
-      render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
+      const { container } = render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
       expect(screen.getByTestId('metadata')).toBeInTheDocument()
 
-      fireEvent.click(screen.getByTestId('document-detail-metadata-toggle'))
+      const svgs = container.querySelectorAll('svg')
+      const toggleBtn = svgs[svgs.length - 1].closest('button')!
+      fireEvent.click(toggleBtn)
       expect(screen.queryByTestId('metadata')).not.toBeInTheDocument()
     })
 
-    it('should expose aria semantics for metadata toggle button', () => {
-      render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
-      const toggle = screen.getByTestId('document-detail-metadata-toggle')
-      expect(toggle).toHaveAttribute('aria-label')
-      expect(toggle).toHaveAttribute('aria-pressed', 'true')
-
-      fireEvent.click(toggle)
-      expect(toggle).toHaveAttribute('aria-pressed', 'false')
-    })
-
     it('should pass correct props to Metadata', () => {
       render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
       const metadata = screen.getByTestId('metadata')
@@ -316,21 +305,20 @@ describe('DocumentDetail', () => {
 
   describe('Navigation', () => {
     it('should navigate back when back button clicked', () => {
-      render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
-      fireEvent.click(screen.getByTestId('document-detail-back-button'))
+      const { container } = render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
+      const backBtn = container.querySelector('svg')!.parentElement!
+      fireEvent.click(backBtn)
       expect(mocks.push).toHaveBeenCalledWith('/datasets/ds-1/documents')
     })
 
-    it('should expose aria label for back button', () => {
-      render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
-      expect(screen.getByTestId('document-detail-back-button')).toHaveAttribute('aria-label')
-    })
-
     it('should preserve query params when navigating back', () => {
-      mocks.state.searchParams = 'page=2&status=active'
-      render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
-      fireEvent.click(screen.getByTestId('document-detail-back-button'))
+      const origLocation = window.location
+      window.history.pushState({}, '', '?page=2&status=active')
+      const { container } = render(<DocumentDetail datasetId="ds-1" documentId="doc-1" />)
+      const backBtn = container.querySelector('svg')!.parentElement!
+      fireEvent.click(backBtn)
       expect(mocks.push).toHaveBeenCalledWith('/datasets/ds-1/documents?page=2&status=active')
+      window.history.pushState({}, '', origLocation.href)
     })
   })
 

web/app/components/datasets/documents/detail/index.tsx

@@ -1,7 +1,8 @@
 'use client'
 import type { FC } from 'react'
 import type { DataSourceInfo, FileItem, FullDocumentDetail, LegacyDataSourceInfo } from '@/models/datasets'
-import { useRouter, useSearchParams } from 'next/navigation'
+import { RiArrowLeftLine, RiLayoutLeft2Line, RiLayoutRight2Line } from '@remixicon/react'
+import { useRouter } from 'next/navigation'
 import * as React from 'react'
 import { useMemo, useState } from 'react'
 import { useTranslation } from 'react-i18next'
@@ -34,7 +35,6 @@ type DocumentDetailProps = {
 
 const DocumentDetail: FC<DocumentDetailProps> = ({ datasetId, documentId }) => {
   const router = useRouter()
-  const searchParams = useSearchParams()
   const { t } = useTranslation()
 
   const media = useBreakpoints()
@@ -98,8 +98,11 @@ const DocumentDetail: FC<DocumentDetailProps> = ({ datasetId, documentId }) => {
   })
 
   const backToPrev = () => {
+    // Preserve pagination and filter states when navigating back
+    const searchParams = new URLSearchParams(window.location.search)
     const queryString = searchParams.toString()
-    const backPath = `/datasets/${datasetId}/documents${queryString ? `?${queryString}` : ''}`
+    const separator = queryString ? '?' : ''
+    const backPath = `/datasets/${datasetId}/documents${separator}${queryString}`
     router.push(backPath)
   }
 
@@ -149,11 +152,6 @@ const DocumentDetail: FC<DocumentDetailProps> = ({ datasetId, documentId }) => {
     return chunkMode === ChunkingMode.parentChild && parentMode === 'full-doc'
   }, [documentDetail?.doc_form, parentMode])
 
-  const backButtonLabel = t('operation.back', { ns: 'common' })
-  const metadataToggleLabel = `${showMetadata
-    ? t('operation.close', { ns: 'common' })
-    : t('operation.view', { ns: 'common' })} ${t('metadata.title', { ns: 'datasetDocuments' })}`
-
   return (
     <DocumentContext.Provider value={{
       datasetId,
@@ -164,19 +162,9 @@ const DocumentDetail: FC<DocumentDetailProps> = ({ datasetId, documentId }) => {
     >
       <div className="flex h-full flex-col bg-background-default">
         <div className="flex min-h-16 flex-wrap items-center justify-between border-b border-b-divider-subtle py-2.5 pl-3 pr-4">
-          <button
-            type="button"
-            data-testid="document-detail-back-button"
-            aria-label={backButtonLabel}
-            title={backButtonLabel}
-            onClick={backToPrev}
-            className="flex h-8 w-8 shrink-0 cursor-pointer items-center justify-center rounded-full hover:bg-components-button-tertiary-bg"
-          >
-            <span
-              aria-hidden="true"
-              className="i-ri-arrow-left-line h-4 w-4 text-components-button-ghost-text hover:text-text-tertiary"
-            />
-          </button>
+          <div onClick={backToPrev} className="flex h-8 w-8 shrink-0 cursor-pointer items-center justify-center rounded-full hover:bg-components-button-tertiary-bg">
+            <RiArrowLeftLine className="h-4 w-4 text-components-button-ghost-text hover:text-text-tertiary" />
+          </div>
           <DocumentTitle
             datasetId={datasetId}
             extension={documentUploadFile?.extension}
@@ -228,17 +216,13 @@ const DocumentDetail: FC<DocumentDetailProps> = ({ datasetId, documentId }) => {
             />
             <button
               type="button"
-              data-testid="document-detail-metadata-toggle"
-              aria-label={metadataToggleLabel}
-              aria-pressed={showMetadata}
-              title={metadataToggleLabel}
               className={style.layoutRightIcon}
               onClick={() => setShowMetadata(!showMetadata)}
             >
               {
                 showMetadata
-                  ? <span aria-hidden="true" className="i-ri-layout-left-2-line h-4 w-4 text-components-button-secondary-text" />
-                  : <span aria-hidden="true" className="i-ri-layout-right-2-line h-4 w-4 text-components-button-secondary-text" />
+                  ? <RiLayoutLeft2Line className="h-4 w-4 text-components-button-secondary-text" />
+                  : <RiLayoutRight2Line className="h-4 w-4 text-components-button-secondary-text" />
               }
             </button>
           </div>

web/app/components/datasets/documents/hooks/__tests__/use-document-list-query-state.spec.ts

@@ -0,0 +1,439 @@
+import type { DocumentListQuery } from '../use-document-list-query-state'
+import { act, renderHook } from '@testing-library/react'
+
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import useDocumentListQueryState from '../use-document-list-query-state'
+
+const mockPush = vi.fn()
+const mockSearchParams = new URLSearchParams()
+
+vi.mock('@/models/datasets', () => ({
+  DisplayStatusList: [
+    'queuing',
+    'indexing',
+    'paused',
+    'error',
+    'available',
+    'enabled',
+    'disabled',
+    'archived',
+  ],
+}))
+
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({ push: mockPush }),
+  usePathname: () => '/datasets/test-id/documents',
+  useSearchParams: () => mockSearchParams,
+}))
+
+describe('useDocumentListQueryState', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    // Reset mock search params to empty
+    for (const key of [...mockSearchParams.keys()])
+      mockSearchParams.delete(key)
+  })
+
+  // Tests for parseParams (exposed via the query property)
+  describe('parseParams (via query)', () => {
+    it('should return default query when no search params present', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query).toEqual({
+        page: 1,
+        limit: 10,
+        keyword: '',
+        status: 'all',
+        sort: '-created_at',
+      })
+    })
+
+    it('should parse page from search params', () => {
+      mockSearchParams.set('page', '3')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.page).toBe(3)
+    })
+
+    it('should default page to 1 when page is zero', () => {
+      mockSearchParams.set('page', '0')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.page).toBe(1)
+    })
+
+    it('should default page to 1 when page is negative', () => {
+      mockSearchParams.set('page', '-5')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.page).toBe(1)
+    })
+
+    it('should default page to 1 when page is NaN', () => {
+      mockSearchParams.set('page', 'abc')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.page).toBe(1)
+    })
+
+    it('should parse limit from search params', () => {
+      mockSearchParams.set('limit', '50')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.limit).toBe(50)
+    })
+
+    it('should default limit to 10 when limit is zero', () => {
+      mockSearchParams.set('limit', '0')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.limit).toBe(10)
+    })
+
+    it('should default limit to 10 when limit exceeds 100', () => {
+      mockSearchParams.set('limit', '101')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.limit).toBe(10)
+    })
+
+    it('should default limit to 10 when limit is negative', () => {
+      mockSearchParams.set('limit', '-1')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.limit).toBe(10)
+    })
+
+    it('should accept limit at boundary 100', () => {
+      mockSearchParams.set('limit', '100')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.limit).toBe(100)
+    })
+
+    it('should accept limit at boundary 1', () => {
+      mockSearchParams.set('limit', '1')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.limit).toBe(1)
+    })
+
+    it('should parse and decode keyword from search params', () => {
+      mockSearchParams.set('keyword', encodeURIComponent('hello world'))
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.keyword).toBe('hello world')
+    })
+
+    it('should return empty keyword when not present', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.keyword).toBe('')
+    })
+
+    it('should sanitize status from search params', () => {
+      mockSearchParams.set('status', 'available')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.status).toBe('available')
+    })
+
+    it('should fallback status to all for unknown status', () => {
+      mockSearchParams.set('status', 'badvalue')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.status).toBe('all')
+    })
+
+    it('should resolve active status alias to available', () => {
+      mockSearchParams.set('status', 'active')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.status).toBe('available')
+    })
+
+    it('should parse valid sort value from search params', () => {
+      mockSearchParams.set('sort', 'hit_count')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.sort).toBe('hit_count')
+    })
+
+    it('should default sort to -created_at for invalid sort value', () => {
+      mockSearchParams.set('sort', 'invalid_sort')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.sort).toBe('-created_at')
+    })
+
+    it('should default sort to -created_at when not present', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.sort).toBe('-created_at')
+    })
+
+    it.each([
+      '-created_at',
+      'created_at',
+      '-hit_count',
+      'hit_count',
+    ] as const)('should accept valid sort value %s', (sortValue) => {
+      mockSearchParams.set('sort', sortValue)
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current.query.sort).toBe(sortValue)
+    })
+  })
+
+  // Tests for updateQuery
+  describe('updateQuery', () => {
+    it('should call router.push with updated params when page is changed', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ page: 3 })
+      })
+
+      expect(mockPush).toHaveBeenCalledTimes(1)
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      expect(pushedUrl).toContain('page=3')
+    })
+
+    it('should call router.push with scroll false', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ page: 2 })
+      })
+
+      expect(mockPush).toHaveBeenCalledWith(
+        expect.any(String),
+        { scroll: false },
+      )
+    })
+
+    it('should set status in URL when status is not all', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ status: 'error' })
+      })
+
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      expect(pushedUrl).toContain('status=error')
+    })
+
+    it('should not set status in URL when status is all', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ status: 'all' })
+      })
+
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      expect(pushedUrl).not.toContain('status=')
+    })
+
+    it('should set sort in URL when sort is not the default -created_at', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ sort: 'hit_count' })
+      })
+
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      expect(pushedUrl).toContain('sort=hit_count')
+    })
+
+    it('should not set sort in URL when sort is default -created_at', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ sort: '-created_at' })
+      })
+
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      expect(pushedUrl).not.toContain('sort=')
+    })
+
+    it('should encode keyword in URL when keyword is provided', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ keyword: 'test query' })
+      })
+
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      // Source code applies encodeURIComponent before setting in URLSearchParams
+      expect(pushedUrl).toContain('keyword=')
+      const params = new URLSearchParams(pushedUrl.split('?')[1])
+      // params.get decodes one layer, but the value was pre-encoded with encodeURIComponent
+      expect(decodeURIComponent(params.get('keyword')!)).toBe('test query')
+    })
+
+    it('should remove keyword from URL when keyword is empty', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ keyword: '' })
+      })
+
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      expect(pushedUrl).not.toContain('keyword=')
+    })
+
+    it('should sanitize invalid status to all and not include in URL', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ status: 'invalidstatus' })
+      })
+
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      expect(pushedUrl).not.toContain('status=')
+    })
+
+    it('should sanitize invalid sort to -created_at and not include in URL', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ sort: 'invalidsort' as DocumentListQuery['sort'] })
+      })
+
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      expect(pushedUrl).not.toContain('sort=')
+    })
+
+    it('should omit page and limit when they are default and no keyword', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ page: 1, limit: 10 })
+      })
+
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      expect(pushedUrl).not.toContain('page=')
+      expect(pushedUrl).not.toContain('limit=')
+    })
+
+    it('should include page and limit when page is greater than 1', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ page: 2 })
+      })
+
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      expect(pushedUrl).toContain('page=2')
+      expect(pushedUrl).toContain('limit=10')
+    })
+
+    it('should include page and limit when limit is non-default', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ limit: 25 })
+      })
+
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      expect(pushedUrl).toContain('page=1')
+      expect(pushedUrl).toContain('limit=25')
+    })
+
+    it('should include page and limit when keyword is provided', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ keyword: 'search' })
+      })
+
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      expect(pushedUrl).toContain('page=1')
+      expect(pushedUrl).toContain('limit=10')
+    })
+
+    it('should use pathname prefix in pushed URL', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({ page: 2 })
+      })
+
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      expect(pushedUrl).toMatch(/^\/datasets\/test-id\/documents/)
+    })
+
+    it('should push path without query string when all values are defaults', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.updateQuery({})
+      })
+
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      expect(pushedUrl).toBe('/datasets/test-id/documents')
+    })
+  })
+
+  // Tests for resetQuery
+  describe('resetQuery', () => {
+    it('should push URL with default query params when called', () => {
+      mockSearchParams.set('page', '5')
+      mockSearchParams.set('status', 'error')
+
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.resetQuery()
+      })
+
+      expect(mockPush).toHaveBeenCalledTimes(1)
+      const pushedUrl = mockPush.mock.calls[0][0] as string
+      // Default query has all defaults, so no params should be in the URL
+      expect(pushedUrl).toBe('/datasets/test-id/documents')
+    })
+
+    it('should call router.push with scroll false when resetting', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      act(() => {
+        result.current.resetQuery()
+      })
+
+      expect(mockPush).toHaveBeenCalledWith(
+        expect.any(String),
+        { scroll: false },
+      )
+    })
+  })
+
+  // Tests for return value stability
+  describe('return value', () => {
+    it('should return query, updateQuery, and resetQuery', () => {
+      const { result } = renderHook(() => useDocumentListQueryState())
+
+      expect(result.current).toHaveProperty('query')
+      expect(result.current).toHaveProperty('updateQuery')
+      expect(result.current).toHaveProperty('resetQuery')
+      expect(typeof result.current.updateQuery).toBe('function')
+      expect(typeof result.current.resetQuery).toBe('function')
+    })
+  })
+})

web/app/components/datasets/documents/hooks/__tests__/use-document-list-query-state.spec.tsx

@@ -1,426 +0,0 @@
-import type { DocumentListQuery } from '../use-document-list-query-state'
-import { act, waitFor } from '@testing-library/react'
-import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { renderHookWithNuqs } from '@/test/nuqs-testing'
-import { useDocumentListQueryState } from '../use-document-list-query-state'
-
-vi.mock('@/models/datasets', () => ({
-  DisplayStatusList: [
-    'queuing',
-    'indexing',
-    'paused',
-    'error',
-    'available',
-    'enabled',
-    'disabled',
-    'archived',
-  ],
-}))
-
-const renderWithAdapter = (searchParams = '') => {
-  return renderHookWithNuqs(() => useDocumentListQueryState(), { searchParams })
-}
-
-describe('useDocumentListQueryState', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  describe('query parsing', () => {
-    it('should return default query when no search params present', () => {
-      const { result } = renderWithAdapter()
-
-      expect(result.current.query).toEqual({
-        page: 1,
-        limit: 10,
-        keyword: '',
-        status: 'all',
-        sort: '-created_at',
-      })
-    })
-
-    it('should parse page from search params', () => {
-      const { result } = renderWithAdapter('?page=3')
-      expect(result.current.query.page).toBe(3)
-    })
-
-    it('should default page to 1 when page is zero', () => {
-      const { result } = renderWithAdapter('?page=0')
-      expect(result.current.query.page).toBe(1)
-    })
-
-    it('should default page to 1 when page is negative', () => {
-      const { result } = renderWithAdapter('?page=-5')
-      expect(result.current.query.page).toBe(1)
-    })
-
-    it('should default page to 1 when page is NaN', () => {
-      const { result } = renderWithAdapter('?page=abc')
-      expect(result.current.query.page).toBe(1)
-    })
-
-    it('should parse limit from search params', () => {
-      const { result } = renderWithAdapter('?limit=50')
-      expect(result.current.query.limit).toBe(50)
-    })
-
-    it('should default limit to 10 when limit is zero', () => {
-      const { result } = renderWithAdapter('?limit=0')
-      expect(result.current.query.limit).toBe(10)
-    })
-
-    it('should default limit to 10 when limit exceeds 100', () => {
-      const { result } = renderWithAdapter('?limit=101')
-      expect(result.current.query.limit).toBe(10)
-    })
-
-    it('should default limit to 10 when limit is negative', () => {
-      const { result } = renderWithAdapter('?limit=-1')
-      expect(result.current.query.limit).toBe(10)
-    })
-
-    it('should accept limit at boundary 100', () => {
-      const { result } = renderWithAdapter('?limit=100')
-      expect(result.current.query.limit).toBe(100)
-    })
-
-    it('should accept limit at boundary 1', () => {
-      const { result } = renderWithAdapter('?limit=1')
-      expect(result.current.query.limit).toBe(1)
-    })
-
-    it('should parse keyword from search params', () => {
-      const { result } = renderWithAdapter('?keyword=hello+world')
-      expect(result.current.query.keyword).toBe('hello world')
-    })
-
-    it('should preserve legacy double-encoded keyword text after URL decoding', () => {
-      const { result } = renderWithAdapter('?keyword=test%2520query')
-      expect(result.current.query.keyword).toBe('test%20query')
-    })
-
-    it('should return empty keyword when not present', () => {
-      const { result } = renderWithAdapter()
-      expect(result.current.query.keyword).toBe('')
-    })
-
-    it('should sanitize status from search params', () => {
-      const { result } = renderWithAdapter('?status=available')
-      expect(result.current.query.status).toBe('available')
-    })
-
-    it('should fallback status to all for unknown status', () => {
-      const { result } = renderWithAdapter('?status=badvalue')
-      expect(result.current.query.status).toBe('all')
-    })
-
-    it('should resolve active status alias to available', () => {
-      const { result } = renderWithAdapter('?status=active')
-      expect(result.current.query.status).toBe('available')
-    })
-
-    it('should parse valid sort value from search params', () => {
-      const { result } = renderWithAdapter('?sort=hit_count')
-      expect(result.current.query.sort).toBe('hit_count')
-    })
-
-    it('should default sort to -created_at for invalid sort value', () => {
-      const { result } = renderWithAdapter('?sort=invalid_sort')
-      expect(result.current.query.sort).toBe('-created_at')
-    })
-
-    it('should default sort to -created_at when not present', () => {
-      const { result } = renderWithAdapter()
-      expect(result.current.query.sort).toBe('-created_at')
-    })
-
-    it.each([
-      '-created_at',
-      'created_at',
-      '-hit_count',
-      'hit_count',
-    ] as const)('should accept valid sort value %s', (sortValue) => {
-      const { result } = renderWithAdapter(`?sort=${sortValue}`)
-      expect(result.current.query.sort).toBe(sortValue)
-    })
-  })
-
-  describe('updateQuery', () => {
-    it('should update page in state when page is changed', () => {
-      const { result } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ page: 3 })
-      })
-
-      expect(result.current.query.page).toBe(3)
-    })
-
-    it('should sync page to URL with push history', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ page: 2 })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.get('page')).toBe('2')
-      expect(update.options.history).toBe('push')
-    })
-
-    it('should set status in URL when status is not all', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ status: 'error' })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.get('status')).toBe('error')
-    })
-
-    it('should not set status in URL when status is all', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ status: 'all' })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.has('status')).toBe(false)
-    })
-
-    it('should set sort in URL when sort is not the default -created_at', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ sort: 'hit_count' })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.get('sort')).toBe('hit_count')
-    })
-
-    it('should not set sort in URL when sort is default -created_at', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ sort: '-created_at' })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.has('sort')).toBe(false)
-    })
-
-    it('should set keyword in URL when keyword is provided', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ keyword: 'test query' })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.get('keyword')).toBe('test query')
-      expect(update.options.history).toBe('replace')
-    })
-
-    it('should use replace history when keyword update also resets page', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter('?page=3')
-
-      act(() => {
-        result.current.updateQuery({ keyword: 'hello', page: 1 })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.get('keyword')).toBe('hello')
-      expect(update.searchParams.has('page')).toBe(false)
-      expect(update.options.history).toBe('replace')
-    })
-
-    it('should remove keyword from URL when keyword is empty', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter('?keyword=existing')
-
-      act(() => {
-        result.current.updateQuery({ keyword: '' })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.has('keyword')).toBe(false)
-      expect(update.options.history).toBe('replace')
-    })
-
-    it('should remove keyword from URL when keyword contains only whitespace', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter('?keyword=existing')
-
-      act(() => {
-        result.current.updateQuery({ keyword: '   ' })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.has('keyword')).toBe(false)
-      expect(result.current.query.keyword).toBe('')
-    })
-
-    it('should preserve literal percent-encoded-like keyword values', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ keyword: '%2F' })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.get('keyword')).toBe('%2F')
-      expect(result.current.query.keyword).toBe('%2F')
-    })
-
-    it('should keep keyword text unchanged when updating query from legacy URL', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter('?keyword=test%2520query')
-
-      act(() => {
-        result.current.updateQuery({ page: 2 })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      expect(result.current.query.keyword).toBe('test%20query')
-    })
-
-    it('should sanitize invalid status to all and not include in URL', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ status: 'invalidstatus' })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.has('status')).toBe(false)
-    })
-
-    it('should sanitize invalid sort to -created_at and not include in URL', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ sort: 'invalidsort' as DocumentListQuery['sort'] })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.has('sort')).toBe(false)
-    })
-
-    it('should not include page in URL when page is default', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ page: 1 })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.has('page')).toBe(false)
-    })
-
-    it('should include page in URL when page is greater than 1', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ page: 2 })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.get('page')).toBe('2')
-    })
-
-    it('should include limit in URL when limit is non-default', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ limit: 25 })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.get('limit')).toBe('25')
-    })
-
-    it('should sanitize invalid page to default and omit page from URL', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ page: -1 })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.has('page')).toBe(false)
-      expect(result.current.query.page).toBe(1)
-    })
-
-    it('should sanitize invalid limit to default and omit limit from URL', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter()
-
-      act(() => {
-        result.current.updateQuery({ limit: 999 })
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.has('limit')).toBe(false)
-      expect(result.current.query.limit).toBe(10)
-    })
-  })
-
-  describe('resetQuery', () => {
-    it('should reset all values to defaults', () => {
-      const { result } = renderWithAdapter('?page=5&status=error&sort=hit_count')
-
-      act(() => {
-        result.current.resetQuery()
-      })
-
-      expect(result.current.query).toEqual({
-        page: 1,
-        limit: 10,
-        keyword: '',
-        status: 'all',
-        sort: '-created_at',
-      })
-    })
-
-    it('should clear all params from URL when called', async () => {
-      const { result, onUrlUpdate } = renderWithAdapter('?page=5&status=error')
-
-      act(() => {
-        result.current.resetQuery()
-      })
-
-      await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-      const update = onUrlUpdate.mock.calls[onUrlUpdate.mock.calls.length - 1][0]
-      expect(update.searchParams.has('page')).toBe(false)
-      expect(update.searchParams.has('status')).toBe(false)
-    })
-  })
-
-  describe('return value', () => {
-    it('should return query, updateQuery, and resetQuery', () => {
-      const { result } = renderWithAdapter()
-
-      expect(result.current).toHaveProperty('query')
-      expect(result.current).toHaveProperty('updateQuery')
-      expect(result.current).toHaveProperty('resetQuery')
-      expect(typeof result.current.updateQuery).toBe('function')
-      expect(typeof result.current.resetQuery).toBe('function')
-    })
-  })
-})

web/app/components/datasets/documents/hooks/__tests__/use-documents-page-state.spec.ts

@@ -1,10 +1,12 @@
 import type { DocumentListQuery } from '../use-document-list-query-state'
+import type { DocumentListResponse } from '@/models/datasets'
 
 import { act, renderHook } from '@testing-library/react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { useDocumentsPageState } from '../use-documents-page-state'
 
 const mockUpdateQuery = vi.fn()
+const mockResetQuery = vi.fn()
 let mockQuery: DocumentListQuery = { page: 1, limit: 10, keyword: '', status: 'all', sort: '-created_at' }
 
 vi.mock('@/models/datasets', () => ({
@@ -20,70 +22,151 @@ vi.mock('@/models/datasets', () => ({
   ],
 }))
 
-vi.mock('ahooks', () => ({
-  useDebounce: (value: unknown, _options?: { wait?: number }) => value,
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({ push: vi.fn() }),
+  usePathname: () => '/datasets/test-id/documents',
+  useSearchParams: () => new URLSearchParams(),
 }))
 
-vi.mock('../use-document-list-query-state', async () => {
-  const React = await import('react')
+// Mock ahooks debounce utilities: required because tests capture the debounce
+// callback reference to invoke it synchronously, bypassing real timer delays.
+let capturedDebounceFnCallback: (() => void) | null = null
+
+vi.mock('ahooks', () => ({
+  useDebounce: (value: unknown, _options?: { wait?: number }) => value,
+  useDebounceFn: (fn: () => void, _options?: { wait?: number }) => {
+    capturedDebounceFnCallback = fn
+    return { run: fn, cancel: vi.fn(), flush: vi.fn() }
+  },
+}))
+
+// Mock the dependent hook
+vi.mock('../use-document-list-query-state', () => ({
+  default: () => ({
+    query: mockQuery,
+    updateQuery: mockUpdateQuery,
+    resetQuery: mockResetQuery,
+  }),
+}))
+
+// Factory for creating DocumentListResponse test data
+function createDocumentListResponse(overrides: Partial<DocumentListResponse> = {}): DocumentListResponse {
   return {
-    useDocumentListQueryState: () => {
-      const [query, setQuery] = React.useState<DocumentListQuery>(mockQuery)
-      return {
-        query,
-        updateQuery: (updates: Partial<DocumentListQuery>) => {
-          mockUpdateQuery(updates)
-          setQuery(prev => ({ ...prev, ...updates }))
-        },
-      }
-    },
+    data: [],
+    has_more: false,
+    total: 0,
+    page: 1,
+    limit: 10,
+    ...overrides,
   }
-})
+}
+
+// Factory for creating a minimal document item
+function createDocumentItem(overrides: Record<string, unknown> = {}) {
+  return {
+    id: `doc-${Math.random().toString(36).slice(2, 8)}`,
+    name: 'test-doc.txt',
+    indexing_status: 'completed' as string,
+    display_status: 'available' as string,
+    enabled: true,
+    archived: false,
+    word_count: 100,
+    created_at: Date.now(),
+    updated_at: Date.now(),
+    created_from: 'web' as const,
+    created_by: 'user-1',
+    dataset_process_rule_id: 'rule-1',
+    doc_form: 'text_model' as const,
+    doc_language: 'en',
+    position: 1,
+    data_source_type: 'upload_file',
+    ...overrides,
+  }
+}
 
 describe('useDocumentsPageState', () => {
   beforeEach(() => {
     vi.clearAllMocks()
+    capturedDebounceFnCallback = null
     mockQuery = { page: 1, limit: 10, keyword: '', status: 'all', sort: '-created_at' }
   })
 
   // Initial state verification
   describe('initial state', () => {
-    it('should return correct initial query-derived state', () => {
+    it('should return correct initial search state', () => {
       const { result } = renderHook(() => useDocumentsPageState())
 
       expect(result.current.inputValue).toBe('')
+      expect(result.current.searchValue).toBe('')
       expect(result.current.debouncedSearchValue).toBe('')
+    })
+
+    it('should return correct initial filter and sort state', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
       expect(result.current.statusFilterValue).toBe('all')
       expect(result.current.sortValue).toBe('-created_at')
       expect(result.current.normalizedStatusFilterValue).toBe('all')
+    })
+
+    it('should return correct initial pagination state', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      // page is query.page - 1 = 0
       expect(result.current.currPage).toBe(0)
       expect(result.current.limit).toBe(10)
+    })
+
+    it('should return correct initial selection state', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
       expect(result.current.selectedIds).toEqual([])
     })
 
-    it('should initialize from non-default query values', () => {
-      mockQuery = {
-        page: 3,
-        limit: 25,
-        keyword: 'initial',
-        status: 'enabled',
-        sort: 'hit_count',
-      }
+    it('should return correct initial polling state', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      expect(result.current.timerCanRun).toBe(true)
+    })
+
+    it('should initialize from query when query has keyword', () => {
+      mockQuery = { ...mockQuery, keyword: 'initial search' }
 
       const { result } = renderHook(() => useDocumentsPageState())
 
-      expect(result.current.inputValue).toBe('initial')
-      expect(result.current.currPage).toBe(2)
+      expect(result.current.inputValue).toBe('initial search')
+      expect(result.current.searchValue).toBe('initial search')
+    })
+
+    it('should initialize pagination from query with non-default page', () => {
+      mockQuery = { ...mockQuery, page: 3, limit: 25 }
+
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      expect(result.current.currPage).toBe(2) // page - 1
       expect(result.current.limit).toBe(25)
-      expect(result.current.statusFilterValue).toBe('enabled')
-      expect(result.current.normalizedStatusFilterValue).toBe('available')
+    })
+
+    it('should initialize status filter from query', () => {
+      mockQuery = { ...mockQuery, status: 'error' }
+
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      expect(result.current.statusFilterValue).toBe('error')
+    })
+
+    it('should initialize sort from query', () => {
+      mockQuery = { ...mockQuery, sort: 'hit_count' }
+
+      const { result } = renderHook(() => useDocumentsPageState())
+
       expect(result.current.sortValue).toBe('hit_count')
     })
   })
 
   // Handler behaviors
   describe('handleInputChange', () => {
-    it('should update keyword and reset page', () => {
+    it('should update input value when called', () => {
       const { result } = renderHook(() => useDocumentsPageState())
 
       act(() => {
@@ -91,59 +174,30 @@ describe('useDocumentsPageState', () => {
       })
 
       expect(result.current.inputValue).toBe('new value')
-      expect(mockUpdateQuery).toHaveBeenCalledWith({ keyword: 'new value', page: 1 })
     })
 
-    it('should clear selected ids when keyword changes', () => {
+    it('should trigger debounced search callback when called', () => {
       const { result } = renderHook(() => useDocumentsPageState())
 
+      // First call sets inputValue and triggers the debounced fn
       act(() => {
-        result.current.setSelectedIds(['doc-1'])
-      })
-      expect(result.current.selectedIds).toEqual(['doc-1'])
-
-      act(() => {
-        result.current.handleInputChange('keyword')
+        result.current.handleInputChange('search term')
       })
 
-      expect(result.current.selectedIds).toEqual([])
-    })
-
-    it('should keep selected ids when keyword is unchanged', () => {
-      mockQuery = { ...mockQuery, keyword: 'same' }
-      const { result } = renderHook(() => useDocumentsPageState())
-
+      // The debounced fn captures inputValue from its render closure.
+      // After re-render with new inputValue, calling the captured callback again
+      // should reflect the updated state.
       act(() => {
-        result.current.setSelectedIds(['doc-1'])
+        if (capturedDebounceFnCallback)
+          capturedDebounceFnCallback()
       })
 
-      act(() => {
-        result.current.handleInputChange('same')
-      })
-
-      expect(result.current.selectedIds).toEqual(['doc-1'])
-      expect(mockUpdateQuery).toHaveBeenCalledWith({ keyword: 'same', page: 1 })
+      expect(result.current.searchValue).toBe('search term')
     })
   })
 
   describe('handleStatusFilterChange', () => {
-    it('should sanitize status, reset page, and clear selection', () => {
-      const { result } = renderHook(() => useDocumentsPageState())
-
-      act(() => {
-        result.current.setSelectedIds(['doc-1'])
-      })
-
-      act(() => {
-        result.current.handleStatusFilterChange('invalid')
-      })
-
-      expect(result.current.statusFilterValue).toBe('all')
-      expect(result.current.selectedIds).toEqual([])
-      expect(mockUpdateQuery).toHaveBeenCalledWith({ status: 'all', page: 1 })
-    })
-
-    it('should update to valid status value', () => {
+    it('should update status filter value when called with valid status', () => {
       const { result } = renderHook(() => useDocumentsPageState())
 
       act(() => {
@@ -151,23 +205,61 @@ describe('useDocumentsPageState', () => {
       })
 
       expect(result.current.statusFilterValue).toBe('error')
+    })
+
+    it('should reset page to 0 when status filter changes', () => {
+      mockQuery = { ...mockQuery, page: 3 }
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.handleStatusFilterChange('error')
+      })
+
+      expect(result.current.currPage).toBe(0)
+    })
+
+    it('should call updateQuery with sanitized status and page 1', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.handleStatusFilterChange('error')
+      })
+
       expect(mockUpdateQuery).toHaveBeenCalledWith({ status: 'error', page: 1 })
     })
+
+    it('should sanitize invalid status to all', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.handleStatusFilterChange('invalid')
+      })
+
+      expect(result.current.statusFilterValue).toBe('all')
+      expect(mockUpdateQuery).toHaveBeenCalledWith({ status: 'all', page: 1 })
+    })
   })
 
   describe('handleStatusFilterClear', () => {
-    it('should reset status to all when status is not all', () => {
-      mockQuery = { ...mockQuery, status: 'error' }
+    it('should set status to all and reset page when status is not all', () => {
       const { result } = renderHook(() => useDocumentsPageState())
 
+      // First set a non-all status
+      act(() => {
+        result.current.handleStatusFilterChange('error')
+      })
+      vi.clearAllMocks()
+
+      // Then clear
       act(() => {
         result.current.handleStatusFilterClear()
       })
 
+      expect(result.current.statusFilterValue).toBe('all')
       expect(mockUpdateQuery).toHaveBeenCalledWith({ status: 'all', page: 1 })
     })
 
-    it('should do nothing when status is already all', () => {
+    it('should not call updateQuery when status is already all', () => {
       const { result } = renderHook(() => useDocumentsPageState())
 
       act(() => {
@@ -179,7 +271,7 @@ describe('useDocumentsPageState', () => {
   })
 
   describe('handleSortChange', () => {
-    it('should update sort and reset page when sort changes', () => {
+    it('should update sort value and call updateQuery when value changes', () => {
       const { result } = renderHook(() => useDocumentsPageState())
 
       act(() => {
@@ -190,7 +282,18 @@ describe('useDocumentsPageState', () => {
       expect(mockUpdateQuery).toHaveBeenCalledWith({ sort: 'hit_count', page: 1 })
     })
 
-    it('should ignore sort update when value is unchanged', () => {
+    it('should reset page to 0 when sort changes', () => {
+      mockQuery = { ...mockQuery, page: 5 }
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.handleSortChange('hit_count')
+      })
+
+      expect(result.current.currPage).toBe(0)
+    })
+
+    it('should not call updateQuery when sort value is same as current', () => {
       const { result } = renderHook(() => useDocumentsPageState())
 
       act(() => {
@@ -201,8 +304,8 @@ describe('useDocumentsPageState', () => {
     })
   })
 
-  describe('pagination handlers', () => {
-    it('should update page with one-based value', () => {
+  describe('handlePageChange', () => {
+    it('should update current page and call updateQuery', () => {
       const { result } = renderHook(() => useDocumentsPageState())
 
       act(() => {
@@ -210,10 +313,23 @@ describe('useDocumentsPageState', () => {
       })
 
       expect(result.current.currPage).toBe(2)
-      expect(mockUpdateQuery).toHaveBeenCalledWith({ page: 3 })
+      expect(mockUpdateQuery).toHaveBeenCalledWith({ page: 3 }) // newPage + 1
     })
 
-    it('should update limit and reset page', () => {
+    it('should handle page 0 (first page)', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.handlePageChange(0)
+      })
+
+      expect(result.current.currPage).toBe(0)
+      expect(mockUpdateQuery).toHaveBeenCalledWith({ page: 1 })
+    })
+  })
+
+  describe('handleLimitChange', () => {
+    it('should update limit, reset page to 0, and call updateQuery', () => {
       const { result } = renderHook(() => useDocumentsPageState())
 
       act(() => {
@@ -226,29 +342,359 @@ describe('useDocumentsPageState', () => {
     })
   })
 
+  // Selection state
+  describe('selection state', () => {
+    it('should update selectedIds via setSelectedIds', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.setSelectedIds(['doc-1', 'doc-2'])
+      })
+
+      expect(result.current.selectedIds).toEqual(['doc-1', 'doc-2'])
+    })
+  })
+
+  // Polling state management
+  describe('updatePollingState', () => {
+    it('should not update timer when documentsRes is undefined', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.updatePollingState(undefined)
+      })
+
+      // timerCanRun remains true (initial value)
+      expect(result.current.timerCanRun).toBe(true)
+    })
+
+    it('should not update timer when documentsRes.data is undefined', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.updatePollingState({ data: undefined } as unknown as DocumentListResponse)
+      })
+
+      expect(result.current.timerCanRun).toBe(true)
+    })
+
+    it('should set timerCanRun to false when all documents are completed and status filter is all', () => {
+      const response = createDocumentListResponse({
+        data: [
+          createDocumentItem({ indexing_status: 'completed' }),
+          createDocumentItem({ indexing_status: 'completed' }),
+        ] as DocumentListResponse['data'],
+        total: 2,
+      })
+
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.updatePollingState(response)
+      })
+
+      expect(result.current.timerCanRun).toBe(false)
+    })
+
+    it('should set timerCanRun to true when some documents are not completed', () => {
+      const response = createDocumentListResponse({
+        data: [
+          createDocumentItem({ indexing_status: 'completed' }),
+          createDocumentItem({ indexing_status: 'indexing' }),
+        ] as DocumentListResponse['data'],
+        total: 2,
+      })
+
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.updatePollingState(response)
+      })
+
+      expect(result.current.timerCanRun).toBe(true)
+    })
+
+    it('should count paused documents as completed for polling purposes', () => {
+      const response = createDocumentListResponse({
+        data: [
+          createDocumentItem({ indexing_status: 'paused' }),
+          createDocumentItem({ indexing_status: 'completed' }),
+        ] as DocumentListResponse['data'],
+        total: 2,
+      })
+
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.updatePollingState(response)
+      })
+
+      // All docs are "embedded" (completed, paused, error), so hasIncomplete = false
+      // statusFilter is 'all', so shouldForcePolling = false
+      expect(result.current.timerCanRun).toBe(false)
+    })
+
+    it('should count error documents as completed for polling purposes', () => {
+      const response = createDocumentListResponse({
+        data: [
+          createDocumentItem({ indexing_status: 'error' }),
+          createDocumentItem({ indexing_status: 'completed' }),
+        ] as DocumentListResponse['data'],
+        total: 2,
+      })
+
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.updatePollingState(response)
+      })
+
+      expect(result.current.timerCanRun).toBe(false)
+    })
+
+    it('should force polling when status filter is a transient status (queuing)', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      // Set status filter to queuing
+      act(() => {
+        result.current.handleStatusFilterChange('queuing')
+      })
+
+      const response = createDocumentListResponse({
+        data: [
+          createDocumentItem({ indexing_status: 'completed' }),
+        ] as DocumentListResponse['data'],
+        total: 1,
+      })
+
+      act(() => {
+        result.current.updatePollingState(response)
+      })
+
+      // shouldForcePolling = true (queuing is transient), hasIncomplete = false
+      // timerCanRun = true || false = true
+      expect(result.current.timerCanRun).toBe(true)
+    })
+
+    it('should force polling when status filter is indexing', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.handleStatusFilterChange('indexing')
+      })
+
+      const response = createDocumentListResponse({
+        data: [
+          createDocumentItem({ indexing_status: 'completed' }),
+        ] as DocumentListResponse['data'],
+        total: 1,
+      })
+
+      act(() => {
+        result.current.updatePollingState(response)
+      })
+
+      expect(result.current.timerCanRun).toBe(true)
+    })
+
+    it('should force polling when status filter is paused', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.handleStatusFilterChange('paused')
+      })
+
+      const response = createDocumentListResponse({
+        data: [
+          createDocumentItem({ indexing_status: 'paused' }),
+        ] as DocumentListResponse['data'],
+        total: 1,
+      })
+
+      act(() => {
+        result.current.updatePollingState(response)
+      })
+
+      expect(result.current.timerCanRun).toBe(true)
+    })
+
+    it('should not force polling when status filter is a non-transient status (error)', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.handleStatusFilterChange('error')
+      })
+
+      const response = createDocumentListResponse({
+        data: [
+          createDocumentItem({ indexing_status: 'error' }),
+        ] as DocumentListResponse['data'],
+        total: 1,
+      })
+
+      act(() => {
+        result.current.updatePollingState(response)
+      })
+
+      // shouldForcePolling = false (error is not transient), hasIncomplete = false (error is embedded)
+      expect(result.current.timerCanRun).toBe(false)
+    })
+
+    it('should set timerCanRun to true when data is empty and filter is transient', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.handleStatusFilterChange('indexing')
+      })
+
+      const response = createDocumentListResponse({ data: [] as DocumentListResponse['data'], total: 0 })
+
+      act(() => {
+        result.current.updatePollingState(response)
+      })
+
+      // shouldForcePolling = true (indexing is transient), hasIncomplete = false (0 !== 0 is false)
+      expect(result.current.timerCanRun).toBe(true)
+    })
+  })
+
+  // Page adjustment
+  describe('adjustPageForTotal', () => {
+    it('should not adjust page when documentsRes is undefined', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.adjustPageForTotal(undefined)
+      })
+
+      expect(result.current.currPage).toBe(0)
+    })
+
+    it('should not adjust page when currPage is within total pages', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      const response = createDocumentListResponse({ total: 20 })
+
+      act(() => {
+        result.current.adjustPageForTotal(response)
+      })
+
+      // currPage is 0, totalPages is 2, so no adjustment needed
+      expect(result.current.currPage).toBe(0)
+    })
+
+    it('should adjust page to last page when currPage exceeds total pages', () => {
+      mockQuery = { ...mockQuery, page: 6 }
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      // currPage should be 5 (page - 1)
+      expect(result.current.currPage).toBe(5)
+
+      const response = createDocumentListResponse({ total: 30 }) // 30/10 = 3 pages
+
+      act(() => {
+        result.current.adjustPageForTotal(response)
+      })
+
+      // currPage (5) + 1 > totalPages (3), so adjust to totalPages - 1 = 2
+      expect(result.current.currPage).toBe(2)
+      expect(mockUpdateQuery).toHaveBeenCalledWith({ page: 3 }) // handlePageChange passes newPage + 1
+    })
+
+    it('should adjust page to 0 when total is 0 and currPage > 0', () => {
+      mockQuery = { ...mockQuery, page: 3 }
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      const response = createDocumentListResponse({ total: 0 })
+
+      act(() => {
+        result.current.adjustPageForTotal(response)
+      })
+
+      // totalPages = 0, so adjust to max(0 - 1, 0) = 0
+      expect(result.current.currPage).toBe(0)
+      expect(mockUpdateQuery).toHaveBeenCalledWith({ page: 1 })
+    })
+
+    it('should not adjust page when currPage is 0 even if total is 0', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      const response = createDocumentListResponse({ total: 0 })
+
+      act(() => {
+        result.current.adjustPageForTotal(response)
+      })
+
+      // currPage is 0, condition is currPage > 0 so no adjustment
+      expect(mockUpdateQuery).not.toHaveBeenCalled()
+    })
+  })
+
+  // Normalized status filter value
+  describe('normalizedStatusFilterValue', () => {
+    it('should return all for default status', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      expect(result.current.normalizedStatusFilterValue).toBe('all')
+    })
+
+    it('should normalize enabled to available', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.handleStatusFilterChange('enabled')
+      })
+
+      expect(result.current.normalizedStatusFilterValue).toBe('available')
+    })
+
+    it('should return non-aliased status as-is', () => {
+      const { result } = renderHook(() => useDocumentsPageState())
+
+      act(() => {
+        result.current.handleStatusFilterChange('error')
+      })
+
+      expect(result.current.normalizedStatusFilterValue).toBe('error')
+    })
+  })
+
   // Return value shape
   describe('return value', () => {
     it('should return all expected properties', () => {
       const { result } = renderHook(() => useDocumentsPageState())
 
+      // Search state
       expect(result.current).toHaveProperty('inputValue')
+      expect(result.current).toHaveProperty('searchValue')
       expect(result.current).toHaveProperty('debouncedSearchValue')
       expect(result.current).toHaveProperty('handleInputChange')
+
+      // Filter & sort state
       expect(result.current).toHaveProperty('statusFilterValue')
       expect(result.current).toHaveProperty('sortValue')
       expect(result.current).toHaveProperty('normalizedStatusFilterValue')
       expect(result.current).toHaveProperty('handleStatusFilterChange')
       expect(result.current).toHaveProperty('handleStatusFilterClear')
       expect(result.current).toHaveProperty('handleSortChange')
+
+      // Pagination state
       expect(result.current).toHaveProperty('currPage')
       expect(result.current).toHaveProperty('limit')
       expect(result.current).toHaveProperty('handlePageChange')
       expect(result.current).toHaveProperty('handleLimitChange')
+
+      // Selection state
       expect(result.current).toHaveProperty('selectedIds')
       expect(result.current).toHaveProperty('setSelectedIds')
+
+      // Polling state
+      expect(result.current).toHaveProperty('timerCanRun')
+      expect(result.current).toHaveProperty('updatePollingState')
+      expect(result.current).toHaveProperty('adjustPageForTotal')
     })
 
-    it('should expose function handlers', () => {
+    it('should have function types for all handlers', () => {
       const { result } = renderHook(() => useDocumentsPageState())
 
       expect(typeof result.current.handleInputChange).toBe('function')
@@ -258,6 +704,8 @@ describe('useDocumentsPageState', () => {
       expect(typeof result.current.handlePageChange).toBe('function')
       expect(typeof result.current.handleLimitChange).toBe('function')
       expect(typeof result.current.setSelectedIds).toBe('function')
+      expect(typeof result.current.updatePollingState).toBe('function')
+      expect(typeof result.current.adjustPageForTotal).toBe('function')
     })
   })
 })

web/app/components/datasets/documents/hooks/use-document-list-query-state.ts

@@ -1,6 +1,6 @@
-import type { inferParserType } from 'nuqs'
+import type { ReadonlyURLSearchParams } from 'next/navigation'
 import type { SortType } from '@/service/datasets'
-import { createParser, parseAsString, throttle, useQueryStates } from 'nuqs'
+import { usePathname, useRouter, useSearchParams } from 'next/navigation'
 import { useCallback, useMemo } from 'react'
 import { sanitizeStatusValue } from '../status-filter'
 
@@ -13,87 +13,99 @@ const sanitizeSortValue = (value?: string | null): SortType => {
   return (ALLOWED_SORT_VALUES.includes(value as SortType) ? value : '-created_at') as SortType
 }
 
-const sanitizePageValue = (value: number): number => {
-  return Number.isInteger(value) && value > 0 ? value : 1
+export type DocumentListQuery = {
+  page: number
+  limit: number
+  keyword: string
+  status: string
+  sort: SortType
 }
 
-const sanitizeLimitValue = (value: number): number => {
-  return Number.isInteger(value) && value > 0 && value <= 100 ? value : 10
+const DEFAULT_QUERY: DocumentListQuery = {
+  page: 1,
+  limit: 10,
+  keyword: '',
+  status: 'all',
+  sort: '-created_at',
 }
 
-const parseAsPage = createParser<number>({
-  parse: (value) => {
-    const n = Number.parseInt(value, 10)
-    return Number.isNaN(n) || n <= 0 ? null : n
-  },
-  serialize: value => value.toString(),
-}).withDefault(1)
+// Parse the query parameters from the URL search string.
+function parseParams(params: ReadonlyURLSearchParams): DocumentListQuery {
+  const page = Number.parseInt(params.get('page') || '1', 10)
+  const limit = Number.parseInt(params.get('limit') || '10', 10)
+  const keyword = params.get('keyword') || ''
+  const status = sanitizeStatusValue(params.get('status'))
+  const sort = sanitizeSortValue(params.get('sort'))
 
-const parseAsLimit = createParser<number>({
-  parse: (value) => {
-    const n = Number.parseInt(value, 10)
-    return Number.isNaN(n) || n <= 0 || n > 100 ? null : n
-  },
-  serialize: value => value.toString(),
-}).withDefault(10)
-
-const parseAsDocStatus = createParser<string>({
-  parse: value => sanitizeStatusValue(value),
-  serialize: value => value,
-}).withDefault('all')
-
-const parseAsDocSort = createParser<SortType>({
-  parse: value => sanitizeSortValue(value),
-  serialize: value => value,
-}).withDefault('-created_at' as SortType)
-
-const parseAsKeyword = parseAsString.withDefault('')
-
-export const documentListParsers = {
-  page: parseAsPage,
-  limit: parseAsLimit,
-  keyword: parseAsKeyword,
-  status: parseAsDocStatus,
-  sort: parseAsDocSort,
+  return {
+    page: page > 0 ? page : 1,
+    limit: (limit > 0 && limit <= 100) ? limit : 10,
+    keyword: keyword ? decodeURIComponent(keyword) : '',
+    status,
+    sort,
+  }
 }
 
-export type DocumentListQuery = inferParserType<typeof documentListParsers>
+// Update the URL search string with the given query parameters.
+function updateSearchParams(query: DocumentListQuery, searchParams: URLSearchParams) {
+  const { page, limit, keyword, status, sort } = query || {}
 
-// Search input updates can be frequent; throttle URL writes to reduce history/api churn.
-const KEYWORD_URL_UPDATE_THROTTLE = throttle(300)
+  const hasNonDefaultParams = (page && page > 1) || (limit && limit !== 10) || (keyword && keyword.trim())
 
-export function useDocumentListQueryState() {
-  const [query, setQuery] = useQueryStates(documentListParsers)
+  if (hasNonDefaultParams) {
+    searchParams.set('page', (page || 1).toString())
+    searchParams.set('limit', (limit || 10).toString())
+  }
+  else {
+    searchParams.delete('page')
+    searchParams.delete('limit')
+  }
 
+  if (keyword && keyword.trim())
+    searchParams.set('keyword', encodeURIComponent(keyword))
+  else
+    searchParams.delete('keyword')
+
+  const sanitizedStatus = sanitizeStatusValue(status)
+  if (sanitizedStatus && sanitizedStatus !== 'all')
+    searchParams.set('status', sanitizedStatus)
+  else
+    searchParams.delete('status')
+
+  const sanitizedSort = sanitizeSortValue(sort)
+  if (sanitizedSort !== '-created_at')
+    searchParams.set('sort', sanitizedSort)
+  else
+    searchParams.delete('sort')
+}
+
+function useDocumentListQueryState() {
+  const searchParams = useSearchParams()
+  const query = useMemo(() => parseParams(searchParams), [searchParams])
+
+  const router = useRouter()
+  const pathname = usePathname()
+
+  // Helper function to update specific query parameters
   const updateQuery = useCallback((updates: Partial<DocumentListQuery>) => {
-    const patch = { ...updates }
-    if ('page' in patch && patch.page !== undefined)
-      patch.page = sanitizePageValue(patch.page)
-    if ('limit' in patch && patch.limit !== undefined)
-      patch.limit = sanitizeLimitValue(patch.limit)
-    if ('status' in patch)
-      patch.status = sanitizeStatusValue(patch.status)
-    if ('sort' in patch)
-      patch.sort = sanitizeSortValue(patch.sort)
-    if ('keyword' in patch && typeof patch.keyword === 'string' && patch.keyword.trim() === '')
-      patch.keyword = ''
-
-    // If keyword is part of this patch (even with page reset), treat it as a search update:
-    // use replace to avoid creating a history entry per input-driven change.
-    if ('keyword' in patch) {
-      setQuery(patch, {
-        history: 'replace',
-        limitUrlUpdates: patch.keyword === '' ? undefined : KEYWORD_URL_UPDATE_THROTTLE,
-      })
-      return
-    }
-
-    setQuery(patch, { history: 'push' })
-  }, [setQuery])
+    const newQuery = { ...query, ...updates }
+    newQuery.status = sanitizeStatusValue(newQuery.status)
+    newQuery.sort = sanitizeSortValue(newQuery.sort)
+    const params = new URLSearchParams()
+    updateSearchParams(newQuery, params)
+    const search = params.toString()
+    const queryString = search ? `?${search}` : ''
+    router.push(`${pathname}${queryString}`, { scroll: false })
+  }, [query, router, pathname])
 
+  // Helper function to reset query to defaults
   const resetQuery = useCallback(() => {
-    setQuery(null, { history: 'replace' })
-  }, [setQuery])
+    const params = new URLSearchParams()
+    updateSearchParams(DEFAULT_QUERY, params)
+    const search = params.toString()
+    const queryString = search ? `?${search}` : ''
+    router.push(`${pathname}${queryString}`, { scroll: false })
+  }, [router, pathname])
 
   return useMemo(() => ({
     query,
@@ -101,3 +113,5 @@ export function useDocumentListQueryState() {
     resetQuery,
   }), [query, updateQuery, resetQuery])
 }
+
+export default useDocumentListQueryState

web/app/components/datasets/documents/hooks/use-documents-page-state.ts

@@ -1,63 +1,175 @@
+import type { DocumentListResponse } from '@/models/datasets'
 import type { SortType } from '@/service/datasets'
-import { useDebounce } from 'ahooks'
-import { useCallback, useState } from 'react'
+import { useDebounce, useDebounceFn } from 'ahooks'
+import { useCallback, useEffect, useMemo, useState } from 'react'
 import { normalizeStatusForQuery, sanitizeStatusValue } from '../status-filter'
-import { useDocumentListQueryState } from './use-document-list-query-state'
+import useDocumentListQueryState from './use-document-list-query-state'
 
+/**
+ * Custom hook to manage documents page state including:
+ * - Search state (input value, debounced search value)
+ * - Filter state (status filter, sort value)
+ * - Pagination state (current page, limit)
+ * - Selection state (selected document ids)
+ * - Polling state (timer control for auto-refresh)
+ */
 export function useDocumentsPageState() {
   const { query, updateQuery } = useDocumentListQueryState()
 
-  const inputValue = query.keyword
-  const debouncedSearchValue = useDebounce(query.keyword, { wait: 500 })
+  // Search state
+  const [inputValue, setInputValue] = useState<string>('')
+  const [searchValue, setSearchValue] = useState<string>('')
+  const debouncedSearchValue = useDebounce(searchValue, { wait: 500 })
 
-  const statusFilterValue = sanitizeStatusValue(query.status)
-  const sortValue = query.sort
-  const normalizedStatusFilterValue = normalizeStatusForQuery(statusFilterValue)
+  // Filter & sort state
+  const [statusFilterValue, setStatusFilterValue] = useState<string>(() => sanitizeStatusValue(query.status))
+  const [sortValue, setSortValue] = useState<SortType>(query.sort)
+  const normalizedStatusFilterValue = useMemo(
+    () => normalizeStatusForQuery(statusFilterValue),
+    [statusFilterValue],
+  )
 
-  const currPage = query.page - 1
-  const limit = query.limit
+  // Pagination state
+  const [currPage, setCurrPage] = useState<number>(query.page - 1)
+  const [limit, setLimit] = useState<number>(query.limit)
 
+  // Selection state
   const [selectedIds, setSelectedIds] = useState<string[]>([])
 
+  // Polling state
+  const [timerCanRun, setTimerCanRun] = useState(true)
+
+  // Initialize search value from URL on mount
+  useEffect(() => {
+    if (query.keyword) {
+      setInputValue(query.keyword)
+      setSearchValue(query.keyword)
+    }
+  }, []) // Only run on mount
+
+  // Sync local state with URL query changes
+  useEffect(() => {
+    setCurrPage(query.page - 1)
+    setLimit(query.limit)
+    if (query.keyword !== searchValue) {
+      setInputValue(query.keyword)
+      setSearchValue(query.keyword)
+    }
+    setStatusFilterValue((prev) => {
+      const nextValue = sanitizeStatusValue(query.status)
+      return prev === nextValue ? prev : nextValue
+    })
+    setSortValue(query.sort)
+  }, [query])
+
+  // Update URL when search changes
+  useEffect(() => {
+    if (debouncedSearchValue !== query.keyword) {
+      setCurrPage(0)
+      updateQuery({ keyword: debouncedSearchValue, page: 1 })
+    }
+  }, [debouncedSearchValue, query.keyword, updateQuery])
+
+  // Clear selection when search changes
+  useEffect(() => {
+    if (searchValue !== query.keyword)
+      setSelectedIds([])
+  }, [searchValue, query.keyword])
+
+  // Clear selection when status filter changes
+  useEffect(() => {
+    setSelectedIds([])
+  }, [normalizedStatusFilterValue])
+
+  // Page change handler
   const handlePageChange = useCallback((newPage: number) => {
+    setCurrPage(newPage)
     updateQuery({ page: newPage + 1 })
   }, [updateQuery])
 
+  // Limit change handler
   const handleLimitChange = useCallback((newLimit: number) => {
+    setLimit(newLimit)
+    setCurrPage(0)
     updateQuery({ limit: newLimit, page: 1 })
   }, [updateQuery])
 
-  const handleInputChange = useCallback((value: string) => {
-    if (value !== query.keyword)
-      setSelectedIds([])
-    updateQuery({ keyword: value, page: 1 })
-  }, [query.keyword, updateQuery])
+  // Debounced search handler
+  const { run: handleSearch } = useDebounceFn(() => {
+    setSearchValue(inputValue)
+  }, { wait: 500 })
 
+  // Input change handler
+  const handleInputChange = useCallback((value: string) => {
+    setInputValue(value)
+    handleSearch()
+  }, [handleSearch])
+
+  // Status filter change handler
   const handleStatusFilterChange = useCallback((value: string) => {
     const selectedValue = sanitizeStatusValue(value)
-    setSelectedIds([])
+    setStatusFilterValue(selectedValue)
+    setCurrPage(0)
     updateQuery({ status: selectedValue, page: 1 })
   }, [updateQuery])
 
+  // Status filter clear handler
   const handleStatusFilterClear = useCallback(() => {
     if (statusFilterValue === 'all')
       return
-    setSelectedIds([])
+    setStatusFilterValue('all')
+    setCurrPage(0)
     updateQuery({ status: 'all', page: 1 })
   }, [statusFilterValue, updateQuery])
 
+  // Sort change handler
   const handleSortChange = useCallback((value: string) => {
     const next = value as SortType
     if (next === sortValue)
       return
+    setSortValue(next)
+    setCurrPage(0)
     updateQuery({ sort: next, page: 1 })
   }, [sortValue, updateQuery])
 
+  // Update polling state based on documents response
+  const updatePollingState = useCallback((documentsRes: DocumentListResponse | undefined) => {
+    if (!documentsRes?.data)
+      return
+
+    let completedNum = 0
+    documentsRes.data.forEach((documentItem) => {
+      const { indexing_status } = documentItem
+      const isEmbedded = indexing_status === 'completed' || indexing_status === 'paused' || indexing_status === 'error'
+      if (isEmbedded)
+        completedNum++
+    })
+
+    const hasIncompleteDocuments = completedNum !== documentsRes.data.length
+    const transientStatuses = ['queuing', 'indexing', 'paused']
+    const shouldForcePolling = normalizedStatusFilterValue === 'all'
+      ? false
+      : transientStatuses.includes(normalizedStatusFilterValue)
+    setTimerCanRun(shouldForcePolling || hasIncompleteDocuments)
+  }, [normalizedStatusFilterValue])
+
+  // Adjust page when total pages change
+  const adjustPageForTotal = useCallback((documentsRes: DocumentListResponse | undefined) => {
+    if (!documentsRes)
+      return
+    const totalPages = Math.ceil(documentsRes.total / limit)
+    if (currPage > 0 && currPage + 1 > totalPages)
+      handlePageChange(totalPages > 0 ? totalPages - 1 : 0)
+  }, [limit, currPage, handlePageChange])
+
   return {
+    // Search state
     inputValue,
+    searchValue,
     debouncedSearchValue,
     handleInputChange,
 
+    // Filter & sort state
     statusFilterValue,
     sortValue,
     normalizedStatusFilterValue,
@@ -65,12 +177,21 @@ export function useDocumentsPageState() {
     handleStatusFilterClear,
     handleSortChange,
 
+    // Pagination state
     currPage,
     limit,
     handlePageChange,
     handleLimitChange,
 
+    // Selection state
     selectedIds,
     setSelectedIds,
+
+    // Polling state
+    timerCanRun,
+    updatePollingState,
+    adjustPageForTotal,
   }
 }
+
+export default useDocumentsPageState

web/app/components/datasets/documents/index.tsx

@@ -1,7 +1,7 @@
 'use client'
 import type { FC } from 'react'
 import { useRouter } from 'next/navigation'
-import { useCallback } from 'react'
+import { useCallback, useEffect } from 'react'
 import Loading from '@/app/components/base/loading'
 import { useDatasetDetailContextWithSelector } from '@/context/dataset-detail'
 import { useProviderContext } from '@/context/provider-context'
@@ -13,16 +13,12 @@ import useEditDocumentMetadata from '../metadata/hooks/use-edit-dataset-metadata
 import DocumentsHeader from './components/documents-header'
 import EmptyElement from './components/empty-element'
 import List from './components/list'
-import { useDocumentsPageState } from './hooks/use-documents-page-state'
+import useDocumentsPageState from './hooks/use-documents-page-state'
 
 type IDocumentsProps = {
   datasetId: string
 }
 
-const POLLING_INTERVAL = 2500
-const TERMINAL_INDEXING_STATUSES = new Set(['completed', 'paused', 'error'])
-const FORCED_POLLING_STATUSES = new Set(['queuing', 'indexing', 'paused'])
-
 const Documents: FC<IDocumentsProps> = ({ datasetId }) => {
   const router = useRouter()
   const { plan } = useProviderContext()
@@ -48,6 +44,9 @@ const Documents: FC<IDocumentsProps> = ({ datasetId }) => {
     handleLimitChange,
     selectedIds,
     setSelectedIds,
+    timerCanRun,
+    updatePollingState,
+    adjustPageForTotal,
   } = useDocumentsPageState()
 
   // Fetch document list
@@ -60,17 +59,19 @@ const Documents: FC<IDocumentsProps> = ({ datasetId }) => {
       status: normalizedStatusFilterValue,
       sort: sortValue,
     },
-    refetchInterval: (query) => {
-      const shouldForcePolling = normalizedStatusFilterValue !== 'all'
-        && FORCED_POLLING_STATUSES.has(normalizedStatusFilterValue)
-      const documents = query.state.data?.data
-      if (!documents)
-        return POLLING_INTERVAL
-      const hasIncompleteDocuments = documents.some(({ indexing_status }) => !TERMINAL_INDEXING_STATUSES.has(indexing_status))
-      return shouldForcePolling || hasIncompleteDocuments ? POLLING_INTERVAL : false
-    },
+    refetchInterval: timerCanRun ? 2500 : 0,
   })
 
+  // Update polling state when documents change
+  useEffect(() => {
+    updatePollingState(documentsRes)
+  }, [documentsRes, updatePollingState])
+
+  // Adjust page when total changes
+  useEffect(() => {
+    adjustPageForTotal(documentsRes)
+  }, [documentsRes, adjustPageForTotal])
+
   // Invalidation hooks
   const invalidDocumentList = useInvalidDocumentList(datasetId)
   const invalidDocumentDetail = useInvalidDocumentDetail()
@@ -118,7 +119,7 @@ const Documents: FC<IDocumentsProps> = ({ datasetId }) => {
 
   // Render content based on loading and data state
   const renderContent = () => {
-    if (isListLoading && !documentsRes)
+    if (isListLoading)
       return <Loading type="app" />
 
     if (total > 0) {
@@ -130,8 +131,8 @@ const Documents: FC<IDocumentsProps> = ({ datasetId }) => {
           onUpdate={handleUpdate}
           selectedIds={selectedIds}
           onSelectedIdChange={setSelectedIds}
+          statusFilterValue={normalizedStatusFilterValue}
           remoteSortValue={sortValue}
-          onSortChange={handleSortChange}
           pagination={{
             total,
             limit,

web/app/components/explore/app-list/__tests__/index.spec.tsx

@@ -1,12 +1,12 @@
 import type { Mock } from 'vitest'
 import type { CreateAppModalProps } from '@/app/components/explore/create-app-modal'
 import type { App } from '@/models/explore'
-import { act, fireEvent, screen, waitFor } from '@testing-library/react'
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import { useAppContext } from '@/context/app-context'
 import { useGlobalPublicStore } from '@/context/global-public-context'
 import { fetchAppDetail } from '@/service/explore'
 import { useMembers } from '@/service/use-common'
-import { renderWithNuqs } from '@/test/nuqs-testing'
 import { AppModeEnum } from '@/types/app'
 import AppList from '../index'
 
@@ -132,9 +132,10 @@ const mockMemberRole = (hasEditPermission: boolean) => {
 
 const renderAppList = (hasEditPermission = false, onSuccess?: () => void, searchParams?: Record<string, string>) => {
   mockMemberRole(hasEditPermission)
-  return renderWithNuqs(
-    <AppList onSuccess={onSuccess} />,
-    { searchParams },
+  return render(
+    <NuqsTestingAdapter searchParams={searchParams}>
+      <AppList onSuccess={onSuccess} />
+    </NuqsTestingAdapter>,
   )
 }
 

web/app/components/goto-anything/actions/commands/slash.tsx

@@ -14,17 +14,13 @@ import { slashCommandRegistry } from './registry'
 import { themeCommand } from './theme'
 import { zenCommand } from './zen'
 
+const i18n = getI18n()
+
 export const slashAction: ActionItem = {
   key: '/',
   shortcut: '/',
-  get title() {
-    const i18n = getI18n()
-    return i18n.t('gotoAnything.actions.slashTitle', { ns: 'app' })
-  },
-  get description() {
-    const i18n = getI18n()
-    return i18n.t('gotoAnything.actions.slashDesc', { ns: 'app' })
-  },
+  title: i18n.t('gotoAnything.actions.slashTitle', { ns: 'app' }),
+  description: i18n.t('gotoAnything.actions.slashDesc', { ns: 'app' }),
   action: (result) => {
     if (result.type !== 'command')
       return
@@ -32,7 +28,6 @@ export const slashAction: ActionItem = {
     executeCommand(command, args)
   },
   search: async (query, _searchTerm = '') => {
-    const i18n = getI18n()
     // Delegate all search logic to the command registry system
     return slashCommandRegistry.search(query, i18n.language)
   },

web/app/components/plugins/marketplace/__tests__/atoms.spec.tsx

@@ -1,20 +1,21 @@
+import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
 import type { ReactNode } from 'react'
 import { act, renderHook } from '@testing-library/react'
 import { Provider as JotaiProvider } from 'jotai'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { createNuqsTestWrapper } from '@/test/nuqs-testing'
 import { DEFAULT_SORT } from '../constants'
 
 const createWrapper = (searchParams = '') => {
-  const { wrapper: NuqsWrapper } = createNuqsTestWrapper({ searchParams })
+  const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
   const wrapper = ({ children }: { children: ReactNode }) => (
     <JotaiProvider>
-      <NuqsWrapper>
+      <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={onUrlUpdate}>
         {children}
-      </NuqsWrapper>
+      </NuqsTestingAdapter>
     </JotaiProvider>
   )
-  return { wrapper }
+  return { wrapper, onUrlUpdate }
 }
 
 describe('Marketplace sort atoms', () => {

web/app/components/plugins/marketplace/__tests__/plugin-type-switch.spec.tsx

@@ -1,8 +1,9 @@
+import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
 import type { ReactNode } from 'react'
 import { fireEvent, render, screen } from '@testing-library/react'
 import { Provider as JotaiProvider } from 'jotai'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { createNuqsTestWrapper } from '@/test/nuqs-testing'
 import PluginTypeSwitch from '../plugin-type-switch'
 
 vi.mock('#i18n', () => ({
@@ -24,15 +25,15 @@ vi.mock('#i18n', () => ({
 }))
 
 const createWrapper = (searchParams = '') => {
-  const { wrapper: NuqsWrapper } = createNuqsTestWrapper({ searchParams })
+  const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
   const Wrapper = ({ children }: { children: ReactNode }) => (
     <JotaiProvider>
-      <NuqsWrapper>
+      <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={onUrlUpdate}>
         {children}
-      </NuqsWrapper>
+      </NuqsTestingAdapter>
     </JotaiProvider>
   )
-  return { Wrapper }
+  return { Wrapper, onUrlUpdate }
 }
 
 describe('PluginTypeSwitch', () => {

web/app/components/plugins/marketplace/__tests__/state.spec.tsx

@@ -2,8 +2,8 @@ import type { ReactNode } from 'react'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { renderHook, waitFor } from '@testing-library/react'
 import { Provider as JotaiProvider } from 'jotai'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { createNuqsTestWrapper } from '@/test/nuqs-testing'
 
 vi.mock('@/config', () => ({
   API_PREFIX: '/api',
@@ -37,7 +37,6 @@ vi.mock('@/service/client', () => ({
 }))
 
 const createWrapper = (searchParams = '') => {
-  const { wrapper: NuqsWrapper } = createNuqsTestWrapper({ searchParams })
   const queryClient = new QueryClient({
     defaultOptions: {
       queries: { retry: false, gcTime: 0 },
@@ -46,9 +45,9 @@ const createWrapper = (searchParams = '') => {
   const Wrapper = ({ children }: { children: ReactNode }) => (
     <JotaiProvider>
       <QueryClientProvider client={queryClient}>
-        <NuqsWrapper>
+        <NuqsTestingAdapter searchParams={searchParams}>
           {children}
-        </NuqsWrapper>
+        </NuqsTestingAdapter>
       </QueryClientProvider>
     </JotaiProvider>
   )

web/app/components/plugins/marketplace/__tests__/sticky-search-and-switch-wrapper.spec.tsx

@@ -1,8 +1,8 @@
 import type { ReactNode } from 'react'
 import { render } from '@testing-library/react'
 import { Provider as JotaiProvider } from 'jotai'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { createNuqsTestWrapper } from '@/test/nuqs-testing'
 import StickySearchAndSwitchWrapper from '../sticky-search-and-switch-wrapper'
 
 vi.mock('#i18n', () => ({
@@ -20,17 +20,13 @@ vi.mock('../search-box/search-box-wrapper', () => ({
   default: () => <div data-testid="search-box-wrapper">SearchBoxWrapper</div>,
 }))
 
-const createWrapper = () => {
-  const { wrapper: NuqsWrapper } = createNuqsTestWrapper()
-  const Wrapper = ({ children }: { children: ReactNode }) => (
-    <JotaiProvider>
-      <NuqsWrapper>
-        {children}
-      </NuqsWrapper>
-    </JotaiProvider>
-  )
-  return { Wrapper }
-}
+const Wrapper = ({ children }: { children: ReactNode }) => (
+  <JotaiProvider>
+    <NuqsTestingAdapter>
+      {children}
+    </NuqsTestingAdapter>
+  </JotaiProvider>
+)
 
 describe('StickySearchAndSwitchWrapper', () => {
   beforeEach(() => {
@@ -38,7 +34,6 @@ describe('StickySearchAndSwitchWrapper', () => {
   })
 
   it('should render SearchBoxWrapper and PluginTypeSwitch', () => {
-    const { Wrapper } = createWrapper()
     const { getByTestId } = render(
       <StickySearchAndSwitchWrapper />,
       { wrapper: Wrapper },
@@ -49,7 +44,6 @@ describe('StickySearchAndSwitchWrapper', () => {
   })
 
   it('should not apply sticky class when no pluginTypeSwitchClassName', () => {
-    const { Wrapper } = createWrapper()
     const { container } = render(
       <StickySearchAndSwitchWrapper />,
       { wrapper: Wrapper },
@@ -61,7 +55,6 @@ describe('StickySearchAndSwitchWrapper', () => {
   })
 
   it('should apply sticky class when pluginTypeSwitchClassName contains top-', () => {
-    const { Wrapper } = createWrapper()
     const { container } = render(
       <StickySearchAndSwitchWrapper pluginTypeSwitchClassName="top-10" />,
       { wrapper: Wrapper },
@@ -74,7 +67,6 @@ describe('StickySearchAndSwitchWrapper', () => {
   })
 
   it('should not apply sticky class when pluginTypeSwitchClassName does not contain top-', () => {
-    const { Wrapper } = createWrapper()
     const { container } = render(
       <StickySearchAndSwitchWrapper pluginTypeSwitchClassName="custom-class" />,
       { wrapper: Wrapper },

web/app/components/plugins/marketplace/hydration-server.tsx

@@ -1,5 +1,4 @@
 import type { SearchParams } from 'nuqs/server'
-import type { MarketplaceSearchParams } from './search-params'
 import { dehydrate, HydrationBoundary } from '@tanstack/react-query'
 import { createLoader } from 'nuqs/server'
 import { getQueryClientServer } from '@/context/query-client-server'
@@ -15,7 +14,7 @@ async function getDehydratedState(searchParams?: Promise<SearchParams>) {
     return
   }
   const loadSearchParams = createLoader(marketplaceSearchParamsParsers)
-  const params: MarketplaceSearchParams = await loadSearchParams(searchParams)
+  const params = await loadSearchParams(searchParams)
 
   if (!PLUGIN_CATEGORY_WITH_COLLECTIONS.has(params.category)) {
     return

web/app/components/plugins/marketplace/search-params.ts

@@ -1,4 +1,3 @@
-import type { inferParserType } from 'nuqs/server'
 import type { ActivePluginType } from './constants'
 import { parseAsArrayOf, parseAsString, parseAsStringEnum } from 'nuqs/server'
 import { PLUGIN_TYPE_SEARCH_MAP } from './constants'
@@ -8,5 +7,3 @@ export const marketplaceSearchParamsParsers = {
   q: parseAsString.withDefault('').withOptions({ history: 'replace' }),
   tags: parseAsArrayOf(parseAsString).withDefault([]).withOptions({ history: 'replace' }),
 }
-
-export type MarketplaceSearchParams = inferParserType<typeof marketplaceSearchParamsParsers>

web/app/components/plugins/plugin-page/__tests__/context.spec.tsx

@@ -7,9 +7,6 @@ import { PluginPageContext, PluginPageContextProvider, usePluginPageContext } fr
 
 // Mock dependencies
 vi.mock('nuqs', () => ({
-  parseAsStringEnum: vi.fn(() => ({
-    withDefault: vi.fn(() => ({})),
-  })),
   useQueryState: vi.fn(() => ['plugins', vi.fn()]),
 }))
 

web/app/components/plugins/plugin-page/__tests__/index.spec.tsx

@@ -80,9 +80,6 @@ vi.mock('@/service/use-plugins', () => ({
 }))
 
 vi.mock('nuqs', () => ({
-  parseAsStringEnum: vi.fn(() => ({
-    withDefault: vi.fn(() => ({})),
-  })),
   useQueryState: vi.fn(() => ['plugins', vi.fn()]),
 }))
 

web/app/components/plugins/plugin-page/context.tsx

@@ -3,7 +3,7 @@
 import type { ReactNode, RefObject } from 'react'
 import type { FilterState } from './filter-management'
 import { noop } from 'es-toolkit/function'
-import { parseAsStringEnum, useQueryState } from 'nuqs'
+import { useQueryState } from 'nuqs'
 import {
   useMemo,
   useRef,
@@ -15,19 +15,6 @@ import {
 } from 'use-context-selector'
 import { useGlobalPublicStore } from '@/context/global-public-context'
 import { PLUGIN_PAGE_TABS_MAP, usePluginPageTabs } from '../hooks'
-import { PLUGIN_TYPE_SEARCH_MAP } from '../marketplace/constants'
-
-export type PluginPageTab = typeof PLUGIN_PAGE_TABS_MAP[keyof typeof PLUGIN_PAGE_TABS_MAP]
-  | (typeof PLUGIN_TYPE_SEARCH_MAP)[keyof typeof PLUGIN_TYPE_SEARCH_MAP]
-
-const PLUGIN_PAGE_TAB_VALUES: PluginPageTab[] = [
-  PLUGIN_PAGE_TABS_MAP.plugins,
-  PLUGIN_PAGE_TABS_MAP.marketplace,
-  ...Object.values(PLUGIN_TYPE_SEARCH_MAP),
-]
-
-const parseAsPluginPageTab = parseAsStringEnum<PluginPageTab>(PLUGIN_PAGE_TAB_VALUES)
-  .withDefault(PLUGIN_PAGE_TABS_MAP.plugins)
 
 export type PluginPageContextValue = {
   containerRef: RefObject<HTMLDivElement | null>
@@ -35,8 +22,8 @@ export type PluginPageContextValue = {
   setCurrentPluginID: (pluginID?: string) => void
   filters: FilterState
   setFilters: (filter: FilterState) => void
-  activeTab: PluginPageTab
-  setActiveTab: (tab: PluginPageTab) => void
+  activeTab: string
+  setActiveTab: (tab: string) => void
   options: Array<{ value: string, text: string }>
 }
 
@@ -52,7 +39,7 @@ export const PluginPageContext = createContext<PluginPageContextValue>({
     searchQuery: '',
   },
   setFilters: noop,
-  activeTab: PLUGIN_PAGE_TABS_MAP.plugins,
+  activeTab: '',
   setActiveTab: noop,
   options: [],
 })
@@ -81,7 +68,9 @@ export const PluginPageContextProvider = ({
   const options = useMemo(() => {
     return enable_marketplace ? tabs : tabs.filter(tab => tab.value !== PLUGIN_PAGE_TABS_MAP.marketplace)
   }, [tabs, enable_marketplace])
-  const [activeTab, setActiveTab] = useQueryState('tab', parseAsPluginPageTab)
+  const [activeTab, setActiveTab] = useQueryState('tab', {
+    defaultValue: options[0].value,
+  })
 
   return (
     <PluginPageContext.Provider

web/app/components/plugins/plugin-page/index.tsx

@@ -1,7 +1,6 @@
 'use client'
 
 import type { Dependency, PluginDeclaration, PluginManifestInMarket } from '../types'
-import type { PluginPageTab } from './context'
 import {
   RiBookOpenLine,
   RiDragDropLine,
@@ -38,16 +37,6 @@ import PluginTasks from './plugin-tasks'
 import useReferenceSetting from './use-reference-setting'
 import { useUploader } from './use-uploader'
 
-const pluginPageTabSet = new Set<string>([
-  PLUGIN_PAGE_TABS_MAP.plugins,
-  PLUGIN_PAGE_TABS_MAP.marketplace,
-  ...Object.values(PLUGIN_TYPE_SEARCH_MAP),
-])
-
-const isPluginPageTab = (value: string): value is PluginPageTab => {
-  return pluginPageTabSet.has(value)
-}
-
 export type PluginPageProps = {
   plugins: React.ReactNode
   marketplace: React.ReactNode
@@ -165,10 +154,7 @@ const PluginPage = ({
           <div className="flex-1">
             <TabSlider
               value={isPluginsTab ? PLUGIN_PAGE_TABS_MAP.plugins : PLUGIN_PAGE_TABS_MAP.marketplace}
-              onChange={(nextTab) => {
-                if (isPluginPageTab(nextTab))
-                  setActiveTab(nextTab)
-              }}
+              onChange={setActiveTab}
               options={options}
             />
           </div>

web/app/components/tools/__tests__/provider-list.spec.tsx

@@ -1,6 +1,6 @@
-import { cleanup, fireEvent, screen } from '@testing-library/react'
+import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { renderWithNuqs } from '@/test/nuqs-testing'
 import { ToolTypeEnum } from '../../workflow/block-selector/types'
 import ProviderList from '../provider-list'
 import { getToolType } from '../utils'
@@ -206,9 +206,10 @@ describe('getToolType', () => {
 })
 
 const renderProviderList = (searchParams?: Record<string, string>) => {
-  return renderWithNuqs(
-    <ProviderList />,
-    { searchParams },
+  return render(
+    <NuqsTestingAdapter searchParams={searchParams}>
+      <ProviderList />
+    </NuqsTestingAdapter>,
   )
 }
 

web/app/components/tools/provider-list.tsx

@@ -1,6 +1,6 @@
 'use client'
 import type { Collection } from './types'
-import { parseAsStringLiteral, useQueryState } from 'nuqs'
+import { useQueryState } from 'nuqs'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import Input from '@/app/components/base/input'
@@ -23,17 +23,6 @@ import { useMarketplace } from './marketplace/hooks'
 import MCPList from './mcp'
 import { getToolType } from './utils'
 
-const TOOL_PROVIDER_CATEGORY_VALUES = ['builtin', 'api', 'workflow', 'mcp'] as const
-type ToolProviderCategory = typeof TOOL_PROVIDER_CATEGORY_VALUES[number]
-const toolProviderCategorySet = new Set<string>(TOOL_PROVIDER_CATEGORY_VALUES)
-
-const isToolProviderCategory = (value: string): value is ToolProviderCategory => {
-  return toolProviderCategorySet.has(value)
-}
-
-const parseAsToolProviderCategory = parseAsStringLiteral(TOOL_PROVIDER_CATEGORY_VALUES)
-  .withDefault('builtin')
-
 const ProviderList = () => {
   // const searchParams = useSearchParams()
   // searchParams.get('category') === 'workflow'
@@ -42,7 +31,9 @@ const ProviderList = () => {
   const { enable_marketplace } = useGlobalPublicStore(s => s.systemFeatures)
   const containerRef = useRef<HTMLDivElement>(null)
 
-  const [activeTab, setActiveTab] = useQueryState('category', parseAsToolProviderCategory)
+  const [activeTab, setActiveTab] = useQueryState('category', {
+    defaultValue: 'builtin',
+  })
   const options = [
     { value: 'builtin', text: t('type.builtIn', { ns: 'tools' }) },
     { value: 'api', text: t('type.custom', { ns: 'tools' }) },
@@ -133,8 +124,6 @@ const ProviderList = () => {
             <TabSliderNew
               value={activeTab}
               onChange={(state) => {
-                if (!isToolProviderCategory(state))
-                  return
                 setActiveTab(state)
                 if (state !== activeTab)
                   setCurrentProviderId(undefined)

web/context/modal-context.test.tsx

@@ -1,9 +1,9 @@
-import { act, screen, waitFor } from '@testing-library/react'
+import { act, render, screen, waitFor } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import * as React from 'react'
 import { defaultPlan } from '@/app/components/billing/config'
 import { Plan } from '@/app/components/billing/type'
 import { ModalContextProvider } from '@/context/modal-context'
-import { renderWithNuqs } from '@/test/nuqs-testing'
 
 vi.mock('@/config', async (importOriginal) => {
   const actual = await importOriginal<typeof import('@/config')>()
@@ -71,10 +71,12 @@ const createPlan = (overrides: PlanOverrides = {}): PlanShape => ({
   },
 })
 
-const renderProvider = () => renderWithNuqs(
-  <ModalContextProvider>
-    <div data-testid="modal-context-test-child" />
-  </ModalContextProvider>,
+const renderProvider = () => render(
+  <NuqsTestingAdapter>
+    <ModalContextProvider>
+      <div data-testid="modal-context-test-child" />
+    </ModalContextProvider>
+  </NuqsTestingAdapter>,
 )
 
 describe('ModalContextProvider trigger events limit modal', () => {

web/context/modal-context.tsx

@@ -158,7 +158,7 @@ export const ModalContextProvider = ({
 }: ModalContextProviderProps) => {
   // Use nuqs hooks for URL-based modal state management
   const [showPricingModal, setPricingModalOpen] = usePricingModal()
-  const [urlAccountModalState, setUrlAccountModalState] = useAccountSettingModal()
+  const [urlAccountModalState, setUrlAccountModalState] = useAccountSettingModal<AccountSettingTab>()
 
   const accountSettingCallbacksRef = useRef<Omit<ModalState<AccountSettingTab>, 'payload'> | null>(null)
   const accountSettingTab = urlAccountModalState.isOpen

web/docs/test.md

@@ -225,38 +225,6 @@ Simulate the interactions that matter to users—primary clicks, change events,
 
 Mock the specific Next.js navigation hooks your component consumes (`useRouter`, `usePathname`, `useSearchParams`) and drive realistic routing flows—query parameters, redirects, guarded routes, URL updates—while asserting the rendered outcome or navigation side effects.
 
-#### 7.1 `nuqs` Query State Testing
-
-When testing code that uses `useQueryState` or `useQueryStates`, treat `nuqs` as the source of truth for URL synchronization.
-
-- ✅ In runtime, keep `NuqsAdapter` in app layout (already wired in `app/layout.tsx`).
-- ✅ In tests, wrap with `NuqsTestingAdapter` (prefer helper utilities from `@/test/nuqs-testing`).
-- ✅ Assert URL behavior via `onUrlUpdate` events (`searchParams`, `options.history`) instead of only asserting router mocks.
-- ✅ For custom parsers created with `createParser`, keep `parse` and `serialize` bijective (round-trip safe). Add edge-case coverage for values like `%2F`, `%25`, spaces, and legacy encoded URLs.
-- ✅ Assert default-clearing behavior explicitly (`clearOnDefault` semantics remove params when value equals default).
-- ⚠️ Only mock `nuqs` directly when URL behavior is intentionally out of scope for the test. For ESM-safe partial mocks, use async `vi.mock` with `importOriginal`.
-
-Example:
-
-```tsx
-import { renderHookWithNuqs } from '@/test/nuqs-testing'
-
-it('should update query with push history', async () => {
-  const { result, onUrlUpdate } = renderHookWithNuqs(() => useMyQueryState(), {
-    searchParams: '?page=1',
-  })
-
-  act(() => {
-    result.current.setQuery({ page: 2 })
-  })
-
-  await waitFor(() => expect(onUrlUpdate).toHaveBeenCalled())
-  const update = onUrlUpdate.mock.calls.at(-1)![0]
-  expect(update.options.history).toBe('push')
-  expect(update.searchParams.get('page')).toBe('2')
-})
-```
-
 ### 8. Edge Cases (REQUIRED - All Components)
 
 **Must Test**:

web/eslint-suppressions.json

@@ -3404,6 +3404,11 @@
       "count": 1
     }
   },
+  "app/components/datasets/documents/components/list.tsx": {
+    "react-refresh/only-export-components": {
+      "count": 1
+    }
+  },
   "app/components/datasets/documents/components/operations.tsx": {
     "no-restricted-imports": {
       "count": 1
@@ -3848,6 +3853,16 @@
       "count": 3
     }
   },
+  "app/components/datasets/documents/hooks/use-documents-page-state.ts": {
+    "react-hooks-extra/no-direct-set-state-in-use-effect": {
+      "count": 12
+    }
+  },
+  "app/components/datasets/documents/index.tsx": {
+    "react-hooks-extra/no-direct-set-state-in-use-effect": {
+      "count": 2
+    }
+  },
   "app/components/datasets/documents/status-item/index.tsx": {
     "no-restricted-imports": {
       "count": 1

web/hooks/use-query-params.spec.tsx

@@ -1,6 +1,8 @@
-import { act, waitFor } from '@testing-library/react'
+import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
+import type { ReactNode } from 'react'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
 import { ACCOUNT_SETTING_MODAL_ACTION } from '@/app/components/header/account-setting/constants'
-import { renderHookWithNuqs } from '@/test/nuqs-testing'
 import {
   clearQueryParams,
   PRICING_MODAL_QUERY_PARAM,
@@ -18,7 +20,14 @@ vi.mock('@/utils/client', () => ({
 }))
 
 const renderWithAdapter = <T,>(hook: () => T, searchParams = '') => {
-  return renderHookWithNuqs(hook, { searchParams })
+  const onUrlUpdate = vi.fn<(event: UrlUpdateEvent) => void>()
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={onUrlUpdate}>
+      {children}
+    </NuqsTestingAdapter>
+  )
+  const { result } = renderHook(hook, { wrapper })
+  return { result, onUrlUpdate }
 }
 
 // Query param hooks: defaults, parsing, and URL sync behavior.

web/hooks/use-query-params.ts

@@ -13,19 +13,14 @@
  * - Use shallow routing to avoid unnecessary re-renders
  */
 
-import type { AccountSettingTab } from '@/app/components/header/account-setting/constants'
 import {
   createParser,
-  parseAsStringEnum,
-  parseAsStringLiteral,
+  parseAsString,
   useQueryState,
   useQueryStates,
 } from 'nuqs'
 import { useCallback } from 'react'
-import {
-  ACCOUNT_SETTING_MODAL_ACTION,
-  ACCOUNT_SETTING_TAB,
-} from '@/app/components/header/account-setting/constants'
+import { ACCOUNT_SETTING_MODAL_ACTION } from '@/app/components/header/account-setting/constants'
 import { isServer } from '@/utils/client'
 
 /**
@@ -57,10 +52,6 @@ export function usePricingModal() {
   )
 }
 
-const accountSettingTabValues = Object.values(ACCOUNT_SETTING_TAB) as AccountSettingTab[]
-const parseAsAccountSettingAction = parseAsStringLiteral([ACCOUNT_SETTING_MODAL_ACTION] as const)
-const parseAsAccountSettingTab = parseAsStringEnum<AccountSettingTab>(accountSettingTabValues)
-
 /**
  * Hook to manage account setting modal state via URL
  * @returns [state, setState] - Object with isOpen + payload (tab) and setter
@@ -70,11 +61,11 @@ const parseAsAccountSettingTab = parseAsStringEnum<AccountSettingTab>(accountSet
  * setAccountModalState({ payload: 'billing' }) // Sets ?action=showSettings&tab=billing
  * setAccountModalState(null) // Removes both params
  */
-export function useAccountSettingModal() {
+export function useAccountSettingModal<T extends string = string>() {
   const [accountState, setAccountState] = useQueryStates(
     {
-      action: parseAsAccountSettingAction,
-      tab: parseAsAccountSettingTab,
+      action: parseAsString,
+      tab: parseAsString,
     },
     {
       history: 'replace',
@@ -82,7 +73,7 @@ export function useAccountSettingModal() {
   )
 
   const setState = useCallback(
-    (state: { payload: AccountSettingTab } | null) => {
+    (state: { payload: T } | null) => {
       if (!state) {
         setAccountState({ action: null, tab: null }, { history: 'replace' })
         return
@@ -97,7 +88,7 @@ export function useAccountSettingModal() {
   )
 
   const isOpen = accountState.action === ACCOUNT_SETTING_MODAL_ACTION
-  const currentTab = isOpen ? accountState.tab : null
+  const currentTab = (isOpen ? accountState.tab : null) as T | null
 
   return [{ isOpen, payload: currentTab }, setState] as const
 }

web/package.json

@@ -23,7 +23,7 @@
     "and_qq >= 14.9"
   ],
   "engines": {
-    "node": "^22"
+    "node": ">=24"
   },
   "scripts": {
     "dev": "next dev",
@@ -31,9 +31,9 @@
     "dev:vinext": "vinext dev",
     "build": "next build",
     "build:docker": "next build && node scripts/optimize-standalone.js",
-    "build:vinext": "cross-env NODE_ENV=production vinext build",
+    "build:vinext": "vinext build",
     "start": "node ./scripts/copy-and-start.mjs",
-    "start:vinext": "cross-env NODE_ENV=production vinext start",
+    "start:vinext": "vinext start",
     "lint": "eslint --cache --concurrency=auto",
     "lint:ci": "eslint --cache --concurrency 2",
     "lint:fix": "pnpm lint --fix",
@@ -248,7 +248,7 @@
     "typescript": "5.9.3",
     "uglify-js": "3.19.3",
     "vinext": "https://pkg.pr.new/hyoban/vinext@cfae669",
-    "vite": "8.0.0-beta.16",
+    "vite": "7.3.1",
     "vite-tsconfig-paths": "6.1.1",
     "vitest": "4.0.18",
     "vitest-canvas-mock": "1.1.3"

web/pnpm-lock.yaml

@@ -375,7 +375,7 @@ importers:
     devDependencies:
       '@antfu/eslint-config':
         specifier: 7.6.1
-        version: 7.6.1(@eslint-react/eslint-plugin@2.13.0(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3))(@next/eslint-plugin-next@16.1.6)(@typescript-eslint/rule-tester@8.56.1(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3))(@typescript-eslint/typescript-estree@8.56.1(typescript@5.9.3))(@typescript-eslint/utils@8.56.1(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3))(@vue/compiler-sfc@3.5.27)(eslint-plugin-react-hooks@7.0.1(eslint@10.0.2(jiti@1.21.7)))(eslint-plugin-react-refresh@0.5.2(eslint@10.0.2(jiti@1.21.7)))(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3)(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 7.6.1(@eslint-react/eslint-plugin@2.13.0(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3))(@next/eslint-plugin-next@16.1.6)(@typescript-eslint/rule-tester@8.56.1(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3))(@typescript-eslint/typescript-estree@8.56.1(typescript@5.9.3))(@typescript-eslint/utils@8.56.1(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3))(@vue/compiler-sfc@3.5.27)(eslint-plugin-react-hooks@7.0.1(eslint@10.0.2(jiti@1.21.7)))(eslint-plugin-react-refresh@0.5.2(eslint@10.0.2(jiti@1.21.7)))(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3)(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       '@chromatic-com/storybook':
         specifier: 5.0.1
         version: 5.0.1(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))
@@ -414,7 +414,7 @@ importers:
         version: 9.5.4(@swc/helpers@0.5.18)(esbuild-wasm@0.27.2)(esbuild@0.27.2)(next@16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react@19.2.4)(typescript@5.9.3)
       '@storybook/addon-docs':
         specifier: 10.2.13
-        version: 10.2.13(@types/react@19.2.9)(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
+        version: 10.2.13(@types/react@19.2.9)(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
       '@storybook/addon-links':
         specifier: 10.2.13
         version: 10.2.13(react@19.2.4)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))
@@ -426,7 +426,7 @@ importers:
         version: 10.2.13(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))
       '@storybook/nextjs-vite':
         specifier: 10.2.13
-        version: 10.2.13(@babel/core@7.29.0)(esbuild@0.27.2)(next@16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
+        version: 10.2.13(@babel/core@7.29.0)(esbuild@0.27.2)(next@16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
       '@storybook/react':
         specifier: 10.2.13
         version: 10.2.13(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)
@@ -513,13 +513,13 @@ importers:
         version: 7.0.0-dev.20251209.1
       '@vitejs/plugin-react':
         specifier: 5.1.4
-        version: 5.1.4(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 5.1.4(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       '@vitejs/plugin-rsc':
         specifier: 0.5.21
-        version: 0.5.21(react-dom@19.2.4(react@19.2.4))(react-server-dom-webpack@19.2.4(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3)))(react@19.2.4)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 0.5.21(react-dom@19.2.4(react@19.2.4))(react-server-dom-webpack@19.2.4(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3)))(react@19.2.4)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       '@vitest/coverage-v8':
         specifier: 4.0.18
-        version: 4.0.18(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 4.0.18(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       autoprefixer:
         specifier: 10.4.21
         version: 10.4.21(postcss@8.5.6)
@@ -609,19 +609,19 @@ importers:
         version: 3.19.3
       vinext:
         specifier: https://pkg.pr.new/hyoban/vinext@cfae669
-        version: https://pkg.pr.new/hyoban/vinext@cfae669(next@16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
+        version: https://pkg.pr.new/hyoban/vinext@cfae669(next@16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
       vite:
-        specifier: 8.0.0-beta.16
-        version: 8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+        specifier: 7.3.1
+        version: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
       vite-tsconfig-paths:
         specifier: 6.1.1
-        version: 6.1.1(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 6.1.1(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       vitest:
         specifier: 4.0.18
-        version: 4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+        version: 4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
       vitest-canvas-mock:
         specifier: 1.1.3
-        version: 1.1.3(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+        version: 1.1.3(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
 
 packages:
 
@@ -2002,13 +2002,6 @@ packages:
     resolution: {integrity: sha512-XRO0zi2NIUKq2lUk3T1ecFSld1fMWRKE6naRFGkgkdeosx7IslyUKNv5Dcb5PJTja9tHJoFu0v/7yEpAkrkrTg==}
     engines: {node: ^20.19.0 || ^22.13.0 || >=24}
 
-  '@oxc-project/runtime@0.115.0':
-    resolution: {integrity: sha512-Rg8Wlt5dCbXhQnsXPrkOjL1DTSvXLgb2R/KYfnf1/K+R0k6UMLEmbQXPM+kwrWqSmWA2t0B1EtHy2/3zikQpvQ==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-
-  '@oxc-project/types@0.115.0':
-    resolution: {integrity: sha512-4n91DKnebUS4yjUHl2g3/b2T+IUdCfmoZGhmwsovZCDaJSs+QkVAM+0AqqTxHSsHfeiMuueT75cZaZcT/m0pSw==}
-
   '@oxc-resolver/binding-android-arm-eabi@11.16.4':
     resolution: {integrity: sha512-6XUHilmj8D6Ggus+sTBp64x/DUQ7LgC/dvTDdUOt4iMQnDdSep6N1mnvVLIiG+qM5tRnNHravNzBJnUlYwRQoA==}
     cpu: [arm]
@@ -2486,92 +2479,12 @@ packages:
     resolution: {integrity: sha512-UuBOt7BOsKVOkFXRe4Ypd/lADuNIfqJXv8GvHqtXaTYXPPKkj2nS2zPllVsrtRjcomDhIJVBnZwfmlI222WH8g==}
     engines: {node: '>=14.0.0'}
 
-  '@rolldown/binding-android-arm64@1.0.0-rc.6':
-    resolution: {integrity: sha512-kvjTSWGcrv+BaR2vge57rsKiYdVR8V8CoS0vgKrc570qRBfty4bT+1X0z3j2TaVV+kAYzA0PjeB9+mdZyqUZlg==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-    cpu: [arm64]
-    os: [android]
-
-  '@rolldown/binding-darwin-arm64@1.0.0-rc.6':
-    resolution: {integrity: sha512-+tJhD21KvGNtUrpLXrZQlT+j5HZKiEwR2qtcZb3vNOUpvoT9QjEykr75ZW/Kr0W89gose/HVXU6351uVZD8Qvw==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-    cpu: [arm64]
-    os: [darwin]
-
-  '@rolldown/binding-darwin-x64@1.0.0-rc.6':
-    resolution: {integrity: sha512-DKNhjMk38FAWaHwUt1dFR3rA/qRAvn2NUvSG2UGvxvlMxSmN/qqww/j4ABAbXhNRXtGQNmrAINMXRuwHl16ZHg==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-    cpu: [x64]
-    os: [darwin]
-
-  '@rolldown/binding-freebsd-x64@1.0.0-rc.6':
-    resolution: {integrity: sha512-8TThsRkCPAnfyMBShxrGdtoOE6h36QepqRQI97iFaQSCRbHFWHcDHppcojZnzXoruuhPnjMEygzaykvPVJsMRg==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-    cpu: [x64]
-    os: [freebsd]
-
-  '@rolldown/binding-linux-arm-gnueabihf@1.0.0-rc.6':
-    resolution: {integrity: sha512-ZfmFoOwPUZCWtGOVC9/qbQzfc0249FrRUOzV2XabSMUV60Crp211OWLQN1zmQAsRIVWRcEwhJ46Z1mXGo/L/nQ==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-    cpu: [arm]
-    os: [linux]
-
-  '@rolldown/binding-linux-arm64-gnu@1.0.0-rc.6':
-    resolution: {integrity: sha512-ZsGzbNETxPodGlLTYHaCSGVhNN/rvkMDCJYHdT7PZr5jFJRmBfmDi2awhF64Dt2vxrJqY6VeeYSgOzEbHRsb7Q==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-    cpu: [arm64]
-    os: [linux]
-
-  '@rolldown/binding-linux-arm64-musl@1.0.0-rc.6':
-    resolution: {integrity: sha512-elPpdevtCdUOqziemR86C4CSCr/5sUxalzDrf/CJdMT+kZt2C556as++qHikNOz0vuFf52h+GJNXZM08eWgGPQ==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-    cpu: [arm64]
-    os: [linux]
-
-  '@rolldown/binding-linux-x64-gnu@1.0.0-rc.6':
-    resolution: {integrity: sha512-IBwXsf56o3xhzAyaZxdM1CX8UFiBEUFCjiVUgny67Q8vPIqkjzJj0YKhd3TbBHanuxThgBa59f6Pgutg2OGk5A==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-    cpu: [x64]
-    os: [linux]
-
-  '@rolldown/binding-linux-x64-musl@1.0.0-rc.6':
-    resolution: {integrity: sha512-vOk7G8V9Zm+8a6PL6JTpCea61q491oYlGtO6CvnsbhNLlKdf0bbCPytFzGQhYmCKZDKkEbmnkcIprTEGCURnwg==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-    cpu: [x64]
-    os: [linux]
-
-  '@rolldown/binding-openharmony-arm64@1.0.0-rc.6':
-    resolution: {integrity: sha512-ASjEDI4MRv7XCQb2JVaBzfEYO98JKCGrAgoW6M03fJzH/ilCnC43Mb3ptB9q/lzsaahoJyIBoAGKAYEjUvpyvQ==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-    cpu: [arm64]
-    os: [openharmony]
-
-  '@rolldown/binding-wasm32-wasi@1.0.0-rc.6':
-    resolution: {integrity: sha512-mYa1+h2l6Zc0LvmwUh0oXKKYihnw/1WC73vTqw+IgtfEtv47A+rWzzcWwVDkW73+UDr0d/Ie/HRXoaOY22pQDw==}
-    engines: {node: '>=14.0.0'}
-    cpu: [wasm32]
-
-  '@rolldown/binding-win32-arm64-msvc@1.0.0-rc.6':
-    resolution: {integrity: sha512-e2ABskbNH3MRUBMjgxaMjYIw11DSwjLJxBII3UgpF6WClGLIh8A20kamc+FKH5vIaFVnYQInmcLYSUVpqMPLow==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-    cpu: [arm64]
-    os: [win32]
-
-  '@rolldown/binding-win32-x64-msvc@1.0.0-rc.6':
-    resolution: {integrity: sha512-dJVc3ifhaRXxIEh1xowLohzFrlQXkJ66LepHm+CmSprTWgVrPa8Fx3OL57xwIqDEH9hufcKkDX2v65rS3NZyRA==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-    cpu: [x64]
-    os: [win32]
-
   '@rolldown/pluginutils@1.0.0-rc.3':
     resolution: {integrity: sha512-eybk3TjzzzV97Dlj5c+XrBFW57eTNhzod66y9HrBlzJ6NsCrWCp/2kaPS3K9wJmurBC0Tdw4yPjXKZqlznim3Q==}
 
   '@rolldown/pluginutils@1.0.0-rc.5':
     resolution: {integrity: sha512-RxlLX/DPoarZ9PtxVrQgZhPoor987YtKQqCo5zkjX+0S0yLJ7Vv515Wk6+xtTL67VONKJKxETWZwuZjss2idYw==}
 
-  '@rolldown/pluginutils@1.0.0-rc.6':
-    resolution: {integrity: sha512-Y0+JT8Mi1mmW08K6HieG315XNRu4L0rkfCpA364HtytjgiqYnMYRdFPcxRl+BQQqNXzecL2S9nii+RUpO93XIA==}
-
   '@rollup/plugin-replace@6.0.3':
     resolution: {integrity: sha512-J4RZarRvQAm5IF0/LwUUg+obsm+xZhYnbMXmXROyoSE1ATJe3oXSb9L5MMppdxP2ylNSjv6zFBwKYjcKMucVfA==}
     engines: {node: '>=14.0.0'}
@@ -5807,76 +5720,6 @@ packages:
     engines: {node: '>=16'}
     hasBin: true
 
-  lightningcss-android-arm64@1.31.1:
-    resolution: {integrity: sha512-HXJF3x8w9nQ4jbXRiNppBCqeZPIAfUo8zE/kOEGbW5NZvGc/K7nMxbhIr+YlFlHW5mpbg/YFPdbnCh1wAXCKFg==}
-    engines: {node: '>= 12.0.0'}
-    cpu: [arm64]
-    os: [android]
-
-  lightningcss-darwin-arm64@1.31.1:
-    resolution: {integrity: sha512-02uTEqf3vIfNMq3h/z2cJfcOXnQ0GRwQrkmPafhueLb2h7mqEidiCzkE4gBMEH65abHRiQvhdcQ+aP0D0g67sg==}
-    engines: {node: '>= 12.0.0'}
-    cpu: [arm64]
-    os: [darwin]
-
-  lightningcss-darwin-x64@1.31.1:
-    resolution: {integrity: sha512-1ObhyoCY+tGxtsz1lSx5NXCj3nirk0Y0kB/g8B8DT+sSx4G9djitg9ejFnjb3gJNWo7qXH4DIy2SUHvpoFwfTA==}
-    engines: {node: '>= 12.0.0'}
-    cpu: [x64]
-    os: [darwin]
-
-  lightningcss-freebsd-x64@1.31.1:
-    resolution: {integrity: sha512-1RINmQKAItO6ISxYgPwszQE1BrsVU5aB45ho6O42mu96UiZBxEXsuQ7cJW4zs4CEodPUioj/QrXW1r9pLUM74A==}
-    engines: {node: '>= 12.0.0'}
-    cpu: [x64]
-    os: [freebsd]
-
-  lightningcss-linux-arm-gnueabihf@1.31.1:
-    resolution: {integrity: sha512-OOCm2//MZJ87CdDK62rZIu+aw9gBv4azMJuA8/KB74wmfS3lnC4yoPHm0uXZ/dvNNHmnZnB8XLAZzObeG0nS1g==}
-    engines: {node: '>= 12.0.0'}
-    cpu: [arm]
-    os: [linux]
-
-  lightningcss-linux-arm64-gnu@1.31.1:
-    resolution: {integrity: sha512-WKyLWztD71rTnou4xAD5kQT+982wvca7E6QoLpoawZ1gP9JM0GJj4Tp5jMUh9B3AitHbRZ2/H3W5xQmdEOUlLg==}
-    engines: {node: '>= 12.0.0'}
-    cpu: [arm64]
-    os: [linux]
-
-  lightningcss-linux-arm64-musl@1.31.1:
-    resolution: {integrity: sha512-mVZ7Pg2zIbe3XlNbZJdjs86YViQFoJSpc41CbVmKBPiGmC4YrfeOyz65ms2qpAobVd7WQsbW4PdsSJEMymyIMg==}
-    engines: {node: '>= 12.0.0'}
-    cpu: [arm64]
-    os: [linux]
-
-  lightningcss-linux-x64-gnu@1.31.1:
-    resolution: {integrity: sha512-xGlFWRMl+0KvUhgySdIaReQdB4FNudfUTARn7q0hh/V67PVGCs3ADFjw+6++kG1RNd0zdGRlEKa+T13/tQjPMA==}
-    engines: {node: '>= 12.0.0'}
-    cpu: [x64]
-    os: [linux]
-
-  lightningcss-linux-x64-musl@1.31.1:
-    resolution: {integrity: sha512-eowF8PrKHw9LpoZii5tdZwnBcYDxRw2rRCyvAXLi34iyeYfqCQNA9rmUM0ce62NlPhCvof1+9ivRaTY6pSKDaA==}
-    engines: {node: '>= 12.0.0'}
-    cpu: [x64]
-    os: [linux]
-
-  lightningcss-win32-arm64-msvc@1.31.1:
-    resolution: {integrity: sha512-aJReEbSEQzx1uBlQizAOBSjcmr9dCdL3XuC/6HLXAxmtErsj2ICo5yYggg1qOODQMtnjNQv2UHb9NpOuFtYe4w==}
-    engines: {node: '>= 12.0.0'}
-    cpu: [arm64]
-    os: [win32]
-
-  lightningcss-win32-x64-msvc@1.31.1:
-    resolution: {integrity: sha512-I9aiFrbd7oYHwlnQDqr1Roz+fTz61oDDJX7n9tYF9FJymH1cIN1DtKw3iYt6b8WZgEjoNwVSncwF4wx/ZedMhw==}
-    engines: {node: '>= 12.0.0'}
-    cpu: [x64]
-    os: [win32]
-
-  lightningcss@1.31.1:
-    resolution: {integrity: sha512-l51N2r93WmGUye3WuFoN5k10zyvrVs0qfKBhyC5ogUQ6Ew6JUSswh78mbSO+IU3nTWsyOArqPCcShdQSadghBQ==}
-    engines: {node: '>= 12.0.0'}
-
   lilconfig@3.1.3:
     resolution: {integrity: sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==}
     engines: {node: '>=14'}
@@ -7029,11 +6872,6 @@ packages:
   robust-predicates@3.0.2:
     resolution: {integrity: sha512-IXgzBWvWQwE6PrDI05OvmXUIruQTcoMDzRsOd5CDvHCVLcLHMTSYvOK5Cm46kWqlV3yAbuSpBZdJ5oP5OUoStg==}
 
-  rolldown@1.0.0-rc.6:
-    resolution: {integrity: sha512-B8vFPV1ADyegoYfhg+E7RAucYKv0xdVlwYYsIJgfPNeiSxZGWNxts9RqhyGzC11ULK/VaeXyKezGCwpMiH8Ktw==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-    hasBin: true
-
   rollup@4.56.0:
     resolution: {integrity: sha512-9FwVqlgUHzbXtDg9RCMgodF3Ua4Na6Gau+Sdt9vyCN4RhHfVKX2DCHy3BjMLTDd47ITDhYAnTwGulWTblJSDLg==}
     engines: {node: '>=18.0.0', npm: '>=8.0.0'}
@@ -7803,49 +7641,6 @@ packages:
       yaml:
         optional: true
 
-  vite@8.0.0-beta.16:
-    resolution: {integrity: sha512-c0t7hYkxsjws89HH+BUFh/sL3BpPNhNsL9CJrTpMxBmwKQBRSa5OJ5w4o9O0bQVI/H/vx7UpUUIevvXa37NS/Q==}
-    engines: {node: ^20.19.0 || >=22.12.0}
-    hasBin: true
-    peerDependencies:
-      '@types/node': ^20.19.0 || >=22.12.0
-      '@vitejs/devtools': ^0.0.0-alpha.31
-      esbuild: 0.27.2
-      jiti: '>=1.21.0'
-      less: ^4.0.0
-      sass: ^1.70.0
-      sass-embedded: ^1.70.0
-      stylus: '>=0.54.8'
-      sugarss: ^5.0.0
-      terser: ^5.16.0
-      tsx: ^4.8.1
-      yaml: ^2.4.2
-    peerDependenciesMeta:
-      '@types/node':
-        optional: true
-      '@vitejs/devtools':
-        optional: true
-      esbuild:
-        optional: true
-      jiti:
-        optional: true
-      less:
-        optional: true
-      sass:
-        optional: true
-      sass-embedded:
-        optional: true
-      stylus:
-        optional: true
-      sugarss:
-        optional: true
-      terser:
-        optional: true
-      tsx:
-        optional: true
-      yaml:
-        optional: true
-
   vitefu@1.1.2:
     resolution: {integrity: sha512-zpKATdUbzbsycPFBN71nS2uzBUQiVnFoOrr2rvqv34S1lcAgMKKkjWleLGeiJlZ8lwCXvtWaRn7R3ZC16SYRuw==}
     peerDependencies:
@@ -8292,7 +8087,7 @@ snapshots:
       idb: 8.0.3
       tslib: 2.8.1
 
-  '@antfu/eslint-config@7.6.1(@eslint-react/eslint-plugin@2.13.0(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3))(@next/eslint-plugin-next@16.1.6)(@typescript-eslint/rule-tester@8.56.1(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3))(@typescript-eslint/typescript-estree@8.56.1(typescript@5.9.3))(@typescript-eslint/utils@8.56.1(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3))(@vue/compiler-sfc@3.5.27)(eslint-plugin-react-hooks@7.0.1(eslint@10.0.2(jiti@1.21.7)))(eslint-plugin-react-refresh@0.5.2(eslint@10.0.2(jiti@1.21.7)))(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3)(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@antfu/eslint-config@7.6.1(@eslint-react/eslint-plugin@2.13.0(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3))(@next/eslint-plugin-next@16.1.6)(@typescript-eslint/rule-tester@8.56.1(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3))(@typescript-eslint/typescript-estree@8.56.1(typescript@5.9.3))(@typescript-eslint/utils@8.56.1(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3))(@vue/compiler-sfc@3.5.27)(eslint-plugin-react-hooks@7.0.1(eslint@10.0.2(jiti@1.21.7)))(eslint-plugin-react-refresh@0.5.2(eslint@10.0.2(jiti@1.21.7)))(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3)(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@antfu/install-pkg': 1.1.0
       '@clack/prompts': 1.0.1
@@ -8301,7 +8096,7 @@ snapshots:
       '@stylistic/eslint-plugin': https://pkg.pr.new/@stylistic/eslint-plugin@258f9d8(eslint@10.0.2(jiti@1.21.7))
       '@typescript-eslint/eslint-plugin': 8.56.1(@typescript-eslint/parser@8.56.1(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3))(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3)
       '@typescript-eslint/parser': 8.56.1(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3)
-      '@vitest/eslint-plugin': 1.6.9(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3)(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+      '@vitest/eslint-plugin': 1.6.9(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3)(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       ansis: 4.2.0
       cac: 6.7.14
       eslint: 10.0.2(jiti@1.21.7)
@@ -9293,11 +9088,11 @@ snapshots:
     dependencies:
       minipass: 7.1.3
 
-  '@joshwooding/vite-plugin-react-docgen-typescript@0.6.4(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@joshwooding/vite-plugin-react-docgen-typescript@0.6.4(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       glob: 13.0.6
       react-docgen-typescript: 2.4.0(typescript@5.9.3)
-      vite: 8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
     optionalDependencies:
       typescript: 5.9.3
 
@@ -9788,10 +9583,6 @@ snapshots:
 
   '@ota-meshi/ast-token-store@0.3.0': {}
 
-  '@oxc-project/runtime@0.115.0': {}
-
-  '@oxc-project/types@0.115.0': {}
-
   '@oxc-resolver/binding-android-arm-eabi@11.16.4':
     optional: true
 
@@ -10221,53 +10012,10 @@ snapshots:
 
   '@rgrove/parse-xml@4.2.0': {}
 
-  '@rolldown/binding-android-arm64@1.0.0-rc.6':
-    optional: true
-
-  '@rolldown/binding-darwin-arm64@1.0.0-rc.6':
-    optional: true
-
-  '@rolldown/binding-darwin-x64@1.0.0-rc.6':
-    optional: true
-
-  '@rolldown/binding-freebsd-x64@1.0.0-rc.6':
-    optional: true
-
-  '@rolldown/binding-linux-arm-gnueabihf@1.0.0-rc.6':
-    optional: true
-
-  '@rolldown/binding-linux-arm64-gnu@1.0.0-rc.6':
-    optional: true
-
-  '@rolldown/binding-linux-arm64-musl@1.0.0-rc.6':
-    optional: true
-
-  '@rolldown/binding-linux-x64-gnu@1.0.0-rc.6':
-    optional: true
-
-  '@rolldown/binding-linux-x64-musl@1.0.0-rc.6':
-    optional: true
-
-  '@rolldown/binding-openharmony-arm64@1.0.0-rc.6':
-    optional: true
-
-  '@rolldown/binding-wasm32-wasi@1.0.0-rc.6':
-    dependencies:
-      '@napi-rs/wasm-runtime': 1.1.1
-    optional: true
-
-  '@rolldown/binding-win32-arm64-msvc@1.0.0-rc.6':
-    optional: true
-
-  '@rolldown/binding-win32-x64-msvc@1.0.0-rc.6':
-    optional: true
-
   '@rolldown/pluginutils@1.0.0-rc.3': {}
 
   '@rolldown/pluginutils@1.0.0-rc.5': {}
 
-  '@rolldown/pluginutils@1.0.0-rc.6': {}
-
   '@rollup/plugin-replace@6.0.3(rollup@4.56.0)':
     dependencies:
       '@rollup/pluginutils': 5.3.0(rollup@4.56.0)
@@ -10484,10 +10232,10 @@ snapshots:
 
   '@standard-schema/spec@1.1.0': {}
 
-  '@storybook/addon-docs@10.2.13(@types/react@19.2.9)(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))':
+  '@storybook/addon-docs@10.2.13(@types/react@19.2.9)(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))':
     dependencies:
       '@mdx-js/react': 3.1.1(@types/react@19.2.9)(react@19.2.4)
-      '@storybook/csf-plugin': 10.2.13(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
+      '@storybook/csf-plugin': 10.2.13(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
       '@storybook/icons': 2.0.1(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@storybook/react-dom-shim': 10.2.13(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))
       react: 19.2.4
@@ -10517,25 +10265,25 @@ snapshots:
       storybook: 10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       ts-dedent: 2.2.0
 
-  '@storybook/builder-vite@10.2.13(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))':
+  '@storybook/builder-vite@10.2.13(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))':
     dependencies:
-      '@storybook/csf-plugin': 10.2.13(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
+      '@storybook/csf-plugin': 10.2.13(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
       storybook: 10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       ts-dedent: 2.2.0
-      vite: 8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - esbuild
       - rollup
       - webpack
 
-  '@storybook/csf-plugin@10.2.13(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))':
+  '@storybook/csf-plugin@10.2.13(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))':
     dependencies:
       storybook: 10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       unplugin: 2.3.11
     optionalDependencies:
       esbuild: 0.27.2
       rollup: 4.56.0
-      vite: 8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
       webpack: 5.104.1(esbuild@0.27.2)(uglify-js@3.19.3)
 
   '@storybook/global@5.0.0': {}
@@ -10545,18 +10293,18 @@ snapshots:
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
 
-  '@storybook/nextjs-vite@10.2.13(@babel/core@7.29.0)(esbuild@0.27.2)(next@16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))':
+  '@storybook/nextjs-vite@10.2.13(@babel/core@7.29.0)(esbuild@0.27.2)(next@16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))':
     dependencies:
-      '@storybook/builder-vite': 10.2.13(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
+      '@storybook/builder-vite': 10.2.13(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
       '@storybook/react': 10.2.13(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)
-      '@storybook/react-vite': 10.2.13(esbuild@0.27.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
+      '@storybook/react-vite': 10.2.13(esbuild@0.27.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
       next: 16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2)
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
       storybook: 10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       styled-jsx: 5.1.6(@babel/core@7.29.0)(react@19.2.4)
-      vite: 8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
-      vite-plugin-storybook-nextjs: 3.2.2(next@16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite-plugin-storybook-nextjs: 3.2.2(next@16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
     optionalDependencies:
       typescript: 5.9.3
     transitivePeerDependencies:
@@ -10573,11 +10321,11 @@ snapshots:
       react-dom: 19.2.4(react@19.2.4)
       storybook: 10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
 
-  '@storybook/react-vite@10.2.13(esbuild@0.27.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))':
+  '@storybook/react-vite@10.2.13(esbuild@0.27.2)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))':
     dependencies:
-      '@joshwooding/vite-plugin-react-docgen-typescript': 0.6.4(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+      '@joshwooding/vite-plugin-react-docgen-typescript': 0.6.4(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       '@rollup/pluginutils': 5.3.0(rollup@4.56.0)
-      '@storybook/builder-vite': 10.2.13(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
+      '@storybook/builder-vite': 10.2.13(esbuild@0.27.2)(rollup@4.56.0)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
       '@storybook/react': 10.2.13(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)
       empathic: 2.0.0
       magic-string: 0.30.21
@@ -10587,7 +10335,7 @@ snapshots:
       resolve: 1.22.11
       storybook: 10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       tsconfig-paths: 4.2.0
-      vite: 8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - esbuild
       - rollup
@@ -11423,7 +11171,7 @@ snapshots:
       '@resvg/resvg-wasm': 2.4.0
       satori: 0.16.0
 
-  '@vitejs/plugin-react@5.1.4(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@vitejs/plugin-react@5.1.4(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@babel/core': 7.29.0
       '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.29.0)
@@ -11431,11 +11179,11 @@ snapshots:
       '@rolldown/pluginutils': 1.0.0-rc.3
       '@types/babel__core': 7.20.5
       react-refresh: 0.18.0
-      vite: 8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - supports-color
 
-  '@vitejs/plugin-rsc@0.5.21(react-dom@19.2.4(react@19.2.4))(react-server-dom-webpack@19.2.4(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3)))(react@19.2.4)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@vitejs/plugin-rsc@0.5.21(react-dom@19.2.4(react@19.2.4))(react-server-dom-webpack@19.2.4(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3)))(react@19.2.4)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@rolldown/pluginutils': 1.0.0-rc.5
       es-module-lexer: 2.0.0
@@ -11447,12 +11195,12 @@ snapshots:
       srvx: 0.11.7
       strip-literal: 3.1.0
       turbo-stream: 3.1.0
-      vite: 8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
-      vitefu: 1.1.2(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vitefu: 1.1.2(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
     optionalDependencies:
       react-server-dom-webpack: 19.2.4(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
 
-  '@vitest/coverage-v8@4.0.18(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@vitest/coverage-v8@4.0.18(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@bcoe/v8-coverage': 1.0.2
       '@vitest/utils': 4.0.18
@@ -11464,16 +11212,16 @@ snapshots:
       obug: 2.1.1
       std-env: 3.10.0
       tinyrainbow: 3.0.3
-      vitest: 4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vitest: 4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
 
-  '@vitest/eslint-plugin@1.6.9(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3)(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@vitest/eslint-plugin@1.6.9(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3)(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@typescript-eslint/scope-manager': 8.56.1
       '@typescript-eslint/utils': 8.56.1(eslint@10.0.2(jiti@1.21.7))(typescript@5.9.3)
       eslint: 10.0.2(jiti@1.21.7)
     optionalDependencies:
       typescript: 5.9.3
-      vitest: 4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vitest: 4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - supports-color
 
@@ -11494,13 +11242,13 @@ snapshots:
       chai: 6.2.2
       tinyrainbow: 3.0.3
 
-  '@vitest/mocker@4.0.18(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
+  '@vitest/mocker@4.0.18(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))':
     dependencies:
       '@vitest/spy': 4.0.18
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
 
   '@vitest/pretty-format@3.2.4':
     dependencies:
@@ -13887,55 +13635,6 @@ snapshots:
     dependencies:
       isomorphic.js: 0.2.5
 
-  lightningcss-android-arm64@1.31.1:
-    optional: true
-
-  lightningcss-darwin-arm64@1.31.1:
-    optional: true
-
-  lightningcss-darwin-x64@1.31.1:
-    optional: true
-
-  lightningcss-freebsd-x64@1.31.1:
-    optional: true
-
-  lightningcss-linux-arm-gnueabihf@1.31.1:
-    optional: true
-
-  lightningcss-linux-arm64-gnu@1.31.1:
-    optional: true
-
-  lightningcss-linux-arm64-musl@1.31.1:
-    optional: true
-
-  lightningcss-linux-x64-gnu@1.31.1:
-    optional: true
-
-  lightningcss-linux-x64-musl@1.31.1:
-    optional: true
-
-  lightningcss-win32-arm64-msvc@1.31.1:
-    optional: true
-
-  lightningcss-win32-x64-msvc@1.31.1:
-    optional: true
-
-  lightningcss@1.31.1:
-    dependencies:
-      detect-libc: 2.1.2
-    optionalDependencies:
-      lightningcss-android-arm64: 1.31.1
-      lightningcss-darwin-arm64: 1.31.1
-      lightningcss-darwin-x64: 1.31.1
-      lightningcss-freebsd-x64: 1.31.1
-      lightningcss-linux-arm-gnueabihf: 1.31.1
-      lightningcss-linux-arm64-gnu: 1.31.1
-      lightningcss-linux-arm64-musl: 1.31.1
-      lightningcss-linux-x64-gnu: 1.31.1
-      lightningcss-linux-x64-musl: 1.31.1
-      lightningcss-win32-arm64-msvc: 1.31.1
-      lightningcss-win32-x64-msvc: 1.31.1
-
   lilconfig@3.1.3: {}
 
   linebreak@1.1.0:
@@ -15506,25 +15205,6 @@ snapshots:
 
   robust-predicates@3.0.2: {}
 
-  rolldown@1.0.0-rc.6:
-    dependencies:
-      '@oxc-project/types': 0.115.0
-      '@rolldown/pluginutils': 1.0.0-rc.6
-    optionalDependencies:
-      '@rolldown/binding-android-arm64': 1.0.0-rc.6
-      '@rolldown/binding-darwin-arm64': 1.0.0-rc.6
-      '@rolldown/binding-darwin-x64': 1.0.0-rc.6
-      '@rolldown/binding-freebsd-x64': 1.0.0-rc.6
-      '@rolldown/binding-linux-arm-gnueabihf': 1.0.0-rc.6
-      '@rolldown/binding-linux-arm64-gnu': 1.0.0-rc.6
-      '@rolldown/binding-linux-arm64-musl': 1.0.0-rc.6
-      '@rolldown/binding-linux-x64-gnu': 1.0.0-rc.6
-      '@rolldown/binding-linux-x64-musl': 1.0.0-rc.6
-      '@rolldown/binding-openharmony-arm64': 1.0.0-rc.6
-      '@rolldown/binding-wasm32-wasi': 1.0.0-rc.6
-      '@rolldown/binding-win32-arm64-msvc': 1.0.0-rc.6
-      '@rolldown/binding-win32-x64-msvc': 1.0.0-rc.6
-
   rollup@4.56.0:
     dependencies:
       '@types/estree': 1.0.8
@@ -16291,19 +15971,19 @@ snapshots:
       '@types/unist': 3.0.3
       vfile-message: 4.0.3
 
-  vinext@https://pkg.pr.new/hyoban/vinext@cfae669(next@16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3)):
+  vinext@https://pkg.pr.new/hyoban/vinext@cfae669(next@16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3)):
     dependencies:
       '@unpic/react': 1.0.2(next@16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       '@vercel/og': 0.8.6
-      '@vitejs/plugin-rsc': 0.5.21(react-dom@19.2.4(react@19.2.4))(react-server-dom-webpack@19.2.4(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3)))(react@19.2.4)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+      '@vitejs/plugin-rsc': 0.5.21(react-dom@19.2.4(react@19.2.4))(react-server-dom-webpack@19.2.4(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3)))(react@19.2.4)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       magic-string: 0.30.21
       react: 19.2.4
       react-dom: 19.2.4(react@19.2.4)
       react-server-dom-webpack: 19.2.4(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(webpack@5.104.1(esbuild@0.27.2)(uglify-js@3.19.3))
       rsc-html-stream: 0.0.7
-      vite: 8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
       vite-plugin-commonjs: 0.10.4
-      vite-tsconfig-paths: 6.1.1(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+      vite-tsconfig-paths: 6.1.1(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
     transitivePeerDependencies:
       - next
       - supports-color
@@ -16323,7 +16003,7 @@ snapshots:
       fast-glob: 3.3.3
       magic-string: 0.30.21
 
-  vite-plugin-storybook-nextjs@3.2.2(next@16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)):
+  vite-plugin-storybook-nextjs@3.2.2(next@16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2))(storybook@10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4))(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)):
     dependencies:
       '@next/env': 16.0.0
       image-size: 2.0.2
@@ -16332,34 +16012,34 @@ snapshots:
       next: 16.1.5(@babel/core@7.29.0)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)(sass@1.93.2)
       storybook: 10.2.13(@testing-library/dom@10.4.1)(react-dom@19.2.4(react@19.2.4))(react@19.2.4)
       ts-dedent: 2.2.0
-      vite: 8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
-      vite-tsconfig-paths: 5.1.4(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite-tsconfig-paths: 5.1.4(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
     transitivePeerDependencies:
       - supports-color
       - typescript
 
-  vite-tsconfig-paths@5.1.4(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)):
+  vite-tsconfig-paths@5.1.4(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)):
     dependencies:
       debug: 4.4.3
       globrex: 0.1.2
       tsconfck: 3.1.6(typescript@5.9.3)
     optionalDependencies:
-      vite: 8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - supports-color
       - typescript
 
-  vite-tsconfig-paths@6.1.1(typescript@5.9.3)(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)):
+  vite-tsconfig-paths@6.1.1(typescript@5.9.3)(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)):
     dependencies:
       debug: 4.4.3
       globrex: 0.1.2
       tsconfck: 3.1.6(typescript@5.9.3)
-      vite: 8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
     transitivePeerDependencies:
       - supports-color
       - typescript
 
-  vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2):
+  vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2):
     dependencies:
       esbuild: 0.27.2
       fdir: 6.5.0(picomatch@4.0.3)
@@ -16371,44 +16051,25 @@ snapshots:
       '@types/node': 24.10.12
       fsevents: 2.3.3
       jiti: 1.21.7
-      lightningcss: 1.31.1
       sass: 1.93.2
       terser: 5.46.0
       tsx: 4.21.0
       yaml: 2.8.2
 
-  vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2):
-    dependencies:
-      '@oxc-project/runtime': 0.115.0
-      lightningcss: 1.31.1
-      picomatch: 4.0.3
-      postcss: 8.5.6
-      rolldown: 1.0.0-rc.6
-      tinyglobby: 0.2.15
+  vitefu@1.1.2(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)):
     optionalDependencies:
-      '@types/node': 24.10.12
-      esbuild: 0.27.2
-      fsevents: 2.3.3
-      jiti: 1.21.7
-      sass: 1.93.2
-      terser: 5.46.0
-      tsx: 4.21.0
-      yaml: 2.8.2
+      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
 
-  vitefu@1.1.2(vite@8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)):
-    optionalDependencies:
-      vite: 8.0.0-beta.16(@types/node@24.10.12)(esbuild@0.27.2)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
-
-  vitest-canvas-mock@1.1.3(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)):
+  vitest-canvas-mock@1.1.3(vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)):
     dependencies:
       cssfontparser: 1.2.1
       moo-color: 1.0.3
-      vitest: 4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vitest: 4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
 
-  vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2):
+  vitest@4.0.18(@types/node@24.10.12)(jiti@1.21.7)(jsdom@27.3.0(canvas@3.2.1))(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2):
     dependencies:
       '@vitest/expect': 4.0.18
-      '@vitest/mocker': 4.0.18(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
+      '@vitest/mocker': 4.0.18(vite@7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2))
       '@vitest/pretty-format': 4.0.18
       '@vitest/runner': 4.0.18
       '@vitest/snapshot': 4.0.18
@@ -16425,7 +16086,7 @@ snapshots:
       tinyexec: 1.0.2
       tinyglobby: 0.2.15
       tinyrainbow: 3.0.3
-      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(lightningcss@1.31.1)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
+      vite: 7.3.1(@types/node@24.10.12)(jiti@1.21.7)(sass@1.93.2)(terser@5.46.0)(tsx@4.21.0)(yaml@2.8.2)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/node': 24.10.12

web/service/knowledge/use-document.ts

@@ -1,9 +1,7 @@
-import type { UseQueryOptions } from '@tanstack/react-query'
 import type { DocumentDownloadResponse, DocumentDownloadZipRequest, MetadataType, SortType } from '../datasets'
 import type { CommonResponse } from '@/models/common'
 import type { DocumentDetailResponse, DocumentListResponse, UpdateDocumentBatchParams } from '@/models/datasets'
 import {
-  keepPreviousData,
   useMutation,
   useQuery,
 } from '@tanstack/react-query'
@@ -16,8 +14,6 @@ import { useInvalid } from '../use-base'
 const NAME_SPACE = 'knowledge/document'
 
 export const useDocumentListKey = [NAME_SPACE, 'documentList']
-type DocumentListRefetchInterval = UseQueryOptions<DocumentListResponse>['refetchInterval']
-
 export const useDocumentList = (payload: {
   datasetId: string
   query: {
@@ -27,7 +23,7 @@ export const useDocumentList = (payload: {
     sort?: SortType
     status?: string
   }
-  refetchInterval?: DocumentListRefetchInterval
+  refetchInterval?: number | false
 }) => {
   const { query, datasetId, refetchInterval } = payload
   const { keyword, page, limit, sort, status } = query
@@ -46,7 +42,6 @@ export const useDocumentList = (payload: {
     queryFn: () => get<DocumentListResponse>(`/datasets/${datasetId}/documents`, {
       params,
     }),
-    placeholderData: keepPreviousData,
     refetchInterval,
   })
 }

web/test/nuqs-testing.tsx

@@ -1,60 +0,0 @@
-import type { UrlUpdateEvent } from 'nuqs/adapters/testing'
-import type { ComponentProps, ReactElement, ReactNode } from 'react'
-import type { Mock } from 'vitest'
-import { render, renderHook } from '@testing-library/react'
-import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
-import { vi } from 'vitest'
-
-type NuqsSearchParams = ComponentProps<typeof NuqsTestingAdapter>['searchParams']
-type NuqsOnUrlUpdate = (event: UrlUpdateEvent) => void
-type NuqsOnUrlUpdateSpy = Mock<NuqsOnUrlUpdate>
-
-type NuqsTestOptions = {
-  searchParams?: NuqsSearchParams
-  onUrlUpdate?: NuqsOnUrlUpdateSpy
-}
-
-type NuqsHookTestOptions<Props> = NuqsTestOptions & {
-  initialProps?: Props
-}
-
-type NuqsWrapperProps = {
-  children: ReactNode
-}
-
-export const createNuqsTestWrapper = (options: NuqsTestOptions = {}) => {
-  const { searchParams = '', onUrlUpdate } = options
-  const urlUpdateSpy = onUrlUpdate ?? vi.fn<NuqsOnUrlUpdate>()
-  const wrapper = ({ children }: NuqsWrapperProps) => (
-    <NuqsTestingAdapter searchParams={searchParams} onUrlUpdate={urlUpdateSpy}>
-      {children}
-    </NuqsTestingAdapter>
-  )
-
-  return {
-    wrapper,
-    onUrlUpdate: urlUpdateSpy,
-  }
-}
-
-export const renderWithNuqs = (ui: ReactElement, options: NuqsTestOptions = {}) => {
-  const { wrapper, onUrlUpdate } = createNuqsTestWrapper(options)
-  const rendered = render(ui, { wrapper })
-  return {
-    ...rendered,
-    onUrlUpdate,
-  }
-}
-
-export const renderHookWithNuqs = <Result, Props = void>(
-  callback: (props: Props) => Result,
-  options: NuqsHookTestOptions<Props> = {},
-) => {
-  const { initialProps, ...nuqsOptions } = options
-  const { wrapper, onUrlUpdate } = createNuqsTestWrapper(nuqsOptions)
-  const rendered = renderHook(callback, { wrapper, initialProps })
-  return {
-    ...rendered,
-    onUrlUpdate,
-  }
-}

web/vite.config.ts

@@ -108,30 +108,10 @@ export default defineConfig(({ mode }) => {
       ? {
           optimizeDeps: {
             exclude: ['nuqs'],
-            // Make Prism in lexical works
-            // https://github.com/vitejs/rolldown-vite/issues/396
-            rolldownOptions: {
-              output: {
-                strictExecutionOrder: true,
-              },
-            },
           },
           server: {
             port: 3000,
           },
-          ssr: {
-            // SyntaxError: Named export not found. The requested module is a CommonJS module, which may not support all module.exports as named exports
-            noExternal: ['emoji-mart'],
-          },
-          // Make Prism in lexical works
-          // https://github.com/vitejs/rolldown-vite/issues/396
-          build: {
-            rolldownOptions: {
-              output: {
-                strictExecutionOrder: true,
-              },
-            },
-          },
         }
       : {}),