@taprootio/site-authoring 0.1.0 → 0.2.0

package/README.md

@@ -223,12 +223,18 @@ Actions output.
 
 ## Public release
 
-Private Taproot is the source authority. A private `site-authoring-v<version>`
-tag verifies this package — the release commit must belong to `main`, the tag
-must name the version `package.json` declares, and `@taprootio/espalier` must
-be pinned to the exact version the release manifest records — then
-allowlist-exports only `packages/site-authoring/` to public
-[`taprootio/trunk`](https://github.com/taprootio/trunk). Trunk's separate
+Private Taproot is the source authority. Merging a version bump to private
+`main` releases this package: the release workflow verifies that the commit
+belongs to `main`, that `site-authoring-v<version>` names the version
+`package.json` declares, and that `@taprootio/espalier` is pinned to the exact
+version the release manifest records, then allowlist-exports only
+`packages/site-authoring/` to public
+[`taprootio/trunk`](https://github.com/taprootio/trunk), whose commit and
+`site-authoring-v<version>` tag are the release record and name the private
+source commit. A pull request that changes this package's public files
+without raising the version fails CI, so the bump is never an afterthought;
+pushing a private `site-authoring-v<version>` tag by hand remains the manual
+path and runs the same verification. Trunk's separate
 `publish-site-authoring.yml` workflow tests and publishes those exact public
 tag bytes with npm trusted-publishing provenance, under its own concurrency
 group, GitHub Environment, tag prefix, and npm identity.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.1.0",
+  "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.4.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.0";
+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/content/components.js

@@ -227,6 +227,9 @@ const IMAGE_BANNER = Object.freeze({
   }),
   ratio: enumOf("4/1", "3/1", "2/1"),
   compactRatio: enumOf("", "2/1", "3/2", "1/1"),
+  // `ratio` keeps the wide/compact shape, capped at the viewport space below
+  // the site header; `viewport` fills exactly that space (TR00413).
+  heightMode: enumOf("ratio", "viewport"),
   contentPosition: enumOf("bottom-start", "bottom", "bottom-end", "center", "top-start", "top", "top-end"),
   scrim: enumOf("auto", "none", "flat", "top", "bottom", "left", "right", "radial"),
   scrimStrength: enumOf("soft", "medium", "strong"),
@@ -457,6 +460,7 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       focus: { x: 0.5, y: 0.5 },
       ratio: "3/1",
       compactRatio: "3/2",
+      heightMode: "ratio",
       contentPosition: "center",
       scrim: "auto",
       scrimStrength: "medium",
@@ -473,6 +477,7 @@ const COMPONENT_DEFINITIONS = Object.freeze({
       altText: "",
       overlayText: "Train together",
       focus: { x: 0.5, y: 0.35 },
+      heightMode: "ratio",
       contentPosition: "bottom-start",
       scrim: "bottom",
       scrimStrength: "medium",

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 }),
@@ -271,6 +281,7 @@ export function getThemeReference() {
       "Define brand anchors first, then assign canvas, ink, accent, action, and structure roles in both schemes.",
       "Add named contexts for whole zones, including inverted zones, and rebind lightness when the zone changes brightness.",
       "Tune typography, type/space ratios, radii, and viewport interpolation as one layout system.",
+      "Typography is per scheme on purpose: light and dark set their own moods, so a heading, body, or brand face that differs between them is a design choice, and theme push never warns about it.",
       "Retune danger/success/warning/info through intents without changing their meanings; design data palettes separately.",
       "Use semanticMappings only for meanings roles and contexts cannot express; scattered pins shadow the coherent model.",
       "Run theme push, inspect warnings, then verify text, actions, focus states, and both schemes in authoring previews.",
@@ -329,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",
@@ -576,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/reference-help.js

@@ -27,7 +27,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 13;
+export const REFERENCE_VERSION = 15;
 export const PAGE_TYPES = Object.freeze(["free-form"]);
 export const REFERENCE_TOPICS = Object.freeze([
   Object.freeze({ name: "pages", usage: `${CLI_BINARY_NAME} help pages`, summary: "List authorable page types." }),

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",