@saasquatch/component-environment 1.0.0-2 → 1.0.0-5

package/README.md

@@ -1 +1,46 @@
 Provides the environment for running SaaSquatch web components.
+
+SaaSquatch web components can run in a number of different environments, including:
+
+- in a widget via `squatch-js`
+- in a microsite (portal)
+- in a mobile SDK (i.e. `squatch-android`)
+- in the admin portal
+
+In each environment, a different set of context information about the tenant, user and program are provided, and the goal of this package is to normalize the differences in environments to provide a common API.
+
+The environment is provided in a set of contexts through `dom-context`, which provides vanilla global context providers. They can be accessed through a raw `ContextListener` or via `useDomContext` in `dom-context-hooks`.
+
+## General environment
+
+### `getEnvironment()`
+
+Get the environment type. The current possible values are: `SquatchJS2`, `SquatchAndroid`, `SquatchPortal`, `SquatchAdmin` or `None`.
+
+### `isDemo()`
+
+Returns whether components should run in demo/preview mode.
+
+### `getTenantAlias()`
+
+Get the current tenant alias.
+
+### `getAppDomain()`
+
+Get the SaaSquatch app domain.
+
+### `getEngagementMedium()`
+
+Get the current engagement medium. This is particularly important in widgets rendered by `squatch-js` for informing metadata about share link clicks.
+
+## User identity
+
+The user identity context name is exported in a constant `USER_CONTEXT_NAME`. The current value can be retrieved with `getUserIdentity()` and set with `setUserIdentity(identity)`.
+
+## Locale
+
+The locale context name is exported in a constnat `LOCALE_CONTEXT_NAME`. The current value can be retrieved with `getLocale()` and set with `setLocal(locale)`.
+
+## Program ID
+
+The program ID context name is exported in a constant `PROGRAM_CONTEXT_NAME`. The current value can be retrieved with `getProgramId()` and set with `setProgramId(programId)`.

package/dist/index.d.ts

@@ -162,6 +162,72 @@ declare function getTenantAlias(): string;
 declare function getAppDomain(): string;
 declare function getEngagementMedium(): EngagementMedium;
 
+interface PartialPath {
+    pathname: string;
+    search?: string;
+    hash?: string;
+}
+interface HistoryEntry extends PartialPath {
+    state?: object;
+}
+declare type To = string | PartialPath;
+interface ListenableHistory {
+    listen(fn: () => void): () => void;
+    push(to: To, state?: object): void;
+    replace(to: To, state?: object): void;
+    back(): void;
+    forward(): void;
+    go(delta?: number): void;
+    location: HistoryEntry;
+}
+declare global {
+    interface Window {
+        squatchHistory: ListenableHistory;
+    }
+}
+declare class BrowserHistory implements ListenableHistory {
+    private listeners;
+    constructor();
+    listen(fn: () => void): () => void;
+    private notify;
+    get location(): {
+        pathname: string;
+        search: string;
+        hash: string;
+        state: any;
+    };
+    back(): void;
+    forward(): void;
+    go(delta: number): void;
+    push(to: To, state?: object): void;
+    replace(to: To, state?: object): void;
+}
+declare class MemoryHistory implements ListenableHistory {
+    private history;
+    private index;
+    private listeners;
+    listen(fn: () => void): () => void;
+    private current;
+    get state(): object | undefined;
+    notify(): void;
+    get location(): HistoryEntry;
+    back(): void;
+    forward(): void;
+    go(delta: number): void;
+    push(to: To, state?: object): void;
+    replace(to: To, state?: object): void;
+}
+declare class LazyHistory implements ListenableHistory {
+    get location(): HistoryEntry;
+    listen(fn: () => void): () => void;
+    back(): void;
+    forward(): void;
+    go(delta: number): void;
+    push(to: To, state?: object): void;
+    replace(to: To, state?: object): void;
+}
+declare const _default: LazyHistory;
+
 /**
  * Lazily start the user context provider. If it already exists, the existing provider is
  * returned. This function is safe to call multiple times.
@@ -223,4 +289,4 @@ declare function setProgramId(programId: string | undefined): void;
  */
 declare function getProgramId(): string | undefined;
 
-export { DEFAULT_MEDIUM, DecodedSquatchJWT, DecodedWidgetAPIJWT, EngagementMedium, Environment, EnvironmentSDK, LOCALE_CONTEXT_NAME, LocaleContextName, PROGRAM_CONTEXT_NAME, PortalEnv, ProgramContextName, SquatchAdmin, SquatchAndroid, SquatchJS2, USER_CONTEXT_NAME, UserContextName, UserId, UserIdentity, WidgetIdent, getAppDomain, getEngagementMedium, getEnvironment, getEnvironmentSDK, getLocale, getProgramId, getTenantAlias, getUserIdentity, isDemo, lazilyStartLocaleContext, lazilyStartProgramContext, lazilyStartUserContext, setLocale, setProgramId, setUserIdentity, userIdentityFromJwt };
+export { BrowserHistory, DEFAULT_MEDIUM, DecodedSquatchJWT, DecodedWidgetAPIJWT, EngagementMedium, Environment, EnvironmentSDK, HistoryEntry, LOCALE_CONTEXT_NAME, LazyHistory, LocaleContextName, MemoryHistory, PROGRAM_CONTEXT_NAME, PortalEnv, ProgramContextName, SquatchAdmin, SquatchAndroid, SquatchJS2, USER_CONTEXT_NAME, UserContextName, UserId, UserIdentity, WidgetIdent, getAppDomain, getEngagementMedium, getEnvironment, getEnvironmentSDK, getLocale, getProgramId, getTenantAlias, getUserIdentity, _default as history, isDemo, lazilyStartLocaleContext, lazilyStartProgramContext, lazilyStartUserContext, setLocale, setProgramId, setUserIdentity, userIdentityFromJwt };

package/dist/index.js

@@ -1,7 +1,9 @@
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __getProtoOf = Object.getPrototypeOf;
@@ -19,6 +21,7 @@ var __spreadValues = (a, b) => {
     }
   return a;
 };
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -37,8 +40,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  BrowserHistory: () => BrowserHistory,
   DEFAULT_MEDIUM: () => DEFAULT_MEDIUM,
   LOCALE_CONTEXT_NAME: () => LOCALE_CONTEXT_NAME,
+  LazyHistory: () => LazyHistory,
+  MemoryHistory: () => MemoryHistory,
   PROGRAM_CONTEXT_NAME: () => PROGRAM_CONTEXT_NAME,
   USER_CONTEXT_NAME: () => USER_CONTEXT_NAME,
   getAppDomain: () => getAppDomain,
@@ -49,6 +55,7 @@ __export(src_exports, {
   getProgramId: () => getProgramId,
   getTenantAlias: () => getTenantAlias,
   getUserIdentity: () => getUserIdentity,
+  history: () => history_default,
   isDemo: () => isDemo,
   lazilyStartLocaleContext: () => lazilyStartLocaleContext,
   lazilyStartProgramContext: () => lazilyStartProgramContext,
@@ -148,6 +155,199 @@ function getEngagementMedium() {
   }
 }
 
+// src/debug.ts
+var debugEnabled = (() => {
+  var _a;
+  try {
+    return (_a = window == null ? void 0 : window.localStorage) == null ? void 0 : _a.getItem("debug");
+  } catch (e) {
+    return false;
+  }
+})();
+function debug(ns, ...args) {
+  if (debugEnabled) {
+    console.debug(`sq:environment:${ns}`, ...args);
+  }
+}
+
+// src/history.ts
+var debug2 = (...args) => debug("history", ...args);
+function normalizeTo(to) {
+  if (typeof to === "string")
+    return to;
+  const url = new URL(to.pathname, window.origin);
+  if (to.search)
+    url.search = to.search;
+  if (to.hash)
+    url.hash = to.hash;
+  return url;
+}
+var BrowserHistory = class {
+  constructor() {
+    this.listeners = /* @__PURE__ */ new Set();
+    window.addEventListener("popstate", this.notify.bind(this));
+    window.addEventListener("pushState", this.notify.bind(this));
+    window.addEventListener("replaceState", this.notify.bind(this));
+  }
+  listen(fn) {
+    this.listeners.add(fn);
+    return () => {
+      this.listeners.delete(fn);
+    };
+  }
+  notify() {
+    debug2("notifying listeners of route change", this.location);
+    if (this.listeners) {
+      this.listeners.forEach((listener) => listener());
+    }
+  }
+  get location() {
+    return {
+      pathname: window.location.pathname,
+      search: window.location.search,
+      hash: window.location.hash,
+      state: window.history.state
+    };
+  }
+  back() {
+    this.go(-1);
+  }
+  forward() {
+    this.go(1);
+  }
+  go(delta) {
+    window.history.go(delta);
+  }
+  push(to, state) {
+    const url = normalizeTo(to);
+    window.history.pushState(state, "", url);
+  }
+  replace(to, state) {
+    const url = normalizeTo(to);
+    window.history.replaceState(state, "", url);
+  }
+};
+var MemoryHistory = class {
+  constructor() {
+    this.history = [{ pathname: "/", search: "", hash: "" }];
+    this.index = 0;
+    this.listeners = /* @__PURE__ */ new Set();
+  }
+  listen(fn) {
+    this.listeners.add(fn);
+    return () => {
+      this.listeners.delete(fn);
+    };
+  }
+  current() {
+    return this.history[this.index];
+  }
+  get state() {
+    return this.current().state;
+  }
+  notify() {
+    debug2("notifying listeners of route change", this.location);
+    this.listeners.forEach((listener) => listener());
+  }
+  get location() {
+    return this.history[this.index];
+  }
+  back() {
+    this.go(-1);
+  }
+  forward() {
+    this.go(1);
+  }
+  go(delta) {
+    this.index += delta;
+    if (this.index < 0)
+      this.index = 0;
+    if (this.index >= this.history.length)
+      this.index = this.history.length - 1;
+    this.notify();
+  }
+  push(to, state) {
+    let entry;
+    if (typeof to === "string") {
+      entry = {
+        pathname: to,
+        search: this.history[this.index].search,
+        hash: this.history[this.index].hash,
+        state
+      };
+    } else {
+      entry = __spreadProps(__spreadValues({}, to), {
+        state
+      });
+    }
+    this.index++;
+    this.history.splice(this.index, this.history.length, entry);
+    this.notify();
+  }
+  replace(to, state) {
+    if (typeof to === "string") {
+      this.history[this.index] = {
+        pathname: to,
+        search: this.history[this.index].search,
+        hash: this.history[this.index].hash,
+        state
+      };
+    } else {
+      this.history[this.index] = __spreadProps(__spreadValues({}, to), {
+        state
+      });
+    }
+    this.notify();
+  }
+};
+function createHistory() {
+  if (getEnvironment() === "SquatchPortal") {
+    let wrapHistoryFunction2 = function(functionName) {
+      const orig = window.history[functionName];
+      return function(...args) {
+        const returnValue = orig.apply(window.history, args);
+        const event = new Event(functionName);
+        window.dispatchEvent(event);
+        return returnValue;
+      };
+    };
+    var wrapHistoryFunction = wrapHistoryFunction2;
+    window.history.pushState = wrapHistoryFunction2("pushState");
+    window.history.replaceState = wrapHistoryFunction2("replaceState");
+    return new BrowserHistory();
+  } else {
+    return new MemoryHistory();
+  }
+}
+function lazyHistory() {
+  window.squatchHistory = window.squatchHistory || createHistory();
+  return window.squatchHistory;
+}
+var LazyHistory = class {
+  get location() {
+    return lazyHistory().location;
+  }
+  listen(fn) {
+    return lazyHistory().listen(fn);
+  }
+  back() {
+    lazyHistory().back();
+  }
+  forward() {
+    lazyHistory().forward();
+  }
+  go(delta) {
+    lazyHistory().go(delta);
+  }
+  push(to, state) {
+    lazyHistory().push(to, state);
+  }
+  replace(to, state) {
+    lazyHistory().replace(to, state);
+  }
+};
+var history_default = new LazyHistory();
+
 // src/contexts/UserIdentityContext.ts
 var import_jwt_decode = __toESM(require("jwt-decode"));
 var import_dom_context3 = require("dom-context");
@@ -158,22 +358,12 @@ var import_dom_context2 = require("dom-context");
 
 // src/contexts/LocaleContext.ts
 var import_dom_context = require("dom-context");
-
-// src/debug.ts
-var debugEnabled = localStorage.getItem("debug");
-function debug(ns, ...args) {
-  if (debugEnabled) {
-    console.debug(`sq:environment:${ns}`, ...args);
-  }
-}
-
-// src/contexts/LocaleContext.ts
-var debug2 = (...args) => debug(LOCALE_CONTEXT_NAME, ...args);
+var debug3 = (...args) => debug(LOCALE_CONTEXT_NAME, ...args);
 function lazilyStartLocaleContext() {
   var _a;
   let globalProvider = window.squatchLocale;
   if (!globalProvider) {
-    debug2("Creating locale context provider");
+    debug3("Creating locale context provider");
     globalProvider = new import_dom_context.ContextProvider({
       element: document.documentElement,
       initialState: ((_a = window.widgetIdent) == null ? void 0 : _a.locale) || navigator.language.replace("-", "_"),
@@ -186,7 +376,7 @@ function lazilyStartLocaleContext() {
 function setLocale(locale) {
   const globalProvider = lazilyStartLocaleContext();
   if (globalProvider.context !== locale) {
-    debug2(`Setting locale context value [${locale}]`);
+    debug3(`Setting locale context value [${locale}]`);
     globalProvider.context = locale;
   }
 }
@@ -196,7 +386,7 @@ function getLocale() {
 }
 
 // src/fetchLocale.ts
-var debug3 = (...args) => debug(LOCALE_CONTEXT_NAME, ...args);
+var debug4 = (...args) => debug(LOCALE_CONTEXT_NAME, ...args);
 var GET_LOCALE = `
   query {
     viewer {
@@ -208,7 +398,7 @@ var GET_LOCALE = `
 `;
 async function fetchLocale() {
   var _a;
-  debug3("Fetching locale from GraphQL for current user");
+  debug4("Fetching locale from GraphQL for current user");
   try {
     const result = await fetch(`${getAppDomain()}/api/v1/${getTenantAlias()}/graphql`, {
       method: "POST",
@@ -229,13 +419,13 @@ async function fetchLocale() {
     }
     return json.data.viewer.locale || void 0;
   } catch (e) {
-    debug3(`Failed to fetch locale for current user`, e.message);
+    debug4(`Failed to fetch locale for current user`, e.message);
     return void 0;
   }
 }
 
 // src/listeners.ts
-var debug4 = (...args) => debug(LOCALE_CONTEXT_NAME, ...args);
+var debug5 = (...args) => debug(LOCALE_CONTEXT_NAME, ...args);
 var userContextListenerDiv = (() => {
   const id = "__environment_context_listener";
   let div = document.getElementById(id);
@@ -255,31 +445,30 @@ var userContextListenerForLocale = new import_dom_context2.ContextListener({
     const defaultLocale = ((_a = window.widgetIdent) == null ? void 0 : _a.locale) || navigator.language.replace("-", "_");
     let newLocale;
     if (next) {
-      debug4("User context changed, refetching locale");
+      debug5("User context changed, refetching locale");
       const locale = await fetchLocale();
       if (localeProvider.context !== locale) {
-        debug4(`New value fetched from GraphQL [${locale}]`);
+        debug5(`New value fetched from GraphQL [${locale}]`);
         newLocale = locale || defaultLocale;
       }
     } else {
       newLocale = defaultLocale;
     }
-    debug4(`Setting locale context to [${newLocale}]`);
+    debug5(`Setting locale context to [${newLocale}]`);
     localeProvider.context = newLocale;
-  },
-  onStatus: (status) => debug4("STATUS", status)
+  }
 });
 function startUserContextListenerForLocale() {
-  debug4("Starting user context listener for locale updates");
+  debug5("Starting user context listener for locale updates");
   userContextListenerForLocale.start();
 }
 
 // src/contexts/UserIdentityContext.ts
-var debug5 = (...args) => debug(USER_CONTEXT_NAME, ...args);
+var debug6 = (...args) => debug(USER_CONTEXT_NAME, ...args);
 function lazilyStartUserContext() {
   let globalProvider = window.squatchUserIdentity;
   if (!globalProvider) {
-    debug5("Creating user context provider");
+    debug6("Creating user context provider");
     globalProvider = new import_dom_context3.ContextProvider({
       element: document.documentElement,
       initialState: _getInitialValue(),
@@ -365,7 +554,7 @@ function _getInitialValue() {
 function setUserIdentity(identity) {
   const globalProvider = lazilyStartUserContext();
   if (!(0, import_equality.equal)(globalProvider.context, identity)) {
-    debug5(`Setting user context value [${JSON.stringify(identity)}]`);
+    debug6(`Setting user context value [${JSON.stringify(identity)}]`);
     globalProvider.context = identity;
   }
   if (identity && getEnvironmentSDK().type === "SquatchPortal") {
@@ -381,12 +570,12 @@ function getUserIdentity() {
 
 // src/contexts/ProgramContext.ts
 var import_dom_context4 = require("dom-context");
-var debug6 = (...args) => debug(PROGRAM_CONTEXT_NAME, ...args);
+var debug7 = (...args) => debug(PROGRAM_CONTEXT_NAME, ...args);
 function lazilyStartProgramContext() {
   var _a;
   let globalProvider = window.squatchProgramId;
   if (!globalProvider) {
-    debug6("Creating program context provider");
+    debug7("Creating program context provider");
     globalProvider = new import_dom_context4.ContextProvider({
       element: document.documentElement,
       initialState: ((_a = window.widgetIdent) == null ? void 0 : _a.programId) || void 0,
@@ -399,7 +588,7 @@ function lazilyStartProgramContext() {
 function setProgramId(programId) {
   const globalProvider = lazilyStartProgramContext();
   if (globalProvider.context !== programId) {
-    debug6(`Setting program context value [${programId}]`);
+    debug7(`Setting program context value [${programId}]`);
     globalProvider.context = programId;
   }
 }
@@ -409,8 +598,11 @@ function getProgramId() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BrowserHistory,
   DEFAULT_MEDIUM,
   LOCALE_CONTEXT_NAME,
+  LazyHistory,
+  MemoryHistory,
   PROGRAM_CONTEXT_NAME,
   USER_CONTEXT_NAME,
   getAppDomain,
@@ -421,6 +613,7 @@ function getProgramId() {
   getProgramId,
   getTenantAlias,
   getUserIdentity,
+  history,
   isDemo,
   lazilyStartLocaleContext,
   lazilyStartProgramContext,