@contember/react-client 1.0.0-rc.2 → 1.0.0-rc.22

package/readme.md

@@ -1,7 +1,9 @@
 # `@contember/react-client`
 
 ## Usage
+
 If you wish to communicate with any Contember API, wrap your code with the `ContemberClient` component:
+
 ```tsx
 import { ContemberClient } from '@contember/react-client'
 
@@ -11,12 +13,48 @@ import { ContemberClient } from '@contember/react-client'
 	sessionToken="SESSION-TOKEN"
 	stage="STAGE-SLUG"
 >
-  ...
+	...
 </ContemberClient>
 ```
 
 ## Notable APIs
+
 You'll have to look at the code for now, sorry.
+
 - `<RichTextRenderer />`
 - `useFileUpload`
 - `useContentApiRequest` / `useTenantApiRequest` / `useSystemApiRequest`
+
+## RichTextRenderer
+
+Here is simple exmaple of how to use the `RichTextRenderer` component with custom references and elements.
+
+```tsx
+import { RichTextRenderer } from '@contember/react-client'
+import Image from './myComponents/Image'
+import Gallery from './myComponents/Gallery'
+import Quote from './myComponents/Quote'
+import Link from './myComponents/Link'
+
+<RichTextRenderer
+	sourceField="json"
+	renderElement={(props) => {
+		if (props.element.type === 'link' && props.reference) {
+			return <Link label={props.element.children[0].text} url={props.reference.target} />
+		}
+
+		return props.fallback
+	}}
+	referenceRenderers={{
+		image: (reference) => <Image reference={reference} />,
+		gallery: (reference) => <Gallery reference={reference} />,
+		quote: (reference) => <Quote reference={reference} />,
+	}}
+/>
+```
+
+| Prop                 | Description                                           |
+| -------------------- | ----------------------------------------------------- |
+| `sourceField`        | The field in the GraphQL that contains the rich text. |
+| `renderElement`      | Function that renders an element.                     |
+| `referenceRenderers` | Object that maps reference types to renderers.        |

package/src/ClientError.ts

@@ -0,0 +1 @@
+export class ClientError extends Error {}

package/src/ContemberClient.tsx

@@ -0,0 +1,48 @@
+import { memo, useCallback, useEffect, useState } from 'react'
+import { SessionTokenContext, SetSessionTokenContext } from './auth'
+import { ApiBaseUrlContext, LoginTokenContext } from './config'
+import { ProjectSlugContext, StageSlugContext } from './project'
+
+export interface ContemberClientProps {
+	apiBaseUrl: string
+	sessionToken?: string
+	loginToken?: string
+	project?: string
+	stage?: string
+}
+
+const sessionTokenKey = 'contember_session_token'
+
+export const ContemberClient = memo<ContemberClientProps & { children: React.ReactNode }>(function ContemberClient({
+	apiBaseUrl,
+	children,
+	loginToken,
+	project,
+	sessionToken,
+	stage,
+}) {
+	const [sessionTokenInner, setSessionTokenInner] = useState(() => localStorage.getItem(sessionTokenKey) ?? sessionToken  ?? undefined)
+
+	const setSessionToken = useCallback((token: string | undefined) => {
+		if (token !== undefined) {
+			localStorage.setItem(sessionTokenKey, token)
+		} else {
+			localStorage.removeItem(sessionTokenKey)
+		}
+		setSessionTokenInner(token)
+	}, [])
+
+	return (
+		<ApiBaseUrlContext.Provider value={apiBaseUrl}>
+			<LoginTokenContext.Provider value={loginToken}>
+				<SetSessionTokenContext.Provider value={setSessionToken}>
+					<SessionTokenContext.Provider value={sessionTokenInner}>
+						<ProjectSlugContext.Provider value={project}>
+							<StageSlugContext.Provider value={stage}>{children}</StageSlugContext.Provider>
+						</ProjectSlugContext.Provider>
+					</SessionTokenContext.Provider>
+				</SetSessionTokenContext.Provider>
+			</LoginTokenContext.Provider>
+		</ApiBaseUrlContext.Provider>
+	)
+})

package/src/ambient.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/src/apiRequest/ApiRequestAction.ts

@@ -0,0 +1,17 @@
+import type { GraphQlClientFailedRequestMetadata } from '@contember/client'
+
+export type ApiRequestAction<SuccessData> =
+	| {
+			type: 'uninitialize'
+	  }
+	| {
+			type: 'initialize'
+	  }
+	| {
+			type: 'resolveSuccessfully'
+			data: SuccessData
+	  }
+	| {
+			type: 'resolveWithError'
+			error: GraphQlClientFailedRequestMetadata
+	  }

package/src/apiRequest/ApiRequestState.ts

@@ -0,0 +1,25 @@
+import type { GraphQlClientFailedRequestMetadata } from '@contember/client'
+
+export type ApiRequestState<SuccessData> =
+	| {
+			isLoading: false
+			isFinished: false
+			readyState: 'uninitialized'
+	  }
+	| {
+			isLoading: true
+			isFinished: false
+			readyState: 'pending'
+	  }
+	| {
+			isLoading: false
+			isFinished: true
+			readyState: 'networkSuccess'
+			data: SuccessData
+	  }
+	| {
+			isLoading: false
+			isFinished: true
+			readyState: 'networkError'
+			data: GraphQlClientFailedRequestMetadata
+	  }

package/src/apiRequest/apiRequestReducer.ts

@@ -0,0 +1,41 @@
+import type { ApiRequestAction } from './ApiRequestAction'
+import type { ApiRequestState } from './ApiRequestState'
+
+export type ApiRequestReducer<SuccessData> = (
+	previousState: ApiRequestState<SuccessData>,
+	action: ApiRequestAction<SuccessData>,
+) => ApiRequestState<SuccessData>
+
+export const apiRequestReducer = <SuccessData>(
+	previousState: ApiRequestState<SuccessData>,
+	action: ApiRequestAction<SuccessData>,
+): ApiRequestState<SuccessData> => {
+	switch (action.type) {
+		case 'uninitialize':
+			return {
+				readyState: 'uninitialized',
+				isFinished: false,
+				isLoading: false,
+			}
+		case 'initialize':
+			return {
+				readyState: 'pending',
+				isFinished: false,
+				isLoading: true,
+			}
+		case 'resolveSuccessfully':
+			return {
+				readyState: 'networkSuccess',
+				data: action.data,
+				isFinished: true,
+				isLoading: false,
+			}
+		case 'resolveWithError':
+			return {
+				readyState: 'networkError',
+				data: action.error,
+				isFinished: true,
+				isLoading: false,
+			}
+	}
+}

package/src/apiRequest/index.ts

@@ -0,0 +1,4 @@
+export * from './ApiRequestAction'
+export * from './apiRequestReducer'
+export * from './ApiRequestState'
+export * from './useApiRequest'

package/src/apiRequest/useApiRequest.ts

@@ -0,0 +1,73 @@
+import type {
+	GraphQlClient,
+	GraphQlClientFailedRequestMetadata,
+	GraphQlClientRequestOptions,
+	GraphQlClientVariables,
+} from '@contember/client'
+import { useCallback, useEffect, useReducer, useRef } from 'react'
+import { ApiRequestReducer, apiRequestReducer } from './apiRequestReducer'
+import type { ApiRequestState } from './ApiRequestState'
+
+const initialState: ApiRequestState<any> = {
+	isLoading: false,
+	isFinished: false,
+	readyState: 'uninitialized',
+}
+
+export type UseApiRequestResult<SuccessData> = [
+	ApiRequestState<SuccessData>,
+	(
+		query: string,
+		variables?: GraphQlClientVariables,
+		options?: Omit<GraphQlClientRequestOptions, 'variables'>,
+	) => Promise<SuccessData>,
+]
+
+export const useApiRequest = <SuccessData>(client: GraphQlClient): UseApiRequestResult<SuccessData> => {
+	const [state, dispatch] = useReducer(apiRequestReducer as ApiRequestReducer<SuccessData>, initialState)
+
+	const isUnmountedRef = useRef(false)
+	const sendRequest = useCallback(
+		async (
+			query: string,
+			variables: GraphQlClientVariables = {},
+			options?: Omit<GraphQlClientRequestOptions, 'variables'>,
+		): Promise<SuccessData> => {
+			if (isUnmountedRef.current) {
+				return Promise.reject()
+			}
+			dispatch({
+				type: 'initialize',
+			})
+			return client
+				.sendRequest<SuccessData>(query, {
+					...options,
+					variables,
+				})
+				.then(data => {
+					dispatch({
+						type: 'resolveSuccessfully',
+						data,
+					})
+					return Promise.resolve(data)
+				})
+				.catch((error: GraphQlClientFailedRequestMetadata) => {
+					dispatch({
+						type: 'resolveWithError',
+						error,
+					})
+					return Promise.reject(error)
+				})
+		},
+		[client],
+	)
+
+	useEffect(
+		() => () => {
+			isUnmountedRef.current = true
+		},
+		[], // This empty array is crucial! Otherwise it will first "unmount" before second render no matter what.
+	)
+
+	return [state, sendRequest]
+}

package/src/auth/SessionTokenContext.ts

@@ -0,0 +1,3 @@
+import { createContext } from 'react'
+
+export const SessionTokenContext = createContext<string | undefined>(undefined)

package/src/auth/SetSessionTokenContext.ts

@@ -0,0 +1,5 @@
+import { createContext } from 'react'
+
+export const SetSessionTokenContext = createContext<(token: string | undefined) => void>(() => {
+	throw new Error('SetSessionTokenContext is not set')
+})

package/src/auth/index.ts

@@ -0,0 +1,4 @@
+export * from './SessionTokenContext'
+export * from './SetSessionTokenContext'
+export * from './useSessionToken'
+export * from './useSetSessionToken'

package/src/auth/useSessionToken.ts

@@ -0,0 +1,4 @@
+import { useContext } from 'react'
+import { SessionTokenContext } from './SessionTokenContext'
+
+export const useSessionToken = () => useContext(SessionTokenContext)

package/src/auth/useSetSessionToken.ts

@@ -0,0 +1,4 @@
+import { useContext } from 'react'
+import { SetSessionTokenContext } from './SetSessionTokenContext'
+
+export const useSetSessionToken = () => useContext(SetSessionTokenContext)

package/src/components/RichTextRenderer/BuiltinElements.ts

@@ -0,0 +1,112 @@
+import type { RichTextElement } from './RichTextElement'
+import type { RichTextLeaf } from './RichTextLeaf'
+
+export type BuiltinElements<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> =
+	| RichTextAnchorElement<CustomElements, CustomLeaves>
+	| RichTextHeadingElement<CustomElements, CustomLeaves>
+	| RichTextHorizontalRuleElement<CustomElements, CustomLeaves>
+	| RichTextListItemElement<CustomElements, CustomLeaves>
+	| RichTextOrderedListElement<CustomElements, CustomLeaves>
+	| RichTextParagraphElement<CustomElements, CustomLeaves>
+	| RichTextReferenceElement<CustomElements, CustomLeaves>
+	| RichTextScrollTargetElement<CustomElements, CustomLeaves>
+	| RichTextTableCellElement<CustomElements, CustomLeaves>
+	| RichTextTableElement<CustomElements, CustomLeaves>
+	| RichTextTableRowElement<CustomElements, CustomLeaves>
+	| RichTextUnorderedListElement<CustomElements, CustomLeaves>
+
+export interface RichTextAnchorElement<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> extends RichTextElement<CustomElements, CustomLeaves> {
+	type: 'anchor'
+	href: string
+}
+
+export interface RichTextHeadingElement<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> extends RichTextElement<CustomElements, CustomLeaves> {
+	type: 'heading'
+	level: 1 | 2 | 3 | 4 | 5 | 6
+	isNumbered?: boolean
+}
+
+export interface RichTextOrderedListElement<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> extends RichTextElement<CustomElements, CustomLeaves> {
+	type: 'orderedList'
+}
+
+export interface RichTextUnorderedListElement<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> extends RichTextElement<CustomElements, CustomLeaves> {
+	type: 'unorderedList'
+}
+
+export interface RichTextListItemElement<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> extends RichTextElement<CustomElements, CustomLeaves> {
+	type: 'listItem'
+}
+
+export interface RichTextHorizontalRuleElement<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> extends RichTextElement<CustomElements, CustomLeaves> {
+	type: 'horizontalRule'
+}
+
+export interface RichTextParagraphElement<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> extends RichTextElement<CustomElements, CustomLeaves> {
+	type: 'paragraph'
+	isNumbered?: boolean
+}
+
+export interface RichTextReferenceElement<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> extends RichTextElement<CustomElements, CustomLeaves> {
+	type: 'reference'
+	referenceId: string
+}
+
+export interface RichTextScrollTargetElement<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> extends RichTextElement<CustomElements, CustomLeaves> {
+	type: 'scrollTarget'
+	identifier: string
+}
+
+export interface RichTextTableElement<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> extends RichTextElement<CustomElements, CustomLeaves> {
+	type: 'table'
+}
+
+export interface RichTextTableCellElement<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> extends RichTextElement<CustomElements, CustomLeaves> {
+	type: 'tableCell'
+	headerScope?: 'row'
+	justify?: 'start' | 'center' | 'end'
+}
+
+export interface RichTextTableRowElement<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> extends RichTextElement<CustomElements, CustomLeaves> {
+	type: 'tableRow'
+	headerScope?: 'table'
+}

package/src/components/RichTextRenderer/BuiltinLeaves.ts

@@ -0,0 +1,32 @@
+import type { RichTextLeaf } from './RichTextLeaf'
+
+export type BuiltinLeaves = RichTextBoldLeaf &
+	RichTextCodeLeaf &
+	RichTextHighlightLeaf &
+	RichTextItalicLeaf &
+	RichTextStrikeThroughLeaf &
+	RichTextUnderlineLeaf
+
+export interface RichTextBoldLeaf extends RichTextLeaf {
+	isBold?: boolean
+}
+
+export interface RichTextCodeLeaf extends RichTextLeaf {
+	isCode?: boolean
+}
+
+export interface RichTextHighlightLeaf extends RichTextLeaf {
+	isHighlighted?: boolean
+}
+
+export interface RichTextItalicLeaf extends RichTextLeaf {
+	isItalic?: boolean
+}
+
+export interface RichTextStrikeThroughLeaf extends RichTextLeaf {
+	isStruckThrough?: boolean
+}
+
+export interface RichTextUnderlineLeaf extends RichTextLeaf {
+	isUnderlined?: boolean
+}

package/src/components/RichTextRenderer/ElementRenderer.tsx

@@ -0,0 +1,71 @@
+import type { ComponentType, ReactElement } from 'react'
+import { createElement } from 'react'
+import type { BuiltinElements } from './BuiltinElements'
+import type { BuiltinLeaves } from './BuiltinLeaves'
+import type { RenderChildrenOptions } from './renderChildren'
+import { renderChildren } from './renderChildren'
+import { RenderElementFallback } from './RenderElementFallback'
+import { resolveRichTextElementMetadata } from './resolveRichTextElementMetadata'
+import type { RichTextElement } from './RichTextElement'
+import type { RichTextElementMetadata } from './RichTextElementMetadata'
+import type { RichTextLeaf } from './RichTextLeaf'
+import type { RichTextReference } from './RichTextReference'
+import { useRichTextRenderMetadata } from './RichTextRenderMetadataContext'
+
+export type RenderElement<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+	Reference extends RichTextReference = RichTextReference,
+> = ComponentType<
+	{
+		element: CustomElements | BuiltinElements<CustomElements, CustomLeaves>
+		children: ReactElement
+
+		fallback: ReactElement
+
+		renderChildren: (
+			children:
+				| CustomElements
+				| BuiltinElements<CustomElements, CustomLeaves>
+				| CustomLeaves
+				| BuiltinLeaves
+				| Array<CustomElements | BuiltinElements<CustomElements, CustomLeaves> | CustomLeaves | BuiltinLeaves>,
+			options: RenderChildrenOptions<CustomElements, CustomLeaves>,
+		) => ReactElement
+		renderChildrenOptions: RenderChildrenOptions<CustomElements, CustomLeaves>
+	} & RichTextElementMetadata<CustomElements, CustomLeaves, Reference>
+>
+
+export interface ElementRendererProps<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> {
+	element: CustomElements | BuiltinElements<CustomElements, CustomLeaves>
+	children: ReactElement
+	options: RenderChildrenOptions<CustomElements, CustomLeaves>
+}
+
+export function ElementRenderer<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+>({ element, children, options }: ElementRendererProps<CustomElements, CustomLeaves>) {
+	const metadata = useRichTextRenderMetadata<CustomElements, CustomLeaves>()
+	const elementMetadata = resolveRichTextElementMetadata<CustomElements, CustomLeaves>(element, metadata)
+
+	const fallback = (
+		<RenderElementFallback element={element as BuiltinElements} options={options}>
+			{children}
+		</RenderElementFallback>
+	)
+
+	return options.renderElement
+		? createElement(options.renderElement, {
+				...elementMetadata,
+				element,
+				fallback,
+				children,
+				renderChildren,
+				renderChildrenOptions: options,
+		  })
+		: fallback
+}

package/src/components/RichTextRenderer/LeafRenderer.tsx

@@ -0,0 +1,39 @@
+import type { ComponentType, ReactElement } from 'react'
+import { createElement } from 'react'
+import type { BuiltinLeaves } from './BuiltinLeaves'
+import { RenderLeafFallback } from './RenderLeafFallback'
+import type { RichTextLeaf } from './RichTextLeaf'
+import type { RichTextLeafMetadata } from './RichTextLeafMetadata'
+import { useRichTextRenderMetadata } from './RichTextRenderMetadataContext'
+
+export type RenderLeaf<CustomLeaves extends RichTextLeaf> = ComponentType<
+	{
+		leaf: CustomLeaves | BuiltinLeaves
+		fallback: ReactElement
+	} & RichTextLeafMetadata
+>
+
+export interface LeafRendererProps<CustomLeaves extends RichTextLeaf = never> {
+	renderLeaf?: RenderLeaf<CustomLeaves>
+	leaf: CustomLeaves | BuiltinLeaves
+}
+
+export function LeafRenderer<CustomLeaves extends RichTextLeaf = never>({
+	leaf,
+	renderLeaf,
+}: LeafRendererProps<CustomLeaves>) {
+	const formatVersion = useRichTextRenderMetadata().formatVersion
+	const fallback = <RenderLeafFallback leaf={leaf} />
+
+	return renderLeaf
+		? createElement(
+				renderLeaf,
+				{
+					formatVersion,
+					leaf,
+					fallback,
+				},
+				leaf.text,
+		  )
+		: fallback
+}

package/src/components/RichTextRenderer/NormalizedRichTextBlock.ts

@@ -0,0 +1,17 @@
+import type { ReferenceRenderer } from './ReferenceRenderer'
+import type { RichTextElement } from './RichTextElement'
+import type { RichTextLeaf } from './RichTextLeaf'
+import type { RichTextReference } from './RichTextReference'
+import type { RootEditorNode } from './RootEditorNode'
+
+export interface NormalizedRichTextBlock<
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> {
+	content: RootEditorNode<CustomElements, CustomLeaves>
+	referenceRenderers: Record<string, ReferenceRenderer<RichTextReference, CustomElements, CustomLeaves>>
+	references: Map<string, RichTextReference> | undefined
+	referencesField: string | undefined
+	referenceDiscriminationField: string | undefined
+	id: string | undefined
+}

package/src/components/RichTextRenderer/ReferenceRenderer.ts

@@ -0,0 +1,26 @@
+import type { ReactElement, ReactNode } from 'react'
+import type { BuiltinElements } from './BuiltinElements'
+import type { RichTextElement } from './RichTextElement'
+import type { RichTextElementMetadata } from './RichTextElementMetadata'
+import type { RichTextLeaf } from './RichTextLeaf'
+import type { RichTextReference } from './RichTextReference'
+
+export type ReferenceRendererProps<
+	Reference extends RichTextReference = RichTextReference,
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> = {
+	element: CustomElements | BuiltinElements<CustomElements, CustomLeaves>
+	children: ReactElement
+} & {
+	[Prop in keyof RichTextElementMetadata<CustomElements, CustomLeaves, Reference>]: Exclude<
+		RichTextElementMetadata<CustomElements, CustomLeaves, Reference>[Prop],
+		undefined
+	>
+}
+
+export type ReferenceRenderer<
+	Reference extends RichTextReference = RichTextReference,
+	CustomElements extends RichTextElement = never,
+	CustomLeaves extends RichTextLeaf = never,
+> = (props: ReferenceRendererProps<Reference, CustomElements, CustomLeaves>) => ReactNode