@datocms/svelte 4.2.9 → 4.2.11

package/package/components/ContentLink/ContentLink.svelte

@@ -23,13 +23,10 @@ onMount(() => {
     // Control stega encoding stripping behavior
     ...stripStega !== void 0 ? { stripStega } : {}
   });
-  if (enableClickToEdit && typeof window !== "undefined" && window.self === window.top) {
-    const shouldEnable = enableClickToEdit === true || !enableClickToEdit.hoverOnly || window.matchMedia("(hover: hover)").matches;
-    if (shouldEnable) {
-      controller.enableClickToEdit(
-        enableClickToEdit === true ? void 0 : { scrollToNearestTarget: enableClickToEdit.scrollToNearestTarget ?? false }
-      );
-    }
+  if (enableClickToEdit && typeof window !== "undefined" && window.self === window.top && (enableClickToEdit === true || !enableClickToEdit.hoverOnly || window.matchMedia("(hover: hover)").matches)) {
+    controller.enableClickToEdit(
+      enableClickToEdit === true ? void 0 : { scrollToNearestTarget: enableClickToEdit.scrollToNearestTarget ?? false }
+    );
   }
 });
 $:

package/package/components/ContentLink/README.md

@@ -38,12 +38,19 @@ This drastically improves the editing experience, especially for non-technical u
 - [Flash-all highlighting](#flash-all-highlighting)
 - [Props](#props)
   - [ClickToEditOptions](#clicktoeditoptions)
-- [StructuredText integration](#structuredtext-integration)
-  - [Edit groups with `data-datocms-content-link-group`](#edit-groups-with-data-datocms-content-link-group)
-  - [Edit boundaries with `data-datocms-content-link-boundary`](#edit-boundaries-with-data-datocms-content-link-boundary)
-- [Manual overlays](#manual-overlays)
-  - [Using `data-datocms-content-link-url`](#using-data-datocms-content-link-url)
-  - [Using `data-datocms-content-link-source`](#using-data-datocms-content-link-source)
+- [Data attributes reference](#data-attributes-reference)
+  - [Developer-specified attributes](#developer-specified-attributes)
+    - [`data-datocms-content-link-url`](#data-datocms-content-link-url)
+    - [`data-datocms-content-link-source`](#data-datocms-content-link-source)
+    - [`data-datocms-content-link-group`](#data-datocms-content-link-group)
+    - [`data-datocms-content-link-boundary`](#data-datocms-content-link-boundary)
+  - [Library-managed attributes](#library-managed-attributes)
+    - [`data-datocms-contains-stega`](#data-datocms-contains-stega)
+    - [`data-datocms-auto-content-link-url`](#data-datocms-auto-content-link-url)
+- [How group and boundary resolution works](#how-group-and-boundary-resolution-works)
+- [Structured Text fields](#structured-text-fields)
+  - [Rule 1: Always wrap the Structured Text component in a group](#rule-1-always-wrap-the-structured-text-component-in-a-group)
+  - [Rule 2: Wrap embedded blocks, inline blocks, and inline records in a boundary](#rule-2-wrap-embedded-blocks-inline-blocks-and-inline-records-in-a-boundary)
 - [Low-level utilities](#low-level-utilities)
   - [`decodeStega`](#decodestega)
   - [`stripStega`](#stripstega)
@@ -51,6 +58,7 @@ This drastically improves the editing experience, especially for non-technical u
   - [Click-to-edit overlays not appearing](#click-to-edit-overlays-not-appearing)
   - [Navigation not syncing with Web Previews plugin](#navigation-not-syncing-with-web-previews-plugin)
   - [StructuredText blocks not clickable](#structuredtext-blocks-not-clickable)
+  - [Layout issues caused by stega encoding](#layout-issues-caused-by-stega-encoding)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
@@ -173,124 +181,309 @@ The `scrollToNearestTarget` parameter scrolls to the nearest editable element, u
 
 ## Props
 
-| Prop                | Type                                      | Default | Description                                                                                                                                            |
-| ------------------- | ----------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `onNavigateTo`      | `(path: string) => void`                  | -       | Callback when [Web Previews plugin](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-web-previews) requests navigation to a different page |
-| `currentPath`       | `string`                                  | -       | Current pathname to sync with [Web Previews plugin](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-web-previews)                         |
-| `enableClickToEdit` | `boolean \| ClickToEditOptions` | -       | Enable click-to-edit overlays on mount. Pass `true` or an object with options. If undefined or false, click-to-edit is disabled                                |
-| `stripStega`        | `boolean`                                 | -       | Whether to strip stega encoding from text nodes after stamping                                                                                         |
-| `root`              | `ParentNode`                              | -       | Root element to limit scanning to instead of the entire document                                                                                       |
+| Prop                | Type                            | Default | Description                                                                                                                                            |
+| ------------------- | ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `onNavigateTo`      | `(path: string) => void`        | -       | Callback when [Web Previews plugin](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-web-previews) requests navigation to a different page |
+| `currentPath`       | `string`                        | -       | Current pathname to sync with [Web Previews plugin](https://www.datocms.com/marketplace/plugins/i/datocms-plugin-web-previews)                         |
+| `enableClickToEdit` | `boolean \| ClickToEditOptions` | -       | Enable click-to-edit overlays on mount. Pass `true` or an object with options. If undefined or false, click-to-edit is disabled                        |
+| `stripStega`        | `boolean`                       | -       | Whether to strip stega encoding from text nodes after stamping                                                                                         |
+| `root`              | `ParentNode`                    | -       | Root element to limit scanning to instead of the entire document                                                                                       |
 
 ### ClickToEditOptions
 
 When passing an object to `enableClickToEdit`, the following options are available:
 
-| Option                  | Type      | Default | Description                                                                                                                                                                                                     |
-| ----------------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Option                  | Type      | Default | Description                                                                                                                                                                                                    |
+| ----------------------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `scrollToNearestTarget` | `boolean` | `false` | Automatically scroll to the nearest editable element if none is currently visible in the viewport when click-to-edit mode is enabled. Also triggers the flash-all highlighting effect.                         |
 | `hoverOnly`             | `boolean` | `false` | Only enable click-to-edit on devices that support hover (non-touch devices). Uses `window.matchMedia('(hover: hover)')` to detect hover capability. Useful to avoid overlays interfering with touch scrolling. |
 
-## StructuredText integration
+## Data attributes reference
 
-When rendering Structured Text fields, you'll want to make the entire structured text area clickable rather than just specific spans. DatoCMS provides special HTML attributes to control this behavior.
+This library uses several `data-datocms-*` attributes. Some are **developer-specified** (you add them to your markup), and some are **library-managed** (added automatically during DOM stamping). Here's a complete reference.
 
-### Edit groups with `data-datocms-content-link-group`
+### Developer-specified attributes
 
-Wrap your StructuredText component with a container that has the `data-datocms-content-link-group` attribute. This makes the entire area clickable to edit the structured text field:
+These attributes are added by you in your templates/components to control how editable regions behave.
+
+#### `data-datocms-content-link-url`
+
+Manually marks an element as editable with an explicit edit URL. Use this for non-text fields (booleans, numbers, dates, JSON) that cannot contain stega encoding. The recommended approach is to use the `_editingUrl` field available on all records:
+
+```graphql
+query {
+  product {
+    id
+    price
+    isActive
+    _editingUrl
+  }
+}
+```
 
 ```svelte
-<script>
-  import { StructuredText } from '@datocms/svelte';
-</script>
+<span data-datocms-content-link-url={product._editingUrl}>
+  ${product.price}
+</span>
+```
+
+#### `data-datocms-content-link-source`
+
+Attaches stega-encoded metadata without the need to render it as content. Useful for structural elements that cannot contain text (like `<video>`, `<audio>`, `<iframe>`, etc.) or when stega encoding in visible text would be problematic:
+
+```svelte
+<div data-datocms-content-link-source={video.alt}>
+  <video src={video.url} poster={video.posterImage.url} controls />
+</div>
+```
+
+The value must be a stega-encoded string (any text field from the API will work). The library decodes the stega metadata from the attribute value and makes the element clickable to edit.
+
+#### `data-datocms-content-link-group`
+
+Expands the clickable area to a parent element. When the library encounters stega-encoded content, by default it makes the immediate parent of the text node clickable to edit. Adding this attribute to an ancestor makes that ancestor the clickable target instead:
+
+```svelte
+<article data-datocms-content-link-group>
+  <!-- product.title contains stega encoding -->
+  <h2>{product.title}</h2>
+  <p>${product.price}</p>
+</article>
+```
+
+Here, clicking anywhere in the `<article>` opens the editor, rather than requiring users to click precisely on the `<h2>`.
+
+**Important:** A group should contain only one stega-encoded source. If multiple stega strings resolve to the same group, the library logs a collision warning and only the last URL wins.
+
+#### `data-datocms-content-link-boundary`
+
+Stops the upward DOM traversal that looks for a `data-datocms-content-link-group`, making the element where stega was found the clickable target instead. This creates an independent editable region that won't merge into a parent group (see [How group and boundary resolution works](#how-group-and-boundary-resolution-works) below for details):
+
+```svelte
+<div data-datocms-content-link-group>
+  <!-- page.title contains stega encoding → resolves to URL A -->
+  <h1>{page.title}</h1>
+  <section data-datocms-content-link-boundary>
+    <!-- page.author contains stega encoding → resolves to URL B -->
+    <span>{page.author}</span>
+  </section>
+</div>
+```
+
+Without the boundary, clicking `page.author` would open URL A (the outer group). With the boundary, the `<span>` becomes the clickable target opening URL B.
+
+The boundary can also be placed directly on the element that contains the stega text:
+
+```svelte
+<div data-datocms-content-link-group>
+  <!-- page.title contains stega encoding → resolves to URL A -->
+  <h1>{page.title}</h1>
+  <!-- page.author contains stega encoding → resolves to URL B -->
+  <span data-datocms-content-link-boundary>{page.author}</span>
+</div>
+```
+
+Here, the `<span>` has the boundary and directly contains the stega text, so the `<span>` itself becomes the clickable target (since the starting element and the boundary element are the same).
+
+### Library-managed attributes
+
+These attributes are added automatically by the library during DOM stamping. You do not need to add them yourself, but you can target them in CSS or JavaScript.
+
+#### `data-datocms-contains-stega`
+
+Added to elements whose text content contains stega-encoded invisible characters. This attribute is only present when `stripStega` is `false` (the default), since with `stripStega: true` the characters are removed entirely. Useful for CSS workarounds — the zero-width characters can sometimes cause unexpected letter-spacing or text overflow:
+
+```css
+[data-datocms-contains-stega] {
+  letter-spacing: 0 !important;
+}
+```
+
+#### `data-datocms-auto-content-link-url`
+
+Added automatically to elements that the library has identified as editable targets (through stega decoding and group/boundary resolution). Contains the resolved edit URL.
+
+This is the automatic counterpart to the developer-specified `data-datocms-content-link-url`. The library adds `data-datocms-auto-content-link-url` wherever it can extract an edit URL from stega encoding, while `data-datocms-content-link-url` is needed for non-text fields (booleans, numbers, dates, etc.) where stega encoding cannot be embedded. Both attributes are used by the click-to-edit overlay system to determine which elements are clickable and where they link to.
+
+## How group and boundary resolution works
+
+When the library encounters stega-encoded content inside an element, it walks up the DOM tree from that element:
+
+1. If it finds a `data-datocms-content-link-group`, it stops and stamps **that** element as the clickable target.
+2. If it finds a `data-datocms-content-link-boundary`, it stops and stamps the **starting element** as the clickable target — further traversal is prevented.
+3. If it reaches the root without finding either, it stamps the **starting element**.
+
+Here are some concrete examples to illustrate:
+
+**Example 1: Nested groups**
+
+```svelte
+<div data-datocms-content-link-group>
+  <!-- page.title contains stega encoding → resolves to URL A -->
+  <h1>{page.title}</h1>
+  <div data-datocms-content-link-group>
+    <!-- page.subtitle contains stega encoding → resolves to URL B -->
+    <p>{page.subtitle}</p>
+  </div>
+</div>
+```
+
+- **`page.title`**: walks up from `<h1>`, finds the outer group → the **outer `<div>`** becomes clickable (opens URL A).
+- **`page.subtitle`**: walks up from `<p>`, finds the inner group first → the **inner `<div>`** becomes clickable (opens URL B). The outer group is never reached.
+
+Each nested group creates an independent clickable region. The innermost group always wins for its own content.
 
+**Example 2: Boundary preventing group propagation**
+
+```svelte
+<div data-datocms-content-link-group>
+  <!-- page.title contains stega encoding → resolves to URL A -->
+  <h1>{page.title}</h1>
+  <section data-datocms-content-link-boundary>
+    <!-- page.author contains stega encoding → resolves to URL B -->
+    <span>{page.author}</span>
+  </section>
+</div>
+```
+
+- **`page.title`**: walks up from `<h1>`, finds the outer group → the **outer `<div>`** becomes clickable (opens URL A).
+- **`page.author`**: walks up from `<span>`, hits the `<section>` boundary → traversal stops, the **`<span>`** itself becomes clickable (opens URL B). The outer group is not reached.
+
+**Example 3: Boundary inside a group**
+
+```svelte
+<div data-datocms-content-link-group>
+  <!-- page.description contains stega encoding → resolves to URL A -->
+  <p>{page.description}</p>
+  <div data-datocms-content-link-boundary>
+    <!-- page.footnote contains stega encoding → resolves to URL B -->
+    <p>{page.footnote}</p>
+  </div>
+</div>
+```
+
+- **`page.description`**: walks up from `<p>`, finds the outer group → the **outer `<div>`** becomes clickable (opens URL A).
+- **`page.footnote`**: walks up from `<p>`, hits the boundary → traversal stops, the **`<p>`** itself becomes clickable (opens URL B). The outer group is not reached.
+
+**Example 4: Multiple stega strings without groups (collision warning)**
+
+```svelte
+<p>
+  <!-- Both product.name and product.tagline contain stega encoding -->
+  {product.name}
+  {product.tagline}
+</p>
+```
+
+Both stega-encoded strings resolve to the same `<p>` element. The library logs a console warning and the last URL wins. To fix this, wrap each piece of content in its own element:
+
+```svelte
+<p>
+  <span>{product.name}</span>
+  <span>{product.tagline}</span>
+</p>
+```
+
+## Structured Text fields
+
+Structured Text fields require special attention because of how stega encoding works within them:
+
+- The DatoCMS API encodes stega information inside a single `<span>` within the structured text output. Without any configuration, only that small span would be clickable.
+- Structured Text fields can contain **embedded blocks** and **inline records**, each with their own editing URL that should open a different record in the editor.
+
+Here are the rules to follow:
+
+### Rule 1: Always wrap the Structured Text component in a group
+
+This makes the entire structured text area clickable, instead of just the tiny stega-encoded span:
+
+```svelte
 <div data-datocms-content-link-group>
-  <StructuredText data={content.structuredTextField} />
+  <StructuredText data={page.content} />
 </div>
 ```
 
-This allows editors to click anywhere within the structured text content to edit it, rather than targeting small span elements.
+### Rule 2: Wrap embedded blocks, inline blocks, and inline records in a boundary
 
-### Edit boundaries with `data-datocms-content-link-boundary`
+Embedded blocks, inline blocks, and inline records each have their own edit URL (pointing to the block/record). Without a boundary, clicking them would bubble up to the parent group and open the structured text field editor instead. Add `data-datocms-content-link-boundary` to the root element of your custom components to prevent them from merging into the parent group.
 
-When your Structured Text contains embedded blocks, you'll want those blocks to open their own specific record editor instead of the structured text field editor. Use the `data-datocms-content-link-boundary` attribute to stop the upward traversal:
+**Note on record links (item links):** Record links (`isItemLink`) typically do **not** need a boundary. They render as `<a>` tags wrapping text that already belongs to the surrounding structured text. Unlike embedded blocks or inline records, record links don't introduce a separate editing target with its own stega-encoded URL, so there's no URL collision and no reason to isolate them from the parent group. When an editor clicks on that text, it correctly opens the structured text field editor (the parent group). Only add a boundary to a record link if you specifically want clicking it to open the linked record's editor instead.
 
 ```svelte
 <script>
   import { StructuredText } from '@datocms/svelte';
-  import BlockComponent from './BlockComponent.svelte';
+  import { isBlock, isInlineBlock, isInlineItem, isItemLink } from 'datocms-structured-text-utils';
+  import Block from './Block.svelte';
+  import InlineBlock from './InlineBlock.svelte';
+  import InlineItem from './InlineItem.svelte';
+  import ItemLink from './ItemLink.svelte';
 </script>
 
 <div data-datocms-content-link-group>
   <StructuredText
-    data={content.structuredTextField}
-    blocks={{
-      // Render custom blocks
-      myBlock: (props) => ({
-        component: BlockComponent,
-        props: {
-          block: props.record,
-          // Wrap the block with a boundary
-          useBoundary: true,
-        }
-      })
-    }}
+    data={page.content}
+    components={[
+      [isBlock, Block],
+      [isInlineBlock, InlineBlock],
+      [isInlineItem, InlineItem],
+      [isItemLink, ItemLink],
+    ]}
   />
 </div>
+```
+
+Then, in your custom components, wrap the root element with `data-datocms-content-link-boundary`:
+
+```svelte
+<!-- Block.svelte -->
+<script>
+  export let block;
+</script>
 
-<!-- In BlockComponent.svelte -->
 <div data-datocms-content-link-boundary>
   <h2>{block.title}</h2>
   <p>{block.description}</p>
 </div>
 ```
 
-In this example:
-- Clicking on the main structured text content opens the structured text field editor
-- Clicking on an embedded block opens that specific block's record editor
-
-## Manual overlays
-
-In some cases, you may want to manually create click-to-edit overlays for content that doesn't have stega encoding.
-
-### Using `data-datocms-content-link-url`
-
-You can add the `data-datocms-content-link-url` attribute with a DatoCMS editing URL:
+```svelte
+<!-- InlineBlock.svelte -->
+<script>
+  export let block;
+</script>
 
-```graphql
-query {
-  product {
-    id
-    price
-    isActive
-    _editingUrl
-  }
-}
+<span data-datocms-content-link-boundary>
+  <em>{block.username}</em>
+</span>
 ```
 
 ```svelte
-<span data-datocms-content-link-url={product._editingUrl}>
-  ${product.price}
-</span>
+<!-- InlineItem.svelte -->
+<script>
+  export let link;
+</script>
 
-<span data-datocms-content-link-url={product._editingUrl}>
-  {product.isActive ? 'Active' : 'Inactive'}
+<span data-datocms-content-link-boundary>
+  {link.title}
 </span>
 ```
 
-### Using `data-datocms-content-link-source`
-
-For elements without visible stega-encoded content, use the [`data-datocms-content-link-source`](https://github.com/datocms/content-link?tab=readme-ov-file#stamping-elements-via-data-datocms-content-link-source) attribute to attach stega metadata directly:
+Record links don't need a boundary — their content belongs to the surrounding structured text:
 
 ```svelte
-<!-- product.asset.video.alt contains stega-encoded info -->
-<video
-  src={product.asset.video.url}
-  data-datocms-content-link-source={product.asset.video.alt}
-  controls
-/>
+<!-- ItemLink.svelte -->
+<script>
+  export let link;
+</script>
+
+<a href={`/posts/${link.slug}`}>
+  <slot />
+</a>
 ```
 
-This is useful for structural elements like `<video>`, `<audio>`, or `<iframe>` where stega encoding in visible text would be problematic.
+With this setup:
+- Clicking the main text (paragraphs, headings, lists) — including record links — opens the **structured text field editor**
+- Clicking an embedded block, inline block, or inline record opens **that record's editor**
 
 ## Low-level utilities
 
@@ -398,4 +591,22 @@ These utilities are useful when you need to:
    </div>
    ```
 
-2. Add `data-datocms-content-link-boundary` to custom blocks to prevent them from bubbling to the parent field
+2. Add `data-datocms-content-link-boundary` to custom blocks, inline blocks, and inline records to prevent them from bubbling to the parent field (record links typically don't need a boundary)
+
+### Layout issues caused by stega encoding
+
+**Problem**: The invisible zero-width characters can cause unexpected letter-spacing or text breaking out of containers.
+
+**Solutions**:
+1. Use the `stripStega` prop to remove stega encoding after processing:
+   ```svelte
+   <ContentLink stripStega={true} />
+   ```
+
+2. Use CSS to reset letter-spacing on elements with stega-encoded content:
+   ```css
+   [data-datocms-contains-stega] {
+     letter-spacing: 0 !important;
+   }
+   ```
+   This attribute is automatically added to elements with stega-encoded content when `stripStega: false` (the default)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@datocms/svelte",
-	"version": "4.2.9",
+	"version": "4.2.11",
 	"description": "A set of components and utilities to work faster with DatoCMS in Svelte",
 	"license": "MIT",
 	"repository": {
@@ -35,8 +35,8 @@
 		}
 	},
 	"devDependencies": {
-		"@mux/mux-player": "^2.5.0",
-		"@mux/playback-core": "^0.22.1",
+		"@mux/mux-player": "^3.11.4",
+		"@mux/playback-core": "^0.33.1",
 		"@sveltejs/adapter-auto": "^3.0.0",
 		"@sveltejs/kit": "^2.0.0",
 		"@sveltejs/package": "^2.0.0",
@@ -66,7 +66,7 @@
 	},
 	"type": "module",
 	"dependencies": {
-		"@datocms/content-link": "^0.3.10",
+		"@datocms/content-link": "^0.3.13",
 		"datocms-listen": "^1.0.2",
 		"datocms-structured-text-utils": "^5.1.6",
 		"svelte-intersection-observer": "^1.0.0"