@crossbind/extension-files 0.0.0-bootstrap.0 → 2.0.0-beta.69

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Buğra Sarı and crossbind contributors
+
+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,6 +1,29 @@
 # @crossbind/extension-files
 
-This version, 0.0.0-bootstrap.0, holds no code. npm lets a trusted publisher be configured only for a
-package that exists, so it reserves the name for the crossbind release workflow.
+The files the system opens the app with.
 
-Install the real package: `npm install @crossbind/extension-files@beta`. Source: https://github.com/crossbind/crossbind
+An app has it by having `@crossbind/core-app-host`, which lists it as a dependency: there is nothing to install or list.
+
+## Use
+
+```js
+import { app, events } from 'crossbind/app';
+
+events.on('open-files', ({ paths }) => openAll(paths));
+openAll(await app.launchFiles());
+```
+
+## Options
+
+`app.fileTypes` lists the types of files the app opens, as `[{ name: 'GeoJSON', extensions: ['geojson'] }]`. The page
+gets those no extension's type takes. The app has this extension only where a type is listed.
+
+## Platforms
+
+macOS, Linux, Windows, iOS and Android.
+
+## Replace or leave out
+
+It holds the role `files`. An extension that gives `replaces: 'files'` takes it; `app: { without: ['files'] }` in `crossbind.config.js` leaves it out. Leaving it out while `app.fileTypes` is set stops the build. [The guide](https://crossbind.dev/guide/extensions/#replace) shows how, and [extensions.md](https://github.com/crossbind/crossbind/blob/main/docs/api/extensions.md#the-hosts-own-extensions) what a replacement answers.
+
+[app.md](https://github.com/crossbind/crossbind/blob/main/docs/api/app.md#files) has each platform's rules.

package/crossbind.extension.js

@@ -0,0 +1,13 @@
+export default function files() {
+    return {
+        name: 'files',
+        contract: 1,
+        root: import.meta.dirname,
+        reads: ['fileTypes'],
+        // An app that opens files of any owner, whose files no extension owns it hands the page.
+        fromApp: (api) => (api.app.fileTypes.length > 0 ? {} : null),
+        app: {
+            sources: ['native/files.cpp'],
+        },
+    };
+}

package/native/files.cpp

@@ -0,0 +1,11 @@
+// The files the system opens the app with that no extension's type takes, those of app.fileTypes among them, which the
+// build gives this extension: the page asks for those that came before it listened with crossbind/app's
+// app.launchFiles(), and hears of each later opening as the event open-files.
+#include "crossbind/app.h"
+#include "crossbind/extension.h"
+
+void crossbind_extension_files(crossbind::Registry &registry) {
+    registry.onOpenFiles([](const crossbind::OpenFiles &open) {
+        crossbind::app::holdEvent("open-files", crossbind::Value(crossbind::Value::Object{{"paths", open.paths}}).json());
+    });
+}

package/package.json

@@ -1,7 +1,41 @@
 {
-    "name": "@crossbind/extension-files",
-    "version": "0.0.0-bootstrap.0",
-    "description": "Placeholder that let npm trust the crossbind release workflow; install @crossbind/extension-files@beta.",
-    "license": "MIT",
-    "repository": "https://github.com/crossbind/crossbind.git"
-}
+  "name": "@crossbind/extension-files",
+  "version": "2.0.0-beta.69",
+  "description": "crossbind app extension: the files the system opens the app with.",
+  "homepage": "https://github.com/crossbind/crossbind/tree/main/extensions/files#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crossbind/crossbind.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./page": {
+      "types": "./page.d.ts",
+      "default": "./page.js"
+    },
+    "./crossbind.extension.js": "./crossbind.extension.js"
+  },
+  "files": [
+    "crossbind.extension.js",
+    "native",
+    "page.d.ts",
+    "page.js"
+  ],
+  "crossbind": {
+    "extension": "./crossbind.extension.js"
+  },
+  "peerDependencies": {
+    "crossbind": "^2.0.0-beta.69"
+  },
+  "devDependencies": {
+    "crossbind": "^2.0.0-beta.69"
+  },
+  "keywords": [
+    "crossbind-extension",
+    "crossbind",
+    "launch",
+    "files",
+    "app"
+  ]
+}

package/page.d.ts

@@ -0,0 +1,20 @@
+/** What the event open-files carries: the absolute paths of the files the system opened the app with at once. */
+export interface OpenFiles {
+    paths: string[];
+}
+
+export declare const app: {
+    /** The files the system opened the app with that have not reached the page yet, those of app.fileTypes in crossbind.config.js and those no extension's type takes, the launch's own among them, each by its absolute path. Once the page has asked, each later opening comes as the event open-files while it listens, so listening first, then asking, misses none. */
+    launchFiles(): Promise<string[]>;
+};
+
+declare module 'crossbind/app/core' {
+    interface AppEvents {
+        /** Calls listener with each set of files the system opens the app with once the page has called app.launchFiles(), or events.held('open-files'), until the function it returns is called. */
+        'open-files': OpenFiles;
+    }
+    interface HeldEvents {
+        /** The files the host held for the page, which came before it asked since it loaded, as app.launchFiles() gives their paths. */
+        'open-files': OpenFiles;
+    }
+}

package/page.js

@@ -0,0 +1,8 @@
+import { events } from 'crossbind/app/core';
+
+export const app = {
+    // The files the system opened the app with that have not reached the page yet, those no extension's type takes, the
+    // launch's own among them, which the host holds as the events open-files; later ones come as the event.
+    launchFiles: async () => (await events.held('open-files')).flatMap((value) => (Array.isArray(value?.paths) ? value.paths : []))
+        .filter((path) => typeof path === 'string'),
+};