@taprootio/site-authoring 0.26.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.26.0",
+  "version": "0.27.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,19 @@
 {
   "entries": [
+    {
+      "version": "0.27.0",
+      "note": "Embedded forms inherit configurable background, border and shadow defaults from the site, with per-form overrides.",
+      "behavior": [
+        "Form definitions accept sparse presentation.background, presentation.border and presentation.shadow boolean overrides. Omitted values inherit the site; explicit false disables the decoration. An empty presentation object is omitted by the form editor.",
+        "Site publishing preferences expose formBoxBackground, formBoxBorder and formBoxShadow. Background and shadow default on; border defaults off. Stage publishing preferences and the form version to apply appearance changes.",
+        "Forms pull and push preserve appearance overrides, including explicit false.",
+        "The help reference version is 44."
+      ],
+      "help": [
+        "forms",
+        "settings"
+      ]
+    },
     {
       "version": "0.26.0",
       "note": "marketing pull and marketing push keep a site's campaigns and placements as files, and link build prints a tracked address, so an agent can run a site's attribution over the CLI.",

package/src/field-schema.json

@@ -22,6 +22,17 @@
       "type": "string",
       "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
     },
+    "presentation": {
+      "description": "Sparse embedded-form appearance choices. Omitted properties inherit the site's staged defaults; explicit false disables a choice. Omit the object when all choices inherit.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": false,
+      "properties": {
+        "background": { "type": "boolean" },
+        "border": { "type": "boolean" },
+        "shadow": { "type": "boolean" }
+      }
+    },
     "submit_label": {
       "description": "The text on the submit button. Omit it for Taproot's default. Must contain more than whitespace; the validator also rejects a blank label, which a schema cannot express.",
       "type": "string",

package/src/field-validation.js

@@ -106,7 +106,7 @@ export function contactFieldId(definition) {
     const emails = definition.fields.filter((field) => field.type === "email");
     return emails.length === 1 ? emails[0].id : undefined;
 }
-const DEFINITION_KEYS = ["fields", "contact_field", "submit_label", "after_submit", "newsletter_audience_id"];
+const DEFINITION_KEYS = ["fields", "contact_field", "submit_label", "after_submit", "newsletter_audience_id", "presentation"];
 const BASE_FIELD_KEYS = ["id", "type", "label", "hint"];
 const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const isInteger = (value) => typeof value === "number" && Number.isInteger(value);
@@ -427,6 +427,22 @@ export function validateDefinition(definition) {
 }
 /** The button text and the after-submit choice, which sit beside the fields in a definition. */
 function validateFormSettings(definition, errors) {
+    if ("presentation" in definition) {
+        const presentation = definition.presentation;
+        if (!isPlainObject(presentation) || Object.keys(presentation).length === 0) {
+            errors.push({ path: "presentation", code: "invalid_presentation" });
+        }
+        else {
+            for (const key of sortedKeys(presentation)) {
+                if (key !== "background" && key !== "border" && key !== "shadow") {
+                    errors.push({ path: `presentation.${key}`, code: "unknown_property" });
+                }
+                else if (typeof presentation[key] !== "boolean") {
+                    errors.push({ path: `presentation.${key}`, code: "invalid_presentation_value" });
+                }
+            }
+        }
+    }
     const audience = definition.newsletter_audience_id;
     if (audience !== undefined && (typeof audience !== "string" || !isResourceId(audience))) {
         errors.push({ path: "newsletter_audience_id", code: "invalid_newsletter_audience" });

package/src/forms-contract.js

@@ -6,7 +6,7 @@ import { contactFieldId, validateDefinition } from "./field-validation.js";
  *
  * A form is one JSON file, `forms/<key>.json`, holding what an author decides:
  * its key, name, sink, retention, owner-notification preference and definition. The definition holds the fields
- * and the form's own settings (`contact_field`, `submit_label`, `after_submit`),
+ * and the form's own settings (`contact_field`, `submit_label`, `after_submit`, `presentation`),
  * exactly as the site stores it, so one validator reads one shape. The
  * definition's own rules belong to `shared/field-validation.ts` and are run
  * here through the generated copy, so this file never restates them. The one
@@ -289,6 +289,20 @@ export function projectFormForWorkspace(form, pathById) {
   if (form.definition.after_submit !== undefined) {
     definition.after_submit = canonicalAfterSubmit(form.definition.after_submit, pathById);
   }
+  if (form.definition.newsletter_audience_id !== undefined) {
+    definition.newsletter_audience_id = form.definition.newsletter_audience_id;
+  }
+  if (form.definition.presentation !== undefined) {
+    const presentation = {};
+    for (const name of ["background", "border", "shadow", ...Object.keys(form.definition.presentation).sort()]) {
+      if (form.definition.presentation[name] !== undefined) presentation[name] = form.definition.presentation[name];
+    }
+    definition.presentation = presentation;
+  }
+  // Preserve future properties on pull so an older workspace cannot silently erase them.
+  for (const name of Object.keys(form.definition).sort()) {
+    if (name !== "contact_field" && definition[name] === undefined) definition[name] = form.definition[name];
+  }
   return {
     key: form.key,
     ...projectFormSettings(form),

package/src/reference-help.js

@@ -95,7 +95,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getSettingsReference, getThemeReference };
 
-export const REFERENCE_VERSION = 43;
+export const REFERENCE_VERSION = 44;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -883,6 +883,11 @@ const WORKFLOW_REFERENCES = Object.freeze({
       + "the visitor saw it, so a response shows what each box agreed to.",
       "Editing a definition appends a version on the site; versions are never changed. A page keeps the form "
       + "version it was published with until the next deploy, and a rollback restores the form it shipped with.",
+      "definition.presentation optionally overrides the site's form appearance: background, border and shadow are "
+      + "optional booleans. Omit a property to inherit the corresponding site preference (formBoxBackground, "
+      + "formBoxBorder, formBoxShadow); false turns that choice off. Omit presentation when all three inherit: an empty "
+      + "object is refused. Site defaults are background on, border off and shadow on. Background can be off while border "
+      + "and shadow remain on. The release freezes both the form choices and the site defaults.",
       "Both verbs write the file in one canonical key order, so a pulled file pushed back unchanged reports "
       + "'unchanged' and leaves the bytes as they were. Write your own files in that order and a push rewrites "
       + "nothing you did not change.",

package/src/setting-reference.js

@@ -272,6 +272,24 @@ const PREFERENCES_ENTRIES = {
       + "a deployment.",
     false,
   ),
+  formBoxBackground: entry(
+    `${FEATURES} > Form appearance > Background`,
+    "Whether embedded forms have a box background by default. A form's presentation.background overrides this choice.",
+    "Embedded forms, including validation and confirmation. A change applies after deployment.",
+    true,
+  ),
+  formBoxBorder: entry(
+    `${FEATURES} > Form appearance > Border`,
+    "Whether embedded forms have a border by default. A form's presentation.border overrides this choice.",
+    "Embedded forms. Independent of background and shadow; applies after deployment.",
+    false,
+  ),
+  formBoxShadow: entry(
+    `${FEATURES} > Form appearance > Shadow`,
+    "Whether embedded forms have a shadow by default. A form's presentation.shadow overrides this choice.",
+    "Embedded forms. Independent of background and border; applies after deployment.",
+    true,
+  ),
   tiptapImageMaxHeightVh: entry(
     `${FEATURES} > Image height`,
     "The tallest an image in a page body may be, as a percent of the screen height (45, 60, 75 or 90).",

package/src/settings-catalog.js

@@ -130,6 +130,9 @@ export const SETTINGS_GROUPS = Object.freeze([
       // Asks readers before the visit cookie is set (TR01263). Off is what an omitted value means, so a snapshot of
       // an untouched site reads the same as the site behaves.
       { name: "analyticsConsentPrompt", wireType: "boolean" },
+      { name: "formBoxBackground", wireType: "boolean", zero: true },
+      { name: "formBoxBorder", wireType: "boolean" },
+      { name: "formBoxShadow", wireType: "boolean", zero: true },
       { name: "tiptapImageMaxHeightVh", wireType: "int" },
       { name: "tiptapImageMaxImagesPerRow", wireType: "int" },
       { name: "tiptapImageBorderWidth", wireType: "int" },
@@ -146,7 +149,7 @@ export const CANDIDATE_SELECTABLE_SETTINGS_TYPES = Object.freeze(
 );
 
 function zeroValue(field) {
-  if (field.wireType === "boolean") return false;
+  if (field.wireType === "boolean") return field.zero ?? false;
   if (field.wireType === "int" || field.wireType === "double") return 0;
   if (field.wireType === "theme" || field.wireType === "document") return field.zero ?? {};
   return field.zero ?? "";