@wix/site-service-lightbox 1.0.4 → 1.0.5

package/README.md

@@ -18,8 +18,8 @@ const lightbox = useService(LightboxDefinition)
 
 type SignupContext = { source: string }
 
-// Open a lightbox page, passing it some context:
-await lightbox.open<SignupContext>({ pageId: 'lightbox-page-id', context: { source: 'signup' } })
+// Open a lightbox by its slug, passing it some context:
+await lightbox.open<SignupContext>({ slug: 'signup', context: { source: 'signup' } })
 
 // In a component rendered inside the lightbox:
 const context = lightbox.getContext<SignupContext>()
@@ -33,8 +33,9 @@ import { LightboxDefinition } from '@wix/site-service-lightbox/definition'
 import { LightboxService } from '@wix/site-service-lightbox/implementations'
 
 createServicesMap().addService(LightboxDefinition, LightboxService, {
-	open: async ({ pageId, context }) => {
-		/* open the lightbox page */
+	open: async (options) => {
+		/* open the lightbox page whose pageUriSEO is options.slug (reject if there is none),
+		   or, for the deprecated form, the lightbox page options.pageId */
 	},
 	close: () => {
 		/* close the open lightbox */
@@ -49,7 +50,7 @@ createServicesMap().addService(LightboxDefinition, LightboxService, {
 
 | Member | Type | Description |
 |---|---|---|
-| `open` | `<TContext = LightboxContext>(options: { pageId: string; context?: TContext }) => Promise<void>` | Opens the lightbox page `pageId` with `context`. Returns the host's promise. |
+| `open` | `<TContext = LightboxContext>(options: { slug: string; context?: TContext } \| { pageId: string; context?: TContext }) => Promise<void>` | Opens the lightbox with `context`. Pass `slug` (the lightbox page's `pageUriSEO`), or the deprecated `pageId`, not both. Returns the host's promise. |
 | `close` | `() => void` | Closes the currently open lightbox. Fire-and-forget: returns nothing, even if the host's close is async. |
 | `getContext` | `<TContext = LightboxContext>() => TContext` | Returns the context the open lightbox was opened with. |
 
@@ -74,3 +75,5 @@ export type ILightboxServiceConfig = {
 
 - `open`, `close`, `getContext` — the host's implementations. The service calls them on each use.
   All three are required; the service has no fallback behavior.
+- `open` receives the options unchanged, with either `slug` or `pageId`, and must handle both. It should
+  reject when no lightbox has the slug.

package/cjs/build/definition/index.d.ts

@@ -5,9 +5,27 @@ import type { ServiceDefinition } from '@wix/services-definitions';
  */
 export type LightboxContext = unknown;
 /**
- * Options for `open()`, with the popup to open and the value to open it with.
+ * Options for `open()` that identify the popup by its slug.
  */
-export type LightboxOpenOptions<TContext = LightboxContext> = {
+export type LightboxOpenBySlugOptions<TContext = LightboxContext> = {
+    /**
+     * Slug of the popup to open, the `pageUriSEO` of the popup page.
+     *
+     * @exampleValue 'quick-view'
+     */
+    slug: string;
+    pageId?: never;
+    /**
+     * Information to pass to the popup. Components inside the popup read it with `getContext()`.
+     *
+     * @exampleValue `{ "productId": "spring-jacket" }`
+     */
+    context?: TContext;
+};
+/**
+ * Options for `open()` that identify the popup by its page ID.
+ */
+export type LightboxOpenByPageIdOptions<TContext = LightboxContext> = {
     /**
      * Page ID of the popup to open.
      *
@@ -16,9 +34,12 @@ export type LightboxOpenOptions<TContext = LightboxContext> = {
      *
      * It isn't the page's `appPageId`.
      *
+     * @deprecated Use `slug` instead.
+     *
      * @exampleValue 'k4q7s'
      */
     pageId: string;
+    slug?: never;
     /**
      * Information to pass to the popup. Components inside the popup read it with `getContext()`.
      *
@@ -26,10 +47,16 @@ export type LightboxOpenOptions<TContext = LightboxContext> = {
      */
     context?: TContext;
 };
+/**
+ * Options for `open()`, with the popup to open and the value to open it with. Specify the popup by
+ * `slug`. Specifying it by `pageId` still works, but is deprecated.
+ */
+export type LightboxOpenOptions<TContext = LightboxContext> = LightboxOpenBySlugOptions<TContext> | LightboxOpenByPageIdOptions<TContext>;
 /**
  * Values the host supplies when it creates the service.
  */
 export type ILightboxServiceConfig = {
+    /** Opens the popup with the slug or the page ID, and rejects when no popup has that slug. */
     open: (options: LightboxOpenOptions) => Promise<void>;
     close: () => void;
     getContext: () => LightboxContext;
@@ -45,8 +72,11 @@ export interface ILightboxService {
      * and its context is replaced with the `context` you specify, or with `undefined` if you omit
      * `context`.
      *
+     * Specify the popup by `slug`. Specifying it by `pageId` is deprecated, but still works.
+     *
      * @param options Options for opening the popup.
-     * @returns Promise that resolves with no value once the popup is open.
+     * @returns Promise that resolves with no value once the popup is open. It rejects when the popup
+     * can't be opened, for example when no popup has the `slug` you specify.
      *
      * @example Open a quick view popup from a button
      * ```tsx
@@ -63,7 +93,7 @@ export interface ILightboxService {
      *     const openQuickView = () => {
      *         setFailed(false)
      *         lightboxService
-     *             .open<QuickViewContext>({ pageId: 'k4q7s', context: { productId } })
+     *             .open<QuickViewContext>({ slug: 'quick-view', context: { productId } })
      *             .catch(() => setFailed(true))
      *     }
      *
@@ -75,29 +105,6 @@ export interface ILightboxService {
      *     )
      * }
      * ```
-     *
-     * @example Open an app's popup found in the pages service
-     * ```ts
-     * // pagesService and lightboxService are resolved from @wix/site-service-pages and
-     * // @wix/site-service-lightbox, as in the first example. QuickViewContext is your own type for the
-     * // popup's context.
-     * function findPopupPageId(appPageId: string): string | undefined {
-     *     const entry = Object.entries(pagesService.pages).find(([, page]) => page.popup && page.appPageId === appPageId)
-     *
-     *     // The page ID is the map key, not the page's appPageId.
-     *     return entry?.[0]
-     * }
-     *
-     * async function openAppPopup(appPageId: string, context: QuickViewContext) {
-     *     const pageId = findPopupPageId(appPageId)
-     *     if (!pageId) {
-     *         return false
-     *     }
-     *
-     *     await lightboxService.open({ pageId, context })
-     *     return true
-     * }
-     * ```
      */
     open<TContext = LightboxContext>(options: LightboxOpenOptions<TContext>): Promise<void>;
     /**

package/cjs/build/definition/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/definition/index.ts"],"names":[],"mappings":";;;AAAA,oEAAyD;AAiM5C,QAAA,kBAAkB,GAAG,IAAA,oCAAa,EAA2C,4BAA4B,CAAC,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/definition/index.ts"],"names":[],"mappings":";;;AAAA,oEAAyD;AA4M5C,QAAA,kBAAkB,GAAG,IAAA,oCAAa,EAA2C,4BAA4B,CAAC,CAAA"}

package/cjs/build/types/index.d.ts

@@ -1 +1 @@
-export type { ILightboxService, ILightboxServiceConfig, ILightboxDefinition, LightboxContext, LightboxOpenOptions, } from '../definition';
+export type { ILightboxService, ILightboxServiceConfig, ILightboxDefinition, LightboxContext, LightboxOpenOptions, LightboxOpenBySlugOptions, LightboxOpenByPageIdOptions, } from '../definition';

package/dist/definition/index.d.ts

@@ -5,9 +5,27 @@ import type { ServiceDefinition } from '@wix/services-definitions';
  */
 export type LightboxContext = unknown;
 /**
- * Options for `open()`, with the popup to open and the value to open it with.
+ * Options for `open()` that identify the popup by its slug.
  */
-export type LightboxOpenOptions<TContext = LightboxContext> = {
+export type LightboxOpenBySlugOptions<TContext = LightboxContext> = {
+    /**
+     * Slug of the popup to open, the `pageUriSEO` of the popup page.
+     *
+     * @exampleValue 'quick-view'
+     */
+    slug: string;
+    pageId?: never;
+    /**
+     * Information to pass to the popup. Components inside the popup read it with `getContext()`.
+     *
+     * @exampleValue `{ "productId": "spring-jacket" }`
+     */
+    context?: TContext;
+};
+/**
+ * Options for `open()` that identify the popup by its page ID.
+ */
+export type LightboxOpenByPageIdOptions<TContext = LightboxContext> = {
     /**
      * Page ID of the popup to open.
      *
@@ -16,9 +34,12 @@ export type LightboxOpenOptions<TContext = LightboxContext> = {
      *
      * It isn't the page's `appPageId`.
      *
+     * @deprecated Use `slug` instead.
+     *
      * @exampleValue 'k4q7s'
      */
     pageId: string;
+    slug?: never;
     /**
      * Information to pass to the popup. Components inside the popup read it with `getContext()`.
      *
@@ -26,10 +47,16 @@ export type LightboxOpenOptions<TContext = LightboxContext> = {
      */
     context?: TContext;
 };
+/**
+ * Options for `open()`, with the popup to open and the value to open it with. Specify the popup by
+ * `slug`. Specifying it by `pageId` still works, but is deprecated.
+ */
+export type LightboxOpenOptions<TContext = LightboxContext> = LightboxOpenBySlugOptions<TContext> | LightboxOpenByPageIdOptions<TContext>;
 /**
  * Values the host supplies when it creates the service.
  */
 export type ILightboxServiceConfig = {
+    /** Opens the popup with the slug or the page ID, and rejects when no popup has that slug. */
     open: (options: LightboxOpenOptions) => Promise<void>;
     close: () => void;
     getContext: () => LightboxContext;
@@ -45,8 +72,11 @@ export interface ILightboxService {
      * and its context is replaced with the `context` you specify, or with `undefined` if you omit
      * `context`.
      *
+     * Specify the popup by `slug`. Specifying it by `pageId` is deprecated, but still works.
+     *
      * @param options Options for opening the popup.
-     * @returns Promise that resolves with no value once the popup is open.
+     * @returns Promise that resolves with no value once the popup is open. It rejects when the popup
+     * can't be opened, for example when no popup has the `slug` you specify.
      *
      * @example Open a quick view popup from a button
      * ```tsx
@@ -63,7 +93,7 @@ export interface ILightboxService {
      *     const openQuickView = () => {
      *         setFailed(false)
      *         lightboxService
-     *             .open<QuickViewContext>({ pageId: 'k4q7s', context: { productId } })
+     *             .open<QuickViewContext>({ slug: 'quick-view', context: { productId } })
      *             .catch(() => setFailed(true))
      *     }
      *
@@ -75,29 +105,6 @@ export interface ILightboxService {
      *     )
      * }
      * ```
-     *
-     * @example Open an app's popup found in the pages service
-     * ```ts
-     * // pagesService and lightboxService are resolved from @wix/site-service-pages and
-     * // @wix/site-service-lightbox, as in the first example. QuickViewContext is your own type for the
-     * // popup's context.
-     * function findPopupPageId(appPageId: string): string | undefined {
-     *     const entry = Object.entries(pagesService.pages).find(([, page]) => page.popup && page.appPageId === appPageId)
-     *
-     *     // The page ID is the map key, not the page's appPageId.
-     *     return entry?.[0]
-     * }
-     *
-     * async function openAppPopup(appPageId: string, context: QuickViewContext) {
-     *     const pageId = findPopupPageId(appPageId)
-     *     if (!pageId) {
-     *         return false
-     *     }
-     *
-     *     await lightboxService.open({ pageId, context })
-     *     return true
-     * }
-     * ```
      */
     open<TContext = LightboxContext>(options: LightboxOpenOptions<TContext>): Promise<void>;
     /**

package/dist/definition/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/definition/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAiMzD,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAA2C,4BAA4B,CAAC,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/definition/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AA4MzD,MAAM,CAAC,MAAM,kBAAkB,GAAG,aAAa,CAA2C,4BAA4B,CAAC,CAAA"}

package/dist/types/index.d.ts

@@ -1 +1 @@
-export type { ILightboxService, ILightboxServiceConfig, ILightboxDefinition, LightboxContext, LightboxOpenOptions, } from '../definition';
+export type { ILightboxService, ILightboxServiceConfig, ILightboxDefinition, LightboxContext, LightboxOpenOptions, LightboxOpenBySlugOptions, LightboxOpenByPageIdOptions, } from '../definition';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/site-service-lightbox",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "license": "UNLICENSED",
   "files": [
     "dist",
@@ -77,5 +77,5 @@
       ]
     }
   },
-  "falconPackageHash": "199bdec5995c3f1e1d582da1111ff32fbabbf9bbc47a13c567dd1593"
+  "falconPackageHash": "7938722bcf6840d5f3e7bd2f8f496f385169197d92de8fe79e96c6d9"
 }

package/src/definition/index.ts

@@ -8,9 +8,28 @@ import type { ServiceDefinition } from '@wix/services-definitions'
 export type LightboxContext = unknown
 
 /**
- * Options for `open()`, with the popup to open and the value to open it with.
+ * Options for `open()` that identify the popup by its slug.
  */
-export type LightboxOpenOptions<TContext = LightboxContext> = {
+export type LightboxOpenBySlugOptions<TContext = LightboxContext> = {
+	/**
+	 * Slug of the popup to open, the `pageUriSEO` of the popup page.
+	 *
+	 * @exampleValue 'quick-view'
+	 */
+	slug: string
+	pageId?: never
+	/**
+	 * Information to pass to the popup. Components inside the popup read it with `getContext()`.
+	 *
+	 * @exampleValue `{ "productId": "spring-jacket" }`
+	 */
+	context?: TContext
+}
+
+/**
+ * Options for `open()` that identify the popup by its page ID.
+ */
+export type LightboxOpenByPageIdOptions<TContext = LightboxContext> = {
 	/**
 	 * Page ID of the popup to open.
 	 *
@@ -19,9 +38,12 @@ export type LightboxOpenOptions<TContext = LightboxContext> = {
 	 *
 	 * It isn't the page's `appPageId`.
 	 *
+	 * @deprecated Use `slug` instead.
+	 *
 	 * @exampleValue 'k4q7s'
 	 */
 	pageId: string
+	slug?: never
 	/**
 	 * Information to pass to the popup. Components inside the popup read it with `getContext()`.
 	 *
@@ -30,10 +52,19 @@ export type LightboxOpenOptions<TContext = LightboxContext> = {
 	context?: TContext
 }
 
+/**
+ * Options for `open()`, with the popup to open and the value to open it with. Specify the popup by
+ * `slug`. Specifying it by `pageId` still works, but is deprecated.
+ */
+export type LightboxOpenOptions<TContext = LightboxContext> =
+	| LightboxOpenBySlugOptions<TContext>
+	| LightboxOpenByPageIdOptions<TContext>
+
 /**
  * Values the host supplies when it creates the service.
  */
 export type ILightboxServiceConfig = {
+	/** Opens the popup with the slug or the page ID, and rejects when no popup has that slug. */
 	open: (options: LightboxOpenOptions) => Promise<void>
 	close: () => void
 	getContext: () => LightboxContext
@@ -50,8 +81,11 @@ export interface ILightboxService {
 	 * and its context is replaced with the `context` you specify, or with `undefined` if you omit
 	 * `context`.
 	 *
+	 * Specify the popup by `slug`. Specifying it by `pageId` is deprecated, but still works.
+	 *
 	 * @param options Options for opening the popup.
-	 * @returns Promise that resolves with no value once the popup is open.
+	 * @returns Promise that resolves with no value once the popup is open. It rejects when the popup
+	 * can't be opened, for example when no popup has the `slug` you specify.
 	 *
 	 * @example Open a quick view popup from a button
 	 * ```tsx
@@ -68,7 +102,7 @@ export interface ILightboxService {
 	 *     const openQuickView = () => {
 	 *         setFailed(false)
 	 *         lightboxService
-	 *             .open<QuickViewContext>({ pageId: 'k4q7s', context: { productId } })
+	 *             .open<QuickViewContext>({ slug: 'quick-view', context: { productId } })
 	 *             .catch(() => setFailed(true))
 	 *     }
 	 *
@@ -80,29 +114,6 @@ export interface ILightboxService {
 	 *     )
 	 * }
 	 * ```
-	 *
-	 * @example Open an app's popup found in the pages service
-	 * ```ts
-	 * // pagesService and lightboxService are resolved from @wix/site-service-pages and
-	 * // @wix/site-service-lightbox, as in the first example. QuickViewContext is your own type for the
-	 * // popup's context.
-	 * function findPopupPageId(appPageId: string): string | undefined {
-	 *     const entry = Object.entries(pagesService.pages).find(([, page]) => page.popup && page.appPageId === appPageId)
-	 *
-	 *     // The page ID is the map key, not the page's appPageId.
-	 *     return entry?.[0]
-	 * }
-	 *
-	 * async function openAppPopup(appPageId: string, context: QuickViewContext) {
-	 *     const pageId = findPopupPageId(appPageId)
-	 *     if (!pageId) {
-	 *         return false
-	 *     }
-	 *
-	 *     await lightboxService.open({ pageId, context })
-	 *     return true
-	 * }
-	 * ```
 	 */
 	open<TContext = LightboxContext>(options: LightboxOpenOptions<TContext>): Promise<void>
 	/**

package/src/types/index.ts

@@ -4,4 +4,6 @@ export type {
 	ILightboxDefinition,
 	LightboxContext,
 	LightboxOpenOptions,
+	LightboxOpenBySlugOptions,
+	LightboxOpenByPageIdOptions,
 } from '../definition'