@datocms/astro 0.1.7 → 0.1.9

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.1.7",
+	"version": "0.1.9",
 	"sideEffects": false,
 	"repository": {
 		"type": "git",
@@ -21,9 +21,10 @@
 		"ui"
 	],
 	"exports": {
-		".": "./src/index.ts",
+		"./useVideoPlayer": "./src/useVideoPlayer/index.ts",
 		"./VideoPlayer": "./src/VideoPlayer/index.ts",
-		"./Image": "./src/Image/index.ts"
+		"./Image": "./src/Image/index.ts",
+		"./StructuredText": "./src/StructuredText/index.ts"
 	},
 	"engines": {
 		"node": ">=18.0.0"
@@ -31,6 +32,7 @@
 	"files": ["src"],
 	"dependencies": {
 		"@mux/playback-core": "^0.25.1",
+		"datocms-structured-text-utils": "^4.0.1",
 		"typescript": "^5.5.4"
 	},
 	"peerDependencies": {

package/src/Image/index.ts

@@ -1,2 +1,2 @@
-import Component from "./Image.astro";
-export default Component;
+import Image from "./Image.astro";
+export { Image };

package/src/StructuredText/Lines.astro

@@ -0,0 +1,18 @@
+---
+interface Props {
+  lines: string[];
+}
+
+const { lines = [] } = Astro.props;
+
+const [first, ...rest] = lines;
+---
+
+{first}{
+  rest.length > 0 && (
+    <>
+      <br />
+      <Astro.self lines={rest} />
+    </>
+  )
+}

package/src/StructuredText/Node.astro

@@ -0,0 +1,81 @@
+---
+import {
+  type Block,
+  type InlineItem,
+  type ItemLink,
+  type Node,
+  type StructuredText,
+  hasChildren,
+  isBlock,
+  isInlineItem,
+  isItemLink,
+} from "datocms-structured-text-utils";
+
+import {
+  defaultComponents,
+  throwRenderErrorForMissingBlock,
+  throwRenderErrorForMissingComponent,
+  throwRenderErrorForMissingLink,
+} from "./utils";
+
+import type { PredicateComponentTuple } from "./types";
+
+interface Props {
+  node: Node;
+  blocks: StructuredText["blocks"];
+  links: StructuredText["links"];
+  components: PredicateComponentTuple[];
+}
+
+const { node, blocks, links, components = [] } = Astro.props;
+
+const findBlock = (node: Block, blocks: StructuredText["blocks"]) =>
+  (blocks || []).find(({ id }) => id === node.item);
+
+const findLink = (
+  node: ItemLink | InlineItem,
+  links: StructuredText["links"]
+) => (links || []).find(({ id }) => id === node.item);
+
+const block =
+  isBlock(node) &&
+  (findBlock(node, blocks) || throwRenderErrorForMissingBlock(node));
+
+const link =
+  (isItemLink(node) &&
+    (findLink(node, links) || throwRenderErrorForMissingLink(node))) ||
+  (isInlineItem(node) &&
+    (findLink(node, links) || throwRenderErrorForMissingLink(node)));
+
+const predicateComponentTuple =
+  [...components, ...defaultComponents].find(([predicate, component]) =>
+    predicate(node)
+  ) || throwRenderErrorForMissingComponent(node);
+
+const Component = (predicateComponentTuple ?? [])[1];
+---
+
+<>
+  {
+    Component &&
+      (isBlock(node) ? (
+        <Component {node} {block} />
+      ) : isInlineItem(node) ? (
+        <Component {node} {link} />
+      ) : isItemLink(node) ? (
+        <Component {node} {link}>
+          {hasChildren(node) &&
+            node.children.map((child) => (
+              <svelte:self node={child} {blocks} {links} {components} />
+            ))}
+        </Component>
+      ) : (
+        <Component {node}>
+          {hasChildren(node) &&
+            node.children.map((child) => (
+              <svelte:self node={child} {blocks} {links} {components} />
+            ))}
+        </Component>
+      ))
+  }
+</>

package/src/StructuredText/README.md

@@ -0,0 +1,208 @@
+# Structured text
+
+`StructuredText />` is a Svelte component that you can use to render the value contained inside a DatoCMS [Structured Text field type](https://www.datocms.com/docs/structured-text/dast).
+
+### Table of contents
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+  - [Setup](#setup)
+- [Basic usage](#basic-usage)
+- [Customization](#customization)
+  - [Custom components for blocks](#custom-components-for-blocks)
+  - [Override default rendering of nodes](#override-default-rendering-of-nodes)
+- [Props](#props)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+### Setup
+
+Import the component like this:
+
+```js
+import { StructuredText } from '@datocms/svelte';
+```
+
+## Basic usage
+
+```svelte
+<script>
+
+import { onMount } from 'svelte';
+
+import { StructuredText } from '@datocms/svelte';
+
+const query = `
+  query {
+    blogPost {
+      title
+      content {
+        value
+      }
+    }
+  }
+`;
+
+export let data = null;
+
+onMount(async () => {
+  const response = await fetch('https://graphql.datocms.com/', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: "Bearer AN_API_TOKEN",
+    },
+    body: JSON.stringify({ query })
+  })
+
+  const json = await response.json()
+
+  data = json.data;
+});
+
+</script>
+
+<article>
+  {#if data}
+    <h1>{{ data.blogPost.title }}</h1>
+    <StructuredText data={data.blogPost.content} />
+  {/if}
+</article>
+```
+
+## Customization
+
+The `<StructuredText />` component comes with a set of default components that are use to render all the nodes present in [DatoCMS Dast trees](https://www.datocms.com/docs/structured-text/dast). These default components are enough to cover most of the simple cases.
+
+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 need to render a conventional node differently (e.g. you may want a custom render for blockquotes)
+
+### Custom components for blocks
+
+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.
+
+```svelte
+<script>
+
+import { onMount } from 'svelte';
+
+import { isBlock, isInlineItem, isItemLink } from 'datocms-structured-text-utils';
+
+import { StructuredText } from '@datocms/svelte';
+
+import Block from './Block.svelte';
+import InlineItem from './InlineItem.svelte';
+import ItemLink from './ItemLink.svelte';
+
+const query = `
+  query {
+    blogPost {
+      title
+      content {
+        value
+        links {
+          __typename
+          ... on TeamMemberRecord {
+            id
+            firstName
+            slug
+          }
+        }
+        blocks {
+          __typename
+          ... on ImageRecord {
+            id
+            image {
+              responsiveImage(
+                imgixParams: { fit: crop, w: 300, h: 300, auto: format }
+              ) {
+                srcSet
+                webpSrcSet
+                sizes
+                src
+                width
+                height
+                aspectRatio
+                alt
+                title
+                base64
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+export let data = null;
+
+onMount(async () => {
+  const response = await fetch('https://graphql.datocms.com/', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: "Bearer AN_API_TOKEN",
+    },
+    body: JSON.stringify({ query })
+  })
+
+  const json = await response.json()
+
+  data = json.data;
+});
+
+</script>
+
+<article>
+  {#if data}
+    <h1>{{ data.blogPost.title }}</h1>
+    <datocms-structured-text
+      data={data.blogPost.content}
+      components={[
+        [isInlineItem, InlineItem],
+        [isItemLink, ItemLink],
+        [isBlock, Block]
+      ]}
+    />
+  {/if}
+</article>
+```
+
+### Override default rendering of nodes
+
+`<StructuredText />` automatically renders all nodes (except for `inline_item`, `item_link` and `block`) using a set of default components, that you might want to customize. For example:
+
+- 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. See test fixtures for example implementations of custom components (e.g. [this special heading component](https://github.com/datocms/datocms-svelte/blob/main/src/lib/components/StructuredText/__tests__/__fixtures__/IncreasedLevelHeading.svelte)).
+
+```svelte
+<script>
+	import { isHeading, isCode } from 'datocms-structured-text-utils';
+
+	import Heading from './Heading.svelte';
+	import Code from './Code.svelte';
+
+	export let data;
+</script>
+
+<StructuredText
+	data={data.blogPost.content}
+	components={[
+		[isHeading, Heading],
+		[isCode, 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/datocms-svelte/blob/main/src/lib/index.ts) | Only required if data contain `block`, `inline_item` or `item_link` nodes | Array of tuples formed by a predicate function and custom component                              | `[]`    |

package/src/StructuredText/StructuredText.astro

@@ -0,0 +1,27 @@
+---
+import {
+  type StructuredText,
+  type Document,
+  isStructuredText,
+} from "datocms-structured-text-utils";
+
+import Node from "./Node.astro";
+import type { PredicateComponentTuple } from "./types";
+
+interface Props {
+  data: StructuredText | Document | null;
+  components: PredicateComponentTuple[];
+}
+
+const { data, components } = Astro.props;
+
+const node =
+  data != null &&
+  (isStructuredText(data) ? (data.value as Document) : data).document;
+
+const blocks = isStructuredText(data) ? data?.blocks : undefined;
+
+const links = isStructuredText(data) ? data?.links : undefined;
+---
+
+{node && <Node {node} {blocks} {links} {components} />}

package/src/StructuredText/index.ts

@@ -0,0 +1,5 @@
+import StructuredText from "./StructuredText.astro";
+
+export { defaultComponents } from "./utils";
+
+export { StructuredText };

package/src/StructuredText/nodes/Blockquote.astro

@@ -0,0 +1,14 @@
+---
+import type { Blockquote } from "datocms-structured-text-utils";
+
+interface Props {
+  node: Blockquote;
+}
+
+const { node } = Astro.props;
+---
+
+<blockquote>
+  <slot />
+  <footer>{node.attribution}</footer>
+</blockquote>

package/src/StructuredText/nodes/Code.astro

@@ -0,0 +1,13 @@
+---
+import type { Code } from "datocms-structured-text-utils";
+
+interface Props {
+  node: Code;
+}
+
+const { node } = Astro.props;
+
+const { code, language } = node;
+---
+
+<pre class={language}>{code}</pre>

package/src/StructuredText/nodes/Heading.astro

@@ -0,0 +1,14 @@
+---
+import type { Heading } from "datocms-structured-text-utils";
+
+interface Props {
+  node: Heading;
+}
+
+const { node } = Astro.props;
+
+const { level = 1 } = node;
+const Element = `h${level}`;
+---
+
+<Element><slot /></Element>

package/src/StructuredText/nodes/Link.astro

@@ -0,0 +1,29 @@
+---
+import type { Link } from "datocms-structured-text-utils";
+
+interface Props {
+  node: Link;
+}
+
+const { node } = Astro.props;
+
+const { url, meta } = node;
+
+let target: string | undefined = undefined;
+
+const targetMetaEntry = meta?.find((metaEntry) => metaEntry.id === "target");
+
+if (targetMetaEntry?.value) {
+  target = targetMetaEntry.value;
+}
+
+let rel: string | undefined = undefined;
+
+const relMetaEntry = meta?.find((metaEntry) => metaEntry.id === "rel");
+
+if (relMetaEntry?.value) {
+  rel = relMetaEntry.value;
+}
+---
+
+<a href={url} {target} {rel}><slot /></a>

package/src/StructuredText/nodes/List.astro

@@ -0,0 +1,21 @@
+---
+import type { List } from "datocms-structured-text-utils";
+
+interface Props {
+  node: List;
+}
+
+const { node } = Astro.props;
+---
+
+{
+  node.style === "numbered" ? (
+    <ol>
+      <slot />
+    </ol>
+  ) : (
+    <ul>
+      <slot />
+    </ul>
+  )
+}

package/src/StructuredText/nodes/ListItem.astro

@@ -0,0 +1,9 @@
+---
+import type { ListItem } from "datocms-structured-text-utils";
+
+interface Props {
+  node: ListItem;
+}
+---
+
+<li><slot /></li>

package/src/StructuredText/nodes/Paragraph.astro

@@ -0,0 +1,9 @@
+---
+import type { Paragraph } from "datocms-structured-text-utils";
+
+interface Props {
+  node: Paragraph;
+}
+---
+
+<p><slot /></p>

package/src/StructuredText/nodes/Root.astro

@@ -0,0 +1,9 @@
+---
+import type { Root } from "datocms-structured-text-utils";
+
+interface Props {
+  node: Root;
+}
+---
+
+<slot />

package/src/StructuredText/nodes/Span.astro

@@ -0,0 +1,56 @@
+---
+import type { Span } from "datocms-structured-text-utils";
+import Lines from "../utils/Lines.astro";
+
+interface Props {
+  node: Span;
+}
+
+const { node } = Astro.props;
+
+const { type, value, marks } = node;
+
+const [mark, ...otherMarks] = marks ?? [];
+---
+
+{
+  !mark ? (
+    <Lines lines={node.value.split(/\n/)} />
+  ) : mark === "emphasis" ? (
+    <em>
+      <Astro.self node={{ type, value, marks: otherMarks }}>
+        <slot />
+      </Astro.self>
+    </em>
+  ) : mark === "highlight" ? (
+    <mark>
+      <Astro.self node={{ type, value, marks: otherMarks }}>
+        <slot />
+      </Astro.self>
+    </mark>
+  ) : mark === "strikethrough" ? (
+    <del>
+      <Astro.self node={{ type, value, marks: otherMarks }}>
+        <slot />
+      </Astro.self>
+    </del>
+  ) : mark === "strong" ? (
+    <strong>
+      <Astro.self node={{ type, value, marks: otherMarks }}>
+        <slot />
+      </Astro.self>
+    </strong>
+  ) : mark === "underline" ? (
+    <u>
+      <Astro.self node={{ type, value, marks: otherMarks }}>
+        <slot />
+      </Astro.self>
+    </u>
+  ) : mark === "code" ? (
+    <code>
+      <Astro.self node={{ type, value, marks: otherMarks }}>
+        <slot />
+      </Astro.self>
+    </code>
+  ) : undefined
+}

package/src/StructuredText/nodes/ThematicBreak.astro

@@ -0,0 +1,9 @@
+---
+import type { ThematicBreak } from "datocms-structured-text-utils";
+
+interface Props {
+  node: ThematicBreak;
+}
+---
+
+<hr />

package/src/StructuredText/types.ts

@@ -0,0 +1,6 @@
+import type { Node } from "datocms-structured-text-utils";
+
+// biome-ignore lint/suspicious/noExplicitAny: <explanation>
+type AstroComponent = (props: any) => any;
+
+export type PredicateComponentTuple = [(n: Node) => boolean, AstroComponent];

package/src/StructuredText/utils.ts

@@ -0,0 +1,92 @@
+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);

package/src/VideoPlayer/index.ts

@@ -1,2 +1,2 @@
-import Component from "./VideoPlayer.astro";
-export default Component;
+import VideoPlayer from "./VideoPlayer.astro";
+export { VideoPlayer };

package/src/index.ts

@@ -1,4 +0,0 @@
-export { default as Image } from "./Image";
-export { useVideoPlayer } from './useVideoPlayer';
-export { default as VideoPlayer } from "./VideoPlayer";
-