@moser-inc/moser-labs-custom-elements 2.5.7 → 3.0.0

package/README.md

@@ -5,7 +5,7 @@ This package contains a collection of custom elements that can be used in any we
 ## Installation
 
 ```bash
-npm i @moser-inc/moser-labs-custom-elements
+npm i @moser-inc/moser-labs-custom-elements @moser-inc/moser-labs-themes
 ```
 
 ## Usage
@@ -13,6 +13,7 @@ npm i @moser-inc/moser-labs-custom-elements
 For these custom elements to function properly, you must first authenticate the user with Keycloak before calling the provided `registerCustomElements` function, passing the Keycloak instance to it.
 
 ```ts
+import Labs from '@moser-inc/moser-labs-themes/labs';
 import Keycloak from 'keycloak-js';
 import { registerCustomElements } from '@moser-inc/moser-labs-custom-elements';
 
@@ -21,7 +22,10 @@ const keycloak = new Keycloak('/keycloak.json');
 keycloak.init({ onLoad: 'login-required' }).then((isAuthenticated) => {
   if (!isAuthenticated) return;
 
-  registerCustomElements({ keycloak });
+  registerCustomElements({
+    preset: Labs,
+    keycloak,
+  });
 });
 ```
 
@@ -30,7 +34,11 @@ keycloak.init({ onLoad: 'login-required' }).then((isAuthenticated) => {
 In order for the custom elements to use the correct instance for calling API endpoints and getting profile pictures, pass the `apiUri` option to `registerCustomElements`, using an environment variable for it to be dynamic between staging and production. It defaults to using `window.location.origin`.
 
 ```ts
-registerCustomElements({ keycloak, apiUri: import.meta.env.VITE_API_URI });
+registerCustomElements({
+  preset: Labs,
+  keycloak,
+  apiUri: import.meta.env.VITE_API_URI,
+});
 ```
 
 ## External

package/dist/external/index.d.ts

@@ -0,0 +1,511 @@
+import { Preset } from "@moser-inc/moser-labs-themes";
+import Keycloak from "keycloak-js";
+
+//#region ../../node_modules/analytics/lib/types.d.ts
+declare module "analytics" {
+  /**
+   * Core Analytic constants. These are exposed for third party plugins & listeners
+   * @property ANON_ID - Anonymous visitor Id localstorage key
+   * @property USER_ID - Visitor Id localstorage key
+   * @property USER_TRAITS - Visitor traits localstorage key
+   */
+  type constants = {
+    ANON_ID: ANON_ID;
+    USER_ID: USER_ID;
+    USER_TRAITS: USER_TRAITS;
+  };
+  /**
+   * Anonymous visitor Id localstorage key
+   */
+  type ANON_ID = string;
+  /**
+   * Visitor Id localstorage key
+   */
+  type USER_ID = string;
+  /**
+   * Visitor traits localstorage key
+   */
+  type USER_TRAITS = string;
+  /**
+   * Analytics library configuration
+   *
+   * After the library is initialized with config, the core API is exposed & ready for use in the application.
+   * @example
+   * import Analytics from 'analytics'
+   * import pluginABC from 'analytics-plugin-abc'
+   * import pluginXYZ from 'analytics-plugin-xyz'
+   *
+   * // initialize analytics
+   * const analytics = Analytics({
+   *   app: 'my-awesome-app',
+   *   plugins: [
+   *     pluginABC,
+   *     pluginXYZ
+   *   ]
+   * })
+   * @param config - analytics core config
+   * @param [config.app] - Name of site / app
+   * @param [config.version] - Version of your app
+   * @param [config.debug] - Should analytics run in debug mode
+   * @param [config.plugins] - Array of analytics plugins
+   * @returns Analytics Instance
+   */
+  function analytics(config: {
+    app?: string;
+    version?: string | number;
+    debug?: boolean;
+    plugins?: AnalyticsPlugin[];
+  }): AnalyticsInstance;
+  /**
+   * Async Management methods for plugins.
+   *
+   * This is also where [custom methods](https://bit.ly/329vFXy) are loaded into the instance.
+   * @example
+   * // Enable a plugin by namespace
+   * analytics.plugins.enable('keenio')
+   *
+   * // Disable a plugin by namespace
+   * analytics.plugins.disable('google-analytics')
+   * @property enable - Set storage value
+   * @property disable - Remove storage value
+   */
+  type Plugins = {
+    enable: EnablePlugin;
+    disable: DisablePlugin;
+  };
+  /**
+   * Enable analytics plugin
+   * @example
+   * analytics.plugins.enable('google-analytics').then(() => {
+   *   console.log('do stuff')
+   * })
+   *
+   * // Enable multiple plugins at once
+   * analytics.plugins.enable(['google-analytics', 'segment']).then(() => {
+   *   console.log('do stuff')
+   * })
+   * @param plugins - name of plugins(s) to disable
+   * @param [callback] - callback after enable runs
+   */
+  type EnablePlugin = (plugins: string | string[], callback?: (...params: any[]) => any) => Promise<any>;
+  /**
+   * Disable analytics plugin
+   * @example
+   * analytics.plugins.disable('google').then(() => {
+   *   console.log('do stuff')
+   * })
+   *
+   * analytics.plugins.disable(['google', 'segment']).then(() => {
+   *   console.log('do stuff')
+   * })
+   * @param plugins - name of integration(s) to disable
+   * @param [callback] - callback after disable runs
+   */
+  type DisablePlugin = (plugins: string | string[], callback?: (...params: any[]) => any) => Promise<any>;
+  /**
+   * Analytic instance returned from initialization
+   * @property identify - Identify a user
+   * @property track - Track an analytics event
+   * @property page - Trigger page view
+   * @property user - Get user data
+   * @property reset - Clear information about user & reset analytics
+   * @property ready - Fire callback on analytics ready event
+   * @property on - Fire callback on analytics lifecycle events.
+   * @property once - Fire callback on analytics lifecycle events once.
+   * @property getState - Get data about user, activity, or context.
+   * @property storage - storage methods
+   * @property plugins - plugin methods
+   */
+  export interface AnalyticsInstance {
+    identify: Identify;
+    track: Track;
+    page: Page;
+    user: User;
+    reset: Reset;
+    ready: Ready;
+    on: On;
+    once: Once;
+    getState: GetState;
+    storage: Storage;
+    plugins: Plugins;
+  }
+  /**
+   * Identify a user. This will trigger `identify` calls in any installed plugins and will set user data in localStorage
+   * @example
+   * // Basic user id identify
+   * analytics.identify('xyz-123')
+   *
+   * // Identify with additional traits
+   * analytics.identify('xyz-123', {
+   *   name: 'steve',
+   *   company: 'hello-clicky'
+   * })
+   *
+   * // Fire callback with 2nd or 3rd argument
+   * analytics.identify('xyz-123', () => {
+   *   console.log('do this after identify')
+   * })
+   *
+   * // Disable sending user data to specific analytic tools
+   * analytics.identify('xyz-123', {}, {
+   *   plugins: {
+   *     // disable sending this identify call to segment
+   *     segment: false
+   *   }
+   * })
+   *
+   * // Send user data to only to specific analytic tools
+   * analytics.identify('xyz-123', {}, {
+   *   plugins: {
+   *     // disable this specific identify in all plugins except customerio
+   *     all: false,
+   *     customerio: true
+   *   }
+   * })
+   * @param userId - Unique ID of user
+   * @param [traits] - Object of user traits
+   * @param [options] - Options to pass to identify call
+   * @param [callback] - Callback function after identify completes
+   */
+  type Identify = (userId: string, traits?: any, options?: any, callback?: (...params: any[]) => any) => Promise<any>;
+  /**
+   * Track an analytics event. This will trigger `track` calls in any installed plugins
+   * @example
+   * // Basic event tracking
+   * analytics.track('buttonClicked')
+   *
+   * // Event tracking with payload
+   * analytics.track('itemPurchased', {
+   *   price: 11,
+   *   sku: '1234'
+   * })
+   *
+   * // Fire callback with 2nd or 3rd argument
+   * analytics.track('newsletterSubscribed', () => {
+   *   console.log('do this after track')
+   * })
+   *
+   * // Disable sending this event to specific analytic tools
+   * analytics.track('cartAbandoned', {
+   *   items: ['xyz', 'abc']
+   * }, {
+   *   plugins: {
+   *     // disable track event for segment
+   *     segment: false
+   *   }
+   * })
+   *
+   * // Send event to only to specific analytic tools
+   * analytics.track('customerIoOnlyEventExample', {
+   *   price: 11,
+   *   sku: '1234'
+   * }, {
+   *   plugins: {
+   *     // disable this specific track call all plugins except customerio
+   *     all: false,
+   *     customerio: true
+   *   }
+   * })
+   * @param eventName - Event name
+   * @param [payload] - Event payload
+   * @param [options] - Event options
+   * @param [callback] - Callback to fire after tracking completes
+   */
+  type Track = (eventName: string, payload?: any, options?: any, callback?: (...params: any[]) => any) => Promise<any>;
+  /**
+   * Trigger page view. This will trigger `page` calls in any installed plugins
+   * @example
+   * // Basic page tracking
+   * analytics.page()
+   *
+   * // Page tracking with page data overrides
+   * analytics.page({
+   *   url: 'https://google.com'
+   * })
+   *
+   * // Fire callback with 1st, 2nd or 3rd argument
+   * analytics.page(() => {
+   *   console.log('do this after page')
+   * })
+   *
+   * // Disable sending this pageview to specific analytic tools
+   * analytics.page({}, {
+   *   plugins: {
+   *     // disable page tracking event for segment
+   *     segment: false
+   *   }
+   * })
+   *
+   * // Send pageview to only to specific analytic tools
+   * analytics.page({}, {
+   *   plugins: {
+   *     // disable this specific page in all plugins except customerio
+   *     all: false,
+   *     customerio: true
+   *   }
+   * })
+   * @param [data] - Page data overrides.
+   * @param [options] - Page tracking options
+   * @param [callback] - Callback to fire after page view call completes
+   */
+  type Page = (data?: PageData, options?: any, callback?: (...params: any[]) => any) => Promise<any>;
+  /**
+   * Get user data
+   * @example
+   * // Get all user data
+   * const userData = analytics.user()
+   *
+   * // Get user id
+   * const userId = analytics.user('userId')
+   *
+   * // Get user company name
+   * const companyName = analytics.user('traits.company.name')
+   * @param [key] - dot.prop.path of user data. Example: 'traits.company.name'
+   */
+  type User = (key?: string) => string & any;
+  /**
+   * Clear all information about the visitor & reset analytic state.
+   * @example
+   * // Reset current visitor
+   * analytics.reset()
+   * @param [callback] - Handler to run after reset
+   */
+  type Reset = (callback?: (...params: any[]) => any) => Promise<any>;
+  /**
+   * Fire callback on analytics ready event
+   * @example
+   * analytics.ready((payload) => {
+   *   console.log('all plugins have loaded or were skipped', payload);
+   * })
+   * @param callback - function to trigger when all providers have loaded
+   */
+  type Ready = (callback: (...params: any[]) => any) => DetachListeners;
+  /**
+   * Attach an event handler function for analytics lifecycle events.
+   * @example
+   * // Fire function when 'track' calls happen
+   * analytics.on('track', ({ payload }) => {
+   *   console.log('track call just happened. Do stuff')
+   * })
+   *
+   * // Remove listener before it is called
+   * const removeListener = analytics.on('track', ({ payload }) => {
+   *   console.log('This will never get called')
+   * })
+   *
+   * // cleanup .on listener
+   * removeListener()
+   * @param name - Name of event to listen to
+   * @param callback - function to fire on event
+   */
+  type On = (name: string, callback: (...params: any[]) => any) => DetachListeners;
+  /**
+   * Detach listeners
+   */
+  export type DetachListeners = () => void;
+  /**
+   * Attach a handler function to an event and only trigger it once.
+   * @example
+   * // Fire function only once per 'track'
+   * analytics.once('track', ({ payload }) => {
+   *   console.log('This is only triggered once when analytics.track() fires')
+   * })
+   *
+   * // Remove listener before it is called
+   * const listener = analytics.once('track', ({ payload }) => {
+   *   console.log('This will never get called b/c listener() is called')
+   * })
+   *
+   * // cleanup .once listener before it fires
+   * listener()
+   * @param name - Name of event to listen to
+   * @param callback - function to fire on event
+   */
+  type Once = (name: string, callback: (...params: any[]) => any) => DetachListeners;
+  /**
+   * Get data about user, activity, or context. Access sub-keys of state with `dot.prop` syntax.
+   * @example
+   * // Get the current state of analytics
+   * analytics.getState()
+   *
+   * // Get a subpath of state
+   * analytics.getState('context.offline')
+   * @param [key] - dot.prop.path value of state
+   */
+  type GetState = (key?: string) => any;
+  /**
+   * Storage utilities for persisting data.
+   * These methods will allow you to save data in localStorage, cookies, or to the window.
+   * @example
+   * // Pull storage off analytics instance
+   * const { storage } = analytics
+   *
+   * // Get value
+   * storage.getItem('storage_key')
+   *
+   * // Set value
+   * storage.setItem('storage_key', 'value')
+   *
+   * // Remove value
+   * storage.removeItem('storage_key')
+   * @property getItem - Get value from storage
+   * @property setItem - Set storage value
+   * @property removeItem - Remove storage value
+   */
+  type Storage = {
+    getItem: GetItem;
+    setItem: SetItem;
+    removeItem: RemoveItem;
+  };
+  /**
+   * Get value from storage
+   * @example
+   * analytics.storage.getItem('storage_key')
+   * @param key - storage key
+   * @param [options] - storage options
+   */
+  type GetItem = (key: string, options?: any) => any;
+  /**
+   * Set storage value
+   * @example
+   * analytics.storage.setItem('storage_key', 'value')
+   * @param key - storage key
+   * @param value - storage value
+   * @param [options] - storage options
+   */
+  type SetItem = (key: string, value: any, options?: any) => void;
+  /**
+   * Remove storage value
+   * @example
+   * analytics.storage.removeItem('storage_key')
+   * @param key - storage key
+   * @param [options] - storage options
+   */
+  type RemoveItem = (key: string, options?: any) => void;
+  /**
+   * Async reduce over matched plugin methods
+   * Fires plugin functions
+   */
+  function processEvent(): void;
+  /**
+   * Return array of event names
+   * @param eventType - original event type
+   * @param namespace - optional namespace postfix
+   * @returns - type, method, end
+   */
+  function getEventNames(eventType: string, namespace: string): any[];
+  /**
+   * Generate arguments to pass to plugin methods
+   * @param instance - analytics instance
+   * @param abortablePlugins - plugins that can be cancelled by caller
+   * @returns function to inject plugin params
+   */
+  function argumentFactory(instance: any, abortablePlugins: any[]): any;
+  /**
+   * Verify plugin is not calling itself with whatever:myPluginName self refs
+   */
+  function validateMethod(): void;
+  /**
+   * Return the canonical URL and rmove the hash.
+   * @param search - search param
+   * @returns return current canonical URL
+   */
+  function currentUrl(search: string): string;
+  /**
+   * Page data for overides
+   * @property [title] - Page title
+   * @property [url] - Page url
+   * @property [path] - Page path
+   * @property [search] - Page search
+   * @property [width] - Page width
+   * @property [height] - Page height
+   */
+  interface PageDataBase {
+    title?: string;
+    url?: string;
+    path?: string;
+    search?: string;
+    width?: string;
+    height?: string;
+  }
+  /**
+   * Get information about current page
+   * @param [pageData = {}] - Page data overides
+   */
+  type getPageData = (pageData?: PageData) => PageData;
+  /**
+   * @property name - Name of plugin
+   * @property [EVENTS] - exposed events of plugin
+   * @property [config] - Configuration of plugin
+   * @property [initialize] - Load analytics scripts method
+   * @property [page] - Page visit tracking method
+   * @property [track] - Custom event tracking method
+   * @property [identify] - User identify method
+   * @property [loaded] - Function to determine if analytics script loaded
+   * @property [ready] - Fire function when plugin ready
+   */
+  interface AnalyticsPluginBase {
+    name: string;
+    EVENTS?: any;
+    config?: any;
+    initialize?: (...params: any[]) => any;
+    page?: (...params: any[]) => any;
+    track?: (...params: any[]) => any;
+    identify?: (...params: any[]) => any;
+    loaded?: (...params: any[]) => any;
+    ready?: (...params: any[]) => any;
+  }
+  export type PageData<T extends string = string> = PageDataBase & Record<T, unknown>;
+  export type AnalyticsPlugin<T extends string = string> = AnalyticsPluginBase & (string extends T ? Record<string, unknown> : Record<T, unknown> & Record<string, unknown>);
+  export const CONSTANTS: constants;
+  export const init: typeof analytics;
+  export const Analytics: typeof analytics;
+  export default analytics;
+}
+//#endregion
+//#region src/index.d.ts
+interface RegisterCustomElementsOptions {
+  /** PrimeUIX preset to provide to custom elements. */
+  preset: Preset;
+  /** Keycloak instance to provide to custom elements. */
+  keycloak: Keycloak;
+  /** Analytics instance to provide to custom elements. */
+  analytics?: AnalyticsInstance$1 | null;
+  /** Base URI to access the Moser Labs API. */
+  apiUri?: string;
+}
+/**
+ * Call this function to register all provided custom elements at once passing
+ * the Keycloak instance to them.
+ *
+ * @example
+ * ```ts
+ * import Labs from '@moser-inc/moser-labs-themes/labs';
+ * import Keycloak from 'keycloak-js';
+ * import { registerCustomElements } from '@moser-inc/moser-labs-custom-elements';
+ *
+ * const keycloak = new Keycloak('/keycloak.json');
+ *
+ * keycloak.init({ onLoad: 'login-required' }).then((isAuthenticated) => {
+ *   if (!isAuthenticated) return;
+ *
+ *   registerCustomElements({
+ *     preset: Labs,
+ *     keycloak,
+ *     apiUri: 'https://www.moserlabs.app'
+ *   });
+ * });
+ * ```
+ *
+ * Use the custom elements anywhere in your application.
+ *
+ * @example
+ * ```html
+ * <labs-account></labs-account>
+ * <labs-app-switcher></labs-app-switcher>
+ * <labs-avatar></labs-avatar>
+ * ```
+ */
+declare function registerCustomElements(options: RegisterCustomElementsOptions): void;
+//#endregion
+export { RegisterCustomElementsOptions, registerCustomElements };