@octane-xplat/files 0.0.1 → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alec Larson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -1,3 +1,48 @@
-# @octane-xplat/files
+# `@octane-xplat/files`
 
-Version 0.0.1 is a reservation stub so the automated release can publish this package name. It has no supported API. Use a later release for the implementation.
+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'
+
+// 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)
+	}
+}
+```

package/package.json

@@ -1,19 +1,77 @@
 {
   "name": "@octane-xplat/files",
-  "version": "0.0.1",
+  "version": "0.10.0",
   "description": "Native + web file pick and read/write for Octane xplat — matching web + NativeScript implementations",
+  "keywords": [
+    "android",
+    "cross-platform",
+    "document-picker",
+    "file-picker",
+    "files",
+    "ios",
+    "nativescript",
+    "octane",
+    "web",
+    "xplat"
+  ],
+  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/files",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/octane-xplat/octane-xplat.git",
+    "url": "https://github.com/octane-xplat/octane-xplat",
     "directory": "packages/files"
   },
-  "homepage": "https://github.com/octane-xplat/octane-xplat/tree/main/packages/files",
-  "main": "./index.js",
-  "types": "./index.d.ts",
   "files": [
-    "README.md",
-    "index.js",
-    "index.d.ts"
-  ]
-}
+    "src",
+    "types"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "macos": {
+        "types": "./types/index.macos.d.ts",
+        "default": "./src/index.macos.ts"
+      },
+      "types": "./types/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./*": "./src/*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nativescript-community/ui-document-picker": "1.1.29",
+    "@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": {
+    "@nativescript-community/octane": {
+      "optional": true
+    },
+    "@nativescript/core": {
+      "optional": true
+    }
+  },
+  "nativescript": {
+    "platforms": {
+      "android": "9.1.0",
+      "ios": "9.1.0"
+    }
+  },
+  "scripts": {
+    "test:packed": "node tests/packed-consumer.mjs"
+  }
+}

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')
+	})
+})