@tutti-os/workspace-file-reference 0.0.14 → 0.0.16

package/dist/react/index.d.ts

@@ -1,7 +1,7 @@
-import { WorkspaceFileReference, WorkspaceFileReferencePrefetchReason, WorkspaceFileReferencePrefetchState, WorkspaceFileReferenceTreeSnapshot, WorkspaceFileReferenceAdapter, ReferenceScope, ReferenceNode, SelectedReference } from '../contracts/index.js';
+import { WorkspaceFileReference, WorkspaceFileReferencePrefetchReason, WorkspaceFileReferencePrefetchState, WorkspaceFileReferenceTreeSnapshot, WorkspaceFileReferenceAdapter, ReferenceScope, ReferenceNode, ReferenceLocateTarget, SelectedReference, ReferenceHandle } from '../contracts/index.js';
 import * as react from 'react';
 import { WorkspaceFilePreviewReadonlyReason } from '@tutti-os/workspace-file-preview';
-import { R as ReferenceSourceAggregator, a as ReferenceSourceTab } from '../referenceSourceAggregator-yyyLVOPi.js';
+import { R as ReferenceSourceAggregator, a as ReferenceSourceTab } from '../referenceSourceAggregator-B8ATnJOZ.js';
 
 declare const workspaceFileReferenceDefaultExpandedDepth = 4;
 interface WorkspaceFileReferenceDirectoryState {
@@ -40,6 +40,10 @@ type WorkspaceFileReferencePreviewState = {
 } | {
     status: "error";
     reference: WorkspaceFileReference;
+} | {
+    status: "html";
+    content: string;
+    reference: WorkspaceFileReference;
 } | {
     status: "image";
     objectUrl: string;
@@ -47,6 +51,10 @@ type WorkspaceFileReferencePreviewState = {
 } | {
     status: "loading";
     reference: WorkspaceFileReference;
+} | {
+    status: "video";
+    objectUrl: string;
+    reference: WorkspaceFileReference;
 } | {
     maxSizeBytes?: number;
     reason: WorkspaceFilePreviewReadonlyReason;
@@ -114,8 +122,21 @@ interface ReferenceSourceTabState {
     childrenByKey: Record<string, ReferenceSourceNodeChildrenState>;
     mode: ReferenceSourcePickerMode;
     searchQuery: string;
+    /** 已选文件类型筛选分类 id(全局统一口径);与 searchQuery 一起构成「查询」。 */
+    searchFilters: string[];
+    /** 当前搜索限定的二级分组节点 nodeId(左栏选中分组);null = 跨整源搜索。 */
+    searchScopeNodeId: string | null;
     searchEntries: ReferenceNode[];
     searchNextCursor: string | null;
+    /**
+     * 当前查询使用的结果上限(增长式分页:拉到底部时 +SEARCH_PAGE_SIZE 重查)。
+     * 0 = 尚未发起查询;每次新查询(改关键词/筛选/分组/换源)重置为 SEARCH_PAGE_SIZE。
+     */
+    searchLimit: number;
+    /** 是否可能还有更多结果(本页返回数 ≥ 请求上限,且未达全局上限)。 */
+    searchHasMore: boolean;
+    /** 正在加载下一页(增长 limit 重查在途);用于底部 spinner,不清空已有结果。 */
+    isSearchLoadingMore: boolean;
     isSearchLoading: boolean;
     searchError: Error | null;
 }
@@ -128,6 +149,23 @@ interface ReferenceSourcePickerSnapshot {
     /** 跨 tab 累积的选中文件节点,按选中顺序。 */
     selection: ReferenceNode[];
 }
+/** confirmGrouped 的产物:一个 navigable 源文件夹 = 一个 bundle(保留分组)。 */
+interface ReferenceConfirmBundle {
+    /** 被选中的文件夹节点(提供 displayName / iconUrl / ref 作为 bundle 身份)。 */
+    root: ReferenceNode;
+    /**
+     * 该 bundle 归一成的可被 agent 解析的领域句柄(见 ReferenceHandle)。
+     * 由所属源 describeReferenceHandle 解码;发给 agent 的 `mention://workspace-reference/...`
+     * 由它构造,替代把文件路径全部展开。源不支持解码时为 null。
+     */
+    handle: ReferenceHandle | null;
+}
+interface ReferenceConfirmGroupedResult {
+    /** 单独选中的文件 + 非 navigable 源的文件夹(保持单条引用)。 */
+    files: SelectedReference[];
+    /** 每个 navigable 源文件夹一项,文件已折叠在内。 */
+    bundles: ReferenceConfirmBundle[];
+}
 interface ReferenceSourcePickerController {
     readonly store: ReferenceSourcePickerSnapshot;
     getSnapshot(): ReferenceSourcePickerSnapshot;
@@ -135,13 +173,43 @@ interface ReferenceSourcePickerController {
     close(): void;
     reset(): void;
     setActiveSource(sourceId: string): void;
+    /**
+     * 把「定位目标」解析为从源根到目标的真实 ReferenceNode 路径(root → leaf)。
+     * 纯数据解析:逐层 listChildren 找到真实节点(带 displayName 等),不改动任何 UI/导航态。
+     * 源不支持定位 / 未找到时返回部分路径(可能为空)。供「打开即定位」一次性应用。
+     */
+    locatePath(target: ReferenceLocateTarget): Promise<ReferenceNode[]>;
     /** 确保某节点(null=当前源根)的子节点已加载(抽屉式导航进入用,不切换展开态)。 */
     ensureChildren(node: ReferenceNode | null): void;
     /** 确保指定源的根层级已加载(左栏可同时展开多源时,为非 active 源预载分组)。 */
     ensureSourceRoot(sourceId: string): void;
+    /** 幂等展开某 folder 并确保其子节点已加载(定位目标默认展开用)。 */
+    expandNode(node: ReferenceNode): void;
     toggleNode(node: ReferenceNode): void;
     loadMore(node: ReferenceNode | null): void;
-    setSearchQuery(query: string): void;
+    /**
+     * 拉取指定源根层级的下一页(左栏二级分组分页用)。
+     * 与 loadMore(null) 的区别:后者只作用于 active 源;本方法显式指定源,
+     * 使左栏任一源(无论是否 active)都能继续拉取其分组。
+     */
+    loadMoreSourceRoot(sourceId: string): void;
+    /**
+     * 设置搜索关键词。scopeNodeId 指定把搜索限定在 active 源内某个二级分组(左栏选中分组)
+     * 的节点 nodeId;缺省/null = 跨整源搜索。query 与 filters 任一非空即进入查询(平铺)态。
+     */
+    setSearchQuery(query: string, scopeNodeId?: string | null): void;
+    /**
+     * 设置已选文件类型筛选分类(全局统一口径)。与 setSearchQuery 同构:
+     * 与现有关键词一起构成查询并(去抖)重搜;query 与 filters 同时为空才回浏览态。
+     */
+    setSearchFilters(filters: string[], scopeNodeId?: string | null): void;
+    /** 搜索进行中切换左栏分组时更新限定范围并以现有关键词/筛选重搜。 */
+    setSearchScope(scopeNodeId: string | null): void;
+    /**
+     * 加载更多查询结果(增长式分页):以同一关键词/筛选、更大的 limit 立即重查,
+     * 结果整体替换(保留旧结果直到新结果就绪)。无更多 / 在途 / 非查询态时 no-op。
+     */
+    loadMoreSearch(): void;
     toggleSelection(node: ReferenceNode): void;
     clearSelection(): void;
     /**
@@ -152,6 +220,11 @@ interface ReferenceSourcePickerController {
      * 含异步枚举,故返回 Promise;结果按 path 去重、保序。
      */
     confirm(): Promise<SelectedReference[]>;
+    /**
+     * 与 confirm 同源,但保留分组:navigable 源的每个选中文件夹折叠成一个 bundle
+     * (文件已递归展开在内),其余作为单条文件。供「文件夹 = 一个节点」的插入形态用。
+     */
+    confirmGrouped(): Promise<ReferenceConfirmGroupedResult>;
 }
 interface CreateReferenceSourcePickerControllerInput {
     aggregator: ReferenceSourceAggregator;

package/dist/react/index.js

@@ -9,8 +9,8 @@ import {
   prefetchReferenceTree,
   useWorkspaceFileReferencePickerView,
   workspaceFileReferenceDefaultExpandedDepth
-} from "../chunk-CD3YNHYJ.js";
-import "../chunk-7C3RZYQE.js";
+} from "../chunk-LJZYN4MH.js";
+import "../chunk-JURSITRX.js";
 export {
   ROOT_CHILDREN_KEY,
   collectVisibleTreeEntries,

package/dist/{referenceSourceAggregator-yyyLVOPi.d.ts → referenceSourceAggregator-B8ATnJOZ.d.ts}

@@ -31,6 +31,11 @@ interface ReferenceSourceAggregator {
     open(scope: ReferenceScope, node: ReferenceNode): Promise<void>;
     readPreview(scope: ReferenceScope, node: ReferenceNode): Promise<ReferencePreview | null>;
     resolveSelection(node: ReferenceNode): SelectedReference;
+    /**
+     * 把语义定位参数解析为某源内从根到目标分组的 NodeRef 路径(root → leaf)。
+     * 源未实现 locateTarget / 未找到时返回 null。需先 listSources/listRoot 触发源加载。
+     */
+    locateTarget(scope: ReferenceScope, sourceId: string, params: Record<string, string>): Promise<NodeRef[] | null>;
     /** 取已加载的源(用于读取 capabilities/metadata)。需先 listRoot 触发加载。 */
     getLoadedSource(sourceId: string): ReferenceSourceService | undefined;
 }

package/dist/ui/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { WorkspaceFileReferenceCopy, WorkspaceFileReferenceAdapter, WorkspaceFileReference } from '../contracts/index.js';
+import { WorkspaceFileReferenceCopy, WorkspaceFileReferenceAdapter, WorkspaceFileReference, ReferenceHandle, ReferenceLocateTarget } from '../contracts/index.js';
 import { JSX } from 'react';
-import { R as ReferenceSourceAggregator } from '../referenceSourceAggregator-yyyLVOPi.js';
+import { R as ReferenceSourceAggregator } from '../referenceSourceAggregator-B8ATnJOZ.js';
 
 interface WorkspaceFileReferencePickerProps {
     copy: WorkspaceFileReferenceCopy;
@@ -10,18 +10,51 @@ interface WorkspaceFileReferencePickerProps {
     onClose: () => void;
     onConfirm: (refs: WorkspaceFileReference[]) => void;
     open: boolean;
+    /**
+     * When true, the dialog is rendered inline (non-portaled, absolutely
+     * positioned) so it stays clipped within the nearest positioned ancestor —
+     * e.g. an agent GUI node window — instead of covering the whole viewport.
+     * Defaults to false (portal to body + cover the viewport).
+     */
+    scoped?: boolean;
     workspaceId: string;
 }
-declare function WorkspaceFileReferencePicker({ copy, fileAdapter, initialPath, onClose, onConfirm, open, workspaceId }: WorkspaceFileReferencePickerProps): react_jsx_runtime.JSX.Element | null;
+declare function WorkspaceFileReferencePicker({ copy, fileAdapter, initialPath, onClose, onConfirm, open, scoped, workspaceId }: WorkspaceFileReferencePickerProps): react_jsx_runtime.JSX.Element;
+
+/** 一个 navigable 源文件夹的折叠选区(文件已映射为 WorkspaceFileReference)。 */
+interface ReferenceBundleSelection {
+    sourceId: string;
+    nodeId: string;
+    displayName: string;
+    iconUrl?: string | null;
+    /**
+     * 可被 agent 解析的领域句柄(见 ReferenceHandle)。发给 agent 的
+     * `mention://workspace-reference/...` 由它构造;源未解码出句柄时为 null。
+     */
+    handle: ReferenceHandle | null;
+    /** 该 bundle 下文件数(展示用,取节点 childCount;不再展开文件)。 */
+    fileCount: number;
+}
+interface ReferenceGroupedSelection {
+    files: WorkspaceFileReference[];
+    bundles: ReferenceBundleSelection[];
+}
 
 interface ReferenceSourcePickerProps {
     aggregator: ReferenceSourceAggregator;
     copy: WorkspaceFileReferenceCopy;
+    /** 可选:打开时直达某事项/应用分组(展开并聚焦)。 */
+    initialTarget?: ReferenceLocateTarget | null;
     onClose: () => void;
     onConfirm: (refs: WorkspaceFileReference[]) => void;
+    /**
+     * 可选:启用「文件夹=一个 bundle 节点」确认形态。提供时确认走 confirmGrouped,
+     * navigable 源的选中文件夹折叠成 bundle 回调,其余仍为单条文件。
+     */
+    onConfirmBundles?: (result: ReferenceGroupedSelection) => void;
     open: boolean;
     workspaceId: string;
 }
-declare function ReferenceSourcePicker({ aggregator, copy, onClose, onConfirm, open, workspaceId }: ReferenceSourcePickerProps): JSX.Element | null;
+declare function ReferenceSourcePicker({ aggregator, copy, initialTarget, onClose, onConfirm, onConfirmBundles, open, workspaceId }: ReferenceSourcePickerProps): JSX.Element | null;
 
-export { ReferenceSourcePicker, type ReferenceSourcePickerProps, WorkspaceFileReferencePicker, type WorkspaceFileReferencePickerProps };
+export { type ReferenceBundleSelection, type ReferenceGroupedSelection, ReferenceSourcePicker, type ReferenceSourcePickerProps, WorkspaceFileReferencePicker, type WorkspaceFileReferencePickerProps };