[pull] main from facebook:main

.cspell.json

@@ -26,12 +26,20 @@
     "yarn.lock",
     "project-words.txt",
     "__snapshots__",
+    "admin/scripts",
     "website/src/data/users.tsx",
     "website/src/data/tweets.tsx",
+    "website/docusaurus.config.localized.json",
+    "website/_dogfooding/_pages tests/diagrams.mdx",
     "*.xyz",
     "*.docx",
+    "*.xsl",
+    "*.xslt",
+    "*.gitignore",
     "versioned_docs",
-    "*.min.*"
+    "*.min.*",
+    "jest/vendor"
   ],
-  "ignoreRegExpList": ["Email", "Urls", "#[\\w-]*"]
+  "ignoreRegExpList": ["Email", "Urls", "#[\\w-]*"],
+  "enableFiletypes": ["mdx"]
 }

.devcontainer/devcontainer.json

@@ -1,5 +1,5 @@
 {
-  "image": "mcr.microsoft.com/vscode/devcontainers/base:ubuntu-20.04",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04",
   "settings": {
     "[typescript]": {
       "editor.defaultFormatter": "esbenp.prettier-vscode",
@@ -26,7 +26,7 @@
   "waitFor": "postCreateCommand", // otherwise automated jest tests fail
   "features": {
     "node": {
-      "version": "14"
+      "version": "18"
     },
     "github-cli": "latest"
   }

.eslintignore

@@ -3,10 +3,12 @@ __mocks__
 dist
 node_modules
 .yarn
+.history
 build
 coverage
 jest.config.js
 jest.transform.js
+jest/vendor
 examples/
 
 packages/lqip-loader/lib/
@@ -19,3 +21,4 @@ packages/create-docusaurus/lib/*
 packages/create-docusaurus/templates/facebook
 
 website/_dogfooding/_swizzle_theme_tests
+website/_dogfooding/_asset-tests/badSyntax.js

.eslintrc.js

@@ -9,6 +9,20 @@ const OFF = 0;
 const WARNING = 1;
 const ERROR = 2;
 
+// Prevent importing lodash, usually for browser bundle size reasons
+const LodashImportPatterns = ['lodash', 'lodash.**', 'lodash/**'];
+
+// Prevent importing content plugins, usually for coupling reasons
+const ContentPluginsImportPatterns = [
+  '@docusaurus/plugin-content-blog',
+  '@docusaurus/plugin-content-blog/**',
+  // TODO fix theme-common => docs dependency issue
+  // '@docusaurus/plugin-content-docs',
+  // '@docusaurus/plugin-content-docs/**',
+  '@docusaurus/plugin-content-pages',
+  '@docusaurus/plugin-content-pages/**',
+];
+
 module.exports = {
   root: true,
   env: {
@@ -20,7 +34,7 @@ module.exports = {
   parser: '@typescript-eslint/parser',
   parserOptions: {
     // tsconfigRootDir: __dirname,
-    // project: ['./tsconfig.json', './website/tsconfig.json'],
+    // project: ['./tsconfig.base.json', './website/tsconfig.base.json'],
   },
   globals: {
     JSX: true,
@@ -54,6 +68,8 @@ module.exports = {
     '@docusaurus',
   ],
   rules: {
+    'react/jsx-uses-react': OFF, // JSX runtime: automatic
+    'react/react-in-jsx-scope': OFF, // JSX runtime: automatic
     'array-callback-return': WARNING,
     camelcase: WARNING,
     'class-methods-use-this': OFF, // It's a way of allowing private variables.
@@ -71,13 +87,14 @@ module.exports = {
         ignorePattern: '(eslint-disable|@)',
       },
     ],
+    'arrow-body-style': OFF,
     'no-await-in-loop': OFF,
     'no-case-declarations': WARNING,
     'no-console': OFF,
     'no-constant-binary-expression': ERROR,
     'no-continue': OFF,
     'no-control-regex': WARNING,
-    'no-else-return': [WARNING, {allowElseIf: true}],
+    'no-else-return': OFF,
     'no-empty': [WARNING, {allowEmptyCatch: true}],
     'no-lonely-if': WARNING,
     'no-nested-ternary': WARNING,
@@ -189,7 +206,10 @@ module.exports = {
       })),
     ],
     'no-template-curly-in-string': WARNING,
-    'no-unused-expressions': [WARNING, {allowTaggedTemplates: true}],
+    'no-unused-expressions': [
+      WARNING,
+      {allowTaggedTemplates: true, allowShortCircuit: true},
+    ],
     'no-useless-escape': WARNING,
     'no-void': [ERROR, {allowAsStatement: true}],
     'prefer-destructuring': WARNING,
@@ -211,10 +231,12 @@ module.exports = {
     ],
 
     'import/extensions': OFF,
-    // Ignore certain webpack aliases because they can't be resolved
+    // This rule doesn't yet support resolving .js imports when the actual file
+    // is .ts. Plus it's not all that useful when our code is fully TS-covered.
     'import/no-unresolved': [
-      ERROR,
+      OFF,
       {
+        // Ignore certain webpack aliases because they can't be resolved
         ignore: [
           '^@theme',
           '^@docusaurus',
@@ -235,8 +257,19 @@ module.exports = {
           'type',
         ],
         pathGroups: [
+          // always put css import to the last, ref:
+          // https://github.com/import-js/eslint-plugin-import/issues/1239
+          {
+            pattern: '*.+(css|sass|less|scss|pcss|styl)',
+            group: 'unknown',
+            patternOptions: {matchBase: true},
+            position: 'after',
+          },
           {pattern: '@jest/globals', group: 'builtin', position: 'before'},
           {pattern: 'react', group: 'builtin', position: 'before'},
+          {pattern: 'react-dom', group: 'builtin', position: 'before'},
+          {pattern: 'react-dom/**', group: 'builtin', position: 'before'},
+          {pattern: 'stream', group: 'builtin', position: 'before'},
           {pattern: 'fs-extra', group: 'builtin'},
           {pattern: 'lodash', group: 'external', position: 'before'},
           {pattern: 'clsx', group: 'external', position: 'before'},
@@ -251,6 +284,10 @@ module.exports = {
           {pattern: '@theme-original/**', group: 'internal'},
         ],
         pathGroupsExcludedImportTypes: [],
+        // example: let `import './nprogress.css';` after importing others
+        // in `packages/docusaurus-theme-classic/src/nprogress.ts`
+        // see more: https://github.com/import-js/eslint-plugin-import/blob/main/docs/rules/order.md#warnonunassignedimports-truefalse
+        warnOnUnassignedImports: true,
       },
     ],
     'import/prefer-default-export': OFF,
@@ -313,10 +350,7 @@ module.exports = {
       ERROR,
       {'ts-expect-error': 'allow-with-description'},
     ],
-    '@typescript-eslint/consistent-indexed-object-style': [
-      WARNING,
-      'index-signature',
-    ],
+    '@typescript-eslint/consistent-indexed-object-style': OFF,
     '@typescript-eslint/consistent-type-imports': [
       WARNING,
       {disallowTypeAnnotations: false},
@@ -346,8 +380,17 @@ module.exports = {
     // We don't provide any escape hatches for this rule. Rest siblings and
     // function placeholder params are always ignored, and any other unused
     // locals must be justified with a disable comment.
-    '@typescript-eslint/no-unused-vars': [ERROR, {ignoreRestSiblings: true}],
+    '@typescript-eslint/no-unused-vars': [
+      ERROR,
+      {
+        ignoreRestSiblings: true,
+        argsIgnorePattern: '^_',
+        varsIgnorePattern: '^_',
+      },
+    ],
     '@typescript-eslint/prefer-optional-chain': ERROR,
+    '@docusaurus/no-html-links': ERROR,
+    '@docusaurus/prefer-docusaurus-heading': ERROR,
     '@docusaurus/no-untranslated-text': [
       WARNING,
       {
@@ -360,6 +403,7 @@ module.exports = {
           '@',
           'WebContainers',
           'Twitter',
+          'X',
           'GitHub',
           'Dev.to',
           '1.x',
@@ -369,19 +413,14 @@ module.exports = {
   },
   overrides: [
     {
-      files: [
-        'packages/docusaurus-*/src/theme/**/*.{js,ts,tsx}',
-        'packages/docusaurus/src/client/**/*.{js,ts,tsx}',
-      ],
+      files: ['packages/docusaurus/src/client/**/*.{js,ts,tsx}'],
       rules: {
         'no-restricted-imports': [
           'error',
           {
             patterns: [
-              // Prevent importing lodash in client bundle for bundle size
-              'lodash',
-              'lodash.**',
-              'lodash/**',
+              ...LodashImportPatterns,
+              ...ContentPluginsImportPatterns,
               // Prevent importing server code in client bundle
               '**/../babel/**',
               '**/../server/**',
@@ -392,6 +431,44 @@ module.exports = {
         ],
       },
     },
+    {
+      files: [
+        'packages/docusaurus-theme-common/src/**/*.{js,ts,tsx}',
+        'packages/docusaurus-utils-common/src/**/*.{js,ts,tsx}',
+      ],
+      excludedFiles: '*.test.{js,ts,tsx}',
+      rules: {
+        'no-restricted-imports': [
+          'error',
+          {
+            patterns: [
+              ...LodashImportPatterns,
+              ...ContentPluginsImportPatterns,
+            ],
+          },
+        ],
+      },
+    },
+    {
+      files: ['packages/docusaurus-*/src/theme/**/*.{js,ts,tsx}'],
+      excludedFiles: '*.test.{js,ts,tsx}',
+      rules: {
+        'no-restricted-imports': [
+          'error',
+          {
+            patterns: LodashImportPatterns.concat(
+              // Prevents relative imports between React theme components
+              [
+                '../**',
+                './**',
+                // Allows relative styles module import with consistent filename
+                '!./styles.module.css',
+              ],
+            ),
+          },
+        ],
+      },
+    },
     {
       files: [
         'packages/docusaurus-*/src/theme/**/*.{js,ts,tsx}',
@@ -449,6 +526,7 @@ module.exports = {
         'admin/**',
         'jest/**',
         'website/**',
+        'packages/docusaurus-theme-common/removeThemeInternalReexport.mjs',
         'packages/docusaurus-theme-translations/update.mjs',
         'packages/docusaurus-theme-translations/src/utils.ts',
       ],
@@ -460,5 +538,14 @@ module.exports = {
       files: ['packages/eslint-plugin/**/*.{js,ts}'],
       extends: ['plugin:eslint-plugin/recommended'],
     },
+    {
+      files: [
+        'packages/docusaurus-plugin-debug/**',
+        'packages/docusaurus/src/**',
+      ],
+      rules: {
+        '@docusaurus/prefer-docusaurus-heading': OFF,
+      },
+    },
   ],
 };

.github/ISSUE_TEMPLATE/bug.yml

@@ -26,7 +26,7 @@ body:
     attributes:
       label: Have you read the Contributing Guidelines on issues?
       options:
-        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-issues).
+        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).
           required: true
 
   - type: checkboxes

.github/ISSUE_TEMPLATE/documentation.yml

@@ -27,7 +27,7 @@ body:
     attributes:
       label: Have you read the Contributing Guidelines on issues?
       options:
-        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-issues).
+        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).
           required: true
 
   - type: textarea

.github/ISSUE_TEMPLATE/feature.yml

@@ -15,7 +15,7 @@ body:
     attributes:
       label: Have you read the Contributing Guidelines on issues?
       options:
-        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-issues).
+        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).
           required: true
 
   - type: textarea

.github/ISSUE_TEMPLATE/proposal.yml

@@ -23,7 +23,7 @@ body:
     attributes:
       label: Have you read the Contributing Guidelines on issues?
       options:
-        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-issues).
+        - label: I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).
           required: true
 
   - type: textarea

.github/dependabot.yml

@@ -7,3 +7,12 @@ updates:
     open-pull-requests-limit: 99
     labels:
       - 'pr: dependencies'
+  - package-ecosystem: 'npm'
+    directory: '/'
+    schedule:
+      interval: 'daily'
+    # Disable version updates for npm dependencies
+    # https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates#overriding-the-default-behavior-with-a-configuration-file
+    open-pull-requests-limit: 0
+    labels:
+      - 'pr: dependencies'

.github/workflows/argos.yml

@@ -0,0 +1,47 @@
+name: Argos CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+    types:
+      # Those 3 are the default PR workflow activity types,
+      # see https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request
+      - opened
+      - synchronize
+      - reopened
+      # We want trigger workflow on labeled too!
+      - labeled
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+jobs:
+  take-screenshots:
+    # Argos is heavy to run
+    # We only want to trigger Argos on PRs with the 'Argos' label
+    # See https://stackoverflow.com/questions/62325286/run-github-actions-when-pull-requests-have-a-specific-label
+    if: ${{ (github.event_name != 'pull_request' && github.ref_name == 'main') || (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'Argos')) }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository code
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+
+      - name: Use Node.js
+        uses: actions/setup-node@39370e3970a6d050c480ffad4ff0ed4d3fdee5af # v4.1.0
+        with:
+          node-version: lts/*
+
+      - name: Install dependencies
+        run: yarn || yarn || yarn
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps chromium
+
+      - name: Build website fast
+        run: yarn argos:build
+
+      - name: Take Argos screenshots
+        run: yarn argos:screenshot