sfcc-dev-mcp 1.0.19 → 1.0.21

package/docs/sfra/product-search.md

@@ -1,245 +0,0 @@
-# SFRA Product Search Model
-
-## Overview
-
-The Product Search model represents search functionality in SFRA applications, providing comprehensive search results, refinements, sorting options, and pagination for product discovery and catalog browsing.
-
-## Constructor
-
-```javascript
-function ProductSearch(productSearch, httpParams, sortingRule, sortingOptions, rootCategory)
-```
-
-Creates a Product Search model instance with search results and related functionality.
-
-### Parameters
-
-- `productSearch` (dw.catalog.ProductSearchModel) - Product search object from the API
-- `httpParams` (Object) - HTTP query parameters including search terms and refinements
-- `sortingRule` (string) - Current sorting rule being applied
-- `sortingOptions` (dw.util.ArrayList<dw.catalog.SortingOption>) - Options to sort search results
-- `rootCategory` (dw.catalog.Category) - Search result's root category if applicable
-
-## Properties
-
-### searchKeywords
-**Type:** string
-
-The search keywords entered by the user.
-
-### category
-**Type:** Object | null
-
-Current category information if this is a category-based search.
-
-### productIds
-**Type:** Array<Object>
-
-Array of product information objects with `productID` and `productSearchHit` properties for search results.
-
-### products
-**Type:** Array<Object>
-
-Array of product tile models for the search results. **Note:** This property is not directly set by the constructor but would be populated by calling code using the `productIds` array.
-
-### pageNumber
-**Type:** number
-
-Current page number for pagination (1-based).
-
-### pageSize
-**Type:** number
-
-Number of products displayed per page (from httpParams.sz or default).
-
-### count
-**Type:** number
-
-Total number of products found matching the search criteria.
-
-### isCategorySearch
-**Type:** boolean
-
-Indicates whether this is a category-based search.
-
-### isRefinedCategorySearch
-**Type:** boolean
-
-Indicates whether this is a refined category search.
-
-### resetLink
-**Type:** string
-
-URL to reset all search refinements (AJAX endpoint).
-
-### resetLinkSeo
-**Type:** string
-
-SEO-friendly URL to reset all search refinements.
-
-### refinements
-**Type:** Array<Object> (computed property)
-
-Array of available search refinements including:
-- `displayName` - Human-readable refinement name
-- `isCategoryRefinement` - Boolean flag for category refinements
-- `isAttributeRefinement` - Boolean flag for attribute refinements
-- `isPriceRefinement` - Boolean flag for price refinements
-- `isPromotionRefinement` - Boolean flag for promotion refinements
-- `values` - Array of refinement value objects
-
-### selectedFilters
-**Type:** Array<Object> (computed property)
-
-Array of currently applied refinements extracted from the refinements.
-
-### productSort
-**Type:** ProductSortOptions
-
-Available sorting options for the search results (ProductSortOptions model instance).
-
-### bannerImageUrl
-**Type:** string | null
-
-URL for category banner image (null if not available).
-
-### showMoreUrl
-**Type:** string
-
-URL to load more search results (for infinite scroll or "show more" functionality).
-
-### permalink
-**Type:** string
-
-Permalink URL for the current search with filters and pagination preserved.
-
-### isSearchSuggestionsAvailable
-**Type:** boolean
-
-Indicates whether search suggestions are available for the current search.
-
-### suggestionPhrases
-**Type:** Array<Object>
-
-Array of suggested search phrases with `value` and `url` properties (only available when `isSearchSuggestionsAvailable` is true).
-
-### category
-**Type:** Object | null
-
-Current category information if this is a category-based search, including:
-- `name` - Category display name
-- `id` - Category ID
-- `pageTitle` - Category page title
-- `pageDescription` - Category page description  
-- `pageKeywords` - Category page keywords
-
-### pageMetaTags
-**Type:** Object
-
-Page meta tags for SEO purposes.
-
-## Helper Functions
-
-### getResetLink(search, httpParams, actionEndpoint)
-Generates URL to remove all refinements and reset search criteria.
-
-**Parameters:**
-- `search` (dw.catalog.ProductSearchModel) - Product search object
-- `httpParams` (Object) - Query parameters
-- `actionEndpoint` (string) - Action endpoint to use
-
-**Returns:** string - URL to reset search refinements
-
-### getRefinements(productSearch, refinements, refinementDefinitions)
-Retrieves and formats search refinements for display.
-
-**Parameters:**
-- `productSearch` (dw.catalog.ProductSearchModel) - Product search object
-- `refinements` (dw.catalog.ProductSearchRefinements) - Search refinements
-- `refinementDefinitions` (ArrayList) - Refinement definitions
-
-**Returns:** Array<Object> - Formatted refinement objects
-
-## Usage Example
-
-```javascript
-var ProductSearch = require('*/cartridge/models/search/productSearch');
-
-// From search controller
-var productSearch = new ProductSearch(
-    apiProductSearch,
-    req.querystring,
-    sortingRule,
-    sortingOptions,
-    rootCategory
-);
-
-// Access search results
-console.log('Found ' + productSearch.count + ' products');
-console.log('Search term: ' + productSearch.searchKeywords);
-
-// Display product IDs (products would be populated separately)
-productSearch.productIds.forEach(function(item) {
-    console.log('Product ID: ' + item.productID);
-});
-
-// Handle refinements
-productSearch.refinements.forEach(function(refinement) {
-    console.log(refinement.displayName + ':');
-    refinement.values.forEach(function(value) {
-        console.log('  ' + value.displayValue + ' (' + value.hitCount + ')');
-    });
-});
-
-// Pagination
-console.log('Page ' + productSearch.pageNumber + ', showing ' + productSearch.pageSize + ' items');
-
-// Check for search suggestions
-if (productSearch.isSearchSuggestionsAvailable) {
-    productSearch.suggestionPhrases.forEach(function(phrase) {
-        console.log('Suggested: ' + phrase.value);
-    });
-}
-```
-
-## Search Types
-
-### Keyword Search
-- Based on search terms entered by users
-- Full-text search across product attributes
-- Includes search suggestions and spell correction
-
-### Category Search  
-- Browse products within specific categories
-- Maintains category hierarchy navigation
-- Category-specific refinements and sorting
-
-### Refined Search
-- Apply filters to narrow results
-- Multiple refinement types (price, attributes, categories)
-- Combinable refinements with removal options
-
-## Refinement Types
-
-The model supports various refinement types:
-- **Category Refinements** - Filter by product categories
-- **Attribute Refinements** - Filter by product attributes (color, size, brand)
-- **Price Refinements** - Filter by price ranges
-- **Promotion Refinements** - Filter by promotional offers
-
-## Notes
-
-- Provides comprehensive search functionality for SFRA storefronts
-- Handles both keyword and category-based searches
-- Includes pagination support with configurable page sizes
-- Supports multiple refinement types with hit counts
-- Integrates with product tile models for consistent display
-- Includes sorting options and search result optimization
-- Provides URLs for search refinement and reset functionality
-
-## Related Models
-
-- **ProductSortOptions** - Used for search result sorting
-- **Product Tile Model** - Used for individual product display
-- **Categories Model** - Used for category-based searches
-- **Refinement Models** - Used for search filtering

package/docs/sfra/product-tile.md

@@ -1,95 +0,0 @@
-# SFRA Product Tile Model
-
-## Overview
-
-The Product Tile model represents a product in tile/grid view format, typically used in product listing pages, search results, and category pages. It provides essential product information optimized for display in compact tile formats.
-
-## Module Function
-
-```javascript
-module.exports = function productTile(product, apiProduct, productType)
-```
-
-Decorates a product object with product tile information using various decorators.
-
-### Parameters
-
-- `product` (Object) - Product Model to be decorated
-- `apiProduct` (dw.catalog.Product) - Product information returned by the script API
-- `productType` (string) - Product type information ('product', 'variant', 'master', 'set', etc.)
-
-### Returns
-
-Object - Decorated product model with tile-specific information
-
-## Applied Decorators
-
-The product tile model applies the following decorators:
-
-### base
-Adds fundamental product information including uuid, id, productName, productType, and brand.
-
-### searchPrice
-Adds pricing information optimized for search results and product tiles: `price` property with promotional pricing.
-
-### images
-Adds product images with the following configuration:
-- **Types:** ['medium'] - Medium-sized images suitable for tiles
-- **Quantity:** 'single' - Single image per type
-
-### ratings
-Adds product rating information: `rating` value calculated from product ID.
-
-### setProductsCollection (conditional)
-Applied only when `productType === 'set'`. Adds `numberOfProductsInSet` property with count of products in the set.
-
-### searchVariationAttributes
-Adds variation attribute information: `variationAttributes` array optimized for search results and product listings (specifically color swatches).
-
-## Usage Example
-
-```javascript
-var productTileDecorator = require('*/cartridge/models/product/productTile');
-var productFactory = require('*/cartridge/scripts/factories/product');
-
-// Create base product model
-var product = productFactory.get({ pid: 'product-id' });
-
-// Apply product tile decorations
-var tileProduct = productTileDecorator(product, apiProduct, 'product');
-
-// Access tile-specific properties
-console.log(tileProduct.images.medium);
-console.log(tileProduct.price);
-console.log(tileProduct.ratings);
-```
-
-## Typical Properties After Decoration
-
-After applying the product tile decorators, the product object typically contains:
-
-- **uuid** - Product UUID
-- **id** - Product ID
-- **productName** - Product name  
-- **productType** - Product type
-- **brand** - Product brand
-- **price** - Pricing information with promotions (DefaultPrice or RangePrice)
-- **images** - Medium-sized product images
-- **rating** - Product rating value
-- **variationAttributes** - Color variation swatches and options
-- **numberOfProductsInSet** - Number of products in set (for product sets only)
-
-## Notes
-
-- Optimized for performance in product listing scenarios
-- Uses medium-sized images to balance quality and load time
-- Includes promotional pricing for accurate display
-- Handles different product types (simple, master, variant, set)
-- Variation attributes are optimized for search/listing context
-
-## Related Models
-
-- **Full Product Model** - More detailed product information
-- **Product Bundle Model** - For bundled products
-- **Product Set Model** - For product sets
-- **Product Decorators** - Individual decoration functions

package/docs/sfra/querystring.md

@@ -1,240 +0,0 @@
-# Class QueryString
-
-## Inheritance Hierarchy
-
-- Object
-  - sfra.models.QueryString
-
-## Description
-
-The SFRA QueryString class is a specialized utility for parsing and managing URL query string parameters in SFCC applications. This class provides enhanced functionality beyond basic query string parsing by handling SFCC-specific parameter formats including product variants (`dwvar_`), product options (`dwopt_`), and search preferences (`pref`). The QueryString class automatically organizes these parameters into structured objects, handles URL encoding/decoding, manages duplicate parameters as arrays, and provides serialization back to query string format. It serves as the primary interface for working with URL parameters in SFRA controllers and templates.
-
-## Properties
-
-### variables
-
-**Type:** Object
-
-Object containing product variant information parsed from `dwvar_` parameters.
-
-### options
-
-**Type:** Array
-
-Array of product option objects parsed from `dwopt_` parameters.
-
-### preferences
-
-**Type:** Object
-
-Object containing search preference filters parsed from `pref` parameters.
-
-### [parameterName]
-
-**Type:** String | Array
-
-Dynamic properties containing standard query parameters. Duplicate parameters are automatically converted to arrays.
-
-## Constructor Summary
-
-### QueryString
-
-**Signature:** `QueryString(raw)`
-
-Creates a new QueryString object by parsing the provided raw query string.
-
-**Parameters:**
-- `raw` (String) - Raw query string to parse
-
-## Method Summary
-
-### toString
-
-**Signature:** `toString() : String`
-
-Serializes the QueryString object back to a URL-encoded query string format.
-
-## Constructor Detail
-
-### QueryString
-
-**Signature:** `QueryString(raw)`
-
-**Description:** Parses a raw query string and organizes parameters into structured objects. Handles SFCC-specific parameter formats and automatically processes URL encoding.
-
-**Parameters:**
-- `raw` (String) - The raw query string to parse, may include the leading `?`
-
-**Processing Logic:**
-- Extracts and parses `dwvar_` parameters into the `variables` object
-- Extracts and parses `dwopt_` parameters into the `options` array
-- Extracts and parses `pref` parameters into the `preferences` object
-- Handles duplicate parameters by converting them to arrays
-- Performs URL decoding on all parameter values
-
-## Method Detail
-
-### toString
-
-**Signature:** `toString() : String`
-
-**Description:** Converts the QueryString object back to a properly formatted and URL-encoded query string. Maintains the original SFCC parameter format conventions.
-
-**Returns:**
-String containing the URL-encoded query string without the leading `?`.
-
-**Output Format:**
-- `dwvar_` parameters for product variants
-- `dwopt_` parameters for product options
-- `prefn`/`prefv`/`prefmin`/`prefmax` parameters for search preferences
-- Standard parameters for all other values
-- Results are sorted alphabetically
-
-## Property Details
-
-### variables
-
-**Type:** Object
-
-**Description:** Contains product variant information parsed from `dwvar_` prefixed parameters. Each variant is represented as:
-
-```javascript
-{
-  "variantAttributeName": {
-    id: "productId",
-    value: "selectedVariantValue"
-  }
-}
-```
-
-**Example:**
-```javascript
-// From: dwvar_123456_color=Red&dwvar_123456_size=Large
-variables: {
-  "color": { id: "123456", value: "Red" },
-  "size": { id: "123456", value: "Large" }
-}
-```
-
-### options
-
-**Type:** Array
-
-**Description:** Contains product option selections parsed from `dwopt_` prefixed parameters. Each option is represented as:
-
-```javascript
-{
-  optionId: "optionIdentifier",
-  selectedValueId: "selectedOptionValue", 
-  productId: "associatedProductId"
-}
-```
-
-**Example:**
-```javascript
-// From: dwopt_123456_warranty=extended&dwopt_123456_installation=yes
-options: [
-  { optionId: "warranty", selectedValueId: "extended", productId: "123456" },
-  { optionId: "installation", selectedValueId: "yes", productId: "123456" }
-]
-```
-
-### preferences
-
-**Type:** Object
-
-**Description:** Contains search refinement preferences parsed from `pref` prefixed parameters. Supports both single values and min/max ranges:
-
-**Single Value Format:**
-```javascript
-{
-  "attributeName": "value"
-}
-```
-
-**Range Value Format:**
-```javascript
-{
-  "attributeName": {
-    min: "minimumValue",
-    max: "maximumValue"
-  }
-}
-```
-
-**Example:**
-```javascript
-// From: prefn1=color&prefv1=Blue&prefn2=price&prefmin2=10&prefmax2=50
-preferences: {
-  "color": "Blue",
-  "price": { min: "10", max: "50" }
-}
-```
-
-## Parameter Handling Details
-
-### SFCC-Specific Parameters
-
-**Product Variants (`dwvar_`):**
-- Format: `dwvar_{productId}_{variantAttribute}={value}`
-- Underscores in product IDs are encoded as double underscores (`__`)
-- Parsed into the `variables` object with product ID and attribute mappings
-
-**Product Options (`dwopt_`):**
-- Format: `dwopt_{productId}_{optionId}={selectedValueId}`
-- Underscores in product IDs are encoded as double underscores (`__`)
-- Parsed into the `options` array with structured option data
-
-**Search Preferences (`pref`):**
-- Single values: `prefn{index}={name}&prefv{index}={value}`
-- Range values: `prefn{index}={name}&prefmin{index}={min}&prefmax{index}={max}`
-- Parsed into the `preferences` object with appropriate structure
-
-### Standard Parameters
-
-**Regular Query Parameters:**
-- Standard URL parameters are stored as properties on the QueryString object
-- Duplicate parameters are automatically converted to arrays
-- All values are URL decoded
-
-### URL Encoding Handling
-
-**Automatic Processing:**
-- Input parameters are automatically URL decoded during parsing
-- Output via `toString()` is automatically URL encoded
-- Spaces are handled correctly (+ symbols converted to %20)
-- Special characters are properly encoded/decoded
-
-## Usage Examples
-
-### Basic Parsing
-```javascript
-var qs = new QueryString('?color=red&size=large&category=shoes');
-// qs.color === 'red'
-// qs.size === 'large' 
-// qs.category === 'shoes'
-```
-
-### Product Variants
-```javascript
-var qs = new QueryString('?dwvar_123456_color=Blue&dwvar_123456_size=Medium');
-// qs.variables.color.id === '123456'
-// qs.variables.color.value === 'Blue'
-```
-
-### Search Preferences
-```javascript
-var qs = new QueryString('?prefn1=color&prefv1=Red&prefn2=price&prefmin2=10&prefmax2=100');
-// qs.preferences.color === 'Red'
-// qs.preferences.price.min === '10'
-// qs.preferences.price.max === '100'
-```
-
-### Serialization
-```javascript
-var qs = new QueryString('?color=red&size=large');
-qs.brand = 'nike';
-var newQuery = qs.toString(); // 'brand=nike&color=red&size=large'
-```
-
----