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

package/src/components/SliceZone.ts

@@ -20,9 +20,11 @@ import { __PRODUCTION__ } from "../lib/__PRODUCTION__";
 import { usePrismic } from "../usePrismic";
 
 /**
- * The minimum required properties to represent a Prismic Slice for the `<SliceZone />` component.
+ * The minimum required properties to represent a Prismic Slice for the
+ * `<SliceZone />` component.
  *
- * If using Prismic's REST API, use the `Slice` export from `@prismicio/types` for a full interface.
+ * If using Prismic's REST API, use the `Slice` export from `@prismicio/types`
+ * for a full interface.
  *
  * @typeParam TSliceType - Type name of the Slice
  */
@@ -34,44 +36,57 @@ export type SliceLike<TSliceType extends string = string> = Pick<
 /**
  * A looser version of the `SliceZone` type from `@prismicio/types` using `SliceLike`.
  *
- * If using Prismic's REST API, use the `SliceZone` export from `@prismicio/types` for the full type.
+ * If using Prismic's REST API, use the `SliceZone` export from
+ * `@prismicio/types` for the full type.
  *
  * @typeParam TSlice - The type(s) of slices in the Slice Zone
  */
 export type SliceZoneLike<TSlice extends SliceLike> = readonly TSlice[];
 
 /**
- * Vue props for a component rendering content from a Prismic Slice using the `<SliceZone />` component.
+ * Vue props for a component rendering content from a Prismic Slice using the
+ * `<SliceZone />` component.
  *
  * @typeParam TSlice - The type(s) of slices in the Slice Zone
- * @typeParam TContext - Arbitrary data passed to `<SliceZone />` and made available to all Slice components
+ * @typeParam TContext - Arbitrary data passed to `<SliceZone />` and made
+ *   available to all Slice components
  */
 export type SliceComponentProps<
 	TSlice extends SliceLike = SliceLike,
 	TContext = unknown,
 > = {
-	/** Slice data for this component. */
+	/**
+	 * Slice data for this component.
+	 */
 	slice: TSlice;
 
-	/** The index of the Slice in the Slice Zone. */
+	/**
+	 * The index of the Slice in the Slice Zone.
+	 */
 	index: number;
 
-	/** All Slices from the Slice Zone to which the Slice belongs. */
+	/**
+	 * All Slices from the Slice Zone to which the Slice belongs.
+	 */
 	// TODO: We have to keep this list of Slices general due to circular
 	// reference limtiations. If we had another generic to determine the full
 	// union of Slice types, it would include TSlice. This causes TypeScript to
 	// throw a compilation error.
 	slices: SliceZoneLike<SliceLike>;
 
-	/** Arbitrary data passed to `<SliceZone />` and made available to all Slice components. */
+	/**
+	 * Arbitrary data passed to `<SliceZone />` and made available to all Slice components.
+	 */
 	context: TContext;
 };
 
 /**
- * Native Vue props for a component rendering content from a Prismic Slice using the `<SliceZone />` component.
+ * Native Vue props for a component rendering content from a Prismic Slice using
+ * the `<SliceZone />` component.
  *
  * @typeParam TSlice - The type(s) of slices in the Slice Zone
- * @typeParam TContext - Arbitrary data passed to `<SliceZone />` and made available to all Slice components
+ * @typeParam TContext - Arbitrary data passed to `<SliceZone />` and made
+ *   available to all Slice components
  */
 export type DefineComponentSliceComponentProps<
 	TSlice extends SliceLike = SliceLike,
@@ -96,36 +111,38 @@ export type DefineComponentSliceComponentProps<
 };
 
 /**
- * Gets native Vue props for a component rendering content from a Prismic Slice using the `<SliceZone />` component. Props are: `["slice", "index", "slices", "context"]`
+ * Gets native Vue props for a component rendering content from a Prismic Slice
+ * using the `<SliceZone />` component. Props are: `["slice", "index", "slices",
+ * "context"]`
  *
- * @param propsHint - An optional array of prop names used for the sole purpose of having a visual hint of which props are made available to the slice, this parameters doesn't have any effect
- *
- * @returns Props object to use with {@link defineComponent}
+ * @example Defining a new slice component:
  *
- * @typeParam TSlice - The type(s) of slices in the Slice Zone
- * @typeParam TContext - Arbitrary data passed to `<SliceZone />` and made available to all Slice components
- *
- * @example
- * Defining a new slice component:
- *
- * ```
+ * ```javascript
  * import { getSliceComponentProps } from "@prismicio/vue";
  *
  * export default {
- *   props: getSliceComponentProps(),
+ * 	props: getSliceComponentProps(),
  * };
  * ```
  *
- * @example
- * Defining a new slice component with visual hint:
+ * @example Defining a new slice component with visual hint:
  *
- * ```
+ * ```javascript
  * import { getSliceComponentProps } from "@prismicio/vue";
  *
  * export default {
- *   props: getSliceComponentProps(["slice", "index", "slices", "context"]),
+ * 	props: getSliceComponentProps(["slice", "index", "slices", "context"]),
  * };
  * ```
+ *
+ * @typeParam TSlice - The type(s) of slices in the Slice Zone
+ * @typeParam TContext - Arbitrary data passed to `<SliceZone />` and made
+ *   available to all Slice components
+ * @param propsHint - An optional array of prop names used for the sole purpose
+ *   of having a visual hint of which props are made available to the slice,
+ *   this parameters doesn't have any effect
+ *
+ * @returns Props object to use with {@link defineComponent}
  */
 export const getSliceComponentProps = <
 	TSlice extends SliceLike = SliceLike,
@@ -170,7 +187,8 @@ export type SliceComponentType<
 /**
  * This Slice component can be used as a reminder to provide a proper implementation.
  *
- * This is also the default Vue component rendered when a component mapping cannot be found in `<SliceZone />`.
+ * This is also the default Vue component rendered when a component mapping
+ * cannot be found in `<SliceZone />`.
  */
 export const TODOSliceComponent = __PRODUCTION__
 	? ((() => null) as FunctionalComponent<SliceComponentProps>)
@@ -201,7 +219,8 @@ export const TODOSliceComponent = __PRODUCTION__
 	  }) as SliceComponentType);
 
 /**
- * A record of Slice types mapped to Vue components. Each components will be rendered for each instance of their Slice type.
+ * A record of Slice types mapped to Vue components. Each components will be
+ * rendered for each instance of their Slice type.
  *
  * @typeParam TSlice - The type(s) of slices in the Slice Zone
  * @typeParam TContext - Arbitrary data made available to all Slice components
@@ -226,26 +245,20 @@ export type SliceZoneComponents<
 	};
 
 /**
- * Gets an optimized record of Slice types mapped to Vue components. Each components will be rendered for each instance of their Slice type.
+ * Gets an optimized record of Slice types mapped to Vue components. Each
+ * components will be rendered for each instance of their Slice type.
  *
- * @param components - {@link SliceZoneComponents}
- *
- * @returns A new optimized record of {@link SliceZoneComponents}
- *
- * @typeParam TSlice - The type(s) of slices in the Slice Zone
- * @typeParam TContext - Arbitrary data made available to all Slice components
- *
- * @remarks This is essentially an helper function to ensure {@link markRaw} is correctly applied on each components, improving performances.
+ * @remarks
+ * This is essentially an helper function to ensure {@link markRaw} is correctly
+ * applied on each components, improving performances.
+ * @example Defining a slice components:
  *
- * @example
- * Defining a slice components:
- *
- * ```
- * import { getSliceZoneComponents } from "@prismicio/vue";
+ * ```javascript
+ * import { defineSliceZoneComponents } from "@prismicio/vue";
  *
  * export default {
  *   data() {
- *     components: getSliceZoneComponents({
+ *     components: defineSliceZoneComponents({
  *       foo: Foo,
  *       bar: defineAsyncComponent(
  *         () => new Promise((res) => res(Bar)),
@@ -255,8 +268,14 @@ export type SliceZoneComponents<
  *   }
  * };
  * ```
+ *
+ * @typeParam TSlice - The type(s) of slices in the Slice Zone
+ * @typeParam TContext - Arbitrary data made available to all Slice components
+ * @param components - {@link SliceZoneComponents}
+ *
+ * @returns A new optimized record of {@link SliceZoneComponents}
  */
-export const getSliceZoneComponents = <
+export const defineSliceZoneComponents = <
 	TSlice extends SliceLike = SliceLike,
 	TContext = unknown,
 >(
@@ -281,6 +300,43 @@ export const getSliceZoneComponents = <
 	return result;
 };
 
+/**
+ * Arguments for a `<SliceZone>` `resolver` function.
+ */
+export type SliceZoneResolverArgs<TSlice extends SliceLike = SliceLike> = {
+	/**
+	 * The Slice to resolve to a Vue component..
+	 */
+	slice: TSlice;
+
+	/**
+	 * The name of the Slice.
+	 */
+	sliceName: TSlice["slice_type"];
+
+	/**
+	 * The index of the Slice in the Slice Zone.
+	 */
+	i: number;
+};
+
+/**
+ * A function that determines the rendered Vue component for each Slice in the
+ * Slice Zone. If a nullish value is returned, the component will fallback to
+ * the `components` or `defaultComponent` props to determine the rendered component.
+ *
+ * @deprecated Use the `components` prop instead.
+ * @param args - Arguments for the resolver function.
+ *
+ * @returns The Vue component to render for a Slice.
+ */
+export type SliceZoneResolver<
+	TSlice extends SliceLike = SliceLike,
+	TContext = unknown,
+> = (
+	args: SliceZoneResolverArgs<TSlice>,
+) => SliceComponentType<TSlice, TContext> | string | undefined | null;
+
 /**
  * Props for `<SliceZone />`.
  *
@@ -291,26 +347,45 @@ export type SliceZoneProps<
 	TSlice extends SliceLike = SliceLike,
 	TContext = unknown,
 > = {
-	/** List of Slice data from the Slice Zone. */
+	/**
+	 * List of Slice data from the Slice Zone.
+	 */
 	slices: SliceZoneLike<TSlice>;
 
-	/** A record mapping Slice types to Vue components. */
-	components: SliceZoneComponents;
+	/**
+	 * A record mapping Slice types to Vue components.
+	 */
+	components?: SliceZoneComponents;
 
-	/** Arbitrary data made available to all Slice components. */
+	/**
+	 * A function that determines the rendered Vue component for each Slice in the
+	 * Slice Zone.
+	 *
+	 * @deprecated Use the `components` prop instead.
+	 * @param args - Arguments for the resolver function.
+	 *
+	 * @returns The Vue component to render for a Slice.
+	 */
+	resolver?: SliceZoneResolver<TSlice, TContext>;
+
+	/**
+	 * Arbitrary data made available to all Slice components.
+	 */
 	context?: TContext;
 
 	/**
-	 * 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 The Slice Zone default component provided to `@prismicio/vue` plugin if configured, otherwise `null` when `process.env.NODE_ENV === "production"` else {@link TODOSliceComponent}.
 	 */
 	defaultComponent?: SliceComponentType<TSlice, TContext>;
 
 	/**
-	 * An HTML tag name, a component, or a functional component used to wrap the output. The Slice Zone is not wrapped by default.
+	 * An HTML tag name, a component, or a functional component used to wrap the
+	 * output. The Slice Zone is not wrapped by default.
 	 */
 	wrapper?: string | ConcreteComponent;
 };
@@ -329,7 +404,13 @@ export const SliceZoneImpl = /*#__PURE__*/ defineComponent({
 		},
 		components: {
 			type: Object as PropType<SliceZoneComponents>,
-			required: true,
+			default: undefined,
+			required: false,
+		},
+		resolver: {
+			type: Function as PropType<SliceZoneResolver>,
+			default: undefined,
+			required: false,
 		},
 		context: {
 			type: null,
@@ -357,14 +438,28 @@ export const SliceZoneImpl = /*#__PURE__*/ defineComponent({
 
 		const renderedSlices = computed(() => {
 			return props.slices.map((slice, index) => {
-				const component =
-					slice.slice_type in props.components
+				let component =
+					props.components && slice.slice_type in props.components
 						? props.components[slice.slice_type]
 						: props.defaultComponent ||
 						  options.components?.sliceZoneDefaultComponent ||
 						  TODOSliceComponent;
 
+				// TODO: Remove `resolver` in v3 in favor of `components`.
+				if (props.resolver) {
+					const resolvedComponent = props.resolver({
+						slice,
+						sliceName: slice.slice_type,
+						i: index,
+					});
+
+					if (resolvedComponent) {
+						component = resolvedComponent;
+					}
+				}
+
 				const p = {
+					key: `${slice.slice_type}-${index}`,
 					slice,
 					index,
 					context: props.context,

package/src/components/index.ts

@@ -23,7 +23,7 @@ export type {
 export {
 	getSliceComponentProps,
 	TODOSliceComponent,
-	getSliceZoneComponents,
+	defineSliceZoneComponents,
 	SliceZoneImpl,
 	SliceZone,
 } from "./SliceZone";
@@ -33,6 +33,8 @@ export type {
 	SliceComponentType,
 	SliceLike,
 	SliceZoneComponents,
+	SliceZoneResolverArgs,
+	SliceZoneResolver,
 	SliceZoneLike,
 	SliceZoneProps,
 } from "./SliceZone";