@driftime/sanity-plugin-handbook 0.4.0 → 0.5.0

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createContext, createElement, useContext, useEffect, useRef, useState } from "react";
-import { CommandList, PreviewCard, SanityDefaultPreview, defineArrayMember, defineField, definePlugin, defineType, useClient, useCurrentUser, useSchema } from "sanity";
+import { CommandList, PreviewCard, SanityDefaultPreview, defineArrayMember, defineField, definePlugin, defineType, useCurrentUser, useDocumentStore, useSchema } from "sanity";
 import { c } from "react/compiler-runtime";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { Box, Button, Card, Flex, Heading, Layer, LayerProvider, Stack, Text, useClickOutsideEvent, useElementSize, useTheme_v2 } from "@sanity/ui";
@@ -11,21 +11,18 @@ import { ChevronRightIcon } from "@sanity/icons/ChevronRight";
 import { Popover } from "@sanity/ui/popover";
 import { PortableText } from "@portabletext/react";
 import { Code } from "@sanity/ui/code";
-/**
-* Properties the plugin's own icons are drawn with. Icons taken from `@sanity/icons` are left alone,
-* since they already carry the sizing and stroke the rest of the Studio uses.
-*/
+/** Default props for the plugin's own icons. Icons from `@sanity/icons` already match the Studio. */
 const defaultIconProps = {
 	width: "1em",
 	height: "1em",
 	strokeWidth: 1.5
 };
 /**
-* Creates a Sanity Studio icon component from an SVG icon.
+* Wraps an SVG icon component for use in the Studio.
 *
-* @param icon - The icon component to wrap.
-* @param props - Additional props merged over the default properties a Studio icon is drawn with.
-* @returns A Studio icon component.
+* @param icon - The icon to wrap.
+* @param props - Props that override the Studio icon defaults.
+* @returns An icon component.
 */
 function createSanityIcon(icon, props) {
 	let Icon = icon;
@@ -37,38 +34,45 @@ function createSanityIcon(icon, props) {
 	}
 	return SanityIcon;
 }
-/** Whether the plugin is running in a development build, which decides whether it reports what it recovered from. */
+/** Whether this is a development build, the only kind in which the plugin logs. */
 const isDevelopment = process.env.NODE_ENV === "development", prefixStyle = "color: #2276fc";
 /**
-* Creates the logger a package reports through, so every message names the plugin it came from and
-* only a development build hears it. In a browser console the name is drawn in blue, the way the
-* Studio's own messages are; a terminal ignores the styling and prints it plain.
+* Creates a logger that prefixes messages with the plugin's name and only logs in development builds.
+* Browser consoles show the prefix in blue.
 *
-* @param name - Name of the package the messages come from.
-* @returns Functions that warn, report an error, or word a message for throwing.
+* @param name - The package name to prefix messages with.
+* @returns Functions that log progress, a warning, or an error, or format a message to throw.
 */
 function createLogger(name) {
 	let prefix = `[${name}]`;
 	/**
-	* Words a message so it names the package it came from.
+	* Prefixes a message with the package name.
 	*
-	* @param message - The message to word.
-	* @returns The message with the package name in front.
+	* @param message - The message.
+	* @returns The prefixed message.
 	*/
 	function format(message) {
 		return `${prefix} ${message}`;
 	}
 	return {
 		/**
-		* Reports something the plugin recovered from, in development only.
+		* Logs progress worth seeing, such as what a build step did, in development builds only.
+		*
+		* @param message - What happened.
+		*/
+		info(message) {
+			isDevelopment && console.info(`%c${prefix}%c ${message}`, prefixStyle, "");
+		},
+		/**
+		* Logs a warning about something the plugin recovered from, in development builds only.
 		*
-		* @param message - What was recovered from and what to do about it.
+		* @param message - What happened and what to do about it.
 		*/
 		warn(message) {
 			isDevelopment && console.warn(`%c${prefix}%c ${message}`, prefixStyle, "");
 		},
 		/**
-		* Reports something the plugin could not recover from, in development only.
+		* Logs an error the plugin couldn't recover from, in development builds only.
 		*
 		* @param message - What went wrong and what to do about it.
 		*/
@@ -78,7 +82,7 @@ function createLogger(name) {
 		format
 	};
 }
-/** Name the package is published under, which every message it reports carries. */
+/** Package name, used as the prefix on every logged message. */
 const pluginName = "@driftime/sanity-plugin-handbook", logger = createLogger(pluginName), guideTypeName = "handbook.guide", handbookTypeName = "handbook.handbook", imageTypeName = "handbook.image", videoTypeName = "handbook.video", codeTypeName = "handbook.code", calloutTypeName = "handbook.callout", horizontalRuleTypeName = "handbook.horizontalRule", singletonTypes = /* @__PURE__ */ new Set([handbookTypeName]), documentTypes = /* @__PURE__ */ new Set([handbookTypeName, guideTypeName]);
 function BookTextIcon(props) {
 	let $ = c(5), t0, t1, t2;
@@ -103,12 +107,11 @@ function BookTextIcon(props) {
 	}), $[3] = props, $[4] = t3), t3;
 }
 /**
-* Checks whether a value is defined and non-empty, treating `false`, empty strings, and objects with
-* no keys as absent. An array is absent unless one of its elements is itself present, while anything
-* built from a class counts as present on existence alone. Not intended for boolean flags.
+* Checks whether a value is present. `false`, blank strings, and empty plain objects count as absent,
+* as does an array with no present elements.
 *
 * @param value - The value to check.
-* @returns True if the value is defined and not empty.
+* @returns True if the value is present.
 */
 function isDefined(value) {
 	if (value == null || value === !1) return !1;
@@ -121,10 +124,10 @@ function isDefined(value) {
 	return !0;
 }
 /**
-* Converts a string between different casing formats.
+* Converts a string to another case.
 *
 * @param value - The string to convert.
-* @param format - The target casing format.
+* @param format - The case to convert to.
 * @returns The converted string.
 */
 function convertCase(value, format) {
@@ -140,21 +143,20 @@ function convertCase(value, format) {
 	}
 }
 /**
-* Checks whether a value can be read by key, narrowing what arrives untyped from outside the plugin.
+* Checks whether a value is an object whose keys can be read.
 *
 * @param value - The value to check.
-* @returns True if the value has keys to read.
+* @returns True if the value is an object.
 */
 function isRecord(value) {
 	return typeof value == "object" && !!value;
 }
 /**
-* Reads a value out of nested records by following a path of keys, so a caller can name something
-* inside a shape it does not otherwise know.
+* Reads a nested value by following a path of keys.
 *
 * @param value - The object to read from.
-* @param path - Keys leading to the value.
-* @returns The value at the path, or undefined when a key is missing or a step holds no keys to read.
+* @param path - The keys to follow.
+* @returns The value, or undefined when the path doesn't exist.
 */
 function readPath(value, path) {
 	let current = value;
@@ -164,7 +166,7 @@ function readPath(value, path) {
 	}
 	return current;
 }
-/** Share of the available space the content pane takes relative to the sidebar. */
+/** Share of the space the content pane takes relative to the sidebar. */
 const contentSpacing = {
 	section: 48,
 	paragraph: 16,
@@ -175,80 +177,53 @@ const contentSpacing = {
 	list: 32,
 	nestedList: 12,
 	rule: 40
-}, assetUrlFragment = "\"asset\": { \"url\": asset.asset->url }", guideFragment = `...@-> {
-  ...,
-  content[] { ..., ${`
-  _type == "${imageTypeName}" => { ..., ${assetUrlFragment} },
-  _type == "${videoTypeName}" => { ..., ${assetUrlFragment} }
-`} }
-}`;
-/**
-* Brands a GROQ query with the shape of the data it returns, so a fetch can infer its result type
-* instead of being told it at every call site.
-*
-* @param query - The GROQ query string.
-* @returns The query, typed to the given result shape.
-*/
-function defineTypedQuery(query) {
-	return query;
-}
-/**
-* Runs a branded query against the dataset, resolving a missing document to undefined.
-*
-* @param client - The Sanity client to query with.
-* @param query - The branded query to run.
-* @returns The result, or undefined when the query matched nothing.
-*/
-async function fetchQuery(client, query) {
-	return await client.fetch(query) ?? void 0;
-}
-/** Fetches the Handbook singleton with expanded guide references. */
-const handbookQuery = defineTypedQuery(`
+}, assetUrlFragment = "\"asset\": { \"url\": asset.asset->url }", handbookQuery = `
   *[_type == "${handbookTypeName}"][0] {
     ...,
     groups[] {
       ...,
       guides[] {
         ...,
-        ${guideFragment}
+        ${`...@-> {
+  ...,
+  content[] { ..., ${`
+  _type == "${imageTypeName}" => { ..., ${assetUrlFragment} },
+  _type == "${videoTypeName}" => { ..., ${assetUrlFragment} }
+`} }
+}`}
       }
     }
   }
-`), handbookDocumentsQuery = defineTypedQuery(`*[_type == "${handbookTypeName}" || _type == "${guideTypeName}"]`);
+`, handbookDocumentsQuery = `*[_type == "${handbookTypeName}" || _type == "${guideTypeName}"]`;
 /**
-* Fetches the Handbook singleton from the dataset with its guide references expanded, refetching
-* whenever one of the documents it draws on changes.
+* Reads the published Handbook document with its guides expanded, updating when any Handbook document is published.
 *
-* @returns The Handbook and a flag for whether it is still loading.
+* @returns The Handbook document, or undefined while it loads or when there isn't one.
 */
 function useHandbookDocument() {
-	let $ = c(7), t0;
-	$[0] === Symbol.for("react.memo_cache_sentinel") ? (t0 = { apiVersion: "2026-01-01" }, $[0] = t0) : t0 = $[0];
-	let client = useClient(t0), [handbook, setHandbook] = useState(void 0), [loading, setLoading] = useState(!0), t1, t2;
-	$[1] === client ? (t1 = $[2], t2 = $[3]) : (t1 = () => {
-		let fetchHandbook = async function fetchHandbook() {
-			setHandbook(await fetchQuery(client, handbookQuery)), setLoading(!1);
-		};
-		fetchHandbook();
-		let subscription = client.listen(handbookDocumentsQuery).subscribe(() => {
-			fetchHandbook();
+	let $ = c(3), documentStore = useDocumentStore(), [handbook, setHandbook] = useState(), t0, t1;
+	return $[0] === documentStore ? (t0 = $[1], t1 = $[2]) : (t0 = () => {
+		let subscription = documentStore.listenQuery({
+			fetch: handbookQuery,
+			listen: handbookDocumentsQuery
+		}, {}, {
+			apiVersion: "2026-01-01",
+			perspective: "published",
+			throttleTime: 1e3
+		}).subscribe((result) => {
+			setHandbook(result ?? void 0);
 		});
 		return () => {
 			subscription.unsubscribe();
 		};
-	}, t2 = [client], $[1] = client, $[2] = t1, $[3] = t2), useEffect(t1, t2);
-	let t3;
-	return $[4] !== handbook || $[5] !== loading ? (t3 = {
-		handbook,
-		loading
-	}, $[4] = handbook, $[5] = loading, $[6] = t3) : t3 = $[6], t3;
+	}, t1 = [documentStore], $[0] = documentStore, $[1] = t0, $[2] = t1), useEffect(t0, t1), handbook;
 }
 const HandbookContext = createContext(void 0);
 /**
-* Accesses the Handbook context for tab state and plugin configuration.
+* Reads the Handbook context.
 *
-* @returns The resolved plugin configuration alongside the state the panes share.
-* @throws If used outside the provider.
+* @returns The plugin configuration and the shared pane state.
+* @throws When used outside the provider.
 */
 function useHandbookContext() {
 	let handbookContext = useContext(HandbookContext);
@@ -256,30 +231,29 @@ function useHandbookContext() {
 	return handbookContext;
 }
 /**
-* Provides the tab state the sidebar and content panes share, alongside the plugin configuration and
-* the handbook singleton fetched from the dataset.
+* Provides the plugin configuration, the Handbook document, and the tab state shared by the sidebar and
+* content panes.
 *
-* @returns The provider wrapping its children.
+* @returns The provider.
 */
 function HandbookProvider(t0) {
-	let $ = c(12), { sidebarTitle, roles, blocks, undocumentedFieldMessage, children } = t0, [activeTab, setActiveTab] = useState(void 0), [sidebarExpanded, setSidebarExpanded] = useState(!0), { handbook, loading } = useHandbookDocument(), t1;
-	$[0] !== activeTab || $[1] !== blocks || $[2] !== handbook || $[3] !== loading || $[4] !== roles || $[5] !== sidebarExpanded || $[6] !== sidebarTitle || $[7] !== undocumentedFieldMessage ? (t1 = {
+	let $ = c(11), { sidebarTitle, roles, blocks, undocumentedFieldMessage, children } = t0, [activeTab, setActiveTab] = useState(void 0), [sidebarExpanded, setSidebarExpanded] = useState(!0), handbook = useHandbookDocument(), t1;
+	$[0] !== activeTab || $[1] !== blocks || $[2] !== handbook || $[3] !== roles || $[4] !== sidebarExpanded || $[5] !== sidebarTitle || $[6] !== undocumentedFieldMessage ? (t1 = {
 		sidebarTitle,
 		roles,
 		blocks,
 		undocumentedFieldMessage,
 		activeTab,
 		sidebarExpanded,
-		loading,
 		handbook,
 		setActiveTab,
 		setSidebarExpanded
-	}, $[0] = activeTab, $[1] = blocks, $[2] = handbook, $[3] = loading, $[4] = roles, $[5] = sidebarExpanded, $[6] = sidebarTitle, $[7] = undocumentedFieldMessage, $[8] = t1) : t1 = $[8];
+	}, $[0] = activeTab, $[1] = blocks, $[2] = handbook, $[3] = roles, $[4] = sidebarExpanded, $[5] = sidebarTitle, $[6] = undocumentedFieldMessage, $[7] = t1) : t1 = $[7];
 	let t2;
-	return $[9] !== children || $[10] !== t1 ? (t2 = /* @__PURE__ */ jsx(HandbookContext, {
+	return $[8] !== children || $[9] !== t1 ? (t2 = /* @__PURE__ */ jsx(HandbookContext, {
 		value: t1,
 		children
-	}), $[9] = children, $[10] = t1, $[11] = t2) : t2 = $[11], t2;
+	}), $[8] = children, $[9] = t1, $[10] = t2) : t2 = $[10], t2;
 }
 function PaneHeader(t0) {
 	let $ = c(46), backButton, props, style, title;
@@ -571,7 +545,7 @@ function TriangleAlertIcon(props) {
 		]
 	}), $[3] = props, $[4] = t3), t3;
 }
-/** Hint kinds a field can carry, in the order they are displayed. */
+/** Hint kinds, in display order. */
 const hintKinds = [
 	{
 		name: "tip",
@@ -626,10 +600,9 @@ function FieldHints(t0) {
 	}), $[16] = T0, $[17] = t1, $[18] = t2, $[19] = t3, $[20] = t4, $[21] = t5) : t5 = $[21], t5;
 }
 /**
-* Resolves the label shown for a schema type, preferring Handbook metadata over the schema's own
-* title and falling back to a title-cased name.
+* Works out a schema type's label: its Handbook title, then its schema title, then its name in title case.
 *
-* @param type - The schema type or field to resolve a label for.
+* @param type - The schema type or field.
 * @returns The label.
 */
 function resolveTitle(type) {
@@ -637,28 +610,27 @@ function resolveTitle(type) {
 	return handbook?.title ?? title ?? convertCase(name, "title");
 }
 /**
-* Resolves the description shown for a schema type, preferring Handbook metadata and ignoring the
-* non-string descriptions a schema may carry.
+* Works out a schema type's description, preferring its Handbook description and ignoring non-string
+* schema descriptions.
 *
-* @param type - The schema type or field to resolve a description for.
-* @returns The description, or undefined when neither source provides one.
+* @param type - The schema type or field.
+* @returns The description, or undefined when there isn't one.
 */
 function resolveDescription(type) {
 	let { description, handbook } = type;
 	return handbook?.description ?? (typeof description == "string" ? description : void 0);
 }
 /**
-* Narrows a schema type's icon to a renderable component, discarding the string form a schema may
-* carry instead. A consumer's icon is redrawn at the plugin's own weight, so it sits beside the
-* built-in ones rather than at its own library's default size.
+* Gets a schema type's icon as a component, redrawn at the plugin's icon size to match the built-in icons.
+* String icons are ignored.
 *
-* @param type - The schema type to read an icon from.
-* @returns The icon component, or undefined when none is set.
+* @param type - The schema type.
+* @returns The icon component, or undefined when there isn't one.
 */
 function resolveIcon(type) {
 	return typeof type.icon == "function" ? createSanityIcon(type.icon) : void 0;
 }
-/** Schema type names treated as leaf types whose subfields are not displayed. */
+/** Types whose subfields aren't shown. */
 const opaqueTypes = /* @__PURE__ */ new Set([
 	"block",
 	"boolean",
@@ -697,7 +669,7 @@ const opaqueTypes = /* @__PURE__ */ new Set([
 	slug: /* @__PURE__ */ new Set(["current", "source"])
 };
 /**
-* Checks whether a value is a compiled schema field with a nested type object.
+* Checks whether a value is a compiled schema field with a type object.
 *
 * @param value - The value to check.
 * @returns True if the value is a compiled field.
@@ -706,49 +678,49 @@ function isCompiledField(value) {
 	return !isRecord(value) || !("name" in value) || !("type" in value) ? !1 : isRecord(value.type);
 }
 /**
-* Checks whether a value has a `fields` array property.
+* Checks whether a value has a `fields` array.
 *
 * @param value - The value to check.
-* @returns True if the value contains a `fields` array.
+* @returns True if the value has a `fields` array.
 */
 function hasFieldsArray(value) {
 	return isRecord(value) && Array.isArray(value.fields);
 }
 /**
-* Checks whether a value has an `of` array property.
+* Checks whether a value has an `of` array.
 *
 * @param value - The value to check.
-* @returns True if the value contains an `of` array.
+* @returns True if the value has an `of` array.
 */
 function hasOfArray(value) {
 	return isRecord(value) && Array.isArray(value.of);
 }
 /**
-* Extracts the type name a value declares, where it names one at all.
+* Reads the type name a value declares.
 *
-* @param value - The value to inspect.
-* @returns The type name, or undefined when the value declares none.
+* @param value - The value.
+* @returns The type name, or undefined when there isn't one.
 */
 function getTypeName(value) {
 	let typeName = readPath(value, ["type"]);
 	return typeof typeName == "string" ? typeName : void 0;
 }
 /**
-* Extracts the parent type name from a compiled schema type, if present.
+* Reads the parent type name from a compiled schema type.
 *
-* @param resolvedType - The compiled schema type to inspect.
-* @returns The parent type name, or undefined when the type extends none.
+* @param resolvedType - The compiled schema type.
+* @returns The parent type name, or undefined when there isn't one.
 */
 function getParentTypeName(resolvedType) {
 	let parentName = readPath(resolvedType, ["type", "name"]);
 	return isDefined(parentName) ? String(parentName) : void 0;
 }
 /**
-* Normalises a compiled schema field into the shape the Handbook renders. Type names already seen are
-* tracked so a type that refers back to itself does not recurse forever.
+* Converts a compiled schema field into the shape the Handbook renders. Types already seen are tracked,
+* so a type that refers to itself doesn't recurse forever.
 *
-* @param field - A compiled schema field or plain field definition.
-* @param visited - Type names already seen in this normalisation chain.
+* @param field - A compiled field or a plain field definition.
+* @param visited - Type names already seen.
 * @returns The normalised field.
 */
 function normalizeField(field, visited = /* @__PURE__ */ new Set()) {
@@ -758,7 +730,7 @@ function normalizeField(field, visited = /* @__PURE__ */ new Set()) {
 			type: typeName,
 			title: field.title ?? field.type.title,
 			description: field.description ?? field.type.description,
-			handbook: field.handbook
+			handbook: field.handbook ?? field.type.handbook
 		};
 		if (!visited.has(typeName)) {
 			let next = !opaqueTypes.has(typeName) && typeName !== "object" && typeName !== "array" ? /* @__PURE__ */ new Set([...visited, typeName]) : visited, fieldSource = hasFieldsArray(field) ? field : field.type, ofSource = hasOfArray(field) ? field : field.type;
@@ -769,12 +741,11 @@ function normalizeField(field, visited = /* @__PURE__ */ new Set()) {
 	return field;
 }
 /**
-* Resolves only the fields a custom type adds on top of an opaque base type, leaving out the ones the
-* base type contributes of its own accord.
+* Lists the fields a custom type adds to an opaque base type, leaving out the base type's own.
 *
 * @param resolvedType - The compiled or normalised schema type.
-* @param parentName - The opaque base type name.
-* @returns The custom fields, or undefined when none of them holds a value.
+* @param parentName - The opaque base type's name.
+* @returns The custom fields, or undefined when there are none.
 */
 function resolveCustomFields(resolvedType, parentName) {
 	if (!hasFieldsArray(resolvedType)) return;
@@ -782,32 +753,31 @@ function resolveCustomFields(resolvedType, parentName) {
 	return isDefined(customFields) ? customFields : void 0;
 }
 /**
-* Normalises a list of raw field values into the shape the Handbook renders.
+* Normalises a list of raw fields.
 *
-* @param items - Raw field values to normalise.
-* @returns The normalised fields, or undefined when none of them holds a value.
+* @param items - The raw fields.
+* @returns The normalised fields, or undefined when there are none.
 */
 function resolveNormalizedFields(items) {
 	let normalized = items.map((item) => normalizeField(item));
 	return isDefined(normalized) ? normalized : void 0;
 }
 /**
-* Normalises array members and filters out opaque types that have no meaningful subfields.
+* Normalises array members, leaving out opaque types.
 *
-* @param members - Raw array member values to normalise.
-* @returns The normalised non-opaque members, or undefined when none of them holds a value.
+* @param members - The raw array members.
+* @returns The normalised members, or undefined when there are none.
 */
 function resolveNormalizedMembers(members) {
 	let normalized = members.map((member) => normalizeField(member)).filter((member) => !opaqueTypes.has(member.type));
 	return isDefined(normalized) ? normalized : void 0;
 }
 /**
-* Resolves the name of the type a value extends, reaching into the schema registry when the value
-* carries nothing but a type name of its own.
+* Works out a value's parent type name, looking it up in the schema when the value only names its type.
 *
-* @param value - The value to inspect.
-* @param schema - The Sanity schema registry.
-* @returns The parent type name, or undefined when the value extends none.
+* @param value - The value.
+* @param schema - The Sanity schema.
+* @returns The parent type name, or undefined when there isn't one.
 */
 function resolveParentName(value, schema) {
 	let direct = getParentTypeName(value);
@@ -818,12 +788,12 @@ function resolveParentName(value, schema) {
 	return isDefined(resolvedType) ? getParentTypeName(resolvedType) : void 0;
 }
 /**
-* Extracts the fields a value displays, whether it carries them directly, carries array members that
-* do, or names a type that does.
+* Works out the fields a value shows, whether it holds them directly, has array members that do, or
+* names a type that does.
 *
-* @param value - The value to extract fields from.
-* @param schema - The Sanity schema registry.
-* @returns The resolved fields, or undefined when the value has none.
+* @param value - The value.
+* @param schema - The Sanity schema.
+* @returns The fields, or undefined when there are none.
 */
 function resolveFields(value, schema) {
 	if (hasFieldsArray(value)) {
@@ -846,11 +816,11 @@ function resolveFields(value, schema) {
 	}
 }
 /**
-* Resolves the displayable subfields of a field definition by traversing the schema.
+* Works out a field's visible subfields by looking through the schema.
 *
-* @param field - The parent field definition.
-* @param schema - The Sanity schema registry.
-* @returns The non-opaque subfields, or undefined when the field has none.
+* @param field - The field.
+* @param schema - The Sanity schema.
+* @returns The subfields, or undefined when there are none.
 */
 function getSubfields(field, schema) {
 	if (opaqueTypes.has(field.type)) return;
@@ -861,7 +831,7 @@ function getSubfields(field, schema) {
 	let parentName = getParentTypeName(resolvedType);
 	return isDefined(parentName) && opaqueTypes.has(parentName) ? resolveCustomFields(resolvedType, parentName) : resolveFields(resolvedType, schema);
 }
-/** Shared empty ancestor set, so the default prop keeps a stable reference across renders. */
+/** Shared empty set, so the default prop keeps the same reference between renders. */
 const noAncestors = /* @__PURE__ */ new Set();
 function DocumentedField(t0) {
 	let $ = c(59), field, props, t1;
@@ -1014,10 +984,10 @@ function DocumentedField(t0) {
 	return t6;
 }
 /**
-* Builds a section for each configured document role.
+* Builds a sidebar section for each document role.
 *
-* @param roles - Document roles from the plugin configuration.
-* @returns One section per role, holding an entry per document type.
+* @param roles - The configured document roles.
+* @returns One section per role, with an entry per document type.
 */
 function documentTypesSections(roles) {
 	return roles.map(({ title, documents }) => ({
@@ -1193,11 +1163,11 @@ function DocumentTypesOverview() {
 		children: t1
 	}), $[8] = t1, $[9] = t2), t2;
 }
-/** What each hint kind signals to an editor, shown as a legend alongside its icon. */
+/** What each hint kind means, shown next to its icon as a key. */
 const hintDescriptions = {
-	tip: "Helpful tips and best practices for content editors.",
-	info: "Additional context about how the field is used.",
-	caution: "Important warnings about constraints or potential issues."
+	tip: "Tips and suggested practices for people editing content.",
+	info: "More detail about how and where the field is used.",
+	caution: "Warnings about restrictions or problems the field can cause."
 };
 function HowToUse() {
 	let $ = c(8), t0;
@@ -1220,7 +1190,7 @@ function HowToUse() {
 		}), /* @__PURE__ */ jsx(Text, {
 			size: 1,
 			muted: !0,
-			children: "The sidebar lists everything the Handbook holds: these introductory pages, then the document types you can create, grouped by the role they play on the site, and finally any guides your team has written. Selecting an entry opens it here."
+			children: "The sidebar lists everything in the Handbook: these introductory pages first, then the document types you can create, grouped by their role on the site, and then any guides your team has written. Select an entry to open it here."
 		})]
 	}), $[1] = t1) : t1 = $[1];
 	let t2;
@@ -1237,7 +1207,7 @@ function HowToUse() {
 		}), /* @__PURE__ */ jsx(Text, {
 			size: 1,
 			muted: !0,
-			children: "Selecting a document type lists its fields, each showing its name, the kind of value it holds, and what the field is for. The documentation is generated from the content model, so what you read always matches what you see while editing."
+			children: "Selecting a document type lists its fields, with each field’s name, the kind of value it holds, and what it’s for. This documentation is generated from the content model, so it always matches what you see in the editor."
 		})]
 	}), $[2] = t2) : t2 = $[2];
 	let t3, t4;
@@ -1252,7 +1222,7 @@ function HowToUse() {
 	}), t4 = /* @__PURE__ */ jsx(Text, {
 		size: 1,
 		muted: !0,
-		children: "Icons beside a field name carry the guidance that would crowd its description if written into it. Hover or click one to read what it says, and use the key below to tell the three kinds apart."
+		children: "Icons next to a field’s name hold extra guidance that would make its description too long. Hover over or click an icon to read it, and use the key below to see what each icon means."
 	}), $[3] = t3, $[4] = t4) : (t3 = $[3], t4 = $[4]);
 	let t5;
 	$[5] === Symbol.for("react.memo_cache_sentinel") ? (t5 = /* @__PURE__ */ jsxs(Stack, {
@@ -1281,7 +1251,7 @@ function HowToUse() {
 		}), /* @__PURE__ */ jsx(Text, {
 			size: 1,
 			muted: !0,
-			children: "Some fields hold subfields of their own, such as a content block pairing a heading with body text. A control beneath the description counts them and expands to show each one, documented exactly as a top-level field is."
+			children: "Some fields contain subfields, such as a content block with a heading and body text. A button below the description shows how many there are and expands to list them, each documented like any other field."
 		})]
 	}), $[6] = t6) : t6 = $[6];
 	let t7;
@@ -1305,7 +1275,7 @@ function HowToUse() {
 				}), /* @__PURE__ */ jsx(Text, {
 					size: 1,
 					muted: !0,
-					children: "Beneath the document types you may find guides, written by your team rather than generated from the content model. They carry what a field description cannot: house style, editorial process, and how all the pieces fit together."
+					children: "Below the document types, you may find guides written by your team rather than generated from the content model. They cover things a field description can’t, such as house style, editorial process, and how everything fits together."
 				})]
 			})
 		]
@@ -1332,9 +1302,9 @@ function _temp$3(t0) {
 	}, name);
 }
 /**
-* Builds the section holding the plugin's own introductory pages.
+* Builds the section for the plugin's introductory pages.
 *
-* @returns A single section listing the built-in pages, in the order they are shown.
+* @returns One section listing the built-in pages.
 */
 function gettingStartedSections() {
 	return [{
@@ -1342,19 +1312,19 @@ function gettingStartedSections() {
 		entries: [{
 			id: "how-to-use-this-handbook",
 			title: "How to use the Handbook",
-			description: "A guide to navigating the Handbook, reading the documentation for each field, and making sense of its examples, hints, and nested structure.",
+			description: "How to find your way around the Handbook, read the documentation for each field, and understand its examples, hints, and subfields.",
 			icon: createSanityIcon(BookTextIcon),
 			render: () => /* @__PURE__ */ jsx(HowToUse, {})
 		}, {
 			id: "document-types",
 			title: "Document Types",
-			description: "An overview of all document types, organized by role. Select a document type to view its fields, descriptions, and examples.",
+			description: "A list of every document type, grouped by role. Select a document type to see its fields, descriptions, and examples.",
 			icon: createSanityIcon(LayoutGridIcon),
 			render: () => /* @__PURE__ */ jsx(DocumentTypesOverview, {})
 		}]
 	}];
 }
-/** Presentation for each callout variant. */
+/** Icon and tone for each callout variant. */
 const presentation = {
 	tip: {
 		icon: LightbulbIcon,
@@ -1442,7 +1412,7 @@ function PortableLink(t0) {
 		children
 	}), $[6] = children, $[7] = props, $[8] = t1, $[9] = t2) : t2 = $[9], t2;
 }
-/** Overrides for a callout body, which takes the card's own text styling and leaves paragraphs unwrapped. */
+/** Overrides for callout text, which uses the card's own text style and doesn't wrap paragraphs. */
 const components$1 = {
 	block: { normal: ({ children }) => /* @__PURE__ */ jsx(Fragment, { children }) },
 	marks: {
@@ -1720,18 +1690,17 @@ function PortableParagraph(props) {
 	}), $[0] = props, $[1] = t0), t0;
 }
 /**
-* Resolves the space around a list, which tightens once the list is nested inside another.
+* Works out the vertical space around a list, which is smaller for nested lists.
 *
-* @param level - Nesting depth of the list, counted from one.
-* @returns The vertical space in pixels.
+* @param level - Nesting depth, starting at 1.
+* @returns The space in pixels.
 */
 function listSpacing(level) {
 	return level > 1 ? contentSpacing.nestedList : contentSpacing.list;
 }
 /**
-* Component rendered for each block style, mark, and embedded type a guide's rich text can hold.
-* The marks and list items left out are deliberate — the library's own defaults already render them
-* as the surrounding text.
+* Components for each block style, mark, and embedded type in a guide. Marks and list items not listed
+* here are left to the library's defaults on purpose.
 */
 const components = {
 	block: {
@@ -1777,10 +1746,10 @@ const components = {
 	}
 };
 /**
-* Adapts a block component to what Portable Text renders an embedded type with, narrowing the props
-* to the block's own value. The rendering props the library also passes would otherwise reach the DOM.
+* Wraps a block component for Portable Text, passing only the block's value. Otherwise the library's
+* other props would reach the DOM.
 *
-* @param Component - Component rendering the block.
+* @param Component - The block component.
 * @returns A component Portable Text can render the type with.
 */
 function blockRenderer(Component) {
@@ -1855,15 +1824,15 @@ function BookOpenTextIcon(props) {
 	}), $[6] = props, $[7] = t6), t6;
 }
 /**
-* Builds a section for each guide group authored in the dataset.
+* Builds a sidebar section for each guide group.
 *
-* @param handbook - Handbook singleton holding the authored guide groups.
-* @returns One section per group, holding an entry per guide.
+* @param handbook - The Handbook document.
+* @returns One section per group, with an entry per published guide.
 */
 function guidesSections(handbook) {
-	return handbook.groups.map(({ title, guides }) => ({
+	return (handbook.groups ?? []).map(({ title, guides }) => ({
 		title,
-		entries: guides.map((guide) => ({
+		entries: (guides ?? []).filter((guide) => isDefined(guide.title)).map((guide) => ({
 			id: guide._key,
 			title: guide.title,
 			description: guide.description,
@@ -1873,17 +1842,17 @@ function guidesSections(handbook) {
 	}));
 }
 /**
-* Composes every page the Handbook shows, in sidebar order.
+* Lists every page in the Handbook, in sidebar order.
 *
-* @returns Sections from the built-in pages, the configured document roles, and the authored guides.
+* @returns The built-in pages, the configured document roles, and the guide groups, as sections.
 */
 function useSections() {
-	let $ = c(4), { roles, handbook, loading } = useHandbookContext(), t0;
-	return $[0] !== handbook || $[1] !== loading || $[2] !== roles ? (t0 = [
+	let $ = c(3), { roles, handbook } = useHandbookContext(), t0;
+	return $[0] !== handbook || $[1] !== roles ? (t0 = [
 		...gettingStartedSections(),
 		...documentTypesSections(roles),
-		...loading || !isDefined(handbook) ? [] : guidesSections(handbook)
-	], $[0] = handbook, $[1] = loading, $[2] = roles, $[3] = t0) : t0 = $[3], t0;
+		...isDefined(handbook) ? guidesSections(handbook) : []
+	], $[0] = handbook, $[1] = roles, $[2] = t0) : t0 = $[2], t0;
 }
 function Content(props) {
 	let $ = c(18), { activeTab } = useHandbookContext(), sections = useSections(), T0, t0, t1, t2, t3, t4;
@@ -2094,23 +2063,23 @@ function HandbookTool(t0) {
 		children: t7
 	}), $[7] = options, $[8] = t7, $[9] = t8) : t8 = $[9], t8;
 }
-/** Editors the plugin was configured with, so the Structure helper need not be handed them a second time. */
+/** Editors from the plugin configuration, so the structure helper doesn't need them passed again. */
 let configuredEditors;
 /**
-* Records the editors a plugin instance was configured with. A Studio running more than one workspace
-* keeps only the list from the workspace configured last, so those cases pass the list explicitly.
+* Stores the editors from the plugin configuration. A Studio with several workspaces keeps only the last
+* workspace's list, so pass the list explicitly there.
 *
-* @param editors - Email addresses permitted to edit Handbook documents.
+* @param editors - Email addresses of the editors.
 */
 function setConfiguredEditors(editors) {
 	configuredEditors = editors;
 }
 /**
-* Checks whether an email address is permitted to edit, treating an absent list as unrestricted access.
+* Checks whether an email address belongs to an editor. Without an editors list, everyone is an editor.
 *
-* @param editors - Email addresses permitted to edit, defaulting to the configured list.
+* @param editors - Email addresses of the editors, defaulting to the configured list.
 * @param email - The email address to check.
-* @returns Whether the email is permitted to edit.
+* @returns Whether the address belongs to an editor.
 */
 function isPermittedEditor(editors, email) {
 	let permitted = editors ?? configuredEditors;
@@ -2208,7 +2177,7 @@ const linkAnnotation = defineArrayMember({
 		name: "href",
 		type: "url",
 		title: "URL",
-		description: "Web address destination for this link. Supports http, https, mailto, and tel schemes.",
+		description: "Web address to link to. Use http, https, mailto, or tel.",
 		validation: (rule) => rule.uri({ scheme: [
 			"http",
 			"https",
@@ -2220,7 +2189,7 @@ const linkAnnotation = defineArrayMember({
 	name: calloutTypeName,
 	type: "object",
 	title: "Callout",
-	description: "Highlighted message block drawing attention to tips, supplementary information, or warnings.",
+	description: "Highlighted tip, note, or warning.",
 	icon: createSanityIcon(MessageCircleIcon),
 	components: { preview: CalloutPreview },
 	preview: {
@@ -2240,7 +2209,7 @@ const linkAnnotation = defineArrayMember({
 	fields: [defineField({
 		name: "variant",
 		type: "string",
-		description: "Visual style and intent of the callout.",
+		description: "Kind of callout, which sets its icon and color.",
 		initialValue: "tip",
 		validation: (rule) => rule.required(),
 		options: {
@@ -2264,7 +2233,7 @@ const linkAnnotation = defineArrayMember({
 	}), defineField({
 		name: "body",
 		type: "array",
-		description: "Content displayed inside the callout. Supports inline formatting and links.",
+		description: "Text inside the callout, with inline formatting and links.",
 		of: [defineArrayMember({
 			name: "block",
 			type: "block",
@@ -2330,7 +2299,7 @@ const codeType = defineType({
 	name: codeTypeName,
 	type: "object",
 	title: "Code",
-	description: "Syntax-highlighted code block with language selection.",
+	description: "Code block with syntax highlighting.",
 	icon: createSanityIcon(CodeIcon),
 	components: { preview: CodePreview },
 	preview: { select: {
@@ -2340,11 +2309,11 @@ const codeType = defineType({
 	fields: [defineField({
 		name: "code",
 		type: "text",
-		description: "The source code to display."
+		description: "Code to display."
 	}), defineField({
 		name: "language",
 		type: "string",
-		description: "Programming language used for syntax highlighting.",
+		description: "Language used for syntax highlighting.",
 		options: { list: [
 			{
 				title: "CSS",
@@ -2415,7 +2384,7 @@ const horizontalRuleType = defineType({
 	name: horizontalRuleTypeName,
 	type: "object",
 	title: "Horizontal Rule",
-	description: "Visual divider between sections of content.",
+	description: "Divider between sections.",
 	icon: createSanityIcon(SeparatorHorizontalIcon),
 	components: { preview: HorizontalRulePreview },
 	preview: { prepare() {
@@ -2424,7 +2393,7 @@ const horizontalRuleType = defineType({
 	fields: [defineField({
 		name: "style",
 		type: "string",
-		description: "Reserved. A horizontal rule carries no authored content.",
+		description: "Unused placeholder field.",
 		hidden: !0
 	})]
 });
@@ -2491,19 +2460,19 @@ const imageType = defineType({
 			name: "asset",
 			type: "image",
 			title: "Image",
-			description: "Upload or select an image from the media library.",
+			description: "Image to show.",
 			options: { hotspot: !0 }
 		}),
 		defineField({
 			name: "caption",
 			type: "string",
-			description: "Caption text displayed below the image, such as a credit or a note."
+			description: "Text shown below the image, such as a credit."
 		}),
 		defineField({
 			name: "alt",
 			type: "string",
 			title: "Alternative Text",
-			description: "Describes what the image shows for people who cannot see it. Don't repeat the caption here."
+			description: "Description of the image for people who can't see it. Don't repeat the caption."
 		})
 	]
 });
@@ -2567,12 +2536,12 @@ const videoType = defineType({
 		name: "asset",
 		type: "file",
 		title: "Video",
-		description: "Upload or select a video from the media library.",
+		description: "Video to show.",
 		options: { accept: "video/*" }
 	}), defineField({
 		name: "caption",
 		type: "string",
-		description: "Caption text displayed below the video, such as a credit or a note."
+		description: "Text shown below the video, such as a credit."
 	})]
 });
 function ListItemStyle(t0) {
@@ -2586,11 +2555,10 @@ function ListItemStyle(t0) {
 	}), $[1] = children, $[2] = t2), t2;
 }
 /**
-* Creates the Portable Text content field for Handbook guides, offering the built-in blocks alongside
-* any a consumer registered.
+* Creates the guide content field, offering the built-in blocks and any custom ones.
 *
-* @param customBlocks - Custom block definitions registered by the consumer.
-* @returns A field definition for the guide content array.
+* @param customBlocks - Custom blocks added by the site.
+* @returns The content field.
 */
 function createGuideContentField(customBlocks = []) {
 	return defineField({
@@ -2678,43 +2646,33 @@ function createGuideContentField(customBlocks = []) {
 	});
 }
 /**
-* Creates the document type a single guide is authored as, with its content field offering the
-* built-in blocks alongside any a consumer registered.
+* Creates the guide document type, with a content field offering the built-in blocks and any custom ones.
 *
-* @param customBlocks - Custom block definitions registered by the consumer.
-* @returns A document type definition for Handbook guides.
+* @param customBlocks - Custom blocks added by the site.
+* @returns The guide document type.
 */
 function createGuideType(customBlocks = []) {
 	return defineType({
 		name: guideTypeName,
 		type: "document",
 		title: "Handbook Guide",
-		description: "Handbook page authored with rich text, images, and custom blocks.",
+		description: "Handbook page written in rich text.",
 		icon: createSanityIcon(BookOpenTextIcon),
-		preview: {
-			select: {
-				title: "title",
-				description: "description"
-			},
-			prepare(selection) {
-				let { title, description } = selection;
-				return {
-					title: title ?? "Untitled",
-					subtitle: description
-				};
-			}
-		},
+		preview: { select: {
+			title: "title",
+			subtitle: "description"
+		} },
 		fields: [
 			defineField({
 				name: "title",
 				type: "string",
-				description: "Appears in the Handbook sidebar and as the guide heading.",
+				description: "Title shown in the Handbook sidebar and as the guide heading.",
 				validation: (rule) => rule.required()
 			}),
 			defineField({
 				name: "description",
 				type: "string",
-				description: "Short introduction text displayed below the guide heading."
+				description: "Short introduction shown below the heading."
 			}),
 			createGuideContentField(customBlocks)
 		]
@@ -2748,7 +2706,7 @@ const handbookType = defineType({
 	name: handbookTypeName,
 	type: "document",
 	title: "Handbook",
-	description: "Defines the groups of guides shown in the Handbook sidebar, and the order they appear in.",
+	description: "Groups of guides shown in the Handbook sidebar, in order.",
 	icon: createSanityIcon(BookTextIcon),
 	preview: { prepare() {
 		return { title: "Handbook" };
@@ -2756,21 +2714,21 @@ const handbookType = defineType({
 	fields: [defineField({
 		name: "groups",
 		type: "array",
-		description: "Ordered list of groups displayed in the Handbook sidebar. Each group contains a title and an ordered list of guide references.",
+		description: "Groups of guides shown in the Handbook sidebar, in order. Each group has a title and a list of guides, also in order.",
 		of: [defineArrayMember({
 			name: "group",
 			type: "object",
-			description: "Named section of the Handbook sidebar holding an ordered list of guides.",
+			description: "Sidebar section holding a list of guides.",
 			icon: createSanityIcon(ListPlusIcon),
 			fields: [defineField({
 				name: "title",
 				type: "string",
-				description: "Heading displayed above this group of guides in the sidebar.",
+				description: "Heading shown above the group in the sidebar.",
 				validation: (rule) => rule.required()
 			}), defineField({
 				name: "guides",
 				type: "array",
-				description: "Ordered list of guides within this group. Drag to reorder.",
+				description: "Guides in the group, in order. Drag to reorder.",
 				of: [defineArrayMember({
 					name: "guide",
 					type: "reference",
@@ -2782,16 +2740,17 @@ const handbookType = defineType({
 					title: "title",
 					guide0: "guides.0.title",
 					guide1: "guides.1.title",
-					guide2: "guides.2.title"
+					guide2: "guides.2.title",
+					guide3: "guides.3.title"
 				},
 				prepare(selection) {
-					let { title, guide0, guide1, guide2 } = selection, shown = [
+					let { title, guide0, guide1, guide2, guide3 } = selection, shown = [
 						guide0,
 						guide1,
 						guide2
-					].filter((guide) => isDefined(guide)).slice(0, 2), hasMore = isDefined(guide2);
+					].filter((guide) => isDefined(guide));
 					function formatSubtitle() {
-						return isDefined(shown) ? hasMore ? `${shown.join(", ")}, and others` : shown.join(" and ") : "No guides selected";
+						return isDefined(shown) ? isDefined(guide3) ? `${shown.slice(0, 2).join(", ")}, and others` : new Intl.ListFormat("en-US").format(shown) : "No guides selected";
 					}
 					return {
 						title: title ?? "Group",
@@ -2808,7 +2767,7 @@ const handbookType = defineType({
 		sidebarTitle: sidebarTitle ?? "Handbook",
 		roles,
 		blocks: blocks ?? [],
-		undocumentedFieldMessage: undocumentedFieldMessage ?? "This field has not been documented yet. Contact your development team for guidance."
+		undocumentedFieldMessage: undocumentedFieldMessage ?? "This field isn't documented yet. Ask your development team for guidance."
 	}, guideType = createGuideType(resolved.blocks);
 	return {
 		name: pluginName,
@@ -2844,25 +2803,26 @@ const handbookType = defineType({
 	};
 });
 /**
-* Creates the Structure tool items for Handbook documents, yielding nothing when the current user is
-* not permitted to edit them.
+* Creates Structure tool items for the Handbook documents, or none when the current user can't edit them.
 *
-* @param structureBuilder - The Sanity Structure builder instance.
-* @param context - The Structure context carrying the current user.
-* @param editors - Email addresses permitted to edit, defaulting to the configured list.
-* @returns The list items for the Handbook singleton and the guides list.
+* @param structureBuilder - The structure builder.
+* @param context - The structure context, with the current user.
+* @param editors - Email addresses of the editors, defaulting to the configured list.
+* @returns List items for the Handbook document and the guides list, oldest guide first.
 * @public
 */
 function handbookStructure(structureBuilder, context, editors) {
 	if (!isPermittedEditor(editors, context.currentUser?.email)) return [];
 	let { listItem, document, documentTypeList } = structureBuilder;
-	return [listItem().title("Handbook").icon(createSanityIcon(BookTextIcon)).child(document().id(handbookTypeName).schemaType(handbookTypeName).title("Handbook")), listItem().title("Handbook Guides").icon(createSanityIcon(BookOpenTextIcon)).child(documentTypeList(guideTypeName).title("Handbook Guides"))];
+	return [listItem().title("Handbook").icon(createSanityIcon(BookTextIcon)).child(document().id(handbookTypeName).schemaType(handbookTypeName).title("Handbook")), listItem().title("Handbook Guides").icon(createSanityIcon(BookOpenTextIcon)).child(documentTypeList(guideTypeName).title("Handbook Guides").defaultOrdering([{
+		field: "_createdAt",
+		direction: "asc"
+	}]))];
 }
 /**
-* Checks whether the current user is permitted to edit Handbook content, treating an absent list as
-* unrestricted access.
+* Checks whether the current user can edit Handbook documents. Without an editors list, everyone can.
 *
-* @param editors - Email addresses permitted to edit, defaulting to the configured list.
+* @param editors - Email addresses of the editors, defaulting to the configured list.
 * @returns Whether the current user can edit Handbook documents.
 * @public
 */