@openviking/react 0.1.1 → 0.1.2

package/dist/components/file-preview/use-file-preview-ids.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 页签与面板的 DOM id 生成器，带实例前缀。
+ *
+ * 只用宿主给的 `tab.key` 拼 id，两个预览同时挂载时会产生重复 id，`aria-controls`
+ * 与 `aria-labelledby` 因此可能指向另一个实例的元素。`useId` 给出每个实例唯一
+ * 的前缀，页签行与面板两侧共用同一份。
+ *
+ * DOM id generators for tabs and panels, prefixed per instance.
+ *
+ * Building ids from the host's `tab.key` alone collides when two previews are
+ * mounted at once, so `aria-controls` and `aria-labelledby` could point at the
+ * other instance's elements. `useId` supplies a unique prefix per instance, shared
+ * by the tab row and the panels.
+ */
+export declare function useFilePreviewIds(activeKey: string): {
+    tabId: (key: string) => string;
+    panelId: (key: string) => string;
+    /** 面板的公共属性：id、role 与 aria 关联，随当前页签变化。 */
+    panelProps: {
+        id: string;
+        role: 'tabpanel';
+        'aria-labelledby': string;
+    };
+};

package/dist/components/file-preview.js

@@ -1,442 +1 @@
-import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { forwardRef, useId, useImperativeHandle, useRef, useState } from "react";
-function FilePreviewBody({ fileTab, contentTab, text, editing, loadingEdit, editFailed, saving, saveFailed, draft, onDraftChange }) {
-    const errorId = useId();
-    if (contentTab) return contentTab.content;
-    if (!fileTab) return null;
-    const { source } = fileTab;
-    if (loadingEdit) return /*#__PURE__*/ jsx("div", {
-        className: "ov-file-preview__state",
-        children: /*#__PURE__*/ jsx("span", {
-            className: "ov-file-preview__muted",
-            children: text.loading
-        })
-    });
-    if (editFailed) return /*#__PURE__*/ jsx("div", {
-        className: "ov-file-preview__state",
-        "data-tone": "error",
-        children: /*#__PURE__*/ jsx("span", {
-            className: "ov-file-preview__muted",
-            children: text.loadFailed
-        })
-    });
-    if (editing && fileTab.editing) return /*#__PURE__*/ jsxs("div", {
-        className: "ov-file-preview__editor",
-        "aria-busy": saving || void 0,
-        children: [
-            saveFailed ? /*#__PURE__*/ jsx("div", {
-                id: errorId,
-                role: "alert",
-                className: "ov-file-preview__save-error",
-                children: text.saveFailed
-            }) : null,
-            /*#__PURE__*/ jsx("textarea", {
-                className: "ov-file-preview__textarea",
-                "aria-label": text.edit,
-                "aria-describedby": saveFailed ? errorId : void 0,
-                readOnly: saving,
-                value: draft,
-                onChange: (event)=>onDraftChange(event.target.value)
-            })
-        ]
-    });
-    if ('string' != typeof source.content) return /*#__PURE__*/ jsx("div", {
-        className: "ov-file-preview__state",
-        children: fileTab.slots?.unsupportedFallback ?? /*#__PURE__*/ jsx("span", {
-            className: "ov-file-preview__muted",
-            children: source.file || source.url ? text.binaryUnsupported : text.unsupported
-        })
-    });
-    return /*#__PURE__*/ jsx("div", {
-        className: "ov-file-preview__text-body",
-        children: /*#__PURE__*/ jsx("pre", {
-            className: "ov-file-preview__pre",
-            children: source.content
-        })
-    });
-}
-function FileIcon() {
-    return /*#__PURE__*/ jsxs("svg", {
-        "aria-hidden": "true",
-        className: "ov-file-preview__icon",
-        viewBox: "0 0 16 16",
-        width: "14",
-        height: "14",
-        children: [
-            /*#__PURE__*/ jsx("path", {
-                d: "M4 1.5h5L12.5 5v9.5h-8.5V1.5Z",
-                fill: "none",
-                stroke: "currentColor",
-                strokeLinejoin: "round",
-                strokeWidth: "1.2"
-            }),
-            /*#__PURE__*/ jsx("path", {
-                d: "M9 1.5V5h3.5",
-                fill: "none",
-                stroke: "currentColor",
-                strokeWidth: "1.2"
-            })
-        ]
-    });
-}
-function CopyIcon() {
-    return /*#__PURE__*/ jsxs("svg", {
-        "aria-hidden": "true",
-        className: "ov-file-preview__action-icon",
-        viewBox: "0 0 16 16",
-        width: "12",
-        height: "12",
-        children: [
-            /*#__PURE__*/ jsx("rect", {
-                x: "5.5",
-                y: "5.5",
-                width: "8",
-                height: "9",
-                rx: "1.2",
-                fill: "none",
-                stroke: "currentColor",
-                strokeWidth: "1.2"
-            }),
-            /*#__PURE__*/ jsx("path", {
-                d: "M10.5 5.5v-2a1 1 0 0 0-1-1h-7a1 1 0 0 0-1 1v8a1 1 0 0 0 1 1h2",
-                fill: "none",
-                stroke: "currentColor",
-                strokeWidth: "1.2"
-            })
-        ]
-    });
-}
-const DEFAULT_LABELS = {
-    copyContent: 'Copy content',
-    copyContentSuccess: 'Content copied',
-    copyContentEmpty: 'Nothing to copy',
-    copyPath: 'Copy path',
-    copyPathSuccess: 'Path copied',
-    openParent: 'Open parent directory',
-    edit: 'Edit',
-    save: 'Save',
-    cancel: 'Cancel',
-    preview: 'Preview',
-    source: 'Source',
-    retry: 'Retry',
-    loadFailed: 'Failed to load the file',
-    saveFailed: 'Failed to save',
-    unsupported: 'Preview is not supported for this format',
-    loading: 'Loading…',
-    download: 'Download',
-    binaryUnsupported: 'Binary preview requires FileViewer'
-};
-function readCopyableText(tab) {
-    const { content } = tab.source;
-    return 'string' == typeof content && content.length > 0 ? content : void 0;
-}
-async function performPreviewOperation(execute, notify) {
-    if (!execute) return;
-    try {
-        await execute();
-    } catch  {
-        return;
-    }
-    notify?.();
-}
-async function copyText(value, onCopied) {
-    try {
-        await navigator.clipboard.writeText(value);
-    } catch  {
-        return;
-    }
-    onCopied?.(value);
-}
-function FilePreviewHeader({ activeTab, fileTab, text, viewMode, editing, loadingEdit, saving, onViewModeChange, onEditStart, onEditCancel, onEditSave }) {
-    const titleExtra = activeTab.slots?.titleExtra;
-    const headerActions = activeTab.slots?.actions;
-    const path = fileTab?.source.path;
-    return /*#__PURE__*/ jsxs("div", {
-        className: "ov-file-preview__header",
-        children: [
-            /*#__PURE__*/ jsxs("div", {
-                className: "ov-file-preview__path-row",
-                children: [
-                    path ? /*#__PURE__*/ jsx("button", {
-                        type: "button",
-                        className: "ov-file-preview__breadcrumb",
-                        onClick: (event)=>{
-                            event.stopPropagation();
-                            performPreviewOperation(fileTab.operations?.openParent ? ()=>fileTab.operations.openParent(path) : void 0, ()=>fileTab.onOpenParent?.(path));
-                        },
-                        disabled: !fileTab.operations?.openParent || saving,
-                        title: path,
-                        children: path
-                    }) : /*#__PURE__*/ jsx("span", {
-                        className: "ov-file-preview__breadcrumb",
-                        children: activeTab.key
-                    }),
-                    path ? /*#__PURE__*/ jsx("button", {
-                        type: "button",
-                        className: "ov-file-preview__action",
-                        "aria-label": text.copyPath,
-                        title: text.copyPath,
-                        onClick: ()=>void copyText(path, fileTab.onCopyPath),
-                        children: /*#__PURE__*/ jsx(CopyIcon, {})
-                    }) : null,
-                    titleExtra ? /*#__PURE__*/ jsx("span", {
-                        className: "ov-file-preview__title-extra",
-                        children: titleExtra
-                    }) : null
-                ]
-            }),
-            /*#__PURE__*/ jsxs("div", {
-                className: "ov-file-preview__header-actions",
-                children: [
-                    fileTab && false !== fileTab.showViewModeSwitch ? /*#__PURE__*/ jsxs("span", {
-                        className: "ov-file-preview__switch",
-                        children: [
-                            /*#__PURE__*/ jsx("button", {
-                                type: "button",
-                                className: "ov-file-preview__switch-item",
-                                "data-active": 'preview' === viewMode || void 0,
-                                onClick: ()=>onViewModeChange('preview'),
-                                children: text.preview
-                            }),
-                            /*#__PURE__*/ jsx("button", {
-                                type: "button",
-                                className: "ov-file-preview__switch-item",
-                                "data-active": 'source' === viewMode || void 0,
-                                onClick: ()=>onViewModeChange('source'),
-                                children: text.source
-                            })
-                        ]
-                    }) : null,
-                    fileTab ? /*#__PURE__*/ jsx("button", {
-                        type: "button",
-                        className: "ov-file-preview__action",
-                        "aria-label": text.copyContent,
-                        title: readCopyableText(fileTab) ? text.copyContent : text.copyContentEmpty,
-                        disabled: !readCopyableText(fileTab),
-                        onClick: ()=>{
-                            const value = readCopyableText(fileTab);
-                            if (value) copyText(value, fileTab.onCopyContent);
-                        },
-                        children: /*#__PURE__*/ jsx(CopyIcon, {})
-                    }) : null,
-                    fileTab?.editing && !editing ? /*#__PURE__*/ jsx("button", {
-                        type: "button",
-                        className: "ov-file-preview__button",
-                        disabled: loadingEdit || !fileTab.editing.loadContent && void 0 === fileTab.source.content && !fileTab.source.file,
-                        onClick: onEditStart,
-                        children: text.edit
-                    }) : null,
-                    fileTab?.editing && editing ? /*#__PURE__*/ jsxs(Fragment, {
-                        children: [
-                            /*#__PURE__*/ jsx("button", {
-                                type: "button",
-                                className: "ov-file-preview__button",
-                                onClick: onEditCancel,
-                                disabled: saving,
-                                children: text.cancel
-                            }),
-                            /*#__PURE__*/ jsx("button", {
-                                type: "button",
-                                className: "ov-file-preview__button--primary",
-                                onClick: onEditSave,
-                                disabled: saving,
-                                children: text.save
-                            })
-                        ]
-                    }) : null,
-                    fileTab?.operations?.download ? /*#__PURE__*/ jsx("button", {
-                        type: "button",
-                        className: "ov-file-preview__button",
-                        onClick: ()=>{
-                            performPreviewOperation(fileTab.operations?.download, fileTab.onDownload);
-                        },
-                        children: text.download
-                    }) : null,
-                    headerActions ? /*#__PURE__*/ jsx("span", {
-                        className: "ov-file-preview__extra-actions",
-                        children: headerActions
-                    }) : null
-                ]
-            })
-        ]
-    });
-}
-function useFilePreviewEditing() {
-    const [editing, setEditing] = useState(false);
-    const [loadingEdit, setLoadingEdit] = useState(false);
-    const [editFailed, setEditFailed] = useState(false);
-    const [saving, setSaving] = useState(false);
-    const [saveFailed, setSaveFailed] = useState(false);
-    const [draft, setDraft] = useState('');
-    const requestId = useRef(0);
-    const loading = useRef(false);
-    const pendingSave = useRef(false);
-    function discard(tab) {
-        requestId.current += 1;
-        loading.current = false;
-        setEditing(false);
-        setLoadingEdit(false);
-        setEditFailed(false);
-        setSaveFailed(false);
-        setDraft('');
-        if (editing && 'file' === tab.kind) tab.editing?.onCancel?.(draft);
-    }
-    async function start(tab) {
-        if (loading.current || pendingSave.current) return;
-        const id = ++requestId.current;
-        loading.current = true;
-        setLoadingEdit(true);
-        setEditFailed(false);
-        setSaveFailed(false);
-        let content;
-        try {
-            content = tab.editing?.loadContent ? await tab.editing.loadContent(tab.source) : tab.source.content ?? await tab.source.file?.text();
-        } catch  {
-            if (id === requestId.current) setEditFailed(true);
-        }
-        if (id !== requestId.current) return;
-        loading.current = false;
-        setLoadingEdit(false);
-        if (void 0 !== content) {
-            setDraft(content);
-            setEditing(true);
-        }
-    }
-    async function save(tab) {
-        if (!editing || !tab.editing || pendingSave.current) return;
-        pendingSave.current = true;
-        setSaving(true);
-        setSaveFailed(false);
-        const value = draft;
-        try {
-            await tab.editing.save(value);
-        } catch  {
-            setSaveFailed(true);
-            return;
-        } finally{
-            pendingSave.current = false;
-            setSaving(false);
-        }
-        setEditing(false);
-        setDraft('');
-        tab.editing.onSave?.(value);
-    }
-    return {
-        editing,
-        loadingEdit,
-        editFailed,
-        saving,
-        saveFailed,
-        draft,
-        discard,
-        start,
-        save,
-        updateDraft: (value)=>{
-            setDraft(value);
-            setSaveFailed(false);
-        }
-    };
-}
-function isFileTab(tab) {
-    return 'file' === tab.kind;
-}
-const file_preview_FilePreview = /*#__PURE__*/ forwardRef(function({ tabs, labels, className, ...rest }, ref) {
-    const text = {
-        ...DEFAULT_LABELS,
-        ...labels
-    };
-    const [activeKey, setActiveKey] = useState(()=>tabs[0].key);
-    const [viewMode, setViewMode] = useState('preview');
-    const editor = useFilePreviewEditing();
-    const activeTab = tabs.find((tab)=>tab.key === activeKey) ?? tabs[0];
-    const tabText = {
-        ...text,
-        ...activeTab.labels
-    };
-    const fileTab = isFileTab(activeTab) ? activeTab : void 0;
-    const contentTab = isFileTab(activeTab) ? void 0 : activeTab;
-    const switchTab = (key)=>{
-        if (key === activeKey) return true;
-        if (editor.saving) return false;
-        setActiveKey(key);
-        setViewMode('preview');
-        editor.discard(activeTab);
-        return true;
-    };
-    useImperativeHandle(ref, ()=>({
-            setActiveTab: (key)=>{
-                const target = tabs.find((tab)=>tab.key === key);
-                if (!target || target.disabled) return false;
-                return switchTab(key);
-            },
-            getActiveTab: ()=>activeKey
-        }));
-    const handleTabClick = (tab)=>{
-        if (tab.disabled) return;
-        switchTab(tab.key);
-    };
-    return /*#__PURE__*/ jsxs("div", {
-        ...rest,
-        className: [
-            'ov-file-preview',
-            className
-        ].filter(Boolean).join(' '),
-        children: [
-            /*#__PURE__*/ jsx("div", {
-                role: "tablist",
-                className: "ov-file-preview__tab-row",
-                children: tabs.map((tab)=>/*#__PURE__*/ jsxs("button", {
-                        type: "button",
-                        role: "tab",
-                        "aria-selected": tab.key === activeTab.key,
-                        disabled: tab.disabled || editor.saving,
-                        className: "ov-file-preview__tab",
-                        onClick: ()=>handleTabClick(tab),
-                        children: [
-                            /*#__PURE__*/ jsx("span", {
-                                className: "ov-file-preview__icon-slot",
-                                children: tab.icon ?? /*#__PURE__*/ jsx(FileIcon, {})
-                            }),
-                            /*#__PURE__*/ jsx("span", {
-                                className: "ov-file-preview__tab-title",
-                                children: tab.title ?? (isFileTab(tab) ? tab.source.fileName : tab.key)
-                            })
-                        ]
-                    }, tab.key))
-            }),
-            /*#__PURE__*/ jsx(FilePreviewHeader, {
-                activeTab: activeTab,
-                fileTab: fileTab,
-                text: tabText,
-                viewMode: viewMode,
-                editing: editor.editing,
-                loadingEdit: editor.loadingEdit,
-                saving: editor.saving,
-                onViewModeChange: setViewMode,
-                onEditStart: ()=>{
-                    if (fileTab) editor.start(fileTab);
-                },
-                onEditCancel: ()=>editor.discard(activeTab),
-                onEditSave: ()=>{
-                    if (fileTab) editor.save(fileTab);
-                }
-            }),
-            /*#__PURE__*/ jsx("div", {
-                className: "ov-file-preview__body",
-                children: /*#__PURE__*/ jsx(FilePreviewBody, {
-                    fileTab: fileTab,
-                    contentTab: contentTab,
-                    text: tabText,
-                    editing: editor.editing,
-                    loadingEdit: editor.loadingEdit,
-                    editFailed: editor.editFailed,
-                    saving: editor.saving,
-                    saveFailed: editor.saveFailed,
-                    draft: editor.draft,
-                    onDraftChange: editor.updateDraft
-                })
-            })
-        ]
-    });
-});
-export { file_preview_FilePreview as FilePreview };
+export { FilePreview } from "../g~0.js";

package/dist/components/file-tree/file-tree-body.d.ts

@@ -1,14 +1,18 @@
 import type { ReactNode } from 'react';
-import type { FileTreeRowContext } from './file-tree-row-context.js';
-import type { FileTreeLabels, FileTreeRow } from './types.js';
+import type { FileTreeRowContext, ResolvedLabels } from './file-tree-row-context.js';
+import type { FileTreeRow } from './types.js';
 export interface FileTreeBodyProps {
     rows: readonly FileTreeRow[];
     isReady: boolean;
-    text: Required<FileTreeLabels>;
+    text: ResolvedLabels;
     loadingFallback?: ReactNode;
     errorFallback?: ReactNode;
     emptyFallback?: ReactNode;
     ctx: FileTreeRowContext;
 }
-/** 树内容区：加载中、整树失败、空态与正常行列表。 */
+/**
+ * 树内容区：首次加载、整树失败、空态与正常行列表。
+ *
+ * The tree body: first load, whole-tree failure, empty state, and the row list.
+ */
 export declare function FileTreeBody({ rows, isReady, text, loadingFallback, errorFallback, emptyFallback, ctx, }: FileTreeBodyProps): import("react").JSX.Element;

package/dist/components/file-tree/file-tree-entry-row.d.ts

@@ -1,6 +1,12 @@
-import { type FileTreeRowContext } from './file-tree-row-context.js';
-import { type FileTreeEntryRow } from './types.js';
-export declare function FileTreeEntryRowView({ row, ctx, }: {
+import type { FileTreeRowContext } from './file-tree-row-context.js';
+import type { FileTreeEntryRow } from './types.js';
+/**
+ * 一条条目行：展开箭头、图标、名称、行内说明、行尾指示器与悬停浮层。
+ *
+ * One entry row: chevron, icon, name, inline description, the row-end indicator
+ * and the hover tooltip.
+ */
+export declare function FileTreeRowView({ row, ctx, }: {
     row: FileTreeEntryRow;
     ctx: FileTreeRowContext;
 }): import("react").JSX.Element;

package/dist/components/file-tree/file-tree-icons.d.ts

@@ -1,8 +1,15 @@
-export declare function Chevron({ expanded }: {
-    expanded: boolean;
+/**
+ * 文件夹图标。展开态与收起态叠放在一起交叉淡入，和宿主一致。
+ *
+ * The folder icon. The open and collapsed states sit stacked and cross-fade,
+ * matching the host tree.
+ */
+export declare function FileTreeFolderIcon({ open }: {
+    open: boolean;
 }): import("react").JSX.Element;
-export declare function FolderIcon({ open }: {
+/** 宿主没有提供 `renderRowIcon` 时的文件图标。Fallback file icon. */
+export declare function FileTreeFileIcon(): import("react").JSX.Element;
+/** 展开箭头，展开时旋转 90°。The expand chevron, rotated when open. */
+export declare function FileTreeChevron({ open }: {
     open: boolean;
 }): import("react").JSX.Element;
-export declare function FileIcon(): import("react").JSX.Element;
-export declare function Spinner(): import("react").JSX.Element;

package/dist/components/file-tree/file-tree-info-labels.d.ts

@@ -0,0 +1,21 @@
+import type { FileTreeInfoKey, FileTreeInfoLabels } from './types.js';
+/**
+ * 内置英文文案。`FileTreeLabels.info` 未提供的键沿用这里的值。
+ *
+ * Built-in English copy. Keys missing from `FileTreeLabels.info` fall back here.
+ */
+export declare const DEFAULT_INFO_LABELS: FileTreeInfoLabels;
+/**
+ * 按宿主的覆盖合并内置文案，键为单位。宿主的空字符串表示该键不显示，因此
+ * 合并时保留空串，由渲染方判断。
+ *
+ * Merges host overrides over the built-in copy, key by key. An empty host string
+ * means "hide this key", so it is kept and the renderer decides.
+ *
+ * Returns the copy of one key, or `undefined` when the key is hidden or has no
+ * copy.
+ */
+export declare function resolveInfoCopy(key: FileTreeInfoKey, hostLabels: FileTreeInfoLabels | undefined): {
+    description?: string;
+    triggerBehavior?: string;
+};

package/dist/components/file-tree/file-tree-info-tooltip.d.ts

@@ -0,0 +1,43 @@
+import type { FileTreeEntryRow, FileTreeInfoLabels } from './types.js';
+export interface FileTreeInfoCopy {
+    /** 行名称，作为浮层标题。Row name, used as the tooltip title. */
+    title: string;
+    /** 说明，已按行内同样的优先级解析。Description, resolved with the same precedence as inline. */
+    description?: string;
+    /** 触发行为，只出现在浮层。Trigger copy, tooltip only. */
+    triggerBehavior?: string;
+    /** 完整路径。Full path. */
+    path: string;
+    /** 浮层里各行的字段名。Field names used inside the tooltip. */
+    fields: {
+        description: string;
+        triggerBehavior: string;
+        path: string;
+    };
+}
+/**
+ * 解析目录浮层要显示的内容，没有可显示内容时返回 `null`。
+ *
+ * 说明按 `row.description` → 内置文案的顺序解析，与行内一致：宿主给了就用宿主的
+ * （含显式空串），没给才用内置。调用方据此决定是否创建浮层外壳，避免留下一个
+ * 只有背景和内边距的空壳。
+ *
+ * Resolves what a directory tooltip should show, or `null` when there is nothing.
+ *
+ * The description resolves as `row.description` then built-in copy, matching the
+ * inline behaviour: a host value wins, including an explicit empty string, and
+ * the built-in copy applies only when absent. The caller uses this to decide
+ * whether to create the tooltip shell, so no empty shell is left behind.
+ */
+export declare function resolveFileTreeInfoCopy(row: FileTreeEntryRow, infoLabels?: FileTreeInfoLabels): FileTreeInfoCopy | null;
+/**
+ * 目录的默认浮层内容：说明、触发行为与路径。九类长期记忆的说明只出现在这里，
+ * 因此这个浮层是它们唯一的展示位置。
+ *
+ * The default tooltip content for a directory: description, trigger copy and
+ * path. The nine long-term-memory keys describe themselves here only, so this
+ * tooltip is the sole place their copy appears.
+ */
+export declare function FileTreeInfoTooltip({ copy }: {
+    copy: FileTreeInfoCopy;
+}): import("react").JSX.Element;

package/dist/components/file-tree/file-tree-info.d.ts

@@ -0,0 +1,29 @@
+import type { FileTreeInfoKey } from './types.js';
+/**
+ * 把 `viking://` 地址拆成小写路径段，忽略协议、查询串与末尾斜杠。
+ *
+ * Splits a `viking://` address into lower-cased segments, ignoring the scheme,
+ * query string and trailing slashes.
+ */
+export declare function splitVikingUri(uri: string): string[];
+/**
+ * 按路径结构判定目录的语义键，判定不出来时返回 `null`。
+ *
+ * 只认路径形状，不认节点类型：同名目录在目录与文件位置上含义相同，由调用方
+ * 决定是否使用。判定规则与产品无关，任何宿主都能直接命中。
+ *
+ * Resolves the semantic key of a directory from its path structure, or `null`
+ * when nothing matches.
+ *
+ * Only the path shape is inspected, not the node type: a name means the same
+ * thing whether it is a directory or a file, and the caller decides whether to
+ * use it. The rules are product-neutral, so any host matches them.
+ */
+export declare function resolveFileTreeInfoKey(uri: string): FileTreeInfoKey | null;
+/**
+ * 该键的说明是否显示在行内。判定不出来时为 `false`。
+ *
+ * Whether the description of this key renders inline; `false` when nothing
+ * matched.
+ */
+export declare function showsInlineDescription(key: FileTreeInfoKey | null): boolean;

package/dist/components/file-tree/file-tree-keyboard.d.ts

@@ -1,10 +1,14 @@
 import type { KeyboardEvent } from 'react';
 import type { FileTreeEntryRow } from './types.js';
-export interface FileTreeKeyHandlerOptions {
+/**
+ * 树行的键盘语义：上下移动焦点，左右展开折叠，回车与空格选中。
+ *
+ * Keyboard semantics for a row: up/down move focus, left/right collapse and
+ * expand, Enter and Space select.
+ */
+export declare function handleRowKeyDown(event: KeyboardEvent<HTMLDivElement>, { root, row, onSelect, onToggleExpand, }: {
     root: HTMLElement | null;
     row: FileTreeEntryRow;
     onSelect?: (row: FileTreeEntryRow) => void;
     onToggleExpand?: (row: FileTreeEntryRow) => void;
-}
-/** 树行的键盘语义：上下移动焦点，左右展开折叠，回车与空格选中。 */
-export declare function handleRowKeyDown(event: KeyboardEvent<HTMLDivElement>, { root, row, onSelect, onToggleExpand }: FileTreeKeyHandlerOptions): void;
+}): void;