Chapter 82: Custom Elements

Building Production Custom Elements

Capstone: Engineering an enterprise-grade, fully accessible, keyboard-navigable, form-associated `<rating-stars>` custom element.

LEARNING OBJECTIVES ⌵

Synthesize all Chapter 82 concepts into a single production-ready enterprise Web Component.
Implement complete W3C ARIA Slider semantics (role="slider", aria-valuenow, aria-valuemin, aria-valuemax).
Implement full keyboard navigation (Arrow keys, Home, End) with accessible live announcements.
Integrate native form submission, constraint validation, reset handling, and custom event dispatching.

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine a Swiss watchmaker designing a mechanical timepiece.

A novice watchmaker might assemble gears that spin when you push them with your finger, but they slip out of alignment when the watch is shaken, they stop running in cold weather, and they don't connect to any standard wristband.

The Master Craftsman, however, builds according to rigorous horological standards:

The Casing (DOM Shell): Precision-molded, responsive, and customizable via standard bezels (CSS Custom Properties).
The Escapement (State Machine): Synchronized gear train that reflects every mechanical tick to both the dial hands (HTML attributes) and the digital sensor (JavaScript properties).
The Universal Lugs (Form & Framework Interoperability): Connects to any standard watch strap—whether <form> submissions, React state, or raw HTML pages.
Haptic & Visual Feedback (Accessibility & Keyboard Engine): Operable by touch alone in total darkness without looking at the face.

In this capstone lesson, we engineer <rating-stars>: a production-grade custom element adhering to FAANG design system standards.

+--------------------------------------------------------------------------------------------------+
|                               <rating-stars> ARCHITECTURAL BLUEPRINT                             |
|                                                                                                  |
|   +------------------------------------------------------------------------------------------+   |
|   | 1. CustomElementRegistry: customElements.define('rating-stars', RatingStars)             |   |
|   +------------------------------------------------------------------------------------------+   |
|                                                |                                                 |
|   +------------------------------------------------------------------------------------------+   |
|   | 2. Property & Attribute Reflection:                                                      |   |
|   |    - value (0 to max)            <---> attribute: value="4"                              |   |
|   |    - max (default 5)             <---> attribute: max="5"                                |   |
|   |    - disabled                    <---> attribute: disabled                               |   |
|   |    - readonly                    <---> attribute: readonly                               |   |
|   +------------------------------------------------------------------------------------------+   |
|                                                |                                                 |
|   +------------------------------------------------------------------------------------------+   |
|   | 3. ElementInternals & Form Participation:                                                |   |
|   |    - static formAssociated = true                                                        |   |
|   |    - setFormValue(this.value)                                                            |   |
|   |    - setValidity({ valueMissing }) on required validation                                |   |
|   |    - formResetCallback() -> resets to initial default value                              |   |
|   +------------------------------------------------------------------------------------------+   |
|                                                |                                                 |
|   +------------------------------------------------------------------------------------------+   |
|   | 4. ARIA & Keyboard Navigation (W3C APG Slider Pattern):                                  |   |
|   |    - role="slider", tabindex="0", aria-valuenow, aria-valuemin, aria-valuemax            |   |
|   |    - ArrowLeft / ArrowDown: Decrement | ArrowRight / ArrowUp: Increment                  |   |
|   |    - Home: Set to minimum (0)         | End: Set to maximum (max)                        |   |
|   +------------------------------------------------------------------------------------------+   |
|                                                |                                                 |
|   +------------------------------------------------------------------------------------------+   |
|   | 5. Event Dispatching:                                                                    |   |
|   |    - dispatchEvent(new CustomEvent('rating-change', { detail: { value }, bubbles, ... }))|   |
|   +------------------------------------------------------------------------------------------+   |
+--------------------------------------------------------------------------------------------------+

Technical Deep Dive & Specifications

Keyboard Navigation & ARIA Matrix

Key / Attribute	Action / ARIA Role	Specification Rule
`role="slider"`	Slider Widget	Identifies the element as an adjustable range control to screen readers.
`aria-valuenow`	Current Rating	Reflects `this.value`. Screen readers announce current value on change.
`aria-valuemin`	Minimum Value	`0` (or `1` if zero ratings are disallowed).
`aria-valuemax`	Maximum Value	Matches `this.max` (e.g. `5`).
`aria-label`	Accessible Label	Set by author or defaults to `'Rating'`.
`ArrowRight` / `ArrowUp`	Increment Value	Increases rating by `1` (clamped to `max`).
`ArrowLeft` / `ArrowDown`	Decrement Value	Decreases rating by `1` (clamped to `0`).
`Home`	Minimum Rating	Sets rating to `0`.
`End`	Maximum Rating	Sets rating to `max`.

CSS Custom Properties Theming Architecture

To make the element customizable across design systems, expose CSS variables:

--star-color-active: Color of filled stars (default #f59e0b).
--star-color-empty: Color of empty stars (default #475569).
--star-color-hover: Preview color during mouse hover (default #fbbf24).
--star-size: Width/height of each star SVG (default 28px).

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Lines 102–104: RatingStars declares static formAssociated = true and observedAttributes.
Lines 118–132: value getter/setter reflects numeric state with automatic clamping between 0 and this.max.
Lines 159–168: connectedCallback() attaches accessibility baseline (role="slider", tabindex="0", aria-label).
Lines 170–175: disconnectedCallback() aborts all pointer and keyboard event listeners using this._abortController.abort().
Lines 197–224: Implements full keyboard navigation (Arrow keys, Home, End) matching the W3C APG Slider pattern.
Lines 262–276: syncState() updates ARIA slider values, submits form value to ElementInternals, and enforces native constraint validation.

Expected Browser Render Output

Renders 5 interactive gold stars with smooth hover scaling.
Navigating with keyboard arrow keys updates the rating and announces changes via screen readers.
Submitting the form with a rating of 0 triggers native HTML5 validation. Selecting 4 stars submits {"quality_rating": "4"}.

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Lesson 82.10: Production Custom Element</title>
  <style>
    body {
      font-family: system-ui, sans-serif;
      padding: 2rem;
      background: #0f172a;
      color: #f8fafc;
    }

.card {
      background: #1e293b;
      padding: 2rem;
      border-radius: 12px;
      border: 1px solid #334155;
      max-width: 500px;
    }

/* Production CSS Theming API */
    rating-stars {
      --star-color-active: #fbbf24;
      --star-color-empty: #334155;
      --star-color-hover: #f59e0b;
      --star-size: 32px;
      display: inline-flex;
      align-items: center;
      gap: 0.25rem;
      outline: none;
      user-select: none;
      cursor: pointer;
    }

rating-stars:focus-visible {
      box-shadow: 0 0 0 3px #38bdf8;
      border-radius: 6px;
    }

rating-stars[disabled] {
      opacity: 0.4;
      cursor: not-allowed;
      pointer-events: none;
    }

.star-icon {
      width: var(--star-size);
      height: var(--star-size);
      fill: var(--star-color-empty);
      transition: fill 0.15s ease, transform 0.15s ease;
    }

.star-icon.filled {
      fill: var(--star-color-active);
    }

.star-icon.preview {
      fill: var(--star-color-hover);
      transform: scale(1.15);
    }

.btn-group {
      display: flex;
      gap: 0.75rem;
      margin-top: 1.5rem;
    }

button {
      padding: 0.6rem 1.2rem;
      border-radius: 6px;
      border: none;
      font-weight: 600;
      cursor: pointer;
    }
    button[type="submit"] { background: #22c55e; color: white; }
    button[type="reset"] { background: #64748b; color: white; }

#log-feed {
      margin-top: 1.5rem;
      background: #000;
      color: #38bdf8;
      font-family: monospace;
      padding: 1rem;
      border-radius: 6px;
    }
  </style>
</head>
<body>
  <h1>Enterprise Component Capstone: <code>&lt;rating-stars&gt;</code></h1>

<div class="card">
    <form id="review-form">
      <label for="product-rating" style="display: block; font-weight: 600; margin-bottom: 0.5rem;">
        Product Quality Rating (Required):
      </label>

<rating-stars id="product-rating" name="quality_rating" max="5" value="3" required></rating-stars>

<div class="btn-group">
        <button type="submit">Submit Review</button>
        <button type="reset">Reset Form</button>
      </div>
    </form>
  </div>

<div id="log-feed"><strong>Telemetry & Form Logs:</strong><br></div>

class RatingStars extends HTMLElement {
      static formAssociated = true;

static get observedAttributes() {
        return ['value', 'max', 'disabled', 'readonly', 'required'];
      }

constructor() {
        super();
        this._internals = this.attachInternals();
        this._isRendered = false;
        this._abortController = null;
        this._hoverValue = null;
      }

// --- Reflected Properties ---
      get value() {
        const v = Number(this.getAttribute('value'));
        return isNaN(v) ? 0 : Math.min(this.max, Math.max(0, v));
      }
      set value(val) {
        const num = Number(val);
        const clamped = isNaN(num) ? 0 : Math.min(this.max, Math.max(0, num));
        this.setAttribute('value', String(clamped));
      }

get max() {
        const m = Number(this.getAttribute('max'));
        return isNaN(m) || m <= 0 ? 5 : m;
      }
      set max(val) {
        this.setAttribute('max', String(val));
      }

get disabled() { return this.hasAttribute('disabled'); }
      set disabled(val) {
        if (val) this.setAttribute('disabled', '');
        else this.removeAttribute('disabled');
      }

get readonly() { return this.hasAttribute('readonly'); }
      set readonly(val) {
        if (val) this.setAttribute('readonly', '');
        else this.removeAttribute('readonly');
      }

get required() { return this.hasAttribute('required'); }
      set required(val) {
        if (val) this.setAttribute('required', '');
        else this.removeAttribute('required');
      }

// Form properties
      get form() { return this._internals.form; }
      get name() { return this.getAttribute('name'); }
      get type() { return 'rating-stars'; }

connectedCallback() {
        // Accessibility baseline
        if (!this.hasAttribute('role')) this.setAttribute('role', 'slider');
        if (!this.hasAttribute('tabindex') && !this.disabled) this.setAttribute('tabindex', '0');
        if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', 'Rating');

this.render();
        this._isRendered = true;

this.setupEventListeners();
        this.syncState();
      }

disconnectedCallback() {
        if (this._abortController) {
          this._abortController.abort();
          this._abortController = null;
        }
      }

attributeChangedCallback(name, oldValue, newValue) {
        if (oldValue === newValue) return;
        if (this._isRendered) {
          if (name === 'max') {
            this.render();
            this.setupEventListeners();
          }
          this.syncState();
        }
      }

// Form Lifecycle Handlers
      formResetCallback() {
        this.value = 0;
        this.syncState();
      }

formDisabledCallback(disabled) {
        this.setAttribute('tabindex', disabled ? '-1' : '0');
        this.disabled = disabled;
      }

setupEventListeners() {
        if (this._abortController) this._abortController.abort();
        this._abortController = new AbortController();
        const { signal } = this._abortController;

// Keyboard Navigation (W3C APG Slider Pattern)
        this.addEventListener('keydown', (e) => {
          if (this.disabled || this.readonly) return;
          const prev = this.value;

if (e.key === 'ArrowRight' || e.key === 'ArrowUp') {
            e.preventDefault();
            this.value = this.value + 1;
            this.emitChange(prev);
          } else if (e.key === 'ArrowLeft' || e.key === 'ArrowDown') {
            e.preventDefault();
            this.value = this.value - 1;
            this.emitChange(prev);
          } else if (e.key === 'Home') {
            e.preventDefault();
            this.value = 0;
            this.emitChange(prev);
          } else if (e.key === 'End') {
            e.preventDefault();
            this.value = this.max;
            this.emitChange(prev);
          }
        }, { signal });

// Pointer hover & click interactions
        const stars = this.querySelectorAll('.star-icon');
        stars.forEach((star, idx) => {
          const starIndex = idx + 1;

star.addEventListener('mouseenter', () => {
            if (this.disabled || this.readonly) return;
            this._hoverValue = starIndex;
            this.updateStarsDisplay();
          }, { signal });

star.addEventListener('click', () => {
            if (this.disabled || this.readonly) return;
            const prev = this.value;
            this.value = (this.value === starIndex) ? 0 : starIndex; // Toggle if clicked again
            this.emitChange(prev);
          }, { signal });
        });

this.addEventListener('mouseleave', () => {
          this._hoverValue = null;
          this.updateStarsDisplay();
        }, { signal });
      }

render() {
        this.innerHTML = '';
        for (let i = 1; i <= this.max; i++) {
          const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
          svg.setAttribute('class', 'star-icon');
          svg.setAttribute('viewBox', '0 0 24 24');
          svg.innerHTML = '<path d="M12 17.27L18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z"/>';
          this.appendChild(svg);
        }
      }

syncState() {
        // 1. Sync ARIA attributes
        this.setAttribute('aria-valuenow', String(this.value));
        this.setAttribute('aria-valuemin', '0');
        this.setAttribute('aria-valuemax', String(this.max));

// 2. Sync ElementInternals Form Value & Validation
        this._internals.setFormValue(this.value > 0 ? String(this.value) : null);

if (this.required && this.value === 0) {
          this._internals.setValidity(
            { valueMissing: true },
            'Please provide a rating before submitting.',
            this
          );
        } else {
          this._internals.setValidity({});
        }

this.updateStarsDisplay();
      }

updateStarsDisplay() {
        const stars = this.querySelectorAll('.star-icon');
        const activeTarget = this._hoverValue !== null ? this._hoverValue : this.value;

stars.forEach((star, index) => {
          const starNum = index + 1;
          star.classList.remove('filled', 'preview');

if (this._hoverValue !== null) {
            if (starNum <= this._hoverValue) star.classList.add('preview');
          } else {
            if (starNum <= this.value) star.classList.add('filled');
          }
        });
      }

emitChange(previousValue) {
        this.dispatchEvent(new CustomEvent('rating-change', {
          detail: {
            value: this.value,
            previousValue,
            max: this.max
          },
          bubbles: true,
          composed: true
        }));
      }
    }

customElements.define('rating-stars', RatingStars);

// Demonstration wiring
    const ratingEl = document.getElementById('product-rating');
    const form = document.getElementById('review-form');

ratingEl.addEventListener('rating-change', (e) => {
      log(`⭐ rating-change event: New Value = ${e.detail.value} (Previous = ${e.detail.previousValue})`);
    });

form.addEventListener('submit', (e) => {
      e.preventDefault();
      const fd = new FormData(form);
      log(`📬 Form Submitted! FormData payload: ${JSON.stringify(Object.fromEntries(fd.entries()))}`);
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

🏋️ Hands-On Exercise

🎯 The Challenge: Extend `<rating-stars>` with a Live Status Badge

Instructions:

Extend the <rating-stars> component to include an optional text summary badge (e.g. "3 of 5 stars").
Add a reflected boolean attribute show-badge.
When show-badge is present, render a <span class="rating-badge"> next to the stars and update its text dynamically whenever the rating changes.
If show-badge is absent, remove the badge element.

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Exercise: Rating Stars with Badge</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 2rem; background: #0f172a; color: white; }
    rating-stars { display: inline-flex; align-items: center; gap: 0.5rem; outline: none; cursor: pointer; }
    .star-icon { width: 28px; height: 28px; fill: #334155; transition: fill 0.15s; }
    .star-icon.filled { fill: #f59e0b; }
    .rating-badge {
      background: #1e293b; color: #38bdf8; padding: 0.2rem 0.6rem; border-radius: 4px;
      font-size: 0.85rem; font-weight: bold; border: 1px solid #334155;
    }
  </style>
</head>
<body>
  <h1>Badge Enhanced Rating Control</h1>
  <rating-stars id="badge-rating" max="5" value="4" show-badge></rating-stars>

  <br><br>
  <button onclick="document.getElementById('badge-rating').value = 2;">Set Value = 2</button>
  <button onclick="const el = document.getElementById('badge-rating'); el.showBadge = !el.showBadge;">Toggle Badge</button>

  <script>
    class RatingStarsWithBadge extends HTMLElement {
      static get observedAttributes() {
        return ['value', 'max', 'show-badge'];
      }

      get value() { return Math.max(0, Math.min(this.max, Number(this.getAttribute('value')) || 0)); }
      set value(v) { this.setAttribute('value', String(v)); }

      get max() { return Number(this.getAttribute('max')) || 5; }
      set max(v) { this.setAttribute('max', String(v)); }

      get showBadge() { return this.hasAttribute('show-badge'); }
      set showBadge(v) {
        if (v) this.setAttribute('show-badge', '');
        else this.removeAttribute('show-badge');
      }

      connectedCallback() {
        this.render();
        this.sync();
      }

      attributeChangedCallback(name, oldV, newV) {
        if (oldV === newV) return;
        this.sync();
      }

      render() {
        this.innerHTML = `
          <div class="stars-holder" style="display:inline-flex;gap:4px;"></div>
          <span class="rating-badge" style="display:none;"></span>
        `;

        const holder = this.querySelector('.stars-holder');
        for (let i = 1; i <= this.max; i++) {
          const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
          svg.setAttribute('class', 'star-icon');
          svg.setAttribute('viewBox', '0 0 24 24');
          svg.innerHTML = '<path d="M12 17.27L18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z"/>';
          svg.addEventListener('click', () => { this.value = i; });
          holder.appendChild(svg);
        }
      }

      sync() {
        const stars = this.querySelectorAll('.star-icon');
        stars.forEach((s, idx) => {
          if (idx + 1 <= this.value) s.classList.add('filled');
          else s.classList.remove('filled');
        });

        const badge = this.querySelector('.rating-badge');
        if (badge) {
          if (this.showBadge) {
            badge.style.display = 'inline-block';
            badge.textContent = `${this.value} / ${this.max} Stars`;
          } else {
            badge.style.display = 'none';
          }
        }
      }
    }

    customElements.define('rating-stars', RatingStarsWithBadge);
  </script>
</body>
</html>

Why this works: RatingStarsWithBadge dynamically reflects the show-badge boolean attribute and updates the rendered score badge in response to both attribute toggles and value updates.

⚠️ Common Pitfalls

Omitting Keyboard Accessibility: Mouse-only components alienate assistive technology users and violate WCAG 2.2 AA standards. Always support standard arrow keys for adjustable widgets.
Unstyled Focus States: Removing outline: none without providing an alternative :focus-visible ring renders the component unusable for keyboard navigation.
Leaking Event Listeners: Always clean up listeners attached to child elements or window via AbortController in disconnectedCallback().

💡 Pro Tips

CSS Custom Property Contracts: Document your component's CSS custom properties as an explicit public API in your component design system documentation.
Universal Framework Wrapper: A standard Web Component with reflected properties and CustomEvent dispatching integrates natively with React 19, Vue 3, Angular, and Svelte without third-party wrapper libraries.

📌 Key Takeaways

Production custom elements integrate registration, reflection, lifecycle cleanup, form participation, and accessibility.
The W3C ARIA Slider pattern provides standardized keyboard navigation (Arrow keys, Home, End) and screen reader support.
ElementInternals allows custom components to participate natively in <form> validation and submission pipelines.
CSS Custom Properties provide a robust theming bridge between external stylesheets and custom components.
Standard custom elements work across every major modern frontend framework without external dependencies.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

Which ARIA role is standard for an interactive range/rating component like `<rating-stars>` according to the W3C APG?

Topic: HTML Fundamentals

? Question 2 / 3

What is the purpose of the `Home` and `End` keys on an accessible slider or rating component?

Topic: HTML Fundamentals

? Question 3 / 3

How should you expose visual customization points (such as colors and sizes) for a production custom element?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

Keyboard Navigation & ARIA Matrix

CSS Custom Properties Theming Architecture

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Expected Browser Render Output

🏋️ Hands-On Exercise

🎯 The Challenge: Extend <rating-stars> with a Live Status Badge

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Which ARIA role is standard for an interactive range/rating component like <rating-stars> according to the W3C APG?

What is the purpose of the Home and End keys on an accessible slider or rating component?

How should you expose visual customization points (such as colors and sizes) for a production custom element?

🎯 The Challenge: Extend `<rating-stars>` with a Live Status Badge

Which ARIA role is standard for an interactive range/rating component like `<rating-stars>` according to the W3C APG?

What is the purpose of the `Home` and `End` keys on an accessible slider or rating component?