DEV Community: Michael Puckett

Show DEV: Open your favorite website in a standalone window on iPhone

Michael Puckett — Mon, 27 Jan 2020 07:37:43 +0000

Check it out here: https://standalone-web-wrapper.firebaseapp.com

Did you know can use the share sheet in Safari and select "Add to Home Screen" to save an app-like icon on the home screen? This functionality has existed pretty much since the iPhone launched.

Personally, I've not used this feature much over the years because it always just launched a fresh instance of the site in a new tab in Safari.

In the last few months, however, I noticed that some websites will open in their own window, not in Safari. Opening the site again will return you to that window, at the same place you left off.

Wow! A much better experience.

But not every website has opted in to this standalone experience. For good reason -- you lose your native browser frame with all the navigation buttons. This isn't so bad most of the time, because you can still swipe from the edge of the screen to go back/forward, just like in Safari.

The trick is to add a manifest.json file with the "display" property set to "standalone".

For me, I wanted the New York Times to work this way. I suspect that news sites might not be opting in because ad blockers still apply to the standalone experience, but anyway I'm not a fan of the NYT native app.

iFrames won't work due to cross-site restrictions, so I set up a meta redirect on the page that will instantly show the desired site. This will show the site name at the top of the page, which wastes a little bit of space, but allows access to Reader View.

I also made the app icon and app icon name customizable.

Let me know what sites you use it for!

https://standalone-web-wrapper.firebaseapp.com

https://github.com/michaelcpuckett/standalone-web-wrapper

How and Why I Avoid Magic Numbers in CSS

Michael Puckett — Wed, 22 Jan 2020 18:18:27 +0000

Introduction

There's a great article called Code smells in CSS by Harry Roberts that first introduced me to the concept of magic numbers in CSS.

When Harry wrote the article in 2012, there weren't too many great solutions for dealing with these problems. But since then, we've gotten Grid and Flex layout, along with CSS custom properties (variables!) so we can now avoid many of the pitfalls.

The basic idea of magic numbers is that writing styles with arbitrary numbers like the following is brittle and unmaintainable:

.container {
    height: 250px;
}
.box1 {
    padding-left: 4px;
    position: relative;
    top: 11px;
}
.box2 {
    padding-left: 2px;
    padding-right: 4px;
    position: relative;
    top: 7px;
}

For one thing, what's so special about these numbers? Even if there were comments, you might not know all that they're doing unless you look at the markup, or how they relate to the other numbers.

Let's say .box1 and .box2 are next to each other.

Focusing on .box2, let's first look at its padding -- 2 on the left and 4 on the right. The left padding is defining the space between the components, and the right side in defining the outer right margin of the page. That's not very conducive to composability. What if we wanted to reverse the order? We would have to sift out the 2 and 4, reverse them, and apply them to the other component. It would be better if the container could manage these details.

The 11px and 7px top values here are vertically centering the boxes inside their container. That's precarious, in case the content changes. There are better ways to achieve this.

Grid Layout

In the example above, with one padding defining the space between components, and the other defining the page margin, we can leave all those details to the grid container. The container gets the following:

.container {
    display: grid;
    padding: 0 4px;
    grid-gap: 2px;
    align-items: center;
    grid-auto-flow: column;
    height: 250px;
}

Now the interior components don't need padding.

Notice also how Grid supports align- and justify- properties that can do the work of centering and aligning, so we can lose the 11px and 7px top value altogether.

(Flexbox also has these alignment properties, but the support for gap is still limited, unfortunately.)

Custom Properties

Any time that we still need to use specific numbers, we can replace them with CSS custom properties: --page-padding: 4px and --gap-width: 2px

Note: I think it's fair to be cautious with a statement like this, and to be conservative when applying this rule in practice. There are potential performance considerations when using CSS custom properties all over the place. But in my experience, the bottleneck in rendering a page hasn't been the CSS.

In keeping with this, we can keep the 250px height as-is, because it's unique.

Similarly, --page-padding might be a better candidate for being a custom property than --gap-width, for example. If the gap between the components is unique, keeping it 2px might be fine.

But what if, when it was originally conceived by the designer, the space between the components was designed to be half of the page padding? If so, you might want to preserve the relationship in case the page padding changes in the future.

You can use calc for this purpose:

.container {
    display: grid;
    padding: 0 var(--page-padding);
    grid-gap: calc(var(--page-padding) / 2);
    align-items: center;
    grid-auto-flow: column;
    height: 250px;
}

Now we're down to just one magic number, and one appropriately-named custom property. In my opinion, that's much easier to reason about and the intent of the code is clearer.

I found a similar article on Dev that goes even more in depth if you want to check it out: https://dev.to/adrianbdesigns/mastering-css-magic-numbers-2297

✌️

JS DOM API for Beginners: Removing all elements with a certain class

Michael Puckett — Sun, 19 Jan 2020 00:14:52 +0000

If you're familiar with CSS 🎨, then you can use the same selector syntax to target all matching elements in JavaScript 💻.

window.document.querySelectorAll('.box')

Notice the selector is the same in CSS, representing elements with a box class.

This returns a special kind of array-like object for DOM elements called a NodeList.

What if we wanted to remove all the elements with a box class?

One way is to call .remove() on each of the elements. To do this, we need to loop over each element.

NodeLists aren't technically arrays, so they don't have a .forEach() method 😫 but they are iterable, meaning they can be converted to regular arrays 🤓

Here's the syntax for the conversion:

[...window.document.querySelectorAll('.box')]

Now we can use .forEach() to remove each item:

[...window.document.querySelectorAll('.box')].forEach(node => node.remove())

It can be any valid CSS selector, such as .boxes li.box.circle[aria-selected="true"]

You could also use .map() or .reduce() on a list of DOM elements this way.

🤟

Handling Overscroll in a Web App with Header and Footer on iOS

Michael Puckett — Tue, 14 Jan 2020 13:53:25 +0000

Introduction

Web pages, originally designed as documents, want to scroll. And since at least the iPhone, web pages can "overscroll" beyond their bounds, based on touch gesture inertia. In fact, every scrollable area on a web page viewed on an iPhone gets this extra "bouncy" scrolling behavior.

Nested scrollable areas "chain" with their parents (including the page itself), so that if you reach the top of a nested scrollable area, the closest scrollable parent will take over scrolling.

However, some app-like web experiences may wish to opt-out of this document-flow/scroll-chaining paradigm. They need to present a fixed scrollable main content area with a fixed header and footer, which goes against the browser's nature.

The main content area, if scrolled, could trigger the entire page to start scrolling unexpectedly. Or, if the page is fixed positioned, nothing will happen and the user will get "trapped" scrolling an unscrollable web page for a few seconds.

To opt out of this paradigm in any browser except Safari, you can use a new CSS property called overscroll-behavior. Setting overscroll-behavior: contain will prevent scroll chaining.

Handling iOS Safari

Polyfilling this CSS property in Safari is pretty tricky.

For non-scrollable elements, you can prevent scroll chaining by simply turning off touch gestures. You can do that with a CSS property that is supported by Safari: touch-action: none.

But for scrollable elements, JavaScript will be required.

Remember that scroll chaining occurs when you reach the bounds of the element. So we need to ensure that the user is never able to fully scroll to the top or bottom. Doing this the wrong way can cause UX problems, because the user will clearly be fighting against the default inertia scroll.

So here's the trick:

Create an inner element that is at least 3px taller than the size of its scrolling parent, to force the area to get the overscroll behavior.
Immediately set the scroll position to 1px to prevent scroll chaining when scrolling up
With JavaScript, catch when the scroll position is exactly 0 or exactly at the bottom. After a requestAnimationFrame, set the scroll position to 1px from either the top or bottom.

The container will still get the inertia scroll (the user won't have to fight it) but it won't trigger scroll chaining.

Here's the JavaScript function I have:

this.addEventListener('scroll', async handleScroll() {
  await new Promise(resolve => window.requestAnimationFrame(resolve))
  const {
    scrollTop,
    scrollLeft,
    scrollHeight,
    clientHeight
  } = this
  const atTop = scrollTop === 0
  const beforeTop = 1
  const atBottom = scrollTop === scrollHeight - clientHeight
  const beforeBottom = scrollHeight - clientHeight - 1

  if (atTop) {
    this.scrollTo(scrollLeft, beforeTop) 
  } else if (atBottom) {
    this.scrollTo(scrollLeft, beforeBottom)
  }
}

Conclusion

Integrating this into an already-existing app probably won't be easy, since this may necessitate restructuring a lot of the page.

Hopefully Safari will implement the overscroll-behavior CSS property soon, so we can avoid this mess!

Here's the WebKit issue:

https://bugs.webkit.org/show_bug.cgi?id=176454

If you've ever faced this challenge, add yourself to the CC list on that issue to indicate that this is important to you.

Is there code review site I can scroll through on my phone?

Michael Puckett — Mon, 13 Jan 2020 09:18:15 +0000

I love scrolling Dev.to. It has replaced some other social apps on my phone because of the substantive feedback and discussion.

The blogging aspect is great but wouldn’t it be nice if there were an interface just for code reviews, where you can comment on lines of code?

This could be a good addition to Dev.to eventually.

But I’m wondering if there is a site like that already?

If not, should I build it? 🤓

How can I get rendered innerHTML that includes Shadow DOM?

Michael Puckett — Sun, 05 Jan 2020 05:48:51 +0000

I'm using web components with shadow DOM on a project and I would like to copy the innerHTML of the page as rendered.

I think I need to write a function loops over each DOM node and gets either the shadow DOM children if available or else the light DOM children.

node.shadowRoot ? node.shadowRoot.children : node.children

I've been having trouble getting it right, and I'm surprised I can't find anything on Google.

How I Built a Dark Mode PWA without JS Libraries in 24 Hours

Michael Puckett — Sat, 04 Jan 2020 15:57:40 +0000

Motivation

I decided to give my Hacker News reading experience a facelift.

First and foremost, I wanted Dark Mode!

Second, I wanted to be able to "install" it on my iPhone's homescreen, so that it runs in its own process, and not in Safari. (Dev.to does this natively, kudos!)

I also wanted to build a project over break that would let me explore new web standards. I wanted to commit to using the latest tools of the native web platform, so I wouldn't use any JS libraries or create a build process. I also wouldn't worry about any browsers other than the ones I use every day -- latest Safari and Chromium.

Before I started, I also got the idea to make it a little more functional for myself, so that it loads to the top comment along with the headline.

Finally, I wanted to timebox it to 24 hours.

Step #1: Loading Data

This was the easy part. The Hacker News API has an endpoint that provides JSON data of the stories. No authorization, no setup, just load the data.

Since I wasn't limited by browser support, I could safely use fetch, Promises, and async/await:

const storyIDs = await fetch(`https://hacker-news.firebaseio.com/v0/topstories.json`).then(res => res.json())

const stories = await Promise.all(storyIDs.slice(0, 25).map(id => fetch(`https://hacker-news.firebaseio.com/v0/item/${id}.json`).then(res => res.json())))

Step #2: Templating and Dynamic Data

Each of the loaded stories would be rendered as an instance of a web component.

There are basically 3 types of data to consider when you use a web component:

Named slots
Custom properties
Custom attributes

I ended up not having a need for custom attributes.

Let's start by looking at the template for a top-story element:

  <template>
    <article class="top-story">
      <span class="top-story-submitter">
        <slot name="by"></slot>
      </span>
      <div class="top-story-content">
        <a class="top-story-main" href="">
          <h3 class="top-story-headline">
            <slot name="title"></slot>
          </h3>
        </a>
        <slot name="top-comment"></slot>
      </div>
    </article>
  </template>

I'm using named slots where I want the dynamic content to go. This will be on the Shadow DOM side.

Anything in the Light DOM side with a matching slot attribute will be injected into the rendered template.

So for the dynamic data, I needed to convert each JSON data property received from the API into an HTML element with a slot attribute. I'm adding the JSON data to the web component as custom properties, then letting setting those properties trigger the creation of the elements with a slot attribute.

  stories.forEach(story => {
    if (story) { // can be null
      const element = window.document.createElement('top-story')
      window.document.body.append(element)
      Object.assign(element, story)
    }
  })

Object.assign here is setting these directly on the element, so we can set those up to be custom properties that react to changes.

In the web component, I have a helper function to do the property conversion to slots, and I have a setter for each of the properties:

window.customElements.define('top-story', class extends HTMLElement {
  constructor() {
    super()
  }
  setSlot(slot, value) {
    if (!this.querySelector(`[slot="${slot}"]`)) {
      const element = window.document.createElement('data')
      element.setAttribute('slot', slot)
      this.append(element)
    }
    this.querySelector(`[slot="${slot}"]`).innerHTML = value
  }
  set text(value) {
    this.setSlot('text', value)
  }
  ...
}

Now, if I change the data on the component, the slot will also update on the Light DOM side, which will update in place in the rendered Shadow DOM.

I can also use the setters to do other kinds of work. I want to embed another web component for the Top Comment inside this one, so I won't use my setSlot helper function. Instead, in the setter, I set up that component the same way I set up this one. This is also where I updated the href attributes on the links.

Step #3: Code Splitting / Imports

Typically I use webpack for converting my projects to ES5 and concatenating into a single JS file.

Here I'm using native JS imports to add the split-up files. Add that to the fact that the base markup is in its own web component, and my HTML file ends up being pretty light:

  <body>
    <app-screen></app-screen>
    <link rel="stylesheet" href="./styles.css">
    <script type="module">
      import './imports/fetcher.js'
      import './imports/AppScreenTemplate.js'
      import './imports/AppScreen.js'
      import './imports/TopCommentTemplate.js'
      import './imports/TopComment.js'
      import './imports/TopStoryTemplate.js'
      import './imports/TopStory.js'
    </script>
  </body>

Step #4: Dark Mode

Although I always use Dark Mode, I wanted to use the native CSS media query that detects Dark Mode in the system settings, in case someone else was used to Light Mode instead:

  @media (prefers-color-scheme: dark) {
    body {
      background: black;
      color: white;
    }
  }

Step #5: PWA Installation

One of the most important aspects of all this was to make Hacker News run like a native app, in its own window and not in Safari. That way my scroll state would be preserved.

This is actually pretty simple for iOS:

  <meta name="apple-mobile-web-app-capable" content="yes" />

To make this more compliant with other browsers, including Chromium Edge, which I have been using, I also added a manifest.json file:

{
  "name": "Hacker News PWA",
  "short_name": "HN",
  "theme_color": "#CD00D8",
  "background_color": "#000000",
  "display": "standalone",
  "orientation": "portrait",
  "scope": "/",
  "start_url": "/",
  "icons": [{
    "src": "/icons/icon-512x512.png",
    "type" : "image/png",
    "sizes": "512x512"
  }]
}

Challenge #1: Dates!

I ended up removing all dates from the project for now. I'm used to using a library such as moment.js or date-fns, and the native functions would sometimes show undefined or have other problems! I think for the final product, if I continue with it, I will pull in one of those libraries.

Challenge #2: Time Constraints

I had planned on having the comments (and possibly even the story if iframe embed is supported) show up in a modal drawer that overlays the rest of the content. This might still happen, but it's outside the 24-hour timebox.

It also isn't quite a full-fledged PWA with service workers. I need to do some work on automatically refreshing content.

Conclusion

I had a great time working on this, and I have started using it whenever I want to check Hacker News. You might enjoy it too.

Install it as an "Add to Homescreen" app from Safari:

http://hn-pwa-1.firebaseapp.com/

Contribute:

https://github.com/michaelcpuckett/hn-pwa-1

Final Result:

Show DEV: Hacker News “Add to Homescreen” Web App

Michael Puckett — Fri, 03 Jan 2020 05:07:00 +0000

https://hn-pwa-1.firebaseapp.com/

Killer features:

It shows the top comment
Dark mode! Or light mode! Depending on your system settings.

If you’re on an iPhone, add it to your home screen. It will open in its own window, not in Safari.

I was able to pull this off easily by adding the apple-mobile-web-app-capable meta tag.

This is what I was able to do in 24 hours. I’ll be working to make it an installable app soon.

An Inclusive Cross-Device Testing Checklist

Michael Puckett — Thu, 02 Jan 2020 19:48:56 +0000

Here’s my web compatibility checklist that includes comprehensive accessibility testing.

Physical Devices

I’m testing with the following real devices:

MacBook
iPhone with a notch
Pixel with a notch

That’s it! I’m able to use macOS Bootcamp to dual boot to native Windows 10.

You can, of course, emulate both iOS and Android. This is useful for inspecting layouts without the notch. But an emulator sometimes doesn’t behave quite the same way.

If you are on a Windows or Linux PC, there won’t be a way to test any proprietary Apple software. I’ll look at how to emulate Safari later — WebKit is open source.

Browsers

You should look at your analytics to see what kind of coverage you want to support for older browsers.

In most cases, unless I want to charge more for the engineering time, the following list is my baseline.

I get to use ES6, CSS Grid, CSS variables, Web Components, and other modern features.

When testing across browsers, I usually like to have a common set of workflows using various amounts of data.

The list:

Latest Chrome (79)
- macOS
- Windows
- Android
N-10 Latest Chrome (69)
- macOS
- Windows
- Android
Latest Firefox (71)
- macOS
- Windows
- Android
Latest Firefox Enterprise (ESR 68)
- macOS
- Windows
Latest Desktop Safari (13)
- macOS
N-1 Latest Desktop Safari (12)
- macOS
Latest Mobile Safari (13)
- iOS
N-1 Latest Mobile Safari (12)
- iOS

What about Internet Explorer and Edge? IE is present but buried in Windows 10, and Edge Beta with Chromium is available for download. It will soon replace the existing Edge. If you have a high number of Edge users, add it to the browser support list, or consider providing a download link to Edge Beta.

If you want to emulate Safari on Windows, you’ll need to install Ubuntu from the Windows Store. You’ll need to install an xServer emulator and have it running. Then run apt-get update && apt-get install epiphany-browser in the Ubuntu shell. Add export DISPLAY =:0 to your bash profile. Then you can run epiphany-browser to test WebKit on a PC.

Assistive Technologies

Are you testing for accessibility? You should be! People with disabilities, such as blind people, need to be able to interact with every app and website. That’s done with semantic HTML and ARIA.

All operating systems now come with a screen reader that interacts with the underlying Accessibility API. You can use ARIA to modify the Accessibility API.

When using a screen reader, you use a keyboard to navigate between items using a virtual cursor (essentially the same as the focus cursor) and interact with the web page. There is usually a developer setting to show the text on screen as it would be spoken.

Here are the assistive technologies I test with:

Windows Narrator (Windows 10)
VoiceOver (macOS and iOS)
TalkBack (Android)
NVDA (Windows 10) is a free download

Manual and Automated Accessibility Testing

I test the markup at various stages (adding items to cart, deleting items from cart, etc) using three helpful developer tools:

validator.nu HTML/ARIA Validator
axe Chromium Extension
Accessibility Insights Chromium Extension - This will walk you through many different accessibility scenarios

Conclusion

Of course, none of the time spent testing comes for free. Make sure you work with your client or project manager to integrate your inclusive testing plan into the overall project plan.

So, did I miss any? Or go overboard? Tell me about your testing plan!

When to use CSS Grid and when to use Flexbox for Multiline Layout

Michael Puckett — Wed, 01 Jan 2020 17:22:07 +0000

Introduction

Flexbox and CSS Grid are both powerful layout technologies built into CSS. They have many overlapping abilities. For most tasks, such as vertical centering, I could reach for either one. In some cases, one or the other is the only way to get the job done.

Is one better than the other, given the current state of web standards?

In the event that either Grid or Flexbox would work, I’m now reaching for Grid. I’ll explain why after discussing some various multiline scenarios.

Gap

Soon there will be a uniform way to apply consistent spacing between child items, as defined by the parent: gap. So, gap: 5px will not affect the outside margin, only the spacing between interior items.

This was inspired by and will eventually supersede Grid’s grid-gap property. Unfortunately, the only way achieve the same result on multiline (wrapping) items in Flexbox using any browser other than Firefox is the Negative Margin Hack. This is where all the child items get a margin equal to half of the gap. Then to account for the extra space on the outside, the container gets a margin of the same value multiplied by -1. You can only use :first-child and :last-child on the items to account for the extra space when you have a single row (non-wrapping flex container).

For multiline grid containers, just apply a grid-gap.

Winner: Grid, but hopefully gap for flex layout will soon be added to Chrome and Safari.

Consistent Sizing vs Automatic Sizing

If you have tracks in both directions (a multi-column and multi-row layout) then your choice depends on the widths of the child items relative to others.

If you want all the items to line up evenly and stack vertically, use Grid.

If you want the items to retain their natural width and not line up vertically, use Flexbox.

The code for Grid requires a repeat() function to be defined on the container’s grid-template-columns property. The repeat function accepts two values. The first for our purpose is either auto-fill or auto-fit. And the second is a minmax function, which accepts a value with a fixed unit, and another fixed or relative value.

All together it might look like this:

grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));

This will give each item a base width of 200px that will scale up as needed.

For Flexbox, just add flex-wrap: wrap.

Winner: Depends on the use case, but Flexbox is a lot simpler. 🙃

Container Control vs Item Control

There may be some cases — such as the boundary between two components — where you only want to modify the parent container’s CSS or the children’s CSS.

If you have control over the parent element, use Grid, which defines the children with grid-template-* and grid-auto-*.

If you have control over the child elements, use Flexbox, where the children define their own flex-basis.

If you must use Flexbox for some other reason, you can still define a CSS variable on the parent that will be inherited by the children.

Winner: Depends on the use case, but Flexbox gets a point for versatility. Personally I like having the ability to control all the items on the parent in one place whenever possible, so Grid gets a point too.

Nested Layout

One killer CSS Grid feature that’s only landed in Firefox is subgrid. This allows a child grid item to define its grid children according to the same track definition as the top level parent.

If you had a set of items that internally are split into a top and bottom section with variable amounts of content, you could define two repeating auto grid tracks at the top level. Then the middle-level child items take up two each of the repeating rows. Then they pass down the track definition so that the top part receives one auto track and the bottom part receives the other. Now, across the items, the split will be at the same place, so internally they all line up.

Winner: Grid, but you’ll still have uneven layouts in any browser other than Firefox.

Conclusion

For most other use cases, especially when working with one track in one direction with no spacing between items, I would be comfortable using either. That goes for situations where you need vertical centering and relative sizing.

But I find it easier to reason about how the children should be laid out when I’m defining them in one place on the parent element — so Grid wins out most of the time.

Overall Winner: Grid, but know its limitations!

As I mentioned, Firefox has taken the lead in this area. Please ⭐️ / CC yourself on these issues on Chromium and WebKit to make both Flexbox and Grid more powerful in the future!

gap for Flexbox (Chromium): https://bugs.chromium.org/p/chromium/issues/detail?id=762679
gap for Flexbox (WebKit): https://bugs.webkit.org/show_bug.cgi?id=206767
subgrid (Chromium): https://bugs.chromium.org/p/chromium/issues/detail?id=618969
subgrid (WebKit): https://bugs.webkit.org/show_bug.cgi?id=202115

The Web We Share

Michael Puckett — Tue, 31 Dec 2019 23:17:52 +0000

Introduction

It’s a tale from another dimension: HTML markup representing not just a graphical experience but also virtual objects and their state.

HTML allows for a single element to have multiple meanings for different use cases.

You could imagine your markup as a topology with multiple layers of semantics. Or, as 3 different dimensions: visual, accessible, and machine-readable.

(And with WebXR and other emerging technologies being grafted onto the web platform, there will soon be more dimensions to consider! Spooky!)

Visual

An element’s class and style attributes are most relevant to the rendering engine that displays the visual interface. For a lot of web developers, this is just the air we breathe.

Accessibility

An element's role and aria‑* attributes are most relevant to screen readers.

Never heard of a screen reader? Most blind people don't use a mouse. Instead, they use a keyboard to operate an application that speaks the content and metadata of the currently focused element. People who are deaf-blind might use a screen reader with a refreshable Braille display.

When using a screen reader, properly marked up elements can be acted upon in unique ways. For instance, marking up all headings using heading elements (h1-h6) will compile them and make them available as a list for easier page navigation.

Interoperability

Metadata attributes such as itemprop are most relevant to digital assistants and search engines, for things like indexing and repurposing.

Audio-enabled digital assistants often parse web pages' structured data and document outlines to find information. The relevant data can be packaged into an experience that is native to that service's voice UI.

Engineering Strategies

To account for the wide range of ways HTML code can be utilized, always adhere to the HTML, ARIA, and Schema.org specifications.

In my experience, building a library of reusable, spec-compliant web components is the best way to deliver beautiful, accessible, interoperable websites.