astro-better-release-notes 0.1.0

package/README.md

@@ -0,0 +1,158 @@
+# astro-better-release-notes
+
+Configurable release notes components for Astro with category chip filtering, sticky version navigation, and deep-linkable release note items.
+
+## Installation
+
+```
+npm install astro-better-release-notes
+```
+
+Import the stylesheet once in your root layout:
+
+```astro
+---
+import 'astro-better-release-notes/style.css';
+---
+```
+
+## Components
+
+- `ReleaseNotes` - renders the filter chips and the full version list
+- `ReleaseNotesItem` - a single categorized release note row (used inside MDX content)
+- `ReleaseNotesSelector` - a sticky version jump dropdown
+
+## Usage
+
+### Content collection setup
+
+Your content collection entries must have at minimum:
+
+```ts
+// src/content.config.ts
+const releases = defineCollection({
+  schema: z.object({
+    version: z.string(),
+    date:    z.coerce.date(),
+    name:    z.string().optional(),
+  }),
+});
+```
+
+Each `.mdx` file in the collection uses `ReleaseNotesItem`:
+
+```mdx
+---
+version: "2.1.0"
+date: 2024-05-01
+---
+import { ReleaseNotesItem } from 'astro-better-release-notes';
+
+<ReleaseNotesItem category="new-feature">Added dark mode.</ReleaseNotesItem>
+<ReleaseNotesItem category="fix" issue="42" issueBaseUrl="https://github.com/org/repo/issues/">Fixed login redirect loop.</ReleaseNotesItem>
+```
+
+### Page component
+
+```astro
+---
+import { getCollection, render } from 'astro:content';
+import {
+  ReleaseNotes,
+  ReleaseNotesSelector,
+  DEFAULT_CATEGORIES,
+} from 'astro-better-release-notes';
+
+const allUpdates = await getCollection('releases');
+const updates = allUpdates
+  .sort((a, b) => {
+    const d = b.data.date.valueOf() - a.data.date.valueOf();
+    return d !== 0 ? d : b.data.version.localeCompare(a.data.version, undefined, { numeric: true });
+  });
+
+const rendered = await Promise.all(
+  updates.map(async item => {
+    const { Content } = await render(item);
+    return { data: item.data, Content };
+  })
+);
+---
+
+<ReleaseNotesSelector updates={rendered} />
+<ReleaseNotes updates={rendered} categories={DEFAULT_CATEGORIES} />
+```
+
+## Custom categories
+
+Pass a `categories` array to `ReleaseNotes` to define your own set:
+
+```js
+const MY_CATEGORIES = [
+  { id: 'new-feature', label: 'New Feature', color: '#16a34a' },
+  { id: 'fix',         label: 'Fix',         color: '#d97706' },
+  { id: 'security',    label: 'Security',    color: '#566f98' },
+];
+```
+
+Category IDs must match the `category` prop values used in your MDX files.
+
+## Custom ReleaseNotesItem
+
+To inject project-specific behavior (e.g. a fixed issue base URL), pass a wrapper component via the `components` prop:
+
+```astro
+---
+// src/components/MyReleaseNotesItem.astro
+import { ReleaseNotesItem } from 'astro-better-release-notes';
+const { issue, bonusIssue, ...rest } = Astro.props;
+const base = 'https://github.com/org/repo/issues/';
+---
+<ReleaseNotesItem
+  {...rest}
+  issue={issue}
+  bonusIssue={bonusIssue}
+  issueBaseUrl={base}
+  categoryColor={rest.categoryColor}
+  categoryLabel={rest.categoryLabel}
+><slot /></ReleaseNotesItem>
+```
+
+```astro
+<ReleaseNotes
+  updates={rendered}
+  categories={MY_CATEGORIES}
+  components={{ ReleaseNotesItem: MyReleaseNotesItem }}
+/>
+```
+
+Note: for the `components` injection to work with categories, you also need to pass `categoryColor` and `categoryLabel` in your wrapper. Use the exported helpers:
+
+```js
+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 |
+|------|------|-------------|
+| `category` | `string` | Category ID; must match a configured category |
+| `issue` | `string` | Issue number shown as a link at row end |
+| `bonusIssue` | `string` | Secondary issue number |
+| `thanks` | `string` | GitHub username to credit |
+| `bonusThanks` | `string` | Secondary GitHub username |
+| `since` | `string` | Version this was introduced |
+| `resolvedIn` | `string` | Version a known issue was resolved in |
+| `viaIssue` | `string` | Issue that resolved a known issue |
+| `issueBaseUrl` | `string` | Base URL for issue links (no default) |
+| `categoryColor` | `string` | CSS color for the badge (default `#71717a`) |
+| `categoryLabel` | `string` | Human label for the badge (default: generated from id) |
+
+## Injecting category color and label automatically
+
+`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`.
+
+## Dark mode
+
+The stylesheet supports both `@media (prefers-color-scheme: dark)` and a `.dark` ancestor class.

package/ReleaseNotes.astro

@@ -0,0 +1,98 @@
+---
+import ReleaseNotesItem from './ReleaseNotesItem.astro';
+
+export interface Category {
+  id: string;
+  label: string;
+  color: string;
+}
+
+export const DEFAULT_CATEGORIES: Category[] = [
+  { id: 'new-feature',        label: 'New Feature',        color: '#16a34a' },
+  { id: 'enhancement',        label: 'Enhancement',        color: '#2563eb' },
+  { id: 'fix',                label: 'Fix',                color: '#d97706' },
+  { id: 'security',           label: 'Security',           color: '#566f98' },
+  { id: 'deprecated',         label: 'Deprecated',         color: '#ffcc48' },
+  { id: 'breaking-change',    label: 'Breaking Change',    color: '#aaaa33' },
+  { id: 'known-issue',        label: 'Known Issue',        color: '#bb4448' },
+  { id: 'internal',           label: 'Internal',           color: '#71717a' },
+];
+
+export const getCategoryColor = (id: string, categories: Category[]) =>
+  categories.find(c => c.id === id)?.color ?? '#71717a';
+
+export const getCategoryLabel = (id: string, categories: Category[]) => {
+  const cat = categories.find(c => c.id === id);
+  if (cat) return cat.label;
+  return id.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+};
+
+export interface ReleaseEntry {
+  data: {
+    version: string;
+    date: Date;
+    name?: string;
+  };
+  Content: any;
+}
+
+export interface Props {
+  updates: ReleaseEntry[];
+  categories?: Category[];
+  // pass { ReleaseNotesItem: YourWrapper } to inject a custom item component
+  components?: Record<string, any>;
+}
+
+const {
+  updates,
+  categories = DEFAULT_CATEGORIES,
+  components: extraComponents = {},
+} = Astro.props as Props;
+
+const mergedComponents = { ReleaseNotesItem, ...extraComponents };
+
+// generate filter CSS from the configured categories
+const filterCSS = [
+  '.release-container:has(.filter-input:checked) .issue-row { display: none !important; }',
+  ...categories.map(cat =>
+    `.release-container:has(#toggle-${cat.id}:checked) [data-category="${cat.id}"] { display: flex !important; }`
+  ),
+].join('\n');
+---
+
+<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="version-list">
+    {updates.map((item) => {
+      const { Content } = item;
+      const versionId = `version-${item.data.version.replaceAll('.', '-')}`;
+      return (
+        <article id={versionId} class="version">
+          <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>
+            <time class="version-date" datetime={item.data.date.toISOString()}>
+              {item.data.date.toLocaleDateString('en-GB', { year: 'numeric', month: 'long', day: 'numeric' })}
+            </time>
+          </header>
+
+          <div class="version-content">
+            <Content components={mergedComponents} />
+          </div>
+        </article>
+      );
+    })}
+  </div>
+</div>

package/ReleaseNotesItem.astro

@@ -0,0 +1,117 @@
+---
+export interface Props {
+  category: string;
+  issue?: string;
+  bonusIssue?: string;
+  thanks?: string;
+  bonusThanks?: string;
+  since?: string;
+  resolvedIn?: string;
+  viaIssue?: string;
+  // base URL for issue links, e.g. "https://github.com/org/repo/issues/"
+  // if omitted, issue numbers are shown as plain text
+  issueBaseUrl?: string;
+  // color for this item's badge; if omitted, uses a neutral gray
+  categoryColor?: string;
+  // human-readable category label; if omitted, generated from id
+  categoryLabel?: string;
+}
+
+const {
+  category = 'fix',
+  issue,
+  bonusIssue,
+  thanks,
+  bonusThanks,
+  since,
+  resolvedIn,
+  viaIssue,
+  issueBaseUrl = '',
+  categoryColor = '#71717a',
+  categoryLabel,
+} = Astro.props as Props;
+
+const label = categoryLabel
+  ?? category.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+
+const versionPart = resolvedIn
+  ? `v-${resolvedIn.replaceAll('.', '-')}`
+  : (since ? `since-${since.replaceAll('.', '-')}` : '');
+
+const issuePart = issue
+  ? `issue-${issue}`
+  : (viaIssue ? `via-${viaIssue}` : '');
+
+const thanksPart = thanks
+  ? `thanks-${thanks.toLowerCase().replace(/[^a-z0-9]/g, '-')}`
+  : '';
+
+const baseId = [versionPart, category, issuePart, thanksPart].filter(Boolean).join('--');
+
+// deterministic content hash for unique deep-link IDs across builds
+const slotContent = await Astro.slots.render('default');
+let hash = 0;
+for (let i = 0; i < slotContent.length; i++) {
+  hash = (hash << 5) - hash + slotContent.charCodeAt(i);
+  hash |= 0;
+}
+const contentSlug = Math.abs(hash).toString(36).substring(0, 4);
+const rowId = baseId ? `${baseId}--${contentSlug}` : contentSlug;
+---
+
+<div
+  id={rowId}
+  class="issue-row"
+  data-category={category}
+  style={`--cat-color: ${categoryColor}`}
+>
+  <a
+    href={`#${rowId}`}
+    class="issue-badge"
+    aria-label={`${label} - permalink to this release note`}
+  >
+    {label}
+  </a>
+
+  <div class="issue-content">
+    <div class="rni-body">
+      <slot />
+      {resolvedIn && viaIssue && (
+        <p class="rni-meta">
+          Resolved in version{' '}
+          <a href={`#version-${resolvedIn.replaceAll('.', '-')}`}><code>{resolvedIn}</code></a>
+          {' '}via{' '}
+          {issueBaseUrl
+            ? <a target="_blank" rel="noopener noreferrer" href={`${issueBaseUrl}${viaIssue}`}>#{viaIssue}</a>
+            : <span>#{viaIssue}</span>
+          }.
+        </p>
+      )}
+      {since && (
+        <p class="rni-meta">
+          Since: <a href={`#version-${since.replaceAll('.', '-')}`}><code>{since}</code></a>
+        </p>
+      )}
+      {thanks && (
+        <p class="rni-meta rni-thanks">
+          Thanks to{' '}
+          <a href={`https://github.com/${thanks}`}>@{thanks}</a>
+          {bonusThanks && (
+            <span> and <a href={`https://github.com/${bonusThanks}`}>@{bonusThanks}</a></span>
+          )}!
+        </p>
+      )}
+    </div>
+  </div>
+
+  {issue && (
+    issueBaseUrl
+      ? <a class="github-link" 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>
+      : <span class="github-link">#{bonusIssue}</span>
+  )}
+</div>

package/ReleaseNotesSelector.astro

@@ -0,0 +1,109 @@
+---
+export interface SelectorEntry {
+  data: {
+    version: string;
+    date: Date;
+    name?: string;
+  };
+}
+
+export interface Props {
+  updates: SelectorEntry[];
+}
+
+const { updates } = Astro.props as Props;
+---
+
+<div class="release-selector">
+  <label for="release-notes-version" class="sr-only">Jump to a release version</label>
+  <select
+    id="release-notes-version"
+    class="release-selector-select"
+  >
+    <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})` : ''}`;
+      return <option value={versionId}>{label}</option>;
+    })}
+  </select>
+</div>
+
+<script is:inline>
+  const initVersionSpy = () => {
+    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]'));
+    if (versions.length === 0) return;
+
+    const HEADER_OFFSET = 210;
+    let currentActiveId = null;
+    let isTicking = false;
+    let hasUserInteracted = false;
+
+    const disablePlaceholder = () => {
+      if (placeholderOption && !placeholderOption.disabled) {
+        placeholderOption.disabled = true;
+        placeholderOption.hidden = true;
+      }
+    };
+
+    const updateScrollSpy = () => {
+      if (window.scrollY === 0 && !hasUserInteracted) return;
+
+      let activeArticle = versions[0];
+      for (let i = versions.length - 1; i >= 0; i--) {
+        if (versions[i].getBoundingClientRect().top < HEADER_OFFSET) {
+          activeArticle = versions[i];
+          break;
+        }
+      }
+
+      if (activeArticle && activeArticle.id !== currentActiveId) {
+        currentActiveId = activeArticle.id;
+        selectEl.value = activeArticle.id;
+        disablePlaceholder();
+      }
+    };
+
+    const onScroll = () => {
+      if (window.scrollY > 0) hasUserInteracted = true;
+      if (!isTicking) {
+        window.requestAnimationFrame(() => {
+          updateScrollSpy();
+          isTicking = false;
+        });
+        isTicking = true;
+      }
+    };
+
+    // navigate on change; aria-live on the region announces the jump for screen readers
+    selectEl.addEventListener('change', () => {
+      hasUserInteracted = true;
+      disablePlaceholder();
+      if (selectEl.value) window.location.hash = selectEl.value;
+    });
+
+    const filterControls = document.querySelector('.filter-controls');
+    if (filterControls) {
+      filterControls.addEventListener('change', () => {
+        const targetVersion = versions.find(a => a.id === currentActiveId) || versions[0];
+        window.requestAnimationFrame(() => {
+          if (targetVersion && hasUserInteracted) {
+            const adjustment = targetVersion.getBoundingClientRect().top - HEADER_OFFSET;
+            window.scrollBy({ top: adjustment, behavior: 'instant' });
+          }
+          updateScrollSpy();
+        });
+      });
+    }
+
+    window.addEventListener('scroll', onScroll, { passive: true });
+    updateScrollSpy();
+  };
+
+  document.addEventListener('DOMContentLoaded', initVersionSpy);
+  document.addEventListener('astro:page-load', initVersionSpy);
+</script>

package/index.js

@@ -0,0 +1,3 @@
+export { default as ReleaseNotes, DEFAULT_CATEGORIES, getCategoryColor, getCategoryLabel } from './ReleaseNotes.astro';
+export { default as ReleaseNotesItem } from './ReleaseNotesItem.astro';
+export { default as ReleaseNotesSelector } from './ReleaseNotesSelector.astro';

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "astro-better-release-notes",
+  "version": "0.1.0",
+  "description": "Configurable release notes components with category filtering and version navigation for Astro",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./style.css": "./style.css",
+    "./ReleaseNotes.astro": "./ReleaseNotes.astro",
+    "./ReleaseNotesItem.astro": "./ReleaseNotesItem.astro",
+    "./ReleaseNotesSelector.astro": "./ReleaseNotesSelector.astro"
+  },
+  "files": [
+    "*.js",
+    "*.astro",
+    "*.css"
+  ],
+  "keywords": ["astro", "release-notes", "changelog", "filter", "categories"],
+  "license": "MIT"
+}

package/style.css

@@ -0,0 +1,234 @@
+/*
+  astro-better-release-notes/style.css
+
+  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').
+
+  Category colors are driven by --cat-color, set inline by ReleaseNotesItem.
+*/
+
+/* ---------------------------------------------------------------
+   Filter controls (category chips)
+--------------------------------------------------------------- */
+
+.filter-controls {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.75rem;
+}
+
+.filter-input {
+  display: none;
+}
+
+.filter-chip {
+  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: #334155;
+  background-color: #f1f5f9;
+  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;
+  border-color: #475569;
+}
+
+.filter-chip:hover {
+  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);
+}
+
+.filter-chip:has(input:checked) {
+  filter: grayscale(0);
+  opacity: 1;
+  background-color: var(--cat-color) !important;
+  border-color: var(--cat-color) !important;
+  color: #fff !important;
+}
+
+/* ---------------------------------------------------------------
+   Release note rows
+   Note: per-category show/hide rules are generated dynamically
+   by ReleaseNotes.astro based on the configured categories.
+--------------------------------------------------------------- */
+
+.issue-row {
+  display: flex;
+  align-items: baseline;
+  gap: 1rem;
+  margin-bottom: 2.5rem;
+  border-radius: 6px;
+  transition: border-color 0.2s;
+  padding: 6px 8px;
+  border: 2px solid transparent;
+  scroll-margin-top: 5rem;
+}
+
+@media (min-width: 768px) {
+  .issue-row {
+    margin-bottom: 1rem;
+  }
+}
+
+.issue-row:target {
+  border-color: rgba(148, 163, 184, 0.5);
+}
+
+.issue-badge {
+  width: 7rem;
+  padding: 4px 8px;
+  flex-shrink: 0;
+  text-align: center;
+  font-size: 0.75rem;
+  font-weight: 700;
+  border-radius: 2px;
+  text-transform: uppercase;
+  text-decoration: none;
+  cursor: pointer;
+  user-select: none;
+  transition: transform 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:active { transform: scale(0.95); }
+
+.issue-content {
+  flex: 1;
+  min-width: 0;
+}
+
+.rni-body {
+  max-width: 100%;
+  overflow-x: auto;
+}
+
+.rni-meta {
+  font-size: 0.875rem;
+  margin-top: 0.25rem;
+  margin-bottom: 0;
+}
+
+.rni-thanks {
+  font-style: italic;
+  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;
+}
+
+.github-link:hover { opacity: 1; text-decoration: underline; }
+
+/* ---------------------------------------------------------------
+   Version articles
+--------------------------------------------------------------- */
+
+.version {
+  content-visibility: auto;
+  contain-intrinsic-size: 0 800px;
+}
+
+.version-header {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  justify-content: space-between;
+  padding-top: 0.75rem;
+  padding-bottom: 0.75rem;
+  margin-bottom: 0.5rem;
+  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 {
+  font-size: 0.875rem;
+  color: #64748b;
+}
+
+/* ---------------------------------------------------------------
+   Version selector (jump dropdown)
+--------------------------------------------------------------- */
+
+.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;
+  }
+}
+
+.dark .release-selector-select {
+  border-color: #4b5563;
+  background-color: #1e293b;
+  color: #cbd5e1;
+}