Cleanup some docs and how they're presented (#155)

packages/react/src/AddToCartButton.doc.ts

@@ -5,8 +5,7 @@ const data: ReferenceEntityTemplateSchema = {
   category: 'components',
   isVisualComponent: false,
   related: [],
-  description: `The \`AddToCartButton\` component renders a button that adds an item to the cart when pressed.
-    It must be a descendent of the \`CartProvider\` component.`,
+  description: `The \`AddToCartButton\` component renders a button that adds an item to the cart when pressed.\n\nIt must be a descendent of the \`CartProvider\` component.`,
   type: 'component',
   defaultExample: {
     description: 'I am the default example',

packages/react/src/BuyNowButton.doc.ts

@@ -5,8 +5,7 @@ const data: ReferenceEntityTemplateSchema = {
   category: 'components',
   isVisualComponent: false,
   related: [],
-  description: `The \`BuyNowButton\` component renders a button that adds an item to the cart and redirects the customer to checkout.
-    Must be a child of a \`CartProvider\` component.
+  description: `The \`BuyNowButton\` component renders a button that adds an item to the cart and redirects the customer to checkout.\n\nMust be a child of a \`CartProvider\` component.
   `,
   type: 'component',
   defaultExample: {

packages/react/src/CartCheckoutButton.doc.ts

@@ -5,8 +5,7 @@ const data: ReferenceEntityTemplateSchema = {
   category: 'components',
   isVisualComponent: false,
   related: [],
-  description: `The \`CartCheckoutButton\` component renders a button that redirects to the checkout URL for the cart.
-    Must be a descendent of a \`CartProvider\` component.
+  description: `The \`CartCheckoutButton\` component renders a button that redirects to the checkout URL for the cart.\n\nMust be a descendent of a \`CartProvider\` component.
   `,
   type: 'component',
   defaultExample: {

packages/react/src/CartCost.doc.ts

@@ -6,9 +6,7 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   related: [],
   description: `
-    The \`CartCost\` component renders a \`Money\` component with the cost associated with the \`amountType\` prop. 
-    If no \`amountType\` prop is specified, then it defaults to \`totalAmount\`.
-    Depends on \`useCart()\` and must be a child of \`<CartProvider/>\`
+    The \`CartCost\` component renders a \`Money\` component with the cost associated with the \`amountType\` prop.\n\nIf no \`amountType\` prop is specified, then it defaults to \`totalAmount\`.\n\nDepends on \`useCart()\` and must be a child of \`<CartProvider/>\`
   `,
   type: 'component',
   defaultExample: {

packages/react/src/CartLineProvider.tsx

@@ -1,12 +1,12 @@
 import {useContext, createContext, type ReactNode} from 'react';
-import {CartLine} from './storefront-api-types.js';
+import type {CartLine} from './storefront-api-types.js';
 
 export const CartLineContext = createContext<CartLine | null>(null);
 
 /**
  * The `useCartLine` hook provides access to the cart line object. It must be a descendent of a `CartProvider` component.
  */
-export function useCartLine() {
+export function useCartLine(): CartLine {
   const context = useContext(CartLineContext);
 
   if (context == null) {

packages/react/src/CartProvider.doc.ts

@@ -12,12 +12,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   description: `
-    The \`CartProvider\` component synchronizes the state of the Storefront API Cart and a customer's cart,
-    and allows you to more easily manipulate the cart by adding, removing, and updating it.
-    It could be placed at the root of your app so that your whole app is able to use the \`useCart()\` hook anywhere.
-
-    There are props that trigger when a call to the Storefront API is made, such as \`onLineAdd={}\` when a line is added to the cart.
-    There are also props that trigger when a call to the Storefront API is completed, such as \`onLineAddComplete={}\` when the fetch request for adding a line to the cart completes.
+    The \`CartProvider\` component synchronizes the state of the Storefront API Cart and a customer's cart, and allows you to more easily manipulate the cart by adding, removing, and updating it. It could be placed at the root of your app so that your whole app is able to use the \`useCart()\` hook anywhere.\n\nThere are props that trigger when a call to the Storefront API is made, such as \`onLineAdd={}\` when a line is added to the cart. There are also props that trigger when a call to the Storefront API is completed, such as \`onLineAddComplete={}\` when the fetch request for adding a line to the cart completes.
   `,
   type: 'component',
   defaultExample: {

packages/react/src/CartProvider.tsx

@@ -35,7 +35,7 @@ export const CartContext = createContext<CartWithActions | null>(null);
 /**
  * The `useCart` hook provides access to the cart object. It must be a descendent of a `CartProvider` component.
  */
-export function useCart() {
+export function useCart(): CartWithActions {
   const context = useContext(CartContext);
 
   if (!context) {

packages/react/src/ShopPayButton.doc.ts

@@ -5,9 +5,7 @@ const data: ReferenceEntityTemplateSchema = {
   category: 'components',
   isVisualComponent: false,
   related: [],
-  description: `The \`ShopPayButton\` component renders a button that redirects to the Shop Pay checkout.
-    It renders a [\`<shop-pay-button>\`](https://shopify.dev/custom-storefronts/tools/web-components) custom element, for which it will lazy-load the source code automatically.
-    It relies on the \`<ShopProvider>\` context provider.`,
+  description: `The \`ShopPayButton\` component renders a button that redirects to the Shop Pay checkout. It renders a [\`<shop-pay-button>\`](https://shopify.dev/custom-storefronts/tools/web-components) custom element, for which it will lazy-load the source code automatically. It relies on the \`<ShopProvider>\` context provider.`,
   type: 'component',
   defaultExample: {
     description: 'I am the default example',

packages/react/src/analytics-constants.doc.ts

@@ -6,7 +6,7 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   related: [],
   description: "A list of constants used by Shopify's analytics system.",
-  type: 'utility',
+  type: 'gear',
   definitions: [
     {
       title: 'AnalyticsEventName',

packages/react/src/analytics.doc.ts

@@ -25,7 +25,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   description: 'Sends analytics to Shopify.',
-  type: 'utility',
+  type: 'gear',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {

packages/react/src/codegen.helpers.doc.ts

@@ -7,24 +7,19 @@ const data: ReferenceEntityTemplateSchema = {
   related: [
     {
       name: 'storefront.schema.json',
-      type: 'utility',
+      type: 'gear',
       url: '/api/react-storefront-kit/utilities/storefront.schema.json',
     },
     {
       name: 'Storefront API Types',
-      type: 'utility',
+      type: 'gear',
       url: '/api/react-storefront-kit/utilities/storefrontapitypes',
     },
   ],
   description: `
-    Meant to be used with GraphQL CodeGen to type the Storefront API's custom scalars correctly when using TypeScript.
-    By default, GraphQL CodeGen uses \`any\` for custom scalars; by using these definitions, GraphQL Codegen will generate the correct types for the Storefront API's custom scalars.
-
-    See more about [GraphQL CodeGen](https://graphql-code-generator.com/) and [custom scalars for TypeScript](https://the-guild.dev/graphql/codegen/plugins/typescript/typescript#scalars).
-
-    Note that \`@shopify/hydrogen-react\` has already generated types for the Storefront API, so you may not need to setup GraphQL Codegen on your own.
+    Meant to be used with GraphQL CodeGen to type the Storefront API's custom scalars correctly when using TypeScript.By default, GraphQL CodeGen uses \`any\` for custom scalars; by using these definitions, GraphQL Codegen will generate the correct types for the Storefront API's custom scalars.\n\nSee more about [GraphQL CodeGen](https://graphql-code-generator.com/) and [custom scalars for TypeScript](https://the-guild.dev/graphql/codegen/plugins/typescript/typescript#scalars).\n\nNote that \`@shopify/hydrogen-react\` has already generated types for the Storefront API, so you may not need to setup GraphQL Codegen on your own.
   `,
-  type: 'utility',
+  type: 'gear',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {
@@ -35,7 +30,7 @@ const data: ReferenceEntityTemplateSchema = {
           language: 'js',
         },
       ],
-      title: 'Example code',
+      title: 'codegen.ts',
     },
   },
   definitions: [],

packages/react/src/flatten-connection.doc.ts

@@ -6,12 +6,9 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   related: [],
   description: `
-    The \`flattenConnection\` utility transforms a connection object from the Storefront API (for example, [Product-related connections](https://shopify.dev/api/storefront/reference/products/product)) into a flat array of nodes.
-    The utility works with either \`nodes\` or \`edges.node\`.
-    
-    If \`connection\` is null or undefined, will return an empty array instead in production. In development, an error will be thrown.
+    The \`flattenConnection\` utility transforms a connection object from the Storefront API (for example, [Product-related connections](https://shopify.dev/api/storefront/reference/products/product)) into a flat array of nodes. The utility works with either \`nodes\` or \`edges.node\`.\n\nIf \`connection\` is null or undefined, will return an empty array instead in production. In development, an error will be thrown.
   `,
-  type: 'utility',
+  type: 'gear',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {

packages/react/src/get-client-browser-parameters.doc.ts

@@ -19,7 +19,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   description: 'Gathers client browser values commonly used for analytics',
-  type: 'utility',
+  type: 'gear',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {

packages/react/src/get-shopify-cookies.doc.ts

@@ -13,7 +13,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   description: 'Parses cookie string and returns Shopify cookies.',
-  type: 'utility',
+  type: 'gear',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {

packages/react/src/parse-metafield.doc.ts

@@ -6,11 +6,9 @@ const data: ReferenceEntityTemplateSchema = {
   isVisualComponent: false,
   related: [],
   description: `
-    A function that uses \`metafield.type\` to parse the Metafield's \`value\` or \`reference\` or \`references\` (depending on the \`metafield.type\`) and places the result in \`metafield.parsedValue\`
-  
-    TypeScript developers can use the type \`ParsedMetafields\` from this package to get the returned object's type correct.
+    A function that uses \`metafield.type\` to parse the Metafield's \`value\` or \`reference\` or \`references\` (depending on the \`metafield.type\`) and places the result in \`metafield.parsedValue\`.\n\nTypeScript developers can use the type \`ParsedMetafields\` from this package to get the returned object's type correct.
   `,
-  type: 'utility',
+  type: 'gear',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {

packages/react/src/storefront-api-types.doc.ts

@@ -7,21 +7,19 @@ const data: ReferenceEntityTemplateSchema = {
   related: [
     {
       name: 'storefrontApiCustomScalars',
-      type: 'utility',
+      type: 'gear',
       url: '/api/react-storefront-kit/utilities/storefrontApiCustomScalars',
     },
     {
       name: 'storefront.schema.json',
-      type: 'utility',
+      type: 'gear',
       url: '/api/react-storefront-kit/utilities/storefront.schema.json',
     },
   ],
   description: `
-    If you are using TypeScript, Hydrogen React ships with pre-generated TypeScript types that match the Storefront API's GraphQL schema. These types can be used when you need to manually create an object that matches a Storefront API object's shape.
-
-    These types also work really well with the new [\`satisfies\` operator](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator) introduced in TypeScript 4.9, though you don't need to use \`satisfies\` to use these types.
+    If you are using TypeScript, Hydrogen React ships with pre-generated TypeScript types that match the Storefront API's GraphQL schema. These types can be used when you need to manually create an object that matches a Storefront API object's shape.\n\nThese types also work really well with the new [\`satisfies\` operator](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator) introduced in TypeScript 4.9, though you don't need to use \`satisfies\` to use these types.
   `,
-  type: 'utility',
+  type: 'gear',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {

packages/react/src/storefront-client.doc.ts

@@ -12,9 +12,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   description: `
-    The \`createStorefrontClient()\` function creates helpers that enable you to quickly query the Shopify Storefront API.
-  
-    When used on the server, it is recommended to use the \`privateStorefrontToken\` prop. When used on the client, it is recommended to use the \`publicStorefrontToken\` prop or consider using \`<ShopifyProvider/>\` instead.
+    The \`createStorefrontClient()\` function creates helpers that enable you to quickly query the Shopify Storefront API.\n\nWhen used on the server, it is recommended to use the \`privateStorefrontToken\` prop. When used on the client, it is recommended to use the \`publicStorefrontToken\` prop or consider using \`<ShopifyProvider/>\` instead.
   `,
   type: 'gear',
   defaultExample: {

packages/react/src/graphqlrc.doc.ts → packages/react/src/storefront.schema.json.doc.ts

@@ -1,29 +1,25 @@
 import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
 
 const data: ReferenceEntityTemplateSchema = {
-  name: 'storefront.schema.json',
+  name: 'Storefront Schema',
   category: 'utilities',
   isVisualComponent: false,
   related: [
     {
       name: 'storefrontApiCustomScalars',
-      type: 'utility',
+      type: 'gear',
       url: '/api/react-storefront-kit/utilities/storefrontApiCustomScalars',
     },
     {
       name: 'Storefront API Types',
-      type: 'utility',
+      type: 'gear',
       url: '/api/react-storefront-kit/utilities/storefrontapitypes',
     },
   ],
   description: `
-    Hydrogen React ships with a pre-generated GraphQL schema for the Storefront API, which can integrate with your IDE and other GraphQL tooling (such as a [GraphQL config file](https://www.graphql-config.com/docs/user/user-usage)) to provide autocompletion and validation for your Storefront API GraphQL queries.
-
-    This schema is generated using the Storefront API's introspection query, and is available at \`@shopify/hydrogen-react/storefront.schema.json\`.
-
-    To get these features working in your IDE, you may need to install an extension. For example, in VSCode you can install this [GraphQL extension](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql).
+    Hydrogen React ships with a pre-generated GraphQL schema for the Storefront API, which can integrate with your IDE and other GraphQL tooling (such as a [GraphQL config file](https://www.graphql-config.com/docs/user/user-usage)) to provide autocompletion and validation for your Storefront API GraphQL queries.\n\nThis schema is generated using the Storefront API's introspection query, and is available at \`@shopify/hydrogen-react/storefront.schema.json\`.\n\nTo get these features working in your IDE, you may need to install an extension. For example, in VSCode you can install this [GraphQL extension](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql).
   `,
-  type: 'utility',
+  type: 'gear',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {
@@ -34,7 +30,7 @@ const data: ReferenceEntityTemplateSchema = {
           language: 'yml',
         },
       ],
-      title: 'Example code',
+      title: '.graphqlrc.yml',
     },
   },
   definitions: [],

packages/react/src/useMoney.doc.ts

@@ -15,7 +15,7 @@ const data: ReferenceEntityTemplateSchema = {
     The \`useMoney\` hook takes a [MoneyV2 object](https://shopify.dev/api/storefront/reference/common-objects/moneyv2) and returns a
     default-formatted string of the amount with the correct currency indicator, along with some of the parts provided by
     [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).
-    Uses \`locale\` from \`ShopifyProvider\`
+    Uses \`locale\` from \`<ShopifyProvider/>\`.
   `,
   type: 'hook',
   defaultExample: {

packages/react/src/useShopifyCookies.doc.ts

@@ -26,7 +26,7 @@ const data: ReferenceEntityTemplateSchema = {
   ],
   description:
     'Sets Shopify user and session cookies and refreshes the expiry time.',
-  type: 'utility',
+  type: 'gear',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {