From f09e2413a929ad5b28466ceb3dab09e5203fcbbb Mon Sep 17 00:00:00 2001 From: alexandre Date: Fri, 27 Oct 2023 14:48:37 +0200 Subject: [PATCH 1/7] [core] Setup vale for enforcing style guides --- .github/styles/Blog/ComposedWords.yml | 13 ++++++++++ .github/styles/Blog/NamingConventions.yml | 17 +++++++++++++ .github/styles/Blog/Typos.yml | 11 ++++++++ .github/styles/Vocab/accept.txt | 0 .github/styles/Vocab/reject.txt | 0 .github/workflows/vale-action.yml | 23 +++++++++++++++++ .gitignore | 3 +++ .vale.ini | 31 +++++++++++++++++++++++ 8 files changed, 98 insertions(+) create mode 100644 .github/styles/Blog/ComposedWords.yml create mode 100644 .github/styles/Blog/NamingConventions.yml create mode 100644 .github/styles/Blog/Typos.yml create mode 100644 .github/styles/Vocab/accept.txt create mode 100644 .github/styles/Vocab/reject.txt create mode 100644 .github/workflows/vale-action.yml create mode 100644 .vale.ini diff --git a/.github/styles/Blog/ComposedWords.yml b/.github/styles/Blog/ComposedWords.yml new file mode 100644 index 00000000000000..d9590deffdbf8f --- /dev/null +++ b/.github/styles/Blog/ComposedWords.yml @@ -0,0 +1,13 @@ +extends: substitution +message: To be consistent with the rest of the documentation, consider using '%s' instead of '%s'. +level: warning +ignorecase: true +# swap maps tokens in form of bad: good +# for more information: https://vale.sh/docs/topics/styles/#substitution +swap: + sub-component: subcomponent + sub-components: subcomponents + 'sub component': subcomponent + 'sub components': subcomponents + usecase: use-case + 'use case': use-case diff --git a/.github/styles/Blog/NamingConventions.yml b/.github/styles/Blog/NamingConventions.yml new file mode 100644 index 00000000000000..116d28a576a593 --- /dev/null +++ b/.github/styles/Blog/NamingConventions.yml @@ -0,0 +1,17 @@ +extends: substitution +message: To be consistent with capitalization, consider using '%s' instead of '%s'. +level: warning +ignorecase: false +# swap maps tokens in form of bad: good +# for more information: https://vale.sh/docs/topics/styles/#substitution +swap: + api: API + Api: API + typescript: TypeScript + Typescript: TypeScript + ts: TypeScript + TS: TypeScript + javascript: JavaScript + Javascript: JavaScript + css: CSS + Css: CSS diff --git a/.github/styles/Blog/Typos.yml b/.github/styles/Blog/Typos.yml new file mode 100644 index 00000000000000..b18f8002373131 --- /dev/null +++ b/.github/styles/Blog/Typos.yml @@ -0,0 +1,11 @@ +extends: substitution +message: Do you mean '%s' instead of '%s'? +level: warning +ignorecase: true +# swap maps tokens in form of bad: good +# for more information: https://vale.sh/docs/topics/styles/#substitution +swap: + bellow: below + eg: e.g. + eg.: e.g. + 'e.g ': 'e.g. ' diff --git a/.github/styles/Vocab/accept.txt b/.github/styles/Vocab/accept.txt new file mode 100644 index 00000000000000..e69de29bb2d1d6 diff --git a/.github/styles/Vocab/reject.txt b/.github/styles/Vocab/reject.txt new file mode 100644 index 00000000000000..e69de29bb2d1d6 diff --git a/.github/workflows/vale-action.yml b/.github/workflows/vale-action.yml new file mode 100644 index 00000000000000..61078d7162eeff --- /dev/null +++ b/.github/workflows/vale-action.yml @@ -0,0 +1,23 @@ +name: Vale action + +on: [pull_request] + +permissions: {} + +jobs: + vale: + name: runner / vale + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + steps: + - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1 + - uses: errata-ai/vale-action@c4213d4de3d5f718b8497bd86161531c78992084 # v2.0.1 + 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}} diff --git a/.gitignore b/.gitignore index d8f84f0b8b32f9..8d71e1848bcfa3 100644 --- a/.gitignore +++ b/.gitignore @@ -37,3 +37,6 @@ node_modules package-lock.json size-snapshot.json docs/public/static/blog/feed/* +# vale downloaded config +.github/styles/Google +.github/styles/write-good diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 00000000000000..f5d60e591ac8db --- /dev/null +++ b/.vale.ini @@ -0,0 +1,31 @@ +# Config vale. More information at https://docs.errata.ai/vale/config +StylesPath = .github/styles +MinAlertLevel = suggestion + +Packages = Google + +[*.md] +# Ignore code injection which start with {{... +BlockIgnores = {{.* + +# Custom syle +# BasedOnStyles = Blog + +Blog.ComposedWords = YES +Blog.NamingConventions = YES +Blog.Typos = YES + +# 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 + +# 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 \ No newline at end of file From 67fb59ce48085009aaa467eb86818d0a8ffcaa7d Mon Sep 17 00:00:00 2001 From: alexandre Date: Fri, 27 Oct 2023 16:45:38 +0200 Subject: [PATCH 2/7] standard naming --- docs/data/base/components/focus-trap/focus-trap.md | 2 +- .../working-with-tailwind-css/working-with-tailwind-css.md | 2 +- .../data/material/guides/interoperability/interoperability.md | 2 +- .../css-theme-variables/css-theme-variables.md | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/data/base/components/focus-trap/focus-trap.md b/docs/data/base/components/focus-trap/focus-trap.md index e04aa60f994042..76c850021919f3 100644 --- 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/guides/working-with-tailwind-css/working-with-tailwind-css.md b/docs/data/base/guides/working-with-tailwind-css/working-with-tailwind-css.md index ecf77e777d7cf2..a63fbc4736b4e4 100644 --- a/docs/data/base/guides/working-with-tailwind-css/working-with-tailwind-css.md +++ b/docs/data/base/guides/working-with-tailwind-css/working-with-tailwind-css.md @@ -27,7 +27,7 @@ All credits go to the Tailwind Labs team for designing this component, found on ## Setting up the project -We'll use [`create-react-app` with typescript](https://create-react-app.dev/docs/adding-typescript/#installation) for this guide. +We'll use [`create-react-app` with TypeScript](https://create-react-app.dev/docs/adding-typescript/#installation) for this guide. After you have created the project, follow the instructions given on the [Tailwind CSS installation page](https://tailwindcss.com/docs/guides/create-react-app) in order to configure `tailwind`. Next, install `@mui/base` in the project: diff --git a/docs/data/material/guides/interoperability/interoperability.md b/docs/data/material/guides/interoperability/interoperability.md index d80e88e0312e8b..5f6a9d244e76df 100644 --- a/docs/data/material/guides/interoperability/interoperability.md +++ b/docs/data/material/guides/interoperability/interoperability.md @@ -295,7 +295,7 @@ If, however, you would like to use styled-components, you can configure your app - [Create React App with styled-components](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components) -- [Create React App with styled-components and typescript](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components-ts) +- [Create React App with styled-components and TypeScript](https://github.com/mui/material-ui/tree/master/examples/material-ui-cra-styled-components-ts) Following this approach reduces the bundle size, and removes the need to configure the CSS injection order. diff --git a/docs/data/system/experimental-api/css-theme-variables/css-theme-variables.md b/docs/data/system/experimental-api/css-theme-variables/css-theme-variables.md index c6e4f48b364c43..1183feacf509c8 100644 --- a/docs/data/system/experimental-api/css-theme-variables/css-theme-variables.md +++ b/docs/data/system/experimental-api/css-theme-variables/css-theme-variables.md @@ -114,7 +114,7 @@ const myCustomDefaultTheme = extendTheme(); export default myCustomDefaultTheme; ``` -Here, the returned `theme` object needs to follow a certain structure to be used correctly by the final `CssVarsProvider`. It should have a `colorSchemes` key with the light and dark (and any other) palette. `prepareCssVars` import from `@mui/system` is used to create css variable names which can then be easily accessed using the returned `vars`. This is also added to the `theme` object. Finally, `myCustomDefaultTheme` theme object is created that can now be passed to the `createCssVarsProvider` to get a `CssVarsProvider`. +Here, the returned `theme` object needs to follow a certain structure to be used correctly by the final `CssVarsProvider`. It should have a `colorSchemes` key with the light and dark (and any other) palette. `prepareCssVars` import from `@mui/system` is used to create CSS variable names which can then be easily accessed using the returned `vars`. This is also added to the `theme` object. Finally, `myCustomDefaultTheme` theme object is created that can now be passed to the `createCssVarsProvider` to get a `CssVarsProvider`. ```js // CssVarsProvider.js @@ -133,7 +133,7 @@ export { CssVarsProvider, useColorScheme }; Now wrap your top level app component with this `CssVarsProvider` component and then you can access the passed theme value to any of the components rendered inside the provider. -Example of a component using the css variable - +Example of a component using the CSS variable - ```js // Button.js From 69ed422e7773f62393259da200322c450bd4cbcc Mon Sep 17 00:00:00 2001 From: alexandre Date: Fri, 27 Oct 2023 16:48:00 +0200 Subject: [PATCH 3/7] renam sub-components -> subcomponents --- docs/data/material/components/selects/selects.md | 2 +- docs/data/material/guides/api/api.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/data/material/components/selects/selects.md b/docs/data/material/components/selects/selects.md index e74eaf9f1ad07d..42689fcd76dbd7 100644 --- a/docs/data/material/components/selects/selects.md +++ b/docs/data/material/components/selects/selects.md @@ -30,7 +30,7 @@ It's meant to be an improved version of the "react-select" and "downshift" packa ## Props The Select component is implemented as a custom `` element of the [InputBase](/material-ui/api/input-base/). -It extends the [text field components](/material-ui/react-text-field/) sub-components, either the [OutlinedInput](/material-ui/api/outlined-input/), [Input](/material-ui/api/input/), or [FilledInput](/material-ui/api/filled-input/), depending on the variant selected. +It extends the [text field components](/material-ui/react-text-field/) subcomponents, either the [OutlinedInput](/material-ui/api/outlined-input/), [Input](/material-ui/api/input/), or [FilledInput](/material-ui/api/filled-input/), depending on the variant selected. It shares the same styles and many of the same props. Refer to the respective component's API page for details. ### Filled and standard variants diff --git a/docs/data/material/guides/api/api.md b/docs/data/material/guides/api/api.md index 1dbecd25c9e6fb..e4cf36440b15bd 100644 --- a/docs/data/material/guides/api/api.md +++ b/docs/data/material/guides/api/api.md @@ -79,7 +79,7 @@ Nested components inside a component have: - their own flattened props when these are key to the top level component abstraction, for instance an `id` prop for the `Input` component. -- their own `xxxProps` prop when users might need to tweak the internal render method's sub-components, +- their own `xxxProps` prop when users might need to tweak the internal render method's subcomponents, for instance, exposing the `inputProps` and `InputProps` props on components that use `Input` internally. - their own `xxxComponent` prop for performing component injection. - their own `xxxRef` prop when you might need to perform imperative actions, From 660f21d221f84ee6da7096b9ba44c5ae0ab1dbf3 Mon Sep 17 00:00:00 2001 From: Alexandre Fauquette <45398769+alexfauquette@users.noreply.github.com> Date: Mon, 30 Oct 2023 12:21:03 +0100 Subject: [PATCH 4/7] Update .github/styles/Blog/ComposedWords.yml Signed-off-by: Alexandre Fauquette <45398769+alexfauquette@users.noreply.github.com> --- .github/styles/Blog/ComposedWords.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/styles/Blog/ComposedWords.yml b/.github/styles/Blog/ComposedWords.yml index d9590deffdbf8f..4acf04623a7c68 100644 --- a/.github/styles/Blog/ComposedWords.yml +++ b/.github/styles/Blog/ComposedWords.yml @@ -9,5 +9,5 @@ swap: sub-components: subcomponents 'sub component': subcomponent 'sub components': subcomponents - usecase: use-case - 'use case': use-case + 'use-case': 'use case' + 'use-case': 'use case' From 6eb20f3b6fb9915653be5e39e3845fc6d47a8294 Mon Sep 17 00:00:00 2001 From: Alexandre Fauquette <45398769+alexfauquette@users.noreply.github.com> Date: Mon, 30 Oct 2023 12:28:19 +0100 Subject: [PATCH 5/7] Apply suggestions from code review Signed-off-by: Alexandre Fauquette <45398769+alexfauquette@users.noreply.github.com> --- .github/styles/Blog/Typos.yml | 3 --- .vale.ini | 2 +- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/styles/Blog/Typos.yml b/.github/styles/Blog/Typos.yml index b18f8002373131..1a6e5407f69c9a 100644 --- a/.github/styles/Blog/Typos.yml +++ b/.github/styles/Blog/Typos.yml @@ -6,6 +6,3 @@ ignorecase: true # for more information: https://vale.sh/docs/topics/styles/#substitution swap: bellow: below - eg: e.g. - eg.: e.g. - 'e.g ': 'e.g. ' diff --git a/.vale.ini b/.vale.ini index f5d60e591ac8db..5b8e5d70df6b02 100644 --- a/.vale.ini +++ b/.vale.ini @@ -25,7 +25,7 @@ Google.We = YES # Try to avoid using first-person plural # 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 +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 \ No newline at end of file From 25eb7041e1f734d24cbbd32be9a9f1350f2b59aa Mon Sep 17 00:00:00 2001 From: alexandre Date: Mon, 30 Oct 2023 12:30:06 +0100 Subject: [PATCH 6/7] fix --- .github/styles/Blog/ComposedWords.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/styles/Blog/ComposedWords.yml b/.github/styles/Blog/ComposedWords.yml index 4acf04623a7c68..a18f017ed64a7e 100644 --- a/.github/styles/Blog/ComposedWords.yml +++ b/.github/styles/Blog/ComposedWords.yml @@ -10,4 +10,4 @@ swap: 'sub component': subcomponent 'sub components': subcomponents 'use-case': 'use case' - 'use-case': 'use case' + 'usecase': 'use case' From faf77b3783c044795053b241e1a0934490da5e9b Mon Sep 17 00:00:00 2001 From: Alexandre Fauquette <45398769+alexfauquette@users.noreply.github.com> Date: Mon, 30 Oct 2023 15:00:55 +0100 Subject: [PATCH 7/7] Update .vale.ini Signed-off-by: Alexandre Fauquette <45398769+alexfauquette@users.noreply.github.com> --- .vale.ini | 1 + 1 file changed, 1 insertion(+) diff --git a/.vale.ini b/.vale.ini index 5b8e5d70df6b02..fbace57ed3bdc5 100644 --- a/.vale.ini +++ b/.vale.ini @@ -22,6 +22,7 @@ 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. # Those rules are not repected a lot # Google.Passive = YES # In general, use active voice instead of passive voice.