@tutti-os/workspace-file-reference 0.0.13 → 0.0.15

package/dist/index.js

@@ -1,7 +1,43 @@
 import {
+  REFERENCE_FILTER_CATEGORIES,
+  SOURCE_ROOT_NODE_ID,
+  WORKSPACE_ROOT_GROUP_NODE_ID,
+  appendReferencePage,
+  base64UrlDecode,
+  base64UrlEncode,
+  categoryOfFileName,
+  createReferenceListSource,
+  createReferenceSourceAggregator,
+  createStaticReferenceSourceRegistry,
+  dedupeReferenceNodes,
+  isSourceRootNode,
+  matchesFilterCategories,
+  nodeKey,
+  nodeRefKey,
+  normalizeReferenceNodeKind,
+  selectedReferenceToWorkspaceFileReference,
+  sortReferenceNodes,
   uniqueWorkspaceFileReferences
-} from "./chunk-PAR2R2G5.js";
+} from "./chunk-HRC2MZ5H.js";
 export {
+  REFERENCE_FILTER_CATEGORIES,
+  SOURCE_ROOT_NODE_ID,
+  WORKSPACE_ROOT_GROUP_NODE_ID,
+  appendReferencePage,
+  base64UrlDecode,
+  base64UrlEncode,
+  categoryOfFileName,
+  createReferenceListSource,
+  createReferenceSourceAggregator,
+  createStaticReferenceSourceRegistry,
+  dedupeReferenceNodes,
+  isSourceRootNode,
+  matchesFilterCategories,
+  nodeKey,
+  nodeRefKey,
+  normalizeReferenceNodeKind,
+  selectedReferenceToWorkspaceFileReference,
+  sortReferenceNodes,
   uniqueWorkspaceFileReferences
 };
 //# sourceMappingURL=index.js.map

package/dist/react/index.d.ts

@@ -1,6 +1,7 @@
-import { WorkspaceFileReference, WorkspaceFileReferencePrefetchReason, WorkspaceFileReferencePrefetchState, WorkspaceFileReferenceTreeSnapshot, WorkspaceFileReferenceAdapter } from '../contracts/index.js';
+import { WorkspaceFileReference, WorkspaceFileReferencePrefetchReason, WorkspaceFileReferencePrefetchState, WorkspaceFileReferenceTreeSnapshot, WorkspaceFileReferenceAdapter, ReferenceScope, ReferenceNode, ReferenceLocateTarget, SelectedReference } 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-B8ATnJOZ.js';
 
 declare const workspaceFileReferenceDefaultExpandedDepth = 4;
 interface WorkspaceFileReferenceDirectoryState {
@@ -89,4 +90,135 @@ declare function useWorkspaceFileReferencePickerView({ fileAdapter, initialPath,
     toggleRef: (ref: WorkspaceFileReference) => void;
 };
 
-export { type UseWorkspaceFileReferencePickerViewInput, type WorkspaceFileReferenceDirectoryState, type WorkspaceFileReferencePreviewState, collectVisibleTreeEntries, createWorkspaceFileReferenceDirectoryStateFromSnapshot, mergeExpandedFolderPaths, mergePrefetchedDirectoryState, normalizeDirectoryPath, prefetchReferenceTree, useWorkspaceFileReferencePickerView, workspaceFileReferenceDefaultExpandedDepth };
+/**
+ * node-keyed 多源 picker 的逻辑层 controller(顶部分源 tab)。
+ * 独立于现有 WorkspaceFileReferencePickerController —— issue-manager 不受影响。
+ * 设计见 docs/architecture/agent-reference-source-services.md §2 / §3。
+ *
+ * 本层只管:tabs、per-source inline 展开树(node-keyed)、cursor 加载更多、
+ * per-tab 搜索、跨 tab 选中集、confirm。预览/打开留待 UI 接入步骤。
+ */
+type ReferenceSourcePickerMode = "browse" | "search";
+interface ReferenceSourceNodeChildrenState {
+    /** 已累积的子节点(含多页 append)。 */
+    entries: ReferenceNode[];
+    nextCursor: string | null;
+    loaded: boolean;
+    loading: boolean;
+    error: Error | null;
+}
+interface ReferenceSourceTabState {
+    sourceId: string;
+    expandedKeys: Record<string, boolean>;
+    /** key = nodeRefKey;源根用 ROOT_CHILDREN_KEY。 */
+    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;
+}
+interface ReferenceSourcePickerSnapshot {
+    isLoadingTabs: boolean;
+    tabsError: Error | null;
+    tabs: ReferenceSourceTab[];
+    activeSourceId: string | null;
+    bySource: Record<string, ReferenceSourceTabState>;
+    /** 跨 tab 累积的选中文件节点,按选中顺序。 */
+    selection: ReferenceNode[];
+}
+/** confirmGrouped 的产物:一个 navigable 源文件夹 = 一个 bundle(保留分组)。 */
+interface ReferenceConfirmBundle {
+    /** 被选中的文件夹节点(提供 displayName / iconUrl / ref 作为 bundle 身份)。 */
+    root: ReferenceNode;
+    /** 该文件夹递归展开后的全部文件。 */
+    files: SelectedReference[];
+}
+interface ReferenceConfirmGroupedResult {
+    /** 单独选中的文件 + 非 navigable 源的文件夹(保持单条引用)。 */
+    files: SelectedReference[];
+    /** 每个 navigable 源文件夹一项,文件已折叠在内。 */
+    bundles: ReferenceConfirmBundle[];
+}
+interface ReferenceSourcePickerController {
+    readonly store: ReferenceSourcePickerSnapshot;
+    getSnapshot(): ReferenceSourcePickerSnapshot;
+    open(): void;
+    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;
+    toggleNode(node: ReferenceNode): void;
+    loadMore(node: ReferenceNode | null): 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;
+    /**
+     * 选中归一。文件 → 单条;文件夹按所属源区分:
+     *  - 本地(非 navigable)源:保持单条 folder 引用(filesystem 路径与目录一一对应);
+     *  - app/issue(navigable)源:其文件夹下文件在 filesystem 里不一定落在该目录路径下,
+     *    故递归 listChildren 枚举,展开成多条文件引用。
+     * 含异步枚举,故返回 Promise;结果按 path 去重、保序。
+     */
+    confirm(): Promise<SelectedReference[]>;
+    /**
+     * 与 confirm 同源,但保留分组:navigable 源的每个选中文件夹折叠成一个 bundle
+     * (文件已递归展开在内),其余作为单条文件。供「文件夹 = 一个节点」的插入形态用。
+     */
+    confirmGrouped(): Promise<ReferenceConfirmGroupedResult>;
+}
+interface CreateReferenceSourcePickerControllerInput {
+    aggregator: ReferenceSourceAggregator;
+    scope: ReferenceScope;
+    searchDebounceMs?: number;
+}
+/** 源根 children 的 key(node===null 时)。 */
+declare const ROOT_CHILDREN_KEY: string;
+declare function createReferenceSourcePickerController(input: CreateReferenceSourcePickerControllerInput): ReferenceSourcePickerController;
+
+export { type CreateReferenceSourcePickerControllerInput, ROOT_CHILDREN_KEY, type ReferenceSourceNodeChildrenState, type ReferenceSourcePickerController, type ReferenceSourcePickerMode, type ReferenceSourcePickerSnapshot, type ReferenceSourceTabState, type UseWorkspaceFileReferencePickerViewInput, type WorkspaceFileReferenceDirectoryState, type WorkspaceFileReferencePreviewState, collectVisibleTreeEntries, createReferenceSourcePickerController, createWorkspaceFileReferenceDirectoryStateFromSnapshot, mergeExpandedFolderPaths, mergePrefetchedDirectoryState, normalizeDirectoryPath, prefetchReferenceTree, useWorkspaceFileReferencePickerView, workspaceFileReferenceDefaultExpandedDepth };

package/dist/react/index.js

@@ -1,5 +1,7 @@
 import {
+  ROOT_CHILDREN_KEY,
   collectVisibleTreeEntries,
+  createReferenceSourcePickerController,
   createWorkspaceFileReferenceDirectoryStateFromSnapshot,
   mergeExpandedFolderPaths,
   mergePrefetchedDirectoryState,
@@ -7,10 +9,12 @@ import {
   prefetchReferenceTree,
   useWorkspaceFileReferencePickerView,
   workspaceFileReferenceDefaultExpandedDepth
-} from "../chunk-LS7P3J6Z.js";
-import "../chunk-PAR2R2G5.js";
+} from "../chunk-KSK6PILG.js";
+import "../chunk-HRC2MZ5H.js";
 export {
+  ROOT_CHILDREN_KEY,
   collectVisibleTreeEntries,
+  createReferenceSourcePickerController,
   createWorkspaceFileReferenceDirectoryStateFromSnapshot,
   mergeExpandedFolderPaths,
   mergePrefetchedDirectoryState,

package/dist/referenceSourceAggregator-B8ATnJOZ.d.ts

@@ -0,0 +1,47 @@
+import { ReferenceScope, ReferenceSourceService, ReferenceNode, NodeRef, ListChildrenResult, SearchInput, SearchResult, ReferencePreview, SelectedReference, ReferenceSourceRegistry } from './contracts/index.js';
+
+/**
+ * 多源聚合器:根层级 = 每个可用源一个 folder 节点;其余按 node.ref.sourceId 委派。
+ * 设计见 docs/architecture/agent-reference-source-services.md §3 / §4.4。
+ */
+/**
+ * 源根节点的 nodeId 哨兵。由聚合器创建源根节点时使用;
+ * 任何真实源都不会产出 nodeId 等于此值的子节点(workspace 源 nodeId 是路径,
+ * app 源 nodeId 以 "app:" 开头),因此路由无歧义。
+ */
+declare const SOURCE_ROOT_NODE_ID = "\0source-root";
+/** 顶部 tab 的描述(source 身份 + 能力)。 */
+interface ReferenceSourceTab {
+    sourceId: string;
+    label: string;
+    icon?: string;
+    capabilities: ReferenceSourceService["capabilities"];
+}
+interface ReferenceSourceAggregator {
+    /** 顶部 tab 列表:每个可用源一个 tab(已过滤 isAvailable、按 order 排序)。 */
+    listSources(scope: ReferenceScope): Promise<ReferenceSourceTab[]>;
+    /** (备用,单树多根形态)根层级:每个可用源一个 folder 节点。 */
+    listRoot(scope: ReferenceScope): Promise<ReferenceNode[]>;
+    listChildren(scope: ReferenceScope, node: NodeRef, input?: {
+        cursor?: string | null;
+        filter?: string | null;
+        signal?: AbortSignal;
+    }): Promise<ListChildrenResult>;
+    search(scope: ReferenceScope, sourceId: string, input: SearchInput): Promise<SearchResult>;
+    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;
+}
+declare function isSourceRootNode(ref: NodeRef): boolean;
+declare function createReferenceSourceAggregator(registry: ReferenceSourceRegistry): ReferenceSourceAggregator;
+/** 静态 registry:持有一组源,按 isAvailable 过滤、按 order 排序。 */
+declare function createStaticReferenceSourceRegistry(sources: readonly ReferenceSourceService[]): ReferenceSourceRegistry;
+
+export { type ReferenceSourceAggregator as R, SOURCE_ROOT_NODE_ID as S, type ReferenceSourceTab as a, createStaticReferenceSourceRegistry as b, createReferenceSourceAggregator as c, isSourceRootNode as i };

package/dist/ui/index.d.ts

@@ -1,5 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { WorkspaceFileReferenceCopy, WorkspaceFileReferenceAdapter, WorkspaceFileReference } from '../contracts/index.js';
+import { WorkspaceFileReferenceCopy, WorkspaceFileReferenceAdapter, WorkspaceFileReference, ReferenceLocateTarget } from '../contracts/index.js';
+import { JSX } from 'react';
+import { R as ReferenceSourceAggregator } from '../referenceSourceAggregator-B8ATnJOZ.js';
 
 interface WorkspaceFileReferencePickerProps {
     copy: WorkspaceFileReferenceCopy;
@@ -8,8 +10,45 @@ 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;
 
-export { WorkspaceFileReferencePicker, type WorkspaceFileReferencePickerProps };
+/** 一个 navigable 源文件夹的折叠选区(文件已映射为 WorkspaceFileReference)。 */
+interface ReferenceBundleSelection {
+    sourceId: string;
+    nodeId: string;
+    displayName: string;
+    iconUrl?: string | null;
+    files: WorkspaceFileReference[];
+}
+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, initialTarget, onClose, onConfirm, onConfirmBundles, open, workspaceId }: ReferenceSourcePickerProps): JSX.Element | null;
+
+export { type ReferenceBundleSelection, type ReferenceGroupedSelection, ReferenceSourcePicker, type ReferenceSourcePickerProps, WorkspaceFileReferencePicker, type WorkspaceFileReferencePickerProps };