@ap666/office-word 0.1.3 → 0.1.6

package/README.md

@@ -11,7 +11,7 @@ npm install @ap666/office-word
 If your package manager does not auto-install peer dependencies, install the required runtime peers as well:
 
 ```bash
-npm install vue @tiptap/core @tiptap/vue-3 @tiptap/pm @tiptap/starter-kit @tiptap/extension-placeholder @tiptap/extension-code-block @tiptap/extension-code-block-lowlight @tiptap/extension-font-family @tiptap/extension-subscript @tiptap/extension-superscript @tiptap/extension-table @tiptap/extension-table-cell @tiptap/extension-table-header @tiptap/extension-table-row @tiptap/extension-task-item @tiptap/extension-task-list @tiptap/extension-text-style @tiptap/extension-underline lowlight
+npm install vue @tiptap/core @tiptap/vue-3 @tiptap/pm @tiptap/starter-kit @tiptap/extension-placeholder @tiptap/extension-code-block @tiptap/extension-code-block-lowlight @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/extension-font-family @tiptap/extension-subscript @tiptap/extension-superscript @tiptap/extension-table @tiptap/extension-table-cell @tiptap/extension-table-header @tiptap/extension-table-row @tiptap/extension-task-item @tiptap/extension-task-list @tiptap/extension-text-style @tiptap/extension-underline @tiptap/y-tiptap lowlight y-prosemirror yjs
 ```
 
 ## Basic Use
@@ -36,7 +36,99 @@ The package imports its own styles from the entry, so no extra CSS import is req
 
 - `modelValue?: JSONContent | null`
 - `editable?: boolean`
+- `mode?: 'edit' | 'preview'`
+- `outlinePlacement?: 'left' | 'right'`
+- `enabledExportItems?: ('pdf' | 'html' | 'image' | 'print')[] | null`
+- `enabledInsertMenuItems?: ('image' | 'video' | 'table' | 'local-file' | 'columns' | 'highlight-block' | 'date' | 'code-block' | 'formula' | 'blockquote' | 'emoji' | 'link' | 'divider' | 'countdown' | 'markdown-import')[] | null`
+- `enabledToolbarActions?: ('blockquote')[] | null`
 - `placeholder?: string`
+- `collaboration?: RichTextEditorCollaborationOptions | null`
+
+When these whitelist props are omitted, all built-in options stay enabled. Once you pass a list, only the listed items remain visible and usable.
+
+```vue
+<RichTextEditor
+  v-model="content"
+  :enabled-export-items="['html', 'image']"
+  :enabled-insert-menu-items="['image', 'local-file', 'blockquote']"
+  :enabled-toolbar-actions="['blockquote']"
+/>
+```
+
+## Preview Mode
+
+Use `mode="preview"` to switch the component into a read-only preview shell. In preview mode, the toolbar is hidden, editing is disabled, and the outline can be placed on either side.
+
+```vue
+<template>
+  <RichTextEditor
+    v-model="content"
+    mode="preview"
+    outline-placement="right"
+  />
+</template>
+```
+
+On narrow screens, preview mode automatically scales the page canvas down so the document stays readable on phones.
+
+## Collaboration
+
+The same component supports both normal single-user editing and optional Yjs collaboration.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import * as Y from 'yjs'
+import { WebsocketProvider } from 'y-websocket'
+import type { JSONContent } from '@tiptap/core'
+import { RichTextEditor } from '@ap666/office-word'
+
+const ydoc = new Y.Doc()
+const provider = new WebsocketProvider('ws://localhost:1234', 'office-word-demo', ydoc)
+const content = ref<JSONContent | null>(null)
+</script>
+
+<template>
+  <RichTextEditor
+    v-model="content"
+    :collaboration="{
+      document: ydoc,
+      field: 'content',
+      provider,
+      user: {
+        name: '张三',
+        color: '#3b82f6',
+      },
+    }"
+  />
+</template>
+```
+
+In collaboration mode, the shared Yjs fragment becomes the source of truth. The component still emits JSON updates, but external `modelValue` changes are not pushed back into the editor. If you want remote cursors, also install `y-websocket` in the host project and pass `provider + user`.
+
+Do not use `modelValue` as the initial seed source for a collaborative room. Seed the Yjs document before mounting the editor if the room needs default content.
+
+### Included Yjs Server Example
+
+The published package also includes a minimal collaboration server under `yjs/`.
+
+```bash
+cd node_modules/@ap666/office-word/yjs
+npm install
+npm run start
+```
+
+Default address is `ws://0.0.0.0:1234`.
+
+Use the same websocket address and room name on every client:
+
+```ts
+import * as Y from 'yjs'
+import { WebsocketProvider } from 'y-websocket'
+
+const ydoc = new Y.Doc()
+const provider = new WebsocketProvider('ws://127.0.0.1:1234', 'office-word-demo', ydoc)
+```
 
 ## Instance API
 
@@ -64,9 +156,29 @@ Available methods:
 - `insertImage(payload | payload[]): boolean`
 - `insertVideo(payload): boolean`
 - `insertFile(payload): boolean`
+- `insertLocalFile(payload): boolean`
+- `openLocalFilePicker(): void`
 - `focus(): void`
 - `getJSON(): JSONContent | null`
 
+## Local File Block
+
+The insert menu now supports `Local File`, and the component instance also exposes local-file insertion APIs.
+
+```ts
+editorRef.value?.insertLocalFile({
+  url: 'https://cdn.example.com/files/demo.txt',
+  name: 'demo.txt',
+  size: 2048,
+  mimeType: 'text/plain',
+})
+```
+
+Listen for local file events from the component:
+
+- `@local-file-upload`: emitted after a local file is selected from the editor picker and inserted
+- `@local-file-download`: emitted when the file card download button is clicked
+
 ## Export Example
 
 ```ts
@@ -167,6 +279,9 @@ async function uploadFile(file: File) {
 
 ```ts
 import type {
+  RichTextEditorCollaborationProvider,
+  RichTextEditorCollaborationUser,
+  RichTextEditorCollaborationOptions,
   RichTextEditorFilePayload,
   RichTextEditorImageExportOptions,
   RichTextEditorImagePayload,
@@ -178,3 +293,4 @@ import type {
 ## Package Docs
 
 - usage guide: `docs/usage.md`
+- bundled Yjs server example: `yjs/README.md`

package/dist/components/LocalFileBlockView.vue.d.ts

@@ -0,0 +1,3 @@
+import { NodeViewProps } from '@tiptap/vue-3';
+declare const _default: import('vue').DefineComponent<NodeViewProps, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<NodeViewProps> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/components/OutlinePanel.vue.d.ts

@@ -1,5 +1,6 @@
 type __VLS_Props = {
     open: boolean;
+    placement: 'left' | 'right';
     items: Array<{
         pos: number;
         level: number;

package/dist/components/RichTextEditor.vue.d.ts

@@ -1,5 +1,5 @@
 import { JSONContent } from '@tiptap/core';
-import { RichTextEditorFilePayload, RichTextEditorImageExportOptions, RichTextEditorImagePayload, RichTextEditorProps, RichTextEditorVideoPayload } from '../types';
+import { RichTextEditorFilePayload, RichTextEditorImageExportOptions, RichTextEditorImagePayload, RichTextEditorLocalFilePayload, RichTextEditorProps, RichTextEditorVideoPayload } from '../types';
 declare const _default: import('vue').DefineComponent<RichTextEditorProps, {
     exportPdf: () => Promise<Blob | null>;
     exportImage: (options?: RichTextEditorImageExportOptions) => Promise<Blob | null>;
@@ -7,18 +7,26 @@ declare const _default: import('vue').DefineComponent<RichTextEditorProps, {
     insertImage: (payload: RichTextEditorImagePayload | RichTextEditorImagePayload[]) => boolean;
     insertVideo: (payload: RichTextEditorVideoPayload) => boolean;
     insertFile: (payload: RichTextEditorFilePayload) => boolean;
+    insertLocalFile: (payload: RichTextEditorLocalFilePayload) => boolean;
+    openLocalFilePicker: () => void;
     focus: () => void;
     getJSON: () => JSONContent | null;
 }, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
     change: (value: JSONContent) => any;
     "update:modelValue": (value: JSONContent) => any;
+    "local-file-upload": (value: RichTextEditorLocalFilePayload) => any;
+    "local-file-download": (value: RichTextEditorLocalFilePayload) => any;
 }, string, import('vue').PublicProps, Readonly<RichTextEditorProps> & Readonly<{
     onChange?: ((value: JSONContent) => any) | undefined;
     "onUpdate:modelValue"?: ((value: JSONContent) => any) | undefined;
+    "onLocal-file-upload"?: ((value: RichTextEditorLocalFilePayload) => any) | undefined;
+    "onLocal-file-download"?: ((value: RichTextEditorLocalFilePayload) => any) | undefined;
 }>, {
     placeholder: string;
+    mode: "edit" | "preview";
     editable: boolean;
     modelValue: JSONContent | null;
+    outlinePlacement: "left" | "right";
 }, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
     rootRef: HTMLDivElement;
     insertMenuRef: HTMLDivElement;
@@ -47,5 +55,6 @@ declare const _default: import('vue').DefineComponent<RichTextEditorProps, {
     countdownBubbleMenuRef: HTMLDivElement;
     countdownBubbleEditButtonRef: HTMLButtonElement;
     markdownImportInputRef: HTMLInputElement;
+    localFileInputRef: HTMLInputElement;
 }, HTMLDivElement>;
 export default _default;

package/dist/composables/useRichTextEditor.d.ts

@@ -1,8 +1,16 @@
 import { JSONContent } from '@tiptap/core';
+import { RichTextEditorCollaborationOptions } from '../types';
 type UseRichTextEditorOptions = {
     content: JSONContent;
     editable: boolean;
     placeholder: string;
+    collaboration?: RichTextEditorCollaborationOptions | null;
+    onLocalFileDownload?: (payload: {
+        url: string;
+        name: string;
+        size?: number;
+        mimeType?: string;
+    }) => void;
     onUpdate: (value: JSONContent) => void;
 };
 export declare function useRichTextEditor(options: UseRichTextEditorOptions): import('vue').ShallowRef<import('@tiptap/vue-3').Editor | undefined, import('@tiptap/vue-3').Editor | undefined>;

package/dist/extensions/local-file-block.d.ts

@@ -0,0 +1,2 @@
+import { Node } from '@tiptap/core';
+export declare const LocalFileBlock: Node<any, any>;

package/dist/index.d.ts

@@ -4,5 +4,5 @@ import { default as RichTextEditor } from './components/RichTextEditor.vue';
 import { default as ScrollArea } from './components/ScrollArea.vue';
 export { OfficeColorIcon, OfficeIcon, RichTextEditor, ScrollArea };
 export { colorIconNames, monoIconNames } from './icons';
-export type { OfficeColorIconProps, OfficeIconProps, RichTextEditorFilePayload, RichTextEditorImageExportOptions, RichTextEditorImagePayload, RichTextEditorInstance, RichTextEditorProps, RichTextEditorVideoPayload, } from './types';
+export type { OfficeColorIconProps, OfficeIconProps, RichTextEditorCollaborationAwareness, RichTextEditorCollaborationDocument, RichTextEditorCollaborationOptions, RichTextEditorCollaborationProvider, RichTextEditorCollaborationUser, RichTextEditorFilePayload, RichTextEditorExportItemKey, RichTextEditorImageExportOptions, RichTextEditorImagePayload, RichTextEditorInstance, RichTextEditorInsertMenuItemKey, RichTextEditorLocalFilePayload, RichTextEditorProps, RichTextEditorToolbarActionKey, RichTextEditorVideoPayload, } from './types';
 export default RichTextEditor;