diff --git a/README.md b/README.md index b1aa57e..b168ca9 100644 --- a/README.md +++ b/README.md @@ -10,825 +10,27 @@ A set of components and utilities to work faster with [DatoCMS](https://www.dato

-## Table of Contents - - - - -- [Demos](#demos) -- [Installation](#installation) -- [Live real-time updates](#live-real-time-updates) - - [Reference](#reference) - - [Initialization options](#initialization-options) - - [Connection status](#connection-status) - - [Error object](#error-object) - - [Example](#example) -- [Progressive/responsive image](#progressiveresponsive-image) - - [Out-of-the-box features](#out-of-the-box-features) - - [Intersection Observer](#intersection-observer) - - [Usage](#usage) - - [Example](#example-1) - - [Props](#props) - - [Layout mode](#layout-mode) - - [The `ResponsiveImage` object](#the-responsiveimage-object) -- [Social share, SEO and Favicon meta tags](#social-share-seo-and-favicon-meta-tags) - - [`renderMetaTags()`](#rendermetatags) - - [`renderMetaTagsToString()`](#rendermetatagstostring) - - [`toRemixMeta()`](#toremixmeta) -- [Structured text](#structured-text) - - [Basic usage](#basic-usage) - - [Custom renderers for inline records, blocks, and links](#custom-renderers-for-inline-records-blocks-and-links) - - [Override default rendering of nodes](#override-default-rendering-of-nodes) - - [Props](#props-1) -- [Site Search hook](#site-search-hook) - - [Reference](#reference-1) - - [Initialization options](#initialization-options-1) - - [Returned data](#returned-data) -- [Development](#development) - - - -## Demos - -For fully working examples take a look at our [examples directory](https://github.com/datocms/react-datocms/tree/master/examples). - -Live demo: [https://react-datocms-example.netlify.com/](https://react-datocms-example.netlify.com/) - -## Installation +# Installation ``` npm install react-datocms ``` -# Live real-time updates - -`useQuerySubscription` is a React hook that you can use to implement client-side updates of the page as soon as the content changes. It uses DatoCMS's [Real-time Updates API](https://www.datocms.com/docs/real-time-updates-api/api-reference) to receive the updated query results in real-time, and is able to reconnect in case of network failures. - -Live updates are great both to get instant previews of your content while editing it inside DatoCMS, or to offer real-time updates of content to your visitors (ie. news site). - -- TypeScript ready; -- Compatible with vanilla React, Next.js and pretty much any other React-based solution; - -## Reference - -Import `useQuerySubscription` from `react-datocms` and use it inside your components like this: - -```js -const { - data: QueryResult | undefined, - error: ChannelErrorData | null, - status: ConnectionStatus, -} = useQuerySubscription(options: Options); -``` - -## Initialization options - -| prop | type | required | description | default | -| ------------------ | ----------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------ | ------------------------------------ | -| enabled | boolean | :x: | Whether the subscription has to be performed or not | true | -| query | string | :white_check_mark: | The GraphQL query to subscribe | | -| token | string | :white_check_mark: | DatoCMS API token to use | | -| variables | Object | :x: | GraphQL variables for the query | | -| preview | boolean | :x: | If true, the Content Delivery API with draft content will be used | false | -| environment | string | :x: | The name of the DatoCMS environment where to perform the query | defaults to primary environment | -| initialData | Object | :x: | The initial data to use on the first render | | -| reconnectionPeriod | number | :x: | In case of network errors, the period (in ms) to wait to reconnect | 1000 | -| fetcher | a [fetch-like function](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) | :x: | The fetch function to use to perform the registration query | window.fetch | -| eventSourceClass | an [EventSource-like](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) class | :x: | The EventSource class to use to open up the SSE connection | window.EventSource | -| baseUrl | string | :x: | The base URL to use to perform the query | `https://graphql-listen.datocms.com` | - -## Connection status - -The `status` property represents the state of the server-sent events connection. It can be one of the following: - -- `connecting`: the subscription channel is trying to connect -- `connected`: the channel is open, we're receiving live updates -- `closed`: the channel has been permanently closed due to a fatal error (ie. an invalid query) - -## Error object - -| prop | type | description | -| -------- | ------ | ------------------------------------------------------- | -| code | string | The code of the error (ie. `INVALID_QUERY`) | -| message | string | An human friendly message explaining the error | -| response | Object | The raw response returned by the endpoint, if available | - -## Example - -```js -import React from 'react'; -import { useQuerySubscription } from 'react-datocms'; - -const App: React.FC = () => { - const { status, error, data } = useQuerySubscription({ - enabled: true, - query: ` - query AppQuery($first: IntType) { - allBlogPosts { - slug - title - } - }`, - variables: { first: 10 }, - token: 'YOUR_API_TOKEN', - }); - - const statusMessage = { - connecting: 'Connecting to DatoCMS...', - connected: 'Connected to DatoCMS, receiving live updates!', - closed: 'Connection closed', - }; - - return ( -
-

Connection status: {statusMessage[status]}

- {error && ( -
-

Error: {error.code}

-
{error.message}
- {error.response && ( - 
{JSON.stringify(error.response, null, 2)}
- )} -
- )} - {data && ( - - )} -
- ); -}; -``` - -# Progressive/responsive image - -`` is a React component specially designed to work seamlessly with DatoCMS’s [`responsiveImage` GraphQL query](https://www.datocms.com/docs/content-delivery-api/uploads#responsive-images) that optimizes image loading for your sites. - -- TypeScript ready; -- CSS-in-JS ready; -- Usable both client and server side; -- Compatible with vanilla React, Next.js and pretty much any other React-based solution; - -![](docs/image-component.gif?raw=true) - -## Out-of-the-box features - -- Offers WebP version of images for browsers that support the format -- Generates multiple smaller images so smartphones and tablets don’t download desktop-sized images -- Efficiently lazy loads images to speed initial page load and save bandwidth -- Holds the image position so your page doesn’t jump while images load -- Uses either blur-up or background color techniques to show a preview of the image while it loads - -## Intersection Observer - -Intersection Observer is the API used to determine if the image is inside the viewport or not. [Browser support is really good](https://caniuse.com/intersectionobserver) - With Safari adding support in 12.1, all major browsers now support Intersection Observers natively. - -If the IntersectionObserver object is not available, the component treats the image as it's always visible in the viewport. Feel free to add a [polyfill](https://www.npmjs.com/package/intersection-observer) so that it will also 100% work on older versions of iOS and IE11. - -## Usage - -1. Import `Image` from `react-datocms` and use it in place of the regular `` tag -2. Write a GraphQL query to your DatoCMS project using the [`responsiveImage` query](https://www.datocms.com/docs/content-delivery-api/images-and-videos#responsive-images) - -The GraphQL query returns multiple thumbnails with optimized compression. The `Image` component automatically sets up the “blur-up” effect as well as lazy loading of images further down the screen. - -## Example - -For a fully working example take a look at our [examples directory](https://github.com/datocms/react-datocms/tree/master/examples). - -```js -import React from 'react'; -import { Image } from 'react-datocms'; - -const Page = ({ data }) => ( -
-

{data.blogPost.title}

- -
-); - -const query = gql` - query { - blogPost { - title - cover { - responsiveImage( - imgixParams: { fit: crop, w: 300, h: 300, auto: format } - ) { - # HTML5 src/srcset/sizes attributes - srcSet - webpSrcSet - sizes - src - - # size information (post-transformations) - width - height - aspectRatio - - # SEO attributes - alt - title - - # background color placeholder or... - bgColor - - # blur-up placeholder, JPEG format, base64-encoded - base64 - } - } - } - } -`; - -export default withQuery(query)(Page); -``` - -## Props - -| prop | type | required | description | default | -| --------------------- | ------------------------------------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | -| data | `ResponsiveImage` object | :white_check_mark: | The actual response you get from a DatoCMS `responsiveImage` GraphQL query | | -| layout | 'intrinsic' \| 'fixed' \| 'responsive' \| 'fill' | :x: | The layout behavior of the image as the viewport changes size | "intrinsic" | -| className | string | :x: | Additional CSS className for root node | null | -| style | CSS properties | :x: | Additional CSS rules to add to the root node | null | -| pictureClassName | string | :x: | Additional CSS class for the image inside the inner `` tag | null | -| pictureStyle | CSS properties | :x: | Additional CSS rules to add to the image inside the inner `` tag | null | -| fadeInDuration | integer | :x: | Duration (in ms) of the fade-in transition effect upoad image loading | 500 | -| intersectionThreshold | float | :x: | Indicate at what percentage of the placeholder visibility the loading of the image should be triggered. A value of 0 means that as soon as even one pixel is visible, the callback will be run. A value of 1.0 means that the threshold isn't considered passed until every pixel is visible. | 0 | -| intersectionMargin | string | :x: | Margin around the placeholder. Can have values similar to the CSS margin property (top, right, bottom, left). The values can be percentages. This set of values serves to grow or shrink each side of the placeholder element's bounding box before computing intersections. | "0px 0px 0px 0px" | -| lazyLoad | Boolean | :x: | Whether enable lazy loading or not | true | -| onLoad | () => void | :x: | Function triggered when the image has finished loading | undefined | -| usePlaceholder | Boolean | :x: | Whether the component should use a blurred image placeholder | true | - -### Layout mode - -With the `layout` property, you can configure the behavior of the image as the viewport changes size: - -- When `intrinsic` (default behaviour), the image will scale the dimensions down for smaller viewports, but maintain the original dimensions for larger viewports. -- When `fixed`, the image dimensions will not change as the viewport changes (no responsiveness) similar to the native `img` element. -- When `responsive`, the image will scale the dimensions down for smaller viewports and scale up for larger viewports. -- When `fill`, the image will stretch both width and height to the dimensions of the parent element, provided the parent element is relative. - - This is usually paired with the `objectFit` and `objectPosition` properties. - - Ensure the parent element has `position: relative` in their stylesheet. - -Example for `layout="fill"` (useful also for background images): - -```jsx -
- -
-``` - -### The `ResponsiveImage` object - -The `data` prop expects an object with the same shape as the one returned by `responsiveImage` GraphQL call. It's up to you to make a GraphQL query that will return the properties you need for a specific use of the `` component. - -- The minimum required properties for `data` are: `aspectRatio`, `width`, `sizes`, `srcSet` and `src`; -- `alt` and `title`, while not mandatory, are all highly suggested, so remember to use them! -- You either want to add the `webpSrcSet` field or specify `{ auto: format }` in your `imgixParams`, to automatically use WebP images in browsers that support the format; -- If you provide both the `bgColor` and `base64` property, the latter will take precedence, so just avoiding querying both fields at the same time, it will only make the response bigger :wink: - -Here's a complete recap of what `responsiveImage` offers: - -| property | type | required | description | -| ----------- | ------- | ------------------ | ----------------------------------------------------------------------------------------------- | -| aspectRatio | float | :white_check_mark: | The aspect ratio (width/height) of the image | -| width | integer | :white_check_mark: | The width of the image | -| height | integer | :white_check_mark: | The height of the image | -| sizes | string | :white_check_mark: | The HTML5 `sizes` attribute for the image | -| srcSet | string | :white_check_mark: | The HTML5 `srcSet` attribute for the image | -| src | string | :white_check_mark: | The fallback `src` attribute for the image | -| webpSrcSet | string | :x: | The HTML5 `srcSet` attribute for the image in WebP format, for browsers that support the format | -| alt | string | :x: | Alternate text (`alt`) for the image | -| title | string | :x: | Title attribute (`title`) for the image | -| bgColor | string | :x: | The background color for the image placeholder | -| base64 | string | :x: | A base64-encoded thumbnail to offer during image loading | - -# Social share, SEO and Favicon meta tags - -Just like for the image component this package offers a number of utilities designed to work seamlessly with DatoCMS’s [`_seoMetaTags` and `faviconMetaTags` GraphQL queries](https://www.datocms.com/docs/content-delivery-api/seo) so that you can easily handle SEO, social shares and favicons in your pages. - -All the utilities take an array of `SeoOrFaviconTag`s in the exact form they're returned by the following [DatoCMS GraphQL API queries](https://www.datocms.com/docs/content-delivery-api/seo): - -- `_seoMetaTags` (always available on any type of record) -- `faviconMetaTags` on the global `_site` object. - -```graphql -query { - page: homepage { - title - seo: _seoMetaTags { - attributes - content - tag - } - } - - site: _site { - favicon: faviconMetaTags { - attributes - content - tag - } - } -} -``` - -You can then concat those two arrays of tags and pass them togheter to the function, ie: - -```js -renderMetaTags([...data.page.seo, ...data.site.favicon]); -``` - -## `renderMetaTags()` - -This function generates React `` and `` elements, so it is compatible with React packages like [`react-helmet`](https://www.npmjs.com/package/react-helmet). - -For a complete example take a look at our [examples directory](https://github.com/datocms/react-datocms/tree/master/examples). - -```js -import React from 'react'; -import { renderMetaTags } from 'react-datocms'; - -function Page({ data }) { - return ( -
- - {renderMetaTags([...data.page.seo, ...data.site.favicon])} - -
- ); -} -``` - -## `renderMetaTagsToString()` - -This function generates an HTML string containing `` and `` tags, so it can be used server-side. - -```js -import { renderMetaTagsToString } from 'react-datocms'; - -const someMoreComplexHtml = ` - - - ${renderMetaTagsToString([...data.page.seo, ...data.site.favicon])} - - -`; -``` - -## `toRemixMeta()` - -This function generates a `HtmlMetaDescriptor` object, compatibile with the [`meta`](https://remix.run/docs/en/v1.1.1/api/conventions#meta) export of the [Remix](https://remix.run/) framework: - -```js -import type { MetaFunction } from 'remix'; -import { toRemixMeta } from 'react-datocms'; - -export const meta: MetaFunction = ({ data: { post } }) => { - return toRemixMeta(post.seo); -}; -``` - -Please note that the [`links`](https://remix.run/docs/en/v1.1.1/api/conventions#links) export [doesn't receive any loader data](https://github.com/remix-run/remix/issues/32) for performance reasons, so you cannot use it to declare favicons meta tags! The best way to render them is using `renderMetaTags` in your root component: - -```jsx -import { renderMetaTags } from 'react-datocms'; - -export const loader = () => { - return request({ - query: ` - { - site: _site { - favicon: faviconMetaTags(variants: [icon, msApplication, appleTouchIcon]) { - ...metaTagsFragment - } - } - } - ${metaTagsFragment} - `, - }); -}; - -export default function App() { - const { site } = useLoaderData(); - - return ( - - - - - - - {renderMetaTags(site.favicon)} - - - - - - {process.env.NODE_ENV === 'development' && } - - - ); -} -``` - -# Structured text - -`` is a React component that you can use to render the value contained inside a DatoCMS [Structured Text field type](https://www.datocms.com/docs/structured-text/dast). - -## Basic usage - -```js -import React from 'react'; -import { StructuredText } from 'react-datocms'; - -const Page = ({ data }) => { - // data.blogPost.content = { - // value: { - // schema: "dast", - // document: { - // type: "root", - // children: [ - // { - // type: "heading", - // level: 1, - // children: [ - // { - // type: "span", - // value: "Hello ", - // }, - // { - // type: "span", - // marks: ["strong"], - // value: "world!", - // }, - // ], - // }, - // ], - // }, - // }, - // } - - return ( -
-

{data.blogPost.title}

- - {/* ->

Hello world!

*/} -
- ); -}; - -const query = gql` - query { - blogPost { - title - content { - value - } - } - } -`; - -export default withQuery(query)(Page); -``` - -## Custom renderers for inline records, blocks, and links - -You can also pass custom renderers for special nodes (inline records, record links and blocks) as an optional parameter like so: - -```js -import React from 'react'; -import { StructuredText, Image } from 'react-datocms'; - -const Page = ({ data }) => { - // data.blogPost.content -> - // { - // value: { - // schema: "dast", - // document: { - // type: "root", - // children: [ - // { - // type: "heading", - // level: 1, - // children: [ - // { type: "span", value: "Welcome onboard " }, - // { type: "inlineItem", item: "324321" }, - // ], - // }, - // { - // type: "paragraph", - // children: [ - // { type: "span", value: "So happy to have " }, - // { - // type: "itemLink", - // item: "324321", - // children: [ - // { - // type: "span", - // marks: ["strong"], - // value: "this awesome humang being", - // }, - // ] - // }, - // { type: "span", value: " in our team!" }, - // ] - // }, - // { type: "block", item: "1984559" } - // ], - // }, - // }, - // links: [ - // { - // id: "324321", - // __typename: "TeamMemberRecord", - // firstName: "Mark", - // slug: "mark-smith", - // }, - // ], - // blocks: [ - // { - // id: "324321", - // __typename: "ImageRecord", - // image: { - // responsiveImage: { ... }, - // }, - // }, - // ], - // } - - return ( -
-

{data.blogPost.title}

- { - switch (record.__typename) { - case 'TeamMemberRecord': - return {record.firstName}; - default: - return null; - } - }} - renderLinkToRecord={({ record, children, transformedMeta }) => { - switch (record.__typename) { - case 'TeamMemberRecord': - return ( - - {children} - - ); - default: - return null; - } - }} - renderBlock={({ record }) => { - switch (record.__typename) { - case 'ImageRecord': - return ; - default: - return null; - } - }} - /> - {/* - Final result: - -

Welcome onboard Mark

-

So happy to have this awesome humang being in our team!

- Our team at work - */} -
- ); -}; - -const query = gql` - query { - blogPost { - title - content { - value - links { - __typename - ... on TeamMemberRecord { - id - firstName - slug - } - } - blocks { - __typename - ... on ImageRecord { - id - image { - responsiveImage( - imgixParams: { fit: crop, w: 300, h: 300, auto: format } - ) { - srcSet - webpSrcSet - sizes - src - width - height - aspectRatio - alt - title - base64 - } - } - } - } - } - } - } -`; - -export default withQuery(query)(Page); -``` - -## Override default rendering of nodes - -This component automatically renders all nodes except for `inline_item`, `item_link` and `block` using a set of default rules, but you might want to customize those. For example: - -For example: - -- For `heading` nodes, you might want to add an anchor; -- For `code` nodes, you might want to use a custom sytax highlighting component like [`prism-react-renderer`](https://github.com/FormidableLabs/prism-react-renderer); -- Apply different logic/formatting to a node based on what its parent node is (using the `ancestors` parameter) - -- For all possible node types, refer to the [list of typeguard functions defined in the main `structured-text` package](https://github.com/datocms/structured-text/tree/main/packages/utils#typescript-type-guards). The [DAST format documentation](https://www.datocms.com/docs/structured-text/dast) has additional details. - -In this case, you can easily override default rendering rules with the `customNodeRules` and `customMarkRules` props. - -```jsx -import { renderNodeRule, renderMarkRule, StructuredText } from 'react-datocms'; -import { isHeading, isCode } from 'datocms-structured-text-utils'; -import { render as toPlainText } from 'datocms-structured-text-to-plain-text'; -import SyntaxHighlight from 'components/SyntaxHighlight'; - - { - const HeadingTag = `h${node.level}`; - const anchor = toPlainText(node) - .toLowerCase() - .replace(/ /g, '-') - .replace(/[^\w-]+/g, ''); - - return ( - - {children} - - - ); - }), - - // Use a custom syntax highlighter component for code blocks - renderNodeRule(isCode, ({ node, key }) => { - return ( - - ); - }), - - // Apply different formatting to top-level paragraphs - renderNodeRule( - isParagraph, - ({ adapter: { renderNode }, node, children, key, ancestors }) => { - if (isRoot(ancestors[0])) { - // If this paragraph node is a top-level one, give it a special class - return renderNode( - 'p', - { key, className: 'top-level-paragraph-container-example' }, - children, - ); - } else { - // Proceed with default paragraph rendering... - // return renderNode('p', { key }, children); - - // Or even completely remove the paragraph and directly render the inner children: - return children; - } - }, - ), - ]} - customMarkRules={[ - // convert "strong" marks into tags - renderMarkRule('strong', ({ mark, children, key }) => { - return {children}; - }), - ]} -/>; -``` - -Note: if you override the rules for `inline_item`, `item_link` or `block` nodes, then the `renderInlineRecord`, `renderLinkToRecord` and `renderBlock` props won't be considered! - -## Props +# Documentation -| prop | type | required | description | default | -| ------------------ | --------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | -| data | `StructuredTextGraphQlResponse \| DastNode` | :white_check_mark: | The actual [field value](https://www.datocms.com/docs/structured-text/dast) you get from DatoCMS | | -| renderInlineRecord | `({ record }) => ReactElement \| null` | Only required if document contains `inlineItem` nodes | Convert an `inlineItem` DAST node into React | `[]` | -| renderLinkToRecord | `({ record, children }) => ReactElement \| null` | Only required if document contains `itemLink` nodes | Convert an `itemLink` DAST node into React | `null` | -| renderBlock | `({ record }) => ReactElement \| null` | Only required if document contains `block` nodes | Convert a `block` DAST node into React | `null` | -| metaTransformer | `({ node, meta }) => Object \| null` | :x: | Transform `link` and `itemLink` meta property into HTML props | [See function](https://github.com/datocms/structured-text/blob/main/packages/generic-html-renderer/src/index.ts#L61) | -| customNodeRules | `Array` | :x: | Customize how nodes are converted in JSX (use `renderNodeRule()` to generate rules) | `null` | -| customMarkRules | `Array` | :x: | Customize how marks are converted in JSX (use `renderMarkRule()` to generate rules) | `null` | -| renderText | `(text: string, key: string) => ReactElement \| string \| null` | :x: | Convert a simple string text into React | `(text) => text` | +This package offers different components and hooks. Please refer to one of the following pages to learn more about a specific area of interest: -# Site Search hook +* [`` component for responsive/progressive images](./docs/image.md) +* [`` component](./docs/structured-text.md) +* [`useQuerySubscription()` hook for live, real-time updates of content](./docs/live-real-time-updates.md) +* [`useSiteSearch()` hook to render a DatoCMS Site Search form widget](./docs/site-search.md) +* [`renderMetaTags()` and other helpers to render social share, SEO and Favicon meta tags](./docs/meta-tags.md) -`useSiteSearch` is a React hook that you can use to render a [DatoCMS Site Search](https://www.datocms.com/docs/site-search) widget. -The hook only handles the form logic: you are in complete and full control of how your form renders down to the very last component, class or style. +# Demos -To perform the necessary API requests, this hook requires a [DatoCMS CMA Client](https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients) instance, so make sure to also add the following package to your project: - -```bash -npm install --save @datocms/cma-client-browser -``` - -## Reference - -Import `useSiteSearch` from `react-datocms` and use it inside your components like this: - -```js -import { useSiteSearch } from 'react-datocms'; -import { buildClient } from '@datocms/cma-client-browser'; - -const client = buildClient({ apiToken: 'YOUR_API_TOKEN' }); - -const { state, error, data } = useSiteSearch({ - client, - initialState: { locale: 'en' }, - buildTriggerId: '7497', - resultsPerPage: 10, -}); -``` - -For a complete example, please refer to the [DatoCMS Site Search documentation page](https://www.datocms.com/docs/site-search/widget). - -## Initialization options - -| prop | type | required | description | default | -| ------------------- | ------------------------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | -| client | CMA Client instance | :x: | [DatoCMS CMA Client](https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients) instance | | -| buildTriggerId | string | :x: | The [ID of the build trigger](https://www.datocms.com/docs/site-search/base-integration#performing-searches) to use to find search results | | -| resultsPerPage | number | :white_check_mark: | The number of search results to show per page | 8 | -| highlightMatch | (match, key, context: 'title' \| 'bodyExcerpt') => React.ReactNode | :white_check_mark: | A function specifying how to highlight the part of page title/content that matches the query | (text, key) => (<mark key={key}>{text}</mark>) | -| initialState.query | string | :white_check_mark: | Initialize the form with a specific query | '' | -| initialState.locale | string | :white_check_mark: | Initialize the form starting from a specific page | 0 | -| initialState.page | string | :white_check_mark: | Initialize the form with a specific locale selected | null | - -## Returned data - -The hook returns an object with the following shape: - -```typescript -{ - state: { - query: string; - setQuery: (newQuery: string) => void; - locale: string | undefined; - setLocale: (newLocale: string) => void; - page: number; - setPage: (newPage: number) => void; - }, - error?: string, - data?: { - pageResults: Array<{ - id: string; - title: React.ReactNode; - bodyExcerpt: React.ReactNode; - url: string; - raw: RawSearchResult; - }>; - totalResults: number; - totalPages: number; - }, -} -``` - -- The `state` property reflects the current state of the form (the current `query`, `page`, and `locale`), and offers a number of functions to change the state itself. As soon as the state of the form changes, a new API request is made to fetch the new search results; -- The `error` property returns a string in case of failure of any API request; -- The `data` property returns all the information regarding the current search results to present to the user; +For fully working examples take a look at our [examples directory](https://github.com/datocms/react-datocms/tree/master/examples). -If both `error` and `data` are `null`, it means that the current state for the form is loading, and a spinner should be shown to the end user. +Live demo: [https://react-datocms-example.netlify.com/](https://react-datocms-example.netlify.com/) # Development diff --git a/docs/image.md b/docs/image.md new file mode 100644 index 0000000..3b0d8db --- /dev/null +++ b/docs/image.md @@ -0,0 +1,176 @@ + + +# `` component for progressive/responsive images + +`` is a React component specially designed to work seamlessly with DatoCMS’s [`responsiveImage` GraphQL query](https://www.datocms.com/docs/content-delivery-api/uploads#responsive-images) that optimizes image loading for your sites. + +- TypeScript ready; +- CSS-in-JS ready; +- Usable both client and server side; +- Compatible with vanilla React, Next.js and pretty much any other React-based solution; + +![](docs/image-component.gif?raw=true) + +## Table of Contents + + + +**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +- [Out-of-the-box features](#out-of-the-box-features) +- [Installation](#installation) +- [Intersection Observer](#intersection-observer) +- [Usage](#usage) +- [Example](#example) +- [Props](#props) + - [Layout mode](#layout-mode) + - [The `ResponsiveImage` object](#the-responsiveimage-object) + + + + + +## Out-of-the-box features + +- Offers WebP version of images for browsers that support the format +- Generates multiple smaller images so smartphones and tablets don’t download desktop-sized images +- Efficiently lazy loads images to speed initial page load and save bandwidth +- Holds the image position so your page doesn’t jump while images load +- Uses either blur-up or background color techniques to show a preview of the image while it loads + +## Installation + +``` +npm install --save react-datocms +``` + +## Intersection Observer + +Intersection Observer is the API used to determine if the image is inside the viewport or not. [Browser support is really good](https://caniuse.com/intersectionobserver) - With Safari adding support in 12.1, all major browsers now support Intersection Observers natively. + +If the IntersectionObserver object is not available, the component treats the image as it's always visible in the viewport. Feel free to add a [polyfill](https://www.npmjs.com/package/intersection-observer) so that it will also 100% work on older versions of iOS and IE11. + +## Usage + +1. Import `Image` from `react-datocms` and use it in place of the regular `` tag +2. Write a GraphQL query to your DatoCMS project using the [`responsiveImage` query](https://www.datocms.com/docs/content-delivery-api/images-and-videos#responsive-images) + +The GraphQL query returns multiple thumbnails with optimized compression. The `Image` component automatically sets up the “blur-up” effect as well as lazy loading of images further down the screen. + +## Example + +For a fully working example take a look at our [examples directory](https://github.com/datocms/react-datocms/tree/master/examples). + +```js +import React from 'react'; +import { Image } from 'react-datocms'; + +const Page = ({ data }) => ( +
+

{data.blogPost.title}

+ +
+); + +const query = gql` + query { + blogPost { + title + cover { + responsiveImage( + imgixParams: { fit: crop, w: 300, h: 300, auto: format } + ) { + # HTML5 src/srcset/sizes attributes + srcSet + webpSrcSet + sizes + src + + # size information (post-transformations) + width + height + aspectRatio + + # SEO attributes + alt + title + + # background color placeholder or... + bgColor + + # blur-up placeholder, JPEG format, base64-encoded + base64 + } + } + } + } +`; + +export default withQuery(query)(Page); +``` + +## Props + +| prop | type | required | description | default | +| --------------------- | ------------------------------------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | +| data | `ResponsiveImage` object | :white_check_mark: | The actual response you get from a DatoCMS `responsiveImage` GraphQL query | | +| layout | 'intrinsic' \| 'fixed' \| 'responsive' \| 'fill' | :x: | The layout behavior of the image as the viewport changes size | "intrinsic" | +| className | string | :x: | Additional CSS className for root node | null | +| style | CSS properties | :x: | Additional CSS rules to add to the root node | null | +| pictureClassName | string | :x: | Additional CSS class for the image inside the inner `` tag | null | +| pictureStyle | CSS properties | :x: | Additional CSS rules to add to the image inside the inner `` tag | null | +| fadeInDuration | integer | :x: | Duration (in ms) of the fade-in transition effect upoad image loading | 500 | +| intersectionThreshold | float | :x: | Indicate at what percentage of the placeholder visibility the loading of the image should be triggered. A value of 0 means that as soon as even one pixel is visible, the callback will be run. A value of 1.0 means that the threshold isn't considered passed until every pixel is visible. | 0 | +| intersectionMargin | string | :x: | Margin around the placeholder. Can have values similar to the CSS margin property (top, right, bottom, left). The values can be percentages. This set of values serves to grow or shrink each side of the placeholder element's bounding box before computing intersections. | "0px 0px 0px 0px" | +| lazyLoad | Boolean | :x: | Whether enable lazy loading or not | true | +| onLoad | () => void | :x: | Function triggered when the image has finished loading | undefined | +| usePlaceholder | Boolean | :x: | Whether the component should use a blurred image placeholder | true | + +### Layout mode + +With the `layout` property, you can configure the behavior of the image as the viewport changes size: + +- When `intrinsic` (default behaviour), the image will scale the dimensions down for smaller viewports, but maintain the original dimensions for larger viewports. +- When `fixed`, the image dimensions will not change as the viewport changes (no responsiveness) similar to the native `img` element. +- When `responsive`, the image will scale the dimensions down for smaller viewports and scale up for larger viewports. +- When `fill`, the image will stretch both width and height to the dimensions of the parent element, provided the parent element is relative. + - This is usually paired with the `objectFit` and `objectPosition` properties. + - Ensure the parent element has `position: relative` in their stylesheet. + +Example for `layout="fill"` (useful also for background images): + +```jsx +
+ +
+``` + +### The `ResponsiveImage` object + +The `data` prop expects an object with the same shape as the one returned by `responsiveImage` GraphQL call. It's up to you to make a GraphQL query that will return the properties you need for a specific use of the `` component. + +- The minimum required properties for `data` are: `aspectRatio`, `width`, `sizes`, `srcSet` and `src`; +- `alt` and `title`, while not mandatory, are all highly suggested, so remember to use them! +- You either want to add the `webpSrcSet` field or specify `{ auto: format }` in your `imgixParams`, to automatically use WebP images in browsers that support the format; +- If you provide both the `bgColor` and `base64` property, the latter will take precedence, so just avoiding querying both fields at the same time, it will only make the response bigger :wink: + +Here's a complete recap of what `responsiveImage` offers: + +| property | type | required | description | +| ----------- | ------- | ------------------ | ----------------------------------------------------------------------------------------------- | +| aspectRatio | float | :white_check_mark: | The aspect ratio (width/height) of the image | +| width | integer | :white_check_mark: | The width of the image | +| height | integer | :white_check_mark: | The height of the image | +| sizes | string | :white_check_mark: | The HTML5 `sizes` attribute for the image | +| srcSet | string | :white_check_mark: | The HTML5 `srcSet` attribute for the image | +| src | string | :white_check_mark: | The fallback `src` attribute for the image | +| webpSrcSet | string | :x: | The HTML5 `srcSet` attribute for the image in WebP format, for browsers that support the format | +| alt | string | :x: | Alternate text (`alt`) for the image | +| title | string | :x: | Title attribute (`title`) for the image | +| bgColor | string | :x: | The background color for the image placeholder | +| base64 | string | :x: | A base64-encoded thumbnail to offer during image loading | diff --git a/docs/live-real-time-updates.md b/docs/live-real-time-updates.md new file mode 100644 index 0000000..24c633f --- /dev/null +++ b/docs/live-real-time-updates.md @@ -0,0 +1,123 @@ +# Live real-time updates + +`useQuerySubscription` is a React hook that you can use to implement client-side updates of the page as soon as the content changes. It uses DatoCMS's [Real-time Updates API](https://www.datocms.com/docs/real-time-updates-api/api-reference) to receive the updated query results in real-time, and is able to reconnect in case of network failures. + +Live updates are great both to get instant previews of your content while editing it inside DatoCMS, or to offer real-time updates of content to your visitors (ie. news site). + +- TypeScript ready; +- Compatible with vanilla React, Next.js and pretty much any other React-based solution; + +## Table of Contents + + + +**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +- [Installation](#installation) +- [Reference](#reference) +- [Initialization options](#initialization-options) +- [Connection status](#connection-status) +- [Error object](#error-object) +- [Example](#example) + + + +## Installation + +``` +npm install --save react-datocms +``` + +## Reference + +Import `useQuerySubscription` from `react-datocms` and use it inside your components like this: + +```js +const { + data: QueryResult | undefined, + error: ChannelErrorData | null, + status: ConnectionStatus, +} = useQuerySubscription(options: Options); +``` + +## Initialization options + +| prop | type | required | description | default | +| ------------------ | ----------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------ | ------------------------------------ | +| enabled | boolean | :x: | Whether the subscription has to be performed or not | true | +| query | string | :white_check_mark: | The GraphQL query to subscribe | | +| token | string | :white_check_mark: | DatoCMS API token to use | | +| variables | Object | :x: | GraphQL variables for the query | | +| preview | boolean | :x: | If true, the Content Delivery API with draft content will be used | false | +| environment | string | :x: | The name of the DatoCMS environment where to perform the query | defaults to primary environment | +| initialData | Object | :x: | The initial data to use on the first render | | +| reconnectionPeriod | number | :x: | In case of network errors, the period (in ms) to wait to reconnect | 1000 | +| fetcher | a [fetch-like function](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) | :x: | The fetch function to use to perform the registration query | window.fetch | +| eventSourceClass | an [EventSource-like](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) class | :x: | The EventSource class to use to open up the SSE connection | window.EventSource | +| baseUrl | string | :x: | The base URL to use to perform the query | `https://graphql-listen.datocms.com` | + +## Connection status + +The `status` property represents the state of the server-sent events connection. It can be one of the following: + +- `connecting`: the subscription channel is trying to connect +- `connected`: the channel is open, we're receiving live updates +- `closed`: the channel has been permanently closed due to a fatal error (ie. an invalid query) + +## Error object + +| prop | type | description | +| -------- | ------ | ------------------------------------------------------- | +| code | string | The code of the error (ie. `INVALID_QUERY`) | +| message | string | An human friendly message explaining the error | +| response | Object | The raw response returned by the endpoint, if available | + +## Example + +```js +import React from 'react'; +import { useQuerySubscription } from 'react-datocms'; + +const App: React.FC = () => { + const { status, error, data } = useQuerySubscription({ + enabled: true, + query: ` + query AppQuery($first: IntType) { + allBlogPosts { + slug + title + } + }`, + variables: { first: 10 }, + token: 'YOUR_API_TOKEN', + }); + + const statusMessage = { + connecting: 'Connecting to DatoCMS...', + connected: 'Connected to DatoCMS, receiving live updates!', + closed: 'Connection closed', + }; + + return ( +
+

Connection status: {statusMessage[status]}

+ {error && ( +
+

Error: {error.code}

+
{error.message}
+ {error.response && ( + 
{JSON.stringify(error.response, null, 2)}
+ )} +
+ )} + {data && ( +
    + {data.allBlogPosts.map((blogPost) => ( +
  • {blogPost.title}
    • + ))} +
+ )} +
+ ); +}; +``` \ No newline at end of file diff --git a/docs/meta-tags.md b/docs/meta-tags.md new file mode 100644 index 0000000..45c3b9d --- /dev/null +++ b/docs/meta-tags.md @@ -0,0 +1,151 @@ +# Social share, SEO and Favicon meta tags + +Just like for the [image component](./image.md) this package offers a number of utilities designed to work seamlessly with DatoCMS’s [`_seoMetaTags` and `faviconMetaTags` GraphQL queries](https://www.datocms.com/docs/content-delivery-api/seo) so that you can easily handle SEO, social shares and favicons in your pages. + +## Table of Contents + + + +**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +- [Installation](#installation) +- [General usage](#general-usage) +- [`renderMetaTags()`](#rendermetatags) +- [`renderMetaTagsToString()`](#rendermetatagstostring) +- [`toRemixMeta()`](#toremixmeta) + + + + +## Installation + +``` +npm install --save react-datocms +``` + +## General usage + +All the utilities take an array of `SeoOrFaviconTag`s in the exact form they're returned by the following [DatoCMS GraphQL API queries](https://www.datocms.com/docs/content-delivery-api/seo): + +- `_seoMetaTags` (always available on any type of record) +- `faviconMetaTags` on the global `_site` object. + +```graphql +query { + page: homepage { + title + seo: _seoMetaTags { + attributes + content + tag + } + } + + site: _site { + favicon: faviconMetaTags { + attributes + content + tag + } + } +} +``` + +You can then concat those two arrays of tags and pass them togheter to the function, ie: + +```js +renderMetaTags([...data.page.seo, ...data.site.favicon]); +``` + +## `renderMetaTags()` + +This function generates React `` and `` elements, so it is compatible with React packages like [`react-helmet`](https://www.npmjs.com/package/react-helmet). + +For a complete example take a look at our [examples directory](https://github.com/datocms/react-datocms/tree/master/examples). + +```js +import React from 'react'; +import { renderMetaTags } from 'react-datocms'; + +function Page({ data }) { + return ( +
+ + {renderMetaTags([...data.page.seo, ...data.site.favicon])} + +
+ ); +} +``` + +## `renderMetaTagsToString()` + +This function generates an HTML string containing `` and `` tags, so it can be used server-side. + +```js +import { renderMetaTagsToString } from 'react-datocms'; + +const someMoreComplexHtml = ` + + + ${renderMetaTagsToString([...data.page.seo, ...data.site.favicon])} + + +`; +``` + +## `toRemixMeta()` + +This function generates a `HtmlMetaDescriptor` object, compatibile with the [`meta`](https://remix.run/docs/en/v1.1.1/api/conventions#meta) export of the [Remix](https://remix.run/) framework: + +```js +import type { MetaFunction } from 'remix'; +import { toRemixMeta } from 'react-datocms'; + +export const meta: MetaFunction = ({ data: { post } }) => { + return toRemixMeta(post.seo); +}; +``` + +Please note that the [`links`](https://remix.run/docs/en/v1.1.1/api/conventions#links) export [doesn't receive any loader data](https://github.com/remix-run/remix/issues/32) for performance reasons, so you cannot use it to declare favicons meta tags! The best way to render them is using `renderMetaTags` in your root component: + +```jsx +import { renderMetaTags } from 'react-datocms'; + +export const loader = () => { + return request({ + query: ` + { + site: _site { + favicon: faviconMetaTags(variants: [icon, msApplication, appleTouchIcon]) { + ...metaTagsFragment + } + } + } + ${metaTagsFragment} + `, + }); +}; + +export default function App() { + const { site } = useLoaderData(); + + return ( + + + + + + + {renderMetaTags(site.favicon)} + + + + + + {process.env.NODE_ENV === 'development' && } + + + ); +} +``` \ No newline at end of file diff --git a/docs/site-search.md b/docs/site-search.md new file mode 100644 index 0000000..d9ff04e --- /dev/null +++ b/docs/site-search.md @@ -0,0 +1,174 @@ +# Site Search hook + +`useSiteSearch` is a React hook that you can use to render a [DatoCMS Site Search](https://www.datocms.com/docs/site-search) widget. +The hook only handles the form logic: you are in complete and full control of how your form renders down to the very last component, class or style. + +## Table of Contents + + + + +- [Installation](#installation) +- [Reference](#reference) +- [Initialization options](#initialization-options) +- [Returned data](#returned-data) +- [Complete example](#complete-example) + + + +## Installation + +To perform the necessary API requests, this hook requires a [DatoCMS CMA Client](https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients) instance, so make sure to also add the following package to your project: + +```bash +npm install --save react-datocms @datocms/cma-client-browser +``` + +## Reference + +Import `useSiteSearch` from `react-datocms` and use it inside your components like this: + +```js +import { useSiteSearch } from 'react-datocms'; +import { buildClient } from '@datocms/cma-client-browser'; + +const client = buildClient({ apiToken: 'YOUR_API_TOKEN' }); + +const { state, error, data } = useSiteSearch({ + client, + initialState: { locale: 'en' }, + buildTriggerId: '7497', + resultsPerPage: 10, +}); +``` + +For a complete walk-through, please refer to the [DatoCMS Site Search documentation](https://www.datocms.com/docs/site-search). + +## Initialization options + +| prop | type | required | description | default | +| ------------------- | ------------------------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- | +| client | CMA Client instance | :white_check_mark: | [DatoCMS CMA Client](https://www.datocms.com/docs/content-management-api/using-the-nodejs-clients) instance | | +| buildTriggerId | string | :white_check_mark: | The [ID of the build trigger](https://www.datocms.com/docs/site-search/base-integration#performing-searches) to use to find search results | | +| resultsPerPage | number | :x: | The number of search results to show per page | 8 | +| highlightMatch | (match, key, context: 'title' \| 'bodyExcerpt') => React.ReactNode | :x: | A function specifying how to highlight the part of page title/content that matches the query | (text, key) => (<mark key={key}>{text}</mark>) | +| initialState.query | string | :x: | Initialize the form with a specific query | '' | +| initialState.locale | string | :x: | Initialize the form starting from a specific page | 0 | +| initialState.page | string | :x: | Initialize the form with a specific locale selected | null | + +## Returned data + +The hook returns an object with the following shape: + +```typescript +{ + state: { + query: string; + setQuery: (newQuery: string) => void; + locale: string | undefined; + setLocale: (newLocale: string) => void; + page: number; + setPage: (newPage: number) => void; + }, + error?: string, + data?: { + pageResults: Array<{ + id: string; + title: React.ReactNode; + bodyExcerpt: React.ReactNode; + url: string; + raw: RawSearchResult; + }>; + totalResults: number; + totalPages: number; + }, +} +``` + +- The `state` property reflects the current state of the form (the current `query`, `page`, and `locale`), and offers a number of functions to change the state itself. As soon as the state of the form changes, a new API request is made to fetch the new search results; +- The `error` property returns a string in case of failure of any API request; +- The `data` property returns all the information regarding the current search results to present to the user; + +If both `error` and `data` are `null`, it means that the current state for the form is loading, and a spinner should be shown to the end user. + +## Complete example + +This example uses the [`react-paginate`](https://www.npmjs.com/package/react-paginate) npm package to simplify the handling of pagination: + +```jsx +import { buildClient } from '@datocms/cma-client-browser'; +import ReactPaginate from 'react-paginate'; +import { useSiteSearch } from 'react-datocms'; +import { useState } from 'react'; + +const client = buildClient({ apiToken: 'YOUR_API_TOKEN' }); + +function App() { + const [query, setQuery] = useState(''); + + const { state, error, data } = useSiteSearch({ + client, + buildTriggerId: '7497', + // optional: you can omit it you only have one locale, or you want to find results in every locale + initialState: { locale: 'en' }, + // optional: to configure how to present the part of page title/content that matches the query + highlightMatch: (text, key, context) => + context === 'title' ? ( + {text} + ) : ( + {text} + ), + // optional: defaults to 8 search results per page + resultsPerPage: 10, + }); + + return ( + + ); +} +``` diff --git a/docs/structured-text.md b/docs/structured-text.md new file mode 100644 index 0000000..119d2a6 --- /dev/null +++ b/docs/structured-text.md @@ -0,0 +1,333 @@ + + + +# Structured text + +`` is a React component that you can use to render the value contained inside a DatoCMS [Structured Text field type](https://www.datocms.com/docs/structured-text/dast). + +## Table of Contents + + + +**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)* + +- [Installation](#installation) +- [Basic usage](#basic-usage) +- [Custom renderers for inline records, blocks, and links](#custom-renderers-for-inline-records-blocks-and-links) +- [Override default rendering of nodes](#override-default-rendering-of-nodes) +- [Props](#props) + + + + +## Installation + +``` +npm install --save react-datocms +``` + +## Basic usage + +```js +import React from 'react'; +import { StructuredText } from 'react-datocms'; + +const Page = ({ data }) => { + // data.blogPost.content = { + // value: { + // schema: "dast", + // document: { + // type: "root", + // children: [ + // { + // type: "heading", + // level: 1, + // children: [ + // { + // type: "span", + // value: "Hello ", + // }, + // { + // type: "span", + // marks: ["strong"], + // value: "world!", + // }, + // ], + // }, + // ], + // }, + // }, + // } + + return ( +
+

{data.blogPost.title}

+ + {/* ->

Hello world!

*/} +
+ ); +}; + +const query = gql` + query { + blogPost { + title + content { + value + } + } + } +`; + +export default withQuery(query)(Page); +``` + +## Custom renderers for inline records, blocks, and links + +You can also pass custom renderers for special nodes (inline records, record links and blocks) as an optional parameter like so: + +```js +import React from 'react'; +import { StructuredText, Image } from 'react-datocms'; + +const Page = ({ data }) => { + // data.blogPost.content -> + // { + // value: { + // schema: "dast", + // document: { + // type: "root", + // children: [ + // { + // type: "heading", + // level: 1, + // children: [ + // { type: "span", value: "Welcome onboard " }, + // { type: "inlineItem", item: "324321" }, + // ], + // }, + // { + // type: "paragraph", + // children: [ + // { type: "span", value: "So happy to have " }, + // { + // type: "itemLink", + // item: "324321", + // children: [ + // { + // type: "span", + // marks: ["strong"], + // value: "this awesome humang being", + // }, + // ] + // }, + // { type: "span", value: " in our team!" }, + // ] + // }, + // { type: "block", item: "1984559" } + // ], + // }, + // }, + // links: [ + // { + // id: "324321", + // __typename: "TeamMemberRecord", + // firstName: "Mark", + // slug: "mark-smith", + // }, + // ], + // blocks: [ + // { + // id: "324321", + // __typename: "ImageRecord", + // image: { + // responsiveImage: { ... }, + // }, + // }, + // ], + // } + + return ( +
+

{data.blogPost.title}

+ { + switch (record.__typename) { + case 'TeamMemberRecord': + return {record.firstName}; + default: + return null; + } + }} + renderLinkToRecord={({ record, children, transformedMeta }) => { + switch (record.__typename) { + case 'TeamMemberRecord': + return ( + + {children} + + ); + default: + return null; + } + }} + renderBlock={({ record }) => { + switch (record.__typename) { + case 'ImageRecord': + return ; + default: + return null; + } + }} + /> + {/* + Final result: + +

Welcome onboard Mark

+

So happy to have this awesome humang being in our team!

+ Our team at work + */} +
+ ); +}; + +const query = gql` + query { + blogPost { + title + content { + value + links { + __typename + ... on TeamMemberRecord { + id + firstName + slug + } + } + blocks { + __typename + ... on ImageRecord { + id + image { + responsiveImage( + imgixParams: { fit: crop, w: 300, h: 300, auto: format } + ) { + srcSet + webpSrcSet + sizes + src + width + height + aspectRatio + alt + title + base64 + } + } + } + } + } + } + } +`; + +export default withQuery(query)(Page); +``` + +## Override default rendering of nodes + +This component automatically renders all nodes except for `inline_item`, `item_link` and `block` using a set of default rules, but you might want to customize those. For example: + +For example: + +- For `heading` nodes, you might want to add an anchor; +- For `code` nodes, you might want to use a custom sytax highlighting component like [`prism-react-renderer`](https://github.com/FormidableLabs/prism-react-renderer); +- Apply different logic/formatting to a node based on what its parent node is (using the `ancestors` parameter) + +- For all possible node types, refer to the [list of typeguard functions defined in the main `structured-text` package](https://github.com/datocms/structured-text/tree/main/packages/utils#typescript-type-guards). The [DAST format documentation](https://www.datocms.com/docs/structured-text/dast) has additional details. + +In this case, you can easily override default rendering rules with the `customNodeRules` and `customMarkRules` props. + +```jsx +import { renderNodeRule, renderMarkRule, StructuredText } from 'react-datocms'; +import { isHeading, isCode } from 'datocms-structured-text-utils'; +import { render as toPlainText } from 'datocms-structured-text-to-plain-text'; +import SyntaxHighlight from 'components/SyntaxHighlight'; + + { + const HeadingTag = `h${node.level}`; + const anchor = toPlainText(node) + .toLowerCase() + .replace(/ /g, '-') + .replace(/[^\w-]+/g, ''); + + return ( + + {children} + + + ); + }), + + // Use a custom syntax highlighter component for code blocks + renderNodeRule(isCode, ({ node, key }) => { + return ( + + ); + }), + + // Apply different formatting to top-level paragraphs + renderNodeRule( + isParagraph, + ({ adapter: { renderNode }, node, children, key, ancestors }) => { + if (isRoot(ancestors[0])) { + // If this paragraph node is a top-level one, give it a special class + return renderNode( + 'p', + { key, className: 'top-level-paragraph-container-example' }, + children, + ); + } else { + // Proceed with default paragraph rendering... + // return renderNode('p', { key }, children); + + // Or even completely remove the paragraph and directly render the inner children: + return children; + } + }, + ), + ]} + customMarkRules={[ + // convert "strong" marks into tags + renderMarkRule('strong', ({ mark, children, key }) => { + return {children}; + }), + ]} +/>; +``` + +Note: if you override the rules for `inline_item`, `item_link` or `block` nodes, then the `renderInlineRecord`, `renderLinkToRecord` and `renderBlock` props won't be considered! + +## Props + +| prop | type | required | description | default | +| ------------------ | --------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- | +| data | `StructuredTextGraphQlResponse \| DastNode` | :white_check_mark: | The actual [field value](https://www.datocms.com/docs/structured-text/dast) you get from DatoCMS | | +| renderInlineRecord | `({ record }) => ReactElement \| null` | Only required if document contains `inlineItem` nodes | Convert an `inlineItem` DAST node into React | `[]` | +| renderLinkToRecord | `({ record, children }) => ReactElement \| null` | Only required if document contains `itemLink` nodes | Convert an `itemLink` DAST node into React | `null` | +| renderBlock | `({ record }) => ReactElement \| null` | Only required if document contains `block` nodes | Convert a `block` DAST node into React | `null` | +| metaTransformer | `({ node, meta }) => Object \| null` | :x: | Transform `link` and `itemLink` meta property into HTML props | [See function](https://github.com/datocms/structured-text/blob/main/packages/generic-html-renderer/src/index.ts#L61) | +| customNodeRules | `Array` | :x: | Customize how nodes are converted in JSX (use `renderNodeRule()` to generate rules) | `null` | +| customMarkRules | `Array` | :x: | Customize how marks are converted in JSX (use `renderMarkRule()` to generate rules) | `null` | +| renderText | `(text: string, key: string) => ReactElement \| string \| null` | :x: | Convert a simple string text into React | `(text) => text` | diff --git a/package.json b/package.json index 9d1494b..fd8abb0 100644 --- a/package.json +++ b/package.json @@ -43,7 +43,7 @@ "watch": "rimraf dist && tsc --watch", "prepare": "npm run test && npm run build", "test": "jest --coverage", - "toc": "doctoc README.md" + "toc": "doctoc --github docs" }, "peerDependencies": { "react": ">= 16.12.0"