@octane-xplat/files 0.10.0 → 0.11.1

package/README.md

@@ -46,3 +46,40 @@ if (file) {
 	}
 }
 ```
+
+## 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 })
+```
+
+`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')
+```
+
+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/dist/linux/FileInput.js

@@ -0,0 +1,2 @@
+import { FileInput } from "./FileInput.web.js";
+export { FileInput };

package/dist/linux/FileInput.web.js

@@ -0,0 +1,263 @@
+import { cx, formatFileSize, normalizePicked, validateFiles } from "./file-input-utils.js";
+import { Fragment, __s, bag5, clone, createElement, createScopedElement, createScopedValue, delegateEvents, evt1, hookSlots, positionalChildren, setEventHandler, setStyle, template, useId, useImperativeHandle, useRef, useState, withSlot } from "octane";
+import { bindSignalAttribute, bindSignalChild, createElementFromConfig, enableSignalBindings } from "octane/internal/client";
+import { Field, Icon, Spinner, Tooltip, useFieldControl } from "@octane-xplat/ui";
+//#region src/FileInput.web.tsrx
+enableSignalBindings(1, true);
+delegateEvents([
+	"dragenter",
+	"dragleave",
+	"dragover",
+	"drop"
+]);
+var _t$0 = /* @__PURE__ */ template("<div></div>");
+var _hs$ = /* @__PURE__ */ hookSlots(9);
+var _h$0 = /* @__PURE__ */ Symbol(_hs$);
+var _h$7 = /* @__PURE__ */ Symbol(_hs$ + 7);
+var STATUS_GLYPHS = {
+	error: "⚠",
+	warning: "⚠",
+	success: "✓"
+};
+var FileInputControl = /* @__PURE__ */ __s(function FileInputControl(inputProps, __s, __extra) {
+	const { props } = withSlot(_h$0, useFieldControl, inputProps);
+	const generatedId = useId(_hs$ + 1);
+	const inputId = props.id ?? generatedId;
+	const fileInput = useRef(null, _hs$ + 2);
+	const [dragging, setDragging] = useState(false, _hs$ + 3);
+	const [busy, setBusy] = useState(false, _hs$ + 4);
+	const [validationErrors, setValidationErrors] = useState([], _hs$ + 5);
+	const files = 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;
+	const emitValue = (next) => props.isMultiple ? next : next[0] ?? null;
+	const fireChange = (next) => {
+		const emitted = emitValue(next);
+		props.onChange?.(emitted);
+		if (props.changeAction) {
+			setBusy(true);
+			Promise.resolve(props.changeAction(emitted)).finally(() => setBusy(false));
+		}
+	};
+	const acceptRefs = (picked) => {
+		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) => {
+		if (isDisabled || isBusy) return;
+		setValidationErrors([]);
+		fireChange(files.filter((_, i) => i !== index));
+	};
+	const pick = () => {
+		if (isDisabled || isBusy) return;
+		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) => {
+		const list = e.target.files;
+		const picked = [];
+		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) => {
+		e.preventDefault();
+		e.stopPropagation();
+		setDragging(false);
+		if (isDisabled || isBusy) return;
+		const list = e.dataTransfer?.files;
+		if (!list?.length) return;
+		const picked = [];
+		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 = createScopedElement(Fragment, {}, () => positionalChildren([
+		files.length ? createScopedElement("ul", { className: "vx-fileinput-list" }, () => files.map((f, i) => createScopedElement("li", {
+			key: `${f.uri}-${i}`,
+			className: "vx-fileinput-item"
+		}, () => positionalChildren([
+			createElementFromConfig("c:b0d78e7b", Icon, {
+				name: "xplat-upload",
+				size: 14
+			}),
+			createScopedElement("span", { className: "vx-fileinput-itemname" }, () => f.name),
+			f.size != null ? createScopedElement("span", { className: "vx-fileinput-itemsize" }, () => formatFileSize(f.size)) : null,
+			!isDisabled && !isBusy ? createScopedValue(() => createElement("button", {
+				type: "button",
+				className: "vx-fileinput-itemremove",
+				"aria-label": `Remove ${f.name}`,
+				onClick: () => removeAt(i)
+			}, "×")) : null
+		])))) : null,
+		dropzone ? createScopedElement("div", { className: "vx-fileinput-dropzone-hint" }, () => positionalChildren([
+			createElementFromConfig("c:928c8dae", Icon, {
+				name: "xplat-upload",
+				size: 24
+			}),
+			createScopedElement("span", {}, () => isDisabled ? "Upload disabled" : "Drag & drop files here or click to browse"),
+			props.accept ? createScopedElement("span", { className: "vx-fileinput-accept" }, () => props.accept) : null
+		])) : createScopedValue(() => createScopedElement("button", {
+			type: "button",
+			id: inputId,
+			className: "vx-fileinput-trigger",
+			disabled: isDisabled && !showsDisabledReason || void 0,
+			"aria-disabled": showsDisabledReason || void 0,
+			"aria-describedby": props.ariaDescribedBy,
+			"aria-required": props.isRequired && !props.isOptional || void 0,
+			"aria-invalid": statusType === "error" || void 0,
+			"aria-busy": isBusy || void 0,
+			onClick: pick
+		}, () => positionalChildren([
+			createElementFromConfig("c:a0fe8d9f", Icon, {
+				name: "xplat-upload",
+				size: 14
+			}),
+			" ",
+			files.length ? "Choose more files" : "Choose files"
+		]))),
+		dropzone ? createScopedValue(() => createElement("button", {
+			type: "button",
+			id: inputId,
+			className: "vx-fileinput-trigger vx-fileinput-trigger--hidden",
+			disabled: isDisabled && !showsDisabledReason || void 0,
+			"aria-disabled": showsDisabledReason || void 0,
+			"aria-describedby": props.ariaDescribedBy,
+			"aria-required": props.isRequired && !props.isOptional || void 0,
+			"aria-invalid": statusType === "error" || void 0,
+			"aria-busy": isBusy || void 0,
+			onClick: pick
+		}, "Browse files")) : null,
+		canClear ? createScopedValue(() => createElement("button", {
+			type: "button",
+			className: "vx-fileinput-clear",
+			"aria-label": `Clear ${props.fieldLabel ?? props.label ?? "files"}`,
+			onClick: () => {
+				setValidationErrors([]);
+				fireChange([]);
+			}
+		}, "×")) : null,
+		isBusy ? createElementFromConfig("c:47d00c47", Spinner, {
+			busy: true,
+			className: "vx-fileinput-spinner"
+		}) : null,
+		statusType ? props.statusVariant === "tooltip" && statusMessage ? createScopedValue(() => createElementFromConfig("c:86665b9b", Tooltip, {
+			trigger: createScopedValue(() => createScopedElement("span", { className: cx("vx-field-icon", `vx-field-icon--${statusType}`) }, () => STATUS_GLYPHS[statusType])),
+			content: statusMessage
+		})) : createScopedValue(() => createScopedElement("span", { className: cx("vx-field-icon", `vx-field-icon--${statusType}`) }, () => STATUS_GLYPHS[statusType])) : null,
+		statusMessage && props.statusVariant !== "tooltip" ? createScopedValue(() => createScopedElement("span", {
+			className: cx("vx-field-status", `vx-field-status--${statusType}`),
+			role: statusType === "error" ? "alert" : "status"
+		}, () => statusMessage)) : null,
+		createScopedValue(() => createElement("input", {
+			ref: (el) => {
+				fileInput.current = el;
+			},
+			type: "file",
+			className: "vx-fileinput-nativeinput",
+			accept: props.accept,
+			multiple: props.isMultiple || void 0,
+			disabled: isDisabled || void 0,
+			"aria-hidden": "true",
+			tabIndex: -1,
+			onChange: handleFileSelect
+		}))
+	]));
+	useImperativeHandle(props.ref, () => ({
+		open: pick,
+		native: fileInput.current
+	}), void 0, _hs$ + 6);
+	if (__s.block.pending && !__s.block.crossRenderUpdate) return;
+	let _b = __s.slots[0];
+	if (_b === void 0) {
+		let _m1;
+		const _root = clone(_t$0);
+		_m1 = _root;
+		setEventHandler(_root, "$$dragover", (e) => {
+			e.preventDefault();
+			if (!isDisabled && !isBusy) setDragging(true);
+		});
+		setEventHandler(_root, "$$dragenter", (e) => {
+			e.preventDefault();
+		});
+		evt1(_root, "$$dragleave", setDragging, false);
+		setEventHandler(_root, "$$drop", handleDrop);
+		_b = bag5(__s, _root, void 0, _m1, void 0, null, void 0);
+	} else {
+		setEventHandler(_b.b, "$$dragover", (e) => {
+			e.preventDefault();
+			if (!isDisabled && !isBusy) setDragging(true);
+		});
+		setEventHandler(_b.b, "$$drop", handleDrop);
+	}
+	_b.a = bindSignalAttribute(__s, _b.a, _b.b, "class", 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), "b:e1094c29", "class");
+	{
+		const _v = props.style;
+		if (_b.c !== _v) {
+			setStyle(_b.b, _v, _b.c);
+			_b.c = _v;
+		}
+	}
+	_b.f = bindSignalChild(__s, _b.f, 1, _b.b, itemContent, "b:11d99fad", null, void 0, void 0, void 0, true);
+});
+var FileInput = function FileInput(props, __s, __extra) {
+	const { inField } = withSlot(_h$7, useFieldControl, props);
+	const cid = useId(_hs$ + 8);
+	const control = createScopedValue(() => createElementFromConfig("c:afa4c501", FileInputControl, { ...props }));
+	if (inField) return control ?? null;
+	return createScopedValue(() => createScopedElement(Field, {
+		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, "c:3f29a6d4"));
+};
+//#endregion
+export { FileInput };

package/dist/linux/file-bytes.js

@@ -0,0 +1,45 @@
+//#region src/file-bytes.ts
+/**
+* Shared helpers for the binary file primitives (readBytes/writeBytes/export).
+* DOM-free so the native leaf can use it too.
+*/
+/** File names used for sandbox writes and export temp files must be bare
+*  names, not paths — a `/`, `\`, or `..` segment escapes the sandbox. */
+function assertSafeFileName(name) {
+	if (typeof name !== "string" || name.length === 0 || name === "." || name === ".." || name.includes("/") || name.includes("\\") || name.includes("\0")) throw new Error(`Unsafe file name: ${JSON.stringify(name)}`);
+}
+function fileTooLarge(name, maxBytes) {
+	return /* @__PURE__ */ new Error(`${name}: file exceeds the ${maxBytes}-byte limit`);
+}
+/** Named rejection for a second `files.export` while one is in flight. */
+function exportBusy() {
+	const error = /* @__PURE__ */ new Error("files.export: an export is already in progress");
+	error.name = "ExportBusyError";
+	return error;
+}
+function throwIfAborted(signal) {
+	if (!signal?.aborted) return;
+	const thrower = signal.throwIfAborted;
+	if (typeof thrower === "function") thrower.call(signal);
+	const error = /* @__PURE__ */ new Error("The operation was aborted");
+	error.name = "AbortError";
+	throw error;
+}
+/** Concatenate Uint8Array chunks into one exact-length array. */
+function concatBytes(chunks, total) {
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		out.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return out;
+}
+/** Return an ArrayBuffer covering exactly this view's byte range — native
+*  marshallers treat the argument as the whole buffer. */
+function exactBuffer(bytes) {
+	if (bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) return bytes.buffer;
+	return bytes.slice().buffer;
+}
+//#endregion
+export { assertSafeFileName, concatBytes, exactBuffer, exportBusy, fileTooLarge, throwIfAborted };

package/dist/linux/file-input-utils.js

@@ -0,0 +1,52 @@
+//#region src/file-input-utils.ts
+function cx(...values) {
+	return values.filter(Boolean).join(" ");
+}
+function normalizePicked(result) {
+	if (result == null) return [];
+	return Array.isArray(result) ? result : [result];
+}
+function fileAccepts(file, accept) {
+	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;
+	});
+}
+function formatFileSize(bytes) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1048576) return `${(bytes / 1024).toFixed(1)} KB`;
+	if (bytes < 1073741824) return `${(bytes / 1048576).toFixed(1)} MB`;
+	return `${(bytes / 1073741824).toFixed(1)} GB`;
+}
+function validateFiles(files, opts) {
+	const errors = [];
+	const valid = [];
+	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
+	};
+}
+//#endregion
+export { cx, fileAccepts, formatFileSize, normalizePicked, validateFiles };

package/dist/linux/files.js

@@ -0,0 +1,2 @@
+import { files } from "./files.web.js";
+export { files };

package/dist/linux/files.web.js

@@ -0,0 +1,144 @@
+import { assertSafeFileName, concatBytes, exactBuffer, fileTooLarge, throwIfAborted } from "./file-bytes.js";
+import { desktopHost } from "@octane-xplat/platform/host/web";
+//#region src/files.web.ts
+var objectBlobs = /* @__PURE__ */ new Map();
+function mintObjectUrl(blob) {
+	const uri = URL.createObjectURL(blob);
+	objectBlobs.set(uri, blob);
+	return uri;
+}
+function chooseFiles(accept, multiple) {
+	return new Promise((resolve) => {
+		const input = document.createElement("input");
+		input.type = "file";
+		input.accept = accept;
+		input.multiple = multiple;
+		input.onchange = () => {
+			const refs = [];
+			for (const file of Array.from(input.files ?? [])) refs.push({
+				name: file.name,
+				uri: mintObjectUrl(file)
+			});
+			resolve(refs);
+		};
+		input.oncancel = () => resolve([]);
+		input.click();
+	});
+}
+async function fetchBytes(uri, opts) {
+	const response = await fetch(uri, { signal: opts?.signal });
+	if (!response.ok) throw new Error(`Unable to read file: ${uri}`);
+	if (opts?.maxBytes == null) return new Uint8Array(await response.arrayBuffer());
+	const reader = response.body?.getReader();
+	if (!reader) {
+		const bytes = new Uint8Array(await response.arrayBuffer());
+		if (bytes.byteLength > opts.maxBytes) throw fileTooLarge(uri, opts.maxBytes);
+		return bytes;
+	}
+	const chunks = [];
+	let total = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			total += value.byteLength;
+			if (total > opts.maxBytes) {
+				await reader.cancel().catch(() => {});
+				throw fileTooLarge(uri, opts.maxBytes);
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	return concatBytes(chunks, total);
+}
+var files = {
+	async pickMultiple(accept = "*/*", _opts) {
+		return chooseFiles(accept, true);
+	},
+	async pick(accept = "*/*", opts) {
+		const host = desktopHost();
+		if (host && await host.supports("files", "pick")) return host.files.pick(accept, { startingFolder: opts?.startingFolder });
+		return (await chooseFiles(accept, false))[0] ?? null;
+	},
+	async readText(ref) {
+		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();
+	},
+	async readBytes(ref, opts) {
+		throwIfAborted(opts?.signal);
+		const blob = objectBlobs.get(ref.uri);
+		if (blob) {
+			if (opts?.maxBytes != null && blob.size > opts.maxBytes) throw fileTooLarge(ref.uri, opts.maxBytes);
+			const bytes = new Uint8Array(await blob.arrayBuffer());
+			throwIfAborted(opts?.signal);
+			return bytes;
+		}
+		return fetchBytes(ref.uri, opts);
+	},
+	/** Desktop hosts write the selected path; plain web starts a download. */
+	async writeText(name, text) {
+		assertSafeFileName(name);
+		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 = mintObjectUrl(new Blob([text], { type: "text/plain" }));
+		const a = document.createElement("a");
+		a.href = uri;
+		a.download = name;
+		a.click();
+		return {
+			name,
+			uri
+		};
+	},
+	/** The desktop host contract is text-only, so bytes always download. */
+	async writeBytes(name, bytes) {
+		assertSafeFileName(name);
+		const uri = mintObjectUrl(new Blob([exactBuffer(bytes)], { type: "application/octet-stream" }));
+		const a = document.createElement("a");
+		a.href = uri;
+		a.download = name;
+		a.click();
+		return {
+			name,
+			uri
+		};
+	},
+	async export(name, bytes, opts) {
+		assertSafeFileName(name);
+		const picker = window.showSaveFilePicker;
+		if (typeof picker !== "function") return "unavailable";
+		const extension = name.includes(".") ? `.${name.split(".").pop()}` : null;
+		const types = opts?.mimeType && extension ? [{ accept: { [opts.mimeType]: [extension] } }] : void 0;
+		try {
+			const writable = await (await picker.call(window, {
+				suggestedName: name,
+				types
+			})).createWritable();
+			await writable.write(bytes);
+			await writable.close();
+			return "saved";
+		} catch (error) {
+			if (error?.name === "AbortError") return "cancelled";
+			throw error;
+		}
+	},
+	release(ref) {
+		if (ref.uri.startsWith("blob:")) {
+			objectBlobs.delete(ref.uri);
+			URL.revokeObjectURL(ref.uri);
+		}
+	}
+};
+//#endregion
+export { files };

package/dist/linux/index.js

@@ -0,0 +1,5 @@
+import { FileInput } from "./FileInput.web.js";
+import "./FileInput.js";
+import { files } from "./files.web.js";
+import "./files.js";
+export { FileInput, files };

package/dist/linux/octane-client-build.json

@@ -0,0 +1,8 @@
+{
+  "version": 1,
+  "buildId": "190c966d-ea82-4510-9cd2-4581c6451685",
+  "mode": "production",
+  "capabilities": {
+    "independentHydration": false
+  }
+}