feat: add getToolbarSrc() helper

[angeloashmore]

Types of changes

• Chore (a non-breaking change which is related to package maintenance)
• Bug fix (a non-breaking change which fixes an issue)
• New feature (a non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Description

This PR adds a getToolbarSrc() helper that returns a Prismic repository's Prismic Toolbar script URL.

import * as prismic from "@prismicio/client";

const toolbarSrc = prismic.getToolbarSrc("my-repo-name");
// => https://static.cdn.prismic.io/prismic.js?new=true&repo=my-repo-name

Motivation

This helper will replace @prismicio/react's <PrismicToolbar> when used in React Server Components environments; in Server Components environments, <script> elements should be rendered on the server, which <PrismicToolbar> is not able to do.

Providing getToolbarSrc() allows a developer to get the Prismic Toolbar's script URL and render the <script> using their framework's conventions. In a Next.js app, for example, a developer would use next/script.

import * as prismic from "@prismicio/client";
import Script from "next/script";

export default function Page() {
  const toolbarSrc = prismic.getToolbarSrc("my-repo-name");

  return (
    <main>
      <Script src={toolbarSrc} />
    </main>
  );
}

Checklist:

• My change requires an update to the official documentation.
• All TSDoc comments are up-to-date and new ones have been added where necessary.
• All new and existing tests are passing.

🐋

[lihbr]

LGTM, don't want to add to the scope if this PR (I can do it later), but any thoughts on adding preview helpers too? + maybe we could expose getPreviewCookie()

Something to stop us from reimplementing this code everytime:

• https://github.com/nuxt-modules/prismic/blob/v3/src/runtime/plugin.ts#L35-L59
• https://github.com/prismicio/prismic-next/blob/cc825bd8ca36b4215880d61c7774ca9c10552f4b/src/lib/getPrismicPreviewCookie.ts
• https://github.com/prismicio/prismic-next/blob/cc825bd8ca36b4215880d61c7774ca9c10552f4b/src/PrismicPreview.tsx#L116-L149

import { getPreviewCookie } from "./lib/getPreviewCookie";

export const isPreviewSession = (cookieJar: string): boolean => {
	const previewCookie = getPreviewCookie(cookieJar);

	if (!previewCookie) {
		return false;
	}

	const session = JSON.parse(decodeURIComponent(previewCookie));

	return Object.keys(session).some((key) => {
		return key in session &&
			typeof session[key] === 'object' &&
			session[key] !== null &&
			'preview' in session[key] &&
			session[key]
	});
};

[angeloashmore]

any thoughts on adding preview helpers too? + maybe we could expose getPreviewCookie()

Yes, let's do it! @samlfair suggested a similar thing here as well: #268

Those additions are outside the scope of this PR, as you mentioned. Let's add these helpers in a separate PR:

• isPreviewSessionActive()
• getPreviewCookie()

(We may need to iterate on the names, but it's at least clear what they should do.)