Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
  • Loading branch information
wizardlyhel committed Dec 4, 2024
1 parent 6e23e6d commit d463bae
Show file tree
Hide file tree
Showing 12 changed files with 799 additions and 287 deletions.
104 changes: 104 additions & 0 deletions packages/hydrogen-react/docs/generated/generated_docs_data.json
Original file line number Diff line number Diff line change
Expand Up @@ -6465,6 +6465,110 @@
}
]
},
{
"name": "getProductOptions",
"category": "utilities",
"isVisualComponent": false,
"related": [
{
"name": "mapSelectedProductOptionToObject",
"type": "gear",
"url": "/api/hydrogen-react/utilities/mapselectedproductoptiontoobject"
},
{
"name": "getAdjacentAndFirstAvailableVariants",
"type": "gear",
"url": "/api/hydrogen-react/utilities/getadjacentandfirstavailablevariants"
}
],
"description": "Returns a product options array with its relevant information about the variant. This function supports combined listing products and products with 2000 variants limit.",
"type": "utility",
"defaultExample": {
"description": "I am the default example",
"codeblock": {
"tabs": [
{
"title": "JavaScript",
"code": "import React from 'react';\nimport {getProductOptions} from '@shopify/hydrogen-react';\n\n// Make sure you are querying for the following fields:\n// - product.handle\n// - product.encodedVariantExistence\n// - product.encodedVariantAvailability\n// - product.options.name\n// - product.options.optionValues.name\n// - product.options.optionValues.firstSelectableVariant\n// - product.selectedOrFirstAvailableVariant\n// - product.adjacentVariants\n//\n// For any fields that are ProductVariant type, make sure to query for:\n// - variant.product.handle\n// - variant.selectedOptions.name\n// - variant.selectedOptions.value\n\nexport default function ProductForm() {\n const product = {\n /* Result from querying the SFAPI for a product */\n };\n\n const productOptions = getProductOptions(product);\n\n return (\n <>\n {productOptions.map((option) => (\n <div key={option.name}>\n <h5>{option.name}</h5>\n <div>\n {option.optionValues.map((value) => {\n const {\n name,\n handle,\n variantUriQuery,\n selected,\n available,\n exists,\n isDifferentProduct,\n swatch,\n } = value;\n\n if (isDifferentProduct) {\n // SEO - When the variant is a\n // combined listing child product\n // that leads to a different url,\n // we need to render it\n // as an anchor tag\n return (\n <a\n key={option.name + name}\n href={`/products/${handle}?${variantUriQuery}`}\n style={{\n border: selected\n ? '1px solid black'\n : '1px solid transparent',\n opacity: available ? 1 : 0.3,\n }}\n >\n <ProductOptionSwatch swatch={swatch} name={name} />\n </a>\n );\n } else {\n // SEO - When the variant is an\n // update to the search param,\n // render it as a button with\n // javascript navigating to\n // the variant so that SEO bots\n // do not index these as\n // duplicated links\n return (\n <button\n type=\"button\"\n key={option.name + name}\n style={{\n border: selected\n ? '1px solid black'\n : '1px solid transparent',\n opacity: available ? 1 : 0.3,\n }}\n disabled={!exists}\n onClick={() => {\n if (!selected) {\n // Navigate to `?${variantUriQuery}`\n }\n }}\n >\n <ProductOptionSwatch swatch={swatch} name={name} />\n </button>\n );\n }\n })}\n </div>\n <br />\n </div>\n ))}\n </>\n );\n}\n\nfunction ProductOptionSwatch({swatch, name}) {\n const image = swatch?.image?.previewImage?.url;\n const color = swatch?.color;\n\n if (!image && !color) return name;\n\n return (\n <div\n aria-label={name}\n className=\"product-option-label-swatch\"\n style={{\n backgroundColor: color || 'transparent',\n }}\n >\n {!!image && <img src={image} alt={name} />}\n </div>\n );\n}\n",
"language": "jsx"
},
{
"title": "TypeScript",
"code": "import React from 'react';\nimport {\n getProductOptions,\n type MappedProductOptions,\n} from '@shopify/hydrogen-react';\nimport type {\n ProductOptionValueSwatch,\n Maybe,\n} from '@shopify/hydrogen-react/storefront-api-types';\n\n// Make sure you are querying for the following fields:\n// - product.handle\n// - product.encodedVariantExistence\n// - product.encodedVariantAvailability\n// - product.options.name\n// - product.options.optionValues.name\n// - product.options.optionValues.firstSelectableVariant\n// - product.selectedOrFirstAvailableVariant\n// - product.adjacentVariants\n//\n// For any fields that are ProductVariant type, make sure to query for:\n// - variant.product.handle\n// - variant.selectedOptions.name\n// - variant.selectedOptions.value\n\nexport default function ProductForm() {\n const product = {\n /* Result from querying the SFAPI for a product */\n };\n\n const productOptions: MappedProductOptions[] = getProductOptions(product);\n\n return (\n <>\n {productOptions.map((option) => (\n <div key={option.name}>\n <h5>{option.name}</h5>\n <div>\n {option.optionValues.map((value) => {\n const {\n name,\n handle,\n variantUriQuery,\n selected,\n available,\n exists,\n isDifferentProduct,\n swatch,\n } = value;\n\n if (isDifferentProduct) {\n // SEO - When the variant is a\n // combined listing child product\n // that leads to a different url,\n // we need to render it\n // as an anchor tag\n return (\n <a\n key={option.name + name}\n href={`/products/${handle}?${variantUriQuery}`}\n style={{\n border: selected\n ? '1px solid black'\n : '1px solid transparent',\n opacity: available ? 1 : 0.3,\n }}\n >\n <ProductOptionSwatch swatch={swatch} name={name} />\n </a>\n );\n } else {\n // SEO - When the variant is an\n // update to the search param,\n // render it as a button with\n // javascript navigating to\n // the variant so that SEO bots\n // do not index these as\n // duplicated links\n return (\n <button\n type=\"button\"\n key={option.name + name}\n style={{\n border: selected\n ? '1px solid black'\n : '1px solid transparent',\n opacity: available ? 1 : 0.3,\n }}\n disabled={!exists}\n onClick={() => {\n if (!selected) {\n // Navigate to `?${variantUriQuery}`\n }\n }}\n >\n <ProductOptionSwatch swatch={swatch} name={name} />\n </button>\n );\n }\n })}\n </div>\n <br />\n </div>\n ))}\n </>\n );\n}\n\nfunction ProductOptionSwatch({\n swatch,\n name,\n}: {\n swatch?: Maybe<ProductOptionValueSwatch> | undefined;\n name: string;\n}) {\n const image = swatch?.image?.previewImage?.url;\n const color = swatch?.color;\n\n if (!image && !color) return name;\n\n return (\n <div\n aria-label={name}\n style={{\n backgroundColor: color || 'transparent',\n }}\n >\n {!!image && <img src={image} alt={name} />}\n </div>\n );\n}\n",
"language": "tsx"
}
],
"title": "Example code"
}
},
"definitions": []
},
{
"name": "getAdjacentAndFirstAvailableVariants",
"category": "utilities",
"isVisualComponent": false,
"related": [
{
"name": "getProductOptions",
"type": "gear",
"url": "/api/hydrogen-react/utilities/getproductoptions"
},
{
"name": "mapSelectedProductOptionToObject",
"type": "gear",
"url": "/api/hydrogen-react/utilities/mapselectedproductoptiontoobject"
}
],
"description": "Finds all the variants provided by `adjacentVariants`, `options.optionValues.firstAvailableVariant`, and `selectedOrFirstAvailableVariant` and return them in a single array. This function will remove any duplicated variants found.",
"type": "utility",
"defaultExample": {
"description": "I am the default example",
"codeblock": {
"tabs": [
{
"title": "getAdjacentAndFirstAvailableVariants example",
"code": "import {getAdjacentAndFirstAvailableVariants} from '@shopify/hydrogen-react';\n\n// Make sure you are querying for the following fields:\n// - product.options.optionValues.firstSelectableVariant\n// - product.selectedOrFirstAvailableVariant\n// - product.adjacentVariants\n//\n// For any fields that are ProductVariant type, make sure to query for:\n// - variant.selectedOptions.name\n// - variant.selectedOptions.value\n\nconst product = {\n /* Result from querying the SFAPI for a product */\n};\n\n// Returns a list of unique variants found in product query\nconst variants = getAdjacentAndFirstAvailableVariants(product);\n",
"language": "js"
}
],
"title": "getAdjacentAndFirstAvailableVariants.js"
}
},
"definitions": []
},
{
"name": "mapSelectedProductOptionToObject",
"category": "utilities",
"isVisualComponent": false,
"related": [
{
"name": "getProductOptions",
"type": "gear",
"url": "/api/hydrogen-react/utilities/getproductoptions"
},
{
"name": "getAdjacentAndFirstAvailableVariants",
"type": "gear",
"url": "/api/hydrogen-react/utilities/getadjacentandfirstavailablevariants"
}
],
"description": "Converts the product selected option into an `Object<key, value>` format for building URL query params",
"type": "utility",
"defaultExample": {
"description": "I am the default example",
"codeblock": {
"tabs": [
{
"title": "mapSelectedProductOptionToObject example",
"code": "import {mapSelectedProductOptionToObject} from '@shopify/hydrogen-react';\n\nconst selectedOption = [\n {\n name: 'Color',\n value: 'Red',\n },\n {\n name: 'Size',\n value: 'Medium',\n },\n];\n\nconst optionsObject = mapSelectedProductOptionToObject(selectedOption);\n\n// Output of optionsObject\n// {\n// Color: 'Red',\n// Size: 'Medium',\n// }\n\nconst searchParams = new URLSearchParams(optionsObject);\nsearchParams.toString(); // '?Color=Red&Size=Medium'\n",
"language": "js"
}
],
"title": "mapSelectedProductOptionToObject.js"
}
},
"definitions": []
},
{
"name": "useLoadScript",
"category": "hooks",
Expand Down
23 changes: 14 additions & 9 deletions packages/hydrogen-react/src/getProductOptions.doc.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,29 +6,34 @@ const data: ReferenceEntityTemplateSchema = {
isVisualComponent: false,
related: [
{
name: 'Storefront Schema',
name: 'mapSelectedProductOptionToObject',
type: 'gear',
url: '/api/hydrogen-react/utilities/storefront-schema',
url: '/api/hydrogen-react/utilities/mapselectedproductoptiontoobject',
},
{
name: 'Storefront API Types',
name: 'getAdjacentAndFirstAvailableVariants',
type: 'gear',
url: '/api/hydrogen-react/utilities/storefront-api-types',
url: '/api/hydrogen-react/utilities/getadjacentandfirstavailablevariants',
},
],
description: `Returns a product options array with its relevant information about the variant.`,
description: `Returns a product options array with its relevant information about the variant. This function supports combined listing products and products with 2000 variants limit.`,
type: 'utility',
defaultExample: {
description: 'I am the default example',
codeblock: {
tabs: [
{
title: 'getProductOption example',
code: './getProductOptions.example.js',
language: 'js',
title: 'JavaScript',
code: './getProductOptions.example.jsx',
language: 'jsx',
},
{
title: 'TypeScript',
code: './getProductOptions.example.tsx',
language: 'tsx',
},
],
title: 'getProductOptions.js',
title: 'Example code',
},
},
definitions: [],
Expand Down
78 changes: 0 additions & 78 deletions packages/hydrogen-react/src/getProductOptions.example.js

This file was deleted.

119 changes: 119 additions & 0 deletions packages/hydrogen-react/src/getProductOptions.example.jsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
import React from 'react';
import {getProductOptions} from '@shopify/hydrogen-react';

// Make sure you are querying for the following fields:
// - product.handle
// - product.encodedVariantExistence
// - product.encodedVariantAvailability
// - product.options.name
// - product.options.optionValues.name
// - product.options.optionValues.firstSelectableVariant
// - product.selectedOrFirstAvailableVariant
// - product.adjacentVariants
//
// For any fields that are ProductVariant type, make sure to query for:
// - variant.product.handle
// - variant.selectedOptions.name
// - variant.selectedOptions.value

export default function ProductForm() {
const product = {
/* Result from querying the SFAPI for a product */
};

const productOptions = getProductOptions(product);

return (
<>
{productOptions.map((option) => (
<div key={option.name}>
<h5>{option.name}</h5>
<div>
{option.optionValues.map((value) => {
const {
name,
handle,
variantUriQuery,
selected,
available,
exists,
isDifferentProduct,
swatch,
} = value;

if (isDifferentProduct) {
// SEO - When the variant is a
// combined listing child product
// that leads to a different url,
// we need to render it
// as an anchor tag
return (
<a
key={option.name + name}
href={`/products/${handle}?${variantUriQuery}`}
style={{
border: selected
? '1px solid black'
: '1px solid transparent',
opacity: available ? 1 : 0.3,
}}
>
<ProductOptionSwatch swatch={swatch} name={name} />
</a>
);
} else {
// SEO - When the variant is an
// update to the search param,
// render it as a button with
// javascript navigating to
// the variant so that SEO bots
// do not index these as
// duplicated links
return (
<button
type="button"
key={option.name + name}
style={{
border: selected
? '1px solid black'
: '1px solid transparent',
opacity: available ? 1 : 0.3,
}}
disabled={!exists}
onClick={() => {
if (!selected) {
// Navigate to `?${variantUriQuery}`
}
}}
>
<ProductOptionSwatch swatch={swatch} name={name} />
</button>
);
}
})}
</div>
<br />
</div>
))}
</>
);
}

function ProductOptionSwatch({swatch, name}) {
const image = swatch?.image?.previewImage?.url;
const color = swatch?.color;

if (!image && !color) return name;

return (
<div
aria-label={name}
className="product-option-label-swatch"
style={{
backgroundColor: color || 'transparent',
}}
>
{!!image && <img src={image} alt={name} />}
</div>
);
}
Loading

0 comments on commit d463bae

Please sign in to comment.