[docs] Fix some Vale errors

mui · Mar 16, 2024 · 5cf8628 · 5cf8628
1 parent 4ca8a0e
commit 5cf8628
Show file tree

Hide file tree

Showing 216 changed files with 666 additions and 574 deletions.
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -62,7 +62,7 @@ commands:
       browsers:
         type: boolean
         default: false
-        description: 'Set to true if you intend to any browser (e.g. with playwright).'
+        description: 'Set to true if you intend to any browser (for example with playwright).'
 
     steps:
       - run:

diff --git a/.vale.ini b/.vale.ini
@@ -1,28 +1,23 @@
-# Config vale. More information at https://docs.errata.ai/vale/config
+# Vale config. More information at https://vale.sh/docs/topics/config/
 StylesPath = .github/styles
-MinAlertLevel = suggestion
+MinAlertLevel = warning
 
-# The docs/writing-rules.zip is generated by `pnpm docs:zipRules`
-Packages = Google, docs/writing-rules.zip
+# The docs/mui-vale.zip is generated by `pnpm docs:zipRules`
+Packages = Google,docs/mui-vale.zip
 
 [*.md]
-# Ignore code injection which start with {{...
+# Ignore code injections that start with {{...
 BlockIgnores = {{.*
 
-BasedOnStyles = writing-rules
+BasedOnStyles = MUI
 
-# Google:
-Google.FirstPerson = YES # Avoid first-person pronouns such as I, me, ...'.
-Google.GenderBias = YES # Avoid gendered profession
-Google.OxfordComma = YES
-Google.Quotes = YES # Commas and periods go inside quotation marks.
-Google.Spelling = YES # In general, use American spelling (word ending with 'nised' or 'logue')
-Google.We = YES # Try to avoid using first-person plural
-Google.Latin = YES # Try to avoid latin expressions e.g. and i.e.
+# Google errors:
+Google.GenderBias = YES # No Gender bias
+# Google warings:
+Google.FirstPerson = YES # Avoid first-person
+Google.We = YES # Avoid first-person plural
+Google.Will = YES # Avoid future tense
+Google.OxfordComma = YES # Prefer Oxford comma
 
-# Those rules are not repected a lot
-# Google.Passive = YES # In general, use active voice instead of passive voice.
-Google.Will = YES # Avoid using will
-
-# False positives with "1st" nearly no use in our doc
-# Google.Units = YES # Put a nonbreaking space between the number and the unit
+[CHANGELOG*.md]
+MUI.CorrectReferenceAllCases = NO
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CHANGELOG.old.md b/CHANGELOG.old.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -253,7 +253,7 @@ Click on **Details** to find out more about them.
 ### Updating the component API documentation
 
 The component API in the component `propTypes` and under `docs/pages/api-docs` is auto-generated from the [JSDoc](https://jsdoc.app/about-getting-started.html) in the TypeScript declarations.
-Be sure to update the documentation in the corresponding `.d.ts` files (e.g. `packages/mui-material/src/Button/Button.d.ts` for `<Button>`) and then run:
+Be sure to update the documentation in the corresponding `.d.ts` files (for example `packages/mui-material/src/Button/Button.d.ts` for `<Button>`) and then run:
 
 ```bash
 $ pnpm proptypes
@@ -300,11 +300,11 @@ docs/src/pages/components/buttons/
 #### 2. Write the demo code
 
 We uses TypeScript to document our components.
-We prefer demos written in TS (using the `.tsx` file format).
+We prefer demos written in TypeScript (using the `.tsx` file format).
 
 After creating a TypeScript demo, run `pnpm docs:typescript:formatted` to automatically create the JavaScript version, which is also required.
 
-If you're not familiar with TypeScript, you can write the demo in JavaScript, and a core contributor may help you migrate it to TS.
+If you're not familiar with TypeScript, you can write the demo in JavaScript, and a core contributor may help you migrate it to TypeScript.
 
 #### 3. Edit the page's Markdown file
 

diff --git a/README.md b/README.md
@@ -117,15 +117,15 @@ You can find complete templates and themes in the [MUI Store](https://mui.com/s
 Read the [contributing guide](/CONTRIBUTING.md) to learn about our development process, how to propose bug fixes and improvements, and how to build and test your changes.
 
 Contributing is about more than just issues and pull requests!
-There are many other ways to [support MUI](https://mui.com/material-ui/getting-started/faq/#mui-is-awesome-how-can-i-support-the-project) beyond contributing to the code base.
+There are many other ways to [support Material UI](https://mui.com/material-ui/getting-started/faq/#mui-is-awesome-how-can-i-support-the-project) beyond contributing to the code base.
 
 ## Changelog
 
 The [changelog](https://github.com/mui/material-ui/releases) is regularly updated to reflect what's changed in each new release.
 
 ## Roadmap
 
-Future plans and high-priority features and enhancements can be found in our [roadmap](https://mui.com/material-ui/discover-more/roadmap/).
+Future plans and high-priority features and enhancements can be found in the [roadmap](https://mui.com/material-ui/discover-more/roadmap/).
 
 ## License
 

diff --git a/TYPESCRIPT_CONVENTION.md b/TYPESCRIPT_CONVENTION.md
@@ -8,7 +8,7 @@
 
 ### `Props Interface`
 
-- export interface `{ComponentName}classes` from `{component}Classes.ts` and add comment for generating api docs (for internal components, may or may not expose classes but don't need comment)
+- export interface `{ComponentName}classes` from `{component}Classes.ts` and add comment for generating API docs (for internal components, may or may not expose classes but don't need comment)
 - export interface `{ComponentName}Props`
 - always export props interface (use `interface` over `type`) from the component file
 

diff --git a/dangerfile.ts b/dangerfile.ts
@@ -194,7 +194,7 @@ function addDeployPreviewUrls() {
     const fragments = url.split('/').reverse();
     if (fragments[0] === fragments[1]) {
       // check if the end of pathname is the same as the one before
-      // e.g. `/data/material/getting-started/overview/overview.md
+      // for example `/data/material/getting-started/overview/overview.md
       url = fragments.slice(1).reverse().join('/');
     }
 

diff --git a/docs/data/base/components/focus-trap/focus-trap.md b/docs/data/base/components/focus-trap/focus-trap.md
@@ -78,7 +78,7 @@ The following demo uses the [Portal](/base-ui/react-portal/) component to render
 
 ### Using a toggle inside the trap
 
-The most common use-case for the Focus Trap component is to maintain focus within a [Modal](/base-ui/react-modal/) component that is entirely separate from the element that opens the modal.
+The most common use case for the Focus Trap component is to maintain focus within a [Modal](/base-ui/react-modal/) component that is entirely separate from the element that opens the modal.
 But you can also create a toggle button for the `open` prop of the Focus Trap component that is stored inside of the component itself, as shown in the following demo:
 
 {{"demo": "ContainedToggleTrappedFocus.js"}}
diff --git a/docs/data/base/components/form-control/form-control.md b/docs/data/base/components/form-control/form-control.md
@@ -82,7 +82,7 @@ The demo below shows how to integrate this hook with its component counterpart:
 
 {{"demo": "UseFormControl.js", "defaultCodeOpen": false}}
 
-Note that even though Form Control supports both controlled and uncontrolled-style APIs (i.e. it accepts `value` and `defaultValue` props), `useFormControlContext` returns only the controlled `value`.
+Note that even though Form Control supports both controlled and uncontrolled-style APIs (that is it accepts `value` and `defaultValue` props), `useFormControlContext` returns only the controlled `value`.
 This way, you don't have to implement both in your custom input—Form Control does this for you.
 
 :::info

diff --git a/docs/data/base/components/no-ssr/no-ssr.md b/docs/data/base/components/no-ssr/no-ssr.md
@@ -38,7 +38,7 @@ At its core, the No-SSR component's purpose is to defer rendering from the serve
 
 ### Delay client-side rendering
 
-You can also use No-SSR to delay the rendering of specific components on the client side—for example, to let the rest of the application load before an especially complex or data-heavy component.
+You can also use No-SSR to delay the rendering of specific components on the client-side—for example, to let the rest of the application load before an especially complex or data-heavy component.
 
 The following demo shows how to use the `defer` prop to prioritize rendering the rest of the app outside of what is nested within No-SSR:
 

diff --git a/docs/data/base/components/tabs/tabs.md b/docs/data/base/components/tabs/tabs.md
@@ -35,7 +35,7 @@ import { TabPanel } from '@mui/base/TabPanel';
 import { Tabs } from '@mui/base/Tabs';
 ```
 
-By default, Tab components and their corresponding panels are **zero-indexed** (i.e. the first tab has a `value` of `0`, then `1`, `2`, etc.).
+By default, Tab components and their corresponding panels are **zero-indexed** (that is the first tab has a `value` of `0`, then `1`, `2`, etc.).
 Clicking on a given Tab opens the panel with the same `value`, which corresponds to the order in which each component is nested within its container.
 
 Though not required, you can add the `value` prop to the Tab and Tab Panel to take control over how these components are associated with one another.

diff --git a/docs/data/base/getting-started/customization/customization.md b/docs/data/base/getting-started/customization/customization.md
@@ -29,9 +29,9 @@ The answer depends on the styling solution used in the project:
 
 You can either [style the components using the built-in classes](#applying-custom-css-rules) or [specify your own classes](#customizing-slot-props) and reference them in your stylesheets.
 
-#### CSS Modules
+#### CSS Modules
 
-When working with [CSS Modules](https://github.com/css-modules/css-modules), the simplest approach is to [specify custom classes using `slotProps`](#customizing-slot-props), as shown below:
+When working with [CSS Modules](https://github.com/css-modules/css-modules), the simplest approach is to [specify custom classes using `slotProps`](#customizing-slot-props), as shown below:
 
 ```tsx
 import clsx from 'clsx';
@@ -57,9 +57,9 @@ export default function Switch(props) {
 
 In this example we're using the [clsx](https://www.npmjs.com/package/clsx) utility to reduce the effort needed to apply class names conditionally.
 
-#### Tailwind CSS
+#### Tailwind CSS
 
-Use [`slotProps`](#customizing-slot-props) to apply custom styles using [Tailwind CSS](https://tailwindcss.com/), as shown below:
+Use [`slotProps`](#customizing-slot-props) to apply custom styles using [Tailwind CSS](https://tailwindcss.com/), as shown below:
 
 ```tsx
 import { Switch as BaseSwitch, SwitchOwnerState } from '@mui/base/Switch';
@@ -83,7 +83,7 @@ export default function Switch(props) {
 }
 ```
 
-See our [Working with Tailwind CSS guide](/base-ui/guides/working-with-tailwind-css/) for more information about integrating Base UI and Tailwind CSS.
+See our [Working with Tailwind CSS guide](/base-ui/guides/working-with-tailwind-css/) for more information about integrating Base UI and Tailwind CSS.
 
 #### Styled components
 
@@ -195,7 +195,7 @@ If you need complete control over a component's rendered HTML structure, you can
 Hooks give you access to the _logic_ that a component uses, but without any default structure.
 See ["Components vs. hooks" on the Base Usage page](/base-ui/getting-started/usage/#components-vs-hooks) for more details.
 
-Hooks return the current state of the component (e.g. `checked`, `disabled`, `open`, etc.) and provide functions that return props you can apply to your fully custom components.
+Hooks return the current state of the component (for example `checked`, `disabled`, `open`, etc.) and provide functions that return props you can apply to your fully custom components.
 
 In the case of [Switch](/base-ui/react-switch/), the component is accompanied by the `useSwitch` hook which gives you all of the functionality without any structure.
 

diff --git a/docs/data/base/getting-started/overview/overview.md b/docs/data/base/getting-started/overview/overview.md
@@ -17,8 +17,8 @@ Base UI includes prebuilt components with production-ready functionality, along
 With Base UI, you can rapidly build on top of our foundational components using any styling solution you choose—no need to override any default style engine or theme.
 
 :::warning
-Base UI's API is currently being revised; there will be no new features or components added to the current implementation.
-Learn more about plans for Base UI in [this blog post](/blog/base-ui-2024-plans/).
+Base UI's API is currently being revised; there will be no new features or components added to the current implementation.
+Learn more about plans for Base UI in [this blog post](/blog/base-ui-2024-plans/).
 :::
 
 ## Advantages of Base UI

diff --git a/docs/data/base/getting-started/quickstart/quickstart.md b/docs/data/base/getting-started/quickstart/quickstart.md
@@ -106,7 +106,7 @@ Pass a `className` prop and use it as a styling hook:
 <Button className="btn">Create Repository</Button>
 ```
 
-Base UI components like the Button come with a classes object (e.g. `buttonClasses`) that provides class hooks for styling a particular state.
+Base UI components like the Button come with a classes object (for example `buttonClasses`) that provides class hooks for styling a particular state.
 
 ```css
 /* To style the disabled state: */
@@ -120,15 +120,15 @@ The demo below shows how to create the Primer button using plain CSS with Base
 
 {{"demo": "BaseButtonPlainCss.js", "defaultCodeOpen": false}}
 
-### Styling with Tailwind CSS
+### Styling with Tailwind CSS
 
-After installing Tailwind CSS, pass its utility classes to `className`, as shown below:
+After installing Tailwind CSS, pass its utility classes to `className`, as shown below:
 
 ```tsx
 <Button className="bg-green-600 rounded-md py-1 px-4...">Create Repository</Button>
 ```
 
-The demo below shows how to build the Primer button using Tailwind CSS:
+The demo below shows how to build the Primer button using Tailwind CSS:
 
 {{"demo": "BaseButtonTailwind.js", "hideToolbar": true, "bg": "inline"}}
 

diff --git a/docs/data/base/getting-started/roadmap/roadmap.md b/docs/data/base/getting-started/roadmap/roadmap.md
@@ -1,22 +1,22 @@
 # Roadmap
 
-<p class="description">Keep up with ongoing projects and help shape the future of Base UI.</p>
+<p class="description">Keep up with ongoing projects and help shape the future of Base UI.</p>
 
 ## How we prioritize
 
-Base UI is a community-driven project, meaning we usually pick the issues and suggestions that resonate the most with the community.
+Base UI is a community-driven project, meaning we usually pick the issues and suggestions that resonate the most with the community.
 Therefore, make sure to leave an upvote 👍 on [the GitHub issues](https://github.com/mui/base-ui/issues) you are most interested in.
 
-Additionally, we conduct annual [developer surveys](/blog/?tags=Developer+survey/) which also serve as key inputs for Base UI's roadmap.
+Additionally, we conduct annual [developer surveys](/blog/?tags=Developer+survey/) which also serve as key inputs for Base UI's roadmap.
 Your participation is invaluable—keep an eye on MUI's social media to catch the next survey and help shape the future of the library!
 
 ## Keeping track of the roadmap
 
 ### GitHub project
 
-The Base UI GitHub project is where you can see the ongoing priorities for the library.
+The Base UI GitHub project is where you can see the ongoing priorities for the library.
 We typically add umbrella issues to the project board after discussing them internally.
 
-**[Visit the Base UI project board 👉](https://github.com/orgs/mui/projects/1/views/13)**
+**[Visit the Base UI project board 👉](https://github.com/orgs/mui/projects/1/views/13)**
 
-<img src="/static/base-ui/roadmap/github-roadmap.png" style="width: 814px;" alt="A screenshot of the public Base UI GitHub project." width="1628" height="400" />
+<img src="/static/base-ui/roadmap/github-roadmap.png" style="width: 814px;" alt="A screenshot of the public Base UI GitHub project." width="1628" height="400" />
diff --git a/docs/data/base/guides/next-js-app-router/next-js-app-router.md b/docs/data/base/guides/next-js-app-router/next-js-app-router.md
@@ -6,7 +6,7 @@
 
 Starting fresh on a new App Router-based project?
 
-Jump right into the code with [this example: Base UI - Next.js App Router with Tailwind CSS in TypeScript](https://github.com/mui/material-ui/tree/master/examples/base-ui-nextjs-tailwind-ts).
+Jump right into the code with [this example: Base UI - Next.js App Router with Tailwind CSS in TypeScript](https://github.com/mui/material-ui/tree/master/examples/base-ui-nextjs-tailwind-ts).
 
 ## Next.js and React Server Components
 
@@ -24,11 +24,11 @@ For more details, see [this explanation](https://github.com/reactwg/server-compo
 ## Setting up Base UI with the App Router
 
 Base UI gives you the freedom to choose your own styling solution, so setting up a Next.js App Router project largely depends on what you choose.
-This guide covers Tailwind CSS, Emotion, and other CSS-in-JS solutions like styled-components.
+This guide covers Tailwind CSS, Emotion, and other CSS-in-JS solutions like styled-components.
 
-### Tailwind CSS
+### Tailwind CSS
 
-Follow the [Tailwind CSS guide on working with Next.js](https://tailwindcss.com/docs/guides/nextjs), and be sure to add the `app` directory and other directories to `tailwind.config.js`, as shown below:
+Follow the [Tailwind CSS guide on working with Next.js](https://tailwindcss.com/docs/guides/nextjs), and be sure to add the `app` directory and other directories to `tailwind.config.js`, as shown below:
 
 ```js
 /** @type {import('tailwindcss').Config} */
@@ -46,7 +46,7 @@ module.exports = {
 };
 ```
 
-Refer to this [example repo](https://github.com/mui/material-ui/tree/master/examples/base-ui-nextjs-tailwind-ts) for a full working demo of a Next.js 13 app using Base UI and Tailwind CSS.
+Refer to this [example repo](https://github.com/mui/material-ui/tree/master/examples/base-ui-nextjs-tailwind-ts) for a full working demo of a Next.js 13 app using Base UI and Tailwind CSS.
 
 ### Emotion
 
@@ -124,7 +124,7 @@ export default function RootLayout(props) {
 }
 ```
 
-If you need to further override theme styles (e.g. using CSS modules), Emotion provides the `prepend: true` option for `createCache` to reverse the injection order, so custom styles can override the theme without using `!important`.
+If you need to further override theme styles (for example using CSS Modules), Emotion provides the `prepend: true` option for `createCache` to reverse the injection order, so custom styles can override the theme without using `!important`.
 
 Currently, `prepend` does not work reliably with the App Router, but you can work around it by wrapping Emotion styles in a CSS `@layer` with a modification to the snippet above: