@jay-framework/wix-stores 0.15.0

package/dist/contracts/media-gallery.jay-contract.d.ts

@@ -0,0 +1,53 @@
+import {HTMLElementCollectionProxy, JayContract} from "@jay-framework/runtime";
+import {MediaViewState, MediaRefs, MediaRepeatedRefs} from "./media.jay-contract";
+
+export enum Selected {
+  selected,
+  notSelected
+}
+
+export interface AvailableMediaOfMediaGalleryViewState {
+  mediaId: string,
+  media: MediaViewState,
+  selected: Selected
+}
+
+export interface MediaGalleryViewState {
+  selectedMedia: MediaViewState,
+  availableMedia: Array<AvailableMediaOfMediaGalleryViewState>
+}
+
+export type MediaGallerySlowViewState = {
+    selectedMedia: MediaGalleryViewState['selectedMedia'];
+    availableMedia: Array<Pick<MediaGalleryViewState['availableMedia'][number], 'mediaId'> & {
+    media: MediaGalleryViewState['availableMedia'][number]['media'];
+}>;
+};
+
+export type MediaGalleryFastViewState = {
+    availableMedia: Array<Pick<MediaGalleryViewState['availableMedia'][number], 'mediaId' | 'selected'>>;
+};
+
+export type MediaGalleryInteractiveViewState = {
+    availableMedia: Array<Pick<MediaGalleryViewState['availableMedia'][number], 'mediaId' | 'selected'>>;
+};
+
+
+export interface MediaGalleryRefs {
+  selectedMedia: MediaRefs,
+  availableMedia: {
+    selected: HTMLElementCollectionProxy<AvailableMediaOfMediaGalleryViewState, HTMLImageElement | HTMLDivElement>,
+    media: MediaRefs
+  }
+}
+
+
+export interface MediaGalleryRepeatedRefs {
+  selectedMedia: MediaRepeatedRefs,
+  availableMedia: {
+    selected: HTMLElementCollectionProxy<AvailableMediaOfMediaGalleryViewState, HTMLImageElement | HTMLDivElement>,
+    media: MediaRepeatedRefs
+  }
+}
+
+export type MediaGalleryContract = JayContract<MediaGalleryViewState, MediaGalleryRefs, MediaGallerySlowViewState, MediaGalleryFastViewState, MediaGalleryInteractiveViewState>

package/dist/contracts/media.jay-contract

@@ -0,0 +1,5 @@
+name: media
+tags:
+  - {tag: url, type: data, dataType: string, description: Media Url}
+  - {tag: mediaType, type: variant, dataType: "enum (IMAGE | VIDEO)", description: Media type}
+  - {tag: thumbnail_50x50, type: data, dataType: string, description: Media Thumbnail Url }

package/dist/contracts/media.jay-contract.d.ts

@@ -0,0 +1,25 @@
+import {JayContract} from "@jay-framework/runtime";
+
+
+export enum MediaType {
+  IMAGE,
+  VIDEO
+}
+
+export interface MediaViewState {
+  url: string,
+  mediaType: MediaType,
+  thumbnail_50x50: string
+}
+
+export type MediaSlowViewState = Pick<MediaViewState, 'url' | 'mediaType' | 'thumbnail_50x50'>;
+
+export type MediaFastViewState = {};
+
+export type MediaInteractiveViewState = {};
+
+export interface MediaRefs {}
+
+export interface MediaRepeatedRefs {}
+
+export type MediaContract = JayContract<MediaViewState, MediaRefs, MediaSlowViewState, MediaFastViewState, MediaInteractiveViewState>

package/dist/contracts/product-card.jay-contract

@@ -0,0 +1,182 @@
+name: product-card
+tags:
+  # Product basic info (from Wix Stores Product API)
+  - tag: _id
+    type: data
+    dataType: string
+    description: Product GUID
+    
+  - tag: name
+    type: data
+    dataType: string
+    required: true
+    description: Product name
+    
+  - tag: slug
+    type: data
+    dataType: string
+    description: Product slug for URL
+    
+  - tag: productUrl
+    type: data
+    dataType: string
+    description: Full URL path to product page (e.g., /products/my-product or /products/polgat/my-product)
+
+  - tag: categoryPrefix
+    type: data
+    dataType: string
+    description: Category prefix name for the product (e.g., the display name of the root category). Empty when no prefix is configured.
+    
+  - tag: productLink
+    type: interactive
+    elementType: HTMLAnchorElement
+    description: Link to product page
+    
+  # Media (from Wix Stores Product API)
+  - tag: mainMedia
+    type: sub-contract
+    description: Main product media
+    tags:
+      - tag: url
+        type: data
+        dataType: string
+        description: Media URL
+        
+      - tag: altText
+        type: data
+        dataType: string
+        description: Media alt text
+        
+      - tag: mediaType
+        type: data
+        dataType: enum (IMAGE | VIDEO)
+        description: Media type
+        
+  - tag: thumbnail
+    type: sub-contract
+    description: Thumbnail image optimized for listings
+    tags:
+      - tag: url
+        type: data
+        dataType: string
+        description: Thumbnail URL
+        
+      - tag: altText
+        type: data
+        dataType: string
+        description: Thumbnail alt text
+        
+      - tag: width
+        type: data
+        dataType: number
+        description: Thumbnail width in pixels
+        
+      - tag: height
+        type: data
+        dataType: number
+        description: Thumbnail height in pixels
+    
+  # Price information
+  - tag: price
+    type: data
+    dataType: string
+    phase: fast+interactive
+    description: The product or variant price
+    
+  - tag: strikethroughPrice
+    type: data
+    dataType: string
+    phase: fast+interactive
+    description: A Strikethrough product price for sales
+    
+  - tag: hasDiscount
+    type: variant
+    dataType: boolean
+    description: Whether product has a discount (compareAtPrice > actualPrice)
+    
+  # Inventory (from Wix Stores Product API)
+  - tag: inventory
+    type: sub-contract
+    description: Product inventory information
+    tags:
+      - tag: availabilityStatus
+        type: variant
+        dataType: enum (IN_STOCK | OUT_OF_STOCK | PARTIALLY_OUT_OF_STOCK)
+        description: Current availability status
+        
+      - tag: preorderStatus
+        type: data
+        dataType: enum (ENABLED | DISABLED | PARTIALLY_ENABLED)
+        description: Current preorder status
+        
+  # Product ribbon (from Wix Stores Product API)
+  - tag: ribbon
+    type: sub-contract
+    description: Product ribbon/badge
+    tags:
+      - tag: _id
+        type: data
+        dataType: string
+        description: Ribbon GUID
+        
+      - tag: name
+        type: data
+        dataType: string
+        description: Ribbon text (e.g., "New", "Sale", "Best Seller")
+        
+  - tag: hasRibbon
+    type: variant
+    dataType: boolean
+    description: Whether product has a ribbon/badge
+    
+  # Brand (from Wix Stores Product API)
+  - tag: brand
+    type: sub-contract
+    description: Product brand
+    tags:
+      - tag: _id
+        type: data
+        dataType: string
+        description: Brand GUID
+        
+      - tag: name
+        type: data
+        dataType: string
+        description: Brand name
+        
+  # Additional product metadata
+  - tag: productType
+    type: data
+    dataType: enum (PHYSICAL | DIGITAL)
+    description: Product type
+    
+  # Quick actions
+  - tag: addToCartButton
+    type: interactive
+    elementType: HTMLButtonElement
+    description: Quick add to cart button (for SIMPLE products with no options)
+    
+  - tag: isAddingToCart
+    type: variant
+    dataType: boolean
+    phase: fast+interactive
+    description: Whether add to cart is in progress
+
+  # Quick-add behavior
+  - tag: quickAddType
+    type: variant
+    dataType: enum (SIMPLE | SINGLE_OPTION | NEEDS_CONFIGURATION)
+    description: |
+      SIMPLE = no options, show Add to Cart button
+      SINGLE_OPTION = one option, show choices on hover (click = add to cart)
+      NEEDS_CONFIGURATION = multiple options or modifiers, link to product page
+
+  - tag: quickOption
+    type: sub-contract
+    description: Primary option for quick selection (only when quickAddType = SINGLE_OPTION)
+    link: ./product-options
+
+  - tag: viewOptionsButton
+    type: interactive
+    elementType: HTMLButtonElement
+    description: Button to navigate to product page (when quickAddType = NEEDS_CONFIGURATION)

package/dist/contracts/product-card.jay-contract.d.ts

@@ -0,0 +1,120 @@
+import {HTMLElementCollectionProxy, HTMLElementProxy, JayContract} from "@jay-framework/runtime";
+import {ProductOptionsViewState, ProductOptionsRefs, ProductOptionsRepeatedRefs} from "./product-options.jay-contract";
+
+export enum MediaType {
+  IMAGE,
+  VIDEO
+}
+
+export interface MainMediaOfProductCardViewState {
+  url: string,
+  altText: string,
+  mediaType: MediaType
+}
+
+export interface ThumbnailOfProductCardViewState {
+  url: string,
+  altText: string,
+  width: number,
+  height: number
+}
+
+export enum AvailabilityStatus {
+  IN_STOCK,
+  OUT_OF_STOCK,
+  PARTIALLY_OUT_OF_STOCK
+}
+
+export enum PreorderStatus {
+  ENABLED,
+  DISABLED,
+  PARTIALLY_ENABLED
+}
+
+export interface InventoryOfProductCardViewState {
+  availabilityStatus: AvailabilityStatus,
+  preorderStatus: PreorderStatus
+}
+
+export interface RibbonOfProductCardViewState {
+  _id: string,
+  name: string
+}
+
+export interface BrandOfProductCardViewState {
+  _id: string,
+  name: string
+}
+
+export enum ProductType {
+  PHYSICAL,
+  DIGITAL
+}
+
+export enum QuickAddType {
+  SIMPLE,
+  SINGLE_OPTION,
+  NEEDS_CONFIGURATION
+}
+
+export interface ProductCardViewState {
+  _id: string,
+  name: string,
+  slug: string,
+  productUrl: string,
+  categoryPrefix: string,
+  mainMedia: MainMediaOfProductCardViewState,
+  thumbnail: ThumbnailOfProductCardViewState,
+  price: string,
+  strikethroughPrice: string,
+  hasDiscount: boolean,
+  inventory: InventoryOfProductCardViewState,
+  ribbon: RibbonOfProductCardViewState,
+  hasRibbon: boolean,
+  brand: BrandOfProductCardViewState,
+  productType: ProductType,
+  isAddingToCart: boolean,
+  quickAddType: QuickAddType,
+  quickOption: ProductOptionsViewState
+}
+
+export type ProductCardSlowViewState = Pick<ProductCardViewState, '_id' | 'name' | 'slug' | 'productUrl' | 'categoryPrefix' | 'hasDiscount' | 'hasRibbon' | 'productType' | 'quickAddType'> & {
+    mainMedia: ProductCardViewState['mainMedia'];
+    thumbnail: ProductCardViewState['thumbnail'];
+    inventory: ProductCardViewState['inventory'];
+    ribbon: ProductCardViewState['ribbon'];
+    brand: ProductCardViewState['brand'];
+    quickOption: Pick<ProductCardViewState['quickOption'], '_id' | 'name' | 'optionRenderType'> & {
+    choices: Array<Pick<ProductCardViewState['quickOption']['choices'][number], 'choiceId' | 'name' | 'choiceType' | 'colorCode' | 'variantId'>>;
+};
+};
+
+export type ProductCardFastViewState = Pick<ProductCardViewState, 'price' | 'strikethroughPrice' | 'isAddingToCart'> & {
+    quickOption: {
+    choices: Array<Pick<ProductCardViewState['quickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+};
+
+export type ProductCardInteractiveViewState = Pick<ProductCardViewState, 'price' | 'strikethroughPrice' | 'isAddingToCart'> & {
+    quickOption: {
+    choices: Array<Pick<ProductCardViewState['quickOption']['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+};
+
+
+export interface ProductCardRefs {
+  productLink: HTMLElementProxy<ProductCardViewState, HTMLAnchorElement>,
+  addToCartButton: HTMLElementProxy<ProductCardViewState, HTMLButtonElement>,
+  viewOptionsButton: HTMLElementProxy<ProductCardViewState, HTMLButtonElement>,
+  quickOption: ProductOptionsRefs
+}
+
+
+export interface ProductCardRepeatedRefs {
+  productLink: HTMLElementCollectionProxy<ProductCardViewState, HTMLAnchorElement>,
+  addToCartButton: HTMLElementCollectionProxy<ProductCardViewState, HTMLButtonElement>,
+  viewOptionsButton: HTMLElementCollectionProxy<ProductCardViewState, HTMLButtonElement>,
+  quickOption: ProductOptionsRepeatedRefs
+}
+
+export type ProductCardContract = JayContract<ProductCardViewState, ProductCardRefs, ProductCardSlowViewState, ProductCardFastViewState, ProductCardInteractiveViewState>

package/dist/contracts/product-options.jay-contract

@@ -0,0 +1,66 @@
+name: product-options
+description: Shared product option structure for quick selection and full product page
+
+tags:
+  - tag: _id
+    type: data
+    dataType: string
+    description: Option GUID
+
+  - tag: name
+    type: data
+    dataType: string
+    description: "Option name (e.g., \"Size\", \"Color\")"
+
+  - tag: optionRenderType
+    type: variant
+    dataType: enum (TEXT_CHOICES | COLOR_SWATCH_CHOICES)
+    description: How the option should be rendered
+
+  - tag: choices
+    type: sub-contract
+    repeated: true
+    trackBy: choiceId
+    description: Available choices for this option
+    tags:
+      - tag: choiceId
+        type: data
+        dataType: string
+        description: Choice GUID
+
+      - tag: name
+        type: data
+        dataType: string
+        description: "Choice display name (e.g., \"XL\", \"Red\")"
+
+      - tag: choiceType
+        type: variant
+        dataType: enum (CHOICE_TEXT | ONE_COLOR)
+        description: Type of choice (text or color swatch)
+
+      - tag: colorCode
+        type: data
+        dataType: string
+        description: Color code in HEX format (for color swatches)
+
+      - tag: inStock
+        type: variant
+        dataType: boolean
+        phase: fast+interactive
+        description: Whether this choice has available stock
+
+      - tag: variantId
+        type: data
+        dataType: string
+        description: The variant ID to use when adding to cart (for single-option products)
+
+      - tag: isSelected
+        type: variant
+        dataType: boolean
+        phase: fast+interactive
+        description: Whether this choice is currently selected
+
+      - tag: choiceButton
+        type: interactive
+        elementType: HTMLButtonElement
+        description: Button to select this choice (click adds to cart for quick-add)

package/dist/contracts/product-options.jay-contract.d.ts

@@ -0,0 +1,57 @@
+import {HTMLElementCollectionProxy, JayContract} from "@jay-framework/runtime";
+
+
+export enum OptionRenderType {
+  TEXT_CHOICES,
+  COLOR_SWATCH_CHOICES
+}
+
+export enum ChoiceType {
+  CHOICE_TEXT,
+  ONE_COLOR
+}
+
+export interface ChoiceOfProductOptionsViewState {
+  choiceId: string,
+  name: string,
+  choiceType: ChoiceType,
+  colorCode: string,
+  inStock: boolean,
+  variantId: string,
+  isSelected: boolean
+}
+
+export interface ProductOptionsViewState {
+  _id: string,
+  name: string,
+  optionRenderType: OptionRenderType,
+  choices: Array<ChoiceOfProductOptionsViewState>
+}
+
+export type ProductOptionsSlowViewState = Pick<ProductOptionsViewState, '_id' | 'name' | 'optionRenderType'> & {
+    choices: Array<Pick<ProductOptionsViewState['choices'][number], 'choiceId' | 'name' | 'choiceType' | 'colorCode' | 'variantId'>>;
+};
+
+export type ProductOptionsFastViewState = {
+    choices: Array<Pick<ProductOptionsViewState['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+
+export type ProductOptionsInteractiveViewState = {
+    choices: Array<Pick<ProductOptionsViewState['choices'][number], 'choiceId' | 'inStock' | 'isSelected'>>;
+};
+
+
+export interface ProductOptionsRefs {
+  choices: {
+    choiceButton: HTMLElementCollectionProxy<ChoiceOfProductOptionsViewState, HTMLButtonElement>
+  }
+}
+
+
+export interface ProductOptionsRepeatedRefs {
+  choices: {
+    choiceButton: HTMLElementCollectionProxy<ChoiceOfProductOptionsViewState, HTMLButtonElement>
+  }
+}
+
+export type ProductOptionsContract = JayContract<ProductOptionsViewState, ProductOptionsRefs, ProductOptionsSlowViewState, ProductOptionsFastViewState, ProductOptionsInteractiveViewState>

package/dist/contracts/product-page.jay-contract

@@ -0,0 +1,151 @@
+name: product-page
+tags:
+  - {tag: _id, type: data, dataType: string, description: Product GUID}
+  - {tag: productName, type: data, dataType: string, required: true, description: Product name}
+
+  - tag: mediaGallery
+    type: sub-contract
+    phase: fast+interactive
+    link: ./media-gallery
+
+  - {tag: description, type: data, dataType: string, description: Product description}
+  - {tag: brand, type: data, dataType: string, description: Brand name}
+  - {tag: ribbon, type: data, dataType: string, description: "Ribbon text (e.g., \"New\", \"Sale\")"}
+  - {tag: productType, type: variant, dataType: "enum (PHYSICAL | DIGITAL)", description: Product type }
+
+  - {tag: sku, type: data, dataType: string, phase: fast+interactive, description: Product SKU, or chosen variant SKU}
+  - {tag: price, type: data, dataType: string, phase: fast+interactive, description: The product or variant price}
+  - {tag: strikethroughPrice, type: data, dataType: string, phase: fast+interactive, description: A Strikethrough product price for sales}
+  - {tag: pricePerUnit, type: data, dataType: string, phase: fast+interactive, description: formatted price per unit, if used}
+  - {tag: stockStatus, type: variant, dataType: "enum (OUT_OF_STOCK | IN_STOCK)", phase: fast+interactive, description: indicator if the product or current variant are in stock }
+
+  - tag: quantity
+    type: sub-contract
+    description: Quantity selection controls
+    tags:
+      - {tag: decrementButton, type: interactive, elementType: HTMLButtonElement, description: Button to decrease quantity}
+      - {tag: incrementButton, type: interactive, elementType: HTMLButtonElement, description: Button to increase quantity}
+      - {tag: quantity, type: [data, interactive], dataType: number, elementType: HTMLInputElement, description: Selected Quantity and Direct quantity input field}
+
+  # Call to action
+  - {tag: addToCartButton, type: interactive, elementType: HTMLButtonElement, required: true, description: Add product to cart button}
+  - {tag: buyNowButton, type: interactive, elementType: HTMLButtonElement, required: true, description: Buy now button}
+  - {tag: actionsEnabled, type: variant, dataType: boolean, phase: fast+interactive, description: should the add to cart and buy now buttons be enabled}
+
+  - tag: options
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    description: Product customization options that generate variants
+    tags:
+      - {tag: _id, type: data, dataType: string, description: "Option GUID (customization ID)"}
+      - {tag: name, type: data, dataType: string, description: "Option name (e.g., \"Color\", \"Size\")"}
+      - {tag: optionRenderType, type: variant, dataType: "enum (TEXT_CHOICES | COLOR_SWATCH_CHOICES)", description: How the option should be rendered}
+      - {tag: textChoice, type: interactive, elementType: HTMLSelectElement, description: dropdown for text choice}
+      - {tag: textChoiceSelection, type: data, dataType: string, phase: fast+interactive, description: the selected text option}
+
+      - tag: choices
+        type: sub-contract
+        repeated: true
+        trackBy: choiceId
+        description: Available choices for this option
+        tags:
+          - {tag: choiceId, type: data, dataType: string, description: Choice GUID}
+          - {tag: choiceType, type: variant, dataType: "enum (CHOICE_TEXT | ONE_COLOR)", description: Type of choice}
+          - {tag: name, type: data, dataType: string, description: "Choice name (e.g., \"Red\", \"Large\")"}
+          - {tag: colorCode, type: data, dataType: string, description: Color code in HEX format (for color choices)}
+          - {tag: inStock, type: data, dataType: boolean, description: Whether at least one variant with this choice is in stock}
+          - {tag: isSelected, type: variant, dataType: boolean, phase: fast+interactive, description: Whether this choice is currently selected (UI state)}
+          - {tag: choiceButton, type: interactive, elementType: HTMLButtonElement, description: Button to select this choice}
+
+  # Additional info sections (from Wix Stores API)
+  - tag: infoSections
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    description: Additional product information sections
+    tags:
+      - {tag: _id, type: data, dataType: string, description: Info section GUID}
+      - {tag: title, type: data, dataType: string, description: Info section title}
+      - {tag: plainDescription, type: data, dataType: string, description: Info section description in HTML}
+
+  - tag: modifiers
+    type: sub-contract
+    repeated: true
+    trackBy: _id
+    description: Product customization options that do not generate variants
+    tags:
+      - {tag: _id, type: data, dataType: string, description: "modifier id"}
+      - {tag: name, type: data, dataType: string, description: "modifier name (e.g., \"Color\", \"Size\")"}
+      - {tag: modifierType, type: variant, dataType: "enum (TEXT_CHOICES | COLOR_SWATCH_CHOICES | FREE_TEXT)", description: What type of modifier to use?}
+      - {tag: textModifier, type: interactive, elementType: HTMLSelectElement, description: dropdown for text modifier}
+      - {tag: textModifierSelection, type: data, dataType: string, phase: fast+interactive, description: the selected text modifier}
+      - {tag: textInput, type: interactive, elementType: HTMLInputElement | HTMLAreaElement, description: text input for free text}
+      - {tag: textInputLength, type: data, dataType: number, description: the limit on the length of free text}
+      - {tag: textInputRequired, type: data, dataType: boolean, description: Is the free text input required?}
+
+      - tag: choices
+        type: sub-contract
+        repeated: true
+        trackBy: choiceId
+        description: Available choices for this Modifier
+        tags:
+          - {tag: choiceId, type: data, dataType: string, description: Choice GUID}
+          - {tag: choiceType, type: variant, dataType: "enum (CHOICE_TEXT | ONE_COLOR)", description: Type of choice}
+          - {tag: name, type: data, dataType: string, description: "Choice name (e.g., \"Red\", \"Large\")"}
+          - {tag: colorCode, type: data, dataType: string, description: Color code in HEX format (for color choices)}
+          - {tag: isSelected, type: variant, dataType: boolean, phase: fast+interactive, description: Whether this choice is currently selected (UI state)}
+          - {tag: choiceButton, type: interactive, elementType: HTMLButtonElement, description: Button to select this choice}
+
+  - tag: seoData
+    type: sub-contract
+    description: Product SEO data.
+    tags:
+      - tag: tags
+        type: sub-contract
+        repeated: true
+        trackBy: position
+        description: SEO tag information.
+        tags:
+          - {tag: position, type: data, dataType: string, description: the number of the tag, as two digit string.}
+          - {tag: type, type: data, dataType: string, description: SEO tag type.}
+          - tag: props
+            type: sub-contract
+            repeated: true
+            trackBy: key
+            description: A Key Value pair of SEO properties.
+            tags:
+              - tag: key
+                type: data
+                dataType: string
+              - tag: value
+                type: data
+                dataType: string
+          - tag: meta
+            type: sub-contract
+            repeated: true
+            trackBy: key
+            description: SEO tag metadata
+            tags:
+              - tag: key
+                type: data
+                dataType: string
+              - tag: value
+                type: data
+                dataType: string
+          - {tag: children, type: data, dataType: string, description: SEO tag inner content.}
+
+      - tag: settings
+        type: sub-contract
+        description: SEO general settings.
+        tags:
+          - {tag: preventAutoRedirect, type: data, dataType: boolean, description: Whether the automatical redirect visits from the old URL to the new one is enabled.}
+          - tag: keywords
+            type: sub-contract
+            repeated: true
+            trackBy: term
+            description: User-selected keyword terms for a specific page.
+            tags:
+            - {tag: term, type: data, dataType: string, description: Keyword value.}
+            - {tag: isMain, type: data, dataType: boolean, description: Whether the keyword is the main focus keyword.}
+            - {tag: origin, type: data, dataType: string, description: The source that added the keyword terms to the SEO settings. }