@openviking/react 0.1.2 → 0.1.4

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

@@ -0,0 +1,63 @@
+import type { Locale } from '../../shared/locale.js';
+import type { ComponentPropsWithRef, HTMLAttributes, ReactElement, ReactNode } from 'react';
+import type { AgentConnectProps } from '../agent-connect/index.js';
+/**
+ * 文件浏览入口条与抽屉的文案。未覆盖项跟随 locale。
+ * Copy of the file browser entries and drawer. Omitted fields follow locale.
+ */
+export interface FileBrowserEntriesLabels {
+    /** 连接 Agent 的文案。Label of the connect-agent entry. */
+    connectAgent?: string;
+    /** 导入资源的文案。Label of the import-resources entry. */
+    importResources?: string;
+    /** 右侧接入抽屉的关闭文案。Close label of the connection drawer. */
+    close?: string;
+}
+/**
+ * 文件浏览入口条的属性。
+ *
+ * 固定两个入口：连接 Agent 与导入资源。agentConnect 可启用内置右侧接入抽屉，
+ * 也可仅通过回调接入宿主流程。宿主可包装或替换默认导入按钮。
+ * 图标、文案、等分排布与分隔线由组件负责。
+ *
+ * 只显示一个入口时不画分隔线：线分隔的是两个相邻项，只剩一个就无从分隔。
+ *
+ * Props of the file browser entry row.
+ *
+ * Two fixed entries: connect an agent and import resources. agentConnect enables
+ * the built-in connection drawer; callbacks also support host-owned flows.
+ * Hosts can wrap or replace the default import button. The component owns the
+ * icons, copy, equal-width layout and divider.
+ *
+ * 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'> {
+    /** 内置中英文文案的语言。Language of the built-in interface copy. */
+    locale: Locale;
+    /**
+     * 内置 AgentConnect 右侧抽屉的参数；传入后显示连接入口。
+     * Options for the built-in AgentConnect drawer; enables the connect entry.
+     */
+    agentConnect?: AgentConnectProps;
+    /**
+     * 点击连接入口时通知；未传 agentConnect 时由宿主处理接入。
+     * Click notification; the host owns connection when agentConnect is omitted.
+     */
+    onConnectAgent?: () => void;
+    /**
+     * 默认导入按钮被点击时触发；未提供导入回调和渲染插槽时隐藏入口。
+     * Called when the default import button is clicked; omit both import props to hide it.
+     */
+    onImportResources?: () => void;
+    /**
+     * 自定义导入入口；参数是带有图标、文案和点击回调的默认原生按钮。
+     * 传入后显示入口，返回 null 时隐藏；不传时按 onImportResources 渲染默认按钮。
+     * Renders the import entry using its default native button, including icon, label
+     * and click handler. Enables the entry; return null to hide it. When omitted,
+     * onImportResources enables the default button.
+     */
+    renderImportResources?: (trigger: ReactElement<ComponentPropsWithRef<'button'>>) => ReactNode;
+    /** 可替换文案，未提供的项使用当前 locale 的内置文案。Replaceable copy; omitted fields follow locale. */
+    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

@@ -20,7 +20,7 @@ import type { FileViewerCoreProps } from '@ark-design/ui/file-viewer/core';
  * pulls in browser-only packages, and a top-level import would break server
  * rendering.
  */
-export declare function createFilePreviewAdapterList({ onLinkClick, }?: {
+export declare function createFilePreviewAdapterList({ onLinkClick, resolveImage, }?: {
     /**
      * Markdown 正文里的链接被点击时调用。传入后由回调接管导航，底座不再自行
      * 跳转；只有 Markdown Adapter 支持这个回调，其余格式忽略它。
@@ -30,4 +30,5 @@ export declare function createFilePreviewAdapterList({ onLinkClick, }?: {
      * Markdown adapter supports this; other formats ignore it.
      */
     onLinkClick?: MarkdownAdapterOptions['onLinkClick'];
+    resolveImage?: (src: string) => Promise<string>;
 }): FileViewerCoreProps['adapters'];

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

@@ -1,3 +1,4 @@
+import type { Locale } from '../../shared/locale.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';
@@ -5,7 +6,7 @@ import type { FilePreviewFileTab, FilePreviewLabels, FilePreviewViewMode } from
 export interface FilePreviewBodyProps {
     fileTab: FilePreviewFileTab;
     text: Required<FilePreviewLabels>;
-    locale?: 'en-US' | 'zh-CN';
+    locale?: Locale;
     viewMode: FilePreviewViewMode;
     editing: ReturnType<typeof useFilePreviewEditing>;
     onViewModeChange: (mode: FilePreviewViewMode) => void;

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

@@ -1,5 +1,6 @@
 import type { PathSegment } from './file-preview-path.js';
 export interface FilePreviewBreadcrumbMenuProps {
+    hiddenPathLabel: string;
     segments: readonly PathSegment[];
     canOpen: boolean;
     disabled: boolean;
@@ -13,4 +14,4 @@ export interface FilePreviewBreadcrumbMenuProps {
  * 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;
+export declare function FilePreviewBreadcrumbMenu({ hiddenPathLabel, segments, canOpen, disabled, onOpen, }: FilePreviewBreadcrumbMenuProps): import("react").JSX.Element;

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

@@ -1,5 +1,6 @@
 import type { PathSegment } from './file-preview-path.js';
 export interface FilePreviewBreadcrumbProps {
+    hiddenPathLabel: string;
     segments: readonly PathSegment[];
     title: string;
     canOpen: boolean;
@@ -18,4 +19,4 @@ export interface FilePreviewBreadcrumbProps {
  * 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;
+export declare function FilePreviewBreadcrumb({ hiddenPathLabel, segments, title, canOpen, disabled, onOpen, }: FilePreviewBreadcrumbProps): import("react").JSX.Element;

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

@@ -0,0 +1,33 @@
+import type { Locale } from '../../shared/locale.js';
+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?: Locale;
+    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-handle-adapters.d.ts

@@ -7,6 +7,7 @@ export interface FilePreviewAdapterOptions {
     onViewModesChange: (modes: readonly ViewerViewModeOption[]) => void;
     /** Markdown 正文里的链接被点击时调用；传入即由宿主接管导航。 */
     onLinkClick?: MarkdownAdapterOptions['onLinkClick'];
+    resolveImage?: (src: string) => Promise<string>;
 }
 /**
  * 给每个 Adapter 套一层：接住底座交出来的命令式句柄，并上报命中格式支持
@@ -23,4 +24,4 @@ export interface FilePreviewAdapterOptions {
  * 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'];
+export declare function createFilePreviewAdapters({ onHandleChange, onViewModesChange, onLinkClick, resolveImage, }: FilePreviewAdapterOptions): FileViewerCoreProps['adapters'];

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

@@ -1,9 +1,31 @@
-import type { FilePreviewActions, FilePreviewFileTab } from './types.js';
+import type { ReactNode } from 'react';
+import type { FilePreviewActions, FilePreviewLevel } 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;
+    levels?: readonly FilePreviewLevel[];
+    levelKey?: string;
+    onLevelChange?: (key: string) => void;
     text: {
         copyPath: string;
+        showHiddenPath: string;
     };
     onOpenParent: (uri: string) => void;
 }
@@ -22,4 +44,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({ levels, levelKey, onLevelChange, path, fileName, canOpenParent, titleExtra, slotActions, actions, text, onOpenParent, }: FilePreviewHeaderProps): import("react").JSX.Element;

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

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react';
+/** Observe the renderer's native image load; no extra file request or decoding. */
+export declare function FilePreviewImageFrame({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;

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

@@ -1,16 +1,4 @@
 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.
- */
+import { type Locale } from '../../shared/locale.js';
 export declare const DEFAULT_LABELS: Required<FilePreviewLabels>;
+export declare function resolveFilePreviewLabels(locale: Locale, labels?: FilePreviewLabels): Required<FilePreviewLabels>;

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

@@ -0,0 +1,7 @@
+import type { FilePreviewLevel } from './types.js';
+export declare function FilePreviewLevelTabs({ levels, activeKey, disabled, onSelect, }: {
+    levels?: readonly FilePreviewLevel[];
+    activeKey?: string;
+    disabled: boolean;
+    onSelect: (key: string) => void;
+}): import("react").JSX.Element | null;

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

@@ -0,0 +1,13 @@
+export declare function imagePreviewTarget(url: string): string;
+export declare function originalImageTarget(url: string): string;
+type Node = {
+    type: string;
+    url?: string;
+    identifier?: string;
+    alt?: string | null;
+    title?: string | null;
+    children?: Node[];
+};
+/** Rewrite image nodes only. Fenced code and normal links remain untouched. */
+export declare function preserveVikingImages(root: Node): void;
+export {};

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

@@ -0,0 +1,44 @@
+import type { Locale } from '../../shared/locale.js';
+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;
+    levelKey?: string;
+    onLevelChange: (key: string) => void;
+    panelProps: HTMLAttributes<HTMLDivElement>;
+    panelClass: string;
+    text: Required<FilePreviewLabels>;
+    locale?: Locale;
+    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({ levelKey, onLevelChange, 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-viewer.d.ts

@@ -1,10 +1,11 @@
+import type { Locale } from '../../shared/locale.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 { FilePreviewFileTab, FilePreviewLabels, FilePreviewViewMode } from './types.js';
 export interface FilePreviewViewerProps {
     tab: FilePreviewFileTab;
     text: Required<FilePreviewLabels>;
-    locale?: 'en-US' | 'zh-CN';
+    locale?: Locale;
     viewMode: FilePreviewViewMode;
     onViewModeChange: (mode: FilePreviewViewMode) => void;
     onDownload: () => void;

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

@@ -1,5 +1,5 @@
 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';
 /**
  * 文件预览：页签行、内容区标题行与正文组成的外壳，正文由底座按格式渲染。
  *

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

@@ -1 +1,2 @@
-export * from './file-preview.js';
+export { FilePreview, LoadingState } from './file-preview.js';
+export type * 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/locales/en-US.d.ts

@@ -0,0 +1,16 @@
+declare const messages: {
+    showHiddenPath: string;
+    copyPath: string;
+    editor: string;
+    leaveEditing: string;
+    retry: string;
+    loadFailed: string;
+    saveFailed: string;
+    unsupported: string;
+    loading: string;
+    download: string;
+    fileEmpty: string;
+    noContent: string;
+    truncated: string;
+};
+export default messages;

package/dist/components/file-preview/locales/zh-CN.d.ts

@@ -0,0 +1,16 @@
+declare const messages: {
+    showHiddenPath: string;
+    copyPath: string;
+    editor: string;
+    leaveEditing: string;
+    retry: string;
+    loadFailed: string;
+    saveFailed: string;
+    unsupported: string;
+    loading: string;
+    download: string;
+    fileEmpty: string;
+    noContent: string;
+    truncated: string;
+};
+export default messages;