@wix/headless-stores 0.0.0

package/cjs/dist/utils/url-params.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Utility class for managing URL parameters in web applications.
+ * Provides methods to parse, update, and retrieve URL search parameters with support for multiple values.
+ *
+ * @class URLParamsUtils
+ */
+export declare class URLParamsUtils {
+    /**
+     * Parses URLSearchParams into a more convenient format that supports multiple values for the same key.
+     * Converts multiple parameters with the same key into an array.
+     *
+     * @static
+     * @param {URLSearchParams} searchParams - The URLSearchParams object to parse
+     * @returns {Record<string, string | string[]>} Object with parameter names as keys and values as strings or arrays
+     *
+     * @example
+     * ```typescript
+     * // URL: ?color=red&color=blue&size=large
+     * const params = new URLSearchParams('color=red&color=blue&size=large');
+     * const parsed = URLParamsUtils.parseSearchParams(params);
+     * // Result: { color: ['red', 'blue'], size: 'large' }
+     * ```
+     */
+    static parseSearchParams(searchParams: URLSearchParams): Record<string, string | string[]>;
+    /**
+     * Updates the current page URL with new parameters without causing a page reload.
+     * Supports multiple values for the same parameter key.
+     *
+     * @static
+     * @param {Record<string, string | string[]>} params - Object with parameter names and values to set
+     *
+     * @example
+     * ```typescript
+     * // Update URL with single and multiple values
+     * URLParamsUtils.updateURL({
+     *   category: 'electronics',
+     *   color: ['red', 'blue'],
+     *   price: '100'
+     * });
+     * // URL becomes: ?category=electronics&color=red&color=blue&price=100
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Clear all parameters by passing empty object
+     * URLParamsUtils.updateURL({});
+     * // URL becomes: current-path (no query string)
+     * ```
+     */
+    static updateURL(params: Record<string, string | string[]>): void;
+    /**
+     * Gets the current URL parameters parsed into a convenient format.
+     * Returns an empty object when running in server-side environment.
+     *
+     * @static
+     * @returns {Record<string, string | string[]>} Object with current URL parameters
+     *
+     * @example
+     * ```typescript
+     * // Current URL: ?category=electronics&color=red&color=blue
+     * const params = URLParamsUtils.getURLParams();
+     * // Result: { category: 'electronics', color: ['red', 'blue'] }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Server-side usage
+     * const params = URLParamsUtils.getURLParams();
+     * // Result: {} (empty object)
+     * ```
+     */
+    static getURLParams(): Record<string, string | string[]>;
+}

package/cjs/dist/utils/url-params.js

@@ -0,0 +1,114 @@
+/**
+ * Utility class for managing URL parameters in web applications.
+ * Provides methods to parse, update, and retrieve URL search parameters with support for multiple values.
+ *
+ * @class URLParamsUtils
+ */
+export class URLParamsUtils {
+    /**
+     * Parses URLSearchParams into a more convenient format that supports multiple values for the same key.
+     * Converts multiple parameters with the same key into an array.
+     *
+     * @static
+     * @param {URLSearchParams} searchParams - The URLSearchParams object to parse
+     * @returns {Record<string, string | string[]>} Object with parameter names as keys and values as strings or arrays
+     *
+     * @example
+     * ```typescript
+     * // URL: ?color=red&color=blue&size=large
+     * const params = new URLSearchParams('color=red&color=blue&size=large');
+     * const parsed = URLParamsUtils.parseSearchParams(params);
+     * // Result: { color: ['red', 'blue'], size: 'large' }
+     * ```
+     */
+    static parseSearchParams(searchParams) {
+        const params = {};
+        // Parse all parameters
+        for (const [key, value] of searchParams.entries()) {
+            if (params[key]) {
+                // Convert to array if multiple values
+                if (Array.isArray(params[key])) {
+                    params[key].push(value);
+                }
+                else {
+                    params[key] = [params[key], value];
+                }
+            }
+            else {
+                params[key] = value;
+            }
+        }
+        return params;
+    }
+    /**
+     * Updates the current page URL with new parameters without causing a page reload.
+     * Supports multiple values for the same parameter key.
+     *
+     * @static
+     * @param {Record<string, string | string[]>} params - Object with parameter names and values to set
+     *
+     * @example
+     * ```typescript
+     * // Update URL with single and multiple values
+     * URLParamsUtils.updateURL({
+     *   category: 'electronics',
+     *   color: ['red', 'blue'],
+     *   price: '100'
+     * });
+     * // URL becomes: ?category=electronics&color=red&color=blue&price=100
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Clear all parameters by passing empty object
+     * URLParamsUtils.updateURL({});
+     * // URL becomes: current-path (no query string)
+     * ```
+     */
+    static updateURL(params) {
+        if (typeof window === 'undefined')
+            return;
+        const url = new URL(window.location.href);
+        const urlParams = new URLSearchParams();
+        // Add all parameters
+        Object.entries(params).forEach(([key, value]) => {
+            if (Array.isArray(value)) {
+                value.forEach((v) => urlParams.append(key, v));
+            }
+            else if (value) {
+                urlParams.set(key, value);
+            }
+        });
+        // Update URL without page reload
+        const newURL = urlParams.toString()
+            ? `${url.pathname}?${urlParams.toString()}`
+            : url.pathname;
+        window.history.replaceState({}, '', newURL);
+    }
+    /**
+     * Gets the current URL parameters parsed into a convenient format.
+     * Returns an empty object when running in server-side environment.
+     *
+     * @static
+     * @returns {Record<string, string | string[]>} Object with current URL parameters
+     *
+     * @example
+     * ```typescript
+     * // Current URL: ?category=electronics&color=red&color=blue
+     * const params = URLParamsUtils.getURLParams();
+     * // Result: { category: 'electronics', color: ['red', 'blue'] }
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Server-side usage
+     * const params = URLParamsUtils.getURLParams();
+     * // Result: {} (empty object)
+     * ```
+     */
+    static getURLParams() {
+        if (typeof window === 'undefined')
+            return {};
+        return this.parseSearchParams(new URLSearchParams(window.location.search));
+    }
+}

package/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/astro/actions/custom-checkout.d.ts

@@ -0,0 +1,50 @@
+import { type CustomLineItemCheckoutOptions } from '../../server-actions/index.js';
+/**
+ * Creates an Astro action factory for custom checkout functionality with line items.
+ *
+ * This factory function generates an Astro action that can be used to create custom
+ * checkout URLs with specific line items. It wraps the Wix headless stores server
+ * action functionality in an Astro-compatible action format.
+ *
+ * @param {CustomLineItemCheckoutOptions} factoryOpts - Configuration options for the custom checkout
+ * @param {string} factoryOpts.productName - The name of the product for the custom line item
+ * @param {string} [factoryOpts.priceDescription] - A description for the price, which will be displayed to the customer
+ * @param {Array<{content: string, title: string}>} [factoryOpts.policies] - An array of policies related to this custom item
+ * @param {string} [factoryOpts.postFlowUrl] - The URL to redirect the user to after the checkout is successfully completed
+ * @param {number} [factoryOpts.quantity=1] - The quantity of the product
+ * @param {string} factoryOpts.price - The price of the product
+ *
+ * @returns {ReturnType<typeof defineAction>} An Astro action that when invoked returns checkout URL
+ *
+ * @example
+ * ```typescript
+ * // Define the action with your configuration
+ * const customCheckoutAction = customCheckoutActionFactory({
+ *   productName: "Premium Subscription",
+ *   price: "29.99",
+ *   priceDescription: "per month",
+ *   quantity: 1,
+ *   postFlowUrl: "https://yoursite.com/thank-you",
+ *   policies: [
+ *     {
+ *       title: "Refund Policy",
+ *       content: "30-day money back guarantee"
+ *     }
+ *   ]
+ * });
+ *
+ * export const server = {
+ *   checkout: customCheckoutAction
+ * };
+ *
+ * // Use in your Astro component or API route
+ * import { actions } from "astro:actions";
+ * const checkoutUrl = await actions.customCheckoutAction();
+ * ```
+ *
+ * @see {@link https://docs.astro.build/en/guides/actions/} Astro Actions Documentation
+ * @see {@link https://dev.wix.com/docs/sdk/headless/api-reference/stores/checkout} Wix Stores Checkout API
+ */
+export declare const customCheckoutActionFactory: (factoryOpts: CustomLineItemCheckoutOptions) => ((input?: any) => Promise<import("astro:actions").SafeResult<never, string>>) & {
+    orThrow: (input?: any) => Promise<string>;
+} & string;

package/dist/astro/actions/custom-checkout.js

@@ -0,0 +1,53 @@
+/// <reference types="astro/env" />
+// @ts-ignore
+import { defineAction } from 'astro:actions';
+import { getCustomLineItemCheckoutURLFactory, } from '../../server-actions/index.js';
+/**
+ * Creates an Astro action factory for custom checkout functionality with line items.
+ *
+ * This factory function generates an Astro action that can be used to create custom
+ * checkout URLs with specific line items. It wraps the Wix headless stores server
+ * action functionality in an Astro-compatible action format.
+ *
+ * @param {CustomLineItemCheckoutOptions} factoryOpts - Configuration options for the custom checkout
+ * @param {string} factoryOpts.productName - The name of the product for the custom line item
+ * @param {string} [factoryOpts.priceDescription] - A description for the price, which will be displayed to the customer
+ * @param {Array<{content: string, title: string}>} [factoryOpts.policies] - An array of policies related to this custom item
+ * @param {string} [factoryOpts.postFlowUrl] - The URL to redirect the user to after the checkout is successfully completed
+ * @param {number} [factoryOpts.quantity=1] - The quantity of the product
+ * @param {string} factoryOpts.price - The price of the product
+ *
+ * @returns {ReturnType<typeof defineAction>} An Astro action that when invoked returns checkout URL
+ *
+ * @example
+ * ```typescript
+ * // Define the action with your configuration
+ * const customCheckoutAction = customCheckoutActionFactory({
+ *   productName: "Premium Subscription",
+ *   price: "29.99",
+ *   priceDescription: "per month",
+ *   quantity: 1,
+ *   postFlowUrl: "https://yoursite.com/thank-you",
+ *   policies: [
+ *     {
+ *       title: "Refund Policy",
+ *       content: "30-day money back guarantee"
+ *     }
+ *   ]
+ * });
+ *
+ * export const server = {
+ *   checkout: customCheckoutAction
+ * };
+ *
+ * // Use in your Astro component or API route
+ * import { actions } from "astro:actions";
+ * const checkoutUrl = await actions.customCheckoutAction();
+ * ```
+ *
+ * @see {@link https://docs.astro.build/en/guides/actions/} Astro Actions Documentation
+ * @see {@link https://dev.wix.com/docs/sdk/headless/api-reference/stores/checkout} Wix Stores Checkout API
+ */
+export const customCheckoutActionFactory = (factoryOpts) => defineAction({
+    handler: () => getCustomLineItemCheckoutURLFactory(factoryOpts)(),
+});

package/dist/astro/actions/index.d.ts

@@ -0,0 +1 @@
+export * from './custom-checkout.js';

package/dist/astro/actions/index.js

@@ -0,0 +1 @@
+export * from './custom-checkout.js';

package/dist/data-component-tags.d.ts

@@ -0,0 +1,8 @@
+export declare enum DataComponentTags {
+    categoryListRoot = "stores.category-list-root",
+    categoryRoot = "stores.category-root",
+    choiceRoot = "stores.choice-root",
+    optionRoot = "stores.option-root",
+    productListRoot = "stores.product-list-root",
+    productRoot = "stores.product-root"
+}

package/dist/data-component-tags.js

@@ -0,0 +1,9 @@
+export var DataComponentTags;
+(function (DataComponentTags) {
+    DataComponentTags["categoryListRoot"] = "stores.category-list-root";
+    DataComponentTags["categoryRoot"] = "stores.category-root";
+    DataComponentTags["choiceRoot"] = "stores.choice-root";
+    DataComponentTags["optionRoot"] = "stores.option-root";
+    DataComponentTags["productListRoot"] = "stores.product-list-root";
+    DataComponentTags["productRoot"] = "stores.product-root";
+})(DataComponentTags || (DataComponentTags = {}));

package/dist/enums/index.d.ts

@@ -0,0 +1,2 @@
+export * from './sort-enums.js';
+export * from './social-platform-enums.js';

package/dist/enums/index.js

@@ -0,0 +1,2 @@
+export * from './sort-enums.js';
+export * from './social-platform-enums.js';

package/dist/enums/social-platform-enums.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Business logic enums for social sharing platforms (headless layer)
+ */
+/**
+ * Enum for social sharing platforms (business identifiers)
+ */
+export declare enum SocialPlatform {
+    FACEBOOK = "facebook",
+    TWITTER = "twitter",
+    LINKEDIN = "linkedin",
+    WHATSAPP = "whatsapp",
+    EMAIL = "email",
+    CLIPBOARD = "clipboard",
+    NATIVE = "native"
+}
+/**
+ * Enum for social platform share URLs (business logic)
+ */
+export declare enum SocialPlatformShareUrl {
+    FACEBOOK = "https://www.facebook.com/sharer/sharer.php",
+    TWITTER = "https://twitter.com/intent/tweet",
+    LINKEDIN = "https://www.linkedin.com/sharing/share-offsite/",
+    WHATSAPP = "https://wa.me/",
+    EMAIL = "mailto:"
+}

package/dist/enums/social-platform-enums.js

@@ -0,0 +1,27 @@
+/**
+ * Business logic enums for social sharing platforms (headless layer)
+ */
+/**
+ * Enum for social sharing platforms (business identifiers)
+ */
+export var SocialPlatform;
+(function (SocialPlatform) {
+    SocialPlatform["FACEBOOK"] = "facebook";
+    SocialPlatform["TWITTER"] = "twitter";
+    SocialPlatform["LINKEDIN"] = "linkedin";
+    SocialPlatform["WHATSAPP"] = "whatsapp";
+    SocialPlatform["EMAIL"] = "email";
+    SocialPlatform["CLIPBOARD"] = "clipboard";
+    SocialPlatform["NATIVE"] = "native";
+})(SocialPlatform || (SocialPlatform = {}));
+/**
+ * Enum for social platform share URLs (business logic)
+ */
+export var SocialPlatformShareUrl;
+(function (SocialPlatformShareUrl) {
+    SocialPlatformShareUrl["FACEBOOK"] = "https://www.facebook.com/sharer/sharer.php";
+    SocialPlatformShareUrl["TWITTER"] = "https://twitter.com/intent/tweet";
+    SocialPlatformShareUrl["LINKEDIN"] = "https://www.linkedin.com/sharing/share-offsite/";
+    SocialPlatformShareUrl["WHATSAPP"] = "https://wa.me/";
+    SocialPlatformShareUrl["EMAIL"] = "mailto:";
+})(SocialPlatformShareUrl || (SocialPlatformShareUrl = {}));

package/dist/enums/sort-enums.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Enum for sort types used in the store
+ * Note: Cannot use SDK SortType as it's for aggregations (COUNT/VALUE)
+ * while this enum represents user-facing sort options
+ */
+export declare enum SortType {
+    NEWEST = "newest",
+    NAME_ASC = "name_asc",
+    NAME_DESC = "name_desc",
+    PRICE_ASC = "price_asc",
+    PRICE_DESC = "price_desc",
+    RECOMMENDED = "recommended"
+}
+/**
+ * Default sort type
+ */
+export declare const DEFAULT_SORT_TYPE = SortType.NEWEST;

package/dist/enums/sort-enums.js

@@ -0,0 +1,18 @@
+/**
+ * Enum for sort types used in the store
+ * Note: Cannot use SDK SortType as it's for aggregations (COUNT/VALUE)
+ * while this enum represents user-facing sort options
+ */
+export var SortType;
+(function (SortType) {
+    SortType["NEWEST"] = "newest";
+    SortType["NAME_ASC"] = "name_asc";
+    SortType["NAME_DESC"] = "name_desc";
+    SortType["PRICE_ASC"] = "price_asc";
+    SortType["PRICE_DESC"] = "price_desc";
+    SortType["RECOMMENDED"] = "recommended";
+})(SortType || (SortType = {}));
+/**
+ * Default sort type
+ */
+export const DEFAULT_SORT_TYPE = SortType.NEWEST;

package/dist/react/Category.d.ts

@@ -0,0 +1,242 @@
+import React from 'react';
+import { categories } from '@wix/categories';
+import { AsChildChildren } from '@wix/headless-utils/react';
+export type Category = categories.Category;
+/**
+ * Props for Category.Root component
+ */
+export interface CategoryRootProps {
+    /** Category data */
+    category: Category;
+    /** Child components */
+    children: React.ReactNode;
+}
+/**
+ * Props for Category.Trigger component
+ */
+export interface CategoryTriggerProps {
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Custom render function when using asChild */
+    children?: AsChildChildren<{
+        category: Category;
+        isSelected: boolean;
+        onSelect: () => void;
+        setIsSelected: (isSelected: boolean) => void;
+    }>;
+    /** Callback when category is selected */
+    onSelect?: (category: Category) => void;
+    /** CSS classes to apply to the default element */
+    className?: string;
+}
+/**
+ * Props for Category.Label component
+ */
+export interface CategoryLabelProps {
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Custom render function when using asChild */
+    children?: AsChildChildren<{
+        name: string;
+        category: Category;
+    }>;
+    /** CSS classes to apply to the default element */
+    className?: string;
+}
+/**
+ * Props for Category.ID component
+ */
+export interface CategoryIDProps {
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Custom render function when using asChild */
+    children?: AsChildChildren<{
+        id: string;
+        category: Category;
+    }>;
+    /** CSS classes to apply to the default element */
+    className?: string;
+}
+/**
+ * Props for Category.Raw component
+ */
+export interface CategoryRawProps {
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Custom render function when using asChild */
+    children?: AsChildChildren<{
+        category: Category;
+        isSelected: boolean;
+    }>;
+    /** CSS classes to apply to the default element */
+    className?: string;
+}
+/**
+ * Props for CategoryFilter component
+ */
+export interface CategoryFilterProps {
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** Custom render function when using asChild */
+    children?: AsChildChildren<{
+        selectedCategory: Category | null;
+        setSelectedCategory: (category: Category | null) => void;
+    }>;
+    /** CSS classes to apply to the default element */
+    className?: string;
+    /** Label for the selected category display */
+    label?: string;
+}
+/**
+ * Root container for a single category item.
+ * This component sets up the necessary services for managing category state
+ * and provides category context to child components.
+ *
+ * @order 1
+ * @component
+ * @example
+ * ```tsx
+ * import { Category } from '@wix/headless-stores/react';
+ *
+ * <Category.Root category={category}>
+ *     <Category.Trigger />
+ *     <Category.Label />
+ *     <Category.ID />
+ * </Category.Root>
+ * ```
+ */
+export declare const Root: React.ForwardRefExoticComponent<CategoryRootProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Interactive element for selecting or triggering category actions.
+ * Provides category data and selection state to custom render functions.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Default usage
+ * <Category.Trigger className="px-4 py-2 rounded border hover:bg-surface-hover" />
+ *
+ * // Custom rendering with forwardRef
+ * <Category.Trigger asChild>
+ *   {React.forwardRef(({category, isSelected, onSelect, ...props}, ref) => (
+ *     <button
+ *       ref={ref}
+ *       {...props}
+ *       onClick={onSelect}
+ *       className={`px-4 py-2 rounded transition-colors ${
+ *         isSelected
+ *           ? 'bg-brand-primary text-white'
+ *           : 'border border-surface-subtle hover:bg-surface-hover'
+ *       }`}
+ *     >
+ *       {category.name}
+ *     </button>
+ *   ))}
+ * </Category.Trigger>
+ * ```
+ */
+export declare const Trigger: React.ForwardRefExoticComponent<CategoryTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+/**
+ * Displays the category name or label.
+ * Provides category name and full category data to custom render functions.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Default usage
+ * <Category.Label className="text-lg font-medium text-content-primary" />
+ *
+ * // Custom rendering with forwardRef
+ * <Category.Label asChild>
+ *   {React.forwardRef(({name, category, ...props}, ref) => (
+ *     <span ref={ref} {...props} className="text-lg font-medium text-content-primary">
+ *       {name}
+ *       {category.numberOfProducts > 0 && (
+ *         <span className="text-sm text-content-muted ml-2">
+ *           ({category.numberOfProducts})
+ *         </span>
+ *       )}
+ *     </span>
+ *   ))}
+ * </Category.Label>
+ * ```
+ */
+export declare const Label: React.ForwardRefExoticComponent<CategoryLabelProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Provides access to the category ID for advanced use cases.
+ * Typically used for tracking, analytics, or hidden form fields.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Default usage (hidden by default)
+ * <Category.ID className="hidden" />
+ *
+ * // Custom rendering with forwardRef
+ * <Category.ID asChild>
+ *   {React.forwardRef(({id, category, ...props}, ref) => (
+ *     <span
+ *       ref={ref}
+ *       {...props}
+ *       data-category-id={id}
+ *       className="sr-only"
+ *     >
+ *       Category ID: {id}
+ *     </span>
+ *   ))}
+ * </Category.ID>
+ * ```
+ */
+export declare const ID: React.ForwardRefExoticComponent<CategoryIDProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Provides access to the full category data for advanced use cases.
+ * Useful for custom implementations that need access to all category properties.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Custom rendering with forwardRef
+ * <Category.Raw asChild>
+ *   {React.forwardRef(({category, ...props}, ref) => (
+ *     <div
+ *       ref={ref}
+ *       {...props}
+ *       data-category-id={category._id}
+ *       className="category-raw-data"
+ *     >
+ *       <pre>{JSON.stringify(category, null, 2)}</pre>
+ *     </div>
+ *   ))}
+ * </Category.Raw>
+ * ```
+ */
+export declare const Raw: React.ForwardRefExoticComponent<CategoryRawProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Category filter component that provides category selection functionality.
+ * Provides selected category state and selection controls to custom render functions.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * // Default usage
+ * <CategoryFilter className="category-filter" />
+ *
+ * // With custom label
+ * <CategoryFilter label="Current Category:" />
+ *
+ * // Custom rendering with forwardRef
+ * <CategoryFilter asChild>
+ *   {React.forwardRef(({selectedCategory, setSelectedCategory, ...props}, ref) => (
+ *     <div ref={ref} {...props} className="custom-category-filter">
+ *       {selectedCategory && (
+ *         <span>Selected: {selectedCategory.name}</span>
+ *       )}
+ *       <button onClick={() => setSelectedCategory(null)}>
+ *         Clear Selection
+ *       </button>
+ *     </div>
+ *   ))}
+ * </CategoryFilter>
+ * ```
+ */
+export declare const CategoryFilter: React.ForwardRefExoticComponent<CategoryFilterProps & React.RefAttributes<HTMLElement>>;