@depict-ai/react-ui 0.0.53 → 0.0.55

package/dist/module.js

@@ -1,11 +1,11 @@
 import {dlog as $TZSbU$dlog, href_change_ipns as $TZSbU$href_change_ipns, catchify as $TZSbU$catchify, observer as $TZSbU$observer, history_replacer as $TZSbU$history_replacer, queueMacroTask as $TZSbU$queueMacroTask, ContainedPlaceholderImage as $TZSbU$ContainedPlaceholderImage, Placeholder as $TZSbU$Placeholder} from "@depict-ai/utilishared";
-import {add_to_version_info as $TZSbU$add_to_version_info, SearchField as $TZSbU$SearchField, DepictSearch as $TZSbU$DepictSearch, get_search_query_updating_blocked_signal as $TZSbU$get_search_query_updating_blocked_signal, SearchPage as $TZSbU$SearchPage} from "@depict-ai/ui";
-import {untrack as $TZSbU$untrack, createComponent as $TZSbU$createComponent, Show as $TZSbU$Show, createSignal as $TZSbU$createSignal, createMemo as $TZSbU$createMemo, createComputed as $TZSbU$createComputed, onCleanup as $TZSbU$onCleanup} from "solid-js";
+import {add_to_version_info as $TZSbU$add_to_version_info, SearchField as $TZSbU$SearchField, DepictSearch as $TZSbU$DepictSearch, DepictCategory as $TZSbU$DepictCategory, get_search_query_updating_blocked_signal as $TZSbU$get_search_query_updating_blocked_signal, SearchPage as $TZSbU$SearchPage, CategoryPage as $TZSbU$CategoryPage, embedded_num_products as $TZSbU$embedded_num_products} from "@depict-ai/ui";
+import {untrack as $TZSbU$untrack, createComponent as $TZSbU$createComponent, Show as $TZSbU$Show, onCleanup as $TZSbU$onCleanup, createSignal as $TZSbU$createSignal, createComputed as $TZSbU$createComputed} from "solid-js";
 import {render as $TZSbU$render} from "solid-js/web";
 import {useState as $TZSbU$useState, useRef as $TZSbU$useRef, useEffect as $TZSbU$useEffect, createElement as $TZSbU$createElement, Fragment as $TZSbU$Fragment} from "react";
-import {en as $TZSbU$en} from "@depict-ai/ui/locales";
-import {createPortal as $TZSbU$createPortal} from "react-dom";
 import {jsx as $TZSbU$jsx} from "react/jsx-runtime";
+import {createPortal as $TZSbU$createPortal} from "react-dom";
+import {en as $TZSbU$en} from "@depict-ai/ui/locales";
 
 /*! Depict.ai search and product listing react SDK wrapper */ // This is where the actual source of your React stuff should live
 // Note, if you add an export here, also add one in src-server/main.ts
@@ -14,6 +14,7 @@ import {jsx as $TZSbU$jsx} from "react/jsx-runtime";
 
 const $42858f023ef23dab$export$8e769ad4338a911e = {
     search: null,
+    category: null,
     header_alignment: null,
     search_page_path_: (0, $TZSbU$createSignal)(),
     required_state_set_: (0, $TZSbU$createSignal)(false)
@@ -23,6 +24,8 @@ const $42858f023ef23dab$export$8e769ad4338a911e = {
 
 
 
+
+
 let $c83ba9ab79386687$var$run_on_href_change;
 function $c83ba9ab79386687$export$74f3924c5027fe1d(cb) {
     $c83ba9ab79386687$var$run_on_href_change = cb;
@@ -31,7 +34,7 @@ function $c83ba9ab79386687$export$74f3924c5027fe1d(cb) {
     for await (const href of (0, $TZSbU$href_change_ipns))$c83ba9ab79386687$var$run_on_href_change?.(href);
 })();
 const $c83ba9ab79386687$export$6cb4d3a5c1ac9b43 = (url)=>url.pathname == (0, $TZSbU$untrack)((0, $42858f023ef23dab$export$8e769ad4338a911e).search_page_path_[0]); // might have changed therefore get it from globalState
-function $c83ba9ab79386687$export$f6e64e17bd69eeef(solid_component, props, wrapper_type = "div", wrapper_style = {}) {
+function $c83ba9ab79386687$export$f6e64e17bd69eeef(solid_component, props, wrapper_type = "div", wrapper_style = {}, render_cb) {
     const [portals, set_portals] = (0, $TZSbU$useState)([]);
     const wrapper_element_ref = (0, $TZSbU$useRef)();
     (0, $TZSbU$useEffect)(()=>{
@@ -39,6 +42,7 @@ function $c83ba9ab79386687$export$f6e64e17bd69eeef(solid_component, props, wrapp
         const dispose = (0, $TZSbU$render)(()=>solid_component(props, set_portals), wrapper_element);
         return dispose;
     }, []);
+    render_cb?.(props);
     return (0, $TZSbU$createElement)(wrapper_type, {
         ref: wrapper_element_ref,
         style: wrapper_style
@@ -56,6 +60,38 @@ function $c83ba9ab79386687$export$e5139bbbb9a05035(component) {
         });
     };
 }
+async function $c83ba9ab79386687$export$79c79419c1ef0081({ display: display , info: info , component_portals: component_portals , set_portals: set_portals , react_template: react_template  }) {
+    const solid_container = document.createElement("div");
+    const react_has_rendered = new Promise((r)=>{
+        const m_o = new MutationObserver(()=>{
+            m_o.disconnect();
+            r();
+        });
+        m_o.observe(solid_container, {
+            childList: true
+        });
+    });
+    const is_placeholder = info.rendering_options.type === "placeholder";
+    const reactProductCard = (0, $TZSbU$jsx)(react_template, {
+        display: is_placeholder ? null : display
+    });
+    const portal = $TZSbU$createPortal(reactProductCard, solid_container);
+    component_portals.add(portal);
+    set_portals([
+        ...component_portals
+    ]);
+    (0, $TZSbU$onCleanup)(()=>{
+        // this will stop working after any await so be careful to not await before this, or you'll have to carry the owner over with getOwner and runWithOwner
+        component_portals.delete(portal);
+        set_portals([
+            ...component_portals
+        ]);
+    });
+    await react_has_rendered; // wait for react to have finish portaling the elements so that the placeholders get removed once we have an actual result and so that the PLP code knows it has a placeholder when this is a placeholder rendering
+    return [
+        solid_container
+    ];
+}
 
 
 
@@ -135,7 +171,7 @@ const $7216ca4c8308a0f9$export$599d4515591ef232 = (href)=>{
 
 
 function $faf794495ff8b304$export$9fac37a9c21c2f3b(props) {
-    const { children: children , market: market , merchant: merchant , navigateFunction: navigateFunction , locale: locale  } = props;
+    const { children: children , navigateFunction: navigateFunction , market: market , merchant: merchant , locale: locale  } = props;
     const usedLocale = locale ?? (0, $TZSbU$en);
     const { searchPagePath: searchPagePath , urlParamName: urlParamName , enableCategorySuggestions: enableCategorySuggestions  } = props.search ?? {};
     if (!market || !merchant) {
@@ -143,9 +179,13 @@ function $faf794495ff8b304$export$9fac37a9c21c2f3b(props) {
         return (0, $TZSbU$createElement)((0, $TZSbU$Fragment), null, children);
     }
     try {
-        const { search: search  } = (0, $42858f023ef23dab$export$8e769ad4338a911e);
+        const { search: search , category: category  } = (0, $42858f023ef23dab$export$8e769ad4338a911e);
         const [get_search_page_path, set_search_page_path] = (0, $42858f023ef23dab$export$8e769ad4338a911e).search_page_path_;
         set_search_page_path(searchPagePath);
+        const on_navigation = typeof window?.next?.router !== "undefined" || navigateFunction ? (new_href)=>{
+            if (navigateFunction) navigateFunction(new_href);
+            else (0, $7216ca4c8308a0f9$export$599d4515591ef232)(new_href);
+        } : undefined;
         if (!search) {
             (0, $42858f023ef23dab$export$8e769ad4338a911e).search = new (0, $TZSbU$DepictSearch)({
                 search_query_url_param_name: urlParamName,
@@ -154,13 +194,8 @@ function $faf794495ff8b304$export$9fac37a9c21c2f3b(props) {
                 enable_category_suggestions: enableCategorySuggestions ?? false,
                 // default category suggestions to false for @depict-ai/react-ui (https://linear.app/depictai/issue/FRO-401/default-enablecategorysuggestions-to-false)
                 localization: usedLocale,
-                ...typeof window?.next?.router !== "undefined" || navigateFunction ? {
-                    on_navigation: (new_href)=>{
-                        if (navigateFunction) navigateFunction(new_href);
-                        else (0, $7216ca4c8308a0f9$export$599d4515591ef232)(new_href);
-                    }
-                } : {},
-                url_transformer: (url)=>url.pathname = (0, $TZSbU$untrack)(get_search_page_path)
+                url_transformer: (url)=>url.pathname = (0, $TZSbU$untrack)(get_search_page_path),
+                on_navigation: on_navigation
             });
             (0, $8071251ee4e9ffa1$export$6453cbc34515a94d)((0, $c83ba9ab79386687$export$6cb4d3a5c1ac9b43));
         } else {
@@ -168,6 +203,17 @@ function $faf794495ff8b304$export$9fac37a9c21c2f3b(props) {
             search.merchant = merchant;
             search.localization = usedLocale;
         }
+        if (!category) (0, $42858f023ef23dab$export$8e769ad4338a911e).category = new (0, $TZSbU$DepictCategory)({
+            market: market,
+            merchant: merchant,
+            localization: usedLocale,
+            on_navigation: on_navigation
+        });
+        else {
+            category.market = market;
+            category.merchant = merchant;
+            category.localization = usedLocale;
+        }
         (0, $42858f023ef23dab$export$8e769ad4338a911e).required_state_set_[1](true);
     } catch (e) {
         // Make sure to not break the users app if we throw
@@ -184,7 +230,6 @@ function $faf794495ff8b304$export$9fac37a9c21c2f3b(props) {
 // and cover the entire height of the header. Then we know where to put the modal input top and bottom, and the left and right we just center.
 
 
-
 function $f41a371216eff80b$export$cbcd1ecdb41b1d0a() {
     return (0, $TZSbU$createElement)("div", {
         className: "depict aligner",
@@ -197,32 +242,7 @@ function $f41a371216eff80b$export$a7f6cffb6b8ba11c() {
         console.error("No active search in the app!");
         return;
     }
-    if (!(0, $42858f023ef23dab$export$8e769ad4338a911e).header_alignment) {
-        console.error("No active search header aligner on the page!");
-        return;
-    }
-    const style_props_ = (0, $TZSbU$createSignal)({
-        position: "fixed",
-        top: 0
-    });
-    if ((0, $42858f023ef23dab$export$8e769ad4338a911e).header_alignment?.clientHeight) {
-        let styles = `.depict.plp.in-header .depict-search-modal .query-input { height: ${(0, $42858f023ef23dab$export$8e769ad4338a911e).header_alignment?.clientHeight}px; }`;
-        styles += `.depict.plp.in-header .depict-search-modal-backdrop { top: ${(0, $42858f023ef23dab$export$8e769ad4338a911e).header_alignment?.clientHeight}px; }`;
-        if (!$f41a371216eff80b$var$sheet) {
-            const style = document.createElement("style");
-            style.append(styles);
-            document.head.appendChild(style);
-        }
-    }
-    const class_list_ = (0, $TZSbU$createMemo)(()=>({
-            "in-header": true
-        }));
-    (0, $42858f023ef23dab$export$8e769ad4338a911e).search.modal_open = [
-        {
-            style_props_: style_props_,
-            class_list_: class_list_
-        }
-    ];
+    (0, $42858f023ef23dab$export$8e769ad4338a911e).search.modal_open = true;
 }
 
 
@@ -230,8 +250,6 @@ function $f41a371216eff80b$export$a7f6cffb6b8ba11c() {
 
 
 
-
-
 function $9f8d5ef3c016c493$export$210723f5a54a7028(props) {
     return (0, $c83ba9ab79386687$export$f6e64e17bd69eeef)((0, $c83ba9ab79386687$export$e5139bbbb9a05035)($9f8d5ef3c016c493$var$SolidSearchPage), props);
 }
@@ -271,38 +289,58 @@ function $9f8d5ef3c016c493$var$SolidSearchPage(props, set_portals) {
         // Todo: Do we need this?
         get_product_id: ()=>"",
         depict_search: depict_search,
-        product_card_template: async (display, info)=>{
-            const solid_container = document.createElement("div");
-            const react_has_rendered = new Promise((r)=>{
-                const m_o = new MutationObserver(()=>{
-                    m_o.disconnect();
-                    r();
-                });
-                m_o.observe(solid_container, {
-                    childList: true
-                });
-            });
-            const is_placeholder = info.rendering_options.type === "placeholder";
-            const reactProductCard = (0, $TZSbU$jsx)(props.productCard, {
-                display: is_placeholder ? null : display
-            });
-            const portal = $TZSbU$createPortal(reactProductCard, solid_container);
-            component_portals.add(portal);
-            set_portals([
-                ...component_portals
-            ]);
-            (0, $TZSbU$onCleanup)(()=>{
-                // this will stop working after any await so be careful to not await before this, or you'll have to carry the owner over with getOwner and runWithOwner
-                component_portals.delete(portal);
-                set_portals([
-                    ...component_portals
-                ]);
-            });
-            await react_has_rendered; // wait for react to have finish portaling the elements so that the placeholders get removed once we have an actual result and so that the PLP code knows it has a placeholder when this is a placeholder rendering
-            return [
-                solid_container
-            ];
-        }
+        product_card_template: (display, info)=>(0, $c83ba9ab79386687$export$79c79419c1ef0081)({
+                display: display,
+                info: info,
+                react_template: props.productCard,
+                component_portals: component_portals,
+                set_portals: set_portals
+            })
+    });
+}
+
+
+
+
+
+let $f2cd62bf5f14ad67$var$render_cb;
+function $f2cd62bf5f14ad67$export$d87c61cecb2edf0d(props) {
+    return (0, $c83ba9ab79386687$export$f6e64e17bd69eeef)((0, $c83ba9ab79386687$export$e5139bbbb9a05035)($f2cd62bf5f14ad67$var$SolidCategoryPage), props, "div", {}, (props)=>$f2cd62bf5f14ad67$var$render_cb?.(props));
+}
+function $f2cd62bf5f14ad67$var$SolidCategoryPage(props, set_portals) {
+    const depict_category = (0, $42858f023ef23dab$export$8e769ad4338a911e).category;
+    if (!depict_category) throw Error("No depict_category instance when rendering SearchPage. Did you forget to wrap your app in DepictProvider?");
+    $f2cd62bf5f14ad67$var$render_cb = (props)=>depict_category.category_id = props.categoryId;
+    $f2cd62bf5f14ad67$var$render_cb(props);
+    const component_portals = new Set();
+    return (0, $TZSbU$CategoryPage)({
+        depict_category: depict_category,
+        cols_at_size: props.columnsAtSize ?? [
+            [
+                4
+            ],
+            [
+                3,
+                1024
+            ],
+            [
+                2,
+                901
+            ]
+        ],
+        grid_spacing: props.gridSpacing ?? "2%",
+        // Todo: Do we need this?
+        get_product_id: ()=>"",
+        category_title: (0, $TZSbU$embedded_num_products),
+        show_breadcrumbs: props.showBreadcrumbs || false,
+        show_quicklinks: props.showQuicklinks || false,
+        product_card_template: (display, info)=>(0, $c83ba9ab79386687$export$79c79419c1ef0081)({
+                display: display,
+                info: info,
+                react_template: props.productCard,
+                component_portals: component_portals,
+                set_portals: set_portals
+            })
     });
 }
 
@@ -330,7 +368,7 @@ const $8aa3ab31237c8dc9$export$89c6019e4baa40b1 = ({ width: width , height: heig
 };
 
 
-const $c9c4d066f9a5b51b$export$83d89fbfd8236492 = "0.0.53";
+const $c9c4d066f9a5b51b$export$83d89fbfd8236492 = "0.0.55";
 
 
 
@@ -372,4 +410,4 @@ const $43099132aad1ceb6$var$package_name = "@depict-ai/react-ui";
 });
 
 
-export {$54b0d21b77e719c4$export$d2c02478244f91f7 as DepictSearchField, $faf794495ff8b304$export$9fac37a9c21c2f3b as DepictProvider, $f41a371216eff80b$export$a7f6cffb6b8ba11c as openModal, $f41a371216eff80b$export$cbcd1ecdb41b1d0a as DepictSearchHeader, $9f8d5ef3c016c493$export$210723f5a54a7028 as DepictSearchPage, $c95f83f01e99fc18$export$3f37af283f8fb843 as ImagePlaceholder, $8aa3ab31237c8dc9$export$89c6019e4baa40b1 as TextPlaceholder, $c9c4d066f9a5b51b$export$83d89fbfd8236492 as version, $97603d19204ec48d$export$b8a61e5c71402559 as Navigation};
+export {$54b0d21b77e719c4$export$d2c02478244f91f7 as DepictSearchField, $faf794495ff8b304$export$9fac37a9c21c2f3b as DepictProvider, $f41a371216eff80b$export$a7f6cffb6b8ba11c as openModal, $f41a371216eff80b$export$cbcd1ecdb41b1d0a as DepictSearchHeader, $9f8d5ef3c016c493$export$210723f5a54a7028 as DepictSearchPage, $f2cd62bf5f14ad67$export$d87c61cecb2edf0d as DepictCategoryPage, $c95f83f01e99fc18$export$3f37af283f8fb843 as ImagePlaceholder, $8aa3ab31237c8dc9$export$89c6019e4baa40b1 as TextPlaceholder, $c9c4d066f9a5b51b$export$83d89fbfd8236492 as version, $97603d19204ec48d$export$b8a61e5c71402559 as Navigation};

package/dist/styles/components/PLP/Buttons.scss

@@ -7,6 +7,9 @@
 $primary-button-overrides: ();
 $secondary-button-overrides: ();
 
+/// Used to get the current properties of the primary button. (`Buttons.$primary-button-overrides` merged into the default properties.) This is so that parts of the button styling can be re-used in other mixins in the state they were in as the mixins get called.
+/// @example
+///  filter: map.get(Buttons.get-primary-button-properties(), "focus-visible-filter");
 @function get-primary-button-properties() {
   $primary-button-properties: (
     "background": variables.$brand-black,
@@ -22,6 +25,9 @@ $secondary-button-overrides: ();
   @return map.merge($primary-button-properties, $primary-button-overrides);
 }
 
+/// Used to get the current properties of the primary button. (`Buttons.$primary-button-overrides` merged into the default properties.) This is so that parts of the button styling can be re-used in other mixins in the state they were in as the mixins get called.
+/// @example
+///  filter: map.get(Buttons.get-secondary-button-properties(), "focus-visible-filter");
 @function get-secondary-button-properties() {
   $secondary-button-properties: (
     "background": variables.$brand-lightest-grey,
@@ -36,6 +42,26 @@ $secondary-button-overrides: ();
   @return map.merge($secondary-button-properties, $secondary-button-overrides);
 }
 
+/// Generates styling for our primary buttons, including hover, active and focus-visible states
+///
+/// *Please only provide options to this mixin if you want to create styling for just a specific button.*
+///
+/// This mixin and the SecondaryButton mixin are specialties that are trying out a way of styling that we'll probably switch to in the future where you configure the styling of different components using maps instead of calling mixins yourself with different properties, as that will reduce boilerplate. The reason we had to change these already is that the values defined here are also used in other mixins and they can't be accessed if they are only provided as arguments in mixin calls.
+////
+/// *For generally changing how the buttons look, override the $primary-button-overrides map with a custom map containing the properties you want to change.*
+/// See the example below.
+/// @example
+///   // To override styling (see explanation in description)
+///   Buttons.$primary-button-overrides: ("background": #3f322a, "color": rgb(240,240,240));
+/// @param {Color} $background [map.get(get-primary-button-properties(), "background")] - The background color of the button. From this color other button states will be automatically inferred by lightening or darkening it.
+///
+/// @param {Color} $color [map.get(get-primary-button-properties(), "color")] - The color of the button text
+/// @param {Border} $border [map.get(get-primary-button-properties(), "border")] - The button border
+/// @param {Number with unit} $border-radius [map.get(get-primary-button-properties(), "border-radius")] - The button border radius
+/// @param {Filter} $hover-filter [map.get(get-primary-button-properties(), "hover-filter")] - The filter to apply on hover
+/// @param {Filter} $active-filter [map.get(get-primary-button-properties(), "active-filter")] - The filter to apply on active
+/// @param {Filter} $focus-visible-filter [map.get(get-primary-button-properties(), "focus-visible-filter")] - The filter to apply on focus-visible (when the button is focused using keyboard navigation)
+
 @mixin PrimaryButton(
   $background: map.get(get-primary-button-properties(), "background"),
   $color: map.get(get-primary-button-properties(), "color"),
@@ -61,6 +87,26 @@ $secondary-button-overrides: ();
   }
 }
 
+/// Generates styling for our secondary buttons, including hover, active and focus-visible states
+///
+/// *Please only provide options to this mixin if you want to create styling for just a specific button.*
+///
+/// This mixin and the SecondaryButton mixin are specialties that are trying out a way of styling that we'll probably switch to in the future where you configure the styling of different components using maps instead of calling mixins yourself with different properties, as that will reduce boilerplate. The reason we had to change these already is that the values defined here are also used in other mixins and they can't be accessed if they are only provided as arguments in mixin calls.
+////
+/// *For generally changing how the buttons look, override the $secondary-button-overrides map with a custom map containing the properties you want to change.*
+/// See the example below.
+/// @example
+///   // To override styling (see explanation in description)
+///   Buttons.$secondary-button-overrides: ("border": 1px solid #afafaf, "background": white);
+/// @param {Color} $background [map.get(get-secondary-button-properties(), "background")] - The background color of the button. From this color other button states will be automatically inferred by lightening or darkening it.
+///
+/// @param {Color} $color [map.get(get-secondary-button-properties(), "color")] - The color of the button text
+/// @param {Border} $border [map.get(get-secondary-button-properties(), "border")] - The button border
+/// @param {Number with unit} $border-radius [map.get(get-secondary-button-properties(), "border-radius")] - The button border radius
+/// @param {Filter} $hover-filter [map.get(get-secondary-button-properties(), "hover-filter")] - The filter to apply on hover
+/// @param {Filter} $active-filter [map.get(get-secondary-button-properties(), "active-filter")] - The filter to apply on active
+/// @param {Filter} $focus-visible-filter [map.get(get-secondary-button-properties(), "focus-visible-filter")] - The filter to apply on focus-visible (when the button is focused using keyboard navigation)
+
 @mixin SecondaryButton(
   $background: map.get(get-secondary-button-properties(), "background"),
   $color: map.get(get-secondary-button-properties(), "color"),

package/dist/styles/components/PLP/PLPResults.scss

@@ -1,8 +1,14 @@
 @use "../../variables";
 @use "../../helpers/utils";
 
+/// Base styling (PLP) that applies to both category and search pages for the PLPResults component, the component which holds the product cards.
+/// Another part of this styling is in the ProductListingPage mixin, which takes care about the overall layout of the page (which mostly means margins and paddings).
+
 @mixin PLPResults() {
   .listing-page {
+    display: flex;
+    flex-direction: column;
+
     .no-results {
       background: white;
       padding: 40px;

package/dist/styles/components/PLP/ProductListingPage.scss

@@ -1,9 +1,15 @@
 @use "../../helpers/utils";
 
+/// Styling that ties together the different components that are common to both Category and Search pages. Mainly takes care of margins and paddings but also sets the styling for .cards which is in both PLPResults and SearchRecommendations.
+///
+/// Note that for the gaps not the exact values will always be used but often multiples for different places where it's appropriate.
+///
+/// @param {Number with size unit} $spacing-to-filters [12px] - The spacing between the filters and content.
+/// @param {Number with size unit} $desktop-item-gap [20px] - The vertical gap between the different items on desktop.
+/// @param {Number with size unit} $mobile-item-gap [16px] - The vertical gap between the different items on mobile.
+
 @mixin ProductListingPage($spacing-to-filters: 12px, $desktop-item-gap: 20px, $mobile-item-gap: 16px) {
   .listing-page {
-    display: flex;
-    flex-direction: column;
     padding: $desktop-item-gap calc(#{$desktop-item-gap} / 2);
     @include mobile_sizes() {
       padding: $mobile-item-gap calc(#{$mobile-item-gap} / 2);
@@ -55,6 +61,17 @@
   }
 }
 
+/// Styling that ties together the different components on the SearchPage. Mainly takes care of margins and paddings.
+///
+/// Note that for the gaps not the exact values will always be used but often multiples for different places where it's appropriate.
+///
+/// @param {Number with size unit} $spacing-to-filters [12px] - The spacing between the filters and content.
+/// @param {Number with size unit} $desktop-item-gap [20px] - The vertical gap between the different items on desktop.
+/// @param {Number with size unit} $mobile-item-gap [16px] - The vertical gap between the different items on mobile.
+/// @param {Boolean} $spacing-above-search-field [true] - Whether to add equal spacing above the search field as below.
+/// @param {Number with size unit} $query-input-width [800px] - The max width of the query input field (if present)
+/// @param {Number} $gaps-to-recs-factor [3] - The factor to multiply the gaps with to get the spacing above the recommendations.
+
 @mixin SearchPage(
   $spacing-to-filters: 12px,
   $desktop-item-gap: 20px,
@@ -124,6 +141,12 @@
   }
 }
 
+/// Styling that ties together the different components on the CategoryPage. Mainly takes care of margins and paddings.
+///
+/// @param {Number with size unit} $spacing-to-filters [12px] - The spacing between the filters and content.
+/// @param {Number with size unit} $desktop-item-gap [20px] - The vertical gap between the different items on desktop.
+/// @param {Number with size unit} $mobile-item-gap [16px] - The vertical gap between the different items on mobile.
+
 @mixin CategoryPage($spacing-to-filters: 12px, $desktop-item-gap: 20px, $mobile-item-gap: 16px) {
   .listing-page {
     .quicklinks,
@@ -136,6 +159,8 @@
   }
 }
 
+/// Internal mixin that dictates when the vertical spaces should switch to the "mobile" versions
+
 @mixin mobile_sizes() {
   @media (max-width: 651px) {
     @content;

package/dist/styles/components/PLP/ScrollStatus.scss

@@ -1,8 +1,15 @@
 @use "../../variables";
 
+/// ScrollStatus shows the user how many items are left to scroll through, if they scroll at a speed that indicates that they are no longer looking at each product but rather just trying to see how many there are.
+///
+/// Making the background slightly frosted is something I'd love to do, but there's a bug in chrome that it doesn't work. I'd appreciate if you starred my bug report so it maybe gets fixed one day: https://bugs.chromium.org/p/chromium/issues/detail?id=1382360
+///
+/// @param {Color} $scroll-status-background [rgba(100, 100, 100, 0.9)] - The background color of the scroll status. I recommend setting a slightly transparent color.
+/// @param {Number with size unit} $border-radius [variables.$border-radius * 5] - The border-radius of the scroll status.
+
 @mixin ScrollStatus(
   $scroll-status-background: rgba(100, 100, 100, 0.9),
-  $border-radius: calc(variables.$border-radius * 5)
+  $border-radius: calc(#{variables.$border-radius} * 5)
 ) {
   .scroll-status {
     pointer-events: none;

package/dist/styles/components/PLP/SelectedFilters.scss

@@ -4,6 +4,13 @@
 @use "./Buttons";
 @use "sass:map";
 
+/// Mixin that styles the SelectedFilters component, which is the component that shows the selected filters if both the sorting and filtering menus are currently hidden.
+/// @param {Number with size unit} $border-radius [variables.$border-radius] - A local override of the border-radius variable.
+/// @param {String} $title-color [variables.$brand-black] - The color of the text that says "Filters:" (the key of this string is `selected_filters_title_` in the locale files).
+/// @param {String} $filter-title-transform [uppercase] - text-transform for the aforementioned "Filters:" string
+/// @param {Number with size unit} $margin-on-desktop [0px] - Margin above/below SelectedFilters on desktop. This is set here because ExpandingContainer, our expanding component, gets confused when the margin isn't precisely on this element. Otherwise this value would be in ProductListingPage.scss.
+/// @param {Boolean} $set-border-on-crumbs [true] - Whether to set a border on the "crumbs" (a crumb is one selected filter).
+
 @mixin SelectedFilters(
   $border-radius: variables.$border-radius,
   $title-color: variables.$brand-black,

package/dist/styles/components/PLP/SlidableItems.scss

@@ -5,6 +5,7 @@
 @use "../../helpers/supports-hover";
 @use "sass:map";
 
+/// Mixin copy-pasted from @depict-ai/utilishared that helps with positioning slider buttons
 @mixin button_positioning {
   .d-navbutton {
     position: absolute;
@@ -47,7 +48,14 @@
   }
 }
 
+/// Styling for sliders used in the PLP.
+/// Most of the times slider is used for items laid out horizontally that do not fit the screen width.
+///
+/// Examples are the QuickLinks (used to navigate sideways or downwards in the category tree) and the SelectedFilters (if not all selected filters fit on the screen).
+/// @param {Color} $fade-to [variables.$brand-lighter-grey] - The color the slider buttons fade to, set this to the background color behind the slider.
+/// @param {Color} @fade-from [transparent] - The color the slider buttons fade from, you probably want to leave this at transparent.
 @mixin SlidableItems($fade-to: variables.$brand-lighter-grey, $fade-from: rgba(238, 238, 240, 0)) {
+  // TODO: we could probably infer these colours (and maybe some more) if we add some global background color variable
   .depict-slider {
     width: 100%;
     position: relative;

package/dist/styles/components/PLP/SortAndFilter/FloatingButtons.scss

@@ -1,6 +1,15 @@
 @use "../../../variables";
 @use "../../../helpers/supports-hover";
 
+/// Styles the FloatingButtons. FloatingButtons are three buttons, one button to open sorting, one button to open filters and one button to scroll to the top that show up when scrolling upwards for a while on a mobile device not really close to the top of the page.
+/// @param {Color} $button-background [variables.$brand-lighter-grey] - The background color of the buttons.
+/// @param {Color} $hovered-button-background [variables.$brand-lightest-grey] - The background color of the buttons when hovered.
+/// @param {Color} $button-border-color [variables.$brand-black] - The border color of the buttons.
+/// @param {Color} $icon-color [variables.$brand-dark-grey] - The color of the icons.
+/// @param {Number with unit} $bottom-distance [12px] - The distance from the bottom of the buttons to the bottom of the screen.
+/// @param {Number with unit} $side-distance [12px] - The distance from the `$position`-side of the buttons to the `$position`-side of the screen.
+/// @param {"left" | "right"} $position [left] - The side of the screen the buttons should be aligned to.
+
 @mixin FloatingButtons(
   $button-background: variables.$brand-lighter-grey,
   $hovered-button-background: variables.$brand-lightest-grey,

package/dist/styles/components/PLP/SortAndFilter/SortAndFilter.scss

@@ -8,6 +8,63 @@
 @use "sass:color";
 @use "sass:map";
 
+/// Mixin that styles the sorting and filtering menus.
+/// We probably want to refactor this quite soon so sorry for not writing descriptions
+/// You'll have to look at the code to see what the params do - I hope the names are somewhat descriptive.
+/// @param {Color} $mobile-top-level-collapse-color [variables.$brand-black] -
+/// @param {Color} $mobile-top-level-collapse-background [#fff] -
+/// @param {Color} $custom-input-checked-background [#fff] -
+/// @param {Color} $custom-input-background [#fff] -
+/// @param {Color} $custom-input-indicator-color [variables.$brand-black] -
+/// @param {Color} $checkbox-background-color [#fff] -
+/// @param {Color} $checkbox-checked-background-color [variables.$brand-black] -
+/// @param {Color} $checkbox-checkmark-color [#fff] -
+/// @param {Number with size unit} $checkbox-border-radius [if(variables.$border-radius == 0, 0, if(variables.$border-radius == 0px, 0, 2px))] -
+/// @param {Border} $checkbox-border [1px solid variables.$brand-black] -
+/// @param {Number with size unit} $checkbox-top-offset [0px] -
+/// @param {Number with size unit} $checkbox-left-offset [0px] -
+/// @param {Border} $radio-border [1px solid variables.$brand-black] -
+/// @param {Color} $radio-background-color [#fff] -
+/// @param {Color} $radio-selected-dot-color [variables.$brand-black] -
+/// @param {Number with size unit} $radio-selected-dot-size [14px] -
+/// @param {Number with size unit} $radio-selected-offset [0px] -
+/// @param {Color} $separator-color [variables.$brand-dark-grey] -
+/// @param {Color} $price-range-min-max-text-color [variables.$brand-dark-grey] -
+/// @param {Color} $range-input-bg-color [variables.$brand-lightest-grey] -
+/// @param {Color} $top-level-summary-background [variables.$brand-black] -
+/// @param {Color} $hovered-top-level-summary-background [variables.$brand-dark-grey] -
+/// @param {Color} $hovered-range-input-bg-color [variables.$brand-lighter-grey] -
+/// @param {Color} $hovered-checkbox-bg [variables.$brand-lighter-grey] -
+/// @param {false | Color} $hovered-checkbox-checked-background-color [false] -
+/// @param {Color} $input-row-label-color [variables.$brand-dark-grey] -
+/// @param {Color} $checked-input-row-label-color [#000] -
+/// @param {Number} $input-row-label-font-weight [400] -
+/// @param {Number} $checked-input-row-label-font-weight [500] -
+/// @param {Color} $showing-selected-subfilter-count-color [variables.$brand-grey] -
+/// @param {Color} $filter-available-products-color [variables.$brand-grey] -
+/// @param {Color} $count-zero-input-row-label-color [rgb(194, 194, 194)] -
+/// @param {Number with size unit} $spacing_between_input_rows [10px] -
+/// @param {Number with size unit} $ungrouped-top-margin [25px] -
+/// @param {Border} $hovered-checkbox-border [2px solid variables.$brand-black] -
+/// @param {Border} $hovered-radio-border [2px solid variables.$brand-black] -
+/// @param {Padding} $sort-and-filter-button-padding [10px 20px] -
+/// @param {Color} $expandable-seperator-color [variables.$brand-lightest-grey] -
+/// @param {Color} $expandable-seperator-hover-color [variables.$brand-lighter-grey] -
+/// @param {Number with size unit} $expandable-seperator-height [1px] -
+/// @param {Color} $filter-group-heading-color [#fff] -
+/// @param {Color} $filter-groups-morphing-sign-color [#fff] -
+/// @param {Number with size unit} $filter-group-summary-border-radius [4px] -
+/// @param {Color} $sort-and-filter-modal-background [variables.$brand-lighter-grey] -
+/// @param {Number with size unit} $filter-group-heading-padding [10px] -
+/// @param {Number with size unit} $filter-group-summary-spacings [10px] -
+/// @param {Number with size unit} $range-input-field-border-radius [4px] -
+/// @param {Border} $range-input-field-border [none] -
+/// @param {false | Number} $filter-group-title-bold [false] -
+/// @param {Color} $view-more-clear-background [rgb(253, 253, 253)] -
+/// @param {Color} $filter-collapsible-body-background [rgb(238, 238, 240)] -
+/// @param {Number | Boolean} $sort-and-filter-modal-section-title-font-weight [false] -
+/// @param {Number | Boolean} $sort-and-filter-modal-section-expanded-title-font-weight [$sort-and-filter-modal-section-title-font-weight] -
+
 @mixin SortAndFilter(
   $mobile-top-level-collapse-color: variables.$brand-black,
   $mobile-top-level-collapse-background: #fff,

package/dist/styles/components/PLP/SortAndFilter/WhiteSortAndFilter.scss

@@ -6,6 +6,10 @@
 @use "../../../helpers/supports-hover";
 @use "SortAndFilter";
 
+/// A wrapper around SortAndFilter that styles the sorting and filtering menus for the white theme by providing a default set of white variables.
+///
+/// ### Parameters
+/// See [SortAndFilter](#undefined-mixin-SortAndFilter) for parameters.
 @mixin WhiteSortAndFilter(
   $mobile-top-level-collapse-color: variables.$brand-black,
   $mobile-top-level-collapse-background: #fff,

package/dist/styles/components/PLP/Toast.scss

@@ -1,6 +1,11 @@
 @use "../../variables";
 @use "../../helpers/utils";
 
+/// Toast is a small, unobtrusive, banner that appears at the bottom of the page when we clear their filters when going sideways in the category tree (or they do it manually). The Toast has a button that allows them to get their filters back (restore them) in case they want it back.
+/// It's a general component otherwise and might also be used for other messages.
+/// @param {Number} $z-index [variables.$base-z-index * 5] - The z-index of the Toast.
+/// @param {Color} $progress-bar-color [variables.$brand-dark-grey] - The color of the progress bar below the toast that shows when it will auto-close.
+
 @mixin Toast($z-index: calc(#{variables.$base-z-index} + 5), $progress-bar-color: variables.$brand-dark-grey) {
   .depict.plp.toast {
     position: fixed;