@datocms/astro 0.3.2 → 0.3.4

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.3.2",
+  "version": "0.3.4",
   "sideEffects": false,
   "repository": {
     "type": "git",

package/src/StructuredText/Node.astro

@@ -10,6 +10,8 @@ import {
   isInlineItem,
   isItemLink,
   RenderError,
+  type NodeType,
+  isSpan,
 } from 'datocms-structured-text-utils';
 
 import Blockquote from './nodes/Blockquote.astro';
@@ -26,7 +28,14 @@ import BlockComponent from './nodes/Block.astro';
 import InlineItemComponent from './nodes/InlineItem.astro';
 import ItemLinkComponent from './nodes/ItemLink.astro';
 
-import type { BlockComponents, InlineItemComponents, ItemLinkComponents, Overrides } from './types';
+import type {
+  BlockComponents,
+  InlineRecordComponents,
+  LinkToRecordComponents,
+  NodeOverrides,
+  AstroComponent,
+  MarkOverrides,
+} from './types';
 
 interface Props {
   node: DastNode;
@@ -35,15 +44,24 @@ interface Props {
   links?: DatocmsRecord[];
 
   blockComponents?: BlockComponents<DatocmsRecord, DatocmsRecord>;
-  itemLinkComponents?: ItemLinkComponents<DatocmsRecord, DatocmsRecord>;
-  inlineItemComponents?: InlineItemComponents<DatocmsRecord, DatocmsRecord>;
-  overrides?: Overrides;
+  linkToRecordComponents?: LinkToRecordComponents<DatocmsRecord, DatocmsRecord>;
+  inlineRecordComponents?: InlineRecordComponents<DatocmsRecord, DatocmsRecord>;
+
+  nodeOverrides?: NodeOverrides;
+  markOverrides?: MarkOverrides;
 }
 
 const { node, ...rest } = Astro.props;
 
-const { blocks, links, blockComponents, itemLinkComponents, inlineItemComponents, overrides } =
-  rest;
+const {
+  blocks,
+  links,
+  blockComponents,
+  linkToRecordComponents,
+  inlineRecordComponents,
+  nodeOverrides,
+  markOverrides,
+} = rest;
 
 function findRecordInBlocks(node: Block) {
   const record = (blocks || []).find(({ id }) => id === node.item);
@@ -71,7 +89,7 @@ function findRecordInLinks(node: ItemLink | InlineItem) {
   return record;
 }
 
-const defaultComponents: Overrides = {
+const defaultComponents: Record<NodeType, AstroComponent> = {
   paragraph: Paragraph,
   root: Root,
   span: Span,
@@ -87,7 +105,11 @@ const defaultComponents: Overrides = {
   block: BlockComponent,
 };
 
-const otherNodeComponents: Overrides = { ...defaultComponents, ...overrides };
+const otherNodeComponents: Record<NodeType, AstroComponent> = {
+  ...defaultComponents,
+  ...nodeOverrides,
+};
+
 const Component = otherNodeComponents[node.type];
 ---
 
@@ -96,13 +118,15 @@ const Component = otherNodeComponents[node.type];
     isBlock(node) ? (
       <Component {node} block={findRecordInBlocks(node)} {blockComponents} />
     ) : isInlineItem(node) ? (
-      <Component {node} record={findRecordInLinks(node)} {inlineItemComponents} />
+      <Component {node} record={findRecordInLinks(node)} {inlineRecordComponents} />
     ) : isItemLink(node) ? (
-      <Component {node} record={findRecordInLinks(node)} {itemLinkComponents}>
+      <Component {node} record={findRecordInLinks(node)} {linkToRecordComponents}>
         {node.children.map((child) => (
           <Astro.self node={child} {...rest} />
         ))}
       </Component>
+    ) : isSpan(node) ? (
+      <Component {node} {markOverrides} />
     ) : (
       <Component {node}>
         {hasChildren(node) && node.children.map((child) => <Astro.self node={child} {...rest} />)}

package/src/StructuredText/README.md

@@ -63,8 +63,8 @@ You need to use custom components in the following cases:
 ### Custom components for blocks, inline records or links to records
 
 - 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 components passed in `inlineRecordComponents` will be used to render inline records and will receive a `record` prop containing the actual record.
+- Astro components passed in `linkToRecordComponents` 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
 ---
@@ -122,10 +122,10 @@ const { blogPost } = await executeQuery(query, { token: '<YOUR-API-TOKEN>' });
       CtaRecord: Cta,
       NewsletterSignupRecord: NewsletterSignup,
     }}
-    inlineItemComponents={{
+    inlineRecordComponents={{
       TeamMemberRecord: InlineTeamMember,
     }}
-    itemLinkComponents={{
+    linkToRecordComponents={{
       TeamMemberRecord: LinkToTeamMember,
     }}
   />
@@ -139,7 +139,7 @@ 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 `overrides` prop.
+In this case, you can easily override default rendering rules with the `nodeOverrides` prop.
 
 ```astro
 ---
@@ -150,7 +150,7 @@ import Code from '~/components/Code/index.astro';
 
 <StructuredText
   data={blogPost.content}
-  components={{
+  nodeOverrides={{
     heading: HeadingWithAnchorLink,
     code: Code,
   }}
@@ -159,10 +159,11 @@ import Code from '~/components/Code/index.astro';
 
 ## Props
 
-| 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            |
+| 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  |
+| linkToRecordComponents | `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 |
+| inlineRecordComponents | `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 |
+| nodeOverrides          | `Record<string, AstroComponent>` |                    | An object in which the keys are the types of DAST nodes to override, and the values are the Astro components            |
+| markOverrides          | `Record<string, AstroComponent>` |                    | An object in which the keys are the types of `span` node marks to override, and the values are the Astro components     |

package/src/StructuredText/StructuredText.astro

@@ -10,7 +10,13 @@ import {
 } from 'datocms-structured-text-utils';
 
 import Node from './Node.astro';
-import type { BlockComponents, InlineItemComponents, ItemLinkComponents, Overrides } from './types';
+import type {
+  BlockComponents,
+  InlineRecordComponents,
+  LinkToRecordComponents,
+  NodeOverrides,
+  MarkOverrides,
+} from './types';
 
 // It would be better to type this as:
 //
@@ -19,12 +25,20 @@ import type { BlockComponents, InlineItemComponents, ItemLinkComponents, Overrid
 // but it's currently not possible: https://github.com/withastro/roadmap/discussions/601#discussioncomment-10333959
 
 interface Props {
+  /** The actual [field value](https://www.datocms.com/docs/structured-text/dast) you get from a DatoCMS Structured Text field */
   data: StructuredText<DatocmsRecord, DatocmsRecord> | Document | DastNode | null | undefined;
 
+  /** An object in which the keys are the `__typename` of the blocks to be rendered, and the values are the Astro components  */
   blockComponents?: BlockComponents<DatocmsRecord, DatocmsRecord>;
-  itemLinkComponents?: ItemLinkComponents<DatocmsRecord, DatocmsRecord>;
-  inlineItemComponents?: InlineItemComponents<DatocmsRecord, DatocmsRecord>;
-  overrides?: Overrides;
+  /** An object in which the keys are the `__typename` of the records to be rendered, and the values are the Astro components */
+  linkToRecordComponents?: LinkToRecordComponents<DatocmsRecord, DatocmsRecord>;
+  /** An object in which the keys are the `__typename` of the records to be rendered, and the values are the Astro components */
+  inlineRecordComponents?: InlineRecordComponents<DatocmsRecord, DatocmsRecord>;
+
+  /** An object in which the keys are the types of DAST nodes to override, and the values are the Astro components */
+  nodeOverrides?: NodeOverrides;
+  /** An object in which the keys are the types of `span` node marks to override, and the values are the Astro components */
+  markOverrides?: MarkOverrides;
 }
 
 const { data, ...rest } = Astro.props;

package/src/StructuredText/nodes/InlineItem.astro

@@ -4,21 +4,21 @@ import {
   RenderError,
   type InlineItem,
 } from 'datocms-structured-text-utils';
-import type { InlineItemComponents } from '../types';
+import type { InlineRecordComponents } from '../types';
 
 interface Props {
   node: InlineItem;
   record: DatocmsRecord;
-  inlineItemComponents?: InlineItemComponents<DatocmsRecord, DatocmsRecord>;
+  inlineRecordComponents?: InlineRecordComponents<DatocmsRecord, DatocmsRecord>;
 }
 
-const { node, record, inlineItemComponents } = Astro.props;
+const { node, record, inlineRecordComponents } = Astro.props;
 
-const Component = inlineItemComponents?.[record.__typename];
+const Component = inlineRecordComponents?.[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!`,
+    `The Structured Text document contains an 'inlineItem' node, but no component for rendering it is specified in the inlineRecordComponents prop!`,
     node,
   );
 }

package/src/StructuredText/nodes/ItemLink.astro

@@ -5,23 +5,23 @@ import {
   type ItemLink,
 } from 'datocms-structured-text-utils';
 
-import type { ItemLinkComponents } from '../types';
+import type { LinkToRecordComponents } from '../types';
 
 import { defaultMetaTransformer } from 'datocms-structured-text-generic-html-renderer';
 
 interface Props {
   node: ItemLink;
   record: DatocmsRecord;
-  itemLinkComponents?: ItemLinkComponents<DatocmsRecord, DatocmsRecord>;
+  linkToRecordComponents?: LinkToRecordComponents<DatocmsRecord, DatocmsRecord>;
 }
 
-const { node, record, itemLinkComponents } = Astro.props;
+const { node, record, linkToRecordComponents } = Astro.props;
 
-const Component = itemLinkComponents?.[record.__typename];
+const Component = linkToRecordComponents?.[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!`,
+    `The Structured Text document contains an 'itemLink' node, but no component for rendering it is specified in the linkToRecordComponents prop!`,
     node,
   );
 }

package/src/StructuredText/nodes/Span.astro

@@ -1,56 +1,49 @@
 ---
-import type { Span } from 'datocms-structured-text-utils';
+import type { Mark, Span } from 'datocms-structured-text-utils';
 import Lines from '../Lines.astro';
+import type { MarkOverrides } from '../types';
 
 interface Props {
   node: Span;
+  markOverrides?: MarkOverrides;
 }
 
-const { node } = Astro.props;
+const { node, markOverrides } = Astro.props;
 
 const { type, value, marks } = node;
 
 const [mark, ...otherMarks] = marks ?? [];
+
+function markToComponent(mark: Mark) {
+  if (markOverrides && mark in markOverrides) {
+    return markOverrides[mark];
+  }
+
+  switch (mark) {
+    case 'emphasis':
+      return 'em';
+    case 'underline':
+      return 'u';
+    case 'strikethrough':
+      return 's';
+    case 'highlight':
+      return 'mark';
+    default:
+      return mark;
+  }
+}
+
+const MarkComponent = mark ? markToComponent(mark) : null;
 ---
 
 {
-  !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>
+  MarkComponent ? (
+    <MarkComponent>
       <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
+    </MarkComponent>
+  ) : (
+    <Lines lines={node.value.split(/\n/)} />
+  )
 }

package/src/StructuredText/types.ts

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