From 8e6f4d3e304331ad9cc49837ed3ce637f41d5081 Mon Sep 17 00:00:00 2001
From: Alessandro Dal Grande <alessandro.dalgrande@shopify.com>
Date: Wed, 20 Mar 2024 23:12:21 +0000
Subject: [PATCH 1/2] Redefine types for validations in a way that works for
 doc generation

---
 .../api/checkout-rules/launch-options.ts      | 48 ++++++++++++-------
 .../admin/api/checkout-rules/metafields.ts    | 15 ++----
 .../checkout-rules/validation-settings.doc.ts | 25 ++++++++++
 .../api/checkout-rules/validation-settings.ts |  3 ++
 4 files changed, 62 insertions(+), 29 deletions(-)
 create mode 100644 packages/ui-extensions/src/surfaces/admin/api/checkout-rules/validation-settings.doc.ts

diff --git a/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/launch-options.ts b/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/launch-options.ts
index 6d973585d..13ceb98fb 100644
--- a/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/launch-options.ts
+++ b/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/launch-options.ts
@@ -1,20 +1,34 @@
-import {Metafield} from './metafields';
+interface Metafield {
+  description?: string;
+  id: string;
+  namespace: string;
+  key: string;
+  value: string;
+  type: string;
+}
+
+interface Validation {
+  /**
+   * the validation's gid when active in a shop
+   */
+  id: string;
+  /**
+   * the metafields owned by the validation
+   */
+  metafields: Metafield[];
+}
+
+interface ShopifyFunction {
+  /**
+   * the validation function's unique identifier
+   */
+  id: string;
+}
 
+/**
+ * The object that exposes the validation with its settings.
+ */
 export interface ValidationData {
-  validation?: {
-    /**
-     * the validation's gid when active in a shop
-     */
-    id: string;
-    /**
-     * the metafields owned by the validation
-     */
-    metafields: Metafield[];
-  };
-  shopifyFunction: {
-    /**
-     * the validation function's unique identifier
-     */
-    id: string;
-  };
+  validation?: Validation;
+  shopifyFunction: ShopifyFunction;
 }
diff --git a/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/metafields.ts b/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/metafields.ts
index f46eddcad..28899b66c 100644
--- a/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/metafields.ts
+++ b/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/metafields.ts
@@ -45,15 +45,6 @@ const supportedDefinitionTypes = [
 
 export type SupportedDefinitionType = typeof supportedDefinitionTypes[number];
 
-export interface Metafield {
-  description?: string;
-  id: string;
-  namespace: string;
-  key: string;
-  value: string;
-  type: string;
-}
-
 interface MetafieldUpdateChange {
   type: 'updateMetafield';
   key: string;
@@ -80,6 +71,6 @@ type MetafieldChangeResult =
   | MetafieldChangeSuccess
   | MetafieldChangeResultError;
 
-export interface ApplyMetafieldChange {
-  (change: MetafieldChange): Promise<MetafieldChangeResult>;
-}
+export type ApplyMetafieldChange = (
+  change: MetafieldChange,
+) => Promise<MetafieldChangeResult>;
diff --git a/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/validation-settings.doc.ts b/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/validation-settings.doc.ts
new file mode 100644
index 000000000..27fa78da6
--- /dev/null
+++ b/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/validation-settings.doc.ts
@@ -0,0 +1,25 @@
+import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Validation Settings API',
+  description:
+    'This API is available Validation Settings extensions. Refer to the [tutorial](/docs/apps/checkout/validation/create-complex-validation-rules) for more information. Note that the [`FunctionSettings`](/docs/api/admin-extensions/components/forms/functionsettings) component is required to build Validation Settings extensions.',
+  isVisualComponent: false,
+  type: 'API',
+  definitions: [
+    {
+      title: 'applyMetafieldChange',
+      description: 'Applies a change to the validation settings.',
+      type: 'ApplyMetafieldChange',
+    },
+    {
+      title: 'data',
+      description: 'The object that exposes the validation with its settings.',
+      type: 'ValidationData',
+    },
+  ],
+  category: 'API',
+  related: [],
+};
+
+export default data;
diff --git a/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/validation-settings.ts b/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/validation-settings.ts
index c7033bcb1..112c51c42 100644
--- a/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/validation-settings.ts
+++ b/packages/ui-extensions/src/surfaces/admin/api/checkout-rules/validation-settings.ts
@@ -7,6 +7,9 @@ import {ValidationData} from './launch-options';
 export interface ValidationSettingsApi<
   ExtensionTarget extends AnyExtensionTarget,
 > extends StandardApi<ExtensionTarget> {
+  /**
+   * Applies a change to the validation settings.
+   */
   applyMetafieldChange: ApplyMetafieldChange;
   data: ValidationData;
 }

From e5b828867ba9f0aa41e74e9439ec47517d463dc7 Mon Sep 17 00:00:00 2001
From: Alessandro Dal Grande <alessandro.dalgrande@shopify.com>
Date: Fri, 22 Mar 2024 18:21:33 +0000
Subject: [PATCH 2/2] Add changelog entry

---
 .changeset/little-seals-punch.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/little-seals-punch.md

diff --git a/.changeset/little-seals-punch.md b/.changeset/little-seals-punch.md
new file mode 100644
index 000000000..8683910e9
--- /dev/null
+++ b/.changeset/little-seals-punch.md
@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': patch
+---
+
+Redefine types for validations in a way that works for doc generation