From ba15a01421d7cfdc64b459601055c8e1d1f94bf6 Mon Sep 17 00:00:00 2001 From: Angelo Ashmore Date: Tue, 27 Jul 2021 15:06:46 -1000 Subject: [PATCH] docs: add documentation to all exports --- src/PrismicLink.tsx | 67 +++++++++++++++++++++++++++++++++++++++- src/PrismicProvider.tsx | 67 +++++++++++++++++++++++++++++++++++++++- src/PrismicRichText.tsx | 12 +++---- src/PrismicText.tsx | 33 ++++++++++++++++---- src/PrismicToolbar.tsx | 33 ++++++++++++++------ src/SliceZone.tsx | 6 ++++ src/createClientHook.ts | 9 ++++++ src/lib/isInternalURL.ts | 8 +++++ src/types.ts | 21 +++++-------- src/usePrismicClient.ts | 7 +++++ 10 files changed, 226 insertions(+), 37 deletions(-) diff --git a/src/PrismicLink.tsx b/src/PrismicLink.tsx index 6405246..42fe02b 100644 --- a/src/PrismicLink.tsx +++ b/src/PrismicLink.tsx @@ -6,25 +6,90 @@ import { isInternalURL } from "./lib/isInternalURL"; import { usePrismicContext } from "./PrismicProvider"; +/** + * Props provided to a component when rendered with ``. + */ export interface LinkProps { + /** The URL to link. */ href: string; + + /** The `target` attribute for anchor elements. If the Prismic field is configured to open in a new window, this prop defaults to `_blank`. */ target?: string; + + /** The `rel` attribute for anchor elements. If the `target` prop is set to `"_blank"`, this prop defaults to `"noopener noreferrer"`. */ rel?: string; + + /** Children for the component. **/ children?: React.ReactNode; } +/** + * Props for ``. + */ export type PrismicLinkProps = { + /** + * The Link Resolver used to resolve links. + * + * @remarks If your app uses Route Resolvers when querying for your Prismic repository's content, a Link Resolver does not need to be provided. + * + * @see Learn about Link Resolvers and Route Resolvers {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver} + */ linkResolver?: prismicH.LinkResolverFunction; + + /** + * The component rendered for internal URLs. Defaults to ``. + * + * If your app uses a client-side router that requires a special Link component, provide the Link component to this prop. + */ internalComponent?: string | React.ComponentType; + + /** The component rendered for external URLs. Defaults to ``. */ externalComponent?: string | React.ComponentType; + + /** The `target` attribute for anchor elements. If the Prismic field is configured to open in a new window, this prop defaults to `_blank`. */ target?: string; + + /** The `rel` attribute for anchor elements. If the `target` prop is set to `"_blank"`, this prop defaults to `"noopener noreferrer"`. */ rel?: string; + + /** Children for the component. **/ children?: React.ReactNode; -} & ({ field: prismicT.LinkField } | { href: string }); +} & ( + | { + /** + * The Prismic Link field containing the URL or document to link. + * + * @see Learn about Prismic Link fields {@link https://prismic.io/docs/core-concepts/link-content-relationship} + */ + field: prismicT.LinkField; + } + | { + /** The URL to link. */ + href: string; + } +); +/** + * The default component rendered for internal URLs. + */ const defaultInternalComponent = "a"; + +/** + * The default component rendered for external URLs. + */ const defaultExternalComponent = "a"; +/** + * React component to render a link from a Prismic Link field. + * + * Different components can be rendered depending on whether the link is internal or external. This is helpful when integrating with client-side routers, such as a router-specific Link component. + * + * If a link is configured to open in a new window using `target="_blank"`, `rel="noopener noreferrer"` is set by default. + * + * @param props Props for the component. + * + * @returns The internal or external link component depending on whether the link is internal or external. + */ export const PrismicLink = (props: PrismicLinkProps): JSX.Element => { const context = usePrismicContext(); diff --git a/src/PrismicProvider.tsx b/src/PrismicProvider.tsx index efd653e..c141bff 100644 --- a/src/PrismicProvider.tsx +++ b/src/PrismicProvider.tsx @@ -3,24 +3,89 @@ import * as prismic from "@prismicio/client"; import * as prismicH from "@prismicio/helpers"; import { LinkProps } from "./PrismicLink"; +import { JSXFunctionSerializer, JSXMapSerializer } from "./types"; +/** + * React context value containing shared configuration for `@prismicio/react` components and hooks. + */ export type PrismicContextValue = { + /** + * A `@prismicio/client` instance used to fetch content from a Prismic repository. This is used by `@prismicio/react` hooks, such as `usePrismicDocuments()`. + */ client?: prismic.Client; + + /** + * A Link Resolver used to resolve links for `` and ``. + * + * @remarks If your app uses Route Resolvers when querying for your Prismic repository's content, a Link Resolver does not need to be provided. + * + * @see Learn about Link Resolvers and Route Resolvers {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver} + */ linkResolver?: prismicH.LinkResolverFunction; - richTextComponents?: Record; + + /** + * A map or function that maps a Rich Text block to a React component. + * + * @remarks Prefer using a map serializer over the function serializer when possible. The map serializer is simpler to maintain. + * + * @example + * A map serializer. + * + * ```ts + * { + * heading1: ({children}) => {children} + * } + * ``` + * + * @example + * A function serializer. + * + * ```ts + * (type, node, content, children) => { + * switch (type) { + * case 'heading1': { + * return {chidlren} + * } + * } + * } + * ``` + */ + richTextComponents?: JSXMapSerializer | JSXFunctionSerializer; + + /** The component rendered by `` for internal URLs. Defaults to ``. */ internalLinkComponent?: string | React.ComponentType; + + /** The component rendered by `` for external URLs. Defaults to ``. */ externalLinkComponent?: string | React.ComponentType; + + /** Children for the component. */ children?: React.ReactNode; }; +/** + * React context containing shared configuration for `@prismicio/react` components and hooks. + */ export const PrismicContext = React.createContext({}); +/** + * React hook used to read shared configuration for `@prismicio/react` components and hooks. + * + * @returns The closest `` context value. + */ export const usePrismicContext = (): PrismicContextValue => { return React.useContext(PrismicContext) || {}; }; +/** + * Props for ``. + */ type PrismicProviderProps = PrismicContextValue; +/** + * React context provider to share configuration for `@prismicio/react` components and hooks. + * + * @returns A React context provider with shared configuration. + */ export const PrismicProvider = ({ client, linkResolver, diff --git a/src/PrismicRichText.tsx b/src/PrismicRichText.tsx index 68b8390..0f2ef08 100644 --- a/src/PrismicRichText.tsx +++ b/src/PrismicRichText.tsx @@ -11,7 +11,7 @@ import * as React from "react"; import * as prismicH from "@prismicio/helpers"; import * as prismicT from "@prismicio/types"; import { usePrismicContext } from "./PrismicProvider"; -import { ComponentFunctionSerializer } from "./types"; +import { JSXFunctionSerializer } from "./types"; import { PrismicLink, PrismicLinkProps } from "./PrismicLink"; /** @@ -94,11 +94,11 @@ function defaultComponentSerializer( linkResolver: prismicH.LinkResolverFunction | undefined, internalLinkComponent: PrismicRichTextProps["internalLinkComponent"], externalLinkComponent: PrismicRichTextProps["externalLinkComponent"], - _type: Parameters[0], - node: Parameters[1], - content: Parameters[2], - children: Parameters[3], - _key: Parameters[4], + _type: Parameters[0], + node: Parameters[1], + content: Parameters[2], + children: Parameters[3], + _key: Parameters[4], ): JSX.Element { switch (node.type) { case Element.heading1: diff --git a/src/PrismicText.tsx b/src/PrismicText.tsx index 48a4adc..9001b93 100644 --- a/src/PrismicText.tsx +++ b/src/PrismicText.tsx @@ -1,16 +1,37 @@ import * as React from "react"; -import { useMemo } from "react"; -import { RichTextField } from "@prismicio/types"; -import { asText } from "@prismicio/helpers"; +import * as prismicT from "@prismicio/types"; +import * as prismicH from "@prismicio/helpers"; +/** + * Props for ``. + */ export type PrismicTextProps = { - field: RichTextField; + /** The Prismic Rich Text field to render. */ + field: prismicT.RichTextField; + + /** The separator used between blocks. Defaults to \n`. */ separator?: string; }; +/** + * React component that renders content from a Prismic Rich Text field as plain text. + * + * @remarks This component returns a React fragment with no wrapping element around the content. If you need a wrapper, add a component around ``. + * + * @see Learn about Rich Text fields {@link https://prismic.io/docs/core-concepts/rich-text-title} + * + * @example + * Rendering a Rich Text field as plain text. + * + * + * + * @param props Props for the component. + * + * @returns The Rich Text field's content as plain text. + */ export const PrismicText = (props: PrismicTextProps): JSX.Element => { - const text = useMemo( - () => asText(props.field, props.separator), + const text = React.useMemo( + () => prismicH.asText(props.field, props.separator), [props.field, props.separator], ); diff --git a/src/PrismicToolbar.tsx b/src/PrismicToolbar.tsx index 8032e20..51503f4 100644 --- a/src/PrismicToolbar.tsx +++ b/src/PrismicToolbar.tsx @@ -1,20 +1,35 @@ import * as React from "react"; +/** + * Props for ``. + */ export type PrismicToolbarProps = { + /** The name of the Prismic repository. For example, `"my-repo"` if the repository URL is `my-repo.prismic.io`. */ repositoryName: string; + + /** + * The type of toolbar needed for the repository. Defaults to `"new"`. + * + * @see To check which version you need, view the Prismic Toolbar documentation {@link https://prismic.io/docs/technologies/previews-and-the-prismic-toolbar-reactjs} + */ type?: "new" | "legacy"; }; +/** + * React component that injects the Prismic Toolbar to the app. This component can be placed anywhere in the React tree. + */ export const PrismicToolbar = ({ repositoryName, type = "new", -}: PrismicToolbarProps): JSX.Element => { - return ( -