feat!: use @portabletext/vue in <SanityContent> (#1251)

Author: parion

docs/content/2.helpers/1.portable-text.md

@@ -1,50 +1,85 @@
 ## Global helper
 
-This module defines a global `<SanityContent>` component that can turn portable text into HTML. It is a lightweight functional component without an instance.
+This module defines a global `<SanityContent>` component that can turn [portable text](https://www.sanity.io/guides/beginners-guide-to-portable-text) into HTML. It is a lightweight functional component without an instance.
 
-::alert{icon=💡}
-If you want to use the same serializers in multiple places, consider creating your own component (e.g. `<MySanityContent>` which wraps SanityContent, but with your default serializers. By creating `~/components/MySanityContent.vue` you should be able to use this everywhere in your app without importing it.
+As of v2, `<SanityContent>` uses [`@portabletext/vue`](https://github.com/portabletext/vue-portabletext) for rendering portable text. This means features and properties available to `@portabletext/vue` also work with `<SanityContent>`. Please refer to their [Usage guide](https://github.com/portabletext/vue-portabletext?tab=readme-ov-file#basic-usage) for advanced configuration options.
+
+::warning
+This render change introduces **breaking changes** for `<SanityContent>` v2 components. Refer to the following upgrade guide:
+* To reflect `@portabletext/vue`'s props, `blocks` → `value` and `serializers` → `components` attribute name changes have been made. The property types remain the same.
+* Custom components now receive their data nested within a `props.value` object. When defining components, you need to extract your props from this structure using object spreading: `{...props.value}`. This applies to all component types (blocks, marks, styles).
 ::
 
 ### Example
 
 ```vue
 <template>
-  <SanityContent :blocks="content" />
+  <SanityContent :value="content" />
 </template>
 ```
 
-### Example with custom serializers
+### Example with custom components
 
 ```vue
 <template>
-  <SanityContent :blocks="content" :serializers="serializers"  />
+  <SanityContent :value="content" :components="components" />
 </template>
 
 <script setup>
+import { defineAsyncComponent, h, resolveComponent } from 'vue'
 import CustomBlockComponent from '~/components/CustomBlockComponent.vue'
-import { resolveComponent } from 'vue'
 
-const serializers = {
+const components = {
   types: {
     // This is how to access a component registered by `@nuxt/components`
-    lazyRegisteredComponent: resolveComponent('LazyCustomSerializer'),
+    lazyRegisteredComponent: props => h(resolveComponent('LazyCustomSerializer'), {
+      ...props.value,
+    }),
     // A directly imported component
-    importedComponent: CustomBlockComponent,
+    importedComponent: props => h(CustomBlockComponent, {
+      ...props.value,
+    }),
     // Example of a more complex async component
-    dynamicComponent: defineAsyncComponent({
+    dynamicComponent: props => h(defineAsyncComponent({
       loadingComponent: () => 'Loading...',
       loader: () => import('~/other/component.vue'),
+    }), {
+      ...props.value,
     }),
   },
   marks: {
-    // You can also just pass a string for a custom serializer if it's an HTML element
-    internalLink: 'a'
+    // Custom marks handling
+    internalLink: props => h('a', { href: props.value.href }, props.text)
   }
 }
 </script>
 ```
 
+::warning
+If you want to use the same components in multiple places, consider creating your own component (e.g. `<MySanityContent>`) which wraps SanityContent with your default components. By creating `~/components/MySanityContent.vue` you should be able to use this everywhere in your app without importing it.
+::
+
+### Advanced Props
+
+The `SanityContent` component accepts all props from `@portabletext/vue`:
+
+```vue
+<template>
+  <SanityContent 
+    :value="content" 
+    :components="components"
+    :onMissingComponent="handleMissingComponent"
+    :listNestingMode="'html'" 
+  />
+</template>
+
+<script setup>
+const handleMissingComponent = (message, options) => {
+  console.warn(`Missing component: ${options.type} (${options.nodeType})`)
+}
+</script>
+```
+
 ## Other resources
 
-- [sanity-blocks-vue-component](https://github.com/rdunk/sanity-blocks-vue-component){ .text-primary-500 }
+- [@portabletext/vue](https://github.com/portabletext/vue-portabletext){ .text-primary-500 }

package.json

@@ -50,6 +50,7 @@
   "dependencies": {
     "@nuxt/kit": "^3.17.7",
     "@portabletext/types": "^2.0.13",
+    "@portabletext/vue": "^1.0.12",
     "@sanity/client": "^7.6.0",
     "@sanity/comlink": "^3.0.5",
     "@sanity/core-loader": "^1.8.10",

playground/pages/movie/[slug].vue

@@ -27,7 +27,7 @@
         asset-id="image-e22a88d23751a84df81f03ef287ae85fc992fe12-780x1170-jpg"
       />
       <div :data-sanity="encodeDataAttribute?.(['overview'])">
-        <SanityContent :blocks="details.overview" />
+        <SanityContent :value="details.overview" />
       </div>
     </template>
     <template v-else>

playground/pages/text.vue

@@ -1,36 +1,54 @@
 <template>
   <div>
+    <h1 class="text-2xl font-bold">
+      Sanity Content Example
+    </h1>
+    <p>This page demonstrates the use of custom serializers with Sanity content blocks.</p>
+    <h2 class="text-xl font-semibold">
+      SanityContent (Vue-PortableText)
+    </h2>
+    <p>This example uses the <a href="https://github.com/portabletext/vue-portabletext">vue-portabletext</a> library for rendering content.</p>
     <SanityContent
-      :blocks="blocks"
-      :serializers="serializers"
+      :value="value"
+      :components="components"
     />
   </div>
 </template>
 
 <script setup>
 import { defineComponent, defineAsyncComponent, resolveComponent, h } from 'vue'
 
-const serializers = {
+const components = {
   types: {
     // This registered by `@nuxt/components`
-    lazyRegisteredComponent: resolveComponent('LazyCustomSerializer'),
+    lazyRegisteredComponent: props => h(resolveComponent('LazyCustomSerializer'), {
+      ...props.value,
+    }),
     // An example of an inline component/directly imported component
-    importedComponent: defineComponent({
+    importedComponent: props => h(defineComponent({
       props: { someProp: String },
-      render: props => h('p', 'An inline/imported custom component: ' + props.someProp),
+      render(componentProps) {
+        return h('p', 'An inline/imported custom component: ' + componentProps.someProp)
+      },
+    }), {
+      ...props.value,
     }),
     // Example of an async component
-    dynamicComponent: defineAsyncComponent({
+    dynamicComponent: props => h(defineAsyncComponent({
       loadingComponent: () => 'Loading...',
       loader: () => Promise.resolve(defineComponent({
         props: { someProp: String },
-        render: props => h('p', 'An dynamically imported custom component: ' + props.someProp),
+        render(componentProps) {
+          return h('p', 'An dynamically imported custom component: ' + componentProps.someProp)
+        },
       })),
+    }), {
+      ...props.value,
     }),
   },
 }
 
-const blocks = [
+const value = [
   {
     _type: 'lazyRegisteredComponent',
     someProp: 'some value',