@adobe/exc-app 0.2.45 → 1.0.0

package/orgswitcher.ts

@@ -1,109 +0,0 @@
-/*************************************************************************
- * Copyright 2020 Adobe
- * All Rights Reserved.
- *
- * NOTICE: Adobe permits you to use, modify, and distribute this file in
- * accordance with the terms of the Adobe license agreement accompanying
- * it. If you have received this file from a source other than Adobe,
- * then your use, modification, or distribution of it requires the prior
- * written permission of Adobe.
- **************************************************************************/
-
-/**
- * APIs that let solutions interact with Org Switcher menu.
- *
- * ***Import:***
- *
- * ```typescript
- * import orgSwitcher from '@adobe/exc-app/orgswitcher';
- * ```
- *
- * ***Default export:***
- *
- * [OrgSwitcherApi](../interfaces/orgswitcher.orgswitcherapi.md#interface-orgswitcherapi)
- *
- * ***Usage:***
- *
- * ```typescript
- * orgswitcher.subOrgs = {
- *   'OrgId1': [
- *     {id: '123', name: 'Sub Org 1'},
- *     {id: '321', name:'Sub Org 2'}
- *   ],
- *   'OrgId2': [
- *     {id: '124', name: 'Sub Org 3'},
- *     {id: '412', name:'Sub Org 4'}
- *   ],
- *   selectedSubOrg: {id: '123', name: 'Sub Org 1'}
- * };
- * ```
- * @packageDocumentation
- * @module orgswitcher
- */
-
-import {connect} from './src/Global';
-
-export interface SubOrg {
-  /**
-   * The ID of the sub-org.
-   */
-  id: string;
-
-  /**
-   * The name of the sub-org.
-   */
-  name: string;
-}
-
-export interface SelectedSubOrg {
-  /**
-   * The sub-org that's currently selected.
-   */
-  selectedSubOrg?: SubOrg;
-}
-
-/**
- * Defines the attributes of the configuration for sub-orgs.
- */
-export type SubOrgs = SelectedSubOrg & Record<string, SubOrg[]>;
-
-/**
- * APIs that let solutions interact with Org Switcher menu.
- */
-export interface OrgSwitcherApi {
-   /**
-    * Configuration to add sub-orgs (nested under their parent org) to the org switcher. In this
-    * object, the key is the parent org that the sub orgs in the array are associated with.
-    *
-    * ***Example:***
-    *
-    * ```typescript
-    * orgswitcher.subOrgs: {
-    *   'OrgId1': [
-    *     {id: '123', name: 'Sub Org 1'},
-    *     {id: '321', name:'Sub Org 2'}
-    *   ],
-    *   'OrgId2': [
-    *     {id: '124', name: 'Sub Org 3'},
-    *     {id: '412', name:'Sub Org 4'}
-    *   ],
-    *   selectedSubOrg: {id: '123', name: 'Sub Org 1'}
-    * };
-    * ```
-    *
-    * Options:
-    * * subOrgs: Object mapping parent org ids to an array of its sub orgs with a special key for
-    * specifying the currently selected sub org.
-    *   * id: The unique id of the sub org.
-    *   * name: The name of the sub org that will be displayed in the org switcher.
-    * * selectedSubOrg: The current selected sub org. This goes inside of the subOrgs object as a
-    * special key.
-    */
-  subOrgs: SubOrgs;
-}
-
-const orgSwitcher = connect('orgSwitcher', [
-  ['subOrgs']
-]);
-
-export default orgSwitcher;

package/page.ts

@@ -1,497 +0,0 @@
-/*************************************************************************
- * Copyright 2020 Adobe
- * All Rights Reserved.
- *
- * NOTICE: Adobe permits you to use, modify, and distribute this file in
- * accordance with the terms of the Adobe license agreement accompanying
- * it. If you have received this file from a source other than Adobe,
- * then your use, modification, or distribution of it requires the prior
- * written permission of Adobe.
- **************************************************************************/
-
-/**
- * APIs that let solutions interact with the main page and personalize it, e.g. setting the title,
- * favicon, refreshing the solution iframe, etc.
- *
- * ***Import:***
- *
- * ```typescript
- * import page from '@adobe/exc-app/page';
- * ```
- *
- * ***Default export:***
- *
- * [PageApi](../interfaces/page.pageapi.md#interface-pageapi)
- *
- * ***Usage:***
- *
- * ```typescript
- * import page from '@adobe/exc-app/page';
- *
- * page.title = 'Experience Cloud';
- *
- * // Show spinner while performing an async operation
- * page.spinner = true;
- * try {
- *   await performOperation();
- * } finally {
- *   page.spinner = false;
- * }
- *
- * // Generate a shell URL that directly opens the specified solution URL
- * const shellUrl = page.generateShellUrl('/relative/path');
- *
- * // Navigate to another solution
- * page.shellRedirect('/target');
- * ```
- * @packageDocumentation
- * @module page
- */
-
-import {connect} from './src/Global';
-
-export interface ObjectWithHref {
-  /**
-   * The URL of the solution page.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * { href: 'https://example.com/abc' }
-   * ```
-   */
-  href: string;
-}
-
-export interface BlockNavigationOptions {
-  /**
-   * Set to true if org changes are the only hash location changes that should be blocked.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * {onOrgChangeOnly: true}
-   * ```
-   */
-  onOrgChangeOnly: boolean;
-}
-
-export interface ObjectWithPath {
-  /**
-   * The relative path within the solution.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * {path: '/abc'}
-   * ```
-   */
-  path: string;
-  /**
-   * Optional sandbox name to be added to URL path.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * {path: '/abc', sandbox: 'prod'}
-   * ```
-   */
-  sandbox?: string;
-}
-
-export interface ShellRedirectOptions {
-  /**
-   * Optional boolean which specifies if the redirect requires discovery.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * {discovery: true}
-   * ```
-   */
-  discovery?: boolean;
-  /**
-   * Optional boolean which specifies if the history action should be a replace
-   * instead of a push.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * {replace: true}
-   * ```
-   */
-  replace?: boolean;
-}
-
-/**
- * Defines the location-like object for which to get the shell URL. You can either specify a path or
- * an absolute URL.
- *
- * ***Example:***
- *
- * `{path: '/abc'}` or `{href: 'https://example.com/abc'}`
- */
-export type LocationLike = ObjectWithHref | ObjectWithPath;
-
-/**
- * Subset of page-level APIs available to solutions that are settable attributes.
- */
-export interface PageApiProperties {
-  /**
-   * Configuration for specifying which element should have the left margin and top margin added to it when
-   * fullscreen overlay or modal needs to be displayed. Left margin will only be added if there is a side nav.
-   * This should be a string with an element selector.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.appContainer = '#example'
-   * ```
-   */
-  appContainer: string;
-
-  /**
-   * Gets or set the favicon for the page. If this isn't set, then the default experience cloud
-   * favicon will be used.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.favicon = "https://img.icons8.com/color/48/000000/thumb-up.png";
-   * ```
-   */
-  favicon: string;
-
-  /**
-   * Configuration to show/hide a modal with fullscreen overlay. Defaults to false.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.modal = true;
-   * ```
-   */
-  modal: boolean;
-
-    /**
-     * Toggle for whether or not runtime should observe DOM changes and check the changes against
-     * modal query selectors to automatically set modal = true. If you use this option consider adding
-     * selectors with setModalQuerySelectors.
-     *
-     * ***Example:***
-     *
-     * ```typescript
-     * page.modalAutoDetect = true;
-     * ```
-     */
-  modalAutoDetect: boolean;
-
-  /**
-   * An array of key combinations for the shell to prevent default browser behavior on in cases
-   * where an application performs some other action.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.preventDefaultCombos = [
-   *   {
-   *     ctrlKey: true,
-   *     key: 's'
-   *   }
-   * ];
-   * ```
-   */
-  preventDefaultCombos: {
-    altKey?: boolean;
-    ctrlKey?: boolean;
-    metaKey?: boolean;
-    shiftKey?: boolean;
-    key: string;
-  }[];
-
-  /**
-   * Gets or sets a value indicating whether or not to show a spinner on the page. This
-   * configuration value is NOT used for the initial loading spinner (see Route Configuration
-   * hideInitialSpinner for that), but can be used to dismiss it if the spinner needs to be
-   * dismissed before a solution invokes runtime.done().
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.spinner = true;
-   * ```
-   */
-  spinner: boolean;
-
-  /**
-   * Gets or sets the title of the page.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.title = 'Adobe Experience Cloud';
-   * ```
-   */
-  title: string;
-
-  /**
-   * Sets a message to be displayed if the user is prompted before navigating away from the page.
-   * This will only be effective if page.blockNavigation is being used. Prompt messages should be
-   * localized based on the current locale of the user before being set. The default value is 'Are you sure?'.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.unloadPromptMessage = 'Are you sure you want to leave?';
-   * ```
-   */
-  unloadPromptMessage: string;
-}
-
-export interface Callback {(value?: any): void}
-
-/**
- * Defines page-level APIs available to solutions.
- */
-export interface PageApi extends PageApiProperties {
-  /**
-   * A function that listens and handles the afterPrint event.
-   *
-   * ```typescript
-   * ***Example:***
-   * page.afterPrintHandler = function () {
-   *   // Revert temporary CSS changes
-   * };
-   * ````
-   * @param callback The function that results in printing.
-   */
-  afterPrintHandler(callback: Callback): void;
-
-  /**
-   * A function that listens and handles the beforePrint event.
-   *
-   * ```typescript
-   * ***Example:***
-   * page.beforePrintHandler = function () {
-   *   // Temporary CSS changes, like unsetting height
-   * };
-   * ````
-   * @param callback The function that results in printing.
-   */
-  beforePrintHandler(callback: Callback): void;
-
-  /**
-   * Sometimes applications will need to block navigation away from the current page. The most common use case
-   * for this is when a user has unsaved changes that would be lost on navigation.
-   *
-   * There are 3 types of navigation in unified shell that must be accounted for:
-   * 1. User attempts to navigate in a way that will cause the browser to reload. This includes page refreshes, manual URL changes, and solution switcher clicks to a non-unified shell application.
-   * 2. User attempts to navigate to another page hosted on unified shell via the shell. This includes workspace clicks, org changes, and solution switches to a unified shell application. Because this is only a hash history change, it does not cause a full browser reload.
-   * 3. User attempts to navigate to another page in the current application via a link in the iframe.
-   *
-   * In order to prevent the first and second types of navigation, unified shell offers a `blockNavigation` function. To turn on navigation blocking, the application should set:
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.blockNavigation(true);
-   * ```
-   * When this function is called with `true`, Unified Shell will set a `beforeUnload` handler on the page. This will block the first type of navigation. Unified Shell will also use `history.block` to block hash navigations such as org switches and workspace changes.
-   * To handle the third type of navigation, applications must block the location change from within the iframe before it propogates to the shell. This is because unified shell won't know about the iframe navigation until after it happens.
-   * To solve for this, solutions should `history.block` from within the iframe as well. It is important to note that only `push` location changes should be blocked. If the solution blocks all location changes, the navigation blocking prompt will be shown to the user multiple times.
-   * When navigation blocking is no longer needed the application should set `runtime.blockNavigation(false)`.
-   *
-   * In special cases, a solution may want to allow workspace changes but block any other type of navigation. To enable this, the option `onOrgChangeOnly` should be passed in.
-   *
-   * ***Example:***
-   *
-   * ```
-   * runtime.blockNavigation(true, {onOrgChangeOnly: true});
-   * ```
-   *
-   * Please note that navigation blocking is currently only supported for tenanted solutions. If you would like to block navigation from a tenantless solution please contact a unified shell team member to discuss your use case.
-   */
-  blockNavigation(enabled: boolean, options?: BlockNavigationOptions): void;
-
-  /**
-   * Browsers do not currently allow pages within the iframe to write data to the user's clipboard.
-   * Utilizing this method, we are able to check that the user has granted permission to write to
-   * their clipboard and then do so.
-   *
-   * **Example:**
-   *
-   * ```typescript
-   * page.clipboardWrite('Message to write to the clipboard');
-   * ```
-   * @param msg The string to write to the clipboard.
-   */
-  clipboardWrite(msg: string): void;
-
-  /**
-   * Tells the Shell that the Solution has loaded and is ready to be used by a user and dismisses
-   * the initial loading spinner.
-   *
-   * At the earliest, done should be called after Ready event was fired to ensure accurate reporting.
-   *
-   * One of the main objectives of using done is to measure UX performance, it should be called after
-   * all network activity is completed and the app is interactive - Ready for users to do their work.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.done();
-   * ```
-   */
-  done(): void;
-
-  /**
-   * Method to take a relative path or full iframe URL and generate a unified shell url.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * // returns `https://experience.adobe.com/#/@tenant/solution/abc`
-   * page.generateShellUrl({path: '/abc'});
-   *
-   * // returns `https://experience.adobe.com/#/@tenant/sname:prod/solution/abc`
-   * page.generateShellUrl({path: '/abc', sandbox: 'prod'});
-   *
-   * // returns `https://experience.adobe.com/#/@tenant/solution/abc`
-   * page.generateShellUrl({href: 'https://example.com/abc'});
-   * ```
-   * @param location Object with either a path and optional sandbox or href key and corresponding
-   * value from which to generate the shell URL.
-   * @param newApp When true generates a new url with the given location without hash values
-   * or pathname resolutions specific to the current app.
-   * @returns The shell URL for the specified view of the solution.
-   */
-  generateShellUrl(location: LocationLike, newApp?: boolean): string;
-
-  /**
-   * Get the list of selectors presently being used by modalAutoDetect.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.getModalQuerySelectors({path: '/abc'});
-   * ```
-   * @returns The list of selectors presently being used by modalAutoDetect.
-   */
-  getModalQuerySelectors(): Array<string>
-
-  /**
-   * Triggers the reload of the solution iframe. Calling this function will regenerate the iframe
-   * source, triggering the discovery URL flow if configured.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.iframeReload();
-   * ```
-   * @param cacheBust Whether the reload should include a unique query param on the iframe URL to
-   * cache bust the page. This defaults to false for SPA pipeline apps, true to other apps for
-   * backwards compatibility purposes.
-   */
-  iframeReload(cacheBust?: boolean): void;
-
-  /**
-   * Replaces the application iframe with the not found page.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.notFound();
-   * ```
-   */
-  notFound(): void;
-
-  /**
-   * Opens the specified URL in the shell in a new tab. This is useful in scenarios where an element
-   * won't be an anchor or link and solution needs to open the URL.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.openInNewTab('/path');
-   * ```
-   * @param path The relative path within the solution.
-   * @param newApp When true generates a new url with the given location without hash values
-   * or pathname resolutions specific to the current app.
-   */
-  openInNewTab(path: string, newApp?: boolean): void;
-
-  /**
-   * A function to control printing. The callback function should call `window.print()`
-   * at some point. It's important that the callback not be an arrow function if you
-   * want the `window` object to be the iframe contents. Feel free to adjust your
-   * CSS or UI before `window.print()` and reverse those changes afterwards.
-   *
-   * ```typescript
-   * ***Example:***
-   * page.print = function () {
-   *   window.print();
-   * };
-   * ````
-   * @param callback The function that results in printing.
-   */
-  print(callback: Callback): void;
-
-  /**
-   * Set the list of selectors presently being used by modalAutoDetect. If set to an empty
-   * array, the default selectors used by runtime will be used instead. To stop observing changes
-   * unset modalAutoDetect. Setting additonal selectors replaces the currently set selectors, use
-   * page.getModalQuerySelectors and append new selectors to the returned list before resetting
-   * to modify the existing list of selectors.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.setModalQuerySelectors(['.someSpecialCaseModal', '.yourNormalModal']);
-   * ```
-   * @param selectors The list of selectors for modalAutoDetect to use.
-   */
-  setModalQuerySelectors(selectors: Array<string>): void
-
-  /**
-   * Redirects to another unified shell solution. Path should be the complete relative path of a
-   * valid unified shell solution url (i.e. if shellRedirect is called from /target to /analytics,
-   * the path paremeter would need to start with /analytics). Query and hash are optional.
-   *
-   * ***Example:***
-   *
-   * ```typescript
-   * page.shellRedirect('/path?a=b#workspace');
-   * ```
-   * @param path Path including search and hash to a unified shell solution.
-   * @param options Options for redirect. Options include discovery which determines if the new
-   * location requires a discovery call and replace which determines if the history action should be
-   * a replace or push.
-   */
-  shellRedirect(path: string, options?: ShellRedirectOptions): void;
-}
-
-const page = connect('page', [
-  ['afterPrintHandler'],
-  ['appContainer'],
-  ['beforePrintHandler'],
-  ['blockNavigation', true],
-  ['clipboardWrite', true],
-  ['done', true],
-  ['generateShellUrl', true],
-  ['getModalQuerySelectors'],
-  ['favicon'],
-  ['iframeReload', true],
-  ['modal'],
-  ['modalAutoDetect'],
-  ['notFound', true],
-  ['openInNewTab', true],
-  ['preventDefaultCombos'],
-  ['print', true],
-  ['shellRedirect', true],
-  ['setModalQuerySelectors'],
-  ['spinner'],
-  ['title'],
-  ['unloadPromptMessage']
-]);
-
-export default page;

package/permissions.ts

@@ -1,103 +0,0 @@
-/*************************************************************************
- * Copyright 2021 Adobe
- * All Rights Reserved.
- *
- * NOTICE: Adobe permits you to use, modify, and distribute this file in
- * accordance with the terms of the Adobe license agreement accompanying
- * it. If you have received this file from a source other than Adobe,
- * then your use, modification, or distribution of it requires the prior
- * written permission of Adobe.
- **************************************************************************/
-
-/**
- * APIs to get permissions for a user. An app in unified shell can consume Permissions service.
- *
- * To consume this API, add the following import to your code.
- *
- * ```typescript
- * import permissions from '@adobe/exc-app/permissions';
- * ```
- *
- * The default export is an object of type [PermissionsApi](../interfaces/_permissions_.permissionsapi.md)
- *
- * API reference: [scroll down](#index)
- *
- * ### Sample code
- *
- * ```typescript
- * import permissions from '@adobe/exc-app/permissions';
- *
- * const {permissions: perms} = await permissions.get({permissions: [
- *   'permission1',
- *   'permission2'
- * ]});
- * ```
- *
- * All permissions can be requested using the key '*'
- * ```typescript
- * import permissions from '@adobe/exc-app/permissions';
- *
- * const {permissions: perms} = await permissions.get({permissions: ['*']});
- * ```
- * @packageDocumentation
- * @module permissions
- */
-
-import {getImpl} from './src/Global';
-
-/**
- * A map of permissions in the permissions service.
- */
-export interface Permissions {
-  [key: string]: string[];
-}
-
-/**
- * The response from the permissions service.
- */
-export interface PermissionsResponse<T extends Permissions> {
-  /**
-   * The map of permissions.
-   */
-  permissions?: T;
-
-  /**
-   * The map of resource types.
-   */
-  resourceTypes?: T;
-}
-
-/**
- * The input parameters for the permissions API.
- */
-export interface Parameters {
-  /**
-   * List of permissions to get.
-   */
-  permissions?: string[];
-
-  /**
-   * List of resource types to get.
-   */
-  resourceTypes?: string[];
-}
-
-/**
- * APIs to get permissions. An app in unified shell can consume PALM ACL service.
- */
-export interface PermissionsApi {
-  /**
-   * Gets permissions based on the specified parameters.
-   * @param params Parameters used to identify permissions to retrieve.
-   * @returns A promise for the specified permissions.
-   */
-  get<T extends Permissions>(params: Parameters): Promise<PermissionsResponse<T>>;
-}
-
-const permissions: PermissionsApi = {
-  get: (params) => {
-    return getImpl('permissions')().get(params);
-  }
-};
-
-export default permissions;