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.tsindex 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.tsnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsindex 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+/, '');