@datocms/astro 0.2.2 → 0.3.1

package/package.json

@@ -2,7 +2,7 @@
   "name": "@datocms/astro",
   "description": "A set of components and utilities to work faster with DatoCMS in Astro projects.",
   "type": "module",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "sideEffects": false,
   "repository": {
     "type": "git",
@@ -45,6 +45,7 @@
   "dependencies": {
     "@0no-co/graphql.web": "^1.0.7",
     "datocms-listen": "^1.0.1",
+    "datocms-structured-text-generic-html-renderer": "^4.0.1",
     "datocms-structured-text-utils": "^4.0.1"
   },
   "peerDependencies": {

package/src/StructuredText/Node.astro

@@ -1,70 +1,112 @@
 ---
 import {
   type Block,
+  type Record as DatocmsRecord,
   type InlineItem,
   type ItemLink,
-  type Node,
-  type StructuredText,
+  type Node as DastNode,
   hasChildren,
   isBlock,
   isInlineItem,
   isItemLink,
+  RenderError,
 } from 'datocms-structured-text-utils';
 
-import {
-  defaultComponents,
-  throwRenderErrorForMissingBlock,
-  throwRenderErrorForMissingComponent,
-  throwRenderErrorForMissingLink,
-} from './utils';
+import Blockquote from './nodes/Blockquote.astro';
+import Code from './nodes/Code.astro';
+import Heading from './nodes/Heading.astro';
+import Link from './nodes/Link.astro';
+import List from './nodes/List.astro';
+import ListItem from './nodes/ListItem.astro';
+import Paragraph from './nodes/Paragraph.astro';
+import Root from './nodes/Root.astro';
+import Span from './nodes/Span.astro';
+import ThematicBreak from './nodes/ThematicBreak.astro';
+import BlockComponent from './nodes/Block.astro';
+import InlineItemComponent from './nodes/InlineItem.astro';
+import ItemLinkComponent from './nodes/ItemLink.astro';
 
-import type { PredicateComponentTuple } from './types';
+import type { BlockComponents, InlineItemComponents, ItemLinkComponents, Overrides } from './types';
 
 interface Props {
-  node: Node;
-  blocks: StructuredText['blocks'];
-  links: StructuredText['links'];
-  components: PredicateComponentTuple[];
+  node: DastNode;
+
+  blocks?: DatocmsRecord[];
+  links?: DatocmsRecord[];
+
+  blockComponents?: BlockComponents<DatocmsRecord, DatocmsRecord>;
+  itemLinkComponents?: ItemLinkComponents<DatocmsRecord, DatocmsRecord>;
+  inlineItemComponents?: InlineItemComponents<DatocmsRecord, DatocmsRecord>;
+  overrides?: Overrides;
 }
 
-const { node, blocks, links, components = [] } = Astro.props;
+const { node, ...rest } = Astro.props;
+
+const { blocks, links, blockComponents, itemLinkComponents, inlineItemComponents, overrides } =
+  rest;
+
+function findRecordInBlocks(node: Block) {
+  const record = (blocks || []).find(({ id }) => id === node.item);
 
-const findBlock = (node: Block, blocks: StructuredText['blocks']) =>
-  (blocks || []).find(({ id }) => id === node.item);
+  if (!record) {
+    throw new RenderError(
+      `The Structured Text document contains a 'block' node, but cannot find a record with ID ${node.item} inside data.blocks!`,
+      node,
+    );
+  }
 
-const findLink = (node: ItemLink | InlineItem, links: StructuredText['links']) =>
-  (links || []).find(({ id }) => id === node.item);
+  return record;
+}
 
-const block = isBlock(node) && (findBlock(node, blocks) || throwRenderErrorForMissingBlock(node));
+function findRecordInLinks(node: ItemLink | InlineItem) {
+  const record = (links || []).find(({ id }) => id === node.item);
 
-const link =
-  (isItemLink(node) && (findLink(node, links) || throwRenderErrorForMissingLink(node))) ||
-  (isInlineItem(node) && (findLink(node, links) || throwRenderErrorForMissingLink(node)));
+  if (!record) {
+    throw new RenderError(
+      `The Structured Text document contains an '${node.type}' node, but cannot find a record with ID ${node.item} inside data.links!`,
+      node,
+    );
+  }
+
+  return record;
+}
 
-const predicateComponentTuple =
-  [...components, ...defaultComponents].find(([predicate, component]) => predicate(node)) ||
-  throwRenderErrorForMissingComponent(node);
+const defaultComponents: Overrides = {
+  paragraph: Paragraph,
+  root: Root,
+  span: Span,
+  link: Link,
+  list: List,
+  heading: Heading,
+  blockquote: Blockquote,
+  listItem: ListItem,
+  thematicBreak: ThematicBreak,
+  code: Code,
+  itemLink: ItemLinkComponent,
+  inlineItem: InlineItemComponent,
+  block: BlockComponent,
+};
 
-const Component = (predicateComponentTuple ?? [])[1];
+const otherNodeComponents: Overrides = { ...defaultComponents, ...overrides };
+const Component = otherNodeComponents[node.type];
 ---
 
 <>
   {
-    Component &&
-      (isBlock(node) ? (
-        <Component {node} {block} />
-      ) : isInlineItem(node) ? (
-        <Component {node} {link} />
-      ) : isItemLink(node) ? (
-        <Component {node} {link}>
-          {hasChildren(node) &&
-            node.children.map((child) => <Astro.self node={child} {blocks} {links} {components} />)}
-        </Component>
-      ) : (
-        <Component {node}>
-          {hasChildren(node) &&
-            node.children.map((child) => <Astro.self node={child} {blocks} {links} {components} />)}
-        </Component>
-      ))
+    isBlock(node) ? (
+      <Component {node} block={findRecordInBlocks(node)} {blockComponents} />
+    ) : isInlineItem(node) ? (
+      <Component {node} record={findRecordInLinks(node)} {inlineItemComponents} />
+    ) : isItemLink(node) ? (
+      <Component {node} record={findRecordInLinks(node)} {itemLinkComponents}>
+        {node.children.map((child) => (
+          <Astro.self node={child} {...rest} />
+        ))}
+      </Component>
+    ) : (
+      <Component {node}>
+        {hasChildren(node) && node.children.map((child) => <Astro.self node={child} {...rest} />)}
+      </Component>
+    )
   }
 </>

package/src/StructuredText/README.md

@@ -10,7 +10,7 @@
 - [Setup](#setup)
 - [Basic usage](#basic-usage)
 - [Customization](#customization)
-  - [Custom components for blocks](#custom-components-for-blocks)
+  - [Custom components for blocks, inline records or links to records](#custom-components-for-blocks-inline-records-or-links-to-records)
   - [Override default rendering of nodes](#override-default-rendering-of-nodes)
 - [Props](#props)
 
@@ -57,21 +57,25 @@ The `<StructuredText />` component comes with a set of default components that a
 
 You need to use custom components in the following cases:
 
-- you have to render blocks, inline items or item links: there's no conventional way of rendering theses nodes, so you must create and pass custom components;
+- you have to render blocks, inline records or links to records: there's no conventional way of rendering theses nodes, so you must create and pass custom components;
 - you need to render a conventional node differently (e.g. you may want a custom render for blockquotes)
 
-### Custom components for blocks
+### Custom components for blocks, inline records or links to records
 
-Here is an example using custom components for blocks, inline and item links. Take a look at the [test fixtures](https://github.com/datocms/datocms-svelte/tree/main/src/lib/components/StructuredText/__tests__/__fixtures__) to see examples on how to implement these components.
+- Astro components passed in `blockComponents` will be used to render blocks and will receive a `block` prop containing the actual block data.
+- Astro components passed in `inlineItemComponents` will be used to render inline records and will receive a `record` prop containing the actual record.
+- Astro components passed in `itemLinkComponents` will be used to render links to records and will receive the following props: `node` (the actual `'inlineItem'` node), `record` (the record linked to the node), and `attrs` (the custom attributes for the link specified by the node).
 
 ```astro
 ---
-import { isBlock, isInlineItem, isItemLink } from 'datocms-structured-text-utils';
 import { StructuredText } from '@datocms/astro/StructuredText';
+import { executeQuery } from '@datocms/cda-client';
+
+import Cta from '~/components/Cta/index.astro';
+import NewsletterSignup from '~/components/NewsletterSignup/index.astro';
 
-import Block from '~/components/Block/index.astro';
-import InlineItem from '~/components/InlineItem/index.astro';
-import ItemLink from '~/components/ItemLink/index.astro';
+import InlineTeamMember from '~/components/InlineTeamMember/index.astro';
+import LinkToTeamMember from '~/components/LinkToTeamMember/index.astro';
 
 const query = gql`
   query {
@@ -79,32 +83,27 @@ const query = gql`
       title
       content {
         value
-        links {
-          __typename
-          ... on TeamMemberRecord {
+        blocks {
+          ... on RecordInterface {
             id
-            firstName
-            slug
+            __typename
+          }
+          ... on CtaRecord {
+            label
+            url
+          }
+          ... on NewsletterSignupRecord {
+            title
           }
         }
-        blocks {
-          __typename
-          ... on ImageRecord {
+        links {
+          ... on RecordInterface {
             id
-            image {
-              responsiveImage(imgixParams: { fit: crop, w: 300, h: 300, auto: format }) {
-                srcSet
-                webpSrcSet
-                sizes
-                src
-                width
-                height
-                aspectRatio
-                alt
-                title
-                base64
-              }
-            }
+            __typename
+          }
+          ... on TeamMemberRecord {
+            firstName
+            slug
           }
         }
       }
@@ -119,11 +118,16 @@ const { blogPost } = await executeQuery(query, { token: '<YOUR-API-TOKEN>' });
   <h1>{blogPost.title}</h1>
   <StructuredText
     data={blogPost.content}
-    components={[
-      [isInlineItem, InlineItem],
-      [isItemLink, ItemLink],
-      [isBlock, Block],
-    ]}
+    blockComponents={{
+      CtaRecord: Cta,
+      NewsletterSignupRecord: NewsletterSignup,
+    }}
+    inlineItemComponents={{
+      TeamMemberRecord: InlineTeamMember,
+    }}
+    itemLinkComponents={{
+      TeamMemberRecord: LinkToTeamMember,
+    }}
   />
 </article>
 ```
@@ -135,20 +139,30 @@ const { blogPost } = await executeQuery(query, { token: '<YOUR-API-TOKEN>' });
 - For `heading` nodes, you might want to add an anchor;
 - For `code` nodes, you might want to use a custom syntax highlighting component;
 
-In this case, you can easily override default rendering rules with the `components` props.
+In this case, you can easily override default rendering rules with the `overrides` prop.
 
 ```astro
 ---
 import { isHeading } from 'datocms-structured-text-utils';
 import HeadingWithAnchorLink from '~/components/HeadingWithAnchorLink/index.astro';
+import Code from '~/components/Code/index.astro';
 ---
 
-<StructuredText data={blogPost.content} components={[[isHeading, HeadingWithAnchorLink]]} />
+<StructuredText
+  data={blogPost.content}
+  components={{
+    heading: HeadingWithAnchorLink,
+    code: Code,
+  }}
+/>
 ```
 
 ## Props
 
-| prop       | type                                                                                                                     | required                                                                  | description                                                                                      | default |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------- |
-| data       | `StructuredText \| DastNode`                                                                                             | :white_check_mark:                                                        | The actual [field value](https://www.datocms.com/docs/structured-text/dast) you get from DatoCMS |         |
-| components | [`PredicateComponentTuple[] \| null`](https://github.com/datocms/astro-datocms/blob/main/src/StructuredText/types.ts#L6) | Only required if data contain `block`, `inline_item` or `item_link` nodes | Array of tuples formed by a predicate function and custom component                              | `[]`    |
+| prop                 | type                             | required           | description                                                                                                             |
+| -------------------- | -------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------- |
+| data                 | `StructuredText \| DastNode`     | :white_check_mark: | The actual [field value](https://www.datocms.com/docs/structured-text/dast) you get from DatoCMS                        |
+| blockComponents      | `Record<string, AstroComponent>` |                    | An object in which the keys are the `__typename` of the blocks to be rendered, and the values are the Astro components  |
+| itemLinkComponents   | `Record<string, AstroComponent>` |                    | An object in which the keys are the `__typename` of the records to be rendered, and the values are the Astro components |
+| inlineItemComponents | `Record<string, AstroComponent>` |                    | An object in which the keys are the `__typename` of the records to be rendered, and the values are the Astro components |
+| overrides            | `Record<string, AstroComponent>` |                    | An object in which the keys are the types of DAST nodes to override, and the values are the Astro components            |

package/src/StructuredText/StructuredText.astro

@@ -1,25 +1,42 @@
 ---
 import {
-  type StructuredText,
+  type Node as DastNode,
   type Document,
+  type Record as DatocmsRecord,
+  type StructuredText,
+  isDocument,
+  isNode,
   isStructuredText,
 } from 'datocms-structured-text-utils';
 
 import Node from './Node.astro';
-import type { PredicateComponentTuple } from './types';
+import type { BlockComponents, InlineItemComponents, ItemLinkComponents, Overrides } from './types';
+
+// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+interface Props<R1 extends DatocmsRecord = any, R2 extends DatocmsRecord = any> {
+  data: StructuredText<R1, R2> | Document | DastNode | null | undefined;
 
-interface Props {
-  data: StructuredText | Document | null;
-  components?: PredicateComponentTuple[];
+  blockComponents?: BlockComponents<R1, R2>;
+  itemLinkComponents?: ItemLinkComponents<R1, R2>;
+  inlineItemComponents?: InlineItemComponents<R1, R2>;
+  overrides?: Overrides;
 }
 
-const { data, components = [] } = Astro.props;
+const { data, ...rest } = Astro.props;
 
-const node = data != null && (isStructuredText(data) ? (data.value as Document) : data).document;
+const node = !data
+  ? null
+  : isStructuredText(data) && isDocument(data.value)
+    ? data.value.document
+    : isDocument(data)
+      ? data.document
+      : isNode(data)
+        ? data
+        : undefined;
 
 const blocks = isStructuredText(data) ? data?.blocks : undefined;
 
 const links = isStructuredText(data) ? data?.links : undefined;
 ---
 
-{node && <Node {node} {blocks} {links} {components} />}
+{node && <Node {node} {blocks} {links} {...rest} />}

package/src/StructuredText/index.ts

@@ -1,5 +1,8 @@
 import StructuredText from './StructuredText.astro';
 
-export { defaultComponents } from './utils';
+export {
+  defaultMetaTransformer,
+  type TransformedMeta,
+} from 'datocms-structured-text-generic-html-renderer';
 
 export { StructuredText };

package/src/StructuredText/nodes/Block.astro

@@ -0,0 +1,27 @@
+---
+import {
+  type Record as DatocmsRecord,
+  RenderError,
+  type Block,
+} from 'datocms-structured-text-utils';
+import type { BlockComponents } from '../types';
+
+interface Props {
+  node: Block;
+  block: DatocmsRecord;
+  blockComponents?: BlockComponents<DatocmsRecord, DatocmsRecord>;
+}
+
+const { node, block, blockComponents } = Astro.props;
+
+const Component = blockComponents?.[block.__typename];
+
+if (!Component) {
+  throw new RenderError(
+    `The Structured Text document contains a 'block' node, but no component for rendering it is specified in blockComponents prop!`,
+    node,
+  );
+}
+---
+
+<Component block={block} />

package/src/StructuredText/nodes/InlineItem.astro

@@ -0,0 +1,27 @@
+---
+import {
+  type Record as DatocmsRecord,
+  RenderError,
+  type InlineItem,
+} from 'datocms-structured-text-utils';
+import type { InlineItemComponents } from '../types';
+
+interface Props {
+  node: InlineItem;
+  record: DatocmsRecord;
+  inlineItemComponents?: InlineItemComponents<DatocmsRecord, DatocmsRecord>;
+}
+
+const { node, record, inlineItemComponents } = Astro.props;
+
+const Component = inlineItemComponents?.[record.__typename];
+
+if (!Component) {
+  throw new RenderError(
+    `The Structured Text document contains an 'inlineItem' node, but no component for rendering it is specified in the inlineItemComponents prop!`,
+    node,
+  );
+}
+---
+
+<Component {record} />

package/src/StructuredText/nodes/ItemLink.astro

@@ -0,0 +1,34 @@
+---
+import {
+  type Record as DatocmsRecord,
+  RenderError,
+  type ItemLink,
+} from 'datocms-structured-text-utils';
+
+import type { ItemLinkComponents } from '../types';
+
+import { defaultMetaTransformer } from 'datocms-structured-text-generic-html-renderer';
+
+interface Props {
+  node: ItemLink;
+  record: DatocmsRecord;
+  itemLinkComponents?: ItemLinkComponents<DatocmsRecord, DatocmsRecord>;
+}
+
+const { node, record, itemLinkComponents } = Astro.props;
+
+const Component = itemLinkComponents?.[record.__typename];
+
+if (!Component) {
+  throw new RenderError(
+    `The Structured Text document contains an 'itemLink' node, but no component for rendering it is specified in the itemLinkComponents prop!`,
+    node,
+  );
+}
+
+const { meta } = node;
+
+const attrs = meta ? defaultMetaTransformer({ node, meta }) : {};
+---
+
+<Component {node} {record} {attrs}><slot /></Component>

package/src/StructuredText/types.ts

@@ -1,6 +1,21 @@
-import type { Node } from 'datocms-structured-text-utils';
+import type { Record as DatocmsRecord, NodeType } from 'datocms-structured-text-utils';
 
 // biome-ignore lint/suspicious/noExplicitAny: <explanation>
 type AstroComponent = (props: any) => any;
 
-export type PredicateComponentTuple = [(n: Node) => boolean, AstroComponent];
+export type BlockComponents<R1 extends DatocmsRecord, R2 extends DatocmsRecord> = Record<
+  R1['__typename'],
+  AstroComponent
+>;
+
+export type ItemLinkComponents<R1 extends DatocmsRecord, R2 extends DatocmsRecord> = Record<
+  R2['__typename'],
+  AstroComponent
+>;
+
+export type InlineItemComponents<R1 extends DatocmsRecord, R2 extends DatocmsRecord> = Record<
+  R2['__typename'],
+  AstroComponent
+>;
+
+export type Overrides = Record<NodeType, AstroComponent>;

package/src/StructuredText/utils.ts

@@ -1,90 +0,0 @@
-import {
-  type Block,
-  type InlineItem,
-  type ItemLink,
-  type Node,
-  RenderError,
-  type StructuredText,
-  isBlock,
-  isBlockquote,
-  isCode,
-  isHeading,
-  isInlineItem,
-  isItemLink,
-  isLink,
-  isList,
-  isListItem,
-  isParagraph,
-  isRoot,
-  isSpan,
-  isThematicBreak,
-} from 'datocms-structured-text-utils';
-
-import Blockquote from './nodes/Blockquote.astro';
-import Code from './nodes/Code.astro';
-import Heading from './nodes/Heading.astro';
-import Link from './nodes/Link.astro';
-import List from './nodes/List.astro';
-import ListItem from './nodes/ListItem.astro';
-import Paragraph from './nodes/Paragraph.astro';
-import Root from './nodes/Root.astro';
-import Span from './nodes/Span.astro';
-import ThematicBreak from './nodes/ThematicBreak.astro';
-
-import type { PredicateComponentTuple } from './types';
-
-export const defaultComponents: PredicateComponentTuple[] = [
-  [isParagraph, Paragraph],
-  [isRoot, Root],
-  [isSpan, Span],
-  [isLink, Link],
-  [isList, List],
-  [isHeading, Heading],
-  [isBlockquote, Blockquote],
-  [isListItem, ListItem],
-  [isThematicBreak, ThematicBreak],
-  [isCode, Code],
-];
-
-export const throwRenderErrorForMissingComponent = (node: Node) => {
-  if (isInlineItem(node)) {
-    throw new RenderError(
-      `The Structured Text document contains an 'inlineItem' node, but no component for rendering is specified!`,
-      node,
-    );
-  }
-
-  if (isItemLink(node)) {
-    throw new RenderError(
-      `The Structured Text document contains an 'itemLink' node, but no component for rendering is specified!`,
-      node,
-    );
-  }
-
-  if (isBlock(node)) {
-    throw new RenderError(
-      `The Structured Text document contains a 'block' node, but no component for rendering is specified!`,
-      node,
-    );
-  }
-};
-
-export const throwRenderErrorForMissingBlock = (node: Block) => {
-  throw new RenderError(
-    `The Structured Text document contains a 'block' node, but cannot find a record with ID ${node.item} inside data.blocks!`,
-    node,
-  );
-};
-
-export const throwRenderErrorForMissingLink = (node: ItemLink | InlineItem) => {
-  throw new RenderError(
-    `The Structured Text document contains an 'itemLink' node, but cannot find a record with ID ${node.item} inside data.links!`,
-    node,
-  );
-};
-
-export const findBlock = (node: Block, blocks: StructuredText['blocks']) =>
-  (blocks || []).find(({ id }) => id === node.item);
-
-export const findLink = (node: ItemLink | InlineItem, links: StructuredText['links']) =>
-  (links || []).find(({ id }) => id === node.item);