pte-interpolation-react 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,161 @@
+# pte-interpolation-react
+
+[![npm version](https://img.shields.io/npm/v/pte-interpolation-react.svg?style=flat-square)](https://www.npmjs.com/package/pte-interpolation-react)
+
+React rendering library that resolves dynamic variable inline blocks in [Portable Text](https://portabletext.org/) to actual values. Wraps [`@portabletext/react`](https://github.com/portabletext/react-portabletext) with automatic variable substitution.
+
+Part of [sanity-pte-interpolation](https://github.com/jordanl17/sanity-pte-interpolation). For adding variable picker inline blocks to Sanity Studio, see [`sanity-plugin-pte-interpolation`](https://www.npmjs.com/package/sanity-plugin-pte-interpolation).
+
+## Install
+
+```sh
+npm install pte-interpolation-react @portabletext/react
+```
+
+### Peer dependencies
+
+- `react` ^18.0.0 || ^19.0.0
+
+## Usage
+
+### Drop-in component (recommended)
+
+`<InterpolatedPortableText>` is a drop-in replacement for `<PortableText>` that handles variable resolution automatically:
+
+```tsx
+import {InterpolatedPortableText} from 'pte-interpolation-react'
+
+function EmailPreview({body, recipient}) {
+  return (
+    <InterpolatedPortableText
+      value={body}
+      interpolationValues={{
+        firstName: recipient.firstName,
+        lastName: recipient.lastName,
+        email: recipient.email,
+      }}
+    />
+  )
+}
+```
+
+Variables render as `<span data-variable-key="firstName">Jo</span>`, making them easy to target with CSS for styling or highlighting.
+
+### With custom Portable Text components
+
+Pass your own `components` prop and they will be merged with the interpolation types:
+
+```tsx
+<InterpolatedPortableText
+  value={body}
+  interpolationValues={values}
+  components={{
+    marks: {
+      link: ({children, value}) => <a href={value.href}>{children}</a>,
+    },
+  }}
+/>
+```
+
+### Custom fallback for missing values
+
+By default, unresolved variables render as `{variableKey}` (e.g. `{firstName}`). Provide a `fallback` function to customise this:
+
+```tsx
+<InterpolatedPortableText
+  value={body}
+  interpolationValues={values}
+  fallback={(variableKey) => `[missing: ${variableKey}]`}
+/>
+```
+
+### Low-level API
+
+If you need full control over component merging, use `createInterpolationComponents` directly with `<PortableText>` from `@portabletext/react`:
+
+```tsx
+import {useMemo} from 'react'
+import {PortableText} from '@portabletext/react'
+import {createInterpolationComponents} from 'pte-interpolation-react'
+
+function EmailPreview({body, values, customComponents}) {
+  const components = useMemo(() => {
+    const interpolation = createInterpolationComponents(values)
+    return {
+      ...customComponents,
+      types: {
+        ...customComponents.types,
+        ...interpolation.types,
+      },
+    }
+  }, [values, customComponents])
+
+  return <PortableText value={body} components={components} />
+}
+```
+
+## Authoring Variables in Sanity Studio
+
+This package handles the **rendering** side. To add the variable picker to Sanity Studio's Portable Text Editor, use [`sanity-plugin-pte-interpolation`](https://www.npmjs.com/package/sanity-plugin-pte-interpolation):
+
+```ts
+import {interpolationVariables} from 'sanity-plugin-pte-interpolation'
+
+defineField({
+  name: 'body',
+  type: 'array',
+  of: [
+    interpolationVariables([
+      {id: 'firstName', name: 'First name'},
+      {id: 'email', name: 'Email address'},
+    ]),
+  ],
+})
+```
+
+## Data Shape
+
+Variable blocks in stored Portable Text look like this:
+
+```json
+{
+  "_type": "block",
+  "children": [
+    {"_type": "span", "text": "Hello, "},
+    {"_type": "pteInterpolationVariable", "variableKey": "firstName"},
+    {"_type": "span", "text": "!"}
+  ]
+}
+```
+
+The `variableKey` maps to the `id` defined in the Studio variable definitions and the keys in the `interpolationValues` record.
+
+## API Reference
+
+### `<InterpolatedPortableText>`
+
+| Prop                  | Type                              | Description                                                                |
+| --------------------- | --------------------------------- | -------------------------------------------------------------------------- |
+| `value`               | `PortableTextBlock[]`             | Portable Text content from Sanity                                          |
+| `interpolationValues` | `Record<string, string>`          | Map of variable IDs to their resolved values                               |
+| `components`          | `PortableTextComponents`          | Optional custom Portable Text components (merged with interpolation types) |
+| `fallback`            | `(variableKey: string) => string` | Optional function for unresolved variables (defaults to `{variableKey}`)   |
+
+Also accepts all other props from `@portabletext/react`'s `<PortableText>`.
+
+### `createInterpolationComponents(values, fallback?)`
+
+Returns a `PortableTextComponents` object with a `types.pteInterpolationVariable` renderer. Use this when you need manual control over component merging.
+
+| Parameter  | Type                              | Description                                |
+| ---------- | --------------------------------- | ------------------------------------------ |
+| `values`   | `Record<string, string>`          | Map of variable IDs to values              |
+| `fallback` | `(variableKey: string) => string` | Optional fallback for unresolved variables |
+
+### `VARIABLE_TYPE_PREFIX`
+
+The constant `'pteInterpolationVariable'` — the `_type` string used for variable inline blocks. Exported for advanced use cases.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -1,8 +1,40 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: !0 });
-var jsxRuntime = require("react/jsx-runtime");
-function InterpolatedText({ blocks, values }) {
-  return /* @__PURE__ */ jsxRuntime.jsx("pre", { children: /* @__PURE__ */ jsxRuntime.jsx("code", { children: JSON.stringify({ blocks, values }, null, 2) }) });
+var jsxRuntime = require("react/jsx-runtime"), react$1 = require("@portabletext/react"), react = require("react");
+const VARIABLE_TYPE_PREFIX = "pteInterpolationVariable";
+function defaultFallback(variableKey) {
+  return `{${variableKey}}`;
 }
-exports.InterpolatedText = InterpolatedText;
+function createInterpolationComponents(values, fallback = defaultFallback) {
+  function VariableComponent(props) {
+    const { variableKey } = props.value, resolvedValue = values[variableKey] !== void 0 ? values[variableKey] : fallback(variableKey);
+    return /* @__PURE__ */ jsxRuntime.jsx("span", { "data-variable-key": variableKey, children: resolvedValue });
+  }
+  return {
+    types: {
+      [VARIABLE_TYPE_PREFIX]: VariableComponent
+    }
+  };
+}
+function InterpolatedPortableText({
+  interpolationValues,
+  components: userComponents,
+  fallback,
+  ...rest
+}) {
+  const mergedComponents = react.useMemo(() => {
+    const interpolationComponents = createInterpolationComponents(interpolationValues, fallback);
+    return userComponents ? {
+      ...userComponents,
+      types: {
+        ...userComponents.types,
+        ...interpolationComponents.types
+      }
+    } : interpolationComponents;
+  }, [interpolationValues, fallback, userComponents]);
+  return /* @__PURE__ */ jsxRuntime.jsx(react$1.PortableText, { ...rest, components: mergedComponents });
+}
+exports.InterpolatedPortableText = InterpolatedPortableText;
+exports.VARIABLE_TYPE_PREFIX = VARIABLE_TYPE_PREFIX;
+exports.createInterpolationComponents = createInterpolationComponents;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../src/InterpolatedText.tsx"],"sourcesContent":["import type {InterpolatedTextProps} from './types'\n\n/** @public */\nexport function InterpolatedText({blocks, values}: InterpolatedTextProps) {\n  return (\n    <pre>\n      <code>{JSON.stringify({blocks, values}, null, 2)}</code>\n    </pre>\n  )\n}\n"],"names":["jsx"],"mappings":";;;AAGO,SAAS,iBAAiB,EAAC,QAAQ,UAAgC;AACxE,SACEA,2BAAAA,IAAC,OAAA,EACC,UAAAA,2BAAAA,IAAC,QAAA,EAAM,UAAA,KAAK,UAAU,EAAC,QAAQ,OAAA,GAAS,MAAM,CAAC,GAAE,GACnD;AAEJ;;"}
+{"version":3,"file":"index.cjs","sources":["../src/constants.ts","../src/createInterpolationComponents.tsx","../src/InterpolatedPortableText.tsx"],"sourcesContent":["/** @public */\nexport const VARIABLE_TYPE_PREFIX = 'pteInterpolationVariable'\n","import type {PortableTextComponents, PortableTextTypeComponentProps} from '@portabletext/react'\n\nimport {VARIABLE_TYPE_PREFIX} from './constants'\nimport type {\n  InterpolationFallback,\n  InterpolationValues,\n  PteInterpolationVariableBlock,\n} from './types'\n\nfunction defaultFallback(variableKey: string): string {\n  return `{${variableKey}}`\n}\n\n/** @public */\nexport function createInterpolationComponents(\n  values: InterpolationValues,\n  fallback: InterpolationFallback = defaultFallback,\n): PortableTextComponents {\n  function VariableComponent(props: PortableTextTypeComponentProps<PteInterpolationVariableBlock>) {\n    const {variableKey} = props.value\n    const resolvedValue =\n      values[variableKey] !== undefined ? values[variableKey] : fallback(variableKey)\n\n    return <span data-variable-key={variableKey}>{resolvedValue}</span>\n  }\n\n  return {\n    types: {\n      [VARIABLE_TYPE_PREFIX]: VariableComponent,\n    },\n  }\n}\n","import {PortableText} from '@portabletext/react'\nimport {useMemo} from 'react'\n\nimport {createInterpolationComponents} from './createInterpolationComponents'\nimport type {InterpolatedPortableTextProps} from './types'\n\n/** @public */\nexport function InterpolatedPortableText({\n  interpolationValues,\n  components: userComponents,\n  fallback,\n  ...rest\n}: InterpolatedPortableTextProps) {\n  const mergedComponents = useMemo(() => {\n    const interpolationComponents = createInterpolationComponents(interpolationValues, fallback)\n\n    if (!userComponents) {\n      return interpolationComponents\n    }\n\n    return {\n      ...userComponents,\n      types: {\n        ...userComponents.types,\n        ...interpolationComponents.types,\n      },\n    }\n  }, [interpolationValues, fallback, userComponents])\n\n  return <PortableText {...rest} components={mergedComponents} />\n}\n"],"names":["jsx","useMemo","PortableText"],"mappings":";;;AACO,MAAM,uBAAuB;ACQpC,SAAS,gBAAgB,aAA6B;AACpD,SAAO,IAAI,WAAW;AACxB;AAGO,SAAS,8BACd,QACA,WAAkC,iBACV;AACxB,WAAS,kBAAkB,OAAsE;AAC/F,UAAM,EAAC,YAAA,IAAe,MAAM,OACtB,gBACJ,OAAO,WAAW,MAAM,SAAY,OAAO,WAAW,IAAI,SAAS,WAAW;AAEhF,WAAOA,2BAAAA,IAAC,QAAA,EAAK,qBAAmB,aAAc,UAAA,eAAc;AAAA,EAC9D;AAEA,SAAO;AAAA,IACL,OAAO;AAAA,MACL,CAAC,oBAAoB,GAAG;AAAA,IAAA;AAAA,EAC1B;AAEJ;ACxBO,SAAS,yBAAyB;AAAA,EACvC;AAAA,EACA,YAAY;AAAA,EACZ;AAAA,EACA,GAAG;AACL,GAAkC;AAChC,QAAM,mBAAmBC,MAAAA,QAAQ,MAAM;AACrC,UAAM,0BAA0B,8BAA8B,qBAAqB,QAAQ;AAE3F,WAAK,iBAIE;AAAA,MACL,GAAG;AAAA,MACH,OAAO;AAAA,QACL,GAAG,eAAe;AAAA,QAClB,GAAG,wBAAwB;AAAA,MAAA;AAAA,IAC7B,IARO;AAAA,EAUX,GAAG,CAAC,qBAAqB,UAAU,cAAc,CAAC;AAElD,SAAOD,2BAAAA,IAACE,QAAAA,cAAA,EAAc,GAAG,MAAM,YAAY,kBAAkB;AAC/D;;;;"}

package/dist/index.d.cts

@@ -1,16 +1,45 @@
 import {JSX} from 'react/jsx-runtime'
-import type {PortableTextBlock} from '@portabletext/react'
+import type {PortableTextComponents} from '@portabletext/react'
+import type {PortableTextProps} from '@portabletext/react'
 
 /** @public */
-export declare function InterpolatedText({blocks, values}: InterpolatedTextProps): JSX.Element
+export declare function createInterpolationComponents(
+  values: InterpolationValues,
+  fallback?: InterpolationFallback,
+): PortableTextComponents
 
 /** @public */
-export declare interface InterpolatedTextProps {
-  blocks: PortableTextBlock[]
-  values: InterpolationValues
+export declare function InterpolatedPortableText({
+  interpolationValues,
+  components: userComponents,
+  fallback,
+  ...rest
+}: InterpolatedPortableTextProps): JSX.Element
+
+/** @public */
+export declare interface InterpolatedPortableTextProps extends Omit<
+  PortableTextProps,
+  'components'
+> {
+  interpolationValues: InterpolationValues
+  components?: PortableTextComponents
+  fallback?: InterpolationFallback
 }
 
+/** @public */
+export declare type InterpolationFallback = (variableKey: string) => string
+
 /** @public */
 export declare type InterpolationValues = Record<string, string>
 
+/** @public */
+export declare interface PteInterpolationVariableBlock {
+  _type: 'pteInterpolationVariable'
+  _key: string
+  variableKey: string
+}
+
+/** @public */
+export declare const VARIABLE_TYPE_PREFIX = 'pteInterpolationVariable'
+
 export {}

package/dist/index.d.ts

@@ -1,16 +1,45 @@
 import {JSX} from 'react/jsx-runtime'
-import type {PortableTextBlock} from '@portabletext/react'
+import type {PortableTextComponents} from '@portabletext/react'
+import type {PortableTextProps} from '@portabletext/react'
 
 /** @public */
-export declare function InterpolatedText({blocks, values}: InterpolatedTextProps): JSX.Element
+export declare function createInterpolationComponents(
+  values: InterpolationValues,
+  fallback?: InterpolationFallback,
+): PortableTextComponents
 
 /** @public */
-export declare interface InterpolatedTextProps {
-  blocks: PortableTextBlock[]
-  values: InterpolationValues
+export declare function InterpolatedPortableText({
+  interpolationValues,
+  components: userComponents,
+  fallback,
+  ...rest
+}: InterpolatedPortableTextProps): JSX.Element
+
+/** @public */
+export declare interface InterpolatedPortableTextProps extends Omit<
+  PortableTextProps,
+  'components'
+> {
+  interpolationValues: InterpolationValues
+  components?: PortableTextComponents
+  fallback?: InterpolationFallback
 }
 
+/** @public */
+export declare type InterpolationFallback = (variableKey: string) => string
+
 /** @public */
 export declare type InterpolationValues = Record<string, string>
 
+/** @public */
+export declare interface PteInterpolationVariableBlock {
+  _type: 'pteInterpolationVariable'
+  _key: string
+  variableKey: string
+}
+
+/** @public */
+export declare const VARIABLE_TYPE_PREFIX = 'pteInterpolationVariable'
+
 export {}

package/dist/index.js

@@ -1,8 +1,42 @@
 import { jsx } from "react/jsx-runtime";
-function InterpolatedText({ blocks, values }) {
-  return /* @__PURE__ */ jsx("pre", { children: /* @__PURE__ */ jsx("code", { children: JSON.stringify({ blocks, values }, null, 2) }) });
+import { PortableText } from "@portabletext/react";
+import { useMemo } from "react";
+const VARIABLE_TYPE_PREFIX = "pteInterpolationVariable";
+function defaultFallback(variableKey) {
+  return `{${variableKey}}`;
+}
+function createInterpolationComponents(values, fallback = defaultFallback) {
+  function VariableComponent(props) {
+    const { variableKey } = props.value, resolvedValue = values[variableKey] !== void 0 ? values[variableKey] : fallback(variableKey);
+    return /* @__PURE__ */ jsx("span", { "data-variable-key": variableKey, children: resolvedValue });
+  }
+  return {
+    types: {
+      [VARIABLE_TYPE_PREFIX]: VariableComponent
+    }
+  };
+}
+function InterpolatedPortableText({
+  interpolationValues,
+  components: userComponents,
+  fallback,
+  ...rest
+}) {
+  const mergedComponents = useMemo(() => {
+    const interpolationComponents = createInterpolationComponents(interpolationValues, fallback);
+    return userComponents ? {
+      ...userComponents,
+      types: {
+        ...userComponents.types,
+        ...interpolationComponents.types
+      }
+    } : interpolationComponents;
+  }, [interpolationValues, fallback, userComponents]);
+  return /* @__PURE__ */ jsx(PortableText, { ...rest, components: mergedComponents });
 }
 export {
-  InterpolatedText
+  InterpolatedPortableText,
+  VARIABLE_TYPE_PREFIX,
+  createInterpolationComponents
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/InterpolatedText.tsx"],"sourcesContent":["import type {InterpolatedTextProps} from './types'\n\n/** @public */\nexport function InterpolatedText({blocks, values}: InterpolatedTextProps) {\n  return (\n    <pre>\n      <code>{JSON.stringify({blocks, values}, null, 2)}</code>\n    </pre>\n  )\n}\n"],"names":[],"mappings":";AAGO,SAAS,iBAAiB,EAAC,QAAQ,UAAgC;AACxE,SACE,oBAAC,OAAA,EACC,UAAA,oBAAC,QAAA,EAAM,UAAA,KAAK,UAAU,EAAC,QAAQ,OAAA,GAAS,MAAM,CAAC,GAAE,GACnD;AAEJ;"}
+{"version":3,"file":"index.js","sources":["../src/constants.ts","../src/createInterpolationComponents.tsx","../src/InterpolatedPortableText.tsx"],"sourcesContent":["/** @public */\nexport const VARIABLE_TYPE_PREFIX = 'pteInterpolationVariable'\n","import type {PortableTextComponents, PortableTextTypeComponentProps} from '@portabletext/react'\n\nimport {VARIABLE_TYPE_PREFIX} from './constants'\nimport type {\n  InterpolationFallback,\n  InterpolationValues,\n  PteInterpolationVariableBlock,\n} from './types'\n\nfunction defaultFallback(variableKey: string): string {\n  return `{${variableKey}}`\n}\n\n/** @public */\nexport function createInterpolationComponents(\n  values: InterpolationValues,\n  fallback: InterpolationFallback = defaultFallback,\n): PortableTextComponents {\n  function VariableComponent(props: PortableTextTypeComponentProps<PteInterpolationVariableBlock>) {\n    const {variableKey} = props.value\n    const resolvedValue =\n      values[variableKey] !== undefined ? values[variableKey] : fallback(variableKey)\n\n    return <span data-variable-key={variableKey}>{resolvedValue}</span>\n  }\n\n  return {\n    types: {\n      [VARIABLE_TYPE_PREFIX]: VariableComponent,\n    },\n  }\n}\n","import {PortableText} from '@portabletext/react'\nimport {useMemo} from 'react'\n\nimport {createInterpolationComponents} from './createInterpolationComponents'\nimport type {InterpolatedPortableTextProps} from './types'\n\n/** @public */\nexport function InterpolatedPortableText({\n  interpolationValues,\n  components: userComponents,\n  fallback,\n  ...rest\n}: InterpolatedPortableTextProps) {\n  const mergedComponents = useMemo(() => {\n    const interpolationComponents = createInterpolationComponents(interpolationValues, fallback)\n\n    if (!userComponents) {\n      return interpolationComponents\n    }\n\n    return {\n      ...userComponents,\n      types: {\n        ...userComponents.types,\n        ...interpolationComponents.types,\n      },\n    }\n  }, [interpolationValues, fallback, userComponents])\n\n  return <PortableText {...rest} components={mergedComponents} />\n}\n"],"names":[],"mappings":";;;AACO,MAAM,uBAAuB;ACQpC,SAAS,gBAAgB,aAA6B;AACpD,SAAO,IAAI,WAAW;AACxB;AAGO,SAAS,8BACd,QACA,WAAkC,iBACV;AACxB,WAAS,kBAAkB,OAAsE;AAC/F,UAAM,EAAC,YAAA,IAAe,MAAM,OACtB,gBACJ,OAAO,WAAW,MAAM,SAAY,OAAO,WAAW,IAAI,SAAS,WAAW;AAEhF,WAAO,oBAAC,QAAA,EAAK,qBAAmB,aAAc,UAAA,eAAc;AAAA,EAC9D;AAEA,SAAO;AAAA,IACL,OAAO;AAAA,MACL,CAAC,oBAAoB,GAAG;AAAA,IAAA;AAAA,EAC1B;AAEJ;ACxBO,SAAS,yBAAyB;AAAA,EACvC;AAAA,EACA,YAAY;AAAA,EACZ;AAAA,EACA,GAAG;AACL,GAAkC;AAChC,QAAM,mBAAmB,QAAQ,MAAM;AACrC,UAAM,0BAA0B,8BAA8B,qBAAqB,QAAQ;AAE3F,WAAK,iBAIE;AAAA,MACL,GAAG;AAAA,MACH,OAAO;AAAA,QACL,GAAG,eAAe;AAAA,QAClB,GAAG,wBAAwB;AAAA,MAAA;AAAA,IAC7B,IARO;AAAA,EAUX,GAAG,CAAC,qBAAqB,UAAU,cAAc,CAAC;AAElD,SAAO,oBAAC,cAAA,EAAc,GAAG,MAAM,YAAY,kBAAkB;AAC/D;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pte-interpolation-react",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "license": "MIT",
   "description": "React components for rendering Portable Text with interpolated values",
@@ -47,6 +47,10 @@
   },
   "devDependencies": {
     "@sanity/pkg-utils": "^10.4.4",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "rimraf": "^6.1.3",
     "typescript": "~5.9.3"
   },

package/src/InterpolatedPortableText.tsx

@@ -0,0 +1,31 @@
+import {PortableText} from '@portabletext/react'
+import {useMemo} from 'react'
+
+import {createInterpolationComponents} from './createInterpolationComponents'
+import type {InterpolatedPortableTextProps} from './types'
+
+/** @public */
+export function InterpolatedPortableText({
+  interpolationValues,
+  components: userComponents,
+  fallback,
+  ...rest
+}: InterpolatedPortableTextProps) {
+  const mergedComponents = useMemo(() => {
+    const interpolationComponents = createInterpolationComponents(interpolationValues, fallback)
+
+    if (!userComponents) {
+      return interpolationComponents
+    }
+
+    return {
+      ...userComponents,
+      types: {
+        ...userComponents.types,
+        ...interpolationComponents.types,
+      },
+    }
+  }, [interpolationValues, fallback, userComponents])
+
+  return <PortableText {...rest} components={mergedComponents} />
+}

package/src/__tests__/InterpolatedPortableText.test.tsx

@@ -0,0 +1,204 @@
+import type {PortableTextComponents} from '@portabletext/react'
+import {renderToStaticMarkup} from 'react-dom/server'
+import {describe, expect, it} from 'vitest'
+
+import {VARIABLE_TYPE_PREFIX} from '../constants'
+import {InterpolatedPortableText} from '../InterpolatedPortableText'
+import {
+  emptyBlocksContent,
+  multiBlockContent,
+  multipleVariablesBlock,
+  plainTextBlock,
+  singleVariableBlock,
+  styledTextWithVariableBlock,
+} from './fixtures'
+
+describe('InterpolatedPortableText', () => {
+  it('renders single variable resolved inline', () => {
+    const html = renderToStaticMarkup(
+      <InterpolatedPortableText
+        value={singleVariableBlock}
+        interpolationValues={{firstName: 'Jordan'}}
+      />,
+    )
+    expect(html).toContain('Hello, ')
+    expect(html).toContain('<span data-variable-key="firstName">Jordan</span>')
+    expect(html).toContain('!')
+  })
+
+  it('renders multiple variables in one block', () => {
+    const html = renderToStaticMarkup(
+      <InterpolatedPortableText
+        value={multipleVariablesBlock}
+        interpolationValues={{
+          firstName: 'Jordan',
+          lastName: 'Lawrence',
+          email: 'jordan@example.com',
+        }}
+      />,
+    )
+    expect(html).toContain('<span data-variable-key="firstName">Jordan</span>')
+    expect(html).toContain('<span data-variable-key="lastName">Lawrence</span>')
+    expect(html).toContain('<span data-variable-key="email">jordan@example.com</span>')
+  })
+
+  it('renders plain text unchanged', () => {
+    const html = renderToStaticMarkup(
+      <InterpolatedPortableText value={plainTextBlock} interpolationValues={{}} />,
+    )
+    expect(html).toContain('No variables here.')
+  })
+
+  it('renders fallback for missing values', () => {
+    const html = renderToStaticMarkup(
+      <InterpolatedPortableText value={singleVariableBlock} interpolationValues={{}} />,
+    )
+    expect(html).toContain('{firstName}')
+  })
+
+  it('uses custom fallback prop', () => {
+    const html = renderToStaticMarkup(
+      <InterpolatedPortableText
+        value={singleVariableBlock}
+        interpolationValues={{}}
+        fallback={(key) => `[${key}]`}
+      />,
+    )
+    expect(html).toContain('[firstName]')
+  })
+
+  it('preserves user components alongside interpolation types', () => {
+    const userComponents: PortableTextComponents = {
+      block: {
+        normal: ({children}) => <div data-testid="custom-block">{children}</div>,
+      },
+    }
+
+    const html = renderToStaticMarkup(
+      <InterpolatedPortableText
+        value={singleVariableBlock}
+        interpolationValues={{firstName: 'Jordan'}}
+        components={userComponents}
+      />,
+    )
+    expect(html).toContain('data-testid="custom-block"')
+    expect(html).toContain('<span data-variable-key="firstName">Jordan</span>')
+  })
+
+  it('renders variables across multiple blocks', () => {
+    const html = renderToStaticMarkup(
+      <InterpolatedPortableText
+        value={multiBlockContent}
+        interpolationValues={{
+          firstName: 'Jordan',
+          email: 'jordan@example.com',
+        }}
+      />,
+    )
+    expect(html).toContain('<span data-variable-key="firstName">Jordan</span>')
+    expect(html).toContain('<span data-variable-key="email">jordan@example.com</span>')
+    expect(html).toContain('Dear ')
+    expect(html).toContain('Your email is ')
+  })
+
+  it('interpolation types take precedence over user types with same key', () => {
+    const userComponents: PortableTextComponents = {
+      types: {
+        [VARIABLE_TYPE_PREFIX]: () => <span>user-override</span>,
+      },
+    }
+
+    const html = renderToStaticMarkup(
+      <InterpolatedPortableText
+        value={singleVariableBlock}
+        interpolationValues={{firstName: 'Jordan'}}
+        components={userComponents}
+      />,
+    )
+    expect(html).not.toContain('user-override')
+    expect(html).toContain('<span data-variable-key="firstName">Jordan</span>')
+  })
+
+  it('renders user custom types alongside interpolation types', () => {
+    const customWidgetBlock = [
+      {
+        _type: 'block',
+        _key: 'block-1',
+        style: 'normal' as const,
+        markDefs: [],
+        children: [
+          {_type: 'span', _key: 'span-1', text: 'Hello ', marks: []},
+          {_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 'firstName'},
+        ],
+      },
+      {
+        _type: 'customWidget',
+        _key: 'widget-1',
+        label: 'Click me',
+      },
+    ]
+
+    const userComponents: PortableTextComponents = {
+      types: {
+        customWidget: ({value}: {value: {label: string}}) => (
+          <button data-testid="widget">{value.label}</button>
+        ),
+      },
+    }
+
+    const html = renderToStaticMarkup(
+      <InterpolatedPortableText
+        value={customWidgetBlock}
+        interpolationValues={{firstName: 'Jordan'}}
+        components={userComponents}
+      />,
+    )
+    expect(html).toContain('data-testid="widget"')
+    expect(html).toContain('Click me')
+    expect(html).toContain('<span data-variable-key="firstName">Jordan</span>')
+  })
+
+  it('preserves user mark components', () => {
+    const userComponents: PortableTextComponents = {
+      marks: {
+        strong: ({children}) => <strong data-testid="custom-strong">{children}</strong>,
+      },
+    }
+
+    const html = renderToStaticMarkup(
+      <InterpolatedPortableText
+        value={styledTextWithVariableBlock}
+        interpolationValues={{firstName: 'Jordan'}}
+        components={userComponents}
+      />,
+    )
+    expect(html).toContain('data-testid="custom-strong"')
+    expect(html).toContain('<span data-variable-key="firstName">Jordan</span>')
+  })
+
+  it('renders without errors when value array is empty', () => {
+    const html = renderToStaticMarkup(
+      <InterpolatedPortableText value={emptyBlocksContent} interpolationValues={{}} />,
+    )
+    expect(html).toBe('')
+  })
+
+  it('default fallback renders exactly {variableKey} format', () => {
+    const html = renderToStaticMarkup(
+      <InterpolatedPortableText value={singleVariableBlock} interpolationValues={{}} />,
+    )
+    expect(html).toContain('<span data-variable-key="firstName">{firstName}</span>')
+  })
+
+  it('renders styled text marks alongside variables', () => {
+    const html = renderToStaticMarkup(
+      <InterpolatedPortableText
+        value={styledTextWithVariableBlock}
+        interpolationValues={{firstName: 'Jordan'}}
+      />,
+    )
+    expect(html).toContain('<strong>Welcome </strong>')
+    expect(html).toContain('<span data-variable-key="firstName">Jordan</span>')
+    expect(html).toContain('<em> aboard</em>')
+  })
+})

package/src/__tests__/createInterpolationComponents.test.tsx

@@ -0,0 +1,115 @@
+import {PortableText} from '@portabletext/react'
+import {renderToStaticMarkup} from 'react-dom/server'
+import {describe, expect, it} from 'vitest'
+
+import {VARIABLE_TYPE_PREFIX} from '../constants'
+import {createInterpolationComponents} from '../createInterpolationComponents'
+import {
+  consecutiveVariablesBlock,
+  multipleVariablesBlock,
+  singleVariableBlock,
+  variableOnlyBlock,
+} from './fixtures'
+
+describe('createInterpolationComponents', () => {
+  it('returns object with types.pteInterpolationVariable component', () => {
+    const components = createInterpolationComponents({firstName: 'Jordan'})
+    expect(components.types).toBeDefined()
+    expect(components.types).toHaveProperty('pteInterpolationVariable')
+  })
+
+  it('resolves variable value from the values map', () => {
+    const components = createInterpolationComponents({firstName: 'Jordan'})
+    const html = renderToStaticMarkup(
+      <PortableText value={singleVariableBlock} components={components} />,
+    )
+    expect(html).toContain('Jordan')
+    expect(html).toContain('data-variable-key="firstName"')
+  })
+
+  it('renders {variableKey} fallback for missing values', () => {
+    const components = createInterpolationComponents({})
+    const html = renderToStaticMarkup(
+      <PortableText value={singleVariableBlock} components={components} />,
+    )
+    expect(html).toContain('{firstName}')
+  })
+
+  it('renders empty string when value is explicitly ""', () => {
+    const components = createInterpolationComponents({firstName: ''})
+    const html = renderToStaticMarkup(
+      <PortableText value={singleVariableBlock} components={components} />,
+    )
+    expect(html).toContain('<span data-variable-key="firstName"></span>')
+    expect(html).not.toContain('{firstName}')
+  })
+
+  it('calls custom fallback function for missing values', () => {
+    const customFallback = (variableKey: string) => `[MISSING: ${variableKey}]`
+    const components = createInterpolationComponents({}, customFallback)
+    const html = renderToStaticMarkup(
+      <PortableText value={singleVariableBlock} components={components} />,
+    )
+    expect(html).toContain('[MISSING: firstName]')
+  })
+
+  it('renders inside <span> with data-variable-key attribute', () => {
+    const components = createInterpolationComponents({
+      firstName: 'Jordan',
+      lastName: 'Lawrence',
+      email: 'jordan@example.com',
+    })
+    const html = renderToStaticMarkup(
+      <PortableText value={multipleVariablesBlock} components={components} />,
+    )
+    expect(html).toContain('<span data-variable-key="firstName">Jordan</span>')
+    expect(html).toContain('<span data-variable-key="lastName">Lawrence</span>')
+    expect(html).toContain('<span data-variable-key="email">jordan@example.com</span>')
+  })
+
+  it('returns components with only a types key', () => {
+    const components = createInterpolationComponents({firstName: 'Jordan'})
+    expect(Object.keys(components)).toEqual(['types'])
+  })
+
+  it('registers component under VARIABLE_TYPE_PREFIX key', () => {
+    const components = createInterpolationComponents({firstName: 'Jordan'})
+    expect(Object.keys(components.types!)).toEqual([VARIABLE_TYPE_PREFIX])
+  })
+
+  it('falls back for all variables when values map is empty', () => {
+    const components = createInterpolationComponents({})
+    const html = renderToStaticMarkup(
+      <PortableText value={multipleVariablesBlock} components={components} />,
+    )
+    expect(html).toContain('{firstName}')
+    expect(html).toContain('{lastName}')
+    expect(html).toContain('{email}')
+  })
+
+  it('escapes HTML special characters in values', () => {
+    const components = createInterpolationComponents({firstName: '<script>alert("xss")</script>'})
+    const html = renderToStaticMarkup(
+      <PortableText value={singleVariableBlock} components={components} />,
+    )
+    expect(html).not.toContain('<script>')
+    expect(html).toContain('&lt;script&gt;')
+  })
+
+  it('renders consecutive variables without interference', () => {
+    const components = createInterpolationComponents({firstName: 'Jordan', lastName: 'Lawrence'})
+    const html = renderToStaticMarkup(
+      <PortableText value={consecutiveVariablesBlock} components={components} />,
+    )
+    expect(html).toContain('<span data-variable-key="firstName">Jordan</span>')
+    expect(html).toContain('<span data-variable-key="lastName">Lawrence</span>')
+  })
+
+  it('renders a variable as the only child in a block', () => {
+    const components = createInterpolationComponents({firstName: 'Jordan'})
+    const html = renderToStaticMarkup(
+      <PortableText value={variableOnlyBlock} components={components} />,
+    )
+    expect(html).toContain('<span data-variable-key="firstName">Jordan</span>')
+  })
+})

package/src/__tests__/fixtures.ts

@@ -0,0 +1,106 @@
+import type {PortableTextBlock} from '@portabletext/react'
+
+export const singleVariableBlock: PortableTextBlock[] = [
+  {
+    _type: 'block',
+    _key: 'block-1',
+    style: 'normal',
+    markDefs: [],
+    children: [
+      {_type: 'span', _key: 'span-1', text: 'Hello, ', marks: []},
+      {_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 'firstName'},
+      {_type: 'span', _key: 'span-2', text: '!', marks: []},
+    ],
+  },
+]
+
+export const multipleVariablesBlock: PortableTextBlock[] = [
+  {
+    _type: 'block',
+    _key: 'block-1',
+    style: 'normal',
+    markDefs: [],
+    children: [
+      {_type: 'span', _key: 'span-1', text: 'Name: ', marks: []},
+      {_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 'firstName'},
+      {_type: 'span', _key: 'span-2', text: ' ', marks: []},
+      {_type: 'pteInterpolationVariable', _key: 'var-2', variableKey: 'lastName'},
+      {_type: 'span', _key: 'span-3', text: ', Email: ', marks: []},
+      {_type: 'pteInterpolationVariable', _key: 'var-3', variableKey: 'email'},
+    ],
+  },
+]
+
+export const plainTextBlock: PortableTextBlock[] = [
+  {
+    _type: 'block',
+    _key: 'block-1',
+    style: 'normal',
+    markDefs: [],
+    children: [{_type: 'span', _key: 'span-1', text: 'No variables here.', marks: []}],
+  },
+]
+
+export const variableOnlyBlock: PortableTextBlock[] = [
+  {
+    _type: 'block',
+    _key: 'block-1',
+    style: 'normal',
+    markDefs: [],
+    children: [{_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 'firstName'}],
+  },
+]
+
+export const consecutiveVariablesBlock: PortableTextBlock[] = [
+  {
+    _type: 'block',
+    _key: 'block-1',
+    style: 'normal',
+    markDefs: [],
+    children: [
+      {_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 'firstName'},
+      {_type: 'pteInterpolationVariable', _key: 'var-2', variableKey: 'lastName'},
+    ],
+  },
+]
+
+export const styledTextWithVariableBlock: PortableTextBlock[] = [
+  {
+    _type: 'block',
+    _key: 'block-1',
+    style: 'normal',
+    markDefs: [],
+    children: [
+      {_type: 'span', _key: 'span-1', text: 'Welcome ', marks: ['strong']},
+      {_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 'firstName'},
+      {_type: 'span', _key: 'span-2', text: ' aboard', marks: ['em']},
+    ],
+  },
+]
+
+export const emptyBlocksContent: PortableTextBlock[] = []
+
+export const multiBlockContent: PortableTextBlock[] = [
+  {
+    _type: 'block',
+    _key: 'block-1',
+    style: 'normal',
+    markDefs: [],
+    children: [
+      {_type: 'span', _key: 'span-1', text: 'Dear ', marks: []},
+      {_type: 'pteInterpolationVariable', _key: 'var-1', variableKey: 'firstName'},
+      {_type: 'span', _key: 'span-2', text: ',', marks: []},
+    ],
+  },
+  {
+    _type: 'block',
+    _key: 'block-2',
+    style: 'normal',
+    markDefs: [],
+    children: [
+      {_type: 'span', _key: 'span-3', text: 'Your email is ', marks: []},
+      {_type: 'pteInterpolationVariable', _key: 'var-2', variableKey: 'email'},
+      {_type: 'span', _key: 'span-4', text: '.', marks: []},
+    ],
+  },
+]

package/src/constants.ts

@@ -0,0 +1,2 @@
+/** @public */
+export const VARIABLE_TYPE_PREFIX = 'pteInterpolationVariable'

package/src/createInterpolationComponents.tsx

@@ -0,0 +1,32 @@
+import type {PortableTextComponents, PortableTextTypeComponentProps} from '@portabletext/react'
+
+import {VARIABLE_TYPE_PREFIX} from './constants'
+import type {
+  InterpolationFallback,
+  InterpolationValues,
+  PteInterpolationVariableBlock,
+} from './types'
+
+function defaultFallback(variableKey: string): string {
+  return `{${variableKey}}`
+}
+
+/** @public */
+export function createInterpolationComponents(
+  values: InterpolationValues,
+  fallback: InterpolationFallback = defaultFallback,
+): PortableTextComponents {
+  function VariableComponent(props: PortableTextTypeComponentProps<PteInterpolationVariableBlock>) {
+    const {variableKey} = props.value
+    const resolvedValue =
+      values[variableKey] !== undefined ? values[variableKey] : fallback(variableKey)
+
+    return <span data-variable-key={variableKey}>{resolvedValue}</span>
+  }
+
+  return {
+    types: {
+      [VARIABLE_TYPE_PREFIX]: VariableComponent,
+    },
+  }
+}

package/src/index.ts

@@ -1,2 +1,9 @@
-export {InterpolatedText} from './InterpolatedText'
-export type {InterpolatedTextProps, InterpolationValues} from './types'
+export {InterpolatedPortableText} from './InterpolatedPortableText'
+export {createInterpolationComponents} from './createInterpolationComponents'
+export {VARIABLE_TYPE_PREFIX} from './constants'
+export type {
+  InterpolatedPortableTextProps,
+  InterpolationFallback,
+  InterpolationValues,
+  PteInterpolationVariableBlock,
+} from './types'

package/src/types.ts

@@ -1,10 +1,21 @@
-import type {PortableTextBlock} from '@portabletext/react'
+import type {PortableTextComponents, PortableTextProps} from '@portabletext/react'
 
 /** @public */
 export type InterpolationValues = Record<string, string>
 
 /** @public */
-export interface InterpolatedTextProps {
-  blocks: PortableTextBlock[]
-  values: InterpolationValues
+export type InterpolationFallback = (variableKey: string) => string
+
+/** @public */
+export interface PteInterpolationVariableBlock {
+  _type: 'pteInterpolationVariable'
+  _key: string
+  variableKey: string
+}
+
+/** @public */
+export interface InterpolatedPortableTextProps extends Omit<PortableTextProps, 'components'> {
+  interpolationValues: InterpolationValues
+  components?: PortableTextComponents
+  fallback?: InterpolationFallback
 }

package/src/InterpolatedText.tsx

@@ -1,10 +0,0 @@
-import type {InterpolatedTextProps} from './types'
-
-/** @public */
-export function InterpolatedText({blocks, values}: InterpolatedTextProps) {
-  return (
-    <pre>
-      <code>{JSON.stringify({blocks, values}, null, 2)}</code>
-    </pre>
-  )
-}

package/src/__tests__/InterpolatedText.test.tsx

@@ -1,9 +0,0 @@
-import {describe, expect, it} from 'vitest'
-import {InterpolatedText} from '../InterpolatedText'
-
-describe('InterpolatedText', () => {
-  it('should be defined', () => {
-    expect(InterpolatedText).toBeDefined()
-    expect(typeof InterpolatedText).toBe('function')
-  })
-})