@taprootio/site-authoring 0.28.0 → 0.30.0

package/examples/riverbend-wellness/settings/site-publishing-preferences.json

@@ -18,6 +18,14 @@
           "pageResourceId": "a0000000-0000-4000-8000-000000000013"
         }
       ],
+      "socialLinks": [
+        {
+          "id": "a0000000-0000-4000-8000-000000000048",
+          "platform": "instagram",
+          "url": "https://instagram.example.test/riverbendwellness",
+          "label": "Riverbend on Instagram"
+        }
+      ],
       "light": {
         "backgroundColor": "--esp-color-layer-1",
         "textColor": "--esp-color-text",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Taproot site authoring CLI: sign in once in the browser, then pull, validate, push, preview, approve, and deploy a site from the terminal",
   "type": "module",
   "license": "ISC",

package/src/changelog.json

@@ -1,5 +1,35 @@
 {
   "entries": [
+    {
+      "version": "0.30.0",
+      "note": "A card-grid can show each card's image whole at a set height, aligned and unframed, with chosen space on any side of the image, so a logo no longer needs a wide padded file.",
+      "behavior": [
+        "A card-grid takes imageFit (cover, the default, or contain), imageHeight (small 2.5rem/40px, medium 4rem/64px, large 6rem/96px at a 16px root), imageAlign (start, center or end) and imageSpacing (an object with any of top, bottom, start and end, each none, small, medium or text). With contain the whole image shows at imageHeight, never cropped or framed, and an image wider than its card shrinks to fit; each card image needs a nonzero width and height, which media upload records. imageHeight and imageAlign are refused unless imageFit is contain. A side left out of imageSpacing keeps its default for the fit: cover has none on every side; contain has small above, none below and text (the padding around the card's text) at start and end. See help component card-grid.",
+        "A card-grid image now sits flush with the top of its card, because the article image margin no longer reaches it. A site gets this on its next publish.",
+        "The help reference version is 49."
+      ],
+      "help": [
+        "components",
+        "component"
+      ]
+    },
+    {
+      "version": "0.29.0",
+      "note": "Pages gain an image-row component for linked pictures at a set height and a product-grid component for priced cards with a button each; feature-grid help states its icon sizes and square crop, and published feature-grid icons now render at the documented sizes.",
+      "behavior": [
+        "A free-form page may hold an image-row component: one to twelve pictures at one height (small 2.5rem/40px, medium 4rem/64px, large 6rem/96px at a 16px root), each with required alt text, required width and height, and an optional link. Pictures keep their own shape, are never cropped or framed, and one wider than the row shrinks to fit. See help component image-row.",
+        "help component feature-grid states the icon box sizes (small 3rem/48px, medium 6rem/96px, large 10rem/160px, xlarge 16rem/256px at a 16px root) and that icons are cropped to a square and framed by the site's image border. Published feature-grid icons now render at those sizes; before this release they filled the item's width with a 2em margin, so re-check existing grids after the runtime update.",
+        "A free-form page may hold a product-grid component: one to a hundred equal-height cards for things to buy or book, each with a title, free-text price and note, badge, description, up to eight feature lines, an optional 16:9 image and one button that links to any checkout; columns 2 to 4, standard or compact density, a border width, and a highlighted card drawn in the site's action color. Site checks now read buttonUrl and linkUrl addresses, so a card-grid, cta or product-grid link to a missing page is reported. See help component product-grid.",
+        "A free-form page may hold a social-links component: one to twelve links, each a platform from a fixed list (Instagram, Facebook, Yelp, YouTube, TikTok, LinkedIn, X, Threads, Bluesky, Mastodon, Pinterest, or Website for any other site) with an https address and an optional label the link reads to screen readers; icons at small 1.5rem, medium 2rem or large 3rem, aligned start, center or end (the align field), with labels shown or hidden. The address must be absolute https, without credentials, to a domain of unaccented letters, digits and hyphens. See help component social-links.",
+        "Footer settings gain socialLinks: up to twelve links with an id, a platform key, an https address and an optional label, published as an icon row between the bottom copy and the utility links. The footer draft hash moves to footer-draft-v4, so every footer draft hash issued before this release is stale once: pull the footer again before pushing it. See help footer.",
+        "The help reference version is 48."
+      ],
+      "help": [
+        "components",
+        "component",
+        "footer"
+      ]
+    },
     {
       "version": "0.28.0",
       "note": "Taproot no longer generates /places, year and month, or tag pages, so a generated page's data drops those fields. One /published page lists every month, a folder page reaches search only with an introduction or three cards, and a review's location byline opens Google Maps.",

package/src/content/components.js

@@ -4,7 +4,10 @@
 // copy — the generator's Playwright Node process, for one — cannot load this
 // pipeline at all once a component module is in the graph.
 import { BUILT_IN_IMAGE_TEXTURES } from "@taprootio/espalier/shared/image-texture-registry";
+import registry from "./free-form-section-registry.json" with { type: "json" };
 import { hasAsciiControl } from "../errors.js";
+import { isSocialLinkUrl, SOCIAL_LINK_URL_MAX_LENGTH, trimSocialLinkInput } from "../social-link-url.js";
+import socialPlatforms from "../social-platforms.json" with { type: "json" };
 import {
   CONTENT_ERROR_CODES as CODES,
   CONTENT_LIMITS,
@@ -61,14 +64,28 @@ const boundedStr = (maximumLength, options = {}) => str({ maximumLength, ...opti
 const bool = () => Object.freeze({ kind: "boolean" });
 const num = (options = {}) => Object.freeze({ kind: "number", ...options });
 const enumOf = (...values) => Object.freeze({ kind: "enum", values: Object.freeze(values) });
-const list = (item) => Object.freeze({ kind: "array", item });
+/** An array of `item`; `minItems`/`maxItems` bound it below the global cap (TR01322). */
+const list = (item, options = {}) => Object.freeze({ kind: "array", item, ...options });
 const shape = (fields, options = {}) => Object.freeze({ kind: "object", fields: Object.freeze(fields), ...options });
-const image = () => Object.freeze({ kind: "image" });
-const safeUrl = (options = {}) => Object.freeze({ kind: "safe-url", ...options });
+/**
+ * A processed-image record or null. `required` refuses null, `altRequired`
+ * refuses a blank alt and `dimensionsRequired` demands positive width and
+ * height, for a component whose images are the content (TR01322).
+ */
+const image = (options = {}) => Object.freeze({ kind: "image", ...options });
+/**
+ * A safe URL; `https: true` is the social-link rule (absolute https to a plain
+ * domain, TR01324), which also makes the field required and refuses an empty
+ * value, so every reader of `required` agrees.
+ */
+const safeUrl = (options = {}) =>
+  Object.freeze({ kind: "safe-url", ...(options.https ? { required: true, allowEmpty: false } : {}), ...options });
 /** A CSS length the published renderer accepts as a per-block override; `allowNone` adds `none` (a max height). */
 const cssLength = (options = {}) => Object.freeze({ kind: "css-length", ...options });
 const textureName = () => Object.freeze({ kind: "texture-name", maximumLength: 64 });
 const withOmission = (spec, whenOmitted) => Object.freeze({ ...spec, whenOmitted: Object.freeze(whenOmitted) });
+/** The same spec with a description `help component` prints beside its constraints. */
+const described = (spec, description) => Object.freeze({ ...spec, description });
 
 /**
  * `ComponentImageData`. `src` and `urls` are the only required-by-key fields
@@ -230,6 +247,22 @@ const LATEST_POSTS = Object.freeze({
   bannerScheme: enumOf("auto", "light", "dark"),
 });
 
+/** The registry owns the row heights; the help text and the renderer derive from the same map. */
+const IMAGE_ROW_HEIGHTS = registry.components["image-row"].heights;
+const IMAGE_ROW_HEIGHT_SIZES = Object.entries(IMAGE_ROW_HEIGHTS)
+  .map(([name, rem]) => `${name} ${rem} (${Number.parseFloat(rem) * 16}px)`)
+  .join(", ");
+const IMAGE_ROW_HEIGHT_HELP =
+  `Each image's height: ${IMAGE_ROW_HEIGHT_SIZES} at a 16px root; width follows each image's own shape, never cropped or framed.`;
+
+/** The registry owns the card image spacings too; each side takes the same four names (TR01326). */
+const CARD_IMAGE_SPACINGS = registry.components["card-grid"].imageSpacings;
+const CARD_IMAGE_SPACING_NAMES = Object.keys(CARD_IMAGE_SPACINGS);
+const CARD_IMAGE_SPACING_VALUES =
+  `none (0), small (${CARD_IMAGE_SPACINGS.small}), medium (${CARD_IMAGE_SPACINGS.medium}) or text (the same padding as around the card's text)`;
+const CARD_IMAGE_SPACING_SIDE_HELP = (side, defaults) =>
+  `Space on the ${side} of each card image: ${CARD_IMAGE_SPACING_VALUES}. Left out, it is ${defaults}.`;
+
 /** `CardGridData`. `cropState` is the one genuinely optional field in types.ts. */
 const CARD_GRID = Object.freeze({
   cards: withOmission(
@@ -245,6 +278,36 @@ const CARD_GRID = Object.freeze({
   columns: num({ values: Object.freeze([2, 3]) }),
   presentation: enumOf("cards", "editorial", "featured", "poster"),
   imageAspect: enumOf("auto", "landscape", "square", "portrait"),
+  imageFit: withOmission(
+    described(
+      enumOf("cover", "contain"),
+      "cover fills the card and crops each image to imageAspect; contain shows the whole image at imageHeight, never cropped or framed, and needs each image's width and height.",
+    ),
+    { kind: "value", value: "cover" },
+  ),
+  imageHeight: described(
+    enumOf(...Object.keys(IMAGE_ROW_HEIGHTS)),
+    `${IMAGE_ROW_HEIGHT_HELP} Only with imageFit contain, where it is medium when left out; refused otherwise.`,
+  ),
+  imageAlign: described(
+    enumOf("start", "center", "end"),
+    "Where each whole image sits across its card, not the text: start is the left edge and end the right edge in a left-to-right page. Only with imageFit contain, where it is start when left out; refused otherwise.",
+  ),
+  imageSpacing: described(
+    shape({
+      top: described(enumOf(...CARD_IMAGE_SPACING_NAMES), CARD_IMAGE_SPACING_SIDE_HELP("top", "none with cover and small with contain")),
+      bottom: described(enumOf(...CARD_IMAGE_SPACING_NAMES), CARD_IMAGE_SPACING_SIDE_HELP("bottom", "none")),
+      start: described(
+        enumOf(...CARD_IMAGE_SPACING_NAMES),
+        CARD_IMAGE_SPACING_SIDE_HELP("left edge (start)", "none with cover and text with contain"),
+      ),
+      end: described(
+        enumOf(...CARD_IMAGE_SPACING_NAMES),
+        CARD_IMAGE_SPACING_SIDE_HELP("right edge (end)", "none with cover and text with contain"),
+      ),
+    }),
+    "Space around each card image; name only the sides to change, and a side left out keeps its default for the fit. With imageFit contain, start moves an image aligned to start and end moves one aligned to end; otherwise they only limit how wide the image can be.",
+  ),
   interaction: enumOf("none", "lift", "zoom", "caption-reveal"),
   borderWidth: num({
     integer: true,
@@ -362,12 +425,135 @@ const FORM = Object.freeze({
   formKey: str({ required: true, nonWhitespace: true }),
 });
 
+/**
+ * The image field table an image spec validates against. The shared table
+ * leaves alt and dimensions optional; a spec that requires them swaps in
+ * stricter entries at the same positions so canonical order is unchanged.
+ */
+function imageFieldsFor(spec) {
+  if (!spec.altRequired && !spec.dimensionsRequired) return COMPONENT_IMAGE_FIELDS;
+  return Object.freeze({
+    ...COMPONENT_IMAGE_FIELDS,
+    ...(spec.dimensionsRequired
+      ? {
+        width: num({ integer: true, minimum: 1, required: true }),
+        height: num({ integer: true, minimum: 1, required: true }),
+      }
+      : {}),
+    ...(spec.altRequired
+      ? {
+        alt: str({
+          required: true,
+          nonWhitespace: true,
+          // What the author can act on: in Markdown the alt is the media manifest's, not the fence's.
+          blankDetail: "alt text that names the picture or its destination; in Markdown the alt comes from the "
+            + "media manifest entry the image path names",
+        }),
+      }
+      : {}),
+  });
+}
+
+/**
+ * `ImageRowData` (TR01322). A row of pictures carries no other text, so every
+ * image needs alt text and the dimensions the row sizes it by.
+ */
+const IMAGE_ROW = Object.freeze({
+  items: list(
+    shape({
+      image: image({ required: true, altRequired: true, dimensionsRequired: true }),
+      url: safeUrl(),
+    }),
+    { minItems: 1, maxItems: registry.components["image-row"].maxItems, required: true },
+  ),
+  height: described(enumOf(...Object.keys(IMAGE_ROW_HEIGHTS)), IMAGE_ROW_HEIGHT_HELP),
+  align: described(
+    enumOf("start", "center", "end"),
+    "Where the images sit when they do not fill the row: start is the left edge and end the right edge in a "
+      + "left-to-right page.",
+  ),
+});
+
+/**
+ * `ProductGridData` (TR01323). The registry owns the text bounds, the item cap
+ * and the crop shape; the generator's readiness check and the editor read the
+ * same entry, so no side can drift. Blank optional text counts as absent on
+ * every side; the cross-field hook below decides the button pair and the
+ * price note.
+ */
+const PRODUCT_GRID_ENTRY = registry.components["product-grid"];
+const PRODUCT_GRID_LIMITS = PRODUCT_GRID_ENTRY.limits;
+const PRODUCT_GRID_BUTTON_TEXT_NOTE = "Keep it short; long text is cut off in narrow columns.";
+const PRODUCT_GRID = Object.freeze({
+  items: list(
+    shape({
+      image: image(),
+      title: boundedStr(PRODUCT_GRID_LIMITS.title, { required: true, nonWhitespace: true }),
+      price: described(boundedStr(PRODUCT_GRID_LIMITS.price), "Free text, such as \"$145\", \"From $30\" or \"Free\"."),
+      priceNote: described(boundedStr(PRODUCT_GRID_LIMITS.priceNote), "Shown beside the price, such as \"per month\"; refused without a price."),
+      badge: boundedStr(PRODUCT_GRID_LIMITS.badge),
+      description: boundedStr(PRODUCT_GRID_LIMITS.description),
+      features: list(
+        described(boundedStr(PRODUCT_GRID_LIMITS.feature, { nonWhitespace: true }), "One line each; a line break inside a feature is refused."),
+        { maxItems: PRODUCT_GRID_LIMITS.features },
+      ),
+      buttonText: described(
+        boundedStr(PRODUCT_GRID_LIMITS.buttonText),
+        `${PRODUCT_GRID_BUTTON_TEXT_NOTE} Needs a buttonUrl, and a buttonUrl needs it.`,
+      ),
+      buttonUrl: safeUrl(),
+      highlighted: bool(),
+      cropState: CROP_STATE,
+    }),
+    { minItems: 1, maxItems: PRODUCT_GRID_ENTRY.maxItems, required: true },
+  ),
+  columns: num({ values: Object.freeze([2, 3, 4]) }),
+  density: described(enumOf("standard", "compact"), "compact tightens the card padding and gaps; nothing is hidden."),
+  borderWidth: num({
+    integer: true,
+    minimum: 0,
+    description: "Pixel border around each card; 0 boxes nothing. A highlighted card always draws at least 2px.",
+  }),
+});
+
 function deepFreeze(value) {
   if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
   for (const child of Object.values(value)) deepFreeze(child);
   return Object.freeze(value);
 }
 
+const HTTPS_URL_DESCRIPTION =
+  `an absolute https URL without credentials, at most ${SOCIAL_LINK_URL_MAX_LENGTH} characters, to a domain name of unaccented letters, digits and hyphens`;
+const UNSUPPORTED_DOMAIN_NOTE =
+  "Domain names with accented or non-English letters are not supported here; use a footer bottom link for that site.";
+const SOCIAL_LINKS_ENTRY = registry.components["social-links"];
+const SOCIAL_PLATFORM_KEYS = socialPlatforms.platforms.map((platform) => platform.key);
+const SOCIAL_LINKS_SIZE_HELP = `The icon's edge: ${
+  Object.entries(SOCIAL_LINKS_ENTRY.sizes).map(([name, rem]) => `${name} ${rem} (${Number.parseFloat(rem) * 16}px)`).join(", ")
+} at a 16px root.`;
+/** Social links (TR01324): the registry entry owns the cap, the label length and the sizes; the shared rule owns the address. */
+const SOCIAL_LINKS = Object.freeze({
+  items: list(
+    shape({
+      platform: described(
+        Object.freeze({ ...enumOf(...SOCIAL_PLATFORM_KEYS), required: true }),
+        `The platform whose icon the link shows: ${
+          socialPlatforms.platforms.map((platform) => `${platform.key} (${platform.name})`).join(", ")
+        }. other is any website and needs a label.`,
+      ),
+      url: safeUrl({ https: true }),
+      label: described(
+        boundedStr(SOCIAL_LINKS_ENTRY.limits.label),
+        "The name screen readers announce instead of the platform name, shown beside the icon when showLabels is true; required for other, and a blank one is refused.",
+      ),
+    }),
+    { minItems: 1, maxItems: SOCIAL_LINKS_ENTRY.maxItems, required: true },
+  ),
+  size: described(enumOf(...Object.keys(SOCIAL_LINKS_ENTRY.sizes)), SOCIAL_LINKS_SIZE_HELP),
+  align: described(enumOf("start", "center", "end"), "Where the row sits across the page: start, center or end."),
+  showLabels: described(bool(), "Show each link's text beside its icon; when false the text is read by screen readers only."),
+});
+
 function component(fields, displayName, summary, defaultData, accessibility, example, authoring) {
   return deepFreeze({
     fields,
@@ -499,6 +685,8 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       "Each linked item needs a title that remains meaningful as link text.",
       "Icon images need descriptive alt text when they convey information; otherwise use an empty alt value.",
       "Item title and description are plain text: an item's url makes the whole item the link, and no link can be placed inside the text. Put linked prose in a paragraph beside the grid.",
+      "iconSize sets the icon box: small 3rem (48px), medium 6rem (96px), large 10rem (160px), xlarge 16rem (256px) at a 16px root.",
+      "Icons are cropped to a square and framed by the site's image border. For badges, logos or any picture that must keep its shape, use the image-row component instead, or a card-grid with imageFit contain when each needs a card.",
     ],
     {
       items: [
@@ -563,6 +751,14 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       "Every linked card needs a title that describes its destination.",
       "Card images need descriptive alt text unless they are decorative.",
       "Card title and description are plain text: a card's linkUrl makes the whole card the link, and no link can be placed inside the text. Put linked prose in a paragraph beside the grid.",
+      "Images are cropped when imageFit is cover, the default: each is cut to the fixed imageAspect, while imageAspect auto follows the picture's own shape up to the page's height cap. imageFit contain never crops; it shows the whole image.",
+      "For a logo or mark use imageFit contain with a tightly cropped file that has no built-in padding, and set the size with imageHeight and the space around it with imageSpacing, not by padding the file.",
+      `imageHeight sets the height of a whole image: ${IMAGE_ROW_HEIGHT_SIZES} at a 16px root. Width follows the image's shape, and an image wider than its card shrinks to fit.`,
+      "imageHeight and imageAlign are refused with cover, and when imageFit is left out, which means cover. With contain, imageHeight is medium and imageAlign is start when left out. imageAlign moves the image only, never the text.",
+      `imageSpacing is an object with any of top, bottom, start and end, each ${CARD_IMAGE_SPACING_VALUES}. It works with either fit.`,
+      "A side left out of imageSpacing keeps its default, so name only the sides to change. Defaults for cover: none on every side. Defaults for contain: top small, bottom none, start and end text.",
+      "imageFit contain needs each card image's width and height, which media upload records; a card image with a missing or zero size is refused.",
+      "A card with a saved crop shows that crop under contain; replace the image with the whole file to show all of it. The Zoom interaction has no effect on a whole image.",
     ],
     {
       cards: [
@@ -700,6 +896,112 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       markdownExample: "```component:video-embed\n{\"url\": \"https://youtu.be/dQw4w9WgXcQ\", \"title\": \"A walk through the studio before your first class.\"}\n```",
     },
   ),
+  "image-row": component(
+    IMAGE_ROW,
+    "Image Row",
+    "A wrapping row of pictures at one height, each with alt text and an optional link, never cropped or framed.",
+    { height: "medium", align: "start" },
+    [
+      "Every image needs alt text: a row of pictures carries no other text. For a linked image the alt is the link's name, so name the destination or action, such as \"Download on the App Store\"; for an unlinked image, describe the picture.",
+      "In Markdown the alt comes from the media manifest entry the image path names; a blank alt is refused.",
+      "Each image keeps its own shape at the chosen height and is never cropped or framed; an image wider than the row shrinks to fit. Width and height are required so the row can size the image; media upload records them.",
+      "Links open in the same tab, as card-grid and feature-grid links do.",
+    ],
+    {
+      items: [
+        {
+          image: {
+            imageId: "6b2d7c4e-1f3a-4b5c-9d8e-7f6a5b4c3d2e",
+            src: "https://static.example.test/site/img/app-store-badge.webp",
+            urls: [{ minWidth: 240, url: "https://static.example.test/site/img/app-store-badge-240.webp" }],
+            width: 1200,
+            height: 400,
+            alt: "Download on the App Store",
+          },
+          url: "https://apps.apple.com/app/id123456789",
+        },
+        {
+          image: {
+            imageId: "7c3e8d5f-2a4b-4c6d-8e9f-6a5b4c3d2e1f",
+            src: "https://static.example.test/site/img/google-play-badge.webp",
+            urls: [{ minWidth: 240, url: "https://static.example.test/site/img/google-play-badge-240.webp" }],
+            width: 1350,
+            height: 400,
+            alt: "Get it on Google Play",
+          },
+          url: "https://play.google.com/store/apps/details?id=example",
+        },
+      ],
+      height: "small",
+      align: "start",
+    },
+  ),
+  "product-grid": component(
+    PRODUCT_GRID,
+    "Product Grid",
+    "Equal-height cards for things to buy or book: a title, free-text price and price note, badge, description, features and one button each, linking to any checkout.",
+    { columns: 3, density: "standard", borderWidth: 0 },
+    [
+      "A button's visible text is its accessible name, and the product's title heads the same list item, so \"Buy now\" on every card reads with its product. Say what the button does, such as \"Buy now\" or \"Book a trial\".",
+      PRODUCT_GRID_BUTTON_TEXT_NOTE,
+      "buttonText and buttonUrl go together: text without an address and an address without text are both refused. Links open in the same tab, as card-grid and feature-grid links do.",
+      "price is free text (\"From $30\", \"Free\"); priceNote is shown beside it and refused without a price.",
+      "An image is optional and cropped to 16:9. Its alt may be blank when the title already says what the picture shows; in Markdown the alt comes from the media manifest entry.",
+      "highlighted draws a border of at least 2px (the borderWidth when that is larger) and the badge in the site's action color to mark one card, such as the most popular plan. The grid displays products only: no cart, payments or inventory.",
+    ],
+    {
+      items: [
+        {
+          image: null,
+          title: "Intro offer",
+          price: "$49",
+          priceNote: "for two weeks",
+          badge: "New students",
+          description: "Unlimited classes for your first two weeks.",
+          features: ["Any class, any time", "No commitment"],
+          buttonText: "Buy now",
+          buttonUrl: "https://pay.example.test/intro",
+          highlighted: false,
+        },
+        {
+          image: null,
+          title: "Monthly unlimited",
+          price: "$145",
+          priceNote: "per month",
+          badge: "Most popular",
+          description: "Every class on the schedule, plus the sauna.",
+          features: ["Unlimited classes", "Sauna included", "Pause any time"],
+          buttonText: "Join now",
+          buttonUrl: "https://pay.example.test/monthly",
+          highlighted: true,
+        },
+      ],
+      columns: 3,
+      density: "standard",
+      borderWidth: 0,
+    },
+  ),
+  "social-links": component(
+    SOCIAL_LINKS,
+    "Social Links",
+    "A row of links to the site's social profiles, each with its platform's icon, an https address and an optional label.",
+    { size: "medium", align: "start", showLabels: false },
+    [
+      "A link's text is its accessible name: the label if set, else the platform's name. With showLabels false the text is visually hidden and read by screen readers only, so the name is the same either way.",
+      "Link only to accounts you control; each platform's brand rules apply to its mark. " + UNSUPPORTED_DOMAIN_NOTE,
+      "platform other is any website and needs a label, such as \"Book online\". A named platform's link carries rel=\"me\"; a Website link carries no rel.",
+    ],
+    {
+      items: [
+        { platform: "instagram", url: "https://www.instagram.com/shywellness" },
+        { platform: "facebook", url: "https://www.facebook.com/shywellness", label: "SHY Wellness on Facebook" },
+        { platform: "other", url: "https://shywellness.example/book", label: "Book online" },
+      ],
+      size: "medium",
+      align: "start",
+      showLabels: false,
+    },
+  ),
 });
 
 export const COMPONENT_TYPES = Object.freeze(Object.keys(COMPONENT_DEFINITIONS));
@@ -754,8 +1056,18 @@ function referenceSchema(spec) {
         ...(spec.patternSource !== undefined
           ? { pattern: spec.patternSource, description: `Must be ${spec.patternDescription}.` }
           : {}),
+        // A `described()` string says what the text is for (TR01323).
+        ...(spec.description ? { description: spec.description } : {}),
       };
     case "safe-url":
+      if (spec.https) {
+        return {
+          type: "string",
+          format: "https-url",
+          maxLength: SOCIAL_LINK_URL_MAX_LENGTH,
+          description: `An ${HTTPS_URL_DESCRIPTION.slice(3)}. ${UNSUPPORTED_DOMAIN_NOTE}`,
+        };
+      }
       return {
         type: "string",
         format: spec.allowEmpty === false ? "safe-url" : "safe-url-or-empty",
@@ -783,7 +1095,11 @@ function referenceSchema(spec) {
     case "uuid":
       return { type: "string", format: "lowercase-uuid" };
     case "enum":
-      return { type: "string", enum: [...spec.values] };
+      return {
+        type: "string",
+        enum: [...spec.values],
+        ...(spec.description ? { description: spec.description } : {}),
+      };
     case "number": {
       const schema = { type: spec.integer ? "integer" : "number" };
       if (spec.values) schema.enum = [...spec.values];
@@ -796,24 +1112,31 @@ function referenceSchema(spec) {
       return schema;
     }
     case "array":
-      return { type: "array", maxItems: MAX_ITEMS, items: referenceSchema(spec.item) };
+      return {
+        type: "array",
+        ...(spec.minItems !== undefined ? { minItems: spec.minItems } : {}),
+        maxItems: spec.maxItems ?? MAX_ITEMS,
+        items: referenceSchema(spec.item),
+      };
     case "object":
       return {
         type: spec.nullable ? ["object", "null"] : "object",
         additionalProperties: false,
         properties: referenceProperties(spec.fields),
+        ...(spec.description ? { description: spec.description } : {}),
       };
     case "image":
       return {
-        type: ["object", "null"],
+        type: spec.required ? "object" : ["object", "null"],
         // What a Markdown component fence takes instead (TR01187).
-        markdownType: ["string", "null"],
-        description:
-          "In Markdown, a media path recorded by media upload (such as \"media/photo.webp\"), or null; pages push "
-          + "stores the image record. A .pm.json document carries that record: keep imageId, src, and urls keys so "
-          + "the server can rewrite delivery URLs.",
+        markdownType: spec.required ? "string" : ["string", "null"],
+        description: `In Markdown, a media path recorded by media upload (such as "media/photo.webp")${
+          spec.required ? "" : ", or null"
+        }; pages push stores the image record. A .pm.json document carries that record: keep imageId, src, and urls keys so the server can rewrite delivery URLs.${
+          spec.altRequired ? " Alt text is required." : ""
+        }${spec.dimensionsRequired ? " Width and height are required." : ""}`,
         additionalProperties: false,
-        properties: referenceProperties(COMPONENT_IMAGE_FIELDS),
+        properties: referenceProperties(imageFieldsFor(spec)),
       };
     default:
       throw new TypeError(`Unknown component schema kind '${spec.kind}'.`);
@@ -866,10 +1189,13 @@ function describe(spec) {
     case "object":
       return "an object";
     case "image":
-      return "a media path in Markdown, an image object in .pm.json, or null";
+      return spec.required
+        ? "a media path in Markdown or an image object in .pm.json"
+        : "a media path in Markdown, an image object in .pm.json, or null";
     case "uuid":
       return "a canonical lowercase UUID";
     case "safe-url":
+      if (spec.https) return HTTPS_URL_DESCRIPTION;
       return `${
         spec.allowEmpty === false ? "a" : "an empty string or a"
       } safe HTTP(S), mailto, tel, non-protocol-relative root path, fragment, query, or relative URL; backslashes and ASCII control characters are rejected`;
@@ -896,12 +1222,19 @@ function validateValue(spec, value, path, errors) {
   switch (spec.kind) {
     case "string":
       if (typeof value !== "string") fail("a string");
-      else if (spec.nonWhitespace && value.trim() === "") fail("a string containing non-whitespace text");
+      else if (spec.nonWhitespace && value.trim() === "") {
+        fail(spec.blankDetail ?? "a string containing non-whitespace text");
+      }
       else if (spec.maximumLength !== undefined && value.length > spec.maximumLength) {
         fail(`a string of at most ${spec.maximumLength} characters`);
       } else if (spec.pattern !== undefined && !spec.pattern.test(value)) fail(spec.patternDescription);
       return;
     case "safe-url":
+      if (spec.https) {
+        // Judged exactly as written: a hand-written document is not trimmed.
+        if (!isSocialLinkUrl(value)) fail(describe(spec));
+        return;
+      }
       if (
         typeof value !== "string"
         || (value === "" && spec.allowEmpty === false)
@@ -961,8 +1294,13 @@ function validateValue(spec, value, path, errors) {
         fail("an array");
         return;
       }
-      if (value.length > MAX_ITEMS) {
-        fail(`at most ${MAX_ITEMS} entries`);
+      if (spec.minItems !== undefined && value.length < spec.minItems) {
+        fail(`at least ${spec.minItems} entries`);
+        return;
+      }
+      const maxItems = spec.maxItems ?? MAX_ITEMS;
+      if (value.length > maxItems) {
+        fail(`at most ${maxItems} entries`);
         return;
       }
       value.forEach((entry, index) => validateValue(spec.item, entry, `${path}/${index}`, errors));
@@ -977,13 +1315,17 @@ function validateValue(spec, value, path, errors) {
       return;
     }
     case "image": {
-      // `ComponentImageData | null` — null is the documented "no image" value.
-      if (value === null) return;
+      // `ComponentImageData | null` — null is the documented "no image" value
+      // unless the component's images are its content.
+      if (value === null) {
+        if (spec.required) fail("an image object");
+        return;
+      }
       if (!isPlainObject(value)) {
-        fail("an image object or null");
+        fail(spec.required ? "an image object" : "an image object or null");
         return;
       }
-      validateFields(COMPONENT_IMAGE_FIELDS, value, path, errors);
+      validateFields(imageFieldsFor(spec), value, path, errors);
       return;
     }
     default:
@@ -1046,6 +1388,44 @@ export function expandComponentAuthoringShorthand(componentType, source) {
   return { source: JSON.stringify({ provider: target.provider, videoId: target.videoId, ...rest }) };
 }
 
+/**
+ * The card grid's image rules that need two fields (TR01326): imageHeight and
+ * imageAlign only mean something with `contain`, and a contained image is
+ * sized from its stored width and height. The published renderer's readiness
+ * check applies the same rules at the same paths.
+ */
+function validateCardImageFit(parsed, dataPath, errors) {
+  const fit = parsed.imageFit;
+  // An invalid imageFit was already reported by `validateFields`.
+  if (fit !== undefined && fit !== "cover" && fit !== "contain") return;
+  if (fit !== "contain") {
+    for (const field of ["imageHeight", "imageAlign"]) {
+      if (parsed[field] === undefined) continue;
+      errors.push(contentError(
+        `${dataPath}/${field}`,
+        CODES.componentData,
+        `${field} applies only when imageFit is "contain"; remove ${field}, or set imageFit to "contain".`,
+      ));
+    }
+    return;
+  }
+  if (!Array.isArray(parsed.cards)) return;
+  for (const [index, card] of parsed.cards.entries()) {
+    if (!isPlainObject(card) || !isPlainObject(card.image)) continue;
+    for (const dimension of ["width", "height"]) {
+      const value = card.image[dimension];
+      // A wrong-type dimension was already reported by `validateFields`.
+      if (value !== undefined && typeof value !== "number") continue;
+      if (value !== undefined && value !== 0) continue;
+      errors.push(contentError(
+        `${dataPath}/cards/${index}/image/${dimension}`,
+        CODES.componentData,
+        `With imageFit "contain" a card image needs its ${dimension} in pixels; upload the image again with media upload, or set imageFit to "cover".`,
+      ));
+    }
+  }
+}
+
 /**
  * Validates a `componentBlock`'s `componentType` and `componentData` pair.
  *
@@ -1097,6 +1477,7 @@ export function validateComponentBlock(componentType, componentData, basePath) {
   const fields = isComponentType(componentType) ? COMPONENT_SHAPES[componentType] : undefined;
   if (!fields) return errors;
   validateFields(fields, parsed, dataPath, errors);
+  if (componentType === "card-grid") validateCardImageFit(parsed, dataPath, errors);
   if (componentType === "card-grid" && Array.isArray(parsed.cards)) {
     for (const [index, card] of parsed.cards.entries()) {
       if (
@@ -1114,6 +1495,77 @@ export function validateComponentBlock(componentType, componentData, basePath) {
       }
     }
   }
+  if (componentType === "product-grid" && Array.isArray(parsed.items)) {
+    // Blank text is absent; a whitespace-only address is already refused by
+    // `safeUrl` above, so trimming it here adds no second error (TR01323).
+    for (const [index, item] of parsed.items.entries()) {
+      if (!isPlainObject(item)) continue;
+      // The editor keeps one feature per line, so a feature is one line.
+      if (Array.isArray(item.features)) {
+        for (const [featureIndex, feature] of item.features.entries()) {
+          if (typeof feature === "string" && /[\r\n]/u.test(feature)) {
+            errors.push(contentError(
+              `${dataPath}/items/${index}/features/${featureIndex}`,
+              CODES.componentData,
+              "A feature is one line; put the rest in another feature or the description.",
+            ));
+          }
+        }
+      }
+      // A wrong-type field or a whitespace-only address was refused by
+      // `validateFields` above; a second error at the same path would say
+      // nothing new, so each rule skips a pair with a wrong-type field and
+      // the other rule still runs, as the generator's readiness check does.
+      const wrongType = (field) => Object.hasOwn(item, field) && typeof item[field] !== "string";
+      if (!wrongType("buttonText") && !wrongType("buttonUrl")) {
+        const text = typeof item.buttonText === "string" ? item.buttonText.trim() : "";
+        const rawUrl = typeof item.buttonUrl === "string" ? item.buttonUrl : "";
+        const url = rawUrl.trim();
+        const urlAlreadyRefused = rawUrl.length > 0 && url.length === 0;
+        if (text.length > 0 && url.length === 0 && !urlAlreadyRefused) {
+          errors.push(contentError(
+            `${dataPath}/items/${index}/buttonUrl`,
+            CODES.componentData,
+            "A product with button text needs a buttonUrl, or clear the text.",
+          ));
+        }
+        if (url.length > 0 && text.length === 0) {
+          errors.push(contentError(
+            `${dataPath}/items/${index}/buttonText`,
+            CODES.componentData,
+            "A product with a buttonUrl needs buttonText, or clear the address.",
+          ));
+        }
+      }
+      if (!wrongType("price") && !wrongType("priceNote")) {
+        const price = typeof item.price === "string" ? item.price.trim() : "";
+        const note = typeof item.priceNote === "string" ? item.priceNote.trim() : "";
+        if (note.length > 0 && price.length === 0) {
+          errors.push(contentError(
+            `${dataPath}/items/${index}/price`,
+            CODES.componentData,
+            "A product with a priceNote needs a price, or clear the note.",
+          ));
+        }
+      }
+    }
+  }
+  if (componentType === "social-links" && Array.isArray(parsed.items)) {
+    // One error per label path: a blank label first, else a Website link
+    // without one. A wrong-type label or platform was refused above (TR01324).
+    for (const [index, item] of parsed.items.entries()) {
+      if (!isPlainObject(item)) continue;
+      if ((Object.hasOwn(item, "label") && typeof item.label !== "string") || typeof item.platform !== "string") continue;
+      const label = typeof item.label === "string" ? item.label : "";
+      const path = `${dataPath}/items/${index}/label`;
+      // The shared whitespace set, so no layer's own trim admits a label another refuses.
+      if (label !== "" && trimSocialLinkInput(label) === "") {
+        errors.push(contentError(path, CODES.componentData, "A label must have text, or leave it out."));
+      } else if (item.platform === "other" && trimSocialLinkInput(label) === "") {
+        errors.push(contentError(path, CODES.componentData, "A Website link needs a label."));
+      }
+    }
+  }
   if (
     componentType === "video-embed" && typeof parsed.provider === "string" && typeof parsed.videoId === "string"
     && (parsed.provider === "youtube" || parsed.provider === "vimeo")

package/src/content/free-form-section-registry.json

@@ -1,5 +1,5 @@
 {
-  "version": 12,
+  "version": 14,
   "section": {
     "nodeType": "section",
     "label": "Section",
@@ -548,7 +548,13 @@
     "card-grid": {
       "label": "Card Grid",
       "measure": "wide",
-      "rootPlacement": "flow"
+      "rootPlacement": "flow",
+      "imageSpacings": {
+        "none": "0rem",
+        "small": "1em",
+        "medium": "2em",
+        "text": "var(--esp-size-small-to-normal, 1rem)"
+      }
     },
     "image-banner": {
       "label": "Image Banner",
@@ -569,6 +575,42 @@
       "label": "Video embed",
       "measure": "wide",
       "rootPlacement": "flow"
+    },
+    "image-row": {
+      "label": "Image Row",
+      "measure": "wide",
+      "rootPlacement": "flow",
+      "maxItems": 12,
+      "heights": {
+        "small": "2.5rem",
+        "medium": "4rem",
+        "large": "6rem"
+      }
+    },
+    "product-grid": {
+      "label": "Product Grid",
+      "measure": "wide",
+      "rootPlacement": "flow",
+      "maxItems": 100,
+      "limits": {
+        "title": 80,
+        "price": 40,
+        "priceNote": 60,
+        "badge": 40,
+        "description": 240,
+        "feature": 80,
+        "features": 8,
+        "buttonText": 40
+      },
+      "imageAspectRatio": { "width": 16, "height": 9 }
+    },
+    "social-links": {
+      "label": "Social Links",
+      "measure": "wide",
+      "rootPlacement": "flow",
+      "maxItems": 12,
+      "limits": { "label": 120 },
+      "sizes": { "small": "1.5rem", "medium": "2rem", "large": "3rem" }
     }
   },
   "integrationPlacement": {

package/src/footer-contract.js

@@ -4,6 +4,8 @@ import {
   isContactOrWebUrl,
 } from "./contact-url.js";
 import { hasControlCharacter, isCanonicalUuid, SiteAuthoringError } from "./errors.js";
+import { isSocialLinkUrl, SOCIAL_LINK_URL_MAX_LENGTH, trimSocialLinkInput } from "./social-link-url.js";
+import socialPlatforms from "./social-platforms.json" with { type: "json" };
 import { FOOTER_COLOR_TOKENS, requireAppearanceColor } from "./theme-validation.js";
 
 export const FOOTER_LIMITS = Object.freeze({
@@ -12,6 +14,7 @@ export const FOOTER_LIMITS = Object.freeze({
   groupsPerColumn: 6,
   linksPerGroup: 12,
   bottomLinks: 8,
+  socialLinks: 12,
   richTextParagraphs: 12,
   richTextRuns: 200,
   groupHeadingLength: 80,
@@ -56,10 +59,12 @@ export const FOOTER_FIELD_INVENTORY = Object.freeze({
     "bottomContent",
     "featureImage",
     "showBrandText",
+    "socialLinks",
   ]),
   FooterLinkColumn: Object.freeze(["id", "groups"]),
   FooterLinkGroup: Object.freeze(["id", "heading", "links"]),
   FooterLink: Object.freeze(["id", "label", "pageResourceId", "externalUrl"]),
+  FooterSocialLink: Object.freeze(["id", "platform", "url", "label"]),
   FooterRichText: Object.freeze(["paragraphs"]),
   FooterRichTextParagraph: Object.freeze(["runs"]),
   FooterRichTextRun: Object.freeze(["text", "bold", "italic", "underline", "link"]),
@@ -82,6 +87,13 @@ export const FOOTER_FIELD_INVENTORY = Object.freeze({
   FooterFeatureResponsiveImageUrl: Object.freeze(["minWidth", "url"]),
 });
 
+/** The platform keys a footer social link may name, in the vocabulary's order; `other` is the Website link. */
+export const SOCIAL_PLATFORM_KEYS = Object.freeze(socialPlatforms.platforms.map((platform) => platform.key));
+export const OTHER_SOCIAL_PLATFORM = "other";
+export const SOCIAL_LINK_URL_REQUIREMENT =
+  `must be an absolute https URL without credentials, at most ${SOCIAL_LINK_URL_MAX_LENGTH} characters, `
+  + "to a domain name of unaccented letters, digits and hyphens, like https://www.instagram.com/yourname";
+
 export const FOOTER_READ_ONLY_FIELDS = Object.freeze([
   "light.backgroundImageUrl",
   "dark.backgroundImageUrl",
@@ -314,6 +326,40 @@ function footerLink(value, path, seenLinkIds, knownPageResourceIds, tolerateStor
   };
 }
 
+// Mirrors the server's social-link rules (TR01324) in the same order: the id
+// shares the footer's seen set, the platform is a vocabulary key, the address
+// is judged after the shared trim, and a label is optional text that is
+// refused when it is only whitespace and required for a Website link.
+function socialLink(value, path, seenLinkIds, tolerateStoredValues) {
+  value = object(value, path);
+  closed(value, "FooterSocialLink", path);
+  const id = stableId(value.id, `${path}.id`, seenLinkIds, "link");
+  // A stored platform that later leaves the vocabulary must still pull, as a
+  // stored bottom-link address does; only an authored document is refused.
+  if (typeof value.platform !== "string" || (!tolerateStoredValues && !SOCIAL_PLATFORM_KEYS.includes(value.platform))) {
+    fail("footer.field_invalid", `${path}.platform must be one of ${SOCIAL_PLATFORM_KEYS.join(", ")}.`, `${path}.platform`);
+  }
+  if (typeof value.url !== "string") {
+    fail("footer.url_invalid", `${path}.url ${SOCIAL_LINK_URL_REQUIREMENT}.`, `${path}.url`);
+  }
+  const url = trimSocialLinkInput(value.url);
+  if (!tolerateStoredValues && !isSocialLinkUrl(url)) {
+    fail("footer.url_invalid", `${path}.url ${SOCIAL_LINK_URL_REQUIREMENT}.`, `${path}.url`);
+  }
+  const rawLabel = value.label === undefined ? "" : value.label;
+  const label = normalizedSingleLine(rawLabel, FOOTER_LIMITS.linkLabelLength, `${path}.label`, { tolerateStoredValues });
+  if (!tolerateStoredValues) {
+    // Blank is judged with the shared whitespace set, as the page component and the handler judge it.
+    if (rawLabel.length > 0 && trimSocialLinkInput(label) === "") {
+      fail("footer.text_required", `${path}.label: A label must have text, or leave it out.`, `${path}.label`);
+    }
+    if (trimSocialLinkInput(label) === "" && value.platform === OTHER_SOCIAL_PLATFORM) {
+      fail("footer.text_required", `${path}.label: A Website link needs a label.`, `${path}.label`);
+    }
+  }
+  return { id, platform: value.platform, url, label };
+}
+
 function footerLinks(values, path, maximum, seenLinkIds, knownPageResourceIds, tolerateStoredValues) {
   return array(values, path, maximum).map((value, index) =>
     footerLink(value, `${path}[${index}]`, seenLinkIds, knownPageResourceIds, tolerateStoredValues)
@@ -463,6 +509,7 @@ export function footerDefaults() {
     bottomContent: { paragraphs: [] },
     featureImage: undefined,
     showBrandText: true,
+    socialLinks: [],
   };
 }
 
@@ -571,6 +618,8 @@ function normalizeFooterDocument(
     ),
     ...(normalizedFeatureImage === undefined ? {} : { featureImage: normalizedFeatureImage }),
     showBrandText: boolean(value.showBrandText, true, "footerSettings.showBrandText"),
+    socialLinks: array(value.socialLinks, "footerSettings.socialLinks", FOOTER_LIMITS.socialLinks)
+      .map((link, index) => socialLink(link, `footerSettings.socialLinks[${index}]`, seenLinkIds, tolerateStoredValues)),
   };
 }
 
@@ -684,4 +733,14 @@ export const FOOTER_EXAMPLE = Object.freeze({
     alt: "A sunlit creative studio with books, artwork, and a writing desk",
   }),
   showBrandText: true,
+  // The icon row between the bottom content and the bottom links. A label is
+  // the link's text; without one the platform's name is read out.
+  socialLinks: Object.freeze([
+    Object.freeze({
+      id: "7c1f3a52-9d4e-4b8a-8f1e-2a6c9d0e4b11",
+      platform: "instagram",
+      url: "https://www.instagram.com/examplestudio",
+      label: "Example Studio on Instagram",
+    }),
+  ]),
 });

package/src/footer-draft-hash.js

@@ -88,7 +88,7 @@ export function stableJson(value) {
 // the canonical form.
 export function computeFooterDraftHash(settings = {}) {
   const canonical = [];
-  append(canonical, "footer-draft-v3");
+  append(canonical, "footer-draft-v4");
   append(canonical, settings.enabled === true);
   append(canonical, settings.showBrand ?? true);
   append(canonical, settings.showBrandText ?? true);
@@ -113,6 +113,7 @@ export function computeFooterDraftHash(settings = {}) {
   if (hasAsideCta) appendLink(canonical, settings.asideCta);
   appendRichText(canonical, settings.bottomContent);
   appendLinks(canonical, settings.bottomLinks);
+  appendSocialLinks(canonical, settings.socialLinks);
   appendScheme(canonical, settings.light);
   appendScheme(canonical, settings.dark);
 
@@ -132,6 +133,18 @@ function appendLinks(canonical, rawLinks) {
   for (const link of links) appendLink(canonical, link);
 }
 
+function appendSocialLinks(canonical, rawLinks) {
+  const links = Array.isArray(rawLinks) ? rawLinks : [];
+  append(canonical, links.length);
+  for (const rawLink of links) {
+    const link = rawLink ?? {};
+    append(canonical, normalizeId(link.id));
+    append(canonical, link.platform ?? "");
+    append(canonical, link.url ?? "");
+    append(canonical, link.label ?? "");
+  }
+}
+
 // Coalesce rather than default so the canonical form stays total even for a
 // null entry: a parameter default covers only undefined.
 function appendLink(canonical, rawLink) {

package/src/presentation-reference.js

@@ -35,6 +35,8 @@ import {
   FOOTER_FIELD_INVENTORY,
   FOOTER_LIMITS,
   FOOTER_READ_ONLY_FIELDS,
+  SOCIAL_LINK_URL_REQUIREMENT,
+  SOCIAL_PLATFORM_KEYS,
   validateFooterDocument,
 } from "./footer-contract.js";
 import {
@@ -589,6 +591,11 @@ const FOOTER_FIELD_DETAILS = Object.freeze({
     maximumParagraphs: FOOTER_LIMITS.richTextParagraphs,
   },
   "FooterSettings.bottomLinks": { type: "FooterLink[]", default: [], maximumItems: FOOTER_LIMITS.bottomLinks },
+  "FooterSettings.socialLinks": {
+    type: "FooterSocialLink[]",
+    default: [],
+    maximumItems: FOOTER_LIMITS.socialLinks,
+  },
   "FooterSettings.light": { type: "FooterSchemeSettings", default: "scheme defaults" },
   "FooterSettings.dark": { type: "FooterSchemeSettings", default: "scheme defaults" },
   "FooterSettings.featureImage": { type: "FooterFeatureImageSettings|null", default: null },
@@ -609,6 +616,14 @@ const FOOTER_FIELD_DETAILS = Object.freeze({
     exclusiveWith: "pageResourceId",
     maximumLength: FOOTER_LIMITS.externalUrlLength,
   },
+  "FooterSocialLink.id": { type: "canonical-lowercase-uuid", required: true },
+  "FooterSocialLink.platform": { type: "social-platform-key", required: true, values: SOCIAL_PLATFORM_KEYS },
+  "FooterSocialLink.url": { type: "https-url", required: true, maximumLength: FOOTER_LIMITS.externalUrlLength },
+  "FooterSocialLink.label": {
+    type: "plain-text",
+    requiredWhen: "platform is other",
+    maximumLength: FOOTER_LIMITS.linkLabelLength,
+  },
   "FooterRichText.paragraphs": { type: "FooterRichTextParagraph[]", default: [] },
   "FooterRichTextParagraph.runs": { type: "FooterRichTextRun[]", default: [] },
   "FooterRichTextRun.text": { type: "string", required: true },
@@ -703,6 +718,12 @@ export function getFooterReference() {
       "Each link has exactly one target: a tracked pageResourceId, or an externalUrl that is an absolute "
       + "credential-free http/https URL, or a mailto:/tel: contact URL such as tel:+15555550123. A contact URL is "
       + "published exactly as authored, so write the number the way it should be dialled.",
+    socialLinkRule:
+      "Each social link names a platform key (" + SOCIAL_PLATFORM_KEYS.join(", ") + ") and a url that "
+      + SOCIAL_LINK_URL_REQUIREMENT + ". The label is the link's text and what screen readers announce; "
+      + "leave it empty to use the platform's name, and give one to every other (Website) link. Domain names "
+      + "with accented or non-English letters are not supported here; use a bottom link for that site. "
+      + "The row renders between the bottom content and the bottom links.",
     imageRule:
       "Image ids come from pull or media upload. Feature images require alt text; background art is decorative.",
     readOnlyProjections: FOOTER_READ_ONLY_FIELDS,
@@ -837,7 +858,8 @@ export function formatPresentationReference(reference) {
     ).join("\n\n");
     return reference.title + "\nUsage: " + reference.usage + "\nWorkspace: "
       + reference.workspaceFile + " :: " + reference.workspacePath + "\n\nClosed schema:\n"
-      + messages + "\n\nTargets: " + reference.targetRule + "\nImages: " + reference.imageRule
+      + messages + "\n\nTargets: " + reference.targetRule + "\nSocial links: " + reference.socialLinkRule
+      + "\nImages: " + reference.imageRule
       + "\nConcurrency: " + reference.concurrency
       + "\nTheme interaction: " + reference.themeInteraction + "\nRead-only projections: "
       + reference.readOnlyProjections.join(", ") + "\n\nWorkflow:\n"

package/src/reference-help.js

@@ -95,7 +95,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getSettingsReference, getThemeReference };
 
-export const REFERENCE_VERSION = 47;
+export const REFERENCE_VERSION = 49;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -1938,6 +1938,7 @@ function schemaConstraints(schema) {
   const constraints = [];
   if (schema.minimum !== undefined) constraints.push(`minimum ${schema.minimum}`);
   if (schema.maximum !== undefined) constraints.push(`maximum ${schema.maximum}`);
+  if (schema.minItems !== undefined) constraints.push(`minimum ${schema.minItems} items`);
   if (schema.maxItems !== undefined) constraints.push(`maximum ${schema.maxItems} items`);
   if (schema.minLength !== undefined) constraints.push(`minimum length ${schema.minLength}`);
   if (schema.maxLength !== undefined) constraints.push(`maximum length ${schema.maxLength}`);
@@ -1953,7 +1954,12 @@ function schemaConstraints(schema) {
 
 function formatSchemaLine(name, schema, required, indent) {
   const constraints = schemaConstraints(schema);
-  const label = schema.markdownType ? "media path | null in Markdown; object | null in .pm.json" : schemaLabel(schema);
+  // A required image (TR01322) takes no null in either form.
+  const label = schema.markdownType
+    ? Array.isArray(schema.type)
+      ? "media path | null in Markdown; object | null in .pm.json"
+      : "media path in Markdown; object in .pm.json"
+    : schemaLabel(schema);
   return `${indent}${name.padEnd(Math.max(1, 28 - indent.length))} ${label}; ${
     required ? "required" : "optional"
   }${constraints.length > 0 ? `; ${constraints.join("; ")}` : ""}`;

package/src/site-checks.js

@@ -159,7 +159,9 @@ function addHtmlLinks(links, html, currentPagePath) {
 }
 function isUrlProperty(name) {
     const lower = name.toLowerCase();
-    return lower === "href" || lower === "url" || lower === "link" || lower === "pagepath";
+    // Component buttons and cards (cta, card-grid, product-grid; TR01323).
+    return lower === "href" || lower === "url" || lower === "link" || lower === "pagepath"
+        || lower === "buttonurl" || lower === "linkurl";
 }
 function addEncodedComponentLinks(links, value, currentPagePath) {
     const decoded = htmlDecodeRepeatedly(value);

package/src/social-link-url.js

@@ -0,0 +1,160 @@
+// Generated from shared/social-link-url.ts by scripts/sync-field-validation.mjs. Do not edit.
+/**
+ * The one owner of which addresses a social link accepts (TR01324).
+ *
+ * A social link is an absolute https URL to a plain domain name. The rule is
+ * literal on purpose: every verdict a URL parser might decide differently in
+ * JavaScript and .NET (case folding, IDNA mapping, IPv4 shorthand, length
+ * limits, whitespace) is decided here by explicit character checks first, and
+ * the parser is only asked whether what remains parses at all. That keeps the
+ * CLI, the generator, the editor and the API's own port in agreement, which
+ * `shared/social-link-url-corpus.json` proves in each of them.
+ *
+ * It is pure and dependency-free. The generator and the site-authoring CLI
+ * cannot import this file, so `node scripts/sync-field-validation.mjs` writes
+ * their copies; edit only this file and re-run it. The editor imports it by
+ * relative path.
+ */
+/** The longest address stored anywhere a social link lives. */
+export const SOCIAL_LINK_URL_MAX_LENGTH = 2048;
+/**
+ * The whitespace a social link may not contain and a typed value is trimmed
+ * of: the .NET `char.IsWhiteSpace` set, which the footer's single-line
+ * normalisation already mirrors, plus U+FEFF, which JavaScript's `trim` strips
+ * and .NET's does not.
+ */
+export function isSocialLinkWhiteSpace(codeUnit) {
+    return (codeUnit >= 0x0009 && codeUnit <= 0x000d)
+        || codeUnit === 0x0020
+        || codeUnit === 0x0085
+        || codeUnit === 0x00a0
+        || codeUnit === 0x1680
+        || (codeUnit >= 0x2000 && codeUnit <= 0x200a)
+        || codeUnit === 0x2028
+        || codeUnit === 0x2029
+        || codeUnit === 0x202f
+        || codeUnit === 0x205f
+        || codeUnit === 0x3000
+        || codeUnit === 0xfeff;
+}
+/** Strips the whitespace set above from both ends; what a typed address is judged on. */
+export function trimSocialLinkInput(value) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && isSocialLinkWhiteSpace(value.charCodeAt(start)))
+        start += 1;
+    while (end > start && isSocialLinkWhiteSpace(value.charCodeAt(end - 1)))
+        end -= 1;
+    return value.slice(start, end);
+}
+/**
+ * Control characters, the backslash, and the default-ignorable and format
+ * code points that can hide inside an address; none has a place in a link.
+ */
+function isRefusedCodeUnit(codeUnit) {
+    return codeUnit <= 0x001f
+        || (codeUnit >= 0x007f && codeUnit <= 0x009f)
+        || codeUnit === 0x005c
+        || codeUnit === 0x00ad
+        || codeUnit === 0x034f
+        || (codeUnit >= 0x200b && codeUnit <= 0x200f)
+        || (codeUnit >= 0x202a && codeUnit <= 0x202e)
+        || (codeUnit >= 0x2060 && codeUnit <= 0x206f)
+        || (codeUnit >= 0xfe00 && codeUnit <= 0xfe0f)
+        || codeUnit >= 0xfff0;
+}
+/** Folds only A to Z, so no runtime's case mapping (U+212A to k, U+0130) can reach a verdict; the editors' field copy reads it too. */
+export function asciiLower(value) {
+    let result = "";
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        result += codeUnit >= 0x41 && codeUnit <= 0x5a ? String.fromCharCode(codeUnit + 0x20) : value[index];
+    }
+    return result;
+}
+const LABEL_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
+/** A final label that is a number in decimal or hex makes the host an IPv4 form, which is refused. */
+const NUMERIC_FINAL_LABEL_RE = /^(?:[0-9]+|0[xX][0-9a-fA-F]*)$/;
+const PORT_RE = /^[0-9]+$/;
+const HOST_MAX_LENGTH = 253;
+const LABEL_MAX_LENGTH = 63;
+function isAcceptedAuthority(authority) {
+    if (authority.length === 0)
+        return false;
+    for (let index = 0; index < authority.length; index += 1) {
+        const codeUnit = authority.charCodeAt(index);
+        if (codeUnit > 0x7f)
+            return false;
+        const character = authority[index];
+        if (character === "@" || character === "%" || character === "_")
+            return false;
+    }
+    let host = authority;
+    const colon = authority.indexOf(":");
+    if (colon !== -1) {
+        host = authority.slice(0, colon);
+        const port = authority.slice(colon + 1);
+        if (!PORT_RE.test(port))
+            return false;
+        const portNumber = Number(port);
+        if (portNumber < 1 || portNumber > 65535)
+            return false;
+    }
+    if (host.length > HOST_MAX_LENGTH)
+        return false;
+    const labels = host.split(".");
+    if (labels.length < 2)
+        return false;
+    for (const label of labels) {
+        if (label.length < 1 || label.length > LABEL_MAX_LENGTH || !LABEL_RE.test(label))
+            return false;
+        if (asciiLower(label).startsWith("xn--"))
+            return false;
+    }
+    return !NUMERIC_FINAL_LABEL_RE.test(labels[labels.length - 1]);
+}
+/**
+ * Whether a value, exactly as written, is an address a social link accepts.
+ * Typed input is trimmed with `trimSocialLinkInput` first; a hand-written
+ * document is judged as it is.
+ */
+export function isSocialLinkUrl(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > SOCIAL_LINK_URL_MAX_LENGTH)
+        return false;
+    for (let index = 0; index < value.length; index += 1) {
+        const codeUnit = value.charCodeAt(index);
+        if (isSocialLinkWhiteSpace(codeUnit) || isRefusedCodeUnit(codeUnit))
+            return false;
+        if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+            const next = index + 1 < value.length ? value.charCodeAt(index + 1) : 0;
+            if (next < 0xdc00 || next > 0xdfff)
+                return false;
+            index += 1;
+        }
+        else if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+            return false;
+        }
+    }
+    if (asciiLower(value.slice(0, 8)) !== "https://")
+        return false;
+    const rest = value.slice(8);
+    let authorityEnd = rest.length;
+    for (const terminator of ["/", "?", "#"]) {
+        const at = rest.indexOf(terminator);
+        if (at !== -1 && at < authorityEnd)
+            authorityEnd = at;
+    }
+    if (!isAcceptedAuthority(rest.slice(0, authorityEnd)))
+        return false;
+    try {
+        new URL(value);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+/** The address as published: the parsed form, as the footer emits its own links. */
+export function socialLinkHref(value) {
+    return new URL(value).toString();
+}

package/src/social-platforms.json

@@ -0,0 +1,16 @@
+{
+  "platforms": [
+    { "key": "instagram", "name": "Instagram", "icon": "brand-instagram" },
+    { "key": "facebook", "name": "Facebook", "icon": "brand-facebook" },
+    { "key": "yelp", "name": "Yelp", "icon": "brand-yelp" },
+    { "key": "youtube", "name": "YouTube", "icon": "brand-youtube" },
+    { "key": "tiktok", "name": "TikTok", "icon": "brand-tiktok" },
+    { "key": "linkedin", "name": "LinkedIn", "icon": "brand-linkedin" },
+    { "key": "x", "name": "X", "icon": "brand-x" },
+    { "key": "threads", "name": "Threads", "icon": "brand-threads" },
+    { "key": "bluesky", "name": "Bluesky", "icon": "brand-bluesky" },
+    { "key": "mastodon", "name": "Mastodon", "icon": "brand-mastodon" },
+    { "key": "pinterest", "name": "Pinterest", "icon": "brand-pinterest" },
+    { "key": "other", "name": "Website", "icon": "external-link" }
+  ]
+}