From 9ec72848e649b54c8bf47f025e00026ac344105b Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 23 Jun 2023 13:39:28 -0500 Subject: [PATCH 1/7] docs: add playground links to correct and incorrect code blocks --- docs/.eleventy.js | 36 ++++++++++++++++++++++++++++++++-- docs/src/assets/scss/docs.scss | 23 ++++++++++++++++++++++ 2 files changed, 57 insertions(+), 2 deletions(-) diff --git a/docs/.eleventy.js b/docs/.eleventy.js index 1bd1de1af2f..73725a9d207 100644 --- a/docs/.eleventy.js +++ b/docs/.eleventy.js @@ -179,14 +179,46 @@ module.exports = function(eleventyConfig) { `.trim(); } + /** + * Encodes text in the base 64 format used in playground URL params. + * @param {string} text Text to be encoded to base 64. + * @see https://github.com/eslint/eslint.org/blob/1b2f2aabeac2955a076d61788da8a0008bca6fb6/src/playground/utils/unicode.js + * @returns {string} The base 64 encoded equivalent of the text. + */ + function encodeToBase64(text) { + /* global btoa -- It does exist, and is what the playground uses. */ + return btoa(unescape(encodeURIComponent(text))); + } + + const withPlaygroundRender = { + render(tokens, index) { + if (tokens[index].nesting !== 1) { + return ""; + } + + const state = encodeToBase64( + JSON.stringify({ + text: tokens[index + 1].content + }) + ); + + return ` +
+ + Open in Playground ↗️ + + `.trim(); + } + }; + const markdownIt = require("markdown-it"); const md = markdownIt({ html: true, linkify: true, typographer: true, highlight: (str, lang) => highlighter(md, str, lang) }) .use(markdownItAnchor, { slugify: s => slug(s) }) .use(markdownItContainer, "img-container", {}) - .use(markdownItContainer, "correct", {}) - .use(markdownItContainer, "incorrect", {}) + .use(markdownItContainer, "correct", withPlaygroundRender) + .use(markdownItContainer, "incorrect", withPlaygroundRender) .use(markdownItContainer, "warning", { render(tokens, idx) { return generateAlertMarkup("warning", tokens, idx); diff --git a/docs/src/assets/scss/docs.scss b/docs/src/assets/scss/docs.scss index ee40123891d..4177b6c517b 100644 --- a/docs/src/assets/scss/docs.scss +++ b/docs/src/assets/scss/docs.scss @@ -126,6 +126,29 @@ div.incorrect { } } +div.with-playground-link { + position: relative; +} + +a.open-in-playground { + background-color: var(--lightest-background-color); + border-radius: 0.25rem; + border: 1px solid var(--border-color); + color: unset; + opacity: 0; + padding: 0.5rem 0.75rem; + position: absolute; + right: 0.5rem; + text-decoration: none; + top: 0.5rem; + transition: opacity 0.2s linear; + z-index: 1; +} + +a.open-in-playground:is(:focus, :hover) { + opacity: 1; +} + div.img-container { background-color: var(--img-background-color); border-radius: var(--border-radius); From 09d5bef62c5001206d7c4c77c3787320e65a6a99 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 7 Jul 2023 14:36:15 -0400 Subject: [PATCH 2/7] Added info options and used existing styles --- docs/.eleventy.js | 56 +++++++++++++++---------- docs/src/assets/js/main.js | 18 -------- docs/src/assets/scss/docs.scss | 28 +------------ docs/src/rules/no-implicit-globals.md | 22 +++++----- docs/src/rules/no-restricted-imports.md | 36 ++++++++-------- 5 files changed, 65 insertions(+), 95 deletions(-) diff --git a/docs/.eleventy.js b/docs/.eleventy.js index 73725a9d207..93348af77fd 100644 --- a/docs/.eleventy.js +++ b/docs/.eleventy.js @@ -190,26 +190,40 @@ module.exports = function(eleventyConfig) { return btoa(unescape(encodeURIComponent(text))); } - const withPlaygroundRender = { - render(tokens, index) { - if (tokens[index].nesting !== 1) { - return "
"; + /** + * Creates markdownItContainer settings for a playground-linked codeblock. + * @param {string} name Plugin name and class name to add to the code block. + * @returns {[string, object]} Plugin name and options for markdown-it. + */ + function withPlaygroundRender(name) { + return [ + name, + { + render(tokens, index) { + if (tokens[index].nesting !== 1) { + return ""; + } + + // See https://github.com/eslint/eslint.org/blob/ac38ab41f99b89a8798d374f74e2cce01171be8b/src/playground/App.js#L44 + const options = tokens[index].info?.split("correct ")[1]?.trim(); + const { content } = tokens[index + 1]; + const state = encodeToBase64( + JSON.stringify({ + ...(options && { options: JSON.parse(options) }), + text: content + }) + ); + + return ` +
+ + Open in Playground ↗️ + + `.trim(); + } } - - const state = encodeToBase64( - JSON.stringify({ - text: tokens[index + 1].content - }) - ); - - return ` -
- - Open in Playground ↗️ - - `.trim(); - } - }; + ]; + } const markdownIt = require("markdown-it"); const md = markdownIt({ html: true, linkify: true, typographer: true, highlight: (str, lang) => highlighter(md, str, lang) }) @@ -217,8 +231,8 @@ module.exports = function(eleventyConfig) { slugify: s => slug(s) }) .use(markdownItContainer, "img-container", {}) - .use(markdownItContainer, "correct", withPlaygroundRender) - .use(markdownItContainer, "incorrect", withPlaygroundRender) + .use(markdownItContainer, ...withPlaygroundRender("correct")) + .use(markdownItContainer, ...withPlaygroundRender("incorrect")) .use(markdownItContainer, "warning", { render(tokens, idx) { return generateAlertMarkup("warning", tokens, idx); diff --git a/docs/src/assets/js/main.js b/docs/src/assets/js/main.js index bf3268266f4..80168a136c9 100644 --- a/docs/src/assets/js/main.js +++ b/docs/src/assets/js/main.js @@ -192,24 +192,6 @@ } })(); -// add "Open in Playground" button to code blocks -// (function() { -// let blocks = document.querySelectorAll('pre[class*="language-"]'); -// if (blocks) { -// blocks.forEach(function(block) { -// let button = document.createElement("a"); -// button.classList.add('c-btn--playground'); -// button.classList.add('c-btn'); -// button.classList.add('c-btn--secondary'); -// button.setAttribute("href", "#"); -// button.innerText = "Open in Playground"; -// block.appendChild(button); -// }); -// } -// })(); - - - // add utilities var util = { keyCodes: { diff --git a/docs/src/assets/scss/docs.scss b/docs/src/assets/scss/docs.scss index 4177b6c517b..381a4c23320 100644 --- a/docs/src/assets/scss/docs.scss +++ b/docs/src/assets/scss/docs.scss @@ -126,29 +126,6 @@ div.incorrect { } } -div.with-playground-link { - position: relative; -} - -a.open-in-playground { - background-color: var(--lightest-background-color); - border-radius: 0.25rem; - border: 1px solid var(--border-color); - color: unset; - opacity: 0; - padding: 0.5rem 0.75rem; - position: absolute; - right: 0.5rem; - text-decoration: none; - top: 0.5rem; - transition: opacity 0.2s linear; - z-index: 1; -} - -a.open-in-playground:is(:focus, :hover) { - opacity: 1; -} - div.img-container { background-color: var(--img-background-color); border-radius: var(--border-radius); @@ -169,10 +146,7 @@ pre[class*="language-"] { right: 0.5rem; offset-block-end: 0.5rem; offset-inline-end: 0.5rem; - - @media all and (max-width: 768px) { - display: none; - } + z-index: 1; } @media (hover: none) { diff --git a/docs/src/rules/no-implicit-globals.md b/docs/src/rules/no-implicit-globals.md index 1e5c5fad723..9d8590158e3 100644 --- a/docs/src/rules/no-implicit-globals.md +++ b/docs/src/rules/no-implicit-globals.md @@ -44,7 +44,7 @@ This rule disallows `var` and `function` declarations at the top-level script sc Examples of **incorrect** code for this rule: -::: incorrect +::: incorrect { "parserOptions": { "sourceType": "script" } } ```js /*eslint no-implicit-globals: "error"*/ @@ -58,7 +58,7 @@ function bar() {} Examples of **correct** code for this rule: -::: correct +::: correct { "parserOptions": { "sourceType": "script" } } ```js /*eslint no-implicit-globals: "error"*/ @@ -79,7 +79,7 @@ window.bar = function() {}; Examples of **correct** code for this rule with `"parserOptions": { "sourceType": "module" }` in the ESLint configuration: -::: correct +::: correct { "parserOptions": { "sourceType": "script" } } ```js /*eslint no-implicit-globals: "error"*/ @@ -100,7 +100,7 @@ This does not apply to ES modules since the module code is implicitly in `strict Examples of **incorrect** code for this rule: -::: incorrect +::: incorrect { "parserOptions": { "sourceType": "script" } } ```js /*eslint no-implicit-globals: "error"*/ @@ -127,7 +127,7 @@ or in a `/*global */` comment. Examples of **incorrect** code for this rule: -::: incorrect +::: incorrect { "parserOptions": { "sourceType": "script" } } ```js /*eslint no-implicit-globals: "error"*/ @@ -155,7 +155,7 @@ If the variable is intended to be local to the script, wrap the code with a bloc Examples of **correct** code for this rule with `"lexicalBindings"` option set to `false` (default): -::: correct +::: correct { "parserOptions": { "sourceType": "script" } } ```js /*eslint no-implicit-globals: ["error", {"lexicalBindings": false}]*/ @@ -171,7 +171,7 @@ class Bar {} Examples of **incorrect** code for this rule with `"lexicalBindings"` option set to `true`: -::: incorrect +::: incorrect { "parserOptions": { "sourceType": "script" } } ```js /*eslint no-implicit-globals: ["error", {"lexicalBindings": true}]*/ @@ -187,7 +187,7 @@ class Bar {} Examples of **correct** code for this rule with `"lexicalBindings"` option set to `true`: -::: correct +::: correct { "parserOptions": { "sourceType": "script" } } ```js /*eslint no-implicit-globals: ["error", {"lexicalBindings": true}]*/ @@ -221,7 +221,7 @@ Even the `typeof` check is not safe from TDZ reference exceptions. Examples of **incorrect** code for this rule with `"lexicalBindings"` option set to `true`: -::: incorrect +::: incorrect { "parserOptions": { "sourceType": "script" } } ```js /*eslint no-implicit-globals: ["error", {"lexicalBindings": true}]*/ @@ -239,7 +239,7 @@ const MyGlobalFunction = (function() { Examples of **correct** code for this rule with `"lexicalBindings"` option set to `true`: -::: correct +::: correct { "parserOptions": { "sourceType": "script" } } ```js /*eslint no-implicit-globals: ["error", {"lexicalBindings": true}]*/ @@ -261,7 +261,7 @@ You can use `/* exported variableName */` block comments in the same way as in [ Examples of **correct** code for `/* exported variableName */` operation: -::: correct +::: correct { "parserOptions": { "sourceType": "script" } } ```js /* exported global_var */ diff --git a/docs/src/rules/no-restricted-imports.md b/docs/src/rules/no-restricted-imports.md index ece0ceb5490..c3e10a62c39 100644 --- a/docs/src/rules/no-restricted-imports.md +++ b/docs/src/rules/no-restricted-imports.md @@ -130,7 +130,7 @@ To restrict the use of all Node.js core imports (via Date: Fri, 7 Jul 2023 19:57:55 -0400 Subject: [PATCH 3/7] Switch options to parserOptions --- docs/.eleventy.js | 4 +- docs/src/rules/no-implicit-globals.md | 93 ++++++++++++------------- docs/src/rules/no-restricted-imports.md | 71 ++++++++++--------- 3 files changed, 83 insertions(+), 85 deletions(-) diff --git a/docs/.eleventy.js b/docs/.eleventy.js index 93348af77fd..a6c557ddf97 100644 --- a/docs/.eleventy.js +++ b/docs/.eleventy.js @@ -205,11 +205,11 @@ module.exports = function(eleventyConfig) { } // See https://github.com/eslint/eslint.org/blob/ac38ab41f99b89a8798d374f74e2cce01171be8b/src/playground/App.js#L44 - const options = tokens[index].info?.split("correct ")[1]?.trim(); + const parserOptions = tokens[index].info?.split("correct ")[1]?.trim(); const { content } = tokens[index + 1]; const state = encodeToBase64( JSON.stringify({ - ...(options && { options: JSON.parse(options) }), + ...(parserOptions && { options: { parserOptions: JSON.parse(parserOptions) } }), text: content }) ); diff --git a/docs/src/rules/no-implicit-globals.md b/docs/src/rules/no-implicit-globals.md index 9d8590158e3..69b612ad4ee 100644 --- a/docs/src/rules/no-implicit-globals.md +++ b/docs/src/rules/no-implicit-globals.md @@ -2,16 +2,15 @@ title: no-implicit-globals rule_type: suggestion related_rules: -- no-undef -- no-global-assign -- no-unused-vars + - no-undef + - no-global-assign + - no-unused-vars further_reading: -- https://benalman.com/news/2010/11/immediately-invoked-function-expression/ -- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Undeclared_var -- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let#Temporal_dead_zone + - https://benalman.com/news/2010/11/immediately-invoked-function-expression/ + - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Undeclared_var + - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let#Temporal_dead_zone --- - It is the best practice to avoid 'polluting' the global scope with variables that are intended to be local to the script. Global variables created from a script can produce name collisions with global variables created from another script, which will @@ -19,9 +18,9 @@ usually lead to runtime errors or unexpected behavior. This rule disallows the following: -* Declarations that create one or more variables in the global scope. -* Global variable leaks. -* Redeclarations of read-only global variables and assignments to read-only global variables. +- Declarations that create one or more variables in the global scope. +- Global variable leaks. +- Redeclarations of read-only global variables and assignments to read-only global variables. There is an explicit way to create a global variable when needed, by assigning to a property of the global object. @@ -32,7 +31,7 @@ By default, this rule does not check `const`, `let` and `class` declarations. This rule has an object option with one option: -* Set `"lexicalBindings"` to `true` if you want this rule to check `const`, `let` and `class` declarations as well. +- Set `"lexicalBindings"` to `true` if you want this rule to check `const`, `let` and `class` declarations as well. ## Rule Details @@ -44,7 +43,7 @@ This rule disallows `var` and `function` declarations at the top-level script sc Examples of **incorrect** code for this rule: -::: incorrect { "parserOptions": { "sourceType": "script" } } +::: incorrect { "sourceType": "script" } ```js /*eslint no-implicit-globals: "error"*/ @@ -58,20 +57,20 @@ function bar() {} Examples of **correct** code for this rule: -::: correct { "parserOptions": { "sourceType": "script" } } +::: correct { "sourceType": "script" } ```js /*eslint no-implicit-globals: "error"*/ // explicitly set on window window.foo = 1; -window.bar = function() {}; +window.bar = function () {}; // intended to be scope to this file -(function() { - var foo = 1; +(function () { + var foo = 1; - function bar() {} + function bar() {} })(); ``` @@ -79,7 +78,7 @@ window.bar = function() {}; Examples of **correct** code for this rule with `"parserOptions": { "sourceType": "module" }` in the ESLint configuration: -::: correct { "parserOptions": { "sourceType": "script" } } +::: correct { "sourceType": "script" } ```js /*eslint no-implicit-globals: "error"*/ @@ -100,7 +99,7 @@ This does not apply to ES modules since the module code is implicitly in `strict Examples of **incorrect** code for this rule: -::: incorrect { "parserOptions": { "sourceType": "script" } } +::: incorrect { "sourceType": "script" } ```js /*eslint no-implicit-globals: "error"*/ @@ -122,12 +121,12 @@ A read-only global variable can be a built-in ES global (e.g. `Array`), an envir (e.g. `window` in the browser environment), or a global variable defined as `readonly` in the configuration file or in a `/*global */` comment. -* [Specifying Environments](../use/configure#specifying-environments) -* [Specifying Globals](../use/configure#specifying-globals) +- [Specifying Environments](../use/configure#specifying-environments) +- [Specifying Globals](../use/configure#specifying-globals) Examples of **incorrect** code for this rule: -::: incorrect { "parserOptions": { "sourceType": "script" } } +::: incorrect { "sourceType": "script" } ```js /*eslint no-implicit-globals: "error"*/ @@ -149,13 +148,13 @@ Lexical declarations `const` and `let`, as well as `class` declarations, create However, when declared in the top-level of a browser script these variables are not 'script-scoped'. They are actually created in the global scope and could produce name collisions with `var`, `const` and `let` variables and `function` and `class` declarations from other scripts. -This does not apply to ES and CommonJS modules. +This does not apply to ES and CommonJS modules. If the variable is intended to be local to the script, wrap the code with a block or with an immediately-invoked function expression (IIFE). Examples of **correct** code for this rule with `"lexicalBindings"` option set to `false` (default): -::: correct { "parserOptions": { "sourceType": "script" } } +::: correct { "sourceType": "script" } ```js /*eslint no-implicit-globals: ["error", {"lexicalBindings": false}]*/ @@ -171,7 +170,7 @@ class Bar {} Examples of **incorrect** code for this rule with `"lexicalBindings"` option set to `true`: -::: incorrect { "parserOptions": { "sourceType": "script" } } +::: incorrect { "sourceType": "script" } ```js /*eslint no-implicit-globals: ["error", {"lexicalBindings": true}]*/ @@ -187,7 +186,7 @@ class Bar {} Examples of **correct** code for this rule with `"lexicalBindings"` option set to `true`: -::: correct { "parserOptions": { "sourceType": "script" } } +::: correct { "sourceType": "script" } ```js /*eslint no-implicit-globals: ["error", {"lexicalBindings": true}]*/ @@ -198,11 +197,11 @@ Examples of **correct** code for this rule with `"lexicalBindings"` option set t class Bar {} } -(function() { +(function () { const foo = 1; let baz; class Bar {} -}()); +})(); ``` ::: @@ -210,47 +209,47 @@ Examples of **correct** code for this rule with `"lexicalBindings"` option set t If you intend to create a global `const` or `let` variable or a global `class` declaration, to be used from other scripts, be aware that there are certain differences when compared to the traditional methods, which are `var` declarations and assigning to a property of the global `window` object: -* Lexically declared variables cannot be conditionally created. A script cannot check for the existence of -a variable and then create a new one. `var` variables are also always created, but redeclarations do not -cause runtime exceptions. -* Lexically declared variables do not create properties on the global object, which is what a consuming script might expect. -* Lexically declared variables are shadowing properties of the global object, which might produce errors if a -consuming script is using both the variable and the property. -* Lexically declared variables can produce a permanent Temporal Dead Zone (TDZ) if the initialization throws an exception. -Even the `typeof` check is not safe from TDZ reference exceptions. +- Lexically declared variables cannot be conditionally created. A script cannot check for the existence of + a variable and then create a new one. `var` variables are also always created, but redeclarations do not + cause runtime exceptions. +- Lexically declared variables do not create properties on the global object, which is what a consuming script might expect. +- Lexically declared variables are shadowing properties of the global object, which might produce errors if a + consuming script is using both the variable and the property. +- Lexically declared variables can produce a permanent Temporal Dead Zone (TDZ) if the initialization throws an exception. + Even the `typeof` check is not safe from TDZ reference exceptions. Examples of **incorrect** code for this rule with `"lexicalBindings"` option set to `true`: -::: incorrect { "parserOptions": { "sourceType": "script" } } +::: incorrect { "sourceType": "script" } ```js /*eslint no-implicit-globals: ["error", {"lexicalBindings": true}]*/ -const MyGlobalFunction = (function() { +const MyGlobalFunction = (function () { const a = 1; let b = 2; - return function() { + return function () { return a + b; - } -}()); + }; +})(); ``` ::: Examples of **correct** code for this rule with `"lexicalBindings"` option set to `true`: -::: correct { "parserOptions": { "sourceType": "script" } } +::: correct { "sourceType": "script" } ```js /*eslint no-implicit-globals: ["error", {"lexicalBindings": true}]*/ -window.MyGlobalFunction = (function() { +window.MyGlobalFunction = (function () { const a = 1; let b = 2; - return function() { + return function () { return a + b; - } -}()); + }; +})(); ``` ::: @@ -261,7 +260,7 @@ You can use `/* exported variableName */` block comments in the same way as in [ Examples of **correct** code for `/* exported variableName */` operation: -::: correct { "parserOptions": { "sourceType": "script" } } +::: correct { "sourceType": "script" } ```js /* exported global_var */ diff --git a/docs/src/rules/no-restricted-imports.md b/docs/src/rules/no-restricted-imports.md index c3e10a62c39..d4a80260a5a 100644 --- a/docs/src/rules/no-restricted-imports.md +++ b/docs/src/rules/no-restricted-imports.md @@ -3,14 +3,13 @@ title: no-restricted-imports rule_type: suggestion --- - Imports are an ES6/ES2015 standard for making the functionality of other modules available in your current module. In CommonJS this is implemented through the `require()` call which makes this ESLint rule roughly equivalent to its CommonJS counterpart `no-restricted-modules`. Why would you want to restrict imports? -* Some imports might not make sense in a particular environment. For example, Node.js' `fs` module would not make sense in an environment that didn't have a file system. +- Some imports might not make sense in a particular environment. For example, Node.js' `fs` module would not make sense in an environment that didn't have a file system. -* Some modules provide similar or identical functionality, think `lodash` and `underscore`. Your project may have standardized on a module. You want to make sure that the other alternatives are not being used as this would unnecessarily bloat the project and provide a higher maintenance cost of two dependencies when one would suffice. +- Some modules provide similar or identical functionality, think `lodash` and `underscore`. Your project may have standardized on a module. You want to make sure that the other alternatives are not being used as this would unnecessarily bloat the project and provide a higher maintenance cost of two dependencies when one would suffice. ## Rule Details @@ -130,57 +129,57 @@ To restrict the use of all Node.js core imports (via Date: Fri, 7 Jul 2023 20:47:37 -0400 Subject: [PATCH 4/7] Use context-based prefix for playground URLs --- docs/.eleventy.js | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/.eleventy.js b/docs/.eleventy.js index a6c557ddf97..ac1c2586b0d 100644 --- a/docs/.eleventy.js +++ b/docs/.eleventy.js @@ -213,10 +213,13 @@ module.exports = function(eleventyConfig) { text: content }) ); + const prefix = process.env.CONTEXT && process.env.CONTEXT !== "deploy-preview" + ? "" + : "https://eslint.org"; return `
- + Open in Playground ↗️ `.trim(); From 2a08889a269d5de167f14e5c21482b4f95d3cc11 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Tue, 11 Jul 2023 21:13:38 -0400 Subject: [PATCH 5/7] Tweaked styles for more padding, and overlaid vertically in thin screens --- docs/src/assets/scss/docs.scss | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/src/assets/scss/docs.scss b/docs/src/assets/scss/docs.scss index 381a4c23320..7181ac3a487 100644 --- a/docs/src/assets/scss/docs.scss +++ b/docs/src/assets/scss/docs.scss @@ -142,11 +142,15 @@ pre[class*="language-"] { .c-btn.c-btn--playground { position: absolute; font-size: var(--step--1); - bottom: 0.5rem; - right: 0.5rem; + bottom: -1rem; + right: 1rem; offset-block-end: 0.5rem; offset-inline-end: 0.5rem; z-index: 1; + + @media all and (min-width: 768px) { + bottom: 1rem; + } } @media (hover: none) { From 91d2801c58ce168a7b93a37bbaa8ad4bd78023d6 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Wed, 12 Jul 2023 10:57:10 -0400 Subject: [PATCH 6/7] Reset md files to main --- docs/src/rules/no-implicit-globals.md | 71 +++++++++++++------------ docs/src/rules/no-restricted-imports.md | 35 ++++++------ 2 files changed, 54 insertions(+), 52 deletions(-) diff --git a/docs/src/rules/no-implicit-globals.md b/docs/src/rules/no-implicit-globals.md index 69b612ad4ee..6a479a0a765 100644 --- a/docs/src/rules/no-implicit-globals.md +++ b/docs/src/rules/no-implicit-globals.md @@ -2,15 +2,16 @@ title: no-implicit-globals rule_type: suggestion related_rules: - - no-undef - - no-global-assign - - no-unused-vars +- no-undef +- no-global-assign +- no-unused-vars further_reading: - - https://benalman.com/news/2010/11/immediately-invoked-function-expression/ - - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Undeclared_var - - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let#Temporal_dead_zone +- https://benalman.com/news/2010/11/immediately-invoked-function-expression/ +- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Undeclared_var +- https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/let#Temporal_dead_zone --- + It is the best practice to avoid 'polluting' the global scope with variables that are intended to be local to the script. Global variables created from a script can produce name collisions with global variables created from another script, which will @@ -18,9 +19,9 @@ usually lead to runtime errors or unexpected behavior. This rule disallows the following: -- Declarations that create one or more variables in the global scope. -- Global variable leaks. -- Redeclarations of read-only global variables and assignments to read-only global variables. +* Declarations that create one or more variables in the global scope. +* Global variable leaks. +* Redeclarations of read-only global variables and assignments to read-only global variables. There is an explicit way to create a global variable when needed, by assigning to a property of the global object. @@ -31,7 +32,7 @@ By default, this rule does not check `const`, `let` and `class` declarations. This rule has an object option with one option: -- Set `"lexicalBindings"` to `true` if you want this rule to check `const`, `let` and `class` declarations as well. +* Set `"lexicalBindings"` to `true` if you want this rule to check `const`, `let` and `class` declarations as well. ## Rule Details @@ -64,13 +65,13 @@ Examples of **correct** code for this rule: // explicitly set on window window.foo = 1; -window.bar = function () {}; +window.bar = function() {}; // intended to be scope to this file -(function () { - var foo = 1; +(function() { + var foo = 1; - function bar() {} + function bar() {} })(); ``` @@ -121,8 +122,8 @@ A read-only global variable can be a built-in ES global (e.g. `Array`), an envir (e.g. `window` in the browser environment), or a global variable defined as `readonly` in the configuration file or in a `/*global */` comment. -- [Specifying Environments](../use/configure#specifying-environments) -- [Specifying Globals](../use/configure#specifying-globals) +* [Specifying Environments](../use/configure#specifying-environments) +* [Specifying Globals](../use/configure#specifying-globals) Examples of **incorrect** code for this rule: @@ -148,7 +149,7 @@ Lexical declarations `const` and `let`, as well as `class` declarations, create However, when declared in the top-level of a browser script these variables are not 'script-scoped'. They are actually created in the global scope and could produce name collisions with `var`, `const` and `let` variables and `function` and `class` declarations from other scripts. -This does not apply to ES and CommonJS modules. +This does not apply to ES and CommonJS modules. If the variable is intended to be local to the script, wrap the code with a block or with an immediately-invoked function expression (IIFE). @@ -197,11 +198,11 @@ Examples of **correct** code for this rule with `"lexicalBindings"` option set t class Bar {} } -(function () { +(function() { const foo = 1; let baz; class Bar {} -})(); +}()); ``` ::: @@ -209,14 +210,14 @@ Examples of **correct** code for this rule with `"lexicalBindings"` option set t If you intend to create a global `const` or `let` variable or a global `class` declaration, to be used from other scripts, be aware that there are certain differences when compared to the traditional methods, which are `var` declarations and assigning to a property of the global `window` object: -- Lexically declared variables cannot be conditionally created. A script cannot check for the existence of - a variable and then create a new one. `var` variables are also always created, but redeclarations do not - cause runtime exceptions. -- Lexically declared variables do not create properties on the global object, which is what a consuming script might expect. -- Lexically declared variables are shadowing properties of the global object, which might produce errors if a - consuming script is using both the variable and the property. -- Lexically declared variables can produce a permanent Temporal Dead Zone (TDZ) if the initialization throws an exception. - Even the `typeof` check is not safe from TDZ reference exceptions. +* Lexically declared variables cannot be conditionally created. A script cannot check for the existence of +a variable and then create a new one. `var` variables are also always created, but redeclarations do not +cause runtime exceptions. +* Lexically declared variables do not create properties on the global object, which is what a consuming script might expect. +* Lexically declared variables are shadowing properties of the global object, which might produce errors if a +consuming script is using both the variable and the property. +* Lexically declared variables can produce a permanent Temporal Dead Zone (TDZ) if the initialization throws an exception. +Even the `typeof` check is not safe from TDZ reference exceptions. Examples of **incorrect** code for this rule with `"lexicalBindings"` option set to `true`: @@ -225,13 +226,13 @@ Examples of **incorrect** code for this rule with `"lexicalBindings"` option set ```js /*eslint no-implicit-globals: ["error", {"lexicalBindings": true}]*/ -const MyGlobalFunction = (function () { +const MyGlobalFunction = (function() { const a = 1; let b = 2; - return function () { + return function() { return a + b; - }; -})(); + } +}()); ``` ::: @@ -243,13 +244,13 @@ Examples of **correct** code for this rule with `"lexicalBindings"` option set t ```js /*eslint no-implicit-globals: ["error", {"lexicalBindings": true}]*/ -window.MyGlobalFunction = (function () { +window.MyGlobalFunction = (function() { const a = 1; let b = 2; - return function () { + return function() { return a + b; - }; -})(); + } +}()); ``` ::: diff --git a/docs/src/rules/no-restricted-imports.md b/docs/src/rules/no-restricted-imports.md index d4a80260a5a..9040170ed13 100644 --- a/docs/src/rules/no-restricted-imports.md +++ b/docs/src/rules/no-restricted-imports.md @@ -3,13 +3,14 @@ title: no-restricted-imports rule_type: suggestion --- + Imports are an ES6/ES2015 standard for making the functionality of other modules available in your current module. In CommonJS this is implemented through the `require()` call which makes this ESLint rule roughly equivalent to its CommonJS counterpart `no-restricted-modules`. Why would you want to restrict imports? -- Some imports might not make sense in a particular environment. For example, Node.js' `fs` module would not make sense in an environment that didn't have a file system. +* Some imports might not make sense in a particular environment. For example, Node.js' `fs` module would not make sense in an environment that didn't have a file system. -- Some modules provide similar or identical functionality, think `lodash` and `underscore`. Your project may have standardized on a module. You want to make sure that the other alternatives are not being used as this would unnecessarily bloat the project and provide a higher maintenance cost of two dependencies when one would suffice. +* Some modules provide similar or identical functionality, think `lodash` and `underscore`. Your project may have standardized on a module. You want to make sure that the other alternatives are not being used as this would unnecessarily bloat the project and provide a higher maintenance cost of two dependencies when one would suffice. ## Rule Details @@ -134,7 +135,7 @@ Examples of **incorrect** code for this rule: ```js /*eslint no-restricted-imports: ["error", "fs"]*/ -import fs from "fs"; +import fs from 'fs'; ``` ::: @@ -144,7 +145,7 @@ import fs from "fs"; ```js /*eslint no-restricted-imports: ["error", "fs"]*/ -export { fs } from "fs"; +export { fs } from 'fs'; ``` ::: @@ -154,7 +155,7 @@ export { fs } from "fs"; ```js /*eslint no-restricted-imports: ["error", "fs"]*/ -export * from "fs"; +export * from 'fs'; ``` ::: @@ -164,7 +165,7 @@ export * from "fs"; ```js /*eslint no-restricted-imports: ["error", { "paths": ["cluster"] }]*/ -import cluster from "cluster"; +import cluster from 'cluster'; ``` ::: @@ -174,7 +175,7 @@ import cluster from "cluster"; ```js /*eslint no-restricted-imports: ["error", { "patterns": ["lodash/*"] }]*/ -import pick from "lodash/pick"; +import pick from 'lodash/pick'; ``` ::: @@ -233,7 +234,7 @@ import * as Foo from "foo"; message: "Please use the default import from 'lodash' instead." }]}]*/ -import pick from "lodash/pick"; +import pick from 'lodash/pick'; ``` ::: @@ -246,7 +247,7 @@ import pick from "lodash/pick"; caseSensitive: true }]}]*/ -import pick from "fooBar"; +import pick from 'fooBar'; ``` ::: @@ -260,7 +261,7 @@ import pick from "fooBar"; message: "Use 'isEmpty' from lodash instead." }]}]*/ -import { isEmpty } from "utils/collection-utils"; +import { isEmpty } from 'utils/collection-utils'; ``` ::: @@ -272,7 +273,7 @@ Examples of **correct** code for this rule: ```js /*eslint no-restricted-imports: ["error", "fs"]*/ -import crypto from "crypto"; +import crypto from 'crypto'; export { foo } from "bar"; ``` @@ -283,8 +284,8 @@ export { foo } from "bar"; ```js /*eslint no-restricted-imports: ["error", { "paths": ["fs"], "patterns": ["eslint/*"] }]*/ -import crypto from "crypto"; -import eslint from "eslint"; +import crypto from 'crypto'; +import eslint from 'eslint'; export * from "path"; ``` @@ -295,7 +296,7 @@ export * from "path"; ```js /*eslint no-restricted-imports: ["error", { paths: [{ name: "foo", importNames: ["DisallowedObject"] }] }]*/ -import DisallowedObject from "foo"; +import DisallowedObject from "foo" ``` ::: @@ -322,7 +323,7 @@ import { AllowedObject as DisallowedObject } from "foo"; message: "Please use the default import from 'lodash' instead." }]}]*/ -import lodash from "lodash"; +import lodash from 'lodash'; ``` ::: @@ -335,7 +336,7 @@ import lodash from "lodash"; caseSensitive: true }]}]*/ -import pick from "food"; +import pick from 'food'; ``` ::: @@ -349,7 +350,7 @@ import pick from "food"; message: "Use 'isEmpty' from lodash instead." }]}]*/ -import { hasValues } from "utils/collection-utils"; +import { hasValues } from 'utils/collection-utils'; ``` ::: From 538ec30105b5222f3eb3fe3df1fa0f0ef8240022 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Wed, 12 Jul 2023 12:35:42 -0400 Subject: [PATCH 7/7] Removed icon and increased bottom padding --- docs/.eleventy.js | 2 +- docs/src/assets/scss/docs.scss | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/.eleventy.js b/docs/.eleventy.js index ac1c2586b0d..94a20211254 100644 --- a/docs/.eleventy.js +++ b/docs/.eleventy.js @@ -220,7 +220,7 @@ module.exports = function(eleventyConfig) { return `
- Open in Playground ↗️ + Open in Playground `.trim(); } diff --git a/docs/src/assets/scss/docs.scss b/docs/src/assets/scss/docs.scss index 7181ac3a487..98d6de83d45 100644 --- a/docs/src/assets/scss/docs.scss +++ b/docs/src/assets/scss/docs.scss @@ -149,7 +149,7 @@ pre[class*="language-"] { z-index: 1; @media all and (min-width: 768px) { - bottom: 1rem; + bottom: 1.5rem; } }