Make better button docs (#164)

Shopify · Feb 3, 2023 · c8c9aa3 · c8c9aa3
1 parent eb1656f
commit c8c9aa3
Show file tree

Hide file tree

Showing 8 changed files with 74 additions and 124 deletions.
diff --git a/packages/react/docs/generated/generated_docs_data.json b/packages/react/docs/generated/generated_docs_data.json
@@ -28,18 +28,11 @@
       {
         "title": "Props",
         "description": "",
-        "type": "AddToCartButtonProps",
+        "type": "AddToCartButtonPropsForDocs",
         "typeDefinitions": {
-          "AddToCartButtonProps": {
+          "AddToCartButtonPropsForDocs": {
             "filePath": "/AddToCartButton.tsx",
-            "syntaxKind": "TypeAliasDeclaration",
-            "name": "AddToCartButtonProps",
-            "value": "AddToCartButtonPropsBase & BaseButtonProps<AsType>",
-            "description": ""
-          },
-          "AddToCartButtonPropsBase": {
-            "filePath": "/AddToCartButton.tsx",
-            "name": "AddToCartButtonPropsBase",
+            "name": "AddToCartButtonPropsForDocs",
             "description": "",
             "members": [
               {
@@ -81,63 +74,48 @@
                 "value": "string",
                 "description": "The selling plan ID of the subscription variant",
                 "isOptional": true
-              }
-            ],
-            "value": "export interface AddToCartButtonPropsBase {\n  /** An array of cart line attributes that belong to the item being added to the cart. */\n  attributes?: {\n    key: string;\n    value: string;\n  }[];\n  /** The ID of the variant. */\n  variantId?: string | null;\n  /** The item quantity. */\n  quantity?: number;\n  /** The text that is announced by the screen reader when the item is being added to the cart. Used for accessibility purposes only and not displayed on the page. */\n  accessibleAddingToCartLabel?: string;\n  /** The selling plan ID of the subscription variant */\n  sellingPlanId?: string;\n}"
-          },
-          "BaseButtonProps": {
-            "filePath": "/BaseButton.tsx",
-            "syntaxKind": "TypeAliasDeclaration",
-            "name": "BaseButtonProps",
-            "value": "CustomBaseButtonProps<AsType> & Omit<\n      React.ComponentPropsWithoutRef<AsType>,\n      keyof CustomBaseButtonProps<AsType>\n    >",
-            "description": ""
-          },
-          "CustomBaseButtonProps": {
-            "filePath": "/BaseButton.tsx",
-            "name": "CustomBaseButtonProps",
-            "description": "",
-            "members": [
+              },
               {
-                "filePath": "/BaseButton.tsx",
+                "filePath": "/AddToCartButton.tsx",
                 "syntaxKind": "PropertySignature",
                 "name": "as",
                 "value": "AsType",
                 "description": "Provide a React element or component to render as the underlying button. Note: for accessibility compliance, almost always you should use a `button` element, or a component that renders an underlying button.",
                 "isOptional": true
               },
               {
-                "filePath": "/BaseButton.tsx",
+                "filePath": "/AddToCartButton.tsx",
                 "syntaxKind": "PropertySignature",
                 "name": "children",
                 "value": "ReactNode",
                 "description": "Any ReactNode elements."
               },
               {
-                "filePath": "/BaseButton.tsx",
+                "filePath": "/AddToCartButton.tsx",
                 "syntaxKind": "PropertySignature",
                 "name": "onClick",
                 "value": "(event?: MouseEvent<HTMLButtonElement, MouseEvent>) => boolean | void",
                 "description": "Click event handler. Default behaviour triggers unless prevented",
                 "isOptional": true
               },
               {
-                "filePath": "/BaseButton.tsx",
+                "filePath": "/AddToCartButton.tsx",
                 "syntaxKind": "PropertySignature",
                 "name": "defaultOnClick",
                 "value": "(event?: MouseEvent<HTMLButtonElement, MouseEvent>) => boolean | void",
-                "description": "A default onClick behavior",
+                "description": "A default `onClick` behavior",
                 "isOptional": true
               },
               {
-                "filePath": "/BaseButton.tsx",
+                "filePath": "/AddToCartButton.tsx",
                 "syntaxKind": "PropertySignature",
                 "name": "buttonRef",
                 "value": "Ref<HTMLButtonElement>",
-                "description": "A ref to the underlying button",
+                "description": "A `ref` to the underlying button",
                 "isOptional": true
               }
             ],
-            "value": "export interface CustomBaseButtonProps<AsType> {\n  /** Provide a React element or component to render as the underlying button. Note: for accessibility compliance, almost always you should use a `button` element, or a component that renders an underlying button. */\n  as?: AsType;\n  /** Any ReactNode elements. */\n  children: ReactNode;\n  /** Click event handler. Default behaviour triggers unless prevented */\n  onClick?: (\n    event?: React.MouseEvent<HTMLButtonElement, MouseEvent>\n  ) => void | boolean;\n  /** A default onClick behavior */\n  defaultOnClick?: (\n    event?: React.MouseEvent<HTMLButtonElement, MouseEvent>\n  ) => void | boolean;\n  /** A ref to the underlying button */\n  buttonRef?: Ref<HTMLButtonElement>;\n}"
+            "value": "export interface AddToCartButtonPropsForDocs<\n  AsType extends React.ElementType = 'button'\n> extends AddToCartButtonPropsBase,\n    CustomBaseButtonProps<AsType> {}"
           }
         }
       }
@@ -172,18 +150,11 @@
       {
         "title": "Props",
         "description": "",
-        "type": "BuyNowButtonProps",
+        "type": "BuyNowButtonPropsForDocs",
         "typeDefinitions": {
-          "BuyNowButtonProps": {
-            "filePath": "/BuyNowButton.tsx",
-            "syntaxKind": "TypeAliasDeclaration",
-            "name": "BuyNowButtonProps",
-            "value": "BuyNowButtonPropsBase & BaseButtonProps<AsType>",
-            "description": ""
-          },
-          "BuyNowButtonPropsBase": {
+          "BuyNowButtonPropsForDocs": {
             "filePath": "/BuyNowButton.tsx",
-            "name": "BuyNowButtonPropsBase",
+            "name": "BuyNowButtonPropsForDocs",
             "description": "",
             "members": [
               {
@@ -208,63 +179,48 @@
                 "value": "{ key: string; value: string; }[]",
                 "description": "An array of cart line attributes that belong to the item being added to the cart.",
                 "isOptional": true
-              }
-            ],
-            "value": "interface BuyNowButtonPropsBase {\n  /** The item quantity. Defaults to 1. */\n  quantity?: number;\n  /** The ID of the variant. */\n  variantId: string;\n  /** An array of cart line attributes that belong to the item being added to the cart. */\n  attributes?: {\n    key: string;\n    value: string;\n  }[];\n}"
-          },
-          "BaseButtonProps": {
-            "filePath": "/BaseButton.tsx",
-            "syntaxKind": "TypeAliasDeclaration",
-            "name": "BaseButtonProps",
-            "value": "CustomBaseButtonProps<AsType> & Omit<\n      React.ComponentPropsWithoutRef<AsType>,\n      keyof CustomBaseButtonProps<AsType>\n    >",
-            "description": ""
-          },
-          "CustomBaseButtonProps": {
-            "filePath": "/BaseButton.tsx",
-            "name": "CustomBaseButtonProps",
-            "description": "",
-            "members": [
+              },
               {
-                "filePath": "/BaseButton.tsx",
+                "filePath": "/BuyNowButton.tsx",
                 "syntaxKind": "PropertySignature",
                 "name": "as",
                 "value": "AsType",
                 "description": "Provide a React element or component to render as the underlying button. Note: for accessibility compliance, almost always you should use a `button` element, or a component that renders an underlying button.",
                 "isOptional": true
               },
               {
-                "filePath": "/BaseButton.tsx",
+                "filePath": "/BuyNowButton.tsx",
                 "syntaxKind": "PropertySignature",
                 "name": "children",
                 "value": "ReactNode",
                 "description": "Any ReactNode elements."
               },
               {
-                "filePath": "/BaseButton.tsx",
+                "filePath": "/BuyNowButton.tsx",
                 "syntaxKind": "PropertySignature",
                 "name": "onClick",
                 "value": "(event?: MouseEvent<HTMLButtonElement, MouseEvent>) => boolean | void",
                 "description": "Click event handler. Default behaviour triggers unless prevented",
                 "isOptional": true
               },
               {
-                "filePath": "/BaseButton.tsx",
+                "filePath": "/BuyNowButton.tsx",
                 "syntaxKind": "PropertySignature",
                 "name": "defaultOnClick",
                 "value": "(event?: MouseEvent<HTMLButtonElement, MouseEvent>) => boolean | void",
-                "description": "A default onClick behavior",
+                "description": "A default `onClick` behavior",
                 "isOptional": true
               },
               {
-                "filePath": "/BaseButton.tsx",
+                "filePath": "/BuyNowButton.tsx",
                 "syntaxKind": "PropertySignature",
                 "name": "buttonRef",
                 "value": "Ref<HTMLButtonElement>",
-                "description": "A ref to the underlying button",
+                "description": "A `ref` to the underlying button",
                 "isOptional": true
               }
             ],
-            "value": "export interface CustomBaseButtonProps<AsType> {\n  /** Provide a React element or component to render as the underlying button. Note: for accessibility compliance, almost always you should use a `button` element, or a component that renders an underlying button. */\n  as?: AsType;\n  /** Any ReactNode elements. */\n  children: ReactNode;\n  /** Click event handler. Default behaviour triggers unless prevented */\n  onClick?: (\n    event?: React.MouseEvent<HTMLButtonElement, MouseEvent>\n  ) => void | boolean;\n  /** A default onClick behavior */\n  defaultOnClick?: (\n    event?: React.MouseEvent<HTMLButtonElement, MouseEvent>\n  ) => void | boolean;\n  /** A ref to the underlying button */\n  buttonRef?: Ref<HTMLButtonElement>;\n}"
+            "value": "export interface BuyNowButtonPropsForDocs<\n  AsType extends React.ElementType = 'button'\n> extends BuyNowButtonPropsBase,\n    CustomBaseButtonProps<AsType> {}"
           }
         }
       }
@@ -299,84 +255,46 @@
       {
         "title": "Props",
         "description": "",
-        "type": "CartCheckoutButtonProps",
+        "type": "CartCheckoutButtonPropsForDocs",
         "typeDefinitions": {
-          "CartCheckoutButtonProps": {
+          "CartCheckoutButtonPropsForDocs": {
             "filePath": "/CartCheckoutButton.tsx",
-            "syntaxKind": "TypeAliasDeclaration",
-            "name": "CartCheckoutButtonProps",
-            "value": "Omit<BaseButtonProps<'button'>, 'onClick'> & ChildrenProps",
-            "description": ""
-          },
-          "BaseButtonProps": {
-            "filePath": "/BaseButton.tsx",
-            "syntaxKind": "TypeAliasDeclaration",
-            "name": "BaseButtonProps",
-            "value": "CustomBaseButtonProps<AsType> & Omit<\n      React.ComponentPropsWithoutRef<AsType>,\n      keyof CustomBaseButtonProps<AsType>\n    >",
-            "description": ""
-          },
-          "CustomBaseButtonProps": {
-            "filePath": "/BaseButton.tsx",
-            "name": "CustomBaseButtonProps",
+            "name": "CartCheckoutButtonPropsForDocs",
             "description": "",
             "members": [
               {
-                "filePath": "/BaseButton.tsx",
+                "filePath": "/CartCheckoutButton.tsx",
                 "syntaxKind": "PropertySignature",
                 "name": "as",
                 "value": "AsType",
                 "description": "Provide a React element or component to render as the underlying button. Note: for accessibility compliance, almost always you should use a `button` element, or a component that renders an underlying button.",
                 "isOptional": true
               },
               {
-                "filePath": "/BaseButton.tsx",
+                "filePath": "/CartCheckoutButton.tsx",
                 "syntaxKind": "PropertySignature",
                 "name": "children",
                 "value": "ReactNode",
                 "description": "Any ReactNode elements."
               },
               {
-                "filePath": "/BaseButton.tsx",
-                "syntaxKind": "PropertySignature",
-                "name": "onClick",
-                "value": "(event?: MouseEvent<HTMLButtonElement, MouseEvent>) => boolean | void",
-                "description": "Click event handler. Default behaviour triggers unless prevented",
-                "isOptional": true
-              },
-              {
-                "filePath": "/BaseButton.tsx",
+                "filePath": "/CartCheckoutButton.tsx",
                 "syntaxKind": "PropertySignature",
                 "name": "defaultOnClick",
                 "value": "(event?: MouseEvent<HTMLButtonElement, MouseEvent>) => boolean | void",
-                "description": "A default onClick behavior",
+                "description": "A default `onClick` behavior",
                 "isOptional": true
               },
               {
-                "filePath": "/BaseButton.tsx",
+                "filePath": "/CartCheckoutButton.tsx",
                 "syntaxKind": "PropertySignature",
                 "name": "buttonRef",
                 "value": "Ref<HTMLButtonElement>",
-                "description": "A ref to the underlying button",
+                "description": "A `ref` to the underlying button",
                 "isOptional": true
               }
             ],
-            "value": "export interface CustomBaseButtonProps<AsType> {\n  /** Provide a React element or component to render as the underlying button. Note: for accessibility compliance, almost always you should use a `button` element, or a component that renders an underlying button. */\n  as?: AsType;\n  /** Any ReactNode elements. */\n  children: ReactNode;\n  /** Click event handler. Default behaviour triggers unless prevented */\n  onClick?: (\n    event?: React.MouseEvent<HTMLButtonElement, MouseEvent>\n  ) => void | boolean;\n  /** A default onClick behavior */\n  defaultOnClick?: (\n    event?: React.MouseEvent<HTMLButtonElement, MouseEvent>\n  ) => void | boolean;\n  /** A ref to the underlying button */\n  buttonRef?: Ref<HTMLButtonElement>;\n}"
-          },
-          "ChildrenProps": {
-            "filePath": "/CartCheckoutButton.tsx",
-            "syntaxKind": "TypeAliasDeclaration",
-            "name": "ChildrenProps",
-            "value": "{\n  /** A `ReactNode` element. */\n  children: ReactNode;\n}",
-            "description": "",
-            "members": [
-              {
-                "filePath": "/CartCheckoutButton.tsx",
-                "syntaxKind": "PropertySignature",
-                "name": "children",
-                "value": "ReactNode",
-                "description": "A `ReactNode` element."
-              }
-            ]
+            "value": "export interface CartCheckoutButtonPropsForDocs<\n  AsType extends React.ElementType = 'button'\n> extends Omit<CustomBaseButtonProps<AsType>, 'onClick'> {}"
           }
         }
       }

diff --git a/packages/react/src/AddToCartButton.doc.ts b/packages/react/src/AddToCartButton.doc.ts
@@ -28,7 +28,7 @@ const data: ReferenceEntityTemplateSchema = {
   definitions: [
     {
       title: 'Props',
-      type: 'AddToCartButtonProps',
+      type: 'AddToCartButtonPropsForDocs',
       description: '',
     },
   ],

diff --git a/packages/react/src/AddToCartButton.tsx b/packages/react/src/AddToCartButton.tsx
@@ -1,7 +1,12 @@
 import {useCallback, useEffect, useState} from 'react';
 import {useCart} from './CartProvider.js';
 import {useProduct} from './ProductProvider.js';
-import {BaseButton, BaseButtonProps} from './BaseButton.js';
+import {
+  BaseButton,
+  type CustomBaseButtonProps,
+  type BaseButtonProps,
+} from './BaseButton.js';
+import * as React from 'react';
 
 export interface AddToCartButtonPropsBase {
   /** An array of cart line attributes that belong to the item being added to the cart. */
@@ -100,3 +105,9 @@ export function AddToCartButton<AsType extends React.ElementType = 'button'>(
     </>
   );
 }
+
+// This is only for documenation purposes, and it is not used in the code.
+export interface AddToCartButtonPropsForDocs<
+  AsType extends React.ElementType = 'button'
+> extends AddToCartButtonPropsBase,
+    CustomBaseButtonProps<AsType> {}
diff --git a/packages/react/src/BaseButton.tsx b/packages/react/src/BaseButton.tsx
@@ -9,11 +9,11 @@ export interface CustomBaseButtonProps<AsType> {
   onClick?: (
     event?: React.MouseEvent<HTMLButtonElement, MouseEvent>
   ) => void | boolean;
-  /** A default onClick behavior */
+  /** A default `onClick` behavior */
   defaultOnClick?: (
     event?: React.MouseEvent<HTMLButtonElement, MouseEvent>
   ) => void | boolean;
-  /** A ref to the underlying button */
+  /** A `ref` to the underlying button */
   buttonRef?: Ref<HTMLButtonElement>;
 }
 

diff --git a/packages/react/src/BuyNowButton.doc.ts b/packages/react/src/BuyNowButton.doc.ts
@@ -29,7 +29,7 @@ const data: ReferenceEntityTemplateSchema = {
   definitions: [
     {
       title: 'Props',
-      type: 'BuyNowButtonProps',
+      type: 'BuyNowButtonPropsForDocs',
       description: '',
     },
   ],

diff --git a/packages/react/src/BuyNowButton.tsx b/packages/react/src/BuyNowButton.tsx
@@ -1,6 +1,10 @@
 import {useEffect, useState, useCallback} from 'react';
 import {useCart} from './CartProvider.js';
-import {BaseButton, BaseButtonProps} from './BaseButton.js';
+import {
+  BaseButton,
+  type BaseButtonProps,
+  type CustomBaseButtonProps,
+} from './BaseButton.js';
 
 interface BuyNowButtonPropsBase {
   /** The item quantity. Defaults to 1. */
@@ -66,3 +70,9 @@ export function BuyNowButton<AsType extends React.ElementType = 'button'>(
     </BaseButton>
   );
 }
+
+// This is only for documenation purposes, and it is not used in the code.
+export interface BuyNowButtonPropsForDocs<
+  AsType extends React.ElementType = 'button'
+> extends BuyNowButtonPropsBase,
+    CustomBaseButtonProps<AsType> {}
diff --git a/packages/react/src/CartCheckoutButton.doc.ts b/packages/react/src/CartCheckoutButton.doc.ts
@@ -29,7 +29,7 @@ const data: ReferenceEntityTemplateSchema = {
   definitions: [
     {
       title: 'Props',
-      type: 'CartCheckoutButtonProps',
+      type: 'CartCheckoutButtonPropsForDocs',
       description: '',
     },
   ],

diff --git a/packages/react/src/CartCheckoutButton.tsx b/packages/react/src/CartCheckoutButton.tsx
@@ -1,6 +1,10 @@
 import {ReactNode, useEffect, useState} from 'react';
 import {useCart} from './CartProvider.js';
-import {BaseButton, BaseButtonProps} from './BaseButton.js';
+import {
+  BaseButton,
+  type BaseButtonProps,
+  type CustomBaseButtonProps,
+} from './BaseButton.js';
 
 type ChildrenProps = {
   /** A `ReactNode` element. */
@@ -34,3 +38,10 @@ export function CartCheckoutButton(props: CartCheckoutButtonProps) {
     </BaseButton>
   );
 }
+
+// This is only for documenation purposes, and it is not used in the code.
+// we ignore this issue because it makes the documentation look better than the equivalent `type` that it wants us to convert to
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface CartCheckoutButtonPropsForDocs<
+  AsType extends React.ElementType = 'button'
+> extends Omit<CustomBaseButtonProps<AsType>, 'onClick'> {}