astro-better-release-notes 0.1.0 → 0.1.1

package/README.md

@@ -18,9 +18,9 @@ import 'astro-better-release-notes/style.css';
 
 ## Components
 
-- `ReleaseNotes` - renders the filter chips and the full version list
+- `ReleaseNotes` - renders a unified sticky header (version selector + category filter chips) and the full version list
 - `ReleaseNotesItem` - a single categorized release note row (used inside MDX content)
-- `ReleaseNotesSelector` - a sticky version jump dropdown
+- `ReleaseNotesSelector` - a standalone version jump dropdown (for custom layouts that need it separately)
 
 ## Usage
 
@@ -54,14 +54,12 @@ import { ReleaseNotesItem } from 'astro-better-release-notes';
 
 ### Page component
 
+`ReleaseNotes` renders everything in one call: a sticky header containing the version selector and filter chips, then the full version list below.
+
 ```astro
 ---
 import { getCollection, render } from 'astro:content';
-import {
-  ReleaseNotes,
-  ReleaseNotesSelector,
-  DEFAULT_CATEGORIES,
-} from 'astro-better-release-notes';
+import { ReleaseNotes, DEFAULT_CATEGORIES } from 'astro-better-release-notes';
 
 const allUpdates = await getCollection('releases');
 const updates = allUpdates
@@ -78,10 +76,60 @@ const rendered = await Promise.all(
 );
 ---
 
-<ReleaseNotesSelector updates={rendered} />
 <ReleaseNotes updates={rendered} categories={DEFAULT_CATEGORIES} />
 ```
 
+### ReleaseNotes props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `updates` | `ReleaseEntry[]` | required | Pre-rendered version entries |
+| `categories` | `Category[]` | `DEFAULT_CATEGORIES` | Category definitions |
+| `components` | `Record<string, any>` | `{}` | Component overrides (e.g. custom `ReleaseNotesItem`) |
+| `showSelector` | `boolean` | `true` | Set `false` to hide the version jump dropdown |
+
+### Sticky offset and scroll margins
+
+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-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`.
+
+```css
+/* in your root layout or global CSS */
+html {
+  --release-notes-top: 56px;
+  --release-notes-scroll-margin: 6rem; /* nav + sticky header height */
+}
+
+@media (min-width: 1024px) {
+  html {
+    --release-notes-top: 80px;
+    --release-notes-scroll-margin: 11rem;
+  }
+}
+```
+
+Set both variables on `html` or any ancestor of `.release-container`.
+
+### Link colors
+
+The github issue links 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-hover-color-dark` | `#fed7aa` (orange-200) | Dark mode hover color |
+
+### 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.
+
 ## Custom categories
 
 Pass a `categories` array to `ReleaseNotes` to define your own set:
@@ -131,8 +179,6 @@ Note: for the `components` injection to work with categories, you also need to p
 import { getCategoryColor, getCategoryLabel, DEFAULT_CATEGORIES } from 'astro-better-release-notes';
 ```
 
-Or provide these values in your own wrapper by computing them from your category list.
-
 ## ReleaseNotesItem props
 
 | Prop | Type | Description |
@@ -153,6 +199,28 @@ Or provide these values in your own wrapper by computing them from your category
 
 `ReleaseNotes.astro` does not automatically inject `categoryColor`/`categoryLabel` into the MDX-rendered items -- those props come from the MDX markup. To automate this, create a wrapper that looks up the category in your list and injects the values, then pass it via `components`.
 
+## Standalone ReleaseNotesSelector
+
+`ReleaseNotesSelector` is available as a standalone component for custom layouts that need the version dropdown without the rest of the notes. It is not sticky by default; wrap it in your own sticky container if needed.
+
+```astro
+import { ReleaseNotesSelector } from 'astro-better-release-notes';
+---
+<div style="position: sticky; top: 56px;">
+  <ReleaseNotesSelector {updates} />
+</div>
+```
+
 ## Dark mode
 
-The stylesheet supports both `@media (prefers-color-scheme: dark)` and a `.dark` ancestor class.
+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:
+
+```css
+@media (prefers-color-scheme: dark) {
+  html:not([data-theme="light"]) {
+    /* copy the .dark rules you need, or add the .dark class via JS */
+  }
+}
+```
+
+Most Tailwind setups initialize the `.dark` class from OS preference on first load, so no extra CSS is needed.

package/ReleaseNotes.astro

@@ -1,5 +1,6 @@
 ---
 import ReleaseNotesItem from './ReleaseNotesItem.astro';
+import ReleaseNotesSelector from './ReleaseNotesSelector.astro';
 
 export interface Category {
   id: string;
@@ -41,12 +42,15 @@ export interface Props {
   categories?: Category[];
   // pass { ReleaseNotesItem: YourWrapper } to inject a custom item component
   components?: Record<string, any>;
+  // set false to hide the version jump dropdown
+  showSelector?: boolean;
 }
 
 const {
   updates,
   categories = DEFAULT_CATEGORIES,
   components: extraComponents = {},
+  showSelector = true,
 } = Astro.props as Props;
 
 const mergedComponents = { ReleaseNotesItem, ...extraComponents };
@@ -63,14 +67,31 @@ const filterCSS = [
 <Fragment set:html={`<style>${filterCSS}</style>`} />
 
 <div class="release-container">
-  <nav class="filter-controls" aria-label="Filter release notes by category">
-    {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>
-      </label>
-    ))}
-  </nav>
+  <div class="release-sticky-header">
+    {showSelector && <ReleaseNotesSelector {updates} />}
+
+    <button
+      class="filter-toggle-btn"
+      aria-expanded="false"
+      aria-controls="release-notes-filters"
+    >
+      <svg xmlns="http://www.w3.org/2000/svg" width="15" height="15" viewBox="0 0 16 16" aria-hidden="true" fill="currentColor">
+        <path d="M6 10.5a.5.5 0 0 1 .5-.5h3a.5.5 0 0 1 0 1h-3a.5.5 0 0 1-.5-.5zm-2-3a.5.5 0 0 1 .5-.5h7a.5.5 0 0 1 0 1h-7a.5.5 0 0 1-.5-.5zm-2-3a.5.5 0 0 1 .5-.5h11a.5.5 0 0 1 0 1h-11a.5.5 0 0 1-.5-.5z"/>
+      </svg>
+      Filter
+    </button>
+
+    <nav id="release-notes-filters" class="filter-controls" aria-label="Filter release notes by category">
+      {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>
+        </label>
+      ))}
+    </nav>
+
+    <noscript><style>@media (max-width: 767px) { #release-notes-filters { display: flex !important; flex-wrap: wrap; } .filter-toggle-btn { display: none !important; } }</style></noscript>
+  </div>
 
   <div class="version-list">
     {updates.map((item) => {
@@ -96,3 +117,18 @@ const filterCSS = [
     })}
   </div>
 </div>
+
+<script is:inline>
+  const initFilterToggle = () => {
+    const btn = document.querySelector('.filter-toggle-btn');
+    const nav = document.getElementById('release-notes-filters');
+    if (!btn || !nav) return;
+    btn.addEventListener('click', () => {
+      const expanded = btn.getAttribute('aria-expanded') === 'true';
+      btn.setAttribute('aria-expanded', String(!expanded));
+      nav.classList.toggle('is-open', !expanded);
+    });
+  };
+  document.addEventListener('DOMContentLoaded', initFilterToggle);
+  document.addEventListener('astro:page-load', initFilterToggle);
+</script>

package/ReleaseNotesItem.astro

@@ -67,7 +67,7 @@ const rowId = baseId ? `${baseId}--${contentSlug}` : contentSlug;
 >
   <a
     href={`#${rowId}`}
-    class="issue-badge"
+    class="issue-badge not-prose"
     aria-label={`${label} - permalink to this release note`}
   >
     {label}
@@ -106,12 +106,12 @@ const rowId = baseId ? `${baseId}--${contentSlug}` : contentSlug;
 
   {issue && (
     issueBaseUrl
-      ? <a class="github-link" target="_blank" rel="noopener noreferrer" href={`${issueBaseUrl}${issue}`}>#{issue}</a>
+      ? <a class="github-link not-prose" target="_blank" rel="noopener noreferrer" href={`${issueBaseUrl}${issue}`}>#{issue}</a>
       : <span class="github-link">#{issue}</span>
   )}
   {bonusIssue && (
     issueBaseUrl
-      ? <a class="github-link" target="_blank" rel="noopener noreferrer" href={`${issueBaseUrl}${bonusIssue}`}>#{bonusIssue}</a>
+      ? <a class="github-link not-prose" target="_blank" rel="noopener noreferrer" href={`${issueBaseUrl}${bonusIssue}`}>#{bonusIssue}</a>
       : <span class="github-link">#{bonusIssue}</span>
   )}
 </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-better-release-notes",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Configurable release notes components with category filtering and version navigation for Astro",
   "type": "module",
   "exports": {

package/style.css

@@ -4,20 +4,151 @@
   Import this in your project root layout to enable release notes styles.
   No external dependencies -- no Tailwind, no framework.
 
-  Dark mode: supports both @media (prefers-color-scheme: dark) and a .dark
-  ancestor class (e.g. Tailwind's darkMode: 'class').
+  Dark mode: uses a .dark ancestor class (e.g. Tailwind's darkMode: 'class').
+  See README for enabling OS-based dark mode without a class toggle.
 
   Category colors are driven by --cat-color, set inline by ReleaseNotesItem.
+
+  Sticky offset configuration:
+    Set --release-notes-top on :root (or any ancestor of .release-sticky-header)
+    to match your site's fixed navigation height. Defaults to 3.5rem (56px).
+
+    Example:
+      :root { --release-notes-top: 57px; }
+      @media (min-width: 1024px) { :root { --release-notes-top: 80px; } }
 */
 
+/* ---------------------------------------------------------------
+   Sticky header (selector + filter toggle + chips)
+--------------------------------------------------------------- */
+
+.release-sticky-header {
+  position: sticky;
+  top: var(--release-notes-top, 3.5rem);
+  z-index: 11;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.5rem 0;
+  background-color: white;
+  box-shadow: 0 1px 0 rgba(0, 0, 0, 0.06);
+  margin-bottom: 0.5rem;
+}
+
+.dark .release-sticky-header {
+  background-color: #0f172a;
+  box-shadow: 0 1px 0 rgba(255, 255, 255, 0.06);
+}
+
+/* ---------------------------------------------------------------
+   Version selector (jump dropdown)
+--------------------------------------------------------------- */
+
+.release-selector {
+  flex: 1;
+  min-width: 200px;
+}
+
+.release-selector-select {
+  width: 100%;
+  height: 2.5rem;
+  padding: 0 0.5rem;
+  border-radius: 6px;
+  border: 2px solid #d1d5db;
+  background-color: #f3f4f6;
+  color: #111827;
+  cursor: pointer;
+}
+
+.release-selector-select:focus {
+  outline: 2px solid #6366f1;
+  outline-offset: 1px;
+}
+
+.dark .release-selector-select {
+  border-color: #4b5563;
+  background-color: #1e293b;
+  color: #cbd5e1;
+}
+
+/* ---------------------------------------------------------------
+   Filter toggle button (mobile only)
+--------------------------------------------------------------- */
+
+.filter-toggle-btn {
+  flex: 0 0 auto;
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
+  padding: 0.4375rem 0.75rem;
+  height: 2.5rem;
+  font-size: 0.875rem;
+  font-weight: 500;
+  border-radius: 6px;
+  border: 2px solid #d1d5db;
+  background-color: #f3f4f6;
+  color: #374151;
+  cursor: pointer;
+  white-space: nowrap;
+}
+
+.filter-toggle-btn:focus {
+  outline: 2px solid #6366f1;
+  outline-offset: 1px;
+}
+
+.dark .filter-toggle-btn {
+  border-color: #4b5563;
+  background-color: #1e293b;
+  color: #cbd5e1;
+}
+
+/* indicate active filters */
+.release-container:has(.filter-input:checked) .filter-toggle-btn {
+  border-color: #6366f1;
+  background-color: color-mix(in srgb, #6366f1 12%, transparent);
+  color: #6366f1;
+}
+
+.dark .release-container:has(.filter-input:checked) .filter-toggle-btn {
+  border-color: #818cf8;
+  color: #818cf8;
+  background-color: color-mix(in srgb, #818cf8 15%, transparent);
+}
+
+@media (min-width: 768px) {
+  .filter-toggle-btn {
+    display: none;
+  }
+}
+
 /* ---------------------------------------------------------------
    Filter controls (category chips)
 --------------------------------------------------------------- */
 
+/* hidden on mobile by default; shown via .is-open (JS) or desktop breakpoint */
+@media (max-width: 767px) {
+  .filter-controls {
+    display: none;
+  }
+
+  .filter-controls.is-open {
+    display: flex;
+  }
+}
+
+@media (min-width: 768px) {
+  .filter-controls {
+    display: flex;
+  }
+}
+
 .filter-controls {
-  display: flex;
+  flex: 0 0 100%;
   flex-wrap: wrap;
   gap: 0.75rem;
+  padding: 0.25rem 0;
 }
 
 .filter-input {
@@ -38,14 +169,6 @@
   border: 1px solid #cbd5e1;
 }
 
-@media (prefers-color-scheme: dark) {
-  .filter-chip {
-    color: #cbd5e1;
-    background-color: #1e293b;
-    border-color: #475569;
-  }
-}
-
 .dark .filter-chip {
   color: #cbd5e1;
   background-color: #1e293b;
@@ -56,12 +179,6 @@
   filter: grayscale(100%) brightness(0.95);
 }
 
-@media (prefers-color-scheme: dark) {
-  .filter-chip:hover {
-    filter: grayscale(100%) brightness(1.1);
-  }
-}
-
 .dark .filter-chip:hover {
   filter: grayscale(100%) brightness(1.1);
 }
@@ -89,7 +206,7 @@
   transition: border-color 0.2s;
   padding: 6px 8px;
   border: 2px solid transparent;
-  scroll-margin-top: 5rem;
+  scroll-margin-top: var(--release-notes-scroll-margin, 5rem);
 }
 
 @media (min-width: 768px) {
@@ -114,15 +231,22 @@
   text-decoration: none;
   cursor: pointer;
   user-select: none;
-  transition: transform 0.15s ease-out;
+  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);
   border: 1px solid color-mix(in srgb, var(--cat-color) 27%, transparent);
 }
 
-.issue-badge:hover { transform: scale(1.05); }
+.issue-badge:hover {
+  transform: scale(1.05);
+  color: var(--release-notes-link-hover-color, #9a3412);
+  text-decoration: none;
+}
 .issue-badge:active { transform: scale(0.95); }
+.dark .issue-badge:hover {
+  color: var(--release-notes-link-hover-color-dark, #fed7aa);
+}
 
 .issue-content {
   flex: 1;
@@ -145,29 +269,35 @@
   color: #475569;
 }
 
-@media (prefers-color-scheme: dark) {
-  .rni-thanks { color: #94a3b8; }
-}
-
 .dark .rni-thanks { color: #94a3b8; }
 
 .github-link {
   flex-shrink: 0;
   font-size: 0.875rem;
   text-decoration: none;
-  opacity: 0.7;
-  color: inherit;
+  color: var(--release-notes-link-color, #4338ca);
+  transition: color 0.15s;
+}
+
+.github-link:hover {
+  color: var(--release-notes-link-hover-color, #9a3412);
+  text-decoration: none;
+}
+
+.dark .github-link {
+  color: var(--release-notes-link-color-dark, #818cf8);
 }
 
-.github-link:hover { opacity: 1; text-decoration: underline; }
+.dark .github-link:hover {
+  color: var(--release-notes-link-hover-color-dark, #fed7aa);
+}
 
 /* ---------------------------------------------------------------
    Version articles
 --------------------------------------------------------------- */
 
 .version {
-  content-visibility: auto;
-  contain-intrinsic-size: 0 800px;
+  scroll-margin-top: var(--release-notes-scroll-margin, 5rem);
 }
 
 .version-header {
@@ -181,10 +311,6 @@
   border-bottom: 1px solid #e2e8f0;
 }
 
-@media (prefers-color-scheme: dark) {
-  .version-header { border-bottom-color: #1e293b; }
-}
-
 .dark .version-header { border-bottom-color: #1e293b; }
 
 .version-date {
@@ -193,42 +319,19 @@
 }
 
 /* ---------------------------------------------------------------
-   Version selector (jump dropdown)
+   Version anchor links (# permalink)
 --------------------------------------------------------------- */
 
-.release-selector {
-  position: sticky;
-  top: 2.75rem;
-  z-index: 10;
-  padding: 0.75rem 0;
-}
-
-.release-selector-select {
-  width: 100%;
-  height: 2.5rem;
-  padding: 0 0.5rem;
-  border-radius: 6px;
-  border: 2px solid #d1d5db;
-  background-color: #f3f4f6;
-  color: #111827;
-  cursor: pointer;
-}
-
-.release-selector-select:focus {
-  outline: 2px solid #6366f1;
-  outline-offset: 1px;
-}
-
-@media (prefers-color-scheme: dark) {
-  .release-selector-select {
-    border-color: #4b5563;
-    background-color: #1e293b;
-    color: #cbd5e1;
-  }
+.release-note .anchor-link {
+  opacity: 0;
+  text-decoration: none;
+  border: none;
+  margin-left: 0.5rem;
+  color: inherit;
+  transition: opacity 0.15s ease;
 }
 
-.dark .release-selector-select {
-  border-color: #4b5563;
-  background-color: #1e293b;
-  color: #cbd5e1;
+.release-note:hover .anchor-link,
+.release-note .anchor-link:focus-visible {
+  opacity: 1;
 }