@openviking/react 0.1.1 → 0.1.2

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-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,25 @@
-import type { FilePreviewFileTab, FilePreviewLabels, FilePreviewTab } from './types.js';
+import type { FilePreviewActions, FilePreviewFileTab } from './types.js';
 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;
+    fileTab: FilePreviewFileTab;
+    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({ fileTab, 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-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;

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

@@ -0,0 +1,28 @@
+import type { FilePreviewLabels } from './types.js';
+/** 空文件态：严格长度为 0。The empty-file state, for a strictly zero-length body. */
+export declare function EmptyFileState({ text, }: {
+    text: Required<FilePreviewLabels>;
+}): import("react").JSX.Element;
+/** 无可见内容态：正文存在但没有可渲染的文本。 */
+export declare function NoContentState({ text, }: {
+    text: Required<FilePreviewLabels>;
+}): import("react").JSX.Element;
+/** 加载态。A loading state. */
+export declare function LoadingState({ text }: {
+    text: Required<FilePreviewLabels>;
+}): import("react").JSX.Element;
+/** 读取失败态，带重试入口。A read-failure state with a retry entry. */
+export declare function LoadFailedState({ text, description, onRetry, }: {
+    text: Required<FilePreviewLabels>;
+    description?: string;
+    onRetry?: () => void;
+}): import("react").JSX.Element;
+/** 格式不支持态，带下载入口。An unsupported-format state with a download entry. */
+export declare function UnsupportedState({ text, onDownload, }: {
+    text: Required<FilePreviewLabels>;
+    onDownload?: () => void;
+}): import("react").JSX.Element;
+/** 正文被截断时的提示，固定在正文下方。 */
+export declare function TruncatedNotice({ text, }: {
+    text: Required<FilePreviewLabels>;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,16 @@
+import type { FilePreviewTab } from './types.js';
+export interface FilePreviewTabRowProps {
+    tabs: readonly FilePreviewTab[];
+    activeKey: string;
+    disabled: boolean;
+    /** 按 key 生成页签的 DOM id，带实例前缀避免多实例重复。 */
+    tabId: (key: string) => string;
+    /** 按 key 生成面板的 DOM id，与 `tabId` 同源。 */
+    panelId: (key: string) => string;
+    onSelect: (key: string) => void;
+}
+/**
+ * 页签行：文件夹卡片式页签，选中页签与内容区连成一体。
+ * The tab row: folder-style tabs where the selected one joins the content area.
+ */
+export declare function FilePreviewTabRow({ tabs, activeKey, disabled, tabId, panelId, onSelect, }: FilePreviewTabRowProps): import("react").JSX.Element;

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

@@ -0,0 +1,31 @@
+import type { ViewerHandle, ViewerViewModeOption } from '@ark-design/ui/file-viewer/core';
+import type { MarkdownAdapterOptions } from '@ark-design/ui/file-viewer/adapters/markdown';
+import type { FilePreviewFileTab, FilePreviewLabels, FilePreviewViewMode } from './types.js';
+export interface FilePreviewViewerProps {
+    tab: FilePreviewFileTab;
+    text: Required<FilePreviewLabels>;
+    locale?: 'en-US' | 'zh-CN';
+    viewMode: FilePreviewViewMode;
+    onViewModeChange: (mode: FilePreviewViewMode) => void;
+    onDownload: () => void;
+    onHandleChange: (handle: ViewerHandle | null) => void;
+    onViewModesChange: (modes: readonly ViewerViewModeOption[]) => void;
+    /** Markdown 正文里的链接被点击时调用；传入即由宿主接管导航。 */
+    onLinkClick?: MarkdownAdapterOptions['onLinkClick'];
+}
+/**
+ * 文件页签的正文：把宿主的 `source` 交给底座按格式渲染。
+ *
+ * `toolbar` 恒为 `false`，外壳全部由组件渲染；兜底态通过 `slots` 换成组件
+ * 自己的文案，底座只负责格式路由、渲染器按需加载与准入。
+ *
+ * 本模块会静态引入底座，只能由懒加载入口引用，见 `file-preview-body.tsx`。
+ *
+ * The body of a file tab: hands the host `source` to the base component for
+ * format rendering. `toolbar` stays `false` because the component renders the
+ * whole shell, and the fallback states are replaced through `slots` so the copy
+ * comes from this component. The base keeps format routing, on-demand renderer
+ * loading and admission. This module statically imports the base, so only the
+ * lazy entry may reference it; see `file-preview-body.tsx`.
+ */
+export declare function FilePreviewViewer({ tab, text, locale, viewMode, onViewModeChange, onDownload, onHandleChange, onViewModesChange, onLinkClick, }: FilePreviewViewerProps): 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>;

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

@@ -1,17 +1,14 @@
 import type { FilePreviewComponent } from './types.js';
-export type { FilePreviewComponent, FilePreviewContentTab, FilePreviewEditing, FilePreviewFileTab, FilePreviewFileTabSlots, FilePreviewHandle, FilePreviewHeaderSlots, FilePreviewLabels, FilePreviewOperations, FilePreviewProps, FilePreviewSource, FilePreviewTab, FilePreviewTabBase, } from './types.js';
+export type { FilePreviewActions, FilePreviewComponent, FilePreviewContentTab, FilePreviewEditing, FilePreviewFileTab, FilePreviewFileTabSlots, FilePreviewHandle, FilePreviewHeaderSlots, FilePreviewLabels, FilePreviewOperations, FilePreviewProps, FilePreviewSource, FilePreviewTab, FilePreviewTabBase, FilePreviewViewMode, } from './types.js';
 /**
- * 文件预览的占位实现。
+ * 文件预览：页签行、内容区标题行与正文组成的外壳，正文由底座按格式渲染。
  *
- * 外壳（页签行、内容区标题行、页签切换与 ref 句柄）按最终形态实现，可直接
- * 交互；文件正文尚未接入 FileViewer，文件页签先以纯文本降级展示，内容页签
- * 按宿主给的节点渲染。
+ * 文件页签的正文交给 `FileViewerCore`，内容页签的正文由宿主原样渲染。空文件、
+ * 截断与编辑态由组件自己处理，不经过底座。
  *
- * Placeholder implementation of the file preview.
- *
- * The shell — tab row, content header row, tab switching and the ref handle — is
- * implemented as it will ship and is fully interactive. The file body is not
- * wired to FileViewer yet: a file tab falls back to plain text, while a content
- * tab renders the node the host supplies.
+ * File preview: a shell of tab row, content header and body, where the body is
+ * rendered by the base component according to the format. A file tab hands its
+ * body to `FileViewerCore`; a content tab renders the host node as-is. Empty
+ * files, truncation and editing are handled by this component, not the base.
  */
 export declare const FilePreview: FilePreviewComponent;