@portabletext/astro 0.0.0 → 0.2.0

package/components/PortableText.astro

@@ -0,0 +1,483 @@
+---
+import {
+  isPortableTextBlock,
+  isPortableTextListItemBlock,
+  isPortableTextToolkitList,
+  isPortableTextToolkitSpan,
+  isPortableTextToolkitTextNode,
+  nestLists,
+  buildMarksTree,
+  LIST_NEST_MODE_HTML,
+} from "@portabletext/toolkit";
+
+import type {
+  Component,
+  Context,
+  MissingComponentHandler,
+  NodeType,
+  PortableTextComponents,
+  PortableTextProps,
+  Props as ComponentProps,
+  RenderOptions,
+  TypedObject,
+} from "../lib/types";
+
+import {
+  isComponent,
+  isSlotName,
+  mergeComponents,
+  setNodeComponents,
+  getNodeComponents,
+  toSlotName,
+} from "../lib/internal";
+import type { SlotNodeType } from "../lib/internal";
+
+import {
+  getWarningMessage,
+  ignoredChildrenWarning,
+  printWarning,
+  unknownSlotWarning,
+} from "../lib/warnings";
+import { key as contextRef } from "../lib/context";
+
+import Block from "./Block.astro";
+import HardBreak from "./HardBreak.astro";
+import List from "./List.astro";
+import ListItem from "./ListItem.astro";
+import Mark from "./Mark.astro";
+import Text from "./Text.astro";
+import UnknownBlock from "./UnknownBlock.astro";
+import UnknownList from "./UnknownList.astro";
+import UnknownListItem from "./UnknownListItem.astro";
+import UnknownMark from "./UnknownMark.astro";
+import UnknownType from "./UnknownType.astro";
+
+export type Props = PortableTextProps;
+
+const {
+  value,
+  components: componentOverrides = {},
+  listNestingMode = LIST_NEST_MODE_HTML,
+  onMissingComponent = true,
+} = Astro.props;
+
+const components = mergeComponents(
+  {
+    type: {},
+    unknownType: UnknownType,
+    block: {
+      h1: Block,
+      h2: Block,
+      h3: Block,
+      h4: Block,
+      h5: Block,
+      h6: Block,
+      blockquote: Block,
+      normal: Block,
+    },
+    unknownBlock: UnknownBlock,
+    list: {
+      bullet: List,
+      number: List,
+      menu: List,
+    },
+    unknownList: UnknownList,
+    listItem: {
+      bullet: ListItem,
+      number: ListItem,
+      menu: ListItem,
+    },
+    unknownListItem: UnknownListItem,
+    mark: {
+      code: Mark,
+      em: Mark,
+      link: Mark,
+      "strike-through": Mark,
+      strong: Mark,
+      underline: Mark,
+    },
+    unknownMark: UnknownMark,
+    text: Text,
+    hardBreak: HardBreak,
+  },
+  componentOverrides
+) as PortableTextComponents;
+
+const noop = () => {};
+
+const missingComponentHandler = ((
+  handler: unknown
+): MissingComponentHandler => {
+  if (typeof handler === "function") {
+    return handler as MissingComponentHandler;
+  }
+  return !handler ? noop : printWarning;
+})(onMissingComponent);
+
+const asComponentProps = <T extends TypedObject>(
+  node: T,
+  index: number,
+  isInline: boolean
+): ComponentProps<T> => ({
+  node,
+  index,
+  isInline,
+});
+
+const provideComponent = (
+  nodeType: NodeType,
+  type: string,
+  fallbackComponent: Component
+): Component => {
+  const component: Component | undefined = ((entry) => {
+    return entry[type as keyof typeof entry] || entry;
+  })(components[nodeType]);
+
+  if (isComponent(component)) {
+    return component;
+  }
+
+  missingComponentHandler(getWarningMessage(nodeType, type), {
+    nodeType,
+    type,
+  });
+
+  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;
+
+const portableTextRender = (options: RenderOptions, isInline?: boolean) => {
+  if (!fallbackRenderOptions) {
+    throw new Error(
+      "[PortableText portableTextRender] fallbackRenderOptions is undefined"
+    );
+  }
+
+  const renderChildren = (children?: TypedObject[], inline = false) => {
+    return children?.map(portableTextRender(options, inline)) ?? [];
+  };
+
+  const renderOptions = { ...fallbackRenderOptions, ...options };
+
+  return function renderNode(node: TypedObject, index: number): any {
+    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(handlerProps);
+    }
+
+    if (isPortableTextToolkitList(node)) {
+      const listType = node.listItem;
+      const UnknownComponent = components.unknownList ?? UnknownList;
+      setNodeComponents(node, List, 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),
+      });
+    }
+
+    if (isPortableTextListItemBlock(node)) {
+      const { listItem, ...blockNode } = node;
+      const isStyled = node.style && node.style !== "normal";
+      // Apply block style if defined (and not "normal"), otherwise render with marks.
+      node.children = isStyled
+        ? renderNode(blockNode, index)
+        : buildMarksTree(node);
+
+      const UnknownComponent = components.unknownListItem ?? UnknownListItem;
+      setNodeComponents(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
+          : renderChildren(node.children, true),
+      });
+    }
+
+    if (isPortableTextToolkitSpan(node)) {
+      const markType = node.markType;
+      const UnknownComponent = components.unknownMark ?? UnknownMark;
+      setNodeComponents(node, Mark, 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),
+      });
+    }
+
+    if (isPortableTextBlock(node)) {
+      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({
+        nodeType: "block",
+        type: style,
+        handler: renderOptions.block,
+        resolveComponent: () =>
+          provideComponent("block", style, UnknownComponent),
+        props: asComponentProps(node, index, false),
+        children: renderChildren(node.children, true),
+      });
+    }
+
+    if (isPortableTextToolkitTextNode(node)) {
+      const isHardBreak = "\n" === node.text;
+      const props = asComponentProps(node, index, true);
+
+      if (isHardBreak) {
+        return run({
+          nodeType: "hardBreak",
+          handler: renderOptions.hardBreak,
+          resolveComponent: () =>
+            isComponent(components.hardBreak)
+              ? components.hardBreak
+              : HardBreak,
+          props,
+        });
+      }
+
+      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({
+      nodeType: "type",
+      type: customType,
+      handler: renderOptions.type,
+      resolveComponent: () =>
+        provideComponent("type", customType, UnknownComponent),
+      props: asComponentProps(
+        node,
+        index,
+        isInline ?? false /* default to block */
+      ),
+    });
+  };
+};
+
+(globalThis as any)[contextRef] = (
+  node: TypedObject & { children?: TypedObject[] }
+): Context => ({
+  getDefaultComponent: provideDefaultComponent.bind(null, node),
+  getUnknownComponent: provideUnknownComponent.bind(null, node),
+  render: (options) => node.children?.map(portableTextRender(options)),
+});
+
+// Returns the `default` component related to the passed in node
+const provideDefaultComponent = (node: TypedObject) => {
+  const DefaultComponent = getNodeComponents(node)?.Default;
+  if (DefaultComponent) return DefaultComponent;
+
+  // Cache missed use manual lookup
+  if (import.meta.env.DEV) {
+    // oxlint-disable-next-line no-console
+    console.warn(
+      `[@portabletext/astro] Cache missed for default component on node type "${node._type}". Ensure you are passing in the original "node" prop.`
+    );
+  }
+
+  if (isPortableTextToolkitList(node)) return List;
+  if (isPortableTextListItemBlock(node)) return ListItem;
+  if (isPortableTextToolkitSpan(node)) return Mark;
+  if (isPortableTextBlock(node)) return Block;
+
+  if (isPortableTextToolkitTextNode(node)) {
+    return "\n" === node.text ? HardBreak : Text;
+  }
+
+  return UnknownType;
+};
+
+// Returns the `unknown` component related to the passed in node
+const provideUnknownComponent = (node: TypedObject) => {
+  const UnknownComponent = getNodeComponents(node)?.Unknown;
+  if (UnknownComponent) return UnknownComponent;
+
+  // Cache missed use manual lookup
+  if (import.meta.env.DEV) {
+    // oxlint-disable-next-line no-console
+    console.warn(
+      `[@portabletext/astro] Cache missed for unknown component on node type "${node._type}". Ensure you are passing in the original "node" prop.`
+    );
+  }
+
+  if (isPortableTextToolkitList(node)) {
+    return components.unknownList ?? UnknownList;
+  }
+
+  if (isPortableTextListItemBlock(node)) {
+    return components.unknownListItem ?? UnknownListItem;
+  }
+
+  if (isPortableTextToolkitSpan(node)) {
+    return components.unknownMark ?? UnknownMark;
+  }
+
+  if (isPortableTextBlock(node)) {
+    return components.unknownBlock ?? UnknownBlock;
+  }
+
+  if (!isPortableTextToolkitTextNode(node)) {
+    return components.unknownType ?? UnknownType;
+  }
+
+  throw new Error(
+    `[PortableText getUnknownComponent] Unable to provide component with node type ${node._type}`
+  );
+};
+
+// Make sure we have an array of blocks
+const blocks = Array.isArray(value) ? value : value ? [value] : [];
+const nodes = nestLists(blocks, listNestingMode);
+
+const render = (options: NonNullable<typeof fallbackRenderOptions>) => {
+  fallbackRenderOptions = options;
+  return portableTextRender(options);
+};
+
+// Create a slot renderer for a specific slot
+const createSlotRenderer = (slotName: string) =>
+  Astro.slots.render.bind(Astro.slots, slotName);
+
+type SlotRenderer = ReturnType<typeof createSlotRenderer>;
+
+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 = (
+  props: Parameters<NonNullable<RenderOptions[keyof RenderOptions]>>[0]
+) => any;
+---
+
+{
+  (() => {
+    const renderNode: RenderNode = ({ Component, props, children }) => (
+      <Component {...(props as any)}>{children}</Component>
+    );
+
+    return nodes.map(
+      render({
+        type: renderNode,
+        block: renderNode,
+        list: renderNode,
+        listItem: renderNode,
+        mark: renderNode,
+        text: renderNode,
+        hardBreak: renderNode,
+      })
+    );
+  })()
+}

package/components/Text.astro

@@ -0,0 +1,9 @@
+---
+import type { TextNode, Props as $ } from "../lib/types";
+
+export type Props = $<TextNode>;
+
+const { node } = Astro.props;
+---
+
+{node.text}

package/components/UnknownBlock.astro

@@ -0,0 +1,7 @@
+---
+import type { Block, Props as $ } from "../lib/types";
+
+export type Props = $<Block>;
+---
+
+<p data-portabletext-unknown="block"><slot /></p>

package/components/UnknownList.astro

@@ -0,0 +1,7 @@
+---
+import type { Props as $, List } from "../lib/types";
+
+export type Props = $<List>;
+---
+
+<ul data-portabletext-unknown="list"><slot /></ul>

package/components/UnknownListItem.astro

@@ -0,0 +1,7 @@
+---
+import type { Props as $, ListItem } from "../lib/types";
+
+export type Props = $<ListItem>;
+---
+
+<li data-portabletext-unknown="listitem"><slot /></li>

package/components/UnknownMark.astro

@@ -0,0 +1,7 @@
+---
+import type { Props as $, Mark } from "../lib/types";
+
+export type Props = $<Mark>;
+---
+
+<span data-portabletext-unknown="mark"><slot /></span>

package/components/UnknownType.astro

@@ -0,0 +1,21 @@
+---
+import type { TypedObject, Props as $ } from "../lib/types";
+import { getWarningMessage } from "../lib/warnings";
+
+export type Props = $<TypedObject>;
+
+const { node, isInline } = Astro.props;
+const warning = getWarningMessage("type", node._type);
+---
+
+{
+  isInline ? (
+    <span style="display:none" data-portabletext-unknown="type">
+      {warning}
+    </span>
+  ) : (
+    <div style="display:none" data-portabletext-unknown="type">
+      {warning}
+    </div>
+  )
+}

package/lib/astro.d.ts

@@ -0,0 +1,9 @@
+/// <reference types="astro/client" />
+
+declare module '*.astro' {
+  type Props = any
+  const Component: (props: Props) => any
+
+  export default Component
+  export type {Props}
+}

package/lib/components.ts

@@ -0,0 +1,4 @@
+export {default as Block} from '../components/Block.astro'
+export {default as List} from '../components/List.astro'
+export {default as ListItem} from '../components/ListItem.astro'
+export {default as Mark} from '../components/Mark.astro'

package/lib/context.ts

@@ -0,0 +1,21 @@
+import type {TypedObject} from '@portabletext/types'
+
+import type {Context} from './types'
+
+export const key = Symbol('@portabletext/astro')
+
+/**
+ * This function returns rendering utility functions within a Portable Text tree. It should
+ * only be used within an Astro component that has been passed into the PortableText `components` prop.
+ * It follows a naming convention similar to React hooks, though it is not a hook as such.
+ *
+ * @param node - The Portable Text node that was passed into the Astro component
+ * @returns Rendering utility functions
+ */
+export function usePortableText(node: TypedObject) {
+  if (!(key in globalThis)) {
+    throw new Error(`PortableText "context" has not been initialised`)
+  }
+
+  return (globalThis as any)[key](node) as Context
+}

package/lib/index.ts

@@ -0,0 +1,2 @@
+export {default as PortableText} from '../components/PortableText.astro'
+export * from './utils'