astro-better-release-notes 0.2.1 → 0.2.3

package/README.md

@@ -92,9 +92,9 @@ const rendered = await Promise.all(
 
 Two CSS custom properties control the positioning:
 
-`--release-notes-top` — how far the sticky header sits from the viewport top (should match your site's fixed nav height). Default: `3.5rem`.
+`--release-notes-top` -- how far the sticky header sits from the viewport top (should match your site's fixed nav height). Default: `3.5rem`.
 
-`--release-notes-scroll-margin` — the `scroll-margin-top` applied to both version articles and individual release note rows when navigating via anchor links. Should be at least as large as your total sticky height (nav + release-notes sticky header). Default: `5rem`.
+`--release-notes-scroll-margin` -- the `scroll-margin-top` applied to version headings and individual release note rows, which are the targets of anchor links and the version selector. Set it to at least the distance from the viewport top to the bottom edge of the release notes sticky header (your nav plus the selector and chip rows), or anchored headings land underneath the header. The chip rows wrap with viewport width, so measure at your breakpoints. Default: `5rem`.
 
 ```css
 /* in your root layout or global CSS */
@@ -115,20 +115,42 @@ Set both variables on `html` or any ancestor of `.release-container`.
 
 ### Link colors
 
-The github issue links and category badge hover colors are configurable:
+The issue links, version permalinks (`#`), and category badge hover colors are configurable:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `--release-notes-link-color` | `#4338ca` (indigo-700) | Issue link color |
-| `--release-notes-link-hover-color` | `#9a3412` (orange-800) | Hover color for links and badge |
-| `--release-notes-link-color-dark` | `#818cf8` (indigo-400) | Dark mode link color |
+| `--release-notes-link-color` | `#4338ca` (indigo-700) | Issue link and permalink color |
+| `--release-notes-link-hover-color` | `#9a3412` (orange-800) | Hover color for links, permalinks, and badges |
+| `--release-notes-link-color-dark` | `#818cf8` (indigo-400) | Dark mode link and permalink color |
 | `--release-notes-link-hover-color-dark` | `#fed7aa` (orange-200) | Dark mode hover color |
+| `--release-notes-anchor-size` | `1.5em` | Font size of the version permalink; match it to your `h2` size |
+
+The permalink sits beside the version heading rather than inside it, so it doesn't inherit the heading's size. Set `--release-notes-anchor-size` if your `h2` isn't `1.5em`.
+
+### Theme variables
+
+Set these on `:root` (and `.dark` for dark mode) to match your site. Each falls back to the default shown.
+
+| Variable | Light default | Dark default | Used for |
+|----------|---------------|--------------|----------|
+| `--rn-bg` | `white` | `#0f172a` | Sticky header background |
+| `--rn-border` | `#d1d5db` | `#4b5563` | Selector and filter button borders |
+| `--rn-input-bg` | `#f3f4f6` | `#1e293b` | Selector and filter button background |
+| `--rn-text` | `#111827` | `#cbd5e1` | Selector text |
+| `--rn-text-muted` | `#374151` | `#cbd5e1` | Filter button text |
+| `--rn-focus` | `#6366f1` | `#818cf8` | Focus rings and the active-filter indicator |
+| `--rn-chip-bg` | `#f1f5f9` | `#1e293b` | Unselected chip background |
+| `--rn-chip-border` | `#cbd5e1` | `#475569` | Unselected chip border |
+| `--rn-chip-color` | `#334155` | `#cbd5e1` | Unselected chip text |
+| `--rn-color-{category}` | see `DEFAULT_CATEGORIES` | same | Category color for chips and badges |
+
+If you map these to your own palette, check that `--rn-chip-color` and `--rn-text-muted` keep a 4.5:1 contrast ratio against `--rn-chip-bg` and `--rn-input-bg`.
 
 ### Mobile filter behavior
 
 On narrow screens the category filter chips are hidden behind a "Filter" toggle button that sits next to the version selector. Tapping it expands the chips below the selector row. When any filter is active, the button changes color as a visual indicator.
 
-On screens 768px and wider, the chips are always visible.
+On screens 1024px and wider, the chips are always visible.
 
 ## Custom categories
 
@@ -211,6 +233,30 @@ import { ReleaseNotesSelector } from 'astro-better-release-notes';
 </div>
 ```
 
+## Accessibility
+
+- Each version is an `<article>` labelled by its `<h2>`. The `<h2>` carries the anchor id (`version-1-2-3`), so fragment links, search crawlers, and TOC tools all resolve to the heading. The `#` permalink sits next to the heading rather than inside it, so the heading's accessible name is only the version.
+- Category filters are native checkboxes inside a `<fieldset>` with a visually hidden `<legend>`. They work with Tab and Space, show a focus ring on the chip, and announce their checked state. Selected chips show a check mark as well as color.
+- Badge and selected-chip text colors are mixed from the category color (darker in light mode, lighter in dark mode), so they stay at or above 4.5:1 for the default categories and for most custom mid-tone colors.
+- The version selector has a label, and its options are bare version numbers, so typing `1.56` jumps to 1.56.0. Each jump is announced through a polite live region. Focus stays on the selector so type-ahead and arrow keys keep working: the selector scrolls with `scrollIntoView` and updates the URL with `history.replaceState`, because assigning `location.hash` would blur it. Jumps don't add browser history entries.
+- Transitions and the badge hover scale are disabled under `prefers-reduced-motion: reduce`.
+- The package ships its own `.rn-sr-only` class, so it doesn't depend on a host `sr-only` utility.
+
+## Upgrading to 0.2.3
+
+- Version selector options no longer start with "Version" (`1.56.0 (SSO Snake)` instead of `Version 1.56.0 (SSO Snake)`).
+- Choosing a version updates the URL with `history.replaceState` instead of a new history entry, so the Back button leaves the page rather than stepping back through jumps.
+- The version permalink now uses the link color variables and `--release-notes-anchor-size` instead of inheriting the surrounding text color and size.
+
+## Upgrading to 0.2.2
+
+Anchor URLs are unchanged, but the markup moved:
+
+- The version id moved from `<article class="version">` to its `<h2>`. Update any CSS or scripts that target `article.version[id]` or `.version:target`.
+- `--release-notes-scroll-margin` now applies to the heading instead of the article, which starts slightly higher. If anchored headings land under your sticky header, increase the value (see [Sticky offset and scroll margins](#sticky-offset-and-scroll-margins)).
+- The permalink is now `.version-title .anchor-link`, outside the `<h2>`. Selectors using `.release-note .anchor-link` need updating.
+- The filter container is a `<fieldset>` instead of a `<nav>`, and keeps the `release-notes-filters` id and `filter-controls` class.
+
 ## Dark mode
 
 The stylesheet uses a `.dark` ancestor class (compatible with Tailwind's `darkMode: 'class'`). To also enable automatic OS-based dark mode, add to your project CSS:

package/ReleaseNotes.astro

@@ -71,6 +71,7 @@ const filterCSS = [
     {showSelector && <ReleaseNotesSelector {updates} />}
 
     <button
+      type="button"
       class="filter-toggle-btn"
       aria-expanded="false"
       aria-controls="release-notes-filters"
@@ -81,14 +82,15 @@ const filterCSS = [
       Filter
     </button>
 
-    <nav id="release-notes-filters" class="filter-controls" aria-label="Filter release notes by category">
+    <fieldset id="release-notes-filters" class="filter-controls">
+      <legend class="rn-sr-only">Show only these categories</legend>
       {categories.map(cat => (
         <label class="filter-chip" style={`--cat-color: ${cat.color}`}>
-          <input type="checkbox" id={`toggle-${cat.id}`} class="filter-input" aria-label={`Show ${cat.label}`} />
-          <span aria-hidden="true">{cat.label}</span>
+          <input type="checkbox" id={`toggle-${cat.id}`} class="filter-input" />
+          {cat.label}
         </label>
       ))}
-    </nav>
+    </fieldset>
 
     <noscript><style>@media (max-width: 1023px) { #release-notes-filters { display: flex !important; flex-wrap: wrap; } .filter-toggle-btn { display: none !important; } }</style></noscript>
   </div>
@@ -98,12 +100,15 @@ const filterCSS = [
       const { Content } = item;
       const versionId = `version-${item.data.version.replaceAll('.', '-')}`;
       return (
-        <article id={versionId} class="version">
+        <article class="version" aria-labelledby={versionId}>
           <header class="version-header">
-            <h2 class="release-note group">
-              Version {item.data.version} {item.data.name && `(${item.data.name})`}
-              <a class="anchor-link" title="copy header link" href={`#${versionId}`} aria-label={`Permalink to version ${item.data.version}`}>#</a>
-            </h2>
+            {/* id on h2 so crawlers resolve anchors; permalink outside h2 keeps the heading name clean */}
+            <div class="version-title">
+              <h2 id={versionId} class="release-note">
+                Version {item.data.version}{item.data.name && ` (${item.data.name})`}
+              </h2>
+              <a class="anchor-link" href={`#${versionId}`} aria-label={`Permalink to version ${item.data.version}`}>#</a>
+            </div>
             <time class="version-date" datetime={item.data.date.toISOString()}>
               {item.data.date.toLocaleDateString('en-GB', { year: 'numeric', month: 'long', day: 'numeric' })}
             </time>

package/ReleaseNotesSelector.astro

@@ -15,7 +15,7 @@ const { updates } = Astro.props as Props;
 ---
 
 <div class="release-selector">
-  <label for="release-notes-version" class="sr-only">Jump to a release version</label>
+  <label for="release-notes-version" class="rn-sr-only">Jump to a release version</label>
   <select
     id="release-notes-version"
     class="release-selector-select"
@@ -23,19 +23,24 @@ const { updates } = Astro.props as Props;
     <option value="">Jump to a version...</option>
     {updates.map((item) => {
       const versionId = `version-${item.data.version.replaceAll('.', '-')}`;
-      const label = `Version ${item.data.version}${item.data.name ? ` (${item.data.name})` : ''}`;
+      // bare version so typing in the select jumps straight to it; the label supplies the context
+      const label = `${item.data.version}${item.data.name ? ` (${item.data.name})` : ''}`;
       return <option value={versionId}>{label}</option>;
     })}
   </select>
+  <p id="release-notes-version-status" class="rn-sr-only" aria-live="polite"></p>
 </div>
 
 <script is:inline>
   const initVersionSpy = () => {
+    // each article's anchor id lives on its h2
+    const headingId = (article) => article.querySelector('h2[id]')?.id;
     const selectEl = document.getElementById('release-notes-version');
     if (!selectEl) return;
 
     const placeholderOption = selectEl.querySelector('option[value=""]');
-    const versions = Array.from(document.querySelectorAll('article.version[id]'));
+    const statusEl = document.getElementById('release-notes-version-status');
+    const versions = Array.from(document.querySelectorAll('article.version')).filter(a => headingId(a));
     if (versions.length === 0) return;
 
     const HEADER_OFFSET = 210;
@@ -61,9 +66,14 @@ const { updates } = Astro.props as Props;
         }
       }
 
-      if (activeArticle && activeArticle.id !== currentActiveId) {
-        currentActiveId = activeArticle.id;
-        selectEl.value = activeArticle.id;
+      if (activeArticle) currentActiveId = headingId(activeArticle);
+      // writing value mid-interaction resets native type-ahead, so wait for blur
+      if (document.activeElement !== selectEl) syncSelect();
+    };
+
+    const syncSelect = () => {
+      if (currentActiveId && selectEl.value !== currentActiveId) {
+        selectEl.value = currentActiveId;
         disablePlaceholder();
       }
     };
@@ -79,17 +89,25 @@ const { updates } = Astro.props as Props;
       }
     };
 
-    // navigate on change; aria-live on the region announces the jump for screen readers
+    // hide the placeholder before typing starts; changing options mid-type-ahead resets it
+    selectEl.addEventListener('focus', disablePlaceholder, { once: true });
+    selectEl.addEventListener('blur', syncSelect);
+
+    // location.hash blurs the select (breaks type-ahead/arrows); replaceState also skips per-key history entries
     selectEl.addEventListener('change', () => {
       hasUserInteracted = true;
       disablePlaceholder();
-      if (selectEl.value) window.location.hash = selectEl.value;
+      const target = selectEl.value && document.getElementById(selectEl.value);
+      if (!target) return;
+      history.replaceState(history.state, '', `#${selectEl.value}`);
+      target.scrollIntoView({ block: 'start' });
+      if (statusEl) statusEl.textContent = `Jumped to version ${selectEl.selectedOptions[0]?.textContent ?? selectEl.value}`;
     });
 
     const filterControls = document.querySelector('.filter-controls');
     if (filterControls) {
       filterControls.addEventListener('change', () => {
-        const targetVersion = versions.find(a => a.id === currentActiveId) || versions[0];
+        const targetVersion = versions.find(a => headingId(a) === currentActiveId) || versions[0];
         window.requestAnimationFrame(() => {
           if (targetVersion && hasUserInteracted) {
             const adjustment = targetVersion.getBoundingClientRect().top - HEADER_OFFSET;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-better-release-notes",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Configurable release notes components with category filtering and version navigation for Astro",
   "keywords": [
     "astro",

package/style.css

@@ -162,21 +162,38 @@
   flex-wrap: wrap;
   gap: 0.75rem;
   padding: 0.25rem 0;
+  /* fieldset resets */
+  border: 0;
+  margin: 0;
+  min-inline-size: 0;
 }
 
+/* visually hidden but still focusable and announced; the chip shows its state */
 .filter-input {
-  display: none;
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+.filter-chip:has(.filter-input:focus-visible) {
+  outline: 2px solid var(--rn-focus, #6366f1);
+  outline-offset: 2px;
 }
 
 .filter-chip {
+  position: relative;
   padding: 0.5rem 1rem;
   font-size: 0.875rem;
   font-weight: 500;
   border-radius: 9999px;
   cursor: pointer;
   transition: filter 0.15s ease-in-out;
-  opacity: 0.7;
-  filter: grayscale(100%);
   color: var(--rn-chip-color, #334155);
   background-color: var(--rn-chip-bg, #f1f5f9);
   border: 1px solid var(--rn-chip-border, #cbd5e1);
@@ -189,19 +206,28 @@
 }
 
 .filter-chip:hover {
-  filter: grayscale(100%) brightness(0.95);
+  filter: brightness(0.95);
 }
 
 .dark .filter-chip:hover {
-  filter: grayscale(100%) brightness(1.1);
+  filter: brightness(1.1);
 }
 
+/* selected: tint + border + check so state isn't color-only; text mixes keep 4.5:1 */
 .filter-chip:has(input:checked) {
-  filter: grayscale(0);
-  opacity: 1;
-  background-color: var(--cat-color) !important;
+  background-color: color-mix(in srgb, var(--cat-color) 18%, white) !important;
   border-color: var(--cat-color) !important;
-  color: #fff !important;
+  color: color-mix(in srgb, var(--cat-color) 45%, black) !important;
+}
+
+.dark .filter-chip:has(input:checked) {
+  background-color: color-mix(in srgb, var(--cat-color) 18%, #1e293b) !important;
+  color: color-mix(in srgb, var(--cat-color) 60%, white) !important;
+}
+
+.filter-chip:has(input:checked)::before {
+  content: "\2713" / "";
+  margin-right: 0.375rem;
 }
 
 /* ---------------------------------------------------------------
@@ -261,10 +287,14 @@
   transition: transform 0.15s ease-out, color 0.15s ease-out;
   transform-origin: left center;
   background-color: color-mix(in srgb, var(--cat-color) 13%, transparent);
-  color: var(--cat-color);
+  color: color-mix(in srgb, var(--cat-color) 45%, black);
   border: 1px solid color-mix(in srgb, var(--cat-color) 27%, transparent);
 }
 
+.dark .issue-badge {
+  color: color-mix(in srgb, var(--cat-color) 60%, white);
+}
+
 .issue-badge:hover {
   transform: scale(1.05);
   color: var(--release-notes-link-hover-color, #9a3412);
@@ -323,7 +353,13 @@
    Version articles
 --------------------------------------------------------------- */
 
-.version {
+.version-title {
+  display: flex;
+  align-items: baseline;
+}
+
+/* the heading carries the anchor id */
+.release-note[id] {
   scroll-margin-top: var(--release-notes-scroll-margin, 5rem);
 }
 
@@ -345,20 +381,67 @@
   color: #64748b;
 }
 
+.dark .version-date { color: #94a3b8; }
+
 /* ---------------------------------------------------------------
    Version anchor links (# permalink)
 --------------------------------------------------------------- */
 
-.release-note .anchor-link {
+/* sits beside the h2, not inside it, so size it to match the heading */
+.version-title .anchor-link {
   opacity: 0;
+  font-size: var(--release-notes-anchor-size, 1.5em);
+  font-weight: 500;
   text-decoration: none;
   border: none;
   margin-left: 0.5rem;
-  color: inherit;
-  transition: opacity 0.15s ease;
+  color: var(--release-notes-link-color, #4338ca);
+  transition: opacity 0.15s ease, color 0.15s ease;
 }
 
-.release-note:hover .anchor-link,
-.release-note .anchor-link:focus-visible {
+.version-title:hover .anchor-link,
+.version-title .anchor-link:focus-visible {
   opacity: 1;
 }
+
+.version-title .anchor-link:hover {
+  color: var(--release-notes-link-hover-color, #9a3412);
+}
+
+.dark .version-title .anchor-link {
+  color: var(--release-notes-link-color-dark, #818cf8);
+}
+
+.dark .version-title .anchor-link:hover {
+  color: var(--release-notes-link-hover-color-dark, #fed7aa);
+}
+
+/* ---------------------------------------------------------------
+   Utilities and motion
+--------------------------------------------------------------- */
+
+.rn-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .filter-chip,
+  .issue-badge,
+  .github-link,
+  .version-title .anchor-link {
+    transition: none;
+  }
+
+  .issue-badge:hover,
+  .issue-badge:active {
+    transform: none;
+  }
+}