@taprootio/site-authoring 0.13.0 → 0.14.1

package/README.md

@@ -362,8 +362,10 @@ file that is not an MP4 with its index first as one (copying the tracks, never
 re-encoding), declares its codecs, and prints the server's one-line refusal as
 it came for anything it will not accept (a non-H.264 or non-AAC file, one over
 the licence's upload cap). A video is ready when its upload confirms; the CLI sets no poster (Node has no video decoder), so
-choose one on the Videos page, where an upload made there gets one automatically; the command
-reports its `videoId` for a `video` component (`help component video`), and
+choose one on the Videos page, where an upload made there gets one automatically, and set its
+title and caption there too: the poster, caption and shape are the video's own and show wherever
+it is placed. The command reports its `videoId`, title, caption and file name for a `video`
+component (`help component video`), and
 `pages push` refuses a page that places a video the site does not have. `nav push`, `theme push`, and `footer push` replace the whole
 navigation tree, the complete light/dark theme pair with its appearance
 settings, and the closed footer document. `pull` writes each scheme's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taprootio/site-authoring",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "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/api.js

@@ -841,6 +841,8 @@ export function normalizeVideo(value) {
   return {
     videoId: requireCanonicalUuid(video.videoId, "api.video_contract", "video.videoId"),
     title: text(video.title),
+    caption: text(video.caption),
+    fileName: text(video.fileName),
     bytes: safeCount(video.bytes),
     durationMilliseconds: safeCount(video.durationMs),
     width: safeCount(video.width),
@@ -1006,6 +1008,7 @@ export async function getPublishingReadiness(client, siteId, selection = {}) {
           ["stagedPageIds", selection.stagedPageIds],
           ["selectedSettingsTypes", selection.selectedSettingsTypes],
           ["includeNavigation", selection.includeNavigation],
+          ["useExactPageSelection", selection.useExactPageSelection],
         ])
       }`,
     )),
@@ -1025,6 +1028,10 @@ export async function getPublishingReadiness(client, siteId, selection = {}) {
     blockedPageCount: safeCount(response.blockedPageCount),
     hasCandidateChanges: response.hasCandidateChanges === true,
     hasSuccessfulStagingDeployment: response.hasSuccessfulStagingDeployment === true,
+    // Site-wide inputs frozen with every release that differ from production's.
+    redirectsChanged: response.redirectsChanged === true,
+    formsChanged: response.formsChanged === true,
+    videosChanged: response.videosChanged === true,
     blockers,
   };
 }

package/src/content/components.js

@@ -297,17 +297,12 @@ const MEDIA_PRESENTATION_HELP =
  * `VideoData`. The page names a library video by id and nothing about where it
  * is served: the generator resolves the id at publish time and refuses a video
  * that is not `ready` or not this site's own. Delivery URLs are not authorable
- * here, so a `delivery` key is refused like any other unknown field.
+ * here, so a `delivery` key is refused like any other unknown field. The poster,
+ * caption and ratio are the video's own (TR01184), so a block carrying one is
+ * refused the same way.
  */
 const VIDEO = Object.freeze({
   videoId: Object.freeze({ kind: "uuid", required: true }),
-  poster: image(),
-  caption: boundedStr(300),
-  aspectRatio: str({
-    pattern: VIDEO_ASPECT_RATIO_RE,
-    patternSource: VIDEO_ASPECT_RATIO_PATTERN,
-    patternDescription: "two whole numbers of at most three digits joined by a colon, such as 16:9",
-  }),
   maxHeight: cssLength({ allowNone: true }),
   borderWidth: cssLength(),
 });
@@ -639,17 +634,14 @@ const COMPONENT_DEFINITIONS = Object.freeze({
   "video": component(
     VIDEO,
     "Video",
-    "A video from the site's library that plays when the visitor presses play; nothing loads before then.",
+    "A video from the site's library that plays when the visitor presses play; the page reads only the start of the file before then.",
     {},
     [
-      "Add a caption that tells a visitor what the video is about; the caption is also the player's accessible name.",
+      "The poster, the caption and the shape are the video's own and show wherever it is placed: set the title, caption and poster on the site's Videos page. The caption tells a visitor what the video is about and is also the player's accessible name.",
       "A video with spoken content needs captions or a transcript in the page text; the player does not generate them.",
-      "Leave aspectRatio out to follow the video's own shape; set it only to crop the frame to a different one.",
     ],
     {
       videoId: "7c5e2b1a-9d3f-4a68-b0c4-1e2f3a4b5c6d",
-      caption: "A walk through the studio before your first class.",
-      aspectRatio: "16:9",
     },
     { notes: [MEDIA_PRESENTATION_HELP] },
   ),

package/src/reference-help.js

@@ -71,7 +71,7 @@ import {
 
 export { getAppearanceReference, getFooterReference, getThemeReference };
 
-export const REFERENCE_VERSION = 32;
+export const REFERENCE_VERSION = 33;
 
 // The date-limit examples `help forms` prints; tests run them through the form validator.
 export const FORM_DATE_WINDOW_FIELD = Object.freeze({
@@ -838,8 +838,8 @@ const WORKFLOW_REFERENCES = Object.freeze({
       "Prepare variants locally with any image tool before uploading: a transparent logo, its @2x copy, a scheme-specific dark logo when one asset does not read on both headers, and a square favicon. The CLI uploads what you give it; it has no recolor, crop, or SVG upload command.",
       "Assign both schemes after uploading: lightLogoId and darkLogoId in settings/taproot-styles.json and brand.faviconId in settings/brand.json take the returned image ids; theme push writes them. See help walkthrough for the full design pass.",
       "Each result item includes media: { imageId, src, urls, width, height, alt }.",
-      "MP4, MOV, and WebM files are uploaded as videos (up to 250 MB each; the site's licence sets the cap, and the container is read from the file's bytes, not its name). The CLI reads each file with mediabunny. A file that is H.264 and AAC but not already an MP4 with its index first is rewritten as one without re-encoding; anything else is sent as it is and judged by the server. When the server refuses a file, its one-line message is printed as media.video_refused. A video is ready to play as soon as the upload is confirmed. The CLI sets no poster, because Node has no video decoder: the Videos page picks one automatically for a video uploaded there, and lets the owner choose another frame, so set a CLI-uploaded video's poster there. The command reports videos.items: { file, videoId, contentType, byteLength, deduplicated, durationMilliseconds, component }, where component.markdown is the component:video fence and component.block the componentBlock node that place it. Needs the site's licence to include video.",
-      "Place an uploaded video on a page with a video component: a component:video fence in Markdown or a componentBlock of type video, with the returned videoId and optional poster, caption, and aspectRatio. See help component video. pages push refuses a video that is not in the site's library; validate checks it against fixture.videoIds.",
+      "MP4, MOV, and WebM files are uploaded as videos (up to 250 MB each; the site's licence sets the cap, and the container is read from the file's bytes, not its name). The CLI reads each file with mediabunny. A file that is H.264 and AAC but not already an MP4 with its index first is rewritten as one without re-encoding; anything else is sent as it is and judged by the server. When the server refuses a file, its one-line message is printed as media.video_refused. A video is ready to play as soon as the upload is confirmed. The CLI sets no poster, because Node has no video decoder: the Videos page picks one automatically for a video uploaded there, and lets the owner choose another frame, so set a CLI-uploaded video's poster there, with its title and caption. The command reports videos.items: { file, videoId, title, caption, fileName, contentType, byteLength, deduplicated, durationMilliseconds, component }, where component.markdown is the component:video fence and component.block the componentBlock node that place it. Needs the site's licence to include video.",
+      "Place an uploaded video on a page with a video component: a component:video fence in Markdown or a componentBlock of type video, with the returned videoId and optional maxHeight and borderWidth; the poster, caption and shape are the video's own. See help component video. pages push refuses a video that is not in the site's library; validate checks it against fixture.videoIds.",
       "The same src/urls delivery fields are saved in .taproot-site-media.json for page and component authoring.",
     ]),
     example: Object.freeze({

package/src/verbs/deploy.js

@@ -132,6 +132,19 @@ async function resolveStagingDeploymentId(client, siteId, invocation, manifest,
   return completed.id;
 }
 
+/**
+ * Names the site-wide changes a staging with nothing selected publishes, the way the
+ * Deployments page does (TR01184): an edited redirect map, form, or video caption or
+ * poster, each frozen with every release.
+ */
+export function siteWideChanges(readiness) {
+  return [
+    readiness.redirectsChanged ? "the redirect map" : "",
+    readiness.formsChanged ? "a form" : "",
+    readiness.videosChanged ? "a video's caption or poster" : "",
+  ].filter(Boolean);
+}
+
 function reportReadiness(readiness) {
   const blockers = boundedList(readiness.blockers, MAXIMUM_REPORTED_BLOCKERS);
   return {
@@ -141,6 +154,9 @@ function reportReadiness(readiness) {
     blockedPageCount: readiness.blockedPageCount,
     hasCandidateChanges: readiness.hasCandidateChanges,
     hasSuccessfulStagingDeployment: readiness.hasSuccessfulStagingDeployment,
+    redirectsChanged: readiness.redirectsChanged,
+    formsChanged: readiness.formsChanged,
+    videosChanged: readiness.videosChanged,
     blockers: blockers.items,
     ...(blockers.truncated ? { blockersTruncated: true } : {}),
   };
@@ -321,7 +337,8 @@ export async function deploy(invocation) {
     const nothingSelected = stagedPageIds.length === 0 && selectedSettingsTypes.length === 0 && !includeNavigation;
     // A managed Docs site stages settings only, so an empty selection is final.
     // Any other site may still have a publishable change no selection names: an
-    // edited redirect map. Readiness below says whether it does.
+    // edited redirect map, form, or video caption or poster. Readiness below says
+    // whether it does.
     const emptySelectionError = () =>
       new SiteAuthoringError(
         "deploy.empty_selection",
@@ -329,7 +346,8 @@ export async function deploy(invocation) {
           ? "A staging deployment on a managed Docs site needs at least one settings change; it stages settings "
             + "only. Change a theme, brand, header, or footer setting first."
           : "A staging deployment needs at least one approved page, settings group, or navigation change, or an "
-            + "edited redirect map. Run 'taproot-site approve' or change staged settings/navigation first.",
+            + "edited redirect map, form, or video caption or poster. Run 'taproot-site approve' or change "
+            + "staged settings/navigation first.",
         { field: "Candidate" },
       );
     if (nothingSelected && presentationOnly) {
@@ -349,6 +367,7 @@ export async function deploy(invocation) {
     const readiness = await getPublishingReadiness(client, siteId, {
       ...candidate,
       stagedPageIds: stagedPageIds.length > MAXIMUM_READINESS_PAGE_IDS ? undefined : stagedPageIds,
+      useExactPageSelection: stagedPageIds.length === 0,
     });
     if (readiness.blockers.length > 0) {
       throw new SiteAuthoringError(
@@ -362,6 +381,15 @@ export async function deploy(invocation) {
     if (nothingSelected && !readiness.hasCandidateChanges) {
       throw emptySelectionError();
     }
+    const siteWide = siteWideChanges(readiness);
+    if (nothingSelected && readiness.hasCandidateChanges) {
+      // An API that names none of them still knows the site changed; say so, as the web dialog does.
+      onProgress(
+        siteWide.length > 0
+          ? `Staging publishes what changed since the last release: ${siteWide.join(", ")}.`
+          : "Your site has changed since the last release. Staging publishes the change.",
+      );
+    }
     if (!readiness.hasCandidateChanges) {
       onProgress("Taproot reports this candidate contains no changes; deploying it anyway would be a no-op.");
     }

package/src/verbs/media-upload.js

@@ -497,6 +497,9 @@ export async function mediaUpload(invocation) {
           uploadedVideos.push({
             file,
             videoId: video.videoId,
+            title: video.title,
+            caption: video.caption,
+            fileName: video.fileName,
             contentType,
             byteLength,
             deduplicated,
@@ -619,6 +622,10 @@ export async function mediaUpload(invocation) {
       uploadedVideos.map((entry) => ({
         file: entry.file,
         videoId: entry.videoId,
+        // Set on the Videos page; the placement shows them wherever the video goes.
+        title: entry.title,
+        caption: entry.caption,
+        fileName: entry.fileName,
         contentType: entry.contentType,
         byteLength: entry.byteLength,
         deduplicated: entry.deduplicated,

package/src/verbs/status.js

@@ -198,6 +198,9 @@ export async function status(invocation) {
         blockedPageCount: readiness.blockedPageCount,
         hasCandidateChanges: readiness.hasCandidateChanges,
         hasSuccessfulStagingDeployment: readiness.hasSuccessfulStagingDeployment,
+        redirectsChanged: readiness.redirectsChanged,
+        formsChanged: readiness.formsChanged,
+        videosChanged: readiness.videosChanged,
         blockers: blockers.items,
         ...(blockers.truncated ? { blockersTruncated: true } : {}),
       },