@timmo001/groundwork-mobile 0.13.0 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timmo001/groundwork-mobile",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "The page side of Groundwork's Android shell: the app config, the typed bridge to the shell, and a fallback to the PWA outside it",
   "license": "Apache-2.0",
   "type": "module",
@@ -33,8 +33,8 @@
     "format:check": "prettier --check ."
   },
   "dependencies": {
-    "@timmo001/groundwork-pwa": "0.13.0",
-    "@timmo001/groundwork-tokens": "0.13.0",
+    "@timmo001/groundwork-pwa": "0.15.0",
+    "@timmo001/groundwork-tokens": "0.15.0",
     "effect": "4.1.2"
   },
   "devDependencies": {

package/src/bridge.ts

@@ -26,13 +26,43 @@ export const Notice = Schema.Struct({
 
 export interface Notice extends Schema.Schema.Type<typeof Notice> {}
 
-/** A share from another app, the same shape the PWA's share target gives. */
+/**
+ * A share from another app, the same shape the PWA's share target gives,
+ * plus the id of the sharing shortcut it was sent to, in the shell.
+ */
 export const ShellShare = Schema.Struct({
   title: Schema.optionalKey(Schema.String),
   text: Schema.optionalKey(Schema.String),
   url: Schema.optionalKey(Schema.String),
+  shortcutId: Schema.optionalKey(Schema.String),
+});
+
+export interface ShellShare extends Schema.Schema.Type<typeof ShellShare> {}
+
+/**
+ * A launcher shortcut that opens `url` as a deep link: on a long press of
+ * the app's icon, pinned to the home screen, and with `share` in the share
+ * sheet's direct row too.
+ */
+export const Shortcut = Schema.Struct({
+  /** Stays the same across updates, so a pinned one keeps working. */
+  id: Schema.String,
+  label: Schema.String,
+  /** Shown where there's room, such as in the long-press menu. */
+  longLabel: Schema.optionalKey(Schema.String),
+  /** An allowed origin's page, or the app's own scheme. */
+  url: Schema.String,
+  /** An SVG path on a 24 unit grid, such as a Material Design Icon. */
+  icon: Schema.optionalKey(Schema.String),
+  /**
+   * A sharing shortcut, whose shares carry its id as `shortcutId`. It shows
+   * on a long press as well, so list it after the ones meant for that.
+   */
+  share: Schema.optionalKey(Schema.Boolean),
 });
 
+export interface Shortcut extends Schema.Schema.Type<typeof Shortcut> {}
+
 export const DeepLink = Schema.Struct({ url: Schema.String });
 
 export interface DeepLink extends Schema.Schema.Type<typeof DeepLink> {}
@@ -145,6 +175,14 @@ export const mobileRequests = {
   discoverServices: Schema.Array(DiscoveredService),
   /** Scans a QR code with the camera: its text, or `null` when cancelled. */
   scanQr: Schema.NullOr(Schema.String),
+  /** Replaces the dynamic shortcuts: how many the launcher took. */
+  setShortcuts: Schema.Number,
+  /** Asks the launcher to pin a shortcut: false where it can't. */
+  pinShortcut: Schema.Boolean,
+  /** Removes shortcuts, greying out pinned ones. */
+  disableShortcuts: Schema.Boolean,
+  /** Saves a file the page made to Downloads, from `{ name, type, data }` in base64. */
+  saveFile: Schema.Boolean,
 } as const;
 
 /** The shell's messages, each with the schema its data is read with. */

package/src/config.ts

@@ -12,6 +12,8 @@ export interface MobileLabels {
   readonly ongoing?: string;
   /** Defaults to `Download finished`. */
   readonly downloadFinished?: string;
+  /** Shown once a file the page made is saved. Defaults to `Saved to Downloads`. */
+  readonly fileSaved?: string;
 }
 
 export type ResolvedMobileLabels = Required<MobileLabels>;
@@ -104,6 +106,7 @@ export const resolveConfig = (
     notifications: "Notifications",
     ongoing: "Ongoing",
     downloadFinished: "Download finished",
+    fileSaved: "Saved to Downloads",
     ...config.labels,
   },
 });

package/src/view.ts

@@ -23,7 +23,6 @@ import {
   unsubscribePush,
   type Pwa,
   type PwaConfig,
-  type Share,
 } from "@timmo001/groundwork-pwa/view";
 import { Option, Schema } from "effect";
 
@@ -35,6 +34,7 @@ import {
   mobileRequests,
   Notice,
   ShellShare,
+  Shortcut,
   type BridgeMessage,
   type DiscoveredService,
   type DiscoveryMode,
@@ -77,8 +77,11 @@ export interface MobilePushOptions {
 export interface ConnectMobileOptions {
   /** The PWA config, for the floor's service worker, install and share target. */
   readonly pwa?: PwaConfig;
-  /** Called with each share, from the shell or the share target. */
-  readonly onShare?: (share: Share) => void;
+  /**
+   * Called with each share, from the shell or the share target, with the
+   * sharing shortcut's id when it was sent to one.
+   */
+  readonly onShare?: (share: ShellShare) => void;
   /** Called with each deep link the shell opens the app with. */
   readonly onDeepLink?: (url: string) => void;
   /**
@@ -146,8 +149,72 @@ export interface Mobile {
   readonly scanQr: (options?: {
     readonly hint?: string;
   }) => Promise<string | undefined>;
+  /**
+   * Replaces the dynamic shortcuts with these, in order, and answers how
+   * many the launcher took. Answers 0 outside the shell, where the PWA
+   * manifest's `shortcuts` give the long-press menu.
+   */
+  readonly setShortcuts: (shortcuts: readonly Shortcut[]) => Promise<number>;
+  /**
+   * Asks the launcher to pin a shortcut to the home screen. False where it
+   * can't, and outside the shell.
+   */
+  readonly pinShortcut: (shortcut: Shortcut) => Promise<boolean>;
+  /**
+   * Removes the shortcuts with these ids. Pinned ones stay, greyed out,
+   * showing `message` when tapped. Does nothing outside the shell.
+   */
+  readonly disableShortcuts: (
+    ids: readonly string[],
+    message?: string,
+  ) => Promise<void>;
+  /**
+   * Saves a file the page made, such as an export: to the phone's Downloads
+   * in the shell, through the browser's download outside it.
+   */
+  readonly saveFile: (file: SavedFile) => Promise<void>;
 }
 
+/** A file for `saveFile`: its name, its type and what's in it. */
+export interface SavedFile {
+  readonly name: string;
+  readonly type: string;
+  readonly contents: string | Blob;
+}
+
+const blobOf = ({ type, contents }: SavedFile) =>
+  contents instanceof Blob ? contents : new Blob([contents], { type });
+
+/** Saves a file through the browser's download. */
+const downloadFile = (file: SavedFile) => {
+  const url = URL.createObjectURL(blobOf(file));
+  const link = document.createElement("a");
+
+  link.href = url;
+  link.download = file.name;
+  link.click();
+  URL.revokeObjectURL(url);
+};
+
+const decodeText = Schema.decodeUnknownOption(Schema.String);
+
+/** A blob's bytes in base64, for the bridge's JSON. */
+const base64Of = (blob: Blob) =>
+  new Promise<string>((resolve, reject) => {
+    const reader = new FileReader();
+
+    // readAsDataURL gives data:<type>;base64,<data>
+    reader.addEventListener("load", () => {
+      const url = Option.getOrElse(decodeText(reader.result), () => "");
+
+      resolve(url.split(",")[1] ?? "");
+    });
+    reader.addEventListener("error", () =>
+      reject(reader.error ?? new Error("Couldn't read the file")),
+    );
+    reader.readAsDataURL(blob);
+  });
+
 interface Waiting {
   readonly resolve: (value: Schema.Json) => void;
   readonly reject: (error: Error) => void;
@@ -171,13 +238,18 @@ const read = <S extends Schema.ConstraintDecoder<unknown>>(
 
 const noticeJson = Schema.encodeSync(Schema.toCodecJson(Notice));
 
+const shortcutJson = Schema.encodeSync(Schema.toCodecJson(Shortcut));
+
+/** The `disableShortcuts` request's params. */
+type DisableParams = { ids: string[]; message?: string };
+
 const pushParams = ({ service, client, headers = {} }: MobilePushOptions) => ({
   service,
   client: { id: client.id, name: client.name, platform: client.platform },
   headers: { ...headers },
 });
 
-const dispatchShare = (share: Share) =>
+const dispatchShare = (share: ShellShare) =>
   window.dispatchEvent(new CustomEvent("gw-share", { detail: share }));
 
 const dispatchDeepLink = (link: DeepLink) =>
@@ -240,6 +312,10 @@ const connectFloor = (
     scanQr: async () => {
       throw new Error("The QR scanner needs the Android shell");
     },
+    setShortcuts: async () => 0,
+    pinShortcut: async () => false,
+    disableShortcuts: async () => {},
+    saveFile: async (file) => downloadFile(file),
   };
 };
 
@@ -395,5 +471,27 @@ export const connectMobile = async (
 
       return (await call("scanQr", mobileRequests.scanQr, params)) ?? undefined;
     },
+    setShortcuts: (shortcuts) =>
+      call("setShortcuts", mobileRequests.setShortcuts, {
+        shortcuts: shortcuts.map((shortcut) => shortcutJson(shortcut)),
+      }),
+    pinShortcut: (shortcut) =>
+      call("pinShortcut", mobileRequests.pinShortcut, shortcutJson(shortcut)),
+    disableShortcuts: async (ids, message) => {
+      const params: DisableParams = { ids: [...ids] };
+
+      if (message !== undefined) params["message"] = message;
+
+      await call("disableShortcuts", mobileRequests.disableShortcuts, params);
+    },
+    saveFile: async (file) => {
+      const blob = blobOf(file);
+
+      await call("saveFile", mobileRequests.saveFile, {
+        name: file.name,
+        type: blob.type || file.type,
+        data: await base64Of(blob),
+      });
+    },
   };
 };