Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(docsite): improve changelog package navigation (#5309)

nynexman4464adafac94e3a4
diff --git a/apps/docsite/src/__tests__/changelog-linkify.test.ts b/apps/docsite/src/__tests__/changelog-linkify.test.ts
index ec80183539..f2d21a5aff 100644
--- a/apps/docsite/src/__tests__/changelog-linkify.test.ts
+++ b/apps/docsite/src/__tests__/changelog-linkify.test.ts
@@ -11,6 +11,7 @@ import {
linkifyPRs,
linkifyContributors,
linkifyComponents,
+ addEmptyReleasePlaceholders,
stripTitle,
} from '../components/changelogLinkify';
@@ -130,6 +131,64 @@ describe('linkifyComponents', () => {
});
});
+describe('addEmptyReleasePlaceholders', () => {
+ it('labels an empty release without hiding populated releases', () => {
+ const input = [
+ '# 0.4.5',
+ '',
+ '---',
+ '',
+ '# 0.4.4',
+ '',
+ '#### Fixes',
+ '',
+ '- Fixed the CLI.',
+ ].join('\n');
+
+ expect(addEmptyReleasePlaceholders(input)).toBe(
+ [
+ '# 0.4.5',
+ '',
+ '_No changes in this release._',
+ '',
+ '---',
+ '',
+ '# 0.4.4',
+ '',
+ '#### Fixes',
+ '',
+ '- Fixed the CLI.',
+ ].join('\n'),
+ );
+ });
+
+ it('fills the final empty release when there is no trailing separator', () => {
+ expect(addEmptyReleasePlaceholders('# 0.4.2')).toBe(
+ '# 0.4.2\n\n_No changes in this release._',
+ );
+ });
+
+ it('leaves a populated release unchanged', () => {
+ const input = [
+ '# 0.4.3',
+ '',
+ '#### Fixes',
+ '',
+ '- A real fix.',
+ '',
+ '---',
+ '',
+ '# 0.4.2',
+ '',
+ '#### Fixes',
+ '',
+ '- Another real fix.',
+ ].join('\n');
+
+ expect(addEmptyReleasePlaceholders(input)).toBe(input);
+ });
+});
+
describe('stripTitle', () => {
it('removes the leading h1 title line', () => {
expect(stripTitle('# @astryxdesign/core\n\n# 0.1.1\n')).toBe('# 0.1.1\n');
diff --git a/apps/docsite/src/__tests__/changelog-view.test.ts b/apps/docsite/src/__tests__/changelog-view.test.ts
new file mode 100644
index 0000000000..bd68105801
--- /dev/null
+++ b/apps/docsite/src/__tests__/changelog-view.test.ts
@@ -0,0 +1,163 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Regression tests for the changelog package selection and empty state.
+ *
+ * Run: pnpm -F @astryxdesign/docsite test ChangelogView
+ */
+
+import {createElement, type ReactNode} from 'react';
+import {renderToStaticMarkup} from 'react-dom/server';
+import {describe, expect, it, vi} from 'vitest';
+
+vi.mock('@stylexjs/stylex', () => ({
+ create: <T>(styles: T) => styles,
+ defineConsts: <T>(constants: T) => constants,
+}));
+
+vi.mock('@astryxdesign/core/Markdown', () => ({
+ Markdown: ({children}: {children: ReactNode}) =>
+ createElement('article', null, children),
+}));
+
+vi.mock('@astryxdesign/core/Text', () => ({
+ Heading: ({children}: {children: ReactNode}) =>
+ createElement('h1', null, children),
+ Text: ({children}: {children: ReactNode}) =>
+ createElement('p', null, children),
+}));
+
+vi.mock('@astryxdesign/core/Layout', () => ({
+ VStack: ({children}: {children: ReactNode}) =>
+ createElement('div', null, children),
+}));
+
+vi.mock('@astryxdesign/core/Section', () => ({
+ Section: ({children}: {children: ReactNode}) =>
+ createElement('section', null, children),
+}));
+
+vi.mock('@astryxdesign/core/TabList', () => ({
+ TabList: ({children, value}: {children: ReactNode; value: string}) =>
+ createElement('div', {'data-selected': value}, children),
+ Tab: ({label}: {label: string}) => createElement('span', null, label),
+}));
+
+vi.mock('@astryxdesign/core/Carousel', () => ({
+ Carousel: ({children}: {children: ReactNode}) =>
+ createElement('div', null, children),
+}));
+
+vi.mock('@astryxdesign/core/theme/tokens.stylex', () => ({
+ typeScaleVars: {
+ '--text-body-size': '--text-body-size',
+ '--text-body-leading': '--text-body-leading',
+ },
+}));
+
+import {ChangelogView} from '../components/ChangelogView';
+
+function renderChangelog(
+ changelogs: Array<{pkg: string; content: string}>,
+ selectedPackage?: string,
+): string {
+ return renderToStaticMarkup(
+ createElement(ChangelogView, {
+ changelogs,
+ componentNames: [],
+ selectedPackage,
+ }),
+ );
+}
+
+describe('ChangelogView', () => {
+ it('defaults to the core package when it is available', () => {
+ const html = renderChangelog([
+ {pkg: '@astryxdesign/cli', content: '# CLI\n\nCLI release notes'},
+ {pkg: '@astryxdesign/core', content: '# Core\n\nCore release notes'},
+ ]);
+
+ expect(html).toContain('data-selected="@astryxdesign/core"');
+ expect(html).toContain('Core release notes');
+ expect(html).not.toContain('CLI release notes');
+ });
+
+ it('orders core first, CLI second, and preserves the remaining order', () => {
+ const html = renderChangelog([
+ {
+ pkg: '@astryxdesign/richtext',
+ content: '# Rich text\n\nRich text release notes',
+ },
+ {pkg: '@astryxdesign/cli', content: '# CLI\n\nCLI release notes'},
+ {pkg: '@astryxdesign/core', content: '# Core\n\nCore release notes'},
+ {
+ pkg: '@astryxdesign/charts',
+ content: '# Charts\n\nCharts release notes',
+ },
+ ]);
+
+ expect(html.indexOf('@astryxdesign/core')).toBeLessThan(
+ html.indexOf('@astryxdesign/cli'),
+ );
+ expect(html.indexOf('@astryxdesign/cli')).toBeLessThan(
+ html.indexOf('@astryxdesign/richtext'),
+ );
+ expect(html.indexOf('@astryxdesign/richtext')).toBeLessThan(
+ html.indexOf('@astryxdesign/charts'),
+ );
+ });
+
+ it('uses a valid package from the URL as the initial selection', () => {
+ const html = renderChangelog(
+ [
+ {pkg: '@astryxdesign/cli', content: '# CLI\n\nCLI release notes'},
+ {pkg: '@astryxdesign/core', content: '# Core\n\nCore release notes'},
+ ],
+ '@astryxdesign/cli',
+ );
+
+ expect(html).toContain('data-selected="@astryxdesign/cli"');
+ expect(html).toContain('CLI release notes');
+ expect(html).not.toContain('Core release notes');
+ });
+
+ it('ignores a hidden theme package from the URL', () => {
+ const html = renderChangelog(
+ [
+ {pkg: '@astryxdesign/core', content: '# Core\n\nCore release notes'},
+ {
+ pkg: '@astryxdesign/theme-neutral',
+ content: '# Neutral\n\nNeutral release notes',
+ },
+ ],
+ '@astryxdesign/theme-neutral',
+ );
+
+ expect(html).toContain('data-selected="@astryxdesign/core"');
+ expect(html).not.toContain('Neutral release notes');
+ });
+
+ it('hides theme packages from the primary changelog tabs', () => {
+ const html = renderChangelog([
+ {pkg: '@astryxdesign/core', content: '# Core\n\nCore release notes'},
+ {
+ pkg: '@astryxdesign/theme-neutral',
+ content: '# Neutral\n\nNeutral release notes',
+ },
+ ]);
+
+ expect(html).toContain('@astryxdesign/core');
+ expect(html).not.toContain('@astryxdesign/theme-neutral');
+ });
+
+ it('shows an empty state when a package has no release entries', () => {
+ const html = renderChangelog([
+ {
+ pkg: '@astryxdesign/richtext',
+ content: '# @astryxdesign/richtext\n\n# 0.1.9\n\n---\n\n# 0.1.8\n',
+ },
+ ]);
+
+ expect(html).toContain('No changes in this release.');
+ });
+});
diff --git a/apps/docsite/src/app/(docs)/changelog/page.tsx b/apps/docsite/src/app/(docs)/changelog/page.tsx
index cf8c18db93..a006398f2e 100644
--- a/apps/docsite/src/app/(docs)/changelog/page.tsx
+++ b/apps/docsite/src/app/(docs)/changelog/page.tsx
@@ -1,7 +1,11 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+import {Suspense} from 'react';
import type {Metadata} from 'next';
-import {ChangelogView} from '../../../components/ChangelogView';
+import {
+ ChangelogView,
+ UrlChangelogView,
+} from '../../../components/ChangelogView';
import {components} from '../../../generated/componentRegistry';
import {packages} from '../../../generated/packageRegistry';
import {pageMetadata} from '../../../lib/pageMetadata';
@@ -22,7 +26,11 @@ export default function ChangelogPage() {
.flat()
.map(c => c.name);
+ const viewProps = {changelogs, componentNames};
+
return (
- <ChangelogView changelogs={changelogs} componentNames={componentNames} />
+ <Suspense fallback={<ChangelogView {...viewProps} />}>
+ <UrlChangelogView {...viewProps} />
+ </Suspense>
);
}
diff --git a/apps/docsite/src/components/ChangelogView.tsx b/apps/docsite/src/components/ChangelogView.tsx
index 30e2f30c95..4ed633c460 100644
--- a/apps/docsite/src/components/ChangelogView.tsx
+++ b/apps/docsite/src/components/ChangelogView.tsx
@@ -1,8 +1,14 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/**
+ * @input Package changelogs, component names, and an optional URL selection.
+ * @output Changelog navigation and the selected package's release notes.
+ * @position Main content for the docsite changelog route.
+ */
+
'use client';
-import {useState} from 'react';
+import {usePathname, useRouter, useSearchParams} from 'next/navigation';
import * as stylex from '@stylexjs/stylex';
import {Markdown} from '@astryxdesign/core/Markdown';
import {Text, Heading} from '@astryxdesign/core/Text';
@@ -16,6 +22,7 @@ import {
linkifyPRs,
linkifyContributors,
linkifyComponents,
+ addEmptyReleasePlaceholders,
stripTitle,
} from './changelogLinkify';
@@ -27,6 +34,44 @@ interface ChangelogEntry {
interface ChangelogViewProps {
changelogs: ChangelogEntry[];
componentNames: string[];
+ selectedPackage?: string;
+ onPackageChange?: (pkg: string) => void;
+}
+
+const DEFAULT_PACKAGE = '@astryxdesign/core';
+const CLI_PACKAGE = '@astryxdesign/cli';
+const THEME_PACKAGE_PREFIX = '@astryxdesign/theme-';
+const ignorePackageChange = (_pkg: string) => undefined;
+
+function packagePriority(pkg: string): number {
+ if (pkg === DEFAULT_PACKAGE) {
+ return 0;
+ }
+ if (pkg === CLI_PACKAGE) {
+ return 1;
+ }
+ return 2;
+}
+
+function resolveActivePackage(
+ changelogs: ChangelogEntry[],
+ selectedPackage: string | undefined,
+): string {
+ if (selectedPackage != null) {
+ const selected = changelogs.find(
+ changelog => changelog.pkg === selectedPackage,
+ );
+ if (selected != null) {
+ return selected.pkg;
+ }
+ }
+
+ const core = changelogs.find(changelog => changelog.pkg === DEFAULT_PACKAGE);
+ if (core != null) {
+ return core.pkg;
+ }
+
+ return changelogs[0]?.pkg ?? '';
}
const styles = stylex.create({
@@ -42,12 +87,38 @@ const styles = stylex.create({
},
});
+export function UrlChangelogView(props: ChangelogViewProps) {
+ const pathname = usePathname();
+ const router = useRouter();
+ const searchParams = useSearchParams();
+ const selectedPackage = searchParams.get('package') ?? undefined;
+
+ const handlePackageChange = (pkg: string) => {
+ const nextSearchParams = new URLSearchParams(searchParams.toString());
+ nextSearchParams.set('package', pkg);
+ router.replace(`${pathname}?${nextSearchParams}`, {scroll: false});
+ };
+
+ return (
+ <ChangelogView
+ {...props}
+ selectedPackage={selectedPackage}
+ onPackageChange={handlePackageChange}
+ />
+ );
+}
+
export function ChangelogView({
changelogs,
componentNames,
+ selectedPackage,
+ onPackageChange,
}: ChangelogViewProps) {
- const [activeTab, setActiveTab] = useState(changelogs[0]?.pkg ?? '');
- const active = changelogs.find(c => c.pkg === activeTab);
+ const displayedChangelogs = changelogs
+ .filter(changelog => !changelog.pkg.startsWith(THEME_PACKAGE_PREFIX))
+ .sort((a, b) => packagePriority(a.pkg) - packagePriority(b.pkg));
+ const activeTab = resolveActivePackage(displayedChangelogs, selectedPackage);
+ const active = displayedChangelogs.find(c => c.pkg === activeTab);
return (
<Section
@@ -64,11 +135,14 @@ export function ChangelogView({
</Text>
</VStack>
- {changelogs.length > 0 ? (
+ {displayedChangelogs.length > 0 ? (
<>
- <TabList value={activeTab} onChange={setActiveTab} hasDivider>
+ <TabList
+ value={activeTab}
+ onChange={onPackageChange ?? ignorePackageChange}
+ hasDivider>
<Carousel gap={0.5} hasSnap={false}>
- {changelogs.map(c => (
+ {displayedChangelogs.map(c => (
<Tab key={c.pkg} value={c.pkg} label={c.pkg} />
))}
</Carousel>
@@ -77,7 +151,11 @@ export function ChangelogView({
{active != null && (
<Markdown headingLevelStart={2}>
{linkifyComponents(
- linkifyContributors(linkifyPRs(stripTitle(active.content))),
+ linkifyContributors(
+ linkifyPRs(
+ addEmptyReleasePlaceholders(stripTitle(active.content)),
+ ),
+ ),
componentNames,
)}
</Markdown>
diff --git a/apps/docsite/src/components/changelogLinkify.ts b/apps/docsite/src/components/changelogLinkify.ts
index 2da6016961..48eb3564ba 100644
--- a/apps/docsite/src/components/changelogLinkify.ts
+++ b/apps/docsite/src/components/changelogLinkify.ts
@@ -103,6 +103,19 @@ export function linkifyComponents(
return out + linkify(markdown.slice(lastIndex));
}
+/** Add a visible note to release sections that contain only a version heading. */
+export function addEmptyReleasePlaceholders(markdown: string): string {
+ return markdown
+ .split(/\n+---\n+/)
+ .map(section => {
+ const trimmed = section.trim();
+ return /^#\s+\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(trimmed)
+ ? `${trimmed}\n\n_No changes in this release._`
+ : trimmed;
+ })
+ .join('\n\n---\n\n');
+}
+
/** Strip the leading `# Title` line (the package name h1) from a changelog. */
export function stripTitle(markdown: string): string {
return markdown.replace(/^#\s+.+\n+/, '');