@prismicio/vue 4.3.0 → 5.0.0-alpha.0

package/src/PrismicText.vue

@@ -0,0 +1,63 @@
+<script lang="ts" setup>
+import type { RichTextField } from "@prismicio/client"
+import { asText, isFilled } from "@prismicio/client"
+import { DEV } from "esm-env"
+import { watchEffect } from "vue"
+
+import Wrapper from "./lib/Wrapper.vue"
+import { devMsg } from "./lib/devMsg"
+
+import type { ComponentOrTagName } from "./types"
+
+/**
+ * Props for `<PrismicText />`.
+ */
+export type PrismicTextProps = {
+	/**
+	 * The Prismic rich text field to render.
+	 */
+	field: RichTextField | null | undefined
+
+	/**
+	 * The string value to be rendered when the field is empty. If a fallback is
+	 * not given, `""` (nothing) will be rendered.
+	 */
+	fallback?: string
+
+	/**
+	 * The separator used between blocks.
+	 *
+	 * @defaultValue `" "` (a whitespace)
+	 */
+	separator?: string
+
+	/**
+	 * An HTML tag name or a component used to wrap the output. `<PrismicText />`
+	 * is not wrapped by default.
+	 *
+	 * @defaultValue `"template"` (no wrapper)
+	 */
+	wrapper?: ComponentOrTagName
+}
+
+const props = defineProps<PrismicTextProps>()
+defineOptions({ name: "PrismicText" })
+
+if (DEV) {
+	watchEffect(() => {
+		if (typeof props.field === "string") {
+			throw new Error(
+				`[PrismicText] The "field" prop only accepts a Rich Text or title field's value but was provided a different type of field instead (e.g. a Key Text or Select field). You can resolve this error by rendering the field value inline without <PrismicText>. For more details, see ${devMsg(
+					"prismictext-works-only-with-rich-text-and-title-fields",
+				)}`,
+			)
+		}
+	}, {})
+}
+</script>
+
+<template>
+	<Wrapper v-if="isFilled.richText(field) || fallback" :wrapper="wrapper">
+		{{ asText(field) || fallback }}
+	</Wrapper>
+</template>

package/src/SliceZone/SliceZone.vue

@@ -0,0 +1,113 @@
+<script lang="ts" setup>
+import { computed } from "vue"
+
+import Wrapper from "../lib/Wrapper.vue"
+
+import type { ComponentOrTagName } from "../types"
+import type {
+	SliceComponentType,
+	SliceLike,
+	SliceZoneComponents,
+	SliceZoneLike,
+} from "./types"
+
+import { usePrismic } from "../usePrismic"
+
+import { TODOSliceComponent } from "./TODOSliceComponent"
+
+/**
+ * Props for `<SliceZone />`.
+ *
+ * @typeParam TContext - Arbitrary data made available to all Slice components
+ */
+export type SliceZoneProps<TContext = unknown> = {
+	/**
+	 * List of Slice data from the Slice Zone.
+	 */
+	slices: SliceZoneLike<SliceLike & Record<string, unknown>>
+
+	/**
+	 * A record mapping Slice types to Vue components.
+	 */
+	components?: SliceZoneComponents
+
+	/**
+	 * The Vue 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}.
+	 */
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	defaultComponent?: SliceComponentType<any, TContext>
+
+	/**
+	 * Arbitrary data made available to all Slice components.
+	 */
+	context?: TContext
+
+	/**
+	 * An HTML tag name or a component used to wrap the output. `<SliceZone />` is
+	 * not wrapped by default.
+	 *
+	 * @defaultValue `"template"` (no wrapper)
+	 */
+	wrapper?: ComponentOrTagName
+}
+
+const props = defineProps<SliceZoneProps>()
+defineOptions({ name: "SliceZone" })
+
+const { options } = usePrismic()
+
+const renderedSlices = computed(() => {
+	return props.slices.map((slice, index) => {
+		const type =
+			"slice_type" in slice ? (slice.slice_type as string) : slice.type
+
+		const key =
+			"id" in slice && typeof slice.id === "string"
+				? slice.id
+				: `${index}-${JSON.stringify(slice)}`
+
+		const is =
+			props.components?.[type] ||
+			props.defaultComponent ||
+			options.components?.sliceZoneDefaultComponent
+
+		if (!is) {
+			return { is: TODOSliceComponent, key, props: { slice } }
+		}
+
+		if (slice.__mapped) {
+			const { __mapped, ...mappedProps } = slice
+
+			return { is, key, props: mappedProps }
+		}
+
+		return {
+			is,
+			key,
+			props: {
+				slice,
+				index,
+				context: props.context,
+				slices: props.slices,
+			},
+		}
+	})
+})
+</script>
+
+<template>
+	<Wrapper v-if="slices" :wrapper="wrapper">
+		<component
+			v-for="renderedSlice in renderedSlices"
+			:is="renderedSlice.is"
+			:key="renderedSlice.key"
+			v-bind="renderedSlice.props"
+		/>
+	</Wrapper>
+</template>

package/src/SliceZone/TODOSliceComponent.ts

@@ -0,0 +1,49 @@
+import { DEV } from "esm-env"
+import type { PropType } from "vue"
+import { computed, defineComponent, h, watchEffect } from "vue"
+
+import type { SliceComponentType, SliceLike } from "./types"
+
+/**
+ * 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 />`.
+ */
+export const TODOSliceComponent = DEV
+	? /*#__PURE__*/ (defineComponent({
+			name: "TODOSliceComponent",
+			props: {
+				slice: {
+					type: Object as PropType<SliceLike>,
+					required: true,
+				},
+			},
+			setup(props) {
+				const type = computed(() => {
+					return "slice_type" in props.slice
+						? props.slice.slice_type
+						: props.slice.type
+				})
+
+				watchEffect(() => {
+					console.warn(
+						`[SliceZone] Could not find a component for Slice type "${type.value}"`,
+						props.slice,
+					)
+				})
+
+				return () => {
+					return h(
+						"section",
+						{
+							"data-slice-zone-todo-component": "",
+							"data-slice-type": type.value,
+						},
+						[`Could not find a component for Slice type "${type.value}"`],
+					)
+				}
+			},
+		}) as SliceComponentType)
+	: ((() => null) as SliceComponentType)

package/src/SliceZone/defineSliceZoneComponents.ts

@@ -0,0 +1,67 @@
+import { markRaw } from "vue"
+
+import type {
+	SliceComponentType,
+	SliceLike,
+	SliceZoneComponents,
+} from "./types"
+
+/**
+ * Gets an optimized record of Slice types mapped to Vue components. Each
+ * components will be rendered for each instance of their Slice type.
+ *
+ * @remarks
+ * This is essentially an helper function to ensure {@link markRaw} is correctly
+ * applied on each components, improving performances.
+ *
+ * @example
+ *
+ * ```javascript
+ * // Defining a slice components
+ * import { defineSliceZoneComponents } from "@prismicio/vue";
+ *
+ * export default {
+ *   data() {
+ *     components: defineSliceZoneComponents({
+ *       foo: Foo,
+ *       bar: defineAsyncComponent(
+ *         () => new Promise((res) => res(Bar)),
+ *       ),
+ *       baz: "Baz",
+ *     }),
+ *   }
+ * };
+ * ```
+ *
+ * @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 defineSliceZoneComponents = <
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	TSlice extends SliceLike = any,
+	TContext = unknown,
+>(
+	components: SliceZoneComponents<TSlice, TContext>,
+): SliceZoneComponents<TSlice, TContext> => {
+	const result = {} as SliceZoneComponents<TSlice, TContext>
+
+	let type: keyof typeof components
+	for (type in components) {
+		const component = components[type]
+		result[type] =
+			typeof component === "string"
+				? component
+				: markRaw(
+						component as SliceComponentType<
+							Extract<TSlice, SliceLike<typeof type>>,
+							TContext
+						>,
+					)
+	}
+
+	return result
+}

package/src/SliceZone/getSliceComponentProps.ts

@@ -0,0 +1,98 @@
+import type { PropType } from "vue"
+
+import type { SliceComponentProps, SliceLike } from "./types"
+
+/**
+ * Native Vue props for a component rendering content from a Prismic Slice using
+ * the `<SliceZone />` component.
+ *
+ * @typeParam TSlice - The Slice type
+ * @typeParam TContext - Arbitrary data passed to `<SliceZone />` and made
+ *   available to all Slice components
+ */
+type DefineComponentSliceComponentProps<
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	TSlice extends SliceLike = any,
+	TContext = unknown,
+> = {
+	slice: {
+		type: PropType<SliceComponentProps<TSlice, TContext>["slice"]>
+		required: true
+	}
+	index: {
+		type: PropType<SliceComponentProps<TSlice, TContext>["index"]>
+		required: true
+	}
+	slices: {
+		type: PropType<SliceComponentProps<TSlice, TContext>["slices"]>
+		required: true
+	}
+	context: {
+		type: PropType<SliceComponentProps<TSlice, TContext>["context"]>
+		required: true
+	}
+}
+
+/**
+ * Gets native Vue props for a component rendering content from a Prismic Slice
+ * using the `<SliceZone />` component.
+ *
+ * Props are: `["slice", "index", "slices", "context"]`
+ *
+ * @example
+ *
+ * ```typescript
+ * // Defining a new slice component
+ * import { getSliceComponentProps } from "@prismicio/vue"
+ *
+ * defineProps(getSliceComponentProps())
+ * ```
+ *
+ * @example
+ *
+ * ```typescript
+ * // Defining a new slice component with visual hint
+ * import { getSliceComponentProps } from "@prismicio/vue"
+ *
+ * defineProps(
+ * 	getSliceComponentProps(["slice", "index", "slices", "context"]),
+ * )
+ * ```
+ *
+ * @typeParam TSlice - The Slice type
+ * @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 `defineProps()`
+ */
+export const getSliceComponentProps = <
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	TSlice extends SliceLike = any,
+	TContext = unknown,
+>(
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	propsHint?: ["slice", "index", "slices", "context"],
+): DefineComponentSliceComponentProps<TSlice, TContext> => ({
+	slice: {
+		type: Object as PropType<SliceComponentProps<TSlice, TContext>["slice"]>,
+		required: true,
+	},
+	index: {
+		type: Number as PropType<SliceComponentProps<TSlice, TContext>["index"]>,
+		required: true,
+	},
+	slices: {
+		type: Array as PropType<SliceComponentProps<TSlice, TContext>["slices"]>,
+		required: true,
+	},
+	context: {
+		type: null as unknown as PropType<
+			SliceComponentProps<TSlice, TContext>["context"]
+		>,
+		required: true,
+	},
+})

package/src/SliceZone/index.ts

@@ -0,0 +1,13 @@
+export { TODOSliceComponent } from "./TODOSliceComponent"
+export { getSliceComponentProps } from "./getSliceComponentProps"
+export { defineSliceZoneComponents } from "./defineSliceZoneComponents"
+
+export type {
+	SliceComponentProps,
+	SliceComponentType,
+	SliceLike,
+	SliceLikeGraphQL,
+	SliceLikeRestV2,
+	SliceZoneComponents,
+	SliceZoneLike,
+} from "./types"

package/src/SliceZone/types.ts

@@ -0,0 +1,163 @@
+import type { Slice } from "@prismicio/client"
+import type {
+	DefineComponent,
+	FunctionalComponent,
+	defineAsyncComponent,
+} from "vue"
+
+/**
+ * Returns the type of a `SliceLike` type.
+ *
+ * @typeParam TSlice - The Slice from which the type will be extracted.
+ */
+type ExtractSliceType<TSlice extends SliceLike> = TSlice extends SliceLikeRestV2
+	? TSlice["slice_type"]
+	: TSlice extends SliceLikeGraphQL
+		? TSlice["type"]
+		: never
+
+/**
+ * The minimum required properties to represent a Prismic Slice from the Prismic
+ * Rest API V2 for the `unstable_mapSliceZone()` helper.
+ *
+ * @typeParam SliceType - Type name of the Slice.
+ */
+export type SliceLikeRestV2<TSliceType extends string = string> = Pick<
+	Slice<TSliceType>,
+	"id" | "slice_type"
+>
+
+/**
+ * The minimum required properties to represent a Prismic Slice from the Prismic
+ * GraphQL API for the `unstable_mapSliceZone()` helper.
+ *
+ * @typeParam SliceType - Type name of the Slice.
+ */
+export type SliceLikeGraphQL<TSliceType extends string = string> = {
+	type: Slice<TSliceType>["slice_type"]
+}
+
+/**
+ * The minimum required properties to represent a Prismic Slice for the
+ * `<SliceZone />` component.
+ *
+ * If using Prismic's Rest API V2, use the `Slice` export from
+ * `@prismicio/client` for a full interface.
+ *
+ * @typeParam TSliceType - Type name of the Slice
+ */
+export type SliceLike<TSliceType extends string = string> = (
+	| SliceLikeRestV2<TSliceType>
+	| SliceLikeGraphQL<TSliceType>
+) & {
+	/**
+	 * If `true`, this Slice has been modified from its original value using a
+	 * mapper and `@prismicio/client`'s `mapSliceZone()`.
+	 *
+	 * @internal
+	 */
+	__mapped?: true
+}
+
+/**
+ * A looser version of the `SliceZone` type from `@prismicio/client` using
+ * `SliceLike`.
+ *
+ * If using Prismic's REST API, use the `SliceZone` export from
+ * `@prismicio/client` for the full type.
+ *
+ * @typeParam TSlice - The type(s) of slices in the Slice Zone
+ */
+export type SliceZoneLike<TSlice extends SliceLike = SliceLike> =
+	readonly TSlice[]
+
+/**
+ * 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
+ */
+export type SliceComponentProps<
+	TSlice extends SliceLike = SliceLike,
+	TContext = unknown,
+> = {
+	/**
+	 * Slice data for this component.
+	 */
+	slice: TSlice
+
+	/**
+	 * The index of the Slice in the Slice Zone.
+	 */
+	index: number
+
+	/**
+	 * 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<
+		TSlice extends SliceLikeGraphQL ? SliceLikeGraphQL : SliceLikeRestV2
+	>
+
+	/**
+	 * Arbitrary data passed to `<SliceZone />` and made available to all Slice
+	 * components.
+	 */
+	context: TContext
+}
+
+/**
+ * A Vue component to be rendered for each instance of its Slice.
+ *
+ * @typeParam TSlice - The type(s) of slices in the Slice Zone
+ * @typeParam TContext - Arbitrary data made available to all Slice components
+ */
+export type SliceComponentType<
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	TSlice extends SliceLike = any,
+	TContext = unknown,
+> =
+	// For reference within TypeScript files when `*.vue` type cannot be inferred
+	// eslint-disable-next-line @typescript-eslint/no-empty-object-type, @typescript-eslint/no-explicit-any
+	| DefineComponent<{}, {}, any>
+	// Likewise, for reference with TypeScript files.
+	| ReturnType<typeof defineAsyncComponent>
+	| DefineComponent<SliceComponentProps<TSlice, TContext>>
+	| FunctionalComponent
+
+/**
+ * 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
+ */
+export type SliceZoneComponents<
+	TSlice extends SliceLike = SliceLike,
+	TContext = unknown,
+> =
+	// This is purposely not wrapped in Partial to ensure a component is provided
+	// for all Slice types. <SliceZone /> will render a default component if one is
+	// not provided, but it *should* be a type error if an explicit component is
+	// missing.
+	//
+	// If a developer purposely does not want to provide a component, they can
+	// assign it to the TODOSliceComponent exported from this package. This
+	// signals to future developers that it is a placeholder and should be
+	// implemented.
+	{
+		[SliceType in ExtractSliceType<TSlice>]:
+			| SliceComponentType<
+					Extract<TSlice, SliceLike<SliceType>> extends never
+						? SliceLike
+						: Extract<TSlice, SliceLike<SliceType>>,
+					TContext
+			  >
+			// Global components
+			| string
+	}