@octane-xplat/files 0.9.0 → 0.11.0

package/src/files.web.ts

@@ -1,27 +1,109 @@
 // Files — web leaf. Desktop webview hosts own real pickers and file:// refs;
 // outside a host this uses opaque object URLs and browser downloads.
 import { desktopHost } from '@octane-xplat/platform/host/web'
-import type { FileRef } from './types'
+import {
+	assertSafeFileName,
+	concatBytes,
+	exactBuffer,
+	fileTooLarge,
+	throwIfAborted,
+} from './file-bytes'
 
-export const files = {
+import type {
+	FileExportOptions,
+	FileExportResult,
+	FileReadBytesOptions,
+	FileRef,
+	Files,
+} from './types'
+
+// Object URLs this leaf minted, keyed by URL, so readBytes returns exact bytes
+// without a fetch round-trip and release can drop the backing Blob.
+const objectBlobs = new Map<string, Blob>()
+
+function mintObjectUrl(blob: Blob): string {
+	const uri = URL.createObjectURL(blob)
+	objectBlobs.set(uri, blob)
+	return uri
+}
+
+function chooseFiles(accept: string, multiple: boolean): Promise<FileRef[]> {
+	return new Promise((resolve) => {
+		const input = document.createElement('input')
+		input.type = 'file'
+		input.accept = accept
+		input.multiple = multiple
+		input.onchange = () => {
+			const refs: FileRef[] = []
+			for (const file of Array.from(input.files ?? [])) {
+				refs.push({ name: file.name, uri: mintObjectUrl(file) })
+			}
+
+			resolve(refs)
+		}
+
+		input.oncancel = () => resolve([])
+		input.click()
+	})
+}
+
+// Capped stream read: stop as soon as the cap is exceeded instead of
+// materializing the whole response.
+async function fetchBytes(uri: string, opts?: FileReadBytesOptions): Promise<Uint8Array> {
+	const response = await fetch(uri, { signal: opts?.signal })
+	if (!response.ok) {
+		throw new Error(`Unable to read file: ${uri}`)
+	}
+
+	if (opts?.maxBytes == null) {
+		return new Uint8Array(await response.arrayBuffer())
+	}
+
+	const reader = response.body?.getReader()
+	if (!reader) {
+		const bytes = new Uint8Array(await response.arrayBuffer())
+		if (bytes.byteLength > opts.maxBytes) {
+			throw fileTooLarge(uri, opts.maxBytes)
+		}
+
+		return bytes
+	}
+
+	const chunks: Uint8Array[] = []
+	let total = 0
+	try {
+		while (true) {
+			const { done, value } = await reader.read()
+			if (done) {
+				break
+			}
+
+			total += value.byteLength
+			if (total > opts.maxBytes) {
+				await reader.cancel().catch(() => {})
+				throw fileTooLarge(uri, opts.maxBytes)
+			}
+
+			chunks.push(value)
+		}
+	} finally {
+		reader.releaseLock()
+	}
+
+	return concatBytes(chunks, total)
+}
+
+export const files: Files = {
+	async pickMultiple(accept = '*/*', _opts?: { startingFolder?: string }): Promise<FileRef[]> {
+		return chooseFiles(accept, true)
+	},
 	async pick(accept = '*/*', opts?: { startingFolder?: string }): Promise<FileRef | null> {
 		const host = desktopHost()
 		if (host && (await host.supports('files', 'pick'))) {
 			return host.files.pick(accept, { startingFolder: opts?.startingFolder })
 		}
 
-		return new Promise((resolve) => {
-			const input = document.createElement('input')
-			input.type = 'file'
-			input.accept = accept
-			input.onchange = () => {
-				const f = input.files?.[0]
-				resolve(f ? { name: f.name, uri: URL.createObjectURL(f) } : null)
-			}
-
-			input.oncancel = () => resolve(null)
-			input.click()
-		})
+		return (await chooseFiles(accept, false))[0] ?? null
 	},
 	async readText(ref: FileRef): Promise<string> {
 		const host = desktopHost()
@@ -36,8 +118,26 @@ export const files = {
 
 		return (await fetch(ref.uri)).text()
 	},
+	async readBytes(ref: FileRef, opts?: FileReadBytesOptions): Promise<Uint8Array> {
+		throwIfAborted(opts?.signal)
+		const blob = objectBlobs.get(ref.uri)
+		if (blob) {
+			if (opts?.maxBytes != null && blob.size > opts.maxBytes) {
+				throw fileTooLarge(ref.uri, opts.maxBytes)
+			}
+
+			const bytes = new Uint8Array(await blob.arrayBuffer())
+			throwIfAborted(opts?.signal)
+			return bytes
+		}
+
+		// Host file:// refs need a host binary read, which the desktop service
+		// contract does not provide; other URLs go through fetch.
+		return fetchBytes(ref.uri, opts)
+	},
 	/** Desktop hosts write the selected path; plain web starts a download. */
 	async writeText(name: string, text: string): Promise<FileRef> {
+		assertSafeFileName(name)
 		const host = desktopHost()
 		if (host && (await host.supports('files', 'writeText'))) {
 			const file = await host.files.writeText(name, text)
@@ -48,15 +148,56 @@ export const files = {
 			return file
 		}
 
-		const uri = URL.createObjectURL(new Blob([text], { type: 'text/plain' }))
+		const uri = mintObjectUrl(new Blob([text], { type: 'text/plain' }))
+		const a = document.createElement('a')
+		a.href = uri
+		a.download = name
+		a.click()
+		return { name, uri }
+	},
+	/** The desktop host contract is text-only, so bytes always download. */
+	async writeBytes(name: string, bytes: Uint8Array): Promise<FileRef> {
+		assertSafeFileName(name)
+		const uri = mintObjectUrl(new Blob([exactBuffer(bytes)], { type: 'application/octet-stream' }))
 		const a = document.createElement('a')
 		a.href = uri
 		a.download = name
 		a.click()
 		return { name, uri }
 	},
+	async export(
+		name: string,
+		bytes: Uint8Array,
+		opts?: FileExportOptions,
+	): Promise<FileExportResult> {
+		assertSafeFileName(name)
+		const picker = (window as any).showSaveFilePicker as ((opts: any) => Promise<any>) | undefined
+
+		if (typeof picker !== 'function') {
+			return 'unavailable'
+		}
+
+		const extension = name.includes('.') ? `.${name.split('.').pop()}` : null
+		const types =
+			opts?.mimeType && extension ? [{ accept: { [opts.mimeType]: [extension] } }] : undefined
+
+		try {
+			const handle = await picker.call(window, { suggestedName: name, types })
+			const writable = await handle.createWritable()
+			await writable.write(bytes)
+			await writable.close()
+			return 'saved'
+		} catch (error) {
+			if ((error as DOMException)?.name === 'AbortError') {
+				return 'cancelled'
+			}
+
+			throw error
+		}
+	},
 	release(ref: FileRef): void {
 		if (ref.uri.startsWith('blob:')) {
+			objectBlobs.delete(ref.uri)
 			URL.revokeObjectURL(ref.uri)
 		}
 	},

package/src/index.macos.ts

@@ -1,2 +1,11 @@
 export * from './types'
 export { files } from './files.macos'
+export { FileInput } from './FileInput.macos.tsrx'
+export type {
+	FileInputFile,
+	FileInputHandle,
+	FileInputPick,
+	FileInputProps,
+	FileInputStatus,
+	FileInputStatusType,
+} from './props'

package/src/index.ts

@@ -1,2 +1,11 @@
 export * from './types'
 export { files } from './files'
+export { FileInput } from './FileInput'
+export type {
+	FileInputFile,
+	FileInputHandle,
+	FileInputPick,
+	FileInputProps,
+	FileInputStatus,
+	FileInputStatusType,
+} from './props'

package/src/props.ts

@@ -0,0 +1,52 @@
+import type { Octane } from 'octane/jsx-runtime'
+
+import type { FieldControlProps, FieldStatus, FieldStatusType } from '@octane-xplat/ui'
+import type { FileRef } from './types'
+
+/** A portable selected file. The browser File is only present on web. */
+export interface FileInputFile extends FileRef {
+	size?: number
+	mimeType?: string
+	file?: any
+}
+
+export type FileInputStatus = FieldStatus
+export type FileInputStatusType = FieldStatusType
+
+export type FileInputPick = (options: {
+	accept?: string
+	multiple?: boolean
+}) => Promise<FileInputFile[] | FileInputFile | null>
+
+export interface FileInputHandle {
+	open(): void
+	native: any
+}
+
+export interface FileInputProps extends FieldControlProps {
+	className?: any
+	style?: any
+	id?: string
+	accessibilityLabel?: string
+	accessibilityHint?: string
+	/** `input` is a compact field row; `dropzone` a larger target that
+	 *  accepts drag/drop on pointer platforms. @default 'input' */
+	mode?: 'input' | 'dropzone'
+	value: FileInputFile | FileInputFile[] | null
+	onChange: (value: FileInputFile | FileInputFile[] | null) => void
+	changeAction?: (value: FileInputFile | FileInputFile[] | null) => void | Promise<void>
+	/** `accept`-style filter: `.ext`, `type/subtype`, wildcard subtype, any. */
+	accept?: string
+	/** When true, `value` and `onChange` use file arrays. */
+	isMultiple?: boolean
+	/** Max bytes per file; skipped for refs without a `size`. */
+	maxSize?: number
+	maxFiles?: number
+	placeholder?: string
+	/** Optional per-instance picker override for cloud or app-specific sources. */
+	pick?: FileInputPick
+	ref?: Octane.Ref<FileInputHandle>
+	ios?: any
+	android?: any
+	web?: any
+}

package/src/types.ts

@@ -2,7 +2,71 @@ export interface FileRef {
 	name: string
 	/**
 	 * Opaque reference: blob/object URL on web, filesystem path on native.
-	 * `files.writeText()` downloads on web and writes a file on native.
+	 * `files.writeText()`/`files.writeBytes()` download on web and write the
+	 * app sandbox on native. Picked Android files may use `content://` URIs.
 	 */
 	uri: string
 }
+
+export interface FilePickOptions {
+	startingFolder?: string
+}
+
+export interface FileReadBytesOptions {
+	/**
+	 * Reject with a too-large error once the file exceeds this many bytes.
+	 * Enforced while reading, so oversized sources are never fully loaded.
+	 */
+	maxBytes?: number
+	/** Abort an in-progress read. Rejects with an `AbortError`. */
+	signal?: AbortSignal
+}
+
+export interface FileExportOptions {
+	/**
+	 * MIME type hint for the destination — the Android SAF action type and the
+	 * web save picker's accept filter. Ignored on iOS.
+	 */
+	mimeType?: string
+}
+
+/**
+ * `saved`: the platform committed the bytes to the chosen destination —
+ * bytes flushed through `ContentResolver` on Android, the export-as-copy
+ * picker's destination commit on iOS, or a closed `FileSystemWritableFileStream`
+ * on web. `cancelled`: the user dismissed the destination UI. `unavailable`:
+ * the platform offers no qualified export surface (browser without the
+ * File System Access API, the AppKit leaf).
+ */
+export type FileExportResult = 'saved' | 'cancelled' | 'unavailable'
+
+/** Shared contract every platform leaf implements. */
+export interface Files {
+	/** Opens the platform document picker and returns its first opaque URI. */
+	pick(accept?: string, opts?: FilePickOptions): Promise<FileRef | null>
+	/** Opens the platform document picker and returns selected opaque URIs. */
+	pickMultiple(accept?: string, opts?: FilePickOptions): Promise<FileRef[]>
+	readText(ref: FileRef): Promise<string>
+	/**
+	 * Reads the full binary content of a picked or sandbox-written ref.
+	 * Android `content://` refs are read through `ContentResolver`; iOS picker
+	 * refs are app-owned import copies; web reads the backing `Blob` directly
+	 * or fetches foreign URLs.
+	 */
+	readBytes(ref: FileRef, opts?: FileReadBytesOptions): Promise<Uint8Array>
+	writeText(name: string, text: string): Promise<FileRef>
+	/**
+	 * Writes bytes inside the app sandbox (native) or starts a browser
+	 * download (web) and returns a ref suitable for `readBytes`/`release`.
+	 */
+	writeBytes(name: string, bytes: Uint8Array): Promise<FileRef>
+	/**
+	 * User-directed export to a destination the user picks: the Android SAF
+	 * create action, iOS export-as-copy picker, web `showSaveFilePicker`.
+	 * Only one export can be in flight — a concurrent call rejects with an
+	 * `ExportBusyError`.
+	 */
+	export(name: string, bytes: Uint8Array, opts?: FileExportOptions): Promise<FileExportResult>
+	/** Free the ref's backing resource (revoke object URLs, delete temp copies). */
+	release(ref: FileRef): void
+}

package/types/index.d.ts

@@ -0,0 +1,22 @@
+import type { UniversalComponent } from 'octane/universal'
+import type { FileInputProps } from '../src/props.js'
+
+export declare const FileInput: UniversalComponent<FileInputProps>
+export type {
+	FileInputFile,
+	FileInputHandle,
+	FileInputPick,
+	FileInputProps,
+	FileInputStatus,
+	FileInputStatusType,
+} from '../src/props.js'
+
+export { files } from '../src/files.js'
+export type {
+	FileExportOptions,
+	FileExportResult,
+	FilePickOptions,
+	FileReadBytesOptions,
+	FileRef,
+	Files,
+} from '../src/types.js'

package/types/index.macos.d.ts

@@ -0,0 +1,21 @@
+import type { FileInputProps } from '../src/props.js'
+
+export declare function FileInput(props: FileInputProps): unknown
+export type {
+	FileInputFile,
+	FileInputHandle,
+	FileInputPick,
+	FileInputProps,
+	FileInputStatus,
+	FileInputStatusType,
+} from '../src/props.js'
+
+export { files } from '../src/files.macos.js'
+export type {
+	FileExportOptions,
+	FileExportResult,
+	FilePickOptions,
+	FileReadBytesOptions,
+	FileRef,
+	Files,
+} from '../src/types.js'