@bison-lab/payload-blocks 3.1.0 → 3.3.0

package/dist/index.mjs

@@ -323,21 +323,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
 		}
 	];
 }
@@ -641,6 +647,442 @@ 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
+* the renderer's reader so the two cannot drift: if the validator accepted a
+* value the renderer dropped, the editor would be back to a width that
+* silently does nothing. React-free, because `config.ts` ships from the Node
+* entry.
+*/
+const REM_WIDTH = /^\s*(\d+(?:\.\d+)?)\s*(rem)?\s*$/;
+/** "30" and "30rem" both mean 30rem; anything else is not a width. */
+function remWidth(value) {
+	const match = REM_WIDTH.exec(value ?? "");
+	return match ? `${Number(match[1])}rem` : null;
+}
+//#endregion
+//#region src/blocks/mega-menu/config.ts
+/** The percent tokens a column can take, as Payload stores them. */
+const MEGA_MENU_WIDTHS = [
+	"25",
+	"33",
+	"50",
+	"66",
+	"75",
+	"100"
+];
+/** Twelfths, so 33 and 66 are real thirds and 33 + 33 + 33 is a full row. */
+const TWELFTHS = {
+	"25": 3,
+	"33": 4,
+	"50": 6,
+	"66": 8,
+	"75": 9,
+	"100": 12
+};
+/**
+* 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
+* it), so nothing publishes with a short row. Skipped when Advanced has custom
+* widths on.
+*/
+const validateColumnWidths = (value, options) => {
+	const limits = rowLimits(value, options);
+	if (limits !== true) return limits;
+	if (options.siblingData?.customWidths || !value?.length) return true;
+	const twelfths = value.reduce((sum, row) => sum + TWELFTHS[row?.width ?? "100"], 0);
+	if (twelfths === 12) return true;
+	return `The columns add up to ${Math.round(twelfths / 12 * 100)}%. They need to add up to 100%.`;
+};
+/**
+* The row `levels` segments above the field at `path`, read off the whole
+* document. A condition on a link needs its section; a condition on a column
+* needs its panel. `data` carries the full form, so the path is enough.
+*/
+function ancestor(data, path, levels) {
+	let node = data;
+	for (const segment of path.slice(0, path.length - levels)) {
+		if (node === null || typeof node !== "object") return void 0;
+		node = node[segment];
+	}
+	return node !== null && typeof node === "object" ? node : void 0;
+}
+/** `links.N.variant` → its section, three segments up. */
+const whenSectionFeatured = (data, _siblingData, { path }) => ancestor(data, path, 3)?.display === "featured";
+/** A featured link's glyph comes from its variant, so `icon` is a list link's field. */
+const unlessSectionFeatured = (data, siblingData, ctx) => !whenSectionFeatured(data, siblingData, ctx);
+/** The renderer would fall back to the preset silently; the editor should hear it here instead. */
+const validateRemWidth = (value) => !value || remWidth(value) !== null ? true : "Type a width in rem, like 30 or 30rem.";
+/** `columns.N.width` → its panel, three segments up. */
+const whenCustomWidths = (data, _siblingData, { path }) => Boolean(ancestor(data, path, 3)?.customWidths);
+const unlessCustomWidths = (data, siblingData, ctx) => !whenCustomWidths(data, siblingData, ctx);
+function approvedSelect(name, options, admin) {
+	if (!options?.length) return [];
+	return [{
+		name,
+		type: "select",
+		options,
+		admin
+	}];
+}
+function megaMenuBlock({ variants, icons } = {}) {
+	const linkRowFields = [
+		...linkFields({ required: true }),
+		{
+			name: "description",
+			type: "textarea",
+			admin: { description: "Supporting line under the label. Optional." }
+		},
+		...approvedSelect("variant", variants, {
+			description: "The look of this featured link.",
+			condition: whenSectionFeatured
+		}),
+		...approvedSelect("icon", icons, {
+			description: "Glyph shown before a list link. Optional.",
+			condition: unlessSectionFeatured
+		})
+	];
+	return {
+		slug: "megaMenu",
+		interfaceName: "MegaMenuBlock",
+		labels: {
+			singular: "Mega menu",
+			plural: "Mega menus"
+		},
+		fields: [
+			{
+				name: "label",
+				type: "text",
+				required: true
+			},
+			{
+				name: "href",
+				type: "text",
+				admin: { description: "The landing page this menu opens. Optional: a trigger with no landing page is allowed." }
+			},
+			{
+				name: "panel",
+				type: "group",
+				fields: [
+					{
+						name: "maxWidth",
+						type: "select",
+						defaultValue: "standard",
+						options: [
+							{
+								label: "Narrow",
+								value: "narrow"
+							},
+							{
+								label: "Standard",
+								value: "standard"
+							},
+							{
+								label: "Wide",
+								value: "wide"
+							}
+						]
+					},
+					{
+						name: "columns",
+						type: "array",
+						required: true,
+						minRows: 1,
+						maxRows: 4,
+						defaultValue: emptyRows(1),
+						labels: {
+							singular: "Column",
+							plural: "Columns"
+						},
+						validate: validateColumnWidths,
+						admin: { components: { Field: MIN_ROWS_ARRAY_FIELD } },
+						fields: [
+							{
+								name: "width",
+								type: "select",
+								defaultValue: "100",
+								options: MEGA_MENU_WIDTHS.map((value) => ({
+									label: `${value}%`,
+									value
+								})),
+								admin: { condition: unlessCustomWidths }
+							},
+							{
+								name: "customWidth",
+								type: "text",
+								admin: {
+									description: "A CSS width: 13rem, 1fr, minmax(0, 1fr)",
+									condition: whenCustomWidths
+								}
+							},
+							{
+								name: "divider",
+								type: "checkbox",
+								label: "Draw a line on the left of this column",
+								defaultValue: false
+							},
+							{
+								name: "sections",
+								type: "array",
+								labels: {
+									singular: "Section",
+									plural: "Sections"
+								},
+								fields: [
+									{
+										name: "eyebrow",
+										type: "text",
+										admin: { description: "Small heading above this group; leave empty for none" }
+									},
+									{
+										name: "display",
+										type: "select",
+										defaultValue: "list",
+										options: [{
+											label: "Featured",
+											value: "featured"
+										}, {
+											label: "List",
+											value: "list"
+										}]
+									},
+									{
+										name: "hideDescriptionsOnMobile",
+										type: "checkbox",
+										label: "Hide descriptions on mobile",
+										defaultValue: true
+									},
+									{
+										name: "links",
+										type: "array",
+										labels: {
+											singular: "Link",
+											plural: "Links"
+										},
+										fields: linkRowFields
+									}
+								]
+							}
+						]
+					},
+					{
+						name: "footer",
+						type: "group",
+						admin: { description: "The strip under the columns. Leave both empty for no footer." },
+						fields: [linkField({
+							name: "overview",
+							label: "Overview link",
+							admin: { description: "The section's own landing page, so it stays reachable from the bar." }
+						}), linkField({
+							name: "cta",
+							label: "Call to action"
+						})]
+					},
+					{
+						type: "collapsible",
+						label: "Advanced",
+						admin: { initCollapsed: true },
+						fields: [{
+							name: "customWidths",
+							type: "checkbox",
+							label: "Type a CSS width for each column instead of choosing a percentage",
+							defaultValue: false
+						}, {
+							name: "customMaxWidth",
+							type: "text",
+							validate: validateRemWidth,
+							admin: { description: "Panel width in rem, e.g. 30. Leave empty to use the preset above." }
+						}]
+					}
+				]
+			}
+		]
+	};
+}
+/** A plain bar item: label and destination, nothing to open. */
+const LinkBlock = {
+	slug: "navLink",
+	interfaceName: "NavLinkBlock",
+	labels: {
+		singular: "Link",
+		plural: "Links"
+	},
+	fields: linkFields({ required: true })
+};
+//#endregion
 //#region src/media.ts
 function isMediaDoc(value) {
 	return typeof value === "object" && value !== null;
@@ -770,6 +1212,143 @@ const heroSample = {
 	}]
 };
 //#endregion
+//#region src/blocks/mega-menu/sample.ts
+/**
+* The options the mega menu sample was written against. A factory block's
+* sample only fits a config built with the same approved values, so a
+* preview builds its block with `megaMenuBlock(megaMenuSampleOptions)`.
+*/
+const megaMenuSampleOptions = {
+	variants: [{
+		label: "Lumbar",
+		value: "lumbar"
+	}, {
+		label: "SI joint",
+		value: "si"
+	}],
+	icons: [{
+		label: "Help",
+		value: "help"
+	}, {
+		label: "Mail",
+		value: "mail"
+	}]
+};
+/**
+* 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.
+*/
+const megaMenuSample = {
+	id: "sample-mega-menu",
+	blockType: "megaMenu",
+	label: "Patients",
+	href: "/patients",
+	panel: {
+		maxWidth: "standard",
+		columns: [{
+			id: "treatment",
+			width: "75",
+			customWidth: "minmax(0, 1fr)",
+			divider: false,
+			sections: [{
+				id: "territories",
+				eyebrow: "Treatment",
+				display: "featured",
+				hideDescriptionsOnMobile: true,
+				links: [{
+					id: "lumbar",
+					label: "Low Back Pain",
+					href: "/patients/low-back-pain",
+					newTab: false,
+					description: "Persistent low back pain from lumbar instability, often with leg pain that limits standing or walking.",
+					variant: "lumbar"
+				}, {
+					id: "si",
+					label: "Hip Pain",
+					href: "/patients/hip-pain",
+					newTab: false,
+					description: "Pain centered on the sacroiliac joint, often worse with sitting or climbing stairs.",
+					variant: "si"
+				}]
+			}]
+		}, {
+			id: "rail",
+			width: "25",
+			customWidth: "13rem",
+			divider: true,
+			sections: [{
+				id: "outcomes",
+				eyebrow: "Patient Outcomes",
+				display: "list",
+				hideDescriptionsOnMobile: true,
+				links: [
+					{
+						id: "stories",
+						label: "Testimonials",
+						href: "/patients/stories",
+						newTab: false
+					},
+					{
+						id: "research",
+						label: "Research",
+						href: "/patients/research",
+						newTab: false
+					},
+					{
+						id: "path",
+						label: "Path to Relief",
+						href: "/patients/path-to-relief",
+						newTab: false
+					}
+				]
+			}, {
+				id: "support",
+				eyebrow: "Support",
+				display: "list",
+				hideDescriptionsOnMobile: false,
+				links: [{
+					id: "faqs",
+					label: "FAQs",
+					href: "/patients/faqs",
+					newTab: false,
+					description: "Short answers to the questions patients ask first.",
+					icon: "help"
+				}, {
+					id: "contact",
+					label: "Contact",
+					href: "https://example.com/contact",
+					newTab: true,
+					icon: "mail"
+				}]
+			}]
+		}],
+		footer: {
+			overview: {
+				label: "All patient resources",
+				href: "/patients",
+				newTab: false
+			},
+			cta: {
+				label: "Find a Doctor",
+				href: "/find-a-doctor",
+				newTab: false
+			}
+		},
+		customWidths: false,
+		customMaxWidth: "42rem"
+	}
+};
+/** A plain bar item. */
+const navLinkSample = {
+	id: "sample-nav-link",
+	blockType: "navLink",
+	label: "Contact",
+	href: "/contact",
+	newTab: false
+};
+//#endregion
 //#region src/blocks/nap/sample.ts
 /**
 * A fictional clinic. `emitJsonLd` is off: the block emits schema.org
@@ -1001,6 +1580,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({
@@ -1098,9 +1721,12 @@ const blockSamples = {
 		minItemsForFade: 6,
 		maxVisibleRows: 2
 	},
-	nap: napSample
+	nap: napSample,
+	statsBand: statsBandSample,
+	megaMenu: megaMenuSample,
+	navLink: navLinkSample
 };
 //#endregion
-export { FaqColumnsBlock, HeroBlock, MIN_ROWS_ARRAY_FIELD, NapBlock, ProcessStepsBlock, RichTextBlock, ShowcasePanelsBlock, TestimonialMasonryBlock, blockSamples, emptyRows, headingFields, imageField, linkField, linkFields, resolveMedia, sampleImage };
+export { FaqColumnsBlock, HeroBlock, LinkBlock, MEGA_MENU_WIDTHS, MIN_ROWS_ARRAY_FIELD, NapBlock, ProcessStepsBlock, RichTextBlock, ShowcasePanelsBlock, StatsBandBlock, TestimonialMasonryBlock, blockSamples, emptyRows, headingFields, imageField, linkField, linkFields, megaMenuBlock, megaMenuSampleOptions, resolveMedia, sampleImage, validateColumnWidths, validateRemWidth };
 
 //# sourceMappingURL=index.mjs.map