diff --git a/.github/deploy-vitepress.yml b/.github/deploy-vitepress.yml new file mode 100644 index 0000000..9ffd9b5 --- /dev/null +++ b/.github/deploy-vitepress.yml @@ -0,0 +1,51 @@ +name: Deploy VitePress site to Pages + +on: + push: + branches: [main] + + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Setup Bun + - uses: oven-sh/setup-bun@v1 + - name: Setup Pages + uses: actions/configure-pages@v4 + - name: Install dependencies + run: bun install + - name: Build with VitePress + run: bun run docs:build + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/.vitepress/dist + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + needs: build + runs-on: ubuntu-latest + name: Deploy + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 9b1ee42..3f3b368 100644 --- a/.gitignore +++ b/.gitignore @@ -173,3 +173,7 @@ dist # Finder (MacOS) folder config .DS_Store + +# Vitepress +docs/.vitepress/cache +docs/.vitepress/dist \ No newline at end of file diff --git a/bun.lockb b/bun.lockb index e993453..6b9334c 100644 Binary files a/bun.lockb and b/bun.lockb differ diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts new file mode 100644 index 0000000..438405b --- /dev/null +++ b/docs/.vitepress/config.ts @@ -0,0 +1,47 @@ +import { defineConfig } from "vitepress"; +import { version } from "../../packages/vue/package.json"; + +// https://vitepress.dev/reference/site-config +export default defineConfig({ + title: "vue-pdfjs", + description: + "A Vue component for displaying PDF files using the standard `pdf.js` viewer. This package provides a simple and powerful integration to embed PDF viewers in Vue applications.", + themeConfig: { + logo: { src: "/vue_pdfjs.svg", width: 48, height: 48 }, + + nav: [ + { text: "Home", link: "/" }, + { text: "Examples", link: "/examples/basic-examples" }, + { + text: `v${version}`, + items: [ + { + text: "Changelog", + link: "https://github.com/tuttarealstep/vue-pdf.js/releases", + }, + ], + }, + ], + + sidebar: [ + { + text: "Introduction", + items: [ + { text: "Getting Started", link: "/guide/getting-started" }, + { text: "Composables", link: "/guide/composables" }, + ], + }, + { + text: "Examples", + items: [ + { text: "Basic Examples", link: "/examples/basic-examples" }, + { text: "Usage with Nuxt", link: "/examples/nuxt-example" }, + ], + }, + ], + + socialLinks: [ + { icon: "github", link: "https://github.com/tuttarealstep/vue-pdf.js" }, + ], + }, +}); diff --git a/docs/examples/basic-examples.md b/docs/examples/basic-examples.md new file mode 100644 index 0000000..bfea340 --- /dev/null +++ b/docs/examples/basic-examples.md @@ -0,0 +1,129 @@ +# Basic examples + +## Use another language + +```vue + + + + + +``` + +## Use the PDF.js eventBus + +In this example, we use the `pdfApp` property to access the `eventBus` and listen to the `pagesloaded` event. When the event is triggered, we search for a specific text in the document. + +```vue + + + + + +``` diff --git a/docs/examples/nuxt-example.md b/docs/examples/nuxt-example.md new file mode 100644 index 0000000..628b675 --- /dev/null +++ b/docs/examples/nuxt-example.md @@ -0,0 +1,118 @@ +# Usage with Nuxt + +If you want to use `@tuttarealstep/vue-pdf.js` in a Nuxt project, you can follow these steps. + +## Create a "client-only" component + +In this example we will use the `@tuttarealstep/vue-pdf.js` component to display a PDF file and highlight some text. + +Create a new component in the `components` directory, for example `PDFViewer.client.vue` + +```vue + + + + +``` + +## Use the component in a page + +Now you can use the `PDFViewer.client.vue` component in a Nuxt page. + +Create a new page in the `pages` directory, for example `pdf-viewer.vue` + +```vue + + +``` diff --git a/docs/guide/composables.md b/docs/guide/composables.md new file mode 100644 index 0000000..55ab600 --- /dev/null +++ b/docs/guide/composables.md @@ -0,0 +1,93 @@ +# Composables + +## `usePDF` composable + +The `usePDF` composable provides a way to load and prepare a PDF document for the usage with the `@tuttarealstep/vue-pdf.js` component. + +It return the pdf source, the pdf metadata and the number of pages. + +```js +import { usePDF } from "@tuttarealstep/vue-pdf.js"; + +const { pdf, info, pages } = usePDF(""); +``` + +### Parameters + +#### `source` + +- Type: `string | URL | TypedArray | ArrayBuffer | DocumentInitParameters | File | Blob | PDFDocumentLoadingTask | undefined | null | ref` +- Required: `true` + +The `DocumentInitParameters` type is defined in the [PDF.js source](https://github.com/mozilla/pdf.js/blob/3634dab10ca7dbaf0ca536f645465b231c88f862/src/display/api.js#L116). + +#### `options` + +- Type: `object` +- Required: `false` + +The options object can contain the following properties: + +- `onProgress`: Callback function to enable progress monitor. +- `onError`: function to handle errors during the loading of the PDF file. +- `onPassword`: Callback function to request a password. If not provided, the default behavior is to use the `password` parameter. +- `password`: The password to use for decrypting the PDF file. + +```ts +function onProgress(progressData: OnProgressParameters) { + console.log(`Progress: ${progressData.loaded} / ${progressData.total}`); +} + +function onPassword(updatePassword: UpdatePasswordFn, reason: any) { + console.log(`Password required: ${reason}`); + updatePassword(""); +} + +function onError(reason: any) { + console.error(`Error: ${reason}`); +} + +const { pdf, info, pages } = usePDF("", { + onPassword, + onProgress, + onError, +}); +``` + +### Return values + +::: info +All the returned values are [ShallowRef](https://vuejs.org/api/reactivity-advanced.html#shallowref) +::: + +#### `pdf` + +- Type: `ShallowRef` + +The PDF document loading task. You can read more about it in the [PDF.js source](https://github.com/mozilla/pdf.js/blob/3634dab10ca7dbaf0ca536f645465b231c88f862/src/display/api.js#L587) + +#### `info` + +- Type: `ShallowRef` + +This object represents the information of the PDF document. It contains the following properties: + +```ts + metadata: PDFInfoMetadata; // Metadata + attachments: Record; // Attachments + javascript: string[] | null; // JavaScript objects + outline: any; // Outline object +``` + +The metadata object contains the following properties: + +```ts +info: any; // PDF informations +metadata: Metadata; // PDF.js Metadata +``` + +#### `pages` + +- Type: `ShallowRef` + +The number of pages in the PDF document. diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md new file mode 100644 index 0000000..4debdba --- /dev/null +++ b/docs/guide/getting-started.md @@ -0,0 +1,110 @@ +# Getting Started + +![npm](https://img.shields.io/npm/v/@tuttarealstep/vue-pdf.js) + +![Editor](/editor.png) + +## Introduction + +`@tuttarealstep/vue-pdf.js` is a Vue 3 client-side component that allow you to display PDF files using the standard [Mozilla's PDF.js viewer](https://github.com/mozilla/pdf.js). + +## Installation + +::: code-group + +```sh [npm] +$ npm i @tuttarealstep/vue-pdf.js +``` + +```sh [bun] +$ bun add @tuttarealstep/vue-pdf.js +``` + +```sh [pnpm] +$ pnpm add @tuttarealstep/vue-pdf.js +``` + +```sh [yarn] +$ yarn add @tuttarealstep/vue-pdf.js +``` + +::: + +## Usage + +Import the component and pass the PDF file to the `source` prop. + +### Basic + +```vue + + + + + +``` + +### Using the `usePDF` composable + +```vue + + + + + +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..fc5830e --- /dev/null +++ b/docs/index.md @@ -0,0 +1,52 @@ +--- +# https://vitepress.dev/reference/default-theme-home-page +layout: home + +hero: + name: "vue-pdfjs" + text: "Display PDF files using the standard PDF.js viewer" + tagline: This package provides a simple and powerful integration to embed the PDF,js viewer in Vue applications. + actions: + - theme: brand + text: Quick Start + link: /guide/getting-started + - theme: alt + text: Examples + link: /examples/basic-examples + image: + src: /logo.webp + alt: "vue-pdfjs" + +features: + - title: A powerful wrapper + icon: 💯 + details: All the features of the Mozilla's PDF.js viewer are available. + - title: Customizable + icon: 🎨 + details: Customize the aspect of the viewer, you can import the default style or create your own. + - title: Easy to use + icon: 🚀 + details: Just import the component and pass the PDF file, that's it! +--- + + diff --git a/docs/public/editor.png b/docs/public/editor.png new file mode 100644 index 0000000..149802f Binary files /dev/null and b/docs/public/editor.png differ diff --git a/docs/public/logo.webp b/docs/public/logo.webp new file mode 100644 index 0000000..09160da Binary files /dev/null and b/docs/public/logo.webp differ diff --git a/docs/public/vue_pdfjs.svg b/docs/public/vue_pdfjs.svg new file mode 100644 index 0000000..9aedeb9 --- /dev/null +++ b/docs/public/vue_pdfjs.svg @@ -0,0 +1,26 @@ + + + + + + + + + + + + + vue_logo + + + + + + + + + + + + + \ No newline at end of file diff --git a/package.json b/package.json index f51e8cb..aec9e9d 100644 --- a/package.json +++ b/package.json @@ -6,16 +6,20 @@ "scripts": { "dev": "bun run --cwd ./packages/vue-pdfjs-playground dev", "build": "bun run --cwd ./packages/vue build", - "test": "bun run --cwd ./packages/vue test" + "test": "bun run --cwd ./packages/vue test", + "docs:dev": "vitepress dev docs", + "docs:build": "vitepress build docs", + "docs:preview": "vitepress preview docs" }, "workspaces": [ "packages/*" ], "devDependencies": { - "@types/bun": "latest" + "@types/bun": "latest", + "vitepress": "^1.5.0" }, "peerDependencies": { - "typescript": "^5.0.0" + "typescript": "^5.6.3" }, "dependencies": {} } \ No newline at end of file diff --git a/packages/vue-pdfjs-playground/package.json b/packages/vue-pdfjs-playground/package.json index 4f4a565..abc1769 100644 --- a/packages/vue-pdfjs-playground/package.json +++ b/packages/vue-pdfjs-playground/package.json @@ -4,7 +4,7 @@ "private": true, "type": "module", "scripts": { - "dev": "vite --force" + "dev": "bun run --cwd ../vue build && vite --force" }, "dependencies": { "@tuttarealstep/vue-pdf.js": "file:../vue" diff --git a/packages/vue-pdfjs-playground/src/App.vue b/packages/vue-pdfjs-playground/src/App.vue index f2f554c..0b387af 100644 --- a/packages/vue-pdfjs-playground/src/App.vue +++ b/packages/vue-pdfjs-playground/src/App.vue @@ -3,15 +3,26 @@ import { reactive, useTemplateRef } from 'vue' import { VuePDFjs, usePDF } from '@tuttarealstep/vue-pdf.js' import '@tuttarealstep/vue-pdf.js/dist/style.css' import enUS_FTL from '@tuttarealstep/vue-pdf.js/l10n/en-US/viewer.ftl?raw' +import type { VuePDFjsProps } from '../../vue/dist/src/components/VuePDFjs.vue'; const pdf = new URL('./assets/compressed.tracemonkey-pldi-09.pdf', import.meta.url); const vuepdfjs = useTemplateRef('vuepdfjs') -const options = reactive({ +const options = reactive>({ locale: { code: 'en-US', ftl: enUS_FTL + }, + toolbar: { + options: { + secondaryOpenFile: false, + /*secondaryDownload: false, + secondaryPrint: false, + scaleSelect: false, + print: false, + download: false,*/ + } } }) @@ -33,13 +44,13 @@ const onPdfAppLoaded = () => { }) } -const { pdf: document, info, pages} = usePDF(pdf) +const { pdf: document, info, pages } = usePDF(pdf) console.log(document, info, pages) @@ -47,7 +58,8 @@ console.log(document, info, pages)