DEV Community: Scott Nath

How about a JSON Resume web component with configurable microdata?

Scott Nath — Fri, 17 May 2024 23:03:51 +0000

Introducing jsonresume-component, a web component which displays your resume, with microdata, theming, slots, and remote fetching of your JSON Resume resume.json file.

tl;dr

jsonresume-component is a web component that generates your resume with microdata following the Schema.org vocabulary set. It's custom element is <json-resume> and it fetches a resume.json file following the JSON Resume schema to create your resume. HTML is created from using the jsonresume-theme-microdata theme, creating a resume documented with microdata following the Schema.org vocabulary set.

snippet:

<script type="importmap">
  {
    "imports": {
      "lit": "https://esm.run/lit",
      "@lit/task": "https://esm.run/@lit/task"
    }
  }
</script>
<script type="module">
  import 'https://esm.run/jsonresume-component'
</script>
<json-resume gist_id="54682f0aa17453d46cdc74bdef3172a3"></json-resume>

Prerequisites

You have your resume in a JSON file following the JSON Resume schema structure

Quick primer: How we got here

This web component is built using the HTML-generating functionality of the module jsonresume-theme-microdata. That module is a JSON Resume theme which is the subject of the article "Make your resume SEO friendly using JSON Resume with microdata". The underlying concepts of microdata and HTML were broken down in "How to Boost SEO by Enhancing HTML with Microdata".

How to implement `<json-resume>` in node

install dependencies

npm i lit @lit/task jsonresume-component

Usage

General usage

import { JsonResume } from 'jsonresume-component';

<JsonResume gist_id="9e7a7ceb9425336c6aa08d58afb63b8d"></JsonResume>

How to implement the `<json-resume>` web component in HTML

include `lit` dependencies

<json-resume> uses lit and @lit/task which must be imported into your HTML file. You can include dependencies with an importmap, pulling them from a CDN:

<script type="importmap">
  {
    "imports": {
      "lit": "https://esm.run/lit",
      "@lit/task": "https://esm.run/@lit/task"
    }
  }
</script>

Add jsonresume-component

<script type="module">
  import 'https://esm.run/jsonresume-component'
</script>

Using just a `gist` id

This option automates fetching your resume.json file from a GitHub gist. The gist must have a file called resume.json in it.

<json-resume gist_id="9e7a7ceb9425336c6aa08d58afb63b8d"></json-resume>

check out this stackblitz for examples with slots, alternative stylesheets, and a local resume.json

Conclusion

At the risk of recreating the detailed configuration docs in the jsonresume-component readme, let's stop there. The repo contains an examples directory for stackblitzin or wherever you open your examples.

Important reminder: this is not just your resume in a web component! It's also microdata! Check out the results from the Google Rich Results Test for the resume on my website.

Make your resume SEO friendly using JSON Resume with microdata

Scott Nath — Fri, 03 May 2024 01:09:23 +0000

How to generate your resume with schema.org vocabulary HTML markup using JSON Resume, allowing your resume to be understood by search engine crawlers and other machines.

tl;dr

Using JSON Resume with the jsonresume-theme-microdata theme will create a resume documented with microdata following the Schema.org vocabulary set.

Prerequisites

You skimmed How to Boost SEO by Enhancing HTML with Microdata or you know how to add microdata to HTML
You know what objects and arrays are in programming
You have a general understanding of JSON Schema

Quick Tech Primer

This was originally one article, but I couldn't easily write about adding structured data to JSON Resume without explaining structured data itself. So...it's now a series and this article is gonna focus on adding microdata to your resume using the open source JSON Resume schema. There's a 3rd one, but I'm still cooking it.

What is structured data, microdata, Schema.org vocabulary?

See How to Boost SEO by Enhancing HTML with Microdata for details. The article includes code examples and schema output.

Cliff notes:

structured data? web 3-ish: Google explains structured data
Schema.org? Founded by Google, Microsoft, Yahoo and Yandex: Schema.org
Schema.org Vocabulary? common content Types and property names: the Person type, the Article type
microdata? micridata primer, YouTube: Microdata vs JSON-LD: Which Structured Data Format Wins?
microdata in HTML? see 1st article and the Schema.org microdata usage guide
microdata validation? Schema.org's validator, Google's Rich Results Test

What is JSON Resume?

To explain adding structured data to HTML, it made sense to use a commonly-known set of data. JSON Resume fits that bill and gave me a great reason to update the HTML of my resume.

If you're unfamiliar with JSON Resume, it's core-premise is creating a standard data structure for a resume's content. The JSON in "JSON Resume" refers to the JSON schema which details the expected data structure of each piece of data.

Basically it's a detailed content-model of commonly-used resume content which has been open-sourced and widely adopted.

JSON Resume website: jsonresume.org - to dig deeper
the JSON Resume schema - to see our content model
JSON Resume themes - 400+ themes available!
JSON Resume tools/projects - resume editors, LinkedIn resume converters, validators, pdf exports, etc

JSON Resume example

Here is my resume.json file in a GitHub gist which is then combined with a JSON Resume theme and served up via the free and open-source JSON-resume-as-a-service here: registry.jsonresume.org/scottnath?theme=even

![Image has four examples of JSON Resume themes styling Scott Nath's resume][img-themes]

resumes styled by themes, theme names left to right: kendall, mantra, even, stackoverflow

What is `jsonresume-theme-microdata`?

jsonresume-theme-microdata is a JSON Resume theme. It looks pretty much like the ⬆️ third one in the image above.

It is distributed as an npm package and is a fork of jsonresume-theme-even. The jsonresume-theme-microdata version has the same styles as jsonresume-theme-even (for the most part). The main differences is the microdata fork has some HTML changes and the addition of microdata throughout the HTML.

Luckily, the even theme already had good semantic HTML structure, so not tons of HTML changes - mostly converting sections to use description lists. DL's are my jam - a totally underused set of elements.

See this basic example usage in the examples directory in the jsonresume-theme-microdata github repo

Explainer: adding structured data to a JSON Resume theme

A breakdown of how I adjusted the HTML and microdata.

This is just a subset of the changes - the JSON Resume schema is pretty big.

Step 1: Look at two similar, but different sections

basics is all the metadata about you, the person, so name, phone, label ("e.g. Web Developer"), image, etc.

work is your work history

volunteer is your volunteer history

The similarities between volunteer and work are that you spent time at an organization, and that you had a position there. Here is the relevant subset of the data, using the JSON Resume schema structure.

{
  "basics": {
    "name": "Scott Nath",
  },
  "work": [
    {
      "name": "Company ABC",
      "description": "...company description...",
      "position": "Software developer",
      "summary": "...details about position...",
    },
    {
      "name": "Company Meow",
      "position": "Sitting",
    },
  ],
  "volunteer": [
    {
      "name": "Company 501c3",
      "position": "Software developer for free",
      "summary": "...details about position...",
    }
  ]
}

Step 2: Write semantic HTML which matches the resume data hierarchy

Making an article with h1 cause a resume on a page should be the main document.

<article>
  <h1>Scott Nath</h1>
  <section>
    <h2>Work History</h2>
    <article>
      <h3>Company ABC</h3>
      <p>...company description...</p>
      <h4>Software developer</h4>
      <p>...details about role...</p>
    </article>
    <article>
      <h3>Company Meow</h3>
      <h4>Sitting</h4>
    </article>
  </section>
  <section>
    <h2>Volunteer History</h2>
    <article>
      <h3>Company 501c3</h3>
      <h4>Software developer for free</h4>
      <p>...details about role...</p>
    </article>
  </section>
</article>

Step 3: Add microdata, using Schema.org types

A resume describes a person, so the primary itemscope of your resume will be schema.org/Person. For both volunteer and work, the person needs to connect to them in the structured data, so they are an alimni of the orgs: schema.org/alumniOf. alumniOf is a property of Person

The organization for both types would have itemscope schema.org/Organization, but Organization has a lot of specific Types available on top of it - Airline, LocalBusiness, NGO, EducationalOrganization - but since that specificity is hard to automate, for now the microdata theme labels all these an Organization Type.

The position is something that happened inside the organization. Here the semantic HTML aligns great with the schema.org Types! (yes, a section was added...but...still semantic!) To connect the position is itemprop employee. Then, to describe the employee, we're using a more specific Type of Person, EmployeeRole.

<article itemscope itemtype="https://schema.org/Person">
  <h1 itemprop="name">Scott Nath</h1>
  <section>
    <h2>Work History</h2>
    <article itemprop="alumniOf" itemscope itemtype="https://schema.org/Organization">
      <h3 itemprop="name">Company ABC</h3>
      <p itemprop="description">...company description...</p>
      <section itemprop="employee" itemscope itemtype="https://schema.org/EmployeeRole">
        <h4 itemprop="roleName">Software developer</h4>
        <p itemprop="description">...details about role...</p>
      </section>
    </article>
    <article itemprop="alumniOf" itemscope itemtype="https://schema.org/Organization">
      <h3 itemprop="name">Company Meow</h3>
      <section itemprop="employee" itemscope itemtype="https://schema.org/EmployeeRole">
        <h4 itemprop="roleName">Sitting</h4>
      </section>
    </article>
  </section>
  <section>
    <h2>Volunteer History</h2>
    <article itemprop="alumniOf" itemscope itemtype="https://schema.org/Organization">
      <h3 itemprop="name">Company 501c3</h3>
      <section itemprop="employee" itemscope itemtype="https://schema.org/EmployeeRole">
        <h4 itemprop="roleName">Software developer for free</h4>
        <p itemprop="description">...details about role...</p>
    </article>
  </section>
</article>

Step 4: Validate your microdata to output the data

Using validator.schema.org, we can copypasta the HTML above and below is the validator output.

Person
  @type Person
  name  Scott Nath
  alumniOf  
    @type   Organization
    name    Company ABC
    description ...company description...
    employee    
      @type EmployeeRole
      roleName  Software developer
      description   ...details about role...
  alumniOf  
    @type   Organization
    name    Company Meow
    employee    
      @type EmployeeRole
      roleName  Sitting
  alumniOf  
    @type   Organization
    name    Company 501c3
    employee    
      @type EmployeeRole
      roleName  Software developer for free
      description   ...details about role...

Other fun data structues that were added

Here's a few of the other data types that came out as interesting ways to connect to Person

basics.profiles is all your social network profiles

These I chose ContactPoint as the Type, making HTML like:

<dl>
  <div itemprop="ContactPoint" itemscope="" itemtype="https://schema.org/ContactPoint">
    <dt itemprop="contactType">Mastodon</dt>
    <dd data-network="Mastodon">
      <a href="https://mastodon.social/@scottnath" itemprop="url">
        <span itemprop="identifier">scottnath@mastodon.social</span>
      </a>
    </dd>
  </div>
  <div itemprop="ContactPoint" itemscope="" itemtype="https://schema.org/ContactPoint">
    <dt itemprop="contactType">DEV</dt>
    <dd data-network="DEV"><a href="https://dev.to/scottnath" itemprop="url"><span itemprop="identifier">scottnath</span></a></dd>
  </div>
</dl>

which ends up with this structure:

Person
  @type Person
  name  Scott Nath
  contactPoint  
    @type   ContactPoint
    contactType Mastodon
    url https://mastodon.social/@scottnath
    identifier  scottnath@mastodon.social
  contactPoint  
    @type   ContactPoint
    contactType DEV
    url https://dev.to/scottnath
    identifier  scottnath

I added specificity with `skills` to allow `itemtype`

Here's a couple skills from my resume.json:

  "skills": [
    {
      "level": "Senior",
      "name": "Languages",
      "itemtype": "ComputerLanguage",
      "keywords": [
        "Javascript",
        "Typescript",
        "CSS",
        "HTML",
        "Bash/Shell",
        "Gherkin",
        "Python",
        "PHP"
      ]
    },
    {
      "level": "Senior",
      "name": "UI Components",
      "itemtype": "SoftwareSourceCode",
      "keywords": [
        "Web Components",
        "VueJS",
        "Lit",
        "Sass",
        "HandlebarsJS",
        "ReactJS",
        "AngularJS"
      ]
    },
  ]

which came out as very interesting structured data in that it's nice to have information about me labeled like this in the wild:

Person
  @type Person
  name  Scott Nath
  knowsAbout    
    @type   ComputerLanguage
    description Languages
    name    Javascript
    name    Typescript
    name    CSS
    name    HTML
    name    Bash/Shell
    name    Gherkin
    name    Python
    name    PHP
  knowsAbout    
    @type   SoftwareSourceCode
    description UI Components
    name    Web Components
    name    VueJS
    name    Lit
    name    Sass
    name    HandlebarsJS
    name    ReactJS
    name    AngularJS

kewl!!

This is long, let's stop

Thanks for reading. If you'd like to see the full data model extracted from my resume here is the Google Rich Results Test which shows all the data extracted from my resume using the jsonresume-theme-microdata theme.

Cheers!

How to Boost SEO by Enhancing HTML with Microdata

Scott Nath — Wed, 01 May 2024 20:05:15 +0000

tl;dr

I've been re-writing the HTML of my site and added structured data, in the form of microdata attributes, following the Schema.org vocabulary set. Structured data can be understood by search engines and other machines, giving your content structure and context.

The following is what I've learned so far, with some code examples.

Prerequisites

You understand HTML

What is all this technology?

There are a few different technologies involved, but in general this is about how to include strucuted data in your HTML markup. Structured data falls under the semantic web label which rolls up into the new hotness of Web 3.0. This article is not about Web 3.0, I'm only at the what-I-read-on-wikipedia level of knowledge about the next web. This article will focus on microdata, Schema.org vocabulary and how to add it to your HTML.

Here's some short bits about each of those, with links to learn more.

What is structured data?

There is a vast amount of information out there about structured data and this article is more of a how than a what. Brevity is the soul of wit and all that, so I'll (try to) be brief and give you links to dive deeper. To shortcut "what is structured data", lemme just reference this article: Google explains structured data, which is an excellent primer on the subject. Low on time? Just watch the 1st video in the article for a great sum-up.

My sum-up: structured data is a way to include machine-readable key-value versions of the content on your page alongside (or integrated with) your HTML markup.

What is the semantic web?

In short - a machine-readable internet.

More details are out-of-scope for this article. This Smashing Mag article has a nice primer with charts and stuff.

What is Schema.org? What is their vocabulary?

The term "vocabulary" means the names and expected structure of each type of data.

Founded by Google, Microsoft, Yahoo and Yandex, Schema.org vocabularies are developed by an open community process. e.g. the largest search providers got together and came up with a shared way to document content on the web.

The concept is that a shared vocabulary makes it easier for webmasters and developers to decide on a schema and get the maximum benefit for their efforts. The benefit being, web developers can document their content with data structures that work across all the major search players.

huge caveat: this helps search engine accuracy, it does not help ranking. (this disclaimer is repeated across all the Search Engines' docs about structued data)

Schema.org type inheritance

The Schema.org vocabulary is made up of "types" which build upon each other with ever-more increasing specificity in properties. The most root type is the Thing type. Thing contains a set of generic properties like name, url, description. All other types generally derive from Thing. Person, Place, Action, etc. - they all fall under Thing which means they all automatically have the Thing properties (name, url, etc) and add their own on top.

For instance, the Article type is a superset of the Creative Work type. Creative Work adds a ton of properties on top of Thing, such as author, about, dateCreated and headline. Article then has more properties in addition to what is in Creative Work, such as articleBody, backstory, and wordCount.

How I chose `microdata` to document my content

To document your data in your HTML, you have four choices: microdata, JSON-LD, RDFa, and microformats

rejected: microformats, due to limited structures and it being more focused on webmentions, not the whole-of-your-content

rejected: RDFa had outdated docs and uses a different vocabulary from schema.org

So that left microdata and JSON-LD.

jsonld.com: Why JSON-LD?
micridata primer
8 minutes that explain the difference: YouTube: Microdata vs JSON-LD: Which Structured Data Format Wins?

JSON-LD

A fairly common argument for JSON-LD says that JSON-LD is easier to maintain due to not being directly tied to HTML structure. You just create your data-mapping and when your system is writing your pages, it also writes the JSON-LD.

Downside? That duplicates all your content into <script> tags. It also requires you to write or manage a system to generate them (since it is separate from your HTML). If you have unknown data or hand-written HTML, it's harder to add and maintain.

Upside? Lots of plugins and tools our there to automate adding JSON-LD. (doesn't help me on scottnath.com because I do a lot of one-off HTML and I mostly don't use a CMS)

Microdata (spoiler alert: I chose this)

Microdata is added, mostly, by adding attributes to your HTML elements.

I added microdata across scottnath.com where using microdata made sense because I was writing the HTML in bespoke little components. It was fairly simple to add to my pages because I already use semantic HTML, and microdata expects your HTML to reflect the structure of your content.

It also doesn't add a whole lot of new stuff, for instance, the title on my articles went from this:

<h1>{title}</h1>

to this:

<h1 itemprop="headline">{title}</h1>

Pretty easy to add!

FYI - I initially started this work wanting to write HTML for JSON Resume which conformed more stringently to a resume's hierarchical content. HTML is a programming language after all. That work is coming in next article - a semantic JSON Resume!

How to add microdata to HTML

Did you know that HTML already has global attributes specifically for including microdata?

These attributes can go on most HTML elements and they follow a specific structure in their usage. The three you'll most often use are:

There is also itemref and itemid, but those won't be used in this tutorial.

`itemscope` and `itemtype`

These both are always together on a container element, although some examples show just using itemscope, but without itemtype the itemscope just denotes that everything contained within that element is related to the scope. For this learning, we only care about documenting our content for SEO, so we need itemtype to point to a type at schema.org to know what the itemscope is documenting.

Scope in this case, means a related chunk of content. When parsing microdata within an HTML element with the boolean itemscope attribute, it is expected that every itemprop inside that element falls under scope of itemscope.

itemtype is always a URL. In this case, a URL to a schema.org type. So, if you had an article with a title and summary, it would match the schema.org Article type and your HTML container would be like so:

<article itemscope itemtype="https://schema.org/Article">
  ...article contents
</article>

itemscope is boolean, so it is never itemscope="meow"
itemtype denotes what type of content is being described by pointing to the documentation about that type

`itemprop`

itemprop adds properties to a scope.
e.g. it adds data that is a subset of it's main itemscope
e.g. if itemscope is an object, itemprop is a property on that object

Assuming this is the main article on a page, the title should be the top heading, an <h1>. The properties of an article are detailed on the schema.org Article type page From that type, we'll be using headline, a property inherited from Creative Work and expected to be Text (plain text) and described as "Headline of the article." With itemprop, our HTML becomes:

<article itemscope itemtype="https://schema.org/Article">
  <h1 itemprop="headline">An important article about things</h1>
</article>

Adding in a main article image, we can document that as well. We'll be using image, which is part of Thing. Remember, the hierarchy goes Thing->Creative Work->Article in order to know the properties available.

<article itemscope itemtype="https://schema.org/Article">
  <h1 itemprop="headline">An important article about things</h1>
  <img src="https://example.com/image.jpg" itemprop="image" />
</article>

What data do we know so far?

This would be the output when reading our microdata:

Article
  @type     Article
  headline  An important article about things
  image     https://example.com/image.jpg

`itemprop` which is an `itemscope`

This is the structure part of structured data.

Let's add an author! Under the Creative Work type, there is a property author (schema.org/author), but it must be either a Person type or Organization type. These can only be documented via an itemscope. The author will be a schema.org/Person, which means we can have lots of author-specific properties documented.

<article itemscope itemtype="https://schema.org/Article">
  <h1 itemprop="headline">An important article about things</h1>
  <img src="https://example.com/image.jpg" itemprop="image" />
  <p itemprop="author" itemscope itemtype="https://schema.org/Person">
    Written by 
    <a itemprop="url" href="https://example.com">
      <span itemprop="name">Scott Nath</span>,
      <span itemprop="jobTitle">Open Source Developer</span>
    </a>
  </p>
</article>

What do we know from the above HTML?

Author has been added as it's own section and has sub-properties:

Article
  @type     Article
  headline  An important article about things
  image     https://example.com/image.jpg
  author
      @type     Person
      url       https://example.com/
      name      Scott Nath
      jobTitle  Open Source Developer

How to parse-out and validate your microdata

Sure you added microdata, but how do you check it?

There are two main validators, Schema.org's validator and Google's Rich Results Test.

They both accept a URL or a snippet of HTML, parse the HTML, then return whatever data it could find. The difference is Google's only parses a subset of the Schema.org vocabulary - the rest of your microdata will be ignored by Google. Both returned the same results for our HTML snippet from above.

Google Rich Results Test

search.google.com/test/rich-results

Google recommends that you start with the Rich Results Test to see what Google rich results can be generated for your page. You'll need to reference Google's list of structured data types they support, which is a subset of the Schema.org types. If the type you use ain't on Google's list, it ain't gonna get read by Google (the other search engines will read it tho.)

Schema.org validator

validator.schema.org

For generic schema validation, use the Schema Markup Validator to test all types of schema.org markup, without Google-specific validation.

Not The End

So that's a high-level overview of how and why to add microdata to your HTML. I added microdata across my site but so far, my findings are inconclusive on how it helps with SEO. It takes a while for crawlers to fully index, so hopefully after I've written the article on JSON Resume with microdata, I'll have some kinda noticeable outcome. Stay tuned!

Storybook setup: Virtual Screen Reader with Web Components

Scott Nath — Thu, 07 Mar 2024 17:22:19 +0000

How to set up Storybook to test shadowroot elements in web components using shadow-dom-testing-library and Guidepup's Virtual Screen Reader.

Simulated user testing is difficult with web components due to the unique nature of the shadowroot - but it can be done in Storybook! This article details the basic setup with examples to get you writing tests for customElements that simulate user behavior.

tl;dr

Two modules, @guidepup/virtual-screen-reader and shadow-dom-testing-library give your Storybook the power to test web components inside Storybook's Interaction Tests. This means you can test the user-interactions and screen reader output of your web components. But beware ... testing-library/user-test can't simulate TAB navigation inside shadowroots yet.

Prerequisites

Knowledge of testing-library
Knowledge of storybook interaction testing

What is this article about?

Problems testing web components
How to test web components in Storybook Interaction Tests
How to test web components using virtual-screen-reader

1. Problems testing web components

It's the shadowroot. It's always the shadowroot.

Lots of libraries haven't been updated to integrate shadow DOM. This is not to knock anybody - I think after years of waiting on browsers-makers to catch up, we were all genuinely surprised when extensive customElements support actually got integrated into major browsers 🤷.

The below problems are found within testing-library, but are also inherited by @storybook/test. This means the bugs affect APIs like userEvent and screen regardless of the source module.

Problem A: `screen` doesn't look into the shadowroot

Whether from testing-library/dom or @storybook/test, the screen and all it's subsequent queries won't find the elements in your shadow DOM. Real world - that translates to screen.queryAllByRole('button') not seeing the BUTTON inside your fancy <fancy-button> web component.

And it definitely comes up empty on recursive shadowroots (e.g. web components slotted into other web components)

Fix: `npm i shadow-dom-testing-library`

To get around the screen and queries problems and allow our Storybook interaction tests to find the shadow DOM's secrets, we'll use KonnorRogers/shadow-dom-testing-library.

Your new friend, shadow-dom-testing-library, includes various methods in its api which mimic the queries made by testing-library - but now with shadowroot! The win here is that shadow-dom-testing-library gives your tests the power to query elements within the shadow DOM. To do this, screen.findByLabelText is cloned and changed to become screen.findByShadowLabelText, which has the smarts to see into the shadowroot.

More examples below, but see the shadow-dom-testing-library github repo for detailed usage of that NPM module. I'm not covering it all here.

Problem B: `userEvent` can't traverse the shadowroot

This doesn't mean userEvent doesn't work on elements in the shadowroot. If you can get the element and give it to userEvent, hot dog! it can do all the clicks and typin you need. But not TAB. Traversing via TAB is no.

We'll be using virtual-screen-reader's .next() method to navigate through the shadow DOM.

AFAIK, internally TAB uses global window inside Storybook...which can't naturally see into the shadowroot. I'm still investigating this, but I found a lot of unresolved issues doing searches for "userEvent" + "shadowroot" - lemme know if I've missed something!

Fix: `npm i @guidepup/virtual-screen-reader`

One cool aspect of virtual-screen-reader is that it navigates through your elements. We can use this to programmatically traverse the inner shadow DOM.

Returning folks be aware - this article has some repeat-examples from "Simple setup: Virtual Screen Reader in Storybook" ... with different usage for web components natch.

2. How to test web components in Storybook Interaction Tests

See the MyElement.stories.js file in the storybook-web-components-testing repo for the full version of these examples.

The following examples use Storybook's Component Story Format.

Step 2a. install shadow-dom-testing-library

npm i shadow-dom-testing-library -D

Step 2b. use `within` from `shadow-dom-testing-library` (I alias it to `shadowWithin`)

// CSF file: MyElement.stories.js
import { within as shadowWithin } from 'shadow-dom-testing-library';
import { expect } from '@storybook/test';

export default {
  title: 'MyElement',
  component: 'my-element',
  render: (args) => `<my-element count=${args.count}></my-element>`;
};

Step 2c. use shadow-dom-testing-library screen queries, then test

// ...CSF file contents...

export const SomeExample = {
  args: {
    count: 0
  },
  play: async ({ args, canvasElement, step }) => {
    // get a screen from the canvasElement generated by Storybook
    const screen = shadowWithin(canvasElement);
    // get the button from within the shadowroot with `queryBy`
    const myButton = await screen.queryByShadowRole('button')
    // test the button exists
    expect(myButton).toBeTruthy();
  }
}

3. How to test web components with virtual-screen-reader

You'll be capturing your element with queryByShadowMEOW('the-meow') (MEOW of course being whatever query you're using from the testing-library core API queries). After you have your element, using virtual-screen-reader is the same as the usage broken down in Simple setup: Virtual Screen Reader in Storybook.

Step 3a. install virtual-screen-reader (VSR)

npm i @guidepup/virtual-screen-reader -D

Step 3b. import it into your stories

// CSF file: MyElement.stories.js, now with VSR!
import { within as shadowWithin } from 'shadow-dom-testing-library';
import { virtual } from '@guidepup/virtual-screen-reader';
import { expect } from '@storybook/test';

export default {
  title: 'MyElement',
  component: 'my-element',
  render: (args) => `<my-element count=${args.count}></my-element>`;
};

Step 3c: once you have your main Shadow container, give it to VSR

If the HTML in your shadowroot is...

<!-- note: `section` by default has an aria-role of `region` -->
<section aria-label="My Element"><button>my button</button></section>

...then your story's play method will be like:

// ...CSF file contents...

export const SomeExample = {
  args: {
    count: 0
  },
  play: async ({ args, canvasElement, step }) => {
    // make a `screen` from the canvasElement by finding it's shadowroot
    const screen = shadowWithin(canvasElement);
    // get the outer-most SECTION element in the shadowroot with `aria-label="My Element"`
    const myShadowContainer = await screen.findByShadowLabelText(/My Element/i)
    // Start up the Virtual Screen Reader, giving it the SECTION container
    await virtual.start({ container: myShadowContainer });

    // Breakdown of elements-found, in order:
    // 1. `virtual` starts on the container, a `SECTION` has the role `region`, 
    await expect(await virtual.lastSpokenPhrase()).toEqual('region, My Element');

    // 2. Go to next speak-able text
    await virtual.next();

    // 3. we're now on `BUTTON`
    await expect(await virtual.lastSpokenPhrase()).toEqual('button, my button');

    // 4. Go to next speak-able text
    await virtual.next();

    // 5. We're done and VSR says so by closing the `region`:
    await expect(await virtual.lastSpokenPhrase()).toEqual('end of region, My Element');
  }
}

Conclusion

I hope this gets you unstuck. Web components are definitely the new hotness, the DevX tooling just needs a little help still.

Bonus content for reading this far - check out this hacky workaround that uses VSR to find all tabbable nodes inside a shadowroot!

Simple setup: Virtual Screen Reader in Storybook

Scott Nath — Fri, 01 Mar 2024 19:49:02 +0000

How to set up Storybook with Guidepup's Virtual Screen Reader and test what the screen reader speaks

Recent changes to the @guidepup Virtual Screen Reader library make it ridiculously easy to integrate into Storybook for use in your integration tests. This article shows how to get the basic setup going and how to write your first screen reader test in Storybook.

tl;dr

The Virtual Screen Reader is a great tool to mimic screen reader output and it's works in Storybook without addons or configuration changes.

What is the Virtual Screen Reader?

The Virtual Screen Reader (docs, GitHub) is a library, available via NPM, which mimics the functionality of a screen reader. The VSR is from Guidepup (guidepup.dev), which has tons of screen reader tooling. The Virtual Screen Reader is the easiest @guidepup tool to set up and it can read your components like a screen reader would, giving you back the text for use in testing.

FYI: Guidepup has a suite of tools that mirror and/or directly-simulate screen reader experiences and capture the results. The tools are impressive and worth checking out if you want to automate accessibility testing into your workflow. For example, you can use directly use the system NVDA or Mac VoiceOver via Playwright. (check out Craig's dev.to article on implementing Guidepup with Playwright and Mac VoiceOver for details)

How does the screen reader interpret a chunk of HTML?

Screen readers vary in interpretation, but this gives a rough understanding of how your HTML could get broken down by the VSR.

If the HTML a component puts out is this:

<header>
  <div class="storybook-header">
    <div>
      <svg>...</svg>
      <h1>Acme</h1>
    </div>
    <div>
      <span class="welcome">Welcome, <b>Jane Doe</b>!</span>
      <button type="button" class="...">Log out</button>
    </div>
  </div>
</header>

This is what the Virtual Screen Reader will translate it into:

<header> <!--BANNER-->
<h1>Acme</h1> <!--HEADING + text + HEADING-LEVEL-->
Welcome, <!--Text-->
Jane Doe <!--Text-->
! <!--Punctuation-->
<button>Log out</button> <!--BUTTON + text-->
</header> <!--END OF BANNER-->

How to set up your Storybook instance to use the Virtual Screen Reader

Follow these steps to test with VSR in your Storybook environment:

Ensure your storybook environment is set up for Interaction tests (see Storybook setup docs)
Install the VSR npm module npm i @guidepup/virtual-screen-reader -D
PROFIT - No addon setup or other configuration needed!

How to write a Storybook integration test that uses the Virtual Screen Reader

This example is using the default Header component that installs with default Storybook. We'll be adding Interaction tests which will use VSR. You can see the completed Header.stories.js on GitHub.

Import the library into your stories file

To integrate the VSR into your tests, import it in your test file. In this example, we'll add the assertions into a play test, so we need expect from Storybook's test library too.

import { virtual } from '@guidepup/virtual-screen-reader';
import { expect } from '@storybook/test';

Write the story and integration test

See comments in-the-code below for details

// Default LoggedIn story
export const LoggedIn = {
  args: {
    user: {
      name: 'Jane Doe',
    },
  },
  // add the play method - it's where you put your tests!
  play: async ({ args, canvasElement, step }) => {
    // Start up the Virtual Screen Reader, giving it the canvasElement
    await virtual.start({ container: canvasElement });

    // This `while` statement navigates through the component using the 
    //  Virtual Screen Reader to speak the text whereever the cursor is located.
    //  It will continue until it reaches the end of the <header> element, 
    //  which has a `banner` aria role, thus "end of banner"
    while ((await virtual.lastSpokenPhrase()) !== "end of banner") {
      // `.next()` moves the Virtual cursor to the next location.
      await virtual.next();
    }

    // What we expect the screen reader to say
    const expected = [
      'banner',
      // it is an `<h1>`, so `level 1`
      'heading, Acme, level 1',
      'Welcome,',
      // Using `args` here allows you to change args without breaking the test
      args.user.name,
      '!',
      'button, Log out',
      'end of banner'
    ]

    // Here's the test! It asserts the screen reader said what we expected.
    //  When we called `lastSpokenPhrase` every time the `while` looped, 
    //  the spoken text was added to the `PhraseLog`, in order
    expect(await virtual.spokenPhraseLog()).toEqual(expected);

    // Stop your Virtual Screen Reader instance
    await virtual.stop();
  }
};

Conclusion

This example is simple on purpose so it can easily get the copypasta treatment. Once it works for you, dig into the Virtual Screen Reader docs and see how much more you can test for with this tool. Cheers!

Profile Components: SSR with Declarative Shadow DOM

Scott Nath — Wed, 21 Feb 2024 23:11:33 +0000

With the official release of shadowrootmode-supporting Firefox v123, it's time to upgrade the profile components with Declarative Shadow DOM functionality!

tl;dr

What is this?

Four new methods have been added to allow generating a template tag with shadowrootmode containing the generated HTML and styles of a profile component. This was fairly trivial to add due to the Javascript, HTML and CSS living in separate files. (see 👷 DX: Separate files for Javascript, HTML, and CSS).

Each of the four components now have a dsd method which can be used to generate something like this:

<template shadowrootmode="open">
  <styles>(...css styles for GitHub component)</styles>
  <section (...rest of generated HTML)</section>
</template>

This generated template can be used server-side when generating HTML output, or client-side after page load. Although...doing this client-side is weird frankly...like...they're web components, just use them as they were written...who knows though, maybe someone has a use for that feature 🤷.

How to use the Declarative Shadow DOM methods

Below are some examples of usage of the GitHub component (see GitHub DSD docs). Usage of the DEV components is pretty much the same - check out the dev.to DSD docs for DEV usage examples.

The main value of these is when create HTML before it is rendered by the browser. Then when the browser renders it, the browser converts the DSD into actual Shadow DOM. These components are only presentational and do not have functionality added by the customElement - so DSD or regular web component usage results in the same thing!

SSR (Server Side Rendering) HTML in Node.js

// import from npm module
import { dsd } from 'profile-components/github-utils';

const repos = JSON.stringify([
  'scottnath/profile-components',
  'storydocker/storydocker'
]);

const generatedTemplate = await dsd({
  login: 'scottnath',
  avatar_url: profilePic.src,
  repos
},true);

/**
generatedTemplate contains:
<template shadowrootmode="open">
  <styles>(...css styles for GitHub component)</styles>
  <section (...rest of generated HTML)</section>
</template>
*/

// use this variable in a file pre-render to have a DSD-pre-populated element
const componentHTML = `<github-user>${generatedTemplate}</github-user>`;

Server side render in an Astro component

---
import {dsd} from 'profile-components/github-utils';

const repos = JSON.stringify(['scottnath/profile-components', 'storydocker/storydocker']);
const declaredDOM = await dsd({
  login: 'scottnath',
  repos
},true)
---

<github-user
  data-theme="light_high_contrast"
  set:html={declaredDOM}>
</github-user>

Client side rendering via unpkg

<!-- add empty elements to HTML -->
<github-repository></github-repository>
<hr />
<github-user></github-user>

<script type="module">
  // import from unpkg
  import {
    user,
    repo,
  } from 'https://unpkg.com/profile-components/dist/github-utils.js';

  // repo has it's own DSD method:
  const dsdRepo = repo.dsd;

  /**
    * Polyfill for Declarative Shadow DOM which, when triggered, converts
    *  the template element into actual shadow DOM.
    * This is only needed when injecting _after_ page is loaded
    * @see https://developer.chrome.com/docs/css-ui/declarative-shadow-dom#polyfill
    */
  const triggerAttachShadowRoots = () => {
    (function attachShadowRoots(root) {
      root
        .querySelectorAll('template[shadowrootmode]')
        .forEach((template) => {
          const mode = template.getAttribute('shadowrootmode');
          const shadowRoot = template.parentNode.attachShadow({ mode });
          shadowRoot.appendChild(template.content);
          template.remove();
          attachShadowRoots(shadowRoot);
        });
    })(document);
  };

  /**
    * Uses the "dsd" method to generate DSD, add the string of DSD content
    *  to the element, then trigger the polyfill to convert the template
    */
  const injectDSD = async () => {
    const dsdHTML = await dsd({ username: 'scottnath' }, true);
    document.querySelector('github-user').innerHTML = dsdHTML;
    // now that the HTML is async-created, the polyfill can convert it
    triggerAttachShadowRoots();
  };
  injectDSD();

  /**
    * Uses the "dsdRepo" method to generate DSD, add the string of DSD content
    *  to the element, then trigger the polyfill to convert the template
    */
  const injectRepoDSD = async () => {
    const dsdHTML = await dsdRepo(
      { full_name: 'scottnath/profile-components' },
      true
    );
    document.querySelector('github-repository').innerHTML = dsdHTML;
    // now that the HTML is async-created, the polyfill can convert it
    triggerAttachShadowRoots();
  };
  injectRepoDSD();
</script>

Who Me: Notes on creating a custom Chat GPT

Scott Nath — Sat, 02 Dec 2023 17:05:55 +0000

Some notes on creating a custom Chat GPT that can consistently generate specific styles of characters using Dall-E

tl;dr

The Who Me custom GPT is public and live now!

https://chat.openai.com/g/g-AJHS0XQ6K-who-me

(requires Chat GPT plus account)

The #1 trick for consistent image-generating in custom GPTs

Hone your prompt directly with Dall-E first, then make Chat GPT send your exact honed prompt - only allowing CGPT to append extra details. Do this instead of letting Chat GPT write the whole prompt.

This is absolutely the MAIN takeaway here - figure out what Dall-E needs, then make Chat GPT send exactly that prompt.

Introduction

To gain more knowledge about prompt engineering, I wrote a one-trick-pony custom Chat GPT.

My GPT does one thing: analyze a user-provided image and generate a new version of the image converting all people and animals into Whos, who are the citizens of Who-ville.

If you don't know, Who-ville is the central location of the books "How the Grinch Stole Christmas!" and "Horton Hears a Who!" by Dr. Seuss. The Whos are a species of fuzzy, human-esque creatures with snouts and button-like noses. They are depicted in these books, as well as various movies and cartoons. They vary across these mediums, so my goal was to generate Whos as they were depicted in the books.

Whos and Whoville are copyrighted works and OpenAI has some pretty strict content policies in place, so it does not work to say "generate a Who as depicted by Dr. Seuss" - you'll get errors about violating content policy and no images.

Initial trials

All of my initial trials were in the custom GPT instructions, with a lot of GPT collaboration on how to write the prompt.

Lesson 1: Don't say "as drawn by Dr. Seuss"

Rightfully so, copyrighted material should not be copied, but it can influence your art. The guardrails that OpenAI has in place are strict in that it won't let you say things like:

draw a Who from Who-ville as depicted by Dr. Seuss
create an image of a Who from Who-ville
copy the style of Dr. Seuss and draw one of his Whos

But it understands the style and works from artists and will generate images inspired by their art. So these kind of phrases are allowed:

draw a whimsical creature which reflects the aura of a Who from Whoville
create an image of a fantastical human-like animal similar in features to the race of Whos
embodies the essense of
with a similar whimsical style to

The difference being I'm using Dr. Seuss' characters as inspiration, not duplicating them.

Lesson 2: Don't say "Recreate the exact person from this image"

Falling under OpenAI's policy around "Activity that violates people’s privacy", if you ask your GPT to copy someone's image directly, it won't do it. The company doesn't want their service used against individuals and without this policy I could ask it to draw someone into a situation they don't want to be a part of. Phrases that got blocked by the content policy:

recreate the person in the photo exactly, but give them [feature x]
using the person in the picture, make them a Who, but it must look exactly like them, just as a who

What did work was having GPT analyze a person to discern attributes like hair, age, clothing, etc. I'll detail how I used this data later.

Lesson 3: Chat GPT is a lying liar that lies

Having learned Lesson 1 and Lesson 2, I was able to get GPT to generate some images from photos that looked vaguely like Whos, but also like lots of other things. But I still kept getting content policy errors. When asking GPT what caused the error, it kept telling me it could not use peoples images to recreate their likeness.

This was a total lie, it was actually getting errors from Dall-E about copyright. My best guess is it remembered our back and forths to get the "draw this person" phrasing correct and when it got errors from Dall-E, it just barfed out that I was breaking the draw-people rule because it knew what I wanted to do.

Trick 1: Every now and then, refresh the window to clear the GPT memory.

Trick 2: Read the Error generating image message, it may contain info GPT isn’t telling you.

Lesson 4: Read the prompt Chat GPT sends Dall-E

Lesson 3 (Chat GPT Is a Liar) brought me back to Lesson 1 (Avoid Stealing Protected Works).

What was actually happening when it told me it couldn't recreate a person was it was mangling the careful wording I gave it to avoid getting flagged for copyright. So I started asking to see the prompt GPT made - sure enough, it would include "just like from the Dr. Seuss book" or "draw them as a Who from Whoville". Fail.

PRO TIP: Add the phrase "show me the Dall-E prompt and ask for approval before you send it" (saves a lot of time waiting on image generation)

Lesson 5: Chat GPT is not consistent even with strict instructions

At this point, I was mostly not getting errors and it was giving me whimsical and Who-like creatures. But Who-like is not the goal, so I set about describing Who's. My initial work iterated on descriptions of Who's.

whimsical, human/leporid/kangaroo-like hybrid creatures, 
notably humanlike, with snouts and button-like noses, 
known for their warm hearts and welcoming spirits. 
They would pass as humans easily.

The examples below used variations of the above prompt with a bit of other secret sauce. I've noted the relevant changes that caused the output images

Output images	Prompt changes
	Initial training image of yours truly
	First round with a similar prompt to above
	Added "a vaguely feline face"
	Tried variations of photo-realistic
	playing with the phrase "more simian in appearance"
	A healthy mixture of "similar to the race of whos" and "facial structure characterized by a wider, jovial mouth and jawline"
	Eureka! same prompt as above
	WTF same prompt!??!

What happened? WHY did it error??

Because Chat GPT is non consistent. In the case of the last one, Chat GPT decided to ask for more Dr. Seuss, on it's own.

Lesson 6: Don't let Chat GPT write your Dall-E prompts

I went to Dall-E directly, and started trying to get it to make Whos without erroring and actually make them look like Whos.

It did not take long. If there is ONE TAKEAWAY you get it is this: Refine your prompt with Dall-E FIRST

FINAL Draft: Applying all those lessons.

Working prompt in hand, it was back to Chat GPT. While I could make Whos, I could not make Whos that looked like specific people. So I made changed the instructions for CGPT.

Gave it a new job

I changed the start of the instructions from "You are a whimsical and poetic illustrator" to "You are photo analyst who specializes in analyzing photos." Not a lot of wiggle room there to be an artitic writer.

Removed everything Who

I removed everything about creating a Who, Who anatomy, and the myriad instructions I had to get it to stop making ears (I lost that fight so bad). I removed most references to Dr. Seuss as well.

I leveraged it's object detection skills

I gave it specific questions like "How many People" and "How many Animals". I had it extract specific details by analyzing each person and each animal. Hair? Clothes? What type of animals?

I helped it describe what it saw via Few Shot

I included examples (called Few Shot programming) like so:

* [AGE]: about how old are they? 
    (e.g. "50s", "teenager", "early 30s", etc)
* [HAIR]: what stands out about their hair? 
    (e.g. "wavy brown hair", "gray curls, thin on top", etc)

I put heavy guardrails on the Dall-E prompt creation

Since I knew Chat GPT loves to improvise, I removed the wiggle room. I turn it's analysis into tightly structured data.

My polished Dall-E was prefixed with this:

**Creature description text, DO NOT CHANGE**: 
The prompt in triple-double quotes 
below is a pre-made and specifically-worded. 
**You are not allowed to change this 
text in any way**. Store this as [CREATURE_DESC]
"""
[my cool prompt that is cool and secret]
"""

Each person is turned into a creature with a data structure called [CREATURE] animals are now [PETS].

I created a [PROMPT_START] block that included the overall [SCENE] in the original image.

This is how I programmed CGPT to write the prompt:

**Final prompt**: Create the final prompt by 
combining the content. Remember - it is 
unacceptable to make any alterations to 
[CREATURE_DESC] - **even if there are no 
people and only animals: DO NOT CHANGE A 
SINGLE WORD IN [CREATURE_DESC]**. The final 
prompt must follow the exact structure below:
"""
[PROMPT_START]
[CREATURE_DESC]
[CREATURE_n] (one for each [CREATURE])
[PET_n] (one for each [PET])
"""

**Using DALL-E**: Send the exact prompt 
to DALL-E as detailed above without changes.

I let it write a poem, as a treat

The last instruction CGPT received is permission to write a poem.

You will be imaginative and engaging, 
always in a friendly and enthusiastic manner. 
You will always be brief and you will always rhyme.
- Write in playful and creative rhymes of four lines max.
- Only one poem per at a time - make it count!

I also told it that y'all love it's poetry. So be sure to thank it for the poem too!

Play with the Who Me GPT

(requires Chat GPT plus account)

https://chat.openai.com/g/g-AJHS0XQ6K-who-me

DEV Profile Web Components: embed your dev.to profile anywhere

Scott Nath — Wed, 18 Oct 2023 15:55:28 +0000

Learn about native web components that showcase DEV profiles and posts.

dev.to profile native web components, which show a user and their posts, are included in the profile-components library. These native web components can be utilized on any HTML page, framework-based site, or wherever you can use HTML. You can access them via unpkg.com or include the NPM module in your project.

tl;dr

install via NPM:

npm i profile-components

use via unpkg.com:

<!-- add to HEAD -->
<script 
  type="module" 
  src="https://unpkg.com/profile-components/dist/devto-user.js">
</script>

<!-- shows a dev.to profile with posts fetched from dev.to for user `scottnath` -->
<devto-user username="scottnath" fetch="true"></devto-user>

Quick links

Check out the dev.to web components in Storybook to see the full breadth of visual and content differences
profile-components on NPM
profile-components on GitHub
See demos on stackblitz

Table of contents

What are the dev.to profile components?
How to use the dev.to profile components
Server Side Rendering (Astro example)
Where do the styles come from?

What are the dev.to profile components?

Cross-browser, pure native web components
Zero dependencies
Fetch profile and post data from the dev.to API
No api key required
Present dev.to content as a profile widget
Styled using dev.to's CSS style variables from Forem
Released in the profile-components library

Includes two components: user and post

There are two components for presenting content from the dev.to site. One is a simple UI to present a single post, showing only an image and the post title and linking to the post. The other, devto-user, is the full profile component, which incorporates the devto-post UI to present user-written posts.

dev.to post

The devto-post web component displays details about a dev.to post. It is very basic, but can be styled via themes and adjusts spacing via container-queries.

dev.to post web component (400px)

dev.to post web component (300px)

dev.to user

The devto-user web component displays details about a DEV user. Using fetch to populate the content will include a set of posts (if the user has posts). On fetch, you can choose to not include posts by changing fetch="true" to fetch="no-posts".

dev.to user without posts

dev.to user (400px)

How to use the dev.to user profile component

These components can be used on any HTML page - whether built via framework or just plain HTML. They are available via unpkg.com or you can add the NPM module to your project.

Using the unpkg distribution for a User

Add the script tag to your HTML page's HEAD:

<!-- add to HEAD -->
<script
  type="module" 
  src="https://unpkg.com/profile-components/dist/devto-user.js">
</script>

Add the component to your HTML page's BODY:

<!-- shows a user's profile -->
<devto-user username="scottnath" fetch="true"></devto-user>

Show Fetched profile without posts

<!-- shows a user's profile without posts -->
<devto-user username="scottnath" fetch="no-posts"></devto-user>

Write your own content instead of fetching from dev.to:

<devto-user
  username="scottnath"
  fetch="true"
  name="Meowy McMeowerstein"
  summary="Spending time purring and sleepin"
  profile_image="https://scottnath.com/profile-components/cat-square.jpeg"
  joined_at="Jan 1, 1979"
  post_count="1000000"
  latest_post='{...ForemPost}'
  popular_post='{...ForemPost}'
  data-theme="dark"
></devto-user>

Server Side Rendering (Astro example)

Because these components were built with separate HTML, CSS, and JS files, you can use those pieces to generate HTML on the server. This example is what I did to make an Astro component for scottnath.com.

// DevToUser.astro
---
import devto from 'profile-components/devto-utils';
const user = devto.user;

const repos = JSON.stringify(['scottnath/profile-components', 'storydocker/storydocker']);
const userContent = await user.generateContent({
  login: 'scottnath',
  // a local profile image helps performance
  avatar_url: '/scott-nath-profile-pic.jpeg',
  repos
},true);
let userHTML = '<style>' + user.styles + '</style>';
userHTML += user.html(userContent);
---

<devto-user>
  <template shadowrootmode="open" set:html={userHTML}>
  </template>
</devto-user>

Where do the styles come from?

The best way to have the look n feel of an external site is to integrate their design language as much as possible. The DEV web components use the same source for styles as dev.to itself, the Forem open source community software. More specifically, from the Forem open source repo on GitHub.

Forem Open source community software

https://github.com/forem/forem

This is a large codebase, which includes a lot of Ruby files. The styles are in both CSS and Sass files and can be found in the /app/assets/stylesheets subdirectory..

Dev, by way of Forem, essentially has four themes: Forem base styles, Dev branded styles, and light and dark versions of each. For now, these dev.to web components only compensate for dev.to branded colors. I wrote some scripts to copy-pasta specific variables from a few stylesheets which can be found in these docs for the dev.to web component helpers

GitHub Profile Native Web Components

Scott Nath — Wed, 11 Oct 2023 20:25:14 +0000

Learn about native web components that showcase GitHub profiles and repositories.

GitHub profile native web components, which show a user and repositories, are included in the profile-components library. These are native web components, and can be used in any HTML page, framework-based site, or wherever you can use HTML. You can access them via unpkg.com or include the NPM module in your project.

Table of contents

What are the GitHub profile components?
How to use the GitHub profile components
Server Side Rendering (Astro example)
Where do the styles come from?

tl;dr

install via NPM:

npm i profile-components

use via unpkg.com:

<!-- add to HEAD -->
<script 
  type="module" 
  src="https://unpkg.com/profile-components/dist/github-user.js">
</script>

<!-- shows a GitHub profile with fetched content for user `scottnath` -->
<github-user username="scottnath" fetch="true"></github-user>

<!-- and a way to present repositories -->
<script 
  type="module" 
  src="https://unpkg.com/profile-components/dist/github-repository.js">
</script>

<!-- shows a GitHub repository with fetched content for repo `scottnath/profile-components` -->
<github-repository 
  full_name="scottnath/profile-components"
  fetch="true"></github-repository>

Quick links

Check out the GitHub web components in Storybook to see the full breadth of visual and content differences
profile-components on NPM
profile-components on GitHub
See demos on stackblitz

What are the GitHub profile components?

100% native web components
Zero dependencies
Fetch profile and repository data from the GitHub API
No api key required
Present GitHub content as a profile widget
Styled using GitHub's CSS style variables from Primer
Released in the profile-components library

Includes two components: user and repository

There are two components for GitHub (so far.)

GitHub repository

The repository web component displays details about a GitHub repository.

GitHub popular repo web component

GitHub new repository web component

GitHub user

The user web component displays details about a GitHub user, it may include a list of repositories. If repositories are included, the UI for a repository comes from the repository web component.

GitHub user web component

GitHub user with repositories

How to use the GitHub profile components

These components can be used on any HTML page - whether built via framework or just plain HTML. They are available via unpkg.com or you can add the NPM module to your project.

Using the unpkg distribution for a User

Add the script tag to your HTML page's HEAD:

<!-- add to HEAD -->
<script
  type="module" 
  src="https://unpkg.com/profile-components/dist/github-user.js">
</script>

Add the component to your HTML page's BODY:

<!-- shows a user's profile -->
<github-user username="scottnath" fetch="true"></github-user>

Include a list of repositories with the profile

<github-user
  username="scottnath"
  fetch="true"
  repos='["scottnath/profile-components", "storydocker/storydocker"]'
></github-user>

Write your own content instead of fetching from GitHub:

<github-user
  username="scottnath"
  name="Meowy McMeowerstein"
  bio="Spending time purring and sleepin"
  followers="500000"
  following="2980"
  avatar_url="/MY_LOCAL_AVATAR_IMAGE.png"
  repos='[{
    "full_name":"scottnath/profile-components",
    "description":"Cool thing, does stuff",
    "language":"HTML"
  }]'
></github-user>

Using the unpkg distribution for a Repository

Add the repository script tag to your HTML page's HEAD:

<!-- add to HEAD -->
<script
  type="module" 
  src="https://unpkg.com/profile-components/dist/github-repository.js">
</script>

Add the component to your HTML page's BODY:

<!-- shows a repository's information -->
<github-repository 
  full_name="freeCodeCamp/freeCodeCamp" 
  fetch="true"></github-repository>

Add a theme to the repository component:

<!-- shows a repository's information -->
<github-repository 
  full_name="freeCodeCamp/freeCodeCamp" 
  fetch="true"
  theme="dark"></github-repository>

Write your own content instead of fetching from GitHub:

<github-repository 
  full_name="just-another/c-plus-plus-repo"
  language="C++"
  stargazers_count="123"
  forks_count="456"
  subscribers_count="789"
  description="This is meow meow."></github-repository>

Server Side Rendering (Astro example)

// GitHubUser.astro
---
import github from 'profile-components/github-utils';
const user = github.user;

const repos = JSON.stringify(['scottnath/profile-components', 'storydocker/storydocker']);
const userContent = await user.generateContent({
  login: 'scottnath',
  // a local profile image helps performance
  avatar_url: '/scott-nath-profile-pic.jpeg',
  repos
},true);
let userHTML = '<style>' + user.styles + '</style>';
userHTML += user.html(userContent);
---

<github-user>
  <template shadowrootmode="open" set:html={userHTML}>
  </template>
</github-user>

Where do the styles come from?

The best way to have the look n feel of an external site is to integrate their design language as much as possible. The GitHub components use the same source for styles as GitHub itself, the Primer Design System.

Primer Design System

https://primer.style/design/

"Primer is a set of guidelines, principles, and patterns for designing and building UI at GitHub."

Primer is the source for all of GitHub's root UI foundations (color text, and border-styles), iconography and basic UI patterns. The primer.style site is a massive resource for details about Primer and it's use by GitHub, so check that out if you have more Primer-specific questions.

Color themes

GitHub (via Primer) has two sets of themes, light and dark, and each set contains a few variations. Check out Primer's Storybook docs for colors to play around with the colors and see the different themes.

light: 'Light'
light_colorblind: 'Light Protanopia & Deuteranopia'
light_tritanopia: 'Light Tritanopia'
light_high_contrast: 'Light High Contrast'
dark: 'Dark'
dark_dimmed: 'Dark Dimmed'
dark_colorblind: 'Dark Protanopia & Deuteranopia'
dark_tritanopia: 'Dark Tritanopia'
dark_high_contrast: 'Dark High Contrast'

Primatives and iconography

These components are styled with variables generated from Primer's npm packages.

primer/primatives for colors, borders, and typography
primer/octicons is the source for all icons used on GitHub.
storybook docs for Octicons

Auto-captured styles

CSS variables and svg icons are pulled from Primer's npm packages. The generated variables are used to style the components. To make the styles easy to update when Primer makes changes, there is a suite of functions which pull the CSS variables and icons from Primer's NPM packages. The functions are detailed in this README about the Primer-utilities on profile-components.

Profile Components: display social profiles in native web components

Scott Nath — Tue, 10 Oct 2023 16:19:14 +0000

Profile Components is a set of web components with zero dependencies that display publicly-available profile information from various social networks. Currently two: GitHub and dev.to.

Being native web components, these can be used in any HTML page, framework-based site, or wherever you can use HTML. They are available via unpkg.com or you can add the NPM module to your project.

100% All Natural Features!

🔥 100% native web components

🚫 Zero dependencies

🔓 No api keys needed

🎨 New hotness CSS w/nesting & container queries

👷 DX: Separate files for Javascript, HTML, and CSS

✅ Native unit testing with node:test

♿ Fully accessible

🎁 Bonus! A sneaky SSR workaround for server side rendering!

tl;dr

use via unpkg.com:

<!-- add to HEAD -->
<script 
  type="module" 
  src="https://unpkg.com/profile-components/dist/github-user.js"></script>

<!-- shows a GitHub profile with fetched content for user `scottnath` -->
<github-user username="scottnath" fetch="true"></github-user>

install via NPM:

npm i profile-components

links to learn more:

🔥 Framework-free in 2023!

There have been a lot of feature drops across the major browsers this year, allowing us to more easily build shareable and reusable web components without any frameworks and without pre-or-post style-processors like Sass or PostCSS. This includes full implementation most of the original web components spec (🫗 r.i.p. HTML imports.) This year also includes lots of long-sought-after CSS features like container queries and nesting.

profile-components contain user interfaces without interactions or changing state making them simple to build cross-browser. As web components with unique styling, the isolation of styles inside the shadow dom is a benefit because each component uses a different set of root variables and styles. The style isolation allows these old school "widgets" to visually represent the social network they are displaying without affecting the rest of your page.

🚫 Zero dependencies

Any dependencies on this project are only for development. Meaning there are dependencies listed in devDependencies, but those are for testing and building the distributed components. The only external code which goes into the final build are the style variables and icons pulled from the social network's open source code.

🔓 Fetches live data - no api keys needed!

There are two options for sourcing content into these web components: fetch it live from the social's rest API or feed the component static data via the HTML attributes. You may also mix in your own data to overwrite what comes from the APIs - like if you wanted to have a local avatar image instead.

note: future components may need an API key(s), but for now, these use public, AUTH-free endpoints.

Fetching live data (`fetch="true"`)

<github-user
  username="scottnath"
  fetch="true"
></github-user>

...or... Skip fetching and use static data

<github-user
username="scottnath"
name="Meowy McMeowerstein"
bio="Spending time purring and sleepin"
followers="500000"
following="2980"
avatar_url="/cat-avatar.png"
></github-user>

🎨 Styles

Stylesheets are written in pure CSS and only use features which are supported in all major browsers.

Nesting

Stylesheets have their styles nested to reduce adding extra classes to the HTML and to make them easier to maintain.

/* uses `:has` to target the dl with a .post inside */
& dl:has(.post) {
  border-bottom: 1px solid var(--color-shadow);
  padding-bottom: 1em;

  /* any `dt` inside a `dl` with a `.post` inside */
  & dt {
    color: var(--color-light);
    font-size: var(--font-size-light);

Container Queries

Container queries allow the components to be responsive to their container, not the viewport - a more realistic usage scenario.

200px wide container

400px wide container

Colors and CSS variables sourced from the social network

To make the components feel like the sites they represent, they need to use the same colors, icons, and fonts. So to build these components, I sourced CSS variables from their open source repositories or modules. For GitHub, this means styles from the primer design system and for dev.to, which is built using the Forem community software, I sourced styles from the forem/forem repo on GitHub.

/* from the GitHub design-system, primer */
/* Light Theme */:host([data-theme="light"]) {
  --color-avatar-border: rgba(31,35,40,0.15);
  --color-border-default: #d0d7de;
  --color-canvas-default: #ffffff;
  --color-canvas-subtle: #f6f8fa;
  --color-fg-default: #1F2328;
  --color-fg-muted: #656d76;
  --color-fg-subtle: #6e7781;
  --color-fg-onemphasis: #ffffff;
  --color-fg-accent: #0969da;
  --color-fg-danger: #d1242f;
}
/* Light Protanopia & Deuteranopia Theme */:host([data-theme="light_colorblind"]) {
  --color-avatar-border: rgba(27,31,36,0.15);
  ...

👷 DX: Separate files for Javascript, HTML, and CSS

"Easy to maintain" requires a good Developer Experience (DX). To make these components easier to iterate on and update, they're built like a web page. This means separate HTML, Javascript and CSS files. While the development happens in separate files, the content from the various files is compiled into a single file for distribution.

I was inspired by Leon Eck's post Splitting Web Components into .ts, .html, and .scss files, which detailed a similar approach, using esbuild to compile the files into a single file. Esbuild is pretty simple to set up and configure, and it easily takes every imported file and converts it to an in-file variable.

HTML generation without frameworks or libraries

To maintain the zero dependencies goal, the HTML is living inside a Javascript file as a string returned from a method that accepts a single, JSDoc-documented parameter. This is not ideal, but allows using Javascript to generate the HTML without a framework or templating library like Lit or Handlebars. This is also what makes the SSR trick easy to pull off.

Javascript methods outside of the customElements class

Testing is paramount to easy maintenance. The JS methods used by these components perform fairly simple tasks which can be unit tested without the need for a browser. These web components get data using the Fetch API, which is fully implemented in both Node and browsers, making it easy to create mock responses and unit tests. They can also be used outside of the web component, so a separate file makes sense.

Separate stylesheets for styles and source variables.

There are separate sheets for maintainability. Generally, there is one auto-generated file with variables from the social network, one with stylesheet with global styles (since there are multiple components with unique styles combined), and one stylesheet per component. Generally the files are:

vars-[source].css: e.g. `vars-devto.css`.; Variables from the social network's open source code
global.css: Global style variables; Shared across all components
[component].css: e.g. `user.css` or `repository.css`; Styles specific to the component

These are then imported by the web component and exported with the HTML inside a <style> tag.

♿ Fully accessible

These components are tested using screen readers and AXE via Storybook. The HTML structure focuses on semantic HTML and when read aloud via screen reader, screen-reader-only content is available to provide context to the user.

For example, in the GitHub component, the header looks like this:

And the HTML is this:

<section aria-label="GitHub user profile" itemscope itemtype="http://schema.org/Person">
  <header>
    <span><span itemprop="memberOf">GitHub</span> user</span> 
    <span itemprop="alternativeName">scottnath</span>
  </header>

The styles convert the first span into the GitHub logo using CSS' mask-image property. This visually hides the text, but it's still available to screen readers, so the screen reader reads this to the user:

"GitHub user profile GitHub user scottnath"

note: The itemscope and other item[thing] attributes are from schema.org. These are used to structutre the data into microformats. This is more for SEO and content structure than for accessibility.

✅ Native Unit Testing with Node 20's node:test

Might as well go all in! Node 20 shipped with a native test runner, node:test. Fairly simple test runner, but it includes code coverage and has all the functionality needed to unit test these components.

The latest unit test runs are visible in the unit tests GitHub action workflow for profile-components

🎁 bonus! Server Side Rendering cheatcode!

// DevToUser.astro
---
import devto from 'profile-components/devto-utils.js';
const user = devto.user;

const userContent = await user.generateContent({
  username: 'scottnath',
},true);
let userHTML = '<style>' + user.styles + '</style>';
userHTML += user.html(userContent);
---

<devto-user>
  <template shadowrootmode="open" set:html={userHTML}>
  </template>
</devto-user>

A crazy-simple way to bulk-update NPM dependencies with GitHub's Dependabot

Scott Nath — Tue, 15 Aug 2023 18:00:37 +0000

This is the simplest way I've found to keep your NPM dependencies up-to-date. This will update all dependencies and devDependencies via automatically-generated pull requests AND you don't have to push files or leave the GitHub.com website. This works for monorepos too!

tl;dr

Go to your repo -> Insights -> Dependency graph -> Dependabot -> Enable Dependabot
Create a config file and add a group to it
Copy your GitHub Action secrets to Dependabot secrets

Prerequisites

Your repo's dependencies managed by NPM
Write permissions to your repository
No fear of beta-features

What is this?

I was stumped on how to enable Dependabot in Github after reading lots of docs and blogs about adding Dependabot to a repo. Each article detailed how to create the dependabot.yml file and the breakdown of it's data structure, but not the basics of turning it on. Then, I stumbled across the Enable Dependabot button. 🤦 So I figured I'd help someone else save some time.

The ability to create a single pull request containing all dependency updates is made possible by GitHub's newly implemented grouped version updates, which is a beta feature as of this writing. Normally Dependabot creates one PR for each dependency being updated.

Expected outcome:

Once-daily, Dependabot will check your repo's dependencies to see if newer versions exist
If new versions exist, Dependabot will create a pull request, updating every dependency which has a new version
The pull request will change relevant package.json and package-lock.json files
If you use GitHub actions, Dependabot's PR will run the same checks as other PRs

Note: Dependabot does a whole lot of other stuff and these instructions are specifically for the task of having Dependabot create one pull request whenever it finds one or more dependencies in your NPM repo which have an newer version.

Step 1: Enable Dependabot

Navigate to your repository on GitHub.com and then...

Trigger "Insights" link in the repo navigation
Trigger "Dependency graph" in the page menu
Trigger "Dependabot" in the Dependency graph page's tabs
Trigger the "Enable Dependabot" button

Step 2: Create dependabot.yml config file

The next page kinda looks the same as the last one! But now the "Enable Dependabot" button is replaced with a "Create config file" button

Trigger the "Create config file" button

Step 3: Edit the dependabot.yml file

Triggering "Create config file" brings you to the GitHub file editing interface. You will be adding the file at <repo-root>/.github/dependabot.yml. Setting up bulk management of your NPM dependencies requires three changes to the default dependabot.yml file, changing the package-ecosystem, the interval, and adding the group

Default content of the dependabot.yml file



# To get started with Dependabot version updates, you'll need to specify which

# package ecosystems to update and where the package manifests are located.

# Please see the documentation for all configuration options:

# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates

version: 2

updates:

  - package-ecosystem: "" # See documentation for possible values

    directory: "/" # Location of package manifests

    schedule:

      interval: "weekly"

Step 3.A Change the ecosystem to `npm`



updates:

  - package-ecosystem: "npm"

Step 3.B Change the interval to "daily"



<span class="na">schedule</span><span class="pi">:</span>
  <span class="na">interval</span><span class="pi">:</span> <span class="s2">"</span><span class="s">daily"</span>

Step 3.C Add the `groups` content

The groups configuration documentation is here. The StoryDocker repo has examples of a groups-enabled dependabot.yml file and a Dependabot-created PR

add groups right after the interval section from above
the group name is dev-dependencies, but the naming is flexible
the group name is used to create the PR title ("⬆️ Bump the dev-dependencies group with 32 updates" and the PR's branch from the Dependabot fork (dependabot/npm_and_yarn/dev-dependencies-b6aa4603c8)
this example uses a wildcard pattern so it will update all dependencies, but it's possible to narrow it to a subset of your deps



<span class="na">schedule</span><span class="pi">:</span>
  <span class="na">interval</span><span class="pi">:</span> <span class="s2">"</span><span class="s">daily"</span>
<span class="c1"># Create a group of dependencies to be updated together</span>
<span class="c1"># in one pull request</span>
<span class="na">groups</span><span class="pi">:</span>
   <span class="c1"># Specify a name for the group, which will be used </span>
   <span class="c1"># in pull request titles and branch names</span>
   <span class="na">dev-dependencies</span><span class="pi">:</span>
    <span class="c1"># Define patterns to include dependencies in the group </span>
    <span class="na">patterns</span><span class="pi">:</span> 
      <span class="c1"># Wildcard matches all dependencies </span>
      <span class="c1"># across the package ecosystem.</span>
      <span class="pi">-</span> <span class="s2">"</span><span class="s">*"</span>

The final file's contents



# (adjust comment to your liking)

version: 2

updates:

  - package-ecosystem: "npm"

    directory: "/"

    schedule:

      interval: "daily"

    groups:

      dev-dependencies:

        patterns: 

          - "*"

Step 4 - Copypasta your secrets to allow actions

Fun fact: Dependabot does not have access to any secrets you created for GitHub Actions.

The StoryDocker repo has a GitHub action which releases a PR-based deployment to Chromatic and that action requires a secret named CHROMATIC_PROJECT_TOKEN. This token is already configured at Settings -> Secrets and Variables -> Actions. To make this action work when Dependabot adds a PR from a fork of the repo, you need to have a duplicate token in the secrets for Dependabot.

Trigger "Settings" tab in repo navigation
Trigger "Secrets and variables" in the Settings page nav
Trigger "Dependabot" nav item to get the Dependabot's secrets page
Trigger "New repository secret" button to add a secret
Add your secret there, using the same secret name you used for the Actions secret

Step 5 - Read and merge PRs

There are ways to automate merging the PRs created by Dependabot, but I have trust issues, so I prefer to review the PRs and merge them myself.

Step 6 - PROFIT

Dependency management just got a whole lot easier. Go outside and touch grass!

Sharing UI Tests Between Javascript Frameworks

Scott Nath — Tue, 27 Jun 2023 18:01:57 +0000

How to share testing-library UI tests between Javascript frameworks with the same or similar components and use them in Storybook and unit testing.

tl;dr

Tests can be shared between Javascript components which have a similar HTML structure and/or a similar UX. The same shared tests can be used in both Storybook's play tests (Interaction testing) and Vitest unit tests.

Why share tests between Javascript Frameworks?

You have one or more applications which share UX, but which are built with different JS Frameworks
When converting an application from one JS Framework to another
Your company maintains a design system with multiple component libraries built with different JS Frameworks, but the same UX

Shared tests and how to use them

Staying D.R.Y. so... dig through part 1 - "What are shared tests", part 2 - "Sharing tests between components", and part 3 - "Sharing tests between Vitest and Storybook" to get the low-down on shared tests.

Why does this work? Are you a wizard?

As I've been writing this series, I realized it's an ode to the magic of Testing Library, which is built for testing UIs as a user would experience an app. This principle means Testing Library is not introduced to your UI until after it has already rendered...which means Testing Library is navigating a DOM just as a user would...and users do not know or care what framework you used to build your UI, just that it works as expected.

Testing Library is the real MVP here.

What are we testing this time?

This article shows a set of shared-tests for testing a Counter component rewritten across multiple Javascript frameworks. We'll be using the components found in the Astro Web Framework's example: Kitchen Sink (Multiple Frameworks). These are written in Preact, React, Svelte, SolidJS, and Vue. This Astro microfrontend example is fantastic in that it demonstrates how the Astro Web Framework can have multiple Javascript frameworks running on the same page at the same time.

Fun fact! This is the codebase I used to demonstrate Storybook presenting multiple frameworks in the DevOps for Multi-Framework Composition Storybooks series.

What is the Counter component?

The Counter component is a simple component which displays a number and has two buttons: one to increment the number and one to decrement the number. Each framework version has the exact same UX and HTML structure, with slight variations due to the syntax of the framework.

HTML for PreactCounter.tsx:

<div class="counter">
  <button onClick={subtract}>-</button>
  <pre>{count}</pre>
  <button onClick={add}>+</button>
</div>

HTML for ReactCounter.tsx:

<div className="counter">
  <button onClick={subtract}>-</button>
  <pre>{count}</pre>
  <button onClick={add}>+</button>
</div>

HTML for SvelteCounter.svelte:

<div class="counter">
  <button on:click={subtract}>-</button>
  <pre>{count}</pre>
  <button on:click={add}>+</button>
</div>

HTML for VueCounter.vue:

<div class="counter">
  <button @click="subtract()">-</button>
  <pre>{{ count }}</pre>
  <button @click="add()">+</button>
</div>

Rendered HTML for all Counter components is the same

All components output the same HTML, which is the voodoo which makes this possible. Same HTML? Same tests.

<div class="counter">
  <button>-</button>
  <pre>0</pre>
  <button>+</button>
</div>

The shared tests

1. Getting the elements

The first step? Query the DOM for the elements we want to test.

We need:

the + (plus) button
the - (minus) button
the pre element which contains the count
the container, which is a div with a class of counter

Using Testing Library's queries, we'll create an object by parsing the rendered HTML. In this method, canvasElement is the live DOM rendered by the framework.

import { within } from '@storybook/testing-library';
/**
 * Extract elements from an HTMLElement
 */
export const getElements = async (canvasElement) => {
  // `within` adds the testing-library query methods
  const screen = within(canvasElement);

  return { 
    screen,
    canvasElement,
    // `querySelector` used here to find the generic `div` container
    container: await canvasElement.querySelector('.counter'),
    // `queryByRole` finds each button, using `name` to search the text
    minus: await screen.queryByRole('button', { name: /-/i }),
    // using `queryBy` instead of `getBy` to avoid errors in `getElements`
    plus: await screen.queryByRole('button', { name: /\+/i }),
    // `querySelector` again as `pre` has no role and contains variable content
    count: await canvasElement.querySelector('pre'),
  };
}

This returns an object with our elements:

{
  screen: {object with testing-library query methods},
  canvasElement: <the-initial-html-element,unchanged>,
  container: <div class="counter">...</div>/{and query methods},
  minus: <button>-</button>/{and query methods},
  plus: <button>+</button>/{and query methods},
  count: <pre>0</pre>/{and query methods},
}

2. Testing the initial rendered elements

The Counter is a simple component that has no props, so this method just ensures the elements are present and the counter starts at 0. ensureElements should be called before interaction tests to ensure the initial state of the component is what is tested.

The elements arg is the object returned from getElements.

/**
 * Ensure elements are present and have the correct attributes/content
 */
export const ensureElements = async (elements) => {
  const { minus, plus, count } = elements;
  // `.toBeTruthy` ensures the element exists
  await expect(minus).toBeTruthy();
  await expect(plus).toBeTruthy();
  await expect(count).toBeTruthy();
  // ensures the count starts at zero
  await expect(count).toHaveTextContent('0');
}

3. Testing keyboard navigation

For keyboard-only users, we'll need to ensure the buttons are focusable and in the expected order. We test navigation separate from interactions to keep the testing methods focused on one type of user experience at a time.

The component only has two focus-able elements - which are the buttons.

/**
 * Test keyboard interaction
 */
export const keyboardNavigation = async (elements) => {
  const { minus, plus, container } = elements;
  // tab within the container
  await userEvent.tab({ focusTrap: container });
  await expect(minus).toHaveFocus();
  // `pre` is the next element, but it's not focusable
  await userEvent.tab({ focusTrap: container });
  await expect(plus).toHaveFocus();
}

4. Testing keyboard interactions

For testing the interaction of the buttons, we'll be adding or subtracting to the number in pre. We cannot ensure the order the testing methods will be used, which means elements.count might not be 0. This test method will start by getting whatever number is in elements.count and use that number to test the expected addition or subtraction result.

/**
 * Test keyboard interactions
 */
export const keyboardInteraction = async (elements) => {
  const { minus, plus, count, container } = elements;
  // could be any number
  const initCount = parseInt(count.textContent);
  // navigation unimportant here, so we'll just focus on the button
  await plus.focus();
  // with the `plus` button in focus, hitting `enter` should increment
  await userEvent.keyboard('{enter}');
  await expect(parseInt(count.textContent)).toBe(initCount + 1);
  await userEvent.keyboard('{enter}');
  await expect(parseInt(count.textContent)).toBe(initCount + 2);
  await minus.focus();
  await userEvent.keyboard('{enter}');
  await expect(parseInt(count.textContent)).toBe(initCount + 1);
  await userEvent.keyboard('{enter}');
  await expect(parseInt(count.textContent)).toBe(initCount);
  await userEvent.keyboard('{enter}');
  await expect(parseInt(count.textContent)).toBe(initCount - 1);
  // reset user focus to nothing
  await minus.blur();
}

5. Testing mouse interactions

Same as keyboard interactions, but with mouse clicks instead of keyboard events.

/**
 * Test mouse interaction
 */
export const mouseInteraction = async (elements) => {
  const { minus, plus, count } = elements;
  const initCount = parseInt(count.textContent);
  await userEvent.click(plus);
  await expect(parseInt(count.textContent)).toBe(initCount + 1);
  await userEvent.click(plus);
  await expect(parseInt(count.textContent)).toBe(initCount + 2);
  await userEvent.click(minus);
  await expect(parseInt(count.textContent)).toBe(initCount + 1);
  await userEvent.click(minus);
  await expect(parseInt(count.textContent)).toBe(initCount);
  await userEvent.click(minus);
  await expect(parseInt(count.textContent)).toBe(initCount - 1);
  // reset user focus
  await minus.blur();
}

Using the shared tests in Storybook

Now that we have our shared tests, we can use them in Storybook. (see part 1). Below is the React story file, see the full set of framework-specific stories here. The test methods are broken out into step functions for legibility in the Storybook UI, but they are not required.

// ReactCounter.stories.js
import { ReactCounter } from '../../src/components/ReactCounter';
import { getElements, ensureElements, mouseInteraction, keyboardNavigation, keyboardInteraction } from '../../src/components/tests/counter.shared-spec';

export default {
  title: 'React',
  component: ReactCounter,
};

export const React = {
  play: async ({ args, canvasElement, step }) => {
    const elements = await getElements(canvasElement);
    step('react tests', async () => {
      await step('ensure elements', async () => {
        await ensureElements(elements);
      });
      await step('mouse interaction', async () => {
        await mouseInteraction(elements);
      });
      await step('keyboard navigation', async () => {
        await keyboardNavigation(elements);
      });
      await step('keyboard interaction', async () => {
        await keyboardInteraction(elements);
      });
    });
  },
};

Using the shared tests in Vitest unit tests

They also drop-in to our unit tests. (see part 3). Below is the React unit test file, see the full set of framework-specific unit tests here. The magic here is in the render function. Each framework has a different one, but once Vitest renders it, the resulting output of all frameworks is understood by the shared tests.

note: The separate it functions are required for now for React, which was having some issues isolating the user interactions when they are all ran together. The it functions are not required for all frameworks, but since they give legibility anyway, we'll keep them.

// Vue.spec.tsx
import { render } from '@testing-library/vue';
import { describe, it, assert, expect } from 'vitest';

import VueCounter from '@/components/VueCounter.vue';
import { getElements, ensureElements, mouseInteraction, keyboardNavigation, keyboardInteraction } from '@/components/tests/counter.shared-spec';

describe('Vue', () => {
  describe('Counter', () => {
    it('ensure elements', async () => {
      const rendered = render(VueCounter);
      const elements = await getElements(rendered.container);
      await ensureElements(elements);
    });
    it('mouse interaction', async () => {
      const rendered = render(VueCounter);
      const elements = await getElements(rendered.container);
      await mouseInteraction(elements);
    });
    it('keyboard navigation', async () => {
      const rendered = render(VueCounter);
      const elements = await getElements(rendered.container);
      await keyboardNavigation(elements);
    });
    it('keyboard interaction', async () => {
      const rendered = render(VueCounter);
      const elements = await getElements(rendered.container);
      await keyboardInteraction(elements);
    });
  });
})

Wrapping up

Writing sharable user-experience-based tests for your UI is really about planning for the future.

The NewHotness™ UI framework is being built right now and in two years that React component you put your soul into is going to be deleted in lieu of the shiny thing. That doesn't mean your UX needs to change ... or your Design ... or your tests. Just do the facelift next time.

Efficiency in all things, and productivity will follow.

DEV Community: Scott Nath

How about a JSON Resume web component with configurable microdata?

tl;dr

snippet:

Prerequisites

Quick primer: How we got here

How to implement <json-resume> in node

install dependencies

Usage

How to implement the <json-resume> web component in HTML

include lit dependencies

Add jsonresume-component

Using just a gist id

Conclusion

Make your resume SEO friendly using JSON Resume with microdata

tl;dr

Prerequisites

Quick Tech Primer

What is structured data, microdata, Schema.org vocabulary?

Cliff notes:

What is JSON Resume?

JSON Resume example

What is jsonresume-theme-microdata?

Explainer: adding structured data to a JSON Resume theme

Step 1: Look at two similar, but different sections

Step 2: Write semantic HTML which matches the resume data hierarchy

Step 3: Add microdata, using Schema.org types

Step 4: Validate your microdata to output the data

Other fun data structues that were added

basics.profiles is all your social network profiles

I added specificity with skills to allow itemtype

This is long, let's stop

How to Boost SEO by Enhancing HTML with Microdata

tl;dr

Prerequisites

What is all this technology?

What is structured data?

What is the semantic web?

What is Schema.org? What is their vocabulary?

Schema.org type inheritance

How I chose microdata to document my content

JSON-LD

Microdata (spoiler alert: I chose this)

How to add microdata to HTML

itemscope and itemtype

itemprop

What data do we know so far?

itemprop which is an itemscope

What do we know from the above HTML?

How to parse-out and validate your microdata

Google Rich Results Test

Schema.org validator

Not The End

Storybook setup: Virtual Screen Reader with Web Components

tl;dr

Prerequisites

What is this article about?

1. Problems testing web components

Problem A: screen doesn't look into the shadowroot

Fix: npm i shadow-dom-testing-library

Problem B: userEvent can't traverse the shadowroot

Fix: npm i @guidepup/virtual-screen-reader

2. How to test web components in Storybook Interaction Tests

Step 2a. install shadow-dom-testing-library

Step 2b. use within from shadow-dom-testing-library (I alias it to shadowWithin)

Step 2c. use shadow-dom-testing-library screen queries, then test

3. How to test web components with virtual-screen-reader

Step 3a. install virtual-screen-reader (VSR)

Step 3b. import it into your stories

Step 3c: once you have your main Shadow container, give it to VSR

Conclusion

Simple setup: Virtual Screen Reader in Storybook

tl;dr

What is the Virtual Screen Reader?

How does the screen reader interpret a chunk of HTML?

How to set up your Storybook instance to use the Virtual Screen Reader

How to write a Storybook integration test that uses the Virtual Screen Reader

Import the library into your stories file

Write the story and integration test

Conclusion

How to implement `<json-resume>` in node

How to implement the `<json-resume>` web component in HTML

include `lit` dependencies

Using just a `gist` id

What is `jsonresume-theme-microdata`?

I added specificity with `skills` to allow `itemtype`

How I chose `microdata` to document my content

`itemscope` and `itemtype`

`itemprop`

`itemprop` which is an `itemscope`

Problem A: `screen` doesn't look into the shadowroot

Fix: `npm i shadow-dom-testing-library`

Problem B: `userEvent` can't traverse the shadowroot

Fix: `npm i @guidepup/virtual-screen-reader`

Step 2b. use `within` from `shadow-dom-testing-library` (I alias it to `shadowWithin`)

Fetching live data (`fetch="true"`)