Merge branch 'main' into refactor/documents

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

api/core/agent/fc_agent_runner.py

@@ -188,7 +188,7 @@ class FunctionCallAgentRunner(BaseAgentRunner):
                     ),
                 )
 
-            assistant_message = AssistantPromptMessage(content="", tool_calls=[])
+            assistant_message = AssistantPromptMessage(content=response, tool_calls=[])
             if tool_calls:
                 assistant_message.tool_calls = [
                     AssistantPromptMessage.ToolCall(
@@ -200,8 +200,6 @@ class FunctionCallAgentRunner(BaseAgentRunner):
                     )
                     for tool_call in tool_calls
                 ]
-            else:
-                assistant_message.content = response
 
             self._current_thoughts.append(assistant_message)
 

api/core/model_runtime/entities/message_entities.py

@@ -251,10 +251,7 @@ class AssistantPromptMessage(PromptMessage):
 
         :return: True if prompt message is empty, False otherwise
         """
-        if not super().is_empty() and not self.tool_calls:
-            return False
-
-        return True
+        return super().is_empty() and not self.tool_calls
 
 
 class SystemPromptMessage(PromptMessage):

api/core/ops/aliyun_trace/aliyun_trace.py

@@ -1,6 +1,7 @@
 import logging
 from collections.abc import Sequence
 
+from opentelemetry.trace import SpanKind
 from sqlalchemy.orm import sessionmaker
 
 from core.ops.aliyun_trace.data_exporter.traceclient import (
@@ -151,6 +152,7 @@ class AliyunDataTrace(BaseTraceInstance):
             ),
             status=status,
             links=trace_metadata.links,
+            span_kind=SpanKind.SERVER,
         )
         self.trace_client.add_span(message_span)
 
@@ -456,6 +458,7 @@ class AliyunDataTrace(BaseTraceInstance):
                 ),
                 status=status,
                 links=trace_metadata.links,
+                span_kind=SpanKind.SERVER,
             )
             self.trace_client.add_span(message_span)
 
@@ -475,6 +478,7 @@ class AliyunDataTrace(BaseTraceInstance):
             ),
             status=status,
             links=trace_metadata.links,
+            span_kind=SpanKind.SERVER if message_span_id is None else SpanKind.INTERNAL,
         )
         self.trace_client.add_span(workflow_span)
 

api/core/ops/aliyun_trace/data_exporter/traceclient.py

@@ -166,7 +166,7 @@ class SpanBuilder:
             attributes=span_data.attributes,
             events=span_data.events,
             links=span_data.links,
-            kind=trace_api.SpanKind.INTERNAL,
+            kind=span_data.span_kind,
             status=span_data.status,
             start_time=span_data.start_time,
             end_time=span_data.end_time,

api/core/ops/aliyun_trace/entities/aliyun_trace_entity.py

@@ -4,7 +4,7 @@ from typing import Any
 
 from opentelemetry import trace as trace_api
 from opentelemetry.sdk.trace import Event
-from opentelemetry.trace import Status, StatusCode
+from opentelemetry.trace import SpanKind, Status, StatusCode
 from pydantic import BaseModel, Field
 
 
@@ -34,3 +34,4 @@ class SpanData(BaseModel):
     status: Status = Field(default=Status(StatusCode.UNSET), description="The status of the span.")
     start_time: int | None = Field(..., description="The start time of the span in nanoseconds.")
     end_time: int | None = Field(..., description="The end time of the span in nanoseconds.")
+    span_kind: SpanKind = Field(default=SpanKind.INTERNAL, description="The OpenTelemetry SpanKind for this span.")

api/core/workflow/workflow_entry.py

@@ -19,6 +19,7 @@ from core.workflow.graph_engine.protocols.command_channel import CommandChannel
 from core.workflow.graph_events import GraphEngineEvent, GraphNodeEventBase, GraphRunFailedEvent
 from core.workflow.nodes import NodeType
 from core.workflow.nodes.base.node import Node
+from core.workflow.nodes.node_factory import DifyNodeFactory
 from core.workflow.nodes.node_mapping import NODE_TYPE_CLASSES_MAPPING
 from core.workflow.runtime import GraphRuntimeState, VariablePool
 from core.workflow.system_variable import SystemVariable
@@ -136,13 +137,11 @@ class WorkflowEntry:
         :param user_inputs: user inputs
         :return:
         """
-        node_config = workflow.get_node_config_by_id(node_id)
+        node_config = dict(workflow.get_node_config_by_id(node_id))
         node_config_data = node_config.get("data", {})
 
-        # Get node class
+        # Get node type
         node_type = NodeType(node_config_data.get("type"))
-        node_version = node_config_data.get("version", "1")
-        node_cls = NODE_TYPE_CLASSES_MAPPING[node_type][node_version]
 
         # init graph init params and runtime state
         graph_init_params = GraphInitParams(
@@ -158,12 +157,12 @@ class WorkflowEntry:
         graph_runtime_state = GraphRuntimeState(variable_pool=variable_pool, start_at=time.perf_counter())
 
         # init workflow run state
-        node = node_cls(
-            id=str(uuid.uuid4()),
-            config=node_config,
+        node_factory = DifyNodeFactory(
             graph_init_params=graph_init_params,
             graph_runtime_state=graph_runtime_state,
         )
+        node = node_factory.create_node(node_config)
+        node_cls = type(node)
 
         try:
             # variable selector to variable mapping

api/tests/unit_tests/core/workflow/test_workflow_entry.py

@@ -2,13 +2,17 @@ from types import SimpleNamespace
 
 import pytest
 
+from configs import dify_config
 from core.file.enums import FileType
 from core.file.models import File, FileTransferMethod
+from core.helper.code_executor.code_executor import CodeLanguage
 from core.variables.variables import StringVariable
 from core.workflow.constants import (
     CONVERSATION_VARIABLE_NODE_ID,
     ENVIRONMENT_VARIABLE_NODE_ID,
 )
+from core.workflow.nodes.code.code_node import CodeNode
+from core.workflow.nodes.code.limits import CodeNodeLimits
 from core.workflow.runtime import VariablePool
 from core.workflow.system_variable import SystemVariable
 from core.workflow.workflow_entry import WorkflowEntry
@@ -96,6 +100,58 @@ class TestWorkflowEntry:
         assert output_var is not None
         assert output_var.value == "system_user"
 
+    def test_single_step_run_injects_code_limits(self):
+        """Ensure single-step CodeNode execution configures limits."""
+        # Arrange
+        node_id = "code_node"
+        node_data = {
+            "type": "code",
+            "title": "Code",
+            "desc": None,
+            "variables": [],
+            "code_language": CodeLanguage.PYTHON3,
+            "code": "def main():\n    return {}",
+            "outputs": {},
+        }
+        node_config = {"id": node_id, "data": node_data}
+
+        class StubWorkflow:
+            def __init__(self):
+                self.tenant_id = "tenant"
+                self.app_id = "app"
+                self.id = "workflow"
+                self.graph_dict = {"nodes": [node_config], "edges": []}
+
+            def get_node_config_by_id(self, target_id: str):
+                assert target_id == node_id
+                return node_config
+
+        workflow = StubWorkflow()
+        variable_pool = VariablePool(system_variables=SystemVariable.empty(), user_inputs={})
+        expected_limits = CodeNodeLimits(
+            max_string_length=dify_config.CODE_MAX_STRING_LENGTH,
+            max_number=dify_config.CODE_MAX_NUMBER,
+            min_number=dify_config.CODE_MIN_NUMBER,
+            max_precision=dify_config.CODE_MAX_PRECISION,
+            max_depth=dify_config.CODE_MAX_DEPTH,
+            max_number_array_length=dify_config.CODE_MAX_NUMBER_ARRAY_LENGTH,
+            max_string_array_length=dify_config.CODE_MAX_STRING_ARRAY_LENGTH,
+            max_object_array_length=dify_config.CODE_MAX_OBJECT_ARRAY_LENGTH,
+        )
+
+        # Act
+        node, _ = WorkflowEntry.single_step_run(
+            workflow=workflow,
+            node_id=node_id,
+            user_id="user",
+            user_inputs={},
+            variable_pool=variable_pool,
+        )
+
+        # Assert
+        assert isinstance(node, CodeNode)
+        assert node._limits == expected_limits
+
     def test_mapping_user_inputs_to_variable_pool_with_env_variables(self):
         """Test mapping environment variables from user inputs to variable pool."""
         # Initialize variable pool with environment variables

web/.env.example

@@ -31,6 +31,8 @@ NEXT_PUBLIC_UPLOAD_IMAGE_AS_ICON=false
 
 # The timeout for the text generation in millisecond
 NEXT_PUBLIC_TEXT_GENERATION_TIMEOUT_MS=60000
+# Used by web/docker/entrypoint.sh to overwrite/export NEXT_PUBLIC_TEXT_GENERATION_TIMEOUT_MS at container startup (Docker only)
+TEXT_GENERATION_TIMEOUT_MS=60000
 
 # CSP https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
 NEXT_PUBLIC_CSP_WHITELIST=

web/app/components/base/amplitude/AmplitudeProvider.tsx

@@ -54,7 +54,7 @@ const pageNameEnrichmentPlugin = (): amplitude.Types.EnrichmentPlugin => {
 }
 
 const AmplitudeProvider: FC<IAmplitudeProps> = ({
-  sessionReplaySampleRate = 1,
+  sessionReplaySampleRate = 0.5,
 }) => {
   useEffect(() => {
     // Only enable in Saas edition with valid API key

web/app/components/datasets/documents/components/documents-header.tsx

@@ -0,0 +1,201 @@
+'use client'
+import type { FC } from 'react'
+import type { Item } from '@/app/components/base/select'
+import type { BuiltInMetadataItem, MetadataItemWithValueLength } from '@/app/components/datasets/metadata/types'
+import type { SortType } from '@/service/datasets'
+import { PlusIcon } from '@heroicons/react/24/solid'
+import { RiDraftLine, RiExternalLinkLine } from '@remixicon/react'
+import { useMemo } from 'react'
+import { useTranslation } from 'react-i18next'
+import Button from '@/app/components/base/button'
+import Chip from '@/app/components/base/chip'
+import Input from '@/app/components/base/input'
+import Sort from '@/app/components/base/sort'
+import AutoDisabledDocument from '@/app/components/datasets/common/document-status-with-action/auto-disabled-document'
+import IndexFailed from '@/app/components/datasets/common/document-status-with-action/index-failed'
+import StatusWithAction from '@/app/components/datasets/common/document-status-with-action/status-with-action'
+import DatasetMetadataDrawer from '@/app/components/datasets/metadata/metadata-dataset/dataset-metadata-drawer'
+import { useDocLink } from '@/context/i18n'
+import { DataSourceType } from '@/models/datasets'
+import { useIndexStatus } from '../status-item/hooks'
+
+type DocumentsHeaderProps = {
+  // Dataset info
+  datasetId: string
+  dataSourceType?: DataSourceType
+  embeddingAvailable: boolean
+  isFreePlan: boolean
+
+  // Filter & sort
+  statusFilterValue: string
+  sortValue: SortType
+  inputValue: string
+  onStatusFilterChange: (value: string) => void
+  onStatusFilterClear: () => void
+  onSortChange: (value: string) => void
+  onInputChange: (value: string) => void
+
+  // Metadata modal
+  isShowEditMetadataModal: boolean
+  showEditMetadataModal: () => void
+  hideEditMetadataModal: () => void
+  datasetMetaData?: MetadataItemWithValueLength[]
+  builtInMetaData?: BuiltInMetadataItem[]
+  builtInEnabled: boolean
+  onAddMetaData: (payload: BuiltInMetadataItem) => Promise<void>
+  onRenameMetaData: (payload: MetadataItemWithValueLength) => Promise<void>
+  onDeleteMetaData: (metaDataId: string) => Promise<void>
+  onBuiltInEnabledChange: (enabled: boolean) => void
+
+  // Actions
+  onAddDocument: () => void
+}
+
+const DocumentsHeader: FC<DocumentsHeaderProps> = ({
+  datasetId,
+  dataSourceType,
+  embeddingAvailable,
+  isFreePlan,
+  statusFilterValue,
+  sortValue,
+  inputValue,
+  onStatusFilterChange,
+  onStatusFilterClear,
+  onSortChange,
+  onInputChange,
+  isShowEditMetadataModal,
+  showEditMetadataModal,
+  hideEditMetadataModal,
+  datasetMetaData,
+  builtInMetaData,
+  builtInEnabled,
+  onAddMetaData,
+  onRenameMetaData,
+  onDeleteMetaData,
+  onBuiltInEnabledChange,
+  onAddDocument,
+}) => {
+  const { t } = useTranslation()
+  const docLink = useDocLink()
+  const DOC_INDEX_STATUS_MAP = useIndexStatus()
+
+  const isDataSourceNotion = dataSourceType === DataSourceType.NOTION
+  const isDataSourceWeb = dataSourceType === DataSourceType.WEB
+
+  const statusFilterItems: Item[] = useMemo(() => [
+    { value: 'all', name: t('list.index.all', { ns: 'datasetDocuments' }) as string },
+    { value: 'queuing', name: DOC_INDEX_STATUS_MAP.queuing.text },
+    { value: 'indexing', name: DOC_INDEX_STATUS_MAP.indexing.text },
+    { value: 'paused', name: DOC_INDEX_STATUS_MAP.paused.text },
+    { value: 'error', name: DOC_INDEX_STATUS_MAP.error.text },
+    { value: 'available', name: DOC_INDEX_STATUS_MAP.available.text },
+    { value: 'enabled', name: DOC_INDEX_STATUS_MAP.enabled.text },
+    { value: 'disabled', name: DOC_INDEX_STATUS_MAP.disabled.text },
+    { value: 'archived', name: DOC_INDEX_STATUS_MAP.archived.text },
+  ], [DOC_INDEX_STATUS_MAP, t])
+
+  const sortItems: Item[] = useMemo(() => [
+    { value: 'created_at', name: t('list.sort.uploadTime', { ns: 'datasetDocuments' }) as string },
+    { value: 'hit_count', name: t('list.sort.hitCount', { ns: 'datasetDocuments' }) as string },
+  ], [t])
+
+  // Determine add button text based on data source type
+  const addButtonText = useMemo(() => {
+    if (isDataSourceNotion)
+      return t('list.addPages', { ns: 'datasetDocuments' })
+    if (isDataSourceWeb)
+      return t('list.addUrl', { ns: 'datasetDocuments' })
+    return t('list.addFile', { ns: 'datasetDocuments' })
+  }, [isDataSourceNotion, isDataSourceWeb, t])
+
+  return (
+    <>
+      {/* Title section */}
+      <div className="flex flex-col justify-center gap-1 px-6 pt-4">
+        <h1 className="text-base font-semibold text-text-primary">
+          {t('list.title', { ns: 'datasetDocuments' })}
+        </h1>
+        <div className="flex items-center space-x-0.5 text-sm font-normal text-text-tertiary">
+          <span>{t('list.desc', { ns: 'datasetDocuments' })}</span>
+          <a
+            className="flex items-center text-text-accent"
+            target="_blank"
+            rel="noopener noreferrer"
+            href={docLink('/guides/knowledge-base/integrate-knowledge-within-application')}
+          >
+            <span>{t('list.learnMore', { ns: 'datasetDocuments' })}</span>
+            <RiExternalLinkLine className="h-3 w-3" />
+          </a>
+        </div>
+      </div>
+
+      {/* Toolbar section */}
+      <div className="flex flex-wrap items-center justify-between px-6 pt-4">
+        {/* Left: Filters */}
+        <div className="flex items-center gap-2">
+          <Chip
+            className="w-[160px]"
+            showLeftIcon={false}
+            value={statusFilterValue}
+            items={statusFilterItems}
+            onSelect={item => onStatusFilterChange(item?.value ? String(item.value) : '')}
+            onClear={onStatusFilterClear}
+          />
+          <Input
+            showLeftIcon
+            showClearIcon
+            wrapperClassName="!w-[200px]"
+            value={inputValue}
+            onChange={e => onInputChange(e.target.value)}
+            onClear={() => onInputChange('')}
+          />
+          <div className="h-3.5 w-px bg-divider-regular"></div>
+          <Sort
+            order={sortValue.startsWith('-') ? '-' : ''}
+            value={sortValue.replace('-', '')}
+            items={sortItems}
+            onSelect={value => onSortChange(String(value))}
+          />
+        </div>
+
+        {/* Right: Actions */}
+        <div className="flex !h-8 items-center justify-center gap-2">
+          {!isFreePlan && <AutoDisabledDocument datasetId={datasetId} />}
+          <IndexFailed datasetId={datasetId} />
+          {!embeddingAvailable && (
+            <StatusWithAction
+              type="warning"
+              description={t('embeddingModelNotAvailable', { ns: 'dataset' })}
+            />
+          )}
+          {embeddingAvailable && (
+            <Button variant="secondary" className="shrink-0" onClick={showEditMetadataModal}>
+              <RiDraftLine className="mr-1 size-4" />
+              {t('metadata.metadata', { ns: 'dataset' })}
+            </Button>
+          )}
+          {isShowEditMetadataModal && (
+            <DatasetMetadataDrawer
+              userMetadata={datasetMetaData ?? []}
+              onClose={hideEditMetadataModal}
+              onAdd={onAddMetaData}
+              onRename={onRenameMetaData}
+              onRemove={onDeleteMetaData}
+              builtInMetadata={builtInMetaData ?? []}
+              isBuiltInEnabled={builtInEnabled}
+              onIsBuiltInEnabledChange={onBuiltInEnabledChange}
+            />
+          )}
+          {embeddingAvailable && (
+            <Button variant="primary" onClick={onAddDocument} className="shrink-0">
+              <PlusIcon className="mr-2 h-4 w-4 stroke-current" />
+              {addButtonText}
+            </Button>
+          )}
+        </div>
+      </div>
+    </>
+  )
+}
+
+export default DocumentsHeader

web/app/components/datasets/documents/components/empty-element.tsx

@@ -0,0 +1,41 @@
+'use client'
+import type { FC } from 'react'
+import { PlusIcon } from '@heroicons/react/24/solid'
+import { useTranslation } from 'react-i18next'
+import Button from '@/app/components/base/button'
+import s from '../style.module.css'
+import { FolderPlusIcon, NotionIcon, ThreeDotsIcon } from './icons'
+
+type EmptyElementProps = {
+  canAdd: boolean
+  onClick: () => void
+  type?: 'upload' | 'sync'
+}
+
+const EmptyElement: FC<EmptyElementProps> = ({ canAdd = true, onClick, type = 'upload' }) => {
+  const { t } = useTranslation()
+  return (
+    <div className={s.emptyWrapper}>
+      <div className={s.emptyElement}>
+        <div className={s.emptySymbolIconWrapper}>
+          {type === 'upload' ? <FolderPlusIcon /> : <NotionIcon />}
+        </div>
+        <span className={s.emptyTitle}>
+          {t('list.empty.title', { ns: 'datasetDocuments' })}
+          <ThreeDotsIcon className="relative -left-1.5 -top-3 inline" />
+        </span>
+        <div className={s.emptyTip}>
+          {t(`list.empty.${type}.tip`, { ns: 'datasetDocuments' })}
+        </div>
+        {type === 'upload' && canAdd && (
+          <Button onClick={onClick} className={s.addFileBtn} variant="secondary-accent">
+            <PlusIcon className={s.plusIcon} />
+            {t('list.addFile', { ns: 'datasetDocuments' })}
+          </Button>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export default EmptyElement

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

@@ -0,0 +1,34 @@
+import type * as React from 'react'
+
+export const FolderPlusIcon = ({ className }: React.SVGProps<SVGElement>) => {
+  return (
+    <svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg" className={className ?? ''}>
+      <path d="M10.8332 5.83333L9.90355 3.9741C9.63601 3.439 9.50222 3.17144 9.30265 2.97597C9.12615 2.80311 8.91344 2.67164 8.6799 2.59109C8.41581 2.5 8.11668 2.5 7.51841 2.5H4.33317C3.39975 2.5 2.93304 2.5 2.57652 2.68166C2.26292 2.84144 2.00795 3.09641 1.84816 3.41002C1.6665 3.76654 1.6665 4.23325 1.6665 5.16667V5.83333M1.6665 5.83333H14.3332C15.7333 5.83333 16.4334 5.83333 16.9681 6.10582C17.4386 6.3455 17.821 6.72795 18.0607 7.19836C18.3332 7.73314 18.3332 8.4332 18.3332 9.83333V13.5C18.3332 14.9001 18.3332 15.6002 18.0607 16.135C17.821 16.6054 17.4386 16.9878 16.9681 17.2275C16.4334 17.5 15.7333 17.5 14.3332 17.5H5.6665C4.26637 17.5 3.56631 17.5 3.03153 17.2275C2.56112 16.9878 2.17867 16.6054 1.93899 16.135C1.6665 15.6002 1.6665 14.9001 1.6665 13.5V5.83333ZM9.99984 14.1667V9.16667M7.49984 11.6667H12.4998" stroke="#667085" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  )
+}
+
+export const ThreeDotsIcon = ({ className }: React.SVGProps<SVGElement>) => {
+  return (
+    <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" className={className ?? ''}>
+      <path d="M5 6.5V5M8.93934 7.56066L10 6.5M10.0103 11.5H11.5103" stroke="#374151" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
+    </svg>
+  )
+}
+
+export const NotionIcon = ({ className }: React.SVGProps<SVGElement>) => {
+  return (
+    <svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg" className={className ?? ''}>
+      <g clipPath="url(#clip0_2164_11263)">
+        <path fillRule="evenodd" clipRule="evenodd" d="M3.5725 18.2611L1.4229 15.5832C0.905706 14.9389 0.625 14.1466 0.625 13.3312V3.63437C0.625 2.4129 1.60224 1.39936 2.86295 1.31328L12.8326 0.632614C13.5569 0.583164 14.2768 0.775682 14.8717 1.17794L18.3745 3.5462C19.0015 3.97012 19.375 4.66312 19.375 5.40266V16.427C19.375 17.6223 18.4141 18.6121 17.1798 18.688L6.11458 19.3692C5.12958 19.4298 4.17749 19.0148 3.5725 18.2611Z" fill="white" />
+        <path d="M7.03006 8.48669V8.35974C7.03006 8.03794 7.28779 7.77104 7.61997 7.74886L10.0396 7.58733L13.3857 12.5147V8.19009L12.5244 8.07528V8.01498C12.5244 7.68939 12.788 7.42074 13.1244 7.4035L15.326 7.29073V7.60755C15.326 7.75628 15.2154 7.88349 15.0638 7.90913L14.534 7.99874V15.0023L13.8691 15.231C13.3136 15.422 12.6952 15.2175 12.3772 14.7377L9.12879 9.83574V14.5144L10.1287 14.7057L10.1147 14.7985C10.0711 15.089 9.82028 15.3087 9.51687 15.3222L7.03006 15.4329C6.99718 15.1205 7.23132 14.841 7.55431 14.807L7.88143 14.7727V8.53453L7.03006 8.48669Z" fill="black" />
+        <path fillRule="evenodd" clipRule="evenodd" d="M12.9218 1.85424L2.95217 2.53491C2.35499 2.57568 1.89209 3.05578 1.89209 3.63437V13.3312C1.89209 13.8748 2.07923 14.403 2.42402 14.8325L4.57362 17.5104C4.92117 17.9434 5.46812 18.1818 6.03397 18.147L17.0991 17.4658C17.6663 17.4309 18.1078 16.9762 18.1078 16.427V5.40266C18.1078 5.06287 17.9362 4.74447 17.6481 4.54969L14.1453 2.18143C13.7883 1.94008 13.3564 1.82457 12.9218 1.85424ZM3.44654 3.78562C3.30788 3.68296 3.37387 3.46909 3.54806 3.4566L12.9889 2.77944C13.2897 2.75787 13.5886 2.8407 13.8318 3.01305L15.7261 4.35508C15.798 4.40603 15.7642 4.51602 15.6752 4.52086L5.67742 5.0646C5.37485 5.08106 5.0762 4.99217 4.83563 4.81406L3.44654 3.78562ZM5.20848 6.76919C5.20848 6.4444 5.47088 6.1761 5.80642 6.15783L16.3769 5.58216C16.7039 5.56435 16.9792 5.81583 16.9792 6.13239V15.6783C16.9792 16.0025 16.7177 16.2705 16.3829 16.2896L5.8793 16.8872C5.51537 16.9079 5.20848 16.6283 5.20848 16.2759V6.76919Z" fill="black" />
+      </g>
+      <defs>
+        <clipPath id="clip0_2164_11263">
+          <rect width="20" height="20" fill="white" />
+        </clipPath>
+      </defs>
+    </svg>
+  )
+}

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

@@ -16,13 +16,16 @@ import * as React from 'react'
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import Checkbox from '@/app/components/base/checkbox'
+import FileTypeIcon from '@/app/components/base/file-uploader/file-type-icon'
 import NotionIcon from '@/app/components/base/notion-icon'
 import Pagination from '@/app/components/base/pagination'
 import Toast from '@/app/components/base/toast'
 import Tooltip from '@/app/components/base/tooltip'
+import ChunkingModeLabel from '@/app/components/datasets/common/chunking-mode-label'
 import { normalizeStatusForQuery } from '@/app/components/datasets/documents/status-filter'
 import { extensionToFileType } from '@/app/components/datasets/hit-testing/utils/extension-to-file-type'
 import EditMetadataBatchModal from '@/app/components/datasets/metadata/edit-metadata-batch/modal'
+import useBatchEditDocumentMetadata from '@/app/components/datasets/metadata/hooks/use-batch-edit-document-metadata'
 import { useDatasetDetailContextWithSelector as useDatasetDetailContext } from '@/context/dataset-detail'
 import useTimestamp from '@/hooks/use-timestamp'
 import { ChunkingMode, DataSourceType, DocumentActionType } from '@/models/datasets'
@@ -31,14 +34,11 @@ import { useDocumentArchive, useDocumentBatchRetryIndex, useDocumentDelete, useD
 import { asyncRunSafe } from '@/utils'
 import { cn } from '@/utils/classnames'
 import { formatNumber } from '@/utils/format'
-import FileTypeIcon from '../../base/file-uploader/file-type-icon'
-import ChunkingModeLabel from '../common/chunking-mode-label'
-import useBatchEditDocumentMetadata from '../metadata/hooks/use-batch-edit-document-metadata'
-import BatchAction from './detail/completed/common/batch-action'
+import BatchAction from '../detail/completed/common/batch-action'
+import StatusItem from '../status-item'
+import s from '../style.module.css'
 import Operations from './operations'
 import RenameModal from './rename-modal'
-import StatusItem from './status-item'
-import s from './style.module.css'
 
 export const renderTdValue = (value: string | number | null, isEmptyStyle = false) => {
   return (

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

@@ -1,4 +1,4 @@
-import type { OperationName } from './types'
+import type { OperationName } from '../types'
 import type { CommonResponse } from '@/models/common'
 import {
   RiArchive2Line,
@@ -17,6 +17,12 @@ import * as React from 'react'
 import { useCallback, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import { useContext } from 'use-context-selector'
+import Confirm from '@/app/components/base/confirm'
+import Divider from '@/app/components/base/divider'
+import CustomPopover from '@/app/components/base/popover'
+import Switch from '@/app/components/base/switch'
+import { ToastContext } from '@/app/components/base/toast'
+import Tooltip from '@/app/components/base/tooltip'
 import { DataSourceType, DocumentActionType } from '@/models/datasets'
 import {
   useDocumentArchive,
@@ -31,14 +37,8 @@ import {
 } from '@/service/knowledge/use-document'
 import { asyncRunSafe } from '@/utils'
 import { cn } from '@/utils/classnames'
-import Confirm from '../../base/confirm'
-import Divider from '../../base/divider'
-import CustomPopover from '../../base/popover'
-import Switch from '../../base/switch'
-import { ToastContext } from '../../base/toast'
-import Tooltip from '../../base/tooltip'
+import s from '../style.module.css'
 import RenameModal from './rename-modal'
-import s from './style.module.css'
 
 type OperationsProps = {
   embeddingAvailable: boolean

web/app/components/datasets/documents/components/rename-modal.tsx

@@ -7,8 +7,8 @@ import { useTranslation } from 'react-i18next'
 import Button from '@/app/components/base/button'
 import Input from '@/app/components/base/input'
 import Modal from '@/app/components/base/modal'
+import Toast from '@/app/components/base/toast'
 import { renameDocumentName } from '@/service/datasets'
-import Toast from '../../base/toast'
 
 type Props = {
   datasetId: string

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

@@ -18,7 +18,7 @@ import { useDocumentDetail, useDocumentMetadata, useInvalidDocumentList } from '
 import { useCheckSegmentBatchImportProgress, useChildSegmentListKey, useSegmentBatchImport, useSegmentListKey } from '@/service/knowledge/use-segment'
 import { useInvalid } from '@/service/use-base'
 import { cn } from '@/utils/classnames'
-import Operations from '../operations'
+import Operations from '../components/operations'
 import StatusItem from '../status-item'
 import BatchModal from './batch-modal'
 import Completed from './completed'

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

@@ -0,0 +1,197 @@
+import type { DocumentListResponse } from '@/models/datasets'
+import type { SortType } from '@/service/datasets'
+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'
+
+/**
+ * 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()
+
+  // Search state
+  const [inputValue, setInputValue] = useState<string>('')
+  const [searchValue, setSearchValue] = useState<string>('')
+  const debouncedSearchValue = useDebounce(searchValue, { wait: 500 })
+
+  // Filter & sort state
+  const [statusFilterValue, setStatusFilterValue] = useState<string>(() => sanitizeStatusValue(query.status))
+  const [sortValue, setSortValue] = useState<SortType>(query.sort)
+  const normalizedStatusFilterValue = useMemo(
+    () => normalizeStatusForQuery(statusFilterValue),
+    [statusFilterValue],
+  )
+
+  // 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])
+
+  // 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)
+    setStatusFilterValue(selectedValue)
+    setCurrPage(0)
+    updateQuery({ status: selectedValue, page: 1 })
+  }, [updateQuery])
+
+  // Status filter clear handler
+  const handleStatusFilterClear = useCallback(() => {
+    if (statusFilterValue === 'all')
+      return
+    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,
+    handleStatusFilterChange,
+    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,185 +1,55 @@
 'use client'
 import type { FC } from 'react'
-import type { Item } from '@/app/components/base/select'
-import type { SortType } from '@/service/datasets'
-import { PlusIcon } from '@heroicons/react/24/solid'
-import { RiDraftLine, RiExternalLinkLine } from '@remixicon/react'
-import { useDebounce, useDebounceFn } from 'ahooks'
 import { useRouter } from 'next/navigation'
-import * as React from 'react'
-import { useCallback, useEffect, useMemo, useState } from 'react'
-import { useTranslation } from 'react-i18next'
-import Button from '@/app/components/base/button'
-import Input from '@/app/components/base/input'
+import { useCallback, useEffect } from 'react'
 import Loading from '@/app/components/base/loading'
-import IndexFailed from '@/app/components/datasets/common/document-status-with-action/index-failed'
 import { useDatasetDetailContextWithSelector } from '@/context/dataset-detail'
-import { useDocLink } from '@/context/i18n'
 import { useProviderContext } from '@/context/provider-context'
 import { DataSourceType } from '@/models/datasets'
 import { useDocumentList, useInvalidDocumentDetail, useInvalidDocumentList } from '@/service/knowledge/use-document'
 import { useChildSegmentListKey, useSegmentListKey } from '@/service/knowledge/use-segment'
 import { useInvalid } from '@/service/use-base'
-import { cn } from '@/utils/classnames'
-import Chip from '../../base/chip'
-import Sort from '../../base/sort'
-import AutoDisabledDocument from '../common/document-status-with-action/auto-disabled-document'
-import StatusWithAction from '../common/document-status-with-action/status-with-action'
 import useEditDocumentMetadata from '../metadata/hooks/use-edit-dataset-metadata'
-import DatasetMetadataDrawer from '../metadata/metadata-dataset/dataset-metadata-drawer'
-import useDocumentListQueryState from './hooks/use-document-list-query-state'
-import List from './list'
-import { normalizeStatusForQuery, sanitizeStatusValue } from './status-filter'
-import { useIndexStatus } from './status-item/hooks'
-import s from './style.module.css'
-
-const FolderPlusIcon = ({ className }: React.SVGProps<SVGElement>) => {
-  return (
-    <svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg" className={className ?? ''}>
-      <path d="M10.8332 5.83333L9.90355 3.9741C9.63601 3.439 9.50222 3.17144 9.30265 2.97597C9.12615 2.80311 8.91344 2.67164 8.6799 2.59109C8.41581 2.5 8.11668 2.5 7.51841 2.5H4.33317C3.39975 2.5 2.93304 2.5 2.57652 2.68166C2.26292 2.84144 2.00795 3.09641 1.84816 3.41002C1.6665 3.76654 1.6665 4.23325 1.6665 5.16667V5.83333M1.6665 5.83333H14.3332C15.7333 5.83333 16.4334 5.83333 16.9681 6.10582C17.4386 6.3455 17.821 6.72795 18.0607 7.19836C18.3332 7.73314 18.3332 8.4332 18.3332 9.83333V13.5C18.3332 14.9001 18.3332 15.6002 18.0607 16.135C17.821 16.6054 17.4386 16.9878 16.9681 17.2275C16.4334 17.5 15.7333 17.5 14.3332 17.5H5.6665C4.26637 17.5 3.56631 17.5 3.03153 17.2275C2.56112 16.9878 2.17867 16.6054 1.93899 16.135C1.6665 15.6002 1.6665 14.9001 1.6665 13.5V5.83333ZM9.99984 14.1667V9.16667M7.49984 11.6667H12.4998" stroke="#667085" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
-    </svg>
-  )
-}
-
-const ThreeDotsIcon = ({ className }: React.SVGProps<SVGElement>) => {
-  return (
-    <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg" className={className ?? ''}>
-      <path d="M5 6.5V5M8.93934 7.56066L10 6.5M10.0103 11.5H11.5103" stroke="#374151" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
-    </svg>
-  )
-}
-
-const NotionIcon = ({ className }: React.SVGProps<SVGElement>) => {
-  return (
-    <svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg" className={className ?? ''}>
-      <g clipPath="url(#clip0_2164_11263)">
-        <path fillRule="evenodd" clipRule="evenodd" d="M3.5725 18.2611L1.4229 15.5832C0.905706 14.9389 0.625 14.1466 0.625 13.3312V3.63437C0.625 2.4129 1.60224 1.39936 2.86295 1.31328L12.8326 0.632614C13.5569 0.583164 14.2768 0.775682 14.8717 1.17794L18.3745 3.5462C19.0015 3.97012 19.375 4.66312 19.375 5.40266V16.427C19.375 17.6223 18.4141 18.6121 17.1798 18.688L6.11458 19.3692C5.12958 19.4298 4.17749 19.0148 3.5725 18.2611Z" fill="white" />
-        <path d="M7.03006 8.48669V8.35974C7.03006 8.03794 7.28779 7.77104 7.61997 7.74886L10.0396 7.58733L13.3857 12.5147V8.19009L12.5244 8.07528V8.01498C12.5244 7.68939 12.788 7.42074 13.1244 7.4035L15.326 7.29073V7.60755C15.326 7.75628 15.2154 7.88349 15.0638 7.90913L14.534 7.99874V15.0023L13.8691 15.231C13.3136 15.422 12.6952 15.2175 12.3772 14.7377L9.12879 9.83574V14.5144L10.1287 14.7057L10.1147 14.7985C10.0711 15.089 9.82028 15.3087 9.51687 15.3222L7.03006 15.4329C6.99718 15.1205 7.23132 14.841 7.55431 14.807L7.88143 14.7727V8.53453L7.03006 8.48669Z" fill="black" />
-        <path fillRule="evenodd" clipRule="evenodd" d="M12.9218 1.85424L2.95217 2.53491C2.35499 2.57568 1.89209 3.05578 1.89209 3.63437V13.3312C1.89209 13.8748 2.07923 14.403 2.42402 14.8325L4.57362 17.5104C4.92117 17.9434 5.46812 18.1818 6.03397 18.147L17.0991 17.4658C17.6663 17.4309 18.1078 16.9762 18.1078 16.427V5.40266C18.1078 5.06287 17.9362 4.74447 17.6481 4.54969L14.1453 2.18143C13.7883 1.94008 13.3564 1.82457 12.9218 1.85424ZM3.44654 3.78562C3.30788 3.68296 3.37387 3.46909 3.54806 3.4566L12.9889 2.77944C13.2897 2.75787 13.5886 2.8407 13.8318 3.01305L15.7261 4.35508C15.798 4.40603 15.7642 4.51602 15.6752 4.52086L5.67742 5.0646C5.37485 5.08106 5.0762 4.99217 4.83563 4.81406L3.44654 3.78562ZM5.20848 6.76919C5.20848 6.4444 5.47088 6.1761 5.80642 6.15783L16.3769 5.58216C16.7039 5.56435 16.9792 5.81583 16.9792 6.13239V15.6783C16.9792 16.0025 16.7177 16.2705 16.3829 16.2896L5.8793 16.8872C5.51537 16.9079 5.20848 16.6283 5.20848 16.2759V6.76919Z" fill="black" />
-      </g>
-      <defs>
-        <clipPath id="clip0_2164_11263">
-          <rect width="20" height="20" fill="white" />
-        </clipPath>
-      </defs>
-    </svg>
-  )
-}
-
-const EmptyElement: FC<{ canAdd: boolean, onClick: () => void, type?: 'upload' | 'sync' }> = ({ canAdd = true, onClick, type = 'upload' }) => {
-  const { t } = useTranslation()
-  return (
-    <div className={s.emptyWrapper}>
-      <div className={s.emptyElement}>
-        <div className={s.emptySymbolIconWrapper}>
-          {type === 'upload' ? <FolderPlusIcon /> : <NotionIcon />}
-        </div>
-        <span className={s.emptyTitle}>
-          {t('list.empty.title', { ns: 'datasetDocuments' })}
-          <ThreeDotsIcon className="relative -left-1.5 -top-3 inline" />
-        </span>
-        <div className={s.emptyTip}>
-          {t(`list.empty.${type}.tip`, { ns: 'datasetDocuments' })}
-        </div>
-        {type === 'upload' && canAdd && (
-          <Button onClick={onClick} className={s.addFileBtn} variant="secondary-accent">
-            <PlusIcon className={s.plusIcon} />
-            {t('list.addFile', { ns: 'datasetDocuments' })}
-          </Button>
-        )}
-      </div>
-    </div>
-  )
-}
+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'
 
 type IDocumentsProps = {
   datasetId: string
 }
 
 const Documents: FC<IDocumentsProps> = ({ datasetId }) => {
-  const { t } = useTranslation()
-  const docLink = useDocLink()
+  const router = useRouter()
   const { plan } = useProviderContext()
   const isFreePlan = plan.type === 'sandbox'
-  const { query, updateQuery } = useDocumentListQueryState()
-  const [inputValue, setInputValue] = useState<string>('') // the input value
-  const [searchValue, setSearchValue] = useState<string>('')
-  const [statusFilterValue, setStatusFilterValue] = useState<string>(() => sanitizeStatusValue(query.status))
-  const [sortValue, setSortValue] = useState<SortType>(query.sort)
-  const DOC_INDEX_STATUS_MAP = useIndexStatus()
-  const [currPage, setCurrPage] = React.useState<number>(query.page - 1) // Convert to 0-based index
-  const [limit, setLimit] = useState<number>(query.limit)
 
-  const router = useRouter()
   const dataset = useDatasetDetailContextWithSelector(s => s.dataset)
-  const [timerCanRun, setTimerCanRun] = useState(true)
-  const isDataSourceNotion = dataset?.data_source_type === DataSourceType.NOTION
-  const isDataSourceWeb = dataset?.data_source_type === DataSourceType.WEB
-  const isDataSourceFile = dataset?.data_source_type === DataSourceType.FILE
   const embeddingAvailable = !!dataset?.embedding_available
-  const debouncedSearchValue = useDebounce(searchValue, { wait: 500 })
 
-  const statusFilterItems: Item[] = useMemo(() => [
-    { value: 'all', name: t('list.index.all', { ns: 'datasetDocuments' }) as string },
-    { value: 'queuing', name: DOC_INDEX_STATUS_MAP.queuing.text },
-    { value: 'indexing', name: DOC_INDEX_STATUS_MAP.indexing.text },
-    { value: 'paused', name: DOC_INDEX_STATUS_MAP.paused.text },
-    { value: 'error', name: DOC_INDEX_STATUS_MAP.error.text },
-    { value: 'available', name: DOC_INDEX_STATUS_MAP.available.text },
-    { value: 'enabled', name: DOC_INDEX_STATUS_MAP.enabled.text },
-    { value: 'disabled', name: DOC_INDEX_STATUS_MAP.disabled.text },
-    { value: 'archived', name: DOC_INDEX_STATUS_MAP.archived.text },
-  ], [DOC_INDEX_STATUS_MAP, t])
-  const normalizedStatusFilterValue = useMemo(() => normalizeStatusForQuery(statusFilterValue), [statusFilterValue])
-  const sortItems: Item[] = useMemo(() => [
-    { value: 'created_at', name: t('list.sort.uploadTime', { ns: 'datasetDocuments' }) as string },
-    { value: 'hit_count', name: t('list.sort.hitCount', { ns: 'datasetDocuments' }) as string },
-  ], [t])
-
-  // 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 pagination changes
-  const handlePageChange = (newPage: number) => {
-    setCurrPage(newPage)
-    updateQuery({ page: newPage + 1 }) // Pagination emits 0-based page, convert to 1-based for URL
-  }
-
-  // Update URL when limit changes
-  const handleLimitChange = (newLimit: number) => {
-    setLimit(newLimit)
-    setCurrPage(0) // Reset to first page when limit changes
-    updateQuery({ limit: newLimit, page: 1 })
-  }
-
-  // Update URL when search changes
-  useEffect(() => {
-    if (debouncedSearchValue !== query.keyword) {
-      setCurrPage(0) // Reset to first page when search changes
-      updateQuery({ keyword: debouncedSearchValue, page: 1 })
-    }
-  }, [debouncedSearchValue, query.keyword, updateQuery])
+  // Use custom hook for page state management
+  const {
+    inputValue,
+    debouncedSearchValue,
+    handleInputChange,
+    statusFilterValue,
+    sortValue,
+    normalizedStatusFilterValue,
+    handleStatusFilterChange,
+    handleStatusFilterClear,
+    handleSortChange,
+    currPage,
+    limit,
+    handlePageChange,
+    handleLimitChange,
+    selectedIds,
+    setSelectedIds,
+    timerCanRun,
+    updatePollingState,
+    adjustPageForTotal,
+  } = useDocumentsPageState()
 
+  // Fetch document list
   const { data: documentsRes, isLoading: isListLoading } = useDocumentList({
     datasetId,
     query: {
@@ -192,16 +62,18 @@ const Documents: FC<IDocumentsProps> = ({ datasetId }) => {
     refetchInterval: timerCanRun ? 2500 : 0,
   })
 
-  const invalidDocumentList = useInvalidDocumentList(datasetId)
-
+  // Update polling state when documents change
   useEffect(() => {
-    if (documentsRes) {
-      const totalPages = Math.ceil(documentsRes.total / limit)
-      if (totalPages < currPage + 1)
-        setCurrPage(totalPages === 0 ? 0 : totalPages - 1)
-    }
-  }, [documentsRes])
+    updatePollingState(documentsRes)
+  }, [documentsRes, updatePollingState])
 
+  // Adjust page when total changes
+  useEffect(() => {
+    adjustPageForTotal(documentsRes)
+  }, [documentsRes, adjustPageForTotal])
+
+  // Invalidation hooks
+  const invalidDocumentList = useInvalidDocumentList(datasetId)
   const invalidDocumentDetail = useInvalidDocumentDetail()
   const invalidChunkList = useInvalid(useSegmentListKey)
   const invalidChildChunkList = useInvalid(useChildSegmentListKey)
@@ -213,73 +85,9 @@ const Documents: FC<IDocumentsProps> = ({ datasetId }) => {
       invalidChunkList()
       invalidChildChunkList()
     }, 5000)
-  }, [])
-
-  useEffect(() => {
-    let completedNum = 0
-    let percent = 0
-    documentsRes?.data?.forEach((documentItem) => {
-      const { indexing_status, completed_segments, total_segments } = documentItem
-      const isEmbedded = indexing_status === 'completed' || indexing_status === 'paused' || indexing_status === 'error'
-
-      if (isEmbedded)
-        completedNum++
-
-      const completedCount = completed_segments || 0
-      const totalCount = total_segments || 0
-      if (totalCount === 0 && completedCount === 0) {
-        percent = isEmbedded ? 100 : 0
-      }
-      else {
-        const per = Math.round(completedCount * 100 / totalCount)
-        percent = per > 100 ? 100 : per
-      }
-      return {
-        ...documentItem,
-        percent,
-      }
-    })
-
-    const hasIncompleteDocuments = completedNum !== documentsRes?.data?.length
-    const transientStatuses = ['queuing', 'indexing', 'paused']
-    const shouldForcePolling = normalizedStatusFilterValue === 'all'
-      ? false
-      : transientStatuses.includes(normalizedStatusFilterValue)
-    setTimerCanRun(shouldForcePolling || hasIncompleteDocuments)
-  }, [documentsRes, normalizedStatusFilterValue])
-  const total = documentsRes?.total || 0
-
-  const routeToDocCreate = () => {
-    // if dataset is created from pipeline, go to create from pipeline page
-    if (dataset?.runtime_mode === 'rag_pipeline') {
-      router.push(`/datasets/${datasetId}/documents/create-from-pipeline`)
-      return
-    }
-    router.push(`/datasets/${datasetId}/documents/create`)
-  }
-
-  const documentsList = documentsRes?.data
-  const [selectedIds, setSelectedIds] = useState<string[]>([])
-
-  // Clear selection when search changes to avoid confusion
-  useEffect(() => {
-    if (searchValue !== query.keyword)
-      setSelectedIds([])
-  }, [searchValue, query.keyword])
-
-  useEffect(() => {
-    setSelectedIds([])
-  }, [normalizedStatusFilterValue])
-
-  const { run: handleSearch } = useDebounceFn(() => {
-    setSearchValue(inputValue)
-  }, { wait: 500 })
-
-  const handleInputChange = (value: string) => {
-    setInputValue(value)
-    handleSearch()
-  }
+  }, [invalidDocumentList, invalidDocumentDetail, invalidChunkList, invalidChildChunkList])
 
+  // Metadata editing hook
   const {
     isShowEditModal: isShowEditMetadataModal,
     showEditModal: showEditMetadataModal,
@@ -297,130 +105,84 @@ const Documents: FC<IDocumentsProps> = ({ datasetId }) => {
     onUpdateDocList: invalidDocumentList,
   })
 
+  // Route to document creation page
+  const routeToDocCreate = useCallback(() => {
+    if (dataset?.runtime_mode === 'rag_pipeline') {
+      router.push(`/datasets/${datasetId}/documents/create-from-pipeline`)
+      return
+    }
+    router.push(`/datasets/${datasetId}/documents/create`)
+  }, [dataset?.runtime_mode, datasetId, router])
+
+  const total = documentsRes?.total || 0
+  const documentsList = documentsRes?.data
+
+  // Render content based on loading and data state
+  const renderContent = () => {
+    if (isListLoading)
+      return <Loading type="app" />
+
+    if (total > 0) {
+      return (
+        <List
+          embeddingAvailable={embeddingAvailable}
+          documents={documentsList || []}
+          datasetId={datasetId}
+          onUpdate={handleUpdate}
+          selectedIds={selectedIds}
+          onSelectedIdChange={setSelectedIds}
+          statusFilterValue={normalizedStatusFilterValue}
+          remoteSortValue={sortValue}
+          pagination={{
+            total,
+            limit,
+            onLimitChange: handleLimitChange,
+            current: currPage,
+            onChange: handlePageChange,
+          }}
+          onManageMetadata={showEditMetadataModal}
+        />
+      )
+    }
+
+    const isDataSourceNotion = dataset?.data_source_type === DataSourceType.NOTION
+    return (
+      <EmptyElement
+        canAdd={embeddingAvailable}
+        onClick={routeToDocCreate}
+        type={isDataSourceNotion ? 'sync' : 'upload'}
+      />
+    )
+  }
+
   return (
     <div className="flex h-full flex-col">
-      <div className="flex flex-col justify-center gap-1 px-6 pt-4">
-        <h1 className="text-base font-semibold text-text-primary">{t('list.title', { ns: 'datasetDocuments' })}</h1>
-        <div className="flex items-center space-x-0.5 text-sm font-normal text-text-tertiary">
-          <span>{t('list.desc', { ns: 'datasetDocuments' })}</span>
-          <a
-            className="flex items-center text-text-accent"
-            target="_blank"
-            href={docLink('/guides/knowledge-base/integrate-knowledge-within-application')}
-          >
-            <span>{t('list.learnMore', { ns: 'datasetDocuments' })}</span>
-            <RiExternalLinkLine className="h-3 w-3" />
-          </a>
-        </div>
-      </div>
+      <DocumentsHeader
+        datasetId={datasetId}
+        dataSourceType={dataset?.data_source_type}
+        embeddingAvailable={embeddingAvailable}
+        isFreePlan={isFreePlan}
+        statusFilterValue={statusFilterValue}
+        sortValue={sortValue}
+        inputValue={inputValue}
+        onStatusFilterChange={handleStatusFilterChange}
+        onStatusFilterClear={handleStatusFilterClear}
+        onSortChange={handleSortChange}
+        onInputChange={handleInputChange}
+        isShowEditMetadataModal={isShowEditMetadataModal}
+        showEditMetadataModal={showEditMetadataModal}
+        hideEditMetadataModal={hideEditMetadataModal}
+        datasetMetaData={datasetMetaData}
+        builtInMetaData={builtInMetaData}
+        builtInEnabled={!!builtInEnabled}
+        onAddMetaData={handleAddMetaData}
+        onRenameMetaData={handleRename}
+        onDeleteMetaData={handleDeleteMetaData}
+        onBuiltInEnabledChange={setBuiltInEnabled}
+        onAddDocument={routeToDocCreate}
+      />
       <div className="flex h-0 grow flex-col px-6 pt-4">
-        <div className="flex flex-wrap items-center justify-between">
-          <div className="flex items-center gap-2">
-            <Chip
-              className="w-[160px]"
-              showLeftIcon={false}
-              value={statusFilterValue}
-              items={statusFilterItems}
-              onSelect={(item) => {
-                const selectedValue = sanitizeStatusValue(item?.value ? String(item.value) : '')
-                setStatusFilterValue(selectedValue)
-                setCurrPage(0)
-                updateQuery({ status: selectedValue, page: 1 })
-              }}
-              onClear={() => {
-                if (statusFilterValue === 'all')
-                  return
-                setStatusFilterValue('all')
-                setCurrPage(0)
-                updateQuery({ status: 'all', page: 1 })
-              }}
-            />
-            <Input
-              showLeftIcon
-              showClearIcon
-              wrapperClassName="!w-[200px]"
-              value={inputValue}
-              onChange={e => handleInputChange(e.target.value)}
-              onClear={() => handleInputChange('')}
-            />
-            <div className="h-3.5 w-px bg-divider-regular"></div>
-            <Sort
-              order={sortValue.startsWith('-') ? '-' : ''}
-              value={sortValue.replace('-', '')}
-              items={sortItems}
-              onSelect={(value) => {
-                const next = String(value) as SortType
-                if (next === sortValue)
-                  return
-                setSortValue(next)
-                setCurrPage(0)
-                updateQuery({ sort: next, page: 1 })
-              }}
-            />
-          </div>
-          <div className="flex !h-8 items-center justify-center gap-2">
-            {!isFreePlan && <AutoDisabledDocument datasetId={datasetId} />}
-            <IndexFailed datasetId={datasetId} />
-            {!embeddingAvailable && <StatusWithAction type="warning" description={t('embeddingModelNotAvailable', { ns: 'dataset' })} />}
-            {embeddingAvailable && (
-              <Button variant="secondary" className="shrink-0" onClick={showEditMetadataModal}>
-                <RiDraftLine className="mr-1 size-4" />
-                {t('metadata.metadata', { ns: 'dataset' })}
-              </Button>
-            )}
-            {isShowEditMetadataModal && (
-              <DatasetMetadataDrawer
-                userMetadata={datasetMetaData || []}
-                onClose={hideEditMetadataModal}
-                onAdd={handleAddMetaData}
-                onRename={handleRename}
-                onRemove={handleDeleteMetaData}
-                builtInMetadata={builtInMetaData || []}
-                isBuiltInEnabled={!!builtInEnabled}
-                onIsBuiltInEnabledChange={setBuiltInEnabled}
-              />
-            )}
-            {embeddingAvailable && (
-              <Button variant="primary" onClick={routeToDocCreate} className="shrink-0">
-                <PlusIcon className={cn('mr-2 h-4 w-4 stroke-current')} />
-                {isDataSourceNotion && t('list.addPages', { ns: 'datasetDocuments' })}
-                {isDataSourceWeb && t('list.addUrl', { ns: 'datasetDocuments' })}
-                {(!dataset?.data_source_type || isDataSourceFile) && t('list.addFile', { ns: 'datasetDocuments' })}
-              </Button>
-            )}
-          </div>
-        </div>
-        {isListLoading
-          ? <Loading type="app" />
-          // eslint-disable-next-line sonarjs/no-nested-conditional
-          : total > 0
-            ? (
-                <List
-                  embeddingAvailable={embeddingAvailable}
-                  documents={documentsList || []}
-                  datasetId={datasetId}
-                  onUpdate={handleUpdate}
-                  selectedIds={selectedIds}
-                  onSelectedIdChange={setSelectedIds}
-                  statusFilterValue={normalizedStatusFilterValue}
-                  remoteSortValue={sortValue}
-                  pagination={{
-                    total,
-                    limit,
-                    onLimitChange: handleLimitChange,
-                    current: currPage,
-                    onChange: handlePageChange,
-                  }}
-                  onManageMetadata={showEditMetadataModal}
-                />
-              )
-            : (
-                <EmptyElement
-                  canAdd={embeddingAvailable}
-                  onClick={routeToDocCreate}
-                  type={isDataSourceNotion ? 'sync' : 'upload'}
-                />
-              )}
+        {renderContent()}
       </div>
     </div>
   )

web/utils/format.spec.ts

@@ -19,6 +19,28 @@ describe('formatNumber', () => {
   it('should correctly handle empty input', () => {
     expect(formatNumber('')).toBe('')
   })
+  it('should format very small numbers without scientific notation', () => {
+    expect(formatNumber(0.0000008)).toBe('0.0000008')
+    expect(formatNumber(0.0000001)).toBe('0.0000001')
+    expect(formatNumber(0.000001)).toBe('0.000001')
+    expect(formatNumber(0.00001)).toBe('0.00001')
+  })
+  it('should format negative small numbers without scientific notation', () => {
+    expect(formatNumber(-0.0000008)).toBe('-0.0000008')
+    expect(formatNumber(-0.0000001)).toBe('-0.0000001')
+  })
+  it('should handle small numbers from string input', () => {
+    expect(formatNumber('0.0000008')).toBe('0.0000008')
+    expect(formatNumber('8E-7')).toBe('0.0000008')
+    expect(formatNumber('1e-7')).toBe('0.0000001')
+  })
+  it('should handle small numbers with multi-digit mantissa in scientific notation', () => {
+    expect(formatNumber(1.23e-7)).toBe('0.000000123')
+    expect(formatNumber(1.234e-7)).toBe('0.0000001234')
+    expect(formatNumber(12.34e-7)).toBe('0.000001234')
+    expect(formatNumber(0.0001234)).toBe('0.0001234')
+    expect(formatNumber('1.23e-7')).toBe('0.000000123')
+  })
 })
 describe('formatFileSize', () => {
   it('should return the input if it is falsy', () => {

web/utils/format.ts

@@ -26,11 +26,39 @@ import 'dayjs/locale/zh-tw'
  * Formats a number with comma separators.
  * @example formatNumber(1234567) will return '1,234,567'
  * @example formatNumber(1234567.89) will return '1,234,567.89'
+ * @example formatNumber(0.0000008) will return '0.0000008'
  */
 export const formatNumber = (num: number | string) => {
   if (!num)
     return num
-  const parts = num.toString().split('.')
+  const n = typeof num === 'string' ? Number(num) : num
+
+  let numStr: string
+
+  // Force fixed decimal for small numbers to avoid scientific notation
+  if (Math.abs(n) < 0.001 && n !== 0) {
+    const str = n.toString()
+    const match = str.match(/e-(\d+)$/)
+    let precision: number
+    if (match) {
+      // Scientific notation: precision is exponent + decimal digits in mantissa
+      const exponent = Number.parseInt(match[1], 10)
+      const mantissa = str.split('e')[0]
+      const mantissaDecimalPart = mantissa.split('.')[1]
+      precision = exponent + (mantissaDecimalPart?.length || 0)
+    }
+    else {
+      // Decimal notation: count decimal places
+      const decimalPart = str.split('.')[1]
+      precision = decimalPart?.length || 0
+    }
+    numStr = n.toFixed(precision)
+  }
+  else {
+    numStr = n.toString()
+  }
+
+  const parts = numStr.split('.')
   parts[0] = parts[0].replace(/\B(?=(\d{3})+(?!\d))/g, ',')
   return parts.join('.')
 }