simple-module-pagebuilder 0.0.1__py3-none-any.whl

pagebuilder/components/widgets/_internal/rich-text.tsx

@@ -0,0 +1,243 @@
+import { type CSSProperties, Fragment, type ReactNode } from 'react';
+import {
+  type MarkdownBlock,
+  parseInlineTokens,
+  parseMarkdownBlocks,
+} from '../../../utils/markdown';
+import { cn } from '../../../utils/widgetUtils';
+
+// `[label](href)`. Split first, so a link's label can still carry the emphasis
+// markers the inline tokenizer understands ("[**Datenschutz**](/x)").
+//
+// The href allows ONE level of balanced parentheses, because a naive `[^)]+`
+// stops at the first `)` and silently truncates URLs that legitimately contain
+// them (Wikipedia's `..._(disambiguation)`), producing a broken href AND
+// leaking the remainder onto the page as stray literal text. Anything the
+// pattern can't parse falls through unchanged and renders as literal text, so
+// malformed input is always visible rather than dropped.
+const LINK_PATTERN = /(\[[^\]]+\]\((?:[^\s()]|\([^\s()]*\))+\))/g;
+
+// `<strong>`'s UA default `font-weight: bolder` is RELATIVE — inside
+// `font-light` (300) copy it computes to 400 and the bold is invisible. An
+// explicit weight keeps `**bold**` legible everywhere; `bold` (700) matches
+// what normal-weight body copy already computed, and tenants can tune it.
+const DEFAULT_STRONG_STYLE: CSSProperties = {
+  fontWeight: 'var(--pb-strong-weight, bold)' as CSSProperties['fontWeight'],
+};
+
+export type RichTextOptions = {
+  /**
+   * Render `[label](href)` as real anchors (default). Pass `false` where the
+   * output already lives inside an interactive element (`<a>`, `<button>`,
+   * `<summary>`) — nested anchors are invalid HTML and browsers split them.
+   *
+   * With `false` a link renders as its LABEL TEXT and the href is DROPPED
+   * silently. That is the only sane rendering inside an anchor, but it means
+   * body-copy call sites (card bodies, action-list descriptions, FAQ answers
+   * that live inside a link) cannot carry their own links — prefer moving
+   * such copy outside the interactive element if the destination matters.
+   * Those fields say "links not supported here" in their Puck label.
+   *
+   * Either way links are split out before emphasis is tokenized, so emphasis
+   * that STRADDLES a link (`**bold [x](/y) more**`) can't pair up and its
+   * markers stay literal. Wrap the emphasis inside the label instead.
+   */
+  allowLinks?: boolean;
+  /** Override the `<em>` produced by `*x*` (AccentText's tenant accent). */
+  renderEm?: (content: string, key: string) => ReactNode;
+  /**
+   * Override the `<strong>` produced by `**x**`. Display headings need this:
+   * a bare `<strong>`'s `font-weight: bolder` is RELATIVE, so inside a
+   * `font-light` (300) heading it computes to 400 and looks unchanged.
+   */
+  renderStrong?: (content: ReactNode, key: string) => ReactNode;
+};
+
+function renderEmphasis(text: string, keyPrefix: string, opts?: RichTextOptions): ReactNode[] {
+  const em = opts?.renderEm ?? ((content: string, key: string) => <em key={key}>{content}</em>);
+  const strong =
+    opts?.renderStrong ??
+    ((content: ReactNode, key: string) => (
+      <strong key={key} style={DEFAULT_STRONG_STYLE}>
+        {content}
+      </strong>
+    ));
+  return parseInlineTokens(text).map((token, i) => {
+    const key = `${keyPrefix}-${i}`;
+    if (token.type === 'strongem') return strong(em(token.content, `${key}-em`), key);
+    if (token.type === 'strong') return strong(token.content, key);
+    if (token.type === 'em') return em(token.content, key);
+    if (token.type === 'code')
+      return (
+        // The text colour is explicit, never inherited: on an inverted
+        // surface (hero, colored CTA band) the inherited colour is white,
+        // which on this light chip is invisible (1.1:1 contrast). Kept as
+        // a light/dark class pair rather than a `--pb-*` token because one
+        // token cannot carry both themes' values.
+        <code
+          key={key}
+          className="rounded bg-gray-100 text-gray-800 dark:bg-gray-800 dark:text-gray-100 px-1.5 py-0.5 text-sm font-mono"
+        >
+          {token.content}
+        </code>
+      );
+    return token.content;
+  });
+}
+
+/**
+ * Editor copy is not fully trusted (ContentEditors can write these fields),
+ * so only well-known schemes and scheme-less (relative / anchor) hrefs become
+ * anchors — `javascript:` & co. fall through and render as literal text,
+ * visible rather than executable.
+ */
+function isSafeHref(href: string): boolean {
+  const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(href);
+  if (!scheme) return true;
+  return ['http', 'https', 'mailto', 'tel'].includes(scheme[1].toLowerCase());
+}
+
+/**
+ * Inline markdown → ReactNodes, with links.
+ *
+ * The shared `parseInlineTokens` covers emphasis/code only, so `[x](y)` used to
+ * render as literal text everywhere it was accepted. Anchors carry
+ * `--pb-prose-link-color` so a tenant can colour body links (BioGarden's Figma
+ * uses the brand purple) without restyling every link on the page.
+ */
+export function renderRichText(
+  text: string | undefined | null,
+  opts?: RichTextOptions,
+): ReactNode[] {
+  // Legacy Puck JSON saved before a field existed passes undefined where the
+  // prop type says string; `{prop}` rendered nothing, so render nothing —
+  // don't let one missing field throw and blank the whole page.
+  if (!text) return [];
+  return collapse(renderRichTextNodes(text, opts));
+}
+
+/**
+ * Multi-node output collapses into ONE `<span>`: many render sites are flex
+ * containers (`inline-flex gap-2` labels, `justify-between` summaries), where
+ * each node would otherwise become its own flex item and `gap` would scatter
+ * the fragments. Plain text stays a bare string — single-node output is
+ * returned as-is, so unmarked copy renders byte-identically to before.
+ */
+function collapse(nodes: ReactNode[]): ReactNode[] {
+  if (nodes.length <= 1) return nodes;
+  return [<span key="rt">{nodes}</span>];
+}
+
+function renderRichTextNodes(text: string, opts?: RichTextOptions): ReactNode[] {
+  const linksAllowed = opts?.allowLinks !== false;
+  const out: ReactNode[] = [];
+  const parts = text.split(LINK_PATTERN);
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (!part) continue;
+    const match = /^\[([^\]]+)\]\(((?:[^\s()]|\([^\s()]*\))+)\)$/.exec(part);
+    if (match && isSafeHref(match[2])) {
+      const [, label, href] = match;
+      // Inside an `<a>`/`<button>`/`<summary>` an anchor can't be nested, so
+      // keep the label (emphasis and all) and drop the href — showing the
+      // raw `[label](href)` markup reads as broken copy to editors.
+      if (!linksAllowed) {
+        out.push(...renderEmphasis(label, `u-${i}`, opts));
+        continue;
+      }
+      // Scheme-relative `//host/...` is off-site too — it must get the
+      // same new-tab + noopener treatment as absolute http(s) links.
+      const external = /^(?:https?:)?\/\//.test(href);
+      out.push(
+        <a
+          key={`l-${i}`}
+          href={href}
+          className="underline underline-offset-2 text-[color:var(--pb-prose-link-color,inherit)]"
+          {...(external ? { target: '_blank', rel: 'noopener noreferrer' } : {})}
+        >
+          {renderEmphasis(label, `l-${i}`, opts)}
+        </a>,
+      );
+      continue;
+    }
+    out.push(...renderEmphasis(part, `t-${i}`, opts));
+  }
+  return out;
+}
+
+export type RichTextBlockProps = {
+  text: string | undefined;
+  className?: string;
+  style?: CSSProperties;
+};
+
+/**
+ * Block-level light markdown for `textarea` widget fields: blank-line
+ * paragraphs, `- ` bullet lists, and everything `renderRichText` does inline.
+ *
+ * Single-paragraph content (the common case) renders the same `<p>` the
+ * widget rendered before — zero DOM/visual change for plain text. Multi-block
+ * content wraps in a `<div>` carrying the caller's className/style so the
+ * widget's spacing and typography still apply.
+ *
+ * Heading markers (`#`) are demoted to bold paragraphs on purpose: widget
+ * copy must not inject `<h1>`–`<h3>` and break the page's real heading
+ * hierarchy — full headings stay the job of the Markdown widget and Heading
+ * fields.
+ */
+export function RichTextBlock({ text, className, style }: RichTextBlockProps): ReactNode {
+  // softBreaks: several widget textareas rendered with `whitespace-pre-line`
+  // before markdown support, so a bare newline has always been a visible
+  // line break there — keep that meaning instead of markdown's space-join.
+  const blocks = parseMarkdownBlocks(text ?? '', { softBreaks: true });
+  if (blocks.length === 0) return null;
+  const only = blocks.length === 1 ? blocks[0] : undefined;
+  if (only && only.type === 'p') {
+    return (
+      <p className={className} style={style}>
+        {renderWithSoftBreaks(only.text)}
+      </p>
+    );
+  }
+  return (
+    <div className={className} style={style}>
+      {blocks.map((block, i) => renderBlock(block, i))}
+    </div>
+  );
+}
+
+/** Inline rich text where remaining `\n`s (softBreaks parsing) become `<br/>`. */
+function renderWithSoftBreaks(text: string): ReactNode[] {
+  return text.split('\n').flatMap((line, i) => {
+    // Each line's nodes go in a keyed fragment so renderRichText's
+    // per-line keys ("t-0", ...) can't collide across lines.
+    //
+    // Index is the only identity these have: they're positional slices of one
+    // string, re-derived on every render, with nothing stable to key on.
+    // biome-ignore lint/suspicious/noArrayIndexKey: positional slices of a string have no stable id
+    const nodes = <Fragment key={`ln-${i}`}>{renderRichText(line)}</Fragment>;
+    // biome-ignore lint/suspicious/noArrayIndexKey: same — the <br> is positional too
+    return i === 0 ? [nodes] : [<br key={`br-${i}`} />, nodes];
+  });
+}
+
+function renderBlock(block: MarkdownBlock, key: number): ReactNode {
+  if (block.type === 'ul') {
+    return (
+      <ul key={key} className="list-disc pl-5 [&:not(:first-child)]:mt-3">
+        {block.items.map((li, j) => (
+          // biome-ignore lint/suspicious/noArrayIndexKey: list items are positional slices of the source text
+          <li key={j}>{renderRichText(li)}</li>
+        ))}
+      </ul>
+    );
+  }
+  return (
+    <p
+      key={key}
+      className={cn('[&:not(:first-child)]:mt-3', block.type !== 'p' && 'font-semibold')}
+    >
+      {renderWithSoftBreaks(block.text)}
+    </p>
+  );
+}

pagebuilder/components/widgets/_internal/solid-icons.tsx

@@ -0,0 +1,73 @@
+import { cn } from '../../../utils/widgetUtils';
+
+/**
+ * Solid (filled) icon set matching the GCA Design System "Icons" Figma page.
+ * Glyphs are Font Awesome Free 6.7.2 solid icons
+ * (https://fontawesome.com — License: CC BY 4.0,
+ * https://creativecommons.org/licenses/by/4.0/); path data unmodified.
+ * Rendered with `fill: currentColor` so the consumer controls the tint the
+ * same way it does for the lucide stroke icons these replace. The svgs are
+ * decorative (aria-hidden, no <title> — a title pops a native tooltip).
+ */
+
+export type SolidIconProps = { className?: string };
+
+function makeIcon(title: string, viewBox: string, d: string) {
+  function Icon({ className }: SolidIconProps) {
+    return (
+      <svg
+        viewBox={viewBox}
+        xmlns="http://www.w3.org/2000/svg"
+        fill="currentColor"
+        className={cn('size-6 shrink-0', className)}
+        aria-hidden="true"
+      >
+        <path d={d} />
+      </svg>
+    );
+  }
+  Icon.displayName = `SolidIcon(${title})`;
+  return Icon;
+}
+
+/** fa-solid fa-chart-area — carbon mapping / area statistics. */
+export const ChartAreaSolid = makeIcon(
+  'Area chart',
+  '0 0 512 512',
+  'M64 64c0-17.7-14.3-32-32-32S0 46.3 0 64L0 400c0 44.2 35.8 80 80 80l400 0c17.7 0 32-14.3 32-32s-14.3-32-32-32L80 416c-8.8 0-16-7.2-16-16L64 64zm96 288l288 0c17.7 0 32-14.3 32-32l0-68.2c0-7.6-2.7-15-7.7-20.8l-65.8-76.8c-12.1-14.2-33.7-15-46.9-1.8l-21 21c-10 10-26.4 9.2-35.4-1.6l-39.2-47c-12.6-15.1-35.7-15.4-48.7-.6L135.9 215c-5.1 5.8-7.9 13.3-7.9 21.1l0 84c0 17.7 14.3 32 32 32z',
+);
+
+/** fa-solid fa-magnifying-glass-chart — tracking disturbance. */
+export const MagnifyingGlassChartSolid = makeIcon(
+  'Magnifying glass with chart',
+  '0 0 512 512',
+  'M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0S416 93.1 416 208zm-312 8l0 64c0 13.3 10.7 24 24 24s24-10.7 24-24l0-64c0-13.3-10.7-24-24-24s-24 10.7-24 24zm80-96l0 160c0 13.3 10.7 24 24 24s24-10.7 24-24l0-160c0-13.3-10.7-24-24-24s-24 10.7-24 24zm80 64l0 96c0 13.3 10.7 24 24 24s24-10.7 24-24l0-96c0-13.3-10.7-24-24-24s-24 10.7-24 24z',
+);
+
+/** fa-solid fa-temperature-three-quarters — microclimate. */
+export const TemperatureSolid = makeIcon(
+  'Thermometer',
+  '0 0 320 512',
+  'M160 64c-26.5 0-48 21.5-48 48l0 164.5c0 17.3-7.1 31.9-15.3 42.5C86.2 332.6 80 349.5 80 368c0 44.2 35.8 80 80 80s80-35.8 80-80c0-18.5-6.2-35.4-16.7-48.9c-8.2-10.6-15.3-25.2-15.3-42.5L208 112c0-26.5-21.5-48-48-48zM48 112C48 50.2 98.1 0 160 0s112 50.1 112 112l0 164.4c0 .1 .1 .3 .2 .6c.2 .6 .8 1.6 1.7 2.8c18.9 24.4 30.1 55 30.1 88.1c0 79.5-64.5 144-144 144S16 447.5 16 368c0-33.2 11.2-63.8 30.1-88.1c.9-1.2 1.5-2.2 1.7-2.8c.1-.3 .2-.5 .2-.6L48 112zM208 368c0 26.5-21.5 48-48 48s-48-21.5-48-48c0-20.9 13.4-38.7 32-45.3L144 144c0-8.8 7.2-16 16-16s16 7.2 16 16l0 178.7c18.6 6.6 32 24.4 32 45.3z',
+);
+
+/** fa-solid fa-tree — forestry restoration. */
+export const TreeSolid = makeIcon(
+  'Tree',
+  '0 0 448 512',
+  'M210.6 5.9L62 169.4c-3.9 4.2-6 9.8-6 15.5C56 197.7 66.3 208 79.1 208l24.9 0L30.6 281.4c-4.2 4.2-6.6 10-6.6 16C24 309.9 34.1 320 46.6 320L80 320 5.4 409.5C1.9 413.7 0 419 0 424.5c0 13 10.5 23.5 23.5 23.5L192 448l0 32c0 17.7 14.3 32 32 32s32-14.3 32-32l0-32 168.5 0c13 0 23.5-10.5 23.5-23.5c0-5.5-1.9-10.8-5.4-15L368 320l33.4 0c12.5 0 22.6-10.1 22.6-22.6c0-6-2.4-11.8-6.6-16L344 208l24.9 0c12.7 0 23.1-10.3 23.1-23.1c0-5.7-2.1-11.3-6-15.5L237.4 5.9C234 2.1 229.1 0 224 0s-10 2.1-13.4 5.9z',
+);
+
+/** fa-solid fa-paw — habitat mapping. */
+export const PawSolid = makeIcon(
+  'Paw print',
+  '0 0 512 512',
+  'M226.5 92.9c14.3 42.9-.3 86.2-32.6 96.8s-70.1-15.6-84.4-58.5s.3-86.2 32.6-96.8s70.1 15.6 84.4 58.5zM100.4 198.6c18.9 32.4 14.3 70.1-10.2 84.1s-59.7-.9-78.5-33.3S-2.7 179.3 21.8 165.3s59.7 .9 78.5 33.3zM69.2 401.2C121.6 259.9 214.7 224 256 224s134.4 35.9 186.8 177.2c3.6 9.7 5.2 20.1 5.2 30.5l0 1.6c0 25.8-20.9 46.7-46.7 46.7c-11.5 0-22.9-1.4-34-4.2l-88-22c-15.3-3.8-31.3-3.8-46.6 0l-88 22c-11.1 2.8-22.5 4.2-34 4.2C84.9 480 64 459.1 64 433.3l0-1.6c0-10.4 1.6-20.8 5.2-30.5zM421.8 282.7c-24.5-14-29.1-51.7-10.2-84.1s54-47.3 78.5-33.3s29.1 51.7 10.2 84.1s-54 47.3-78.5 33.3zM310.1 189.7c-32.3-10.6-46.9-53.9-32.6-96.8s52.1-69.1 84.4-58.5s46.9 53.9 32.6 96.8s-52.1 69.1-84.4 58.5z',
+);
+
+/** fa-solid fa-water — flooding and erosion. */
+export const WaterSolid = makeIcon(
+  'Water waves',
+  '0 0 576 512',
+  'M269.5 69.9c11.1-7.9 25.9-7.9 37 0C329 85.4 356.5 96 384 96c26.9 0 55.4-10.8 77.4-26.1c0 0 0 0 0 0c11.9-8.5 28.1-7.8 39.2 1.7c14.4 11.9 32.5 21 50.6 25.2c17.2 4 27.9 21.2 23.9 38.4s-21.2 27.9-38.4 23.9c-24.5-5.7-44.9-16.5-58.2-25C449.5 149.7 417 160 384 160c-31.9 0-60.6-9.9-80.4-18.9c-5.8-2.7-11.1-5.3-15.6-7.7c-4.5 2.4-9.7 5.1-15.6 7.7c-19.8 9-48.5 18.9-80.4 18.9c-33 0-65.5-10.3-94.5-25.8c-13.4 8.4-33.7 19.3-58.2 25c-17.2 4-34.4-6.7-38.4-23.9s6.7-34.4 23.9-38.4C42.8 92.6 61 83.5 75.3 71.6c11.1-9.5 27.3-10.1 39.2-1.7c0 0 0 0 0 0C136.7 85.2 165.1 96 192 96c27.5 0 55-10.6 77.5-26.1zm37 288C329 373.4 356.5 384 384 384c26.9 0 55.4-10.8 77.4-26.1c0 0 0 0 0 0c11.9-8.5 28.1-7.8 39.2 1.7c14.4 11.9 32.5 21 50.6 25.2c17.2 4 27.9 21.2 23.9 38.4s-21.2 27.9-38.4 23.9c-24.5-5.7-44.9-16.5-58.2-25C449.5 437.7 417 448 384 448c-31.9 0-60.6-9.9-80.4-18.9c-5.8-2.7-11.1-5.3-15.6-7.7c-4.5 2.4-9.7 5.1-15.6 7.7c-19.8 9-48.5 18.9-80.4 18.9c-33 0-65.5-10.3-94.5-25.8c-13.4 8.4-33.7 19.3-58.2 25c-17.2 4-34.4-6.7-38.4-23.9s6.7-34.4 23.9-38.4c18.1-4.2 36.2-13.3 50.6-25.2c11.1-9.4 27.3-10.1 39.2-1.7c0 0 0 0 0 0C136.7 373.2 165.1 384 192 384c27.5 0 55-10.6 77.5-26.1c11.1-7.9 25.9-7.9 37 0zm0-144C329 229.4 356.5 240 384 240c26.9 0 55.4-10.8 77.4-26.1c0 0 0 0 0 0c11.9-8.5 28.1-7.8 39.2 1.7c14.4 11.9 32.5 21 50.6 25.2c17.2 4 27.9 21.2 23.9 38.4s-21.2 27.9-38.4 23.9c-24.5-5.7-44.9-16.5-58.2-25C449.5 293.7 417 304 384 304c-31.9 0-60.6-9.9-80.4-18.9c-5.8-2.7-11.1-5.3-15.6-7.7c-4.5 2.4-9.7 5.1-15.6 7.7c-19.8 9-48.5 18.9-80.4 18.9c-33 0-65.5-10.3-94.5-25.8c-13.4 8.4-33.7 19.3-58.2 25c-17.2 4-34.4-6.7-38.4-23.9s6.7-34.4 23.9-38.4c18.1-4.2 36.2-13.3 50.6-25.2c11.1-9.5 27.3-10.1 39.2-1.7c0 0 0 0 0 0C136.7 229.2 165.1 240 192 240c27.5 0 55-10.6 77.5-26.1c11.1-7.9 25.9-7.9 37 0z',
+);

pagebuilder/components/widgets/_shared/background-media.tsx

@@ -0,0 +1,74 @@
+import { cn, decorativeAriaProps } from '../../../utils/widgetUtils';
+
+export type BackgroundMediaOverlay = 'none' | 'subtle' | 'dark';
+export type BackgroundMediaFallback = 'gradient-mesh' | 'solid';
+
+export type BackgroundMediaProps = {
+  imageUrl: string;
+  imageAlt: string;
+  overlay?: BackgroundMediaOverlay;
+  fallback?: BackgroundMediaFallback;
+  /**
+   * CSS `object-position` for the cover-fitted photo. Callers pass a themeable
+   * token so a tenant can choose which part of a tall photo survives the crop
+   * (BioGarden's hero is a 1440x1920 sky-over-meadow shot that the Figma
+   * anchors to the top; centered, the sky is cut away). Omitted = centered.
+   */
+  objectPosition?: string;
+};
+
+// The "dark" scrim strength is tenant-tunable: GCA's Figma hero is nearly
+// un-dimmed (see `--pb-hero-overlay` in gca.css); the fallback keeps the
+// original 55% black for tenants that don't set the token.
+const OVERLAY_CLASSES: Record<Exclude<BackgroundMediaOverlay, 'none'>, string> = {
+  subtle: 'bg-black/30',
+  dark: 'bg-[color:var(--pb-hero-overlay,rgb(0_0_0/0.55))]',
+};
+
+// Hoisted: a fresh style object per render would defeat React's prop-equality
+// fast-path and re-trigger style-attribute writes on every editor keystroke.
+const MESH_STYLE = {
+  background:
+    'radial-gradient(at 18% 28%, #c084fc 0px, transparent 50%), ' +
+    'radial-gradient(at 82% 18%, #ec4899 0px, transparent 50%), ' +
+    'radial-gradient(at 72% 88%, #6366f1 0px, transparent 50%), ' +
+    '#2e1065',
+} as const;
+
+export function BackgroundMedia({
+  imageUrl,
+  imageAlt,
+  overlay = 'none',
+  fallback = 'gradient-mesh',
+  objectPosition,
+}: BackgroundMediaProps) {
+  // data-pb-* attributes are stable selectors for tests and CMS-side analytics.
+  return (
+    <>
+      {imageUrl ? (
+        <img
+          src={imageUrl}
+          alt={imageAlt ?? ''}
+          {...decorativeAriaProps(imageAlt)}
+          loading="lazy"
+          className="absolute inset-0 -z-10 w-full h-full object-cover"
+          style={objectPosition ? { objectPosition } : undefined}
+        />
+      ) : fallback === 'gradient-mesh' ? (
+        <div
+          data-pb-fallback="gradient-mesh"
+          className="absolute inset-0 -z-10"
+          style={MESH_STYLE}
+        />
+      ) : (
+        <div data-pb-fallback="solid" className="absolute inset-0 -z-10 bg-slate-900" />
+      )}
+      {overlay !== 'none' && (
+        <div
+          data-pb-overlay={overlay}
+          className={cn('absolute inset-0 -z-10', OVERLAY_CLASSES[overlay])}
+        />
+      )}
+    </>
+  );
+}

pagebuilder/components/widgets/_shared/content-media.tsx

@@ -0,0 +1,43 @@
+import { cn, decorativeAriaProps } from '../../../utils/widgetUtils';
+
+export type ContentMediaAspect = 'square' | 'video' | 'portrait';
+
+export type ContentMediaProps = {
+  imageUrl: string;
+  imageAlt: string;
+  aspect?: ContentMediaAspect;
+};
+
+const ASPECT_CLASSES: Record<ContentMediaAspect, string> = {
+  square: 'aspect-square',
+  video: 'aspect-video',
+  portrait: 'aspect-[3/4]',
+};
+
+// Hoisted: same rationale as MESH_STYLE in background-media.tsx — keep render
+// referential stability so React doesn't churn the style attribute.
+const DOTTED_STYLE = {
+  background:
+    'radial-gradient(circle, rgba(99,102,241,0.18) 1px, transparent 1px), ' +
+    'linear-gradient(135deg, #f8fafc 0%, #e2e8f0 100%)',
+  backgroundSize: '16px 16px, 100% 100%',
+} as const;
+
+export function ContentMedia({ imageUrl, imageAlt, aspect = 'video' }: ContentMediaProps) {
+  const wrapperCls = cn('w-full rounded-xl overflow-hidden', ASPECT_CLASSES[aspect], 'shadow-xl');
+  if (imageUrl) {
+    return (
+      <div className={wrapperCls}>
+        <img
+          src={imageUrl}
+          alt={imageAlt ?? ''}
+          {...decorativeAriaProps(imageAlt)}
+          loading="lazy"
+          className="w-full h-full object-cover"
+        />
+      </div>
+    );
+  }
+  // data-pb-fallback is a stable selector for tests and CMS-side analytics.
+  return <div data-pb-fallback="dotted-grid" className={wrapperCls} style={DOTTED_STYLE} />;
+}

pagebuilder/components/widgets/_shared/cta-button.tsx

@@ -0,0 +1,69 @@
+import { cn } from '../../../utils/widgetUtils';
+import { renderRichText } from '../_internal/rich-text';
+
+export type CTAButtonVariant = 'primary' | 'secondary' | 'inverse-primary' | 'inverse-outline';
+
+export type CTAButtonSize = 'md' | 'lg';
+
+export type CTAButtonProps = {
+  label: string;
+  href: string;
+  variant: CTAButtonVariant;
+  size?: CTAButtonSize;
+};
+
+// Shape and type are tenant-tunable: GCA's design system uses pill buttons
+// with SemiBold 17px labels (see `.gca-root` in gca.css); the fallbacks keep
+// the original rounded-md / medium / text-base look for other tenants.
+const BASE =
+  'inline-flex items-center justify-center rounded-[var(--pb-button-radius,0.375rem)] font-[number:var(--pb-button-weight,500)] transition-colors ' +
+  'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500';
+
+// Padding is tenant-tunable alongside the font size so a tenant whose buttons
+// are a fixed Figma size (BioGarden: 211x54 at 18px) can hit it without every
+// other tenant's buttons changing — the fallbacks are the previous literals.
+const SIZE_CLASSES: Record<CTAButtonSize, string> = {
+  md: 'py-[var(--pb-button-py-md,0.625rem)] px-[var(--pb-button-px-md,1.25rem)] text-[length:var(--pb-button-font-size-md,0.875rem)]',
+  lg: 'py-[var(--pb-button-py,0.75rem)] px-[var(--pb-button-px,1.5rem)] text-[length:var(--pb-button-font-size,1rem)]',
+};
+
+// The two "inverse" variants sit on a photo/dark band (Hero, CallToAction).
+// Their surface is tokenized because tenants disagree on what a primary
+// button on a photo looks like: the default is the solid white pill, while
+// BioGarden's Figma draws it as a transparent white-outlined pill. Every
+// fallback reproduces the previous hardcoded value, so tenants that set none
+// of these tokens render exactly as before.
+const VARIANT_CLASSES: Record<CTAButtonVariant, string> = {
+  primary: 'bg-primary-800 hover:bg-primary-900 text-white',
+  secondary:
+    'border border-gray-300 dark:border-gray-700 text-gray-900 dark:text-gray-100 hover:bg-gray-50 dark:hover:bg-gray-800',
+  'inverse-primary':
+    'bg-[var(--pb-button-inverse-bg,#ffffff)] text-[color:var(--pb-button-inverse-fg,var(--color-primary-800))] ' +
+    'border-[length:var(--pb-button-inverse-border-width,0px)] border-solid border-[color:var(--pb-button-inverse-border,transparent)] ' +
+    'hover:bg-[var(--pb-button-inverse-bg-hover,var(--color-primary-50))]',
+  'inverse-outline':
+    'bg-[var(--pb-button-outline-bg,rgb(255_255_255/0.2))] border-[length:var(--pb-button-outline-border-width,1px)] border-solid ' +
+    'border-[color:var(--pb-button-outline-border,rgb(255_255_255/0.55))] text-white ' +
+    'hover:bg-[var(--pb-button-outline-bg-hover,rgb(255_255_255/0.3))]',
+};
+
+export function CTAButton({ label, href, variant, size = 'lg' }: CTAButtonProps) {
+  if (!label || label.trim() === '') return null;
+  return (
+    <a href={href || '#'} className={cn(BASE, SIZE_CLASSES[size], VARIANT_CLASSES[variant])}>
+      {/* The label is already inside this <a>, so links stay markup-free —
+			    a nested anchor is invalid HTML and browsers split it. */}
+      {renderRichText(label, { allowLinks: false })}
+      {/* Trailing arrow, off by default. Tenants flip it on globally via
+			    `--pb-button-arrow-display` (e.g. inline-block) — no content change.
+			    Labels that already carry their own arrow (a literal "→", or a "←"
+			    back link) suppress it, so the global toggle never doubles or
+			    contradicts an explicit direction. */}
+      {!/[←→]/.test(label) && (
+        <span aria-hidden="true" className="ml-2 [display:var(--pb-button-arrow-display,none)]">
+          →
+        </span>
+      )}
+    </a>
+  );
+}

pagebuilder/components/widgets/_shared/empty-placeholder.tsx

@@ -0,0 +1,15 @@
+export type EmptyPlaceholderProps = {
+  label: string;
+};
+
+/**
+ * Dashed-border placeholder shown when a media/embed widget has no content
+ * to render (no source, no slides, …).
+ */
+export function EmptyPlaceholder({ label }: EmptyPlaceholderProps) {
+  return (
+    <div className="border-2 border-dashed border-gray-300 rounded-lg p-8 text-center text-gray-500">
+      {label}
+    </div>
+  );
+}

pagebuilder/components/widgets/_shared/eyebrow-text.tsx

@@ -0,0 +1,27 @@
+import { cn } from '../../../utils/widgetUtils';
+import { renderRichText } from '../_internal/rich-text';
+
+export type EyebrowTone = 'primary' | 'muted' | 'inverse';
+
+export type EyebrowTextProps = {
+  children: string;
+  tone?: EyebrowTone;
+};
+
+const TONE_CLASSES: Record<EyebrowTone, string> = {
+  primary: 'text-primary-800',
+  muted: 'text-gray-500 dark:text-gray-400',
+  inverse: 'text-white/85',
+};
+
+export function EyebrowText({ children, tone = 'primary' }: EyebrowTextProps) {
+  // Tolerate undefined at runtime: legacy Puck JSON saved before the eyebrow
+  // field existed renders without that prop, and Puck doesn't always merge
+  // defaultProps for newly added fields.
+  if (!children || children.trim() === '') return null;
+  return (
+    <p className={cn('text-sm font-semibold uppercase tracking-wider', TONE_CLASSES[tone])}>
+      {renderRichText(children)}
+    </p>
+  );
+}

pagebuilder/components/widgets/_shared/heading.tsx

@@ -0,0 +1,88 @@
+import type { CSSProperties } from 'react';
+import { cn } from '../../../utils/widgetUtils';
+import { AccentText } from '../_internal/accent-text';
+
+export type HeadingLevel = 'h1' | 'h2' | 'h3';
+export type HeadingSize = 'xl' | 'lg' | 'md';
+export type HeadingTone = 'default' | 'inverse';
+
+export type HeadingProps = {
+  as: HeadingLevel;
+  size: HeadingSize;
+  text: string;
+  align?: 'left' | 'center';
+  tone?: HeadingTone;
+  /**
+   * Opt-in "accent" treatment for page-hero titles. Tenants can give the hero
+   * title a distinct weight/style (e.g. GCA's SemiBold *Italic* H1) via the
+   * `--pb-hero-title-*` tokens. Falls back to the normal display weight / an
+   * upright style, so tenants that don't set the tokens are unaffected.
+   */
+  accent?: boolean;
+};
+
+// Display line-height is tenant-tunable: Mowing's Figma uses 1.2 for every
+// heading level; the fallbacks reproduce the prior tight leading, so tenants
+// that don't set `--pb-heading-leading` (GCA, Recodo) render unchanged.
+const SIZE_CLASSES: Record<HeadingSize, string> = {
+  xl: 'leading-[var(--pb-heading-leading,1.1)]',
+  lg: 'leading-[var(--pb-heading-leading,1.1)]',
+  md: 'leading-[var(--pb-heading-leading,1.25)]',
+};
+
+// Font sizes are tenant-themeable via `--pb-heading-*`; the clamp() fallbacks
+// reproduce the previous responsive Tailwind steps, so tenants that don't set
+// the tokens render unchanged. A tenant (e.g. Mowing) can scale the whole
+// display hierarchy up by overriding these tokens in its theme vars.
+const SIZE_FONT: Record<HeadingSize, string> = {
+  xl: 'var(--pb-heading-xl, clamp(2.25rem, 1.4rem + 3.6vw, 3.75rem))',
+  lg: 'var(--pb-heading-lg, clamp(1.875rem, 1.3rem + 2.5vw, 3rem))',
+  md: 'var(--pb-heading-md, clamp(1.5rem, 1.2rem + 1.4vw, 1.875rem))',
+};
+
+// `inverse` keeps white on dark/colored backgrounds; `default` takes the
+// per-tenant heading color from the --pb-* tokens via `style`.
+const TONE_CLASSES: Record<HeadingTone, string> = {
+  default: '',
+  inverse: 'text-white',
+};
+
+// Display weight/tracking/font come from per-tenant page-builder tokens
+// (Recodo defaults in styles.css `:root`, GCA overrides in `.gca-root`).
+const DISPLAY_STYLE: CSSProperties = {
+  fontWeight: 'var(--pb-display-weight)' as CSSProperties['fontWeight'],
+  letterSpacing: 'var(--pb-display-tracking)',
+  fontFamily: 'var(--pb-display-font)',
+};
+
+// Hero-title "accent" overrides: a distinct weight + (optional) italic style,
+// each falling back so non-GCA tenants render an upright display-weight title.
+const ACCENT_STYLE: CSSProperties = {
+  fontWeight:
+    'var(--pb-hero-title-weight, var(--pb-display-weight))' as CSSProperties['fontWeight'],
+  fontStyle: 'var(--pb-hero-title-style, normal)' as CSSProperties['fontStyle'],
+};
+
+export function Heading({ as, size, text, align, tone = 'default', accent = false }: HeadingProps) {
+  if (!text || text.trim() === '') return null;
+  const Tag = as;
+  // Hero titles (accent) may take a dedicated size token so a tenant can make
+  // its page-hero H1 larger than section headings that share the same `size`
+  // (e.g. Mowing: hero 64px while SectionIntro `lg` stays 48px). Falls back to
+  // the normal size token, so tenants that don't set it render unchanged.
+  const fontSize = accent ? `var(--pb-hero-title-size, ${SIZE_FONT[size]})` : SIZE_FONT[size];
+  const base: CSSProperties = {
+    ...(accent ? { ...DISPLAY_STYLE, ...ACCENT_STYLE } : DISPLAY_STYLE),
+    fontSize,
+  };
+  const style: CSSProperties =
+    tone === 'inverse' ? base : { ...base, color: 'var(--pb-heading-color)' };
+  return (
+    <Tag
+      className={cn(SIZE_CLASSES[size], TONE_CLASSES[tone], align === 'center' && 'text-center')}
+      style={style}
+    >
+      <AccentText text={text} />
+    </Tag>
+  );
+}