@portabletext/astro 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @portabletext/astro
 
+## 0.2.0
+
+### Minor Changes
+
+- [#4](https://github.com/portabletext/astro-portabletext/pull/4) [`0fd7cd3`](https://github.com/portabletext/astro-portabletext/commit/0fd7cd372df10919c6ff88d7533f4f7a0293a42e) Thanks [@msfragala](https://github.com/msfragala)! - Allow `PortableText` slots to be scoped to a specific type with `nodeType:type`, e.g. `block:h1`, `mark:link`, `list:bullet`, `listItem:number` and `type:myCustomType`. A scoped slot takes precedence over the node type it belongs to.
+
+  Slots now also take precedence over `render` from `usePortableText`. Previously a component reached through the `components` prop could displace a slot by rendering its children with `render`, so a slot for that node type never applied.
+
+  `Component` is now resolved lazily, so a slot that renders its own markup no longer reports a missing component. This makes a scoped slot enough on its own to render a custom type, which has no default component.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -7,11 +7,7 @@
 Render [Portable Text](https://portabletext.org) with [Astro](https://astro.build).
 
 > [!NOTE]
-> This package is a fork of [`astro-portabletext`](https://github.com/theisel/astro-portabletext)
-> by [Tom Theisel](https://github.com/theisel), maintained under the
-> [`@portabletext`](https://github.com/portabletext) organization. All credit for the original
-> design and implementation goes to Tom. It remains distributed under the original
-> [ISC License](./LICENSE). See [Migrating from `astro-portabletext`](#migrating-from-astro-portabletext).
+> This package is a fork of [`astro-portabletext`](https://github.com/theisel/astro-portabletext) by [Tom Theisel](https://github.com/theisel), maintained under the [`@portabletext`](https://github.com/portabletext) organization. All credit for the original design and implementation goes to Tom. It remains distributed under the original [ISC License](./LICENSE). See [Migrating from `astro-portabletext`](#migrating-from-astro-portabletext).
 
 ## Table of contents
 
@@ -40,8 +36,7 @@ npm install @portabletext/astro
 
 ## Basic usage
 
-Import the `PortableText` component and pass it a Portable Text value. The library provides sensible
-defaults for rendering all standard Portable Text elements, which you can override.
+Import the `PortableText` component and pass it a Portable Text value. The library provides sensible defaults for rendering all standard Portable Text elements, which you can override.
 
 ```astro
 ---
@@ -66,9 +61,7 @@ const portableText = [
 
 ## Sanity integration
 
-This library's predecessor is
-[officially recommended](https://www.sanity.io/plugins/sanity-astro#rendering-rich-text-and-block-content-with-portable-text)
-by [Sanity](https://sanity.io) for rendering Portable Text in Astro projects. Helpful resources:
+This library's predecessor is [officially recommended](https://www.sanity.io/plugins/sanity-astro#rendering-rich-text-and-block-content-with-portable-text) by [Sanity](https://sanity.io) for rendering Portable Text in Astro projects. Helpful resources:
 
 - [Sanity integration for Astro](https://www.sanity.io/plugins/sanity-astro)
 - [Guide: building a blog with Sanity and Astro](https://www.sanity.io/guides/sanity-astro-blog)
@@ -77,9 +70,7 @@ by [Sanity](https://sanity.io) for rendering Portable Text in Astro projects. He
 
 ### Default components
 
-Default components are provided for all standard features of the Portable Text spec, with logical
-HTML defaults. Provided components are merged with the defaults, so you only need to provide the
-things you want to override.
+Default components are provided for all standard features of the Portable Text spec, with logical HTML defaults. Provided components are merged with the defaults, so you only need to provide the things you want to override.
 
 <details>
   <summary>View the default structure and output</summary>
@@ -126,8 +117,7 @@ things you want to override.
 
 ### Custom components
 
-Custom components give you control over how each node is rendered. Map a component to a whole node
-type, or to a specific property (style, mark type, list item type, etc.) of that node type.
+Custom components give you control over how each node is rendered. Map a component to a whole node type, or to a specific property (style, mark type, list item type, etc.) of that node type.
 
 ```astro
 ---
@@ -165,8 +155,7 @@ const components = {
 <PortableText value={portableText} components={components} />
 ```
 
-Each custom component receives `node`, `index` and `isInline` props, and renders any children
-through a `<slot />`. For example, a custom `link` mark:
+Each custom component receives `node`, `index` and `isInline` props, and renders any children through a `<slot />`. For example, a custom `link` mark:
 
 ```astro
 ---
@@ -183,9 +172,7 @@ const href = node.markDef?.href
 
 ### Slots
 
-Slots provide a flexible way to enhance rendering by passing additional props to the resolved
-component - for example applying custom classes or wrapping elements - without replacing the default
-component entirely.
+Slots provide a flexible way to enhance rendering by passing additional props to the resolved component - for example applying custom classes or wrapping elements - without replacing the default component entirely.
 
 ```astro
 ---
@@ -211,6 +198,86 @@ const portableText = [
 </style>
 ```
 
+A slot named after a node type applies to every node of that type: `type`, `block`, `list`, `listItem`, `mark`, `text` and `hardBreak`. To target a single block style, list type, mark type or custom type, scope the slot name with `nodeType:type`.
+
+```astro
+<PortableText value={portableText}>
+  <fragment slot="block:h1">
+    {({Component, props, children}) => (
+      <Component {...props} class="heading">{children}</Component>
+    )}
+  </fragment>
+  <fragment slot="mark:link">
+    {({Component, props, children}) => (
+      <Component {...props} rel="noopener">{children}</Component>
+    )}
+  </fragment>
+  <fragment slot="type:callout">
+    {({props}) => <aside class="callout">{props.node.text}</aside>}
+  </fragment>
+</PortableText>
+```
+
+A slot only has a `Component` to render when the node type has one. Standard block styles, list types and mark types all ship defaults, but `components.type` starts out empty - a custom type has no default component. So a slot for a custom type either renders its own markup, as `type:callout` does above, or registers a component to receive:
+
+```astro
+<PortableText value={portableText} components={{type: {callout: Callout}}}>
+  <fragment slot="type:callout">
+    {({Component, props}) => <Component {...props} class="callout" />}
+  </fragment>
+</PortableText>
+```
+
+Asking for `Component` when the node type has none gives you the unknown-type component and reports the missing component through [`onMissingComponent`](#portabletext-component-properties). A slot that never touches `Component` renders cleanly.
+
+A scoped slot takes precedence over the node type it belongs to, so `block` can handle every block while `block:h1` handles headings.
+
+```astro
+<PortableText value={portableText}>
+  <!-- Every block except `h1` -->
+  <fragment slot="block">
+    {({Component, props, children}) => (
+      <Component {...props} class="block">{children}</Component>
+    )}
+  </fragment>
+  <fragment slot="block:h1">
+    {({Component, props, children}) => (
+      <Component {...props} class="heading">{children}</Component>
+    )}
+  </fragment>
+</PortableText>
+```
+
+The `text` and `hardBreak` node types have no types of their own, so they cannot be scoped.
+
+#### Slots and the `components` prop
+
+A slot does not replace the [`components`](#customizing-components) prop, it wraps it. The `Component` handed to a slot is whatever the `components` prop resolved to for that node, so the two compose - the slot decides how the resolved component is rendered.
+
+```astro
+<PortableText value={portableText} components={{block: {h1: MyHeading}}}>
+  <fragment slot="block:h1">
+    <!-- `Component` is `MyHeading` -->
+    {({Component, props, children}) => (
+      <Component {...props} class="heading">{children}</Component>
+    )}
+  </fragment>
+</PortableText>
+```
+
+Slots belong to the author of the `PortableText` element, so they always win. A component reached through the `components` prop can customize its own children with [`render`](#useportabletext), but a slot for that node type takes precedence over it.
+
+```astro
+<PortableText value={portableText} components={{block: MyBlock}}>
+  <!-- Applies even if `MyBlock` renders its children with `render({mark: ...})` -->
+  <fragment slot="mark">
+    {({Component, props, children}) => (
+      <Component {...props} class="mark">{children}</Component>
+    )}
+  </fragment>
+</PortableText>
+```
+
 ## `PortableText` component properties
 
 | Property                        | Type                    | Description                                                                                                                                 |
@@ -228,8 +295,7 @@ import {usePortableText, mergeComponents, toPlainText, spanToPlainText} from '@p
 
 ### `usePortableText`
 
-Within a component passed into the `components` prop, `usePortableText(node)` returns rendering
-utilities scoped to that node: `getDefaultComponent()`, `getUnknownComponent()` and `render()`.
+Within a component passed into the `components` prop, `usePortableText(node)` returns rendering utilities scoped to that node: `getDefaultComponent()`, `getUnknownComponent()` and `render()`.
 
 ```astro
 ---
@@ -248,8 +314,7 @@ const Default = getDefaultComponent()
 
 ### `mergeComponents`
 
-Merges two component maps, giving priority to the overrides. Useful for extending a shared base set
-of components.
+Merges two component maps, giving priority to the overrides. Useful for extending a shared base set of components.
 
 ```js
 import {mergeComponents} from '@portabletext/astro'
@@ -261,8 +326,7 @@ const components = mergeComponents(baseComponents, {
 
 ### `toPlainText`
 
-Renders one or more Portable Text blocks as a plain string - handy for meta descriptions or
-generating slugs. `spanToPlainText` does the same for a single span's children.
+Renders one or more Portable Text blocks as a plain string - handy for meta descriptions or generating slugs. `spanToPlainText` does the same for a single span's children.
 
 ```astro
 ---
@@ -275,8 +339,7 @@ const text = toPlainText(node)
 
 ## Migrating from `astro-portabletext`
 
-`@portabletext/astro` is a drop-in fork of [`astro-portabletext`](https://github.com/theisel/astro-portabletext).
-To migrate, swap the dependency and update your imports:
+`@portabletext/astro` is a drop-in fork of [`astro-portabletext`](https://github.com/theisel/astro-portabletext). To migrate, swap the dependency and update your imports:
 
 ```diff
 - import {PortableText} from 'astro-portabletext'

package/components/PortableText.astro

@@ -24,12 +24,20 @@ import type {
 
 import {
   isComponent,
+  isSlotName,
   mergeComponents,
   setNodeComponents,
   getNodeComponents,
+  toSlotName,
 } from "../lib/internal";
+import type { SlotNodeType } from "../lib/internal";
 
-import { getWarningMessage, printWarning } from "../lib/warnings";
+import {
+  getWarningMessage,
+  ignoredChildrenWarning,
+  printWarning,
+  unknownSlotWarning,
+} from "../lib/warnings";
 import { key as contextRef } from "../lib/context";
 
 import Block from "./Block.astro";
@@ -137,6 +145,18 @@ const provideComponent = (
   return fallbackComponent;
 };
 
+type RunArgs = {
+  nodeType: SlotNodeType;
+  /** Block style, list type, mark type or custom `_type`, when there is one */
+  type?: string;
+  // Loosely typed: each `RenderOptions` entry narrows `node` to its own type
+  handler: ((handlerProps: any) => any) | undefined;
+  /** Called only if something actually asks for the node's `Component` */
+  resolveComponent: () => Component;
+  props: ComponentProps<TypedObject>;
+  children?: unknown;
+};
+
 // The local render function will override these options
 let fallbackRenderOptions: Required<RenderOptions> | undefined;
 
@@ -154,25 +174,55 @@ const portableTextRender = (options: RenderOptions, isInline?: boolean) => {
   const renderOptions = { ...fallbackRenderOptions, ...options };
 
   return function renderNode(node: TypedObject, index: number): any {
-    function run<H extends (...args: any) => any, P = Parameters<H>[0]>(
-      handler: H | undefined,
-      props: P
-    ) {
+    function run({
+      nodeType,
+      type,
+      handler,
+      resolveComponent,
+      props,
+      children,
+    }: RunArgs) {
+      let component: Component | undefined;
+
+      const handlerProps = {
+        // Resolved lazily. A slot rendering its own markup never asks for
+        // `Component`, and so must not trigger a missing component warning.
+        get Component() {
+          return (component ??= resolveComponent());
+        },
+        props,
+        children,
+      };
+
+      // A slot always wins. `renderOptions` may have been overridden by a component
+      // from the `components` prop calling `render` from `usePortableText`, which
+      // must not take the slot away from the author of this `PortableText`.
+      const slotRenderer = provideSlot(nodeType, type);
+
+      if (slotRenderer) {
+        return slotRenderer([handlerProps]);
+      }
+
       if (!isComponent(handler)) {
         throw new Error(
           `[PortableText render] No handler found for node type ${node._type}.`
         );
       }
 
-      return handler(props);
+      return handler(handlerProps);
     }
 
     if (isPortableTextToolkitList(node)) {
+      const listType = node.listItem;
       const UnknownComponent = components.unknownList ?? UnknownList;
       setNodeComponents(node, List, UnknownComponent);
 
-      return run(renderOptions.list, {
-        Component: provideComponent("list", node.listItem, UnknownComponent),
+      return run({
+        nodeType: "list",
+        type: listType,
+        handler: renderOptions.list,
+        resolveComponent: () =>
+          provideComponent("list", listType, UnknownComponent),
         props: asComponentProps(node, index, false),
         children: renderChildren(node.children, false),
       });
@@ -189,12 +239,12 @@ const portableTextRender = (options: RenderOptions, isInline?: boolean) => {
       const UnknownComponent = components.unknownListItem ?? UnknownListItem;
       setNodeComponents(node, ListItem, UnknownComponent);
 
-      return run(renderOptions.listItem, {
-        Component: provideComponent(
-          "listItem",
-          node.listItem,
-          UnknownComponent
-        ),
+      return run({
+        nodeType: "listItem",
+        type: listItem,
+        handler: renderOptions.listItem,
+        resolveComponent: () =>
+          provideComponent("listItem", listItem, UnknownComponent),
         props: asComponentProps(node, index, false),
         children: isStyled
           ? node.children
@@ -203,11 +253,16 @@ const portableTextRender = (options: RenderOptions, isInline?: boolean) => {
     }
 
     if (isPortableTextToolkitSpan(node)) {
+      const markType = node.markType;
       const UnknownComponent = components.unknownMark ?? UnknownMark;
       setNodeComponents(node, Mark, UnknownComponent);
 
-      return run(renderOptions.mark, {
-        Component: provideComponent("mark", node.markType, UnknownComponent),
+      return run({
+        nodeType: "mark",
+        type: markType,
+        handler: renderOptions.mark,
+        resolveComponent: () =>
+          provideComponent("mark", markType, UnknownComponent),
         props: asComponentProps(node, index, true),
         children: renderChildren(node.children, true),
       });
@@ -217,11 +272,16 @@ const portableTextRender = (options: RenderOptions, isInline?: boolean) => {
       node.style ??= "normal"; /* Make sure style has been set */
       node.children = buildMarksTree(node);
 
+      const style = node.style;
       const UnknownComponent = components.unknownBlock ?? UnknownBlock;
       setNodeComponents(node, Block, UnknownComponent);
 
-      return run(renderOptions.block, {
-        Component: provideComponent("block", node.style, UnknownComponent),
+      return run({
+        nodeType: "block",
+        type: style,
+        handler: renderOptions.block,
+        resolveComponent: () =>
+          provideComponent("block", style, UnknownComponent),
         props: asComponentProps(node, index, false),
         children: renderChildren(node.children, true),
       });
@@ -232,25 +292,36 @@ const portableTextRender = (options: RenderOptions, isInline?: boolean) => {
       const props = asComponentProps(node, index, true);
 
       if (isHardBreak) {
-        return run(renderOptions.hardBreak, {
-          Component: isComponent(components.hardBreak)
-            ? components.hardBreak
-            : HardBreak,
+        return run({
+          nodeType: "hardBreak",
+          handler: renderOptions.hardBreak,
+          resolveComponent: () =>
+            isComponent(components.hardBreak)
+              ? components.hardBreak
+              : HardBreak,
           props,
         });
       }
 
-      return run(renderOptions.text, {
-        Component: isComponent(components.text) ? components.text : Text,
+      return run({
+        nodeType: "text",
+        handler: renderOptions.text,
+        resolveComponent: () =>
+          isComponent(components.text) ? components.text : Text,
         props,
       });
     }
 
     // Custom type
+    const customType = node._type;
     const UnknownComponent = components.unknownType ?? UnknownType;
 
-    return run(renderOptions.type, {
-      Component: provideComponent("type", node._type, UnknownComponent),
+    return run({
+      nodeType: "type",
+      type: customType,
+      handler: renderOptions.type,
+      resolveComponent: () =>
+        provideComponent("type", customType, UnknownComponent),
       props: asComponentProps(
         node,
         index,
@@ -346,47 +417,66 @@ const createSlotRenderer = (slotName: string) =>
 
 type SlotRenderer = ReturnType<typeof createSlotRenderer>;
 
-const slots = [
-  "type",
-  "block",
-  "list",
-  "listItem",
-  "mark",
-  "text",
-  "hardBreak",
-].reduce(
-  (obj, name) => {
-    obj[name] = Astro.slots.has(name) ? createSlotRenderer(name) : undefined;
-    return obj;
-  },
-  {} as Record<string, SlotRenderer | undefined>
-);
+const slotRenderers = new Map<string, SlotRenderer | undefined>();
+
+const provideSlotRenderer = (slotName: string): SlotRenderer | undefined => {
+  if (!slotRenderers.has(slotName)) {
+    slotRenderers.set(
+      slotName,
+      Astro.slots.has(slotName) ? createSlotRenderer(slotName) : undefined
+    );
+  }
+
+  return slotRenderers.get(slotName);
+};
+
+/**
+ * Resolves the slot to render a node with.
+ * A slot scoped to a type, e.g. `block:h1`, takes precedence over `block`.
+ */
+const provideSlot = (
+  nodeType: SlotNodeType,
+  type?: string
+): SlotRenderer | undefined =>
+  (type ? provideSlotRenderer(toSlotName(nodeType, type)) : undefined) ??
+  provideSlotRenderer(nodeType);
+
+// A slot targeting an unrecognised node type never renders, so let the author
+// know rather than silently ignoring it.
+if (import.meta.env.DEV) {
+  for (const slotName of Object.keys(Astro.slots)) {
+    if (isSlotName(slotName)) continue;
+
+    printWarning(
+      "default" === slotName
+        ? ignoredChildrenWarning()
+        : unknownSlotWarning(slotName)
+    );
+  }
+}
 
+// Slots are resolved by `portableTextRender`, so every node type falls back to
+// simply rendering its resolved component.
 type RenderNode = (
-  slotRenderer: SlotRenderer | undefined
-) => (
   props: Parameters<NonNullable<RenderOptions[keyof RenderOptions]>>[0]
 ) => any;
 ---
 
 {
   (() => {
-    const renderNode: RenderNode = (slotRenderer) => {
-      return ({ Component, props, children }) =>
-        slotRenderer?.([{ Component, props, children }]) ?? (
-          <Component {...(props as any)}>{children}</Component>
-        );
-    };
+    const renderNode: RenderNode = ({ Component, props, children }) => (
+      <Component {...(props as any)}>{children}</Component>
+    );
 
     return nodes.map(
       render({
-        type: renderNode(slots.type),
-        block: renderNode(slots.block),
-        list: renderNode(slots.list),
-        listItem: renderNode(slots.listItem),
-        mark: renderNode(slots.mark),
-        text: renderNode(slots.text),
-        hardBreak: renderNode(slots.hardBreak),
+        type: renderNode,
+        block: renderNode,
+        list: renderNode,
+        listItem: renderNode,
+        mark: renderNode,
+        text: renderNode,
+        hardBreak: renderNode,
       })
     );
   })()

package/lib/internal.ts

@@ -1,4 +1,10 @@
-import type {Component, ComponentOrRecord, SomePortableTextComponents, TypedObject} from './types'
+import type {
+  Component,
+  ComponentOrRecord,
+  NodeType,
+  SomePortableTextComponents,
+  TypedObject,
+} from './types'
 
 /**
  * Helper for component to throw an error
@@ -62,6 +68,80 @@ export function mergeComponents<
   }
 }
 
+/**
+ * =====
+ * Slots
+ * =====
+ */
+
+/**
+ * A node type that a `PortableText` slot can target. `text` and `hardBreak` have
+ * no types of their own, so they round out the scopeable `NodeType`s.
+ * @internal
+ */
+export type SlotNodeType = NodeType | 'text' | 'hardBreak'
+
+/**
+ * Node types that a `PortableText` slot can target, mapped to whether the slot
+ * name can be scoped to a specific type, e.g. `block:h1`.
+ * @internal
+ *
+ * @remarks
+ * `satisfies` keeps this map exhaustive - adding a `NodeType` will not compile
+ * until it is given an entry here.
+ */
+const slotNodeTypes = {
+  type: true,
+  block: true,
+  list: true,
+  listItem: true,
+  mark: true,
+  text: false,
+  hardBreak: false,
+} as const satisfies Record<SlotNodeType, boolean>
+
+/**
+ * The node types that a `PortableText` slot can target.
+ * @internal
+ */
+export const slotNames: readonly SlotNodeType[] = Object.keys(slotNodeTypes) as SlotNodeType[]
+
+/**
+ * Builds the name of the slot that renders the given node type, optionally
+ * scoped to a specific `type` such as a block style or a mark type.
+ * @internal
+ */
+export function toSlotName(nodeType: string, type?: string): string {
+  return type ? `${nodeType}:${type}` : nodeType
+}
+
+/**
+ * Returns true if `slotName` targets a node type that is rendered by `PortableText`.
+ * @internal
+ *
+ * @remarks
+ * The scope of a scoped slot name, e.g. the `h1` of `block:h1`, cannot be verified
+ * upfront as block styles, mark types and custom types are user defined.
+ */
+export function isSlotName(slotName: string): boolean {
+  const separator = slotName.indexOf(':')
+
+  // `Object.hasOwn` rather than `in`, so inherited keys such as `toString` and
+  // `constructor` are not mistaken for node types.
+  if (separator === -1) {
+    return Object.hasOwn(slotNodeTypes, slotName)
+  }
+
+  const nodeType = slotName.slice(0, separator)
+  const scope = slotName.slice(separator + 1)
+
+  return (
+    Object.hasOwn(slotNodeTypes, nodeType) &&
+    slotNodeTypes[nodeType as SlotNodeType] &&
+    scope.length > 0
+  )
+}
+
 /**
  * ========================
  * Node Components Registry

package/lib/warnings.ts

@@ -1,3 +1,4 @@
+import {slotNames} from './internal'
 import type {NodeType} from './types'
 
 const getTemplate = (prop: string, type: string): string =>
@@ -14,6 +15,15 @@ export const unknownListWarning = (listItem: string): string => getTemplate('lis
 export const unknownListItemWarning = (listStyle: string): string =>
   getTemplate('listItem', listStyle)
 
+export const unknownSlotWarning = (slotName: string): string =>
+  `PortableText slot "${slotName}" does not target a node type and will be ignored. ` +
+  `Expected ${slotNames.map((it) => `"${it}"`).join(', ')}, ` +
+  `optionally scoped to a type, e.g. "block:h1"`
+
+export const ignoredChildrenWarning = (): string =>
+  'PortableText was given children that are not assigned to a slot, so they will be ignored. ' +
+  'Assign them to a node type, e.g. <fragment slot="block">'
+
 export const getWarningMessage = (nodeType: NodeType, type: string) => {
   const fncs = {
     block: unknownBlockWarning,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portabletext/astro",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Render Portable Text with Astro",
   "keywords": [
     "astro",