@portabletext/astro 0.0.0 → 0.1.0

package/components/PortableText.astro

@@ -0,0 +1,393 @@
+---
+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,
+  mergeComponents,
+  setNodeComponents,
+  getNodeComponents,
+} from "../lib/internal";
+
+import { getWarningMessage, printWarning } 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;
+};
+
+// 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<H extends (...args: any) => any, P = Parameters<H>[0]>(
+      handler: H | undefined,
+      props: P
+    ) {
+      if (!isComponent(handler)) {
+        throw new Error(
+          `[PortableText render] No handler found for node type ${node._type}.`
+        );
+      }
+
+      return handler(props);
+    }
+
+    if (isPortableTextToolkitList(node)) {
+      const UnknownComponent = components.unknownList ?? UnknownList;
+      setNodeComponents(node, List, UnknownComponent);
+
+      return run(renderOptions.list, {
+        Component: provideComponent("list", node.listItem, 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(renderOptions.listItem, {
+        Component: provideComponent(
+          "listItem",
+          node.listItem,
+          UnknownComponent
+        ),
+        props: asComponentProps(node, index, false),
+        children: isStyled
+          ? node.children
+          : renderChildren(node.children, true),
+      });
+    }
+
+    if (isPortableTextToolkitSpan(node)) {
+      const UnknownComponent = components.unknownMark ?? UnknownMark;
+      setNodeComponents(node, Mark, UnknownComponent);
+
+      return run(renderOptions.mark, {
+        Component: provideComponent("mark", node.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 UnknownComponent = components.unknownBlock ?? UnknownBlock;
+      setNodeComponents(node, Block, UnknownComponent);
+
+      return run(renderOptions.block, {
+        Component: provideComponent("block", node.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(renderOptions.hardBreak, {
+          Component: isComponent(components.hardBreak)
+            ? components.hardBreak
+            : HardBreak,
+          props,
+        });
+      }
+
+      return run(renderOptions.text, {
+        Component: isComponent(components.text) ? components.text : Text,
+        props,
+      });
+    }
+
+    // Custom type
+    const UnknownComponent = components.unknownType ?? UnknownType;
+
+    return run(renderOptions.type, {
+      Component: provideComponent("type", node._type, 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 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>
+);
+
+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>
+        );
+    };
+
+    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),
+      })
+    );
+  })()
+}

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'

package/lib/internal.ts

@@ -0,0 +1,103 @@
+import type {Component, ComponentOrRecord, SomePortableTextComponents, TypedObject} from './types'
+
+/**
+ * Helper for component to throw an error
+ * @param err
+ */
+export function throwError(err: Error | string): never {
+  throw err
+}
+
+/**
+ * Returns true if `it` is component
+ */
+export function isComponent(it: unknown): it is Component {
+  return typeof it === 'function'
+}
+
+/**
+ * Merges two {@link SomePortableTextComponents} objects, giving priority to overrides.
+ *
+ * This function combines two component objects used in Portable Text rendering.
+ * If both objects have the same key, the value from `overrides` takes precedence.
+ * This is useful for customizing the rendering of specific components while keeping
+ * the default behavior for others.
+ *
+ * @typeParam Components - The type of the base components object.
+ * @typeParam Overrides - The type of the overrides components object.
+ *
+ * @param components - The base components object.
+ * @param overrides - The overrides components object.
+ *
+ * @returns A new object with the merged components.
+ */
+export function mergeComponents<
+  Components extends SomePortableTextComponents,
+  Overrides extends SomePortableTextComponents,
+>(components: Components, overrides: Overrides) {
+  const cmps = {...components} as Record<string, ComponentOrRecord>
+
+  for (const [key, override] of Object.entries(overrides)) {
+    const current = components[key as keyof typeof components]
+
+    const value =
+      !current || isComponent(override) || isComponent(current)
+        ? override
+        : {
+            ...(current as Record<string, Component>),
+            ...(override as Record<string, Component>),
+          }
+
+    cmps[key] = value
+  }
+
+  return cmps as {
+    [Key in keyof (Components & Overrides)]: Key extends keyof (Overrides | Components)
+      ? Overrides[Key] extends Component
+        ? Overrides[Key]
+        : Components[Key] extends Component
+          ? Overrides[Key]
+          : (Overrides & Components)[Key]
+      : (Overrides & Components)[Key]
+  }
+}
+
+/**
+ * ========================
+ * Node Components Registry
+ * ========================
+ */
+
+type ResolvedComponents = {
+  Default: Component
+  Unknown: Component
+}
+
+const nodeComponentsMap = new WeakMap<TypedObject, ResolvedComponents>()
+
+/**
+ * Binds the resolved components to a specific node object.
+ * @internal
+ *
+ * @remarks
+ * This uses the node's _object reference_ as the key. This enables the `Context` API via
+ * `usePortableText` to look up which components were assigned to this specific node during rendering.
+ *
+ * @param node - The node object to be used as the key.
+ * @param Default - The resolved default component for this node.
+ * @param Unknown - The resolved fallback (unknown) component for this node.
+ */
+export function setNodeComponents(node: TypedObject, Default: Component, Unknown: Component): void {
+  nodeComponentsMap.set(node, {Default, Unknown})
+}
+
+/**
+ * Retrieves the components bound to a specific node object.
+ * @internal
+ *
+ * @param node - The node object to look up (by reference).
+ * @returns The component pair, or `undefined` if this exact node object was not registered.
+ */
+export function getNodeComponents(node: TypedObject): ResolvedComponents | undefined {
+  return nodeComponentsMap.get(node)
+}