@openviking/react 0.1.1 → 0.1.3

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

@@ -0,0 +1,18 @@
+/**
+ * 入口条的两个图标。
+ *
+ * 路径取自控制台 `assets/context-console/` 下的 `connect-agent.svg` 与
+ * `upload.svg`，只把 `vector-effect="non-scaling-stroke"` 去掉——本包的图标按
+ * viewBox 原尺寸渲染，不需要它。描边宽度 1.4 与圆头圆角保持原值。
+ *
+ * The two icons of the entry row.
+ *
+ * The paths come from `connect-agent.svg` and `upload.svg` under the console's
+ * `assets/context-console/`; only `vector-effect="non-scaling-stroke"` is dropped,
+ * because this package renders icons at their viewBox size and does not need it.
+ * The 1.4 stroke width and the round caps and joins are kept as-is.
+ */
+/** 连接 Agent 图标，14 × 14 的插头。Connect-agent icon: a 14 × 14 plug. */
+export declare function ConnectAgentIcon(): import("react").JSX.Element;
+/** 导入资源图标，12 × 12 的方框向上箭头。Import-resources icon: a 12 × 12 box with an up arrow. */
+export declare function ImportResourcesIcon(): import("react").JSX.Element;

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

@@ -0,0 +1,14 @@
+import type { FileBrowserEntriesProps } from './types.js';
+export type { FileBrowserEntriesLabels, FileBrowserEntriesProps, } from './types.js';
+/**
+ * 文件浏览入口条：连接 Agent 与导入资源。
+ *
+ * 两项都省略回调时不渲染任何东西，入口条因此整块消失——宿主既没接连接也没接
+ * 导入时，留一条空白底色只会让人以为还有内容没加载出来。
+ *
+ * The file browser entry row: connect an agent, import resources.
+ *
+ * With both callbacks omitted nothing renders and the row disappears entirely —
+ * leaving an empty tinted strip would suggest something failed to load.
+ */
+export declare function FileBrowserEntries({ onConnectAgent, onImportResources, labels, className, ...rest }: FileBrowserEntriesProps): import("react").JSX.Element | null;

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

@@ -0,0 +1 @@
+export * from './file-browser-entries.js';

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-adapters.d.ts

@@ -0,0 +1,33 @@
+import type { MarkdownAdapterOptions } from '@ark-design/ui/file-viewer/adapters/markdown';
+import type { FileViewerCoreProps } from '@ark-design/ui/file-viewer/core';
+/**
+ * 组件内置的格式集合：文本、文档、图片与音视频。
+ *
+ * 图片是内容式 Adapter，音视频是引用式 Adapter；底座会按 Adapter 声明的读取
+ * 方式自动转换 `source`，宿主只需给出内容、文件或链接，不用区分。
+ *
+ * CAD 与 3D 需要额外的引擎与伴随资源，不放进公共组件。
+ *
+ * 本模块会静态引入底座，因此只能被懒加载的正文模块引用，不能进入包的顶层
+ * 导入链——底座会静态引入浏览器专用组件，顶层导入会破坏服务端渲染。
+ *
+ * The formats the component ships: text, documents, images and media. The image
+ * adapter reads content while the media adapter reads a reference; the base
+ * converts `source` according to the adapter's declared mode, so the host only
+ * supplies content, a file or a URL. CAD and 3D need extra engines and companion
+ * resources, so they stay out of the shared component. This module statically
+ * imports the base, so only the lazily loaded body may reference it: the base
+ * pulls in browser-only packages, and a top-level import would break server
+ * rendering.
+ */
+export declare function createFilePreviewAdapterList({ onLinkClick, }?: {
+    /**
+     * Markdown 正文里的链接被点击时调用。传入后由回调接管导航，底座不再自行
+     * 跳转；只有 Markdown Adapter 支持这个回调，其余格式忽略它。
+     *
+     * Called when a link inside a Markdown body is clicked. Supplying it hands
+     * navigation to the callback and the base no longer jumps on its own. Only the
+     * Markdown adapter supports this; other formats ignore it.
+     */
+    onLinkClick?: MarkdownAdapterOptions['onLinkClick'];
+}): FileViewerCoreProps['adapters'];

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

@@ -1,15 +1,27 @@
-import type { FilePreviewContentTab, FilePreviewFileTab, FilePreviewLabels } from './types.js';
+import type { ViewerHandle, ViewerViewModeOption } from '@ark-design/ui/file-viewer/core';
+import type { MarkdownAdapterOptions } from '@ark-design/ui/file-viewer/adapters/markdown';
+import type { useFilePreviewEditing } from './use-file-preview-editing.js';
+import type { FilePreviewFileTab, FilePreviewLabels, FilePreviewViewMode } from './types.js';
 export interface FilePreviewBodyProps {
-    fileTab?: FilePreviewFileTab;
-    contentTab?: FilePreviewContentTab;
+    fileTab: FilePreviewFileTab;
     text: Required<FilePreviewLabels>;
-    editing: boolean;
-    loadingEdit: boolean;
-    editFailed: boolean;
-    saving: boolean;
-    saveFailed: boolean;
-    draft: string;
-    onDraftChange: (value: string) => void;
+    locale?: 'en-US' | 'zh-CN';
+    viewMode: FilePreviewViewMode;
+    editing: ReturnType<typeof useFilePreviewEditing>;
+    onViewModeChange: (mode: FilePreviewViewMode) => void;
+    onHandleChange: (handle: ViewerHandle | null) => void;
+    onViewModesChange: (modes: readonly ViewerViewModeOption[]) => void;
+    onDownload: () => void;
+    /** Markdown 正文里的链接被点击时调用。 */
+    onLinkClick?: MarkdownAdapterOptions['onLinkClick'];
+    /** 读取失败后退出编辑态。Leaves editing after a failed load. */
+    onCancelEditing: () => void;
 }
-/** 内容区：内容页签原样渲染，文件页签按编辑态、取正文状态与文本降级依次分支。 */
-export declare function FilePreviewBody({ fileTab, contentTab, text, editing, loadingEdit, editFailed, saving, saveFailed, draft, onDraftChange, }: FilePreviewBodyProps): string | number | bigint | boolean | import("react").JSX.Element | Iterable<import("react").ReactNode> | Promise<string | number | bigint | boolean | Iterable<import("react").ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;
+/**
+ * 文件页签的正文：按编辑态、空文件、底座依次短路。内容页签不走这里——它的
+ * 正文整块由宿主渲染。
+ *
+ * The body of a file tab: it short-circuits through editing, empty file and then
+ * the base component. A content tab never reaches this — its body is the host's.
+ */
+export declare function FilePreviewBody({ fileTab, text, locale, viewMode, editing, onViewModeChange, onHandleChange, onViewModesChange, onDownload, onLinkClick, onCancelEditing, }: FilePreviewBodyProps): import("react").JSX.Element;

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

@@ -0,0 +1,16 @@
+import type { PathSegment } from './file-preview-path.js';
+export interface FilePreviewBreadcrumbMenuProps {
+    segments: readonly PathSegment[];
+    canOpen: boolean;
+    disabled: boolean;
+    onOpen: (uri: string) => void;
+}
+/**
+ * 折叠层级的菜单。用 Tooltip 的 `click` 形态承载：点击「…」展开，按 Esc 或
+ * 点外部关闭，浮层渲染到 body，因此不受面包屑容器的布局约束。
+ *
+ * The menu of collapsed levels, carried by Tooltip's `click` shape: clicking "…"
+ * opens it, Escape or a press outside closes it, and because the surface renders
+ * into `body` the breadcrumb's own layout cannot clip it.
+ */
+export declare function FilePreviewBreadcrumbMenu({ segments, canOpen, disabled, onOpen, }: FilePreviewBreadcrumbMenuProps): import("react").JSX.Element;

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

@@ -0,0 +1,21 @@
+import type { PathSegment } from './file-preview-path.js';
+export interface FilePreviewBreadcrumbProps {
+    segments: readonly PathSegment[];
+    title: string;
+    canOpen: boolean;
+    disabled: boolean;
+    onOpen: (uri: string) => void;
+}
+/**
+ * 路径面包屑：祖先逐段可点，放不下时按「保两端、缩中间」折叠。
+ *
+ * 折叠顺序与内部版一致：先保留首段与末段，从紧邻首段的那一级开始逐级收进
+ * 「…」；中间全部收起后仍放不下，才连首段一起收起，只留末段。
+ *
+ * Path breadcrumb: every ancestor is clickable, and overflow collapses by keeping
+ * both ends and shrinking the middle. The first level and the trailing name stay
+ * as long as possible; ancestors are folded into a "…" menu starting next to the
+ * first level, and only when even that does not fit is the first level dropped
+ * too, leaving the trailing name alone.
+ */
+export declare function FilePreviewBreadcrumb({ segments, title, canOpen, disabled, onOpen, }: FilePreviewBreadcrumbProps): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+/**
+ * 路径旁的复制按钮。有 `source.path` 的文件在任何宿主下都需要它，因此内置在
+ * 外壳里，而不是交给宿主渲染。
+ *
+ * The copy-path button beside the path. Any file with a `source.path` needs it
+ * under every host, so it lives in the shell rather than being left to the host.
+ */
+export declare function FilePreviewCopyPath({ label, disabled, onClick, }: {
+    label: string;
+    disabled: boolean;
+    onClick: () => void;
+}): import("react").JSX.Element;

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-editor.d.ts

@@ -0,0 +1,22 @@
+import type { FilePreviewLabels } from './types.js';
+export interface FilePreviewEditorProps {
+    draft: string;
+    text: Required<FilePreviewLabels>;
+    loading: boolean;
+    failed: boolean;
+    saveFailed: boolean;
+    saving: boolean;
+    onChange: (value: string) => void;
+    onCancel: () => void;
+}
+/**
+ * 编辑态正文：纯文本编辑区，不经过底座。
+ *
+ * 编辑区独立于 `FileViewerCore`，因此进入编辑不会重建渲染器，退出编辑也
+ * 不会重新解析内容。
+ *
+ * The editing body: a plain-text area that bypasses the base component. Keeping
+ * it separate means entering or leaving editing never remounts the renderer nor
+ * reparses the content.
+ */
+export declare function FilePreviewEditor({ draft, text, loading, failed, saveFailed, saving, onChange, onCancel, }: FilePreviewEditorProps): import("react").JSX.Element;

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

@@ -0,0 +1,26 @@
+import type { FileViewerCoreProps, ViewerHandle, ViewerViewModeOption } from '@ark-design/ui/file-viewer/core';
+import type { MarkdownAdapterOptions } from '@ark-design/ui/file-viewer/adapters/markdown';
+export interface FilePreviewAdapterOptions {
+    /** 底座交出或收回命令式句柄时调用。 */
+    onHandleChange: (handle: ViewerHandle | null) => void;
+    /** 命中的 Adapter 加载完成时，上报它支持的视图模式。 */
+    onViewModesChange: (modes: readonly ViewerViewModeOption[]) => void;
+    /** Markdown 正文里的链接被点击时调用；传入即由宿主接管导航。 */
+    onLinkClick?: MarkdownAdapterOptions['onLinkClick'];
+}
+/**
+ * 给每个 Adapter 套一层：接住底座交出来的命令式句柄，并上报命中格式支持
+ * 的视图模式。
+ *
+ * 底座没有 forwardRef，句柄是通过渲染组件的 `registerHandle` 属性交出的；
+ * `load()` 只会对命中的那个 Adapter 调用一次，因此在这里上报视图模式就等价
+ * 于「当前文件支持哪些视图」，组件据此决定是否显示预览/源码切换。
+ *
+ * Wraps every adapter to capture the imperative handle and to report the view
+ * modes the matched format supports. The base has no forwardRef: the handle
+ * arrives through the renderer's `registerHandle` prop. `load()` runs once for
+ * the matched adapter only, so reporting there is equivalent to "which views
+ * this file supports", and the component uses it to decide whether to render the
+ * preview/source switch.
+ */
+export declare function createFilePreviewAdapters({ onHandleChange, onViewModesChange, onLinkClick, }: FilePreviewAdapterOptions): FileViewerCoreProps['adapters'];

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

@@ -1,16 +1,43 @@
-import type { FilePreviewFileTab, FilePreviewLabels, FilePreviewTab } 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 {
-    activeTab: FilePreviewTab;
-    fileTab?: FilePreviewFileTab;
-    text: Required<FilePreviewLabels>;
-    viewMode: 'preview' | 'source';
-    editing: boolean;
-    loadingEdit: boolean;
-    saving: boolean;
-    onViewModeChange: (mode: 'preview' | 'source') => void;
-    onEditStart: () => void;
-    onEditCancel: () => void;
-    onEditSave: () => void;
+    /** 完整路径，显示为面包屑；省略时面包屑退化为文件名。 */
+    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;
+    };
+    onOpenParent: (uri: string) => void;
 }
-/** 内容区标题行：路径面包屑、复制、视图切换、编辑与页签级插槽。 */
-export declare function FilePreviewHeader({ activeTab, fileTab, text, viewMode, editing, loadingEdit, saving, onViewModeChange, onEditStart, onEditCancel, onEditSave, }: FilePreviewHeaderProps): import("react").JSX.Element;
+/**
+ * 内容区标题行：路径面包屑、复制路径与宿主提供的动作区。
+ *
+ * 复制路径是外壳的一部分——有 `source.path` 的文件在任何宿主下都需要它，因此
+ * 内置在面包屑末尾。其余动作（复制正文、下载、视图切换、编辑）依赖宿主的产品
+ * 语义与文案，由宿主在 `slots.actions` 里用 `actions` 上下文自行渲染。
+ *
+ * The content header: the path breadcrumb, copy-path, and a host-supplied action
+ * area.
+ *
+ * Copy-path belongs to the shell — any file with a `source.path` needs it under
+ * every host — so it sits at the end of the breadcrumb. The other actions (copy
+ * 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({ path, fileName, canOpenParent, titleExtra, slotActions, actions, text, onOpenParent, }: FilePreviewHeaderProps): import("react").JSX.Element;

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

@@ -1,5 +1,16 @@
-import type { FilePreviewFileTab, FilePreviewLabels } from './types.js';
-/** 组件内置文案，宿主可通过面板或页签级 `labels` 覆盖。 */
+import type { FilePreviewLabels } from './types.js';
+/**
+ * 组件内置文案，宿主可通过 `labels` 逐项覆盖。
+ *
+ * 只包含组件自己渲染的文案：复制路径按钮、加载与失败态、格式不支持、空文件
+ * 与截断提示。其余动作按钮（复制正文、下载、预览/源码切换、编辑）由宿主在
+ * `slots.actions` 里自绘，文案归宿主，这里不重复提供。
+ *
+ * Built-in copy, overridable field by field through `labels`.
+ *
+ * Only what the component renders itself: the copy-path button, loading and
+ * failure states, unsupported formats, empty files and the truncation notice.
+ * Every other action button (copy content, download, preview/source, edit) is
+ * drawn by the host in `slots.actions` and carries its own copy.
+ */
 export declare const DEFAULT_LABELS: Required<FilePreviewLabels>;
-/** 从文件页签的 `source` 里取出可复制的纯文本；拿不到时返回 `undefined`。 */
-export declare function readCopyableText(tab: FilePreviewFileTab): string | undefined;

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

@@ -0,0 +1,3 @@
+import type { FilePreviewViewerProps } from './file-preview-viewer.js';
+/** 懒加载正文：先渲染加载态，模块就绪后交给底座。 */
+export declare function LazyFilePreviewViewer(props: FilePreviewViewerProps): 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-path.d.ts

@@ -0,0 +1,30 @@
+export interface PathSegment {
+    /** 该段的展示文本，不含协议前缀。 */
+    label: string;
+    /** 点击该段时要打开的完整 URI。 */
+    uri: string;
+    /** 是否首段，渲染时在它前面补上协议前缀。 */
+    isFirst: boolean;
+}
+/**
+ * 把完整路径拆成可逐级打开的祖先段，最后一段（文件名）不包含在内。
+ *
+ * 带协议前缀时首段带 `isFirst` 标记，渲染时补上前缀：`viking://a/b/c.md` 拆成
+ * `a`、`b`，首段显示为 `viking://a`。
+ *
+ * 绝对路径（`/a/b/c.md`）保留开头的斜杠：丢掉它祖先会变成相对路径 `a`、
+ * `a/b`，宿主按相对路径解析就跳到了错误的目录。相对路径（`a/b/c.md`）保持
+ * 原样，不加斜杠。
+ *
+ * Splits a full path into the ancestor levels that can be opened one by one,
+ * excluding the trailing file name. The first segment carries `isFirst` so the
+ * renderer can prepend the scheme: `viking://a/b/c.md` yields `a` and `b`, the
+ * first rendering as `viking://a`.
+ *
+ * An absolute path (`/a/b/c.md`) keeps its leading slash: dropping it turns the
+ * ancestors into relative paths (`a`, `a/b`) that a host resolves against the
+ * wrong directory. A relative path (`a/b/c.md`) is left as-is with no slash added.
+ */
+export declare function splitPathSegments(path?: string): PathSegment[];
+/** 取路径里的文件名，用于面包屑末段与标题回落。 */
+export declare function getPathFileName(path?: string): string | undefined;

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

@@ -0,0 +1,24 @@
+import type { FileSource } from '@ark-design/ui/file-viewer';
+import type { FilePreviewSource } from './types.js';
+/**
+ * 把宿主的 `source` 映射成底座的 `FileSource`，按 `content`、`file`、`url`
+ * 的顺序取第一个有值的来源。都没有时返回 `undefined`，由组件渲染不支持态。
+ *
+ * Maps the host `source` onto the base `FileSource`, taking the first available
+ * of `content`, `file` and `url`. Returns `undefined` when none is present, and
+ * the component then renders the unsupported state.
+ */
+export declare function toFileSource(source: FilePreviewSource): FileSource | undefined;
+/** 取页签上可用于复制的正文；拿不到时返回 `undefined`。 */
+export declare function readCopyableText(source: FilePreviewSource): string | undefined;
+/**
+ * 判断文件是否为严格空文件。
+ *
+ * 只把长度为 0 视为空文件；空白字符组成的文件有内容但无可见文本，属于
+ * 「暂无内容」，两者提示不同，不能合并成 `trim()` 判断。
+ *
+ * Whether the file itself is empty. Only a zero-length body counts as empty; a
+ * body made of whitespace has content but nothing visible, which is a different
+ * message. The two must not be merged into a `trim()` check.
+ */
+export declare function isEmptyFile(source: FilePreviewSource): boolean;