@taprootio/site-authoring 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.1.1",
+  "version": "0.2.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",
@@ -27,7 +27,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@taprootio/espalier": "4.6.0"
+    "@taprootio/espalier": "4.7.0"
   },
   "scripts": {
     "test": "node --test",

package/src/appearance-contract.js

@@ -40,6 +40,20 @@ export const APPEARANCE_SCALAR_FIELDS = Object.freeze([
     type: "string",
     default: "",
   }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_TAPROOT_STYLES,
+    name: "fontMenu",
+    path: "taproot-styles.fontMenu",
+    type: "string",
+    default: "",
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_TAPROOT_STYLES,
+    name: "fontWeightMenu",
+    path: "taproot-styles.fontWeightMenu",
+    type: "string",
+    default: "",
+  }),
   ...["lightLogoId", "darkLogoId", "lightCanvasImageId", "darkCanvasImageId"].map((name) =>
     Object.freeze({
       settingsType: SETTINGS_TYPE_TAPROOT_STYLES,
@@ -72,9 +86,33 @@ export const APPEARANCE_SCALAR_FIELDS = Object.freeze([
     name: "headerLayout",
     path: "site-header.headerLayout",
     type: "enum",
-    values: Object.freeze(["standard", "centered-brand", "minimal"]),
+    values: Object.freeze(["standard", "centered-brand", "minimal", "centered-menu"]),
     default: "standard",
   }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_SITE_HEADER,
+    name: "headerWidth",
+    path: "site-header.headerWidth",
+    type: "enum",
+    values: Object.freeze(["contained", "wide"]),
+    default: "contained",
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_SITE_HEADER,
+    name: "navDrawerStyle",
+    path: "site-header.navDrawerStyle",
+    type: "enum",
+    values: Object.freeze(["panel", "full-screen"]),
+    default: "full-screen",
+  }),
+  Object.freeze({
+    settingsType: SETTINGS_TYPE_SITE_HEADER,
+    name: "navDrawerTransition",
+    path: "site-header.navDrawerTransition",
+    type: "enum",
+    values: Object.freeze(["fade", "slide-down", "slide-up", "slide-left", "slide-right"]),
+    default: "fade",
+  }),
   Object.freeze({
     settingsType: SETTINGS_TYPE_SITE_HEADER,
     name: "brandText",

package/src/constants.js

@@ -1,5 +1,5 @@
 export const CLI_NAME = "@taprootio/site-authoring";
-export const CLI_VERSION = "0.1.1";
+export const CLI_VERSION = "0.2.0";
 export const CLI_BINARY_NAME = "taproot-site";
 export const RESULT_SCHEMA_VERSION = 1;
 export const CONFIG_FILE_NAME = "taproot-site.json";

package/src/presentation-reference.js

@@ -57,6 +57,12 @@ function getEspalierVersion() {
 
 const OPTIONAL_THEME_FIELDS = Object.freeze([
   "explicitMappingTokens",
+  // Espalier 4.7.0 menu typography: documented so the theme help covers the
+  // installed contract, optional so pulled baselines that predate it stay
+  // complete (the server seeds and requires the fields listed in
+  // DefaultSiteTheme.RequiredProperties only).
+  "fontMenu",
+  "fontWeightMenu",
   "boxBackgroundImage",
   "boxBackgroundImageOpacity",
   "vellumOpacity",
@@ -201,8 +207,12 @@ const THEME_GROUPS = Object.freeze([
       ...["fontBody", "fontHeadings", "fontBrand", "fontMonospace"].map((name) =>
         themeField(name, "CSS font-family; empty inherits the consuming surface's fallback.")
       ),
-      ...["fontWeightBody", "fontWeightHeadings", "fontWeightBrand", "fontWeightMonospace"].map((name) =>
-        themeField(name, "CSS font-weight: 1–1000, normal/bold/lighter/bolder, or a CSS-wide keyword.")
+      themeField(
+        "fontMenu",
+        "CSS font-family for navigation menu items and group labels; empty falls back to fontBody, never to headings.",
+      ),
+      ...["fontWeightBody", "fontWeightHeadings", "fontWeightBrand", "fontWeightMonospace", "fontWeightMenu"].map(
+        (name) => themeField(name, "CSS font-weight: 1–1000, normal/bold/lighter/bolder, or a CSS-wide keyword."),
       ),
       themeField("rootFontSize", "Root font size in px.", { minimum: 1, warningMaximum: 100 }),
       themeField("typeRatio", "Modular type-scale ratio.", { exclusiveMinimum: 1, warningMaximum: 1.3 }),
@@ -330,6 +340,18 @@ export function getAppearanceReference() {
       "Use site-owned image ids retained from pull or returned by media upload. URLs are server projections, never authored inputs.",
     logoContract:
       "lightLogoId and darkLogoId are the current scheme-specific logo fields; there is no separate compact-logo setting.",
+    headerWidthContract:
+      "headerWidth 'contained' keeps the brand and the header buttons at the page content edges; "
+      + "'wide' moves them to the viewport edges. Pages with root-band components (image-banner) span the viewport, "
+      + "so full-bleed designs usually pair headerWidth 'wide' with headerLayout 'centered-menu', which keeps the "
+      + "brand left, the buttons right, and the navigation centered. validate prints a hint, never a failure, when a "
+      + "root-band page ships with a contained header.",
+    menuContract:
+      "navDrawerStyle 'full-screen' (the published default) opens the mobile menu over the whole viewport with the "
+      + "brand centered above large centered items and navDrawerTransition choosing how it appears (fade, slide-down, "
+      + "slide-up, slide-left, or slide-right); 'panel' keeps the side panel, which exists for application-style "
+      + "menus with many groups. fontMenu and fontWeightMenu set the navigation face the way fontBrand sets the "
+      + "brand; an empty fontMenu falls back to the body font, never to headings.",
     mutationOrder: [
       "fresh footer read plus concurrency-protected ten-color overlay",
       "default scheme, brand fonts and assets, favicon, and header scalars",
@@ -577,6 +599,8 @@ export function formatPresentationReference(reference) {
       + "\n\nRead-only server projections:\n"
       + reference.readOnlyProjections.map((field) => "  " + field.file + " :: " + field.path).join("\n")
       + "\n\nImages: " + reference.imageReferences + "\nLogos: " + reference.logoContract
+      + "\nHeader width: " + reference.headerWidthContract
+      + "\nMobile menu and menu font: " + reference.menuContract
       + "\nFooter: " + reference.footerBoundary
       + "\nFooter content guard: " + reference.footerContentGuard + "\n\nMutation order (non-atomic):\n"
       + reference.mutationOrder.map((step, index) => "  " + (index + 1) + ". " + step).join("\n")

package/src/settings-catalog.js

@@ -58,6 +58,8 @@ export const SETTINGS_GROUPS = Object.freeze([
         "defaultScheme",
         "fontBrand",
         "fontWeightBrand",
+        "fontMenu",
+        "fontWeightMenu",
         "lightLogoId",
         "lightLogoUrl",
         "darkLogoId",
@@ -86,6 +88,9 @@ export const SETTINGS_GROUPS = Object.freeze([
     fields: Object.freeze([
       ...stringFields(
         "headerLayout",
+        "headerWidth",
+        "navDrawerStyle",
+        "navDrawerTransition",
         "brandText",
         "brandColor",
         "logoAlt",

package/src/verbs/validate.js

@@ -2,7 +2,7 @@ import { lstat, realpath } from "node:fs/promises";
 import path from "node:path";
 
 import { NAVIGATION_MAXIMUM_DEPTH, TEMPLATE_TYPE_FREE_FORM } from "../api.js";
-import { sharedThemeContextNames } from "../content/free-form-sections.js";
+import { freeFormRootPresentation, sharedThemeContextNames } from "../content/free-form-sections.js";
 import { VERB_VALIDATE } from "../constants.js";
 import { isCanonicalUuid, SiteAuthoringError } from "../errors.js";
 import { FOOTER_SETTINGS_FILE } from "../footer-workspace.js";
@@ -340,6 +340,34 @@ function validatePageImageReferences(value, field, knownImageIds, deliveryOrigin
   }
 }
 
+/** Whether a validated page document places a root-band component at its root. */
+function pageUsesRootBand(document) {
+  return Array.isArray(document?.content)
+    && document.content.some((node) => freeFormRootPresentation(node)?.rootPlacement === "root-band");
+}
+
+/**
+ * Advisory only: a root-band component spans the viewport, so a header whose
+ * brand and buttons stop at the content edges usually reads as misaligned
+ * beside it. The wide header with the centered menu is the recommended pair,
+ * never a requirement, so this is a hint in the result and on stderr, not a
+ * failure (TR00697).
+ */
+function headerWidthHints(headerWidth, rootBandPages) {
+  if (rootBandPages.length === 0 || headerWidth === "wide") return [];
+  const pages = boundedList(rootBandPages, MAXIMUM_REPORTED);
+  return [{
+    code: "header.width_contained_with_root_band",
+    message: `${rootBandPages.length} page(s) use a full-bleed root-band component while site-header.headerWidth is `
+      + `'${headerWidth}'. Full-bleed designs usually read better with headerWidth 'wide' (brand and buttons at the `
+      + "viewport edges) paired with headerLayout 'centered-menu'.",
+    setting: "site-header.headerWidth",
+    suggested: { headerWidth: "wide", headerLayout: "centered-menu" },
+    pages: pages.items,
+    ...(pages.truncated ? { pagesTruncated: true } : {}),
+  }];
+}
+
 export async function validateFixture(invocation = {}) {
   const onProgress = typeof invocation.onProgress === "function" ? invocation.onProgress : () => {};
   const fixtureRoot = await resolveFixtureRoot(invocation.cwd ?? process.cwd(), invocation.fixturePath);
@@ -377,6 +405,7 @@ export async function validateFixture(invocation = {}) {
     fail("fixture.page_untracked", `Page source '${untracked}' is not bound by ${FIXTURE_MANIFEST_FILE_NAME}.`, untracked);
   }
   const validatedPages = [];
+  const rootBandPages = [];
   for (const file of pageFiles) {
     onProgress(`Validating '${file}'.`);
     const entry = manifestByFile.get(file);
@@ -404,7 +433,10 @@ export async function validateFixture(invocation = {}) {
     }
     validatePageImageReferences(page.document, file, imageIds, deliveryOrigins);
     validatedPages.push({ file, path: page.pagePath });
+    if (pageUsesRootBand(page.document)) rootBandPages.push(file);
   }
+  const hints = headerWidthHints(presentation.header.headerWidth, rootBandPages);
+  for (const hint of hints) onProgress(`Hint: ${hint.message}`);
 
   onProgress("Validating navigation shape and local PAGE targets.");
   const navigation = validateNavigationWorkspaceDocument(
@@ -459,6 +491,7 @@ export async function validateFixture(invocation = {}) {
       count: presentation.themes.warningCount,
       ...(presentation.themes.warningsTruncated ? { truncated: true } : {}),
     },
+    hints,
     proves: [
       "fixture structure and bounded files",
       "page content and named theme contexts",