@octanejs/portabletext 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanity.io <hello@sanity.io>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @octanejs/portabletext
+
+Octane renderer for [Portable Text](https://www.portabletext.org/), compatible with the
+runtime API of `@portabletext/react@8.0.1`.
+
+```sh
+npm install @octanejs/portabletext
+pnpm add @octanejs/portabletext
+```
+
+```tsrx
+import {PortableText} from '@octanejs/portabletext'
+
+export function Article(props: {body: PortableTextBlock[]}) @{
+  <article><PortableText value={props.body} /></article>
+}
+```
+
+The package reuses `@portabletext/toolkit` and `@portabletext/types` unchanged. It
+supports default block, list, mark and hard-break rendering; custom component maps;
+missing-component handlers; list nesting modes; `toPlainText`; client rendering; and SSR.
+
+Component callbacks return `OctaneNode` and refs/events follow Octane semantics. The
+upstream `PortableTextReactComponents` and `ReactPortableTextList` type names remain as
+migration aliases; prefer `PortableTextOctaneComponents` and `OctanePortableTextList` in
+new code.

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@octanejs/portabletext",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.22.2"
+  },
+  "description": "Render Portable Text with Octane using the @portabletext/react API.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/portabletext"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@portabletext/toolkit": "6.0.0",
+    "@portabletext/types": "4.0.2"
+  },
+  "peerDependencies": {
+    "octane": "0.1.50"
+  },
+  "devDependencies": {
+    "@portabletext/react": "8.0.1",
+    "@tsrx/react": "^0.2.61",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "vitest": "^4.1.10",
+    "octane": "0.1.50"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.. --project portabletext --project portabletext-ssr",
+    "typecheck": "tsgo --noEmit -p tsconfig.json"
+  }
+}

package/src/components/defaults.ts

@@ -0,0 +1,71 @@
+import type { PortableTextBlock } from '@portabletext/types';
+import { createElement } from 'octane';
+import type {
+	DefaultPortableTextBlockStyle,
+	PortableTextBlockComponent,
+	PortableTextComponentProps,
+	PortableTextOctaneComponents,
+} from '../types';
+import { DefaultListItem, defaultLists } from './list';
+import { defaultMarks } from './marks';
+import {
+	DefaultUnknownBlockStyle,
+	DefaultUnknownList,
+	DefaultUnknownListItem,
+	DefaultUnknownMark,
+	DefaultUnknownType,
+} from './unknown';
+
+export function DefaultHardBreak() {
+	return createElement('br', {});
+}
+function DefaultNormal({ children }: PortableTextComponentProps<PortableTextBlock>) {
+	return createElement('p', { children });
+}
+function DefaultBlockquote({ children }: PortableTextComponentProps<PortableTextBlock>) {
+	return createElement('blockquote', { children });
+}
+function DefaultH1({ children }: PortableTextComponentProps<PortableTextBlock>) {
+	return createElement('h1', { children });
+}
+function DefaultH2({ children }: PortableTextComponentProps<PortableTextBlock>) {
+	return createElement('h2', { children });
+}
+function DefaultH3({ children }: PortableTextComponentProps<PortableTextBlock>) {
+	return createElement('h3', { children });
+}
+function DefaultH4({ children }: PortableTextComponentProps<PortableTextBlock>) {
+	return createElement('h4', { children });
+}
+function DefaultH5({ children }: PortableTextComponentProps<PortableTextBlock>) {
+	return createElement('h5', { children });
+}
+function DefaultH6({ children }: PortableTextComponentProps<PortableTextBlock>) {
+	return createElement('h6', { children });
+}
+
+export const defaultBlockStyles: Record<DefaultPortableTextBlockStyle, PortableTextBlockComponent> =
+	{
+		normal: DefaultNormal,
+		blockquote: DefaultBlockquote,
+		h1: DefaultH1,
+		h2: DefaultH2,
+		h3: DefaultH3,
+		h4: DefaultH4,
+		h5: DefaultH5,
+		h6: DefaultH6,
+	};
+
+export const defaultComponents: PortableTextOctaneComponents = {
+	types: {},
+	block: defaultBlockStyles,
+	marks: defaultMarks,
+	list: defaultLists,
+	listItem: DefaultListItem,
+	hardBreak: DefaultHardBreak,
+	unknownType: DefaultUnknownType,
+	unknownMark: DefaultUnknownMark,
+	unknownList: DefaultUnknownList,
+	unknownListItem: DefaultUnknownListItem,
+	unknownBlockStyle: DefaultUnknownBlockStyle,
+};

package/src/components/list.ts

@@ -0,0 +1,27 @@
+import type { PortableTextListItemBlock } from '@portabletext/types';
+import { createElement } from 'octane';
+import type {
+	DefaultPortableTextListItem,
+	OctanePortableTextList,
+	PortableTextComponentProps,
+	PortableTextListComponent,
+} from '../types';
+
+function DefaultNumberList({ children }: PortableTextComponentProps<OctanePortableTextList>) {
+	return createElement('ol', { children });
+}
+
+function DefaultBulletList({ children }: PortableTextComponentProps<OctanePortableTextList>) {
+	return createElement('ul', { children });
+}
+
+export function DefaultListItem({
+	children,
+}: PortableTextComponentProps<PortableTextListItemBlock>) {
+	return createElement('li', { children });
+}
+
+export const defaultLists: Record<DefaultPortableTextListItem, PortableTextListComponent> = {
+	number: DefaultNumberList,
+	bullet: DefaultBulletList,
+};

package/src/components/marks.ts

@@ -0,0 +1,42 @@
+import type { TypedObject } from '@portabletext/types';
+import { createElement } from 'octane';
+import type {
+	DefaultPortableTextMark,
+	PortableTextMarkComponent,
+	PortableTextMarkComponentProps,
+} from '../types';
+
+interface DefaultLinkMark extends TypedObject {
+	_type: 'link';
+	href: string;
+}
+
+const underlineStyle = { textDecoration: 'underline' };
+
+function DefaultEm({ children }: PortableTextMarkComponentProps) {
+	return createElement('em', { children });
+}
+function DefaultStrong({ children }: PortableTextMarkComponentProps) {
+	return createElement('strong', { children });
+}
+function DefaultCode({ children }: PortableTextMarkComponentProps) {
+	return createElement('code', { children });
+}
+function DefaultUnderline({ children }: PortableTextMarkComponentProps) {
+	return createElement('span', { style: underlineStyle, children });
+}
+function DefaultStrikeThrough({ children }: PortableTextMarkComponentProps) {
+	return createElement('del', { children });
+}
+function DefaultLink({ children, value }: PortableTextMarkComponentProps<DefaultLinkMark>) {
+	return createElement('a', { href: value?.href, children });
+}
+
+export const defaultMarks: Record<DefaultPortableTextMark, PortableTextMarkComponent> = {
+	em: DefaultEm,
+	strong: DefaultStrong,
+	code: DefaultCode,
+	underline: DefaultUnderline,
+	'strike-through': DefaultStrikeThrough,
+	link: DefaultLink,
+};

package/src/components/merge.ts

@@ -0,0 +1,43 @@
+import type { PortableTextComponents, PortableTextOctaneComponents } from '../types';
+
+export function mergeComponents(
+	parent: PortableTextOctaneComponents,
+	overrides: PortableTextComponents,
+): PortableTextOctaneComponents {
+	const {
+		block: _block,
+		list: _list,
+		listItem: _listItem,
+		marks: _marks,
+		types: _types,
+		...rest
+	} = overrides;
+	return {
+		...parent,
+		block: mergeDeeply(parent, overrides, 'block') as PortableTextOctaneComponents['block'],
+		list: mergeDeeply(parent, overrides, 'list') as PortableTextOctaneComponents['list'],
+		listItem: mergeDeeply(
+			parent,
+			overrides,
+			'listItem',
+		) as PortableTextOctaneComponents['listItem'],
+		marks: mergeDeeply(parent, overrides, 'marks') as PortableTextOctaneComponents['marks'],
+		types: mergeDeeply(parent, overrides, 'types') as PortableTextOctaneComponents['types'],
+		...rest,
+	};
+}
+
+function mergeDeeply(
+	parent: PortableTextOctaneComponents,
+	overrides: PortableTextComponents,
+	key: 'block' | 'list' | 'listItem' | 'marks' | 'types',
+): PortableTextOctaneComponents[typeof key] {
+	const override = overrides[key];
+	const parentValue = parent[key];
+	if (typeof override === 'function') return override;
+	if (override && typeof parentValue === 'function') return override;
+	if (override) {
+		return { ...parentValue, ...override } as PortableTextOctaneComponents[typeof key];
+	}
+	return parentValue;
+}

package/src/components/unknown.ts

@@ -0,0 +1,43 @@
+import type { PortableTextBlock, PortableTextListItemBlock } from '@portabletext/types';
+import { createElement } from 'octane';
+import type {
+	OctanePortableTextList,
+	PortableTextComponentProps,
+	PortableTextMarkComponentProps,
+	UnknownNodeType,
+} from '../types';
+import { unknownTypeWarning } from '../warnings';
+
+const hidden = { display: 'none' };
+
+export function DefaultUnknownType({
+	value,
+	isInline,
+}: PortableTextComponentProps<UnknownNodeType>) {
+	const warning = unknownTypeWarning(value._type);
+	return isInline
+		? createElement('span', { style: hidden, children: warning })
+		: createElement('div', { style: hidden, children: warning });
+}
+
+export function DefaultUnknownMark({ markType, children }: PortableTextMarkComponentProps) {
+	return createElement('span', { className: `unknown__pt__mark__${markType}`, children });
+}
+
+export function DefaultUnknownBlockStyle({
+	children,
+}: PortableTextComponentProps<PortableTextBlock>) {
+	return createElement('p', { children });
+}
+
+export function DefaultUnknownList({
+	children,
+}: PortableTextComponentProps<OctanePortableTextList>) {
+	return createElement('ul', { children });
+}
+
+export function DefaultUnknownListItem({
+	children,
+}: PortableTextComponentProps<PortableTextListItemBlock>) {
+	return createElement('li', { children });
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export { defaultComponents } from './components/defaults';
+export { mergeComponents } from './components/merge';
+export { PortableText } from './portable-text';
+export * from './types';
+export type { ToolkitListNestMode as ListNestMode } from '@portabletext/toolkit';
+export { toPlainText } from '@portabletext/toolkit';
+export type { PortableTextBlock } from '@portabletext/types';

package/src/portable-text.ts

@@ -0,0 +1,200 @@
+import type { ToolkitNestedPortableTextSpan, ToolkitTextNode } from '@portabletext/toolkit';
+import {
+	LIST_NEST_MODE_HTML,
+	buildMarksTree,
+	isPortableTextBlock,
+	isPortableTextListItemBlock,
+	isPortableTextToolkitList,
+	isPortableTextToolkitSpan,
+	isPortableTextToolkitTextNode,
+	nestLists,
+	spanToPlainText,
+} from '@portabletext/toolkit';
+import type {
+	PortableTextBlock,
+	PortableTextListItemBlock,
+	TypedObject,
+} from '@portabletext/types';
+import { createElement } from 'octane';
+import type { OctaneNode } from 'octane';
+import { defaultComponents } from './components/defaults';
+import { mergeComponents } from './components/merge';
+import type {
+	MissingComponentHandler,
+	NodeRenderer,
+	OctanePortableTextList,
+	PortableTextOctaneComponents,
+	PortableTextProps,
+	Serializable,
+	SerializedBlock,
+} from './types';
+import {
+	printWarning,
+	unknownBlockStyleWarning,
+	unknownListItemStyleWarning,
+	unknownListStyleWarning,
+	unknownMarkWarning,
+	unknownTypeWarning,
+} from './warnings';
+
+export function PortableText<B extends TypedObject = PortableTextBlock>({
+	value: input,
+	components: componentOverrides,
+	listNestingMode,
+	onMissingComponent: missingComponentHandler = printWarning,
+}: PortableTextProps<B>): OctaneNode {
+	const handleMissingComponent = missingComponentHandler || noop;
+	const blocks = Array.isArray(input) ? input : input == null ? [] : [input];
+	const nested = nestLists(blocks, listNestingMode || LIST_NEST_MODE_HTML);
+	const components = componentOverrides
+		? mergeComponents(defaultComponents, componentOverrides)
+		: defaultComponents;
+	const renderNode = getNodeRenderer(components, handleMissingComponent);
+	return nested.map((node, index) => renderNode({ node, index, isInline: false, renderNode }));
+}
+
+function getNodeRenderer(
+	components: PortableTextOctaneComponents,
+	handleMissingComponent: MissingComponentHandler,
+): NodeRenderer {
+	function renderNode<N extends TypedObject>(options: Serializable<N>): OctaneNode {
+		const { node, index, isInline } = options;
+		const key = node._key || `node-${index}`;
+		if (isPortableTextToolkitList(node)) return renderList(node, index, key);
+		if (isPortableTextListItemBlock(node)) return renderListItem(node, index, key);
+		if (isPortableTextToolkitSpan(node)) return renderSpan(node, index, key);
+		if (node._type in components.types) return renderCustomBlock(node, index, key, isInline);
+		if (isPortableTextBlock(node)) return renderBlock(node, index, key, isInline);
+		if (isPortableTextToolkitTextNode(node)) return renderText(node, key);
+		return renderUnknownType(node, index, key, isInline);
+	}
+
+	function renderListItem(node: PortableTextListItemBlock, index: number, key: string) {
+		const tree = serializeBlock({ node, index, isInline: false, renderNode });
+		const configured = components.listItem;
+		const handler = typeof configured === 'function' ? configured : configured[node.listItem];
+		const ListItem = handler || components.unknownListItem;
+		if (ListItem === components.unknownListItem) {
+			const style = node.listItem || 'bullet';
+			handleMissingComponent(unknownListItemStyleWarning(style), {
+				type: style,
+				nodeType: 'listItemStyle',
+			});
+		}
+		let children = tree.children;
+		if (node.style && node.style !== 'normal') {
+			const { listItem: _listItem, ...blockNode } = node;
+			children = renderNode({ node: blockNode, index, isInline: false, renderNode });
+		}
+		return createElement(ListItem, {
+			key,
+			value: node,
+			index,
+			isInline: false,
+			renderNode,
+			children,
+		});
+	}
+
+	function renderList(node: OctanePortableTextList, index: number, key: string) {
+		const children = node.children.map((child, childIndex) =>
+			renderNode({
+				node: child._key ? child : { ...child, _key: `li-${index}-${childIndex}` },
+				index: childIndex,
+				isInline: false,
+				renderNode,
+			}),
+		);
+		const configured = components.list;
+		const handler = typeof configured === 'function' ? configured : configured[node.listItem];
+		const List = handler || components.unknownList;
+		if (List === components.unknownList) {
+			const style = node.listItem || 'bullet';
+			handleMissingComponent(unknownListStyleWarning(style), {
+				nodeType: 'listStyle',
+				type: style,
+			});
+		}
+		return createElement(List, {
+			key,
+			value: node,
+			index,
+			isInline: false,
+			renderNode,
+			children,
+		});
+	}
+
+	function renderSpan(node: ToolkitNestedPortableTextSpan, _index: number, key: string) {
+		const { markDef, markType, markKey } = node;
+		const Span = components.marks[markType] || components.unknownMark;
+		const children = node.children.map((child, childIndex) =>
+			renderNode({ node: child, index: childIndex, isInline: true, renderNode }),
+		);
+		if (Span === components.unknownMark) {
+			handleMissingComponent(unknownMarkWarning(markType), { nodeType: 'mark', type: markType });
+		}
+		return createElement(Span, {
+			key,
+			text: spanToPlainText(node),
+			value: markDef,
+			markType,
+			markKey,
+			renderNode,
+			children,
+		});
+	}
+
+	function renderBlock(node: PortableTextBlock, index: number, key: string, isInline: boolean) {
+		const { _key, ...serialized } = serializeBlock({ node, index, isInline, renderNode });
+		const style = serialized.node.style || 'normal';
+		const configured = components.block;
+		const handler = typeof configured === 'function' ? configured : configured[style];
+		const Block = handler || components.unknownBlockStyle;
+		if (Block === components.unknownBlockStyle) {
+			handleMissingComponent(unknownBlockStyleWarning(style), {
+				nodeType: 'blockStyle',
+				type: style,
+			});
+		}
+		return createElement(Block, {
+			key,
+			...serialized,
+			value: serialized.node,
+			renderNode,
+		});
+	}
+
+	function renderText(node: ToolkitTextNode, key: string) {
+		if (node.text === '\n') {
+			const HardBreak = components.hardBreak;
+			return HardBreak ? createElement(HardBreak, { key }) : '\n';
+		}
+		return node.text;
+	}
+
+	function renderUnknownType(node: TypedObject, index: number, key: string, isInline: boolean) {
+		const nodeOptions = { value: node, isInline, index, renderNode };
+		handleMissingComponent(unknownTypeWarning(node._type), { nodeType: 'block', type: node._type });
+		return createElement(components.unknownType, { key, ...nodeOptions });
+	}
+
+	function renderCustomBlock(node: TypedObject, index: number, key: string, isInline: boolean) {
+		const Component = components.types[node._type];
+		return Component
+			? createElement(Component, { key, value: node, isInline, index, renderNode })
+			: null;
+	}
+
+	return renderNode;
+}
+
+function serializeBlock(options: Serializable<PortableTextBlock>): SerializedBlock {
+	const { node, index, isInline, renderNode } = options;
+	const children = buildMarksTree(node).map((child, childIndex) =>
+		renderNode({ node: child, isInline: true, index: childIndex, renderNode }),
+	);
+	return { _key: node._key || `block-${index}`, children, index, isInline, node };
+}
+
+function noop() {}

package/src/types.ts

@@ -0,0 +1,329 @@
+import type {
+	ToolkitListNestMode,
+	ToolkitPortableTextList,
+	ToolkitPortableTextListItem,
+} from '@portabletext/toolkit';
+import type {
+	ArbitraryTypedObject,
+	PortableTextBlock,
+	PortableTextBlockStyle,
+	PortableTextListItemBlock,
+	PortableTextListItemType,
+	TypedObject,
+} from '@portabletext/types';
+import type { OctaneNode } from 'octane';
+
+export type PortableTextComponentType<Props = any> = (props: Props) => OctaneNode;
+
+export interface PortableTextProps<
+	B extends TypedObject = PortableTextBlock | ArbitraryTypedObject,
+> {
+	value: B | B[] | null | undefined;
+	components?: PortableTextComponents<B>;
+	onMissingComponent?: MissingComponentHandler | false;
+	listNestingMode?: ToolkitListNestMode;
+}
+
+export type PortableTextComponent<N> = PortableTextComponentType<PortableTextComponentProps<N>>;
+export type PortableTextBlockComponent = PortableTextComponent<PortableTextBlock>;
+export type PortableTextListComponent = PortableTextComponent<OctanePortableTextList>;
+export type PortableTextListItemComponent = PortableTextComponent<PortableTextListItemBlock>;
+export type PortableTextMarkComponent<M extends TypedObject = any> = PortableTextComponentType<
+	PortableTextMarkComponentProps<M>
+>;
+export type PortableTextTypeComponent<V extends TypedObject = any> = PortableTextComponentType<
+	PortableTextTypeComponentProps<V>
+>;
+
+type LooseRecord<K extends string, V> = Record<string, V> & { [P in K]?: V };
+type TypeName<T> = T extends { _type: infer Name } ? (Name extends string ? Name : never) : never;
+type BuiltInPortableTextString<T> = T extends string ? (string extends T ? never : T) : never;
+type BlockFrom<B extends TypedObject> = Extract<B, { _type: 'block' }>;
+type CustomTypeFrom<B extends TypedObject> = Exclude<B, { _type: 'block' }>;
+type CustomTypeName<B extends TypedObject> = TypeName<CustomTypeFrom<B>>;
+
+export type DefaultPortableTextBlockStyle = BuiltInPortableTextString<PortableTextBlockStyle>;
+export type DefaultPortableTextListItem = BuiltInPortableTextString<PortableTextListItemType>;
+export type DefaultPortableTextMark =
+	'em' | 'strong' | 'code' | 'underline' | 'strike-through' | 'link';
+
+type BlockStyleName<B extends TypedObject> =
+	BlockFrom<B> extends { style?: infer Style }
+		? NonNullable<Style> extends string
+			? NonNullable<Style>
+			: never
+		: never;
+type CustomBlockStyleName<B extends TypedObject> = Exclude<
+	BlockStyleName<B>,
+	DefaultPortableTextBlockStyle
+>;
+type ListItemName<B extends TypedObject> =
+	BlockFrom<B> extends { listItem?: infer Item }
+		? NonNullable<Item> extends string
+			? NonNullable<Item>
+			: never
+		: never;
+type CustomListItemName<B extends TypedObject> = Exclude<
+	ListItemName<B>,
+	DefaultPortableTextListItem
+>;
+type MarkFrom<B extends TypedObject> =
+	BlockFrom<B> extends { markDefs?: infer MarkDefs }
+		? NonNullable<MarkDefs> extends readonly (infer MarkDef)[]
+			? Extract<MarkDef, TypedObject>
+			: never
+		: never;
+type MarkName<B extends TypedObject> = TypeName<MarkFrom<B>>;
+type CustomMarkName<B extends TypedObject> = Exclude<MarkName<B>, DefaultPortableTextMark>;
+
+type BlockComponentFor<B extends TypedObject> =
+	BlockFrom<B> extends never ? PortableTextBlockComponent : PortableTextComponent<BlockFrom<B>>;
+type ListComponentFor<B extends TypedObject> =
+	ListItemName<B> extends never
+		? PortableTextListComponent
+		: PortableTextComponent<
+				Omit<OctanePortableTextList, 'listItem'> & { listItem: ListItemName<B> }
+			>;
+type ListItemComponentFor<B extends TypedObject> =
+	ListItemName<B> extends never
+		? PortableTextListItemComponent
+		: PortableTextComponent<Omit<BlockFrom<B>, 'listItem'> & { listItem: ListItemName<B> }>;
+
+type BlockComponents<B extends TypedObject> =
+	string extends BlockStyleName<B>
+		? LooseRecord<PortableTextBlockStyle, PortableTextBlockComponent | undefined>
+		: BlockStyleName<B> extends never
+			? LooseRecord<PortableTextBlockStyle, PortableTextBlockComponent | undefined>
+			: Record<string, PortableTextComponent<any> | undefined> & {
+					[Style in BlockStyleName<B>]?: PortableTextComponent<
+						Omit<BlockFrom<B>, 'style'> & { style?: Style }
+					>;
+				};
+
+type ListComponents<B extends TypedObject> =
+	string extends ListItemName<B>
+		? LooseRecord<PortableTextListItemType, PortableTextListComponent | undefined>
+		: ListItemName<B> extends never
+			? Record<string, PortableTextListComponent | undefined>
+			: Record<string, PortableTextComponent<any> | undefined> & {
+					[Item in ListItemName<B>]?: PortableTextComponent<
+						Omit<OctanePortableTextList, 'listItem'> & { listItem: Item }
+					>;
+				};
+
+type ListItemComponents<B extends TypedObject> =
+	string extends ListItemName<B>
+		? LooseRecord<PortableTextListItemType, PortableTextListItemComponent | undefined>
+		: ListItemName<B> extends never
+			? Record<string, PortableTextListItemComponent | undefined>
+			: Record<string, PortableTextComponent<any> | undefined> & {
+					[Item in ListItemName<B>]?: PortableTextComponent<
+						Omit<BlockFrom<B>, 'listItem'> & { listItem: Item }
+					>;
+				};
+
+type MarkComponents<B extends TypedObject> =
+	string extends MarkName<B>
+		? Record<string, PortableTextMarkComponent | undefined>
+		: MarkName<B> extends never
+			? Record<string, PortableTextMarkComponent | undefined>
+			: Record<string, PortableTextMarkComponent | undefined> & {
+					[Name in MarkName<B>]?: PortableTextMarkComponent<Extract<MarkFrom<B>, { _type: Name }>>;
+				};
+
+type TypeComponents<B extends TypedObject> =
+	string extends CustomTypeName<B>
+		? Record<string, PortableTextTypeComponent | undefined>
+		: CustomTypeName<B> extends never
+			? Record<string, PortableTextTypeComponent | undefined>
+			: Record<string, PortableTextTypeComponent | undefined> & {
+					[Name in CustomTypeName<B>]?: PortableTextTypeComponent<
+						Extract<CustomTypeFrom<B>, { _type: Name }>
+					>;
+				};
+
+export interface PortableTextOctaneComponents<B extends TypedObject = any> {
+	types: TypeComponents<B>;
+	marks: MarkComponents<B>;
+	block: BlockComponents<B> | PortableTextComponent<BlockFrom<B>>;
+	list: ListComponents<B> | PortableTextListComponent;
+	listItem: ListItemComponents<B> | PortableTextListItemComponent;
+	hardBreak: PortableTextComponentType | false;
+	unknownMark: PortableTextMarkComponent;
+	unknownType: PortableTextComponent<UnknownNodeType>;
+	unknownBlockStyle: PortableTextComponent<PortableTextBlock>;
+	unknownList: PortableTextComponent<OctanePortableTextList>;
+	unknownListItem: PortableTextComponent<PortableTextListItemBlock>;
+}
+
+/** @deprecated Prefer PortableTextOctaneComponents in new Octane code. */
+export type PortableTextReactComponents<B extends TypedObject = any> =
+	PortableTextOctaneComponents<B>;
+export type PortableTextComponents<B extends TypedObject = any> = Partial<
+	PortableTextOctaneComponents<B>
+>;
+
+type PortableTextValueItem<T> = Extract<
+	NonNullable<T> extends readonly (infer B)[] ? B : NonNullable<T>,
+	TypedObject
+>;
+type PortableTextArrayItem<T> =
+	NonNullable<T> extends readonly (infer Item)[]
+		? Extract<NonNullable<Item>, { _type: 'block' }> extends never
+			? never
+			: Extract<NonNullable<Item>, TypedObject>
+		: never;
+type InferPortableTextTypedObject<T> = T extends unknown
+	? PortableTextArrayItem<T> extends never
+		? NonNullable<T> extends readonly (infer Item)[]
+			? InferPortableTextTypedObject<Item>
+			: NonNullable<T> extends object
+				? {
+						[Key in keyof NonNullable<T>]: InferPortableTextTypedObject<NonNullable<T>[Key]>;
+					}[keyof NonNullable<T>]
+				: never
+		: PortableTextArrayItem<T>
+	: never;
+
+type StrictTypeComponents<B extends TypedObject> =
+	string extends CustomTypeName<B>
+		? Record<string, PortableTextTypeComponent | undefined>
+		: CustomTypeName<B> extends never
+			? Record<string, never>
+			: {
+					[Name in CustomTypeName<B>]-?: PortableTextTypeComponent<
+						Extract<CustomTypeFrom<B>, { _type: Name }>
+					>;
+				};
+type StrictTypeOverrides<B extends TypedObject> =
+	CustomTypeName<B> extends never
+		? { types?: StrictTypeComponents<B> }
+		: { types: StrictTypeComponents<B> };
+
+type StrictMarkComponents<B extends TypedObject> =
+	string extends MarkName<B>
+		? Record<string, PortableTextMarkComponent | undefined>
+		: MarkName<B> extends never
+			? Record<string, never>
+			: {
+					[Name in CustomMarkName<B>]-?: PortableTextMarkComponent<
+						Extract<MarkFrom<B>, { _type: Name }>
+					>;
+				} & {
+					[Name in Extract<DefaultPortableTextMark, MarkName<B>>]?: PortableTextMarkComponent<
+						Extract<MarkFrom<B>, { _type: Name }>
+					>;
+				};
+type StrictMarkOverrides<B extends TypedObject> =
+	CustomMarkName<B> extends never
+		? { marks?: StrictMarkComponents<B> }
+		: { marks: StrictMarkComponents<B> };
+
+type StrictBlockComponents<B extends TypedObject> =
+	string extends BlockStyleName<B>
+		? LooseRecord<PortableTextBlockStyle, PortableTextBlockComponent | undefined>
+		: BlockStyleName<B> extends never
+			? Record<string, never>
+			: {
+					[Style in CustomBlockStyleName<B>]-?: PortableTextComponent<
+						Omit<BlockFrom<B>, 'style'> & { style?: Style }
+					>;
+				} & {
+					[
+						Style in Extract<DefaultPortableTextBlockStyle, BlockStyleName<B>>
+					]?: PortableTextComponent<Omit<BlockFrom<B>, 'style'> & { style?: Style }>;
+				};
+type StrictBlockOverrides<B extends TypedObject> =
+	CustomBlockStyleName<B> extends never
+		? { block?: StrictBlockComponents<B> | BlockComponentFor<B> }
+		: { block: StrictBlockComponents<B> | BlockComponentFor<B> };
+
+type StrictListComponents<B extends TypedObject> =
+	string extends ListItemName<B>
+		? LooseRecord<PortableTextListItemType, PortableTextListComponent | undefined>
+		: ListItemName<B> extends never
+			? Record<string, never>
+			: {
+					[Item in CustomListItemName<B>]-?: PortableTextComponent<
+						Omit<OctanePortableTextList, 'listItem'> & { listItem: Item }
+					>;
+				} & {
+					[Item in Extract<DefaultPortableTextListItem, ListItemName<B>>]?: PortableTextComponent<
+						Omit<OctanePortableTextList, 'listItem'> & { listItem: Item }
+					>;
+				};
+type StrictListOverrides<B extends TypedObject> =
+	CustomListItemName<B> extends never
+		? { list?: StrictListComponents<B> | ListComponentFor<B> }
+		: { list: StrictListComponents<B> | ListComponentFor<B> };
+
+type StrictListItemComponents<B extends TypedObject> =
+	string extends ListItemName<B>
+		? LooseRecord<PortableTextListItemType, PortableTextListItemComponent | undefined>
+		: ListItemName<B> extends never
+			? Record<string, never>
+			: {
+					[Item in ListItemName<B>]-?: PortableTextComponent<
+						Omit<BlockFrom<B>, 'listItem'> & { listItem: Item }
+					>;
+				};
+type StrictListItemOverrides<B extends TypedObject> = {
+	listItem?: StrictListItemComponents<B> | ListItemComponentFor<B>;
+};
+
+export type InferComponents<T> = PortableTextComponents<PortableTextValueItem<T>>;
+export type InferValue<T> = Exclude<InferPortableTextTypedObject<T>, undefined>[];
+export type InferStrictComponents<T> = Omit<
+	PortableTextComponents<PortableTextValueItem<T>>,
+	'types' | 'marks' | 'block' | 'list' | 'listItem'
+> &
+	StrictTypeOverrides<PortableTextValueItem<T>> &
+	StrictMarkOverrides<PortableTextValueItem<T>> &
+	StrictBlockOverrides<PortableTextValueItem<T>> &
+	StrictListOverrides<PortableTextValueItem<T>> &
+	StrictListItemOverrides<PortableTextValueItem<T>>;
+
+export interface PortableTextComponentProps<T> {
+	value: T;
+	index: number;
+	isInline: boolean;
+	children?: OctaneNode;
+	renderNode: NodeRenderer;
+}
+export type PortableTextTypeComponentProps<T> = Omit<PortableTextComponentProps<T>, 'children'>;
+export interface PortableTextMarkComponentProps<M extends TypedObject = ArbitraryTypedObject> {
+	value?: M;
+	text: string;
+	markKey?: string;
+	markType: string;
+	children: OctaneNode;
+	renderNode: NodeRenderer;
+}
+
+export type UnknownNodeType = { _type: string; [key: string]: unknown } | TypedObject;
+export type NodeRenderer = <T extends TypedObject>(options: Serializable<T>) => OctaneNode;
+export type NodeType = 'block' | 'mark' | 'blockStyle' | 'listStyle' | 'listItemStyle';
+export type MissingComponentHandler = (
+	message: string,
+	options: { type: string; nodeType: NodeType },
+) => void;
+export interface Serializable<T> {
+	node: T;
+	index: number;
+	isInline: boolean;
+	renderNode: NodeRenderer;
+}
+export interface SerializedBlock {
+	_key: string;
+	children: OctaneNode;
+	index: number;
+	isInline: boolean;
+	node: PortableTextBlock | PortableTextListItemBlock;
+}
+
+export type OctanePortableTextList = ToolkitPortableTextList;
+export type OctanePortableTextListItem = ToolkitPortableTextListItem;
+/** @deprecated Prefer OctanePortableTextList in new Octane code. */
+export type ReactPortableTextList = OctanePortableTextList;
+/** @deprecated Prefer OctanePortableTextListItem in new Octane code. */
+export type ReactPortableTextListItem = OctanePortableTextListItem;

package/src/warnings.ts

@@ -0,0 +1,17 @@
+const getTemplate = (type: string, prop: string): string =>
+	`[@portabletext/react] Unknown ${type}, specify a component for it in the \`components.${prop}\` prop`;
+
+export const unknownTypeWarning = (typeName: string): string =>
+	getTemplate(`block type "${typeName}"`, 'types');
+export const unknownMarkWarning = (markType: string): string =>
+	getTemplate(`mark type "${markType}"`, 'marks');
+export const unknownBlockStyleWarning = (blockStyle: string): string =>
+	getTemplate(`block style "${blockStyle}"`, 'block');
+export const unknownListStyleWarning = (listStyle: string): string =>
+	getTemplate(`list style "${listStyle}"`, 'list');
+export const unknownListItemStyleWarning = (listStyle: string): string =>
+	getTemplate(`list item style "${listStyle}"`, 'listItem');
+
+export function printWarning(message: string): void {
+	console.warn(message);
+}