@prismicio/vue 3.0.0-alpha.3 → 3.0.0-beta.0

package/src/types.ts

@@ -11,7 +11,6 @@ import type {
 	asHTML,
 	asLink,
 	asDate,
-	documentAsLink,
 	documentToLinkField,
 	HTMLFunctionSerializer,
 	HTMLMapSerializer,
@@ -26,6 +25,7 @@ import type { RouterLink } from "vue-router";
 
 import type {
 	SliceComponentProps,
+	SliceComponentType,
 	TODOSliceComponent,
 } from "./components/SliceZone";
 
@@ -45,23 +45,29 @@ type PrismicPluginComponentsOptions = {
 	linkBlankTargetRelAttribute?: string;
 
 	/**
-	 * An HTML tag name, a component, or a functional component used to render internal links.
-	 *
-	 * @remarks HTML tag names will be rendered using the anchor tag interface (`href`, `target`, and `rel` attributes).
-	 *
-	 * @remarks Components will be rendered using Vue Router {@link RouterLink} interface (`to` props).
-	 *
+	 * An HTML tag name, a component, or a functional component used to render
+	 * internal links.
+	 *
+	 * @remarks
+	 * HTML tag names will be rendered using the anchor tag interface (`href`,
+	 * `target`, and `rel` attributes).
+	 * @remarks
+	 * Components will be rendered using Vue Router {@link RouterLink} interface
+	 * (`to` props).
 	 * @defaultValue {@link RouterLink}
 	 */
 	linkInternalComponent?: string | ConcreteComponent;
 
 	/**
-	 * An HTML tag name, a component, or a functional component used to render external links.
-	 *
-	 * @remarks HTML tag names will be rendered using the anchor tag interface (`href`, `target`, and `rel` attributes).
-	 *
-	 * @remarks Components will be rendered using Vue Router {@link RouterLink} interface (`to` props).
-	 *
+	 * An HTML tag name, a component, or a functional component used to render
+	 * external links.
+	 *
+	 * @remarks
+	 * HTML tag names will be rendered using the anchor tag interface (`href`,
+	 * `target`, and `rel` attributes).
+	 * @remarks
+	 * Components will be rendered using Vue Router {@link RouterLink} interface
+	 * (`to` props).
 	 * @defaultValue `"a"`
 	 */
 	linkExternalComponent?: string | ConcreteComponent;
@@ -69,20 +75,23 @@ type PrismicPluginComponentsOptions = {
 	/**
 	 * An HTML tag name, a component, or a functional component used to render images.
 	 *
-	 * @remarks HTML tag names and components will be rendered using the `img` tag interface (`src` and `alt` attribute). Components will also receive an additional `copyright` props.
-	 *
+	 * @remarks
+	 * HTML tag names and components will be rendered using the `img` tag
+	 * interface (`src` and `alt` attribute). Components will also receive an
+	 * additional `copyright` props.
 	 * @defaultValue `"img"`
 	 */
 	imageComponent?: string | ConcreteComponent;
 
 	/**
-	 * A component or a functional component rendered if a component mapping from the `components` prop cannot be found.
-	 *
-	 * @remarks Components will be rendered using the {@link SliceComponentProps} interface.
+	 * A component or a functional component rendered if a component mapping from
+	 * the `components` prop cannot be found.
 	 *
+	 * @remarks
+	 * Components will be rendered using the {@link SliceComponentProps} interface.
 	 * @defaultValue `null` when `process.env.NODE_ENV === "production"` else {@link TODOSliceComponent}
 	 */
-	sliceZoneDefaultComponent?: string | ConcreteComponent;
+	sliceZoneDefaultComponent?: SliceComponentType;
 };
 
 /**
@@ -90,7 +99,8 @@ type PrismicPluginComponentsOptions = {
  */
 type PrismicPluginOptionsBase = {
 	/**
-	 * An optional link resolver function used to resolve links to Prismic documents when not using the route resolver parameter with `@prismicio/client`.
+	 * An optional link resolver function used to resolve links to Prismic
+	 * documents when not using the route resolver parameter with `@prismicio/client`.
 	 *
 	 * @see Link resolver documentation {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver#link-resolver}
 	 */
@@ -125,10 +135,13 @@ type PrismicPluginOptionsBase = {
  */
 type PrismicPluginOptionsWithClient = PrismicPluginOptionsBase & {
 	/**
-	 * A `@prismicio/client` instance used to fetch content from a Prismic repository to configure the plugin with.
-	 *
-	 * @remarks The client will be used by `@prismicio/vue` composables, such as {@link usePrismicDocuments} and exposed through `this.$prismic.client` and `usePrismic().client`.
+	 * A `@prismicio/client` instance used to fetch content from a Prismic
+	 * repository to configure the plugin with.
 	 *
+	 * @remarks
+	 * The client will be used by `@prismicio/vue` composables, such as
+	 * {@link usePrismicDocuments} and exposed through `this.$prismic.client` and
+	 * `usePrismic().client`.
 	 * @see Prismic client documentation {@link https://prismic.io/docs/technologies/javascript}
 	 */
 	client: Client;
@@ -155,62 +168,57 @@ type PrismicPluginOptionsWithClient = PrismicPluginOptionsBase & {
  */
 type PrismicPluginOptionsWithEndpoint = PrismicPluginOptionsBase & {
 	/**
-	 * A Prismic repository endpoint to init the plugin's `@prismicio/client` instance used to fetch content from a Prismic repository with.
-	 *
-	 * @remarks Said client will be used by `@prismicio/vue` composables, such as {@link usePrismicDocuments} and exposed through `this.$prismic.client` and `usePrismic().client`.
+	 * A Prismic repository endpoint to init the plugin's `@prismicio/client`
+	 * instance used to fetch content from a Prismic repository with.
 	 *
-	 * @see Prismic client documentation {@link https://prismic.io/docs/technologies/javascript}
+	 * @remarks
+	 * Said client will be used by `@prismicio/vue` composables, such as
+	 * {@link usePrismicDocuments} and exposed through `this.$prismic.client` and
+	 * `usePrismic().client`.
+	 * @example A repository ID:
 	 *
-	 * @example
-	 * A repository ID:
+	 *     "my-repo";
 	 *
-	 * ```
-	 * "my-repo"
-	 * ```
+	 * @example A full repository endpoint:
 	 *
-	 * @example
-	 * A full repository endpoint:
+	 *     "https://my-repo.cdn.prismic.io/api/v2";
 	 *
-	 * ```
-	 * "https://my-repo.cdn.prismic.io/api/v2"
-	 * ```
+	 * @see Prismic client documentation {@link https://prismic.io/docs/technologies/javascript}
 	 */
 	endpoint: string;
 
 	/**
 	 * An optional object to configure `@prismicio/client` instance further.
 	 *
-	 * @see Prismic client documentation {@link https://prismic.io/docs/technologies/javascript}
-	 * @see Route resolver documentation {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver#route-resolver}
-	 *
-	 * @example
-	 * Accessing a private private repository:
+	 * @example Accessing a private private repository:
 	 *
-	 * ```
+	 * ```javascript
 	 * {
-	 *   accessToken: "abc",
+	 * 	"accessToken": "abc"
 	 * }
 	 * ```
 	 *
-	 * @example
-	 * Using a route resolver:
+	 * @example Using a route resolver:
 	 *
-	 * ```
+	 * ```javascript
 	 * {
-	 *   defaultParams: {
-	 *     routes: [
-	 *       {
-	 *         type: "page",
-	 *         path: "/:uid"
-	 *       },
-	 *       {
-	 *         type: "post",
-	 *         path: "/blog/:uid"
-	 *       }
-	 *     ]
-	 *   }
+	 * 	"defaultParams": {
+	 * 		"routes": [
+	 * 			{
+	 * 				"type": "page",
+	 * 				"path": "/:uid"
+	 * 			},
+	 * 			{
+	 * 				"type": "post",
+	 * 				"path": "/blog/:uid"
+	 * 			}
+	 * 		]
+	 * 	}
 	 * }
 	 * ```
+	 *
+	 * @see Prismic client documentation {@link https://prismic.io/docs/technologies/javascript}
+	 * @see Route resolver documentation {@link https://prismic.io/docs/core-concepts/link-resolver-route-resolver#route-resolver}
 	 */
 	clientConfig?: ClientConfig;
 
@@ -233,46 +241,60 @@ export type PrismicPluginOptions =
 	| PrismicPluginOptionsWithEndpoint;
 
 /**
- * `@prismicio/client` related methods and properties exposed by `@prismicio/vue` plugin and accessible through `this.$prismic` and `usePrismic()`.
+ * `@prismicio/client` related methods and properties exposed by
+ * `@prismicio/vue` plugin and accessible through `this.$prismic` and `usePrismic()`.
  */
 export type PrismicPluginClient = {
-	/** A `@prismicio/client` instance. */
+	/**
+	 * A `@prismicio/client` instance.
+	 */
 	client: Client;
 
-	/** Query predicates from `@prismicio/client`. */
+	/**
+	 * Query predicates from `@prismicio/client`.
+	 */
 	predicate: typeof predicate;
 
-	/** Prismic cookies from `@prismicio/client`. */
+	/**
+	 * Prismic cookies from `@prismicio/client`.
+	 */
 	cookie: typeof cookie;
 };
 
 /**
- * `@prismicio/helpers` related methods exposed by `@prismicio/vue` plugin and accessible through `this.$prismic` and `usePrismic()`.
+ * `@prismicio/helpers` related methods exposed by `@prismicio/vue` plugin and
+ * accessible through `this.$prismic` and `usePrismic()`.
  */
 export type PrismicPluginHelpers = {
 	/**
-	 * Serializes a rich text or title field to a plain text string. This is `@prismicio/helpers` {@link asText} function.
+	 * Serializes a rich text or title field to a plain text string. This is
+	 * `@prismicio/helpers` {@link asText} function.
 	 *
 	 * @see Templating rich text and title fields {@link https://prismic.io/docs/technologies/vue-template-content#rich-text-and-titles}
 	 */
 	asText: typeof asText;
 
 	/**
-	 * Serializes a rich text or title field to an HTML string. This is `@prismicio/helpers` {@link asHTML} function.
-	 *
-	 * @remarks If no `linkResolver` is provided the function will use the one provided to the plugin at {@link PrismicPluginOptions.linkResolver} if available.
-	 *
-	 * @remarks If no `htmlSerializer` is provided the function will use the one provided to the plugin at {@link PrismicPluginOptions.htmlSerializer} if available.
-	 *
+	 * Serializes a rich text or title field to an HTML string. This is
+	 * `@prismicio/helpers` {@link asHTML} function.
+	 *
+	 * @remarks
+	 * If no `linkResolver` is provided the function will use the one provided to
+	 * the plugin at {@link PrismicPluginOptions.linkResolver} if available.
+	 * @remarks
+	 * If no `htmlSerializer` is provided the function will use the one provided
+	 * to the plugin at {@link PrismicPluginOptions.htmlSerializer} if available.
 	 * @see Templating rich text and title fields {@link https://prismic.io/docs/technologies/vue-template-content#rich-text-and-titles}
 	 */
 	asHTML: typeof asHTML;
 
 	/**
-	 * Resolves any type of link field to a URL. This is `@prismicio/helpers` {@link asLink} function.
-	 *
-	 * @remarks If no `linkResolver` is provided the function will use the one provided to the plugin at {@link PrismicPluginOptions.linkResolver} if available.
+	 * Resolves any type of link field or document to a URL. This is
+	 * `@prismicio/helpers` {@link asLink} function.
 	 *
+	 * @remarks
+	 * If no `linkResolver` is provided the function will use the one provided to
+	 * the plugin at {@link PrismicPluginOptions.linkResolver} if available.
 	 * @see Templating link fields {@link https://prismic.io/docs/technologies/vue-template-content#links-and-content-relationships}
 	 */
 	asLink: (
@@ -281,30 +303,23 @@ export type PrismicPluginHelpers = {
 	) => string | null;
 
 	/**
-	 * Transforms a date or timestamp field into a JavaScript Date object. This is `@prismicio/helpers` {@link asDate} function.
+	 * Transforms a date or timestamp field into a JavaScript Date object. This is
+	 * `@prismicio/helpers` {@link asDate} function.
 	 */
 	asDate: typeof asDate;
 
 	/**
-	 * Converts a document into a link field. This is `@prismicio/helpers` {@link documentToLinkField} function.
-	 */
-	documentToLinkField: typeof documentToLinkField;
-
-	/**
-	 * Resolves a document to a URL. This is `@prismicio/helpers` {@link documentAsLink} function.
-	 *
-	 * @remarks If no `linkResolver` is provided the function will use the one provided to the plugin at {@link PrismicPluginOptions.linkResolver} if available.
+	 * Converts a document into a link field. This is `@prismicio/helpers`
+	 * {@link documentToLinkField} function.
 	 *
-	 * @see Templating link fields {@link https://prismic.io/docs/technologies/vue-template-content#links-and-content-relationships}
+	 * @internal
 	 */
-	documentAsLink: (
-		prismicDocument: Parameters<typeof documentAsLink>[0],
-		linkResolver?: LinkResolverFunction,
-	) => string | null;
+	documentToLinkField: typeof documentToLinkField;
 };
 
 /**
- * Methods and properties exposed by `@prismicio/vue` plugin and accessible through `this.$prismic` and `usePrismic()`.
+ * Methods and properties exposed by `@prismicio/vue` plugin and accessible
+ * through `this.$prismic` and `usePrismic()`.
  */
 export type PrismicPlugin = {
 	/**
@@ -327,24 +342,31 @@ export type PrismicPlugin = {
  * States of a `@prismicio/client` composable.
  */
 export const enum PrismicClientComposableState {
-	/** The composable has not started fetching. */
+	/**
+	 * The composable has not started fetching.
+	 */
 	Idle = "idle",
 
-	/** The composable is fetching data. */
+	/**
+	 * The composable is fetching data.
+	 */
 	Pending = "pending",
 
-	/** The composable sucessfully fetched data. */
+	/**
+	 * The composable sucessfully fetched data.
+	 */
 	Success = "success",
 
-	/** The composable failed to fetch data. */
+	/**
+	 * The composable failed to fetch data.
+	 */
 	Error = "error",
 }
 
 // Helpers
 
 /**
- * Type to transform a static object into one that allows passing Refs as
- * values.
+ * Type to transform a static object into one that allows passing Refs as values.
  *
  * @internal
  */
@@ -353,8 +375,7 @@ export type VueUseOptions<T> = {
 };
 
 /**
- * Type to transform a static tuple into one that allows passing Refs as
- * values.
+ * Type to transform a static tuple into one that allows passing Refs as values.
  *
  * @internal
  */

package/src/usePrismic.ts

@@ -6,22 +6,21 @@ import { PrismicPlugin } from "./types";
 /**
  * Accesses `@prismicio/vue` plugin interface.
  *
- * @returns The interface {@link PrismicPlugin}
- *
- * @example
- * With the composition API:
+ * @example With the composition API:
  *
- * ```
+ * ```javascript
  * import { usePrismic } from "@prismicio/vue";
  *
  * export default {
- *   setup() {
- *     const prismic = usePrismic();
+ * 	setup() {
+ * 		const prismic = usePrismic();
  *
- *     return {}
- *   },
+ * 		return {};
+ * 	},
  * };
  * ```
+ *
+ * @returns The interface {@link PrismicPlugin}
  */
 export const usePrismic = (): PrismicPlugin => {
 	return inject(prismicKey, { options: { endpoint: "" } } as PrismicPlugin);

package/src/useStatefulPrismicClientMethod.ts

@@ -15,23 +15,29 @@ type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type ClientMethodLike = (...args: any[]) => Promise<any> | any;
 type ClientMethods = typeof Client.prototype;
-type ClientError = PrismicError | ParsingError | ForbiddenError;
+type ClientError = PrismicError<unknown> | ParsingError | ForbiddenError;
 
 // Interfaces
 
-/** @internal */
+/**
+ * @internal
+ */
 export type ClientMethodParameters<TMethodName extends keyof ClientMethods> =
 	ClientMethods[TMethodName] extends ClientMethodLike
 		? VueUseParameters<Parameters<ClientMethods[TMethodName]>>
 		: never;
 
-/** @internal */
+/**
+ * @internal
+ */
 export type ClientMethodReturnType<TMethodName extends keyof ClientMethods> =
 	ClientMethods[TMethodName] extends ClientMethodLike
 		? ReturnType<ClientMethods[TMethodName]>
 		: never;
 
-/** @internal */
+/**
+ * @internal
+ */
 export type ComposableOnlyParameters = {
 	client?: Ref<Client> | Client;
 };
@@ -42,16 +48,24 @@ export type ComposableOnlyParameters = {
  * @typeParam TData - The expected format of the `data` property of the returned object
  */
 export type ClientComposableReturnType<TData = unknown> = {
-	/** The current state of the composable's client method call. */
+	/**
+	 * The current state of the composable's client method call.
+	 */
 	state: Ref<PrismicClientComposableState>;
 
-	/** Data returned by the client. */
+	/**
+	 * Data returned by the client.
+	 */
 	data: Ref<TData | null>;
 
-	/** Error returned by the composable's client method call if in an errror state. */
-	error: Ref<ClientError | null>;
+	/**
+	 * Error returned by the composable's client method call if in an errror state.
+	 */
+	error: Ref<ClientError | Error | null>;
 
-	/** Perform the composable's client method call again. */
+	/**
+	 * Perform the composable's client method call again.
+	 */
 	refresh: () => Promise<void>;
 };
 
@@ -70,17 +84,17 @@ const isParams = (
 };
 
 /**
- * A low level Vue composable that uses provided method name on plugin or provided client with given arguments. The composable has its own internal state manager to report async status, such as pending or error statuses.
- *
- * @param method - The `@prismicio/client` method name to use
- * @param args - The arguments to use with requested method
- *
- * @returns The composable payload {@link ClientComposableReturnType}
+ * A low level Vue composable that uses provided method name on plugin or
+ * provided client with given arguments. The composable has its own internal
+ * state manager to report async status, such as pending or error statuses.
  *
  * @typeParam TClientMethodName - A method name from `@prismicio/client`
  * @typeParam TClientMethodArguments - The method expected arguments
  * @typeParam TClientMethodReturnType - The method expected return type
+ * @param method - The `@prismicio/client` method name to use
+ * @param args - The arguments to use with requested method
  *
+ * @returns The composable payload {@link ClientComposableReturnType}
  * @internal
  */
 export const useStatefulPrismicClientMethod = <
@@ -99,7 +113,7 @@ export const useStatefulPrismicClientMethod = <
 		PrismicClientComposableState.Idle,
 	);
 	const data = shallowRef<TClientMethodReturnType | null>(null);
-	const error = ref<ClientError | null>(null);
+	const error = ref<ClientError | Error | null>(null);
 	const refresh = async (): Promise<void> => {
 		const lastArg = unref(args[args.length - 1]);
 		const { client: explicitClient, ...params } = isParams(lastArg)
@@ -120,7 +134,7 @@ export const useStatefulPrismicClientMethod = <
 			state.value = PrismicClientComposableState.Success;
 		} catch (err) {
 			state.value = PrismicClientComposableState.Error;
-			error.value = err;
+			error.value = err as ClientError | Error;
 		}
 	};