+
+
+
+
+ `,
+ });
+
+ const routes = [
+ { path: '/', component: app.component('Content') },
+ { path: '/:path', component: app.component('Content') },
+ { path: '/:pathMatch(.*)', component: app.component('Content') },
+ ];
+
+ const router = VueRouter.createRouter({
+ history: VueRouter.createWebHistory(window.location.hostname !== 'localhost' ? `/${window.location.pathname.split('/')[1]}/` : undefined),
+ routes,
+ });
+ router.afterEach((to, from) => {
+ if (to.path !== from.path) {
+ // close navigation on mobile upon changing routes (not applicable to initial load)
+ if (window.innerWidth < 768 && document.getElementById('navigation')?.classList.contains('visible')) {
+ document.querySelector('.collapseNav')?.click();
+ }
+
+ // invoked here to handle removal when iframe is rendered
+ document.querySelector('.legend')?.remove();
+ }
+ });
+
+ app.use(router);
+
+ app.mount('#app');
+
+ const SCROLL_TO_HEADING_DELAY = 2000;
+ const DEBOUNCE_DELAY = 100;
+ window.postRenderModifications = function () {
+ let headingIdsInView = [];
+ let lastScrolledUp = true;
+ let lastScrollY = window.scrollY;
+ let hashId = window.location.hash.split('#')[1];
+ let preventLegendUpdate = Boolean(hashId); // if there is a hash id, prevent the legend from updating while scrolling
+ if (hashId) {
+ // scroll to heading if it exists in the url
+ const heading = document.getElementById(hashId);
+ if (heading && createHeadingId(heading) === hashId) {
+ heading.scrollIntoView({ behavior: 'smooth' });
+ heading.classList.add('scrolled-to');
+ window.setTimeout(function () {
+ heading.classList.remove('scrolled-to');
+ preventLegendUpdate = false;
+ }, SCROLL_TO_HEADING_DELAY);
+ } else {
+ // handle redirects of old routes
+ if (hashId === '/') {
+ router.replace('/');
+ } else if (hashId.match(/^\/components-preact/)) {
+ router.replace(hashId.replace(/^\/components-preact/, '/preact-components'));
+ } else if (hashId.match(/^\/integration-recommendations/)) {
+ router.replace('/snap-recommendations-integration');
+ } else if (hashId.match(/^\/snap-recommendations-legacy/)) {
+ router.replace('/snap-recommendations-legacy');
+ } else if (hashId.match(/^\/start-preact/)) {
+ router.replace('/getting-started');
+ } else if (hashId.match(/^\/start-preact-events/)) {
+ router.replace('/reference-snap-preact-middleware');
+ } else if (hashId.match(/^\/start-github/)) {
+ router.replace('/build-deploy');
+ } else if (hashId.match(/^\/start-setup/)) {
+ router.replace('/snap-setup');
+ }
+ }
+ }
+
+ // highlight code blocks
+ document.querySelectorAll('pre code').forEach((block) => {
+ hljs.highlightElement(block);
+ });
+
+ const handleScroll = debounce(() => {
+ if (window.scrollY > lastScrollY) {
+ lastScrolledUp = false;
+ } else {
+ lastScrolledUp = true;
+ }
+ lastScrollY = window.scrollY;
+ }, DEBOUNCE_DELAY);
+
+ window.addEventListener('scroll', handleScroll);
+
+ function updateLegend(id) {
+ if (preventLegendUpdate && !id) return;
+
+ document.querySelectorAll(`.legend a`).forEach((item) => {
+ item.classList.remove('active');
+ });
+ const activeHeadingId = id || headingIdsInView[lastScrolledUp ? 0 : headingIdsInView.length - 1];
+ const legendItem = document.querySelector(`.legend a[data-id="${activeHeadingId}"]`);
+ if (legendItem) {
+ legendItem.classList.add('active');
+ }
+ }
+
+ // update active legend item when clicked
+ // setTimeout is needed to prevent the legend from updating if observer fires
+ window.updateLegend = (id) => {
+ router.push({ hash: '#' + id });
+ document.getElementById(id).scrollIntoView({ behavior: 'instant' });
+ setTimeout(() => updateLegend(id), 1);
+ };
+
+ // adds ids to headings for permalinks and handles clicks to copy to clipboard
+ const headingsRaw = Array.from(document.querySelectorAll('#content h2, #content h3'));
+ const headings = headingsRaw.map((heading) => {
+ heading.role = 'link';
+ const id = createHeadingId(heading);
+ heading.id = id;
+ heading.addEventListener('click', () => {
+ const url = window.location.origin + window.location.pathname + '#' + id;
+ navigator.clipboard.writeText(url);
+ router.push({ hash: '#' + id });
+ const span = document.createElement('span');
+ span.textContent = 'Permalink copied!';
+ span.classList.add('permalink');
+ heading.prepend(span);
+ window.setTimeout(function () {
+ span.remove();
+ }, SCROLL_TO_HEADING_DELAY);
+ });
+ const observer = new IntersectionObserver((entries) => {
+ entries.forEach((entry) => {
+ if (entry.isIntersecting) {
+ headingIdsInView.push(entry.target.id);
+ } else {
+ headingIdsInView = headingIdsInView.filter((item) => item !== entry.target.id);
+ }
+ headingIdsInView.sort((a, b) => {
+ const aIndex = headingsRaw.findIndex((h) => h.id === a);
+ const bIndex = headingsRaw.findIndex((h) => h.id === b);
+ return aIndex - bIndex;
+ });
+ updateLegend();
+ });
+ });
+ observer.observe(heading);
+ return heading;
+ });
+
+ // adds a legend to the top of the page with links to the headings
+ if (headings.length) {
+ const legend = document.createElement('div');
+ legend.classList.add('legend');
+ const title = document.querySelector('#content h1')?.textContent;
+ legend.innerHTML =
+ `
+
+
+ 
+
+
+
+
+
+ ` +
+ (title ? `
`;
+ document.getElementById('content').prepend(legend);
+ // scroll active legend item into view
+ const activeLegendItem = document.querySelector('.legend a.active');
+ if (activeLegendItem) {
+ activeLegendItem.scrollIntoView({ behavior: 'instant' });
+ }
+ }
+ };
+
+ function debounce(func, wait) {
+ let timeout;
+ return function executedFunction(...args) {
+ const later = () => {
+ clearTimeout(timeout);
+ func(...args);
+ };
+ clearTimeout(timeout);
+ timeout = setTimeout(later, wait);
+ };
+ }
+
+ function createHeadingId(heading) {
+ return heading.id || 'id-' + heading.textContent.toLowerCase().replace(/ /g, '-');
+ }
+});
diff --git a/docs/404.md b/docs/404.md
index 50ba99565b..883d8cf102 100644
--- a/docs/404.md
+++ b/docs/404.md
@@ -1,4 +1,4 @@
${title}
` : '') +
+ `
+ -
+ ${headings
+ .map((h) => {
+ const id = h.id;
+ const text = h.textContent;
+ const level = h.tagName.toLowerCase();
+ return `
- ${text} `; + }) + .join('')} +
- 404 - This link is broken... sorry.
+ This link may no longer exist. Please find the content you are looking for in the side navigation or attempt to search for it.
\ No newline at end of file
diff --git a/docs/ABOUT.md b/docs/ABOUT.md
index 926994f77b..00dd1118be 100644
--- a/docs/ABOUT.md
+++ b/docs/ABOUT.md
@@ -1,15 +1,39 @@
-## What is Snap?
+# Snap Documentation
-Snap is not an acronym! Snap is Searchspring's open source SDK for integrating into front end web apps. It replaces the previous version - v3.
+Snap is not an acronym! Snap is an open source SDK for building e-commerce experiences powered by Searchspring.
-Snap supports Searchspring's latest features and API release for lightning fast performance.
+The SDK includes multiple core packages published to npm that in combination with each other, provide the complete front-end tooling for building e-commerce experiences with Searchspring. However to simplify usage, the `@searchspring/snap-preact` package is an abstraction that combines all core packages into a single dependency in combination with Preact to render the UI. This documentation is primarily focused on the usage of this package.
-Snap also supports integration with modern front end frameworks such as React and Vue. In addition, we've also released a full [React component library](https://searchspring.github.io/snap/#/components-preact) to get you up and running quickly.
+## Getting Started
+This documentation is organized into two sections: Snap Integration and API Integration. Depending on how you're going to integrate Snap, you'll want to reference the correct section to get started.
-## Getting Started
+
+
+Additionally, the Reference section contains the most comprehensive and technical material that is common between all integration types and is linked to from other sections.
+
+### Snap Integration
+
+A "Snap Integration" is a project that uses the `Snap` export from the `@searchspring/snap-preact` package to build a storefront integration. It provides the ability to create multiple controllers, custom plugins, and full custom markup to match the storefront markup and inherit styles. It is the most flexible and powerful way to integrate Searchspring into your storefront.
+
+An example Snap Integration project can be found [here](https://github.com/searchspring-implementations/demo.shopify).
+
+Continue by referencing the [Snap Setup](https://searchspring.github.io/snap/snap-setup) section.
+
+### Snap Templates Integration
+
+A "Snap Templates Integration" is a project that uses the `SnapTemplates` export from the `@searchspring/snap-preact` package to build a storefront integration. It is an abstraction of the `Snap` integration that limits the available configuration and does not provide access to the entire project markup.
+
+Instead, it is based on choosing an optimimzed and prebuilt template and theme while only customizing slight layout changes, theme variables, result card markup, and general style declarations. This integration type allows for a rapid integration of Searchspring to your storefront.
+
+Continue by referencing the [Snap Templates Integration](https://searchspring.github.io/snap/templates-about) documentation.
+
+### API Integration
+
+An "API Integration" is a project that utilizes the Searchspring APIs directly to integrate into your custom storefront project. Although not required, we recommend using just the `@searchspring/snap-client` package to fetch data from Searchspring APIs.
+
+Continue by referencing the [API Integration](https://searchspring.github.io/snap/snap-client) section.
-Check out the [Getting Started](https://searchspring.github.io/snap/#/start-setup) guide to jump right in!
## Contributing
@@ -18,8 +42,3 @@ Snap is open source! The repository can be found on [Github](https://github.com/
We invite your participation through Github issues, discussions and pull requests!
Please reference Searchspring's [Community Contribution Guidelines](https://github.com/searchspring/community/blob/main/CONTRIBUTING.md) before contributing.
-
-
-## Documentation
-
-For all Snap documentation, see the [Snap Docs](https://searchspring.github.io/snap/).
diff --git a/docs/ADVANCED.md b/docs/ADVANCED.md
deleted file mode 100644
index aaae46d582..0000000000
--- a/docs/ADVANCED.md
+++ /dev/null
@@ -1,8 +0,0 @@
-## Advanced Snap Usage
-
-If a controller or service is needed with configuration outside of what is permited by the Snap abstraction layer, one can be created by following the docs in this section.
-
-It is recommended to use the Snap abstraction layer packages whenever possible - these packages quickly create Snap controllers using a config based interface. Underneath the hood the Snap abstraction packages utilize all of the core Snap packages that will be outlined here.
-
-### Snap abstraction Packages
-[@searchspring/snap-preact](https://github.com/searchspring/snap/tree/main/packages/snap-preact)
\ No newline at end of file
diff --git a/docs/ADVANCED_AUTOCOMPLETE.md b/docs/ADVANCED_AUTOCOMPLETE.md
deleted file mode 100644
index 9eee744951..0000000000
--- a/docs/ADVANCED_AUTOCOMPLETE.md
+++ /dev/null
@@ -1,102 +0,0 @@
-## Autocomplete
-To set up Autocomplete using Snap, we'll need to create a `AutocompleteController` instance, which requires `AutocompleteControllerConfig` and `ControllerServices` objects to instantiate. For more details see the [`AutocompleteController docs`](https://github.com/searchspring/snap/tree/main/packages/snap-controller/src/Autocomplete).
-
-### Config (AutocompleteControllerConfig)
-Let's define an `AutocompleteControllerConfig` object:
-
-```typescript
-const autocompleteConfig = {
- id: 'autocomplete',
- selector: '#search_query',
- globals: {
- suggestions: {
- count: 4,
- },
- pagination: {
- pageSize: 6,
- },
- },
- settings: {
- initializeFromUrl: true,
- syncInputs: false,
- facets: {
- trim: true
- },
- },
-}
-```
-
-### Autocomplete Controller Services
-The `ControllerServices` object contains all of the controller's dependencies. Note the difference between SearchController's ControllerServices is the different store. Here we are using `AutocompleteStore`
-
-Note that the `UrlManager` is utilizing the `UrlTranslator` which will use `'q'` as the URL query parameter. This can be overwritten to use `'search_query'` by providing a by providing a `parameters.core.query` [config](https://github.com/searchspring/snap/tree/main/packages/snap-url-manager/src/Translators/Url) such as in this example:
-
-```typescript
-const autocompleteUrlManager = new UrlManager(new UrlTranslator({ parameters: core: { query: { name: 'search_query' } } }), reactLinker).detach();
-const autocompleteControllerServices = {
- client,
- store: new AutocompleteStore(autocompleteConfig, { urlManager: autocompleteUrlManager }),
- urlManager: new UrlManager(new UrlTranslator({ queryParameter: 'search_query' }), reactLinker),
- eventManager: new EventManager(),
- profiler: new Profiler(),
- logger: new Logger(),
- tracker
-}
-```
-
-The translator type should be the same between Autocomplete and Search Controllers in order for compatible URLs to be generated.
-
-Note: `client` and `tracker` are shared services and are defined in previous steps.
-
-### Instantiation
-With the `AutocompleteControllerConfig` and `ControllerServices` defined, we can now create an instance of a `AutocompleteController`.
-
-```typescript
-const autocompleteController = new AutocompleteController(autocompleteConfig, autocompleteControllerServices);
-```
-
-### Middleware
-Autocomplete supports middleware to hook into various events using `plugin` and `on` methods. See [Search Middlewear](https://github.com/searchspring/snap/blob/main/docs/SEARCH.md) for usage
-
-
-### DomTargeter
-Similar to Search DomTargeter, the following example shows how to use the DomTargeter with an `AutocompleteController` and passing that controller as a prop to a `Autocomplete` component (not shown). After the target has been found it injects a new element ('.ss-ac-target') and then uses the Preact render function to render the component into the newly created element.
-
-For further usage and documentation, see [DomTargeter](https://github.com/searchspring/snap/tree/main/packages/snap-toolbox/src/DomTargeter).
-
-```typescript
-new DomTargeter(
- [
- {
- selector: autocompleteController.config.selector, // input element that we are binding to
- inject: {
- action: 'after', // injecting an element after the input
- element: (target, origElement) => {
- const acContainer = document.createElement('div');
- acContainer.id = 'ss-ac-target';
- acContainer.addEventListener('click', (e) => {
- e.stopPropagation();
- });
- return acContainer;
- },
- },
- },
- ],
- (target, injectedElem, inputElem) => {
- // bind to config selector
- autocompleteController.bind();
- render(
Search
- -To set up Search using Snap, we'll need to create a `SearchController` instance, which requires `SearchControllerConfig` and `ControllerServices` objects to instantiate. For more details see the [`SearchController docs`](https://github.com/searchspring/snap/tree/main/packages/snap-controller/src/Search). - -### Config (SearchControllerConfig) -Let's define a `SearchControllerConfig` object: -```typescript -const searchConfig = { - id: 'search', - globals: { - filters: [], - }, - settings: { - redirects: { - merchandising: true, - singleResult: true, - }, - facets: { - trim: true, - } - }, -}; -``` - - -### Category Pages / Background Filters -Optionally, apply filters from the page's content to the SearchControllerConfig `globals.filters` property. The controller globals are similar to the client globals in that all search requests will include the parameters specified. This can be used to configure category/brand pages, or other special filtering to apply to the current page's search requests. - -For example, if a global variable `snapConfig` exists on the page (must be defined prior to our Snap script): - -```html - -``` - -```typescript -if (snapConfig?.category) { - searchConfig.globals.filters.push({ - type: 'value', - background: true, - field: 'categories_hierarchy', - value: snapConfig.category.value, - }); -} -``` - - -### ControllerServices -The `ControllerServices` object contains all of the controller's dependencies. - -Note that the `UrlManager` is created separately because it is a shared dependency; it is also a service needed for the `SearchStore`. The `UrlManager` is utilizing the `UrlTranslator` which will use `'q'` as the default URL query parameter. This can be overwritten to use `'search_query'` by providing a `parameters.core.query` [config](https://github.com/searchspring/snap/tree/main/packages/snap-url-manager/src/Translators/Url) such as in this example: - -```typescript -const searchUrlManager = new UrlManager(new UrlTranslator({ parameters: core: { query: { name: 'search_query' } } }), reactLinker); -const searchControllerServices = { - client, - store: new SearchStore(searchConfig, { urlManager, searchUrlManager }), - urlManager: searchUrlManager, - eventManager: new EventManager(), - profiler: new Profiler(), - logger: new Logger(), - tracker -} -``` - -Note: `client` and `tracker` are shared services and are defined in previous steps. - -### Instantiation -With the `SearchControllerConfig` and `ControllerServices` defined, we can now create an instance of a `SearchController`. - -```typescript -const searchController = new SearchController(searchConfig, searchControllerServices); -``` - -Middleware
- -Now that our `SearchController` is instantiated (using `searchController` variable), we can optionally attach middleware to hook into various events. There are two ways of doing this, using the Controller's `on` or `plugin` methods. - -#### via `on` method: - -```typescript -searchController.on('afterStore', async ({ controller }, next) => { - controller.log.debug('store', controller.store.toJSON()); - await next(); -}) -``` - -#### via `plugin` method (to attach groups of middleware): - -```typescript -const middleware = (controller) => { - controller.on('init', async({ controller }, next) => { - controller.log.imageText({ - url: 'https://searchspring.com/wp-content/themes/SearchSpring-Theme/dist/images/favicons/favicon.svg', - text: 'snap integration initialized', - style: `color: ${controller.log.colors.indigo}; font-weight: bold;`, - }); - - await next(); - }); - // log the store - controller.on('afterStore', async({ controller }, next) => { - controller.log.debug('store', controller.store.toJSON()); - await next(); - }); -}; - -searchController.plugin(middleware); -``` - -DomTargeter
- -`DomTargeter` is a utility for rending components in specified DOM targets. The following example shows how to use the DomTargeter with a `SearchController` and passing that controller as a prop to a `Content` component (not shown). It uses the Preact render function to render the component after the target has been found. - -For further usage and documentation, see [DomTargeter](https://github.com/searchspring/snap/tree/main/packages/snap-toolbox/src/DomTargeter). - -```typescript -const contentTarget = new DomTargeter( - [ - { - selector: '#searchspring-content', // CSS selector for element to render component into - }, - ], - (target, elem) => { - // run search after finding target - controller.search(); - render(
+
+This will also be persisted across page navigation. To stop previewing a branch build, you must click the `Stop Preview` button in the interface or clear the `ssBranch` cookie. The interface can also be minimized.
+
+## Modern vs Universal Builds
+
+If your project is hosted in Searchspring's Github organization, we'll automatically handle serving the appropriate version of the build files for you. However if you are hosting your own build files, you can either:
+
+- only serve the modern build to all users, however this will break functionallity for IE11.
+- change the build targets, although this may impact core web vitals negatively.
+- serve the appropriate bundle via a check of the userAgent. More information below.
+
+Always serve the build to modern browsers and the universal build only to legacy browsers. Serving universal builds to modern browsers negatively impacts Core Web Vitals:
+
+```html
+
+
+
+
+
+```
+
+The modern build is used for projects targeting the latest browsers supporting the latest JavaScript features (ES6 and above). Example modern build files: `bundle.js` & `bundle.chunk.[hash].js`
+
+A browser is considered modern based on the [@searchspring/browserslist-config-snap modern](https://github.com/searchspring/browserslist-config-snap/blob/main/modern/index.js) rules and is included in the preconfigured scaffold.
+
+
+The universal build is used for projects targeting legacy browsers and will transpile any usage of modern JavaScript to ES5 as well as polyfill any missing browser features. If you are not targeting legacy browsers, you can omit deploying the universal built files that are prefixed with `universal.` - Example: `universal.bundle.js` and `universal.bundle.chunk.[hash].js`
+
+A browser is considered legacy based on the [@searchspring/browserslist-config-snap universal](https://github.com/searchspring/browserslist-config-snap/blob/main/universal/index.js) rules and is included in the preconfigured scaffold.
+
+However, if you are targeting legacy browsers, it is not recommended to always serve the universal build files to all browsers—including modern browsers—as this will impact Core Web Vitals and performance negatively.
+
+Therefore, you will require a method for switching the front-end script `src` to point to the appropriate version of the build files depending on whether the browser is modern or legacy. This can be done in many ways, including:
+
+- Server-side checking the userAgent and serving the appropriate version of the build files.
+- Front-end checking the userAgent and serving the appropriate version of the build files.
+- Lambda function serving the appropriate version of the build files based on the userAgent.
+
+The following is an example of a regex that would match the versions of the `browserlist-config-snap@1.0.7` rules:
+
+```js
+module.exports = /((CPU[ +]OS|iPhone[ +]OS|CPU[ +]iPhone|CPU IPhone OS)[ +]+(14|(1[5-9]|[2-9]\d|\d{3,})|15|(1[6-9]|[2-9]\d|\d{3,}))[_.]\d+(?:[_.]\d+)?)|((?:Chrome).*OPR\/(77|(7[8-9]|[8-9]\d|\d{3,}))\.\d+\.\d+)|(Edge\/(91|(9[2-9]|\d{3,}))(?:\.\d+)?)|((Chromium|Chrome)\/(91|(9[2-9]|\d{3,}))\.\d+(?:\.\d+)?)|(Version\/(14|(1[5-9]|[2-9]\d|\d{3,})|15|(1[6-9]|[2-9]\d|\d{3,}))\.\d+(?:\.\d+)? Safari\/)|(Firefox\/(74|(7[5-9]|[8-9]\d|\d{3,}))\.\d+\.\d+)|(Firefox\/(74|(7[5-9]|[8-9]\d|\d{3,}))\.\d+(pre|[ab]\d+[a-z]*)?)/;
+```
+(regex generated using [browserslist-useragent-regexp](https://www.npmjs.com/package/browserslist-useragent-regexp))
+
+
+
+## Build Tools
+
+Webpack is the default choice of build tooling that all Snapfu templates include and will be preconfigured.
+
+If you are integrating `@searchspring/snap-preact` using other build tools, you may require certain plugins to ensure preact compatibility.
+
+We hope to maintain this page with the most common build tools and their respective plugins as we discover them.
+
+
+### Vite
+
+[@preact/preset-vite](https://github.com/preactjs/presets/tree/main/packages/preset-vite) is a plugin for Vite that allows you to use Preact in your Vite project.
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite'
+import preact from '@preact/preset-vite'
+
+// https://vite.dev/config/
+export default defineConfig({
+ plugins: [preact()],
+})
+```
\ No newline at end of file
diff --git a/docs/BUILD_DEPLOY_CHECKLIST.md b/docs/BUILD_DEPLOY_CHECKLIST.md
new file mode 100644
index 0000000000..204f3e4b97
--- /dev/null
+++ b/docs/BUILD_DEPLOY_CHECKLIST.md
@@ -0,0 +1,35 @@
+# QA Checklist
+
+## Integration Code Checklist
+
+- [Background Filters](./snap-background-filters) are being read from script context and applied as client globals to handle Category pages.
+
+- (If applicable) [Foreground Filters](./snap-background-filters) are added as client globals to handle custom filtering (ie. only show results in stock)
+
+- Merchandising [Banner](https://searchspring.github.io/snap/preact-components?params=%3Fpath%3D%2Fstory%2Fatoms-banner--footer) components have been added for all banner locations: `header`, `banner`, `footer`, `left`. See [Search > Search Store Merchandising](./snap-search#searchcontrollerstoremerchandising)
+
+- [InlineBanner](https://searchspring.github.io/snap/preact-components?params=%3Fpath%3D%2Fstory%2Fatoms-inlinebanner--default) component is conditionally rendered in your Results component. See [Search > Search Store Results](./snap-search#searchcontrollerstoreresults)
+
+- [Result impression tracking](./snap-tracking#impressions) has been added. Confirm via browser dev tools network tab that beacon impression events are being sent for results in Search, Category, Autocomplete, and Recommendations
+
+- [Result click tracking](./snap-tracking#product-click) has been added. (not required if using `withTracking` or `ResultTracker` as this functionallity is handled by those components)
+
+- [Result add to cart tracking](./snap-tracking#product-add-to-cart) has been added. Confirm via browser dev tools network tab that beacon add to cart events are being sent for results in Search, Category, Autocomplete, and Recommendations
+
+- (If enabled) Self-configured [Badges](./snap-badges) are added to your Result component
+
+- No Results component text has been personalized for your store (ie. contains support contact and storefront address information)
+
+## Platform Integration Checklist
+
+- [Shopper Login tracking](./snap-tracking#shopper-login) has been added. Confirm via browser dev tools network tab that beacon shopper login events are being sent only when a shopper is logged in
+
+- [Currency tracking](./snap-tracking#currency) has been added. Confirm via browser dev tools network tab that beacon events contain currency code in data payload for any event. If using a single currency, this is not required.
+
+- [Product view tracking](./snap-tracking#product-view). Confirm via browser dev tools that last viewed products cookie is being updated when a product is viewed.
+
+- [Order transaction tracking](./snap-tracking#order-transaction) has been added. Confirm via browser dev tools network tab that beacon order transaction events are being sent only when an order is completed.
+
+- [Cart contents tracking](./snap-tracking#cart-contents) has been added. Confirm via browser dev tools network tab that beacon cart add and remove events are being sent when cart contents change.
+
+- (If applicable) Realtime recommendations requires [Cart Attribute Tracking](./snap-tracking#cart-attribute-tracking)
diff --git a/docs/INTEGRATION_CONTEXT.md b/docs/BUILD_DEPLOY_INTEGRATION.md
similarity index 57%
rename from docs/INTEGRATION_CONTEXT.md
rename to docs/BUILD_DEPLOY_INTEGRATION.md
index a747c49a6f..4dce7a4046 100644
--- a/docs/INTEGRATION_CONTEXT.md
+++ b/docs/BUILD_DEPLOY_INTEGRATION.md
@@ -1,15 +1,48 @@
+# Integration
+
+After building the project and uploading the build files to your CDN or hosting provider, you will need to add a script tag to your storefront.
+
+
+```html
+
+```
+
+The bundle should be included in the tag, ideally near the top of the node, and should not have a 'defer' or 'async' attribute. This location is important in order to start fetching results and as soon as possible. This placement prior to any body elements also serves to allow for the hiding of targeted elements that contain content - this preventing a flash when the contents change upon injection.
+
+
+```html
+
+
+
+
+
+
+
+
+
+```
+
+### Use Skeleton Components
+
+We recommended using server-side rendered skeletons inside the target elements for the best LCP performance. If this is the case, also set the `renderAfterSearch` property to `true`.
+
+```html
+
+
+
+
+
+
+```
+
+```jsx
+import { Snap } from '@searchspring/snap-preact';
+
+const config = {
+ controllers: {
+ search: [{
+ config: {
+ id: 'search',
+ },
+ targeters: [{
+ selector: '#searchspring-content',
+ component: () => import('./Search'),
+ renderAfterSearch: true, // Render the skeleton after search is ready
+ }]
+ }]
+ }
+};
+```
+
+### Set Image Dimensions
+
+Ensure product images have defined dimensions to prevent layout shifts:
+
+```css
+.ss__image img {
+ width: 100%;
+ height: auto;
+ aspect-ratio: 1 / 1; /* Maintain aspect ratio */
+}
+```
+
+Or use the `style` prop on Image components:
+
+```jsx
+
-
-This will also be persisted across page navigation. To stop previewing a branch build, you must click the `Stop Preview` button in the interface or clear the `ssBranch` cookie. The interface can also be minimized.
-
-
-## Development Mode
-
-While browsing a page that contains a Snap integration, appending the `?dev` query parameter to the URL will set the controller's `environment` property to `development`.
-
-This is commonly used to enable visibility of development logs in the console.
-
-See [AbstractController](https://github.com/searchspring/snap/tree/main/packages/snap-controller/src/Abstract) and [@searchspring/snap-logger](https://github.com/searchspring/snap/tree/main/packages/snap-logger)
-
diff --git a/docs/INTEGRATION_VARIANTS.md b/docs/INTEGRATION_VARIANTS.md
index 285bb99b49..4be5ac144a 100644
--- a/docs/INTEGRATION_VARIANTS.md
+++ b/docs/INTEGRATION_VARIANTS.md
@@ -9,48 +9,7 @@ Product variants allow you to represent different versions of the same base prod
Snap's variants functionality helps manage these product variations by providing tools to configure, display and interact with variant data in your components.
-Configure variants by setting the variant field in either:
-- Controller config: `controllers[controller].config.settings.variants.field`
-- Recommendation config: `instantiators.recommendation.config.settings.variants.field`
-
-Example -
-
-```typescript
-const config = {
- instantiators: {
- recommendation: {
- components: {
- Bundle: async () => (await import('./components/Recommendations/Bundle/Bundle')).Bundle,
- },
- config: {
- settings: {
- variants: {
- field: 'ss_variants',
- },
- },
- },
- },
- },
- controllers: {
- search: [
- {
- config: {
- id: 'search',
- settings: {
- variants: {
- field: 'ss_variants',
- },
- },
- },
- },
- ],
- },
-};
-
-const snap = new Snap(config);
-```
-
-Once configured, each result that has variants in `controller.store.results` should include a `variants` object with:
+The Athos API will automatically return variants data when applicable. When this happens, each result that has variants in `controller.store.results` will include a `variants` object with:
**Properties:**
- `active` - Currently selected variant data
@@ -175,7 +134,6 @@ const config = {
config: {
settings: {
variants: {
- field: 'ss_variants',
realtime: {
enabled: true,
},
@@ -234,7 +192,6 @@ You can filter which results update in realtime by adding filters to your config
Example -
```typescript
variants: {
- field: 'ss_variants',
realtime: {
enabled: true,
filters: ['first']
diff --git a/docs/PREACT.md b/docs/PREACT.md
deleted file mode 100644
index 46aa55f31f..0000000000
--- a/docs/PREACT.md
+++ /dev/null
@@ -1,13 +0,0 @@
-## Snap Preact
-
-The [@searchspring/snap-preact](#/package-preact) package is an abstraction layer for Preact that provides a config based interface for creating a Searchspring integration quickly. Underneath the hood it utilizes all of the core Snap packages. If you wish to create a Snap integration using core packages individually (hard mode), see the Advanced section.
-
-If you are not using Snapfu to start with a template, you will need to start by adding Snap to your project.
-
-```bash
-npm install --save @searchspring/snap-preact
-```
-
-```typescript
-import { Snap } from '@searchspring/snap-preact';
-```
\ No newline at end of file
diff --git a/docs/PREACT_CONFIG.md b/docs/PREACT_CONFIG.md
deleted file mode 100644
index 35bfcf04f0..0000000000
--- a/docs/PREACT_CONFIG.md
+++ /dev/null
@@ -1,149 +0,0 @@
-## Configuration
-
-Let's define our config. The config that is provided to Snap will create and return controllers that are specified in the config. In this example, we will be creating a Search and Autocomplete controller.
-
-```typescript
-const config = {
- features: {
- integratedSpellCorrection: {
- enabled: true,
- },
- },
- url: {
- parameters: {
- core: {
- query: { name: 'query' }
- }
- }
- },
- client: {
- globals: {
- siteId: 'xxxxxx',
- },
- },
- controllers: {
- search: [
- {
- config: {
- id: 'search',
- },
- targeters: [
- {
- selector: '#searchspring-content',
- component: () => Content,
- skeleton: () => ContentSkel,
- hideTarget: true,
- },
- {
- selector: '#searchspring-sidebar',
- component: () => Sidebar,
- skeleton: () => SidebarSkel,
- hideTarget: true,
- },
- ],
- },
- ],
- autocomplete: [
- {
- config: {
- id: 'autocomplete',
- selector: 'input.searchspring-ac',
- settings: {
- trending: {
- limit: 5,
- },
- },
- },
- targeters: [
- {
- selector: 'input.searchspring-ac',
- component: () => Autocomplete,
- hideTarget: true,
- },
- ],
- },
- ],
- },
-};
-```
-
-Let's go over a few things.
-
-`config.url` is optional and contains a [`UrlTranslator` config](https://github.com/searchspring/snap/tree/main/packages/snap-url-manager/src/Translators/Url) object that is passed to the core [@searchspring/snap-url-manager](https://github.com/searchspring/snap/tree/main/packages/snap-url-manager) package used by all controllers. This parameter configuration will be applied to all controllers created via Snap, but can be specified per controller for specific customization.
-
-`config.client` is required and contains a config object that is passed to the core [@searchspring/snap-client](https://github.com/searchspring/snap/tree/main/packages/snap-client) package. This service handles the network requests to our APIs to retrieve data to be displayed.
-
-`config.client.globals` specifies base query parameters to the API; these are parameters that will ALWAYS be included on every request. At the bare minimum, `siteId` is required and can be obtained in the [Searchspring Management Console](https://manage.searchspring.net/)
-
-`config.controllers` specifies all of the controllers that we wish to create. In this this example we are creating a Search and Autocomplete controller. In addition, Finder and Recommendation services can also be specified.
-
-### Search
-
-Lets look at the Search controller that we are creating.
-
-The `config` object contains all controller configurations. The most notable property here is the required `id` with a given value of `'search'`. This will be the name of the search controller that we can then interface with the return of the `new Snap()` instance via the `getController` method. In snap-preact controllers are created only as needed (typically when a targeter has found a target), their creation is an asynchronous process. The `getController` method will return a promise that will resolve to the controller object requested immediately after its creation.
-
-For example:
-
-```typescript
-const snap = new Snap(config);
-snap.getController('search').then((search) => {
- // do things with controller
-});
-```
-
-If multiple controllers are needed at the same time, usage of the `getControllers` method is necessary. The `getControllers` method returns a promise that resolves to an array of controllers in the order requested by the parameters. The promise only resolves when ALL of the controllers have been created - if a controller is specified that is never created the promise will never resolve. For this reason this method should only be used when all controllers are needed simultaneously.
-
-```typescript
-const snap = new Snap(config);
-snap.getControllers('search', 'autocomplete').then(([search, autocomplete]) => {
- // do things with controllers
-});
-```
-
-We also have a `targeters` array of DomTargeter `targeter` configuration objects. Each object defines an entry point on the page where a component will be rendered.
-
-`targeter.selector` specifies the DOM selector to target
-
-`targeter.component` specifies a function that returns a reference to the component to render at the target selector.
-
-`targeter.hideTarget` boolean that specifies if the target node should be hidden before the component is mounted and rendered. It is recommended to enable this to prevent flashy behaviour.
-
-`targeter.autoRetarget` (optional) boolean that specificies if the targeter should continuously query for the selector in the DOM until it finds it and triggers a retarget. This is useful for dynamically generated selectors that might not exist at dom ready.
-
-`targeter.skeleton` (optional) meant to be used as a "loading" component. This specifies a function that returns a reference to the component to render immediately at the target selector to show briefly while the data is returning and the real component is rendering. You can use any component you want for this, although `snap-preact-components` provides a `skeleton` component for you to use if preferred.
-
-`targeter.props` (optional) convenient way of passing additional props to the component, by default we pass `controller`
-
-`targeter.onTarget` (optional) callback that fires after a target is found
-
-`targeter.name` (optional) name to give the targeter for later reference using `controller.targeters`
-
-In our example, we are rendering a `` and the `` component into `