@dotcms/vue 1.5.5 → 1.7.0

package/lib/client/dotcms-client.plugin.d.ts

@@ -0,0 +1,79 @@
+import { App, InjectionKey } from 'vue';
+import { createDotCMSClient } from '@dotcms/client';
+import { DotCMSClientConfig } from '@dotcms/types';
+/**
+ * The dotCMS client instance created by {@link createDotCMSClient}. Use this
+ * type to annotate variables that hold the injected client.
+ */
+export type DotCMSClient = ReturnType<typeof createDotCMSClient>;
+/**
+ * Injection key for the dotCMS client.
+ *
+ * Advanced: exported so a consumer can `inject(DOTCMS_CLIENT)` directly (e.g.
+ * outside a `setup()` where {@link useDotCMSClient} would throw), but prefer
+ * {@link useDotCMSClient}.
+ */
+export declare const DOTCMS_CLIENT: InjectionKey<DotCMSClient>;
+/**
+ * A Vue plugin returned by {@link createDotCMSVue}. Install it with `app.use`.
+ */
+export interface DotCMSVuePlugin {
+    install(app: App): void;
+    /** The client instance the plugin provides. Handy for use outside components. */
+    client: DotCMSClient;
+}
+/**
+ * Creates the dotCMS Vue plugin.
+ *
+ * Builds a single dotCMS client from `config` and provides it to the whole app
+ * so components can retrieve it with {@link useDotCMSClient} — no module-level
+ * singleton to import. This is the Vue analog of Angular's `provideDotCMSClient`.
+ *
+ * The created client is also exposed on the returned object as `.client`, so
+ * non-component code (route loaders, plain modules) can share the same instance.
+ *
+ * @param config - the same configuration accepted by `createDotCMSClient`
+ * @returns a Vue plugin to pass to `app.use()`
+ *
+ * @example
+ * ```ts
+ * import { createApp } from 'vue';
+ * import { createDotCMSVue } from '@dotcms/vue';
+ * import App from './App.vue';
+ *
+ * const app = createApp(App);
+ *
+ * app.use(
+ *   createDotCMSVue({
+ *     dotcmsUrl: 'https://demo.dotcms.com',
+ *     authToken: 'your-auth-token',
+ *     siteId: 'your-site-id',
+ *     requestOptions: {
+ *       // UVE needs fresh data so in-context edits are reflected immediately.
+ *       cache: 'no-cache'
+ *     }
+ *   })
+ * );
+ *
+ * app.mount('#app');
+ * ```
+ */
+export declare function createDotCMSVue(config: DotCMSClientConfig): DotCMSVuePlugin;
+/**
+ * Retrieves the dotCMS client provided by {@link createDotCMSVue}.
+ *
+ * Must be called from a component `setup` (or another composable). Throws if the
+ * plugin was not installed with `app.use(createDotCMSVue(...))`, so a missing
+ * provider fails loudly instead of returning `undefined`.
+ *
+ * @returns the dotCMS client instance
+ *
+ * @example
+ * ```ts
+ * import { useDotCMSClient } from '@dotcms/vue';
+ *
+ * const client = useDotCMSClient();
+ * const { pageAsset } = await client.page.get({ path: '/' });
+ * ```
+ */
+export declare function useDotCMSClient(): DotCMSClient;

package/lib/components/DotCMSLayoutBody/types.d.ts

@@ -1,5 +1,13 @@
 import { DotCMSPageAsset, DotCMSPageRendererMode } from '@dotcms/types';
 import { Component } from 'vue';
+/**
+ * Prefix for the per-contentlet named slots of {@link DotCMSLayoutBody}. A slot
+ * named `contentlet-<identifier>` overrides the mapped component for the
+ * contentlet with that identifier.
+ *
+ * @example `<template #contentlet-abc123>…</template>` targets identifier `abc123`.
+ */
+export declare const CONTENTLET_SLOT_PREFIX = "contentlet-";
 /**
  * Props for {@link DotCMSLayoutBody}.
  */

package/lib/composables/useDotCMSShowWhen.d.ts

@@ -1,11 +1,13 @@
-import { Ref } from 'vue';
+import { ComputedRef, MaybeRefOrGetter } from 'vue';
 import { UVE_MODE } from '@dotcms/types';
 /**
  * Composable that reports whether the current UVE mode matches the given mode.
  *
  * Useful for conditionally rendering content based on the editor mode (EDIT,
  * PREVIEW, LIVE). It resolves after mount (returns `false` during SSR), matching
- * the React SDK's `useDotCMSShowWhen` behavior.
+ * the React SDK's `useDotCMSShowWhen` behavior. The `when` argument may be a
+ * plain value, a `ref`, or a getter — a reactive value is re-evaluated when it
+ * changes.
  *
  * @example
  * ```ts
@@ -13,6 +15,6 @@ import { UVE_MODE } from '@dotcms/types';
  * ```
  *
  * @param when the UVE mode to check against
- * @returns a readonly ref that is `true` when the current UVE mode matches
+ * @returns a readonly computed that is `true` when the current UVE mode matches
  */
-export declare function useDotCMSShowWhen(when: UVE_MODE): Readonly<Ref<boolean>>;
+export declare function useDotCMSShowWhen(when: MaybeRefOrGetter<UVE_MODE>): Readonly<ComputedRef<boolean>>;

package/lib/composables/useEditableDotCMSPage.d.ts

@@ -1,4 +1,4 @@
-import { Ref } from 'vue';
+import { MaybeRefOrGetter, Ref } from 'vue';
 import { DotCMSComposedPageResponse, DotCMSExtendedPageResponse } from '@dotcms/types';
 /**
  * Composable to manage the editable state of a dotCMS page inside the Universal
@@ -28,7 +28,10 @@ import { DotCMSComposedPageResponse, DotCMSExtendedPageResponse } from '@dotcms/
  * // page.value.pageAsset — reactive; re-renders on UVE content changes.
  * ```
  *
- * @param pageResponse the initial page response from `client.page.get()`
+ * @param pageResponse the page response from `client.page.get()`. May be a plain
+ * value, a `ref`, or a getter — when it's reactive, the composable re-initializes
+ * the UVE for the new page (e.g. on client-side route changes) so no manual
+ * component remount is needed.
  * @returns a reactive ref holding the (possibly live-updating) page response
  */
-export declare function useEditableDotCMSPage<T extends DotCMSExtendedPageResponse>(pageResponse: DotCMSComposedPageResponse<T>): Ref<DotCMSComposedPageResponse<T>>;
+export declare function useEditableDotCMSPage<T extends DotCMSExtendedPageResponse>(pageResponse: MaybeRefOrGetter<DotCMSComposedPageResponse<T>>): Ref<DotCMSComposedPageResponse<T>>;

package/lib/contexts/dotcms-page.context.d.ts

@@ -1,13 +1,13 @@
-import { Component, ComputedRef, InjectionKey } from 'vue';
+import { Component, ComputedRef, InjectionKey, Slot } from 'vue';
 import { DotCMSPageAsset, DotCMSPageRendererMode } from '@dotcms/types';
 /**
  * The value carried by the dotCMS page context.
  *
  * This is the Vue analog of the React SDK's `DotCMSPageContext`. It is provided
- * once by {@link DotCMSLayoutBody} and consumed by the internal layout tree
- * (Container, Contentlet) as well as the dev-mode composable.
- *
- * @internal
+ * once by {@link DotCMSLayoutBody} and consumed by the layout tree (Container,
+ * Contentlet). It is also part of the public API: a custom content-type
+ * component rendered deep in the tree can read it via {@link useDotCMSPageContext}
+ * to access the page asset without prop drilling. This shape is stable.
  */
 export interface DotCMSPageContextValue {
     /** The dotCMS page asset containing the layout and containers. */
@@ -31,6 +31,15 @@ export interface DotCMSPageContextValue {
      * single `dotcms:analytics:ready` listener) and shared with the tree.
      */
     isAnalyticsActive: boolean;
+    /**
+     * Named slots passed to {@link DotCMSLayoutBody}, keyed by contentlet
+     * identifier (the `contentlet-<identifier>` slot name, with the prefix
+     * stripped). When a contentlet has a matching slot, that slot content is
+     * rendered instead of the mapped component — the Vue analog of the React
+     * SDK's `slots` prop. Empty (or omitted) when no per-contentlet slots were
+     * provided; {@link DotCMSLayoutBody} always sets it.
+     */
+    slots?: Record<string, Slot>;
 }
 /**
  * Injection key for the dotCMS page context.
@@ -39,23 +48,27 @@ export interface DotCMSPageContextValue {
  * asset arriving via `uve-set-page-data`) propagate to every consumer that reads
  * `ctx.value` — the whole layout tree re-renders reactively.
  *
- * @internal
+ * Advanced: exported so consumers can `inject` directly, but prefer
+ * {@link useDotCMSPageContext}.
  */
 export declare const DOTCMS_PAGE_CONTEXT: InjectionKey<ComputedRef<DotCMSPageContextValue>>;
 /**
  * Provides the dotCMS page context to descendant components.
  *
- * @internal
+ * Advanced: {@link DotCMSLayoutBody} already provides this for the rendered tree,
+ * so most applications never call it. Exposed for consumers that render the
+ * layout tree themselves.
+ *
  * @param value a computed producing the current context value
  */
 export declare function provideDotCMSPageContext(value: ComputedRef<DotCMSPageContextValue>): void;
 /**
  * Injects the dotCMS page context as a reactive `ComputedRef`.
  *
- * Falls back to an empty context when used outside of a {@link DotCMSLayoutBody},
- * mirroring the default value the React context is created with.
+ * Public: use this from a custom content-type component to read the current
+ * `pageAsset`, renderer `mode`, or editor state without prop drilling. Falls back
+ * to an empty context when used outside of a {@link DotCMSLayoutBody}.
  *
- * @internal
  * @returns the current page context value as a computed ref
  */
 export declare function useDotCMSPageContext(): ComputedRef<DotCMSPageContextValue>;

package/lib/utils/imageLoader.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Options for a single {@link DotCMSImageLoader} call.
+ */
+export interface DotCMSImageLoaderOptions {
+    /** Target width in pixels. Requests a resized image from the dotCMS image API. */
+    width?: number;
+    /**
+     * JPEG quality (1-100).
+     * @default 50
+     */
+    quality?: number;
+    /**
+     * Language id for the asset.
+     * @default '1'
+     */
+    languageId?: string;
+}
+/**
+ * A function that turns a dotCMS asset identifier (or path) into an image URL.
+ * Returned by {@link createDotCMSImageLoader}.
+ */
+export type DotCMSImageLoader = (src: string, options?: DotCMSImageLoaderOptions) => string;
+/**
+ * Creates a dotCMS image URL builder.
+ *
+ * dotCMS serves images through its image API (the `/dA/` route), which handles
+ * on-the-fly resizing and optimization. This is the Vue analog of Angular's
+ * `provideDotCMSImageLoader`: Angular wires the same URL math into its
+ * `IMAGE_LOADER` token, while Vue has no such token, so this returns a plain
+ * function you call from a template.
+ *
+ * Absolute URLs (already `http(s)://…`) are returned unchanged, so mixing dotCMS
+ * assets with external/stock imagery just works.
+ *
+ * @param dotcmsUrl - Base URL of the dotCMS instance. When omitted (empty), URLs
+ *   are site-relative (`/dA/…`), which is what you want behind a dev proxy.
+ * @returns a loader function `(src, options?) => url`
+ * @throws if `dotcmsUrl` is a non-empty, invalid URL
+ *
+ * @example
+ * ```ts
+ * import { createDotCMSImageLoader } from '@dotcms/vue';
+ *
+ * // Absolute (production): points at the dotCMS host.
+ * const image = createDotCMSImageLoader(import.meta.env.VITE_DOTCMS_HOST);
+ * image(contentlet.inode, { width: 800 });
+ * // → https://demo.dotcms.com/dA/<inode>/800w/50q?language_id=1
+ *
+ * // Relative (dev proxy): omit the host so the Vite proxy handles /dA.
+ * const proxied = createDotCMSImageLoader();
+ * proxied(contentlet.inode, { width: 800 }); // → /dA/<inode>/800w/50q?language_id=1
+ * ```
+ */
+export declare function createDotCMSImageLoader(dotcmsUrl?: string): DotCMSImageLoader;

package/package.json

@@ -1,47 +1,47 @@
 {
-    "name": "@dotcms/vue",
-    "version": "1.5.5",
-    "peerDependencies": {
-        "vue": ">=3.4"
-    },
-    "dependencies": {
-        "@dotcms/uve": "latest",
-        "@dotcms/client": "latest",
-        "@tinymce/tinymce-vue": "^6.1.0"
-    },
-    "devDependencies": {
-        "@dotcms/types": "latest"
-    },
-    "description": "Official Vue components library to render a dotCMS page.",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/dotCMS/core.git#main"
-    },
-    "keywords": [
-        "dotCMS",
-        "CMS",
-        "Content Management",
-        "API Client",
-        "REST API",
-        "Vue",
-        "Vue 3",
-        "Components"
-    ],
-    "type": "module",
-    "main": "./index.js",
-    "module": "./index.js",
-    "types": "./index.d.ts",
-    "exports": {
-        "./package.json": "./package.json",
-        ".": {
-            "types": "./index.d.ts",
-            "import": "./index.js"
-        }
-    },
-    "author": "dotcms <dev@dotcms.com>",
-    "license": "MIT",
-    "bugs": {
-        "url": "https://github.com/dotCMS/core/issues"
-    },
-    "homepage": "https://github.com/dotCMS/core/tree/main/core-web/libs/sdk/vue/README.md"
+  "name": "@dotcms/vue",
+  "version": "1.7.0",
+  "peerDependencies": {
+    "vue": ">=3.4"
+  },
+  "dependencies": {
+    "@dotcms/uve": "latest",
+    "@dotcms/client": "latest",
+    "@tinymce/tinymce-vue": "^6.1.0"
+  },
+  "devDependencies": {
+    "@dotcms/types": "latest"
+  },
+  "description": "Official Vue components library to render a dotCMS page.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotCMS/core.git#main"
+  },
+  "keywords": [
+    "dotCMS",
+    "CMS",
+    "Content Management",
+    "API Client",
+    "REST API",
+    "Vue",
+    "Vue 3",
+    "Components"
+  ],
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "author": "dotcms <dev@dotcms.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/dotCMS/core/issues"
+  },
+  "homepage": "https://github.com/dotCMS/core/tree/main/core-web/libs/sdk/vue/README.md"
 }