vue-datocms 8.1.5 → 8.1.7

package/dist/index.d.ts

@@ -1,14 +1,303 @@
 import * as vue from 'vue';
-import { PropType, h, VNode, Ref, UnwrapRef, CSSProperties } from 'vue';
+import { Ref, PropType, h, VNode, UnwrapRef, CSSProperties } from 'vue';
+import { Controller } from '@datocms/content-link';
+export { Controller, decodeStega, stripStega } from '@datocms/content-link';
 import { TransformedMeta, RenderMarkRule, TransformMetaFn } from 'datocms-structured-text-generic-html-renderer';
 export { renderMarkRule, renderNodeRule, renderNodeRule as renderRule } from 'datocms-structured-text-generic-html-renderer';
-import { Record as Record$1, RenderResult, StructuredText as StructuredText$1, CdaStructuredTextRecord, Document, Node, RenderRule } from 'datocms-structured-text-utils';
+import { Record as Record$1, RenderResult, StructuredText as StructuredText$1, Document, Node, RenderRule } from 'datocms-structured-text-utils';
 export { CdaStructuredTextRecord, CdaStructuredTextValue, RenderError, Document as StructuredTextDocument, StructuredText as StructuredTextGraphQlResponse, Record as StructuredTextGraphQlResponseRecord, TypesafeCdaStructuredTextValue } from 'datocms-structured-text-utils';
 import * as hls_js from 'hls.js';
-import { StreamTypes, MaxResolutionValue, MinResolutionValue, CmcdTypes, PlaybackTypes } from '@mux/playback-core/.';
+import { StreamTypes, MaxResolutionValue, MinResolutionValue, CmcdTypes, PlaybackTypes, RenditionOrderValue } from '@mux/playback-core/.';
 import MuxPlayerElement, { Tokens } from '@mux/mux-player';
 import { Options, ConnectionStatus } from 'datocms-listen';
 
+type UseContentLinkOptions = {
+    /**
+     * Whether the controller is enabled, or an options object.
+     * - Pass `true` (default): Enables the controller with stega encoding preserved (allows controller recreation)
+     * - Pass `false`: Disables the controller completely
+     * - Pass `{ stripStega: true }`: Enables the controller and strips stega encoding after stamping
+     *
+     * When stripStega is false (default): Stega encoding remains in the DOM, allowing controllers
+     * to be disposed and recreated on the same page. The invisible characters don't affect display
+     * but preserve the source of truth.
+     *
+     * When stripStega is true: Stega encoding is permanently removed from text nodes, providing
+     * clean textContent for programmatic access. However, recreating a controller on the same page
+     * won't detect elements since the encoding is lost.
+     */
+    enabled?: boolean | {
+        stripStega: boolean;
+    };
+    /** Callback when Web Previews plugin requests navigation */
+    onNavigateTo?: (path: string) => void;
+    /** Root element to limit scanning to (instead of document) */
+    root?: Ref<ParentNode | null | undefined>;
+};
+type UseContentLinkResult = {
+    /** The controller instance, or null if disabled */
+    controller: Ref<Controller | null>;
+    /** Enable click-to-edit overlays */
+    enableClickToEdit: (options?: {
+        scrollToNearestTarget: boolean;
+    }) => void;
+    /** Disable click-to-edit overlays */
+    disableClickToEdit: () => void;
+    /** Check if click-to-edit is enabled */
+    isClickToEditEnabled: () => boolean;
+    /** Highlight all editable elements */
+    flashAll: (scrollToNearestTarget?: boolean) => void;
+    /** Notify Web Previews plugin of current path */
+    setCurrentPath: (path: string) => void;
+};
+/**
+ * Composable for managing DatoCMS Content Link controller for Visual Editing.
+ *
+ * This composable provides low-level control over the @datocms/content-link controller,
+ * enabling click-to-edit overlays and integration with the DatoCMS Web Previews plugin.
+ *
+ * For most use cases, consider using the `<ContentLink />` component instead, which
+ * provides a simpler declarative API.
+ *
+ * @param options - Configuration options for the content link controller
+ * @returns Controller instance and methods for managing visual editing
+ *
+ * @example
+ * ```vue
+ * <script setup>
+ * import { useContentLink } from 'vue-datocms';
+ * import { useRouter, useRoute } from 'vue-router';
+ *
+ * const router = useRouter();
+ * const route = useRoute();
+ *
+ * const { controller, enableClickToEdit, setCurrentPath } = useContentLink({
+ *   onNavigateTo: (path) => router.push(path),
+ * });
+ *
+ * // Enable click-to-edit on mount
+ * onMounted(() => {
+ *   enableClickToEdit({ scrollToNearestTarget: true });
+ * });
+ *
+ * // Sync current path with Web Previews plugin
+ * watch(() => route.path, (newPath) => {
+ *   setCurrentPath(newPath);
+ * });
+ * </script>
+ * ```
+ *
+ * @see https://www.npmjs.com/package/@datocms/content-link
+ */
+declare function useContentLink(options?: UseContentLinkOptions): UseContentLinkResult;
+
+type ContentLinkProps = Omit<UseContentLinkOptions, 'enabled'> & {
+    /** Current pathname to sync with Web Previews plugin */
+    currentPath?: string;
+    /** Enable click-to-edit on mount. Pass true for default behavior or an object with scrollToNearestTarget. If undefined, click-to-edit is disabled. */
+    enableClickToEdit?: true | {
+        scrollToNearestTarget: true;
+    };
+    /** Whether to strip stega encoding from text nodes after stamping. */
+    stripStega?: boolean;
+};
+/**
+ * ContentLink component enables Visual Editing for DatoCMS content.
+ *
+ * This component provides two powerful editing experiences:
+ *
+ * 1. **Standalone website editing**: When viewing your draft content on the website,
+ *    editors can click on any content element to open the DatoCMS editor and modify
+ *    that specific field. This works by detecting stega-encoded metadata in the content
+ *    and creating interactive overlays.
+ *
+ * 2. **Web Previews plugin integration**: When your preview runs inside the Visual Editing
+ *    mode of the DatoCMS Web Previews plugin, this component automatically establishes
+ *    bidirectional communication with the plugin. This enables:
+ *    - Clicking content to instantly open the correct field in the side panel
+ *    - In-plugin navigation: users can navigate to different URLs within Visual mode
+ *      (like a browser navigation bar), and the preview updates accordingly
+ *    - Synchronized state between the preview and the DatoCMS interface
+ *
+ * The component handles client-side routing by:
+ * - Listening to navigation requests from the Web Previews plugin via `onNavigateTo`
+ * - Notifying the plugin when the URL changes via `currentPath` prop
+ *
+ * This integration is completely automatic when running inside the plugin's iframe,
+ * with graceful fallback to opening edit URLs in a new tab when running standalone.
+ *
+ * **Click-to-edit behavior**:
+ * - By default, editors can press and hold Alt/Option key to temporarily enable click-to-edit mode
+ * - Set `enableClickToEdit` prop to `true` to enable it programmatically on mount
+ * - Release the Alt/Option key to disable it again
+ *
+ * @example
+ * Basic usage (no routing):
+ * ```vue
+ * <script setup>
+ * import { ContentLink } from 'vue-datocms';
+ * </script>
+ *
+ * <template>
+ *   <ContentLink />
+ *   <!-- Your content here -->
+ * </template>
+ * ```
+ *
+ * @example
+ * With Vue Router:
+ * ```vue
+ * <script setup>
+ * import { ContentLink } from 'vue-datocms';
+ * import { useRouter, useRoute } from 'vue-router';
+ *
+ * const router = useRouter();
+ * const route = useRoute();
+ * </script>
+ *
+ * <template>
+ *   <ContentLink
+ *     :on-navigate-to="(path) => router.push(path)"
+ *     :current-path="route.path"
+ *   />
+ * </template>
+ * ```
+ *
+ * @example
+ * With Nuxt:
+ * ```vue
+ * <script setup>
+ * import { ContentLink } from 'vue-datocms';
+ * const router = useRouter();
+ * const route = useRoute();
+ * </script>
+ *
+ * <template>
+ *   <ContentLink
+ *     :on-navigate-to="(path) => router.push(path)"
+ *     :current-path="route.path"
+ *   />
+ * </template>
+ * ```
+ *
+ * @example
+ * Enable click-to-edit programmatically:
+ * ```vue
+ * <template>
+ *   <ContentLink :enable-click-to-edit="true" />
+ * </template>
+ * ```
+ *
+ * @see https://www.npmjs.com/package/@datocms/content-link
+ * @see https://www.datocms.com/marketplace/plugins/i/datocms-plugin-web-previews
+ */
+declare const ContentLink: vue.DefineComponent<{
+    /**
+     * Callback when Web Previews plugin requests navigation.
+     * Use this to integrate with your router.
+     *
+     * @example
+     * With Vue Router: `(path) => router.push(path)`
+     * With Nuxt: `(path) => navigateTo(path)`
+     */
+    onNavigateTo: {
+        type: PropType<(path: string) => void>;
+        required: false;
+    };
+    /**
+     * Root element to limit scanning to (instead of document).
+     * Pass a ref to a parent element to limit the scope of content link scanning.
+     */
+    root: {
+        type: PropType<UseContentLinkOptions["root"]>;
+        required: false;
+    };
+    /**
+     * Current pathname to sync with Web Previews plugin.
+     * This keeps the plugin in sync with the current page being previewed.
+     *
+     * @example
+     * With Vue Router: `route.path`
+     * With Nuxt: `route.path`
+     */
+    currentPath: {
+        type: StringConstructor;
+        required: false;
+    };
+    /**
+     * Enable click-to-edit on mount. Pass true for default behavior or an object with scrollToNearestTarget.
+     * If undefined, click-to-edit is disabled and editors can use Alt/Option key for temporary activation.
+     */
+    enableClickToEdit: {
+        type: PropType<true | {
+            scrollToNearestTarget: true;
+        }>;
+        required: false;
+    };
+    /**
+     * Whether to strip stega encoding from text nodes after stamping.
+     */
+    stripStega: {
+        type: BooleanConstructor;
+        required: false;
+    };
+}, () => null, unknown, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.VNodeProps & vue.AllowedComponentProps & vue.ComponentCustomProps, Readonly<vue.ExtractPropTypes<{
+    /**
+     * Callback when Web Previews plugin requests navigation.
+     * Use this to integrate with your router.
+     *
+     * @example
+     * With Vue Router: `(path) => router.push(path)`
+     * With Nuxt: `(path) => navigateTo(path)`
+     */
+    onNavigateTo: {
+        type: PropType<(path: string) => void>;
+        required: false;
+    };
+    /**
+     * Root element to limit scanning to (instead of document).
+     * Pass a ref to a parent element to limit the scope of content link scanning.
+     */
+    root: {
+        type: PropType<UseContentLinkOptions["root"]>;
+        required: false;
+    };
+    /**
+     * Current pathname to sync with Web Previews plugin.
+     * This keeps the plugin in sync with the current page being previewed.
+     *
+     * @example
+     * With Vue Router: `route.path`
+     * With Nuxt: `route.path`
+     */
+    currentPath: {
+        type: StringConstructor;
+        required: false;
+    };
+    /**
+     * Enable click-to-edit on mount. Pass true for default behavior or an object with scrollToNearestTarget.
+     * If undefined, click-to-edit is disabled and editors can use Alt/Option key for temporary activation.
+     */
+    enableClickToEdit: {
+        type: PropType<true | {
+            scrollToNearestTarget: true;
+        }>;
+        required: false;
+    };
+    /**
+     * Whether to strip stega encoding from text nodes after stamping.
+     */
+    stripStega: {
+        type: BooleanConstructor;
+        required: false;
+    };
+}>>, {
+    stripStega: boolean;
+}, {}>;
+declare const DatocmsContentLinkPlugin: {
+    install: (Vue: any) => void;
+};
+
 type Maybe$2<T> = T | null;
 type ResponsiveImageType = {
     /** A base64-encoded thumbnail to offer during image loading */
@@ -471,19 +760,19 @@ type RenderBlockContext<R extends Record$1 = Record$1> = {
 declare const StructuredText: vue.DefineComponent<{
     /** The actual field value you get from DatoCMS **/
     data: {
-        type: PropType<StructuredText$1<CdaStructuredTextRecord, CdaStructuredTextRecord, CdaStructuredTextRecord> | Document<string, string> | Node<string, string> | null | undefined>;
+        type: PropType<StructuredText$1 | Document | Node | null | undefined>;
     };
     /** @deprecated use customNodeRules **/
     customRules: {
-        type: PropType<RenderRule<typeof h, (text: string, _key: string) => AdapterReturn, (children: AdapterReturn[], _key: string) => AdapterReturn>[]>;
+        type: PropType<RenderRule<H, T, F>[]>;
     };
     /** A set of additional rules to convert the document to JSX **/
     customNodeRules: {
-        type: PropType<RenderRule<typeof h, (text: string, _key: string) => AdapterReturn, (children: AdapterReturn[], _key: string) => AdapterReturn>[]>;
+        type: PropType<RenderRule<H, T, F>[]>;
     };
     /** A set of additional rules to convert the document to JSX **/
     customMarkRules: {
-        type: PropType<RenderMarkRule<typeof h, (text: string, _key: string) => AdapterReturn, (children: AdapterReturn[], _key: string) => AdapterReturn>[]>;
+        type: PropType<RenderMarkRule<H, T, F>[]>;
     };
     /** Fuction that converts an 'inlineItem' node into a Vue component **/
     renderInlineRecord: {
@@ -507,32 +796,32 @@ declare const StructuredText: vue.DefineComponent<{
     };
     /** Fuction that converts a simple string text into a Vue component **/
     renderText: {
-        type: PropType<(text: string, _key: string) => AdapterReturn>;
+        type: PropType<T>;
     };
     /** React.createElement-like function to use to convert a node into a Vue component **/
     renderNode: {
-        type: PropType<typeof h>;
+        type: PropType<H>;
     };
     /** Function to use to generate a Vue.Fragment **/
     renderFragment: {
-        type: PropType<(children: AdapterReturn[], _key: string) => AdapterReturn>;
+        type: PropType<F>;
     };
 }, () => RenderResult<typeof h, (text: string, _key: string) => AdapterReturn, (children: AdapterReturn[], _key: string) => AdapterReturn>, unknown, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.VNodeProps & vue.AllowedComponentProps & vue.ComponentCustomProps, Readonly<vue.ExtractPropTypes<{
     /** The actual field value you get from DatoCMS **/
     data: {
-        type: PropType<StructuredText$1<CdaStructuredTextRecord, CdaStructuredTextRecord, CdaStructuredTextRecord> | Document<string, string> | Node<string, string> | null | undefined>;
+        type: PropType<StructuredText$1 | Document | Node | null | undefined>;
     };
     /** @deprecated use customNodeRules **/
     customRules: {
-        type: PropType<RenderRule<typeof h, (text: string, _key: string) => AdapterReturn, (children: AdapterReturn[], _key: string) => AdapterReturn>[]>;
+        type: PropType<RenderRule<H, T, F>[]>;
     };
     /** A set of additional rules to convert the document to JSX **/
     customNodeRules: {
-        type: PropType<RenderRule<typeof h, (text: string, _key: string) => AdapterReturn, (children: AdapterReturn[], _key: string) => AdapterReturn>[]>;
+        type: PropType<RenderRule<H, T, F>[]>;
     };
     /** A set of additional rules to convert the document to JSX **/
     customMarkRules: {
-        type: PropType<RenderMarkRule<typeof h, (text: string, _key: string) => AdapterReturn, (children: AdapterReturn[], _key: string) => AdapterReturn>[]>;
+        type: PropType<RenderMarkRule<H, T, F>[]>;
     };
     /** Fuction that converts an 'inlineItem' node into a Vue component **/
     renderInlineRecord: {
@@ -556,15 +845,15 @@ declare const StructuredText: vue.DefineComponent<{
     };
     /** Fuction that converts a simple string text into a Vue component **/
     renderText: {
-        type: PropType<(text: string, _key: string) => AdapterReturn>;
+        type: PropType<T>;
     };
     /** React.createElement-like function to use to convert a node into a Vue component **/
     renderNode: {
-        type: PropType<typeof h>;
+        type: PropType<H>;
     };
     /** Function to use to generate a Vue.Fragment **/
     renderFragment: {
-        type: PropType<(children: AdapterReturn[], _key: string) => AdapterReturn>;
+        type: PropType<F>;
     };
 }>>, {}, {}>;
 declare const DatocmsStructuredTextPlugin: {
@@ -577,6 +866,8 @@ type Possibly<T> = Maybe$1<T> | undefined;
 type Video = {
     /** Title attribute (`title`) for the video */
     title?: Possibly<string>;
+    /** Alt attribute used for content link integration (passed as data-datocms-content-link-source) */
+    alt?: Possibly<string>;
     /** The height of the video */
     height?: Possibly<number>;
     /** The width of the video */
@@ -597,7 +888,7 @@ declare const toNativeAttrName: (propName: string, propValue: any) => string | u
 declare const toNativeAttrValue: (propValue: any, propName: string) => any;
 declare const VideoPlayer: vue.DefineComponent<{
     _hlsConfig: {
-        type: PropType<Readonly<Partial<hls_js.HlsConfig>> | undefined>;
+        type: PropType<MuxPlayerElement["_hlsConfig"]>;
         required: false;
     };
     accentColor: {
@@ -609,7 +900,7 @@ declare const VideoPlayer: vue.DefineComponent<{
         required: false;
     };
     autoPlay: {
-        type: PropType<string | boolean>;
+        type: PropType<boolean | string>;
         required: false;
     };
     backwardSeekOffset: {
@@ -780,7 +1071,7 @@ declare const VideoPlayer: vue.DefineComponent<{
         required: false;
     };
     renditionOrder: {
-        type: PropType<"desc">;
+        type: PropType<RenditionOrderValue>;
         required: false;
     };
     secondaryColor: {
@@ -837,10 +1128,10 @@ declare const VideoPlayer: vue.DefineComponent<{
         disableCookies: boolean;
         disableTracking: boolean;
         preload: string;
-        style?: (vue.CSSProperties | null) | undefined;
-        title?: (string | null) | undefined;
-        playbackId?: (string | null) | undefined;
-        placeholder?: (string | null) | undefined;
+        style?: vue.CSSProperties | null;
+        title?: string | null;
+        playbackId?: string | null;
+        placeholder?: string | null;
     };
     otherProps: {
         disablePictureInPicture: boolean;
@@ -923,9 +1214,10 @@ declare const VideoPlayer: vue.DefineComponent<{
         onCuePointChange: ((...args: any[]) => any) | undefined;
         onCuePointsChange: ((...args: any[]) => any) | undefined;
     };
+    alt: Possibly<string>;
 }, unknown, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, ("error" | "seeking" | "ended" | "pause" | "play" | "abort" | "canPlay" | "canPlayThrough" | "emptied" | "loadStart" | "loadedData" | "loadedMetadata" | "progress" | "durationChange" | "volumeChange" | "rateChange" | "resize" | "waiting" | "playing" | "timeUpdate" | "seeked" | "stalled" | "suspend" | "cuePointChange" | "cuePointsChange")[], "error" | "seeking" | "ended" | "pause" | "play" | "abort" | "canPlay" | "canPlayThrough" | "emptied" | "loadStart" | "loadedData" | "loadedMetadata" | "progress" | "durationChange" | "volumeChange" | "rateChange" | "resize" | "waiting" | "playing" | "timeUpdate" | "seeked" | "stalled" | "suspend" | "cuePointChange" | "cuePointsChange", vue.VNodeProps & vue.AllowedComponentProps & vue.ComponentCustomProps, Readonly<vue.ExtractPropTypes<{
     _hlsConfig: {
-        type: PropType<Readonly<Partial<hls_js.HlsConfig>> | undefined>;
+        type: PropType<MuxPlayerElement["_hlsConfig"]>;
         required: false;
     };
     accentColor: {
@@ -937,7 +1229,7 @@ declare const VideoPlayer: vue.DefineComponent<{
         required: false;
     };
     autoPlay: {
-        type: PropType<string | boolean>;
+        type: PropType<boolean | string>;
         required: false;
     };
     backwardSeekOffset: {
@@ -1108,7 +1400,7 @@ declare const VideoPlayer: vue.DefineComponent<{
         required: false;
     };
     renditionOrder: {
-        type: PropType<"desc">;
+        type: PropType<RenditionOrderValue>;
         required: false;
     };
     secondaryColor: {
@@ -1352,4 +1644,4 @@ declare const toHead: (...args: ToMetaTagsType[]) => {
     }[];
 };
 
-export { DatocmsImagePlugin, DatocmsNakedImagePlugin, DatocmsStructuredTextPlugin, DatocmsVideoPlayerPlugin, DisabledQueryListenerOptions, EnabledQueryListenerOptions, GenericClient, Image, NakedImage, QueryListenerOptions, RawSearchResult, RenderBlockContext, RenderInlineRecordContext, RenderRecordLinkContext, ResponsiveImageType, SeoMetaTagType, StructuredText, SubscribeToQueryOptions, ToMetaTagsType, UseSiteSearchConfig, UseSiteSearchData, UseSiteSearchResult, Video, VideoPlayer, appendKeyToValidElement, defaultAdapter, isKeyOf, isNil, toHead, toNativeAttrName, toNativeAttrValue, useQuerySubscription, useSiteSearch, useVideoPlayer };
+export { ContentLink, ContentLinkProps, DatocmsContentLinkPlugin, DatocmsImagePlugin, DatocmsNakedImagePlugin, DatocmsStructuredTextPlugin, DatocmsVideoPlayerPlugin, DisabledQueryListenerOptions, EnabledQueryListenerOptions, GenericClient, Image, NakedImage, QueryListenerOptions, RawSearchResult, RenderBlockContext, RenderInlineRecordContext, RenderRecordLinkContext, ResponsiveImageType, SeoMetaTagType, StructuredText, SubscribeToQueryOptions, ToMetaTagsType, UseContentLinkOptions, UseContentLinkResult, UseSiteSearchConfig, UseSiteSearchData, UseSiteSearchResult, Video, VideoPlayer, appendKeyToValidElement, defaultAdapter, isKeyOf, isNil, toHead, toNativeAttrName, toNativeAttrValue, useContentLink, useQuerySubscription, useSiteSearch, useVideoPlayer };