docs: improving contributing guidelines #47

.vscode/development.code-snippets

@@ -0,0 +1,99 @@
+{
+  // Develop / test your contributions here
+
+  // JavaScript only snippet (*.js)
+  "A JavaScript only snippet": {
+    "scope": "javascript",
+    "prefix": "myConsoleLog",
+    "body": [
+      "console.log(\"Hello Map\");"
+    ],
+    "description": "Console log \"Hello Map\""
+  },
+
+  // HTML only snippet (*.html and *.htm)
+  "A HTML only snippet": {
+    "scope": "html",
+    "prefix": "dojoConfig",
+    "body": [
+      "<script>",
+      "\tconst locationPath = location.pathname.replace(/\\/[^\\/]+$/,\"\");",
+      "\twindow.dojoConfig = {",
+      "\tpackages:[",
+      "\t\t{",
+      "\t\tname:\"app\",",
+      "\t\tlocation: locationPath + \"/app\"",
+      "\t\t}",
+      "\t]",
+      "\t}",
+      "</script>"
+    ],
+    "description": "Loads dojoConfig"
+  },
+
+  // CSS only snippet (*.css)
+  "A CSS only snippet": {
+    "scope": "css",
+    "prefix": "smallMap",
+    "body": [
+      ".viewDiv{ width: 300px; height: 300px }"
+    ],
+    "description": "Set viewDiv to 300px x 300px"
+  },
+
+  // JSON only snippet (*.json and *.geojson)
+  "A JSON only snippet": {
+    "scope": "json",
+    "prefix": "featureCollectionPoint",
+    "body": [
+      "{",
+      "\t\"type\": \"FeatureCollection\",",
+      "\t\"features\": [",
+      "\t\t{",
+      "\t\t\t\"type\": \"Feature\",",
+      "\t\t\t\"properties\": {},",
+      "\t\t\t\"geometry\": {",
+      "\t\t\t\t\"coordinates\": [",
+      "\t\t\t\t\t-4.795935418929616,",
+      "\t\t\t\t\t38.74031154905251",
+      "\t\t\t\t],",
+      "\t\t\t\t\"type\": \"Point\"",
+      "\t\t\t}",
+      "\t\t}",
+      "\t]",
+      "}",
+    ],
+    "description": "Sample of camera position object"
+  },
+
+  // TypeScript (*.ts)
+  "A TypeScript only snippet": {
+    "scope": "typescript",
+    "body": [
+      "declare function myDebug(value: any): void;"
+    ],
+    "description": "Example using any and void",
+    "prefix": "myDebug"
+  },
+
+  // TypeScript React (*.tsx)
+  "A TypeScript only snippet": {
+    "scope": "typescriptreact",
+    "body": [
+      "const HelloWorld = () => <h1>Hello, World!</h1>",
+	    "export default HelloWorld",
+    ],
+    "description": "Hello world usint TypeScript and React",
+    "prefix": "helloWorldTSX"
+  },
+
+  // SCSS only snippet (*.scss)
+  "A SCSS snippet": {
+    "scope": "scss",
+    "prefix": "smallMap",
+    "body": [
+      ".viewDiv{ width: 400px; height: 400px }"
+    ],
+    "description": "Set viewDiv to 400px x 400px"
+  },
+}

README.md

@@ -31,20 +31,23 @@ Visual Studio Code extension that contains a collection of snippets for common c
 To use this extension you will need to install:
 1. [Visual Studio Code](https://code.visualstudio.com/download) (version 1.35 or higher).
 2. The extension. There are two possibilities:
-    - From the [Visual Studio Code marketplace](https://marketplace.visualstudio.com/items?itemName=Esri.arcgis-jsapi-snippets).
+    - From the [Visual Studio Code marketplace](https://marketplace.visualstudio.com/items?itemName=Esri.arcgis-maps-sdk-js-snippets).
     - Using the ***[Install from VSIX](https://code.visualstudio.com/docs/editor/extension-marketplace#_install-from-a-vsix)*** command in Visual Studio Code then import the [arcgis-jsapi-snippets-1.0.0.vsix](./arcgis-jsapi-snippets-1.0.0.vsix) file.
 
 ### Usage
 
 After installing, there are two ways to use it:
 
 **Option 1**) Using [built-in VS Code Intellisense](https://code.visualstudio.com/docs/languages/javascript#_intellisense):
-1. Start typing the prefix for the code snippet.
-2. Select the snippet by pressing `Tab` or `Enter` key.
+1. Create an empty project with an empty `index.js` file.
+2. Start typing one the prefix of one the [available code snippets](#snippets-available). (e.g. `elev`).
+3. Select the snippet by pressing `Tab` or `Enter` key.
+4. If there are values highlighted in gray, you can move between them using `Tab` (forward) and `Shift+Tab` (backwards).
 
 <img src="./images/code-snippets.gif" width="400px" alt="Intelissense demo"/>
 
-> **Notes:**
+> **Troubleshooting:**<br>
+> If the Intellisense doesn't work:
 > - Make sure to have `"editor.tabCompletion": "on"` in the settings (`Preferences` > `Open Settings(JSON)`)
 > - If pressing Tab doesn't work then you might have several snippets with the same prefix. Press `Ctrl-Space` (`Cmd-Space` on mac) to select the one you need.
 >
@@ -58,12 +61,6 @@ This extension adds a new option to the activity bar that lets you quickly brows
 
 <img src="./images/snippets-viewer.gif" width="700px" alt="Intelissense demo"/>
 
-### Configuration
-
-If you want to create you own custom snippets you can do so. Read [about User defined snippets in Visual Studio official documentation](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_create-your-own-snippets).
-
-If you do so, please consider [contributing to this repository](#contributing) or join [other developers sharing their snippets](#community-snippets).
-
 ## Snippets available
 
 ### [HTML snippets](snippets/html.json)
@@ -172,14 +169,18 @@ If you do so, please consider [contributing to this repository](#contributing) o
 
 ## Issues
 
-If something isn't working the way you expected, please take a look at [previously logged issues](https://github.com/Esri/arcgis-js-vscode-snippets/issues/) first. Have you found a new bug? Want to request a new feature? [Open a new issue](https://github.com/Esri/arcgis-js-vscode-snippets/issues/), we'd love to hear from you.
-
-If you're looking for help you can also post issues on Stack Overflow with the "[**esri-oss**](https://stackoverflow.com/questions/tagged/esri-oss)" tag.
+If something isn't working the way you expected, please take a look at [previously logged issues](https://github.com/Esri/arcgis-js-vscode-snippets/issues/) first. Have you found a new bug? Want to request an enhancement to an existing snippet? Suggest a new snippet or tool? [Open a new issue](https://github.com/Esri/arcgis-js-vscode-snippets/issues/new/choose), we'd love to hear from you.
 
 ## Contributing
 
 Esri welcomes contributions from anyone and everyone. Please see our [guidelines for contributing](./CONTRIBUTING.md).
 
+### Additional resources
+
+To learn more about **general use of code snippets in Visual Studio Code** read [Visual Studio official documentation](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_create-your-own-snippets).
+
+If you create your own custom code snippets to work with the ArcGIS Maps SDK for JavaScript, please consider [contributing to this repository](#contributing) or join [other developers sharing their snippets](#community-snippets).
+
 ## License
 
 Copyright 2023 Esri

builder/index.html

@@ -40,7 +40,7 @@ <h2>Custom Snippet</h2>
         </p>
         <calcite-label layout="default">
           <span
-            >Prefix *
+            >Prefix<sup>*</sup>
             <calcite-popover-manager>
               <calcite-popover
                 label="Popover label"
@@ -51,14 +51,14 @@ <h2>Custom Snippet</h2>
                     <b>Prefix</b><br />
                     <img src="assets/snippet-prefix.png" class="screenshot" /><br/>
                     Defines one or more <b>trigger words</b> that display the
-                    snippet in IntelliSense. Substring matching is performed on
-                    prefixes, so in this case, "fc" could match "for-const".
+                    snippet in IntelliSense. Approximate string matching (fuzzy search) is performed on
+                    prefixes, so in this case, "fl" could match "FeatureLayer".
                   </p>
                   <p>
-                    <b>Recomendations</b><br />
+                    <b>Recommendations</b><br />
                     Good prefixes are short and easy to remember, so you can
                     include the name of the method, class or property. Avoid
-                    using just acronyms.
+                    using just acronyms. E.g. MapView, basemapsWithAPIKeys, findLayerByTitle, popupTemplateProps. 
                   </p>
                 </div>
               </calcite-popover>
@@ -74,7 +74,7 @@ <h2>Custom Snippet</h2>
         </calcite-label>
         <calcite-label layout="default">
           <span>
-            Name *
+            Name<sup>*</sup>
             <calcite-popover-manager>
               <calcite-popover
                 label="Popover label"
@@ -87,9 +87,8 @@ <h2>Custom Snippet</h2>
                     Short description that follows the prefix.
                   </p>
                   <p>
-                    <b>Recomendations</b><br />
-                    To differentiate from other IntelliSense we recommend you to
-                    include (Esri JSAPI)
+                    <b>Recommendations</b><br />
+                    Use plain English, using spaces as needed (length &lt;35 characters). E.g. "Find layer in a MapView by title"
                   </p>
                 </div>
               </calcite-popover>
@@ -118,8 +117,8 @@ <h2>Custom Snippet</h2>
                   IntelliSense.
                 </p>
                 <p>
-                  <b>Recomendations</b><br />
-                  Explain of what the snippet does, but keep it short.
+                  <b>Recommendations</b><br />
+                  Explain of what the snippet does. Reuse text from the API reference whenever possible. Add AMD and ESM paths if it is a class initialization (new ...)
                 </p>
               </div>
             </calcite-popover>
@@ -131,11 +130,11 @@ <h2>Custom Snippet</h2>
             ></calcite-icon>
           </calcite-popover-manager>
           </span>
-          <calcite-input required id="desc"></calcite-input>
+          <calcite-input required type="textarea" id="desc"></calcite-input>
         </calcite-label>
         <calcite-label layout="default">
           <span>
-            Body *
+            Body<sup>*</sup> (<a href="https://prettier.io/playground/#N4Igxg9gdgLgprEAuEIA0IIAcYEtoDOyoAhgE5kQDuACuQkSiQDZUkCeRGARmSWAGs4MAMokAtnAAyuKHGQAzFgTg8+g4SKz9ZAc2QwyAV1UgV43AeOmCe5nACKRiPEXLTAKwIAPEXcfOrkhKzCoYAI6BcDSUWIzghLgE8IgYhiS4zHoAwhDi4iTIIFDQ8hi2ULr2AIIwhrjcRvA0cGQycm6hpgAWMOLMAOrduPAE2mBwIgwjuABuI+xFYARcILMmAJJQACYIomBkuDjVOyIw7PadYSBYlCoDfFhFt3AqZLNlILJvMDEkugUrqZtGQ3kVuCRuHBmOgbodYANcNsYN1kABGABMAAYMGQ4JFcHi-gDCsF3GlIYjkaikBiMEYVAAVSGMELXODiKHbXbbKQkSpGf5wABiEDIBTqeiKJCaEBAAF95UA" target="_blank">Prettier playground</a>)
             <calcite-popover-manager>
               <calcite-popover
                 label="Popover label"
@@ -150,7 +149,7 @@ <h2>Custom Snippet</h2>
                     which the snippet is inserted.
                   </p>
                   <p>
-                    <b>Recomendations</b><br />
+                    <b>Recommendations</b><br />
                     Use "Placeholders" (${1:foo}) and "Choices" (${1|value1,value2}) when possible.
                   </p>
                 </div>

dev/README.md

@@ -0,0 +1,111 @@
+# Development environment
+
+To contribute without messing around with other snippets you might use in other projects, this repo provides a project-folder scoped file (`development.code-snippets`) and several playgrounds to help you test the snippets you are going to contribute.
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**: 
+
+- [Getting started](#getting-started)
+  - [Add a new snippet](#add-a-new-snippet)
+  - [Enhance an existing snippet](#enhance-an-existing-snippet)
+  - [Test a snippet](#test-a-snippet)
+- [Troubleshooting](#troubleshooting)
+- [FAQ](#faq)
+  - [How do I add placeholders to my snippet?](#how-do-i-add-placeholders-to-my-snippet)
+  - [How do I add a dropdown/choices in my snippet?](#how-do-i-add-a-dropdownchoices-in-my-snippet)
+  - [Are there other alternatives to use the `development.code-snippets` file?](#are-there-other-alternatives-to-use-the-developmentcode-snippets-file)
+  - [Are there other alternatives to use the Snippet Builder to generate JSON code?](#are-there-other-alternatives-to-use-the-snippet-builder-to-generate-json-code)
+- [Additional resources](#additional-resources)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Getting started
+
+First of all, **fork and clone locally** this repository.
+
+### Add a new snippet
+
+* 1\) Within this folder ([dev](./dev)), build a sample app make sure you have tested the code snippet you want to contribute (e.g. [sample-app.html](./sample-app.html)).
+* 2\) Generate the [custom snippet code](#what-is-a-custom-snippet-code) using the [VS Code Snippets Builder](https://esri.github.io/arcgis-js-vscode-snippets/builder/).
+* 3\) Paste your VS Code Snippets JSON syntax into [../.vscode/development.code-snippets](../.vscode/development.code-snippets).
+* 4\) [Test the snippet](#test-a-snippet)
+
+
+### Enhance an existing snippet
+
+To be able to test your modifications, we encourage you to follow these steps, even if you are doing a simple change to the `prefix`, `name`, or `description`. 
+
+* 1\) Open the file (from the [snippets folder](../snippets/)) that contains the [custom snippet code](#what-is-a-custom-snippet-code) you are going to enhance, **find it and copy it**.
+* 2\) Paste the snippet into [../.vscode/development.code-snippets](../.vscode/development.code-snippets).
+* 3\) Do the modifications there. Use the [snippets builder](https://esri.github.io/arcgis-js-vscode-snippets/builder/), and add [placeholders](#are-there-other-alternatives-to-use-the-developmentcode-snippets-file), [choices](#how-do-i-add-a-dropdownchoices-in-my-snippet), ... as needed.
+* 4\) [Test the snippet](#test-a-snippet)
+
+### Test a snippet
+
+* 1\) Open in VS Code a file and start typing your snippet prefix. You can use any of the provided files within the folder [playgrounds](./playgrounds/) to test it. Choose the right one based on the type of snippets you want to contribute:
+  * **index.html** for HTML, CSS and JavaScript snippets.
+  * **config.json** or **data.geojson** for JSON snippets.
+  * **main.scss** for SCSS snippets.
+  * **index.ts** for TypeScript snippets.
+  * **index.tsx** for TypeScript React snippets.
+* 2\) If everything works as expected, follow the [steps to add your changes](https://github.com/Esri/arcgis-js-vscode-snippets/blob/master/CONTRIBUTING.md#add-your-changes).
+
+
+## Troubleshooting
+
+If your code snippet doesn't show up:
+* Make sure the developmnet.code-snippets is still a valid JSON. You can test it with [JSONLint](http://jsonlint.com/) (but **remember to remove comments**).
+* Use the command palette (Mac: `Cmd + Shift + P` | Windows/Linux: `Ctrl + Shift + P`) and type Developer: `Reload Window`.
+
+## FAQ
+
+### How do I add placeholders to my snippet?
+
+You have to use the syntax `${1:default_value}`. Example:
+
+```json
+{
+  "Load a new MapView (2D)": {
+    "prefix": "mapView",
+    "body": [
+      "new MapView({",
+      "\tcontainer: \"${1:viewDiv}\",",
+      "\tmap: ${2:map},",
+      "});"
+    ]
+  },
+}
+```
+Learn [more about placeholders](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_placeholders).
+
+### How do I add a dropdown/choices in my snippet?
+
+You have to use the syntax `${1|one,two,three|}`. Example:
+
+```json
+  "Get the API from the CDN": {
+    "prefix": "getApi",
+    "body": [
+      "<link rel=\"stylesheet\" href=\"https://js.arcgis.com/${1|4.20,4.19,4.18,4.17,4.16,1.15,4.14|}/esri/css/main.css\">",
+      "<script src=\"https://js.arcgis.com/${2|4.20,4.19,4.18,4.17,4.16,4.15,4.14|}\"></script>"
+    ],
+  },
+```
+
+Learn [more about choices](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_choice).
+
+### Are there other alternatives to use the `development.code-snippets` file?
+1. In VSCode show command palette pressing: `Cmd + Shift + P` (Windows: `Ctrl + Shift + P`) then type/select `Preferences: Configure User Snippets`.
+2. Select your preferred option, `New Global Snippets file...` or the folder you want to place the snippets file.
+
+### Are there other alternatives to use the Snippet Builder to generate JSON code?
+Yes, you can use any another extension, for example, the [Snippet Generator](https://marketplace.visualstudio.com/items?itemName=wenfangdu.snippet-generator).
+
+## Additional resources
+
+Learn more about:
+* [VS Code Snippets JSON syntax](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_snippet-syntax)
+* [Snippets scope (language and project scopes)](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_snippet-scope)
+
+

dev/playgrounds/config.json

@@ -0,0 +1,2 @@
+// Test your JSON snippets here (e.g. featureCollectionPoint)
+// Note: Remove this comments afterwards (JSON do not support comments)

dev/playgrounds/data.geojson

@@ -0,0 +1,2 @@
+// Test your JSON snippets here (e.g. featureCollectionPoint)
+// Note: Remove this comments afterwards (GeoJSON do not support comments)

dev/playgrounds/index.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Development environment</title>
+    <style>
+      /* Test your CSS snippets here (e.g. smallMap) */
+    </style>
+  </head>
+  <body>
+    <script>
+      // Test your JavaScript snippets here (e.g. myConsoleLog)
+    </script>
+
+    <!-- Test your HTML snippets here (e.g. dojoConfig) -->
+  </body>
+</html>

dev/playgrounds/index.ts

@@ -0,0 +1 @@
+// Test your TypeScript here (e.g. myDebug)

dev/playgrounds/index.tsx

@@ -0,0 +1 @@
+// Test your TypeScript React here (e.g. helloWorldTSX)

dev/playgrounds/main.scss

@@ -0,0 +1 @@
+// Test your JavaScript snippets here (e.g. smallMap)