@bison-lab/payload-blocks 3.2.0 → 3.4.0

package/dist/index.mjs

@@ -19,30 +19,125 @@ function imageField(overrides = {}) {
 //#endregion
 //#region src/fields/link.ts
 /**
-* The three fields a call to action is made of, unwrapped.
+* The import-map path of the link picker, `LinkField` in
+* `@bison-lab/payload-blocks/admin`.
 *
-* `href` is plain text rather than a relationship to a `pages` row: a block in
-* this package has to work on a site whose page collection is named something
-* else, or which links out more often than in. Resolving an internal reference
-* is the site's job.
+* It sits on the row that holds a link's `type`, `page` and `href`, and
+* replaces those three inputs with one box: type to search published pages,
+* or paste a URL. Referenced here by package specifier, like
+* `MIN_ROWS_ARRAY_FIELD`; a site picks it up with `payload generate:importmap`.
+* Until it does, Payload logs the missing entry and renders the row as
+* nothing (a custom `Field` with no component behind it is an empty element,
+* not the stock fields), so the step is part of adopting this release.
+*/
+const LINK_FIELD = "@bison-lab/payload-blocks/admin#LinkField";
+/**
+* The package's resolver: a published, populated page is `/<slug>`; an
+* external link is its `href` as typed.
+*
+* A page that did not populate is `null`: Payload hands the public read the
+* bare id when the reader may not see the page, which is what an unpublished
+* page looks like from the site. A populated page whose `_status` is `draft`
+* is `null` too, for a read that can see drafts. A row from before links had
+* a `type` is an external link by `linkTypeOf`, here, in the stock fields'
+* conditions and in the picker alike: the site keeps rendering its `href`,
+* the admin shows it as an External chip, and the site's migration to
+* `type: external` only makes the stored row say what every reader already
+* assumes.
+*/
+function resolveLink(link) {
+	if (!link) return null;
+	if (linkTypeOf(link) === "page") {
+		const page = link.page;
+		if (!page || typeof page !== "object") return null;
+		if (page._status === "draft") return null;
+		return page.slug ? `/${page.slug}` : null;
+	}
+	return link.href ? link.href : null;
+}
+/**
+* Which of the two stored destinations a row is using. `type` decides; a row
+* with no `type` yet (saved before links had one) is read by what it holds,
+* an `href` making it external, the same reading `resolveLink` and the picker
+* make, so all three agree on every row.
+*/
+function linkTypeOf(link) {
+	if (link?.type === "external") return "external";
+	if (link?.type === "page") return "page";
+	return link?.href ? "external" : "page";
+}
+const whenPage = (_data, siblingData) => linkTypeOf(siblingData) === "page";
+const whenExternal = (_data, siblingData) => linkTypeOf(siblingData) === "external";
+/**
+* Where a link goes, as stored: `type`, `page` and `href` in one row.
+*
+* The row carries the picker (`LINK_FIELD`), which replaces all three inputs
+* with one box. The stored fields are the website template's shape and stay
+* editable on their own: `page` shows for a page link, `href` for an external
+* one, and `required` binds whichever is active, since Payload skips
+* validation on a field whose condition is false. `page` offers published
+* rows only, and Payload re-checks that on publish, so a page that was
+* unpublished after being picked has to be picked again or republished.
+*/
+function linkDestinationFields({ required = false, pagesCollection = "pages" } = {}) {
+	return [{
+		type: "row",
+		admin: { components: { Field: LINK_FIELD } },
+		fields: [
+			{
+				name: "type",
+				type: "radio",
+				label: "Goes to",
+				defaultValue: "page",
+				options: [{
+					label: "Page",
+					value: "page"
+				}, {
+					label: "URL",
+					value: "external"
+				}],
+				admin: { layout: "horizontal" }
+			},
+			{
+				name: "page",
+				type: "relationship",
+				relationTo: pagesCollection,
+				required,
+				filterOptions: { _status: { equals: "published" } },
+				admin: { condition: whenPage }
+			},
+			{
+				name: "href",
+				type: "text",
+				label: "URL",
+				required,
+				admin: {
+					condition: whenExternal,
+					description: "A full URL (\"https://example.com\"), \"mailto:\" or \"tel:\", or a site path (\"/contact\")."
+				}
+			}
+		]
+	}];
+}
+/**
+* The fields a call to action is made of, unwrapped: the destination row,
+* then the label and the new-tab flag.
 *
 * `newTab` drives `target="_blank"` *and* the matching `rel`, which is why no
 * renderer takes one without the other.
 */
-function linkFields({ required = false, labelFieldLabel = "Label" } = {}) {
+function linkFields({ required = false, labelFieldLabel = "Label", pagesCollection } = {}) {
 	return [
+		...linkDestinationFields({
+			required,
+			pagesCollection
+		}),
 		{
 			name: "label",
 			type: "text",
 			label: labelFieldLabel,
 			required
 		},
-		{
-			name: "href",
-			type: "text",
-			required,
-			admin: { description: "A site path (\"/contact\") or a full URL (\"https://example.com\")." }
-		},
 		{
 			name: "newTab",
 			type: "checkbox",
@@ -323,21 +418,27 @@ const ProcessStepsBlock = {
 * puts the least-optional copy behind a click. The field names match the
 * `@bison-lab/ui` prop names so the renderers stay a pass-through.
 */
-function headingFields({ required = true, eyebrowDescription = "Small label above the heading. Leave empty to hide the row." } = {}) {
+function headingFields({ required = true, eyebrowDescription = "Small label above the heading. Leave empty to hide the row.", condition } = {}) {
+	const when = condition ? { condition } : {};
 	return [
 		{
 			name: "eyebrow",
 			type: "text",
-			admin: { description: eyebrowDescription }
+			admin: {
+				description: eyebrowDescription,
+				...when
+			}
 		},
 		{
 			name: "title",
 			type: "text",
-			required
+			required,
+			admin: when
 		},
 		{
 			name: "description",
-			type: "textarea"
+			type: "textarea",
+			admin: when
 		}
 	];
 }
@@ -389,10 +490,7 @@ const FaqColumnsBlock = {
 					name: "linkText",
 					type: "text"
 				},
-				{
-					name: "href",
-					type: "text"
-				},
+				...linkDestinationFields(),
 				{
 					name: "newTab",
 					type: "checkbox",
@@ -641,6 +739,177 @@ const NapBlock = {
 	]
 };
 //#endregion
+//#region src/fields/row-limits.ts
+/**
+* A custom `validate` replaces Payload's stock array check, so any array
+* with its own rule re-applies the row limits first or `minRows` and
+* `maxRows` stop being enforced. Same messages as the stock check, through
+* the request's translator when the admin supplies one.
+*/
+function rowLimits(value, { minRows, maxRows, required, req }) {
+	const count = value?.length ?? 0;
+	const t = req?.t;
+	if (required && count === 0) return t ? t("validation:required") : "This field is required.";
+	if (minRows && count < minRows) return t ? t("validation:requiresAtLeast", {
+		count: minRows,
+		label: t("general:rows")
+	}) : `This field requires at least ${minRows} rows.`;
+	if (maxRows && count > maxRows) return t ? t("validation:requiresNoMoreThan", {
+		count: maxRows,
+		label: t("general:rows")
+	}) : `This field requires no more than ${maxRows} rows.`;
+	return true;
+}
+//#endregion
+//#region src/blocks/stats-band/config.ts
+/**
+* The rule on `wide`: on phones the band is two per row, so only an odd
+* count has a stat on a row of its own, only one stat can take it, and it
+* has to be a stat that starts a row (the 1st, 3rd or 5th), since a full-row
+* cell beside another cell would leave a hole. The array's own `validate`,
+* so the editor sees the message as they build, and Payload runs it again on
+* publish.
+*/
+const validateWideFlag = (value, options) => {
+	const limits = rowLimits(value, options);
+	if (limits !== true) return limits;
+	const rows = value ?? [];
+	const wide = rows.flatMap((row, i) => row?.wide ? [i] : []);
+	if (wide.length > 1) return "Only one stat can be full width on phones.";
+	if (wide.length === 0) return true;
+	if (rows.length % 2 === 0) return "Full width on phones only applies to an odd number of stats. With an even count every row is already full.";
+	if (wide[0] % 2 !== 0) return "Only a stat that starts a phone row can be full width: the 1st, 3rd or 5th. Move it up or down one place, or flag another.";
+	return true;
+};
+/**
+* An overlapping band is headless: it floats across the seam as a card, and a
+* heading pulled up into the block above would land on the wrong surface.
+* The heading fields disappear from the admin the moment `overlap` is on,
+* and the renderer ignores them if they were filled in first.
+*/
+const unlessOverlap = (_data, siblingData) => !siblingData?.overlap;
+/**
+* A strip of figures: the facts a visitor should take in at a glance.
+*
+* The count, the order and the desktop column count are the editor's. The
+* phone and tablet layouts are the library's: two per row and three per row,
+* with `wide` naming the one stat that takes a full phone row when the count
+* is odd.
+*/
+const StatsBandBlock = {
+	slug: "statsBand",
+	interfaceName: "StatsBandBlock",
+	labels: {
+		singular: "Stats Band",
+		plural: "Stats Bands"
+	},
+	fields: [
+		...headingFields({
+			required: false,
+			eyebrowDescription: "Small label above the heading. The heading and eyebrow are optional; without them the band stands alone.",
+			condition: unlessOverlap
+		}),
+		{
+			name: "items",
+			type: "array",
+			required: true,
+			minRows: 2,
+			maxRows: 6,
+			defaultValue: emptyRows(2),
+			labels: {
+				singular: "Stat",
+				plural: "Stats"
+			},
+			admin: { components: { Field: MIN_ROWS_ARRAY_FIELD } },
+			validate: validateWideFlag,
+			fields: [
+				{
+					name: "value",
+					type: "text",
+					required: true,
+					admin: { description: "The figure, as it should read: \"98%\", \"12,000+\", \"L1–S1\"." }
+				},
+				{
+					name: "label",
+					type: "textarea",
+					required: true
+				},
+				{
+					name: "href",
+					type: "text",
+					admin: { description: "Optional. Makes the whole stat a link: a site path (\"/outcomes\") or a full URL." }
+				},
+				{
+					name: "wide",
+					type: "checkbox",
+					label: "Full width on phones",
+					defaultValue: false,
+					admin: { description: "Phones show two per row. With an odd number of stats, this one takes a row to itself. Only the 1st, 3rd or 5th stat can." }
+				}
+			]
+		},
+		{
+			name: "columns",
+			type: "select",
+			defaultValue: "4",
+			options: [
+				{
+					label: "2",
+					value: "2"
+				},
+				{
+					label: "3",
+					value: "3"
+				},
+				{
+					label: "4",
+					value: "4"
+				},
+				{
+					label: "5",
+					value: "5"
+				},
+				{
+					label: "6",
+					value: "6"
+				}
+			],
+			admin: { description: "From large screens up, and never more than there are stats. Phones show two per row and tablets three." }
+		},
+		{
+			name: "tone",
+			type: "select",
+			defaultValue: "card",
+			options: [{
+				label: "Card (bordered, raised)",
+				value: "card"
+			}, {
+				label: "Plain (dividers only)",
+				value: "plain"
+			}]
+		},
+		{
+			name: "align",
+			type: "select",
+			defaultValue: "start",
+			options: [{
+				label: "Left",
+				value: "start"
+			}, {
+				label: "Centred",
+				value: "center"
+			}]
+		},
+		{
+			name: "overlap",
+			type: "checkbox",
+			label: "Float over the seam with the block above",
+			defaultValue: false,
+			admin: { description: "The band sits across the join between the block above and the block below. Both make room for it automatically. A floating band is headless: the heading fields above are hidden while this is on." }
+		}
+	]
+};
+//#endregion
 //#region src/blocks/mega-menu/rem-width.ts
 /**
 * The one rule for a typed panel width, shared by the config's validator and
@@ -676,25 +945,6 @@ const TWELFTHS = {
 	"100": 12
 };
 /**
-* A custom `validate` replaces Payload's stock array check, so the row limits
-* are re-applied here or five columns would pass. Same messages as the stock
-* check, through the request's translator when the admin supplies one.
-*/
-function rowLimits(value, { minRows, maxRows, required, req }) {
-	const count = value?.length ?? 0;
-	const t = req?.t;
-	if (required && count === 0) return t ? t("validation:required") : "This field is required.";
-	if (minRows && count < minRows) return t ? t("validation:requiresAtLeast", {
-		count: minRows,
-		label: t("general:rows")
-	}) : `This field requires at least ${minRows} rows.`;
-	if (maxRows && count > maxRows) return t ? t("validation:requiresNoMoreThan", {
-		count: maxRows,
-		label: t("general:rows")
-	}) : `This field requires no more than ${maxRows} rows.`;
-	return true;
-}
-/**
 * The rule on `columns`: read as fractions, the widths must total 100%. It is
 * the array's own `validate`, so the editor sees the message as they build,
 * and Payload runs field validation again on publish (only draft saves skip
@@ -990,6 +1240,7 @@ const faqColumnsSample = {
 	cta: {
 		title: "Still have questions?",
 		linkText: "Call the front desk",
+		type: "external",
 		href: "tel:+13035550142",
 		newTab: false
 	},
@@ -1044,12 +1295,19 @@ const heroSample = {
 		alt: "A bright, open treatment room"
 	}),
 	links: [{
+		type: "page",
+		page: {
+			id: "sample-page-book",
+			title: "Book an assessment",
+			slug: "book",
+			_status: "published"
+		},
 		label: "Book an assessment",
-		href: "/book",
 		newTab: false
 	}, {
-		label: "See our approach",
+		type: "external",
 		href: "https://example.com/approach",
+		label: "See our approach",
 		newTab: true
 	}]
 };
@@ -1080,7 +1338,10 @@ const megaMenuSampleOptions = {
 * Spinal Simplicity's Patients panel as a saved row: two featured territories
 * in a 75% column, two rail sections in a divided 25% column, overview and
 * CTA. Every field is set at least once; the Advanced fields are set but off,
-* so the percent widths are what renders.
+* so the percent widths are what renders. Most links are site paths typed as
+* external links; Testimonials and the overview are page links carried
+* inline, as `depth: 1` would populate them, so the preview needs no pages
+* collection.
 */
 const megaMenuSample = {
 	id: "sample-mega-menu",
@@ -1102,6 +1363,7 @@ const megaMenuSample = {
 				links: [{
 					id: "lumbar",
 					label: "Low Back Pain",
+					type: "external",
 					href: "/patients/low-back-pain",
 					newTab: false,
 					description: "Persistent low back pain from lumbar instability, often with leg pain that limits standing or walking.",
@@ -1109,6 +1371,7 @@ const megaMenuSample = {
 				}, {
 					id: "si",
 					label: "Hip Pain",
+					type: "external",
 					href: "/patients/hip-pain",
 					newTab: false,
 					description: "Pain centered on the sacroiliac joint, often worse with sitting or climbing stairs.",
@@ -1129,18 +1392,26 @@ const megaMenuSample = {
 					{
 						id: "stories",
 						label: "Testimonials",
-						href: "/patients/stories",
+						type: "page",
+						page: {
+							id: "sample-page-stories",
+							title: "Testimonials",
+							slug: "patients/stories",
+							_status: "published"
+						},
 						newTab: false
 					},
 					{
 						id: "research",
 						label: "Research",
+						type: "external",
 						href: "/patients/research",
 						newTab: false
 					},
 					{
 						id: "path",
 						label: "Path to Relief",
+						type: "external",
 						href: "/patients/path-to-relief",
 						newTab: false
 					}
@@ -1153,6 +1424,7 @@ const megaMenuSample = {
 				links: [{
 					id: "faqs",
 					label: "FAQs",
+					type: "external",
 					href: "/patients/faqs",
 					newTab: false,
 					description: "Short answers to the questions patients ask first.",
@@ -1160,6 +1432,7 @@ const megaMenuSample = {
 				}, {
 					id: "contact",
 					label: "Contact",
+					type: "external",
 					href: "https://example.com/contact",
 					newTab: true,
 					icon: "mail"
@@ -1169,11 +1442,18 @@ const megaMenuSample = {
 		footer: {
 			overview: {
 				label: "All patient resources",
-				href: "/patients",
+				type: "page",
+				page: {
+					id: "sample-page-patients",
+					title: "Patients",
+					slug: "patients",
+					_status: "published"
+				},
 				newTab: false
 			},
 			cta: {
 				label: "Find a Doctor",
+				type: "external",
 				href: "/find-a-doctor",
 				newTab: false
 			}
@@ -1187,6 +1467,7 @@ const navLinkSample = {
 	id: "sample-nav-link",
 	blockType: "navLink",
 	label: "Contact",
+	type: "external",
 	href: "/contact",
 	newTab: false
 };
@@ -1422,6 +1703,50 @@ const showcasePanelsSample = {
 	defaultActiveIndex: 0
 };
 //#endregion
+//#region src/blocks/stats-band/sample.ts
+/**
+* Four figures, the count the strip was designed around: one row on a
+* desktop, two by two on a tablet and a phone. `wide` is set (to `false`) so
+* the preview exercises the field, and an even count is where it is ignored.
+* `overlap` is off so the heading shows: a floating band is headless, and a
+* preview page has no hero for it to float over.
+*/
+const statsBandSample = {
+	id: "sample-stats-band",
+	blockType: "statsBand",
+	eyebrow: "At a glance",
+	title: "The clinic in numbers",
+	description: "What a year looks like across our two rooms, counted from the front desk rather than estimated.",
+	items: [
+		{
+			id: "sample-stat-pain",
+			value: "94%",
+			label: "of patients report less pain by their sixth session.",
+			href: "/outcomes",
+			wide: false
+		},
+		{
+			id: "sample-stat-visits",
+			value: "4,200+",
+			label: "appointments a year across two treatment rooms."
+		},
+		{
+			id: "sample-stat-wait",
+			value: "15 min",
+			label: "average wait from the front desk to the treatment room."
+		},
+		{
+			id: "sample-stat-years",
+			value: "12",
+			label: "years in the same building, on the same street."
+		}
+	],
+	columns: "4",
+	tone: "card",
+	align: "start",
+	overlap: false
+};
+//#endregion
 //#region src/blocks/testimonial-masonry/sample.ts
 function avatar(name) {
 	return sampleImage({
@@ -1512,18 +1837,20 @@ const blockSamples = {
 			}
 		],
 		link: {
-			label: "Read every review",
+			type: "external",
 			href: "https://example.com/reviews",
+			label: "Read every review",
 			newTab: true
 		},
 		minItemsForFade: 6,
 		maxVisibleRows: 2
 	},
 	nap: napSample,
+	statsBand: statsBandSample,
 	megaMenu: megaMenuSample,
 	navLink: navLinkSample
 };
 //#endregion
-export { FaqColumnsBlock, HeroBlock, LinkBlock, MEGA_MENU_WIDTHS, MIN_ROWS_ARRAY_FIELD, NapBlock, ProcessStepsBlock, RichTextBlock, ShowcasePanelsBlock, TestimonialMasonryBlock, blockSamples, emptyRows, headingFields, imageField, linkField, linkFields, megaMenuBlock, megaMenuSampleOptions, resolveMedia, sampleImage, validateColumnWidths, validateRemWidth };
+export { FaqColumnsBlock, HeroBlock, LINK_FIELD, LinkBlock, MEGA_MENU_WIDTHS, MIN_ROWS_ARRAY_FIELD, NapBlock, ProcessStepsBlock, RichTextBlock, ShowcasePanelsBlock, StatsBandBlock, TestimonialMasonryBlock, blockSamples, emptyRows, headingFields, imageField, linkDestinationFields, linkField, linkFields, linkTypeOf, megaMenuBlock, megaMenuSampleOptions, resolveLink, resolveMedia, sampleImage, validateColumnWidths, validateRemWidth };
 
 //# sourceMappingURL=index.mjs.map