🆕 update README with docs, add examples (#2)

README.hbs

@@ -0,0 +1,80 @@
+# jsonresume-component
+
+`<json-resume>` is a web component (using LitElement) which presents resume content stored in [JSON Resume][jsonresume] format. The HTML structure uses the components from [jsonresume-theme-microdata][jtm] to generate HTML which includes structured data as microdata in HTML attributes.
+
+
+## NPM / Node.js usage
+
+### Install dependencies
+
+```sh
+npm i jsonresume-component
+```
+
+```javascript
+import { JsonResume } from 'jsonresume-component/src/index.js';
+```
+
+```html
+<JsonResume gist_id="9e7a7ceb9425336c6aa08d58afb63b8d"></JsonResume>
+```
+
+## Browser usage
+
+The web component is lightly-bundled in that it puts all non-`lit` external files in a single .js file, which is located at `./dist/json-resume.js` in the NPM package.
+
+### include `lit` dependencies
+
+`<json-resume>` uses [`lit`](https://lit.dev) and [`@lit/task`](https://lit.dev/docs/data/task/) which must be imported into your HTML file. You can include dependencies with an [importmap](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) like this:
+
+```html
+<script type="importmap">
+  {
+    "imports": {
+      "lit": "https://esm.run/lit",
+      "@lit/task": "https://esm.run/@lit/task"
+    }
+  }
+</script>
+```
+
+### Add jsonresume-component
+
+`unpkg` points directly to the lightly-bundled web component file, which does not include `lit`.
+
+```html
+<script type="module">
+  import 'https://unpkg.com/jsonresume-component'
+</script>
+```
+
+### Use the web component by giving it your `gist` ID
+
+```html
+<json-resume gist_id="54682f0aa17453d46cdc74bdef3172a3"></json-resume>
+```
+
+### The web component accepts a `resume.json` url
+
+```html
+<json-resume json_url="https://gist.githubusercontent.com/scottnath/54682f0aa17453d46cdc74bdef3172a3/raw/resume.json"></json-resume>
+```
+
+## Options 
+
+### A modified JSON Resume schema
+
+The JSON structure follows an extension of the [JSON Resume][jsonresume] schema with added schema structure for microdata `itemtype` on some content types, `basics.pronouns`, and `meta.themeOptions` which allows changing the content of the resume section titles, colors, and other theme opts. See the [jsonresume-theme-microdata][jtm] README for details on this adjusted structure.
+
+
+{{>main}}
+
+
+[microdata-html]: /blahg/microdata-with-html/
+[microdata-jsonresume]: /blahg/microdata-with-jsonresume/
+[jsonresume]: https://jsonresume.org
+[jsonresume-schema]: https://github.com/jsonresume/resume-schema/blob/master/schema.json
+[jsonresume-project]: https://jsonresume.org/projects/
+[jtm]: https://github.com/scottnath/jsonresume-theme-microdata
+[jtm-example]: https://github.com/scottnath/jsonresume-theme-microdata/TBD___
+[jte]: https://github.com/rbardini/jsonresume-theme-even

README.md

@@ -21,6 +21,8 @@ import { JsonResume } from 'jsonresume-component/src/index.js';
 
 ## Browser usage
 
+The web component is lightly-bundled in that it puts all non-`lit` external files in a single .js file, which is located at `./dist/json-resume.js` in the NPM package.
+
 ### include `lit` dependencies
 
 `<json-resume>` uses [`lit`](https://lit.dev) and [`@lit/task`](https://lit.dev/docs/data/task/) which must be imported into your HTML file. You can include dependencies with an [importmap](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) like this:
@@ -38,23 +40,102 @@ import { JsonResume } from 'jsonresume-component/src/index.js';
 
 ### Add jsonresume-component
 
+`unpkg` points directly to the lightly-bundled web component file, which does not include `lit`.
+
 ```html
 <script type="module">
-  import 'https://esm.run/jsonresume-component'
+  import 'https://unpkg.com/jsonresume-component'
 </script>
 ```
 
 ### Use the web component by giving it your `gist` ID
 
 ```html
-<json-resume gist_id="9e7a7ceb9425336c6aa08d58afb63b8d"></json-resume>
+<json-resume gist_id="54682f0aa17453d46cdc74bdef3172a3"></json-resume>
+```
+
+### The web component accepts a `resume.json` url
+
+```html
+<json-resume json_url="https://gist.githubusercontent.com/scottnath/54682f0aa17453d46cdc74bdef3172a3/raw/resume.json"></json-resume>
 ```
 
-## A modified JSON Resume schema
+## Options 
+
+### A modified JSON Resume schema
 
 The JSON structure follows an extension of the [JSON Resume][jsonresume] schema with added schema structure for microdata `itemtype` on some content types, `basics.pronouns`, and `meta.themeOptions` which allows changing the content of the resume section titles, colors, and other theme opts. See the [jsonresume-theme-microdata][jtm] README for details on this adjusted structure.
 
 
+## class: `JsonResume`, `json-resume`
+
+### Fields
+
+| Name              | Privacy | Type      | Default | Description                                                                                                                                                                                                    | Inherited From |
+| ----------------- | ------- | --------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| `gist_id`         | public  | `string`  |         | GitHub gist ID. When present, calls the GitHub rest API to fetch a resume.json gist's content.&#xA;Checked first, if gist is present and has a resume.json, \`json\_url\` and \`local\_file\` will be ignored. |                |
+| `json_url`        | public  | `string`  |         | URL to a JSON file. When present, used to fetch a resume.json file from the URL.&#xA;Checked second or if gist\_id does not have a resume.json, \`local\_file\` will be ignored.                               |                |
+| `preordered`      | public  | `boolean` |         | When true, sections of resume (basic, work, etc) will be injected according to their order in resume.json                                                                                                      |                |
+| `label`           | public  | `string`  |         | The aria-label for the \`div\` containing the resume. Defaults to \`${basics.name}'s resume\`                                                                                                                  |                |
+| `globalizeStyles` | public  | `boolean` |         | When styles are generated internally, repeat them onto the global document (page)&#xA;\*\*WARNING\*\* Completely deletes and overrides page styles                                                             |                |
+| `resumejson`      | public  | `object`  |         | Property accepts a JSON Resume object                                                                                                                                                                          |                |
+| `stylesheet`      | public  | `string`  |         | Accepts a string containing styles&#xA;\*\*WARNING\*\* Completely deletes and overrides internal component styles                                                                                              |                |
+
+### CSS Properties
+
+| Name                  | Default | Description           |
+| --------------------- | ------- | --------------------- |
+| `--card-border-color` | `#ccc`  | The card border color |
+| `--card-border-size`  | `1px`   | The card border color |
+| `--card-border-style` | `solid` | The card border color |
+
+### CSS Parts
+
+| Name           | Description                        |
+| -------------- | ---------------------------------- |
+| `basics`       | style the \`basics\` section       |
+| `work`         | style the \`work\` section         |
+| `volunteer`    | style the \`volunteer\` section    |
+| `education`    | style the \`education\` section    |
+| `awards`       | style the \`awards\` section       |
+| `certificates` | style the \`certificates\` section |
+| `publications` | style the \`publications\` section |
+| `skills`       | style the \`skills\` section       |
+| `languages`    | style the \`languages\` section    |
+| `interests`    | style the \`interests\` section    |
+| `references`   | style the \`references\` section   |
+| `projects`     | style the \`projects\` section     |
+| `meta`         | style the \`meta\` section         |
+
+### Slots
+
+| Name           | Description                                      |
+| -------------- | ------------------------------------------------ |
+| `basics`       | Replace the entire \`basics\` HTML section       |
+| `work`         | Replace the entire \`work\` HTML section         |
+| `volunteer`    | Replace the entire \`volunteer\` HTML section    |
+| `education`    | Replace the entire \`education\` HTML section    |
+| `awards`       | Replace the entire \`awards\` HTML section       |
+| `certificates` | Replace the entire \`certificates\` HTML section |
+| `publications` | Replace the entire \`publications\` HTML section |
+| `skills`       | Replace the entire \`skills\` HTML section       |
+| `languages`    | Replace the entire \`languages\` HTML section    |
+| `interests`    | Replace the entire \`interests\` HTML section    |
+| `references`   | Replace the entire \`references\` HTML section   |
+| `projects`     | Replace the entire \`projects\` HTML section     |
+| `meta`         | Replace the entire \`meta\` HTML section         |
+
+<hr/>
+
+## Exports
+
+| Kind                        | Name          | Declaration | Module       | Package |
+| --------------------------- | ------------- | ----------- | ------------ | ------- |
+| `js`                        | `JsonResume`  | JsonResume  | src/index.js |         |
+| `custom-element-definition` | `json-resume` | JsonResume  | src/index.js |         |
+
+
+
 [microdata-html]: /blahg/microdata-with-html/
 [microdata-jsonresume]: /blahg/microdata-with-jsonresume/
 [jsonresume]: https://jsonresume.org

custom-elements.json

@@ -231,16 +231,6 @@
               "description": "URL to a JSON file. When present, used to fetch a resume.json file from the URL.\nChecked second or if gist_id does not have a resume.json, `local_file` will be ignored.",
               "attribute": "json_url"
             },
-            {
-              "kind": "field",
-              "name": "local_file",
-              "privacy": "public",
-              "type": {
-                "text": "string"
-              },
-              "description": "Path to a local resume.json file",
-              "attribute": "local_file"
-            },
             {
               "kind": "field",
               "name": "preordered",
@@ -307,14 +297,6 @@
               "description": "URL to a JSON file. When present, used to fetch a resume.json file from the URL.\nChecked second or if gist_id does not have a resume.json, `local_file` will be ignored.",
               "fieldName": "json_url"
             },
-            {
-              "name": "local_file",
-              "type": {
-                "text": "string"
-              },
-              "description": "Path to a local resume.json file",
-              "fieldName": "local_file"
-            },
             {
               "name": "preordered",
               "type": {

examples/browser/README.md

@@ -0,0 +1,12 @@
+json-resume web component examples
+---
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/scottnath/jsonresume-component/tree/main/examples/browser?file=README.md)
+
+
+These examples show usage of `<json-resume>` in a browser.
+
+* [Get `resume.json` using a GitHub gist ID](./index.html)
+* [Injecting a local `resume.json`](./local.html)
+* [Replacing resume sections with `slot` content](./slots.html)
+* [Overriding _all_ styles with your own stylesheet](./stylesheet.html)

examples/browser/index.html

@@ -15,7 +15,7 @@
       }
     </script>
     <script type="module">
-      import 'https://esm.run/jsonresume-component'
+      import 'https://unpkg.com/jsonresume-component'
     </script>
   </head>
   <body>

examples/browser/local.html

@@ -15,7 +15,7 @@
       }
     </script>
     <script type="module">
-      import 'https://esm.run/jsonresume-component'
+      import 'https://unpkg.com/jsonresume-component'
       import resumejson from './lorem.resume.short.json' with { type: 'json' };
       resumejson.basics.summary = 'This resume gets resume.json from a local file. In your HTML you can get the file using `import resumejson from "./resume.json" with { type: "json" };` and inject it into the component with `document.getElementById("jsonresume").resumejson = resumejson;`';
 

examples/browser/slots.html

@@ -16,7 +16,7 @@
     </script>
     <script type="module" src="https://unpkg.com/profile-components/dist/github-repository.js"></script>
     <script type="module">
-      import 'https://esm.run/jsonresume-component'
+      import 'https://unpkg.com/jsonresume-component'
       import resumejson from './lorem.resume.short.json' with { type: 'json' };
       resumejson.basics.summary = 'This resume replaces `work` and `projects` with slotted content. `projects` is using the github-repository component from profile-components to show the projects';
       const jsonresume = document.getElementById('jsonresume');

examples/browser/stylesheet.html

@@ -13,7 +13,7 @@
       }
     </script>
     <script type="module">
-      import 'https://esm.run/jsonresume-component'
+      import 'https://unpkg.com/jsonresume-component'
       // imports a stylesheet to a variable
       import evenTheme from 'https://unpkg.com/[email protected]/dist/style.css' with { type: "css" };
       // converts stylesheet to a string

lib/cem-readme.js

@@ -0,0 +1,24 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url'
+import { customElementsManifestToMarkdown } from '@custom-elements-manifest/to-markdown';
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const template = fs.readFileSync(path.join(__dirname, '../README.hbs'), 'utf8');
+
+const manifest = JSON.parse(fs.readFileSync('./custom-elements.json', 'utf-8'));
+const markdown = customElementsManifestToMarkdown(manifest, {
+  heading: 3,
+  private: 'hidden',
+  omitSections: [
+    'main-heading',
+    'super-class',
+    'attributes'
+  ]
+});
+
+const final = template.replace('{{>main}}', markdown)
+
+fs.writeFileSync('./README.md', final);

package.json

@@ -9,6 +9,7 @@
   },
   "scripts": {
     "cem": "custom-elements-manifest analyze --litelement --config 'lib/custom-elements-manifest.config.js'",
+    "postcem": "node ./lib/cem-readme.js",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "preview-storybook": "storybook dev",
@@ -77,7 +78,7 @@
   "customElements": "custom-elements.json",
   "dependencies": {
     "@lit/task": "^1.0.0",
-    "jsonresume-theme-microdata": "^0.0.7",
+    "jsonresume-theme-microdata": "^0.1.0",
     "lit": "^3.1.3"
   }
 }

src/index.js

@@ -79,13 +79,6 @@ export class JsonResume extends LitElement {
       type: String,
       attribute: 'json_url'
     },
-    /**
-     * Path to a local resume.json file
-     */
-    local_file: {
-      type: String,
-      attribute: 'local_file'
-    },
     /**
      * When true, sections of resume (basic, work, etc) will be injected according to their order in resume.json
      */

src/style.css

@@ -59,6 +59,7 @@
   width: 100%;
   background: var(--color-background);
   color: var(--color-primary);
+  padding: var(--spacing);
 }
 
 @media (prefers-color-scheme: dark) {

src/web-component.stories.js

@@ -98,6 +98,17 @@ export const SectionTitles = {
   }
 }
 
+export const Contained = {
+  render: (args) => 
+  html`<div style="margin: 0 auto; width: 100%; max-width: ${args.maxwidth || 52}em;">
+    <json-resume .resumejson="${args.resumejson}" preordered="${args.preordered}"></json-resume></div>
+  `,
+  args: {
+    resumejson: changeSummary('This resume is boxed into a container'),
+    preordered: true,
+  },
+}
+
 export const Slots = {
   render: (args) => 
   html`<json-resume .resumejson="${args.resumejson}" preordered="${args.preordered}">

yarn.lock

@@ -9082,10 +9082,10 @@ jsonparse@^1.2.0, jsonparse@^1.3.1:
   resolved "https://registry.yarnpkg.com/jsonparse/-/jsonparse-1.3.1.tgz#3f4dae4a91fac315f71062f8521cc239f1366280"
   integrity sha512-POQXvpdL69+CluYsillJ7SUhKvytYjW9vG/GKpnf+xP8UWgYEM/RaMzHHofbALDiKbbP1W8UEYmgGl39WkPZsg==
 
-jsonresume-theme-microdata@^0.0.7:
-  version "0.0.7"
-  resolved "https://registry.yarnpkg.com/jsonresume-theme-microdata/-/jsonresume-theme-microdata-0.0.7.tgz#98a24b91d4ab372f5432a500e7a36a1829ea273d"
-  integrity sha512-mkJDckOy+d9X9M9Dbyoux922cTM+oWLdw29z1wqZHV7v67+BnDqTscMZyFWXJAticKHvAaxILQTSMjRbQQ0cJA==
+jsonresume-theme-microdata@^0.1.0:
+  version "0.1.0"
+  resolved "https://registry.yarnpkg.com/jsonresume-theme-microdata/-/jsonresume-theme-microdata-0.1.0.tgz#f5785fff46ebc1609cf33b7dc91f9b395c541a78"
+  integrity sha512-4rUUwc4u3PEkBgxCrjhzDm8kzMa5dhEFHEDp+lhnLfOGnNopDI+gZoy1n0xnhumBfUmjV/ROYOy10BGPSuMD+w==
   dependencies:
     feather-icons "^4.29.2"
     micromark "^4.0.0"