[docs-infra] Fail CI on Vale error (#40944)

.circleci/config.yml

@@ -207,6 +207,43 @@ jobs:
       - run:
           name: Lint Markdown
           command: pnpm markdownlint
+      - run:
+          # See https://circleci.com/developer/orbs/orb/circleci/vale as reference
+          name: Install Vale
+          command: |
+            #!/bin/bash
+            VALE_STR_CLI_VERSION=3.3.0
+
+            mkdir /tmp/vale-extract
+            cd /tmp/vale-extract
+            GZIPPED_OUTPUT="vale.tar.gz"
+            BINARY_URL=https://github.com/errata-ai/vale/releases/download/v${VALE_STR_CLI_VERSION}/vale_${VALE_STR_CLI_VERSION}_Linux_64-bit.tar.gz
+            curl -sSL "$BINARY_URL" -o "${GZIPPED_OUTPUT}"
+
+            if [ ! -s "${GZIPPED_OUTPUT}" ]; then
+              echo "Downloaded file is empty"
+              rm "${GZIPPED_OUTPUT}"
+              exit 1
+            fi
+
+            tar -xzf "${GZIPPED_OUTPUT}"
+            $SUDO mv vale /usr/local/bin
+            rm "${GZIPPED_OUTPUT}"
+
+            # validate installation
+            if [[ -z "$(command -v vale)" ]]; then
+              echo "vale installation failed"
+              exit 1
+            else
+              echo "vale installation successful"
+              vale --version
+              exit 0
+            fi
+      - run:
+          name: Lint writing style
+          command: |
+            vale sync
+            pnpm run valelint
   test_static:
     <<: *default-job
     steps:

.github/workflows/vale-action.yml

@@ -14,11 +14,8 @@ jobs:
     steps:
       - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
       - uses: errata-ai/vale-action@38bf078c328061f59879b347ca344a718a736018 # v2.1.0
-        continue-on-error: true
+        continue-on-error: true # GitHub Action flag needed until https://github.com/errata-ai/vale-action/issues/89 is fixed
         with:
-          reporter: github-pr-review
-          files: docs/data
-        env:
-          # Required, set by GitHub actions automatically:
-          # https://docs.github.com/en/actions/security-guides/automatic-token-authentication#about-the-github_token-secret
-          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+          fail_on_error: true
+          reporter: github-pr-check
+          token: ${{secrets.GITHUB_TOKEN}}

.vale.ini

@@ -19,5 +19,5 @@ Google.We = YES # Avoid first-person plural
 Google.Will = YES # Avoid future tense
 Google.OxfordComma = YES # Prefer Oxford comma
 
-[CHANGELOG*.md]
+[*CHANGELOG*.md]
 MUI.CorrectReferenceAllCases = NO

docs/mui-vale/styles/MUI/CorrectReferenceAllCases.yml

@@ -7,7 +7,7 @@ ignorecase: true
 # for more information: https://vale.sh/docs/topics/styles/#substitution
 swap:
   ' api': API
-  typescript: TypeScript
+  'typescript ': TypeScript
   ' ts': TypeScript
   ' js': JavaScript
   javascript: JavaScript

docs/pages/blog/2019-developer-survey-results.md

@@ -281,7 +281,7 @@ Multiple options were allowed.
 
 <img src="/static/blog/2019-developer-survey-results/16.png" style="display: block; margin: 0 auto;" alt="Pie chart: 54,3% for my company, 24.9% for a client, 15.2% as a side project, 5.6% more than one of these." />
 
-### 17. Which JS framework are you using, if any?
+### 17. Which JavaScript framework are you using, if any?
 
 Multiple options were allowed.
 

docs/pages/blog/2019.md

@@ -64,7 +64,7 @@ Some of the key factors:
 - We have fixed a significant number of [accessibility issues](https://github.com/mui/material-ui/issues?q=is%3Aissue+label%3Aaccessibility+is%3Aclosed).
 - We have introduced global class names.
 - We have migrated the whole codebase to hooks.
-- We migrated all the demos to TypeScript (while also offering transpiled JS demos).
+- We migrated all the demos to TypeScript (while also offering transpiled JavaScript demos).
 - We introduced [native tree-shaking](/material-ui/guides/minimizing-bundle-size/) support.
 - We introduced [built-in localization](/material-ui/guides/localization/).
 - We removed a good number of external dependencies and increased the `features/bundle size` density.

docs/pages/blog/2020-developer-survey-results.md

@@ -277,7 +277,7 @@ section.
 <img src="/static/blog/2020-survey/17.png" style="width: 796px; margin-top: 16px; margin-bottom: 8px;" alt="Pie chart: 55.17% For my company
 22.86% For a client, 16.94% Side project, 5.03% More than one of these." />
 
-### 18. Which JS framework are you using, if any?
+### 18. Which JavaScript framework are you using, if any?
 
 <img src="/static/blog/2020-survey/18.png" style="width: 796px; margin-top: 16px; margin-bottom: 8px;" alt="Pie chart: 57.34% Create React App, 16.40% Custom Webpack, 12.35% Next.js, 5.40% Gatsby, 8.51% Other." />
 

docs/pages/blog/making-customizable-components.md

@@ -59,10 +59,10 @@ you can play around with it in [CodeSandbox](https://codesandbox.io/p/sandbox/fa
 }
 ```
 
-### Let JS generate the CSS
+### Let JavaScript generate the CSS
 
 Maybe you don't want to spend your time switching between CSS and JavaScript files, or writing long, cluttered stylesheets.
-To avoid these problems you can integrate styles directly into your JS code. 🎉
+To avoid these problems you can integrate styles directly into your JavaScript code. 🎉
 
 Because the level of customization varies across projects, Material UI's components can be customized in several different ways.
 For more information on this topic, check out the [Material UI customization documentation](https://mui.com/material-ui/customization/how-to-customize/).

docs/pages/blog/toolpad-use-cases.md

@@ -61,7 +61,7 @@ Your browser does not support the video tag.
 </video>
 
 We opted for Toolpad since Metabase doesn't support importing data from REST APIs.
-This is possible in Google Sheets but it requires writing a lot of JS code, and since we wanted to embed it in a [Notion page](https://mui-org.notion.site/KPIs-1ce9658b85ce4628a2a2ed2ae74ff69c?pvs=4#3974cb6ed12b4c5a9013bac63113e3bc), Toolpad was the ideal choice.
+This is possible in Google Sheets but it requires writing a lot of JavaScript code, and since we wanted to embed it in a [Notion page](https://mui-org.notion.site/KPIs-1ce9658b85ce4628a2a2ed2ae74ff69c?pvs=4#3974cb6ed12b4c5a9013bac63113e3bc), Toolpad was the ideal choice.
 Toolpad handles state management and routing, and simplifies query building and data binding, removing the need to write glue code.
 
 You can explore both of the aforementioned apps in dev mode on your device by running the underlying [Node application](https://github.com/mui/mui-public/tree/HEAD/tools-public).

docs/src/pages/premium-themes/onepirate/modules/views/privacy.md

@@ -13,7 +13,7 @@ Please read this policy carefully to understand how we handle and treat your per
 
 We may collect and process the following personal information from you:
 
-- **Information you provide to us:** We collect personal information when you voluntarily provide us with such information in the course of using our website or Services. For example, when you register to use our Services, we will collect your name, email address and organization information. We also collect personal information from you when you subscribe to our newsletter, or respond to a survey. If you make an enquiry through our website, or contact us in any other way, we will keep a copy of your communications with us.
+- **Information you provide to us:** We collect personal information when you voluntarily provide us with such information in the course of using our website or Services. For example, when you register to use our Services, we will collect your name, email address and organization information. We also collect personal information from you when you subscribe to our newsletter, or respond to a survey. If you make an inquiry through our website, or contact us in any other way, we will keep a copy of your communications with us.
 - **Information we collect when you do business with us:** We may process your personal information when you do business with us – for example, as a customer or prospective customer, or as a vendor, supplier, consultant or other third party. For example, we may hold your business contact information and financial account information (if any) and other communications you have with us for the purposes of maintaining our business relations with you.
 - **Information we automatically collect:** We may also collect certain technical information by automatic means when you visit our website, such as IP address, browser type and operating system, referring URLs, your use of our website, and other clickstream data. We collect this information automatically through the use of various technologies, such as cookies.
 - **Personal information where we act as a data processor:** We also process personal information on behalf of our customers in the context of supporting our products and services. Where a customer subscribes to our Services for their website, game or app, they will be the ones who control what event data is collected and stored on our systems. For example, they may ask us to log basic user data (for example email address or username), device identifiers, IP addresses, event type, and related source code. In such cases, we are data processors acting in accordance with the instructions of our customers. You will need to refer to the privacy policies of our customers to find out more about how such information is handled by them.
@@ -84,7 +84,7 @@ You can also unsubscribe from our marketing communications at any time by follow
 
 ## Data Retention
 
-We may retain your personal information as long as you continue to use the Services, have an account with us or for as long as is necessary to fulfil the purposes outlined in the policy. You can ask to close your account by contacting us at the details below and we will delete your personal information on request.
+We may retain your personal information as long as you continue to use the Services, have an account with us or for as long as is necessary to fulfill the purposes outlined in the policy. You can ask to close your account by contacting us at the details below and we will delete your personal information on request.
 
 We may however retain personal information for an additional period as is permitted or required under applicable laws, for legal, tax or regulatory reasons, or for legitimate and lawful business purposes.
 

package.json

@@ -46,6 +46,7 @@
     "eslint:ci": "eslint . --report-unused-disable-directives --ext .js,.ts,.tsx --max-warnings 0",
     "stylelint": "stylelint --reportInvalidScopeDisables --reportNeedlessDisables \"docs/**/*.{js,ts,tsx}\"",
     "markdownlint": "markdownlint-cli2 \"**/*.md\"",
+    "valelint": "git ls-files | grep -h \".md$\" | xargs vale --filter='.Level==\"error\"'",
     "prettier": "pretty-quick --ignore-path .eslintignore",
     "prettier:all": "prettier --write . --ignore-path .eslintignore",
     "size:snapshot": "node --max-old-space-size=4096 ./scripts/sizeSnapshot/create",

packages-internal/scripts/typescript-to-proptypes/CHANGELOG.old.md

@@ -123,7 +123,7 @@ All notable changes to this project will be documented in this file. See [standa
 - **parser:** handle optional any ([30f56ec](https://github.com/merceyz/typescript-to-proptypes/commit/30f56ec))
 - **parser:** handle optional React.ElementType ([c7a87fd](https://github.com/merceyz/typescript-to-proptypes/commit/c7a87fd))
 - **parser:** treat ComponentType as elementType ([53f1e21](https://github.com/merceyz/typescript-to-proptypes/commit/53f1e21))
-- export typescript as ts ([ba90e22](https://github.com/merceyz/typescript-to-proptypes/commit/ba90e22))
+- export TypeScript as ts ([ba90e22](https://github.com/merceyz/typescript-to-proptypes/commit/ba90e22))
 
 ### Features
 

packages/mui-codemod/CONTRIBUTING.md

@@ -4,7 +4,7 @@
 
 The codemod is a tool that helps developers migrate their codebase when we introduce changes in a new version. The changes could be deprecations, enhancements, or breaking changes.
 
-The codemods for JS files are based on [jscodeshift](https://github.com/facebook/jscodeshift) which is a wrapper of [recast](https://github.com/benjamn/recast).
+The codemods for JavaScript files are based on [jscodeshift](https://github.com/facebook/jscodeshift) which is a wrapper of [recast](https://github.com/benjamn/recast).
 
 The codemods for CSS files are based on [postcss](https://github.com/postcss/postcss).
 
@@ -22,7 +22,7 @@ The codemods for CSS files are based on [postcss](https://github.com/postcss/pos
      - `actual.css` - the input for the postcss plugin (optional)
      - `expected.css` - the expected output of the postcss plugin (optional)
 3. Use [astexplorer](https://astexplorer.net/) to check the AST types and properties
-   - For JS codemods set </> to @babel/parser because we use [`tsx`](https://github.com/benjamn/recast/blob/master/parsers/babel.ts) as a default parser.
+   - For JavaScript codemods set </> to @babel/parser because we use [`tsx`](https://github.com/benjamn/recast/blob/master/parsers/babel.ts) as a default parser.
    - For CSS codemods set </> to postcss
 4. [Test the codemod locally](#local)
 5. Add the codemod to README.md

packages/mui-codemod/README.md

@@ -1639,7 +1639,7 @@ The following scenarios are not currently handled by this codemod and will be ma
 - In order for arrow functions at the rule level to be converted, the parameter must use object
   destructuring (for example `root: ({color, padding}) => (...)`). If the parameter is not destructured
   (for example `root: (props) => (...)`), it will not be converted.
-- If an arrow function at the rule level contains a code block (i.e. contains an explicit `return`
+- If an arrow function at the rule level contains a code block (that is contains an explicit `return`
   statement) rather than just an object expression, it will not be converted.
 
 You can find more details about migrating from JSS to tss-react in [the migration guide](https://mui.com/material-ui/migration/migrating-from-jss/#2-use-tss-react).

packages/pigment-css-react/README.md

@@ -34,7 +34,7 @@ Thanks to recent advancements in CSS (like CSS variables and `color-mix()`), "tr
 Pigment CSS addresses the needs of the modern React developer by providing a zero-runtime CSS-in-JS styling solution as a successor to tools like Emotion and styled-components.
 
 Compared to its predecessors, Pigment CSS offers improved DX and runtime performance (though at the cost of increased build time) while also being compatible with React Server Components.
-Pigment CSS is built on top of [WyW-in-JS](https://wyw-in-js.dev/), enabling us to provide the smoothest possible experience for Material UI users when migrating from Emotion in v5 to Pigment CSS in v6.
+Pigment CSS is built on top of [WyW-in-JS](https://wyw-in-js.dev/), enabling to provide the smoothest possible experience for Material UI users when migrating from Emotion in v5 to Pigment CSS in v6.
 
 ### Start with Next.js
 
@@ -157,7 +157,7 @@ function App() {
 }
 ```
 
-The call to the `css` function will be replaced with a unique string that represents the CSS class name for the generated styles.
+The call to the `css` function is replaced with a unique string that represents the CSS class name for the generated styles.
 
 Use a callback function to get access to the [theme](#theming) values:
 
@@ -264,7 +264,7 @@ const Button = styled('button')({
 });
 ```
 
-Note that the `props` function will not work if it is inside another closure, for example, inside an `array.map`:
+Note that the `props` function doesn't work if it is inside another closure, for example, inside an `array.map`:
 
 ```jsx
 const Button = styled('button')({
@@ -307,7 +307,7 @@ const Heading = styled('h1')({
 });
 ```
 
-Pigment CSS will replace the callback with a CSS variable and inject the value through inline style. This makes it possible to create a static CSS file while still allowing dynamic styles.
+Pigment CSS replaces the callback with a CSS variable and inject the value through inline style. This makes it possible to create a static CSS file while still allowing dynamic styles.
 
 ```css
 .Heading_class_akjsdfb {
@@ -384,7 +384,7 @@ function Example1() {
 }
 ```
 
-The call to the `keyframes` function will be replaced with a unique string that represents the CSS animation name. It can be used with `css` or `styled` too.
+The call to the `keyframes` function is replaced with a unique string that represents the CSS animation name. It can be used with `css` or `styled` too.
 
 ```js
 import { css, styled, keyframes } from '@pigment-css/react';
@@ -415,7 +415,7 @@ Theming is an **optional** feature that lets you reuse the same values, such as
 
 > **💡 Good to know**:
 >
-> The **theme** object is used at build time and does not exist in the final JS bundle. This means that components created using Pigment's `styled` can be used with React Server Components by default while still getting the benefits of theming.
+> The **theme** object is used at build time and does not exist in the final JavaScript bundle. This means that components created using Pigment CSS's `styled` can be used with React Server Components by default while still getting the benefits of theming.
 
 For example, in Next.js, you can define a theme in the `next.config.js` file like this:
 
@@ -484,7 +484,7 @@ module.exports = withPigment(
 );
 ```
 
-The `extendTheme` utility will go through the theme and create a `vars` object which represents the tokens that refer to CSS variables.
+The `extendTheme` utility goes through the theme and create a `vars` object which represents the tokens that refer to CSS variables.
 
 ```jsx
 const theme = extendTheme({
@@ -508,7 +508,7 @@ extendTheme({
 });
 ```
 
-The generated CSS variables will have the `pigment` prefix:
+The generated CSS variables has the `pigment` prefix:
 
 ```css
 :root {
@@ -579,7 +579,7 @@ function App() {
 #### Styling based on color scheme
 
 The `extendTheme` utility attaches a function called `applyStyles` to the theme object. It receives a color scheme as the first argument followed by a style object.
-It will return a proper CSS selector based on the theme configuration.
+It returns a proper CSS selector based on the theme configuration.
 
 ```jsx
 const Heading = styled('h1')(({ theme }) => ({
@@ -620,7 +620,7 @@ declare module '@pigment-css/react/theme' {
 
 Emotion and styled-components are runtime CSS-in-JS libraries. What you write in your styles is what you get in the final bundle, which means the styles can be as dynamic as you want with bundle size and performance overhead trade-offs.
 
-On the other hand, Pigment CSS extracts CSS at build time and replaces the JS code with hashed class names and some CSS variables. This means that it has to know all of the styles to be extracted ahead of time, so there are rules and limitations that you need to be aware of when using JavaScript callbacks or variables in Pigment CSS's APIs.
+On the other hand, Pigment CSS extracts CSS at build time and replaces the JavaScript code with hashed class names and some CSS variables. This means that it has to know all of the styles to be extracted ahead of time, so there are rules and limitations that you need to be aware of when using JavaScript callbacks or variables in Pigment CSS's APIs.
 
 Here are some common patterns and how to achieve them with Pigment CSS:
 
@@ -669,7 +669,7 @@ const Flex = styled('div')((props) => ({
 
 2. **Programatically generated styles**
 
-For Emotion and styled-components, the styles will be different on each render and instance because the styles are generated at runtime:
+For Emotion and styled-components, the styles is different on each render and instance because the styles are generated at runtime:
 
 ```js
 function randomBetween(min: number, max: number) {
@@ -693,7 +693,7 @@ function App() {
 }
 ```
 
-However, in Pigment CSS with the same code as above, all instances will have the same styles and won't change between renders because the styles are extracted at build time.
+However, in Pigment CSS with the same code as above, all instances have the same styles and won't change between renders because the styles are extracted at build time.
 
 To achieve the same result, you need to move the dynamic logic to props and pass the value to CSS variables instead: