docs(headless-react): more typedoc annotations (#4890)

https://coveord.atlassian.net/browse/LENS-2449 A number of updates meant to improve the generated typedoc documentation for the headless-react package. I've added links to docs.coveo.com in a few places, but it's expected that they won't work until I merge coveo/doc_jekyll-public-site#12443 (probably early next week) Live demo: https://docs.coveo.com/en/headless-react/latest/reference Notably: https://docs.coveo.com/en/headless-react/latest/reference/functions/SSR_Commerce.index.defineCommerceEngine.html https://docs.coveo.com/en/headless-react/latest/reference/functions/SSR_Commerce.index.buildProviderWithDefinition.html https://docs.coveo.com/en/headless-react/latest/reference/types/SSR_Commerce.index.ProductList.html https://docs.coveo.com/en/headless-react/latest/reference/types/SSR_Commerce.index.SearchBox.html --------- Co-authored-by: Frederic Beaudoin <[email protected]>
coveo · Jan 24, 2025 · 5e06b8b · 5e06b8b
1 parent 99da9ad
commit 5e06b8b
Show file tree

Hide file tree

Showing 14 changed files with 59 additions and 12 deletions.
diff --git a/packages/headless-react/README.md b/packages/headless-react/README.md
@@ -7,7 +7,6 @@
 
 ## Learn more
 
-<!-- TODO: KIT-3698: Add link to headless-react/ssr-commerce link in public doc -->
+- Checkout our [Documentation for SSR Search](https://docs.coveo.com/en/headless/latest/usage/headless-server-side-rendering/) and refer to [samples/headless-ssr](https://github.com/coveo/ui-kit/tree/master/packages/samples/headless-ssr) for examples.
 
-- Checkout our [Documentation](https://docs.coveo.com/en/headless/latest/usage/headless-server-side-rendering/)
-- Refer to [samples/headless-ssr-commerce](https://github.com/coveo/ui-kit/tree/master/packages/samples/headless-ssr-commerce/) for examples.
+- Checkout our [Documentation for SSR Commerce](https://docs.coveo.com/en/obif0156) and refer to [samples/headless-ssr-commerce](https://github.com/coveo/ui-kit/tree/master/packages/samples/headless-ssr-commerce/) for examples.
diff --git a/packages/headless-react/src/ssr-commerce/commerce-engine.tsx b/packages/headless-react/src/ssr-commerce/commerce-engine.tsx
@@ -22,6 +22,11 @@ import {
   ReactEngineDefinition,
 } from './types.js';
 
+/**
+ * A React engine definition that includes context providers for static and hydrated states.
+ *
+ * @group Engine
+ *  */
 export type ReactCommerceEngineDefinition<
   TControllers extends ControllerDefinitionsMap<Controller>,
   TSolutionType extends SolutionType,
@@ -38,11 +43,11 @@ export function createSingletonContext<
 }
 
 /**
+ * Returns engine and controller hooks, and context providers.
  *
- * Returns controller hooks as well as SSR and CSR context providers that can be used to interact with a Commerce engine
- *  on the server and client side respectively.
+ * See [Define the commerce engine and controllers](docs.coveo.com/en/obif0156#define-the-commerce-engine-and-controllers).
  *
- * @group React
+ * @group Engine
  */
 export function defineCommerceEngine<
   TControllers extends ControllerDefinitionsMap<Controller>,

diff --git a/packages/headless-react/src/ssr-commerce/index.ts b/packages/headless-react/src/ssr-commerce/index.ts
@@ -3,3 +3,4 @@ export {buildProviderWithDefinition} from './providers.js';
 export type {ReactCommerceEngineDefinition} from './commerce-engine.js';
 export {MissingEngineProviderError} from '../errors.js';
 export {defineCommerceEngine} from './commerce-engine.js';
+export {ReactEngineDefinition} from './types.js';
diff --git a/packages/headless-react/src/ssr-commerce/providers.tsx b/packages/headless-react/src/ssr-commerce/providers.tsx
@@ -35,7 +35,13 @@ function getController<T extends Controller>(
 }
 
 /**
- * @group React
+ * Providers take care of displaying your page with the static
+ * state, and then hydrating the state and displaying the page
+ * with the hydrated state. They are required for your controller hooks to function.
+ *
+ * See [Create providers](docs.coveo.com/en/obif0156/#create-providers).
+ *
+ * @group Providers
  */
 export function buildProviderWithDefinition<
   TControllers extends ControllerDefinitionsMap<Controller>,

diff --git a/packages/headless-react/typedoc.json b/packages/headless-react/typedoc.json
@@ -8,5 +8,6 @@
   "categorizeByGroup": true,
   "entryPoints": ["./temp/ssr-commerce.json", "./temp/ssr.json"],
   "gitRevision": "typedoc-POC",
-  "plugin": ["./typedoc/dist/index.js"]
+  "plugin": ["./typedoc/dist/index.js"],
+  "projectDocuments": ["./README.md"]
 }
diff --git a/packages/headless-react/typedoc/COMMERCEREADME.md b/packages/headless-react/typedoc/COMMERCEREADME.md
@@ -0,0 +1,8 @@
+# Headless React Utils for SSR
+
+`@coveo/headless-react/ssr-commerce` provides React utilities for server-side rendering with Headless Commerce controllers.
+
+## Learn more
+
+- Checkout our [Documentation](https://docs.coveo.com/en/obif0156)
+- Refer to [samples/headless-ssr-commerce](https://github.com/coveo/ui-kit/tree/master/packages/samples/headless-ssr-commerce/) for examples.
diff --git a/packages/headless-react/typedoc/SEARCHREADME.md b/packages/headless-react/typedoc/SEARCHREADME.md
@@ -0,0 +1,8 @@
+# Headless React Utils for SSR
+
+`@coveo/headless-react/ssr` provides React utilities for server-side rendering with headless controllers.
+
+## Learn more
+
+- Checkout our [Documentation for SSR Search](https://docs.coveo.com/en/headless/latest/usage/headless-server-side-rendering/)
+- Refer to [samples/headless-ssr](https://github.com/coveo/ui-kit/tree/master/packages/samples/headless-ssr) for examples.
diff --git a/packages/headless-react/typedoc/configs/ssr-commerce.typedoc.json b/packages/headless-react/typedoc/configs/ssr-commerce.typedoc.json
@@ -6,8 +6,8 @@
   },
   "categorizeByGroup": true,
   "groupOrder": [
-    "React",
     "Engine",
+    "Providers",
     "Definers",
     "Controllers",
     "Buildable controllers",
@@ -16,7 +16,7 @@
     "*"
   ],
   "name": "SSR Commerce",
-  "readme": "none",
+  "readme": "../COMMERCEREADME.md",
   "entryPoints": ["../../src/ssr-commerce/index.ts"],
   "gitRevision": "typedoc-POC",
   "plugin": ["../../typedoc/dist/index.js"],

diff --git a/packages/headless-react/typedoc/configs/ssr.typedoc.json b/packages/headless-react/typedoc/configs/ssr.typedoc.json
@@ -15,7 +15,7 @@
     "*"
   ],
   "name": "SSR Search",
-  "readme": "none",
+  "readme": "../SEARCHREADME.md",
   "entryPoints": ["../../src/ssr/index.ts"],
   "gitRevision": "typedoc-POC",
   "plugin": ["../../typedoc/dist/index.js"]

diff --git a/packages/headless-react/typedoc/documents/hooks.md b/packages/headless-react/typedoc/documents/hooks.md
@@ -7,6 +7,8 @@ title: Controller hooks
 This package provides React hooks for controllers defined in the Engine Definition. Hooks allow you to access controller state and methods easily within your React components.
 Without these hooks, you would need to manually pass down props through every component or implement your own provider solution, which can be cumbersome and error-prone.
 
+See [Headless commerce usage (SSR): Define the commerce engine and controllers](https://docs.coveo.com/en/obif0156/#define-the-commerce-engine-and-controllers)
+
 ## Usage
 
 1. Create an engine configuration

diff --git a/packages/headless/src/controllers/commerce/product-list/headless-product-list.ssr.ts b/packages/headless/src/controllers/commerce/product-list/headless-product-list.ssr.ts
@@ -10,7 +10,12 @@ import {
 } from '../product-listing/headless-product-listing.js';
 import {buildSearch, Search} from '../search/headless-search.js';
 
-export type {ProductListingState as ProductListState} from '../product-listing/headless-product-listing.js';
+export type {
+  ProductListing,
+  ProductListingState as ProductListState,
+} from '../product-listing/headless-product-listing.js';
+export type {Search} from '../search/headless-search.js';
+
 export type ProductList = Pick<
   ProductListing | Search,
   'state' | 'subscribe' | 'interactiveProduct' | 'promoteChildToParent'

diff --git a/packages/headless/src/controllers/commerce/search-box/headless-search-box.ssr.ts b/packages/headless/src/controllers/commerce/search-box/headless-search-box.ssr.ts
@@ -11,6 +11,7 @@ export type {
   SearchBoxState,
   SearchBox,
   SearchBoxProps,
+  CoreSearchBox,
 } from './headless-search-box.js';
 export type {SearchBoxOptions, Suggestion};
 

diff --git a/packages/headless/src/controllers/commerce/search-box/headless-search-box.ts b/packages/headless/src/controllers/commerce/search-box/headless-search-box.ts
@@ -54,6 +54,7 @@ export type {
   SuggestionHighlightingOptions,
   Suggestion,
   Delimiters,
+  CoreSearchBox,
 };
 
 export interface SearchBoxProps {

diff --git a/packages/headless/src/ssr-commerce.index.ts b/packages/headless/src/ssr-commerce.index.ts
@@ -196,6 +196,8 @@ export {defineParameterManager} from './controllers/commerce/core/parameter-mana
 export type {
   ProductList,
   ProductListState,
+  ProductListing,
+  Search,
 } from './controllers/commerce/product-list/headless-product-list.ssr.js';
 export {defineProductList} from './controllers/commerce/product-list/headless-product-list.ssr.js';
 
@@ -205,6 +207,7 @@ export {defineProductView} from './controllers/commerce/product-view/headless-pr
 export type {
   RecommendationsState,
   Recommendations,
+  RecommendationsDefinition,
 } from './controllers/commerce/recommendations/headless-recommendations.ssr.js';
 export {defineRecommendations} from './controllers/commerce/recommendations/headless-recommendations.ssr.js';
 
@@ -237,6 +240,7 @@ export type {
   SearchBoxState,
   Suggestion,
   SearchBoxDefinition,
+  CoreSearchBox,
 } from './controllers/commerce/search-box/headless-search-box.ssr.js';
 export {defineSearchBox} from './controllers/commerce/search-box/headless-search-box.ssr.js';
 
@@ -321,6 +325,12 @@ export type {
   InstantProductsDefinition,
 } from './controllers/commerce/instant-products/headless-instant-products.ssr.js';
 export {defineInstantProducts} from './controllers/commerce/instant-products/headless-instant-products.ssr.js';
+
+export type {
+  InteractiveProduct,
+  InteractiveProductOptions,
+  InteractiveProductProps,
+} from './controllers/commerce/core/interactive-product/headless-core-interactive-product.js';
 // TODO: KIT-3391 - export other SSR commerce controllers
 
 //#endregion