An open source design system that's fully customizable and agent ready
TypeScript
feat(docsite): suggest matching pages on 404s (#5669)
nynexman4464d7bb4bff3b07
diff --git a/apps/docsite/src/__tests__/did-you-mean.test.ts b/apps/docsite/src/__tests__/did-you-mean.test.tsnew file mode 100644index 0000000000..f31b2481a8--- /dev/null+++ b/apps/docsite/src/__tests__/did-you-mean.test.ts@@ -0,0 +1,71 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Tests for docsite DidYouMean matching.+ * @input Representative missing paths and canonical sitemap page candidates+ * @output Confidence, ranking, normalization, deduplication, and limit guarantees+ * @position Unit coverage for the pure similar-page matcher+ */++import {describe, expect, it} from 'vitest';+import {findSimilarPages, type PageCandidate} from '../lib/didYouMean';++const pages: PageCandidate[] = [+ {path: '/', title: 'Home'},+ {path: '/docs', title: 'Docs'},+ {path: '/docs/getting-started', title: 'Getting Started'},+ {path: '/components', title: 'Components'},+ {path: '/components/AppShell', title: 'App Shell'},+ {path: '/components/Button', title: 'Button'},+ {path: '/changelog', title: "What's New"},+ {path: '/templates/dashboard', title: 'Dashboard'},+];++function suggestedPaths(pathname: string, limit?: number): string[] {+ return findSimilarPages(pathname, pages, limit).map(page => page.path);+}++describe('findSimilarPages', () => {+ it('finds a page whose final segment exactly matches the missing path', () => {+ expect(suggestedPaths('/getting-started')[0]).toBe('/docs/getting-started');+ });++ it('matches a partial page title', () => {+ expect(suggestedPaths('/start')[0]).toBe('/docs/getting-started');+ });++ it('matches a word from the canonical page title', () => {+ expect(suggestedPaths('/new')[0]).toBe('/changelog');+ });++ it('corrects typos in a full nested path', () => {+ expect(suggestedPaths('/doc/geting-started')[0]).toBe(+ '/docs/getting-started',+ );+ });++ it('normalizes case and punctuation', () => {+ expect(suggestedPaths('/components/app-shell')[0]).toBe(+ '/components/AppShell',+ );+ });++ it('does not offer low-confidence matches', () => {+ expect(suggestedPaths('/nothing-like-a-real-page')).toEqual([]);+ });++ it('deduplicates pages and respects the result limit', () => {+ const duplicatePages = [+ ...pages,+ {path: '/components/Button', title: 'Button duplicate'},+ ];++ expect(findSimilarPages('/components/Buton', duplicatePages, 1)).toEqual([+ {path: '/components/Button', title: 'Button'},+ ]);+ });++ it('ignores unusually long input rather than doing fuzzy work', () => {+ expect(suggestedPaths(`/${'x'.repeat(129)}`)).toEqual([]);+ });+});diff --git a/apps/docsite/src/__tests__/sitemap.test.ts b/apps/docsite/src/__tests__/sitemap.test.tsindex 14fbf4460a..c7c4a85336 100644--- a/apps/docsite/src/__tests__/sitemap.test.ts+++ b/apps/docsite/src/__tests__/sitemap.test.ts@@ -16,7 +16,7 @@ import {describe, it, expect, vi} from 'vitest';// cache scope to configure. Stub it so the sitemap can run under vitest.vi.mock('next/cache', () => ({cacheLife: () => {}}));-import sitemap from '../app/sitemap';+import sitemap, {getSitemapPages} from '../app/sitemap';import {SITE_URL} from '../lib/siteConfig';import {flattenComponentSidebarEntries} from '../components/componentSidebarData';import {docTopics} from '../generated/docsRegistry';@@ -25,6 +25,7 @@ import {templates} from '../generated/templateRegistry';import {blogPosts} from '../generated/blogRegistry';const entries = await sitemap();+const pages = await getSitemapPages();const urls = entries.map(e => e.url);describe('docsite sitemap', () => {@@ -44,6 +45,12 @@ describe('docsite sitemap', () => {}});+ it('exports canonical page titles for route recovery', () => {+ expect(+ pages.find(page => new URL(page.url).pathname === '/changelog')?.title,+ ).toBe("What's New");+ });+it('includes every component detail page', () => {for (const c of flattenComponentSidebarEntries()) {expect(urls).toContain(diff --git a/apps/docsite/src/app/(docs)/changelog/page.tsx b/apps/docsite/src/app/(docs)/changelog/page.tsxindex a006398f2e..de44cb67b1 100644--- a/apps/docsite/src/app/(docs)/changelog/page.tsx+++ b/apps/docsite/src/app/(docs)/changelog/page.tsx@@ -1,5 +1,12 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+/**+ * @file Changelog route for published Astryx packages.+ * @input Generated package changelogs, component names, and URL selection state+ * @output The canonical What's New page with package-filtered release notes+ * @position Public docsite page at /changelog+ */+import {Suspense} from 'react';import type {Metadata} from 'next';import {@@ -9,9 +16,10 @@ import {import {components} from '../../../generated/componentRegistry';import {packages} from '../../../generated/packageRegistry';import {pageMetadata} from '../../../lib/pageMetadata';+import {CHANGELOG_PAGE_TITLE} from '../../../lib/pageTitles';export const metadata: Metadata = pageMetadata({- title: 'Changelog',+ title: CHANGELOG_PAGE_TITLE,description:'Release notes and version history for Astryx packages and components.',path: '/changelog',diff --git a/apps/docsite/src/app/(site)/community/page.tsx b/apps/docsite/src/app/(site)/community/page.tsxindex 2489351115..cf7f6f322a 100644--- a/apps/docsite/src/app/(site)/community/page.tsx+++ b/apps/docsite/src/app/(site)/community/page.tsx@@ -4,6 +4,10 @@* Astryx community page — channels + contribution paths + live* contributors.*+ * @input Static community content plus an hourly-cached GitHub contributor list+ * @output Community landing page with contribution paths and contributor wall+ * @position Public docsite page at /community+ ** Three roles in one page (modeled after how Astro, Svelte, and* GitHub Primer balance the same trio):*@@ -22,6 +26,7 @@import type {ReactNode} from 'react';import type {Metadata} from 'next';+import {cacheLife} from 'next/cache';import {FileText, Scale} from 'lucide-react';import {NavSurfaceMode} from './NavSurfaceMode';import {TemplatesPreview} from '../_landing/TemplatesPreview';@@ -731,10 +736,12 @@ interface Contributor {// Astryx contributor set. Falls back to Unsplash placeholders if the// request fails.async function fetchContributors(): Promise<Contributor[]> {+ 'use cache';+ cacheLife('hours');+try {const res = await fetch('https://api.github.com/repos/facebook/stylex/contributors?per_page=50',- {next: {revalidate: 3600}},);if (!res.ok) {return [];diff --git a/apps/docsite/src/app/not-found.tsx b/apps/docsite/src/app/not-found.tsxindex f4ebf82373..38e4c472cc 100644--- a/apps/docsite/src/app/not-found.tsx+++ b/apps/docsite/src/app/not-found.tsx@@ -1,18 +1,32 @@// Copyright (c) Meta Platforms, Inc. and affiliates.+/**+ * @file Global not-found page for the Astryx docsite.+ * @input Shared shell chrome, sitemap pages, and the current request pathname+ * @output Branded 404 page with high-confidence destination suggestions+ * @position Fallback route rendered whenever no static or dynamic docsite page matches+ */+import {AppShell} from '@astryxdesign/core/AppShell';import {Center} from '@astryxdesign/core/Center';import {VStack} from '@astryxdesign/core/Layout';import {Heading, Text} from '@astryxdesign/core/Text';import {SharedTopNav} from '../components/SharedTopNav';import {CanaryBanner} from '../components/CanaryBanner';+import {DidYouMean} from '../components/DidYouMean';import {CURRENT_TARGET} from '../lib/docsVersions';import {SiteFooter} from '../components/SiteFooter';import {getCopyrightYear} from '../lib/copyrightYear';+import {getSitemapPages} from './sitemap';import styles from './not-found.module.css';export default async function NotFound() {const year = await getCopyrightYear();+ const sitemapPages = await getSitemapPages();+ const pages = sitemapPages.map(({url, title}) => ({+ path: new URL(url).pathname,+ title,+ }));return (<AppShell@@ -31,6 +45,7 @@ export default async function NotFound() {<Text type="body" color="secondary">This page could not be found.</Text>+ <DidYouMean pages={pages} /></VStack></Center></div>diff --git a/apps/docsite/src/app/sitemap.ts b/apps/docsite/src/app/sitemap.tsindex 243275a088..69182bebfb 100644--- a/apps/docsite/src/app/sitemap.ts+++ b/apps/docsite/src/app/sitemap.ts@@ -9,11 +9,8 @@* template, or blog post and it appears in the sitemap with no manual edit.** Mirrors the `generateStaticParams` of each dynamic route so the sitemap and- * the actual rendered pages never drift:- * - /components/[name] ← flattenComponentSidebarEntries()- * - /docs/[topic] ← docTopics + non-theme packages- * - /templates/[slug] ← templates- * - /blog/[slug] ← blogPosts+ * the actual rendered pages never drift. `getSitemapPages()` exposes the same+ * entries with their canonical page titles for 404 recovery.** @output MetadataRoute.Sitemap consumed by Next.js to emit /sitemap.xml*/@@ -21,14 +18,15 @@import type {MetadataRoute} from 'next';import {cacheLife} from 'next/cache';import {SITE_URL} from '../lib/siteConfig';+import {CHANGELOG_PAGE_TITLE} from '../lib/pageTitles';import {flattenComponentSidebarEntries} from '../components/componentSidebarData';import {docTopics} from '../generated/docsRegistry';import {packages} from '../generated/packageRegistry';import {templates} from '../generated/templateRegistry';import {blogPosts} from '../generated/blogRegistry';-// Theme packages don't get a /docs/[topic] reference page (see the docs route's-// own filter); keep the sitemap aligned with what actually renders.+export type SitemapPage = MetadataRoute.Sitemap[number] & {title: string};+function isThemePackage(name: string): boolean {return name.includes('theme-');}@@ -43,52 +41,102 @@ async function getLastModified(): Promise<Date> {return new Date();}-export default async function sitemap(): Promise<MetadataRoute.Sitemap> {+export async function getSitemapPages(): Promise<SitemapPage[]> {const now = await getLastModified();- // Static, hand-authored pages. `priority` is a relative hint to crawlers;- // the home page and primary galleries rank highest.- const staticEntries: MetadataRoute.Sitemap = [- {url: url('/'), changeFrequency: 'weekly', priority: 1},- {url: url('/components'), changeFrequency: 'weekly', priority: 0.9},- {url: url('/docs'), changeFrequency: 'weekly', priority: 0.9},- {url: url('/templates'), changeFrequency: 'weekly', priority: 0.8},- {url: url('/themes'), changeFrequency: 'weekly', priority: 0.8},- {url: url('/blog'), changeFrequency: 'weekly', priority: 0.8},- {url: url('/changelog'), changeFrequency: 'weekly', priority: 0.6},- {url: url('/community'), changeFrequency: 'monthly', priority: 0.5},- {url: url('/playground'), changeFrequency: 'monthly', priority: 0.6},- {url: url('/llms.txt'), changeFrequency: 'weekly', priority: 0.5},+ const staticEntries: SitemapPage[] = [+ {url: url('/'), title: 'Home', changeFrequency: 'weekly', priority: 1},+ {+ url: url('/components'),+ title: 'Components',+ changeFrequency: 'weekly',+ priority: 0.9,+ },+ {+ url: url('/docs'),+ title: 'Docs',+ changeFrequency: 'weekly',+ priority: 0.9,+ },+ {+ url: url('/templates'),+ title: 'Templates',+ changeFrequency: 'weekly',+ priority: 0.8,+ },+ {+ url: url('/themes'),+ title: 'Themes',+ changeFrequency: 'weekly',+ priority: 0.8,+ },+ {+ url: url('/blog'),+ title: 'Blog',+ changeFrequency: 'weekly',+ priority: 0.8,+ },+ {+ url: url('/changelog'),+ title: CHANGELOG_PAGE_TITLE,+ changeFrequency: 'weekly',+ priority: 0.6,+ },+ {+ url: url('/community'),+ title: 'Community',+ changeFrequency: 'monthly',+ priority: 0.5,+ },+ {+ url: url('/playground'),+ title: 'Playground',+ changeFrequency: 'monthly',+ priority: 0.6,+ },+ {+ url: url('/llms.txt'),+ title: 'LLMs.txt',+ changeFrequency: 'weekly',+ priority: 0.5,+ },];- const componentEntries: MetadataRoute.Sitemap =- flattenComponentSidebarEntries().map(c => ({- url: url(`/components/${c.name}`),+ const componentEntries: SitemapPage[] = flattenComponentSidebarEntries().map(+ component => ({+ url: url(`/components/${component.name}`),+ title: component.displayName,changeFrequency: 'weekly',priority: 0.7,- }));+ }),+ );- const docTopicEntries: MetadataRoute.Sitemap = [- ...docTopics.map(d => d.topic),+ const docTopicEntries: SitemapPage[] = [+ ...docTopics.map(topic => ({slug: topic.topic, title: topic.title})),...packages- .filter(p => !isThemePackage(p.name))- .map(p => p.name.replace('@astryxdesign/', '')),- ].map(topic => ({- url: url(`/docs/${topic}`),+ .filter(pkg => !isThemePackage(pkg.name))+ .map(pkg => ({+ slug: pkg.name.replace('@astryxdesign/', ''),+ title: pkg.displayName,+ })),+ ].map(({slug, title}) => ({+ url: url(`/docs/${slug}`),+ title,changeFrequency: 'weekly' as const,priority: 0.7,}));- const templateEntries: MetadataRoute.Sitemap = templates.map(t => ({- url: url(`/templates/${t.slug}`),+ const templateEntries: SitemapPage[] = templates.map(template => ({+ url: url(`/templates/${template.slug}`),+ title: template.name,changeFrequency: 'monthly',priority: 0.6,}));- const blogEntries: MetadataRoute.Sitemap = blogPosts.map(p => ({- url: url(`/blog/${p.slug}`),- // Use the post's own publish date as lastModified when present.- lastModified: p.date ? new Date(p.date) : now,+ const blogEntries: SitemapPage[] = blogPosts.map(post => ({+ url: url(`/blog/${post.slug}`),+ title: post.title,+ lastModified: post.date ? new Date(post.date) : now,changeFrequency: 'monthly',priority: 0.6,}));@@ -101,3 +149,8 @@ export default async function sitemap(): Promise<MetadataRoute.Sitemap> {...blogEntries,];}++export default async function sitemap(): Promise<MetadataRoute.Sitemap> {+ const pages = await getSitemapPages();+ return pages.map(({title: _title, ...entry}) => entry);+}diff --git a/apps/docsite/src/components/ChangelogView.tsx b/apps/docsite/src/components/ChangelogView.tsxindex 4ed633c460..31fd4e0731 100644--- a/apps/docsite/src/components/ChangelogView.tsx+++ b/apps/docsite/src/components/ChangelogView.tsx@@ -18,6 +18,7 @@ import {TabList, Tab} from '@astryxdesign/core/TabList';import {Carousel} from '@astryxdesign/core/Carousel';import {typeScaleVars} from '@astryxdesign/core/theme/tokens.stylex';import {layout} from '../layout.stylex';+import {CHANGELOG_PAGE_TITLE} from '../lib/pageTitles';import {linkifyPRs,linkifyContributors,@@ -128,7 +129,7 @@ export function ChangelogView({<VStack gap={8}><VStack gap={4}><Heading level={1} type="display-1">- What's New+ {CHANGELOG_PAGE_TITLE}</Heading><Text type="large" weight="normal" color="secondary">Release notes and changelog for all packages.diff --git a/apps/docsite/src/components/DidYouMean.tsx b/apps/docsite/src/components/DidYouMean.tsxnew file mode 100644index 0000000000..9e0603d3c3--- /dev/null+++ b/apps/docsite/src/components/DidYouMean.tsx@@ -0,0 +1,42 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Suggested destinations for a missing docsite page.+ * @input Current pathname and canonical pages exported by the sitemap+ * @output High-confidence navigation links when a likely destination exists+ * @position Client-side recovery UI within the server-rendered 404 page+ */++'use client';++import {usePathname} from 'next/navigation';+import {VStack} from '@astryxdesign/core/Layout';+import {Link} from '@astryxdesign/core/Link';+import {Text} from '@astryxdesign/core/Text';+import {findSimilarPages, type PageCandidate} from '../lib/didYouMean';++interface DidYouMeanProps {+ pages: readonly PageCandidate[];+}++export function DidYouMean({pages}: DidYouMeanProps) {+ const pathname = usePathname();+ const suggestions = findSimilarPages(pathname, pages);++ if (suggestions.length === 0) {+ return null;+ }++ return (+ <VStack gap={1} hAlign="center">+ <Text type="body" color="secondary">+ Did you mean?+ </Text>+ {suggestions.map(suggestion => (+ <Link key={suggestion.path} href={suggestion.path} isStandalone>+ {suggestion.title}+ </Link>+ ))}+ </VStack>+ );+}diff --git a/apps/docsite/src/lib/didYouMean.ts b/apps/docsite/src/lib/didYouMean.tsnew file mode 100644index 0000000000..1d09527dfb--- /dev/null+++ b/apps/docsite/src/lib/didYouMean.ts@@ -0,0 +1,181 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Similar-page ranking for the docsite 404 experience.+ * @input The missing pathname and canonical sitemap paths and page titles+ * @output Up to three high-confidence pages ordered by similarity+ * @position Pure matching logic behind the DidYouMean component+ */++const MAX_INPUT_LENGTH = 128;+const MAX_NORMALIZED_DISTANCE = 0.34;++export interface PageCandidate {+ path: string;+ title: string;+}++interface NormalizedPath {+ full: string;+ leaf: string;+}++interface Comparison {+ distance: number;+ ratio: number;+ length: number;+}++interface RankedPage {+ page: PageCandidate;+ matchTier: number;+ comparison: Comparison;+}++function decodePath(path: string): string {+ try {+ return decodeURIComponent(path);+ } catch {+ return path;+ }+}++function normalizeSegment(segment: string): string {+ return segment.toLowerCase().replace(/[^a-z0-9]/g, '');+}++function normalizeWords(value: string): string[] {+ return value+ .toLowerCase()+ .replace(/[’']/g, '')+ .split(/[^a-z0-9]+/)+ .filter(Boolean);+}++function normalizePath(path: string): NormalizedPath {+ const pathname = decodePath(path).split(/[?#]/, 1)[0];+ const segments = pathname+ .split('/')+ .filter(Boolean)+ .map(normalizeSegment)+ .filter(Boolean);++ return {+ full: segments.join('/'),+ leaf: segments.at(-1) ?? '',+ };+}++function levenshteinDistance(a: string, b: string): number {+ if (a === b) {+ return 0;+ }+ if (a.length === 0) {+ return b.length;+ }+ if (b.length === 0) {+ return a.length;+ }++ let previous = Array.from({length: b.length + 1}, (_, index) => index);++ for (let i = 1; i <= a.length; i++) {+ const current = [i];+ for (let j = 1; j <= b.length; j++) {+ current[j] = Math.min(+ current[j - 1] + 1,+ previous[j] + 1,+ previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),+ );+ }+ previous = current;+ }++ return previous[b.length];+}++function compare(a: string, b: string): Comparison {+ const length = Math.max(a.length, b.length);+ if (length === 0) {+ return {distance: Number.POSITIVE_INFINITY, ratio: 1, length};+ }++ const distance = levenshteinDistance(a, b);+ return {distance, ratio: distance / length, length};+}++function isHighConfidence(comparison: Comparison): boolean {+ const maxDistance = Math.max(1, Math.floor(comparison.length * 0.34));+ return (+ comparison.distance <= maxDistance &&+ comparison.ratio <= MAX_NORMALIZED_DISTANCE+ );+}++export function findSimilarPages(+ pathname: string,+ pages: readonly PageCandidate[],+ limit = 3,+): PageCandidate[] {+ if (pathname.length > MAX_INPUT_LENGTH || limit <= 0) {+ return [];+ }++ const requested = normalizePath(pathname);+ if (!requested.leaf) {+ return [];+ }++ const seen = new Set<string>();+ const ranked: RankedPage[] = [];++ for (const page of pages) {+ if (seen.has(page.path)) {+ continue;+ }+ seen.add(page.path);++ const candidate = normalizePath(page.path);+ if (!candidate.leaf || page.path === pathname) {+ continue;+ }++ const terms = [+ candidate.leaf,+ normalizeSegment(page.title),+ ...normalizeWords(page.title),+ ].filter(Boolean);+ const termComparisons = terms.map(term => compare(requested.leaf, term));+ const fullComparison = compare(requested.full, candidate.full);+ const comparison = [...termComparisons, fullComparison].sort(+ (a, b) => a.ratio - b.ratio || a.distance - b.distance,+ )[0];+ const exactTerm = termComparisons.some(result => result.distance === 0);+ const partialTerm = terms.some(+ term =>+ requested.leaf.length >= 4 &&+ term.length >= 4 &&+ (term.includes(requested.leaf) || requested.leaf.includes(term)),+ );+ const matchTier = exactTerm ? 0 : partialTerm ? 1 : 2;++ if (matchTier === 2 && !isHighConfidence(comparison)) {+ continue;+ }++ ranked.push({page, matchTier, comparison});+ }++ return ranked+ .sort((a, b) => {+ return (+ a.matchTier - b.matchTier ||+ a.comparison.ratio - b.comparison.ratio ||+ a.comparison.distance - b.comparison.distance ||+ a.page.path.length - b.page.path.length ||+ a.page.title.localeCompare(b.page.title)+ );+ })+ .slice(0, limit)+ .map(match => match.page);+}diff --git a/apps/docsite/src/lib/pageTitles.ts b/apps/docsite/src/lib/pageTitles.tsnew file mode 100644index 0000000000..0fcdbb7dc5--- /dev/null+++ b/apps/docsite/src/lib/pageTitles.ts@@ -0,0 +1,9 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Canonical titles for hand-authored docsite pages.+ * @output Shared page-title constants for metadata, headings, and route recovery+ * @position Lightweight source of truth consumed by server and client modules+ */++export const CHANGELOG_PAGE_TITLE = "What's New";