@shopify/app-bridge-react 0.0.0-snapshot-20221220002610

package/README.md

@@ -0,0 +1,171 @@
+# `@shopify/app-bridge-react`
+
+**[Join our team and work on libraries like this one.](https://www.shopify.ca/careers)**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE.md)
+[![npm version](https://badge.fury.io/js/%40shopify%2Fapp-bridge-react.svg)](https://badge.fury.io/js/%40shopify%2Fapp-bridge-react.svg)
+[![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/@shopify/app-bridge-react.svg)](https://img.shields.io/bundlephobia/minzip/@shopify/app-bridge-react.svg)
+
+Shopify App Bridge offers React component wrappers for some App Bridge actions. This is a great option if you are already using React and want to follow familiar patterns.
+
+Instead of using App Bridge actions directly:
+
+```js
+import createApp from '@shopify/app-bridge';
+import * as TitleBar from '@shopify/app-bridge/actions/TitleBar';
+
+const app = createApp({
+  apiKey: 'API key from Shopify Partner Dashboard',
+  host: 'host from URL search parameter',
+});
+
+const titleBarOptions = {
+  title: 'My page title',
+};
+
+const myTitleBar = TitleBar.create(app, titleBarOptions);
+```
+
+Use the React component wrappers:
+
+> **Note**: only one `Provider` is needed for your application.
+
+```jsx
+// MyApp.jsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import {Provider} from '@shopify/app-bridge-react';
+import {RedirectButton} from './RedirectButton';
+
+function MyApp() {
+  const config = {
+    apiKey: 'API key from Shopify Partner Dashboard',
+    host: 'host from URL search parameter',
+  };
+
+  return (
+    <Provider config={config}>
+      <RedirectButton />
+    </Provider>
+  );
+}
+
+const root = document.createElement('div');
+document.body.appendChild(root);
+ReactDOM.createRoot(root).render(<MyApp />);
+```
+
+To access an `app` from the Provider, use the `useAppBridge` hook (since `v1.25.0`):
+
+```jsx
+// RedirectButton.jsx
+import {Button, Redirect} from '@shopify/app-bridge/actions';
+import {useAppBridge} from '@shopify/app-bridge-react';
+
+function RedirectButton() {
+  const app = useAppBridge();
+  const redirect = Redirect.create(app);
+
+  const handleClick = () => {
+    // Go to {shopUrl}/admin/customers with newContext
+    redirect.dispatch(Redirect.Action.ADMIN_PATH, {
+      path: '/customers',
+      newContext: true,
+    });
+  };
+
+  return <Button onClick={handleClick}>Activate Lasers for Customers</Button>;
+}
+```
+
+## Migrating from 2.x.x to 3.0.0
+
+There are two breaking API changes in version 3.0.0.
+
+- `useContextualSaveBar`
+- `useToast`
+
+### useContextualSaveBar
+
+In version 2.x.x, `useContextualSaveBar` was called with all of its options. It then created the contextual save bar and dispatched show and hide functions as an internal side effect based on the `visible` prop and any changes in options. It did not return anything.
+
+#### Example code
+
+```tsx
+useContextualSaveBar({
+  discardAction,
+  saveAction,
+  fullWidth,
+  leaveConfirmationDisable,
+  visible,
+});
+```
+
+In version 3.0.0, `useContextualSaveBar` becomes more declarative. The hook is called without any props and it returns several objects and methods that can be used to update contextual save bar options, as well as to show and hide the component.
+
+#### Example code
+
+```tsx
+const {show, hide, saveAction, discardAction} = useContextualSaveBar();
+const fullWidth = true;
+const leaveConfirmationDisabled = false;
+
+<Button
+  primary
+  onClick={() => {
+    show(fullWidth, leaveConfirmationDisabled);
+    discardAction.setOptions({onAction: () => console.log('On discard')});
+    saveAction.setOptions({onAction: () => console.log('On save')});
+  }}
+>
+  Show ContextualSaveBar
+</Button>
+<Button onClick={hide}>Hide ContextualSaveBar</Button>
+```
+
+See [useContextualSaveBar docs](https://shopify.dev/apps/tools/app-bridge/react-components/contextual-save-bar) for more details.
+
+### useToast
+
+In version 2.x.x, `useToast` returns a `show` method that accepts one prop - an object with the following properties:
+
+- `content`
+- `duration`
+- `isError`
+- `onDismiss`
+
+All the props except `content` are optional.
+
+#### Example code
+
+```tsx
+const {show} = useToast
+
+show({
+  content: 'Success!,
+  duration: 2000,
+  isError: false,
+  onDismiss: () => console.log('Dismissed'),
+})
+```
+
+In version 3.0.0, the `content` moves to a top-level prop and the remaining properties are passed in as an optional options prop (all properties in the options object remain optional).
+`
+
+#### Example code
+
+```tsx
+const {show} = useToast;
+
+show('Success!', {
+  duration: 2000,
+  isError: false,
+  onDismiss: () => console.log('Dismissed'),
+});
+```
+
+See [useToast docs](https://shopify.dev/apps/tools/app-bridge/react-components/toast) for more details.
+
+## Legacy support
+
+If you are using App Bridge `v1.24.0` and below, or your project does not support React hooks, alternative methods on how to access `app` can be found in the [Provider docs](https://shopify.dev/tools/app-bridge/react-components/provider#accessing-the-app-bridge-client-directly).

package/components/ClientRouter/ClientRouter.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+import { Unsubscribe } from '@shopify/app-bridge';
+import { AppBridgeContext } from '../../context';
+import { History } from './router';
+export interface Props {
+    history: History;
+}
+/**
+ * ClientRouter component
+ *
+ * @remarks
+ * React component which keeps the Shopify admin url in sync with the app url
+ *
+ * @public
+ */
+export default class ClientRouter extends React.Component<Props, never> {
+    static contextType: React.Context<import("../../context").IAppBridgeContext>;
+    context: React.ContextType<typeof AppBridgeContext>;
+    unsubscribe?: Unsubscribe;
+    componentDidMount(): void;
+    componentWillUnmount(): void;
+    render(): null;
+}

package/components/ClientRouter/ClientRouter.js

@@ -0,0 +1,52 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var react_1 = __importDefault(require("react"));
+var context_1 = require("../../context");
+var router_1 = require("./router");
+/**
+ * ClientRouter component
+ *
+ * @remarks
+ * React component which keeps the Shopify admin url in sync with the app url
+ *
+ * @public
+ */
+var ClientRouter = /** @class */ (function (_super) {
+    __extends(ClientRouter, _super);
+    function ClientRouter() {
+        return _super !== null && _super.apply(this, arguments) || this;
+    }
+    ClientRouter.prototype.componentDidMount = function () {
+        var history = this.props.history;
+        this.unsubscribe = router_1.handleRouteChange(this.context, history);
+    };
+    ClientRouter.prototype.componentWillUnmount = function () {
+        if (this.unsubscribe) {
+            this.unsubscribe();
+        }
+    };
+    ClientRouter.prototype.render = function () {
+        return null;
+    };
+    ClientRouter.contextType = context_1.AppBridgeContext;
+    return ClientRouter;
+}(react_1.default.Component));
+exports.default = ClientRouter;

package/components/ClientRouter/hook.d.ts

@@ -0,0 +1,10 @@
+import { History } from './router';
+/**
+ * useRoutePropagation
+ *
+ * @remarks
+ * A hook which keeps the Shopify admin url in sync with the app url
+ *
+ * @public
+ */
+export default function useClientRouting(history: History): void;

package/components/ClientRouter/hook.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var react_1 = require("react");
+var useAppBridge_1 = require("../../useAppBridge");
+var router_1 = require("./router");
+/**
+ * useRoutePropagation
+ *
+ * @remarks
+ * A hook which keeps the Shopify admin url in sync with the app url
+ *
+ * @public
+ */
+function useClientRouting(history) {
+    var app = useAppBridge_1.useAppBridge();
+    react_1.useEffect(function () {
+        return router_1.handleRouteChange(app, history);
+    }, [app, history]);
+}
+exports.default = useClientRouting;

package/components/ClientRouter/index.d.ts

@@ -0,0 +1,3 @@
+export { default as ClientRouter } from './ClientRouter';
+export { default as useClientRouting } from './hook';
+export { History } from './router';

package/components/ClientRouter/index.js

@@ -0,0 +1,10 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useClientRouting = exports.ClientRouter = void 0;
+var ClientRouter_1 = require("./ClientRouter");
+Object.defineProperty(exports, "ClientRouter", { enumerable: true, get: function () { return __importDefault(ClientRouter_1).default; } });
+var hook_1 = require("./hook");
+Object.defineProperty(exports, "useClientRouting", { enumerable: true, get: function () { return __importDefault(hook_1).default; } });

package/components/ClientRouter/router.d.ts

@@ -0,0 +1,5 @@
+import { ClientApplication } from '@shopify/app-bridge';
+export interface History {
+    replace(path: string): void;
+}
+export declare function handleRouteChange(app: ClientApplication, history: History): import("@shopify/app-bridge").Unsubscribe;

package/components/ClientRouter/router.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleRouteChange = void 0;
+var actions_1 = require("@shopify/app-bridge/actions");
+function handleRouteChange(app, history) {
+    return app.subscribe(actions_1.Redirect.Action.APP, function (_a) {
+        var path = _a.path;
+        history.replace(path);
+    });
+}
+exports.handleRouteChange = handleRouteChange;

package/components/ContextualSaveBar/ContextualSaveBar.d.ts

@@ -0,0 +1,9 @@
+import type { DiscardActionOptions, SaveActionOptions } from '@shopify/app-bridge/actions/ContextualSaveBar';
+export interface Props {
+    discardAction?: DiscardActionOptions;
+    saveAction?: SaveActionOptions;
+    fullWidth?: boolean;
+    leaveConfirmationDisable?: boolean;
+    visible?: boolean;
+}
+export default function ContextualSaveBar({ discardAction, saveAction, fullWidth, leaveConfirmationDisable, visible, }: Props): null;

package/components/ContextualSaveBar/ContextualSaveBar.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var react_1 = require("react");
+var hooks_1 = require("../../hooks");
+function ContextualSaveBar(_a) {
+    var _b = _a.discardAction, discardAction = _b === void 0 ? {} : _b, _c = _a.saveAction, saveAction = _c === void 0 ? {} : _c, fullWidth = _a.fullWidth, leaveConfirmationDisable = _a.leaveConfirmationDisable, visible = _a.visible;
+    var _d = hooks_1.useContextualSaveBar(), show = _d.show, hide = _d.hide, saveActionSetOptions = _d.saveAction.setOptions, discardActionSetOptions = _d.discardAction.setOptions;
+    react_1.useEffect(function () {
+        saveActionSetOptions(saveAction);
+    }, [saveAction]);
+    react_1.useEffect(function () {
+        discardActionSetOptions(discardAction);
+    }, [discardAction]);
+    react_1.useEffect(function () {
+        if (visible) {
+            show({ fullWidth: fullWidth, leaveConfirmationDisable: leaveConfirmationDisable });
+        }
+        else {
+            hide();
+        }
+    }, [fullWidth, leaveConfirmationDisable, visible]);
+    return null;
+}
+exports.default = ContextualSaveBar;

package/components/ContextualSaveBar/index.d.ts

@@ -0,0 +1,3 @@
+import ContextualSaveBar, { Props } from './ContextualSaveBar';
+export default ContextualSaveBar;
+export { Props };

package/components/ContextualSaveBar/index.js

@@ -0,0 +1,7 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var ContextualSaveBar_1 = __importDefault(require("./ContextualSaveBar"));
+exports.default = ContextualSaveBar_1.default;

package/components/Loading/Loading.d.ts

@@ -0,0 +1,19 @@
+import React from 'react';
+import { AppBridgeContext } from '../../context';
+/**
+ * Loading component
+ *
+ * @remarks
+ * React component which wraps the Shopify App Bridge Loading action.
+ *
+ * @public
+ */
+declare class Loading extends React.Component {
+    static contextType: React.Context<import("../../context").IAppBridgeContext>;
+    context: React.ContextType<typeof AppBridgeContext>;
+    private loading;
+    componentDidMount(): void;
+    componentWillUnmount(): void;
+    render(): null;
+}
+export default Loading;

package/components/Loading/Loading.js

@@ -0,0 +1,55 @@
+"use strict";
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var react_1 = __importDefault(require("react"));
+var actions_1 = require("@shopify/app-bridge/actions");
+var context_1 = require("../../context");
+/**
+ * Loading component
+ *
+ * @remarks
+ * React component which wraps the Shopify App Bridge Loading action.
+ *
+ * @public
+ */
+var Loading = /** @class */ (function (_super) {
+    __extends(Loading, _super);
+    function Loading() {
+        return _super !== null && _super.apply(this, arguments) || this;
+    }
+    Loading.prototype.componentDidMount = function () {
+        var app = this.context;
+        this.loading = actions_1.Loading.create(app);
+        if (this.loading != null) {
+            this.loading.dispatch(actions_1.Loading.Action.START);
+        }
+    };
+    Loading.prototype.componentWillUnmount = function () {
+        if (this.loading != null) {
+            this.loading.dispatch(actions_1.Loading.Action.STOP);
+        }
+    };
+    Loading.prototype.render = function () {
+        return null;
+    };
+    Loading.contextType = context_1.AppBridgeContext;
+    return Loading;
+}(react_1.default.Component));
+exports.default = Loading;

package/components/Loading/index.d.ts

@@ -0,0 +1,2 @@
+import Loading from './Loading';
+export default Loading;

package/components/Loading/index.js

@@ -0,0 +1,7 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var Loading_1 = __importDefault(require("./Loading"));
+exports.default = Loading_1.default;

package/components/Modal/Modal.d.ts

@@ -0,0 +1,32 @@
+import { Size } from '@shopify/app-bridge/actions/Modal';
+import { ActionProps } from '../../types';
+export interface Props {
+    /** Whether the modal is open or not */
+    open: boolean;
+    /** The url that will be loaded as the content of the modal */
+    src?: string;
+    /** The content for the title of the modal */
+    title?: string;
+    /** Controls the size of the modal */
+    size?: keyof typeof Size;
+    /** Message to display inside modal */
+    message?: string;
+    /** Primary action */
+    primaryAction?: ActionProps;
+    /** Collection of secondary actions */
+    secondaryActions?: ActionProps[];
+    /** Callback when the modal is closed */
+    onClose?(): void;
+    /** Enable loading behaviour, when `true` bear in mind you will need to use `Modal Content` to dismiss the loading after the iframe page is fully loaded */
+    loading?: boolean;
+}
+/**
+ * Modal component
+ *
+ * @remarks
+ * React component which wraps the Shopify App Bridge Modal action.
+ *
+ * @public
+ */
+declare function Modal(props: Props): null;
+export default Modal;

package/components/Modal/Modal.js

@@ -0,0 +1,139 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+var react_1 = require("react");
+var Modal_1 = require("@shopify/app-bridge/actions/Modal");
+var transformers_1 = require("../../utilities/transformers");
+var useAppBridge_1 = require("../../useAppBridge");
+/**
+ * Modal component
+ *
+ * @remarks
+ * React component which wraps the Shopify App Bridge Modal action.
+ *
+ * @public
+ */
+function Modal(props) {
+    var app = useAppBridge_1.useAppBridge();
+    var focusReturnPoint = react_1.useRef(null);
+    // Initialize with open: false so the open action will dispatch on initial load
+    var prevProps = react_1.useRef({ open: false });
+    var open = props.open;
+    var isUnmounted = react_1.useRef(false);
+    var modal = react_1.useMemo(function () {
+        /**
+         * We purposely don't pass buttons here as they will be replaced
+         * by the subsequent useEffect to call `set` to update the options.
+         * If we pass them in here button subscriptions will be created without
+         * being cleaned up.
+         */
+        var primaryAction = props.primaryAction, secondaryActions = props.secondaryActions, rest = __rest(props, ["primaryAction", "secondaryActions"]);
+        return Modal_1.create(app, transformProps(app, rest));
+    }, [app]);
+    /**
+     * All option updates are handled in this useEffect to avoid race conditions.
+     * For example, we need to call `modal.unsubscribe` to clean up button subscriptions
+     * but we calling it will also unsubscribe the onClose handler. Therefore we want
+     * to ensure all callbacks are handled in a single useEffect with a single clean up
+     * call to unsubscribe.
+     */
+    react_1.useEffect(function () {
+        if (isUnmounted.current) {
+            prevProps.current = props;
+            return;
+        }
+        var wasOpen = prevProps.current.open;
+        var openUpdated = wasOpen !== open;
+        /** We only call `set` to update the options if the modal is open.
+         * This is because while the modal is closed updates don't take effect on screen.
+         */
+        if (open) {
+            var transformedProps = transformProps(app, props, wasOpen);
+            /** We skip dispatching the update action if we're about to update the open state.
+             * This is because the OPEN action will always sends the updated options
+             * so we don't need to send it twice.
+             */
+            var shouldSendUpdate = !openUpdated;
+            if (isIframeModal(transformedProps)) {
+                modal.set(transformedProps, shouldSendUpdate);
+            }
+            else {
+                modal.set(transformedProps, shouldSendUpdate);
+            }
+        }
+        if (openUpdated) {
+            if (open) {
+                modal.dispatch(Modal_1.Action.OPEN);
+                focusReturnPoint.current = document.activeElement;
+            }
+            else {
+                modal.dispatch(Modal_1.Action.CLOSE);
+                if (focusReturnPoint.current != null && document.contains(focusReturnPoint.current)) {
+                    focusReturnPoint.current.focus();
+                    focusReturnPoint.current = null;
+                }
+            }
+        }
+        if (props.onClose != null) {
+            modal.subscribe(Modal_1.Action.CLOSE, props.onClose);
+        }
+        prevProps.current = props;
+        return function () {
+            // This is important to clean up previous buttons and onClose subscriptions
+            modal.unsubscribe();
+        };
+    }, [props, open]);
+    react_1.useEffect(function () {
+        return function () {
+            if (prevProps.current.open) {
+                modal.dispatch(Modal_1.Action.CLOSE);
+            }
+        };
+    }, [modal]);
+    return null;
+}
+function isIframeModal(options) {
+    return (typeof options.url === 'string' ||
+        typeof options.path === 'string');
+}
+function transformProps(app, props, wasOpen) {
+    var title = props.title, size = props.size, message = props.message, src = props.src, primaryAction = props.primaryAction, secondaryActions = props.secondaryActions, loading = props.loading;
+    var safeSize = size == null ? undefined : Modal_1.Size[size];
+    var srcPayload = {};
+    if (src != null) {
+        if (src.match('^https?://')) {
+            srcPayload.url = src;
+        }
+        else {
+            srcPayload.path = src;
+        }
+    }
+    return __assign(__assign({ title: title, message: message, size: safeSize }, srcPayload), { footer: {
+            buttons: transformers_1.transformActions(app, {
+                primaryAction: primaryAction,
+                secondaryActions: secondaryActions,
+            }),
+        }, loading: wasOpen ? undefined : loading });
+}
+exports.default = Modal;

package/components/Modal/ModalContent/ModalContent.d.ts

@@ -0,0 +1,24 @@
+import React from 'react';
+import { AppBridgeContext } from '../../../context';
+export interface Props {
+    /** Show/Dismiss loading spinner */
+    loading: boolean;
+}
+/**
+ * Modal Content component
+ *
+ * @remarks
+ * React component which wraps the Shopify App Bridge Modal Content action.
+ *
+ * @public
+ */
+declare class ModalContent extends React.Component<Props> {
+    static contextType: React.Context<import("../../../context").IAppBridgeContext>;
+    context: React.ContextType<typeof AppBridgeContext>;
+    private modalContent;
+    componentDidMount(): void;
+    componentDidUpdate(): void;
+    syncLoadingStatus(): void;
+    render(): null;
+}
+export default ModalContent;