@depict-ai/ui 1.1.5 → 1.2.0

package/dist/index.d.ts

@@ -1,13 +1,50 @@
-import { Node_Array, Display, Elem, ColsAtSize } from "@depict-ai/utilishared";
+import { Display, ModernDisplay, Node_Array, Elem, ColsAtSize } from "@depict-ai/utilishared";
+import { BaseCategoryDisplay, ProductListingResponse } from "@depict-ai/types/api/ProductListingResponse";
+import { CategorySuggestion, SearchSuggestionsResponse } from "@depict-ai/types/api/SearchSuggestionsResponse";
 import { JSX, Accessor, Setter, Signal } from "solid-js";
 import { SearchResponse } from "@depict-ai/types/api/SearchResponse";
 import { SearchRequest, SearchFilter } from "@depict-ai/types/api/SearchRequest";
 import { BaseSearchRequest } from "@depict-ai/types/api/BaseSearchRequest";
-import { SearchSuggestionsResponse, CategorySuggestion } from "@depict-ai/types/api/SearchSuggestionsResponse";
 import { SearchSuggestionsRequest } from "@depict-ai/types/api/SearchSuggestionsRequest";
 import { ProductListingRequest } from "@depict-ai/types/api/ProductListingRequest";
-import { ProductListingResponse } from "@depict-ai/types/api/ProductListingResponse";
-export const version = "1.1.5";
+export const version = "1.2.0";
+type PageURLCreatorAlwaysThereData = {
+    merchant: string;
+    market: string;
+};
+type PageURLCreatorCategoryData = {
+    type: "categories";
+    data: (BaseCategoryDisplay | CategorySuggestion)[];
+};
+type PageURLCreatorProductData<T extends ModernDisplay> = {
+    displays: T[];
+    type: "products";
+};
+type CanBePromiseWrapped<T> = T | Promise<T>;
+export type ModernDisplayWithPageUrl<T extends ModernDisplay> = {
+    [K in keyof T]: K extends "variant_displays" ? (T[K][number] & {
+        page_url: string;
+    })[] : T[K];
+};
+/**
+ * PageUrlCreator is, in its most basic form, a function that takes in a list of categories or products and returns a list of page_urls for the provided categories or products.
+ * It's main use case is to allow for the creation of links to the product or category pages on the merchant's site.
+ * It can also be used for the depict customers which already have links to change those links (i.e. for staging sites).
+ * Also, it can be used to enrich the data for each product card in a batched way, which is why it can be an async function and return a whole display in the case of products.
+ */
+type PageURLCreatorOptions<InputDisplay extends ModernDisplay> = (PageURLCreatorAlwaysThereData & PageURLCreatorCategoryData) | (PageURLCreatorAlwaysThereData & PageURLCreatorProductData<InputDisplay>);
+export type PageURLCreator<InputDisplay extends ModernDisplay, OutputDisplay extends ModernDisplay | never> = (options: PageURLCreatorOptions<InputDisplay>) => (typeof options)["type"] extends "categories" ? CanBePromiseWrapped<{
+    page_url: string;
+}[]> : CanBePromiseWrapped<{
+    page_url: string;
+}[]> | CanBePromiseWrapped<OutputDisplay extends ModernDisplay ? ModernDisplayWithPageUrl<OutputDisplay>[] : never>;
+export type SomethingTakingAPageURLCreator<InputDisplay extends Display, OutputDisplay extends ModernDisplay | never> = InputDisplay extends ModernDisplay ? "page_url" extends keyof InputDisplay["variant_displays"][number] ? {
+    page_url_creator?: PageURLCreator<InputDisplay, OutputDisplay>;
+} : {
+    page_url_creator: PageURLCreator<InputDisplay, OutputDisplay>;
+} : {
+    page_url_creator?: never;
+};
 /**
  * Basically allows you to use SearchModal
  * So the idea is to have a modal. It should either be rendered and exist, in which case it is in the foreground and open, or it's completely gone. This makes things easier.
@@ -188,27 +225,57 @@ export type InstantCard<T extends Display> = (display: T, context: {
     merchant: string;
     market: string;
 }) => JSX.Element;
-interface DepictAPIConstructorOptions {
+type CategorySuggestionAfterURLCreator = CategorySuggestion & {
+    page_url: string;
+};
+type ReplaceCategorySuggestion<T> = T extends CategorySuggestion ? CategorySuggestionAfterURLCreator : T extends CategorySuggestion[] ? CategorySuggestionAfterURLCreator[] : T;
+type SearchSuggestionsResponseAfterURLCreator = {
+    [K in keyof SearchSuggestionsResponse]: ReplaceCategorySuggestion<SearchSuggestionsResponse[K]>;
+};
+type AddPageUrlToDisplay<T extends any[]> = (T[number] & {
+    page_url: string;
+})[];
+type SearchResponseAfterURLCreator = {
+    [K in keyof SearchResponse]: K extends "displays" ? AddPageUrlToDisplay<SearchResponse[K]> : SearchResponse[K];
+};
+type BaseCategoryDisplayAfterURLCreator = BaseCategoryDisplay & {
+    page_url: string;
+};
+type ReplaceBaseCategoryDisplay<T> = T extends BaseCategoryDisplay ? BaseCategoryDisplayAfterURLCreator : T extends BaseCategoryDisplay[] ? BaseCategoryDisplayAfterURLCreator[] : T;
+type _AddPageUrlToDisplay1<T extends any[]> = (T[number] & {
+    page_url: string;
+})[];
+type ProductListingResponseAfterURLCreator = {
+    [K in keyof ProductListingResponse]: K extends "displays" ? _AddPageUrlToDisplay1<ProductListingResponse[K]> : K extends "breadcrumb" | "quick_links" ? ReplaceBaseCategoryDisplay<ProductListingResponse[K]> : ProductListingResponse[K];
+};
+type DepictAPIConstructorOptions<InputDisplay extends Display, OutputDisplay extends ModernDisplay | never> = {
     get_metadata?: () => Promise<{
         [k: string]: string;
     } | undefined>;
     get_user_id?: () => string | undefined;
     get_session_id?: () => string | undefined;
-}
-export class DepictAPI {
+} & SomethingTakingAPageURLCreator<InputDisplay, OutputDisplay>;
+/**
+ * Class that handles all communication done in PLP code with the Depict API. (Notably not for recommendations currently).
+ * It handles caching, retries and errors and is the only place that should be making requests to the Depict API.
+ */
+export class DepictAPI<InputDisplay extends Display, OutputDisplay extends ModernDisplay | never = InputDisplay extends ModernDisplay ? ModernDisplayWithPageUrl<InputDisplay> : never> {
     #private;
-    constructor({ get_metadata, get_user_id, get_session_id }?: DepictAPIConstructorOptions);
-    suggest(input_req: SearchSuggestionsRequest): Promise<SearchSuggestionsResponse & {
+    page_url_creator: PageURLCreator<ModernDisplay, OutputDisplay> | undefined;
+    constructor(options: DepictAPIConstructorOptions<InputDisplay, OutputDisplay>);
+    suggest(input_req: SearchSuggestionsRequest): Promise<SearchSuggestionsResponseAfterURLCreator & {
         failed?: true;
     }>;
-    query(input_req: SearchRequest): Promise<SearchResponse & {
+    query(input_req: SearchRequest): Promise<SearchResponseAfterURLCreator & {
         failed?: true;
     }>;
-    list(input_req: ProductListingRequest): Promise<ProductListingResponse & {
+    list(input_req: ProductListingRequest): Promise<ProductListingResponseAfterURLCreator & {
         failed?: true;
     }>;
-    get_recommended<D extends Display>(input_req: BaseSearchRequest): Promise<{
-        displays: D[];
+    get_recommended<T extends Display>(input_req: BaseSearchRequest): Promise<{
+        displays: T[];
+    } & {
+        failed?: true | undefined;
     }>;
 }
 /**
@@ -228,6 +295,11 @@ export interface SDKRenderingInfo {
     market: string;
 }
 export type ProductCardTemplate<T extends Display> = (display: T | null, info?: SDKRenderingInfo) => JSX.Element | Promise<JSX.Element>;
+/**
+ * Will be sent to backend to indicate whether the query_id_ is for a collection or category.
+ * Backend defaults to category if not specified.
+ */
+export type ListingType = "collection" | "category";
 export function show_toast({ children, on_close_, close_after_, ...more_attributes }: {
     children?: JSX.Element;
     close_after_: number;
@@ -298,98 +370,28 @@ export type SDKColsAtSize = [number, number?][];
  * @returns
  */
 export const convert_sdk_cols_at_size_to_layout: (cols_at_size: SDKColsAtSize) => ColsAtSize;
-export type BaseProviderConfig = {
-    /**
-     * The merchant to use for the search.
-     * @example "YOUR_MERCHANT", "stronger"
-     */
-    merchant: string;
-    /**
-     * The market to use for the search.
-     * @example "YOUR_MARKET", "no", "en-de"
-     */
-    market: string;
-    /**
-     * Optional unique identifier of a logged in user. Should be persistent across devices and sessions.
-     */
-    userId?: string;
-    /**
-     * Optional unique identifer of the current session. Only necessary when performing server side requests to Depict.
-     */
-    sessionId?: string;
-    /**
-     * Custom metadata to be sent with each request to the Depict API. Only necessary if specifically instructed by Depict.
-     */
-    metaData?: Record<string, string>;
-};
-export type BaseSearchProviderConfig = {
-    /**
-     * The path to the search page.
-     * @example "/search", "/sok"
-     */
-    searchPagePath: string;
-    /**
-     * The name of the url parameter that will be used for the search query.
-     * @example "q", "search_query", "query"
-     * @default "query"
-     */
-    urlParamName?: string;
-    /**
-     * Whether to enable category suggestions in the search modal and search page.
-     * @default false
-     */
-    enableCategorySuggestions?: boolean;
-};
-export interface BaseProductListingConfig {
-    /**
-     * How many columns to show at each media size.
-     * @default
-     * [[2, 901], [3, 1024], [4]]
-     * @example
-     * [[2, 901], [3, 1024], [4]]
-     * means 2 columns at sizes up to 901px, 3 columns at sizes up to 1024px and after that 4 columns at any viewport size.
-     */
-    columnsAtSize?: SDKColsAtSize;
-    /**
-     * The spacing between products.
-     * @default "2%"
-     * @example
-     * "2%", "10px", "1rem", {horizontal: "1%", vertical: "5px"}
-     */
-    gridSpacing?: SDKGridSpacing;
-}
-export interface BaseSearchPageConfig extends BaseProductListingConfig {
-    /**
-     * Whether to show the search input field in the search page.
-     * @default true
-     */
-    includeInputField?: boolean;
-}
-export interface BaseCategoryPageConfig extends BaseProductListingConfig {
-    /**
-     * Whether to show the breadcrumbs in the category page.
-     * @default true
-     */
-    showBreadcrumbs?: boolean;
-    /**
-     * Whether to show the quicklinks in the category page.
-     * @default true
-     */
-    showQuicklinks?: boolean;
-}
-/**
- * Will be sent to backend to indicate whether the query_id_ is for a collection or category.
- * Backend defaults to category if not specified.
- */
-export type ListingType = "collection" | "category";
-type DepictCategoryConstructorOptions = {
+type GeneralCategoryListingOptions = {
     market: string;
     merchant: string;
     localization: category_i18n;
     on_navigation?: OnNavigation;
-    api?: DepictAPI;
 };
-export class DepictCategory {
+type CategoryConstructorOptionsWithApi<InputDisplay extends Display, OutputDisplay extends ModernDisplay | never> = GeneralCategoryListingOptions & {
+    api: DepictAPI<InputDisplay, OutputDisplay>;
+} & {
+    page_url_creator?: never;
+};
+type CategoryConstructorOptionsWithoutApi<InputDisplay extends Display, OutputDisplay extends ModernDisplay | never> = GeneralCategoryListingOptions & {
+    api?: never;
+} & (InputDisplay extends ModernDisplay ? "page_url" extends keyof InputDisplay["variant_displays"][number] ? {
+    page_url_creator?: PageURLCreator<InputDisplay, OutputDisplay>;
+} : {
+    page_url_creator: PageURLCreator<InputDisplay, OutputDisplay>;
+} : {
+    page_url_creator?: never;
+});
+type DepictCategoryConstructorOptions<InputDisplay extends Display, OutputDisplay extends ModernDisplay> = CategoryConstructorOptionsWithApi<InputDisplay, OutputDisplay> | CategoryConstructorOptionsWithoutApi<InputDisplay, OutputDisplay>;
+export class DepictCategory<InputDisplay extends Display, OutputDisplay extends ModernDisplay | never = InputDisplay extends ModernDisplay ? ModernDisplayWithPageUrl<InputDisplay> : never> {
     #private;
     get localization(): category_i18n;
     set localization(locale_obj: category_i18n);
@@ -403,22 +405,24 @@ export class DepictCategory {
     set listing_type(listing_type: ListingType | undefined);
     get on_navigation(): OnNavigation;
     set on_navigation(new_function: OnNavigation);
-    constructor({ api, on_navigation, ...props_on_class }: DepictCategoryConstructorOptions);
+    constructor({ api, on_navigation, page_url_creator, ...props_on_class }: DepictCategoryConstructorOptions<InputDisplay, OutputDisplay>);
 }
-export function CategoryPage<T extends Display>({ depict_category, grid_spacing, cols_at_size, product_card_template, show_breadcrumbs, show_quicklinks, category_title, }: {
-    depict_category: DepictCategory;
+export function CategoryPage<OriginalDisplay extends Display, OutputDisplay extends ModernDisplay | never>({ depict_category, grid_spacing, cols_at_size, product_card_template, show_breadcrumbs, show_quicklinks, category_title, }: {
+    depict_category: DepictCategory<OriginalDisplay, OutputDisplay>;
     grid_spacing: SDKGridSpacing;
     cols_at_size: SDKColsAtSize;
-    product_card_template: ProductCardTemplate<T>;
+    product_card_template: ProductCardTemplate<[
+        OutputDisplay
+    ] extends [never] ? OriginalDisplay : ModernDisplayWithPageUrl<OutputDisplay>>;
     show_quicklinks?: boolean;
     show_breadcrumbs?: boolean;
     category_title: typeof CategoryTitle | typeof embedded_num_products;
 }): import("@depict-ai/utilishared").Node_Array;
-export function BreadCrumbs({ depict_category }: {
-    depict_category: DepictCategory;
+export function BreadCrumbs<T extends Display>({ depict_category }: {
+    depict_category: DepictCategory<T>;
 }): HTMLElement;
-export function QuickLinks({ depict_category }: {
-    depict_category: DepictCategory;
+export function QuickLinks<T extends Display>({ depict_category }: {
+    depict_category: DepictCategory<T>;
 }): HTMLElement;
 /**
  * Gets available categories/collections (query_ids for the product-listing endpoint) for a merchant
@@ -464,7 +468,7 @@ interface Styles {
 }
 export const styles_to_valid_css_string: (styles: Styles) => string;
 /** A function that renders category suggestion cards. Set to false to disable category suggestions. */
-export type RenderCategorySuggestion = (category_suggestion: Accessor<CategorySuggestion>, index: number) => JSX.Element;
+export type RenderCategorySuggestion = (category_suggestion: Accessor<CategorySuggestionAfterURLCreator>, index: number) => JSX.Element;
 /**
  * Connects the height of the search field to the height of the aligner.
  * @param aligner
@@ -473,7 +477,7 @@ export type RenderCategorySuggestion = (category_suggestion: Accessor<CategorySu
 export function connect_search_field_height_to_aligner_height(aligner: HTMLElement): {
     cleanup: () => void;
 };
-type ConstructorOptions<T extends Display> = {
+type GeneralConstructorOptions<InputDisplay extends Display, OutputDisplay extends ModernDisplay | never> = {
     search_query_url_param_name?: string;
     market: string;
     merchant: string;
@@ -482,10 +486,18 @@ type ConstructorOptions<T extends Display> = {
     url_transformer?: (url_object: URL) => unknown;
     enable_category_suggestions?: boolean;
     disable_scrolling_during_modal?: boolean;
-    api?: DepictAPI;
     bottom_distance_under_modal?: Accessor<number | undefined>;
-    render_instant_card?: InstantCard<T>;
+    render_instant_card?: InstantCard<OutputDisplay extends ModernDisplay ? OutputDisplay : InputDisplay>;
+};
+type ConstructorOptionsWithApi<InputDisplay extends Display, OutputDisplay extends ModernDisplay | never> = GeneralConstructorOptions<InputDisplay, OutputDisplay> & {
+    api: DepictAPI<InputDisplay, OutputDisplay>;
+} & {
+    page_url_creator?: never;
 };
+type ConstructorOptionsWithoutAPI<InputDisplay extends Display, OutputDisplay extends ModernDisplay | never> = GeneralConstructorOptions<InputDisplay, OutputDisplay> & {
+    api?: never;
+} & SomethingTakingAPageURLCreator<InputDisplay, OutputDisplay>;
+type ConstructorOptions<InputDisplay extends Display, OutputDisplay extends ModernDisplay> = ConstructorOptionsWithApi<InputDisplay, OutputDisplay> | ConstructorOptionsWithoutAPI<InputDisplay, OutputDisplay>;
 export type OpenModalArguments = [
     options_for_modal?: {
         style_props_?: Signal<JSX.CSSProperties>;
@@ -497,9 +509,9 @@ export type OpenModalArguments = [
     on_dispose?: VoidFunction
 ];
 export const get_search_query_updating_blocked_signal: (depict_search: DepictSearch<any>) => Signal<boolean> | undefined;
-export class DepictSearch<T extends Display> {
+export class DepictSearch<InputDisplay extends Display, OutputDisplay extends ModernDisplay | never = InputDisplay extends ModernDisplay ? ModernDisplayWithPageUrl<InputDisplay> : never> {
     #private;
-    constructor({ search_query_url_param_name: search_query_url_param_name_, url_transformer, on_navigation, enable_category_suggestions, disable_scrolling_during_modal, api, bottom_distance_under_modal, render_instant_card, ...props_on_class }: ConstructorOptions<T>);
+    constructor({ search_query_url_param_name: search_query_url_param_name_, url_transformer, on_navigation, enable_category_suggestions, page_url_creator, disable_scrolling_during_modal, api, bottom_distance_under_modal, render_instant_card, ...props_on_class }: ConstructorOptions<InputDisplay, OutputDisplay>);
     get on_navigation(): OnNavigation;
     set on_navigation(new_function: OnNavigation);
     get localization(): search_i18n;
@@ -510,17 +522,19 @@ export class DepictSearch<T extends Display> {
     set merchant(tenant: string);
     get market(): string;
     set market(market: string);
-    fetchSearchResults(query: string, filters?: SearchFilter[], maxResults?: number): Promise<T[]>;
+    fetchSearchResults(query: string, filters?: SearchFilter[], maxResults?: number): Promise<([OutputDisplay] extends [never] ? InputDisplay : ModernDisplayWithPageUrl<OutputDisplay>)[]>;
 }
-export function SearchPage<T extends Display>(props: {
-    depict_search: DepictSearch<T>;
+export function SearchPage<OriginalDisplay extends Display, TransformedDisplay extends never | ModernDisplay>(props: {
+    depict_search: DepictSearch<OriginalDisplay, TransformedDisplay>;
     include_input_field?: boolean | {
         on_open_?: VoidFunction;
         on_close_?: VoidFunction;
     };
     grid_spacing: SDKGridSpacing;
     cols_at_size: SDKColsAtSize;
-    product_card_template: ProductCardTemplate<T>;
+    product_card_template: ProductCardTemplate<[
+        TransformedDisplay
+    ] extends [never] ? OriginalDisplay : ModernDisplayWithPageUrl<TransformedDisplay>>;
     extra_depict_options?: {
         recommendations_cols_at_size?: SDKColsAtSize;
     };
@@ -532,6 +546,91 @@ interface SearchFieldParams {
     aligner_ref?: HTMLElement | null;
 }
 export function SearchField({ depict_search, modal_dispose_handler, click_handler, aligner_ref, }: SearchFieldParams): import("@depict-ai/utilishared").Node_Array;
+export type BaseProviderConfig<InputDisplay extends Display, PossibleTransformedDisplay extends ModernDisplay | never = InputDisplay extends ModernDisplay ? ModernDisplayWithPageUrl<InputDisplay> : never> = {
+    /**
+     * The merchant to use for the search.
+     * @example "YOUR_MERCHANT", "stronger"
+     */
+    merchant: string;
+    /**
+     * The market to use for the search.
+     * @example "YOUR_MARKET", "no", "en-de"
+     */
+    market: string;
+    /**
+     * Optional unique identifier of a logged in user. Should be persistent across devices and sessions.
+     */
+    userId?: string;
+    /**
+     * Optional unique identifer of the current session. Only necessary when performing server side requests to Depict.
+     */
+    sessionId?: string;
+    /**
+     * Custom metadata to be sent with each request to the Depict API. Only necessary if specifically instructed by Depict.
+     */
+    metaData?: Record<string, string>;
+} & (InputDisplay extends ModernDisplay ? "page_url" extends keyof InputDisplay["variant_displays"][number] ? {
+    pageURLCreator?: PageURLCreator<InputDisplay, PossibleTransformedDisplay>;
+} : {
+    pageURLCreator: PageURLCreator<InputDisplay, PossibleTransformedDisplay>;
+} : {
+    pageURLCreator?: never;
+});
+export type BaseSearchProviderConfig = {
+    /**
+     * The path to the search page.
+     * @example "/search", "/sok"
+     */
+    searchPagePath: string;
+    /**
+     * The name of the url parameter that will be used for the search query.
+     * @example "q", "search_query", "query"
+     * @default "query"
+     */
+    urlParamName?: string;
+    /**
+     * Whether to enable category suggestions in the search modal and search page.
+     * @default false
+     */
+    enableCategorySuggestions?: boolean;
+};
+export interface BaseProductListingConfig {
+    /**
+     * How many columns to show at each media size.
+     * @default
+     * [[2, 901], [3, 1024], [4]]
+     * @example
+     * [[2, 901], [3, 1024], [4]]
+     * means 2 columns at sizes up to 901px, 3 columns at sizes up to 1024px and after that 4 columns at any viewport size.
+     */
+    columnsAtSize?: SDKColsAtSize;
+    /**
+     * The spacing between products.
+     * @default "2%"
+     * @example
+     * "2%", "10px", "1rem", {horizontal: "1%", vertical: "5px"}
+     */
+    gridSpacing?: SDKGridSpacing;
+}
+export interface BaseSearchPageConfig extends BaseProductListingConfig {
+    /**
+     * Whether to show the search input field in the search page.
+     * @default true
+     */
+    includeInputField?: boolean;
+}
+export interface BaseCategoryPageConfig extends BaseProductListingConfig {
+    /**
+     * Whether to show the breadcrumbs in the category page.
+     * @default true
+     */
+    showBreadcrumbs?: boolean;
+    /**
+     * Whether to show the quicklinks in the category page.
+     * @default true
+     */
+    showQuicklinks?: boolean;
+}
 type CenteredLocation = {
     location?: "centered";
 };
@@ -543,8 +642,8 @@ type AlignedLocation = {
  * How the modal should be opened.
  */
 type ModalLocation = AlignedLocation | CenteredLocation;
-type OpenModalParams<T extends Display> = ModalLocation & {
-    search: DepictSearch<T>;
+type OpenModalParams<OriginalDisplay extends Display, OutputDisplay extends ModernDisplay | never> = ModalLocation & {
+    search: DepictSearch<OriginalDisplay, OutputDisplay>;
     /**
      * If true, the search field in the modal opened will be empty and de-coupled from the other SearchFields.
      */
@@ -554,7 +653,7 @@ type OpenModalParams<T extends Display> = ModalLocation & {
  * Open the modal with support for alignment.
  * @returns {void}
  */
-export const open_modal_with_alignment: <T extends Display>(openModalParams: OpenModalParams<T>) => void;
+export const open_modal_with_alignment: <OriginalDisplay extends Display, OutputDisplay extends ModernDisplay>(openModalParams: OpenModalParams<OriginalDisplay, OutputDisplay>) => void;
 export function open_search_with_shift_slash(open_search: VoidFunction): () => void;
 export interface PageReplacer {
     readonly render_: () => Node_Array;