@filens/vue 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FiLens contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# @filens/vue
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vue 3 components for the shared preview engines: `Preview` is the all-format entry;
+`PptxPreview` and `IworkPreview` provide specialized viewers. For a ready-to-deploy
+single JS file or split modules including Vue, see the [standalone builds](../preview/README.md).
+
+## All-format entry
+
+```vue
+<script setup lang="ts">
+import { Preview } from '@filens/vue';
+import '@filens/vue/style.css';
+</script>
+
+<template>
+  <Preview src="/report.pdf" name="report.pdf" />
+</template>
+```
+
+`src` also accepts a `File`, `Blob` or byte array; provide `name` or `extension`
+when the source has no filename. Legacy Office and RAW previews need a
+`converter` configured with `createWasmConverterClient({ wasm, imageWasm, officeWasm })`
+from `@filens/converter-client`. See the demo for complete WASM asset wiring.
+
+`officeWasm` points to the optional `converter-office.wasm` asset. The current
+core detects encrypted Office documents itself and loads this module only after
+password submission. Omitting it retains ordinary conversions and password
+prompts; encrypted conversions with a supplied password return `engine_unavailable`.
+The standalone `@filens/preview` builds wire the module automatically.
+
+## Languages (source build)
+
+All three preview components accept `locale` and `messages`. Toolbars, model
+controls, loading states and password prompts include 28 locale dictionaries,
+using the same codes as ZimaOS:
+
+```text
+en_US en_GB it_IT nb_NO zh_CN zh_TW ja_JP ko_KR fr_FR de_DE sv_SE da_DK
+nl_NL es_ES ca_ES pt_PT pt_BR pl_PL cs_CZ sk_SK hu_HU ro_RO hr_HR ru_RU
+tr_TR el_GR ga_IE ml_IN
+```
+
+BCP 47 tags such as `zh-CN`, `zh-Hant` and `pt-BR` also work. Omit `locale` to
+use the browser's preferred supported language; unsupported languages fall back
+to English. Locale changes update controls without reopening the document.
+Translations are ordinary strings rendered as text, with no `vue-i18n` dependency.
+Document content, source warnings and driver errors retain their original text.
+
+```vue
+<Preview :src="file" :locale="zimaosLocale" :messages="{ Next: 'Forward' }" />
+```
+
+`messages` maps English source phrases to host strings for that component only.
+For example, `Warnings: {count}` preserves its named placeholder. Exported
+`previewLocales` lists available codes; `resolvePreviewLocale()` normalizes host
+locale tags. Standalone `createPreview()` accepts the same options and supports
+`viewer.update({ locale: 'ja_JP' })`.
+
+## Application icons (source build)
+
+APK and IPA packages open as ZIP-compatible archives by default, with directory
+browsing and entry previews. Windows EXE/DLL/MUI/MUN resource containers use the
+shared WASM core to extract their application icon as PNG, then display it with
+the normal image controls. The core also converts ICO to PNG; browser-native ICO
+preview and existing ICNS preview remain available. No application is executed.
+Configure `converter` as for legacy Office previews. APK/IPA icon extraction is
+available through explicit conversion requests.
+
+APK extraction follows the application's compiled manifest icon resource through
+`resources.arsc`, including obfuscated paths and raster-backed adaptive XML. IPA
+extraction uses the main `.app` bundle's XML or binary plist icon declarations,
+selects the largest raster and normalizes iOS CgBI PNGs. PE extraction uses resource
+RVA mapping and icon group IDs, with PNG and 1/4/8/24/32-bit DIB frames and masks.
+Vector-only Android icons, asset-catalog-only IPA icons, legacy ICNS planes,
+JPEG 2000 icons and OS-resolved `.app`/`.desktop` folder icons are not decoded.
+Missing or unsupported icons produce a parse error.
+
+## Install
+
+```bash
+npm install @filens/vue @filens/core @filens/iwork
+```
+
+`vue` is a peer dependency and must be provided by the host app.
+
+## Password-protected documents
+
+The generic `Preview` component prompts for passwords when opening encrypted PDFs
+and Office documents. Configure its `converter` with `createWasmConverterClient()`
+for Office decryption in the browser. Supported Office encryption includes Agile,
+Office 2007 Standard, legacy RC4 CryptoAPI and XLS XOR obfuscation; rights-managed
+documents and other unsupported encryption methods report a format error.
+
+The password form supports incorrect-password retries, cancellation and reopening.
+It clears the entered password after submission, cancellation or changing files.
+The optional `password` prop supplies a known password; `requestPassword` replaces
+the built-in form with a host callback using `PreviewOptions['requestPassword']`.
+
+## Usage
+
+```vue
+<script setup lang="ts">
+import { IworkPreview, PptxPreview } from '@filens/vue';
+import '@filens/vue/style.css';
+
+const src = '/samples/sample-deck.pptx';
+const keySrc = '/samples/a.key';
+</script>
+
+<template>
+  <PptxPreview :src="src" fit="contain" :toolbar="true" :thumbnails="true" />
+  <IworkPreview :src="keySrc" type="key" :toolbar="true" :thumbnails="true" />
+</template>
+```
+
+## `PptxPreview` Props
+
+```ts
+interface PptxPreviewProps {
+  src: string | ArrayBuffer | Uint8Array | Blob | File;
+  fit?: 'contain' | 'width' | 'none';
+  initialScale?: number;
+  minScale?: number;
+  maxScale?: number;
+  toolbar?: boolean;
+  thumbnails?: boolean;
+}
+```
+
+## `PptxPreview` Emits
+
+- `rendered`
+- `error`
+- `slide-change`
+- `scale-change`
+- `warnings`
+
+## `IworkPreview` Props
+
+```ts
+interface IworkPreviewProps {
+  src: string | ArrayBuffer | Uint8Array | Blob | File;
+  type?: 'auto' | 'key' | 'pages' | 'numbers';
+  initialScale?: number;
+  minScale?: number;
+  maxScale?: number;
+  toolbar?: boolean;
+  thumbnails?: boolean;
+}
+```
+
+## `IworkPreview` Emits
+
+- `rendered`
+- `error`
+- `warnings`
+- `page-change`
+- `sheet-change`
+- `scale-change`
+
+## Behavior
+
+The components are designed to feel close to the `vue-office` direct-`src` usage pattern:
+
+- pass `src` directly as a URL or binary source
+- source changes trigger a fresh preview automatically
+- the old preview task is discarded by the viewer lifecycle
+- toolbar and thumbnails are built in
+- `IworkPreview` automatically switches between paged and sheet-oriented behavior depending on document kind
+
+## Included UI
+
+- top toolbar
+- left thumbnail rail
+- main preview area
+- zoom in / out
+- fit to page
+- fit to width
+- previous / next slide
+- previous / next iWork page or sheet where applicable
+- keyboard navigation when the shell is focused
+
+## Dist Output
+
+Build output:
+
+- `dist/index.js`
+- `dist/style.css`
+- `dist/index.d.ts`
+
+Import CSS with:
+
+```ts
+import '@filens/vue/style.css';
+```
+
+## Scope
+
+This package is for client-side Vue 3 apps in modern browsers. It is not currently positioned as an SSR-first or full Office/iWork-compatibility renderer.

package/dist/IworkPreview.vue.d.ts

@@ -0,0 +1,40 @@
+import { PreviewMessages } from './i18n';
+import { IworkFitMode, IworkSource, IworkTypeHint, ParsedIworkDocument } from '@filens/iwork';
+type __VLS_Props = {
+    src: IworkSource;
+    type?: IworkTypeHint;
+    fit?: IworkFitMode;
+    initialScale?: number;
+    minScale?: number;
+    maxScale?: number;
+    toolbar?: boolean;
+    locale?: string;
+    messages?: PreviewMessages;
+    thumbnails?: boolean;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    rendered: (document: ParsedIworkDocument | null) => any;
+    error: (error: Error) => any;
+    warnings: (warnings: string[]) => any;
+    "page-change": (pageIndex: number) => any;
+    "sheet-change": (sheetIndex: number) => any;
+    "scale-change": (scale: number) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onRendered?: ((document: ParsedIworkDocument | null) => any) | undefined;
+    onError?: ((error: Error) => any) | undefined;
+    onWarnings?: ((warnings: string[]) => any) | undefined;
+    "onPage-change"?: ((pageIndex: number) => any) | undefined;
+    "onSheet-change"?: ((sheetIndex: number) => any) | undefined;
+    "onScale-change"?: ((scale: number) => any) | undefined;
+}>, {
+    type: IworkTypeHint;
+    initialScale: number;
+    minScale: number;
+    maxScale: number;
+    toolbar: boolean;
+    thumbnails: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    shellRef: HTMLDivElement;
+    viewerHost: HTMLDivElement;
+}, HTMLDivElement>;
+export default _default;

package/dist/PptxPreview.vue.d.ts

@@ -0,0 +1,38 @@
+import { PreviewMessages } from './i18n';
+import { FitMode, ParsedPresentation, PptxSource } from '@filens/core';
+type __VLS_Props = {
+    src: PptxSource;
+    fit?: FitMode;
+    initialScale?: number;
+    minScale?: number;
+    maxScale?: number;
+    toolbar?: boolean;
+    locale?: string;
+    messages?: PreviewMessages;
+    thumbnails?: boolean;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    rendered: (presentation: ParsedPresentation | null) => any;
+    error: (error: Error) => any;
+    warnings: (warnings: string[]) => any;
+    "scale-change": (scale: number) => any;
+    "slide-change": (slideIndex: number) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onRendered?: ((presentation: ParsedPresentation | null) => any) | undefined;
+    onError?: ((error: Error) => any) | undefined;
+    onWarnings?: ((warnings: string[]) => any) | undefined;
+    "onScale-change"?: ((scale: number) => any) | undefined;
+    "onSlide-change"?: ((slideIndex: number) => any) | undefined;
+}>, {
+    fit: FitMode;
+    initialScale: number;
+    minScale: number;
+    maxScale: number;
+    toolbar: boolean;
+    thumbnails: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    shellRef: HTMLDivElement;
+    sidebarRef: HTMLElement;
+    viewerHost: HTMLDivElement;
+}, HTMLDivElement>;
+export default _default;

package/dist/Preview.vue.d.ts

@@ -0,0 +1,140 @@
+import { PreviewMessages } from './i18n';
+import { ConverterClient, FormatDefinition, PreviewDriver, PreviewFitMode, PreviewFontResolver, PreviewFontLoadingOptions, PreviewItemState, PreviewOptions, PreviewResourceResolver, PreviewSource, SourceDescriptor } from '@filens/core';
+import { MediaPreviewDriverOptions } from '../../media/dist/index.js';
+type __VLS_Props = {
+    src: PreviewSource | SourceDescriptor;
+    name?: string;
+    extension?: string;
+    contentType?: string;
+    password?: string;
+    requestPassword?: PreviewOptions['requestPassword'];
+    fit?: PreviewFitMode;
+    initialScale?: number;
+    minScale?: number;
+    maxScale?: number;
+    toolbar?: boolean | 'minimal';
+    locale?: string;
+    messages?: PreviewMessages;
+    drivers?: PreviewDriver[];
+    routes?: FormatDefinition[];
+    converter?: ConverterClient;
+    mediaConverter?: ConverterClient;
+    browserMedia?: MediaPreviewDriverOptions['browserMedia'];
+    fontResolver?: PreviewFontResolver;
+    fontLoading?: boolean | PreviewFontLoadingOptions;
+    resourceResolver?: PreviewResourceResolver;
+    audio?: PreviewOptions['audio'];
+    panoramaProcessor?: MediaPreviewDriverOptions['panoramaProcessor'];
+};
+declare function previousPage(): void;
+declare function nextPage(): void;
+declare function goToIndex(index: number): void;
+declare const _default: import('vue').DefineComponent<__VLS_Props, {
+    goToIndex: typeof goToIndex;
+    next: typeof nextPage;
+    prev: typeof previousPage;
+    fit: (mode?: PreviewFitMode) => void;
+    setScale: (nextScale: number) => void;
+    rotate: (degrees?: number) => void;
+    getState: () => {
+        loading: boolean;
+        error: string | null;
+        title?: string | undefined;
+        family: import('@filens/core').PreviewFamily;
+        warnings: string[];
+        fonts?: {
+            fontId?: string | undefined;
+            fontFamily?: string | undefined;
+            fontFile?: string | undefined;
+            styleName?: string | undefined;
+            resolvedFontFamily?: string | undefined;
+            status: import('@filens/core').PreviewFontStatus;
+            source: import('@filens/core').PreviewFontSource;
+            classification?: {
+                evidence: "metadata" | "known" | "name" | "unknown";
+                serif?: boolean | undefined;
+                monospace?: boolean | undefined;
+                style?: "text" | "handwriting" | "decorative" | "symbol" | undefined;
+                script?: "latin" | "cjk-sc" | "cjk-tc" | "japanese" | "korean" | "emoji" | undefined;
+                panose?: string | undefined;
+                weight?: number | undefined;
+                stretch?: number | undefined;
+                averageWidth?: number | undefined;
+            } | undefined;
+            substitutionReason?: string | undefined;
+            matchScore?: number | undefined;
+            coverage?: "matched" | "unknown" | undefined;
+            embedded?: boolean | undefined;
+        }[] | undefined;
+        capabilities: {
+            search?: boolean | undefined;
+            zoom?: boolean | undefined;
+            fit?: boolean | undefined;
+            paged?: boolean | undefined;
+            thumbnails?: boolean | undefined;
+            workbook?: boolean | undefined;
+            pan?: boolean | undefined;
+            rotate?: boolean | undefined;
+            fullscreen?: boolean | undefined;
+            playback?: boolean | undefined;
+            playlist?: boolean | undefined;
+            timeline?: boolean | undefined;
+            volume?: boolean | undefined;
+            subtitles?: boolean | undefined;
+            chapters?: boolean | undefined;
+            sheets?: boolean | undefined;
+            outline?: boolean | undefined;
+            codeHighlight?: boolean | undefined;
+            lineNumbers?: boolean | undefined;
+            wordWrap?: boolean | undefined;
+            minimap?: boolean | undefined;
+            archiveBrowse?: boolean | undefined;
+            layers?: boolean | undefined;
+            measure?: boolean | undefined;
+            section?: boolean | undefined;
+            orbit?: boolean | undefined;
+            explode?: boolean | undefined;
+            modelTree?: boolean | undefined;
+            metadata?: boolean | undefined;
+            materialFilter?: boolean | undefined;
+            displayMode?: boolean | undefined;
+            print?: boolean | undefined;
+            download?: boolean | undefined;
+        };
+    };
+}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {} & {
+    rendered: (state: PreviewItemState) => any;
+    error: (error: Error) => any;
+    warnings: (warnings: string[]) => any;
+    "page-change": (pageIndex: number) => any;
+    "sheet-change": (sheetIndex: number) => any;
+    "scale-change": (scale: number) => any;
+    "state-change": (state: PreviewItemState) => any;
+}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onRendered?: ((state: PreviewItemState) => any) | undefined;
+    onError?: ((error: Error) => any) | undefined;
+    onWarnings?: ((warnings: string[]) => any) | undefined;
+    "onPage-change"?: ((pageIndex: number) => any) | undefined;
+    "onSheet-change"?: ((sheetIndex: number) => any) | undefined;
+    "onScale-change"?: ((scale: number) => any) | undefined;
+    "onState-change"?: ((state: PreviewItemState) => any) | undefined;
+}>, {
+    initialScale: number;
+    minScale: number;
+    maxScale: number;
+    toolbar: boolean | "minimal";
+    browserMedia: boolean | import('../../media/dist/index.js').BrowserMediaOptions;
+    panoramaProcessor: import('@filens/panorama').PanoramaProcessor;
+    drivers: PreviewDriver[];
+    routes: FormatDefinition[];
+    converter: ConverterClient;
+    mediaConverter: ConverterClient;
+    fontResolver: PreviewFontResolver;
+    fontLoading: boolean | PreviewFontLoadingOptions;
+    resourceResolver: PreviewResourceResolver;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    shellRef: HTMLDivElement;
+    viewerHost: HTMLDivElement;
+    passwordField: HTMLInputElement;
+}, HTMLDivElement>;
+export default _default;

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

@@ -0,0 +1,12 @@
+import { ParsedPresentation, SlideModel } from '@filens/core';
+type __VLS_Props = {
+    slide: SlideModel;
+    presentation: ParsedPresentation;
+    mediaRegistry: {
+        getUrl(mediaId: string): string;
+    } | null;
+};
+declare const _default: import('vue').DefineComponent<__VLS_Props, {}, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import('vue').ComponentProvideOptions, false, {
+    host: HTMLDivElement;
+}, HTMLDivElement>;
+export default _default;

package/dist/defaults.d.ts

@@ -0,0 +1,4 @@
+import { FormatDefinition } from '@filens/core';
+export declare function createVueDefaultPreviewRoutes(options?: {
+    rawPreview?: boolean;
+}): FormatDefinition[];