MarchBox (Articles)

Regina Spektor

2023-08-07T00:00:00-07:00

Last Saturday, we went to our 2nd Regina Spektor concert this year. We went to see her at Walt Disney Concert Hall in LA back in March, and had a really great time. After we came back home, I saw she was coming to Woodinville, WA, about 3 miles from our house.

I’ve been liking her since college, when I was still living in Beijing, China. She wasn’t one of my top favorite artists back then. I started to appreciate her a lot more a few years ago, when my husband, who is a music fanatic and can tell you the billboard ranking every year in the past a few decades, started to talk about how she is a storyteller. I normally pay way more attention to the rhythms than the lyrics of a song, especially when the lyrics aren’t even in my mother tongue (Mandarin). So I started to read her lyrics while listening, there’s so much whimsy and wisdom.

However, her live performance is on a different level. This is her first tour I’ve been to, and usually I go to concerts because of being forced by my husband, I just don’t enjoy having loud sound blast into my ear (hence I always wear AirPods Pro with transparency mode on) and surrounded by overly passionate people (like the person who forces me into this situation). Although, at Walt Disney Concert Hall, because of the amazing acoustics, I didn’t put on my AirPods.

The Walt Disney Concert Hall

She was on stage alone, no band, she sometimes sang with no instruments, most time while playing piano, at one time she was singing, playing an electronic keyboard, drumming, and stumping at the same time. She also played one song with a tap dancer and that was so much fun.

The song Becoming All Alone really touched me, because the reason we went to LA was to stay with a friend for a week, who lost his husband last year. The 3 of us when to the concert together (and Disneyland After Dark Princess Nite), the lyrics has “I’m becoming all alone again” in its chorus, and I couldn’t help but put myself in the friend’s position (and I think he was crying during that song). But that’s not the only time I was really touched. There are usually 2 things that could bring me tears instantly, acceptance and craftsmanship, and boy did she show her craftsmanship.

Throughout the show, other than her amazing vocal and piano skills, she was so confident, relaxed, whimsical, playful, interactive, conversational, and just having a good time with herself and with the audience. If she made a mistake, there was no panicking or pretending, just made a quick joke and moved on, like how a friend would sing to you. Everything felt so effortless. She also utilized the Concert Hall’s acoustic, it felt like she was singing to you and telling you all her stories in a small and cozy room with woods burning inside the fireplace (*crack crack crack*).

Regina Spektor at her Woodinville concert

Last week the Seattle area had a warm and sunny week, but on Saturday morning, it started to drizzle. First thing she said was Seattle brought the rain, she expected nothing less. But it was a good rain, the concert was at our favorite winery, we were surrounded by grasses and trees, and of course wines. The whole evening felt like an intimate camping trip, with a close friend who’s so good at singing and telling stories.

I often wish she was a bit more productive, so that I didn’t have to wait for so many years to enjoy another album. But on the other side, that’s her way, the way that brought everything I love about her. I can’t wait to listen to more stories she has to tell. Until then, her songs will keep being my go-to repeating playlist (and my husband just has to deal with that).

Gradient background with transparent borders

2023-03-17T00:00:00-07:00

Everybody is asking about how to create gradient borders with transparent backgrounds. But I just had to solve an issue that’s in the opposite situation and learned about background-origin.

The issue

I have an element that has a CSS gradient as a background, adding transparent borders would create something like this:

Example with 2px borders. View details on CodePen

Notice the different colors on the borders? Here is the CSS code:

div {
  background: linear-gradient(45deg, red, blue);
  border: 2px solid transparent;
}

It’s a bit hard to understand what’s going on. So I bumped up the border-width to 20px. And now it looks like this:

Example with 20px borders. View details on CodePen

Now it’s clear, it appears that the gradient background, which is technically a background-image, is repeating itself. If the borders had colors, they’ll cover up the extra repeats, so normally I wouldn’t notice this. But now I set border colors to be transparent, I can see the repeats now.

How the background repeats itself within the border box.

Why this is happening? Now introducing background-origin.

`background-origin`

The CSS background-origin property sets where the background’s top left corner should start. Its value is one of the following keywords (other than the global values like inherit):

border-box: Align the background’s top left corner with the border box.
padding-box: Align the background’s top left corner with the padding box. This is the default value, which makes sense, because why would you want to hide part of the background behind the borders?
content-box: Align the background’s top left corner with the content box, which means the padding areas won’t get any background.

This is a CSS property I knew of before but never paid much attention to, until now. After I added background-origin: border-box, the problem was solved!

div {
  background: linear-gradient(45deg, red, blue) border-box;
  border: 2px solid transparent;
}

Issue fixed, the background gradient run throughout the padding box now.

Using DOMTokenList

2023-01-04T00:00:00-07:00

DOMTokenList is a built-in DOM interface that represents a set of string tokens. If you are familiar with classList, you are already familiar with it. In a recent project, I wanted to make a custom element property as a DOMTokenList, here’s what I learned.

Why use `DOMTokenList`?

Take the class attribute as an example, its value is a list of space-separated strings. If you want to add new classes, it’s relatively easy, but don’t forget to check if the new class already exists. And if you were to remove a class or replace one with another, it’ll involve more string manipulation or even regular expressions. But with the classList property, which is a reflection of the class attribute’s value, it’s much easier to change the class list, you can use methods like add(), remove(), replace(), toggle(), etc, you can also access individual classes with item() method or the bracket notation (e.g., classList[0]). In summary, a DOMTokenList takes a list of space-separated strings and makes it structural, and any updates on the structure will be reflected in the original list of strings.

intl-elements is the project I’ve been working on, I won’t go into details of the project, that’ll be articles for other days. But in short, it’s a collection of custom elements that makes it easy to use the Intl API declaratively. One of the key features of this library is for component users to pass in a list of locales to the custom elements, so that they can use these locales with Intl APIs to format strings. The attribute to pass in the locale list is locales, and I thought it would be nice to create a localeList property as a DOMTokenList so that authors can easily change the locale list, just like how class attribute and classList property work.

Implementing `DOMTokenList`

If you type “DOMTokenList” in a browser developer console, you can see the interface is exposed in the global context. But if you try to call it or create an instance with the new operator, browsers will throw TypeError: Illegal constructor. This is similar to the CustomElementRegistry interface. Because both are interfaces, not classes, you can’t instantiate them. However, browsers exposes window.customElements as an implementation of the CustomElementRegistry interface, so that developers can use it directly, e.g. customElements.define(). For DOMTokenList, there’s no such existing implementation in the global context. So I thought I could just implement one myself since it doesn’t seem to be very complicated. If you are interested in the implementation, here is the source code.

For the most part, the implementation was straightforward, I created a private property #list to store the actual locale list as an Array, and did some string parsing and manipulation to implement methods like add(), remove(), replace(), toggle(), entries(), item(), values(), etc.

To inform the custom elements that the list has been updated, I added a method, onChange(), so custom elements can call it and pass in callback functions, similar to how addEventListener() works. Any list-changing methods will execute all the callback functions so that the custom elements can update their internal states.

So far it’s all good, until I was stuck on how to allow accessing list items via the bracket notation, e.g. myElement.localeList[1]. I ended up looping through the private property, #list, and adding indexed getters (accessing list items is read-only):

this.#list.forEach((el, i) => {
  Object.defineProperty(this, i, {
    configurable: true,
    get: () => el,
    set: () => {},
  });
});

And inside list changing methods like add(), I had to first clear out all these getters and set them again, the clearing looks like this:

this.#list.forEach((_, i) => {
  Object.defineProperty(this, i, {
    get: () => undefined,
  });
});

This implementation worked, but it didn’t feel right. It felt like over-engineered and fragile, and when I was trying to print out an element’s localeList in a browser developer console, the output looked messy, not as clean as a classList would. That’s when I found this StackOverflow answer, suggesting to just using a classList.

Using `classList`

On the high level, the idea is to create an HTML element without connecting it to document, and use its classList as the localeList.

First, I created a function for creating the localeList in custom elements:

function createLocaleList(initialValue, onChange) {
  const hostingElement = document.createElement('div');
  const localeList = hostingElement.classList;
  localeList.value = initialValue ?? '';

  let observer;
  if (typeof onChange === 'function') {
    observer = new MutationObserver(() => {
      onChange();
    });
    observer.observe(hostingElement, {
      attributes: true,
      attributeFilter: ['class'],
    });
  }

  return localeList;
}

In a custom element definition, I could call this function like so:

class MyElement extends HTMLElement {
  // ...

  #localeList;

  get localeList() {
    return this.#localeList;
  }

  connectedCallback() {
    this.#localeList = createLocaleList(
      this.getAttribute('locales');
      () => {
        this.setAttribute(this.#localeList.value);
        // And maybe re-render the element’s content
        // based on the new locales.
      }
    );
  }

  // ...
}

Since I created a MutationObserver during the localeList creation, it would be a good idea to disconnect the observer when the custom element is disconnected (removed) from the DOM. So I added a __destroy__() method, the underlines are just to mark the method as special since it’s only intended to be used inside the custom elements, not by custom element users.

function createLocaleList(initialValue, onChange) {
  // ...

  Object.defineProperty(localeList, '__destroy__', {
    value: function() {
      observer?.disconnect();
    },
  });

  // ...
}

Then I can call it in the custom element’s disconnectedCallback():

class MyElement extends HTMLElement {
  // ...

  disconnectedCallback() {
    this.#localeList.__destroy__();
  }

  // ...
}

Last but not least, since the items of a locale list should be valid language tags, I should implement DOMTokenList’s supports() method. A localeList belongs to a custom element, which is designed for a particular Intl API, and each Intl API has a supportedLocalesOf() method to check support. Hence, I need to know which Intl API when creating the locale list.

function createLocaleList(intl, initialValue, onChange) {
  // ...

  Object.defineProperties({
    'supports': {
      value: function(locale) {
        if ('supportedLocalesOf' in intl) {
          return intl.supportedLocalesOf(locale).length > 0;
        }
        return true;
      }
    },
    '__destroy__': {/* ... */},
  });

  // ...
}

Now custom element users can check if a locale is supported by the custom element’s internal Intl object:

if (myElement.localeList.supports('es-JP')) {
  myElement.localeList.add('es-JP');
} else {
  myElement.localeList.add('es');
}

Note that I could also use other DOMTokenList, like part. But classList has much better cross-browser support. Also, unlike relList, it doesn’t define the supports() method, so I don’t have to override any built-in functionality to add supports() to localeList.

If you are interested in the new implementation, here is the source code.

Conclusion

I think DOMTokenList is a very useful interface, especially for custom elements. When developers use our custom elements, they should feel familiar with the APIs like writing HTML code, and making some custom element properties as DOMTokenList would help with that. I wish we could get a better way to create DOMTokenLists in the future, maybe something like element.createDOMTokenList()?

Generate letter-based default avatars in JavaScript

2022-07-23T00:00:00-07:00

Many websites take the first letters from a user’s names to generate their default avatar. It is similar to monograms. If you have to achieve this in JavaScript, I found using Unicode property escapes Regular Expressions is the easiest.

I recently worked on a React and GraphQL based project. In our project, we asked users to set their display names, but they don’t have to use their real names, it’s a single text field with a limit of 30 characters.

Based on the product specification, a user’s default avatar, if they haven’t uploaded an image, should be the first character of their display name contained in a circle with a background color.

An example avatar.

The chosen character must be one that is commonly used as a “letter” in any given language. For example, a Latin letter like “A”, a Chinese character like “赵”. But it shouldn’t be an emoji, a symbol, or punctuation. For example, if your display name is “🍣~Sushi Lover~”, your default avatar should display a letter “S”.

Because this is about text processing, I thought I should explore my options with Regular Expression first. And luckily, I found Unicode property escapes. Here is my code:

function genAvatar(name) {
  try {
    // Match General_Category=Letter
    const match = name.match(/\p{L}/u);
    return (match && match[0]) || null;
  } catch {
    return name[0] || null;
  }
}

It has great browser support. Here are a few things worth noting:

Because it’s an escape, you do need that \p{..}. You can also use \P{..} for negation.
The Regular Expression in my code is a shorthand of /\p{General_Category=Letter}/, because you don’t need property name (General_Category) for General categories, and Letter can be shortened to L.
You need that u flag to tell JavaScript that you are trying to match based on Unicode code points.
Based on my reading and testing, this Regular Expression seems to cover all cases. I tested in Latin script (with and without accent), Simplified Chinese, Japanese (Hiragana), Arabic, Hebrew, and Korean (Hangul). I may have missed some cases, I’ll update the article if I found any.

You can do so much more with it. It’s particularly useful when you need to handle non-Latin cases. Since this is all new to me, I’m gonna stop here before I spread any misinformation. But I recommend to dig into the MDN article and those linked standard pages if you want to do more research.

HTML isn’t GUI

2022-06-04T00:00:00-07:00

Many web developers take design mockups a bit too literally–thinking the rendered webpages should visually match the mockups. While it’s crucial to carry the visual design over to the coded webpages, there’s much more to our works than just making visual copies of mockups. We develop user interfaces that can be understood and interacted with by different people with different tools.

The web democratized information access and publishing. As web developers, we should hold the responsibility to maintain this openness, and make our webpages as inclusive, understandable, and usable by as many people in the world as possible.

Webpages are often accessed by using graphical web browsers like Safari and Chrome. But there are also screen readers like Jaws and VoiceOver for visually impaired users, and they interpret the webpages into audio instead of visuals. Therefore, when developing a webpage, we shouldn’t just focus on its graphical user interface (GUI) but also on the more abstract and content-focused user interface. The content-focused interface is output agnostic, users can consume the content visually, audibly, or even kinesthetically.

Mockup to content structure

When we develop a website, we typically think about the site structure first: How many pages? What’s the content hierarchy? How does the navigation work? What content is shared across all pages? And so on. We should also do the same for individual webpages.

When I’m handed over a wireframe or a visual design mockup, the first thing I do is to figure out the content structure: What’s the title of the page (<h1>)? What are the sections and their headings (<h2>-<h6>)? What are the relationships between different sections? Where are the header and footer content boundaries? Where is the navigation? What’s the main content of the page? And so on.

After I get an overall grasp of the content structure, I’ll start writing HTML code without thinking too much about how to achieve the visual design from the mockup because that’s mainly CSS’s job at a later time. HTML is essential for all the different software that people use to understand the content on your webpages, it’s important to keep the HTML code content-focused: use semantic markups; minimize markups for decorative purposes; use proper role and aria-* attributes if necessary; add text-based content to visual assets like images and videos as alternative interface.

When you code HTML, don’t think about the mockups, keep a tree-shape structure that represents the content in your mind. Eventually, when you form a tree in your mind instinctually, you can repeat the process of mockup to content structure to HTML to CSS for each page section, multiple times for the same page.

Separation of concerns

Many UI frameworks consider a webpage as a collection of UI elements, and to maximize their frameworks’ flexibility, many have components like <Text> and <Spacer> (but no <table> and GIF needed anymore, if you know what I mean):

<Text variant="h1" weight="semibold">Heading 1</Text>
<Spacer vertical="12"></Spacer>
<Text variant="body2">
  Lorem ipsum <Text weight="bold">dolor sit</Text> amet.
</Text>

The above code usually outputs the following HTML code:

<div class="type-h1 type-semibold">Heading 1</div>
<div class="spacer-v-12"></div>
<div class="type-body2">
  Lorem ipsum <span class="type-bold">dolor sit</span> amet.
</div>

The problem with this mindset is that you are only developing for visual users. The code could confuse visually impaired users because <div>’s don’t have semantic meanings by default, a spacer doesn’t mean anything in the auditory context, and <span class="type-bold"> doesn’t convey any importance of the marked content. This mindset also mixes document structure with presentation, resulting in maintenance issues down the road.

When we transitioned away from table layouts, the main idea was a separation of concerns: HTML handles the content structure, CSS handles the presentation, and JavaScript handles the behavior. The separation keeps HTML as a clean content-focused interface, and it makes many design changes easy to implement (by modifying CSS only).

Conclusion

Web development is all about making the design accessible to everyone. Use your technical expertise to enhance the design mockups and make them work beyond the visual context. If you haven’t, I highly recommend reading (or re-read) A Dao of Web Design.

Opening day

2022-04-22T00:00:00-07:00

Welcome to my new personal website! It took me quite a while, but I finally finished building the first iteration, and I had so much fun doing it. As the site’s first article, I’ll talk about what I’m planning on posting here.

The last time I had a blog was almost two decades ago. I was living in China and had just started my career as a web developer. I was eager to learn all the frontend technologies and read many O’Reilly books. So, I was blogging about what I learned, in Chinese. It’s such a shame that I didn’t persist, as I often admire people who’ve kept their blogs for decades.

Web design

But, better late than never. Two decades later, I’m still a web developer, and I’ve never been more passionate and confident about web development. So naturally, that’s what I’ll be primarily writing about. My focuses on web development are accessibility, semantic HTML, progressive enhancement, performance, maintainability, and localization. I also spend a lot of time thinking about web design, which, in my opinion, is an essential part of our job, because what we code directly impacts users’ lives, understanding and caring design makes us better developers. As a result, I regularly use “web design” and “web development” almost interchangeably – more on this in future articles.

Drawings

I’ve been doodling since I was two years old. I drew all over my textbooks, even in my notebooks for our weekly writing assignments. I’ve never had proper training. I used to think that allowed me to draw freely. But in the recent years, I hit a wall—I wanted to draw “perfectly” like a professional illustrator, but my lack of training kept dragging me down, I often relied on happy accidents to achieve what I want. Eventually, the frustration built up, I stopped drawing, for years, until last January, when I became aware of my anxiety issues and started to look for solutions. One day, I decided to start drawing something without caring about perfection and polish, I had a blast for about 2 months. You can see all drawings in that series on the Drawings page. I will continue posting some of my old drawings and new ones as I go.

Disney

I always think I am who I am because of 2 things: my mom and Disney. I grew up in the far west part of mainland China, and the internet wasn’t a thing until I was in high school. Disney was my window to the outside world. My love for Disney has driven me through almost all significant changes in my life. So, it would be impossible for me not to talk about Disney on my personal website.

Other things

I’ve also developed interests and hobbies in many other things, like linguistics, typography, travel, animations, and so on. I’m using this site to express my thoughts, experiences, and passions. It’s one way of dealing with my anxiety, I can build and write in the ways I want, and it helps me move my focus away from things I can’t control.

Hope you enjoy the ride.

MarchBox (Articles)

Regina Spektor

Gradient background with transparent borders

The issue

background-origin

Using DOMTokenList

Why use DOMTokenList?

Implementing DOMTokenList

Using classList

Conclusion

Generate letter-based default avatars in JavaScript

HTML isn’t GUI

Mockup to content structure

Separation of concerns

Conclusion

Opening day

Web design

Drawings

Disney

Other things

`background-origin`

Why use `DOMTokenList`?

Implementing `DOMTokenList`

Using `classList`