docs: document widget zones changes + caching support in cloud (#16217)

Author: shahednasser

www/apps/book/app/learn/customization/customize-admin/widget/page.mdx

@@ -76,7 +76,7 @@ export const highlights = [
   ["19", "fields", "Specify the product's brand to be retrieved."],
   ["23", "brandName", "Get brand name from the query request."],
   ["53", "defineWidgetConfig", "Export the widget's configurations"],
-  ["54", "zone", "Show the widget at the top of the product details page."]
+  ["54", "zone", "Show the widget in the product details page."]
 ]
 
 ```tsx title="src/admin/widgets/product-brand.tsx" highlights={highlights}
@@ -133,7 +133,7 @@ const ProductBrandWidget = ({
 }
 
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 
 export default ProductBrandWidget
@@ -144,7 +144,7 @@ A widget's file must export:
 - A React component to be rendered in the specified injection zone. The component must be the file's default export.
 - A configuration object created with `defineWidgetConfig` from the Admin Extension SDK. The function receives an object as a parameter that has a `zone` property, whose value is the zone to inject the widget to.
 
-Since the widget is injected at the top of the product details page, the widget receives the product's details as a parameter.
+Since the widget is injected into the product details page, the widget receives the product's details as a parameter.
 
 In the widget, you use [Tanstack (React) Query](https://tanstack.com/query/latest) to query the Medusa server. Tanstack Query provides features like asynchronous state management and optimized caching. In the `queryFn` function that executes the query, you use the JS SDK to send a request to the [Get Product API Route](!api!/admin/products/get-a-product), passing `+brand.*` in the `fields` query parameter to retrieve the product's brand.
 

www/apps/book/app/learn/debugging-and-testing/feature-flags/page.mdx

@@ -187,7 +187,7 @@ const ProductWidget = () => {
 }
 
 export const config = defineWidgetConfig({
-  zone: "product.details.after",
+  zone: "product.details",
 })
 
 export default ProductWidget

www/apps/book/app/learn/fundamentals/admin/constraints/page.mdx

@@ -34,25 +34,25 @@ const ProductWidget = () => {
 A widget zone's value must be wrapped in double or single quotes. It can't be a template literal or a variable. Otherwise, Medusa doesn't register the widget correctly.
 
 export const zoneHighlights = [
-  ["3", "`product.details.before`", "Don't specify the value of `zone` as a template literal."],
+  ["3", "`product.details`", "Don't specify the value of `zone` as a template literal."],
   ["9", "ZONE", "Don't specify a variable as the value of `zone`."],
-  ["14", `"product.details.before"`, "Wrap the value of `zone` in double or single quotes."]
+  ["14", `"product.details"`, "Wrap the value of `zone` in double or single quotes."]
 ]
 
 ```ts highlights={zoneHighlights}
 // Don't
 export const config = defineWidgetConfig({
-  zone: `product.details.before`,
+  zone: `product.details`,
 })
 
 // Don't
-const ZONE = "product.details.after"
+const ZONE = "product.details"
 export const config = defineWidgetConfig({
   zone: ZONE,
 })
 
 // Do
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 ```

www/apps/book/app/learn/fundamentals/admin/custom-injection-zones/page.mdx

@@ -126,11 +126,17 @@ Refer to the [LayoutComposer](!resources!/admin-components/components/layout-com
 
 ### Custom Zone Naming Convention
 
-Custom injection zones should follow the pattern `{resource-name}.{page-context}.{position}`, where:
+Custom injection zones should follow the pattern `{resource-name}.{page-context}` for the main section, and `{resource-name}.{page-context}.{section}` for other sections, where:
 
 - `resource-name`: The name of the resource being accessed in the page. For example, `brand` in the example above.
 - `page-context`: The page or section context. For example, `details` for a details page or `list` for a list page.
-- `position`: One of `before`, `after`, `side.before`, or `side.after`.
+- `section`: The name of the layout section the zone belongs to, if it isn't the main one. For example, `side` for the side section of a two-column layout.
+
+<Note>
+
+Don't add a `.before` or `.after` suffix to your zone names. These suffixes are deprecated since [Medusa v2.17.2](https://github.com/medusajs/medusa/releases/tag/v2.17.2), as admin users now change a widget's placement with [Layout Configurations](!user-guide!/tips/layout-configurations).
+
+</Note>
 
 This naming convention helps avoid conflicts between different plugins and makes zones easier to identify.
 
@@ -145,10 +151,9 @@ To register the injection zones, augment the `InjectionZoneRegistry` interface t
 ```ts title="index.d.ts"
 declare module "@medusajs/admin-shared" {
   interface InjectionZoneRegistry {
-    "brand.details.before": true
-    "brand.details.after": true
-    "brand.details.side.before": true
-    "brand.details.side.after": true
+    "brand.details": true
+    "brand.details.side": true
+    "brand.list": true
   }
 }
 ```
@@ -191,15 +196,15 @@ const BrandListWidget = () => {
 }
 
 export const config = defineWidgetConfig({
-  zone: "brand.list.before",
+  zone: "brand.list",
 })
 
 export default BrandListWidget
 ```
 
-In this example, the widget is injected into the `brand.list.before` zone, so it's rendered before the main content of the brand list page you added to your plugin.
+In this example, the widget is injected into the `brand.list` zone, so it's rendered in the main section of the brand list page you added to your plugin.
 
-If you don't see `brand.list.before` in the autocompletion of the `zone` property, make sure your `src/admin/tsconfig.json` has the following in its `include` array:
+If you don't see `brand.list` in the autocompletion of the `zone` property, make sure your `src/admin/tsconfig.json` has the following in its `include` array:
 
 ```json title="src/admin/tsconfig.json"
 "include": [
@@ -248,10 +253,10 @@ const BrandWidget = ({
 }
 
 export const config = defineWidgetConfig({
-  zone: "brand.details.before",
+  zone: "brand.details",
 })
 
 export default BrandWidget
 ```
 
-In this example, the `BrandWidget` is injected into the `brand.details.before` zone, which is part of the brand details page you added to your plugin. Since you passed the `brand` object as data to the `LayoutComposer`, developers can access it in the widget through the `data` prop.
+In this example, the `BrandWidget` is injected into the `brand.details` zone, which is part of the brand details page you added to your plugin. Since you passed the `brand` object as data to the `LayoutComposer`, developers can access it in the widget through the `data` prop.

www/apps/book/app/learn/fundamentals/admin/environment-variables/page.mdx

@@ -53,7 +53,7 @@ const ProductWidget = () => {
 }
 
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 
 export default ProductWidget
@@ -189,7 +189,7 @@ const ProductWidget = () => {
 }
 
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 
 export default ProductWidget
@@ -228,7 +228,7 @@ const ProductWidget = () => {
 }
 
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 
 export default ProductWidget

www/apps/book/app/learn/fundamentals/admin/routing/page.mdx

@@ -39,7 +39,7 @@ const ProductWidget = () => {
 
 // The widget's configurations
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 
 export default ProductWidget

www/apps/book/app/learn/fundamentals/admin/tips/page.mdx

@@ -82,7 +82,7 @@ const ProductWidget = () => {
 }
 
 export const config = defineWidgetConfig({
-  zone: "product.list.before",
+  zone: "product.list",
 })
 
 export default ProductWidget
@@ -126,7 +126,7 @@ const ProductWidget = ({
 }
 
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 
 export default ProductWidget

www/apps/book/app/learn/fundamentals/admin/translations/page.mdx

@@ -133,7 +133,7 @@ const ProductWidget = () => {
 }
 
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 
 export default ProductWidget
@@ -231,7 +231,7 @@ const ProductWidget = () => {
 }
 
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 
 export default ProductWidget
@@ -327,7 +327,7 @@ const ProductWidget = () => {
 
 // The widget's configurations
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 
 export default ProductWidget

www/apps/book/app/learn/fundamentals/admin/widgets/page.mdx

@@ -58,13 +58,13 @@ const ProductWidget = () => {
 
 // The widget's configurations
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 
 export default ProductWidget
 ```
 
-In the example above, the widget is injected at the top of a product’s details.
+In the example above, the widget is injected at the end of a product’s details page.
 
 You export the `ProductWidget` component, which displays the heading `Product Widget`. In the widget, you use [Medusa UI](!ui!) to customize the dashboard with the same components used to build it.
 
@@ -87,15 +87,27 @@ To test out the widget, start the Medusa application:
 npm run dev
 ```
 
-Then, open a product’s details page. You’ll find your custom widget at the top of the page.
+Then, open a product’s details page. You’ll find your custom widget at the end of the page.
+
+---
+
+## Widget Placement
+
+Prior to Medusa v2.17.2, widget zones ended with `.before` or `.after` to indicate whether the widget should be placed at the beginning or end of the zone. For example, `product.details.before` would place the widget at the top of the product details page, while `product.details.after` would place it at the bottom.
+
+As of Medusa v2.17.2, the `.before` and `.after` suffixes have been deprecated in favor of [Layout Configurations](!user-guide!/tips/layout-configurations). The login page is the only exception. It isn't part of the layout configurations, so its `login.before` and `login.after` zones still place the widget before or after the login form.
+
+Widgets are now placed at the end of the zone they're injected into. For example, if you inject a widget into the `product.details` zone, it will be placed at the end of the product details page. Then, users can customize the placement of the widget in the Medusa Admin dashboard using [Layout Configurations](!user-guide!/tips/layout-configurations). The widget can be moved to the top of the page or in between core components of the page.
+
+If you're still using the `.before` or `.after` suffixes, you can continue to do so, but it's recommended to migrate to the new system. `.before` and `.after` (aside from the login page) have no effect on the placement of widgets in Medusa v2.17.2 and later, and may be removed in future versions.
 
 ---
 
 ## Props Passed to Widgets on Detail Pages
 
 Widgets that are injected into a detail page receive a `data` prop, which is the main data of the details page.
 
-For example, a widget injected into the `product.details.before` zone receives the product's details in the `data` prop:
+For example, a widget injected into the `product.details` zone receives the product's details in the `data` prop:
 
 export const detailHighlights = [
   ["10", "data", "Receive the data as a prop."],
@@ -128,7 +140,7 @@ const ProductWidget = ({
 
 // The widget's configurations
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 
 export default ProductWidget
@@ -195,7 +207,7 @@ const ProductWidget = ({
 
 // The widget's configurations
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 
 export default ProductWidget

www/apps/book/app/learn/introduction/from-v1-to-v2/page.mdx

@@ -1706,7 +1706,7 @@ const ProductWidget = () => {
 
 // The widget's configurations
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 
 export default ProductWidget
@@ -1808,7 +1808,7 @@ const ProductWidget = () => {
 
 // The widget's configurations
 export const config = defineWidgetConfig({
-  zone: "product.details.before",
+  zone: "product.details",
 })
 
 export default ProductWidget