Add line wrap in code blocks

Author: webstackdev

_TODO.md

@@ -21,12 +21,6 @@ Cons: Browser rendering can be inconsistent across different operating systems a
 
 Axe accessibility (2) - axe-core integration
 
-## Search UI
-
-- Move search box into header. Should be an icon like theme picker and hamburger menu, and spread out when clicked.
-- On search results page, center results on page
-- Improve indexing and how contents are returned.
-
 ## Performance
 
 Implement mitigations in test/e2e/specs/07-performance/PERFORMANCE.md
@@ -41,7 +35,6 @@ Vercel AI Gateway, maybe could use for a chatbot:
 
 https://vercel.com/kevin-browns-projects-dd474f73/astro-webstackbuilders-com/ai-gateway
 
-
 ## Testimonials on mobile
 
 We have E2E errors again testimonials slide on mobile chrome and safari. I think the problem is that we are pausing carousels when part of the carousel is outside of the viewport, and the testimonials are too large to display on mobile without being off viewport.
@@ -52,10 +45,6 @@ We have E2E errors again testimonials slide on mobile chrome and safari. I think
 
 We should start the mock containers with the dev server instead of with Playwright so that they're useable in a dev environment.
 
-## Add Tooltip component
-
-We need a Tooltip component. It should apply to the existing tooltips on the theme picker palettes.
-
 ## Improve print layout by hiding header and footer for articles, add tracking
 
 ```typescript
@@ -114,8 +103,14 @@ Link to the second-order category from the "Skills/Technologies Preview" icons o
 
 - Show article titles only in drop-down search result box, and dedupe results
 
+## Header
+
 Title box - need to squish to 75% and have it absolute in place as you scroll down, go back to 100% when you scroll back up
 
+## Themepicker
+
+Need to tweak 1px border for non-active theme cards
+
 ## ToolTips
 
 Need a tooltip component for consistency. List to add tooltips to:
@@ -182,13 +177,3 @@ We have generated detailed outlines for each of the MDX proposed articles we hav
 Act as a principal software engineer. Your goal is to write a detailed technical article based on the provided outline. Context: The target audience is Senior DevOps and infrastructure Engineers. The tone should be authoritative, professional, and concise, avoiding fluff or filler words. Think step-by-step before writing to improve the accuracy of technical explanations. Use a friendly first-person voice. Anything that reads like generic marketing copy is not what we want but we still want the effect of being "real" and approachable - try not to sound like technical documentation. We want to show empathy for our readers.
 
 Let's work through each article section by section based on the H2 headers in the outline. If the section looks good as-is, I'll just type "ok" so you know to continue to the next section.
-
-## Link Check
-
-Should we disable external link checking? Or maybe require allow-listing them?
-
-## Carousel
-
-- On hover when it rises, the corners get cut off and squared. It should raise to a higher index and move up.
-- The focus outline should just replace the existing border with the highlight border.
-- The card background isn't distinct enough - maybe it needs shadow all the way around, or a darker color.

src/components/Code/CodeTabs/client/__tests__/index.spec.ts

@@ -102,4 +102,89 @@ describe('CodeTabs web component', () => {
       expect(() => copyButton?.click()).not.toThrow()
     })
   })
+
+  it('renders a single tab label for a single named code block', async () => {
+    await withJsdomEnvironment(async ({ window }) => {
+      const { registerCodeTabsWebComponent } =
+        await import('@components/Code/CodeTabs/client/index')
+      registerCodeTabsWebComponent()
+
+      const element = window.document.createElement('code-tabs')
+      const pre = window.document.createElement('pre')
+      pre.setAttribute('data-language', 'typescript')
+
+      const code = window.document.createElement('code')
+      code.textContent = 'const x: number = 1'
+      pre.appendChild(code)
+
+      element.appendChild(pre)
+      window.document.body.appendChild(element)
+
+      const tabButton = element.querySelector('button[data-code-tabs-button="0"]')
+      expect(tabButton, 'CodeTabs should render a tab button for a single named code block').toBeTruthy()
+      expect(tabButton?.textContent).toBe('TypeScript')
+      expect(
+        tabButton?.className.includes('hover:text-gray-600'),
+        'Single-tab UI should not change text color on hover'
+      ).toBe(false)
+    })
+  })
+
+  it('does not apply hover color change to the active tab when multiple tabs exist', async () => {
+    await withJsdomEnvironment(async ({ window }) => {
+      const { registerCodeTabsWebComponent } =
+        await import('@components/Code/CodeTabs/client/index')
+      registerCodeTabsWebComponent()
+
+      const element = window.document.createElement('code-tabs')
+
+      const preA = window.document.createElement('pre')
+      preA.setAttribute('data-code-tabs-tab', 'A')
+      preA.setAttribute('data-language', 'javascript')
+      preA.appendChild(window.document.createElement('code'))
+
+      const preB = window.document.createElement('pre')
+      preB.setAttribute('data-code-tabs-tab', 'B')
+      preB.setAttribute('data-language', 'typescript')
+      preB.appendChild(window.document.createElement('code'))
+
+      element.appendChild(preA)
+      element.appendChild(preB)
+      window.document.body.appendChild(element)
+
+      const activeButton = element.querySelector('button[data-code-tabs-button="0"]')
+      const inactiveButton = element.querySelector('button[data-code-tabs-button="1"]')
+
+      expect(activeButton).toBeTruthy()
+      expect(inactiveButton).toBeTruthy()
+
+      expect(
+        activeButton?.className.includes('hover:text-gray-600'),
+        'Active tab should not change text color on hover'
+      ).toBe(false)
+
+      expect(
+        inactiveButton?.className.includes('hover:text-gray-600'),
+        'Inactive tab should change text color on hover'
+      ).toBe(true)
+    })
+  })
+
+  it('does not render tabs for excluded single-language blocks', async () => {
+    await withJsdomEnvironment(async ({ window }) => {
+      const { registerCodeTabsWebComponent } =
+        await import('@components/Code/CodeTabs/client/index')
+      registerCodeTabsWebComponent()
+
+      const element = window.document.createElement('code-tabs')
+      const pre = window.document.createElement('pre')
+      pre.setAttribute('data-language', 'text')
+      pre.textContent = 'plain text'
+      element.appendChild(pre)
+      window.document.body.appendChild(element)
+
+      const anyTabButton = element.querySelector('button[data-code-tabs-button]')
+      expect(anyTabButton, 'CodeTabs should not render tab buttons for excluded languages').toBeFalsy()
+    })
+  })
 })

src/components/Code/CodeTabs/client/index.ts

@@ -37,6 +37,37 @@ function getCodeText(pre: HTMLPreElement): string {
   return text
 }
 
+const EXCLUDED_SINGLE_TAB_LANGUAGES = new Set(['text', 'mermaid', 'math'])
+
+function formatLanguageLabel(language: string): string {
+  const normalized = language.trim().toLowerCase()
+  const labelMap: Record<string, string> = {
+    js: 'JavaScript',
+    javascript: 'JavaScript',
+    ts: 'TypeScript',
+    typescript: 'TypeScript',
+    html: 'HTML',
+    css: 'CSS',
+    json: 'JSON',
+    yaml: 'YAML',
+    yml: 'YAML',
+    md: 'Markdown',
+  }
+
+  return labelMap[normalized] ?? (language.trim() || language)
+}
+
+function getTabLabel(pre: HTMLPreElement, index: number): string | null {
+  const explicit = pre.getAttribute('data-code-tabs-tab')
+  if (explicit && explicit.trim()) return explicit.trim()
+
+  const language = pre.getAttribute('data-language')
+  if (!language || !language.trim()) return null
+  if (EXCLUDED_SINGLE_TAB_LANGUAGES.has(language.trim().toLowerCase())) return null
+
+  return formatLanguageLabel(language)
+}
+
 async function writeToClipboard(text: string): Promise<boolean> {
   try {
     const nav = (globalThis as unknown as { navigator?: Navigator }).navigator
@@ -57,6 +88,7 @@ class CodeTabsElement extends HTMLElement {
   private codeBlocks: HTMLPreElement[] = []
   private activeIndex = 0
   private copyTimer: number | null = null
+  private isInteractiveTabs = false
 
   connectedCallback(): void {
     if (this.dataset['enhanced'] === 'true') return
@@ -66,12 +98,16 @@ class CodeTabsElement extends HTMLElement {
 
     if (this.codeBlocks.length === 0) return
 
-    const hasTabs = this.codeBlocks.length >= 2
-    this.buildUi(hasTabs)
+    const labels = this.codeBlocks
+      .map((pre, index) => getTabLabel(pre, index))
+      .filter((label): label is string => Boolean(label))
 
-    if (hasTabs) {
-      this.setActive(0)
-    }
+    this.isInteractiveTabs = this.codeBlocks.length >= 2
+    const shouldRenderTabs = this.isInteractiveTabs || (this.codeBlocks.length === 1 && labels.length === 1)
+
+    this.buildUi({ shouldRenderTabs, labels })
+
+    if (shouldRenderTabs) this.setActive(0)
   }
 
   disconnectedCallback(): void {
@@ -81,26 +117,26 @@ class CodeTabsElement extends HTMLElement {
     }
   }
 
-  private buildUi(hasTabs: boolean): void {
+  private buildUi(args: { shouldRenderTabs: boolean; labels: string[] }): void {
     const header = document.createElement('div')
     header.className =
       'flex w-full min-w-0 items-center justify-between border-b border-gray-200 bg-gray-50'
 
     const copyButton = this.createCopyButton()
 
-    if (hasTabs) {
+    if (args.shouldRenderTabs) {
       const list = document.createElement('ul')
       list.className = 'flex-1 min-w-0 p-0 whitespace-nowrap overflow-auto select-none'
 
-      this.tabButtons = this.codeBlocks.map((pre, index) => {
-        const tabLabel = pre.getAttribute('data-code-tabs-tab') || `Tab ${index + 1}`
+      this.tabButtons = this.codeBlocks.map((_, index) => {
+        const tabLabel = args.labels[index] || `Tab ${index + 1}`
 
         const li = document.createElement('li')
         li.className = 'list-none inline-block relative'
 
         const button = document.createElement('button')
         button.type = 'button'
-        button.className = 'inline-block px-2 py-1 m-2 text-gray-400 hover:text-gray-600'
+        button.className = 'inline-block px-2 py-1 m-2 text-gray-400'
         button.textContent = tabLabel
         button.setAttribute('data-code-tabs-button', String(index))
 
@@ -132,7 +168,7 @@ class CodeTabsElement extends HTMLElement {
     const button = document.createElement('button')
     button.type = 'button'
     button.className =
-      'flex shrink-0 items-center gap-2 px-3 py-2 text-gray-600 hover:text-gray-900 border-l border-gray-200'
+      'flex shrink-0 items-center gap-2 mr-2 px-3 py-2 text-gray-600 hover:text-gray-900 border-l border-gray-200'
     button.setAttribute('aria-label', tooltip)
     button.title = tooltip
 
@@ -166,8 +202,19 @@ class CodeTabsElement extends HTMLElement {
     }
 
     this.tabButtons.forEach((btn, i) => {
-      btn.classList.toggle('text-gray-900', i === index)
-      btn.classList.toggle('text-gray-400', i !== index)
+      const isActive = i === index
+      btn.classList.toggle('text-gray-900', isActive)
+      btn.classList.toggle('text-gray-400', !isActive)
+
+      // Hover color behavior:
+      // - Single-tab UI: no hover color change.
+      // - Multi-tab UI: inactive tabs change color on hover; active tab does not.
+      if (!this.isInteractiveTabs) {
+        btn.classList.remove('hover:text-gray-600')
+        return
+      }
+
+      btn.classList.toggle('hover:text-gray-600', !isActive)
     })
   }
 

src/components/Toc/index.astro

@@ -51,6 +51,7 @@ const tocTree = buildTocTree(items)
                 Jump to section
               </span>
             </div>
+            <hr class="mt-4 border-dotted border-t-2 border-content-offset w-full" />
             <nav class="mt-4 toc-nav" aria-label="Table of contents">
               <ol class="space-y-1">
                 {(() => {
@@ -61,7 +62,7 @@ const tocTree = buildTocTree(items)
                           href={`#${node.slug}`}
                           data-toc-link
                           data-toc-slug={node.slug}
-                          class="block text-sm text-content-active transition-colors hover:text-primary data-[current=true]:text-content-active"
+                          class="block mb-2 text-sm sm:text-md text-content-offset transition-colors hover:text-content-active data-[current=true]:text-content no-underline hover:underline"
                         >
                           {node.text}
                         </a>

src/content/articles/demo/index.mdx

@@ -73,6 +73,7 @@ function fetchUserData(userId) {
     }, 500) // Simulate network delay
   })
 }
+
 ```
 ```typescript [g1:Typescript]
 class TypedEventEmitter<T extends Record<keyof T, any>> implements EventEmitter<T> {
@@ -226,6 +227,39 @@ features:
   }
 }
 ```
+```html [g3:HTML]
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+</head>
+<body style="margin: 0 auto; max-width: 520px;">
+  <h1>Hi there!</h1>
+  <div>I'm your cool new webpage! Use the toggle in the <dark-mode style="border: 2px solid blue"></dark-mode> 👈  button to switch my theme.</div>
+  Github: <a href="https://github.com/jaywcjlove/dark-mode.git" target="__blank">@jaywcjlove/dark-mode</a>
+  <script>
+    const toggle = document.querySelector('dark-mode');
+    const button = document.createElement('button');
+    button.textContent = 'Change Theme';
+    button.style = 'line-height: 16px';
+    button.onclick = () => {
+      const theme = document.documentElement.dataset.colorMode;
+      toggle.mode = theme === 'light' ? 'dark' : 'light';
+      // document.documentElement.setAttribute('data-color-mode', theme === 'light' ? 'dark' : 'light');
+    }
+    document.body.appendChild(button);
+    document.addEventListener('colorschemechange', (e) => {
+      console.log(`colorschemechange: Color scheme changed to "${e.detail.colorScheme}" or .`);
+      button.textContent = toggle.mode === 'dark' ? 'Change Theme 🌞' : 'Change Theme 🌒';
+    });
+    document.addEventListener('permanentcolorscheme', (e) => {
+      console.log(`~permanentcolorscheme: Color scheme changed to "${e.detail.colorScheme}" or .`);
+    });
+    const removePermanent = () => document.querySelectorAll('dark-mode').forEach((item) => item.removeAttribute('permanent'));
+  </script>
+</body>
+</html>
+```
 
 #### Add a title to the code block
 
@@ -973,8 +1007,6 @@ my ==marked== text
 
 ### rehype-mathjax and remark-math
 
-- `rehype-katex` is alternative but lacks accessibility
-
 ```markdown
 Lift($$L$$) can be determined by Lift Coefficient ($$C_L$$) like the following
 equation.

src/content/themes.json

@@ -25,7 +25,7 @@
     {
       "id": "a11y",
       "name": "High Contrast",
-      "description": "High contrast theme targeting WCAG 2.2 SC 1.4.6 (Contrast (Enhanced))",
+      "description": "High contrast theme targeting WCAG 2.2 SC 1.4.6 Contrast (Enhanced)",
       "category": "core",
       "colors": {
         "backgroundOffset": "#e5e7eb"

src/lib/config/linkValidator.ts

@@ -29,6 +29,10 @@ export const linkValidatorPlugin = linkValidator({
     /** Skip hard-coded site URLs due to timeouts from CI to Vercel */
     'https://www.webstackbuilders.com',
     'https://www.webstackbuilders.com/rss.xml',
+    /** Allow-listed external links to avoid timeouts */
+    'https://webstackdev.github.io/',
+    'https://www.keithcirkel.co.uk/metaprogramming-in-es6-part-3-proxies/',
+    'https://typedoc.org',
   ],
   externalTimeout: 15000,
   failOnBrokenLinks: true,

src/lib/config/markdown.ts

@@ -465,8 +465,8 @@ export const markdownConfig: Partial<MdxOptions> = {
         themes: shikiConfigOptions.themes,
         defaultColor: shikiConfigOptions.defaultColor,
         langAlias: shikiConfigOptions.langAlias,
-        wrap: false,
-        excludeLangs: ['mermaid', 'math'],
+        wrap: true,
+        excludeLangs: ['text', 'mermaid', 'math'],
       },
     ],
     /**