Add README plugin and generate README

Co-authored-by: Keith Cirkel <[email protected]>

Author: koddsson

README.md

@@ -1,28 +1,16 @@
 # <details-dialog> element
 
-A modal dialog that's opened with a <details> button.
+A modal dialog opened with a <details> button.
 
 ## Installation
-
-```
-$ npm install --save @github/details-dialog-element
-```
+  Available on [npm](https://www.npmjs.com/) as [**@github/details-dialog-element**](https://www.npmjs.com/package/@github/details-dialog-element).
+    ```
+  $ npm install --save @github/details-dialog-element
+  ```
 
 ## Usage
 
-### Script
-
-Import as ES modules:
-
-```js
-import '@github/details-dialog-element'
-```
-
-Include with a script tag:
-
-```html
-<script type="module" src="./node_modules/@github/details-dialog-element/dist/index.js">
-```
+### details-dialog
 
 ### Markup
 
@@ -74,26 +62,11 @@ document.addEventListener('details-dialog-close', function(event) {
 })
 ```
 
-## Browser support
-
-Browsers without native [custom element support][support] require a [polyfill][].
-
-- Chrome
-- Firefox
-- Safari
-- Microsoft Edge
-
-## Development
-
-```
-npm install
-npm test
-```
-
-## License
-
-Distributed under the MIT license. See LICENSE for details.
-
-[fragment]: https://github.com/github/include-fragment-element/
-[support]: https://caniuse.com/#feat=custom-elementsv1
-[polyfill]: https://github.com/webcomponents/custom-elements
+## Browser Support
+  Browsers without native [custom element support][support] require a [polyfill][].
+    - Chrome
+    - Firefox
+    - Safari
+    - Microsoft Edge
+  [support]: https://caniuse.com/custom-elementsv1
+  [polyfill]: https://github.com/webcomponents/custom-elements

cem-plugin-readme.js

@@ -0,0 +1,63 @@
+import {accessSync, readFileSync, writeFileSync} from 'fs'
+
+function generateInstallationInstructions({packageJson: {name}}) {
+  return `## Installation
+  Available on [npm](https://www.npmjs.com/) as [**${name}**](https://www.npmjs.com/package/${name}).
+    \`\`\`
+  $ npm install --save ${name}
+  \`\`\``
+}
+
+function generateBrowserSupportInstructions() {
+  return `## Browser Support
+  Browsers without native [custom element support][support] require a [polyfill][].
+    - Chrome
+    - Firefox
+    - Safari
+    - Microsoft Edge
+  [support]: https://caniuse.com/custom-elementsv1
+  [polyfill]: https://github.com/webcomponents/custom-elements`
+}
+
+function generateTitle({packageJson: {name}}) {
+  const formattedName = name
+    .split('/')
+    .at(-1)
+    .replace(/-element$/, '')
+  return `<${formattedName}> element`
+}
+
+function generateDescription({packageJson: {description}}) {
+  return description
+}
+
+export function readme(options) {
+  const {filename = 'README.md', exclude = [], title, preamble, footer} = options ?? {}
+
+  const packageJson = JSON.parse(readFileSync('./package.json', 'utf8'))
+
+  return {
+    name: 'readme',
+    async packageLinkPhase({customElementsManifest}) {
+      const content = [
+        `# ${title || generateTitle({packageJson})}`,
+        generateDescription({packageJson}),
+        preamble,
+        generateInstallationInstructions({packageJson}),
+        `## Usage`
+      ]
+      for (const module of customElementsManifest.modules) {
+        for (const {name, tagName, description} of module.declarations.filter(x => x.customElement)) {
+          if (exclude.includes(name)) continue
+          content.push(`### ${tagName}`)
+          content.push(description.trim())
+        }
+      }
+
+      content.push(generateBrowserSupportInstructions())
+      content.push(footer)
+
+      writeFileSync(filename, content.filter(Boolean).join('\n\n'))
+    }
+  }
+}

custom-elements-manifest.config.js

@@ -1,9 +1,11 @@
 import {generateCustomData} from 'cem-plugin-vs-code-custom-data-generator'
+import {readme} from './cem-plugin-readme.js'
 
 export default {
   packagejson: true,
   globs: ['src/index.ts'],
   plugins: [
+    readme(),
     generateCustomData()
   ]
 }

custom-elements.json

@@ -8,7 +8,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "",
+          "description": "### Markup\n\n```html\n<details>\n  <summary>Open dialog</summary>\n  <details-dialog>\n    Modal content\n    <button type=\"button\" data-close-dialog>Close</button>\n  </details-dialog>\n</details>\n```\n\n## Deferred loading\n\nDialog content can be loaded from a server by embedding an [`<include-fragment>`][fragment] element.\n\n```html\n<details>\n  <summary>Robots</summary>\n  <details-dialog src=\"/robots\" preload>\n    <include-fragment>Loading…</include-fragment>\n  </details-dialog>\n</details>\n```\n\nThe `src` attribute value is copied to the `<include-fragment>` the first time the `<details>` button is toggled open, which starts the server fetch.\n\nIf the `preload` attribute is present, hovering over the `<details>` element will trigger the server fetch.\n\n## Events\n\n### `details-dialog-close`\n\n`details-dialog-close` event is fired from `<details-dialog>` when a request to close the dialog is made from\n\n- pressing <kbd>escape</kbd>,\n- submitting a `form[method=\"dialog\"]`\n- clicking on `summary, form button[formmethod=\"dialog\"], [data-close-dialog]`, or\n- `dialog.toggle(false)`\n\nThis event bubbles, and can be canceled to keep the dialog open.\n\n```js\ndocument.addEventListener('details-dialog-close', function(event) {\n  if (!confirm('Are you sure?')) {\n    event.preventDefault()\n  }\n})\n```",
           "name": "DetailsDialogElement",
           "members": [
             {

src/index.ts

@@ -181,6 +181,57 @@ type State = {
 
 const initialized: WeakMap<Element, State> = new WeakMap()
 
+/**
+  * ### Markup
+  * 
+  * ```html
+  * <details>
+  *   <summary>Open dialog</summary>
+  *   <details-dialog>
+  *     Modal content
+  *     <button type="button" data-close-dialog>Close</button>
+  *   </details-dialog>
+  * </details>
+  * ```
+  * 
+  * ## Deferred loading
+  * 
+  * Dialog content can be loaded from a server by embedding an [`<include-fragment>`][fragment] element.
+  * 
+  * ```html
+  * <details>
+  *   <summary>Robots</summary>
+  *   <details-dialog src="/robots" preload>
+  *     <include-fragment>Loading…</include-fragment>
+  *   </details-dialog>
+  * </details>
+  * ```
+  *
+  * The `src` attribute value is copied to the `<include-fragment>` the first time the `<details>` button is toggled open, which starts the server fetch.
+  * 
+  * If the `preload` attribute is present, hovering over the `<details>` element will trigger the server fetch.
+  * 
+  * ## Events
+  * 
+  * ### `details-dialog-close`
+  * 
+  * `details-dialog-close` event is fired from `<details-dialog>` when a request to close the dialog is made from
+  * 
+  * - pressing <kbd>escape</kbd>,
+  * - submitting a `form[method="dialog"]`
+  * - clicking on `summary, form button[formmethod="dialog"], [data-close-dialog]`, or
+  * - `dialog.toggle(false)`
+  * 
+  * This event bubbles, and can be canceled to keep the dialog open.
+  * 
+  * ```js
+  * document.addEventListener('details-dialog-close', function(event) {
+  *   if (!confirm('Are you sure?')) {
+  *     event.preventDefault()
+  *   }
+  * })
+  * ```
+  **/
 class DetailsDialogElement extends HTMLElement {
   static get CLOSE_ATTR() {
     return CLOSE_ATTR

vscode.html-custom-data.json

@@ -2,7 +2,7 @@
   "tags": [
     {
       "name": "details-dialog",
-      "description": "",
+      "description": "### Markup\n\n```html\n<details>\n  <summary>Open dialog</summary>\n  <details-dialog>\n    Modal content\n    <button type=\"button\" data-close-dialog>Close</button>\n  </details-dialog>\n</details>\n```\n\n## Deferred loading\n\nDialog content can be loaded from a server by embedding an [`<include-fragment>`][fragment] element.\n\n```html\n<details>\n  <summary>Robots</summary>\n  <details-dialog src=\"/robots\" preload>\n    <include-fragment>Loading…</include-fragment>\n  </details-dialog>\n</details>\n```\n\nThe `src` attribute value is copied to the `<include-fragment>` the first time the `<details>` button is toggled open, which starts the server fetch.\n\nIf the `preload` attribute is present, hovering over the `<details>` element will trigger the server fetch.\n\n## Events\n\n### `details-dialog-close`\n\n`details-dialog-close` event is fired from `<details-dialog>` when a request to close the dialog is made from\n\n- pressing <kbd>escape</kbd>,\n- submitting a `form[method=\"dialog\"]`\n- clicking on `summary, form button[formmethod=\"dialog\"], [data-close-dialog]`, or\n- `dialog.toggle(false)`\n\nThis event bubbles, and can be canceled to keep the dialog open.\n\n```js\ndocument.addEventListener('details-dialog-close', function(event) {\n  if (!confirm('Are you sure?')) {\n    event.preventDefault()\n  }\n})\n```",
       "attributes": [{ "name": "src" }, { "name": "preload" }]
     }
   ]