@octane-xplat/files 0.9.0 → 0.11.0

package/README.md

@@ -1,32 +1,85 @@
 # `@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)
+## Binary reads, writes, and export
+
+`files.readBytes(ref, { maxBytes?, signal? })` reads the full contents as a
+`Uint8Array`. It works on `content://` picks (read through Android's
+`ContentResolver`), iOS picker copies, sandbox files, and web object URLs.
+`maxBytes` rejects oversized files mid-read instead of loading them, and
+`signal` aborts the read with an `AbortError`.
+
+```ts
+const bytes = await files.readBytes(file, { maxBytes: 10 * 1024 * 1024 })
 ```
 
-`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.
+`files.writeBytes(name, bytes)` mirrors `writeText`: on native it writes into
+the app sandbox (Documents) and returns a `FileRef`; on web it starts a
+browser download. `name` must be a bare file name — paths like `../x` or
+`a/b` are rejected, and `writeText` enforces the same rule.
+
+`files.export(name, bytes, { mimeType? })` asks the user where to save the
+data and resolves `saved`, `cancelled`, or `unavailable`. `saved` means the
+platform committed the bytes — Android flushes them through
+`ContentResolver` to the picked document, iOS completes the export-as-copy
+flow, and web closes a File System Access writable. Browsers without
+`showSaveFilePicker` and the AppKit leaf report `unavailable`; a share-sheet
+presentation never counts as `saved`. Only one export can run at a time — a
+concurrent call rejects with an `ExportBusyError` rather than stealing the
+open picker's result.
+
+```ts
+const result = await files.export('report.pdf', pdfBytes, { mimeType: 'application/pdf' })
+if (result === 'cancelled') console.log('user dismissed')
+```
 
-Guide: [Using device features](../../docs/platform-services.md);
-per-target availability: [platform notes](../../docs/platform-notes.md).
+Picked refs are only guaranteed readable within the picking session. Android
+`content://` grants are not persisted by the picker, and iOS import-mode
+copies live in a temp folder — copy what you need with `writeBytes`, and
+call `files.release(ref)` when done.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/files",
-  "version": "0.9.0",
+  "version": "0.11.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.11.0"
   },
   "devDependencies": {
     "@nativescript-community/octane": "0.2.4",
     "@nativescript/core": "9.1.2",
     "@nativescript/types": "9.0.0",
+    "@octane-xplat/ui": "0.11.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')
+	})
+})