@inboxsdk/core 2.1.40 → 2.1.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inboxsdk/core",
-  "version": "2.1.40",
+  "version": "2.1.42",
   "description": "Library for building browser extensions for Gmail",
   "main": "inboxsdk.js",
   "author": "Streak",

package/src/inboxsdk.d.ts

@@ -31,12 +31,16 @@ import type ComposeView from './platform-implementation-js/views/compose-view';
 import type Search from './platform-implementation-js/namespaces/search';
 import type {
   default as Toolbars,
+  LegacyToolbarButtonOnClickEvent,
   LegacyToolbarButtonDescriptor,
 } from './platform-implementation-js/namespaces/toolbars';
 import type CollapsibleSectionView from './platform-implementation-js/views/collapsible-section-view';
 import type ListRouteView from './platform-implementation-js/views/route-view/list-route-view';
 import type SectionView from './platform-implementation-js/views/section-view';
-import type { RouteParams } from './platform-implementation-js/namespaces/router';
+import Router, {
+  type RouteParams,
+} from './platform-implementation-js/namespaces/router';
+import CustomRouteView from './platform-implementation-js/views/route-view/custom-route-view';
 
 export type { User };
 
@@ -128,71 +132,7 @@ export interface NavMenu {
   ): NavItemView;
 }
 
-export interface Router {
-  createLink(routeID: string, params?: any): string;
-  getCurrentRouteView(): RouteView;
-  goto(routeID: string, params?: any): Promise<void>;
-  handleAllRoutes(handler: (routeView: RouteView) => void): () => void;
-  handleCustomRoute(
-    routeID: string,
-    handler: (customRouteView: CustomRouteView) => void,
-  ): () => void;
-  handleCustomListRoute(
-    routeID: string,
-    handler: (offset: number, max: number) => void,
-  ): void;
-  handleListRoute(
-    routeID: string,
-    handler: (listRouteView: ListRouteView) => void,
-  ): () => void;
-  NativeRouteIDs: Record<NativeRouteIdTypes, string>;
-  NativeListRouteIDs: Record<
-    | 'ALL_MAIL'
-    | 'ANY_LIST'
-    | 'DRAFTS'
-    | 'IMPORTANT'
-    | 'INBOX'
-    | 'LABEL'
-    | 'SEARCH'
-    | 'SEARCH'
-    | 'SENT'
-    | 'SPAM'
-    | 'STARRED'
-    | 'TRASH',
-    string
-  >;
-  RouteTypes: Record<RouteTypes, string>;
-}
-
-type NativeRouteIdTypes =
-  | 'INBOX'
-  | 'ALL_MAIL'
-  | 'SENT'
-  | 'STARRED'
-  | 'DRAFTS'
-  | 'SNOOZED'
-  | 'DONE'
-  | 'REMINDERS'
-  | 'LABEL'
-  | 'TRASH'
-  | 'SPAM'
-  | 'IMPORTANT'
-  | 'SEARCH'
-  | 'THREAD'
-  | 'CHATS'
-  | 'CHAT'
-  | 'CONTACTS'
-  | 'CONTACT'
-  | 'SETTINGS'
-  | 'ANY_LIST';
-
-type RouteTypes =
-  | 'CHAT'
-  | 'CUSTOM'
-  | 'LIST'
-  | 'SETTINGS'
-  | 'THREAD'
-  | 'UNKNOWN';
+export { Router };
 
 export interface Widgets {
   /** check whether mole view has light title bar as part of gmail new view / original view  */
@@ -203,7 +143,11 @@ export interface Widgets {
   showTopMessageBarView(opts: { el: Element }): TopMessageBarView;
 }
 
-export { Toolbars, LegacyToolbarButtonDescriptor };
+export {
+  Toolbars,
+  LegacyToolbarButtonDescriptor,
+  LegacyToolbarButtonOnClickEvent,
+};
 export {
   ToolbarButtonDescriptor,
   ToolbarButtonOnClickEvent,
@@ -431,9 +375,7 @@ export interface SectionDescriptor {
 
 export { ListRouteView };
 
-export interface CustomRouteView extends RouteView {
-  getElement(): HTMLElement;
-}
+export { CustomRouteView };
 
 export interface CustomListDescriptor {
   hasMore?: boolean;

package/src/platform-implementation-js/lib/handler-registry.d.ts

@@ -1,4 +1,4 @@
-export type Handler<T> = (target: T) => void;
+export type Handler<T> = (target: T) => void | Promise<void>;
 export default class HandlerRegistry<T> {
     private _targets;
     private _pendingHandlers;

package/src/platform-implementation-js/lib/handler-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler-registry.d.ts","sourceRoot":"","sources":["../../../../../src/platform-implementation-js/lib/handler-registry.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,CAAC;AAE7C,MAAM,CAAC,OAAO,OAAO,eAAe,CAAC,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,gBAAgB,CAAyB;IACjD,OAAO,CAAC,SAAS,CAAyB;IAE1C,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAwBhD,SAAS,CAAC,MAAM,EAAE,CAAC;IAiBnB,YAAY,CAAC,MAAM,EAAE,CAAC;IAItB,YAAY;IAKZ,OAAO,CAAC,uBAAuB;IAO/B,OAAO,CAAC,uBAAuB;CAMhC"}
+{"version":3,"file":"handler-registry.d.ts","sourceRoot":"","sources":["../../../../../src/platform-implementation-js/lib/handler-registry.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE7D,MAAM,CAAC,OAAO,OAAO,eAAe,CAAC,CAAC;IACpC,OAAO,CAAC,QAAQ,CAAgB;IAChC,OAAO,CAAC,gBAAgB,CAAyB;IACjD,OAAO,CAAC,SAAS,CAAyB;IAE1C,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAwBhD,SAAS,CAAC,MAAM,EAAE,CAAC;IAiBnB,YAAY,CAAC,MAAM,EAAE,CAAC;IAItB,YAAY;IAKZ,OAAO,CAAC,uBAAuB;IAO/B,OAAO,CAAC,uBAAuB;CAMhC"}

package/src/platform-implementation-js/namespaces/router.d.ts

@@ -1,12 +1,17 @@
-import HandlerRegistry from '../lib/handler-registry';
 import RouteView from '../views/route-view/route-view';
 import ListRouteView from '../views/route-view/list-route-view';
 import CustomRouteView from '../views/route-view/custom-route-view';
 import type Membrane from '../lib/Membrane';
 import type { Driver } from '../driver-interfaces/driver';
 import type { Handler } from '../lib/handler-registry';
-export type RouteParams = Record<string, string | number>;
+export type RouteParams = Record<string, string | number | undefined | null>;
+/**
+ * This namespace contains functionality associated with creating your own content inside Gmail. It allows you to define "Routes" which define a full page of content and an associated URL space for which they are active. You can think of routes as different pages in your application. Gmail already have a few routes built in (Inbox, Sent, Drafts, etc). This namespace allows you to define your own as well as listen in on the built in routes being navigated to.
+
+This is typically used when you want to create content to fill the main content area of Gmail. Every route has a URL associated with it and can have optional parameters. However, you never construct these URL's manually. The SDK will take care of creating a URL that will work in Gmail for your Route. Since these URL's may change due to implementations of Gmail, you should always create new links when trying to set URL on elements or simply use the goto function which naviagtes to the created link automatically. Using the handleX family of methods, you can specify which routes your application can handle. You will be called back with and instance of a RouteView or similar when the user navigates to a route you've declared you can handle. For custom routes, you'll typically add your own content and for built in routes, you'll typically modify the existing content. Route ID's are path like strings with named parameters, for example: "myroute/:someParamMyRouteNeeds".
+ */
 declare class Router {
+    #private;
     NativeRouteIDs: Readonly<{
         INBOX: "inbox/:page";
         ALL_MAIL: "all/:page";
@@ -62,12 +67,56 @@ declare class Router {
         UNKNOWN: "UNKNOWN";
     }>;
     constructor(appId: string, driver: Driver, membrane: Membrane);
+    /**
+     * Get a URL that can be used to navigate to a view. You'll typically want to use this to set the href of an element or similar. Returns the encoded URL string.
+     *
+     * @param routeID A route specifying where the link should navigate the user to. This should either be a routeID registered with {@link Router#handleCustomRoute} or {@link Router#handleCustomListRoute}, or a value from {@link Router#NativeRouteIDs}.
+     * @param params an object containing the parameters that will be encoded in the link and decoded when the user subsequently visits the route. Handlers for the specified routeID will receive a copy of this object. This object must contain only simple key value pairs with no nested arrays/objects.
+     */
     createLink(routeID: string, params?: (RouteParams | null | undefined) | string): string;
+    /**
+     * Change the route to be the one with the given ID and have the given parameters.
+     * @param routeID A route specifying where the link should navigate the user to. This should either be a routeID registered with {@link Router#handleCustomRoute} or {@link Router#handleCustomListRoute} a value from {@link Router#NativeRouteIDs}, or a value previously returned by {@link Router#createLink}. If it's a value previously returned by {@link Router#createLink} then the params argument must be omitted.
+     * @param params an object containing the parameters that will be encoded in the link and decoded when the user subsequently visits the route. Handlers for the specified routeID will receive a copy of this object. This object must contain only simple key value pairs with no nested arrays/objects.
+     */
     goto(routeID: string, params?: (RouteParams | null | undefined) | string): Promise<void>;
-    handleCustomRoute(routeID: string, handler: HandlerRegistry<CustomRouteView>): () => void;
+    /**
+     * Registers a handler (callback) to be called when the user navigates to a custom route which matches the routeID you provide. Use this to create your own routes (pages) with your own custom content. Your callback will be passed an instance of a {@link CustomRouteView} whose contents you may modify.
+     * @param routeID which route this handler is registering for
+     * @param handler The callback to call when the route changes to a custom route matching the provided routeID
+     * @returns a function which removes the handler registration.
+     */
+    handleCustomRoute(routeID: string, handler: Handler<CustomRouteView>): () => void;
+    /**
+     * Registers a handler (callback) to be called when the user navigates to any route (both customs and built in routes). Because this can apply to any route, your callback will be given only a generic RouteView. This is typically used when you want to monitor for page changes but don't necessarily need to modify the page.
+     * @param handler The callback to call when the route changes
+     * @returns a function which removes the handler registration.
+     */
     handleAllRoutes(handler: Handler<any>): () => void;
+    /**
+     * Registers a handler (callback) to be called when the user navigates to a list route which matches the routeID you provide. Gmail have several built in routes which are "Lists". These include routes like Inbox, All Mail, Sent, Drafts, etc. You'll typically use this to modify Gmail's built in List routes.
+     * @param routeID which list route this handler is registering for.
+     * @param handler The callback to call when the route changes to a list route matching the routeId.
+     * @returns a function which removes the handler registration.
+     *
+     * @example
+     *
+     * ```javascript
+     * sdk.Router.handleListRoute(sdk.Router.NativeRouteIDs.INBOX, (listRouteView) => {
+     * ```
+  });
+     */
     handleListRoute(routeID: string, handler: Handler<ListRouteView>): () => void;
+    /**
+     * Used to create a custom view that shows a list of threads. When the user navigates to the given routeID, the handler function will be called. The handler function will be passed the starting offset (if the user sees 50 threads per page and is on page 2, then the offset will be 50), and a maximum number of threads to return. It must return a CustomListDescriptor, or a promise which resolves to one.
+     * @param routeID  Which route this handler is registering for.
+     * @param handler Passed a page offset and a maximum number of threads to return. Must return a CustomListDescriptor, or a promise which resolves to one.
+     * @returns a function which removes the handler registration.
+     */
     handleCustomListRoute(routeID: string, handler: (...args: Array<any>) => any): () => void;
+    /**
+     * @returns a RouteView of the current route view
+     */
     getCurrentRouteView(): RouteView;
 }
 export default Router;

package/src/platform-implementation-js/namespaces/router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../../../src/platform-implementation-js/namespaces/router.ts"],"names":[],"mappings":"AAGA,OAAO,eAAe,MAAM,yBAAyB,CAAC;AAEtD,OAAO,SAAS,MAAM,gCAAgC,CAAC;AACvD,OAAO,aAAa,MAAM,qCAAqC,CAAC;AAChE,OAAO,eAAe,MAAM,uCAAuC,CAAC;AAEpE,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAM5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;AAgB1D,cAAM,MAAM;IACV,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;OAAoB;IAClC,kBAAkB;;;;;;;;;;;;;;;OAAyB;IAC3C,UAAU;;;;;;;;;OAAe;gBAEb,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ;IAkC7D,UAAU,CACR,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,CAAC,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,GACjD,MAAM;IAIT,IAAI,CACF,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,CAAC,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,GACjD,OAAO,CAAC,IAAI,CAAC;IAmBhB,iBAAiB,CACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,eAAe,CAAC,eAAe,CAAC,GACxC,MAAM,IAAI;IAsBb,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,IAAI;IAMlD,eAAe,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAC9B,MAAM,IAAI;IAUb,qBAAqB,CACnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,GACpC,MAAM,IAAI;IAIb,mBAAmB,IAAI,SAAS;CAIjC;AAkFD,eAAe,MAAM,CAAC"}
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../../../../src/platform-implementation-js/namespaces/router.ts"],"names":[],"mappings":"AAEA,OAAO,SAAS,MAAM,gCAAgC,CAAC;AACvD,OAAO,aAAa,MAAM,qCAAqC,CAAC;AAChE,OAAO,eAAe,MAAM,uCAAuC,CAAC;AAEpE,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAC;AAM5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAGvD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC,CAAC;AAI7E;;;;GAIG;AACH,cAAM,MAAM;;IACV,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;OAAoB;IAClC,kBAAkB;;;;;;;;;;;;;;;OAAyB;IAC3C,UAAU;;;;;;;;;OAAe;gBAcb,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ;IA8B7D;;;;;OAKG;IACH,UAAU,CACR,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,CAAC,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,GACjD,MAAM;IAIT;;;;OAIG;IACH,IAAI,CACF,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,CAAC,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,MAAM,GACjD,OAAO,CAAC,IAAI,CAAC;IAmBhB;;;;;OAKG;IACH,iBAAiB,CACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,CAAC,eAAe,CAAC,GAChC,MAAM,IAAI;IAoBb;;;;OAIG;IACH,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,IAAI;IAIlD;;;;;;;;;;;;OAYG;IACH,eAAe,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,GAC9B,MAAM,IAAI;IAUb;;;;;OAKG;IACH,qBAAqB,CACnB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,KAAK,GAAG,GACpC,MAAM,IAAI;IAIb;;OAEG;IACH,mBAAmB,IAAI,SAAS;CA6EjC;AAED,eAAe,MAAM,CAAC"}