From 3fb5b18e98f67cec11fc23ecd02187f036e89387 Mon Sep 17 00:00:00 2001 From: Michelle Chen Date: Thu, 4 Jul 2024 11:02:58 -0400 Subject: [PATCH 01/17] update dosc to 2024-07 --- .../docs/generated/generated_docs_data.json | 5870 +++++++++++++++++ 1 file changed, 5870 insertions(+) diff --git a/packages/hydrogen/docs/generated/generated_docs_data.json b/packages/hydrogen/docs/generated/generated_docs_data.json index c4ac70f9c5..6263bb753e 100644 --- a/packages/hydrogen/docs/generated/generated_docs_data.json +++ b/packages/hydrogen/docs/generated/generated_docs_data.json @@ -27728,6 +27728,5876 @@ }, "definitions": [] }, + { + "name": "Storefront API Types", + "category": "utilities", + "isVisualComponent": false, + "related": [ + { + "name": "storefrontApiCustomScalars", + "type": "gear", + "url": "/api/hydrogen/utilities/storefrontApiCustomScalars" + }, + { + "name": "Storefront Schema", + "type": "gear", + "url": "/api/hydrogen/utilities/storefront-schema" + } + ], + "description": "\n If you are using TypeScript, pre-generated TypeScript types are available 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.\n ", + "type": "utility", + "defaultExample": { + "description": "I am the default example", + "codeblock": { + "tabs": [ + { + "title": "Storefront API Types in TypeScript", + "code": "import type {\n Product,\n Collection,\n} from '@shopify/hydrogen/storefront-api-types';\n\nconst myProduct = {id: '123', title: 'My Product'} satisfies Partial<Product>;\nconsole.log(myProduct.title);\n\nconst myCollection = {\n id: '456',\n title: 'My Collection',\n} satisfies Partial<Collection>;\nconsole.log(myCollection.title);\n\nconst myNotSatisfyingProduct: Partial<Product> = {\n id: '789',\n title: 'Other Product',\n};\nconsole.log(myNotSatisfyingProduct.title);\n", + "language": "ts" + } + ], + "title": "Example code" + } + }, + "definitions": [] + }, + { + "name": "Image", + "category": "components", + "subCategory": "media", + "isVisualComponent": false, + "related": [ + { + "name": "MediaFile", + "type": "component", + "url": "/api/hydrogen/components/mediafile" + } + ], + "description": "The `Image` component renders an image for the Storefront API's\n[Image object](https://shopify.dev/api/storefront/reference/common-objects/image) by using the `data` prop. You can [customize this component](https://shopify.dev/api/hydrogen/components#customizing-hydrogen-components) using passthrough props.\n\nImages default to being responsive automatically (`width: 100%, height: auto`), and expect an `aspectRatio` prop, which ensures your image doesn't create any layout shift. For fixed-size images, you can set `width` to an exact value, and a `srcSet` with 1x, 2x, and 3x DPI variants will automatically be generated for you.", + "type": "component", + "defaultExample": { + "description": "I am the default example", + "codeblock": { + "tabs": [ + { + "title": "JavaScript", + "code": "import {Image} from '@shopify/hydrogen';\n\n// An example query\nconst IMAGE_QUERY = `#graphql\n query {\n product {\n featuredImage {\n altText\n url\n height\n width\n }\n }\n }\n`;\n\nexport default function ProductImage({product}) {\n if (!product.featuredImage) {\n return null;\n }\n\n return (\n <Image\n data={product.featuredImage}\n sizes=\"(min-width: 45em) 50vw, 100vw\"\n aspectRatio=\"4/5\"\n />\n );\n}\n", + "language": "jsx" + }, + { + "title": "TypeScript", + "code": "import React from 'react';\nimport {Image} from '@shopify/hydrogen';\nimport type {Product} from '@shopify/hydrogen/storefront-api-types';\n\n// An example query\nconst IMAGE_QUERY = `#graphql\n query {\n product {\n featuredImage {\n altText\n url\n height\n width\n }\n }\n }\n`;\n\nexport default function ProductImage({product}: {product: Product}) {\n if (!product.featuredImage) {\n return null;\n }\n\n return (\n <Image\n data={product.featuredImage}\n sizes=\"(min-width: 45em) 50vw, 100vw\"\n aspectRatio=\"4/5\"\n />\n );\n}\n", + "language": "tsx" + } + ], + "title": "Example code" + } + }, + "definitions": [ + { + "title": "Props", + "description": "", + "type": "HydrogenImageBaseProps", + "typeDefinitions": { + "HydrogenImageBaseProps": { + "filePath": "/Image.tsx", + "syntaxKind": "TypeAliasDeclaration", + "name": "HydrogenImageBaseProps", + "value": "{\n /** The aspect ratio of the image, in the format of `width/height`.\n *\n * @example\n * ```\n * \n * ```\n */\n aspectRatio?: string;\n /** The crop position of the image.\n *\n * @remarks\n * In the event that AspectRatio is set, without specifying a crop,\n * the Shopify CDN won't return the expected image.\n *\n * @defaultValue `center`\n */\n crop?: Crop;\n /** Data mapping to the [Storefront API `Image`](https://shopify.dev/docs/api/storefront/2024-07/objects/Image) object. Must be an Image object.\n *\n * @example\n * ```\n * import {IMAGE_FRAGMENT, Image} from '@shopify/hydrogen';\n *\n * export const IMAGE_QUERY = `#graphql\n * ${IMAGE_FRAGMENT}\n * query {\n * product {\n * featuredImage {\n * ...Image\n * }\n * }\n * }`\n *\n * \n * ```\n *\n * Image: {@link https://shopify.dev/api/storefront/reference/common-objects/image}\n */\n data?: PartialDeep;\n /** A function that returns a URL string for an image.\n *\n * @remarks\n * By default, this uses Shopify’s CDN {@link https://cdn.shopify.com/} but you can provide\n * your own function to use a another provider, as long as they support URL based image transformations.\n */\n loader?: Loader;\n /** An optional prop you can use to change the default srcSet generation behaviour */\n srcSetOptions?: SrcSetOptions;\n}", + "description": "", + "members": [ + { + "filePath": "/Image.tsx", + "syntaxKind": "PropertySignature", + "name": "aspectRatio", + "value": "string", + "description": "The aspect ratio of the image, in the format of `width/height`.", + "isOptional": true, + "examples": [ + { + "title": "Example", + "description": "", + "tabs": [ + { + "code": "", + "title": "Example" + } + ] + } + ] + }, + { + "filePath": "/Image.tsx", + "syntaxKind": "PropertySignature", + "name": "crop", + "value": "Crop", + "description": "The crop position of the image.", + "isOptional": true, + "defaultValue": "`center`" + }, + { + "filePath": "/Image.tsx", + "syntaxKind": "PropertySignature", + "name": "data", + "value": "PartialDeep", + "description": "Data mapping to the [Storefront API `Image`](https://shopify.dev/docs/api/storefront/2024-07/objects/Image) object. Must be an Image object.", + "isOptional": true, + "examples": [ + { + "title": "Example", + "description": "", + "tabs": [ + { + "code": "import {IMAGE_FRAGMENT, Image} from '@shopify/hydrogen';\n\nexport const IMAGE_QUERY = `#graphql\n${IMAGE_FRAGMENT}\nquery {\n product {\n featuredImage {\n ...Image\n }\n }\n}`\n\n", + "title": "Example" + }, + { + "code": "Image:", + "title": "Example" + } + ] + } + ] + }, + { + "filePath": "/Image.tsx", + "syntaxKind": "PropertySignature", + "name": "loader", + "value": "Loader", + "description": "A function that returns a URL string for an image.", + "isOptional": true + }, + { + "filePath": "/Image.tsx", + "syntaxKind": "PropertySignature", + "name": "srcSetOptions", + "value": "SrcSetOptions", + "description": "An optional prop you can use to change the default srcSet generation behaviour", + "isOptional": true + } + ] + }, + "Crop": { + "filePath": "/Image.tsx", + "syntaxKind": "TypeAliasDeclaration", + "name": "Crop", + "value": "'center' | 'top' | 'bottom' | 'left' | 'right'", + "description": "" + }, + "Loader": { + "filePath": "/Image.tsx", + "name": "Loader", + "description": "", + "params": [ + { + "name": "params", + "description": "", + "value": "LoaderParams", + "filePath": "/Image.tsx" + } + ], + "returns": { + "filePath": "/Image.tsx", + "description": "", + "name": "string", + "value": "string" + }, + "value": "export type Loader = (params: LoaderParams) => string;" + }, + "LoaderParams": { + "filePath": "/Image.tsx", + "syntaxKind": "TypeAliasDeclaration", + "name": "LoaderParams", + "value": "{\n /** The base URL of the image */\n src?: ImageType['url'];\n /** The URL param that controls width */\n width?: number;\n /** The URL param that controls height */\n height?: number;\n /** The URL param that controls the cropping region */\n crop?: Crop;\n}", + "description": "", + "members": [ + { + "filePath": "/Image.tsx", + "syntaxKind": "PropertySignature", + "name": "src", + "value": "string", + "description": "The base URL of the image", + "isOptional": true + }, + { + "filePath": "/Image.tsx", + "syntaxKind": "PropertySignature", + "name": "width", + "value": "number", + "description": "The URL param that controls width", + "isOptional": true + }, + { + "filePath": "/Image.tsx", + "syntaxKind": "PropertySignature", + "name": "height", + "value": "number", + "description": "The URL param that controls height", + "isOptional": true + }, + { + "filePath": "/Image.tsx", + "syntaxKind": "PropertySignature", + "name": "crop", + "value": "Crop", + "description": "The URL param that controls the cropping region", + "isOptional": true + } + ] + }, + "SrcSetOptions": { + "filePath": "/Image.tsx", + "syntaxKind": "TypeAliasDeclaration", + "name": "SrcSetOptions", + "value": "{\n /** The number of sizes to generate */\n intervals: number;\n /** The smallest image size */\n startingWidth: number;\n /** The increment by which to increase for each size, in pixels */\n incrementSize: number;\n /** The size used for placeholder fallback images */\n placeholderWidth: number;\n}", + "description": "", + "members": [ + { + "filePath": "/Image.tsx", + "syntaxKind": "PropertySignature", + "name": "intervals", + "value": "number", + "description": "The number of sizes to generate" + }, + { + "filePath": "/Image.tsx", + "syntaxKind": "PropertySignature", + "name": "startingWidth", + "value": "number", + "description": "The smallest image size" + }, + { + "filePath": "/Image.tsx", + "syntaxKind": "PropertySignature", + "name": "incrementSize", + "value": "number", + "description": "The increment by which to increase for each size, in pixels" + }, + { + "filePath": "/Image.tsx", + "syntaxKind": "PropertySignature", + "name": "placeholderWidth", + "value": "number", + "description": "The size used for placeholder fallback images" + } + ] + } + } + } + ] + }, + { + "name": "ExternalVideo", + "category": "components", + "subCategory": "media", + "isVisualComponent": false, + "related": [ + { + "name": "MediaFile", + "type": "component", + "url": "/api/hydrogen/components/mediafile" + } + ], + "description": "The `ExternalVideo` component renders an embedded video for the Storefront API's [ExternalVideo object](https://shopify.dev/api/storefront/reference/products/externalvideo).", + "type": "component", + "defaultExample": { + "description": "I am the default example", + "codeblock": { + "tabs": [ + { + "title": "JavaScript", + "code": "import {ExternalVideo} from '@shopify/hydrogen';\n\nexport default function MyProductVideo({products}) {\n const firstMediaElement = products.nodes[0].media.nodes[0];\n\n if (firstMediaElement.__typename === 'ExternalVideo') {\n return <ExternalVideo data={firstMediaElement} />;\n }\n}\n", + "language": "jsx" + }, + { + "title": "TypeScript", + "code": "import {ExternalVideo} from '@shopify/hydrogen';\nimport type {ProductConnection} from '@shopify/hydrogen/storefront-api-types';\n\nexport default function MyProductVideo({\n products,\n}: {\n products: ProductConnection;\n}) {\n const firstMediaElement = products.nodes[0].media.nodes[0];\n if (firstMediaElement.__typename === 'ExternalVideo') {\n return <ExternalVideo data={firstMediaElement} />;\n }\n}\n", + "language": "tsx" + } + ], + "title": "ExternalVideo example" + } + }, + "definitions": [ + { + "title": "Props", + "description": "Takes in the same props as a native `