@gjsify/file-chooser 0.0.0-stage → 0.61.0

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# @gjsify/file-chooser
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`Gtk.FileDialog`, `Gtk.FileFilter` and `Gio.File` as one import on GJS, the browser and
+NativeScript ([ADR 0100](../../../docs/adr/0100-file-dialog-and-gio-file-run-on-the-browser-and-nativescript.md)).
+
+```ts
+import { FileDialog, FileFilter, File, ListStore, promisify } from '@gjsify/file-chooser';
+
+promisify(FileDialog.prototype, 'open', 'open_finish');
+promisify(File.prototype, 'load_contents_async', 'load_contents_finish');
+
+const filter = FileFilter.new();
+filter.set_name('Assembly');
+filter.add_suffix('asm');
+const filters = new ListStore({ item_type: FileFilter.$gtype });
+filters.append(filter);
+
+const file = await new FileDialog({ filters }).open(window, null);
+const [contents] = await file.load_contents_async(null);
+```
+
+| Target | What you get |
+|---|---|
+| GJS | the native `gi://` classes, by identity; the xdg portal is the dialog |
+| browser | File System Access where `showSaveFilePicker` exists, otherwise a self-drawn Adwaita dialog over the Origin Private File System |
+| NativeScript (Android) | the Storage Access Framework (`ACTION_OPEN_DOCUMENT` / `ACTION_CREATE_DOCUMENT`) |
+
+The package is a strict SUBSET of the GJS API: the same names and semantics, and anything outside
+the subset (`File.new_for_uri`, `get_parent`, `query_exists`, non-modal dialogs, `open_multiple`,
+glob patterns other than `*.ext` and `*`, …) throws `UnsupportedGObjectError` rather than guessing.
+
+## Recommended import path
+
+- An app written against `gi://` that you build with `gjsify build --gi-renderer` needs nothing
+  from here: `gi://Gtk` and `gi://Gio` already resolve to the renderer, which carries the same
+  subset.
+- Code that imports `@gjsify/file-chooser` gets the right door per target through gjsify's
+  platform files (`platform.gtk.ts` / `platform.web.ts` / `platform.native.ts`). A bundler
+  without those chains gets the base, which has no driver: every `open`/`save` rejects
+  `Gtk.DialogError.FAILED` until you call `registerFileChooserDriver()`.
+
+## Behaviour you should know about
+
+- **A save is not atomic on the ports.** `replace_async` truncates and writes in place; GJS writes
+  a temporary file and renames it. A crash mid-write leaves a partial file on the web and Android.
+- **OPFS is invisible to the file manager.** On a browser without File System Access, files live
+  in the origin's private storage. The dialog's "Upload…" copies a picked file in; nothing is ever
+  saved as a download.
+- **Persistence is the app's call.** The browser may evict OPFS under storage pressure; call
+  `navigator.storage.persist()` yourself if your files must survive that.
+- **Android filters by MIME type.** An extension-only filter (`add_suffix('asm')`) opens `*/*`
+  and accepts any pick: the filter is a hint, as is usual on Android.
+- **`etag` is `null` on the ports**; the browser has no user activation outside a gesture, so a
+  dialog opened then rejects `Gtk.DialogError.FAILED`.
+- **iOS has no picker yet**: `open`/`save` reject `FAILED`.
+
+## Conformance
+
+`@gjsify/file-chooser/conformance` exports `FILE_CHOOSER_VECTORS` and `driveFileChooserVectors`,
+the same vectors that run against real GJS, for anyone writing a driver of their own.

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/conformance.js

@@ -0,0 +1 @@
+import{FILE_CHOOSER_ROWS as e,FILE_CHOOSER_VECTORS as t,driveFileChooserVectors as n,promisifyFileChooser as r}from"@gjsify/adwaita-core/conformance";export{e as FILE_CHOOSER_ROWS,t as FILE_CHOOSER_VECTORS,n as driveFileChooserVectors,r as promisifyFileChooser};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{Bytes as e,DialogError as t,File as n,FileCreateFlags as r,FileDialog as i,FileFilter as a,FileOutputStream as o,GLibError as s,IOErrorEnum as c,ListStore as l,OutputStream as u,promisify as d,registerFileChooserDriver as f}from"./platform.js";export{e as Bytes,t as DialogError,n as File,r as FileCreateFlags,i as FileDialog,a as FileFilter,o as FileOutputStream,s as GLibError,c as IOErrorEnum,l as ListStore,u as OutputStream,d as promisify,f as registerFileChooserDriver};

package/lib/esm/platform.gtk.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import e from"gi://Gio?version=2.0";import t from"gi://GLib?version=2.0";import n from"gi://Gtk?version=4.0";const r=n.FileDialog,i=n.FileFilter,a=n.DialogError,o=e.File,s=e.ListStore,c=e.OutputStream,l=e.FileOutputStream,u=e.FileCreateFlags,d=e.IOErrorEnum,f=e._promisify,p=t.Bytes,m=t.Error;function registerFileChooserDriver(e){throw Error(`registerFileChooserDriver() has no effect on GJS: Gtk.FileDialog is native there and the xdg portal is its driver (ADR 0101).`)}export{p as Bytes,a as DialogError,o as File,u as FileCreateFlags,r as FileDialog,i as FileFilter,l as FileOutputStream,m as GLibError,d as IOErrorEnum,s as ListStore,c as OutputStream,f as promisify,registerFileChooserDriver};

package/lib/esm/platform.js

@@ -0,0 +1 @@
+import{DialogError as e,FileCreateFlags as t,GLibBytes as n,GLibError as r,GioFile as i,GioFileOutputStream as a,GioListStore as o,GioOutputStream as s,GtkFileDialog as c,GtkFileFilter as l,IOErrorEnum as u,promisify as d,registerFileChooserDriver as f}from"@gjsify/adwaita-core";export{n as Bytes,e as DialogError,i as File,t as FileCreateFlags,c as FileDialog,l as FileFilter,a as FileOutputStream,r as GLibError,u as IOErrorEnum,o as ListStore,s as OutputStream,d as promisify,f as registerFileChooserDriver};

package/lib/esm/platform.native.js

@@ -0,0 +1 @@
+import{registerFileChooserDriver as e}from"@gjsify/adwaita-core";import{GLib as t,Gio as n,Gtk as r}from"@gjsify/adwaita-nativescript";const i=r.FileDialog,a=r.FileFilter,o=r.DialogError,s=n.File,c=n.ListStore,l=n.OutputStream,u=n.FileOutputStream,d=n.FileCreateFlags,f=n.IOErrorEnum,p=n._promisify,m=t.Bytes,h=t.Error;export{m as Bytes,o as DialogError,s as File,d as FileCreateFlags,i as FileDialog,a as FileFilter,u as FileOutputStream,h as GLibError,f as IOErrorEnum,c as ListStore,l as OutputStream,p as promisify,e as registerFileChooserDriver};

package/lib/esm/platform.web.js

@@ -0,0 +1 @@
+import{registerFileChooserDriver as e}from"@gjsify/adwaita-core";import{GLib as t,Gio as n,Gtk as r}from"@gjsify/adwaita-web";const i=r.FileDialog,a=r.FileFilter,o=r.DialogError,s=n.File,c=n.ListStore,l=n.OutputStream,u=n.FileOutputStream,d=n.FileCreateFlags,f=n.IOErrorEnum,p=n._promisify,m=t.Bytes,h=t.Error;export{m as Bytes,o as DialogError,s as File,d as FileCreateFlags,i as FileDialog,a as FileFilter,u as FileOutputStream,h as GLibError,f as IOErrorEnum,c as ListStore,l as OutputStream,p as promisify,e as registerFileChooserDriver};

package/lib/types/conformance.d.ts

@@ -0,0 +1,2 @@
+export { FILE_CHOOSER_ROWS, FILE_CHOOSER_VECTORS, driveFileChooserVectors, promisifyFileChooser, } from '@gjsify/adwaita-core/conformance';
+export type { FileChooserNamespaces, FileChooserRow, FileChooserSubject, FileChooserVector, ScriptedPick, } from '@gjsify/adwaita-core/conformance';

package/lib/types/index.browser.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/index.d.ts

@@ -0,0 +1,2 @@
+export { FileDialog, FileFilter, File, ListStore, OutputStream, FileOutputStream, FileCreateFlags, IOErrorEnum, DialogError, Bytes, GLibError, promisify, registerFileChooserDriver, } from './platform.js';
+export type { FileChooserDriver, FileChooserHandle, FileChooserRequest, FileChooserWriter } from '@gjsify/adwaita-core';

package/lib/types/index.gjs.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/platform.d.ts

@@ -0,0 +1 @@
+export { GtkFileDialog as FileDialog, GtkFileFilter as FileFilter, GioFile as File, GioListStore as ListStore, GioOutputStream as OutputStream, GioFileOutputStream as FileOutputStream, FileCreateFlags, IOErrorEnum, DialogError, GLibBytes as Bytes, GLibError, promisify, registerFileChooserDriver, } from '@gjsify/adwaita-core';

package/lib/types/platform.gtk.d.ts

@@ -0,0 +1,17 @@
+import Gio from 'gi://Gio?version=2.0';
+import GLib from 'gi://GLib?version=2.0';
+import Gtk from 'gi://Gtk?version=4.0';
+import type { FileChooserDriver } from '@gjsify/adwaita-core';
+export declare const FileDialog: typeof Gtk.FileDialog;
+export declare const FileFilter: typeof Gtk.FileFilter;
+export declare const DialogError: typeof Gtk.DialogError;
+export declare const File: Gio.FileNamespace & (new () => Gio.File);
+export declare const ListStore: typeof Gio.ListStore;
+export declare const OutputStream: typeof Gio.OutputStream;
+export declare const FileOutputStream: typeof Gio.FileOutputStream;
+export declare const FileCreateFlags: typeof Gio.FileCreateFlags;
+export declare const IOErrorEnum: typeof Gio.IOErrorEnum;
+export declare const promisify: typeof Gio._promisify;
+export declare const Bytes: typeof GLib.Bytes;
+export declare const GLibError: typeof GLib.Error;
+export declare function registerFileChooserDriver(_next: FileChooserDriver | null): FileChooserDriver | null;

package/lib/types/platform.native.d.ts

@@ -0,0 +1,30 @@
+import { Gio, GLib, Gtk } from '@gjsify/adwaita-nativescript';
+import { registerFileChooserDriver } from '@gjsify/adwaita-core';
+export declare const FileDialog: typeof Gtk.FileDialog;
+export declare const FileFilter: typeof Gtk.FileFilter;
+export declare const DialogError: Readonly<{
+    FAILED: number;
+    CANCELLED: number;
+    DISMISSED: number;
+}>;
+export declare const File: typeof Gio.File;
+export declare const ListStore: typeof Gio.ListStore;
+export declare const OutputStream: typeof Gio.OutputStream;
+export declare const FileOutputStream: typeof Gio.FileOutputStream;
+export declare const FileCreateFlags: Readonly<{
+    NONE: 0;
+    PRIVATE: 1;
+    REPLACE_DESTINATION: 2;
+}>;
+export declare const IOErrorEnum: Readonly<{
+    FAILED: number;
+    NOT_FOUND: number;
+    NOT_SUPPORTED: number;
+    CLOSED: number;
+    CANCELLED: number;
+    PENDING: number;
+}>;
+export declare const promisify: typeof Gio._promisify;
+export declare const Bytes: typeof GLib.Bytes;
+export declare const GLibError: typeof GLib.Error;
+export { registerFileChooserDriver };

package/lib/types/platform.web.d.ts

@@ -0,0 +1,30 @@
+import { Gio, GLib, Gtk } from '@gjsify/adwaita-web';
+import { registerFileChooserDriver } from '@gjsify/adwaita-core';
+export declare const FileDialog: typeof Gtk.FileDialog;
+export declare const FileFilter: typeof Gtk.FileFilter;
+export declare const DialogError: Readonly<{
+    FAILED: number;
+    CANCELLED: number;
+    DISMISSED: number;
+}>;
+export declare const File: typeof Gio.File;
+export declare const ListStore: typeof Gio.ListStore;
+export declare const OutputStream: typeof Gio.OutputStream;
+export declare const FileOutputStream: typeof Gio.FileOutputStream;
+export declare const FileCreateFlags: Readonly<{
+    NONE: 0;
+    PRIVATE: 1;
+    REPLACE_DESTINATION: 2;
+}>;
+export declare const IOErrorEnum: Readonly<{
+    FAILED: number;
+    NOT_FOUND: number;
+    NOT_SUPPORTED: number;
+    CLOSED: number;
+    CANCELLED: number;
+    PENDING: number;
+}>;
+export declare const promisify: typeof Gio._promisify;
+export declare const Bytes: typeof GLib.Bytes;
+export declare const GLibError: typeof GLib.Error;
+export { registerFileChooserDriver };

package/package.json

@@ -1,6 +1,82 @@
 {
-  "name": "@gjsify/file-chooser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@gjsify/file-chooser",
+    "version": "0.61.0",
+    "description": "Gtk.FileDialog, Gtk.FileFilter and Gio.File as one import on GJS, the browser and NativeScript: the native classes on GJS, File System Access or a self-drawn OPFS dialog on the web, the Storage Access Framework on Android",
+    "keywords": [
+        "gjs",
+        "gtk",
+        "gio",
+        "file-dialog",
+        "file-system-access",
+        "opfs",
+        "nativescript",
+        "storage-access-framework"
+    ],
+    "type": "module",
+    "main": "lib/esm/index.js",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        },
+        "./conformance": {
+            "types": "./lib/types/conformance.d.ts",
+            "default": "./lib/esm/conformance.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "lib",
+        "!lib/types/**/*.spec.d.ts",
+        "!lib/types/test.d.mts"
+    ],
+    "scripts": {
+        "clear": "gjsify clear lib tmp tsconfig.tsbuildinfo test.gjs.mjs dist",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}' 'src/test.browser.{mts,ts}'",
+        "build:types": "gjsify tsc",
+        "build:test": "gjsify run build:test:gjs",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs",
+        "build:test:browser": "gjsify build src/test.browser.mts --app browser --outfile dist/test.browser.mjs",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs"
+    },
+    "gjsify": {
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "none",
+            "browser": "polyfill",
+            "nativescript": "polyfill"
+        },
+        "tier": 3
+    },
+    "dependencies": {
+        "@gjsify/adwaita-core": "^0.61.0",
+        "@gjsify/adwaita-nativescript": "^0.61.0",
+        "@gjsify/adwaita-web": "^0.61.0"
+    },
+    "devDependencies": {
+        "@girs/gio-2.0": "5.4.0",
+        "@girs/gjs": "5.4.0",
+        "@girs/glib-2.0": "5.4.0",
+        "@girs/gtk-4.0": "5.4.0",
+        "@gjsify/cli": "^0.61.0",
+        "@gjsify/unit": "^0.61.0",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "author": "Pascal Garber <pascal@artandcode.studio>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/framework/file-chooser"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/framework/file-chooser#readme"
+}