docs: clarify root-only ViewTransition snapshots (#8732)

.github/workflows/site_lint.yml

@@ -1,4 +1,4 @@
-name: Site Lint / Heading ID check
+name: Site Lint / Heading checks
 
 on:
   push:
@@ -17,6 +17,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - name: Use Node.js 20.x
         uses: actions/setup-node@v4
         with:
@@ -35,3 +37,8 @@ jobs:
 
       - name: Lint codebase
         run: yarn ci-check
+
+      - name: Check heading order
+        env:
+          HEADING_ORDER_BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+        run: yarn lint-heading-order "$HEADING_ORDER_BASE_SHA"

package.json

@@ -15,6 +15,7 @@
     "prettier": "yarn format:source",
     "prettier:diff": "yarn nit:source",
     "lint-heading-ids": "node scripts/headingIdLinter.js",
+    "lint-heading-order": "node scripts/headingOrderLinter.js",
     "fix-headings": "node scripts/headingIdLinter.js --fix",
     "ci-check": "npm-run-all prettier:diff --parallel lint test:eslint-local-rules tsc lint-heading-ids rss deadlinks",
     "tsc": "tsc --noEmit",

scripts/headingOrderLinter.js

@@ -0,0 +1,157 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {execFileSync} = require('child_process');
+
+const contentDirectory = 'src/content';
+const baseSha = process.argv[2];
+
+if (!baseSha) {
+  console.error(
+    'Pass the base commit SHA to compare heading-order violations.'
+  );
+  process.exit(1);
+}
+
+function walk(directory) {
+  return fs.readdirSync(directory, {withFileTypes: true}).flatMap((entry) => {
+    const entryPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      return walk(entryPath);
+    }
+    return entry.name.endsWith('.md') || entry.name.endsWith('.mdx')
+      ? [entryPath]
+      : [];
+  });
+}
+
+function findHeadingOrderViolations(content, file) {
+  const violations = [];
+  const lines = content.split(/\r?\n/);
+  let previousLevel = 1;
+  let codeFence = null;
+
+  lines.forEach((line, index) => {
+    const fence = /^\s{0,3}(`{3,}|~{3,})/.exec(line);
+    if (fence) {
+      const marker = fence[1][0];
+      if (!codeFence) {
+        codeFence = {marker, length: fence[1].length};
+      } else if (
+        marker === codeFence.marker &&
+        fence[1].length >= codeFence.length
+      ) {
+        codeFence = null;
+      }
+      return;
+    }
+    if (codeFence) {
+      return;
+    }
+
+    const heading = /^(#{1,6})[ \t]+(.+?)\s*$/.exec(line);
+    if (!heading) {
+      return;
+    }
+
+    const level = heading[1].length;
+    if (level > previousLevel + 1) {
+      const text = heading[2].replace(/\s+\{\/\*.*?\*\/}\s*$/, '').trim();
+      violations.push({
+        file,
+        line: index + 1,
+        previousLevel,
+        level,
+        text,
+      });
+    }
+    previousLevel = level;
+  });
+
+  return violations;
+}
+
+function violationKey(violation) {
+  return JSON.stringify([
+    violation.file,
+    violation.previousLevel,
+    violation.level,
+    violation.text,
+  ]);
+}
+
+function readBaseContent(revision, file) {
+  try {
+    return execFileSync('git', ['show', `${revision}:${file}`], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+  } catch (error) {
+    if (error.status === 128) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+try {
+  execFileSync('git', ['rev-parse', '--verify', `${baseSha}^{commit}`], {
+    stdio: 'ignore',
+  });
+
+  const currentViolations = walk(contentDirectory).flatMap((filePath) => {
+    const file = path
+      .relative(process.cwd(), filePath)
+      .split(path.sep)
+      .join('/');
+    return findHeadingOrderViolations(fs.readFileSync(filePath, 'utf8'), file);
+  });
+  const filesWithViolations = [
+    ...new Set(currentViolations.map((violation) => violation.file)),
+  ];
+  const baselineCounts = new Map();
+
+  filesWithViolations.forEach((file) => {
+    const content = readBaseContent(baseSha, file);
+    const violations = content ? findHeadingOrderViolations(content, file) : [];
+    violations.forEach((violation) => {
+      const key = violationKey(violation);
+      baselineCounts.set(key, (baselineCounts.get(key) || 0) + 1);
+    });
+  });
+
+  const newViolations = [];
+  currentViolations.forEach((violation) => {
+    const key = violationKey(violation);
+    const count = baselineCounts.get(key) || 0;
+    if (count > 0) {
+      baselineCounts.set(key, count - 1);
+    } else {
+      newViolations.push(violation);
+    }
+  });
+
+  if (newViolations.length > 0) {
+    console.error('New heading-order skips found:');
+    newViolations.forEach(({file, line, previousLevel, level, text}) => {
+      console.error(
+        `  ${file}:${line}: h${previousLevel} to h${level}: ${text}`
+      );
+    });
+    process.exitCode = 1;
+  } else {
+    console.log('No new heading-order skips found.');
+  }
+} catch (error) {
+  console.error(
+    'Unable to check heading order against the base commit:',
+    error.message
+  );
+  process.exitCode = 1;
+}

src/content/reference/react/ViewTransition.md

@@ -2775,6 +2775,14 @@ React waits for any pending Navigation to finish to ensure that scroll restorati
 
 If a `startTransition` is started from the legacy popstate event, such as during a "back"-navigation then it must finish synchronously to ensure scroll and form restoration works correctly. This is in conflict with running a View Transition animation. Therefore, React will skip animations from popstate and animations won't run for the back button. You can fix this by upgrading your router to use the Navigation API.
 
+#### Animating only the root snapshot {/*animating-only-the-root-snapshot*/}
+
+React starts a browser View Transition when a `<ViewTransition>` activates, but this does not guarantee that the browser's root snapshot will be available. React may cancel the root snapshot when it determines that the transition does not affect the root layout. For example, a small keyed `<ViewTransition enter="auto" exit="auto">` can start a transition, but does not by itself guarantee that the root snapshot is kept. A boundary that changes size and affects its parent layout may cause React to keep the root snapshot; changes in a portal may also affect it.
+
+Because activating a boundary and keeping the root snapshot are separate, CSS for `::view-transition-old(root)` and `::view-transition-new(root)` may not run for every navigation. React does not currently document a supported pattern that guarantees a root-only snapshot for route transitions. Do not rely on a small keyed boundary as that guarantee; test the behavior with your router and target browsers.
+
+Wrapping a whole page in `<ViewTransition>` does not create a viewport-only snapshot. The browser captures the element's painted overflow, including content outside the viewport. A tall or scrolling page can therefore produce a large snapshot and use substantial memory, especially on mobile devices. Avoid wrapping a page-sized element when you only intend to animate the viewport.
+
 ---
 
 ## Troubleshooting {/*troubleshooting*/}