@wix/headless-stores 0.0.36 → 0.0.38

package/cjs/dist/services/categories-list-service.js

@@ -0,0 +1,148 @@
+import { defineService, implementService } from "@wix/services-definitions";
+import { SignalsServiceDefinition, } from "@wix/services-definitions/core-services/signals";
+import { categories } from "@wix/categories";
+/**
+ * Service definition for the Categories List service.
+ * This defines the reactive API contract for managing a list of product categories.
+ *
+ * @constant
+ */
+export const CategoriesListServiceDefinition = defineService("categories-list");
+/**
+ * Implementation of the Categories List service that manages reactive categories data.
+ * This service provides signals for categories data, loading state, and error handling.
+ * The service is initialized with pre-loaded categories and maintains them in reactive signals.
+ *
+ * @example
+ * ```tsx
+ * import { CategoriesListService, CategoriesListServiceDefinition } from '@wix/stores/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function CategoriesComponent({ categoriesConfig }) {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [CategoriesListServiceDefinition, CategoriesListService.withConfig(categoriesConfig)]
+ *     ])}>
+ *       <CategoriesDisplay />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function CategoriesDisplay() {
+ *   const categoriesService = useService(CategoriesListServiceDefinition);
+ *   const categories = categoriesService.categories.get();
+ *   const isLoading = categoriesService.isLoading.get();
+ *   const error = categoriesService.error.get();
+ *
+ *   if (isLoading) return <div>Loading categories...</div>;
+ *   if (error) return <div>Error: {error}</div>;
+ *
+ *   return (
+ *     <ul>
+ *       {categories.map(category => (
+ *         <li key={category._id}>{category.name}</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export const CategoriesListService = implementService.withConfig()(CategoriesListServiceDefinition, ({ getService, config }) => {
+    const signalsService = getService(SignalsServiceDefinition);
+    const categoriesSignal = signalsService.signal(config.categories);
+    const isLoadingSignal = signalsService.signal(false);
+    const errorSignal = signalsService.signal(null);
+    return {
+        categories: categoriesSignal,
+        isLoading: isLoadingSignal,
+        error: errorSignal,
+    };
+});
+/**
+ * Loads categories list service configuration from the Wix Categories API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * all visible product categories. The "all-products" category is automatically moved to the front of the list.
+ *
+ * @returns {Promise<CategoriesListServiceConfig>} Promise that resolves to the categories configuration
+ *
+ * @example
+ * ```astro
+ * ---
+ * // Astro page example - pages/categories.astro
+ * import { loadCategoriesListServiceConfig } from '@wix/stores/services';
+  * import { CategoryList } from '@wix/stores/components';
+ *
+ * // Load categories data during SSR
+ * const categoriesConfig = await loadCategoriesListServiceConfig();
+ * ---
+ *
+ * <CategoryList.Root categoriesConfig={categoriesConfig}>
+ *   <CategoryList.ItemContent>
+ *     {({ category }) => (
+ *       <div>
+ *         <h3>{category.name}</h3>
+ *         <p>{category.description}</p>
+ *       </div>
+ *     )}
+ *   </CategoryList.ItemContent>
+ * </CategoryList.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Next.js page example - pages/categories.tsx
+ * import { GetServerSideProps } from 'next';
+ * import { loadCategoriesListServiceConfig } from '@wix/stores/services';
+  * import { CategoryList } from '@wix/stores/components';
+ *
+ * interface CategoriesPageProps {
+ *   categoriesConfig: Awaited<ReturnType<typeof loadCategoriesListServiceConfig>>;
+ * }
+ *
+ * export const getServerSideProps: GetServerSideProps<CategoriesPageProps> = async () => {
+ *   const categoriesConfig = await loadCategoriesListServiceConfig();
+ *
+ *   return {
+ *     props: {
+ *       categoriesConfig,
+ *     },
+ *   };
+ * };
+ *
+ * export default function CategoriesPage({ categoriesConfig }: CategoriesPageProps) {
+ *   return (
+ *     <CategoryList.Root categoriesConfig={categoriesConfig}>
+ *       <CategoryList.ItemContent>
+ *         {({ category }) => (
+ *           <div>
+ *             <h3>{category.name}</h3>
+ *             <p>{category.description}</p>
+ *           </div>
+ *         )}
+ *       </CategoryList.ItemContent>
+ *     </CategoryList.Root>
+ *   );
+ * }
+ * ```
+ */
+export async function loadCategoriesListServiceConfig() {
+    const categoriesResponse = await categories
+        .queryCategories({
+        treeReference: {
+            appNamespace: "@wix/stores",
+            treeKey: null,
+        },
+    })
+        .eq("visible", true)
+        .find();
+    const fetchedCategories = categoriesResponse.items || [];
+    // Sort categories to put "all-products" first, keep the rest in original order
+    const allProductsCategory = fetchedCategories.find((cat) => cat.slug === "all-products");
+    const otherCategories = fetchedCategories.filter((cat) => cat.slug !== "all-products");
+    const allCategories = allProductsCategory
+        ? [allProductsCategory, ...otherCategories]
+        : fetchedCategories;
+    return {
+        categories: allCategories,
+    };
+}

package/cjs/dist/services/category-service.d.ts

@@ -1,113 +1,158 @@
+import { categories } from "@wix/categories";
 import { type Signal } from "@wix/services-definitions/core-services/signals";
-import * as categories from "@wix/auto_sdk_categories_categories";
-export interface CategoryServiceAPI {
-    selectedCategory: Signal<string | null>;
-    categories: Signal<categories.Category[]>;
-    setSelectedCategory: (categoryId: string | null) => void;
-    loadCategories: () => Promise<void>;
-}
+/**
+ * Service definition for the Category service.
+ * This defines the reactive API contract for managing a single product category.
+ *
+ * @constant
+ */
 export declare const CategoryServiceDefinition: string & {
-    __api: CategoryServiceAPI;
+    __api: {
+        /** Reactive signal containing the current category data */
+        category: Signal<categories.Category>;
+    };
     __config: {};
     isServiceDefinition?: boolean;
-} & CategoryServiceAPI;
-export interface CategoryServiceConfig {
-    categories: categories.Category[];
-    initialCategoryId?: string | null;
-    onCategoryChange?: (categoryId: string | null, category: categories.Category | null) => void;
-}
+} & {
+    /** Reactive signal containing the current category data */
+    category: Signal<categories.Category>;
+};
+/**
+ * Configuration interface for the Category service.
+ * Contains the initial category data that will be loaded into the service.
+ *
+ * @interface CategoryServiceConfig
+ */
+export type CategoryServiceConfig = {
+    /** The category object to initialize the service with */
+    category: categories.Category;
+};
+/**
+ * Implementation of the Category service that manages reactive category data.
+ * This service provides a signal for category data and maintains it in a reactive state.
+ * The service is initialized with pre-loaded category data.
+ *
+ * @example
+ * ```tsx
+ * import { CategoryService, CategoryServiceDefinition } from '@wix/stores/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function CategoryComponent({ categoryConfig }) {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [CategoryServiceDefinition, CategoryService.withConfig(categoryConfig)]
+ *     ])}>
+ *       <CategoryDisplay />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function CategoryDisplay() {
+ *   const categoryService = useService(CategoryServiceDefinition);
+ *   const category = categoryService.category.get();
+ *
+ *   return (
+ *     <div>
+ *       <h1>{category.name}</h1>
+ *       <p>{category.description}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export declare const CategoryService: import("@wix/services-definitions").ServiceFactory<string & {
-    __api: CategoryServiceAPI;
+    __api: {
+        /** Reactive signal containing the current category data */
+        category: Signal<categories.Category>;
+    };
     __config: {};
     isServiceDefinition?: boolean;
-} & CategoryServiceAPI, CategoryServiceConfig>;
+} & {
+    /** Reactive signal containing the current category data */
+    category: Signal<categories.Category>;
+}, CategoryServiceConfig>;
 /**
- * Loads categories configuration from the Wix Categories API for SSR initialization.
+ * Loads category service configuration from the Wix Categories API for SSR initialization.
  * This function is designed to be used during Server-Side Rendering (SSR) to preload
- * initial categories data that will be passed to the Category.Root component.
- * Fetches all visible categories and sorts them with "all-products" category first.
+ * a specific category by slug that will be used to configure the CategoryService.
  *
- * @returns Promise that resolves to an object containing categories array
+ * @param {string} slug - The category slug to load
+ * @returns {Promise} Promise that resolves to either success with config or not-found result
  *
  * @example
  * ```astro
  * ---
- * // Astro page example - pages/categories.astro
- * import { loadCategoriesConfig } from '@wix/stores/services';
+ * // Astro page example - pages/category/[slug].astro
+ * import { loadCategoryServiceConfig } from '@wix/stores/services';
  * import { Category } from '@wix/stores/components';
  *
- * // Load categories data during SSR
- * const categoryConfig = await loadCategoriesConfig();
+ * // Get category slug from URL params
+ * const { slug } = Astro.params;
+ *
+ * // Load category data during SSR
+ * const categoryResult = await loadCategoryServiceConfig(slug);
+ *
+ * // Handle not found case
+ * if (categoryResult.type === 'not-found') {
+ *   return Astro.redirect('/404');
+ * }
  * ---
  *
- * <Category.Root categoryConfig={categoryConfig}>
- *   <Category.List>
- *     {({ categories, selectedCategory, setSelectedCategory }) => (
- *       <nav className="category-nav">
- *         <h2>Shop by Category</h2>
- *         {categories.map(category => (
- *           <button
- *             key={category.id}
- *             onClick={() => setSelectedCategory(category.id)}
- *             className={selectedCategory === category.id ? 'active' : ''}
- *           >
- *             {category.name}
- *           </button>
- *         ))}
- *       </nav>
- *     )}
- *   </Category.List>
+ * <Category.Root categoryConfig={categoryResult.config}>
+ *   <Category.Name>
+ *     {({ name }) => <h1>{name}</h1>}
+ *   </Category.Name>
  * </Category.Root>
  * ```
  *
  * @example
  * ```tsx
- * // Next.js page example - pages/categories.tsx
+ * // Next.js page example - pages/category/[slug].tsx
  * import { GetServerSideProps } from 'next';
- * import { loadCategoriesConfig } from '@wix/stores/services';
+ * import { loadCategoryServiceConfig } from '@wix/stores/services';
  * import { Category } from '@wix/stores/components';
  *
  * interface CategoryPageProps {
- *   categoryConfig: Awaited<ReturnType<typeof loadCategoriesConfig>>;
+ *   categoryConfig: Awaited<ReturnType<typeof loadCategoryServiceConfig>>['config'];
  * }
  *
- * export const getServerSideProps: GetServerSideProps<CategoryPageProps> = async () => {
- *   // Load categories data during SSR
- *   const categoryConfig = await loadCategoriesConfig();
+ * export const getServerSideProps: GetServerSideProps<CategoryPageProps> = async ({ params }) => {
+ *   const slug = params?.slug as string;
+ *
+ *   // Load category data during SSR
+ *   const categoryResult = await loadCategoryServiceConfig(slug);
+ *
+ *   // Handle not found case
+ *   if (categoryResult.type === 'not-found') {
+ *     return {
+ *       notFound: true,
+ *     };
+ *   }
  *
  *   return {
  *     props: {
- *       categoryConfig,
+ *       categoryConfig: categoryResult.config,
  *     },
  *   };
  * };
  *
  * export default function CategoryPage({ categoryConfig }: CategoryPageProps) {
  *   return (
- *     <div>
- *       <h1>Product Categories</h1>
- *       <Category.Root categoryConfig={categoryConfig}>
- *         <Category.List>
- *           {({ categories, selectedCategory, setSelectedCategory }) => (
- *             <nav className="category-nav">
- *               {categories.map(category => (
- *                 <button
- *                   key={category.id}
- *                   onClick={() => setSelectedCategory(category.id)}
- *                   className={`category-btn ${selectedCategory === category.id ? 'active' : ''}`}
- *                 >
- *                   {category.name}
- *                 </button>
- *               ))}
- *             </nav>
- *           )}
- *         </Category.List>
- *       </Category.Root>
- *     </div>
+ *     <Category.Root categoryConfig={categoryConfig}>
+ *       <Category.Name>
+ *         {({ name }) => <h1>{name}</h1>}
+ *       </Category.Name>
+ *     </Category.Root>
  *   );
  * }
  * ```
  */
-export declare function loadCategoriesConfig(): Promise<{
-    categories: categories.Category[];
+export declare function loadCategoryServiceConfig(slug: string): Promise<{
+    /** Type "success" means that the category was found and the config is valid */
+    type: "success";
+    /** The category config containing the loaded category data */
+    config: CategoryServiceConfig;
+} | {
+    /** Type "not-found" means that the category was not found */
+    type: "not-found";
 }>;

package/cjs/dist/services/category-service.js

@@ -1,156 +1,147 @@
 import { defineService, implementService } from "@wix/services-definitions";
+import { categories } from "@wix/categories";
 import { SignalsServiceDefinition, } from "@wix/services-definitions/core-services/signals";
-import * as categories from "@wix/auto_sdk_categories_categories";
-export const CategoryServiceDefinition = defineService("category-service");
+/**
+ * Service definition for the Category service.
+ * This defines the reactive API contract for managing a single product category.
+ *
+ * @constant
+ */
+export const CategoryServiceDefinition = defineService("category");
+/**
+ * Implementation of the Category service that manages reactive category data.
+ * This service provides a signal for category data and maintains it in a reactive state.
+ * The service is initialized with pre-loaded category data.
+ *
+ * @example
+ * ```tsx
+ * import { CategoryService, CategoryServiceDefinition } from '@wix/stores/services';
+ * import { useService } from '@wix/services-manager-react';
+ *
+ * function CategoryComponent({ categoryConfig }) {
+ *   return (
+ *     <ServiceProvider services={createServicesMap([
+ *       [CategoryServiceDefinition, CategoryService.withConfig(categoryConfig)]
+ *     ])}>
+ *       <CategoryDisplay />
+ *     </ServiceProvider>
+ *   );
+ * }
+ *
+ * function CategoryDisplay() {
+ *   const categoryService = useService(CategoryServiceDefinition);
+ *   const category = categoryService.category.get();
+ *
+ *   return (
+ *     <div>
+ *       <h1>{category.name}</h1>
+ *       <p>{category.description}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
 export const CategoryService = implementService.withConfig()(CategoryServiceDefinition, ({ getService, config }) => {
     const signalsService = getService(SignalsServiceDefinition);
-    const selectedCategory = signalsService.signal((config?.initialCategoryId || null));
-    const categories = signalsService.signal(config?.categories);
-    const loadCategories = async () => {
-        const { categories: loadedCategories } = await loadCategoriesConfig();
-        categories.set(loadedCategories);
-    };
-    // Track if this is the initial load to prevent navigation on service creation
-    let isInitialLoad = true;
-    const setSelectedCategory = (categoryId) => {
-        selectedCategory.set(categoryId);
-    };
-    // Subscribe to category changes and handle navigation as a side effect
-    signalsService.effect(() => {
-        const categoryId = selectedCategory.get();
-        // Skip navigation on initial load (when service is first created)
-        if (isInitialLoad) {
-            isInitialLoad = false;
-            return;
-        }
-        // If a navigation handler is provided, use it
-        if (config?.onCategoryChange) {
-            const category = categoryId
-                ? config?.categories.find((cat) => cat._id === categoryId) || null
-                : null;
-            config.onCategoryChange(categoryId, category);
-        }
-    });
+    const categorySignal = signalsService.signal(config.category);
     return {
-        selectedCategory,
-        categories,
-        setSelectedCategory,
-        loadCategories,
+        category: categorySignal,
     };
 });
 /**
- * Loads categories configuration from the Wix Categories API for SSR initialization.
+ * Loads category service configuration from the Wix Categories API for SSR initialization.
  * This function is designed to be used during Server-Side Rendering (SSR) to preload
- * initial categories data that will be passed to the Category.Root component.
- * Fetches all visible categories and sorts them with "all-products" category first.
+ * a specific category by slug that will be used to configure the CategoryService.
  *
- * @returns Promise that resolves to an object containing categories array
+ * @param {string} slug - The category slug to load
+ * @returns {Promise} Promise that resolves to either success with config or not-found result
  *
  * @example
  * ```astro
  * ---
- * // Astro page example - pages/categories.astro
- * import { loadCategoriesConfig } from '@wix/stores/services';
+ * // Astro page example - pages/category/[slug].astro
+ * import { loadCategoryServiceConfig } from '@wix/stores/services';
  * import { Category } from '@wix/stores/components';
  *
- * // Load categories data during SSR
- * const categoryConfig = await loadCategoriesConfig();
+ * // Get category slug from URL params
+ * const { slug } = Astro.params;
+ *
+ * // Load category data during SSR
+ * const categoryResult = await loadCategoryServiceConfig(slug);
+ *
+ * // Handle not found case
+ * if (categoryResult.type === 'not-found') {
+ *   return Astro.redirect('/404');
+ * }
  * ---
  *
- * <Category.Root categoryConfig={categoryConfig}>
- *   <Category.List>
- *     {({ categories, selectedCategory, setSelectedCategory }) => (
- *       <nav className="category-nav">
- *         <h2>Shop by Category</h2>
- *         {categories.map(category => (
- *           <button
- *             key={category.id}
- *             onClick={() => setSelectedCategory(category.id)}
- *             className={selectedCategory === category.id ? 'active' : ''}
- *           >
- *             {category.name}
- *           </button>
- *         ))}
- *       </nav>
- *     )}
- *   </Category.List>
+ * <Category.Root categoryConfig={categoryResult.config}>
+ *   <Category.Name>
+ *     {({ name }) => <h1>{name}</h1>}
+ *   </Category.Name>
  * </Category.Root>
  * ```
  *
  * @example
  * ```tsx
- * // Next.js page example - pages/categories.tsx
+ * // Next.js page example - pages/category/[slug].tsx
  * import { GetServerSideProps } from 'next';
- * import { loadCategoriesConfig } from '@wix/stores/services';
+ * import { loadCategoryServiceConfig } from '@wix/stores/services';
  * import { Category } from '@wix/stores/components';
  *
  * interface CategoryPageProps {
- *   categoryConfig: Awaited<ReturnType<typeof loadCategoriesConfig>>;
+ *   categoryConfig: Awaited<ReturnType<typeof loadCategoryServiceConfig>>['config'];
  * }
  *
- * export const getServerSideProps: GetServerSideProps<CategoryPageProps> = async () => {
- *   // Load categories data during SSR
- *   const categoryConfig = await loadCategoriesConfig();
+ * export const getServerSideProps: GetServerSideProps<CategoryPageProps> = async ({ params }) => {
+ *   const slug = params?.slug as string;
+ *
+ *   // Load category data during SSR
+ *   const categoryResult = await loadCategoryServiceConfig(slug);
+ *
+ *   // Handle not found case
+ *   if (categoryResult.type === 'not-found') {
+ *     return {
+ *       notFound: true,
+ *     };
+ *   }
  *
  *   return {
  *     props: {
- *       categoryConfig,
+ *       categoryConfig: categoryResult.config,
  *     },
  *   };
  * };
  *
  * export default function CategoryPage({ categoryConfig }: CategoryPageProps) {
  *   return (
- *     <div>
- *       <h1>Product Categories</h1>
- *       <Category.Root categoryConfig={categoryConfig}>
- *         <Category.List>
- *           {({ categories, selectedCategory, setSelectedCategory }) => (
- *             <nav className="category-nav">
- *               {categories.map(category => (
- *                 <button
- *                   key={category.id}
- *                   onClick={() => setSelectedCategory(category.id)}
- *                   className={`category-btn ${selectedCategory === category.id ? 'active' : ''}`}
- *                 >
- *                   {category.name}
- *                 </button>
- *               ))}
- *             </nav>
- *           )}
- *         </Category.List>
- *       </Category.Root>
- *     </div>
+ *     <Category.Root categoryConfig={categoryConfig}>
+ *       <Category.Name>
+ *         {({ name }) => <h1>{name}</h1>}
+ *       </Category.Name>
+ *     </Category.Root>
  *   );
  * }
  * ```
  */
-export async function loadCategoriesConfig() {
-    try {
-        const categoriesResponse = await categories
-            .queryCategories({
-            treeReference: {
-                appNamespace: "@wix/stores",
-                treeKey: null,
-            },
-        })
-            .eq("visible", true)
-            .find();
-        const fetchedCategories = categoriesResponse.items || [];
-        // Sort categories to put "all-products" first, keep the rest in original order
-        const allProductsCategory = fetchedCategories.find((cat) => cat.slug === "all-products");
-        const otherCategories = fetchedCategories.filter((cat) => cat.slug !== "all-products");
-        const allCategories = allProductsCategory
-            ? [allProductsCategory, ...otherCategories]
-            : fetchedCategories;
-        return {
-            categories: allCategories,
-        };
-    }
-    catch (error) {
-        console.warn("Failed to load categories:", error);
+export async function loadCategoryServiceConfig(slug) {
+    const category = await categories
+        .queryCategories({
+        treeReference: {
+            appNamespace: "@wix/stores",
+        },
+    })
+        .eq("slug", slug)
+        .find();
+    if (category.items.length === 0) {
         return {
-            categories: [],
+            type: "not-found",
         };
     }
+    return {
+        type: "success",
+        config: {
+            category: category.items[0],
+        },
+    };
 }

package/cjs/dist/services/index.d.ts

@@ -1,10 +1,9 @@
-export { CatalogService, CatalogServiceDefinition, } from "./catalog-service.js";
-export { CategoryService, CategoryServiceDefinition, loadCategoriesConfig, } from "./category-service.js";
-export { CollectionService, CollectionServiceDefinition, loadCollectionServiceConfig, } from "./collection-service.js";
-export { FilterService, FilterServiceDefinition, Filter, AvailableOptions, } from "./filter-service.js";
+export { CategoryService, CategoryServiceDefinition, loadCategoryServiceConfig, CategoryServiceConfig, } from "./category-service.js";
+export { CategoriesListService, CategoriesListServiceDefinition, loadCategoriesListServiceConfig, CategoriesListServiceConfig, } from "./categories-list-service.js";
 export { ProductModifiersService, ProductModifiersServiceDefinition, } from "./product-modifiers-service.js";
 export { ProductService, ProductServiceDefinition, loadProductServiceConfig, } from "./product-service.js";
-export { RelatedProductsService, RelatedProductsServiceDefinition, loadRelatedProductsServiceConfig, } from "./related-products-service.js";
 export { SelectedVariantService, SelectedVariantServiceDefinition, } from "./selected-variant-service.js";
-export { ProductListService, ProductsListServiceDefinition, loadProductsListServiceConfig, } from "./products-list-service.js";
-export { SortService, SortServiceDefinition, SortBy } from "./sort-service.js";
+export { ProductListService, ProductsListServiceDefinition, loadProductsListServiceConfig, ProductsListServiceConfig, } from "./products-list-service.js";
+export { SortType, ProductsListSortService, ProductsListSortServiceDefinition, } from "./products-list-sort-service.js";
+export { InventoryStatusType, ProductsListFiltersService, ProductsListFiltersServiceDefinition, loadProductsListFiltersServiceConfig, ProductsListFiltersServiceConfig, } from "./products-list-filters-service.js";
+export { ProductsListPaginationService, ProductsListPaginationServiceDefinition, } from "./products-list-pagination-service.js";