crossbind 2.0.0-beta.68 → 2.0.0-beta.69

package/src/app/index.d.ts

@@ -1,171 +1,164 @@
-// What an app's host does for its page (target.runtimeEnv: 'app'); in any other build every call rejects.
+// What an app's host does for its page (target.runtimeEnv: 'app'): crossbind/app/core alone, which crossbind/app has with
+// what crossbind's own extensions give the page. A TypeScript app has their types with
+// /// <reference types="@crossbind/core-app-host/app" />.
 
-/** A kind of file a dialog offers: its name, and the extensions, with or without the dot, that make it; "*" is any file. */
-export interface FileFilter {
-    name: string;
-    extensions: string[];
-}
-
-export interface OpenOptions {
-    title?: string;
-    /** The folder the dialog shows first. */
-    defaultPath?: string;
-    filters?: FileFilter[];
-    /** Folders instead of files. */
-    directory?: boolean;
-    multiple?: boolean;
-}
-
-export interface SaveOptions {
-    title?: string;
-    /** The folder the dialog shows first. */
-    defaultPath?: string;
-    defaultName?: string;
-    filters?: FileFilter[];
-}
-
-export interface MessageOptions {
-    message: string;
-    /** Smaller text under the message. */
-    detail?: string;
-    /** info by default. Windows shows its icon for each, and macOS a caution sign for error; Linux, iOS and Android show none. */
-    kind?: 'info' | 'warning' | 'error';
-    /** One to three labels, the first the default; without them OK. */
-    buttons?: string[];
-}
-
-/** The app's own folders, made when first asked for: what it keeps, what it can lose, and its logs. */
+/** The app's own folders, made when first asked for: what it keeps, what it can lose, and its logs; and the read-only one of the files app.files lists, each in the place it had in the project. */
 export interface AppPaths {
     data: string;
     cache: string;
     logs: string;
+    resources: string;
+    /** An iOS app's App Group's folder, which the targets of its extensions' that ask for it with appGroup: true share; '' elsewhere. */
+    group: string;
 }
 
-export declare const dialog: {
-    /** The paths of the files or folders the user picked, or null when they cancelled. */
-    open(options?: OpenOptions): Promise<string[] | null>;
-    /** The path the user chose to save to, or null when they cancelled. */
-    save(options?: SaveOptions): Promise<string | null>;
-    /** The index of the button the user clicked: Return gives the first, and Escape or closing the dialog the last. */
-    message(options: MessageOptions): Promise<number>;
-};
-
-export declare const shell: {
-    /** An http, https or mailto address in the default browser or mail app. */
-    openExternal(url: string | URL): Promise<void>;
-    /** A file in the app the system opens its kind with, where app.openPath in crossbind.config.js lets the page: nowhere without it. */
-    openPath(path: string): Promise<void>;
-    /** A file, selected, in the system's file manager: one in the app's folders, or one a dialog picked during this run. */
-    revealInFolder(path: string): Promise<void>;
-    /** A file or folder moved to the system's trash, where its user can take it back: one in the app's folders, not one of them itself, or one a dialog picked during this run. Where the system has no trash, nothing moves and it rejects. */
-    trash(path: string): Promise<void>;
-};
-
 export declare const app: {
     paths(): Promise<AppPaths>;
     /** Ends the app as closing its window does. */
     quit(): Promise<void>;
+    /** Asks the app's extensions, as its user's Quit does, then ends the app as quit() does, unless one keeps it running. It resolves once it has asked the host, before the answer. */
+    requestQuit(): Promise<void>;
     /** Ends the app as quit() does, then opens it again, with no link. */
     relaunch(): Promise<void>;
-    /** The links of app.urlSchemes in crossbind.config.js that opened the app and have not reached the page yet, the one it was launched with among them. Once the page has asked, each later link comes as the event open-url while it listens, so listening first, then asking, misses none. */
-    launchUrls(): Promise<string[]>;
+    /** The launch that started a desktop app. A phone's has no arguments, and no folder. */
+    launchArgs(): Promise<Launch>;
 };
 
-/** A key with CmdOrCtrl, Ctrl or Alt and maybe Shift, joined by +, as CmdOrCtrl+Shift+O is, or F1–F12, alone or with any of them. The key is A–Z, 0–9, F1–F12, Enter, Escape, Tab, Space, Backspace, Delete, Up, Down, Left, Right, Home, End, PageUp, PageDown, Plus, Minus, Comma or Period. */
-export type Accelerator = string;
-
-/** An item of a menu: one the page handles, by its id, a submenu, a separator, or a standard one by its role. */
-export type MenuItem =
-    | { label: string; id?: string; accelerator?: Accelerator; enabled?: boolean; checked?: boolean }
-    | { label: string; items: MenuItem[] }
-    | { type: 'separator' }
-    | { role: 'undo' | 'redo' | 'cut' | 'copy' | 'paste' | 'selectAll'; label?: string; accelerator?: never }
-    | { role: 'minimize' | 'close' | 'quit'; label?: string; accelerator?: Accelerator }
-    | { role: 'editMenu' | 'windowMenu'; label?: string };
-
-/** A menu of the bar, by its items, or a standard one by its role. */
-export type Menu = { label: string; items: MenuItem[] } | { role: 'editMenu' | 'windowMenu'; label?: string };
-
-/** What the event menu carries: the id of the item clicked, and for one with checked whether it now is. */
-export interface MenuClick {
-    id: string;
-    checked?: boolean;
+/** What windows.set() changes of an open window: sizes and places in logical pixels, a page's size without the frame, and x and y the frame's place from the top left of the main screen, given together. A limit of 0 takes it away. */
+export interface WindowChanges {
+    title?: string;
+    width?: number;
+    height?: number;
+    x?: number;
+    y?: number;
+    /** Moves the window to the middle of its screen. */
+    center?: boolean;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    resizable?: boolean;
+    /** Keeps the window above the other apps' windows. */
+    alwaysOnTop?: boolean;
+    fullscreen?: boolean;
 }
 
-export declare const menu: {
-    /** Sets the app's menus: on macOS after its app menu, which the app keeps, and on Windows and Linux in a bar of its window. A click of an item with an id is an event, menu, with a MenuClick. */
-    set(menus: Menu[]): Promise<void>;
-};
+/** What a window opens with: app.window's options, beside the page it loads and its name. Without x and y it opens in the middle of the screen. */
+export interface WindowOptions extends Omit<WindowChanges, 'center' | 'minWidth' | 'minHeight' | 'maxWidth' | 'maxHeight'> {
+    /** The app's own page, as /settings.html?tab=2: '/' by default. */
+    path?: string;
+    /** A name of the app's own: a window of a name already open comes to the front, and no other opens. */
+    name?: string;
+    minWidth?: number;
+    minHeight?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    /** What the window shows until the page paints, as #rrggbb: app.window's by default. */
+    backgroundColor?: string;
+    /** false opens a window without a title bar and its buttons, which the page moves with data-crossbind-drag or windows.startDrag(). */
+    frame?: boolean;
+    /** The id of the window it stays above, and closes with. */
+    parent?: number;
+    /** With a parent: a sheet of the parent's on macOS, and on Windows and Linux a window the parent takes no input under until it closes. */
+    modal?: boolean;
+}
 
-/** An item of the tray's menu: one the page handles, by its id, a submenu or a separator. */
-export type TrayItem =
-    | { label: string; id?: string; enabled?: boolean; checked?: boolean }
-    | { label: string; items: TrayItem[] }
-    | { type: 'separator' };
-
-export interface TrayOptions {
-    /** What the icon shows when the pointer rests on it. */
-    tooltip?: string;
-    /** The menu a click of the icon opens: a click on macOS, a right click on Windows, and on Linux the one its desktop takes. */
-    menu?: TrayItem[];
+/** An open window, as windows.list() tells of it. */
+export interface WindowState {
+    id: number;
+    name: string | null;
+    title: string;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    isMaximized: boolean;
+    isMinimized: boolean;
+    isFullscreen: boolean;
+    isFocused: boolean;
 }
 
-export declare const tray: {
-    /** The app's icon in the macOS menu bar, the Windows notification area or a Linux desktop's status tray. A click of an item with an id is the event menu, with a MenuClick, and a click of the icon the event tray where it opens no menu. Set again, it changes the icon that shows. */
-    set(options?: TrayOptions): Promise<void>;
-    /** Takes the icon away. */
-    remove(): Promise<void>;
-};
+/** What windows.open() and windows.set() answer: the window's id, and the options the platform could not honour, which it did without, as Wayland's x and y. */
+export interface WindowOpened {
+    id: number;
+    ignored: string[];
+}
 
-export interface NotificationOptions {
-    title: string;
-    body?: string;
+/** What the events window-opened and window-closed carry. */
+export interface WindowEvent {
+    id: number;
+    name: string | null;
 }
 
-export declare const notification: {
-    /** A notification of the system's; a click on it is the event notification. macOS asks its user first. */
-    show(options: NotificationOptions): Promise<void>;
+export declare const windows: {
+    /** Opens a window of the app's own page, in front, on the desktop and an iPad whose app.ios.multipleWindows is true; an iPhone and Android reject. */
+    open(options?: WindowOptions): Promise<WindowOpened>;
+    /** Changes the window of this id, or the page's own without one. */
+    set(changes: WindowChanges): Promise<{ ignored: string[] }>;
+    set(id: number, changes: WindowChanges): Promise<{ ignored: string[] }>;
+    /** Closes the window of this id, or the page's own without one, as its user does: an extension may keep it open. The app quits as its last window closes. */
+    close(id?: number): Promise<void>;
+    /** Brings the window of this id, or the page's own without one, to the front, restored if it was minimized. */
+    focus(id?: number): Promise<void>;
+    minimize(id?: number): Promise<void>;
+    toggleMaximize(id?: number): Promise<void>;
+    /** Moves the page's window with the pointer, as its title bar does, from a mousedown of the primary button. */
+    startDrag(): Promise<void>;
+    /** The open windows, the oldest first. */
+    list(): Promise<WindowState[]>;
+    /** The page's own window. */
+    current(): Promise<WindowState>;
 };
 
-/** What the event second-instance carries: a later launch's arguments, the program's own left out, and the folder it was launched in. */
-export interface SecondInstance {
+/** A launch of a desktop app: its arguments, the program's own and its links left out, which reach the owners of their schemes, the page those of app.urlSchemes as the event open-url; and the folder it was launched in. */
+export interface Launch {
     args: string[];
     cwd: string;
 }
 
-/** What the event open-url carries: a link of one of app.urlSchemes that the system opened the app with. */
-export interface OpenUrl {
-    url: string;
+/** What each event a page's listeners get gives them, by the event's name: the host's own here, and those an extension's types add. */
+export interface AppEvents {
+    /** Calls listener as the app becomes the active one on the desktop, or comes to a phone's foreground, until the function it returns is called. A Linux app's is its window's focus. */
+    'active': void;
+    /** Calls listener as another app takes the app's place on the desktop, or a phone's is interrupted, as by a call, a system alert or another app's picker, or goes to the background, until the function it returns is called. */
+    'inactive': void;
+    /** Calls listener as each window of the app's opens, until the function it returns is called. */
+    'window-opened': WindowEvent;
+    /** Calls listener as each window of the app's closes, until the function it returns is called. */
+    'window-closed': WindowEvent;
 }
 
+/** What each event the host holds for the page gives, by the event's name, which an extension's types add. */
+export interface HeldEvents {}
+
 export declare const events: {
-    /** Calls listener with each click of an item with an id in the menus menu.set sets or in the tray's menu, until the function it returns is called. */
-    on(name: 'menu', listener: (click: MenuClick) => void): () => void;
-    /** Calls listener with each link of app.urlSchemes the system opens the app with once the page has called app.launchUrls(), until the function it returns is called. */
-    on(name: 'open-url', listener: (open: OpenUrl) => void): () => void;
-    /** Calls listener with each later launch of a desktop app that app.singleInstance keeps to one instance, which brings its window to the front as far as the system lets it, until the function it returns is called. */
-    on(name: 'second-instance', listener: (launch: SecondInstance) => void): () => void;
-    /** Calls listener as the system of a desktop app goes to sleep, which it may do before the page has run, until the function it returns is called. */
-    on(name: 'suspend', listener: () => void): () => void;
-    /** Calls listener as the system of a desktop app wakes from sleep, until the function it returns is called. */
-    on(name: 'resume', listener: () => void): () => void;
-    /** Calls listener with each left or right click of the tray's icon that opens no menu, until the function it returns is called. */
-    on(name: 'tray', listener: () => void): () => void;
-    /** Calls listener with each click on a notification the app's notification.show showed while it runs, until the function it returns is called. */
-    on(name: 'notification', listener: () => void): () => void;
+    on<Name extends keyof AppEvents>(name: Name, listener: (value: AppEvents[Name]) => void): () => void;
     /** Calls listener with the value of each event of this name the app's native code emits from now on, until the function it returns is called. */
     on(name: string, listener: (value: unknown) => void): () => void;
+    held<Name extends keyof HeldEvents>(name: Name): Promise<HeldEvents[Name][]>;
+    /** The values of the events of this name the app's native code held for the page with holdEvent(), which came before the page asked for them since it loaded; later ones come as the events while it listens, so listening first, then asking, misses none. */
+    held(name: string): Promise<unknown[]>;
 };
 
-/** A newer version of the app, which app.updater.url in crossbind.config.js offers. */
-export interface Update {
-    version: string;
+/** What an option of a page's function is, beside what typeof tells: how it is checked, and what it is called. */
+export interface OptionKind {
+    isFitting(value: unknown): boolean;
+    name: string;
 }
 
-/** One check or install runs at a time, and another rejects meanwhile. */
-export declare const updater: {
-    /** The version app.updater.url offers when it is newer than the app's, or null. */
-    check(): Promise<Update | null>;
-    /** Downloads that version, checks that the key of app.updater.publicKey signed it and installs it in place of the app, which then quits and opens the new version. It rejects when that fails. */
-    install(): Promise<void>;
-};
+/** The options as the host takes them, so a misspelt or mistyped one fails here, saying which. */
+export declare function checkedOptions<T>(name: string, options: T, kinds: Record<string, string | OptionKind>): T;
+
+/** What invoke takes beside a function's options. */
+export interface InvokeOptions<M = unknown> {
+    /** Gets each message the function sends before it answers, in the order it sent them, all of them before invoke resolves. */
+    onMessage?: (message: M) => void;
+    /** Cancels the call: invoke rejects with the signal's reason, and the function hears of it. A new page cancels each call of the one before. */
+    signal?: AbortSignal;
+}
+
+/** A function of one of the app's extensions, by its name, as clipboard.readText, with options of JSON values and bytes, a typed array, a DataView or an ArrayBuffer, whose result's bytes come back as a Uint8Array; an extension's own package calls it so. */
+export declare function invoke<T = unknown, M = unknown>(name: string, options?: Record<string, unknown>, call?: InvokeOptions<M>): Promise<T>;
+
+/** The URL of a path an extension's route serves, as "/clips/intro.mp4" or "/thumb/42?size=256", for the page's <img>, <video> or fetch(): crossbind://app/ext/<extension><path>, and https://appassets.androidplatform.net/ext/<extension><path> on Android. The path is as a URL holds it, escaped where it must be, without a part "." or ".."; the route gets it decoded. */
+export declare function routeUrl(extension: string, path: string): string;