@openviking/react 0.1.0 → 0.1.2

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

@@ -0,0 +1,25 @@
+import type { FilePreviewActions, FilePreviewFileTab } from './types.js';
+export interface FilePreviewHeaderProps {
+    fileTab: FilePreviewFileTab;
+    actions: FilePreviewActions;
+    text: {
+        copyPath: string;
+    };
+    onOpenParent: (uri: string) => void;
+}
+/**
+ * 内容区标题行：路径面包屑、复制路径与宿主提供的动作区。
+ *
+ * 复制路径是外壳的一部分——有 `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

@@ -0,0 +1,16 @@
+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>;

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 +1,14 @@
-export {};
+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';
+/**
+ * 文件预览：页签行、内容区标题行与正文组成的外壳，正文由底座按格式渲染。
+ *
+ * 文件页签的正文交给 `FileViewerCore`，内容页签的正文由宿主原样渲染。空文件、
+ * 截断与编辑态由组件自己处理，不经过底座。
+ *
+ * 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;

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

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