@depict-ai/react-ui 1.5.20 → 2.0.1

package/server/latest/index.d.ts

@@ -1,20 +1,503 @@
-import { ReactElement } from "react";
 import { DPC } from "@depict-ai/dpc/latest";
-import { ExclusiveId, fetchDepictRecommendations, ImagePlaceholder as _ImagePlaceholder1, TextPlaceholder as _TextPlaceholder1 } from "@depict-ai/ui/latest";
-import { Display } from "@depict-ai/utilishared/latest";
+import React, { PropsWithChildren, ReactNode, ReactPortal, ReactElement } from "react";
+import { BaseProviderConfig, BaseSearchProviderConfig, BaseCategoryProviderConfig, ModernDisplayWithPageUrl, BaseProductListingConfig, BaseSearchPageConfig, BaseCategoryPageConfig, CategoryTitle, embedded_num_products, ImagePlaceholder as _ImagePlaceholder1, TextPlaceholder as _TextPlaceholder1, ExclusiveId, fetchDepictRecommendations } from "@depict-ai/ui/latest";
+import { Locale } from "@depict-ai/ui/locales/latest";
+import { Display, ModernDisplay } from "@depict-ai/utilishared/latest";
+export const version = "2.0.1";
+interface UsePerformanceClientReturn {
+  dpc: DPC;
+}
+/**
+ * Hook used to access the Depict Performance Client.
+ * Calls on the returned DPC instance can not be done server side.
+ * @example
+ * Send an add-to-cart event
+ * ```tsx
+ * import { useEffect } from "react";
+ * import { usePerformanceClient } from "@depict-ai/react-ui";
+ *
+ * const ProductPage = ({ productId }) => {
+ *   const { dpc } = usePerformanceClient();
+ *
+ *   useEffect(() => {
+ *     dpc.setProductId(productId);
+ *   }, [dpc, productId]);
+ *
+ *   return <div>Showing product {productId}</div>;
+ * }
+ * ```
+ * @returns {UsePerformanceClientReturn}
+}
+ */
+export const usePerformanceClient: () => UsePerformanceClientReturn;
+/**
+ * relativeUrl: The relative url to navigate to.
+ * replace: Whether to replace the current url or push a new one.
+ */
+type NavigateFunction = (relativeUrl: string, options: {
+  replace: boolean;
+  scroll: boolean;
+}) => void;
+/**
+ * The config for the DepictProvider.
+ */
+type ProviderConfig<OriginalDisplay extends Display, OutputDisplay extends ModernDisplay | never> = BaseProviderConfig<OriginalDisplay, OutputDisplay> & {
+  /**
+   * The function to use for navigating to a new page.
+   * This function will be used internally by our components to navigate.
+   *
+   * You don't need to provide any in a Next.js context.
+   *
+   * @param relativeUrl - The relative url to navigate to.
+   *
+   * @example
+   * Here is how you would use it with react-router, @reach/router, Gatsby or similar.
+   * ```tsx
+   * import { DepictProvider, Navigation } from "@depict-ai/react-ui";
+   * import { useNavigate } from "react-router-dom";
+   * // import { navigate } from "gatsby";
+   *
+   * function Router() {
+   *   const navigate = useNavigate();
+   *   return (
+   *     <DepictProvider
+   *       merchant="houdini"
+   *       market="en-de"
+   *       navigateFunction={navigate}
+   *       search={{
+   *         searchPagePath: "/search",
+   *       }}
+   *     >
+   *       <Routes>[...]</Routes>
+   *     </DepictProvider>
+   *   );
+   * }
+   * ```
+   * @example
+   * If you're using another library, you can define your own navigate function, that's compatible with the `NavigateFunction` type.
+   * ```tsx
+   * const navigateFunction = (relativeUrl: string, { replace }) => {
+   *  router.push(relativeUrl, { replace });
+   * };
+   * ```
+   */
+  navigateFunction?: NavigateFunction;
+  /**
+   * The locale to use for the Depict components.
+   * @default en
+   */
+  locale?: Locale;
+  /**
+   * Unique ID of the currently logged in user, if applicable.
+   */
+  userId?: string;
+  /**
+   * Options that are required for search functionality.
+   */
+  search?: BaseSearchProviderConfig;
+  /**
+   * Options that can be used for category page functionality.
+   */
+  category?: BaseCategoryProviderConfig;
+};
+/**
+ * The DepictProvider is a wrapper component that should be used to wrap any component that uses Depict components.
+ *
+ * Make sure it's mounted on every page where the search modal should be available.
+ *
+ * @param props -  The props for the DepictProvider.
+ *
+ * @example
+ * ```tsx
+ *  const App = () => { *
+ *    return (
+ *      <DepictProvider
+ *        merchant="YOUR_MERCHANT"
+ *        market="YOUR_MARKET"
+ *        search={{
+ *          searchPagePath: "/search",
+ *        }}
+ *      >
+ *        <App />
+ *      </DepictProvider>
+ *    );
+ * };
+ * ```
+ * @returns {JSX.Element} The DepictProvider.
+ */
+export function DepictProvider<InputDisplay extends Display, OutputDisplay extends ModernDisplay | never = InputDisplay extends ModernDisplay ? ModernDisplayWithPageUrl<InputDisplay> : never>(props: PropsWithChildren<ProviderConfig<InputDisplay, OutputDisplay>>): import("react").FunctionComponentElement<{
+  children?: import("react").ReactNode;
+}>;
+/**
+ * A component used to align other Depict components to.
+ * @example
+ * Align the search modal
+ * ```tsx
+ * import React from "react";
+ * import { ComponentAligner, useSearchModal } from "@depict-ai/react-ui";
+ *
+ * const App = () => {
+ *   const ref = React.createRef();
+ *
+ *   const { open } = useSearchModal({
+ *     location: "aligned",
+ *     alignerRef: ref,
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <ComponentAligner ref={ref} />
+ *       <button onClick={open}>Open</button>
+ *     </div>
+ *   );
+ * };
+ * ```
+ * @returns {JSX.Element}
+ */
+export const ComponentAligner: import("react").ForwardRefExoticComponent<import("react").RefAttributes<unknown>>;
+interface PLPConfig<T extends Display> extends BaseProductListingConfig {
+  /**
+   * The product card to use for rendering products.
+   */
+  productCard: DepictProductCard<T>;
+}
+/**
+ * The Depict product card props.
+ */
+export interface DepictProductCardProps<T extends Display> {
+  /** The display data to render. */
+  display: T | null;
+}
+/**
+ * Depict product card to use for rendering products.
+ */
+export type DepictProductCard<T extends Display> = (props: DepictProductCardProps<T>) => ReactNode;
+interface SearchPageConfig<T extends Display> extends BaseSearchPageConfig, PLPConfig<T> {
+  /**
+   * When using multiple search instances on the same page, you need to set a unique stateKey for each one. We recommend using an incrementing number, such as "1", "2", "3", etc. To associate a modal with a SearchPage keyed component, set the same stateKey on both. If no stateKey is provided, the "default" instance will be used.
+   */
+  stateKey?: string;
+}
+/**
+ * SearchPage is a component that renders a Depict search results page.
+ * @param props - The props for the search page. Go to definition for more info.
+ *
+ * @example
+ * ```tsx
+ * import { DepictProductCard, ImagePlaceholder, Display, SearchPage } from '@depict-ai/react-ui'
+ *
+ * function Search() {
+ *    return <SearchPage productCard={MyCustomSearchProductCard} />
+ * }
+ *
+ * interface MyCustomDisplay extends Display {}
+ *
+ * export const MyCustomSearchProductCard: DepictProductCard<MyCustomDisplay> = ({
+ *   display,
+ * }) => {
+ *   if (!display) {
+ *     return <ImagePlaceholder aspectRatio={3 / 4} />
+ *   }
+ *
+ *   return (
+ *     <>
+ *       <MyCustomProductCard
+ *         product={{
+ *           id: display.product_id,
+ *           name: display.title,
+ *           description: display.title,
+ *           images: [{ url: display.image_url }],
+ *           price: {
+ *             value: display.sale_price,
+ *           },
+ *         }}
+ *       />
+ *     </>
+ *   )
+ * }
+ *
+ * ```
+ */
+export function SearchPage<OriginalDisplay extends Display, OutputDisplay extends ModernDisplay | never>(props: SearchPageConfig<[OutputDisplay] extends [never] ? OriginalDisplay : ModernDisplayWithPageUrl<OutputDisplay>>): import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+interface CategoryPageConfig<T extends Display> extends BaseCategoryPageConfig, PLPConfig<T> {
+  /**
+   * The category id to show.
+   */
+  categoryId: string;
+  /**
+   * categoryTitlePlugin is an optional plugin that can be used to customize the title of the category page.
+   * @default CategoryTitle
+   *
+   * @example
+   * ```tsx
+   * <CategoryPage categoryId="jeans" productCard={MyCustomCategoryProductCard}  categoryTitlePlugin={EmbeddedNumProducts} />
+   * ```
+   */
+  categoryTitlePlugin?: typeof CategoryTitle | typeof embedded_num_products;
+  /**
+   * Whether this page is a collection or a category. If not specified it will be inferred as described in the docs https://docs.depict.ai/reference/category-sdk/specifying-listing-type-in-the-category-page-sdk
+   */
+  listingType?: "collection" | "category";
+  /**
+   * When using multiple CategoryPage components on the same page, you need to set a unique stateKey for each one. We recommend using an incrementing number, such as "1", "2", "3", etc. To associate a certain BreadCrumbs or QuickLinks component with a certain CategoryPage component, set the same stateKey on both.
+   */
+  stateKey?: string;
+}
+/**
+ * CategoryPage is a component that renders a Depict category page. Go to definition on the props for more info.
+ * @param props the props for the category page.
+ *
+ * @example
+ * ```tsx
+ * import { DepictProductCard, ImagePlaceholder, Display, CategoryPage } from '@depict-ai/react-ui'
+ *
+ * function Category() {
+ *  return <CategoryPage categoryId="jeans" productCard={MyCustomCategoryProductCard} />
+ * }
+ *
+ * interface MyCustomDisplay extends Display {}
+ *
+ * export const MyCustomCategoryProductCard: DepictProductCard<MyCustomDisplay> = ({
+ *   display,
+ * }) => {
+ *   if (!display) {
+ *     return <ImagePlaceholder aspectRatio={3 / 4} />
+ *   }
+ *
+ *   return (
+ *     <>
+ *       <MyCustomProductCard
+ *         product={{
+ *           id: display.product_id,
+ *           name: display.title,
+ *           description: display.title,
+ *           images: [{ url: display.image_url }],
+ *           price: {
+ *             value: display.sale_price,
+ *           },
+ *         }}
+ *       />
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export function CategoryPage<OriginalDisplay extends Display, OutputDisplay extends ModernDisplay | never>(props: CategoryPageConfig<[OutputDisplay] extends [never] ? OriginalDisplay : ModernDisplayWithPageUrl<OutputDisplay>>): import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+/**
+ * BreadCrumbs is the "trail" in the header of a category page.
+ * @property stateKey - When using multiple CategoryPage components on the same page, you need to set a unique stateKey for each one. To associate a certain BreadCrumbs component with a certain CategoryPage component, set the same stateKey on both.
+ */
+export function BreadCrumbs(react_props: {
+  stateKey?: string | undefined;
+}): import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+/**
+ * QuickLinks is a component enabling the user to go sideways and downwards in the category tree.
+ * @property stateKey - When using multiple CategoryPage components on the same page, you need to set a unique stateKey for each one. To associate a certain QuickLinks component with a certain CategoryPage component, set the same stateKey on both.
+ */
+export function QuickLinks(react_props?: {
+  stateKey?: string | undefined;
+}): import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+/**
+ * A placeholder that can be used instead of an image or other block of content while it's loading.
+ * The placeholder has `display:block`, meaning it will create a new "row" in the layout for itself. Can be used either for images with a defined aspect ratio (ContainedImage) or blocks.
+ * @property aspectRatio if aspectRatio is defined the placeholder will be in "image mode" and fill out the available width and then adjust the height according to the aspectRatio
+ * @property width If width and height is set, the defined width and height will be used.
+ * @property height If width and height is set, the defined width and height will be used.
+ * @property class extra classes to add to the placeholder
+ * @property style extra styles to add to the placeholder
+ */
+export const ImagePlaceholder: React.FC<Parameters<typeof _ImagePlaceholder1>[0] & {
+  className?: string;
+}>;
+/**
+ * A Placeholder to use instead of some text, while it's loading. This is the inline version, meant to be embedded into sentences (or exist instead of them), etc.
+ * If you want a block version, use `ImagePlaceholder` with `width`and `height` set instead.
+ * @property height height of the placeholder. Set to `1em` by default.
+ * @property width width of the placeholder. For specific number of characters use `ch`, ex: `width="7ch"`
+ * @property className extra classes to add to the placeholder
+ * @property style extra styles to add to the placeholder
+ */
+export const TextPlaceholder: React.FC<Parameters<typeof _TextPlaceholder1>[0] & {
+  className?: string;
+}>;
+interface RecommendationConfig<T extends Display> extends BaseProductListingConfig {
+  /**
+   * A promise containing the recommendations to render, see https://docs.depict.ai/api-guide/recommendations/api-client/fetching
+   */
+  recommendations: Promise<T[]>;
+  /**
+   * The product card function to use for rendering products.
+   */
+  productCard: DepictProductCard<T>;
+}
+interface RecommendationGridConfig<T extends Display> extends RecommendationConfig<T> {
+  maxRows?: number;
+  viewMoreButton?: {
+    text: string;
+    startRows?: number;
+    rowsPerClick?: number;
+  };
+}
+declare function SolidRecommendationWrapper<T extends Display>(props: RecommendationGridConfig<T>, set_portals: (portals: ReactPortal[]) => void): HTMLDivElement;
+interface RecommendationSliderConfig<T extends Display> extends RecommendationConfig<T> {
+  viewMoreButton?: {
+    text: string;
+    startRows?: number;
+    rowsPerClick?: number;
+  };
+}
+/**
+ * Renders a slider of the provided products
+ * @param recommendations a promise resolving to an array of displays to render
+ * @param productCard a function that renders a product card or a placeholder for one
+ * @param columnsAtSize the number of columns to show at each media breakpoint
+ * @param gridSpacing the spacing between the product cards
+ */
+export function RecommendationSlider<T extends Display>(props: Parameters<typeof SolidRecommendationSliderWrapper<T>>[0]): import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+declare function SolidRecommendationSliderWrapper<T extends Display>(props: RecommendationSliderConfig<T>, set_portals: (portals: ReactPortal[]) => void): HTMLDivElement;
+/**
+ * Renders a product grid of the provided products
+ * @param recommendations a promise resolving to an array of displays to render
+ * @param productCard a function that renders a product card or a placeholder for one
+ * @param columnsAtSize the number of columns to show at each media breakpoint
+ * @param gridSpacing the spacing between the product cards
+ * @param maxRows the maximum number of rows to show.
+ * @param viewMoreButton optional configuration for the view more button. If unset, all products will be shown by default. Otherwise, a view more button with the given text will be shown. With the properties startRows and rowsPerClick, you can configure how many rows should be shown initially and how many rows should be added on each click.
+ */
+export function RecommendationGrid<T extends Display>(props: Parameters<typeof SolidRecommendationWrapper<T>>[0]): import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+/**
+ * Parameters to configure the search modal.
+ */
+interface UseSearchModalParams {
+  /**
+   * How the modal should be opened.
+   * Will default to "centered" if nothing else is specified.
+   * - "centered" - The modal will be opened in the center of the screen.
+   * - "aligned" - The modal will be opened aligned to the alignerRef element.
+   */
+  location?: ModalLocation;
+  /**
+   * The ref to the element that the modal should be aligned to.
+   * This is only used when location is "aligned".
+   * @default undefined
+   * @example
+   * ```tsx
+      import React from "react";
+      import { ComponentAligner, useSearchModal } from "@depict-ai/react-ui";
+         const App = () => {
+        const ref = React.createRef();
+           const { open } = useSearchModal({
+          location: "aligned",
+          alignerRef: ref,
+        });
+           return (
+          <div>
+            <ComponentAligner ref={ref} />
+            <button onClick={open}>Open</button>
+          </div>
+        );
+      };
+   * ```
+   */
+  alignerRef?: React.RefObject<HTMLElement>;
+  /**
+   * When using multiple search instances on the same page, you need to set a unique stateKey for each one. We recommend using an incrementing number, such as "1", "2", "3", etc. To associate a modal with a SearchPage keyed component, set the same stateKey on both. If no stateKey is provided, the "default" instance will be used.
+   */
+  stateKey?: string;
+}
 type OpenModal = () => void;
+/**
+ * How the modal should be opened.
+ */
+type ModalLocation = "centered" | "aligned";
 interface UseSearchModalReturn {
   open: OpenModal;
 }
+/**
+ * Hook used to open the search modal.
+ * @example
+ * Open a centered modal:
+ * ```tsx
+ * import React from "react";
+ * import { useSearchModal } from "@depict-ai/react-ui";
+ *
+ * const App = () => {
+ *   const { open } = useSearchModal({
+ *     location: "centered",
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={open}>Open</button>
+ *     </div>
+ *   );
+ * };
+ * ```
+ * @returns {UseSearchModalReturn}
+ */
+export function useSearchModal(params?: UseSearchModalParams): UseSearchModalReturn;
+interface SearchFieldProps {
+  /**
+   * A reference to the DOM element that the modal should be aligned to.
+   *
+   * The top of the modal will be aligned to the top of the element.
+   *
+   * The height of the search field in the modal will be the same as the height of the element.
+   * If not provided, the modal will be aligned to the search field itself.
+   */
+  alignerRef?: React.RefObject<HTMLElement>;
+  /**
+   * When using multiple search instances on the same page, you need to set a unique stateKey for each one. We recommend using an incrementing number, such as "1", "2", "3", etc. To associate a modal with a SearchPage keyed component, set the same stateKey on both. If no stateKey is provided, the "default" instance will be used.
+   */
+  stateKey?: string;
+}
 interface UseSearchFieldReturn {
   /**
    * A React component that renders the search field.
    */
   SearchField: () => ReactElement;
 }
-interface UsePerformanceClientReturn {
-  dpc: DPC;
-}
+/**
+ * Hook used to configure the Depict search field.
+ * @example
+ * Render a search field that opens a modal aligned to the search field itself:
+ * ```tsx
+ * import React from "react";
+ * import { useSearchField } from "@depict-ai/react-ui";
+ *
+ * const App = () => {
+ *   const { SearchField } = useSearchField();
+ *
+ *   return (
+ *     <div>
+ *       <SearchField />
+ *     </div>
+ *   );
+ * };
+ * ```
+ * @example
+ * Render a search field that opens a modal aligned another DOM element:
+ * ```tsx
+ * import React from "react";
+ * import { ComponentAligner, useSearchField } from "@depict-ai/react-ui";
+ *
+ * const App = () => {
+ *   const ref = useRef(null);
+ *   const { SearchField } = useSearchField({
+ *     alignerRef: ref
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <ComponentAligner ref={ref} />
+ *       <SearchField />
+ *     </div>
+ *   );
+ * };
+ * ```
+ * @returns {UseSearchFieldReturn}
+ */
+export const useSearchField: (props?: SearchFieldProps) => UseSearchFieldReturn;
 type FetchRecsOptions = Omit<Parameters<typeof fetchDepictRecommendations>[0], "merchant" | "market" | "userId" | "sessionId"> & ExclusiveId;
 interface UseFetchRecommendationsReturn<T extends Display> {
   /**
@@ -33,34 +516,63 @@ interface UseFetchRecommendationsReturn<T extends Display> {
    */
   fetchRecommendations: (opts: FetchRecsOptions) => Promise<T[]>;
 }
-export const version = "1.5.20";
-export function DepictProvider(props: any): any;
-export function SearchPage(): import("react").DetailedReactHTMLElement<{
-  children: never[];
-}, HTMLElement>;
-export function CategoryPage(): import("react").DetailedReactHTMLElement<{
-  children: never[];
-}, HTMLElement>;
-export function BreadCrumbs(): import("react").DetailedReactHTMLElement<{
-  children: never[];
-}, HTMLElement>;
-export function QuickLinks(): import("react").DetailedReactHTMLElement<{
-  children: never[];
-}, HTMLElement>;
-export function ComponentAligner(): import("react").DetailedReactHTMLElement<{
-  className: string;
-  style: {
-    height: string;
-  };
-}, HTMLElement>;
-export function ImagePlaceholder(raw_react_props: Parameters<typeof _ImagePlaceholder1>[0] & {
-  className: string;
-}): import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
-export function TextPlaceholder(raw_react_props: Omit<Parameters<typeof _TextPlaceholder1>[0], "class"> & {
-  className: string;
-}): import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
-export function useSearchField(): UseSearchFieldReturn;
-export function openModal(): void;
-export function useSearchModal(): UseSearchModalReturn;
-export function usePerformanceClient(): UsePerformanceClientReturn;
-export function useFetchRecommendations<T extends Display>(): UseFetchRecommendationsReturn<T>;
+/**
+ * Hook used to fetch Depict recommendations.
+ * @example
+ * Fetch general recommendations for a landing page:
+ * ```tsx
+ * import React from "react";
+ * import { useFetchRecommendations } from "@depict-ai/react-ui";
+ *
+ * export const LandingPage = () => {
+ *   const [recs, setRecs] = React.useState();
+ *   const { fetchRecommendations } = useFetchRecommendations();
+ *
+ *   React.useEffect(() => {
+ *     fetchRecommendations({ type: "landing_page" }).then(setRecs);
+ *   }, [fetchRecommendations]);
+ *
+ *   return (
+ *     <div>
+ *      {recs?.map((display) => (
+ *        <ProductCard display={display} />
+ *      ))}
+ *     </div>
+ *   );
+ * };
+ * ```
+ * @example
+ * Fetch targeted recommendations for a product details page (PDP):
+ * ```tsx
+ * import React from "react";
+ * import { useFetchRecommendations } from "@depict-ai/react-ui";
+ *
+ * export const ProductPage = ({ productId }) => {
+ *   const [recs, setRecs] = React.useState();
+ *   const { fetchRecommendations } = useFetchRecommendations();
+ *
+ *   React.useEffect(() => {
+ *     fetchRecommendations({ type: "related", productId }).then(setRecs);
+ *   }, [fetchRecommendations, productId]);
+ *
+ *   return (
+ *     <div>
+ *      {recs?.map((display) => (
+ *        <ProductCard display={display} />
+ *      ))}
+ *     </div>
+ *   );
+ * };
+ * ```
+ * @returns {UseFetchRecommendationsReturn}
+ */
+export function useFetchRecommendations<T extends Display>(): UseFetchRecommendationsReturn<T>;
+/**
+ * Helper function to navigate to a new page depending on the navigation library used.
+ */
+export const Navigation: {
+  nextRouterNavigation: (router: import("next/router").NextRouter) => import("ui/components/DepictProvider").NavigateFunction;
+};
+export { CategoryTitle, embedded_num_products as EmbeddedNumProducts } from "@depict-ai/ui";
+export type { PageURLCreator, DisplayTransformers } from "@depict-ai/ui";
+export type { Locale } from "@depict-ai/ui/locales";