@openviking/react 0.1.2 → 0.1.3

package/dist/components/file-browser-entries/style.css

@@ -0,0 +1,155 @@
+.ov-agent-connect, .ov-divider, .ov-file-browser, .ov-file-browser-entries, .ov-file-preview, .ov-file-tree, .ov-module-placeholder, .ov-popover, .ov-scope-switcher, .ov-tooltip, .ov-tui, .ov-viking-bot, .ov-viking-bot__interaction {
+  --ov-ui-primary-default: #5252ff;
+  --ov-ui-primary-hover-default: #7075ff;
+  --ov-ui-primary-active-default: #3833d2;
+  --ov-ui-primary-light-default: #f5f7ff;
+  --ov-ui-connect-glow-warm-default: #ff952b0a;
+  --ov-ui-connect-glow-pink-default: #fb4fbc0f;
+  --ov-ui-connect-glow-pink-soft-default: #fb4fbc0a;
+  --ov-ui-on-primary-default: #fff;
+  --ov-ui-text-1-default: #0b0b0f;
+  --ov-ui-text-2-default: #3f3f51;
+  --ov-ui-text-3-default: #6e718c;
+  --ov-ui-text-description-default: #0006;
+  --ov-ui-text-disabled-default: #a5a7bb;
+  --ov-ui-border-1-default: #f0f2fa;
+  --ov-ui-border-2-default: #e1e4f2;
+  --ov-ui-border-3-default: #d7daea;
+  --ov-ui-bg-1-default: #fff;
+  --ov-ui-bg-3-default: #f7f8fd;
+  --ov-ui-bg-4-default: #f6f7fa;
+  --ov-ui-bg-5-default: #f1f2f9;
+  --ov-ui-status-success-default: #1f9d55;
+  --ov-ui-shadow-default: #0f172a;
+  --ov-ui-focus-default: #5252ff;
+  --ov-ui-fill-hover-default: #f1f2f9;
+  --ov-ui-status-error-default: #c43838;
+  --ov-ui-warning-default: #b26a00;
+  --ov-ui-warning-light-default: #fff0b3;
+  --ov-ui-tooltip-bg-default: #1f2329;
+  --ov-ui-tooltip-text-default: #fff;
+}
+
+.dark .ov-agent-connect, .dark .ov-divider, .dark .ov-file-browser, .dark .ov-file-browser-entries, .dark .ov-file-preview, .dark .ov-file-tree, .dark .ov-module-placeholder, .dark .ov-popover, .dark .ov-scope-switcher, .dark .ov-tooltip, .dark .ov-tui, .dark .ov-viking-bot, .dark .ov-viking-bot__interaction {
+  --ov-ui-primary-default: #5f5fff;
+  --ov-ui-primary-hover-default: #7075ff;
+  --ov-ui-primary-active-default: #4242ba;
+  --ov-ui-primary-light-default: #1a1632;
+  --ov-ui-connect-glow-warm-default: #ff952b05;
+  --ov-ui-connect-glow-pink-default: #fb4fbc08;
+  --ov-ui-connect-glow-pink-soft-default: #fb4fbc05;
+  --ov-ui-text-1-default: #c7ccd6;
+  --ov-ui-text-2-default: #9da3af;
+  --ov-ui-text-3-default: #737a87;
+  --ov-ui-text-description-default: #fff6;
+  --ov-ui-text-disabled-default: #42464e;
+  --ov-ui-border-1-default: #23252a;
+  --ov-ui-border-2-default: #2e3138;
+  --ov-ui-border-3-default: #3a3d45;
+  --ov-ui-bg-1-default: #131416;
+  --ov-ui-bg-3-default: #1b1d21;
+  --ov-ui-bg-4-default: #202227;
+  --ov-ui-bg-5-default: #23252a;
+  --ov-ui-focus-default: #5f5fff;
+  --ov-ui-fill-hover-default: #23252a;
+  --ov-ui-status-error-default: #ff9595;
+  --ov-ui-warning-default: #e0a04a;
+  --ov-ui-warning-light-default: #3a2f14;
+  --ov-ui-tooltip-bg-default: #2a2d33;
+  --ov-ui-tooltip-text-default: #f0f1f3;
+}
+
+.ov-agent-connect {
+  --ov-ui-connect-card-default: #fbfbfc;
+  --ov-ui-connect-tabs-default: #f7f7f9;
+  --ov-ui-connect-selected-default: #f3f4f7;
+  --ov-ui-connect-border-default: #edeef2;
+  --ov-ui-connect-outline-default: #e1e3ea;
+  --ov-ui-connect-muted-default: #787c91;
+  --ov-ui-connect-notice-default: #2e2984;
+}
+
+.dark .ov-agent-connect {
+  --ov-ui-connect-card-default: var(--ov-ui-bg-3-default);
+  --ov-ui-connect-tabs-default: var(--ov-ui-bg-3-default);
+  --ov-ui-connect-selected-default: var(--ov-ui-bg-4-default);
+  --ov-ui-connect-border-default: var(--ov-ui-border-1-default);
+  --ov-ui-connect-outline-default: var(--ov-ui-border-2-default);
+  --ov-ui-connect-muted-default: var(--ov-ui-text-3-default);
+  --ov-ui-connect-notice-default: var(--ov-ui-text-2-default);
+}
+
+.ov-divider {
+  box-sizing: border-box;
+  display: block;
+}
+
+.ov-file-browser-entries {
+  --ov-file-browser-entries-height: 32px;
+  box-sizing: border-box;
+  height: var(--ov-file-browser-entries-height);
+  background: color-mix(in srgb,
+    var(--ov-ui-color-primary, var(--ov-ui-primary-default, #5252ff)) 6%,
+    var(--ov-ui-color-bg-1, var(--ov-ui-bg-1-default, #fff)));
+  border-radius: 8px;
+  justify-content: center;
+  align-items: center;
+  gap: 6px;
+  display: flex;
+  overflow: hidden;
+}
+
+.ov-file-browser-entries__entry {
+  min-width: 1px;
+  height: var(--ov-file-browser-entries-height);
+  color: var(--ov-ui-color-primary, var(--ov-ui-primary-default, #5252ff));
+  font: inherit;
+  letter-spacing: .039px;
+  white-space: nowrap;
+  cursor: pointer;
+  background: none;
+  border: 0;
+  border-radius: 6px;
+  flex: 1 0 0;
+  justify-content: center;
+  align-items: center;
+  gap: 6px;
+  padding: 0;
+  font-size: 13px;
+  font-weight: 500;
+  line-height: 22px;
+  transition: background-color .16s;
+  display: inline-flex;
+  overflow: hidden;
+}
+
+.ov-file-browser-entries__entry:hover:not(:disabled) {
+  background: color-mix(in srgb,
+    var(--ov-ui-color-primary, var(--ov-ui-primary-default, #5252ff)) 10%,
+    transparent);
+}
+
+.ov-file-browser-entries__entry:focus-visible {
+  outline: 2px solid
+    var(--ov-ui-color-focus, var(--ov-ui-focus-default, #5252ff));
+  outline-offset: -2px;
+}
+
+.ov-file-browser-entries__entry:disabled {
+  color: var(--ov-ui-color-text-disabled, var(--ov-ui-text-disabled-default, #a5a7bb));
+  cursor: not-allowed;
+}
+
+.ov-file-browser-entries__icon {
+  flex: none;
+  align-items: center;
+  display: inline-flex;
+}
+
+.ov-file-browser-entries__label {
+  text-overflow: ellipsis;
+  overflow: hidden;
+}
+
+
+

package/dist/components/file-browser-entries/types.d.ts

@@ -0,0 +1,45 @@
+import type { HTMLAttributes } from 'react';
+/**
+ * 文件浏览入口条的文案。两项的文案都可替换，缺省为英文。
+ * Copy of the file browser entry row. Both labels are replaceable, English by
+ * default.
+ */
+export interface FileBrowserEntriesLabels {
+    /** 连接 Agent 的文案。Label of the connect-agent entry. */
+    connectAgent?: string;
+    /** 导入资源的文案。Label of the import-resources entry. */
+    importResources?: string;
+}
+/**
+ * 文件浏览入口条的属性。
+ *
+ * 它固定是两个入口：连接 Agent 与导入资源。宿主只决定显示哪几个、点击后做
+ * 什么，图标、文案、等分排布与两者之间的分隔线都由组件负责——这两项在每个
+ * 宿主下外观都相同，差别只在点击行为。
+ *
+ * 只显示一个入口时不画分隔线：线分隔的是两个相邻项，只剩一个就无从分隔。
+ *
+ * Props of the file browser entry row.
+ *
+ * It is fixed to two entries: connect an agent, import resources. The host only
+ * decides which appear and what a click does; the icons, copy, equal-width layout
+ * and the divider between them belong to the component, because both look the same
+ * under every host and differ only in behaviour.
+ *
+ * With a single entry no divider is drawn: a divider separates two neighbours, and
+ * there is nothing left to separate.
+ */
+export interface FileBrowserEntriesProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+    /**
+     * 连接 Agent 成功后触发。省略时不显示该入口。
+     * Called after the connect-agent entry is clicked. Omit it to hide that entry.
+     */
+    onConnectAgent?: () => void;
+    /**
+     * 导入资源成功后触发。省略时不显示该入口。
+     * Called after the import-resources entry is clicked. Omit it to hide that entry.
+     */
+    onImportResources?: () => void;
+    /** 可替换文案，缺省为英文。Replaceable copy; English by default. */
+    labels?: FileBrowserEntriesLabels;
+}

package/dist/components/file-browser-entries.js

@@ -0,0 +1 @@
+export { FileBrowserEntries } from "../2~0.js";

package/dist/components/file-preview/file-preview-directory.d.ts

@@ -0,0 +1,32 @@
+import type { ViewerHandle, ViewerViewModeOption } from '@ark-design/ui/file-viewer/core';
+import type { FilePreviewActions } from './types.js';
+import type { useFilePreviewEditing } from './use-file-preview-editing.js';
+import type { FilePreviewDirectoryTab, FilePreviewLabels, FilePreviewViewMode } from './types.js';
+/**
+ * 目录页签的正文：标题行之下多一层同级视图切换（L0 摘要 / L1 总览），每一级
+ * 各自是一份 Markdown，走与文件页签相同的渲染路径。
+ *
+ * 这一层属于目录这种实体：文件没有同级视图可切，给它加同样的插槽只会留一个
+ * 永远空着的位置。
+ *
+ * The body of a directory tab: one extra level of sibling switching between
+ * summary levels (L0 / L1) under the header, each level its own Markdown going
+ * through the same rendering path as a file tab.
+ *
+ * That level belongs to the directory entity: a file has no sibling views to
+ * switch, so giving it the same slot would only leave a permanently empty space.
+ */
+export interface FilePreviewDirectoryBodyProps {
+    tab: FilePreviewDirectoryTab;
+    text: Required<FilePreviewLabels>;
+    locale?: 'en-US' | 'zh-CN';
+    actions: FilePreviewActions;
+    editing: ReturnType<typeof useFilePreviewEditing>;
+    viewMode: FilePreviewViewMode;
+    onViewModeChange: (mode: FilePreviewViewMode) => void;
+    onHandleChange: (handle: ViewerHandle | null) => void;
+    onViewModesChange: (modes: readonly ViewerViewModeOption[]) => void;
+    onDownload: () => void;
+    onCancelEditing: () => void;
+}
+export declare function FilePreviewDirectoryBody({ tab, text, locale, actions, editing, viewMode, onViewModeChange, onHandleChange, onViewModesChange, onDownload, onCancelEditing, }: FilePreviewDirectoryBodyProps): import("react").JSX.Element | null;

package/dist/components/file-preview/file-preview-header.d.ts

@@ -1,6 +1,24 @@
-import type { FilePreviewActions, FilePreviewFileTab } from './types.js';
+import type { ReactNode } from 'react';
+import type { FilePreviewActions } from './types.js';
+/**
+ * 标题行需要的最少信息。它按字段而不是按页签类型取值，文件页签与目录页签因此
+ * 共用同一条渲染路径——两者的路径行本来就一样。
+ *
+ * The least a header needs. It reads fields rather than a tab kind, so a file tab
+ * and a directory tab share one rendering path — their path rows are the same.
+ */
 export interface FilePreviewHeaderProps {
-    fileTab: FilePreviewFileTab;
+    /** 完整路径，显示为面包屑；省略时面包屑退化为文件名。 */
+    path?: string;
+    /** 无路径时回落到文件名。Falls back to the file name when there is no path. */
+    fileName: string;
+    /** 能否沿路径向上打开。Whether an ancestor can be opened. */
+    canOpenParent: boolean;
+    /** 标题旁的额外内容。Extra content next to the title. */
+    titleExtra?: ReactNode;
+    /** 标题行动作区，节点或接收上下文的函数。 */
+    /** The header action area: a node, or a function of the actions context. */
+    slotActions?: ReactNode | ((actions: FilePreviewActions) => ReactNode);
     actions: FilePreviewActions;
     text: {
         copyPath: string;
@@ -22,4 +40,4 @@ export interface FilePreviewHeaderProps {
  * body, download, view switch, edit) carry host product semantics and copy, and
  * the host renders them in `slots.actions` from the `actions` context.
  */
-export declare function FilePreviewHeader({ fileTab, actions, text, onOpenParent, }: FilePreviewHeaderProps): import("react").JSX.Element;
+export declare function FilePreviewHeader({ path, fileName, canOpenParent, titleExtra, slotActions, actions, text, onOpenParent, }: FilePreviewHeaderProps): import("react").JSX.Element;

package/dist/components/file-preview/file-preview-panels.d.ts

@@ -0,0 +1,41 @@
+import type { MarkdownAdapterOptions } from '@ark-design/ui/file-viewer/adapters/markdown';
+import type { ViewerHandle, ViewerViewModeOption } from '@ark-design/ui/file-viewer/core';
+import type { HTMLAttributes } from 'react';
+import type { useFilePreviewActions } from './use-file-preview-actions.js';
+import type { FilePreviewActions } from './types.js';
+import type { useFilePreviewEditing } from './use-file-preview-editing.js';
+import type { FilePreviewContentTab, FilePreviewDirectoryTab, FilePreviewFileTab, FilePreviewLabels, FilePreviewTab, FilePreviewViewMode } from './types.js';
+/**
+ * 页签正文的三种渲染分支：内容页签整块交给宿主，目录页签多一层摘要切换，文件
+ * 页签走底座。
+ *
+ * 单独成文件是因为三条分支的参数加起来让主组件超出了行数上限；分支本身仍是
+ * 主组件的一次渲染，没有引入新的状态。
+ *
+ * The three ways a tab body renders: a content tab hands the whole body to the
+ * host, a directory tab adds one summary-switching layer, and a file tab goes
+ * through the base component.
+ *
+ * It lives in its own file because the three branches' parameters pushed the main
+ * component past the line limit; it is still one render of that component and
+ * introduces no state of its own.
+ */
+export interface FilePreviewPanelsProps {
+    contentTab?: FilePreviewContentTab;
+    directoryTab?: FilePreviewDirectoryTab;
+    fileTab?: FilePreviewFileTab;
+    panelProps: HTMLAttributes<HTMLDivElement>;
+    panelClass: string;
+    text: Required<FilePreviewLabels>;
+    locale?: 'en-US' | 'zh-CN';
+    actions: ReturnType<typeof useFilePreviewActions>;
+    actionContext: FilePreviewActions;
+    editing: ReturnType<typeof useFilePreviewEditing>;
+    viewMode: FilePreviewViewMode;
+    setViewMode: (mode: FilePreviewViewMode) => void;
+    onHandleChange: (handle: ViewerHandle | null) => void;
+    onViewModesChange: (modes: readonly ViewerViewModeOption[]) => void;
+    linkClickHandler?: MarkdownAdapterOptions['onLinkClick'];
+    activeTab: FilePreviewTab;
+}
+export declare function FilePreviewPanels({ contentTab, directoryTab, fileTab, panelProps, panelClass, text, locale, actions, actionContext, editing, viewMode, setViewMode, onHandleChange, onViewModesChange, linkClickHandler, activeTab, }: FilePreviewPanelsProps): import("react").JSX.Element | null;

package/dist/components/file-preview/file-preview-state.d.ts

@@ -7,9 +7,16 @@ export declare function EmptyFileState({ text, }: {
 export declare function NoContentState({ text, }: {
     text: Required<FilePreviewLabels>;
 }): import("react").JSX.Element;
-/** 加载态。A loading state. */
-export declare function LoadingState({ text }: {
-    text: Required<FilePreviewLabels>;
+/**
+ * 加载态。只用到 `loading` 一条文案，因此参数收窄到这一项：宿主在正文还没
+ * 取回来时手上没有完整的一套文案，也不该为了显示加载中而编一份。
+ *
+ * A loading state. Only `loading` is read, so the parameter narrows to that one
+ * field: a host that has not received the body yet has no full copy set, and should
+ * not have to invent one just to show that something is loading.
+ */
+export declare function LoadingState({ text, }: {
+    text: Pick<FilePreviewLabels, 'loading'>;
 }): import("react").JSX.Element;
 /** 读取失败态，带重试入口。A read-failure state with a retry entry. */
 export declare function LoadFailedState({ text, description, onRetry, }: {

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

@@ -1,5 +1,6 @@
 import type { FilePreviewComponent } from './types.js';
-export type { FilePreviewActions, FilePreviewComponent, FilePreviewContentTab, FilePreviewEditing, FilePreviewFileTab, FilePreviewFileTabSlots, FilePreviewHandle, FilePreviewHeaderSlots, FilePreviewLabels, FilePreviewOperations, FilePreviewProps, FilePreviewSource, FilePreviewTab, FilePreviewTabBase, FilePreviewViewMode, } from './types.js';
+export { LoadingState } from './file-preview-state.js';
+export type { FilePreviewActions, FilePreviewComponent, FilePreviewContentTab, FilePreviewDirectoryLevel, FilePreviewDirectoryTab, FilePreviewEditing, FilePreviewFileTab, FilePreviewFileTabSlots, FilePreviewHandle, FilePreviewHeaderSlots, FilePreviewLabels, FilePreviewOperations, FilePreviewProps, FilePreviewSource, FilePreviewTab, FilePreviewTabBase, FilePreviewViewMode, } from './types.js';
 /**
  * 文件预览：页签行、内容区标题行与正文组成的外壳，正文由底座按格式渲染。
  *

package/dist/components/file-preview/level-selection.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 目录页签的初始层级：受控值优先，其次是非受控时记下的选择，然后是
+ * `defaultLevelKey`，最后回落到第一级。
+ *
+ * 单列成纯函数是因为它有一条容易漏掉的规则：外壳算出的 `activeLevelKey` 是受控
+ * 值，正文组件因此没有机会用上自己的初值，`defaultLevelKey` 必须在这里就被尊重，
+ * 否则宿主声明的默认层级会被静默改成第一级。
+ *
+ * The initial level of a directory tab: the controlled value first, then the choice
+ * recorded while uncontrolled, then `defaultLevelKey`, and the first level as the last
+ * resort.
+ *
+ * It is a standalone pure function because of one easily missed rule: the
+ * `activeLevelKey` the shell computes is a controlled value, so the body component never
+ * applies its own initial one — `defaultLevelKey` has to be honoured here, or the
+ * host's declared default is silently replaced by the first level.
+ */
+export interface LevelChoiceTab {
+    levels: readonly {
+        key: string;
+    }[];
+    activeLevelKey?: string;
+    defaultLevelKey?: string;
+}
+export declare function initialLevelKey(tab: LevelChoiceTab, remembered: Readonly<Record<string, string>>, tabKey: string): string;

package/dist/components/file-preview/style.css

@@ -1,4 +1,4 @@
-.ov-agent-connect, .ov-file-browser, .ov-file-preview, .ov-file-tree, .ov-module-placeholder, .ov-scope-switcher, .ov-tooltip, .ov-tui, .ov-viking-bot, .ov-viking-bot__interaction {
+.ov-agent-connect, .ov-divider, .ov-file-browser, .ov-file-browser-entries, .ov-file-preview, .ov-file-tree, .ov-module-placeholder, .ov-popover, .ov-scope-switcher, .ov-tooltip, .ov-tui, .ov-viking-bot, .ov-viking-bot__interaction {
   --ov-ui-primary-default: #5252ff;
   --ov-ui-primary-hover-default: #7075ff;
   --ov-ui-primary-active-default: #3833d2;
@@ -30,7 +30,7 @@
   --ov-ui-tooltip-text-default: #fff;
 }
 
-.dark .ov-agent-connect, .dark .ov-file-browser, .dark .ov-file-preview, .dark .ov-file-tree, .dark .ov-module-placeholder, .dark .ov-scope-switcher, .dark .ov-tooltip, .dark .ov-tui, .dark .ov-viking-bot, .dark .ov-viking-bot__interaction {
+.dark .ov-agent-connect, .dark .ov-divider, .dark .ov-file-browser, .dark .ov-file-browser-entries, .dark .ov-file-preview, .dark .ov-file-tree, .dark .ov-module-placeholder, .dark .ov-popover, .dark .ov-scope-switcher, .dark .ov-tooltip, .dark .ov-tui, .dark .ov-viking-bot, .dark .ov-viking-bot__interaction {
   --ov-ui-primary-default: #5f5fff;
   --ov-ui-primary-hover-default: #7075ff;
   --ov-ui-primary-active-default: #4242ba;
@@ -258,7 +258,6 @@
 }
 
 .ov-file-preview__header {
-  border-bottom: 1px solid var(--ov-ui-file-preview-border);
   flex: none;
   justify-content: space-between;
   align-items: center;
@@ -593,6 +592,80 @@
   font-size: 12px;
 }
 
+.ov-file-preview__levels {
+  flex: none;
+  align-items: stretch;
+  gap: 32px;
+  height: 34px;
+  padding: 0 16px;
+  display: flex;
+  position: relative;
+}
+
+.ov-file-preview__level {
+  color: var(--ov-ui-file-preview-text-muted);
+  font: inherit;
+  letter-spacing: .039px;
+  cursor: pointer;
+  background: none;
+  border: 0;
+  align-items: center;
+  padding: 0 0 2px;
+  font-size: 13px;
+  line-height: 22px;
+  transition: color .16s;
+  display: inline-flex;
+}
+
+.ov-file-preview__level:hover {
+  color: var(--ov-ui-file-preview-text);
+}
+
+.ov-file-preview__level[data-active] {
+  color: var(--ov-ui-file-preview-text);
+  font-weight: 500;
+}
+
+.ov-file-preview__level-indicator {
+  background: var(--ov-ui-file-preview-text);
+  border-radius: 1px;
+  height: 2px;
+  transition: transform .2s cubic-bezier(.2, 0, 0, 1), width .2s cubic-bezier(.2, 0, 0, 1);
+  position: absolute;
+  bottom: 0;
+  left: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ov-file-preview__level-indicator {
+    transition: none;
+  }
+}
+
+.ov-file-preview__spinner {
+  box-sizing: border-box;
+  border: 2px solid var(--ov-ui-file-preview-border);
+  border-top-color: var(--ov-ui-file-preview-text-muted);
+  border-radius: 50%;
+  flex: none;
+  width: 16px;
+  height: 16px;
+  animation: .9s linear infinite ov-file-preview-spin;
+  display: inline-block;
+}
+
+@keyframes ov-file-preview-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ov-file-preview__spinner {
+    animation-duration: 2s;
+  }
+}
+
 /*!
  * Copyright (c) 2026 Bytedance, Inc. and its affiliates.
  * SPDX-License-Identifier: MIT

package/dist/components/file-preview/types.d.ts

@@ -112,7 +112,7 @@ export interface FilePreviewTabBase {
  * 文件预览页签或宿主自定义内容页签。
  * A file-preview tab or a tab with host-provided content.
  */
-export type FilePreviewTab = FilePreviewFileTab | FilePreviewContentTab;
+export type FilePreviewTab = FilePreviewFileTab | FilePreviewContentTab | FilePreviewDirectoryTab;
 /**
  * 按文件格式预览 `source` 的页签。
  * A tab that previews `source` according to its file format.
@@ -123,6 +123,18 @@ export interface FilePreviewFileTab extends FilePreviewTabBase {
      * Tab kind discriminator, always `file`.
      */
     kind: 'file';
+    /**
+     * 正文是否还在读取。为真时组件渲染加载态而不是正文，外壳（页签行、路径行）
+     * 照常显示——宿主切换文件时外壳因此不闪，只有正文区在等。
+     *
+     * `source` 在加载中可以为空；组件不会把它判成「空文件」。
+     *
+     * Whether the body is still being read. When true the component renders its
+     * loading state instead of the body while the shell — tab row, path row — stays
+     * put, so a host switching files does not flash the whole area. `source` may be
+     * empty while loading; it is not treated as an empty file.
+     */
+    loading?: boolean;
     /**
      * 要预览的内容及文件信息。
      * The content and file information to preview.
@@ -203,6 +215,93 @@ export interface FilePreviewContentTab extends FilePreviewTabBase {
      */
     content: ReactNode;
 }
+/**
+ * 目录页签：一个目录的若干级摘要，例如 L0 摘要与 L1 总览。
+ *
+ * 它和文件页签的区别在于**正文的层级**：文件页签只有正文；目录页签在标题行
+ * 之下、正文之上还有一层同级视图切换（下划线页签），每一级各自是一份
+ * Markdown。这一层属于目录这种实体，不属于所有文件页签，因此单独开一类，
+ * 而不是给文件页签加一个通用插槽——那样每个文件页签都会多一个它用不到的
+ * 空位。
+ *
+ * A tab for a directory's summary levels, for example its L0 abstract and L1
+ * overview.
+ *
+ * It differs from a file tab in the layering of the body: a file tab has a body
+ * and nothing else, while a directory tab has one more level between the header
+ * and the body — an underlined switch between sibling views, each holding its own
+ * Markdown. That level belongs to the directory entity rather than to every file
+ * tab, so it gets its own kind instead of a generic slot on file tabs, which would
+ * leave every file tab with an empty space it never uses.
+ */
+export interface FilePreviewDirectoryTab extends FilePreviewTabBase {
+    /**
+     * 页签类型标记，固定为 `directory`。
+     * Tab kind discriminator, always `directory`.
+     */
+    kind: 'directory';
+    /**
+     * 摘要是否还在读取。与文件页签同义：为真时正文区显示加载态，外壳照常。
+     * Whether the summary is still being read. Same as a file tab: the body shows
+     * the loading state while the shell stays put.
+     */
+    loading?: boolean;
+    /**
+     * 可切换的摘要层级，至少一级。每级用 `source` 交给组件按格式渲染，与文件
+     * 页签的正文同一条渲染路径。
+     * The summary levels to switch between, at least one. Each level's `source` goes
+     * through the same rendering path as a file tab's body.
+     */
+    levels: readonly [FilePreviewDirectoryLevel, ...FilePreviewDirectoryLevel[]];
+    /**
+     * 受控的当前层级 key。传入时由宿主决定层级，组件只上报切换意图。
+     * The controlled active level key. When given, the host owns the level and the
+     * component only reports switch intent.
+     */
+    activeLevelKey?: string;
+    /**
+     * 非受控时的初始层级 key，省略时选中第一级。
+     * Initial level key when uncontrolled; the first level is selected when omitted.
+     */
+    defaultLevelKey?: string;
+    /**
+     * 当前层级变化后触发，参数为新的层级 key。
+     * Called after the active level changes, with the new level key.
+     */
+    onActiveLevelChange?: (key: string) => void;
+    /**
+     * 目录操作的执行能力，例如沿路径向上打开。省略对应方法时该操作不可用。
+     * Directory operation capabilities, for example opening an ancestor. Omitting a
+     * method makes its operation unavailable.
+     */
+    operations?: FilePreviewOperations;
+    /**
+     * 目录页签的插槽。标题行动作与状态兜底与文件页签一致。
+     * Slots of a directory tab. Header actions and state fallbacks match a file tab.
+     */
+    slots?: FilePreviewFileTabSlots;
+}
+/**
+ * 目录的一级摘要。One summary level of a directory.
+ */
+export interface FilePreviewDirectoryLevel {
+    /**
+     * 层级唯一标识，用于切换与受控状态。
+     * Unique level key, used for switching and controlled state.
+     */
+    key: string;
+    /**
+     * 页签行显示的名称，例如「L0 摘要」。
+     * What the level switch shows, for example "L0 Summary".
+     */
+    label: ReactNode;
+    /**
+     * 该级的正文来源，与文件页签的 `source` 同形，交给组件按格式渲染。
+     * The body source of this level, the same shape as a file tab's `source`, handed
+     * to the component for format rendering.
+     */
+    source: FilePreviewSource;
+}
 /**
  * 文件操作的执行能力。方法返回的 Promise 完成后才触发对应的成功通知。
  * File operation capabilities. The matching success notification fires only

package/dist/components/file-preview/use-directory-level.d.ts

@@ -0,0 +1,30 @@
+import type { FilePreviewDirectoryTab, FilePreviewSource } from './types.js';
+/**
+ * 目录页签当前看的是哪一级摘要。
+ *
+ * 它必须由预览外壳持有，而不是留在正文组件内部：复制正文取的是「用户正在看的
+ * 那一份」，标题行的路径也来自同一级，两处都在外壳这一层取值；留在正文里，复制
+ * 到的永远是第一级。
+ *
+ * 宿主给了 `activeLevelKey` 时以宿主的为准，这里只记非受控页签自己的选择。
+ *
+ * Which summary level of a directory tab is on screen.
+ *
+ * It belongs to the preview shell rather than inside the body component: copy-content
+ * takes "what the user is looking at" and the header path comes from the same level,
+ * both read at this layer — kept in the body, a copy would always take the first
+ * level.
+ *
+ * A host-supplied `activeLevelKey` wins; this only records the choice of an
+ * uncontrolled tab.
+ */
+export interface DirectoryLevelState {
+    /** 实际渲染的那一级。The level actually rendered. */
+    activeLevel?: FilePreviewDirectoryTab['levels'][number];
+    /** 把当前层级固定下来的目录页签，交给正文组件。 */
+    /** The directory tab with the level pinned, handed to the body. */
+    directoryTab?: FilePreviewDirectoryTab;
+    /** 复制路径与复制正文共用的来源。The source shared by copy-path and copy-content. */
+    source?: FilePreviewSource;
+}
+export declare function useDirectoryLevel(tab: FilePreviewDirectoryTab | undefined): DirectoryLevelState;

package/dist/components/file-preview/use-file-preview-actions-context.d.ts

@@ -1,6 +1,6 @@
 import type { useFilePreviewActions } from './use-file-preview-actions.js';
 import type { useFilePreviewEditing } from './use-file-preview-editing.js';
-import type { FilePreviewActions, FilePreviewFileTab, FilePreviewTab, FilePreviewViewMode } from './types.js';
+import type { FilePreviewActions, FilePreviewFileTab, FilePreviewSource, FilePreviewTab, FilePreviewViewMode } from './types.js';
 type Operations = ReturnType<typeof useFilePreviewActions>;
 type Editing = ReturnType<typeof useFilePreviewEditing>;
 /**
@@ -11,9 +11,13 @@ type Editing = ReturnType<typeof useFilePreviewEditing>;
  * and operation state together with the methods that change them, so a
  * `slots.actions` renderer can build its own buttons.
  */
-export declare function useFilePreviewActionsContext({ activeTab, fileTab, viewMode, canSwitchView, setViewMode, editing, operations, }: {
+export declare function useFilePreviewActionsContext({ activeTab, fileTab, currentPath, currentSource, viewMode, canSwitchView, setViewMode, editing, operations, }: {
     activeTab: FilePreviewTab;
     fileTab?: FilePreviewFileTab;
+    /** 当前页签的路径；目录页签也有。The current tab's path; a directory has one too. */
+    currentPath?: string;
+    /** 当前页签的正文来源；目录页签取当前那一级。The body source; a directory uses its active level. */
+    currentSource?: FilePreviewSource;
     viewMode: FilePreviewViewMode;
     canSwitchView: boolean;
     setViewMode: (mode: FilePreviewViewMode) => void;

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

@@ -15,5 +15,5 @@ export declare function useFilePreviewActions(): {
     download: (tab: FilePreviewFileTab) => Promise<void>;
     openUri: (tab: FilePreviewFileTab, uri: string) => Promise<void>;
     copyPath: (tab: FilePreviewTab, path: string) => Promise<boolean>;
-    copyContent: (tab: FilePreviewFileTab, text: string) => Promise<boolean>;
+    copyContent: (tab: FilePreviewTab, text: string) => Promise<boolean>;
 };

package/dist/components/file-preview.js

@@ -1 +1 @@
-export { FilePreview } from "../g~0.js";
+export { FilePreview, LoadingState } from "../30~0.js";