chore: update tsdocs for layout configurations

packages/core/core-flows/src/settings/steps/clear-layout-configuration.ts

@@ -1,13 +1,33 @@
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The input to clear the layout configuration.
+ */
 export type ClearLayoutConfigurationStepInput = {
+  /**
+   * The zone that the layout configuration applies to.
+   */
   zone: string
+  /**
+   * The ID of the user whose layout configuration is cleared.
+   */
   user_id: string
 }
 
 export const clearLayoutConfigurationStepId = "clear-layout-configuration"
-
+/**
+ * This step clears a user's personal layout configuration for a zone,
+ * reverting them to the system default.
+ *
+ * @since 2.17.2
+ *
+ * @example
+ * const data = clearLayoutConfigurationStep({
+ *   zone: "products",
+ *   user_id: "user_123",
+ * })
+ */
 export const clearLayoutConfigurationStep = createStep(
   clearLayoutConfigurationStepId,
   async (input: ClearLayoutConfigurationStepInput, { container }) => {

packages/core/core-flows/src/settings/steps/set-active-layout-scope.ts

@@ -1,14 +1,39 @@
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The input for setting the active layout scope for a user in a zone.
+ */
 export type SetActiveLayoutScopeStepInput = {
+  /**
+   * The zone that the layout scope applies to.
+   */
   zone: string
+  /**
+   * The ID of the user whose active layout scope is set.
+   */
   user_id: string
+  /**
+   * The active layout scope to set for the user. If not provided, the
+   * user's active scope is cleared.
+   */
   scope?: "personal" | "default"
 }
 
 export const setActiveLayoutScopeStepId = "set-active-layout-scope"
-
+/**
+ * This step sets a user's active layout scope for a zone, which determines
+ * whether the user's personal or the system default configuration is shown.
+ *
+ * @since 2.17.2
+ *
+ * @example
+ * const data = setActiveLayoutScopeStep({
+ *   zone: "products",
+ *   user_id: "user_123",
+ *   scope: "personal",
+ * })
+ */
 export const setActiveLayoutScopeStep = createStep(
   setActiveLayoutScopeStepId,
   async (input: SetActiveLayoutScopeStepInput, { container }) => {

packages/core/core-flows/src/settings/steps/set-layout-configuration.ts

@@ -5,15 +5,45 @@ import {
 import { Modules } from "@medusajs/framework/utils"
 import { StepResponse, createStep } from "@medusajs/framework/workflows-sdk"
 
+/**
+ * The input for setting a layout configuration for a zone.
+ */
 export type SetLayoutConfigurationStepInput = {
+  /**
+   * The zone that the layout configuration applies to.
+   */
   zone: string
+  /**
+   * The ID of the user that the layout configuration belongs to.
+   */
   user_id: string
+  /**
+   * Whether to set the configuration as the system default for the zone,
+   * rather than the user's personal configuration.
+   */
   is_default?: boolean
+  /**
+   * The layout configuration data to set.
+   */
   configuration: LayoutConfigurationData
 }
 
 export const setLayoutConfigurationStepId = "set-layout-configuration"
-
+/**
+ * This step sets a layout configuration for a zone, either as the user's
+ * personal configuration or as the system default.
+ *
+ * @since 2.17.2
+ *
+ * @example
+ * const data = setLayoutConfigurationStep({
+ *   zone: "products",
+ *   user_id: "user_123",
+ *   configuration: {
+ *     // ...
+ *   },
+ * })
+ */
 export const setLayoutConfigurationStep = createStep(
   setLayoutConfigurationStepId,
   async (input: SetLayoutConfigurationStepInput, { container }) => {

packages/core/core-flows/src/settings/workflows/clear-layout-configuration.ts

@@ -5,13 +5,47 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { clearLayoutConfigurationStep, setActiveLayoutScopeStep } from "../steps"
 
+/**
+ * The data to clear a layout configuration.
+ */
 export type ClearLayoutConfigurationWorkflowInput = {
+  /**
+   * The zone that the layout configuration applies to.
+   */
   zone: string
+  /**
+   * The ID of the user whose layout configuration is cleared.
+   */
   user_id: string
 }
 
 export const clearLayoutConfigurationWorkflowId = "clear-layout-configuration"
-
+/**
+ * This workflow clears a user's personal layout configuration for a zone,
+ * reverting them to the system default. It also resets the user's active
+ * layout scope for the zone.
+ *
+ * This workflow is used by the
+ * [Clear Layout Configuration Admin API Route](https://docs.medusajs.com/api/admin#layouts_deletelayoutszoneconfiguration).
+ *
+ * You can use this workflow within your own customizations or custom workflows,
+ * allowing you to clear a layout configuration within your custom flows.
+ *
+ * @since 2.17.2
+ *
+ * @example
+ * const { result } = await clearLayoutConfigurationWorkflow(container)
+ *   .run({
+ *     input: {
+ *       zone: "products",
+ *       user_id: "user_123",
+ *     },
+ *   })
+ *
+ * @summary
+ *
+ * Clear a user's layout configuration for a zone.
+ */
 export const clearLayoutConfigurationWorkflow = createWorkflow(
   clearLayoutConfigurationWorkflowId,
   (input: WorkflowData<ClearLayoutConfigurationWorkflowInput>) => {

packages/core/core-flows/src/settings/workflows/set-layout-configuration.ts

@@ -10,15 +10,59 @@ import {
 } from "@medusajs/framework/workflows-sdk"
 import { setActiveLayoutScopeStep, setLayoutConfigurationStep } from "../steps"
 
+/**
+ * The data to set a layout configuration.
+ */
 export type SetLayoutConfigurationWorkflowInput = {
+  /**
+   * The zone that the layout configuration applies to.
+   */
   zone: string
+  /**
+   * The ID of the user that the layout configuration belongs to.
+   */
   user_id: string
+  /**
+   * Whether to set the configuration as the system default for the zone,
+   * rather than the user's personal configuration.
+   */
   is_default?: boolean
+  /**
+   * The layout configuration data to set.
+   */
   configuration: LayoutConfigurationData
 }
 
 export const setLayoutConfigurationWorkflowId = "set-layout-configuration"
-
+/**
+ * This workflow sets a layout configuration for a zone, either as the user's
+ * personal configuration or as the system default. It also persists the saved
+ * scope as the user's active view for the zone, so it sticks across reloads.
+ *
+ * This workflow is used by the
+ * [Set Layout Configuration Admin API Route](https://docs.medusajs.com/api/admin#layouts_postlayoutszoneconfiguration).
+ *
+ * You can use this workflow within your own customizations or custom workflows,
+ * allowing you to set a layout configuration within your custom flows.
+ *
+ * @since 2.17.2
+ *
+ * @example
+ * const { result } = await setLayoutConfigurationWorkflow(container)
+ *   .run({
+ *     input: {
+ *       zone: "products",
+ *       user_id: "user_123",
+ *       configuration: {
+ *         // ...
+ *       },
+ *     },
+ *   })
+ *
+ * @summary
+ *
+ * Set a layout configuration for a zone.
+ */
 export const setLayoutConfigurationWorkflow = createWorkflow(
   setLayoutConfigurationWorkflowId,
   (

packages/medusa/src/api/admin/layouts/[zone]/configuration/route.ts

@@ -43,6 +43,9 @@ const getConfigurations = async (
   }
 }
 
+/**
+ * @since 2.17.2
+ */
 export const GET = async (
   req: AuthenticatedMedusaRequest,
   res: MedusaResponse<HttpTypes.AdminLayoutConfigurationResponse>
@@ -58,6 +61,9 @@ export const GET = async (
   )
 }
 
+/**
+ * @since 2.17.2
+ */
 export const POST = async (
   req: AuthenticatedMedusaRequest<HttpTypes.AdminSetLayoutConfiguration>,
   res: MedusaResponse<HttpTypes.AdminLayoutConfigurationResponse>
@@ -82,6 +88,9 @@ export const POST = async (
   )
 }
 
+/**
+ * @since 2.17.2
+ */
 export const DELETE = async (
   req: AuthenticatedMedusaRequest,
   res: MedusaResponse<{ success: boolean }>

packages/medusa/src/api/admin/layouts/configurations/route.ts

@@ -5,6 +5,9 @@ import {
 import { HttpTypes } from "@medusajs/framework/types"
 import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
 
+/**
+ * @since 2.17.2
+ */
 export const GET = async (
   req: AuthenticatedMedusaRequest<HttpTypes.AdminGetLayoutConfigurationsParams>,
   res: MedusaResponse<HttpTypes.AdminLayoutConfigurationListResponse>

www/apps/api-reference/specs/admin/openapi.full.yaml

@@ -25830,7 +25830,7 @@ paths:
     delete:
       operationId: DeleteLayoutsZoneConfiguration
       summary: Clear Configuration of Layout
-      description: Clears all layout configurations for a given zone, including both personal and default configurations. This action will remove any customizations made by the user and revert to the system defaults.
+      description: Clears all user layout configurations for a given zone. This action will remove any customizations made by the user and revert to the system defaults.
       x-authenticated: true
       parameters:
         - name: zone

www/apps/api-reference/specs/admin/paths/admin_layouts_{zone}_configuration.yaml

@@ -100,9 +100,9 @@ delete:
   operationId: DeleteLayoutsZoneConfiguration
   summary: Clear Configuration of Layout
   description: >-
-    Clears all layout configurations for a given zone, including both personal
-    and default configurations. This action will remove any customizations made
-    by the user and revert to the system defaults.
+    Clears all user layout configurations for a given zone. This action will
+    remove any customizations made by the user and revert to the system
+    defaults.
   x-authenticated: true
   parameters:
     - name: zone

www/utils/generated/oas-output/operations/admin/delete_admin_layouts_[zone]_configuration.ts

@@ -2,7 +2,7 @@
  * @oas [delete] /admin/layouts/{zone}/configuration
  * operationId: DeleteLayoutsZoneConfiguration
  * summary: Clear Configuration of Layout
- * description: Clears all layout configurations for a given zone, including both personal and default configurations. This action will remove any customizations made by the user and revert to the system defaults.
+ * description: Clears all user layout configurations for a given zone. This action will remove any customizations made by the user and revert to the system defaults.
  * x-authenticated: true
  * parameters:
  *   - name: zone