astro-better-release-notes 0.2.1 → 0.2.2

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 */
@@ -124,11 +124,30 @@ The github issue links and category badge hover colors are configurable:
 | `--release-notes-link-color-dark` | `#818cf8` (indigo-400) | Dark mode link color |
 | `--release-notes-link-hover-color-dark` | `#fed7aa` (orange-200) | Dark mode hover color |
 
+### 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 +230,24 @@ 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 announces each jump through a polite live region. Focus stays on the selector, because Chrome and Edge on Windows fire `change` on every arrow key press.
+- 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.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"
@@ -27,15 +27,19 @@ const { updates } = Astro.props as Props;
       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 +65,9 @@ const { updates } = Astro.props as Props;
         }
       }
 
-      if (activeArticle && activeArticle.id !== currentActiveId) {
-        currentActiveId = activeArticle.id;
-        selectEl.value = activeArticle.id;
+      if (activeArticle && headingId(activeArticle) !== currentActiveId) {
+        currentActiveId = headingId(activeArticle);
+        selectEl.value = currentActiveId;
         disablePlaceholder();
       }
     };
@@ -79,17 +83,19 @@ const { updates } = Astro.props as Props;
       }
     };
 
-    // navigate on change; aria-live on the region announces the jump for screen readers
+    // focus stays on the select (arrow keys fire change on windows), so announce the jump instead
     selectEl.addEventListener('change', () => {
       hasUserInteracted = true;
       disablePlaceholder();
-      if (selectEl.value) window.location.hash = selectEl.value;
+      if (!selectEl.value) return;
+      window.location.hash = selectEl.value;
+      if (statusEl) statusEl.textContent = `Jumped to ${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.2",
   "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,11 +381,13 @@
   color: #64748b;
 }
 
+.dark .version-date { color: #94a3b8; }
+
 /* ---------------------------------------------------------------
    Version anchor links (# permalink)
 --------------------------------------------------------------- */
 
-.release-note .anchor-link {
+.version-title .anchor-link {
   opacity: 0;
   text-decoration: none;
   border: none;
@@ -358,7 +396,37 @@
   transition: opacity 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;
 }
+
+/* ---------------------------------------------------------------
+   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;
+  }
+}