@shopgate/engage 7.32.0-beta.2 → 7.32.0-beta.20

package/components/v2/IconButton/IconButton.d.ts

@@ -0,0 +1,72 @@
+import React from 'react';
+import type { PaletteColorsWithMain, ShadowSize, Theme } from '@shopgate/engage/styles';
+import type { ButtonBaseProps } from '../ButtonBase';
+type StyleParams = Required<Pick<IconButtonOwnProps, 'variant' | 'color' | 'size' | 'shape'>> & Pick<IconButtonOwnProps, 'elevation'>;
+declare const useStyles: (params: StyleParams, muiStyleOverridesParams?: {
+    props: Record<string, unknown>;
+    ownerState?: Record<string, unknown> | undefined;
+} | undefined) => {
+    classes: Record<"surface" | "root" | "circular" | "rounded", string>;
+    theme: Theme;
+    css: import("tss-react").Css;
+    cx: import("tss-react").Cx;
+};
+export type IconButtonSize = 'small' | 'medium' | 'large';
+export interface IconButtonOwnProps {
+    /**
+     * Accessible name of the button. Required, because an icon carries no text of its own.
+     */
+    'aria-label': string;
+    /**
+     * `plain` draws no background, `surface` the themed surface that floating buttons sit on.
+     * @default 'plain'
+     */
+    variant?: 'plain' | 'surface';
+    /**
+     * The color of the icon.
+     * @default 'inherit'
+     */
+    color?: PaletteColorsWithMain | 'inherit' | 'cta';
+    /**
+     * The size of the component. Sets both the hit area and the icon.
+     * @default 'medium'
+     */
+    size?: IconButtonSize;
+    /**
+     * Corner rounding. `rounded` uses the `components.iconButton.borderRadius` theme token.
+     * @default 'circular'
+     */
+    shape?: 'circular' | 'rounded';
+    /**
+     * Depth of the drop shadow. A number indexes `theme.shadows`, a `ShadowSize` resolves through
+     * `theme.shadowSizes`. Only drawn while the `components.iconButton.boxShadow` token is unset.
+     */
+    elevation?: number | ShadowSize;
+    /**
+     * If `true`, the icon is replaced by a loading indicator and the button is disabled.
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Replaces the icon while the button is loading. By default it renders a `CircularProgress`.
+     */
+    loadingIndicator?: React.ReactNode;
+    /**
+     * Override or extend the styles applied to the component.
+     */
+    classes?: Partial<ReturnType<typeof useStyles>['classes']>;
+    /**
+     * The icon to render.
+     */
+    children: React.ReactNode;
+}
+export type IconButtonProps<C extends React.ElementType = 'button'> = IconButtonOwnProps & ButtonBaseProps<C>;
+/**
+ * The IconButton component renders an icon as a click target of its own. Unlike `Button` it carries
+ * no label, so it sizes itself to a square hit area and takes its accessible name from `aria-label`.
+ */
+declare const IconButtonComponent: <C extends React.ElementType = "button">(props: IconButtonProps<C> & {
+    ref?: React.ComponentPropsWithRef<C>["ref"];
+}) => React.ReactElement | null;
+export default IconButtonComponent;
+//# sourceMappingURL=IconButton.d.ts.map

package/components/v2/IconButton/IconButton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IconButton.d.ts","sourceRoot":"","sources":["../../../../components/v2/IconButton/IconButton.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAqB,MAAM,OAAO,CAAC;AAE1C,OAAO,KAAK,EAAE,qBAAqB,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAGxF,OAAO,KAAK,EAAsB,eAAe,EAAE,MAAM,eAAe,CAAC;AAmGzE,KAAK,WAAW,GACd,QAAQ,CAAC,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,GACxE,IAAI,CAAC,kBAAkB,EAAE,WAAW,CAAC,CAAC;AAE1C,QAAA,MAAM,SAAS;;cAR0C,CAAC;;;;;;CAwExD,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE1D,MAAM,WAAW,kBAAkB;IACjC;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B;;;OAGG;IACH,KAAK,CAAC,EAAE,qBAAqB,GAAG,SAAS,GAAG,KAAK,CAAC;IAClD;;;OAGG;IACH,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAChC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;OAEG;IACH,gBAAgB,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACnC;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAC3D;;OAEG;IACH,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,KAAK,CAAC,WAAW,GAAG,QAAQ,IAChE,kBAAkB,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC;AAS1C;;;GAGG;AACH,QAAA,MAAM,mBAAmB,EAAwB,CAAC,CAAC,SAAS,KAAK,CAAC,WAAW,GAAG,QAAQ,EACtF,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,KAAK,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;CAAE,KACxE,KAAK,CAAC,YAAY,GAAG,IAAI,CAAC;AAE/B,eAAe,mBAAmB,CAAC"}

package/components/v2/IconButton/IconButton.js

@@ -0,0 +1,169 @@
+import React, { forwardRef } from 'react';
+import { makeStyles } from '@shopgate/engage/styles';
+import CircularProgress from "../CircularProgress";
+import ButtonBase from "../ButtonBase";
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Renders the button. Exported through `IconButtonComponent`, which carries the public docs.
+ * @param props The component props.
+ * @param ref Forwarded ref.
+ * @returns The rendered button.
+ */
+function IconButton(props, ref) {
+  const {
+    variant = 'plain',
+    color = 'inherit',
+    size = 'medium',
+    shape = 'circular',
+    elevation,
+    loading = false,
+    loadingIndicator: loadingIndicatorProp,
+    disabled = false,
+    className,
+    classes: classesProp,
+    children,
+    ...other
+  } = props;
+  const {
+    classes,
+    cx
+  } = useStyles({
+    variant,
+    color,
+    size,
+    shape,
+    elevation
+  }, {
+    props: {
+      classes: classesProp
+    }
+  });
+  const loadingIndicator = loadingIndicatorProp ?? /*#__PURE__*/_jsx(CircularProgress, {
+    color: "inherit",
+    size: LOADING_INDICATOR_SIZES[size]
+  });
+  return /*#__PURE__*/_jsx(ButtonBase
+  // Rendered through the default `button` view of ButtonBase: TypeScript cannot check an
+  // object literal against `ComponentPropsWithRef<C>` while `C` is unresolved. The ref is
+  // forwarded untouched, and the public signature below restores the caller's element type.
+  , {
+    ref: ref,
+    className: cx(classes.root, {
+      [classes.surface]: variant === 'surface',
+      [classes.circular]: shape === 'circular',
+      [classes.rounded]: shape === 'rounded'
+    }, 'engage__icon-button', className),
+    disableBaseClassName: true,
+    "data-variant": variant,
+    "data-color": color,
+    "data-size": size,
+    "data-shape": shape,
+    "data-loading": loading || undefined,
+    disabled: disabled || loading,
+    ...other,
+    children: loading ? loadingIndicator : children
+  });
+}
+
+// Edge length of the square hit area per size. The icon is sized by the matching `components.icon`
+// token, so the padding around it follows from the difference.
+const BOX_SIZES = {
+  small: 32,
+  medium: 40,
+  large: 48
+};
+
+// Diameter of the default loading indicator per size, smaller than the icon it stands in for.
+const LOADING_INDICATOR_SIZES = {
+  small: 16,
+  medium: 20,
+  large: 24
+};
+
+/**
+ * Resolves an `elevation` prop into a box-shadow.
+ * @param theme The active theme.
+ * @param elevation A `theme.shadows` index, or a size of `theme.shadowSizes`.
+ * @returns The box-shadow value.
+ */
+const resolveElevation = (theme, elevation) => typeof elevation === 'number' ? theme.shadows[elevation] : theme.shadowSizes[elevation];
+
+// Share of the overlay the button tints itself with on hover, in percent. The dark scheme needs
+// more of it: the overlay takes the color of the icon, and a light tint over a dark surface reads
+// as less.
+const HOVER_OVERLAY_PERCENT = 10;
+const HOVER_OVERLAY_PERCENT_DARK = 28;
+
+// The background a button paints before the hover overlay. Only `surface` publishes it, so a plain
+// button falls back to no background of its own.
+const BASE_BACKGROUND = 'var(--icon-button-background, transparent)';
+const useStyles = makeStyles({
+  name: 'IconButton'
+})((theme, props) => {
+  const {
+    color,
+    size,
+    elevation
+  } = props;
+  let cssColor = 'currentColor';
+  if (color === 'cta') {
+    cssColor = theme.components.ctaButton.background;
+  } else if (color !== 'inherit') {
+    cssColor = theme.palette?.[color]?.main ? theme.palette[color].main : theme.palette.primary.main;
+  }
+
+  // Mixing the tint into the base keeps an opaque surface visible underneath. Declaring a
+  // translucent color instead would replace it, since this rule outranks the `surface` class.
+  const hoverBackground = percent => `color-mix(in srgb, ${cssColor} ${percent}%, ${BASE_BACKGROUND})`;
+  return {
+    root: {
+      '--icon-button-color': cssColor,
+      backgroundColor: BASE_BACKGROUND,
+      boxShadow: `var(${theme.vars.components.iconButton.boxShadow}, ${elevation === undefined ? 'none' : resolveElevation(theme, elevation)})`,
+      color: 'var(--icon-button-color)',
+      width: BOX_SIZES[size],
+      height: BOX_SIZES[size],
+      fontSize: theme.components.icon[size],
+      lineHeight: 1,
+      transition: theme.transitions.create(['background-color', 'box-shadow'], {
+        duration: theme.transitions.duration.short
+      }),
+      // A disabled button keeps taking pointer events so that it can show a not-allowed cursor,
+      // which leaves it matching `:hover`.
+      '&:hover:not(:disabled):not([aria-disabled="true"])': {
+        backgroundColor: hoverBackground(HOVER_OVERLAY_PERCENT),
+        ...theme.applyStyles('dark', {
+          backgroundColor: hoverBackground(HOVER_OVERLAY_PERCENT_DARK)
+        }),
+        // Reset on touch devices, it doesn't add specificity
+        '@media (hover: none)': {
+          backgroundColor: BASE_BACKGROUND
+        }
+      },
+      '&:disabled, &[aria-disabled="true"]': {
+        color: theme.palette.action.disabled
+      }
+    },
+    surface: {
+      '--icon-button-background': theme.components.iconButton.background
+    },
+    circular: {
+      borderRadius: '50%'
+    },
+    rounded: {
+      borderRadius: theme.components.iconButton.borderRadius
+    }
+  };
+});
+const IconButtonWithRef = /*#__PURE__*/forwardRef(IconButton);
+IconButtonWithRef.displayName = 'IconButton';
+
+// `forwardRef` erases the generic, so the call signature is restored with a cast. The cast has to
+// land on a named binding rather than on the export itself, or hovering an import of this component
+// resolves to an anonymous function type and shows no documentation at all.
+/**
+ * The IconButton component renders an icon as a click target of its own. Unlike `Button` it carries
+ * no label, so it sizes itself to a square hit area and takes its accessible name from `aria-label`.
+ */
+const IconButtonComponent = IconButtonWithRef;
+export default IconButtonComponent;

package/components/v2/IconButton/index.d.ts

@@ -0,0 +1,3 @@
+export { default } from './IconButton';
+export type { IconButtonOwnProps, IconButtonProps, IconButtonSize } from './IconButton';
+//# sourceMappingURL=index.d.ts.map

package/components/v2/IconButton/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../components/v2/IconButton/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/components/v2/IconButton/index.js

@@ -0,0 +1 @@
+export { default } from "./IconButton";

package/components/v2/index.d.ts

@@ -1,5 +1,6 @@
 export { default as ButtonBase, type ButtonBaseProps } from './ButtonBase';
 export { default as Button, type ButtonProps } from './Button';
 export { default as ButtonGroup, type ButtonGroupProps } from './ButtonGroup';
+export { default as IconButton, type IconButtonProps, type IconButtonSize } from './IconButton';
 export { default as CircularProgress, type CircularProgressProps } from './CircularProgress';
 //# sourceMappingURL=index.d.ts.map

package/components/v2/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../components/v2/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../components/v2/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,KAAK,WAAW,EAAE,MAAM,UAAU,CAAC;AAC/D,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAChG,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAC"}

package/components/v2/index.js

@@ -1,4 +1,5 @@
 export { default as ButtonBase } from "./ButtonBase";
 export { default as Button } from "./Button";
 export { default as ButtonGroup } from "./ButtonGroup";
+export { default as IconButton } from "./IconButton";
 export { default as CircularProgress } from "./CircularProgress";

package/core/helpers/getFullImageSource.d.ts

@@ -1,5 +1,9 @@
-export function getFullImageSource(src: string, { width, height }?: {
+export function getFullImageSource(src: string | null, { width, height }?: {
     width: number;
     height: number;
+}, settings?: {
+    quality?: number | undefined;
+    fillColor?: string | undefined;
+    fillTransparent?: boolean | undefined;
 }): string;
 //# sourceMappingURL=getFullImageSource.d.ts.map

package/core/helpers/getFullImageSource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getFullImageSource.d.ts","sourceRoot":"","sources":["../../../core/helpers/getFullImageSource.js"],"names":[],"mappings":"AA+CO,wCANI,MAAM,sBAEd;IAA0B,KAAK,EAAvB,MAAM;IACY,MAAM,EAAxB,MAAM;CACd,GAAU,MAAM,CAgDlB"}
+{"version":3,"file":"getFullImageSource.d.ts","sourceRoot":"","sources":["../../../core/helpers/getFullImageSource.js"],"names":[],"mappings":"AAiEO,wCAVI,MAAM,GAAC,IAAI,sBAEnB;IAA0B,KAAK,EAAvB,MAAM;IACY,MAAM,EAAxB,MAAM;CACd,aACA;IAA0B,OAAO;IACP,SAAS;IACR,eAAe;CAC1C,GAAU,MAAM,CAyDlB"}

package/core/helpers/getFullImageSource.js

@@ -5,9 +5,18 @@ import "core-js/modules/web.url.to-json.js";
 import "core-js/modules/web.url-search-params.js";
 import { CONFIGURATION_COLLECTION_CREATE_EXTERNAL_IMAGE_URL } from '@shopgate/engage/core/constants';
 import { configuration } from '@shopgate/engage/core/collections';
-import { getProductImageSettings } from "../../product/helpers";
+import { DEFAULT_IMAGE_FILL_COLOR, DEFAULT_IMAGE_FILL_TRANSPARENT, DEFAULT_IMAGE_QUALITY } from '@shopgate/engage/settings/constants/imageSettings';
 import { getImageFormat } from "./getImageFormat";
 
+/**
+ * The settings applied when the caller passes none.
+ */
+const defaultSettings = {
+  quality: DEFAULT_IMAGE_QUALITY,
+  fillColor: DEFAULT_IMAGE_FILL_COLOR,
+  fillTransparent: DEFAULT_IMAGE_FILL_TRANSPARENT
+};
+
 /**
  * Regex to detect the "fill" query parameter
  */
@@ -43,29 +52,38 @@ const buildUrl = (baseUrl, params = {}) => {
 };
 
 /**
- * Returns the actual url to the image, by adding url parameters with the dimensions for img-cdn
- * @param {string} src Source to the image.
+ * Builds the url that requests an image at a given size. A src that no known image source
+ * recognizes is returned untouched.
+ * @param {string|null} src Source to the image.
  * @param {Object} dimension Dimension of the requested image.
  * @param {number} dimension.width Width in pixels.
  * @param {number} dimension.height Height in pixels.
+ * @param {Object} [settings] Image service settings, as resolved by useImageServiceSettings.
+ * @param {number} [settings.quality] Compression quality.
+ * @param {string} [settings.fillColor] Fill color as a hash free hex, not a CSS color.
+ * @param {boolean} [settings.fillTransparent] Whether transparent areas are filled too.
  * @returns {string}
  */
 export const getFullImageSource = (src, {
   width,
   height
-} = {}) => {
+} = {}, settings = {}) => {
+  const {
+    quality,
+    fillColor,
+    fillTransparent
+  } = {
+    ...defaultSettings,
+    ...settings
+  };
   if (src && src.includes('images.shopgate.services')) {
-    const {
-      fillColor,
-      quality
-    } = getProductImageSettings();
     const format = getImageFormat();
     return buildUrl(src, {
       format,
       width,
       height,
       quality,
-      fill: fillColor.replace('#', '')
+      fill: fillTransparent ? `${fillColor},1` : fillColor
     });
   }
   if (src && src.startsWith('https://img-cdn.shopgate.com') && !src.includes('?')) {
@@ -74,17 +92,14 @@ export const getFullImageSource = (src, {
       h: height,
       q: 70,
       zd: 'resize',
-      fillc: 'FFFFFF'
+      // No transparency flag here - the legacy cdn only understands a plain color.
+      fillc: fillColor
     });
   }
 
   // Check if an extension registered an external image url handler within the config collection.
   const createUrlFn = configuration.get(CONFIGURATION_COLLECTION_CREATE_EXTERNAL_IMAGE_URL);
   if (typeof createUrlFn === 'function') {
-    const {
-      fillColor,
-      quality
-    } = getProductImageSettings();
     const format = getImageFormat();
 
     // Invoke the handler with all relevant parameters.
@@ -92,6 +107,7 @@ export const getFullImageSource = (src, {
       width,
       height,
       fillColor,
+      fillTransparent,
       quality,
       format
     });

package/core/helpers/i18n.d.ts

@@ -40,6 +40,10 @@ export type I18nHelpers = {
      * - Get locale data by path
      */
     getPath: Function;
+    /**
+     * - Check whether a translation key resolves to a value
+     */
+    has: Function;
     /**
      * - Get locale lang code, eg de-DE
      */

package/core/helpers/i18n.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../../../core/helpers/i18n.js"],"names":[],"mappings":"AAyEA;;GAEG;AACH,mBAFU,WAAW,CAEM;AAMpB,oCAFM,MAAM,EAAE,CAQpB"}
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../../../core/helpers/i18n.js"],"names":[],"mappings":"AA4EA;;GAEG;AACH,mBAFU,WAAW,CAEM;AAMpB,oCAFM,MAAM,EAAE,CAQpB"}

package/core/helpers/i18n.js

@@ -13,6 +13,7 @@ import { logger } from '@shopgate/pwa-core/helpers';
  * @property {Function} number - Number translator
  * @property {Function} getSupplementalData - Get Supplemental Data
  * @property {Function} getPath - Get locale data by path
+ * @property {Function} has - Check whether a translation key resolves to a value
  * @property {Function} getLang - Get locale lang code, eg de-DE
  */
 
@@ -50,6 +51,7 @@ const I18n = () => {
       this.number = getNumberFormatter(lang);
       this.getSupplementalData = () => locales.supplementalData || {};
       this.getPath = path => get(locales, path);
+      this.has = path => this.getPath(path) !== undefined;
       this.getLang = () => lang;
       // If component decides to act accordingly this information should be exposed.
       this.ready = true;
@@ -62,6 +64,7 @@ const I18n = () => {
     number: notReadyCb,
     getSupplementalData: notReadyCb,
     getPath: notReadyCb,
+    has: notReadyCb,
     getLang: notReadyCb,
     ready: false
   };

package/core/hooks/events/appEvents.d.ts

@@ -2,82 +2,67 @@
  * Additional options for app event hooks.
  */
 export interface AppEventOptions {
-  /**
-   * When false, no listener is registered.
-   * @default true
-   */
-  enabled?: boolean;
-  /**
-   * When true, the callback is removed after first call.
-   * @default false
-   */
-  once?: boolean;
+    /**
+     * When false, no listener is registered.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * When true, the callback is removed after first call.
+     * @default false
+     */
+    once?: boolean;
 }
-
 /**
  * Extended options for return-from-background hook.
  */
 export interface ReturnFromBackgroundOptions extends AppEventOptions {
-  /**
-   * If true, requires a new background event to re-arm before firing again.
-   * If false, remains armed until disabled or unmounted.
-   * @default true
-   */
-  resetAfterFire?: boolean;
+    /**
+     * If true, requires a new background event to re-arm before firing again.
+     * If false, remains armed until disabled or unmounted.
+     * @default true
+     */
+    resetAfterFire?: boolean;
 }
-
 /**
  * Registers a callback for a given event from the Shopgate app event bus.
  *
  * Automatically unsubscribes on unmount. Can optionally run only once.
- *
  * @param name The event name to subscribe to.
  * @param callback The function to call when the event fires.
  * @param options Additional options.
  */
-export declare function useAppEvent(
-  name: string,
-  callback: () => void,
-  options?: AppEventOptions
-): void;
-
+export declare function useAppEvent(name: string, callback: () => void, options?: AppEventOptions): void;
 /**
- * Registers a callback that fires when the app will enter foreground.
- *
- * Automatically unsubscribes on unmount.
+ * Registers a callback that fires when the app will enter foreground
+ * (`applicationWillEnterForeground`).
  *
+ * Automatically unsubscribes on unmount. Accepts same options as `useAppEvent`.
  * @param callback The callback to run when entering foreground.
  * @param options Additional options.
  */
-export declare function useAppEventOnEnterForeground(
-  callback: () => void,
-  options?: AppEventOptions
-): void;
-
+export declare function useAppEventOnEnterForeground(callback: () => void, options?: AppEventOptions): void;
 /**
- * Registers a callback that fires when the app did enter background.
- *
- * Automatically unsubscribes on unmount.
+ * Registers a callback that fires when the app did enter background
+ * (`applicationDidEnterBackground`).
  *
+ * Automatically unsubscribes on unmount. Accepts same options as `useAppEvent`.
  * @param callback The callback to run when entering background.
  * @param options Additional options.
  */
-export declare function useAppEventOnDidEnterBackground(
-  callback: () => void,
-  options?: AppEventOptions
-): void;
-
+export declare function useAppEventOnDidEnterBackground(callback: () => void, options?: AppEventOptions): void;
 /**
  * Invokes a callback only after the app was first sent to background and then
- * returns to the foreground — i.e. a complete background → foreground cycle.
+ * returns to the foreground - i.e. a complete background to foreground cycle.
  *
  * Common use case: user leaves the app to open system settings and returns, so you
  * can re-check permissions or refresh data.
  *
+ * Internally, this subscribes to both background and foreground events:
+ * - Arms itself when entering background
+ * - Fires on next foreground if armed
  * @param callback The callback to run after returning from background.
  * @param options Additional options.
  */
-export declare function useAppEventOnReturnFromBackground(
-  callback: () => void,
-  options?: ReturnFromBackgroundOptions
-): void;
+export declare function useAppEventOnReturnFromBackground(callback: () => void, options?: ReturnFromBackgroundOptions): void;
+//# sourceMappingURL=appEvents.d.ts.map

package/core/hooks/events/appEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appEvents.d.ts","sourceRoot":"","sources":["../../../../core/hooks/events/appEvents.ts"],"names":[],"mappings":"AAOA;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA4B,SAAQ,eAAe;IAClE;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAkBD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,GAAE,eAAoB,QAiB5F;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,CAAC,EAAE,eAAe,QAE3F;AAED;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,OAAO,CAAC,EAAE,eAAe,QAE9F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,MAAM,IAAI,EACpB,OAAO,GAAE,2BAAgC,QAsB1C"}

package/core/hooks/events/appEvents.js

@@ -2,15 +2,22 @@ import { useEffect, useRef } from 'react';
 import { APP_EVENT_APPLICATION_WILL_ENTER_FOREGROUND, APP_EVENT_APPLICATION_DID_ENTER_BACKGROUND } from '@shopgate/engage/core/constants';
 import { event } from '@shopgate/engage/core/classes';
 
+/**
+ * Additional options for app event hooks.
+ */
+
+/**
+ * Extended options for return-from-background hook.
+ */
+
 /**
  * Returns a stable reference to the given callback, preserving the same function identity
  * across renders, while still always calling the latest version of the callback.
  *
  * Useful when passing callbacks into event listeners or effects so they don't re-subscribe
  * on every render but still access up-to-date props/state.
- *
- * @param {Function} fn The callback function whose latest version should be retained.
- * @returns {Function} A stable function reference that always invokes the latest callback.
+ * @param fn The callback function whose latest version should be retained.
+ * @returns A stable function reference that always invokes the latest callback.
  */
 function useStableCallback(fn) {
   const ref = useRef(fn);
@@ -18,16 +25,14 @@ function useStableCallback(fn) {
   const stable = useRef((...args) => ref.current?.(...args));
   return stable.current;
 }
+
 /**
  * Registers a callback for a given event from the Shopgate app event bus.
  *
  * Automatically unsubscribes on unmount. Can optionally run only once.
- *
- * @param {string} name The event name to subscribe to.
- * @param {Function} callback The function to call when the event fires.
- * @param {Object} [options] Additional options.
- * @param {boolean} [options.enabled=true] When false, no listener is registered.
- * @param {boolean} [options.once=false] When true, the callback is removed after first call.
+ * @param name The event name to subscribe to.
+ * @param callback The function to call when the event fires.
+ * @param options Additional options.
  */
 export function useAppEvent(name, callback, options = {}) {
   const {
@@ -37,7 +42,10 @@ export function useAppEvent(name, callback, options = {}) {
   const latest = useStableCallback(callback);
   useEffect(() => {
     if (!enabled) return undefined;
-    // eslint-disable-next-line require-jsdoc
+
+    /**
+     * Invokes the callback, and unsubscribes again when the event was only wanted once.
+     */
     const handler = () => {
       latest();
       if (once) event.removeCallback(name, handler);
@@ -52,11 +60,8 @@ export function useAppEvent(name, callback, options = {}) {
  * (`applicationWillEnterForeground`).
  *
  * Automatically unsubscribes on unmount. Accepts same options as `useAppEvent`.
- *
- * @param {Function} callback The callback to run when entering foreground.
- * @param {Object} [options] Additional options.
- * @param {boolean} [options.enabled=true] When false, the listener is not registered.
- * @param {boolean} [options.once=false] Remove after first call.
+ * @param callback The callback to run when entering foreground.
+ * @param options Additional options.
  */
 export function useAppEventOnEnterForeground(callback, options) {
   useAppEvent(APP_EVENT_APPLICATION_WILL_ENTER_FOREGROUND, callback, options);
@@ -65,12 +70,10 @@ export function useAppEventOnEnterForeground(callback, options) {
 /**
  * Registers a callback that fires when the app did enter background
  * (`applicationDidEnterBackground`).
- ** Automatically unsubscribes on unmount. Accepts same options as `useAppEvent`.
  *
- * @param {Function} callback The callback to run when entering background.
- * @param {Object} [options] Additional options.
- * @param {boolean} [options.enabled=true] When false, the listener is not registered.
- * @param {boolean} [options.once=false] Remove after first call.
+ * Automatically unsubscribes on unmount. Accepts same options as `useAppEvent`.
+ * @param callback The callback to run when entering background.
+ * @param options Additional options.
  */
 export function useAppEventOnDidEnterBackground(callback, options) {
   useAppEvent(APP_EVENT_APPLICATION_DID_ENTER_BACKGROUND, callback, options);
@@ -78,7 +81,7 @@ export function useAppEventOnDidEnterBackground(callback, options) {
 
 /**
  * Invokes a callback only after the app was first sent to background and then
- * returns to the foreground — i.e. a complete background → foreground cycle.
+ * returns to the foreground - i.e. a complete background to foreground cycle.
  *
  * Common use case: user leaves the app to open system settings and returns, so you
  * can re-check permissions or refresh data.
@@ -86,14 +89,8 @@ export function useAppEventOnDidEnterBackground(callback, options) {
  * Internally, this subscribes to both background and foreground events:
  * - Arms itself when entering background
  * - Fires on next foreground if armed
- *
- * @param {Function} callback The callback to run after returning from background.
- * @param {Object} [options] Additional options.
- * @param {boolean} [options.enabled=true] When false, no listener behavior is active.
- * @param {boolean} [options.once=false] When true, callback fires only for the first cycle.
- * @param {boolean} [options.resetAfterFire=true]
- *        If true, requires a new background event to re-arm before firing again.
- *        If false, remains armed until disabled or unmounted.
+ * @param callback The callback to run after returning from background.
+ * @param options Additional options.
  */
 export function useAppEventOnReturnFromBackground(callback, options = {}) {
   const {