@octane-xplat/files 0.0.1 → 0.9.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,32 @@
-# @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.
+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
+```
+
+```ts
+import { files } from '@octane-xplat/files'
+
+const ref = await files.pick('image/*')
+if (ref) {
+	const text = await files.readText(ref)
+	files.release(ref)
+}
+
+// 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,19 +1,70 @@
 {
   "name": "@octane-xplat/files",
-  "version": "0.0.1",
+  "version": "0.9.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"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "macos": "./src/index.macos.ts",
+      "default": "./src/index.ts"
+    },
+    "./*": "./src/*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nativescript-community/ui-document-picker": "1.1.29",
+    "@octane-xplat/platform": "0.9.0"
+  },
+  "devDependencies": {
+    "@nativescript-community/octane": "0.2.4",
+    "@nativescript/core": "9.1.2",
+    "@nativescript/types": "9.0.0",
+    "octane": "0.6.3"
+  },
+  "peerDependencies": {
+    "@nativescript-community/octane": ">=0.2.1 <1",
+    "@nativescript/core": ">=9.1.0 <10",
+    "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/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,18 @@
+// Files — AppKit host leaf. The dev host has no picker or save panel wired.
+import type { FileRef } from './types'
+
+export const files = {
+	async pick(): Promise<FileRef | null> {
+		throw new Error('unsupported: the AppKit host does not provide a file picker')
+	},
+	async pickMultiple(): Promise<FileRef[]> {
+		throw new Error('unsupported: the AppKit host does not provide a file picker')
+	},
+	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,133 @@
+// 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()
+	}
+}
+
+export const files = {
+	/** Opens the platform document picker and returns its opaque native 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 }
+	},
+	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,63 @@
+// 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'
+
+export const files = {
+	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()
+		})
+	},
+	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,2 @@
+export * from './types'
+export { files } from './files.macos'

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './types'
+export { files } from './files'

package/src/types.ts

@@ -0,0 +1,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.
+	 */
+	uri: string
+}

package/index.d.ts

@@ -1 +0,0 @@
-export {}

package/index.js

@@ -1,2 +0,0 @@
-// Reservation stub; implementation will arrive in a later release.
-module.exports = {}