Tweak docs (#161)

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

Hide file tree

Showing 15 changed files with 411 additions and 345 deletions.
diff --git a/.changeset/twenty-months-swim.md b/.changeset/twenty-months-swim.md
@@ -0,0 +1,5 @@
+---
+'@shopify/hydrogen-react': patch
+---
+
+Update docs
diff --git a/packages/react/docs/generated/generated_docs_data.json b/packages/react/docs/generated/generated_docs_data.json
diff --git a/packages/react/src/analytics-constants.doc.ts b/packages/react/src/analytics-constants.doc.ts
diff --git a/packages/react/src/analytics-types.ts b/packages/react/src/analytics-types.ts
@@ -11,37 +11,86 @@ import {
 import {SHOPIFY_Y, SHOPIFY_S} from './cart-constants.js';
 
 export type ClientBrowserParameters = {
-  /** Shopify unique user token: Value of `_shopify_y` cookie. Use `getClientBrowserParameters()` to collect this value. */
+  /**
+   * Shopify unique user token: Value of `_shopify_y` cookie.
+   *
+   * Use `getClientBrowserParameters()` to collect this value.
+   **/
   uniqueToken: string;
-  /** Shopify session token: Value of `_shopify_s` cookie. Use `getClientBrowserParameters()` to collect this value. */
+  /**
+   * Shopify session token: Value of `_shopify_s` cookie.
+   *
+   * Use `getClientBrowserParameters()` to collect this value.
+   **/
   visitToken: string;
-  /** `window.location.href`. Use `getClientBrowserParameters()` to collect this value. */
+  /**
+   * Value of `window.location.href`.
+   *
+   * Use `getClientBrowserParameters()` to collect this value.
+   **/
   url: string;
-  /** `window.location.pathname`. Use `getClientBrowserParameters()` to collect this value. */
+  /**
+   * Value of `window.location.pathname`.
+   *
+   * Use `getClientBrowserParameters()` to collect this value.
+   **/
   path: string;
-  /** `window.location.search`. Use `getClientBrowserParameters()` to collect this value. */
+  /**
+   * Value of `window.location.search`.
+   *
+   * Use `getClientBrowserParameters()` to collect this value.
+   **/
   search: string;
-  /** `window.location.referrer`. Use `getClientBrowserParameters()` to collect this value. */
+  /**
+   * Value of `window.location.referrer`.
+   *
+   * Use `getClientBrowserParameters()` to collect this value.
+   **/
   referrer: string;
-  /** `document.title`. Use `getClientBrowserParameters()` to collect this value. */
+  /**
+   * Value of `document.title`.
+   *
+   * Use `getClientBrowserParameters()` to collect this value.
+   **/
   title: string;
-  /** `navigator.userAgent`. Use `getClientBrowserParameters()` to collect this value. */
+  /**
+   * Value of `navigator.userAgent`.
+   *
+   * Use `getClientBrowserParameters()` to collect this value.
+   **/
   userAgent: string;
-  /** Navigation type: 'navigate' | 'reload' | 'back_forward' | 'prerender' | 'unknown <number>'. Use `getClientBrowserParameters()` to collect this value. */
+  /**
+   * Navigation type: `'navigate' | 'reload' | 'back_forward' | 'prerender' | 'unknown'`.
+   *
+   * Use `getClientBrowserParameters()` to collect this value.
+   **/
   navigationType: string;
-  /** Navigation api: 'PerformanceNavigationTiming' | 'performance.navigation'. Use `getClientBrowserParameters()` to collect this value. */
+  /**
+   * Navigation api: `'PerformanceNavigationTiming' | 'performance.navigation'`.
+   *
+   * Use `getClientBrowserParameters()` to collect this value.
+   **/
   navigationApi: string;
 };
 
 export type ShopifyAnalyticsProduct = {
+  /** Product id in the form of `gid://shopify/Product/<id>`. */
   productGid: Product['id'];
+  /** Variant id in the form of `gid://shopify/ProductVariant/<id>`. */
   variantGid?: ProductVariant['id'];
+  /** Product name. */
   name: Product['title'];
+  /** Variant name. */
   variantName?: ProductVariant['title'];
+  /** Product brand or vendor. */
   brand: Product['vendor'];
+  /** Product category or type. */
   category?: Product['productType'];
+  /** Product price. */
   price: ProductVariant['price']['amount'];
+  /** Product sku. */
   sku?: ProductVariant['sku'];
+  /** Quantity of the product in this event. */
   quantity?: number;
 };
 
@@ -62,7 +111,7 @@ type ShopifyAnalyticsBase = {
   customerId?: string;
   /** Total value of products. */
   totalValue?: number;
-  /** Shopify products. */
+  /** Product list. */
   products?: ShopifyAnalyticsProduct[];
 };
 

diff --git a/packages/react/src/analytics.doc.ts b/packages/react/src/analytics.doc.ts
@@ -25,7 +25,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   description: 'Sends analytics to Shopify.',
-  type: 'gear',
+  type: 'utility',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {
@@ -51,6 +51,22 @@ const data: ReferenceEntityTemplateSchema = {
       description:
         'If `event.payload.hasUserConsent` is false, no analytics event will happen.',
     },
+    {
+      title: 'AnalyticsEventName',
+      type: 'AnalyticsEventName',
+      description: 'Analytics event names accepted by Shopify analytics.',
+    },
+    {
+      title: 'AnalyticsPageType',
+      type: 'AnalyticsPageType',
+      description: 'Analytics page type values accepted by Shopify analytics.',
+    },
+    {
+      title: 'ShopifySalesChannel',
+      type: 'ShopifySalesChannel',
+      description:
+        'Analytics sales channel values accepted by Shopify analytics.',
+    },
   ],
 };
 

diff --git a/packages/react/src/codegen.helpers.doc.ts b/packages/react/src/codegen.helpers.doc.ts
@@ -19,7 +19,7 @@ const data: ReferenceEntityTemplateSchema = {
   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.\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: 'gear',
+  type: 'utility',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {

diff --git a/packages/react/src/flatten-connection.doc.ts b/packages/react/src/flatten-connection.doc.ts
@@ -8,7 +8,7 @@ const data: ReferenceEntityTemplateSchema = {
   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\`.\n\nIf \`connection\` is null or undefined, will return an empty array instead in production. In development, an error will be thrown.
   `,
-  type: 'gear',
+  type: 'utility',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {

diff --git a/packages/react/src/get-client-browser-parameters.doc.ts b/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: 'gear',
+  type: 'utility',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {

diff --git a/packages/react/src/get-shopify-cookies.doc.ts b/packages/react/src/get-shopify-cookies.doc.ts
@@ -13,7 +13,7 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   description: 'Parses cookie string and returns Shopify cookies.',
-  type: 'gear',
+  type: 'utility',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {
@@ -39,6 +39,11 @@ const data: ReferenceEntityTemplateSchema = {
       description:
         "If the Shopify cookies doesn't exist, this method will return empty string for each missing cookie.",
     },
+    {
+      title: 'ShopifyCookies',
+      type: 'ShopifyCookies',
+      description: 'Shopify cookies names',
+    },
   ],
 };
 

diff --git a/packages/react/src/storefront-api-types.doc.ts b/packages/react/src/storefront-api-types.doc.ts
@@ -19,7 +19,7 @@ const data: ReferenceEntityTemplateSchema = {
   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.\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: 'gear',
+  type: 'utility',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {

diff --git a/packages/react/src/storefront-client.doc.ts b/packages/react/src/storefront-client.doc.ts
@@ -14,7 +14,7 @@ const data: ReferenceEntityTemplateSchema = {
   description: `
     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',
+  type: 'utility',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {

diff --git a/packages/react/src/storefront.schema.json.doc.ts b/packages/react/src/storefront.schema.json.doc.ts
@@ -19,7 +19,7 @@ const data: ReferenceEntityTemplateSchema = {
   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.\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: 'gear',
+  type: 'utility',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {

diff --git a/packages/react/src/useShopifyCookies.doc.ts b/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: 'gear',
+  type: 'utility',
   defaultExample: {
     description: 'I am the default example',
     codeblock: {
@@ -49,7 +49,8 @@ const data: ReferenceEntityTemplateSchema = {
     {
       title: 'useShopifyCookies',
       type: 'UseShopifyCookiesGeneratedType',
-      description: '',
+      description:
+        'Manages Shopify cookies. If `hasUserConsent` option is false, Shopify cookies will be removed.',
     },
   ],
 };

diff --git a/packages/react/src/useShopifyCookies.example.jsx b/packages/react/src/useShopifyCookies.example.jsx
@@ -2,7 +2,7 @@ import * as React from 'react';
 import {useShopifyCookies} from '@shopify/hydrogen-react';
 
 export default function App({Component, pageProps}) {
-  useShopifyCookies();
+  useShopifyCookies({hasUserConsent: false});
 
   return <Component {...pageProps} />;
 }
diff --git a/packages/react/src/useShopifyCookies.example.tsx b/packages/react/src/useShopifyCookies.example.tsx
@@ -2,7 +2,7 @@ import * as React from 'react';
 import {useShopifyCookies} from '@shopify/hydrogen-react';
 
 export default function App({Component, pageProps}) {
-  useShopifyCookies();
+  useShopifyCookies({hasUserConsent: false});
 
   return <Component {...pageProps} />;
 }