@octane-xplat/files 0.0.1 → 0.10.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-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 }
+}

package/src/files.linux.ts

@@ -0,0 +1,2 @@
+// Linux's system webview uses the shared host-aware web implementation.
+export { files } from './files.web'

package/src/files.macos.ts

@@ -0,0 +1,59 @@
+// Files — AppKit host leaf.
+import type { FileRef } from './types'
+
+function openPanel(accept = '*/*', multiple = false): FileRef[] | null {
+	const appKit = globalThis as any
+	const Panel = appKit.NSOpenPanel
+	if (!Panel?.openPanel) {
+		throw new Error('AppKit NSOpenPanel is unavailable in this macOS host')
+	}
+
+	const panel = Panel.openPanel()
+	panel.canChooseFiles = true
+	panel.canChooseDirectories = false
+	panel.allowsMultipleSelection = multiple
+	const extensions = accept
+		.split(',')
+		.map((value) => value.trim())
+		.filter((value) => value.startsWith('.'))
+		.map((value) => value.slice(1))
+
+	if (extensions.length) {
+		panel.allowedFileTypes = extensions
+	}
+
+	if (panel.runModal() !== (appKit.NSModalResponseOK ?? 1)) {
+		return null
+	}
+
+	const urls: any[] = []
+	if (multiple) {
+		const selected = panel.URLs
+		for (let index = 0; index < Number(selected?.count ?? 0); index++) {
+			urls.push(selected.objectAtIndex(index))
+		}
+	} else if (panel.URL) {
+		urls.push(panel.URL)
+	}
+
+	return urls.map((url) => ({
+		name: String(url.lastPathComponent ?? ''),
+		uri: String(url.absoluteString ?? url.path ?? ''),
+	}))
+}
+
+export const files = {
+	async pick(accept = '*/*'): Promise<FileRef | null> {
+		return openPanel(accept)?.[0] ?? null
+	},
+	async pickMultiple(accept = '*/*'): Promise<FileRef[]> {
+		return openPanel(accept, true) ?? []
+	},
+	async readText(_file: FileRef): Promise<string> {
+		throw new Error('unsupported: AppKit file access is not wired')
+	},
+	async writeText(_name: string, _text: string): Promise<FileRef> {
+		throw new Error('unsupported: the AppKit host does not provide a save panel')
+	},
+	release(_file: FileRef): void {},
+}

package/src/files.ts

@@ -0,0 +1,141 @@
+// Files — native leaf. FileRef wraps an opaque native URI. App-document paths
+// are still used for writes; picked Android SAF references may be content://
+// URIs and must be read through ContentResolver.
+import { openFilePicker } from '@nativescript-community/ui-document-picker'
+import { Application, File, knownFolders, path } from '@nativescript/core'
+import type { FileRef } from './types'
+
+const docs = () => knownFolders.documents()
+
+function pickerTypes(accept: string): { extensions: string[]; mimeTypes: string[] } {
+	const values = accept
+		.split(',')
+		.map((value) => value.trim())
+		.filter(Boolean)
+
+	return {
+		extensions: values.filter((value) => value.startsWith('.')).map((value) => value.slice(1)),
+		// `*/*` is the default, not a useful iOS UTType MIME value. Leaving it
+		// out lets the upstream picker use its public.data fallback.
+		mimeTypes: values.filter((value) => value.includes('/') && value !== '*/*'),
+	}
+}
+
+function androidDisplayName(uri: string, nativeUri: any): string | undefined {
+	if (!Application.android || !uri.startsWith('content://')) {
+		return undefined
+	}
+
+	try {
+		const activity = Application.android.foregroundActivity ?? Application.android.startActivity
+		// Android accepts null for projection/filter args; its generated
+		// declarations omit that nullable bridge contract.
+		const noColumns = null as unknown as string[]
+		const noFilter = null as unknown as string
+		const cursor = activity
+			?.getContentResolver()
+			?.query(nativeUri ?? android.net.Uri.parse(uri), noColumns, noFilter, noColumns, noFilter)
+
+		if (!cursor) {
+			return undefined
+		}
+
+		try {
+			if (!cursor.moveToFirst()) {
+				return undefined
+			}
+
+			const index = cursor.getColumnIndex('display_name')
+			return index >= 0 ? cursor.getString(index) : undefined
+		} finally {
+			cursor.close()
+		}
+	} catch {
+		return undefined
+	}
+}
+
+function fallbackName(uri: string): string {
+	const segment = uri.split('/').pop() ?? ''
+	try {
+		return decodeURIComponent(segment) || 'document'
+	} catch {
+		return segment || 'document'
+	}
+}
+
+async function readContentUri(uri: string): Promise<string> {
+	const activity = Application.android?.foregroundActivity ?? Application.android?.startActivity
+	const input = activity?.getContentResolver()?.openInputStream(android.net.Uri.parse(uri))
+
+	if (!input) {
+		throw new Error(`Unable to open picked file: ${uri}`)
+	}
+
+	const reader = new java.io.BufferedReader(new java.io.InputStreamReader(input))
+	const lines: string[] = []
+	try {
+		let line: string | null
+		while ((line = reader.readLine()) !== null) {
+			lines.push(line)
+		}
+
+		return lines.join('\n')
+	} finally {
+		reader.close()
+	}
+}
+
+async function pickFiles(
+	accept: string,
+	multiple: boolean,
+	opts?: { startingFolder?: string },
+): Promise<FileRef[]> {
+	const { extensions, mimeTypes } = pickerTypes(accept)
+	const result = await openFilePicker({
+		extensions,
+		mimeTypes,
+		multipleSelection: multiple,
+		permissions: { read: true, persistable: true },
+		startingFolder: opts?.startingFolder,
+	})
+
+	return (result.files ?? []).map((uri, index) => ({
+		name: androidDisplayName(uri, index === 0 ? result.android : undefined) ?? fallbackName(uri),
+		uri,
+	}))
+}
+
+export const files = {
+	/** Opens the platform document picker and returns selected opaque URIs. */
+	async pickMultiple(accept = '*/*', opts?: { startingFolder?: string }): Promise<FileRef[]> {
+		return pickFiles(accept, true, opts)
+	},
+	/** Opens the platform document picker and returns its first opaque URI. */
+	async pick(accept = '*/*', opts?: { startingFolder?: string }): Promise<FileRef | null> {
+		return (await pickFiles(accept, false, opts))[0] ?? null
+	},
+	async readText(ref: FileRef): Promise<string> {
+		if (ref.uri.startsWith('content://')) {
+			return readContentUri(ref.uri)
+		}
+
+		return File.fromPath(ref.uri).readText()
+	},
+	async writeText(name: string, text: string): Promise<FileRef> {
+		const p = path.join(docs().path, name)
+		const f = File.fromPath(p)
+		f.writeTextSync(text)
+		return { name, uri: p }
+	},
+	release(ref: FileRef): void {
+		const cachePrefix = knownFolders.temp().path + '/'
+		if (!ref.uri.startsWith(cachePrefix)) {
+			return
+		}
+
+		try {
+			File.fromPath(ref.uri).removeSync()
+		} catch {}
+	},
+}

package/src/files.web.ts

@@ -0,0 +1,75 @@
+// 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'
+
+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: URL.createObjectURL(file) })
+			}
+
+			resolve(refs)
+		}
+
+		input.oncancel = () => resolve([])
+		input.click()
+	})
+}
+
+export const 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 (await chooseFiles(accept, false))[0] ?? null
+	},
+	async readText(ref: FileRef): Promise<string> {
+		const host = desktopHost()
+		if (host && (await host.supports('files', 'readText'))) {
+			const text = await host.files.readText(ref.uri)
+			if (text === null) {
+				throw new Error(`Unable to read host file: ${ref.uri}`)
+			}
+
+			return text
+		}
+
+		return (await fetch(ref.uri)).text()
+	},
+	/** Desktop hosts write the selected path; plain web starts a download. */
+	async writeText(name: string, text: string): Promise<FileRef> {
+		const host = desktopHost()
+		if (host && (await host.supports('files', 'writeText'))) {
+			const file = await host.files.writeText(name, text)
+			if (!file) {
+				throw new Error('Host file save was cancelled')
+			}
+
+			return file
+		}
+
+		const uri = URL.createObjectURL(new Blob([text], { type: 'text/plain' }))
+		const a = document.createElement('a')
+		a.href = uri
+		a.download = name
+		a.click()
+		return { name, uri }
+	},
+	release(ref: FileRef): void {
+		if (ref.uri.startsWith('blob:')) {
+			URL.revokeObjectURL(ref.uri)
+		}
+	},
+}

package/src/index.macos.ts

@@ -0,0 +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

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