@octane-xplat/files 0.9.0 → 0.11.0

package/src/FileInput.web.tsrx

@@ -0,0 +1,240 @@
+import { useImperativeHandle, useId, useRef, useState } from 'octane'
+import { Field as FormField, Icon, Spinner as ActivityIndicator, Tooltip, useFieldControl } from '@octane-xplat/ui'
+import type { FileInputFile, FileInputProps } from './props'
+import { cx, formatFileSize, normalizePicked, validateFiles } from './file-input-utils'
+
+const STATUS_GLYPHS = { error: '⚠', warning: '⚠', success: '✓' } as const
+
+function FileInputControl(inputProps: FileInputProps) @{
+	const { props } = useFieldControl(inputProps)
+	const generatedId = useId()
+	const inputId = props.id ?? generatedId
+	const fileInput = useRef<HTMLInputElement | null>(null)
+
+	const [dragging, setDragging] = useState(false)
+	const [busy, setBusy] = useState(false)
+	const [validationErrors, setValidationErrors] = useState<string[]>([])
+
+	const files: FileInputFile[] = props.value == null ? [] : Array.isArray(props.value) ? props.value : [props.value]
+	const isDisabled = !!props.isDisabled || !!props.isReadOnly
+	const isBusy = !!props.isLoading || busy
+	const canClear = files.length > 0 && !isDisabled && !isBusy
+	const showsDisabledReason = isDisabled && !!props.disabledMessage
+	const statusType = validationErrors.length ? 'error' : props.status?.type
+	const statusMessage = validationErrors.length ? validationErrors.join(' ') : props.status?.message
+
+	// `onChange` mirrors `value`'s shape: array when `isMultiple`, single ref
+	// or null otherwise.
+	const emitValue = (next: FileInputFile[]): FileInputFile | FileInputFile[] | null =>
+		props.isMultiple ? next : (next[0] ?? null)
+
+	const fireChange = (next: FileInputFile[]) => {
+		const emitted = emitValue(next)
+		props.onChange?.(emitted)
+		if (props.changeAction) {
+			setBusy(true)
+			Promise.resolve(props.changeAction(emitted)).finally(() => setBusy(false))
+		}
+	}
+
+	const acceptRefs = (picked: FileInputFile[]) => {
+		if (isDisabled || isBusy || !picked.length) return
+		const merged = props.isMultiple ? [...files, ...picked] : picked
+		const { valid, errors } = validateFiles(merged, {
+			accept: props.accept,
+			maxSize: props.maxSize,
+			maxFiles: props.maxFiles,
+		})
+
+		setValidationErrors(errors)
+		const next = !props.isMultiple && errors.length ? files : valid
+		if (next.length !== files.length || next.some((file, index) => file.uri !== files[index]?.uri)) {
+			fireChange(next)
+		}
+	}
+
+	const removeAt = (index: number) => {
+		if (isDisabled || isBusy) return
+		setValidationErrors([])
+		fireChange(files.filter((_, i) => i !== index))
+	}
+
+	const pick = () => {
+		if (isDisabled || isBusy) return
+		// An optional custom picker can provide cloud or app-specific sources.
+		if (props.pick) {
+			Promise.resolve(props.pick({ accept: props.accept, multiple: props.isMultiple }))
+				.then((r) => acceptRefs(normalizePicked(r)))
+				.catch((error) => setValidationErrors([String(error?.message ?? error)]))
+
+			return
+		}
+
+		fileInput.current?.click()
+	}
+
+	const handleFileSelect = (e: any) => {
+		const list = e.target.files as any
+		const picked: FileInputFile[] = []
+		if (list) {
+			for (let i = 0; i < list.length; i++) {
+				const f = list[i]
+				picked.push({ name: f.name, uri: URL.createObjectURL(f), size: f.size, mimeType: f.type, file: f })
+			}
+		}
+
+		e.target.value = ''
+		acceptRefs(picked)
+	}
+
+	const handleDrop = (e: any) => {
+		e.preventDefault()
+		e.stopPropagation()
+		setDragging(false)
+		if (isDisabled || isBusy) return
+		const list = e.dataTransfer?.files
+		if (!list?.length) return
+		const picked: FileInputFile[] = []
+		for (let i = 0; i < list.length; i++) {
+			const f = list[i]
+			picked.push({ name: f.name, uri: URL.createObjectURL(f), size: f.size, mimeType: f.type, file: f })
+		}
+
+		acceptRefs(picked)
+	}
+
+	const dropzone = props.mode === 'dropzone'
+	const itemContent = (
+		<>
+			{files.length ? (
+				<ul className="vx-fileinput-list">
+					{files.map((f: FileInputFile, i: number) => (
+						<li key={`${f.uri}-${i}`} className="vx-fileinput-item">
+							<Icon name="xplat-upload" size={14} />
+							<span className="vx-fileinput-itemname">{f.name}</span>
+							{f.size != null ? <span className="vx-fileinput-itemsize">{formatFileSize(f.size)}</span> : null}
+							{!isDisabled && !isBusy
+								? <button type="button" className="vx-fileinput-itemremove" aria-label={`Remove ${f.name}`} onClick={() => removeAt(i)}>{'×'}</button>
+								: null}
+						</li>
+					))}
+				</ul>
+			) : null}
+			{dropzone ? (
+				<div className="vx-fileinput-dropzone-hint">
+					<Icon name="xplat-upload" size={24} />
+					<span>{isDisabled ? 'Upload disabled' : 'Drag & drop files here or click to browse'}</span>
+					{props.accept ? <span className="vx-fileinput-accept">{props.accept}</span> : null}
+				</div>
+			) : (
+				<button
+					type="button"
+					id={inputId}
+					className="vx-fileinput-trigger"
+					disabled={isDisabled && !showsDisabledReason || undefined}
+					aria-disabled={showsDisabledReason || undefined}
+					aria-describedby={props.ariaDescribedBy}
+					aria-required={props.isRequired && !props.isOptional || undefined}
+					aria-invalid={statusType === 'error' || undefined}
+					aria-busy={isBusy || undefined}
+					onClick={pick}
+				>
+					<Icon name="xplat-upload" size={14} /> {files.length ? 'Choose more files' : 'Choose files'}
+				</button>
+			)}
+			{dropzone ? (
+				<button
+					type="button"
+					id={inputId}
+					className="vx-fileinput-trigger vx-fileinput-trigger--hidden"
+					disabled={isDisabled && !showsDisabledReason || undefined}
+					aria-disabled={showsDisabledReason || undefined}
+					aria-describedby={props.ariaDescribedBy}
+					aria-required={props.isRequired && !props.isOptional || undefined}
+					aria-invalid={statusType === 'error' || undefined}
+					aria-busy={isBusy || undefined}
+					onClick={pick}
+				>
+					Browse files
+				</button>
+			) : null}
+			{canClear ? <button type="button" className="vx-fileinput-clear" aria-label={`Clear ${props.fieldLabel ?? props.label ?? 'files'}`} onClick={() => { setValidationErrors([]); fireChange([]) }}>{'×'}</button> : null}
+			{isBusy ? <ActivityIndicator busy className="vx-fileinput-spinner" /> : null}
+			{statusType ? (
+				props.statusVariant === 'tooltip' && statusMessage
+					? <Tooltip trigger={<span className={cx('vx-field-icon', `vx-field-icon--${statusType}`)}>{STATUS_GLYPHS[statusType]}</span>} content={statusMessage} />
+					: <span className={cx('vx-field-icon', `vx-field-icon--${statusType}`)}>{STATUS_GLYPHS[statusType]}</span>
+			) : null}
+			{statusMessage && props.statusVariant !== 'tooltip'
+				? <span className={cx('vx-field-status', `vx-field-status--${statusType}`)} role={statusType === 'error' ? 'alert' : 'status'}>{statusMessage}</span>
+				: null}
+			<input
+				ref={(el: any) => { fileInput.current = el; }}
+				type="file"
+				className="vx-fileinput-nativeinput"
+				accept={props.accept}
+				multiple={props.isMultiple || undefined}
+				disabled={isDisabled || undefined}
+				aria-hidden="true"
+				tabIndex={-1}
+				onChange={handleFileSelect}
+			/>
+		</>
+	)
+
+	useImperativeHandle(props.ref, () => ({ open: pick, native: fileInput.current }), undefined);
+
+	<div
+		className={cx(
+			'vx-fileinput',
+			dropzone && 'vx-fileinput--dropzone',
+			isDisabled && 'vx-fileinput--disabled',
+			isBusy && 'vx-fileinput--loading',
+			dragging && 'vx-fileinput--dragging',
+			statusType && `vx-fileinput--status-${statusType}`,
+			props.size && `vx-fileinput--size-${props.size}`,
+			props.className,
+		)}
+		style={props.style}
+		onDragOver={(e: any) => { e.preventDefault(); if (!isDisabled && !isBusy) setDragging(true) }}
+		onDragEnter={(e: any) => { e.preventDefault() }}
+		onDragLeave={() => setDragging(false)}
+		onDrop={handleDrop}
+	>
+		{itemContent}
+	</div>
+}
+
+/**
+ * File entry — `compact` (button + list) or `dropzone` mode. Values are
+ * `{name, uri, size?, mimeType?}` portable refs. On web the hidden browser
+ * input returns the `File` alongside its object URL. Drag/drop targets the
+ * control wrapper in both modes.
+ */
+export function FileInput(props: FileInputProps) @{
+	const { inField } = useFieldControl(props)
+	const cid = useId()
+	const control = <FileInputControl {...props} />
+	if (inField) return control
+	return (
+		<FormField
+			inputID={props.id ?? cid}
+			label={props.label}
+			isLabelHidden={props.isLabelHidden}
+			description={props.description}
+			isDisabled={props.isDisabled}
+			disabledMessage={props.disabledMessage}
+			isReadOnly={props.isReadOnly}
+			isLoading={props.isLoading}
+			isRequired={props.isRequired}
+			isOptional={props.isOptional}
+			size={props.size}
+			status={props.status}
+			statusVariant={props.statusVariant}
+			labelTooltip={props.labelTooltip}
+			width={props.width}
+		>
+			{control}
+		</FormField>
+	)
+}

package/src/file-bytes.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import { assertSafeFileName, concatBytes, exactBuffer, throwIfAborted } from './file-bytes'
+
+describe('assertSafeFileName', () => {
+	it('accepts plain file names', () => {
+		for (const name of ['a.txt', 'report 1.pdf', 'x.y.z.bin', 'résumé.md']) {
+			expect(() => assertSafeFileName(name)).not.toThrow()
+		}
+	})
+
+	it('rejects empty, dot, and traversal names', () => {
+		for (const name of ['', '.', '..', '../x', 'a/b', 'a\\b', '..\\x', 'a\0b']) {
+			expect(() => assertSafeFileName(name)).toThrow(/Unsafe file name/)
+		}
+	})
+})
+
+describe('throwIfAborted', () => {
+	it('passes for live or absent signals', () => {
+		expect(() => throwIfAborted(undefined)).not.toThrow()
+		const controller = new AbortController()
+		expect(() => throwIfAborted(controller.signal)).not.toThrow()
+	})
+
+	it('throws AbortError for aborted signals', () => {
+		const controller = new AbortController()
+		controller.abort()
+		expect(() => throwIfAborted(controller.signal)).toThrowError(
+			expect.objectContaining({ name: 'AbortError' }),
+		)
+	})
+})
+
+describe('concatBytes / exactBuffer', () => {
+	it('concatenates chunks in order', () => {
+		const joined = concatBytes(
+			[new Uint8Array([1, 2]), new Uint8Array([3]), new Uint8Array([4, 5])],
+			5,
+		)
+
+		expect([...joined]).toEqual([1, 2, 3, 4, 5])
+	})
+
+	it('returns the buffer only when the view covers it', () => {
+		const buffer = new Uint8Array([9, 8, 7, 6]).buffer
+		expect(exactBuffer(new Uint8Array(buffer))).toBe(buffer)
+
+		const windowed = new Uint8Array(buffer, 1, 2)
+		const exact = exactBuffer(windowed)
+		expect(exact.byteLength).toBe(2)
+		expect([...new Uint8Array(exact)]).toEqual([8, 7])
+	})
+})

package/src/file-bytes.ts

@@ -0,0 +1,68 @@
+/**
+ * Shared helpers for the binary file primitives (readBytes/writeBytes/export).
+ * DOM-free so the native leaf can use it too.
+ */
+
+/** File names used for sandbox writes and export temp files must be bare
+ *  names, not paths — a `/`, `\`, or `..` segment escapes the sandbox. */
+export function assertSafeFileName(name: string): void {
+	if (
+		typeof name !== 'string' ||
+		name.length === 0 ||
+		name === '.' ||
+		name === '..' ||
+		name.includes('/') ||
+		name.includes('\\') ||
+		name.includes('\0')
+	) {
+		throw new Error(`Unsafe file name: ${JSON.stringify(name)}`)
+	}
+}
+
+export function fileTooLarge(name: string, maxBytes: number): Error {
+	return new Error(`${name}: file exceeds the ${maxBytes}-byte limit`)
+}
+
+/** Named rejection for a second `files.export` while one is in flight. */
+export function exportBusy(): Error {
+	const error = new Error('files.export: an export is already in progress')
+	error.name = 'ExportBusyError'
+	return error
+}
+
+export function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (!signal?.aborted) {
+		return
+	}
+
+	const thrower = (signal as { throwIfAborted?: () => void }).throwIfAborted
+	if (typeof thrower === 'function') {
+		thrower.call(signal)
+	}
+
+	const error = new Error('The operation was aborted')
+	error.name = 'AbortError'
+	throw error
+}
+
+/** Concatenate Uint8Array chunks into one exact-length array. */
+export function concatBytes(chunks: Uint8Array[], total: number): Uint8Array {
+	const out = new Uint8Array(total)
+	let offset = 0
+	for (const chunk of chunks) {
+		out.set(chunk, offset)
+		offset += chunk.byteLength
+	}
+
+	return out
+}
+
+/** Return an ArrayBuffer covering exactly this view's byte range — native
+ *  marshallers treat the argument as the whole buffer. */
+export function exactBuffer(bytes: Uint8Array): ArrayBuffer {
+	if (bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) {
+		return bytes.buffer as ArrayBuffer
+	}
+
+	return bytes.slice().buffer as ArrayBuffer
+}

package/src/file-input-utils.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { fileAccepts, validateFiles } from './file-input-utils'
+
+describe('file validation', () => {
+	it('matches accept tokens', () => {
+		expect(fileAccepts({ name: 'a.png', uri: 'x' }, '.png')).toBe(true)
+		expect(fileAccepts({ name: 'a.jpg', uri: 'x' }, '.png')).toBe(false)
+		expect(fileAccepts({ name: 'a.png', uri: 'x', mimeType: 'image/png' }, 'image/*')).toBe(true)
+	})
+
+	it('enforces maxSize and maxFiles', () => {
+		const files = [
+			{ name: 'a', uri: 'a', size: 10 },
+			{ name: 'b', uri: 'b', size: 99999 },
+			{ name: 'c', uri: 'c' },
+		]
+
+		const result = validateFiles(files, { maxSize: 100, maxFiles: 1 })
+		expect(result.valid.map((file) => file.name)).toEqual(['a'])
+		expect(result.errors).toHaveLength(2)
+	})
+})

package/src/file-input-utils.ts

@@ -0,0 +1,113 @@
+/**
+ * Shared formatting and validation helpers for this package's FileInput.
+ */
+
+import type { FileInputFile } from './props'
+
+export function cx(...values: Array<string | false | null | undefined>): string {
+	return values.filter(Boolean).join(' ')
+}
+
+export function normalizePicked(result: FileInputFile[] | FileInputFile | null): FileInputFile[] {
+	if (result == null) {
+		return []
+	}
+
+	return Array.isArray(result) ? result : [result]
+}
+
+// ---------------------------------------------------------------------------
+// Validation — `accept` tokens (`.ext`, `type/subtype`, `type/*`, `*/*`),
+// `maxSize` bytes, `maxFiles` count. Refs without `size`/`mimeType` skip the
+// checks that need them.
+// ---------------------------------------------------------------------------
+
+export interface FileValidationOptions {
+	accept?: string
+	maxSize?: number
+	maxFiles?: number
+}
+
+export interface FileValidationResult {
+	valid: FileInputFile[]
+	errors: string[]
+}
+
+export function fileAccepts(file: FileInputFile, accept: string | undefined): boolean {
+	if (!accept) {
+		return true
+	}
+
+	const tokens = accept
+		.split(',')
+		.map((t) => t.trim().toLowerCase())
+		.filter(Boolean)
+
+	if (!tokens.length) {
+		return true
+	}
+
+	const name = file.name.toLowerCase()
+	const mime = (file.mimeType ?? '').toLowerCase()
+	return tokens.some((token) => {
+		if (token === '*/*') {
+			return true
+		}
+
+		if (token.startsWith('.')) {
+			return name.endsWith(token)
+		}
+
+		if (token.endsWith('/*')) {
+			return mime.startsWith(token.slice(0, -1))
+		}
+
+		return mime === token
+	})
+}
+
+export function formatFileSize(bytes: number): string {
+	if (bytes < 1024) {
+		return `${bytes} B`
+	}
+
+	if (bytes < 1024 * 1024) {
+		return `${(bytes / 1024).toFixed(1)} KB`
+	}
+
+	if (bytes < 1024 * 1024 * 1024) {
+		return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+	}
+
+	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`
+}
+
+export function validateFiles(
+	files: FileInputFile[],
+	opts: FileValidationOptions,
+): FileValidationResult {
+	const errors: string[] = []
+	const valid: FileInputFile[] = []
+	for (const file of files) {
+		if (!fileAccepts(file, opts.accept)) {
+			errors.push(`${file.name}: file type not accepted`)
+			continue
+		}
+
+		if (opts.maxSize != null && file.size != null && file.size > opts.maxSize) {
+			errors.push(`${file.name}: file exceeds ${formatFileSize(opts.maxSize)}`)
+			continue
+		}
+
+		valid.push(file)
+	}
+
+	if (opts.maxFiles != null && valid.length > opts.maxFiles) {
+		const extra = valid.splice(opts.maxFiles)
+		for (const file of extra) {
+			errors.push(`${file.name}: exceeds the ${opts.maxFiles}-file limit`)
+		}
+	}
+
+	return { valid, errors }
+}