Fix theme picker, add progress bar to articles, fix vertical scroll bar, add sticky behavior to ToC, improve squishy effect on Header

Author: webstackdev

TROUBLESHOOTING_HEADER_SPACING.md

@@ -0,0 +1,182 @@
+// @vitest-environment jsdom
+/**
+ * Unit tests for ReadingProgressBar web component
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { ReadingProgressBar, registerProgressBarComponent } from '../index'
+
+vi.mock('@components/scripts/errors/handler', () => ({
+  handleScriptError: vi.fn(),
+}))
+
+vi.mock('@components/scripts/utils', () => ({
+  defineCustomElement: vi.fn((tagName: string, ctor: CustomElementConstructor) => {
+    if (!customElements.get(tagName)) {
+      customElements.define(tagName, ctor)
+    }
+  }),
+}))
+
+// ============================================================================
+// HELPERS
+// ============================================================================
+
+function createDOM(contentHeight = 2000) {
+  const component = document.createElement('reading-progress-bar') as ReadingProgressBar
+  component.setAttribute('data-progress-bar', '')
+
+  const progress = document.createElement('progress')
+  progress.max = 100
+  progress.value = 0
+  component.appendChild(progress)
+  document.body.appendChild(component)
+
+  const content = document.createElement('div')
+  content.id = 'content'
+  // Mock getBoundingClientRect for content
+  content.getBoundingClientRect = vi.fn().mockReturnValue({
+    top: 0,
+    height: contentHeight,
+    bottom: contentHeight,
+    left: 0,
+    right: 800,
+    width: 800,
+    x: 0,
+    y: 0,
+    toJSON: vi.fn(),
+  })
+  document.body.appendChild(content)
+
+  return { component, progress, content }
+}
+
+// ============================================================================
+// TESTS
+// ============================================================================
+
+describe('ReadingProgressBar', () => {
+  let rafCallback: FrameRequestCallback | null = null
+
+  beforeEach(async () => {
+    rafCallback = null
+    vi.spyOn(window, 'requestAnimationFrame').mockImplementation((cb: FrameRequestCallback) => {
+      rafCallback = cb
+      return 1
+    })
+    vi.spyOn(window, 'cancelAnimationFrame').mockImplementation(() => {})
+
+    // Ensure the custom element is registered
+    await registerProgressBarComponent()
+  })
+
+  afterEach(() => {
+    document.body.innerHTML = ''
+    vi.restoreAllMocks()
+  })
+
+  describe('registration', () => {
+    it('should call defineCustomElement with the correct tag name', async () => {
+      const { defineCustomElement } = await import('@components/scripts/utils')
+      await registerProgressBarComponent()
+      expect(defineCustomElement).toHaveBeenCalledWith('reading-progress-bar', ReadingProgressBar)
+    })
+  })
+
+  describe('component', () => {
+    it('should set registeredName to reading-progress-bar', () => {
+      expect(ReadingProgressBar.registeredName).toBe('reading-progress-bar')
+    })
+
+    it('should use light DOM', () => {
+      const el = new ReadingProgressBar()
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect((el as any).createRenderRoot()).toBe(el)
+    })
+
+    it('should start progress at 0', () => {
+      const { progress } = createDOM()
+      expect(progress.value).toBe(0)
+    })
+  })
+
+  describe('progress calculation', () => {
+    it('should compute progress based on content position', () => {
+      const { progress, content } = createDOM(2000)
+
+      const instance = document.createElement('reading-progress-bar')
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const priv = instance as any
+      priv.progressEl = progress
+      priv.contentEl = content
+
+      vi.spyOn(content, 'getBoundingClientRect').mockReturnValue({
+        top: -500,
+        height: 2000,
+        bottom: 1500,
+        left: 0,
+        right: 800,
+        width: 800,
+        x: 0,
+        y: -500,
+        toJSON: vi.fn(),
+      })
+
+      priv.updateProgress()
+
+      expect(progress.value).toBeGreaterThan(0)
+      expect(progress.value).toBeLessThanOrEqual(100)
+    })
+
+    it('should clamp progress to 0-100 range', () => {
+      const { progress, content } = createDOM(2000)
+
+      const instance = document.createElement('reading-progress-bar')
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const priv = instance as any
+      priv.progressEl = progress
+      priv.contentEl = content
+
+      vi.spyOn(content, 'getBoundingClientRect').mockReturnValue({
+        top: -5000,
+        height: 2000,
+        bottom: -3000,
+        left: 0,
+        right: 800,
+        width: 800,
+        x: 0,
+        y: -5000,
+        toJSON: vi.fn(),
+      })
+
+      priv.updateProgress()
+
+      expect(progress.value).toBe(100)
+    })
+
+    it('should set 100% when content fits within one viewport', () => {
+      const { progress, content } = createDOM(500)
+
+      const instance = document.createElement('reading-progress-bar')
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const priv = instance as any
+      priv.progressEl = progress
+      priv.contentEl = content
+
+      vi.spyOn(content, 'getBoundingClientRect').mockReturnValue({
+        top: 100,
+        height: 500,
+        bottom: 600,
+        left: 0,
+        right: 800,
+        width: 800,
+        x: 0,
+        y: 100,
+        toJSON: vi.fn(),
+      })
+
+      priv.updateProgress()
+
+      expect(progress.value).toBe(100)
+    })
+  })
+})

src/components/Content/ProgressBar/client/__tests__/index.spec.ts

@@ -0,0 +1,132 @@
+/**
+ * Article reading progress bar – Lit web component
+ *
+ * Renders a fixed `<progress>` element below the header that fills as
+ * the visitor scrolls through the article `#content` region. Uses the
+ * layout-position store's `--layout-top-offset` to position itself
+ * directly beneath the header.
+ */
+import { LitElement } from 'lit'
+import { defineCustomElement } from '@components/scripts/utils'
+import type { WebComponentModule } from '@components/scripts/@types/webComponentModule'
+import { handleScriptError } from '@components/scripts/errors/handler'
+
+export class ReadingProgressBar extends LitElement {
+  static registeredName = 'reading-progress-bar'
+
+  /** Keep the element in light DOM so Tailwind / CSS variables work. */
+  protected override createRenderRoot() {
+    return this
+  }
+
+  // ── Internal state ──────────────────────────────────────────────────
+  private progressEl: HTMLProgressElement | null = null
+  private contentEl: HTMLElement | null = null
+  private rafId: number | null = null
+  private scrollHandler: (() => void) | null = null
+  private resizeHandler: (() => void) | null = null
+
+  // ── Lifecycle ───────────────────────────────────────────────────────
+
+  override connectedCallback(): void {
+    super.connectedCallback()
+    this.cacheElements()
+    this.attachListeners()
+    this.updateProgress()
+  }
+
+  override disconnectedCallback(): void {
+    this.detachListeners()
+    super.disconnectedCallback()
+  }
+
+  // ── DOM ─────────────────────────────────────────────────────────────
+
+  private cacheElements(): void {
+    this.progressEl = this.querySelector<HTMLProgressElement>('progress')
+    this.contentEl = document.querySelector<HTMLElement>('#content')
+  }
+
+  // ── Listeners ───────────────────────────────────────────────────────
+
+  private attachListeners(): void {
+    this.scrollHandler = () => this.scheduleUpdate()
+    this.resizeHandler = () => this.scheduleUpdate()
+
+    window.addEventListener('scroll', this.scrollHandler, { passive: true })
+    document.addEventListener('scroll', this.scrollHandler, { passive: true, capture: true })
+    window.addEventListener('resize', this.resizeHandler, { passive: true })
+  }
+
+  private detachListeners(): void {
+    if (this.scrollHandler) {
+      window.removeEventListener('scroll', this.scrollHandler)
+      document.removeEventListener('scroll', this.scrollHandler, { capture: true })
+    }
+    if (this.resizeHandler) {
+      window.removeEventListener('resize', this.resizeHandler)
+    }
+    if (this.rafId !== null) {
+      cancelAnimationFrame(this.rafId)
+      this.rafId = null
+    }
+  }
+
+  // ── Progress calculation ────────────────────────────────────────────
+
+  private scheduleUpdate(): void {
+    if (this.rafId !== null) return
+    this.rafId = requestAnimationFrame(() => {
+      this.rafId = null
+      this.updateProgress()
+    })
+  }
+
+  /** Compute scroll progress through the `#content` region as 0–100. */
+  private updateProgress(): void {
+    try {
+      if (!this.progressEl || !this.contentEl) return
+
+      const rect = this.contentEl.getBoundingClientRect()
+      const viewportHeight = window.innerHeight
+
+      // Total scrollable distance for the content region
+      const totalHeight = rect.height
+      if (totalHeight <= 0) {
+        this.progressEl.value = 0
+        return
+      }
+
+      // How far past the top of the viewport has the content scrolled?
+      // rect.top starts positive (below viewport top) and becomes negative.
+      const scrolled = -rect.top
+      const scrollableDistance = totalHeight - viewportHeight
+
+      if (scrollableDistance <= 0) {
+        // Content fits within one screen
+        this.progressEl.value = 100
+        return
+      }
+
+      const progress = Math.min(100, Math.max(0, (scrolled / scrollableDistance) * 100))
+      this.progressEl.value = progress
+    } catch (error) {
+      handleScriptError(error, {
+        scriptName: 'ReadingProgressBar',
+        operation: 'updateProgress',
+      })
+    }
+  }
+}
+
+export const registerProgressBarComponent = async (
+  tagName = ReadingProgressBar.registeredName,
+): Promise<void> => {
+  defineCustomElement(tagName, ReadingProgressBar)
+}
+
+export const webComponentModule: WebComponentModule<ReadingProgressBar> = {
+  registeredName: ReadingProgressBar.registeredName,
+  componentCtor: ReadingProgressBar,
+  registerWebComponent: registerProgressBarComponent,
+}

src/components/Content/ProgressBar/client/index.ts

@@ -0,0 +1,28 @@
+---
+/**
+ * Article reading progress bar.
+ *
+ * Fixed below the header, shows scroll progress through the article.
+ * Rendered as a Lit web component wrapping a native <progress> element.
+ * Uses --layout-top-offset from the layout-position store for vertical
+ * positioning. The data-progress-bar attribute lets the store measure it.
+ */
+---
+
+<reading-progress-bar
+  class="fixed left-0 right-0 block h-1 sm:h-2"
+  style="top: var(--layout-top-offset, 0px); z-index: var(--z-nav);"
+  data-progress-bar
+  aria-hidden="true"
+>
+  <progress
+    max="100"
+    value="0"
+    class="block h-full w-full appearance-none [&::-webkit-progress-bar]:bg-transparent [&::-webkit-progress-value]:bg-success [&::-moz-progress-bar]:bg-success"
+  ></progress>
+</reading-progress-bar>
+
+<script>
+  import { registerProgressBarComponent } from '@components/Content/ProgressBar/client'
+  registerProgressBarComponent()
+</script>

src/components/Content/ProgressBar/index.astro

@@ -0,0 +1,38 @@
+---
+import './index.css'
+
+export type Props = {
+  /** The currently active variant, used to determine the position of the switcher thumb */
+  currentVariant: 'overview' | 'deep-dive'
+  /** The slug of the current article, used to construct links to the overview and deep dive pages */
+  slug: string
+}
+
+const { currentVariant, slug } = Astro.props
+---
+
+<div class="flex items-center gap-3" role="radiogroup" aria-label="Content Variant">
+  <span
+    class="text-sm font-medium text-content-active content-switcher-label content-switcher-label--overview"
+    id="v1-overview-label"
+  >
+    Overview
+  </span>
+
+  <button
+    type="button"
+    role="switch"
+    aria-checked={currentVariant === 'deep-dive' ? 'true' : 'false'}
+    aria-label="Toggle between Overview and Deep Dive"
+    class="content-switcher-track group relative inline-flex h-7 w-12 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent bg-trim-offset transition-colors focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-secondary"
+  >
+    <span class="content-switcher-thumb pointer-events-none inline-block size-5 translate-x-0.5 rounded-full bg-page-base shadow-sm ring-0 transition-transform" />
+  </button>
+
+  <span
+    class="text-sm text-content-offset content-switcher-label content-switcher-label--deep-dive"
+    id="v1-deep-dive-label"
+  >
+    Deep Dive
+  </span>
+</div>