@contember/react-multipass-rendering 1.0.0-rc.1 → 1.0.0-rc.12

package/src/ChildrenAnalyzer.ts

@@ -0,0 +1,250 @@
+import type { ElementType, ReactNode } from 'react'
+import { assertNever } from './assertNever'
+import type { BranchNodeList } from './BranchNodeList'
+import { ChildrenAnalyzerError } from './ChildrenAnalyzerError'
+import type { ChildrenAnalyzerOptions } from './ChildrenAnalyzerOptions'
+import { getErrorMessage } from './helpers'
+import type { LeafList } from './LeafList'
+import type {
+	DeclarationSiteNodeRepresentationFactory,
+	RawNodeRepresentation,
+	RepresentationFactorySite,
+	StaticContextFactory,
+	SyntheticChildrenFactory,
+	UnconstrainedLeafRepresentationFactory,
+	ValidFactoryName,
+} from './nodeSpecs'
+
+export class ChildrenAnalyzer<
+	AllLeavesRepresentation = any,
+	AllBranchNodesRepresentation = never,
+	StaticContext = undefined,
+> {
+	private static defaultOptions: ChildrenAnalyzerOptions = {
+		ignoreRenderProps: true,
+		renderPropsErrorMessage: 'Render props (functions as React component children) are not supported.',
+
+		ignoreUnhandledNodes: true,
+		unhandledNodeErrorMessage: 'Encountered an unknown child.',
+
+		staticContextFactoryName: 'getStaticContext',
+		staticRenderFactoryName: 'staticRender',
+	}
+
+	private readonly leaves: LeafList<AllLeavesRepresentation, StaticContext>
+	private readonly branchNodes: BranchNodeList<AllLeavesRepresentation, AllBranchNodesRepresentation, StaticContext>
+	private readonly options: ChildrenAnalyzerOptions<StaticContext>
+
+	public constructor(
+		leaves: LeafList<AllLeavesRepresentation, StaticContext>,
+		options?: Partial<ChildrenAnalyzerOptions>,
+	)
+	public constructor(
+		leaves: LeafList<AllLeavesRepresentation, StaticContext>,
+		branchNodes: BranchNodeList<AllLeavesRepresentation, AllBranchNodesRepresentation, StaticContext>,
+		options?: Partial<ChildrenAnalyzerOptions>,
+	)
+	public constructor(
+		leaves: LeafList<AllLeavesRepresentation, StaticContext>,
+		decider:
+			| Partial<ChildrenAnalyzerOptions>
+			| BranchNodeList<AllLeavesRepresentation, AllBranchNodesRepresentation, StaticContext> = [],
+		options: Partial<ChildrenAnalyzerOptions> = {},
+	) {
+		this.leaves = leaves
+
+		if (Array.isArray(decider)) {
+			this.branchNodes = decider
+		} else {
+			this.branchNodes = []
+			options = decider
+		}
+		this.options = { ...ChildrenAnalyzer.defaultOptions, ...options }
+	}
+
+	public processChildren(
+		children: ReactNode,
+		initialStaticContext: StaticContext,
+	): Array<AllLeavesRepresentation | AllBranchNodesRepresentation> {
+		const processed = this.processNode(children, initialStaticContext)
+
+		const rawResult: Array<AllLeavesRepresentation | AllBranchNodesRepresentation | undefined> = Array.isArray(
+			processed,
+		)
+			? processed
+			: [processed]
+
+		return rawResult.filter(
+			(item): item is AllLeavesRepresentation | AllBranchNodesRepresentation => item !== undefined,
+		)
+	}
+
+	private processNode(
+		node: ReactNode | Function,
+		staticContext: StaticContext,
+	): RawNodeRepresentation<AllLeavesRepresentation, AllBranchNodesRepresentation> {
+		if (!node || typeof node === 'string' || typeof node === 'number' || typeof node === 'boolean') {
+			for (const leaf of this.leaves) {
+				const specification = leaf.specification
+				if (specification.type === 'useSite') {
+					const { ComponentType, factory } = specification
+					if (ComponentType === undefined) {
+						return factory(node, staticContext)
+					}
+				}
+			}
+			if (node === false || node === undefined || node === null) {
+				// This adds seamless support for conditionals and such.
+				return undefined
+			}
+			if (!this.options.ignoreUnhandledNodes) {
+				throw new ChildrenAnalyzerError(getErrorMessage(this.options.unhandledNodeErrorMessage, node, staticContext))
+			}
+			return undefined
+		}
+
+		if (typeof node === 'function') {
+			if (this.options.ignoreRenderProps) {
+				return undefined
+			}
+			throw new ChildrenAnalyzerError(getErrorMessage(this.options.renderPropsErrorMessage, node, staticContext))
+		}
+
+		if (Array.isArray(node)) {
+			let mapped: Array<AllLeavesRepresentation | AllBranchNodesRepresentation> = []
+
+			for (const subNode of node) {
+				const processed = this.processNode(subNode, staticContext)
+
+				if (processed !== undefined) {
+					if (Array.isArray(processed)) {
+						mapped = mapped.concat(processed)
+					} else {
+						mapped.push(processed)
+					}
+				}
+			}
+
+			return mapped
+		}
+
+		let children: ReactNode = undefined
+
+		if (!('type' in node)) {
+			return this.processNode(children, staticContext)
+		}
+		children = node.props.children
+
+		if (typeof node.type === 'symbol') {
+			// Fragment, Portal or other non-component
+			return this.processNode(children, staticContext)
+		}
+		// if (typeof node.type === 'string') {
+		// 	// Typically a host component
+		// 	if (!this.options.ignoreUnhandledNodes) {
+		// 		throw new ChildrenAnalyzerError(getErrorMessage(this.options.unhandledNodeErrorMessage, node, staticContext))
+		// 	}
+		// 	return this.processNode(children, staticContext)
+		// }
+
+		// Component, PureComponent, FunctionComponent
+
+		const treeNode = node.type as ElementType &
+			{
+				[staticMethod in ValidFactoryName]:
+					| StaticContextFactory<any, StaticContext>
+					| SyntheticChildrenFactory<any, StaticContext>
+					| UnconstrainedLeafRepresentationFactory<any, AllLeavesRepresentation, StaticContext>
+					| DeclarationSiteNodeRepresentationFactory<any, unknown, AllBranchNodesRepresentation, StaticContext>
+			}
+
+		if (typeof treeNode !== 'string') {
+			if (this.options.staticContextFactoryName in treeNode) {
+				const staticContextFactory = treeNode[this.options.staticContextFactoryName] as StaticContextFactory<
+					any,
+					StaticContext
+				>
+				staticContext = staticContextFactory(node.props, staticContext)
+			}
+
+			if (this.options.staticRenderFactoryName in treeNode) {
+				const factory = treeNode[this.options.staticRenderFactoryName] as SyntheticChildrenFactory<any, StaticContext>
+				children = factory(node.props, staticContext)
+			}
+		}
+
+		for (const leaf of this.leaves) {
+			const specification = leaf.specification
+			switch (specification.type) {
+				case 'declarationSite': {
+					const { factoryMethodName } = specification
+
+					if (typeof treeNode !== 'string' && factoryMethodName in treeNode) {
+						const factory = treeNode[factoryMethodName] as UnconstrainedLeafRepresentationFactory<
+							any,
+							AllBranchNodesRepresentation | AllLeavesRepresentation,
+							StaticContext
+						>
+						return factory(node.props, staticContext)
+					}
+					break
+				}
+				case 'useSite': {
+					const { ComponentType, factory } = specification
+					if (ComponentType === undefined || node.type === ComponentType) {
+						return factory(node, staticContext)
+					}
+					break
+				}
+				default:
+					return assertNever(specification)
+			}
+		}
+
+		const processedChildren = this.processNode(children, staticContext)
+
+		for (const branchNode of this.branchNodes) {
+			const specification = branchNode.specification
+			switch (specification.type) {
+				case 'declarationSite': {
+					const { factoryMethodName, childrenRepresentationReducer } = specification
+
+					if (typeof treeNode !== 'string' && factoryMethodName in treeNode) {
+						if (processedChildren === undefined && !branchNode.options.childrenAreOptional) {
+							throw new ChildrenAnalyzerError(branchNode.options.childrenAbsentErrorMessage)
+						}
+						const factory = treeNode[factoryMethodName] as DeclarationSiteNodeRepresentationFactory<
+							any,
+							unknown,
+							AllBranchNodesRepresentation | AllLeavesRepresentation,
+							StaticContext
+						>
+						return factory(node.props, childrenRepresentationReducer(processedChildren), staticContext)
+					}
+					break
+				}
+				case 'useSite': {
+					const { factory, ComponentType } = specification
+					if (ComponentType === undefined || node.type === ComponentType) {
+						if (processedChildren === undefined && !branchNode.options.childrenAreOptional) {
+							throw new ChildrenAnalyzerError(branchNode.options.childrenAbsentErrorMessage)
+						}
+						return factory(node, processedChildren, staticContext)
+					}
+					break
+				}
+				default:
+					return assertNever(specification)
+			}
+		}
+
+		if (
+			!this.options.ignoreUnhandledNodes &&
+			!(typeof treeNode !== 'string' && this.options.staticRenderFactoryName in treeNode)
+		) {
+			throw new ChildrenAnalyzerError(getErrorMessage(this.options.unhandledNodeErrorMessage, node, staticContext))
+		}
+
+		return processedChildren
+	}
+}

package/src/ChildrenAnalyzerError.ts

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

package/src/ChildrenAnalyzerOptions.ts

@@ -0,0 +1,12 @@
+import type { ErrorMessageFactory } from './ErrorMessageFactory'
+
+export interface ChildrenAnalyzerOptions<StaticContext = any> {
+	ignoreRenderProps: boolean
+	renderPropsErrorMessage: ErrorMessageFactory<StaticContext>
+
+	ignoreUnhandledNodes: boolean
+	unhandledNodeErrorMessage: ErrorMessageFactory<StaticContext>
+
+	staticContextFactoryName: string
+	staticRenderFactoryName: string
+}

package/src/ErrorMessageFactory.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react'
+
+export type ErrorMessageFactory<StaticContext = any> =
+	| string
+	| ((node: ReactNode, staticContext: StaticContext) => string)

package/src/LeafList.ts

@@ -0,0 +1,8 @@
+import type { Leaf, ValidFactoryName } from './nodeSpecs'
+
+export type LeafList<RepresentationUnion, StaticContext> = Leaf<
+	any,
+	StaticContext,
+	ValidFactoryName,
+	RepresentationUnion
+>[]

package/src/assertNever.ts

@@ -0,0 +1,3 @@
+export const assertNever = (_: never): never => {
+	throw new Error()
+}

package/src/helpers/getErrorMessage.ts

@@ -0,0 +1,10 @@
+import type { ReactNode } from 'react'
+import type { ErrorMessageFactory } from '../ErrorMessageFactory'
+
+export const getErrorMessage = <StaticContext>(
+	factory: ErrorMessageFactory<StaticContext>,
+	node: ReactNode,
+	staticContext: StaticContext,
+): string => {
+	return typeof factory === 'string' ? factory : factory(node, staticContext)
+}

package/src/helpers/index.ts

@@ -0,0 +1 @@
+export * from './getErrorMessage'

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './nodeSpecs'
+
+export * from './ChildrenAnalyzer'
+export * from './ChildrenAnalyzerError'
+export * from './ChildrenAnalyzerOptions'

package/src/nodeSpecs/BranchNode.ts

@@ -0,0 +1,103 @@
+import type { ElementType } from 'react'
+import { ChildrenAnalyzerError } from '../ChildrenAnalyzerError'
+import type { BranchNodeOptions } from './BranchNodeOptions'
+import type { ChildrenRepresentationReducer, UseSiteBranchNodeRepresentationFactory, ValidFactoryName } from './types'
+
+class BranchNode<
+	Props extends {} = {},
+	StaticContext = undefined,
+	FactoryMethodName extends ValidFactoryName = string,
+	ChildrenRepresentation = any,
+	ReducedChildrenRepresentation = any,
+	Representation = any,
+> {
+	private static defaultOptions: BranchNodeOptions = {
+		childrenAreOptional: false,
+		childrenAbsentErrorMessage: 'Component must have children!',
+	}
+
+	public readonly specification: BranchNode.Specification<
+		Props,
+		StaticContext,
+		FactoryMethodName,
+		ChildrenRepresentation,
+		ReducedChildrenRepresentation,
+		Representation
+	>
+
+	public readonly options: BranchNodeOptions
+
+	public constructor(
+		factoryMethodName: FactoryMethodName,
+		childrenRepresentationReducer: ChildrenRepresentationReducer<ChildrenRepresentation, ReducedChildrenRepresentation>,
+		options?: Partial<BranchNodeOptions>,
+	)
+	public constructor(
+		useSiteFactory: UseSiteBranchNodeRepresentationFactory<
+			Props,
+			ChildrenRepresentation,
+			Representation,
+			StaticContext
+		>,
+		ComponentType?: ElementType<Props>,
+		options?: Partial<BranchNodeOptions>,
+	)
+	public constructor(
+		factory:
+			| FactoryMethodName
+			| UseSiteBranchNodeRepresentationFactory<Props, ChildrenRepresentation, Representation, StaticContext>,
+		componentOrReducer?:
+			| ChildrenRepresentationReducer<ChildrenRepresentation, ReducedChildrenRepresentation>
+			| ElementType<Props>,
+		options?: Partial<BranchNodeOptions>,
+	) {
+		if (typeof factory !== 'function') {
+			this.specification = {
+				type: 'declarationSite',
+				factoryMethodName: factory,
+				childrenRepresentationReducer: componentOrReducer as ChildrenRepresentationReducer<
+					ChildrenRepresentation,
+					ReducedChildrenRepresentation
+				>,
+			}
+		} else if (typeof factory === 'function') {
+			this.specification = {
+				type: 'useSite',
+				factory,
+				ComponentType: componentOrReducer as ElementType<Props>,
+			}
+		} else {
+			throw new ChildrenAnalyzerError('Invalid arguments')
+		}
+		this.options = {
+			...BranchNode.defaultOptions,
+			...options,
+		}
+	}
+}
+
+namespace BranchNode {
+	export type Specification<
+		Props extends {} = {},
+		StaticContext = any,
+		FactoryMethodName extends ValidFactoryName = string,
+		ChildrenRepresentation = any,
+		ReducedChildrenRepresentation = any,
+		Representation = any,
+	> =
+		| {
+				type: 'declarationSite'
+				factoryMethodName: FactoryMethodName
+				childrenRepresentationReducer: ChildrenRepresentationReducer<
+					ChildrenRepresentation,
+					ReducedChildrenRepresentation
+				>
+		  }
+		| {
+				type: 'useSite'
+				factory: UseSiteBranchNodeRepresentationFactory<Props, ChildrenRepresentation, Representation, StaticContext>
+				ComponentType?: ElementType<Props>
+		  }
+}
+
+export { BranchNode }

package/src/nodeSpecs/BranchNodeOptions.ts

@@ -0,0 +1,4 @@
+export interface BranchNodeOptions {
+	childrenAreOptional: boolean
+	childrenAbsentErrorMessage: string
+}

package/src/nodeSpecs/Leaf.ts

@@ -0,0 +1,59 @@
+import type { ElementType } from 'react'
+import type {
+	ConstrainedLeafRepresentationFactory,
+	UnconstrainedLeafRepresentationFactory,
+	ValidFactoryName,
+} from './types'
+
+class Leaf<
+	Props extends {} = {},
+	StaticContext = any,
+	FactoryMethodName extends ValidFactoryName = string,
+	Representation = any,
+> {
+	public readonly specification: Leaf.Specification<FactoryMethodName, Representation, Props, StaticContext>
+
+	public constructor(factoryMethodName: FactoryMethodName)
+	public constructor(staticFactory: UnconstrainedLeafRepresentationFactory<Props, Representation, StaticContext>)
+	public constructor(
+		staticFactory: ConstrainedLeafRepresentationFactory<Props, Representation, StaticContext>,
+		ComponentType: ElementType<Props>,
+	)
+	public constructor(
+		factory: FactoryMethodName | UnconstrainedLeafRepresentationFactory<Props, Representation, StaticContext>,
+		ComponentType?: ElementType<Props>,
+	) {
+		if (typeof factory === 'function') {
+			this.specification = {
+				type: 'useSite',
+				ComponentType,
+				factory,
+			}
+		} else {
+			this.specification = {
+				type: 'declarationSite',
+				factoryMethodName: factory,
+			}
+		}
+	}
+}
+
+namespace Leaf {
+	export type Specification<
+		FactoryMethodName extends ValidFactoryName,
+		Representation,
+		Props extends {},
+		StaticContext,
+	> =
+		| {
+				type: 'declarationSite'
+				factoryMethodName: FactoryMethodName
+		  }
+		| {
+				type: 'useSite'
+				factory: UnconstrainedLeafRepresentationFactory<Props, Representation, StaticContext>
+				ComponentType?: ElementType<Props>
+		  }
+}
+
+export { Leaf }

package/src/nodeSpecs/RawNodeRepresentation.ts

@@ -0,0 +1,5 @@
+export type RawNodeRepresentation<AllLeavesRepresentation, AllBranchNodesRepresentation = AllLeavesRepresentation> =
+	| AllLeavesRepresentation
+	| AllBranchNodesRepresentation
+	| Array<AllLeavesRepresentation | AllBranchNodesRepresentation>
+	| undefined

package/src/nodeSpecs/index.ts

@@ -0,0 +1,6 @@
+export * from './types'
+
+export * from './BranchNode'
+export * from './BranchNodeOptions'
+export * from './Leaf'
+export * from './RawNodeRepresentation'

package/src/nodeSpecs/types/ChildrenRepresentationReducer.ts

@@ -0,0 +1,3 @@
+export type ChildrenRepresentationReducer<ChildrenRepresentation, ReducedChildrenRepresentation> = (
+	childrenRepresentations: ChildrenRepresentation,
+) => ReducedChildrenRepresentation

package/src/nodeSpecs/types/ConstrainedLeafRepresentationFactory.ts

@@ -0,0 +1,6 @@
+import type { ReactElement } from 'react'
+
+export type ConstrainedLeafRepresentationFactory<Props extends {}, Representation, StaticContext> = (
+	node: ReactElement<Props, any>,
+	staticContext: StaticContext,
+) => Representation

package/src/nodeSpecs/types/DeclarationSiteNodeRepresentationFactory.ts

@@ -0,0 +1,10 @@
+export type DeclarationSiteNodeRepresentationFactory<
+	Props extends {},
+	ReducedChildrenRepresentation,
+	Representation,
+	StaticContext,
+> = (
+	props: Props,
+	reducedChildrenRepresentation: ReducedChildrenRepresentation,
+	staticContext: StaticContext,
+) => Representation

package/src/nodeSpecs/types/RepresentationFactorySite.ts

@@ -0,0 +1 @@
+export type RepresentationFactorySite = 'declarationSite' | 'useSite'

package/src/nodeSpecs/types/StaticContextFactory.ts

@@ -0,0 +1,4 @@
+export type StaticContextFactory<Props extends {}, StaticContext> = (
+	props: Props,
+	staticContext: StaticContext,
+) => StaticContext

package/src/nodeSpecs/types/SyntheticChildrenFactory.ts

@@ -0,0 +1,6 @@
+import type { ReactNode } from 'react'
+
+export type SyntheticChildrenFactory<Props extends {}, StaticContext> = (
+	props: Props,
+	staticContext: StaticContext,
+) => ReactNode

package/src/nodeSpecs/types/UnconstrainedLeafRepresentationFactory.ts

@@ -0,0 +1,6 @@
+import type { ReactElement, ReactText } from 'react'
+
+export type UnconstrainedLeafRepresentationFactory<Props extends {}, Representation, StaticContext> = (
+	node: ReactText | ReactElement<Props, any> | boolean | null | undefined | {},
+	staticContext: StaticContext,
+) => Representation

package/src/nodeSpecs/types/UseSiteBranchNodeRepresentationFactory.ts

@@ -0,0 +1,12 @@
+import type { ReactElement } from 'react'
+
+export type UseSiteBranchNodeRepresentationFactory<
+	Props extends {},
+	ChildrenRepresentation,
+	Representation,
+	StaticContext,
+> = (
+	node: ReactElement<Props, any>,
+	childrenRepresentation: ChildrenRepresentation,
+	staticContext: StaticContext,
+) => Representation

package/src/nodeSpecs/types/ValidFactoryName.ts

@@ -0,0 +1 @@
+export type ValidFactoryName = string | number

package/src/nodeSpecs/types/index.ts

@@ -0,0 +1,9 @@
+export * from './ChildrenRepresentationReducer'
+export * from './ConstrainedLeafRepresentationFactory'
+export * from './DeclarationSiteNodeRepresentationFactory'
+export * from './RepresentationFactorySite'
+export * from './StaticContextFactory'
+export * from './SyntheticChildrenFactory'
+export * from './UnconstrainedLeafRepresentationFactory'
+export * from './UseSiteBranchNodeRepresentationFactory'
+export * from './ValidFactoryName'

package/src/tsconfig.json

@@ -0,0 +1,6 @@
+{
+	"extends": "../tsconfig.settings.json",
+	"compilerOptions": {
+		"outDir": "../dist/types"
+	}
+}