reroute-js 0.6.0 → 0.7.1

package/_/blog/src/client/routes/docs.tsx

@@ -0,0 +1,670 @@
+import { Link } from 'reroute-js/react';
+
+const meta = {
+	title: 'Documentation - Fragment Navigation Demo',
+	description: 'Testing the new fragment prop for automatic scrolling',
+};
+
+export default function DocsPage() {
+	return (
+		<div style={{ minHeight: '100vh', background: '#f9f9f9' }}>
+			{/* Header */}
+			<header
+				style={{
+					background: '#fff',
+					borderBottom: '1px solid #e0e0e0',
+					padding: '1rem 2rem',
+					position: 'sticky',
+					top: 0,
+					zIndex: 100,
+					boxShadow: '0 2px 4px rgba(0,0,0,0.05)',
+				}}
+			>
+				<div style={{ maxWidth: '1200px', margin: '0 auto' }}>
+					<Link
+						to='/'
+						style={{
+							fontSize: '1.5rem',
+							fontWeight: 'bold',
+							color: '#333',
+							textDecoration: 'none',
+						}}
+					>
+						← Back to Home
+					</Link>
+				</div>
+			</header>
+
+			{/* Main Content */}
+			<main style={{ maxWidth: '1200px', margin: '0 auto', padding: '2rem' }}>
+				<h1 style={{ fontSize: '2.5rem', marginBottom: '1rem' }}>
+					📚 Documentation
+				</h1>
+				<p style={{ fontSize: '1.1rem', color: '#666', marginBottom: '3rem' }}>
+					This page demonstrates the new <code>fragment</code> prop for the Link
+					component. Click any section in the table of contents below to
+					automatically scroll to that section with smooth scrolling behavior.
+				</p>
+
+				{/* Table of Contents with Fragment Navigation */}
+				<div
+					style={{
+						background: '#fff',
+						border: '1px solid #e0e0e0',
+						borderRadius: '8px',
+						padding: '2rem',
+						marginBottom: '3rem',
+					}}
+				>
+					<h2 style={{ marginTop: 0, marginBottom: '1rem' }}>
+						📑 Table of Contents
+					</h2>
+					<nav>
+						<ul style={{ listStyle: 'none', padding: 0 }}>
+							<li style={{ marginBottom: '0.75rem' }}>
+								<Link
+									to='/docs'
+									fragment='getting-started'
+									style={{
+										color: '#0066cc',
+										textDecoration: 'none',
+										fontSize: '1.1rem',
+									}}
+								>
+									→ Getting Started
+								</Link>
+							</li>
+							<li style={{ marginBottom: '0.75rem' }}>
+								<Link
+									to='/docs'
+									fragment='installation'
+									style={{
+										color: '#0066cc',
+										textDecoration: 'none',
+										fontSize: '1.1rem',
+									}}
+								>
+									→ Installation
+								</Link>
+							</li>
+							<li style={{ marginBottom: '0.75rem' }}>
+								<Link
+									to='/docs'
+									fragment='usage'
+									style={{
+										color: '#0066cc',
+										textDecoration: 'none',
+										fontSize: '1.1rem',
+									}}
+								>
+									→ Usage
+								</Link>
+							</li>
+							<li style={{ marginBottom: '0.75rem' }}>
+								<Link
+									to='/docs'
+									fragment='api-reference'
+									style={{
+										color: '#0066cc',
+										textDecoration: 'none',
+										fontSize: '1.1rem',
+									}}
+								>
+									→ API Reference
+								</Link>
+							</li>
+							<li style={{ marginBottom: '0.75rem' }}>
+								<Link
+									to='/docs'
+									fragment='examples'
+									style={{
+										color: '#0066cc',
+										textDecoration: 'none',
+										fontSize: '1.1rem',
+									}}
+								>
+									→ Examples
+								</Link>
+							</li>
+							<li style={{ marginBottom: '0.75rem' }}>
+								<Link
+									to='/docs'
+									fragment='faq'
+									style={{
+										color: '#0066cc',
+										textDecoration: 'none',
+										fontSize: '1.1rem',
+									}}
+								>
+									→ FAQ
+								</Link>
+							</li>
+						</ul>
+					</nav>
+					<div
+						style={{
+							marginTop: '1.5rem',
+							padding: '1rem',
+							background: '#fff3cd',
+							border: '1px solid #ffc107',
+							borderRadius: '4px',
+						}}
+					>
+						<strong>💡 Test Cross-Page Navigation:</strong> Go to the{' '}
+						<Link to='/blog' style={{ color: '#0066cc' }}>
+							Blog page
+						</Link>{' '}
+						and click the fragment navigation buttons there to test navigating
+						from a different route!
+					</div>
+				</div>
+
+				{/* Sections */}
+				<Section
+					id='getting-started'
+					title='🚀 Getting Started'
+					content={
+						<>
+							<p>
+								Welcome to the documentation! This section will help you get
+								started with using fragment navigation in your Reroute
+								application.
+							</p>
+							<p>
+								Fragment navigation allows you to link directly to specific
+								sections of a page using the <code>fragment</code> prop on the
+								Link component. When the user clicks the link, the page will
+								automatically scroll to the target section with smooth scrolling
+								behavior.
+							</p>
+							<p>
+								<strong>Key Features:</strong>
+							</p>
+							<ul>
+								<li>✨ Smooth scrolling animation</li>
+								<li>🔄 Works with same-page and cross-page navigation</li>
+								<li>🎯 Automatic retry for slow-rendering components</li>
+								<li>📱 Respects scroll margin for sticky headers</li>
+								<li>♿ Accessible (hash in URL)</li>
+							</ul>
+							<code
+								style={{
+									display: 'block',
+									background: '#f5f5f5',
+									padding: '1rem',
+									borderRadius: '4px',
+									marginTop: '1rem',
+								}}
+							>
+								{`<Link to="/docs" fragment="getting-started">
+  Jump to Getting Started
+</Link>`}
+							</code>
+						</>
+					}
+				/>
+
+				<Section
+					id='installation'
+					title='📦 Installation'
+					content={
+						<>
+							<p>
+								To use fragment navigation, simply upgrade to the latest version
+								of reroute-js that includes the fragment prop feature.
+							</p>
+							<code
+								style={{
+									display: 'block',
+									background: '#f5f5f5',
+									padding: '1rem',
+									borderRadius: '4px',
+									marginTop: '1rem',
+								}}
+							>
+								bun add reroute-js@latest
+							</code>
+							<p style={{ marginTop: '1rem' }}>
+								No additional setup is required. The fragment functionality is
+								built into the Link component and works out of the box.
+							</p>
+							<p>
+								<strong>Requirements:</strong>
+							</p>
+							<ul>
+								<li>React 18+</li>
+								<li>Bun or Node.js</li>
+								<li>Modern browser with smooth scrolling support</li>
+							</ul>
+						</>
+					}
+				/>
+
+				<Section
+					id='usage'
+					title='💡 Usage'
+					content={
+						<>
+							<p>
+								Using fragment navigation is simple. Just add the{' '}
+								<code>fragment</code> prop to any Link component:
+							</p>
+							<code
+								style={{
+									display: 'block',
+									background: '#f5f5f5',
+									padding: '1rem',
+									borderRadius: '4px',
+									marginTop: '1rem',
+									whiteSpace: 'pre',
+									overflow: 'auto',
+								}}
+							>
+								{`// Navigate to a section on the same page
+<Link to="/docs" fragment="usage">
+  View Usage
+</Link>
+
+// Navigate to a different page and scroll to a section
+<Link to="/about" fragment="team">
+  Meet Our Team
+</Link>
+
+// Combine with other Link props
+<Link
+  to="/docs"
+  fragment="api-reference"
+  prefetch={false}
+  replace
+>
+  API Reference
+</Link>`}
+							</code>
+							<p style={{ marginTop: '1rem' }}>
+								<strong>Important:</strong> Make sure your target sections have
+								an <code>id</code> attribute that matches the fragment value:
+							</p>
+							<code
+								style={{
+									display: 'block',
+									background: '#f5f5f5',
+									padding: '1rem',
+									borderRadius: '4px',
+									marginTop: '0.5rem',
+								}}
+							>
+								{`<section id="usage">
+  {/* Your content here */}
+</section>`}
+							</code>
+						</>
+					}
+				/>
+
+				<Section
+					id='api-reference'
+					title='📖 API Reference'
+					content={
+						<>
+							<h3>Link Component Props</h3>
+							<table
+								style={{
+									width: '100%',
+									borderCollapse: 'collapse',
+									marginTop: '1rem',
+								}}
+							>
+								<thead>
+									<tr style={{ borderBottom: '2px solid #e0e0e0' }}>
+										<th style={{ padding: '0.75rem', textAlign: 'left' }}>
+											Prop
+										</th>
+										<th style={{ padding: '0.75rem', textAlign: 'left' }}>
+											Type
+										</th>
+										<th style={{ padding: '0.75rem', textAlign: 'left' }}>
+											Default
+										</th>
+										<th style={{ padding: '0.75rem', textAlign: 'left' }}>
+											Description
+										</th>
+									</tr>
+								</thead>
+								<tbody>
+									<tr style={{ borderBottom: '1px solid #e0e0e0' }}>
+										<td style={{ padding: '0.75rem' }}>
+											<code>to</code>
+										</td>
+										<td style={{ padding: '0.75rem' }}>string</td>
+										<td style={{ padding: '0.75rem' }}>-</td>
+										<td style={{ padding: '0.75rem' }}>
+											Destination URL (required)
+										</td>
+									</tr>
+									<tr
+										style={{
+											borderBottom: '1px solid #e0e0e0',
+											background: '#f0f8ff',
+										}}
+									>
+										<td style={{ padding: '0.75rem' }}>
+											<code>fragment</code>
+										</td>
+										<td style={{ padding: '0.75rem' }}>string</td>
+										<td style={{ padding: '0.75rem' }}>undefined</td>
+										<td style={{ padding: '0.75rem' }}>
+											<strong>
+												Fragment identifier to scroll to after navigation
+											</strong>
+										</td>
+									</tr>
+									<tr style={{ borderBottom: '1px solid #e0e0e0' }}>
+										<td style={{ padding: '0.75rem' }}>
+											<code>replace</code>
+										</td>
+										<td style={{ padding: '0.75rem' }}>boolean</td>
+										<td style={{ padding: '0.75rem' }}>false</td>
+										<td style={{ padding: '0.75rem' }}>
+											Replace history entry instead of push
+										</td>
+									</tr>
+									<tr style={{ borderBottom: '1px solid #e0e0e0' }}>
+										<td style={{ padding: '0.75rem' }}>
+											<code>prefetch</code>
+										</td>
+										<td style={{ padding: '0.75rem' }}>boolean</td>
+										<td style={{ padding: '0.75rem' }}>true</td>
+										<td style={{ padding: '0.75rem' }}>
+											Enable prefetching on hover/focus
+										</td>
+									</tr>
+									<tr>
+										<td style={{ padding: '0.75rem' }}>
+											<code>state</code>
+										</td>
+										<td style={{ padding: '0.75rem' }}>any</td>
+										<td style={{ padding: '0.75rem' }}>undefined</td>
+										<td style={{ padding: '0.75rem' }}>
+											State to pass to the route
+										</td>
+									</tr>
+								</tbody>
+							</table>
+							<p style={{ marginTop: '1.5rem' }}>
+								All standard HTML anchor element attributes are also supported
+								(className, style, aria-*, etc.).
+							</p>
+						</>
+					}
+				/>
+
+				<Section
+					id='examples'
+					title='🎯 Examples'
+					content={
+						<>
+							<h3>Example 1: Table of Contents</h3>
+							<p>
+								Create a table of contents that allows users to jump to
+								different sections of a page:
+							</p>
+							<code
+								style={{
+									display: 'block',
+									background: '#f5f5f5',
+									padding: '1rem',
+									borderRadius: '4px',
+									marginTop: '1rem',
+									whiteSpace: 'pre',
+									overflow: 'auto',
+								}}
+							>
+								{`<nav>
+  <Link to="/docs" fragment="intro">Introduction</Link>
+  <Link to="/docs" fragment="setup">Setup</Link>
+  <Link to="/docs" fragment="advanced">Advanced</Link>
+</nav>
+
+<section id="intro">...</section>
+<section id="setup">...</section>
+<section id="advanced">...</section>`}
+							</code>
+
+							<h3 style={{ marginTop: '2rem' }}>
+								Example 2: Cross-Page Navigation
+							</h3>
+							<p>Navigate to a specific section on a different page:</p>
+							<code
+								style={{
+									display: 'block',
+									background: '#f5f5f5',
+									padding: '1rem',
+									borderRadius: '4px',
+									marginTop: '1rem',
+									whiteSpace: 'pre',
+									overflow: 'auto',
+								}}
+							>
+								{`// From home page to a specific section in docs
+<Link to="/docs" fragment="installation">
+  View Installation Guide
+</Link>`}
+							</code>
+
+							<h3 style={{ marginTop: '2rem' }}>Example 3: Blog Post Links</h3>
+							<p>Link to specific sections within blog posts:</p>
+							<code
+								style={{
+									display: 'block',
+									background: '#f5f5f5',
+									padding: '1rem',
+									borderRadius: '4px',
+									marginTop: '1rem',
+									whiteSpace: 'pre',
+									overflow: 'auto',
+								}}
+							>
+								{`<Link to="/blog/my-post" fragment="conclusion">
+  Skip to Conclusion
+</Link>`}
+							</code>
+
+							<h3 style={{ marginTop: '2rem' }}>
+								Example 4: Sticky Header Compatibility
+							</h3>
+							<p>
+								Use <code>scroll-margin-top</code> CSS to account for sticky
+								headers:
+							</p>
+							<code
+								style={{
+									display: 'block',
+									background: '#f5f5f5',
+									padding: '1rem',
+									borderRadius: '4px',
+									marginTop: '1rem',
+									whiteSpace: 'pre',
+									overflow: 'auto',
+								}}
+							>
+								{`section {
+  scroll-margin-top: 80px; /* Height of sticky header */
+}`}
+							</code>
+						</>
+					}
+				/>
+
+				<Section
+					id='faq'
+					title='❓ FAQ'
+					content={
+						<>
+							<h3>How does fragment scrolling work?</h3>
+							<p>
+								When you click a Link with a <code>fragment</code> prop, the
+								component:
+							</p>
+							<ol>
+								<li>
+									Navigates to the target URL with the fragment in the hash
+								</li>
+								<li>Waits for the route component to render</li>
+								<li>
+									Searches for an element with an ID matching the fragment
+								</li>
+								<li>
+									Scrolls smoothly to that element using{' '}
+									<code>scrollIntoView</code>
+								</li>
+								<li>
+									Retries up to 10 times (500ms total) if the element isn't
+									found immediately
+								</li>
+							</ol>
+
+							<h3 style={{ marginTop: '1.5rem' }}>Does it work with SSR?</h3>
+							<p>
+								Yes! The fragment is added to the href attribute, so it works
+								even with JavaScript disabled. When JavaScript is enabled, you
+								get smooth scrolling behavior.
+							</p>
+
+							<h3 style={{ marginTop: '1.5rem' }}>
+								Can I combine it with other Link props?
+							</h3>
+							<p>
+								Absolutely! The <code>fragment</code> prop works seamlessly with
+								all other Link props like <code>replace</code>,{' '}
+								<code>state</code>, and <code>prefetch</code>.
+							</p>
+
+							<h3 style={{ marginTop: '1.5rem' }}>
+								What about browser back/forward?
+							</h3>
+							<p>
+								Fragment navigation fully supports browser history. When users
+								navigate back/forward, the page will scroll to the appropriate
+								fragment automatically.
+							</p>
+
+							<h3 style={{ marginTop: '1.5rem' }}>
+								Does it work with view transitions?
+							</h3>
+							<p>
+								Yes! The fragment scrolling is coordinated with React's view
+								transitions, so animations complete before scrolling occurs.
+							</p>
+						</>
+					}
+				/>
+
+				{/* Bottom Navigation */}
+				<div
+					style={{
+						marginTop: '4rem',
+						padding: '2rem',
+						background: '#fff',
+						border: '1px solid #e0e0e0',
+						borderRadius: '8px',
+						textAlign: 'center',
+					}}
+				>
+					<h3>Try it out!</h3>
+					<p style={{ marginBottom: '1.5rem' }}>
+						Use the table of contents at the top to test the fragment
+						navigation, or click below to jump to specific sections:
+					</p>
+					<div
+						style={{
+							display: 'flex',
+							gap: '1rem',
+							justifyContent: 'center',
+							flexWrap: 'wrap',
+						}}
+					>
+						<Link
+							to='/docs'
+							fragment='getting-started'
+							style={{
+								padding: '0.75rem 1.5rem',
+								background: '#0066cc',
+								color: '#fff',
+								textDecoration: 'none',
+								borderRadius: '4px',
+							}}
+						>
+							↑ Back to Top
+						</Link>
+						<Link
+							to='/'
+							style={{
+								padding: '0.75rem 1.5rem',
+								background: '#666',
+								color: '#fff',
+								textDecoration: 'none',
+								borderRadius: '4px',
+							}}
+						>
+							← Back to Home
+						</Link>
+						<Link
+							to='/blog'
+							style={{
+								padding: '0.75rem 1.5rem',
+								background: '#28a745',
+								color: '#fff',
+								textDecoration: 'none',
+								borderRadius: '4px',
+							}}
+						>
+							View Blog →
+						</Link>
+						<Link
+							to='/client'
+							style={{
+								padding: '0.75rem 1.5rem',
+								background: '#6610f2',
+								color: '#fff',
+								textDecoration: 'none',
+								borderRadius: '4px',
+							}}
+						>
+							ClientOnly Demo →
+						</Link>
+					</div>
+				</div>
+			</main>
+		</div>
+	);
+}
+
+// Helper component for sections
+function Section({
+	id,
+	title,
+	content,
+}: {
+	id: string;
+	title: string;
+	content: React.ReactNode;
+}) {
+	return (
+		<section
+			id={id}
+			style={{
+				background: '#fff',
+				border: '1px solid #e0e0e0',
+				borderRadius: '8px',
+				padding: '2rem',
+				marginBottom: '2rem',
+				scrollMarginTop: '80px', // Account for sticky header
+			}}
+		>
+			<h2 style={{ marginTop: 0, marginBottom: '1rem' }}>{title}</h2>
+			<div style={{ lineHeight: '1.6', color: '#333' }}>{content}</div>
+		</section>
+	);
+}
+
+export { meta };

package/_/blog/src/client/routes/index.tsx

@@ -38,6 +38,42 @@ export default function HomePage() {
 					>
 						Blog
 					</Link>
+					<Link
+						to='/docs'
+						style={{
+							padding: '0.5rem 1rem',
+							background: '#0066cc',
+							color: '#fff',
+							textDecoration: 'none',
+							borderRadius: '4px',
+						}}
+					>
+						📚 Docs (Fragment Demo)
+					</Link>
+					<Link
+						to='/client'
+						style={{
+							padding: '0.5rem 1rem',
+							background: '#28a745',
+							color: '#fff',
+							textDecoration: 'none',
+							borderRadius: '4px',
+						}}
+					>
+						🎯 ClientOnly Demo
+					</Link>
+					<Link
+						to='/markdown-demo'
+						style={{
+							padding: '0.5rem 1rem',
+							background: '#8b5cf6',
+							color: '#fff',
+							textDecoration: 'none',
+							borderRadius: '4px',
+						}}
+					>
+						📝 Markdown Routes Demo
+					</Link>
 				</nav>
 			</section>
 
@@ -56,6 +92,7 @@ export default function HomePage() {
 					<li>Server-side rendering (SSR)</li>
 					<li>Type-safe route params</li>
 					<li>Automatic route generation</li>
+					<li>Native markdown routes with syntax highlighting</li>
 				</ul>
 			</section>
 		</main>