Glossary Web Component 관련

Markdown > Article(s)

---

Article(s)

• The Idea
• The Implementation
• Failures
• Bookmarking

---

Glossary Web Component

The one where I put the hypercard in the hyperlink

I’ve added a secret glossary to my blog! You might find it by hovering over special links. Don’t tell anyone, it’s a secret. At least until I can find a way to style the links without them being a distraction. Do I need to, or can they remain easter eggs^[1]?

The Idea

This project came about when I noted concern over my reliance on MDN^[2]. I always favour MDN over other sources. I’m lazy. I feel guilty for not linking to the small web, the indie web, the weird web. At first I banned myself from linking to MDN. Later I mulled over the glossary idea. I think I’ve solved it!

---

The Implementation

I write my blog posts in Markdown^[3]. For new glossary terms I now link to a placeholder rather than an external source. For example:

[React](/glossary/react.json)

This references a JSON^[4] file that has the following format:

{
  "title": "React",
  "description": "A legacy JavaScript framework (turned religion). Favoured by tech bros and famous for bloated bundles and crippling web performance.",
  "links": [
    {
      "name": "JSX.lol",
      "title": "Does anybody actually like React?",
      "url": "https://jsx.lol"
    },
    {
      "name": "React",
      "url": "https://react.dev"
    }
  ]
}

My build script replaces the markdown link with a web component^[5]:

<glossary-term id="--term-react">
  <a href="https://jsx.lol">React</a>
</glossary-term>

The first link in the JSON is used as the canonical source.

HTML wrapped in a custom element^[6] is a perfect example of progressive enhancement[^7]. For unsupported browsers there is still an accessible link inside. For browsers that support the Popover API[^8] each <glossary-term> element is enhanced with a fancy popover.

[^7] The front-end practice of building an accessible baseline with extra features and functionality defined by browser capabilities. The antithesis of React.

[^8] A mechanism for top-layer accessible components. Popovers can be implemented declaratively in HTML (yay!) or with JavaScript (boo!)

If you’ve missed every example so far here is the React^[7] link.

I captured a screen recording of how it should appear:

The popover is activated by either hover or keyboard focus. The escape key can also dismiss them. For touchscreens I’m going to test that live…

~[INSERT TEST RESULTS]~

Test results

it works fine. If you’ve got one of those new Apple Pencils — the new new one, not the new old one — the hover effect is magical. Touch taps are taken straight to the canonical link. The popover might be open upon return. Maybe I should cancel the popover based on touch events to avoid confusion?

---

Failures

Initially I tried to use CSS anchor positioning^[8].

I really tried. It left me in tears and I rage quit. It might be the most unintuitive, doesn’t work like it says, infuriating web “standard” ever. When anchoring a popover it’s impossible to ensure elements stay inside the viewport (without JavaScript). Please prove me wrong!

I tried to get creative with view transitions^[9] and failed. Safari had some pixel-shifting jank going on. I tried normal transitions with allow-discrete and @starting-style and failed. In an isolated demo it’s all gravy but together this new CSS stuff doesn’t plays nice. It’s not all baseline^[10] yet so let’s hope it improves. 🤞

CSS anchors are Chrome and Chrome derivatives (ungoogled-software/ungoogled-chromium)^[11] only right now. Safari Technical Preview claims to have support but Apple lies under oath so who knows?

Ultimately I gave up and used JavaScript^[12] to calculate position so I can support all browsers. I’ll recharge morale and tackle a v2.0 at a later date.

---

Bookmarking

I don’t plan to immediately retrofit older blog posts with glossary links. Although that could be a quick find & replace if I’m careful. I’m looking for positive feedback before I do. So let me know if you like it (or not). If no one hates it I’ll plough ahead, because I like it. This glossary may just be the third incarnation of my bookmarks blog.

I’m tempted to use a similar technique to create popover cards for linked notes. They have more content so I need to consider that more.

Sources on 'Easter Egg'(1)

WikipediaIGN

Sources on 'MDN Web Docs'(2)

MDN

Sources on 'Markdown'(3)

Daring Fireball: Markdown

---

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid HTML.

Hmmarkdown 2

---

The one where I parse and render Markdown (again)

Sources on 'JSON'(4)

JSON

---

JSON (JavaScript Object Notation) is a lightweight data-interchange format. It is easy for humans to read and write. It is easy for machines to parse and generate. It is based on a subset of the JavaScript Programming Language Standard ECMA-262 3rd Edition - December 1999. JSON is a text format that is completely language independent but uses conventions that are familiar to programmers of the C-family of languages, including C, C++, C#, Java, JavaScript, Perl, Python, and many others. These properties make JSON an ideal data-interchange language.

Sources on 'Web Component'(5)

Jeremy KeithDave RupertJim NielsenZach LeathermanMDN

Sources on '<custom-element>'(6)

MDN

Declarative Shadow DOM

Sources on 'Progressive Enhancement'(7)

It’s about time I tried to explain what progressive enhancement actually is

---

Progressive enhancement hasn’t caught on nearly as much as it should. It’s likely related to folks not being able to envision it working in their real world contexts. This post attempts to alleviate that and reignite the conversation.

MDN

Sources on 'Popover API'(8)

Using the Popover API for HTML Tooltips

---

We can *mostly* use HTML alone for this API. But here, we'll use CSS to style the

Popover API | 12 Days of Web

A declarative way to display elements on top of page content.

Dialog is for modals, popover is for everything else

---

and popover are currently the only two ways to access the browser’s top layer. So what’s the difference between them and which one should you use when?

Popover API - Web APIs | MDN

The Popover API provides developers with a standard, consistent, flexible mechanism for displaying popover content on top of other page content. Popover content can be controlled either using HTML attributes, or via JavaScript.

Sources on 'React'(9)

JSX.lol

Does anybody actually like React? A cherry-picked collection of React (and React-tainted) criticism.

React

React is the library for web and native user interfaces. Build user interfaces out of individual pieces called components written in JavaScript. React is designed to let you seamlessly combine components written by independent people, teams, and organizations.

Sources on 'CSS Anchor Positioning'(10)

Juan Diego RodríguezUna Kravets

Sources on 'View Transition'(11)

HTMXMDN

Sources on 'Baseline'(12)

dbushell.comweb.devMDN

Sources on 'Chrome'(13)

ungoogled-chromium (ungoogled-software/ungoogled-chromium "Google Chromium, sans integration with Google")

Sources on 'JavaScript'(14)

TC39TypeScript

Glossary Web Component

---

The one where I put the hypercard in the hyperlink

---

1. A hidden message or feature covered in less chocolate than last year due to shrinkflation. ↩︎

2. The GOAT resource for web standards documentation, API references, developer guides, and an entire section on accessibility you’ve never read. ↩︎

3. A _simple plain text markup language created by John Gruber and bastardised by everyone else. Designed for writers who enjoy teeny-weeny font sizes. ↩︎

4. JavaScript Object Notation. An almost perfect specification. If only they’d allowed trailing commas. ↩︎

5. A combination of web APIs including custom elements, shadow DOM, HTML templates, and good times. ↩︎

6. An extension of HTML with behaviour defined by the developer. Shadow DOM allows for encapsulation. Bring your own tag! It must be hyphenated. ↩︎

7. React: A legacy JavaScript framework (turned religion). Favoured by tech bros and famous for bloated bundles and crippling web performance. ↩︎

8. CSS Anchor Positioning: An indecipherable jumble of keywords that may or may not tether elements to one another. ↩︎

9. View Transition: Yet another web standard API for animations and transitions. They’ve become exceeding efficient at it. ↩︎

10. Baseline: A summary of web platform support across browsers based on spurious self-reporting and lack of real-world testing. Invented by Big Browser. ↩︎

11. One browser to rule them all, one browser to find them, one browser to bring them all, and in the darkness bind them. ↩︎

12. [object Object] ↩︎