@timmo001/groundwork-mobile 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timmo001/groundwork-mobile",
-  "version": "0.13.0",
+  "version": "0.14.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.14.0",
+    "@timmo001/groundwork-tokens": "0.14.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,12 @@ 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,
 } as const;
 
 /** The shell's messages, each with the schema its data is read with. */

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,6 +149,25 @@ 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>;
 }
 
 interface Waiting {
@@ -171,13 +193,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 +267,9 @@ const connectFloor = (
     scanQr: async () => {
       throw new Error("The QR scanner needs the Android shell");
     },
+    setShortcuts: async () => 0,
+    pinShortcut: async () => false,
+    disableShortcuts: async () => {},
   };
 };
 
@@ -395,5 +425,18 @@ 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);
+    },
   };
 };