Skip to content

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

TypeScript

fix(docsite): add browser back/forward navigation support (#1911)

Ted McDonald75d3aa072f92
diff --git a/apps/sandbox/src/app/(fullscreen)/pages/docsite/DocsView.tsx b/apps/sandbox/src/app/(fullscreen)/pages/docsite/DocsView.tsx
index 78d6856613..64f59dfe44 100644
--- a/apps/sandbox/src/app/(fullscreen)/pages/docsite/DocsView.tsx
+++ b/apps/sandbox/src/app/(fullscreen)/pages/docsite/DocsView.tsx
@@ -1,7 +1,7 @@
'use client';
import React, {useState, useEffect, useMemo} from 'react';
-import {useSearchParams} from 'next/navigation';
+
import * as stylex from '@stylexjs/stylex';
import {XDSAppShell} from '@xds/core/AppShell';
import {XDSTopNav, XDSTopNavHeading} from '@xds/core/TopNav';
@@ -5075,52 +5075,25 @@ function ComponentDetailPage({
}
export function DocsView({
- activeView: _activeView,
setActiveView,
+ selectedComponent,
+ onComponentChange,
}: {
- activeView: 'craft' | 'explore' | 'docs' | 'profile' | 'theme';
setActiveView: (
v: 'craft' | 'explore' | 'docs' | 'profile' | 'theme',
) => void;
+ selectedComponent: string | null;
+ onComponentChange: (key: string | null) => void;
}) {
- const searchParams = useSearchParams();
-
- const [activeNav, setActiveNav] = useState(() => {
- const tab = searchParams.get('tab');
- const component = searchParams.get('component');
- if (tab === 'whats-new' || tab === 'getting-started') return tab;
- if (component) return component;
- return 'button';
- });
+ const [activeNav, setActiveNav] = useState(selectedComponent ?? 'button');
const [_showCode, _setShowCode] = useState(true);
const [_activeRightNav, _setActiveRightNav] = useState('usage');
- const [selectedComponent, setSelectedComponent] = useState<string | null>(
- () => {
- const tab = searchParams.get('tab');
- const component = searchParams.get('component');
- if (tab === 'whats-new' || tab === 'getting-started') return tab;
- if (component) return component;
- return null;
- },
- );
const [isSearchOpen, setIsSearchOpen] = useState(false);
useEffect(() => {
- const params = new URLSearchParams();
- params.set('page', 'docs');
-
- if (selectedComponent === 'whats-new') {
- params.set('tab', 'whats-new');
- } else if (selectedComponent === 'getting-started') {
- params.set('tab', 'getting-started');
- } else if (selectedComponent !== null) {
- params.set('component', selectedComponent);
+ if (selectedComponent !== null) {
+ setActiveNav(selectedComponent);
}
-
- const qs = params.toString();
- if (qs === window.location.search.slice(1)) return;
- const url = `${basePath}/pages/docsite/?${qs}`;
- window.history.replaceState(window.history.state, '', url);
}, [selectedComponent]);
const headingMenu = (
@@ -5173,7 +5146,7 @@ export function DocsView({
<XDSSideNavItem
label="Home"
isSelected={selectedComponent === null}
- onClick={() => setSelectedComponent(null)}
+ onClick={() => onComponentChange(null)}
/>
</XDSSideNavSection>
<XDSSideNavSection title="Overview" isHeaderHidden>
@@ -5185,7 +5158,7 @@ export function DocsView({
activeNav === 'getting-started'
}
onClick={() => {
- setSelectedComponent('getting-started');
+ onComponentChange('getting-started');
setActiveNav('getting-started');
}}
/>
@@ -5193,7 +5166,7 @@ export function DocsView({
label="What's New"
isSelected={selectedComponent === 'whats-new'}
onClick={() => {
- setSelectedComponent('whats-new');
+ onComponentChange('whats-new');
setActiveNav('whats-new');
}}
/>
@@ -5206,7 +5179,7 @@ export function DocsView({
selectedComponent !== null && activeNav === item.key
}
onClick={() => {
- setSelectedComponent(item.key);
+ onComponentChange(item.key);
setActiveNav(item.key);
}}
/>
@@ -5221,7 +5194,7 @@ export function DocsView({
selectedComponent !== null && activeNav === pkg.key
}
onClick={() => {
- setSelectedComponent(pkg.key);
+ onComponentChange(pkg.key);
setActiveNav(pkg.key);
}}
/>
@@ -5240,7 +5213,7 @@ export function DocsView({
selectedComponent !== null && activeNav === item.key
}
onClick={() => {
- setSelectedComponent(item.key);
+ onComponentChange(item.key);
setActiveNav(item.key);
}}
/>
@@ -5253,11 +5226,11 @@ export function DocsView({
{selectedComponent === null ? (
<LibraryOverview
onGetStarted={() => {
- setSelectedComponent('getting-started');
+ onComponentChange('getting-started');
setActiveNav('getting-started');
}}
onSelectComponent={(key: string) => {
- setSelectedComponent(key);
+ onComponentChange(key);
setActiveNav(key);
}}
onCraft={() => setActiveView('craft')}
@@ -5272,7 +5245,7 @@ export function DocsView({
<LibraryPackagePage
packageKey={selectedComponent}
onSelectComponent={(key: string) => {
- setSelectedComponent(key);
+ onComponentChange(key);
setActiveNav(key);
}}
onCraft={() => setActiveView('craft')}
diff --git a/apps/sandbox/src/app/(fullscreen)/pages/docsite/page.tsx b/apps/sandbox/src/app/(fullscreen)/pages/docsite/page.tsx
index 6a5a7c5cb6..8bc7dd6ae3 100644
--- a/apps/sandbox/src/app/(fullscreen)/pages/docsite/page.tsx
+++ b/apps/sandbox/src/app/(fullscreen)/pages/docsite/page.tsx
@@ -428,6 +428,16 @@ function DocsiteLandingTemplate() {
const CRAFT_TABS = ['all', 'templates', 'components'];
const isCraftTab = page !== null && CRAFT_TABS.includes(page);
+ const component = searchParams.get('component');
+ let docsComponent: string | null = null;
+ if (page === 'docs') {
+ if (tab === 'whats-new' || tab === 'getting-started') {
+ docsComponent = tab;
+ } else if (component) {
+ docsComponent = component;
+ }
+ }
+
return {
view: v,
templateIdx: isNaN(templateIdx as number) ? null : templateIdx,
@@ -444,6 +454,7 @@ function DocsiteLandingTemplate() {
used,
settings: settings === '1',
collection,
+ docsComponent,
};
}, [searchParams]);
@@ -455,6 +466,9 @@ function DocsiteLandingTemplate() {
| 'profile'
| 'theme',
);
+ const [docsComponent, setDocsComponent] = useState<string | null>(
+ initialView.docsComponent,
+ );
const [profileTab, setProfileTab] = useState<
'Crafted' | 'Used' | 'Bookmarks'
>(initialView.tab ?? 'Crafted');
@@ -605,6 +619,9 @@ function DocsiteLandingTemplate() {
[editorPanelWidth],
);
+ const isPopstateRef = useRef(false);
+ const prevUrlRef = useRef('');
+
// Sync URL when view state changes
useEffect(() => {
const params = new URLSearchParams();
@@ -621,7 +638,16 @@ function DocsiteLandingTemplate() {
params.set('page', activeTab);
} else if (activeView !== 'craft') {
params.set('page', activeView);
- if (activeView === 'profile') {
+ if (activeView === 'docs') {
+ if (
+ docsComponent === 'whats-new' ||
+ docsComponent === 'getting-started'
+ ) {
+ params.set('tab', docsComponent);
+ } else if (docsComponent !== null) {
+ params.set('component', docsComponent);
+ }
+ } else if (activeView === 'profile') {
if (profileCraftName) {
params.set('tab', 'Crafted');
params.set('craft', profileCraftName);
@@ -643,13 +669,42 @@ function DocsiteLandingTemplate() {
const qs = params.toString();
if (qs === window.location.search.slice(1)) return;
const url = `${basePath}/pages/docsite/${qs ? '?' + qs : ''}`;
- window.history.replaceState(window.history.state, '', url);
+
+ if (isPopstateRef.current) {
+ isPopstateRef.current = false;
+ prevUrlRef.current = qs;
+ return;
+ }
+
+ const prevParams = new URLSearchParams(prevUrlRef.current);
+ const prevPage = prevParams.get('page');
+ const prevComponent = prevParams.get('component');
+ const prevTab = prevParams.get('tab');
+ const prevView = prevParams.get('view');
+ const curPage = params.get('page');
+ const curComponent = params.get('component');
+ const curTab = params.get('tab');
+ const curView = params.get('view');
+
+ const isSignificant =
+ curView !== prevView ||
+ curPage !== prevPage ||
+ curComponent !== prevComponent ||
+ (curPage === 'docs' && curTab !== prevTab);
+
+ if (isSignificant) {
+ window.history.pushState(null, '', url);
+ } else {
+ window.history.replaceState(window.history.state, '', url);
+ }
+ prevUrlRef.current = qs;
}, [
previewTarget,
useTarget,
craftTitle,
activeView,
activeTab,
+ docsComponent,
profileTab,
profileCraftName,
profileUsedName,
@@ -657,6 +712,56 @@ function DocsiteLandingTemplate() {
profileCollectionName,
]);
+ useEffect(() => {
+ const onPopState = () => {
+ isPopstateRef.current = true;
+ const params = new URLSearchParams(window.location.search);
+ const page = params.get('page');
+ const view = params.get('view');
+ const template = params.get('template');
+ const q = params.get('q');
+
+ if (view === 'preview' && template !== null) {
+ setPreviewTarget(parseInt(template, 10));
+ setUseTarget(null);
+ } else if (view === 'editor' && template !== null) {
+ setUseTarget(parseInt(template, 10));
+ setPreviewTarget(null);
+ } else if (q) {
+ setCraftTitle(q);
+ setPreviewTarget(null);
+ setUseTarget(null);
+ } else {
+ setPreviewTarget(null);
+ setUseTarget(null);
+ setCraftTitle(null);
+ const CRAFT_TABS = ['all', 'templates', 'components'];
+ if (page && CRAFT_TABS.includes(page)) {
+ setActiveView('craft');
+ setActiveTab(page);
+ } else if (page === 'docs') {
+ setActiveView('docs');
+ const tab = params.get('tab');
+ const component = params.get('component');
+ if (tab === 'whats-new' || tab === 'getting-started') {
+ setDocsComponent(tab);
+ } else if (component) {
+ setDocsComponent(component);
+ } else {
+ setDocsComponent(null);
+ }
+ } else if (page === 'profile' || page === 'theme') {
+ setActiveView(page);
+ } else {
+ setActiveView('craft');
+ setActiveTab('all');
+ }
+ }
+ };
+ window.addEventListener('popstate', onPopState);
+ return () => window.removeEventListener('popstate', onPopState);
+ }, []);
+
const prevViewRef = useRef(activeView);
const skipViewResetRef = useRef(false);
useEffect(() => {
@@ -671,6 +776,9 @@ function DocsiteLandingTemplate() {
setChatOpen(false);
setCraftTitle(null);
setResultFilters(new Set());
+ if (activeView !== 'docs') {
+ setDocsComponent(null);
+ }
}, [activeView]);
const timerRef = useRef(null as ReturnType<typeof setTimeout> | null);
const previewTimerRef = useRef(null as ReturnType<typeof setTimeout> | null);
@@ -1066,7 +1174,13 @@ function DocsiteLandingTemplate() {
}
if (activeView === 'docs') {
- return <DocsView activeView={activeView} setActiveView={setActiveView} />;
+ return (
+ <DocsView
+ setActiveView={setActiveView}
+ selectedComponent={docsComponent}
+ onComponentChange={setDocsComponent}
+ />
+ );
}
if (activeView === 'profile') {