Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,79 @@ async function onSave({ blob, mimeType }: ExportResult) {
</template>
```

### Editing a local file

The editor needs no server: hand it a `File` from an `<input type="file">`,
or any `Blob`, and it hands the edited image back as a `Blob`. Nothing is
uploaded or stored anywhere. The playground has a working version of this
at `?demo=local-file` (`playground/LocalFileDemo.vue`).

```vue
<script setup lang="ts">
import type { ExportResult } from '@nextcloud/image-editor'
import { shallowRef } from 'vue'
import { ImageEditor } from '@nextcloud/image-editor'

const file = shallowRef<File | null>(null)
const preview = shallowRef<string | null>(null)

function onPick(event: Event) {
file.value = (event.target as HTMLInputElement).files?.[0] ?? null
}

function onSave({ blob, mimeType }: ExportResult) {
// An object URL keeps its Blob alive: revoke the old one first,
// and the last one when the component goes away
if (preview.value !== null) {
URL.revokeObjectURL(preview.value)
}
preview.value = URL.createObjectURL(blob)
file.value = null
}

function onError(error: Error) {
// The image could not be decoded or exported. The editor stays
// open, so tell the user and let them cancel or try again.
console.error(error)
}
</script>

<template>
<ImageEditor
v-if="file"
:src="file"
:label="file.name"
@save="onSave"
@cancel="file = null"
@error="onError" />
<template v-else>
<input type="file" accept="image/*" @change="onPick">
<a v-if="preview" :href="preview" download="edited">
<img :src="preview" alt="The edited image">
</a>
</template>
</template>
```

A few things to know when the source is a `Blob` or `File`:

- The editor saves in the format the image came in: a JPEG as a JPEG,
with its EXIF, XMP and colour profile carried over; a PNG or WebP as
the same. Ask for another with `exportOptions`, e.g.
`{ format: 'image/webp', quality: 0.8 }`.
- Saving an image that was not edited hands the source bytes back as
they are.
- A `Blob` without a `type` (`new Blob([bytes])`, or a `File` with an
extension the browser does not know) still works. The editor reads
the format from the first bytes of the image, for JPEG, PNG and WebP.
For any other format the type stays unknown, and the editor saves a
PNG unless `exportOptions.format` says otherwise.
- Object URLs the editor makes to decode the image are revoked as soon
as the image is decoded. Object URLs you make for the result are
yours to revoke.
- A file that is not an image, or is corrupt, fires `error` and shows
a retry. It never leaves the editor waiting.

## API

### `<ImageEditor>`
Expand Down
65 changes: 63 additions & 2 deletions __tests__/image.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@
*/
import type { ImageWorkerClient } from '../lib/utils/image-worker.ts'

import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
import { imageWorker } from '../lib/utils/image-worker.ts'
import { canvasToBlob, decodeImage, imageSize, loadImage } from '../lib/utils/image.ts'
import { canvasToBlob, decodeImage, imageSize, loadImage, sniffImageType, sourceName } from '../lib/utils/image.ts'

vi.mock('../lib/utils/image-worker.ts', () => ({ imageWorker: vi.fn(() => null) }))

Expand Down Expand Up @@ -67,6 +67,25 @@ afterEach(() => {
Reflect.deleteProperty(URL, 'revokeObjectURL')
})

/**
* jsdom's Blob cannot hand its bytes over the way a browser's does, and
* reading the type of an untyped source starts there. FileReader is the
* one way in that jsdom does implement.
*/
function installBlobReading(): void {
Object.defineProperty(Blob.prototype, 'arrayBuffer', {
configurable: true,
value(this: Blob) {
return new Promise<ArrayBuffer>((resolve, reject) => {
const reader = new FileReader()
reader.onload = () => resolve(reader.result as ArrayBuffer)
reader.onerror = () => reject(reader.error)
reader.readAsArrayBuffer(this)
})
},
})
}

describe('loadImage', () => {
it('leaves a relative URL alone', async () => {
await loadImage('/remote.php/dav/files/admin/photo.jpg')
Expand Down Expand Up @@ -154,6 +173,48 @@ describe('imageSize', () => {
})
})

describe('sniffImageType', () => {
beforeAll(installBlobReading)
afterAll(() => Reflect.deleteProperty(Blob.prototype, 'arrayBuffer'))

/**
* A Blob with no type, starting with the given bytes.
*
* @param head the first bytes of the file
*/
const untyped = (...head: number[]) => new Blob([Uint8Array.from([...head, 0, 0, 0, 0])])
const ascii = (text: string) => [...text].map((char) => char.charCodeAt(0))

it('trusts a type the Blob already carries', async () => {
await expect(sniffImageType(new Blob(['bytes'], { type: 'image/heic' }))).resolves.toBe('image/heic')
})

it('reads a JPEG, a PNG and a WebP from their first bytes', async () => {
await expect(sniffImageType(untyped(0xFF, 0xD8, 0xFF, 0xE0))).resolves.toBe('image/jpeg')
await expect(sniffImageType(untyped(0x89, ...ascii('PNG\r\n'), 0x1A, 0x0A))).resolves.toBe('image/png')
await expect(sniffImageType(untyped(...ascii('RIFF'), 1, 2, 3, 4, ...ascii('WEBP')))).resolves.toBe('image/webp')
})

it('leaves anything else unknown', async () => {
await expect(sniffImageType(new Blob(['not an image']))).resolves.toBe('')
await expect(sniffImageType(new Blob([]))).resolves.toBe('')
})
})

describe('sourceName', () => {
it('names a File after itself, rather than "[object File]"', () => {
expect(sourceName(new File(['bytes'], 'holiday.jpg'))).toBe('holiday.jpg')
})

it('names a URL as it was given', () => {
expect(sourceName('/photos/holiday.jpg')).toBe('/photos/holiday.jpg')
})

it('has no name for a bare Blob', () => {
expect(sourceName(new Blob(['bytes']))).toBeNull()
})
})

describe('decodeImage', () => {
it('decodes bytes in the worker, where there is one', async () => {
const bitmap = { width: 200, height: 100 } as ImageBitmap
Expand Down
59 changes: 58 additions & 1 deletion __tests__/useExportImage.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
import type { EditorState } from '../lib/editor/state.ts'
import type { ExportOptions, ExportResult } from '../lib/types/export.ts'

import { afterEach, describe, expect, it, vi } from 'vitest'
import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from 'vitest'
import { useExportImage } from '../lib/composables/useExportImage.ts'
import * as render from '../lib/editor/render.ts'
import { createInitialState } from '../lib/editor/state.ts'
Expand Down Expand Up @@ -52,6 +52,25 @@ function recordingCanvas(): { asked: { type?: string, quality?: number } } {
return { asked }
}

/**
* jsdom's Blob cannot hand its bytes over the way a browser's does, and
* reading the type of an untyped source starts there. FileReader is the
* one way in that jsdom does implement.
*/
function installBlobReading(): void {
Object.defineProperty(Blob.prototype, 'arrayBuffer', {
configurable: true,
value(this: Blob) {
return new Promise<ArrayBuffer>((resolve, reject) => {
const reader = new FileReader()
reader.onload = () => resolve(reader.result as ArrayBuffer)
reader.onerror = () => reject(reader.error)
reader.readAsArrayBuffer(this)
})
},
})
}

describe('useExportImage', () => {
afterEach(() => vi.restoreAllMocks())

Expand Down Expand Up @@ -93,6 +112,44 @@ describe('useExportImage', () => {
await expect(setup(new Blob(['bytes'])).exportImage()).rejects.toThrow()
})

describe('a source that came without a type', () => {
beforeAll(installBlobReading)
afterAll(() => Reflect.deleteProperty(Blob.prototype, 'arrayBuffer'))

const edited = { ...createInitialState(), rotation: 90 as const }

/**
* The same JPEG bytes as a Blob that does not say what it is.
*
* @param quality the setting the JPEG was written at
*/
const untyped = (quality: number) => new Blob([jpegBlobAtQuality(quality)])

it('is handed back untouched, now saying it is a JPEG', async () => {
const source = untyped(85)
const result = await setup(source).exportImage()

expect(result.mimeType).toBe('image/jpeg')
expect(result.blob.type).toBe('image/jpeg')
expect(result.blob.size).toBe(source.size)
})

it('is saved as the JPEG it is, at the quality it was written at', async () => {
const { asked } = recordingCanvas()
const result = await setup(untyped(85), edited).exportImage()

expect(result.mimeType).toBe('image/jpeg')
expect(asked.type).toBe('image/jpeg')
expect(asked.quality).toBeCloseTo(0.85)
})

it('still gives way to the format the host asked for', async () => {
const { asked } = recordingCanvas()
await setup(untyped(85), edited).exportImage({ format: 'image/webp', quality: 0.6 })
expect(asked).toEqual({ type: 'image/webp', quality: 0.6 })
})
})

it('cannot pass through a source it never saw the bytes of', async () => {
await expect(setup(null).exportImage()).rejects.toThrow()
})
Expand Down
32 changes: 32 additions & 0 deletions e2e/local-file.spec.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
/**
* SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
* SPDX-License-Identifier: AGPL-3.0-or-later
*/
import { expect, test } from '@playwright/test'
import { readFile } from 'node:fs/promises'

test('edits a local file and hands the edited Blob back', async ({ page }) => {
await page.goto('/?demo=local-file')
await page.getByLabel('Pick an image to edit').setInputFiles({
name: 'holiday.jpg',
mimeType: 'image/jpeg',
buffer: await readFile(new URL('../playground/with-metadata.jpg', import.meta.url)),
})

await page.getByRole('button', { name: 'Rotate right' }).click()
await page.getByRole('button', { name: 'Save', exact: true }).click()

const result = page.locator('[data-test="local-result"]')
await expect(result).toContainText('image/jpeg')
const download = result.getByRole('link')
await expect(download).toHaveAttribute('download', 'holiday-edited.jpg')

// The link points at the edited Blob itself
const blob = await download.evaluate(async (link: HTMLAnchorElement) => {
const saved = await (await fetch(link.href)).blob()
return { type: saved.type, size: saved.size }
})
expect(blob.type).toBe('image/jpeg')
expect(blob.size).toBeGreaterThan(0)
await expect(page.getByRole('alert')).toHaveCount(0)
})
5 changes: 3 additions & 2 deletions lib/components/ImageEditor.vue
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ import { clampRect, createInitialState, duplicateAnnotation, flipHorizontal, fli
import { attachPointerTools } from '../editor/tools.ts'
import { clampPan, panBounds, VIEW_MARGIN } from '../editor/view.ts'
import { fitContain } from '../utils/geometry.ts'
import { decodeImage, imageSize } from '../utils/image.ts'
import { decodeImage, imageSize, sourceName } from '../utils/image.ts'
import { t } from '../utils/l10n.ts'

const props = defineProps<{
Expand Down Expand Up @@ -92,6 +92,7 @@ const labels = {
tooLarge: t('This image is larger than this browser can edit'),
tooLargeConfirm: t('Continue with a smaller copy'),
tooLargeReject: t('Close the editor'),
unnamed: t('This image'),
}

/**
Expand All @@ -109,7 +110,7 @@ function confirmDownscale(full: Size, fit: number): Promise<boolean> {
text: t(
'{name} is {source} megapixels and this browser can only edit {limit}. Continuing means the saved image is {width} by {height} pixels instead, and the detail beyond that is lost.',
{
name: props.label ?? props.src.toString(),
name: props.label ?? sourceName(props.src) ?? labels.unnamed,
source: String(megapixels(full)),
limit: String(megapixels({ width: full.width * fit, height: full.height * fit })),
width: String(Math.floor(full.width * fit)),
Expand Down
Loading
Loading