Add carousel and hover/focus tooltips with description to theme picker

Author: webstackdev

_TODO.md

@@ -210,50 +210,3 @@ Google Calendar, Apple Calendar,  Yahoo Calender,  Microsoft 365, Outlook, and T
 
 `https://github.com/add2cal/add-to-calendar-button`
 `https://add-to-calendar-button.com/`
-
-## Markdown
-
-## Code Block and Highlighting
-
-## Astro includes shiki, tweak config
-
-### Custom version of the code block integration from Astro Docs. "Beautiful code blocks for your Astro site". Applied to the code blocks created in `.mdx` files
-
-[`astro-code-blocks`](https://www.npmjs.com/package/@thewebforge/astro-code-blocks)
-
-
-#### Code tabs plugin so Javascript and Typescript examples can both be show.
-
-There can only be white space between two code blocks. Display name is set by `tabName` and can only contain characters in [A-Za-z0-9_]. Syntax for the first line of the code block is:
-
-```js [group:tabName]
-```
-
-`markdown-it-codetabs`
-
-#### Add copy button to code blocks
-
-`markdown-it-copy`
-
-Options for "copy" button added to code blocks
-
-```javascript
-const markdownCodeCopyConfig = {
-  /** Text shown on copy button */
-  btnText: `Copy`,
-  /** Text shown on copy failure */
-  failText: `Copy Failed`,
-  /** Text shown on copy success */
-  successText: `Success!`, // 'copy success' | copy-success text
-  /** Amount of time to show success message */
-  successTextDelay: 2000,
-  /** An HTML fragment included before <button> */
-  extraHtmlBeforeBtn: ``,
-  /** An HTML fragment included after <button> */
-  extraHtmlAfterBtn: ``,
-  /** Whether to show code language before the copy button */
-  showCodeLanguage: false,
-  /** Test to append after the copied text like a copyright notice */
-  attachText: ``,
-}
-```

src/components/Header/index.astro

@@ -64,7 +64,7 @@ const { path } = Astro.props
   {/* Theme picker toggle button to show modal */}
   <span
     id="header__theme-icon"
-    class="w-[calc(var(--header-icon-size)*2+0.5em)] lg:w-(--header-icon-size) relative z-(--z-content-overlay)"
+    class="ml-2 shrink-0 w-(--header-icon-size) relative z-(--z-content-overlay)"
   >
     <ThemeButton />
   </span>

src/components/Navigation/index.astro

@@ -13,13 +13,13 @@ const { path } = Astro.props
 <site-navigation class="contents" data-testid="site-navigation">
   <div id="mobile-nav-focus-container" class="contents">
     {/* Main Navigation Menu */}
-    <span id="header__main-nav" class="lg:z-(--z-nav) lg:flex-1 lg:mx-8">
+    <span id="header__main-nav" class="flex-1 min-w-0 lg:z-(--z-nav) lg:mx-8">
       <Menu path={path} />
     </span>
     {/* Mobile navigation toggle button to show menu on full-page splash screen */}
     <span
       id="header__nav-icon"
-      class="block fixed right-4 sm:right-6 top-2 z-(--z-mobile-close-btn) lg:hidden"
+      class="block shrink-0 z-(--z-content-overlay) lg:hidden"
     >
       <NavToggle />
     </span>

src/components/ThemePicker/client/__tests__/index.spec.ts

@@ -37,6 +37,12 @@ const getThemeModal = (root: ThemePickerElement) =>
 const getThemeCloseButton = (root: ThemePickerElement) =>
   queryElement<HTMLButtonElement>(root, '[data-theme-close]')
 const getThemeList = (root: ThemePickerElement) => queryElement<HTMLElement>(root, '#theme-menu')
+const getEmblaViewport = (root: ThemePickerElement) =>
+  queryElement<HTMLElement>(root, '[data-theme-embla-viewport]')
+const getEmblaPrevButton = (root: ThemePickerElement) =>
+  queryElement<HTMLButtonElement>(root, '[data-theme-embla-prev]')
+const getEmblaNextButton = (root: ThemePickerElement) =>
+  queryElement<HTMLButtonElement>(root, '[data-theme-embla-next]')
 const getThemeListItems = (root: ThemePickerElement) =>
   queryElements<HTMLLIElement>(root, '.themepicker__item')
 const getThemeButtons = (root: ThemePickerElement) =>
@@ -119,6 +125,19 @@ describe('ThemePicker Component', () => {
         const themes = themeButtons.map((btn) => btn.getAttribute('data-theme'))
         expect(themes).toContain('light')
         expect(themes).toContain('dark')
+        expect(themes).toContain('a11y')
+      })
+    })
+
+    it('should render embla viewport and nav buttons', async () => {
+      await renderThemePickerDom(({ element }) => {
+        const viewport = getEmblaViewport(element)
+        expect(viewport.classList.contains('embla__viewport')).toBe(true)
+
+        const prev = getEmblaPrevButton(element)
+        const next = getEmblaNextButton(element)
+        expect(prev.getAttribute('aria-label')).toBe('Previous theme')
+        expect(next.getAttribute('aria-label')).toBe('Next theme')
       })
     })
 
@@ -212,7 +231,7 @@ describe('ThemePicker Component', () => {
         buttons.forEach((button) => {
           expect(button.hasAttribute('data-theme')).toBe(true)
           const theme = button.getAttribute('data-theme')
-          expect(['light', 'dark', 'holiday']).toContain(theme)
+          expect(['light', 'dark', 'holiday', 'a11y']).toContain(theme)
         })
       })
     })
@@ -223,6 +242,7 @@ describe('ThemePicker Component', () => {
       await renderThemePickerDom(({ element }) => {
         const list = getThemeList(element)
         expect(list.classList.contains('themepicker__list')).toBe(true)
+        expect(list.classList.contains('embla__container')).toBe(true)
       })
     })
 
@@ -301,18 +321,17 @@ describe('ThemePicker Component', () => {
   })
 
   describe('Responsive Design', () => {
-    it('should have horizontal scroll on theme list', async () => {
+    it('should use Embla viewport with overflow hidden', async () => {
       await renderThemePickerDom(({ element }) => {
-        const list = queryElement<HTMLElement>(element, '.themepicker__list')
-        expect(list.classList.contains('overflow-x-auto')).toBe(true)
-        expect(list.classList.contains('overflow-y-hidden')).toBe(true)
+        const viewport = getEmblaViewport(element)
+        expect(viewport.classList.contains('overflow-hidden')).toBe(true)
       })
     })
 
-    it('should have whitespace-nowrap for horizontal layout', async () => {
+    it('should render tooltip for themes with descriptions', async () => {
       await renderThemePickerDom(({ element }) => {
-        const list = queryElement<HTMLElement>(element, '.themepicker__list')
-        expect(list.classList.contains('whitespace-nowrap')).toBe(true)
+        const tooltips = queryElements<HTMLElement>(element, '[data-theme-tooltip]')
+        expect(tooltips.length).toBeGreaterThan(0)
       })
     })
   })

src/components/ThemePicker/client/index.ts

@@ -5,6 +5,7 @@
  */
 
 import { LitElement } from 'lit'
+import EmblaCarousel, { type EmblaCarouselType, type EmblaOptionsType } from 'embla-carousel'
 import {
   setTheme,
   toggleThemePicker,
@@ -30,6 +31,14 @@ export const CLASSES = {
   active: 'is-active',
 }
 
+const THEME_PICKER_EMBLA_OPTIONS: EmblaOptionsType = {
+  loop: false,
+  align: 'center',
+  containScroll: 'trimSnaps',
+  skipSnaps: false,
+  dragFree: false,
+}
+
 /**
  * ThemePicker Custom Element (Lit-based)
  * Uses Light DOM (no Shadow DOM) with Astro-rendered templates
@@ -51,6 +60,16 @@ export class ThemePickerElement extends LitElement {
   private closeBtn!: HTMLButtonElement
   private themeSelectBtns!: NodeListOf<HTMLButtonElement>
 
+  private emblaViewport: HTMLElement | null = null
+  private emblaPrevBtn: HTMLButtonElement | null = null
+  private emblaNextBtn: HTMLButtonElement | null = null
+  private emblaApi: EmblaCarouselType | null = null
+  private emblaEvents: AbortController | null = null
+  private lastIsOpen: boolean | null = null
+  private lastTheme: ThemeId | null = null
+
+  private readonly emblaUpdateHandler = () => this.updateEmblaNavState()
+
   // Track View Transitions
   private isTransitioning = false
   private isInitialized = false
@@ -72,6 +91,11 @@ export class ThemePickerElement extends LitElement {
     }
   }
 
+  override disconnectedCallback(): void {
+    super.disconnectedCallback()
+    this.teardownEmbla()
+  }
+
   /**
    * Initialize the theme picker after DOM is ready
    */
@@ -124,6 +148,8 @@ export class ThemePickerElement extends LitElement {
 
     // Update active theme button
     this.updateActiveTheme(currentTheme)
+
+    this.syncThemeCarousel(isOpen, currentTheme)
   }
 
   /**
@@ -136,6 +162,145 @@ export class ThemePickerElement extends LitElement {
     this.toggleBtn = getThemePickerToggleBtn()
     this.closeBtn = getThemePickerCloseBtn(this)
     this.themeSelectBtns = getThemeSelectBtns(this)
+
+    this.emblaViewport = this.querySelector('[data-theme-embla-viewport]')
+    this.emblaPrevBtn = this.querySelector('[data-theme-embla-prev]')
+    this.emblaNextBtn = this.querySelector('[data-theme-embla-next]')
+  }
+
+  private syncThemeCarousel(isOpen: boolean, currentTheme: ThemeId): void {
+    const shouldInit = isOpen && !!this.emblaViewport
+
+    if (!shouldInit) {
+      if (this.lastIsOpen) {
+        this.teardownEmbla()
+      }
+      this.lastIsOpen = isOpen
+      this.lastTheme = currentTheme
+      return
+    }
+
+    const openChanged = this.lastIsOpen !== isOpen
+    const themeChanged = this.lastTheme !== currentTheme
+
+    if (openChanged) {
+      this.setupEmbla()
+      // Modal just opened; wait a frame so Embla sees correct sizing.
+      requestAnimationFrame(() => {
+        try {
+          this.emblaApi?.reInit()
+          this.updateEmblaNavState()
+          this.scrollThemeIntoView(currentTheme)
+        } catch (error) {
+          handleScriptError(error, { scriptName: 'ThemePickerElement', operation: 'embla:reInit' })
+        }
+      })
+    } else if (themeChanged) {
+      this.scrollThemeIntoView(currentTheme)
+    }
+
+    this.lastIsOpen = isOpen
+    this.lastTheme = currentTheme
+  }
+
+  private setupEmbla(): void {
+    this.teardownEmbla()
+    if (!this.emblaViewport) return
+
+    try {
+      this.emblaApi = EmblaCarousel(this.emblaViewport, THEME_PICKER_EMBLA_OPTIONS)
+      this.updateEmblaNavState()
+
+      const emblaWithEvents = this.emblaApi as EmblaCarouselType & {
+        on: (_event: string, _handler: () => void) => EmblaCarouselType
+      }
+
+      emblaWithEvents.on('select', this.emblaUpdateHandler)
+      emblaWithEvents.on('reInit', this.emblaUpdateHandler)
+
+      this.emblaEvents = new AbortController()
+      const { signal } = this.emblaEvents
+
+      if (this.emblaPrevBtn) {
+        this.emblaPrevBtn.addEventListener('click', (event) => {
+          event.preventDefault()
+          try {
+            this.emblaApi?.scrollPrev()
+          } catch (error) {
+            handleScriptError(error, { scriptName: 'ThemePickerElement', operation: 'embla:scrollPrev' })
+          }
+        }, { signal })
+      }
+
+      if (this.emblaNextBtn) {
+        this.emblaNextBtn.addEventListener('click', (event) => {
+          event.preventDefault()
+          try {
+            this.emblaApi?.scrollNext()
+          } catch (error) {
+            handleScriptError(error, { scriptName: 'ThemePickerElement', operation: 'embla:scrollNext' })
+          }
+        }, { signal })
+      }
+    } catch (error) {
+      this.teardownEmbla()
+      handleScriptError(error, { scriptName: 'ThemePickerElement', operation: 'embla:setup' })
+    }
+  }
+
+  private teardownEmbla(): void {
+    if (this.emblaEvents) {
+      this.emblaEvents.abort()
+      this.emblaEvents = null
+    }
+
+    if (this.emblaApi) {
+      this.emblaApi.destroy()
+      this.emblaApi = null
+    }
+  }
+
+  private updateEmblaNavState(): void {
+    if (!this.emblaApi || !this.emblaPrevBtn || !this.emblaNextBtn) return
+
+    const hasOverflow = this.emblaApi.scrollSnapList().length > 1
+    if (!hasOverflow) {
+      this.emblaPrevBtn.setAttribute('hidden', '')
+      this.emblaNextBtn.setAttribute('hidden', '')
+      this.emblaPrevBtn.setAttribute('disabled', 'true')
+      this.emblaNextBtn.setAttribute('disabled', 'true')
+      return
+    }
+
+    this.emblaPrevBtn.removeAttribute('hidden')
+    this.emblaNextBtn.removeAttribute('hidden')
+
+    if (this.emblaApi.canScrollPrev()) {
+      this.emblaPrevBtn.removeAttribute('disabled')
+    } else {
+      this.emblaPrevBtn.setAttribute('disabled', 'true')
+    }
+
+    if (this.emblaApi.canScrollNext()) {
+      this.emblaNextBtn.removeAttribute('disabled')
+    } else {
+      this.emblaNextBtn.setAttribute('disabled', 'true')
+    }
+  }
+
+  private scrollThemeIntoView(themeId: ThemeId): void {
+    if (!this.emblaApi) return
+
+    const buttons = Array.from(this.themeSelectBtns)
+    const index = buttons.findIndex(button => button.dataset['theme'] === themeId)
+    if (index < 0) return
+
+    try {
+      this.emblaApi.scrollTo(index, true)
+      this.updateEmblaNavState()
+    } catch (error) {
+      handleScriptError(error, { scriptName: 'ThemePickerElement', operation: 'embla:scrollToTheme' })
+    }
   }
 
   /**