@datocms/astro 0.4.1 → 0.5.1

package/README.md

@@ -44,27 +44,44 @@ npm install @datocms/astro
 
 # What is DatoCMS?
 
-<a href="https://www.datocms.com/"><img src="https://www.datocms.com/images/full_logo.svg" height="60"></a>
+<a href="https://www.datocms.com/"><img src="https://www.datocms.com/images/full_logo.svg" height="60" alt="DatoCMS - The Headless CMS for the Modern Web"></a>
 
 [DatoCMS](https://www.datocms.com/) is the REST & GraphQL Headless CMS for the modern web.
 
-Trusted by over 25,000 enterprise businesses, agency partners, and individuals across the world, DatoCMS users create online content at scale from a central hub and distribute it via API. We ❤️ our [developers](https://www.datocms.com/team/best-cms-for-developers), [content editors](https://www.datocms.com/team/content-creators) and [marketers](https://www.datocms.com/team/cms-digital-marketing)!
+Trusted by over 25,000 enterprise businesses, agencies, and individuals across the world, DatoCMS users create online content at scale from a central hub and distribute it via API. We ❤️ our [developers](https://www.datocms.com/team/best-cms-for-developers), [content editors](https://www.datocms.com/team/content-creators) and [marketers](https://www.datocms.com/team/cms-digital-marketing)!
+
+**Why DatoCMS?**
+
+- **API-First Architecture**: Built for both REST and GraphQL, enabling flexible content delivery
+- **Just Enough Features**: We believe in keeping things simple, and giving you [the right feature-set tools](https://www.datocms.com/features) to get the job done
+- **Developer Experience**: First-class TypeScript support with powerful developer tools
+
+**Getting Started:**
+
+- ⚡️ [Create Free Account](https://dashboard.datocms.com/signup) - Get started with DatoCMS in minutes
+- 🔖 [Documentation](https://www.datocms.com/docs) - Comprehensive guides and API references
+- ⚙️ [Community Support](https://community.datocms.com/) - Get help from our team and community
+- 🆕 [Changelog](https://www.datocms.com/product-updates) - Latest features and improvements
+
+**Official Libraries:**
+
+- [**Content Delivery Client**](https://github.com/datocms/cda-client) - TypeScript GraphQL client for content fetching
+- [**REST API Clients**](https://github.com/datocms/js-rest-api-clients) - Node.js/Browser clients for content management
+- [**CLI Tools**](https://github.com/datocms/cli) - Command-line utilities for schema migrations (includes [Contentful](https://github.com/datocms/cli/tree/main/packages/cli-plugin-contentful) and [WordPress](https://github.com/datocms/cli/tree/main/packages/cli-plugin-wordpress) importers)
 
-**Quick links:**
+**Official Framework Integrations**
 
-- ⚡️ Get started with a [free DatoCMS account](https://dashboard.datocms.com/signup)
-- 🔖 Go through the [docs](https://www.datocms.com/docs)
-- ⚙️ Get [support from us and the community](https://community.datocms.com/)
-- 🆕 Stay up to date on new features and fixes on the [changelog](https://www.datocms.com/product-updates)
+Helpers to manage SEO, images, video and Structured Text coming from your DatoCMS projects:
 
-**Our featured repos:**
+- [**React Components**](https://github.com/datocms/react-datocms)
+- [**Vue Components**](https://github.com/datocms/vue-datocms)
+- [**Svelte Components**](https://github.com/datocms/datocms-svelte)
+- [**Astro Components**](https://github.com/datocms/astro-datocms)
 
-- [datocms/react-datocms](https://github.com/datocms/react-datocms): React helper components for images, Structured Text rendering, and more
-- [datocms/js-rest-api-clients](https://github.com/datocms/js-rest-api-clients): Node and browser JavaScript clients for updating and administering your content. For frontend fetches, we recommend using our [GraphQL Content Delivery API](https://www.datocms.com/docs/content-delivery-api) instead.
-- [datocms/cli](https://github.com/datocms/cli): Command-line interface that includes our [Contentful importer](https://github.com/datocms/cli/tree/main/packages/cli-plugin-contentful) and [Wordpress importer](https://github.com/datocms/cli/tree/main/packages/cli-plugin-wordpress)
-- [datocms/plugins](https://github.com/datocms/plugins): Example plugins we've made that extend the editor/admin dashboard
-- [DatoCMS Starters](https://www.datocms.com/marketplace/starters) has examples for various Javascript frontend frameworks
+**Additional Resources:**
 
-Or see [all our public repos](https://github.com/orgs/datocms/repositories?q=&type=public&language=&sort=stargazers)
+- [**Plugin Examples**](https://github.com/datocms/plugins) - Example plugins we've made that extend the editor/admin dashboard
+- [**Starter Projects**](https://www.datocms.com/marketplace/starters) - Example website implementations for popular frameworks
+- [**All Public Repositories**](https://github.com/orgs/datocms/repositories?q=&type=public&language=&sort=stargazers)
 
 <!--datocms-autoinclude-footer end-->

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.4.1",
+  "version": "0.5.1",
   "sideEffects": false,
   "repository": {
     "type": "git",
@@ -45,8 +45,8 @@
   "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"
+    "datocms-structured-text-generic-html-renderer": "^4.1.2",
+    "datocms-structured-text-utils": "^4.1.2"
   },
   "peerDependencies": {
     "astro": "*"

package/src/Image/Image.astro

@@ -14,6 +14,7 @@ const {
   usePlaceholder = true,
   sizes,
   srcSetCandidates = [0.25, 0.5, 0.75, 1, 1.5, 2, 3, 4],
+  referrerPolicy = 'strict-origin',
 } = Astro.props;
 
 const placeholderStyle =
@@ -59,6 +60,7 @@ const sizingStyle = {
         title={data.title ?? null}
         fetchpriority={priority ? 'high' : undefined}
         loading={priority ? undefined : 'lazy'}
+        referrerpolicy={referrerPolicy}
         class={imgClass}
         style={{
           ...placeholderStyle,

package/src/Image/README.md

@@ -122,3 +122,4 @@ Here's a complete recap of what `responsiveImage` offers:
 | sizes            | string                   | undefined                          | :x:                | The HTML5 [`sizes`](https://web.dev/learn/design/responsive-images/#sizes) attribute for the image (will be used `data.sizes` as a fallback)         |
 | usePlaceholder   | Boolean                  | true                               | :x:                | Whether the image should use a blurred image placeholder                                                                                             |
 | srcSetCandidates | Array<number>            | [0.25, 0.5, 0.75, 1, 1.5, 2, 3, 4] | :x:                | If `data` does not contain `srcSet`, the candidates for the `srcset` attribute of the image will be auto-generated based on these width multipliers  |
+| referrerPolicy   | string                   | `strict-origin`                    | :x:                | Defines which referrer is sent when fetching the image. Defaults to `strict-origin` to give more useful stats in DatoCMS Project Usages              |

package/src/Image/types.ts

@@ -63,4 +63,11 @@ export type ImageProps = {
    * Default candidate multipliers are [0.25, 0.5, 0.75, 1, 1.5, 2, 3, 4]
    **/
   srcSetCandidates?: number[];
+  /**
+   * Defines which referrer is sent when fetching the image
+   * Read more: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#referrerpolicy
+   *
+   * Defaults to `strict-origin` to give more useful stats in DatoCMS Project Usages
+   **/
+  referrerPolicy?: JSX.HTMLAttributeReferrerPolicy;
 };

package/src/StructuredText/Node.astro

@@ -1,12 +1,14 @@
 ---
 import {
   type Block,
+  type InlineBlock,
   type Record as DatocmsRecord,
   type InlineItem,
   type ItemLink,
   type Node as DastNode,
   hasChildren,
   isBlock,
+  isInlineBlock,
   isInlineItem,
   isItemLink,
   RenderError,
@@ -25,11 +27,13 @@ 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 InlineBlockComponent from './nodes/InlineBlock.astro';
 import InlineItemComponent from './nodes/InlineItem.astro';
 import ItemLinkComponent from './nodes/ItemLink.astro';
 
 import type {
   BlockComponents,
+  InlineBlockComponents,
   InlineRecordComponents,
   LinkToRecordComponents,
   NodeOverrides,
@@ -44,6 +48,7 @@ interface Props {
   links?: DatocmsRecord[];
 
   blockComponents?: BlockComponents<DatocmsRecord, DatocmsRecord>;
+  inlineBlockComponents?: InlineBlockComponents<DatocmsRecord, DatocmsRecord>;
   linkToRecordComponents?: LinkToRecordComponents<DatocmsRecord, DatocmsRecord>;
   inlineRecordComponents?: InlineRecordComponents<DatocmsRecord, DatocmsRecord>;
 
@@ -57,18 +62,19 @@ const {
   blocks,
   links,
   blockComponents,
+  inlineBlockComponents,
   linkToRecordComponents,
   inlineRecordComponents,
   nodeOverrides,
   markOverrides,
 } = rest;
 
-function findRecordInBlocks(node: Block) {
+function findRecordInBlocks(node: Block | InlineBlock) {
   const record = (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!`,
+      `The Structured Text document contains a '${node.type}' node, but cannot find a record with ID ${node.item} inside data.blocks!`,
       node,
     );
   }
@@ -103,6 +109,7 @@ const defaultComponents: NodeOverrides = {
   itemLink: ItemLinkComponent,
   inlineItem: InlineItemComponent,
   block: BlockComponent,
+  inlineBlock: InlineBlockComponent,
 };
 
 const otherNodeComponents: Record<NodeType, AstroComponent> = {
@@ -117,6 +124,8 @@ const Component = otherNodeComponents[node.type] as AstroComponent;
   {
     isBlock(node) ? (
       <Component {node} block={findRecordInBlocks(node)} {blockComponents} />
+    ) : isInlineBlock(node) ? (
+      <Component {node} block={findRecordInBlocks(node)} {inlineBlockComponents} />
     ) : isInlineItem(node) ? (
       <Component {node} record={findRecordInLinks(node)} {inlineRecordComponents} />
     ) : isItemLink(node) ? (

package/src/StructuredText/README.md

@@ -10,8 +10,9 @@
 - [Setup](#setup)
 - [Basic usage](#basic-usage)
 - [Customization](#customization)
-  - [Custom components for blocks, inline records or links to records](#custom-components-for-blocks-inline-records-or-links-to-records)
+  - [Custom components for blocks, inline blocks, inline records or links to records](#custom-components-for-blocks-inline-blocks-inline-records-or-links-to-records)
   - [Override default rendering of nodes](#override-default-rendering-of-nodes)
+  - [Strict props type checking](#strict-props-type-checking)
 - [Props](#props)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -60,9 +61,10 @@ You need to use custom components in the following cases:
 - 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, inline records or links to records
+### Custom components for blocks, inline 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 `inlineBlockComponents` will be used to render inline blocks and will receive a `block` prop containing the actual block data.
 - 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).
 
@@ -129,7 +131,7 @@ const { blogPost } = await executeQuery(query, { token: '<YOUR-API-TOKEN>' });
       TeamMemberRecord: LinkToTeamMember,
     }}
   />
-</article>
+</article>gql.tada
 ```
 
 ### Override default rendering of nodes
@@ -143,6 +145,7 @@ In this case, you can easily override default rendering rules with the `nodeOver
 
 ```astro
 ---
+import { StructuredText } from '@datocms/astro/StructuredText';
 import { isHeading } from 'datocms-structured-text-utils';
 import HeadingWithAnchorLink from '~/components/HeadingWithAnchorLink/index.astro';
 import Code from '~/components/Code/index.astro';
@@ -157,13 +160,42 @@ import Code from '~/components/Code/index.astro';
 />
 ```
 
+### Strict props type checking
+
+Since [Astro doesn't support generics-typed components](https://github.com/withastro/roadmap/discussions/601) yet, you can use `ensureValidStructuredTextProps()` to strictly validate that all possible block and linked record types are managed in your `blockComponents`, `inlineRecordComponents` and `linkToRecordComponents` props.
+
+This is especially useful when working with tools like [gql.tada](https://gql-tada.0no.co/) that provide precise typing for your `data`:
+
+```astro
+---
+import { StructuredText, ensureValidStructuredTextProps } from '@datocms/astro/StructuredText';
+---
+
+<StructuredText
+  {...ensureValidStructuredTextProps({
+    data: blogPost.content,
+    blockComponents: {
+      CtaRecord: Cta,
+      NewsletterSignupRecord: NewsletterSignup,
+    },
+    inlineRecordComponents: {
+      TeamMemberRecord: InlineTeamMember,
+    },
+    linkToRecordComponents: {
+      TeamMemberRecord: LinkToTeamMember,
+    },
+  })}
+/>
+```
+
 ## 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  |
-| 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     |
+| 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        |
+| inlineBlockComponents  | `Record<string, AstroComponent>` |                    | An object in which the keys are the `__typename` of the inline 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

@@ -26,6 +26,8 @@ interface Props {
 
   /** An object in which the keys are the `__typename` of the blocks to be rendered, and the values are the Astro components  */
   blockComponents?: Record<string, AstroComponent>;
+  /** An object in which the keys are the `__typename` of the inline blocks to be rendered, and the values are the Astro components  */
+  inlineBlockComponents?: 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 */
   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 */

package/src/StructuredText/ensureValidStructuredTextProps.ts

@@ -4,13 +4,19 @@ import {
   type Document,
   type StructuredText,
 } from 'datocms-structured-text-utils';
-import type { BlockComponents, InlineRecordComponents, LinkToRecordComponents } from './types';
+import type {
+  BlockComponents,
+  InlineBlockComponents,
+  InlineRecordComponents,
+  LinkToRecordComponents,
+} from './types';
 
 type Props<R1 extends DatocmsRecord, R2 extends DatocmsRecord> =
   | {
       /** The actual [field value](https://www.datocms.com/docs/structured-text/dast) you get from a DatoCMS Structured Text field */
       data: Document | DastNode | null | undefined;
       blockComponents?: never;
+      inlineBlockComponents?: never;
       linkToRecordComponents?: never;
       inlineRecordComponents?: never;
     }
@@ -22,6 +28,8 @@ type Props<R1 extends DatocmsRecord, R2 extends DatocmsRecord> =
         | 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<R1, R2>;
+      /** An object in which the keys are the `__typename` of the inline blocks to be rendered, and the values are the Astro components  */
+      inlineBlockComponents: BlockComponents<R1, R2>;
       /** An object in which the keys are the `__typename` of the records to be rendered, and the values are the Astro components */
       linkToRecordComponents: LinkToRecordComponents<R1, R2>;
       /** An object in which the keys are the `__typename` of the records to be rendered, and the values are the Astro components */
@@ -35,6 +43,7 @@ type Props<R1 extends DatocmsRecord, R2 extends DatocmsRecord> =
         | 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<R1, R2>;
+      inlineBlockComponents: InlineBlockComponents<R1, R2>;
       linkToRecordComponents?: never;
       inlineRecordComponents?: never;
     }
@@ -45,6 +54,7 @@ type Props<R1 extends DatocmsRecord, R2 extends DatocmsRecord> =
         | null
         | undefined;
       blockComponents?: never;
+      inlineBlockComponents?: never;
       /** An object in which the keys are the `__typename` of the records to be rendered, and the values are the Astro components */
       linkToRecordComponents: LinkToRecordComponents<R1, R2>;
       /** An object in which the keys are the `__typename` of the records to be rendered, and the values are the Astro components */
@@ -57,6 +67,7 @@ type Props<R1 extends DatocmsRecord, R2 extends DatocmsRecord> =
         | null
         | undefined;
       blockComponents?: never;
+      inlineBlockComponents?: never;
       linkToRecordComponents?: never;
       inlineRecordComponents?: never;
     };

package/src/StructuredText/nodes/InlineBlock.astro

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

package/src/StructuredText/types.ts

@@ -2,6 +2,7 @@ import type { TransformedMeta } from 'datocms-structured-text-generic-html-rende
 import type {
   Block,
   Record as DatocmsRecord,
+  InlineBlock,
   InlineItem,
   ItemLink,
   Mark,
@@ -16,6 +17,10 @@ export type BlockComponents<R1 extends DatocmsRecord, _R2 extends DatocmsRecord>
   [R in R1 as R['__typename']]: AstroComponent<{ block: R }>;
 };
 
+export type InlineBlockComponents<R1 extends DatocmsRecord, _R2 extends DatocmsRecord> = {
+  [R in R1 as R['__typename']]: AstroComponent<{ block: R }>;
+};
+
 export type LinkToRecordComponents<_R1 extends DatocmsRecord, R2 extends DatocmsRecord> = {
   [R in R2 as R['__typename']]: AstroComponent<{
     node: ItemLink;
@@ -53,7 +58,13 @@ export type NodeOverrides = Partial<{
                 node: N;
                 markOverrides?: MarkOverrides;
               }
-            : { node: N }
+            : N extends InlineBlock
+              ? {
+                  node: N;
+                  block: DatocmsRecord;
+                  inlineBlockComponents: InlineBlockComponents<DatocmsRecord, DatocmsRecord>;
+                }
+              : { node: N }
   >;
 }>;