@octane-xplat/files 0.9.0 → 0.10.0

package/README.md

@@ -1,32 +1,48 @@
 # `@octane-xplat/files`
 
-File pick, read, and write for Octane xplat apps. iOS/Android run
-`@nativescript-community/ui-document-picker` plus `@nativescript/core`
-filesystem APIs (including `content://` URIs); web uses an `<input
-type="file">` pick and downloads for writes; Linux goes through the desktop
-host bridge (`Gtk.FileDialog`) and falls back to the web flow in a plain
-browser; the macOS AppKit dev host is not wired and throws `unsupported`.
-
-```sh
-pnpm add @octane-xplat/files
+Cross-platform file selection and file entry for Octane apps.
+
+Install `@octane-xplat/files` and `@octane-xplat/ui`. `FileInput` uses the
+platform picker by default: the browser file input on web, the NativeScript
+document picker on iOS/Android, and AppKit `NSOpenPanel` on macOS. No
+app-registered picker is needed. The optional `pick` prop can replace the
+default for a custom source such as cloud storage.
+
+```tsrx
+import { useState } from 'octane'
+import { FileInput } from '@octane-xplat/files'
+import type { FileInputFile } from '@octane-xplat/files'
+
+export function Attachments() @{
+	const [files, setFiles] = useState<FileInputFile[] | null>([])
+
+	<FileInput
+		label="Attachments"
+		isMultiple
+		value={files}
+		onChange={(next) => setFiles(Array.isArray(next) ? next : next ? [next] : [])}
+	/>
+}
 ```
 
+The portable value is `{ name, uri, size?, mimeType? }`. On web, the selected
+browser `File` is also available as `file`; its `uri` is a temporary object
+URL. Native platforms return a local path or content URI, which apps should
+retain as an opaque reference and pass to `files.readText` where supported.
+AppKit provides native picking, but its current `readText` and `writeText`
+methods are unsupported. Web file references should be released with
+`files.release` when no longer needed.
+
 ```ts
 import { files } from '@octane-xplat/files'
 
-const ref = await files.pick('image/*')
-if (ref) {
-	const text = await files.readText(ref)
-	files.release(ref)
+// Run in a .web.ts file: AppKit currently does not support readText.
+const file = await files.pick('text/plain')
+if (file) {
+	try {
+		console.log(await files.readText(file))
+	} finally {
+		files.release(file)
+	}
 }
-
-// web: triggers a download; native: writes into the app documents folder
-const out = await files.writeText('packing-list.txt', text)
 ```
-
-`FileRef.uri` is opaque — a blob/object URL on web, a filesystem path or
-`content://` URI on native. Pass it back to `files.readText`; do not parse
-it. `release(ref)` cleans up native temp picks and is a no-op elsewhere.
-
-Guide: [Using device features](../../docs/platform-services.md);
-per-target availability: [platform notes](../../docs/platform-notes.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/files",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Native + web file pick and read/write for Octane xplat — matching web + NativeScript implementations",
   "keywords": [
     "android",
@@ -22,12 +22,17 @@
     "directory": "packages/files"
   },
   "files": [
-    "src"
+    "src",
+    "types"
   ],
   "type": "module",
   "exports": {
     ".": {
-      "macos": "./src/index.macos.ts",
+      "macos": {
+        "types": "./types/index.macos.d.ts",
+        "default": "./src/index.macos.ts"
+      },
+      "types": "./types/index.d.ts",
       "default": "./src/index.ts"
     },
     "./*": "./src/*"
@@ -37,17 +42,19 @@
   },
   "dependencies": {
     "@nativescript-community/ui-document-picker": "1.1.29",
-    "@octane-xplat/platform": "0.9.0"
+    "@octane-xplat/platform": "0.10.0"
   },
   "devDependencies": {
     "@nativescript-community/octane": "0.2.4",
     "@nativescript/core": "9.1.2",
     "@nativescript/types": "9.0.0",
+    "@octane-xplat/ui": "0.10.0",
     "octane": "0.6.3"
   },
   "peerDependencies": {
     "@nativescript-community/octane": ">=0.2.1 <1",
     "@nativescript/core": ">=9.1.0 <10",
+    "@octane-xplat/ui": ">=0.6.0 <1",
     "octane": ">=0.6.3 <1"
   },
   "peerDependenciesMeta": {

package/src/FileInput.linux.tsrx

@@ -0,0 +1 @@
+export { FileInput } from './FileInput.web.tsrx'

package/src/FileInput.macos.tsrx

@@ -0,0 +1,167 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+import { useRef, useImperativeHandle, useId, useState } from 'octane'
+import { Field as FormField, Icon, Pressable, useFieldControl } from '@octane-xplat/ui'
+import type { FileInputFile, FileInputProps } from './props'
+import { files as fileService } from './files'
+import { cx, formatFileSize, normalizePicked, validateFiles } from './file-input-utils'
+
+const STATUS_TEXT = { error: '⚠', warning: '⚠', success: '✓' } as const
+
+function FileInputControl(inputProps: FileInputProps) @{
+	const hostRef = useRef<any>(null);
+	const { props } = useFieldControl(inputProps)
+	const generatedId = useId()
+	const inputId = props.id ?? generatedId
+
+	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 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
+		const options = { accept: props.accept, multiple: props.isMultiple }
+		const picked = props.pick
+			? props.pick(options)
+			: props.isMultiple
+				? fileService.pickMultiple(props.accept)
+				: fileService.pick(props.accept)
+
+		Promise.resolve(picked)
+			.then((result) => acceptRefs(normalizePicked(result)))
+			.catch((error) => setValidationErrors([String(error?.message ?? error)]))
+	}
+
+	const dropzone = props.mode === 'dropzone'
+	const statusText = statusType ? STATUS_TEXT[statusType] : null
+
+	useImperativeHandle(props.ref, () => ({ open: pick, native: hostRef.current }), undefined);
+
+	<flexboxlayout
+		flexDirection="column"
+		className={cx(
+			'vx-fileinput',
+			dropzone && 'vx-fileinput--dropzone',
+			isDisabled && 'vx-fileinput--disabled',
+			isBusy && 'vx-fileinput--loading',
+			statusType && `vx-fileinput--status-${statusType}`,
+			props.size && `vx-fileinput--size-${props.size}`,
+			props.className,
+		)}
+		style={props.style}
+	>
+		{files.length ? (
+			<flexboxlayout flexDirection="column" className="vx-fileinput-list">
+				{files.map((f, i) => (
+					<flexboxlayout key={`${f.uri}-${i}`} flexDirection="row" alignItems="center" className="vx-fileinput-item">
+						<Icon name="xplat-upload" size={14} />
+						<label className="vx-fileinput-itemname" text={f.name} />
+						{f.size != null ? <label className="vx-fileinput-itemsize" text={formatFileSize(f.size)} /> : null}
+						{!isDisabled && !isBusy
+							? <Pressable className="vx-fileinput-itemremove" accessibilityLabel={`Remove ${f.name}`} onPress={() => removeAt(i)}><label text="×" /></Pressable>
+							: null}
+					</flexboxlayout>
+				))}
+			</flexboxlayout>
+		) : null}
+		<Pressable
+			ref={(v: any) => { hostRef.current = v; }}
+			id={inputId}
+			className="vx-fileinput-trigger"
+			disabled={isDisabled || isBusy}
+			accessibilityLabel={props.accessibilityLabel ?? props.ariaLabel ?? props.fieldLabel ?? props.label}
+			accessibilityHint={props.accessibilityHint}
+			accessibilityState={{ disabled: isDisabled, busy: isBusy } as any}
+			onPress={pick}
+		>
+			<flexboxlayout flexDirection="row" alignItems="center">
+				<Icon name="xplat-upload" size={14} />
+				<label text={files.length ? 'Choose more files' : 'Choose files'} />
+			</flexboxlayout>
+		</Pressable>
+		{files.length > 0 && !isDisabled && !isBusy
+			? <Pressable className="vx-fileinput-clear" accessibilityLabel={`Clear ${props.fieldLabel ?? props.label ?? 'files'}`} onPress={() => { setValidationErrors([]); fireChange([]) }}><label text="×" /></Pressable>
+			: null}
+		{statusText != null
+			? <label className={cx('vx-field-icon', `vx-field-icon--${statusType}`)} text={statusText} accessibilityLabel={props.statusVariant === 'tooltip' ? statusMessage : undefined} />
+			: null}
+		{statusMessage && props.statusVariant !== 'tooltip'
+			? <label className={cx('vx-field-status', `vx-field-status--${statusType}`)} text={statusMessage} />
+			: null}
+	</flexboxlayout>
+}
+
+/**
+ * File entry — delegates selection to this package's AppKit files service.
+ * Values are portable `{name, uri, size?, mimeType?}` refs. Drag/drop is not
+ * implemented on this leaf.
+ */
+export function FileInput(props: FileInputProps) @{
+	const { inField } = useFieldControl(props)
+	const cid = useId()
+	const control = <FileInputControl {...props} />
+
+	<>
+		{inField ? control : (
+			<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/FileInput.tsrx

@@ -0,0 +1,168 @@
+/** @jsxImportSource @nativescript-community/octane */
+import { useRef, useImperativeHandle, useId, useState } from 'octane'
+import { Field as FormField, Icon, Pressable, useFieldControl } from '@octane-xplat/ui'
+import type { FileInputFile, FileInputProps } from './props'
+import { files as fileService } from './files'
+import { cx, formatFileSize, normalizePicked, validateFiles } from './file-input-utils'
+
+const STATUS_TEXT = { error: '⚠', warning: '⚠', success: '✓' } as const
+
+function FileInputControl(inputProps: FileInputProps) @{
+	const hostRef = useRef<any>(null);
+	const { props } = useFieldControl(inputProps)
+	const generatedId = useId()
+	const inputId = props.id ?? generatedId
+
+	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 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
+		const options = { accept: props.accept, multiple: props.isMultiple }
+		const picked = props.pick
+			? props.pick(options)
+			: props.isMultiple
+				? fileService.pickMultiple(props.accept)
+				: fileService.pick(props.accept)
+
+		Promise.resolve(picked)
+			.then((result) => acceptRefs(normalizePicked(result)))
+			.catch((error) => setValidationErrors([String(error?.message ?? error)]))
+	}
+
+	const dropzone = props.mode === 'dropzone'
+	const statusText = statusType ? STATUS_TEXT[statusType] : null
+
+	useImperativeHandle(props.ref, () => ({ open: pick, native: hostRef.current }), undefined);
+
+	<flexboxlayout
+		flexDirection="column"
+		className={cx(
+			'vx-fileinput',
+			dropzone && 'vx-fileinput--dropzone',
+			isDisabled && 'vx-fileinput--disabled',
+			isBusy && 'vx-fileinput--loading',
+			statusType && `vx-fileinput--status-${statusType}`,
+			props.size && `vx-fileinput--size-${props.size}`,
+			props.className,
+		)}
+		style={props.style}
+	>
+		{files.length ? (
+			<flexboxlayout flexDirection="column" className="vx-fileinput-list">
+				{files.map((f, i) => (
+					<flexboxlayout key={`${f.uri}-${i}`} flexDirection="row" alignItems="center" className="vx-fileinput-item">
+						<Icon name="xplat-upload" size={14} />
+						<label className="vx-fileinput-itemname" text={f.name} />
+						{f.size != null ? <label className="vx-fileinput-itemsize" text={formatFileSize(f.size)} /> : null}
+						{!isDisabled && !isBusy
+							? <Pressable className="vx-fileinput-itemremove" accessibilityLabel={`Remove ${f.name}`} onPress={() => removeAt(i)}><label text="×" /></Pressable>
+							: null}
+					</flexboxlayout>
+				))}
+			</flexboxlayout>
+		) : null}
+		<Pressable
+			ref={(v: any) => { hostRef.current = v; }}
+			id={inputId}
+			className="vx-fileinput-trigger"
+			disabled={isDisabled || isBusy}
+			accessibilityLabel={props.accessibilityLabel ?? props.ariaLabel ?? props.fieldLabel ?? props.label}
+			accessibilityHint={props.accessibilityHint}
+			accessibilityState={{ disabled: isDisabled, busy: isBusy } as any}
+			onPress={pick}
+		>
+			<flexboxlayout flexDirection="row" alignItems="center">
+				<Icon name="xplat-upload" size={14} />
+				<label text={files.length ? 'Choose more files' : 'Choose files'} />
+			</flexboxlayout>
+		</Pressable>
+		{files.length > 0 && !isDisabled && !isBusy
+			? <Pressable className="vx-fileinput-clear" accessibilityLabel={`Clear ${props.fieldLabel ?? props.label ?? 'files'}`} onPress={() => { setValidationErrors([]); fireChange([]) }}><label text="×" /></Pressable>
+			: null}
+		{statusText != null
+			? <label className={cx('vx-field-icon', `vx-field-icon--${statusType}`)} text={statusText} accessibilityLabel={props.statusVariant === 'tooltip' ? statusMessage : undefined} />
+			: null}
+		{statusMessage && props.statusVariant !== 'tooltip'
+			? <label className={cx('vx-field-status', `vx-field-status--${statusType}`)} text={statusMessage} />
+			: null}
+	</flexboxlayout>
+}
+
+/**
+ * File entry — `compact`/`dropzone` modes render the same tappable surface
+ * on iOS/Android (drag/drop has no touch equivalent). Values are
+ * `FileInputFile` `{name, uri, size?, mimeType?}`; native picking uses the
+ * platform file service exported by this package.
+ */
+export function FileInput(props: FileInputProps) @{
+	const { inField } = useFieldControl(props)
+	const cid = useId()
+	const control = <FileInputControl {...props} />
+
+	<>
+		{inField ? control : (
+			<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/FileInput.web.test.tsx

@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, createRoot } from 'octane'
+import { FileInput } from './FileInput.web.tsrx'
+
+vi.mock('@octane-xplat/ui', () => ({
+	Field: ({ children }: any) => children,
+	Icon: () => null,
+	Spinner: () => null,
+	Tooltip: ({ trigger }: any) => trigger,
+	useFieldControl: (props: any) => ({ props, inField: false }),
+}))
+
+const roots: any[] = []
+function mount(jsx: any) {
+	const el = document.createElement('div')
+	document.body.append(el)
+	const root = createRoot(el)
+	roots.push(root)
+	act(() => root.render(jsx))
+	return el
+}
+
+afterEach(() => {
+	for (const root of roots.splice(0)) {
+		act(() => root.unmount())
+	}
+
+	document.body.innerHTML = ''
+})
+
+describe('FileInput (web)', () => {
+	it('validates and emits portable refs from a custom source', async () => {
+		const change = vi.fn()
+		const el = mount(
+			<FileInput
+				value={null}
+				onChange={change}
+				isMultiple={true}
+				accept=".txt"
+				pick={() =>
+					Promise.resolve([
+						{ name: 'ok.txt', uri: 'blob:1', size: 10 },
+						{ name: 'no.exe', uri: 'blob:2', size: 10 },
+					])
+				}
+			/>,
+		)
+
+		await act(async () => {
+			el.querySelector('.vx-fileinput-trigger')!.dispatchEvent(
+				new MouseEvent('click', { bubbles: true }),
+			)
+		})
+
+		expect(change).toHaveBeenCalledWith([{ name: 'ok.txt', uri: 'blob:1', size: 10 }])
+		expect(el.querySelector('.vx-field-status')?.textContent).toContain('no.exe')
+	})
+
+	it('replaces a single value even when the list length stays one', async () => {
+		const change = vi.fn()
+		const el = mount(
+			<FileInput
+				value={{ name: 'old.txt', uri: 'blob:old' }}
+				onChange={change}
+				pick={() => Promise.resolve({ name: 'new.txt', uri: 'blob:new' })}
+			/>,
+		)
+
+		await act(async () => {
+			el.querySelector('.vx-fileinput-trigger')!.dispatchEvent(
+				new MouseEvent('click', { bubbles: true }),
+			)
+		})
+
+		expect(change).toHaveBeenCalledWith({ name: 'new.txt', uri: 'blob:new' })
+	})
+
+	it('retains the current file when a replacement fails validation', async () => {
+		const change = vi.fn()
+		const el = mount(
+			<FileInput
+				value={{ name: 'old.txt', uri: 'blob:old' }}
+				onChange={change}
+				accept=".txt"
+				pick={() => Promise.resolve({ name: 'new.exe', uri: 'blob:new' })}
+			/>,
+		)
+
+		await act(async () => {
+			el.querySelector('.vx-fileinput-trigger')!.dispatchEvent(
+				new MouseEvent('click', { bubbles: true }),
+			)
+		})
+
+		expect(change).not.toHaveBeenCalled()
+		expect(el.querySelector('.vx-field-status')?.textContent).toContain('new.exe')
+	})
+})

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.macos.ts

@@ -1,12 +1,53 @@
-// Files — AppKit host leaf. The dev host has no picker or save panel wired.
+// 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(): Promise<FileRef | null> {
-		throw new Error('unsupported: the AppKit host does not provide a file picker')
+	async pick(accept = '*/*'): Promise<FileRef | null> {
+		return openPanel(accept)?.[0] ?? null
 	},
-	async pickMultiple(): Promise<FileRef[]> {
-		throw new Error('unsupported: the AppKit host does not provide a file picker')
+	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')

package/src/files.ts

@@ -86,26 +86,34 @@ async function readContentUri(uri: string): Promise<string> {
 	}
 }
 
+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 its opaque native URI. */
+	/** 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> {
-		const { extensions, mimeTypes } = pickerTypes(accept)
-		const result = await openFilePicker({
-			extensions,
-			mimeTypes,
-			multipleSelection: false,
-			permissions: { read: true, persistable: true },
-			startingFolder: opts?.startingFolder,
-		})
-
-		const uri = result.files?.[0]
-
-		if (!uri) {
-			return null
-		}
-
-		const name = androidDisplayName(uri, result.android) ?? fallbackName(uri)
-		return { name, uri }
+		return (await pickFiles(accept, false, opts))[0] ?? null
 	},
 	async readText(ref: FileRef): Promise<string> {
 		if (ref.uri.startsWith('content://')) {

package/src/files.web.ts

@@ -3,25 +3,37 @@
 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 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()

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,8 @@ 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()` downloads on web and writes where implemented.
+	 * Picked mobile files may use `content://` URIs.
 	 */
 	uri: string
 }

package/types/index.d.ts

@@ -0,0 +1,15 @@
+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 { FileRef } from '../src/types.js'

package/types/index.macos.d.ts

@@ -0,0 +1,14 @@
+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 { FileRef } from '../src/types.js'