@file-viewer/web 2.0.9 → 2.0.11

package/README.en.md

@@ -1,23 +1,35 @@
 # @file-viewer/web
 
-The standard pure web native component package for Flyfish File Viewer. It mounts the complete viewer directly into the target DOM and ships the ESM API, IIFE global bundle, and asset-copy CLI for legacy admin pages, script-tag usage, and framework-free systems.
+The standard pure web native component package for Flyfish File Viewer. It ships the `<flyfish-file-viewer>` Web Component, imperative `mountViewer` controller, IIFE global bundle, and asset-copy CLI for legacy admin pages, script-tag usage, micro-frontends, and framework-free systems.
 
 ```bash
 npm install @file-viewer/web
 ```
 
+```html
+<flyfish-file-viewer
+  id="viewer"
+  src="/example/demo.pdf"
+  theme="light"
+  toolbar-position="bottom-right"
+  style="display:block;height:720px"
+></flyfish-file-viewer>
+```
+
 ```ts
-import { mountViewer } from '@file-viewer/web'
-
-const controller = mountViewer(document.getElementById('viewer')!, {
-  url: '/example/demo.pdf',
-  options: {
-    theme: 'light',
-    toolbar: { position: 'bottom-right' }
-  }
+import { defineFileViewerElement } from '@file-viewer/web'
+
+defineFileViewerElement()
+
+const viewer = document.getElementById('viewer')
+viewer.addEventListener('viewer-event', event => {
+  console.log(event.detail.type)
 })
+viewer.zoomIn()
 ```
 
+Use `mountViewer(container, options)` when you need a fully imperative controller.
+
 Use the asset copy command when you need to self-host workers, WASM files, and static examples:
 
 ```bash
@@ -28,12 +40,11 @@ No-build or legacy admin pages can copy `dist/flyfish-file-viewer-web.iife.js` a
 
 ```html
 <script src="/vendor/file-viewer-web/flyfish-file-viewer-web.iife.js"></script>
-<script>
-  window.FlyfishFileViewerWeb.mountViewer(document.getElementById('viewer'), {
-    url: '/files/demo.pdf',
-    options: { theme: 'light' }
-  })
-</script>
+<flyfish-file-viewer
+  src="/files/demo.pdf"
+  theme="light"
+  style="display:block;height:720px"
+></flyfish-file-viewer>
 ```
 
 The historical package `@flyfish-group/file-viewer-web` remains supported for compatibility. New integrations should prefer the standard package `@file-viewer/web`.
@@ -114,7 +125,7 @@ The table below lists the real props, event channel, and customization entry for
 | Vue 2.6 `@file-viewer/vue2.6` | Same as Vue 2.7 | `viewer-event` / `viewerEvent` | Separate Vue 2.6 build for long-lived applications that cannot move to Vue 2.7. |
 | React `@file-viewer/react` | `ViewerMountOptions` plus native `div` props such as `className`, `style`, `data-*`, and `aria-*` | `onEvent`, `onStateChange` | `ref` exposes `FileViewerHandle`; `useFileViewer()` returns `ref`, `props`, `state`, and `handle` for custom toolbars. |
 | React Legacy `@file-viewer/react-legacy` | Same as the React package | `onEvent`, `onStateChange` | Targets React 16.8 / 17 with a legacy-friendly component export. |
-| Pure Web `@file-viewer/web` | `mountViewer(container, ViewerMountOptions, ViewerCoreOptions?)` | `onEvent`, `onStateChange`, `controller.subscribe()` | Returns `ViewerController`; also ships ESM, script-tag IIFE, and the `file-viewer-copy-assets` CLI. |
+| Pure Web `@file-viewer/web` | `<flyfish-file-viewer>` attributes: `src/url`, `filename/name`, `type`, `size`, `theme`, `toolbar`, `toolbar-position`, `watermark`, `search`, `options`; also supports `mountViewer(...)` | `viewer-ready`, `viewer-event`, `viewer-state-change`, `viewer-error`, `onEvent`, `onStateChange`, `controller.subscribe()` | The Custom Element instance exposes the full controller handle; the IIFE script auto-registers it while keeping imperative `mountViewer` and the asset copy CLI. |
 | jQuery `@file-viewer/jquery` | `$(el).fileViewer(ViewerMountOptions & { replace?: boolean })` | `onEvent`, `onStateChange`, or `getFileViewerController(el).subscribe()` | Plugin methods include `zoomIn`, `printRenderedHtml`, and `searchDocument`; `replace:false` updates the same node in place. |
 | Svelte `@file-viewer/svelte` | `ViewerMountOptions` plus `className` and `containerStyle` | `on:viewerEvent`, `onEvent`, `onStateChange` | `bind:this` exposes the controller handle; the `use:fileViewer` action is also available and adds `replace`. |
 
@@ -149,7 +160,7 @@ For fully custom toolbars, hide the built-in toolbar and call the standard ref /
 | Vue 3 | Pass `:options="{ toolbar: false }"`, call `downloadOriginalFile()`, `printRenderedHtml()`, `exportRenderedHtml()`, `zoomIn()`, `zoomOut()`, and `resetZoom()` through the template ref, and sync buttons with `@operation-availability-change` plus `@zoom-change`. |
 | Vue 2.7 / 2.6 | Use `toolbar:false`, call instance methods through `$refs.viewer`, and listen to `@viewer-event` for `operation-availability-change` or `zoom-change`. |
 | React / React Legacy | Prefer `useFileViewer({ options:{ toolbar:false } })`; pass `viewer.props` to the component, bind custom buttons to `viewer.handle`, and read `viewer.state.availability` / `viewer.state.zoom`. |
-| Pure Web | Use `mountViewer(container, { options:{ toolbar:false }, onStateChange })`; custom DOM buttons call controller methods, and `controller.subscribe()` covers more advanced state sync. |
+| Pure Web | Use `<flyfish-file-viewer toolbar="false">` or `mountViewer(container, { options:{ toolbar:false }, onStateChange })`; custom DOM buttons can call `zoomIn()`, `printRenderedHtml()`, `searchDocument()`, and other element / controller methods directly. Use `viewer-state-change` or `controller.subscribe()` for advanced state sync. |
 | jQuery | Use `$("#viewer").fileViewer({ options:{ toolbar:false } })`; buttons can call `$("#viewer").fileViewer("zoomIn")` or read capability state through `getFileViewerController($("#viewer")).subscribe()`. |
 | Svelte | Use `<FileViewer bind:this={viewer} options={{ toolbar:false }} />`; buttons call `viewer.zoomIn()` / `viewer.printRenderedHtml()`, with `on:viewerEvent` or `onStateChange` for state sync. |
 

package/README.md

@@ -1,23 +1,35 @@
 # @file-viewer/web
 
-标准纯 Web native 组件包。它把完整 Flyfish Viewer 直接挂载到目标 DOM，提供 ESM API、IIFE 全局脚本和资源复制 CLI，适合传统后台页面、script 标签接入和无框架系统集成。
+标准纯 Web native 组件包。它提供 `<flyfish-file-viewer>` 原生 Web Component、`mountViewer` 命令式 controller、IIFE 全局脚本和资源复制 CLI，适合传统后台页面、script 标签接入、微前端壳和无框架系统集成。
 
 ```bash
 npm install @file-viewer/web
 ```
 
+```html
+<flyfish-file-viewer
+  id="viewer"
+  src="/example/demo.pdf"
+  theme="light"
+  toolbar-position="bottom-right"
+  style="display:block;height:720px"
+></flyfish-file-viewer>
+```
+
 ```ts
-import { mountViewer } from '@file-viewer/web'
-
-const controller = mountViewer(document.getElementById('viewer')!, {
-  url: '/example/demo.pdf',
-  options: {
-    theme: 'light',
-    toolbar: { position: 'bottom-right' }
-  }
+import { defineFileViewerElement } from '@file-viewer/web'
+
+defineFileViewerElement()
+
+const viewer = document.getElementById('viewer')
+viewer.addEventListener('viewer-event', event => {
+  console.log(event.detail.type)
 })
+viewer.zoomIn()
 ```
 
+需要完全命令式场景时，仍可使用 `mountViewer(container, options)` 返回完整 controller。
+
 如需自托管 Worker、WASM 和静态示例资源，可以使用资源复制命令:
 
 ```bash
@@ -28,12 +40,11 @@ npx file-viewer-copy-assets ./public/file-viewer
 
 ```html
 <script src="/vendor/file-viewer-web/flyfish-file-viewer-web.iife.js"></script>
-<script>
-  window.FlyfishFileViewerWeb.mountViewer(document.getElementById('viewer'), {
-    url: '/files/demo.pdf',
-    options: { theme: 'light' }
-  })
-</script>
+<flyfish-file-viewer
+  src="/files/demo.pdf"
+  theme="light"
+  style="display:block;height:720px"
+></flyfish-file-viewer>
 ```
 
 历史包名 `@flyfish-group/file-viewer-web` 会继续同步维护；新项目建议优先使用标准包 `@file-viewer/web`。English README: [README.en.md](./README.en.md)。
@@ -114,7 +125,7 @@ npx file-viewer-copy-assets ./public/file-viewer
 | Vue 2.6 `@file-viewer/vue2.6` | 同 Vue 2.7 | `viewer-event` / `viewerEvent` | 独立 Vue 2.6 构建，不要求业务升级到 Vue 2.7。 |
 | React `@file-viewer/react` | `ViewerMountOptions` + `div` 原生属性，如 `className`、`style`、`data-*`、`aria-*` | `onEvent`、`onStateChange` | `ref` 暴露 `FileViewerHandle`；`useFileViewer()` 会返回 `ref`、`props`、`state`、`handle`，便于自定义工具栏。 |
 | React Legacy `@file-viewer/react-legacy` | 同 React 标准包 | `onEvent`、`onStateChange` | 面向 React 16.8 / 17；组件名和默认导出保持 legacy 生态友好。 |
-| Pure Web `@file-viewer/web` | `mountViewer(container, ViewerMountOptions, ViewerCoreOptions?)` | `onEvent`、`onStateChange`、`controller.subscribe()` | 返回 `ViewerController`；同时提供 ESM、IIFE script 标签包和 `file-viewer-copy-assets`。 |
+| Pure Web `@file-viewer/web` | `<flyfish-file-viewer>` 属性 `src/url`、`filename/name`、`type`、`size`、`theme`、`toolbar`、`toolbar-position`、`watermark`、`search`、`options`；也支持 `mountViewer(...)` | `viewer-ready`、`viewer-event`、`viewer-state-change`、`viewer-error`、`onEvent`、`onStateChange`、`controller.subscribe()` | Custom Element 实例暴露完整 controller handle；IIFE script 标签会自动注册元素，同时保留 `mountViewer` 命令式挂载和资源复制 CLI。 |
 | jQuery `@file-viewer/jquery` | `$(el).fileViewer(ViewerMountOptions & { replace?: boolean })` | `onEvent`、`onStateChange` 或 `getFileViewerController(el).subscribe()` | 插件方法支持 `zoomIn`、`printRenderedHtml`、`searchDocument` 等；`replace:false` 可在同一节点上原地更新。 |
 | Svelte `@file-viewer/svelte` | `ViewerMountOptions` + `className`、`containerStyle` | `on:viewerEvent`、`onEvent`、`onStateChange` | `bind:this` 暴露 controller handle；也提供 `use:fileViewer` action，action 额外支持 `replace`。 |
 
@@ -149,7 +160,7 @@ npx file-viewer-copy-assets ./public/file-viewer
 | Vue 3 | 传 `:options="{ toolbar: false }"` 隐藏内置工具栏，通过模板 `ref` 调用 `downloadOriginalFile()`、`printRenderedHtml()`、`exportRenderedHtml()`、`zoomIn()`、`zoomOut()`、`resetZoom()`；用 `@operation-availability-change` 和 `@zoom-change` 同步按钮显隐与比例。 |
 | Vue 2.7 / 2.6 | 同样设置 `toolbar:false`，通过 `$refs.viewer` 调用实例方法；监听 `@viewer-event`，在 `event.type === "operation-availability-change"` 或 `event.type === "zoom-change"` 时更新外部工具栏。 |
 | React / React Legacy | 推荐 `useFileViewer({ options:{ toolbar:false } })`，把 `viewer.props` 传给组件，把按钮绑定到 `viewer.handle`，并读取 `viewer.state.availability` / `viewer.state.zoom` 控制禁用状态。 |
-| Pure Web | `const controller = mountViewer(container, { options:{ toolbar:false }, onStateChange })`；外部 DOM 按钮调用 controller 方法，复杂场景可用 `controller.subscribe()` 做状态同步。 |
+| Pure Web | `<flyfish-file-viewer toolbar="false">` 或 `mountViewer(container, { options:{ toolbar:false }, onStateChange })`；外部 DOM 按钮可直接调用元素实例 / controller 的 `zoomIn()`、`printRenderedHtml()`、`searchDocument()` 等方法，复杂场景用 `viewer-state-change` 或 `controller.subscribe()` 同步状态。 |
 | jQuery | `$("#viewer").fileViewer({ options:{ toolbar:false } })`；按钮调用 `$("#viewer").fileViewer("zoomIn")` 或通过 `getFileViewerController($("#viewer")).subscribe()` 获取能力状态。 |
 | Svelte | `<FileViewer bind:this={viewer} options={{ toolbar:false }} />`；按钮直接调用 `viewer.zoomIn()`、`viewer.printRenderedHtml()`，并用 `on:viewerEvent` / `onStateChange` 同步状态。 |
 

package/dist/element.d.ts

@@ -0,0 +1,91 @@
+import { type FileRef, type ViewerController, type ViewerControllerHandle, type ViewerCoreOptions, type ViewerEvent, type ViewerMountOptions, type ViewerOptions, type ViewerState, type ViewerStateListener } from './controller.js';
+export declare const FILE_VIEWER_ELEMENT_TAG = "flyfish-file-viewer";
+export type FileViewerElementEventName = 'viewer-ready' | 'viewer-event' | 'viewer-state-change' | 'viewer-error';
+export interface FileViewerElementReadyDetail {
+    controller: ViewerController;
+}
+export interface FileViewerElementStateChangeDetail {
+    state: ViewerState;
+    event?: ViewerEvent;
+}
+export interface FileViewerElementErrorDetail {
+    error: unknown;
+}
+export interface FileViewerElementSource extends ViewerMountOptions {
+    coreOptions?: ViewerCoreOptions;
+}
+declare const ElementBase: typeof HTMLElement;
+declare const observedAttributes: readonly ["src", "url", "filename", "name", "type", "size", "theme", "toolbar", "toolbar-position", "watermark", "search", "options"];
+type ObservedAttributeName = typeof observedAttributes[number];
+export declare class FileViewerElement extends ElementBase implements ViewerControllerHandle {
+    static get observedAttributes(): ObservedAttributeName[];
+    private mountNode;
+    private controller;
+    private pendingUpdate;
+    private mountOptions;
+    private internalCoreOptions;
+    get src(): string | undefined;
+    set src(value: string | undefined);
+    get url(): string | undefined;
+    set url(value: string | undefined);
+    get file(): FileRef | undefined;
+    set file(value: FileRef | undefined);
+    get buffer(): ArrayBuffer | undefined;
+    set buffer(value: ArrayBuffer | undefined);
+    get name(): string | undefined;
+    set name(value: string | undefined);
+    get filename(): string | undefined;
+    set filename(value: string | undefined);
+    get type(): string | undefined;
+    set type(value: string | undefined);
+    get size(): number | undefined;
+    set size(value: number | undefined);
+    get options(): ViewerOptions | undefined;
+    set options(value: ViewerOptions | undefined);
+    get source(): FileViewerElementSource;
+    set source(value: FileViewerElementSource | undefined);
+    get coreOptions(): ViewerCoreOptions;
+    set coreOptions(value: ViewerCoreOptions | undefined);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: ObservedAttributeName, oldValue: string | null, newValue: string | null): void;
+    load(options: ViewerMountOptions): Promise<void>;
+    update(options?: ViewerMountOptions): Promise<void>;
+    reload(): Promise<void>;
+    destroy(): void;
+    getController(): ViewerController | null;
+    getApi(): ReturnType<ViewerControllerHandle['getApi']>;
+    downloadOriginalFile(): Promise<void>;
+    printRenderedHtml(): Promise<void>;
+    exportRenderedHtml(): Promise<void>;
+    zoomIn(): ReturnType<ViewerControllerHandle['zoomIn']>;
+    zoomOut(): ReturnType<ViewerControllerHandle['zoomOut']>;
+    resetZoom(): ReturnType<ViewerControllerHandle['resetZoom']>;
+    searchDocument(query: string): ReturnType<ViewerControllerHandle['searchDocument']>;
+    clearDocumentSearch(): ReturnType<ViewerControllerHandle['clearDocumentSearch']>;
+    nextSearchResult(): ReturnType<ViewerControllerHandle['nextSearchResult']>;
+    previousSearchResult(): ReturnType<ViewerControllerHandle['previousSearchResult']>;
+    collectDocumentAnchors(): ReturnType<ViewerControllerHandle['collectDocumentAnchors']>;
+    scrollToAnchor(anchor: Parameters<ViewerControllerHandle['scrollToAnchor']>[0]): Promise<boolean>;
+    scrollToLine(line: number): Promise<boolean>;
+    getDocumentTextChunks(): ReturnType<ViewerControllerHandle['getDocumentTextChunks']>;
+    getOperationAvailability(): ReturnType<ViewerControllerHandle['getOperationAvailability']>;
+    getZoomState(): ReturnType<ViewerControllerHandle['getZoomState']>;
+    getSearchState(): ReturnType<ViewerControllerHandle['getSearchState']>;
+    getState(): ReturnType<ViewerControllerHandle['getState']>;
+    subscribe(listener: ViewerStateListener): () => void;
+    private setMountOptions;
+    private mount;
+    private remount;
+    private remountOrUpdate;
+    private ensureMountNode;
+    private createEffectiveMountOptions;
+    private readAttributeMountOptions;
+    private readAttributeViewerOptions;
+    private scheduleUpdate;
+    private dispatchViewerEvent;
+    private dispatchError;
+    private dispatchTypedEvent;
+}
+export declare const defineFileViewerElement: (tagName?: string) => CustomElementConstructor | undefined;
+export {};