From ea049f72e2f1cc2136e7e20f3ce9a3ae3602c667 Mon Sep 17 00:00:00 2001 From: Robert Reinhard Date: Wed, 29 Nov 2023 22:36:22 -0800 Subject: [PATCH] Update documentation --- README.md | 17 ++++++++ packages/contentful/README.md | 73 ++++++++++++++++++++--------------- packages/react/README.md | 1 + 3 files changed, 59 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index d4c69e8..0a700a9 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,7 @@ A monorepo hosting components for rendering image and video in a single container for easy rendering of visual elements. - [@react-visual/react](./packages/react) - Vanilla implementation. +- [@react-visual/contentful](./packages/contentful) - Adapter for Contentful assets. - [@react-visual/next](./packages/next) - Uses the `next/image` component for rendering images. - [@react-visual/sanity-next](./packages/sanity-next) - Takes Sanity asset and passes them to `@react-visual/next` for rendering. @@ -34,6 +35,22 @@ export default function ResponsiveExample() { [View CodeSandbox demo](https://codesandbox.io/p/sandbox/react-visual-react-demo-w4sh62) +### @react-visual/contentful + +Using with a Visual entryType containing image and video fields: + +```jsx +import Visual from '@react-visual/contentful' + +export default function Example() { + return ( + + ) +} +``` + ### @react-visual/next Using framework adapter for Next.js: diff --git a/packages/contentful/README.md b/packages/contentful/README.md index dbc4baf..a509fb2 100644 --- a/packages/contentful/README.md +++ b/packages/contentful/README.md @@ -1,51 +1,40 @@ -# @react-visual/next [![react-visual](https://img.shields.io/endpoint?url=https://cloud.cypress.io/badge/simple/fn6c7w&style=flat&logo=cypress)](https://cloud.cypress.io/projects/fn6c7w/runs) +# @react-visual/contentful [![react-visual](https://img.shields.io/endpoint?url=https://cloud.cypress.io/badge/simple/fn6c7w&style=flat&logo=cypress)](https://cloud.cypress.io/projects/fn6c7w/runs) -Renders images and videos into a container. Features: +Renders Contentful images and videos into a container. Features: -- Uses `next/image` to render images -- Easily render assets using aspect ratios -- Videos are lazyloaded (unless `priority` flag is set) +- Automatically defines a loader functions for generating srcsets +- Supports responsive image and video assets ## Install ```sh -yarn add @react-visual/next +yarn add @react-visual/contentful ``` -Images will be rendered using `next/image` so expect to do configuration of [`remotePatterns`](https://nextjs.org/docs/app/api-reference/components/image#remotepatterns) for CMS hosted images. - ## Usage +### Asset fields + ```jsx -import Visual from '@react-visual/next' +import Visual from '@react-visual/contentful' export default function Example() { return ( + image={ entry.image } + video={ entry.video } + sizes='100vw'/> ) } ``` -```gql -fragment visual on Visual { - image { ...image } - portraitImage { ...image } - video { ...video } - portraitVideo { ...video } - alt -} +Where `image` and `video` are asset fields defined by these GQL fragments: +```gql fragment image on Asset { title description fileName - title - description width height url @@ -59,11 +48,31 @@ fragment video on Asset { } ``` +### Visual entryType reference + +This is the expected pattern for rendering responsive images and videos. + +```jsx +import Visual from '@react-visual/contentful' + +export default function Example() { + return ( + + ) +} +``` + +Where `background` is defined by this GQL fragment (this consumes the previous fragments): + ```gql -query heroBlockEntryQuery { - heroBlock(id: "3T13NtVzGIOKRMISRYRDhO") { - background { ...visual } - } +fragment visual on Visual { + image { ...image } + portraitImage { ...image } + video { ...video } + portraitVideo { ...video } + alt } ``` @@ -75,16 +84,16 @@ For more examples, read [the Cypress component tests](./cypress/component). | Prop | Type | Description | -- | -- | -- -| `image` | `string` | URL to an image asset. -| `video` | `string` | URL to a video asset asset. -| `placeholderData` | `string` | A Data URL that is rendered before the image loads via [`next/image`'s `blurDataURL`](https://nextjs.org/docs/pages/api-reference/components/image#blurdataurl). +| `image` | `object` | A Contentful image Asset. +| `video` | `object` | A Contentful video Asset. +| `src` | `object` | An object with keys of responsive keys. See examples above. ### Layout | Prop | Type | Description | -- | -- | -- | `expand` | `boolean` | Make the Visual fill it's container via CSS using absolute positioning. -| `aspect` | `number` | Force the Visual to a specific aspect ratio. +| `aspect` | `number` | Force the Visual to a specific aspect ratio. If empty, this will be set using width and height fields from Contentful queries. | `width` | `number`, `string` | A CSS dimension value or a px number. | `height` | `number`, `string` | A CSS dimension value or a px number. | `fit` | `string` | An [`object-fit`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) value that is applied to the assets. Defaults to `cover`. diff --git a/packages/react/README.md b/packages/react/README.md index 53f9ea4..0e7186d 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -194,6 +194,7 @@ For more examples, read [the Cypress component tests](./cypress/component). | `sourceTypes` | `string[]` | Specify image MIME types that will be passed to the `imageLoader` and used to create additional `` tags. Use this to create `webp` or `avif` sources with a CDN like Contentful. | `sourceMedia` | `string[]` | Specify media queries that will be passed to the `imageLoader` and used to create additional `` tags. | `imageLoader` | `Function` | Uses syntax that is similar [to `next/image`'s `loader` prop](https://nextjs.org/docs/app/api-reference/components/image#loader). A srcset is built with a hardcoded list of widths. +| `videoLoader` | `Function` | Like `imageLoader` but is only passed the `src` and `media` properties. ### Video