diff --git a/.github/workflows/cypress.yml b/.github/workflows/cypress.yml index cba8281..d89b4ab 100644 --- a/.github/workflows/cypress.yml +++ b/.github/workflows/cypress.yml @@ -9,8 +9,9 @@ jobs: strategy: matrix: dir: - - packages/next - packages/react + - packages/contentful + - packages/next - packages/sanity-next steps: 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 new file mode 100644 index 0000000..a509fb2 --- /dev/null +++ b/packages/contentful/README.md @@ -0,0 +1,128 @@ +# @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 Contentful images and videos into a container. Features: + +- Automatically defines a loader functions for generating srcsets +- Supports responsive image and video assets + +## Install + +```sh +yarn add @react-visual/contentful +``` + +## Usage + +### Asset fields + +```jsx +import Visual from '@react-visual/contentful' + +export default function Example() { + return ( + + ) +} +``` + +Where `image` and `video` are asset fields defined by these GQL fragments: + +```gql +fragment image on Asset { + title + description + fileName + width + height + url +} + +fragment video on Asset { + title + description + fileName + url +} +``` + +### 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 +fragment visual on Visual { + image { ...image } + portraitImage { ...image } + video { ...video } + portraitVideo { ...video } + alt +} +``` + +For more examples, read [the Cypress component tests](./cypress/component). + +## Props + +### Sources + +| Prop | Type | Description +| -- | -- | -- +| `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. 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`. +| `position` | `string` | An [`object-position`](https://developer.mozilla.org/en-US/docs/Web/CSS/object-position) value. + +### Loading + +| Prop | Type | Description +| -- | -- | -- +| `priority` | `boolean` | Sets [`next/image`'s `priority`](https://nextjs.org/docs/pages/api-reference/components/image#priority) and videos to not lazy load. +| `sizes` | `string` | Sets [`next/image`'s `sizes`](https://nextjs.org/docs/pages/api-reference/components/image#sizes) prop. +| `imageLoader` | `Function` | This is passed through [to `next/image`'s `loader` prop](https://nextjs.org/docs/app/api-reference/components/image#loader). + +### Video + +| Prop | Type | Description +| -- | -- | -- +| `paused` | `boolean` | Disables autoplay of videos. This prop is reactive, unlike the `paused` property of the html `