asljs-ui-file 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,51 @@
+# Permissive No-Derivatives License 1.0
+
+Copyright (c) 2026 Alexandrite Software Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software (the "Software") to:
+
+1. Use the Software for any purpose, including commercial purposes.
+2. Copy and redistribute the Software, including as part of another application,
+   library, or package.
+3. Modify the Software for private or internal use.
+
+Subject to the following conditions:
+
+## 1. No Distribution of Modified Versions
+
+Modified versions of the Software, or substantial portions thereof, must not be
+distributed without prior written permission from the copyright holder.
+
+Routine build transformations, including minification, transpilation, and
+bundling, are permitted for distribution, provided they do not intentionally
+alter the Software's functionality.
+
+## 2. Licence and Copyright Preservation
+
+All distributed copies of the Software must retain this copyright notice and
+licence.
+
+The Software itself, including copies incorporated into other applications,
+libraries, or packages, remains subject to this licence.
+
+The Software must not be sublicensed or redistributed under a different licence.
+
+## 3. Use in Other Software
+
+Applications and libraries that merely use, import, link to, or bundle the
+Software are not considered modified versions of the Software and may be
+distributed under any licence.
+
+Such use, incorporation, or bundling does not grant permission to relicense the
+Software or distribute modified versions of it.
+
+### 4. No Warranty
+
+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 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# file
 
-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.
+> Part of [Alexandrite Software Library][#1] - a set of high-quality, performant
+> JavaScript libraries and tools for everyday use.
+
+## Overview
+
+`asljs-ui-file` provides `asljs-file`, a file view that renders one file through
+an ordered list of display handlers. A provider loads the file, and the first
+handler that can display it renders it.
+
+## Scope
+
+- Handlers for PDF, image, text and editable text files, and your own.
+- Text editing persists through the provider's optional `saveText`.
+- A fallback "Preview unavailable" view, with an Open link when the content
+  allows one.
+
+## Installation
+
+```bash
+npm install asljs-ui-file
+```
+
+NPM package: [asljs-ui-file][NPM]
+
+## Usage
+
+Import the package to register the element and get the handlers:
+
+```ts
+import { createImageFileHandler,
+         createPdfFileHandler,
+         createTextFileHandler }
+  from 'asljs-ui-file';
+
+const fileView =
+  document.createElement('asljs-file') as HTMLElement & {
+    provider: { loadFile: (fileName: string) => Promise<unknown> } | null;
+    handlers: unknown[];
+    fileName: string | null;
+  };
+
+fileView.provider =
+  { loadFile: async fileName => ({ name: fileName, text: 'Hello' }) };
+
+fileView.handlers =
+  [ createPdfFileHandler(),
+    createImageFileHandler(),
+    createTextFileHandler() ];
+
+fileView.fileName = 'notes.txt';
+
+document.body.appendChild(fileView);
+```
+
+## Further reading
+
+- [File][DOC] - the provider, the handlers and the fallback view.
+
+Questions and bugs: [asljs/issues][ISS].
+
+## Related packages
+
+- [ui][UI] - the shared code and the other UI packages.
+
+## License
+
+MIT License. See [LICENSE][LIC] for details.
+
+[#1]: https://github.com/AlexandriteSoftware/asljs
+[DOC]: docs/File.md
+[ISS]: https://github.com/AlexandriteSoftware/asljs/issues
+[LIC]: LICENSE.md
+[NPM]: https://www.npmjs.com/package/asljs-ui-file
+[UI]: ../core/README.md

package/dist/file.d.ts

@@ -0,0 +1,41 @@
+import { ComponentModelDefinition } from 'asljs-ui';
+import { LitElement } from 'lit';
+export declare const FileViewModelDefinition: ComponentModelDefinition;
+export interface FileViewData {
+    name: string;
+    mimeType?: string | null;
+    blob?: Blob | null;
+    text?: string | null;
+    dataUrl?: string | null;
+}
+export interface FileViewProvider {
+    loadFile: (fileName: string) => Promise<FileViewData | null>;
+    saveText?: (fileName: string, text: string) => Promise<void> | void;
+}
+export interface FileHandlerRenderResult {
+    element: HTMLElement;
+    dispose?: () => void;
+}
+export interface FileHandlerRenderContext {
+    file: FileViewData;
+    fileName: string;
+    provider: FileViewProvider;
+}
+export interface FileHandler {
+    canDisplay: (file: FileViewData) => boolean | Promise<boolean>;
+    render: (context: FileHandlerRenderContext) => Promise<FileHandlerRenderResult> | FileHandlerRenderResult;
+}
+export declare class FileView extends LitElement {
+    #private;
+    accessor provider: FileViewProvider | null;
+    accessor handlers: FileHandler[];
+    accessor fileName: string | null;
+    createRenderRoot(): this;
+    disconnectedCallback(): void;
+    render(): ReturnType<LitElement['render']>;
+    updated(changedProperties: Map<PropertyKey, unknown>): void;
+}
+export declare function createPdfFileHandler(): FileHandler;
+export declare function createImageFileHandler(): FileHandler;
+export declare function createTextFileHandler(): FileHandler;
+export declare function createTextEditorFileHandler(): FileHandler;

package/dist/file.js

@@ -0,0 +1,315 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { defineComponentModel } from 'asljs-ui';
+import { html, LitElement } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+export const FileViewModelDefinition = { name: 'FileViewModelDefinition',
+    title: 'File View',
+    properties: [{ name: 'provider',
+            title: 'Provider',
+            type: 'object',
+            description: 'File provider used to load and optionally save files.' },
+        { name: 'handlers',
+            title: 'Handlers',
+            type: 'array',
+            description: 'Ordered file handlers from most specific to most general.' },
+        { name: 'fileName',
+            title: 'File name',
+            type: 'string',
+            description: 'Selected file name to preview.' }] };
+defineComponentModel('asljs-file', FileViewModelDefinition);
+let FileView = class FileView extends LitElement {
+    #activeRenderState = null;
+    #renderRequestId = 0;
+    #provider_accessor_storage = null;
+    get provider() { return this.#provider_accessor_storage; }
+    set provider(value) { this.#provider_accessor_storage = value; }
+    #handlers_accessor_storage = [];
+    get handlers() { return this.#handlers_accessor_storage; }
+    set handlers(value) { this.#handlers_accessor_storage = value; }
+    #fileName_accessor_storage = null;
+    get fileName() { return this.#fileName_accessor_storage; }
+    set fileName(value) { this.#fileName_accessor_storage = value; }
+    createRenderRoot() {
+        return this;
+    }
+    disconnectedCallback() {
+        this.#disposeActiveRender();
+        super.disconnectedCallback();
+    }
+    render() {
+        return html `
+      <div data-role="content"></div>
+    `;
+    }
+    updated(changedProperties) {
+        if (changedProperties.has('provider')
+            || changedProperties.has('handlers')
+            || changedProperties.has('fileName')) {
+            void this.#refresh();
+        }
+    }
+    async #refresh() {
+        const requestId = ++this.#renderRequestId;
+        this.#disposeActiveRender();
+        const contentHost = this.querySelector('[data-role="content"]');
+        if (contentHost === null) {
+            return;
+        }
+        if (this.fileName === null
+            || this.fileName.trim() === '') {
+            contentHost.replaceChildren(createMessageElement('Select a file to preview.'));
+            return;
+        }
+        const provider = this.provider;
+        if (provider === null) {
+            contentHost.replaceChildren(createMessageElement('File provider is not configured.'));
+            return;
+        }
+        contentHost.replaceChildren(createMessageElement('Loading preview...'));
+        const file = await provider.loadFile(this.fileName);
+        if (requestId
+            !== this.#renderRequestId) {
+            return;
+        }
+        if (file === null) {
+            contentHost.replaceChildren(createMessageElement('File content is not available.'));
+            return;
+        }
+        const handler = await findHandler(this.handlers, file);
+        if (requestId
+            !== this.#renderRequestId) {
+            return;
+        }
+        if (handler === null) {
+            const fallback = createFallbackElement(file);
+            this.#activeRenderState =
+                { dispose: fallback.dispose };
+            contentHost.replaceChildren(fallback.element);
+            return;
+        }
+        const result = await handler.render({ file,
+            fileName: this.fileName,
+            provider });
+        if (requestId
+            !== this.#renderRequestId) {
+            result.dispose?.();
+            return;
+        }
+        this.#activeRenderState =
+            { dispose: result.dispose };
+        contentHost.replaceChildren(result.element);
+    }
+    #disposeActiveRender() {
+        this.#activeRenderState?.dispose?.();
+        this.#activeRenderState = null;
+    }
+};
+__decorate([
+    property({ attribute: false })
+], FileView.prototype, "provider", null);
+__decorate([
+    property({ attribute: false })
+], FileView.prototype, "handlers", null);
+__decorate([
+    property({ attribute: false })
+], FileView.prototype, "fileName", null);
+FileView = __decorate([
+    customElement('asljs-file')
+], FileView);
+export { FileView };
+export function createPdfFileHandler() {
+    return { canDisplay: file => isPdfFile(file),
+        render: async ({ file }) => {
+            const source = await getObjectUrlSource(file);
+            if (source === null) {
+                return createUnavailableResult();
+            }
+            const frame = document.createElement('iframe');
+            frame.src =
+                `${source.url}#toolbar=1&navpanes=0`;
+            frame.title = file.name;
+            frame.referrerPolicy = 'no-referrer';
+            frame.style.width = '100%';
+            frame.style.height = '100%';
+            frame.style.minHeight = '32rem';
+            frame.style.border = '0';
+            return { element: frame,
+                dispose: source.dispose };
+        } };
+}
+export function createImageFileHandler() {
+    return { canDisplay: file => isImageFile(file),
+        render: async ({ file }) => {
+            const source = await getObjectUrlSource(file);
+            if (source === null) {
+                return createUnavailableResult();
+            }
+            const image = document.createElement('img');
+            image.src = source.url;
+            image.alt = file.name;
+            image.style.display = 'block';
+            image.style.maxWidth = '100%';
+            image.style.maxHeight = '100%';
+            image.style.objectFit = 'contain';
+            return { element: image,
+                dispose: source.dispose };
+        } };
+}
+export function createTextFileHandler() {
+    return { canDisplay: file => isTextFile(file),
+        render: async ({ file }) => {
+            const text = await resolveText(file);
+            if (text === null) {
+                return createUnavailableResult();
+            }
+            const pre = document.createElement('pre');
+            pre.textContent = text;
+            pre.style.margin = '0';
+            pre.style.whiteSpace = 'pre-wrap';
+            return { element: pre };
+        } };
+}
+export function createTextEditorFileHandler() {
+    return { canDisplay: file => isTextFile(file),
+        render: async ({ file, fileName, provider }) => {
+            const text = await resolveText(file);
+            if (text === null) {
+                return createUnavailableResult();
+            }
+            const textArea = document.createElement('textarea');
+            textArea.value = text;
+            textArea.disabled = provider.saveText === undefined;
+            textArea.spellcheck = false;
+            textArea.style.width = '100%';
+            textArea.style.height = '100%';
+            textArea.style.minHeight = '16rem';
+            textArea.style.border = '0';
+            textArea.style.resize = 'none';
+            textArea.style.padding = '0.75rem';
+            textArea.style.fontFamily =
+                'SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace';
+            textArea.style.fontSize = '0.8rem';
+            textArea.style.lineHeight = '1.6';
+            textArea.style.boxSizing = 'border-box';
+            if (provider.saveText !== undefined) {
+                textArea.addEventListener('blur', () => {
+                    void provider.saveText?.(fileName, textArea.value);
+                });
+            }
+            return { element: textArea };
+        } };
+}
+async function findHandler(handlers, file) {
+    for (const handler of handlers) {
+        if (await handler.canDisplay(file)) {
+            return handler;
+        }
+    }
+    return null;
+}
+function createMessageElement(text) {
+    const element = document.createElement('div');
+    element.textContent = text;
+    element.style.color =
+        'var(--bs-secondary-color, #6c757d)';
+    return element;
+}
+function createUnavailableResult() {
+    return { element: createMessageElement('Preview unavailable for this file type.') };
+}
+function createFallbackElement(file) {
+    const root = document.createElement('div');
+    root.style.display = 'flex';
+    root.style.alignItems = 'center';
+    root.style.gap = '0.5rem';
+    const message = createMessageElement('Preview unavailable for this file type.');
+    root.appendChild(message);
+    if (file.blob
+        || file.dataUrl) {
+        const link = document.createElement('a');
+        link.textContent = 'Open';
+        link.target = '_blank';
+        link.rel =
+            'noopener noreferrer';
+        if (file.dataUrl) {
+            link.href = file.dataUrl;
+            root.appendChild(link);
+            return { element: root };
+        }
+        const url = URL.createObjectURL(file.blob);
+        link.href = url;
+        root.appendChild(link);
+        return { element: root,
+            dispose: () => {
+                URL.revokeObjectURL(url);
+            } };
+    }
+    return { element: root };
+}
+async function getObjectUrlSource(file) {
+    if (file.dataUrl) {
+        return { url: file.dataUrl };
+    }
+    if (file.blob) {
+        if (isPdfFile(file)
+            && normalizeMimeType(file.mimeType ?? file.blob.type)
+                !== 'application/pdf') {
+            const pdfBlob = new Blob([await file.blob.arrayBuffer()], { type: 'application/pdf' });
+            const pdfUrl = URL.createObjectURL(pdfBlob);
+            return { url: pdfUrl,
+                dispose: () => {
+                    URL.revokeObjectURL(pdfUrl);
+                } };
+        }
+        const url = URL.createObjectURL(file.blob);
+        return { url,
+            dispose: () => {
+                URL.revokeObjectURL(url);
+            } };
+    }
+    return null;
+}
+async function resolveText(file) {
+    if (typeof file.text
+        === 'string') {
+        return file.text;
+    }
+    if (file.blob
+        && isTextFile(file)) {
+        return await file.blob.text();
+    }
+    return null;
+}
+function isPdfFile(file) {
+    return normalizeMimeType(file.mimeType ?? file.blob?.type)
+        === 'application/pdf'
+        || getLowerFileName(file).endsWith('.pdf');
+}
+function isImageFile(file) {
+    const mimeType = normalizeMimeType(file.mimeType ?? file.blob?.type);
+    return mimeType.startsWith('image/')
+        || /\.(png|jpg|jpeg|gif|webp|svg)$/i.test(file.name);
+}
+function isTextFile(file) {
+    if (typeof file.text
+        === 'string') {
+        return true;
+    }
+    const mimeType = normalizeMimeType(file.mimeType ?? file.blob?.type);
+    return mimeType.startsWith('text/')
+        || ['application/json',
+            'application/xml',
+            'image/svg+xml'].includes(mimeType)
+        || /\.(txt|csv|json|xml|html|htm|md|markdown|svg)$/i.test(file.name);
+}
+function normalizeMimeType(mimeType) {
+    return (mimeType ?? '').trim().toLowerCase();
+}
+function getLowerFileName(file) {
+    return file.name.toLowerCase();
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { createImageFileHandler, createPdfFileHandler, createTextEditorFileHandler, createTextFileHandler, FileView, FileViewModelDefinition, type FileHandler, type FileHandlerRenderContext, type FileHandlerRenderResult, type FileViewData, type FileViewProvider } from './file.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { createImageFileHandler, createPdfFileHandler, createTextEditorFileHandler, createTextFileHandler, FileView, FileViewModelDefinition } from './file.js';

package/docs/File.md

@@ -0,0 +1,69 @@
+# File
+
+`asljs-file` (`FileView`) renders one file through an ordered list of display
+handlers.
+
+## Properties
+
+- `provider` — `provider.loadFile(fileName)` returns normalized file data;
+  `provider.saveText(...)` persists edits when text editing is used
+- `handlers` — ordered from most specific to most general
+- `fileName` — the file to show
+
+The component asks the handlers in order whether they can display the file, and
+the first match renders it. The component itself does not hard-code file types:
+those decisions belong to the handlers, and providers abstract file lookup and
+optional text persistence.
+
+## Handlers
+
+`asljs-ui-file` provides these handler factories:
+
+- `createPdfFileHandler()`
+- `createImageFileHandler()`
+- `createTextFileHandler()`
+- `createTextEditorFileHandler()`
+
+If no handler matches, the component shows fallback "Preview unavailable"
+content, and an Open link when blob or data-url content is available.
+
+## Usage
+
+```ts
+import {
+    createImageFileHandler,
+    createPdfFileHandler,
+    createTextFileHandler,
+  } from 'asljs-ui-file';
+
+const fileView =
+  document.createElement('asljs-file') as HTMLElement & {
+    provider: {
+      loadFile: (fileName: string) => Promise<unknown>;
+    } | null;
+    handlers: unknown[];
+    fileName: string | null;
+  };
+
+fileView.provider =
+  { loadFile: async (fileName: string) => {
+      if (fileName === 'invoice.pdf') {
+        return {
+          name: 'invoice.pdf',
+          blob: new Blob([ 'pdf' ], { type: 'application/pdf' }),
+        };
+      }
+
+      return {
+        name: fileName,
+        text: 'No content',
+      };
+    } };
+
+fileView.handlers =
+  [ createPdfFileHandler(),
+    createImageFileHandler(),
+    createTextFileHandler() ];
+
+fileView.fileName = 'invoice.pdf';
+```

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "asljs-ui-file",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "A file view web component with pluggable display handlers.",
+  "type": "module",
+  "asljs": {
+    "type": "lib"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE.md",
+    "docs/**"
+  ],
+  "scripts": {
+    "flint": "toolkit flint",
+    "clean": "toolkit clean",
+    "build": "npm run codegen --if-present && tsc -p tsconfig.build.json",
+    "build:dist": "npm run codegen --if-present && tsc -p tsconfig.dist.json",
+    "typecheck": "npm run codegen --if-present && tsc -p tsconfig.build.json --noEmit",
+    "guard:clean-git": "toolkit ensure-clean-working-directory",
+    "prepack": "npm run clean && npm run build:dist && npm run build && npm run test && npm run guard:clean-git",
+    "postpublish": "toolkit tag-release-revision",
+    "test": "node --test --enable-source-maps \"build/**/*.test.js\"",
+    "test:watch": "node --watch --test \"build/**/*.test.js\"",
+    "coverage": "npm run build && node --test --experimental-test-coverage --enable-source-maps --test-coverage-exclude=\"**/*.test.js\" \"build/**/*.test.js\"",
+    "release:patch": "toolkit release-patch",
+    "all": "npm run clean && npm run build:dist && npm run flint && npm run typecheck && npm run build && npm run test"
+  },
+  "keywords": [
+    "web-components",
+    "lit",
+    "ui",
+    "file",
+    "viewer"
+  ],
+  "author": "\"Alex Netkachov\" <alex.netkachov@gmail.com>",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "homepage": "https://github.com/AlexandriteSoftware/asljs#readme",
+  "bugs": {
+    "url": "https://github.com/AlexandriteSoftware/asljs/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexandriteSoftware/asljs.git"
+  },
+  "dependencies": {
+    "asljs-ui": "^0.1.1",
+    "lit": "^3.3.1"
+  },
+  "devDependencies": {
+    "asljs-testing": "^0.1.1",
+    "asljs-toolkit": "^0.1.0"
+  }
+}